@godxjp/ui 33.20.0 → 33.22.1

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/Markdown.json

@@ -78,6 +78,11 @@
       "description": "Fenced code in a known language is tokenised at parse time as `<span data-code-token>` with the kit's twelve names, which Prose colours (renderer v6). `false` leaves plain text for a host `pre` with its own highlighter.",
       "name": "highlight",
       "type": "boolean"
+    },
+    {
+      "description": "Host renderers for container directives the kit does not model, by name (`{ poll: (b) => <PollCard … /> }`). Each gets `{ name, label, attributes, source, body, children }` — label / source / body as written, `children` the rendered body without the label (a `::::form`'s `:::poll` cards). Return `undefined` to render the block as an unknown directive (its content in `div.ui-prose-directive`), which is also what an unregistered name renders. `toggle` / `columns` / `column` cannot be overridden.",
+      "name": "directives",
+      "type": "Record<string, (block: DirectiveRenderProps) => ReactNode | undefined>"
     }
   ],
   "related": [
@@ -94,6 +99,7 @@
     "DO `<Prose><Markdown>{body}</Markdown></Prose>` for every rendered body (wiki page, issue, mail).",
     "DO record `MARKDOWN_FORMAT` and `RENDERER_VERSION` on stored versions.",
     "DO `import \"@godxjp/markdown/katex.css\"` once in the app: `$…$`, `$$…$$` and ```math are drawn by KaTeX at parse time (trust: false, renderer v6) and need its stylesheet and fonts. A single `$` follows Pandoc's rule, so `$5 and $10` stays text.",
+    "DO import `Markdown` from `@godxjp/markdown/lazy` in a client-rendered app: KaTeX (+ its stylesheet, no global katex.css import needed) and highlight.js load only when a body has math or a fence with a language, then the body re-renders. The default entry stays eager because a server or Worker render is synchronous; a server or a hydrating client using `/lazy` awaits `preloadMarkdownRuntime(body)` first.",
     "DON'T assemble react-markdown + rehype-sanitize per app, add rehype-raw, or render Mermaid yourself — `checkMermaidSvg` is the gate."
   ]
 }

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/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",