@table-bro/mcp 0.0.0-stage → 1.2.0

package/dist/generate/generate-code.js

@@ -0,0 +1,59 @@
+import { validateSpec } from '../spec/validate-spec.js';
+import { angularTable } from './angular.js';
+import { angularClasses, fillingsErrors } from './fillings.js';
+import { setupSteps, skinFeatures } from './setup.js';
+import { vanillaTable } from './vanilla.js';
+/**
+ * Writes the code of a table from its spec for a target and a skin: a pure function, the spec and the fillings in,
+ * the files out. It checks the spec first and writes nothing for a spec with errors.
+ */
+export function generateCode(spec, options) {
+    const { target, skin } = options;
+    const report = validateSpec(spec, { skin, extensions: options.extensions, limits: options.limits });
+    if (target === 'vanilla' && skin === 'mat') {
+        report.valid = false;
+        report.errors.push({ path: '', message: 'the mat skin is for Angular', fix: 'use the target angular, or the skin bs or nv' });
+    }
+    // Fillings of another form would fail the generator: they are errors of the fillings, with their paths
+    const fillingIssues = fillingsErrors(options.fillings);
+    if (fillingIssues.length) {
+        report.valid = false;
+        report.errors.push(...fillingIssues);
+    }
+    // An import that the generator cannot place would crash it: it is an error of the fillings, with the path
+    for (const [cell, skins] of Object.entries(fillingIssues.length ? {} : options.fillings?.cells ?? {})) {
+        for (const [fillingSkin, filling] of Object.entries(skins ?? {})) {
+            (filling?.imports ?? []).forEach((item, index) => {
+                const known = (typeof item === 'string') ? Boolean(angularClasses[item]) : (typeof item?.name === 'string' && typeof item?.from === 'string');
+                if (!known) {
+                    report.valid = false;
+                    report.errors.push({
+                        path: `fillings.cells.${cell}.${fillingSkin}.imports[${index}]`,
+                        message: `${JSON.stringify(item)} is not an import that the generator can place`,
+                        fix: 'give {"name": "OrderBadge", "from": "./order-badge"} for a class of the project; the classes of Angular Material and the pipes of Angular come from the template, and a string is only the name of such a class'
+                    });
+                }
+            });
+        }
+    }
+    if (!report.valid) {
+        return { report, files: [], setup: [], todo: [] };
+    }
+    const fillings = options.fillings ?? {};
+    const extensions = options.extensions ?? [];
+    const table = (target === 'angular') ? angularTable(spec, skin, fillings, options.tagSuffix, extensions, options.simulateServer) : vanillaTable(spec, skin, fillings, options.tagSuffix, extensions);
+    // The cells of an Angular project are Angular components in every skin: they become Custom Elements with @angular/elements
+    const elements = (target === 'angular' && skin !== 'mat' && Boolean(spec.cells?.length)) ? ['@angular/elements'] : [];
+    // A module joins the setup when the spec uses one of its fields
+    const modules = extensions.filter(extension => Object.keys(extension.config ?? {}).some(field => (spec.config ?? {})[field] !== undefined));
+    // The page of an Angular server table loads the answers of its API with HttpClient; the simulated server needs none
+    const http = (target === 'angular' && spec.config?.server && (spec.api || !options.simulateServer))
+        ? [{
+                title: 'Provide HttpClient',
+                text: 'The table loads its rows from the API with HttpClient. In the providers of `app.config.ts`:',
+                code: "import {provideHttpClient} from '@angular/common/http';\n\n// providers: [..., provideHttpClient()]",
+                language: 'typescript'
+            }]
+        : [];
+    return { report, files: table.files, setup: [...setupSteps(target, skin, elements, skinFeatures(spec, skin)), ...http, ...modules.flatMap(extension => (extension.setup ?? []).map(step => ({ ...step, module: extension.package })))], todo: table.todo };
+}

package/dist/generate/names.d.ts

@@ -0,0 +1,52 @@
+import type { BroTableSpec } from '../spec/spec.js';
+/**
+ * The names of the generated code, from the type of the row and the names of the cells.
+ */
+export declare class BroNames {
+    readonly rowType: string;
+    private tagSuffix;
+    /** order or purchase-request: the part of the tags, the files and the id. */
+    readonly kebab: string;
+    /**
+     * @param rowType - the type of the row in the generated code, as Order; the names follow it
+     * @param tagSuffix - the suffix of the tags of the cells: the site defines new Custom Elements for every generation,
+     * and a tag cannot be defined twice
+     */
+    constructor(rowType: string, tagSuffix?: string);
+    static of(spec: BroTableSpec, tagSuffix?: string): BroNames;
+    /** The folder of the generated files. */
+    get folder(): string;
+    get tableId(): string;
+    /** The id of the container of the Filter Drawer of the bs and nv skins. */
+    get drawerId(): string;
+    /** OrderFilterValues: the values of the filters, as the class of their component takes OrderFilters. */
+    get filtersType(): string;
+    /** OrderFilters: the component of the filters, without the suffix Component, as ng generate names it since Angular 20. */
+    get filtersClass(): string;
+    /** The file of the filters, from the folder of the page. */
+    get filtersFile(): string;
+    /** app-order-filters: the filters are a component of the application, as the page app-order-table. */
+    get filtersSelector(): string;
+    /** OrderTable: the page, without the suffix Component, as ng generate names it since Angular 20. */
+    get pageClass(): string;
+    /** The file of the page, from its folder. */
+    get pageFile(): string;
+    get pageSelector(): string;
+    /** The service of a server table: it maps the queries of the table and the answers of the API. */
+    get serviceClass(): string;
+    /** The file of the service, from the folder of the page. */
+    get serviceFile(): string;
+    /** The request, the answer and an item of the answer of the API of a server table. */
+    get apiQueryType(): string;
+    get apiPageType(): string;
+    get apiItemType(): string;
+    /** bro-cell-order-status for the cell status of the type Order: the prefix bro-cell- belongs to the application. */
+    tag(cell: string): string;
+    /**
+     * OrderStatusCell for the cell status of the type Order: the prefix Bro belongs to the library, and the suffix Cell
+     * keeps the names of the cells apart from the page, the filters and the types of the row.
+     */
+    cellClass(cell: string): string;
+    /** The file of a cell, from the folder of the page: order-status-cell. */
+    cellFile(cell: string): string;
+}

package/dist/generate/names.js

@@ -0,0 +1,93 @@
+/**
+ * The names of the generated code, from the type of the row and the names of the cells.
+ */
+export class BroNames {
+    rowType;
+    tagSuffix;
+    /** order or purchase-request: the part of the tags, the files and the id. */
+    kebab;
+    /**
+     * @param rowType - the type of the row in the generated code, as Order; the names follow it
+     * @param tagSuffix - the suffix of the tags of the cells: the site defines new Custom Elements for every generation,
+     * and a tag cannot be defined twice
+     */
+    constructor(rowType, tagSuffix = '') {
+        this.rowType = rowType;
+        this.tagSuffix = tagSuffix;
+        this.kebab = rowType.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+    }
+    static of(spec, tagSuffix = '') {
+        return new BroNames(spec.rowType, tagSuffix);
+    }
+    /** The folder of the generated files. */
+    get folder() {
+        return `${this.kebab}-table`;
+    }
+    get tableId() {
+        return `${this.kebab}-table${this.tagSuffix ? `-${this.tagSuffix}` : ''}`;
+    }
+    /** The id of the container of the Filter Drawer of the bs and nv skins. */
+    get drawerId() {
+        return `${this.tableId}-filters`;
+    }
+    /** OrderFilterValues: the values of the filters, as the class of their component takes OrderFilters. */
+    get filtersType() {
+        return `${this.rowType}FilterValues`;
+    }
+    /** OrderFilters: the component of the filters, without the suffix Component, as ng generate names it since Angular 20. */
+    get filtersClass() {
+        return `${this.rowType}Filters`;
+    }
+    /** The file of the filters, from the folder of the page. */
+    get filtersFile() {
+        return `${this.kebab}-filters`;
+    }
+    /** app-order-filters: the filters are a component of the application, as the page app-order-table. */
+    get filtersSelector() {
+        return `app-${this.kebab}-filters`;
+    }
+    /** OrderTable: the page, without the suffix Component, as ng generate names it since Angular 20. */
+    get pageClass() {
+        return `${this.rowType}Table`;
+    }
+    /** The file of the page, from its folder. */
+    get pageFile() {
+        return `${this.kebab}-table`;
+    }
+    get pageSelector() {
+        return `app-${this.kebab}-table`;
+    }
+    /** The service of a server table: it maps the queries of the table and the answers of the API. */
+    get serviceClass() {
+        return `${this.rowType}Service`;
+    }
+    /** The file of the service, from the folder of the page. */
+    get serviceFile() {
+        return `${this.kebab}.service`;
+    }
+    /** The request, the answer and an item of the answer of the API of a server table. */
+    get apiQueryType() {
+        return `${this.rowType}ApiQuery`;
+    }
+    get apiPageType() {
+        return `${this.rowType}ApiPage`;
+    }
+    get apiItemType() {
+        return `${this.rowType}ApiItem`;
+    }
+    /** bro-cell-order-status for the cell status of the type Order: the prefix bro-cell- belongs to the application. */
+    tag(cell) {
+        return `bro-cell-${this.kebab}-${cell}${this.tagSuffix ? `-${this.tagSuffix}` : ''}`;
+    }
+    /**
+     * OrderStatusCell for the cell status of the type Order: the prefix Bro belongs to the library, and the suffix Cell
+     * keeps the names of the cells apart from the page, the filters and the types of the row.
+     */
+    cellClass(cell) {
+        return `${this.rowType}${cell.split('-').map(part => part[0].toUpperCase() + part.slice(1)).join('')}Cell`;
+    }
+    /** The file of a cell, from the folder of the page: order-status-cell. */
+    cellFile(cell) {
+        return `${this.kebab}-${cell}-cell`;
+    }
+}

package/dist/generate/rows.d.ts

@@ -0,0 +1,5 @@
+import type { BroTableSpec } from '../spec/spec.js';
+/** The file of the type of the row and of the type of its filters. */
+export declare function rowTypeCode(spec: BroTableSpec): string;
+/** The rule of the CSS variables on the element itself: a value from an ancestor does not reach it. */
+export declare function cssVarsRule(id: string, vars: [string, string][]): string;

package/dist/generate/rows.js

@@ -0,0 +1,22 @@
+import { blockComment, imports } from './code.js';
+import { BroFiltersCode } from './filters.js';
+/** The file of the type of the row and of the type of its filters. */
+export function rowTypeCode(spec) {
+    const filters = new BroFiltersCode(spec);
+    return [
+        imports({ 'type @table-bro/core': filters.filters.length ? ['BroFilters', 'BroRow'] : ['BroRow'] }),
+        '',
+        `export interface ${spec.rowType} extends BroRow {`,
+        spec.fields.map(field => [
+            ...(field.values ? [`  /** ${blockComment(field.values.join(', '))} */`] : []),
+            `  ${field.name}: ${field.type};`
+        ].join('\n')).join('\n'),
+        '}',
+        ...(filters.filters.length ? ['', filters.typeCode()] : []),
+        ''
+    ].join('\n');
+}
+/** The rule of the CSS variables on the element itself: a value from an ancestor does not reach it. */
+export function cssVarsRule(id, vars) {
+    return `#${id} {\n${vars.map(([name, value]) => `  ${name}: ${value};`).join('\n')}\n}`;
+}

package/dist/generate/scaffold.d.ts

@@ -0,0 +1,35 @@
+import type { BroSpecField, BroSpecFilter, BroSpecSkin } from '../spec/spec.js';
+import { type BroSpecReport } from '../spec/validate-spec.js';
+import { type BroCellFilling } from './fillings.js';
+import type { BroTarget } from './setup.js';
+export interface BroScaffoldRequest {
+    kind: 'cell' | 'details' | 'filters';
+    target: BroTarget;
+    skin: BroSpecSkin;
+    rowType: string;
+    /** The fields of the row: the names for a cell, the names and types for filters. */
+    fields: BroSpecField[];
+    /** A cell or details: its name in kebab-case. */
+    name?: string;
+    /** A cell or details: what it shows, in words. */
+    shows?: string;
+    /** A cell: the fields it reads. */
+    reads?: string[];
+    /** A cell: the actions it sends. */
+    actions?: string[];
+    filters?: BroSpecFilter[];
+    filling?: BroCellFilling;
+}
+export interface BroScaffold {
+    report: BroSpecReport;
+    /** The file from the folder of the page. */
+    path: string;
+    content: string;
+    /** How the page connects it: the registration and the column, or the container of the Filter Drawer. */
+    connect: string;
+}
+/**
+ * One component for an existing table: a cell, the row details or the filters of the Filter Drawer, by the recipe
+ * of the generator. The request is checked as a small spec, so the messages are the messages of validate_spec.
+ */
+export declare function scaffoldComponent(request: BroScaffoldRequest): BroScaffold;

package/dist/generate/scaffold.js

@@ -0,0 +1,62 @@
+import { validateSpec } from '../spec/validate-spec.js';
+import { cellCode } from './cells.js';
+import { literal, quote } from './code.js';
+import { fillingErrors } from './fillings.js';
+import { BroFiltersCode } from './filters.js';
+import { BroNames } from './names.js';
+/**
+ * One component for an existing table: a cell, the row details or the filters of the Filter Drawer, by the recipe
+ * of the generator. The request is checked as a small spec, so the messages are the messages of validate_spec.
+ */
+export function scaffoldComponent(request) {
+    const { kind, target, skin, rowType } = request;
+    const cell = (kind !== 'filters') ? { name: request.name ?? kind, kind: kind === 'details' ? 'details' : 'cell', shows: request.shows ?? '', fields: request.reads ?? [], actions: request.actions } : undefined;
+    const spec = {
+        specVersion: 1,
+        rowType,
+        fields: request.fields,
+        cols: (kind === 'cell') ? [{ title: '', component: { cell: cell.name } }] : [{ title: '', name: request.fields[0]?.name }],
+        cells: cell ? [cell] : undefined,
+        filters: (kind === 'filters') ? request.filters : undefined,
+        config: (kind === 'details') ? { rowDetailsComponent: { cell: cell.name } } : undefined
+    };
+    const report = validateSpec(spec, { skin });
+    if (target === 'vanilla' && skin === 'mat') {
+        report.valid = false;
+        report.errors.push({ path: '', message: 'the mat skin is for Angular', fix: 'use the target angular, or the skin bs or nv' });
+    }
+    if (kind === 'filters' && !request.filters?.length) {
+        report.valid = false;
+        report.errors.push({ path: 'filters', message: 'the filters of the drawer need at least one filter', fix: 'give the filters as the filters of a spec, get_docs topic filters' });
+    }
+    if (kind !== 'filters' && request.filling !== undefined) {
+        const fillingIssues = fillingErrors(request.filling, 'filling');
+        report.valid &&= !fillingIssues.length;
+        report.errors.push(...fillingIssues);
+    }
+    if (!report.valid) {
+        return { report, path: '', content: '', connect: '' };
+    }
+    if (kind === 'filters') {
+        const filters = new BroFiltersCode(spec);
+        return {
+            report,
+            path: `${BroNames.of(spec).filtersFile}.ts`,
+            content: (target === 'angular') ? filters.angularComponent(skin) : filters.vanillaForm(skin),
+            connect: [
+                `The type of the filters, next to the type ${rowType}:\n\n\`\`\`ts\n${filters.typeCode()}\n\`\`\``,
+                `filtersTransform of the local mode, in the config:\n\n\`\`\`ts\nfiltersTransform: ${filters.transformCode()}\n\`\`\``,
+                'The container of the Filter Drawer around the table: see get_docs with the topic filters.'
+            ].join('\n\n')
+        };
+    }
+    const code = cellCode(spec, cell, target, request.filling);
+    const define = code.angular ? `customElements.define(${quote(code.tag)}, createCustomElement(${code.className}, {injector: this.injector}));` : `customElements.define(${quote(code.tag)}, ${code.className});`;
+    const use = (kind === 'details') ? `In the config: rowDetailsComponent: ${quote(code.tag)}` : `The column:\n\n\`\`\`ts\n${literal({ title: '', component: { selector: code.tag, event: cell.actions?.length ? 'action' : undefined } })}\n\`\`\``;
+    return {
+        report,
+        path: `${code.file}.ts`,
+        content: code.content,
+        connect: [`The registration, once before the table is created, with a customElements.get guard:\n\n\`\`\`ts\n${define}\n\`\`\``, use].join('\n\n')
+    };
+}

package/dist/generate/service.d.ts

@@ -0,0 +1,16 @@
+import type { BroTableSpec } from '../spec/spec.js';
+import type { BroFiltersCode } from './filters.js';
+/**
+ * Where a server table takes its rows: the API of the project, the simulated server of the site, or the API of the spec
+ * that gives its rows page by page or all at once.
+ */
+export type BroServerSource = 'project' | 'simulated' | 'api-pages' | 'api';
+/**
+ * The service of a server table, as BroService of @table-bro/angular: loadPage sends the request of a query of the table
+ * and gives the rows of its page with the number of all rows; mapServerQuery turns the query into the request of the API,
+ * and mapServerResponse the answer of the API into the rows. The page only delivers the rows to the table. The simulated
+ * server of the site is a REST API with names of its own, so its service maps as the service of a real API does.
+ */
+export declare function serviceCode(spec: BroTableSpec, source: BroServerSource, filtersCode?: BroFiltersCode): string;
+/** The fields of a row whose values come from other names of the API: the API sorts by its own names. */
+export declare function renamedSources(spec: BroTableSpec): [string, string][];