@godxjp/ui 30.9.0 → 31.0.2

package/README.md

@@ -112,7 +112,8 @@ A value is defined **once** as a CSS var (`--primary`), mapped to a utility in t
 | **Data Entry**     | `@godxjp/ui/data-entry`   | `Input`, `Select`, `FormField`, `Field`, `DatePicker`, `TimePicker`, `Combobox`, `Switch`, `Toggle`, `Upload`, `Cascader`, `TreeSelect`, `ColorPicker`, `Slider`, `PasswordInput`, `PasswordStrength`, `InputOTP`, `Rating`, `TagInput` |
 | **Data Display**   | `@godxjp/ui/data-display` | `Table`, `DataTable`, `Card`, `StatCard`, `Badge`, `Avatar`, `Descriptions`, `Timeline`, `EmptyState`, `Progress`, `QrCode`, `CredentialReveal`, `Accordion`, `HoverCard`, `Carousel`, `Popover`, `Collapsible`                         |
 | **Feedback**       | `@godxjp/ui/feedback`     | `Dialog`, `AlertDialog`, `Sheet` (side), `Drawer` (bottom-sheet), `Toast`, `Skeleton`, `Alert`, `Tooltip`                                                                                                                               |
-| **Query**          | `@godxjp/ui/query`        | `DataState`, `InfiniteQueryState`, `PrefetchLink` (adapter subpath — pulls TanStack Query)                                                                                                                                              |
+| **Query**          | `@godxjp/ui/query`        | `DataState`, `InfiniteQueryState` (adapter subpath — pulls TanStack Query; no router)                                                                                                                                                   |
+| **React Router**   | `@godxjp/ui/react-router` | `PrefetchLink` — imports the optional `react-router-dom` peer, so it is kept out of `/query` (gh#996)                                                                                                                                   |
 | **Navigation**     | `@godxjp/ui/navigation`   | `Tabs`, `Toolbar`, `DropdownMenu`, `Steps`, `Pagination`, `Breadcrumb`, `AppSettingPicker`                                                                                                                                              |
 | **App**            | `@godxjp/ui/app`          | `AppProvider`, `useDateTime` (adapter — i18n/datetime singleton)                                                                                                                                                                        |
 | **Datetime**       | `@godxjp/ui/datetime`     | `formatDate` (mandatory for display)                                                                                                                                                                                                    |

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` 30.9.0.** If the project you are editing has a different
+**This catalog describes `@godxjp/ui` 31.0.2.** 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.

package/agent/components/PrefetchLink.json

@@ -1,7 +1,7 @@
 {
-  "example": "import { PrefetchLink } from \"@godxjp/ui/query\";\nimport { fetchInvoice } from \"@/api/invoices\";\n\n// Inside a table row or list item:\n<PrefetchLink\n  to={`/invoices/${invoice.id}`}\n  queryKey={[\"invoice\", invoice.id]}\n  queryFn={() => fetchInvoice(invoice.id)}\n  staleTime={60_000}\n  className=\"font-medium hover:underline\"\n>\n  {invoice.number}\n</PrefetchLink>\n\n// Disable prefetch for rows where data is not yet stable:\n<PrefetchLink\n  to={`/invoices/${invoice.id}`}\n  queryKey={[\"invoice\", invoice.id]}\n  queryFn={() => fetchInvoice(invoice.id)}\n  prefetchOn=\"none\"\n>\n  {invoice.number}\n</PrefetchLink>",
+  "example": "import { PrefetchLink } from \"@godxjp/ui/react-router\";\nimport { fetchInvoice } from \"@/api/invoices\";\n\n// Inside a table row or list item:\n<PrefetchLink\n  to={`/invoices/${invoice.id}`}\n  queryKey={[\"invoice\", invoice.id]}\n  queryFn={() => fetchInvoice(invoice.id)}\n  staleTime={60_000}\n  className=\"font-medium hover:underline\"\n>\n  {invoice.number}\n</PrefetchLink>\n\n// Disable prefetch for rows where data is not yet stable:\n<PrefetchLink\n  to={`/invoices/${invoice.id}`}\n  queryKey={[\"invoice\", invoice.id]}\n  queryFn={() => fetchInvoice(invoice.id)}\n  prefetchOn=\"none\"\n>\n  {invoice.number}\n</PrefetchLink>",
   "group": "data-display",
-  "importPath": "@godxjp/ui/query",
+  "importPath": "@godxjp/ui/react-router",
   "name": "PrefetchLink",
   "props": [
     {
@@ -46,7 +46,7 @@
     31
   ],
   "storyPath": "data-display/PrefetchLink.stories.tsx",
-  "tagline": "React Router Link that fires prefetchQuery on hover/focus so detail pages feel instant — requires a TanStack Query QueryClient in context.",
+  "tagline": "React Router Link that fires prefetchQuery on hover/focus so detail pages feel instant — requires a TanStack Query QueryClient in context. Imported from `@godxjp/ui/react-router` (not `/query`) because it imports the optional `react-router-dom` peer; in `/query` it broke every router-less app's build (gh#996).",
   "usage": [
     "DO: provide a queryKey that exactly matches the destination page's useQuery key — a mismatch means the prefetch populates a different cache slot and the page still loads cold.",
     "DO: keep queryFn lightweight and side-effect-free; it runs speculatively on hover. Avoid mutations or write operations inside queryFn.",

package/agent/components-index.json

@@ -590,7 +590,7 @@
   {
     "group": "data-display",
     "name": "PrefetchLink",
-    "tagline": "React Router Link that fires prefetchQuery on hover/focus so detail pages feel instant — requires a TanStack Query QueryClient in context."
+    "tagline": "React Router Link that fires prefetchQuery on hover/focus so detail pages feel instant — requires a TanStack Query QueryClient in context. Imported from `@godxjp/ui/react-router` (not `/query`) because it imports the optional `react-router-dom` peer; in `/query` it broke every router-less app's build (gh#996)."
   },
   {
     "group": "data-display",

package/agent/components.json

@@ -11201,9 +11201,9 @@
     ]
   },
   {
-    "example": "import { PrefetchLink } from \"@godxjp/ui/query\";\nimport { fetchInvoice } from \"@/api/invoices\";\n\n// Inside a table row or list item:\n<PrefetchLink\n  to={`/invoices/${invoice.id}`}\n  queryKey={[\"invoice\", invoice.id]}\n  queryFn={() => fetchInvoice(invoice.id)}\n  staleTime={60_000}\n  className=\"font-medium hover:underline\"\n>\n  {invoice.number}\n</PrefetchLink>\n\n// Disable prefetch for rows where data is not yet stable:\n<PrefetchLink\n  to={`/invoices/${invoice.id}`}\n  queryKey={[\"invoice\", invoice.id]}\n  queryFn={() => fetchInvoice(invoice.id)}\n  prefetchOn=\"none\"\n>\n  {invoice.number}\n</PrefetchLink>",
+    "example": "import { PrefetchLink } from \"@godxjp/ui/react-router\";\nimport { fetchInvoice } from \"@/api/invoices\";\n\n// Inside a table row or list item:\n<PrefetchLink\n  to={`/invoices/${invoice.id}`}\n  queryKey={[\"invoice\", invoice.id]}\n  queryFn={() => fetchInvoice(invoice.id)}\n  staleTime={60_000}\n  className=\"font-medium hover:underline\"\n>\n  {invoice.number}\n</PrefetchLink>\n\n// Disable prefetch for rows where data is not yet stable:\n<PrefetchLink\n  to={`/invoices/${invoice.id}`}\n  queryKey={[\"invoice\", invoice.id]}\n  queryFn={() => fetchInvoice(invoice.id)}\n  prefetchOn=\"none\"\n>\n  {invoice.number}\n</PrefetchLink>",
     "group": "data-display",
-    "importPath": "@godxjp/ui/query",
+    "importPath": "@godxjp/ui/react-router",
     "name": "PrefetchLink",
     "props": [
       {
@@ -11248,7 +11248,7 @@
       31
     ],
     "storyPath": "data-display/PrefetchLink.stories.tsx",
-    "tagline": "React Router Link that fires prefetchQuery on hover/focus so detail pages feel instant — requires a TanStack Query QueryClient in context.",
+    "tagline": "React Router Link that fires prefetchQuery on hover/focus so detail pages feel instant — requires a TanStack Query QueryClient in context. Imported from `@godxjp/ui/react-router` (not `/query`) because it imports the optional `react-router-dom` peer; in `/query` it broke every router-less app's build (gh#996).",
     "usage": [
       "DO: provide a queryKey that exactly matches the destination page's useQuery key — a mismatch means the prefetch populates a different cache slot and the page still loads cold.",
       "DO: keep queryFn lightweight and side-effect-free; it runs speculatively on hover. Avoid mutations or write operations inside queryFn.",

package/agent/index.json

@@ -48,7 +48,7 @@
   "note": "Pin to the tag that matches the @godxjp/ui version you installed. A catalog newer than your package describes props you do not have; older, and it hides props you do.",
   "read": {
     "live": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/index.json",
-    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v30.9.0/agent/index.json"
+    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v31.0.2/agent/index.json"
   },
   "source": "mcp/src/data — the same data @godxjp/ui-mcp serves — plus the foundation and semantic token tiers, read from src/tokens/*.css",
   "start": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/START-HERE.md",
@@ -62,5 +62,5 @@
     "foundation": "the seeds a consumer is invited to set — --primary, --background, --radius",
     "semantic": "named roles that follow the seeds — --ring, --text-link, --overlay-background"
   },
-  "version": "30.9.0"
+  "version": "31.0.2"
 }

package/agent/llms.txt

@@ -1,10 +1,10 @@
 # @godxjp/ui
 
 > A Japanese-enterprise React design system: 175 components, 2074 design tokens,
-> 50 cardinal rules. This file is the entry point for AI agents. Catalog version 30.9.0.
+> 50 cardinal rules. This file is the entry point for AI agents. Catalog version 31.0.2.
 
 If your client can run a process, do not read these files — run the MCP server instead
-(`npx @godxjp/ui-mcp@30.9.0`). It is searchable and version-locked. These files exist for agents
+(`npx @godxjp/ui-mcp@31.0.2`). It is searchable and version-locked. These files exist for agents
 that can only fetch URLs.
 
 ## Start
@@ -26,7 +26,7 @@ that can only fetch URLs.
 ## Pinning
 
 Every URL above tracks `main`. To pin to the release a project actually installed, swap `main` for
-the tag: `.../godx-jp/godxjp-ui/v30.9.0/agent/...`. A catalog that does not match the installed
+the tag: `.../godx-jp/godxjp-ui/v31.0.2/agent/...`. A catalog that does not match the installed
 package describes props that are absent, or hides props that are present, and says nothing either way.
 
 Pinned catalogs only exist for releases whose tag actually contains `agent/`. If `…/v<version>/agent/index.json` returns 404, that release predates this catalog: read `…/main/…` instead and compare `index.json` → `version` against the package you have, so you at least know which way it drifted.

package/agent/patterns/settings-page-responsive.json

@@ -4,7 +4,7 @@
     "settings-page",
     "settings-layout"
   ],
-  "code": "// Research basis: GitHub, Google Account, Microsoft Account, Atlassian Account settings +\n// the IBM Carbon form grid. Every destination is a URL, so deep links and browser back/forward\n// work for free and the active item is derived from the route — never from local tab state.\n//\n// Desktop (>= lg): persistent vertical local nav on the left + bounded content on the right.\n// Mobile (< lg):   the SAME routes become a horizontal, scrollable tab strip above the content.\n// Styling uses ONLY real semantic token classes (bg-muted / text-foreground / text-muted-foreground)\n// and responsive/visibility utilities — the library ships NO bespoke settings shell/nav CSS classes.\nimport { NavLink, Outlet, Navigate } from \"react-router-dom\";\nimport { Flex } from \"@godxjp/ui/layout\";\nimport { FormField, Input } from \"@godxjp/ui/data-entry\";\nimport { Button } from \"@godxjp/ui/general\";\n\nconst SECTIONS = [\n  { to: \"general\", label: \"基本情報\" },\n  { to: \"security\", label: \"セキュリティ\" },\n  { to: \"notifications\", label: \"通知\" },\n] as const;\n\n// One link renderer for BOTH breakpoints. NavLink gives us the active state (and sets\n// aria-current=\"page\") straight from the URL; semantic tokens only, no invented classes.\nconst link = ({ isActive }: { isActive: boolean }) =>\n  [\n    \"rounded-md px-3 py-2 text-sm no-underline transition-colors whitespace-nowrap\",\n    isActive\n      ? \"bg-muted text-foreground font-medium\"\n      : \"text-muted-foreground hover:text-foreground\",\n  ].join(\" \");\n\nexport function SettingsLayout() {\n  return (\n    <Flex direction=\"col\" gap=\"lg\" className=\"lg:flex-row lg:items-start\">\n      {/* < lg: horizontal, scrollable route tabs. Flex owns the row and the gap — hideFrom /\n          hideBelow own the breakpoint, so neither nav needs a hand-rolled flex or gap utility. */}\n      <Flex as=\"nav\" aria-label=\"設定\" gap={1} hideFrom=\"lg\" className=\"overflow-x-auto\">\n        {SECTIONS.map((s) => (\n          <NavLink key={s.to} to={s.to} className={link} end>{s.label}</NavLink>\n        ))}\n      </Flex>\n      {/* >= lg: persistent vertical local nav (bounded width, does not shrink). */}\n      <Flex as=\"nav\" aria-label=\"設定\" direction=\"col\" gap={1} hideBelow=\"lg\" width={224} shrink={false}>\n        {SECTIONS.map((s) => (\n          <NavLink key={s.to} to={s.to} className={link} end>{s.label}</NavLink>\n        ))}\n      </Flex>\n      {/* Bounded content region (~42rem) — the routed section renders here. min-w-0 lets it shrink. */}\n      <main className=\"min-w-0 max-w-2xl flex-1\"><Outlet /></main>\n    </Flex>\n  );\n}\n\n// A settings section. Horizontal label/control rows on desktop (collapse to stacked on mobile),\n// controls bounded to a semantic width. FormField OWNS the label↔control relationship — do NOT\n// hand-roll <Label> + <input>. Save feedback = Button loading prop + a toast in onSuccess.\nexport function GeneralSettingsSection({\n  defaults, onSave, saving, error,\n}: { defaults: { name: string; email: string }; onSave: (v: FormData) => void; saving: boolean; error?: string }) {\n  return (\n    <form onSubmit={(e) => { e.preventDefault(); onSave(new FormData(e.currentTarget)); }}>\n      <Flex direction=\"col\" gap=\"md\">\n        <FormField id=\"ws-name\" label=\"ワークスペース名\" layout=\"horizontal\" controlWidth=\"24rem\"\n          helper=\"請求書や共有リンクに表示されます。\" error={error}>\n          <Input id=\"ws-name\" name=\"name\" defaultValue={defaults.name} />\n        </FormField>\n        <FormField id=\"ws-email\" label=\"連絡先メール\" layout=\"horizontal\" controlWidth=\"24rem\">\n          <Input id=\"ws-email\" name=\"email\" type=\"email\" defaultValue={defaults.email} />\n        </FormField>\n        <Flex gap=\"sm\"><Button type=\"submit\" loading={saving}>変更を保存</Button></Flex>\n      </Flex>\n    </form>\n  );\n}\n\n// Router wiring — each destination is addressable, so deep links + back/forward just work:\n//   <Route path=\"settings\" element={<SettingsLayout/>}>\n//     <Route index element={<Navigate to=\"general\" replace/>} />\n//     <Route path=\"general\" element={<GeneralSettingsSection .../>} />\n//     <Route path=\"security\" element={<SecuritySection/>} />\n//     <Route path=\"notifications\" element={<NotificationsSection/>} />\n//   </Route>\n\n// ── DO / DON'T ────────────────────────────────────────────────────────────────────────────\n// ✅ Tabs (navigation) are fine for a SMALL number (2–4) of PEER views inside ONE task/section\n//    — e.g. \"プロフィール\" ⇄ \"環境設定\" within a single account page — where losing the URL is OK.\n// ⛔ Tabs as the PRIMARY IA for broad settings (Account / Security / Billing / Members / …):\n//    use route-backed local navigation so every area is deep-linkable and back/forward works.\n// ⛔ Do NOT wrap the whole settings page in a Card, and do NOT make desktop a horizontal tab bar\n//    — persistent local nav scales to many sections; a tab strip does not.\n// ⛔ Do NOT invent CSS class names for the shell/nav/content — compose Flex + semantic tokens.",
+  "code": "// Research basis: GitHub, Google Account, Microsoft Account, Atlassian Account settings +\n// the IBM Carbon form grid. Every destination is a URL, so deep links and browser back/forward\n// work for free and the active item is derived from the route — never from local tab state.\n//\n// Desktop (>= lg): persistent vertical local nav on the left + bounded content on the right.\n// Mobile (< lg):   the SAME routes become a horizontal, scrollable tab strip above the content.\n// Styling uses ONLY real semantic token classes (bg-muted / text-foreground / text-muted-foreground)\n// and responsive/visibility utilities — the library ships NO bespoke settings shell/nav CSS classes.\nimport { NavLink, Outlet, Navigate } from \"react-router-dom\";\nimport { Flex } from \"@godxjp/ui/layout\";\nimport { Form, FormField, Input } from \"@godxjp/ui/data-entry\";\nimport { Button } from \"@godxjp/ui/general\";\n\nconst SECTIONS = [\n  { to: \"general\", label: \"基本情報\" },\n  { to: \"security\", label: \"セキュリティ\" },\n  { to: \"notifications\", label: \"通知\" },\n] as const;\n\n// One link renderer for BOTH breakpoints. NavLink gives us the active state (and sets\n// aria-current=\"page\") straight from the URL; semantic tokens only, no invented classes.\nconst link = ({ isActive }: { isActive: boolean }) =>\n  [\n    \"rounded-md px-3 py-2 text-sm no-underline transition-colors whitespace-nowrap\",\n    isActive\n      ? \"bg-muted text-foreground font-medium\"\n      : \"text-muted-foreground hover:text-foreground\",\n  ].join(\" \");\n\nexport function SettingsLayout() {\n  return (\n    <Flex direction=\"col\" gap=\"lg\" className=\"lg:flex-row lg:items-start\">\n      {/* < lg: horizontal, scrollable route tabs. Flex owns the row and the gap — hideFrom /\n          hideBelow own the breakpoint, so neither nav needs a hand-rolled flex or gap utility. */}\n      <Flex as=\"nav\" aria-label=\"設定\" gap={1} hideFrom=\"lg\" className=\"overflow-x-auto\">\n        {SECTIONS.map((s) => (\n          <NavLink key={s.to} to={s.to} className={link} end>{s.label}</NavLink>\n        ))}\n      </Flex>\n      {/* >= lg: persistent vertical local nav (bounded width, does not shrink). */}\n      <Flex as=\"nav\" aria-label=\"設定\" direction=\"col\" gap={1} hideBelow=\"lg\" width={224} shrink={false}>\n        {SECTIONS.map((s) => (\n          <NavLink key={s.to} to={s.to} className={link} end>{s.label}</NavLink>\n        ))}\n      </Flex>\n      {/* Bounded content region (~42rem) — the routed section renders here. min-w-0 lets it shrink. */}\n      <main className=\"min-w-0 max-w-2xl flex-1\"><Outlet /></main>\n    </Flex>\n  );\n}\n\n// A settings section. Horizontal label/control rows on desktop (collapse to stacked on mobile),\n// controls bounded to a semantic width — set ONCE on the <Form>, which every FormField reads\n// (gh#998). FormField OWNS the label↔control relationship — do NOT hand-roll <Label> + <input>. Save feedback = Button loading prop + a toast in onSuccess.\nexport function GeneralSettingsSection({\n  defaults, onSave, saving, error,\n}: { defaults: { name: string; email: string }; onSave: (v: FormData) => void; saving: boolean; error?: string }) {\n  return (\n    <Form layout=\"horizontal\" controlWidth=\"24rem\"\n      onSubmit={(e) => { e.preventDefault(); onSave(new FormData(e.currentTarget)); }}>\n      <FormField id=\"ws-name\" label=\"ワークスペース名\"\n        helper=\"請求書や共有リンクに表示されます。\" error={error}>\n        <Input id=\"ws-name\" name=\"name\" defaultValue={defaults.name} />\n      </FormField>\n      <FormField id=\"ws-email\" label=\"連絡先メール\">\n        <Input id=\"ws-email\" name=\"email\" type=\"email\" defaultValue={defaults.email} />\n      </FormField>\n      <Flex gap=\"sm\"><Button type=\"submit\" loading={saving}>変更を保存</Button></Flex>\n    </Form>\n  );\n}\n\n// Router wiring — each destination is addressable, so deep links + back/forward just work:\n//   <Route path=\"settings\" element={<SettingsLayout/>}>\n//     <Route index element={<Navigate to=\"general\" replace/>} />\n//     <Route path=\"general\" element={<GeneralSettingsSection .../>} />\n//     <Route path=\"security\" element={<SecuritySection/>} />\n//     <Route path=\"notifications\" element={<NotificationsSection/>} />\n//   </Route>\n\n// ── DO / DON'T ────────────────────────────────────────────────────────────────────────────\n// ✅ Tabs (navigation) are fine for a SMALL number (2–4) of PEER views inside ONE task/section\n//    — e.g. \"プロフィール\" ⇄ \"環境設定\" within a single account page — where losing the URL is OK.\n// ⛔ Tabs as the PRIMARY IA for broad settings (Account / Security / Billing / Members / …):\n//    use route-backed local navigation so every area is deep-linkable and back/forward works.\n// ⛔ Do NOT wrap the whole settings page in a Card, and do NOT make desktop a horizontal tab bar\n//    — persistent local nav scales to many sections; a tab strip does not.\n// ⛔ Do NOT invent CSS class names for the shell/nav/content — compose Flex + semantic tokens.",
   "name": "settings-page-responsive",
   "tagline": "Route-backed settings: persistent desktop local navigation, compact mobile tab strip, deep links + browser history, and bounded form content — NO Card wrapper, NO undefined CSS.",
   "tags": [

package/agent/patterns.json

@@ -34,7 +34,7 @@
       "settings-page",
       "settings-layout"
     ],
-    "code": "// Research basis: GitHub, Google Account, Microsoft Account, Atlassian Account settings +\n// the IBM Carbon form grid. Every destination is a URL, so deep links and browser back/forward\n// work for free and the active item is derived from the route — never from local tab state.\n//\n// Desktop (>= lg): persistent vertical local nav on the left + bounded content on the right.\n// Mobile (< lg):   the SAME routes become a horizontal, scrollable tab strip above the content.\n// Styling uses ONLY real semantic token classes (bg-muted / text-foreground / text-muted-foreground)\n// and responsive/visibility utilities — the library ships NO bespoke settings shell/nav CSS classes.\nimport { NavLink, Outlet, Navigate } from \"react-router-dom\";\nimport { Flex } from \"@godxjp/ui/layout\";\nimport { FormField, Input } from \"@godxjp/ui/data-entry\";\nimport { Button } from \"@godxjp/ui/general\";\n\nconst SECTIONS = [\n  { to: \"general\", label: \"基本情報\" },\n  { to: \"security\", label: \"セキュリティ\" },\n  { to: \"notifications\", label: \"通知\" },\n] as const;\n\n// One link renderer for BOTH breakpoints. NavLink gives us the active state (and sets\n// aria-current=\"page\") straight from the URL; semantic tokens only, no invented classes.\nconst link = ({ isActive }: { isActive: boolean }) =>\n  [\n    \"rounded-md px-3 py-2 text-sm no-underline transition-colors whitespace-nowrap\",\n    isActive\n      ? \"bg-muted text-foreground font-medium\"\n      : \"text-muted-foreground hover:text-foreground\",\n  ].join(\" \");\n\nexport function SettingsLayout() {\n  return (\n    <Flex direction=\"col\" gap=\"lg\" className=\"lg:flex-row lg:items-start\">\n      {/* < lg: horizontal, scrollable route tabs. Flex owns the row and the gap — hideFrom /\n          hideBelow own the breakpoint, so neither nav needs a hand-rolled flex or gap utility. */}\n      <Flex as=\"nav\" aria-label=\"設定\" gap={1} hideFrom=\"lg\" className=\"overflow-x-auto\">\n        {SECTIONS.map((s) => (\n          <NavLink key={s.to} to={s.to} className={link} end>{s.label}</NavLink>\n        ))}\n      </Flex>\n      {/* >= lg: persistent vertical local nav (bounded width, does not shrink). */}\n      <Flex as=\"nav\" aria-label=\"設定\" direction=\"col\" gap={1} hideBelow=\"lg\" width={224} shrink={false}>\n        {SECTIONS.map((s) => (\n          <NavLink key={s.to} to={s.to} className={link} end>{s.label}</NavLink>\n        ))}\n      </Flex>\n      {/* Bounded content region (~42rem) — the routed section renders here. min-w-0 lets it shrink. */}\n      <main className=\"min-w-0 max-w-2xl flex-1\"><Outlet /></main>\n    </Flex>\n  );\n}\n\n// A settings section. Horizontal label/control rows on desktop (collapse to stacked on mobile),\n// controls bounded to a semantic width. FormField OWNS the label↔control relationship — do NOT\n// hand-roll <Label> + <input>. Save feedback = Button loading prop + a toast in onSuccess.\nexport function GeneralSettingsSection({\n  defaults, onSave, saving, error,\n}: { defaults: { name: string; email: string }; onSave: (v: FormData) => void; saving: boolean; error?: string }) {\n  return (\n    <form onSubmit={(e) => { e.preventDefault(); onSave(new FormData(e.currentTarget)); }}>\n      <Flex direction=\"col\" gap=\"md\">\n        <FormField id=\"ws-name\" label=\"ワークスペース名\" layout=\"horizontal\" controlWidth=\"24rem\"\n          helper=\"請求書や共有リンクに表示されます。\" error={error}>\n          <Input id=\"ws-name\" name=\"name\" defaultValue={defaults.name} />\n        </FormField>\n        <FormField id=\"ws-email\" label=\"連絡先メール\" layout=\"horizontal\" controlWidth=\"24rem\">\n          <Input id=\"ws-email\" name=\"email\" type=\"email\" defaultValue={defaults.email} />\n        </FormField>\n        <Flex gap=\"sm\"><Button type=\"submit\" loading={saving}>変更を保存</Button></Flex>\n      </Flex>\n    </form>\n  );\n}\n\n// Router wiring — each destination is addressable, so deep links + back/forward just work:\n//   <Route path=\"settings\" element={<SettingsLayout/>}>\n//     <Route index element={<Navigate to=\"general\" replace/>} />\n//     <Route path=\"general\" element={<GeneralSettingsSection .../>} />\n//     <Route path=\"security\" element={<SecuritySection/>} />\n//     <Route path=\"notifications\" element={<NotificationsSection/>} />\n//   </Route>\n\n// ── DO / DON'T ────────────────────────────────────────────────────────────────────────────\n// ✅ Tabs (navigation) are fine for a SMALL number (2–4) of PEER views inside ONE task/section\n//    — e.g. \"プロフィール\" ⇄ \"環境設定\" within a single account page — where losing the URL is OK.\n// ⛔ Tabs as the PRIMARY IA for broad settings (Account / Security / Billing / Members / …):\n//    use route-backed local navigation so every area is deep-linkable and back/forward works.\n// ⛔ Do NOT wrap the whole settings page in a Card, and do NOT make desktop a horizontal tab bar\n//    — persistent local nav scales to many sections; a tab strip does not.\n// ⛔ Do NOT invent CSS class names for the shell/nav/content — compose Flex + semantic tokens.",
+    "code": "// Research basis: GitHub, Google Account, Microsoft Account, Atlassian Account settings +\n// the IBM Carbon form grid. Every destination is a URL, so deep links and browser back/forward\n// work for free and the active item is derived from the route — never from local tab state.\n//\n// Desktop (>= lg): persistent vertical local nav on the left + bounded content on the right.\n// Mobile (< lg):   the SAME routes become a horizontal, scrollable tab strip above the content.\n// Styling uses ONLY real semantic token classes (bg-muted / text-foreground / text-muted-foreground)\n// and responsive/visibility utilities — the library ships NO bespoke settings shell/nav CSS classes.\nimport { NavLink, Outlet, Navigate } from \"react-router-dom\";\nimport { Flex } from \"@godxjp/ui/layout\";\nimport { Form, FormField, Input } from \"@godxjp/ui/data-entry\";\nimport { Button } from \"@godxjp/ui/general\";\n\nconst SECTIONS = [\n  { to: \"general\", label: \"基本情報\" },\n  { to: \"security\", label: \"セキュリティ\" },\n  { to: \"notifications\", label: \"通知\" },\n] as const;\n\n// One link renderer for BOTH breakpoints. NavLink gives us the active state (and sets\n// aria-current=\"page\") straight from the URL; semantic tokens only, no invented classes.\nconst link = ({ isActive }: { isActive: boolean }) =>\n  [\n    \"rounded-md px-3 py-2 text-sm no-underline transition-colors whitespace-nowrap\",\n    isActive\n      ? \"bg-muted text-foreground font-medium\"\n      : \"text-muted-foreground hover:text-foreground\",\n  ].join(\" \");\n\nexport function SettingsLayout() {\n  return (\n    <Flex direction=\"col\" gap=\"lg\" className=\"lg:flex-row lg:items-start\">\n      {/* < lg: horizontal, scrollable route tabs. Flex owns the row and the gap — hideFrom /\n          hideBelow own the breakpoint, so neither nav needs a hand-rolled flex or gap utility. */}\n      <Flex as=\"nav\" aria-label=\"設定\" gap={1} hideFrom=\"lg\" className=\"overflow-x-auto\">\n        {SECTIONS.map((s) => (\n          <NavLink key={s.to} to={s.to} className={link} end>{s.label}</NavLink>\n        ))}\n      </Flex>\n      {/* >= lg: persistent vertical local nav (bounded width, does not shrink). */}\n      <Flex as=\"nav\" aria-label=\"設定\" direction=\"col\" gap={1} hideBelow=\"lg\" width={224} shrink={false}>\n        {SECTIONS.map((s) => (\n          <NavLink key={s.to} to={s.to} className={link} end>{s.label}</NavLink>\n        ))}\n      </Flex>\n      {/* Bounded content region (~42rem) — the routed section renders here. min-w-0 lets it shrink. */}\n      <main className=\"min-w-0 max-w-2xl flex-1\"><Outlet /></main>\n    </Flex>\n  );\n}\n\n// A settings section. Horizontal label/control rows on desktop (collapse to stacked on mobile),\n// controls bounded to a semantic width — set ONCE on the <Form>, which every FormField reads\n// (gh#998). FormField OWNS the label↔control relationship — do NOT hand-roll <Label> + <input>. Save feedback = Button loading prop + a toast in onSuccess.\nexport function GeneralSettingsSection({\n  defaults, onSave, saving, error,\n}: { defaults: { name: string; email: string }; onSave: (v: FormData) => void; saving: boolean; error?: string }) {\n  return (\n    <Form layout=\"horizontal\" controlWidth=\"24rem\"\n      onSubmit={(e) => { e.preventDefault(); onSave(new FormData(e.currentTarget)); }}>\n      <FormField id=\"ws-name\" label=\"ワークスペース名\"\n        helper=\"請求書や共有リンクに表示されます。\" error={error}>\n        <Input id=\"ws-name\" name=\"name\" defaultValue={defaults.name} />\n      </FormField>\n      <FormField id=\"ws-email\" label=\"連絡先メール\">\n        <Input id=\"ws-email\" name=\"email\" type=\"email\" defaultValue={defaults.email} />\n      </FormField>\n      <Flex gap=\"sm\"><Button type=\"submit\" loading={saving}>変更を保存</Button></Flex>\n    </Form>\n  );\n}\n\n// Router wiring — each destination is addressable, so deep links + back/forward just work:\n//   <Route path=\"settings\" element={<SettingsLayout/>}>\n//     <Route index element={<Navigate to=\"general\" replace/>} />\n//     <Route path=\"general\" element={<GeneralSettingsSection .../>} />\n//     <Route path=\"security\" element={<SecuritySection/>} />\n//     <Route path=\"notifications\" element={<NotificationsSection/>} />\n//   </Route>\n\n// ── DO / DON'T ────────────────────────────────────────────────────────────────────────────\n// ✅ Tabs (navigation) are fine for a SMALL number (2–4) of PEER views inside ONE task/section\n//    — e.g. \"プロフィール\" ⇄ \"環境設定\" within a single account page — where losing the URL is OK.\n// ⛔ Tabs as the PRIMARY IA for broad settings (Account / Security / Billing / Members / …):\n//    use route-backed local navigation so every area is deep-linkable and back/forward works.\n// ⛔ Do NOT wrap the whole settings page in a Card, and do NOT make desktop a horizontal tab bar\n//    — persistent local nav scales to many sections; a tab strip does not.\n// ⛔ Do NOT invent CSS class names for the shell/nav/content — compose Flex + semantic tokens.",
     "name": "settings-page-responsive",
     "tagline": "Route-backed settings: persistent desktop local navigation, compact mobile tab strip, deep links + browser history, and bounded form content — NO Card wrapper, NO undefined CSS.",
     "tags": [

package/dist/components/query/index.d.ts

@@ -6,7 +6,5 @@ export { ButtonRefetch } from "./query-refetch-button.js";
 export type { ButtonRefetchProp, ButtonRefetchProps } from "./query-refetch-button.js";
 export { InfiniteQueryState, flattenItemPages } from "./infinite-query-state.js";
 export type { InfiniteQueryStateProp, InfiniteQueryStateProps } from "./infinite-query-state.js";
-export { PrefetchLink } from "./prefetch-link.js";
-export type { PrefetchLinkProp, PrefetchLinkProps } from "./prefetch-link.js";
 export { classifyQueryError, isRetryableQueryError } from "../../lib/query-error.js";
 export type { QueryErrorCategory, QueryErrorInfo } from "../../lib/query-error.js";

package/dist/components/query/index.js

@@ -2,14 +2,12 @@ import { DataState } from "./data-state.js";
 import { AlertMutationFeedback } from "./mutation-feedback.js";
 import { ButtonRefetch } from "./query-refetch-button.js";
 import { InfiniteQueryState, flattenItemPages } from "./infinite-query-state.js";
-import { PrefetchLink } from "./prefetch-link.js";
 import { classifyQueryError, isRetryableQueryError } from "../../lib/query-error.js";
 export {
   AlertMutationFeedback,
   ButtonRefetch,
   DataState,
   InfiniteQueryState,
-  PrefetchLink,
   classifyQueryError,
   flattenItemPages,
   isRetryableQueryError

package/dist/components/react-router/index.d.ts

@@ -0,0 +1,2 @@
+export { PrefetchLink } from "./prefetch-link.js";
+export type { PrefetchLinkProp, PrefetchLinkProps } from "./prefetch-link.js";

package/dist/components/react-router/index.js

@@ -0,0 +1,4 @@
+import { PrefetchLink } from "./prefetch-link.js";
+export {
+  PrefetchLink
+};

package/dist/contracts/measurement.json

@@ -1,6 +1,6 @@
 {
   "$comment": "AUTO-GENERATED by scripts/gen-measurement-contract.mjs — do not edit. Read this instead of guessing: docs/MEASUREMENT-CONTRACT.md.",
-  "version": "30.9.0",
+  "version": "31.0.2",
   "targetSize": {
     "standard": "WCAG 2.2 SC 2.5.8 Target Size (Minimum), level AA — 24×24 CSS px",
     "min": 24,

package/dist/styles/alert-layout.css

@@ -2,6 +2,8 @@
 
 @layer components {
   [data-slot="alert"] {
+
+    container: alert / inline-size;
     position: relative;
     display: flex;
     align-items: flex-start;
@@ -133,7 +135,7 @@
     gap: var(--alert-inner-space-gap);
   }
 
-  @media (min-width: 640px) {
+  @container alert (min-width: 40rem) {
     [data-slot="alert-body"]:has(> [data-slot="alert-actions"]) {
       display: grid;
       grid-template-columns: minmax(0, 1fr) auto;
@@ -190,7 +192,7 @@
     width: 100%;
   }
 
-  @media (min-width: 640px) {
+  @container alert (min-width: 40rem) {
     [data-slot="alert-actions"] {
       width: auto;
       justify-content: flex-end;

package/dist/styles/layers.json

@@ -1,5 +1,5 @@
 {
-  "version": "30.9.0",
+  "version": "31.0.2",
   "generatedBy": "scripts/gen-style-layers.mjs — do not edit by hand; run `pnpm gen:style-layers`",
   "base": "base.css",
   "fonts": "fonts.css",

package/docs/CONSUMER-RULES.md

@@ -6,7 +6,7 @@ Read this once; the audit enforces it. Everything else in `docs/` is for contrib
 2. Every page is `<PageContainer title subtitle extra footer>`; its sections are spaced by the page. Group items inside a section with `<Flex direction="col" gap>` or `<ResponsiveGrid>`.
 3. No Tailwind layout on your own elements: no `flex`, `grid`, `gap-*`, `p-*`, `m-*`, `space-*`. Rows are `<Flex>` (default row), stacks are `<Flex direction="col">`, grids are `<ResponsiveGrid>`.
 4. No hand-rolled surfaces: no `rounded-* border bg-*` divs. A box is `Card`, a pill is `Badge`, a person is `Avatar`, a row is `ListRow`, a label/value pair is `Descriptions`, an empty area is `EmptyState`, a read-only sample of a colour the USER chose is `Swatch`. A LIST of those rows is `<Flex as="ul" marker="none" direction="col" gap="none">` with `<ListRow as="li">` children — `marker="none"` keeps the `<ul>`, the `<li>` semantics and the gap token while dropping the bullet and the indent. Never a raw `<ul>`/`<ol>` (it carries no gap token), never `<div role="list">` + `<div role="listitem">`, and never a wrapper around each row: the divider is `:not(:last-child)` among siblings, so a row alone in its own wrapper is always the last one and EVERY divider disappears silently. A bulleted prose list is the same `<Flex as="ul">` without `marker`.
-5. Real controls only: `Button`, `Input`, `Select`, `Textarea`, `Checkbox`… never raw `<button>`/`<input>`; a labelled control lives in `<FormField label>`. A Select outside a form takes `width="auto"`. **A disabled control's reason is visible text, never a tooltip** — see below.
+5. Real controls only: `Button`, `Input`, `Select`, `Textarea`, `Checkbox`… never raw `<button>`/`<input>`; a labelled control lives in `<FormField label>`. A Select outside a form takes `width="auto"`. **A disabled control's reason is visible text, never a tooltip** — see below. **Fields live in a `<Form layout="horizontal" labelWidth controlWidth>`** — never a group of `FormField`s without one, never a hand-rolled `<Flex>` row of fields (a row that belongs together is `<SpaceCompact>` or `<Form columns>`); size each control for its content with `controlWidth` (GOV.UK text-input width: a port ~7rem, a short enum ~10rem); three or more fields is a page, not a Dialog. The audit rules are `formfield-needs-form`, `dialog-form-too-big` and `select-width-hint`. **A case the kit cannot express is an issue, not a hand-roll:** open it on godx-jp/godxjp-ui, use the nearest valid composition, and mark it `// TODO(godxjp-ui#<n>)` (gh#998).
 6. Text is `<Text>` / `<Heading>` with `tone`, `size`, `weight`, `truncate`, `mono` — not `className="text-muted-foreground font-semibold"`. A STANDALONE glyph is `<Icon as={Lock} size="sm" tone="muted" />` from `@godxjp/ui/general`: a bare lucide icon carries its own `width="24" height="24"` and only four places re-size it for you (`Button`, a `DropdownMenuItem`, a `TopbarItem`, a `ListRow` leading slot), so everywhere else — in a `Text`, a table cell, an `<a>` — it draws at 24px beside 14px type. `size-4` and `w-[16px]` are closed to you by rules 3 and 8, and `size={16}` hard-codes a number the theme owns; `Icon` puts the glyph on the `--icon-size-*` scale (`2xs…4xl`) instead, and is `aria-hidden` unless you give it a `label` (then it is `role="img"` with that name). The audit rule is `lucide-icon-needs-size`.
 7. Colours are semantic tokens (`tone="destructive"`, `bg-primary`), never palette names, hex, or `bg-black` / `text-white`.
 8. Sizes come from props (`size`, `width`, `columns`), never `w-[240px]` / `max-h-[420px]`.

package/docs/data-display/permission-matrix.tsx

@@ -17,7 +17,7 @@ import {
   CardTitle,
   PermissionMatrix,
 } from "@godxjp/ui/data-display";
-import { FormField, Label, Select, Switch } from "@godxjp/ui/data-entry";
+import { Form, FormField, Label, Select, Switch } from "@godxjp/ui/data-entry";
 import { Flex, PageContainer } from "@godxjp/ui/layout";
 import { grantKey } from "@godxjp/ui/lib/permission-grid";
 
@@ -114,35 +114,37 @@ export default function Demo() {
           </CardHeader>
           <CardContent>
             <Flex direction="col" gap="md">
-              <Flex direction="row" wrap align="end" gap="md">
-                {/* Bare Select has NO accessible name (axe button-name) — the compare
+              <Form>
+                <Flex direction="row" wrap align="end" gap="md">
+                  {/* Bare Select has NO accessible name (axe button-name) — the compare
                     pickers are labelled through FormField, exactly as the showcase does. */}
-                <FormField label="比較 A">
-                  <Select
-                    value={compareA}
-                    onValueChange={setCompareA}
-                    options={roleOptions}
-                    className="w-40"
-                  />
-                </FormField>
-                <FormField label="比較 B">
-                  <Select
-                    value={compareB}
-                    onValueChange={setCompareB}
-                    options={roleOptions}
-                    className="w-40"
-                  />
-                </FormField>
-                <Flex direction="row" align="center" gap="sm">
-                  <Switch
-                    id="pm-doc-diff-only"
-                    size="sm"
-                    checked={diffOnly}
-                    onCheckedChange={setDiffOnly}
-                  />
-                  <Label htmlFor="pm-doc-diff-only">差分のみ</Label>
+                  <FormField label="比較 A">
+                    <Select
+                      value={compareA}
+                      onValueChange={setCompareA}
+                      options={roleOptions}
+                      className="w-40"
+                    />
+                  </FormField>
+                  <FormField label="比較 B">
+                    <Select
+                      value={compareB}
+                      onValueChange={setCompareB}
+                      options={roleOptions}
+                      className="w-40"
+                    />
+                  </FormField>
+                  <Flex direction="row" align="center" gap="sm">
+                    <Switch
+                      id="pm-doc-diff-only"
+                      size="sm"
+                      checked={diffOnly}
+                      onCheckedChange={setDiffOnly}
+                    />
+                    <Label htmlFor="pm-doc-diff-only">差分のみ</Label>
+                  </Flex>
                 </Flex>
-              </Flex>
+              </Form>
               <Card variant="outline" className="overflow-hidden">
                 <CardContent flush>
                   <div>

package/docs/data-entry/cascader.tsx

@@ -1,7 +1,7 @@
 import { useState } from "react";
 
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
-import { Cascader, FormField } from "@godxjp/ui/data-entry";
+import { Form, Cascader, FormField } from "@godxjp/ui/data-entry";
 import { Flex, PageContainer } from "@godxjp/ui/layout";
 import type { TreeOptionProp } from "@godxjp/ui/props";
 
@@ -351,25 +351,27 @@ export default function Demo() {
             </CardDescription>
           </CardHeader>
           <CardContent>
-            <Flex direction="col" gap="md">
-              <FormField id="disabled-empty" label="無効（未選択）">
-                <Cascader
-                  id="disabled-empty"
-                  options={EXPENSE_CATEGORIES}
-                  disabled
-                  placeholder="カテゴリを選択..."
-                />
-              </FormField>
-              <FormField id="disabled-selected" label="無効（選択済み）">
-                <Cascader
-                  id="disabled-selected"
-                  options={EXPENSE_CATEGORIES}
-                  disabled
-                  defaultValue={["operating", "admin", "salary"]}
-                  placeholder="カテゴリを選択..."
-                />
-              </FormField>
-            </Flex>
+            <Form>
+              <Flex direction="col" gap="md">
+                <FormField id="disabled-empty" label="無効（未選択）">
+                  <Cascader
+                    id="disabled-empty"
+                    options={EXPENSE_CATEGORIES}
+                    disabled
+                    placeholder="カテゴリを選択..."
+                  />
+                </FormField>
+                <FormField id="disabled-selected" label="無効（選択済み）">
+                  <Cascader
+                    id="disabled-selected"
+                    options={EXPENSE_CATEGORIES}
+                    disabled
+                    defaultValue={["operating", "admin", "salary"]}
+                    placeholder="カテゴリを選択..."
+                  />
+                </FormField>
+              </Flex>
+            </Form>
           </CardContent>
         </Card>
       </Flex>

package/docs/data-entry/date-picker.tsx

@@ -2,7 +2,7 @@ import { useState } from "react";
 import { ja } from "date-fns/locale";
 
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
-import { DatePicker, FormField } from "@godxjp/ui/data-entry";
+import { Form, DatePicker, FormField } from "@godxjp/ui/data-entry";
 import { Flex, PageContainer } from "@godxjp/ui/layout";
 import type { DateRange } from "react-day-picker";
 
@@ -65,23 +65,25 @@ export default function Demo() {
             </CardDescription>
           </CardHeader>
           <CardContent>
-            <Flex gap="lg" wrap>
-              <FormField id="ruled-date" label="罫線あり (既定)">
-                <DatePicker
-                  id="ruled-date"
-                  name="ruled_date"
-                  defaultValue={new Date(2026, 0, 15)}
-                />
-              </FormField>
-              <FormField id="unruled-date" label="罫線なし (bordered={false})">
-                <DatePicker
-                  id="unruled-date"
-                  name="unruled_date"
-                  defaultValue={new Date(2026, 0, 15)}
-                  bordered={false}
-                />
-              </FormField>
-            </Flex>
+            <Form>
+              <Flex gap="lg" wrap>
+                <FormField id="ruled-date" label="罫線あり (既定)">
+                  <DatePicker
+                    id="ruled-date"
+                    name="ruled_date"
+                    defaultValue={new Date(2026, 0, 15)}
+                  />
+                </FormField>
+                <FormField id="unruled-date" label="罫線なし (bordered={false})">
+                  <DatePicker
+                    id="unruled-date"
+                    name="unruled_date"
+                    defaultValue={new Date(2026, 0, 15)}
+                    bordered={false}
+                  />
+                </FormField>
+              </Flex>
+            </Form>
           </CardContent>
         </Card>
 
@@ -231,31 +233,33 @@ export default function Demo() {
             <CardTitle level={2}>表示形式と元号</CardTitle>
           </CardHeader>
           <CardContent>
-            <Flex direction="col" gap="md">
-              <FormField id="formatted-date" label="契約日">
-                <DatePicker
-                  id="formatted-date"
-                  name="contract"
-                  defaultValue={new Date(2026, 8, 9)}
-                  format="yyyy年MM月dd日"
-                />
-              </FormField>
-              <FormField id="era-date" label="和暦">
-                <DatePicker
-                  id="era-date"
-                  name="era"
-                  defaultValue={new Date(2026, 8, 9)}
-                  format={{
-                    calendar: "japanese",
-                    era: "long",
-                    year: "numeric",
-                    month: "long",
-                    day: "numeric",
-                  }}
-                  inputReadOnly
-                />
-              </FormField>
-            </Flex>
+            <Form>
+              <Flex direction="col" gap="md">
+                <FormField id="formatted-date" label="契約日">
+                  <DatePicker
+                    id="formatted-date"
+                    name="contract"
+                    defaultValue={new Date(2026, 8, 9)}
+                    format="yyyy年MM月dd日"
+                  />
+                </FormField>
+                <FormField id="era-date" label="和暦">
+                  <DatePicker
+                    id="era-date"
+                    name="era"
+                    defaultValue={new Date(2026, 8, 9)}
+                    format={{
+                      calendar: "japanese",
+                      era: "long",
+                      year: "numeric",
+                      month: "long",
+                      day: "numeric",
+                    }}
+                    inputReadOnly
+                  />
+                </FormField>
+              </Flex>
+            </Form>
           </CardContent>
         </Card>
         <Card>