@godxjp/ui 33.20.0 → 33.22.1

package/agent/components/EditorialPanel.json

@@ -0,0 +1,48 @@
+{
+  "example": "import { EditorialPanel, ResponsiveGrid } from \"@godxjp/ui/layout\";\n\n<ResponsiveGrid preset=\"panels\">\n  <EditorialPanel tag=\"NEXT\" title=\"More ways to discover.\" items={[\"Products and their contents\"]} />\n</ResponsiveGrid>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "EditorialPanel",
+  "props": [
+    {
+      "description": "The heading.",
+      "name": "title",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Short tag above it.",
+      "name": "tag",
+      "type": "ReactNode"
+    },
+    {
+      "description": "List items.",
+      "name": "items",
+      "type": "ReactNode[]"
+    },
+    {
+      "description": "Anything after the list.",
+      "name": "children",
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "2",
+      "description": "Heading level.",
+      "name": "level",
+      "type": "2 | 3"
+    }
+  ],
+  "related": [
+    "ResponsiveGrid — `preset=\"panels\"`."
+  ],
+  "rules": [
+    2,
+    6,
+    44,
+    45
+  ],
+  "tagline": "A bordered panel with a short tag, a heading and a list (gh#1440) — a roadmap group. Lay a row of them out with `ResponsiveGrid preset=\"panels\"` (tracks and gap are `--responsive-grid-panels-*`, re-declared at the theme's own steps). Geometry: `--editorial-panel-*`.",
+  "usage": [
+    "DO lay a row of panels out with `ResponsiveGrid preset=\"panels\"`."
+  ]
+}

package/agent/components/EditorialPillNav.json

@@ -0,0 +1,41 @@
+{
+  "example": "import { EditorialPillNav, EditorialPillNavItem } from \"@godxjp/ui/layout\";\n\n<EditorialPillNav aria-label=\"Browse by game\" label=\"YOUR GAME\">\n  <EditorialPillNavItem asChild icon=\"dot\"><a href=\"/cards/?game=pokemon\">Pokémon</a></EditorialPillNavItem>\n</EditorialPillNav>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "EditorialPillNav",
+  "props": [
+    {
+      "description": "Landmark name.",
+      "name": "aria-label",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "EditorialPillNavItem elements.",
+      "name": "children",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Visible lead text (aria-hidden; the landmark is named).",
+      "name": "label",
+      "type": "ReactNode"
+    }
+  ],
+  "related": [
+    "EditorialSection."
+  ],
+  "rules": [
+    2,
+    6,
+    44,
+    45
+  ],
+  "subParts": [
+    "EditorialPillNavItem"
+  ],
+  "tagline": "A horizontal band of section links (gh#1435) — a site's \"browse by game\" row: an optional lead label, then `EditorialPillNavItem`s (an icon or a small `\"dot\"` marker; `aria-current=\"page\"` on the link marks the current one). Scrolls sideways when it overflows. Geometry: `--editorial-pill-*`.",
+  "usage": [
+    "DO put it in `EditorialSection as=\"div\" tone=\"surface\" divider=\"end\"` for a band under the header."
+  ]
+}

package/agent/components/EditorialPrompt.json

@@ -0,0 +1,54 @@
+{
+  "example": "import { EditorialPrompt } from \"@godxjp/ui/layout\";\nimport { Lock } from \"lucide-react\";\n\n<EditorialPrompt icon={<Lock />} title=\"See more when you sign in\" description=\"Per-market prices and history are for members.\" action={<Button asChild><a href=\"/login\">Sign in</a></Button>} />",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "EditorialPrompt",
+  "props": [
+    {
+      "description": "Glyph in the round badge.",
+      "name": "icon",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Heading.",
+      "name": "title",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Paragraph.",
+      "name": "description",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Small note.",
+      "name": "note",
+      "type": "ReactNode"
+    },
+    {
+      "description": "The one action.",
+      "name": "action",
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "3",
+      "description": "Heading level.",
+      "name": "level",
+      "type": "2 | 3 | 4"
+    }
+  ],
+  "related": [
+    "Alert — status messages.",
+    "EmptyState — nothing to show."
+  ],
+  "rules": [
+    2,
+    6,
+    44,
+    45
+  ],
+  "tagline": "A polite inline invitation (gh#1438): a round glyph, a heading, a short paragraph and a note, with one action at the end (\"sign in to see more\"). Not a live region. Geometry: `--editorial-prompt-*`.",
+  "usage": [
+    "DO use Alert for a status message; this is an invitation that is there when the page loads."
+  ]
+}

package/agent/components/EditorialSearch.json

@@ -0,0 +1,112 @@
+{
+  "example": "import { EditorialSearch } from \"@godxjp/ui/layout\";\n\n<EditorialSearch label=\"Card name or number\" placeholder=\"Search a card\" submitLabel=\"Search\" action=\"/cards/\" onSearch={(q) => navigate(q)} />",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "EditorialSearch",
+  "props": [
+    {
+      "description": "Accessible label (visually hidden).",
+      "name": "label",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "Site search box, or a collection's own row (visible label, live count, no button). Default: \"inset\".",
+      "name": "variant",
+      "type": "\"inset\" | \"inline\""
+    },
+    {
+      "description": "Button text (inset; required there).",
+      "name": "submitLabel",
+      "type": "ReactNode"
+    },
+    {
+      "description": "inline: live count at the end of the row.",
+      "name": "count",
+      "type": "ReactNode"
+    },
+    {
+      "description": "inline: settle delay (ms). Default: 300.",
+      "name": "debounce",
+      "type": "number"
+    },
+    {
+      "description": "Placeholder.",
+      "name": "placeholder",
+      "type": "string"
+    },
+    {
+      "defaultValue": "\"q\"",
+      "description": "Query parameter.",
+      "name": "name",
+      "type": "string"
+    },
+    {
+      "description": "Initial query.",
+      "name": "defaultValue",
+      "type": "string"
+    },
+    {
+      "description": "Form action for the no-JS submit.",
+      "name": "action",
+      "type": "string"
+    },
+    {
+      "description": "Submit handler.",
+      "name": "onSearch",
+      "type": "(query: string) => void"
+    },
+    {
+      "description": "A scope control at the start of the box — the kit Select (borderless, width auto) with its own aria-label and name.",
+      "name": "scope",
+      "type": "ReactNode"
+    },
+    {
+      "description": "inset (gh#1447): grouped rows { id, label, items: [{ id, href, label, description?, media?, meta? }] } under the focused box; the field becomes an ARIA combobox.",
+      "name": "suggestions",
+      "type": "EditorialSearchSuggestionGroupProp[]"
+    },
+    {
+      "description": "inset: the popup's last row — all results.",
+      "name": "suggestionsFooter",
+      "type": "{ href: string; label: ReactNode }"
+    },
+    {
+      "description": "inset: accessible name of the listbox (default: label).",
+      "name": "suggestionsLabel",
+      "type": "string"
+    },
+    {
+      "description": "inset: field text after each edit; never mid-IME-composition, once on compositionend.",
+      "name": "onQueryChange",
+      "type": "(query: string) => void"
+    },
+    {
+      "description": "inset: the element suggestion rows render as (a router Link). Default \"a\".",
+      "name": "linkComponent",
+      "type": "ElementType"
+    },
+    {
+      "description": "Field id.",
+      "name": "id",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "SearchInput — a debounced filter field.",
+    "EditorialHero — the `search` slot."
+  ],
+  "rules": [
+    2,
+    6,
+    44,
+    45
+  ],
+  "tagline": "The inset site search (gh#1435): ONE bordered box holding a search glyph, the field and the submit button, under a visually hidden label that also names the `role=\"search\"` landmark. `onSearch` gets the trimmed query; without JavaScript the form GETs `action`. Geometry: `--editorial-search-*`.",
+  "usage": [
+    "DO use it for a site search that submits; use SearchInput for a live filter.",
+    "DO use variant=\"inline\" for a collection's own search row (visible label, live count) — gh#1439.",
+    "DO fetch suggestions yourself (debounce, abort, cache) from onQueryChange and pass the rows in; the kit neither debounces nor fetches (gh#1447).",
+    "DON'T put buttons or other controls in a suggestion row — each row is one link (role=option)."
+  ]
+}

package/agent/components/EditorialSection.json

@@ -0,0 +1,68 @@
+{
+  "example": "import { CenteredShell, EditorialSection, EditorialSectionHead } from \"@godxjp/ui/layout\";\n\n<CenteredShell preset=\"public-landing\" flow=\"sections\" topbar={<SiteHeader />} footer={<SiteFooter />}>\n  <EditorialSection tone=\"subtle\" divider=\"both\" spacing=\"section\" aria-labelledby=\"sets\">\n    <EditorialSectionHead titleId=\"sets\" title=\"Every expansion, a new chapter.\" />\n  </EditorialSection>\n</CenteredShell>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "EditorialSection",
+  "props": [
+    {
+      "description": "Band content, already in the landing column.",
+      "name": "children",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "Ground: page canvas, card surface, muted, or the hero wash.",
+      "name": "tone",
+      "type": "\"default\" | \"surface\" | \"subtle\" | \"hero\""
+    },
+    {
+      "defaultValue": "\"none\"",
+      "description": "Hairlines on the block edges.",
+      "name": "divider",
+      "type": "\"none\" | \"end\" | \"both\""
+    },
+    {
+      "defaultValue": "\"none\"",
+      "description": "Section rhythm as block padding.",
+      "name": "spacing",
+      "type": "\"none\" | \"section\""
+    },
+    {
+      "defaultValue": "\"section\"",
+      "description": "Landmark element.",
+      "name": "as",
+      "type": "\"section\" | \"div\" | \"nav\""
+    },
+    {
+      "description": "Landmark name.",
+      "name": "aria-label",
+      "type": "string"
+    },
+    {
+      "description": "Landmark name reference (the section head's titleId).",
+      "name": "aria-labelledby",
+      "type": "string"
+    },
+    {
+      "description": "Id on the band.",
+      "name": "id",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "CenteredShell — `flow=\"sections\"`.",
+    "EditorialHero, EditorialSectionHead — what goes inside."
+  ],
+  "rules": [
+    2,
+    6,
+    44,
+    45
+  ],
+  "tagline": "One full-width band of an editorial page (gh#1435): put it straight inside `CenteredShell preset=\"public-landing\" flow=\"sections\"`. Its ground (`tone`) and block hairlines (`divider`) run edge to edge while its content sits in the landing column (max width + gutter). `spacing=\"section\"` pads it by the section rhythm. Geometry: `--editorial-section-*`.",
+  "usage": [
+    "DO stack bands directly in a `flow=\"sections\"` shell — the shell drops its column cap, gap and main padding for them.",
+    "DO NOT nest a band inside a capped column: it cannot reach the edges there."
+  ]
+}

package/agent/components/EditorialSectionHead.json

@@ -0,0 +1,62 @@
+{
+  "example": "import { EditorialSectionHead, EditorialTextLink, Eyebrow } from \"@godxjp/ui/layout\";\n\n<EditorialSectionHead\n  eyebrow={<Eyebrow>THE TCG-M JOURNAL</Eyebrow>}\n  title=\"A little knowledge. More enjoyment.\"\n  titleId=\"journal\"\n  action={<EditorialTextLink asChild><a href=\"/journal/\">View all</a></EditorialTextLink>}\n/>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "EditorialSectionHead",
+  "props": [
+    {
+      "description": "The heading.",
+      "name": "title",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Kicker above it.",
+      "name": "eyebrow",
+      "type": "ReactNode"
+    },
+    {
+      "description": "One line under it.",
+      "name": "description",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Trailing call to action.",
+      "name": "action",
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "2",
+      "description": "Heading level.",
+      "name": "level",
+      "type": "2 | 3"
+    },
+    {
+      "defaultValue": "\"section\"",
+      "description": "A module's smaller head (gh#1438).",
+      "name": "scale",
+      "type": "\"section\" | \"module\""
+    },
+    {
+      "description": "Id on the title, for the section's aria-labelledby.",
+      "name": "titleId",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "EditorialSection, EditorialTextLink."
+  ],
+  "rules": [
+    2,
+    6,
+    44,
+    45
+  ],
+  "subParts": [
+    "EditorialTextLink"
+  ],
+  "tagline": "A section's head (gh#1435): kicker, an editorial h2, one line of description and a trailing action on the title's row — usually an `EditorialTextLink` \"view all →\" (an inline-flex link with a trailing arrow, `asChild` for a router link). Geometry: `--editorial-section-head-*`, `--editorial-text-link-*`.",
+  "usage": [
+    "DO name the EditorialSection with `aria-labelledby={titleId}`."
+  ]
+}

package/agent/components/EditorialStats.json

@@ -0,0 +1,32 @@
+{
+  "example": "import { EditorialStats } from \"@godxjp/ui/layout\";\n\n<EditorialStats aria-label=\"Collection totals\" items={[{ label: \"Items in your collection\", value: \"12\", unit: \"items\", note: \"A collection of things you love.\" }, { label: \"Single cards\", value: \"9\", unit: \"items\" }, { label: \"Sealed products\", value: \"3\", unit: \"items\" }]} />",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "EditorialStats",
+  "props": [
+    {
+      "description": "The tiles.",
+      "name": "items",
+      "required": true,
+      "type": "{ label: ReactNode; value: ReactNode; unit?: ReactNode; note?: ReactNode }[]"
+    },
+    {
+      "description": "Name of the list.",
+      "name": "aria-label",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "StatCard — an application KPI tile."
+  ],
+  "rules": [
+    2,
+    6,
+    44,
+    45
+  ],
+  "tagline": "A strip of figure tiles on unequal tracks (gh#1439, default `1.4fr 1fr 1fr`): label, large tabular figure with a small unit, optional note. The first tile is the lead (quiet ground; a theme can span it across a phone row with its figure beside the label). Geometry: `--editorial-stats-*`.",
+  "usage": [
+    "DO format the figures with Intl before passing them."
+  ]
+}

package/agent/components/EditorialTextButton.json

@@ -0,0 +1,47 @@
+{
+  "example": "import { EditorialTextButton } from \"@godxjp/ui/layout\";\n\n<EditorialTextButton onClick={reset}>Reset display preferences</EditorialTextButton>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "EditorialTextButton",
+  "props": [
+    {
+      "description": "Label.",
+      "name": "children",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Trailing glyph.",
+      "name": "icon",
+      "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"
+    }
+  ],
+  "related": [
+    "EditorialTextLink — the bold arrow link of a section head.",
+    "Button — actions with weight."
+  ],
+  "rules": [
+    2,
+    6,
+    44,
+    45
+  ],
+  "tagline": "An underlined text action in the primary tone (gh#1439): \"Reset display preferences\", \"Your collection →\". A `<button>` by default; `asChild` turns a router link into it; `icon` trails the label. Geometry: `--editorial-text-button-*`.",
+  "usage": [
+    "DO use it for a quiet secondary action next to copy; a primary action is a Button."
+  ]
+}

package/agent/components/EditorialToggleGroup.json

@@ -0,0 +1,52 @@
+{
+  "example": "import { EditorialToggleGroup } from \"@godxjp/ui/layout\";\nimport { Grid2x2, List } from \"lucide-react\";\n\n<EditorialToggleGroup aria-label=\"View\" variant=\"icon\" value={view} onValueChange={setView} items={[{ value: \"grid\", label: \"Grid view\", icon: <Grid2x2 /> }, { value: \"list\", label: \"List view\", icon: <List /> }]} />",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "EditorialToggleGroup",
+  "props": [
+    {
+      "description": "Group name.",
+      "name": "aria-label",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "The toggles; label is the text and the accessible name.",
+      "name": "items",
+      "required": true,
+      "type": "{ value: string; label: string; icon?: ReactNode }[]"
+    },
+    {
+      "description": "Pressed toggle.",
+      "name": "value",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "Change handler.",
+      "name": "onValueChange",
+      "required": true,
+      "type": "(value: string) => void"
+    },
+    {
+      "description": "Labels, or framed icon-only buttons. Default: \"text\".",
+      "name": "variant",
+      "type": "\"text\" | \"icon\""
+    }
+  ],
+  "related": [
+    "Segmented — a track with a lifted slab.",
+    "EditorialFilterBar — underlined toggles."
+  ],
+  "rules": [
+    2,
+    6,
+    44,
+    45
+  ],
+  "tagline": "One-of-N toggles of the editorial account family (gh#1439): a named `role=\"group\"` of `aria-pressed` buttons. `variant=\"text\"` is a filter row (pressed = filled, bordered); `variant=\"icon\"` a framed icon-only switch such as grid / list view, each button named by its label. Geometry: `--editorial-toggle-group-*`.",
+  "usage": [
+    "DO use it above a collection to filter it or switch its view; the collection is yours.",
+    "DO pass a lucide icon per item for the icon variant — the label stays the button's name."
+  ]
+}

package/agent/components/EditorialToolbar.json

@@ -0,0 +1,45 @@
+{
+  "example": "import { Select } from \"@godxjp/ui/data-entry\";\nimport { Button } from \"@godxjp/ui/general\";\nimport { EditorialToggleGroup, EditorialToolbar } from \"@godxjp/ui/layout\";\n\n<EditorialToolbar divider start={<EditorialToggleGroup aria-label=\"Type\" value={type} onValueChange={setType} items={[{ value: \"all\", label: \"All items\" }, { value: \"card\", label: \"Cards\" }]} />} end={<Button>Add an item</Button>} />\n<EditorialToolbar summary={{ count: \"396 results\", note: \"Prices are reference values.\" }} end={<Select aria-label=\"Sort\" value={sort} onValueChange={setSort} options={sorts} />} />",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "EditorialToolbar",
+  "props": [
+    {
+      "description": "Listing summary: result count (announced politely) and a note under it.",
+      "name": "summary",
+      "type": "{ count?: ReactNode; note?: ReactNode }"
+    },
+    {
+      "description": "Start cluster.",
+      "name": "start",
+      "type": "ReactNode"
+    },
+    {
+      "description": "End cluster.",
+      "name": "end",
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Hairline under the row.",
+      "name": "divider",
+      "type": "boolean"
+    }
+  ],
+  "related": [
+    "Toolbar — the application filter strip.",
+    "EditorialToggleGroup — the toggles it holds.",
+    "EditorialFilterPanel — the filters above a listing."
+  ],
+  "rules": [
+    2,
+    6,
+    44,
+    45
+  ],
+  "tagline": "The row above a collection (gh#1438, gh#1439): an optional `summary` (result count as a polite live region + a short note), a start cluster (an EditorialToggleGroup filter) and an end cluster (order Select, view switch, primary action), optionally over a hairline (`divider`). With a summary it is a listing row that keeps one line; without one a theme stacks it on a phone with `--editorial-toolbar-display: block`. Geometry: `--editorial-toolbar-*`.",
+  "usage": [
+    "DO keep the count text short; a phone theme may hide it (--editorial-toolbar-count-display).",
+    "DO keep search in its own row below it."
+  ]
+}

package/agent/components/Eyebrow.json

@@ -0,0 +1,39 @@
+{
+  "example": "import { Eyebrow } from \"@godxjp/ui/layout\";\n\n<Eyebrow>THE CURATED SELECTION</Eyebrow>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "Eyebrow",
+  "props": [
+    {
+      "description": "Kicker text.",
+      "name": "children",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "\"ruled\"",
+      "description": "With or without the leading rule.",
+      "name": "variant",
+      "type": "\"ruled\" | \"plain\""
+    },
+    {
+      "defaultValue": "\"p\"",
+      "description": "Element.",
+      "name": "as",
+      "type": "\"p\" | \"span\" | \"div\""
+    }
+  ],
+  "related": [
+    "EditorialSectionHead."
+  ],
+  "rules": [
+    2,
+    6,
+    44,
+    45
+  ],
+  "tagline": "The small uppercase kicker above an editorial heading (gh#1435), led by a short ornament rule (`variant=\"ruled\"`, default) or bare (`\"plain\"`). Face, size, tracking, colour and rule: `--editorial-eyebrow-*`, `--editorial-kicker-*`, `--editorial-ornament-color`.",
+  "usage": [
+    "DO use it in the eyebrow slot of EditorialHero / EditorialSectionHead / EditorialBanner."
+  ]
+}