handoff-app 2.0.0-6 → 2.0.0-7

package/README.md

@@ -66,11 +66,16 @@ my-handoff-project/
 └─ out/            # build output; gitignored
 ```
 
-## Components and patterns
+## Catalog items
 
-An implementation and a `*.handoff.ts` declaration are required for a
-TypeScript React component. Stable identity, documentation metadata, source
-entries, and previews are supplied by the declaration.
+Every documented UI entry is a catalog item. Each item declares either an implementation or a composition of other items.
+An implementation names its renderer. `defineCatalogItem` comes from the module for that renderer.
+The declaration supplies stable identity, documentation metadata, source entries, and previews.
+
+### React
+
+Handoff finds the implementation file from its import, so you do not need to repeat the path.
+Previews are named exports. `Preview<typeof item>` gives them the implementation's argument type.
 
 ```tsx
 // components/example/Component.tsx
@@ -83,61 +88,136 @@ export default function Component({ label }: ComponentProps) {
 }
 ```
 
-```ts
-// components/example/component.handoff.ts
-import { defineReactComponent } from 'handoff-app';
+```tsx
+// components/example/example.handoff.ts
+import { defineCatalogItem, type Preview } from 'handoff-app/react';
 import Component from './Component';
 
-export default defineReactComponent(Component, {
+const item = defineCatalogItem({
   id: 'component-id',
   name: 'Component name',
   description: 'Usage guidance for the component.',
   group: 'Group name',
-  entries: {
-    component: './Component.tsx',
-  },
-  previews: {
-    default: {
-      title: 'Default',
-      args: { label: 'Example' },
-    },
-  },
+  implementation: Component,
+});
+
+export default item;
+
+type ComponentPreview = Preview<typeof item>;
+
+export const Default = {
+  args: { label: 'Example' },
+} satisfies ComponentPreview;
+```
+
+The export name is the preview name. Use `name` to set a different display title.
+
+### Handlebars
+
+The implementation is the path to the template. Arguments are `Record<string, unknown>` by default;
+an explicit argument type is supplied through `defineCatalogItem<BadgeArgs>`.
+
+```ts
+// components/badge/badge.handoff.ts
+import { defineCatalogItem, type Preview } from 'handoff-app/handlebars';
+
+const item = defineCatalogItem({
+  id: 'badge',
+  name: 'Badge',
+  implementation: './Badge.hbs',
 });
+
+export default item;
+
+type BadgePreview = Preview<typeof item>;
+
+export const Primary = {
+  args: { variant: 'primary', children: 'New' },
+} satisfies BadgePreview;
 ```
 
-Components are referenced by stable ID in patterns. A named preview can be
-selected and its arguments can be overridden by each reference. Additional
-references can be added as required by the composition.
+### CSF
+
+CSF is a source format. A story file uses the renderer from the module that declares it. A React item references an existing CSF file with `fromCSF`.
+The CSF file stays unchanged and defines its previews through named exports. Each story's `args` merge with and override `meta.args`.
+Handoff preserves story names, `argTypes`, and `render` functions.
+It finds the React component through `meta.component`, then documents and publishes it with the story file.
 
 ```ts
-// patterns/example/pattern.handoff.ts
-import { definePattern } from 'handoff-app';
+// components/card/card.handoff.ts
+import { defineCatalogItem, fromCSF } from 'handoff-app/react';
 
-export default definePattern({
+export default defineCatalogItem({
+  id: 'card',
+  name: 'Card',
+  implementation: fromCSF('./Card.stories.tsx'),
+});
+```
+
+`Meta` and `StoryObj` are exported from `handoff-app/react`, so a story file type-checks without a
+Storybook dependency. A project that already has Storybook keeps using its own types.
+
+```tsx
+// components/card/Card.stories.tsx
+import { type Meta, type StoryObj } from 'handoff-app/react';
+import Card from './Card';
+
+const meta = { component: Card } satisfies Meta<typeof Card>;
+export default meta;
+
+export const Primary: StoryObj<typeof meta> = {
+  args: { title: 'Example' },
+};
+```
+
+A CSF preview is rendered on the server and is not hydrated. A direct React implementation is
+hydrated in the browser.
+
+### Compositions
+
+A composition references other items by stable id. A named preview can be selected and its arguments
+can be overridden by each reference. A composition needs no renderer, so it is declared with
+`defineCatalogItem` from `handoff-app/pattern`.
+
+```ts
+// patterns/example/example.handoff.ts
+import { defineCatalogItem } from 'handoff-app/pattern';
+
+export default defineCatalogItem({
   id: 'pattern-id',
   name: 'Pattern name',
   description: 'Purpose and usage of the composition.',
   group: 'Group name',
-  components: [
-    {
-      id: 'component-id',
-      preview: 'default',
-      args: { label: 'Pattern example' },
-    },
+  composition: [
+    { ref: 'component-id', preview: 'Default' },
+    { ref: 'badge', args: { children: 'Send' } },
   ],
 });
 ```
 
-Component and pattern directories are registered in the project config:
+An item declares `implementation` or `composition`, never both. Terms such as atom, element, and
+block stay optional classification metadata on `type` and `categories`.
+
+The `id` addresses the item everywhere: its artifacts, its documentation URL, and its publish and
+checkout commands. Components and patterns share one namespace, so each id must be unique across
+both.
+
+If two declarations claim one id, Handoff keeps the first and skips the second. The warning names
+both files. `publish` refuses to run until each id is unique.
+
+
+### Registration
+
+Catalog directories are registered in one place. A path is either an item directory or a collection
+directory whose subdirectories are each treated as an item.
 
 ```ts
 // handoff.config.ts
 import { defineConfig } from 'handoff-app';
 
 export default defineConfig({
-  entries: {
-    components: ['components/example'],
-    patterns: ['patterns'],
+  catalog: {
+    include: ['components', 'patterns'],
   },
   runtime: {
     workspace: {
@@ -147,6 +227,11 @@ export default defineConfig({
 });
 ```
 
+### Upgrade from version 1.x.x to version 2.x.x
+
+See the [version 1.x.x to version 2.x.x migration guide](UPGRADE.md#version-1xx-to-version-2xx)
+for breaking changes, migration steps, and upgrade verification.
+
 Custom documentation pages are Markdown files under `pages/`. Their relative
 paths become their routes and registry IDs.
 
@@ -340,20 +425,23 @@ npm run publish -- all
 A single kind is published on its own:
 
 ```bash
-npm run publish -- components
-npm run publish -- patterns
+npm run publish -- catalog
 npm run publish -- pages
 npm run publish -- tokens
 npm run publish -- assets
 ```
 
+`catalog` covers every catalog item. An item is stored as a component or as a
+pattern, and its declaration decides which. The command names items and never a
+kind.
+
 Publishing tokens or assets runs the Figma data pipeline before upload, so the
 documented Figma credentials must be available.
 
 One or more IDs can be appended to narrow a publish to those entities:
 
 ```bash
-npm run publish -- components component-id another-id
+npm run publish -- catalog item-id another-id
 ```
 
 `--dry-run` reports what would be uploaded and contacts no registry at all, so
@@ -363,16 +451,16 @@ the existing output, and the two combine to leave the workspace untouched:
 
 ```bash
 npm run publish -- all --dry-run
-npm run publish -- components --no-build
+npm run publish -- catalog --no-build
 ```
 
 `checkout` takes the same `all`, multi-ID, and `--dry-run` forms. A dry-run
 checkout reads from the registry, lists the files it would create or overwrite,
 and writes nothing.
 
-After the registry is reloaded, the published components, patterns, and
-foundations should be visible. Published database records are read by registry
-pages; the local workspace is never read directly.
+After the registry is reloaded, the published catalog items and foundations are
+visible. Published database records are read by registry pages; the local
+workspace is never read directly.
 
 For CI, a registry connection and user-issued token are configured:
 
@@ -473,7 +561,7 @@ both.
 | `npm run build -- [--target static\|registry]` | The static site or standalone registry bundle is built |
 | `npm run db:migrate` | Registry database migrations are applied |
 | `npm run validate` | Configured components are validated |
-| `npm run publish -- <kind\|all> [id...]` | Components, patterns, pages, tokens, or assets are published |
+| `npm run publish -- <kind\|all> [id...]` | Catalog items, pages, tokens, or assets are published |
 | `npm run checkout -- <kind\|all> [id...]` | Published content is pulled into a workspace |
 | `npm run login -- --url <url>` | The CLI is authorized through the registry device flow |
 | `npm run logout -- [--url <url>]` | A saved CLI credential is revoked and removed |

package/UPGRADE.md

@@ -0,0 +1,198 @@
+# Upgrade Handoff
+
+This document contains migration steps for each major version upgrade.
+
+## Version 1.x.x to version 2.x.x
+
+This guide describes how to upgrade a Handoff project from version 1.x.x to version 2.x.x.
+Each feature section identifies the affected projects and the required changes.
+
+### Before you start
+
+1. Verify that the project builds with its current Handoff version.
+2. Save the project files, package version, and lockfile in version control.
+3. Install the version 2.x.x package that you plan to use.
+4. Apply the migration sections that affect your project.
+
+### Breaking changes
+
+| Change | Affected projects |
+| --- | --- |
+| [Catalog items](#catalog-items) | Projects with component or pattern declarations |
+
+<!-- Add future breaking changes as feature sections before "Verify the upgrade". Add each section to this table. -->
+
+### Catalog items
+
+#### Affected projects
+
+This change affects projects that use the old component or pattern registration API.
+It also affects projects that use the deprecated API from an earlier version 2.x.x prerelease.
+Version 2.x.x requires `defineCatalogItem` for implementations and compositions.
+
+#### Register catalog directories
+
+Move component and pattern directories from `entries` to `catalog.include`.
+
+Version 1.x.x:
+
+```js
+entries: { components: ['components'], patterns: ['patterns'], scss: 'styles/main.scss' }
+```
+
+Version 2.x.x:
+
+```js
+catalog: { include: ['components', 'patterns'] },
+entries: { scss: 'styles/main.scss' }
+```
+
+Each path can name one item directory or a collection of item directories. Global `entries.js` and `entries.scss` still work.
+
+#### Convert declaration files
+
+Use `<name>.handoff.ts`, `<name>.handoff.js`, or `<name>.handoff.cjs`.
+Replace legacy filenames such as `button.json` or `button.js`.
+
+Version 2.x.x does not support JSON item declarations, including `.handoff.json`.
+JSON project config (`handoff.config.json`) remains supported.
+
+If `runtime.workspace.declarationFormat` is `json`, change it to `ts`, `js`, or `cjs`. The default remains `ts`.
+
+#### Replace declaration helpers
+
+| Removed API | Replacement |
+| --- | --- |
+| `defineReactComponent(Component, config)` | `defineCatalogItem({ ...config, implementation: Component })` from `handoff-app/react` |
+| `defineHandlebarsComponent(config)` | `defineCatalogItem({ ...config, implementation: './Button.hbs' })` from `handoff-app/handlebars` |
+| `defineCsfComponent(config)` | `defineCatalogItem({ ...config, implementation: fromCSF('./Button.stories.tsx') })` from `handoff-app/react` |
+| `defineComponent(config)` | `defineCatalogItem({ ...config, implementation: './Button.tsx' })` from the module for its renderer |
+| `definePattern({ components })` | `defineCatalogItem({ composition })` from `handoff-app/pattern` |
+
+Remove the old `renderer`, `entries.component`, `entries.template`, and `entries.story` fields.
+The implementation supplies the renderer and source file.
+Keep the supporting `entries.js`, `entries.scss`, `entries.schema`, and `entries.templates` paths that your item uses.
+Rename the metadata fields:
+
+| Old field | Version 2.x.x field |
+| --- | --- |
+| `title` | `name` |
+| `should_do` | `shouldDo` |
+| `should_not_do` | `shouldNotDo` |
+
+##### React
+
+```ts
+import { defineCatalogItem, type Preview } from 'handoff-app/react';
+import Button from './Button';
+
+const item = defineCatalogItem({
+  name: 'Button',
+  implementation: Button,
+  entries: { scss: './button.scss' },
+});
+export default item;
+export const Primary = { args: { children: 'Save' } } satisfies Preview<typeof item>;
+```
+
+Imported components retain their prop types. A file path also works: `implementation: './Button.tsx'`.
+Keep implementation files inside the item directory to publish them.
+
+##### Handlebars and CommonJS
+
+```js
+const { defineCatalogItem } = require('handoff-app/handlebars');
+
+exports.default = defineCatalogItem({
+  name: 'Badge',
+  implementation: './Badge.hbs',
+});
+exports.Primary = { args: { children: 'New' } };
+```
+
+Use this form in `.handoff.js` or `.handoff.cjs`. JavaScript declarations can also use `import` and `export`.
+
+##### CSF
+
+```ts
+import { defineCatalogItem, fromCSF } from 'handoff-app/react';
+
+export default defineCatalogItem({
+  name: 'Button',
+  implementation: fromCSF('./Button.stories.tsx'),
+});
+```
+
+CSF is a React source format. The story file supplies the previews.
+The filename does not select CSF automatically.
+
+##### Compositions
+
+```ts
+import { defineCatalogItem } from 'handoff-app/pattern';
+
+export default defineCatalogItem({
+  name: 'Toolbar',
+  composition: [{ ref: 'button', preview: 'Primary', args: { children: 'Save' } }],
+});
+```
+
+Rename `components` to `composition`.
+Rename each member's `id` to `ref`.
+Keep item IDs stable.
+
+#### Export previews
+
+Remove the inline `previews` map.
+Export each preview beside the default catalog item.
+Rename preview `title` to `name`.
+Rename `values` to `args`:
+
+```ts
+export const Primary = { name: 'Primary action', args: { children: 'Save' } };
+```
+
+If a preview key is a valid export name, preserve its spelling and capitalization.
+If a key is not a valid export name, rename it.
+Update composition references to each renamed preview.
+
+Previews appear in source export order.
+
+For CommonJS declarations, use `exports.default` for the item.
+Use a named export such as `exports.Primary` for each preview.
+
+#### Replace declaration types
+
+Replace imports of the removed types:
+
+| Removed type | Replacement |
+| --- | --- |
+| `Component` | `CatalogItem` |
+| `DeclarationPreview` | `CatalogPreview` or `Preview<typeof item>` |
+| `PatternComponentRef` | `CompositionRef` |
+| `ReactDeclarationConfig`, `HandlebarsDeclarationConfig`, `CsfDeclarationConfig` | The catalog helper's input type |
+| `GenericDeclarationConfig`, `GenericPatternDeclarationConfig` | The catalog helper's input type, or `CatalogItemMeta` for shared metadata |
+
+`RendererKind` comes from the catalog API and contains `react` and `handlebars`.
+CSF uses `renderer: 'react'` with `format: 'csf'` inside `implementation`.
+
+#### Registry projects
+
+Checkout writes only catalog declarations.
+Registry records require explicit renderer and source-format metadata where applicable.
+
+### Verify the upgrade
+
+After you apply the required migrations, verify the project:
+
+1. Build the project with version 2.x.x.
+2. Verify that all expected catalog items appear in the documentation.
+3. Verify the preview order, arguments, and composition references.
+4. Start the workspace with file watchers.
+5. Edit a declaration to verify that its previews update.
+
+If the project uses a registry, verify the published items:
+
+1. Publish the migrated items.
+2. Verify that checkout produces valid declarations.
+3. Rebuild the checked-out items.

package/config/config.template.js

@@ -54,13 +54,10 @@ const config = {
     ports: { app: 3000, websocket: 3001 },
   },
   // These are the entry points used to compile the target application
+  catalog: { include: ['./components'] },
   entries: {
     scss: './sass/main.scss',
     js: './js/main.js',
-    components: ['./components'],
-    // Uncomment to enable pattern documentation pages.
-    // Patterns compose component previews into single-page views.
-    // patterns: ['./patterns'],
   },
   // These are the asset zip file download links
   assetsZipLinks: {

package/config/config.template.ts

@@ -34,11 +34,10 @@ export default defineConfig({
     },
     ports: { app: 3000, websocket: 3001 },
   },
+  catalog: { include: ['./components'] },
   entries: {
     scss: './sass/main.scss',
     js: './js/main.js',
-    components: ['./components'],
-    // patterns: ['./patterns'],
   },
   assetsZipLinks: {
     icons: null,

package/dist/app-builder/build.js

@@ -695,14 +695,12 @@ const watchApp = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
         pendingHandlers: new Map(),
         runtimeComponentsWatcher: null,
         runtimeConfigurationWatcher: null,
-        componentDirectoriesWatcher: null,
-        patternDirectoriesWatcher: null,
+        catalogDirectoriesWatcher: null,
     };
     (0, watchers_1.watchPublicDirectory)(handoff, wss, state, chokidarConfig);
     (0, watchers_1.watchRuntimeComponents)(handoff, state, (0, watchers_1.getRuntimeComponentsPathsToWatch)(handoff));
     (0, watchers_1.watchRuntimeConfiguration)(handoff, state);
-    (0, watchers_1.watchComponentDirectories)(handoff, state, chokidarConfig);
-    (0, watchers_1.watchPatternDirectories)(handoff, state, chokidarConfig);
+    (0, watchers_1.watchCatalogDirectories)(handoff, state, chokidarConfig);
     (0, watchers_1.watchGlobalEntries)(handoff, state, chokidarConfig);
     (0, watchers_1.watchPages)(handoff, chokidarConfig);
 });

package/dist/app-builder/config-diff/strategies/pattern.js

@@ -43,12 +43,12 @@ const snapshot_1 = require("../snapshot");
  * components. Outer key is component id, inner key is synthetic preview key.
  */
 const snapshotPatternSynthetics = (handoff, patternId) => {
-    var _a, _b, _c, _d;
-    const components = (_c = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.components) !== null && _c !== void 0 ? _c : {};
+    var _a, _b, _c;
+    const components = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.components) !== null && _b !== void 0 ? _b : {};
     const prefix = `__pattern_${patternId}_`;
     const result = new Map();
     for (const [componentId, component] of Object.entries(components)) {
-        const previews = (_d = component.internalPatternPreviews) !== null && _d !== void 0 ? _d : {};
+        const previews = (_c = component.internalPatternPreviews) !== null && _c !== void 0 ? _c : {};
         const entries = new Map();
         for (const [key, preview] of Object.entries(previews)) {
             if (key.startsWith(prefix)) {

package/dist/app-builder/watchers/component.js

@@ -23,11 +23,11 @@ const mapEntryTypeToSegment = (type) => {
 };
 exports.mapEntryTypeToSegment = mapEntryTypeToSegment;
 const resolveComponentIdForChangedFile = (handoff, changedFilePath) => {
-    var _a, _b, _c, _d;
+    var _a, _b, _c;
     const normalizedChangedPath = (0, path_2.normalizePathForCompare)(changedFilePath);
-    const runtimeComponents = (_c = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.components) !== null && _c !== void 0 ? _c : {};
+    const runtimeComponents = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.components) !== null && _b !== void 0 ? _b : {};
     for (const [componentId, componentDef] of Object.entries(runtimeComponents)) {
-        const entries = (_d = componentDef.entries) !== null && _d !== void 0 ? _d : {};
+        const entries = (_c = componentDef.entries) !== null && _c !== void 0 ? _c : {};
         for (const entryPath of Object.values(entries)) {
             if (!entryPath)
                 continue;
@@ -49,8 +49,8 @@ exports.resolveComponentIdForChangedFile = resolveComponentIdForChangedFile;
 const getRuntimeComponentsPathsToWatch = (handoff) => {
     var _a, _b, _c;
     const result = new Map();
-    for (const runtimeComponentId of Object.keys((_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries.components) !== null && _b !== void 0 ? _b : {})) {
-        const runtimeComponent = handoff.runtimeConfig.entries.components[runtimeComponentId];
+    for (const runtimeComponentId of Object.keys((_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.components) !== null && _b !== void 0 ? _b : {})) {
+        const runtimeComponent = handoff.runtimeConfig.entities.components[runtimeComponentId];
         for (const [runtimeComponentEntryType, runtimeComponentEntryPath] of Object.entries((_c = runtimeComponent.entries) !== null && _c !== void 0 ? _c : {})) {
             const normalizedComponentEntryPath = runtimeComponentEntryPath;
             if (fs_extra_1.default.existsSync(normalizedComponentEntryPath)) {

package/dist/app-builder/watchers/utils.d.ts

@@ -4,9 +4,8 @@ export interface WatcherState {
     pendingHandlers: Map<string, () => Promise<void>>;
     runtimeComponentsWatcher: chokidar.FSWatcher | null;
     runtimeConfigurationWatcher: chokidar.FSWatcher | null;
-    componentDirectoriesWatcher: chokidar.FSWatcher | null;
-    /** Watches entries.patterns parent directories for newly created pattern subdirectories. */
-    patternDirectoriesWatcher: chokidar.FSWatcher | null;
+    /** Watches every registered catalog directory for newly created item subdirectories. */
+    catalogDirectoriesWatcher: chokidar.FSWatcher | null;
 }
 /**
  * Schedules a handler for execution with mutual exclusion and per-source

package/dist/app-builder/watchers.d.ts

@@ -36,19 +36,12 @@ export declare const watchRuntimeComponents: (handoff: Handoff, state: WatcherSt
  */
 export declare const watchRuntimeConfiguration: (handoff: Handoff, state: WatcherState) => void;
 /**
- * Watches the parent component directories from config.entries.components for
- * new components being added. When a new config file appears in a new
- * subdirectory, reloads the runtime config, restarts the component and
- * configuration watchers, then builds the new component and any patterns that
- * reference it.
- */
-export declare const watchComponentDirectories: (handoff: Handoff, state: WatcherState, chokidarConfig: chokidar.WatchOptions) => void;
-/**
- * Watches the parent pattern directories from config.entries.patterns for new
- * patterns being added. The rebuild sequence intentionally differs from
- * watchComponentDirectories because the dependency arrow is reversed: a new
- * pattern references existing components, so we rebuild only the preview
- * segment of those components (to produce the __pattern_* HTML files that
- * injectPatternPreviews registered) before composing the pattern itself.
+ * Watches `catalog.include` directories for a new item. A single watcher covers implementations
+ * and compositions; the declaration determines which pipeline builds the item.
+ *
+ * The rebuild differs by kind, and the dependency arrow is reversed between them. A new item with
+ * an implementation builds itself, then the compositions that reference it. A new composition
+ * rebuilds the preview segment of the items it references, so the synthetic `__pattern_*` HTML
+ * exists, and only then composes itself.
  */
-export declare const watchPatternDirectories: (handoff: Handoff, state: WatcherState, chokidarConfig: chokidar.WatchOptions) => void;
+export declare const watchCatalogDirectories: (handoff: Handoff, state: WatcherState, chokidarConfig: chokidar.WatchOptions) => void;