npm package: @mozgbrasil/node-web-components
Description: Uma coleção de Web Components modernos, reutilizáveis, auditáveis, escaláveis e prontos para múltiplos frameworks
Author: Mozg Brasil
Latest version: 1.0.58

# @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:

```bash
npm install @mozgbrasil/node-web-components
```

Para contribuir no workspace privado:

```bash
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

```ts
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.

```html
<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

```bash
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>