@godxjp/ui 31.31.8 → 32.0.0

package/docs/roadmap/badge-tag-chip-count.md

@@ -1,172 +0,0 @@
-# Badge / Tag / Chip / Pill / Count — audit + normalized spec
-
-> **Canonical taxonomy:** <https://namethatui.com/web/badge-chip-pill?part=badge-count>
-> **Capability reference:** Ant Design `Badge` + `Tag` (never their prop spellings where they
-> conflict with `docs/PROPS-VOCABULARY.md`).
-> **Contract:** `.claude/skills/godxjp-ui-component/SKILL.md` is the hard gate.
-
-## 1. The canonical taxonomy — five different things, routinely confused
-
-| Term | Canonical definition | Interactive? |
-| --- | --- | --- |
-| **Badge** | A tiny count or status marker **attached to another object**. Parts: the *badge anchor* (the icon/avatar it attaches to) and the *badge count* (the number in the bubble). | No |
-| **Tag** | Non-interactive **category metadata** on a card or row. | No |
-| **Pill** | A **shape**, not a component — a capsule-shaped status label. | No |
-| **Chip** | A compact **interactive token** that can be selected, edited or removed. Parts: a *remove button* (a real `<button>` with an `aria-label`) and a *selected state* (`aria-pressed`). | Yes |
-| **Label** | The text naming a form field (`<label for>`). | No |
-
-## 2. What the library actually has, mapped onto that taxonomy
-
-| Repo component | What it really is | Verdict |
-| --- | --- | --- |
-| `Badge` (`src/components/data-display/badge.tsx`) | A **Tag / Pill** — a standalone non-interactive chip with `variant` (structure), `tone` (meaning), `color` (data), `shape`, `status`→tone+icon+i18n. Nothing is attached to an anchor and there is no count. | **Misnamed, but keep the name** — see §5. Capability-wise it is *richer* than Ant's `Tag` (the `color` wash carries a real WCAG argument: 8.52:1 worst case across the sRGB cube). |
-| `Toggle` / `ToggleGroupItem` | The **selectable Chip** — `pressed`/`onPressedChange` (= `aria-pressed`) plus the `count`/`overflowCount`/`showZero`/`countLabel` counter-pill vocabulary. Its own catalog entry already says a faceted filter chip ("Open 42") and a reaction chip are this, and explicitly forbids nesting a `Badge` inside it. | **Already correct.** Do **not** build a second selectable chip. |
-| `TagInput` | The **chip field** — Ant-aligned (`tagRender`, `status`, `readOnly`, overflow, Backspace-removes-last). Its removable chips are **private markup** (`.ui-tag-input-chip` + a `<button aria-label>`). | Chip rendering is trapped inside it — see §4.2. |
-| `Label` | A real `<label>` on `react-aria-components`. | **Correct.** Not part of this family. |
-| `Button` | Also carries `count`/`overflowCount`/`showZero`/`countLabel`. | Source of the count vocabulary to reuse. |
-
-## 3. The gap — what Ant Design has and this library does not
-
-Verified: `count` / `overflowCount` appear **only** in `Button`, `Toggle`, `ToggleGroup` and their
-props. `Badge` has no `count` at all, and nothing anywhere renders a bubble attached to a child.
-
-| Ant Design | Missing here | Consequence today |
-| --- | --- | --- |
-| antd `Badge` with `count` wrapping an `Avatar` — the count bubble on an anchor | **Entirely** | No way to put an unread count on an avatar, a nav icon, a Topbar bell or a tab. `Sidebar`/`NavList` take a `badge` prop, but that renders the Tag-style pill *inline*, not an attached marker. |
-| antd `Badge` with `dot` — the bare dot marker | **Entirely** | No "there is something new" affordance. |
-| `overflowCount` → `99+` on a marker | **Entirely** | (The cap exists on `Button`/`Toggle`; it never reaches a marker.) |
-| `<Tag closable onClose>` — the removable chip | **Not public** | Only exists privately inside `TagInput`; a filter-summary row or a recipient list has to hand-roll a ✕ button, which is how `aria-label`-less removers get shipped. |
-| `<Badge.Ribbon>` | Entirely | Composition — see §4.4. |
-| `<CheckableTag>` | — | **Already covered by `Toggle`.** No action. |
-
-## 4. The fix — one new component, one extension, two documentation fixes
-
-This deliberately adds the **minimum**. Three of the five gaps close by extending what exists;
-building a `Chip` component would duplicate `Toggle` and is an instant reject.
-
-### 4.1 NEW — `CountBadge` (group: `data-display`)
-
-The attached count/status marker. Ant's `Badge`; NameThatUI's *badge* proper.
-
-**GATE 0 ledger**
-
-| # | Criterion | Verdict | Why |
-| --- | --- | --- | --- |
-| C1 | Universal | **PASS** | Unread counts on avatars, nav icons, bells, tabs, inbox rows — every app. |
-| C2 | Reusable behavior | **PASS** | Overflow capping, zero suppression, dot mode, anchor-relative placement that survives RTL, and folding the count into the anchor's accessible name / announcing changes politely. |
-| C3 | Not composable | **PASS** | Requires an absolutely-positioned marker measured against an arbitrary child plus a live-region contract. A `Badge` in a `<div className="relative">` is exactly the hand-rolled version this replaces. |
-| C4 | Single responsibility + vocabulary | **PASS** | One job; reuses the count vocabulary already defined by `Button`. |
-| C5 | Token-themeable | **PASS** | Size, offset, surface, ring are `--count-badge-*` tokens. |
-| C6 | Earns the i18n/a11y contract | **PASS** | `Intl.NumberFormat` for the number *and* the cap (vi renders `1.000+`), and the count must be announced, not merely drawn. |
-| C7 | Earns bundle cost | **PASS** | Used by nav chrome in every consumer. |
-
-**ALL PASS → framework component.**
-
-**API — reuse the EXISTING count vocabulary verbatim.** `Button` and `Toggle` already define
-`count` / `overflowCount` / `showZero` / `countLabel`. Do not invent a second spelling; a third
-dialect of the same idea is the defect this repo keeps fixing.
-
-| Ant Design | **godx `CountBadge`** |
-| --- | --- |
-| `count` | `count: number` |
-| `overflowCount` | `overflowCount: number` (default `99`) |
-| `showZero` | `showZero: boolean` (default `false`) |
-| `dot` | `dot: boolean` — a marker with no number |
-| `children` | `children` — the **anchor**; omit it for a standalone inline marker |
-| `status` + `text` | *dropped* — that is `Badge status=…`, which already exists |
-| `color` | `tone` (semantic) — the free-form data colour stays `Badge`'s job |
-| `offset` | *dropped* — placement is `placement` + tokens, never a caller-supplied pixel pair |
-| `size: 'default' \| 'small'` | `size: 'xs' \| 'sm' \| 'md' \| 'lg'` (never `"default"`) |
-| `title` | `countLabel` — same name `Button` uses |
-| — | `placement: 'start' \| 'end'` (logical; flips under RTL) |
-
-**Required semantics**
-- The number and the cap both go through `Intl.NumberFormat` on the active locale — never
-  `String(n)`, never a hand-rolled thousands separator. Above the cap render `{overflowCount}+`.
-- `count={0}` renders nothing unless `showZero`.
-- The marker is **not** an accessible name of its own floating next to the anchor: fold it into the
-  anchor's name via a visually-hidden text node (`t()`-driven, e.g. "Notifications, 5 unread"), or
-  expose `countLabel`. A bare "5" read out of context is a bug.
-- A changing count updates a single `aria-live="polite"` region — not one per marker.
-- `dot` mode still needs a text alternative; **never colour-or-shape-only** (WCAG 1.4.1).
-- Placement uses logical offsets (`inset-inline-end`), so it flips under `dir="rtl"`.
-- The marker must not clip: it overflows the anchor box deliberately, and the anchor keeps its own
-  hit area ≥24×24px (WCAG 2.5.8).
-
-**Tokens** — `src/tokens/components/count-badge.css`, `@import`ed from `src/tokens/base.css`,
-names passing `check:token-tiers`: `--count-badge-size`, `--count-badge-dot-size`,
-`--count-badge-inset-block`, `--count-badge-inset-inline`, `--count-badge-background`,
-`--count-badge-foreground`, `--count-badge-ring-color`, `--count-badge-ring-width`,
-`--count-badge-font-size`. No literal heights.
-
-**i18n** — `countBadge.unreadCount` (a CLDR `{one, other}` plural selected by `Intl.PluralRules`,
-in en/vi/ja), `countBadge.new` for `dot`.
-
-### 4.2 EXTEND — `Badge` gains `onRemove` (this *is* the removable Chip)
-
-Rather than a new `Chip` component that would collide with `Toggle`:
-
-- Add `onRemove?: () => void` and `removeLabel?: string` to `Badge`. When `onRemove` is present the
-  badge renders a trailing `<button type="button">` with a `t()`-driven `aria-label` naming the
-  item it removes ("Remove {tag}"), a ≥24×24px target, and `Backspace`/`Delete` support when the
-  badge itself is focused. `Badge` renders a `<div>`/`<span>`, so this is **not** a button-in-button.
-- Then **fix it upstream, not at the call site**: refactor `TagInput` to render its chips as
-  `Badge onRemove=…` instead of the private `.ui-tag-input-chip` markup, so there is exactly one
-  removable-chip implementation and one remover `aria-label` in the system. `TagInput`'s public API
-  and its existing tests must not change — prove it by running them.
-- Selection is **not** added to `Badge`. A selectable chip is `Toggle` (`pressed` + `count`), and
-  the catalog must keep saying so.
-
-### 4.3 DOCUMENT — the routing rules, so consumers stop guessing
-
-The real reason this family "doesn't look like Ant Design" is that the map is unwritten. Add to
-`mcp/src/data/components.ts`, on **both** sides of each pair (a one-sided claim is the mistake
-commit `8365bf05` fixed):
-
-- `Badge` tagline: state that in the canonical taxonomy this is the **Tag / Pill** — non-interactive
-  category or status metadata — and that a count marker attached to an anchor is `CountBadge`.
-- `Badge.related`: → `CountBadge` (counts on an anchor), `Toggle` (selectable chip),
-  `TagInput` (an editable set of chips), `Label` (naming a form field).
-- `CountBadge.related`: → `Badge`, `Toggle`, `Sidebar`/`NavList` `badge` props.
-- New rules: *DON'T hand-roll a `<span>` counter or an absolutely positioned `Badge` to mark an
-  anchor — use `CountBadge`.* *DON'T nest a `Badge` inside a `Toggle` for a count — `Toggle` owns
-  `count`.* *DON'T build a selectable chip out of `Badge` + `onClick` — use `Toggle`.*
-
-### 4.4 COMPOSITION — not framework components
-
-- **Ribbon** (Ant `Badge.Ribbon`): C2 and C3 fail — it is a `Card` plus an absolutely positioned
-  `Badge` plus a corner token. Ship it as a `docs/` showcase, never in `src/components/`.
-- **Status dot + text** (Ant `Badge status text`): already `Badge status=…`, which maps the key to
-  tone + icon + an i18n label. No new API.
-
-## 5. Explicitly NOT doing: renaming `Badge`
-
-`Badge` is used across the entire library and every consumer. Renaming it to `Tag` to satisfy the
-taxonomy would be a breaking change that buys nothing a catalog tagline cannot. **Keep the name;
-document the meaning.** No agent may rename, alias or deprecate `Badge` under this work.
-
-## 6. Definition of done
-
-1. `src/components/data-display/count-badge.tsx`, exported from that group's `index.ts`
-2. `CountBadgeProp` (+ `as CountBadgeProps`) in `src/props/components/data-display.prop.ts`,
-   **registered in `src/props/registry.ts`**; `Badge`'s `onRemove`/`removeLabel` added to its prop type
-3. `src/tokens/components/count-badge.css` + `@import` in `src/tokens/base.css`
-4. i18n keys in **all three** of `en.json`, `vi.json`, `ja.json`
-5. Tests in `src/components/data-display/__tests__/`: `count-badge.test.tsx` (Intl formatting in
-   en/vi/ja, cap → `99+`, `showZero`, `dot`, RTL placement, live-region announcement, accessible
-   name folding), `badge-remove.test.tsx` (remove button name, keyboard, ≥24px), and
-   `count-badge.a11y.test.tsx` at **0 axe violations**
-6. `mcp/src/data/components.ts`: a `CountBadge` entry, `Badge`'s new props, and the §4.3 routing
-   rules on both sides
-7. A real-screen docs page `docs/data-display/count-badge.tsx`
-8. `TagInput` refactored onto `Badge onRemove`, with its existing tests still green
-
-Gates, then only the touched test files:
-
-```
-pnpm typecheck && pnpm lint && pnpm run audit \
-  && pnpm check:prop-vocabulary && pnpm check:mcp-sync && pnpm check:mcp-orphans \
-  && pnpm check:token-tiers && pnpm check:control-sizing && pnpm check:example-imports
-```
-
-`pnpm test` and a bare `pnpm vitest run` are **forbidden** — the full suite is CI's job.

package/docs/roadmap/list-masonry.md

@@ -1,159 +0,0 @@
-# `List` (Ant `Listy`) + `Masonry` — normalized spec
-
-> **Capability reference:** <https://ant.design/components/listy> and
-> <https://ant.design/components/masonry>. **Canonical definition:**
-> <https://namethatui.com/web/masonry>.
-> **Contract:** `.claude/skills/godxjp-ui-component/SKILL.md`.
-
-Measured facts this spec rests on: the library has **no virtualization anywhere**
-(no `react-window` / `@tanstack/react-virtual` / any `virtual` code path in `src/`), and **no
-masonry** (every `grid-template-columns` in `src/styles/` is a fixed uniform grid; `ResponsiveGrid`
-is a uniform-row card grid). Both are genuine holes, not restyling jobs.
-
----
-
-## 1. `List` — port of Ant Design `Listy` (group: `data-display`)
-
-Ant's old `List` is **deprecated** and `Listy` replaces it. Port `Listy`, not `List`: it is the
-narrower, performance-shaped component (virtual scrolling + grouping), which is exactly the part
-that cannot be composed here.
-
-### GATE 0 ledger
-
-| # | Criterion | Verdict | Why |
-| --- | --- | --- | --- |
-| C1 | Universal | **PASS** | Long feeds, activity streams, message lists, pickers, log views. |
-| C2 | Reusable behavior | **PASS** | Windowed rendering, measured row heights, sticky group headers, an imperative `scrollTo` that resolves an item key or a group key to an offset. |
-| C3 | Not composable | **PASS** | Nothing in the library virtualizes. `ScrollArea` + `.map()` renders every row. |
-| C4 | Single responsibility + vocabulary | **PASS** | One job; maps onto `items` / `getRowId` / `size`. |
-| C5 | Token-themeable | **PASS** | Row height, group-header surface, divider are `--list-*` tokens. |
-| C6 | Earns the contract | **PASS** | A virtual list is where `role`/`aria-setsize`/`aria-posinset` are *mandatory* — the DOM no longer contains the whole set. |
-| C7 | Earns bundle cost | **PASS** | Every consumer has at least one long list. |
-
-**ALL PASS → framework component.**
-
-### API — Ant `Listy` → godx `List`
-
-| Ant `Listy` | **godx `List`** | Note |
-| --- | --- | --- |
-| `items` | `items: T[]` | |
-| `itemRender(item, index)` | `itemRender(item, index)` | |
-| `rowKey` | **`getRowId: (item: T) => string`** | The house spelling — `DataTable` already uses `getRowId`. Do not introduce `rowKey` as a second dialect. |
-| `height` | `height?: number` | Scroll container height; content scrolls past it. |
-| `virtual` | `virtual?: boolean` (default `false`) | |
-| `group: { key, title }` | `group?: { key: (item) => K; title: (key, items) => ReactNode }` | |
-| `sticky` | `sticky?: boolean` (default `false`) | Group headers stick. |
-| `onScroll` | `onScroll?: React.UIEventHandler<HTMLElement>` | |
-| `classNames` / `styles` | `classNames?: { root?; item?; groupHeader? }` | Keep the semantic-slot shape; skip the `styles` twin (inline style is not how this system themes). |
-| ref `scrollTo(config)` | ref `scrollTo(config)` | Accepts a pixel offset, `{ top }`, `{ key, align?, offset? }`, or `{ groupKey, align?, offset? }`. |
-| — | `size: 'xs' \| 'sm' \| 'md' \| 'lg'` | House requirement. |
-| — | `loading?: boolean`, `empty?: ReactNode` | Compose the real `Skeleton` / `EmptyState`; do not hand-roll either. |
-
-**Deliberately NOT ported** (and say so in the catalog entry, so nobody re-adds them): `bordered`,
-`split`, `header`, `footer`, `size: 'large'`, `pagination`, `loadMore`, `itemLayout`. `Listy`
-dropped them, and here they are already covered — the frame is `Card` + `CardContent flush`,
-dividers are `Separator`, paging is `Pagination`. Re-adding them would rebuild a second `Card`.
-
-### Required semantics
-- `role="list"` with `role="listitem"` rows; when `virtual`, every row **must** carry `aria-setsize`
-  (the full count) and `aria-posinset` — otherwise a screen reader reports the window, not the list.
-  This is the single most-skipped part of a virtual list and it is not optional.
-- Grouping renders `role="group"` with the header as its `aria-label`/`aria-labelledby`.
-- Keyboard: the scroll container is focusable; `PageUp`/`PageDown`/`Home`/`End` work. Rows are not
-  a roving-tabindex widget — interactive controls inside a row keep normal tab order.
-- `sticky` headers use `position: sticky` with logical insets and must not cover the focused row
-  (`scroll-margin-block-start`).
-- Row heights are measured, not assumed; a row whose content grows must not desynchronise the
-  window. Reserve image dimensions.
-- `prefers-reduced-motion: reduce` disables any smooth-scroll in `scrollTo`.
-
-### Tokens
-`src/tokens/components/list.css` (`@import` from `src/tokens/base.css`): `--list-row-min-height`
-(from the `--control-height` tier), `--list-divider-color`,
-`--list-group-header-background`, `--list-group-header-foreground`, `--list-group-header-height`.
-
-### Spacing — the list does NOT own its inline inset
-
-Read `docs/SPACING.md` before writing a single spacing declaration. A row inside a
-`Card` + `CardContent flush` takes its inline inset from the public class **`ui-card-inset-x`**
-(which reads `--card-space-inset`), so the row lines up with the card shell and follows the card's
-`density`. **Do not invent a `--list-row-padding-inline`** — a parallel spacing knob drifts away
-from the Card that contains it, and the block axis is owned by `--list-row-min-height`.
-
-Macro rhythm is never the component's: no Tailwind `p-*` / `m-*` / `gap-*` (the audit rejects them
-as `no-utility-spacing`), no hand-rolled `flex`/`grid` (`no-utility-layout`). Vertical rhythm comes
-from `Flex gap` on the φ scale (`xs`/`sm` = 4px grid, `md` = φ⁰, `lg` = φ¹, `xl` = φ²) — this repo
-does **not** use the 8pt grid.
-
-### i18n
-`list.empty`, `list.loading`, `list.group` (group-header accessible name), and any count through
-`Intl.NumberFormat` + `Intl.PluralRules`.
-
----
-
-## 2. `Masonry` (group: `layout`)
-
-**Canonical definition** (NameThatUI): *a layout where each new item joins the shortest column,
-creating a staggered bottom edge with no row lines and cards keeping their individual heights.*
-The named part is the **packed column** — each column flows straight down, nothing lines up
-sideways. Aliases: Pinterest grid, waterfall, brick layout.
-
-### GATE 0 ledger
-
-| # | Criterion | Verdict | Why |
-| --- | --- | --- | --- |
-| C1 | Universal | **PASS** | Media galleries, card boards, dashboards with variable-height cards. |
-| C2 | Reusable behavior | **PASS** | Shortest-column packing, re-packing on resize/content change (`ResizeObserver`), and keeping DOM reading order row-major while the visual flow is column-major. Native `grid-template-rows: masonry` covers the paint but not the ordering or the fallback. |
-| C3 | Not composable | **PASS** | `ResponsiveGrid` is a uniform grid; nothing packs by column height. |
-| C4 | Single responsibility + vocabulary | **PASS** | One job; `columns`/`gap` reuse `ResponsiveGrid`'s exact spellings. |
-| C5 | Token-themeable | **PASS** | Gaps come from the spacing scale. |
-| C6 | Earns the contract | **PASS** | Reading order vs visual order is an accessibility decision, not a style one. |
-| C7 | Earns bundle cost | **PASS** | Small; broadly useful. |
-
-**ALL PASS → framework component.**
-
-### API — Ant `Masonry` → godx `Masonry`
-
-| Ant Design | **godx `Masonry`** | Note |
-| --- | --- | --- |
-| `columns: number \| { xs, sm, md }` | `columns: number \| { base?, sm?, md?, lg? }` (default `3`) | **Use `ResponsiveGrid`'s existing breakpoint shape** (`base/sm/md/lg`), not antd's `xs/…/xxl`. One breakpoint dialect in this library. |
-| `gutter: Gap \| [Gap, Gap]` | `gap: 'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` (default `'md'`) | Token scale, exactly as `ResponsiveGrid`. A caller-supplied pixel pair is not how this system spaces. |
-| `items: MasonryItem[]` | `items: MasonryItemProp[]` — `{ key, children?, data?, column? }` | Drop antd's `height`: heights are measured, never declared. |
-| `itemRender(item)` | `itemRender(item, index)` | `item.children` still wins. |
-| `fresh` | `observeItems?: boolean` (default `true`) | Keep watching child sizes via `ResizeObserver`; the antd name says nothing. |
-| `onLayoutChange` | `onLayoutChange?: (placements: { key: Key; column: number }[]) => void` | |
-| `classNames` / `styles` | `classNames?: { root?; item? }` | Skip the `styles` twin. |
-| — | `sequential?: boolean` | Fill columns left-to-right in order instead of shortest-first, for a strict reading order. |
-
-### Required semantics
-- **Reading order is DOM order.** Whatever the visual packing, the DOM stays in `items` order so
-  keyboard and screen-reader traversal match the source sequence. This is the reason the CSS
-  `columns` fallback alone is not acceptable — it flows column-major.
-- Prefer native `@supports (grid-template-rows: masonry)`; fall back to measured absolute/transform
-  packing. Never ship the bare `columns:` fallback as the only path.
-- The container is a plain grouping element with no invented role. If the content is a list, the
-  **caller** supplies the semantics; `Masonry` must not silently impose `role="list"`.
-- Re-pack on container resize and on item resize (`ResizeObserver`), debounced to a frame.
-- Reserve media dimensions (`AspectRatio`) so image loads do not cause layout shift — call this out
-  in the docs page.
-- Logical CSS only; column order flips under `dir="rtl"`.
-
-### Tokens
-`src/tokens/components/masonry.css`: `--masonry-gap-inline`, `--masonry-gap-block`,
-`--masonry-column-min-inline-size`.
-
----
-
-## 3. Definition of done (both)
-
-Per component: source + group `index.ts` export · `XProp` (+ `as XProps`) in the group's
-`*.prop.ts` **and `src/props/registry.ts`** · tokens file + `@import` in `src/tokens/base.css` ·
-i18n keys in **en/vi/ja** · `@testing-library/user-event` behaviour tests + a `*.a11y.test.tsx` at
-**0 axe violations** · an `mcp/src/data/components.ts` entry (including the "deliberately not
-ported" list for `List`) · a real-screen docs page.
-
-For `List`, the virtual-mode test must assert `aria-setsize`/`aria-posinset` reflect the **full**
-item count while only a window is in the DOM. For `Masonry`, a test must assert DOM order equals
-`items` order under every `columns` value.
-
-Gates, then only the touched test files. `pnpm test` and a bare `pnpm vitest run` are **forbidden**.