@mohasinac/appkit 4.58.0 → 4.60.0

package/dist/ui/forms/AddAnotherToggle.js

@@ -0,0 +1,56 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * "Create & add another" — the toggle, and the submit label that follows it.
+ *
+ * Entering a batch of similar records is the one thing every create form in
+ * this app is bad at: save, land on a detail page, navigate back, re-pick the
+ * store, re-pick the category, re-pick the listing type. Four of those five
+ * steps are the same every time.
+ *
+ * 🛑 THE TOGGLE RENDERS NOTHING UNLESS THE FORM OPTED IN, and that is the
+ * point rather than a nicety. `FormShell` does not own the draft, so it cannot
+ * know what a fresh one looks like or which fields are sticky — only the
+ * caller's submit handler can keep this promise. A checkbox on all ~59 editors
+ * when one honours it is a control that does nothing on 58 of them, which is
+ * the defect shape this codebase keeps paying for: a declaration with no
+ * reader.
+ *
+ * So: `useFormShellState(schema, nav, { allowAddAnother: true })` offers it,
+ * the handler reads `addAnother`, and `audit-add-another-honoured` checks that
+ * whoever offers it also reads it.
+ */
+import { useContext } from "react";
+import { FormShellContext } from "./FormShell.js";
+import { FieldCheckbox } from "./FieldCheckbox.js";
+export function AddAnotherToggle({ noun, isCreate = true, }) {
+    const ctx = useContext(FormShellContext);
+    /*
+     * 🛑 `useContext` DIRECTLY, not `useFormShell()`, which throws without a
+     * provider. A toggle that crashes the form it is decorating is worse than
+     * one that renders nothing, and this is library code adjusting to its
+     * surroundings (Root Cause #20 — no provider must fail CLOSED, not loudly).
+     */
+    if (!ctx?.addAnotherEnabled)
+        return null;
+    /*
+     * 🛑 Hidden on EDIT. "Add another" after changing an existing record would
+     * have to mean "save this, then start a new one", which is a different and
+     * surprising action — and the sticky-field reasoning does not apply, because
+     * nobody edits a batch of records by starting from the last one they fixed.
+     */
+    if (!isCreate)
+        return null;
+    return (_jsx(FieldCheckbox, { name: "addAnother", label: noun ? `Create & add another ${noun}` : "Create & add another", hint: "Stay on this form after saving, keeping the store, category and type.", checked: ctx.addAnother, onChange: (next) => ctx.setAddAnother(next) }));
+}
+/**
+ * The submit button's label, given the toggle.
+ *
+ * 🛑 A SEPARATE HELPER BECAUSE THE LABEL MUST CHANGE. A button that says
+ * "Create listing" and then does not navigate has lied about what it did, and
+ * the user's next move is to press it again — which creates a duplicate. The
+ * label is the only thing telling them the destination changed.
+ */
+export function addAnotherSubmitLabel(base, addAnother) {
+    return addAnother ? `${base} & add another` : base;
+}

package/dist/ui/forms/ColorPickerField.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useContext } from "react";
+import { useContext, useId } from "react";
 import { FormShellContext } from "./FormShell.js";
 import { Label, Text, Span } from "../components/Typography.js";
 const SWATCH_WIDTH_MAP = {
@@ -23,7 +23,20 @@ export function ColorPickerField({ name, label, hint, required, swatchWidth = "f
     const error = errorProp ?? contextError;
     const touched = ctx?.touched[name];
     const showError = !!error && (touched != null ? touched : true);
-    const inputId = `field-${name}`;
+    const reactId = useId();
+    /*
+     * 🛑 UNIQUE PER INSTANCE. This was `field-${name}`, so two fields sharing a
+     * name on one page produced two elements with the SAME id — `/auth/login`
+     * shipped two `id="field-email"` (the sign-in form and the footer
+     * newsletter).
+     *
+     * That is not cosmetic. `htmlFor` resolves to the FIRST element with the
+     * id, so the second field's label points at the first field's input: the
+     * label is present in the markup and the input has no accessible name, which
+     * is what an accessibility pass reports as an unlabelled field. Clicking the
+     * second label also focuses the first input.
+     */
+    const inputId = `field-${name}-${reactId}`;
     const errorId = `${inputId}-error`;
     function handleBlur(e) {
         ctx?.setFieldTouched(name);

package/dist/ui/forms/FieldCheckbox.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useContext } from "react";
+import { useContext, useId } from "react";
 import { FormShellContext } from "./FormShell.js";
 import { Checkbox } from "../components/Checkbox.js";
 import { Text } from "../components/Typography.js";
@@ -10,7 +10,20 @@ export function FieldCheckbox({ name, label, hint, checked, onChange, onBlur, di
     const error = errorProp ?? contextError;
     const touched = ctx?.touched[name];
     const showError = !!error && (touched != null ? touched : true);
-    const inputId = `field-${name}`;
+    const reactId = useId();
+    /*
+     * 🛑 UNIQUE PER INSTANCE. This was `field-${name}`, so two fields sharing a
+     * name on one page produced two elements with the SAME id — `/auth/login`
+     * shipped two `id="field-email"` (the sign-in form and the footer
+     * newsletter).
+     *
+     * That is not cosmetic. `htmlFor` resolves to the FIRST element with the
+     * id, so the second field's label points at the first field's input: the
+     * label is present in the markup and the input has no accessible name, which
+     * is what an accessibility pass reports as an unlabelled field. Clicking the
+     * second label also focuses the first input.
+     */
+    const inputId = `field-${name}-${reactId}`;
     const errorId = `${inputId}-error`;
     function handleChange(e) {
         onChange?.(e.target.checked);

package/dist/ui/forms/FieldInput.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
+import { type LabelPlacement } from "./FieldLabel";
 export interface FieldInputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "onChange"> {
     name: string;
     label?: string;
@@ -7,5 +8,25 @@ export interface FieldInputProps extends Omit<React.InputHTMLAttributes<HTMLInpu
     onChange?: (value: string) => void;
     /** Override error — falls back to FormShell context error for this field */
     error?: string;
+    /**
+     * A ref to the inner `<input>`, for the cases that need programmatic focus:
+     * a scan station that must re-focus after every scan, an error summary that
+     * jumps to the offending field, a drawer that focuses its first control.
+     *
+     * 🛑 NAMED `inputRef`, not a `forwardRef` on the component. This renders a
+     * wrapper `<div>`, a `<Label>`, the `<input>` and an error `<Text>` — so a
+     * bare "the ref" has no single obvious target, and the next reader could
+     * reasonably expect the wrapper. Being explicit about which element is the
+     * same lesson as `Select`'s `wrapperClassName` (Root Cause #29): when a
+     * primitive has an outer box and an inner control, a prop that does not say
+     * which one it means will eventually reach the wrong one.
+     */
+    inputRef?: React.Ref<HTMLInputElement>;
+    /**
+     * Override the section's label placement. Omit it — placement is a
+     * section-level decision (see `FieldLabel`), and a field that disagrees with
+     * its neighbours reads as broken rather than varied.
+     */
+    labelPlacement?: LabelPlacement;
 }
-export declare function FieldInput({ name, label, hint, required, onChange, error: errorProp, onBlur, className, ...inputProps }: FieldInputProps): React.JSX.Element;
+export declare function FieldInput({ name, label, hint, required, onChange, error: errorProp, onBlur, className, inputRef, labelPlacement, ...inputProps }: FieldInputProps): React.JSX.Element;

package/dist/ui/forms/FieldInput.js

@@ -1,16 +1,30 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useContext } from "react";
+import { useContext, useId } from "react";
 import { FormShellContext } from "./FormShell.js";
 import { Input } from "../components/Input.js";
-import { Label, Text, Span } from "../components/Typography.js";
-export function FieldInput({ name, label, hint, required, onChange, error: errorProp, onBlur, className, ...inputProps }) {
+import { Text } from "../components/Typography.js";
+import { FieldLabel } from "./FieldLabel.js";
+export function FieldInput({ name, label, hint, required, onChange, error: errorProp, onBlur, className, inputRef, labelPlacement, ...inputProps }) {
     const ctx = useContext(FormShellContext);
     const contextError = ctx?.errors[name];
     const error = errorProp ?? contextError;
     const touched = ctx?.touched[name];
     const showError = !!error && (touched != null ? touched : true);
-    const inputId = `field-${name}`;
+    const reactId = useId();
+    /*
+     * 🛑 UNIQUE PER INSTANCE. This was `field-${name}`, so two fields sharing a
+     * name on one page produced two elements with the SAME id — `/auth/login`
+     * shipped two `id="field-email"` (the sign-in form and the footer
+     * newsletter).
+     *
+     * That is not cosmetic. `htmlFor` resolves to the FIRST element with the
+     * id, so the second field's label points at the first field's input: the
+     * label is present in the markup and the input has no accessible name, which
+     * is what an accessibility pass reports as an unlabelled field. Clicking the
+     * second label also focuses the first input.
+     */
+    const inputId = `field-${name}-${reactId}`;
     const errorId = `${inputId}-error`;
     function handleBlur(e) {
         ctx?.setFieldTouched(name);
@@ -21,5 +35,5 @@ export function FieldInput({ name, label, hint, required, onChange, error: error
         if (showError)
             ctx?.clearFieldError(name);
     }
-    return (_jsxs("div", { className: ["appkit-form-field", className].filter(Boolean).join(" "), children: [label && (_jsxs(Label, { htmlFor: inputId, className: "appkit-form-field__label", children: [label, required && _jsx(Span, { className: "appkit-form-field__required", children: " *" })] })), _jsx(Input, { id: inputId, name: name, "aria-required": required || undefined, "aria-invalid": showError || undefined, "aria-describedby": showError ? errorId : undefined, onBlur: handleBlur, onChange: handleChange, ...inputProps }), !showError && hint && (_jsx(Text, { size: "sm", variant: "secondary", className: "appkit-form-field__hint", children: hint })), showError && (_jsx(Text, { id: errorId, size: "sm", variant: "error", className: "appkit-form-field__error", role: "alert", children: error }))] }));
+    return (_jsxs("div", { className: ["appkit-form-field", className].filter(Boolean).join(" "), children: [label && (_jsx(FieldLabel, { htmlFor: inputId, required: required, placement: labelPlacement, children: label })), _jsx(Input, { ref: inputRef, id: inputId, name: name, "aria-required": required || undefined, "aria-invalid": showError || undefined, "aria-describedby": showError ? errorId : undefined, onBlur: handleBlur, onChange: handleChange, ...inputProps }), !showError && hint && (_jsx(Text, { size: "sm", variant: "secondary", className: "appkit-form-field__hint", children: hint })), showError && (_jsx(Text, { id: errorId, size: "sm", variant: "error", className: "appkit-form-field__error", role: "alert", children: error }))] }));
 }

package/dist/ui/forms/FieldLabel.d.ts

@@ -0,0 +1,35 @@
+export type LabelPlacement = "above" | "inline" | "hidden";
+/**
+ * Set by a section, read by every field inside it.
+ *
+ * Defaults to `"above"` — the current behaviour of all four owners — so
+ * introducing this changes no existing markup. The concept is new; the output
+ * is not.
+ */
+export declare const LabelPlacementContext: import("react").Context<LabelPlacement>;
+export declare function useLabelPlacement(override?: LabelPlacement): LabelPlacement;
+export interface FieldLabelProps {
+    /**
+     * The `id` of the control this labels. The normal case.
+     *
+     * 🛑 OPTIONAL ONLY FOR THE `aria-labelledby` DIRECTION, and omitting it on a
+     * real input is how an unlabelled field is made. `htmlFor` associates with a
+     * LABELABLE element — `input`, `select`, `textarea`, `button`, `output`,
+     * `meter`, `progress` — and nothing else. A `contenteditable` div (the rich
+     * text editor) is not one, so there `htmlFor` points at nothing: the label
+     * looks correct to a human and the control has no accessible name.
+     *
+     * For those, give the LABEL an `id` and have the control carry
+     * `aria-labelledby` pointing back at it. Exactly one of `htmlFor` or `id`
+     * should be set.
+     */
+    htmlFor?: string;
+    /** This label's own id, for a control that points back via `aria-labelledby`. */
+    id?: string;
+    children: React.ReactNode;
+    required?: boolean;
+    /** Overrides the section's placement. Use only when this field differs. */
+    placement?: LabelPlacement;
+    className?: string;
+}
+export declare function FieldLabel({ htmlFor, id, children, required, placement, className, }: FieldLabelProps): import("react").JSX.Element;

package/dist/ui/forms/FieldLabel.js

@@ -0,0 +1,70 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The one owner of a form field's label.
+ *
+ * ── THE FOUR OWNERS THIS REPLACES ───────────────────────────────────────────
+ *
+ * `FieldInput`, `FieldSelect` and `FieldTextarea` each carried a BYTE-IDENTICAL
+ * copy of the same five lines, and `FormField` carried a fourth that had
+ * already drifted: its required marker is `>*<` where the other three are
+ * `> *<`, so the asterisk sits flush against the label text on ~40 screens and
+ * spaced on the rest. Nobody chose that. It is what four copies of five lines
+ * always become, and it is the smallest possible demonstration of why this
+ * file exists.
+ *
+ * A fifth family — `Input`, `Select`, `Textarea`, `Toggle`, `Radio`, `Slider`,
+ * `TagInput`, `DateInput`, `OtpInput` — each accept their own `label` prop and
+ * render it differently again. Those are NOT migrated here and should not be:
+ * see the note at the bottom on why a primitive keeps its own label.
+ *
+ * ── LABEL PLACEMENT ─────────────────────────────────────────────────────────
+ *
+ * 🛑 PLACEMENT IS A SECTION-LEVEL DECISION, NOT A PER-FIELD ONE. A form where
+ * one field labels above and its neighbour labels inline reads as broken
+ * rather than as varied, and the choice is about the density of a whole
+ * section — a 12-field address block wants inline, a 3-field settings panel
+ * wants above. So it comes from context, set once by `SectionDef`, and a field
+ * only overrides it when it genuinely differs from its neighbours.
+ *
+ * `"hidden"` is NOT "no label". It renders the label to assistive technology
+ * and hides it visually, which is the correct treatment for a field whose
+ * purpose is obvious from context (a search box with a magnifier, a quantity
+ * stepper in a table row). Passing no `label` at all is what produces an
+ * unlabelled field, and there are 392 of those — `"hidden"` is the fix for the
+ * subset that genuinely should not show one, not a way to silence the count.
+ */
+import { createContext, useContext } from "react";
+import { Label, Span } from "../components/Typography.js";
+/**
+ * Set by a section, read by every field inside it.
+ *
+ * Defaults to `"above"` — the current behaviour of all four owners — so
+ * introducing this changes no existing markup. The concept is new; the output
+ * is not.
+ */
+export const LabelPlacementContext = createContext("above");
+export function useLabelPlacement(override) {
+    const fromSection = useContext(LabelPlacementContext);
+    return override ?? fromSection;
+}
+/**
+ * 🛑 `sr-only`, not `display: none`, for the hidden placement.
+ *
+ * A `display: none` label is removed from the accessibility tree, so hiding a
+ * label that way produces exactly the unlabelled field it was meant to avoid —
+ * the screen reader announces "edit text" and the visual user sees a box with
+ * a placeholder. `sr-only` keeps it announced and off-screen, which is the
+ * whole distinction between "visually hidden" and "absent".
+ */
+const PLACEMENT_CLASS = {
+    above: "appkit-form-field__label",
+    inline: "appkit-form-field__label appkit-form-field__label--inline",
+    hidden: "sr-only",
+};
+export function FieldLabel({ htmlFor, id, children, required, placement, className = "", }) {
+    const resolved = useLabelPlacement(placement);
+    return (_jsxs(Label, { htmlFor: htmlFor, id: id, className: [PLACEMENT_CLASS[resolved], className]
+            .filter(Boolean)
+            .join(" "), children: [children, required && _jsx(Span, { className: "appkit-form-field__required", children: " *" })] }));
+}

package/dist/ui/forms/FieldSelect.d.ts

@@ -1,5 +1,6 @@
 import React from "react";
 import { type SelectOption } from "../components/Select";
+import { type LabelPlacement } from "./FieldLabel";
 export interface FieldSelectProps {
     name: string;
     label?: string;
@@ -14,5 +15,7 @@ export interface FieldSelectProps {
     /** Override error — falls back to FormShell context error for this field */
     error?: string;
     className?: string;
+    /** Override the section's label placement. Omit it — see `FieldLabel`. */
+    labelPlacement?: LabelPlacement;
 }
-export declare function FieldSelect({ name, label, hint, required, value, onChange, onBlur, options, disabled, placeholder, error: errorProp, className, }: FieldSelectProps): React.JSX.Element;
+export declare function FieldSelect({ name, label, hint, required, value, onChange, onBlur, options, disabled, placeholder, error: errorProp, className, labelPlacement, }: FieldSelectProps): React.JSX.Element;

package/dist/ui/forms/FieldSelect.js

@@ -1,16 +1,38 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useContext } from "react";
+import { useContext, useId } from "react";
 import { FormShellContext } from "./FormShell.js";
 import { Select } from "../components/Select.js";
-import { Label, Text, Span } from "../components/Typography.js";
-export function FieldSelect({ name, label, hint, required, value, onChange, onBlur, options, disabled, placeholder, error: errorProp, className, }) {
+import { Text } from "../components/Typography.js";
+import { FieldLabel } from "./FieldLabel.js";
+export function FieldSelect({ name, label, hint, required, value, onChange, onBlur, options, disabled, placeholder, error: errorProp, className, 
+/*
+ * 🛑 Declared on `FieldSelectProps` and never destructured, so line 77 read
+ * a free variable that does not exist — `TS2304: Cannot find name
+ * 'labelPlacement'`. A prop that is typed but not unpacked is the exact
+ * shape of the `schema: _schema` defect `audit-dead-underscore-prop` exists
+ * for, except here it did not even compile.
+ */
+labelPlacement, }) {
     const ctx = useContext(FormShellContext);
     const contextError = ctx?.errors[name];
     const error = errorProp ?? contextError;
     const touched = ctx?.touched[name];
     const showError = !!error && (touched != null ? touched : true);
-    const inputId = `field-${name}`;
+    const reactId = useId();
+    /*
+     * 🛑 UNIQUE PER INSTANCE. This was `field-${name}`, so two fields sharing a
+     * name on one page produced two elements with the SAME id — `/auth/login`
+     * shipped two `id="field-email"` (the sign-in form and the footer
+     * newsletter).
+     *
+     * That is not cosmetic. `htmlFor` resolves to the FIRST element with the
+     * id, so the second field's label points at the first field's input: the
+     * label is present in the markup and the input has no accessible name, which
+     * is what an accessibility pass reports as an unlabelled field. Clicking the
+     * second label also focuses the first input.
+     */
+    const inputId = `field-${name}-${reactId}`;
     const errorId = `${inputId}-error`;
     function handleBlur() {
         ctx?.setFieldTouched(name);
@@ -21,5 +43,5 @@ export function FieldSelect({ name, label, hint, required, value, onChange, onBl
         if (showError)
             ctx?.clearFieldError(name);
     }
-    return (_jsxs("div", { className: ["appkit-form-field", className].filter(Boolean).join(" "), children: [label && (_jsxs(Label, { htmlFor: inputId, className: "appkit-form-field__label", children: [label, required && _jsx(Span, { className: "appkit-form-field__required", children: " *" })] })), _jsx(Select, { id: inputId, name: name, value: value, onChange: handleChange, onBlur: handleBlur, options: options, disabled: disabled, placeholder: placeholder, "aria-required": required || undefined, "aria-invalid": showError || undefined, "aria-describedby": showError ? errorId : undefined }), !showError && hint && (_jsx(Text, { size: "sm", variant: "secondary", className: "appkit-form-field__hint", children: hint })), showError && (_jsx(Text, { id: errorId, size: "sm", variant: "error", className: "appkit-form-field__error", role: "alert", children: error }))] }));
+    return (_jsxs("div", { className: ["appkit-form-field", className].filter(Boolean).join(" "), children: [label && (_jsx(FieldLabel, { htmlFor: inputId, required: required, placement: labelPlacement, children: label })), _jsx(Select, { id: inputId, name: name, value: value, onChange: handleChange, onBlur: handleBlur, options: options, disabled: disabled, placeholder: placeholder, "aria-required": required || undefined, "aria-invalid": showError || undefined, "aria-describedby": showError ? errorId : undefined }), !showError && hint && (_jsx(Text, { size: "sm", variant: "secondary", className: "appkit-form-field__hint", children: hint })), showError && (_jsx(Text, { id: errorId, size: "sm", variant: "error", className: "appkit-form-field__error", role: "alert", children: error }))] }));
 }

package/dist/ui/forms/FieldTextarea.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
+import { type LabelPlacement } from "./FieldLabel";
 export interface FieldTextareaProps extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, "onChange"> {
     name: string;
     label?: string;
@@ -9,5 +10,7 @@ export interface FieldTextareaProps extends Omit<React.TextareaHTMLAttributes<HT
     error?: string;
     /** Show a `{n}/{maxLength}` counter when maxLength is set */
     showCharCount?: boolean;
+    /** Override the section's label placement. Omit it — see `FieldLabel`. */
+    labelPlacement?: LabelPlacement;
 }
-export declare function FieldTextarea({ name, label, hint, required, onChange, error: errorProp, onBlur, className, showCharCount, ...textareaProps }: FieldTextareaProps): React.JSX.Element;
+export declare function FieldTextarea({ name, label, hint, required, onChange, error: errorProp, onBlur, className, showCharCount, labelPlacement, ...textareaProps }: FieldTextareaProps): React.JSX.Element;

package/dist/ui/forms/FieldTextarea.js

@@ -1,16 +1,30 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useContext } from "react";
+import { useContext, useId } from "react";
 import { FormShellContext } from "./FormShell.js";
 import { Textarea } from "../components/Textarea.js";
-import { Label, Text, Span } from "../components/Typography.js";
-export function FieldTextarea({ name, label, hint, required, onChange, error: errorProp, onBlur, className, showCharCount, ...textareaProps }) {
+import { Text } from "../components/Typography.js";
+import { FieldLabel } from "./FieldLabel.js";
+export function FieldTextarea({ name, label, hint, required, onChange, error: errorProp, onBlur, className, showCharCount, labelPlacement, ...textareaProps }) {
     const ctx = useContext(FormShellContext);
     const contextError = ctx?.errors[name];
     const error = errorProp ?? contextError;
     const touched = ctx?.touched[name];
     const showError = !!error && (touched != null ? touched : true);
-    const fieldId = `field-${name}`;
+    const reactId = useId();
+    /*
+     * 🛑 UNIQUE PER INSTANCE. This was `field-${name}`, so two fields sharing a
+     * name on one page produced two elements with the SAME id — `/auth/login`
+     * shipped two `id="field-email"` (the sign-in form and the footer
+     * newsletter).
+     *
+     * That is not cosmetic. `htmlFor` resolves to the FIRST element with the
+     * id, so the second field's label points at the first field's input: the
+     * label is present in the markup and the input has no accessible name, which
+     * is what an accessibility pass reports as an unlabelled field. Clicking the
+     * second label also focuses the first input.
+     */
+    const fieldId = `field-${name}-${reactId}`;
     const errorId = `${fieldId}-error`;
     function handleBlur(e) {
         ctx?.setFieldTouched(name);
@@ -21,5 +35,8 @@ export function FieldTextarea({ name, label, hint, required, onChange, error: er
         if (showError)
             ctx?.clearFieldError(name);
     }
-    return (_jsxs("div", { className: ["appkit-form-field", className].filter(Boolean).join(" "), children: [label && (_jsxs(Label, { htmlFor: fieldId, className: "appkit-form-field__label", children: [label, required && _jsx(Span, { className: "appkit-form-field__required", children: " *" })] })), _jsx(Textarea, { id: fieldId, name: name, "aria-required": required || undefined, "aria-invalid": showError || undefined, "aria-describedby": showError ? errorId : undefined, onBlur: handleBlur, onChange: handleChange, showCharCount: showCharCount, ...textareaProps }), !showError && hint && (_jsx(Text, { size: "sm", variant: "secondary", className: "appkit-form-field__hint", children: hint })), showError && (_jsx(Text, { id: errorId, size: "sm", variant: "error", className: "appkit-form-field__error", role: "alert", children: error }))] }));
+    return (_jsxs("div", { className: ["appkit-form-field", className].filter(Boolean).join(" "), children: [label && (
+            /* One label implementation — see FieldLabel's header on the four
+               byte-identical copies this replaced. */
+            _jsx(FieldLabel, { htmlFor: fieldId, required: required, placement: labelPlacement, children: label })), _jsx(Textarea, { id: fieldId, name: name, "aria-required": required || undefined, "aria-invalid": showError || undefined, "aria-describedby": showError ? errorId : undefined, onBlur: handleBlur, onChange: handleChange, showCharCount: showCharCount, ...textareaProps }), !showError && hint && (_jsx(Text, { size: "sm", variant: "secondary", className: "appkit-form-field__hint", children: hint })), showError && (_jsx(Text, { id: errorId, size: "sm", variant: "error", className: "appkit-form-field__error", role: "alert", children: error }))] }));
 }

package/dist/ui/forms/FormShell.d.ts

@@ -69,9 +69,25 @@ export interface FormShellContextValue {
     submitAttemptCount: number;
     /** Call from a submit handler, before validating. */
     markSubmitAttempted: () => void;
+    addAnotherEnabled: boolean;
+    /** Ticked? Meaningless unless `addAnotherEnabled`. */
+    addAnother: boolean;
+    setAddAnother: (next: boolean) => void;
 }
 export declare const FormShellContext: React.Context<FormShellContextValue | null>;
 export declare function useFormShell(): FormShellContextValue;
+export interface FormShellStateOptions {
+    /**
+     * Offer "Create & add another".
+     *
+     * 🛑 OPT-IN, and the caller is taking on an obligation by passing it: its
+     * submit handler MUST read `addAnother` and, when true, keep the user on the
+     * form with a fresh draft instead of navigating away. Passing this without
+     * honouring it ships a checkbox that does nothing — the defect shape this
+     * codebase has paid for most often. `audit-add-another-honoured` blocks it.
+     */
+    allowAddAnother?: boolean;
+}
 export interface UseFormShellStateResult {
     shellCtx: FormShellContextValue;
     setFieldError: (name: string, error: string | null) => void;
@@ -105,7 +121,7 @@ export interface UseFormShellStateResult {
  * for single-segment forms; the summary renders a flat list, which is right
  * for them.
  */
-export declare function useFormShellState<TSchema extends import("zod").ZodTypeAny = import("zod").ZodTypeAny>(schema?: TSchema, nav?: FormShellNav): UseFormShellStateResult;
+export declare function useFormShellState<TSchema extends import("zod").ZodTypeAny = import("zod").ZodTypeAny>(schema?: TSchema, nav?: FormShellNav, opts?: FormShellStateOptions): UseFormShellStateResult;
 export interface FormShellProviderProps {
     children: ReactNode;
     /** Called on debounced auto-save when isDirty changes */

package/dist/ui/forms/FormShell.js

@@ -24,9 +24,18 @@ export function useFormShell() {
  * for single-segment forms; the summary renders a flat list, which is right
  * for them.
  */
-export function useFormShellState(schema, nav) {
+export function useFormShellState(schema, nav, opts) {
     const [errors, setErrors] = useState({});
     const [submitAttemptCount, setSubmitAttemptCount] = useState(0);
+    /*
+     * 🛑 DEFAULTS TO UNTICKED, even when offered. "Create & add another" changes
+     * what happens after a successful save, and a user who did not ask for a
+     * batch and is silently kept on the form reads it as "the save failed" —
+     * then saves again, and creates a duplicate. Defaulting a destination change
+     * is not a convenience.
+     */
+    const [addAnother, setAddAnother] = useState(false);
+    const addAnotherEnabled = opts?.allowAddAnother ?? false;
     const markSubmitAttempted = useCallback(() => setSubmitAttemptCount((n) => n + 1), []);
     const submitAttempted = submitAttemptCount > 0;
     const setFieldError = useCallback((name, error) => {
@@ -90,7 +99,14 @@ export function useFormShellState(schema, nav) {
         submitAttempted,
         submitAttemptCount,
         markSubmitAttempted,
-    }), [errors, setFieldError, navSections, navGoTo, navFieldMap, submitAttempted, submitAttemptCount, markSubmitAttempted]);
+        addAnotherEnabled,
+        // 🛑 Forced to `false` when the feature is not offered, rather than passed
+        // through. Otherwise a caller that never opted in but reads `addAnother`
+        // (a copy-paste from one that did) could branch on a value no control can
+        // change — a dead branch that looks live.
+        addAnother: addAnotherEnabled && addAnother,
+        setAddAnother,
+    }), [errors, setFieldError, navSections, navGoTo, navFieldMap, submitAttempted, submitAttemptCount, markSubmitAttempted, addAnotherEnabled, addAnother]);
     return {
         shellCtx,
         setFieldError,
@@ -185,6 +201,24 @@ export function FormShellProvider({ children, onSaveDraft, isDirty = false, auto
         submitAttempted,
         submitAttemptCount,
         markSubmitAttempted,
+        /*
+         * 🛑 `FormShellProvider` DOES NOT OFFER "Create & add another", and this
+         * is a decision rather than an omission.
+         *
+         * This provider backs the multi-step WIZARD (`features/shell/FormShell` +
+         * `StepForm`) — auto-save, draft, publish. "Add another" means "stay here
+         * with a fresh draft", and in a wizard that would also have to mean "and
+         * go back to step one", silently discarding a publish flow the user had
+         * walked through. It also auto-saves drafts, so a half-cleared wizard
+         * would persist. If a batch-create wizard is ever wanted, it needs its own
+         * design; a checkbox here would be the control-that-lies shape.
+         *
+         * `addAnother` is hard `false`, so `<AddAnotherToggle>` inside a wizard
+         * renders nothing and any handler reading it takes the normal branch.
+         */
+        addAnotherEnabled: false,
+        addAnother: false,
+        setAddAnother: () => { },
     }), [errors, touched, setFieldError, setFieldTouched, clearFieldError, isDirty, onGoToStep, fieldToStepIndex, sections, submitAttempted, submitAttemptCount, markSubmitAttempted]);
     return _jsx(FormShellContext.Provider, { value: ctx, children: children });
 }