@design-ai/cli 4.55.0

package/examples/component-transfer.md

@@ -0,0 +1,156 @@
+# `Transfer` (dual list) — spec
+
+> Citing Ant Design `Transfer`, MUI (no built-in), shadcn-ui (no built-in)
+
+## Purpose
+
+Two side-by-side lists with arrows to move items between them. Used for: permission editors (available roles → assigned roles), team assignment, tag selection (available tags → applied tags), feature flags (available features → enabled features).
+
+## When Transfer vs alternatives
+
+| Pattern | Use |
+| --- | --- |
+| **Transfer** | User explicitly moves items between TWO lists; both sides matter |
+| **Multi-Select** | User picks from many; UI shows selected as tags only |
+| **Checkbox list** | Simpler — just toggle each item |
+| **Tree (with check)** | Hierarchical permissions; tree shape matters |
+
+Transfer is a power-user pattern. Most consumer UIs should use Multi-Select instead.
+
+## Anatomy
+
+```
+┌──────────────────┐                   ┌──────────────────┐
+│ Available (12)   │                   │ Assigned (3)     │
+│ ▣ Search...      │                   │ ▣ Search...      │
+├──────────────────┤                   ├──────────────────┤
+│ ☐ Item A          │      [→  ]       │ ☑ Item D          │
+│ ☐ Item B          │      [→→]       │ ☑ Item E          │
+│ ☑ Item C          │   [←]  [←←]      │ ☑ Item F          │
+│ ☐ Item D          │                   │                   │
+│ ...               │                   │                   │
+└──────────────────┘                   └──────────────────┘
+   Select all (1)                          Remove all (0)
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Source list (left) | yes | Available items |
+| Target list (right) | yes | Selected/assigned items |
+| Movement arrows (center) | yes | Single + bulk move buttons |
+| Search per side | optional | Filter within each list |
+| Header per side | yes | Title + count + select-all |
+| Item checkbox | yes | Multi-select before move |
+
+## API
+
+```tsx
+<Transfer
+  source={availableItems}
+  target={selectedItemKeys}
+  onChange={setSelectedItemKeys}
+  searchable
+  titles={["사용 가능한 권한", "할당된 권한"]}
+  itemRender={(item) => <PermissionItem item={item} />}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `source` | `Item[]` | — | All possible items |
+| `target` | `string[]` | `[]` | Keys currently in the target side |
+| `onChange` | `(targetKeys: string[]) => void` | — | |
+| `titles` | `[string, string]` | `["Source", "Target"]` | Header labels per side |
+| `searchable` | `boolean` | `false` | Search inputs |
+| `itemRender` | `(item) => ReactNode` | default | Custom rendering |
+| `disabled` | `boolean` | `false` | |
+| `oneWay` | `boolean` | `false` | Items only move source → target (no return) |
+
+```ts
+type Item = {
+  key: string;
+  label: string;
+  description?: string;
+  disabled?: boolean;
+  data?: unknown;
+};
+```
+
+## Behavior
+
+### Movement
+
+1. User checks items in source list.
+2. Click `→` to move selected items to target.
+3. Reverse with `←`.
+4. Bulk: `→→` (move all visible), `←←` (return all).
+
+### Search
+
+Per-side search filters that side's visible items. Doesn't affect the other side. Combined search across both: typically not provided (different lists, different intent).
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Both lists rendered |
+| Item checked (in source) | Move-right arrow enabled |
+| Item checked (in target) | Move-left arrow enabled |
+| Empty source side | "모든 항목이 할당되었습니다" |
+| Empty target side | "할당된 항목이 없습니다" |
+| Disabled | Both lists muted |
+
+## Accessibility
+
+- Each side: `<section>` with `<h3>` heading.
+- Lists: `role="listbox" aria-multiselectable="true"`.
+- Items: `role="option"`, `aria-selected="true|false"`.
+- Movement buttons: `<button>` with `aria-label`.
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` | Reach search → list → arrows → other list (in order) |
+| `↑` / `↓` | Move within list |
+| `Space` | Toggle item selected |
+| `Enter` (on arrow) | Apply movement |
+
+## Mobile pattern
+
+Transfer's two-side layout doesn't fit mobile. Switch to:
+
+```
+[Single tab list with toggles]
+"Available" tab          "Assigned" tab
+   Item A  [→ Add]            Item D  [✕]
+   Item B  [→ Add]            Item E  [✕]
+   Item C  [✓ Added]          Item F  [✕]
+```
+
+Or a simpler "tap to toggle" pattern:
+
+```
+☐ Item A    (tap to add)
+☐ Item B
+☑ Item D    (tap to remove)
+☑ Item E
+```
+
+## Don't
+
+- Don't use Transfer for < 10 items. Use Checkbox list — simpler.
+- Don't use for non-symmetric "both sides matter" cases. If user only cares about one side, use Multi-Select.
+- Don't omit per-side counts — users want to know how many they've selected.
+- Don't disable items in source after moving — make it clear they're already in target by hiding or disabling consistently.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/transfer/`](../refs/ant-design/components/transfer/) — `Transfer`. Most exhaustive; supports tree-like (`Transfer.TableTransfer`).
+- MUI / shadcn-ui: no built-in.
+
+## Cross-reference
+
+- [`examples/component-form-controls.md`](component-form-controls.md) — Checkbox list alternative
+- [`examples/component-select.md`](component-select.md) — Multi-Select alternative
+- [`examples/component-tree.md`](component-tree.md) — for hierarchical permission pickers

package/examples/component-tree-select.md

@@ -0,0 +1,202 @@
+# `TreeSelect` — spec
+
+> Synthesized from Ant Design `TreeSelect`. A select-style dropdown that opens a tree view for hierarchical selection. Distinct from `Cascader` (level-by-level columns) and `Tree` (full-page).
+
+## TreeSelect vs Cascader vs Tree
+
+| | TreeSelect | Cascader | Tree |
+| --- | --- | --- | --- |
+| Trigger | Single dropdown | Single dropdown with column drilldown | Full-page or panel |
+| Hierarchy | Whole tree visible (collapsible) | Level-at-a-time | Whole tree visible |
+| Multi-select | Yes | Variable | Yes |
+| Search | Yes | Yes | Yes |
+| Use | Department / category picker (deep tree) | Region / address (consistent depth) | File browser / hierarchy management |
+
+## Anatomy
+
+```
+[ Engineering / Frontend  ▾ ]    ← trigger field with selected path
+                                    
+       ↓ open
+       ┌──────────────────────┐
+       │  ⌕ Search...          │
+       │ ───────────────       │
+       │  ▶ Engineering         │
+       │    ▼ Frontend         │
+       │       ● React (selected) │
+       │       ○ Vue              │
+       │       ○ Svelte           │
+       │    ▶ Backend             │
+       │  ▶ Design                 │
+       │  ▶ Marketing              │
+       └──────────────────────┘
+```
+
+## API
+
+```tsx
+<TreeSelect
+  value={selectedKey}
+  onChange={setSelectedKey}
+  treeData={[
+    {
+      title: "Engineering",
+      key: "eng",
+      children: [
+        {
+          title: "Frontend",
+          key: "fe",
+          children: [
+            { title: "React", key: "react" },
+            { title: "Vue", key: "vue" },
+          ],
+        },
+        { title: "Backend", key: "be" },
+      ],
+    },
+    { title: "Design", key: "design" },
+  ]}
+  treeDefaultExpandAll
+  showSearch
+  placeholder="부서 선택"
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string \| string[]` | controlled | Selected key(s) |
+| `onChange` | `(value) => void` | — | Callback |
+| `treeData` | `TreeNode[]` | — | Hierarchy |
+| `multiple` | `boolean` | `false` | Multi-select |
+| `treeCheckable` | `boolean` | `false` | Show checkbox per node (multi-select with parent ↔ children sync) |
+| `showSearch` | `boolean` | `false` | Filter input |
+| `treeDefaultExpandAll` | `boolean` | `false` | Expand all on mount |
+| `treeDefaultExpandedKeys` | `string[]` | `[]` | Initial expanded |
+| `placeholder` | `string` | — | When no selection |
+| `disabled` | `boolean` | `false` | — |
+
+## Variants
+
+### Single-select
+
+One value, single click. No checkboxes.
+
+### Multi-select with checkboxes (`treeCheckable`)
+
+Click parent → all children checked.
+Half-checked when some children selected.
+Selected items shown as chips in trigger.
+
+### Search
+
+Type filters tree to matching nodes (and their ancestors so the path is visible).
+
+## States
+
+Same family as Combobox + Tree:
+- Trigger states (default, focus, error, disabled).
+- Open / closed.
+- Hover / selected nodes.
+- Expanded / collapsed branches.
+
+## Tokens consumed
+
+```
+--tree-select-bg                   (panel)
+--tree-select-bg-hover
+--tree-select-bg-selected
+--tree-select-checkbox-bg          (multi-select)
+--tree-select-line                 (tree connector lines, optional)
+--tree-select-search-bg            (filter input)
+--space-xs, --space-sm
+--font-size-sm
+--motion-fast
+--z-overlay
+```
+
+## Accessibility
+
+- Trigger: `<button role="combobox" aria-haspopup="tree" aria-expanded>`.
+- Tree: `role="tree"` with `<li role="treeitem" aria-expanded="true|false" aria-selected>` items.
+- Keyboard:
+  - Tab into trigger; Enter opens.
+  - Arrow keys navigate within tree (Down/Up moves to next/prev visible node; Right expands; Left collapses).
+  - Enter selects.
+  - Esc closes.
+- For multi-select with checkboxes: each checkbox is independent focusable.
+- Touch target ≥ 36pt per node.
+
+## Code example — KR organizational tree
+
+```tsx
+function DepartmentSelect() {
+  return (
+    <Field>
+      <Label>부서</Label>
+      <TreeSelect
+        value={department}
+        onChange={setDepartment}
+        showSearch
+        placeholder="부서를 선택해 주세요"
+        treeData={[
+          {
+            title: "엔지니어링",
+            key: "eng",
+            children: [
+              { title: "프론트엔드", key: "fe" },
+              { title: "백엔드", key: "be" },
+              { title: "데이터", key: "data" },
+              { title: "데브옵스", key: "ops" },
+            ],
+          },
+          {
+            title: "디자인",
+            key: "design",
+            children: [
+              { title: "프로덕트", key: "product-design" },
+              { title: "브랜드", key: "brand" },
+              { title: "리서치", key: "research" },
+            ],
+          },
+          {
+            title: "마케팅",
+            key: "marketing",
+            children: [
+              { title: "그로스", key: "growth" },
+              { title: "콘텐츠", key: "content" },
+            ],
+          },
+        ]}
+      />
+    </Field>
+  );
+}
+```
+
+## Edge cases
+
+- **Very deep tree (5+ levels)**: visual gets cramped. Consider Cascader instead.
+- **Very wide tree at one level (50+ siblings)**: virtualize the visible nodes.
+- **Async tree data**: load children on expand. Show loading state per node.
+- **Search filters deeply**: ensure path-to-match is highlighted; expand intermediate ancestors.
+- **Multi-select with checkbox + parent-child sync**: clicking parent checks all descendants. Half-check parent when some descendants checked.
+- **Reduced motion**: skip expand/collapse animation.
+
+## Don't
+
+- Don't use TreeSelect when Cascader is appropriate (consistent depth, e.g., region selection).
+- Don't show 1000+ flat nodes — that's a Combobox + virtualization.
+- Don't auto-collapse user's manual expansions on re-open. Persist state.
+- Don't omit search for trees > 20 nodes.
+
+## References
+
+- Ant: [`TreeSelect`](../refs/ant-design/components/tree-select)
+- WAI-ARIA: [Tree pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/)
+
+## Cross-reference
+
+- [`examples/component-tree.md`](component-tree.md) — full-page tree
+- [`examples/component-cascader.md`](component-cascader.md) — column-by-column
+- [`examples/component-combobox.md`](component-combobox.md) — flat selectable
+- [`examples/component-select.md`](component-select.md) — flat selectable variant

package/examples/component-tree.md

@@ -0,0 +1,297 @@
+# `Tree` (TreeView) — spec
+
+> Citing Ant Design `Tree`, MUI `TreeView` (X package), shadcn-ui (no built-in)
+
+## Purpose
+
+Hierarchical data with expandable nodes. Used for: file explorers, organization charts, category trees, taxonomy editors, navigation sidebars with nested sections.
+
+## When Tree vs alternatives
+
+| Pattern | Use |
+| --- | --- |
+| **Tree** | True parent-child hierarchy with arbitrary depth |
+| **Accordion** | Two-level grouping where the inner items are flat |
+| **Cascader / multi-level select** | Picking ONE leaf from a hierarchy |
+| **Nested list** | Display-only hierarchy, no expand/collapse |
+| **Sidebar nav** | Fixed structure (≤ 2 levels usually) |
+
+Use Tree when nodes can be expanded/collapsed, possibly selected, possibly draggable.
+
+## Anatomy
+
+```
+▾ 📁 Root
+  ▾ 📁 Folder 1
+    📄 file-a.tsx
+    📄 file-b.tsx
+  ▸ 📁 Folder 2
+  ▸ 📁 Folder 3
+▸ 📁 Archived
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Expand toggle | yes | Chevron `▸` / `▾` (rotates on expand) |
+| Icon | optional | Folder / file / custom |
+| Label | yes | Node display name |
+| Trailing meta | optional | Count, badge, actions on hover |
+| Indent | yes | Per depth level (typically 16–20px) |
+
+## API
+
+```tsx
+<Tree
+  data={treeData}
+  selectedKeys={selected}
+  onSelect={setSelected}
+  expandedKeys={expanded}
+  onExpand={setExpanded}
+  multiSelect={false}
+  draggable
+/>
+
+// where treeData is:
+type TreeNode = {
+  key: string;
+  label: ReactNode;
+  icon?: ReactNode;
+  children?: TreeNode[];
+  disabled?: boolean;
+  isLeaf?: boolean;        // override (children may exist but not visible — async load)
+  meta?: ReactNode;
+};
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | `TreeNode[]` | — | Hierarchical data |
+| `selectedKeys` | `string[]` | `[]` | Selected node keys |
+| `onSelect` | `(keys, node) => void` | — | |
+| `expandedKeys` | `string[]` | computed | Open nodes |
+| `onExpand` | `(keys) => void` | — | |
+| `defaultExpandedKeys` | `string[]` | `[]` | Initial open |
+| `defaultExpandAll` | `boolean` | `false` | Expand everything on mount |
+| `multiSelect` | `boolean` | `false` | Allow multiple selection (Ctrl/Shift modifiers) |
+| `checkable` | `boolean` | `false` | Render checkboxes on each node |
+| `checkedKeys` | `string[]` | `[]` | Checked items (with checkable) |
+| `onCheck` | `(keys, info) => void` | — | |
+| `searchable` | `boolean` | `false` | Render search input above; auto-expands matching paths |
+| `searchValue` | `string` | — | Controlled search |
+| `draggable` | `boolean` | `false` | Drag-and-drop reordering |
+| `onDrop` | `(info) => void` | — | |
+| `loadData` | `(node) => Promise<TreeNode[]>` | — | Async lazy-load children on expand |
+| `density` | `"compact" \| "comfortable"` | `"comfortable"` | |
+| `showLine` | `boolean` | `false` | Render guide lines connecting parent → children |
+
+## Modes — selection vs check
+
+| Mode | Use |
+| --- | --- |
+| **Selection** (`onSelect`) | Pick a single (or with multiSelect: multiple) node — file explorer "open this file" |
+| **Check** (`checkable: true`) | Check sub-trees — permission editor "include these folders" |
+
+You can combine — Tree with selectable nodes + checkboxes, but it's heavy. Pick one as primary.
+
+### Check semantics
+
+When `checkable`:
+- Checking a parent checks all descendants.
+- Unchecking a parent unchecks all descendants.
+- Children with mixed states → parent shows **indeterminate** (─).
+- "Strictly mode" (independent parent/child checks): set `checkStrictly={true}` for permission editors that need this.
+
+## Behavior
+
+### Expand / collapse
+
+- Click chevron: toggle expand for that node.
+- Click label: select (don't expand). Chevron handles expand.
+- Some products: double-click label to expand. Convention.
+
+### Single selection
+
+- Click a node: select. Highlights row.
+- Click again: deselect (or stays — depends on UX).
+
+### Multi-selection
+
+- `Ctrl+click` (or `Cmd`): toggle individual.
+- `Shift+click`: select range from last selected to clicked.
+- `Click` (no modifier): replace selection with single.
+
+### Async lazy-load
+
+When `loadData` is set, expanding a node fetches its children:
+
+```tsx
+<Tree
+  data={treeData}
+  loadData={async (node) => {
+    const children = await api.fetchChildren(node.key);
+    return children;
+  }}
+/>
+```
+
+Show spinner on the expanding node while fetching. Cache results — don't re-fetch on subsequent expands of the same node (unless explicitly invalidated).
+
+### Search
+
+Filter the tree by label. Auto-expand paths containing matches. Highlight matched substring.
+
+When all matches in a subtree, that path is fully expanded. Other paths collapse.
+
+```
+search: "minji"
+
+▾ 📁 Root
+  ▾ 📁 Team
+    👤 김**민지** (matched)
+  📁 Archived (collapsed — no matches inside)
+```
+
+## States — per node
+
+| State | Visual |
+| --- | --- |
+| Default | Resting |
+| Hover | Bg `--color-bg-subtle` |
+| Selected | Bg `--color-primary-subtle-bg`, text `--color-primary-default` |
+| Focus-visible | 2px ring on row |
+| Loading (async) | Spinner replacing chevron |
+| Disabled | Muted, no events |
+| Drag-over (drop target) | Highlighted top/bottom border (insert above/below) or whole row (insert into) |
+
+## Sizes / density
+
+| Density | Row height | Indent per level |
+| --- | --- | --- |
+| `compact` | 24px | 16px |
+| `comfortable` (default) | 32px | 20px |
+
+For deep trees (10+ levels): `compact` is often the only readable choice. Render scrollable container.
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-subtle              (hover)
+--color-primary-subtle-bg       (selected)
+--color-primary-default         (selected text, indeterminate check)
+--color-text-primary
+--color-text-secondary          (icon, secondary meta)
+--color-text-tertiary           (chevron when collapsed)
+--color-border-default          (drop indicator, guide lines)
+--color-focus-ring
+--space-xs, --space-sm
+--font-size-sm, --font-size-base
+--motion-fast                   (chevron rotate)
+```
+
+## Accessibility — WAI-ARIA Tree pattern
+
+This is one of the more complex a11y patterns. Use Radix/Headless or a battle-tested primitive.
+
+### ARIA structure
+
+- `role="tree"` on the container.
+- Each node: `role="treeitem"`, `aria-expanded={true|false|undefined}` (undefined for leaves), `aria-level={n}`, `aria-setsize={count}`, `aria-posinset={index}`.
+- Selected: `aria-selected="true"`.
+- Children container: `role="group"`.
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` | Reach the tree (single tab stop) |
+| `↓` / `↑` | Move focus to next / previous visible node |
+| `→` | Expand if collapsed; if expanded, move to first child |
+| `←` | Collapse if expanded; if leaf, move to parent |
+| `Home` / `End` | First / last visible node |
+| `Enter` / `Space` | Select / toggle check |
+| `*` (asterisk) | Expand all siblings of focused node |
+| Type-ahead | Jump to first node starting with typed character |
+
+This is **the** WAI-ARIA tree pattern. Don't reinvent. Implement exactly.
+
+### Screen reader
+
+Announce on movement:
+- Position: "node 2 of 5"
+- Level: "level 2"
+- Expansion state: "expanded" / "collapsed"
+- Selection: "selected"
+
+## Code example
+
+```tsx
+// File explorer
+<Tree
+  data={fileTree}
+  selectedKeys={openFile ? [openFile.key] : []}
+  onSelect={(keys, { node }) => setOpenFile(node.isLeaf ? node : null)}
+  defaultExpandedKeys={["root"]}
+  showLine
+/>
+
+// Permission editor with checkable
+<Tree
+  data={permissionTree}
+  checkable
+  checkedKeys={selectedPermissions}
+  onCheck={setSelectedPermissions}
+/>
+
+// Async lazy-load
+<Tree
+  data={initialTree}
+  loadData={async (node) => api.getChildren(node.key)}
+/>
+
+// Searchable team directory
+<Tree
+  data={orgTree}
+  searchable
+  searchValue={query}
+  onSelect={(keys, { node }) => navigate(`/people/${node.key}`)}
+/>
+```
+
+## Edge cases
+
+- **Very deep trees (20+ levels)**: indent overflow horizontally. Allow horizontal scroll OR use breadcrumbs at the top showing path.
+- **Many siblings (1000+)**: virtualize. Standard Tree libraries (react-arborist, MUI X TreeView) support virtualization.
+- **Async load fails**: show retry inline next to the node. Don't blow up the whole tree.
+- **Loading parent that already has children**: re-fetch silently OR ignore (depends on whether children are stale).
+- **Drag-and-drop**: provide visual cues (drop indicator), prevent dropping a node into its own descendant.
+- **Mobile**: tree UIs are often broken on touch — small targets, no hover. Switch to a drill-in list pattern (each level is its own screen with breadcrumb).
+- **Empty tree**: render an empty state (see [`empty-states.md`](../knowledge/patterns/empty-states.md)).
+- **Korean tree labels**: usually short (3–10 chars per node). Hangul renders cleanly at compact density.
+
+## Don't
+
+- Don't render a tree with no expand/collapse if all data is always visible. Use a list.
+- Don't use a tree for navigation if depth > 3. The user gets lost.
+- Don't auto-expand-all on mount for large trees (perf + visual chaos).
+- Don't combine selection + multiselect + check + drag in one tree without strong UX. Pick the modes.
+- Don't forget keyboard nav. Tree without arrow keys is broken.
+- Don't put long labels that wrap. Truncate with title attribute.
+- Don't use trees on mobile without testing the drill-in alternative.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/tree/`](../refs/ant-design/components/tree/) — `Tree` with `Tree.DirectoryTree` for file-style. Most exhaustive (drag-drop, async, search, virtual). Heavy.
+- MUI: `@mui/x-tree-view` (separate package) — `RichTreeView` (declarative), `SimpleTreeView` (composition). Excellent a11y.
+- shadcn-ui: no built-in. Compose from primitives + headless library (react-arborist or @aria-tree).
+
+API choices made:
+- **`data` driven prop** (not children composition): trees are usually data-driven from API; declarative API matches.
+- **`selectedKeys` + `checkedKeys` separate**: select and check are different semantics (selection = "current pointer", check = "included in operation").
+- **`loadData` for async**: matches Ant's convention; explicit promise return is clearer than callbacks.
+
+## Cross-reference
+
+- [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md) — tree keyboard contract
+- [`knowledge/patterns/list-and-feed.md`](../knowledge/patterns/list-and-feed.md) — when flat list is enough
+- [WAI-ARIA Tree Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/)