@apollion-dsi/core 4.1.0 → 4.3.0

package/CHANGELOG.md

@@ -0,0 +1,1357 @@
+# @apollion-dsi/core
+
+## 4.3.0
+
+### Minor Changes
+
+- ADR-010: `txtOn` por contraste de luminância (`getContrastColor`) — on-color **dark-mode-stable** para superfícies sólidas (marca + feedback/action + interface.function). Corrige o "escuro-no-escuro" em fundos de marca fixos (`main`) no dark mode: o texto agora deriva da luminância do próprio fundo, não do par `baseLight`/`baseDark` que o dark mode troca.
+
+  Novos tokens Foundation (aditivos): `bg.brand`, `text.onMain`, `text.onOpposite`, `text.onComplementary`.
+
+  Novo helper `readableColor(color, background, minRatio?)` (export de `themes/colors`) — ajusta a luminância OKLch de uma cor de acento até passar o piso WCAG contra um fundo, **preservando hue/croma** (diferente de `getContrastColor`). Aplicado no elemento `Link`: links de marca agora ficam legíveis sobre fundos escuros (dark mode) sem perder a cor.
+
+## 4.2.0
+
+### Minor Changes
+
+- feat(form): `Checkbox`/`Radio` string labels render with DS typography; new `labelProps`
+
+  String labels now render through the DS `BaseText` styles instead of raw text,
+  and the new optional `labelProps` lets consumers override the label typography
+  (`fontSize`, `color`, `fontWeight`, …). `ReactNode` labels are rendered as-is,
+  unchanged.
+
+- feat(themes): native dark mode in `ApollionProvider` + `useApollionTheme`
+  - `ApollionProvider` now implements the mode API its types already advertised:
+    the `lightTheme`/`darkTheme` pair, controlled `themeMode` +
+    `onThemeModeChange`, `useSystemPreference` (watches `prefers-color-scheme`,
+    SSR-safe) and `toggleTheme` via the new `useApollionTheme()` hook. The single
+    `theme` prop keeps working unchanged.
+  - Dark-mode contrast fixes: the `Tabs` header divider now uses a mode-symmetric
+    gray (`grayscale.30`), and `InputSelect` no longer hardcodes white — the
+    control and menu follow the same surface tokens as the other inputs
+    (`grayscale.0`/`baseLight`).
+  - Vendor isolation now also blocks `import type` of vendored libs, enforced
+    via `@typescript-eslint/no-restricted-imports` in the package lint config.
+  - Internal: the `entities/` folder was dissolved — the SSR-safe window helpers
+    (`$window`, `$documentBody`, `canuseDom`) moved into `utils` (still exported
+    via `@apollion-dsi/core/utils`); the unused `debounce`/`timer` entities were
+    removed (never part of the public API).
+  - Storybook: stories renamed to `<Component>.story.tsx` and new `Flex`/`Grid`
+    stories (not part of the published bundle).
+
+### Patch Changes
+
+- 3321f56: fix(core): correct three DataTable/Calendar visual bugs
+  - **DataTable EmptyState** now centers horizontally. The 80%-wide empty block
+    was pinned to the left because the flex container (a `BaseContainer`, which
+    defaults to `flex-direction: column`) lacked `align-items: center` on its
+    cross axis.
+  - **DataTable pagination** no longer renders an empty scroll region when the
+    page size grows. The virtualizer now targets the element that actually
+    scrolls — `CustomScroll`'s inner node, exposed via a new optional
+    `scrollableRef` prop — instead of the non-scrolling outer container, so
+    `getScrollElement` reads the correct `scrollTop`/`clientHeight` and receives
+    scroll events.
+  - **Calendar** renders the day number on a day that is simultaneously today and
+    selected. A CSS specificity collision painted the number in `primary.base`
+    over the selected `primary.base` background (invisible); the today rule now
+    excludes selected days so the selected contrast color wins.
+
+- b3cf796: fix(core): seed type-aware empty defaults in `Form` so fields mount controlled
+
+  `Form` passed `defaultValues: { ...initialValues }` to `useForm`, so a field
+  without an `initialValues` entry mounted with `value={undefined}` (uncontrolled)
+  and flipped to controlled on the first change — triggering React's
+  "changing an uncontrolled input to be controlled" warning. The new
+  `buildDefaultValues` helper seeds every field with a type-aware empty value
+  (`false` for checkbox/radio, `''` otherwise — same convention as `Field` reset),
+  with `initialValues` taking precedence. No public API change.
+
+## 4.1.0
+
+### Minor Changes
+
+- d18737c: Add `DescriptionList` + widen `Field` hint props to `ReactNode` — closes two open "Gaps Apollion" tracked by DEX-Aggregator.
+  - **`DescriptionList`** (`@apollion-dsi/core/data-display/description-list`) — new `data-display` component: semantic key/value list (`<dl>`/`<dt>`/`<dd>`) under an optional title, `direction="row" | "column"`. Both `key` and `value` accept `ReactNode`. Absorbs the recurring "key/value card under a title" pattern that clients reimplemented locally (DEX-Aggregator `InfoCard`, ~210 LOC duplicated across 7 screens). Full doc surface (TSDoc + Storybook + README.mdx + README.AI.md) + unit tests.
+  - **`Field` hint props accept `ReactNode`.** `hintText`, `hintSuccessText` and `hintErrorText` widen from `string` to `React.ReactNode` (backward-compatible — `string ⊂ ReactNode`). Unblocks inline hint affordances — an action button ("use max"), a daily-limit `Text` — that previously had to render as a sibling outside `Field`, blocking deletion of the consumer wrapper (DEX-Aggregator `InputTextAdapter`).
+
+  No breaking change. `@apollion-dsi/tokens` bumps in lockstep (`.changeset/config.json#fixed`).
+
+- 063e0e9: Align `@apollion-dsi/tokens` DTCG output with the Design Tokens Format Module 2025.10.
+  - **Structured values:** `color` `$value` is now an OKLch object `{ colorSpace, components, hex, alpha? }` and `dimension` is `{ value, unit }` (was bare hex / length strings).
+  - **Typed IR:** a single intermediate representation (`src/ir.ts`) drives the JSON/CSS/TS renderers as pure projections.
+  - **Reference graph:** JSON emits a `color` primitives layer (structural SSOT) and foundation `bg`/`text` colours reference it via DTCG aliases (`{color.primary.base}`), with inline fallback when a resolved value diverges (e.g. surface inversion).
+  - **Composite tokens:** `border` (dimension / strokeStyle), `typography` (fontFamily / fontWeight / number + dimension) and `shadow` (DTCG shadow composite) now ship; values DTCG cannot model (em `letterSpacing`, `textTransform`, `fontStyle`, `100%` radius) travel in `$extensions` under `com.apollion.*`.
+
+  `@apollion-dsi/core` now exports the `themes/{border,depth,font}` subpaths so tokens consumes them as the single source of truth.
+
+  CSS/TS outputs for the existing `bg`/`text`/`spacing` layers are byte-identical; JSON is the spec-interop surface.
+
+## 4.0.0
+
+### Major Changes
+
+- bd7d6cb: # v4.0.0 — OKLch + Dimension + Token Split
+
+  The v4 epic per [ADR-006](../packages/core/docs/adr/ADR-006-v4-oklch-dimension-token-split.md) + [PRD-002](../packages/core/docs/prd/PRD-002-v4-epic-execution.md). DS-from-scratch (Q-G grilling 2026-05-24); no consumer migration. Greenfield adoption via [MIGRATION-v4.md](../packages/core/docs/migration/MIGRATION-v4.md).
+
+  ## Breaking — `@apollion-dsi/core@4.0.0`
+  - **Root barrel removed.** `import { Button } from '@apollion-dsi/core'` no longer works. Use granular subpaths (`@apollion-dsi/core/elements/button`). ESLint rule flips warn → error. ADR-001 Slice 6 finalized here. ADR-006 §3.7 E7.
+  - **OKLch palette derivation.** All `mount*Colors` helpers + `getOppositeColor` migrated from `color@5` RGB lerp to `culori@4` OKLch lerp. Validated by `spike/culori-oklch-lerp-parity` (0 unexpected regressions; greyscale 19× more uniform in OKLAB L). ADR-006 §2 B1 + §6 S2.
+  - **`defaultInputColors.opposite` token value changed.** OKLch hue rotation differs from HSL rotation (the OKLch is the perceptually correct opposite). Audit `theme.colors.opposite.*` consumers.
+  - **Dimension axis added.** `<ApollionProvider dimension="compact|normal|spacious">` is a new prop; default `normal` preserves v3.x spacing byte-exact. ADR-006 §6 S3.
+  - **`vendors/Color` eliminated.** Internal `color@5` vendor deleted (zero call-sites after S6 migration). `color` + `@types/color` removed from `package.json#dependencies`. WCAG functions migrated to `culori.wcagContrast` + `culori.wcagLuminance` (100% bit-exact parity per `spike/culori-wcag-parity`).
+  - **`invertForSurface(theme, surface, mode)` 3-arg signature.** `mode` is additive optional — existing 2-arg calls continue to work; `mode` is a placeholder for future PRD-003 mode-aware inversion. ADR-006 §6 S6.
+
+  ## Minor — `@apollion-dsi/eslint-config`
+  - `culori` + `zod` added to `VENDORED_V4_LIBS` — must import via `vendors/Culori|Zod`.
+  - `color` removed from `VENDORED_T2_LIBS` (eliminated).
+  - `no-restricted-imports` for `'@apollion-dsi/core'` root: `warn` → `error` (per v4 barrel removal above).
+
+  ## Major — `@apollion-dsi/tokens@4.0.0` (first release)
+
+  New package — framework-agnostic design tokens consumed via `runtime/v1` versioned API + `apollion-tokens build` CLI.
+  - **Strangler Fig builders** duplicated from core (`colors.ts`, `spacing.ts`); Foundation + Surface re-exported. Parity enforced by `__tests__/parity.test.ts`. ADR-006 §3.1 + §6 S4.
+  - **Atomic + idempotent build CLI.** `apollion-tokens build [--check] [--verbose] --config <path> [--out <dir>]`. Emits `dist/{css,json,ts}/*` + `dist/manifest.json` with sha256 audit trail. Rerun byte-identical. `--check` mode for CI gate. ADR-006 §3.5 + §6 S5.
+  - **DTCG-compliant JSON output** (tech-radar R1).
+  - **`as const` TypeScript output** (tech-radar R4).
+  - **CSS `@property` declarations** (tech-radar R3) + custom properties `--apollion-{layer}-{role}-{variant}`.
+  - **Sandboxed `apollion.config.mjs` loader** (`node:vm` + zod schema) — threat-model T2+E1 mitigation. ADR-006 §3.8 B3 + §6 S6.
+  - **Lockstep version** with `@apollion-dsi/core` via `.changeset/config.json#fixed`.
+
+  ## Minor — `@apollion-dsi/scripts`
+  - `codemods/v4-migrate.mjs` — one-way codemod (Q-G10: no `--revert`; DEX/Jovian/Fanaticofc don't consume v3.x, no legacy to revert). Transforms `invertForSurface` to 3-arg, flags `createTheme` for manual hoist to `apollion.config.mjs`. Transcript JSONL audit log.
+  - `verify-no-install-scripts.js` — supply-chain hardening; blocks `preinstall`/`install`/`postinstall` in `@apollion-dsi/*` workspaces (threat-model E2 mitigation).
+
+  ## Spike validation (preserved local, NOT merged to main)
+  - `spike/culori-wcag-parity` — 100.0000% bit-exact culori vs color@5 (262 measurements / 10 palettes). `vendors/Color` elimination LOCKED.
+  - `spike/culori-oklch-lerp-parity` — 0 unexpected regressions in 68 deltas; greyscale ramp 19× more uniform in OKLAB L. DECISION ✅ PROCEED.
+
+- 879eedd: feat(core)!: ADR-007 S6 — hard cut Formik+Yup vendors (v4.0.0)
+
+  Completa a migração ADR-007 com a remoção definitiva do legacy stack
+  Formik+Yup. Vendors removidos, deps dropped, ESLint VENDORED_LIBS limpo.
+
+  **Removidos:**
+  - `packages/core/src/vendors/Formik/` — 4 arquivos (component.ts, interface.ts, index.ts, README.md).
+  - `packages/core/src/vendors/Yup/` — 4 arquivos (mesmo padrão).
+  - `formik@2.4.9` removido de `packages/core/package.json#dependencies`.
+  - `yup@1.7.1` removido de `packages/core/package.json#dependencies`.
+  - `formik` + `yup` removidos de `packages/eslint-config/index.js` `VENDORED_T1_FORM_LIBS`.
+  - `yarn.lock` shrunk em ~932 KiB (-9 transitive packages).
+
+  **Estado pós-S6:**
+  - 0 imports diretos de `formik`/`yup` em `packages/core/src/**` e `website/src/**`.
+  - `corepack yarn workspace @apollion-dsi/core run check-types`: ✅
+  - `corepack yarn workspace @apollion-dsi/core run lint`: ✅
+  - `corepack yarn workspace @apollion-dsi/core run validate:tests`: ✅ 317 passed (1 skipped pre-existente), 59 snapshots OK.
+  - `corepack yarn workspace @apollion-dsi/website run build`: ✅
+  - Bundle form-basic/form-form/form-dynamic: 422 kB First Load JS (unchanged vs S3 — Formik/Yup já eram dead code desde S3).
+
+  **Status ADR-007:** ✅ Implemented. Todos S0-S6 mergeados.
+
+  **Achado de sessão:** ADR-006 v4 epic já estava ✅ Implemented (2026-05-25,
+  commit `4188501`). O "gate v4.0.0" para S6 era apenas pendência de
+  execução, não bloqueio externo. S6 executado imediatamente.
+
+  **Trabalho restante (fora do escopo ADR-007):**
+  1. `corepack yarn version` — consolida changesets queued, bumpa
+     `@apollion-dsi/core@3.0.0 → 4.0.0` (lockstep com `@apollion-dsi/tokens`).
+  2. `corepack yarn release` — npm publish com `--provenance` (ADR-006 §AI-7).
+  3. Visual regression 3-browser full pass na CI antes do release.
+
+  **Breaking changes consumer-facing (já documentados em MIGRATION-v4.md §1-§8):**
+  - `validation` prop em `<Form fields>` agora aceita `ZodTypeAny` (era Yup).
+  - `validateOnChange`/`validateOnBlur` booleans → `mode?: Mode` enum.
+  - `onError(errors)` recebe `FieldErrors` (era `FormikErrors`).
+  - `handleSubmit(values, methods)` recebe `UseFormReturn` no 2º arg (era `FormikHelpers`).
+  - `FormRef` type aponta para `UseFormReturn<any>` (era `FormikProps<any>`).
+  - `formik` + `yup` removidos de transitive deps — consumers que importavam diretamente do core via barrel devem trocar para `import { z } from 'zod'` / `import { useForm } from 'react-hook-form'` direto.
+
+  Ver `packages/core/docs/adr/ADR-007-form-stack-rhf-zod.md` §6 Slice 6 +
+  `packages/core/MIGRATION-v4.md` para guia consumer-side completo.
+
+- e2abc9c: feat(core)!: ADR-008 — router-agnostic polymorphic Link (v4.0.0)
+
+  `<Link>` deixa de depender de `react-router-dom`. Refactor para polymorphic
+  component via prop `as` — default `<a>` nativo; consumer passa
+  `as={NextLink}`/`as={RouterLink}`/`as={RemixLink}` para SPA navigation.
+
+  **Removidos:**
+  - `packages/core/src/vendors/ReactRouterDom/` (4 files).
+  - `react-router-dom@7.15.0` de `packages/core/package.json#dependencies`.
+  - `react-router-dom` de `packages/eslint-config/index.js` `VENDORED_T1_DATA_LIBS`.
+  - `<MemoryRouter>` wrapper de `website/pages/_app.jsx` (era só para satisfazer Link RRD-based).
+  - Yarn lockfile shrunk **−4.17 MiB** (−4 packages: `react-router-dom`, `react-router`, `cookie`, `set-cookie-parser`).
+
+  **Refatorados:**
+  - `elements/Link/Link.tsx` — single render path; `effectiveAs = isExternal ? 'a' : as`; dropped `getRoute()` helper.
+  - `elements/Link/Link.style.ts` — `LinkStyle` + `LinkButtonStyle` base em `baseStyled.a`; styled-components forward `as` prop. Eliminados styles redundantes (`ExternalLinkStyle`, `ExternalLinkButtonStyle`).
+  - `elements/Link/Link.interface.ts` — drop `Partial<LinkProps>`; add `as?: React.ElementType` + `to?: any`.
+  - `elements/Link/Link.test.tsx` — drop `<Router>` wrapper + `jest.mock('react-router-dom')`.
+  - `elements/Link/story.tsx` — drop `MemoryRouter` decorator.
+  - `elements/List/story.tsx` — drop `MemoryRouter` decorator (era scaffolding-only).
+  - `elements/List/List.tsx` — `<Link to={item.to}>` → `<Link href={item.to}>`.
+  - `elements/Link/README.mdx` + `README.AI.md` — rewrite com pattern `as={NextLink}` / `as={RouterLink}`.
+  - `hooks/useUnload/README.mdx` — remove exemplo legacy com `<Prompt>` (Prompt nem existe em react-router v6+).
+
+  **Bundle delta (Next.js First Load JS, website pós-build):**
+
+  | Page                |    Pre |   Post |              Δ |
+  | ------------------- | -----: | -----: | -------------: |
+  | `form-basic`        | 422 kB | 410 kB | −12 kB / −2.8% |
+  | `form-form`         | 422 kB | 410 kB | −12 kB / −2.8% |
+  | `form-input-select` | 411 kB | 399 kB | −12 kB / −2.9% |
+  | Shared chunks       | 211 kB | 199 kB | −12 kB / −5.7% |
+
+  **12 kB real savings** em todas pages do website — `react-router-dom` saía amortizado em shared chunks. Aplica também a consumers externos que não usavam RRD (Next.js, Remix). Contraste com ADR-007 (Form migration) que ficou em +1.2%.
+
+  **Breaking change consumer-facing** (documentado em MIGRATION-v4.md §ADR-008):
+  - `<Link to="/x">` sem `as` vira no-op silencioso. Migrar para `<Link as={RouterLink} to="/x">` ou `<Link href="/x">`.
+  - `<MemoryRouter>` wrappers que só existiam para satisfazer DS Link podem ser removidos.
+
+  **Validation:**
+  - check-types ✅ / lint ✅ / 317 tests ✅ / 59 snapshots ✅ / core build ✅ / website build ✅
+  - 0 imports de `react-router-dom` em `packages/core/src/**` e `website/src/**` (only docs/JSDoc examples remain — legítimos).
+
+  ROADMAP entry "Router-agnostic Link" → ✅ COMPLETE. ADR-008 Status → ✅ Implemented.
+
+  Ver `packages/core/docs/adr/ADR-008-router-agnostic-link.md` para análise completa + `packages/core/MIGRATION-v4.md` §ADR-008 para guia consumer-side.
+
+### Minor Changes
+
+- 32f7a1d: feat(themes): ADR-002 Slice 2 — Semantic alias layer
+
+  Adds `theme.semantic` — the intent-named token layer that mirrors Aplica DS
+  taxonomy (`semantic.<category>.<group>.<state>.<property>`) and derives
+  from the existing structural theme without breaking it.
+
+  Public API:
+  - `theme.semantic.color.feedback.{success|danger|warning|information}.{bg|txtOn|border}`
+  - `theme.semantic.color.interface.function.{primary|secondary|tertiary}.normal.{bg|txtOn}`
+  - `theme.semantic.color.brand.{first|second|third}.default.{surface|txtOn}`
+  - `theme.semantic.dimension.spacing.{zero..giant}` (pre-resolved CSS strings)
+  - `createSemantic(input)` helper — pure, idempotent, no side-effects
+  - Granular subpath import: `@apollion-dsi/core/themes/semantic`
+
+  Backward-compatible: `theme.colors.*`, `theme.spacing(...)` and all other
+  structural tokens remain untouched. Components migrate at their own pace.
+
+  Also fixes a latent regression in `scripts/generate-exports.js` that would
+  overwrite `package.json#sideEffects` (currently `false` since the v3.0.0
+  side-effects-free refactor) back to the legacy allow-list.
+
+  See `packages/core/docs/adr/ADR-002-layered-theme-aliases-and-surface.md`
+  §3, §6 (Slice 2), §9 (grill-with-docs validations).
+
+- 2dadba5: feat(themes): ADR-002 Slice 3 — Foundation alias layer
+
+  Adds `theme.foundation` — ergonomic short aliases over Semantic, designed
+  as the **default layer for product code** (DEX, Jovian, Fanaticofc).
+
+  Public API:
+  - `theme.foundation.bg.{primary, secondary, tertiary, success, danger, warning, info}`
+  - `theme.foundation.text.{onPrimary, onSecondary, onTertiary, onSuccess, onDanger, onWarning, onInfo}`
+  - `theme.foundation.spacing.{xs, sm, md, lg, xl, xxl}` (pre-resolved CSS strings)
+  - `createFoundation(semantic)` helper — pure, idempotent (ADR-002 §9 contract)
+  - Subpath import: `@apollion-dsi/core/themes/foundation`
+  - Cheatsheet: `packages/core/src/themes/Foundation/README.md`
+
+  Layer-of-choice rule (CONCEPTS.md §3):
+  - Product code → Foundation
+  - Core components → Semantic
+  - Engine internals → Structural (unchanged)
+
+  Backward-compatible: no breaking change. Existing `theme.colors.*`,
+  `theme.spacing(...)`, `theme.semantic.*` remain intact.
+
+  Storybook MDX cheatsheet deferred (themes folder has no story precedent
+  in repo) — replaced by Markdown cheatsheet co-located with the layer.
+
+  See `packages/core/docs/adr/ADR-002-layered-theme-aliases-and-surface.md`
+  §3, §6 (Slice 3).
+
+- 820a612: feat(themes): ADR-002 Slice 4 — Surface inversion (positive / negative)
+
+  Adds contextual surface inversion for Semantic + Foundation **without
+  touching Structural**, resolving the "dark card on light page" hack
+  documented in ADR-002 §2.
+
+  Public API:
+  - `<SurfaceProvider surface="positive" | "negative">` — lightweight wrapper
+    for subtree inversion (preferred). Uses styled-components theme function
+    pattern (ADR-002 §9 grill-with-docs §1).
+  - `invertForSurface(theme, surface)` — pure, idempotent helper (ADR-002 §9).
+  - `ApollionProvider` now accepts `surface` prop for app-wide inversion.
+  - New type: `SurfaceMode = 'positive' | 'negative'`.
+  - Subpath import: `@apollion-dsi/core/themes/surface`.
+  - Quick docs: `packages/core/src/themes/Surface/README.md`.
+
+  Semantics of inversion (v1):
+  - Structural (`theme.colors.*`, `theme.spacing(...)`) untouched.
+  - `foundation.bg.{primary,secondary,tertiary}` → `colors.baseDark`.
+  - `foundation.bg.<feedback>` → `colors.<feedback>.dark` (hue preserved).
+  - `foundation.text.*` → `colors.baseLight` (always).
+  - `semantic.color.brand.{n}.default.surface` → `colors.<brand>.dark`.
+  - `semantic.color.feedback.<state>.border` → `colors.<state>.base`.
+
+  Tests: 17 new cases including WCAG contrast sanity checks and subtree
+  isolation (negative does not leak to siblings).
+
+  Limitations (v1, deferred to ADR-003 / v4 epic):
+  - Inversion is deterministic and ignores `themeMode` — Apollion v3.x has
+    no algorithmic mode resolution yet. v4 will introduce "negative within
+    the current mode" semantics per Aplica DS Mode × Surface matrix.
+
+  Refs:
+  - packages/core/docs/adr/ADR-002-layered-theme-aliases-and-surface.md §3.2, §6, §9
+  - packages/core/src/themes/Surface/README.md (full cheatsheet)
+
+  🎉 ADR-002 epic complete (Slices 1-4 shipped, 3.0.0 → 3.3.0).
+
+- 75961a1: feat: novo `Calendar` primitive + `InputDate` reescrito com popover Apollion-styled
+
+  Substitui o antigo wrapper de `<input type="date">` nativo por um popover
+  Apollion-styled. Resolve dois problemas distintos:
+  1. **Bug crítico no `form/Input`**: o default `value = ''` em
+     `Input.tsx:27` forçava todos os Inputs ao modo controlled mesmo quando
+     o consumer passava apenas `defaultValue`. Afetava `InputDate`,
+     `InputCurrency`, `InputMask`, etc. — sintoma reportado era "valor não
+     atualiza ao selecionar". Fix cirúrgico + regressão em `Input.test.tsx`.
+  2. **Visual inconsistente cross-browser do `InputDate`**: o picker nativo
+     variava de UA pra UA e Safari Desktop não tinha picker nenhum.
+
+  Mudanças:
+  - **Novo:** `elements/Calendar` — primitive de grid headless sobre
+    `react-day-picker@9`. Modos `single`/`multiple`/`range`, locale via
+    `date-fns` (default `ptBR`), `disabled`/`hidden` via `Matcher`. Não
+    cuida de posicionamento — é grid puro. Stories Default/Range/Locale/MinMax.
+  - **Refatorado:** `form/InputDate` — `Input[type=text readOnly]` + popover
+    com `@floating-ui/react` + `Paper` + `Calendar`. API **drop-in**:
+    `onChange: (e: ChangeEvent<HTMLInputElement>) => void` preservado via
+    synthetic event (`target.value` em ISO `yyyy-MM-dd`). Adicional
+    `onValueChange: (iso) => void` para código novo. Novas props: `locale`,
+    `displayFormat`, `minDate`, `maxDate`, `disabledDates`.
+  - **Fix:** `form/Input` deixa de forçar `value=""` quando consumer omite
+    `value`. Permite `defaultValue` funcionar.
+  - **Novo ícone:** `calendar` em `icons/Icons/categoryInterface.tsx`.
+  - **Deps:** `react-day-picker@9.5.0`, `date-fns@4.1.0`. ~25 KB gzip.
+  - **Subpath export:** `@apollion-dsi/core/elements/calendar` registrado em
+    `package.json#exports`.
+
+  Sem breaking change. Consumers existentes do `InputDate` (zero hoje em
+  DEX/Jovian/Fanaticofc) continuam funcionando — `onValueChange` é o caminho
+  novo recomendado.
+
+  Ver `docs/ROADMAP.md` §🟡 Next ("Calendar primitive + InputDate refactor"
+  ✅ COMPLETE 2026-05-27).
+
+- fba9a41: feat(core): DataTable absorbs faceted filters (per-column drill-down)
+
+  ROADMAP §🟡 Next "DataTable absorption gaps" — 3rd sub-feature
+  shipped (after pagination + tree expansion). Remaining: column
+  reordering + detail-panel expansion (deferred — conflicts with
+  fixed-row-height virtualizer).
+
+  Shipped across 4 vertical slices (+ 2 visual baseline commits):
+  - **S1** (`552e1ca`) — Vendor extension: added `getFacetedRowModel`,
+    `getFacetedUniqueValues`, `getFacetedMinMaxValues` runtime exports
+    and `ColumnFiltersState`, `FilterFn` type re-exports to
+    `vendors/TanstackReactTable/`. Wrapper test grew from 15 to 21
+    invariant cases (`TanstackReactTable.test.ts`).
+  - **S2** (`865525c` + baseline `90ce176`) — DataTable wiring + filter
+    UI + bonus dead-code fix. New `DataTable.filters.tsx` houses three
+    pure sub-components anchored in `<Dropdown>` popovers off the
+    header filter icon: - `SelectFilter` — multi-select checkboxes with counts (uses
+    `getFacetedUniqueValues()`). - `RangeFilter` — 2 number inputs (uses
+    `getFacetedMinMaxValues()` for placeholders). Apply debounced
+    200ms. - `TextFilter` — single input. Case-insensitive contains. Apply
+    debounced 200ms. - `VARIANT_FILTER_FN` resolver maps
+    `'select' → 'arrIncludesSome'`, `'range' → 'inNumberRange'`,
+    `'text' → 'includesString'`. Consumer overrides via
+    `Column.filterFn`.
+
+        New styled `HeaderControls` grouper centralizes the filter + sort
+        icon alignment in the header cell. Filter icon click stops
+        propagation so it does NOT toggle sort. `useReactTable` spreads
+        faceted helpers + columnFilters state conditionally on
+        `hasAnyFilter` (derived from `columns.some(c =>
+
+    c.filterVariant && !c.disableFilters)`) — zero overhead when no
+    column opts in.
+
+        **Bonus fix:** activates `Column.disableFilters` (was no-op for
+        multiple cycles). Now hides the filter icon AND sets
+        `enableColumnFilter: false` on the corresponding ColumnDef.
+
+        Filter icon: `ellipsisH` (3-dot more-options) — DS icon registry
+        has no `filter`/`funnel` icon; `ellipsisH` reads as "open options".
+        A dedicated SVG can land later without changing the public API.
+
+        Existing 5 DataTable visual baselines regen'd: the `<HeaderControls>`
+        wrapper shifts the sort icon's spacing by `theme.spacing('xs')` on
+        any sortable column, even when no filter chrome is rendered. The
+        functional behavior is unchanged — click on the header still
+        toggles sort.
+
+  - **S3** (`2ce44ef` + baseline `b9fa130`) — New `FacetedFiltering`
+    story with 4 columns showcasing all three variants + a
+    `disableFilters` override. 9 new jsdom-observable smoke tests
+    (mounts per variant, header text co-exists with chrome,
+    `disableFilters` honored, controlled / initialColumnFilters,
+    consumer filterFn override, default-off path).
+  - **S4** (this commit) — README.mdx adds "Filtros por coluna
+    (faceted)" section with variant table, controlled + uncontrolled
+    examples, `filterFn` override pattern, and the i18n / pipeline /
+    drill-down notes. README.AI.md grows by 5 rows (Column-level
+    `filterVariant` + `filterFn` + DataTable-level
+    `initialColumnFilters`, `columnFilters`, `onColumnFiltersChange`).
+    `disableFilters` description corrected (was "exclude from global
+    filter" — actually it opts the column out of the per-column filter
+    pipeline AND hides the filter icon).
+
+  New props on `DataTableProps` (all optional, default-off):
+  - `initialColumnFilters?: ColumnFiltersState` — uncontrolled init.
+  - `columnFilters?: ColumnFiltersState` — controlled state.
+  - `onColumnFiltersChange?: OnChangeFn<ColumnFiltersState>` — controlled
+    callback; also fires in uncontrolled mode as observer (via reused
+    `useHybridState` helper from S2/S3 #8).
+
+  New props on `Column<T>`:
+  - `filterVariant?: 'select' | 'range' | 'text'` — opt-in switch +
+    drives UI choice.
+  - `filterFn?: FilterFn<T> | string` — custom filter logic override.
+
+  Non-breaking for existing consumers — all new props default-off. The
+  `Column.disableFilters` activation is technically observable but the
+  declared semantics were already what the docs said; the no-op was the
+  bug.
+
+  40 suites · 318 tests passing. Coverage 69.72 / 50.57 / 56.65 / 69.42
+  (vs floors 68/48/53/67).
+
+- 3a90653: feat(core): DataTable absorbs pagination + expandable tree rows
+
+  ROADMAP §🟡 Next "DataTable absorption gaps" — 2 of 4 sub-features
+  shipped this cycle. The remaining 2 (column reordering, faceted
+  filters) stay open for future cycles; detail-panel expansion is
+  documented as a separate gap (conflicts with the fixed-row-height
+  virtualizer).
+
+  Shipped across 4 vertical slices:
+  - **S1** (`e53fec6`) — Vendor extension: added `getPaginationRowModel`
+    - `getExpandedRowModel` runtime exports and `PaginationState`,
+      `ExpandedState`, `OnChangeFn` type re-exports to
+      `vendors/TanstackReactTable/`. Closed the pre-existing wrapper-test
+      gap (15 invariant cases mirror FloatingUI / TanstackReactVirtual S1
+      pattern).
+  - **S2** (`ac54bd8` + baseline `3d3a45e`) — Pagination: opt-in via
+    `paginated: true`. New `PaginationRow` styled + `PaginationControls`
+    pure component (`"Mostrando X-Y de Z"` + Anterior / page indicator /
+    Próximo + page-size dropdown). Hybrid state pattern via new
+    `useHybridState<T>` helper that unifies controlled/uncontrolled in a
+    single `[value, setValue]` callsite. New `Paginated` story + 1
+    visual baseline. 8 new tests.
+  - **S3** (`808d162` + baseline `763bbe6`) — Expandable tree: opt-in
+    via `getSubRows` callback. New `buildExpandColumnDef` helper mirrors
+    `buildSelectableColumnDef`; expand toggle column injected leftmost
+    (read order: "control the tree → select what you see → consume
+    data"). Chevron indented by `row.depth * 16px`. `useHybridState`
+    reused for `ExpandedState`. New `Expandable` story + 1 baseline. 5
+    new tests.
+  - **S4** (this commit) — README.mdx adds "Paginação client-side" +
+    "Linhas expansíveis (modo tree)" sections with controlled +
+    uncontrolled examples. README.AI.md props table extended with the
+    10 new props. ROADMAP entry stays in `🟡 Next` annotated with the
+    shipped sub-features.
+
+  New props on `DataTableProps` (all optional, default-off):
+
+  Pagination:
+  - `paginated?: boolean` — opt-in flag.
+  - `initialPagination?: Partial<PaginationState>` — uncontrolled init.
+  - `pagination?: PaginationState` — controlled state.
+  - `onPaginationChange?: OnChangeFn<PaginationState>` — controlled
+    callback; also fires in uncontrolled mode as observer.
+  - `pageSizeOptions?: number[]` — default `[10, 25, 50, 100]`. Empty
+    or single-element hides the page-size selector.
+
+  Expandable (tree mode):
+  - `getSubRows?: (row: T, index: number) => T[] | undefined` — opt-in.
+  - `expandedColumnWidth?: number` — defaults to
+    `selectableColumnWidth`.
+  - `initialExpanded?: ExpandedState` — uncontrolled init (use `true`
+    to expand all).
+  - `expanded?: ExpandedState` — controlled state.
+  - `onExpandedChange?: OnChangeFn<ExpandedState>` — controlled callback.
+
+  Non-breaking for existing consumers — all new props default-off, none
+  of the 21 existing DataTable visual baselines drift, public API of
+  `DataTableProps` is purely additive.
+
+  Strings (`"Mostrando X-Y de Z"`, `"Anterior"`, `"Próximo"`,
+  `"{N} / página"`) hardcoded PT-BR — consistent with `EmptyTable`'s
+  default `"Nada foi encontrado"`. Apollion has no i18n layer today;
+  documented gap.
+
+  40 suites · 302 tests passing. Coverage `70.46 / 50.95 / 57.73 /
+70.17` (vs floors `68 / 48 / 53 / 67`).
+
+- 5fca933: feat(core): swap `react-window` for `@tanstack/react-virtual` in DataTable
+
+  ROADMAP §🟡 Next "Migrate ReactWindow → @tanstack/react-virtual" closes
+  across 4 vertical slices:
+  - **S1** (`456b13e`) — Scaffolded `vendors/TanstackReactVirtual/`
+    re-exporting `useVirtualizer` + `Virtualizer` + `VirtualItem` from
+    `@tanstack/react-virtual@^3.13.26`. 3 wrapper-invariant unit tests
+    modeled on ADR-005 S2.
+  - **S2** (`e04e6c4`) — Refactored `DataTable.tsx` virtualization block
+    to use the hook via a small internal `VirtualizedRows` wrapper. The
+    public `renderRow({ index, style })` callsite contract stayed
+    stable. Dropped the file-level `@ts-ignore` and the inline
+    `@ts-ignore TS2786` over the JSX block. Replaced
+    `outerElementType={VitualScrollbar}` with direct
+    `<VitualScrollbar ref={parentRef}>`. Added 4 jsdom-observable
+    characterization tests (mount / headers / empty state). Refreshed
+    one visual-regression baseline (`components-datatable--bordered`,
+    0.19% pixel drift on transform-vs-absolute border rendering).
+  - **S3** (`04d9f7e`) — Added 8 wide-scope smoke tests: header chrome
+    (title / hasHeader gating / search placeholder), header checkbox
+    select-all + deselect cycles via `onRowSelect`, spacing-menu
+    rendering, sortable-header click cycle.
+  - **S4** (this commit) — Removed `vendors/ReactWindow/` and the
+    `react-window` + `@types/react-window` deps. Flipped the
+    `VENDORED_T1_UI_LIBS` allow-list in `@apollion-dsi/eslint-config`
+    to replace `'react-window'` with `'@tanstack/react-virtual'` so the
+    vendor-isolation rule keeps catching future direct imports outside
+    `src/vendors/**`.
+
+  Why the swap (driver):
+  1. **Same family as `@tanstack/react-table`** (already vendored). One
+     fewer mental model, one fewer audit surface.
+  2. **React 19 + TS 6 compatibility.** `react-window` is class-component
+     with an incompatible type shape — required `@ts-ignore TS2786` at
+     the JSX site. Hook surface removes that debt.
+  3. **Variable-row-height unlocked.** `useVirtualizer` exposes
+     `estimateSize: (i) => number` + opt-in `measureElement`. Future
+     DataTable variable-row work (ROADMAP §🟡 "DataTable absorption
+     gaps") needs no further vendor swap.
+
+  Non-breaking for consumers — `DataTable<T>` public API
+  (`data` / `columns` / `height` / `striped` / `bordered` / `hasHeader` /
+  `onRowSelect` / `renderRow`-like callbacks via `Column.Cell`) stays
+  identical. Bundle delta: react-window 1.8.11 + @types/react-window
+  1.8.8 (~7 KB shipped + types) out, @tanstack/react-virtual 3.13.26 +
+  @tanstack/virtual-core 3.16.0 (~12 KB shipped) in. Net node_modules
+  freed: 929 KiB.
+
+  Coverage at the end of the swap: statements 69.95 / branches 49.69 /
+  functions 56.08 / lines 69.63 — comfortably above the ratchet floors
+  (68 / 48 / 53 / 67). +1 vendor test suite + 1 DataTable test suite (12
+  cases total).
+
+- ea3dc3a: feat(core): swap `@tippyjs/react/headless` for `@floating-ui/react` in Tooltip + Dropdown
+
+  ROADMAP §🟡 Next "Migrate TippyHeadless → @floating-ui/react" closes
+  across 4 vertical slices, all landed in the same day:
+  - **S1** (`f75e428`) — Scaffolded `vendors/FloatingUI/` re-exporting
+    the runtime surface from `@floating-ui/react@^0.27.19`: 10 hooks
+    (`useFloating`, `useInteractions`, `useClick`, `useHover`,
+    `useFocus`, `useDismiss`, `useRole`), 2 components
+    (`FloatingPortal`, `FloatingFocusManager`), 5 middleware (`arrow`,
+    `offset`, `flip`, `shift`, `autoUpdate`), 4 types (`Placement`,
+    `Strategy`, `MiddlewareData`, `OpenChangeReason`). 29 wrapper-
+    invariant unit tests (singleton + runtime shape + type re-exports).
+  - **S2** (`d61a111`) — Refactored `Tooltip.tsx` from `<Tippy
+render={…}>` to `useFloating + useInteractions([useHover(restMs: 40),
+useFocus(), useDismiss(), useRole({ role: 'tooltip' })])`. Added
+    `useFocus` per Q2 of the grill so the tooltip also opens on Tab
+    focus (a11y AAA). Arrow positioning is now inline at the callsite,
+    reading `middlewareData.arrow.{x, y}` (Q3 option a). Tooltip gained
+    its first `.test.tsx` (6 cases on the controlled `visible` path —
+    jsdom can't observe uncontrolled hover/focus). Dropped the
+    `@ts-ignore TS2786`.
+  - **S3** (`681f73b`) — Refactored `Dropdown.tsx` to `useFloating +
+useInteractions([useClick({ enabled: !function-children }),
+useHover({ enabled: hoverable }), useDismiss(), useRole({ role })])`.
+    Per Q1.a: `role: 'menu'` when `options` prop is passed, `role:
+'dialog'` when arbitrary `content` — `useRole(context, { role })`
+    injects the correct `aria-haspopup` and the floating-element role.
+    Wraps the floating element in `<FloatingPortal>` +
+    `<FloatingFocusManager modal={false} initialFocus={-1}>` (no trap,
+    no auto-focus jump — preserves the legacy click-and-pick UX).
+    Existing 5 tests in `Dropdown.test.tsx` pass unchanged. Dropped
+    the `@ts-ignore TS2786`.
+  - **S4** (this commit) — Removed `vendors/TippyHeadless/` and the
+    `@tippyjs/react` dep. Flipped the `VENDORED_T1_UI_LIBS` allow-list
+    in `@apollion-dsi/eslint-config` to replace
+    `'@tippyjs/react/headless'` with `'@floating-ui/react'` so the
+    vendor-isolation rule keeps catching future direct imports outside
+    `src/vendors/**`. Removed the corresponding ROADMAP entry per the
+    new convention (drop completed items instead of striking them
+    through — see `7c2d253`).
+
+  Why the swap (driver):
+  1. **`tippy.js` sem release ≥ 18 meses.** `floating-ui` is the de
+     facto successor, maintained by the original Popper author whose
+     library `tippy.js` already wrapped internally. Same family, zero
+     functional regression in the consumer-facing surface.
+  2. **Explicit a11y.** Tippy didn't dictate ARIA. `useRole(context, {
+role })` injects `role="tooltip" | "menu" | "dialog"` plus the
+     matching `aria-haspopup` / `aria-describedby` linkage via prop
+     getters. A11y is now code, not hope.
+  3. **Composição visível.** `<Tippy interactive onClickOutside={…}>`
+     packaged hover/click/focus/dismiss into a single opaque boolean.
+     floating-ui demands `useInteractions([useClick, useHover, useFocus,
+useDismiss, useRole])` — the reader knows exactly which behaviors
+     are wired. Tested invariants per `enabled` flag.
+  4. **Type ergonomics.** Pure hooks — no `@ts-ignore TS2786` (which
+     was required in 2 sites with React 19 + TS 6).
+
+  Non-breaking for consumers — `TooltipProps` and `DropdownProps`
+  public surface unchanged. `interactive?: boolean` on `Tooltip` is
+  kept as a `@deprecated` legacy no-op because floating-ui's tooltip is
+  inherently interactive (hover/focus on the floating element doesn't
+  trigger dismiss). `position` props now type as `Placement` from
+  `@floating-ui/react` — same 12 string-literal values as Tippy.
+
+  Bundle delta:
+  - Out: `@tippyjs/react@4.2.6` + transitive `tippy.js@6.3.7` (~2.23 MiB
+    on disk, ~16 KB shipped).
+  - In: `@floating-ui/react@0.27.19` + transitive `@floating-ui/react-
+dom`, `@floating-ui/utils`, `tabbable` (~911 KiB on disk, ~11 KB
+    shipped).
+  - Net: ~5 KB shipped reduction; ~1.32 MiB node_modules freed.
+
+  Coverage at the end of the swap: statements 70.25 / branches 49.97 /
+  functions 57.37 / lines 70.01 — comfortably above the ratchet floors
+  (68 / 48 / 53 / 67). +1 vendor test suite (29 cases) + 1 Tooltip test
+  suite (6 cases).
+
+### Patch Changes
+
+- 032f81c: docs: ADR-002 Slice 1 — CONCEPTS.md + README lineage
+
+  Adds conceptual reference document covering the Layer Cake (Structural →
+  Semantic → Foundation), 3-group communication model (Abstraction / Intent /
+  Consumer), Learning Spiral with three personas, bilingual glossary (PT-BR /
+  EN-US), and the Apollion ⇄ Aplica DS vocabulary map.
+
+  Credits Fernando Poe (co-author of Apollion 2020, author of
+  [Aplica DS](https://aplica.me/en/)) in a new Lineage & Acknowledgements
+  section of the README.
+
+  Doc-only. Zero API change.
+
+  See `packages/core/docs/adr/ADR-002-layered-theme-aliases-and-surface.md` §6
+  (Migration Plan, Slice 1).
+
+- c056ee3: chore(core,eslint-config): ADR-004 backfill — vendor `react-day-picker` + `date-fns` + InputDate hardening
+
+  Pattern-guardian audit do commit `75961a1 Input Date` (Calendar primitive +
+  InputDate refactor) flagueou 4 desvios vs Apollion gold standard. Backfill
+  consolidado neste PR:
+
+  **V1 — ADR-004 backfill (2 novos vendors, vendor count 16 → 18):**
+  - **ReactDayPicker** (T1 UI, 4 files)
+    - Absorbed runtime: `DayPicker`
+    - Absorbed types: `DayPickerProps`, `Mode`, `DateRange`, `Matcher`,
+      `PropsSingle`, `PropsSingleRequired`, `PropsRange`, `PropsRangeRequired`
+    - Gap intencional: `useDayPicker` hook, `Modifier` API, plugins `addons`
+      — reabsorver quando `InputDateTime`/`TimePicker` (ROADMAP) precisar.
+  - **DateFns** (util tier, 4 files, novo `VENDORED_DATE_LIBS` na eslint-config)
+    - Absorbed runtime: `format`, `parse`, `parseISO`, `isValid`
+    - Absorbed locales: `ptBR`, `enUS`
+    - Absorbed types: `Locale`
+    - Gap intencional: `addDays`/`subDays`/aritmética, `formatDistance`/
+      formatação relativa, locales adicionais — adicionar conforme demanda.
+
+  Sites migrados (8 files): Calendar.tsx, Calendar.interface, Calendar.test,
+  Calendar/story, InputDate.tsx, InputDate.interface, InputDate.test,
+  InputDate/story.
+
+  **V2 — `parseInputDate` removido** do barrel `form/InputDate/index.ts`:
+  re-export vazava `date-fns` na public surface do DS (anti-pattern
+  ADR-004). Sem consumers conhecidos. Consumers que precisem importam
+  direto de `date-fns` no próprio package.
+
+  **V3 — `InputDate.handleKeyDown` a11y**: rewrite blocklist → allowlist.
+  Antes: `preventDefault` em tudo exceto Tab/Enter/Space — Esc, ArrowUp/Down/
+  Left/Right, Home, End, PageUp/Down ficavam swallowed, quebrando
+  `useDismiss({ escapeKey: true })`. Agora: `preventDefault` só em printable
+  chars (`key.length === 1 && key !== ' '`); named keys bubblam livremente.
+  WCAG 2.1.1 ok.
+
+  **V4 — `buildSyntheticEvent` extraído** para `form/InputDate/buildSyntheticEvent.ts`:
+  helper com cast-chain `as unknown as ChangeEvent` é fragile sob mudança
+  de shape em majors do React. Novo arquivo dedicado + 6 testes de contrato
+  runtime detectam drift cedo.
+
+  **Determinismo visual**: `Calendar/story.tsx` agora pin `FIXED_TODAY`
+  constant + `today`/`month` props nas 4 stories — baseline não drifta
+  diariamente conforme `new Date()` muda (era 0.5%+ por dia, acima do
+  threshold 0.1%).
+
+  Backward-compatible runtime API. Validate verde
+  (54 visual tests, 352+ unit tests, lint, typecheck, build).
+
+  Refs:
+  - `packages/core/docs/adr/ADR-004-vendor-isolation-policy.md` (status
+    atualizado: 18 vendors após backfill)
+  - `docs/ROADMAP.md` §"Calendar primitive + InputDate refactor" (hardening
+    block adicionado)
+  - `packages/core/src/vendors/ReactDayPicker/README.md` + DateFns/README.md
+
+- d032437: docs(core): ADR-004 / PRD-001 S0 — vendor isolation scaffold
+
+  Approves ADR-004 (Vendor Isolation Policy) and PRD-001 (Vendor Isolation
+  Execution). Adds the infrastructure that makes `packages/core/src/vendors/`
+  internal-only:
+  - `esbuild.js` skips `vendors/` in `findEntryPoints` so wrappers never
+    become bundle entry points.
+  - `scripts/check-vendors-not-published.js` (new) asserts the invariant
+    post-build: no `lib/vendors/**` and no `./vendors/*` keys in
+    `package.json#exports`. Wired into `validate.sh`.
+  - `docs/CONCEPTS.md` gets a new §8 Vendor Isolation covering the canonical
+    shape (`component.ts` / `interface.ts` / `index.ts` / `README.md`), hard
+    rules, and rationale.
+  - `ROADMAP.md` moves vendor isolation to 🔴 Now.
+
+  `generate-exports.js` needed no change: its allow-list (`LEAF_CATEGORIES`,
+  `UTIL_CATEGORIES`) already excludes `vendors/` by construction.
+
+  No vendor wrappers in this slice. No API surface change. Doc + infra only.
+
+  See `packages/core/docs/adr/ADR-004-vendor-isolation-policy.md` §6 (Migration
+  Plan, Slice 0) and `packages/core/docs/prd/PRD-001-vendor-isolation-execution.md`.
+
+- 00e0525: feat(core,eslint-config): ADR-004 Slice 1 — T2 utils vendoring
+
+  Vendor 8 T2 utility libs (re-export wrappers only) into
+  `packages/core/src/vendors/<Lib>/`, migrating all direct imports across
+  the core, and add a `no-restricted-imports` ESLint rule (severity `warn`)
+  that enforces the policy in `@apollion-dsi/eslint-config`.
+
+  **Vendored libs (T2 utils, 8 wrappers × 4 files):**
+  - Nanoid (4 sites)
+  - LodashDebounce (2)
+  - ObjectHash (1)
+  - Deepmerge (1)
+  - Color (3 — incl. Surface.test.tsx)
+  - FastDeepEqual (1)
+  - EmotionIsPropValid (2)
+  - StyledNormalize (1)
+
+  **Each vendor ships with:**
+  - `component.ts` — typed re-export of the absorbed surface
+  - `interface.ts` — DS-owned contract (skeleton for S1; full opinionated
+    shape will land per-lib in S2-S4 where DS opinion matters more)
+  - `index.ts` — barrel
+  - `README.md` — skeleton with `## What this vendor wraps` etc. — full
+    pass in S5
+
+  **ESLint rule (`@apollion-dsi/eslint-config`):**
+  - Path-scoped to `packages/core/src/**/*.{ts,tsx}`
+  - Allows direct upstream imports inside `packages/core/src/vendors/**`
+  - Severity `warn` in S1-S5 (grace period); flips to `error` in S6
+  - Other workspaces unaffected (paths don't match)
+
+  **Backward-compatible:** vendors are internal (esbuild skips the folder,
+  generate-exports.js doesn't list them, validate.sh's
+  `check-vendors-not-published.js` keeps the invariant). Consumer-side import
+  surface (`@apollion-dsi/core/elements/button` etc.) unchanged.
+
+  Bundle delta target: ≤ 0 KB gzip (re-exports are inlined by esbuild).
+
+  Refs:
+  - `packages/core/docs/adr/ADR-004-vendor-isolation-policy.md` §6 Slice 1
+  - `packages/core/docs/prd/PRD-001-vendor-isolation-execution.md` §S1
+
+- 1c87be8: feat(core,eslint-config): ADR-004 S2 — T1 UI primitives vendoring
+
+  Vendor 4 T1 UI primitive libs into `packages/core/src/vendors/<Lib>/`
+  and migrate 12 direct import sites. Extends the ESLint
+  `no-restricted-imports` rule (warn) to cover the new vendors.
+
+  **Vendored libs (T1 UI, 4 × 4 files):**
+  - FramerMotion (6 sites: Modal, Notification × 3, Flex.style, Base.style)
+    - Absorbed: `motion`, `AnimatePresence`, `MotionConfig`, `useReducedMotion`, `MotionProps`
+    - Gap: gestures, drag, useAnimate, useScroll, layoutGroup (intentional — DS doesn't expose full expressiveness)
+  - TippyHeadless (3 sites: Dropdown, Tooltip × 2)
+    - Absorbed: `Tippy` default + `TippyProps`
+    - Uses headless entry only (no embedded CSS)
+  - ReactContentLoader (2 sites: ComposedSkeleton × 2)
+    - Absorbed: `ContentLoader`, `BulletList`, `Code`, `Facebook`, `List`, `IContentLoaderProps`
+  - ReactWindow (1 site: DataTable)
+    - Absorbed: `FixedSizeList` only
+
+  Backward-compatible. Bundle delta target ≤ +0.1 KB gzip per ADR-004 §6.
+  Snapshot tests Modal/Notification (framer consumers) inalterados.
+
+  Refs:
+  - `packages/core/docs/adr/ADR-004-vendor-isolation-policy.md` §6 Slice 2
+  - `packages/core/docs/prd/PRD-001-vendor-isolation-execution.md` §S2
+
+- d1192da: feat(core,eslint-config): ADR-004 S3 — T1 form/validation vendoring
+
+  Vendor 3 T1 form/validation libs into `packages/core/src/vendors/<Lib>/`
+  and migrate 13 direct import sites. Slice mais opinativo do épico
+  ADR-004 — `interface.ts` faz o exercício real de "contrato ideal do DS,
+  não espelho da lib" (ADR-004 §6 S3).
+
+  **Vendored libs (T1 form/validation, 3 × 4 files):**
+  - **Formik** (4 sites: Form.{interface,tsx,helpers}, Field.interface)
+    - Absorbed runtime: `useFormik` apenas (DS expõe `Form`/`Field`/`FieldGroup` próprios)
+    - Absorbed types: `FormikErrors`, `FormikHelpers`, `FormikProps`, `FormikSharedConfig`
+    - Gap intencional: `<Field>`, `<FieldArray>`, `<ErrorMessage>`, `Formik`, `FormikProvider`, `useFormikContext`, `useField`, `withFormik`, wizards
+  - **Yup** (4 sites: Form.{interface,tsx,helpers}, story.tsx)
+    - Absorbed: namespace inteiro via `export *` — preserva padrão `import * as Yup`
+    - Justificativa: Yup é DSL; restringir builders quebra expressividade
+  - **ReactSelect** (5 sites: InputSelect.{tsx,interface}, DropdownIndicator)
+    - Sync + `/async` consolidados em 1 wrapper
+    - Absorbed runtime: `DefaultSelect`, `AsyncSelect`, `components`
+    - Absorbed types: `DropdownIndicatorProps`, `ReactSelectProps` (re-export renomeado de `Props`)
+    - Gap: `Creatable`, `formatGroupLabel`, `MenuListProps`, `MultiValue`, sortable
+
+  ESLint rule estendida para cobrir `formik`, `react-select`,
+  `react-select/async`, `yup` com severidade `warn` (flips em S6).
+
+  Backward-compatible. Bundle delta target ≤ +0.1 KB gzip em `lib/form/form/`.
+
+  Refs:
+  - `packages/core/docs/adr/ADR-004-vendor-isolation-policy.md` §6 Slice 3
+  - `packages/core/docs/prd/PRD-001-vendor-isolation-execution.md` §S3
+
+- 3194fba: feat(core,eslint-config): ADR-004 S4 — T1 data/routing vendoring
+
+  Vendor 2 T1 data/routing libs into `packages/core/src/vendors/<Lib>/`
+  and migrate 7 direct import sites.
+
+  **Vendored libs (T1 data/routing, 2 × 4 files):**
+  - **ReactRouterDom** (5 sites: Link.style, Link.interface, Link.test,
+    List/story, Link/story)
+    - Absorbed runtime: `Link`, `MemoryRouter` (stories + tests apenas)
+    - Absorbed types: `LinkProps`
+    - Gap intencional: tudo o mais. Decisão consciente (ADR-004 §9 Q3):
+      DS não deve ditar router. Reabsorver é diff por símbolo + entrada
+      de roadmap. `BrowserRouter`, `Route`, `Routes`, `Outlet`,
+      `useNavigate`, `useLocation`, `useParams`, `NavLink`, `Navigate`
+      não absorvidos.
+  - **TanstackReactTable** (2 sites: DataTable.tsx multi-import + DataTable.interface)
+    - Absorbed runtime: `useReactTable`, `flexRender`, `getCoreRowModel`,
+      `getSortedRowModel`, `getFilteredRowModel`
+    - Absorbed types: `ColumnDef`, `Row`, `RowSelectionState`,
+      `SortingState`
+    - Gap: `getExpandedRowModel`, `getGroupedRowModel`,
+      `getPaginationRowModel`, `getFacetedRowModel` + types `Cell`,
+      `Header`, `Table`, `RowModel`, `Column`, etc. — features que
+      DataTable do core não suporta hoje.
+
+  ESLint rule estendida (warn) cobrindo `@tanstack/react-table` e
+  `react-router-dom`.
+
+  Backward-compatible. Validate target verde (180+ tests, snapshots
+  inalterados em DataTable/Link).
+
+  Refs:
+  - `packages/core/docs/adr/ADR-004-vendor-isolation-policy.md` §6 Slice 4
+  - `packages/core/docs/prd/PRD-001-vendor-isolation-execution.md` §S4
+
+- f359982: docs(core): ADR-004 S5 — Vendor README full pass
+
+  Preenche os 17 vendor READMEs (skeleton → completo) com 3 seções
+  padronizadas + atualiza ROADMAP com 6 entradas derivadas de gaps:
+
+  **Cada vendor README agora tem:**
+  - `## What this vendor wraps` — npm link + versão exata + tabela
+    símbolo → tipo → uso no core
+  - `## DS Absorption Gap` — bullet do que ficou fora + rationale + link
+    ROADMAP quando candidato
+  - `## Replacement candidates` — libs concorrentes com trade-off explícito
+    - "When to consider" + triggers de troca quantificados
+
+  **Novas entradas em ROADMAP.md (🟡 Next):**
+  1. Migrate ReactWindow → @tanstack/react-virtual (Low burn, consolida ecosystem)
+  2. Migrate TippyHeadless → @floating-ui/react (Medium burn, sucessor natural)
+  3. Router-agnostic Link — remove react-router-dom dep (Medium, candidato ADR-006)
+  4. DataTable absorption gaps (expandable rows, pagination, etc.)
+  5. FormWizard absorption + Combobox replacement evaluation
+  6. Zod/Valibot evaluation paired with form library refactor
+
+  **Resolve numbering conflict:**
+  - ADR-003 (file) = Visual regression (não "v4 epic")
+  - ADR-005 = styled-components facade (placeholder)
+  - ADR-006 = v4 epic (OKLch + Dimension + token-only) — renomeado de "ADR-003"
+
+  Remove entrada duplicada "Visual regression suite (Chromatic)" de 🟡 Next
+  (agora coberta por ADR-003).
+
+  Doc-only. Sem mudança de código/API. Patch bump.
+
+  Refs:
+  - packages/core/docs/adr/ADR-004-vendor-isolation-policy.md §6 Slice 5
+  - packages/core/docs/prd/PRD-001-vendor-isolation-execution.md §S5
+
+- 5d17ebc: feat(core, eslint-config): ADR-005 — styled-components vendor facade
+
+  Closes the Vendor Isolation epic (ADR-004 §5 leftover). styled-components
+  becomes vendor #18 under `packages/core/src/vendors/StyledComponents/`,
+  following the same canonical 4-file shape used by the other vendors.
+
+  **Core (`@apollion-dsi/core`):**
+  - New `vendors/StyledComponents/{component.ts, interface.ts, index.ts,
+README.md, StyledComponents.test.ts}`. Wrapper re-exports the surface
+    consumed by the core (runtime: `styled`, `css`, `keyframes`,
+    `ThemeProvider`, `StyleSheetManager`, `createGlobalStyle`, `useTheme`;
+    types: `CSSObject`, `DefaultTheme`, `Interpolation`, `IStyledComponent`,
+    `RuleSet`, `Styled`).
+  - `DefaultTheme extends Theme` augmentation moved out of
+    `src/typings/index.d.ts` into the co-located `vendors/StyledComponents/
+interface.ts`. `typings/index.d.ts` reduced to `@testing-library/jest-dom` - the legacy `react-table` module declaration.
+  - 62 sites under `src/**/*.{ts,tsx}` codemoded from `import ... from
+'styled-components'` to the vendor wrapper via the new
+    `scripts/migrate-styled-components-imports.js` helper. READMEs in
+    `containers/Base/README.{mdx,AI.md}` preserved — consumer-facing examples
+    must keep showing `from 'styled-components'`.
+  - `@types/styled-components@5.1.36` removed from `devDependencies` — dead
+    for `styled-components@6.x`, which ships its own `dist/index.d.ts`.
+  - Vendor test verifies (a) singleton — wrapper re-exports identical
+    upstream runtime references, (b) `Theme` `satisfies DefaultTheme` at
+    compile time, (c) `useTheme()` returns the `Theme`-shaped object injected
+    by `<ApollionProvider>`.
+
+  **ESLint config (`@apollion-dsi/eslint-config`):**
+  - New `VENDORED_STYLED_LIBS = ['styled-components']` group folded into
+    `VENDORED_LIBS`. The existing `no-restricted-imports` rule now blocks
+    direct `from 'styled-components'` in `packages/core/src/**` (vendor
+    directory remains exempt). Severity `error` from day one — the codemod
+    guarantees zero violations before the rule activates, so the
+    warn-intermediate phase originally proposed in ADR-005 §6 S3 was
+    skipped (documented in ADR-005 §11.2).
+
+  Non-breaking: consumer-facing API and `ApollionProvider` behavior
+  unchanged. See `packages/core/docs/adr/ADR-005-styled-components-vendor-facade.md`
+  §11 for the full set of deviations between the planned and executed slices.
+
+- 6545751: docs(core): ADR-007 — Zod v4 idiomatic corrections + shadow-PoC S1 wording
+
+  Atualiza ADR-007 (Form stack migration) com correções pós grill-with-docs
+  (2026-05-27) sobre as APIs externas reais:
+  - **§S1 wording:** clarifica que S1 é **shadow-PoC em arquivo novo**
+    (`poc-rhf-zod.tsx`), NÃO migração do example atual. Examples atuais usam
+    `<Form>` do DS que ainda é Formik-backed em S0/S1 — migrar example exige
+    S2 (DS Form refactor) primeiro. Shadow-PoC destrava sem reverter ordem.
+  - **§S2 + §7 PoC code:** validation API muda de `validateOnChange`/
+    `validateOnBlur` booleans → `mode?: Mode` direto (breaking aceito em
+    v4.0.0). Mode type vendored em S0 follow-up.
+  - **§7 Yup→Zod mapping:** atualizado para Zod v4 idiomatic:
+    - `z.string().email()` → `z.email()` (top-level)
+    - `Yup.string().required()` → `z.string().min(1, 'msg')`
+    - `Yup.boolean().required()` → `z.boolean().refine((v) => v === true, ...)`
+    - `z.ZodIssueCode.custom` → `'custom'` string literal
+    - Nota sobre `z.unknown()` não ser optional por default em v4.
+  - **§7 BasicFormExample concrete mapping** adicionado — fonte de verdade
+    do S1 PoC schema.
+  - **§7 Zod v4 breaking changes table** adicionada com 10 entries cobrindo
+    todas as APIs usadas no PoC.
+  - **§8 Risks #6 atualizado:** validation API direct mode (não mais
+    mapping interno boolean→enum).
+  - **§8 Risks #9 + #10 adicionados:** Zod v4 `z.unknown()` não-optional
+    por default; `.refine()` removeu type narrowing via predicate.
+  - **§S0 marcado MERGED** com commits + 3 changesets gerados.
+  - **Status do ADR:** 📝 Proposed → 🚧 In Progress.
+
+  Doc-lock cross-checked contra `.d.ts` locais de `react-hook-form@7.76.1`,
+  `@hookform/resolvers@5.4.0` e `zod@4.4.3`, suplementado com WebFetch de
+  zod.dev/v4/changelog.
+
+- 36eaf4a: feat(core): ADR-007 S0 follow-up — expose `Mode` type in ReactHookForm vendor
+
+  Adiciona `Mode` (`'onSubmit' | 'onBlur' | 'onChange' | 'onTouched' | 'all'`)
+  ao surface re-exportado de `vendors/ReactHookForm/interface.ts`. Necessário
+  para `Form.interface.ts#FormCommonInterface['mode']` em S2 — substitui o par
+  booleano legado `validateOnChange?`/`validateOnBlur?` do Formik (decisão
+  fixada via tech-radar pass 2026-05-27).
+
+  Surface change pequena, isolada à interface do vendor. Zero impacto
+  runtime — só types.
+
+  Ver `packages/core/src/vendors/ReactHookForm/README.md` para tabela
+  atualizada.
+
+- 802828f: feat(core): ADR-007 S0 — react-hook-form vendor scaffold
+
+  Adds `packages/core/src/vendors/ReactHookForm/` (4 arquivos no padrão
+  ADR-004): re-export tipado de `useForm`, `Controller`, `useFormContext`,
+  `useFieldArray` + bridge adapter `zodResolver` (de `@hookform/resolvers/zod`)
+  co-localizado para evitar dois call-sites distintos.
+
+  Deps adicionadas (exact pin, latest stable):
+  - `react-hook-form@7.76.1`
+  - `@hookform/resolvers@5.4.0`
+
+  Vendor wrapper isolado — ainda não consumido pelo core (S2 migra
+  `form/Form/Form.tsx`). Zero impacto runtime nesta slice. `vendors/Zod/`
+  já existe desde ADR-006 S6 e cobre a surface de schema requerida — sem
+  duplicação.
+
+  Pre-flight verificado: lint, check-types e prettier verdes; sem violações
+  da regra `no-restricted-imports` (codemod do core acontece em S2).
+
+  Ver `packages/core/docs/adr/ADR-007-form-stack-rhf-zod.md` §6 Slice 0
+  e `docs/ROADMAP.md` §🟡 Next "Form stack migration — Formik+Yup → RHF+Zod".
+
+- e14469c: feat(core): ADR-007 S2 — DS Form internals migrated Formik+Yup → RHF+Zod
+
+  Migra os 4 arquivos core do `form/` do stack Formik+Yup para React Hook
+  Form + Zod, dentro do escopo de [vendors/ReactHookForm](src/vendors/ReactHookForm)
+  e [vendors/Zod](src/vendors/Zod) (ADR-004 vendor isolation). Single
+  commit no padrão "vertical-slice":
+
+  **Arquivos migrados:**
+  - **`form/Form/Form.tsx`** — `useFormik({...})` → `useForm<any>({ resolver: zodResolver(schema), mode: mode ?? 'onSubmit', defaultValues })`. `useImperativeHandle(ref, () => methods)` agora expõe `UseFormReturn<any>` no lugar de `FormikProps<any>`. `Field` continua recebendo `value`/`errors`/`setFieldValue` via prop (paradigma controlled preservado via `methods.watch()` e `methods.setValue`).
+  - **`form/Form/Form.helpers.ts`** — `getValidationSchema` agora constrói `z.object(shape)`. Default fallback p/ fields sem `validation`: `z.unknown().optional()` (Zod v4 requer `.optional()` explícito — `z.unknown()` não é optional por default em object schemas, mudança vs v3). `prepareSubmit` assinatura aceita `UseFormReturn<any>` no lugar de `FormikHelpers`.
+  - **`form/Form/Form.interface.ts`** — types swap inteiro:
+    - `FormRef = FormikProps<any>` → `FormRef = UseFormReturn<any>` (breaking API ref — major bump em v4)
+    - `validateOnChange?: boolean` + `validateOnBlur?: boolean` → **REMOVIDOS**. Substituídos por `mode?: Mode` enum (`'onSubmit' | 'onBlur' | 'onChange' | 'onTouched' | 'all'`), default `'onSubmit'`. Mapping legacy em MIGRATION-v4.md (ADR-007 §S5).
+    - `validation?: any | (() => any)` → `validation?: ZodTypeAny`
+    - `onError?: (errors: FormikErrors<...>) => void` → `onError?: (errors: FieldErrors<...>) => void`
+    - Workaround `const a = Yup.string().required()` (tree-shake legacy) removido.
+  - **`form/Field/Field.interface.ts`** — `setFieldValue?: FormikHelpers<any>['setFieldValue']` → `setFieldValue?: UseFormSetValue<any>`. Nome da prop preservado para minimizar blast-radius nos primitives (`InputDate`, `InputSelect`, etc. continuam chamando `setFieldValue(name, value)` — assinatura compat). Renome `FormikBaseInterface` → `FormBaseInterface`.
+  - **`form/Form/story.tsx`** (Storybook) — `Yup.string().required('Required')` → `z.string().min(1, 'Required')`; `Yup.string().email()` → `z.email()`. Import de `vendors/Yup` removido.
+
+  **Estado pós-S2:**
+  - `yarn workspace @apollion-dsi/core run validate:tests`: ✅ 317 passed (1 skipped pre-existente), 59 snapshots OK.
+  - `yarn workspace @apollion-dsi/core run check-types`: ✅ verde.
+  - `yarn workspace @apollion-dsi/core run lint`: ✅ zero violations.
+  - `yarn workspace @apollion-dsi/core run build` (esbuild + tsc + Storybook): ✅ verde.
+  - `yarn workspace @apollion-dsi/website run build` (Next.js): ✅ verde.
+
+  **Website examples (`BasicFormExample`, `FormExample`, `DynamicFormExample`) ainda usam Yup schemas:**
+
+  Type check passa via casting permissivo (`validation as ZodSchema`), mas runtime de submit no website QUEBRA (Yup schema sem `.parse()` → `zodResolver` throws). Render OK; submit broken until S3 migra os examples. Esperado per ADR-007 §S2 critério.
+
+  **Bundle delta:** ainda não visível (Yup permanece importado pelos examples website até S3). Re-measure em S3 com examples + smoke pages atualizadas.
+
+  Storybook stories (`Form/story.tsx`) já migradas — Storybook submit funciona end-to-end.
+
+  **Vendors antigos `vendors/Formik/` + `vendors/Yup/`:** preservados sem uso interno até S6 (hard cut em v4.0.0). 0 imports de `formik`/`yup` em `packages/core/src/**` fora dos próprios vendor dirs.
+
+  Ver `packages/core/docs/adr/ADR-007-form-stack-rhf-zod.md` §6 Slice 2.
+
+- 81cd55b: feat(website): ADR-007 S3 — migrate 8 form examples Yup → Zod + cleanup PoC/smoke
+
+  Completa a migração end-to-end Formik+Yup → RHF+Zod no website:
+
+  **6 example files migrados:**
+  - `website/src/examples/Components/Form/Form/index.tsx` — `BasicFormExample`, `FormExample` (15 fields), `DynamicFormExample` (8 fields + conditional).
+  - `website/src/examples/Components/Form/Field/index.tsx` — `FieldFormExample` (UploadCard).
+  - `website/src/examples/Components/Form/Inputs/Input/index.tsx` — `InputFormExample`.
+  - `website/src/examples/Components/Form/Inputs/InputDate/index.tsx` — `InputDateFormExample`.
+  - `website/src/examples/Components/Form/Inputs/InputMask/index.tsx` — `InputMaskDateExample`.
+  - `website/src/examples/Components/Form/Inputs/InputSelect/index.tsx` — `InputSelectExampleButton`.
+
+  **Mapping aplicado** (consistente com MIGRATION-v4.md ADR-007 §S5):
+
+  | Yup pattern                                                               | Zod v4 equivalent                                                                            |
+  | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+  | `Yup.string().required('msg')`                                            | `z.string().min(1, 'msg')`                                                                   |
+  | `Yup.string().email('m1').required('m2')`                                 | `z.email('m1')` (top-level v4)                                                               |
+  | `Yup.boolean().required('msg')`                                           | `z.boolean()` (matches Yup loose `.required` semantics)                                      |
+  | `Yup.number().required('msg')`                                            | `z.coerce.number()` (HTML inputs return string)                                              |
+  | `Yup.mixed().test('hasFile', 'm', fn)`                                    | `z.unknown().refine(fn, { message: 'm' })`                                                   |
+  | `Yup.mixed().test(date).required()`                                       | `z.string().min(1, 'Required').refine(dateValid, { message: 'm' })`                          |
+  | `Yup.string().required()` on InputSelect/FieldGroup (object/array stores) | `z.unknown().refine((v) => !!v, { message: 'Required' })` (preserve Yup permissive coercion) |
+
+  **Cleanup:**
+  - ❌ `website/src/examples/Components/Form/Form/poc-rhf-zod.tsx` — deletado (shadow-PoC obsoleto; `BasicFormExample` agora cobre o mesmo pattern via DS `<Form>` migrado).
+  - ❌ `website/pages/docs/smoke-form-poc-rhf-zod.mdx` — deletado (instrumentação S1).
+  - ❌ `website/pages/docs/smoke-form-basic-formik.mdx` — deletado (instrumentação S1).
+
+  **Bundle re-measurement (Next.js First Load JS):**
+
+  | Page           | Pre-S0 (Formik+Yup) | Post-S3 (RHF+Zod) |             Δ |
+  | -------------- | ------------------: | ----------------: | ------------: |
+  | `form-basic`   |              417 kB |            422 kB | +5 kB / +1.2% |
+  | `form-dynamic` |              417 kB |            422 kB | +5 kB / +1.2% |
+  | `form-form`    |              417 kB |            422 kB | +5 kB / +1.2% |
+
+  **Δ NEGATIVO vs ADR-007 target** (≥15% redução; alvo 21%). Análise honesta:
+  - Zod v4 com features atuais (`z.email`, `z.coerce`, `z.refine`, `z.string().min`) ship mais bytes que o subset de Yup usado previamente.
+  - Formik (~13kB) → RHF (~10kB) shrink ~3kB.
+  - Yup (~15kB) → Zod (~15-18kB) wash or slight growth.
+  - Net: bundle parity, com leve growth devido a Zod ser mais "feature-rich" em runtime.
+
+  **Benefícios do migration (realizados, independente do bundle):**
+  - ✅ Ecosystem alignment 2024-2026+: RHF + Zod dominantes em TS-first stacks.
+  - ✅ TypeScript SSOT via `z.infer<typeof schema>` (Yup exigia tipo manual `Values<T>`).
+  - ✅ Future-proofing: Formik+Yup com manutenção decrescente, React 19/20 risk.
+  - ✅ Vendor isolation paga: refactor cirúrgico em 4 arquivos core + 6 examples.
+  - ✅ Apollion como gold-standard do ecosystem mantém alinhamento com mercado.
+
+  **Acceptance Criteria ADR-007:**
+  - ✅ 0 imports diretos de `formik`/`yup` em `packages/core/src/**` e `website/src/**` (fora dos vendors).
+  - ✅ 0 imports diretos de `react-hook-form`/`zod`/`@hookform/resolvers/zod` em core fora de `vendors/`.
+  - ⚠️ Bundle delta target ≥15%: **NÃO atingido** (medição real: +1.2% growth). Documentado como finding honesto. Justificativa do migration permanece válida (ecosystem + maintenance + TS).
+  - ✅ `yarn validate` verde nos 4 workspaces.
+  - ✅ 317 tests passed (1 skipped pre-existente), 59 snapshots OK.
+
+  Vendors `vendors/Formik/` + `vendors/Yup/` permanecem sem uso interno até S6 hard cut em v4.0.0.
+
+  Ver `packages/core/docs/adr/ADR-007-form-stack-rhf-zod.md` §6 Slice 3.
+
+- c57c548: docs(core): ADR-007 S4+S5 — README sweep + MIGRATION-v4.md draft
+
+  **S4 — README + AI docs sweep (12 arquivos):**
+
+  MDX docs (4):
+  - `form/Form/README.mdx` — exemplos Yup → Zod v4 idiomatic.
+  - `form/Field/README.mdx` — exemplos Yup → Zod; "(Formik)" → "(RHF + Zod)".
+  - `form/InputDate/README.mdx` — `Yup.mixed().test(date)` → `z.string().min(1).refine(date)`.
+  - `form/InputMask/README.mdx` — mesma migration de date validator.
+
+  AI docs (8):
+  - `form/Form/README.AI.md` — reescrita full (purpose, props table com `mode`,
+    examples Zod, do-not section atualizada).
+  - `form/Field/README.AI.md` — referências "Formik" → "RHF + Zod"; exemplo
+    inside-form com Zod.
+  - `form/Checkbox/README.AI.md`, `form/InputCurrency/README.AI.md`,
+    `form/InputDate/README.AI.md`, `form/InputMask/README.AI.md`,
+    `form/InputRange/README.AI.md`, `form/InputSelect/README.AI.md`,
+    `form/TextArea/README.AI.md` — `<related>` section "Form orquestra
+    validação Yup" → "Zod"; exemplos Yup migrados onde presentes.
+
+  **DEPRECATED headers nos vendors antigos:**
+  - `vendors/Formik/README.md` — ⚠️ DEPRECATED header apontando ReactHookForm
+    - ADR-007 §S6.
+  - `vendors/Yup/README.md` — ⚠️ DEPRECATED header apontando Zod + ADR-007 §S6.
+
+  **S5 — MIGRATION-v4.md draft:**
+
+  Cria `packages/core/MIGRATION-v4.md` com seção "Form stack migration"
+  cobrindo:
+  - §1 Resumo do impacto (7 surfaces com migration cost por linha).
+  - §2 Mapping Yup → Zod v4 (cheat sheet com 20+ patterns).
+  - §3 `validateOnChange`/`validateOnBlur` → `mode` (com diff blocks).
+  - §4 `onError` callback shape (FormikErrors → FieldErrors).
+  - §5 `handleSubmit` second arg (FormikHelpers → UseFormReturn method map).
+  - §6 Ref imperativa (FormikProps → UseFormReturn).
+  - §7 Type inference (`z.infer<typeof schema>` SSOT vs `Values<T>` manual).
+  - §8 Migration steps consumer-side (7 passos).
+  - §9 Bundle delta esperado (medição real + análise honesta).
+  - §10 Refs (ADR-007, ADR-004, Zod v4 changelog, RHF docs).
+
+  Status DRAFT — finalizado no merge final do épico v4.0.0.
+
+  **ADR-007 status atualizado:** S0-S5 marcados ✅; S6 (hard cut) ⏳ gated pelo
+  épico v4.0.0 (ADR-006). Acceptance criteria atualizado com checkboxes
+  reais; finding de bundle delta documentado honestamente (NÃO atingido
+  target; justificativa migration permanece válida).
+
+  Vendors `Formik`/`Yup` permanecem (sem uso interno) até S6 hard cut.
+
+  Ver `packages/core/docs/adr/ADR-007-form-stack-rhf-zod.md` §6 Slice 4 + 5
+  - §10 Acceptance Criteria atualizado.
+
+- e55019a: chore(security): bump Storybook 8.6.9 → 8.6.18 + force `uuid` to 11.1.1
+
+  DevDeps-only — no consumer-facing API change. Closes three security
+  advisories surfaced by `yarn audit-dependencies` (after the audit pipeline
+  itself was migrated off the broken `audit-ci@7.1.0` Yarn Berry handler in
+  the same cycle):
+  - **High** — Storybook manager bundle env-var exposure during build
+    (GHSA-8452-54wp-rmv6, fixed in `storybook >=8.6.15`).
+  - **High** — Storybook Dev Server WebSocket Hijacking
+    (GHSA-mjf5-7g4m-gx5w, fixed in `storybook >=8.6.17`).
+  - **Moderate** — `uuid` missing buffer bounds check in v3/v5/v6
+    (GHSA-w5hq-g745-h8pq, fixed in `uuid >=11.1.1`). Forced via root
+    `resolutions` since `@storybook/addon-actions` + `jest-junit` would
+    otherwise keep transitive `uuid@8.3.2` / `uuid@9.0.1`.
+
+  Verified:
+  - `yarn install` clean.
+  - `yarn workspace @apollion-dsi/core build-storybook` succeeds.
+  - Visual regression suite (chromium, 133/133) idempotent — matches the
+    pre-push hook default.
+  - `yarn audit-dependencies` no longer reports any of the three
+    advisories above.
+
+- 51f71f6: fix(core): emit `.d.ts` for every subpath entry (v4 build follow-up)
+
+  `packages/core/tsconfig.json` used `files: ["src/index.ts"]` as its only
+  entry point. After ADR-006 §3.7 E7 emptied the root barrel in v4.0.0,
+  that entry walks to nothing — `tsc --emitDeclarationOnly` produced a
+  single `lib/index.d.ts` while `esbuild` emitted 217 `.esm.js` files for
+  every subpath barrel discovered via `findEntryPoints`. Consumers
+  importing `@apollion-dsi/core/themes/colors`, `@apollion-dsi/core/elements/
+button`, etc. got runtime JS but `any`-typed modules — which only became
+  visible when `@apollion-dsi/tokens` validate started failing with TS7016
+  "Could not find a declaration file" against the published subpaths.
+
+  The same bug also reduced `yarn check-types` to a near no-op: since
+  `src/index.ts` no longer imported anything, `tsc --noEmit` only checked
+  that one file and silently ignored real type errors in the remaining 200+
+  modules of the source tree.
+
+  Switches the config to `include: ["src/**/*"]` with explicit excludes for
+  test files (`*.test.{ts,tsx}`, `__tests__/**`) and Storybook stories
+  (`story.{ts,tsx}`, `__stories__/**`) — neither of which should ship type
+  declarations. Post-fix:
+  - `lib/` carries 430 `.d.ts` files (covering all 217 ESM entries plus
+    pure-type interface files), matching the surface declared in
+    `package.json#exports`.
+  - `lib/vendors/StyledComponents/` ships `.d.ts` only (`component.d.ts`,
+    `interface.d.ts`, `index.d.ts`) — `scripts/check-vendors-not-published.js`
+    remains green (the script only forbids `.js` under `lib/vendors/`).
+  - `yarn check-types` now type-checks the entire `src/**` tree.
+  - No new TypeScript errors surfaced — the existing source tree was
+    internally consistent; it just wasn't being checked.
+
+  Pure build-config fix. No runtime change, no public API change. Patch
+  bump.
+
+- 0a1baeb: chore(core): coverage re-baseline — exclude boilerplate, honest floors
+
+  Apply coverage exclusions em `packages/core/jest.config.js` +
+  `packages/relay/jest.config.js` para boilerplate sem business logic
+  testável:
+  - `/vendors/` — wrappers re-export-only (re-exports a 100% statements
+    - 0-50% functions noise via IIFE wrappers ts-jest).
+  - `*.story.tsx` — Storybook stories (visual coverage via visual-gate).
+  - `*.interface.ts` — type-only files (compile a empty JS = 100% padding).
+  - `*.style.ts` — styled-components (testados via component renders).
+  - `/index.ts` (barrels) — re-exports puros.
+
+  **Impact:** revela coverage real do código com lógica testável.
+
+  | Métrica core | Pre-exclusões | Post-exclusões |       Δ |
+  | ------------ | ------------: | -------------: | ------: |
+  | Statements   |         69.8% |         61.75% | -8.05pp |
+  | Branches     |        50.63% |         50.74% | +0.11pp |
+  | Functions    |         56.2% |         48.25% | -7.95pp |
+  | Lines        |        69.41% |          62.3% | -7.11pp |
+
+  Drop em statements/functions/lines reflete REMOÇÃO de files inflados
+  (re-exports a 100%, types a 100%) — não regressão real. Branches estável
+  porque excluídos não tinham branches significativos.
+
+  **Thresholds rebaselined** (core/jest.config.js):
+  - `branches`: 48 → 50 (sobe acompanhando actuals)
+  - `functions`: 53 → 47 (cai — honest baseline)
+  - `lines`: 67 → 61
+  - `statements`: 68 → 60
+
+  Buffer ~1-2pp do actuals real. Relay thresholds unchanged (actuals
+  post-exclusion ainda passam).
+
+  **Path para 80% goal** (adoption-readiness, decisão @fedbalves 2026-05-27):
+
+  Top gaps onde testes reais teriam impacto:
+  - `hooks/*` — useDrag/useClipboard/useScript/useProgress/useIntersect/
+    useFileDialog todos <30% statements.
+  - `form/UploadCard` (21%), `form/InputSelect` (51%), `form/InputRange` (55%).
+  - `entities/*` (32%).
+  - `containers/Scroll` (63%).
+  - `elements/Svg` (38%), `elements/Label` (52%).
+
+  Ratchet path: +5pp incremental atrás de feature work TDD-vertical (per
+  strategy original do ROADMAP).
+
+  Ver `docs/ROADMAP.md` §🟡 Next "Coverage ratchet to 80%" — entrada
+  atualizada com baseline honesta + path detalhado.
+
+- 6d1371e: docs: factual drift sweep + AI-friendly doc surface
+
+  Sincroniza documentação com estado de `main` pós-v3.x (ADR-002 +
+  ADR-004 shipped, ADR-005 escrito) e introduz camada AI-readable
+  (`README.AI.md`, `AGENTS.md`, `llms.txt` por sub-package).
+
+  **Drift corrigido (BLOCKER):**
+  - Root README + core README: Storybook `9` → `8.x` (real: 8.6.9).
+  - ROADMAP: ADR-005 "placeholder/não escrita" → "Proposed" linkando ao
+    arquivo já existente.
+  - `website/README.md`: era boilerplate de Docusaurus 2 — substituído
+    por descrição real (Next 15 + Nextra 2 + copyStorybook).
+  - `website/pages/index.mdx`: remove `npm install` (yarn-only) e
+    amplia scope para citar 3-layer theme + vendor isolation.
+  - `packages/scripts/README.MD`: rebrand de `@captalys-platform/scripts`
+    → `@apollion-dsi/scripts`; atualiza stack (webpack 5, Babel 7,
+    Jest 30, TS 6); remove `.editorconfig.js`.
+
+  **Novas concept pages no website (IMPORTANT):**
+  - `concept-semantic-tokens.mdx` — explica Foundation/Semantic/Structural
+    (ADR-002).
+  - `concept-surface-inversion.mdx` — `surface="negative"` + limitação
+    mode-agnostic (ADR-002 S4 / refinada em ADR-006).
+  - `concept-vendor-policy.mdx` — política de vendor isolation pública
+    (ADR-004).
+
+  Source canônica em `packages/core/concept/`; thin re-exports em
+  `website/pages/docs/`; entradas em `_meta.json`.
+
+  **AI-friendly doc layer:**
+  - Raiz `README.AI.md` — navegação + decision tree + ADR matrix.
+  - Raiz `AGENTS.md` — contrato operacional p/ agentes (hard rules,
+    per-component checklist, skill triggers).
+  - `packages/eslint-config/llms.txt`, `packages/relay/llms.txt`,
+    `packages/scripts/llms.txt` — indexação token-otimizada por package
+    (espelhando o padrão já em `packages/core/llms.txt`).
+
+  Doc-only. Sem mudança de API/código. Patch bump em todos os
+  publishable packages para sincronizar versões.
+
+- e55019a: chore(security): close 7 pre-existing CVEs revealed by audit-dependencies fix
+
+  Follow-up to the `audit-ci@7.1.0` → `yarn npm audit` migration earlier in
+  this cycle. The native audit pipeline surfaced 7 vulnerabilities that the
+  broken handler had been printing as `undefined` and never failing on.
+  All closed in this changeset. `yarn audit-dependencies` → 0 findings.
+
+  | #   | CVE                 | Pkg              | Severity | Strategy                                                                                                            |
+  | --- | ------------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
+  | 1   | GHSA-3xgq-45jj-v275 | `cross-spawn`    | High     | Root resolution `cross-spawn: ^7.0.6` (was transitive 5.1.0 via `execa@0.8.0` → `clipboardy` → `title` → `nextra`). |
+  | 2   | GHSA-qjx8-664m-686j | `js-cookie`      | High     | Direct upgrade in `packages/relay`: `3.0.5` → `3.0.7`.                                                              |
+  | 3   | GHSA-37ch-88jc-xwx2 | `path-to-regexp` | High     | Direct upgrade in `packages/relay`: `express 4.21.2` → `4.22.2` (express 4.22 ships path-to-regexp 0.1.13).         |
+  | 4   | GHSA-7mvr-c777-76hp | `playwright`     | High     | Direct upgrade in `packages/core`: `@playwright/test 1.49.1` → `1.60.0`.                                            |
+  | 5   | GHSA-qx2v-qp2m-jg93 | `postcss`        | Moderate | Root resolution `postcss: ^8.5.10` (Next 15 pinned 8.4.31; css-loader already uses 8.5.15).                         |
+  | 6   | GHSA-6rw7-vpxm-498p | `qs`             | Moderate | Closed by item 3 (express 4.22.2 bundles body-parser 1.20.5 → qs 6.15.2).                                           |
+  | 7   | GHSA-q8mj-m7cp-5q26 | `qs`             | Moderate | Closed by item 3 (same).                                                                                            |
+
+  **Verified post-remediation:**
+  - `corepack yarn audit-dependencies` → exit 0, no audit suggestions.
+  - `corepack yarn workspace @apollion-dsi/core run validate` → green (types + prettier + lint + tests + build + check-vendors-not-published + visual gate). Visual regression suite chromium **133/133 passing** with `@playwright/test@1.60.0` — no baseline drift from the playwright bump.
+  - `corepack yarn workspace @apollion-dsi/relay run validate` → green (3 test suites / 11 tests / 0 failures).
+  - `corepack yarn workspace @apollion-dsi/website run build` → green.
+
+  **Exploit-surface notes:**
+  - Express, body-parser, qs, path-to-regexp are all in `@apollion-dsi/relay#devDependencies` (test fixtures for the GraphQL relay environment) — realistic exploit surface was zero. Upgraded anyway because the fix was free.
+  - Playwright cert verification (item 4) only matters during `npx playwright install` — also low exploit surface in a single-machine setup, but upgrading was free.
+  - cross-spawn ReDoS reachable only during `nextra` doc generation, dev-only.
+
+- 29081ae: chore(visual): regenerate firefox + webkit baselines (post ADR-006 OKLch)
+
+  DevDeps-only — no consumer-facing API change. Refreshes the 124 stale
+  firefox + webkit baselines that drifted after `d57c47c feat(v4-s2): OKLch
+lerp via culori` updated only chromium baselines (the pre-push hook is
+  chromium-only, so firefox + webkit drift went unnoticed). Restores the
+  multi-browser net at 399/399 green and idempotent on darwin-arm64.
+  - **Median diff absorbed:** 0.53 %; **max:** 10.35 % on
+    `Layouts/SideBarLayout › Default` firefox — `primary.dark` shifted from
+    `rgb(20, 70, 88)` (pre-OKLch RGB lerp) to `rgb(7, 46, 60)` (OKLch lerp).
+    Same code, new perceptually-uniform color math.
+  - **Net-new baselines:** `Components/Button › AllDimensions` and
+    `Components/Card › AllDimensions` firefox + webkit captured for the first
+    time (story count 131 → 133).
+  - **PER_STORY_THRESHOLD escalations** (firefox skeleton shimmer sub-pixel
+    drift — pre-existing class documented in `__image_snapshots__/AUDIT.md`):
+    - `components-textpreset--default`: 0.5 % (re-emergence of the S2 entry,
+      handled per AUDIT's predicted path).
+    - `components-scenario-rect--default`: 1 % (new entry — same root cause).
+
+  Verified:
+  - `VISUAL_BROWSERS="chromium firefox webkit" yarn workspace @apollion-dsi/core run test-storybook`
+    is 399/399 green on two consecutive fresh runs (~80 s each, no `-u`).
+  - Pre-push hook (chromium-only) behavior unchanged — closes the same gate.
+  - SHA-256 of regenerated PNGs differs from `HEAD` (real pixel updates, not
+    no-op mtime touches).