handoff-app 1.1.3 → 1.2.0-1

package/dist/pipeline/patterns.js

@@ -0,0 +1,21 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPatterns = void 0;
+const builder_1 = require("../transformers/preview/pattern/builder");
+/**
+ * Builds pattern previews by composing pre-built component preview HTML.
+ * Must be called AFTER buildComponents.
+ */
+const buildPatterns = (handoff, options) => __awaiter(void 0, void 0, void 0, function* () {
+    yield (0, builder_1.processPatterns)(handoff, options);
+});
+exports.buildPatterns = buildPatterns;

package/dist/transformers/docgen/index.js

@@ -225,8 +225,18 @@ exports.enrichPropertiesWithDocgen = enrichPropertiesWithDocgen;
 const generateDocsArtifact = (entry, handoff) => __awaiter(void 0, void 0, void 0, function* () {
     try {
         const tsconfigPath = path_1.default.resolve(handoff.workingPath, 'tsconfig.json');
-        if (!fs_extra_1.default.existsSync(tsconfigPath)) {
-            logger_1.Logger.warn(`TypeScript config not found at ${tsconfigPath}, using default resolution`);
+        const hasTsconfig = fs_extra_1.default.existsSync(tsconfigPath);
+        const entryExtension = path_1.default.extname(entry).toLowerCase();
+        const isJavaScriptEntry = ['.js', '.jsx', '.cjs', '.mjs'].includes(entryExtension);
+        if (!hasTsconfig) {
+            // For JS-only projects, handoff-docgen currently expects a tsconfig and will fail noisily.
+            // Skip docgen gracefully in this case.
+            if (isJavaScriptEntry) {
+                logger_1.Logger.debug(`Skipping handoff-docgen for ${entry}: no tsconfig.json found in ${handoff.workingPath}`);
+                return null;
+            }
+            logger_1.Logger.warn(`TypeScript config not found at ${tsconfigPath}; skipping docs generation for ${entry}.`);
+            return null;
         }
         const componentDirectory = path_1.default.dirname(path_1.default.resolve(entry));
         const { maxDepth, excludeDirectories } = getDocgenConfig(handoff);

package/dist/transformers/plugins/csf-render.js

@@ -18,13 +18,16 @@ const lodash_1 = require("lodash");
 const path_1 = __importDefault(require("path"));
 const react_1 = __importDefault(require("react"));
 const server_1 = __importDefault(require("react-dom/server"));
+const react_element_to_jsx_string_1 = __importDefault(require("react-element-to-jsx-string"));
 const logger_1 = require("../../utils/logger");
+const docgen_1 = require("../docgen");
 const component_1 = require("../preview/component");
 const html_1 = require("../utils/html");
 const module_1 = require("../utils/module");
 const schema_1 = require("../utils/schema");
+const usage_1 = require("../utils/usage");
+const csf_1 = require("../utils/csf");
 const vite_logger_1 = require("../utils/vite-logger");
-const docgen_1 = require("../docgen");
 const PLUGIN_CONSTANTS = {
     PLUGIN_NAME: 'vite-plugin-csf-render',
     SCRIPT_ID: 'script',
@@ -75,17 +78,6 @@ function createSlotMetadata(key, argType, value) {
         },
     };
 }
-function getStoryEntries(moduleExports) {
-    return Object.entries(moduleExports).filter(([key, value]) => {
-        if (key === 'default' || key === '__esModule')
-            return false;
-        if (typeof value === 'function')
-            return true;
-        if (value && typeof value === 'object')
-            return true;
-        return false;
-    });
-}
 function toReactElement(renderResult, meta, args) {
     if (react_1.default.isValidElement(renderResult)) {
         return renderResult;
@@ -101,23 +93,147 @@ function toReactElement(renderResult, meta, args) {
     }
     return react_1.default.createElement('pre', null, JSON.stringify(args, null, 2));
 }
+/**
+ * Produces the React element for a story, mirroring Storybook's resolution order:
+ * story render > meta render > meta.component > JSON fallback.
+ */
+function getStoryElement(meta, story, args) {
+    const storyRender = typeof story === 'function' ? story : story === null || story === void 0 ? void 0 : story.render;
+    const render = storyRender || meta.render;
+    if (render) {
+        return toReactElement(render(args), meta, args);
+    }
+    if (meta.component) {
+        return react_1.default.createElement(meta.component, args);
+    }
+    return react_1.default.createElement('pre', null, JSON.stringify(args, null, 2));
+}
 function safeRenderToHtml(meta, story, args) {
     try {
-        const storyRender = typeof story === 'function' ? story : story.render;
-        const render = storyRender || meta.render;
-        if (render) {
-            return server_1.default.renderToString(toReactElement(render(args), meta, args));
-        }
-        if (meta.component) {
-            return server_1.default.renderToString(react_1.default.createElement(meta.component, args));
-        }
-        return server_1.default.renderToString(react_1.default.createElement('pre', null, JSON.stringify(args, null, 2)));
+        return server_1.default.renderToString(getStoryElement(meta, story, args));
     }
     catch (error) {
         logger_1.Logger.warn(`SSR render failed for story, falling back to static placeholder: ${error}`);
         return `<div style="padding:1rem;color:#b91c1c;font-family:monospace;font-size:13px">Render error: ${String(error)}</div>`;
     }
 }
+/**
+ * Converts a story's React element into a JSX source string using the same
+ * approach as Storybook's Docs addon.
+ */
+function reactElementToUsage(element) {
+    try {
+        return (0, react_element_to_jsx_string_1.default)(element, {
+            sortProps: false,
+            useBooleanShorthandSyntax: true,
+            useFragmentShortSyntax: true,
+            maxInlineAttributesLineLength: 80,
+        });
+    }
+    catch (error) {
+        logger_1.Logger.warn(`Failed to convert React element to JSX string: ${error}`);
+        return null;
+    }
+}
+function findMatchingBrace(source, openIndex) {
+    let depth = 0;
+    for (let i = openIndex; i < source.length; i += 1) {
+        const char = source[i];
+        if (char === '{')
+            depth += 1;
+        if (char === '}') {
+            depth -= 1;
+            if (depth === 0) {
+                return i;
+            }
+        }
+    }
+    return -1;
+}
+function extractMetaObjectBody(sourceCode) {
+    // TODO: Regex-based CSF meta parsing can miss complex inline `satisfies` cases.
+    // Move this to a TS-AST resolver in handoff-docgen and consume the normalized import info here.
+    const inlineMetaMatch = sourceCode.match(/export\s+default\s+({[\s\S]*?})\s*(?:satisfies\s+[^{;\n]+|as\s+[^{;\n]+)?\s*;/m);
+    if (inlineMetaMatch === null || inlineMetaMatch === void 0 ? void 0 : inlineMetaMatch[1]) {
+        return inlineMetaMatch[1];
+    }
+    const exportedMetaRef = sourceCode.match(/export\s+default\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*;/m);
+    if (!(exportedMetaRef === null || exportedMetaRef === void 0 ? void 0 : exportedMetaRef[1])) {
+        return null;
+    }
+    const metaVarName = exportedMetaRef[1];
+    const declarationPatterns = [
+        new RegExp(`(?:const|let|var)\\s+${metaVarName}\\s*=\\s*`, 'm'),
+        new RegExp(`(?:const|let|var)\\s+${metaVarName}\\s*=\\s*[^\\n;]*?\\b(?:satisfies|as)\\b[^\\n;]*?`, 'm'),
+    ];
+    for (const pattern of declarationPatterns) {
+        const match = pattern.exec(sourceCode);
+        if (!match)
+            continue;
+        const openIndex = sourceCode.indexOf('{', match.index);
+        if (openIndex === -1)
+            continue;
+        const closeIndex = findMatchingBrace(sourceCode, openIndex);
+        if (closeIndex === -1)
+            continue;
+        return sourceCode.slice(openIndex, closeIndex + 1);
+    }
+    return null;
+}
+function resolveComponentImportInfo(sourceCode) {
+    const metaBody = extractMetaObjectBody(sourceCode);
+    if (!metaBody) {
+        return null;
+    }
+    const componentMatch = metaBody.match(/\bcomponent\s*:\s*([A-Za-z_$][A-Za-z0-9_$]*)\b/m);
+    if (!(componentMatch === null || componentMatch === void 0 ? void 0 : componentMatch[1])) {
+        return null;
+    }
+    const localName = componentMatch[1];
+    const defaultImportMatch = sourceCode.match(new RegExp(`import\\s+${localName}\\s+from\\s+['"]([^'"]+)['"]`, 'm'));
+    if (defaultImportMatch === null || defaultImportMatch === void 0 ? void 0 : defaultImportMatch[1]) {
+        return {
+            componentName: localName,
+            importStatement: `import ${localName} from '${defaultImportMatch[1]}';`,
+        };
+    }
+    const namedImportRegex = /import\s*{\s*([^}]+)\s*}\s*from\s*['"]([^'"]+)['"]/gm;
+    for (const match of sourceCode.matchAll(namedImportRegex)) {
+        const specifiers = match[1]
+            .split(',')
+            .map((specifier) => specifier.trim())
+            .filter(Boolean);
+        const moduleSpecifier = match[2];
+        for (const specifier of specifiers) {
+            const aliasMatch = specifier.match(/^([A-Za-z_$][A-Za-z0-9_$]*)\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*)$/);
+            if (aliasMatch && aliasMatch[2] === localName) {
+                return {
+                    componentName: localName,
+                    importStatement: `import { ${aliasMatch[1]} as ${localName} } from '${moduleSpecifier}';`,
+                };
+            }
+            if (specifier === localName) {
+                return {
+                    componentName: localName,
+                    importStatement: `import { ${localName} } from '${moduleSpecifier}';`,
+                };
+            }
+        }
+    }
+    return null;
+}
+function buildUsageSnippet(componentName, importStatement, element, properties, previewValues) {
+    const usageBody = element ? reactElementToUsage(element) : null;
+    if (usageBody) {
+        return `${importStatement}\n\n${usageBody}`;
+    }
+    return (0, usage_1.generateUsageSnippet)({
+        componentName,
+        properties,
+        previewValues,
+        importStatement,
+    });
+}
 function createHtmlDocument(componentId, previewTitle, renderedHtml) {
     var _a, _b, _c;
     return `<!DOCTYPE html>
@@ -172,24 +288,22 @@ function csfRenderPlugin(componentData, _documentationComponents, handoff) {
                     return;
                 }
                 const meta = (moduleExports.default || {});
-                const stories = getStoryEntries(moduleExports);
+                const stories = (0, csf_1.getCsfStoryEntries)(moduleExports);
+                const storyMap = Object.fromEntries(stories);
                 if (stories.length === 0) {
                     logger_1.Logger.warn(`No named stories found in CSF file for ${componentId}: ${templatePath}`);
                     return;
                 }
                 const explicitProperties = componentData.properties || {};
                 const generatedProperties = Object.assign({}, explicitProperties);
-                // Include all named stories as previews and infer properties from args/argTypes
-                componentData.previews = {};
+                const incomingPreviews = Object.assign({}, (componentData.previews || {}));
+                const patternPreviews = Object.fromEntries(Object.entries(incomingPreviews).filter(([key]) => key.startsWith('__pattern_')));
+                // Include all named stories as previews and preserve injected pattern previews.
+                componentData.previews = Object.assign(Object.assign({}, (0, csf_1.createCsfStoryPreviews)(moduleExports)), patternPreviews);
                 for (const [storyKey, storyValue] of stories) {
                     const storyObj = (typeof storyValue === 'function' ? {} : storyValue);
                     const mergedArgs = Object.assign(Object.assign({}, (meta.args || {})), (storyObj.args || {}));
                     const mergedArgTypes = Object.assign(Object.assign({}, (meta.argTypes || {})), (storyObj.argTypes || {}));
-                    componentData.previews[storyKey] = {
-                        title: storyObj.name || (0, lodash_1.startCase)(storyKey),
-                        values: mergedArgs,
-                        url: '',
-                    };
                     for (const [argKey, argValue] of Object.entries(mergedArgs)) {
                         if (!generatedProperties[argKey]) {
                             generatedProperties[argKey] = createSlotMetadata(argKey, mergedArgTypes[argKey], argValue);
@@ -204,6 +318,9 @@ function csfRenderPlugin(componentData, _documentationComponents, handoff) {
                 // Enrich with docgen: descend into array/object types (e.g. cards[].image, title, link)
                 const generatedDocs = yield (0, docgen_1.generateDocsArtifact)(templatePath, handoff);
                 const componentName = ((_a = meta.component) === null || _a === void 0 ? void 0 : _a.displayName) || ((_b = meta.component) === null || _b === void 0 ? void 0 : _b.name);
+                const componentImportInfo = resolveComponentImportInfo(sourceCode);
+                const usageComponentName = (componentImportInfo === null || componentImportInfo === void 0 ? void 0 : componentImportInfo.componentName) || componentName || (0, usage_1.extractComponentName)(templatePath);
+                const usageImportStatement = (componentImportInfo === null || componentImportInfo === void 0 ? void 0 : componentImportInfo.importStatement) || `import ${usageComponentName} from './${usageComponentName}';`;
                 if (generatedDocs && componentName) {
                     const docgenProperties = (0, docgen_1.getPropertiesForComponentFromDocs)(generatedDocs, componentName);
                     if (docgenProperties) {
@@ -242,11 +359,15 @@ function csfRenderPlugin(componentData, _documentationComponents, handoff) {
                 }
                 componentData.properties = (0, schema_1.ensureIds)(generatedProperties);
                 let lastHtml = '';
-                for (const [storyKey, storyValue] of stories) {
-                    const preview = componentData.previews[storyKey];
-                    const rendered = safeRenderToHtml(meta, storyValue, preview.values || {});
+                for (const [previewKey, preview] of Object.entries(componentData.previews)) {
+                    const storyKey = preview.sourcePreview && storyMap[preview.sourcePreview]
+                        ? preview.sourcePreview
+                        : (storyMap[previewKey] ? previewKey : undefined);
+                    const storyValue = storyKey ? storyMap[storyKey] : undefined;
+                    const storyArgs = preview.values || {};
+                    const rendered = safeRenderToHtml(meta, storyValue, storyArgs);
                     const html = yield (0, html_1.formatHtml)(createHtmlDocument(componentId, preview.title, rendered));
-                    const fileName = `${componentId}-${storyKey}.html`;
+                    const fileName = `${componentId}-${previewKey}.html`;
                     this.emitFile({
                         type: 'asset',
                         fileName,
@@ -254,9 +375,18 @@ function csfRenderPlugin(componentData, _documentationComponents, handoff) {
                     });
                     this.emitFile({
                         type: 'asset',
-                        fileName: `${componentId}-${storyKey}${PLUGIN_CONSTANTS.INSPECT_SUFFIX}.html`,
+                        fileName: `${componentId}-${previewKey}${PLUGIN_CONSTANTS.INSPECT_SUFFIX}.html`,
                         source: html,
                     });
+                    // Capture JSX usage for each story so docs can switch usage by selected preview.
+                    let storyElement = null;
+                    try {
+                        storyElement = getStoryElement(meta, storyValue, storyArgs);
+                    }
+                    catch (_f) {
+                        // Fall back to schema-based generation below.
+                    }
+                    preview.usage = buildUsageSnippet(usageComponentName, usageImportStatement, storyElement, componentData.properties || {}, storyArgs);
                     preview.url = fileName;
                     lastHtml = html;
                 }
@@ -264,6 +394,12 @@ function csfRenderPlugin(componentData, _documentationComponents, handoff) {
                 componentData.preview = '';
                 componentData.code = (0, html_1.trimPreview)(sourceCode);
                 componentData.html = (0, html_1.trimPreview)(lastHtml);
+                // Keep top-level usage for backwards compatibility (first preview usage).
+                const storyKeys = Object.keys(componentData.previews);
+                const firstStoryKey = storyKeys[0];
+                if (firstStoryKey) {
+                    componentData.usage = componentData.previews[firstStoryKey].usage || '';
+                }
             });
         },
     };

package/dist/transformers/plugins/ssr-render.js

@@ -26,6 +26,7 @@ const html_1 = require("../utils/html");
 const module_1 = require("../utils/module");
 const schema_loader_1 = require("../utils/schema-loader");
 const string_1 = require("../utils/string");
+const usage_1 = require("../utils/usage");
 const vite_logger_1 = require("../utils/vite-logger");
 /**
  * Constants for the SSR render plugin
@@ -187,7 +188,6 @@ function ssrRenderPlugin(componentData, documentationComponents, handoff) {
                 if (!documentationComponents) {
                     documentationComponents = {};
                 }
-                const generatedPreviews = {};
                 // Process component instances from documentation
                 // Use figmaComponentId if provided, otherwise skip implicit matching
                 if (componentData.figmaComponentId) {
@@ -200,6 +200,7 @@ function ssrRenderPlugin(componentData, documentationComponents, handoff) {
                                 title: variationId,
                                 url: '',
                                 values: instanceValues,
+                                usage: '',
                             };
                         }
                     }
@@ -254,8 +255,13 @@ function ssrRenderPlugin(componentData, documentationComponents, handoff) {
                         fileName: `${componentId}-${previewKey}${PLUGIN_CONSTANTS.INSPECT_SUFFIX}.html`,
                         source: finalHtml,
                     });
-                    generatedPreviews[previewKey] = finalHtml;
                     componentData.previews[previewKey].url = `${componentId}-${previewKey}.html`;
+                    componentData.previews[previewKey].usage = (0, usage_1.generateUsageSnippet)({
+                        componentName: (0, usage_1.extractComponentName)(componentPath),
+                        properties: componentData.properties || {},
+                        previewValues: previewProps || {},
+                        templateFileName: path_1.default.basename(componentPath),
+                    });
                 }
                 // Format final HTML and update component data
                 finalHtml = yield (0, html_1.formatHtml)(finalHtml);
@@ -263,6 +269,16 @@ function ssrRenderPlugin(componentData, documentationComponents, handoff) {
                 componentData.preview = '';
                 componentData.code = (0, html_1.trimPreview)(componentSourceCode);
                 componentData.html = (0, html_1.trimPreview)(finalHtml);
+                // Generate usage snippet from the first preview's values
+                const previewKeys = Object.keys(componentData.previews);
+                const firstPreviewValues = previewKeys.length > 0 ? componentData.previews[previewKeys[0]].values : {};
+                const componentName = (0, usage_1.extractComponentName)(componentPath);
+                componentData.usage = (0, usage_1.generateUsageSnippet)({
+                    componentName,
+                    properties: componentData.properties || {},
+                    previewValues: firstPreviewValues,
+                    templateFileName: path_1.default.basename(componentPath),
+                });
             });
         },
     };

package/dist/transformers/preview/component/api.js

@@ -15,6 +15,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.readComponentMetadataApi = exports.readComponentApi = exports.updateComponentSummaryApi = exports.writeComponentApi = exports.getAPIPath = void 0;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
+const previews_1 = require("./previews");
+const sanitizeComponentApiData = (component) => {
+    if (!component)
+        return component;
+    const sanitized = Object.assign(Object.assign({}, component), { previews: (0, previews_1.getDocumentedPreviews)(component.previews) });
+    delete sanitized.internalPatternPreviews;
+    return sanitized;
+};
 /**
  * Merges values from a source object into a target object, returning a new object.
  * For each key present in either object:
@@ -66,15 +74,16 @@ const writeComponentSummaryAPI = (handoff, componentData) => __awaiter(void 0, v
 const writeComponentApi = (id_1, component_1, handoff_1, ...args_1) => __awaiter(void 0, [id_1, component_1, handoff_1, ...args_1], void 0, function* (id, component, handoff, preserveKeys = []) {
     const outputDirPath = path_1.default.resolve((0, exports.getAPIPath)(handoff), 'component');
     const outputFilePath = path_1.default.resolve(outputDirPath, `${id}.json`);
+    const sanitizedComponent = sanitizeComponentApiData(component);
     if (fs_extra_1.default.existsSync(outputFilePath)) {
         const existingJson = yield fs_extra_1.default.readFile(outputFilePath, 'utf8');
         if (existingJson) {
             try {
-                const existingData = JSON.parse(existingJson);
+                const existingData = sanitizeComponentApiData(JSON.parse(existingJson));
                 // Special case: always allow page to be cleared when undefined
                 // This handles the case where page slices are removed
-                const finalPreserveKeys = component.page === undefined ? preserveKeys.filter((key) => key !== 'page') : preserveKeys;
-                const mergedData = updateObject(existingData, component, finalPreserveKeys);
+                const finalPreserveKeys = sanitizedComponent.page === undefined ? preserveKeys.filter((key) => key !== 'page') : preserveKeys;
+                const mergedData = sanitizeComponentApiData(updateObject(existingData, sanitizedComponent, finalPreserveKeys));
                 yield fs_extra_1.default.writeFile(outputFilePath, JSON.stringify(mergedData, null, 2));
                 return;
             }
@@ -86,7 +95,7 @@ const writeComponentApi = (id_1, component_1, handoff_1, ...args_1) => __awaiter
     if (!fs_extra_1.default.existsSync(outputDirPath)) {
         fs_extra_1.default.mkdirSync(outputDirPath, { recursive: true });
     }
-    yield fs_extra_1.default.writeFile(outputFilePath, JSON.stringify(component, null, 2));
+    yield fs_extra_1.default.writeFile(outputFilePath, JSON.stringify(sanitizedComponent, null, 2));
 });
 exports.writeComponentApi = writeComponentApi;
 /**
@@ -106,7 +115,7 @@ const updateComponentSummaryApi = (handoff_1, componentData_1, ...args_1) => __a
     if (fs_extra_1.default.existsSync(apiPath)) {
         try {
             const existing = yield fs_extra_1.default.readFile(apiPath, 'utf8');
-            existingData = JSON.parse(existing);
+            existingData = JSON.parse(existing).map((component) => (Object.assign(Object.assign({}, component), { previews: (0, previews_1.getDocumentedPreviews)(component.previews) })));
         }
         catch (_a) {
             // Corrupt or missing JSON — treat as empty
@@ -132,7 +141,7 @@ const readComponentApi = (handoff, id) => __awaiter(void 0, void 0, void 0, func
         try {
             const existingJson = yield fs_extra_1.default.readFile(outputFilePath, 'utf8');
             if (existingJson) {
-                return JSON.parse(existingJson);
+                return sanitizeComponentApiData(JSON.parse(existingJson));
             }
         }
         catch (_) {
@@ -166,7 +175,7 @@ const readComponentMetadataApi = (handoff, id) => __awaiter(void 0, void 0, void
         categories: componentData.categories ? componentData.categories : [],
         tags: componentData.tags ? componentData.tags : [],
         properties: componentData.properties,
-        previews: componentData.previews,
+        previews: (0, previews_1.getDocumentedPreviews)(componentData.previews),
         path: `/api/component/${id}.json`,
     };
 });

package/dist/transformers/preview/component/builder.js

@@ -27,10 +27,12 @@ exports.ComponentSegment = void 0;
 exports.processComponents = processComponents;
 const cloneDeep_1 = __importDefault(require("lodash/cloneDeep"));
 const cache_1 = require("../../../cache");
+const duration_1 = require("../../../utils/duration");
 const logger_1 = require("../../../utils/logger");
 const schema_1 = require("../../utils/schema");
 const types_1 = require("../types");
 const api_1 = require("./api");
+const previews_1 = require("./previews");
 const css_1 = __importDefault(require("./css"));
 const html_1 = __importDefault(require("./html"));
 const javascript_1 = __importDefault(require("./javascript"));
@@ -79,6 +81,40 @@ const ensureDefaultPreview = (data) => {
         };
     }
 };
+const getBuildPreviews = (data) => {
+    return Object.assign(Object.assign({}, ((data === null || data === void 0 ? void 0 : data.previews) || {})), ((data === null || data === void 0 ? void 0 : data.internalPatternPreviews) || {}));
+};
+/** Vite-backed segments in execution order; extend here if new steps are added. */
+const VITE_BUILD_SEGMENTS = [
+    { key: 'js', label: 'script' },
+    { key: 'css', label: 'styles' },
+    { key: 'previews', label: 'previews' },
+];
+const isFullViteComponentBuild = (plan) => plan.js && plan.css && plan.previews;
+const getActiveViteBuildLabels = (plan) => VITE_BUILD_SEGMENTS.filter(({ key }) => plan[key]).map(({ label }) => label);
+/** e.g. "a", "a and b", "a, b, and c" — common CLI copy style. */
+const formatEnglishList = (items) => {
+    if (items.length === 0)
+        return '';
+    if (items.length === 1)
+        return items[0];
+    if (items.length === 2)
+        return `${items[0]} and ${items[1]}`;
+    return `${items.slice(0, -1).join(', ')}, and ${items[items.length - 1]}`;
+};
+const viteBuildStartMessage = (componentId, plan) => {
+    if (isFullViteComponentBuild(plan)) {
+        return `Building component "${componentId}"…`;
+    }
+    return `Building ${formatEnglishList(getActiveViteBuildLabels(plan))} for component "${componentId}"…`;
+};
+const viteBuildFinishMessage = (componentId, plan, elapsedMs) => {
+    const duration = (0, duration_1.formatDurationMs)(elapsedMs);
+    if (isFullViteComponentBuild(plan)) {
+        return `Finished building component "${componentId}" in ${duration}`;
+    }
+    return `Finished building ${formatEnglishList(getActiveViteBuildLabels(plan))} for component "${componentId}" in ${duration}`;
+};
 /**
  * Returns a normalized build plan describing which component segments need rebuilding.
  *
@@ -166,12 +202,17 @@ function processComponents(handoff, id, segmentToProcess, options) {
             if (cache) {
                 (0, cache_1.pruneRemovedComponents)(cache, allComponentIds);
             }
-            const skippedCount = allComponentIds.length - componentsToBuild.size;
-            if (skippedCount > 0) {
-                logger_1.Logger.info(`Building ${componentsToBuild.size} of ${allComponentIds.length} components (${skippedCount} unchanged)`);
+            const total = allComponentIds.length;
+            const toBuildCount = componentsToBuild.size;
+            const skippedCount = total - toBuildCount;
+            if (total > 0 && toBuildCount === 0) {
+                logger_1.Logger.info(`All ${total} components unchanged; skipping build`);
+            }
+            else if (skippedCount > 0 && toBuildCount > 0) {
+                logger_1.Logger.info(`Building ${toBuildCount} of ${total} components (${skippedCount} unchanged)`);
             }
-            else if (componentsToBuild.size > 0) {
-                logger_1.Logger.info(`Building all ${componentsToBuild.size} components`);
+            else if (toBuildCount > 0) {
+                logger_1.Logger.info(`Building all ${toBuildCount} components`);
             }
             else {
                 logger_1.Logger.info('All components up to date, nothing to build');
@@ -239,10 +280,11 @@ function processComponents(handoff, id, segmentToProcess, options) {
                     data.css = existingData.css;
                     data.sass = existingData.sass;
                 }
-                // If we're not building previews, preserve pre-existing HTML, code snippet, and previews.
+                // If we're not building previews, preserve pre-existing HTML, code snippet, usage, and previews.
                 if (!buildPlan.previews) {
                     data.html = existingData.html;
                     data.code = existingData.code;
+                    data.usage = existingData.usage;
                     data.previews = existingData.previews;
                 }
                 /**
@@ -261,6 +303,12 @@ function processComponents(handoff, id, segmentToProcess, options) {
             }
             // Components should always have at least one preview variation.
             ensureDefaultPreview(data);
+            const runsViteBuildSteps = buildPlan.js || buildPlan.css || buildPlan.previews;
+            let viteBuildStartedAtMs = 0;
+            if (runsViteBuildSteps) {
+                viteBuildStartedAtMs = Date.now();
+                logger_1.Logger.info(viteBuildStartMessage(runtimeComponentId, buildPlan));
+            }
             // Build JS if needed (new build, validation missing, or explicit segment request).
             if (buildPlan.js) {
                 data = yield (0, javascript_1.default)(data, handoff);
@@ -271,7 +319,11 @@ function processComponents(handoff, id, segmentToProcess, options) {
             }
             // Build previews (HTML, snapshots, etc) if needed.
             if (buildPlan.previews) {
-                data = yield (0, html_1.default)(data, handoff, components);
+                data = yield (0, html_1.default)(Object.assign(Object.assign({}, data), { previews: getBuildPreviews(data) }), handoff, components);
+            }
+            if (runsViteBuildSteps) {
+                const elapsedMs = Date.now() - viteBuildStartedAtMs;
+                logger_1.Logger.info(viteBuildFinishMessage(runtimeComponentId, buildPlan, elapsedMs));
             }
             /**
              * Run validation if explicitly requested and a hook is configured.
@@ -284,6 +336,7 @@ function processComponents(handoff, id, segmentToProcess, options) {
             // Ensure that every property within the properties array/object contains an 'id' field.
             // This guarantees unique identification for property entries, which is useful for updates and API consumers.
             data.properties = (0, schema_1.ensureIds)(data.properties);
+            data.previews = (0, previews_1.getDocumentedPreviews)(data.previews);
             // Write the updated component data to the API file for external access and caching.
             //console.log('data', data);
             yield (0, api_1.writeComponentApi)(runtimeComponentId, data, handoff, []);
@@ -337,7 +390,7 @@ const buildComponentSummary = (id, data) => {
         categories: data.categories ? data.categories : [],
         tags: data.tags ? data.tags : [],
         properties: data.properties,
-        previews: data.previews,
+        previews: (0, previews_1.getDocumentedPreviews)(data.previews),
         path: `${(_a = process.env.HANDOFF_APP_BASE_PATH) !== null && _a !== void 0 ? _a : ''}/api/component/${id}.json`,
     };
 };

package/dist/transformers/preview/component/css.d.ts

@@ -19,11 +19,15 @@ declare const buildComponentCss: (data: TransformComponentTokensResult, handoff:
     css?: string;
     sass?: string;
     sharedStyles?: string;
+    usage?: string;
     title?: string;
     description?: string;
     previews?: {
         [key: string]: import("../types").OptionalPreviewRender;
     };
+    internalPatternPreviews?: {
+        [key: string]: import("../types").OptionalPreviewRender;
+    };
     properties?: {
         [key: string]: import("../component").SlotMetadata;
     };
@@ -32,8 +36,12 @@ declare const buildComponentCss: (data: TransformComponentTokensResult, handoff:
         js?: string;
         scss?: string;
         template?: string;
+        component?: string;
+        story?: string;
         schema?: string;
+        templates?: string;
     };
+    renderer?: import("../../../index").RendererKind;
     options?: {
         preview?: {
             groupBy?: string;

package/dist/transformers/preview/component/css.js

@@ -17,6 +17,7 @@ const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const vite_1 = require("vite");
 const config_1 = require("../../../config");
+const duration_1 = require("../../../utils/duration");
 const logger_1 = require("../../../utils/logger");
 const vite_config_1 = __importDefault(require("../../vite-config"));
 const component_1 = require("../component");
@@ -155,9 +156,9 @@ const buildMainCss = (handoff) => __awaiter(void 0, void 0, void 0, function* ()
         const stat = yield fs_extra_1.default.stat(runtimeConfig.entries.scss);
         const entryPath = stat.isDirectory() ? path_1.default.resolve(runtimeConfig.entries.scss, 'main.scss') : runtimeConfig.entries.scss;
         if (entryPath === runtimeConfig.entries.scss || fs_extra_1.default.existsSync(entryPath)) {
-            logger_1.Logger.success(`Building main CSS file...`);
+            logger_1.Logger.info(`Building styles for global entry (main.css)…`);
+            const startedAt = Date.now();
             try {
-                // Setup SASS load paths
                 const loadPaths = [
                     path_1.default.resolve(handoff.workingPath),
                     path_1.default.resolve(handoff.workingPath, handoff.exportsDirectory, handoff.getProjectId()),
@@ -173,9 +174,10 @@ const buildMainCss = (handoff) => __awaiter(void 0, void 0, void 0, function* ()
                     loadPaths,
                     handoff,
                 });
+                logger_1.Logger.info(`Finished building styles for global entry (main.css) in ${(0, duration_1.formatDurationMs)(Date.now() - startedAt)}`);
             }
-            catch (e) {
-                logger_1.Logger.error(`Failed to build main CSS:`, e);
+            catch (_d) {
+                // buildCssBundle already logs failure for the entry path
             }
         }
     }