@uiresponse/renderer-react 0.1.0

package/src/blocks/containers.jsx

@@ -0,0 +1,150 @@
+/**
+ * The three containers: `section`, `card`, `tabs`.
+ *
+ * Containers own ARRANGEMENT; blocks own EMPHASIS. There is no layout tree to keep in sync with the
+ * block tree, and no per-block position or size — structure IS layout (DECISIONS P1). A section of
+ * three cards arranged `grid` tells a web renderer to draw columns, an e-ink renderer to stack, and
+ * a voice renderer to say "three cards". This file is the web renderer's half of that bargain.
+ */
+import React, { useState } from "react";
+import { UIResponseContext, useUIResponse, scopeFor } from "./context.js";
+import { runWithConfirm } from "../core/actions.js";
+import { isEditorialSection } from "../core/record.js";
+
+const arrangementOf = (block) => block.layout?.arrangement ?? "stack";
+const densityOf = (block) => block.layout?.density ?? undefined;
+
+/** `intent.priority` as an ordering tiebreak among siblings of equal emphasis. */
+const PRIORITY = { primary: 0, supporting: 1, ambient: 2 };
+const EMPHASIS = { hero: 0, primary: 1, normal: 2, subtle: 3 };
+
+/**
+ * Sibling order. The DOCUMENT order is authoritative — a page's block order is a claim the author
+ * made, and reordering it would rewrite the page. `intent.priority` only breaks ties BETWEEN BLOCKS
+ * THE AUTHOR GAVE THE SAME EMPHASIS, and only inside `grid`/`row`/`flow` arrangements, where the
+ * blocks are peers scanned together rather than read in sequence. A `stack` is a reading order and
+ * is never reordered.
+ */
+export function orderSiblings(children, arrangement) {
+  if (arrangement === "stack") return children;
+  return children
+    .map((block, index) => ({ block, index }))
+    .sort((a, b) => {
+      const ea = EMPHASIS[a.block.emphasis ?? "normal"], eb = EMPHASIS[b.block.emphasis ?? "normal"];
+      if (ea !== eb) return ea - eb;
+      const pa = PRIORITY[a.block.intent?.priority] ?? 1, pb = PRIORITY[b.block.intent?.priority] ?? 1;
+      if (pa !== pb) return pa - pb;
+      return a.index - b.index;
+    })
+    .map((x) => x.block);
+}
+
+export function Arrange({ block, children }) {
+  return (
+    <div className="uir-arrange" data-arrangement={arrangementOf(block)}>
+      {children}
+    </div>
+  );
+}
+
+/**
+ * A section is a LABELLED GROUPING of tiles, not a framed region.
+ *
+ * It draws no border, no rule and no rail. Its title is a small quiet label sitting above its tiles,
+ * and the grouping is legible from the gap around it — which is how grouping works on a canvas.
+ * A framed region inside a page is a page inside a page, and the tiles were already the objects.
+ *
+ * THE EXCEPTION IS THE EDITORIAL SECTION, and it is inferred rather than declared. A section whose
+ * title is followed by a `text` block is a magazine section: a headline, then one sentence saying
+ * what this run of things has in common, then the things. That composition was always expressible —
+ * `section.title` plus a `text` child is the only way OBL can say it — and the renderer drew both
+ * parts identically, a 12px grey label above a paragraph of body copy.
+ *
+ * So the pattern is READ, not added: no prop, no new block, nothing for a voice renderer to fail to
+ * honour (it already reads the title, then the sentence, then the things). The document is unchanged;
+ * only its treatment knows what it is looking at. The text block keeps its own `.uir-block` wrapper
+ * and its own `visible_when`, because it is still a block — it is styled as a standfirst by POSITION,
+ * not by being taken apart.
+ */
+export function SectionBlock({ block, renderChild, hideTitle }) {
+  const uir = useUIResponse();
+  const arrangement = arrangementOf(block);
+  const density = densityOf(block) ?? uir.density;
+  const editorial = isEditorialSection(block) && !hideTitle;
+  return (
+    <section className="uir-section" data-density={densityOf(block)} data-editorial={editorial || undefined}>
+      {/* Inside `tabs`, the section's title IS the tab label. Drawing it again would say the same
+          word twice, six pixels apart. */}
+      {block.title && !hideTitle && <h2 className="uir-section__label">{block.title}</h2>}
+      <UIResponseContext.Provider value={{ ...uir, density }}>
+        <Arrange block={block}>
+          {/* An editorial section's intro sentence is its standfirst and belongs above the things it
+              introduces. `orderSiblings` would happily promote a `hero` list above it on emphasis. */}
+          {orderSiblings(block.children ?? [], editorial ? "stack" : arrangement).map(renderChild)}
+        </Arrange>
+      </UIResponseContext.Provider>
+    </section>
+  );
+}
+
+export function CardBlock({ block, renderChild, emphasis }) {
+  const uir = useUIResponse();
+  const clickable = Boolean(block.on_click);
+  return (
+    <div
+      className={`uir-card${clickable ? " uir-card--clickable" : ""}`}
+      data-emphasis={emphasis}
+      onClick={clickable ? () => runWithConfirm(block.on_click, { ...uir.actionCtx, scope: scopeFor(uir) }) : undefined}
+    >
+      {block.title && <h3 className="uir-card__title">{block.title}</h3>}
+      {/* A card IS a tile. Its children are the card's contents, so they shed their own tile chrome
+          (see `.uir-card .uir-block[data-tile]` in uir.css) — a tile inside a tile is a box inside
+          a box, which is the exact thing this composition model exists to stop. */}
+      <div className="uir-arrange" data-arrangement="grid">
+        {orderSiblings(block.children ?? [], "grid").map(renderChild)}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Tabs are alternative views of one subject, one at a time. Their children are SECTIONS, and each
+ * section's `title` is its tab label (DECISIONS P3) — there is no anonymous tab container.
+ */
+export function TabsBlock({ block, renderChild }) {
+  const [active, setActive] = useState(0);
+  const sections = block.children ?? [];
+
+  return (
+    <div className="uir-tabs">
+      <div className="uir-tabs__list" role="tablist">
+        {sections.map((section, i) => (
+          <button
+            key={section.id}
+            type="button"
+            role="tab"
+            className="uir-tab"
+            aria-selected={i === active}
+            aria-controls={`panel-${section.id}`}
+            onClick={() => setActive(i)}
+          >
+            {section.title}
+          </button>
+        ))}
+      </div>
+      {sections.map((section, i) => (
+        <div
+          key={section.id}
+          id={`panel-${section.id}`}
+          role="tabpanel"
+          // The inactive panel is HIDDEN, not unmounted. Unmounting would restart its datasets'
+          // progressive load every time the user flicked between tabs, and a tab is a view of data
+          // the page already asked for.
+          hidden={i !== active}
+        >
+          {renderChild(section, i)}
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/blocks/content.jsx

@@ -0,0 +1,292 @@
+/**
+ * The content and interactive leaves: `text`, `media`, `input`, `button`.
+ */
+import React, { useEffect, useRef, useState } from "react";
+import { useUIResponse, scopeFor } from "./context.js";
+import { ActionButton, BlockError, BlurImage } from "./primitives.jsx";
+import { resolveValue, isBinding, boundColumn } from "../core/value.js";
+import { runWithConfirm, runInputAction } from "../core/actions.js";
+import { thumbNameFor } from "../core/record.js";
+import { formatAudioTime } from "../core/presentation.js";
+
+// ───────────────────────────────────────────────────────────────────────────────
+// text — prose the page author wrote. PLAIN TEXT: no markdown, no HTML.
+// ───────────────────────────────────────────────────────────────────────────────
+export function TextBlock({ block, emphasis }) {
+  // Rendered as a text node, never `dangerouslySetInnerHTML`. `body` is plain text by schema
+  // (Principle 8: microsyntax in a string is invisible to JSON Schema), and a renderer that parsed
+  // markdown here would quietly make it a markup surface — reachable from a chat message.
+  return <p className="uir-text" data-emphasis={emphasis}>{block.body}</p>;
+}
+
+// ───────────────────────────────────────────────────────────────────────────────
+// media — something to look at or listen to
+// ───────────────────────────────────────────────────────────────────────────────
+
+/**
+ * THE PROVIDER ALLOWLIST (DECISIONS MED4, MED5).
+ *
+ * A page never carries a frame URL. It carries a provider from a closed enum and an opaque id, and
+ * THIS TABLE — code, reviewed, versioned — is the only thing that turns those into an origin. That
+ * inversion is what closes the three attack classes A2UI's architect names on stage
+ * (`docs/research/video-study-UsMDkEsR-ok-2026-07-09.md`):
+ *
+ *   · exfiltration through a rendered resource the agent did not mean to fetch — a page cannot name
+ *     an origin, so there is nowhere to exfiltrate TO;
+ *   · a hidden form inside a click target — the page supplies no markup, only an id;
+ *   · supply chain — the set of reachable origins is fixed by the spec, not by generation.
+ *
+ * `content_id` is already `^[A-Za-z0-9_-]{1,128}$` in the schema, so it cannot spell a scheme, a
+ * path traversal or markup. We encode it anyway. A validator that ran yesterday is not a guarantee
+ * about this render, and the same reasoning puts A8's scheme check back in `runAction`.
+ *
+ * An UNRECOGNISED provider — one a later minor added — draws NOTHING and reports itself. Guessing an
+ * origin from a name is the one thing this table exists to make impossible.
+ */
+const EMBED_PROVIDERS = {
+  youtube: { origin: "https://www.youtube-nocookie.com", url: (id) => `https://www.youtube-nocookie.com/embed/${id}`, open: (id) => `https://www.youtube.com/watch?v=${id}`, domain: "youtube.com", name: "YouTube" },
+  tiktok: { origin: "https://www.tiktok.com", url: (id) => `https://www.tiktok.com/embed/v2/${id}`, open: (id) => `https://www.tiktok.com/player/v1/${id}`, domain: "tiktok.com", name: "TikTok" },
+  // An opaque id cannot say track-vs-playlist-vs-episode, so `spotify` resolves to the default
+  // surface. Widening that is a `content_type` prop or more enum members; encoding it in the id
+  // would be a microsyntax (B2) and would reopen the path surface the pattern closes.
+  spotify: { origin: "https://open.spotify.com", url: (id) => `https://open.spotify.com/embed/track/${id}`, open: (id) => `https://open.spotify.com/track/${id}`, domain: "open.spotify.com", name: "Spotify" },
+};
+
+/**
+ * `sandbox` without `allow-same-origin` would break every provider's player (they need their own
+ * storage and their own origin). Granting it is safe here precisely because the frame is CROSS-origin:
+ * "same origin" means the provider's, never ours. What is withheld is what matters — no `allow-forms`,
+ * no `allow-popups`, no `allow-top-navigation`: a frame from an allowlisted origin still cannot
+ * navigate the page that hosts it or put a form in front of the user.
+ */
+const EMBED_SANDBOX = "allow-scripts allow-same-origin allow-presentation";
+
+function ProviderEmbed({ block }) {
+  const spec = EMBED_PROVIDERS[block.provider];
+  if (!spec) {
+    return <BlockError message={`This renderer does not know the media provider \`${block.provider}\`. It will not guess an origin.`} />;
+  }
+  const src = spec.url(encodeURIComponent(block.content_id));
+  const external = spec.open(encodeURIComponent(block.content_id));
+  // No `aspect` means landscape. That is a renderer default over an absent optional prop, not an
+  // inference from one — a page that says nothing about shape gets the shape most video has.
+  const aspect = block.aspect ?? "16:9";
+
+  return (
+    <figure className="uir-media">
+      <div className="uir-media__frame" data-aspect={aspect} style={{ aspectRatio: aspect.replace(":", " / ") }}>
+        <iframe
+          className="uir-media__embed"
+          src={src}
+          title={block.alt}
+          sandbox={EMBED_SANDBOX}
+          referrerPolicy="no-referrer"
+          allow="encrypted-media; picture-in-picture; clipboard-write"
+          allowFullScreen
+          loading="lazy"
+        />
+      </div>
+      {/* `alt` is required on video and embed: the content lives at an origin this renderer cannot
+          inspect, so the page is the only thing that can describe it. */}
+      <figcaption className="uir-embed-meta">
+        <span className="uir-embed-meta__icon" aria-hidden="true">{spec.name[0]}</span>
+        <span className="uir-embed-meta__copy">
+          <strong>{block.caption ?? block.alt}</strong>
+          <span>{spec.domain}</span>
+        </span>
+        <a href={external} target="_blank" rel="noreferrer">Open <span aria-hidden="true">↗</span></a>
+      </figcaption>
+    </figure>
+  );
+}
+
+function AudioPlayer({ src, title }) {
+  const audio = useRef(null);
+  const [playing, setPlaying] = useState(false);
+  const [current, setCurrent] = useState(0);
+  const [duration, setDuration] = useState(0);
+  useEffect(() => { setPlaying(false); setCurrent(0); setDuration(0); }, [src]);
+  const toggle = async () => {
+    if (!audio.current) return;
+    try {
+      if (audio.current.paused) await audio.current.play(); else audio.current.pause();
+    } catch {
+      setPlaying(false);
+    }
+  };
+  const pct = duration > 0 ? Math.min(100, (current / duration) * 100) : 0;
+  return (
+    <div className="uir-audio">
+      <audio ref={audio} src={src} preload="metadata" onPlay={() => setPlaying(true)} onPause={() => setPlaying(false)}
+        onEnded={() => setPlaying(false)} onTimeUpdate={(event) => setCurrent(event.currentTarget.currentTime)}
+        onLoadedMetadata={(event) => setDuration(event.currentTarget.duration)} />
+      <button type="button" onClick={toggle} aria-label={playing ? `Pause ${title}` : `Play ${title}`}>
+        <span aria-hidden="true">{playing ? "Ⅱ" : "▶"}</span>
+      </button>
+      <div className="uir-audio__body">
+        <div className="uir-audio__line"><strong title={title}>{title}</strong><span>{formatAudioTime(current)} / {formatAudioTime(duration)}</span></div>
+        <div className="uir-audio__track"><span style={{ width: `${pct}%` }} /></div>
+      </div>
+    </div>
+  );
+}
+
+export function MediaBlock({ block }) {
+  const uir = useUIResponse();
+  const scope = scopeFor(uir, uir.row);
+
+  if (block.kind === "video" || block.kind === "embed") return <ProviderEmbed block={block} />;
+
+  const src = resolveValue(block.src, scope);
+
+  // A bound `src` is only known at render time, so the literal's schema-level `^https?://` check
+  // cannot have run on it. Check it here, at the point of use (VERSIONING §9, media.src).
+  if (typeof src !== "string" || !/^https?:\/\//i.test(src)) {
+    return <div className="uir-error" role="alert"><span className="uir-error__label">Refused media source</span>Only absolute http(s) URLs may be rendered.</div>;
+  }
+
+  if (block.kind === "audio") {
+    return (
+      <figure className="uir-media">
+        <AudioPlayer src={src} title={block.caption ?? "Audio"} />
+      </figure>
+    );
+  }
+  return (
+    <figure className="uir-media">
+      {/* `alt` is required on images by the schema: accessibility is semantics, and it is what a
+          voice renderer SAYS. */}
+      <BlurImage className="uir-media__image" src={src} thumb={thumbSrc(block.src, scope)} alt={block.alt ?? ""} />
+      {block.caption && <figcaption className="uir-media__caption">{block.caption}</figcaption>}
+    </figure>
+  );
+}
+
+/**
+ * The blur-up proxy for a BOUND `src`, or null.
+ *
+ * `media.src` is a binding at a named field of a named dataset. Its proxy is the SAME binding at the
+ * conventional sibling field (`artwork_url` → `artwork_thumb_url`, see `core/record.js`) — same
+ * dataset, same row selector, so a hero cover picked with `row: "first"` gets the first row's
+ * thumbnail and never the wrong record's. If the dataset never declared the sibling, there is no
+ * proxy and the image fades in from nothing.
+ *
+ * A literal `src` has no dataset to ask, and so has no proxy. That is correct: a URL written into a
+ * document is one URL, and inventing a second by string surgery would be a request for a file that
+ * nobody said exists.
+ */
+function thumbSrc(srcSpec, scope) {
+  const bind = srcSpec?.$bind;
+  if (!bind?.dataset || !bind.field) return null;
+  const want = thumbNameFor(bind.field);
+  const declared = scope.dataset(bind.dataset)?.columns ?? [];
+  if (!declared.some((c) => c?.name === want)) return null;
+  try {
+    const v = resolveValue({ $bind: { ...bind, field: want } }, scope);
+    return typeof v === "string" && v ? v : null;
+  } catch {
+    return null; // a proxy that will not resolve is simply absent; the picture is not
+  }
+}
+
+// ───────────────────────────────────────────────────────────────────────────────
+// input — the way a page listens. ONE block, types are props.
+// ───────────────────────────────────────────────────────────────────────────────
+export function InputBlock({ block }) {
+  const uir = useUIResponse();
+  const scope = scopeFor(uir);
+
+  // An input's state belongs to a param or to nobody. `value` names the param it reflects; failing
+  // that, the param its `on_change` writes.
+  const paramName = block.value?.$param ?? (block.on_change?.type === "set_param" ? block.on_change.param : null);
+  const current = paramName ? uir.params[paramName] : undefined;
+
+  const ctx = { ...uir.actionCtx, scope: scopeFor(uir) };
+
+  /**
+   * `widgetValue` is what `{"$self": true}` resolves to, and it is what each `input_type` promises
+   * to write (binding.schema.json#selfRef): a select writes its chosen option's value field, a
+   * toggle a boolean, a text field its string, a date its date. `row` is passed only by a select,
+   * because only a select has one — and `row: null` is the CLEARED select, which `runInputAction`
+   * turns into `set_param(null)` for the older row-binding spelling.
+   */
+  const fire = ({ row, widgetValue }) => runInputAction(block.on_change, ctx, { row, widgetValue });
+
+  if (block.input_type === "select") {
+    const bind = block.options?.$bind;
+    const ds = bind ? uir.dataset(bind.dataset) : null;
+    const rows = ds?.rows ?? [];
+    const labelField = block.option_label_field;
+    const valueField = block.option_value_field ?? labelField;
+
+    return (
+      <div className="uir-field">
+        <span className="uir-eyebrow">{block.label}</span>
+        <div className="uir-select-row">
+          <select
+            aria-label={block.label}
+            className="uir-select"
+            value={current ?? ""}
+            onChange={(e) => {
+              const picked = rows.find((r) => String(r[valueField]) === e.target.value);
+              // The empty option CLEARS the param. `set_param` to null is how "no filter" is spelled,
+              // and a query predicate marked `optional: true` then drops out entirely (R4).
+              if (!picked) { fire({ row: null, widgetValue: null }); return; }
+              fire({ row: picked, widgetValue: picked[valueField] ?? null });
+            }}
+          >
+            <option value="">All</option>
+            {rows.map((row, i) => (
+              <option key={i} value={String(row[valueField])}>{row[labelField]}</option>
+            ))}
+          </select>
+          {current !== null && current !== undefined && current !== "" && (
+            <button type="button" className="uir-select-clear" onClick={() => fire({ row: null, widgetValue: null })}>Clear</button>
+          )}
+        </div>
+      </div>
+    );
+  }
+
+  if (block.input_type === "toggle") {
+    return (
+      <div className="uir-toggle">
+        <span>{block.label}</span>
+        <button type="button" role="switch" aria-checked={Boolean(current)} aria-label={block.label}
+          onClick={() => fire({ widgetValue: !Boolean(current) })}><span aria-hidden="true" /></button>
+      </div>
+    );
+  }
+
+  return (
+    <label className="uir-field">
+      <span className="uir-eyebrow">{block.label}</span>
+      <input
+        className="uir-input"
+        type={block.input_type === "date" ? "date" : "text"}
+        placeholder={block.placeholder}
+        value={current ?? ""}
+        onChange={(e) => fire({ widgetValue: e.target.value })}
+      />
+    </label>
+  );
+}
+
+// ───────────────────────────────────────────────────────────────────────────────
+// button — a verb with a border. Its label is the ACTION's label: one source of truth.
+// ───────────────────────────────────────────────────────────────────────────────
+export function ButtonBlock({ block, emphasis }) {
+  const uir = useUIResponse();
+  return (
+    <div>
+      <ActionButton
+        action={block.on_click}
+        ctx={{ ...uir.actionCtx, scope: scopeFor(uir) }}
+        variant={emphasis === "hero" || emphasis === "primary" ? "solid" : "ghost"}
+        fallbackLabel={block.on_click?.type}
+      />
+    </div>
+  );
+}
+
+export { isBinding, boundColumn };

package/src/blocks/context.js

@@ -0,0 +1,27 @@
+import { createContext, useContext } from "react";
+
+/**
+ * Everything a block needs and nothing it does not. Note what is ABSENT: no connector, no query, no
+ * credential, no fetch. A block cannot reach data except through `dataset(name)`, which holds rows
+ * the resolver already returned. Principle 4, enforced by the shape of this object.
+ */
+export const UIResponseContext = createContext(null);
+
+export function useUIResponse() {
+  const ctx = useContext(UIResponseContext);
+  if (!ctx) throw new Error("OBL blocks must render inside <UIResponsePage>.");
+  return ctx;
+}
+
+/**
+ * The binding scope for a block: optionally inside a repeating element's `row`, and optionally
+ * carrying the value of the control that fired the action (`self`).
+ *
+ * `self` is left OFF unless a control supplied one — `{"$self": true}` then throws rather than
+ * resolving to `undefined`, which is what tells us a page reached the renderer unvalidated.
+ */
+export function scopeFor(uir, row, self) {
+  const scope = { dataset: uir.dataset, params: uir.params, now: uir.now, row };
+  if (self !== undefined) scope.self = self;
+  return scope;
+}