@entifix/react-controls 0.19.0 → 0.20.1

package/dist/ui/organisms/entity-form/entity-form.js

@@ -1,22 +1,26 @@
 'use client';
+import { _ as _extends } from "@swc/helpers/_/_extends";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { cloneEntityDraft, describeEntityColumns, readDraftString, readLocalizedDraft, readRowDrafts } from '@entifix/core';
-import { useId, useState } from 'react';
-import { useErrorMessage, useLocalizedDescriptors, useT, useTranslateKey } from '../../../i18n/index.js';
-import { OVERFLOW_GLYPH, renderAnchor, useCasesForSurface } from '../../actions/index.js';
+import { cloneEntityDraft, describeEntityColumns, extractMetaEntity, readDraftString, readLocalizedDraft, readRowDrafts } from '@entifix/core';
+import { useEffect, useId, useRef, useState } from 'react';
+import { useEntityNoun, useLocalizedDescriptors, useT, useTranslateKey } from '../../../i18n/index.js';
+import { renderAnchor, useCasesForSurface } from '../../actions/index.js';
+import { useVerbInvoker } from '../../actions/use-verb-invoker.js';
 import { Button, button } from '../../atoms/button/index.js';
 import { CellValue } from '../../atoms/cell-value/index.js';
 import { FieldControl } from '../../atoms/field-control/index.js';
 import { LocalizedFieldControl } from '../../atoms/localized-field-control/index.js';
 import { Skeleton } from '../../atoms/skeleton/index.js';
 import { Text } from '../../atoms/text/index.js';
+import { ActionBar, itemsForUseCases } from '../../molecules/action-bar/index.js';
 import { Card } from '../../molecules/card/index.js';
-import { ConfirmDialog } from '../../molecules/confirm-dialog/index.js';
 import { EntityLinkInput } from '../../molecules/entity-link-input/index.js';
 import { LoadingBoundary } from '../../molecules/loading-boundary/index.js';
-import { Menu } from '../../molecules/menu/index.js';
+import { RegionState } from '../../molecules/region-state/index.js';
 import { Stack } from '../../molecules/stack/index.js';
 import { cn } from '../../utils/cn.js';
+import { useLiveUpdates } from '../../utils/live-updates.js';
+import { useFocusOnArrival } from '../../utils/use-focus-on-arrival.js';
 import { EntityDetailGrid } from '../entity-detail-grid/index.js';
 import { readEntityFormFields } from './entity-form-slots.js';
 import { resolveEntityFormFields } from './use-entity-form-fields.js';
@@ -59,14 +63,10 @@ import { resolveEntityFormFields } from './use-entity-form-fields.js';
  *
  * It is presentational: the draft, its errors and the save/delete actions are
  * all props, so the same form hosts on a plain route and inside a workspace tab.
- */ /**
- * How many verbs a surface shows before the rest fold into an overflow menu.
- *
- * Four, because that is roughly what fits beside a title at a laptop width
- * without the row wrapping — the same number Fiori's object-page header settles
- * on. It is a layout constant, not a policy: raising it does not grant anything.
- */ const VISIBLE_ACTION_LIMIT = 4;
-export function EntityForm({ entityConstructor, entity, values, onFieldChange, linkSources, onLinkChange, mode: modeProp, defaultMode, onModeChange, errors, formError, onSubmit, onDelete, embedded = false, isLoading = false, skeleton = true, isSaving = false, isPending = false, isDeleting = false, error, backHref, renderLink = renderAnchor, title, metadata, isMetadataLoading = false, onUseCase, onClone, children }) {
+ */ /** The key the built-in Delete runs under, which no declared verb can take. */ const DELETE_KEY = '$delete';
+/** Save, from anywhere in the form — the caret in a field included. */ const SAVE_SHORTCUT = 'Mod+S';
+/** The footer's declared primary, when it is not Save. */ const PRIMARY_SHORTCUT = 'Mod+Enter';
+export function EntityForm({ entityConstructor, entity, values, onFieldChange, linkSources, onLinkChange, mode: modeProp, defaultMode, onModeChange, errors, formError, onSubmit, onDelete, deletePolicy = 'confirm', recordLabel: hostRecordLabel, embedded = false, isLoading = false, skeleton = true, isSaving = false, isPending = false, isDeleting = false, error, onRetry, backHref, renderLink = renderAnchor, title, metadata, isMetadataLoading = false, onUseCase, onClone, children }) {
     const formId = useId();
     const slots = readEntityFormFields(children);
     // The *field* descriptors, which stay local and synchronous — a column is a
@@ -105,7 +105,12 @@ export function EntityForm({ entityConstructor, entity, values, onFieldChange, l
     };
     const t = useT();
     const translateKey = useTranslateKey();
-    const errorMessage = useErrorMessage();
+    const entityNoun = useEntityNoun();
+    const live = useLiveUpdates();
+    // A form reached by a write — saved, handed off by a wizard — takes focus on
+    // its heading, so it never rests on `<body>` (ADR 0028).
+    const heading = useRef(null);
+    useFocusOnArrival(heading);
     const busy = isSaving || isPending || isDeleting;
     // A draft restored from storage holds relation ids and no instances, so every
     // picker is resolving its target for a moment after mount. Saving inside that
@@ -141,214 +146,285 @@ export function EntityForm({ entityConstructor, entity, values, onFieldChange, l
     const declaredFooterUseCases = useCasesForSurface('form-footer', metadata == null ? void 0 : metadata.useCases);
     const headerUseCases = onUseCase ? declaredHeaderUseCases : [];
     const footerUseCases = onUseCase ? declaredFooterUseCases : [];
-    // A descriptor carrying `confirm` must be asked about before it fires;
-    // `revoke-sessions` ends every session a user holds. The state holds the
-    // confirmation itself rather than the descriptor, so the dialog cannot be
-    // opened for a verb that never asked for one.
-    const [pending, setPending] = useState(undefined);
-    const invoke = (descriptor)=>{
-        const confirm = descriptor.confirm;
-        if (confirm) {
-            setPending({
-                key: descriptor.key,
-                labelKey: descriptor.labelKey,
-                confirm
-            });
+    // Every verb on the form, and its own Delete, goes through one invoker: a
+    // destructive verb asks, asks for the name, or runs and offers Undo, as it
+    // declared — `revoke-sessions` ends every session a user holds.
+    const verbs = useVerbInvoker({
+        run: (key)=>key === DELETE_KEY ? onDelete == null ? void 0 : onDelete() : onUseCase == null ? void 0 : onUseCase(key),
+        busy,
+        served: metadata == null ? void 0 : metadata.useCases
+    });
+    // What a confirmation names: the record as the reader knows it — its first
+    // filled-in field — or, for a record with nothing filled in, the entity.
+    const metaEntity = extractMetaEntity(entityConstructor);
+    const named = fields.find((field)=>field.type !== 'id' && readDraftString(draft, field.name) !== '');
+    const recordLabel = hostRecordLabel != null ? hostRecordLabel : named === undefined ? entityNoun(metaEntity) : readDraftString(draft, named.name);
+    const invoke = (descriptor)=>verbs.invoke({
+            descriptor,
+            target: undefined,
+            object: recordLabel,
+            count: 1
+        });
+    const requestDelete = ()=>{
+        // Undo is the host's to offer: only it can put a deleted record back.
+        if (deletePolicy === 'undo') {
+            onDelete == null ? void 0 : onDelete();
             return;
         }
-        onUseCase == null ? void 0 : onUseCase(descriptor.key);
-    };
-    const useCaseButton = (descriptor)=>{
-        var _descriptor_confirm;
-        return /*#__PURE__*/ _jsx(Button, {
-            type: "button",
-            variant: ((_descriptor_confirm = descriptor.confirm) == null ? void 0 : _descriptor_confirm.tone) === 'destructive' ? 'destructive' : 'secondary',
-            size: descriptor.placement === 'context-independent' ? 'sm' : 'md',
-            disabled: busy,
-            onClick: ()=>invoke(descriptor),
-            children: translateKey(descriptor.labelKey)
-        }, descriptor.key);
-    };
-    const useCaseMenuItem = (descriptor)=>{
-        var _descriptor_confirm;
-        return /*#__PURE__*/ _jsx(Menu.Item, {
-            tone: ((_descriptor_confirm = descriptor.confirm) == null ? void 0 : _descriptor_confirm.tone) === 'destructive' ? 'destructive' : 'neutral',
-            disabled: busy,
-            onClick: ()=>invoke(descriptor),
-            children: translateKey(descriptor.labelKey)
-        }, descriptor.key);
+        invoke({
+            key: DELETE_KEY,
+            binding: 'entity',
+            placement: 'determining',
+            labelKey: 'controls:form.delete',
+            confirm: {
+                tone: 'destructive',
+                messageKey: 'controls:confirm.deleteMessage'
+            },
+            reversible: deletePolicy
+        });
     };
+    const headerItems = itemsForUseCases(headerUseCases, translateKey, invoke, busy);
+    const footerItems = itemsForUseCases(footerUseCases, translateKey, invoke, busy);
     /**
-   * Four actions fit a row; twelve do not.
-   *
-   * So a surface renders its first {@link VISIBLE_ACTION_LIMIT} verbs as
-   * buttons and folds the rest behind one overflow trigger, in **declaration
-   * order** — the entity's author decided which verbs matter by writing them
-   * first, and a rule that sorted by anything else (alphabetical, destructive
-   * last) would reorder the row every time a verb was added.
-   *
-   * The split is only applied when there is something to fold: a fifth action
-   * is the point at which a menu is cheaper than a wider row, and a menu
-   * holding one entry is strictly worse than the button it replaced.
-   */ const withOverflow = (descriptors)=>{
-        if (descriptors.length <= VISIBLE_ACTION_LIMIT) {
-            return descriptors.map(useCaseButton);
-        }
-        const visible = descriptors.slice(0, VISIBLE_ACTION_LIMIT);
-        const folded = descriptors.slice(VISIBLE_ACTION_LIMIT);
-        return [
-            ...visible.map(useCaseButton),
-            /*#__PURE__*/ _jsxs(Menu, {
-                children: [
-                    /*#__PURE__*/ _jsx(Menu.Trigger, {
-                        "aria-label": t('form.moreActions'),
-                        children: OVERFLOW_GLYPH
-                    }),
-                    /*#__PURE__*/ _jsx(Menu.Items, {
-                        children: folded.map(useCaseMenuItem)
-                    })
-                ]
-            }, "overflow")
-        ];
+   * A save attempt. Counted, so a refused one moves focus to the error summary
+   * once — not again on every keystroke that leaves an error standing.
+   */ const [attempt, setAttempt] = useState(0);
+    const save = ()=>{
+        setAttempt((current)=>current + 1);
+        onSubmit == null ? void 0 : onSubmit(draft);
     };
-    return /*#__PURE__*/ _jsxs(Card, {
+    const summary = useRef(null);
+    const summaryId = useId();
+    const invalid = editing ? fields.filter((field)=>(errors == null ? void 0 : errors[field.name]) !== undefined) : [];
+    const focusedAttempt = useRef(0);
+    useEffect(()=>{
+        var _summary_current;
+        if (attempt === focusedAttempt.current || invalid.length === 0) return;
+        focusedAttempt.current = attempt;
+        (_summary_current = summary.current) == null ? void 0 : _summary_current.focus();
+    }, [
+        attempt,
+        invalid.length
+    ]);
+    // Save is the footer's primary unless the entity declared one of its own — a
+    // determining "Publish" is what that page is for, and Save steps aside.
+    const declaresFooterPrimary = footerItems.some((item)=>item.emphasis === 'primary');
+    const footerActions = [
+        ...may('write') ? [
+            {
+                key: 'save',
+                // A pending write waits on the push stream; while that is down
+                // it says so, rather than waiting without a word.
+                label: isPending ? t(live.connection === 'open' ? 'form.pending' : 'live.waiting') : isSaving ? t('form.saving') : t('form.save'),
+                emphasis: declaresFooterPrimary ? 'default' : 'primary',
+                disabled: busy || resolvingLinks,
+                submit: true,
+                shortcut: SAVE_SHORTCUT,
+                onSelect: save
+            }
+        ] : [],
+        // The page's main act answers Mod+Enter, unless it declared its own.
+        ...footerItems.map((item)=>item.emphasis === 'primary' && item.shortcut === undefined ? _extends({}, item, {
+                shortcut: PRIMARY_SHORTCUT
+            }) : item),
+        // Clone is the CRUD triple's, not a declared verb's: every entity can be
+        // copied, so giving it a `@useCase()` would mean declaring the same verb on
+        // all 28 of them. It needs `write`, because what it produces is a create.
+        ...onClone && entity && may('write') ? [
+            {
+                key: 'clone',
+                label: t('form.clone'),
+                disabled: busy,
+                onSelect: ()=>onClone(cloneEntityDraft(entityConstructor, draft))
+            }
+        ] : [],
+        ...onDelete && may('delete') ? [
+            {
+                key: 'delete',
+                label: isDeleting ? t('form.deleting') : t('form.delete'),
+                destructive: true,
+                disabled: busy,
+                onSelect: requestDelete
+            }
+        ] : []
+    ];
+    // A real form while editing, so Enter in a field saves; an embedded one
+    // belongs to its host's flow, and a caller who may not write has no Save.
+    const asForm = editing && !embedded && may('write');
+    const rows = fields.map((field)=>/*#__PURE__*/ _jsx(FieldRow, {
+            field: field,
+            entity: entity,
+            draft: draft,
+            value: readDraftString(draft, field.name),
+            editing: editing,
+            error: editing ? errors == null ? void 0 : errors[field.name] : undefined,
+            setField: setField,
+            linkSource: linkSources == null ? void 0 : linkSources[field.name],
+            onLinkChange: onLinkChange,
+            id: `${formId}-${field.name}`
+        }, field.name));
+    const body = /*#__PURE__*/ _jsxs(Stack, {
+        gap: "s",
         children: [
-            /*#__PURE__*/ _jsxs(Stack, {
-                gap: "s",
+            !embedded && /*#__PURE__*/ _jsxs(Stack, {
+                direction: "row",
+                gap: "xs",
+                align: "center",
                 children: [
-                    !embedded && /*#__PURE__*/ _jsxs(Stack, {
-                        direction: "row",
-                        gap: "xs",
-                        align: "center",
-                        children: [
-                            /*#__PURE__*/ _jsx(Text, {
-                                as: "h2",
-                                step: 1,
-                                weight: "semibold",
-                                children: title != null ? title : entity || isLoading ? t('form.details') : t('form.new')
-                            }),
-                            modeProp === undefined && entity && /*#__PURE__*/ _jsx(Button, {
-                                type: "button",
-                                variant: "ghost",
-                                size: "sm",
-                                onClick: toggleMode,
-                                children: editing ? t('form.view') : t('form.edit')
-                            }),
-                            /*#__PURE__*/ _jsx(LoadingBoundary, {
-                                isLoading: isMetadataLoading,
-                                lines: 0,
-                                children: /*#__PURE__*/ _jsxs(_Fragment, {
-                                    children: [
-                                        withOverflow(headerUseCases),
-                                        slots.headerActions
-                                    ]
-                                })
-                            })
-                        ]
+                    /*#__PURE__*/ _jsx(Text, {
+                        as: "h2",
+                        ref: heading,
+                        tabIndex: -1,
+                        step: 1,
+                        weight: "semibold",
+                        className: "focus-ring",
+                        children: title != null ? title : entity || isLoading ? t('form.details') : t('form.new')
                     }),
-                    /*#__PURE__*/ _jsx("span", {
-                        role: "status",
-                        "aria-live": "polite",
-                        className: "sr-only",
-                        children: isLoading ? t('form.loading') : ''
+                    modeProp === undefined && entity && /*#__PURE__*/ _jsx(Button, {
+                        type: "button",
+                        variant: "ghost",
+                        size: "sm",
+                        onClick: toggleMode,
+                        children: editing ? t('form.view') : t('form.edit')
                     }),
-                    error && /*#__PURE__*/ _jsx("p", {
-                        role: "alert",
-                        "data-testid": "entity-form-error",
-                        className: "rounded-sm border border-danger bg-danger-subtle px-s py-2xs text-step-sm text-danger",
-                        children: errorMessage(error)
-                    }),
-                    showSkeleton ? customSkeleton != null ? customSkeleton : fields.map((field)=>/*#__PURE__*/ _jsxs(Stack, {
-                            gap: "3xs",
+                    /*#__PURE__*/ _jsx(LoadingBoundary, {
+                        isLoading: isMetadataLoading,
+                        lines: 0,
+                        children: /*#__PURE__*/ _jsxs(_Fragment, {
                             children: [
-                                /*#__PURE__*/ _jsx(Skeleton, {
-                                    shape: "line",
-                                    className: "w-24"
+                                headerItems.length > 0 && /*#__PURE__*/ _jsx(ActionBar, {
+                                    surface: "form-header",
+                                    items: headerItems
                                 }),
-                                /*#__PURE__*/ _jsx(Skeleton, {
-                                    className: "h-9 w-full"
-                                })
+                                slots.headerActions
                             ]
-                        }, field.name)) : fields.map((field)=>/*#__PURE__*/ _jsx(FieldRow, {
-                            field: field,
-                            entity: entity,
-                            draft: draft,
-                            value: readDraftString(draft, field.name),
-                            editing: editing,
-                            error: editing ? errors == null ? void 0 : errors[field.name] : undefined,
-                            setField: setField,
-                            linkSource: linkSources == null ? void 0 : linkSources[field.name],
-                            onLinkChange: onLinkChange,
-                            id: `${formId}-${field.name}`
-                        }, field.name)),
-                    ownedCollections.map((field)=>/*#__PURE__*/ _jsx(EntityDetailGrid, {
-                            descriptor: field,
-                            rows: readRowDrafts(draft[field.name]),
-                            onRowsChange: (rows)=>setField(field.name, rows),
-                            errors: editing ? errors : undefined,
-                            editing: editing,
-                            isLoading: isLoading,
-                            skeleton: skeleton
-                        }, field.name)),
-                    editing && formError && /*#__PURE__*/ _jsx("span", {
-                        role: "alert",
-                        className: "text-step-sm text-danger",
-                        children: formError
+                        })
+                    })
+                ]
+            }),
+            /*#__PURE__*/ _jsx("span", {
+                role: "status",
+                "aria-live": "polite",
+                className: "sr-only",
+                children: isLoading ? t('form.loading') : ''
+            }),
+            /*#__PURE__*/ _jsx(RegionState, {
+                plural: entityNoun(metaEntity, 'plural'),
+                error: error,
+                onRetry: onRetry,
+                // Only a load that can be retried leaves an out-of-date record; a
+                // failed save leaves what the reader typed, which is current.
+                hasStaleData: entity !== undefined && onRetry !== undefined
+            }),
+            invalid.length > 0 && /*#__PURE__*/ _jsxs("div", {
+                ref: summary,
+                tabIndex: -1,
+                role: "alert",
+                "aria-labelledby": summaryId,
+                "data-testid": "entity-form-error-summary",
+                className: "rounded-lg border-l-4 border-danger bg-danger-subtle px-s py-xs text-step-sm text-content focus-ring",
+                children: [
+                    /*#__PURE__*/ _jsx("p", {
+                        id: summaryId,
+                        className: "m-0 font-semibold",
+                        children: t('form.errorSummary', {
+                            count: invalid.length
+                        })
                     }),
-                    editing && !embedded && /*#__PURE__*/ _jsxs(Stack, {
-                        direction: "row",
-                        gap: "xs",
-                        children: [
-                            may('write') && /*#__PURE__*/ _jsx(Button, {
-                                type: "button",
-                                onClick: ()=>onSubmit == null ? void 0 : onSubmit(draft),
-                                disabled: busy || resolvingLinks,
-                                children: isPending ? t('form.pending') : isSaving ? t('form.saving') : t('form.save')
-                            }),
-                            onDelete && may('delete') && /*#__PURE__*/ _jsx(Button, {
-                                type: "button",
-                                variant: "secondary",
-                                onClick: onDelete,
-                                disabled: busy,
-                                children: isDeleting ? t('form.deleting') : t('form.delete')
-                            }),
-                            withOverflow(footerUseCases),
-                            onClone && entity && may('write') && /*#__PURE__*/ _jsx(Button, {
-                                type: "button",
-                                variant: "secondary",
-                                disabled: busy,
-                                onClick: ()=>onClone(cloneEntityDraft(entityConstructor, draft)),
-                                children: t('form.clone')
-                            }),
-                            slots.footerActions,
-                            backHref && renderLink({
-                                href: backHref,
-                                className: cn(button({
-                                    variant: 'ghost'
-                                }), busy && 'pointer-events-none opacity-50'),
-                                children: t('form.back'),
-                                intent: {
-                                    kind: 'back'
-                                }
-                            })
-                        ]
+                    /*#__PURE__*/ _jsx("ul", {
+                        className: "m-0 ps-s",
+                        children: invalid.map((field)=>/*#__PURE__*/ _jsx("li", {
+                                children: /*#__PURE__*/ _jsx("a", {
+                                    href: `#${formId}-${field.name}`,
+                                    // The content colour: primary on the danger surface misses
+                                    // 4.5:1.
+                                    className: "font-medium text-content underline underline-offset-2 focus-ring",
+                                    onClick: (event)=>{
+                                        var _document_getElementById;
+                                        event.preventDefault();
+                                        (_document_getElementById = document.getElementById(`${formId}-${field.name}`)) == null ? void 0 : _document_getElementById.focus();
+                                    },
+                                    children: errors == null ? void 0 : errors[field.name]
+                                })
+                            }, field.name))
+                    })
+                ]
+            }),
+            editing && fields.some((field)=>field.required && !field.readonly) && /*#__PURE__*/ _jsx(Text, {
+                step: -1,
+                tone: "muted",
+                children: t('form.requiredHint')
+            }),
+            showSkeleton ? customSkeleton != null ? customSkeleton : fields.map((field)=>/*#__PURE__*/ _jsxs(Stack, {
+                    gap: "3xs",
+                    children: [
+                        /*#__PURE__*/ _jsx(Skeleton, {
+                            shape: "line",
+                            className: "w-24"
+                        }),
+                        /*#__PURE__*/ _jsx(Skeleton, {
+                            className: "h-9 w-full"
+                        })
+                    ]
+                }, field.name)) : editing ? rows : // when there is no control, and a term and its value is what
+            // the pair is.
+            rows.length > 0 && /*#__PURE__*/ _jsx("dl", {
+                className: "m-0 flex flex-col gap-s",
+                children: rows
+            }),
+            ownedCollections.map((field)=>/*#__PURE__*/ _jsx(EntityDetailGrid, {
+                    descriptor: field,
+                    rows: readRowDrafts(draft[field.name]),
+                    onRowsChange: (rows)=>setField(field.name, rows),
+                    errors: editing ? errors : undefined,
+                    editing: editing,
+                    isLoading: isLoading,
+                    skeleton: skeleton
+                }, field.name)),
+            editing && formError && /*#__PURE__*/ _jsx("span", {
+                role: "alert",
+                className: "text-step-sm text-danger",
+                children: formError
+            }),
+            editing && !embedded && /*#__PURE__*/ _jsxs(Stack, {
+                direction: "row",
+                gap: "xs",
+                align: "center",
+                children: [
+                    /*#__PURE__*/ _jsx(ActionBar, {
+                        surface: "form-footer",
+                        size: "md",
+                        items: footerActions
                     }),
-                    slots.rest
+                    slots.footerActions,
+                    backHref && renderLink({
+                        href: backHref,
+                        className: cn(button({
+                            variant: 'ghost'
+                        }), busy && 'pointer-events-none opacity-50'),
+                        children: t('form.back'),
+                        intent: {
+                            kind: 'back'
+                        }
+                    })
                 ]
             }),
-            pending && /*#__PURE__*/ _jsx(ConfirmDialog, {
-                open: true,
-                tone: pending.confirm.tone,
-                title: translateKey(pending.labelKey),
-                message: translateKey(pending.confirm.messageKey),
-                busy: busy,
-                onCancel: ()=>setPending(undefined),
-                onConfirm: ()=>{
-                    const key = pending.key;
-                    setPending(undefined);
-                    onUseCase == null ? void 0 : onUseCase(key);
-                }
-            })
+            slots.rest
+        ]
+    });
+    return /*#__PURE__*/ _jsxs(Card, {
+        children: [
+            asForm ? /*#__PURE__*/ _jsx("form", {
+                noValidate: true,
+                // Enter submits through Save, the form's default button, which is
+                // disabled while a save is in flight — so a busy form stays put.
+                onSubmit: (event)=>{
+                    event.preventDefault();
+                    save();
+                },
+                children: body
+            }) : body,
+            verbs.dialog
         ]
     });
 }
@@ -421,6 +497,8 @@ linkSources) {
  * The source branch sits above the `virtual || isRelation` fallback and below
  * `field.render`, which is what lets a slot still override a picked field.
  */ function FieldRow({ field, entity, draft, value, editing, error, setField, linkSource, onLinkChange, id }) {
+    const t = useT();
+    const errorId = `${id}-error`;
     const readNode = field.readRender ? field.readRender(entity) : /*#__PURE__*/ _jsx(CellValue, {
         value: entity ? entity[field.name] : undefined,
         descriptor: field,
@@ -475,21 +553,51 @@ linkSources) {
             value: value,
             onChange: (next)=>setField(field.name, next),
             id: id,
-            record: draft
+            record: draft,
+            "aria-invalid": error !== undefined || undefined,
+            "aria-describedby": error === undefined ? undefined : errorId,
+            "aria-required": field.required || undefined
         });
     }
-    const ownsLabel = editing && field.type === 'boolean' && !field.render && !field.virtual;
-    return /*#__PURE__*/ _jsxs(Stack, {
-        gap: "3xs",
+    if (!editing) return /*#__PURE__*/ _jsxs("div", {
+        className: "flex flex-col gap-3xs",
         children: [
-            !ownsLabel && /*#__PURE__*/ _jsx("label", {
-                htmlFor: id,
+            /*#__PURE__*/ _jsx("dt", {
                 className: "text-step-sm text-content-muted",
                 children: field.label
             }),
+            /*#__PURE__*/ _jsx("dd", {
+                className: "m-0",
+                children: control
+            })
+        ]
+    });
+    const ownsLabel = field.type === 'boolean' && !field.render && !field.virtual;
+    // Marked before anyone submits, not discovered after.
+    const marked = field.required && !field.readonly;
+    return /*#__PURE__*/ _jsxs(Stack, {
+        gap: "3xs",
+        children: [
+            !ownsLabel && // The marker sits beside the label, not in it: the name stays the
+            // field's own, and `aria-required` is what says it to a reader.
+            /*#__PURE__*/ _jsxs("span", {
+                className: "flex items-baseline gap-3xs",
+                children: [
+                    /*#__PURE__*/ _jsx("label", {
+                        htmlFor: id,
+                        className: "text-step-sm text-content-muted",
+                        children: field.label
+                    }),
+                    marked && /*#__PURE__*/ _jsx("span", {
+                        "aria-hidden": "true",
+                        className: "text-step-sm text-danger",
+                        children: t('form.requiredMarker')
+                    })
+                ]
+            }),
             control,
             error && /*#__PURE__*/ _jsx("span", {
-                role: "alert",
+                id: errorId,
                 className: "text-step-sm text-danger",
                 children: error
             })