@uiresponse/renderer-react 0.1.0

package/src/core/record.js

@@ -0,0 +1,160 @@
+/**
+ * Drawing ONE record: the pure decisions behind the `detail` block's hierarchy.
+ *
+ * A record has a name, a state, and then some facts. Which is which is not a style choice and not a
+ * guess — it is `column.role`, which the dataset already declares, and which exists so that "a model
+ * can assemble a good page rather than merely a valid one: bind `name` to the row title, `status` to
+ * a badge" (`data.schema.json#columnRole`).
+ *
+ * These functions are here, free of React, for the same reason `format.js` and `empty.js` are: they
+ * are the semantics, and the semantics are what must not regress.
+ */
+
+/**
+ * Tone for a status the document did not tone.
+ *
+ * `badge` lets an author state tone outright (`tone`) or map it (`tone_map`). `detail` has neither
+ * prop and may not grow one — tone is not in that block's vocabulary, and Principle 1 keeps colour
+ * out of the document. So the renderer recognises a small, CLOSED vocabulary of process words and
+ * stays neutral for everything else.
+ *
+ * Neutral is the honest default. Colouring an unrecognised status would be a guess rendered as a
+ * fact, on a real label's real pipeline, where "Cancelled" and "Cleared" both start with C.
+ */
+const STATUS_TONES = [
+  [/^(live|released|complete|completed|done|signed|approved|delivered|paid|cleared)$/i, "positive"],
+  [/^(overdue|blocked|rejected|cancelled|canceled|failed|void|at risk)$/i, "negative"],
+  [/^(pending|waiting|in progress|in review|draft|scheduled|chasing|on hold)$/i, "warning"],
+];
+
+export function statusTone(value) {
+  const s = String(value ?? "").trim();
+  for (const [re, tone] of STATUS_TONES) if (re.test(s)) return tone;
+  return "neutral";
+}
+
+/** Only absolute http(s) may be drawn as a link, checked at the point of use (VERSIONING §9). */
+export const isHttpUrl = (v) => typeof v === "string" && /^https?:\/\//i.test(v);
+
+/**
+ * What may be drawn as an IMAGE: absolute http(s), or an inline `data:image/…` URI. The two gates
+ * differ on purpose — a data URI is a perfectly good picture and a nonsensical link, so seed and
+ * offline corpora can carry self-contained artwork without the renderer mistaking it for a URL a
+ * person could visit. Nothing else (javascript:, blob:, relative paths) is drawn at all.
+ */
+export const isImageSrc = (v) => isHttpUrl(v) || (typeof v === "string" && /^data:image\//i.test(v));
+
+/** Absent for the purpose of promotion: a headline cannot be an empty string. */
+export const isEmptyish = (v) => v === null || v === undefined || v === "";
+
+/** A url a person can read: the host and its path, without the ceremony. */
+export function linkText(url) {
+  try {
+    const u = new URL(url);
+    const tail = `${u.pathname}${u.search}`.replace(/\/$/, "");
+    return `${u.host.replace(/^www\./, "")}${tail}`;
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * The image column a list draws its posters from, or null.
+ *
+ * `role: image` is the dataset saying "this column is a picture, not a URL" — the same declaration a
+ * table already reads to draw a thumbnail. A list read it nowhere, so a list of records with cover
+ * art rendered as a column of text.
+ */
+export const imageColumn = (columns) => (columns ?? []).find((c) => c?.role === "image") ?? null;
+
+/**
+ * Rail or grid, decided from the content.
+ *
+ * `layout.columns` was deleted from the language (R5) precisely so this is the renderer's call. Four
+ * or more sleeves read as a shelf you push through; three or fewer read as a row that happens to be
+ * short, and making those scroll would be a lie about how much there is.
+ */
+export const RAIL_THRESHOLD = 4;
+export const posterMode = (count) => (count >= RAIL_THRESHOLD ? "rail" : "grid");
+
+/**
+ * A section is EDITORIAL when it has a headline and opens with a sentence.
+ *
+ * `section.title` followed by a `text` child is the only way OBL can express "a headline, then one
+ * line saying what these things have in common". The composition was always expressible; the renderer
+ * just drew both parts in the same quiet grey. Reading it costs no schema and no new block, and a
+ * voice renderer already honours it — it reads the title, then the sentence, then the things.
+ */
+export const isEditorialSection = (block) => Boolean(block?.title) && block?.children?.[0]?.type === "text";
+
+/**
+ * THE PAGE ALREADY HAS A HEADLINE, so the shell must not print a second one.
+ *
+ * A browse answer is one editorial section: a headline, a standfirst, then the things. The shell drew
+ * `page.title` above it as well — and because a two-leaf page is "an answer, not a document", that
+ * title rendered as the 12px grey label, sitting directly on top of the 30px headline. Two titles,
+ * six pixels apart, saying nearly the same thing in two different voices.
+ *
+ * Only the SHELL's title is dropped, and only when the document's own first and only top-level block
+ * is the headline. `page.title` is untouched: it is what the overlay's head, the saved-page list and
+ * the browser address the page by. The header line survives too — it still carries the dataset status.
+ */
+export const pageHeadlineIsInDocument = (page) => {
+  const blocks = page?.blocks ?? [];
+  return blocks.length === 1 && blocks[0]?.type === "section" && isEditorialSection(blocks[0]);
+};
+
+/**
+ * BLUR-UP: the low-resolution proxy of an image column, by convention rather than by schema.
+ *
+ * A cover arriving as a raw JPEG paints top-down, band by band, which is the ugliest thing on the
+ * page. The fix is the oldest one there is: show a tiny version instantly, blurred, and cross-fade to
+ * the real one. Airtable already makes the tiny version — every attachment carries `thumbnails.small`
+ * — so nothing has to be generated, only mapped.
+ *
+ * Where does the renderer LOOK for it? Not in a new schema property: `blur_thumb: "..."` would be a
+ * visual instruction in a document that forbids them (Principle 1), and a voice renderer could not
+ * honour it. So it is a NAME: the proxy of `artwork_url` is the column `artwork_thumb_url`, exactly
+ * as the proxy of `image_url` is `image_thumb_url`. A connector that has thumbnails maps one; a
+ * connector that has none maps nothing, and the image fades in from empty instead. Same document,
+ * same blocks, one more column — and the column is honest, because it really is data about the row.
+ *
+ * It is data about the row's PICTURE, though, not a fact about the record, so `defaultColumnSpecs`
+ * below keeps it out of any table or detail that did not ask for it by name.
+ */
+const THUMB_SUFFIX = "_thumb_url";
+export const thumbNameFor = (name) =>
+  typeof name === "string" ? `${name.replace(/_url$/, "")}${THUMB_SUFFIX}` : null;
+export const isThumbName = (name) => typeof name === "string" && name.endsWith(THUMB_SUFFIX);
+export const thumbColumn = (columns, imageCol) => {
+  if (!imageCol) return null;
+  const want = thumbNameFor(imageCol.name);
+  return (columns ?? []).find((c) => c?.name === want) ?? null;
+};
+
+/**
+ * Every column the dataset declared, in declared order — what `columns`/`fields` mean when omitted.
+ * Minus the blur-up proxies, which are a picture's loading state and never a column of a table.
+ */
+export const defaultColumnSpecs = (columns) =>
+  (columns ?? []).filter((c) => !isThumbName(c?.name)).map((c) => ({ field: c.name }));
+
+/** A row's arrival delay index, capped so a long table does not take seconds to finish appearing. */
+export const STAGGER_CAP = 12;
+export const staggerIndex = (i) => Math.min(i, STAGGER_CAP);
+
+/**
+ * Split a record's field specs into a headline, its status badges, and the quiet facts.
+ *
+ * `find`, not `filter`, for the headline: a record has ONE name. A second name-role column stays in
+ * the facts, where it is a fact. A dataset that declares no `name` role gets `head: null` and the
+ * caller draws the flat list it always drew — inventing a headline from the first column would be
+ * the renderer making a claim the author did not.
+ */
+export function splitRecordFields(withCols, row) {
+  const head = withCols.find(({ col }) => col?.role === "name" && !isEmptyish(row[col.name])) ?? null;
+  const badges = head ? withCols.filter(({ col }) => col?.role === "status" && !isEmptyish(row[col.name])) : [];
+  const promoted = new Set([head, ...badges].filter(Boolean).map(({ spec }) => spec.field));
+  const facts = withCols.filter(({ spec }) => !promoted.has(spec.field));
+  return { head, badges, facts };
+}

package/src/core/store.js

@@ -0,0 +1,357 @@
+/**
+ * Top-down progressive loading.
+ *
+ * The behaviour Dan asked for by name, and the one that makes a generated page feel like a product
+ * rather than a spinner:
+ *
+ *   1. The page's STRUCTURE paints immediately. Every block draws its frame, its title and its
+ *      skeleton on the first frame, before a single row exists. The shape of the answer is knowable
+ *      from the document alone — that is what a semantic block language buys you.
+ *   2. Datasets resolve in FIRST-USE ORDER, walking the block tree top-down. The dataset the top
+ *      block needs is requested first; the dataset only the last tab needs is requested last.
+ *   3. `intent.priority` breaks ties. Two datasets first used at the same depth resolve `primary`
+ *      before `supporting` before `ambient` — the page's own statement of what matters, honoured
+ *      as load order. This is `priority` earning its keep as more than an annotation (DECISIONS I4).
+ *   4. Each block paints the moment ITS datasets land. One slow royalty aggregation does not hold
+ *      the contract queue hostage.
+ *
+ * Concurrency is bounded, deliberately. Firing every dataset at once is the fastest way to fill the
+ * page and the slowest way to fill the TOP of it: the browser's connection pool would serve the
+ * footer's chart in parallel with the header's metric, and the user reads top-down.
+ */
+import { useCallback, useEffect, useMemo, useReducer, useRef } from "react";
+import { collectDatasets, collectParams } from "./value.js";
+
+const PRIORITY_RANK = { primary: 0, supporting: 1, ambient: 2 };
+const rankOf = (block) => PRIORITY_RANK[block?.intent?.priority] ?? 1;
+export const DATASET_TIMEOUT_MS = 20_000;
+
+/** Flatten the block tree in document order, carrying each block's depth. */
+export function flattenBlocks(page) {
+  const out = [];
+  const walk = (block, depth, parent) => {
+    out.push({ block, depth, parent });
+    for (const child of block.children ?? []) walk(child, depth + 1, block);
+  };
+  for (const b of page.blocks ?? []) walk(b, 0, null);
+  return out;
+}
+
+/**
+ * The load plan: dataset names in the order they should be requested.
+ *
+ * First-use index (document order) is primary; `intent.priority` of the first block to use it is
+ * the tiebreak. A dataset used by a `primary` metric at index 4 outranks one used by an `ambient`
+ * footnote at index 4, and both outrank anything at index 9.
+ */
+export function planDatasetOrder(page) {
+  const flat = flattenBlocks(page);
+  const firstUse = new Map(); // dataset -> { index, rank }
+
+  // Document order means the first sighting IS the lowest index, so we only ever record a dataset
+  // once. The tiebreak matters when two DIFFERENT datasets are first used at the same index — a
+  // card whose `visible_when` reads one dataset while its children read another.
+  flat.forEach(({ block }, index) => {
+    for (const name of collectDatasets(block)) {
+      if (!firstUse.has(name)) firstUse.set(name, { index, rank: rankOf(block) });
+    }
+  });
+
+  const declared = (page.data ?? []).map((d) => d.name);
+  return declared
+    .filter((name) => firstUse.has(name))
+    .sort((a, b) => {
+      const A = firstUse.get(a), B = firstUse.get(b);
+      return A.index - B.index || A.rank - B.rank || declared.indexOf(a) - declared.indexOf(b);
+    });
+}
+
+/** Which parameters does each dataset's query read? `set_param` invalidates exactly those datasets. */
+export function datasetParamDeps(page) {
+  const deps = new Map();
+  for (const ds of page.data ?? []) deps.set(ds.name, collectParams(ds.query ?? {}));
+  return deps;
+}
+
+/** Initial parameter values: declared defaults, overridden by the host's session/url values. */
+export function initialParams(page, supplied = {}) {
+  const params = {};
+  for (const p of page.params ?? []) {
+    params[p.name] = Object.prototype.hasOwnProperty.call(supplied, p.name)
+      ? supplied[p.name]
+      : "default" in p ? p.default : null;
+  }
+  return { ...params, ...supplied };
+}
+
+// ---------------------------------------------------------------------------
+// state
+// ---------------------------------------------------------------------------
+// Per dataset: { status: "idle"|"loading"|"ready"|"error", rows, columns, error, epoch }
+
+function reducer(state, action) {
+  switch (action.type) {
+    case "sync": {
+      const next = {};
+      for (const ds of action.datasets) {
+        next[ds.name] = state.datasets[ds.name] ?? {
+          status: "idle", rows: [], columns: ds.columns ?? [], error: null, stale: false,
+        };
+      }
+      return { ...state, datasets: next };
+    }
+    case "loading":
+      return { ...state, datasets: { ...state.datasets, [action.name]: { ...state.datasets[action.name], status: "loading" } } };
+    case "ready":
+      return { ...state, datasets: { ...state.datasets, [action.name]: { status: "ready", rows: action.rows, columns: action.columns, error: null } } };
+    case "error":
+      return { ...state, datasets: { ...state.datasets, [action.name]: { status: "error", rows: [], columns: action.columns ?? [], error: action.error } } };
+    case "invalidate": {
+      const next = { ...state.datasets };
+      // An invalidated dataset returns to `idle`, KEEPING its last rows. A filter change should
+      // dim the old answer, not blank the table — a blank table reads as "no matching rows", which
+      // is the confident lie this renderer exists to refuse.
+      for (const name of action.names) next[name] = { ...next[name], status: "idle", stale: true };
+      return { ...state, datasets: next, epoch: state.epoch + 1 };
+    }
+    case "params":
+      return { ...state, params: { ...state.params, ...action.params } };
+    default:
+      return state;
+  }
+}
+
+/**
+ * One bounded dataset request. Timeout aborts the browser fetch and rejects with a stable message;
+ * callers retain the abort handle so unmounts, parameter changes and manual refreshes also stop
+ * work that no longer has a consumer. Nothing here retries — an error is terminal until the user
+ * explicitly presses the block's Retry control.
+ */
+export function startDatasetResolve(resolve, args, { timeoutMs = DATASET_TIMEOUT_MS } = {}) {
+  const controller = new AbortController();
+  let settled = false;
+  let timer;
+  let rejectOuter;
+
+  const promise = new Promise((resolveOuter, reject) => {
+    rejectOuter = reject;
+    const finish = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      fn(value);
+    };
+    timer = setTimeout(() => {
+      const error = new Error(`Dataset "${args.dataset}" timed out after ${Math.ceil(timeoutMs / 1000)}s.`);
+      controller.abort(error);
+      finish(reject, error);
+    }, timeoutMs);
+
+    Promise.resolve()
+      .then(() => resolve({ ...args, signal: controller.signal }))
+      .then((value) => finish(resolveOuter, value), (error) => finish(reject, error));
+  });
+
+  return {
+    promise,
+    signal: controller.signal,
+    abort(reason = `Dataset "${args.dataset}" was cancelled.`) {
+      if (settled) return;
+      const error = new Error(reason);
+      controller.abort(error);
+      settled = true;
+      clearTimeout(timer);
+      rejectOuter(error);
+    },
+  };
+}
+
+function initState(page, suppliedParams) {
+  const datasets = {};
+  for (const ds of page.data ?? []) datasets[ds.name] = { status: "idle", rows: [], columns: ds.columns ?? [], error: null, stale: false };
+  return { datasets, params: initialParams(page, suppliedParams), epoch: 0 };
+}
+
+/**
+ * @param {object} page      the OBL page document
+ * @param {Function} resolve `({page, dataset, params}) => Promise<{rows}>` — the ONE data surface.
+ *                           The renderer never sees a connector, a query, or a credential.
+ * @param {object} options
+ * @param {object} [options.params]      host-supplied param values (url, session)
+ * @param {number} [options.concurrency] datasets in flight at once. 2 keeps the top of the page
+ *                                       first without leaving one slow query alone on the wire.
+ */
+export function usePageData(page, resolve, { params: suppliedParams, concurrency = 2, timeoutMs = DATASET_TIMEOUT_MS } = {}) {
+  const [state, dispatch] = useReducer(reducer, undefined, () => initState(page, suppliedParams));
+  const order = useMemo(() => planDatasetOrder(page), [page]);
+  const paramDeps = useMemo(() => datasetParamDeps(page), [page]);
+  const inflight = useRef(new Set());
+  const requests = useRef(new Map());
+  const generation = useRef(0);
+  const unmounted = useRef(false);
+  /**
+   * Datasets that have SETTLED (ready or error) for the current generation, recorded synchronously
+   * — the reducer's answer arrives only when React next flushes. Without this, a resolver that
+   * settles in the same microtask turn (any in-memory resolver: tests, demos, offline fixtures)
+   * starves that flush: the post-settle pump reads the pre-flush `status: "idle"` through
+   * `latest`, refires the same dataset, settles again, and the microtask chain never yields to
+   * the MessageChannel macrotask React flushes on — a hard main-thread freeze (measured at 1.4M
+   * resolves in 8s). Same principle as `inflight` above: the ref is the authority, the reducer
+   * is the render. Entries are generation-scoped, so `setParam`/`refresh` (which bump the
+   * generation as they invalidate) naturally re-arm the pump.
+   */
+  const settled = useRef(new Map());
+
+  // The pump reads the LATEST state through a ref rather than through the effect's closure. An
+  // effect that closes over `state.datasets` and cancels on cleanup would abort every in-flight
+  // request the moment the first one landed and re-rendered — the datasets would never arrive.
+  const latest = useRef(state);
+  latest.current = state;
+
+  const columnsFor = useCallback(
+    (name) => (page.data ?? []).find((d) => d.name === name)?.columns ?? [],
+    [page],
+  );
+
+  useEffect(() => {
+    unmounted.current = false;
+    return () => {
+      unmounted.current = true;
+      for (const request of requests.current.values()) request.abort();
+      requests.current.clear();
+      inflight.current.clear();
+    };
+  }, []);
+
+  // Streaming can legitimately replace an initial declaration (for example a template offer).
+  // Synchronise by name so a renderer that first saw `data: []` can still resolve the reconciled
+  // document instead of keeping an empty reducer state forever.
+  const declarationKey = (page.data ?? []).map((d) => d.name).join("\u001f");
+  useEffect(() => {
+    const declared = new Set((page.data ?? []).map((d) => d.name));
+    for (const [name, request] of requests.current) {
+      if (!declared.has(name)) request.abort();
+    }
+    dispatch({ type: "sync", datasets: page.data ?? [] });
+  }, [declarationKey]);
+
+  /** Keep `concurrency` datasets in flight, always the earliest idle one in plan order. */
+  const pump = useCallback(() => {
+    for (const name of order) {
+      if (unmounted.current) return;
+      if (inflight.current.size >= concurrency) return;
+      // `inflight` is the authority, not `status`. `dispatch` is batched, so two pump calls in one
+      // tick both still see `status: "idle"` and both fire the request — the resolver gets asked
+      // the same question twice, and the second answer overwrites the first. The ref updates
+      // synchronously; the reducer does not.
+      if (inflight.current.has(name)) continue;
+      if (settled.current.get(name) === generation.current) continue;
+      if (latest.current.datasets[name]?.status !== "idle") continue;
+
+      const myGeneration = generation.current;
+      inflight.current.add(name);
+      dispatch({ type: "loading", name });
+
+      const request = startDatasetResolve(
+        resolve,
+        { page: page.id, dataset: name, params: latest.current.params, pageDoc: page },
+        { timeoutMs },
+      );
+      requests.current.set(name, request);
+
+      request.promise
+        .then((out) => {
+          // A result from before a `set_param` describes a page the user has moved on from.
+          if (unmounted.current || generation.current !== myGeneration) return;
+          settled.current.set(name, myGeneration);
+          dispatch({ type: "ready", name, rows: out?.rows ?? [], columns: out?.columns?.length ? out.columns : columnsFor(name) });
+        })
+        .catch((error) => {
+          if (unmounted.current || generation.current !== myGeneration) return;
+          // A dataset that failed is an ERROR, never an empty result set. "No matching rows" and
+          // "I could not ask the question" must never look the same (DECISIONS R9).
+          settled.current.set(name, myGeneration);
+          dispatch({ type: "error", name, error: error?.message ?? String(error), columns: columnsFor(name) });
+        })
+        .finally(() => {
+          if (requests.current.get(name) === request) requests.current.delete(name);
+          inflight.current.delete(name);
+          if (!unmounted.current) queueMicrotask(() => pumpRef.current());
+        });
+    }
+  }, [page, resolve, order, concurrency, columnsFor, timeoutMs]);
+
+  const pumpRef = useRef(pump);
+  pumpRef.current = pump;
+
+  // Re-run after every render: an `invalidate` returns datasets to `idle` and this picks them up.
+  useEffect(() => { pump(); });
+
+  const setParam = useCallback((name, value) => {
+    generation.current += 1;
+    dispatch({ type: "params", params: { [name]: value } });
+    const affected = [...paramDeps.entries()].filter(([, deps]) => deps.has(name)).map(([ds]) => ds);
+    if (affected.length) {
+      for (const ds of affected) requests.current.get(ds)?.abort();
+      dispatch({ type: "invalidate", names: affected });
+    }
+  }, [paramDeps]);
+
+  const refresh = useCallback((names) => {
+    generation.current += 1;
+    const all = (page.data ?? []).map((d) => d.name);
+    const targets = names === "all" || !names ? all : names;
+    for (const ds of targets) requests.current.get(ds)?.abort();
+    dispatch({ type: "invalidate", names: targets });
+  }, [page]);
+
+  const dataset = useCallback((name) => state.datasets[name], [state.datasets]);
+
+  /** A block can paint when every dataset it reads is `ready`. */
+  const blockReady = useCallback(
+    (block) => [...collectDatasets(block)].every((n) => state.datasets[n]?.status === "ready"),
+    [state.datasets],
+  );
+  const blockError = useCallback(
+    (block) => [...collectDatasets(block)].map((n) => state.datasets[n]).find((d) => d?.status === "error")?.error ?? null,
+    [state.datasets],
+  );
+  const blockStale = useCallback(
+    (block) => [...collectDatasets(block)].some((n) => state.datasets[n]?.stale && state.datasets[n]?.status !== "ready"),
+    [state.datasets],
+  );
+
+  return { datasets: state.datasets, params: state.params, dataset, setParam, refresh, blockReady, blockError, blockStale, order };
+}
+
+
+/**
+ * Whether one block has SETTLED — nothing about it is still on its way to the screen.
+ *
+ *   - a block that reads no data settled the moment it painted;
+ *   - an errored dataset is terminal (nothing here retries unbidden), so its block has settled
+ *     INTO its error state — a gate that waited for it to become "ready" would wait forever;
+ *   - otherwise the block settles when its data is ready AND the reveal dwell has released it —
+ *     rows in memory whose tile still wears its skeleton have not been revealed to anyone.
+ *
+ * This is the pure heart of `<UIResponsePage onAllRevealed>`: the page has revealed when every walked
+ * block satisfies this.
+ */
+export const blockSettled = ({ needsData, error, dataReady, held }) =>
+  !needsData || Boolean(error) || (dataReady && !held);
+
+/**
+ * The parameters a page presented in an overlay is resolved with (DECISIONS A13, P8).
+ *
+ * The action supplies what the user chose — the row they clicked. The HOST supplies identity:
+ * `source: "session"` params like `label_id` or `current_user_id`, which P8 says are "the ONLY way
+ * user identity may enter a page", and which a saved document therefore can never carry.
+ *
+ * So a `navigate` can never name them, and merging them in is structurally the renderer's job. Miss
+ * it and every session-scoped drawer fails every dataset with `parameter "label_id" is required` —
+ * which is the resolver correctly refusing to guess who is asking.
+ *
+ * The action's own params win on collision: the row the user clicked is more specific than the
+ * session they clicked it in.
+ */
+export const overlayParams = (sessionParams, actionParams) => ({ ...sessionParams, ...actionParams });