@mohasinac/appkit 4.61.0 → 4.62.1

package/dist/tokens/themes/default-dark.js

@@ -54,6 +54,7 @@ export const DEFAULT_DARK_THEME = {
         "appkit-color-text": "#fafafa",
         "appkit-color-text-muted": "#b4b4bd",
         "appkit-color-text-faint": "#8b8b94",
+        "appkit-color-link": "#22d3ee",
         "appkit-color-success": "#34d399",
         "appkit-color-success-surface": "rgba(6, 78, 59, 0.25)",
         "appkit-color-warning": "#fbbf24",

package/dist/tokens/themes/default-light.js

@@ -57,6 +57,7 @@ export const DEFAULT_LIGHT_THEME = {
         "appkit-color-text-muted": "#5b5b63",
         "appkit-color-text-faint": "#6f6f78",
         "appkit-color-text-on-primary": "#ffffff",
+        "appkit-color-link": "#0f766e",
         "appkit-color-success": "#15803d",
         "appkit-color-success-surface": "#f0fdf4",
         "appkit-color-warning": "#b45309",

package/dist/tokens/themes/required.d.ts

@@ -10,6 +10,6 @@ import type { GradientKey } from "./types";
  * unknown keys are rejected; missing keys fall back to the active mode's
  * default theme value (so a theme can override only a subset).
  */
-export declare const REQUIRED_THEME_TOKENS: readonly ["appkit-color-primary", "appkit-color-primary-50", "appkit-color-primary-100", "appkit-color-primary-200", "appkit-color-primary-300", "appkit-color-primary-400", "appkit-color-primary-500", "appkit-color-primary-600", "appkit-color-primary-700", "appkit-color-primary-800", "appkit-color-primary-900", "appkit-color-primary-950", "appkit-color-secondary", "appkit-color-secondary-50", "appkit-color-secondary-100", "appkit-color-secondary-200", "appkit-color-secondary-300", "appkit-color-secondary-400", "appkit-color-secondary-500", "appkit-color-secondary-600", "appkit-color-secondary-700", "appkit-color-secondary-800", "appkit-color-secondary-900", "appkit-color-secondary-950", "appkit-color-bg", "appkit-color-surface", "appkit-color-surface-elevated", "appkit-color-surface-input", "appkit-color-border", "appkit-color-border-subtle", "appkit-color-text", "appkit-color-text-muted", "appkit-color-text-faint", "appkit-color-text-on-primary", "appkit-color-success", "appkit-color-success-surface", "appkit-color-warning", "appkit-color-warning-surface", "appkit-color-error", "appkit-color-error-surface", "appkit-color-info", "appkit-color-info-surface", "appkit-color-focus-ring", "appkit-shadow-glow", "appkit-shadow-glow-pink", "appkit-font-display", "appkit-font-sans", "appkit-font-editorial", "appkit-font-mono", "appkit-space-0-5", "appkit-space-1", "appkit-space-1-5", "appkit-space-2", "appkit-space-2-5", "appkit-space-3", "appkit-space-3-5", "appkit-space-4", "appkit-space-5", "appkit-space-6", "appkit-space-8", "appkit-space-10", "appkit-space-12", "appkit-space-14", "appkit-space-16", "appkit-space-18", "appkit-space-20", "appkit-space-24", "appkit-text-2xs", "appkit-text-xs", "appkit-text-sm", "appkit-text-base", "appkit-text-lg", "appkit-text-xl", "appkit-text-2xl", "appkit-text-3xl", "appkit-text-4xl", "appkit-text-5xl"];
+export declare const REQUIRED_THEME_TOKENS: readonly ["appkit-color-primary", "appkit-color-primary-50", "appkit-color-primary-100", "appkit-color-primary-200", "appkit-color-primary-300", "appkit-color-primary-400", "appkit-color-primary-500", "appkit-color-primary-600", "appkit-color-primary-700", "appkit-color-primary-800", "appkit-color-primary-900", "appkit-color-primary-950", "appkit-color-secondary", "appkit-color-secondary-50", "appkit-color-secondary-100", "appkit-color-secondary-200", "appkit-color-secondary-300", "appkit-color-secondary-400", "appkit-color-secondary-500", "appkit-color-secondary-600", "appkit-color-secondary-700", "appkit-color-secondary-800", "appkit-color-secondary-900", "appkit-color-secondary-950", "appkit-color-bg", "appkit-color-surface", "appkit-color-surface-elevated", "appkit-color-surface-input", "appkit-color-border", "appkit-color-border-subtle", "appkit-color-text", "appkit-color-text-muted", "appkit-color-text-faint", "appkit-color-text-on-primary", "appkit-color-link", "appkit-color-success", "appkit-color-success-surface", "appkit-color-warning", "appkit-color-warning-surface", "appkit-color-error", "appkit-color-error-surface", "appkit-color-info", "appkit-color-info-surface", "appkit-color-focus-ring", "appkit-shadow-glow", "appkit-shadow-glow-pink", "appkit-font-display", "appkit-font-sans", "appkit-font-editorial", "appkit-font-mono", "appkit-space-0-5", "appkit-space-1", "appkit-space-1-5", "appkit-space-2", "appkit-space-2-5", "appkit-space-3", "appkit-space-3-5", "appkit-space-4", "appkit-space-5", "appkit-space-6", "appkit-space-8", "appkit-space-10", "appkit-space-12", "appkit-space-14", "appkit-space-16", "appkit-space-18", "appkit-space-20", "appkit-space-24", "appkit-text-2xs", "appkit-text-xs", "appkit-text-sm", "appkit-text-base", "appkit-text-lg", "appkit-text-xl", "appkit-text-2xl", "appkit-text-3xl", "appkit-text-4xl", "appkit-text-5xl"];
 export type RequiredThemeToken = (typeof REQUIRED_THEME_TOKENS)[number];
 export declare const REQUIRED_GRADIENT_KEYS: readonly GradientKey[];

package/dist/tokens/themes/required.js

@@ -47,6 +47,7 @@ export const REQUIRED_THEME_TOKENS = [
     "appkit-color-text-muted",
     "appkit-color-text-faint",
     "appkit-color-text-on-primary",
+    "appkit-color-link",
     // Status
     "appkit-color-success",
     "appkit-color-success-surface",

package/dist/tokens/tokens.css

@@ -302,6 +302,15 @@
   --appkit-color-text-on-primary:  #ffffff;
   --appkit-color-text-on-dark:     #ffffff;
 
+  /* Link ink for long-form prose. A SEPARATE token because the right link
+   * colour is not the same ramp in every theme: default-light wants primary
+   * (teal), default-dark wants secondary (cyan) because its primary is a RED
+   * that reads as danger, and cobalt-night's primary IS blue. Binding prose
+   * links to `primary-600` instead would be #dc2626 on the dark theme.
+   * primary-700, not -600: #0d9488 is only 3.59:1 on --appkit-color-bg and
+   * fails AA for normal text; #0f766e is 5.24:1. */
+  --appkit-color-link:             #0f766e;    /* primary-700 — 5.24:1 on --appkit-color-bg */
+
   --appkit-color-success:          #15803d;    /* green-700 — 4.5:1 AA against success-surface, distinct from the new teal primary */
   --appkit-color-success-surface:  #f0fdf4;    /* green-50 */
   --appkit-color-warning:          #b45309;    /* amber-700 — 4.5:1 AA against warning-surface */
@@ -500,6 +509,8 @@
   --appkit-color-text-muted:       #b4b4bd;    /* lightened from zinc-400 #a1a1aa — ~9:1 on the dark page */
   --appkit-color-text-faint:       #8b8b94;    /* lightened from zinc-500 #71717a, which was ~3:1 and read as barely present */
 
+  --appkit-color-link:             #22d3ee;    /* secondary-400 — 11.16:1 on --appkit-color-bg. NOT primary: this theme's primary is crimson */
+
   --appkit-color-success:          #34d399;    /* emerald-400 */
   --appkit-color-success-surface:  rgba(6, 78, 59, 0.25);
   --appkit-color-warning:          #fbbf24;    /* amber-400 */
@@ -620,6 +631,8 @@
   --appkit-color-text-muted:       #bcd4ff;    /* primary-200 */
   --appkit-color-text-faint:       #8eb9ff;    /* primary-300 */
 
+  --appkit-color-link:             #5992ff;    /* primary-500 — 5.17:1 on --appkit-color-bg */
+
   --appkit-color-success:          #4ade80;
   --appkit-color-success-surface:  rgba(20, 83, 45, 0.3);
   --appkit-color-warning:          #fbbf24;
@@ -652,6 +665,8 @@
   --appkit-color-surface-elevated: #ffffff;
   --appkit-color-surface-input:    #fffbeb;    /* amber-50 */
 
+  --appkit-color-link:             #b45309;    /* amber-700 — 4.73:1 on --appkit-color-bg; primary-600 #d97706 is only 3.0:1 */
+
   /* --- Interactive surfaces ------------------------------------------------
    * `-hover` is the neutral chrome hover fill; `-raised` is a resting panel one
    * step off the page surface; `primary-surface` is the brand-tinted hover.

package/dist/ui/components/Checkbox.js

@@ -19,13 +19,21 @@ export function Checkbox({ label, suffix, error, indeterminate = false, type = "
     const generatedId = React.useId();
     const inputId = id ?? generatedId;
     const inputRef = React.useRef(null);
+    /*
+     * A caller's own `aria-invalid` wins. `{...props}` is spread first, so
+     * re-specifying the attribute afterwards used to overwrite an incoming
+     * `"true"` with `undefined` — and `FieldCheckbox` sets it itself while
+     * withholding `error` (to avoid a double message). See the full writeup in
+     * `Input.tsx`; the same bug existed here.
+     */
+    const ariaInvalid = props["aria-invalid"] ?? (error ? "true" : undefined);
     React.useEffect(() => {
         if (inputRef.current) {
             inputRef.current.indeterminate = indeterminate;
         }
     }, [indeterminate]);
     if (bare) {
-        return (_jsx("input", { ...props, ref: inputRef, id: inputId, type: type, checked: checked, disabled: disabled, "aria-invalid": error ? "true" : undefined, className: className }));
+        return (_jsx("input", { ...props, ref: inputRef, id: inputId, type: type, checked: checked, disabled: disabled, "aria-invalid": ariaInvalid, className: className }));
     }
     // A checkbox with no label/suffix has no text to lay out beside the box, so
     // the default `width: 100%` on the root serves no purpose and actively harms
@@ -43,7 +51,7 @@ export function Checkbox({ label, suffix, error, indeterminate = false, type = "
                     disabled ? UI_CHECKBOX.labelDisabled : "",
                 ]
                     .filter(Boolean)
-                    .join(" "), children: [_jsxs("span", { className: UI_CHECKBOX.boxWrap, children: [_jsx("input", { ...props, ref: inputRef, id: inputId, type: type, checked: checked, disabled: disabled, "aria-invalid": error ? "true" : undefined, className: [
+                    .join(" "), children: [_jsxs("span", { className: UI_CHECKBOX.boxWrap, children: [_jsx("input", { ...props, ref: inputRef, id: inputId, type: type, checked: checked, disabled: disabled, "aria-invalid": ariaInvalid, className: [
                                     UI_CHECKBOX.input,
                                     error ? UI_CHECKBOX.inputError : "",
                                     className,

package/dist/ui/components/DateInput.js

@@ -5,7 +5,14 @@ import { Label, Span, Text } from "./Typography.js";
 export const DateInput = React.forwardRef(function DateInput({ label, error, helperText, value, onChange, disabled, required, id, className = "", ...props }, ref) {
     const generatedId = React.useId();
     const inputId = id ?? generatedId;
-    return (_jsxs("div", { className: "w-full", children: [label && (_jsx(Label, { htmlFor: inputId, required: required, className: "appkit-form-field__label mb-1.5", children: label })), _jsx("input", { ...props, ref: ref, id: inputId, type: "date", value: value, disabled: disabled, required: required, "aria-invalid": error ? "true" : undefined, onChange: (e) => onChange?.(e.target.value), className: ["appkit-input", error ? "appkit-input--error" : "", className].filter(Boolean).join(" ") }), error ? (_jsx(Text, { size: "sm", variant: "error", role: "alert", className: "mt-1.5", children: error })) : helperText ? (_jsx(Text, { size: "sm", variant: "secondary", className: "mt-1.5", children: helperText })) : null] }));
+    /*
+     * A caller's own `aria-invalid` wins. `{...props}` is spread first, so
+     * re-specifying the attribute afterwards overwrites an incoming "true"
+     * with `undefined` — the defect that left every Field*-built form in the
+     * app with no aria-invalid at all. See the full writeup in `Input.tsx`.
+     */
+    const ariaInvalid = props["aria-invalid"] ?? (error ? "true" : undefined);
+    return (_jsxs("div", { className: "w-full", children: [label && (_jsx(Label, { htmlFor: inputId, required: required, className: "appkit-form-field__label mb-1.5", children: label })), _jsx("input", { ...props, ref: ref, id: inputId, type: "date", value: value, disabled: disabled, required: required, "aria-invalid": ariaInvalid, onChange: (e) => onChange?.(e.target.value), className: ["appkit-input", error ? "appkit-input--error" : "", className].filter(Boolean).join(" ") }), error ? (_jsx(Text, { size: "sm", variant: "error", role: "alert", className: "mt-1.5", children: error })) : helperText ? (_jsx(Text, { size: "sm", variant: "secondary", className: "mt-1.5", children: helperText })) : null] }));
 });
 export function DateRangeInput({ label, startLabel = "From", endLabel = "To", startValue, endValue, onStartChange, onEndChange, error, helperText, disabled, required, startMin, startMax, endMin, endMax, }) {
     return (_jsxs("div", { className: "w-full", children: [label && (_jsx(Text, { size: "sm", className: "appkit-form-field__label mb-1.5 block font-medium", children: label })), _jsxs("div", { className: "flex items-end gap-2", children: [_jsx(DateInput, { label: startLabel, value: startValue, onChange: onStartChange, disabled: disabled, required: required, min: startMin, max: startMax ?? endValue }), _jsx(Span, { size: "sm", className: "mb-2.5 shrink-0 text-[var(--appkit-color-text-muted)]", children: "\u2013" }), _jsx(DateInput, { label: endLabel, value: endValue, onChange: onEndChange, disabled: disabled, min: endMin ?? startValue, max: endMax })] }), error ? (_jsx(Text, { size: "sm", variant: "error", role: "alert", className: "mt-1.5", children: error })) : helperText ? (_jsx(Text, { size: "sm", variant: "secondary", className: "mt-1.5", children: helperText })) : null] }));

package/dist/ui/components/Disclaimer.d.ts

@@ -0,0 +1,19 @@
+import React from "react";
+import { type DisclaimerId } from "../../_internal/shared/content/disclaimers";
+import { type PublishedValues } from "../../_internal/shared/content/published-values";
+export interface DisclaimerProps {
+    id: DisclaimerId;
+    /** Override the money figures with the admin's current configuration. */
+    publishedValues?: PublishedValues;
+    /**
+     * Render without the surrounding box — for a disclaimer that sits inside a
+     * card that already has chrome.
+     *
+     * 🛑 Does NOT make it smaller or quieter. A `warning`-tone entry keeps its
+     * tone inline, because the entries marked `warning` are the ones where
+     * ignoring the text has a consequence the reader cannot undo.
+     */
+    inline?: boolean;
+    className?: string;
+}
+export declare function Disclaimer({ id, publishedValues, inline, className, }: DisclaimerProps): React.JSX.Element | null;

package/dist/ui/components/Disclaimer.js

@@ -0,0 +1,74 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from "react";
+import { Div, Stack, Text } from "../index.js";
+import { DISCLAIMERS, } from "../../_internal/shared/content/disclaimers.js";
+import { resolvePublishedCopy, resolvePublishedValues, } from "../../_internal/shared/content/published-values.js";
+/**
+ * The one way to render a disclaimer (Phase 12).
+ *
+ * ## 🛑 `id` only — there is no `text` prop, deliberately
+ *
+ * A `text` escape hatch would make this a styled box, and then the legally
+ * material disclaimers would be written at their call sites again, drift, and
+ * end up weakest exactly where they matter most. That is the failure this
+ * registry exists to close. If a surface needs a disclaimer that does not
+ * exist, the fix is a new registry entry — which is also what gets it
+ * reviewed.
+ *
+ * ## Tokens resolve here
+ *
+ * The protection entry quotes `{{saleProtectionMaxValue}}` and the claim
+ * windows, so the published limits come from the constants that ENFORCE them
+ * (Phase 9's mechanism). A change to `SALE_PROTECTION_MAX_VALUE` updates the
+ * terms rather than contradicting them.
+ *
+ * Code-derived values are the default; a caller with settings in hand passes
+ * better ones for the money figures.
+ *
+ * ## Safe in a Server Component
+ *
+ * No hooks, no state, and the registry is a plain object — so this renders on
+ * either side of the boundary. Do not add state here without checking every
+ * RSC call site (Root Cause #76).
+ */
+const CODE_DERIVED_VALUES = resolvePublishedValues();
+/**
+ * Renders `**bold**` and nothing else.
+ *
+ * 🛑 A deliberately tiny subset, not a markdown renderer. The emphasis is
+ * load-bearing in exactly the places it is used — "**not insurance**" in the
+ * protection entry, "**under review**" versus "**verified**" in the scam
+ * registry — and those are the phrases a reader skims past without it.
+ *
+ * 🛑 And it returns ELEMENTS, never HTML. The bodies are our own constants so
+ * injection is not the risk; the risk is that a `dangerouslySetInnerHTML`
+ * here would invite someone to pass admin-editable text through it later,
+ * which is how a disclaimer box becomes a stored-XSS surface.
+ */
+function renderEmphasis(text) {
+    return text.split(/(\*\*[^*]+\*\*)/g).map((part, i) => part.startsWith("**") && part.endsWith("**") && part.length > 4 ? (_jsx(Text, { as: "span", weight: "semibold", children: part.slice(2, -2) }, i)) : (_jsx(React.Fragment, { children: part }, i)));
+}
+export function Disclaimer({ id, publishedValues = CODE_DERIVED_VALUES, inline = false, className = "", }) {
+    const entry = DISCLAIMERS[id];
+    /*
+     * A `Record<DisclaimerId, …>` means this cannot happen through the type, but
+     * an `as DisclaimerId` cast at a call site could — and rendering nothing is
+     * the wrong failure here. A missing disclaimer is invisible, which is the
+     * whole problem; so it renders nothing only when the registry genuinely has
+     * no entry, and the audit is what catches that case before it ships.
+     */
+    if (!entry)
+        return null;
+    const body = resolvePublishedCopy(entry.body, publishedValues);
+    const content = (_jsxs(Stack, { gap: "xs", children: [entry.heading && (_jsx(Text, { size: "xs", weight: "semibold", transform: "uppercase", color: "muted", children: entry.heading })), _jsx(Text, { size: "xs", color: "muted", className: "leading-relaxed", children: renderEmphasis(body) })] }));
+    if (inline)
+        return _jsx(Div, { className: className, children: content });
+    /*
+     * 🛑 `surface` + the matching ink, never a status background with literal
+     * white text. `-surface` is a near-white tint in light themes and a dark
+     * tint in dark ones, so a fixed `text-white` is invisible in exactly one
+     * theme — Root Cause #67, which shipped 26 invisible surfaces that way.
+     * `Text color="muted"` above pairs correctly with both.
+     */
+    return (_jsx(Div, { surface: entry.tone === "warning" ? "warning-surface" : "muted", rounded: "lg", padding: "sm", className: className, children: content }));
+}

package/dist/ui/components/Input.js

@@ -13,6 +13,26 @@ export const Input = React.forwardRef(function Input({ label, error, helperText,
         : variant === "ghost"
             ? "border-transparent bg-transparent shadow-none"
             : "";
+    /*
+     * 🛑 A CALLER'S OWN `aria-invalid` MUST WIN — it did not, and that broke
+     * every form in the app.
+     *
+     * `{...props}` is spread FIRST on both `<input>` elements below, so
+     * re-specifying `aria-invalid={error ? "true" : undefined}` afterwards
+     * OVERWROTE an incoming `"true"` with `undefined` (JSX: later wins).
+     *
+     * That is not hypothetical. `FieldInput` sets `aria-invalid` itself and
+     * deliberately WITHHOLDS `error` from this component, so the message is not
+     * rendered twice — which means `error` here is `undefined` exactly when the
+     * field is invalid. Net effect: no `Field*`-built form ever emitted
+     * `aria-invalid`, and `SectionForm`'s jump-to-error
+     * (`querySelector("[aria-invalid='true']")?.focus()`) silently focused
+     * nothing, every time.
+     *
+     * Same precedence rule as `bareAriaLabel` below: fill the gap, never
+     * override an explicit choice.
+     */
+    const ariaInvalid = props["aria-invalid"] ?? (error ? "true" : undefined);
     const inputClassName = [
         "appkit-input",
         icon ? "pl-10" : "",
@@ -45,10 +65,10 @@ export const Input = React.forwardRef(function Input({ label, error, helperText,
          * overrides an explicit choice.
          */
         const bareAriaLabel = props["aria-label"] ?? (typeof label === "string" ? label : undefined);
-        return (_jsx("input", { ...props, ref: ref, id: inputId, disabled: disabled, "aria-label": bareAriaLabel, "aria-invalid": error ? "true" : undefined, className: inputClassName }));
+        return (_jsx("input", { ...props, ref: ref, id: inputId, disabled: disabled, "aria-label": bareAriaLabel, "aria-invalid": ariaInvalid, className: inputClassName }));
     }
     const adornment = rightIcon ??
         (success && !error ? (_jsx("svg", { className: CLS_INPUT_SUCCESS_ICON, viewBox: "0 0 20 20", fill: "currentColor", "aria-hidden": "true", children: _jsx("path", { fillRule: "evenodd", d: "M16.704 5.29a1 1 0 010 1.42l-7.2 7.2a1 1 0 01-1.415 0l-3.2-3.2a1 1 0 111.414-1.42l2.493 2.494 6.493-6.494a1 1 0 011.415 0z", clipRule: "evenodd" }) })) : null);
-    return (_jsxs("div", { className: "w-full", "data-section": "input-div-527", children: [label && (_jsx(Label, { htmlFor: inputId, required: required, children: label })), _jsxs("div", { className: "relative", "data-section": "input-div-528", children: [icon && (_jsx(Div, { className: "pointer-events-none absolute inset-y-0 left-3 flex items-center text-[var(--appkit-color-text-faint)]", "data-section": "input-div-529", children: icon })), _jsx("input", { ...props, ref: ref, id: inputId, disabled: disabled, "aria-invalid": error ? "true" : undefined, className: inputClassName }), adornment && (_jsx(Div, { className: "pointer-events-none absolute inset-y-0 right-3 flex items-center text-[var(--appkit-color-text-faint)]", "data-section": "input-div-530", children: adornment }))] }), error ? (_jsx(Text, { size: "sm", variant: "error", className: "mt-1.5", role: "alert", children: error })) : helperText ? (_jsx(Text, { size: "sm", variant: "secondary", className: "mt-1.5", children: helperText })) : null] }));
+    return (_jsxs("div", { className: "w-full", "data-section": "input-div-527", children: [label && (_jsx(Label, { htmlFor: inputId, required: required, children: label })), _jsxs("div", { className: "relative", "data-section": "input-div-528", children: [icon && (_jsx(Div, { className: "pointer-events-none absolute inset-y-0 left-3 flex items-center text-[var(--appkit-color-text-faint)]", "data-section": "input-div-529", children: icon })), _jsx("input", { ...props, ref: ref, id: inputId, disabled: disabled, "aria-invalid": ariaInvalid, className: inputClassName }), adornment && (_jsx(Div, { className: "pointer-events-none absolute inset-y-0 right-3 flex items-center text-[var(--appkit-color-text-faint)]", "data-section": "input-div-530", children: adornment }))] }), error ? (_jsx(Text, { size: "sm", variant: "error", className: "mt-1.5", role: "alert", children: error })) : helperText ? (_jsx(Text, { size: "sm", variant: "secondary", className: "mt-1.5", children: helperText })) : null] }));
 });
 Input.displayName = "Input";

package/dist/ui/components/PaginatedSelect.d.ts

@@ -20,6 +20,14 @@ interface BaseProps<V> {
     disabled?: boolean;
     className?: string;
     ariaLabel?: string;
+    /** Field name — resolves this control's error from `FormShellContext`, as `Field*` do. */
+    name?: string;
+    /**
+     * Validation message. Explicit prop wins; else read from context by `name`.
+     * Without these two this control had no error affordance at all: a required
+     * taxonomy pick could fail and the control showed nothing.
+     */
+    error?: React.ReactNode;
     /** "+ Create new …" button. Provide `renderCreateForm` OR (`createFields` + `onCreateSubmit`). */
     createLabel?: string;
     drawerTitle?: string;
@@ -59,24 +67,5 @@ interface MultiProps<V> extends BaseProps<V> {
     maxChipsVisible?: number;
 }
 export type PaginatedSelectProps<V = string> = SingleProps<V> | MultiProps<V>;
-/**
- * PaginatedSelect — searchable, async-paginated select with optional multi-mode
- * and optional inline create-new drawer.
- *
- * @example single-select
- * <PaginatedSelect value={storeId} onChange={setStoreId} loadOptions={loadStores} />
- *
- * @example single-select with inline create
- * <PaginatedSelect
- *   value={categoryId}
- *   onChange={(v) => setCategoryId(v ?? "")}
- *   loadOptions={loadCategories}
- *   createLabel="Category"
- *   renderCreateForm={({ onCreated, onCancel }) => <CategoryForm ... />}
- * />
- *
- * @example multi-select
- * <PaginatedSelect multiple value={tagIds} onChange={setTagIds} loadOptions={loadTags} />
- */
 export declare function PaginatedSelect<V = string>(props: PaginatedSelectProps<V>): React.JSX.Element;
 export {};

package/dist/ui/components/PaginatedSelect.js

@@ -1,7 +1,10 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { useCallback, useEffect, useRef, useState } from "react";
+import React, { useCallback, useEffect, useRef, useState } from "react";
 import { Input } from "./Input.js";
+import { toUserMessage } from "../../errors/error-display-map.js";
+import { Text } from "./Typography.js";
+import { FormShellContext } from "../forms/FormShell.js";
 import { SideDrawer } from "./SideDrawer.js";
 import { Button } from "./Button.js";
 import { QuickFormDrawer } from "../../features/shell/QuickFormDrawer.js";
@@ -87,9 +90,43 @@ function isValueSelected(value, props, isMulti) {
  * @example multi-select
  * <PaginatedSelect multiple value={tagIds} onChange={setTagIds} loadOptions={loadTags} />
  */
+/**
+ * Resolve this control's validation message and the id that labels it.
+ *
+ * A hook rather than four lines in the component body: `PaginatedSelect` is
+ * already at `audit-code-quality`'s size limit, and the error affordance is
+ * self-contained — explicit prop wins, else `FormShellContext` by `name`,
+ * exactly as the `Field*` primitives resolve theirs.
+ */
+function usePaginatedSelectError(name, errorProp) {
+    const ctx = React.useContext(FormShellContext);
+    const error = errorProp ?? (name ? ctx?.errors[name] : undefined);
+    const errorId = `${React.useId()}-error`;
+    return { error, errorId };
+}
+/** The message, under the trigger it describes. */
+function PaginatedSelectError({ id, error }) {
+    if (!error)
+        return null;
+    return (_jsx(Text, { id: id, size: "sm", variant: "error", className: "appkit-form-field__error", role: "alert", children: error }));
+}
+/**
+ * The selected-values row, multi-select only.
+ *
+ * Its own component because `PaginatedSelect` sits against
+ * `audit-code-quality`'s size limit, and this block needs none of the
+ * control's twelve state variables — only what it is handed.
+ */
+function PaginatedSelectChips({ chips, labelFor, overflowCount, disabled, onRemove, }) {
+    return (_jsxs("div", { className: C.chips, children: [chips.map((v) => (_jsxs("span", { className: C.chip, children: [_jsx("span", { className: C.chipLabel, children: labelFor(v) }), !disabled && (_jsx("button", { type: "button", "aria-label": "Remove", className: C.chipRemove, onClick: (e) => {
+                            e.stopPropagation();
+                            onRemove(v);
+                        }, children: "\u2715" }))] }, String(v)))), overflowCount > 0 && (_jsxs("span", { className: C.overflowChip, children: ["+", overflowCount, " more"] }))] }));
+}
 export function PaginatedSelect(props) {
-    const { options, loadOptions, placeholder = "Select...", searchPlaceholder = "Search...", noResultsText = "No results", disabled, className = "", ariaLabel, createLabel, drawerTitle, renderCreateForm, createFields, createSchema, onCreateSubmit, createSubmitLabel, editLabel, editDrawerTitle, renderEditForm, editFields, editSchema, onEditLoad, onEditSubmit, editSubmitLabel, } = props;
+    const { options, loadOptions, placeholder = "Select...", searchPlaceholder = "Search...", noResultsText = "No results", disabled, className = "", ariaLabel, name, error: errorProp, createLabel, drawerTitle, renderCreateForm, createFields, createSchema, onCreateSubmit, createSubmitLabel, editLabel, editDrawerTitle, renderEditForm, editFields, editSchema, onEditLoad, onEditSubmit, editSubmitLabel, } = props;
     const isMulti = props.multiple === true;
+    const { error, errorId } = usePaginatedSelectError(name, errorProp);
     const maxChipsVisible = isMulti ? props.maxChipsVisible ?? 3 : 0;
     const [query, setQuery] = useState("");
     const [open, setOpen] = useState(false);
@@ -222,7 +259,7 @@ export function PaginatedSelect(props) {
             // Same staleness rule as the success path: a superseded request must
             // not paint its failure over a newer request's results.
             if (requestId === requestIdRef.current) {
-                setLoadError(normalized.message || "Could not load options.");
+                setLoadError(toUserMessage(normalized.code, undefined, { fallback: "Could not load options." }));
                 if (reset)
                     setAsyncOptions([]);
             }
@@ -370,12 +407,9 @@ export function PaginatedSelect(props) {
     const multiValue = isMulti ? props.value : [];
     const visibleChips = multiValue.slice(0, maxChipsVisible);
     const overflowCount = multiValue.length - maxChipsVisible;
-    return (_jsxs(_Fragment, { children: [_jsxs("div", { ref: containerRef, className: [C.root, className].filter(Boolean).join(" "), "aria-label": ariaLabel, children: [isMulti && multiValue.length > 0 && (_jsxs("div", { className: C.chips, children: [visibleChips.map((v) => (_jsxs("span", { className: C.chip, children: [_jsx("span", { className: C.chipLabel, children: labelMap.current.get(v) ?? String(v) }), !disabled && (_jsx("button", { type: "button", "aria-label": "Remove", className: C.chipRemove, onClick: (e) => {
-                                            e.stopPropagation();
-                                            removeChip(v);
-                                        }, children: "\u2715" }))] }, String(v)))), overflowCount > 0 && (_jsxs("span", { className: C.overflowChip, children: ["+", overflowCount, " more"] }))] })), _jsxs("button", { type: "button", disabled: disabled, onClick: () => setOpen((prev) => !prev), className: [C.trigger, disabled ? C.triggerDisabled : ""]
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { ref: containerRef, className: [C.root, className].filter(Boolean).join(" "), children: [isMulti && multiValue.length > 0 && (_jsx(PaginatedSelectChips, { chips: visibleChips, labelFor: (v) => labelMap.current.get(v) ?? String(v), overflowCount: overflowCount, disabled: disabled, onRemove: removeChip })), _jsxs("button", { type: "button", disabled: disabled, onClick: () => setOpen((prev) => !prev), className: [C.trigger, disabled ? C.triggerDisabled : ""]
                             .filter(Boolean)
-                            .join(" "), "aria-expanded": open, "aria-haspopup": "listbox", children: [_jsx("span", { className: C.triggerLeft, children: _jsx("span", { className: triggerEmpty ? C.placeholder : "", children: triggerLabel }) }), _jsx("span", { "aria-hidden": "true", children: "\u25BE" })] }), hasEdit && !disabled ? (_jsx("button", { type: "button", className: C.editBtn, "aria-label": `Edit ${editLabel}`, title: `Edit ${editLabel}`, onClick: () => {
+                            .join(" "), "aria-label": ariaLabel, "aria-expanded": open, "aria-haspopup": "listbox", "aria-invalid": error ? "true" : undefined, "aria-describedby": error ? errorId : undefined, children: [_jsx("span", { className: C.triggerLeft, children: _jsx("span", { className: triggerEmpty ? C.placeholder : "", children: triggerLabel }) }), _jsx("span", { "aria-hidden": "true", children: "\u25BE" })] }), hasEdit && !disabled ? (_jsx("button", { type: "button", className: C.editBtn, "aria-label": `Edit ${editLabel}`, title: `Edit ${editLabel}`, onClick: () => {
                             setOpen(false);
                             setEditOpen(true);
                         }, children: "\u270E" })) : null, open && (_jsxs("div", { className: [C.dropdown, opensUp ? C.dropdownUp : ""].filter(Boolean).join(" "), role: "listbox", "aria-multiselectable": isMulti || undefined, children: [_jsx(Input, { autoFocus: true, value: query, onChange: (e) => setQuery(e.target.value), placeholder: searchPlaceholder, className: C.search }), _jsxs("ul", { className: C.list, children: [filtered.map((opt, idx) => {
@@ -386,7 +420,7 @@ export function PaginatedSelect(props) {
                                     }), loadError && !loading && (_jsxs("li", { className: C.empty, role: "alert", children: [loadError, " ", _jsx(Button, { variant: "ghost", size: "sm", onClick: () => void load(query, 1, true), children: "Try again" })] })), !loadError && filtered.length === 0 && !loading && (_jsx("li", { className: C.empty, children: noResultsText })), loading && _jsx("li", { className: C.loading, children: "Loading\u2026" }), hasMore && !loading && (_jsx("li", { children: _jsx("button", { type: "button", className: C.loadMore, onClick: () => void load(query, page + 1), children: "Load more" }) })), hasCreate && (_jsx("li", { children: _jsxs("button", { type: "button", className: C.createBtn, onClick: () => {
                                                 setOpen(false);
                                                 setDrawerOpen(true);
-                                            }, children: ["+ Create new ", createLabel] }) }, CREATE_SENTINEL))] })] }))] }), hasCreate && renderCreateForm ? (_jsx(SideDrawer, { isOpen: drawerOpen, onClose: () => setDrawerOpen(false), title: drawerTitle ?? `Create ${createLabel}`, mode: "create", footer: _jsx(Button, { variant: "ghost", onClick: () => setDrawerOpen(false), children: "Cancel" }), children: renderCreateForm({
+                                            }, children: ["+ Create new ", createLabel] }) }, CREATE_SENTINEL))] })] })), _jsx(PaginatedSelectError, { id: errorId, error: error })] }), hasCreate && renderCreateForm ? (_jsx(SideDrawer, { isOpen: drawerOpen, onClose: () => setDrawerOpen(false), title: drawerTitle ?? `Create ${createLabel}`, mode: "create", footer: _jsx(Button, { variant: "ghost", onClick: () => setDrawerOpen(false), children: "Cancel" }), children: renderCreateForm({
                     onCreated: handleCreated,
                     onCancel: () => setDrawerOpen(false),
                 }) })) : hasCreate && createFields && onCreateSubmit ? (_jsx(QuickFormDrawer, { isOpen: drawerOpen, onClose: () => setDrawerOpen(false), title: drawerTitle ?? `Create ${createLabel}`, fields: createFields, schema: createSchema, submitLabel: createSubmitLabel ?? `Create ${createLabel}`, onSubmit: async (values) => {

package/dist/ui/components/Radio.js

@@ -66,5 +66,12 @@ export function RadioGroup({ name, options, value, onChange, label, error, orien
 export function RadioItem({ label, suffix, error, className = "", checked, disabled, id, ...props }) {
     const generatedId = React.useId();
     const inputId = id ?? generatedId;
-    return (_jsxs("div", { className: "appkit-radio-item", "data-section": "radio-item-div", children: [_jsxs(Label, { htmlFor: inputId, className: ["appkit-radio-item__label", disabled ? "appkit-radio-item__label--disabled" : ""].filter(Boolean).join(" "), children: [_jsx("span", { className: "appkit-radio-item__box-wrap", children: _jsx("input", { ...props, id: inputId, type: "radio", checked: checked, disabled: disabled, "aria-invalid": error ? "true" : undefined, className: ["appkit-radio-item__input", error ? "appkit-radio-item__input--error" : "", className].filter(Boolean).join(" ") }) }), (label || suffix) && (_jsxs("span", { className: "appkit-radio-item__content", children: [label ? _jsx(Span, { className: "appkit-radio-item__text", children: label }) : _jsx("span", {}), suffix] }))] }), error && (_jsx(Text, { size: "sm", variant: "error", className: "appkit-radio-item__error", role: "alert", children: error }))] }));
+    /*
+     * A caller's own `aria-invalid` wins. `{...props}` is spread first, so
+     * re-specifying the attribute afterwards overwrites an incoming "true"
+     * with `undefined` — the defect that left every Field*-built form in the
+     * app with no aria-invalid at all. See the full writeup in `Input.tsx`.
+     */
+    const ariaInvalid = props["aria-invalid"] ?? (error ? "true" : undefined);
+    return (_jsxs("div", { className: "appkit-radio-item", "data-section": "radio-item-div", children: [_jsxs(Label, { htmlFor: inputId, className: ["appkit-radio-item__label", disabled ? "appkit-radio-item__label--disabled" : ""].filter(Boolean).join(" "), children: [_jsx("span", { className: "appkit-radio-item__box-wrap", children: _jsx("input", { ...props, id: inputId, type: "radio", checked: checked, disabled: disabled, "aria-invalid": ariaInvalid, className: ["appkit-radio-item__input", error ? "appkit-radio-item__input--error" : "", className].filter(Boolean).join(" ") }) }), (label || suffix) && (_jsxs("span", { className: "appkit-radio-item__content", children: [label ? _jsx(Span, { className: "appkit-radio-item__text", children: label }) : _jsx("span", {}), suffix] }))] }), error && (_jsx(Text, { size: "sm", variant: "error", className: "appkit-radio-item__error", role: "alert", children: error }))] }));
 }

package/dist/ui/components/Select.js

@@ -6,6 +6,14 @@ import { Label, Text } from "./Typography.js";
 export function Select({ options, value, onChange, onValueChange, placeholder, label, error, helperText, disabled = false, required, className = "", id, variant = "default", bare = false, wrapperClassName, ...props }) {
     const generatedId = React.useId();
     const inputId = id ?? generatedId;
+    /*
+     * A caller's own `aria-invalid` wins. `{...props}` is spread first, so
+     * re-specifying the attribute afterwards used to overwrite an incoming
+     * `"true"` with `undefined` — and `FieldSelect` sets it itself while
+     * withholding `error` (to avoid a double message). See the full writeup in
+     * `Input.tsx`; the same bug existed here.
+     */
+    const ariaInvalid = props["aria-invalid"] ?? (error ? "true" : undefined);
     const handleChange = (event) => {
         onChange?.(event);
         onValueChange?.(event.target.value);
@@ -28,7 +36,7 @@ export function Select({ options, value, onChange, onValueChange, placeholder, l
         .join(" ");
     const optionsMarkup = (_jsxs(_Fragment, { children: [placeholder ? (_jsx("option", { value: "", disabled: true, children: placeholder })) : null, options.map((option) => (_jsx("option", { value: option.value, disabled: option.disabled, children: option.label }, String(option.value))))] }));
     if (bare) {
-        return (_jsx("select", { ...props, id: inputId, value: value, onChange: handleChange, disabled: disabled, "aria-invalid": error ? "true" : undefined, className: selectClassName, children: optionsMarkup }));
+        return (_jsx("select", { ...props, id: inputId, value: value, onChange: handleChange, disabled: disabled, "aria-invalid": ariaInvalid, className: selectClassName, children: optionsMarkup }));
     }
-    return (_jsxs("div", { className: ["appkit-select", wrapperClassName].filter(Boolean).join(" "), "data-section": "select-div-592", children: [label && (_jsx(Label, { htmlFor: inputId, className: "appkit-select__label", required: required, children: label })), _jsxs("div", { className: "relative group", "data-section": "select-div-593", children: [_jsx("select", { ...props, id: inputId, value: value, onChange: handleChange, disabled: disabled, "aria-invalid": error ? "true" : undefined, className: selectClassName, children: optionsMarkup }), _jsx(Div, { className: "pointer-events-none absolute inset-y-0 right-3 flex items-center text-[var(--appkit-color-text-faint)]", "data-section": "select-div-594", children: _jsx("svg", { className: "h-4 w-4", viewBox: "0 0 20 20", fill: "currentColor", "aria-hidden": "true", children: _jsx("path", { fillRule: "evenodd", d: "M5.293 7.293a1 1 0 011.414 0L10 10.586l3.293-3.293a1 1 0 111.414 1.414l-4 4a1 1 0 01-1.414 0l-4-4a1 1 0 010-1.414z", clipRule: "evenodd" }) }) })] }), error ? (_jsx(Text, { size: "sm", variant: "error", className: "appkit-select__error", role: "alert", children: error })) : helperText ? (_jsx(Text, { size: "sm", variant: "secondary", className: "appkit-select__error", children: helperText })) : null] }));
+    return (_jsxs("div", { className: ["appkit-select", wrapperClassName].filter(Boolean).join(" "), "data-section": "select-div-592", children: [label && (_jsx(Label, { htmlFor: inputId, className: "appkit-select__label", required: required, children: label })), _jsxs("div", { className: "relative group", "data-section": "select-div-593", children: [_jsx("select", { ...props, id: inputId, value: value, onChange: handleChange, disabled: disabled, "aria-invalid": ariaInvalid, className: selectClassName, children: optionsMarkup }), _jsx(Div, { className: "pointer-events-none absolute inset-y-0 right-3 flex items-center text-[var(--appkit-color-text-faint)]", "data-section": "select-div-594", children: _jsx("svg", { className: "h-4 w-4", viewBox: "0 0 20 20", fill: "currentColor", "aria-hidden": "true", children: _jsx("path", { fillRule: "evenodd", d: "M5.293 7.293a1 1 0 011.414 0L10 10.586l3.293-3.293a1 1 0 111.414 1.414l-4 4a1 1 0 01-1.414 0l-4-4a1 1 0 010-1.414z", clipRule: "evenodd" }) }) })] }), error ? (_jsx(Text, { size: "sm", variant: "error", className: "appkit-select__error", role: "alert", children: error })) : helperText ? (_jsx(Text, { size: "sm", variant: "secondary", className: "appkit-select__error", children: helperText })) : null] }));
 }

package/dist/ui/components/TagInput.d.ts

@@ -7,5 +7,12 @@ export interface TagInputProps {
     placeholder?: string;
     className?: string;
     helperText?: string;
+    /**
+     * Validation message. This control had no error slot at all, so a schema
+     * failure on a tags field could only ever appear in the summary — the field
+     * itself showed nothing and was not announced as invalid. Mirrors the
+     * contract Input/Select/Textarea/Checkbox already have.
+     */
+    error?: React.ReactNode;
 }
-export declare function TagInput({ value, onChange, disabled, label, placeholder, className, helperText, }: TagInputProps): React.JSX.Element;
+export declare function TagInput({ value, onChange, disabled, label, placeholder, className, helperText, error, }: TagInputProps): React.JSX.Element;

package/dist/ui/components/TagInput.js

@@ -1,10 +1,11 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useRef, useState } from "react";
+import React, { useRef, useState } from "react";
 import { Label, Span } from "./Typography.js";
-export function TagInput({ value, onChange, disabled = false, label, placeholder = "Add a tag...", className = "", helperText = "Press Enter or comma to add a tag", }) {
+export function TagInput({ value, onChange, disabled = false, label, placeholder = "Add a tag...", className = "", helperText = "Press Enter or comma to add a tag", error, }) {
     const [draft, setDraft] = useState("");
     const inputRef = useRef(null);
+    const errorId = React.useId();
     const normalizeTag = (raw) => raw.trim().replace(/,+$/, "").trim();
     const addTag = (raw) => {
         const tag = normalizeTag(raw);
@@ -69,5 +70,5 @@ export function TagInput({ value, onChange, disabled = false, label, placeholder
                             disabled ? "appkit-tag-input__text--disabled" : "",
                         ]
                             .filter(Boolean)
-                            .join(" "), "aria-label": label ?? "Tag input" })] }), helperText && (_jsx(Span, { size: "xs", className: "appkit-tag-input__helper", children: helperText }))] }));
+                            .join(" "), "aria-label": label ?? "Tag input", "aria-invalid": error ? "true" : undefined, "aria-describedby": error ? errorId : undefined })] }), error ? (_jsx(Span, { id: errorId, size: "xs", className: "appkit-tag-input__helper appkit-form-field__error", role: "alert", children: error })) : helperText ? (_jsx(Span, { size: "xs", className: "appkit-tag-input__helper", children: helperText })) : null] }));
 }

package/dist/ui/components/Textarea.js

@@ -15,12 +15,20 @@ export const Textarea = React.forwardRef(function Textarea({ label, error, helpe
         : variant === "ghost"
             ? "border-transparent bg-transparent shadow-none"
             : "";
+    /*
+     * A caller's own `aria-invalid` wins. `{...props}` is spread first, so
+     * re-specifying the attribute afterwards used to overwrite an incoming
+     * `"true"` with `undefined` — and `FieldTextarea` sets it itself while
+     * withholding `error` (to avoid a double message). See the full writeup in
+     * `Input.tsx`; the same bug existed here.
+     */
+    const ariaInvalid = props["aria-invalid"] ?? (error ? "true" : undefined);
     const textareaClassName = ["appkit-textarea", variantClass, className]
         .filter(Boolean)
         .join(" ");
     if (bare) {
-        return (_jsx("textarea", { ...props, ref: ref, id: inputId, value: value, defaultValue: defaultValue, maxLength: maxLength, "aria-invalid": error ? "true" : undefined, className: textareaClassName }));
+        return (_jsx("textarea", { ...props, ref: ref, id: inputId, value: value, defaultValue: defaultValue, maxLength: maxLength, "aria-invalid": ariaInvalid, className: textareaClassName }));
     }
-    return (_jsxs("div", { className: "w-full", "data-section": "textarea-div-620", children: [label && (_jsx(Label, { htmlFor: inputId, required: required, children: label })), _jsx("textarea", { ...props, ref: ref, id: inputId, value: value, defaultValue: defaultValue, maxLength: maxLength, "aria-invalid": error ? "true" : undefined, className: textareaClassName }), (error || helperText || (showCharCount && maxLength)) && (_jsxs("div", { className: "mt-1.5 flex items-start justify-between gap-3", "data-section": "textarea-div-621", children: [_jsx("div", { className: "min-w-0 flex-1", "data-section": "textarea-div-622", children: error ? (_jsx(Text, { size: "sm", variant: "error", role: "alert", children: error })) : helperText ? (_jsx(Text, { size: "sm", variant: "secondary", children: helperText })) : null }), showCharCount && maxLength ? (_jsxs(Text, { size: "xs", variant: charCount >= maxLength ? "error" : "muted", className: "shrink-0 tabular-nums", children: [charCount, "/", maxLength] })) : null] }))] }));
+    return (_jsxs("div", { className: "w-full", "data-section": "textarea-div-620", children: [label && (_jsx(Label, { htmlFor: inputId, required: required, children: label })), _jsx("textarea", { ...props, ref: ref, id: inputId, value: value, defaultValue: defaultValue, maxLength: maxLength, "aria-invalid": ariaInvalid, className: textareaClassName }), (error || helperText || (showCharCount && maxLength)) && (_jsxs("div", { className: "mt-1.5 flex items-start justify-between gap-3", "data-section": "textarea-div-621", children: [_jsx("div", { className: "min-w-0 flex-1", "data-section": "textarea-div-622", children: error ? (_jsx(Text, { size: "sm", variant: "error", role: "alert", children: error })) : helperText ? (_jsx(Text, { size: "sm", variant: "secondary", children: helperText })) : null }), showCharCount && maxLength ? (_jsxs(Text, { size: "xs", variant: charCount >= maxLength ? "error" : "muted", className: "shrink-0 tabular-nums", children: [charCount, "/", maxLength] })) : null] }))] }));
 });
 Textarea.displayName = "Textarea";