handoff-app 1.0.6 → 1.1.0-canary.1

package/Changelog.md

@@ -6,6 +6,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## \[1.1.0]
+
 ## \[1.0.6] - 2026-02-24
 
 Version 1.0.4 fixed an issue when running Handoff in subpaths (eg.

package/dist/config.js

@@ -9,6 +9,10 @@ const defaultConfig = () => {
         exportsOutputDirectory: (_c = process.env.HANDOFF_OUTPUT_DIR) !== null && _c !== void 0 ? _c : 'exported',
         sitesOutputDirectory: (_d = process.env.HANDOFF_SITES_DIR) !== null && _d !== void 0 ? _d : 'out',
         useVariables: (_e = Boolean(process.env.HANDOFF_USE_VARIABLES)) !== null && _e !== void 0 ? _e : false,
+        reactDocgen: {
+            maxDepth: 7,
+            excludeDirectories: ['dist', 'build', '.next'],
+        },
         app: {
             theme: 'default',
             title: 'Convertiv Design System',

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

@@ -1,9 +1,16 @@
-/**
- * Generates component properties using react-docgen-typescript
- * @param entry - Path to the component/schema file
- * @param handoff - Handoff instance for configuration
- * @returns Generated properties or null if failed
- */
+import { type GeneratedDocs } from 'handoff-docgen';
+import { SlotMetadata } from '../preview/component';
+export declare const getPropertiesFromGeneratedDocs: (generatedDocs: GeneratedDocs, entry: string, handoff: any) => {
+    [key: string]: SlotMetadata;
+} | null;
+export declare const enrichPropertiesWithDocgen: (properties: {
+    [key: string]: SlotMetadata;
+} | null | undefined, docgenProperties: {
+    [key: string]: SlotMetadata;
+} | null | undefined) => {
+    [key: string]: SlotMetadata;
+} | null;
+export declare const generateDocsArtifact: (entry: string, handoff: any) => Promise<GeneratedDocs | null>;
 export declare const generatePropertiesFromDocgen: (entry: string, handoff: any) => Promise<{
     [key: string]: any;
 } | null>;

package/dist/transformers/docgen/index.js

@@ -12,50 +12,223 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generatePropertiesFromDocgen = void 0;
+exports.generatePropertiesFromDocgen = exports.generateDocsArtifact = exports.enrichPropertiesWithDocgen = exports.getPropertiesFromGeneratedDocs = void 0;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
-const react_docgen_typescript_1 = require("react-docgen-typescript");
+const handoff_docgen_1 = require("handoff-docgen");
 const logger_1 = require("../../utils/logger");
-const schema_1 = require("../utils/schema");
-/**
- * Generates component properties using react-docgen-typescript
- * @param entry - Path to the component/schema file
- * @param handoff - Handoff instance for configuration
- * @returns Generated properties or null if failed
- */
-const generatePropertiesFromDocgen = (entry, handoff) => __awaiter(void 0, void 0, void 0, function* () {
+const component_1 = require("../preview/component");
+const DEFAULT_DOCGEN_MAX_DEPTH = 7;
+const DEFAULT_DOCGEN_EXCLUDE_DIRECTORIES = ['dist', 'build', '.next'];
+const generatorCache = new Map();
+const normalizePathForCompare = (filePath) => filePath.replace(/\\/g, '/');
+const mapDocgenTypeToSlotType = (typeName) => {
+    const normalizedType = typeName === null || typeName === void 0 ? void 0 : typeName.trim().toLowerCase();
+    switch (normalizedType) {
+        case 'boolean':
+            return component_1.SlotType.BOOLEAN;
+        case 'number':
+            return component_1.SlotType.NUMBER;
+        case 'string':
+            return component_1.SlotType.TEXT;
+        case 'array':
+            return component_1.SlotType.ARRAY;
+        case 'object':
+            return component_1.SlotType.OBJECT;
+        case 'function':
+            return component_1.SlotType.FUNCTION;
+        case 'enum':
+            return component_1.SlotType.ENUM;
+        case 'any':
+        case 'unknown':
+            return component_1.SlotType.ANY;
+        default:
+            if (normalizedType === null || normalizedType === void 0 ? void 0 : normalizedType.includes('=>')) {
+                return component_1.SlotType.FUNCTION;
+            }
+            return component_1.SlotType.TEXT;
+    }
+};
+const getDocgenConfig = (handoff) => {
+    var _a, _b, _c;
+    const reactDocgenConfig = (_b = (_a = handoff === null || handoff === void 0 ? void 0 : handoff.config) === null || _a === void 0 ? void 0 : _a.reactDocgen) !== null && _b !== void 0 ? _b : (_c = handoff === null || handoff === void 0 ? void 0 : handoff.config) === null || _c === void 0 ? void 0 : _c.docgen;
+    const configuredMaxDepth = reactDocgenConfig === null || reactDocgenConfig === void 0 ? void 0 : reactDocgenConfig.maxDepth;
+    const configuredExcludeDirectories = reactDocgenConfig === null || reactDocgenConfig === void 0 ? void 0 : reactDocgenConfig.excludeDirectories;
+    const maxDepth = typeof configuredMaxDepth === 'number' && Number.isFinite(configuredMaxDepth) && configuredMaxDepth > 0
+        ? Math.floor(configuredMaxDepth)
+        : DEFAULT_DOCGEN_MAX_DEPTH;
+    const excludeDirectories = Array.isArray(configuredExcludeDirectories)
+        ? configuredExcludeDirectories
+            .map((entry) => String(entry).trim())
+            .filter((entry) => entry.length > 0)
+        : DEFAULT_DOCGEN_EXCLUDE_DIRECTORIES;
+    return {
+        maxDepth,
+        excludeDirectories: excludeDirectories.length > 0 ? excludeDirectories : DEFAULT_DOCGEN_EXCLUDE_DIRECTORIES,
+    };
+};
+const getGenerator = (componentDirectory, tsconfigPath, maxDepth, excludeDirectories) => {
+    const cacheKey = `${componentDirectory}::${tsconfigPath}::${maxDepth}::${excludeDirectories.join('|')}`;
+    const cached = generatorCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const generator = (0, handoff_docgen_1.createGenerator)({
+        componentDirectory,
+        tsconfigPath,
+        maxDepth,
+        pathMode: 'relative',
+        excludeDirectories,
+    });
+    generatorCache.set(cacheKey, generator);
+    return generator;
+};
+const findComponentDocForEntry = (generatedDocs, entry, handoff) => {
+    const normalizedEntryAbsolute = normalizePathForCompare(path_1.default.resolve(entry));
+    const normalizedEntryRelative = normalizePathForCompare(path_1.default.relative(handoff.workingPath, normalizedEntryAbsolute));
+    const entryBasename = path_1.default.basename(normalizedEntryAbsolute, path_1.default.extname(normalizedEntryAbsolute));
+    const matchesByFile = generatedDocs.components.filter((component) => {
+        const source = normalizePathForCompare(component.sourceFile);
+        return source === normalizedEntryAbsolute || source === normalizedEntryRelative || source.endsWith(`/${normalizedEntryRelative}`);
+    });
+    if (matchesByFile.length > 0) {
+        return matchesByFile[0];
+    }
+    const matchesByName = generatedDocs.components.filter((component) => component.name === entryBasename);
+    if (matchesByName.length > 0) {
+        return matchesByName[0];
+    }
+    return generatedDocs.components[0];
+};
+const toSlotMetadata = (prop) => {
+    var _a, _b;
+    const slotType = mapDocgenTypeToSlotType(prop.docgenType || ((_a = prop.deepType) === null || _a === void 0 ? void 0 : _a.kind) || 'any');
+    const deepType = prop.deepType;
+    const metadata = {
+        id: prop.name,
+        name: prop.name,
+        description: prop.description || '',
+        generic: (deepType === null || deepType === void 0 ? void 0 : deepType.display) || prop.docgenType || '',
+        default: prop.defaultValue,
+        type: slotType,
+        rules: {
+            required: !!prop.required,
+        },
+        docgenType: prop.docgenType,
+        deepType: prop.deepType,
+        typeRefs: prop.typeRefs,
+        warnings: prop.warnings,
+        annotations: prop.annotations,
+    };
+    if ((deepType === null || deepType === void 0 ? void 0 : deepType.kind) === 'object' && ((_b = deepType.properties) === null || _b === void 0 ? void 0 : _b.length)) {
+        metadata.type = component_1.SlotType.OBJECT;
+        metadata.properties = Object.fromEntries(deepType.properties.map((property) => {
+            var _a, _b;
+            return [
+                property.name,
+                toSlotMetadata({
+                    name: property.name,
+                    required: !property.optional,
+                    description: property.description,
+                    docgenType: ((_a = property.type) === null || _a === void 0 ? void 0 : _a.display) || ((_b = property.type) === null || _b === void 0 ? void 0 : _b.kind) || 'unknown',
+                    deepType: property.type,
+                    annotations: property.annotations,
+                }),
+            ];
+        }));
+    }
+    else if ((deepType === null || deepType === void 0 ? void 0 : deepType.kind) === 'array' && deepType.elementType) {
+        metadata.type = component_1.SlotType.ARRAY;
+        metadata.items = {
+            type: mapDocgenTypeToSlotType(deepType.elementType.display || deepType.elementType.kind),
+            properties: deepType.elementType.kind === 'object' && deepType.elementType.properties
+                ? Object.fromEntries(deepType.elementType.properties.map((property) => {
+                    var _a, _b;
+                    return [
+                        property.name,
+                        toSlotMetadata({
+                            name: property.name,
+                            required: !property.optional,
+                            description: property.description,
+                            docgenType: ((_a = property.type) === null || _a === void 0 ? void 0 : _a.display) || ((_b = property.type) === null || _b === void 0 ? void 0 : _b.kind) || 'unknown',
+                            deepType: property.type,
+                            annotations: property.annotations,
+                        }),
+                    ];
+                }))
+                : undefined,
+        };
+    }
+    return metadata;
+};
+const toPropertiesMap = (generatedDocs, entry, handoff) => {
+    var _a;
+    if (!generatedDocs.components.length) {
+        return null;
+    }
+    const componentDoc = findComponentDocForEntry(generatedDocs, entry, handoff);
+    if (!componentDoc || !((_a = componentDoc.props) === null || _a === void 0 ? void 0 : _a.length)) {
+        return null;
+    }
+    const properties = {};
+    for (const prop of componentDoc.props) {
+        properties[prop.name] = toSlotMetadata(prop);
+    }
+    return properties;
+};
+const getPropertiesFromGeneratedDocs = (generatedDocs, entry, handoff) => toPropertiesMap(generatedDocs, entry, handoff);
+exports.getPropertiesFromGeneratedDocs = getPropertiesFromGeneratedDocs;
+const enrichPropertiesWithDocgen = (properties, docgenProperties) => {
+    if (!properties && !docgenProperties) {
+        return null;
+    }
+    if (!properties) {
+        return docgenProperties || null;
+    }
+    if (!docgenProperties) {
+        return properties;
+    }
+    const merged = Object.assign({}, properties);
+    const docgenEntries = Object.entries(docgenProperties);
+    for (const [propName, docgenProp] of docgenEntries) {
+        const existing = merged[propName];
+        if (!existing) {
+            merged[propName] = docgenProp;
+            continue;
+        }
+        merged[propName] = Object.assign(Object.assign({}, existing), { generic: existing.generic || docgenProp.generic, default: existing.default || docgenProp.default, docgenType: docgenProp.docgenType, deepType: docgenProp.deepType, typeRefs: docgenProp.typeRefs, warnings: docgenProp.warnings, annotations: docgenProp.annotations });
+    }
+    return merged;
+};
+exports.enrichPropertiesWithDocgen = enrichPropertiesWithDocgen;
+const generateDocsArtifact = (entry, handoff) => __awaiter(void 0, void 0, void 0, function* () {
     try {
-        // Use root project's tsconfig.json
         const tsconfigPath = path_1.default.resolve(handoff.workingPath, 'tsconfig.json');
-        // Check if tsconfig exists
         if (!fs_extra_1.default.existsSync(tsconfigPath)) {
-            logger_1.Logger.warn(`TypeScript config not found at ${tsconfigPath}, using default configuration`);
+            logger_1.Logger.warn(`TypeScript config not found at ${tsconfigPath}, using default resolution`);
         }
-        const parserConfig = {
-            savePropValueAsString: true,
-            shouldExtractLiteralValuesFromEnum: true,
-            shouldRemoveUndefinedFromOptional: true,
-            propFilter: (prop) => {
-                if (prop.parent) {
-                    return !prop.parent.fileName.includes('node_modules');
-                }
-                return true;
-            },
-        };
-        const parser = (0, react_docgen_typescript_1.withCustomConfig)(tsconfigPath, parserConfig);
-        const docgenResults = parser.parse(entry);
-        if (docgenResults.length > 0) {
-            const componentDoc = docgenResults[0];
-            if (componentDoc.props && Object.keys(componentDoc.props).length > 0) {
-                return (0, schema_1.convertDocgenToProperties)(Object.values(componentDoc.props));
-            }
-        }
-        return null;
+        const componentDirectory = path_1.default.dirname(path_1.default.resolve(entry));
+        const { maxDepth, excludeDirectories } = getDocgenConfig(handoff);
+        const generator = getGenerator(componentDirectory, tsconfigPath, maxDepth, excludeDirectories);
+        return yield generator.generate({
+            componentDirectory,
+            tsconfigPath,
+            maxDepth,
+            pathMode: 'relative',
+            excludeDirectories,
+        });
     }
     catch (error) {
-        logger_1.Logger.warn(`Failed to generate docs with react-docgen-typescript for ${entry}: ${error}`);
+        logger_1.Logger.warn(`Failed to generate docs with handoff-docgen for ${entry}: ${error}`);
+        return null;
+    }
+});
+exports.generateDocsArtifact = generateDocsArtifact;
+const generatePropertiesFromDocgen = (entry, handoff) => __awaiter(void 0, void 0, void 0, function* () {
+    const generatedDocs = yield (0, exports.generateDocsArtifact)(entry, handoff);
+    if (!generatedDocs) {
         return null;
     }
+    return (0, exports.getPropertiesFromGeneratedDocs)(generatedDocs, entry, handoff);
 });
 exports.generatePropertiesFromDocgen = generatePropertiesFromDocgen;

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

@@ -62,7 +62,7 @@ function loadComponentSchemaAndModule(componentData, componentPath, handoff) {
                 component = moduleExports.exports.default;
                 // Try to load schema from component exports
                 properties = yield (0, schema_loader_1.loadSchemaFromComponent)(moduleExports.exports, handoff);
-                // If no schema found, use react-docgen-typescript
+                // If no schema found, use shared docgen fallback
                 if (!properties) {
                     properties = yield (0, docgen_1.generatePropertiesFromDocgen)(componentPath, handoff);
                 }
@@ -169,6 +169,7 @@ function ssrRenderPlugin(componentData, documentationComponents, handoff) {
                 const componentSourceCode = fs_extra_1.default.readFileSync(componentPath, 'utf8');
                 // Load component schema and module
                 const [schemaProperties, ReactComponent] = yield loadComponentSchemaAndModule(componentData, componentPath, handoff);
+                const generatedDocs = yield (0, docgen_1.generateDocsArtifact)(componentPath, handoff);
                 if (!ReactComponent) {
                     logger_1.Logger.error(`Failed to load React component for ${componentId}`);
                     return;
@@ -177,6 +178,11 @@ function ssrRenderPlugin(componentData, documentationComponents, handoff) {
                 if (schemaProperties) {
                     componentData.properties = schemaProperties;
                 }
+                if (generatedDocs) {
+                    const docgenProperties = (0, docgen_1.getPropertiesFromGeneratedDocs)(generatedDocs, componentPath, handoff);
+                    componentData.properties = (0, docgen_1.enrichPropertiesWithDocgen)(componentData.properties, docgenProperties) || {};
+                    componentData.docgen = generatedDocs;
+                }
                 // Ensure components object exists
                 if (!documentationComponents) {
                     documentationComponents = {};

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

@@ -41,6 +41,7 @@ declare const buildComponentCss: (data: TransformComponentTokensResult, handoff:
     };
     validations?: Record<string, import("../../../types").ValidationResult>;
     page?: import("../types").ComponentPageDefinition;
+    docgen?: import("handoff-docgen").GeneratedDocs;
 }>;
 /**
  * Build the main CSS file using Vite

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

@@ -1,3 +1,4 @@
+import type { DocAnnotation, TypeNode } from 'handoff-docgen';
 import Handoff from '../../index';
 export interface ComponentMetadata {
     title: string;
@@ -38,6 +39,11 @@ export interface SlotMetadata {
     };
     key?: string;
     rules?: RuleObject;
+    docgenType?: string;
+    deepType?: TypeNode;
+    typeRefs?: string[];
+    warnings?: string[];
+    annotations?: DocAnnotation[];
 }
 export type RuleObject = {
     required?: boolean;

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

@@ -1,4 +1,5 @@
 import { Card } from '../../app/components/Component/Cards';
+import type { GeneratedDocs } from 'handoff-docgen';
 import { ValidationResult } from '../../types';
 import { Filter } from '../../utils/filter';
 import { SlotMetadata } from './component';
@@ -159,6 +160,7 @@ export type TransformComponentTokensResult = {
     };
     validations?: Record<string, ValidationResult>;
     page?: ComponentPageDefinition;
+    docgen?: GeneratedDocs;
 } | null;
 export type OptionalPreviewRender = {
     title: string;

package/dist/transformers/types.d.ts

@@ -2,24 +2,6 @@ import { Types as CoreTypes } from 'handoff-core';
 import { Plugin } from 'vite';
 import { SlotMetadata } from './preview/component';
 import { TransformComponentTokensResult } from './preview/types';
-/**
- * Configuration for react-docgen-typescript parser
- */
-export interface DocgenParserConfig {
-    savePropValueAsString: boolean;
-    shouldExtractLiteralValuesFromEnum: boolean;
-    shouldRemoveUndefinedFromOptional: boolean;
-    propFilter: (prop: any) => boolean;
-}
-/**
- * Result from react-docgen-typescript parsing
- */
-export interface DocgenResult {
-    props: {
-        [key: string]: any;
-    };
-    [key: string]: any;
-}
 /**
  * Module evaluation result
  */

package/dist/transformers/utils/schema-loader.js

@@ -43,7 +43,7 @@ const loadSchemaFromFile = (schemaPath, handoff) => __awaiter(void 0, void 0, vo
         }
         else if (schema) {
             // Schema exists but is not a valid schema object (e.g., type/interface)
-            // Use react-docgen-typescript to document the schema file
+            // Use handoff-docgen to document the schema file
             return yield (0, docgen_1.generatePropertiesFromDocgen)(schemaPath, handoff);
         }
         return null;
@@ -72,7 +72,7 @@ const loadSchemaFromComponent = (componentExports, handoff) => __awaiter(void 0,
     }
     else if (schema) {
         // Schema exists but is not a valid schema object (e.g., type/interface)
-        // Use react-docgen-typescript to document the schema
+        // Use handoff-docgen to document the schema
         return yield (0, docgen_1.generatePropertiesFromDocgen)(componentExports.__filename || '', handoff);
     }
     return null;

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

@@ -10,8 +10,8 @@ export declare const ensureIds: (properties: {
     [key: string]: SlotMetadata;
 };
 /**
- * Converts react-docgen-typescript props to our SlotMetadata format
- * @param docgenProps - Array of props from react-docgen-typescript
+ * Converts baseline docgen props to our SlotMetadata format
+ * @param docgenProps - Array of props from a docgen parser
  * @returns Converted properties object
  */
 export declare const convertDocgenToProperties: (docgenProps: any[]) => {

package/dist/transformers/utils/schema.js

@@ -470,8 +470,8 @@ const ensureNestedParsing = (metadata) => {
     return metadata;
 };
 /**
- * Converts react-docgen-typescript props to our SlotMetadata format
- * @param docgenProps - Array of props from react-docgen-typescript
+ * Converts baseline docgen props to our SlotMetadata format
+ * @param docgenProps - Array of props from a docgen parser
  * @returns Converted properties object
  */
 const convertDocgenToProperties = (docgenProps) => {

package/dist/types/config.d.ts

@@ -74,6 +74,21 @@ export interface Config {
     exportsOutputDirectory?: string;
     sitesOutputDirectory?: string;
     useVariables?: boolean;
+    /**
+     * Configuration for React component docs generation (handoff-docgen).
+     */
+    reactDocgen?: {
+        /**
+         * Maximum recursion depth for nested type traversal.
+         * @default 7
+         */
+        maxDepth?: number;
+        /**
+         * Directory names to exclude while scanning for components.
+         * @default ["dist", "build", ".next"]
+         */
+        excludeDirectories?: string[];
+    };
     app?: NextAppConfig;
     /**
      * Configuration for the build pipeline

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import { Types as CoreTypes } from 'handoff-core';
+import type { GeneratedDocs } from 'handoff-docgen';
 import { SlotMetadata } from './transformers/preview/component';
 import { ComponentPageDefinition } from './transformers/preview/types';
 import { type Filter } from './utils/filter';
@@ -74,6 +75,7 @@ export interface PreviewObject {
      */
     validations?: Record<string, ValidationResult>;
     page?: ComponentPageDefinition;
+    docgen?: GeneratedDocs;
 }
 export type PreviewJson = {
     components: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-app",
-  "version": "1.0.6",
+  "version": "1.1.0-canary.1",
   "description": "Automated documentation toolchain for building client side documentation from figma",
   "author ": {
     "name": "Convertiv",
@@ -100,6 +100,7 @@
     "gray-matter": "^4.0.3",
     "handlebars": "^4.7.8",
     "handoff-core": "^0.2.0",
+    "handoff-docgen": "^0.1.0",
     "html-react-parser": "^5.2.5",
     "jquery": "^3.6.1",
     "lodash": "^4.17.21",