handoff-app 1.1.3 → 1.2.0-1

package/dist/config/runtime.js

@@ -3,27 +3,140 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toLowerCaseKeysAndValues = exports.getComponentsForPath = exports.initRuntimeConfig = void 0;
+exports.toLowerCaseKeysAndValues = exports.getItemsForPath = exports.getComponentsForPath = exports.initRuntimeConfig = void 0;
+const esbuild_1 = __importDefault(require("esbuild"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
+const module_1 = require("module");
 const path_1 = __importDefault(require("path"));
+const csf_1 = require("../transformers/utils/csf");
+const module_2 = require("../transformers/utils/module");
 const logger_1 = require("../utils/logger");
+const path_2 = require("../utils/path");
+const declaration_1 = require("./normalizers/declaration");
+const pattern_1 = require("./normalizers/pattern");
+const MODERN_EXTENSIONS = ['ts', 'js', 'cjs', 'json'];
+const getLegacyDeclarationFiles = (componentBaseName) => [
+    `${componentBaseName}.json`,
+    `${componentBaseName}.js`,
+    `${componentBaseName}.cjs`,
+];
+const getModernDeclarationFiles = (componentBaseName) => MODERN_EXTENSIONS.map((ext) => `${componentBaseName}.handoff.${ext}`);
+const findPreferredModernDeclaration = (componentDir, componentBaseName) => {
+    const exactCandidates = getModernDeclarationFiles(componentBaseName);
+    const exactMatch = exactCandidates.find((candidate) => fs_extra_1.default.existsSync(path_1.default.resolve(componentDir, candidate)));
+    if (exactMatch)
+        return exactMatch;
+    const allFiles = fs_extra_1.default.existsSync(componentDir) ? fs_extra_1.default.readdirSync(componentDir) : [];
+    const modernFiles = allFiles
+        .filter((file) => /\.handoff\.(ts|js|cjs|json)$/.test(file))
+        .sort((a, b) => a.localeCompare(b));
+    if (!modernFiles.length)
+        return undefined;
+    for (const ext of MODERN_EXTENSIONS) {
+        const extMatch = modernFiles.find((file) => file.endsWith(`.handoff.${ext}`));
+        if (extMatch)
+            return extMatch;
+    }
+    return modernFiles[0];
+};
+const resolveComponentDeclaration = (componentDir, componentBaseName) => {
+    const modernMatch = findPreferredModernDeclaration(componentDir, componentBaseName);
+    const legacyFiles = getLegacyDeclarationFiles(componentBaseName);
+    const legacyMatch = legacyFiles.find((candidate) => fs_extra_1.default.existsSync(path_1.default.resolve(componentDir, candidate)));
+    if (modernMatch) {
+        if (legacyMatch) {
+            logger_1.Logger.warn(`Both modern and legacy declarations found in "${componentDir}". Using "${modernMatch}" and ignoring "${legacyMatch}".`);
+        }
+        return { fileName: modernMatch };
+    }
+    if (legacyMatch) {
+        return { fileName: legacyMatch };
+    }
+    return null;
+};
+const evaluateTypeScriptDeclaration = (filePath, handoffModulePath) => {
+    var _a, _b;
+    const buildResult = esbuild_1.default.buildSync({
+        entryPoints: [filePath],
+        bundle: true,
+        write: false,
+        platform: 'node',
+        format: 'cjs',
+        target: 'node16',
+        logLevel: 'silent',
+        jsx: 'automatic',
+        external: ['react', 'react-dom', 'handoff-app'],
+    });
+    const code = (_b = (_a = buildResult.outputFiles) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.text;
+    if (!code) {
+        throw new Error(`Unable to compile declaration file "${filePath}"`);
+    }
+    const mod = { exports: {} };
+    const localRequire = (0, module_1.createRequire)(filePath);
+    const handoffRequire = (0, module_1.createRequire)(path_1.default.resolve(handoffModulePath, 'package.json'));
+    const runtimeRequire = (id) => {
+        try {
+            return localRequire(id);
+        }
+        catch (_a) {
+            return handoffRequire(id);
+        }
+    };
+    const evaluator = new Function('require', 'module', 'exports', '__filename', '__dirname', code);
+    evaluator(runtimeRequire, mod, mod.exports, filePath, path_1.default.dirname(filePath));
+    return mod.exports;
+};
+const loadDeclarationFile = (filePath, handoffModulePath) => {
+    if (filePath.endsWith('.json')) {
+        const componentJson = fs_extra_1.default.readFileSync(filePath, 'utf8');
+        return JSON.parse(componentJson);
+    }
+    if (filePath.endsWith('.ts')) {
+        return evaluateTypeScriptDeclaration(filePath, handoffModulePath);
+    }
+    // Invalidate require cache to ensure fresh read
+    delete require.cache[require.resolve(filePath)];
+    return require(filePath);
+};
+const discoverCsfPreviews = (component, handoff) => {
+    var _a;
+    if (component.renderer !== 'csf' || !((_a = component.entries) === null || _a === void 0 ? void 0 : _a.template)) {
+        return component.previews;
+    }
+    try {
+        const loaded = (0, module_2.buildAndEvaluateModuleSync)(component.entries.template, handoff);
+        const discoveredPreviews = (0, csf_1.createCsfStoryPreviews)(loaded.exports);
+        if (Object.keys(discoveredPreviews).length === 0) {
+            logger_1.Logger.warn(`No named stories found in CSF file for "${component.id}": ${component.entries.template}`);
+            return component.previews;
+        }
+        return discoveredPreviews;
+    }
+    catch (error) {
+        logger_1.Logger.warn(`Failed to discover CSF stories for "${component.id}" from "${component.entries.template}". Falling back to declared previews.`);
+        logger_1.Logger.debug('CSF discovery error', error);
+        return component.previews;
+    }
+};
 /**
  * Initializes the runtime configuration by resolving component entries,
  * SCSS/JS paths, and transformer options from the handoff config.
  *
  * @param handoff - Object with config and workingPath.
- * @returns A tuple of [RuntimeConfig, configFilePaths].
+ * @returns A tuple of [RuntimeConfig, configFilePaths, configFileIndex].
  */
 const initRuntimeConfig = (handoff) => {
-    var _a, _b, _c, _d, _e, _f, _g, _h;
-    var _j;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    var _l;
     const configFiles = [];
+    const configFileIndex = new Map();
     const result = {
         options: {},
         entries: {
             scss: undefined,
             js: undefined,
             components: {},
+            patterns: {},
         },
     };
     if (!!((_a = handoff.config.entries) === null || _a === void 0 ? void 0 : _a.scss)) {
@@ -37,46 +150,34 @@ const initRuntimeConfig = (handoff) => {
         for (const componentPath of componentPaths) {
             const resolvedComponentPath = path_1.default.resolve(handoff.workingPath, componentPath);
             const componentBaseName = path_1.default.basename(resolvedComponentPath);
-            const possibleConfigFiles = [`${componentBaseName}.json`, `${componentBaseName}.js`, `${componentBaseName}.cjs`];
-            const configFileName = possibleConfigFiles.find((file) => fs_extra_1.default.existsSync(path_1.default.resolve(resolvedComponentPath, file)));
-            if (!configFileName) {
-                logger_1.Logger.warn(`Missing config: ${path_1.default.resolve(resolvedComponentPath, possibleConfigFiles.join(' or '))}`);
+            const declaration = resolveComponentDeclaration(resolvedComponentPath, componentBaseName);
+            if (!declaration) {
+                const modernFiles = getModernDeclarationFiles(componentBaseName);
+                const legacyFiles = getLegacyDeclarationFiles(componentBaseName);
+                logger_1.Logger.warn(`Missing config: ${path_1.default.resolve(resolvedComponentPath, [...modernFiles, ...legacyFiles].join(' or '))}`);
                 continue;
             }
-            const resolvedComponentConfigPath = path_1.default.resolve(resolvedComponentPath, configFileName);
+            const resolvedComponentConfigPath = path_1.default.resolve(resolvedComponentPath, declaration.fileName);
             configFiles.push(resolvedComponentConfigPath);
             let component;
             try {
-                if (configFileName.endsWith('.json')) {
-                    const componentJson = fs_extra_1.default.readFileSync(resolvedComponentConfigPath, 'utf8');
-                    component = JSON.parse(componentJson);
-                }
-                else {
-                    // Invalidate require cache to ensure fresh read
-                    delete require.cache[require.resolve(resolvedComponentConfigPath)];
-                    const importedComponent = require(resolvedComponentConfigPath);
-                    component = importedComponent.default || importedComponent;
-                }
+                const importedDeclaration = loadDeclarationFile(resolvedComponentConfigPath, handoff.modulePath);
+                const rawComponent = importedDeclaration.default || importedDeclaration;
+                component = (0, declaration_1.normalizeComponentDeclaration)(rawComponent, {
+                    declarationPath: resolvedComponentConfigPath,
+                    fallbackId: componentBaseName,
+                    warn: (message) => logger_1.Logger.warn(message),
+                });
             }
             catch (err) {
                 logger_1.Logger.error(`Failed to read or parse config: ${resolvedComponentConfigPath}`, err);
                 continue;
             }
-            // Use component basename as the id
-            component.id = componentBaseName;
-            // Resolve entry paths relative to component directory
-            if (component.entries) {
-                for (const entryType in component.entries) {
-                    if (component.entries[entryType]) {
-                        component.entries[entryType] = path_1.default.resolve(resolvedComponentPath, component.entries[entryType]);
-                    }
-                }
-            }
             // Initialize options with safe defaults
             component.options || (component.options = {
                 transformer: { defaults: {}, replace: {} },
             });
-            (_j = component.options).transformer || (_j.transformer = { defaults: {}, replace: {} });
+            (_l = component.options).transformer || (_l.transformer = { defaults: {}, replace: {} });
             const transformer = component.options.transformer;
             (_g = transformer.cssRootClass) !== null && _g !== void 0 ? _g : (transformer.cssRootClass = null);
             (_h = transformer.tokenNameSegments) !== null && _h !== void 0 ? _h : (transformer.tokenNameSegments = null);
@@ -85,11 +186,52 @@ const initRuntimeConfig = (handoff) => {
             transformer.replace = (0, exports.toLowerCaseKeysAndValues)(Object.assign({}, transformer.replace));
             // Save transformer config
             result.options[component.id] = transformer;
+            // Discover CSF stories early so patterns can resolve stories like normal previews.
+            component.previews = discoverCsfPreviews(component, handoff);
             // Save full component entry
             result.entries.components[component.id] = component;
+            configFileIndex.set((0, path_2.normalizePathForCompare)(resolvedComponentConfigPath), { kind: 'component', entityId: component.id });
         }
     }
-    return [result, Array.from(configFiles)];
+    // -------------------------------------------------------------------------
+    // Load pattern declarations
+    // -------------------------------------------------------------------------
+    if ((_k = (_j = handoff.config.entries) === null || _j === void 0 ? void 0 : _j.patterns) === null || _k === void 0 ? void 0 : _k.length) {
+        const patternPaths = handoff.config.entries.patterns.flatMap(exports.getItemsForPath);
+        for (const patternPath of patternPaths) {
+            const resolvedPatternPath = path_1.default.resolve(handoff.workingPath, patternPath);
+            const patternBaseName = path_1.default.basename(resolvedPatternPath);
+            const declaration = resolveComponentDeclaration(resolvedPatternPath, patternBaseName);
+            if (!declaration) {
+                const modernFiles = getModernDeclarationFiles(patternBaseName);
+                const legacyFiles = getLegacyDeclarationFiles(patternBaseName);
+                logger_1.Logger.warn(`Missing pattern config: ${path_1.default.resolve(resolvedPatternPath, [...modernFiles, ...legacyFiles].join(' or '))}`);
+                continue;
+            }
+            const resolvedPatternConfigPath = path_1.default.resolve(resolvedPatternPath, declaration.fileName);
+            configFiles.push(resolvedPatternConfigPath);
+            let pattern;
+            try {
+                const importedDeclaration = loadDeclarationFile(resolvedPatternConfigPath, handoff.modulePath);
+                const rawPattern = importedDeclaration.default || importedDeclaration;
+                pattern = (0, pattern_1.normalizePatternDeclaration)(rawPattern, {
+                    declarationPath: resolvedPatternConfigPath,
+                    fallbackId: patternBaseName,
+                });
+            }
+            catch (err) {
+                logger_1.Logger.error(`Failed to read or parse pattern config: ${resolvedPatternConfigPath}`, err);
+                continue;
+            }
+            configFileIndex.set((0, path_2.normalizePathForCompare)(resolvedPatternConfigPath), { kind: 'pattern', entityId: pattern.id });
+            result.entries.patterns[pattern.id] = pattern;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Inject synthetic previews from patterns onto components
+    // -------------------------------------------------------------------------
+    injectPatternPreviews(result);
+    return [result, Array.from(configFiles), configFileIndex];
 };
 exports.initRuntimeConfig = initRuntimeConfig;
 /**
@@ -107,9 +249,8 @@ exports.initRuntimeConfig = initRuntimeConfig;
  */
 const getComponentsForPath = (searchPath) => {
     const dirName = path_1.default.basename(searchPath);
-    const possibleConfigFiles = [`${dirName}.json`, `${dirName}.js`, `${dirName}.cjs`];
+    const hasOwnConfig = !!resolveComponentDeclaration(searchPath, dirName);
     // Check if searchPath itself is a component directory (has a config file named after the directory)
-    const hasOwnConfig = possibleConfigFiles.some((file) => fs_extra_1.default.existsSync(path_1.default.resolve(searchPath, file)));
     if (hasOwnConfig) {
         // This directory is a single component
         return [searchPath];
@@ -128,6 +269,92 @@ const getComponentsForPath = (searchPath) => {
     return [searchPath];
 };
 exports.getComponentsForPath = getComponentsForPath;
+/**
+ * Generic directory discovery for both components and patterns.
+ * Reuses the same logic as getComponentsForPath.
+ */
+const getItemsForPath = (searchPath) => {
+    return (0, exports.getComponentsForPath)(searchPath);
+};
+exports.getItemsForPath = getItemsForPath;
+/**
+ * After both components and patterns are loaded, this function iterates all
+ * pattern component refs and auto-registers synthetic preview entries on the
+ * referenced components whenever custom args are specified.
+ *
+ * This ensures the component build renders every preview needed by patterns
+ * so that pattern composition is purely file I/O (no rendering).
+ */
+const injectPatternPreviews = (result) => {
+    var _a, _b, _c, _d, _e, _f;
+    const patterns = (_b = (_a = result.entries) === null || _a === void 0 ? void 0 : _a.patterns) !== null && _b !== void 0 ? _b : {};
+    const components = (_d = (_c = result.entries) === null || _c === void 0 ? void 0 : _c.components) !== null && _d !== void 0 ? _d : {};
+    for (const [patternId, pattern] of Object.entries(patterns)) {
+        for (let i = 0; i < pattern.components.length; i++) {
+            const ref = pattern.components[i];
+            const component = components[ref.id];
+            if (!component) {
+                const error = `Pattern "${patternId}" references component "${ref.id}" which is not declared. This fragment will be skipped.`;
+                logger_1.Logger.warn(error);
+                ref.resolved = false;
+                continue;
+            }
+            // Case 1: only preview, no args -> use the existing preview as-is
+            if (ref.preview && !ref.args) {
+                if ((_e = component.previews) === null || _e === void 0 ? void 0 : _e[ref.preview]) {
+                    ref.resolved = true;
+                }
+                else {
+                    const error = `Pattern "${patternId}" references preview "${ref.preview}" on component "${ref.id}" which does not exist. This fragment may be skipped.`;
+                    logger_1.Logger.warn(error);
+                    ref.resolved = false;
+                }
+                ref.resolvedPreview = ref.preview;
+                continue;
+            }
+            // Case 2: no preview AND no args -> use the component's first existing preview (never assume "default")
+            if (!ref.preview && !ref.args) {
+                const previewKeys = Object.keys(component.previews || {});
+                const firstPreview = previewKeys[0];
+                if (firstPreview) {
+                    ref.resolvedPreview = firstPreview;
+                    ref.resolved = true;
+                }
+                else {
+                    logger_1.Logger.warn(`Pattern "${patternId}" component ref "${ref.id}" has neither "preview" nor "args", and the component has no previews. This fragment will be skipped.`);
+                    ref.resolved = false;
+                }
+                continue;
+            }
+            // Case 3: args present (with or without preview base) -> create synthetic preview
+            let resolvedValues = {};
+            if (ref.preview) {
+                const basePreview = (_f = component.previews) === null || _f === void 0 ? void 0 : _f[ref.preview];
+                if (basePreview) {
+                    resolvedValues = Object.assign({}, basePreview.values);
+                }
+                else {
+                    const error = `Pattern "${patternId}" references preview "${ref.preview}" on component "${ref.id}" which does not exist. Using args only.`;
+                    logger_1.Logger.warn(error);
+                    ref.resolved = false;
+                }
+            }
+            resolvedValues = Object.assign(Object.assign({}, resolvedValues), ref.args);
+            const syntheticKey = `__pattern_${patternId}_${i}`;
+            component.internalPatternPreviews = component.internalPatternPreviews || {};
+            component.internalPatternPreviews[syntheticKey] = {
+                title: syntheticKey,
+                values: resolvedValues,
+                url: '',
+                sourcePreview: ref.preview,
+            };
+            ref.resolvedPreview = syntheticKey;
+            if (ref.resolved === undefined) {
+                ref.resolved = true;
+            }
+        }
+    }
+};
 /**
  * Recursively converts all keys and string values in an object to lowercase.
  */

package/dist/declarations/helpers.d.ts

@@ -0,0 +1,6 @@
+import { CsfDeclarationConfig, GenericDeclarationConfig, GenericPatternDeclarationConfig, HandlebarsDeclarationConfig, ReactComponentType, ReactDeclarationConfig } from './types';
+export declare const defineReactComponent: <TProps>(_component: ReactComponentType<TProps>, config: ReactDeclarationConfig<TProps>) => GenericDeclarationConfig;
+export declare const defineHandlebarsComponent: (config: HandlebarsDeclarationConfig) => GenericDeclarationConfig;
+export declare const defineCsfComponent: (config: CsfDeclarationConfig) => GenericDeclarationConfig;
+export declare const defineComponent: (config: GenericDeclarationConfig) => GenericDeclarationConfig;
+export declare const definePattern: (config: GenericPatternDeclarationConfig) => GenericPatternDeclarationConfig;

package/dist/declarations/helpers.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.definePattern = exports.defineComponent = exports.defineCsfComponent = exports.defineHandlebarsComponent = exports.defineReactComponent = void 0;
+const defineReactComponent = (_component, config) => {
+    return Object.assign(Object.assign({}, config), { renderer: 'react' });
+};
+exports.defineReactComponent = defineReactComponent;
+const defineHandlebarsComponent = (config) => {
+    return Object.assign(Object.assign({}, config), { renderer: 'handlebars' });
+};
+exports.defineHandlebarsComponent = defineHandlebarsComponent;
+const defineCsfComponent = (config) => {
+    return Object.assign(Object.assign({}, config), { renderer: 'csf' });
+};
+exports.defineCsfComponent = defineCsfComponent;
+const defineComponent = (config) => config;
+exports.defineComponent = defineComponent;
+const definePattern = (config) => config;
+exports.definePattern = definePattern;

package/dist/declarations/index.d.ts

@@ -0,0 +1,2 @@
+export { defineComponent, defineCsfComponent, defineHandlebarsComponent, definePattern, defineReactComponent } from './helpers';
+export type { CsfDeclarationConfig, DeclarationPreview, GenericDeclarationConfig, GenericPatternDeclarationConfig, HandlebarsDeclarationConfig, PatternComponentRef, ReactDeclarationConfig, RendererKind } from './types';

package/dist/declarations/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineReactComponent = exports.definePattern = exports.defineHandlebarsComponent = exports.defineCsfComponent = exports.defineComponent = void 0;
+var helpers_1 = require("./helpers");
+Object.defineProperty(exports, "defineComponent", { enumerable: true, get: function () { return helpers_1.defineComponent; } });
+Object.defineProperty(exports, "defineCsfComponent", { enumerable: true, get: function () { return helpers_1.defineCsfComponent; } });
+Object.defineProperty(exports, "defineHandlebarsComponent", { enumerable: true, get: function () { return helpers_1.defineHandlebarsComponent; } });
+Object.defineProperty(exports, "definePattern", { enumerable: true, get: function () { return helpers_1.definePattern; } });
+Object.defineProperty(exports, "defineReactComponent", { enumerable: true, get: function () { return helpers_1.defineReactComponent; } });

package/dist/declarations/types.d.ts

@@ -0,0 +1,60 @@
+import type React from 'react';
+import type { ComponentObject } from '../transformers/preview/types';
+export type RendererKind = 'react' | 'handlebars' | 'csf';
+export type DeclarationPreview<TArgs = Record<string, any>> = {
+    title: string;
+    args?: TArgs;
+    values?: TArgs;
+    url?: string;
+    usage?: string;
+};
+type BaseDeclarationEntries = NonNullable<ComponentObject['entries']> & {
+    component?: string;
+    story?: string;
+    templates?: string;
+};
+type OptionalComponentMetadata = Partial<Omit<ComponentObject, 'previews' | 'entries' | 'title' | 'should_do' | 'should_not_do'>>;
+export type BaseDeclarationConfig = OptionalComponentMetadata & {
+    id?: string;
+    name: string;
+    renderer?: RendererKind;
+    entries?: BaseDeclarationEntries;
+    previews?: Record<string, DeclarationPreview>;
+    shouldDo?: string[];
+    shouldNotDo?: string[];
+};
+export type ReactDeclarationConfig<TProps> = Omit<BaseDeclarationConfig, 'renderer' | 'entries' | 'previews'> & {
+    entries: BaseDeclarationEntries & {
+        component: string;
+    };
+    previews: Record<string, DeclarationPreview<Partial<TProps>>>;
+};
+export type HandlebarsDeclarationConfig = Omit<BaseDeclarationConfig, 'renderer' | 'entries'> & {
+    entries: BaseDeclarationEntries & {
+        template: string;
+    };
+};
+export type CsfDeclarationConfig = Omit<BaseDeclarationConfig, 'renderer' | 'entries'> & {
+    entries: BaseDeclarationEntries & {
+        story: string;
+    };
+};
+export type GenericDeclarationConfig = Omit<BaseDeclarationConfig, 'renderer'> & {
+    renderer: RendererKind;
+};
+export type ReactComponentType<TProps = any> = React.ComponentType<TProps>;
+export type PatternComponentRef = {
+    id: string;
+    preview?: string;
+    args?: Record<string, any>;
+};
+export type BasePatternDeclarationConfig = {
+    id?: string;
+    name: string;
+    description?: string;
+    group?: string;
+    tags?: string[];
+    components: PatternComponentRef[];
+};
+export type GenericPatternDeclarationConfig = BasePatternDeclarationConfig;
+export {};

package/dist/declarations/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import 'dotenv/config';
 import { Types as CoreTypes, Handoff as HandoffRunner } from 'handoff-core';
-import { Config, RuntimeConfig } from './types/config';
+import { Config, ConfigFileEntry, RuntimeConfig } from './types/config';
 declare class Handoff {
     config: Config | null;
     debug: boolean;
@@ -17,6 +17,8 @@ declare class Handoff {
     };
     private _initialArgs;
     private _configFilePaths;
+    private _configFileIndex;
+    private _mainConfigFilePath?;
     private _documentationObjectCache?;
     private _handoffRunner?;
     constructor(debug?: boolean, force?: boolean, config?: Partial<Config>);
@@ -26,6 +28,7 @@ declare class Handoff {
     preRunner(validate?: boolean): Handoff;
     fetch(): Promise<Handoff>;
     component(name: string | null): Promise<Handoff>;
+    pattern(): Promise<Handoff>;
     build(skipComponents?: boolean): Promise<Handoff>;
     ejectConfig(): Promise<Handoff>;
     ejectPages(): Promise<Handoff>;
@@ -82,6 +85,11 @@ declare class Handoff {
      * @returns {string[]} Array of absolute paths to config files
      */
     getConfigFilePaths(): string[];
+    /**
+     * Gets the selected main config file path if one exists.
+     */
+    getMainConfigFilePath(): string | undefined;
+    getConfigFileEntry(configPath: string): ConfigFileEntry | undefined;
     /**
      * Clears all cached data
      * @returns {void}
@@ -96,5 +104,8 @@ declare class Handoff {
 }
 export type { ComponentObject as Component } from './transformers/preview/types';
 export type { Config, RegisterHandlebarsHelpersContext } from './types/config';
+export { defineConfig } from './config';
+export { defineComponent, defineCsfComponent, defineHandlebarsComponent, definePattern, defineReactComponent, } from './declarations';
+export type { CsfDeclarationConfig, DeclarationPreview, GenericDeclarationConfig, GenericPatternDeclarationConfig, HandlebarsDeclarationConfig, PatternComponentRef, ReactDeclarationConfig, RendererKind, } from './declarations';
 export { Transformers as CoreTransformers, TransformerUtils as CoreTransformerUtils, Types as CoreTypes } from 'handoff-core';
 export default Handoff;

package/dist/index.js

@@ -35,7 +35,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CoreTypes = exports.CoreTransformerUtils = exports.CoreTransformers = void 0;
+exports.CoreTypes = exports.CoreTransformerUtils = exports.CoreTransformers = exports.defineReactComponent = exports.definePattern = exports.defineHandlebarsComponent = exports.defineCsfComponent = exports.defineComponent = exports.defineConfig = void 0;
 require("dotenv/config");
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const handoff_core_1 = require("handoff-core");
@@ -48,6 +48,7 @@ const pipeline_1 = __importStar(require("./pipeline"));
 const builder_1 = __importStar(require("./transformers/preview/component/builder"));
 const logger_1 = require("./utils/logger");
 const path_2 = require("./utils/path");
+const path_3 = require("./utils/path");
 class Handoff {
     constructor(debug, force, config) {
         this.debug = false;
@@ -58,6 +59,7 @@ class Handoff {
         this.sitesDirectory = 'out';
         this._initialArgs = {};
         this._configFilePaths = [];
+        this._configFileIndex = new Map();
         this._initialArgs = { debug, force, config };
         this.construct(debug, force, config);
     }
@@ -71,11 +73,13 @@ class Handoff {
     }
     init(configOverride) {
         var _a, _b, _c;
-        const config = (0, config_1.initConfig)(configOverride !== null && configOverride !== void 0 ? configOverride : {});
+        const configResult = (0, config_1.initConfigWithMetadata)(configOverride !== null && configOverride !== void 0 ? configOverride : {});
+        const config = configResult.config;
         this.config = config;
+        this._mainConfigFilePath = configResult.configPath;
         this.exportsDirectory = (_a = config.exportsOutputDirectory) !== null && _a !== void 0 ? _a : this.exportsDirectory;
         this.sitesDirectory = (_b = config.sitesOutputDirectory) !== null && _b !== void 0 ? _b : this.exportsDirectory;
-        [this.runtimeConfig, this._configFilePaths] = (0, config_1.initRuntimeConfig)(this);
+        [this.runtimeConfig, this._configFilePaths, this._configFileIndex] = (0, config_1.initRuntimeConfig)(this);
         if (this.config.app.base_path && !process.env.HANDOFF_APP_BASE_PATH) {
             process.env.HANDOFF_APP_BASE_PATH = (_c = this.config.app.base_path) !== null && _c !== void 0 ? _c : '';
         }
@@ -114,6 +118,13 @@ class Handoff {
             return this;
         });
     }
+    pattern() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.preRunner();
+            yield (0, pipeline_1.buildPatterns)(this);
+            return this;
+        });
+    }
     build(skipComponents) {
         return __awaiter(this, void 0, void 0, function* () {
             this.preRunner();
@@ -242,7 +253,7 @@ class Handoff {
             return this.config.figma_project_id;
         }
         // Fallback to filesystem-safe transformation of working path
-        return (0, path_2.generateFilesystemSafeId)(this.workingPath);
+        return (0, path_3.generateFilesystemSafeId)(this.workingPath);
     }
     /**
      * Gets the output path for the current project
@@ -291,7 +302,17 @@ class Handoff {
      * @returns {string[]} Array of absolute paths to config files
      */
     getConfigFilePaths() {
-        return this._configFilePaths;
+        const combined = this._mainConfigFilePath ? [this._mainConfigFilePath, ...this._configFilePaths] : this._configFilePaths;
+        return Array.from(new Set(combined));
+    }
+    /**
+     * Gets the selected main config file path if one exists.
+     */
+    getMainConfigFilePath() {
+        return this._mainConfigFilePath;
+    }
+    getConfigFileEntry(configPath) {
+        return this._configFileIndex.get((0, path_2.normalizePathForCompare)(configPath));
     }
     /**
      * Clears all cached data
@@ -316,6 +337,14 @@ class Handoff {
         });
     }
 }
+var config_2 = require("./config");
+Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function () { return config_2.defineConfig; } });
+var declarations_1 = require("./declarations");
+Object.defineProperty(exports, "defineComponent", { enumerable: true, get: function () { return declarations_1.defineComponent; } });
+Object.defineProperty(exports, "defineCsfComponent", { enumerable: true, get: function () { return declarations_1.defineCsfComponent; } });
+Object.defineProperty(exports, "defineHandlebarsComponent", { enumerable: true, get: function () { return declarations_1.defineHandlebarsComponent; } });
+Object.defineProperty(exports, "definePattern", { enumerable: true, get: function () { return declarations_1.definePattern; } });
+Object.defineProperty(exports, "defineReactComponent", { enumerable: true, get: function () { return declarations_1.defineReactComponent; } });
 // Export transformers and types from handoff-core
 var handoff_core_2 = require("handoff-core");
 Object.defineProperty(exports, "CoreTransformers", { enumerable: true, get: function () { return handoff_core_2.Transformers; } });

package/dist/pipeline/index.d.ts

@@ -2,6 +2,7 @@ import 'dotenv/config';
 import Handoff from '..';
 export { readPrevJSONFile, zip, zipAssets } from './archive';
 export { buildComponents } from './components';
+export { buildPatterns } from './patterns';
 /**
  * Run the entire Figma data pipeline:
  * 1. Validate runtime requirements

package/dist/pipeline/index.js

@@ -12,7 +12,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildComponents = exports.zipAssets = exports.zip = exports.readPrevJSONFile = void 0;
+exports.buildPatterns = exports.buildComponents = exports.zipAssets = exports.zip = exports.readPrevJSONFile = void 0;
 require("dotenv/config");
 const app_builder_1 = __importDefault(require("../app-builder"));
 const logger_1 = require("../utils/logger");
@@ -26,6 +26,8 @@ Object.defineProperty(exports, "zip", { enumerable: true, get: function () { ret
 Object.defineProperty(exports, "zipAssets", { enumerable: true, get: function () { return archive_1.zipAssets; } });
 var components_1 = require("./components");
 Object.defineProperty(exports, "buildComponents", { enumerable: true, get: function () { return components_1.buildComponents; } });
+var patterns_1 = require("./patterns");
+Object.defineProperty(exports, "buildPatterns", { enumerable: true, get: function () { return patterns_1.buildPatterns; } });
 /**
  * Run the entire Figma data pipeline:
  * 1. Validate runtime requirements

package/dist/pipeline/patterns.d.ts

@@ -0,0 +1,8 @@
+import Handoff from '..';
+import { ProcessPatternsOptions } from '../transformers/preview/pattern/builder';
+export type { ProcessPatternsOptions };
+/**
+ * Builds pattern previews by composing pre-built component preview HTML.
+ * Must be called AFTER buildComponents.
+ */
+export declare const buildPatterns: (handoff: Handoff, options?: ProcessPatternsOptions) => Promise<void>;