vultus-core 0.4.0 → 0.5.1

package/src/kinds.ts

@@ -0,0 +1,208 @@
+import { resolveChoice, type OneOfChoice, type OneOfChoiceControls } from './choices.js';
+import type { FieldBaseOptions, FieldKind } from './field.js';
+import type { FieldCtx } from './FieldContext.js';
+import { clamp, fit, resolveNumeric } from './numeric.js';
+import { resolveIn } from './resolve.js';
+import { normalizeTreeValue, type TreeNode } from './tree.js';
+import type { Fits, ValueOrFn } from './types.js';
+import { boolInitialValue, type useBoolField } from './useBoolField.js';
+import { manyOfInitialValue, type ManyOfOwnOptions, type useManyOfField } from './useManyOfField.js';
+import { mixedBoolInitialValue, type MixedBool, type useMixedBoolField } from './useMixedBoolField.js';
+import { numericInitialValue, type NumericOwnOptions, type useNumericField } from './useNumericField.js';
+import { oneOfInitialValue, type OneOfOwnOptions, type useOneOfField } from './useOneOfField.js';
+import { rangeInitialValue, type NumberRange, type RangeOwnOptions, type useRangeField } from './useRangeField.js';
+import { textInitialValue, type TextOwnOptions, type useTextField } from './useTextField.js';
+import { treeInitialValue, type TreeOwnOptions, type useTreeField } from './useTreeField.js';
+import { booleanType, numberType, rangeType, stringSetType, stringType, type ValueType } from './valueTypes.js';
+
+/**
+ * A definition of kind `K`: the kind's hook options in their inside form, with `kind` required.
+ * It has no `value`, `onChange` or `commit`: where the value lives is chosen by whoever runs the
+ * field, and a store holds the definition's initial value as its default.
+ */
+type Definition<K extends FieldKind, V, Own, Ctx> =
+  { kind: K } & FieldBaseOptions<V, Ctx> & { initialValue?: ValueOrFn<V, Ctx> } & Own;
+
+/**
+ * A field as plain data (a module's filters, a dialog's options), tagged by its kind. Narrowed
+ * by `kind`, a definition is its kind's hook options as they are: `useOneOfField(definition)`.
+ * Its functions receive the field context `Ctx` (see FieldContextProvider).
+ */
+export type FieldDefinition<Ctx = any> =
+  | Definition<'boolean', boolean, {}, Ctx>
+  | Definition<'mixed-boolean', MixedBool, {}, Ctx>
+  | Definition<'oneOf', string, OneOfOwnOptions<string, Ctx>, Ctx>
+  | Definition<'manyOf', string[], ManyOfOwnOptions<string, Ctx>, Ctx>
+  | Definition<'numeric', number, NumericOwnOptions<Ctx>, Ctx>
+  | Definition<'range', NumberRange, RangeOwnOptions<Ctx>, Ctx>
+  | Definition<'tree', string[], TreeOwnOptions<string, Ctx>, Ctx>
+  | Definition<'text', string, TextOwnOptions, Ctx>;
+
+type DefinitionOf<K extends FieldKind> = Extract<FieldDefinition, { kind: K }>;
+type HookOptions<H extends (...args: any[]) => unknown> = Parameters<H>[0];
+
+/**
+ * A compile-time check, the gate for "a definition is its kind's hook options as they are": if a
+ * hook's options and the definition drift apart, `tsc` fails here.
+ */
+type DefinitionsFitTheirHooks = [
+  Fits<DefinitionOf<'boolean'>, HookOptions<typeof useBoolField>>,
+  Fits<DefinitionOf<'mixed-boolean'>, HookOptions<typeof useMixedBoolField>>,
+  Fits<DefinitionOf<'oneOf'>, HookOptions<typeof useOneOfField>>,
+  Fits<DefinitionOf<'manyOf'>, HookOptions<typeof useManyOfField>>,
+  Fits<DefinitionOf<'numeric'>, HookOptions<typeof useNumericField>>,
+  Fits<DefinitionOf<'range'>, HookOptions<typeof useRangeField>>,
+  Fits<DefinitionOf<'tree'>, HookOptions<typeof useTreeField>>,
+  Fits<DefinitionOf<'text'>, HookOptions<typeof useTextField>>,
+];
+
+const NOT_STORABLE = 'a mixed-boolean field is an aggregate of other data and cannot be stored';
+
+/** A definition whose kind is none of FieldKind's (plain data can carry anything): fail loudly rather than give nothing. */
+function unknownKind(definition: never): never {
+  const { id, kind } = definition as { id: string; kind: unknown };
+  throw new Error(`Field '${id}': unknown kind '${String(kind)}'`);
+}
+
+/** The choices of a one-of or many-of definition, resolved as the hooks resolve them. */
+function choicesOf(definition: { id: string; choices: ValueOrFn<OneOfChoice[]> }, ctx: FieldCtx): OneOfChoiceControls[] {
+  const { id, choices } = definition;
+  return resolveIn<OneOfChoice[]>(choices, [], ctx, `Field '${id}': option 'choices'`).map((c) => resolveChoice(id, c));
+}
+
+/** Every node's value, at any depth. */
+function nodeValues(nodes: TreeNode[], into = new Set<string>()): Set<string> {
+  for (const node of nodes) {
+    into.add(node.value);
+    if (node.children) nodeValues(node.children, into);
+  }
+  return into;
+}
+
+/** A tree definition's nodes, resolved as useTreeField resolves them. */
+function nodesOf(definition: { id: string; nodes: ValueOrFn<TreeNode[]> }, ctx: FieldCtx): TreeNode[] {
+  return resolveIn<TreeNode[]>(definition.nodes, [], ctx, `Field '${definition.id}': option 'nodes'`);
+}
+
+/**
+ * A definition's default: `initialValue` resolved with the field context, else its kind's
+ * implicit initial value (false; the first enabled choice; the empty list; `min`, or 0, clamped
+ * into the bounds; `[min, max]`; the empty string). A tree's comes normalized under its
+ * selection, as the hook shows it, so a value equal to what the field shows by default is equal
+ * to the default too. It is what a store falls back to, what a reset restores, and what "is it
+ * set?" compares against; the kind's hook starts at the same value.
+ */
+export function initialValueOf(definition: FieldDefinition, ctx: FieldCtx): unknown {
+  const { id } = definition;
+  switch (definition.kind) {
+    case 'boolean': return boolInitialValue(definition, ctx, id);
+    case 'mixed-boolean': return mixedBoolInitialValue(definition, ctx, id);
+    case 'oneOf': return oneOfInitialValue(definition, ctx, id, choicesOf(definition, ctx));
+    case 'manyOf': return manyOfInitialValue(definition, ctx, id);
+    case 'numeric': return numericInitialValue(definition, ctx, id);
+    case 'range': return rangeInitialValue(definition, ctx, id);
+    case 'tree':
+      return normalizeTreeValue(nodesOf(definition, ctx), treeInitialValue(definition, ctx, id), definition.selection ?? 'topmost');
+    case 'text': return textInitialValue(definition, ctx, id);
+    default: return unknownKind(definition);
+  }
+}
+
+/** How a kind's value is kept in a store. A mixed-boolean field shows an aggregate of other data, so it has none and throws. */
+export function valueTypeOf(kind: FieldKind): ValueType<any> {
+  switch (kind) {
+    case 'boolean': return booleanType;
+    case 'oneOf':
+    case 'text': return stringType;
+    case 'manyOf':
+    case 'tree': return stringSetType;
+    case 'numeric': return numberType;
+    case 'range': return rangeType;
+    case 'mixed-boolean': throw new Error(NOT_STORABLE);
+    default: throw new Error(`unknown field kind '${String(kind as unknown)}'`);
+  }
+}
+
+function warnDropped(id: string, among: 'choices' | 'nodes', dropped: string[], warn: (message: string) => void): void {
+  if (dropped.length === 0) return;
+  const listed = [...new Set(dropped)].map((v) => `'${v}'`).join(', ');
+  warn(`Field '${id}': dropping stored values that are not among its ${among}: ${listed}`);
+}
+
+/**
+ * A stored value (already parsed by the kind's value type) made fit for the definition as it is
+ * now: choices, nodes and bounds follow the data, and an old URL may not. A one-of value that is
+ * not a choice becomes the initial value; many-of and tree values that are not choices or nodes
+ * are dropped; numbers and ranges are clamped into the bounds, then rounded when the field is
+ * `integer` (so a stored `2.5` reads `3`; a whole number inside the bounds, see `fit`), with one
+ * warning for whichever of the two actually changed the value: "outside its bounds" when
+ * clamping did (whether or not rounding also did), "not a whole number" ("has ends that are not
+ * whole numbers" for a range) when only rounding did. Each such change warns, naming the
+ * field: the value came from outside, so it is not an error. Reordering is silent: lists come
+ * back in choice order or normalized under the tree's selection (a store keeps them sorted, so a
+ * warning would come on every read), and a range's ends in order. The warnings go to `warn`,
+ * console.warn unless a caller that only summarizes (useStoredFields) silences them.
+ */
+export function sanitizeStored(
+  definition: FieldDefinition,
+  value: unknown,
+  ctx: FieldCtx,
+  warn: (message: string) => void = (message) => console.warn(message),
+): unknown {
+  const { id } = definition;
+  switch (definition.kind) {
+    case 'boolean':
+    case 'text':
+      return value;
+    case 'mixed-boolean':
+      throw new Error(`Field '${id}': ${NOT_STORABLE}`);
+    case 'oneOf': {
+      const choices = choicesOf(definition, ctx);
+      if (choices.some((c) => c.value === value)) return value;
+      const fallback = oneOfInitialValue(definition, ctx, id, choices);
+      if (fallback !== value) warn(`Field '${id}': stored value '${value}' is not one of its choices, using '${fallback}'`);
+      return fallback;
+    }
+    case 'manyOf': {
+      const stored = value as string[];
+      const known = choicesOf(definition, ctx).map((c) => c.value);
+      warnDropped(id, 'choices', stored.filter((v) => !known.includes(v)), warn);
+      return known.filter((v) => stored.includes(v));
+    }
+    case 'tree': {
+      const stored = value as string[];
+      const nodes = nodesOf(definition, ctx);
+      const known = nodeValues(nodes);
+      warnDropped(id, 'nodes', stored.filter((v) => !known.has(v)), warn);
+      return normalizeTreeValue(nodes, stored.filter((v) => known.has(v)), definition.selection ?? 'topmost');
+    }
+    case 'numeric': {
+      const stored = value as number;
+      const { min, max, integer } = resolveNumeric(id, definition, ctx);
+      const clamped = clamp(stored, min, max);
+      const fitted = fit(stored, min, max, integer);
+      if (fitted !== stored) {
+        if (clamped !== stored) warn(`Field '${id}': stored value ${stored} is outside its bounds, using ${fitted}`);
+        else warn(`Field '${id}': stored value ${stored} is not a whole number, using ${fitted}`);
+      }
+      return fitted;
+    }
+    case 'range': {
+      const stored = value as NumberRange;
+      const { min, max, integer } = resolveNumeric(id, definition, ctx);
+      const clampedChanged = clamp(stored[0], min, max) !== stored[0] || clamp(stored[1], min, max) !== stored[1];
+      const from = fit(stored[0], min, max, integer);
+      const to = fit(stored[1], min, max, integer);
+      const sanitized: NumberRange = [Math.min(from, to), Math.max(from, to)];
+      if (from !== stored[0] || to !== stored[1]) {
+        if (clampedChanged) {
+          warn(`Field '${id}': stored range ${rangeType.format(stored)} is outside its bounds, using ${rangeType.format(sanitized)}`);
+        } else {
+          warn(`Field '${id}': stored range ${rangeType.format(stored)} has ends that are not whole numbers, using ${rangeType.format(sanitized)}`);
+        }
+      }
+      return sanitized;
+    }
+    default: return unknownKind(definition);
+  }
+}

package/src/localStorageStore.ts

@@ -0,0 +1,68 @@
+import type { ArgStore } from './argStore.js';
+
+/**
+ * An ArgStore over `window.localStorage` (Praeceptor's print options), items kept under
+ * `${prefix}.${key}`. Guarded for SSR/Node (`typeof window === 'undefined'`), so creating one
+ * outside a browser does not crash: reads then give `undefined` and writes are no-ops. A browser
+ * may block storage (a sandboxed frame, blocked site data) or refuse a write (quota), and then
+ * reaching or using `localStorage` throws: a read that fails reads as absent and a write that
+ * fails is skipped, with one warning per store rather than one per call.
+ *
+ * A write notifies this store's own subscribers; a `storage` event (another tab changed a key
+ * under the prefix) notifies them too. The store listens for that event on `window` only while
+ * it has subscribers, so a store that is dropped leaves no listener behind; still, create one
+ * once (outside render, or in `useMemo`) rather than on every render.
+ */
+export function localStorageStore(prefix: string): ArgStore {
+  const hasWindow = typeof window !== 'undefined';
+  const listeners = new Set<() => void>();
+  const storageKey = (key: string) => `${prefix}.${key}`;
+  // `null` means "another tab cleared the whole storage" (localStorage.clear()): every key under
+  // the prefix may have changed, so this counts as ours too.
+  const isOwnStorageKey = (key: string | null) => key === null || key.startsWith(`${prefix}.`);
+  const onStorage = (event: StorageEvent) => {
+    if (isOwnStorageKey(event.key)) listeners.forEach((listener) => listener());
+  };
+
+  let warned = false;
+  /** Runs a use of localStorage; if it throws, warns (the first time for this store) and gives `undefined`. */
+  const guarded = <T>(what: string, use: (storage: Storage) => T): T | undefined => {
+    try {
+      return use(window.localStorage);
+    } catch (error) {
+      if (!warned) {
+        warned = true;
+        console.warn(
+          `localStorageStore('${prefix}'): cannot ${what} localStorage (${String(error)}); `
+          + 'failing reads read as absent and failing writes are skipped, without further warnings',
+        );
+      }
+      return undefined;
+    }
+  };
+
+  return {
+    read(key) {
+      if (!hasWindow) return undefined;
+      return guarded('read', (storage) => storage.getItem(storageKey(key))) ?? undefined;
+    },
+    write(changes, _method) {
+      if (!hasWindow) return;
+      for (const { key, raw } of changes) {
+        guarded('write', (storage) => {
+          if (raw === undefined) storage.removeItem(storageKey(key));
+          else storage.setItem(storageKey(key), raw);
+        });
+      }
+      listeners.forEach((listener) => listener());
+    },
+    subscribe(listener) {
+      if (hasWindow && listeners.size === 0) window.addEventListener('storage', onStorage);
+      listeners.add(listener);
+      return () => {
+        if (!listeners.delete(listener)) return;
+        if (hasWindow && listeners.size === 0) window.removeEventListener('storage', onStorage);
+      };
+    },
+  };
+}

package/src/normalizeText.ts

@@ -0,0 +1,7 @@
+/**
+ * A key for accent- and case-insensitive comparison of labels (the tree hook's search,
+ * Taskmaster's): decompose, strip the combining marks, lower-case. No quaesitor dependency.
+ */
+export function normalizeText(text: string): string {
+  return text.normalize('NFD').replace(/\p{M}/gu, '').toLowerCase();
+}

package/src/numeric.ts

@@ -0,0 +1,80 @@
+import { NO_FIELD_CONTEXT, readingContext, type FieldCtx } from './FieldContext.js';
+import { resolveIn } from './resolve.js';
+import type { ValueOrFn } from './types.js';
+
+/**
+ * The bounds and formatting a numeric field has, shared with the range kind (whose two ends
+ * reuse the same bounds). Each may be a context function, resolved like any other field option.
+ * `format` is not itself a ValueOrFn — it always takes the number as its first argument — so it
+ * is resolved by its own rule, below.
+ */
+export interface NumericBounds<Ctx = any> {
+  min?: ValueOrFn<number | undefined, Ctx>;
+  max?: ValueOrFn<number | undefined, Ctx>;
+  step?: ValueOrFn<number | undefined, Ctx>;
+  integer?: ValueOrFn<boolean, Ctx>;
+  unit?: ValueOrFn<string | undefined, Ctx>;
+  /** Formats a value for display; default: the number followed by the unit, if any. */
+  format?: (n: number, ctx: Ctx) => string;
+}
+
+/** A NumericBounds with every option resolved through the field context. */
+export interface ResolvedNumeric {
+  min: number | undefined;
+  max: number | undefined;
+  step: number | undefined;
+  integer: boolean;
+  unit: string | undefined;
+  format(n: number): string;
+}
+
+/** Clamps `n` into [min, max]; either end left out leaves that side open. */
+export function clamp(n: number, min?: number, max?: number): number {
+  let result = n;
+  if (min !== undefined) result = Math.max(result, min);
+  if (max !== undefined) result = Math.min(result, max);
+  return result;
+}
+
+/**
+ * `n` clamped into [min, max], then, when `integer` is true, rounded and kept to the whole numbers
+ * inside the bounds ([ceil(min), floor(max)]: with `max: 9.5`, 9.7 is 9, not 10): the rule a
+ * numeric or range field's shown value and requests are fit by (useNumericField, useRangeField),
+ * and the one `sanitizeStored` fits a stored value by.
+ */
+export function fit(n: number, min: number | undefined, max: number | undefined, integer: boolean): number {
+  const clamped = clamp(n, min, max);
+  if (!integer) return clamped;
+  return clamp(Math.round(clamped), min === undefined ? undefined : Math.ceil(min), max === undefined ? undefined : Math.floor(max));
+}
+
+/**
+ * Resolves a numeric field's bounds and formatter with the field context. `format` goes by its
+ * own rule, not resolveIn's, as it always receives the number first; otherwise it is treated
+ * the same way. With a provider above, it receives the context as its second argument, and a
+ * key it reads that no provider gave throws naming the field and the option `'format'`. With
+ * none, a `format` that declares the context parameter (`format.length >= 2`) throws the same
+ * message shape resolveIn uses, and one that does not is called with the number alone.
+ */
+export function resolveNumeric(id: string, opts: NumericBounds, ctx: FieldCtx): ResolvedNumeric {
+  const where = (name: string) => `Field '${id}': option '${name}'`;
+  const min = resolveIn<number | undefined>(opts.min, undefined, ctx, where('min'));
+  const max = resolveIn<number | undefined>(opts.max, undefined, ctx, where('max'));
+  const step = resolveIn<number | undefined>(opts.step, undefined, ctx, where('step'));
+  const integer = resolveIn<boolean>(opts.integer, false, ctx, where('integer'));
+  const unit = resolveIn<string | undefined>(opts.unit, undefined, ctx, where('unit'));
+
+  const { format } = opts;
+  let resolvedFormat: (n: number) => string;
+  if (format === undefined) {
+    resolvedFormat = (n) => `${n}${unit ?? ''}`;
+  } else if (ctx !== NO_FIELD_CONTEXT) {
+    resolvedFormat = (n) => readingContext(where('format'), () => format(n, ctx as never));
+  } else if (format.length < 2) {
+    resolvedFormat = (n) => format(n, undefined as never);
+  } else {
+    throw new Error(`${where('format')} is a function of the field context, but no FieldContextProvider is above it`);
+  }
+
+  return { min, max, step, integer, unit, format: resolvedFormat };
+}

package/src/resolve.ts

@@ -1,6 +1,29 @@
+import { NO_FIELD_CONTEXT, readingContext, type FieldCtx } from './FieldContext.js';
 import type { ValueOrFn } from './types.js';
 
 export function resolve<T>(v: ValueOrFn<T> | undefined, fallback: T): T {
   if (v === undefined) return fallback;
   return typeof v === 'function' ? (v as () => T)() : v;
 }
+
+/**
+ * Resolves a field's option with its context. With a provider above, every function receives
+ * `ctx`, so one whose parameter has a default (`(ctx = {}) => ...`) gets it too. With none, a
+ * function without declared parameters is called with nothing, so it works without a provider,
+ * and one that declares a parameter throws, `where` (`Field '<id>': option '<name>'`) saying
+ * whose it is. A key the function reads that no provider gave throws with `where` in front, so
+ * that error names the field and the option too. A function that returns `undefined` counts as
+ * an absent option, and yields `fallback` — a context lookup that misses (e.g. `(ctx) =>
+ * ctx.items[id]`) should fall back exactly as leaving the option out would, not leave the field
+ * with no value at all.
+ */
+export function resolveIn<T>(v: ValueOrFn<T> | undefined, fallback: T, ctx: FieldCtx, where: string): T {
+  if (v === undefined) return fallback;
+  if (typeof v !== 'function') return v;
+  const fn = v as (ctx?: object) => T;
+  if (ctx !== NO_FIELD_CONTEXT) return readingContext(where, () => fn(ctx)) ?? fallback;
+  if (fn.length > 0) {
+    throw new Error(`${where} is a function of the field context, but no FieldContextProvider is above it`);
+  }
+  return fn() ?? fallback;
+}

package/src/tree.ts

@@ -0,0 +1,175 @@
+import type { OneOfChoice, OneOfChoiceControls } from './choices.js';
+import { normalizeText } from './normalizeText.js';
+
+/** A node of a tree field (Praeceptor's categories): a choice with children. */
+export interface TreeNode<T extends string = string> extends OneOfChoice<T> {
+  children?: TreeNode<T>[];
+}
+
+/** A node as the widgets get it: the resolved choice, its children likewise, and whether it shows checked. */
+export interface TreeNodeControls<T extends string = string> extends OneOfChoiceControls<T> {
+  children: TreeNodeControls<T>[] | undefined;
+  /** Covered by the value (in the cascading selections), or in the value (`'independent'`). */
+  checked: boolean;
+}
+
+/**
+ * What a tree field's value lists, as antd TreeSelect's `showCheckedStrategy` and
+ * `checkStrictly` do. In the three cascading selections a node stands for its subtree, and
+ * a node all of whose children are covered is covered too; they differ only in which of the
+ * covered nodes the value names:
+ * - `'topmost'` (`SHOW_PARENT`, the default): the covered nodes whose parent is not covered;
+ * - `'all'` (`SHOW_ALL`): every covered node;
+ * - `'leaves'` (`SHOW_CHILD`): the covered leaves.
+ *
+ * `'independent'` (`checkStrictly`, moxb's `strictSelect`): each node is chosen on its own.
+ */
+export type TreeSelection = 'topmost' | 'all' | 'leaves' | 'independent';
+
+/**
+ * Which nodes a tree widget opens at first: `'top'` (the default), the roots with children;
+ * `'none'`; `'selected'` (moxb's `expandValues`), the ancestors of the value's nodes; `'all'`,
+ * every node with children.
+ */
+export type TreeExpand = 'top' | 'none' | 'selected' | 'all';
+
+function hasChildren(node: { children?: unknown[] }): boolean {
+  return (node.children?.length ?? 0) > 0;
+}
+
+/** The nodes in pre-order, and each node's parent. */
+function indexTree<T extends string>(nodes: TreeNode<T>[]): { order: TreeNode<T>[]; parent: Map<T, T> } {
+  const order: TreeNode<T>[] = [];
+  const parent = new Map<T, T>();
+  const walk = (list: TreeNode<T>[], up: T | undefined) => {
+    for (const node of list) {
+      order.push(node);
+      if (up !== undefined) parent.set(node.value, up);
+      if (node.children) walk(node.children, node.value);
+    }
+  };
+  walk(nodes, undefined);
+  return { order, parent };
+}
+
+/** The values that name no node, in their order, without duplicates (kept, so a stale value is not silently dropped). */
+function unknownValues<T extends string>(order: TreeNode<T>[], value: T[]): T[] {
+  const known = new Set(order.map((n) => n.value));
+  return [...new Set(value.filter((v) => !known.has(v)))];
+}
+
+/** The nodes a value covers in the cascading selections: the value's nodes, their descendants, and every node all of whose children are covered. */
+function cascade<T extends string>(nodes: TreeNode<T>[], value: T[]): Set<T> {
+  const listed = new Set(value);
+  const covered = new Set<T>();
+  const walk = (node: TreeNode<T>, inherited: boolean): boolean => {
+    const self = inherited || listed.has(node.value);
+    const children = (node.children ?? []).map((child) => walk(child, self));
+    const isCovered = self || (children.length > 0 && children.every(Boolean));
+    if (isCovered) covered.add(node.value);
+    return isCovered;
+  };
+  for (const node of nodes) walk(node, false);
+  return covered;
+}
+
+/** The covered nodes the value names under `selection` (see TreeSelection), in pre-order. */
+function namedNodes<T extends string>(order: TreeNode<T>[], parent: Map<T, T>, covered: Set<T>, selection: TreeSelection): T[] {
+  const named = order.filter((node) => {
+    if (!covered.has(node.value)) return false;
+    if (selection === 'leaves') return !hasChildren(node);
+    if (selection === 'topmost') {
+      const up = parent.get(node.value);
+      return up === undefined || !covered.has(up);
+    }
+    return true;
+  });
+  return named.map((node) => node.value);
+}
+
+/**
+ * A tree field's value in its canonical form under `selection` (see TreeSelection): the
+ * nodes it names in tree pre-order, followed by the values that name no node, without
+ * duplicates. With `'topmost'`, `['A1', 'A']` becomes `['A']`, and a node's children all
+ * listed become the node.
+ */
+export function normalizeTreeValue<T extends string>(nodes: TreeNode<T>[], value: T[], selection: TreeSelection): T[] {
+  const { order, parent } = indexTree(nodes);
+  const covered = selection === 'independent' ? new Set(value) : cascade(nodes, value);
+  const named = selection === 'independent'
+    ? order.filter((node) => covered.has(node.value)).map((node) => node.value)
+    : namedNodes(order, parent, covered, selection);
+  return [...named, ...unknownValues(order, value)];
+}
+
+/**
+ * Every node a tree field's value stands for, in pre-order (what an item filed under some
+ * node matches against): in the cascading selections the covered nodes (the value's nodes,
+ * their descendants, and every node all of whose children are covered); with
+ * `'independent'` the value's nodes themselves. Values that name no node follow, as in
+ * normalizeTreeValue.
+ */
+export function coveredNodes<T extends string>(nodes: TreeNode<T>[], value: T[], selection: TreeSelection = 'topmost'): T[] {
+  return normalizeTreeValue(nodes, value, selection === 'independent' ? 'independent' : 'all');
+}
+
+/**
+ * The value after flipping `node`, normalized. In the cascading selections a covered node
+ * is removed with its descendants and its ancestors (they no longer have all their
+ * children), and an uncovered one is added with its descendants; with `'independent'` the
+ * node alone is added or removed. A `node` that is not one of the nodes changes nothing.
+ */
+export function toggleTreeValue<T extends string>(nodes: TreeNode<T>[], value: T[], node: T, selection: TreeSelection): T[] {
+  const { order, parent } = indexTree(nodes);
+  const target = order.find((n) => n.value === node);
+  if (!target) return normalizeTreeValue(nodes, value, selection);
+  if (selection === 'independent') {
+    return normalizeTreeValue(nodes, value.includes(node) ? value.filter((v) => v !== node) : [...value, node], selection);
+  }
+  const covered = cascade(nodes, value);
+  const subtree = indexTree([target]).order.map((n) => n.value);
+  if (covered.has(node)) {
+    for (const v of subtree) covered.delete(v);
+    for (let up = parent.get(node); up !== undefined; up = parent.get(up)) covered.delete(up);
+  } else {
+    for (const v of subtree) covered.add(v);
+  }
+  return normalizeTreeValue(nodes, [...covered, ...unknownValues(order, value)], selection);
+}
+
+/** The nodes a tree widget opens at first under `expand` (see TreeExpand), in pre-order. */
+export function expandedTreeKeys<T extends string>(nodes: TreeNode<T>[], value: T[], expand: TreeExpand): T[] {
+  if (expand === 'none') return [];
+  if (expand === 'top') return nodes.filter(hasChildren).map((node) => node.value);
+  const { order, parent } = indexTree(nodes);
+  if (expand === 'all') return order.filter(hasChildren).map((node) => node.value);
+  const ancestors = new Set<T>();
+  for (const v of value) {
+    for (let up = parent.get(v); up !== undefined; up = parent.get(up)) ancestors.add(up);
+  }
+  return order.filter((node) => ancestors.has(node.value)).map((node) => node.value);
+}
+
+/**
+ * The nodes matching a search (Taskmaster's category search), by antd TreeSelect's rule, so a
+ * dropdown and a drawer over the same nodes agree: a node matches if its label (else its
+ * value) contains the query, ignoring accents, case and the query's surrounding spaces. A
+ * matching node stays with its whole subtree; any other node stays if one of its descendants
+ * matches, keeping only the children that stay. A node that stays with no children has
+ * `children` undefined, not an empty list. Generic over the node's shape, so the widgets can
+ * filter resolved node controls; the nodes given are not changed. An empty query returns
+ * them as they are.
+ */
+export function filterTree<N extends { label?: string; value: string; children?: N[] }>(nodes: N[], query: string): N[] {
+  const q = normalizeText(query.trim());
+  if (!q) return nodes;
+  /** The nodes of `list` that stay; `all` when an ancestor matched, so every node does. */
+  const keep = (list: N[], all: boolean): N[] => list.flatMap((node) => {
+    const matches = all || normalizeText(node.label ?? node.value).includes(q);
+    const children = keep(node.children ?? [], matches);
+    if (!matches && children.length === 0) return [];
+    if (node.children === undefined) return [node];
+    return [{ ...node, children: children.length > 0 ? children : undefined }];
+  });
+  return keep(nodes, false);
+}

package/src/types.ts

@@ -10,7 +10,16 @@ export interface FormLike {
 }
 
 export type Decision = boolean | { verdict: boolean; reason?: string };
-export type ValueOrFn<T> = T | (() => T);
+/**
+ * A value, or a function giving it, as a field's options take them. With a FieldContextProvider
+ * above, a field calls every such function with its field context (the provider's value); with
+ * none, a function without parameters is called with nothing and one that declares a parameter
+ * throws.
+ */
+export type ValueOrFn<T, Ctx = any> = T | ((ctx: Ctx) => T);
+
+/** A value, or a function of no arguments giving it, as an action's options take them: an action calls its functions with nothing. */
+export type Thunk<T> = T | (() => T);
 
 export type Severity = 'info' | 'warning' | 'error';
 
@@ -53,17 +62,29 @@ export type ConfirmationSpec =
 
 export interface ActionOptions<TArgs = void, TResult = void, RouteId extends string = string> {
   id: string;
-  label: ValueOrFn<string>;
-  icon?: ValueOrFn<React.ReactNode>;
-  variant?: ValueOrFn<'default' | 'primary' | 'danger'>;
-  enabled?: ValueOrFn<Decision>;
-  invisible?: ValueOrFn<boolean>;
-  confirmation?: ValueOrFn<ConfirmationSpec | undefined>;
+  label: Thunk<string>;
+  icon?: Thunk<React.ReactNode>;
+  variant?: Thunk<'default' | 'primary' | 'danger'>;
+  enabled?: Thunk<Decision>;
+  invisible?: Thunk<boolean>;
+  confirmation?: Thunk<ConfirmationSpec | undefined>;
   errorRoute?: RouteId;
   fire: (args: TArgs, ctx: ExecutionContext) => Promise<TResult> | TResult;
   onSuccess?: (result: TResult) => void;
 }
 
+/** Compiles only when `A` is assignable to `B`. Not part of the package's public API: kept here as the one definition, imported directly by the files that use it (kinds.ts), and left out of index.ts's re-export of this module. */
+export type Fits<A extends B, B> = A;
+
+/**
+ * A compile-time check: an action calls its options' functions with nothing, so one that takes
+ * a parameter (the field context, say) must not compile, rather than crash when it is called.
+ */
+type ActionFunctionsTakeNoParameter = [
+  // @ts-expect-error -- a function of a parameter is not a zero-argument thunk.
+  Fits<(ctx: { t(key: string): string }) => string, ActionOptions['label']>,
+];
+
 // Conditional rest-tuple lets call sites omit args entirely when TArgs is
 // void (e.g. plain ActionButton click) and requires the value otherwise
 // (e.g. FormSubmitButton passing typed form values).