@godxjp/ui 30.9.0 → 31.0.2

package/docs/showcase/theme-customization.tsx

@@ -136,6 +136,7 @@ import {
   type TimelineItem,
 } from "@godxjp/ui/data-display";
 import {
+  Form,
   CheckboxGroup,
   ColorPicker,
   DatePicker,
@@ -586,85 +587,91 @@ function ComponentsBoard(props: {
       pad={{ inline: "lg", block: "md" }}
     >
       {/* 1 · text entry */}
-      <Flex direction="col" gap="md">
-        <FormField
-          id="board-email"
-          label={t("themeShowcase.form.email")}
-          helper={t("themeShowcase.form.emailHint")}
-        >
-          <Input
+      <Form>
+        <Flex direction="col" gap="md">
+          <FormField
             id="board-email"
-            type="email"
-            autoComplete="email"
-            prefix={<Mail aria-hidden="true" />}
-            placeholder={t("themeShowcase.form.emailPlaceholder")}
-            defaultValue="release-desk@ops.example.jp"
-          />
-        </FormField>
-        <FormField id="board-handle" label={t("themeShowcase.form.handle")}>
-          <Input
-            id="board-handle"
-            addonBefore={<AtSign aria-hidden="true" />}
-            defaultValue="release-desk"
-            count={{ max: 24, show: true }}
-          />
-        </FormField>
-      </Flex>
+            label={t("themeShowcase.form.email")}
+            helper={t("themeShowcase.form.emailHint")}
+          >
+            <Input
+              id="board-email"
+              type="email"
+              autoComplete="email"
+              prefix={<Mail aria-hidden="true" />}
+              placeholder={t("themeShowcase.form.emailPlaceholder")}
+              defaultValue="release-desk@ops.example.jp"
+            />
+          </FormField>
+          <FormField id="board-handle" label={t("themeShowcase.form.handle")}>
+            <Input
+              id="board-handle"
+              addonBefore={<AtSign aria-hidden="true" />}
+              defaultValue="release-desk"
+              count={{ max: 24, show: true }}
+            />
+          </FormField>
+        </Flex>
+      </Form>
 
       {/* 2 · multi-select with removable tags + free tags */}
-      <Flex direction="col" gap="md">
-        <FormField
-          id="board-regions"
-          label={t("themeShowcase.form.regions")}
-          helper={regions.length > 0 ? regionList : t("themeShowcase.form.regionsEmpty")}
-        >
-          <Select
+      <Form>
+        <Flex direction="col" gap="md">
+          <FormField
             id="board-regions"
-            mode="multiple"
-            maxTagCount={2}
-            value={regions}
-            onValueChange={setRegions}
-            placeholder={t("themeShowcase.form.regionsPlaceholder")}
-            options={REGION_CODES.map((code) => ({
-              value: code,
-              label: new Intl.DisplayNames([props.locale], { type: "region" }).of(code) ?? code,
-            }))}
-          />
-        </FormField>
-        <FormField id="board-labels" label={t("themeShowcase.form.labels")}>
-          <TagInput
-            id="board-labels"
-            value={labels}
-            onValueChange={setLabels}
-            maxTagCount={2}
-            /* The ceiling the 71-character id is measured against (gh#840). 16 is the widest cut
+            label={t("themeShowcase.form.regions")}
+            helper={regions.length > 0 ? regionList : t("themeShowcase.form.regionsEmpty")}
+          >
+            <Select
+              id="board-regions"
+              mode="multiple"
+              maxTagCount={2}
+              value={regions}
+              onValueChange={setRegions}
+              placeholder={t("themeShowcase.form.regionsPlaceholder")}
+              options={REGION_CODES.map((code) => ({
+                value: code,
+                label: new Intl.DisplayNames([props.locale], { type: "region" }).of(code) ?? code,
+              }))}
+            />
+          </FormField>
+          <FormField id="board-labels" label={t("themeShowcase.form.labels")}>
+            <TagInput
+              id="board-labels"
+              value={labels}
+              onValueChange={setLabels}
+              maxTagCount={2}
+              /* The ceiling the 71-character id is measured against (gh#840). 16 is the widest cut
                that still leaves room for a second chip and the `+1` on one row at 375px; the value
                is untouched — it stays in the chip's `title` and in the remover's accessible name,
                which is the only reason truncating an identifier is allowed at all. */
-            maxTagTextLength={16}
-            placeholder={t("themeShowcase.form.labelsPlaceholder")}
-          />
-        </FormField>
-      </Flex>
+              maxTagTextLength={16}
+              placeholder={t("themeShowcase.form.labelsPlaceholder")}
+            />
+          </FormField>
+        </Flex>
+      </Form>
 
       {/* 3 · dropdown + date */}
-      <Flex direction="col" gap="md">
-        <FormField id="board-plan" label={t("themeShowcase.form.plan")}>
-          <Select
-            id="board-plan"
-            value={plan}
-            onValueChange={setPlan}
-            options={[
-              { value: "starter", label: t("themeShowcase.plan.starter") },
-              { value: "standard", label: t("themeShowcase.plan.standard") },
-              { value: "scale", label: t("themeShowcase.plan.scale") },
-            ]}
-          />
-        </FormField>
-        <FormField id="board-date" label={t("themeShowcase.form.releaseDate")}>
-          <DatePicker id="board-date" defaultValue={new Date("2026-09-12T00:00:00Z")} />
-        </FormField>
-      </Flex>
+      <Form>
+        <Flex direction="col" gap="md">
+          <FormField id="board-plan" label={t("themeShowcase.form.plan")}>
+            <Select
+              id="board-plan"
+              value={plan}
+              onValueChange={setPlan}
+              options={[
+                { value: "starter", label: t("themeShowcase.plan.starter") },
+                { value: "standard", label: t("themeShowcase.plan.standard") },
+                { value: "scale", label: t("themeShowcase.plan.scale") },
+              ]}
+            />
+          </FormField>
+          <FormField id="board-date" label={t("themeShowcase.form.releaseDate")}>
+            <DatePicker id="board-date" defaultValue={new Date("2026-09-12T00:00:00Z")} />
+          </FormField>
+        </Flex>
+      </Form>
 
       {/* 4 · checkboxes — a three-line label beside a one-word one, and a disabled row */}
       <Flex direction="col" gap="md">
@@ -929,35 +936,37 @@ function ComponentsBoard(props: {
           <CardDescription>{t("themeShowcase.signup.description")}</CardDescription>
         </CardHeader>
         <CardContent>
-          <Flex direction="col" gap="md">
-            <FormField id="signup-email" label={t("themeShowcase.signup.email")}>
-              <Input
-                id="signup-email"
-                type="email"
-                autoComplete="email"
-                placeholder="you@example.jp"
-              />
-            </FormField>
-            <FormField id="signup-secret" label={t("themeShowcase.signup.password")}>
-              <PasswordInput
-                id="signup-secret"
-                value={secret}
-                onChange={(event) => setSecret(event.target.value)}
-                autoComplete="new-password"
-              />
-            </FormField>
-            <PasswordStrength value={secret} />
-            <Button fullWidth>{t("themeShowcase.signup.submit")}</Button>
-            <AuthDivider label={t("themeShowcase.signup.or")} />
-            <Button variant="outline" fullWidth>
-              <ShieldCheck aria-hidden="true" />
-              {t("themeShowcase.signup.sso")}
-            </Button>
-            <Button variant="outline" fullWidth>
-              <Fingerprint aria-hidden="true" />
-              {t("themeShowcase.signup.passkey")}
-            </Button>
-          </Flex>
+          <Form>
+            <Flex direction="col" gap="md">
+              <FormField id="signup-email" label={t("themeShowcase.signup.email")}>
+                <Input
+                  id="signup-email"
+                  type="email"
+                  autoComplete="email"
+                  placeholder="you@example.jp"
+                />
+              </FormField>
+              <FormField id="signup-secret" label={t("themeShowcase.signup.password")}>
+                <PasswordInput
+                  id="signup-secret"
+                  value={secret}
+                  onChange={(event) => setSecret(event.target.value)}
+                  autoComplete="new-password"
+                />
+              </FormField>
+              <PasswordStrength value={secret} />
+              <Button fullWidth>{t("themeShowcase.signup.submit")}</Button>
+              <AuthDivider label={t("themeShowcase.signup.or")} />
+              <Button variant="outline" fullWidth>
+                <ShieldCheck aria-hidden="true" />
+                {t("themeShowcase.signup.sso")}
+              </Button>
+              <Button variant="outline" fullWidth>
+                <Fingerprint aria-hidden="true" />
+                {t("themeShowcase.signup.passkey")}
+              </Button>
+            </Flex>
+          </Form>
         </CardContent>
       </Card>
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "30.9.0",
-  "godxUiMcp": "30.9.0",
+  "version": "31.0.2",
+  "godxUiMcp": "31.0.2",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -141,6 +141,10 @@
       "types": "./dist/inertia/index.d.ts",
       "import": "./dist/inertia/index.js"
     },
+    "./react-router": {
+      "types": "./dist/components/react-router/index.d.ts",
+      "import": "./dist/components/react-router/index.js"
+    },
     "./app": {
       "types": "./dist/app/index.d.ts",
       "import": "./dist/app/index.js"

package/scripts/consumer-rule.md

@@ -120,6 +120,20 @@ ngày: năm thứ cần đều ĐÃ CÓ và vẫn bị dựng lại bằng thứ
 Lỗi không phải "đoán sai tên prop" mà là **cho rằng nó không tồn tại nên không
 hỏi**.
 
+## Form: `Form` bọc `FormField`, bề rộng theo nội dung, form dài là PAGE
+
+godx-mailer dính bốn lỗi form trong một ngày, cả bốn đều là kit ĐÃ CÓ đồ đúng
+(gh#998). Giờ ui-audit chặn:
+
+| Sai                                                         | Đúng                                                                                         | rule                   |
+| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------- |
+| ≥2 `FormField` không có `Form`, hoặc xếp hàng bằng `<Flex>` | `<Form layout="horizontal" labelWidth controlWidth>`; hàng = `SpaceCompact` / `Form columns` | `formfield-needs-form` |
+| ≥3 `FormField` trong `DialogBody`                           | page riêng (route riêng)                                                                     | `dialog-form-too-big`  |
+| `Select` hai lựa chọn kéo full width                        | `controlWidth` trên field hoặc một lần trên `Form`                                           | `select-width-hint`    |
+
+Ca kit không diễn đạt được thì **mở issue ở godx-jp/godxjp-ui**, tạm dùng cách
+hợp lệ gần nhất kèm `// TODO(godxjp-ui#<n>)` — không tự chế.
+
 ## Dialog và AlertDialog là MỘT họ — `variant` là lối chuẩn
 
 Đừng với tay sang 12 export `AlertDialog*` nữa. Chúng **vẫn chạy y như cũ** (gỡ

package/scripts/ui-audit.mjs

@@ -85,8 +85,6 @@ function changedFiles() {
     };
   }
 
-
-
   const parts = [
     run(["diff", "--name-only", "--diff-filter=ACMR", mergeBase.trim(), "--"]),
     run(["diff", "--name-only", "--diff-filter=ACMR", "--cached"]),
@@ -1895,6 +1893,105 @@ for (const dir of SCAN_DIRS) {
         snippet: match[0].replace(/\s+/g, " ").slice(0, 120),
       });
     }
+
+    /*
+     * THE LAYER ABOVE THE FIELD (gh#998). `bare-control-needs-formfield` stops a control without a
+     * FormField; nothing stopped a FormField without a Form, or a Form without a width, or a form
+     * that belongs on a page stuffed into a Dialog. godx-mailer hit all four in one day. Validated
+     * on the reporter's own files before and after its fixes: every defect caught before, none in
+     * the fixed files except one the fix missed (four FormFields in a hand-rolled wrapping Flex).
+     */
+    if (isJsx) {
+      const lineAt = (i) => scanContent.slice(0, i).split("\n").length;
+      /*
+       * TWO OR MORE FormFields under ONE parent with no <Form> above them. That is the shape of
+       * every defect in the report — a hand-rolled <Flex> row of fields, a long form in a Dialog, a
+       * page of fields each choosing its own layout. A LONE field is not: a search box, the
+       * ConfirmDialog's type-to-confirm input, a field component whose whole output is one
+       * FormField. Flagging those made this repo's own library code and 29 docs pages red on a
+       * rule whose defect they do not have.
+       *
+       * The walk keeps a stack of open JSX elements so "same parent" is structural. `(?<![\w.$])`
+       * skips a generic argument (`useRef<HTMLDivElement>`), which is preceded by an identifier.
+       */
+      const stack = [];
+      const bareByParent = new Map();
+      let formDepth = 0;
+      for (const m of scanContent.matchAll(
+        /(?<![\w.$])<(\/?)([A-Za-z][\w.]*)(?=[\s>/])([^<>]*?(?:\{[^{}]*\}[^<>]*?)*)(\/?)>/g,
+      )) {
+        const [, close, tag, , selfClose] = m;
+        if (close) {
+          for (let i = stack.length - 1; i >= 0; i -= 1) {
+            if (stack[i].tag === tag) {
+              stack.length = i;
+              break;
+            }
+          }
+          if (tag === "Form") formDepth = Math.max(0, formDepth - 1);
+          continue;
+        }
+        if (tag === "FormField" && formDepth === 0) {
+          const parent = stack.at(-1)?.index ?? -1;
+          (bareByParent.get(parent) ?? bareByParent.set(parent, []).get(parent)).push(m.index);
+        }
+        if (selfClose) continue;
+        stack.push({ tag, index: m.index });
+        if (tag === "Form") formDepth += 1;
+      }
+      for (const group of bareByParent.values()) {
+        if (group.length < 2) continue;
+        for (const at of group) {
+          const lineNo = lineAt(at);
+          if (suppressed("formfield-needs-form", lineNo - 1)) continue;
+          findings.push({
+            file: rel,
+            line: lineNo,
+            rule: "formfield-needs-form",
+            severity: "error",
+            standard: "@godxjp/ui Form (gh#998)",
+            message: `${group.length} FormFields under one parent with no <Form> around them. <Form layout="horizontal" labelWidth controlWidth> is what lines fields up — without it each form picks its own layout, and a row of fields in a hand-rolled <Flex> drops the required field's label out of line. Wrap them in <Form>; a row that belongs together is <SpaceCompact> or <Form columns>. A lone field (a search box, a type-to-confirm input) is not flagged.`,
+            snippet: scanContent.slice(at, at + 120).replace(/\s+/g, " "),
+          });
+        }
+      }
+
+      for (const m of scanContent.matchAll(/<(Dialog\.Body|DialogBody)(?=[\s>])[\s\S]*?<\/\1>/g)) {
+        const count = (m[0].match(/<FormField(?=[\s>/])/g) ?? []).length;
+        if (count < 3) continue;
+        const lineNo = lineAt(m.index);
+        if (suppressed("dialog-form-too-big", lineNo - 1)) continue;
+        findings.push({
+          file: rel,
+          line: lineNo,
+          rule: "dialog-form-too-big",
+          severity: "error",
+          standard: "@godxjp/ui form placement (gh#998)",
+          message: `${count} FormFields in a ${m[1]} — a form this size is a page of its own (its own route, back button, and room to scroll), not a modal. Keep dialogs for a confirmation or one or two fields. A Sheet is not flagged: a side drawer is where an advanced filter or an edit form belongs (antd Drawer).`,
+          snippet: m[0].slice(0, 120).replace(/\s+/g, " "),
+        });
+      }
+
+      for (const m of scanContent.matchAll(/<FormField(?=[\s>])([^>]*)>([\s\S]*?)<\/FormField>/g)) {
+        if (!/<Select(?=[\s>/])/.test(m[2]) || /controlWidth=/.test(m[1])) continue;
+        const before = scanContent.slice(0, m.index);
+        const lastForm = [...before.matchAll(/<Form(?=[\s>])([^>]*)>/g)].at(-1);
+        const insideForm = lastForm && before.lastIndexOf("</Form>") < lastForm.index;
+        if (insideForm && /controlWidth=/.test(lastForm[1])) continue;
+        const lineNo = lineAt(m.index);
+        if (suppressed("select-width-hint", lineNo - 1)) continue;
+        findings.push({
+          file: rel,
+          line: lineNo,
+          rule: "select-width-hint",
+          severity: "warn",
+          standard: "GOV.UK Design System · text input width",
+          message:
+            "A <Select> in a FormField with no controlWidth on the field or its <Form> stretches to the full column — a two-option select as wide as an address line. Size the control for its content (`controlWidth` on the FormField, or once on the Form). https://design-system.service.gov.uk/components/text-input/",
+          snippet: scanContent.slice(m.index, m.index + 120).replace(/\s+/g, " "),
+        });
+      }
+    }
   }
 }