@colixsystems/widget-sdk 0.245.0 → 0.247.0

package/dist/index.native.js

@@ -112,6 +112,8 @@ export {
   widthTier,
   WIDE_WIDTH_PX,
 } from "./container-width.js";
+// Balanced lines of cells sized from the grid's own measured width.
+export { Grid } from "./grid.native.js";
 // REQ-WSDK-PLATFORM §6 — Tier A hooks (native variants).
 export { useClipboard, ClipboardError } from "./clipboard.native.js";
 export { useToast } from "./toast.native.js";
@@ -234,6 +236,8 @@ export { List, ListRow, ListHeader, EmptyState } from "./list.native.js";
 export { Badge, Avatar, Progress, Stat, Divider } from "./detail-parts.native.js";
 export { initialsFor } from "./initials.js";
 export { avatarColorFor } from "./avatar-color.js";
+// A stored file's picture: a themed placeholder, then a fallback on failure.
+export { FileImage } from "./file-image.native.js";
 // The one card surface: the theme's `card` scope, a gradient fill, margin.
 export { Card } from "./card.native.js";
 export {
@@ -251,7 +255,7 @@ export {
   cardGradientProps,
 } from "./card-style.js";
 // The themed button; follows the theme's button, destructive and ring scopes.
-export { Button, BUTTON_VARIANTS } from "./button.native.js";
+export { Button, IconButton, BUTTON_VARIANTS } from "./button.native.js";
 export {
   BUTTON_PADDING_MAX,
   BUTTON_BORDER_WIDTH_MAX,
@@ -271,6 +275,10 @@ export { Checkbox } from "./checkbox.native.js";
 export { Switch } from "./switch.native.js";
 export { Select } from "./select.native.js";
 export { SearchField } from "./search-field.native.js";
+// A searchable `<Select>` of users, groups or one table's records.
+export { PeoplePicker } from "./people-picker.native.js";
+// Pick one of a short visible list; `muted` scope, or `tabs` when segmented.
+export { RadioGroup } from "./radio-group.native.js";
 // Space for a control whose role is not a button; a no-op on native.
 export { spaceActivates } from "./form-control-logic.js";
 // A themed tab strip; follows the theme's `tabs` scope.
@@ -285,8 +293,13 @@ export { Modal } from "./modal.native.js";
 export { ConfirmDialog } from "./confirm-dialog.native.js";
 // Themed filter chips, tags and pills; follow the theme's `chip` scope.
 export { Chip, ChipGroup } from "./chip.native.js";
+// Themed bar, line, area and donut charts; follow the theme's `chart` scope.
+export { Chart } from "./chart.native.js";
+export { chartColors } from "./chart-tokens.js";
 // A themed file chooser on `<FilePicker>`; follows the theme's `muted` scope.
 export { FileUpload } from "./file-upload.native.js";
+// Anchored actions, content and labels; follow the theme's `popover` scope.
+export { Menu, Popover, Tooltip } from "./popover.native.js";
 // The semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

package/dist/menu-view.js

@@ -0,0 +1,168 @@
+// The ONE implementation behind `<Menu>`: a list of actions opened from a
+// trigger, on the anchored surface `<Popover>` uses. Its rows are `<Select>`'s
+// option rows, so a menu and a dropdown in one app look alike.
+
+import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { Icon } from "./icon.js";
+import { optionRowStyle, resolveFormControlTokens } from "./form-control-tokens.js";
+import { isText, optionKeyDown } from "./form-control-logic.js";
+import { initialFocusIndex } from "./select-logic.js";
+import { POPOVER_DEFAULTS, menuItemList } from "./popover-tokens.js";
+import { triggerWith } from "./popover-view.js";
+
+const h = React.createElement;
+const ICON_SIZE = 18;
+const NOTHING_PICKED = () => false;
+
+/**
+ * Bind the shared menu to one platform's primitives and anchored surface.
+ *
+ * @param {{View: any, Text: any, Pressable: any, ScrollView: any, Platform: any}} rn
+ * @param {any} AnchoredSurface — from `makePopover()` for the same host.
+ */
+export function makeMenu(rn, AnchoredSurface) {
+  const { Text, Pressable, ScrollView, Platform } = rn;
+
+  // Keyboard focus is a web concern: a device moves its reader into the
+  // sheet by itself, and a programmatic focus there would fight it.
+  function focusNode(node) {
+    if (Platform.OS === "web" && node && typeof node.focus === "function") node.focus();
+  }
+
+  function itemGlyph(icon, color) {
+    if (typeof icon === "string" && icon) return h(Icon, { name: icon, size: ICON_SIZE, color });
+    return React.isValidElement(icon) ? icon : null;
+  }
+
+  function MenuItems({ t, items, onPick, accessibilityLabel, testID }) {
+    const nodes = React.useRef([]);
+    const initial = initialFocusIndex(items, NOTHING_PICKED);
+    const pendingFocus = React.useRef(true);
+    return h(
+      ScrollView,
+      {
+        style: { flexShrink: 1 },
+        role: "menu",
+        accessibilityLabel,
+        keyboardShouldPersistTaps: "handled",
+        testID: testID ? `${testID}-items` : undefined,
+      },
+      ...items.map((item, index) => {
+        // The web host still delivers keys to a disabled Pressable.
+        const activate = () => {
+          if (!item.disabled) onPick(item);
+        };
+        const color = item.danger ? t.popover.dangerColor : t.popover.textColor;
+        return h(
+          Pressable,
+          {
+            key: item.key,
+            ref: (node) => {
+              nodes.current[index] = node;
+              if (node && index === initial && pendingFocus.current) {
+                pendingFocus.current = false;
+                focusNode(node);
+              }
+            },
+            onPress: activate,
+            onKeyDown: optionKeyDown({
+              options: items,
+              index,
+              focusAt: (next) => focusNode(nodes.current[next]),
+              activate,
+            }),
+            disabled: item.disabled,
+            role: "menuitem",
+            "aria-disabled": item.disabled,
+            accessibilityLabel: item.accessibilityLabel,
+            testID: item.testID,
+            style: ({ pressed }) => optionRowStyle(t, { pressed, disabled: item.disabled }),
+          },
+          itemGlyph(item.icon, color),
+          h(
+            Text,
+            { style: { fontFamily: t.fontFamily, fontSize: t.fontSize, color, flexShrink: 1 } },
+            item.label,
+          ),
+        );
+      }),
+    );
+  }
+
+  /**
+   * A list of actions opened from a trigger: a row's "…" button, a toolbar's
+   * overflow. Beside the trigger on a wide screen, a bottom sheet on a phone.
+   * Each item closes the menu, then runs its `onPress` once the menu has left
+   * the screen, so an item can open a dialog of its own.
+   *
+   * @param {object} props
+   * @param {any} props.trigger — the pressable element that opens it.
+   * @param {Array<{label: string, onPress?: () => void, icon?: string|any,
+   *   danger?: boolean, disabled?: boolean, testID?: string,
+   *   accessibilityLabel?: string, key?: string}|null|false>} props.items —
+   *   falsy entries are skipped, so `cond && {…}` works.
+   * @param {string} [props.accessibilityLabel] — names the menu.
+   * @param {"bottom"|"top"} [props.placement] — default "bottom"; flips.
+   * @param {string} [props.closeAccessibilityLabel] — the sheet backdrop's name.
+   * @param {string} [props.testID] — on the panel; the list takes `-items`.
+   */
+  function Menu({
+    trigger,
+    items,
+    accessibilityLabel,
+    placement = "bottom",
+    closeAccessibilityLabel,
+    testID,
+  }) {
+    const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+    const t = resolveFormControlTokens(theme);
+    const anchorRef = React.useRef(null);
+    const [open, setOpen] = React.useState(false);
+    const list = menuItemList(items);
+    const close = () => setOpen(false);
+    // A dialog opened before the menu is gone would lose focus on the web and
+    // fail to present on iOS.
+    const picked = React.useRef(null);
+    const pick = (item) => {
+      picked.current = item.onPress;
+      close();
+    };
+    const runPicked = () => {
+      const run = picked.current;
+      picked.current = null;
+      if (typeof run === "function") run();
+    };
+
+    return h(
+      React.Fragment,
+      null,
+      triggerWith(trigger, {
+        anchorRef,
+        onOpen: () => setOpen(true),
+        extraProps: { "aria-haspopup": "menu", "aria-expanded": open },
+      }),
+      h(
+        AnchoredSurface,
+        {
+          visible: open && list.length > 0,
+          onRequestClose: close,
+          onDismiss: runPicked,
+          anchorRef,
+          placement,
+          padding: t.rowGap,
+          minWidth: POPOVER_DEFAULTS.menuMinWidth,
+          maxWidth: POPOVER_DEFAULTS.menuMaxWidth,
+          accessibilityLabel: isText(accessibilityLabel) ? String(accessibilityLabel) : undefined,
+          closeAccessibilityLabel,
+          testID,
+        },
+        h(MenuItems, { t, items: list, onPick: pick, accessibilityLabel, testID }),
+      ),
+    );
+  }
+
+  Menu.displayName = "Menu";
+  return Menu;
+}

package/dist/overlay-tokens.js

@@ -85,6 +85,56 @@ export function overlayCornerStyle(radius, presentation) {
     : { borderRadius: radius };
 }
 
+/**
+ * The screen box and the panel box of one overlay. An anchored overlay (a
+ * menu or popover placed at its trigger) has no scrim, and its panel sits at
+ * `anchoredAt`, a window position, instead of in the centre or at the bottom.
+ *
+ * @param {object} tokens — `resolveOverlayTokens()`'s result.
+ * @param {{top: number, left: number}|null} [anchoredAt]
+ */
+export function overlayFrameStyles(tokens, anchoredAt) {
+  const look = {
+    backgroundColor: tokens.surface,
+    padding: tokens.padding,
+    ...tokens.elevation,
+  };
+  if (anchoredAt) {
+    return {
+      backdrop: { flex: 1, backgroundColor: "transparent" },
+      panel: {
+        position: "absolute",
+        top: anchoredAt.top,
+        left: anchoredAt.left,
+        ...look,
+        ...overlayCornerStyle(tokens.radius, "dialog"),
+      },
+    };
+  }
+  return {
+    backdrop: {
+      flex: 1,
+      alignItems: "center",
+      justifyContent: tokens.verticalAlign,
+      padding: tokens.screenPadding,
+      ...(tokens.topGap ? { paddingTop: tokens.topGap } : null),
+      backgroundColor: tokens.scrim,
+    },
+    panel: {
+      width: "100%",
+      // Capped to the padded screen box so a tall panel scrolls inside its own
+      // ScrollView instead of overflowing past the viewport unreachably.
+      maxHeight: "100%",
+      flexShrink: 1,
+      ...(tokens.maxWidth ? { maxWidth: tokens.maxWidth } : { flex: 1 }),
+      backgroundColor: look.backgroundColor,
+      ...overlayCornerStyle(tokens.radius, tokens.presentation),
+      padding: look.padding,
+      ...tokens.elevation,
+    },
+  };
+}
+
 /**
  * Resolve the values one overlay is painted with, from the workspace theme.
  *

package/dist/overlay-view.js

@@ -16,7 +16,7 @@
 
 import React from "react";
 import { useHostTheme } from "./hooks.js";
-import { overlayCornerStyle, resolveOverlayTokens } from "./overlay-tokens.js";
+import { overlayFrameStyles, resolveOverlayTokens } from "./overlay-tokens.js";
 
 // Kept clickable, but out of the tab order and the accessibility tree.
 const SILENT_BACKDROP = {
@@ -32,13 +32,58 @@ const SILENT_BACKDROP = {
  *
  * `namesPanel` is for a host whose `Modal` cannot carry the accessible name
  * (React Native's): the panel carries it there, the dialog node on the web.
+ * `awaitsDismiss` is for a host whose `Modal` leaves the screen after it is
+ * told to (iOS): it stays mounted, hidden, until its `onDismiss`.
  *
  * @param {{Modal: any, View: any, Pressable: any, StyleSheet: any,
- *   namesPanel?: boolean}} rn
+ *   namesPanel?: boolean, awaitsDismiss?: boolean}} rn
  */
 export function makeOverlay(rn) {
   const { Modal, View, Pressable, StyleSheet } = rn;
   const namesPanel = Boolean(rn.namesPanel);
+  const awaitsDismiss = Boolean(rn.awaitsDismiss);
+  // Compiled, so the web host can express "box-none" as real CSS rules.
+  let passiveBackdrop = null;
+  const passiveBackdropStyle = () => {
+    passiveBackdrop =
+      passiveBackdrop || StyleSheet.create({ backdrop: { pointerEvents: "box-none" } }).backdrop;
+    return passiveBackdrop;
+  };
+
+  /**
+   * Runs `onDismiss` once a shown overlay has left the screen: after the
+   * commit that removed it (focus already returned on the web), or, where
+   * the host takes it away itself, from that host's `onDismiss`. Returns
+   * the handler to hand the host while it is still dismissing, else null.
+   */
+  function useDismissal(visible, onDismiss) {
+    const onDismissRef = React.useRef(onDismiss);
+    onDismissRef.current = onDismiss;
+    // Decided in render, so the host's Modal is never unmounted mid-dismissal.
+    const [prevVisible, setPrevVisible] = React.useState(visible);
+    const [hostDismissing, setHostDismissing] = React.useState(false);
+    if (visible !== prevVisible) {
+      setPrevVisible(visible);
+      setHostDismissing(!visible && awaitsDismiss && typeof onDismiss === "function");
+    }
+    const hostDismissed = React.useCallback(() => {
+      setHostDismissing(false);
+      if (typeof onDismissRef.current === "function") onDismissRef.current();
+    }, []);
+
+    const shown = React.useRef(false);
+    React.useEffect(() => {
+      if (visible) {
+        shown.current = true;
+        return;
+      }
+      if (!shown.current) return;
+      shown.current = false;
+      if (!awaitsDismiss && typeof onDismissRef.current === "function") onDismissRef.current();
+    }, [visible]);
+
+    return hostDismissing ? hostDismissed : null;
+  }
 
   function Overlay({
     visible = false,
@@ -53,6 +98,9 @@ export function makeOverlay(rn) {
     closeAccessibilityLabel = "Close",
     initialFocusRef,
     panelFrame: PanelFrame,
+    anchoredAt,
+    passive = false,
+    onDismiss,
     style,
     testID,
     children,
@@ -65,36 +113,28 @@ export function makeOverlay(rn) {
     const requestClose = React.useCallback(() => {
       if (typeof onRequestClose === "function") onRequestClose();
     }, [onRequestClose]);
+    const dismissing = useDismissal(visible, onDismiss);
 
+    if (dismissing) {
+      return React.createElement(Modal, {
+        visible: false,
+        transparent: true,
+        animationType: "none",
+        onDismiss: dismissing,
+      });
+    }
     // Unmounted while closed: `Modal` appends a host container the moment it
     // renders, so every widget on the page would otherwise leave one behind.
     if (!visible) return null;
 
-    const backdrop = {
-      flex: 1,
-      alignItems: "center",
-      justifyContent: tokens.verticalAlign,
-      padding: tokens.screenPadding,
-      ...(tokens.topGap ? { paddingTop: tokens.topGap } : null),
-      backgroundColor: tokens.scrim,
-    };
-    const panel = {
-      width: "100%",
-      // Capped to the padded screen box so a tall panel scrolls inside its own
-      // ScrollView instead of overflowing past the viewport unreachably.
-      maxHeight: "100%",
-      flexShrink: 1,
-      ...(tokens.maxWidth ? { maxWidth: tokens.maxWidth } : { flex: 1 }),
-      backgroundColor: tokens.surface,
-      ...overlayCornerStyle(tokens.radius, tokens.presentation),
-      padding: tokens.padding,
-      ...tokens.elevation,
-    };
+    const frame = overlayFrameStyles(tokens, anchoredAt);
+    // A passive layer lets the pointer through everywhere but its panel.
+    const backdrop = passive ? [frame.backdrop, passiveBackdropStyle()] : frame.backdrop;
 
     const panelNode = React.createElement(
       View,
       {
-        style: [panel, style],
+        style: [frame.panel, style],
         accessibilityLabel: namesPanel ? accessibilityLabel : undefined,
         testID,
       },
@@ -113,11 +153,13 @@ export function makeOverlay(rn) {
         "aria-label": accessibilityLabelledBy ? undefined : accessibilityLabel,
         "aria-labelledby": accessibilityLabelledBy,
         initialFocusRef,
+        ...(passive ? { passive } : null),
+        ...(anchoredAt ? { closesOnOutsideScroll: true } : null),
       },
       React.createElement(
         View,
         { style: backdrop },
-        dismissOnBackdropPress
+        dismissOnBackdropPress && !passive
           ? React.createElement(Pressable, {
               style: StyleSheet.absoluteFill,
               onPress: requestClose,
@@ -130,6 +172,7 @@ export function makeOverlay(rn) {
             })
           : null,
         // @internal `panelFrame`: `<Modal>` wraps its panel, never the scrim.
+        // @internal `anchoredAt` / `passive` / `onDismiss`: `<Popover>`, `<Menu>`, `<Tooltip>`.
         PanelFrame
           ? React.createElement(PanelFrame, { verticalAlign: tokens.verticalAlign }, panelNode)
           : panelNode,

package/dist/overlay.native.js

@@ -5,14 +5,16 @@
 // hardware back button to `onRequestClose`, matching what react-native-web's
 // portal does on the web (./overlay.js). Only the import differs.
 
-import { Modal, View, Pressable, StyleSheet } from "react-native";
+import { Modal, View, Pressable, StyleSheet, Platform } from "react-native";
 import { makeOverlay } from "./overlay-view.js";
 
 // RN's `Modal` forwards no ARIA props, so the panel carries the name here.
+// iOS cannot present a modal while another is still being dismissed.
 export const Overlay = makeOverlay({
   Modal,
   View,
   Pressable,
   StyleSheet,
   namesPanel: true,
+  awaitsDismiss: Platform.OS === "ios",
 });

package/dist/people-picker-logic.js

@@ -0,0 +1,203 @@
+// The `<PeoplePicker>` rules that need no renderer: which source it reads,
+// the query each source is asked, how a row is named, and which saved values
+// still need a name. Both hosts share them, and the node suite tests them.
+
+export const PEOPLE_PICKER_SOURCES = Object.freeze(["users", "groups", "records"]);
+export const DEFAULT_PEOPLE_PAGE_SIZE = 50;
+// The directory resolves at most this many ids per request.
+export const MAX_RESOLVE_IDS = 100;
+
+/** A `source` prop as the picker reads it; anything unknown is "users". */
+export function pickerSource(source) {
+  return PEOPLE_PICKER_SOURCES.includes(source) ? source : "users";
+}
+
+function isId(value) {
+  return (typeof value === "string" && value !== "") || typeof value === "number";
+}
+
+function text(value) {
+  if (typeof value === "number") return String(value);
+  if (typeof value !== "string") return "";
+  return value.trim();
+}
+
+/**
+ * The page query a source's hook is asked: the typed search sent to the
+ * server, never filtered from one page here.
+ *
+ * @param {"users"|"groups"|"records"} source
+ * @param {{query?: string, pageSize?: number, groupId?: string, filter?: object}} own
+ */
+export function pageQuery(source, { query, pageSize, groupId, filter } = {}) {
+  const q = text(query);
+  const limit =
+    Number.isInteger(pageSize) && pageSize > 0 ? Math.min(pageSize, 200) : DEFAULT_PEOPLE_PAGE_SIZE;
+  const out = { ...(q ? { q } : null), limit };
+  if (source === "users" && isId(groupId)) out.group_id = groupId;
+  if (source === "records" && filter && typeof filter === "object") out.filter = filter;
+  return out;
+}
+
+// Schema columns arrive as wire `data_type` / `is_identification`; a
+// manifest-derived column carries `dataType` / `isIdentification`, and a
+// column being written names the flag `is_identification_column`.
+function columnType(column) {
+  return column.data_type ?? column.dataType;
+}
+
+function isIdentificationColumn(column) {
+  return Boolean(column.is_identification ?? column.isIdentification ?? column.is_identification_column);
+}
+
+/**
+ * The column a record is named by: the one given, else the table's
+ * identification column, else its first text column, else none.
+ *
+ * @param {{columns?: Array<{name: string, data_type?: string, dataType?: string,
+ *   is_identification?: boolean, isIdentification?: boolean}>}|null} schema
+ * @param {string} [own]
+ */
+export function recordLabelColumn(schema, own) {
+  if (typeof own === "string" && own !== "") return own;
+  const columns = (schema && Array.isArray(schema.columns) ? schema.columns : []).filter(Boolean);
+  const named = columns.find(isIdentificationColumn);
+  if (named) return named.name;
+  const textual = columns.find((column) => ["STRING", "TEXT"].includes(columnType(column)));
+  return textual ? textual.name : null;
+}
+
+/**
+ * A row's name: a user's name or email, a group's name, a record's label
+ * column. A row with none is `unknownText`, never its id.
+ *
+ * @param {object} row
+ * @param {{source: string, labelColumn?: string|null, unknownText: string}} how
+ */
+export function rowLabel(row, { source, labelColumn, unknownText }) {
+  if (!row || typeof row !== "object") return unknownText;
+  if (source === "records") {
+    const cell = labelColumn ? row[labelColumn] : undefined;
+    // A relation cell is hydrated as `{ id, label }`.
+    const shown = cell && typeof cell === "object" ? text(cell.label) : text(cell);
+    return shown || unknownText;
+  }
+  if (source === "users") return text(row.name) || text(row.email) || unknownText;
+  return text(row.name) || unknownText;
+}
+
+/** The rows a page offers: each with an id, none of `excludeIds`. */
+export function offeredRows(rows, excludeIds) {
+  const excluded = new Set(Array.isArray(excludeIds) ? excludeIds.map(String) : []);
+  return (Array.isArray(rows) ? rows : []).filter(
+    (row) => row && isId(row.id) && !excluded.has(String(row.id)),
+  );
+}
+
+/** A `value` or `values` prop as the list of picked ids. */
+export function pickedIds({ multiple, value, values }) {
+  if (multiple) return (Array.isArray(values) ? values : []).filter(isId);
+  return isId(value) ? [value] : [];
+}
+
+/**
+ * The picked ids no row has named and no lookup has tried yet: each is asked
+ * for once, so a deleted person is not looked up on every render.
+ *
+ * @param {Array<string|number>} ids
+ * @param {Map<string, object>} knownRows — id → row.
+ * @param {Set<string>} attempted — ids already looked up.
+ */
+export function unresolvedIds(ids, knownRows, attempted) {
+  return (Array.isArray(ids) ? ids : []).filter(
+    (id) => !knownRows.has(String(id)) && !attempted.has(String(id)),
+  );
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Split saved ids into those a users or groups lookup can ask for and those
+ * it cannot: the directory refuses a whole batch over one id that is not a
+ * UUID, so such an id is named unknown at once instead. Record ids are each
+ * read alone, so every one is asked for.
+ *
+ * @param {Array<string|number>} ids
+ * @param {"users"|"groups"|"records"} source
+ */
+export function lookupableIds(ids, source) {
+  const list = Array.isArray(ids) ? ids : [];
+  if (source === "records") return { lookup: list, unknown: [] };
+  const lookup = [];
+  const unknown = [];
+  for (const id of list) (typeof id === "string" && UUID.test(id) ? lookup : unknown).push(id);
+  return { lookup, unknown };
+}
+
+/**
+ * The lookups in flight, with `ids` that none of them holds yet added as new
+ * batches. A batch keeps the key it was given, so an id resolving elsewhere
+ * never restarts a lookup still out. Returns `queue` itself when nothing is new.
+ *
+ * @param {{pending: Array<{key: number, ids: Array<string|number>}>, next: number}} queue
+ * @param {Array<string|number>} ids
+ * @param {number} [size]
+ */
+export function queueLookups(queue, ids, size = MAX_RESOLVE_IDS) {
+  const out = new Set(queue.pending.flatMap((batch) => batch.ids.map(String)));
+  const fresh = (Array.isArray(ids) ? ids : []).filter((id) => !out.has(String(id)));
+  if (fresh.length === 0) return queue;
+  const added = batches(fresh, size).map((batch, i) => ({ key: queue.next + i, ids: batch }));
+  return { pending: [...queue.pending, ...added], next: queue.next + added.length };
+}
+
+/** `queue` without the lookup `key`. */
+export function settleLookup(queue, key) {
+  return { ...queue, pending: queue.pending.filter((batch) => batch.key !== key) };
+}
+
+/**
+ * Whether a page hook's result answers the query it was last asked. After the
+ * query changes, the hook still holds the previous answer until it starts
+ * loading or returns new rows, so that answer is not reported as this one.
+ *
+ * @param {{queryKey: string|null, rows: unknown, error: unknown}|null} last — what was last reported.
+ * @param {{queryKey: string|null, rows: unknown, error: unknown, loading: boolean}} now
+ */
+export function answersQuery(last, now) {
+  if (!last || last.queryKey === now.queryKey) return true;
+  return now.loading || now.rows !== last.rows || now.error !== last.error;
+}
+
+/** `ids` in batches of at most `size`. */
+export function batches(ids, size = MAX_RESOLVE_IDS) {
+  const list = Array.isArray(ids) ? ids : [];
+  const out = [];
+  for (let start = 0; start < list.length; start += size) out.push(list.slice(start, start + size));
+  return out;
+}
+
+/**
+ * What the trigger shows for each picked id: its row's name, "loading" while
+ * the lookup is out, `unknownText` once it found nothing. Never the raw id.
+ *
+ * @param {Array<string|number>} ids
+ * @param {{knownRows: Map<string, object>, attempted: Set<string>,
+ *   nameOf: (row: object) => string, loadingText: string, unknownText: string}} how
+ */
+export function pickedLabels(ids, { knownRows, attempted, nameOf, loadingText, unknownText }) {
+  return (Array.isArray(ids) ? ids : []).map((id) => {
+    const row = knownRows.get(String(id));
+    if (row) return { value: id, label: nameOf(row), row };
+    return { value: id, label: attempted.has(String(id)) ? unknownText : loadingText };
+  });
+}
+
+/** `knownRows` with every row in `rows` added by id. */
+export function rememberRows(knownRows, rows) {
+  const next = new Map(knownRows);
+  for (const row of Array.isArray(rows) ? rows : []) {
+    if (row && isId(row.id)) next.set(String(row.id), row);
+  }
+  return next;
+}