@mozgbrasil/node-web-components

Biblioteca pública de Web Components da MOZG, com Storybook como vitrine oficial e contrato de release auditável.

Requisitos

• Node.js >=20.0.0 para desenvolvimento local, com validação da matriz CI em Node 24.14.1
• npm >=10.0.0
• navegador moderno para inspecionar o Storybook local em http://localhost:6006

Ver os componentes

• Storybook: https://mozgbrasil.github.io/node-web-components-storybook/?path=/docs/catalog-explorer--docs
• npm: https://www.npmjs.com/package/@mozgbrasil/node-web-components
• suporte: https://mozg.com.br/contato

O Storybook é a forma recomendada para navegar, testar presets e validar quais componentes fazem sentido no seu projeto.

Instalação

Para consumir o pacote publicado:

npm install @mozgbrasil/node-web-components

Para contribuir no workspace privado:

npm install

O prepare instala Husky apenas quando este projeto e o root Git local, evitando ruido em execucoes do workspace aninhado dentro do monorepo privado.

Uso rápido

import '@mozgbrasil/node-web-components';

Os componentes públicos mais úteis hoje para superfícies institucionais, páginas de produto e experiências PWA são:

• mozg-web-share: abre o compartilhamento nativo quando disponível e faz fallback para cópia do link.
• mozg-a2hs: oferece instalação do site ou app quando o dispositivo suporta a experiência PWA.
• mozg-monitor-connectivity: sinaliza conectividade atual do navegador com evento público para o host.
• mozg-fullscreen: alterna tela cheia com rótulos configuráveis e evento observável.
• mozg-service-worker: registra o cache offline com pill opcional de status e sinal público de registro.
• mozg-parking-lottery: executa sorteio auditável de vagas para empreendimentos imobiliários com cenários prontos, múltiplos modelos e fila de espera.

<mozg-web-share
  label="Compartilhar"
  share-title="MOZG"
  share-text="Veja esta página."
  share-url="https://mozg.com.br/"
></mozg-web-share>

<mozg-a2hs label="Instalar app"></mozg-a2hs>

<mozg-monitor-connectivity
  show-indicator
  label-online="Online"
  label-offline="Offline"
></mozg-monitor-connectivity>

<mozg-fullscreen
  label-enter="Abrir em tela cheia"
  label-exit="Sair da tela cheia"
></mozg-fullscreen>

<mozg-service-worker
  src="/service-worker.js"
  scope="/"
  show-indicator
  label-ready="Cache ativo"
></mozg-service-worker>

<mozg-parking-lottery
  scenario-preset="torre-panorama-20"
  model="balanced"
  seed="20260409"
  label-reroll="Reprocessar sorteio"
></mozg-parking-lottery>

Eventos úteis:

• mozg-monitor-connectivity emite connectivitychange com { online: boolean }.
• mozg-web-share funciona bem em páginas públicas, páginas de produto, portfólios e páginas institucionais.
• mozg-fullscreen emite fullscreenchange com { active: boolean }.
• mozg-service-worker emite swstatuschange com { status, scope, src }.
• mozg-parking-lottery emite parkinglotterydraw com request_id, generated_at, scenario_id, model, seed e zone_summaries.

Sorteio de vagas

O componente mozg-parking-lottery foi desenhado para administradoras, incorporadoras e síndicos que precisam publicar sorteios de vagas com replay por seed e leitura visual por andar.

Modelos canônicos incluídos:

• balanced: distribui as unidades equilibrando ocupação por zona.
• proximity: cria viés de proximidade vertical entre apartamento e zona.
• cluster: agrupa por conjuntos de andares e colunas.
• rotation: faz rodízio determinístico com sequência reproduzível.

Cenários prontos incluídos:

• torre-panorama-20: 20 andares, apartamentos 11, 12, 13, 14 no primeiro andar e inventário com 17 vagas no térreo, 24 no subsolo 1 e 34 no subsolo 2.
• torre-boutique-8: torre compacta para validações rápidas.
• residencial-jardins-16: cenário denso com cinco unidades por pavimento.

Também é possível injetar um cenário customizado via property scenarioData quando o host quiser controlar apartamentos, pavimentos e zonas programaticamente.

Desenvolvimento

npm run storybook
bash scripts/build.sh all

CI

• Entrada principal node-web-components: format, lint, test e build habilitados com gate local recomendado em bash scripts/build.sh all
• Entrada auxiliar node-web-components-build-storybook: format, lint e build habilitados, test desabilitado, com build canonico em npm run release:check && npm run build:storybook
• Para repetir a esteira principal sem reinstalar dependencias, use bash scripts/build.sh check-only

Superfície auditável

• npm run release:manifest: gera o manifesto público de release.
• npm run surface:json: exporta a superfície operacional em JSON.
• npm run surface:ready: calcula readiness local.
• npm run surface:links:ndjson: exporta links públicos em NDJSON.
• GET /api/catalog: expõe o catálogo público de componentes com filtros previsíveis.
• GET /api/catalog/:id: retorna o detalhe auditável de um componente específico.
• operations.api_version: 2026.03
• operations.audit_headers: x-request-id, x-request-timestamp, x-request-path, x-request-method, x-response-status, x-api-version, x-response-timestamp, access-control-expose-headers
• supported_filters: category, host, section, search, limit, status
• catalog.supported_filters: framework, group, status, search, limit

Os endpoints Nitro de workflow também expõem envelope operacional previsível no payload e nos headers, incluindo x-request-id, x-request-timestamp, x-request-path, x-request-method, x-response-status, x-api-version, x-response-timestamp e access-control-expose-headers.

Exemplos rápidos:

• GET /api/catalog?framework=vanilla&group=mdn&search=share&limit=5
• GET /api/catalog/web-share

Publicacao

• Storybook publicado em: https://mozgbrasil.github.io/node-web-components-storybook/?path=/docs/catalog-explorer--docs
• pacote publicado em: https://www.npmjs.com/package/@mozgbrasil/node-web-components
• o gate de release local continua sendo bash scripts/build.sh all seguido de npm run release:check

Suporte

• site: https://mozg.com.br
• contato: https://mozg.com.br/contato
• GitHub Sponsors: https://github.com/sponsors/mozgbrasil