@ethlete/components 1.0.0-next.37 → 1.0.0-next.39

package/generators/component/component-names.js

@@ -0,0 +1,19 @@
+import { names } from '@nx/devkit';
+const KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+export function componentNames(name) {
+    const { fileName, className, constantName } = names(name.trim());
+    if (!KEBAB.test(fileName)) {
+        throw new Error(`"${name}" is not a usable domain name. Use kebab-case, e.g. "stat-tile".`);
+    }
+    const words = fileName.replace(/-/g, ' ');
+    return {
+        fileName,
+        className,
+        constantName,
+        elementSelector: `et-${fileName}`,
+        attributeSelector: `et${className}`,
+        title: words.charAt(0).toUpperCase() + words.slice(1),
+        storyIdPrefix: `components-${fileName}`,
+    };
+}
+//# sourceMappingURL=component-names.js.map

package/generators/component/component-templates.js

@@ -0,0 +1,211 @@
+export const TIERS = ['both', 'component', 'headless'];
+const TICK = '`';
+export function directiveFile(n) {
+    return `import { Directive } from '@angular/core';
+
+/**
+ * Describe the behavior and state this directive owns, and the markup it expects around it.
+ *
+ * @example
+ * <div ${n.attributeSelector}>…</div>
+ */
+@Directive({
+  selector: '[${n.attributeSelector}]',
+})
+export class ${n.className}Directive {}
+`;
+}
+export function componentFile(n, options) {
+    const headless = options.tier === 'both';
+    const importPath = `./headless/${n.fileName}.directive`;
+    return `import { Component, ViewEncapsulation } from '@angular/core';
+${headless ? `import { ${n.className}Directive } from '${importPath}';\n` : ''}
+/**
+ * Describe what this component renders and when to reach for it.
+ *
+ * @example
+ * <${n.elementSelector}>…</${n.elementSelector}>
+ */
+@Component({
+  selector: '${n.elementSelector}',
+  template: ${TICK}<ng-content />${TICK},
+  styleUrl: './${n.fileName}.component.css',
+  encapsulation: ViewEncapsulation.None,
+${headless ? `  hostDirectives: [${n.className}Directive],\n` : ''}  host: {
+    class: '${n.elementSelector}',
+  },
+})
+export class ${n.className}Component {}
+`;
+}
+export function stylesFile(n) {
+    return `@layer components {
+  .${n.elementSelector} {
+    display: block;
+  }
+}
+`;
+}
+export function errorsFile(n, block) {
+    return `// codes ${block}-${block + 99}
+export const ${n.constantName}_ERROR_CODES = {
+  /** Describe the misuse this code reports. */
+  PLACEHOLDER: ${block},
+} as const;
+`;
+}
+export function importsFile(n, options) {
+    const component = `import { ${n.className}Component } from './${n.fileName}.component';`;
+    const directive = options.tier === 'both'
+        ? `import { ${n.className}Directive } from './headless/${n.fileName}.directive';`
+        : `import { ${n.className}Directive } from './${n.fileName}.directive';`;
+    const imports = options.tier === 'both' ? `${directive}\n${component}` : options.tier === 'component' ? component : directive;
+    const members = options.tier === 'both'
+        ? `${n.className}Component, ${n.className}Directive`
+        : options.tier === 'component'
+            ? `${n.className}Component`
+            : `${n.className}Directive`;
+    return `${imports}
+
+export const ${n.constantName}_IMPORTS = [${members}] as const;
+`;
+}
+export function headlessBarrelFile(n) {
+    return `export * from './${n.fileName}.directive';\n`;
+}
+export function barrelFile(n, options) {
+    const exports = [];
+    if (options.tier === 'both')
+        exports.push(`export * from './headless';`);
+    if (options.tier === 'headless')
+        exports.push(`export * from './${n.fileName}.directive';`);
+    if (options.tier !== 'headless')
+        exports.push(`export * from './${n.fileName}.component';`);
+    if (options.errors)
+        exports.push(`export * from './${n.fileName}-errors';`);
+    exports.push(`export * from './${n.fileName}.imports';`);
+    return `${exports.join('\n')}\n`;
+}
+export function specFile(n, options) {
+    if (options.tier === 'headless') {
+        return `import { Component } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { By } from '@angular/platform-browser';
+import '../../test-helpers';
+import { ${n.className}Directive } from './${n.fileName}.directive';
+import { ${n.constantName}_IMPORTS } from './${n.fileName}.imports';
+
+@Component({
+  selector: 'et-test-${n.fileName}-host',
+  template: ${TICK}<div ${n.attributeSelector}>Content</div>${TICK},
+  imports: [${n.constantName}_IMPORTS],
+})
+class ${n.className}HostComponent {}
+
+describe('${n.className}Directive', () => {
+  it('applies to its host', () => {
+    const fixture = TestBed.createComponent(${n.className}HostComponent);
+    fixture.detectChanges();
+
+    expect(fixture.debugElement.query(By.directive(${n.className}Directive))).not.toBeNull();
+  });
+});
+`;
+    }
+    return `import { Component } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import '../../test-helpers';
+import { ${n.constantName}_IMPORTS } from './${n.fileName}.imports';
+
+@Component({
+  selector: 'et-test-${n.fileName}-host',
+  template: ${TICK}<${n.elementSelector}>Content</${n.elementSelector}>${TICK},
+  imports: [${n.constantName}_IMPORTS],
+})
+class ${n.className}HostComponent {}
+
+describe('${n.className}Component', () => {
+  it('renders its projected content', () => {
+    const fixture = TestBed.createComponent(${n.className}HostComponent);
+    fixture.detectChanges();
+
+    const host = fixture.nativeElement.querySelector('${n.elementSelector}') as HTMLElement;
+
+    expect(host.classList.contains('${n.elementSelector}')).toBe(true);
+    expect(host.textContent?.trim()).toBe('Content');
+  });
+});
+`;
+}
+export function storybookComponentFile(n, options) {
+    const markup = options.tier === 'headless'
+        ? `<div ${n.attributeSelector}>${n.title}</div>`
+        : `<${n.elementSelector}>${n.title}</${n.elementSelector}>`;
+    return `import { Component, ViewEncapsulation } from '@angular/core';
+import { ${n.constantName}_IMPORTS } from '../${n.fileName}.imports';
+
+@Component({
+  selector: 'et-sb-${n.fileName}',
+  template: ${TICK}
+    <div class="p-8 font-sans">
+      ${markup}
+    </div>
+  ${TICK},
+  encapsulation: ViewEncapsulation.None,
+  imports: [${n.constantName}_IMPORTS],
+})
+export class ${n.className}StorybookComponent {}
+`;
+}
+export function storiesFile(n) {
+    return `import { Meta, moduleMetadata, StoryObj } from '@storybook/angular';
+import { ${n.className}StorybookComponent } from './${n.fileName}-storybook.component';
+
+export default {
+  title: 'Components/${n.title}',
+  component: ${n.className}StorybookComponent,
+  decorators: [moduleMetadata({ imports: [${n.className}StorybookComponent] })],
+} as Meta<${n.className}StorybookComponent>;
+
+type Story = StoryObj<${n.className}StorybookComponent>;
+
+export const Default: Story = {};
+`;
+}
+export function docsFile(n, options) {
+    const subject = options.tier === 'headless' ? `${TICK}[${n.attributeSelector}]${TICK}` : `${TICK}${n.elementSelector}${TICK}`;
+    const markup = options.tier === 'headless'
+        ? `<div ${n.attributeSelector}>…</div>`
+        : `<${n.elementSelector}>…</${n.elementSelector}>`;
+    return `# ${n.title}
+
+${subject} is … Say what it is in one sentence, then when to reach for it over the alternatives. Import ${TICK}${n.constantName}_IMPORTS${TICK}.
+
+${TICK}${TICK}${TICK}ts
+import { ${n.constantName}_IMPORTS } from '@ethlete/components';
+${TICK}${TICK}${TICK}
+
+${TICK}${TICK}${TICK}html
+${markup}
+${TICK}${TICK}${TICK}
+
+## Live demo
+
+<StoryEmbed id="${n.storyIdPrefix}--default" height="240px" />
+
+## Options
+
+| Input | Type | Default | Description |
+| ----- | ---- | ------- | ----------- |
+
+## Accessibility
+
+Describe the roles, the keyboard model and what a screen reader announces.
+
+## Theming
+
+List the public ${TICK}--et-${n.fileName}-*${TICK} design tokens and their defaults, and which theming tokens the
+colors resolve from. See [theming](/core/theming).
+`;
+}
+//# sourceMappingURL=component-templates.js.map

package/generators/component/generator.js

@@ -0,0 +1,144 @@
+import { formatFiles, logger, readProjectConfiguration, visitNotIgnoredFiles } from '@nx/devkit';
+import { join } from 'node:path';
+import { componentNames } from './component-names';
+import { barrelFile, componentFile, docsFile, errorsFile, headlessBarrelFile, importsFile, specFile, storiesFile, storybookComponentFile, stylesFile, TIERS, directiveFile, } from './component-templates';
+import { claimErrorCodeBlock as claimErrorCodeBlockRow, insertBarrelExport, insertDocsSidebarEntry, nextErrorCodeBlock, } from './workspace-edits';
+const DEFAULT_PROJECT = 'components';
+const DEFAULT_TIER = 'both';
+const DEFAULT_DOCS_ROOT = 'apps/docs';
+const DEFAULT_DOCS_GROUP = 'Layout & structure';
+const ARCHITECTURE_DOC = 'docs/COMPONENT-ARCHITECTURE.md';
+export default async function generate(tree, schema) {
+    logger.log('\n🧱 Scaffolding an Ethlete component domain...\n');
+    const tier = schema.tier ?? DEFAULT_TIER;
+    if (!TIERS.includes(tier)) {
+        logger.error(`❌ Unknown tier "${tier}". Use one of: ${TIERS.join(', ')}.`);
+        return;
+    }
+    let names;
+    try {
+        names = componentNames(schema.name);
+    }
+    catch (error) {
+        logger.error(`❌ ${error instanceof Error ? error.message : String(error)}`);
+        return;
+    }
+    const projectName = schema.project || DEFAULT_PROJECT;
+    let sourceRoot;
+    try {
+        const project = readProjectConfiguration(tree, projectName);
+        sourceRoot = project.sourceRoot ?? join(project.root, 'src');
+    }
+    catch {
+        logger.error(`❌ No project named "${projectName}" in this workspace. Pass --project.`);
+        return;
+    }
+    const domainDir = join(sourceRoot, 'lib', names.fileName);
+    if (tree.exists(domainDir)) {
+        logger.error(`❌ ${domainDir} already exists. Pick another name or delete it first.`);
+        return;
+    }
+    const options = { tier, errors: schema.errors ?? false };
+    const written = [];
+    const write = (path, content) => {
+        tree.write(path, content);
+        written.push(path);
+    };
+    if (tier === 'both') {
+        write(join(domainDir, 'headless', `${names.fileName}.directive.ts`), directiveFile(names));
+        write(join(domainDir, 'headless', 'index.ts'), headlessBarrelFile(names));
+    }
+    else if (tier === 'headless') {
+        write(join(domainDir, `${names.fileName}.directive.ts`), directiveFile(names));
+    }
+    if (tier !== 'headless') {
+        write(join(domainDir, `${names.fileName}.component.ts`), componentFile(names, options));
+        write(join(domainDir, `${names.fileName}.component.css`), stylesFile(names));
+    }
+    if (options.errors) {
+        const block = allocateErrorBlock(tree, sourceRoot);
+        write(join(domainDir, `${names.fileName}-errors.ts`), errorsFile(names, block));
+        const claimed = claimErrorCodeBlock(tree, names, block);
+        if (claimed)
+            written.push(claimed);
+    }
+    write(join(domainDir, `${names.fileName}.imports.ts`), importsFile(names, options));
+    write(join(domainDir, 'index.ts'), barrelFile(names, options));
+    if (schema.spec ?? true) {
+        const suffix = tier === 'headless' ? 'directive' : 'component';
+        write(join(domainDir, `${names.fileName}.${suffix}.spec.ts`), specFile(names, options));
+    }
+    if (schema.stories ?? true) {
+        write(join(domainDir, 'stories', `${names.fileName}-storybook.component.ts`), storybookComponentFile(names, options));
+        write(join(domainDir, 'stories', `${names.fileName}.stories.ts`), storiesFile(names));
+    }
+    const rootBarrel = join(sourceRoot, 'index.ts');
+    if (tree.exists(rootBarrel)) {
+        tree.write(rootBarrel, insertBarrelExport(tree.read(rootBarrel, 'utf-8') ?? '', names.fileName));
+        written.push(rootBarrel);
+    }
+    else {
+        logger.warn(`⚠️  No barrel at ${rootBarrel} - export the domain yourself.`);
+    }
+    if (schema.docs ?? true) {
+        written.push(...writeDocs(tree, names, options, schema));
+    }
+    if (!schema.skipFormat) {
+        await formatFiles(tree);
+    }
+    logger.log(`✅ ${written.length} file(s) written:\n   - ${written.join('\n   - ')}`);
+    logger.log(`\nNext:
+   - fill in the JSDoc and docs prose the scaffold left as placeholders
+   - add a changeset (.changeset/*.md, minor for @ethlete/components)
+   - nx lint ${projectName} --fix && nx test ${projectName}\n`);
+}
+/** Records the claimed block in the architecture doc, when the workspace has one. */
+function claimErrorCodeBlock(tree, names, block) {
+    if (!tree.exists(ARCHITECTURE_DOC)) {
+        return null;
+    }
+    const before = tree.read(ARCHITECTURE_DOC, 'utf-8') ?? '';
+    const after = claimErrorCodeBlockRow(before, block, names.title);
+    if (after === before) {
+        logger.warn(`⚠️  Could not update the code range table in ${ARCHITECTURE_DOC} - claim ${block} yourself.`);
+        return null;
+    }
+    tree.write(ARCHITECTURE_DOC, after);
+    return ARCHITECTURE_DOC;
+}
+/** The next unused 100-code block across every `*-errors.ts` in the lib. */
+function allocateErrorBlock(tree, sourceRoot) {
+    const contents = [];
+    visitNotIgnoredFiles(tree, join(sourceRoot, 'lib'), (path) => {
+        if (path.endsWith('-errors.ts')) {
+            contents.push(tree.read(path, 'utf-8') ?? '');
+        }
+    });
+    return nextErrorCodeBlock(contents);
+}
+function writeDocs(tree, names, options, schema) {
+    const docsRoot = schema.docsRoot || DEFAULT_DOCS_ROOT;
+    const page = join(docsRoot, 'components', `${names.fileName}.md`);
+    if (!tree.exists(join(docsRoot, 'components'))) {
+        logger.warn(`⚠️  No docs site at ${docsRoot} - skipping the guide page.`);
+        return [];
+    }
+    const written = [page];
+    tree.write(page, docsFile(names, options));
+    const config = join(docsRoot, '.vitepress', 'config.mts');
+    if (!tree.exists(config)) {
+        logger.warn(`⚠️  No ${config} - add the sidebar entry yourself.`);
+        return written;
+    }
+    const group = schema.docsGroup || DEFAULT_DOCS_GROUP;
+    const before = tree.read(config, 'utf-8') ?? '';
+    const after = insertDocsSidebarEntry(before, group, names.title, `/components/${names.fileName}`);
+    if (after === before) {
+        logger.warn(`⚠️  Could not find the "${group}" sidebar group in ${config} - add the entry yourself.`);
+        return written;
+    }
+    tree.write(config, after);
+    written.push(config);
+    return written;
+}
+//# sourceMappingURL=generator.js.map

package/generators/component/schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "et-component",
+  "title": "Ethlete Component Generator",
+  "description": "Scaffolds a component domain that follows the three-tier architecture: folder layout, headless + default split, imports barrel, styles, spec, stories, docs page and barrel/sidebar wiring.",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Domain name in kebab-case, e.g. 'stat-tile'.",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "What is the domain called (kebab-case)?"
+    },
+    "tier": {
+      "type": "string",
+      "description": "Which tiers to scaffold: 'both' is a headless directive plus the default component applying it, 'component' a presentational component only, 'headless' a behavior directive only.",
+      "enum": ["both", "component", "headless"],
+      "default": "both",
+      "x-prompt": {
+        "message": "Which tiers does the domain need?",
+        "type": "list",
+        "items": [
+          { "value": "both", "label": "Headless directive + default component" },
+          { "value": "component", "label": "Default component only" },
+          { "value": "headless", "label": "Headless directive only" }
+        ]
+      }
+    },
+    "project": {
+      "type": "string",
+      "description": "Nx project to scaffold into. The domain lands in its '<sourceRoot>/lib/<name>'.",
+      "default": "components"
+    },
+    "errors": {
+      "type": "boolean",
+      "description": "Add a '<name>-errors.ts' with the next free 100-code block.",
+      "default": false
+    },
+    "spec": {
+      "type": "boolean",
+      "description": "Add a spec file.",
+      "default": true
+    },
+    "stories": {
+      "type": "boolean",
+      "description": "Add a Storybook story and its demo component.",
+      "default": true
+    },
+    "docs": {
+      "type": "boolean",
+      "description": "Add a VitePress guide page and its sidebar entry.",
+      "default": true
+    },
+    "docsGroup": {
+      "type": "string",
+      "description": "Sidebar group the guide page is listed under.",
+      "default": "Layout & structure"
+    },
+    "docsRoot": {
+      "type": "string",
+      "description": "Path to the VitePress site (relative to workspace root).",
+      "default": "apps/docs"
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "description": "Skip formatting files after generation.",
+      "default": false
+    }
+  },
+  "required": ["name"]
+}

package/generators/component/workspace-edits.js

@@ -0,0 +1,92 @@
+const LIB_EXPORT = /^export \* from '(\.\/lib\/[^']+)';$/;
+const SIDEBAR_ENTRY = /^(\s*)\{ text: '([^']+)', link: '([^']+)' \},$/;
+const ERROR_BLOCK = /\/\/ codes \d+-(\d+)/;
+const CODE_RANGE_ROW = /^\| \d+ – \d+ \|.*\|$/;
+const NEXT_FREE_BLOCK = /next free: \*\*\d+\*\*/;
+/** Adds `export * from './lib/<domain>';` to the lib's root barrel, in alphabetical order. */
+export function insertBarrelExport(content, domain) {
+    const path = `./lib/${domain}`;
+    const line = `export * from '${path}';`;
+    const lines = content.split('\n');
+    if (lines.includes(line)) {
+        return content;
+    }
+    const exportIndexes = lines.map((l, i) => (LIB_EXPORT.test(l) ? i : -1)).filter((i) => i !== -1);
+    if (!exportIndexes.length) {
+        return content;
+    }
+    const before = exportIndexes.find((i) => (lines[i]?.match(LIB_EXPORT)?.[1] ?? '') > path);
+    const at = before ?? (exportIndexes[exportIndexes.length - 1] ?? 0) + 1;
+    lines.splice(at, 0, line);
+    return lines.join('\n');
+}
+/**
+ * Adds `{ text, link }` to the named VitePress sidebar group. An alphabetical group keeps that
+ * order - a stray pair out of place (a group naming a recipe page, say) still counts as
+ * alphabetical - while a hand-ordered group (the forms one) gets the entry appended instead.
+ */
+export function insertDocsSidebarEntry(content, group, text, link) {
+    if (content.includes(`link: '${link}' }`)) {
+        return content;
+    }
+    const lines = content.split('\n');
+    const groupIndex = lines.findIndex((l) => l.trim() === `text: '${group}',`);
+    if (groupIndex === -1) {
+        return content;
+    }
+    const itemsIndex = lines.findIndex((l, i) => i > groupIndex && l.trim() === 'items: [');
+    if (itemsIndex === -1) {
+        return content;
+    }
+    const end = lines.findIndex((l, i) => i > itemsIndex && l.trim() === '],');
+    if (end === -1) {
+        return content;
+    }
+    const entries = lines
+        .slice(itemsIndex + 1, end)
+        .map((l, i) => ({ index: itemsIndex + 1 + i, match: l.match(SIDEBAR_ENTRY) }))
+        .filter((e) => e.match !== null);
+    if (!entries.length) {
+        return content;
+    }
+    const indent = entries[0]?.match[1] ?? '';
+    const texts = entries.map((e) => e.match[2] ?? '');
+    const alphabetical = isMostlyAlphabetical(texts);
+    const at = (alphabetical ? entries.find((e) => (e.match[2] ?? '').localeCompare(text) > 0)?.index : undefined) ?? end;
+    lines.splice(at, 0, `${indent}{ text: '${text}', link: '${link}' },`);
+    return lines.join('\n');
+}
+/**
+ * Claims a block in the architecture doc's error-code table: appends the row and moves the
+ * "next free" pointer on, so the table stays append-only the way the doc requires.
+ */
+export function claimErrorCodeBlock(content, block, domain) {
+    const lines = content.split('\n');
+    const lastRow = lines.reduce((last, line, i) => (CODE_RANGE_ROW.test(line) ? i : last), -1);
+    if (lastRow === -1) {
+        return content;
+    }
+    lines.splice(lastRow + 1, 0, `| ${block} – ${block + 99} | ${domain} |`);
+    return lines.join('\n').replace(NEXT_FREE_BLOCK, `next free: **${block + 100}**`);
+}
+const MAX_OUT_OF_ORDER_RATIO = 0.2;
+function isMostlyAlphabetical(texts) {
+    const pairs = texts.length - 1;
+    if (pairs < 1) {
+        return true;
+    }
+    const outOfOrder = texts.filter((t, i) => i > 0 && (texts[i - 1] ?? '').localeCompare(t) > 0).length;
+    return outOfOrder / pairs <= MAX_OUT_OF_ORDER_RATIO;
+}
+/**
+ * The next free 100-code block, read from the `// codes <from>-<to>` header every `*-errors.ts`
+ * file carries. Domains never reuse a block, so this only ever moves forward.
+ */
+export function nextErrorCodeBlock(errorFileContents) {
+    const highest = errorFileContents.reduce((max, content) => {
+        const to = Number(content.match(ERROR_BLOCK)?.[1] ?? 0);
+        return to > max ? to : max;
+    }, 0);
+    return highest ? Math.floor(highest / 100) * 100 + 100 : 1000;
+}
+//# sourceMappingURL=workspace-edits.js.map

package/generators/generators.json

@@ -1,5 +1,10 @@
 {
   "generators": {
+    "component": {
+      "factory": "./component/generator",
+      "schema": "./component/schema.json",
+      "description": "Scaffold a component domain following the three-tier architecture (folder layout, headless + default split, styles, spec, stories, docs page, barrel wiring)"
+    },
     "migrate-query-error-labels": {
       "factory": "./migrate-query-error-labels/migration",
       "schema": "./migrate-query-error-labels/schema.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethlete/components",
-  "version": "1.0.0-next.37",
+  "version": "1.0.0-next.39",
   "license": "MIT",
   "sideEffects": false,
   "peerDependencies": {