@dloizides/ui-forms 1.14.0 → 1.16.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.15.0
+
+**`FormSwitch` now emits `aria-checked` / `aria-disabled` on web; `ChipSelector` gained an option icon slot and opt-in radio semantics.**
+
+`FormSwitch` (A11Y-ARIA-CHECKED-1): react-native-web 0.21 emits nothing from `accessibilityState` on web, so the
+switch wrapper rendered `role="switch"` with no `aria-checked` - an invalid switch that announced no state. The
+state is now passed as literal `aria-checked` (always) and `aria-disabled` (only when disabled) web props;
+`accessibilityState` also carries `disabled` for native.
+
+`ChipSelector`:
+- `ChipOption.icon?: React.ReactNode` - rendered before the label inside the chip, wrapped `aria-hidden`. Options
+  without an icon render the exact same tree as before.
+- `singleSelectRole?: 'button' | 'radio'` (type `ChipSingleSelectRole`). Default `button` = unchanged. With
+  `radio` and `multiple` unset, the group is `role="radiogroup"` and each chip `role="radio"` + `aria-checked`.
+  Ignored for multi-select. Trade-off: RN-web renders a radio chip as a `<div>`, which activates on Enter but not
+  Space and has no arrow-key roving focus.
+
+**Additive and backward-compatible.** No prop set = identical DOM for every existing consumer.
+
 ## 1.14.0
 
 **`FormField` gained an opt-in `recentKey` — remember the last N submitted values and offer them on focus.**

package/dist/index.d.mts

@@ -525,27 +525,24 @@ declare function useRecentValues(key: string, max?: number): RecentValues;
 declare const DEFAULT_MAX_RECENTS = 10;
 
 /**
- * Chip/pill selector for selecting one or multiple options.
- *
- * Two visual variants (both fully theme-driven):
- *  - `solid` (default) — the original filled-pill look: selected = solid primary fill with
- *    white ink. Unchanged, so existing consumers (erevna / katalogos / kefi) render identically.
- *  - `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.
+ * Public + internal types for ChipSelector. Split out of `ChipSelector.tsx` so the component, its
+ * two chip variants and the radio keyboard hook can share them without a circular import.
  */
 
 /** Visual variant. `solid` = filled selected pill (default); `outline` = v1 tinted-outline. */
 type ChipVariant = 'solid' | 'outline';
+/**
+ * Role of a SINGLE-select chip. `button` (default) = today's semantics; `radio` = opt-in
+ * `radiogroup` of `radio` chips carrying `aria-checked`. Ignored when `multiple` is set.
+ * A string union rather than a `const enum` to match `ChipVariant`: a const enum does not
+ * survive the package boundary for consumers compiled with `isolatedModules`.
+ */
+type ChipSingleSelectRole = 'button' | 'radio';
 interface ChipOption<T> {
     value: T;
     label: string;
+    /** Optional decorative icon rendered before the label; hidden from assistive tech. */
+    icon?: React.ReactNode;
 }
 interface ChipSelectorProps<T> {
     /** Optional — with no label, no label row is rendered (no phantom gap above the chips). */
@@ -585,8 +582,37 @@ interface ChipSelectorProps<T> {
      * consumers keep their current announcement.
      */
     optionAccessibilityHint?: string;
+    /**
+     * Opt-in radio semantics for a SINGLE-select group: the group becomes `role="radiogroup"` and
+     * each chip `role="radio"` + `aria-checked`, with the WAI-ARIA radio group keyboard pattern
+     * (Space activates, arrow keys move focus + selection with wrap, one roving tab stop).
+     * Defaults to `button` (unchanged behaviour). Ignored when `multiple` is set — a multi chip
+     * stays a toggle button with `aria-pressed`.
+     */
+    singleSelectRole?: ChipSingleSelectRole;
 }
-declare const ChipSelector: <T extends string | number>({ label, options, value, onChange, multiple, disabled, variant, containerStyle, spacing, required, error, testID, chipTestIDPrefix, optionAccessibilityHint, }: ChipSelectorProps<T>) => React.ReactElement;
+
+/**
+ * Chip/pill selector for selecting one or multiple options.
+ *
+ * Two visual variants (both fully theme-driven):
+ *  - `solid` (default) — the original filled-pill look: selected = solid primary fill with
+ *    white ink. Unchanged, so existing consumers (erevna / katalogos / kefi) render identically.
+ *  - `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.
+ *
+ * Structure: chip variants in `components/`, the radio keyboard wiring in `hooks/`, and the pure
+ * resolvers (`chipIdentity`, colours, radio key logic) in `utils/`.
+ */
+
+declare const ChipSelector: <T extends string | number>({ label, options, value, onChange, multiple, disabled, variant, containerStyle, spacing, required, error, testID, chipTestIDPrefix, optionAccessibilityHint, singleSelectRole, }: ChipSelectorProps<T>) => React.ReactElement;
 
 /**
  * Reusable form switch/toggle with an optional description.
@@ -944,4 +970,60 @@ declare function suggestOptions(options: readonly ControlOption[], query: string
 /** True when `text` is non-empty yet matches no option's value or label exactly (case-insensitive). */
 declare function isUnmatched(options: readonly ControlOption[], text: string): boolean;
 
-export { AnchoredMenu, type AnchoredMenuColors, type AnchoredMenuProps, type ChipOption, ChipSelector, type ChipSelectorProps, type ChipVariant, type ControlOption, DEFAULT_MAX_RECENTS, DEFAULT_OPTIONAL_LABEL, DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS, DEFAULT_TYPEAHEAD_MIN_CHARS, DateRangeControl, type DateRangeControlProps, type DateRangeValue, Field, type FieldChildContext, type FieldChildren, type FieldLabelVariant, type FieldMarker, type FieldProps, type FieldSpacing, FormActions, type FormActionsProps, FormCell, type FormCellProps, FormCheckbox, type FormCheckboxProps, FormField, type FormFieldProps, FormGrid, type FormGridProps, FormSection, type FormSectionProps, FormSwitch, type FormSwitchProps, type RecentValues, SelectControl, type SelectControlProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, TypeaheadControl, type TypeaheadControlProps, type UseThemedInputOptions, controlStyles, isUnmatched, suggestOptions, useRecentValues, useThemedInput };
+/**
+ * Group selection — the pure tri-state logic behind a "select all" / "select this category"
+ * control, kept out of any component so it is testable as LOGIC rather than through the DOM.
+ *
+ * ## Why it lives here and not in @dloizides/ui-tables
+ *
+ * `ui-tables` already had this arithmetic inside `DataTable/selection.ts`, but deliberately
+ * unexported: its tri-state is a `const enum`, which in a published `.d.ts` is an ambient const
+ * enum that every `isolatedModules` consumer rejects. It is also page-scoped and wired to the
+ * table's select-all banner. So the second consumer (a 12-tile console picker with no table in
+ * sight, and no reason to pull a table package into its bundle budget) could not reach it.
+ *
+ * This module is the extraction: domain-neutral (keys in, keys out — nothing here knows what a
+ * key *is*), component-free, and crossing the package boundary as a plain interface rather than
+ * an enum. `ui-tables` can adopt it and delete its private copy.
+ */
+/**
+ * A group's tri-state, as two booleans rather than an enum.
+ *
+ * `all` and `some` are mutually exclusive: a fully selected group is `{ all: true, some: false }`,
+ * so a caller can branch on `all` then `some` without re-deriving "partial" itself. Both false
+ * means nothing in the group is selected — which is also what an EMPTY group reports, because an
+ * empty group is neither fully nor partially selected.
+ */
+interface GroupSelection {
+    /** Every key in the group is selected (never true for an empty group). */
+    readonly all: boolean;
+    /** At least one, but not every, key in the group is selected — the mixed/indeterminate state. */
+    readonly some: boolean;
+}
+/**
+ * Resolve a group's tri-state from the selection ∩ the group.
+ *
+ * Scoped to the GROUP, not to the whole selection: selected keys OUTSIDE the group must never
+ * make this group look partially selected.
+ */
+declare function resolveGroupSelection<T>(selected: readonly T[], groupKeys: readonly T[]): GroupSelection;
+/**
+ * The value an `aria-checked` / `accessibilityState` consumer needs for a tri-state control.
+ *
+ * A partially selected group is `'mixed'`, which is what makes a screen reader announce the
+ * control honestly instead of claiming the whole category is on.
+ */
+declare function groupAriaChecked(state: GroupSelection): boolean | 'mixed';
+/**
+ * Toggle a whole group, returning the NEXT selection array. Pure — never mutates the input.
+ *
+ * All-on → off. Partial or off → on: the conventional behaviour, and the one a mixed checkbox
+ * looks like it will do. Keys OUTSIDE the group always survive untouched, so a category control
+ * can never silently clear a selection it does not own.
+ *
+ * `order`, when given, is the canonical key order the result is sorted into (catalogue order, say)
+ * so the selection does not carry click order around. Without it, newly added keys are appended.
+ */
+declare function toggleGroupSelection<T>(selected: readonly T[], groupKeys: readonly T[], order?: readonly T[]): T[];
+
+export { AnchoredMenu, type AnchoredMenuColors, type AnchoredMenuProps, type ChipOption, ChipSelector, type ChipSelectorProps, type ChipSingleSelectRole, type ChipVariant, type ControlOption, DEFAULT_MAX_RECENTS, DEFAULT_OPTIONAL_LABEL, DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS, DEFAULT_TYPEAHEAD_MIN_CHARS, DateRangeControl, type DateRangeControlProps, type DateRangeValue, Field, type FieldChildContext, type FieldChildren, type FieldLabelVariant, type FieldMarker, type FieldProps, type FieldSpacing, FormActions, type FormActionsProps, FormCell, type FormCellProps, FormCheckbox, type FormCheckboxProps, FormField, type FormFieldProps, FormGrid, type FormGridProps, FormSection, type FormSectionProps, FormSwitch, type FormSwitchProps, type GroupSelection, type RecentValues, SelectControl, type SelectControlProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, TypeaheadControl, type TypeaheadControlProps, type UseThemedInputOptions, controlStyles, groupAriaChecked, isUnmatched, resolveGroupSelection, suggestOptions, toggleGroupSelection, useRecentValues, useThemedInput };

package/dist/index.d.ts

@@ -525,27 +525,24 @@ declare function useRecentValues(key: string, max?: number): RecentValues;
 declare const DEFAULT_MAX_RECENTS = 10;
 
 /**
- * Chip/pill selector for selecting one or multiple options.
- *
- * Two visual variants (both fully theme-driven):
- *  - `solid` (default) — the original filled-pill look: selected = solid primary fill with
- *    white ink. Unchanged, so existing consumers (erevna / katalogos / kefi) render identically.
- *  - `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.
+ * Public + internal types for ChipSelector. Split out of `ChipSelector.tsx` so the component, its
+ * two chip variants and the radio keyboard hook can share them without a circular import.
  */
 
 /** Visual variant. `solid` = filled selected pill (default); `outline` = v1 tinted-outline. */
 type ChipVariant = 'solid' | 'outline';
+/**
+ * Role of a SINGLE-select chip. `button` (default) = today's semantics; `radio` = opt-in
+ * `radiogroup` of `radio` chips carrying `aria-checked`. Ignored when `multiple` is set.
+ * A string union rather than a `const enum` to match `ChipVariant`: a const enum does not
+ * survive the package boundary for consumers compiled with `isolatedModules`.
+ */
+type ChipSingleSelectRole = 'button' | 'radio';
 interface ChipOption<T> {
     value: T;
     label: string;
+    /** Optional decorative icon rendered before the label; hidden from assistive tech. */
+    icon?: React.ReactNode;
 }
 interface ChipSelectorProps<T> {
     /** Optional — with no label, no label row is rendered (no phantom gap above the chips). */
@@ -585,8 +582,37 @@ interface ChipSelectorProps<T> {
      * consumers keep their current announcement.
      */
     optionAccessibilityHint?: string;
+    /**
+     * Opt-in radio semantics for a SINGLE-select group: the group becomes `role="radiogroup"` and
+     * each chip `role="radio"` + `aria-checked`, with the WAI-ARIA radio group keyboard pattern
+     * (Space activates, arrow keys move focus + selection with wrap, one roving tab stop).
+     * Defaults to `button` (unchanged behaviour). Ignored when `multiple` is set — a multi chip
+     * stays a toggle button with `aria-pressed`.
+     */
+    singleSelectRole?: ChipSingleSelectRole;
 }
-declare const ChipSelector: <T extends string | number>({ label, options, value, onChange, multiple, disabled, variant, containerStyle, spacing, required, error, testID, chipTestIDPrefix, optionAccessibilityHint, }: ChipSelectorProps<T>) => React.ReactElement;
+
+/**
+ * Chip/pill selector for selecting one or multiple options.
+ *
+ * Two visual variants (both fully theme-driven):
+ *  - `solid` (default) — the original filled-pill look: selected = solid primary fill with
+ *    white ink. Unchanged, so existing consumers (erevna / katalogos / kefi) render identically.
+ *  - `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.
+ *
+ * Structure: chip variants in `components/`, the radio keyboard wiring in `hooks/`, and the pure
+ * resolvers (`chipIdentity`, colours, radio key logic) in `utils/`.
+ */
+
+declare const ChipSelector: <T extends string | number>({ label, options, value, onChange, multiple, disabled, variant, containerStyle, spacing, required, error, testID, chipTestIDPrefix, optionAccessibilityHint, singleSelectRole, }: ChipSelectorProps<T>) => React.ReactElement;
 
 /**
  * Reusable form switch/toggle with an optional description.
@@ -944,4 +970,60 @@ declare function suggestOptions(options: readonly ControlOption[], query: string
 /** True when `text` is non-empty yet matches no option's value or label exactly (case-insensitive). */
 declare function isUnmatched(options: readonly ControlOption[], text: string): boolean;
 
-export { AnchoredMenu, type AnchoredMenuColors, type AnchoredMenuProps, type ChipOption, ChipSelector, type ChipSelectorProps, type ChipVariant, type ControlOption, DEFAULT_MAX_RECENTS, DEFAULT_OPTIONAL_LABEL, DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS, DEFAULT_TYPEAHEAD_MIN_CHARS, DateRangeControl, type DateRangeControlProps, type DateRangeValue, Field, type FieldChildContext, type FieldChildren, type FieldLabelVariant, type FieldMarker, type FieldProps, type FieldSpacing, FormActions, type FormActionsProps, FormCell, type FormCellProps, FormCheckbox, type FormCheckboxProps, FormField, type FormFieldProps, FormGrid, type FormGridProps, FormSection, type FormSectionProps, FormSwitch, type FormSwitchProps, type RecentValues, SelectControl, type SelectControlProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, TypeaheadControl, type TypeaheadControlProps, type UseThemedInputOptions, controlStyles, isUnmatched, suggestOptions, useRecentValues, useThemedInput };
+/**
+ * Group selection — the pure tri-state logic behind a "select all" / "select this category"
+ * control, kept out of any component so it is testable as LOGIC rather than through the DOM.
+ *
+ * ## Why it lives here and not in @dloizides/ui-tables
+ *
+ * `ui-tables` already had this arithmetic inside `DataTable/selection.ts`, but deliberately
+ * unexported: its tri-state is a `const enum`, which in a published `.d.ts` is an ambient const
+ * enum that every `isolatedModules` consumer rejects. It is also page-scoped and wired to the
+ * table's select-all banner. So the second consumer (a 12-tile console picker with no table in
+ * sight, and no reason to pull a table package into its bundle budget) could not reach it.
+ *
+ * This module is the extraction: domain-neutral (keys in, keys out — nothing here knows what a
+ * key *is*), component-free, and crossing the package boundary as a plain interface rather than
+ * an enum. `ui-tables` can adopt it and delete its private copy.
+ */
+/**
+ * A group's tri-state, as two booleans rather than an enum.
+ *
+ * `all` and `some` are mutually exclusive: a fully selected group is `{ all: true, some: false }`,
+ * so a caller can branch on `all` then `some` without re-deriving "partial" itself. Both false
+ * means nothing in the group is selected — which is also what an EMPTY group reports, because an
+ * empty group is neither fully nor partially selected.
+ */
+interface GroupSelection {
+    /** Every key in the group is selected (never true for an empty group). */
+    readonly all: boolean;
+    /** At least one, but not every, key in the group is selected — the mixed/indeterminate state. */
+    readonly some: boolean;
+}
+/**
+ * Resolve a group's tri-state from the selection ∩ the group.
+ *
+ * Scoped to the GROUP, not to the whole selection: selected keys OUTSIDE the group must never
+ * make this group look partially selected.
+ */
+declare function resolveGroupSelection<T>(selected: readonly T[], groupKeys: readonly T[]): GroupSelection;
+/**
+ * The value an `aria-checked` / `accessibilityState` consumer needs for a tri-state control.
+ *
+ * A partially selected group is `'mixed'`, which is what makes a screen reader announce the
+ * control honestly instead of claiming the whole category is on.
+ */
+declare function groupAriaChecked(state: GroupSelection): boolean | 'mixed';
+/**
+ * Toggle a whole group, returning the NEXT selection array. Pure — never mutates the input.
+ *
+ * All-on → off. Partial or off → on: the conventional behaviour, and the one a mixed checkbox
+ * looks like it will do. Keys OUTSIDE the group always survive untouched, so a category control
+ * can never silently clear a selection it does not own.
+ *
+ * `order`, when given, is the canonical key order the result is sorted into (catalogue order, say)
+ * so the selection does not carry click order around. Without it, newly added keys are appended.
+ */
+declare function toggleGroupSelection<T>(selected: readonly T[], groupKeys: readonly T[], order?: readonly T[]): T[];
+
+export { AnchoredMenu, type AnchoredMenuColors, type AnchoredMenuProps, type ChipOption, ChipSelector, type ChipSelectorProps, type ChipSingleSelectRole, type ChipVariant, type ControlOption, DEFAULT_MAX_RECENTS, DEFAULT_OPTIONAL_LABEL, DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS, DEFAULT_TYPEAHEAD_MIN_CHARS, DateRangeControl, type DateRangeControlProps, type DateRangeValue, Field, type FieldChildContext, type FieldChildren, type FieldLabelVariant, type FieldMarker, type FieldProps, type FieldSpacing, FormActions, type FormActionsProps, FormCell, type FormCellProps, FormCheckbox, type FormCheckboxProps, FormField, type FormFieldProps, FormGrid, type FormGridProps, FormSection, type FormSectionProps, FormSwitch, type FormSwitchProps, type GroupSelection, type RecentValues, SelectControl, type SelectControlProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, TypeaheadControl, type TypeaheadControlProps, type UseThemedInputOptions, controlStyles, groupAriaChecked, isUnmatched, resolveGroupSelection, suggestOptions, toggleGroupSelection, useRecentValues, useThemedInput };