handoff-app 1.1.3 → 1.2.0-0

package/dist/transformers/utils/usage.js

@@ -0,0 +1,294 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractComponentName = extractComponentName;
+exports.generateUsageSnippet = generateUsageSnippet;
+const path_1 = __importDefault(require("path"));
+const component_1 = require("../preview/component");
+const CHILDREN_PROP = 'children';
+const INDENT = '  ';
+function isValidIdentifier(key) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key);
+}
+/**
+ * Formats a prop value as a JSX attribute string.
+ * Returns the right-hand side only (e.g. `"hello"`, `{42}`, `{true}`).
+ */
+function formatPropValue(value, type) {
+    if (value === undefined || value === null) {
+        return '{undefined}';
+    }
+    switch (type) {
+        case component_1.SlotType.BOOLEAN:
+            return typeof value === 'boolean' ? `{${value}}` : `{${Boolean(value)}}`;
+        case component_1.SlotType.NUMBER:
+            return `{${Number(value)}}`;
+        case component_1.SlotType.FUNCTION:
+            return '{() => { /* handler */ }}';
+        case component_1.SlotType.OBJECT:
+            return `{${formatObjectLiteral(value)}}`;
+        case component_1.SlotType.ARRAY:
+            return `{${formatArrayLiteral(value)}}`;
+        case component_1.SlotType.TEXT:
+        case component_1.SlotType.IMAGE:
+        case component_1.SlotType.BUTTON:
+        case component_1.SlotType.ENUM:
+        default:
+            if (typeof value === 'string') {
+                return `"${escapeJsxString(value)}"`;
+            }
+            if (typeof value === 'boolean') {
+                return `{${value}}`;
+            }
+            if (typeof value === 'number') {
+                return `{${value}}`;
+            }
+            if (typeof value === 'object') {
+                return `{${JSON.stringify(value, null, 2)}}`;
+            }
+            return `"${escapeJsxString(String(value))}"`;
+    }
+}
+function escapeJsxString(str) {
+    return str.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+function formatObjectLiteral(value) {
+    if (typeof value !== 'object' || value === null) {
+        return JSON.stringify(value);
+    }
+    const entries = Object.entries(value);
+    if (entries.length === 0)
+        return '{}';
+    if (entries.length <= 3) {
+        const inline = entries
+            .map(([k, v]) => `${isValidIdentifier(k) ? k : JSON.stringify(k)}: ${JSON.stringify(v)}`)
+            .join(', ');
+        if (inline.length <= 60)
+            return `{ ${inline} }`;
+    }
+    return JSON.stringify(value, null, 2);
+}
+function formatArrayLiteral(value) {
+    if (!Array.isArray(value))
+        return JSON.stringify(value);
+    if (value.length === 0)
+        return '[]';
+    const inline = JSON.stringify(value);
+    if (inline.length <= 60)
+        return inline;
+    return JSON.stringify(value, null, 2);
+}
+/**
+ * Determines whether a prop value matches its declared default and can be omitted.
+ */
+function matchesDefault(value, slotDefault) {
+    if (slotDefault === undefined || slotDefault === null)
+        return false;
+    if (typeof value === typeof slotDefault && value === slotDefault)
+        return true;
+    // SlotMetadata.default is typed as `string | undefined`, but runtime values
+    // may be numbers or booleans. Do a loose string comparison as a fallback.
+    if (String(value) === String(slotDefault))
+        return true;
+    return false;
+}
+/**
+ * Extracts the PascalCase component name from a file path.
+ * e.g. `/path/to/Button.tsx` -> `Button`
+ */
+function extractComponentName(filePath) {
+    const basename = path_1.default.basename(filePath);
+    const ext = path_1.default.extname(basename);
+    return basename.slice(0, basename.length - ext.length);
+}
+/**
+ * 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.
+ */
+function generateUsageSnippet(options) {
+    var _a;
+    const { componentName, properties, previewValues, templateFileName, importStatement } = options;
+    const importPath = `./${templateFileName ? path_1.default.basename(templateFileName, path_1.default.extname(templateFileName)) : componentName}`;
+    const attrs = [];
+    let childrenValue = undefined;
+    let hasChildren = false;
+    // Merge all known prop keys: preview values first (preserve order), then
+    // any additional keys from the property schema that weren't in the preview.
+    const allKeys = new Set([...Object.keys(previewValues), ...Object.keys(properties)]);
+    for (const key of allKeys) {
+        const slot = properties[key];
+        const inPreview = key in previewValues;
+        const value = inPreview ? previewValues[key] : resolveSchemaValue(slot);
+        // Nothing to show for this prop
+        if (value === undefined || value === null) {
+            continue;
+        }
+        if (key === CHILDREN_PROP) {
+            hasChildren = true;
+            childrenValue = value;
+            continue;
+        }
+        // Skip function props that weren't explicitly provided in preview values
+        if (!inPreview && (slot === null || slot === void 0 ? void 0 : slot.type) === component_1.SlotType.FUNCTION) {
+            continue;
+        }
+        // Omit props that match their declared default
+        if (slot && matchesDefault(value, slot.default)) {
+            continue;
+        }
+        const type = (_a = slot === null || slot === void 0 ? void 0 : slot.type) !== null && _a !== void 0 ? _a : inferSlotType(value);
+        // Boolean true → JSX shorthand: <Comp disabled />
+        if (type === component_1.SlotType.BOOLEAN && value === true) {
+            attrs.push(key);
+            continue;
+        }
+        // Boolean false → omit (implicit JSX default)
+        if (type === component_1.SlotType.BOOLEAN && value === false) {
+            continue;
+        }
+        attrs.push(`${key}=${formatPropValue(value, type)}`);
+    }
+    const lines = [];
+    lines.push(importStatement || `import ${componentName} from '${importPath}';`);
+    lines.push('');
+    if (hasChildren && childrenValue !== undefined && childrenValue !== null && childrenValue !== '') {
+        const openTag = attrs.length > 0 ? `<${componentName} ${attrs.join(' ')}>` : `<${componentName}>`;
+        const childStr = typeof childrenValue === 'string'
+            ? childrenValue
+            : typeof childrenValue === 'number' || typeof childrenValue === 'boolean'
+                ? String(childrenValue)
+                : '{/* children */}';
+        if (childStr.length <= 40 && !childStr.includes('\n')) {
+            lines.push(`${openTag}${childStr}</${componentName}>`);
+        }
+        else {
+            lines.push(openTag);
+            for (const childLine of childStr.split('\n')) {
+                lines.push(`${INDENT}${childLine}`);
+            }
+            lines.push(`</${componentName}>`);
+        }
+    }
+    else {
+        if (attrs.length === 0) {
+            lines.push(`<${componentName} />`);
+        }
+        else if (attrs.length <= 3 && attrs.join(' ').length <= 60) {
+            lines.push(`<${componentName} ${attrs.join(' ')} />`);
+        }
+        else {
+            lines.push(`<${componentName}`);
+            for (const attr of attrs) {
+                lines.push(`${INDENT}${attr}`);
+            }
+            lines.push('/>');
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Resolves a display value for a schema-only property (not present in preview values).
+ *
+ * - Uses the declared default when available and non-trivial.
+ * - For required props without a default, generates a type-appropriate placeholder.
+ * - Returns `undefined` for optional props with no useful default (they are skipped).
+ */
+function resolveSchemaValue(slot) {
+    var _a;
+    if (!slot)
+        return undefined;
+    // Use explicit default if it's non-trivial
+    if (slot.default !== undefined && slot.default !== null && slot.default !== '') {
+        return coerceDefault(slot.default, slot.type);
+    }
+    // Required props must appear even without a default
+    if ((_a = slot.rules) === null || _a === void 0 ? void 0 : _a.required) {
+        return getPlaceholder(slot);
+    }
+    // Optional with no default → omit
+    return undefined;
+}
+/**
+ * Coerces a string default from SlotMetadata into the appropriate JS type
+ * for code-generation purposes.
+ */
+function coerceDefault(value, type) {
+    if (typeof value !== 'string')
+        return value;
+    switch (type) {
+        case component_1.SlotType.BOOLEAN:
+            return value === 'true';
+        case component_1.SlotType.NUMBER: {
+            const n = Number(value);
+            return Number.isNaN(n) ? value : n;
+        }
+        default:
+            return value;
+    }
+}
+/**
+ * Generates a type-appropriate placeholder value for required props
+ * that have no default and no preview value.
+ */
+function getPlaceholder(slot) {
+    switch (slot.type) {
+        case component_1.SlotType.ENUM: {
+            const member = extractFirstEnumMember(slot);
+            return member !== null && member !== void 0 ? member : 'value';
+        }
+        case component_1.SlotType.TEXT:
+        case component_1.SlotType.IMAGE:
+            return '...';
+        case component_1.SlotType.NUMBER:
+            return 0;
+        case component_1.SlotType.BOOLEAN:
+            return true;
+        case component_1.SlotType.ARRAY:
+            return [];
+        case component_1.SlotType.OBJECT:
+            return {};
+        case component_1.SlotType.FUNCTION:
+            return undefined; // handled separately
+        default:
+            return '...';
+    }
+}
+/**
+ * Attempts to extract the first enum member from a SlotMetadata's deepType
+ * (e.g. `"primary"` from `'primary' | 'secondary' | 'danger'`).
+ */
+function extractFirstEnumMember(slot) {
+    var _a, _b;
+    // deepType.members contains the enum values when available
+    if (((_a = slot.deepType) === null || _a === void 0 ? void 0 : _a.kind) === 'enum' && ((_b = slot.deepType.members) === null || _b === void 0 ? void 0 : _b.length)) {
+        const raw = slot.deepType.members[0];
+        // Members are stored as quoted strings like `"primary"` — strip quotes
+        return typeof raw === 'string' ? raw.replace(/^["']|["']$/g, '') : undefined;
+    }
+    // Fall back to parsing the generic display string (e.g. `"primary" | "secondary"`)
+    if (slot.generic) {
+        const match = slot.generic.match(/["']([^"']+)["']/);
+        if (match)
+            return match[1];
+    }
+    return undefined;
+}
+function inferSlotType(value) {
+    if (typeof value === 'boolean')
+        return component_1.SlotType.BOOLEAN;
+    if (typeof value === 'number')
+        return component_1.SlotType.NUMBER;
+    if (typeof value === 'function')
+        return component_1.SlotType.FUNCTION;
+    if (Array.isArray(value))
+        return component_1.SlotType.ARRAY;
+    if (typeof value === 'object' && value !== null)
+        return component_1.SlotType.OBJECT;
+    return component_1.SlotType.TEXT;
+}

package/dist/types/config.d.ts

@@ -3,7 +3,7 @@ import type Handlebars from 'handlebars';
 import { Types as HandoffTypes } from 'handoff-core';
 import { InlineConfig } from 'vite';
 import { SlotMetadata } from '../transformers/preview/component';
-import { ComponentListObject, TransformComponentTokensResult } from '../transformers/preview/types';
+import { ComponentListObject, PatternListObject, TransformComponentTokensResult } from '../transformers/preview/types';
 import { ValidationResult } from './preview';
 export interface ImageStyle {
     name: string;
@@ -65,13 +65,19 @@ export interface NextAppConfig {
     theme?: string;
     title: string;
     client: string;
-    google_tag_manager: string | null | undefined;
-    type_copy: string;
-    type_sort: string[];
-    color_sort: string[];
+    google_tag_manager?: string | null | undefined;
+    googleTagManager?: string | null | undefined;
+    type_copy?: string;
+    typeCopy?: string;
+    type_sort?: string[];
+    typeSort?: string[];
+    color_sort?: string[];
+    colorSort?: string[];
     breakpoints: Breakpoints;
-    component_sort: string[];
-    base_path: string;
+    component_sort?: string[];
+    componentSort?: string[];
+    base_path?: string;
+    basePath?: string;
     attribution: boolean;
     ports?: {
         app: number;
@@ -80,7 +86,9 @@ export interface NextAppConfig {
 }
 export interface Config {
     dev_access_token?: string | null | undefined;
+    devAccessToken?: string | null | undefined;
     figma_project_id?: string | null | undefined;
+    figmaProjectId?: string | null | undefined;
     exportsOutputDirectory?: string;
     sitesOutputDirectory?: string;
     useVariables?: boolean;
@@ -123,6 +131,12 @@ export interface Config {
          * @example ["components/button", "components/input"]
          */
         components?: string[];
+        /**
+         * Array of pattern paths to be included in the build.
+         * Patterns compose multiple component previews into single-page views.
+         * @example ["patterns/hero-section", "patterns"]
+         */
+        patterns?: string[];
     };
     /**
      * Configuration for asset zip file download links
@@ -140,6 +154,10 @@ export interface Config {
          */
         logos?: string;
     };
+    assetsZipLinks?: {
+        icons?: string;
+        logos?: string;
+    };
     /**
      * Configuration hooks for extending functionality
      */
@@ -278,6 +296,10 @@ export interface RuntimeConfigComponentOptions {
         };
     };
 }
+export interface ConfigFileEntry {
+    kind: string;
+    entityId: string;
+}
 export interface RuntimeConfig {
     entries?: {
         scss?: string;
@@ -286,6 +308,9 @@ export interface RuntimeConfig {
         components: {
             [id: string]: ComponentListObject;
         };
+        patterns: {
+            [id: string]: PatternListObject;
+        };
     };
     options: {
         [key: string]: RuntimeConfigComponentOptions;

package/dist/types/preview.d.ts

@@ -54,6 +54,7 @@ export interface PreviewObject {
                 [key: string]: string;
             };
             url: string;
+            usage?: string;
         };
     };
     properties?: {
@@ -61,6 +62,7 @@ export interface PreviewObject {
     };
     code: string;
     html?: string;
+    usage?: string;
     format: string;
     variant?: Record<string, string>;
     options?: {

package/docs/cli.md

@@ -14,9 +14,9 @@ The CLI will allow you to build the various kinds of configurations that you
 will need for interacting with Figma. Handoff has sane configuration defaults
 but the various kinds of configurations can be tailored or extended.
 
-Handoff has 4 configuration files - 
+Handoff has 4 configuration areas - 
 
-`handoff.config.json` - Defines the general handoff configuration.
+`handoff.config.*` - Defines the general handoff configuration. Supported files are `handoff.config.ts`, `handoff.config.js`, `handoff.config.cjs`, and `handoff.config.json` (resolved in that precedence order).
 `pages` - Markdown files that will create or customize pages in the documentation
 app
 `exportables` - JSON schemas for each component in your figma file that you
@@ -28,7 +28,7 @@ The CLI exposes two ways to manage the config - `make` and `eject`.
 
 __Eject__ commands will take the default configuration and eject them into
 the current working directory. If you customize these configurations, then run 
-handoff commands in that directory, these configs will be executed.
+handoff commands in that directory, these configs will be executed. `eject:config` now prompts for TypeScript or JavaScript config format.
 __Make__ commands will generate a boilerplate configuration in the current
 working directory. This is useful for extending handoff for different components
 or integrations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-app",
-  "version": "1.1.3",
+  "version": "1.2.0-0",
   "description": "Automated documentation toolchain for building client side documentation from figma",
   "author ": {
     "name": "Convertiv",
@@ -105,6 +105,8 @@
     "prettier": "^3.4.2",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
+    "react-element-to-jsx-string": "^17.0.1",
+    "react-is": "^19.1.0",
     "react-markdown": "^10.1.0",
     "react-scroll": "^1.8.9",
     "react-syntax-highlighter": "^16.1.0",

package/src/app/components/Component/PageSliceResolver.tsx

@@ -8,8 +8,8 @@ export interface PageSliceResolverProps {
   preview: PreviewObject;
   title: string;
   height?: string;
-  currentValues?: Record<string, string>;
-  onValuesChange?: (values: Record<string, string>) => void;
+  currentPreviewUrl?: string;
+  onPreviewChange?: (previewUrl: string) => void;
   bestPracticesCard?: boolean;
   codeHighlight?: boolean;
   properties?: boolean;
@@ -21,8 +21,8 @@ export const PageSliceResolver: React.FC<PageSliceResolverProps> = ({
   preview,
   title,
   height,
-  currentValues,
-  onValuesChange,
+  currentPreviewUrl,
+  onPreviewChange,
   bestPracticesCard = true,
   codeHighlight = true,
   properties = true,
@@ -39,8 +39,8 @@ export const PageSliceResolver: React.FC<PageSliceResolverProps> = ({
           preview={preview}
           title={title}
           height={height}
-          currentValues={currentValues}
-          onValuesChange={onValuesChange}
+          currentPreviewUrl={currentPreviewUrl}
+          onPreviewChange={onPreviewChange}
           showPreview={slice.showPreview}
           showCodeHighlight={slice.showCodeHighlight}
           defaultHeight={slice.defaultHeight}

package/src/app/components/Component/Preview.tsx

@@ -55,8 +55,8 @@ export const ComponentDisplay: React.FC<{
   component: PreviewObject | undefined;
   defaultHeight?: string | undefined;
   title?: string;
-  onValuesChange?: (values: Record<string, string>) => void;
-}> = ({ component, defaultHeight, title, onValuesChange }) => {
+  onPreviewChange?: (previewUrl: string) => void;
+}> = ({ component, defaultHeight, title, onPreviewChange }) => {
   const context = usePreviewContext();
   const ref = React.useRef<HTMLIFrameElement>(null);
   const [height, setHeight] = React.useState('100px');
@@ -131,11 +131,10 @@ export const ComponentDisplay: React.FC<{
       if (keys.length === 0) {
         return;
       }
-      // check the environment
-      setPreviewUrl(component.previews[keys[0]].url);
-      !!onValuesChange && onValuesChange(component.previews[keys[0]].values);
+      const firstPreview = component.previews[keys[0]];
+      setPreviewUrl(firstPreview.url);
     }
-  }, [component, onValuesChange]);
+  }, [component]);
 
   React.useEffect(() => {
     if (!component) return;
@@ -147,11 +146,17 @@ export const ComponentDisplay: React.FC<{
 
     if (!!previewFilterResult && previewFilterResult.length > 0) {
       setPreviewUrl(previewFilterResult[0].url);
-      !!onValuesChange && onValuesChange(previewFilterResult[0].values);
     } else {
       setPreviewUrl(null);
     }
-  }, [context.variantFilter, component, onValuesChange]);
+  }, [context.variantFilter, component]);
+
+  React.useEffect(() => {
+    if (!component?.previews || !previewUrl) return;
+    const selectedPreview = Object.values(component.previews).find((preview) => preview.url === previewUrl);
+    if (!selectedPreview) return;
+    !!onPreviewChange && onPreviewChange(selectedPreview.url);
+  }, [component?.previews, onPreviewChange, previewUrl]);
 
   const { reloadCounter } = useContext(HotReloadContext);
 
@@ -376,7 +381,7 @@ export const ComponentPreview: React.FC<{
     const context = usePreviewContext();
     const [loaded, setLoaded] = React.useState(false);
     const [preview, setPreview] = React.useState<PreviewObject | undefined>(defaultPreview);
-    const [currentValues, setCurrentValues] = React.useState<Record<string, string> | undefined>();
+    const [currentPreviewUrl, setCurrentPreviewUrl] = React.useState<string | undefined>();
     React.useEffect(() => {
       if (context.preview) {
         setPreview(context.preview);
@@ -409,9 +414,9 @@ export const ComponentPreview: React.FC<{
             preview={preview}
             title={title}
             height={height}
-            currentValues={currentValues}
-            onValuesChange={(vals) => {
-              setCurrentValues(vals);
+            currentPreviewUrl={currentPreviewUrl}
+            onPreviewChange={(previewUrl) => {
+              setCurrentPreviewUrl(previewUrl);
             }}
             bestPracticesCard={bestPracticesCard}
             codeHighlight={codeHighlight}

package/src/app/components/Component/slices/ComponentDisplaySlice.tsx

@@ -8,8 +8,8 @@ export interface ComponentDisplaySliceProps {
   preview: PreviewObject;
   title: string;
   height?: string;
-  currentValues?: Record<string, string>;
-  onValuesChange?: (values: Record<string, string>) => void;
+  currentPreviewUrl?: string;
+  onPreviewChange?: (previewUrl: string) => void;
   showPreview?: boolean;
   showCodeHighlight?: boolean;
   defaultHeight?: string;
@@ -33,8 +33,8 @@ const ComponentDisplaySlice: React.FC<ComponentDisplaySliceProps> = ({
   preview,
   title,
   height,
-  currentValues,
-  onValuesChange,
+  currentPreviewUrl,
+  onPreviewChange,
   showPreview = true,
   showCodeHighlight,
   defaultHeight,
@@ -64,12 +64,22 @@ const ComponentDisplaySlice: React.FC<ComponentDisplaySliceProps> = ({
   return (
     <div id={filteredPreview.id}>
       {showPreview && (
-        <ComponentDisplay title={title} component={filteredPreview} defaultHeight={finalDefaultHeight} onValuesChange={onValuesChange} />
+        <ComponentDisplay
+          title={title}
+          component={filteredPreview}
+          defaultHeight={finalDefaultHeight}
+          onPreviewChange={onPreviewChange}
+        />
       )}
       {finalShowCodeHighlight && (
         <>
           <a id="code-highlight" />
-          <CodeHighlight title={title} data={filteredPreview} collapsible={true} currentValues={currentValues} />
+          <CodeHighlight
+            title={title}
+            data={filteredPreview}
+            collapsible={true}
+            currentPreviewUrl={currentPreviewUrl}
+          />
         </>
       )}
     </div>