@godxjp/ui 20.2.0 → 21.0.0

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

@@ -0,0 +1,172 @@
+# 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

@@ -0,0 +1,159 @@
+# `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**.