handoff-app 1.1.0-experimental.2 → 1.1.0

package/dist/transformers/utils/build.js

@@ -1,13 +1,4 @@
 "use strict";
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -15,12 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_CLIENT_BUILD_CONFIG = exports.DEFAULT_SSR_BUILD_CONFIG = void 0;
 exports.resolveModule = resolveModule;
 exports.createReactResolvePlugin = createReactResolvePlugin;
-exports.generateClientComponentSource = generateClientComponentSource;
-exports.generateCsfClientComponentSource = generateCsfClientComponentSource;
-exports.buildClientModule = buildClientModule;
-const esbuild_1 = __importDefault(require("esbuild"));
 const path_1 = __importDefault(require("path"));
-const logger_1 = require("../../utils/logger");
 /**
  * Default esbuild configuration for SSR builds
  */
@@ -88,97 +74,3 @@ function createReactResolvePlugin(workingPath, handoffModulePath) {
         },
     };
 }
-function toForwardSlash(p) {
-    return p.replace(/\\/g, '/');
-}
-/**
- * Generates the entry source for a standalone client-side React component module.
- * The resulting module exports `render(container, props)` and `update(props)`
- * so the Playground can dynamically load and re-render it in an iframe.
- */
-function generateClientComponentSource(componentPath) {
-    return `
-    import React from 'react';
-    import { createRoot } from 'react-dom/client';
-    import Component from '${toForwardSlash(componentPath)}';
-
-    let root = null;
-
-    export function render(container, props) {
-      root = createRoot(container);
-      root.render(React.createElement(Component, props));
-      return root;
-    }
-
-    export function update(props) {
-      if (root) {
-        root.render(React.createElement(Component, props));
-      }
-    }
-  `;
-}
-/**
- * Generates the entry source for a standalone CSF component module.
- * Replicates the story rendering logic (meta.render / story.render / meta.component)
- * so the Playground can render CSF components client-side.
- */
-function generateCsfClientComponentSource(componentPath, storyKey) {
-    return `
-    import React from 'react';
-    import { createRoot } from 'react-dom/client';
-    import * as stories from '${toForwardSlash(componentPath)}';
-
-    const meta = stories.default || {};
-    const story = stories['${storyKey}'];
-
-    let root = null;
-
-    function renderElement(props) {
-      const storyRender = typeof story === 'function' ? story : (story && story.render);
-      const renderFn = storyRender || meta.render;
-      if (renderFn) {
-        const result = renderFn(props);
-        return React.isValidElement(result) ? result : React.createElement(meta.component, props);
-      }
-      if (meta.component) {
-        return React.createElement(meta.component, props);
-      }
-      return React.createElement('pre', null, JSON.stringify(props, null, 2));
-    }
-
-    export function render(container, props) {
-      root = createRoot(container);
-      root.render(renderElement(props));
-      return root;
-    }
-
-    export function update(props) {
-      if (root) {
-        root.render(renderElement(props));
-      }
-    }
-  `;
-}
-/**
- * Builds a self-contained browser ESM module from the given source code.
- * React and ReactDOM are bundled into the output so the module works standalone.
- */
-function buildClientModule(sourceCode, handoff) {
-    return __awaiter(this, void 0, void 0, function* () {
-        var _a, _b;
-        const config = Object.assign(Object.assign({}, exports.DEFAULT_CLIENT_BUILD_CONFIG), { logLevel: 'silent', stdin: {
-                contents: sourceCode,
-                resolveDir: process.cwd(),
-                loader: 'tsx',
-            }, plugins: [createReactResolvePlugin(handoff.workingPath, handoff.modulePath)] });
-        const finalConfig = ((_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.hooks) === null || _b === void 0 ? void 0 : _b.clientBuildConfig)
-            ? handoff.config.hooks.clientBuildConfig(config)
-            : config;
-        const result = yield esbuild_1.default.build(finalConfig);
-        if (result.warnings.length > 0) {
-            const messages = yield esbuild_1.default.formatMessages(result.warnings, { kind: 'warning', color: true });
-            messages.forEach((msg) => logger_1.Logger.warn(msg));
-        }
-        return result.outputFiles[0].text;
-    });
-}

package/dist/types/config.d.ts

@@ -3,7 +3,6 @@ import { Types as HandoffTypes } from 'handoff-core';
 import { InlineConfig } from 'vite';
 import { SlotMetadata } from '../transformers/preview/component';
 import { ComponentListObject, TransformComponentTokensResult } from '../transformers/preview/types';
-import { PageListObject } from '../transformers/preview/page/types';
 import { ValidationResult } from './preview';
 export interface ImageStyle {
     name: string;
@@ -114,11 +113,6 @@ export interface Config {
          * @example ["components/button", "components/input"]
          */
         components?: string[];
-        /**
-         * Array of page paths to be included in the build
-         * @example ["pages/homepage", "pages/about"]
-         */
-        pages?: string[];
     };
     /**
      * Configuration for asset zip file download links
@@ -136,16 +130,6 @@ export interface Config {
          */
         logos?: string;
     };
-    /**
-     * Platform project ID (UUID). Set by `platform:init` to link this
-     * local project with a remote handoff-service project.
-     */
-    platformProjectId?: string;
-    /**
-     * Platform base URL (e.g. "http://localhost:3000" or "https://handoff.example.com").
-     * Set by `platform:init` so subsequent sync commands know where to connect.
-     */
-    platformUrl?: string;
     /**
      * Configuration hooks for extending functionality
      */
@@ -277,9 +261,6 @@ export interface RuntimeConfig {
         components: {
             [id: string]: ComponentListObject;
         };
-        pages: {
-            [id: string]: PageListObject;
-        };
     };
     options: {
         [key: string]: RuntimeConfigComponentOptions;

package/docs/api.md

@@ -0,0 +1,279 @@
+# Handoff API
+
+Handoff exposes two APIs - A Javascript API for interacting with the pipeline
+Handoff exposes a Javascript API allowing you to easily integrate Handoff into
+existing Node based applications, CI/CD, and command line tools. This API also
+allows you to hook into the pipeline execution and generate new build artifacts
+during the execution.
+
+## Example Project
+
+Here's a demo project you can check out to get started fast
+https://github.com/Convertiv/handoff-0-6-0/
+
+## Get Started
+
+1. Run `npm install --save handoff-app`
+2. Add handoff to your code. Create `handoff.ts`
+
+```js
+import Handoff from 'handoff-app';
+
+const handoff = new Handoff({
+  // You can customize the configuration here
+});
+handoff.fetch();
+```
+
+3. Build your typescript `tsc`
+4. Run your project `node handoff.js`
+
+## Methods
+
+Methods of the handoff class can be called to run actions in the
+
+### init
+
+```js
+handoff.init();
+```
+
+Init will check and build the local state, including the configuration. You
+probably don't need to call this method since it is executed as part of the
+class constructor
+
+### fetch
+
+```js
+handoff.fetch();
+```
+
+Fetch will connect to the defined Figma file id provided in the
+`env`. If no env or file is found, it will interactively request one. Then it
+will export all of the tokens and generated data into an `exported` directory
+in the local working root.
+
+### build
+
+```js
+handoff.build();
+```
+
+Build will take the exported artifacts and build a react documentation site from
+those artifacts. The build html site will be exported to the `out` directory
+in the current working root
+
+This method will throw an error if the `exported` directory or the `tokens.json`
+files do not exist
+
+### integration
+
+```js
+handoff.integration();
+```
+
+The integration method will run just the preview and integration generation.
+This step is done as part of the build step, but its often useful to be able
+to generate only the integration code.
+
+## Hooks
+
+Hooks allow a typescript or javascript app to interact with the pipeline.
+This is especially useful for modifying or extending the output of the pipeline.
+To use a hook in your project, once you've instantiated the handoff object, you
+can call one of the hook methods and pass a function to the method. The hook
+function will be called at the appropriate point in the pipeline.
+
+For example if you want to alter the integration output, you can do this -
+
+```js
+import Handoff from 'handoff-app';
+
+const handoff = new Handoff({
+  // You can customize the configuration here
+});
+
+handoff.postIntegration((documentationObject: DocumentationObject, data: HookReturn[]) => {
+  const colors = documentationObject.design.color.map((color) => {
+    return {
+      name: color.name,
+      value: color.value,
+    };
+  });
+  data.push({
+    filename: 'colors.json',
+    data: JSON.stringify(colors, null, 2),
+  });
+  return data;
+});
+
+handoff.fetch();
+```
+
+### postIntegration
+
+The Post integration hook will allow you to add a function that will be executed
+after the integration build is complete. The function accepts two arguments -
+
+**arguments**
+
+- `tokens: DocumentationObject` This is an instance of the exported
+  DocumentationObject containing all of the tokens.
+- `data: HookReturn[]` This an array of HookReturns, consisting of `filename`
+  and `data`. Each object in this array will be written out to
+  `exported/{integration}-tokens`
+
+**return**
+The hook must return an array of `HookReturn` objects, or an empty array
+
+#### Example
+
+```js
+handoff.postIntegration((documentationObject: DocumentationObject, data: HookReturn[]) => {
+  const colors = documentationObject.design.color.map((color) => {
+    return {
+      name: color.name,
+      value: color.value,
+    };
+  });
+  data.push({
+    filename: 'colors.json',
+    data: JSON.stringify(colors, null, 2),
+  });
+  return data;
+});
+```
+
+### postBuild
+
+This function is called after the app build is complete.
+
+**arguments**
+
+- `tokens: DocumentationObject` This is an instance of the exported
+  DocumentationObject containing all of the tokens.
+
+**returns**
+Nothing is returned from the postBuild hook
+
+### postCssTransformer
+
+This function is called after the css generation is complete. It allows an
+application to alter the css generation in transit
+
+**arguments**
+
+- `tokens: DocumentationObject` This is an instance of the exported
+  DocumentationObject containing all of the tokens.
+- `css: CssTransformerOutput` This is an object containing all of the
+  tokens for components and foundations, formatted as CSS variables
+
+**returns**
+
+- `css: CssTransformerOutput` This is an object containing all of the
+  tokens for components and foundations, formatted as CSS variables.
+  Any changes you return here will be written to the css files
+
+### postCssTransformer
+
+This function is called after the css generation is complete. It allows an
+application to alter the css generation in transit. It will allow you to alter
+the transformed output prior to being written to disk.
+
+**arguments**
+
+- `tokens: DocumentationObject` This is an instance of the exported
+  DocumentationObject containing all of the tokens.
+- `css: CssTransformerOutput` This is an object containing all of the
+  tokens for components and foundations, formatted as CSS variables
+
+**returns**
+
+- `css: CssTransformerOutput` This is an object containing all of the
+  tokens for components and foundations, formatted as CSS variables.
+  Any changes you return here will be written to the css files.
+
+### postScssTransformer
+
+This function is called after the scss generation is complete. It allows an
+application to alter the scss generation in transit. It will allow you to alter
+the transformed output prior to being written to disk.
+
+**arguments**
+
+- `tokens: DocumentationObject` This is an instance of the exported
+  DocumentationObject containing all of the tokens.
+- `scss: CssTransformerOutput` This is an object containing all of the
+  tokens for components and foundations, formatted as SCSS variables
+
+**returns**
+
+- `css: CssTransformerOutput` This is an object containing all of the
+  tokens for components and foundations, formatted as SCSS variables.
+  Any changes you return here will be written to the scss files.
+
+### postTypeTransformer
+
+Handoff generates a set of scss files that list all the possible types of
+a component (type, state, activity, size, theme, etc.). This allows frontend
+engineers to iterate over the types and build scss maps with the variables.
+
+This function is called after the type generation is complete. It allows an
+application to alter the type generation in transit. It will allow you to alter
+the transformed output prior to being written to disk.
+
+**arguments**
+
+- `tokens: DocumentationObject` This is an instance of the exported
+  DocumentationObject containing all of the tokens.
+- `scss: CssTransformerOutput` This is an object containing all of the
+  type arrays for components and foundations, formatted as SCSS variables
+
+**returns**
+
+- `css: CssTransformerOutput` This is an object containing all of the
+  tokens for components and foundations, formatted as type variables.
+  Any changes you return here will be written to the scss type files.
+
+### modifyWebpackConfig
+
+When the application is built, Handoff uses webpack to compile css, scss,
+and javascript in the entry point to build a little live preview of the
+components. This hook accepts a webpack.Configuration as the first argument
+and allows you to alter and return that configuration.
+
+**arguments**
+
+- `webpackConfig: webpack.Configuration` This is a full webpack configuration.
+
+**returns**
+
+- `webpackConfig: webpack.Configuration` Return the webpack configuration that
+  you have altered to fit your needs.
+
+**Example**
+
+```js
+export const modifyWebpackConfigForTailwind = (webpackConfig: webpack.Configuration): webpack.Configuration => {
+  // Enable webpack dev mode
+  webpackConfig.mode = 'development';
+  return webpackConfig;
+};
+```
+
+### configureExportables
+
+This hook allows you to alter the exportable list. You could do this by ejecting
+the handoff configuration and modifying the list, but this hook allows you to
+alter the exportable list with just a couple of lines of code rather than 
+exporting the whole list
+
+**arguments**
+
+- `exportables: string[]` The current list of exportables
+
+**returns**
+
+- `exportables: string[]` Return the list with whatever additions and subtractions
+you need for your application.
+

package/docs/cli.md

@@ -1,86 +1,72 @@
-# CLI Reference
+# Handoff CLI
 
-The Handoff CLI is run as `handoff-app` (when installed globally) or `node ./dist/cli.js` from the project root. For full options for any command, run:
+The Handoff cli allows you to interact with your Figma file and Handoff app
+via the command line. It allows you to run handoff in any folder with
+no other configuration or setup.  
 
-```bash
-handoff-app <command> --help
-```
+## Interacting with Figma
+The CLI will allow you to fetch all data from Figma, build the documentation
+app and run a local dev site. For these use the build, fetch, and serve commands
+documented below.  
 
-## Shared options
+## Configuring a handoff project
+The CLI will allow you to build the various kinds of configurations that you
+will need for interacting with Figma. Handoff has sane configuration defaults
+but the various kinds of configurations can be tailored or extended.
 
-Most commands accept these options (from [getSharedOptions](src/commands/utils.ts)):
+Handoff has 4 configuration files - 
 
-| Option | Short | Description |
-|--------|-------|-------------|
-| `--config` | `-c` | Path to config file |
-| `--force` | `-f` | Force action |
-| `--debug` | `-d` | Enable debug mode |
+`handoff.config.json` - Defines the general handoff configuration.
+`pages` - Markdown files that will create or customize pages in the documentation
+app
+`exportables` - JSON schemas for each component in your figma file that you
+want to pull into handoff.
+`integration` - scss mappings and html templates for making it easy to map
+handoff tokens to your frontend framework.
 
-## Commands
+The CLI exposes two ways to manage the config - `make` and `eject`. 
 
-### Build
+__Eject__ commands will take the default configuration and eject them into
+the current working directory. If you customize these configurations, then run 
+handoff commands in that directory, these configs will be executed.
+__Make__ commands will generate a boilerplate configuration in the current
+working directory. This is useful for extending handoff for different components
+or integrations.
 
-| Command | Description | Main options |
-|---------|-------------|--------------|
-| `build:app` | Build the documentation application | `--skip-components` — skip building components before building the app |
-| `build:components [component]` | Build project components | Optional positional: component name to build a specific component |
+## Requirements
+Node 16+
 
-### Development
+## Install the CLI 
 
-| Command | Description |
-|---------|-------------|
-| `dev` | Start the design system in development mode (custom dev server with watchers) |
-| `start` | Start the design system in development mode (same as dev) |
+`npm install -g handoff-app`
 
-### Eject
+## Run the CLI
 
-| Command | Description |
-|---------|-------------|
-| `eject:config` | Eject the default configuration to the current working directory |
-| `eject:pages` | Eject the default pages to the current working directory |
-| `eject:theme` | Eject the currently selected theme |
+`handoff-app --help`
 
-### Fetch / Init
+## Commands and Flags
 
-| Command | Description |
-|---------|-------------|
-| `fetch` | Fetch the design tokens |
-| `init` | Initialize a new Handoff project with interactive wizard |
+Usage: handoff-app <cmd> <opts>
 
-### Make
+Commands:
+  fetch [opts] - Fetches the design tokens from the design system
 
-| Command | Description | Arguments |
-|---------|-------------|-----------|
-| `make:page <name> [parent]` | Create a new page | `name` — page name; optional `parent` |
-| `make:component <name>` | Create a new HTML code component for documentation | `name` — component name |
-| `make:template <component> [state]` | Create a new template | `component` — component; optional `state` |
+  build - Using the current tokens, build various outputs
+    build:app [opts] - Builds the design system static application
 
-### Platform
+  start [opts] - Starts the design system in development mode
 
-| Command | Description | Main options |
-|---------|-------------|--------------|
-| `platform:login` | Log in to the Handoff platform | `--url` — platform URL (overrides config) |
-| `platform:init` | Link this directory to a Handoff platform project | `--url` — platform URL |
-| `platform:pull` | Pull project files from the Handoff platform | `--url`, `--force`, `--debug` |
-| `platform:push` | Push local changes to the Handoff platform | `--url`, `--force`, `--debug` |
-| `platform:logout` | Log out from the Handoff platform | `--url` — platform URL |
+  make
+    make:template <component> <state> [opts] - Creates a new template
+    make:page <component> <state> [opts] - Creates a new page
 
-### ISR (Incremental Static Regeneration)
+  eject - Ejects the default entire configuration to the current directory
+    eject:config [opts] - Ejects the default configuration to the current directory
+    eject:integration [opts] - Ejects the default integration to the current directory
+    eject:pages [opts] - Ejects the default pages to the current directory
 
-| Command | Description | Main options |
-|---------|-------------|--------------|
-| `isr:pages` | Rebuild app (skip components) and optionally deploy only affected routes | `--path`, `--paths`, `--menu-changed`, `--partial`, `--deploy-dir` |
-| `isr:component` | Rebuild one or more components, then rebuild app and optionally deploy only affected routes | `--id`, `--ids`, `--partial`, `--deploy-dir` |
-
-For detailed ISR behavior and options, see [ISR](./isr.md).
-
-### Other
-
-| Command | Description | Main options |
-|---------|-------------|--------------|
-| `scaffold` | Scaffold component stubs for fetched Figma components | |
-| `validate:components` | Validate components in the design system | `--skip-build` — skip build step before validating |
-
-## Config
-
-The CLI reads config from `handoff.config.js`, `handoff.config.cjs`, or `handoff.config.json` in the current working directory. Use `-c` or `--config` to point to a different file.
+Options:
+  -c, --config [file]      Define the path to the config file
+  -d, --debug              Show debug logs
+  -h, --help               Show this help message
+  -v, --version            Show the handoff version number

package/docs/props.md

@@ -0,0 +1,34 @@
+Here are the property types and rules
+
+## Types
+- string
+- image
+    - array of 
+        - src
+        - alt
+- breadcrumb
+    - array of
+        - label
+        - url
+        - active (boolean)
+- button
+    - label
+    - url
+
+## Rules
+- required
+- content
+    - min 
+    - max
+- pattern (regex)
+- dimensions
+    - min
+        - width
+        - height
+    - max
+        - width
+        - height
+    - recommend
+        - width
+        - height
+- filesize

package/handoff.config.js

@@ -57,7 +57,7 @@ module.exports = {
     js: './js/main.js',
     bundle: './js/main.js',
     components: ['./test_components'],
-    pages: ['./test_pages'],
+    patterns: ['./test_patterns'],
   },
   // These are the asset zip file download links
   assets_zip_links: {