handoff-app 2.0.0-5 → 2.0.0-7

package/dist/catalog/normalize.js

@@ -0,0 +1,115 @@
+"use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeCatalogItem = void 0;
+const lodash_1 = require("lodash");
+const path_1 = __importDefault(require("path"));
+const define_1 = require("./define");
+const implementation_1 = require("./implementation");
+const previews_1 = require("./previews");
+const renderers_1 = require("./renderers");
+/** Imported component values need a file path recovered from the declaration source. */
+const resolveImplementation = (item, options) => {
+    const stamped = item.implementation;
+    const source = { renderer: stamped.renderer, sourceFormat: stamped.format };
+    if (stamped.file) {
+        return Object.assign(Object.assign({}, source), { file: stamped.file });
+    }
+    const declarationDir = path_1.default.dirname(options.declarationPath);
+    const resolved = (0, implementation_1.resolvePropertySource)(options.declarationPath, 'implementation');
+    if (resolved) {
+        if (!(0, implementation_1.isInsideDirectory)(resolved.file, declarationDir)) {
+            options.warn(`Catalog item "${options.fallbackId}" resolves its implementation to "${resolved.file}", outside "${declarationDir}". ` +
+                `Previews still build, but the item cannot be published. Move the file into the item directory to publish it.`);
+        }
+        return Object.assign(Object.assign({}, source), { file: resolved.file, exportName: resolved.exportName });
+    }
+    const sibling = (0, implementation_1.findSiblingComponentFile)(declarationDir, options.declarationPath);
+    if (sibling) {
+        options.warn(`Catalog item "${options.fallbackId}" in "${options.declarationPath}" could not resolve the import behind ` +
+            `"implementation". Using "${path_1.default.basename(sibling)}". Set "implementation" to the file path to be explicit.`);
+        return Object.assign(Object.assign({}, source), { file: sibling });
+    }
+    options.warn(`Catalog item "${options.fallbackId}" in "${options.declarationPath}" could not resolve the import behind ` +
+        `"implementation". Set "implementation" to the file path instead of the imported value.`);
+    return source;
+};
+const quotedList = (values) => values.map((value) => `"${value}"`).join(' or ');
+/** Maps the authoring contract directly into the runtime read model. */
+const normalizeCatalogItem = (moduleExports, options) => {
+    var _a, _b, _c;
+    const item = (_a = moduleExports.default) !== null && _a !== void 0 ? _a : moduleExports;
+    (0, define_1.validateCatalogItem)(item);
+    const { implementation, composition, __args, name, shouldDo, shouldNotDo } = item, meta = __rest(item, ["implementation", "composition", "__args", "name", "shouldDo", "shouldNotDo"]);
+    const id = typeof meta.id === 'string' && meta.id.trim() ? meta.id.trim() : options.fallbackId;
+    const title = name || (0, lodash_1.startCase)(id);
+    const directory = path_1.default.dirname(options.declarationPath);
+    if (composition) {
+        return {
+            kind: 'pattern',
+            item: {
+                id,
+                title,
+                path: directory,
+                description: meta.description,
+                group: meta.group,
+                tags: meta.tags,
+                components: composition.map((ref) => ({
+                    id: ref.ref.trim(),
+                    preview: typeof ref.preview === 'string' ? ref.preview.trim() : undefined,
+                    args: ref.args ? Object.assign({}, ref.args) : undefined,
+                })),
+            },
+        };
+    }
+    const source = resolveImplementation(item, options);
+    const entries = {};
+    for (const [key, value] of Object.entries((_b = meta.entries) !== null && _b !== void 0 ? _b : {})) {
+        if (value)
+            entries[key] = path_1.default.resolve(directory, value);
+    }
+    const entryKey = (0, renderers_1.entryKeyFor)(source.renderer, source.sourceFormat);
+    if (!source.file) {
+        throw new Error(`Catalog item "${id}" needs an implementation file. Set implementation to a file path.`);
+    }
+    entries[entryKey] = path_1.default.resolve(directory, source.file);
+    // Existing builders consume template as the primary build input for every renderer.
+    entries.template = entries[entryKey];
+    // A wrong renderer builds a broken preview without failing on its own, so a mismatch is fatal.
+    // `config/runtime.ts` turns the throw into a skipped item that retries on the next save.
+    const claim = (0, renderers_1.sourceForFile)(source.file);
+    if (claim && !claim.renderers.includes(source.renderer)) {
+        throw new Error(`Catalog item "${id}" declares renderer "${source.renderer}", but "${source.file}" is a ${quotedList(claim.renderers)} source. ` +
+            `Declare it from ${quotedList(claim.renderers.map(renderers_1.moduleFor))}.`);
+    }
+    // Only a suffix that names a format is conclusive. A `.stories.tsx` file is always CSF, while a
+    // plain `.tsx` file says nothing about its format.
+    const fileFormat = claim === null || claim === void 0 ? void 0 : claim.format;
+    // The comparison narrows a single-format union to `never`, so read the helper first.
+    const fileFormatHelper = fileFormat && renderers_1.SOURCE_FORMATS[fileFormat].helper;
+    if (fileFormat && fileFormat !== source.sourceFormat) {
+        throw new Error(`Catalog item "${id}" declares "${source.file}" as a plain source, but it is a "${fileFormat}" source. ` +
+            `Wrap it with ${fileFormatHelper}() from "${(0, renderers_1.moduleFor)(source.renderer)}".`);
+    }
+    if (((_c = meta.page) === null || _c === void 0 ? void 0 : _c.slices) && !Array.isArray(meta.page.slices)) {
+        throw new Error(`Catalog item "${id}" has invalid page.slices; expected an array.`);
+    }
+    return {
+        kind: 'component',
+        item: Object.assign(Object.assign(Object.assign(Object.assign({}, meta), { id, title: name || '', path: directory, should_do: shouldDo, should_not_do: shouldNotDo, renderer: source.renderer, sourceFormat: source.sourceFormat, entries }), (source.exportName && source.exportName !== 'default' ? { componentExport: source.exportName } : {})), { previews: (0, previews_1.createCatalogPreviews)(moduleExports, options.declarationPath) }),
+    };
+};
+exports.normalizeCatalogItem = normalizeCatalogItem;

package/dist/catalog/previews.d.ts

@@ -0,0 +1,18 @@
+import type { OptionalPreviewRender } from '../transformers/preview/types';
+/**
+ * Exported names in the order the source declares them.
+ *
+ * The evaluated module cannot supply this order. esbuild emits its export map alphabetically, and
+ * an ESM namespace object has sorted keys by specification.
+ */
+export declare const readExportOrderFromSource: (sourceCode: string) => string[];
+/** Exported names in source order, or an empty list when the file cannot be read. */
+export declare const readExportOrder: (filePath: string) => string[];
+/**
+ * Re-keys previews into the given order. A preview the order does not mention is placed after the
+ * ordered ones, so an export form the parser does not recognize falls back to the evaluated order
+ * rather than dropping the preview.
+ */
+export declare const orderPreviews: <T>(previews: Record<string, T>, order: string[]) => Record<string, T>;
+/** Collects the named exports of a declaration module as previews, in declaration order. */
+export declare const createCatalogPreviews: (moduleExports: Record<string, unknown>, declarationPath?: string) => Record<string, OptionalPreviewRender>;

package/dist/catalog/previews.js

@@ -0,0 +1,106 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCatalogPreviews = exports.orderPreviews = exports.readExportOrder = exports.readExportOrderFromSource = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const lodash_1 = require("lodash");
+/**
+ * A declaration module exports more than previews: the item itself, the implementation it
+ * re-exports, helper values. Accept only a plain object that owns `args` or `name`, so an exported
+ * component or helper is never mistaken for a preview.
+ *
+ * `getCsfStoryEntries` does not fit here: on a CSF file every named export is a story, and on a
+ * declaration file it is not.
+ */
+const isPreviewDeclaration = (value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    return Object.prototype.hasOwnProperty.call(value, 'args') || Object.prototype.hasOwnProperty.call(value, 'name');
+};
+/** Matches an exported binding, an export list, or a CommonJS export assignment. */
+const EXPORT_PATTERNS = [
+    { pattern: /\bexport\s+(?:async\s+)?(?:const|let|var|function\s*\*?|class)\s+([A-Za-z_$][\w$]*)/g },
+    { pattern: /\bexport\s*(?!type[\s{])\{([^}]*)\}/g, list: true },
+    { pattern: /\bexports\.([A-Za-z_$][\w$]*)\s*=/g },
+];
+/** Reads the exported name an export-list specifier binds: `A as B` exports `B`, `A` exports `A`. */
+const readExportedName = (specifier) => {
+    const name = specifier.trim().replace(/^type\s+/, '');
+    if (!name)
+        return undefined;
+    const aliased = name.match(/^[A-Za-z_$][\w$]*\s+as\s+([A-Za-z_$][\w$]*)$/);
+    if (aliased)
+        return aliased[1];
+    return /^[A-Za-z_$][\w$]*$/.test(name) ? name : undefined;
+};
+/**
+ * Exported names in the order the source declares them.
+ *
+ * The evaluated module cannot supply this order. esbuild emits its export map alphabetically, and
+ * an ESM namespace object has sorted keys by specification.
+ */
+const readExportOrderFromSource = (sourceCode) => {
+    const found = [];
+    for (const { pattern, list } of EXPORT_PATTERNS) {
+        for (const match of sourceCode.matchAll(pattern)) {
+            const names = list ? match[1].split(',').map(readExportedName) : [match[1]];
+            names.forEach((name, offset) => {
+                if (name)
+                    found.push({ index: match.index + offset, name });
+            });
+        }
+    }
+    const order = [];
+    const seen = new Set();
+    for (const { name } of found.sort((a, b) => a.index - b.index)) {
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        order.push(name);
+    }
+    return order;
+};
+exports.readExportOrderFromSource = readExportOrderFromSource;
+/** Exported names in source order, or an empty list when the file cannot be read. */
+const readExportOrder = (filePath) => {
+    try {
+        return (0, exports.readExportOrderFromSource)(fs_extra_1.default.readFileSync(filePath, 'utf8'));
+    }
+    catch (_a) {
+        return [];
+    }
+};
+exports.readExportOrder = readExportOrder;
+/**
+ * Re-keys previews into the given order. A preview the order does not mention is placed after the
+ * ordered ones, so an export form the parser does not recognize falls back to the evaluated order
+ * rather than dropping the preview.
+ */
+const orderPreviews = (previews, order) => {
+    if (order.length === 0)
+        return previews;
+    const ranked = new Set(order.filter((name) => name in previews));
+    const rest = Object.keys(previews).filter((name) => !ranked.has(name));
+    return Object.fromEntries([...ranked, ...rest].map((name) => [name, previews[name]]));
+};
+exports.orderPreviews = orderPreviews;
+/** Collects the named exports of a declaration module as previews, in declaration order. */
+const createCatalogPreviews = (moduleExports, declarationPath) => {
+    var _a, _b;
+    const previews = {};
+    for (const [exportName, value] of Object.entries(moduleExports !== null && moduleExports !== void 0 ? moduleExports : {})) {
+        if (exportName === 'default' || exportName === '__esModule')
+            continue;
+        if (!isPreviewDeclaration(value))
+            continue;
+        if (value && typeof value === 'object' && ('values' in value || 'title' in value)) {
+            throw new Error(`Preview "${exportName}" uses removed fields. Use args and name. See UPGRADE.md#catalog-items.`);
+        }
+        const preview = value;
+        previews[exportName] = Object.assign({ title: preview.name || (0, lodash_1.startCase)(exportName), values: Object.assign({}, ((_a = preview.args) !== null && _a !== void 0 ? _a : {})), url: (_b = preview.url) !== null && _b !== void 0 ? _b : '' }, (preview.usage ? { usage: preview.usage } : {}));
+    }
+    return declarationPath ? (0, exports.orderPreviews)(previews, (0, exports.readExportOrder)(declarationPath)) : previews;
+};
+exports.createCatalogPreviews = createCatalogPreviews;

package/dist/catalog/renderers.d.ts

@@ -0,0 +1,43 @@
+/**
+ * This module has no runtime imports, so every layer can use the renderer registry.
+ * Import it directly to avoid the catalog barrel dependencies, including `fs-extra`.
+ */
+/** Add a renderer only with its preview support. */
+export type RendererKind = 'react' | 'handlebars';
+/** How an implementation file is written, independent of the renderer that renders it. */
+export type SourceFormat = 'csf';
+/** Key in `entries` that holds an implementation file. */
+export type EntryKey = 'component' | 'template' | 'story';
+export type ComponentSource = {
+    renderer: RendererKind;
+    sourceFormat?: SourceFormat;
+};
+type RendererDefinition = {
+    /** Declaration module that supplies this renderer. */
+    module: string;
+    /** Entry key normalization writes the implementation file to. */
+    entryKey: EntryKey;
+};
+type SourceFormatDefinition = {
+    /** Renderers this format applies to. */
+    renderers: RendererKind[];
+    entryKey: EntryKey;
+    /** Export of the renderer module that declares an implementation in this format. */
+    helper: string;
+};
+export declare const RENDERERS: Record<RendererKind, RendererDefinition>;
+export declare const SOURCE_FORMATS: Record<SourceFormat, SourceFormatDefinition>;
+/** Which renderers can own a file name, and the source format the name implies. */
+export type SourceClaim = {
+    renderers: RendererKind[];
+    format?: SourceFormat;
+};
+export declare const isRendererKind: (value: unknown) => value is RendererKind;
+export declare const isSourceFormat: (value: unknown) => value is SourceFormat;
+/** What the file name says about a source, matched case-insensitively. Undefined when no suffix claims it. */
+export declare const sourceForFile: (file: string | undefined) => SourceClaim | undefined;
+/** Entry key normalization records the implementation file under, if the renderer is registered. */
+export declare const entryKeyFor: (renderer: RendererKind | undefined, sourceFormat?: SourceFormat) => EntryKey | undefined;
+/** Declaration module that supplies a renderer, or undefined when it has no module of its own. */
+export declare const moduleFor: (renderer: RendererKind | undefined) => string | undefined;
+export {};

package/dist/catalog/renderers.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * This module has no runtime imports, so every layer can use the renderer registry.
+ * Import it directly to avoid the catalog barrel dependencies, including `fs-extra`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.moduleFor = exports.entryKeyFor = exports.sourceForFile = exports.isSourceFormat = exports.isRendererKind = exports.SOURCE_FORMATS = exports.RENDERERS = void 0;
+exports.RENDERERS = {
+    react: {
+        module: 'handoff-app/react',
+        entryKey: 'component',
+    },
+    handlebars: {
+        module: 'handoff-app/handlebars',
+        entryKey: 'template',
+    },
+};
+exports.SOURCE_FORMATS = {
+    csf: {
+        renderers: ['react'],
+        entryKey: 'story',
+        helper: 'fromCSF',
+    },
+};
+/**
+ * This table never decides a renderer. The declaration states it, and the table only checks the
+ * implementation file against it. Keying by suffix keeps one row per file name: a suffix that more
+ * than one renderer owns lists them all, and a duplicate key is a compile error. A file that no
+ * row claims is not checked.
+ */
+const SOURCE_SUFFIXES = {
+    '.stories.tsx': { renderers: ['react'], format: 'csf' },
+    '.stories.jsx': { renderers: ['react'], format: 'csf' },
+    '.stories.ts': { renderers: ['react'], format: 'csf' },
+    '.stories.js': { renderers: ['react'], format: 'csf' },
+    '.tsx': { renderers: ['react'] },
+    '.jsx': { renderers: ['react'] },
+    '.hbs': { renderers: ['handlebars'] },
+};
+/** Longest first, so `.stories.tsx` reads as a CSF source rather than a plain React source. */
+const SUFFIXES_BY_LENGTH = Object.keys(SOURCE_SUFFIXES).sort((first, second) => second.length - first.length);
+const RENDERER_KINDS = Object.keys(exports.RENDERERS);
+const SOURCE_FORMAT_KINDS = Object.keys(exports.SOURCE_FORMATS);
+const isRendererKind = (value) => RENDERER_KINDS.includes(value);
+exports.isRendererKind = isRendererKind;
+const isSourceFormat = (value) => SOURCE_FORMAT_KINDS.includes(value);
+exports.isSourceFormat = isSourceFormat;
+/** What the file name says about a source, matched case-insensitively. Undefined when no suffix claims it. */
+const sourceForFile = (file) => {
+    if (!file)
+        return undefined;
+    const lowerCased = file.toLowerCase();
+    const suffix = SUFFIXES_BY_LENGTH.find((candidate) => lowerCased.endsWith(candidate));
+    return suffix ? SOURCE_SUFFIXES[suffix] : undefined;
+};
+exports.sourceForFile = sourceForFile;
+/** Entry key normalization records the implementation file under, if the renderer is registered. */
+const entryKeyFor = (renderer, sourceFormat) => { var _a, _b; return sourceFormat ? (_a = exports.SOURCE_FORMATS[sourceFormat]) === null || _a === void 0 ? void 0 : _a.entryKey : renderer ? (_b = exports.RENDERERS[renderer]) === null || _b === void 0 ? void 0 : _b.entryKey : undefined; };
+exports.entryKeyFor = entryKeyFor;
+/** Declaration module that supplies a renderer, or undefined when it has no module of its own. */
+const moduleFor = (renderer) => { var _a; return (renderer ? (_a = exports.RENDERERS[renderer]) === null || _a === void 0 ? void 0 : _a.module : undefined); };
+exports.moduleFor = moduleFor;

package/dist/catalog/types.d.ts

@@ -0,0 +1,63 @@
+import type { RendererKind, SourceFormat } from './renderers';
+import type { ComponentObject } from '../transformers/preview/types';
+/**
+ * How an implementation file is written. `fromCSF('./Button.stories.tsx')` is shorthand for
+ * `{ format: 'csf', file: './Button.stories.tsx' }`.
+ */
+export type SourceDescriptor<TFormat extends string = string> = {
+    format: TFormat;
+    file: string;
+};
+export type CsfSource = SourceDescriptor<'csf'>;
+/** The loader recovers the file for an imported component in `value` from the declaration source. */
+export type NormalizedImplementation = {
+    renderer: RendererKind;
+    format?: SourceFormat;
+    file?: string;
+    value?: unknown;
+};
+export type CatalogItemEntries = Pick<NonNullable<ComponentObject['entries']>, 'js' | 'scss' | 'schema' | 'templates'>;
+/**
+ * Metadata a catalog item can carry. `type` and `categories` are free-form classification, so a
+ * term such as atom, element, or block goes there.
+ */
+export type CatalogItemMeta = Partial<Omit<ComponentObject, 'previews' | 'previewOrder' | 'entries' | 'title' | 'should_do' | 'should_not_do' | 'renderer' | 'sourceFormat' | 'componentExport'>> & {
+    id?: string;
+    name?: string;
+    description?: string;
+    group?: string;
+    entries?: CatalogItemEntries;
+    shouldDo?: string[];
+    shouldNotDo?: string[];
+};
+/** One member of a composition. `ref` is the id of another catalog item. */
+export type CompositionRef = {
+    ref: string;
+    preview?: string;
+    args?: Record<string, unknown>;
+};
+/** A named preview, exported next to the catalog item it belongs to. */
+export type CatalogPreview<TArgs = Record<string, unknown>> = {
+    /** Display title. Defaults to a start-cased form of the export name. */
+    name?: string;
+    args?: TArgs;
+    usage?: string;
+    url?: string;
+};
+/**
+ * `__args` exists only in the type system so `Preview<typeof item>` can infer the preview argument type.
+ */
+export type CatalogItem<TArgs = Record<string, unknown>> = CatalogItemMeta & {
+    implementation?: unknown;
+    composition?: CompositionRef[];
+    readonly __args?: TArgs;
+};
+/** Preview type for a catalog item, with its argument type applied. */
+export type Preview<TItem> = TItem extends {
+    readonly __args?: infer TArgs;
+} ? CatalogPreview<Partial<NonNullable<TArgs>>> : never;
+/** Input accepted by every `defineCatalogItem` entry point. */
+export type CatalogItemInput = CatalogItemMeta & {
+    implementation?: unknown;
+    composition?: CompositionRef[];
+};

package/dist/cli/make.d.ts

@@ -1,9 +1,4 @@
 import Handoff from '../index';
-/**
- * Make a new exportable component
- * @param handoff
- */
-export declare const makeTemplate: (handoff: Handoff, component: string, state: string) => Promise<Handoff>;
 /**
  * Make a new docs page
  * @param handoff

package/dist/cli/make.js

@@ -35,54 +35,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.makeComponent = exports.makePage = exports.makeTemplate = void 0;
+exports.makeComponent = exports.makePage = void 0;
+const catalog_include_1 = require("../config/catalog-include");
+const runtime_1 = require("../config/runtime");
 const p = __importStar(require("@clack/prompts"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const logger_1 = require("../utils/logger");
-/**
- * Make a new exportable component
- * @param handoff
- */
-const makeTemplate = (handoff, component, state) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b;
-    if (!((_b = (_a = handoff === null || handoff === void 0 ? void 0 : handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.templates)) {
-        logger_1.Logger.error(`Runtime config does not specify entry for templates.`);
-        return;
-    }
-    if (!component) {
-        logger_1.Logger.error(`Template component must be set`);
-        return;
-    }
-    if (!state) {
-        state = 'default';
-    }
-    if (!/^[a-z0-9]+$/i.test(component)) {
-        logger_1.Logger.error(`Template component must be alphanumeric and may contain dashes or underscores`);
-        return;
-    }
-    if (!/^[a-z0-9]+$/i.test(state)) {
-        logger_1.Logger.error(`Template state must be alphanumeric and may contain dashes or underscores`);
-        return;
-    }
-    const workingPath = path_1.default.resolve(handoff.runtimeConfig.entries.templates, component);
-    if (!fs_extra_1.default.existsSync(workingPath)) {
-        fs_extra_1.default.mkdirSync(workingPath, { recursive: true });
-    }
-    const target = path_1.default.resolve(workingPath, `${state}.html`);
-    if (fs_extra_1.default.existsSync(target)) {
-        if (!handoff.force) {
-            logger_1.Logger.warn(`'${state}' already exists as custom template.  Use the --force flag revert it to default.`);
-            return;
-        }
-    }
-    const templatePath = path_1.default.resolve(path_1.default.join(handoff.modulePath, 'config/templates', 'template.html'));
-    const template = fs_extra_1.default.readFileSync(templatePath, 'utf8');
-    fs_extra_1.default.writeFileSync(target, template);
-    logger_1.Logger.success(`New template ${state}.html was created in ${workingPath}`);
-    return handoff;
-});
-exports.makeTemplate = makeTemplate;
 /**
  * Make a new docs page
  * @param handoff
@@ -136,22 +95,15 @@ exports.makePage = makePage;
  */
 const DEFAULT_COMPONENTS_DIR = 'components';
 const makeComponent = (handoff, name) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b, _c;
+    var _a, _b;
     if (!name) {
         logger_1.Logger.error(`Component name must be set`);
         return;
     }
     name = name.replace('.html', '');
-    let componentsRoot;
-    if ((_c = (_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.components) === null || _c === void 0 ? void 0 : _c.length) {
-        componentsRoot = path_1.default.resolve(handoff.workingPath, handoff.config.entries.components[0]);
-    }
-    else {
-        componentsRoot = path_1.default.resolve(handoff.workingPath, DEFAULT_COMPONENTS_DIR);
-        logger_1.Logger.warn(`No entries.components configured in handoff.config.*. ` +
-            `Scaffolding into "${DEFAULT_COMPONENTS_DIR}/". ` +
-            `Add this path to entries.components in your config so the build picks it up.`);
-    }
+    const configuredRoot = (_b = (_a = handoff.config.catalog) === null || _a === void 0 ? void 0 : _a.include) === null || _b === void 0 ? void 0 : _b[0];
+    const root = path_1.default.resolve(handoff.workingPath, configuredRoot !== null && configuredRoot !== void 0 ? configuredRoot : DEFAULT_COMPONENTS_DIR);
+    const componentsRoot = (0, runtime_1.isComponentDirectory)(root) ? path_1.default.dirname(root) : root;
     let workingPath = path_1.default.resolve(componentsRoot, name);
     if (!fs_extra_1.default.existsSync(workingPath)) {
         fs_extra_1.default.mkdirSync(workingPath, { recursive: true });
@@ -188,34 +140,37 @@ const makeComponent = (handoff, name) => __awaiter(void 0, void 0, void 0, funct
         const scssTemplate = fs_extra_1.default.readFileSync(scssPath, 'utf8');
         fs_extra_1.default.writeFileSync(path_1.default.resolve(workingPath, `${name}.scss`), scssTemplate);
     }
-    const declarationEntries = [`template: './${name}.hbs'`];
+    // `implementation` names the template, so `entries` carries only supporting files.
+    const declarationEntries = [];
     if (writeJSFile === true) {
         declarationEntries.push(`js: './${name}.js'`);
     }
     if (writeSassFile === true) {
         declarationEntries.push(`scss: './${name}.scss'`);
     }
-    const declarationContent = `const { defineHandlebarsComponent } = require('handoff-app');
+    const entriesBlock = declarationEntries.length ? `\n  entries: {\n    ${declarationEntries.join(',\n    ')}\n  },` : '';
+    const declarationContent = `const { defineCatalogItem } = require('handoff-app/handlebars');
 
-module.exports = defineHandlebarsComponent({
+exports.default = defineCatalogItem({
   id: '${name}',
   name: '',
   description: '',
   group: '',
   type: 'element',
-  entries: {
-    ${declarationEntries.join(',\n    ')}
-  },
-  previews: {
-    default: {
-      title: 'Default',
-      args: {}
-    }
-  }
+  implementation: './${name}.hbs',${entriesBlock}
 });
+
+exports.Default = {
+  args: {},
+};
 `;
     fs_extra_1.default.writeFileSync(path_1.default.resolve(workingPath, `${name}.handoff.js`), declarationContent);
     logger_1.Logger.success(`New component declaration ${name}.handoff.js was created in ${workingPath}`);
+    if (!(0, catalog_include_1.isIncluded)(handoff, workingPath)) {
+        const result = yield (0, catalog_include_1.addToCatalog)(handoff, [workingPath]);
+        if (result.status === 'unsupported')
+            logger_1.Logger.warn(`Add ${result.pending.join(', ')} to catalog.include in handoff.config.`);
+    }
     return handoff;
 });
 exports.makeComponent = makeComponent;