@uiresponse/renderer-react 0.1.0

package/src/blocks/primitives.jsx

@@ -0,0 +1,290 @@
+/**
+ * The three primitives every block is built from: a rendered VALUE, an ABSENCE, and a SKELETON.
+ *
+ * They exist once so that `format` and `empty` are applied in exactly one place. A `table` cell, a
+ * `metric` and a `detail` field must render `null` identically — the moment two of them disagree,
+ * the page is lying in one of them.
+ */
+import React, { useEffect, useId, useRef, useState } from "react";
+import { formatValue, isNumericFormat } from "../core/format.js";
+import { emptyRender, isEmptyValue } from "../core/empty.js";
+import { runWithConfirm, actionGate, actionLabel } from "../core/actions.js";
+import { initialsFor, isDestructiveAction } from "../core/presentation.js";
+
+/**
+ * AN IMAGE THAT ARRIVES, rather than one that is painted onto the page a band at a time.
+ *
+ * A browser given a 400KB JPEG and a box to put it in draws the JPEG top-down as its bytes land. On a
+ * shelf of twelve record sleeves that is twelve pictures wiping themselves in from above, and it is
+ * the ugliest thing on the page — it reads as damage, not as loading.
+ *
+ * ONE ELEMENT DOES ALL OF IT. The low-resolution proxy is the `<img>`'s own BACKGROUND, and the full
+ * image is its content. Before the content decodes, the element shows its background; a CSS `filter`
+ * blurs the element, so the moment the full image does appear it appears already blurred, in
+ * register, and sharpens as the filter lifts. That is a cross-fade with nothing to cross-fade — no
+ * second element, no absolute positioning, no z-index, and it therefore drops unchanged into the
+ * sleeve, the hero card and the table cell, each of which sizes its image differently.
+ *
+ * Nothing is preloaded. A `new Image()` warm-up would defeat `loading="lazy"` and fetch all twelve
+ * covers of a rail the moment the page painted, which is the opposite of the thing being fixed.
+ *
+ * WITHOUT A PROXY there is nothing to show, so nothing is shown: the image is transparent until it
+ * has loaded, then fades in whole. That is the universal fallback, and it is why this component is
+ * used even where no connector supplies a thumbnail. Painting nothing is not slower than painting a
+ * third of a photograph; it only looks slower to whoever wrote the loading code.
+ *
+ * `onError` settles the state as well as `onLoad`. A dead URL must not leave the page holding its
+ * breath at `opacity: 0` forever — settled, it draws the browser's own broken-image treatment, over
+ * the thumbnail if there was one. Both are honest; an invisible box is not.
+ */
+const cssUrl = (u) => (typeof u === "string" && /^https?:\/\/[^"'()\s\\]+$/i.test(u) ? `url("${u}")` : null);
+
+export function BlurImage({ src, thumb, alt = "", className, ...rest }) {
+  const ref = useRef(null);
+  const [loaded, setLoaded] = useState(false);
+
+  // A new src is a new picture, and a new picture has not loaded. A picture already in the browser's
+  // cache, though, fires `load` before React has attached a handler to it — so ask the element.
+  useEffect(() => {
+    const img = ref.current;
+    setLoaded(Boolean(img?.complete && img.naturalWidth > 0));
+  }, [src]);
+
+  const proxy = cssUrl(thumb);
+  return (
+    <img
+      {...rest}
+      ref={ref}
+      className={["uir-img", className].filter(Boolean).join(" ")}
+      src={src}
+      alt={alt}
+      loading="lazy"
+      decoding="async"
+      style={proxy ? { ...rest.style, backgroundImage: proxy } : rest.style}
+      data-blurup={proxy ? "thumb" : "none"}
+      data-loaded={loaded || undefined}
+      onLoad={() => setLoaded(true)}
+      onError={() => setLoaded(true)}
+    />
+  );
+}
+
+/**
+ * An absent value, drawn so it cannot be mistaken for a small one. `empty.show: "dash"` is OBL's
+ * default because "rendering an unfiled royalty as £0.00 is a lie the page tells confidently."
+ */
+export function Absent({ policy }) {
+  const { kind, text } = emptyRender(policy);
+  if (kind === "hide" || kind === "blank") return null; // `hide` is handled by the block; here it draws nothing
+  if (kind === "zero") return <span className="uir-absent uir-absent--zero">0</span>;
+  if (kind === "text") return <span className="uir-absent uir-absent--text" title="No value recorded">{text}</span>;
+  return (
+    <span className="uir-absent uir-absent--dash" aria-label="No value recorded" title="No value recorded">
+      —
+    </span>
+  );
+}
+
+/**
+ * One resolved value, formatted per its binding's `format`, and falling back to its COLUMN's type
+ * when the page stated none — a currency column drawn without a format is still money.
+ *
+ * A column whose declared `role` is `image` is a picture, not a URL. `role` is the dataset stating
+ * what a column MEANS as opposed to what it stores (DECISIONS D7), and this is the renderer taking
+ * it at its word. The scheme is checked at the point of use: a bound value is only known at render
+ * time, so the schema's `^https?://` never ran on it.
+ */
+export function Value({ value, format, empty, column, now, thumb, spec }) {
+  if (isEmptyValue(value)) return <Absent policy={empty} />;
+
+  if (column?.role === "image" && typeof value === "string") {
+    if (!/^https?:\/\//i.test(value)) return <Absent policy={empty} />;
+    return <BlurImage className="uir-thumb" src={value} thumb={thumb} alt="" />;
+  }
+
+  const text = formatValue(value, format, { column, now });
+
+  // `columnSpec.as: "badge"` — a status stated as a status, inside a row where the `badge` block
+  // cannot go (BLK12). Absence is still absence: an empty cell draws its `empty` policy above,
+  // never an empty chip, because a badge of nothing is a claim that nothing is a status.
+  if (spec?.as === "badge") {
+    const tone = spec.tone ?? spec.tone_map?.find((e) => e.value === value)?.tone ?? "neutral";
+    return <span className="uir-badge uir-badge--cell" data-tone={tone}>{text}</span>;
+  }
+
+  return <>{text}</>;
+}
+
+export const numericish = (format, column) => isNumericFormat(format, column);
+
+/** A semantic name with no image still gets the sheet's quiet, deterministic identity marker. */
+export function InitialsChip({ value, shape = "round" }) {
+  return <span className="uir-initials" data-shape={shape} aria-hidden="true">{initialsFor(value)}</span>;
+}
+
+const skeletonTitleCase = (name) => String(name).replace(/_/g, " ").replace(/^./, (c) => c.toUpperCase());
+
+/**
+ * The frame every block paints on the first frame, before any row exists.
+ *
+ * A block's DOCUMENT arrives seconds before its ROWS do, and everything the document says is already
+ * knowable: what this tile is called, what the metric measures, which columns the table will have.
+ * Drawing three grey bars instead throws that away and makes a generation that is visibly working
+ * look like a generation that is hung — which is exactly what Dan was watching.
+ *
+ * So the skeleton shimmers only where DATA goes. Everything the model has already written is set in
+ * real type, at its real size, in its final position, and does not move when the rows land.
+ */
+export function Skeleton({ variant = "bars", block }) {
+  const heading = block?.title;
+  const columns = block?.type === "table" ? block.columns : null;
+
+  // A metric knows its own label and unit. Only the number is pending.
+  if (variant === "metric") {
+    return (
+      <div className="uir-skeleton">
+        {block?.label ? <span className="uir-skeleton__label">{block.label}</span> : <div className="uir-skeleton__bar" />}
+        <div className="uir-skeleton__value" />
+      </div>
+    );
+  }
+  if (variant === "value") {
+    return (
+      <div className="uir-skeleton">
+        {block?.label ? <span className="uir-skeleton__label">{block.label}</span> : <div className="uir-skeleton__bar" />}
+        <div className="uir-skeleton__bar uir-skeleton__bar--narrow" />
+      </div>
+    );
+  }
+  return (
+    <div className="uir-skeleton">
+      {heading ? <h3 className="uir-skeleton__heading">{heading}</h3> : <div className="uir-skeleton__bar" />}
+      {columns?.length ? (
+        // The column heads are the table's shape. They are in the document, so they are on the screen.
+        <div className="uir-skeleton__cols">
+          {columns.map((c) => (
+            <span key={c.field}>{c.label ?? skeletonTitleCase(c.field)}</span>
+          ))}
+        </div>
+      ) : null}
+      <div className="uir-skeleton__value" style={{ height: 56, width: "100%" }} />
+    </div>
+  );
+}
+
+export const LoadingRule = () => <div className="uir-loading-rule" role="progressbar" aria-label="Resolving data" />;
+
+/**
+ * A dataset that failed is an error, never an empty result set (DECISIONS R9).
+ *
+ * But it is one TILE that failed, not the page. It says so at the tile's own scale: a small mark, a
+ * short label, and the reason in one line that may be read in full on hover. A full-width red
+ * paragraph makes one unresolvable dataset look like an outage — dishonest in the other direction.
+ */
+export function BlockError({ message, onRetry }) {
+  // The design sets the offending identifier in mono inside the sentence. Resolver messages already
+  // name it in backticks, so we render those spans as code rather than re-parsing the message.
+  const parts = String(message).split(/`([^`]+)`/g);
+
+  return (
+    <div className="uir-error" role="alert">
+      <span className="uir-error__mark" aria-hidden="true">!</span>
+      <span className="uir-error__body">
+        <span className="uir-error__label">Could not resolve</span>
+        <span className="uir-error__msg" title={message}>
+          {parts.map((p, i) => (i % 2 ? <code key={i}>{p}</code> : p))}
+        </span>
+        {/* The one action that can help. A dataset that failed can be asked again; the design puts a
+            Retry here, and we can honour it exactly because `refresh` is already a first-class verb. */}
+        {onRetry && (
+          <button type="button" className="uir-error__retry" onClick={onRetry}>Retry</button>
+        )}
+      </span>
+    </div>
+  );
+}
+
+/**
+ * The validation tick (`States — validation`).
+ *
+ * Rendered only when the HOST says the page was validated. The renderer does not validate — Phase 2
+ * runs before it — so a tick it drew on its own initiative would assert a check nobody performed.
+ * A mark that appears whether or not the check ran is a decoration, and this one is a claim.
+ */
+export function ValidationTick() {
+  return (
+    <span className="uir-tick" aria-hidden="true">
+      <svg width="9" height="7" viewBox="0 0 9 7"><polyline points="1,3.5 3.5,6 8,1" /></svg>
+    </span>
+  );
+}
+
+/** The sheet's default confirmation surface. Hosts may still replace it with `UIResponsePage.confirm`. */
+export function ConfirmDialog({ prompt, onResolve }) {
+  const panel = useRef(null);
+  const titleId = useId();
+  useEffect(() => {
+    panel.current?.focus();
+    const onKey = (event) => { if (event.key === "Escape") onResolve(false); };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [onResolve]);
+  return (
+    <div className="uir-confirm" role="dialog" aria-modal="true" aria-labelledby={titleId}>
+      <button className="uir-confirm__scrim" type="button" aria-label="Cancel" onClick={() => onResolve(false)} />
+      <div className="uir-confirm__panel" ref={panel} tabIndex={-1}>
+        <h2 id={titleId}>{prompt.title}</h2>
+        {prompt.body && <p>{prompt.body}</p>}
+        <div className="uir-confirm__actions">
+          <button type="button" className="uir-button uir-button--ghost" onClick={() => onResolve(false)}>Cancel</button>
+          <button type="button" className={`uir-button${prompt.destructive ? " uir-button--confirm" : ""}`} onClick={() => onResolve(true)}>{prompt.confirm_label ?? "Confirm"}</button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * An action, rendered as a button. An action that cannot run is drawn DISABLED wearing its reason —
+ * never omitted (the page said it should be there) and never live (it would lie).
+ *
+ * ONE treatment, two reasons, and they are different kinds of thing (DECISIONS A12). Either this
+ * renderer cannot execute the verb — a fact about the implementation — or the page's `enabled_when`
+ * says the action does not apply to the current data. `actionGate` decides which, and the second is
+ * a teaching affordance rather than a guard: the resolver owns authorization, always.
+ *
+ * The reason gets a unique id per instance. Keying it by verb, as this did, meant every disabled
+ * `mutate` on a page pointed its `aria-describedby` at the first one's reason.
+ */
+export function ActionButton({ action, ctx, variant = "ghost", small = false, fallbackLabel }) {
+  const reasonId = useId();
+  const { disabled, reason } = actionGate(action, ctx);
+  const label = actionLabel(action, fallbackLabel);
+  const effectiveVariant = isDestructiveAction(action) ? "danger" : variant;
+  const className = [
+    "uir-button",
+    effectiveVariant === "ghost" ? "uir-button--ghost" : "",
+    effectiveVariant === "danger" ? "uir-button--danger" : "",
+    small ? "uir-button--small" : "",
+  ].filter(Boolean).join(" ");
+
+  const button = (
+    <button
+      type="button"
+      className={className}
+      disabled={disabled}
+      aria-describedby={disabled ? reasonId : undefined}
+      onClick={(e) => { e.stopPropagation(); runWithConfirm(action, ctx); }}
+    >
+      {label}
+    </button>
+  );
+
+  if (!disabled) return button;
+  return (
+    <span className="uir-disabled-wrap">
+      {button}
+      <span className="uir-reason" role="note" id={reasonId}>{reason}</span>
+    </span>
+  );
+}