@hyperframes/core 0.7.27 → 0.7.29

package/dist/figma/tokensToVariables.js

@@ -0,0 +1,118 @@
+/**
+ * Phase 2 translator: figma variables → composition brand-variable entries,
+ * a human-readable sidecar, and binding-index records (design spec §6, §7.1).
+ *
+ * Pure — REST payload in, artifacts out. Alias chains are walked to the leaf
+ * value (cycle-safe) but the binding records the semantic id the designer
+ * bound, so a swapped primitive doesn't orphan the link.
+ */
+import { figmaColorToCss } from "./color.js";
+const TYPE_MAP = {
+    COLOR: "color",
+    FLOAT: "number",
+    STRING: "string",
+    BOOLEAN: "boolean",
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+/**
+ * The collection's defaultModeId is the authority for "which mode is the
+ * base value" (Light vs Dark). Falls back to first-inserted mode when the
+ * collection or its default mode isn't in the payload.
+ */
+function baseModeValue(payload, collections) {
+    const modes = payload.valuesByMode ?? {};
+    const collection = collections[payload.variableCollectionId ?? ""];
+    if (isRecord(collection) && typeof collection.defaultModeId === "string") {
+        const preferred = modes[collection.defaultModeId];
+        if (preferred !== undefined)
+            return preferred;
+    }
+    for (const value of Object.values(modes))
+        return value;
+    return undefined;
+}
+function collectionName(payload, collections) {
+    const collection = collections[payload.variableCollectionId ?? ""];
+    return isRecord(collection) && typeof collection.name === "string" ? collection.name : null;
+}
+/** Follow VARIABLE_ALIAS links to a leaf value; null on cycle/missing. */
+function resolveValue(start, vars) {
+    const chain = [];
+    const seen = new Set();
+    let currentId = start;
+    while (!seen.has(currentId)) {
+        chain.push(currentId);
+        seen.add(currentId);
+        const payload = vars.variables[currentId];
+        if (!payload)
+            return null;
+        const value = baseModeValue(payload, vars.variableCollections);
+        if (isRecord(value) && value.type === "VARIABLE_ALIAS" && typeof value.id === "string") {
+            currentId = value.id;
+            continue;
+        }
+        return { value, chain };
+    }
+    return null; // cycle
+}
+/** Value must match the declared resolvedType — a stringified "8" for a
+ * FLOAT would silently break the CompositionVariableEntry contract. */
+function toEntryValue(resolvedType, raw) {
+    if (resolvedType === "COLOR")
+        return figmaColorToCss(raw);
+    if (resolvedType === "FLOAT")
+        return typeof raw === "number" ? raw : null;
+    if (resolvedType === "BOOLEAN")
+        return typeof raw === "boolean" ? raw : null;
+    if (resolvedType === "STRING")
+        return typeof raw === "string" ? raw : null;
+    return null;
+}
+export function tokensToVariables(vars, source) {
+    const entries = [];
+    const bindings = [];
+    const sidecarTokens = [];
+    for (const [figmaId, payload] of Object.entries(vars.variables)) {
+        const entryType = TYPE_MAP[payload.resolvedType ?? ""];
+        const resolved = resolveValue(figmaId, vars);
+        const value = resolved ? toEntryValue(payload.resolvedType, resolved.value) : null;
+        // Namespace by collection: figma allows the same variable name in
+        // different collections (Semantic Blue/500 vs Primitive Blue/500), and a
+        // collision here would silently merge two distinct bindings.
+        const collection = collectionName(payload, vars.variableCollections);
+        const compositionVariableId = collection
+            ? `figma:${collection}/${payload.name}`
+            : `figma:${payload.name}`;
+        // Sidecar keeps EVERY variable — including unresolvable ones (value:
+        // null) — for designer visibility into what didn't map; entries/bindings
+        // below only get the mappable subset.
+        sidecarTokens.push({
+            name: payload.name,
+            type: entryType ?? payload.resolvedType ?? "unknown",
+            figmaId,
+            key: payload.key,
+            value,
+        });
+        if (!entryType || value === null || !resolved)
+            continue;
+        entries.push({
+            id: compositionVariableId,
+            type: entryType,
+            label: payload.name,
+            default: value,
+        });
+        bindings.push({
+            kind: "binding",
+            figmaId,
+            key: payload.key,
+            sourceFileKey: source.fileKey,
+            aliasChain: resolved.chain.length > 1 ? resolved.chain : undefined,
+            compositionVariableId,
+            version: source.version,
+        });
+    }
+    return { entries, bindings, sidecar: { source, tokens: sidecarTokens } };
+}
+//# sourceMappingURL=tokensToVariables.js.map

package/dist/figma/tokensToVariables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokensToVariables.js","sourceRoot":"","sources":["../../src/figma/tokensToVariables.ts"],"names":[],"mappings":"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"}

package/dist/figma/types.d.ts

@@ -0,0 +1,81 @@
+export interface FigmaRef {
+    fileKey: string;
+    nodeId?: string;
+}
+export type FigmaAssetFormat = "png" | "svg" | "jpg" | "pdf";
+export interface FigmaProvenance {
+    source: "figma";
+    fileKey: string;
+    nodeId: string;
+    version?: string;
+    format?: FigmaAssetFormat;
+    scale?: number;
+}
+export interface FigmaManifestRecord {
+    id: string;
+    type: "image" | "video";
+    path: string;
+    source: string;
+    description?: string;
+    width?: number;
+    height?: number;
+    provenance: FigmaProvenance;
+}
+export interface AssetSnippet {
+    path: string;
+    html: string;
+}
+/** A motion.dev easing value as returned by get_motion_context: a named ease
+ *  (e.g. "linear") or a cubic-bezier control-point array [x1,y1,x2,y2]. */
+export type MotionEase = string | [number, number, number, number];
+/** One animated property, normalized from get_motion_context's motion.dev snippet. */
+export interface MotionTrack {
+    /** motion.dev property name: "opacity" | "x" | "y" | "scaleX" | "scaleY" | "rotation" | ... */
+    property: string;
+    values: Array<number | string>;
+    /** normalized 0..1, same length as values */
+    times: number[];
+    /** length values.length - 1; ease[i] governs the segment values[i] -> values[i+1] */
+    ease: MotionEase[];
+    /** seconds */
+    duration: number;
+    /** Infinity or a finite count; clamped to finite during translation */
+    repeat?: number;
+}
+export interface MotionDoc {
+    /** string-literal CSS selector for the target element, e.g. "#hero-title" */
+    selector: string;
+    tracks: MotionTrack[];
+}
+export type MappedEase = {
+    kind: "named";
+    ease: string;
+} | {
+    kind: "bezier";
+    bezier: [number, number, number, number];
+};
+export interface CustomEaseRef {
+    name: string;
+    bezier: [number, number, number, number];
+}
+export interface GsapKeyframeStep {
+    value: number | string;
+    /** seconds */
+    duration: number;
+    /** GSAP ease string or a registered CustomEase name */
+    ease: string;
+}
+export interface GsapTween {
+    selector: string;
+    property: string;
+    initial: number | string;
+    steps: GsapKeyframeStep[];
+    /** finite; 0 = play once */
+    repeat: number;
+}
+export interface TimelineSpec {
+    timelineId: string;
+    tweens: GsapTween[];
+    customEases: CustomEaseRef[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/figma/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/figma/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAE7D,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,eAAe,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED;2EAC2E;AAC3E,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAEnE,sFAAsF;AACtF,MAAM,WAAW,WAAW;IAC1B,+FAA+F;IAC/F,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IAC/B,6CAA6C;IAC7C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,qFAAqF;IACrF,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,cAAc;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC;AAEjE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,cAAc;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,WAAW,EAAE,aAAa,EAAE,CAAC;CAC9B"}

package/dist/figma/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/figma/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/figma/types.ts"],"names":[],"mappings":""}