handoff-app 1.0.4 → 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/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

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

@@ -0,0 +1,181 @@
+
+
+/** @type {import('handoff-app').Config} */
+module.exports = {
+  app: {
+    theme: "default",
+    title: "{{projectName}} Design System",
+    client: "{{projectName}}",
+    google_tag_manager: null,
+    attribution: true,
+    type_copy: "Almost before we knew it, we had left the ground.",
+    type_sort: [
+      "Heading 1",
+      "Heading 2",
+      "Heading 3",
+      "Heading 4",
+      "Heading 5",
+      "Heading 6",
+      "Paragraph",
+      "Subheading",
+      "Blockquote",
+      "Input Labels",
+      "Link"
+    ],
+    color_sort: [
+      "primary",
+      "secondary",
+      "extra",
+      "system"
+    ],
+    component_sort: [
+      "primary",
+      "secondary",
+      "transparent"
+    ],
+    base_path: "",
+    breakpoints: {
+      sm: { size: 576, name: "Small" },
+      md: { size: 768, name: "Medium" },
+      lg: { size: 992, name: "Large" },
+      xl: { size: 1200, name: "Extra Large" }
+    }
+  },
+
+  // entries: {
+  //   /**
+  //    * Array of component paths to be included in the build
+  //    * Add your component directories here
+  //    */
+  //   components: ["components/button"]
+  // },
+
+  hooks: {
+    /**
+     * Optional validation callback for components
+     * @param component - The component instance to validate
+     * @returns A record of validation results where keys are validation types and values are detailed validation results
+     *
+     * @example
+     * validateComponent: async (component) => ({
+     *   a11y: {
+     *     description: 'Accessibility validation check',
+     *     passed: true,
+     *     messages: ['No accessibility issues found']
+     *   },
+     *   responsive: {
+     *     description: 'Responsive design validation',
+     *     passed: false,
+     *     messages: ['Component breaks at mobile breakpoint']
+     *   }
+     * })
+     */
+    // validateComponent: async (component) => {
+    //   // Add your custom validation logic here
+    //   return {};
+    // },
+
+    /**
+     * Optional hook to override the SSR build configuration used in the ssrRenderPlugin
+     * @param config - The default esbuild configuration
+     * @returns Modified esbuild configuration
+     *
+     * @example
+     * ssrBuildConfig: (config) => {
+     *   // Modify the esbuild config as needed
+     *   return config;
+     * }
+     */
+    // ssrBuildConfig: (config) => {
+    //   // Add your custom SSR build configuration here
+    //   return config;
+    // },
+
+    /**
+     * Optional hook to override the client-side build configuration used in the ssrRenderPlugin
+     * @param config - The default esbuild configuration
+     * @returns Modified esbuild configuration
+     *
+     * @example
+     * clientBuildConfig: (config) => {
+     *   // Modify the esbuild config as needed
+     *   return config;
+     * }
+     */
+    // clientBuildConfig: (config) => {
+    //   // Add your custom client build configuration here
+    //   return config;
+    // },
+
+    /**
+     * Optional hook to specify which export property contains the schema
+     * @param exports - The module exports object containing the schema
+     * @returns The schema object from the exports
+     *
+     * @example
+     * getSchemaFromExports: (exports) => exports.customSchema || exports.default
+     */
+    // getSchemaFromExports: (exports) => {
+    //   // Add your custom schema extraction logic here
+    //   return exports.default;
+    // },
+
+    /**
+     * Optional hook to transform the schema into properties
+     * @param schema - The schema object to transform
+     * @returns The transformed properties object
+     */
+    // schemaToProperties: (schema) => {
+    //   // Add your custom schema to properties transformation here
+    //   return {};
+    // },
+
+    /**
+     * Optional hook to override the JavaScript Vite configuration
+     * @param config - The default Vite configuration
+     * @returns Modified Vite configuration
+     *
+     * @example
+     * jsBuildConfig: (config) => {
+     *   // Modify the Vite config as needed
+     *   return config;
+     * }
+     */
+    // jsBuildConfig: (config) => {
+    //   // Add your custom JavaScript build configuration here
+    //   return config;
+    // },
+
+    /**
+     * Optional hook to override the CSS Vite configuration
+     * @param config - The default Vite configuration
+     * @returns Modified Vite configuration
+     *
+     * @example
+     * cssBuildConfig: (config) => {
+     *   // Modify the Vite config as needed
+     *   return config;
+     * }
+     */
+    // cssBuildConfig: (config) => {
+    //   // Add your custom CSS build configuration here
+    //   return config;
+    // },
+
+    /**
+     * Optional hook to override the HTML Vite configuration
+     * @param config - The default Vite configuration
+     * @returns Modified Vite configuration
+     *
+     * @example
+     * htmlBuildConfig: (config) => {
+     *   // Modify the Vite config as needed
+     *   return config;
+     * }
+     */
+    // htmlBuildConfig: (config) => {
+    //   // Add your custom HTML build configuration here
+    //   return config;
+    // },
+  },
+};