handoff-app 1.1.0 → 1.1.2-0

package/src/cache/build-cache.ts

@@ -2,6 +2,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import Handoff from '../index';
 import { Logger } from '../utils/logger';
+import { normalizePathForCompare } from '../utils/path';
 import { computeDirectoryState, computeFileState, directoryStatesMatch, FileState, statesMatch } from './file-state';
 
 /** Current cache format version - bump when structure changes */
@@ -162,25 +163,18 @@ export function getComponentFilePaths(handoff: Handoff, componentId: string): {
 
   const files: string[] = [];
   let templateDir: string | undefined;
+  const componentDirs = new Set<string>();
 
-  // Find the config file path for this component
-  const configPaths = handoff.getConfigFilePaths();
-  for (const configPath of configPaths) {
-    // Check if this config path belongs to this component
-    if (configPath.includes(componentId)) {
-      files.push(configPath);
-      break;
-    }
-  }
-
-  // Add entry files
+  // Add entry files and infer component directories from resolved entry paths
   const entries = runtimeComponent.entries as Record<string, string | undefined> | undefined;
   if (entries) {
     if (entries.js) {
       files.push(entries.js);
+      componentDirs.add(normalizePathForCompare(path.dirname(entries.js)));
     }
     if (entries.scss) {
       files.push(entries.scss);
+      componentDirs.add(normalizePathForCompare(path.dirname(entries.scss)));
     }
     // Handle both 'template' (singular) and 'templates' (plural) entry types
     const templatePath = entries.template || entries.templates;
@@ -189,16 +183,40 @@ export function getComponentFilePaths(handoff: Handoff, componentId: string): {
         const stat = fs.statSync(templatePath);
         if (stat.isDirectory()) {
           templateDir = templatePath;
+          componentDirs.add(normalizePathForCompare(templatePath));
         } else {
           files.push(templatePath);
+          componentDirs.add(normalizePathForCompare(path.dirname(templatePath)));
         }
       } catch {
         // File doesn't exist, still add to track
         files.push(templatePath);
+        componentDirs.add(normalizePathForCompare(path.dirname(templatePath)));
       }
     }
   }
 
+  // Find the config file path for this component using exact config filename + directory matching.
+  const configPaths = handoff.getConfigFilePaths();
+  const expectedConfigFileNames = new Set([`${componentId}.json`, `${componentId}.js`, `${componentId}.cjs`]);
+  const matchingConfigPath = configPaths.find((configPath) => {
+    const configFileName = path.basename(configPath);
+    if (!expectedConfigFileNames.has(configFileName)) {
+      return false;
+    }
+
+    if (componentDirs.size === 0) {
+      return true;
+    }
+
+    const configDir = normalizePathForCompare(path.dirname(configPath));
+    return componentDirs.has(configDir);
+  });
+
+  if (matchingConfigPath) {
+    files.push(matchingConfigPath);
+  }
+
   return { files, templateDir };
 }
 

package/src/cli.ts

@@ -19,7 +19,7 @@ class HandoffCliError extends Error {
  * Show the help message
  */
 const showVersion = () => {
-  return 'Handoff App - 1.1.0';
+  return 'Handoff App - 1.1.2';
 };
 
 /**

package/src/index.ts

@@ -297,7 +297,7 @@ class Handoff {
 }
 
 export type { ComponentObject as Component } from './transformers/preview/types';
-export type { Config } from './types/config';
+export type { Config, RegisterHandlebarsHelpersContext } from './types/config';
 
 // Export transformers and types from handoff-core
 export { Transformers as CoreTransformers, TransformerUtils as CoreTransformerUtils, Types as CoreTypes } from 'handoff-core';

package/src/transformers/plugins/handlebars-previews.ts

@@ -69,12 +69,14 @@ async function renderHandlebarsTemplate(
   template: string,
   componentData: TransformComponentTokensResult,
   previewData: PreviewRenderData,
-  injectFieldWrappers: boolean
+  injectFieldWrappers: boolean,
+  handoff: Handoff
 ): Promise<string> {
   // Register Handlebars helpers with current injection state
   registerHandlebarsHelpers(
-    { id: componentData.id, properties: componentData.properties || {} }, 
-    injectFieldWrappers
+    { id: componentData.id, properties: componentData.properties || {} },
+    injectFieldWrappers,
+    handoff.config?.hooks?.registerHandlebarsHelpers
   );
 
   const context = createHandlebarsContext({ 
@@ -158,6 +160,17 @@ export function handlebarsPreviewsPlugin(
       // Process component instances from documentation
       processComponentInstances(componentData, documentationComponents);
 
+      if (!componentData.previews || Object.keys(componentData.previews).length === 0) {
+        Logger.warn(`No previews defined for ${componentId}; using default preview values.`);
+        componentData.previews = {
+          default: {
+            title: 'Default',
+            values: {},
+            url: '',
+          },
+        };
+      }
+
       const generatedPreviews: { [key: string]: string } = {};
 
       // Generate previews for each variation
@@ -170,14 +183,16 @@ export function handlebarsPreviewsPlugin(
             templateContent,
             componentData,
             previewData,
-            false
+            false,
+            handoff
           );
 
           const inspectModeHtml = await renderHandlebarsTemplate(
             templateContent,
             componentData,
             previewData,
-            true
+            true,
+            handoff
           );
 
           // Emit preview files
@@ -202,7 +217,8 @@ export function handlebarsPreviewsPlugin(
       componentData.format = PLUGIN_CONSTANTS.OUTPUT_FORMAT;
       componentData.preview = '';
       componentData.code = trimPreview(templateContent);
-      componentData.html = trimPreview(generatedPreviews[Object.keys(generatedPreviews)[0]]);
+      const firstGeneratedPreview = Object.values(generatedPreviews)[0];
+      componentData.html = trimPreview(firstGeneratedPreview ?? templateContent);
     },
   };
 }

package/src/transformers/preview/component/builder.ts

@@ -62,6 +62,19 @@ type ComponentBuildPlan = {
   validationMode: boolean;
 };
 
+const ensureDefaultPreview = (data: TransformComponentTokensResult): void => {
+  if (!data) return;
+  if (!data.previews || Object.keys(data.previews).length === 0) {
+    data.previews = {
+      default: {
+        title: 'Default',
+        values: {},
+        url: '',
+      },
+    };
+  }
+};
+
 /**
  * Returns a normalized build plan describing which component segments need rebuilding.
  *
@@ -223,7 +236,7 @@ export async function processComponents(
     // those will override this default (standard "config overrides defaults" behavior).
     if (!restMetadata.figmaComponentId) {
       componentDefaults.previews = {
-        generic: {
+        default: {
           title: 'Default',
           values: {},
           url: '',
@@ -276,6 +289,9 @@ export async function processComponents(
       }
     }
 
+    // Components should always have at least one preview variation.
+    ensureDefaultPreview(data);
+
     // Build JS if needed (new build, validation missing, or explicit segment request).
     if (buildPlan.js) {
       data = await buildComponentJs(data, handoff);

package/src/transformers/utils/handlebars.ts

@@ -1,16 +1,19 @@
 import Handlebars from 'handlebars';
+import { RegisterHandlebarsHelpersContext } from '../../types/config';
 import { Logger } from '../../utils/logger';
 import { SlotMetadata } from '../preview/component';
 import { HandlebarsContext } from '../types';
 
 /**
- * Registers common Handlebars helpers
+ * Registers common Handlebars helpers, then runs optional `hooks.registerHandlebarsHelpers`.
  * @param data - Component data containing properties
  * @param injectFieldWrappers - Whether to inject field wrappers for inspection
+ * @param extend - Optional callback from config to register additional helpers
  */
 export const registerHandlebarsHelpers = (
   data: { properties: { [key: string]: SlotMetadata }; id: string },
-  injectFieldWrappers: boolean
+  injectFieldWrappers: boolean,
+  extend?: (context: RegisterHandlebarsHelpersContext) => void
 ): void => {
   // Field helper for property binding
   Handlebars.registerHelper('field', function (field: string, options: any) {
@@ -20,21 +23,21 @@ export const registerHandlebarsHelpers = (
         // Logger.error(`Missing field declaration for ${data.id}`);
         return options.fn(this);
       }
-      
+
       let parts = field.split('.');
       let current: any = data.properties;
-      
+
       for (const part of parts) {
         if (current?.type === 'object') current = current.properties;
         else if (current?.type === 'array') current = current.items.properties;
         current = current?.[part];
       }
-      
+
       if (!current) {
         Logger.error(`Undefined field path for ${data.id}`);
         return options.fn(this);
       }
-      
+
       return new Handlebars.SafeString(
         `<span class="handoff-field handoff-field-${current?.type || 'unknown'}" data-handoff-field="${field}" data-handoff="${encodeURIComponent(JSON.stringify(current))}">${options.fn(this)}</span>`
       );
@@ -47,6 +50,13 @@ export const registerHandlebarsHelpers = (
   Handlebars.registerHelper('eq', function (a: any, b: any) {
     return a === b;
   });
+
+  extend?.({
+    handlebars: Handlebars,
+    componentId: data.id,
+    properties: data.properties,
+    injectFieldWrappers,
+  });
 };
 
 /**
@@ -61,9 +71,7 @@ export const createHandlebarsContext = (
   options?: { includeSharedStyles?: boolean }
 ): HandlebarsContext => {
   const basePath = process.env.HANDOFF_APP_BASE_PATH ?? '';
-  const sharedStylesLink = options?.includeSharedStyles
-    ? `<link rel="stylesheet" href="${basePath}/api/component/shared.css">`
-    : '';
+  const sharedStylesLink = options?.includeSharedStyles ? `<link rel="stylesheet" href="${basePath}/api/component/shared.css">` : '';
 
   return {
     style:

package/src/transformers/utils/html.ts

@@ -7,9 +7,22 @@ import prettier from 'prettier';
  * @returns Trimmed HTML content
  */
 export const trimPreview = (preview: string): string => {
-  const bodyEl = parse(preview).querySelector('body');
-  const code = bodyEl ? bodyEl.innerHTML.trim() : preview;
-  return code;
+  if (typeof preview !== 'string') {
+    return '';
+  }
+
+  const normalizedPreview = preview.trim();
+  if (!normalizedPreview) {
+    return '';
+  }
+
+  try {
+    const bodyEl = parse(normalizedPreview).querySelector('body');
+    return bodyEl ? bodyEl.innerHTML.trim() : normalizedPreview;
+  } catch {
+    // Keep build resilient if parser fails on malformed HTML.
+    return normalizedPreview;
+  }
 };
 
 /**

package/src/types/config.ts

@@ -1,4 +1,5 @@
 import { BuildOptions } from 'esbuild';
+import type Handlebars from 'handlebars';
 import { Types as HandoffTypes } from 'handoff-core';
 import { InlineConfig } from 'vite';
 import { SlotMetadata } from '../transformers/preview/component';
@@ -47,6 +48,14 @@ export interface Breakpoints {
   desktop: { size: number; name: string };
 }
 
+/** Context passed to the `registerHandlebarsHelpers` config hook after built-in helpers (`field`, `eq`) are registered for a preview render. */
+export type RegisterHandlebarsHelpersContext = {
+  handlebars: typeof Handlebars;
+  componentId: string;
+  properties: { [key: string]: SlotMetadata };
+  injectFieldWrappers: boolean;
+};
+
 export interface NextAppConfig {
   theme?: string;
   title: string;
@@ -240,6 +249,22 @@ export interface Config {
      * ```
      */
     htmlBuildConfig?: (config: InlineConfig) => InlineConfig;
+
+    /**
+     * Optional hook invoked after Handoff registers built-in Handlebars helpers for
+     * component preview HTML. Use `context.handlebars.registerHelper` to add or
+     * replace helpers. Called once per preview render (per variation and inspect mode).
+     *
+     * @param context - Handlebars runtime, component id/properties, and whether
+     *   inspect field wrappers are enabled for this render.
+     * @example
+     * ```typescript
+     * registerHandlebarsHelpers: ({ handlebars, componentId }) => {
+     *   handlebars.registerHelper('upperId', () => componentId.toUpperCase());
+     * }
+     * ```
+     */
+    registerHandlebarsHelpers?: (context: RegisterHandlebarsHelpersContext) => void;
   };
 }
 

package/src/utils/path.ts

@@ -1,3 +1,5 @@
+import path from 'path';
+
 /**
  * Generates a filesystem-safe directory name from an absolute path
  * @param workingPath - The absolute working path to transform
@@ -30,3 +32,30 @@ export function generateFilesystemSafeId(workingPath: string): string {
   return safeId;
 }
 
+/**
+ * Normalize a filesystem path for cross-platform string comparison.
+ * - Resolves to absolute path
+ * - Normalizes separators to forward slashes
+ * - Lowercases on Windows where paths are case-insensitive
+ */
+export function normalizePathForCompare(inputPath: string): string {
+  const normalized = path.resolve(inputPath).replace(/\\/g, '/');
+  return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+
+/**
+ * True when both paths resolve to the same normalized filesystem path.
+ */
+export function arePathsEqual(pathA: string, pathB: string): boolean {
+  return normalizePathForCompare(pathA) === normalizePathForCompare(pathB);
+}
+
+/**
+ * True when childPath is equal to or within parentPath.
+ */
+export function isPathInside(childPath: string, parentPath: string): boolean {
+  const normalizedChild = normalizePathForCompare(childPath);
+  const normalizedParent = normalizePathForCompare(parentPath);
+  return normalizedChild === normalizedParent || normalizedChild.startsWith(`${normalizedParent}/`);
+}
+

package/templates/default/handoff.config.js.tpl

@@ -183,5 +183,21 @@ module.exports = {
     //   // Add your custom HTML build configuration here
     //   return config;
     // },
+
+    /**
+     * Optional hook run after built-in Handlebars helpers (`field`, `eq`) for preview HTML.
+     * @param context.handlebars - Handlebars module (use registerHelper)
+     * @param context.componentId - Current component id
+     * @param context.properties - Slot metadata map from the schema
+     * @param context.injectFieldWrappers - True when generating inspect-mode previews
+     *
+     * @example
+     * registerHandlebarsHelpers: ({ handlebars, componentId }) => {
+     *   handlebars.registerHelper('upperId', () => componentId.toUpperCase());
+     * }
+     */
+    // registerHandlebarsHelpers: ({ handlebars, componentId, properties, injectFieldWrappers }) => {
+    //   // Add your custom Handlebars helpers here
+    // },
   },
 };

package/templates/default/handoff.config.with-examples.js.tpl

@@ -184,5 +184,21 @@ module.exports = {
     //   // Add your custom HTML build configuration here
     //   return config;
     // },
+
+    /**
+     * Optional hook run after built-in Handlebars helpers (`field`, `eq`) for preview HTML.
+     * @param context.handlebars - Handlebars module (use registerHelper)
+     * @param context.componentId - Current component id
+     * @param context.properties - Slot metadata map from the schema
+     * @param context.injectFieldWrappers - True when generating inspect-mode previews
+     *
+     * @example
+     * registerHandlebarsHelpers: ({ handlebars, componentId }) => {
+     *   handlebars.registerHelper('upperId', () => componentId.toUpperCase());
+     * }
+     */
+    // registerHandlebarsHelpers: ({ handlebars, componentId, properties, injectFieldWrappers }) => {
+    //   // Add your custom Handlebars helpers here
+    // },
   },
 };