@figma/code-connect 1.4.9 → 1.5.0

package/dist/commands/preview_utils.js

@@ -37,14 +37,21 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.collectNodesToPreview = collectNodesToPreview;
+exports.fetchComponentPropertyDefinitions = fetchComponentPropertyDefinitions;
+exports.parsePropsArg = parsePropsArg;
 exports.filterTemplatesForNodes = filterTemplatesForNodes;
 exports.getPrettierParserMap = getPrettierParserMap;
 exports.isPrettierParseable = isPrettierParseable;
 exports.formatSnippet = formatSnippet;
 exports.displayResults = displayResults;
+exports.parseMaxCombinationsArg = parseMaxCombinationsArg;
+exports.chunkNodeIdsForPreview = chunkNodeIdsForPreview;
+exports.parseMissingProperty = parseMissingProperty;
+exports.chunkOutcomeToResults = chunkOutcomeToResults;
 exports.handlePreview = handlePreview;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
 const prettier = __importStar(require("prettier"));
 const connect_1 = require("./connect");
 const logging_1 = require("../common/logging");
@@ -52,6 +59,8 @@ const validation_1 = require("../connect/validation");
 const project_1 = require("../connect/project");
 const figma_rest_api_1 = require("../connect/figma_rest_api");
 const fetch_1 = require("../common/fetch");
+const property_list_table_1 = require("./property_list_table");
+const property_combinations_1 = require("../connect/property_combinations");
 /**
  * Collect nodes to preview from file arguments.
  * Matches by exact path first, then by basename.
@@ -131,6 +140,85 @@ async function collectNodesToPreview(files, allCodeConnectObjects, dir, cmd) {
     }
     return nodesToPreview;
 }
+/**
+ * Fetch one node's property definitions from the REST `files/:key/nodes` endpoint.
+ */
+async function fetchNodeSchema(baseApiUrl, fileKey, nodeId, accessToken) {
+    try {
+        const nodesUrl = `${baseApiUrl}/files/${fileKey}/nodes?ids=${nodeId}`;
+        const resp = await fetch_1.request.get(nodesUrl, { headers: (0, figma_rest_api_1.getHeaders)(accessToken) });
+        if (resp.response.status !== 200) {
+            logging_1.logger.debug(`files/nodes returned ${resp.response.status} for ${nodeId}`);
+            return { status: 'error' };
+        }
+        const node = resp.data.nodes?.[nodeId];
+        const componentSetId = node?.components?.[nodeId]?.componentSetId || undefined;
+        const defs = node?.document?.componentPropertyDefinitions;
+        if (defs && Object.keys(defs).length > 0)
+            return { status: 'ok', defs, componentSetId };
+        logging_1.logger.debug(`files/nodes returned no componentPropertyDefinitions for ${nodeId}`);
+        return { status: 'empty', componentSetId };
+    }
+    catch (err) {
+        const detail = (0, fetch_1.isFetchError)(err) ? `status ${err.response?.status}` : String(err);
+        logging_1.logger.debug(`files/nodes fetch failed for ${nodeId} (${detail})`);
+        return { status: 'error' };
+    }
+}
+/**
+ * Fetch a component's property definitions from the REST `files/:key/nodes` endpoint.
+ */
+async function fetchComponentPropertyDefinitions(baseApiUrl, fileKey, nodeId, accessToken) {
+    const node = await fetchNodeSchema(baseApiUrl, fileKey, nodeId, accessToken);
+    if (node.status === 'error')
+        return { status: 'error' };
+    // Variant child → resolve to the parent COMPONENT_SET (whose schema carries the
+    // variant axes). Fall back to the variant's own defs if the set can't be fetched.
+    if (node.componentSetId) {
+        const set = await fetchNodeSchema(baseApiUrl, fileKey, node.componentSetId, accessToken);
+        if (set.status === 'ok')
+            return { status: 'ok', defs: set.defs };
+        logging_1.logger.debug(`Component set ${node.componentSetId} for variant ${nodeId} had no usable schema ` +
+            `(${set.status}); using the variant's own definitions`);
+    }
+    return node.status === 'ok' ? { status: 'ok', defs: node.defs } : { status: 'empty' };
+}
+/** Case-insensitive lookup of a `ComponentPropertyType` from a `--props` prefix token. */
+function parsePropertyTypePrefix(token) {
+    const upper = token.trim().toUpperCase();
+    return Object.values(figma_rest_api_1.FigmaRestApi.ComponentPropertyType).includes(upper)
+        ? upper
+        : undefined;
+}
+/**
+ * Parse a single `--props` argument into a name/value pair, with an optional
+ * `TYPE:` prefix to disambiguate properties that share a name but differ in
+ * type (e.g. a BOOLEAN and a TEXT property both named `textMsg`).
+ * Example: --props Variant=Primary "Has Icon=true" "BOOLEAN:textMsg=false"
+ *
+ * The prefix is only recognized when the token before the first `:` matches a
+ * known property type (case-insensitive); otherwise the whole name-part is kept
+ * as the property name, so real names containing `:` are preserved.
+ */
+function parsePropsArg(props) {
+    return props
+        .flatMap((arg) => arg.split(','))
+        .map((pair) => pair.trim())
+        .filter((pair) => pair.length > 0)
+        .map((pair) => {
+        const eq = pair.indexOf('=');
+        const namePart = (eq === -1 ? pair : pair.slice(0, eq)).trim();
+        const value = eq === -1 ? '' : pair.slice(eq + 1).trim();
+        const colon = namePart.indexOf(':');
+        if (colon !== -1) {
+            const type = parsePropertyTypePrefix(namePart.slice(0, colon));
+            if (type) {
+                return { name: namePart.slice(colon + 1).trim(), value, type };
+            }
+        }
+        return { name: namePart, value };
+    });
+}
 /**
  * Filter templates to only those matching the requested node IDs.
  */
@@ -222,20 +310,30 @@ async function formatSnippet(snippet, language) {
 /**
  * Display results with terminal colors
  */
+const purple = chalk_1.default.ansi256(93);
+const red = chalk_1.default.ansi256(196);
+const gray = chalk_1.default.ansi256(243);
+const yellow = chalk_1.default.ansi256(179);
 function displayResults(results) {
     console.log('');
     const successCount = results.filter((r) => r.success).length;
     const errorCount = results.filter((r) => !r.success).length;
-    const purple = '\x1b[38;5;93m';
-    const red = '\x1b[38;5;196m';
-    const gray = '\x1b[38;5;243m';
-    const reset = '\x1b[0m';
-    const bold = '\x1b[1m';
+    // A muted note when nested children rendered as placeholders (not an error).
+    const printUnresolved = (result) => {
+        if (!result.unresolvedInstances?.length)
+            return;
+        const names = result.unresolvedInstances.map((u) => u.name || u.guid).join(', ');
+        console.log(`  ${yellow(`⚠ ${result.unresolvedInstances.length} nested instance(s) not Code Connected: ${names}`)}`);
+    };
     for (const result of results) {
+        // When expanding property combinations, label the header with the specific combination.
+        const combinationSuffix = result.propertyCombinationLabel
+            ? ` ${gray(`— ${result.propertyCombinationLabel}`)}`
+            : '';
         if (result.success && result.snippet) {
-            const componentInfo = result.component ? ` ${gray}→ ${result.component}${reset}` : '';
-            console.log(`${purple}●${reset} ${bold}${result.filePath}${reset}${componentInfo}`);
-            console.log(`  ${gray}${result.url}${reset}`);
+            const componentInfo = result.component ? ` ${gray(`→ ${result.component}`)}` : '';
+            console.log(`${purple('●')} ${chalk_1.default.bold(result.filePath)}${componentInfo}${combinationSuffix}`);
+            console.log(`  ${gray(result.url)}`);
             console.log('');
             const indentedSnippet = result.snippet
                 .trim()
@@ -243,17 +341,30 @@ function displayResults(results) {
                 .map((line) => '  ' + line)
                 .join('\n');
             console.log(indentedSnippet);
+            printUnresolved(result);
             console.log('');
         }
         else {
-            const componentInfo = result.component ? ` ${gray}(${result.component})${reset}` : '';
-            console.log(`${red}✕${reset} ${bold}${result.filePath}${reset}${componentInfo}`);
-            console.log(`  ${gray}${result.url}${reset}`);
-            console.log(`  ${red}Error:${reset} ${result.error}`);
+            const componentInfo = result.component ? ` ${gray(`(${result.component})`)}` : '';
+            console.log(`${red('✕')} ${chalk_1.default.bold(result.filePath)}${componentInfo}${combinationSuffix}`);
+            console.log(`  ${gray(result.url)}`);
+            console.log(`  ${red('Error:')} ${result.error}`);
+            // One-line repair hint: the offending property and the real vocabulary.
+            // (Transport errors carry no vocabulary — nothing to hint.)
+            const available = result.errorDetails?.availableProperties?.map((p) => p.name).join(', ');
+            const missingProperty = result.errorDetails?.missingProperty;
+            if (missingProperty && available) {
+                console.log(`  ${gray(`property "${missingProperty}" not found — available: ${available}`)}`);
+            }
+            else if (available) {
+                console.log(`  ${gray(`available properties: ${available}`)}`);
+            }
+            printUnresolved(result);
             console.log('');
         }
     }
-    console.log(`${bold}Summary:${reset} ${purple}${successCount} succeeded${reset}, ${errorCount > 0 ? `${red}${errorCount} failed${reset}` : `${gray}${errorCount} failed${reset}`}`);
+    const failed = errorCount > 0 ? red(`${errorCount} failed`) : gray(`${errorCount} failed`);
+    console.log(`${chalk_1.default.bold('Summary:')} ${purple(`${successCount} succeeded`)}, ${failed}`);
 }
 // The server caps inbound request bodies at 5MB. The figmaDocs payload
 // (one Code Connect template per requested component) dominates the body size,
@@ -265,6 +376,22 @@ const PREVIEW_CHUNK_SIZE = 50;
 // overwhelms upstream token validation and causes spurious 403 "Invalid
 // token" responses for the chunks that queue up too long.
 const PREVIEW_MAX_CONCURRENCY = 5;
+// Mirrors MAX_PROPERTY_COMBINATIONS_PER_REQUEST in pixie/code_connect_preview_handler.ts.
+// `--all` caps enumeration here and warns rather than sending a request that fails wholesale.
+const MAX_PROPERTY_COMBINATIONS = 500;
+function parseMaxCombinationsArg(value) {
+    if (value === undefined) {
+        return MAX_PROPERTY_COMBINATIONS;
+    }
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        (0, logging_1.exitWithError)('--max-combinations must be a positive integer');
+    }
+    if (parsed > MAX_PROPERTY_COMBINATIONS) {
+        (0, logging_1.exitWithError)(`--max-combinations cannot exceed ${MAX_PROPERTY_COMBINATIONS}`);
+    }
+    return parsed;
+}
 function chunkArray(arr, size) {
     const chunks = [];
     for (let i = 0; i < arr.length; i += size) {
@@ -272,6 +399,41 @@ function chunkArray(arr, size) {
     }
     return chunks;
 }
+/**
+ * Split node IDs into request chunks that respect BOTH the node-count cap
+ * (PREVIEW_CHUNK_SIZE) and, when rendering property combinations, the server's
+ * per-request combination cap (MAX_PROPERTY_COMBINATIONS).
+ *
+ * The server sums combinations across every node in a request and rejects the
+ * whole request if the total exceeds the cap, so bundling by node count alone
+ * can push several individually-valid nodes over the limit and fail them all.
+ * Each node is already truncated to <= MAX_PROPERTY_COMBINATIONS upstream, so a
+ * single node always fits (worst case: one node per chunk).
+ */
+function chunkNodeIdsForPreview(nodeIds, propertyCombinationsByNodeId) {
+    if (!propertyCombinationsByNodeId) {
+        return chunkArray(nodeIds, PREVIEW_CHUNK_SIZE);
+    }
+    const chunks = [];
+    let current = [];
+    let currentCombinations = 0;
+    for (const nodeId of nodeIds) {
+        const count = propertyCombinationsByNodeId[nodeId]?.length ?? 0;
+        // Close the current chunk before adding this node would breach either cap.
+        if (current.length > 0 &&
+            (current.length >= PREVIEW_CHUNK_SIZE ||
+                currentCombinations + count > MAX_PROPERTY_COMBINATIONS)) {
+            chunks.push(current);
+            current = [];
+            currentCombinations = 0;
+        }
+        current.push(nodeId);
+        currentCombinations += count;
+    }
+    if (current.length > 0)
+        chunks.push(current);
+    return chunks;
+}
 async function runInWaves(items, fn, maxConcurrency) {
     const out = [];
     for (let i = 0; i < items.length; i += maxConcurrency) {
@@ -281,14 +443,55 @@ async function runInWaves(items, fn, maxConcurrency) {
     }
     return out;
 }
-function sendPreviewChunk({ chunkNodeIds, requiredTemplates, baseApiUrl, fileKey, accessToken, }) {
+function sendPreviewChunk({ chunkNodeIds, requiredTemplates, baseApiUrl, fileKey, accessToken, propertyCombinationsByNodeId, }) {
     const chunkTemplates = filterTemplatesForNodes(chunkNodeIds, requiredTemplates);
+    // Only include property combinations for the node IDs in this chunk.
+    let renderCombinations;
+    if (propertyCombinationsByNodeId) {
+        renderCombinations = {};
+        for (const nodeId of chunkNodeIds) {
+            if (propertyCombinationsByNodeId[nodeId]) {
+                renderCombinations[nodeId] = propertyCombinationsByNodeId[nodeId];
+            }
+        }
+    }
     return fetch_1.request
-        .post(`${baseApiUrl}/code_connect/preview_snippets?file_key=${fileKey}`, { nodeIds: chunkNodeIds, figmaDocs: { all: chunkTemplates } }, { headers: (0, figma_rest_api_1.getHeaders)(accessToken) })
+        .post(`${baseApiUrl}/code_connect/preview_snippets?file_key=${fileKey}`, {
+        nodeIds: chunkNodeIds,
+        figmaDocs: { all: chunkTemplates },
+        ...(renderCombinations && Object.keys(renderCombinations).length > 0
+            ? { renderCombinations }
+            : {}),
+    }, { headers: (0, figma_rest_api_1.getHeaders)(accessToken) })
         .then((response) => ({ chunkNodeIds, response, error: null }))
         .catch((err) => ({ chunkNodeIds, response: null, error: err }));
 }
-function chunkOutcomeToResults(outcome, nodes, fileKey) {
+/**
+ * Parse the offending property name out of a "property not found" render error,
+ * e.g. `PropertyNotFoundError: property 'Varient' not found` -> `Varient`.
+ */
+function parseMissingProperty(error) {
+    if (!error)
+        return undefined;
+    const match = error.match(/propert(?:y|ies)[^'"`]*['"`]([^'"`]+)['"`]/i) ?? error.match(/['"`]([^'"`]+)['"`]/);
+    return match?.[1];
+}
+/** Build `errorDetails` for a failed result. Undefined when there's no property context (not --all). */
+function buildErrorDetails(error, errorKind, availableProperties) {
+    // Transport failure: network/backend problem, not a bad property — carry only the kind.
+    if (errorKind === 'transport')
+        return { kind: 'transport' };
+    if (!availableProperties)
+        return undefined;
+    const details = { availableProperties };
+    if (errorKind)
+        details.kind = errorKind;
+    const missingProperty = parseMissingProperty(error);
+    if (missingProperty)
+        details.missingProperty = missingProperty;
+    return details;
+}
+function chunkOutcomeToResults(outcome, nodes, fileKey, availablePropsByNodeId) {
     const { chunkNodeIds, response, error } = outcome;
     const results = [];
     if (error) {
@@ -311,6 +514,8 @@ function chunkOutcomeToResults(outcome, nodes, fileKey) {
                         filePath: node.filePath,
                         success: false,
                         error: errorMsg,
+                        // Chunk-level failure is a server/network error, not a template problem.
+                        errorDetails: { kind: 'transport' },
                     });
                 }
             }
@@ -321,39 +526,61 @@ function chunkOutcomeToResults(outcome, nodes, fileKey) {
         // Track match index per nodeId so duplicate node IDs get the correct file attribution.
         // The server returns results in the same order as the templates we sent. Each chunk's
         // nodeIds are disjoint (we dedupe before chunking), so per-chunk indexing is correct.
+        // Property-combination results are expanded renders of one node, not one result per
+        // matching template, so they should not consume this per-template index.
         const nodeMatchIndex = {};
         for (const result of response.data.meta.results) {
             const idx = nodeMatchIndex[result.nodeId] ?? 0;
             const matchingNodes = nodes.filter((n) => n.nodeId === result.nodeId);
-            const node = matchingNodes[idx] || matchingNodes[0];
-            nodeMatchIndex[result.nodeId] = idx + 1;
+            const node = result.propertyCombinationLabel
+                ? matchingNodes[0]
+                : matchingNodes[idx] || matchingNodes[0];
+            if (!result.propertyCombinationLabel) {
+                nodeMatchIndex[result.nodeId] = idx + 1;
+            }
+            const error = result.error || (!result.snippet ? 'No snippet returned by server' : undefined);
+            const success = !result.error && !!result.snippet;
             results.push({
                 url: node?.url || result.nodeUrl,
                 nodeId: result.nodeId,
                 filePath: node?.filePath || '',
-                success: !result.error && !!result.snippet,
+                success,
                 snippet: result.snippet,
                 language: result.language,
                 component: result.component,
-                error: result.error || (!result.snippet ? 'No snippet returned by server' : undefined),
+                error,
+                ...(result.propertyCombinationLabel
+                    ? { propertyCombinationLabel: result.propertyCombinationLabel }
+                    : {}),
+                ...(result.unresolvedInstances?.length
+                    ? { unresolvedInstances: result.unresolvedInstances }
+                    : {}),
+                ...(success
+                    ? {}
+                    : {
+                        errorDetails: buildErrorDetails(error, result.errorKind, availablePropsByNodeId?.[result.nodeId]),
+                    }),
             });
         }
         return results;
     }
     for (const nodeId of chunkNodeIds) {
         for (const node of nodes.filter((n) => n.nodeId === nodeId)) {
+            const error = `API request failed with status ${response.response.status}`;
             results.push({
                 url: node.url,
                 nodeId: node.nodeId,
                 filePath: node.filePath,
                 success: false,
-                error: `API request failed with status ${response.response.status}`,
+                error,
+                // Non-2xx from the endpoint is a transport-level failure, not a template problem.
+                errorDetails: { kind: 'transport' },
             });
         }
     }
     return results;
 }
-async function previewFile({ fileKey, nodes, baseApiUrl, accessToken, dir, allCodeConnectObjects, }) {
+async function previewFile({ fileKey, nodes, baseApiUrl, accessToken, dir, allCodeConnectObjects, propertyCombinationsByNodeId, availablePropsByNodeId, }) {
     const allNodeIds = nodes.map((n) => n.nodeId);
     // Deduplicate — multiple figma.connect() calls may share the same nodeId;
     // the individual templates are sent in figmaDocs and the server iterates per-template.
@@ -362,9 +589,183 @@ async function previewFile({ fileKey, nodes, baseApiUrl, accessToken, dir, allCo
     // for the same nodeId exist on the server and shouldn't be rendered individually.
     const requestedFilePaths = new Set(nodes.map((n) => path_1.default.resolve(dir, n.filePath)));
     const requiredTemplates = filterTemplatesForNodes(allNodeIds, allCodeConnectObjects).filter((t) => requestedFilePaths.has(path_1.default.resolve(t._codeConnectFilePath || '')));
-    const chunks = chunkArray(nodeIds, PREVIEW_CHUNK_SIZE);
-    const outcomes = await runInWaves(chunks, (chunkNodeIds) => sendPreviewChunk({ chunkNodeIds, requiredTemplates, baseApiUrl, fileKey, accessToken }), PREVIEW_MAX_CONCURRENCY);
-    return outcomes.flatMap((outcome) => chunkOutcomeToResults(outcome, nodes, fileKey));
+    const chunks = chunkNodeIdsForPreview(nodeIds, propertyCombinationsByNodeId);
+    const outcomes = await runInWaves(chunks, (chunkNodeIds) => sendPreviewChunk({
+        chunkNodeIds,
+        requiredTemplates,
+        baseApiUrl,
+        fileKey,
+        accessToken,
+        propertyCombinationsByNodeId,
+    }), PREVIEW_MAX_CONCURRENCY);
+    return outcomes.flatMap((outcome) => chunkOutcomeToResults(outcome, nodes, fileKey, availablePropsByNodeId));
+}
+function collectAllLocalNodesToPreview(allCodeConnectObjects, dir, cmd) {
+    const nodesToCheck = [];
+    for (const doc of allCodeConnectObjects) {
+        const parsed = (0, validation_1.parseFigmaNode)(cmd.verbose, doc, true);
+        if (parsed) {
+            nodesToCheck.push({
+                fileKey: parsed.fileKey,
+                nodeId: parsed.nodeId,
+                url: doc.figmaNode,
+                filePath: path_1.default.relative(dir, doc._codeConnectFilePath || ''),
+            });
+        }
+    }
+    return nodesToCheck;
+}
+function groupNodesByFileKey(nodes) {
+    const nodesByFileKey = {};
+    for (const node of nodes) {
+        nodesByFileKey[node.fileKey] ??= [];
+        nodesByFileKey[node.fileKey].push(node);
+    }
+    return nodesByFileKey;
+}
+async function handleInspect({ nodesByFileKey, configuredApiUrl, accessToken, outputFormat, }) {
+    const items = [];
+    const seen = new Set();
+    for (const [fileKey, nodes] of Object.entries(nodesByFileKey)) {
+        const baseApiUrl = (0, figma_rest_api_1.getApiUrl)(nodes[0].url, configuredApiUrl);
+        for (const node of nodes) {
+            const dedupeKey = `${node.filePath}::${node.nodeId}`;
+            if (seen.has(dedupeKey))
+                continue;
+            seen.add(dedupeKey);
+            const result = await fetchComponentPropertyDefinitions(baseApiUrl, fileKey, node.nodeId, accessToken);
+            if (result.status === 'error') {
+                logging_1.logger.warn(`Couldn't fetch property definitions for node ${node.nodeId}`);
+            }
+            else if (result.status === 'empty') {
+                logging_1.logger.info(`Node ${node.nodeId} has no component properties or variants.`);
+            }
+            items.push({
+                filePath: node.filePath,
+                nodeId: node.nodeId,
+                availableProperties: result.status === 'ok' ? (0, property_combinations_1.toAvailableProperties)(result.defs) : [],
+            });
+        }
+    }
+    if (outputFormat === 'json') {
+        console.log(JSON.stringify(items, null, 2));
+    }
+    else {
+        (0, property_list_table_1.displayPropertyList)(items);
+    }
+}
+function validatePreviewOptions(cmd) {
+    if (cmd.all && cmd.props) {
+        (0, logging_1.exitWithError)('Cannot combine --props and --all; use one or the other');
+    }
+    if (cmd.maxCombinations !== undefined && !cmd.all) {
+        (0, logging_1.exitWithError)('--max-combinations can only be used with --all');
+    }
+}
+async function buildPropertyPreviewInputs({ enabled, baseApiUrl, fileKey, nodes, accessToken, propsPairs, maxCombinations, }) {
+    if (!enabled)
+        return {};
+    const propertyCombinationsByNodeId = {};
+    const availablePropsByNodeId = {};
+    for (const nodeId of [...new Set(nodes.map((n) => n.nodeId))]) {
+        const result = await fetchComponentPropertyDefinitions(baseApiUrl, fileKey, nodeId, accessToken);
+        if (result.status === 'error') {
+            logging_1.logger.warn(`Couldn't fetch property definitions for node ${nodeId} (ensure your token has the ` +
+                `Code Connect: Write and File content: Read scopes); rendering its default property combination only`);
+            continue;
+        }
+        if (result.status === 'empty') {
+            // Not an error: the component simply has no properties or variants to vary.
+            if (propsPairs) {
+                logging_1.logger.warn(`Node ${nodeId} has no component properties or variants, so --props ` +
+                    `(${propsPairs.map((p) => p.name).join(', ')}) has no effect; rendering its only property combination.`);
+            }
+            else {
+                logging_1.logger.info(`Node ${nodeId} has no component properties or variants to vary; rendering its only property combination.`);
+            }
+            continue;
+        }
+        const defs = result.defs;
+        if (propsPairs) {
+            const { propertyCombination, availableProperties, unknown, invalid, ambiguous } = (0, property_combinations_1.buildPropertyCombinationFromProps)(defs, propsPairs);
+            if (unknown.length > 0) {
+                logging_1.logger.warn(`Unknown propert${unknown.length > 1 ? 'ies' : 'y'} for node ${nodeId}: ${unknown.join(', ')}. ` +
+                    `Available: ${availableProperties.map((p) => p.name).join(', ')}`);
+            }
+            for (const { name, value, options } of invalid) {
+                logging_1.logger.warn(`"${value}" is not a valid value for ${name} on node ${nodeId}. Options: ${options.join(', ')}`);
+            }
+            for (const { name, types } of ambiguous) {
+                logging_1.logger.warn(`Property "${name}" on node ${nodeId} matches multiple types (${types.join(', ')}); ` +
+                    `prefix the value with a type to disambiguate, e.g. ${types[0]}:${name}=... . Skipping.`);
+            }
+            availablePropsByNodeId[nodeId] = availableProperties;
+            propertyCombinationsByNodeId[nodeId] = [propertyCombination];
+        }
+        else {
+            const { propertyCombinations, availableProperties, truncated } = (0, property_combinations_1.enumeratePropertyCombinations)(defs, {
+                maxCombinations,
+            });
+            availablePropsByNodeId[nodeId] = availableProperties;
+            if (truncated) {
+                logging_1.logger.warn(`Node ${nodeId} has ${truncated.total} property combinations, exceeding the ${truncated.cap}-combination ` +
+                    `preview limit; rendering the first ${truncated.cap}. Use --props to preview a ` +
+                    `specific property combination.`);
+            }
+            if (propertyCombinations.length > 0) {
+                propertyCombinationsByNodeId[nodeId] = propertyCombinations;
+            }
+        }
+    }
+    return { propertyCombinationsByNodeId, availablePropsByNodeId };
+}
+async function previewNodesForFile({ fileKey, nodes, configuredApiUrl, accessToken, dir, allCodeConnectObjects, renderPropertyCombinations, propsPairs, maxCombinations, }) {
+    const baseApiUrl = (0, figma_rest_api_1.getApiUrl)(nodes[0].url, configuredApiUrl);
+    const { propertyCombinationsByNodeId, availablePropsByNodeId } = await buildPropertyPreviewInputs({
+        enabled: renderPropertyCombinations,
+        baseApiUrl,
+        fileKey,
+        nodes,
+        accessToken,
+        propsPairs,
+        maxCombinations,
+    });
+    return previewFile({
+        fileKey,
+        nodes,
+        baseApiUrl,
+        accessToken,
+        dir,
+        allCodeConnectObjects,
+        propertyCombinationsByNodeId,
+        availablePropsByNodeId,
+    });
+}
+async function validateRenderedSnippets(results) {
+    for (const result of results) {
+        if (result.success && result.snippet) {
+            const prettierValid = await isPrettierParseable(result.snippet, result.language);
+            if (!prettierValid) {
+                // Prettier can parse this language but failed — mark as error
+                result.success = false;
+                result.error = 'Snippet has syntax errors and may not be valid code';
+            }
+        }
+    }
+}
+async function outputPreviewResults(results, outputFormat) {
+    if (outputFormat === 'json') {
+        console.log(JSON.stringify(results, null, 2));
+        return;
+    }
+    const formattedResults = await Promise.all(results.map(async (result) => {
+        if (result.success && result.snippet) {
+            const formattedSnippet = await formatSnippet(result.snippet, result.language);
+            return { ...result, snippet: formattedSnippet };
+        }
+        return result;
+    }));
+    displayResults(formattedResults);
 }
 /**
  * Handle the preview command
@@ -375,75 +776,51 @@ async function handlePreview(files, cmd) {
     const projectInfo = await (0, project_1.getProjectInfo)(dir, cmd.config);
     const accessToken = (0, connect_1.getAccessTokenOrExit)(cmd);
     const outputFormat = cmd.output || 'table';
-    const allCodeConnectObjects = await (0, connect_1.getCodeConnectObjects)(cmd, projectInfo, true);
-    let nodesToCheck;
-    if (files && files.length > 0) {
-        nodesToCheck = await collectNodesToPreview(files, allCodeConnectObjects, dir, cmd);
+    const configuredApiUrl = cmd.apiUrl || projectInfo.config.apiUrl;
+    if (cmd.all && (!files || files.length === 0)) {
+        (0, logging_1.exitWithError)('--all requires a specific component, e.g. `figma connect preview Button.figma.ts --all`');
     }
-    else {
+    const allCodeConnectObjects = await (0, connect_1.getCodeConnectObjects)(cmd, projectInfo, true);
+    const nodesToCheck = files && files.length > 0
+        ? await collectNodesToPreview(files, allCodeConnectObjects, dir, cmd)
+        : collectAllLocalNodesToPreview(allCodeConnectObjects, dir, cmd);
+    if (!files || files.length === 0) {
         logging_1.logger.info('Previewing all local Code Connect files...');
-        nodesToCheck = [];
-        for (const doc of allCodeConnectObjects) {
-            const parsed = (0, validation_1.parseFigmaNode)(cmd.verbose, doc, true);
-            if (parsed) {
-                nodesToCheck.push({
-                    fileKey: parsed.fileKey,
-                    nodeId: parsed.nodeId,
-                    url: doc.figmaNode,
-                    filePath: path_1.default.relative(dir, doc._codeConnectFilePath || ''),
-                });
-            }
-        }
     }
     if (nodesToCheck.length === 0) {
         (0, logging_1.exitWithError)('No valid Code Connect files found to preview');
     }
     logging_1.logger.info(`Previewing ${nodesToCheck.length} component(s)...`);
-    // Group nodes by fileKey for batching
-    const nodesByFileKey = {};
-    for (const node of nodesToCheck) {
-        if (!nodesByFileKey[node.fileKey]) {
-            nodesByFileKey[node.fileKey] = [];
-        }
-        nodesByFileKey[node.fileKey].push(node);
+    const nodesByFileKey = groupNodesByFileKey(nodesToCheck);
+    if (cmd.inspect) {
+        await handleInspect({
+            nodesByFileKey,
+            configuredApiUrl,
+            accessToken,
+            outputFormat,
+        });
+        return;
     }
+    validatePreviewOptions(cmd);
+    const maxCombinations = parseMaxCombinationsArg(cmd.maxCombinations);
+    const propsPairs = cmd.props ? parsePropsArg(cmd.props) : undefined;
     const results = [];
     for (const [fileKey, nodes] of Object.entries(nodesByFileKey)) {
-        const baseApiUrl = (0, figma_rest_api_1.getApiUrl)(nodes[0].url, cmd.apiUrl || projectInfo.config.apiUrl);
-        const fileResults = await previewFile({
+        const fileResults = await previewNodesForFile({
             fileKey,
             nodes,
-            baseApiUrl,
+            configuredApiUrl,
             accessToken,
             dir,
             allCodeConnectObjects,
+            renderPropertyCombinations: cmd.all || !!propsPairs,
+            propsPairs,
+            maxCombinations,
         });
         results.push(...fileResults);
     }
-    // Validate snippet syntax
-    for (const result of results) {
-        if (result.success && result.snippet) {
-            const prettierValid = await isPrettierParseable(result.snippet, result.language);
-            if (!prettierValid) {
-                // Prettier can parse this language but failed — mark as error
-                result.success = false;
-                result.error = 'Snippet has syntax errors and may not be valid code';
-            }
-        }
-    }
-    if (outputFormat === 'json') {
-        console.log(JSON.stringify(results, null, 2));
-    }
-    else {
-        const formattedResults = await Promise.all(results.map(async (result) => {
-            if (result.success && result.snippet) {
-                const formattedSnippet = await formatSnippet(result.snippet, result.language);
-                return { ...result, snippet: formattedSnippet };
-            }
-            return result;
-        }));
-        displayResults(formattedResults);
-    }
+    await validateRenderedSnippets(results);
+    await outputPreviewResults(results, outputFormat);
     if (results.every((r) => !r.success)) {
         process.exit(1);
     }