@dloizides/ui-forms 1.15.0 → 1.16.0

package/dist/index.d.mts

@@ -970,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 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 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

@@ -970,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 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 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.js

@@ -1679,6 +1679,30 @@ function DateRangeControl({
   ] });
 }
 
+// src/groupSelection/groupSelection.ts
+var NONE = 0;
+function countSelected(selected, groupKeys) {
+  return groupKeys.filter((key) => selected.includes(key)).length;
+}
+function resolveGroupSelection(selected, groupKeys) {
+  const count = countSelected(selected, groupKeys);
+  if (count === NONE) return { all: false, some: false };
+  return count === groupKeys.length ? { all: true, some: false } : { all: false, some: true };
+}
+function groupAriaChecked(state) {
+  if (state.all) return true;
+  return state.some ? "mixed" : false;
+}
+function toggleGroupSelection(selected, groupKeys, order) {
+  const { all } = resolveGroupSelection(selected, groupKeys);
+  if (all) return selected.filter((key) => !groupKeys.includes(key));
+  const merged = [...selected];
+  groupKeys.forEach((key) => {
+    if (!merged.includes(key)) merged.push(key);
+  });
+  return order === void 0 ? merged : order.filter((key) => merged.includes(key));
+}
+
 exports.AnchoredMenu = AnchoredMenu;
 exports.ChipSelector = ChipSelector;
 exports.DEFAULT_MAX_RECENTS = DEFAULT_MAX_RECENTS;
@@ -1698,8 +1722,11 @@ exports.SelectControl = SelectControl;
 exports.ThemedTextInput = ThemedTextInput;
 exports.TypeaheadControl = TypeaheadControl;
 exports.controlStyles = controlStyles;
+exports.groupAriaChecked = groupAriaChecked;
 exports.isUnmatched = isUnmatched;
+exports.resolveGroupSelection = resolveGroupSelection;
 exports.suggestOptions = suggestOptions;
+exports.toggleGroupSelection = toggleGroupSelection;
 exports.useRecentValues = useRecentValues;
 exports.useThemedInput = useThemedInput;
 //# sourceMappingURL=index.js.map