@godxjp/ui 33.19.0 → 33.21.0

package/agent/components/HoldingCard.json

@@ -0,0 +1,69 @@
+{
+  "example": "import { HoldingCard, HoldingCardAction } from \"@godxjp/ui/layout\";\nimport { Trash2 } from \"lucide-react\";\n\n<HoldingCard media={<a href=\"/cards/1/\"><img src=\"/card.png\" alt=\"\" /></a>} overline=\"Single card\" title={<a href=\"/cards/1/\">Pikachu</a>} meta=\"025/165\" tags={[\"NM\", \"× 2\"]} purchase={{ label: \"Purchase / item\", value: \"¥1,200\" }} actions={<HoldingCardAction icon={<Trash2 />} onClick={remove}>Remove</HoldingCardAction>} />",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "HoldingCard",
+  "props": [
+    {
+      "description": "Link around the image (the picture ground).",
+      "name": "media",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Line above the title.",
+      "name": "overline",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Title (a link).",
+      "name": "title",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Heading level. Default: 2.",
+      "name": "level",
+      "type": "2 | 3"
+    },
+    {
+      "description": "Meta line.",
+      "name": "meta",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Outlined tags.",
+      "name": "tags",
+      "type": "ReactNode[]"
+    },
+    {
+      "description": "Purchase line.",
+      "name": "purchase",
+      "type": "{ label: ReactNode; value: ReactNode }"
+    },
+    {
+      "description": "Date line.",
+      "name": "date",
+      "type": "ReactNode"
+    },
+    {
+      "description": "HoldingCardAction elements.",
+      "name": "actions",
+      "type": "ReactNode"
+    }
+  ],
+  "related": [
+    "HoldingGrid — the track.",
+    "HoldingCardAction — its actions."
+  ],
+  "rules": [
+    2,
+    6,
+    44,
+    45
+  ],
+  "tagline": "One owned item (gh#1439): a picture ground (the consumer's link around an image), overline, title, meta, outlined tags (the last set apart), the purchase line, a date and HoldingCardActions. Its geometry follows the enclosing HoldingGrid view. Geometry: `--editorial-holding-card-*`.",
+  "usage": [
+    "DO keep the owner's purchase price apart from reference prices."
+  ]
+}

package/agent/components/HoldingCardAction.json

@@ -0,0 +1,51 @@
+{
+  "example": "import { HoldingCardAction } from \"@godxjp/ui/layout\";\nimport { Pencil } from \"lucide-react\";\n\n<HoldingCardAction icon={<Pencil />} asChild><a href=\"/collection/1/edit/\">Edit</a></HoldingCardAction>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "HoldingCardAction",
+  "props": [
+    {
+      "description": "Leading glyph.",
+      "name": "icon",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Label.",
+      "name": "children",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Render the child link as the action.",
+      "name": "asChild",
+      "type": "boolean"
+    },
+    {
+      "description": "Activation handler.",
+      "name": "onClick",
+      "type": "() => void"
+    },
+    {
+      "description": "Native disabled.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "description": "Accessible name when the label is not enough.",
+      "name": "aria-label",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "HoldingCard — its card."
+  ],
+  "rules": [
+    2,
+    6,
+    44,
+    45
+  ],
+  "tagline": "A quiet glyph + label action of a HoldingCard (gh#1439): edit, remove. A `<button>` by default; `asChild` turns a router link into it.",
+  "usage": [
+    "DO name a destructive action with the item (\"Remove Pikachu\") through aria-label."
+  ]
+}

package/agent/components/HoldingGrid.json

@@ -0,0 +1,37 @@
+{
+  "example": "import { HoldingCard, HoldingGrid } from \"@godxjp/ui/layout\";\n\n<HoldingGrid view=\"grid\" aria-label=\"Your collection\"><HoldingCard media={<a href=\"/cards/1/\"><img src=\"/card.png\" alt=\"\" /></a>} title={<a href=\"/cards/1/\">Pikachu</a>} /></HoldingGrid>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "HoldingGrid",
+  "props": [
+    {
+      "description": "Tiles or rows. Default: \"grid\".",
+      "name": "view",
+      "type": "\"grid\" | \"list\""
+    },
+    {
+      "description": "Name of the list.",
+      "name": "aria-label",
+      "type": "string"
+    },
+    {
+      "description": "HoldingCards.",
+      "name": "children",
+      "type": "ReactNode"
+    }
+  ],
+  "related": [
+    "HoldingCard — its items.",
+    "CatalogCard — a catalogue tile."
+  ],
+  "rules": [
+    2,
+    6,
+    44,
+    45
+  ],
+  "tagline": "The track of HoldingCards (gh#1439): `view=\"grid\"` lays tiles on `--editorial-holding-grid-track-size` (default four columns); `view=\"list\"` turns the same cards into wide rows (`140px 1fr`, body on `1.5fr 1fr 140px`). A list (`ul`) of the cards.",
+  "usage": [
+    "DO switch the view with an EditorialToggleGroup variant=\"icon\"; never swap to a data table."
+  ]
+}

package/agent/components/NumberInput.json

@@ -111,6 +111,11 @@
       "name": "suffix",
       "type": "React.ReactNode"
     },
+    {
+      "description": "How the field takes its inline space, as `Select` and the pickers mean it (gh#1448). `full` fills the line; `auto` is sized to the widest value the bounds allow (formatted `min` / `max`, 6 characters when unbounded) plus the steppers — a quantity stepper outside a FormField, e.g. in a `ListRow` trailing slot; `bounded` holds `--control-bounded-width`. Inside a FormField, `controlWidth` still sizes it. Default: \"full\".",
+      "name": "width",
+      "type": "\"full\" | \"auto\" | \"bounded\""
+    },
     {
       "description": "Form field name — submits its value natively.",
       "name": "name",

package/agent/components/PriceSummary.json

@@ -0,0 +1,32 @@
+{
+  "example": "import { PriceSummary } from \"@godxjp/ui/layout\";\n\n<PriceSummary items={[{ key: \"sell\", label: \"Asking\", value: \"¥32,800\", caption: \"Japan · JPY\" }]} context={{ label: \"Compared\", value: \"JP · NM · Raw\" }} />",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "PriceSummary",
+  "props": [
+    {
+      "description": "Figure cells.",
+      "name": "items",
+      "required": true,
+      "type": "{ key; label; value; caption? }[]"
+    },
+    {
+      "description": "Context cell (conditions compared).",
+      "name": "context",
+      "type": "{ label; value; caption? }"
+    }
+  ],
+  "related": [
+    "Statistic — one KPI in a dashboard."
+  ],
+  "rules": [
+    2,
+    6,
+    44,
+    45
+  ],
+  "tagline": "A joined strip of headline figures (gh#1438): one bordered surface split by hairlines, each cell a label, a figure in the number face and a caption, with an optional wider context cell on the subtle ground. Geometry: `--editorial-price-summary-*`.",
+  "usage": [
+    "DO keep each value one formatted figure; put the source and date in caption."
+  ]
+}

package/agent/components/SettingsLayout.json

@@ -0,0 +1,31 @@
+{
+  "example": "import { SettingsLayout, SettingsPanel } from \"@godxjp/ui/layout\";\n\n<SettingsLayout aside={<p>Preferences are saved in this browser.</p>}><SettingsPanel number=\"01\" title=\"Language\" /></SettingsLayout>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "SettingsLayout",
+  "props": [
+    {
+      "description": "Sticky rail.",
+      "name": "aside",
+      "type": "ReactNode"
+    },
+    {
+      "description": "SettingsPanels.",
+      "name": "children",
+      "type": "ReactNode"
+    }
+  ],
+  "related": [
+    "SettingsPanel — the panels."
+  ],
+  "rules": [
+    2,
+    6,
+    44,
+    45
+  ],
+  "tagline": "A settings page (gh#1439): a sticky rail (`aside`, default 260px, `--editorial-settings-layout-aside-inset` from the top) beside the panels, gap 64px. A theme hides the rail on narrow screens with `--editorial-settings-layout-aside-display: none` and one track.",
+  "usage": [
+    "DO put a short note and one link in the rail, never controls."
+  ]
+}

package/agent/components/SettingsPanel.json

@@ -0,0 +1,53 @@
+{
+  "example": "import { SettingsPanel } from \"@godxjp/ui/layout\";\n\n<SettingsPanel number=\"02\" title=\"Appearance\" description=\"Card artwork keeps its colours.\" />",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "SettingsPanel",
+  "props": [
+    {
+      "description": "Section number.",
+      "name": "number",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Title.",
+      "name": "title",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Heading level. Default: 2.",
+      "name": "level",
+      "type": "2 | 3"
+    },
+    {
+      "description": "Copy.",
+      "name": "description",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Fields.",
+      "name": "children",
+      "type": "ReactNode"
+    },
+    {
+      "description": "id of the title (names the section).",
+      "name": "titleId",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "SettingsLayout — the page.",
+    "EditorialPanel — a reading-page panel."
+  ],
+  "rules": [
+    2,
+    6,
+    44,
+    45
+  ],
+  "tagline": "One bordered settings section (gh#1439): a number in the figure face beside the title and its description, then the fields (a Form). Geometry: `--editorial-settings-panel-*`.",
+  "usage": [
+    "DO put the fields in a Form (columns={2} for paired fields)."
+  ]
+}

package/agent/components/Tabs.json

@@ -5,9 +5,9 @@
   "name": "Tabs",
   "props": [
     {
-      "description": "Optional data-driven tab list. When provided, Tabs renders all triggers and content panels. When Tabs owns the initial selection (no `value`, and no `defaultValue` naming an existing ENABLED item), it falls back to the first item that is NOT `disabled` — never a disabled one — and selects nothing if every item is disabled. `icon` is a leading glyph in the trigger (Ant Design `Tab.icon`). `closable` / `closeIcon` only apply under `variant=\"editable-card\"`; `closable: false` opts one tab out of removal (Ant Design `getRemovable`). `forceRender` (Ant Design `Tab.forceRender`) mounts THAT panel up front and keeps it mounted while another tab is selected, without switching the whole strip over with `destroyOnHidden={false}` — antd's per-item `destroyOnHidden` is deliberately not offered, because on this component \"kept mounted\" is one state and it would be a second spelling of `forceRender`. `count` (+ `overflowCount`, default 99; `showZero`, default true; `countLabel`) draws the counter pill beside the label — 「未対応 12」 — in the SAME vocabulary Button and Toggle publish and through the same helper, formatted with `Intl.NumberFormat` in the active locale. Pass `countLabel` to say what the number is: the pill is `aria-hidden` and an `sr-only` clause carries the digits, so the tab announces \"未対応, 12 件の課題\" and never the concatenated \"未対応12\". Prefer this over antd's answer, which is to put a Badge inside `label` — with the number inside the label the package owns neither its size nor its tone as the tab moves between selected / unselected / disabled, so every consumer aligns it differently. `href` makes the strip a ROUTE strip (gh#1364) — see `linkComponent`.",
+      "description": "Optional data-driven tab list. When provided, Tabs renders all triggers and content panels. When Tabs owns the initial selection (no `value`, and no `defaultValue` naming an existing ENABLED item), it falls back to the first item that is NOT `disabled` — never a disabled one — and selects nothing if every item is disabled. `icon` is a leading glyph in the trigger (Ant Design `Tab.icon`). `closable` / `closeIcon` only apply under `variant=\"editable-card\"`; `closable: false` opts one tab out of removal (Ant Design `getRemovable`). `forceRender` (Ant Design `Tab.forceRender`) mounts THAT panel up front and keeps it mounted while another tab is selected, without switching the whole strip over with `destroyOnHidden={false}` — antd's per-item `destroyOnHidden` is deliberately not offered, because on this component \"kept mounted\" is one state and it would be a second spelling of `forceRender`. `countTone=\"neutral\"` keeps passive counts muted in both selected and resting states; omitted/\"accent\" preserves the existing muted resting and accent selected appearance. The compound TabsTrigger accepts the same countTone. Neutral uses --tabs-count-neutral-background/color; accent uses the existing --tabs-count-background/color and --tabs-count-active-background/color knobs (all role mirrors). `count` (+ `overflowCount`, default 99; `showZero`, default true; `countLabel`) draws the counter pill beside the label — 「未対応 12」 — in the SAME vocabulary Button and Toggle publish and through the same helper, formatted with `Intl.NumberFormat` in the active locale. Pass `countLabel` to say what the number is: the pill is `aria-hidden` and an `sr-only` clause carries the digits, so the tab announces \"未対応, 12 件の課題\" and never the concatenated \"未対応12\". Prefer this over antd's answer, which is to put a Badge inside `label` — with the number inside the label the package owns neither its size nor its tone as the tab moves between selected / unselected / disabled, so every consumer aligns it differently. `href` makes the strip a ROUTE strip (gh#1364) — see `linkComponent`.",
       "name": "items",
-      "type": "{ value: string; label: React.ReactNode; content?: React.ReactNode; href?: string; disabled?: boolean; icon?: React.ReactNode; closable?: boolean; closeIcon?: React.ReactNode; forceRender?: boolean; count?: number; overflowCount?: number; showZero?: boolean; countLabel?: string }[]"
+      "type": "{ value: string; label: React.ReactNode; content?: React.ReactNode; href?: string; disabled?: boolean; icon?: React.ReactNode; closable?: boolean; closeIcon?: React.ReactNode; forceRender?: boolean; count?: number; countTone?: \"neutral\" | \"accent\"; overflowCount?: number; showZero?: boolean; countLabel?: string }[]"
     },
     {
       "description": "Controlled active tab key.",

package/agent/components/ThemePicker.json

@@ -0,0 +1,54 @@
+{
+  "example": "import { ThemePicker } from \"@godxjp/ui/layout\";\nimport { Moon, Sun } from \"lucide-react\";\n\n<ThemePicker legend=\"Choose a theme\" value={theme} onValueChange={setTheme} options={[{ value: \"light\", label: \"Light\", icon: <Sun />, preview: \"light\" }, { value: \"dark\", label: \"Dark\", icon: <Moon />, preview: \"dark\" }]} />",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "ThemePicker",
+  "props": [
+    {
+      "description": "Name of the group (visually hidden).",
+      "name": "legend",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "The choices.",
+      "name": "options",
+      "required": true,
+      "type": "{ value: string; label: string; icon?: ReactNode; preview: \"light\" | \"dark\" | \"system\" }[]"
+    },
+    {
+      "description": "Controlled value.",
+      "name": "value",
+      "type": "string"
+    },
+    {
+      "description": "Uncontrolled initial value.",
+      "name": "defaultValue",
+      "type": "string"
+    },
+    {
+      "description": "Change handler.",
+      "name": "onValueChange",
+      "type": "(value: string) => void"
+    },
+    {
+      "description": "Name of the radio inputs.",
+      "name": "name",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "AppSettingPicker kind=\"theme\" — a compact select.",
+    "Radio — plain radios."
+  ],
+  "rules": [
+    2,
+    6,
+    44,
+    45
+  ],
+  "tagline": "An illustrated radio group for the colour theme (gh#1439): each choice is a painted preview of the interface — light, dark, or the system split — over its glyph and label. Native radios in a fieldset (arrow keys move), the checked preview ringed in the primary tone. Geometry: `--editorial-theme-picker-*`.",
+  "usage": [
+    "DO apply the theme at once; no Save button."
+  ]
+}

package/agent/components/TopbarItem.json

@@ -25,6 +25,11 @@
       "name": "labelHideBelow",
       "type": "BreakpointProp"
     },
+    {
+      "description": "Remove the whole cell FROM a breakpoint step upwards (Flex hideFrom's contract) — a phone-only cell such as the menu trigger that opens the same navigation in a sheet (gh#1428).",
+      "name": "hideFrom",
+      "type": "BreakpointProp"
+    },
     {
       "description": "Overlaid count; does not change the bar cell width. Rendered under asChild too (gh#1171): the pill goes inside the child element after its children, so `<TopbarItem asChild badge={3}><a href=\"/notifications\">…</a></TopbarItem>` keeps its count. Nothing renders for `undefined`, `\"\"` or the number `0` (gh#1341) — pass the count as it is, never `count === 0 ? undefined : count`; pass the string `\"0\"` to show a zero on purpose.",
       "name": "badge",