@table-bro/mcp 0.0.0-stage → 1.2.0

package/dist/server/server.js

@@ -0,0 +1,212 @@
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import * as z from 'zod/v4';
+import { allTopics, getDocs, getStarted, serverInstructions } from '../docs/docs.js';
+import { generateCode } from '../generate/generate-code.js';
+import { scaffoldComponent } from '../generate/scaffold.js';
+import { setupText } from '../generate/setup.js';
+import { findExtensions, inspectProject } from '../project/inspect-project.js';
+import { builtinSpecs } from '../spec/builtin-specs.js';
+import { cellFillingSchema, fillingsSchema, filterSchema, specSchema } from '../spec/schema.js';
+import { rowDetailsByDefault, validateSpec } from '../spec/validate-spec.js';
+import { tableBroVersion } from '../version.js';
+const skin = z.enum(['mat', 'bs', 'nv']).describe('The skin, the UI library the table works on top of: mat (Angular Material), bs (Bootstrap 5) or nv (native HTML, no library)');
+const target = z.enum(['angular', 'vanilla']).describe('The target: angular for an Angular project, through the wrapper <table-bro-ng>; vanilla for a page without a framework, the Custom Element <table-bro> itself');
+/**
+ * A value that the tool checks itself, shown to the agent with its JSON Schema: the check of the tool names every
+ * error with its path and its fix, as did you mean, which a check of the arguments by the schema would not.
+ */
+function shown(schema) {
+    // The dialect of the schema stays out: the list of the tools gives its own
+    return z.any().meta(Object.fromEntries(Object.entries(schema).filter(([key]) => key !== '$schema')));
+}
+const issue = z.object({ path: z.string(), message: z.string(), fix: z.string().optional() });
+const report = { valid: z.boolean(), errors: z.array(issue), warnings: z.array(issue), omitted: z.object({ errors: z.number().optional(), warnings: z.number().optional() }).optional() };
+/** The sizes of a spec that the server takes: the answers of a larger one would fill the context of the agent. */
+const limits = { cols: 200, rows: 1000, cells: 100, filters: 100, valueLength: 2000 };
+const profile = {
+    folder: z.string(),
+    tableBro: z.object({ version: z.string().nullable(), packages: z.record(z.string(), z.string()), extensions: z.array(z.string()) }),
+    framework: z.object({ name: z.enum(['angular', 'none']), version: z.string().nullable() }),
+    ui: z.object({ material: z.string().nullable(), bootstrap: z.string().nullable() }),
+    skins: z.object({ registered: z.array(z.enum(['mat', 'bs', 'nv'])), where: z.array(z.string()) }),
+    styles: z.array(z.string()),
+    customElements: z.array(z.object({ tag: z.string(), file: z.string() })),
+    tables: z.array(z.string()),
+    problems: z.array(z.object({ code: z.string(), message: z.string(), fix: z.string() })),
+    omitted: z.record(z.string(), z.number()).optional()
+};
+/** Every tool only reads, and the same call gives the same answer: the agent writes the files. */
+const readOnly = { readOnlyHint: true, idempotentHint: true, openWorldHint: false };
+/**
+ * The first folder of the workspace of the client, when the client gives its roots: a client may start the server
+ * outside the project, as a desktop application does.
+ */
+async function clientRoot(server) {
+    if (!server.server.getClientCapabilities()?.roots) {
+        return undefined;
+    }
+    try {
+        const { roots } = await server.server.listRoots();
+        const folder = roots.find(item => item.uri.startsWith('file:'));
+        return folder ? fileURLToPath(folder.uri) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The paid modules that the arguments of the server name: --extension <package>, once for each module. */
+export function enabledExtensions(args) {
+    return args.flatMap((arg, index) => {
+        if (arg === '--extension') {
+            return args[index + 1] ? [args[index + 1]] : [];
+        }
+        return arg.startsWith('--extension=') ? [arg.slice('--extension='.length)] : [];
+    });
+}
+/**
+ * Loads the parts of the server of the installed paid modules that the server is started with, from the scope
+ * @table-bro-extended only: the server runs no code of a package that nobody named. A module that fails to load, or has
+ * no part of the server, is left out with a message on stderr, and the server works without it.
+ * @param root - the folder of the project
+ * @param enabled - the packages of the modules that the arguments of the server name
+ */
+export async function loadExtensions(root, enabled) {
+    const extensions = [];
+    const installed = findExtensions(root);
+    for (const name of enabled) {
+        const found = installed.find(extension => extension.name === name);
+        if (!found) {
+            console.error(`[@table-bro/mcp] ${name} is not loaded: no package of the scope @table-bro-extended with a part of the MCP server has this name in ${root}`);
+            continue;
+        }
+        try {
+            const extension = (await import(pathToFileURL(found.entry).href)).default;
+            if (typeof extension?.package !== 'string') {
+                throw new Error('its file has no part of the MCP server as its default export');
+            }
+            extensions.push(extension);
+        }
+        catch (error) {
+            console.error(`[@table-bro/mcp] ${name} is not loaded: ${error.message}`);
+        }
+    }
+    return extensions;
+}
+/**
+ * The MCP server of Table, Bro: six tools over the pure functions of the package. It reads the project and writes
+ * nothing: the agent writes the files and shows the changes to the developer.
+ */
+export function createServer(root, extensions = []) {
+    const server = new McpServer({ name: 'table-bro', version: tableBroVersion }, { instructions: serverInstructions });
+    server.registerTool('get_started', {
+        title: 'Get started with Table, Bro',
+        description: 'Call this first, once per session. It explains how Table, Bro works, a Web Components table engine on top of the UI library of your project, and which tool to use when; '
+            + 'shows a minimal table for your target and skin; lists the topics of get_docs. Do not call it again in the same session: use get_docs. Example: {"target": "angular", "skin": "mat"}',
+        inputSchema: { target: target.optional(), skin: skin.optional() },
+        annotations: readOnly
+    }, ({ target, skin }) => text(getStarted({ target, skin }, extensions)));
+    server.registerTool('get_docs', {
+        title: 'The reference of Table, Bro',
+        description: 'Returns one topic of the reference or one page of Docs with its code by its name, the two topics that match a query best, or all topics with their summaries. '
+            + 'Use it for questions about the API and for changes of an existing table; get_started already gives the topics basics and workflow. '
+            + 'Example: {"topic": "server-mode"} or {"query": "row height"}',
+        inputSchema: {
+            topic: z.enum(allTopics(extensions).map(topic => topic.name)).optional(),
+            query: z.string().optional().describe('The words to search the topics for, as row height; without topic')
+        },
+        annotations: readOnly
+    }, ({ topic, query }) => text(getDocs({ topic, query }, extensions)));
+    server.registerTool('inspect_project', {
+        title: 'Inspect the project',
+        description: 'Profiles the project: the packages of Table, Bro and their version, the framework, the registered skins, the CSS, the custom elements, the tables, '
+            + 'and the problems of the setup with their fixes. Call it once before you add code to a project, and when a table does not render. '
+            + 'Pass skins.registered as the skin and framework.name as the target of the other tools. Not for questions about the API. '
+            + 'Each list keeps its first 20 items; omitted counts the rest. It reads the project as text and writes nothing. Example: {}',
+        inputSchema: { path: z.string().optional().describe('The root of the project. Without it, the first root of the workspace that the client gives, else the folder where the server was started') },
+        outputSchema: profile,
+        annotations: readOnly
+    }, async ({ path }) => structured(inspectProject(path ?? await clientRoot(server) ?? root)));
+    server.registerTool('validate_spec', {
+        title: 'Check a table spec',
+        description: 'Checks a table spec, a BroTableSpec (get_docs, topic spec), and reports every error and warning with its path, what is wrong and the fix. '
+            + 'Use it while you draft a spec. generate_code runs the same check first and returns the same report for a spec with errors. '
+            + 'Example: {"spec": {"specVersion": 1, "rowType": "Product", "fields": [{"name": "title", "type": "string"}], "cols": [{"title": "Product", "name": "title"}]}, "skin": "mat"}',
+        inputSchema: { spec: shown(specSchema), skin: skin.optional().describe('The skin of the project: mat, bs or nv. Without it the spec is checked against all three') },
+        outputSchema: report,
+        annotations: readOnly
+    }, ({ spec, skin }) => {
+        const result = validateSpec(spec, { skin, extensions, limits });
+        // Every table has row details by default: a warning, as the request may ask for a table without them
+        result.warnings.push(...rowDetailsByDefault(spec));
+        return structured(result);
+    });
+    server.registerTool('generate_code', {
+        title: 'Generate the code of a table',
+        description: 'Generates the code of a new table from a spec or from a built-in spec: the files, the setup of the project, once per project, and what is left to finish by hand. '
+            + 'The fillings are the templates of the cells, the rules of the custom filters and the bodies of the functions of the skin config (get_docs, topic fillings); '
+            + 'without them the files keep TODOs. A spec with errors returns the report of validate_spec and no files. '
+            + 'For one cell, the row details or the filters of an existing table use scaffold_component. '
+            + 'Example: {"builtinSpec": "products", "target": "angular", "skin": "mat"}',
+        inputSchema: {
+            // The list of the tools goes into the context of the agent in every session: the schema of a spec stays in validate_spec
+            spec: z.any().optional().describe('A BroTableSpec, as the JSON Schema of the spec of validate_spec describes it'),
+            builtinSpec: z.enum(builtinSpecs.map(builtin => builtin.name)).optional().describe(`The name of a built-in spec instead of a spec: ${builtinSpecs.map(builtin => `${builtin.name}, ${builtin.description}`).join('; ')}`),
+            fillings: shown(fillingsSchema).optional(),
+            target,
+            skin
+        },
+        annotations: readOnly
+    }, ({ spec, builtinSpec, fillings, target, skin }) => {
+        const builtin = builtinSpecs.find(item => item.name === builtinSpec);
+        if (!spec && !builtin) {
+            return { ...text('Give a spec or the name of a built-in spec.'), isError: true };
+        }
+        const result = generateCode((spec ?? builtin.spec), { target, skin, fillings: fillings ?? builtin?.fillings, extensions, limits });
+        if (!result.report.valid) {
+            return { ...text(`The spec has errors:\n\n${JSON.stringify(result.report, null, 2)}`), isError: true };
+        }
+        result.report.warnings.push(...rowDetailsByDefault(spec ?? builtin.spec));
+        return text([
+            ...result.files.map(file => `## ${file.path}\n\n${file.description ? `${file.description[0].toUpperCase()}${file.description.slice(1)}\n\n` : ''}\`\`\`${file.path.endsWith('.css') ? 'css' : 'ts'}\n${file.content}\`\`\``),
+            `## Setup, once per project\n\n${setupText(result.setup)}`,
+            ...(result.todo.length ? [`## To finish\n\n${result.todo.map(item => `- ${item}`).join('\n')}`] : []),
+            ...(result.report.warnings.length ? [`## Warnings\n\n${result.report.warnings.map(item => `- ${item.path}: ${item.message}${item.fix ? `; ${item.fix}` : ''}`).join('\n')}`] : [])
+        ].join('\n\n'));
+    });
+    server.registerTool('scaffold_component', {
+        title: 'Scaffold a component of a table',
+        description: 'Scaffolds one component for an existing table: a custom cell, the element of the row details, or the filters of the Filter Drawer, and tells how to connect it to the page: '
+            + 'the registration of the element and its column, or the container of the drawer. '
+            + 'For a new table use generate_code, which writes its cells too. '
+            + 'Example: {"kind": "cell", "target": "angular", "skin": "mat", "rowType": "Order", "fields": [{"name": "status", "type": "string"}], "name": "status", "shows": "the status as a chip", "reads": ["status"]}',
+        inputSchema: {
+            kind: z.enum(['cell', 'details', 'filters']).describe('What to scaffold: cell, a custom cell of a column; details, the element of the row details; filters, the filters of the Filter Drawer'),
+            target,
+            skin,
+            rowType: z.string().describe('The name of the type of a row in PascalCase, as Order'),
+            fields: z.array(z.object({ name: z.string(), type: z.enum(['string', 'number', 'boolean', 'string[]']), values: z.array(z.string()).optional() })).describe('The fields of the row: name, type (string, number, boolean or string[]) and, for a string field, its values'),
+            name: z.string().optional().describe('For a cell or the details: its name in kebab-case, as status; the tag of the element is bro-cell-<row-type>-<name>'),
+            shows: z.string().optional().describe('For a cell or the details: what it shows, in words, as the status as a chip'),
+            reads: z.array(z.string()).optional().describe('For a cell or the details: the names of the fields of the row that it reads'),
+            actions: z.array(z.string()).optional().describe('For a cell: the actions that it sends in its output action, as edit; the table gives them to the page as bro-action with the column and the row'),
+            filters: shown({ type: 'array', description: 'For filters: the filters of the Filter Drawer, in the form of filters of a spec; get_docs, topic filters', items: filterSchema }).optional(),
+            filling: shown({ ...cellFillingSchema, description: 'For a cell or the details, the code that you write: {imports, template, styles, members} for an Angular project, {render, members} for Vanilla JS; get_docs, topic fillings' }).optional()
+        },
+        annotations: readOnly
+    }, request => {
+        const scaffold = scaffoldComponent(request);
+        if (!scaffold.report.valid) {
+            return { ...text(`The request has errors:\n\n${JSON.stringify(scaffold.report, null, 2)}`), isError: true };
+        }
+        return text(`## ${scaffold.path}\n\n\`\`\`ts\n${scaffold.content}\`\`\`\n\n${scaffold.connect}`);
+    });
+    return server;
+}
+function text(value) {
+    return { content: [{ type: 'text', text: value }] };
+}
+/** A result of the form of the output schema of its tool, also as JSON text for a client without structured content. */
+function structured(value) {
+    return { ...text(JSON.stringify(value, null, 2)), structuredContent: value };
+}

package/dist/spec/builtin-specs.d.ts

@@ -0,0 +1,13 @@
+import type { BroSpecFillings } from '../generate/fillings.js';
+import type { BroTableSpec } from './spec.js';
+export interface BroBuiltinSpec {
+    name: string;
+    description: string;
+    spec: BroTableSpec;
+    fillings: BroSpecFillings;
+}
+/**
+ * The built-in specs of the reference: generate_code gives the code of a built-in spec by its name, and the check
+ * of the generator runs every built-in spec through every pair of a target and a skin.
+ */
+export declare const builtinSpecs: BroBuiltinSpec[];

package/dist/spec/builtin-specs.js

@@ -0,0 +1,167 @@
+/**
+ * The built-in specs of the reference: generate_code gives the code of a built-in spec by its name, and the check
+ * of the generator runs every built-in spec through every pair of a target and a skin.
+ */
+export const builtinSpecs = [
+    {
+        name: 'orders',
+        description: 'Orders with custom cells and their actions, row details, filters in the Filter Drawer, buttons of the toolbar, a message of a state and a taller row',
+        spec: {
+            specVersion: 1,
+            rowType: 'Order',
+            fields: [
+                { name: 'number', type: 'string' },
+                { name: 'customer', type: 'string' },
+                { name: 'total', type: 'number' },
+                { name: 'status', type: 'string', values: ['paid', 'pending', 'refunded'] },
+                { name: 'tags', type: 'string[]' },
+                { name: 'urgent', type: 'boolean' }
+            ],
+            cols: [
+                { title: 'Order', name: 'number' },
+                { title: 'Customer', name: 'customer', component: { cell: 'customer' } },
+                { title: 'Total amount', shortTitle: 'Total', name: 'total' },
+                { title: 'Status', name: 'status', component: { cell: 'status' } },
+                { title: 'Tags', name: 'tags', component: { element: 'tags' } },
+                { title: 'Urgent', name: 'urgent', component: { element: 'switch' } },
+                { title: '', component: { cell: 'actions' } },
+                { title: '', component: { element: 'details-button' } }
+            ],
+            cells: [
+                { name: 'customer', shows: 'the customer and the order number below it in a smaller font', fields: ['customer', 'number'] },
+                { name: 'status', shows: 'the status as a badge of the library of the skin, paid stands out', fields: ['status'] },
+                { name: 'actions', shows: 'Edit and Delete icon buttons', fields: ['number'], actions: ['edit', 'delete'] },
+                { name: 'details', kind: 'details', shows: 'the customer, the total and the tags of the order', fields: ['customer', 'total', 'tags'] }
+            ],
+            filters: [
+                { name: 'customer', label: 'Customer', control: 'text', field: 'customer' },
+                { name: 'status', label: 'Status', control: 'select', field: 'status' },
+                { name: 'total', label: 'Total', control: 'range', field: 'total' },
+                { name: 'urgent', label: 'Urgent only', control: 'checkbox', field: 'urgent' },
+                { name: 'big', label: 'Big orders', control: 'checkbox', match: 'custom', rule: 'the total is over 1000' }
+            ],
+            rows: [
+                { number: 'A-1042', customer: 'Ada Lovelace', total: 1200, status: 'paid', tags: ['new', 'priority'], urgent: true },
+                { number: 'A-1043', customer: 'Alan Turing', total: 310, status: 'pending', tags: ['new'], urgent: false },
+                { number: 'A-1044', customer: 'Grace Hopper', total: 75, status: 'paid', tags: [], urgent: false },
+                { number: 'A-1045', customer: 'Edsger Dijkstra', total: 990, status: 'refunded', tags: ['return'], urgent: true },
+                { number: 'A-1046', customer: 'Barbara Liskov', total: 1450, status: 'pending', tags: ['priority'], urgent: false }
+            ],
+            config: { toolbarTitle: 'Orders', pageSize: 10, rowDetailsComponent: { cell: 'details' } },
+            toolbar: {
+                buttons: [{ title: 'Export', action: 'export', icon: 'download' }],
+                menu: { title: 'More', items: [{ title: 'Archive', action: 'archive' }] }
+            },
+            stateMessages: { 'no-data': 'No orders yet', 'not-found': 'No orders match the filters' },
+            cssVars: { '--bro-row-height': '56px' }
+        },
+        fillings: {
+            cells: {
+                customer: {
+                    mat: {
+                        template: '<span class="customer">{{ row.customer }}</span>\n<small class="number">{{ row.number }}</small>',
+                        styles: ':host {\n  display: flex;\n  flex-direction: column;\n  line-height: 1.2;\n}\n\n.number {\n  font-size: 12px;\n  opacity: .7;\n}'
+                    },
+                    bs: {
+                        template: '<span>{{ row.customer }}</span>\n<small class="text-body-secondary">{{ row.number }}</small>',
+                        styles: ':host {\n  display: flex;\n  flex-direction: column;\n  line-height: 1.2;\n}',
+                        render: "const customer = document.createElement('div');\nconst number = document.createElement('small');\n\ncustomer.textContent = this.row?.customer ?? '';\nnumber.className = 'text-body-secondary';\nnumber.textContent = this.row?.number ?? '';\n\nthis.style.lineHeight = '1.2';\nthis.append(customer, number);"
+                    },
+                    nv: {
+                        template: '<span>{{ row.customer }}</span>\n<small class="number">{{ row.number }}</small>',
+                        styles: ':host {\n  display: flex;\n  flex-direction: column;\n  line-height: 1.2;\n}\n\n.number {\n  opacity: .7;\n}',
+                        render: "const customer = document.createElement('div');\nconst number = document.createElement('small');\n\ncustomer.textContent = this.row?.customer ?? '';\nnumber.style.opacity = '.7';\nnumber.textContent = this.row?.number ?? '';\n\nthis.style.lineHeight = '1.2';\nthis.append(customer, number);"
+                    }
+                },
+                status: {
+                    mat: {
+                        template: '<mat-chip-set>\n  <mat-chip [highlighted]="row.status === \'paid\'">{{ row.status }}</mat-chip>\n</mat-chip-set>'
+                    },
+                    bs: {
+                        template: '<span class="badge" [class]="colors[row.status] ?? \'text-bg-light\'">{{ row.status }}</span>',
+                        members: "colors: Record<string, string> = {paid: 'text-bg-success', pending: 'text-bg-warning', refunded: 'text-bg-secondary'};",
+                        render: "const badge = document.createElement('span');\nconst colors: Record<string, string> = {paid: 'text-bg-success', pending: 'text-bg-warning', refunded: 'text-bg-secondary'};\n\nbadge.className = `badge ${colors[this.row?.status ?? ''] ?? 'text-bg-light'}`;\nbadge.textContent = this.row?.status ?? '';\n\nthis.append(badge);"
+                    },
+                    nv: {
+                        template: '<span class="status" [class.status_paid]="row.status === \'paid\'">{{ row.status }}</span>',
+                        styles: '.status {\n  padding: 0 6px;\n  border: 1px solid GrayText;\n  border-radius: 4px;\n}\n\n.status_paid {\n  border-color: CanvasText;\n}',
+                        render: "const badge = document.createElement('span');\n\nbadge.style.padding = '0 6px';\nbadge.style.border = `1px solid ${(this.row?.status === 'paid') ? 'CanvasText' : 'GrayText'}`;\nbadge.style.borderRadius = '4px';\nbadge.textContent = this.row?.status ?? '';\n\nthis.append(badge);"
+                    }
+                },
+                actions: {
+                    mat: {
+                        template: '<button matIconButton aria-label="Edit" matTooltip="Edit" matTooltipPosition="above" (click)="action.emit(\'edit\')">\n  <mat-icon>edit</mat-icon>\n</button>\n<button matIconButton aria-label="Delete" matTooltip="Delete" matTooltipPosition="above" (click)="action.emit(\'delete\')">\n  <mat-icon>delete</mat-icon>\n</button>',
+                        styles: ':host {\n  --mat-icon-button-icon-color: var(--mat-sys-primary);\n}'
+                    },
+                    bs: {
+                        template: '<button type="button" class="btn btn-link" (click)="action.emit(\'edit\')">Edit</button>\n<button type="button" class="btn btn-link" (click)="action.emit(\'delete\')">Delete</button>',
+                        render: "for (const [action, title] of [['edit', 'Edit'], ['delete', 'Delete']]) {\n  const button = document.createElement('button');\n\n  button.type = 'button';\n  button.className = 'btn btn-link';\n  button.textContent = title;\n  button.addEventListener('click', () => this.sendAction(action));\n\n  this.append(button);\n}"
+                    },
+                    nv: {
+                        template: '<a href="" role="button" (click)="$event.preventDefault(); action.emit(\'edit\')">Edit</a>\n<a href="" role="button" (click)="$event.preventDefault(); action.emit(\'delete\')">Delete</a>',
+                        styles: ':host {\n  display: flex;\n  gap: 16px;\n}\n\na {\n  color: LinkText;\n}',
+                        render: "for (const [action, title] of [['edit', 'Edit'], ['delete', 'Delete']]) {\n  const link = document.createElement('a');\n\n  link.href = '';\n  link.setAttribute('role', 'button');\n  link.style.color = 'LinkText';\n  link.textContent = title;\n  link.addEventListener('click', event => {\n    event.preventDefault();\n    this.sendAction(action);\n  });\n\n  this.append(link);\n}"
+                    }
+                },
+                details: {
+                    mat: {
+                        template: '<dl>\n  <dt>Customer</dt>\n  <dd>{{ row.customer }}</dd>\n  <dt>Total</dt>\n  <dd>{{ row.total }}</dd>\n  <dt>Tags</dt>\n  <dd>\n    <mat-chip-set>\n      @for (tag of row.tags; track tag) {\n        <mat-chip>{{ tag }}</mat-chip>\n      }\n    </mat-chip-set>\n  </dd>\n</dl>',
+                        styles: ':host {\n  display: block;\n}\n\ndl {\n  padding: 16px 24px;\n  display: grid;\n  grid-template-columns: max-content 1fr;\n  align-items: center;\n  gap: 8px 24px;\n  margin: 0;\n}\n\ndt {\n  color: var(--mat-sys-on-surface-variant);\n}\n\ndd {\n  margin: 0;\n}'
+                    },
+                    bs: {
+                        template: '<dl>\n  <dt>Customer</dt>\n  <dd>{{ row.customer }}</dd>\n  <dt>Total</dt>\n  <dd>{{ row.total }}</dd>\n  <dt>Tags</dt>\n  <dd>\n    @for (tag of row.tags; track tag) {\n      <span class="badge text-bg-secondary me-1">{{ tag }}</span>\n    }\n  </dd>\n</dl>',
+                        styles: ':host {\n  display: block;\n}\n\ndl {\n  padding: 12px 16px;\n  display: grid;\n  grid-template-columns: max-content 1fr;\n  gap: 8px 24px;\n  margin: 0;\n}\n\ndt {\n  font-weight: normal;\n  color: var(--bs-secondary-color);\n}\n\ndd {\n  margin: 0;\n}',
+                        render: "this.style.display = 'block';\n\nconst list = document.createElement('dl');\n\nlist.style.cssText = 'display: grid; grid-template-columns: max-content 1fr; gap: 8px 24px; margin: 0; padding: 12px 16px;';\n\nfor (const [label, value] of [['Customer', this.row?.customer], ['Total', this.row?.total], ['Tags', this.row?.tags.join(', ')]] as [string, unknown][]) {\n  const term = document.createElement('dt');\n  const detail = document.createElement('dd');\n\n  term.style.cssText = 'font-weight: normal; color: var(--bs-secondary-color);';\n  term.textContent = label;\n  detail.style.margin = '0';\n  detail.textContent = String(value ?? '');\n  list.append(term, detail);\n}\n\nthis.append(list);"
+                    },
+                    nv: {
+                        template: '<dl>\n  <dt>Customer</dt>\n  <dd>{{ row.customer }}</dd>\n  <dt>Total</dt>\n  <dd>{{ row.total }}</dd>\n  <dt>Tags</dt>\n  <dd>{{ row.tags.join(\', \') }}</dd>\n</dl>',
+                        styles: ':host {\n  display: block;\n}\n\ndl {\n  padding: 12px 16px;\n  display: grid;\n  grid-template-columns: max-content 1fr;\n  gap: 8px 24px;\n  margin: 0;\n}\n\ndt {\n  color: GrayText;\n}\n\ndd {\n  margin: 0;\n}',
+                        render: "this.style.display = 'block';\n\nconst list = document.createElement('dl');\n\nlist.style.cssText = 'display: grid; grid-template-columns: max-content 1fr; gap: 8px 24px; margin: 0; padding: 12px 16px;';\n\nfor (const [label, value] of [['Customer', this.row?.customer], ['Total', this.row?.total], ['Tags', this.row?.tags.join(', ')]] as [string, unknown][]) {\n  const term = document.createElement('dt');\n  const detail = document.createElement('dd');\n\n  term.style.color = 'GrayText';\n  term.textContent = label;\n  detail.style.margin = '0';\n  detail.textContent = String(value ?? '');\n  list.append(term, detail);\n}\n\nthis.append(list);"
+                    }
+                }
+            },
+            filterRules: {
+                big: 'return row.total > 1000;'
+            }
+        }
+    },
+    {
+        name: 'users-server',
+        description: 'Users loaded from the server page by page, with a search of the toolbar and the sort of the columns',
+        spec: {
+            specVersion: 1,
+            rowType: 'User',
+            fields: [
+                { name: 'name', type: 'string' },
+                { name: 'email', type: 'string' },
+                { name: 'role', type: 'string', values: ['admin', 'editor', 'viewer'] },
+                { name: 'active', type: 'boolean' }
+            ],
+            cols: [
+                { title: 'Name', name: 'name' },
+                { title: 'Email', name: 'email' },
+                { title: 'Role', name: 'role' },
+                { title: 'Active', name: 'active', component: { element: 'switch' } }
+            ],
+            config: { toolbarTitle: 'Users', pageSize: 20, server: true }
+        },
+        fillings: {}
+    },
+    {
+        name: 'products',
+        description: 'The smallest table: columns of the fields of a row, the rows loaded by the page',
+        spec: {
+            specVersion: 1,
+            rowType: 'Product',
+            fields: [
+                { name: 'title', type: 'string' },
+                { name: 'price', type: 'number' }
+            ],
+            cols: [
+                { title: 'Product', name: 'title' },
+                { title: 'Price', name: 'price' }
+            ]
+        },
+        fillings: {}
+    }
+];

package/dist/spec/css-variables.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The CSS custom properties a spec may set: the sizes and the timings that a skin declares on the host and the core
+ * registers with @property (packages/core/styles/_custom-properties.scss). A value set on the element changes
+ * the CSS and the script of the table together, without a new build of the skin.
+ */
+export interface BroCssVariable {
+    name: string;
+    kind: 'length' | 'time' | 'number' | 'integer' | 'easing';
+    /**
+     * The element that reads it: the table, the container of the Filter Drawer, or both. A value from an ancestor does
+     * not reach them, so the generator sets it on the element itself.
+     */
+    target: 'table' | 'drawer' | 'both';
+    min?: number;
+    max?: number;
+    description: string;
+}
+export declare const cssVariables: BroCssVariable[];
+/** The registered properties a spec may not set, with the reason. */
+export declare const excludedCssVariables: Record<string, string>;
+/** The problem of a value for its variable, or undefined for a good value. */
+export declare function checkCssValue(variable: BroCssVariable, value: string): string | undefined;

package/dist/spec/css-variables.js

@@ -0,0 +1,54 @@
+export const cssVariables = [
+    { name: '--bro-row-height', kind: 'length', target: 'table', description: 'the height of a body row' },
+    { name: '--bro-header-height', kind: 'length', target: 'table', description: 'the height of the header' },
+    { name: '--bro-shadow-size', kind: 'length', target: 'both', description: 'the size of the shadow of the table and the room the Filter Drawer leaves for it' },
+    { name: '--bro-corner-radius', kind: 'length', target: 'both', description: 'the radius of the corners of the table; 0 keeps them square' },
+    { name: '--bro-island-space-size', kind: 'length', target: 'both', description: 'the space between the table and the Filter Drawer' },
+    { name: '--bro-table-min-width', kind: 'length', target: 'table', description: 'the narrowest table, as wide as its paginator in one line; the Filter Drawer lies over a table that would be narrower next to it' },
+    { name: '--bro-filter-drawer-width', kind: 'length', target: 'drawer', description: 'the width of the Filter Drawer' },
+    { name: '--bro-filter-drawer-corner-radius', kind: 'length', target: 'drawer', description: 'the radius of the corners of the Filter Drawer; 0 keeps them square' },
+    { name: '--bro-filter-drawer-duration', kind: 'time', target: 'both', description: 'the duration of the motion of the Filter Drawer and of the columns with it' },
+    { name: '--bro-column-width-duration', kind: 'time', target: 'table', description: 'the duration of the motion of the columns to their new widths' },
+    { name: '--bro-details-duration', kind: 'time', target: 'table', description: 'the duration of opening the row details' },
+    { name: '--bro-details-easing', kind: 'easing', target: 'table', description: 'the curve of the eased row details, with config.rowDetailsMotion: eased, and of the turn of their button' },
+    { name: '--bro-kinetic-time-constant', kind: 'time', target: 'table', description: 'the time constant of the kinetic scroll' },
+    { name: '--bro-state-icon-duration', kind: 'time', target: 'table', description: 'the duration of the animation of the state icon' },
+    { name: '--bro-state-message-duration', kind: 'time', target: 'table', description: 'the duration of the animation of the state message' },
+    { name: '--bro-refresh-overlay-opacity', kind: 'number', target: 'table', min: 0, max: 1, description: 'how much the cells of the body fade during a refresh, in the light theme' },
+    { name: '--bro-refresh-overlay-opacity-dark', kind: 'number', target: 'table', min: 0, max: 1, description: 'how much the cells of the body fade during a refresh, in the dark theme' },
+    { name: '--bro-table-body-container-z-index', kind: 'integer', target: 'table', description: 'the layer of the body of the table' }
+];
+/** The registered properties a spec may not set, with the reason. */
+export const excludedCssVariables = {
+    '--bro-duration-scale': 'the skin sets it to 0 under prefers-reduced-motion; a value on the table would cancel this setting of the user',
+    '--bro-filter-drawer-opened': 'it is the state of the Filter Drawer, not a setting: its CSS moves it from 0 to 1 on opening, and a value would stop the drawer'
+};
+const units = {
+    length: /^(\d+|\d*\.\d+)(px|rem|em)$|^0$/,
+    time: /^(\d+|\d*\.\d+)(ms|s)$/,
+    number: /^(\d+|\d*\.\d+)$/,
+    integer: /^-?\d+$/,
+    // The x of the two points of a cubic-bezier lie from 0 to 1, as CSS takes them
+    easing: /^cubic-bezier\(\s*(0(\.\d+)?|1(\.0+)?|\.\d+)\s*,\s*-?(\d+(\.\d+)?|\.\d+)\s*,\s*(0(\.\d+)?|1(\.0+)?|\.\d+)\s*,\s*-?(\d+(\.\d+)?|\.\d+)\s*\)$|^(linear|ease|ease-in|ease-out|ease-in-out)$/
+};
+const expectedValues = {
+    length: 'a length in px, rem or em, as 64px',
+    time: 'a time in ms or s, as 300ms',
+    number: 'a number, as 0.5',
+    integer: 'an integer, as 2',
+    easing: 'a curve of CSS, as cubic-bezier(.2, 0, 0, 1) or ease-out'
+};
+/** The problem of a value for its variable, or undefined for a good value. */
+export function checkCssValue(variable, value) {
+    if (!units[variable.kind].test(value)) {
+        return `expected ${expectedValues[variable.kind]}`;
+    }
+    const number = parseFloat(value);
+    if (variable.min !== undefined && number < variable.min) {
+        return `expected a value from ${variable.min}`;
+    }
+    if (variable.max !== undefined && number > variable.max) {
+        return `expected a value up to ${variable.max}`;
+    }
+    return undefined;
+}

package/dist/spec/schema.d.ts

@@ -0,0 +1,19 @@
+import type { BroSpecField } from './spec.js';
+/** A JSON Schema as a plain object. */
+export type BroJsonSchema = Record<string, unknown>;
+/**
+ * The JSON Schema of BroTableSpec, for the tools of the MCP server and the reference. It gives the form; validateSpec
+ * checks the meaning: the names of the fields, the cells and the filters, the values of the CSS variables.
+ */
+export declare const specSchema: BroJsonSchema;
+/** The JSON Schema of a filter of the Filter Drawer, as in the spec. */
+export declare const filterSchema: BroJsonSchema;
+/** The JSON Schema of the filling of one cell or of the row details, BroCellFilling, for the tools of the MCP server. */
+export declare const cellFillingSchema: BroJsonSchema;
+/** The JSON Schema of BroSpecFillings, the parts of the code that a model writes, for the tools of the MCP server. */
+export declare const fillingsSchema: BroJsonSchema;
+/**
+ * The JSON Schema of the rows for the fields of a spec. A strict schema of a model has no object with free keys, so
+ * the site asks the model for the rows by this schema, after the spec: every value gets the type of its field.
+ */
+export declare function rowsSchema(fields: BroSpecField[]): BroJsonSchema;