@godxjp/ui 31.26.2 → 31.28.0

package/agent/START-HERE.md

@@ -3,7 +3,7 @@
 You are about to write code against a design system you did not author. This file is the whole
 contract. Read it before you write JSX.
 
-**This catalog describes `@godxjp/ui` 31.26.2.** If the project you are editing has a different
+**This catalog describes `@godxjp/ui` 31.28.0.** If the project you are editing has a different
 version in its `package.json`, read the pinned catalog for THAT version instead
 (`…/v<their-version>/agent/…`). A catalog newer than the installed package describes props that do
 not exist yet; older, and it hides props that do. Neither failure announces itself.
@@ -47,7 +47,7 @@ Then ask it: `search_components`, `get_component`, `get_tokens`, `get_rule`, `li
    task is a task** — "build a settings page", "confirm a destructive delete", "a list page with
    filters" — start HERE, not at the components. Then fetch `patterns/<name>.json` for complete,
    copy-paste-ready code. A component index answers "does X exist"; it cannot answer "build Y".
-1. `components-index.json` — 50 KB, all 181 components as name + group +
+1. `components-index.json` — 51 KB, all 184 components as name + group +
    tagline. Read this when you already know the SHAPE you need. Each entry may carry `absorbed`:
    names that **do not exist** and map to it — `Combobox`, `Autocomplete`, `CountrySelect` and
    `SearchSelect` are all `Select`. If you are about to hand-roll something, search this field
@@ -56,15 +56,15 @@ Then ask it: `search_components`, `get_component`, `get_tokens`, `get_rule`, `li
    its `importPath`, and its examples. Fetch only the handful you picked in step 1.
 3. `rules.json` — 50 cardinal rules. The ones about raw HTML and hardcoded colour are not
    style advice.
-4. `tokens.json` — 2137 design tokens, each tagged with its `tier`. **If you were handed a
+4. `tokens.json` — 2155 design tokens, each tagged with its `tier`. **If you were handed a
    brand, read the 211 `foundation` entries first** — `--primary`, `--background`,
    `--radius`, `--font-size-base` are the handful everything else derives from. The
-   1822 `component` entries are per-part knobs; reach for one only when a role is
+   1832 `component` entries are per-part knobs; reach for one only when a role is
    right everywhere except one component.
 5. `anti-ai-tells.json` — 26 shapes that make generated UI look generated, each with the
    fix. Read before you reach for a gradient hero or a wall of coloured chips.
 
-**Do not fetch `components.json`.** It is 1.2 MB, and most URL fetchers truncate a
+**Do not fetch `components.json`.** It is 1.3 MB, and most URL fetchers truncate a
 response that size and return the head without telling you. You get the first few entries, believe
 you read the catalog, and answer the rest from memory — which is the failure this file exists to
 prevent. The per-component files say the same thing without the cliff.
@@ -144,8 +144,8 @@ has stopped following the brand.
 | `tier` | count | what it is | set it? |
 |---|---|---|---|
 | `foundation` | 211 | the seeds — `--primary`, `--background`, `--foreground`, `--radius`, `--font-size-base`, `--shadow-color`. Everything below is derived from these | **yes — this is the main road.** Handed a brand colour, this is where it goes: `:root { --primary: <H> <S>% <L>%; }` (HSL components, no `hsl()` wrapper) |
-| `semantic` | 104 | named roles that follow the seeds — `--ring`, `--text-link`, `--primary-hover`, `--overlay-background` | only when the seed is right and ONE role must differ. That role then stops following a later brand change |
-| `component` | 1822 | per-part knobs, `--{component}-{part}-{property}` | rarely. Most are declared `initial` with the real default at the call site — deliberate, so a scoped override re-resolves instead of freezing at `:root` |
+| `semantic` | 112 | named roles that follow the seeds — `--ring`, `--text-link`, `--primary-hover`, `--overlay-background` | only when the seed is right and ONE role must differ. That role then stops following a later brand change |
+| `component` | 1832 | per-part knobs, `--{component}-{part}-{property}` | rarely. Most are declared `initial` with the real default at the call site — deliberate, so a scoped override re-resolves instead of freezing at `:root` |
 
 A token whose `value` is `initial` is not empty and not broken: `initial` is the guaranteed-invalid
 value, so the real default is computed where the element paints it. Set it and yours wins.

package/agent/components/BlockEditor.json

@@ -0,0 +1,91 @@
+{
+  "docPath": "docs/data-entry/block-editor.tsx",
+  "example": "import { BlockEditor } from \"@godxjp/block-editor\";\nimport { FormField } from \"@godxjp/ui/data-entry\";\n\n<FormField id=\"body\" label=\"本文\">\n  <BlockEditor\n    value={body}\n    onValueChange={setBody}\n    upload={async (file, { signal }) => ({ url: await media.put(file, { signal }), name: file.name })}\n    suggestWikilinks={(q) => pages.search(q)}\n  />\n</FormField>",
+  "group": "data-entry",
+  "importPath": "@godxjp/block-editor",
+  "name": "BlockEditor",
+  "props": [
+    {
+      "description": "Controlled Markdown body (with `onValueChange`).",
+      "name": "value",
+      "type": "string"
+    },
+    {
+      "description": "Uncontrolled initial body.",
+      "name": "defaultValue",
+      "type": "string"
+    },
+    {
+      "description": "Canonical Markdown after each edit — `serialize(editor.getJSON())`, identical to `normalize(body)` from `@godxjp/markdown/codec` (CODEC_ID kit-md@1).",
+      "name": "onValueChange",
+      "type": "(markdown: string) => void"
+    },
+    {
+      "description": "Stores a pasted / dropped / chosen file (return `asset:<id>` if you like). An inline placeholder shows progress; failure offers Retry / Remove; deleting the placeholder aborts `signal`. Images become `![name](url)`, other files a link.",
+      "name": "upload",
+      "type": "(file: File, options: { signal: AbortSignal }) => Promise<{ url: string; name?: string }>"
+    },
+    {
+      "description": "The host's media library; the `/` Image row opens it instead of a file picker.",
+      "name": "pickMedia",
+      "type": "() => Promise<{ url: string; name?: string } | null>"
+    },
+    {
+      "description": "Refuse files with this message.",
+      "name": "uploadBlockedReason",
+      "type": "string | null"
+    },
+    {
+      "description": "`[[` suggestions from the host's page index; picking inserts `[[target|label]]`.",
+      "name": "suggestWikilinks",
+      "type": "(query: string) => WikilinkSuggestion[] | Promise<WikilinkSuggestion[]>"
+    },
+    {
+      "description": "Renders a block embed `![[target]]`; default is a labelled placeholder.",
+      "name": "renderEmbed",
+      "type": "(target: string) => ReactNode"
+    },
+    {
+      "description": "Resolves a stored image URL (`asset:<id>`) for display; the body keeps the original.",
+      "name": "resolveUrl",
+      "type": "(url: string) => string | undefined"
+    },
+    {
+      "defaultValue": "\"framed\"",
+      "description": "framed: a field's border, padding and focus colour, so the editor reads as an editor inside a form; plain: the borderless Notion-style canvas for a full-page editor.",
+      "name": "appearance",
+      "type": "\"framed\" | \"plain\""
+    },
+    {
+      "description": "Extra `/` rows ({ key, label, icon, keywords?, run(api) }) — `api.insertMarkdown` inserts through the codec.",
+      "name": "actions",
+      "type": "BlockEditorAction[]"
+    },
+    {
+      "description": "Override any string (defaults: kit ja / en / vi).",
+      "name": "labels",
+      "type": "Partial<BlockEditorLabels>"
+    },
+    {
+      "description": "Not editable; the body still renders as Prose.",
+      "name": "disabled / readOnly",
+      "type": "boolean"
+    }
+  ],
+  "related": [
+    "MarkdownEditor — a Textarea with Markdown tooling, for raw-Markdown editing.",
+    "Markdown — rendering a stored body (same grammar, renderer v4)."
+  ],
+  "rules": [],
+  "storyPath": "data-entry/block-editor.tsx",
+  "tagline": "Notion / note.com style block editor (sibling package `@godxjp/block-editor`, versioned with the kit) that reads and writes MARKDOWN through `@godxjp/markdown/codec`: what onValueChange returns is byte-for-byte normalize(body). `/` block menu at the caret, ⋮⋮ handle (drag, turn into, duplicate, move, delete), floating format toolbar, `[[` wikilink suggestions, paste / drop uploads through the host, IME-safe, ja / en / vi (gh#1156).",
+  "usage": [
+    "Clicking a link (or Mod+K) opens a settings drawer: text, URL, title, open / remove. Clicking an image opens one for src, alt, title, replace (pickMedia / upload) and remove. Markdown stores no link target, so there is no target field. A link in the editor never navigates mid-edit.",
+    "YAML front matter shows as a Properties block at the top and round-trips verbatim; read it with frontmatterOf() from @godxjp/markdown/codec.",
+    "DO store the Markdown it emits — it is already canonical; compute `normalize()` server-side from the same codec to verify.",
+    "DO give it a name: wrap in `FormField` or pass `aria-label` / `aria-labelledby` (the editable is a named `textbox`).",
+    "DO pass `upload` (and `pickMedia` for a library) instead of handling paste yourself.",
+    "DON'T render Markdown into it via HTML — pass `value`; HTML paste from other apps is handled by the schema.",
+    "Keyboard: `/` menu (↑↓ Enter Esc), Alt+Shift+↑/↓ moves a block, Mod+/ opens the block menu, Markdown shortcuts (`# `, `- `, `> `, ```` ``` ````, `---`)."
+  ]
+}

package/agent/components/CommandPalette.json

@@ -10,6 +10,11 @@
       "required": true,
       "type": "CommandPaletteGroup[]"
     },
+    {
+      "description": "Decorative glyph before an item's label — a folder, a file, an emoji (gh#1159). Menu-row icon size (--menu-icon-size), aria-hidden: the label stays the option's name.",
+      "name": "groups[].items[].icon",
+      "type": "ReactNode"
+    },
     {
       "description": "Localized dialog and search copy.",
       "name": "labels",

package/agent/components/EmojiPicker.json

@@ -0,0 +1,78 @@
+{
+  "docPath": "docs/data-entry/emoji-picker.tsx",
+  "example": "import { EmojiPicker } from \"@godxjp/ui/data-entry\";\n\n<EmojiPicker value={icon} onValueChange={setIcon} />",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "EmojiPicker",
+  "props": [
+    {
+      "description": "The chosen emoji (controlled with onValueChange).",
+      "name": "value",
+      "type": "string | null"
+    },
+    {
+      "description": "Uncontrolled initial emoji.",
+      "name": "defaultValue",
+      "type": "string | null"
+    },
+    {
+      "description": "Picked emoji, or null from \"remove icon\".",
+      "name": "onValueChange",
+      "type": "(emoji: string | null) => void"
+    },
+    {
+      "description": "The popover.",
+      "name": "open / defaultOpen / onOpenChange",
+      "type": "boolean / boolean / (open) => void"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Offer \"remove icon\" while a value is set.",
+      "name": "removable",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "\"godxjp-ui:emoji-recents\"",
+      "description": "localStorage key for the per-user recents.",
+      "name": "recentsKey",
+      "type": "string"
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Trigger size.",
+      "name": "size",
+      "type": "\"xs\" | \"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "description": "Replace the default trigger (e.g. the page icon drawn large).",
+      "name": "trigger",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Disables the trigger.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "description": "Accessible name for the trigger; defaults to the localized \"Choose an icon\".",
+      "name": "aria-label",
+      "type": "string"
+    },
+    {
+      "description": "Id on the trigger button.",
+      "name": "id",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "PageContainer — `icon` slot.",
+    "CommandPalette — items can carry an emoji `icon`."
+  ],
+  "rules": [],
+  "storyPath": "data-entry/emoji-picker.tsx",
+  "tagline": "Page icon / reaction picker in a Popover (gh#1164): search by the active language's CLDR keywords (ja / en / vi — emojibase-data, loaded lazily for that locale only), categories, per-user recents, a WAI-ARIA grid (one tab stop, arrows, Home / End, Enter), and \"remove icon\". No skin tones.",
+  "usage": [
+    "DO use it for a page icon next to PageContainer `icon` — pass the icon itself as `trigger`.",
+    "The data loads on first open (one locale, ~100 KB gzip); nothing ships in your main bundle."
+  ]
+}

package/agent/components/Markdown.json

@@ -52,6 +52,21 @@
       "name": "shortCellLength",
       "type": "number | false"
     },
+    {
+      "description": "Default 'same-tab'. Renderer policy for links to another origin (an absolute http(s) URL whose origin differs from `origin`). 'new-tab' adds target=\"_blank\" rel=\"noopener noreferrer\"; relative links, #anchors, resolved wikilinks and mailto: stay in the tab. Markdown cannot store target, so this replaces it.",
+      "name": "externalLinks",
+      "type": "'same-tab' | 'new-tab'"
+    },
+    {
+      "description": "The page origin externalLinks compares against; defaults to location.origin. Pass it for server rendering, or every absolute link counts as external there.",
+      "name": "origin",
+      "type": "string"
+    },
+    {
+      "description": "Visible titles for GitHub-alert callouts (`> [!WARNING]`) that carry none of their own. English by default (the package has no i18n); pass localized strings. Grammar v1 (gh#1156): callouts, `:::toggle[summary]`, `::::columns`/`:::column{width=N}`, CJK-friendly emphasis — the same syntax the pure codec at `@godxjp/markdown/codec` (CODEC_ID kit-md@1, parse/serialize/normalize, DOM-free) and @godxjp/block-editor use.",
+      "name": "calloutTitles",
+      "type": "Partial<Record<'note' | 'tip' | 'important' | 'warning' | 'caution', string>>"
+    },
     {
       "defaultValue": "true",
       "description": "`false` keeps ```mermaid fences as code. Diagrams need the optional peer `mermaid`.",
@@ -68,6 +83,7 @@
   "storyPath": "data-display/markdown.tsx",
   "tagline": "The one Markdown renderer for GoDX apps (sibling package `@godxjp/markdown`, versioned with the kit): GFM + GitHub heading anchors, one sanitiser schema (no raw HTML; http/https/mailto/relative URLs only), and ```mermaid drawn only after its SVG passes a fail-closed gate (gh#1108). Wrap it in `Prose`.",
   "usage": [
+    "Table of contents: outline(markdown) from @godxjp/markdown/codec returns { depth, text, id }[] with exactly the ids <Markdown> writes — feed it to the kit Anchor. YAML front matter is kept verbatim and never rendered; frontmatterOf(markdown) returns it (gh#1163).",
     "DO `<Prose><Markdown>{body}</Markdown></Prose>` for every rendered body (wiki page, issue, mail).",
     "DO record `MARKDOWN_FORMAT` and `RENDERER_VERSION` on stored versions.",
     "DON'T assemble react-markdown + rehype-sanitize per app, add rehype-raw, or render Mermaid yourself — `checkMermaidSvg` is the gate."

package/agent/components/PageContainer.json

@@ -93,7 +93,7 @@
       "defaultValue": "\"document\"",
       "description": "What the page's top row IS, which decides the `<h1>`'s type step. \"document\" (default) = the row is the page's TITLE (a record, a form, a collection, a report): --page-title-font-size (h1, 20px) with the existing responsive step down at 720px; no attribute is emitted, so an existing page is byte-identical. \"chrome\" = the row is the surface's own furniture — a chat channel name, a mail subject line, an IDE tab — naming the thing the user is already INSIDE instead of announcing a document; the h1 takes --page-title-font-size-chrome (--heading-h3 = the 14px body step) at EVERY width, including below 720px where the document-scale step would otherwise pull it back UP. The heading stays an `<h1>` either way — this moves the type step only, never the element, so the screen-reader outline is untouched.",
       "name": "headerScale",
-      "type": "\"document\" | \"chrome\""
+      "type": "\"document\" | \"chrome\" | \"display\""
     },
     {
       "defaultValue": "\"default\"",
@@ -125,6 +125,16 @@
       "name": "headerLoading",
       "type": "boolean"
     },
+    {
+      "description": "The page's icon (an emoji or glyph) drawn large above the title, riding over a banner `cover`'s bottom edge — Notion's page icon (gh#1160). Add aria-hidden unless it is itself a control.",
+      "name": "icon",
+      "type": "ReactNode"
+    },
+    {
+      "description": "A PageCover: the banner variant spans the page edge to edge above the header; the eyecatch variant sits in the reading column above the title (gh#1160).",
+      "name": "cover",
+      "type": "ReactNode (a PageCover)"
+    },
     {
       "description": "Ref to the page's <h1>; passing it also makes the heading programmatically focusable (tabIndex -1, outside the tab order, no focus ring) so a router can focus the new page title after client-side navigation (gh#1135).",
       "name": "titleRef",

package/agent/components/PageCover.json

@@ -0,0 +1,75 @@
+{
+  "docPath": "docs/layout/page-cover.tsx",
+  "example": "import { PageContainer, PageCover } from \"@godxjp/ui/layout\";\nimport { Button } from \"@godxjp/ui/general\";\n\n<PageContainer\n  title={page.title}\n  headerScale=\"display\"\n  icon={<span aria-hidden=\"true\">{page.icon}</span>}\n  cover={\n    <PageCover\n      src={page.cover}\n      alt=\"\"\n      positionY={y}\n      onPositionChange={setY}\n      repositioning={moving}\n      onRepositioningChange={setMoving}\n      actions={<Button size=\"sm\" variant=\"secondary\" onClick={() => setMoving(true)}>Reposition</Button>}\n    />\n  }\n>\n  {body}\n</PageContainer>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "PageCover",
+  "props": [
+    {
+      "description": "Image URL.",
+      "name": "src",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "Alternative text; \"\" for a decorative cover.",
+      "name": "alt",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "defaultValue": "50",
+      "description": "Vertical focal point, 0 top – 100 bottom.",
+      "name": "positionY",
+      "type": "number"
+    },
+    {
+      "description": "New focal point while repositioning.",
+      "name": "onPositionChange",
+      "type": "(positionY: number) => void"
+    },
+    {
+      "description": "Reposition mode (controlled): the image becomes a slider.",
+      "name": "repositioning",
+      "type": "boolean"
+    },
+    {
+      "description": "Enter / Escape ended the mode.",
+      "name": "onRepositioningChange",
+      "type": "(repositioning: boolean) => void"
+    },
+    {
+      "defaultValue": "\"banner\"",
+      "description": "Banner above the header, or eyecatch in the reading column.",
+      "name": "variant",
+      "type": "\"banner\" | \"eyecatch\""
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Banner height step; token-owned, scales phone → desktop.",
+      "name": "height",
+      "type": "\"md\" | \"lg\""
+    },
+    {
+      "description": "Change / reposition / remove controls: over the bottom edge on a wide screen, BELOW the image on a phone (never on the focal area).",
+      "name": "actions",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Id on the cover frame.",
+      "name": "id",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "PageContainer — `cover`, `icon`, headerScale=\"display\" for an article title.",
+    "Image — an image that opens a preview."
+  ],
+  "rules": [],
+  "storyPath": "layout/page-cover.tsx",
+  "tagline": "A page's cover image (gh#1160): Notion's banner across the top, or note.com's eyecatch (~1.91:1, rounded) in the reading column. Put it in PageContainer `cover`. The focal point is positionY (object-position); while `repositioning` the image IS a vertical WAI-ARIA slider — drag or arrows / PageUp / PageDown / Home / End, Enter / Escape to finish.",
+  "usage": [
+    "DO pass it as PageContainer `cover` with the page `icon` — the container places it and overlaps the icon.",
+    "DO wire a Reposition button in `actions` that sets `repositioning`, and persist positionY from onPositionChange."
+  ]
+}

package/agent/components/Tree.json

@@ -85,6 +85,12 @@
       "name": "defaultExpandAll",
       "type": "boolean"
     },
+    {
+      "defaultValue": "false",
+      "description": "Expand a parent by clicking its ROW, not only its switcher (antd DirectoryTree): \"click\" selects AND toggles — a page tree where choosing a folder opens it; \"doubleClick\" toggles on a double click (gh#1162). Keyboard keeps the APG map.",
+      "name": "expandAction",
+      "type": "false | \"click\" | \"doubleClick\""
+    },
     {
       "description": "Lazy children (antd `loadData`). Called when a branch with no `children` and `isLeaf !== true` is expanded, and never again once its promise RESOLVES; a Skeleton row and `aria-busy` cover the wait. Push the fetched children into `treeData`. A REJECTED promise is not a load (rc-tree, gh#1041): the branch folds back shut (uncontrolled expansion) and the next expand asks again, up to 10 attempts.",
       "name": "loadData",

package/agent/components-index.json

@@ -49,6 +49,11 @@
     "name": "PageContainer",
     "tagline": "Mandatory page shell — EVERY page wraps its content in PageContainer (title/subtitle/extra/footer/breadcrumb)."
   },
+  {
+    "group": "layout",
+    "name": "PageCover",
+    "tagline": "A page's cover image (gh#1160): Notion's banner across the top, or note.com's eyecatch (~1.91:1, rounded) in the reading column. Put it in PageContainer `cover`. The focal point is positionY (object-position); while `repositioning` the image IS a vertical WAI-ARIA slider — drag or arrows / PageUp / PageDown / Home / End, Enter / Escape to finish."
+  },
   {
     "group": "layout",
     "name": "Flex",
@@ -311,6 +316,11 @@
     "name": "MarkdownEditor",
     "tagline": "Markdown editor (sibling package `@godxjp/editor`, versioned with the kit): the kit's Textarea with a WAI-ARIA formatting toolbar, write / preview / side by side (preview via `@godxjp/markdown`), IME-safe ⌘/Ctrl+B·I·K, one undo step per toolbar edit, and paste / drop / attach through a host `upload` (gh#1109)."
   },
+  {
+    "group": "data-entry",
+    "name": "BlockEditor",
+    "tagline": "Notion / note.com style block editor (sibling package `@godxjp/block-editor`, versioned with the kit) that reads and writes MARKDOWN through `@godxjp/markdown/codec`: what onValueChange returns is byte-for-byte normalize(body). `/` block menu at the caret, ⋮⋮ handle (drag, turn into, duplicate, move, delete), floating format toolbar, `[[` wikilink suggestions, paste / drop uploads through the host, IME-safe, ja / en / vi (gh#1156)."
+  },
   {
     "group": "data-display",
     "name": "Prose",
@@ -791,6 +801,11 @@
     "name": "CommandPalette",
     "tagline": "Searchable command dialog with controlled or uncontrolled open state and consumer-owned selection."
   },
+  {
+    "group": "data-entry",
+    "name": "EmojiPicker",
+    "tagline": "Page icon / reaction picker in a Popover (gh#1164): search by the active language's CLDR keywords (ja / en / vi — emojibase-data, loaded lazily for that locale only), categories, per-user recents, a WAI-ARIA grid (one tab stop, arrows, Home / End, Enter), and \"remove icon\". No skin tones."
+  },
   {
     "group": "feedback",
     "name": "TwoFactorSetup",