@colixsystems/widget-sdk 0.246.0 → 0.247.0

package/dist/people-picker-view.js

@@ -0,0 +1,247 @@
+// The ONE implementation behind the `<PeoplePicker>` SDK primitive: a
+// searchable `<Select>` over the workspace's users, its groups, or one
+// table's records, read through the SDK's own directory and datastore hooks.
+// The platform bindings (`people-picker.js` / `people-picker.native.js`)
+// differ only in which host's `<Select>` and `<Avatar>` they pass.
+//
+// Nothing is fetched until the sheet first opens; each pause in typing asks
+// the server again. A saved choice the page does not hold is looked up once
+// by id, so the trigger names it and never shows the raw id.
+
+import React from "react";
+import {
+  useDatastoreQuery,
+  useDatastoreRecord,
+  useDatastoreSchema,
+  useDirectory,
+  useGroups,
+} from "./hooks.js";
+import {
+  answersQuery,
+  lookupableIds,
+  offeredRows,
+  pageQuery,
+  pickedIds,
+  pickedLabels,
+  pickerSource,
+  queueLookups,
+  recordLabelColumn,
+  rememberRows,
+  rowLabel,
+  settleLookup,
+  unresolvedIds,
+} from "./people-picker-logic.js";
+
+const h = React.createElement;
+const NO_ROWS = Object.freeze([]);
+const NO_LOOKUPS = Object.freeze({ pending: [], next: 0 });
+
+function serialize(query) {
+  try {
+    return JSON.stringify(query);
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Bind the shared people picker to one host's `<Select>` and `<Avatar>`.
+ *
+ * @param {{View: any, Select: any, Avatar: any}} rn
+ */
+export function makePeoplePicker(rn) {
+  const { View, Select, Avatar } = rn;
+
+  // Hands one hook result up once it answers the current query.
+  function useReport(onReport, query, rows, loading, error, sent) {
+    const queryKey = serialize(query);
+    const last = React.useRef(null);
+    React.useEffect(() => {
+      const now = { queryKey, rows, error, loading };
+      if (!answersQuery(last.current, now)) return;
+      last.current = now;
+      onReport({ rows: Array.isArray(rows) ? rows : NO_ROWS, loading, error: error || null, query: sent });
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [queryKey, rows, loading, error, sent]);
+  }
+
+  function UsersPage({ query, sent, onReport }) {
+    const { users, loading, error } = useDirectory(query);
+    useReport(onReport, query, users, loading, error, sent);
+    return null;
+  }
+
+  function GroupsPage({ query, sent, onReport }) {
+    const { groups, loading, error } = useGroups(query);
+    useReport(onReport, query, groups, loading, error, sent);
+    return null;
+  }
+
+  function RecordsPage({ table, query, sent, onReport }) {
+    const { data, loading, fetching, error } = useDatastoreQuery(table, query);
+    useReport(onReport, query, data, loading || fetching, error, sent);
+    return null;
+  }
+
+  // A lookup reports once it settles; a failed one names nothing.
+  function useResolved(onResolved, lookup, settled, rows) {
+    React.useEffect(() => {
+      if (settled) onResolved(lookup, rows || NO_ROWS);
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [settled]);
+  }
+
+  function UsersLookup({ lookup, onResolved }) {
+    const { users, loading, error } = useDirectory({ ids: lookup.ids, limit: lookup.ids.length });
+    useResolved(onResolved, lookup, !loading, error ? null : users);
+    return null;
+  }
+
+  function GroupsLookup({ lookup, onResolved }) {
+    const { groups, loading, error } = useGroups({ ids: lookup.ids, limit: lookup.ids.length });
+    useResolved(onResolved, lookup, !loading, error ? null : groups);
+    return null;
+  }
+
+  // The datastore list filters no system `id`, so each saved record is read alone.
+  function RecordLookup({ table, lookup, onResolved }) {
+    const { data, loading, error } = useDatastoreRecord(table, lookup.ids[0]);
+    useResolved(onResolved, lookup, !loading, error || !data ? null : [data]);
+    return null;
+  }
+
+  const LOOKUPS = { users: UsersLookup, groups: GroupsLookup, records: RecordLookup };
+
+  function avatarFor(source, row, label, avatarColumn) {
+    if (source === "records") {
+      if (!avatarColumn) return undefined;
+      const fileId = typeof row[avatarColumn] === "string" ? row[avatarColumn] : null;
+      return h(Avatar, { name: label, fileId, seed: String(row.id), size: "sm" });
+    }
+    return h(Avatar, {
+      name: label,
+      seed: String(row.id),
+      size: "sm",
+      shape: source === "groups" ? "rounded" : "circle",
+    });
+  }
+
+  // The row's name is its text; the picture only decorates it.
+  function decoration(node) {
+    if (!node) return undefined;
+    return h(
+      View,
+      {
+        "aria-hidden": true,
+        importantForAccessibility: "no-hide-descendants",
+        accessibilityElementsHidden: true,
+      },
+      node,
+    );
+  }
+
+  function SourcePicker(props) {
+    const {
+      source,
+      table,
+      labelColumn,
+      avatarColumn,
+      groupId,
+      filter,
+      excludeIds,
+      pageSize,
+      showAvatars = true,
+      unknownText = "Unknown",
+      loadingText = "Loading…",
+      multiple = false,
+      value,
+      values,
+      forwardedRef,
+      ...rest
+    } = props;
+    const [sent, setSent] = React.useState(null);
+    const [page, setPage] = React.useState({ rows: NO_ROWS, loading: false, error: null, query: null });
+    const [knownRows, setKnownRows] = React.useState(() => new Map());
+    const [attempted, setAttempted] = React.useState(() => new Set());
+    const [lookups, setLookups] = React.useState(NO_LOOKUPS);
+
+    const how = { source, labelColumn, unknownText };
+    const nameOf = (row) => rowLabel(row, how);
+    const toOption = (row) => {
+      const label = nameOf(row);
+      return {
+        value: row.id,
+        label,
+        ...(showAvatars ? { leading: decoration(avatarFor(source, row, label, avatarColumn)) } : null),
+      };
+    };
+
+    const onReport = React.useCallback((result) => {
+      setPage(result);
+      if (result.rows.length) setKnownRows((own) => rememberRows(own, result.rows));
+    }, []);
+    const onResolved = React.useCallback((lookup, rows) => {
+      setKnownRows((own) => rememberRows(own, rows));
+      setAttempted((own) => new Set([...own, ...lookup.ids.map(String)]));
+      setLookups((own) => settleLookup(own, lookup.key));
+    }, []);
+
+    // A record source with no table bound yet has nothing to read.
+    const readable = source !== "records" || (typeof table === "string" && table !== "");
+    const ids = pickedIds({ multiple, value, values });
+    const missing = readable ? unresolvedIds(ids, knownRows, attempted) : [];
+    const { lookup, unknown } = lookupableIds(missing, source);
+    const named = unknown.length ? new Set([...attempted, ...unknown.map(String)]) : attempted;
+    const query = sent === null || !readable ? null : pageQuery(source, { query: sent, pageSize, groupId, filter });
+    const options = offeredRows(page.rows, excludeIds).map(toOption);
+    const selectedOptions = pickedLabels(ids, { knownRows, attempted: named, nameOf, loadingText, unknownText }).map(
+      (own) => (own.row ? toOption(own.row) : own),
+    );
+
+    const lookupKey = lookup.join(",");
+    React.useEffect(() => {
+      if (lookup.length) setLookups((own) => queueLookups(own, lookup, source === "records" ? 1 : undefined));
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [lookupKey]);
+
+    const pages = { users: UsersPage, groups: GroupsPage, records: RecordsPage };
+    const Lookup = LOOKUPS[source];
+
+    return h(
+      React.Fragment,
+      null,
+      h(Select, {
+        ...rest,
+        ref: forwardedRef,
+        multiple,
+        value,
+        values,
+        options,
+        selectedOptions,
+        onSearch: setSent,
+        loading: sent !== null && (page.query !== sent || page.loading),
+        optionsError: !!page.error,
+        loadingText,
+      }),
+      query ? h(pages[source], { table, query, sent, onReport }) : null,
+      ...lookups.pending.map((own) => h(Lookup, { key: own.key, table, lookup: own, onResolved })),
+    );
+  }
+
+  // A record source names rows by a column, so it waits for the table's schema.
+  function RecordsPicker(props) {
+    const { schema } = useDatastoreSchema(props.table || null);
+    return h(SourcePicker, { ...props, labelColumn: recordLabelColumn(schema, props.labelColumn) });
+  }
+
+  const PeoplePicker = React.forwardRef(function PeoplePicker(props, ref) {
+    const source = pickerSource(props.source);
+    const own = { ...props, source, forwardedRef: ref };
+    // Changing the source starts a fresh picker rather than mixing rows.
+    if (source === "records") return h(RecordsPicker, { ...own, key: `records:${props.table}` });
+    return h(SourcePicker, { ...own, key: source });
+  });
+
+  PeoplePicker.displayName = "PeoplePicker";
+  return PeoplePicker;
+}

package/dist/people-picker.js

@@ -0,0 +1,11 @@
+// `<PeoplePicker>` (web). Binds ./people-picker-view.js to the web `<Select>`
+// and `<Avatar>`; see ./primitives.js for why not the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import { makePeoplePicker } from "./people-picker-view.js";
+import { Select } from "./select.js";
+import { Avatar } from "./detail-parts.js";
+
+const { View } = ReactNative;
+
+export const PeoplePicker = makePeoplePicker({ View, Select, Avatar });

package/dist/people-picker.native.js

@@ -0,0 +1,9 @@
+// `<PeoplePicker>` (native). Binds ./people-picker-view.js to the native
+// `<Select>` and `<Avatar>`; only the imports differ from ./people-picker.js.
+
+import { View } from "react-native";
+import { makePeoplePicker } from "./people-picker-view.js";
+import { Select } from "./select.native.js";
+import { Avatar } from "./detail-parts.native.js";
+
+export const PeoplePicker = makePeoplePicker({ View, Select, Avatar });

package/dist/select-search-logic.js

@@ -0,0 +1,150 @@
+// The searchable `<Select>` rules that need no renderer: when a typed query
+// is sent, which answer is still wanted, what the sheet shows meanwhile, and
+// the labels it keeps for picked values the current page no longer holds.
+// Both hosts share them, and the node suite tests them.
+
+import { normaliseThemeComponents } from "./theme-components.js";
+
+/** How long typing must pause before the query is sent, in ms. */
+export const DEFAULT_SEARCH_DEBOUNCE_MS = 250;
+
+/** A typed query as it is sent: trimmed, never null. */
+export function normaliseQuery(text) {
+  return typeof text === "string" ? text.trim() : "";
+}
+
+/**
+ * A trailing debounce: `push` restarts the wait, and only the last text
+ * pushed is delivered, once typing pauses. `cancel` drops a pending one.
+ *
+ * @param {number|(() => number)} delay — ms, or a getter read at each push
+ *   so a changed delay applies to the next pause; below 0 counts as 0.
+ * @param {(query: string) => void} deliver
+ * @param {{setTimeout: Function, clearTimeout: Function}} [timers]
+ */
+export function createDebouncer(delay, deliver, timers = globalThis) {
+  const waitFor = () => {
+    const ms = typeof delay === "function" ? delay() : delay;
+    return Number.isFinite(ms) && ms > 0 ? ms : 0;
+  };
+  let pending = null;
+  const cancel = () => {
+    if (pending !== null) timers.clearTimeout(pending);
+    pending = null;
+  };
+  return {
+    push(text) {
+      cancel();
+      pending = timers.setTimeout(() => {
+        pending = null;
+        deliver(normaliseQuery(text));
+      }, waitFor());
+    },
+    cancel,
+  };
+}
+
+/**
+ * Numbers each request so only the latest one's answer is used; an answer to
+ * a query the person has already typed past is dropped.
+ */
+export function createRequestGate() {
+  let latest = 0;
+  return {
+    begin: () => ++latest,
+    isCurrent: (ticket) => ticket === latest,
+  };
+}
+
+/**
+ * The options whose label holds the query, case-insensitively; all of them
+ * for an empty query. For a list that is searched where it is held.
+ *
+ * @param {Array<{label: unknown}>} options
+ * @param {string} query
+ */
+export function filterOptions(options, query) {
+  const list = Array.isArray(options) ? options : [];
+  const needle = normaliseQuery(query).toLocaleLowerCase();
+  if (!needle) return list;
+  return list.filter((option) =>
+    String(option && option.label != null ? option.label : "")
+      .toLocaleLowerCase()
+      .includes(needle),
+  );
+}
+
+/**
+ * What the sheet's body shows: a spinner while the answer is pending, the
+ * error, the "nothing matches" note for a query with no result, the empty
+ * note for no options at all, else the list.
+ *
+ * @param {{loading?: boolean, error?: boolean, query?: string, count: number}} state
+ * @returns {"loading"|"error"|"noResults"|"empty"|"list"}
+ */
+export function sheetBody({ loading, error, query, count }) {
+  if (loading) return "loading";
+  if (error) return "error";
+  if (count > 0) return "list";
+  return normaliseQuery(query) ? "noResults" : "empty";
+}
+
+// 1 and "1" are two values; the key keeps them apart.
+function valueKey(value) {
+  return `${typeof value}:${value}`;
+}
+
+/**
+ * A copy of `known` (value key → option) holding every option in `lists`,
+ * later lists winning. A searchable select remembers each option it has
+ * shown, so a picked one keeps its label after a search drops it.
+ *
+ * @param {Map<string, object>} known
+ * @param {...Array<{value: string|number}>} lists
+ */
+export function rememberOptions(known, ...lists) {
+  const next = new Map(known instanceof Map ? known : []);
+  for (const list of lists) {
+    for (const option of Array.isArray(list) ? list : []) {
+      if (option && (typeof option.value === "string" || typeof option.value === "number")) {
+        next.set(valueKey(option.value), option);
+      }
+    }
+  }
+  return next;
+}
+
+/** The remembered option for one value, or undefined. */
+export function knownOption(known, value) {
+  return known instanceof Map ? known.get(valueKey(value)) : undefined;
+}
+
+/**
+ * The remembered options for `values`, in their order; a value nothing has
+ * named is left out rather than shown by its raw value.
+ *
+ * @param {Map<string, object>} known
+ * @param {Array<string|number>} values
+ */
+export function knownOptions(known, values) {
+  return (Array.isArray(values) ? values : [])
+    .map((value) => knownOption(known, value))
+    .filter(Boolean);
+}
+
+/**
+ * The row size a searchable sheet takes from the theme's `list` scope: only
+ * the values the theme sets, so an unthemed list keeps the option row's own.
+ *
+ * @param {object} theme — the resolved workspace theme.
+ * @returns {{minHeight?: number, paddingHorizontal?: number}}
+ */
+export function searchRowOverrides(theme) {
+  const components = theme && typeof theme === "object" ? theme.components : undefined;
+  const list = normaliseThemeComponents({ list: components && components.list }).list || {};
+  const out = {};
+  // A row stays a 44px target however small the theme draws list rows.
+  if (Number.isFinite(list.rowMinHeight)) out.minHeight = Math.max(44, list.rowMinHeight);
+  if (Number.isFinite(list.rowPadding)) out.paddingHorizontal = list.rowPadding;
+  return out;
+}