handoff-app 2.0.0-8 → 2.0.0

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

@@ -1,9 +1,11 @@
 import fs from 'fs-extra';
 import path from 'path';
 import { InlineConfig, build as viteBuild } from 'vite';
+import { BuildInputs, withBuildInputs } from '../../../cache/build-inputs';
 import Handoff from '../../../index';
 import { formatDurationMs } from '../../../utils/duration';
 import { Logger } from '../../../utils/logger';
+import { collectStyleImports } from '../../utils/build';
 import viteBaseConfig from '../../vite-config';
 import { getComponentOutputPath } from '../component';
 import { TransformComponentTokensResult } from '../types';
@@ -21,6 +23,7 @@ export const SHARED_COMPONENT_CSS_FILE = 'shared.css';
  * @param options.outputFilename - The name of the output file
  * @param options.loadPaths - Array of paths for SASS to look for imports
  * @param options.handoff - The Handoff configuration object
+ * @param options.inputs - Collects the files that the build reads, for the build cache
  */
 const buildCssBundle = async ({
   entry,
@@ -28,12 +31,14 @@ const buildCssBundle = async ({
   outputFilename,
   loadPaths,
   handoff,
+  inputs,
 }: {
   entry: string;
   outputPath: string;
   outputFilename: string;
   loadPaths: string[];
   handoff: Handoff;
+  inputs?: BuildInputs;
 }): Promise<void> => {
   // Store the current NODE_ENV value
   const oldNodeEnv = process.env.NODE_ENV;
@@ -84,7 +89,7 @@ const buildCssBundle = async ({
       viteConfig = handoff.config.hooks.cssBuildConfig(viteConfig);
     }
 
-    await viteBuild(viteConfig);
+    await viteBuild(withBuildInputs(viteConfig, inputs));
   } catch (e) {
     Logger.error(`Failed to build CSS for "${entry}"`);
     throw e;
@@ -98,14 +103,56 @@ const buildCssBundle = async ({
   }
 };
 
-const buildComponentCss = async (data: TransformComponentTokensResult, handoff: Handoff) => {
+const STYLE_SOURCE_EXTENSIONS = new Set(['.scss', '.sass', '.css']);
+
+/**
+ * The stylesheets of one item, in cascade order and deduplicated by resolved path.
+ *
+ * Discovered imports come first and the declared entry last, so a declared entry can override what
+ * the component imports. A project that both declares and imports one file must build it once.
+ */
+const resolveStyleSources = async (data: TransformComponentTokensResult, handoff: Handoff): Promise<string[]> => {
+  const template = data.entries?.template;
+  const discovered = template ? await collectStyleImports(path.resolve(template), handoff) : [];
+  const declared = data.entries?.scss ? [path.resolve(data.entries.scss)] : [];
+
+  const ordered: string[] = [];
+  const seen = new Set<string>();
+
+  for (const source of [...discovered, ...declared]) {
+    if (!seen.has(source) && STYLE_SOURCE_EXTENSIONS.has(path.extname(source)) && fs.existsSync(source)) {
+      seen.add(source);
+      ordered.push(source);
+    }
+  }
+
+  return ordered;
+};
+
+/**
+ * A single Sass entry that `@use`s every source in order.
+ *
+ * `@use` emits a repeated file once and inlines a plain `.css` source, which `@import` would leave
+ * as an unresolvable URL. Namespaces are explicit because two sources sharing a basename would
+ * claim the same default namespace and fail the compile.
+ */
+const writeCombinedStyleEntry = async (sources: string[], outputPath: string, id: string): Promise<string> => {
+  const entryPath = path.resolve(outputPath, `.${id}.entry.scss`);
+  const rules = sources.map((source, index) => `@use '${source.split(path.sep).join('/')}' as ns${index};`);
+
+  await fs.outputFile(entryPath, `${rules.join('\n')}\n`);
+
+  return entryPath;
+};
+
+const buildComponentCss = async (data: TransformComponentTokensResult, handoff: Handoff, inputs?: BuildInputs) => {
   const id = data.id;
   Logger.debug(`buildComponentCss`, id);
   const outputPath = getComponentOutputPath(handoff);
   const builtCssPath = path.resolve(outputPath, `${id}.css`);
-  const entry = data.entries?.scss;
+  const sources = await resolveStyleSources(data, handoff);
 
-  if (!entry) {
+  if (sources.length === 0) {
     // Keep generated output aligned with the current component declaration.
     await fs.remove(builtCssPath);
     delete data['css'];
@@ -114,64 +161,65 @@ const buildComponentCss = async (data: TransformComponentTokensResult, handoff:
     return data;
   }
 
-  const extension = path.extname(entry);
-
-  if (!extension) {
-    return data;
-  }
+  // A single source compiles directly, so its relative asset URLs and documented Sass stay as authored.
+  const combinedEntry = sources.length > 1 ? await writeCombinedStyleEntry(sources, outputPath, id) : undefined;
+  const entry = combinedEntry ?? sources[0];
 
   try {
-    if (extension === '.scss' || extension === '.css') {
-      // Remove the previous artifact before rebuilding so "no emitted CSS"
-      // doesn't silently preserve stale output from an earlier build.
-      await fs.remove(builtCssPath);
-
-      // Read the original source
-      const sourceContent = await fs.readFile(entry, 'utf8');
-      if (extension === '.scss') {
-        data['sass'] = sourceContent;
-      }
+    // Remove the previous artifact before rebuilding so "no emitted CSS"
+    // doesn't silently preserve stale output from an earlier build.
+    await fs.remove(builtCssPath);
+
+    // Read the original source
+    const primarySource = data.entries?.scss ? path.resolve(data.entries.scss) : sources[0];
+    if (path.extname(primarySource) === '.scss') {
+      data['sass'] = await fs.readFile(primarySource, 'utf8');
+    }
 
-      // Setup SASS load paths
-      const loadPaths = [
-        path.resolve(handoff.workingPath),
-        path.resolve(handoff.workingPath, handoff.exportsDirectory, handoff.getProjectId()),
-        path.resolve(handoff.workingPath, 'node_modules'),
-      ];
+    // Setup SASS load paths
+    const loadPaths = [
+      path.resolve(handoff.workingPath),
+      handoff.getOutputPath(),
+      path.resolve(handoff.workingPath, 'node_modules'),
+    ];
 
-      if (handoff.runtimeConfig?.entries?.scss) {
-        loadPaths.unshift(path.dirname(handoff.runtimeConfig.entries.scss));
-      }
+    if (handoff.runtimeConfig?.entries?.scss) {
+      loadPaths.unshift(path.dirname(handoff.runtimeConfig.entries.scss));
+    }
+
+    await buildCssBundle({
+      entry,
+      outputPath,
+      outputFilename: `${id}.css`,
+      loadPaths,
+      handoff,
+      inputs,
+    });
 
-      await buildCssBundle({
-        entry,
-        outputPath,
-        outputFilename: `${id}.css`,
-        loadPaths,
-        handoff,
-      });
-
-      // Read the built CSS
-      if (fs.existsSync(builtCssPath)) {
-        const builtCss = await fs.readFile(builtCssPath, 'utf8');
-        data['css'] = builtCss;
-
-        // Handle shared styles — if the component SCSS uses the split marker,
-        // extract shared styles from the portion above it
-        const splitCSS = builtCss.split('/* COMPONENT STYLES*/');
-        if (splitCSS && splitCSS.length > 1) {
-          data['css'] = splitCSS[1];
-          data['sharedStyles'] = splitCSS[0];
-          await fs.writeFile(path.resolve(outputPath, SHARED_COMPONENT_CSS_FILE), data['sharedStyles']);
-        }
-      } else {
-        delete data['css'];
-        delete data['sharedStyles'];
+    // Read the built CSS
+    if (fs.existsSync(builtCssPath)) {
+      const builtCss = await fs.readFile(builtCssPath, 'utf8');
+      data['css'] = builtCss;
+
+      // Handle shared styles — if the component SCSS uses the split marker,
+      // extract shared styles from the portion above it
+      const splitCSS = builtCss.split('/* COMPONENT STYLES*/');
+      if (splitCSS && splitCSS.length > 1) {
+        data['css'] = splitCSS[1];
+        data['sharedStyles'] = splitCSS[0];
+        await fs.writeFile(path.resolve(outputPath, SHARED_COMPONENT_CSS_FILE), data['sharedStyles']);
       }
+    } else {
+      delete data['css'];
+      delete data['sharedStyles'];
     }
   } catch (e) {
     Logger.error(`Failed to build CSS for "${id}"`);
     throw e;
+  } finally {
+    if (combinedEntry) {
+      await fs.remove(combinedEntry);
+    }
   }
 
   return data;
@@ -199,7 +247,7 @@ export const buildMainCss = async (handoff: Handoff): Promise<void> => {
         const loadPaths = [
           path.dirname(scssEntry),
           path.resolve(handoff.workingPath),
-          path.resolve(handoff.workingPath, handoff.exportsDirectory, handoff.getProjectId()),
+          handoff.getOutputPath(),
           path.resolve(handoff.workingPath, 'node_modules'),
         ];
 

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

@@ -1,6 +1,7 @@
 import react from '@vitejs/plugin-react';
 import { Types as CoreTypes } from 'handoff-core';
 import { InlineConfig, PluginOption, build as viteBuild } from 'vite';
+import { BuildInputs, withBuildInputs } from '../../../cache/build-inputs';
 import type { RendererKind, SourceFormat } from '../../../catalog/renderers';
 import Handoff from '../../../index';
 import { Logger } from '../../../utils/logger';
@@ -35,6 +36,7 @@ const RENDERER_PLUGINS: Record<RendererKind, PreviewPlugins> = {
  * @param data - The result of transforming component tokens.
  * @param handoff - The Handoff configuration object.
  * @param components - Optional file components object.
+ * @param inputs - Collects the files that the build reads, for the build cache.
  * @returns A promise that resolves to the transformed component tokens result.
  * @throws Will throw an error if the Vite build process fails.
  *
@@ -46,7 +48,8 @@ const RENDERER_PLUGINS: Record<RendererKind, PreviewPlugins> = {
 export const buildPreviews = async (
   data: TransformComponentTokensResult,
   handoff: Handoff,
-  components?: CoreTypes.IDocumentationObject['components']
+  components?: CoreTypes.IDocumentationObject['components'],
+  inputs?: BuildInputs
 ): Promise<TransformComponentTokensResult> => {
   if (!data.entries?.template) return data;
 
@@ -87,8 +90,9 @@ export const buildPreviews = async (
       viteConfig = handoff.config.hooks.htmlBuildConfig(viteConfig);
     }
 
-    await viteBuild(viteConfig);
+    await viteBuild(withBuildInputs(viteConfig, inputs));
   } catch (error) {
+    if (inputs) inputs.failed = true;
     Logger.error(`Error building component previews: ${data.entries.template}`, error);
   } finally {
     // Restore the original NODE_ENV value after vite build completes

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

@@ -1,6 +1,7 @@
 import fs from 'fs-extra';
 import path from 'path';
 import { InlineConfig, build as viteBuild } from 'vite';
+import { BuildInputs, withBuildInputs } from '../../../cache/build-inputs';
 import Handoff from '../../../index';
 import { formatDurationMs } from '../../../utils/duration';
 import { Logger } from '../../../utils/logger';
@@ -17,6 +18,7 @@ export const MAIN_COMPONENT_JS_FILE = 'main.js';
  * @param options.entry - The entry file path for the bundle
  * @param options.outputPath - The directory where the bundle will be output
  * @param options.outputFilename - The name of the output file
+ * @param inputs - Collects the files that the build reads, for the build cache
  */
 const buildJsBundle = async (
   {
@@ -25,7 +27,8 @@ const buildJsBundle = async (
     outputFilename,
     format = 'cjs',
   }: { entry: string; outputPath: string; outputFilename: string; format?: 'cjs' | 'iife' },
-  handoff: Handoff
+  handoff: Handoff,
+  inputs?: BuildInputs
 ) => {
   const absEntryPath = path.resolve(entry);
 
@@ -62,7 +65,7 @@ const buildJsBundle = async (
       viteConfig = handoff.config.hooks.jsBuildConfig(viteConfig);
     }
 
-    await viteBuild(viteConfig);
+    await viteBuild(withBuildInputs(viteConfig, inputs));
   } finally {
     // Restore the original NODE_ENV value after vite build completes
     // This prevents interference with Next.js app building/running processes
@@ -84,7 +87,11 @@ const buildJsBundle = async (
  * @param handoff - The Handoff configuration object
  * @returns The updated component transformation result with JavaScript data
  */
-export const buildComponentJs = async (data: TransformComponentTokensResult, handoff: Handoff): Promise<TransformComponentTokensResult> => {
+export const buildComponentJs = async (
+  data: TransformComponentTokensResult,
+  handoff: Handoff,
+  inputs?: BuildInputs
+): Promise<TransformComponentTokensResult> => {
   const id = data.id;
   const outputPath = getComponentOutputPath(handoff);
   const builtJsPath = path.resolve(outputPath, `${id}.js`);
@@ -111,9 +118,11 @@ export const buildComponentJs = async (data: TransformComponentTokensResult, han
           outputPath,
           outputFilename: `${id}.js`,
         },
-        handoff
+        handoff,
+        inputs
       );
     } catch (e) {
+      if (inputs) inputs.failed = true;
       Logger.error(`Failed to bundle JS for component "${id}" (${id}.js):`, e);
       return data;
     }
@@ -126,6 +135,7 @@ export const buildComponentJs = async (data: TransformComponentTokensResult, han
       delete data['jsCompiled'];
     }
   } catch (e) {
+    if (inputs) inputs.failed = true;
     Logger.error(`JS build failed for component "${id}":`, e);
   }
 

package/src/transformers/preview/pattern/html.ts

@@ -56,7 +56,9 @@ export const composePatternHtml = (
       }
     }
 
-    const doc = parse(html);
+    // React SSR separates adjacent text children with `<!-- -->`. The parser drops comments by
+    // default, which would make every composed React fragment fail to hydrate.
+    const doc = parse(html, { comment: true });
     const suffix = `_p${i}`;
     const namespacedRootId = `root${suffix}`;
     const namespacedPropsId = `__APP_PROPS__${suffix}`;

package/src/transformers/preview/types.ts

@@ -18,6 +18,9 @@ export interface BasePageSlice {
   type: PageSliceType;
 }
 
+/** A fluid preview renders at the width the reader's stage has, so it is never scaled down. */
+export type PreviewWidth = 'fluid' | number;
+
 export interface BestPracticesPageSlice extends BasePageSlice {
   type: 'BEST_PRACTICES';
 }
@@ -27,6 +30,8 @@ export interface ComponentDisplayPageSlice extends BasePageSlice {
   showPreview?: boolean;
   showCodeHighlight?: boolean;
   defaultHeight?: string;
+  /** Viewport width for the preview, in pixels. Defaults to 'fluid'. */
+  defaultWidth?: PreviewWidth;
   filterBy?: Filter;
 }
 
@@ -115,6 +120,8 @@ export type ComponentObject = {
     story?: string;
     /** Optional path to schema file (if available) */
     schema?: string;
+    /** Declaration file path; a preview `render` is read from it at build and hydration time. */
+    declaration?: string;
     /** Optional path to templates directory */
     templates?: string;
   };
@@ -192,6 +199,8 @@ export type TransformComponentTokensResult = {
     story?: string;
     schema?: string;
     templates?: string;
+    /** See `ComponentObject.entries.declaration`. */
+    declaration?: string;
   };
   renderer?: RendererKind;
   /** See `ComponentObject.sourceFormat`. Distinct from `format`, the preview's code language. */
@@ -212,6 +221,11 @@ export type OptionalPreviewRender = {
   values: { [key: string]: string | string[] | any };
   url: string;
   usage?: string;
+  /**
+   * Build-time only: the server renders it and the client re-reads it from the declaration module.
+   * `JSON.stringify` drops it from published artifacts.
+   */
+  render?: (args: Record<string, any>) => unknown;
   /** Optional source preview/story key used to derive this preview */
   sourcePreview?: string;
 };

package/src/transformers/utils/build.ts

@@ -1,6 +1,21 @@
 import esbuild from 'esbuild';
 import path from 'path';
 
+const STYLE_EXTENSIONS = ['.css', '.scss', '.sass'];
+
+/**
+ * Keeps co-located stylesheet imports out of the JavaScript graph; the CSS pipeline compiles them.
+ *
+ * esbuild has no `.scss` loader, and a `.css` import fails too because these builds run with
+ * `write: false` and no output path. `empty` rather than a plugin: `esbuild.buildSync` rejects
+ * plugins, and the declaration and config loaders are synchronous.
+ *
+ * CSS Modules are not covered — the empty module leaves the class map undefined.
+ */
+export const STYLE_IMPORT_LOADERS: Record<string, esbuild.Loader> = Object.fromEntries(
+  STYLE_EXTENSIONS.map((extension) => [extension, 'empty' as esbuild.Loader])
+);
+
 /**
  * Default esbuild configuration for SSR builds
  */
@@ -11,6 +26,7 @@ export const DEFAULT_SSR_BUILD_CONFIG: esbuild.BuildOptions = {
   platform: 'node',
   jsx: 'automatic',
   external: ['react', 'react-dom', '@opentelemetry/api'],
+  loader: STYLE_IMPORT_LOADERS,
 };
 
 /**
@@ -24,8 +40,85 @@ export const DEFAULT_CLIENT_BUILD_CONFIG: esbuild.BuildOptions = {
   jsx: 'automatic',
   sourcemap: false,
   minify: false,
+  loader: STYLE_IMPORT_LOADERS,
 };
 
+/** Apply after a consumer hook: a hook that replaces `loader` would otherwise drop these. */
+export function withStyleLoaders<T extends esbuild.BuildOptions>(config: T): T {
+  return { ...config, loader: { ...config.loader, ...STYLE_IMPORT_LOADERS } };
+}
+
+/**
+ * Stylesheets of the module graph in cascade order: every import of a module before the module
+ * itself, siblings in source order.
+ *
+ * This is the order a bundler emits CSS in, and the cascade depends on it. A component that
+ * overrides a rule of a component it imports ties that rule on specificity, so the later of the
+ * two wins. esbuild's `onLoad` callbacks do not give this order: they fire roughly breadth-first,
+ * which puts a component's own stylesheet ahead of the ones it imports and reverses every such
+ * override.
+ */
+function orderStyleImports(metafile: esbuild.Metafile, entryPath: string): string[] {
+  const entryKey = Object.keys(metafile.inputs).find((key) => path.resolve(key) === entryPath);
+  if (!entryKey) return [];
+
+  const ordered: string[] = [];
+  const visited = new Set<string>();
+
+  const visit = (key: string) => {
+    if (visited.has(key)) return;
+    visited.add(key);
+
+    for (const imported of metafile.inputs[key]?.imports ?? []) {
+      if (!imported.external && metafile.inputs[imported.path]) visit(imported.path);
+    }
+
+    if (STYLE_EXTENSIONS.includes(path.extname(key))) ordered.push(path.resolve(key));
+  };
+
+  visit(entryKey);
+
+  return ordered;
+}
+
+/**
+ * Stylesheet paths imported anywhere in a component's module graph, in cascade order.
+ *
+ * An unbuildable graph yields an empty list rather than throwing, leaving the CSS step with the
+ * declared entry.
+ */
+export async function collectStyleImports(entryPath: string, handoff: any): Promise<string[]> {
+  const metafile = await buildModuleGraph(entryPath, handoff);
+  return metafile ? orderStyleImports(metafile, entryPath) : [];
+}
+
+/**
+ * Every file in the module graph of an entry, stylesheets included, or `null` when the graph does
+ * not build.
+ */
+export async function collectModuleInputs(entryPath: string, handoff: any): Promise<string[] | null> {
+  const metafile = await buildModuleGraph(entryPath, handoff);
+  return metafile ? Object.keys(metafile.inputs).map((input) => path.resolve(input)) : null;
+}
+
+async function buildModuleGraph(entryPath: string, handoff: any): Promise<esbuild.Metafile | null> {
+  const baseConfig: esbuild.BuildOptions = {
+    ...DEFAULT_SSR_BUILD_CONFIG,
+    entryPoints: [entryPath],
+    logLevel: 'silent',
+  };
+  const hookedConfig = handoff?.config?.hooks?.ssrBuildConfig ? handoff.config.hooks.ssrBuildConfig(baseConfig) : baseConfig;
+
+  try {
+    // The `empty` loader keeps stylesheets out of the JavaScript, and the metafile still records
+    // them as inputs, so the graph carries the order.
+    const result = await esbuild.build({ ...withStyleLoaders(hookedConfig), metafile: true });
+    return result.metafile ?? null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Resolves a module from multiple search directories
  * @param id - Module ID to resolve

package/src/transformers/utils/module.ts

@@ -1,6 +1,6 @@
 import esbuild from 'esbuild';
 import { ModuleEvaluationResult } from '../types';
-import { DEFAULT_SSR_BUILD_CONFIG } from './build';
+import { DEFAULT_SSR_BUILD_CONFIG, withStyleLoaders } from './build';
 
 function createModuleBuildConfig(entryPath: string, handoff: any): esbuild.BuildOptions {
   const defaultBuildConfig: esbuild.BuildOptions = {
@@ -8,9 +8,11 @@ function createModuleBuildConfig(entryPath: string, handoff: any): esbuild.Build
     entryPoints: [entryPath],
   };
 
-  return handoff.config?.hooks?.ssrBuildConfig
+  const hookedBuildConfig = handoff.config?.hooks?.ssrBuildConfig
     ? handoff.config.hooks.ssrBuildConfig(defaultBuildConfig)
     : defaultBuildConfig;
+
+  return withStyleLoaders(hookedBuildConfig);
 }
 
 function evaluateBuiltModule(code: string): ModuleEvaluationResult {