@godxjp/ui 28.9.0 → 28.12.0

package/agent/components/TreeSelect.json

@@ -0,0 +1,232 @@
+{
+  "example": "import { useState } from \"react\";\nimport { FormField, TreeSelect } from \"@godxjp/ui/data-entry\";\n\nconst accountTree = [\n  {\n    value: \"assets\",\n    label: \"Assets\",\n    content: [\n      { value: \"current-assets\", label: \"Current Assets\", content: [\n          { value: \"cash\", label: \"Cash\" },\n          { value: \"ar\", label: \"Accounts Receivable\" },\n        ],\n      },\n      { value: \"fixed-assets\", label: \"Fixed Assets\", content: [\n          { value: \"equipment\", label: \"Equipment\" },\n        ],\n      },\n    ],\n  },\n  {\n    value: \"liabilities\",\n    label: \"Liabilities\",\n    content: [\n      { value: \"ap\", label: \"Accounts Payable\" },\n    ],\n  },\n];\n\n// Single-select (returns string | undefined)\nexport function AccountPicker() {\n  const [account, setAccount] = useState<string | undefined>();\n  return (\n    <FormField id=\"account-picker\" label=\"GL Account\">\n      <TreeSelect\n        id=\"account-picker\"\n        treeData={accountTree}\n        value={account}\n        onValueChange={(v) => setAccount(v as string | undefined)}\n        showSearch\n        treeDefaultExpandAll\n        placeholder=\"Select account…\"\n        allowClear\n      />\n    </FormField>\n  );\n}\n\n// Multi-select with checkboxes + cascade + SHOW_PARENT display\nexport function DepartmentFilter() {\n  const [selected, setSelected] = useState<string[]>([]);\n  return (\n    <TreeSelect\n      id=\"dept-filter\"\n      treeData={accountTree}\n      value={selected}\n      onValueChange={(v) => setSelected(v as string[])}\n      treeCheckable\n      showCheckedStrategy={TreeSelect.SHOW_PARENT}\n      showSearch\n      placeholder=\"Filter by department…\"\n    />\n  );\n}",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "TreeSelect",
+  "props": [
+    {
+      "description": "Native form field name; repeated values for multiple selections.",
+      "name": "name",
+      "type": "string"
+    },
+    {
+      "description": "Prevent edits while preserving value.",
+      "name": "readOnly",
+      "type": "boolean"
+    },
+    {
+      "description": "The tree data. Each node: `{ value: string; label: ReactNode; disabled?: boolean; disableCheckbox?: boolean; isLeaf?: boolean; children?: TreeOptionProp[] }`. Use `fieldNames` to remap custom keys.",
+      "name": "treeData",
+      "required": true,
+      "type": "TreeOptionProp[]"
+    },
+    {
+      "description": "Controlled selected value(s). Pass `string` in single mode, `string[]` in multi/checkable mode. When undefined the component is uncontrolled.",
+      "name": "value",
+      "type": "string | string[]"
+    },
+    {
+      "description": "Initial value for uncontrolled usage. Ignored once `value` is provided.",
+      "name": "defaultValue",
+      "type": "string | string[]"
+    },
+    {
+      "description": "Called on selection change. Returns `string` in single mode, `string[]` in multi/checkable mode, or `undefined` when cleared.",
+      "name": "onValueChange",
+      "type": "(value: string | string[] | undefined) => void"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Enable multi-select without checkboxes. When true, `onValueChange` always fires with `string[]`.",
+      "name": "multiple",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Render Checkbox controls beside each node. Implies multi-select; cascade-selects all descendants by default unless `treeCheckStrictly` is set.",
+      "name": "treeCheckable",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "When true (only with `treeCheckable`), parent and child selections are independent — checking a parent does NOT auto-check its children.",
+      "name": "treeCheckStrictly",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "\"SHOW_CHILD\"",
+      "description": "Controls which values appear in the trigger label when checkboxes are used. `SHOW_CHILD` (default) — show only leaf nodes selected; `SHOW_PARENT` — show nearest ancestor when all children selected; `SHOW_ALL` — show every checked node. Use the exported constants `TreeSelect.SHOW_CHILD`, `TreeSelect.SHOW_PARENT`, `TreeSelect.SHOW_ALL` instead of raw strings.",
+      "name": "showCheckedStrategy",
+      "type": "\"SHOW_CHILD\" | \"SHOW_PARENT\" | \"SHOW_ALL\""
+    },
+    {
+      "defaultValue": "false",
+      "description": "Show a labelled SearchInput at the top of the dropdown. Filters visible tree nodes by label text; the trigger combobox controls the tree.",
+      "name": "showSearch",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Expand all nodes when the dropdown first opens. Initialised once; does not re-expand on re-render.",
+      "name": "treeDefaultExpandAll",
+      "type": "boolean"
+    },
+    {
+      "description": "Trigger button placeholder text when nothing is selected. Defaults to the i18n key `dataEntry.treeSelect.placeholder`.",
+      "name": "placeholder",
+      "type": "string"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Disables the trigger button and all interactions.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Show an `X` icon in the trigger to clear the selection. Off by default, as antd TreeSelect; pass `allowClear` on an optional field.",
+      "name": "allowClear",
+      "type": "boolean"
+    },
+    {
+      "description": "Additional Tailwind classes applied to the trigger Button.",
+      "name": "className",
+      "type": "string"
+    },
+    {
+      "description": "HTML `id` placed on the trigger Button — use this to associate a `<label htmlFor>` for accessibility.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "description": "Accessible name for the combobox trigger when no visible label is available.",
+      "name": "aria-label",
+      "type": "string"
+    },
+    {
+      "description": "ID of the element containing the current validation error message.",
+      "name": "aria-errormessage",
+      "type": "string"
+    },
+    {
+      "description": "Marks the semantic combobox trigger invalid for assistive technology.",
+      "name": "aria-invalid",
+      "type": "boolean | 'true' | 'false'"
+    },
+    {
+      "description": "Marks the semantic combobox trigger required for assistive technology.",
+      "name": "aria-required",
+      "type": "boolean | 'true' | 'false'"
+    },
+    {
+      "description": "Remap data object keys. Example: `{ label: 'name', value: 'id', children: 'items' }` so you don't have to transform your API response before passing it to `treeData`.",
+      "name": "fieldNames",
+      "type": "{ label?: string; value?: string; children?: string }"
+    },
+    {
+      "description": "antd `status`. `error` recolours the control AND sets aria-invalid (a colour-only error fails WCAG 2.2 SC 1.4.1); `warning` recolours only. An aria-invalid injected by FormField always wins.",
+      "name": "status",
+      "type": "\"error\" | \"warning\""
+    },
+    {
+      "description": "antd `variant` — the control surface. Default `outlined`. Drawn from --control-{surface,filled,borderless}-* tokens, so a theme retunes all three at once.",
+      "name": "variant",
+      "type": "\"outlined\" | \"filled\" | \"borderless\""
+    },
+    {
+      "description": "antd `loading` — the FIELD is in flight: the trailing chevron becomes a spinner and the trigger reports aria-busy. Distinct from the list-level spinner an async loadOptions shows inside the popup.",
+      "name": "loading",
+      "type": "boolean"
+    },
+    {
+      "description": "antd `size` — height tier on the shared --control-height ladder.",
+      "name": "size",
+      "type": "\"xs\" | \"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "description": "antd `open` — controlled panel state. The consumer is the authority: nothing internal closes a pinned panel.",
+      "name": "open",
+      "type": "boolean"
+    },
+    {
+      "description": "antd `defaultOpen` — uncontrolled initial panel state.",
+      "name": "defaultOpen",
+      "type": "boolean"
+    },
+    {
+      "description": "antd `onOpenChange` — fires for both controlled and uncontrolled panels.",
+      "name": "onOpenChange",
+      "type": "(open: boolean) => void"
+    },
+    {
+      "description": "antd `maxTagCount` — how many selected values stay visible before the rest collapse into the overflow node. antd's `\"responsive\"` is not supported (see the parity PR).",
+      "name": "maxTagCount",
+      "type": "number"
+    },
+    {
+      "description": "antd `maxTagPlaceholder` — the node standing in for what maxTagCount hid. Defaults to a localized `+N`.",
+      "name": "maxTagPlaceholder",
+      "type": "React.ReactNode | ((omitted: { value: string; label: React.ReactNode }[]) => React.ReactNode)"
+    },
+    {
+      "description": "antd `notFoundContent` — the node shown when the popup has nothing to list. Outranks the string-only emptyMessage.",
+      "name": "notFoundContent",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "antd `autoClearSearchValue` (default true) — clear the search box after a pick / on close. Set false to resume the same filtered list on the next open.",
+      "name": "autoClearSearchValue",
+      "type": "boolean"
+    },
+    {
+      "description": "antd `loadData` — lazy children. Called ONCE per node that has no children and isLeaf !== true, the first time it is expanded; push the fetched children into treeData. Such a node still reads as expandable (aria-expanded + a working expander).",
+      "name": "loadData",
+      "type": "(node: TreeOptionProp) => void | Promise<void>"
+    },
+    {
+      "description": "antd `treeTitleRender` — owns a node's title only; the checkbox, expander and row ARIA stay with the component.",
+      "name": "treeTitleRender",
+      "type": "(node: TreeOptionProp) => React.ReactNode"
+    },
+    {
+      "description": "Controlled search query (antd `showSearch.searchValue`).",
+      "name": "search",
+      "type": "string"
+    },
+    {
+      "description": "Search query change (antd `showSearch.onSearch`).",
+      "name": "onSearchChange",
+      "type": "(query: string) => void"
+    }
+  ],
+  "related": [
+    "Select — flat single/multi picker; use when data has no parent-child hierarchy. Pick TreeSelect as soon as items have `children`.",
+    "Cascader — also renders tree data but in a multi-column panel where the user drills down column by column; pick Cascader for strict path selection (select a full path Country→Region→City). Pick TreeSelect when the user may select any node at any level or needs checkboxes.",
+    "Checkbox / CheckboxGroup — use for a small, always-visible flat list of options. Use TreeSelect when options are hierarchical or the list is long enough to warrant a dropdown.",
+    "Command / CommandInput — low-level search primitive; TreeSelect already embeds this internally. Do NOT compose your own tree dropdown out of Command — use TreeSelect."
+  ],
+  "rules": [
+    3,
+    6,
+    13,
+    23
+  ],
+  "storyPath": "data-entry/TreeSelect.stories.tsx",
+  "tagline": "Hierarchical tree picker in a Popover (single or multi-select with checkboxes) — `onValueChange` receives `string` in single mode and `string[]` in multi/checkable mode; never use a raw `<select>` for tree-structured data.",
+  "usage": [
+    "DO pair with a `<label htmlFor={id}>` and pass the matching `id` prop so screen readers announce the control correctly. The underlying trigger is a `<Button role='combobox'>` — not a native `<select>` — so an explicit label is required.",
+    "DO use `treeCheckable` (+ optionally `showCheckedStrategy`) for selecting multiple nodes with parent–child cascade; use `multiple` only when you want multi-select WITHOUT the checkbox cascade behaviour.",
+    "DO use the static constants `TreeSelect.SHOW_CHILD`, `TreeSelect.SHOW_PARENT`, `TreeSelect.SHOW_ALL` (or the named exports `SHOW_CHILD`/`SHOW_PARENT`/`SHOW_ALL` from the same import path) instead of raw string literals for `showCheckedStrategy`.",
+    "DON'T pass `value` and `defaultValue` simultaneously — pick controlled (`value` + `onValueChange`) OR uncontrolled (`defaultValue` only). Mixing them causes the component to silently prefer the controlled path.",
+    "DON'T hand-roll `onValueChange` type narrowing: in single mode the callback receives `string | undefined`; in multi/checkable mode it receives `string[]`. Branch on `multiple || treeCheckable` if you need to handle both shapes in the same handler.",
+    "DON'T use a raw `<select>` or a flat `Select` component for hierarchical/nested data — TreeSelect is the correct primitive. If hierarchy is irrelevant and data is flat, use `Select` instead."
+  ],
+  "useCases": [
+    "Chart-of-accounts picker in an accounting app where accounts belong to groups (Assets > Current Assets > Cash) and the user must select one leaf account.",
+    "Multi-select department or cost-centre filter where selecting a parent division should auto-select all child departments (treeCheckable + SHOW_PARENT).",
+    "Category assignment on invoice line items where categories have up to 3 levels of nesting and users can assign a parent or a leaf.",
+    "Permission scope selector where roles are structured in a tree and selecting a parent role should cascade to all child scopes (treeCheckable + treeCheckStrictly=false).",
+    "Location picker (Country > Prefecture > City) in a form where only leaf-level cities are valid selections (single mode, no checkboxes).",
+    "Large GL hierarchy browser with showSearch enabled so users can type to filter thousands of account codes instead of manually expanding nodes."
+  ]
+}

package/agent/components/TwoFactorSetup.json

@@ -0,0 +1,79 @@
+{
+  "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",
+  "importPath": "@godxjp/ui/feedback",
+  "name": "TwoFactorSetup",
+  "props": [
+    {
+      "description": "Controlled dialog state.",
+      "name": "open",
+      "required": true,
+      "type": "boolean"
+    },
+    {
+      "description": "Dialog state callback.",
+      "name": "onOpenChange",
+      "required": true,
+      "type": "(open: boolean) => void"
+    },
+    {
+      "description": "Consumer-provided enrollment secret.",
+      "name": "manualKey",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "Optional QR payload for the same enrollment secret.",
+      "name": "qrValue",
+      "type": "string"
+    },
+    {
+      "description": "Current verification code.",
+      "name": "code",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "Verification-code callback.",
+      "name": "onCodeChange",
+      "required": true,
+      "type": "(code: string) => void"
+    },
+    {
+      "description": "Consumer-owned verification action.",
+      "name": "onConfirm",
+      "required": true,
+      "type": "() => void"
+    },
+    {
+      "description": "Codes shown only after successful enrollment.",
+      "name": "recoveryCodes",
+      "type": "string[]"
+    },
+    {
+      "description": "Recovery-code acknowledgement action.",
+      "name": "onAcknowledge",
+      "required": true,
+      "type": "() => void"
+    },
+    {
+      "description": "All localized copy.",
+      "name": "labels",
+      "required": true,
+      "type": "TwoFactorSetupLabels"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Disables actions while the consumer request runs.",
+      "name": "pending",
+      "type": "boolean"
+    }
+  ],
+  "rules": [],
+  "storyPath": "feedback/TwoFactorSetup.stories.tsx",
+  "tagline": "Canonical two-factor enrollment dialog for QR/manual-key verification and recovery-code acknowledgement.",
+  "usage": [
+    "Keep enrollment, verification, persistence, and secret lifecycle in the consumer; this component is presentational.",
+    "Only pass recovery codes after verification succeeds, and clear them when the dialog lifecycle ends."
+  ]
+}

package/agent/components/Typography.json

@@ -0,0 +1,42 @@
+{
+  "example": "import { Typography } from \"@godxjp/ui/general\";\n\n<Typography>\n  <Typography.Title level={3}>リリースノート</Typography.Title>\n  <Typography.Paragraph>請求書の一括ダウンロードに対応しました。</Typography.Paragraph>\n  <Typography.Link href=\"/changelog\">変更履歴</Typography.Link>\n</Typography>",
+  "group": "general",
+  "importPath": "@godxjp/ui/general",
+  "name": "Typography",
+  "props": [
+    {
+      "defaultValue": "\"article\"",
+      "description": "Rendered element.",
+      "name": "as",
+      "type": "string"
+    },
+    {
+      "description": "antd's private alias for `as`. Accepted so antd code pastes in unchanged; `as` wins when both are passed.",
+      "name": "component",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "Text",
+    "Title",
+    "Paragraph",
+    "Link",
+    "Heading",
+    "Prose"
+  ],
+  "rules": [
+    2,
+    23
+  ],
+  "storyPath": "general/typography.tsx",
+  "tagline": "antd's prose container — a plain <article> that Title / Paragraph / Text / Link sit inside, and the compound root so `<Typography.Text>` from an antd codebase compiles here unchanged.",
+  "usage": [
+    "DO reach for it when you have a RUN of prose — a heading, some paragraphs, a link — rather than one label. A single caption is just `<Text>`.",
+    "DO use the compound spelling when porting from antd: `Typography.Text`, `Typography.Title`, `Typography.Paragraph` and `Typography.Link` ARE the flat `Text` / `Title` / `Paragraph` / `Link` exports, not poorer copies of them.",
+    "DON'T use it as a layout box. It carries type, not spacing — sections are spaced by `PageContainer` and groups by `Flex` / `ResponsiveGrid`."
+  ],
+  "useCases": [
+    "A release-note body: a `Title`, two `Paragraph`s and a `Link`, wrapped so the block rhythm is owned in one place.",
+    "Pasting an antd screen in unchanged, `Typography.Paragraph` and all."
+  ]
+}

package/agent/components/Upload.json

@@ -0,0 +1,221 @@
+{
+  "example": "import { useState } from \"react\";\nimport { Upload, type UploadFileItem, collectUploadCommitActions } from \"@godxjp/ui/data-entry\";\n\n// Example: avatar picker with server upload\nexport function AvatarUploadForm() {\n  const [items, setItems] = useState<UploadFileItem[]>([]);\n\n  async function handleUpload(file: File, _item: UploadFileItem) {\n    const fd = new FormData();\n    fd.append(\"file\", file);\n    const res = await fetch(\"/api/media/upload\", { method: \"POST\", body: fd });\n    const { mediaId, previewUrl } = await res.json();\n    return { mediaId, previewUrl };\n  }\n\n  function handleSubmit(e: React.FormEvent) {\n    e.preventDefault();\n    const { deleteMediaIds, promoteMediaIds } = collectUploadCommitActions(items);\n    // Send to your API — never send raw File objects\n    console.log({ deleteMediaIds, promoteMediaIds });\n  }\n\n  return (\n    <form onSubmit={handleSubmit}>\n      <Upload\n        variant=\"avatar-crop\"\n        value={items}\n        onValueChange={setItems}\n        onUpload={handleUpload}\n        maxSizeBytes={5 * 1024 * 1024}\n      />\n      <button type=\"submit\">Save Profile</button>\n    </form>\n  );\n}\n\n// Example: multi-file dropzone\nexport function DocumentUploadDropzone() {\n  const [items, setItems] = useState<UploadFileItem[]>([]);\n\n  return (\n    <Upload\n      variant=\"dropzone\"\n      value={items}\n      onValueChange={setItems}\n      accept=\".pdf,.xlsx\"\n      maxCount={10}\n      maxSizeBytes={20 * 1024 * 1024}\n      onUpload={async (file) => {\n        const res = await fetch(\"/api/media/upload\", {\n          method: \"POST\",\n          body: Object.assign(new FormData(), { file }),\n        });\n        return res.json();\n      }}\n    />\n  );\n}",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "Upload",
+  "props": [
+    {
+      "defaultValue": "\"dropzone\"",
+      "description": "Controls the visual rendering mode. dropzone = large dashed drop area + file list; button = compact outline button + file list; picture-card = grid of 96×96 image thumbnails; picture = single image preview with change/remove actions; avatar = circular single-image picker; avatar-crop = avatar with an in-dialog crop step before the item is staged.",
+      "name": "variant",
+      "type": "\"dropzone\" | \"button\" | \"picture-card\" | \"picture\" | \"avatar\" | \"avatar-crop\""
+    },
+    {
+      "defaultValue": "\"picture\" for variant=\"picture\", otherwise \"text\"",
+      "description": "HOW THE CHOSEN FILES ARE LISTED — antd's listType, and an axis of its own: variant decides how files are PICKED, listType decides how the picked ones are DRAWN. text = name, size and actions (the classic dropzone/button row). picture = a leading box on every row: the thumbnail when the item has a previewUrl, otherwise the glyph for its file kind (image / pdf / archive / text / generic), both boxes the same size so a mixed list keeps one row height. The glyph is decorative (aria-hidden) and carries its kind as data-file-kind for theming. antd's picture-card is variant='picture-card' here — the tile grid IS the picker there, so it is not offered as a listType.",
+      "name": "listType",
+      "type": "\"text\" | \"picture\""
+    },
+    {
+      "description": "Controlled list of file items. When provided the component is controlled — you own the state. Omit to run uncontrolled.",
+      "name": "value",
+      "type": "UploadFileItem[]"
+    },
+    {
+      "description": "Initial list of file items for uncontrolled usage. Ignored once value is provided.",
+      "name": "defaultValue",
+      "type": "UploadFileItem[]"
+    },
+    {
+      "description": "MIME / extension accept string passed to the hidden <input type=\"file\">. avatar/avatar-crop/picture/picture-card default to \"image/*\"; dropzone and button default to unrestricted.",
+      "name": "accept",
+      "type": "string"
+    },
+    {
+      "description": "Allow multi-file selection. Auto-derived: false when maxCount is 1 (or when variant is avatar/avatar-crop/picture); otherwise true.",
+      "name": "multiple",
+      "type": "boolean"
+    },
+    {
+      "description": "Hard upper bound on the number of items. avatar/avatar-crop/picture auto-default to 1. Once the limit is reached the add button is hidden (picture-card) or additions are rejected; maxCount=1 replaces the current item.",
+      "name": "maxCount",
+      "type": "number"
+    },
+    {
+      "description": "Files larger than this limit are rejected with localized feedback and onReject.",
+      "name": "maxSizeBytes",
+      "type": "number"
+    },
+    {
+      "description": "Disables all interactive surfaces (drop zone, buttons). Visual opacity + pointer-events-none applied.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Show the remove/delete control on each item. Set false to make uploads permanent within the session.",
+      "name": "removable",
+      "type": "boolean"
+    },
+    {
+      "description": "Called immediately after a file is picked (before form submit). Transitions the item to status='uploading', then 'done' on resolve or 'error' on reject. Wire this to your media-service issue/PUT/complete cycle. If omitted files stay in status='idle' and the raw File object remains in item.file.",
+      "name": "onUpload",
+      "type": "(file: File, item: UploadFileItem, context: UploadRequestContext) => Promise<UploadResult>"
+    },
+    {
+      "description": "Extra CSS class applied to the outer wrapper div.",
+      "name": "className",
+      "type": "string"
+    },
+    {
+      "description": "Custom button label for variant='button'. Falls back to the i18n 'Upload file' string.",
+      "name": "children",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "Fires with the current file list.",
+      "name": "onValueChange",
+      "type": "(items: UploadFileItemProp[]) => void"
+    },
+    {
+      "description": "`variant=\"button\"` only — size of the visible trigger, forwarded to Button. An icon size renders it icon-only and moves the label to `aria-label`: a 32px square beside other icon buttons rather than a 147px labelled one that outweighs them.",
+      "name": "triggerSize",
+      "type": "\"default\" | \"md\" | \"xs\" | \"sm\" | \"lg\" | \"icon\" | \"icon-xs\" | \"icon-sm\" | \"icon-lg\""
+    },
+    {
+      "defaultValue": "\"outline\"",
+      "description": "`variant=\"button\"` only — visual weight of the visible trigger, forwarded to Button. Default `outline` suits a standalone form field. Pass `ghost` when the trigger sits in a toolbar row beside other icon buttons — inside a chat composer, say — where a bordered square reads as the odd one out.",
+      "name": "triggerVariant",
+      "type": "\"default\" | \"destructive\" | \"outline\" | \"dashed\" | \"secondary\" | \"ghost\" | \"link\" | \"bare\""
+    },
+    {
+      "defaultValue": "the lucide upload arrow",
+      "description": "`variant=\"button\"` only — the glyph the trigger draws. Pass the COMPONENT (`triggerIcon={Plus}`), not an element, exactly as `Icon`'s `as` takes it; every lucide icon qualifies. It exists because the glyph was hard-coded and `triggerVariant` only moves emphasis, so a \"create new\" action that HAPPENS to upload could not carry a plus and had to announce itself as an upload (gh#734). The library still owns the class, the label spacing and the `aria-hidden`, so a swapped glyph renders at the same `--upload-row-icon-size` and never reaches the accessible name — the trigger's metrics cannot drift with the icon.",
+      "name": "triggerIcon",
+      "type": "React.ComponentType<React.SVGProps<SVGSVGElement> & React.RefAttributes<SVGSVGElement>>"
+    },
+    {
+      "description": "Displays existing files, blocks changes, preserves staged form data.",
+      "name": "readOnly",
+      "type": "boolean"
+    },
+    {
+      "description": "Select a folder; each item preserves relativePath.",
+      "name": "directory",
+      "type": "boolean"
+    },
+    {
+      "description": "Paste clipboard files while focus is inside this Upload; text paste is untouched.",
+      "name": "pastable",
+      "type": "boolean"
+    },
+    {
+      "description": "Defaults true. Disable native dialog activation for drop-only surfaces.",
+      "name": "openFileDialogOnClick",
+      "type": "boolean"
+    },
+    {
+      "description": "Multipart file field name; named staged files also join native FormData.",
+      "name": "name",
+      "type": "string"
+    },
+    {
+      "description": "Multipart upload URL; onUpload takes precedence.",
+      "name": "action",
+      "type": "string | ((file: File) => string | Promise<string>)"
+    },
+    {
+      "description": "Request method, default POST.",
+      "name": "method",
+      "type": "\"POST\" | \"PUT\" | \"PATCH\""
+    },
+    {
+      "description": "Request headers such as CSRF tokens; multipart boundaries remain browser-owned.",
+      "name": "headers",
+      "type": "Record<string, string>"
+    },
+    {
+      "description": "Additional multipart fields, optionally resolved per file.",
+      "name": "data",
+      "type": "Record<string, string | Blob> | ((file: File) => Record<string, string | Blob> | Promise<Record<string, string | Blob>>)"
+    },
+    {
+      "description": "Send credentials with the default transport.",
+      "name": "withCredentials",
+      "type": "boolean"
+    },
+    {
+      "description": "Validate or transform before upload; false stages manually; UPLOAD_LIST_IGNORE excludes. Rejections are reported.",
+      "name": "beforeUpload",
+      "type": "(file: File, files: File[]) => boolean | File | Blob | typeof UPLOAD_LIST_IGNORE | Promise<boolean | File | Blob | typeof UPLOAD_LIST_IGNORE>"
+    },
+    {
+      "description": "Reports accept, size, count, or preflight rejection.",
+      "name": "onReject",
+      "type": "(rejection: UploadRejection) => void"
+    },
+    {
+      "description": "Returning false or rejecting vetoes removal. Accepted removal aborts active upload.",
+      "name": "onRemove",
+      "type": "(item: UploadFileItem) => boolean | void | Promise<boolean | void>"
+    },
+    {
+      "description": "Preview action callback.",
+      "name": "onPreview",
+      "type": "(item: UploadFileItem) => void"
+    },
+    {
+      "description": "Download action callback.",
+      "name": "onDownload",
+      "type": "(item: UploadFileItem) => void"
+    },
+    {
+      "description": "Asynchronously generate a custom thumbnail.",
+      "name": "previewFile",
+      "type": "(file: File) => Promise<string>"
+    },
+    {
+      "description": "Observe drop events.",
+      "name": "onDrop",
+      "type": "React.DragEventHandler<HTMLElement>"
+    },
+    {
+      "description": "Show the default file list, default true.",
+      "name": "showUploadList",
+      "type": "boolean"
+    },
+    {
+      "description": "Customize a file row while preserving its default actions.",
+      "name": "itemRender",
+      "type": "(node: React.ReactElement, item: UploadFileItem, items: UploadFileItem[], actions: UploadItemActions) => React.ReactNode"
+    }
+  ],
+  "related": [
+    "Input (type='file') — never hand-roll a raw file input; use Upload instead. Upload provides drag-drop, preview, upload lifecycle, and soft-delete draft.",
+    "Avatar (display-only) — the godx-ui Avatar component renders a user's existing image; use Upload variant='avatar' or 'avatar-crop' when you need the user to change it.",
+    "DataTable — unrelated to Upload but both appear together in bulk-import flows: Upload (button variant) triggers the import, DataTable shows the result."
+  ],
+  "rules": [
+    3,
+    23
+  ],
+  "storyPath": "data-entry/Upload.stories.tsx",
+  "tagline": "Drag-and-drop / button / avatar / picture file uploader in six variants — wire onUpload to your media-service and call collectUploadCommitActions on form submit; supports multipart forms and custom media storage.",
+  "usage": [
+    "DO provide onUpload to auto-upload on pick. The callback must return { mediaId, previewUrl? } — the component transitions item.status through uploading → done/error automatically. Without onUpload the File object sits in item.file until you manually process it.",
+    "DO call collectUploadCommitActions(items) on form submit to get { deleteMediaIds, promoteMediaIds } for your media-service. For multipart endpoints submit File objects via FormData; never submit blob URLs as persisted media.",
+    "DO use createUploadItem(file) to build UploadFileItem objects when pre-populating value from server data (e.g. edit forms). Set status='done' and mediaId on existing server media so the draft/undo machinery tracks them correctly.",
+    "For native multipart or Inertia Form submissions, set name: staged local files are appended during the formdata event. Completed media uploads use collectUploadCommitActions instead.",
+    "Avatar/picture variants (maxCount=1) use internal soft-delete draft logic: removing an item marks it pendingDelete so the user can undo before committing. On form submit, collectUploadCommitActions converts pendingDelete → deleteMediaIds and done mediaIds → promoteMediaIds.",
+    "For avatar-crop: a crop dialog opens after pick. The cropped Blob is staged as a new UploadFileItem. The original file never enters the list — only the cropped version is passed to onUpload.",
+    "For a drawer or panel listing MIXED attachments (.png beside .json and .txt), keep variant='dropzone' and set listType='picture': the image rows draw their previewUrl as a thumbnail and every other row draws the glyph for its kind, on one row height. Do NOT switch to variant='picture' to get thumbnails — that variant also changes the picker, the default accept to image/* and maxCount to 1."
+  ],
+  "useCases": [
+    "Profile / user avatar editor: use variant='avatar-crop' so users can crop the image before upload; wire onUpload to your media-service; call collectUploadCommitActions on profile form submit to promote or delete.",
+    "Invoice / document attachment list: use variant='dropzone' with accept='.pdf,.xlsx' and maxSizeBytes to let accountants drag-drop supporting documents; show the file list with status indicators below the drop zone.",
+    "Product gallery (multiple images): use variant='picture-card' with maxCount to display a grid of thumbnails; each item gets an individual remove ✕ button; collectUploadCommitActions on product save.",
+    "Single cover-image picker on a content form: use variant='picture' with maxCount=1 to show a preview rectangle with change/remove controls and undo-delete support.",
+    "CSV / bulk-import button in an admin table header: use variant='button' with accept='.csv' and custom children label ('Import CSV') to keep the UI compact; process item.file in the onChange handler.",
+    "Inline document replacement on an accounting record (replace, not append): use variant='avatar' (single-slot logic) or picture; onUpload returns the new mediaId; collectUploadCommitActions delivers replacesMediaId → deleteMediaIds."
+  ]
+}

package/agent/components/UploadCropDialog.json

@@ -0,0 +1,60 @@
+{
+  "example": "{`import { useState } from \"react\";\nimport { UploadCropDialog } from \"@godxjp/ui/upload\"; // internal — prefer Upload variant=\"avatar-crop\" instead\n\nexport function AvatarField() {\n  const [cropFile, setCropFile] = useState<File | null>(null);\n\n  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {\n    const file = e.target.files?.[0] ?? null;\n    setCropFile(file);\n    e.target.value = \"\"; // reset so re-selecting same file fires onChange\n  };\n\n  const handleConfirm = (cropped: File) => {\n    // cropped is always image/jpeg 256×256\n    const form = new FormData();\n    form.append(\"avatar\", cropped);\n    fetch(\"/api/avatar\", { method: \"POST\", body: form });\n  };\n\n  return (\n    <>\n      <input type=\"file\" accept=\"image/*\" onValueChange={handleFileChange} />\n      <UploadCropDialog\n        open={cropFile !== null}\n        onOpenChange={(open) => { if (!open) setCropFile(null); }}\n        file={cropFile}\n        onConfirm={handleConfirm}\n      />\n    </>\n  );\n}`}",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "UploadCropDialog",
+  "props": [
+    {
+      "description": "Controls dialog visibility. Drive this with useState; the component never auto-opens.",
+      "name": "open",
+      "required": true,
+      "type": "boolean"
+    },
+    {
+      "description": "Called when the dialog requests close (Cancel button or overlay click). Set your open state to false here.",
+      "name": "onOpenChange",
+      "required": true,
+      "type": "(open: boolean) => void"
+    },
+    {
+      "description": "The raw File object to crop. An object URL is created internally and revoked on cleanup. Pass null when no file is selected (dialog renders empty).",
+      "name": "file",
+      "required": true,
+      "type": "File | null"
+    },
+    {
+      "description": "Called with the cropped result — always a JPEG File (256x256, quality 0.92) regardless of the original format. The dialog closes itself after calling this.",
+      "name": "onConfirm",
+      "required": true,
+      "type": "(cropped: File) => void"
+    }
+  ],
+  "related": [
+    "Upload (variant='avatar-crop') — the preferred way to get crop-on-upload for avatars; it wraps UploadCropDialog automatically. Use UploadCropDialog directly only when you need a custom file-picking trigger or a non-avatar crop flow.",
+    "Upload (variant='avatar') — same circular avatar UI without the crop step; the file is used as-is.",
+    "Upload (variant='picture') — rectangular single-image upload without crop; no dialog.",
+    "Upload (variant='picture-card') — multi-image grid upload without crop."
+  ],
+  "rules": [
+    3,
+    13,
+    23
+  ],
+  "storyPath": "data-entry/UploadCropDialog.stories.tsx",
+  "tagline": "Modal crop dialog for a single image file — always controlled (open + file + onConfirm required); do NOT use standalone when Upload variant=\"avatar-crop\" already embeds it.",
+  "usage": [
+    "DO pass a File object selected by the user (e.g. from an <input type='file'> or drag-drop handler) to `file`; the dialog creates and revokes its own object URL — never create one yourself before passing.",
+    "DO close the dialog in onOpenChange: `onOpenChange={(open) => !open && setCropFile(null)}` — always clear cropFile state on close to avoid a stale image on the next open.",
+    "DO handle the cropped File in onConfirm and then upload or store it; the output is always image/jpeg 256×256 named `<originalName>.jpg`.",
+    "DON'T use UploadCropDialog directly if you are already using `<Upload variant='avatar-crop'>` — that variant already embeds UploadCropDialog internally. Using both will double-mount the dialog.",
+    "DON'T try to control the zoom slider from outside — scale state is fully internal; the user controls zoom in-dialog via a Slider (1–2.5×, step 0.05).",
+    "DON'T submit the dialog's output File as a form field directly; pass it to your upload handler (e.g. onUpload prop on Upload, or a manual FormData POST), since File objects cannot survive a standard HTML form serialisation."
+  ],
+  "useCases": [
+    "Avatar / profile photo upload flow: show a file picker, pass the chosen File to UploadCropDialog, upload the cropped 256×256 JPEG to the server on confirm.",
+    "Admin user management: let admins set or replace a team member's avatar with consistent square crop instead of accepting arbitrary-shaped originals.",
+    "Legal-entity logo upload in an accounting app: enforce a square, web-ready JPEG from any source image before storing it as the entity's icon.",
+    "Any single-image form field that needs browser-side crop before upload — avoids a round-trip to a server-side image processor.",
+    "Building a custom avatar picker UI on top of the godx-ui Upload primitives when the built-in variant='avatar-crop' does not fit your layout."
+  ]
+}