@godxjp/ui 31.27.0 → 31.28.1

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.27.0.** If the project you are editing has a different
+**This catalog describes `@godxjp/ui` 31.28.1.** 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 182 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` — 2142 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
-   1827 `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` | 1827 | 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

@@ -50,6 +50,12 @@
       "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",
@@ -74,6 +80,8 @@
   "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.",

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,16 @@
       "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",
@@ -73,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",
@@ -796,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",

package/agent/components.json

@@ -705,7 +705,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\"",
@@ -737,6 +737,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",
@@ -796,6 +806,81 @@
       "A chat channel page where a fixed band (channel workflow / pinned-message / connection status) must sit between the page header and the scrolling transcript — `toolbar={<Toolbar>…</Toolbar>}` with `fill` + `footer={<Composer/>}` + `stickyFooter`. The band is outside the scroller, so the transcript never travels under it and the composer stays pinned; a collection page uses the same slot for its filter strip above a full-bleed DataTable (`variant='flush'`)."
     ]
   },
+  {
+    "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."
+    ]
+  },
   {
     "example": "import { Flex } from \"@godxjp/ui/layout\";\nimport { Button } from \"@godxjp/ui/general\";\n\n<Flex direction=\"row\" gap=\"sm\" align=\"center\" justify=\"between\" wrap>\n  <SearchSummary />\n  <Flex direction=\"row\" gap=\"xs\" align=\"center\" wrap>\n    <Button variant=\"outline\">リセット</Button>\n    <Button>適用</Button>\n  </Flex>\n</Flex>",
     "group": "layout",
@@ -5061,6 +5146,16 @@
         "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",
@@ -5082,6 +5177,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."
@@ -5205,6 +5301,12 @@
         "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",
@@ -5229,6 +5331,8 @@
     "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.",
@@ -11477,6 +11581,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",
@@ -14265,6 +14375,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",
@@ -14343,6 +14458,84 @@
       "The empty-state contract: with `shouldFilter` (default) cmdk decides — items exist, the query matches none. With `shouldFilter={false}` the PALETTE decides from props — `labels.empty` renders when `groups` carries no items, and never while `loading` or `error` is set. Hold `loading` for the whole in-flight window: a request that has not answered yet is not an empty result, and asserting over cmdk's own empty node races an async group that populates a frame late."
     ]
   },
+  {
+    "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."
+    ]
+  },
   {
     "example": "import { TwoFactorSetup } from \"@godxjp/ui/feedback\";\n\n<TwoFactorSetup\n  open={open}\n  onOpenChange={setOpen}\n  qrValue={enrollment.qr}\n  manualKey={enrollment.secret}\n  code={code}\n  onCodeChange={setCode}\n  onConfirm={verify}\n  recoveryCodes={recoveryCodes}\n  onAcknowledge={finish}\n  labels={labels}\n/>",
     "group": "feedback",