@cueplusplus/ui 0.13.0

package/dist/elements/generative/spec.d.ts

@@ -0,0 +1,110 @@
+//#region src/elements/generative/spec.d.ts
+/**
+ * The vocabulary, and the readers that make a model's JSON safe to render.
+ *
+ * Nothing here is a component. This module is the *contract*: the 27 names a
+ * model may emit, and a set of readers that turn an arbitrary value into
+ * something a renderer can hand to React without ever asking whether it is the
+ * shape it was promised. Every reader has the same two properties — it never
+ * throws, and it never widens: a number that arrives as `"3"` is a number, a
+ * number that arrives as `{}` is the fallback, and a size that arrives as
+ * `"enormous"` is the default rung rather than an attribute selector nothing
+ * declares.
+ *
+ * That is the whole defence, and it is deliberately not validation-then-render.
+ * A schema pass would have to walk the spec before the first pixel, which is a
+ * second recursion over an object whose depth an attacker picks; and it would
+ * answer with a boolean, when what a reader wants is a *value*. So the walk
+ * happens once, lazily, inside the render, and every property is read through
+ * one of these.
+ */
+/**
+ * The 27 intrinsics a model may emit, in the seven groups the vocabulary is
+ * published in.
+ *
+ * This list is the closed set. A `$type` outside it is not an error in the
+ * spec's author — a newer model, a newer catalogue, a typo in a tool
+ * description — so it renders the unknown-node notice rather than failing the
+ * message it arrived in.
+ */
+declare const GENERATIVE_TYPES: readonly ["Card", "Row", "Col", "Box", "Spacer", "Divider", "Carousel", "Header", "Text", "Caption", "Markdown", "Fact", "Table", "Chart", "Badge", "Image", "Icon", "Button", "Select", "Input", "DatePicker", "Checkbox", "RadioGroup", "Form", "ListView", "ListViewItem", "Alert"];
+/** One of the 27 names {@link GENERATIVE_TYPES} lists. */
+type GenerativeTypeName = (typeof GENERATIVE_TYPES)[number];
+/** Whether `name` is one of the 27 intrinsics. */
+declare function isGenerativeType(name: string): name is GenerativeTypeName;
+/**
+ * One node of a model-composed spec.
+ *
+ * The two reserved keys carry the `$` upstream gave them so a node's own props
+ * can never collide with them: `$type` names the intrinsic, `$action` is the
+ * identifier a control hands back through {@link GenerativeAction}. Everything
+ * else is `unknown` on purpose — this interface describes what the model was
+ * *asked* for, and the readers below are what the renderer actually trusts.
+ */
+interface GenerativeNode {
+  /** The intrinsic to render: one of {@link GENERATIVE_TYPES}. */
+  $type: string;
+  /** Fired back to the host when a control in this node is used. */
+  $action?: string;
+  /** Nested nodes. One node or a list of them; anything else reads as none. */
+  children?: unknown;
+  /** Everything else the intrinsic documents, unvalidated as it arrives. */
+  [prop: string]: unknown;
+}
+/** What a control hands back when the person using it does something. */
+interface GenerativeAction {
+  /** The `$action` string the model put on the node. */
+  action: string;
+  /** The intrinsic that fired it. */
+  type: GenerativeTypeName;
+  /** The control's own value, where it has one: a field's text, a box's state. */
+  value?: string | boolean;
+  /**
+   * Every named control inside the submitted form, keyed by its `name`.
+   *
+   * Present only for a `Form` submit and for a `Card` with `asForm`, which is
+   * the one moment several controls answer at once.
+   */
+  values?: Record<string, string>;
+}
+/** One `Table` column, once its own shape has been read. */
+interface TableColumn {
+  /** The key a row object is looked up by, and the fallback heading. */
+  key: string;
+  /** The column heading. */
+  label: string;
+  /** Which way the cells sit in the column. */
+  align?: "start" | "center" | "end";
+}
+/** One chart series, once its own shape has been read. */
+interface ChartSeries {
+  /** The name in the legend. */
+  label: string;
+  /** The points, in order. */
+  data: number[];
+}
+/** Why a node could not be rendered as the model asked. */
+type GenerativeFaultKind =
+/** The value in the tree is not an object with a `$type`. */
+"not-a-node" |
+/** `$type` is a name this vocabulary does not publish. */
+"unknown-type" |
+/** A prop the intrinsic requires is absent or unreadable. */
+"missing-prop" |
+/** The tree is nested deeper than the renderer will walk. */
+"too-deep";
+/** One thing the renderer refused to guess at, with where it happened. */
+interface GenerativeFault {
+  /** Which of the four refusals this is. */
+  kind: GenerativeFaultKind;
+  /** The node's position, as a dotted path from the root: `root.children.2`. */
+  path: string;
+  /** The `$type` that was read, where there was one. */
+  type?: string;
+  /** The prop that was missing, for `missing-prop`. */
+  prop?: string;
+  /** One line a person can act on. */
+  message: string;
+}
+//#endregion
+export { ChartSeries, GENERATIVE_TYPES, GenerativeAction, GenerativeFault, GenerativeFaultKind, GenerativeNode, GenerativeTypeName, TableColumn, isGenerativeType };

package/dist/elements/generative/spec.js

@@ -0,0 +1,366 @@
+//#region src/elements/generative/spec.ts
+/**
+* The vocabulary, and the readers that make a model's JSON safe to render.
+*
+* Nothing here is a component. This module is the *contract*: the 27 names a
+* model may emit, and a set of readers that turn an arbitrary value into
+* something a renderer can hand to React without ever asking whether it is the
+* shape it was promised. Every reader has the same two properties — it never
+* throws, and it never widens: a number that arrives as `"3"` is a number, a
+* number that arrives as `{}` is the fallback, and a size that arrives as
+* `"enormous"` is the default rung rather than an attribute selector nothing
+* declares.
+*
+* That is the whole defence, and it is deliberately not validation-then-render.
+* A schema pass would have to walk the spec before the first pixel, which is a
+* second recursion over an object whose depth an attacker picks; and it would
+* answer with a boolean, when what a reader wants is a *value*. So the walk
+* happens once, lazily, inside the render, and every property is read through
+* one of these.
+*/
+/**
+* The 27 intrinsics a model may emit, in the seven groups the vocabulary is
+* published in.
+*
+* This list is the closed set. A `$type` outside it is not an error in the
+* spec's author — a newer model, a newer catalogue, a typo in a tool
+* description — so it renders the unknown-node notice rather than failing the
+* message it arrived in.
+*/
+const GENERATIVE_TYPES = [
+	"Card",
+	"Row",
+	"Col",
+	"Box",
+	"Spacer",
+	"Divider",
+	"Carousel",
+	"Header",
+	"Text",
+	"Caption",
+	"Markdown",
+	"Fact",
+	"Table",
+	"Chart",
+	"Badge",
+	"Image",
+	"Icon",
+	"Button",
+	"Select",
+	"Input",
+	"DatePicker",
+	"Checkbox",
+	"RadioGroup",
+	"Form",
+	"ListView",
+	"ListViewItem",
+	"Alert"
+];
+const KNOWN = new Set(GENERATIVE_TYPES);
+/** Whether `name` is one of the 27 intrinsics. */
+function isGenerativeType(name) {
+	return KNOWN.has(name);
+}
+/** Whether `value` is an object with a string `$type` — the shape of a node. */
+function isNode(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.$type === "string";
+}
+/** A node's `$action`, when it has a non-empty one. */
+function actionOf(node) {
+	const action = node["$action"];
+	return typeof action === "string" && action !== "" ? action : void 0;
+}
+/**
+* A string prop, or `undefined`.
+*
+* Numbers and booleans are accepted and stringified: a model that writes
+* `"value": 42` for a `Fact` meant the characters, and refusing them would
+* blank a cell over a JSON type nobody chose deliberately. Everything else —
+* an object, an array, a null — is absent, because there is no reading of it
+* that is not a guess.
+*/
+function str(node, prop) {
+	const value = node[prop];
+	if (typeof value === "string") return value;
+	if (typeof value === "number" && Number.isFinite(value)) return String(value);
+	if (typeof value === "boolean") return String(value);
+}
+/** A string prop with a default for the absent case. */
+function strOr(node, prop, fallback) {
+	return str(node, prop) ?? fallback;
+}
+/** A boolean prop. Absent, wrong-typed and `false` all read the same. */
+function flag(node, prop) {
+	return node[prop] === true;
+}
+/** A finite number prop, or `undefined`. A numeric string counts. */
+function num(node, prop) {
+	const value = node[prop];
+	if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
+	if (typeof value === "string" && value.trim() !== "") {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : void 0;
+	}
+}
+/**
+* A rung on the 0–8 scale `gap` and `padding` are expressed in, as a string.
+*
+* A string because it is going straight into a `data-aui-gap` attribute, which
+* is what the stylesheet selects on. Out-of-range and fractional values are
+* clamped and rounded rather than dropped: a model that asks for 12 wants the
+* widest gap there is, and a stylesheet that declares eight rungs should give
+* it the eighth rather than nothing.
+*/
+function scale(node, prop) {
+	const value = num(node, prop);
+	if (value === void 0) return void 0;
+	return String(Math.max(0, Math.min(8, Math.round(value))));
+}
+/**
+* An enumerated prop, or `undefined` when it is absent or not on the list.
+*
+* The unlisted case is deliberately `undefined` rather than the default: an
+* attribute that is never written cannot select a rule, so an unknown variant
+* falls back to whatever the element paints with no modifier at all, which is
+* the one value the stylesheet is guaranteed to have.
+*/
+function choice(node, prop, allowed) {
+	const value = node[prop];
+	return typeof value === "string" && allowed.includes(value) ? value : void 0;
+}
+/**
+* A node's children, as a list.
+*
+* One node, a list of nodes, or nothing. A single node is wrapped rather than
+* refused because models write both, and the difference is a JSON habit rather
+* than a meaning. Non-node entries survive the trip so the renderer can show
+* *which* child was malformed instead of silently shortening the list.
+*/
+function childList(node) {
+	const children = node["children"];
+	if (Array.isArray(children)) return children;
+	if (children === void 0 || children === null) return [];
+	return [children];
+}
+/** A prop that should be a list, as one. A non-list reads as empty. */
+function list(node, prop) {
+	const value = node[prop];
+	return Array.isArray(value) ? value : [];
+}
+/** A list of finite numbers, with everything unreadable dropped. */
+function numberList(value) {
+	if (!Array.isArray(value)) return [];
+	return value.map((entry) => typeof entry === "number" ? entry : Number(entry)).filter((entry) => Number.isFinite(entry));
+}
+/**
+* A list of `{ label, value }` options, as `Select` and `RadioGroup` take it.
+*
+* Both the plain-string form (`["Small", "Large"]`) and the object form
+* (`[{ label: "Small", value: "s" }]`) are accepted, because both are what
+* models write. A label is required; a missing value falls back to the label,
+* which is what makes the string form work at all.
+*/
+function optionList(value) {
+	if (!Array.isArray(value)) return [];
+	const options = [];
+	for (const entry of value) {
+		if (typeof entry === "string") {
+			options.push({
+				label: entry,
+				value: entry
+			});
+			continue;
+		}
+		if (typeof entry !== "object" || entry === null) continue;
+		const record = entry;
+		const label = typeof record["label"] === "string" ? record["label"] : typeof record["value"] === "string" ? record["value"] : void 0;
+		if (label === void 0) continue;
+		const raw = record["value"];
+		options.push({
+			label,
+			value: typeof raw === "string" || typeof raw === "number" ? String(raw) : label
+		});
+	}
+	return options;
+}
+/**
+* A `Table`'s columns.
+*
+* A string entry is both key and heading; an object entry may name them apart.
+* A column with neither is skipped, because a table with a nameless column has
+* a cell nobody can read.
+*/
+function columnList(value) {
+	if (!Array.isArray(value)) return [];
+	const columns = [];
+	for (const entry of value) {
+		if (typeof entry === "string") {
+			columns.push({
+				key: entry,
+				label: entry
+			});
+			continue;
+		}
+		if (typeof entry !== "object" || entry === null) continue;
+		const record = entry;
+		const key = typeof record["key"] === "string" ? record["key"] : void 0;
+		const label = typeof record["label"] === "string" ? record["label"] : void 0;
+		if (key === void 0 && label === void 0) continue;
+		const align = record["align"];
+		columns.push({
+			key: key ?? label,
+			label: label ?? key,
+			...align === "start" || align === "center" || align === "end" ? { align } : {}
+		});
+	}
+	return columns;
+}
+/**
+* One table row, read against the columns.
+*
+* A row may be a list of cells positional to the columns, or an object keyed by
+* column key. Both are flattened to one string per column here so the renderer
+* never has to ask which form arrived, and a cell that is missing in either
+* form is an empty string rather than a hole in the row.
+*/
+function rowCells(row, columns) {
+	if (Array.isArray(row)) return columns.map((_, at) => cellText(row[at]));
+	if (typeof row === "object" && row !== null) {
+		const record = row;
+		return columns.map((column) => cellText(record[column.key]));
+	}
+	return columns.map((_, at) => at === 0 ? cellText(row) : "");
+}
+/** One cell, as characters. Objects and arrays are not text and read as blank. */
+function cellText(value) {
+	if (typeof value === "string") return value;
+	if (typeof value === "number" && Number.isFinite(value)) return String(value);
+	if (typeof value === "boolean") return String(value);
+	return "";
+}
+/**
+* A chart's series.
+*
+* `series` takes precedence over `data`, which is upstream's rule: a spec that
+* carries both meant the multi-series one. A bare `data` array becomes one
+* unnamed series so the same geometry draws both.
+*/
+function seriesList(node) {
+	const multi = node["series"];
+	if (Array.isArray(multi)) {
+		const series = [];
+		for (const entry of multi) {
+			if (Array.isArray(entry)) {
+				series.push({
+					label: "",
+					data: numberList(entry)
+				});
+				continue;
+			}
+			if (typeof entry !== "object" || entry === null) continue;
+			const record = entry;
+			const data = numberList(record["data"]);
+			if (data.length === 0) continue;
+			series.push({
+				label: typeof record["label"] === "string" ? record["label"] : "",
+				data
+			});
+		}
+		if (series.length > 0) return series;
+	}
+	const single = numberList(node["data"]);
+	return single.length > 0 ? [{
+		label: strOr(node, "label", ""),
+		data: single
+	}] : [];
+}
+/** A list of strings, with everything unreadable dropped. */
+function stringList(value) {
+	if (!Array.isArray(value)) return [];
+	return value.filter((entry) => typeof entry === "string");
+}
+/**
+* The protocols an image source may carry.
+*
+* Three, and the same three `MarkdownText` allows, for the same reasons.
+* `javascript:` and `vbscript:` hand a string to a script engine; `data:` is
+* the modern one — a `data:image/svg+xml` document is a script host in enough
+* browsers' history that allow-listing image media types is not worth the
+* argument; `blob:` and `file:` reach the host's own storage. A scheme-less
+* `//host/path` is refused too: it inherits the page's protocol and is the one
+* form that looks relative and is not.
+*/
+const ALLOWED_PROTOCOLS = ["http", "https"];
+/**
+* An image source, or `undefined` when the model asked for one this surface
+* will not fetch.
+*
+* `undefined` rather than an empty string, because React omits an absent
+* attribute entirely: a refused source leaves an `<img>` with no `src` and its
+* `alt` showing, which is a legible answer, where `src=""` re-requests the
+* current document in several browsers.
+*/
+function safeSrc(value) {
+	if (value === void 0) return void 0;
+	const url = value.trim();
+	if (url === "" || url.startsWith("//")) return void 0;
+	const colon = url.indexOf(":");
+	const slash = url.indexOf("/");
+	const question = url.indexOf("?");
+	const hash = url.indexOf("#");
+	if (colon === -1 || slash !== -1 && colon > slash || question !== -1 && colon > question || hash !== -1 && colon > hash) return url;
+	return ALLOWED_PROTOCOLS.includes(url.slice(0, colon).toLowerCase()) ? url : void 0;
+}
+/**
+* Colour syntax this surface will put in a `style` attribute.
+*
+* `Box` and `Card` take a `background` the model writes freely, and that value
+* lands in an inline style. React escapes the string, so there is no way out of
+* the declaration — but there is a way out of the *property*: `url(…)` inside a
+* background is a network request to an address the model chose, which turns a
+* rendered widget into a beacon. So this is an allow-list of shapes rather than
+* a deny-list of characters: a hex triple, one of the numeric colour functions
+* with nothing but numbers and separators inside it, or a bare CSS colour
+* keyword.
+*/
+const COLOR = /^(?:#[0-9a-f]{3,8}|[a-z]{3,20}|(?:rgba?|hsla?|oklch|oklab|lab|lch)\([\d\s.,%/-]+\))$/i;
+/** A colour prop, or `undefined` when it is not a shape this will paint. */
+function safeColor(node, prop) {
+	const value = str(node, prop)?.trim();
+	return value !== void 0 && COLOR.test(value) ? value : void 0;
+}
+/**
+* A CSS length this surface will put in a `style` attribute.
+*
+* A number is pixels, which is what a model writing `"width": 240` means. A
+* string has to be a plain number-and-unit: enough for `50%`, `12rem` and
+* `320px`, and not enough for `calc(…)`, `var(…)` or anything else that can
+* reach outside its own declaration. `auto` and `full` are the two keywords the
+* vocabulary documents.
+*/
+const LENGTH = /^(?:\d+(?:\.\d+)?(?:px|rem|em|%|ch|vw|vh)?)$/;
+/** A length prop as a CSS value, or `undefined`. */
+function safeLength(node, prop) {
+	const raw = node[prop];
+	if (typeof raw === "number") return Number.isFinite(raw) ? `${raw}px` : void 0;
+	if (typeof raw !== "string") return void 0;
+	const value = raw.trim();
+	if (value === "auto") return "auto";
+	if (value === "full") return "100%";
+	if (!LENGTH.test(value)) return void 0;
+	return /^\d+(?:\.\d+)?$/.test(value) ? `${value}px` : value;
+}
+/** A short, quoted description of what actually arrived. */
+function describe(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "an array";
+	const kind = typeof value;
+	if (kind === "object") {
+		const type = value.$type;
+		return type === void 0 ? "an object with no $type" : `an object whose $type is a ${typeof type}`;
+	}
+	if (kind === "undefined") return "nothing";
+	return `a ${kind}`;
+}
+//#endregion
+export { GENERATIVE_TYPES, actionOf, childList, choice, columnList, describe, flag, isGenerativeType, isNode, list, num, numberList, optionList, rowCells, safeColor, safeLength, safeSrc, scale, seriesList, str, strOr, stringList };