@godxjp/ui 26.2.0 → 26.4.0

package/dist/components/data-entry/chat-composer.d.ts

@@ -31,6 +31,7 @@ export declare const ChatComposer: React.ForwardRefExoticComponent<Omit<React.HT
     onCancel?: () => void;
     loading?: import("../../props/index.js").PendingProp;
     submitType?: import("./chat-composer.js").ChatComposerSubmitTypeProp;
+    allowEmptySubmit?: boolean;
     placeholder?: import("../../props/index.js").PlaceholderProp;
     disabled?: import("../../props/index.js").DisabledProp;
     readOnly?: boolean;

package/dist/components/data-entry/chat-composer.js

@@ -4,6 +4,7 @@ import * as React from "react";
 import { SendHorizontal, Square } from "lucide-react";
 import { useTranslation } from "../../i18n/use-translation.js";
 import { cn } from "../../lib/utils.js";
+import { isApplePlatform } from "../../lib/platform.js";
 import { omitFieldA11y, pickFieldA11y, useFieldIdentity } from "../../lib/field-a11y.js";
 import { Button } from "../general/button.js";
 import { Textarea } from "./textarea.js";
@@ -23,6 +24,7 @@ const ChatComposer = React.forwardRef(
     onCancel,
     loading = false,
     submitType = "enter",
+    allowEmptySubmit = false,
     placeholder,
     disabled = false,
     readOnly = false,
@@ -57,12 +59,13 @@ const ChatComposer = React.forwardRef(
     const rest = omitFieldA11y(props);
     const identity = useFieldIdentity({ id, name, "data-field": props["data-field"] });
     const surface = controlSurfaceAttrs({ status, size });
-    const canSubmit = isSendable(draft) && !disabled && !readOnly && !loading;
+    const canSubmit = (allowEmptySubmit || isSendable(draft)) && !disabled && !readOnly && !loading;
     const submit = React.useCallback(() => {
+      if (disabled || readOnly || loading) return;
       const text = innerRef.current?.value ?? draft;
-      if (!isSendable(text) || disabled || readOnly || loading) return;
-      onSubmit?.(text);
-    }, [draft, disabled, readOnly, loading, onSubmit]);
+      if (isSendable(text)) onSubmit?.(text);
+      else if (allowEmptySubmit) onSubmit?.("");
+    }, [draft, disabled, readOnly, loading, allowEmptySubmit, onSubmit]);
     const handleKeyDown = (event) => {
       onKeyDown?.(event);
       if (event.defaultPrevented) return;
@@ -70,7 +73,11 @@ const ChatComposer = React.forwardRef(
       if (composing.current || event.nativeEvent.isComposing || event.nativeEvent.keyCode === 229) {
         return;
       }
-      const wantsSend = submitType === "enter" ? !event.shiftKey : event.shiftKey;
+      const wantsSend = submitType === "modEnter" ? (
+        // ⌘ on Apple platforms, Ctrl everywhere else — the other one is left alone, because
+        // Ctrl+Enter on a Mac is not the convention a Mac user reaches for.
+        isApplePlatform() ? event.metaKey : event.ctrlKey
+      ) : submitType === "enter" ? !event.shiftKey : event.shiftKey;
       if (!wantsSend) return;
       event.preventDefault();
       submit();

package/dist/components/query/mutation-feedback.d.ts

@@ -3,5 +3,7 @@ export type { AlertMutationFeedbackProp, AlertMutationFeedbackProp as AlertMutat
 /**
  * Inline mutation error — renders nothing when idle/success.
  * Prefer toast for transient saves; use this for blocking form sections (SimulatorPage).
+ * Inside a form that received a server error bag (`FormRoot errors` / `Form errors`), a validation
+ * error is the fields' to show, so it is skipped by default (gh#690).
  */
-export declare function AlertMutationFeedback({ mutation, onRetry, showRetry, pending, className, }: AlertMutationFeedbackProp): import("react").JSX.Element | null;
+export declare function AlertMutationFeedback({ mutation, onRetry, showRetry, pending, ignoreValidationErrors, className, }: AlertMutationFeedbackProp): import("react").JSX.Element | null;

package/dist/components/query/mutation-feedback.js

@@ -1,15 +1,25 @@
 "use client";
 import { Fragment, jsx } from "react/jsx-runtime";
 import { AlertQueryError } from "../feedback/alert.js";
+import { useFormErrorsRegistry } from "../data-entry/form-errors.js";
+import { classifyQueryError } from "../../lib/query-error.js";
 function AlertMutationFeedback({
   mutation,
   onRetry,
   showRetry = true,
   pending,
+  ignoreValidationErrors,
   className
 }) {
+  const registry = useFormErrorsRegistry();
+  const bagShowsErrors = registry !== null && Object.values(registry.errors).some(
+    (entry) => Array.isArray(entry) ? entry.some(Boolean) : Boolean(entry)
+  );
   if (mutation.isPending && pending) return /* @__PURE__ */ jsx(Fragment, { children: pending });
   if (!mutation.isError || mutation.error == null) return null;
+  if ((ignoreValidationErrors ?? bagShowsErrors) && classifyQueryError(mutation.error).category === "validation") {
+    return null;
+  }
   return /* @__PURE__ */ jsx(
     AlertQueryError,
     {

package/dist/contracts/measurement.json

@@ -1,6 +1,6 @@
 {
   "$comment": "AUTO-GENERATED by scripts/gen-measurement-contract.mjs — do not edit. Read this instead of guessing: docs/MEASUREMENT-CONTRACT.md.",
-  "version": "26.2.0",
+  "version": "26.4.0",
   "targetSize": {
     "standard": "WCAG 2.2 SC 2.5.8 Target Size (Minimum), level AA — 24×24 CSS px",
     "min": 24,

package/dist/i18n/messages/en.json

@@ -169,7 +169,8 @@
       "send": "Send message",
       "cancel": "Stop generating",
       "hintEnter": "Enter to send · Shift + Enter for a new line",
-      "hintShiftEnter": "Shift + Enter to send · Enter for a new line"
+      "hintShiftEnter": "Shift + Enter to send · Enter for a new line",
+      "hintModEnter": "{modifier} + Enter to send · Enter for a new line"
     },
     "chatSuggestion": {
       "label": "Suggestions",

package/dist/i18n/messages/ja.json

@@ -166,7 +166,8 @@
       "send": "メッセージを送信",
       "cancel": "生成を停止",
       "hintEnter": "Enter で送信 · Shift + Enter で改行",
-      "hintShiftEnter": "Shift + Enter で送信 · Enter で改行"
+      "hintShiftEnter": "Shift + Enter で送信 · Enter で改行",
+      "hintModEnter": "{modifier} + Enter で送信 · Enter で改行"
     },
     "chatSuggestion": {
       "label": "候補",

package/dist/i18n/messages/vi.json

@@ -166,7 +166,8 @@
       "send": "Gửi tin nhắn",
       "cancel": "Dừng tạo câu trả lời",
       "hintEnter": "Enter để gửi · Shift + Enter để xuống dòng",
-      "hintShiftEnter": "Shift + Enter để gửi · Enter để xuống dòng"
+      "hintShiftEnter": "Shift + Enter để gửi · Enter để xuống dòng",
+      "hintModEnter": "{modifier} + Enter để gửi · Enter để xuống dòng"
     },
     "chatSuggestion": {
       "label": "Gợi ý",

package/dist/lib/platform.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Whether the user agent runs on an Apple platform (macOS, iOS, iPadOS), where the primary
+ * shortcut modifier is ⌘ (`metaKey`) rather than Ctrl (`ctrlKey`).
+ *
+ * `navigator.userAgentData.platform` is the standards answer (Chromium); `navigator.platform` is
+ * the deprecated but universally present fallback (Safari and Firefox still report `MacIntel` /
+ * `iPhone` / `iPad` there). Outside a browser there is no platform, so the answer is `false` — a
+ * server render therefore describes the Ctrl shortcut.
+ */
+export declare function isApplePlatform(): boolean;

package/dist/lib/platform.js

@@ -0,0 +1,9 @@
+function isApplePlatform() {
+  if (typeof navigator === "undefined") return false;
+  const data = navigator.userAgentData;
+  const platform = data?.platform || navigator.platform || "";
+  return /mac|iphone|ipad|ipod/i.test(platform);
+}
+export {
+  isApplePlatform
+};

package/dist/lib/utils.d.ts

@@ -1,2 +1,3 @@
 import { type ClassValue } from "clsx";
 export declare function cn(...inputs: ClassValue[]): string;
+export { isApplePlatform } from "./platform.js";

package/dist/lib/utils.js

@@ -3,6 +3,8 @@ import { twMerge } from "tailwind-merge";
 function cn(...inputs) {
   return twMerge(clsx(inputs));
 }
+import { isApplePlatform } from "./platform.js";
 export {
-  cn
+  cn,
+  isApplePlatform
 };

package/dist/props/components/data-entry.prop.d.ts

@@ -294,9 +294,9 @@ export type FormFieldProp = {
      *
      * `before` is for a helper the reader needs BEFORE they answer rather than after: the
      * secondary language of a bilingual form, a unit or format note, a pick-one-of-these
-     * preamble. `labelAddon` cannot carry that — it is an inline row beside the label with no
-     * wrap, sized for a chip or a help button, so a full sentence squeezes the label instead of
-     * taking its own line. Putting the second line inside `label` does work, but costs the
+     * preamble. `labelAddon` cannot carry that — it belongs to the label row, sized for a chip, a
+     * help button or a short text action; in a horizontal/inline field it wraps under the label
+     * inside the label column, so a full sentence stacks there instead of above the input. Putting the second line inside `label` does work, but costs the
      * string-label fallbacks (`aria-label`, `FieldNameContext`), which fire only when `label` is
      * a plain string.
      *
@@ -308,7 +308,11 @@ export type FormFieldProp = {
     validateStatus?: "success" | "warning" | "error" | "validating";
     hasFeedback?: boolean;
     feedback?: React.ReactNode;
-    /** Optional control rendered inline after the label (e.g. a help button). */
+    /**
+     * Optional control rendered after the label (e.g. a help button, a short text action). In a
+     * horizontal/inline field the label row wraps: an addon that does not fit beside the label
+     * drops to its own line under it, capped to the label column, never into the control column.
+     */
     labelAddon?: React.ReactNode;
     /** Override the Form's layout for this field only. */
     layout?: FormLayoutProp;
@@ -341,9 +345,9 @@ export type FormFieldProp = {
      *
      * `before` is for a helper the reader needs BEFORE they answer rather than after: the
      * secondary language of a bilingual form, a unit or format note, a pick-one-of-these
-     * preamble. `labelAddon` cannot carry that — it is an inline row beside the label with no
-     * wrap, sized for a chip or a help button, so a full sentence squeezes the label instead of
-     * taking its own line. Putting the second line inside `label` does work, but costs the
+     * preamble. `labelAddon` cannot carry that — it belongs to the label row, sized for a chip, a
+     * help button or a short text action; in a horizontal/inline field it wraps under the label
+     * inside the label column, so a full sentence stacks there instead of above the input. Putting the second line inside `label` does work, but costs the
      * string-label fallbacks (`aria-label`, `FieldNameContext`), which fire only when `label` is
      * a plain string.
      *
@@ -355,7 +359,11 @@ export type FormFieldProp = {
     validateStatus?: "success" | "warning" | "error" | "validating";
     hasFeedback?: boolean;
     feedback?: React.ReactNode;
-    /** Optional control rendered inline after the label (e.g. a help button). */
+    /**
+     * Optional control rendered after the label (e.g. a help button, a short text action). In a
+     * horizontal/inline field the label row wraps: an addon that does not fit beside the label
+     * drops to its own line under it, capped to the label column, never into the control column.
+     */
     labelAddon?: React.ReactNode;
     /** Override the Form's layout for this field only. */
     layout?: FormLayoutProp;
@@ -1774,10 +1782,13 @@ export type BranchScopePickerProp = FieldA11yProps & {
  *
  * `enter` (default) is the chat convention: `Enter` sends, `Shift+Enter` inserts a newline.
  * `shiftEnter` is the inverse, for composers that hold long, deliberately multi-line drafts.
- * Neither ever fires while an IME conversion is in flight.
+ * `modEnter` is this library's extension (antd X has only the first two; see
+ * docs/DESIGN-AUTHORITY.md): `⌘+Enter` on Apple platforms, `Ctrl+Enter` elsewhere sends, while
+ * `Enter` and `Shift+Enter` both insert a newline — the record-comment convention.
+ * None of them ever fires while an IME conversion is in flight.
  * @see ChatComposer
  */
-export type ChatComposerSubmitTypeProp = "enter" | "shiftEnter";
+export type ChatComposerSubmitTypeProp = "enter" | "shiftEnter" | "modEnter";
 /**
  * @see ChatComposer — the message input of a conversation (Ant Design X `Sender`; the industry
  * calls the control a *composer*, so that is what it is named).
@@ -1797,7 +1808,8 @@ export type ChatComposerProp = Omit<React.HTMLAttributes<HTMLDivElement>, "onSub
     onValueChange?: OnValueChangeProp<string>;
     /**
      * Send the draft. Receives the text as typed; never fires for an empty or whitespace-only
-     * draft, and never while `loading`, `disabled` or `readOnly`.
+     * draft (unless `allowEmptySubmit`, which then passes `""`), and never while `loading`,
+     * `disabled` or `readOnly`.
      */
     onSubmit?: (value: string) => void;
     /** Stop the in-flight response. Only reachable while `loading`. */
@@ -1809,6 +1821,13 @@ export type ChatComposerProp = Omit<React.HTMLAttributes<HTMLDivElement>, "onSub
     loading?: PendingProp;
     /** Which keystroke sends and which breaks the line. Default `enter`. */
     submitType?: ChatComposerSubmitTypeProp;
+    /**
+     * Let an empty or whitespace-only draft be sent — for a composer whose `header`/`footer` carry
+     * payload of their own (a status change on a record). The send button stays enabled and both
+     * the button and the keyboard submit call `onSubmit("")`. Still blocked while `loading`,
+     * `disabled` or `readOnly`. Default `false`.
+     */
+    allowEmptySubmit?: boolean;
     /** Empty-state text of the draft box; pass it through `t()` at the call site. */
     placeholder?: PlaceholderProp;
     /** Disable the whole composer (draft box and every action). */

package/dist/props/components/query.prop.d.ts

@@ -31,6 +31,13 @@ export type AlertMutationFeedbackProp = {
     showRetry?: boolean;
     /** Optional inline pending slot while `mutation.isPending`. */
     pending?: React.ReactNode;
+    /**
+     * Skip rendering when the error classifies as a validation error (`classifyQueryError` category
+     * `"validation"`: 400/422). `true` skips every such error. When omitted, the alert is skipped only
+     * inside a `FormRoot`/`Form` whose `errors` bag holds at least one message (the fields show it;
+     * `FormErrors` shows unclaimed keys); an empty/absent bag still renders the alert.
+     */
+    ignoreValidationErrors?: boolean;
     className?: ClassNameProp;
 };
 type QueryRefetchLike = Pick<UseQueryResult<unknown>, "isFetching" | "refetch">;

package/dist/props/registry.d.ts

@@ -2048,6 +2048,10 @@ export declare const COMPONENT_PROP_REGISTRY: {
             readonly field: "pending";
             readonly local: true;
             readonly reason: "Inline pending ReactNode slot, not boolean PendingProp state.";
+        }, {
+            readonly field: "ignoreValidationErrors";
+            readonly local: true;
+            readonly reason: "Query-error category filter; defaults on inside a Form whose error bag holds messages.";
         }, "ClassNameProp"];
     };
     readonly ButtonRefetchProp: {

package/dist/props/registry.js

@@ -2401,6 +2401,11 @@ const COMPONENT_PROP_REGISTRY = {
         local: true,
         reason: "Inline pending ReactNode slot, not boolean PendingProp state."
       },
+      {
+        field: "ignoreValidationErrors",
+        local: true,
+        reason: "Query-error category filter; defaults on inside a Form whose error bag holds messages."
+      },
       "ClassNameProp"
     ]
   },

package/dist/styles/control.css

@@ -1060,7 +1060,7 @@
     border: 0;
     padding: 0;
     cursor: pointer;
-    color: hsl(var(--muted-foreground) / 0.45);
+    color: hsl(var(--rating-star-empty-color, var(--muted-foreground)) / var(--rating-star-empty-alpha));
     line-height: 0;
   }
   .ui-rating-star:disabled {
@@ -1072,7 +1072,7 @@
   }
 
   .ui-rating-star-filled {
-    color: hsl(var(--warning));
+    color: hsl(var(--rating-star-filled-color, var(--warning)));
   }
   .ui-rating-star-filled svg {
     fill: currentColor;
@@ -3017,7 +3017,7 @@
   }
 
   .ui-rating-star-half-filled {
-    color: hsl(var(--warning));
+    color: hsl(var(--rating-star-filled-color, var(--warning)));
   }
 
   .ui-radio-button-bar {

package/dist/styles/form-layout.css

@@ -99,9 +99,16 @@
     column-gap: var(--form-label-gap);
     row-gap: var(--space-stack-xs);
   }
+
   .ui-form-field[data-collapse-below="false"]:is([data-layout="horizontal"], [data-layout="inline"])
     > .ui-form-field-label {
     min-block-size: var(--control-height);
+    flex-wrap: wrap;
+  }
+  .ui-form-field[data-collapse-below="false"]:is([data-layout="horizontal"], [data-layout="inline"])
+    > .ui-form-field-label
+    > * {
+    max-inline-size: 100%;
   }
   .ui-form-field[data-collapse-below="false"][data-label-align="end"]:is(
       [data-layout="horizontal"],
@@ -125,6 +132,12 @@
     .ui-form-field[data-collapse-below="sm"]:is([data-layout="horizontal"], [data-layout="inline"])
       > .ui-form-field-label {
       min-block-size: var(--control-height);
+      flex-wrap: wrap;
+    }
+    .ui-form-field[data-collapse-below="sm"]:is([data-layout="horizontal"], [data-layout="inline"])
+      > .ui-form-field-label
+      > * {
+      max-inline-size: 100%;
     }
     .ui-form-field[data-collapse-below="sm"][data-label-align="end"]:is(
         [data-layout="horizontal"],
@@ -149,6 +162,12 @@
     .ui-form-field[data-collapse-below="md"]:is([data-layout="horizontal"], [data-layout="inline"])
       > .ui-form-field-label {
       min-block-size: var(--control-height);
+      flex-wrap: wrap;
+    }
+    .ui-form-field[data-collapse-below="md"]:is([data-layout="horizontal"], [data-layout="inline"])
+      > .ui-form-field-label
+      > * {
+      max-inline-size: 100%;
     }
     .ui-form-field[data-collapse-below="md"][data-label-align="end"]:is(
         [data-layout="horizontal"],
@@ -173,6 +192,12 @@
     .ui-form-field[data-collapse-below="lg"]:is([data-layout="horizontal"], [data-layout="inline"])
       > .ui-form-field-label {
       min-block-size: var(--control-height);
+      flex-wrap: wrap;
+    }
+    .ui-form-field[data-collapse-below="lg"]:is([data-layout="horizontal"], [data-layout="inline"])
+      > .ui-form-field-label
+      > * {
+      max-inline-size: 100%;
     }
     .ui-form-field[data-collapse-below="lg"][data-label-align="end"]:is(
         [data-layout="horizontal"],
@@ -197,6 +222,12 @@
     .ui-form-field[data-collapse-below="xl"]:is([data-layout="horizontal"], [data-layout="inline"])
       > .ui-form-field-label {
       min-block-size: var(--control-height);
+      flex-wrap: wrap;
+    }
+    .ui-form-field[data-collapse-below="xl"]:is([data-layout="horizontal"], [data-layout="inline"])
+      > .ui-form-field-label
+      > * {
+      max-inline-size: 100%;
     }
     .ui-form-field[data-collapse-below="xl"][data-label-align="end"]:is(
         [data-layout="horizontal"],

package/dist/tokens/components/control.css

@@ -82,6 +82,10 @@
 
   --rating-focus-ring-offset: 2px;
 
+  --rating-star-filled-color: initial;
+  --rating-star-empty-color: initial;
+  --rating-star-empty-alpha: 0.45;
+
   --checkbox-border-width: var(--stroke-hairline);
   --checkbox-size: calc(1rem * var(--scaling));
   --checkbox-size-compact: 0.875rem;

package/docs/DESIGN-AUTHORITY.md

@@ -257,6 +257,15 @@ in page CSS.
   `onClose`, because `onClose` already means overlay dismiss across Dialog/Drawer and would read
   as closing a surface, not removing one applied filter chip. Implemented on `Badge` — the DS chip
   primitive — rather than adding a separate `Tag` export beside `Badge`.
+- **`ChatComposer.submitType="modEnter"` and `ChatComposer.allowEmptySubmit`.** Ant Design X
+  `Sender.submitType` is only `"enter" | "shiftEnter"`, and `Sender` never submits an empty draft.
+  A comment composer on a record needs the convention GitHub, Jira, Linear and GitLab share —
+  `Enter` breaks the line, `⌘+Enter` (Apple platforms, `metaKey`) / `Ctrl+Enter` (elsewhere,
+  `ctrlKey`) sends — and needs to post a status change with no text (gh#693). `"modEnter"` extends
+  antd's union rather than renaming it, so both antd values keep their meaning; its hint is
+  `dataEntry.chatComposer.hintModEnter` with `{modifier}` from `isApplePlatform()`
+  (`@godxjp/ui/lib/utils`). `allowEmptySubmit` (default `false`, antd's behaviour) sends `""`,
+  still never while `loading` / `disabled` / `readOnly`.
 
 **A knob that only a fork could reach is not parity either.** antd's `components`,
 `filterDropdown`, `classNames`/`styles` semantic maps and `prefixCls` all exist to let a consumer

package/docs/data-entry/chat-composer.tsx

@@ -14,9 +14,12 @@ import {
   ChatComposer,
   ChatSuggestion,
   FormField,
+  Select,
   type ChatSuggestionItemProp,
 } from "@godxjp/ui/data-entry";
 import { Button, Text } from "@godxjp/ui/general";
+import { useTranslation } from "@godxjp/ui/i18n";
+import { isApplePlatform } from "@godxjp/ui/lib/utils";
 import {
   AppShell,
   Flex,
@@ -34,7 +37,8 @@ import { Bot, MessageSquare, Paperclip, Settings, Smile, Sparkles, Users } from
  *
  * The first card is the real screen: a live assistant transcript whose composer sends, streams and
  * cancels, with `/` slash commands and `@` mentions wired to the same draft. Every card after it
- * exists so the whole API is visible AT REST — both `submitType` values, all four `size` steps,
+ * exists so the whole API is visible AT REST — every `submitType` value (including the record-
+ * comment bar: `modEnter` + `allowEmptySubmit`), all four `size` steps,
  * every slot, and each non-default state — without having to click anything.
  *
  * Composed only from real @godxjp/ui components.
@@ -91,6 +95,20 @@ const OPENING: Message[] = [
   },
 ];
 
+/** Record statuses for the comment bar — a status change is postable without any text. */
+const STATUSES = [
+  { value: "open", label: "未対応" },
+  { value: "inProgress", label: "処理中" },
+  { value: "resolved", label: "処理済み" },
+  { value: "closed", label: "完了" },
+];
+
+interface Comment {
+  id: number;
+  body: string;
+  status: string | null;
+}
+
 /** One transcript line. The message FEED is ChatBubbleList's job; here it only sets the scene. */
 function Line({ message }: { message: Message }) {
   const mine = message.author === "you";
@@ -110,6 +128,8 @@ function Line({ message }: { message: Message }) {
 }
 
 export default function Demo() {
+  const { t } = useTranslation();
+
   // ── Card 1: the live screen ───────────────────────────────────────────────────────────────
   const [messages, setMessages] = useState<Message[]>(OPENING);
   const [draft, setDraft] = useState("");
@@ -142,6 +162,24 @@ export default function Demo() {
   const [shiftDraft, setShiftDraft] = useState("Enter は改行、Shift + Enter で送信");
   const [lastSent, setLastSent] = useState<string>("—");
 
+  // ── Card 2b: the record-comment bar (modEnter + allowEmptySubmit) ──────────────────────────
+  const [commentDraft, setCommentDraft] = useState("");
+  const [status, setStatus] = useState("open");
+  const [savedStatus, setSavedStatus] = useState("open");
+  const [comments, setComments] = useState<Comment[]>([]);
+
+  function postComment(text: string) {
+    const changed = status !== savedStatus;
+    // An empty draft with no status change carries nothing — the consumer decides, not the box.
+    if (!text && !changed) return;
+    setComments((current) => [
+      ...current,
+      { id: current.length + 1, body: text, status: changed ? status : null },
+    ]);
+    setSavedStatus(status);
+    setCommentDraft("");
+  }
+
   // ── Card 3: the four size steps ───────────────────────────────────────────────────────────
   const [sizeDrafts, setSizeDrafts] = useState<Record<string, string>>({
     xs: "xs",
@@ -286,6 +324,68 @@ export default function Demo() {
             </CardContent>
           </Card>
 
+          {/* ── 2b. Record comment bar ───────────────────────────────────────────────────── */}
+          <Card>
+            <CardHeader>
+              <CardTitle level={2}>
+                submitType=&quot;modEnter&quot; · allowEmptySubmit · 課題へのコメント
+              </CardTitle>
+              <CardDescription>
+                Enter と Shift + Enter は改行、⌘ + Enter（Mac）/ Ctrl + Enter（Windows・Linux）で
+                投稿します。allowEmptySubmit により本文が空でも送信でき、ステータスだけを
+                変更できます（onSubmit には空文字が渡ります）。
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Flex direction="col" gap="md">
+                {comments.length === 0 ? (
+                  <Text size="sm" tone="muted">
+                    まだコメントはありません
+                  </Text>
+                ) : (
+                  comments.map((comment) => (
+                    <Flex key={comment.id} direction="col" gap="xs">
+                      {comment.status ? (
+                        <Badge tone="info">
+                          ステータス：
+                          {STATUSES.find((option) => option.value === comment.status)?.label}
+                        </Badge>
+                      ) : null}
+                      {comment.body ? <Text>{comment.body}</Text> : null}
+                    </Flex>
+                  ))
+                )}
+                <ChatComposer
+                  aria-label="課題へのコメント"
+                  submitType="modEnter"
+                  allowEmptySubmit
+                  value={commentDraft}
+                  onValueChange={setCommentDraft}
+                  onSubmit={postComment}
+                  placeholder="コメントを入力"
+                  submitLabel="コメントを投稿"
+                  footer={
+                    <Flex direction="row" gap="sm" align="center" justify="between" wrap>
+                      <Select
+                        size="sm"
+                        aria-label="ステータス"
+                        value={status}
+                        onValueChange={setStatus}
+                        clearable={false}
+                        options={STATUSES}
+                      />
+                      <Text size="xs" tone="muted">
+                        {t("dataEntry.chatComposer.hintModEnter", {
+                          modifier: isApplePlatform() ? "⌘" : "Ctrl",
+                        })}
+                      </Text>
+                    </Flex>
+                  }
+                />
+              </Flex>
+            </CardContent>
+          </Card>
+
           {/* ── 3. Every size step ───────────────────────────────────────────────────────── */}
           <Card>
             <CardHeader>

package/docs/query/mutation-feedback.tsx

@@ -4,15 +4,19 @@ import { QueryClient, QueryClientProvider, useMutation } from "@tanstack/react-q
 
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
 import { FormField, Input } from "@godxjp/ui/data-entry";
+import { FormFieldControl, FormRoot, useZodForm } from "@godxjp/ui/form";
 import { Button } from "@godxjp/ui/general";
 import { Flex, PageContainer } from "@godxjp/ui/layout";
 import { AlertMutationFeedback } from "@godxjp/ui/query";
+import { z } from "zod";
 
 /**
  * AlertMutationFeedback · inline mutation error below a form's submit. Renders
  * NOTHING while idle/successful; surfaces the error + a retry when useMutation
  * fails. Composed from real @godxjp/ui + @tanstack/react-query. (This demo fires
- * the mutation once on mount so the error state is visible.)
+ * the mutation once on mount so the error state is visible.) Inside a FormRoot
+ * that received `errors`, a 400/422 validation error is skipped by default —
+ * the fields already show the bag — while a 5xx still renders the alert.
  */
 const queryClient = new QueryClient();
 
@@ -54,6 +58,59 @@ function Block() {
   );
 }
 
+type SaveError = Error & { status: number; errors?: Record<string, string[]> };
+
+function saveError(status: number, message: string, errors?: Record<string, string[]>) {
+  return Object.assign(new Error(message), { status, errors }) as SaveError;
+}
+
+const schema = z.object({ code: z.string() });
+
+function InFormBlock() {
+  const form = useZodForm(schema, { defaultValues: { code: "BTY-0012" } });
+  const mutation = useMutation<void, SaveError, number>({
+    mutationFn: async (status) => {
+      throw status === 422
+        ? saveError(422, "The given data was invalid.", {
+            code: ["取引先コードが重複しています"],
+          })
+        : saveError(500, "サーバーエラーが発生しました (500)");
+    },
+  });
+
+  useEffect(() => {
+    mutation.mutate(422);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle level={2}>取引先の登録 · FormRoot errors</CardTitle>
+        <CardDescription>
+          A 422 shows on the field only; a 500 still renders the alert.
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        <FormRoot form={form} errors={mutation.error?.errors} onSubmit={() => mutation.mutate(422)}>
+          <FormFieldControl name="code" label="取引先コード">
+            {(field) => <Input {...field} value={String(field.value ?? "")} />}
+          </FormFieldControl>
+          <AlertMutationFeedback mutation={mutation} onRetry={() => mutation.mutate(500)} />
+          <Flex direction="row" wrap justify="end" gap="sm">
+            <Button variant="outline" type="button" onClick={() => mutation.mutate(500)}>
+              500 を再現
+            </Button>
+            <Button type="submit" loading={mutation.isPending}>
+              保存
+            </Button>
+          </Flex>
+        </FormRoot>
+      </CardContent>
+    </Card>
+  );
+}
+
 export default function Demo() {
   return (
     <QueryClientProvider client={queryClient}>
@@ -63,6 +120,7 @@ export default function Demo() {
       >
         <Flex direction="col" gap="lg">
           <Block />
+          <InFormBlock />
         </Flex>
       </PageContainer>
     </QueryClientProvider>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "26.2.0",
-  "godxUiMcp": "26.2.0",
+  "version": "26.4.0",
+  "godxUiMcp": "26.4.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/scripts/_agent-setup.mjs

@@ -58,12 +58,19 @@ function isPackageWrittenMcpEntry(entry) {
   return Object.keys(entry.env ?? {}).every((key) => key === "GODX_UI_VERSION");
 }
 
-function mcpConfigMismatchMessage(root, existing, expected) {
+/** True when an `mcpServers` entry launches the catalog server, under any key or launcher flags. */
+function runsUiMcp(entry) {
+  const parts = [entry?.command, ...(Array.isArray(entry?.args) ? entry.args : [])];
+  return parts.some((part) => typeof part === "string" && /(^|\/)@godxjp\/ui-mcp(@|$)/.test(part));
+}
+
+function mcpConfigMismatchMessage(root, existing, expected, key = MCP_KEY) {
   const ui = readConsumerUiMetadata(root);
   const pin = expected.args?.[0] ?? "@godxjp/ui-mcp";
   const ver = ui?.version ?? "(unknown)";
   return (
-    `present (custom godx-ui MCP entry — not overwritten; expected ${pin} with ` +
+    `present (custom godx-ui MCP entry${key === MCP_KEY ? "" : ` under key "${key}"`} — not overwritten, ` +
+    `no duplicate added; expected ${pin} with ` +
     `env.GODX_UI_VERSION=${ver} from node_modules/@godxjp/ui)`
   );
 }
@@ -265,7 +272,18 @@ function readJsonFile(path) {
   // writing the result back is the same data loss by a different door, so it is a refusal too.
   if (json === null || typeof json !== "object" || Array.isArray(json))
     return { state: "wrong-shape" };
-  return { state: "ok", json };
+  return { state: "ok", json, indent: indentOf(raw) };
+}
+
+/**
+ * The indentation the file already uses — a tab, or the width of the first indented line — so a
+ * rewrite changes only the keys it touches. Re-serialising at a fixed 2 turned a one-entry edit
+ * into a whole-file diff in a repo formatted at 4 (gh#692).
+ */
+function indentOf(raw) {
+  const first = raw.match(/\n([ \t]+)\S/);
+  if (!first) return 2;
+  return first[1].startsWith("\t") ? "\t" : first[1].length;
 }
 
 /** The sentence that goes in the refusal, so a consumer knows which of the three it hit. */
@@ -385,18 +403,25 @@ export function ensureMcpJson(root) {
     return refuseAndSuggest(path, suggested, "`mcpServers` is not an object");
   }
   json.mcpServers = json.mcpServers ?? {};
-  if (json.mcpServers[MCP_KEY]) {
-    if (mcpEntryMatches(json.mcpServers[MCP_KEY], expected)) return "present";
-    if (!isPackageWrittenMcpEntry(json.mcpServers[MCP_KEY])) {
-      return mcpConfigMismatchMessage(root, json.mcpServers[MCP_KEY], expected);
+  const indent = read.state === "ok" ? read.indent : 2;
+  // The catalog server may already be registered under ANOTHER key — `godxjp-ui`, `ui`, whatever
+  // the repo chose. Looking only at MCP_KEY added a second copy of the same server beside it, at
+  // a different version (gh#692). Whatever key runs @godxjp/ui-mcp is the entry.
+  const key = json.mcpServers[MCP_KEY]
+    ? MCP_KEY
+    : Object.keys(json.mcpServers).find((name) => runsUiMcp(json.mcpServers[name]));
+  if (key) {
+    if (mcpEntryMatches(json.mcpServers[key], expected)) return "present";
+    if (!isPackageWrittenMcpEntry(json.mcpServers[key])) {
+      return mcpConfigMismatchMessage(root, json.mcpServers[key], expected, key);
     }
-    json.mcpServers[MCP_KEY] = expected;
-    writeFileAtomic(path, JSON.stringify(json, null, 2) + "\n");
+    json.mcpServers[key] = expected;
+    writeFileAtomic(path, JSON.stringify(json, null, indent) + "\n");
     return "refreshed";
   }
   const created = read.state === "missing";
   json.mcpServers[MCP_KEY] = expected;
-  writeFileAtomic(path, JSON.stringify(json, null, 2) + "\n");
+  writeFileAtomic(path, JSON.stringify(json, null, indent) + "\n");
   return created ? "created" : "added";
 }
 
@@ -450,7 +475,7 @@ export function ensureClaudeHooks(root) {
     added.push("SessionStart:workflow-primer");
   }
 
-  writeFileAtomic(path, JSON.stringify(json, null, 2) + "\n");
+  writeFileAtomic(path, JSON.stringify(json, null, read.state === "ok" ? read.indent : 2) + "\n");
   return added;
 }