@yahoo/uds-create-config 4.10.5 → 4.12.0

package/dist/capture/capture-to-spec.d.ts

@@ -0,0 +1,69 @@
+import { Config } from "../framework/Config.js";
+import { CapturedNodeJson } from "./captured-tree.js";
+
+//#region src/capture/capture-to-spec.d.ts
+/**
+ * A rendered page (or one element of it) as a canvas spec.
+ *
+ * Every emitted component marks its layers with `data-uds-component` and `data-uds-layer`, and its
+ * classes follow the grammar the config derives, so the tree of components and most of their props
+ * read straight off the DOM. With the dev flag on, a root layer also stamps its primitive props as
+ * `data-uds-props` and each slot layer its slot name as `data-uds-slot`; those answer exactly and
+ * replace the guesses below. Without them, slot content that a hand-authored render placed directly
+ * is routed by DOM order into `children`, and a prop with no class or text (an `id`, a boolean the
+ * render never paints) is not recovered.
+ */
+interface SpecElement {
+  [key: string]: unknown;
+  type: string;
+  props: Record<string, unknown>;
+  children?: string[];
+  slots?: Record<string, string[]>;
+}
+interface Spec {
+  [key: string]: unknown;
+  root: string;
+  meta: Record<string, unknown>;
+  elements: Record<string, SpecElement>;
+}
+interface CaptureToSpecOptions {
+  /** The captured page, as the host parsed it. */
+  readonly tree: CapturedNodeJson;
+  readonly config: Config;
+  /** CSS selector for the subtree to convert; the whole document by default. */
+  readonly selector?: string;
+  /** Wraps every top-level element under this root; required when the capture has several. */
+  readonly root?: {
+    type: string;
+    props?: Record<string, unknown>;
+  };
+  /** The spec's frame width, recorded on `meta`; what `100vw` means inside the frame. */
+  readonly width?: number;
+  /** The frame height, what `100vh` means inside the frame. */
+  readonly height?: number;
+  /** Children kept per element, so a long list stays a list; `0` keeps every child. */
+  readonly childCap?: number;
+  /** Names a glyph the DOM does not: a bare `<svg>`, or a renderer whose name is not stamped. */
+  readonly icons?: IconHook;
+}
+interface IconAnswer {
+  /** The component that renders the glyph, as the config paths it. */
+  readonly component: string;
+  readonly props: Record<string, unknown>;
+}
+interface IconHook {
+  /** Components that render a glyph themselves; one whose SVG cannot be named is dropped. */
+  readonly renderers: ReadonlySet<string>;
+  resolve(svg: {
+    readonly paths: readonly string[];
+    readonly width?: number;
+  }): IconAnswer | undefined;
+}
+interface CaptureToSpecResult {
+  readonly spec: Spec;
+  /** Icon components the SVG hook could not name; their elements are dropped. */
+  readonly unresolvedIcons: number;
+}
+declare function specFromCapture(options: CaptureToSpecOptions): CaptureToSpecResult;
+//#endregion
+export { CaptureToSpecOptions, CaptureToSpecResult, IconAnswer, IconHook, Spec, SpecElement, specFromCapture };

package/dist/capture/capture-to-spec.js

@@ -0,0 +1,433 @@
+import { elementFromCaptured, isCapturedElement } from "./captured-tree.js";
+import { classGrammar, normalizeCssValue } from "./class-grammar.js";
+//#region src/capture/capture-to-spec.ts
+/** Inline declarations that are rendering plumbing rather than a prop. */
+const SKIP_INLINE_PROPERTY = new Set([
+	"display",
+	"visibility",
+	"box-sizing",
+	"touch-action",
+	"pointer-events",
+	"user-select",
+	"will-change",
+	"cursor",
+	"transition",
+	"transition-property",
+	"transition-duration",
+	"transition-timing-function",
+	"transition-delay",
+	"animation",
+	"outline",
+	"outline-style",
+	"outline-width",
+	"outline-color",
+	"outline-offset",
+	"border-image",
+	"border-image-source",
+	"border-image-slice",
+	"border-image-width",
+	"border-image-outset",
+	"border-image-repeat"
+]);
+/** Browser defaults a shorthand such as `border: none` expands into. */
+const SKIP_INLINE_VALUE = new Set([
+	"none",
+	"initial",
+	"inherit",
+	"unset",
+	"revert",
+	"medium",
+	"currentcolor",
+	"auto"
+]);
+const VIEWPORT_VALUE = /\d(vh|vw|dvh|dvw|svh|svw|lvh|lvw|vmin|vmax)\b/;
+/** A value that is nothing but the viewport: `100vh`, `100dvw`. */
+const WHOLE_VIEWPORT = /^\d+(\.\d+)?(vh|vw|dvh|dvw|svh|svw|lvh|lvw)$/;
+/** Viewport units in an expression as frame pixels; a unit with no frame size to measure stays. */
+function frameUnits(value, width, height) {
+	return value.replace(/(\d+(?:\.\d+)?)(vw|dvw|svw|lvw|vh|dvh|svh|lvh)\b/g, (whole, amount, unit) => {
+		const size = unit.endsWith("vw") ? width : height;
+		if (size === void 0) return whole;
+		const px = Number(amount) / 100 * size;
+		return `${Number.isInteger(px) ? px : px.toFixed(2)}px`;
+	});
+}
+/** Runtime channels and DOM plumbing a stamp carries that a spec never authors. */
+const SKIP_STAMPED = new Set([
+	"as",
+	"style",
+	"key",
+	"ref",
+	"tabIndex",
+	"role",
+	"className",
+	"layerProps",
+	"hidden",
+	"htmlFor",
+	"href",
+	"target",
+	"rel"
+]);
+const ROOT_LAYER = "[data-uds-component][data-uds-layer=\"root\"]";
+const DEFAULT_CHILD_CAP = 12;
+const isElement = isCapturedElement;
+function specFromCapture(options) {
+	const tree = elementFromCaptured(options.tree);
+	let scope = tree;
+	if (options.selector) scope = tree.closest(options.selector) ?? tree.querySelector(options.selector);
+	if (!scope) throw new Error(`Nothing matches "${options.selector}" in the capture.`);
+	const converter = new Converter(options, classGrammar(options.config));
+	const top = scope.closest(ROOT_LAYER) === scope || scope.tagName === "svg" ? converter.convertTop(scope) : converter.convertChildren(scope);
+	let rootKey;
+	if (options.root) {
+		rootKey = "root";
+		converter.elements.root = {
+			type: options.root.type,
+			props: { ...options.root.props ?? {} },
+			children: top
+		};
+	} else if (top.length === 1) rootKey = top[0];
+	else throw new Error(`The capture has ${top.length} top-level components; pass \`root\` to wrap them.`);
+	const meta = {};
+	if (options.width !== void 0) meta.width = options.width;
+	return {
+		spec: {
+			root: rootKey,
+			meta,
+			elements: reachable(converter.elements, rootKey)
+		},
+		unresolvedIcons: converter.unresolvedIcons
+	};
+}
+/** Only what the root reaches is an element; anything else was a branch the cap cut. */
+function reachable(elements, root) {
+	const kept = {};
+	const stack = [root];
+	while (stack.length > 0) {
+		const key = stack.pop();
+		if (kept[key] || !elements[key]) continue;
+		kept[key] = elements[key];
+		stack.push(...elements[key].children ?? []);
+		for (const fills of Object.values(elements[key].slots ?? {})) stack.push(...fills);
+	}
+	return kept;
+}
+var Converter = class {
+	elements = {};
+	unresolvedIcons = 0;
+	counter = 0;
+	childCap;
+	constructor(options, grammar) {
+		this.options = options;
+		this.grammar = grammar;
+		this.childCap = options.childCap ?? DEFAULT_CHILD_CAP;
+	}
+	convertTop(el) {
+		return this.convert(el);
+	}
+	convertChildren(el) {
+		const out = [];
+		for (let i = 0; i < el.childNodes.length; i += 1) {
+			if (this.childCap > 0 && out.length >= this.childCap) break;
+			const node = el.childNodes[i];
+			if (isElement(node)) out.push(...this.convert(node));
+		}
+		return out;
+	}
+	/** The components under `layer`, skipping every other layer `path` marks inside it. */
+	convertOutsideLayers(layer, path) {
+		const out = [];
+		for (let i = 0; i < layer.childNodes.length; i += 1) {
+			if (this.childCap > 0 && out.length >= this.childCap) break;
+			const node = layer.childNodes[i];
+			if (!isElement(node)) continue;
+			if (node.getAttribute("data-uds-component") === path && node.getAttribute("data-uds-layer") !== "root") continue;
+			if (node.tagName.toLowerCase() === "svg" || node.hasAttribute("data-uds-component") && node.getAttribute("data-uds-layer") === "root") out.push(...this.convert(node));
+			else if (visible(node)) out.push(...this.convertOutsideLayers(node, path));
+		}
+		return out;
+	}
+	convert(el) {
+		if (!visible(el)) return [];
+		const path = el.getAttribute("data-uds-component");
+		if (path && el.getAttribute("data-uds-layer") === "root") {
+			const key = this.component(el, path);
+			return key ? [key] : [];
+		}
+		if (el.tagName.toLowerCase() === "svg") return this.icon(el);
+		return this.convertChildren(el);
+	}
+	/** A bare `<svg>` placed as the component its library renders it with. */
+	icon(svg) {
+		const answer = this.options.icons?.resolve(svgOf(svg));
+		if (!answer) {
+			this.unresolvedIcons += 1;
+			return [];
+		}
+		const key = this.key(answer.component);
+		this.elements[key] = {
+			type: `component:${answer.component}`,
+			props: { ...answer.props }
+		};
+		return [key];
+	}
+	key(path) {
+		this.counter += 1;
+		return `${(path.split("/").pop() ?? "el").toLowerCase().replace(/[^a-z0-9]+/g, "") || "el"}${this.counter}`;
+	}
+	component(el, path) {
+		const grammar = this.grammar.component(path);
+		const props = {};
+		const stamped = stampedProps(el);
+		if (grammar) this.propsFromClasses(el, grammar, props);
+		Object.assign(props, stamped);
+		if (grammar) this.propsFromInlineStyle(el, grammar, props);
+		if (props.position === "fixed") props.position = "absolute";
+		const renders = this.options.icons?.renderers.has(path) ?? false;
+		if (renders) {
+			const svg = el.tagName.toLowerCase() === "svg" ? el : el.querySelector("svg");
+			const answer = svg ? this.options.icons?.resolve(svgOf(svg)) : void 0;
+			if (answer) for (const [prop, value] of Object.entries(answer.props)) props[prop] ??= value;
+			else if (Object.keys(stamped).length === 0) {
+				this.unresolvedIcons += 1;
+				return;
+			}
+		}
+		const key = this.key(path);
+		const element = {
+			type: `component:${path}`,
+			props
+		};
+		const declared = grammar?.declared ?? {};
+		const slots = {};
+		for (const layer of asArray(el.querySelectorAll("[data-uds-slot]"))) {
+			if (nearestRoot(layer) !== el || hiddenBetween(layer, el)) continue;
+			const names = slotNames(layer).filter((slot) => !grammar || slot in declared);
+			const intoOf = (slot) => grammar?.layerProps.get(slot)?.into ?? "children";
+			const ownChildren = names.filter((slot) => intoOf(slot) === "children");
+			for (const slot of names) {
+				const into = intoOf(slot);
+				if (into === "children" && slot !== ownChildren.at(-1)) continue;
+				const holder = into === "children" ? layer : slotLayerNamed(layer, into);
+				if (!holder) continue;
+				const fills = holder === layer ? this.convertOutsideLayers(layer, path) : this.convertChildren(holder);
+				if (fills.length > 0) slots[slot] = fills;
+				else if (holder !== layer) {
+					const text = collapse(ownText(holder));
+					if (text) props[slot] = text;
+				}
+			}
+		}
+		const claimed = /* @__PURE__ */ new Set();
+		for (const [prop, route] of grammar?.layerProps ?? []) {
+			if (props[prop] !== void 0 || slots[prop]) continue;
+			const layer = layerOf(el, path, route.layer);
+			if (!layer || !visible(layer) || hiddenBetween(layer, el)) continue;
+			const holdsComponents = layer.querySelector(`${ROOT_LAYER}, svg`) !== null;
+			if (!route.content && holdsComponents) continue;
+			claimed.add(layer);
+			if (route.content && holdsComponents) {
+				const fills = this.convertOutsideLayers(layer, path);
+				if (fills.length > 0) slots[prop] = fills;
+			} else {
+				const text = collapse(ownText(layer, claimed));
+				if (text) props[prop] = text;
+			}
+		}
+		const loose = [];
+		const looseSelector = renders ? ROOT_LAYER : `${ROOT_LAYER}, svg`;
+		for (const nested of asArray(el.querySelectorAll(looseSelector))) {
+			if (this.childCap > 0 && loose.length >= this.childCap) break;
+			if (nearestRoot(nested) !== el) continue;
+			if (hiddenBetween(nested, el)) continue;
+			const stampedLayer = nested.parentElement?.closest("[data-uds-slot]") ?? null;
+			if (stampedLayer && nearestRoot(stampedLayer) === el) continue;
+			if (withinAny(nested, claimed, el)) continue;
+			loose.push(...this.convert(nested));
+		}
+		if (loose.length > 0 && !slots.children) slots.children = loose;
+		if (Object.keys(slots).length > 0) element.slots = slots;
+		const aria = el.getAttribute("aria-label");
+		if (aria) {
+			if ("tooltip" in declared && props.tooltip === void 0) props.tooltip = aria;
+			props["aria-label"] = aria;
+		}
+		const textSlot = declared.children;
+		if (textSlot?.type === "slot" && textSlot.text && props.children === void 0 && !slots.children) {
+			const text = collapse(ownText(el, claimed));
+			if (text) props.children = text;
+		}
+		if (el.getAttribute("aria-selected") === "true" || el.getAttribute("aria-pressed") === "true") {
+			if ("selected" in declared) props.selected = true;
+		}
+		if (el.getAttribute("aria-checked") === "true") {
+			if ("checked" in declared) props.checked = true;
+			else if ("selected" in declared) props.selected = true;
+		}
+		if (grammar) {
+			for (const prop of Object.keys(props)) if (!(prop in declared) && prop !== "aria-label") delete props[prop];
+		}
+		this.elements[key] = element;
+		return key;
+	}
+	propsFromClasses(el, grammar, props) {
+		for (const cls of classesOf(el)) {
+			const condition = grammar.conditions.get(cls);
+			if (condition) {
+				Object.assign(props, condition);
+				continue;
+			}
+			const composite = grammar.composites.get(cls);
+			if (composite) {
+				props[composite.prop] = composite.value;
+				continue;
+			}
+			const style = this.grammar.styleProp(cls);
+			if (style) {
+				const prop = grammar.propForStyleProperty.get(style.path);
+				if (prop && props[prop] === void 0) props[prop] = this.frameValue(style.path, style.leaf);
+			}
+		}
+	}
+	/**
+	* A leaf as it reads inside a frame: a viewport-sized value (`100vh`) measures the canvas, so it
+	* becomes the leaf that fills the container instead.
+	*/
+	frameValue(path, leaf) {
+		if (leaf === "") return true;
+		if (!this.grammar.viewportLeaf(path, leaf)) return leaf;
+		return this.grammar.fullLeaf(path) ?? leaf;
+	}
+	/**
+	* The element's inline styles as props: a component's own `style` is the one place a size the
+	* classes do not carry lives, so `width: 300px` becomes the declared width prop with `[300px]`,
+	* and `column-gap: var(--uds-spacing-2)` becomes the gap leaf `2`. A value with no leaf lands as
+	* an off-scale `[value]` only on a property that takes one. Rendering plumbing (display, box
+	* sizing, transitions, browser defaults) is not a prop and is skipped.
+	*/
+	propsFromInlineStyle(el, grammar, props) {
+		const style = el.getAttribute("style");
+		if (!style) return;
+		for (const declaration of style.split(";")) {
+			const at = declaration.indexOf(":");
+			if (at < 0) continue;
+			const property = declaration.slice(0, at).trim().toLowerCase();
+			let value = normalizeCssValue(declaration.slice(at + 1));
+			if (!value || SKIP_INLINE_PROPERTY.has(property) || SKIP_INLINE_VALUE.has(value)) continue;
+			if (property === "position" && value === "fixed") value = "absolute";
+			if (VIEWPORT_VALUE.test(value) && !WHOLE_VIEWPORT.test(value)) value = frameUnits(value, this.options.width, this.options.height);
+			for (const option of this.grammar.stylePropsFor(property)) {
+				const prop = grammar.propForStyleProperty.get(option.path);
+				if (!prop) continue;
+				let next;
+				const leaf = option.leafFor(value);
+				if (WHOLE_VIEWPORT.test(value)) next = option.fullLeaf;
+				else if (leaf !== void 0) next = leaf === "" ? true : leaf;
+				else if (option.arbitrary) next = `[${value.replaceAll(" ", "_")}]`;
+				if (next === void 0) continue;
+				props[prop] = next;
+				break;
+			}
+		}
+	}
+};
+function stampedProps(el) {
+	const raw = el.getAttribute("data-uds-props");
+	if (!raw) return {};
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return {};
+	}
+	if (!parsed || typeof parsed !== "object") return {};
+	const out = {};
+	for (const [key, value] of Object.entries(parsed)) {
+		if (SKIP_STAMPED.has(key)) continue;
+		if (key.startsWith("data-") || key.startsWith("aria-") || key.startsWith("on")) continue;
+		out[key] = value;
+	}
+	return out;
+}
+/** The props a slot layer's marker names. */
+function slotNames(layer) {
+	return (layer.getAttribute("data-uds-slot") ?? "").split(/\s+/).filter(Boolean);
+}
+/** The slot layer inside `layer` whose marker names `slot`, with no other slot layer between. */
+function slotLayerNamed(layer, slot) {
+	return asArray(layer.querySelectorAll("[data-uds-slot]")).find((candidate) => slotNames(candidate).includes(slot) && candidate.parentElement?.closest("[data-uds-slot]") === layer);
+}
+function nearestRoot(el) {
+	return el.parentElement?.closest(ROOT_LAYER) ?? null;
+}
+function visible(el) {
+	const style = el.getAttribute("style") ?? "";
+	if (/display:\s*none/.test(style) || /visibility:\s*hidden/.test(style)) return false;
+	if (/(^|;)\s*opacity:\s*0+(\.0+)?\s*(;|$)/.test(style)) return false;
+	if (el.hasAttribute("hidden")) return false;
+	if (el.getAttribute("aria-hidden") === "true" && el.tagName.toLowerCase() !== "svg") return false;
+	if (el.getAttribute("role") === "tooltip") return false;
+	if (el.getAttribute("data-uds-props")?.includes("\"hidden\":true")) return false;
+	return true;
+}
+function classesOf(el) {
+	return (el.getAttribute("class") ?? "").split(/\s+/).filter(Boolean);
+}
+function ownText(el, skip) {
+	let text = "";
+	for (let i = 0; i < el.childNodes.length; i += 1) {
+		const node = el.childNodes[i];
+		if (!isElement(node)) {
+			text += node.textContent ?? "";
+			continue;
+		}
+		if (skip?.has(node)) continue;
+		if (node.hasAttribute("data-uds-slot")) continue;
+		if (node.getAttribute("data-uds-layer") === "root" && node.hasAttribute("data-uds-component")) continue;
+		if (!visible(node)) continue;
+		text += ownText(node, skip);
+	}
+	return text;
+}
+/** Whether an element between `el` and its component root `root` is hidden. */
+function hiddenBetween(el, root) {
+	let node = el.parentElement;
+	while (node && node !== root) {
+		if (!visible(node)) return true;
+		node = node.parentElement;
+	}
+	return false;
+}
+/** Whether `el` sits inside one of `layers`, below `root`. */
+function withinAny(el, layers, root) {
+	let node = el.parentElement;
+	while (node && node !== root) {
+		if (layers.has(node)) return true;
+		node = node.parentElement;
+	}
+	return false;
+}
+/** The component's own layer named `layer`, when the DOM marks one under this root. */
+function layerOf(root, path, layer) {
+	for (const candidate of asArray(root.querySelectorAll(`[data-uds-component="${path}"][data-uds-layer="${layer}"]`))) if (nearestRoot(candidate) === root) return candidate;
+}
+function svgOf(svg) {
+	return {
+		paths: asArray(svg.querySelectorAll("path")).map((p) => p.getAttribute("d") ?? "").filter(Boolean),
+		width: numberAttr(svg, "width")
+	};
+}
+function collapse(text) {
+	return text.replace(/\s+/g, " ").trim();
+}
+function numberAttr(el, name) {
+	const raw = el.getAttribute(name);
+	if (raw === null) return void 0;
+	const value = Number.parseFloat(raw);
+	return Number.isFinite(value) ? value : void 0;
+}
+function asArray(list) {
+	return Array.from(list);
+}
+//#endregion
+export { specFromCapture };

package/dist/capture/captured-tree.d.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+
+//#region src/capture/captured-tree.d.ts
+/**
+ * A captured page as plain data: the tree a host hands the `node/from-html` op. Each node is a tag,
+ * its attributes and its children, text included, which is everything the converter reads off a
+ * rendered screen: the component and layer markers, the class list, the inline style, the stamped
+ * props and the text. Parsing markup into this shape is the host's job, so the config package
+ * needs no DOM.
+ */
+interface CapturedNodeJson {
+  readonly tag: string;
+  readonly attrs?: Readonly<Record<string, string>>;
+  readonly children?: ReadonlyArray<string | CapturedNodeJson>;
+}
+declare const CapturedNode: z.ZodType<CapturedNodeJson>;
+declare class CapturedText {
+  readonly textContent: string;
+  readonly parentElement: CapturedElement | null;
+  readonly nodeType = 3;
+  constructor(textContent: string, parentElement: CapturedElement | null);
+}
+type CapturedChild = CapturedElement | CapturedText;
+/** The slice of the DOM element API the converter walks, over captured data. */
+declare class CapturedElement {
+  private readonly attrs;
+  readonly nodeType = 1;
+  readonly tagName: string;
+  readonly childNodes: CapturedChild[];
+  parentElement: CapturedElement | null;
+  constructor(tag: string, attrs: Readonly<Record<string, string>>);
+  getAttribute(name: string): string | null;
+  hasAttribute(name: string): boolean;
+  get attributes(): ReadonlyArray<{
+    name: string;
+    value: string;
+  }>;
+  get textContent(): string;
+  get children(): CapturedElement[];
+  querySelectorAll(selector: string): CapturedElement[];
+  querySelector(selector: string): CapturedElement | null;
+  closest(selector: string): CapturedElement | null;
+  /** Back to data, for a host that rewrites part of a tree. */
+  toJSON(): CapturedNodeJson;
+}
+/** A captured tree as elements the converter can walk. */
+declare function elementFromCaptured(node: CapturedNodeJson, parent?: CapturedElement | null): CapturedElement;
+/** The subset of a DOM element a host's parser exposes, whichever DOM it is. */
+interface DomLikeElement {
+  readonly nodeType: number;
+  readonly tagName?: string;
+  readonly textContent?: string | null;
+  readonly attributes?: ArrayLike<{
+    readonly name: string;
+    readonly value: string;
+  }>;
+  readonly childNodes?: ArrayLike<DomLikeElement>;
+}
+/**
+ * A captured tree from a parsed DOM element, for a host: scripts, styles and templates carry no
+ * rendered content and are left out, as is whitespace-only text.
+ */
+declare function capturedFromDom(el: DomLikeElement): CapturedNodeJson;
+//#endregion
+export { CapturedChild, CapturedElement, CapturedNode, CapturedNodeJson, CapturedText, DomLikeElement, capturedFromDom, elementFromCaptured };