@godxjp/ui 28.8.0 → 28.10.0

package/agent/components/ThoughtChain.json

@@ -0,0 +1,76 @@
+{
+  "docPath": "data-display/thought-chain.tsx",
+  "example": "import { ThoughtChain } from \"@godxjp/ui/data-display\";\n\n<ThoughtChain\n  label=\"思考の手順\"\n  defaultExpandedKeys={[\"search\"]}\n  items={[\n    { key: \"read\", title: \"資料を読む\", description: \"3件\", status: \"success\" },\n    {\n      key: \"search\",\n      title: \"社内規程を検索\",\n      status: \"loading\",\n      collapsible: true,\n      blink: true,\n      content: <pre>{hits}</pre>,\n    },\n    { key: \"write\", title: \"下書きを書く\", status: \"abort\" },\n  ]}\n/>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "ThoughtChain",
+  "props": [
+    {
+      "description": "The steps: { key?, icon?, title?, description?, content?, footer?, status?, collapsible?, blink?, destroyOnHidden? }. `icon: false` drops the glyph column; omitted, the step shows its 1-based ordinal (Ant Design X's own default).",
+      "name": "items",
+      "type": "ThoughtChainItemsProp[]"
+    },
+    {
+      "description": "Uncontrolled initially-open steps.",
+      "name": "defaultExpandedKeys",
+      "type": "string[]"
+    },
+    {
+      "description": "Controlled open steps.",
+      "name": "expandedKeys",
+      "type": "string[]"
+    },
+    {
+      "description": "Fires with the NEXT open set.",
+      "name": "onExpand",
+      "type": "(keys: string[]) => void"
+    },
+    {
+      "defaultValue": "true",
+      "description": "The connector drawn between steps. false draws none. (Ant Design X's own type spells the third with a stray U+200C, so `line=\"dotted\"` does not type-check there; the clean spelling is used here.)",
+      "name": "line",
+      "type": "boolean | \"solid\" | \"dashed\" | \"dotted\""
+    },
+    {
+      "description": "Accessible name of the chain (a plain string). Localized default otherwise.",
+      "name": "label",
+      "type": "string"
+    },
+    {
+      "description": "DOM id of the chain root.",
+      "name": "id",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "Timeline — the same vertical rail for events that ALREADY happened. Use it when nothing is in flight.",
+    "Steps — a wizard's progress across a form. ThoughtChain is the assistant's own reasoning, not the user's path.",
+    "Accordion — a general disclosure list with no rail, no ordinal and no status.",
+    "ChatBubble — the answer the chain explains."
+  ],
+  "rules": [
+    2,
+    6,
+    23,
+    44,
+    45
+  ],
+  "storyPath": "data-display/ThoughtChain.stories.tsx",
+  "subParts": [
+    "ThoughtChainItem"
+  ],
+  "tagline": "The assistant's reasoning, step by step (Ant Design X ThoughtChain): an ORDERED list of steps, each with an ordinal or a glyph, a status, and a body it can collapse — where Ant X's own step is a <div onClick> with no role and no aria-expanded.",
+  "usage": [
+    "DO give every step a stable `key` — it is what expandedKeys addresses and what onExpand reports.",
+    "DO set `collapsible` on a step whose `content` is long (a tool's raw output, a retrieved passage). The title then becomes a real disclosure button with aria-expanded, keyboard-reachable; without `collapsible` the body is simply always shown.",
+    "DO use `status` for how a step ENDED — loading / success / error / abort. The word rides along in a visually hidden span, so the state is never carried by the tint alone.",
+    "DO use `blink` while a step is still streaming; it pulses the title and body and collapses to nothing under prefers-reduced-motion.",
+    "DON'T reach for it for events that already happened — that is Timeline. A thought chain is a run IN PROGRESS, which is why it has loading and abort states and a body that opens.",
+    "DON'T expect `styles`/`classNames` from Ant Design X — retune through the --thought-chain-* tokens."
+  ],
+  "useCases": [
+    "An agent's tool calls under its answer: read the documents, search the policy, draft the reply — each with its output collapsed.",
+    "A long-running job's progress inside a chat: the current step blinking, the finished ones ticked, an aborted one greyed.",
+    "ThoughtChainItem alone: the chip an assistant drops inline to name the tool it just reached for."
+  ]
+}

package/agent/components/Thumbnail.json

@@ -0,0 +1,70 @@
+{
+  "docPath": "data-display/thumbnail.tsx",
+  "example": "import { Thumbnail } from \"@godxjp/ui/data-display\";\n\n<Flex gap=\"sm\" wrap align=\"start\">\n  <Thumbnail src=\"/shot-portrait.png\" width={360} height={640} alt=\"モバイル版の一覧画面\" size=\"lg\" />\n  <Thumbnail src=\"/shot-desktop.png\" width={960} height={540} alt=\"デスクトップ版のダッシュボード\" size=\"lg\" />\n</Flex>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "Thumbnail",
+  "props": [
+    {
+      "description": "Image URL.",
+      "name": "src",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "Required by the type. Pass \"\" for a picture that carries no information the page does not already say — the empty string is a decision, a missing attribute is an omission (WCAG 1.1.1).",
+      "name": "alt",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Frame height — sm 64px (an attachment strip), md 96px (a gallery row), lg 160px (a review screen). The width follows the picture's own ratio.",
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "description": "The file's real pixel width. Pass it with `height` and the browser knows the ratio before the bytes land, so the frame takes its final width on the first paint instead of reflowing the row.",
+      "name": "width",
+      "type": "number"
+    },
+    {
+      "description": "The file's real pixel height. See `width`.",
+      "name": "height",
+      "type": "number"
+    },
+    {
+      "description": "Native img attribute, passed through. Every other img attribute passes through too.",
+      "name": "loading",
+      "type": "\"lazy\" | \"eager\""
+    },
+    {
+      "description": "Root class. The three heights, the hairline and the radius live in the --thumbnail-* tokens.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "AspectRatio — a ratio-constrained slot at full width; use it when YOU choose the ratio, not when the picture does.",
+    "Avatar — an identity mark for a person, team or entity, with an initials fallback.",
+    "CardCover — the full-bleed media slot at the top of a Card.",
+    "Carousel — for a set too large to lay out at once; a wrap row of 2–5 thumbnails is not a carousel."
+  ],
+  "rules": [],
+  "storyPath": "data-display/Thumbnail.stories.tsx",
+  "tagline": "A framed picture at a FIXED height with its own INTRINSIC width — the shape a wrapping row of screenshots with different aspect ratios needs.",
+  "usage": [
+    "DO import from `@godxjp/ui/data-display`: `import { Thumbnail } from \"@godxjp/ui/data-display\";`",
+    "DO wrap a row of them in `<Flex gap=\"sm\" wrap align=\"start\">` — equal heights make the strip read as one row while each width stays natural.",
+    "DO pass the file's real `width` and `height` so the row does not reflow while the pictures load.",
+    "DON'T use AspectRatio for this: it spans `width: 100%` and pins ONE ratio, so a row of mixed-ratio screenshots comes out letterboxed or cropped. AspectRatio is for a slot whose ratio you choose.",
+    "DON'T use Avatar (an identity mark with an initials fallback) or Card (it pads the frame away from the picture). CardCover is the full-bleed media slot inside a Card, not a standalone thumbnail.",
+    "DON'T hand-roll `<img className=\"h-40 w-auto rounded-md border\" />` — `no-hand-rolled-surface` flags it, correctly: border + radius is a surface."
+  ],
+  "useCases": [
+    "A review screen showing a submission's screenshots, portrait and landscape in the same wrapping row.",
+    "An attachment strip beside a message or a ticket, at `size=\"sm\"`.",
+    "A gallery row of uploaded images where each picture must stay uncropped.",
+    "Any picture that needs a hairline so a light image is distinguishable from the card behind it."
+  ]
+}

package/agent/components/TimePicker.json

@@ -0,0 +1,200 @@
+{
+  "example": "import { FormField, TimePicker } from \"@godxjp/ui/data-entry\";\nimport { Button } from \"@godxjp/ui/general\";\nimport { useState } from \"react\";\n\n// Controlled usage inside a React form\nexport function ShiftStartField() {\n  const [startTime, setStartTime] = useState(\"09:00\");\n\n  return (\n    <FormField id=\"shift-start\" label=\"Shift start\" controlWidth=\"9rem\">\n      <TimePicker\n        id=\"shift-start\"\n        name=\"shift_start\"\n        value={startTime}\n        onValueChange={setStartTime}\n        minuteStep={15}\n      />\n    </FormField>\n  );\n}\n\n// Uncontrolled usage inside a native form\nexport function CutoffTimeForm() {\n  return (\n    <form method=\"post\" action=\"/settings/cutoff\">\n      <TimePicker\n        id=\"cutoff\"\n        name=\"cutoff_time\"\n        defaultValue=\"17:00\"\n        minuteStep={30}\n        placeholder=\"hh:mm\"\n      />\n      <Button type=\"submit\">Save</Button>\n    </form>\n  );\n}",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "TimePicker",
+  "props": [
+    {
+      "description": "Opt-in wheel selection, skipping disabled entries without closing the panel. Defaults off.",
+      "name": "changeOnScroll",
+      "type": "boolean"
+    },
+    {
+      "description": "Controlled panel visibility.",
+      "name": "open",
+      "type": "boolean"
+    },
+    {
+      "description": "Initial panel visibility.",
+      "name": "defaultOpen",
+      "type": "boolean"
+    },
+    {
+      "description": "Panel visibility changes.",
+      "name": "onOpenChange",
+      "type": "(open: boolean) => void"
+    },
+    {
+      "description": "Validation appearance; error announces invalid state.",
+      "name": "status",
+      "type": "\"error\" | \"warning\""
+    },
+    {
+      "description": "Shared control surface.",
+      "name": "variant",
+      "type": "\"outlined\" | \"filled\" | \"borderless\""
+    },
+    {
+      "description": "Shared control sizing.",
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "description": "Disable typing while preserving panel selection.",
+      "name": "inputReadOnly",
+      "type": "boolean"
+    },
+    {
+      "description": "Keep invalid draft text on blur; never submit it as a committed value.",
+      "name": "preserveInvalidOnBlur",
+      "type": "boolean"
+    },
+    {
+      "description": "Logical popup placement.",
+      "name": "placement",
+      "type": "\"bottom-start\" | \"bottom-end\" | \"top-start\" | \"top-end\""
+    },
+    {
+      "description": "Additional panel footer content.",
+      "name": "renderExtraFooter",
+      "type": "() => ReactNode"
+    },
+    {
+      "description": "Ref to the editable input (range start).",
+      "name": "ref",
+      "type": "Ref<HTMLInputElement>"
+    },
+    {
+      "description": "Hour column step, default 1.",
+      "name": "hourStep",
+      "type": "number"
+    },
+    {
+      "description": "Second column step, default 1.",
+      "name": "secondStep",
+      "type": "number"
+    },
+    {
+      "description": "Enable seconds in the panel and canonical value.",
+      "name": "showSeconds",
+      "type": "boolean"
+    },
+    {
+      "description": "Override the locale hour cycle.",
+      "name": "use12Hours",
+      "type": "boolean"
+    },
+    {
+      "description": "HH:mm, HH:mm:ss, h:mm A or date-fns a. Canonical value stays HH:mm or HH:mm:ss.",
+      "name": "format",
+      "type": "string"
+    },
+    {
+      "description": "Forbid individual hours, minutes and seconds. Without it a 開始/終了 pair has no way to stop the end time being set before the start — the columns will happily offer it. Applies to BOTH routes into the value: a disabled option cannot be clicked, is skipped by the arrow keys, and a forbidden time typed into the field is rejected.",
+      "name": "disabledTime",
+      "type": "TimePickerDisabledTimeProp"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Drop disabled options from the columns instead of greying them out (antd's default too). Greyed-out is usually better — a visible-but-refused option tells the reader the rule exists — but a column that is mostly forbidden reads better short.",
+      "name": "hideDisabledOptions",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Offer a \\u201cnow\\u201d action in the panel footer (antd's `showNow`). It is REFUSED, not hidden, when `disabledTime` forbids the current time — the same treatment a forbidden column option gets.",
+      "name": "showNow",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Hold the panel's choices as a DRAFT until a confirm action commits them (antd's `needConfirm`). Default `false` diverges from antd deliberately: this library has always committed on select and closed, and flipping the default would silently add a click to every existing time field. Opt in where the value is expensive to change (a saved shift, a published slot).",
+      "name": "needConfirm",
+      "type": "boolean"
+    },
+    {
+      "description": "Controlled value in HH:mm (24h) format. When provided the component is fully controlled — you must update it via `onValueChange`.",
+      "name": "value",
+      "type": "string"
+    },
+    {
+      "description": "Uncontrolled initial value in HH:mm format. Used only when `value` is not provided.",
+      "name": "defaultValue",
+      "type": "string"
+    },
+    {
+      "description": "Called with the canonical HH:mm string whenever the user commits a time (picks from columns or types and blurs/presses Enter). Not called for every keystroke.",
+      "name": "onValueChange",
+      "type": "(value: string) => void"
+    },
+    {
+      "description": "Native form field name. Formatted or staged controls manage a hidden canonical value internally; do not add a second hidden field.",
+      "name": "name",
+      "type": "string"
+    },
+    {
+      "description": "HTML id for the visible input — use with a `<label htmlFor>` for accessibility.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "defaultValue": "hh:mm (i18n fallback)",
+      "description": "Placeholder text shown when the input is empty. Falls back to the i18n key `dataEntry.timePicker.placeholder`.",
+      "name": "placeholder",
+      "type": "string"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Disables both the visible input and the clock-icon popover trigger.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "5",
+      "description": "Step for the minute column (1–60). Only multiples of this step appear in the picker; typed values are still free-form and normalized on blur.",
+      "name": "minuteStep",
+      "type": "number"
+    },
+    {
+      "description": "Extra Tailwind classes applied to the outer wrapper `<div>`. Use for width overrides (e.g. `w-32`).",
+      "name": "className",
+      "type": "string"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Inline ✕ on the trigger that resets the value when one is set (Ant-style). Pass `false` to hide it (e.g. a required field).",
+      "name": "allowClear",
+      "type": "boolean"
+    }
+  ],
+  "related": [
+    "DatePicker — use for calendar date selection; combine with TimePicker in a flex row when you need a full datetime. DatePicker emits an ISO date string; TimePicker emits HH:mm.",
+    "Input — the raw primitive TimePicker wraps internally. Use Input directly only when you need a plain text field with no time semantics or popover.",
+    "ColorPicker — another popover-backed input primitive in the same group; structurally similar pattern but for hex colour values."
+  ],
+  "rules": [
+    3,
+    6,
+    13,
+    23
+  ],
+  "storyPath": "data-entry/TimePicker.stories.tsx",
+  "tagline": "Time combobox with hours, minutes, optional seconds, confirmation and 12-hour formatting. Native submission stays canonical 24-hour time.",
+  "usage": [
+    "One trailing icon: empty shows calendar/clock; filled and clearable shows only ×; allowClear=false retains the picker icon. Click the input or ArrowDown to open a filled picker.",
+    "DO give it a name in native forms. It submits HH:mm or HH:mm:ss, regardless of display format; the component manages any hidden canonical field.",
+    "DO use the controlled pattern (`value` + `onValueChange`) in React-managed forms (e.g. useForm). For simple HTML forms without React state, omit `value` and use `defaultValue` for the uncontrolled pattern.",
+    "DON'T pass a raw `<input type='time'>` alongside or instead — this component IS the input, fully accessible (role='combobox', aria-expanded, aria-haspopup) and e2e-testable by filling the text input directly.",
+    "DO pair with a `<label htmlFor={id}>` for screen-reader accessibility — the component renders a plain `<input>` internally that `id` connects to.",
+    "DON'T expect `onValueChange` on every keystroke — it fires only when a valid HH:mm is committed (column pick closes popover; typed value normalised on blur or Enter). Guard downstream logic accordingly.",
+    "DO adjust `minuteStep` for domain needs (e.g. `minuteStep={15}` for scheduling, `minuteStep={1}` for precise entry) — the minute column only shows multiples, but the type-in field accepts any valid HH:mm."
+  ],
+  "useCases": [
+    "Shift/schedule entry forms where workers select start and end times from a scrollable hour/minute grid (use `minuteStep={15}` or `minuteStep={30}`).",
+    "Invoice or transaction timestamp fields that require a 24h HH:mm time alongside a DatePicker — pair the two in a flex row.",
+    "Logistics cut-off time configuration (e.g. 'last order by') where the default `minuteStep={5}` aligns with typical operational granularity.",
+    "Admin settings panels that persist a canonical HH:mm string to the database — the `name` prop makes native form submission trivial.",
+    "Time-range pickers (from/to) — render two TimePicker instances side-by-side with separate controlled values and validate that `to > from` in `onValueChange`.",
+    "E2E-tested forms — test helpers can fill the text input directly (it accepts typed HH:mm) without needing to interact with the popover columns."
+  ]
+}

package/agent/components/TimeRangePicker.json

@@ -0,0 +1,90 @@
+{
+  "docPath": "docs/data-entry/time-range-picker.tsx",
+  "example": "import { TimeRangePicker } from \"@godxjp/ui/data-entry\";\n<TimeRangePicker aria-label=\"Shift\" defaultValue={[\"09:00\", \"18:00\"]} />",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "TimeRangePicker",
+  "props": [
+    {
+      "description": "Controlled canonical times.",
+      "name": "value",
+      "type": "[string,string]"
+    },
+    {
+      "description": "Uncontrolled initial range.",
+      "name": "defaultValue",
+      "type": "[string,string]"
+    },
+    {
+      "description": "Reports edited range.",
+      "name": "onValueChange",
+      "type": "(value: [string,string]) => void"
+    },
+    {
+      "description": "Sort times automatically; false allows overnight ranges.",
+      "name": "order",
+      "type": "boolean"
+    },
+    {
+      "description": "Permitted empty endpoints, default [true,true].",
+      "name": "allowEmpty",
+      "type": "[boolean,boolean]"
+    },
+    {
+      "description": "Native names are name_from and name_to.",
+      "name": "name",
+      "type": "string"
+    },
+    {
+      "description": "TimePicker display format.",
+      "name": "format",
+      "type": "string"
+    },
+    {
+      "description": "Shared time constraints.",
+      "name": "disabledTime",
+      "type": "TimePickerDisabledTimeProp"
+    },
+    {
+      "description": "Enable second precision.",
+      "name": "showSeconds",
+      "type": "boolean"
+    },
+    {
+      "description": "Minute column step.",
+      "name": "minuteStep",
+      "type": "number"
+    },
+    {
+      "description": "Hour column step.",
+      "name": "hourStep",
+      "type": "number"
+    },
+    {
+      "description": "Second column step.",
+      "name": "secondStep",
+      "type": "number"
+    },
+    {
+      "description": "Permit clear only for an endpoint also allowed empty.",
+      "name": "allowClear",
+      "type": "boolean"
+    }
+  ],
+  "related": [
+    "TimePicker",
+    "DatePicker"
+  ],
+  "rules": [
+    9
+  ],
+  "storyPath": "data-entry/time-range-picker.tsx",
+  "tagline": "Ordered time range with optional endpoints and canonical native fields.",
+  "usage": [
+    "Use for a start/end time pair. Set order=false for overnight intervals.",
+    "Each endpoint follows the one-trailing-icon rule; allowEmpty=false suppresses its clear action."
+  ],
+  "useCases": [
+    "Shift scheduling and reception hours."
+  ]
+}

package/agent/components/Timeline.json

@@ -0,0 +1,47 @@
+{
+  "example": "import { Timeline } from \"@godxjp/ui/data-display\";\n\n// Default icon variant\n<Timeline items={[\n  { title: \"注文受付\", time: \"2024-06-01 10:00\" },\n  { title: \"発送準備中\", time: \"2024-06-01 14:00\" },\n  { title: \"配送中\", current: true },\n]} />\n\n// Numbered route stepper (Pattern A)\n<Timeline variant=\"ordinal\" items={[\n  { title: \"集荷\", location: \"東京 → 名古屋\", status: \"pending\" },\n  { title: \"幹線輸送\", location: \"名古屋 → 大阪\", status: \"pending\" },\n]} />\n\n// Status tracker (Pattern B): done → check, current → dot, pending → number\n<Timeline variant=\"status\" items={[\n  { title: \"請求書を発行\", status: \"done\" },\n  { title: \"承認待ち\", status: \"current\" },\n  { title: \"消費税を計上\", status: \"pending\" },\n]} />",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "Timeline",
+  "props": [
+    {
+      "description": "Array of `{ title, location?, time?, note?, current?, status?, icon? }`. `status` is the explicit 3-state ('done' | 'current' | 'pending'); `current: true` is shorthand for `status: 'current'`. `icon` (a LucideIcon) overrides the auto-glyph for that item.",
+      "name": "items",
+      "required": true,
+      "type": "TimelineItem[]"
+    },
+    {
+      "description": "Rail glyph strategy (default 'icon'). 'icon' = legacy look (Plane for current, CheckCircle2 otherwise). 'ordinal' = every glyph is its 1-based step number; status sets colour only. 'status' = glyph by status (done → check, current → filled dot, pending → step number).",
+      "name": "variant",
+      "type": "\"icon\" | \"ordinal\" | \"status\""
+    }
+  ],
+  "related": [
+    "Steps — use Steps (navigation group) when the user must actively progress through a wizard (interactive, shows step numbers/status, horizontal layout by default); use Timeline for read-only historical event sequences that have already happened.",
+    "Descriptions — use Descriptions to display a flat set of label/value metadata fields (e.g., invoice header); use Timeline when events are ordered chronologically and a connector rail communicates sequence and progress.",
+    "DataTable — use DataTable for multi-row, multi-column tabular event logs where sorting, filtering, and pagination are needed; use Timeline when the sequence/rail visual is the primary communication and there are fewer than ~10 events.",
+    "Badge — Badge is a single-item inline indicator; Timeline sequences multiple statuses with connectors. Compose Badge inside a Timeline `title` or `note` field for richer per-event context, but do not replace Timeline with a stack of Badges."
+  ],
+  "rules": [],
+  "storyPath": "data-display/Timeline.stories.tsx",
+  "tagline": "Vertical event list with an icon rail. Current item gets a highlighted glyph. `variant` switches the rail to numbered (ordinal) or status-driven glyphs, and each item carries a 3-state `status` (done/current/pending) plus an optional per-item `icon`. The whole progress column is ONE hue: done dot, current dot and travelled line all paint `--primary`, exactly as `Steps` paints `finish` and `process`.",
+  "usage": [
+    "DO pass an array of `TimelineItem` objects to `items`. Each item is `{ title, location?, time?, note?, current?, status?, icon? }`. All fields except `title` are optional. The only other prop is `variant`.",
+    "DO mark the in-progress event with `current: true` (or `status: 'current'`). In the default `variant='icon'`, the current item renders a `Plane` icon and every other item a `CheckCircle2`. Use `variant='ordinal'` for a numbered route stepper (1,2,3…) or `variant='status'` for a done→check / current→dot / pending→number tracker. Pass `status: 'done' | 'current' | 'pending'` per item to drive colour and (in the status variant) the glyph; pass `icon` (a LucideIcon) to override the glyph for a single item.",
+    "DO pass `ReactNode` to `title`, `location`, `time`, and `note` — you can embed formatted text, `<Badge>`, `<Badge>`, or `<span>` inside those fields. Use `formatDate` to pre-format timestamps before passing them as `time`.",
+    "DO NOT hand-roll a vertical event list with divs, icons, and connector lines — that is exactly what Timeline ships. Do not apply extra padding or wrapping outside the component; it manages its own rail and spacing internally.",
+    "DO NOT use Timeline for user-facing wizard progress (steps the user must complete in order) — use `Steps` for that. Timeline is read-only historical/status display; it has no interactive state, no `onClick`, and no concept of 'go to step'.",
+    "DO wrap Timeline in `<CardContent>` when placing it inside a `Card` — bare `Card` has no inner padding, so the rail will render flush against the card edge without `CardContent`.",
+    "THE PROGRESS COLUMN IS ONE HUE (gh#731). The done dot, the current dot and the travelled line all default to `hsl(var(--primary))` — the same contract `Steps` uses for `finish` + `process`, and antd's (only `error` leaves the primary hue). The current item is told apart by a ring (`--timeline-dot-current-ring-width`, `--steps-dot-process-ring-width`'s value), by `aria-current=\"step\"` + a localized sr-only prefix, and by a different glyph — never by a second colour role. Re-theme `--primary` and the whole rail follows. Measured light: done 2.18:1 → 6.31:1 against the card, glyph 6.31:1 on the fill; dark 7.22:1 → 9.84:1, glyph 10.72:1.",
+    "DON'T expect `--success` on a `status: 'done'` item — `done | current | pending` is POSITION IN A SEQUENCE, not status, and Timeline has no `tone` axis. Put a real status on the item's `title` or `note` with a `<Badge tone=\"success\">`, which is the surface that owns the status green.",
+    "TO RESTORE the pre-27.9 green/violet pairing, set the done dot's fill AND its ink together in your theme (global or `[data-tenant]`) — the two roles have opposite ink polarity, so the fill alone leaves a near-white glyph on 若竹 green at 2.18:1 (gh#643): `--timeline-dot-done-background: hsl(var(--success)); --timeline-dot-done-foreground: hsl(var(--success-foreground));`. `--timeline-dot-current-background` and `--timeline-line-completed-background` retint the other two surfaces the same way."
+  ],
+  "useCases": [
+    "Shipment / delivery tracking — showing a parcel's journey through 'Order placed → Packed → In transit → Delivered' with timestamps and a current-stop indicator.",
+    "Accounting document audit trail — rendering the lifecycle of an invoice or payment (Draft → Submitted → Approved → Paid) with the current approval stage highlighted.",
+    "Support ticket / task history — displaying a chronological log of status transitions (Open → Assigned → In Review → Closed) with agent names in the `note` field and timestamps in `time`.",
+    "MF sync log viewer — listing each sync run event (OAuth refresh, fetch, upsert) with timestamps and record counts so an operator can see what the last sync did.",
+    "Approval workflow status panel — showing a multi-stage approval chain where completed stages have CheckCircle2 icons and the pending stage has the Plane (in-flight) icon.",
+    "Order / purchase-order lifecycle in an admin detail page — placed alongside a `Descriptions` summary at the top of a `Card` to give a compact at-a-glance history."
+  ]
+}

package/agent/components/TimelineGrid.json

@@ -0,0 +1,92 @@
+{
+  "example": "import { TimelineGrid } from \"@godxjp/ui/data-display\";\n\n<TimelineGrid\n  label=\"週シフト 5月11日〜17日\"\n  start=\"06:00\"\n  end=\"24:00\"\n  interval={2}\n  now=\"14:35\"\n  columns={[\n    { id: \"05-13\", label: \"水 13\" },\n    { id: \"05-14\", label: \"木 14\", current: true },\n  ]}\n  events={[\n    { id: \"a\", columnId: \"05-14\", start: \"09:00\", end: \"17:30\", title: \"早番\", description: \"田中\" },\n    { id: \"b\", columnId: \"05-14\", start: \"13:00\", end: \"22:00\", title: \"遅番\", description: \"高橋\" },\n    { id: \"c\", columnId: \"05-14\", start: \"22:00\", end: \"06:00\", title: \"夜勤\", description: \"伊藤\" },\n  ]}\n  onEventSelect={(event) => openShift(event.id)}\n/>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "TimelineGrid",
+  "props": [
+    {
+      "description": "Accessible name of the grid. Required, and a plain string: the grid is a focusable scrolling region, so its name has to survive as an `aria-label`.",
+      "name": "label",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "`{ id, label, description?, current? }` in render order. `label` is the column head AND the accessible name of that column's event list, so keep it text. `current: true` marks today's column: it takes the tint and hosts the `now` marker.",
+      "name": "columns",
+      "required": true,
+      "type": "TimelineGridColumnProp[]"
+    },
+    {
+      "description": "`{ id, columnId, start, end, title, description?, color? }` in any order. `start`/`end` are clock times in the column's own day, `\"HH:MM\"` 24-hour (`\"24:00\"` = end of day). An `end` at or before `start` continues into the next day (22:00–06:00 夜勤). `color` is the record's own colour, washed like `Badge color`.",
+      "name": "events",
+      "required": true,
+      "type": "TimelineGridEventProp[]"
+    },
+    {
+      "defaultValue": "the earliest event, on the hour",
+      "description": "First clock time on the axis, `\"HH:MM\"`. Left off, the axis is derived from the events, so a block can only fall outside an axis you PINNED.",
+      "name": "start",
+      "type": "string"
+    },
+    {
+      "defaultValue": "the latest event, on the hour",
+      "description": "Last clock time on the axis, `\"HH:MM\"`. A block the pinned axis cuts is drawn to the edge and carries `data-clipped`, and still prints its real range as text.",
+      "name": "end",
+      "type": "string"
+    },
+    {
+      "defaultValue": "1",
+      "description": "Hours between hour rules and axis labels. Use 2 or 3 when a long axis has to fit one screen.",
+      "name": "interval",
+      "type": "number"
+    },
+    {
+      "description": "Current clock time, `\"HH:MM\"`. Draws the now marker in every column marked `current`. The marker is decorative (`aria-hidden`): the hours it points at are already text on every block.",
+      "name": "now",
+      "type": "string"
+    },
+    {
+      "description": "Block click handler. Its PRESENCE turns every block into a real `button`, which is what makes the blocks keyboard-reachable; without it the grid is a read-only board.",
+      "name": "onEventSelect",
+      "type": "(event: TimelineGridEventProp) => void"
+    },
+    {
+      "description": "Extra classes on the scroll region.",
+      "name": "className",
+      "type": "string"
+    },
+    {
+      "description": "DOM id on the scroll region.",
+      "name": "id",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "Timeline — one lane of ordered events with no scale (an audit trail, a shipment history). TimelineGrid is the same family with a measured time axis and one lane per column.",
+    "Table — the MONTH calendar is a real table (`bordered`, one row per week, one cell per day), not a TimelineGrid.",
+    "Calendar — the single-date PICKER in data-entry. Use it to jump to a month; it does not show events.",
+    "Sheet — the usual destination of `onEventSelect`: the block is the affordance, the drawer is the detail.",
+    "Badge — the same `color` wash for a record's own colour, on a chip instead of a block."
+  ],
+  "rules": [
+    42,
+    45
+  ],
+  "storyPath": "data-display/TimelineGrid.stories.tsx",
+  "tagline": "The time-axis half of the Timeline family: a vertical hour axis, one column per day (or room, or machine) and event blocks placed by start time and duration. Overlapping events are laid out side by side automatically. NOT a calendar — no month view, no navigation, no drag-to-create, no recurrence, no timezone conversion.",
+  "usage": [
+    "DO import from `@godxjp/ui/data-display`: `import { TimelineGrid } from \"@godxjp/ui/data-display\";`",
+    "DO give a shift/booking board one column per day and let the grid place the blocks. DON'T hand-roll a `relative` container with absolutely-positioned divs and percentage offsets — that is the exact shape this primitive replaces (#354 item 7), and it hides one of two overlapping shifts.",
+    "DO re-tune the rhythm with the tokens instead of a className: `--timeline-grid-hour-height` is the height of one hour (the knob that fits a 24-hour axis on one screen), `--timeline-grid-column-min-width` is the floor below which the grid scrolls instead of collapsing, `--timeline-grid-axis-width` is the hour rail, and `--timeline-grid-event-color` / `--timeline-grid-now-color` / `--timeline-grid-current-tint` are role-mirror colour knobs.",
+    "DO express a shift that crosses midnight as `start: \"22:00\", end: \"06:00\"` — an `end` at or before `start` means the next day. The block is drawn to the end of the window and marked `data-clipped`, and the text still reads 22:00–06:00.",
+    "DON'T reach for TimelineGrid for a MONTH calendar: a month grid is a real `Table`, one `TableRow` per week and one `TableCell` per day. TimelineGrid owns the continuous time axis, not the day matrix.",
+    "DON'T expect navigation, drag-to-create, recurrence or timezone conversion — none of it ships. `start`/`end` are clock times in the column's own day; which day a column stands for is yours to decide.",
+    "DON'T pass an event whose `columnId` matches no column, or one that falls entirely outside a pinned `start`/`end`: it is not drawn. Leave the axis unpinned and it is derived from the events instead."
+  ],
+  "useCases": [
+    "A weekly shift board (シフトカレンダー): seven day columns on a 06:00–24:00 axis, 早番 / 遅番 / 夜勤 blocks in the decorative wa-iro palette, `now` drawing the current-time line on today's column.",
+    "A day view of one team: one column per staff member, `interval={1}`, `onEventSelect` opening the shift detail in a Sheet.",
+    "Meeting-room booking for a single day: one column per room, the axis derived from the bookings themselves, overlapping holds side by side so a double-booking is visible instead of hidden.",
+    "Machine / bay utilisation on a shop floor: one column per machine, blocks coloured by job, the clipped marker showing a run that continues past the shift window."
+  ]
+}