/** * Bake chosen variable values into an installed item's declared defaults. * * A block is mounted by a `
`, so `add --vars` can put * the values on that mount as `data-variable-values` and two mounts of the same * block can differ. A component has no mount element: it is markup you paste * into a host composition, and it reads its values through * `__hyperframes.getVariables()`, which merges the declared defaults of every * `[data-composition-variables]` element in the document with render-time * overrides. * * So for a component the only place a chosen value can live and survive being * pasted is the component's own declaration. Rewriting the defaults there is * what makes "customise it on the catalog page, copy the command, run it" end * with the look you picked. Before this, `--vars` was accepted, documented, and * silently discarded for every component in the catalog. */ import { isCompositionVariable, validateVariables, type CompositionVariable, } from "@hyperframes/core/variables"; export interface ApplyResult { /** The source with defaults rewritten. Unchanged when nothing applied. */ html: string; /** Variable ids whose default was replaced. */ applied: string[]; /** Ids the item does not declare. */ unknown: string[]; /** Ids declared but given a value the declaration does not allow. */ invalid: { id: string; reason: string }[]; } /** `--vars` values the item's declaration cannot take; the install writes nothing. */ export class InvalidVariableValuesError extends Error { constructor(readonly invalid: { id: string; reason: string }[]) { super(`--vars refused: ${invalid.map(({ id, reason }) => `${id}: ${reason}`).join("; ")}`); this.name = "InvalidVariableValuesError"; } } const ATTR = "data-composition-variables"; /** Locate the attribute's quoted value, tolerating either delimiter. */ function findDeclaration(source: string): { start: number; end: number; raw: string } | null { const at = source.indexOf(`${ATTR}=`); if (at === -1) return null; const quote = source[at + ATTR.length + 1]; if (quote !== "'" && quote !== '"') return null; const start = at + ATTR.length + 2; const end = source.indexOf(quote, start); if (end === -1) return null; return { start, end, raw: source.slice(start, end) }; } function decode(raw: string): string { return raw.replace(/'/g, "'").replace(/"/g, '"'); } /** Mirrors the escaping the block-mount path uses, so either delimiter is safe. */ function encode(json: string, quote: string): string { return quote === "'" ? json.replace(/'/g, "'") : json.replace(/"/g, """); } function rejectNumber(decl: CompositionVariable, value: unknown): string | null { if (decl.type !== "number") return null; const n = typeof value === "number" ? value : Number(value); if (!Number.isFinite(n)) return "not a number"; if (decl.min !== undefined && n < decl.min) return `below min ${decl.min}`; if (decl.max !== undefined && n > decl.max) return `above max ${decl.max}`; return null; } // Refuse what the runtime would ignore. Numbers keep their own check (string input, min/max); // every other type goes through the runtime's validator. function reject(decl: CompositionVariable, value: unknown): string | null { if (decl.type === "number") return rejectNumber(decl, value); const [issue] = validateVariables({ [decl.id]: value }, [decl]); if (!issue) return null; if (issue.kind === "enum-out-of-range") return `not one of ${issue.allowed.join(", ")}`; if (issue.kind === "type-mismatch") return `expected ${issue.expected}, got ${issue.actual}`; return null; } export function applyVariableDefaults( source: string, values: Record, ): ApplyResult { const ids = Object.keys(values); if (ids.length === 0) return { html: source, applied: [], unknown: [], invalid: [] }; const found = findDeclaration(source); if (!found) return { html: source, applied: [], unknown: ids, invalid: [] }; // isCompositionVariable is the predicate parseCompositionVariables filters // with -- the schema's own definition of a well-formed declaration. Using it // here means everything below works on a real discriminated union instead of // a bag of `unknown` re-checked at each use, and a declaration the schema // rejects is one we must not rewrite, because we would be guessing at its // shape. parseCompositionVariables itself takes a DOM Element, which the CLI // has no business constructing to read a string. let parsed: unknown; try { parsed = JSON.parse(decode(found.raw)); } catch { return { html: source, applied: [], unknown: ids, invalid: [] }; } if (!Array.isArray(parsed)) return { html: source, applied: [], unknown: ids, invalid: [] }; const declared: CompositionVariable[] = parsed.filter(isCompositionVariable); if (declared.length !== parsed.length) { // Rewriting a partially understood declaration would drop the entries we // could not model, so leave the file exactly as the registry shipped it. return { html: source, applied: [], unknown: ids, invalid: [] }; } const applied: string[] = []; const invalid: { id: string; reason: string }[] = []; const byId = new Map(declared.map((decl) => [decl.id, decl])); const updated = new Map(); for (const [id, value] of Object.entries(values)) { const decl = byId.get(id); if (!decl) continue; const reason = reject(decl, value); if (reason) { invalid.push({ id, reason }); continue; } // The declaration's own type decides how the value is stored. A number // written as the string "76" would trip the composition's guard and fall // back, which looks exactly like the value being ignored. updated.set(id, decl.type === "number" ? Number(value) : value); applied.push(id); } const unknown = ids.filter((id) => !byId.has(id)); if (applied.length === 0) return { html: source, applied, unknown, invalid }; // One declaration per line, matching how the registry authors these files, so // a re-install produces a readable diff rather than one enormous line. const quote = source[found.start - 1]!; const body = declared .map((decl) => { const next = updated.has(decl.id) ? { ...decl, default: updated.get(decl.id)! } : decl; return ` ${JSON.stringify(next)}`; }) .join(",\n"); const rewritten = encode(`[\n${body}\n ]`, quote); const html = source.slice(0, found.start) + rewritten + source.slice(found.end); return { html, applied, unknown, invalid }; }