@godxjp/ui 28.9.0 → 28.10.0

package/agent/components/VisuallyHidden.json

@@ -0,0 +1,20 @@
+{
+  "docPath": "docs/general/typography.tsx",
+  "example": "<VisuallyHidden>Unread</VisuallyHidden>",
+  "group": "general",
+  "importPath": "@godxjp/ui/general",
+  "name": "VisuallyHidden",
+  "props": [
+    {
+      "description": "Text available to assistive technology.",
+      "name": "children",
+      "type": "ReactNode"
+    }
+  ],
+  "rules": [],
+  "storyPath": "general/typography.tsx",
+  "tagline": "Accessible supporting text without a visible layout box.",
+  "usage": [
+    "Use for supplementary accessible labels. Do not hide controls that remain focusable."
+  ]
+}

package/agent/components/Welcome.json

@@ -0,0 +1,65 @@
+{
+  "docPath": "data-display/welcome.tsx",
+  "example": "import { Welcome } from \"@godxjp/ui/data-display\";\nimport { Button } from \"@godxjp/ui/general\";\nimport { Bot } from \"lucide-react\";\n\n<Welcome\n  icon={<Bot />}\n  title=\"こんにちは\"\n  description=\"請求、経費、勤怠のことならお手伝いできます。\"\n  extra={<Button variant=\"ghost\" size=\"sm\">閉じる</Button>}\n/>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "Welcome",
+  "props": [
+    {
+      "description": "Leading glyph. A STRING beginning with http(s) is rendered as a decorative <img alt=\"\"> (Ant Design X does the same, with alt=\"icon\"); any other string renders as text.",
+      "name": "icon",
+      "type": "React.ReactNode | string"
+    },
+    {
+      "description": "The greeting. Renders as an <h4>, which is Ant Design X's hardcoded Typography.Title level={4}.",
+      "name": "title",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "The line under the greeting.",
+      "name": "description",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "Trailing slot on the TITLE row — a dismiss button, a model picker. Not under the description.",
+      "name": "extra",
+      "type": "React.ReactNode"
+    },
+    {
+      "defaultValue": "\"filled\"",
+      "description": "filled gives the block its own tinted ground and hairline; borderless lets it sit on the page.",
+      "name": "variant",
+      "type": "\"filled\" | \"borderless\""
+    },
+    {
+      "description": "DOM id of the block.",
+      "name": "id",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "EmptyState — the general 'nothing here yet' block for a list or a table. Welcome is the chat surface's greeting and carries an icon/title/description/extra shape of its own.",
+    "PageContainer — owns the PAGE header; Welcome sits inside the page body.",
+    "ChatSuggestion / ChatBubbleList — the rest of the same surface."
+  ],
+  "rules": [
+    2,
+    6,
+    44,
+    45
+  ],
+  "storyPath": "data-display/Welcome.stories.tsx",
+  "tagline": "The greeting block at the head of an empty conversation (Ant Design X Welcome): glyph, greeting, one line under it, and a trailing slot ON THE TITLE ROW — which is the placement a hand-roll gets wrong.",
+  "usage": [
+    "DO put it above the composer on an empty chat, with ChatSuggestion or a Prompts row beneath it — that is the surface it belongs to.",
+    "DO pass `extra` for the one action the greeting carries (dismiss, switch model). It lands beside the title, top-aligned, so a two-line title does not float it.",
+    "DON'T reach for it as a generic page header — that is PageContainer's title/subtitle/extra, which owns the page rhythm.",
+    "DON'T expect a heading-level prop: Ant Design X hardcodes level 4 and this ports that. Wrap it in your own heading hierarchy if the page needs a different rung.",
+    "DON'T expect `styles`/`classNames` from Ant Design X — retune through the --welcome-* tokens."
+  ],
+  "useCases": [
+    "The first screen of an assistant, before the first message.",
+    "The head of a fresh conversation started from the Conversations rail.",
+    "A feature introduction card inside a chat surface, dismissed through `extra`."
+  ]
+}

package/agent/components/formatDate.json

@@ -0,0 +1,46 @@
+{
+  "example": "import { formatDate } from \"@godxjp/ui/datetime\";\n\nformatDate(coupon.validFrom);                       // \"2026-05-01\"\nformatDate(order.createdAt, { kind: \"relative\" });  // \"3日前\"",
+  "group": "providers",
+  "importPath": "@godxjp/ui/app",
+  "name": "formatDate",
+  "props": [
+    {
+      "description": "ISO date, ISO datetime, HH:mm, or Date.",
+      "name": "value",
+      "required": true,
+      "type": "string | Date | null | undefined"
+    },
+    {
+      "defaultValue": "\"auto\"",
+      "description": "Output preset; auto infers from the value.",
+      "name": "options.kind",
+      "type": "\"auto\" | \"date\" | \"datetime\" | \"time\" | \"long\" | \"relative\""
+    }
+  ],
+  "related": [
+    "AppProvider — required peer that seeds locale, timezone, dateFormat, and timeFormat into the module-level context that `formatDate` reads. Must be mounted once at app root; omitting it means `formatDate` silently falls back to Vietnamese/Ho Chi Minh City defaults.",
+    "DatePicker — the corresponding input control for calendar dates. Use `DatePicker` to capture a date from the user; use `formatDate(value, { calendar: true })` to display the picked `Date` object back as a string.",
+    "DateFormatPicker / TimeFormatPicker / TimezonePicker — preference pickers that update AppProvider context; their selections are automatically picked up by subsequent `formatDate` calls with no extra wiring needed.",
+    "TimePicker — the corresponding input control for HH:mm time values. Use `TimePicker` to capture time; use `formatDate(hhmm)` (auto-detects `'time'` kind) to display the stored `HH:mm` string respecting the user's 12h/24h preference."
+  ],
+  "rules": [
+    5
+  ],
+  "storyPath": "app/formatDate.stories.tsx",
+  "tagline": "MANDATORY for all date/time display. Auto-detects ISO date / HH:mm / instant; reads AppProvider context. Import from @godxjp/ui/datetime.",
+  "usage": [
+    "DO import from `@godxjp/ui/datetime` — NOT from `date-fns` or any other datetime utility. `formatDate` is the single mandatory display entry point; calling `date-fns/format` directly bypasses AppProvider locale/timezone/dateFormat/timeFormat context and produces inconsistent output across the app.",
+    "DO ensure `AppProvider` is mounted at the app root before the first `formatDate` call. The function reads a module-level context synced by `AppProvider` via `syncDatetimeContext`. Without it the fallback locale is `'vi'` / timezone `'Asia/Ho_Chi_Minh'` / `'24h'`, which will silently produce wrong output in Japanese or English apps.",
+    "DO pass `null` or `undefined` safely — `formatDate` returns an em-dash `'—'` for null/undefined/empty string values. Never guard with a ternary before calling it.",
+    "DO use `options.kind` when auto-detection is wrong: pass `kind: 'date'` for an ISO datetime string you want displayed as date-only, `kind: 'relative'` for age display (e.g. `'3日前'`), `kind: 'long'` for full PPP format in modals/detail panels. Auto-detection maps plain `yyyy-MM-dd` → `'date'`, `HH:mm` → `'time'`, everything else → `'datetime'`.",
+    "DO pass `{ calendar: true }` when the `Date` object came from a react-day-picker calendar pick — this prevents timezone shift that would occur if the Date were treated as a UTC instant.",
+    "DON'T hand-roll per-call locale/timezone resolution with `Intl.DateTimeFormat` or raw `date-fns/format`. The `options.locale` / `options.timezone` overrides exist for one-off per-cell display differences (e.g. showing a partner's local time), not as a substitute for AppProvider context."
+  ],
+  "useCases": [
+    "Rendering all date/time columns in a DataTable — invoice due dates (`kind: 'date'`), transaction timestamps (`kind: 'datetime'`), and elapsed time since last sync (`kind: 'relative'`) all go through `formatDate` so the locale/timezone/12h-24h setting from AppProvider is respected everywhere.",
+    "Displaying a single date/time field in a Descriptions or Card detail panel, e.g. `formatDate(invoice.issuedAt)` for the issued-at row — no extra formatting logic needed, null is handled as `'—'` automatically.",
+    "Formatting a stored `HH:mm` string (24h canonical storage) for display according to the user's timeFormat preference — pass the raw `'14:30'` string and auto-detection routes it through `formatTimeOfDay`, outputting `'2:30 PM'` or `'14:30'` based on context.",
+    "Rendering a 'last modified' timestamp with relative wording in an activity feed or audit log row — `formatDate(entry.updatedAt, { kind: 'relative' })` produces locale-correct relative strings like `'3日前'` / `'3 days ago'`.",
+    "Converting a `Date` selected from `DatePicker` (react-day-picker) back to a display string — pass `{ calendar: true }` to avoid the UTC midnight shift that the default instant path would apply."
+  ]
+}

package/agent/components/inertiaUpload.json

@@ -0,0 +1,32 @@
+{
+  "docPath": "FORMS.md",
+  "example": "import { inertiaUpload } from \"@godxjp/ui/inertia\";\nconst upload = inertiaUpload((file, callbacks) => router.post(endpoint, { file }, callbacks), t(\"Upload failed\"));\n<Upload onUpload={upload} />;",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/inertia",
+  "name": "inertiaUpload",
+  "props": [
+    {
+      "description": "Start a router.post visit with the supplied callbacks and file.",
+      "name": "send",
+      "type": "(file: File, callbacks: InertiaUploadCallbacks) => void"
+    },
+    {
+      "description": "Localized fallback for network or HTTP failures.",
+      "name": "errorMessage",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "Upload",
+    "FormRoot"
+  ],
+  "rules": [
+    1
+  ],
+  "storyPath": "data-entry/Upload.stories.tsx",
+  "tagline": "Bridge Inertia multipart visits to Upload progress, cancellation, retry and error recovery.",
+  "usage": [
+    "Pass the returned callback to Upload.onUpload. Spread callbacks into router.post options; they enable multipart and independent async requests.",
+    "Keep failed items in controlled value so the user can retry; remove only done items when server props provide the saved list."
+  ]
+}

package/agent/components/useZodForm.json

@@ -0,0 +1,39 @@
+{
+  "docPath": "docs/FORMS.md",
+  "example": "import { useZodForm } from \"@godxjp/ui/form\";\nimport { z } from \"zod\";\nconst form = useZodForm(z.object({email: z.string().email()}), {defaultValues: {email: \"\"}, mode: \"onBlur\"});",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/form",
+  "name": "useZodForm",
+  "props": [
+    {
+      "description": "Zod schema, including async refinements.",
+      "name": "schema",
+      "type": "z.ZodType<T>"
+    },
+    {
+      "description": "RHF options such as defaultValues, mode, reValidateMode, criteriaMode and shouldUnregister.",
+      "name": "options",
+      "type": "UseZodFormOptionsProp<T>"
+    }
+  ],
+  "related": [
+    "Form",
+    "FormField",
+    "FormRoot",
+    "FormFieldControl"
+  ],
+  "rules": [
+    23,
+    31
+  ],
+  "storyPath": "data-entry/Form.stories.tsx",
+  "tagline": "Create a typed React Hook Form instance with Zod validation; reuse reset, setValue, trigger, formState and field errors.",
+  "usage": [
+    "Use inside the documented form composition; do not nest native form elements.",
+    "Use godx-ui controls and preserve field names, errors and disabled state."
+  ],
+  "useCases": [
+    "Validated settings forms",
+    "Nested repeating data entry"
+  ]
+}