@pierdigital/arraia-web 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,236 @@
-# Temporary Holding Version
+# @pierdigital/arraia-web
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Componentes React do **Arraia**, o design system da Pier, construídos com [vanilla-extract](https://vanilla-extract.style) (CSS gerado no build, sem runtime) e [Base UI](https://base-ui.com) (comportamento e acessibilidade). Os tokens vêm do [`@pierdigital/arraia-core`](../core/README.md).
+
+## Instalação
+
+```bash
+pnpm add @pierdigital/arraia-web @pierdigital/arraia-core
+```
+
+Carregue as vars do Arraia uma vez, na raiz do app:
+
+- **Sem styled-components:** `import '@pierdigital/arraia-core/tokens.css';`
+- **Com styled-components:** monte o `ArraiaGlobalStyles` do `@pierdigital/arraia-core/styled` (mesmo conteúdo).
+
+O app **não** precisa do plugin do vanilla-extract: cada componente sai compilado, com o JS importando o próprio CSS. Funciona em Vite e Next (App Router e Pages).
+
+## Uso
+
+Um entry por componente, em PascalCase. Não há import raiz.
+
+```tsx
+import { Button } from '@pierdigital/arraia-web/Button';
+
+<Button onClick={save}>Salvar</Button>;
+```
+
+| Entry | Componente |
+| --- | --- |
+| `@pierdigital/arraia-web/Button` | `Button` |
+| `@pierdigital/arraia-web/Spinner` | `Spinner` |
+
+## Padrão de API
+
+Vale para todos os componentes. A regra do Cursor [`arraia-web.mdc`](../../.cursor/rules/arraia-web.mdc) repete estes pontos para os agentes.
+
+1. **Um entry por componente, em PascalCase**, com named exports e sem default.
+2. **Simples x composto:** componente de um elemento é um só export (`Button`). Componente com partes é um namespace com os nomes de partes do Base UI (`Select.Root`, `Select.Trigger`, `Select.Popup`, `Select.Item`).
+3. **Estado controlado ou não, com os nomes do Base UI:** `value`/`defaultValue`/`onValueChange`, `checked`/`defaultChecked`/`onCheckedChange`, `open`/`defaultOpen`/`onOpenChange`, mais `disabled`, `required` e `name`.
+4. **Variantes só pelas props do Figma** (no Button: `variant`, `size`, `color`), via `recipe` do vanilla-extract. Os tipos saem de `RecipeVariants`, nunca escritos à mão.
+5. **API fechada: o visual do DS não se altera de fora.**
+   - Sem `className`, `style` nem `render` no componente. Os tipos não aceitam essas props, e o runtime também as descarta.
+   - Espaçamento externo só por `mt`, `mb`, `ml`, `mr`, com `'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'` (tokens de `space.between`, de 4 a 24 px). São classes geradas no build; valor arbitrário não passa.
+   - No **Button**, navegação com `asChild` e um único filho (`<a>` ou componente de link): `href`, `to` e demais props ficam no filho; o Button **clona** esse filho e funde visual/a11y nele (padrão Slot), sem recriar por `type`.
+6. **Ganchos internos:** cada parte tem `data-slot="<parte>"` (para teste e depuração, não para o app estilizar). Hover, pressed e focus saem do CSS e dos data-attributes do Base UI, nunca de props.
+7. **Ref e tipos:** `forwardRef` com `displayName` em toda parte; props exportadas como `<Componente><Parte>Props`.
+8. **CSS:** todo estilo em `@layer arraia.components`, depois de `arraia.tokens`, para o CSS global do app não brigar com o DS.
+
+### Formulários
+
+Os campos não conhecem `react-hook-form`, Formik nem outra lib. Integram por contrato: `name`, `ref` encaminhada até o elemento nativo, `value`/`onValueChange` (ou `checked`/`onCheckedChange`), `onBlur` e `invalid` para o erro.
+
+- Campos nativos (`Input`, `TextArea`) funcionam com `register()` direto.
+- Campos compostos (`Select`, `Checkbox`, `Combobox`) usam `Controller`:
+
+```tsx
+<Controller
+  control={control}
+  name="plan"
+  render={({ field, fieldState }) => (
+    <Select.Root
+      invalid={fieldState.invalid}
+      name={field.name}
+      onValueChange={field.onChange}
+      value={field.value}
+    >
+      <Select.Trigger onBlur={field.onBlur} ref={field.ref} />
+      {/* … */}
+    </Select.Root>
+  )}
+/>
+```
+
+Se esse boilerplate pesar, a integração vira um pacote à parte (por exemplo `@pierdigital/arraia-web-rhf`, com `react-hook-form` como peer), nunca dentro do `arraia-web`.
+
+## Button
+
+Segue o Figma (DO | Components · Button).
+
+| Prop | Valores | Padrão |
+| --- | --- | --- |
+| `variant` | `'contained' \| 'outlined' \| 'ghost'` | `'contained'` |
+| `size` | `'sm' \| 'md' \| 'lg'` (32 / 40 / 48 px) | `'sm'` |
+| `color` | `'pink' \| 'blue'` | `'pink'` |
+| `iconLeft`, `iconRight` | `ReactNode` (20 px em sm/md, 24 px em lg) | — |
+| `loading` | `boolean`: `Spinner` no lugar do conteúdo, fundo da variante com o botão inteiro a 40% (Processing do Figma), `aria-busy`, clique bloqueado e largura mantida | `false` |
+| `disabled`, `focusableWhenDisabled` | `boolean`: com o segundo, vira `aria-disabled` e continua na ordem do Tab | `false` |
+| `fullWidth` | `boolean` | `false` |
+| `asChild` | `true` + um filho (`<a>`, `Link`…); props de rota no filho; merge via `cloneElement` | — |
+| `mt`, `mb`, `ml`, `mr` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | — |
+
+```tsx
+<Button variant="outlined" iconLeft={<PlusIcon />}>Adicionar</Button>
+<Button aria-label="Adicionar" iconLeft={<PlusIcon />} /> {/* icon-only: aria-label obrigatório */}
+<Button loading>Salvando</Button>
+<Button asChild><a href="https://pier.digital">Site</a></Button>
+<Button asChild><NextLink href="/pedidos">Ver pedidos</NextLink></Button>
+<Button asChild><RouterLink to="/pedidos">Ver pedidos</RouterLink></Button>
+```
+
+- `type="button"` por padrão, para não submeter formulário sem querer.
+- Link com `disabled` ou `loading`: `aria-disabled`, sai da ordem do Tab e o clique é cancelado.
+- Um componente de link já estilizado (`asChild` com `styled(Link)`) traz CSS próprio. O TypeScript não impede; evite no review.
+- **Uso (guideline do Figma):** um `contained` por contexto; no máximo duas ações por grupo; na horizontal, secundário à esquerda e primário à direita; na vertical, primário em cima.
+
+**Spinner no loading:** contained usa `onColor`; outlined e ghost usam a cor do botão (`pink` ou `blue`). O tamanho acompanha o ícone: `sm` (20 px) em sm/md e `md` (24 px) em lg.
+
+**Movimento:**
+
+- Press: escala e overlay de pressed instantâneos, sem transição. A escala é `0.97`, `0.98` no `lg` e `0.99` no `fullWidth`, para o botão largo não encolher demais. Hover só com mouse (`(hover: hover) and (pointer: fine)`).
+- Entrada no `loading`: o conteúdo encolhe para `scale(0.95)` e desfoca (`blur(4px)`) em 200 ms, enquanto o spinner aparece no mesmo espaço (opacidade em 200 ms) e entra em foco mais devagar (`blur(4px)` → nítido em 300 ms, curva que começa lenta), para o desfoque ser visto.
+- Volta assimétrica: o spinner sai em 120 ms e o conteúdo reaparece em 200 ms.
+- Com `prefers-reduced-motion: reduce`: só opacidade, sem escala nem blur.
+
+As curvas e durações ficam em [`src/styles/motion.css.ts`](src/styles/motion.css.ts).
+
+## Spinner
+
+Segue o Figma (DO | Components · Spinner): track inteiro e arco fixo de um terço da volta, girando em 800 ms (1,6 s com reduced motion).
+
+| Prop | Valores | Padrão |
+| --- | --- | --- |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` (16 / 20 / 24 / 32 / 40 px) | `'md'` |
+| `color` | `'pink' \| 'blue' \| 'neutral' \| 'onColor'` | `'pink'` |
+| `label` | `string`, anunciado com `role="status"` | `'Carregando'` |
+| `mt`, `mb`, `ml`, `mr` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | — |
+
+```tsx
+<Spinner label="Buscando opções" />
+<Spinner color="onColor" size="lg" />
+```
+
+- Só para processamento real (mais de ~300 ms), nunca como decoração.
+- `onColor` vai sobre superfícies sólidas e saturadas; pink, blue e neutral, em superfícies claras.
+- Dentro de um componente que já anuncia o loading (como o Button, com `aria-busy`), use `aria-hidden`.
+
+## Desenvolvimento
+
+| Comando | O que faz |
+| --- | --- |
+| `pnpm storybook` | Storybook na porta 6011 |
+| `pnpm test` | Vitest (jsdom, Testing Library) |
+| `pnpm build` | Typecheck e build da lib: `dist/components/<Nome>/index.{js,cjs,d.ts}` e `<Nome>.css`, mais `dist/shared.css` (margens e layers) e os chunks compartilhados |
+| `pnpm lint` / `pnpm lint:fix` | Ultracite (Biome) |
+
+### Estrutura
+
+```text
+src/
+├── components/<Nome>/
+│   ├── <Nome>.tsx           # só orquestra: separa props, monta a classe, escolhe o elemento
+│   ├── <Nome>.types.ts      # props exportadas
+│   ├── <Nome>.css.ts        # recipe da raiz (vanilla-extract, build time)
+│   ├── index.ts             # entry `@pierdigital/arraia-web/<Nome>`
+│   ├── components/          # partes internas, não exportadas (ex.: ButtonContent, ButtonSpinner)
+│   │   └── <Nome><Parte>/{<Nome><Parte>.tsx, <Nome><Parte>.css.ts, __tests__/}
+│   ├── utils/{functions.ts, functions.types.ts, __tests__/}
+│   ├── __tests__/<Nome>.test.tsx
+│   └── stories/<Nome>.stories.tsx
+├── styles/
+│   ├── layers.css.ts        # ordem das layers (`arraia.tokens` / `arraia.components`)
+│   ├── layered.ts           # helper `layered(...)` (fora do `.css.ts`: VE não serializa função)
+│   ├── spacing.css.ts       # classes de `mt`/`mb`/`ml`/`mr`
+│   └── motion.css.ts        # curvas, durações e o helper `transition`
+├── utils/functions.ts       # `cx`, `spacingClassNames`, `omitBlockedProps`
+└── types.ts                 # contratos de todos os componentes: `SpacingStep`, `SpacingProps`, `BlockedProp`
+```
+
+Cada tipo fica onde está o que ele descreve:
+
+- `src/types.ts`: contrato que vale para todos os componentes. Só entra tipo usado por mais de um componente.
+- `<Nome>.types.ts`: props do componente. As públicas saem pelo `index.ts`; as internas (repassadas às partes em `components/`) ficam no mesmo arquivo, derivadas das públicas com `Pick`/`Required`, sem redeclarar campo.
+- `utils/functions.types.ts`: só parâmetros e retornos das funções de `utils/functions.ts`.
+
+Uma parte interna vira componente próprio, com entry, quando um segundo componente precisar dela ou quando ela existir como componente no Figma. Foi o caso do `Spinner`: o `ButtonSpinner` virou só a camada do crossfade e usa o `Spinner` público.
+
+### Novo componente
+
+1. Crie `src/components/<Nome>/` com a estrutura acima, sobre o primitivo do Base UI quando existir.
+2. Adicione o nome em `COMPONENTS` no [`vite.config.ts`](vite.config.ts) e o export `./<Nome>` no [`package.json`](package.json).
+3. Siga o padrão de API acima: props do Figma, API fechada, `data-slot`, estilos em `layered(...)`.
+4. No Storybook: `Playground` com `tags: ['test', 'snapshot']` + `play`. Visual novo no PR só entra de propósito (CI falha → olha o diff → `test:visual:update --linux`).
+5. Figma no mesmo look do snapshot — ver seção abaixo.
+
+### Storybook, Vis e Figma
+
+```bash
+pnpm playwright:install   # Chromium (também no postinstall)
+pnpm storybook            # 6011 — Interactions, a11y, Vis, Design
+pnpm test:storybook       # play + a11y
+pnpm test:visual          # compara; falha se o PNG não acompanhou a mudança
+```
+
+O snapshot do componente é o `Playground` (args default). No Figma, o `node-id` / `nodeId` tem que ser **desse** variant — no Button, Contained / sm / Enabled / Pink / text — não o set inteiro nem outro estado. Esse mesmo URL vai em `parameters.design` (aba Design) e em `figma-refs.json` (`fileKey` + `nodeId` + `url`). No URL do Figma o id vem com hífen (`152-1104`); no JSON e na API usa dois-pontos (`152:1104`).
+
+```json
+{
+  "Button/playground": {
+    "fileKey": "GoNNaKQ3naATm4j03SFvmK",
+    "nodeId": "152:1104",
+    "url": "https://www.figma.com/design/…?node-id=152-1104"
+  }
+}
+```
+
+Mudou o visual de propósito? Aceita o baseline **e** tenta puxar de novo o PNG do Figma (Pixel Tribunal + evidência local). Sem ref, sem URL do node ou sem `FIGMA_TOKEN`, só avisa e o Vis segue:
+
+```bash
+export FIGMA_TOKEN=figd_…   # Figma → Settings → Security → PAT, escopo file_content:read (~90 dias)
+pnpm test:visual:update --linux -- src/components/<Nome>/stories
+git add __vis__/local __vis__/linux __figma__
+git commit -m "chore(arraia-web): accept visual baselines"
+```
+
+`--linux` gera o que o CI usa (Docker amd64). `--skip-figma` pula a tentativa. Sem API, exporta o PNG no Figma e troca `__figma__/<Nome>/playground.png` no PR.
+
+Só o PNG:
+
+```bash
+pnpm figma:refs                     # tudo do figma-refs.json
+pnpm figma:refs Button/playground   # um entry
+```
+
+A aba Design abre o file no Figma (precisa de acesso). O PAT baixa o PNG versionado; o CI não chama a API.
+
+### Skills no Cursor
+
+Quem for escrever story, util ou PR neste pacote: as skills em [`.cursor/skills/`](../../../.cursor/skills/) entram sozinhas quando o pedido casa com a description. As que mais importam aqui:
+
+| Skill | Quando |
+| --- | --- |
+| [`arraia-web-stories`](../../../.cursor/skills/arraia-web-stories/SKILL.md) | `*.stories.tsx` — um conceito por story, JSDoc/`@summary` em inglês, `test`+`play` na mesma story, `!manifest` em matrix/demo, `snapshot` no Playground, Figma = variant do snapshot |
+| [`util-functions`](../../../.cursor/skills/util-functions/SKILL.md) | helpers em `**/utils/functions.ts` + testes `functions.<nome>.test.ts` |
+| [`pier-writing-pr`](../../../.cursor/skills/pier-writing-pr/SKILL.md) | abrir PR no template do monorepo, em português, falando do comportamento |
+
+A regra [`arraia-web.mdc`](../../.cursor/rules/arraia-web.mdc) continua valendo pro contrato do componente (API fechada, entries, layers).

package/package.json

@@ -1,6 +1,102 @@
 {
   "name": "@pierdigital/arraia-web",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "private": false,
+  "description": "Arraia Web — componentes React do design system da Seguradora Pier, com vanilla-extract e Base UI.",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "type": "module",
+  "exports": {
+    "./Button": {
+      "types": "./dist/components/Button/index.d.ts",
+      "source": "./src/components/Button/index.ts",
+      "import": "./dist/components/Button/index.js",
+      "require": "./dist/components/Button/index.cjs"
+    },
+    "./Spinner": {
+      "types": "./dist/components/Spinner/index.d.ts",
+      "source": "./src/components/Spinner/index.ts",
+      "import": "./dist/components/Spinner/index.js",
+      "require": "./dist/components/Spinner/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc --noEmit && vite build",
+    "build:watch": "vite build --watch",
+    "build-storybook": "storybook build",
+    "figma:refs": "node ./scripts/fetch-figma-refs.mjs",
+    "postinstall": "playwright install chromium",
+    "lint": "ultracite check",
+    "lint:fix": "ultracite fix",
+    "lint-staged": "lint-staged",
+    "playwright:install": "playwright install chromium",
+    "storybook": "storybook dev -p 6011",
+    "storybook:build": "pnpm build-storybook --quiet",
+    "storybook:dev": "pnpm storybook",
+    "storybook:move": "mv storybook-static ../../../storybook-static/arraia-web",
+    "test": "vitest run --config vitest.unit.config.ts --passWithNoTests",
+    "test:storybook": "vitest run --config vitest.storybook.config.ts",
+    "test:unit": "vitest run --config vitest.unit.config.ts --passWithNoTests",
+    "test:visual": "vitest run --config vitest.visual.config.ts",
+    "test:visual:update": "bash ./scripts/update-visual-baselines.sh",
+    "test:watch": "vitest --config vitest.unit.config.ts"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.8.0",
+    "@vanilla-extract/recipes": "^0.5.7"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "catalog:",
+    "@pierdigital/arraia-core": "workspace:*",
+    "@playwright/test": "^1.64.1",
+    "@repo/typescript-config": "workspace:*",
+    "@storybook/addon-a11y": "catalog:",
+    "@storybook/addon-designs": "catalog:",
+    "@storybook/addon-docs": "catalog:",
+    "@storybook/addon-mcp": "catalog:",
+    "@storybook/addon-vitest": "catalog:",
+    "@storybook/builder-vite": "catalog:",
+    "@storybook/react-vite": "catalog:",
+    "@testing-library/jest-dom": "catalog:",
+    "@testing-library/react": "catalog:",
+    "@testing-library/user-event": "catalog:",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
+    "@vanilla-extract/css": "catalog:",
+    "@vanilla-extract/vite-plugin": "catalog:",
+    "@vitest/browser": "5.0.5",
+    "@vitest/browser-playwright": "5.0.5",
+    "jsdom": "catalog:",
+    "playwright": "^1.64.1",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "react-router": "catalog:",
+    "storybook": "catalog:",
+    "storybook-addon-vis": "^4.4.0",
+    "typescript": "catalog:",
+    "ultracite": "catalog:",
+    "vite": "catalog:",
+    "vite-plugin-dts": "catalog:",
+    "vite-plugin-lib-inject-css": "^2.2.2",
+    "vite-tsconfig-paths": "catalog:",
+    "vitest": "catalog:"
+  },
+  "peerDependencies": {
+    "@pierdigital/arraia-core": "workspace:^",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "packageManager": "pnpm@10.33.4",
+  "engines": {
+    "node": "24.x"
+  },
+  "engineStrict": true,
+  "publishConfig": {
+    "access": "public"
+  }
+}