handoff-app 1.1.3 → 1.2.0-0

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

@@ -0,0 +1,61 @@
+"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());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncPatternArtifacts = exports.writePatternSummaryApi = exports.writePatternHtml = exports.writePatternApi = exports.getPatternAPIPath = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const getPatternAPIPath = (handoff) => {
+    const patternPath = path_1.default.resolve(handoff.workingPath, 'public/api/pattern');
+    if (!fs_extra_1.default.existsSync(patternPath)) {
+        fs_extra_1.default.mkdirSync(patternPath, { recursive: true });
+    }
+    return patternPath;
+};
+exports.getPatternAPIPath = getPatternAPIPath;
+const writePatternApi = (id, pattern, handoff) => __awaiter(void 0, void 0, void 0, function* () {
+    const outputDir = (0, exports.getPatternAPIPath)(handoff);
+    const outputFilePath = path_1.default.resolve(outputDir, `${id}.json`);
+    yield fs_extra_1.default.writeFile(outputFilePath, JSON.stringify(pattern, null, 2));
+});
+exports.writePatternApi = writePatternApi;
+const writePatternHtml = (id, html, handoff) => __awaiter(void 0, void 0, void 0, function* () {
+    const outputDir = (0, exports.getPatternAPIPath)(handoff);
+    const outputFilePath = path_1.default.resolve(outputDir, `${id}.html`);
+    yield fs_extra_1.default.writeFile(outputFilePath, html);
+});
+exports.writePatternHtml = writePatternHtml;
+const writePatternSummaryApi = (handoff, patterns) => __awaiter(void 0, void 0, void 0, function* () {
+    const apiPath = path_1.default.resolve(handoff.workingPath, 'public/api');
+    if (!fs_extra_1.default.existsSync(apiPath)) {
+        fs_extra_1.default.mkdirSync(apiPath, { recursive: true });
+    }
+    patterns.sort((a, b) => a.title.localeCompare(b.title));
+    yield fs_extra_1.default.writeFile(path_1.default.resolve(apiPath, 'patterns.json'), JSON.stringify(patterns, null, 2));
+});
+exports.writePatternSummaryApi = writePatternSummaryApi;
+const syncPatternArtifacts = (handoff, validIds) => __awaiter(void 0, void 0, void 0, function* () {
+    const validIdSet = new Set(validIds);
+    const patternPath = (0, exports.getPatternAPIPath)(handoff);
+    const entries = yield fs_extra_1.default.readdir(patternPath);
+    for (const entry of entries) {
+        const parsed = path_1.default.parse(entry);
+        const isPatternArtifact = parsed.ext === '.json' || parsed.ext === '.html';
+        if (!isPatternArtifact)
+            continue;
+        if (!validIdSet.has(parsed.name)) {
+            yield fs_extra_1.default.remove(path_1.default.resolve(patternPath, entry));
+        }
+    }
+});
+exports.syncPatternArtifacts = syncPatternArtifacts;

package/dist/transformers/preview/pattern/builder.d.ts

@@ -0,0 +1,9 @@
+import Handoff from '../../../index';
+import { PatternListObject } from '../types';
+/**
+ * Process all pattern declarations and compose their HTML from pre-built
+ * component preview files. This function must run AFTER buildComponents
+ * so that all component preview HTML files already exist on disk.
+ */
+export declare function processPatterns(handoff: Handoff): Promise<PatternListObject[]>;
+export default processPatterns;

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

@@ -0,0 +1,86 @@
+"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());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processPatterns = processPatterns;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const logger_1 = require("../../../utils/logger");
+const api_1 = require("./api");
+const html_1 = require("./html");
+/**
+ * Process all pattern declarations and compose their HTML from pre-built
+ * component preview files. This function must run AFTER buildComponents
+ * so that all component preview HTML files already exist on disk.
+ */
+function processPatterns(handoff) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d;
+        const runtimePatterns = (_c = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.patterns) !== null && _c !== void 0 ? _c : {};
+        const patternIds = Object.keys(runtimePatterns);
+        const result = [];
+        if (patternIds.length === 0) {
+            yield (0, api_1.syncPatternArtifacts)(handoff, []);
+            yield (0, api_1.writePatternSummaryApi)(handoff, result);
+            return result;
+        }
+        logger_1.Logger.info(`Building ${patternIds.length} pattern(s)...`);
+        const componentOutputDir = path_1.default.resolve(handoff.workingPath, 'public/api/component');
+        const basePath = (_d = process.env.HANDOFF_APP_BASE_PATH) !== null && _d !== void 0 ? _d : '';
+        for (const patternId of patternIds) {
+            const pattern = runtimePatterns[patternId];
+            const fragments = [];
+            let hasErrors = false;
+            for (let i = 0; i < pattern.components.length; i++) {
+                const ref = pattern.components[i];
+                if (ref.resolved === false && !ref.resolvedPreview) {
+                    hasErrors = true;
+                    continue;
+                }
+                const previewKey = ref.resolvedPreview || ref.preview || 'default';
+                const htmlFileName = `${ref.id}-${previewKey}.html`;
+                const htmlFilePath = path_1.default.resolve(componentOutputDir, htmlFileName);
+                if (!fs_extra_1.default.existsSync(htmlFilePath)) {
+                    const error = `Pattern "${patternId}" component[${i}] ("${ref.id}") preview file not found: ${htmlFileName}. ` +
+                        `Ensure the component has a preview named "${previewKey}".`;
+                    logger_1.Logger.warn(error);
+                    ref.resolved = false;
+                    hasErrors = true;
+                    continue;
+                }
+                ref.resolved = true;
+                const html = yield fs_extra_1.default.readFile(htmlFilePath, 'utf8');
+                fragments.push({ componentId: ref.id, html });
+            }
+            if (fragments.length === 0) {
+                logger_1.Logger.warn(`Pattern "${patternId}" produced no fragments. Skipping.`);
+                continue;
+            }
+            if (hasErrors) {
+                logger_1.Logger.warn(`Pattern "${patternId}" has missing components but will be composed from available fragments.`);
+            }
+            const composedHtml = (0, html_1.composePatternHtml)(patternId, pattern.title, fragments, basePath);
+            const patternUrl = `${patternId}.html`;
+            const patternData = Object.assign(Object.assign({}, pattern), { url: patternUrl, path: `${basePath}/api/pattern/${patternId}.json` });
+            yield (0, api_1.writePatternHtml)(patternId, composedHtml, handoff);
+            yield (0, api_1.writePatternApi)(patternId, patternData, handoff);
+            result.push(patternData);
+            logger_1.Logger.debug(`Built pattern: ${patternId} (${fragments.length} component(s))`);
+        }
+        yield (0, api_1.syncPatternArtifacts)(handoff, result.map((pattern) => pattern.id));
+        yield (0, api_1.writePatternSummaryApi)(handoff, result);
+        logger_1.Logger.info(`Finished building ${result.length} pattern(s).`);
+        return result;
+    });
+}
+exports.default = processPatterns;

package/dist/transformers/preview/pattern/html.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Composes multiple component preview HTML documents into a single-page HTML.
+ *
+ * Each component preview may be a React SSR document (with hydration scripts
+ * and a `#root` / `#__APP_PROPS__` pair) or a static Handlebars document.
+ *
+ * This function namespaces the element ids per-fragment so multiple React
+ * components can coexist and hydrate independently on the same page.
+ *
+ * Each hydration bundle gets its own `<script type="module">` tag for full
+ * module-level isolation. This is critical because esbuild bundles React
+ * into each script using module-scoped `var` declarations, and `hydrateRoot`
+ * is asynchronous — sharing a single module scope would cause later bundles
+ * to overwrite earlier React instances before hydration completes.
+ */
+export declare const composePatternHtml: (_patternId: string, patternTitle: string, fragments: {
+    componentId: string;
+    html: string;
+}[], basePath: string) => string;

package/dist/transformers/preview/pattern/html.js

@@ -0,0 +1,94 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composePatternHtml = void 0;
+const escape_1 = __importDefault(require("lodash/escape"));
+const node_html_parser_1 = require("node-html-parser");
+/**
+ * Composes multiple component preview HTML documents into a single-page HTML.
+ *
+ * Each component preview may be a React SSR document (with hydration scripts
+ * and a `#root` / `#__APP_PROPS__` pair) or a static Handlebars document.
+ *
+ * This function namespaces the element ids per-fragment so multiple React
+ * components can coexist and hydrate independently on the same page.
+ *
+ * Each hydration bundle gets its own `<script type="module">` tag for full
+ * module-level isolation. This is critical because esbuild bundles React
+ * into each script using module-scoped `var` declarations, and `hydrateRoot`
+ * is asynchronous — sharing a single module scope would cause later bundles
+ * to overwrite earlier React instances before hydration completes.
+ */
+const composePatternHtml = (_patternId, patternTitle, fragments, basePath) => {
+    const cssHrefs = new Set();
+    const bodyParts = [];
+    const scriptTags = [];
+    cssHrefs.add(`${basePath}/api/component/main.css`);
+    cssHrefs.add(`${basePath}/assets/css/preview.css`);
+    const seenComponents = new Set();
+    for (let i = 0; i < fragments.length; i++) {
+        const { componentId, html } = fragments[i];
+        if (!seenComponents.has(componentId)) {
+            seenComponents.add(componentId);
+            cssHrefs.add(`${basePath}/api/component/${componentId}.css`);
+        }
+        const doc = (0, node_html_parser_1.parse)(html);
+        const suffix = `_p${i}`;
+        const namespacedRootId = `root${suffix}`;
+        const namespacedPropsId = `__APP_PROPS__${suffix}`;
+        // -- Extract props JSON (React SSR) ------------------------------------
+        const propsScript = doc.querySelector('#__APP_PROPS__');
+        let propsContent = '{}';
+        if (propsScript) {
+            propsContent = propsScript.textContent || '{}';
+            propsScript.remove();
+        }
+        // -- Extract and rewrite hydration scripts (React SSR) -----------------
+        // Each script becomes its own <script type="module"> for full isolation.
+        const moduleScripts = doc.querySelectorAll('script[type="module"]');
+        for (const script of moduleScripts) {
+            let code = script.textContent || '';
+            if (code.trim()) {
+                code = code
+                    .replace(/__APP_PROPS__/g, namespacedPropsId)
+                    .replace(/getElementById\(\s*["']root["']\s*\)/g, `getElementById("${namespacedRootId}")`);
+                scriptTags.push(`    <script type="module">\n${code}\n    </script>`);
+            }
+            script.remove();
+        }
+        // -- Namespace the root element (React SSR) ----------------------------
+        const rootEl = doc.querySelector('#root');
+        if (rootEl) {
+            rootEl.setAttribute('id', namespacedRootId);
+        }
+        // -- Extract body content ----------------------------------------------
+        const bodyEl = doc.querySelector('body');
+        const bodyContent = bodyEl
+            ? bodyEl.innerHTML.trim()
+            : rootEl
+                ? rootEl.outerHTML
+                : doc.innerHTML || '';
+        bodyParts.push(`    <div class="handoff-pattern-block" data-component="${componentId}" data-fragment="${i}">\n` +
+            `      <script id="${namespacedPropsId}" type="application/json">${propsContent}</script>\n` +
+            `      ${bodyContent}\n` +
+            `    </div>`);
+    }
+    const linkTags = Array.from(cssHrefs)
+        .map((href) => `    <link rel="stylesheet" href="${href}" />`)
+        .join('\n');
+    return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+${linkTags}
+    <title>${(0, escape_1.default)(patternTitle)}</title>
+  </head>
+  <body>
+${bodyParts.join('\n')}
+${scriptTags.join('\n')}
+  </body>
+</html>`;
+};
+exports.composePatternHtml = composePatternHtml;

package/dist/transformers/preview/types.d.ts

@@ -1,5 +1,6 @@
 import type { GeneratedDocs } from 'handoff-docgen';
 import { Card } from '../../app/components/Component/Cards';
+import type { RendererKind } from '../../declarations/types';
 import { ValidationResult } from '../../types/preview';
 import { Filter } from '../../utils/filter';
 import { SlotMetadata } from './component';
@@ -93,7 +94,17 @@ export type ComponentObject = {
         scss?: string;
         /** Optional path to component template file (if available) */
         template?: string;
+        /** Optional path to React component source for preview rendering */
+        component?: string;
+        /** Optional path to CSF story file */
+        story?: string;
+        /** Optional path to schema file (if available) */
+        schema?: string;
+        /** Optional path to templates directory */
+        templates?: string;
     };
+    /** Optional explicit renderer id */
+    renderer?: RendererKind;
     /** Schema describing the expected properties (props/slots) for the component */
     properties: {
         [key: string]: SlotMetadata;
@@ -102,10 +113,18 @@ export type ComponentObject = {
     previews: {
         [key: string]: OptionalPreviewRender;
     };
+    /** Internal previews generated only for pattern composition, not public docs */
+    internalPatternPreviews?: {
+        [key: string]: OptionalPreviewRender;
+    };
     /** Optional array of high-level categories for search/filtering */
     categories?: string[];
     /** Optional array of tags for search/filtering (e.g. "primary", "interactive") */
     tags?: string[];
+    /** Optional markdown strings describing recommended usage patterns */
+    should_do?: string[];
+    /** Optional markdown strings describing anti-patterns to avoid */
+    should_not_do?: string[];
     /** Optional source Figma file or node URL for the component */
     figma?: string;
     /** Optional canonical Figma component name or ID (used for matching back to design tokens) */
@@ -138,11 +157,15 @@ export type TransformComponentTokensResult = {
     css?: string;
     sass?: string;
     sharedStyles?: string;
+    usage?: string;
     title?: string;
     description?: string;
     previews?: {
         [key: string]: OptionalPreviewRender;
     };
+    internalPatternPreviews?: {
+        [key: string]: OptionalPreviewRender;
+    };
     properties?: {
         [key: string]: SlotMetadata;
     };
@@ -151,8 +174,12 @@ export type TransformComponentTokensResult = {
         js?: string;
         scss?: string;
         template?: string;
+        component?: string;
+        story?: string;
         schema?: string;
+        templates?: string;
     };
+    renderer?: RendererKind;
     options?: {
         preview?: {
             groupBy?: string;
@@ -168,7 +195,34 @@ export type OptionalPreviewRender = {
         [key: string]: string | string[] | any;
     };
     url: string;
+    usage?: string;
+    /** Optional source preview/story key used to derive this preview */
+    sourcePreview?: string;
 };
 export interface TransformedPreviewComponents {
     [key: string]: TransformComponentTokensResult[];
 }
+export type PatternComponentEntry = {
+    /** Component id reference */
+    id: string;
+    /** Named preview variant to use (optional if args provided) */
+    preview?: string;
+    /** Arg overrides (optional if preview provided) */
+    args?: Record<string, any>;
+    /** Preview key resolved during injectPatternPreviews (set at build time) */
+    resolvedPreview?: string;
+    /** Whether the pattern entry resolved to a usable component preview */
+    resolved?: boolean;
+};
+export type PatternObject = {
+    title: string;
+    description?: string;
+    group?: string;
+    tags?: string[];
+    components: PatternComponentEntry[];
+    url?: string;
+};
+export type PatternListObject = {
+    id: string;
+    path: string;
+} & PatternObject;

package/dist/transformers/utils/csf.d.ts

@@ -0,0 +1,16 @@
+import { OptionalPreviewRender } from '../preview/types';
+export type StoryObject = {
+    name?: string;
+    args?: Record<string, any>;
+    argTypes?: Record<string, any>;
+    render?: (args: Record<string, any>) => any;
+};
+export type CsfMeta = {
+    title?: string;
+    component?: any;
+    args?: Record<string, any>;
+    argTypes?: Record<string, any>;
+    render?: (args: Record<string, any>) => any;
+};
+export declare function getCsfStoryEntries(moduleExports: Record<string, any>): Array<[string, StoryObject]>;
+export declare function createCsfStoryPreviews(moduleExports: Record<string, any>): Record<string, OptionalPreviewRender>;

package/dist/transformers/utils/csf.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCsfStoryEntries = getCsfStoryEntries;
+exports.createCsfStoryPreviews = createCsfStoryPreviews;
+const lodash_1 = require("lodash");
+function getCsfStoryEntries(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 createCsfStoryPreviews(moduleExports) {
+    const meta = (moduleExports.default || {});
+    const stories = getCsfStoryEntries(moduleExports);
+    const previews = {};
+    for (const [storyKey, storyValue] of stories) {
+        const storyObj = (typeof storyValue === 'function' ? {} : storyValue);
+        previews[storyKey] = {
+            title: storyObj.name || (0, lodash_1.startCase)(storyKey),
+            values: Object.assign(Object.assign({}, (meta.args || {})), (storyObj.args || {})),
+            url: '',
+        };
+    }
+    return previews;
+}

package/dist/transformers/utils/index.d.ts

@@ -8,5 +8,6 @@ export * from './schema';
 export * from './html';
 export * from './build';
 export * from './module';
+export * from './csf';
 export * from './handlebars';
 export * from './schema-loader';

package/dist/transformers/utils/index.js

@@ -28,6 +28,8 @@ __exportStar(require("./html"), exports);
 __exportStar(require("./build"), exports);
 // Module utilities
 __exportStar(require("./module"), exports);
+// CSF utilities
+__exportStar(require("./csf"), exports);
 // Handlebars utilities
 __exportStar(require("./handlebars"), exports);
 // Schema loader utilities

package/dist/transformers/utils/module.d.ts

@@ -6,3 +6,8 @@ import { ModuleEvaluationResult } from '../types';
  * @returns Module evaluation result with exports
  */
 export declare function buildAndEvaluateModule(entryPath: string, handoff: any): Promise<ModuleEvaluationResult>;
+/**
+ * Builds and evaluates a module synchronously using esbuild.
+ * Used by config/runtime code paths that must remain synchronous.
+ */
+export declare function buildAndEvaluateModuleSync(entryPath: string, handoff: any): ModuleEvaluationResult;

package/dist/transformers/utils/module.js

@@ -13,8 +13,22 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildAndEvaluateModule = buildAndEvaluateModule;
+exports.buildAndEvaluateModuleSync = buildAndEvaluateModuleSync;
 const esbuild_1 = __importDefault(require("esbuild"));
 const build_1 = require("./build");
+function createModuleBuildConfig(entryPath, handoff) {
+    var _a, _b;
+    const defaultBuildConfig = Object.assign(Object.assign({}, build_1.DEFAULT_SSR_BUILD_CONFIG), { entryPoints: [entryPath] });
+    return ((_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.hooks) === null || _b === void 0 ? void 0 : _b.ssrBuildConfig)
+        ? handoff.config.hooks.ssrBuildConfig(defaultBuildConfig)
+        : defaultBuildConfig;
+}
+function evaluateBuiltModule(code) {
+    const mod = { exports: {} };
+    const func = new Function('require', 'module', 'exports', code);
+    func(require, mod, mod.exports);
+    return mod;
+}
 /**
  * Builds and evaluates a module using esbuild
  * @param entryPath - Path to the module entry point
@@ -23,20 +37,19 @@ const build_1 = require("./build");
  */
 function buildAndEvaluateModule(entryPath, handoff) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a, _b;
-        // Default esbuild configuration
-        const defaultBuildConfig = Object.assign(Object.assign({}, build_1.DEFAULT_SSR_BUILD_CONFIG), { entryPoints: [entryPath] });
-        // Apply user's SSR build config hook if provided
-        const buildConfig = ((_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.hooks) === null || _b === void 0 ? void 0 : _b.ssrBuildConfig)
-            ? handoff.config.hooks.ssrBuildConfig(defaultBuildConfig)
-            : defaultBuildConfig;
-        // Compile the module
+        const buildConfig = createModuleBuildConfig(entryPath, handoff);
         const build = yield esbuild_1.default.build(buildConfig);
         const { text: code } = build.outputFiles[0];
-        // Evaluate the compiled code
-        const mod = { exports: {} };
-        const func = new Function('require', 'module', 'exports', code);
-        func(require, mod, mod.exports);
-        return mod;
+        return evaluateBuiltModule(code);
     });
 }
+/**
+ * Builds and evaluates a module synchronously using esbuild.
+ * Used by config/runtime code paths that must remain synchronous.
+ */
+function buildAndEvaluateModuleSync(entryPath, handoff) {
+    const buildConfig = createModuleBuildConfig(entryPath, handoff);
+    const build = esbuild_1.default.buildSync(buildConfig);
+    const { text: code } = build.outputFiles[0];
+    return evaluateBuiltModule(code);
+}

package/dist/transformers/utils/usage.d.ts

@@ -0,0 +1,23 @@
+import { SlotMetadata } from '../preview/component';
+/**
+ * Extracts the PascalCase component name from a file path.
+ * e.g. `/path/to/Button.tsx` -> `Button`
+ */
+export declare function extractComponentName(filePath: string): string;
+export interface GenerateUsageSnippetOptions {
+    componentName: string;
+    properties: Record<string, SlotMetadata>;
+    previewValues: Record<string, any>;
+    /** Template filename for the import path (e.g. "Button.tsx") */
+    templateFileName?: string;
+    importStatement?: string;
+}
+/**
+ * Generates a JSX usage snippet showing how to consume a React component
+ * with the given preview values.
+ *
+ * Iterates over the union of preview values and schema properties so that
+ * props not present in the preview are still represented when they carry
+ * a meaningful default or are required.
+ */
+export declare function generateUsageSnippet(options: GenerateUsageSnippetOptions): string;