@godxjp/ui 19.0.0 → 19.2.0

package/docs/data-entry/form-field/examples/create-form.tsx

@@ -0,0 +1,105 @@
+import { useState } from "react";
+
+import { Field, FormField, Input, Select, Switch, Textarea } from "@godxjp/ui/data-entry";
+import { Button } from "@godxjp/ui/general";
+import { Avatar, AvatarFallback } from "@godxjp/ui/data-display";
+import {
+  AppShell,
+  Flex,
+  PageContainer,
+  Sidebar,
+  type SidebarSectionProp,
+  Topbar,
+} from "@godxjp/ui/layout";
+import { BookOpen, FileText, LayoutDashboard, ReceiptText, Users } from "lucide-react";
+
+/**
+ * Create form — a real screen: FormField wraps each stacked control (Input /
+ * Select / Textarea), Field pairs the Switch with its label, and the page's
+ * footer holds the primary submit + outline cancel. The canonical data-entry
+ * page, composed only from real @godxjp/ui components.
+ */
+const sections: SidebarSectionProp[] = [
+  {
+    label: "会計",
+    items: [
+      { id: "dashboard", label: "ダッシュボード", icon: LayoutDashboard },
+      { id: "journal", label: "仕訳", icon: FileText },
+      { id: "invoices", label: "請求書", icon: ReceiptText },
+      { id: "partners", label: "取引先", icon: BookOpen },
+    ],
+  },
+  { label: "管理", items: [{ id: "users", label: "ユーザー", icon: Users }] },
+];
+
+export default function Demo() {
+  const [type, setType] = useState("corp");
+
+  return (
+    <AppShell
+      sidebar={
+        <Sidebar
+          activeId="partners"
+          sections={sections}
+          onSelect={() => {}}
+          product={{ name: "CoreBooks", role: "管理コンソール", color: "hsl(var(--primary))" }}
+        />
+      }
+      topbar={
+        <Topbar
+          start={
+            <Avatar className="rounded-md">
+              <AvatarFallback className="bg-primary text-primary-foreground font-bold">
+                C
+              </AvatarFallback>
+            </Avatar>
+          }
+        />
+      }
+    >
+      <PageContainer
+        title="取引先を作成"
+        breadcrumb={[{ label: "取引先", to: "#" }, { label: "新規" }]}
+        footer={
+          <Flex direction="row" wrap gap="sm" justify="end">
+            <Button variant="outline" type="button">
+              キャンセル
+            </Button>
+            <Button type="submit">作成</Button>
+          </Flex>
+        }
+      >
+        <Flex direction="col" gap="md" className="max-w-2xl">
+          <FormField id="cf-name" label="取引先名" required helper="最大50文字">
+            <Input id="cf-name" placeholder="株式会社ベトヤ" />
+          </FormField>
+          <FormField id="cf-code" label="取引先コード" required helper="一意のコードを入力">
+            <Input id="cf-code" placeholder="BTY-0012" />
+          </FormField>
+          <FormField id="cf-type" label="区分">
+            <Select
+              id="cf-type"
+              name="type"
+              value={type}
+              onValueChange={setType}
+              options={[
+                { value: "corp", label: "法人" },
+                { value: "indiv", label: "個人事業主" },
+              ]}
+            />
+          </FormField>
+          <FormField id="cf-memo" label="メモ" helper="任意">
+            <Textarea id="cf-memo" placeholder="例: 4月分から取引開始" />
+          </FormField>
+          <Field
+            id="cf-active"
+            label="取引を有効にする"
+            description="無効にすると新規取引を登録できません"
+          >
+            <Switch id="cf-active" defaultChecked />
+          </Field>
+        </Flex>
+      </PageContainer>
+    </AppShell>
+  );
+}

package/docs/data-entry/form-field/index.md

@@ -0,0 +1,8 @@
+---
+title: Overview
+---
+
+The labelled-field wrapper for every stacked control — it renders the label, a required
+asterisk, a helper hint or a role="alert" error, and wires `aria-describedby` /
+`aria-invalid` onto the single child control. Use `Field` instead for a checkbox/switch
+beside its label. See Examples for a full create form.

package/docs/data-entry/form-field/index.tsx

@@ -0,0 +1,326 @@
+import { useState } from "react";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
+import { Checkbox, Form, FormField, Input, Select } from "@godxjp/ui/data-entry";
+import {
+  Dialog,
+  DialogBody,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  Sheet,
+  SheetContent,
+  SheetHeader,
+  SheetTitle,
+} from "@godxjp/ui/feedback";
+import { Button } from "@godxjp/ui/general";
+import { Flex, PageContainer } from "@godxjp/ui/layout";
+
+/**
+ * FormField — wraps one control with a label, helper, and error, and wires
+ * aria-describedby / aria-invalid onto the child. Use it for every stacked
+ * labelled control (Input/Textarea/Select/DatePicker…); use Field for a
+ * checkbox/switch beside its label. Composed only from real @godxjp/ui components.
+ */
+export default function Demo() {
+  const [dialogOpen, setDialogOpen] = useState(false);
+  const [sheetOpen, setSheetOpen] = useState(false);
+  return (
+    <PageContainer
+      title="FormField"
+      subtitle="Label · helper · required · error · a11y wired for the control"
+    >
+      <Flex direction="col" gap="lg">
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>States</CardTitle>
+            <CardDescription>
+              required adds a red asterisk; helper is a muted hint; error (role=alert) overrides it.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <FormField id="ff-name" label="取引先名" required helper="最大50文字">
+                <Input id="ff-name" placeholder="株式会社..." />
+              </FormField>
+              <FormField
+                id="ff-email"
+                label="メール"
+                error="メールアドレスの形式が正しくありません"
+              >
+                <Input id="ff-email" type="email" defaultValue="invalid@" />
+              </FormField>
+              <FormField id="ff-status" label="状態" helper="未選択の場合は下書きになります">
+                <Select
+                  id="ff-status"
+                  name="status"
+                  value="paid"
+                  onValueChange={() => {}}
+                  options={[
+                    { value: "draft", label: "下書き" },
+                    { value: "paid", label: "入金済" },
+                  ]}
+                />
+              </FormField>
+              <FormField
+                id="ff-required-status"
+                label="承認状態"
+                required
+                helper="承認ワークフローで使用します"
+                error="承認状態を選択してください"
+              >
+                <Select
+                  id="ff-required-status"
+                  name="approval_status"
+                  value=""
+                  onValueChange={() => {}}
+                  placeholder="状態を選択"
+                  options={[
+                    { value: "pending", label: "承認待ち" },
+                    { value: "approved", label: "承認済み" },
+                  ]}
+                />
+              </FormField>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Complete field contract</CardTitle>
+            <CardDescription>
+              Auto id, label addon, every layout, per-field widths, className and grid span are
+              rendered explicitly.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Form columns={2}>
+              <FormField
+                label="自動ID"
+                helper="id を省略すると control に生成IDを注入"
+                labelAddon={<Button aria-label="自動IDの説明">?</Button>}
+                className="contract-auto-id"
+              >
+                <Input defaultValue="自動関連付け" />
+              </FormField>
+              <FormField
+                id="contract-horizontal"
+                label="Horizontal"
+                layout="horizontal"
+                labelWidth="8rem"
+                controlWidth="16rem"
+                required={false}
+              >
+                <Input defaultValue="有効" />
+              </FormField>
+              <FormField id="contract-vertical" label="Vertical" layout="vertical" required>
+                <Input aria-invalid defaultValue="不正な値" />
+              </FormField>
+              <FormField
+                id="contract-inline"
+                label="Inline"
+                layout="inline"
+                error="入力内容を確認してください"
+                colSpan={2}
+              >
+                <Input defaultValue="invalid@example" />
+              </FormField>
+            </Form>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Field identity · data-field (gh#337)</CardTitle>
+            <CardDescription>
+              項目キーを control の data-field に出す。既定は id から導出。id が DOM
+              一意化のためのもので項目キーと違う場合だけ field を明示する。AppProvider
+              emitFieldNames を立てたアプリでは同じキーが name にも出る。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Form columns={2}>
+              <FormField id="project_name" label="案件名" helper="data-field は id から導出">
+                <Input defaultValue="ABC商事 更新案件" />
+              </FormField>
+              <FormField
+                id="source_slip_field"
+                field="source_slip_id"
+                label="ソース伝票番号"
+                helper="id は枠の一意化用。項目キーは field で明示"
+              >
+                <Input defaultValue="2024-00871" />
+              </FormField>
+              <FormField
+                id="fax_field"
+                label="FAX"
+                helper="ラッパー越しでも各控えが自分の id で名乗る"
+              >
+                <Flex gap="sm" align="center">
+                  <Input id="fax" defaultValue="03-1234-5678" />
+                  <Checkbox id="fax_unknown" aria-label="不明" />
+                </Flex>
+              </FormField>
+              <FormField id="branch_cd" label="拠点" helper="trigger は data-value に選択コード">
+                <Select
+                  options={[
+                    { value: "52", label: "東京本社" },
+                    { value: "53", label: "大阪支社" },
+                  ]}
+                  value="52"
+                  onValueChange={() => undefined}
+                />
+              </FormField>
+            </Form>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Static value · mixed with editable fields (gh#294)</CardTitle>
+            <CardDescription>
+              staticText renders a read-only VALUE as a FormField itself: Descriptions.Item's exact
+              value typography, no control, no id/aria-* wiring. An immutable name/email row and an
+              editable role Select then share the same Form context · label column · labelAlign ·
+              row-to-row gap, with nothing to reconcile by hand.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Form layout="horizontal" labelWidth="8rem" controlWidth="20rem">
+              <FormField label="名前" staticText="山田 太郎" />
+              <FormField label="メールアドレス" staticText="yamada@example.jp" />
+              <FormField id="static-role" label="ロール" required>
+                <Select
+                  id="static-role"
+                  name="role"
+                  value="member"
+                  onValueChange={() => {}}
+                  options={[
+                    { value: "member", label: "Member" },
+                    { value: "admin", label: "Admin" },
+                  ]}
+                />
+              </FormField>
+            </Form>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>
+              Layout matrix · widths / breakpoints / long locale / RTL
+            </CardTitle>
+            <CardDescription>
+              horizontal は md 未満で vertical に collapse。field 単位の width override と 320px
+              相当の長文を同時確認する。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <div className="max-w-3xl">
+              <Form layout="horizontal" labelWidth="12rem" controlWidth="28rem">
+                <FormField
+                  id="matrix-ja"
+                  label="請求書の送付先メールアドレス"
+                  required
+                  helper="確認メールを送信します"
+                >
+                  <Input id="matrix-ja" defaultValue="billing@example.jp" />
+                </FormField>
+                <FormField
+                  id="matrix-vi"
+                  label="Địa chỉ email nhận hóa đơn và thông báo"
+                  controlWidth="20rem"
+                >
+                  <Input id="matrix-vi" defaultValue="ketoan@example.vn" />
+                </FormField>
+              </Form>
+            </div>
+            <div className="mt-6 max-w-80 border p-3" dir="rtl" lang="ar">
+              <FormField
+                id="matrix-rtl"
+                label="البريد الإلكتروني لاستلام الفاتورة"
+                helper="سيتم إرسال رسالة تأكيد"
+              >
+                <Input id="matrix-rtl" type="email" placeholder="name@example.com" />
+              </FormField>
+            </div>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>State contract · supported and untested gaps</CardTitle>
+            <CardDescription>
+              FormField supports helper, required and error. warning, pending, touched/submitted
+              timing, server-error mapping and form-summary focus are not FormField props; those
+              remain UNTESTED and belong to the form controller/application flow.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <FormField id="state-readonly" label="作成者" helper="システム管理項目">
+                <Input id="state-readonly" readOnly defaultValue="山田 太郎" />
+              </FormField>
+              <FormField id="state-disabled" label="契約番号">
+                <Input id="state-disabled" disabled defaultValue="CTR-2026-0042" />
+              </FormField>
+              <FormField
+                id="state-server"
+                label="組織名"
+                error="保存できませんでした。しばらくしてから再試行してください。"
+              >
+                <Input id="state-server" defaultValue="株式会社アクメ" />
+              </FormField>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Composition · Dialog / Sheet</CardTitle>
+            <CardDescription>同じ bounded form を overlay 内で確認する。</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex gap="sm" wrap>
+              <Button onClick={() => setDialogOpen(true)}>Dialog form</Button>
+              <Button variant="outline" onClick={() => setSheetOpen(true)}>
+                Sheet form
+              </Button>
+            </Flex>
+            <Dialog open={dialogOpen} onOpenChange={setDialogOpen}>
+              <DialogContent className="max-w-lg">
+                <DialogHeader>
+                  <DialogTitle>取引先を追加</DialogTitle>
+                </DialogHeader>
+                <DialogBody>
+                  <Form>
+                    <FormField id="dialog-name" label="取引先名" required>
+                      <Input id="dialog-name" />
+                    </FormField>
+                    <FormField id="dialog-email" label="メール" helper="任意">
+                      <Input id="dialog-email" type="email" />
+                    </FormField>
+                  </Form>
+                </DialogBody>
+              </DialogContent>
+            </Dialog>
+            <Sheet open={sheetOpen} onOpenChange={setSheetOpen}>
+              <SheetContent>
+                <SheetHeader>
+                  <SheetTitle>請求先設定</SheetTitle>
+                </SheetHeader>
+                <Form className="mt-4">
+                  <FormField id="sheet-name" label="宛名" required>
+                    <Input id="sheet-name" />
+                  </FormField>
+                  <FormField id="sheet-note" label="備考">
+                    <Input id="sheet-note" />
+                  </FormField>
+                </Form>
+              </SheetContent>
+            </Sheet>
+          </CardContent>
+        </Card>
+      </Flex>
+    </PageContainer>
+  );
+}

package/docs/data-entry/form-inertia.tsx

@@ -0,0 +1,80 @@
+import { useState } from "react";
+import { Input } from "@godxjp/ui/data-entry";
+import { Button } from "@godxjp/ui/general";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
+import { PageContainer } from "@godxjp/ui/layout";
+import { FormFieldControl, FormRoot, useFormSubmitting } from "@godxjp/ui/form";
+import { inertiaAdapter } from "@godxjp/ui/inertia";
+
+// Stand-in for Inertia's useForm() — the real hook from @inertiajs/react has this exact shape, so a
+// page passes it straight to inertiaAdapter (the library never imports @inertiajs). Here a tiny local
+// mock drives the demo: server-style state + errors + processing, no react-hook-form.
+function useMockInertiaForm(initial: Record<string, string>) {
+  const [data, setData] = useState(initial);
+  const [errors, setErrors] = useState<Record<string, string>>({});
+  const [processing, setProcessing] = useState(false);
+  return {
+    data,
+    errors,
+    processing,
+    setData: (key: string, value: unknown) => {
+      setData((d) => ({ ...d, [key]: String(value) }));
+      setErrors((e) => ({ ...e, [key]: "" })); // clear the field error on edit (Inertia behaviour)
+    },
+    post: () => {
+      setProcessing(true);
+      window.setTimeout(() => {
+        setProcessing(false);
+        // Simulate a Laravel FormRequest validation error landing in form.errors.
+        setErrors({ email: "このメールアドレスは登録されていません。" });
+      }, 600);
+    },
+  };
+}
+
+// The submit button reads processing via useFormSubmitting() — app code, not a library component.
+function SubmitButton() {
+  return (
+    <Button type="submit" loading={useFormSubmitting()}>
+      サインイン
+    </Button>
+  );
+}
+
+/**
+ * FormRoot with an Inertia adapter — server-driven form binding. inertiaAdapter(form) lets Inertia's
+ * useForm drive FormFieldControl with the SAME auto-binding as the react-hook-form path: no manual
+ * value/onChange/error/aria-invalid per field; server errors surface on the right field and clear on
+ * edit; processing flows to the submit button via useFormSubmitting(). Composed of real @godxjp/ui.
+ */
+export default function Demo() {
+  const form = useMockInertiaForm({ email: "", password: "" });
+
+  return (
+    <PageContainer
+      title="FormRoot with Inertia"
+      subtitle="Server-driven form binding via inertiaAdapter · no per-field wiring"
+    >
+      <Card className="max-w-xl">
+        <CardHeader>
+          <CardTitle level={2}>サインイン</CardTitle>
+          <CardDescription>
+            Inertia の useForm を inertiaAdapter でラップし、FormRoot に渡すだけ。value / onChange /
+            error / aria は name から自動でバインドされる。
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <FormRoot adapter={inertiaAdapter(form)} onSubmit={() => form.post()}>
+            <FormFieldControl name="email" label="メールアドレス" required>
+              {(field) => <Input {...field} type="email" value={String(field.value ?? "")} />}
+            </FormFieldControl>
+            <FormFieldControl name="password" label="パスワード" required>
+              {(field) => <Input {...field} type="password" value={String(field.value ?? "")} />}
+            </FormFieldControl>
+            <SubmitButton />
+          </FormRoot>
+        </CardContent>
+      </Card>
+    </PageContainer>
+  );
+}

package/docs/data-entry/form-root.tsx

@@ -0,0 +1,102 @@
+import { useState } from "react";
+import { z } from "zod";
+import { Alert, AlertDescription } from "@godxjp/ui/feedback";
+import { Input } from "@godxjp/ui/data-entry";
+import { Button } from "@godxjp/ui/general";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
+import { Flex, PageContainer } from "@godxjp/ui/layout";
+import { FormFieldControl, FormRoot, useZodForm } from "@godxjp/ui/form";
+
+const schema = z.object({
+  name: z.string().min(1, "組織名を入力してください"),
+  email: z.string().email("有効なメールアドレスを入力してください"),
+});
+
+export default function Demo() {
+  const [status, setStatus] = useState<"idle" | "pending" | "success" | "server-error">("idle");
+  const form = useZodForm(schema, {
+    defaultValues: { name: "株式会社アクメ", email: "billing@example.jp" },
+  });
+
+  async function submit() {
+    setStatus("pending");
+    await new Promise((resolve) => window.setTimeout(resolve, 500));
+    setStatus("success");
+  }
+
+  return (
+    <PageContainer
+      title="FormRoot"
+      subtitle="Zod + React Hook Form · validation timing / reset / pending / summary"
+    >
+      <Card className="max-w-2xl">
+        <CardHeader>
+          <CardTitle level={2}>送付先設定</CardTitle>
+          <CardDescription>
+            Submit 後に field error を表示し、最初の invalid field へ focus。reset は defaultValues
+            を復元する。server error summary は application が管理する。
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <FormRoot form={form} onSubmit={submit}>
+            {status === "server-error" && (
+              <Alert tone="destructive">
+                <AlertDescription>
+                  保存できませんでした。接続を確認して再試行してください。
+                </AlertDescription>
+              </Alert>
+            )}
+            {status === "success" && (
+              <Alert tone="success">
+                <AlertDescription>保存しました。</AlertDescription>
+              </Alert>
+            )}
+            <FormFieldControl name="name" label="組織名" required helper="請求書に表示します">
+              {(field) => (
+                <Input
+                  {...field}
+                  disabled={status === "pending"}
+                  value={String(field.value ?? "")}
+                />
+              )}
+            </FormFieldControl>
+            <FormFieldControl name="email" label="送付先メール" required>
+              {(field) => (
+                <Input
+                  {...field}
+                  type="email"
+                  disabled={status === "pending"}
+                  value={String(field.value ?? "")}
+                />
+              )}
+            </FormFieldControl>
+            <Flex gap="sm" wrap>
+              <Button type="submit" loading={status === "pending"}>
+                保存
+              </Button>
+              <Button
+                type="button"
+                variant="outline"
+                disabled={status === "pending"}
+                onClick={() => {
+                  form.reset();
+                  setStatus("idle");
+                }}
+              >
+                リセット
+              </Button>
+              <Button type="button" variant="ghost" onClick={() => setStatus("server-error")}>
+                Server error を表示
+              </Button>
+            </Flex>
+          </FormRoot>
+        </CardContent>
+      </Card>
+      <p className="text-muted-foreground mt-4 text-sm">
+        warning state、form-level error-summary から field への focus link、touched-only timing は
+        public wrapper API では未提供。React Hook Form の設定または consumer composition として
+        UNTESTED。
+      </p>
+    </PageContainer>
+  );
+}