Files
hyperframes/packages/core/src/runtime/getVariables.ts
T
Miguel Ángel f312fca7e2 feat(producer): fail a render whose variables the page does not declare (#7548)
* feat(producer): fail a render whose variables the page does not declare

* chore(producer): keep the comment share and the dead-code audit clean for the variables check
2026-11-11 08:46:13 +00:00

340 lines
14 KiB
TypeScript

/**
* Reads the resolved variables for the current composition.
*
* Top-level path: declared defaults from `<html data-composition-variables="...">`
* merged with `window.__hfVariables` (set at render time by the engine when
* the user passes `hyperframes render --variables '<json>'`).
*
* Sub-comp path (per-instance scoping): when called inside a sub-composition
* script wrapped by `compositionScoping.ts`, the wrapper shadows
* `__hyperframes.getVariables` with a scoped variant that returns the
* pre-merged values from `window.__hfVariablesByComp[compositionId]`. The
* loader populates that table before running scripts, layering the host
* element's `data-variable-values` over the sub-comp's declared defaults.
*
* Returns `Partial<T>` because not every declared variable is guaranteed to
* have a default, and not every key in `__hfVariables` is guaranteed to be
* declared. Callers are expected to destructure with their own fallbacks
* where strictness matters:
*
* const { title = "Untitled", theme = "light" } = getVariables<MyVars>();
*/
import { cssVariableName, detectSlugCollisions } from "../tokenSlug";
import { scopedVariablesFor } from "./variableScope";
export function getVariables<
T extends Record<string, unknown> = Record<string, unknown>,
>(): Partial<T> {
if (typeof document === "undefined") return {} as Partial<T>;
const declarers = topLevelDeclarers();
const declaredDefaults: Record<string, unknown> = {};
for (const el of declarers) {
Object.assign(declaredDefaults, readDeclaredDefaults(el));
}
const overrides = readRenderOverrides();
const merged = { ...declaredDefaults, ...overrides };
for (const el of declarers) warnUnknownEnumValues(el, merged);
return merged as Partial<T>;
}
/**
* Top-level declarers: `<html>` first, then others outside a sub-composition's scope; a later one wins.
* `getVariables` merges these, and `getDeclaredVariableSources` hands the same elements to a strict render.
*/
function topLevelDeclarers(): Set<Element> {
const declarers = new Set<Element>();
if (document.documentElement?.hasAttribute("data-composition-variables")) {
declarers.add(document.documentElement);
}
for (const el of Array.from(document.querySelectorAll("[data-composition-variables]"))) {
if (!scopedVariablesFor(el)) declarers.add(el);
}
return declarers;
}
/** The raw `data-composition-variables` text of each top-level declarer, in precedence order (later wins). */
export function getDeclaredVariableSources(): string[] {
if (typeof document === "undefined") return [];
return Array.from(
topLevelDeclarers(),
(el) => el.getAttribute("data-composition-variables") ?? "",
);
}
/**
* An enum variable given a value outside its declared `options` is coerced to
* the composition's default by the composition's own guard. That fallback is
* deliberate (a bad value must never break a frame) but it was silent, so a
* meaningless value could sit in a project indefinitely and look correct only
* by coincidence. Warn; do not change what renders.
*
* Reads the option set straight off `data-composition-variables`, so it covers
* every declared enum, not just the `accentColors` guard shape, and needs no
* per-composition code. Deduped per composition+variable+value so a remount
* (studio re-init, seek) cannot spam the console.
*
* Silent for a valid value, for an absent one (an absent variable resolves to
* its own declared default), and for a value that already equals that default
* (nothing fell back).
*/
const warnedUnknownEnumValues = new Set<string>();
/**
* The declaration array on an element, or empty when there isn't a usable one.
*
* One owner for `getAttribute` -> `JSON.parse` -> "is it an array", because
* every reader of this attribute needs exactly that and each copy was a place
* the three answers could drift apart.
*/
function readDeclarations(el: Element | null | undefined): Record<string, unknown>[] {
const raw = el?.getAttribute("data-composition-variables");
if (!raw) return [];
let parsed: unknown;
try {
parsed = JSON.parse(raw);
} catch {
return [];
}
if (!Array.isArray(parsed)) return [];
return parsed.filter(
(entry): entry is Record<string, unknown> => !!entry && typeof entry === "object",
);
}
/**
* What to call the composition in a warning.
*
* The canonical top-level shape declares the variables on `<html>`, which
* carries no id: the composition id sits on the root element below it. Without
* the descendant lookup the message reads "composition variable ...", naming
* nothing in a project that has more than one.
*/
function compositionLabel(declarer: Element, compositionId?: string): string {
return (
compositionId?.trim() ||
declarer.getAttribute("data-composition-id")?.trim() ||
declarer.querySelector("[data-composition-id]")?.getAttribute("data-composition-id")?.trim() ||
"composition"
);
}
/** The declared option values of an enum entry, as comparable primitives. */
function declaredOptions(entry: Record<string, unknown>): (string | number)[] {
if (!Array.isArray(entry.options)) return [];
return entry.options
.map((option) =>
option && typeof option === "object" ? (option as Record<string, unknown>).value : option,
)
.filter((v): v is string | number => typeof v === "string" || typeof v === "number");
}
/**
* Did `resolved` hand this entry a value outside its own option set?
*
* Silent for a valid value, for an absent one (an absent variable resolves to
* its own declared default), and for a value that already equals that default,
* because then nothing fell back. A default outside its own option set is a
* declaration defect for the linter to catch; warning here would print the
* self-contradictory "got X ... rendering X".
*/
function unknownEnumValue(
entry: Record<string, unknown>,
resolved: Record<string, unknown>,
): { id: string; value: unknown; allowed: (string | number)[] } | null {
if (typeof entry.id !== "string") return null;
const value = resolved[entry.id];
if (value === undefined || value === null) return null;
if ("default" in entry && String(value) === String(entry.default)) return null;
const allowed = declaredOptions(entry);
// Stringified compare: `--variables` / `data-variable-values` can deliver a
// declared numeric option as a string, and that is not the defect here.
if (allowed.length === 0 || allowed.some((v) => String(v) === String(value))) return null;
return { id: entry.id, value, allowed };
}
export function warnUnknownEnumValues(
declarer: Element | null | undefined,
resolved: Record<string, unknown>,
compositionId?: string,
): void {
if (!declarer) return;
const entries = readDeclarations(declarer);
if (entries.length === 0) return;
const move = compositionLabel(declarer, compositionId);
for (const entry of entries) {
const found = unknownEnumValue(entry, resolved);
if (!found) continue;
// Deduped per composition+variable+value so a remount (studio re-init,
// seek) cannot spam the console.
const key = `${move}|${found.id}|${String(found.value)}`;
if (warnedUnknownEnumValues.has(key)) continue;
warnedUnknownEnumValues.add(key);
const fallback = "default" in entry ? JSON.stringify(entry.default) : "the composition default";
console.warn(
`[hyperframes] runtime_unknown_enum_value: ${move} variable "${found.id}" got ${JSON.stringify(found.value)}, which is not a declared option (${found.allowed.join(", ")}). Rendering ${fallback} instead.`,
);
}
}
/** Test-only: clear the per-page dedupe set. */
export function resetUnknownEnumWarnings(): void {
warnedUnknownEnumValues.clear();
}
/**
* Extract `{id: default}` map from an element's `data-composition-variables`
* attribute. Returns an empty object when the attribute is missing, the JSON
* is unparseable, or the payload isn't an array. Exported so the
* compositionLoader can compute the same defaults map for sub-comp instances.
*/
export function readDeclaredDefaults(root: Element | null): Record<string, unknown> {
const out: Record<string, unknown> = {};
for (const entry of readDeclarations(root)) {
if (typeof entry.id !== "string" || !("default" in entry)) continue;
out[entry.id] = entry.default;
}
return out;
}
const APPLIED_VARS_ATTR = "data-hf-css-vars";
function hasInlineStyle(target: Element): target is Element & ElementCSSInlineStyle {
return "style" in target && typeof (target as HTMLElement).style?.setProperty === "function";
}
/**
* Define primitive-valued variables as CSS custom properties on `target`,
* recording the applied names so re-init/unmount can clear them. Empty
* strings are skipped — CSSOM setProperty("", …) REMOVES the property, and a
* blank default has no CSS meaning anyway.
*/
export function applyCssVariables(target: Element, variables: Record<string, unknown>): void {
if (!hasInlineStyle(target)) return;
const applied: string[] = [];
for (const [id, value] of Object.entries(variables)) {
if ((typeof value === "string" && value !== "") || typeof value === "number") {
const name = cssVariableName(id);
target.style.setProperty(name, String(value));
applied.push(name);
}
}
if (applied.length > 0) target.setAttribute(APPLIED_VARS_ATTR, applied.join(" "));
}
/** Keep only variables whose CSS custom property is not already defined. */
export function filterVariablesIfAbsent(
target: Element,
variables: Record<string, unknown>,
view: Window | null,
): Record<string, unknown> {
const filtered: Record<string, unknown> = {};
for (const [id, value] of Object.entries(variables)) {
const name = cssVariableName(id);
const existing =
(hasInlineStyle(target) ? target.style.getPropertyValue(name) : "") ||
(view ? view.getComputedStyle(target).getPropertyValue(name) : "");
if (existing.trim() === "") filtered[id] = value;
}
return filtered;
}
/** Remove custom properties a previous applyCssVariables call defined. */
export function clearAppliedCssVariables(target: Element): void {
if (!hasInlineStyle(target)) return;
const applied = target.getAttribute(APPLIED_VARS_ATTR);
if (!applied) return;
for (const name of applied.split(" ")) {
if (name.startsWith("--")) target.style.removeProperty(name);
}
target.removeAttribute(APPLIED_VARS_ATTR);
}
/**
* Imported figma components reference brand tokens as `var(--slug, literal)`.
* Define each declaring element's composition variables as CSS custom
* properties ON THAT ELEMENT — scoping by the cascade, so two compositions
* on one page can't clobber each other and a flattened sub-composition root
* correctly styles only its own subtree.
*
* Declared DEFAULTS are define-if-absent: a value the author already styled
* (stylesheet `:root` rule, compile-time emission, hand-written inline) wins
* over the declared default, preserving pre-existing conventions where a
* variable id coincides with an authored custom property. Render-time
* overrides (`--variables` → `window.__hfVariables`) always win — that's
* explicit user intent.
*/
export function injectCompositionCssVariables(doc: Document): void {
const declarers = new Set<Element>();
if (doc.documentElement?.hasAttribute("data-composition-variables")) {
declarers.add(doc.documentElement);
}
for (const el of Array.from(doc.querySelectorAll("[data-composition-variables]"))) {
declarers.add(el);
}
const overrides = readRenderOverrides();
const allIds: string[] = [];
for (const el of declarers) {
allIds.push(...applyDeclaredForElement(el, overrides, doc.defaultView));
}
for (const group of detectSlugCollisions(allIds)) {
console.warn(
`composition variables ${group.join(", ")} collapse to the same CSS property ${cssVariableName(group[0] ?? "")}. Rename one to avoid cross-talk`,
);
}
}
/** Apply one declarer's variables (define-if-absent for defaults, overrides
* always win). Returns the declared ids for collision reporting. */
function applyDeclaredForElement(
el: Element,
overrides: Record<string, unknown>,
view: Window | null,
): string[] {
if (!hasInlineStyle(el)) return [];
const declared = readDeclaredDefaults(el);
const toApply: Record<string, unknown> = {};
for (const [id, value] of Object.entries(declared)) {
if (id in overrides) continue; // overrides applied below, always win
const name = cssVariableName(id);
// define-if-absent: respect authored/compiled definitions
const existing =
el.style.getPropertyValue(name) ||
(view ? view.getComputedStyle(el).getPropertyValue(name) : "");
if (existing.trim() !== "") continue;
toApply[id] = value;
}
for (const [id, value] of Object.entries(overrides)) {
if (id in declared) toApply[id] = value;
}
applyCssVariables(el, toApply);
return Object.keys(declared);
}
/** Parse a host element's `data-variable-values` JSON attribute (per-instance
* sub-composition overrides). Shared by the runtime loader and the bundler. */
export function parseHostVariableValues(host: Element): Record<string, unknown> {
const raw = host.getAttribute("data-variable-values");
if (!raw) return {};
let parsed: unknown;
try {
parsed = JSON.parse(raw);
} catch {
return {};
}
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
return parsed as Record<string, unknown>;
}
/** Render-time variable overrides (`hyperframes render --variables`). */
export function readRenderOverrides(): Record<string, unknown> {
if (typeof window === "undefined") return {};
const raw = (window as Window & { __hfVariables?: unknown }).__hfVariables;
if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
return raw as Record<string, unknown>;
}