handoff-app 1.0.3 → 1.0.5

package/src/create.ts

@@ -0,0 +1,302 @@
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { spawn } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Get the current handoff-app version from package.json
+ */
+const getVersion = (): string => {
+  try {
+    const packageJsonPath = path.resolve(__dirname, '../package.json');
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    return packageJson.version || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+};
+
+interface CreateOptions {
+  projectName: string;
+  figmaProjectId: string;
+  figmaAccessToken: string;
+  [key: string]: string; // Allow dynamic access for template replacement
+}
+
+class CreateError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CreateError';
+  }
+}
+
+/**
+ * Check if directory exists
+ */
+const directoryExists = (dirPath: string): boolean => {
+  try {
+    return fs.existsSync(dirPath);
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Create directory recursively
+ */
+const createDirectory = (dirPath: string): void => {
+  try {
+    fs.mkdirSync(dirPath, { recursive: true });
+  } catch (error) {
+    throw new CreateError(`Failed to create directory: ${error}`);
+  }
+};
+
+interface TemplateConfig {
+  source: string;
+  destination: string;
+  isExample?: boolean; // Flag to indicate if this is an example file
+}
+
+/**
+ * Get mandatory templates based on whether examples are included
+ * Uses different handoff config templates for blank vs. with-examples projects
+ */
+const getMandatoryTemplates = (includeExamples: boolean): TemplateConfig[] => [
+  { source: 'package.json.tpl', destination: 'package.json' },
+  { 
+    source: includeExamples ? 'handoff.config.with-examples.js.tpl' : 'handoff.config.js.tpl', 
+    destination: 'handoff.config.js' 
+  },
+  { source: 'tsconfig.json.tpl', destination: 'tsconfig.json' },
+  { source: 'gitignore.tpl', destination: '.gitignore' },
+  { source: 'env.tpl', destination: '.env' },
+  { source: 'README.md.tpl', destination: 'README.md' },
+];
+
+// Example component files (only included when user opts for examples)
+const exampleTemplates: TemplateConfig[] = [
+  { source: 'components/button/Button.tsx.tpl', destination: 'components/button/Button.tsx', isExample: true },
+  { source: 'components/button/button.js.tpl', destination: 'components/button/button.js', isExample: true },
+];
+
+/**
+ * Render a template string by replacing placeholders with values
+ */
+const renderTemplate = (content: string, data: CreateOptions): string => {
+  return content.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+    if (!(key in data)) {
+      console.warn(chalk.yellow(`Warning: Unknown template placeholder '{{${key}}}'`));
+    }
+    return data[key] || '';
+  });
+};
+
+/**
+ * Execute npm install
+ */
+const runNpmInstall = async (projectPath: string): Promise<void> => {
+  const spinner = p.spinner();
+  spinner.start('Installing dependencies...');
+
+  return new Promise((resolve, reject) => {
+    const npmProcess = spawn('npm', ['install'], {
+      cwd: projectPath,
+      stdio: 'pipe',
+      shell: true,
+    });
+
+    let stderr = '';
+
+    npmProcess.stderr?.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    npmProcess.on('close', (code) => {
+      if (code === 0) {
+        spinner.stop('Dependencies installed successfully');
+        resolve();
+      } else {
+        spinner.stop('Failed to install dependencies');
+        reject(new CreateError(`npm install failed: ${stderr}`));
+      }
+    });
+
+    npmProcess.on('error', (error) => {
+      spinner.stop('Failed to install dependencies');
+      reject(new CreateError(`Failed to run npm install: ${error.message}`));
+    });
+  });
+};
+
+/**
+ * Validate project name
+ */
+const validateProjectName = (name: string): boolean => {
+  const validNameRegex = /^[a-zA-Z0-9-_]+$/;
+  return validNameRegex.test(name) && name.length > 0;
+};
+
+/**
+ * Main create function
+ */
+const create = async (): Promise<void> => {
+  const version = getVersion();
+  p.intro(chalk.bgCyan.black(` Handoff App Creator (v${version}) `));
+
+  try {
+    // Get project name
+    const projectName = await p.text({
+      message: 'Enter project name:',
+      placeholder: 'my-handoff-project',
+      validate: (value) => {
+        if (!value.trim()) return 'Project name is required';
+        if (!validateProjectName(value)) {
+          return 'Invalid project name. Use only letters, numbers, hyphens, and underscores.';
+        }
+      },
+    });
+
+    if (p.isCancel(projectName)) {
+      p.cancel('Project creation cancelled.');
+      process.exit(0);
+    }
+
+    const projectPath = path.resolve(process.cwd(), projectName as string);
+
+    // Check if directory exists
+    if (directoryExists(projectPath)) {
+      const overwrite = await p.confirm({
+        message: `Directory "${projectName}" already exists. Do you want to overwrite it?`,
+        initialValue: false,
+      });
+
+      if (p.isCancel(overwrite) || !overwrite) {
+        p.cancel('Project creation cancelled.');
+        process.exit(0);
+      }
+
+      // Remove existing directory
+      p.log.info('Removing existing directory...');
+      fs.rmSync(projectPath, { recursive: true, force: true });
+    }
+
+    // Create project directory
+    p.log.info('Creating project directory...');
+    createDirectory(projectPath);
+
+    // Ask if user wants a blank project or one with examples
+    p.log.step(chalk.blue('Project Configuration'));
+    const projectType = await p.select({
+      message: 'What type of project would you like to create?',
+      options: [
+        { value: 'with-examples', label: 'Project with sample components', hint: 'Includes example components to get started' },
+        { value: 'blank', label: 'Blank project', hint: 'Only mandatory files, no examples' },
+      ],
+      initialValue: 'with-examples',
+    });
+
+    if (p.isCancel(projectType)) {
+      p.cancel('Project creation cancelled.');
+      process.exit(0);
+    }
+
+    const includeExamples = projectType === 'with-examples';
+
+    // Get Figma project ID
+    p.log.step(chalk.blue('Figma Configuration'));
+    const figmaProjectId = await p.text({
+      message: 'Enter Figma project ID:',
+      placeholder: 'Optional - can be configured later',
+    });
+
+    if (p.isCancel(figmaProjectId)) {
+      p.cancel('Project creation cancelled.');
+      process.exit(0);
+    }
+
+    // Get Figma access token
+    let figmaAccessToken: string | boolean | symbol = '';
+
+    if (figmaProjectId) {
+      figmaAccessToken = await p.password({
+        message: 'Enter Figma developer access token:',
+      });
+
+      if (p.isCancel(figmaAccessToken)) {
+        p.cancel('Project creation cancelled.');
+        process.exit(0);
+      }
+    }
+
+    const options: CreateOptions = {
+      projectName: projectName as string,
+      figmaProjectId: ((figmaProjectId as string) || '').trim(),
+      figmaAccessToken: ((figmaAccessToken as string) || '').trim(),
+    };
+
+    // Create files
+    const spinner = p.spinner();
+    spinner.start('Creating project files...');
+
+    const templateDir = path.resolve(__dirname, '../templates/default');
+
+    if (!fs.existsSync(templateDir)) {
+      throw new CreateError(`Template directory not found at ${templateDir}. This may indicate a packaging issue.`);
+    }
+
+    // Combine mandatory templates with example templates based on user choice
+    const templates = [
+      ...getMandatoryTemplates(includeExamples),
+      ...(includeExamples ? exampleTemplates : []),
+    ];
+
+    try {
+      for (const template of templates) {
+        const templatePath = path.join(templateDir, template.source);
+        const destinationPath = path.join(projectPath, template.destination);
+
+        try {
+          const content = fs.readFileSync(templatePath, 'utf8');
+          const rendered = renderTemplate(content, options);
+          fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+          fs.writeFileSync(destinationPath, rendered);
+        } catch (err) {
+          throw new CreateError(`Failed to create file ${template.destination}: ${err}`);
+        }
+      }
+      spinner.stop('Project files created');
+    } catch (err) {
+      spinner.stop('Failed to create project files');
+      throw err;
+    }
+
+    // Install dependencies
+    await runNpmInstall(projectPath);
+
+    // Success message
+    const nextSteps = [`cd ${projectName}`];
+    if (figmaProjectId && figmaAccessToken) {
+      nextSteps.push('npm run fetch');
+    }
+    nextSteps.push('npm run start');
+
+    p.note(nextSteps.join('\n'), 'Next steps');
+
+    const outroMessage = includeExamples
+      ? 'Project created successfully with sample components! First, fetch your Figma data (optional), then start the documentation site.'
+      : 'Blank project created successfully! First, fetch your Figma data, then start the documentation site.';
+
+    p.outro(chalk.green(outroMessage));
+  } catch (error) {
+    if (error instanceof CreateError) {
+      p.cancel(chalk.red(`Error: ${error.message}`));
+    } else {
+      p.cancel(chalk.red(`Unexpected error: ${error}`));
+    }
+    process.exit(1);
+  }
+};
+
+export default create;

package/src/index.ts

@@ -55,6 +55,9 @@ class Handoff {
     this.exportsDirectory = config.exportsOutputDirectory ?? this.exportsDirectory;
     this.sitesDirectory = config.sitesOutputDirectory ?? this.exportsDirectory;
     [this.runtimeConfig, this._configFilePaths] = initRuntimeConfig(this);
+    if(this.config.app.base_path && !process.env.HANDOFF_APP_BASE_PATH) {
+      process.env.HANDOFF_APP_BASE_PATH = this.config.app.base_path ?? '';
+    }
     return this;
   }
 

package/src/transformers/plugins/ssr-render.ts

@@ -118,9 +118,9 @@ function generateHtmlDocument(componentId: string, previewTitle: string, rendere
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <link rel="stylesheet" href="/api/component/main.css" />
-    <link rel="stylesheet" href="/api/component/${componentId}.css" />
-    <link rel="stylesheet" href="/assets/css/preview.css" />
+    <link rel="stylesheet" href="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/component/main.css" />
+    <link rel="stylesheet" href="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/component/${componentId}.css" />
+    <link rel="stylesheet" href="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/assets/css/preview.css" />
     <script id="${PLUGIN_CONSTANTS.PROPS_SCRIPT_ID}" type="application/json">${JSON.stringify(props)}</script>
     <script type="module">
       ${clientJs}

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

@@ -107,7 +107,7 @@ export const updateComponentSummaryApi = async (handoff: Handoff, componentData:
   }
 
   // Partial update: merge with existing data
-  const apiPath = path.resolve(handoff.workingPath, 'public/api/components.json');
+  const apiPath = path.resolve(handoff.workingPath, `${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/components.json`);
   let existingData: ComponentListObject[] = [];
 
   if (fs.existsSync(apiPath)) {

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

@@ -363,7 +363,7 @@ const buildComponentSummary = (id: string, data: TransformComponentTokensResult)
     tags: data.tags ? data.tags : [],
     properties: data.properties,
     previews: data.previews,
-    path: `/api/component/${id}.json`,
+    path: `${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/component/${id}.json`,
   };
 };
 

package/src/transformers/utils/handlebars.ts

@@ -60,8 +60,8 @@ export const createHandlebarsContext = (
   previewData: { values?: any }
 ): HandlebarsContext => {
   return {
-    style: `<link rel="stylesheet" href="/api/component/shared.css"><link rel="stylesheet" href="/api/component/${data.id}.css">\n<link rel="stylesheet" href="/assets/css/preview.css">`,
-    script: `<script src="/api/component/${data.id}.js"></script>\n<script src="/assets/js/preview.js"></script><script>var fields = ${JSON.stringify(data.properties)};</script>`,
+    style: `<link rel="stylesheet" href="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/component/shared.css"><link rel="stylesheet" href="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/component/${data.id}.css">\n<link rel="stylesheet" href="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/assets/css/preview.css">`,
+    script: `<script src="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/component/${data.id}.js"></script>\n<script src="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/assets/js/preview.js"></script><script>var fields = ${JSON.stringify(data.properties)};</script>`,
     properties: previewData.values || {},
     fields: data.properties,
     title: data.title,

package/templates/default/README.md.tpl

@@ -0,0 +1,15 @@
+# {{projectName}}
+
+A design system documentation site powered by Handoff App.
+
+## Getting Started
+
+1. Configure your Figma credentials in `.env`
+2. Run `npm run fetch` to pull design tokens
+3. Run `npm run start` to launch the documentation site
+
+## Scripts
+
+- `npm run fetch` - Fetch design data from Figma
+- `npm run start` - Start the documentation server
+- `npm run build` - Build for production

package/templates/default/components/button/Button.tsx.tpl

@@ -0,0 +1,92 @@
+import React, { useState } from 'react';
+
+interface ButtonProps {
+  type?: 'primary' | 'secondary';
+  children: React.ReactNode;
+  disabled?: boolean;
+  className?: string;
+  showCounter?: boolean;
+}
+
+const Button: React.FC<ButtonProps> = ({
+  type = 'primary',
+  children,
+  disabled = false,
+  className = '',
+  showCounter = true
+}) => {
+  const [clickCount, setClickCount] = useState(0);
+  
+  const baseColor = type === 'primary' ? '#4f46e5' : '#dc2626';
+  const hoverColor = type === 'primary' ? '#4338ca' : '#b91c1c';
+
+  const handleClick = () => {
+    if (!disabled) {
+      setClickCount(prev => prev + 1);
+    }
+  };
+
+  const variantStyle: React.CSSProperties = {
+    backgroundColor: baseColor,
+    color: '#ffffff',
+    border: 'none',
+    borderRadius: '100px',
+    fontSize: '1rem',
+    padding: '0.625rem 1rem',
+    outline: 'none',
+    cursor: disabled ? 'not-allowed' : 'pointer',
+    opacity: disabled ? 0.6 : 1,
+    transition: 'all 0.15s ease-in-out',
+    fontWeight: 500,
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: '8px'
+  };
+
+  const wrapperStyle: React.CSSProperties = {
+    padding: '8px 0'
+  };
+
+  const counterBadgeStyle: React.CSSProperties = {
+    backgroundColor: 'rgba(255, 255, 255, 0.3)',
+    borderRadius: '12px',
+    padding: '2px 8px',
+    fontSize: '0.875rem',
+    fontWeight: 600,
+    minWidth: '24px',
+    textAlign: 'center'
+  };
+
+  return (
+    <div style={wrapperStyle}>
+      <button
+        type="button"
+        disabled={disabled}
+        style={variantStyle}
+        className={`btn btn-${type} ${className}`.trim()}
+        onClick={handleClick}
+        onMouseEnter={(e) => {
+          if (!disabled) {
+            e.currentTarget.style.backgroundColor = hoverColor;
+            e.currentTarget.style.transform = 'translateY(-1px)';
+          }
+        }}
+        onMouseLeave={(e) => {
+          if (!disabled) {
+            e.currentTarget.style.backgroundColor = baseColor;
+            e.currentTarget.style.transform = 'translateY(0)';
+          }
+        }}
+      >
+        <span>{children}</span>
+        {showCounter && (
+          <span style={counterBadgeStyle}>
+            {clickCount}
+          </span>
+        )}
+      </button>
+    </div>
+  );
+};
+
+export default Button;

package/templates/default/components/button/button.js.tpl

@@ -0,0 +1,62 @@
+/** @type {import('handoff-app').Component} */
+module.exports = {
+  title: "Button",
+  description: "Interactive buttons that trigger actions and allow users to complete tasks, such as submitting a form or confirming a choice. This component includes click tracking to demonstrate stateful component behavior.",
+  group: "Atomic Elements",
+  type: "element",
+  categories: [
+    "functionality",
+    "interactive"
+  ],
+  entries: {
+    template: "Button.tsx",
+    // schema: "Schema.ts"
+  },
+  // Intentionally omit figmaComponentId so docs variants are not sourced from Figma.
+  previews: {
+    primary: {
+      title: "Primary Button",
+      values: {
+        type: "primary",
+        children: "Click me!",
+        showCounter: true
+      }
+    },
+    secondary: {
+      title: "Secondary Button",
+      values: {
+        type: "secondary",
+        children: "Click me too!",
+        showCounter: true
+      }
+    },
+    primaryDisabled: {
+      title: "Disabled State",
+      values: {
+        type: "primary",
+        children: "Disabled",
+        disabled: true,
+        showCounter: true
+      }
+    },
+    withoutCounter: {
+      title: "Without Counter",
+      values: {
+        type: "primary",
+        children: "Submit",
+        showCounter: false
+      }
+    }
+  },
+  should_do: [
+    "Keep one primary button per section so main action is clear.",
+    "Use the secondary variant for less important actions.",
+    "Provide clear, action-oriented labels that describe what will happen.",
+    "Show visual feedback on hover and click interactions."
+  ],
+  should_not_do: [
+    "Do not use vague labels like Click here or OK when the action can be specific.",
+    "Do not mix primary and secondary styles inconsistently.",
+    "Do not disable buttons without providing alternative guidance or feedback."
+  ]
+};

package/templates/default/env.tpl

@@ -0,0 +1,2 @@
+HANDOFF_FIGMA_PROJECT_ID={{figmaProjectId}}
+HANDOFF_DEV_ACCESS_TOKEN={{figmaAccessToken}}

package/templates/default/gitignore.tpl

@@ -0,0 +1,7 @@
+node_modules/
+.env
+dist/
+.next/
+out/
+.DS_Store
+*.log