@godxjp/ui 20.2.1 → 21.0.0

package/docs/roadmap/tree-components.md

@@ -0,0 +1,151 @@
+# 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` | **out of scope for v1** — cap with `ScrollArea`; file a follow-up issue |
+
+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`).
+- Ships `tree.a11y.test.tsx` with `expectNoA11yViolations` — 0 violations.
+
+## 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.

package/docs/showcase/table-tree-rows.tsx

@@ -3,10 +3,10 @@
  *
  * Tree / hierarchical rows inside the real @godxjp/ui DataTable.
  *
- * The lib's `TreeList` is a flat presentational list (fixed icons, no twirl, no
- * tabular columns) — it cannot express a *tabular* hierarchy with per-row metrics,
- * a parent-only disclosure twirl, and DataTable chrome (sticky header, density,
- * sortable columns). So this composes the behaviour from real primitives:
+ * The lib's `Tree` owns the standalone tree view, but it is single-column — it
+ * cannot express a *tabular* hierarchy with per-row metrics, a parent-only
+ * disclosure twirl, and DataTable chrome (sticky header, density, sortable
+ * columns). So this composes the behaviour from real primitives:
  *
  *   row model ........ flatten an org tree to rows carrying { depth, hasChildren,
  *                      expanded }, then derive `visibleRows` from the open set.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "20.2.1",
-  "godxUiMcp": "20.2.1",
+  "version": "21.0.0",
+  "godxUiMcp": "21.0.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -351,9 +351,11 @@
     "check:display-runtime-evidence": "node scripts/check-display-runtime-evidence.mjs",
     "check:data-table-pagination-wrap": "node scripts/check-data-table-pagination-wrap.mjs",
     "check:button-icon-xs": "node scripts/check-button-icon-xs.mjs",
+    "check:timeline-title-fill": "node scripts/check-timeline-title-fill.mjs",
+    "check:descriptions-label-value-step": "node scripts/check-descriptions-label-value-step.mjs",
     "check:frame-contracts": "pnpm check:component-api-manifest && pnpm audit:component-cases && pnpm check:frame-coverage && pnpm check:frame-coverage-ledger && pnpm check:screen-reader-evidence && pnpm check:data-entry-owner-source && pnpm check:display-runtime-evidence",
     "check:final-touch-rtl": "node scripts/check-final-touch-rtl.mjs",
-    "check:frame-runtime": "pnpm check:data-entry-frame-runtime && pnpm check:data-entry-touch-aria && pnpm check:layout-nav-frames && pnpm check:provider-feedback-query-runtime && pnpm check:layout-nav-closure && pnpm check:final-touch-rtl && pnpm check:data-table-pagination-wrap && pnpm check:button-icon-xs",
+    "check:frame-runtime": "pnpm check:data-entry-frame-runtime && pnpm check:data-entry-touch-aria && pnpm check:layout-nav-frames && pnpm check:provider-feedback-query-runtime && pnpm check:layout-nav-closure && pnpm check:final-touch-rtl && pnpm check:data-table-pagination-wrap && pnpm check:button-icon-xs && pnpm check:timeline-title-fill && pnpm check:descriptions-label-value-step",
     "verify": "pnpm typecheck && pnpm lint && pnpm format && pnpm build && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:no-consumer-coupling && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:no-external-assets && pnpm check:token-scale-bypass && pnpm check:dist-tokens-resolve && pnpm check:no-hardcoded-geometry && pnpm check:no-hardcoded-css-values && pnpm check:no-inline-magic-numbers && pnpm check:no-tailwind-class-assertions && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-lockstep && pnpm check:mcp-sync && pnpm check:doc-prop-existence && pnpm check:mcp-catalog-coverage && pnpm check:mcp-orphans && pnpm check:mcp-pattern-imports && pnpm check:audit-sync && pnpm check:frame-coverage && pnpm test",
     "verify:static": "pnpm build && pnpm check:packed-public-contract && pnpm typecheck && pnpm typecheck:docs && pnpm lint && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:no-consumer-coupling && pnpm check:use-client && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:token-scale-bypass && pnpm check:dist-tokens-resolve && pnpm check:no-hardcoded-geometry && pnpm check:no-hardcoded-css-values && pnpm check:no-inline-magic-numbers && pnpm check:no-tailwind-class-assertions && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-lockstep && pnpm check:mcp-sync && pnpm check:doc-prop-existence && pnpm check:mcp-catalog-coverage && pnpm check:mcp-orphans && pnpm check:mcp-pattern-imports && pnpm check:audit-sync && pnpm check:mcp-prop-sync && pnpm check:contrast && pnpm check:visual-audit && pnpm test",
     "verify:ci": "pnpm verify:ci:static && pnpm check:frame-contracts && pnpm test",

package/dist/components/data-display/tree-list.d.ts

@@ -1,13 +0,0 @@
-import type { ReactNode } from "react";
-export type TreeListItem = {
-    id: string;
-    title: ReactNode;
-    description?: ReactNode;
-    depth?: number;
-    active?: boolean;
-    badge?: ReactNode;
-};
-export type TreeListProps = {
-    items: TreeListItem[];
-};
-export declare function TreeList({ items }: TreeListProps): import("react").JSX.Element;

package/dist/components/data-display/tree-list.js

@@ -1,26 +0,0 @@
-"use client";
-import { jsx, jsxs } from "react/jsx-runtime";
-import { Badge } from "./badge.js";
-function TreeList({ items }) {
-  return /* @__PURE__ */ jsx("ul", { className: "ui-tree-list", children: items.map((item) => /* @__PURE__ */ jsxs(
-    "li",
-    {
-      className: "ui-tree-item",
-      "data-active": item.active ? "true" : void 0,
-      "data-depth": Math.max(0, item.depth ?? 0),
-      style: { "--tree-item-depth": Math.max(0, item.depth ?? 0) },
-      "aria-current": item.active ? "true" : void 0,
-      children: [
-        /* @__PURE__ */ jsxs("div", { className: "ui-tree-item-body", children: [
-          /* @__PURE__ */ jsx("div", { className: "ui-tree-item-title", children: item.title }),
-          item.description ? /* @__PURE__ */ jsx("div", { className: "ui-tree-item-description", children: item.description }) : null
-        ] }),
-        item.badge != null ? /* @__PURE__ */ jsx(Badge, { variant: "secondary", children: item.badge }) : null
-      ]
-    },
-    item.id
-  )) });
-}
-export {
-  TreeList
-};

package/docs/data-display/tree-list.tsx

@@ -1,107 +0,0 @@
-import {
-  Badge,
-  Card,
-  CardContent,
-  CardDescription,
-  CardHeader,
-  CardTitle,
-  EmptyState,
-  TreeList,
-} from "@godxjp/ui/data-display";
-import { Flex, PageContainer } from "@godxjp/ui/layout";
-import { FolderTree } from "lucide-react";
-
-/**
- * TreeList — a flat array rendered as an indented hierarchy; depth is data-driven
- * (never nest DOM). active highlights a row (aria-current); badge surfaces a
- * secondary label. Indentation is defined for depth 0-2, so flatten deeper
- * branches before rendering. Composed only from real @godxjp/ui components.
- */
-const accounts = [
-  { id: "1000", title: "資産", depth: 0, badge: "親科目" },
-  { id: "1100", title: "流動資産", depth: 1, description: "1年以内に現金化" },
-  {
-    id: "1110",
-    title: "現金及び預金",
-    description: "普通・当座・小口",
-    depth: 2,
-    badge: "3 口座",
-    active: true,
-  },
-  {
-    id: "1120",
-    title: "売掛金",
-    description: "得意先への未回収債権",
-    depth: 2,
-    badge: (
-      <Badge variant="outline" tone="warning">
-        要確認
-      </Badge>
-    ),
-  },
-  { id: "2000", title: "負債", depth: 0, badge: "親科目" },
-  { id: "2100", title: "流動負債", depth: 1, description: "1年以内に支払" },
-  { id: "2110", title: "買掛金", depth: 2, badge: "12 件" },
-];
-
-// Independent data: active is allowed on any depth, including a top-level parent.
-const departments = [
-  { id: "d0", title: "本社", depth: 0, active: true, badge: "選択中" },
-  { id: "d1", title: "営業部", depth: 1, description: "首都圏・関西" },
-  { id: "d2", title: "開発部", depth: 1, description: "プロダクト・基盤" },
-];
-
-export default function Demo() {
-  return (
-    <PageContainer
-      title="TreeList"
-      subtitle="Hierarchical list · depth lives in the data, not the DOM"
-    >
-      <Flex direction="col" gap="lg">
-        <Card>
-          <CardHeader>
-            <CardTitle level={2}>勘定科目ツリー</CardTitle>
-            <CardDescription>
-              Pre-filter server-side; each item still carries its depth (0-2). An active leaf
-              carries aria-current; badges accept a string or a nested Badge node.
-            </CardDescription>
-          </CardHeader>
-          <CardContent>
-            <TreeList items={accounts} />
-          </CardContent>
-        </Card>
-
-        <Card>
-          <CardHeader>
-            <CardTitle level={2}>組織ツリー（親を選択中）</CardTitle>
-            <CardDescription>
-              active is data-driven and works at any depth. Here the depth-0 parent is the current
-              row.
-            </CardDescription>
-          </CardHeader>
-          <CardContent>
-            <TreeList items={departments} />
-          </CardContent>
-        </Card>
-
-        <Card>
-          <CardHeader>
-            <CardTitle level={2}>空の状態</CardTitle>
-            <CardDescription>
-              An empty items={"{[]}"} array renders an empty list. Pair it with an EmptyState
-              placeholder.
-            </CardDescription>
-          </CardHeader>
-          <CardContent>
-            <TreeList items={[]} />
-            <EmptyState
-              icon={FolderTree}
-              title="科目がありません"
-              description="フィルター条件に一致する勘定科目が見つかりませんでした。"
-            />
-          </CardContent>
-        </Card>
-      </Flex>
-    </PageContainer>
-  );
-}