jfs-components 0.1.34 → 0.1.36

package/scripts/extract-figma-modes.js

@@ -21,7 +21,8 @@
  * GET /v1/files/:key call per extraction.
  *
  * Usage:
- *   export FIGMA_ACCESS_TOKEN=figd_...
+ *   # Either add FIGMA_ACCESS_TOKEN=figd_... to .env in the current project,
+ *   # or export it in the shell (shell values take precedence over .env).
  *   npx jfs-extract-modes "https://www.figma.com/design/<fileKey>/...?node-id=1-10636"
  *   npx jfs-extract-modes <fileKey> <nodeId> [--out modes.json]
  *
@@ -41,105 +42,132 @@
  *   }
  */
 
-"use strict";
+"use strict"
 
-const fs = require("fs");
-const path = require("path");
+const fs = require("fs")
+const path = require("path")
+const dotenv = require("dotenv")
 
-const API_BASE = "https://api.figma.com/v1";
-const TOKENS_DIR = path.join(__dirname, "..", "src", "design-tokens");
-const COLLECTION_KEY_PATTERN = /^VariableCollectionId:([0-9a-f]{40})\//;
+const API_BASE = "https://api.figma.com/v1"
+const TOKENS_DIR = path.join(__dirname, "..", "src", "design-tokens")
+const COLLECTION_KEY_PATTERN = /^VariableCollectionId:([0-9a-f]{40})\//
+
+/**
+ * Load the consumer project's root .env without replacing values that were
+ * explicitly exported in the shell. The CLI is normally launched by npx from
+ * the consumer project, so process.cwd() is the correct project root rather
+ * than the installed package directory.
+ */
+function loadProjectEnv(cwd = process.cwd()) {
+  const envPath = path.resolve(cwd, ".env")
+  if (!fs.existsSync(envPath)) return null
+
+  const result = dotenv.config({
+    path: envPath,
+    override: false,
+    quiet: true,
+  })
+  if (result.error) {
+    throw new Error(`Could not load ${envPath}: ${result.error.message}`)
+  }
+  return envPath
+}
 
 function usage(exitCode) {
   console.error(
     `Usage:
-  FIGMA_ACCESS_TOKEN=... jfs-extract-modes <figma-url> [--out modes.json]
-  FIGMA_ACCESS_TOKEN=... jfs-extract-modes <fileKey> <nodeId> [--out modes.json]
-  FIGMA_ACCESS_TOKEN=... jfs-extract-modes --add-keys <master-library-fileKey-or-url>`,
-  );
-  process.exit(exitCode);
+  jfs-extract-modes <figma-url> [--out modes.json]
+  jfs-extract-modes <fileKey> <nodeId> [--out modes.json]
+  jfs-extract-modes --add-keys <master-library-fileKey-or-url>
+
+Set FIGMA_ACCESS_TOKEN in the shell or in .env in the current project.`,
+  )
+  process.exit(exitCode)
 }
 
 function fileKeyFromUrlOrKey(value) {
   if (/^https?:\/\//.test(value)) {
-    const match = new URL(value).pathname.match(/\/(?:design|file)\/([^/]+)/);
+    const match = new URL(value).pathname.match(/\/(?:design|file)\/([^/]+)/)
     if (!match) {
-      console.error("Could not parse fileKey from URL.");
-      process.exit(1);
+      console.error("Could not parse fileKey from URL.")
+      process.exit(1)
     }
-    return match[1];
+    return match[1]
   }
-  return value;
+  return value
 }
 
 function parseArgs(argv) {
-  const args = argv.slice(2);
-  const out = { fileKey: null, nodeId: null, outPath: null, addKeysFile: null };
+  const args = argv.slice(2)
+  const out = { fileKey: null, nodeId: null, outPath: null, addKeysFile: null }
 
   for (let i = 0; i < args.length; i += 1) {
-    const arg = args[i];
+    const arg = args[i]
     if (arg === "--out") {
-      out.outPath = args[++i];
+      out.outPath = args[++i]
     } else if (arg === "--add-keys") {
-      out.addKeysFile = fileKeyFromUrlOrKey(args[++i] ?? "");
+      out.addKeysFile = fileKeyFromUrlOrKey(args[++i] ?? "")
     } else if (arg === "--help" || arg === "-h") {
-      usage(0);
+      usage(0)
     } else if (/^https?:\/\//.test(arg)) {
-      const url = new URL(arg);
-      out.fileKey = fileKeyFromUrlOrKey(arg);
-      const nodeParam = url.searchParams.get("node-id");
-      if (nodeParam) out.nodeId = nodeParam.replace(/-/g, ":");
+      const url = new URL(arg)
+      out.fileKey = fileKeyFromUrlOrKey(arg)
+      const nodeParam = url.searchParams.get("node-id")
+      if (nodeParam) out.nodeId = nodeParam.replace(/-/g, ":")
     } else if (!out.fileKey) {
-      out.fileKey = arg;
+      out.fileKey = arg
     } else if (!out.nodeId) {
-      out.nodeId = arg.replace(/-/g, ":");
+      out.nodeId = arg.replace(/-/g, ":")
     } else {
-      usage(1);
+      usage(1)
     }
   }
 
-  if (out.addKeysFile) return out;
-  if (!out.fileKey || !out.nodeId) usage(1);
-  return out;
+  if (out.addKeysFile) return out
+  if (!out.fileKey || !out.nodeId) usage(1)
+  return out
 }
 
 function getToken() {
-  const token = process.env.FIGMA_ACCESS_TOKEN || process.env.FIGMA_TOKEN;
+  const token = process.env.FIGMA_ACCESS_TOKEN || process.env.FIGMA_TOKEN
   if (!token) {
-    console.error("Set FIGMA_ACCESS_TOKEN (needs file read access only).");
-    process.exit(1);
+    console.error(
+      "Set FIGMA_ACCESS_TOKEN in the shell or in the project-root .env " +
+        "(requires only the Figma file_content:read scope).",
+    )
+    process.exit(1)
   }
-  return token;
+  return token
 }
 
 async function figmaGet(urlPath, token) {
   const response = await fetch(`${API_BASE}${urlPath}`, {
     headers: { "X-Figma-Token": token },
-  });
-  const body = await response.json().catch(() => ({}));
+  })
+  const body = await response.json().catch(() => ({}))
   if (!response.ok) {
     throw new Error(
       `Figma API ${response.status} for ${urlPath}: ${body.err || body.message || "request failed"}`,
-    );
+    )
   }
-  return body;
+  return body
 }
 
 function listVariablesJsonFiles() {
-  let files;
+  let files
   try {
     files = fs
       .readdirSync(TOKENS_DIR)
       .filter((name) => name.endsWith("-variables-full.json"))
-      .map((name) => path.join(TOKENS_DIR, name));
+      .map((name) => path.join(TOKENS_DIR, name))
   } catch {
-    files = [];
+    files = []
   }
   if (files.length === 0) {
-    console.error(`No *-variables-full.json found in ${TOKENS_DIR}.`);
-    process.exit(1);
+    console.error(`No *-variables-full.json found in ${TOKENS_DIR}.`)
+    process.exit(1)
   }
-  return files;
+  return files
 }
 
 /**
@@ -148,22 +176,22 @@ function listVariablesJsonFiles() {
  * resolution is the only supported path.
  */
 function buildKeyIndex() {
-  const byKey = new Map();
-  const missingKeys = [];
-  const files = listVariablesJsonFiles();
+  const byKey = new Map()
+  const missingKeys = []
+  const files = listVariablesJsonFiles()
 
   for (const file of files) {
-    const data = JSON.parse(fs.readFileSync(file, "utf8"));
+    const data = JSON.parse(fs.readFileSync(file, "utf8"))
     for (const collection of data.collections ?? []) {
       if (typeof collection.key !== "string" || collection.key.length === 0) {
-        missingKeys.push(`${collection.name} (${path.basename(file)})`);
-        continue;
+        missingKeys.push(`${collection.name} (${path.basename(file)})`)
+        continue
       }
-      const modes = new Map();
+      const modes = new Map()
       for (const mode of collection.modes ?? []) {
-        modes.set(mode.modeId, mode.name);
+        modes.set(mode.modeId, mode.name)
       }
-      byKey.set(collection.key, { name: collection.name, modes });
+      byKey.set(collection.key, { name: collection.name, modes })
     }
   }
 
@@ -172,48 +200,48 @@ function buildKeyIndex() {
       "The variables JSON has no collection keys, so modes cannot be resolved.\n" +
         "Run this once against the master variables library file to patch them in:\n" +
         "  jfs-extract-modes --add-keys <master-library-fileKey-or-url>",
-    );
-    process.exit(1);
+    )
+    process.exit(1)
   }
   if (missingKeys.length > 0) {
     console.error(
       `Warning: ${missingKeys.length} collection(s) have no key and were skipped:\n  ` +
         missingKeys.slice(0, 10).join("\n  "),
-    );
+    )
   }
 
   console.error(
     `Indexed ${byKey.size} collection(s) by key from ${files.length} variables JSON file(s).`,
-  );
-  return byKey;
+  )
+  return byKey
 }
 
 function findNodePath(node, targetId, trail = []) {
-  const next = [...trail, node];
-  if (node.id === targetId) return next;
+  const next = [...trail, node]
+  if (node.id === targetId) return next
   for (const child of node.children ?? []) {
-    const found = findNodePath(child, targetId, next);
-    if (found) return found;
+    const found = findNodePath(child, targetId, next)
+    if (found) return found
   }
-  return null;
+  return null
 }
 
 function extractModes(fileResponse, nodeId, byKey) {
-  const pathToRoot = findNodePath(fileResponse.document, nodeId);
+  const pathToRoot = findNodePath(fileResponse.document, nodeId)
   if (!pathToRoot) {
-    throw new Error(`Node "${nodeId}" not found in file.`);
+    throw new Error(`Node "${nodeId}" not found in file.`)
   }
 
-  const root = pathToRoot[pathToRoot.length - 1];
-  const layers = [];
-  const unresolved = [];
+  const root = pathToRoot[pathToRoot.length - 1]
+  const layers = []
+  const unresolved = []
 
   function resolveNodeModes(node) {
-    const modes = {};
+    const modes = {}
     for (const [collectionId, modeId] of Object.entries(
       node.explicitVariableModes ?? {},
     )) {
-      const keyMatch = String(collectionId).match(COLLECTION_KEY_PATTERN);
+      const keyMatch = String(collectionId).match(COLLECTION_KEY_PATTERN)
       if (!keyMatch) {
         // Local (non-subscribed) collection in the consumer file: not part of
         // the published library, nothing to resolve against.
@@ -222,66 +250,66 @@ function extractModes(fileResponse, nodeId, byKey) {
           collectionId,
           modeId,
           reason: "local collection (no library key in id)",
-        });
-        continue;
+        })
+        continue
       }
-      const collection = byKey.get(keyMatch[1]);
+      const collection = byKey.get(keyMatch[1])
       if (!collection) {
         unresolved.push({
           layer: node.name,
           collectionId,
           modeId,
           reason: "key not in variables JSON (library out of date?)",
-        });
-        continue;
+        })
+        continue
       }
-      const modeName = collection.modes.get(modeId);
+      const modeName = collection.modes.get(modeId)
       if (!modeName) {
         unresolved.push({
           layer: node.name,
           collectionId,
           modeId,
           reason: `mode not in collection "${collection.name}" (re-export variables JSON?)`,
-        });
-        continue;
+        })
+        continue
       }
-      modes[collection.name] = modeName;
+      modes[collection.name] = modeName
     }
-    return modes;
+    return modes
   }
 
   // Modes set on ancestors above the requested node (inherited by everything below)
-  const inherited = {};
+  const inherited = {}
   for (const ancestor of pathToRoot.slice(0, -1)) {
-    Object.assign(inherited, resolveNodeModes(ancestor));
+    Object.assign(inherited, resolveNodeModes(ancestor))
   }
 
   function walk(node, trail) {
-    const modes = resolveNodeModes(node);
+    const modes = resolveNodeModes(node)
     if (Object.keys(modes).length > 0) {
       layers.push({
         layer: node.name,
         nodeId: node.id,
         path: trail.join(" > "),
         modes,
-      });
+      })
     }
     for (const child of node.children ?? []) {
-      walk(child, [...trail, child.name]);
+      walk(child, [...trail, child.name])
     }
   }
 
-  walk(root, [root.name]);
+  walk(root, [root.name])
 
   const result = {
     file: fileResponse.name ?? null,
     root: root.name,
     note: "explicit variable modes per layer; children inherit ancestor modes unless overridden",
     modes: layers,
-  };
-  if (Object.keys(inherited).length > 0) result.inheritedFromAncestors = inherited;
-  if (unresolved.length > 0) result.unresolved = unresolved;
-  return result;
+  }
+  if (Object.keys(inherited).length > 0) result.inheritedFromAncestors = inherited
+  if (unresolved.length > 0) result.unresolved = unresolved
+  return result
 }
 
 /**
@@ -293,67 +321,68 @@ async function addKeys(masterFileKey, token) {
   const response = await figmaGet(
     `/files/${masterFileKey}/variables/local`,
     token,
-  );
-  const remote = Object.values(response.meta?.variableCollections ?? {});
+  )
+  const remote = Object.values(response.meta?.variableCollections ?? {})
   const keyById = new Map(
     remote
       .filter((collection) => collection.key)
       .map((collection) => [collection.id, collection.key]),
-  );
+  )
   console.error(
     `Fetched ${keyById.size} collection key(s) from ${masterFileKey}.`,
-  );
+  )
 
   for (const file of listVariablesJsonFiles()) {
-    const data = JSON.parse(fs.readFileSync(file, "utf8"));
-    let patched = 0;
-    let missing = 0;
+    const data = JSON.parse(fs.readFileSync(file, "utf8"))
+    let patched = 0
+    let missing = 0
     for (const collection of data.collections ?? []) {
-      const key = keyById.get(collection.id);
+      const key = keyById.get(collection.id)
       if (key) {
-        collection.key = key;
-        patched += 1;
+        collection.key = key
+        patched += 1
       } else if (!collection.key) {
-        missing += 1;
+        missing += 1
       }
     }
-    fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`);
+    fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`)
     console.error(
       `${path.basename(file)}: patched ${patched} key(s)` +
         (missing ? `, ${missing} collection(s) still without key` : ""),
-    );
+    )
   }
 }
 
 async function main() {
-  const args = parseArgs(process.argv);
-  const token = getToken();
+  const args = parseArgs(process.argv)
+  loadProjectEnv()
+  const token = getToken()
 
   if (args.addKeysFile) {
-    await addKeys(args.addKeysFile, token);
-    return;
+    await addKeys(args.addKeysFile, token)
+    return
   }
 
-  const byKey = buildKeyIndex();
+  const byKey = buildKeyIndex()
   const fileResponse = await figmaGet(
     `/files/${args.fileKey}?ids=${encodeURIComponent(args.nodeId)}`,
     token,
-  );
-  const result = extractModes(fileResponse, args.nodeId, byKey);
+  )
+  const result = extractModes(fileResponse, args.nodeId, byKey)
 
-  const json = JSON.stringify(result, null, 2);
+  const json = JSON.stringify(result, null, 2)
   if (args.outPath) {
-    fs.writeFileSync(path.resolve(args.outPath), `${json}\n`);
-    console.error(`Wrote ${args.outPath}`);
+    fs.writeFileSync(path.resolve(args.outPath), `${json}\n`)
+    console.error(`Wrote ${args.outPath}`)
   }
-  process.stdout.write(`${json}\n`);
+  process.stdout.write(`${json}\n`)
 }
 
 if (require.main === module) {
   main().catch((error) => {
-    console.error(error.message || error);
-    process.exit(1);
-  });
+    console.error(error.message || error)
+    process.exit(1)
+  })
 }
 
-module.exports = { buildKeyIndex, extractModes };
+module.exports = { buildKeyIndex, extractModes, loadProjectEnv }

package/src/components/LottiePlayer/LottiePlayer.tsx

@@ -29,10 +29,10 @@ export type LottiePlayerProps = {
    * Override the rendered size. Pass a number for a square box, or
    * `{ width, height }` for non-square.
    *
-   * When omitted, size is resolved from the `media/width` and `media/height`
-   * design tokens (default `117 × 117`). The `Media / Output` collection
+   * When omitted, size is resolved from the `video/width` and `video/height`
+   * design tokens (default `117 × 117`). The `Video / Output` collection
    * exposes `L | M | S` modes (117 / 70 / 20) — pass
-   * `modes={{ 'Media / Output': 'M' }}` to render at 70×70, etc.
+   * `modes={{ 'Video / Output': 'M' }}` to render at 70×70, etc.
    */
   size?: number | { width: number; height: number }
   /** Play the animation on mount. Defaults to `true`. */
@@ -57,9 +57,9 @@ function resolveSize(
   if (typeof size === 'number') return { width: size, height: size }
   if (size && typeof size === 'object') return size
   const width =
-    Number(getVariableByName('media/width', modes))
+    Number(getVariableByName('video/width', modes)) || DEFAULT_SIZE
   const height =
-    Number(getVariableByName('media/height', modes))
+    Number(getVariableByName('video/height', modes)) || DEFAULT_SIZE
   return { width, height }
 }
 
@@ -83,8 +83,8 @@ function resolveSize(
  * webpack via platform extensions — same pattern as `MediaCard/GlassFill`.
  *
  * Token-driven sizing: when `size` is omitted, `LottiePlayer` reads
- * `media/width` and `media/height` from the Figma variables resolver, so the
- * animation matches the surrounding component's `Media / Output` mode
+ * `video/width` and `video/height` from the Figma variables resolver, so the
+ * animation matches the surrounding component's `Video / Output` mode
  * automatically. This is the same sizing contract `PageHero` and
  * `LottieIntroBlock` use for their `media` slots.
  *
@@ -95,7 +95,7 @@ function resolveSize(
  *
  * <LottiePlayer source={animation} />                    // 117 × 117 (default)
  * <LottiePlayer source={animation} size={70} />          // 70 × 70
- * <LottiePlayer source={animation} modes={{ 'Media / Output': 'S' }} />  // 20 × 20
+ * <LottiePlayer source={animation} modes={{ 'Video / Output': 'S' }} />  // 20 × 20
  * <PageHero media={<LottiePlayer source={animation} />} />
  * ```
  */

package/src/components/LottiePlayer/LottiePlayer.web.tsx

@@ -28,9 +28,9 @@ function resolveSize(
   if (typeof size === 'number') return { width: size, height: size }
   if (size && typeof size === 'object') return size
   const width =
-    Number(getVariableByName('media/width', modes))
+    Number(getVariableByName('video/width', modes)) || DEFAULT_SIZE
   const height =
-    Number(getVariableByName('media/height', modes))
+    Number(getVariableByName('video/height', modes)) || DEFAULT_SIZE
   return { width, height }
 }