@godxjp/ui 27.0.0 → 27.1.0

package/dist/components/data-entry/form-errors.d.ts

@@ -17,6 +17,11 @@ interface FormErrorsRegistryValue {
 export declare function useFormErrorsRegistry(): FormErrorsRegistryValue | null;
 /** First message of a bag entry — Laravel arrays surface their first message on the field. */
 export declare function firstBagMessage(entry: string | string[] | undefined): string | undefined;
+/**
+ * `true` when an error bag holds at least one non-empty message. A bag with no keys, or keys whose
+ * entries are empty (`{ code: [] }`), shows nothing anywhere — so it never counts as "displayed".
+ */
+export declare function errorBagHasMessage(errors: ErrorBagProp | undefined): boolean;
 /**
  * FormErrorsProvider — one shared error registry (error bag + claim set) over a region. 兄弟 Form 群で
  * 1 つのエラーバッグを共有するための公開プロバイダ。Two ways to get one: 1. `Form errors={…}` renders this provider itself

package/dist/components/data-entry/form-errors.js

@@ -12,6 +12,11 @@ function firstBagMessage(entry) {
   const message = Array.isArray(entry) ? entry[0] : entry;
   return message ? message : void 0;
 }
+function errorBagHasMessage(errors) {
+  return Object.values(errors ?? {}).some(
+    (entry) => Array.isArray(entry) ? entry.some(Boolean) : Boolean(entry)
+  );
+}
 function FormErrorsProvider({ errors, children }) {
   const [claimed, setClaimed] = React.useState(/* @__PURE__ */ new Map());
   const claim = React.useCallback((key) => {
@@ -65,6 +70,7 @@ function FormErrors({ errors: errorsProp, title, className }) {
 export {
   FormErrors,
   FormErrorsProvider,
+  errorBagHasMessage,
   firstBagMessage,
   useClaimErrorKey,
   useFormErrorsRegistry

package/dist/components/feedback/dialog.d.ts

@@ -12,14 +12,15 @@ interface OverlayOpenProps {
 }
 interface DialogRootProps extends OverlayOpenProps, Pick<DialogProp, "variant"> {
     /**
-     * Giữ tên prop của Radix. RAC không có kiểu overlay không-modal: `Modal` LUÔN khoá cuộn và ẩn
-     * nền khỏi trình đọc màn hình, nên `modal={false}` không còn tắt được điều đó.
+     * `false` = hộp thoại không-modal (WAI-ARIA APG cho phép): trang phía sau vẫn tương tác được và
+     * vẫn trong cây trợ năng, không khoá cuộn, không màn nền, bấm ra ngoài không đóng; tiêu điểm vào
+     * hộp thoại khi mở, Tab ra được, Esc (tiêu điểm ở trong) đóng. Xem đầu tệp, mục gh#696.
      */
     modal?: boolean;
     children?: React.ReactNode;
 }
 /** `data-slot="dialog"` cũ nằm trên Root của Radix, thứ không dựng thẻ nào — nó chưa từng ra DOM. */
-declare function DialogRoot({ children, modal: _modal, variant, ...openProps }: DialogRootProps): React.JSX.Element;
+declare function DialogRoot({ children, modal, variant, ...openProps }: DialogRootProps): React.JSX.Element;
 interface DialogTriggerProps extends React.ComponentPropsWithRef<"button"> {
     /** Mượn thẻ của con thay vì dựng `<button>` riêng. */
     asChild?: boolean;

package/dist/components/feedback/dialog.js

@@ -6,9 +6,11 @@ import { chain, mergeRefs } from "@react-aria/utils";
 import { Dialog as RacDialog, Modal, ModalOverlay } from "react-aria-components";
 import { AlertCircle, X } from "lucide-react";
 import { cn } from "../../lib/utils.js";
+import { isDevelopment } from "../../lib/dev.js";
 import { Slot } from "../../lib/slot.js";
 import { overlayHeaderToneClass } from "./overlay-header-tone.js";
 import { useOverlayCloseFocus } from "./overlay-close-focus.js";
+import { closeOnEscape, NonModalPortal, useNonModalPortal } from "./non-modal-layer.js";
 import { buttonVariants } from "../general/button.js";
 import { useTranslation } from "../../i18n/use-translation.js";
 import { Button } from "../general/button.js";
@@ -41,6 +43,7 @@ function useDialogOpenState(component) {
 }
 const DialogLabelContext = React.createContext(null);
 const DialogVariantContext = React.createContext("default");
+const DialogModalContext = React.createContext(true);
 const OVERLAY_CLASS = "ui-dialog-overlay data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:animate-in data-[state=open]:fade-in-0";
 const CONTENT_CLASS = "data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 duration-200 outline-none";
 function DialogShell({
@@ -59,8 +62,47 @@ function DialogShell({
   const descriptionId = React.useId();
   const labels = React.useMemo(() => ({ titleId, descriptionId }), [titleId, descriptionId]);
   const dataState = state.isOpen ? "open" : "closed";
-  useOverlayCloseFocus(state.isOpen, onCloseAutoFocus);
+  const requestedModal = React.useContext(DialogModalContext);
+  const modal = requestedModal || role === "alertdialog";
+  const ignoresNonModal = !requestedModal && role === "alertdialog";
+  React.useEffect(() => {
+    if (ignoresNonModal && isDevelopment()) {
+      console.warn(
+        '[godxjp-ui] Dialog: `modal={false}` is ignored for `variant="destructive"` \u2014 an alertdialog is always modal (WAI-ARIA APG).'
+      );
+    }
+  }, [ignoresNonModal]);
+  const { contentRef, isMounted } = useNonModalPortal(state.isOpen, !modal);
+  useOverlayCloseFocus(state.isOpen, onCloseAutoFocus, modal ? void 0 : contentRef);
   const overlayPortalContainer = useOverlayPortalContainer();
+  const dialog = /* @__PURE__ */ jsx(
+    RacDialog,
+    {
+      role,
+      "aria-labelledby": props["aria-labelledby"] ?? titleId,
+      "aria-describedby": props["aria-describedby"] ?? descriptionId,
+      "data-slot": "dialog-content",
+      "data-state": dataState,
+      className: cn(CONTENT_CLASS, className),
+      render: (racProps) => {
+        const { "data-rac": _rac, ref: racRef, ...rest } = racProps;
+        return modal ? /* @__PURE__ */ jsx("section", { ...rest, ...props, style, ref: mergeRefs(ref, racRef) }) : /* @__PURE__ */ jsx(
+          "section",
+          {
+            ...rest,
+            ...props,
+            style,
+            ref: mergeRefs(ref, racRef, contentRef),
+            onKeyDown: chain(props.onKeyDown, closeOnEscape(() => state.setOpen(false)))
+          }
+        );
+      },
+      children: /* @__PURE__ */ jsx(DialogLabelContext.Provider, { value: labels, children })
+    }
+  );
+  if (!modal) {
+    return isMounted ? /* @__PURE__ */ jsx(NonModalPortal, { container: overlayPortalContainer, children: dialog }) : null;
+  }
   return /* @__PURE__ */ jsx(
     ModalOverlay,
     {
@@ -71,33 +113,18 @@ function DialogShell({
       "data-slot": "dialog-overlay",
       "data-state": dataState,
       className: cn(OVERLAY_CLASS, overlayClassName),
-      children: /* @__PURE__ */ jsx(Modal, { className: "contents", children: /* @__PURE__ */ jsx(
-        RacDialog,
-        {
-          role,
-          "aria-labelledby": props["aria-labelledby"] ?? titleId,
-          "aria-describedby": props["aria-describedby"] ?? descriptionId,
-          "data-slot": "dialog-content",
-          "data-state": dataState,
-          className: cn(CONTENT_CLASS, className),
-          render: (racProps) => {
-            const { "data-rac": _rac, ref: racRef, ...rest } = racProps;
-            return /* @__PURE__ */ jsx("section", { ...rest, ...props, style, ref: mergeRefs(ref, racRef) });
-          },
-          children: /* @__PURE__ */ jsx(DialogLabelContext.Provider, { value: labels, children })
-        }
-      ) })
+      children: /* @__PURE__ */ jsx(Modal, { className: "contents", children: dialog })
     }
   );
 }
 function DialogRoot({
   children,
-  modal: _modal,
+  modal = true,
   variant = "default",
   ...openProps
 }) {
   const state = useOverlayOpenState(openProps);
-  return /* @__PURE__ */ jsx(DialogOpenContext.Provider, { value: state, children: /* @__PURE__ */ jsx(DialogVariantContext.Provider, { value: variant, children }) });
+  return /* @__PURE__ */ jsx(DialogOpenContext.Provider, { value: state, children: /* @__PURE__ */ jsx(DialogModalContext.Provider, { value: modal, children: /* @__PURE__ */ jsx(DialogVariantContext.Provider, { value: variant, children }) }) });
 }
 function DialogTrigger({ asChild, onClick, ...props }) {
   const state = useDialogOpenState("DialogTrigger");

package/dist/components/feedback/non-modal-layer.d.ts

@@ -0,0 +1,16 @@
+import * as React from "react";
+/**
+ * Trạng thái dựng của nhánh non-modal. `enabled=false` (nhánh modal) thì không làm gì: `contentRef`
+ * không được gắn, và `ModalOverlay` tự lo hoạt ảnh thoát.
+ */
+export declare function useNonModalPortal(isOpen: boolean, enabled: boolean): {
+    contentRef: React.RefObject<HTMLElement | null>;
+    isMounted: boolean;
+};
+/** `onKeyDown` cho thẻ dialog non-modal: Esc (tiêu điểm ở trong) đóng. */
+export declare function closeOnEscape(close: () => void): (event: React.KeyboardEvent<HTMLElement>) => void;
+/** Portal + `FocusScope autoFocus restoreFocus` (không `contain`) quanh bề mặt non-modal. */
+export declare function NonModalPortal({ container, children, }: {
+    container: Element | undefined;
+    children: React.ReactNode;
+}): React.ReactPortal | null;

package/dist/components/feedback/non-modal-layer.js

@@ -0,0 +1,37 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { createPortal } from "react-dom";
+import { useExitAnimation } from "@react-aria/utils";
+import { FocusScope } from "react-aria";
+function useNonModalPortal(isOpen, enabled) {
+  const contentRef = React.useRef(null);
+  const isExiting = useExitAnimation(contentRef, enabled && isOpen);
+  return { contentRef, isMounted: isOpen || isExiting };
+}
+function closeOnEscape(close) {
+  return (event) => {
+    if (event.key === "Escape" && !event.defaultPrevented && !event.nativeEvent.isComposing) {
+      event.preventDefault();
+      event.stopPropagation();
+      close();
+    }
+  };
+}
+function NonModalPortal({
+  container,
+  children
+}) {
+  if (typeof document === "undefined") {
+    return null;
+  }
+  return createPortal(
+    /* @__PURE__ */ jsx(FocusScope, { autoFocus: true, restoreFocus: true, children }),
+    container ?? document.body
+  );
+}
+export {
+  NonModalPortal,
+  closeOnEscape,
+  useNonModalPortal
+};

package/dist/components/feedback/sheet.d.ts

@@ -19,13 +19,16 @@ export interface SheetProps {
     /** Gọi khi trạng thái mở đổi. */
     onOpenChange?: (open: boolean) => void;
     /**
-     * Giữ tên prop của Radix. RAC không có kiểu overlay không-modal: `Modal` LUÔN khoá cuộn và ẩn
-     * nền khỏi trình đọc màn hình, nên `modal={false}` không còn tắt được điều đó.
+     * `false` renders a NON-MODAL sheet (WAI-ARIA APG allows non-modal dialogs): the page behind
+     * stays interactive and in the accessibility tree, no scroll lock, no scrim, an outside press
+     * does not close it, no `aria-modal`. Focus moves in on open, Tab can leave, Escape closes while
+     * focus is inside, focus returns to the trigger. Side, size and tokens are unchanged. Default
+     * `true`. gh#701.
      */
     modal?: boolean;
     children?: React.ReactNode;
 }
-export declare function Sheet({ open, defaultOpen, onOpenChange, modal: _modal, children }: SheetProps): React.JSX.Element;
+export declare function Sheet({ open, defaultOpen, onOpenChange, modal, children, }: SheetProps): React.JSX.Element;
 export interface SheetTriggerProps extends React.ComponentPropsWithRef<"button"> {
     /** Mượn thẻ của con thay vì dựng `<button>` riêng. */
     asChild?: boolean;
@@ -74,7 +77,7 @@ export interface SheetContentProps extends React.ComponentPropsWithRef<"section"
      */
     responsive?: SheetResponsiveProp;
 }
-export declare function SheetContent({ side, className, children, showCloseButton, overlayClassName, forceMount: _forceMount, width, responsive, style, ref, ...props }: SheetContentProps): React.JSX.Element;
+export declare function SheetContent({ side, className, children, showCloseButton, overlayClassName, forceMount: _forceMount, width, responsive, style, ref, ...props }: SheetContentProps): React.JSX.Element | null;
 export declare namespace SheetContent {
     var displayName: string;
 }

package/dist/components/feedback/sheet.js

@@ -11,6 +11,7 @@ import { cn } from "../../lib/utils.js";
 import { Slot } from "../../lib/slot.js";
 import { overlayHeaderToneClass } from "./overlay-header-tone.js";
 import { useOverlayCloseFocus } from "./overlay-close-focus.js";
+import { closeOnEscape, NonModalPortal, useNonModalPortal } from "./non-modal-layer.js";
 import { useTranslation } from "../../i18n/use-translation.js";
 const toCssLength = (v) => typeof v === "number" ? `${v}px` : v;
 const SHEET_BREAKPOINT_TOKEN = "--sheet-responsive-breakpoint-width";
@@ -28,8 +29,15 @@ function useSheetOpenState(component) {
   }
   return state;
 }
+const SheetModalContext = React.createContext(true);
 const SheetLabelContext = React.createContext(null);
-function Sheet({ open, defaultOpen, onOpenChange, modal: _modal, children }) {
+function Sheet({
+  open,
+  defaultOpen,
+  onOpenChange,
+  modal = true,
+  children
+}) {
   const [uncontrolled, setUncontrolled] = React.useState(defaultOpen ?? false);
   const isOpen = open ?? uncontrolled;
   const setOpen = React.useCallback(
@@ -45,7 +53,7 @@ function Sheet({ open, defaultOpen, onOpenChange, modal: _modal, children }) {
     [isOpen, open, onOpenChange]
   );
   const state = React.useMemo(() => ({ isOpen, setOpen }), [isOpen, setOpen]);
-  return /* @__PURE__ */ jsx(SheetOpenContext.Provider, { value: state, children });
+  return /* @__PURE__ */ jsx(SheetOpenContext.Provider, { value: state, children: /* @__PURE__ */ jsx(SheetModalContext.Provider, { value: modal, children }) });
 }
 function SheetTrigger({ asChild, onClick, ...props }) {
   const state = useSheetOpenState("SheetTrigger");
@@ -132,8 +140,59 @@ function SheetContent({
   const widthSet = width != null && horizontal;
   const mergedStyle = widthSet ? { ...style, ["--sheet-width"]: toCssLength(width) } : style;
   const dataState = state.isOpen ? "open" : "closed";
-  useOverlayCloseFocus(state.isOpen);
+  const modal = React.useContext(SheetModalContext);
+  const { contentRef, isMounted } = useNonModalPortal(state.isOpen, !modal);
+  useOverlayCloseFocus(state.isOpen, void 0, modal ? void 0 : contentRef);
   const overlayPortalContainer = useOverlayPortalContainer();
+  const dialog = /* @__PURE__ */ jsx(
+    RacDialog,
+    {
+      "aria-labelledby": props["aria-labelledby"] ?? titleId,
+      "aria-describedby": props["aria-describedby"] ?? descriptionId,
+      "data-slot": "sheet-content",
+      "data-state": dataState,
+      "data-responsive": responsive,
+      "data-side": resolvedSide,
+      className: cn(
+        sheetVariants({ side: resolvedSide }),
+        // `width` caps at the viewport: full-width panel on a small screen, capped on a large one.
+        widthSet && "w-[min(var(--sheet-width),100%)] max-w-none sm:max-w-none",
+        // Only the RESPONSIVE bottom presentation is capped — a plain `side="bottom"` sheet keeps
+        // its content-sized height so existing usage is untouched.
+        bottomSheet && "max-h-[var(--sheet-bottom-max-height)]",
+        className
+      ),
+      render: (racProps) => {
+        const { "data-rac": _rac, ref: racRef, ...rest } = racProps;
+        return modal ? /* @__PURE__ */ jsx("section", { ...rest, ...props, style: mergedStyle, ref: mergeRefs(ref, racRef) }) : /* @__PURE__ */ jsx(
+          "section",
+          {
+            ...rest,
+            ...props,
+            style: mergedStyle,
+            ref: mergeRefs(ref, racRef, contentRef),
+            onKeyDown: chain(props.onKeyDown, closeOnEscape(() => state.setOpen(false)))
+          }
+        );
+      },
+      children: /* @__PURE__ */ jsxs(SheetLabelContext.Provider, { value: labels, children: [
+        children,
+        showCloseButton ? /* @__PURE__ */ jsxs(
+          SheetClose,
+          {
+            className: "ui-sheet-close ui-focus-ring disabled:pointer-events-none",
+            children: [
+              /* @__PURE__ */ jsx(X, { className: "ui-sheet-close-icon", "aria-hidden": "true" }),
+              /* @__PURE__ */ jsx("span", { className: "sr-only", children: t("feedback.alert.dismiss") })
+            ]
+          }
+        ) : null
+      ] })
+    }
+  );
+  if (!modal) {
+    return isMounted ? /* @__PURE__ */ jsx(NonModalPortal, { container: overlayPortalContainer, children: dialog }) : null;
+  }
   return /* @__PURE__ */ jsx(
     ModalOverlay,
     {
@@ -144,43 +203,7 @@ function SheetContent({
       "data-slot": "sheet-overlay",
       "data-state": dataState,
       className: cn(SHEET_OVERLAY_CLASS, overlayClassName),
-      children: /* @__PURE__ */ jsx(Modal, { className: "contents", children: /* @__PURE__ */ jsx(
-        RacDialog,
-        {
-          "aria-labelledby": props["aria-labelledby"] ?? titleId,
-          "aria-describedby": props["aria-describedby"] ?? descriptionId,
-          "data-slot": "sheet-content",
-          "data-state": dataState,
-          "data-responsive": responsive,
-          "data-side": resolvedSide,
-          className: cn(
-            sheetVariants({ side: resolvedSide }),
-            // `width` caps at the viewport: full-width panel on a small screen, capped on a large one.
-            widthSet && "w-[min(var(--sheet-width),100%)] max-w-none sm:max-w-none",
-            // Only the RESPONSIVE bottom presentation is capped — a plain `side="bottom"` sheet keeps
-            // its content-sized height so existing usage is untouched.
-            bottomSheet && "max-h-[var(--sheet-bottom-max-height)]",
-            className
-          ),
-          render: (racProps) => {
-            const { "data-rac": _rac, ref: racRef, ...rest } = racProps;
-            return /* @__PURE__ */ jsx("section", { ...rest, ...props, style: mergedStyle, ref: mergeRefs(ref, racRef) });
-          },
-          children: /* @__PURE__ */ jsxs(SheetLabelContext.Provider, { value: labels, children: [
-            children,
-            showCloseButton ? /* @__PURE__ */ jsxs(
-              SheetClose,
-              {
-                className: "ui-sheet-close ui-focus-ring disabled:pointer-events-none",
-                children: [
-                  /* @__PURE__ */ jsx(X, { className: "ui-sheet-close-icon", "aria-hidden": "true" }),
-                  /* @__PURE__ */ jsx("span", { className: "sr-only", children: t("feedback.alert.dismiss") })
-                ]
-              }
-            ) : null
-          ] })
-        }
-      ) })
+      children: /* @__PURE__ */ jsx(Modal, { className: "contents", children: dialog })
     }
   );
 }

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

@@ -1,7 +1,7 @@
 "use client";
 import { Fragment, jsx } from "react/jsx-runtime";
 import { AlertQueryError } from "../feedback/alert.js";
-import { useFormErrorsRegistry } from "../data-entry/form-errors.js";
+import { errorBagHasMessage, useFormErrorsRegistry } from "../data-entry/form-errors.js";
 import { classifyQueryError } from "../../lib/query-error.js";
 function AlertMutationFeedback({
   mutation,
@@ -12,9 +12,7 @@ function AlertMutationFeedback({
   className
 }) {
   const registry = useFormErrorsRegistry();
-  const bagShowsErrors = registry !== null && Object.values(registry.errors).some(
-    (entry) => Array.isArray(entry) ? entry.some(Boolean) : Boolean(entry)
-  );
+  const bagShowsErrors = registry !== null && errorBagHasMessage(registry.errors);
   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") {

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": "27.0.0",
+  "version": "27.1.0",
   "targetSize": {
     "standard": "WCAG 2.2 SC 2.5.8 Target Size (Minimum), level AA — 24×24 CSS px",
     "min": 24,

package/dist/form/form-root.d.ts

@@ -7,4 +7,4 @@ export type { FormRootProp } from "../props/components/form.prop.js";
  * validation) OR `adapter` (a framework-agnostic {@link FormStateAdapter} for a server-driven form
  * library — Inertia's `useForm` via `@godxjp/ui/inertia`, formik, TanStack Form).
  */
-export declare function FormRoot<TFieldValues extends FieldValues>({ form, adapter, onSubmit, onSubmitFailed, onSubmitError, onReset, scrollToFirstError, disabled, layout, labelWidth, controlWidth, labelAlign, collapseBelow, density, columns, requiredMark, errors, children, className, id, }: FormRootProp<TFieldValues>): React.JSX.Element;
+export declare function FormRoot<TFieldValues extends FieldValues>({ form, adapter, onSubmit, onSubmitFailed, onSubmitError, submitFailedMessage, onReset, scrollToFirstError, disabled, layout, labelWidth, controlWidth, labelAlign, collapseBelow, density, columns, requiredMark, errors, children, className, id, }: FormRootProp<TFieldValues>): React.JSX.Element;

package/dist/form/form-root.js

@@ -5,8 +5,10 @@ import { FormProvider } from "react-hook-form";
 import { Alert, AlertDescription } from "../components/feedback/alert.js";
 import { ResponsiveGrid } from "../components/layout/responsive-grid.js";
 import { useTranslation } from "../i18n/use-translation.js";
+import { classifyQueryError } from "../lib/query-error.js";
 import { cn } from "../lib/utils.js";
 import { Form } from "../components/data-entry/form.js";
+import { errorBagHasMessage } from "../components/data-entry/form-errors.js";
 import { FormAdapterContext, FormOptionsContext } from "./form-context.js";
 function collectErrorNames(errors, prefix = "", out = []) {
   if (!errors || typeof errors !== "object") return out;
@@ -43,6 +45,7 @@ function FormRoot({
   onSubmit,
   onSubmitFailed,
   onSubmitError,
+  submitFailedMessage,
   onReset,
   scrollToFirstError = true,
   disabled = false,
@@ -63,21 +66,37 @@ function FormRoot({
   const { t } = useTranslation();
   const pending = React.useRef(false);
   const [submitting, setSubmitting] = React.useState(false);
-  const [submitFailed, setSubmitFailed] = React.useState(false);
+  const [submitFailure, setSubmitFailure] = React.useState(null);
   const options = React.useMemo(() => ({ disabled, submitting }), [disabled, submitting]);
+  const fieldsShowFailure = submitFailure?.validation === true && errorBagHasMessage(errors);
+  React.useEffect(() => {
+    if (!fieldsShowFailure) return;
+    setSubmitFailure(
+      (current) => current && !current.shownByFields ? { ...current, shownByFields: true } : current
+    );
+  }, [fieldsShowFailure]);
+  const showSubmitFailed = submitFailure !== null && submitFailure.settled && !submitFailure.shownByFields && !fieldsShowFailure && submitFailedMessage !== false;
   const content = /* @__PURE__ */ jsxs(Fragment, { children: [
-    submitFailed && /* @__PURE__ */ jsx(Alert, { tone: "destructive", children: /* @__PURE__ */ jsx(AlertDescription, { children: t("dataEntry.form.submitFailed") }) }),
+    showSubmitFailed && /* @__PURE__ */ jsx(Alert, { tone: "destructive", children: /* @__PURE__ */ jsx(AlertDescription, { children: submitFailedMessage ?? t("dataEntry.form.submitFailed") }) }),
     columns ? /* @__PURE__ */ jsx(ResponsiveGrid, { columns, children }) : children
   ] });
   const submit = async (work) => {
     if (disabled || pending.current || adapter?.isSubmitting) return;
     pending.current = true;
     setSubmitting(true);
-    setSubmitFailed(false);
+    setSubmitFailure(null);
     try {
       await work();
     } catch (error) {
-      setSubmitFailed(true);
+      const validation = classifyQueryError(error).category === "validation";
+      setSubmitFailure({ error, validation, settled: !validation, shownByFields: false });
+      if (validation) {
+        setTimeout(
+          () => setSubmitFailure(
+            (current) => current && current.error === error ? { ...current, settled: true } : current
+          )
+        );
+      }
       onSubmitError?.(error);
     } finally {
       pending.current = false;
@@ -117,7 +136,7 @@ function FormRoot({
           onReset: (event) => {
             event.preventDefault();
             if (pending.current) return;
-            setSubmitFailed(false);
+            setSubmitFailure(null);
             adapter.reset?.();
             onReset?.();
           },
@@ -151,7 +170,7 @@ function FormRoot({
         onReset: (event) => {
           event.preventDefault();
           if (pending.current) return;
-          setSubmitFailed(false);
+          setSubmitFailure(null);
           form.reset();
           onReset?.();
         },

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

@@ -16,7 +16,13 @@ export type DialogProp = {
     defaultOpen?: DefaultOpenProp;
     onOpenChange?: OnOpenChangeProp;
     variant?: ConfirmVariantProp;
-    /** Kept from Radix. RAC's `Modal` always locks scroll, so `false` no longer turns that off. */
+    /**
+     * `false` renders a NON-MODAL dialog (allowed by WAI-ARIA APG, Dialog (Modal) pattern): the page
+     * behind stays interactive and in the accessibility tree, no scroll lock, no scrim, an outside
+     * press does not close it, no `aria-modal`. Focus moves in on open, Tab can leave, Escape closes
+     * while focus is inside, focus returns to the trigger. Ignored (dev warning) for
+     * `variant="destructive"` — an alertdialog is always modal. Default `true`.
+     */
     modal?: boolean;
     children?: ChildrenProp;
 };

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

@@ -58,6 +58,18 @@ export type FormRootProp<TFieldValues extends FieldValues> = {
      * render a form-level error instead.
      */
     onSubmitError?: (error: unknown) => void;
+    /**
+     * The form-level banner shown when `onSubmit` rejects. Default: the localized
+     * `dataEntry.form.submitFailed` text. A node replaces that text; `false` never shows the banner.
+     *
+     * The banner is skipped by default for a validation rejection (`classifyQueryError` category
+     * `"validation"`: 400/422) once the `errors` bag holds at least one message — a field or
+     * `<FormErrors />` already shows it (antd shows field errors, not a form banner) — and stays
+     * skipped for that failure if the app later clears the bag. A validation rejection with an empty
+     * or message-less bag, and every other rejection (5xx, network, unknown), shows it. Errors mapped with react-hook-form `setError` instead of `errors` are not detected —
+     * pass `false` there.
+     */
+    submitFailedMessage?: React.ReactNode | false;
     /**
      * A native `<Button type="reset">` inside the form restores `defaultValues` (adapter path:
      * `adapter.reset()`); this runs afterwards for any extra app state (a status banner, a step).
@@ -159,7 +171,12 @@ export type FormFieldControlProp<TFieldValues extends FieldValues> = Pick<import
         onChange: (...args: unknown[]) => void;
         onValueChange: (...args: unknown[]) => void;
         onBlur: () => void;
-        ref: React.Ref<HTMLInputElement>;
+        /**
+         * Callback ref typed on `HTMLElement`, so `{...field}` spreads onto every godx-ui control
+         * (Input, Textarea, Select, NumberInput, DatePicker) with no cast. react-hook-form only needs
+         * `focus()` on it to focus the first invalid field.
+         */
+        ref: React.RefCallback<HTMLElement>;
         /** Present (and `true`) only when the field is disabled, so `{...field}` never re-enables a control. */
         disabled?: DisabledProp;
     }) => React.ReactNode;

package/docs/FORMS.md

@@ -59,16 +59,17 @@ export function CreateCustomerForm({ onSubmit }: { onSubmit: (v: Values) => void
 
 `onSubmit` runs only after validation passes (antd `onFinish`). Everything else is optional:
 
-| Prop                                                              | antd                    | Notes                                                                                    |
-| ----------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------- |
-| `onSubmitFailed(errors)`                                          | `onFinishFailed`        | RHF error tree; the first invalid field is focused regardless                            |
-| `onSubmitError(error)`                                            | —                       | Optional error callback; rejected submissions show localized feedback and retain values  |
-| `onReset`                                                         | —                       | A native `<Button type="reset">` restores `defaultValues`; this runs after               |
-| `scrollToFirstError`                                              | `scrollToFirstError`    | Default `true`; centres the field row, honours `prefers-reduced-motion`                  |
-| `disabled`                                                        | Form `disabled`         | Disables fields and submission; values remain in state. Buttons read `useFormDisabled()` |
-| `layout` `labelWidth` `controlWidth` `labelAlign` `collapseBelow` | `layout` `labelCol` …   | Renders the `Form` layout shell (see the spacing note below)                             |
-| `density` / `requiredMark`                                        | `size` / `requiredMark` | Forwarded to the same shell                                                              |
-| `errors`                                                          | —                       | Server error bag; fields claim their keys, `<FormErrors />` shows the rest               |
+| Prop                                                              | antd                    | Notes                                                                                              |
+| ----------------------------------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------- |
+| `onSubmitFailed(errors)`                                          | `onFinishFailed`        | RHF error tree; the first invalid field is focused regardless                                      |
+| `onSubmitError(error)`                                            | —                       | Optional error callback; rejected submissions show localized feedback and retain values            |
+| `submitFailedMessage`                                             | —                       | Rejection banner text; `false` never shows it. Skipped for a 400/422 once `errors` holds a message |
+| `onReset`                                                         | —                       | A native `<Button type="reset">` restores `defaultValues`; this runs after                         |
+| `scrollToFirstError`                                              | `scrollToFirstError`    | Default `true`; centres the field row, honours `prefers-reduced-motion`                            |
+| `disabled`                                                        | Form `disabled`         | Disables fields and submission; values remain in state. Buttons read `useFormDisabled()`           |
+| `layout` `labelWidth` `controlWidth` `labelAlign` `collapseBelow` | `layout` `labelCol` …   | Renders the `Form` layout shell (see the spacing note below)                                       |
+| `density` / `requiredMark`                                        | `size` / `requiredMark` | Forwarded to the same shell                                                                        |
+| `errors`                                                          | —                       | Server error bag; fields claim their keys, `<FormErrors />` shows the rest                         |
 
 > **Spacing.** A bare `FormRoot` stacks its children with `ui-stack-md`. Passing ANY layout prop
 > switches it to the `Form` shell, whose `--form-block-gap` owns the spacing instead — the two are

package/docs/feedback/dialog.tsx

@@ -34,6 +34,15 @@ const headerTones = [
   "neutral",
 ] as const;
 
+/** Order lines behind the non-modal payment dialog — they stay editable while it is open. */
+const initialLines = [
+  { id: "coffee", name: "ブレンドコーヒー", unitPrice: 480, quantity: 2 },
+  { id: "sandwich", name: "ミックスサンド", unitPrice: 650, quantity: 1 },
+  { id: "cake", name: "チーズケーキ", unitPrice: 520, quantity: 1 },
+];
+
+const yen = new Intl.NumberFormat("ja-JP", { style: "currency", currency: "JPY" });
+
 /**
  * Dialog · compound controlled modal for form-style flows. Always control via
  * open + onOpenChange. Include DialogHeader > DialogTitle (required for a11y).
@@ -46,6 +55,16 @@ export default function Demo() {
   const [headerTone, setHeaderTone] = useState<(typeof headerTones)[number]>("default");
   const [terminateOpen, setTerminateOpen] = useState(false);
   const [reason, setReason] = useState("");
+  const [paymentOpen, setPaymentOpen] = useState(false);
+  const [lines, setLines] = useState(initialLines);
+  const total = lines.reduce((sum, line) => sum + line.unitPrice * line.quantity, 0);
+  const changeQuantity = (id: string, delta: number) => {
+    setLines((current) =>
+      current.map((line) =>
+        line.id === id ? { ...line, quantity: Math.max(0, line.quantity + delta) } : line,
+      ),
+    );
+  };
 
   return (
     <PageContainer
@@ -249,6 +268,69 @@ export default function Demo() {
             </Dialog>
           </CardContent>
         </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Non-modal dialog: the list behind stays editable</CardTitle>
+            <CardDescription>
+              modal=&#123;false&#125; renders a non-modal dialog, a pattern WAI-ARIA APG allows. The
+              page behind keeps working: no scrim, no scroll lock, nothing hidden from assistive
+              tech, and a press outside does not close the dialog. Open the payment dialog, then
+              change a quantity below. The total inside the dialog follows. Focus moves into the
+              dialog on open, Tab can leave it, Escape closes it while focus is inside, and focus
+              returns to the trigger.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              {lines.map((line) => (
+                <Flex key={line.id} direction="row" align="center" justify="between" gap="sm">
+                  <Text>{line.name}</Text>
+                  <Flex direction="row" align="center" gap="sm">
+                    <Button
+                      variant="outline"
+                      size="sm"
+                      aria-label={`${line.name}を減らす`}
+                      disabled={line.quantity === 0}
+                      onClick={() => changeQuantity(line.id, -1)}
+                    >
+                      −
+                    </Button>
+                    <Text aria-live="polite">{line.quantity}</Text>
+                    <Button
+                      variant="outline"
+                      size="sm"
+                      aria-label={`${line.name}を増やす`}
+                      onClick={() => changeQuantity(line.id, 1)}
+                    >
+                      ＋
+                    </Button>
+                  </Flex>
+                </Flex>
+              ))}
+              <Dialog modal={false} open={paymentOpen} onOpenChange={setPaymentOpen}>
+                <DialogTrigger asChild>
+                  <Button size="sm">お会計へ</Button>
+                </DialogTrigger>
+                <DialogContent className="max-w-sm">
+                  <DialogHeader title="お会計" subtitle="注文明細は背面で編集を続けられます。" />
+                  <DialogBody>
+                    <Flex direction="row" justify="between">
+                      <Text tone="muted">合計</Text>
+                      <Text>{yen.format(total)}</Text>
+                    </Flex>
+                  </DialogBody>
+                  <DialogFooter>
+                    <Button variant="outline" onClick={() => setPaymentOpen(false)}>
+                      キャンセル
+                    </Button>
+                    <Button onClick={() => setPaymentOpen(false)}>支払いを確定</Button>
+                  </DialogFooter>
+                </DialogContent>
+              </Dialog>
+            </Flex>
+          </CardContent>
+        </Card>
       </Flex>
     </PageContainer>
   );

package/docs/feedback/sheet.tsx

@@ -42,6 +42,15 @@ const headerTones = [
   "neutral",
 ] as const;
 
+/** Order lines behind the non-modal sheet — they stay editable while it is open. */
+const initialLines = [
+  { id: "coffee", name: "ブレンドコーヒー", unitPrice: 480, quantity: 2 },
+  { id: "sandwich", name: "ミックスサンド", unitPrice: 650, quantity: 1 },
+  { id: "cake", name: "チーズケーキ", unitPrice: 520, quantity: 1 },
+];
+
+const yen = new Intl.NumberFormat("ja-JP", { style: "currency", currency: "JPY" });
+
 /**
  * Sheet · side-panel drawer (Radix Dialog). Slides in from an edge. Compose
  * Sheet > SheetTrigger (asChild) > SheetContent(side) > SheetHeader >
@@ -84,6 +93,18 @@ export default function Demo() {
   const [toneOpen, setToneOpen] = useState(false);
   const [headerTone, setHeaderTone] = useState<(typeof headerTones)[number]>("default");
 
+  // Card 6 · non-modal sheet: the order lines behind it stay editable while it is open.
+  const [summaryOpen, setSummaryOpen] = useState(false);
+  const [lines, setLines] = useState(initialLines);
+  const total = lines.reduce((sum, line) => sum + line.unitPrice * line.quantity, 0);
+  const changeQuantity = (id: string, delta: number) => {
+    setLines((current) =>
+      current.map((line) =>
+        line.id === id ? { ...line, quantity: Math.max(0, line.quantity + delta) } : line,
+      ),
+    );
+  };
+
   return (
     <PageContainer
       title="Sheet"
@@ -415,6 +436,69 @@ export default function Demo() {
             </Flex>
           </CardContent>
         </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Non-modal sheet: the list behind stays editable</CardTitle>
+            <CardDescription>
+              modal=&#123;false&#125; on Sheet renders a non-modal panel, a pattern WAI-ARIA APG
+              allows. The page behind keeps working: no scrim, no scroll lock, nothing hidden from
+              assistive tech, and a press outside does not close the panel. Open the order summary
+              (side=&quot;left&quot;, so the quantity controls stay uncovered), then change a quantity
+              below. The total inside the panel follows. Focus moves into the
+              panel on open, Tab can leave it, Escape closes it while focus is inside, and focus
+              returns to the trigger.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              {lines.map((line) => (
+                <Flex key={line.id} direction="row" align="center" justify="between" gap="sm">
+                  <Text>{line.name}</Text>
+                  <Flex direction="row" align="center" gap="sm">
+                    <Button
+                      variant="outline"
+                      size="sm"
+                      aria-label={`${line.name}を減らす`}
+                      disabled={line.quantity === 0}
+                      onClick={() => changeQuantity(line.id, -1)}
+                    >
+                      −
+                    </Button>
+                    <Text aria-live="polite">{line.quantity}</Text>
+                    <Button
+                      variant="outline"
+                      size="sm"
+                      aria-label={`${line.name}を増やす`}
+                      onClick={() => changeQuantity(line.id, 1)}
+                    >
+                      ＋
+                    </Button>
+                  </Flex>
+                </Flex>
+              ))}
+              <Sheet modal={false} open={summaryOpen} onOpenChange={setSummaryOpen}>
+                <SheetTrigger asChild>
+                  <Button variant="outline" size="sm">
+                    注文サマリー
+                  </Button>
+                </SheetTrigger>
+                <SheetContent side="left" width={360}>
+                  <SheetHeader title="注文サマリー" subtitle="明細は背面で編集を続けられます。" />
+                  <SheetBody>
+                    <Flex direction="row" justify="between">
+                      <Text tone="muted">合計</Text>
+                      <Text>{yen.format(total)}</Text>
+                    </Flex>
+                  </SheetBody>
+                  <SheetFooter>
+                    <Button onClick={() => setSummaryOpen(false)}>完了</Button>
+                  </SheetFooter>
+                </SheetContent>
+              </Sheet>
+            </Flex>
+          </CardContent>
+        </Card>
       </Flex>
     </PageContainer>
   );

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "27.0.0",
-  "godxUiMcp": "27.0.0",
+  "version": "27.1.0",
+  "godxUiMcp": "27.1.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -460,6 +460,7 @@
     "input-otp": "^1.5.0",
     "lucide-react": "^1.37.0",
     "qrcode.react": "4.2.0",
+    "react-aria": "3.52.1",
     "react-aria-components": "^1.21.1",
     "react-day-picker": "^10.0.1",
     "react-resizable-panels": "^4.12.3",