@godxjp/ui 28.9.0 → 28.12.0

package/agent/components/Title.json

@@ -0,0 +1,67 @@
+{
+  "example": "import { Title } from \"@godxjp/ui/general\";\n\n<Title level={2}>請求書一覧</Title>\n<Title level={3} editable={{ onChange: rename }}>{projectName}</Title>",
+  "group": "general",
+  "importPath": "@godxjp/ui/general",
+  "name": "Title",
+  "props": [
+    {
+      "defaultValue": "1",
+      "description": "Sets BOTH the --heading-h{1..5} size token and the semantic <h1>..<h5>. Level 5 reads --heading-h5, which is bound to the existing --font-size-2xs step rather than being a new number. A value outside 1..5 falls back to h1, the way antd does — an <h7> from a runtime value would have no heading semantics at all. NOTE the default is antd's 1, while `Heading` defaults to 2.",
+      "name": "level",
+      "type": "1 | 2 | 3 | 4 | 5"
+    },
+    {
+      "description": "Override the rendered element — a visual h2 that is a real <h1>.",
+      "name": "as",
+      "type": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"div\""
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "Semantic foreground colour. Outranks antd's `type`.",
+      "name": "tone",
+      "type": "\"default\" | \"muted\" | \"primary\" | \"success\" | \"warning\" | \"destructive\" | \"info\" | \"inherit\""
+    },
+    {
+      "description": "Logical text alignment.",
+      "name": "align",
+      "type": "\"start\" | \"center\" | \"end\""
+    },
+    {
+      "description": "Single-line ellipsis. `ellipsis` outranks it when both are passed.",
+      "name": "truncate",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "\"medium\"",
+      "description": "Font weight, from the three-weight canon.",
+      "name": "weight",
+      "type": "\"regular\" | \"medium\" | \"semibold\" | \"bold\""
+    },
+    {
+      "description": "Truncation. `true` is one line; `rows` clamps to N. `expandable` adds an expand control, `symbol` relabels it, `onEllipsis` fires when the measured overflow flips.",
+      "name": "ellipsis",
+      "type": "boolean | { rows, expandable, suffix, symbol, defaultExpanded, expanded, onExpand, onEllipsis, tooltip }"
+    }
+  ],
+  "related": [
+    "Heading",
+    "Typography",
+    "Text",
+    "CardTitle"
+  ],
+  "rules": [
+    2,
+    23
+  ],
+  "storyPath": "general/typography.tsx",
+  "tagline": "antd Typography.Title — a heading with five levels and the antd block behaviours (copyable, editable, ellipsis, the decorations). A SIBLING of `Heading`, which is this library's own four-level heading and is unchanged.",
+  "usage": [
+    "DO use `Title` when you want antd's spelling, a fifth level, or a heading that is copyable / editable.",
+    "DO use `Heading` for everything else. It is the four-level heading the rest of this library is written in, and `CardTitle` / `PageContainer` already render one for you.",
+    "DON'T set `level` to pick a SIZE. It sets the semantic element too, so skipping from h1 to h4 for looks breaks the document outline — override the element with `as` instead."
+  ],
+  "useCases": [
+    "A project name a user can rename in place: `<Title level={2} editable={{ onChange: rename }}>{name}</Title>`.",
+    "A dense sub-label below the body step, where `Heading` has no level left: `<Title level={5}>内訳</Title>`."
+  ]
+}

package/agent/components/Toaster.json

@@ -0,0 +1,42 @@
+{
+  "example": "// app root — mount once\nimport { Toaster } from \"@godxjp/ui/feedback\";\n<>{children}<Toaster richColors /></>\n\n// anywhere — import toast from \"sonner\"\nimport { toast } from \"sonner\";\ntoast.success(\"クーポンを公開しました\");\ntoast.error(\"保存に失敗しました\");",
+  "group": "feedback",
+  "importPath": "@godxjp/ui/feedback",
+  "name": "Toaster",
+  "props": [
+    {
+      "defaultValue": "\"bottom-right\"",
+      "description": "Toast stack anchor.",
+      "name": "position",
+      "type": "\"top-right\" | \"top-center\" | \"bottom-right\" | \"…\""
+    },
+    {
+      "description": "Enable Sonner rich variant colours.",
+      "name": "richColors",
+      "type": "boolean"
+    }
+  ],
+  "related": [
+    "Alert — use for persistent, inline feedback that must stay visible (validation summaries, page-level warnings, destructive notices). Unlike Toaster, Alert does not auto-dismiss and lives in the document flow.",
+    "AlertMutationFeedback — use when you have a TanStack `useMutation` result and want an inline error + retry UI inside a form or card. Renders nothing on success/idle; pairs naturally with a `toast.success` in `onSuccess`.",
+    "Dialog — use when the user must make a conscious decision (confirm delete, resolve conflict) before proceeding. Toaster toasts are fire-and-forget; Dialog blocks until the user responds."
+  ],
+  "rules": [],
+  "storyPath": "feedback/Toaster.stories.tsx",
+  "tagline": "Mount once at app root to enable toasts. IMPORTANT: trigger toasts via `import { toast } from \"sonner\"` — NOT from @godxjp/ui.",
+  "usage": [
+    "DO: Mount exactly ONE `<Toaster richColors />` at the app root (e.g. inside your layout or AppShell children). Multiple mounts create duplicate toast stacks — there is no provider context, only DOM portals.",
+    "DO: Import `toast` from `\"sonner\"` directly (not from `@godxjp/ui`) to fire toasts anywhere: `toast.success(…)`, `toast.error(…)`, `toast.warning(…)`, `toast.info(…)`, `toast.loading(…)`, `toast.promise(…)`.",
+    "DON'T: Try to import a `toast` helper from `@godxjp/ui/feedback` — it does not exist. The component re-exports only the `Toaster` mount; the imperative API lives in the `sonner` package.",
+    "DO: Let the wrapper handle theming — it uses `useDocumentTheme()` to sync with the document `dark` class and `prefers-color-scheme` automatically. Never pass a hardcoded `theme` prop unless you are deliberately overriding.",
+    "DON'T: Use `Toaster` for persistent errors or blocking confirmations. Toasts auto-dismiss; they are not a substitute for `Alert` (inline persistent warnings) or `Dialog` (decisions requiring user input).",
+    "DO: Pass `position` to relocate the stack if a persistent sidebar/footer would obscure the default `bottom-right`. The wrapper already sets a safe `mobileOffset`; don't add redundant mobile offsets unless your layout differs."
+  ],
+  "useCases": [
+    "After a successful form save (invoice, journal entry, vendor record) — show `toast.success(\"保存しました\")` to confirm without blocking navigation.",
+    "After a background job is enqueued (e.g. bulk sync or export) — show `toast.info(\"エクスポートを開始しました\")` then later update with `toast.promise()` to track completion.",
+    "Mutation error fallback when the error is transient and retrying is the right UX — show `toast.error(message)` instead of replacing page content; reserve `AlertMutationFeedback` for inline, persistent error display inside a form.",
+    "Soft destructive action confirmation outcome — e.g. \"削除しました\" after an item is removed, paired with an undo action via `toast(\"…\", { action: { label: '元に戻す', onClick: undo } })`.",
+    "OAuth / session expiry warnings — surface a brief `toast.warning(\"セッションの有効期限が近づいています\")` without interrupting the user's current form state."
+  ]
+}

package/agent/components/Toggle.json

@@ -0,0 +1,90 @@
+{
+  "example": "import { Toggle } from \"@godxjp/ui/data-entry\";\n\n<Toggle aria-label=\"Bold\">B</Toggle>\n\n// A counted filter chip — one control, one accessible name (\"Unread, 12 items\").\n// Drive the state with the usual Radix pair: pressed / defaultPressed / onPressedChange.\n// variant=\"soft\" + shape=\"pill\" is the antd Tag.CheckableTag shape: it has a RESTING fill, so\n// the chip is legible before it is pressed.\n<Toggle\n  variant=\"soft\"\n  shape=\"pill\"\n  onPressedChange={setUnreadOnly}\n  count={12}\n  countLabel={t(\"common.items\")}\n>\n  {t(\"inbox.unread\")}\n</Toggle>",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "Toggle",
+  "props": [
+    {
+      "description": "Controlled pressed state.",
+      "name": "pressed",
+      "type": "boolean"
+    },
+    {
+      "description": "Pressed-state callback.",
+      "name": "onPressedChange",
+      "type": "(pressed: boolean) => void"
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "Visual style. `default` is a 1px TRANSPARENT border (a toolbar affordance — no resting surface at all), `outline` a hairline on --background, and `soft` (gh#734) the REST FILL a chip needs: hsl(var(--secondary)), byte-identical to the fill `Badge variant=\"secondary\"` and `Button variant=\"secondary\"` already paint, so a chip, a badge and a button on one row are one family. `soft` is antd Tag's resting surface and is what makes a FILTER CHIP legible before it is pressed — with `default` or `outline` the chip reads as transparent, which is the reported defect. Hover is the opaque --secondary-hover (not a translucent tint, which would shift between a page and a Card); pressed still wins over both.",
+      "name": "variant",
+      "type": "\"default\" | \"outline\" | \"soft\""
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Control size on the --control-height tier: xs 24px · sm 28px · md 32px · lg 36px. Pick the step the ROW already has — an xs chip is what lets a 24px-dense row carry a pressed/segmented control instead of someone hand-rolling one out of Buttons (gh#716). Every step clears the WCAG 2.2 SC 2.5.8 24px target floor, xs exactly.",
+      "name": "size",
+      "type": "\"xs\" | \"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "Corner shape, the SAME three values and the same two radius tokens `Button` and `Badge` use, so `shape=\"pill\"` means one thing across the library (gh#734). `pill` + `variant=\"soft\"` is the antd-Tag filter chip. On a ToggleGroup it propagates to every item through context, because a chip row is a row of pills, not one pill among squares.",
+      "name": "shape",
+      "type": "\"default\" | \"pill\" | \"sharp\""
+    },
+    {
+      "description": "Optional numeric count rendered as a borderless counter pill after the label — the SAME vocabulary Button defines (count/overflowCount/showZero), so a counted filter tab and a counted PRESSED chip read identically. This is what makes a faceted filter chip ('Open 42', selected or not) or a reaction chip ONE control: one button[aria-pressed], one tab stop, one focus ring, one accessible name. Formatted with Intl.NumberFormat in the active locale — never String(n), never a hand-rolled separator. NEVER nest a Badge inside a Toggle for this (a Badge is a status chip with its own surface: it double-borders the chip and puts two boxes where there is one control), and never hand-write a <span> counter inside a Toggle (that re-derives the Intl formatting, the cap and the pill's type ramp page-side).",
+      "name": "count",
+      "type": "number"
+    },
+    {
+      "defaultValue": "99",
+      "description": "Cap for `count` — above it the pill shows `{overflowCount}+` (e.g. 99+). The cap itself is locale-formatted too (vi: 1.000+). Same default and semantics as Button.",
+      "name": "overflowCount",
+      "type": "number"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Render the pill when `count` is 0. Same default as Button. Set false to hide an empty facet's pill while keeping the chip.",
+      "name": "showZero",
+      "type": "boolean"
+    },
+    {
+      "description": "Localized description of what the count MEANS, folded into the accessible name so the control never announces as a bare number. The name always comes out as '<label>, <count> <unit>' — from contents for a text chip ('Unread, 12 items'), or folded into `aria-label` for an icon/emoji chip ('thumbs up, 3 reactions'). REQUIRED in practice whenever the visible label is an icon or emoji. Pass a t()-resolved string; the library does not own this wording.",
+      "name": "countLabel",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "ToggleGroup",
+    "Button",
+    "Badge — the REMOVABLE chip (`onRemove` = antd Tag `closable`). Toggle is the SELECTABLE chip. Between them they cover antd's Tag family, which is why no `Tag` component exists here."
+  ],
+  "rules": [
+    3,
+    13,
+    45
+  ],
+  "storyPath": "data-entry/Toggle.stories.tsx",
+  "tagline": "Radix Toggle wrapper with default/outline variants and tokenized sizes.",
+  "usage": [
+    "DO provide an accessible label when the toggle only contains an icon.",
+    "DON'T use Toggle for multi-option selection; use ToggleGroup.",
+    "DO reach for `count` for a faceted filter chip, a counted segmented toggle or a reaction chip — Toggle is the primitive that owns BOTH the count and the pressed state.",
+    "DON'T write `<Button count={n} aria-pressed>` for this: buttonVariants has no pressed branch, so the state paints nothing and the chip is indistinguishable from an unpressed one.",
+    "DON'T nest a Badge (or a hand-written span) inside a Toggle to show a count — use `count`.",
+    "DO pass `countLabel` whenever the label is an icon or an emoji, so the chip does not announce as a bare number.",
+    "DON'T wrap the chip in a live region to announce count changes — Toggle deliberately does not, because a count driven by other people is not this control's status.",
+    "DO build a FILTER CHIP (antd `Tag.CheckableTag`) as `<Toggle variant=\"soft\" shape=\"pill\" count countLabel>` — that IS the chip: a resting --secondary fill, a pill corner, a real pressed state and the counter pill, in one control with one tab stop. There is no separate `Tag` / `CheckableTag` export and there will not be one (gh#734).",
+    "DON'T substitute `<Button variant=\"secondary\" shape=\"pill\" aria-pressed>` for it: Button has no pressed branch, so the chip paints identically selected and unselected (WCAG 1.4.1).",
+    "DO reach for `Badge onRemove` instead when the chip is REMOVABLE rather than selectable — an applied-filter chip that draws its own × is antd `Tag closable`, and this library put that on Badge, not on Toggle."
+  ],
+  "useCases": [
+    "Bold/italic toolbar buttons",
+    "Pinned filter toggles",
+    "Compact view mode buttons",
+    "Faceted filter chips with facet sizes (Open 42 / Closed 118)",
+    "A tag-filter panel — `variant=\"soft\" shape=\"pill\"` chips carrying tag counts (antd Tag.CheckableTag)",
+    "Reaction chips (emoji + how many reacted + whether YOU did)"
+  ]
+}

package/agent/components/ToggleGroup.json

@@ -0,0 +1,102 @@
+{
+  "example": "import { ToggleGroup, ToggleGroupItem } from \"@godxjp/ui/data-entry\";\n\n// size/variant are set ONCE on the group and reach every item.\n<ToggleGroup type=\"single\" size=\"lg\" variant=\"outline\" defaultValue=\"left\" aria-label=\"Alignment\">\n  <ToggleGroupItem value=\"left\">Left</ToggleGroupItem>\n  <ToggleGroupItem value=\"center\">Center</ToggleGroupItem>\n</ToggleGroup>",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "ToggleGroup",
+  "props": [
+    {
+      "description": "Selection mode.",
+      "name": "type",
+      "required": true,
+      "type": "\"single\" | \"multiple\""
+    },
+    {
+      "description": "Controlled selected value(s).",
+      "name": "value",
+      "type": "string | string[]"
+    },
+    {
+      "description": "Uncontrolled initial value(s).",
+      "name": "defaultValue",
+      "type": "string | string[]"
+    },
+    {
+      "description": "Selection callback.",
+      "name": "onValueChange",
+      "type": "(value: string | string[]) => void"
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "Visual style, PROVIDED TO EVERY ITEM via context — set it once on the group, not on each ToggleGroupItem. An explicit `variant` on an item still wins. The default is applied per item by toggleVariants, so an unset group emits no `data-variant` at all. `soft` (gh#734) is the chip fill: use it for a tag-filter panel, where `default`/`outline` leave the unselected chips reading as transparent.",
+      "name": "variant",
+      "type": "\"default\" | \"outline\" | \"soft\""
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "Corner shape, PROVIDED TO EVERY ITEM via context exactly as `variant`/`size` are — a chip row is a row of pills, so the decision belongs to the row (gh#734). An explicit `shape` on an item still wins. Same three values and same radius tokens as Button and Badge.",
+      "name": "shape",
+      "type": "\"default\" | \"pill\" | \"sharp\""
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Control size, PROVIDED TO EVERY ITEM via context — set it once on the group. An explicit `size` on an item still wins. Heights come from the --control-height tier (xs 24px · sm 28px · md 32px · lg 36px). Pick the step the ROW already has: xs is the one that fits a 24px-dense row (gh#716).",
+      "name": "size",
+      "type": "\"xs\" | \"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "description": "Disables the whole group; individual items also accept `disabled`.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "May the group end up with NOTHING selected? Omitted it may — pressing the selected item again clears it and reports `\"\"`, which is what a tag-filter row wants. THIS PROP DECIDES THE ARIA ROLE of a type=single group (gh#744), because emptiness is the one thing the two candidate roles disagree about: ARIA has no press-again-to-deselect for a radio, so a radiogroup the user just emptied is a state a screen reader cannot read out. Omitted → `role=\"group\"` + `aria-pressed` per item (no `aria-orientation`, which `group` does not take), arrow keys move FOCUS and Space/Enter presses. Set → `role=\"radiogroup\"` + `role=\"radio\"` / `aria-checked`, the selected item is the single tab stop, arrow keys move the SELECTION as APG requires, and pressing the selected item again keeps it. The name is React Aria's own (`useToggleGroupState`); neither antd nor Radix names the capability, and Radix's own single group emits radio roles while still allowing empty — the divergence is recorded in docs/DESIGN-AUTHORITY.md. On type=multiple it only keeps the last item selected; the roles do not move.",
+      "name": "disallowEmptySelection",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Let the row break onto further lines instead of running past its rail (gh#741) — the SAME name, boolean shape and `data-wrap` attribute `Flex` carries. OPT-IN, and the same default for every `variant`, both decided by measurement: a twelve-chip soft/pill xs row in a 320px rail is scrollWidth 644 > clientWidth 320 and 171.5px tall without it (chips squeezed to min-content, labels broken over up to seven lines) and scrollWidth 320 = clientWidth 320, 108px, 4 lines with it — while forcing wrap on all 18 groups of the docs page changed NONE of the 17 that already fit, at a 320px and a 1358px rail. So a default of true could only reflow rows that overflow today, silently, on an upgrade; and `variant=\"soft\"` gets no different default because forcing wrap changed nothing across default/outline/soft either — paint is not the axis that decides, content width against the rail is. The wrapped lines keep the group's single `gap`, so both axes measure the same 4px, and `flex-wrap` reorders nothing: arrow keys still walk the items in DOM order across lines, in LTR and in RTL.",
+      "name": "wrap",
+      "type": "boolean"
+    },
+    {
+      "description": "The counter-pill vocabulary is available PER ITEM, because variant/size are a group decision but the number is per-item data. Same vocabulary and same rendering as Toggle and Button: Intl.NumberFormat on the active locale, `{overflowCount}+` above the cap, and the count folded into that item's own accessible name. This is the faceted filter chip row (Open 42 / Closed 118) and the reaction row.",
+      "name": "ToggleGroupItem count / overflowCount / showZero / countLabel",
+      "type": "number | number | boolean | string"
+    }
+  ],
+  "related": [
+    "Segmented — the single-select sibling with a shared connected track. ToggleGroup is the generic multi/single toggle set; Segmented is the one-of-N control.",
+    "Toggle",
+    "RadioGroup"
+  ],
+  "rules": [
+    3,
+    13
+  ],
+  "storyPath": "data-entry/ToggleGroup.stories.tsx",
+  "subParts": [
+    "ToggleGroupItem"
+  ],
+  "tagline": "Single or multiple toggle selection on react-aria-components. On type=single the ARIA role follows `disallowEmptySelection`: omitted it is a `group` of `aria-pressed` buttons that MAY be all-off, set it is a `radiogroup` of `radio`s (gh#744).",
+  "usage": [
+    "DO choose type='single' for mutually exclusive toolbar modes.",
+    "DO add `disallowEmptySelection` to a type='single' group that is a SETTING — a view density, a sort order, a fiscal period. It is what makes the group a real radiogroup (role, aria-checked, one tab stop, arrow keys that move the selection) and it stops the second press from clearing the value, so you no longer need the `onValueChange={(v) => { if (v) setX(v) }}` guard that used to paper over it (gh#744).",
+    "DON'T add `disallowEmptySelection` to a FILTER row. Clearing a chip by pressing it again is what the user expects there, and without the prop the group says so honestly: `role=\"group\"` + `aria-pressed`, a set of buttons that may all be off.",
+    "DO choose type='multiple' for independent formatting toggles.",
+    "DO set `variant`/`size`/`shape` ONCE on the ToggleGroup — they propagate to every ToggleGroupItem through context. Repeating them on each item is redundant (it still works, and an explicit item prop overrides the group).",
+    "DO build a tag-filter panel as `<ToggleGroup type=\"multiple\" variant=\"soft\" shape=\"pill\" size=\"xs\">` with one counted `ToggleGroupItem` per tag — that is the whole antd `Tag.CheckableTag` row, one tab stop per chip, no `Tag` component needed (gh#734).",
+    "DO set `size`/`variant` on an individual ToggleGroupItem only when that ONE item must differ from the group.",
+    "DO add `wrap` to a TAG FILTER ROW — `<ToggleGroup type=\"multiple\" variant=\"soft\" shape=\"pill\" size=\"xs\" wrap>` is the whole folder-tag panel however many tags the folder has. This is what replaces the hand-built `<ul>` of individual `<Toggle>`s a row wider than its rail used to force (gh#741): that list loses exactly what the group owns — the shared `variant`/`size`/`shape` context, ONE `value`/`onValueChange`, and the group's arrow-key traversal, which keeps walking the chips in DOM order across the wrapped lines.",
+    "DON'T set `wrap` on a 3–4 item segmented group. Measured at a 320px rail it is one 32px line either way, so the prop buys nothing and only adds a way for a toolbar to reflow.",
+    "DON'T pass size='default' — it is not a member of the `xs | sm | md | lg` union. Omit `size` for the md default.",
+    "DO give the group an accessible name (`aria-label`) — it renders a `group` of toggle buttons (single, the default), a `radiogroup` (single + `disallowEmptySelection`) or a `toolbar` of toggle buttons (multiple), and all three need a name."
+  ],
+  "useCases": [
+    "Text alignment selector",
+    "Formatting toolbar",
+    "View density switcher",
+    "Tag filter row (wrap)"
+  ]
+}

package/agent/components/Toolbar.json

@@ -0,0 +1,120 @@
+{
+  "docPath": "navigation/toolbar",
+  "example": "import { Toolbar, ToolbarGroup } from \"@godxjp/ui/navigation\";\nimport { SearchInput, Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from \"@godxjp/ui/data-entry\";\n\n<Toolbar sticky hasActiveFilters={hasFilters} onClear={clearAll}>\n  <SearchInput placeholder=\"氏名・メールで検索\" value={q} onSearch={setQ} />\n  <ToolbarGroup label=\"ステータス\">\n    <Select value={status} onValueChange={setStatus}>\n      <SelectTrigger aria-label=\"ステータス\"><SelectValue /></SelectTrigger>\n      <SelectContent>\n        <SelectItem value=\"all\">すべて</SelectItem>\n        <SelectItem value=\"active\">有効</SelectItem>\n      </SelectContent>\n    </Select>\n  </ToolbarGroup>\n</Toolbar>",
+  "group": "navigation",
+  "importPath": "@godxjp/ui/navigation",
+  "name": "Toolbar",
+  "props": [
+    {
+      "description": "Filter controls. Place SearchInput directly; wrap each labelled Select/DatePicker in a ToolbarGroup.",
+      "name": "children",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Clear-all handler. When provided AND hasActiveFilters is true, Toolbar renders the trailing 'Clear filters' button.",
+      "name": "onClear",
+      "type": "() => void"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Whether any filter is applied — gates the clear-all button visibility.",
+      "name": "hasActiveFilters",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Pin the strip to the top of its scroll container while the list scrolls beneath it. Opt-in; tune offset/fill via the --filter-bar-sticky-offset / --filter-bar-sticky-background theme knobs.",
+      "name": "sticky",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "'wrap'",
+      "description": "Responsive overflow strategy. 'wrap' stacks the groups into one column below 640px, then wraps onto extra rows. 'scroll' keeps ONE bounded row at >=640px that scrolls inline (groups never shrink; the clear-all button stays sticky at the inline end) — use it when many filters with long JA/EN/VI labels would otherwise push the table below the fold. Below 640px 'scroll' still stacks, so a 390px viewport never hides a filter behind an invisible horizontal scroll.",
+      "name": "overflow",
+      "type": "'wrap' | 'scroll'"
+    },
+    {
+      "description": "Typed model — canonical search slot rendered FIRST in the strip with the token-owned consistent width (--filter-bar-search-width, full-width below 640px). Controlled triad value/defaultValue/onValueChange plus SearchInput's debounced onSearch. ANY model prop (search/filters/chips/onChipRemove/actions/resultCount/loading/disabled/error) switches the bar to the canonical model layout; with none of them the bar stays the plain children-composition toolbar unchanged.",
+      "name": "search",
+      "type": "FilterBarSearchProp"
+    },
+    {
+      "description": "Typed model — labelled domain-neutral Select filters rendered after the search slot in array order. Each: { value (stable identity), label (rendered as the control's REAL <label htmlFor> — WCAG 2.5.3), options, selected/defaultSelected/onSelectedChange, placeholder, disabled }. Width is token-owned (--filter-bar-filter-width).",
+      "name": "filters",
+      "type": "FilterBarFilterProp[]"
+    },
+    {
+      "description": "Typed model — applied-filter chips as pure consumer data ({ value, label, disabled }), rendered in a labelled row under the strip. Lifecycle: ADD = include the chip, REMOVE = onChipRemove(value) via each chip's × button, CLEAR-ALL = onClear. Keep label a string so the remove button's accessible name can quote it.",
+      "name": "chips",
+      "type": "FilterBarChipProp[]"
+    },
+    {
+      "description": "Remove ONE chip by its value. Required for chips to render their × remove button (each gets a localized 'Remove filter: {label}' accessible name).",
+      "name": "onChipRemove",
+      "type": "(value: string) => void"
+    },
+    {
+      "description": "Typed model — trailing action slot (e.g. the primary 'Add' Button) parked at the inline end of the strip, after the reset button in DOM/keyboard order.",
+      "name": "actions",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Typed model — localized, CLDR-pluralized result count ('{count} results' / '{count} 件の結果' / '{count} kết quả') announced politely via a role='status' line under the strip. 0 renders '0 results' as the visible empty state.",
+      "name": "resultCount",
+      "type": "number"
+    },
+    {
+      "description": "Typed model — marks the strip aria-busy (and sets data-loading on the root) while results are being (re)fetched.",
+      "name": "loading",
+      "type": "boolean"
+    },
+    {
+      "description": "Typed model — disables every model-rendered control: search, filter Selects, the reset button and the chip remove buttons. Custom children stay consumer-owned.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "description": "Typed model — consumer error content announced via role='alert' in the meta line, replacing the result count while present.",
+      "name": "error",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Extra classes on the root element.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "ToolbarGroup — the labelled wrapper for each individual filter control inside a Toolbar (SearchInput is placed directly, without a group).",
+    "DataTable.Toolbar — the in-table strip for column/density/bulk-action controls; Toolbar (this) is the page-level filter strip that sits ABOVE the table.",
+    "SearchInput — the debounced free-text control placed as the first child of Toolbar.",
+    "Badge — compose Badge + a sibling icon Button to render each active-filter chip; Badge itself is a non-interactive leaf."
+  ],
+  "rules": [
+    23,
+    44,
+    45,
+    46
+  ],
+  "storyPath": "navigation/toolbar.tsx",
+  "subParts": [
+    "ToolbarGroup"
+  ],
+  "tagline": "List-page filter strip (the framework FilterBar) — SearchInput + labelled ToolbarGroup filter slots + a clear-all affordance, optionally sticky.",
+  "usage": [
+    "DO prefer the typed model on a canonical list page — `search`/`filters`/`chips`/`onChipRemove`/`actions`/`resultCount` (+ `loading`/`disabled`/`error`) make the bar own layout, widths, chip lifecycle and keyboard order through --filter-bar-* tokens while ALL state stays consumer data. Children composition remains fully supported and unchanged when no model prop is passed.",
+    "DO place Toolbar ABOVE the table Card, never inside a `CardContent flush`. Put SearchInput as a direct child (it self-labels) and wrap every other control in a ToolbarGroup with a `label`.",
+    "DO drive the clear-all button with `hasActiveFilters` + `onClear` — it only renders when both are truthy. The strip collapses to a single stacked column below 640px automatically.",
+    "DO set `sticky` for long list pages so the filters stay reachable while scrolling; if a topbar sits above the list, raise `--filter-bar-sticky-offset` so the strip parks below it.",
+    "DO pass `controlId` on a ToolbarGroup that wraps ONE control and give that control the same `id` — the visible caption then becomes the control's real `<label htmlFor>` (WCAG 2.5.3 label-in-name). Without it the caption only names the group wrapper and the control itself is NAMELESS (axe: select-name / button-name), so you must fall back to an `aria-label` that repeats the caption.",
+    "DO switch to `overflow='scroll'` when a list page carries more filters than fit one row — one bounded row that scrolls inline keeps the table above the fold, where the default `wrap` would grow a 3-row strip with long JA/EN/VI labels. Never re-implement the geometry in the page: no page-local flex/grid/width rules on a filter strip.",
+    "DON'T build active-filter chips by nesting a Button inside a Badge (invalid markup + broken focus). Render each chip as a Badge label with a SIBLING icon Button (`aria-label` = 'clear <filter>'); a ghost `size='sm'` Button clears all.",
+    "DON'T hand-roll a debounced search box or a raw `<select>` — compose SearchInput and Select. Toolbar is layout + clear-all only; the controls own their own state and a11y."
+  ],
+  "useCases": [
+    "Master list screens (members, organizations, subscriptions, invoices) that need free-text search plus a few dropdown filters above a DataTable.",
+    "Sticky filter strip over a tall list where the filters must remain visible as the user scrolls the results.",
+    "Filtered views that surface applied conditions as removable chips (clear-one via each chip's × Button, clear-all via `onClear`)."
+  ]
+}

package/agent/components/Tooltip.json

@@ -0,0 +1,110 @@
+{
+  "example": "import {\n  Tooltip,\n  TooltipTrigger,\n  TooltipContent,\n} from \"@godxjp/ui/feedback\";\nimport { Button } from \"@godxjp/ui/general\";\nimport { Trash2Icon } from \"lucide-react\";\n\n// Icon-only button with tooltip label\nexport function DeleteAction() {\n  return (\n    <Tooltip>\n      <TooltipTrigger asChild>\n        <Button variant=\"ghost\" size=\"icon\" aria-label=\"Delete invoice\">\n          <Trash2Icon className=\"size-4\" />\n        </Button>\n      </TooltipTrigger>\n      <TooltipContent side=\"top\">Delete invoice</TooltipContent>\n    </Tooltip>\n  );\n}\n\n// Controlled tooltip (e.g. force-open for a tutorial)\nexport function ControlledExample() {\n  const [open, setOpen] = React.useState(false);\n  return (\n    <Tooltip open={open} onOpenChange={setOpen}>\n      <TooltipTrigger asChild>\n        <Button variant=\"outline\" onMouseEnter={() => setOpen(true)}>\n          Hover me\n        </Button>\n      </TooltipTrigger>\n      <TooltipContent side=\"bottom\" sideOffset={8}>\n        This is a controlled tooltip\n      </TooltipContent>\n    </Tooltip>\n  );\n}",
+  "group": "feedback",
+  "importPath": "@godxjp/ui/feedback",
+  "name": "Tooltip",
+  "props": [
+    {
+      "defaultValue": "200",
+      "description": "Milliseconds of hover before the tooltip opens. Accepted on both Tooltip (per-instance) and TooltipProvider (subtree-wide override).",
+      "name": "delayDuration",
+      "type": "number"
+    },
+    {
+      "description": "Controlled open state. Pair with onOpenChange to drive the tooltip programmatically.",
+      "name": "open",
+      "type": "boolean"
+    },
+    {
+      "description": "Callback fired when the open state changes. Required when using controlled 'open'.",
+      "name": "onOpenChange",
+      "type": "(open: boolean) => void"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Uncontrolled initial open state.",
+      "name": "defaultOpen",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "When true, the tooltip closes as soon as the pointer leaves the trigger (content is not hoverable). Passed through to Radix Root.",
+      "name": "disableHoverableContent",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "\"top\"",
+      "description": "On TooltipContent — preferred side for the tooltip panel. Radix flips automatically when there is not enough space.",
+      "name": "side",
+      "type": "'top' | 'right' | 'bottom' | 'left'"
+    },
+    {
+      "defaultValue": "6",
+      "description": "On TooltipContent — pixel gap between the trigger edge and the tooltip panel.",
+      "name": "sideOffset",
+      "type": "number"
+    },
+    {
+      "defaultValue": "\"center\"",
+      "description": "On TooltipContent — alignment relative to the trigger along the cross-axis.",
+      "name": "align",
+      "type": "'start' | 'center' | 'end'"
+    },
+    {
+      "defaultValue": "0",
+      "description": "On TooltipContent — pixel offset applied to the align position.",
+      "name": "alignOffset",
+      "type": "number"
+    },
+    {
+      "description": "On TooltipContent — extra Tailwind classes merged with the built-in panel styles (z-50, max-w-xs, rounded-md, shadow-md, text-xs).",
+      "name": "className",
+      "type": "string"
+    },
+    {
+      "description": "On TooltipContent — the text or JSX rendered inside the floating panel.",
+      "name": "children",
+      "required": true,
+      "type": "React.ReactNode"
+    },
+    {
+      "defaultValue": "false",
+      "description": "On TooltipTrigger — merges props onto the immediate child instead of wrapping with a <button>. Use when the trigger is already an interactive element.",
+      "name": "asChild",
+      "type": "boolean"
+    }
+  ],
+  "related": [
+    "Popover — use Popover (also @godxjp/ui/feedback) when the floating panel needs interactive content (forms, links, action menus) rather than read-only text. Tooltip is read-only; Popover is interactive.",
+    "HoverCard — for rich preview cards (user profiles, link previews) that appear on hover with more complex layout. Tooltip is for short text hints only.",
+    "Badge / StatusChip — for persistent, always-visible short labels inline with text; not hover-triggered. Use Tooltip when the hint should be hidden until hovered."
+  ],
+  "rules": [
+    3,
+    6,
+    23,
+    39
+  ],
+  "storyPath": "feedback/Tooltip.stories.tsx",
+  "subParts": [
+    "TooltipContent",
+    "TooltipProvider",
+    "TooltipTrigger"
+  ],
+  "tagline": "Radix-based hover/focus tooltip — self-providing, no app-level TooltipProvider required; compose Tooltip > TooltipTrigger > TooltipContent every time.",
+  "usage": [
+    "DO compose the full three-part structure every time: <Tooltip> wraps <TooltipTrigger> (the element that triggers the tip) and <TooltipContent> (the floating panel). Omitting any part silently produces nothing.",
+    "DO NOT add an app-level <TooltipProvider> — every <Tooltip> self-provides its own Radix Provider. Only add <TooltipProvider> at a subtree root when you need a shared delayDuration different from the default 200ms across many tooltips.",
+    "DO use asChild on TooltipTrigger when the trigger is already a Button, IconButton, or other interactive element — this avoids nesting a <button> inside a <button>, which is invalid HTML and breaks keyboard focus.",
+    "DON'T put non-interactive elements (plain <div>, <span>) as the direct TooltipTrigger child without asChild — Radix needs a focusable element for keyboard accessibility. Wrap the target in a <span tabIndex={0}> or use a Button.",
+    "For controlled usage (e.g. programmatic show/hide or testing), pass open + onOpenChange to <Tooltip>. For typical hover/focus behaviour, leave both unset (uncontrolled).",
+    "TooltipContent renders inside a Radix Portal appended to document.body — z-index and overflow:hidden on ancestors do NOT clip it. Use className to extend max width beyond the built-in max-w-xs if long text is expected."
+  ],
+  "useCases": [
+    "Explaining an icon-only Button action (e.g. a trash icon, a copy-to-clipboard icon) in a DataTable action column — show the label on hover without cluttering the row.",
+    "Annotating a truncated cell value in a DataTable (e.g. a long account name clipped with text-ellipsis) — reveal the full text on hover without a modal.",
+    "Providing contextual help for a form field label or an info icon next to an accounting term (e.g. 'AR Balance' with a short definition).",
+    "Surfacing keyboard shortcut hints next to toolbar buttons (e.g. '⌘K — open search') without adding visible text to the UI.",
+    "NOT for a disabled control's reason. A disabled Button gets `pointer-events: none` (control.css) and leaves the tab order, so a tooltip on one can never open — measured in Chromium: the same trigger showed 1 tooltip on hover while enabled and 0 while disabled, and `.focus()` on it left activeElement as BODY, so keyboard and touch get nothing either. Render the reason as VISIBLE TEXT before the action instead — that is what ServiceLauncherCard's `disabledReason` does, and it puts the explanation ahead of the control in DOM order (WCAG 1.3.2). See docs/CONSUMER-RULES.md."
+  ]
+}