@yewdiel21/motion-kit 0.10.0 → 0.15.0

package/src/core/segment-field.ts

@@ -0,0 +1,373 @@
+import { gsap, EASE, registerMotion } from './gsap';
+import { reduced } from './reduced';
+import { createScope } from './scope';
+import { rollDigits, shake } from '../motion/micro';
+import {
+  BIG_STEP, dayPeriods, defaultHour12, formatSegment, segmentLayout, segmentLimits, stepSegment, typeDigit,
+  type SegmentType, type SegmentValues,
+} from './segments';
+
+export type { SegmentValues } from './segments';
+
+/*
+ * Segmented field controller (time-field, date-range-picker): one
+ * role="spinbutton" per segment in the locale's order, inside a group it
+ * appends to `root`. Segments are contenteditable with inputmode="numeric" so
+ * phones open the number pad, but every edit is intercepted (keydown on
+ * desktop, beforeinput on phones) and the controller writes the text. Arrows
+ * step with wrap and the digits roll in the direction of the change; typing
+ * fills a segment and moves to the next; Backspace erases, then moves back; a
+ * pill glides behind the focused segment (swing curve).
+ */
+
+export interface SegmentFieldOptions {
+  kind: 'date' | 'time' | 'datetime';
+  locale: string;
+  /** Time and datetime; default: the locale's. */
+  hour12?: boolean;
+  seconds?: boolean;
+  /** Arrow step per segment (default 1). */
+  steps?: Partial<Record<SegmentType, number>>;
+  /** Accessible names of the segments. */
+  labels?: Partial<Record<SegmentType, string>>;
+  disabled?: boolean;
+  readOnly?: boolean;
+  /** Any value changed (by the person or by setValues with notify). */
+  onChange?: (values: SegmentValues) => void;
+}
+
+export interface SegmentField {
+  /** The group: [data-mk-segments] role="group". */
+  readonly element: HTMLElement;
+  values(): SegmentValues;
+  /** Keys the field does not have are ignored; null empties a segment. No onChange. */
+  setValues(values: SegmentValues, animate?: boolean): void;
+  /** aria-invalid on the group; `shakeIt` shakes it once. */
+  invalid(on: boolean, shakeIt?: boolean): void;
+  focus(which?: 'first' | 'last'): void;
+  destroy(): void;
+}
+
+const LABELS: Record<SegmentType, string> = {
+  day: 'día',
+  month: 'mes',
+  year: 'año',
+  hour: 'hora',
+  minute: 'minutos',
+  second: 'segundos',
+  dayPeriod: 'a. m./p. m.',
+};
+
+const placeholder = (type: SegmentType, language: string) => {
+  if (type === 'year') return language === 'es' ? 'aaaa' : 'yyyy';
+  if (type === 'day') return 'dd';
+  if (type === 'month') return 'mm';
+  return '––';
+};
+
+interface Segment {
+  type: SegmentType;
+  element: HTMLElement;
+  limits: [number, number];
+  step: number;
+  value: number | null;
+}
+
+export function createSegmentField(root: HTMLElement, options: SegmentFieldOptions): SegmentField {
+  registerMotion();
+  const scope = createScope();
+  const language = options.locale.split('-')[0]!.toLowerCase();
+  const hour12 = options.kind === 'date' ? false : (options.hour12 ?? defaultHour12(options.locale));
+  const periods = dayPeriods(options.locale);
+  const layout = segmentLayout(options.kind, options.locale, { hour12, seconds: options.seconds });
+  const editable = !options.disabled && !options.readOnly;
+
+  const group = document.createElement('div');
+  group.dataset.mkSegments = '';
+  group.setAttribute('role', 'group');
+  if (options.disabled) group.setAttribute('aria-disabled', 'true');
+  const pill = document.createElement('span');
+  pill.dataset.mkSegmentFocus = '';
+  pill.setAttribute('aria-hidden', 'true');
+  group.append(pill);
+
+  const segments: Segment[] = [];
+  for (const part of layout) {
+    if ('literal' in part) {
+      const literal = document.createElement('span');
+      literal.dataset.mkSegmentLiteral = '';
+      literal.setAttribute('aria-hidden', 'true');
+      literal.textContent = part.literal;
+      group.append(literal);
+      continue;
+    }
+    const { type } = part;
+    const element = document.createElement('span');
+    element.dataset.mkSegment = type;
+    element.setAttribute('role', 'spinbutton');
+    element.setAttribute('aria-label', options.labels?.[type] ?? LABELS[type]);
+    element.setAttribute('tabindex', options.disabled ? '-1' : '0');
+    element.setAttribute('spellcheck', 'false');
+    element.setAttribute('autocorrect', 'off');
+    element.setAttribute('autocapitalize', 'off');
+    element.setAttribute('enterkeyhint', 'next');
+    element.setAttribute('inputmode', type === 'dayPeriod' ? 'text' : 'numeric');
+    if (editable) element.setAttribute('contenteditable', 'true');
+    if (options.disabled) element.setAttribute('aria-disabled', 'true');
+    if (options.readOnly) element.setAttribute('aria-readonly', 'true');
+    const limits = segmentLimits(type, hour12);
+    element.setAttribute('aria-valuemin', String(limits[0]));
+    element.setAttribute('aria-valuemax', String(limits[1]));
+    group.append(element);
+    const step = Math.max(1, Math.round(options.steps?.[type] ?? 1));
+    segments.push({ type, element, limits, step, value: null });
+  }
+  root.append(group);
+  scope.add(() => group.remove());
+
+  const effects = new Set<gsap.core.Animation>();
+  const keep = (animation: gsap.core.Animation | null) => {
+    if (!animation) return;
+    effects.add(animation);
+    // Finished ones leave as new ones arrive: the animation's own onComplete stays untouched.
+    for (const effect of effects) if (effect.totalProgress() === 1) effects.delete(effect);
+  };
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+    gsap.killTweensOf([pill, group]);
+  });
+
+  /** Typing in progress: the segment and the digits typed so far. */
+  let typing: { segment: Segment; buffer: string } | null = null;
+  const partialYear = (segment: Segment) => segment.type === 'year' && typing?.segment === segment && typing.buffer !== '';
+
+  const text = (segment: Segment) => {
+    if (partialYear(segment)) return typing!.buffer;
+    return segment.value === null ? placeholder(segment.type, language) : formatSegment(segment.type, segment.value, periods);
+  };
+  const paint = (segment: Segment, direction: 1 | -1 | 0 = 0) => {
+    const shown = text(segment);
+    const { element } = segment;
+    if (direction && !reduced() && segment.value !== null && element.textContent) keep(rollDigits(element, shown, direction, 0.28));
+    else element.textContent = shown;
+    element.toggleAttribute('data-mk-empty', segment.value === null && !partialYear(segment));
+    if (segment.value === null) {
+      element.removeAttribute('aria-valuenow');
+      element.setAttribute('aria-valuetext', 'Vacío');
+    } else {
+      element.setAttribute('aria-valuenow', String(segment.value));
+      element.setAttribute('aria-valuetext', shown);
+    }
+  };
+  segments.forEach((segment) => paint(segment));
+
+  const values = (): SegmentValues => {
+    const out: SegmentValues = {};
+    for (const segment of segments) out[segment.type] = partialYear(segment) ? null : segment.value;
+    return out;
+  };
+  let last = JSON.stringify(values());
+  const notify = () => {
+    const now = JSON.stringify(values());
+    if (now === last) return;
+    last = now;
+    options.onChange?.(values());
+  };
+
+  const set = (segment: Segment, value: number | null, direction: 1 | -1 | 0 = 0) => {
+    segment.value = value;
+    paint(segment, direction);
+  };
+
+  const indexOf = (element: Element | null) => segments.findIndex((segment) => segment.element === element);
+  const focusAt = (index: number) => segments[index]?.element.focus();
+
+  /** Leaving a segment ends its typing; a partial year is taken as typed. */
+  const endTyping = () => {
+    if (!typing) return;
+    const { segment, buffer } = typing;
+    typing = null;
+    if (segment.type === 'year' && buffer) {
+      const year = Number(buffer);
+      set(segment, year >= segment.limits[0] ? year : segment.value);
+    } else paint(segment);
+    notify();
+  };
+
+  // The focus pill glides behind the focused segment.
+  let pillShown = false;
+  const movePill = (segment: Segment) => {
+    const box = { x: segment.element.offsetLeft, width: segment.element.offsetWidth };
+    if (!pillShown || reduced()) {
+      gsap.set(pill, box);
+      if (!reduced()) keep(gsap.to(pill, { opacity: 1, duration: 0.15, ease: 'power2.out' }));
+    } else keep(gsap.to(pill, { ...box, opacity: 1, duration: 0.35, ease: EASE.swatch, overwrite: 'auto' }));
+    pillShown = true;
+  };
+
+  const typeInto = (segment: Segment, digit: string) => {
+    const index = segments.indexOf(segment);
+    const buffer = typing?.segment === segment ? typing.buffer : '';
+    const result = typeDigit(buffer, digit, segment.limits);
+    typing = result.buffer ? { segment, buffer: result.buffer } : null;
+    if (result.value !== null) set(segment, result.value);
+    else if (segment.type === 'year') paint(segment);
+    else if (typing) segment.element.textContent = result.buffer.padStart(2, '0');
+    notify();
+    if (result.done && index < segments.length - 1) focusAt(index + 1);
+  };
+
+  const erase = (segment: Segment) => {
+    const index = segments.indexOf(segment);
+    if (segment.value === null && !partialYear(segment)) {
+      if (index > 0) focusAt(index - 1);
+      return;
+    }
+    typing = null;
+    set(segment, null);
+    notify();
+  };
+
+  const stepBy = (segment: Segment, delta: number, step: number) => {
+    typing = null;
+    const before = segment.value;
+    const next = stepSegment(before, delta, segment.limits, step);
+    if (next === before) return;
+    const wrapped = before !== null && (delta > 0 ? next < before : next > before);
+    const direction = (delta > 0) !== wrapped ? 1 : -1;
+    set(segment, next, before === null ? 0 : direction);
+    notify();
+  };
+
+  scope.on(group, 'keydown', (event) => {
+    const key = event as KeyboardEvent;
+    const index = indexOf(key.target as Element);
+    const segment = segments[index];
+    if (!segment) return;
+    if (key.metaKey || key.ctrlKey || key.altKey) return;
+    if (key.key === 'Tab') return;
+    if (key.key === 'ArrowLeft' || key.key === 'ArrowRight') {
+      key.preventDefault();
+      focusAt(index + (key.key === 'ArrowLeft' ? -1 : 1));
+      return;
+    }
+    if (key.key === 'Enter') return;
+    // Everything else is ours: contenteditable must not write by itself.
+    if (key.key.length === 1 || ['Backspace', 'Delete', 'ArrowUp', 'ArrowDown', 'PageUp', 'PageDown', 'Home', 'End'].includes(key.key)) key.preventDefault();
+    if (!editable) return;
+    const { type, step } = segment;
+    switch (key.key) {
+      case 'ArrowUp':
+        return stepBy(segment, step, step);
+      case 'ArrowDown':
+        return stepBy(segment, -step, step);
+      case 'PageUp':
+        return stepBy(segment, Math.max(step, BIG_STEP[type]), step);
+      case 'PageDown':
+        return stepBy(segment, -Math.max(step, BIG_STEP[type]), step);
+      case 'Home':
+      case 'End': {
+        typing = null;
+        const target = key.key === 'Home' ? segment.limits[0] : segment.limits[1];
+        if (target !== segment.value) {
+          set(segment, target, segment.value === null ? 0 : target > segment.value ? 1 : -1);
+          notify();
+        }
+        return;
+      }
+      case 'Backspace':
+      case 'Delete':
+        return erase(segment);
+    }
+    if (type === 'dayPeriod') {
+      const letter = key.key.toLowerCase();
+      const match = periods.findIndex((period) => period.toLowerCase().replace(/[^\p{L}]/gu, '').startsWith(letter));
+      if (match >= 0 && /\p{L}/u.test(letter)) {
+        if (segment.value !== match) {
+          set(segment, match, match ? 1 : -1);
+          notify();
+        }
+        if (index < segments.length - 1) focusAt(index + 1);
+      }
+      return;
+    }
+    if (/^\d$/.test(key.key)) typeInto(segment, key.key);
+  });
+
+  // Phones send beforeinput instead of key codes: read what they meant, write nothing.
+  scope.on(group, 'beforeinput', (event) => {
+    const input = event as InputEvent;
+    const segment = segments[indexOf(input.target as Element)];
+    if (!segment) return;
+    input.preventDefault();
+    if (!editable) return;
+    if (input.inputType.startsWith('delete')) return erase(segment);
+    for (const character of input.data ?? '') {
+      const current = segments[indexOf(document.activeElement)] ?? segment;
+      if (/\d/.test(character) && current.type !== 'dayPeriod') typeInto(current, character);
+      else if (current.type === 'dayPeriod') {
+        const match = periods.findIndex((period) => period.toLowerCase().startsWith(character.toLowerCase()));
+        if (match >= 0) {
+          set(current, match);
+          notify();
+        }
+      }
+    }
+  });
+  // Paste, drop and IME composition must not leave stray text either.
+  scope.on(group, 'paste', (event) => event.preventDefault());
+  scope.on(group, 'drop', (event) => event.preventDefault());
+
+  scope.on(group, 'focusin', (event) => {
+    const segment = segments[indexOf(event.target as Element)];
+    if (!segment) return;
+    if (typing && typing.segment !== segment) endTyping();
+    typing = null;
+    movePill(segment);
+    // The caret is hidden; select the text so the whole segment reads as active.
+    const selection = typeof getSelection === 'function' ? getSelection() : null;
+    try {
+      selection?.selectAllChildren(segment.element);
+      selection?.collapseToEnd();
+    } catch {
+      // jsdom without a full selection model.
+    }
+  });
+  scope.on(group, 'focusout', (event) => {
+    const next = (event as FocusEvent).relatedTarget as Node | null;
+    const leaving = segments[indexOf(event.target as Element)];
+    if (leaving && typing?.segment === leaving) endTyping();
+    if (next && group.contains(next)) return;
+    pillShown = false;
+    if (reduced()) gsap.set(pill, { opacity: 0 });
+    else keep(gsap.to(pill, { opacity: 0, duration: 0.15, ease: 'power2.in' }));
+  });
+
+  return {
+    element: group,
+    values,
+    setValues(next, animate = false) {
+      typing = null;
+      for (const segment of segments) {
+        if (!(segment.type in next)) continue;
+        const raw = next[segment.type];
+        const value = raw === null || raw === undefined ? null : Math.min(segment.limits[1], Math.max(segment.limits[0], Math.round(raw)));
+        if (value === segment.value) continue;
+        const direction = !animate || value === null || segment.value === null ? 0 : value > segment.value ? 1 : -1;
+        set(segment, value, direction);
+      }
+      last = JSON.stringify(values());
+    },
+    invalid(on, shakeIt = false) {
+      if (on) group.setAttribute('aria-invalid', 'true');
+      else group.removeAttribute('aria-invalid');
+      if (on && shakeIt) keep(shake(group));
+    },
+    focus(which = 'first') {
+      const target = which === 'last' ? segments[segments.length - 1] : segments[0];
+      target?.element.focus();
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/core/segments.ts

@@ -0,0 +1,153 @@
+import { safeFormat } from './dates';
+
+/*
+ * Segmented date and time input, the pure part: which segments a locale shows
+ * and in what order, for a date, a time or both (es: dd/mm/aaaa, 24 h and
+ * "dd/mm/aaaa, HH:MM"; en-US: mm/dd/yyyy and 12 h with
+ * AM/PM), each segment's limits, stepping with wrap, typing digit by digit, and
+ * time values ("HH:MM[:SS]", always 24 h). core/segment-field.ts puts it on screen.
+ */
+
+export type SegmentType = 'day' | 'month' | 'year' | 'hour' | 'minute' | 'second' | 'dayPeriod';
+export type SegmentValues = Partial<Record<SegmentType, number | null>>;
+export type SegmentPart = { type: SegmentType } | { literal: string };
+
+export interface TimeValue {
+  hour: number;
+  minute: number;
+  second: number;
+}
+
+/** 0 = a.m., 1 = p.m. */
+export type DayPeriod = 0 | 1;
+
+/** Whether the locale writes 12-hour times. */
+export function defaultHour12(locale: string): boolean {
+  const options = safeFormat(locale, { hour: 'numeric' }).resolvedOptions() as Intl.ResolvedDateTimeFormatOptions & { hourCycle?: string };
+  if (options.hourCycle) return options.hourCycle === 'h11' || options.hourCycle === 'h12';
+  return Boolean(options.hour12);
+}
+
+const KNOWN = new Set<string>(['day', 'month', 'year', 'hour', 'minute', 'second', 'dayPeriod']);
+
+/** Segments and the text between them, in the locale's order. */
+export function segmentLayout(kind: 'date' | 'time' | 'datetime', locale: string, { hour12, seconds = false }: { hour12?: boolean; seconds?: boolean } = {}): SegmentPart[] {
+  const twelve = hour12 ?? defaultHour12(locale);
+  const date: Intl.DateTimeFormatOptions = { day: '2-digit', month: '2-digit', year: 'numeric' };
+  const time: Intl.DateTimeFormatOptions = { hour: '2-digit', minute: '2-digit', ...(seconds ? { second: '2-digit' } : {}), hourCycle: twelve ? 'h12' : 'h23' };
+  // Date and time together: the locale's own order and joint ("23/11/2026, 13:05").
+  const format = safeFormat(locale, kind === 'date' ? date : kind === 'time' ? time : { ...date, ...time });
+  const parts: SegmentPart[] = [];
+  for (const part of format.formatToParts(new Date(2026, 10, 23, 13, 5, 9))) {
+    if (KNOWN.has(part.type)) parts.push({ type: part.type as SegmentType });
+    else if (part.type === 'literal') {
+      // Some engines spell a narrow no-break space before AM/PM; a plain space reads the same.
+      const literal = part.value.replace(/[  ]/g, ' ');
+      const last = parts[parts.length - 1];
+      if (last && 'literal' in last) last.literal += literal;
+      else parts.push({ literal });
+    }
+  }
+  // Leading or trailing text (a comma, a space) belongs to no segment.
+  while (parts.length && 'literal' in parts[0]!) parts.shift();
+  while (parts.length && 'literal' in parts[parts.length - 1]!) parts.pop();
+  return parts;
+}
+
+/** The locale's words for a.m. and p.m. */
+export function dayPeriods(locale: string): [string, string] {
+  const format = safeFormat(locale, { hour: 'numeric', hourCycle: 'h12' });
+  const read = (hour: number) =>
+    format.formatToParts(new Date(2026, 0, 1, hour)).find((part) => part.type === 'dayPeriod')?.value.replace(/[  ]/g, ' ') ?? (hour < 12 ? 'AM' : 'PM');
+  return [read(1), read(13)];
+}
+
+export const daysIn = (year: number, month: number) => {
+  const date = new Date(2000, 0, 1);
+  date.setFullYear(year, month, 0);
+  return date.getDate();
+};
+
+/** [min, max] of a segment. */
+export function segmentLimits(type: SegmentType, hour12 = false): [number, number] {
+  switch (type) {
+    case 'day':
+      return [1, 31];
+    case 'month':
+      return [1, 12];
+    case 'year':
+      return [1, 9999];
+    case 'hour':
+      return hour12 ? [1, 12] : [0, 23];
+    case 'minute':
+    case 'second':
+      return [0, 59];
+    default:
+      return [0, 1];
+  }
+}
+
+/** A bigger jump for PageUp / PageDown. */
+export const BIG_STEP: Record<SegmentType, number> = { day: 7, month: 3, year: 5, hour: 3, minute: 15, second: 15, dayPeriod: 1 };
+
+/**
+ * `value` moved by `delta` with wrap. Steps above 1 land on multiples of the
+ * step (09:32 + 15 → 09:45). An empty segment starts at its minimum (or its
+ * maximum when going down).
+ */
+export function stepSegment(value: number | null, delta: number, [min, max]: [number, number], step = 1): number {
+  if (value === null) return delta >= 0 ? min : max - ((max - min) % Math.max(1, step));
+  const size = max - min + 1;
+  let next: number;
+  if (step > 1 && Math.abs(delta) === step && (value - min) % step !== 0) {
+    next = delta > 0 ? Math.ceil((value - min) / step) * step + min : Math.floor((value - min) / step) * step + min;
+  } else next = value + delta;
+  return ((((next - min) % size) + size) % size) + min;
+}
+
+export interface Typed {
+  /** Digits kept for the next key ('' when the segment is done). */
+  buffer: string;
+  /** The value to show, or null while the digits typed so far are below the minimum (a leading 0). */
+  value: number | null;
+  /** The segment is full: focus moves on. */
+  done: boolean;
+}
+
+/** One digit typed into a segment that already holds `buffer`. */
+export function typeDigit(buffer: string, digit: string, [min, max]: [number, number]): Typed {
+  const width = String(max).length;
+  let text = buffer + digit;
+  if (Number(text) > max || text.length > width) text = digit;
+  const value = Number(text);
+  const done = text.length >= width || value * 10 > max;
+  return { buffer: done ? '' : text, value: value < min ? null : value, done };
+}
+
+export function formatSegment(type: SegmentType, value: number, periods: [string, string] = ['AM', 'PM']): string {
+  if (type === 'dayPeriod') return periods[value ? 1 : 0];
+  return String(value).padStart(type === 'year' ? 4 : 2, '0');
+}
+
+/** "09:30", "9:30:15" → the time; null when it is not one. */
+export function parseTime(text: string | null | undefined): TimeValue | null {
+  const match = /^(\d{1,2}):(\d{2})(?::(\d{2}))?$/.exec((text ?? '').trim());
+  if (!match) return null;
+  const [hour, minute, second] = [Number(match[1]), Number(match[2]), Number(match[3] ?? 0)];
+  if (hour > 23 || minute > 59 || second > 59) return null;
+  return { hour, minute, second };
+}
+
+const two = (n: number) => String(n).padStart(2, '0');
+
+/** "HH:MM", or "HH:MM:SS" with `seconds`. */
+export const formatTime = (time: TimeValue, seconds = false) => `${two(time.hour)}:${two(time.minute)}${seconds ? `:${two(time.second)}` : ''}`;
+
+/** Minutes since midnight (seconds as a fraction), to compare times. */
+export const timeMinutes = (time: TimeValue) => time.hour * 60 + time.minute + time.second / 60;
+
+/** 24 h → 12 h with its period (0 → 12 a.m., 13 → 1 p.m.). */
+export const to12 = (hour: number): { hour: number; period: DayPeriod } => ({ hour: hour % 12 || 12, period: hour >= 12 ? 1 : 0 });
+
+/** 12 h and its period → 24 h. */
+export const to24 = (hour: number, period: number) => (hour % 12) + (period ? 12 : 0);

package/src/core/tree.ts

@@ -0,0 +1,116 @@
+import { foldText } from './mark';
+
+/*
+ * Trees (tree-view, file-explorer, json-viewer), the pure part: finding a node
+ * and its path, three-state checks (a branch is checked when every child is,
+ * mixed when some are; checking a branch checks everything under it, except
+ * disabled nodes, which keep their state and do not count for their branch)
+ * and searching (the matches, the ancestors that keep them visible and open;
+ * accents and case ignored).
+ */
+
+export interface TreeNode {
+  id: string;
+  label: string;
+  children?: TreeNode[];
+  /** A short glyph before the label. */
+  icon?: string;
+  disabled?: boolean;
+  /** Has children that loadChildren() will bring. */
+  hasChildren?: boolean;
+  /** Anything the app wants to keep with the node. */
+  data?: unknown;
+}
+
+export type CheckState = 'true' | 'false' | 'mixed';
+
+export const isBranch = (node: TreeNode) => Boolean(node.children?.length || node.hasChildren);
+
+/** Every node, depth first, with its depth and parent. */
+export function walk(nodes: TreeNode[], visit: (node: TreeNode, depth: number, parent: TreeNode | null) => void, depth = 0, parent: TreeNode | null = null) {
+  for (const node of nodes) {
+    visit(node, depth, parent);
+    if (node.children) walk(node.children, visit, depth + 1, node);
+  }
+}
+
+/** The node with `id` and the path from the top to it (it included). */
+export function findNode(nodes: TreeNode[], id: string): { node: TreeNode; path: TreeNode[] } | null {
+  for (const node of nodes) {
+    if (node.id === id) return { node, path: [node] };
+    if (node.children) {
+      const found = findNode(node.children, id);
+      if (found) return { node: found.node, path: [node, ...found.path] };
+    }
+  }
+  return null;
+}
+
+/** Each node's state: leaves from `checked`, branches from their children (the enabled ones, when there are). */
+export function checkStates(nodes: TreeNode[], checked: Set<string>): Map<string, CheckState> {
+  const states = new Map<string, CheckState>();
+  const visit = (node: TreeNode): CheckState => {
+    let state: CheckState;
+    if (!node.children?.length) state = checked.has(node.id) ? 'true' : 'false';
+    else {
+      const all = node.children.map(visit);
+      const enabled = all.filter((_, i) => !node.children![i]!.disabled);
+      const children = enabled.length ? enabled : all;
+      state = children.every((child) => child === 'true') ? 'true' : children.every((child) => child === 'false') ? 'false' : 'mixed';
+    }
+    states.set(node.id, state);
+    return state;
+  };
+  nodes.forEach(visit);
+  return states;
+}
+
+/** Check or uncheck `id` and everything under it but disabled nodes; returns the new set (branches follow their children). */
+export function toggleCheck(nodes: TreeNode[], checked: Set<string>, id: string, value?: boolean): Set<string> {
+  const found = findNode(nodes, id);
+  if (!found) return new Set(checked);
+  const states = checkStates(nodes, checked);
+  const on = value ?? states.get(id) !== 'true';
+  const next = new Set(checked);
+  const set = (node: TreeNode) => {
+    if (on) next.add(node.id);
+    else next.delete(node.id);
+    for (const child of node.children ?? []) if (!child.disabled) set(child);
+  };
+  set(found.node);
+  // Branches mirror their children.
+  const after = checkStates(nodes, next);
+  walk(nodes, (node) => {
+    if (!node.children?.length) return;
+    if (after.get(node.id) === 'true') next.add(node.id);
+    else next.delete(node.id);
+  });
+  return next;
+}
+
+const fold = foldText;
+
+/**
+ * The nodes whose text has `query` (accents and case ignored), the ancestors
+ * that keep them visible, and the branches to open to show them.
+ */
+export function searchTree(nodes: TreeNode[], query: string, text: (node: TreeNode) => string = (node) => node.label) {
+  const needle = fold(query.trim());
+  const matches = new Set<string>();
+  const visible = new Set<string>();
+  const open = new Set<string>();
+  if (!needle) return { matches, visible, open, active: false };
+  const visit = (node: TreeNode, ancestors: TreeNode[]) => {
+    if (fold(text(node)).includes(needle)) {
+      matches.add(node.id);
+      visible.add(node.id);
+      for (const ancestor of ancestors) {
+        visible.add(ancestor.id);
+        open.add(ancestor.id);
+      }
+    }
+    for (const child of node.children ?? []) visit(child, [...ancestors, node]);
+  };
+  for (const node of nodes) visit(node, []);
+  return { matches, visible, open, active: true };
+}