@godxjp/ui 31.31.7 → 32.0.0

package/docs/roadmap/parity-backlog.md

@@ -1,77 +0,0 @@
-# Consolidated parity backlog — all three audits merged
-
-Sources: `parity-audit-data-entry.md` · `parity-audit-data-display-feedback.md` ·
-`parity-audit-layout-navigation-general.md`. Sequencing strategy is decided in
-`debate/antd-parity-scope-and-sequencing/04-Decision.md`.
-
-## The headline the audits actually produced
-
-All three groups came back **more Ant-aligned than the complaint implied**, and all three agents
-independently proposed **zero new components** for their P0/P1 rows — every one closes by widening
-an existing API. The real damage is not missing antd props. It is:
-
-1. **Two data-corruption / i18n defects that are live in shipped locales** (P0 below).
-2. **A toast surface with no owner** — the catalog tells consumers to import from `sonner` directly.
-3. **MCP catalog drift** — props that ship in `src/` but are invisible to consumers, in at least
-   10 components. This is the same failure class as commit `8365bf05`.
-
-A reference-version note that changes how future audits must run: ant.design now serves **v6**, and
-v6 has moved `fixed`, `gapPosition`, `dotPosition`, `expandIconPosition` and `Timeline.mode` to
-logical `start`/`end` — **toward the spelling this repo already uses**. Part of "doesn't look like
-Ant Design" is this library being ahead, not behind. Any future audit must pin the antd version it
-compared against, or successive waves will silently measure against different targets.
-
-## P0 — fix first, regardless of which strategy wins
-
-| #   | Defect                                                                                 | Evidence                                                                                                                                                                                                                                                  | Why P0                                                                                                |
-| --- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| 1   | **`NumberInput` corrupts values 10× in comma-decimal locales, including shipped `vi`** | formats via `Intl.NumberFormat` (`number-input.tsx:100`), parses via hardcoded `replace(/,/g,"")` (`:41`), `handleBlur` re-parses the displayed draft (`:220`). `Intl.NumberFormat("vi",{useGrouping:false}).format(1.5)` → `"1,5"` → parses back as `15` | Silent money/quantity corruption. Focus-then-blur is enough. Keep the NFKC 全角 fold — it is correct. |
-| 2   | **`Timeline` hardcodes English screen-reader status text**                             | `SR_PREFIX = {done:"Completed: ",…}` `timeline.tsx:31-35`, injected `:107`; `grep timeline src/i18n/messages/en.json` → 0 hits                                                                                                                            | A ja/vi product announces English. Violates the mandatory i18n gate.                                  |
-| 3   | **`PasswordStrength` is hardcoded English end-to-end**                                 | `password-strength.tsx:4-8,75,106,113,119-133`; never imports `useTranslation`; `labels` overrides only 3 of ~10 strings                                                                                                                                  | Same gate; and consumers cannot work around it.                                                       |
-
-## P1 — grouped by owning file, so one agent owns one group
-
-**`data-entry`** — `SearchInput` Enter does
-not commit (no `onKeyDown` in the file; `:59-63`) · `ColorPicker` has no `size`/`status`/`variant`
-and no `presets` (`data-entry.prop.ts:893-908`) · `PasswordStrength` uses `role="img"` instead of
-`role="meter"` (`:74-76`) · `Upload showUploadList` boolean-only (`:1196`) ·
-`Transfer` has no `status` (`:1413-1459`) · `Cascader` search uncapped (`cascader.tsx:389-393`) ·
-`Select` lacks `fieldNames` although `Cascader` and `TreeSelect` both have it · `NumberInput` has
-no `stringMode`.
-
-**`data-display` + `feedback`** — `Toaster` has no house API at all (`components.ts:7302` sends
-consumers to `sonner`; `position` is physical and never flips under RTL) · `Skeleton` puts
-`aria-live="polite"` on every block (`skeleton.tsx:13-14`); `SkeletonTable` mounts 40+ nested,
-unnamed live regions · `Accordion` hardcodes `<h3>` (`ui/accordion.tsx:314`) and has no `extra`
-slot · `Carousel` dots lack `aria-controls` and the arrows do not flip under RTL
-(`carousel.tsx:249-269`, `data-display-layout.css:547-580`) · `Avatar` has no `size` · `Progress`
-never displays its percentage and hand-builds `aria-valuetext` (`progress.tsx:174`) · `StatCard`
-derives delta tone from a regex on a stringified node (`card.tsx:233-246`) · `QrCode` has no
-`status`/`onRefresh` · `DataTable` lacks `virtual`, `onCell`, `column.rowScope`,
-`childrenColumnName`/`indentSize`.
-
-**`layout` + `navigation` + `general`** — `Dialog` has no `width` while `Sheet` does
-(`dialog.tsx:287-294` vs `sheet.tsx:264`), so the catalog's own example teaches the utility geometry
-`ui-audit` blocks · no `dismissible` on `Dialog`/`Sheet` (`dialog.tsx:310` hardcodes
-`isDismissable`) · `Pagination` is controlled-only, breaking the full-triad rule · `AppShell` has no
-`onSidebarCollapsedChange` and no built-in trigger (`app-shell.tsx:30`) · shell collapse breakpoint
-hardcoded (`shell-layout.css:1119`) while the overlay family's equivalent is a token · `Sidebar`
-submenu open state is unreachable local state (`sidebar.tsx:271`) · no `copyable` anywhere despite `ErrorSurface` rendering a
-`requestId` "so it can be read out or copied accurately" (`layout.prop.ts:787`) · clamped text
-cannot expand.
-
-## Cross-cutting: MCP catalog drift
-
-Props that ship but are invisible to consumers — `Select`'s `onSelect`/`onDeselect`/
-`maxTagPlaceholder` (`data-entry.prop.ts:1093,1112-1114,1124` vs `components.ts:5572-5987`), the
-entire `ResponsiveGrid.Item`/`span` API, `Pagination`'s `total`/`pageSize`, and six more. Treat as
-one work item, not ten: whatever fixes it must be a **check**, not a sweep, or it returns.
-
-## New components proposed by the audits (all deferred pending the ruling)
-
-`ButtonGroup` (GATE 0 7/7; `Dropdown.Button` then becomes a composition over it) ·
-`EditableText` (GATE 0 passes; deliberately not a `Text` prop, so IME-safe commit does not ride
-along on every `<Text>`) · `Avatar.Group` (blocked on `Avatar.size`). Rejected outright:
-`Watermark`, `Popconfirm`, `CircularProgress`, `Notification`, `Empty`, `Result`, `Spin`, `Rate`,
-`ColorSwatchPicker`, `CascaderPanel`, `Input.Search`. `Image` preview and `Tour` pass on merit but
-fail C7 (bundle cost) and are deferred with a catalog note forbidding hand-rolled lightboxes.

package/docs/roadmap/tree-components.md

@@ -1,151 +0,0 @@
-# Tree components — audit + normalized spec
-
-> **Status:** audit complete 2026-09-10. `Tree` is NOT implemented. Read this before touching
-> anything under `src/components/**/tree-*`.
-> **Contract:** `.claude/skills/godxjp-ui-component/SKILL.md` is the hard gate. This document only
-> normalizes *what* to build; the skill owns *how*.
-
-## 1. What exists today (measured, not eyeballed)
-
-| Thing | File | What it actually is |
-| --- | --- | --- |
-| `TreeSelect` | `src/components/data-entry/tree-select.tsx` (499 L) | A real tree, but only **inside a dropdown**. Ant-aligned API. |
-| `TreeList` | `src/components/data-display/tree-list.tsx` (41 L) | **Not a tree.** A flat `<ul>` where `depth` is a number that only drives `margin-inline-start`. |
-| `tree-utils` | `src/components/data-entry/tree-utils.ts` (216 L) | Normalize / flatten / filter / descendants. Sound, reusable. Currently private to `data-entry`. |
-| `Tree` | — | **Does not exist.** |
-
-### 1a. `TreeSelect` is fine — leave it alone
-
-It is genuinely modeled on Ant Design: `treeData`, `fieldNames`, `treeCheckable`, `treeCheckStrictly`,
-`showCheckedStrategy` (`SHOW_PARENT` / `SHOW_CHILD` / `SHOW_ALL`), `loadData`, `treeTitleRender`,
-`maxTagCount`, `notFoundContent`. Markup carries `role="tree"` / `role="treeitem"` with
-`aria-expanded` / `aria-selected` / `aria-multiselectable`. It is not the problem.
-
-### 1b. `TreeList` is the problem — it promises a tree and delivers indentation
-
-Verified against the source, the CSS (`src/styles/data-display-layout.css:282-334`) and its tests:
-
-| Gap | Evidence |
-| --- | --- |
-| No nested data model | `items: TreeListItem[]` only — the caller must pre-flatten; there is no `children`. |
-| No expand / collapse | No disclosure control anywhere in the component. NameThatUI calls this the **disclosure triangle**; an indented tree that expands is an **Outline View**. `TreeList` has neither. |
-| No ARIA tree semantics | Only `aria-current`. No `role="tree"` / `role="treeitem"` / `aria-expanded` / `aria-level` / `aria-setsize` / `aria-posinset` / `aria-selected`. **Violates the mandatory WAI-ARIA APG gate.** |
-| No keyboard | No arrows, Home/End, `*`, type-ahead. Rows are not focusable at all. |
-| No selection contract | No `value` / `defaultValue` / `onValueChange`. **Violates the controlled-vocabulary rule (§2d).** |
-| No `size`, no `ref`, no `className`/`...props` | Props are literally `{ items }`. **Violates §2d.** |
-| Depth is uncapped but unstyled past 2 | Its own docs page says "Indentation is defined for depth 0-2, so flatten deeper branches". `tree-list-depth.test.tsx` asserts depth `5` sets the CSS var — which then renders at an indent nobody designed. |
-| Missing every Ant affordance | no icons, no `showLine`, no drag & drop, no virtual scroll, no async `loadData`, no search/filter highlight, no `blockNode`, no DirectoryTree. |
-
-**Conclusion:** the "tree components don't look like Ant Design" complaint is correct, and it is
-localized: `TreeSelect` is fine, `TreeList` is a cosmetic indented list, and the standalone `Tree`
-that every Ant-shaped app reaches for was never built.
-
-## 2. GATE 0 ledger — `Tree` (required before any `src/components/**` addition)
-
-| # | Criterion | Verdict | Why |
-| --- | --- | --- | --- |
-| C1 | Universal, not design-specific | **PASS** | File explorers, org charts, category pickers, permission trees, nav outlines. |
-| C2 | Encapsulates reusable behavior | **PASS** | Roving tabindex, arrow/Home/End/`*` navigation, type-ahead, expand state, tri-state check propagation, async load. |
-| C3 | Not composable from existing primitives | **PASS** | `Accordion` is single-level disclosure; `Timeline`/`NavList`/`ListRow` are flat. No primitive owns tree keyboard navigation on a page. |
-| C4 | Single responsibility + controlled-vocabulary API | **PASS** | One job (render + navigate a hierarchy); maps cleanly onto the triads in §3. |
-| C5 | Fully token-themeable | **PASS** | Indent, rail, glyph, row height all become `--tree-*` component tokens. |
-| C6 | Earns the international contract | **PASS** | Needs correct APG semantics and RTL indentation; used everywhere. |
-| C7 | Earns its bundle cost | **PASS** | Broad; also lets `TreeSelect` and `Tree` share one node renderer. |
-
-**ALL PASS → `Tree` is a framework component.**
-
-## 3. Normalized API — Ant Design name → godx controlled vocabulary
-
-`Tree` mirrors Ant Design's *capabilities*, never its *prop names* where they conflict with
-`docs/PROPS-VOCABULARY.md`. This mapping is the contract; do not invent a third spelling.
-
-| Capability | Ant Design | **godx `Tree`** |
-| --- | --- | --- |
-| Data | `treeData` | `treeData: TreeOptionProp[]` (reuse the existing `TreeOptionProp` + `TreeFieldNamesProp`) |
-| Field remap | `fieldNames` | `fieldNames` (unchanged — already in the registry) |
-| Selection | `selectedKeys` / `defaultSelectedKeys` / `onSelect` | `value` / `defaultValue` / `onValueChange` |
-| Multi-select | `multiple` | `multiple` |
-| Checkboxes | `checkedKeys` / `onCheck` | `checkedValues` / `defaultCheckedValues` / `onCheckedValuesChange` |
-| Checkbox mode | `checkable` | `checkable` |
-| Independent checks | `checkStrictly` | `checkStrictly` |
-| Expansion | `expandedKeys` / `onExpand` | `expandedValues` / `defaultExpandedValues` / `onExpandedValuesChange` |
-| Expand all | `defaultExpandAll` | `defaultExpandAll` |
-| Async children | `loadData` | `loadData` (same signature as `TreeSelect`'s) |
-| Node label render | `titleRender` | `titleRender` |
-| Connector lines | `showLine` | `showLine` |
-| Node icons | `showIcon` / `icon` | `showIcon`, per-node `icon` |
-| Full-width row | `blockNode` | *dropped* — always full-width row; that is the only correct hit area under WCAG 2.5.8 |
-| Disclosure glyph | `switcherIcon` | *dropped* — the glyph is a token (`--tree-switcher-*`), not a prop |
-| Density | — | `size: xs \| sm \| lg` (`md` is the default, never `"default"`) |
-| Directory variant | `<DirectoryTree>` | `variant="directory"` |
-| Drag & drop | `draggable` | **out of scope for v1** — file a follow-up issue |
-| Virtual scroll | `virtual` / `height` | `height` + `virtual` (gh#1042) — windowed rows are a flat run of treeitems; antd has no "load more" node, so none is shipped |
-| Match highlight | `filterTreeNode` | `filterTreeNode` (gh#1043) — `data-filter-node="true"` for antd's `filter-node` class, plus an sr-only "matches" |
-
-Plus the house rules: forward `ref`, spread `...props`, accept `className` + `id`, export
-`TreeProp` and `TreeProp as TreeProps` from `src/props/components/data-display.prop.ts`, and
-**register it in `src/props/registry.ts`**.
-
-## 4. Required semantics (WAI-ARIA APG "Tree View")
-
-- Container `role="tree"`, `aria-multiselectable` when `multiple` or `checkable`.
-- Each node `role="treeitem"` with `aria-level` (1-based), `aria-setsize`, `aria-posinset`,
-  `aria-selected`, and `aria-expanded` **only on nodes that have children**.
-- Grouping wrapper `role="group"`.
-- **Roving tabindex** — exactly one node has `tabIndex={0}`; all others `-1`.
-- Keyboard: `↓`/`↑` next/previous *visible* node · `→` expand, then move to first child ·
-  `←` collapse, then move to parent · `Home`/`End` first/last visible · `Enter`/`Space` select
-  (or toggle the checkbox when `checkable`) · `*` expand all siblings at the current level ·
-  type-ahead jumps to the next node whose label starts with the typed characters.
-- Under `dir="rtl"`, `→`/`←` swap meaning and indentation flips — logical CSS only
-  (`margin-inline-start`, `padding-inline-start`), never `ml-`/`pl-`/`left-`.
-- Tri-state parent checkbox: checked / unchecked / **indeterminate** when only some descendants
-  are checked (skip propagation entirely when `checkStrictly`).
-
-## 5. Tokens (tier: `src/tokens/components/tree.css`, `@import`ed from `src/tokens/base.css`)
-
-Names must pass `pnpm check:token-tiers` (`--{component}-{part}-{property}`):
-`--tree-node-height` (from the `--control-height` tier — never a literal), `--tree-indent-width`,
-`--tree-switcher-size`, `--tree-switcher-color`, `--tree-line-color`, `--tree-node-selected-background`,
-`--tree-node-hover-background`, `--tree-icon-size`. Row hit area ≥ 24×24px (WCAG 2.5.8).
-
-## 6. i18n keys (`src/i18n/messages/{en,vi,ja}.json`)
-
-`tree.expand`, `tree.collapse`, `tree.loading`, `tree.empty`, `tree.selected` (sr-only status —
-selection must never be colour-only, WCAG 1.4.1). Every `aria-label` goes through `t()`.
-
-## 7. `TreeList` — what happened to it
-
-**Superseded here, then REMOVED in 21.0.0.** The plan above ("stays exported, it has consumers")
-was written while it still had them. It stopped: the last two call sites in `godx-task`
-(`pages/tests/show.tsx`, `pages/documents/index.tsx`) moved to `Tree`, and a sweep of all four
-consumer repos (godx-task, godx-chat, ql, platform) found none left. A superseded export that
-nobody calls is not a compatibility surface, it is a second answer to a question that already has
-one — and the catalog blurb it shipped with promised a "chevron + package icon" the component
-never rendered.
-
-So it is gone, with no deprecated shim: component, types, barrel entries, tests, frame, catalog
-entry, `--tree-item-*` tokens and `.ui-tree-item` CSS. `Tree` is the replacement, and the Tree
-catalog entry carries the migration (`id`->`value`, `title`->`label`, `depth`->nesting).
-`check-mcp-pattern-imports.mjs` now denylists an import of, or JSX for, the removed export, the
-same way it denylists `Stack`/`Inline`.
-
-## 8. Shared code
-
-Move `src/components/data-entry/tree-utils.ts` to a location both groups can import
-(`src/lib/tree.ts`), re-export from the old path so `TreeSelect` keeps working, and have `Tree`
-consume the same `normalizeTreeOptions` / `flattenVisibleTree` / `getDescendantValues`.
-**One tree model, two surfaces** — do not fork the traversal logic.
-
-## 9. Definition of done
-
-Cheap gates, then this component's tests only:
-
-```
-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 vitest run src/components/data-display/__tests__ --maxWorkers=2
-```
-
-`pnpm test` / bare `pnpm vitest run` are **forbidden** — the full suite is CI's job.