@dloizides/ui-forms 1.5.0 → 1.7.0

package/dist/index.d.ts

@@ -1,8 +1,31 @@
 import React from 'react';
-import { ViewStyle, TextInputProps, TextInput, TextStyle } from 'react-native';
+import { StyleProp, TextStyle, ViewStyle, TextInputProps, TextInput } from 'react-native';
 
 /**
- * Field — the generic "label over a control, error under it" wrapper.
+ * The TWO legitimate label voices, per the shared forms contract
+ * (`PROOViD/AMLService/AMLService/wwwroot/shared/FORMS.md` → "The TWO legitimate label voices").
+ *
+ *  - `field`   — 13 / 600 / sentence case. A label that is READ: prose addressed to the person
+ *                filling the form. This is `Field`'s historical, unchanged default, so every
+ *                existing consumer renders byte-identically.
+ *  - `control` — 11 / 700 / UPPERCASE + letter-spacing. A label that is SCANNED: a key over a value
+ *                in a dense row (filter bars, compact toolbars, pager controls). These are exactly
+ *                the metrics `@dloizides/ui-tables` forked into its private `FieldShell` because
+ *                `Field` hard-coded the `field` voice and offered no way out.
+ *
+ * A THIRD voice is drift, not a variant. Pick the voice from the SURFACE, not the component: every
+ * label on one surface uses one voice, and voices are never mixed within a single row.
+ *
+ * Why a plain string union and not a `const enum`: this type crosses the package boundary into
+ * consumers' `.d.ts`, and a cross-boundary `const enum` breaks `isolatedModules` / Babel-only
+ * builds. `@dloizides/ui-buttons` sets the same precedent for `ButtonVariant` for the same reason.
+ */
+
+/** Which of the two contract voices a field label speaks. */
+type FieldLabelVariant = 'field' | 'control';
+
+/**
+ * Field — the generic "label over a control, hint + error under it" wrapper.
  *
  * `FormField` is hard-wired to a text input, so any NON-text control (a dropdown, a date picker,
  * a chip selector) had no shared way to get a label — and ended up visually misaligned next to
@@ -13,26 +36,151 @@ import { ViewStyle, TextInputProps, TextInput, TextStyle } from 'react-native';
  * truth: `FormField` composes `Field` internally, so the two can never drift apart.
  *
  * Children may be a plain node (the common case — just wrap your control) or a render function
- * receiving `{ describedById, hasError }`, so a custom control can wire the error line into its
- * own `aria-describedby` / invalid state exactly the way `FormField` does.
+ * receiving `{ describedById, hasError }`, so a custom control can wire the hint AND error lines
+ * into its own `aria-describedby` / invalid state exactly the way `FormField` does.
+ *
+ * The anatomy (label → control → hint → error), the two label voices, the mutually-exclusive
+ * required/optional markers and the collapsing error slot all implement the shared cross-stack
+ * contract in `PROOViD/AMLService/AMLService/wwwroot/shared/FORMS.md`.
  */
 
 /** What a render-function child receives, so it can mirror `FormField`'s error wiring. */
 interface FieldChildContext {
-    /** id of the rendered error line, or `undefined` when there is no error. */
+    /**
+     * Space-separated ids of the lines describing this control — the hint, the error, or both, in
+     * reading order. `undefined` when there is neither. Assign straight to `aria-describedby`.
+     */
     describedById?: string;
     hasError: boolean;
 }
 type FieldChildren = React.ReactNode | ((context: FieldChildContext) => React.ReactNode);
 interface FieldProps {
-    label: string;
+    /**
+     * Label shown above the control. Optional so a control whose label is supplied elsewhere (or
+     * which genuinely has none) can still use the shared shell for its error line + spacing: an
+     * absent or empty label renders NO label row at all, rather than an empty one that would add a
+     * phantom gap and misalign the control against its labelled siblings.
+     */
+    label?: string;
     children: FieldChildren;
     required?: boolean;
+    /**
+     * Marks the field explicitly optional. MUTUALLY EXCLUSIVE with `required` — if both are set,
+     * `required` wins (the safe direction: an under-marked required field causes a failed submit).
+     * Use it to mark the MINORITY: on a mostly-required form, marking the two optional fields is far
+     * less noise than asterisking the other eleven.
+     */
+    optional?: boolean;
+    /**
+     * Pre-localized text for the optional marker. Defaults to the English `DEFAULT_OPTIONAL_LABEL`
+     * so a single-locale app can adopt `optional` in one line; a localized app MUST pass this.
+     */
+    optionalLabel?: string;
+    /**
+     * Help line rendered UNDER the control and ABOVE the error — the sentence that stops the user
+     * guessing. It coexists with `error` (the hint states the rule, the error says which rule was
+     * broken) and both are reachable from the control via `aria-describedby`.
+     *
+     * Rendering a hint INSIDE the field is the point: as an outside sibling it lands past the
+     * container's 16px bottom margin and detaches from the control it explains.
+     */
+    hint?: string;
     error?: string;
-    containerStyle?: ViewStyle;
+    /**
+     * Which of the two contract label voices to speak: `field` (13/600 sentence case — the default,
+     * unchanged) or `control` (11/700 uppercase — dense filter bars and toolbars).
+     */
+    labelVariant?: FieldLabelVariant;
+    /**
+     * Escape hatch applied AFTER `labelVariant`, for the genuine one-off a variant does not cover.
+     * Prefer `labelVariant`: it is the reviewable, named choice, and a bare `labelStyle` is the thing
+     * to grep for when auditing label drift.
+     */
+    labelStyle?: StyleProp<TextStyle>;
+    /**
+     * `StyleProp` (not a bare `ViewStyle`) so a caller can compose an array — e.g. a base field style
+     * plus a `grow` modifier — instead of having to restate a COMPLETE style per variant.
+     */
+    containerStyle?: StyleProp<ViewStyle>;
     testID?: string;
 }
-declare const Field: ({ label, children, required, error, containerStyle, testID, }: FieldProps) => React.ReactElement;
+declare const Field: ({ label, children, required, optional, optionalLabel, hint, error, labelVariant, labelStyle, containerStyle, testID, }: FieldProps) => React.ReactElement;
+
+/**
+ * Required / optional markers, per the shared forms contract
+ * (`…/wwwroot/shared/FORMS.md` → "Required and optional markers").
+ *
+ * The contract says the two markers are MUTUALLY EXCLUSIVE — a field is required or optional, never
+ * annotated as both — and that you mark the MINORITY: on a mostly-required form mark the optional
+ * fields, on a mostly-optional form mark the required ones. Asterisking twelve of thirteen fields
+ * is noise that trains the eye to ignore the marker.
+ *
+ * Exclusivity is enforced here rather than in the type system so that a caller spreading a props
+ * object (`<Field {...fieldProps} />`, where both flags may be computed) still gets a defined,
+ * single-marker result instead of a compile error it cannot act on.
+ *
+ * Precedence when a caller asks for BOTH: `required` wins. That is the safe failure direction —
+ * showing "optional" on a field the server will reject sends the user into a failed submit, while
+ * showing "required" on a genuinely optional field costs, at worst, an unnecessary keystroke.
+ */
+/** Which marker a field label carries. Exactly one, never both. */
+type FieldMarker = 'none' | 'required' | 'optional';
+/**
+ * The English fallback for the optional marker's text.
+ *
+ * `@dloizides/ui-forms` contains NO i18n runtime by design — aml-v2 uses `@dloizides/i18n` with
+ * positional `{0}` params while the other six apps use i18next `{{p1}}`, and nothing bridges them,
+ * so all user-visible copy arrives as pre-localized props. This constant exists ONLY so a
+ * single-locale app can adopt `optional` in one line. It is exported precisely so it is greppable:
+ * **a localized app MUST pass `optionalLabel`.** The required marker needs no such escape — `*` is
+ * a glyph, not copy.
+ */
+declare const DEFAULT_OPTIONAL_LABEL = "(optional)";
+
+/**
+ * `FormActions` — the submit/cancel button row every form ends with.
+ *
+ * Promoted from the BYTE-IDENTICAL `erevna-web/src/components/Forms/FormActions.tsx` and
+ * `katalogos-web/src/components/Forms/FormActions.tsx` (68 lines each, `diff` returns nothing);
+ * all seven apps hand-roll the same row. Buttons come from the shared `@dloizides/ui-buttons` kit
+ * rather than being forked here, so there is exactly one button implementation in the estate.
+ *
+ * The layout implements the contract's actions row
+ * (`…/wwwroot/shared/FORMS.md` → "Actions row"): the primary action is LAST in DOM order, so tab
+ * order reaches Cancel before Save, and `saving` drives the primary button's spinner rather than
+ * disabling-and-relabelling it.
+ *
+ * Two minimal generalizations over the app-local twins:
+ *  1. Labels and hints arrive as PRE-LOCALIZED props. The twins called `FM()` internally, which
+ *     cannot work here: aml-v2 localizes via `@dloizides/i18n` with positional `{0}` params while
+ *     the other six use i18next `{{p1}}`, and nothing bridges them.
+ *  2. `testID`s are overridable but default to the twins' `save-button` / `cancel-button`, so the
+ *     existing Playwright selectors in every app keep matching.
+ */
+
+interface FormActionsProps {
+    /** Submit handler. May be async — the shared Button drives its own spinner for the promise. */
+    onSave: () => void | Promise<unknown>;
+    /** Cancel handler. Omit it entirely to render a save-only row (no empty Cancel slot). */
+    onCancel?: () => void | Promise<unknown>;
+    /** Pre-localized label for the primary action. */
+    saveLabel: string;
+    /** Pre-localized label for the cancel action. Required whenever `onCancel` is supplied. */
+    cancelLabel?: string;
+    /** Pre-localized accessibility hint for the primary action. Falls back to its label. */
+    saveHint?: string;
+    /** Pre-localized accessibility hint for the cancel action. Falls back to its label. */
+    cancelHint?: string;
+    /** In-flight submit: spins the primary action and disables cancel so the form can't be abandoned mid-write. */
+    saving?: boolean;
+    /** Disables the primary action independently of `saving` (e.g. an invalid form). */
+    saveDisabled?: boolean;
+    containerStyle?: StyleProp<ViewStyle>;
+    saveTestID?: string;
+    cancelTestID?: string;
+    testID?: string;
+}
+declare const FormActions: ({ onSave, onCancel, saveLabel, cancelLabel, saveHint, cancelHint, saving, saveDisabled, containerStyle, saveTestID, cancelTestID, testID, }: FormActionsProps) => React.ReactElement;
 
 /**
  * Reusable form field — labelled text input with optional required mark + error.
@@ -117,6 +265,12 @@ declare function useThemedInput(options?: UseThemedInputOptions): ThemedInput;
  *  - `outline` — the AML v1 console look: an outlined pill on a muted fill; selected = a subtle
  *    tinted-outline (primary border + primary ink + a low-alpha primary wash), NOT a solid fill.
  *    Hover (web) lifts the border/ink to the primary colour.
+ *
+ * The label row, the error line and the container spacing come from the shared `Field` wrapper —
+ * NOT from a local `<Text>`. Its own label used to drift from `Field` on three of four axes
+ * (`marginBottom: 8` vs 4, no `fontSize` at all so ~14 vs 13, `colors.text` vs `textSecondary`),
+ * so a `ChipSelector` next to a `FormField` in a row/grid started a different distance down the
+ * column and read as a different weight of text. Now there is exactly one label implementation.
  */
 
 /** Visual variant. `solid` = filled selected pill (default); `outline` = v1 tinted-outline. */
@@ -126,6 +280,7 @@ interface ChipOption<T> {
     label: string;
 }
 interface ChipSelectorProps<T> {
+    /** Optional — with no label, no label row is rendered (no phantom gap above the chips). */
     label?: string;
     options: Array<ChipOption<T>>;
     value: T | T[];
@@ -135,8 +290,25 @@ interface ChipSelectorProps<T> {
     /** Visual variant. `solid` (default) = filled selected pill; `outline` = v1 tinted-outline. */
     variant?: ChipVariant;
     containerStyle?: ViewStyle;
+    /** Marks the selection mandatory — renders `Field`'s decorative `*` next to the label. */
+    required?: boolean;
+    /** Validation message under the chips, wired to the chip group via `aria-describedby`. */
+    error?: string;
+    testID?: string;
+    /**
+     * Stem for each chip's testID — a chip becomes `${chipTestIDPrefix}-${value}`. Defaults to
+     * `chip-selector-chip`, which existing specs select on; supply your own when a screen has
+     * several chip groups that must be addressed independently.
+     */
+    chipTestIDPrefix?: string;
+    /**
+     * Accessibility hint applied to every chip in the group. Supply a LOCALIZED string — the
+     * built-in default (`Selects <label>`) is English-only and exists solely so pre-existing
+     * consumers keep their current announcement.
+     */
+    optionAccessibilityHint?: string;
 }
-declare const ChipSelector: <T extends string | number>({ label, options, value, onChange, multiple, disabled, variant, containerStyle, }: ChipSelectorProps<T>) => React.ReactElement;
+declare const ChipSelector: <T extends string | number>({ label, options, value, onChange, multiple, disabled, variant, containerStyle, required, error, testID, chipTestIDPrefix, optionAccessibilityHint, }: ChipSelectorProps<T>) => React.ReactElement;
 
 /**
  * Reusable form switch/toggle with an optional description.
@@ -179,4 +351,4 @@ interface FormCheckboxProps {
 }
 declare const FormCheckbox: ({ label, value, onValueChange, onChange, hint, description, disabled, containerStyle, testID, accessibilityLabel, accessibilityHint, }: FormCheckboxProps) => React.ReactElement;
 
-export { type ChipOption, ChipSelector, type ChipSelectorProps, type ChipVariant, Field, type FieldChildContext, type FieldChildren, type FieldProps, FormCheckbox, type FormCheckboxProps, FormField, type FormFieldProps, FormSwitch, type FormSwitchProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, type UseThemedInputOptions, useThemedInput };
+export { type ChipOption, ChipSelector, type ChipSelectorProps, type ChipVariant, DEFAULT_OPTIONAL_LABEL, Field, type FieldChildContext, type FieldChildren, type FieldLabelVariant, type FieldMarker, type FieldProps, FormActions, type FormActionsProps, FormCheckbox, type FormCheckboxProps, FormField, type FormFieldProps, FormSwitch, type FormSwitchProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, type UseThemedInputOptions, useThemedInput };