@svgrid/enterprise 2.5.2 → 2.6.0

package/dist/studio/scaffold.js

@@ -0,0 +1,346 @@
+/**
+ * scaffold - turn an `EntitySchema` into runnable SvelteKit files. The shared
+ * code-emit core: both the AI generator (MCP `scaffold_entity` tool) and the
+ * visual designer's "Generate code" action call this one function, so there is
+ * a single source of truth for what generated code looks like.
+ *
+ * Every generated file wraps its body in `svgrid:managed` markers. A future
+ * regeneration replaces only the managed region, so edits a user makes outside
+ * the markers survive - idempotent generation, the thing that makes a
+ * generator trustworthy enough to keep using.
+ *
+ * Pure string building. No filesystem, no Svelte. The `validate` (Standard
+ * Schema) functions on a field cannot be serialized to a literal, so they are
+ * omitted from the emitted schema with a note to re-add them by hand.
+ */
+import { resolveIdField } from '../schema.js';
+const DRIVERS = {
+    postgres: {
+        imports: `import pg from 'pg'`,
+        setup: `const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL })`,
+        dialectArg: `\n  dialect: { placeholders: '$', ilike: true },`,
+        execBody: `const result = await pool.query(text, params)\n    return result.rows`,
+    },
+    mysql: {
+        imports: `import mysql from 'mysql2/promise'`,
+        setup: `const pool = mysql.createPool(process.env.DATABASE_URL ?? '')`,
+        dialectArg: ``,
+        execBody: `const [rows] = await pool.query(text, params)\n    return rows as Record<string, unknown>[]`,
+    },
+    mssql: {
+        imports: `import mssql from 'mssql'`,
+        setup: `const poolPromise = mssql.connect(process.env.DATABASE_URL ?? '')`,
+        dialectArg: `\n  dialect: { placeholders: '@' },`,
+        execBody: `const pool = await poolPromise\n    const request = pool.request()\n    params.forEach((p, i) => request.input('p' + (i + 1), p))\n    const result = await request.query(text)\n    return result.recordset as Record<string, unknown>[]`,
+    },
+    sqlite: {
+        imports: `import Database from 'better-sqlite3'`,
+        setup: `const db = new Database(process.env.DATABASE_URL ?? 'data.db')`,
+        dialectArg: ``,
+        execBody: `return db.prepare(text).all(...params) as Record<string, unknown>[]`,
+    },
+};
+/**
+ * Whether an in-place writer must SKIP this file to preserve the developer's
+ * code: a user-owned companion (a screen's `handlers.ts`) that already exists on
+ * disk. Such files carry no `svgrid:managed` markers, so `mergeManaged` would
+ * overwrite them wholesale - the write-once contract lives here instead, shared
+ * by every writer (CLI regenerate + the designer's bundle write). See
+ * HANDLERS-DESIGN.md.
+ */
+export function skipUserOwned(file, existsOnDisk) {
+    return file.userOwned === true && existsOnDisk;
+}
+export const MANAGED_START = '// svgrid:managed:start';
+export const MANAGED_END = '// svgrid:managed:end';
+const MANAGED_NOTE = '// Regenerated by SvGrid Studio. Edits inside these markers are overwritten.';
+function pascal(name) {
+    return name
+        .replace(/[_\-\s]+/g, ' ')
+        .replace(/([a-z\d])([A-Z])/g, '$1 $2')
+        .split(' ')
+        .filter(Boolean)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join('');
+}
+function camel(name) {
+    const p = pascal(name);
+    return p.charAt(0).toLowerCase() + p.slice(1);
+}
+function tsType(field) {
+    switch (field.type) {
+        case 'number':
+            return 'number';
+        case 'boolean':
+            return 'boolean';
+        default:
+            return 'string';
+    }
+}
+function fieldLiteral(field) {
+    const parts = [`field: ${JSON.stringify(field.field)}`, `type: ${JSON.stringify(field.type)}`];
+    if (field.label)
+        parts.push(`label: ${JSON.stringify(field.label)}`);
+    if (field.primaryKey)
+        parts.push('primaryKey: true');
+    if (field.readonly)
+        parts.push('readonly: true');
+    if (field.required)
+        parts.push('required: true');
+    if (field.hidden)
+        parts.push(`hidden: ${JSON.stringify(field.hidden)}`);
+    if (field.options)
+        parts.push(`options: ${JSON.stringify(field.options)}`);
+    if (field.relation)
+        parts.push(`relation: ${JSON.stringify(field.relation)}`);
+    return `    { ${parts.join(', ')} }`;
+}
+function schemaLiteral(schema, constName, rowType) {
+    const head = [`  name: ${JSON.stringify(schema.name)}`];
+    if (schema.label)
+        head.push(`  label: ${JSON.stringify(schema.label)}`);
+    if (schema.idField)
+        head.push(`  idField: ${JSON.stringify(schema.idField)}`);
+    const fields = schema.fields.map(fieldLiteral).join(',\n');
+    return `export const ${constName}: EntitySchema<${rowType}> = {\n${head.join(',\n')},\n  fields: [\n${fields}\n  ],\n}`;
+}
+function managed(body) {
+    return `${MANAGED_START}\n${MANAGED_NOTE}\n${body}\n${MANAGED_END}`;
+}
+export function scaffold(schema, options = {}) {
+    const route = options.route ?? schema.name;
+    const apiRoute = options.apiRoute ?? `/api/${route}`;
+    const schemaImport = options.schemaImport ?? `$lib/${route}.schema`;
+    const constName = `${camel(schema.name)}Schema`;
+    const rowType = `${pascal(schema.name)}Row`;
+    const idField = resolveIdField(schema);
+    const label = schema.label ?? schema.name;
+    const rowFields = schema.fields
+        .map((f) => `  ${f.field}: ${tsType(f)}`)
+        .join('\n');
+    // 1. The schema module ($lib).
+    const schemaFile = {
+        path: `src/lib/${route}.schema.ts`,
+        description: 'Entity schema + row type. Re-add any Standard Schema `validate` functions here by hand.',
+        contents: `import type { EntitySchema } from '@svgrid/enterprise'
+
+${managed(`export type ${rowType} = {
+${rowFields}
+}
+
+${schemaLiteral(schema, constName, rowType)}`)}
+`,
+    };
+    // 2. The API route: SvelteKit +server.ts using the transport handlers.
+    const dataSource = options.dataSource ?? 'memory';
+    const driver = dataSource === 'supabase' ? DRIVERS.postgres : DRIVERS[dataSource];
+    let serverImport;
+    let serverBody;
+    let serverDescription;
+    if (driver) {
+        // Fully-connected route: driver + DATABASE_URL, no manual editing needed.
+        serverImport = `${driver.imports}
+import { createKitHandlers, createSqlDataSource } from '@svgrid/enterprise'`;
+        serverBody = `${driver.setup}
+
+const source = createSqlDataSource<${rowType}>({
+  schema: ${constName},
+  table: ${JSON.stringify(schema.name)},${driver.dialectArg}
+  execute: async (text, params) => {
+    ${driver.execBody}
+  },
+})
+
+export const { POST } = createKitHandlers({ schema: ${constName}, source })`;
+        serverDescription = `API route connected to your ${dataSource} database via process.env.DATABASE_URL.`;
+    }
+    else if (dataSource === 'sql') {
+        serverImport = `import { createKitHandlers, createSqlDataSource } from '@svgrid/enterprise'`;
+        serverBody = `// Wire execute() to your SQL client: run \`text\` with \`params\`, return the rows.
+// Works with Drizzle (db.execute), postgres.js, better-sqlite3, mysql2, ...
+const source = createSqlDataSource<${rowType}>({
+  schema: ${constName},
+  table: ${JSON.stringify(schema.name)},
+  dialect: { placeholders: '$', ilike: true },
+  execute: async (text, params) => {
+    throw new Error('TODO: run the query with your database client and return the rows.')
+  },
+})
+
+export const { POST } = createKitHandlers({ schema: ${constName}, source })`;
+        serverDescription = 'API route. Fill in execute() with your SQL client (Drizzle / postgres.js / ...).';
+    }
+    else {
+        serverImport = `import { createInMemoryDataSource, createKitHandlers } from '@svgrid/enterprise'`;
+        serverBody = `// Starts empty and in-memory so the screen runs immediately. Swap this for
+// a database-backed source (scaffold with dataSource:"sql" or a dialect) when ready.
+const source = createInMemoryDataSource<${rowType}>([], ${constName})
+
+export const { POST } = createKitHandlers({ schema: ${constName}, source })`;
+        serverDescription = 'API route using an in-memory source. Scaffold with a dialect for a real database.';
+    }
+    const serverFile = {
+        path: `src/routes${apiRoute}/+server.ts`,
+        description: serverDescription,
+        contents: `${serverImport}
+import { ${constName}, type ${rowType} } from '${schemaImport}'
+
+${managed(serverBody)}
+`,
+    };
+    // Relation (foreign-key) fields become searchable lookups in the edit form.
+    // Each lookup queries the related entity's API route, so scaffold those tables
+    // too (e.g. `npx @svgrid/studio add <relatedTable>`).
+    const relationFields = schema.fields.filter((f) => f.type === 'relation' && !!f.relation);
+    const hasLookups = relationFields.length > 0;
+    const lookupDecls = relationFields
+        .map((f) => {
+        const name = `${camel(f.field)}Lookup`;
+        const endpoint = JSON.stringify(`/api/${f.relation.entity}`);
+        return `  const ${name} = createRelationLookup<Record<string, unknown>>({
+    source: createKitDataSource({ endpoint: ${endpoint} }),
+    labelField: ${JSON.stringify(f.relation.labelField)},
+  })`;
+    })
+        .join('\n');
+    const lookupsMap = `  const lookups = { ${relationFields
+        .map((f) => `${JSON.stringify(f.field)}: ${camel(f.field)}Lookup`)
+        .join(', ')} }`;
+    const lookupsSection = hasLookups ? `\n\n${lookupDecls}\n${lookupsMap}` : '';
+    // 3. The page: a full data screen - search, server sort + paging,
+    //    multi-select delete (optimistic), create/edit, loading/error/empty.
+    const pageBody = `  const source = createKitDataSource<${rowType}>({ endpoint: '${apiRoute}' })
+  const columns = schemaToColumns(${constName})${lookupsSection}
+
+  let state = $state<ServerState<${rowType}>>({
+    rows: [], total: 0, loading: false, saving: false, error: null,
+    pageIndex: 0, pageSize: 25, pageCount: 1, sortModel: [], filterModel: {},
+  })
+  const controller = createServerDataSource<${rowType}>(source, {
+    pageSize: 25,
+    optimistic: true,
+    getRowId: (r) => String(r.${idField}),
+    onChange: (s) => (state = s),
+  })
+  controller.refresh()
+
+  let selected = $state<${rowType}[]>([])
+  let editing = $state<${rowType} | null | undefined>(undefined) // undefined = closed, null = create
+
+  async function save({ mode, id, values }: { mode: 'create' | 'edit'; id: string | null; values: Partial<${rowType}> }) {
+    if (mode === 'create') {
+      await controller.createRow(values)
+      controller.setPage(state.pageCount - 1) // jump to the new row (appended at the end)
+    } else if (id) {
+      await controller.updateRow(id, values)
+    }
+    editing = undefined
+  }
+
+  async function removeSelected() {
+    for (const row of selected) await controller.deleteRow(String(row.${idField}))
+    selected = []
+  }`;
+    const pageFile = {
+        path: `src/routes/${route}/+page.svelte`,
+        description: 'The data screen: sort, filter, search, paging, multi-select delete, and create/edit - wired to the API route.',
+        contents: `<script lang="ts">
+  import { SvGrid, createServerDataSource } from '@svgrid/grid'
+  import {
+    SvGridEditPanel,
+    createKitDataSource,${hasLookups ? '\n    createRelationLookup,' : ''}
+    schemaToColumns,
+    type ServerState,
+  } from '@svgrid/enterprise'
+  import { ${constName}, type ${rowType} } from '${schemaImport}'
+
+${managed(pageBody)}
+</script>
+
+<div class="page">
+  <header class="page__toolbar">
+    <h2 class="page__title">${label}</h2>
+    <div class="page__actions">
+      <button onclick={() => (editing = null)}>New</button>
+      <button disabled={selected.length === 0} onclick={removeSelected}>
+        Delete {selected.length > 0 ? '(' + selected.length + ')' : ''}
+      </button>
+    </div>
+  </header>
+
+  {#if state.error}<p class="page__error" role="alert">{state.error}</p>{/if}
+
+  <SvGrid
+    data={state.rows}
+    {columns}
+    loading={state.loading}
+    loadingOverlay
+    fitColumns
+    enableRowSummaries={false}
+    showRowSelection
+    enableCellSelection
+    sortable
+    externalSort
+    onSortingChange={(s) => controller.setSort(s)}
+    filterable
+    showGlobalFilter
+    externalFilter
+    onFiltersChange={(f) =>
+      controller.setFilter({
+        global: f.global || undefined,
+        columns: Object.fromEntries(
+          f.columns.map((c) => [c.id, { operator: c.operator, value: c.value, valueTo: c.valueTo, selectedValues: c.selectedValues }]),
+        ),
+      })}
+    onRowClick={(e) => (editing = e.row)}
+    onRowSelectionChange={(_sel, rows) => (selected = rows)}
+    showPagination
+    externalPagination
+    rowCount={state.total}
+    pageIndex={state.pageIndex}
+    pageSize={state.pageSize}
+    onPaginationChange={({ pageIndex, pageSize }) => {
+      if (pageSize !== state.pageSize) controller.setPageSize(pageSize)
+      else controller.setPage(pageIndex)
+    }}
+    emptyMessage="No ${label} yet"
+    containerHeight={480}
+  />
+
+  {#if editing !== undefined}
+    <SvGridEditPanel schema={${constName}} row={editing} ${hasLookups ? 'lookups={lookups} ' : ''}onSubmit={save} onCancel={() => (editing = undefined)} />
+  {/if}
+</div>
+
+<style>
+  .page { display: flex; flex-direction: column; gap: 12px; }
+  .page__toolbar { display: flex; align-items: center; justify-content: space-between; gap: 12px; }
+  .page__title { margin: 0; font-size: 18px; font-weight: 600; }
+  .page__actions { display: flex; gap: 8px; }
+  .page__actions button { padding: 7px 12px; border: 1px solid #ccc; border-radius: 6px; background: #fff; cursor: pointer; }
+  .page__error { margin: 0; padding: 8px 12px; color: #b3261e; background: #fdecea; border-radius: 6px; }
+</style>
+`,
+    };
+    return { files: [schemaFile, serverFile, pageFile] };
+}
+/**
+ * Merge freshly-scaffolded files into existing file contents, replacing only
+ * each file's `svgrid:managed` region and preserving everything a user wrote
+ * outside it. When there's no existing content (or no markers in it), the new
+ * file is used whole. This is what makes regeneration safe.
+ */
+export function mergeManaged(existing, generated) {
+    if (!existing)
+        return generated;
+    const startIdx = existing.indexOf(MANAGED_START);
+    const endIdx = existing.indexOf(MANAGED_END);
+    if (startIdx === -1 || endIdx === -1 || endIdx < startIdx)
+        return generated;
+    const genStart = generated.indexOf(MANAGED_START);
+    const genEnd = generated.indexOf(MANAGED_END);
+    if (genStart === -1 || genEnd === -1)
+        return generated;
+    const newRegion = generated.slice(genStart, genEnd + MANAGED_END.length);
+    return (existing.slice(0, startIdx) + newRegion + existing.slice(endIdx + MANAGED_END.length));
+}

package/dist/studio/screen-suites.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Screen factories + the CRUD-suite generator.
+ *
+ * Two layers live here:
+ *
+ * 1. The composable screen factories (`listScreen` / `formScreen` / `detailScreen`
+ *    / `dashScreen`) the curated sample apps are built from. They take explicit,
+ *    hand-picked options - a sample app knows its own domain.
+ * 2. The CRUD suite (`crudSuiteScreens` / `addCrudSuite` / `crudAppFromSchemas`),
+ *    which derives those options from a schema and produces a linked multi-screen
+ *    app: a list, an edit form, a record detail page, and an optional overview
+ *    dashboard, with drill-through and related-child tabs wired from the entity's
+ *    relations. This is what the guided onboarding (designer wizard + `svgrid-studio
+ *    init`) calls, so both hosts scaffold identical apps.
+ *
+ * Pure + node-safe (studio subtree): plain data built from the same immutable ops
+ * the designer uses, so results round-trip through parse/serialize and generate a
+ * runnable app with no special-casing.
+ */
+import type { EntitySchema } from '../schema.js';
+import type { ChartType } from '@svgrid/grid';
+import { type BlockConfig, type DataSourceKind, type DetailRelated, type EntityDataSource, type FormatRule, type GridDensity, type GridEditing, type KpiFormat, type Presentation, type ProjectTheme, type Reduce, type RowAction, type RowLink, type Screen, type StudioProject } from './project.js';
+/** Rich-grid options an enterprise screen layers onto the default grid: status
+ *  pills / thresholds (formatRules), a totals row, row actions, row-click drill,
+ *  and density. */
+export type GridOpts = {
+    format?: FormatRule[];
+    rowActions?: RowAction[];
+    rowLink?: RowLink;
+    summaries?: boolean;
+    density?: GridDensity;
+    pageSize?: number;
+    /** How rows are edited: in-cell, via a popup form, or not at all (read-only
+     *  lists that drill into a detail page). Defaults to the grid default (`'form'`). */
+    editing?: GridEditing;
+    /** Where the edit form opens when `editing` is `'form'`. */
+    formPresentation?: Presentation;
+};
+/** A dashboard tile: KPI card (with trend/target/format), chart, gauge, pivot,
+ *  tree, a rich grid, or a tabbed group of display tiles. */
+export type Tile = {
+    kpi: string;
+    measure?: string;
+    reduce: Reduce;
+    format?: KpiFormat;
+    trendField?: string;
+    trendReduce?: Reduce;
+    target?: number;
+    span?: 1 | 2 | 3;
+} | {
+    chart: string;
+    measure?: string;
+    reduce?: Reduce;
+    type?: ChartType;
+    span?: 1 | 2 | 3;
+} | {
+    gauge: string;
+    measure?: string;
+    reduce: Reduce;
+    min?: number;
+    max?: number;
+    unit?: string;
+    span?: 1 | 2 | 3;
+} | {
+    pivot: {
+        rows: string[];
+        cols: string[];
+        measure?: string;
+        aggregate?: Reduce;
+    };
+    span?: 1 | 2 | 3;
+} | {
+    tree: {
+        labelField: string;
+        parentField: string;
+    };
+    span?: 1 | 2 | 3;
+} | ({
+    grid: true;
+    span?: 1 | 2 | 3;
+} & GridOpts) | {
+    filter: string[];
+    span?: 1 | 2 | 3;
+} | {
+    tabs: {
+        label: string;
+        tiles: Tile[];
+    }[];
+    span?: 1 | 2 | 3;
+};
+/** The default grid config with enterprise options merged on. */
+export declare function gridConfig(entity: EntitySchema, opts: GridOpts): BlockConfig;
+/** Compose a dashboard screen from explicit tiles (KPI cards + gauges + charts +
+ *  pivots + trees + a rich grid). */
+export declare function dashScreen(entity: EntitySchema, meta: {
+    id: string;
+    title: string;
+    order: number;
+}, tiles: Tile[]): Screen;
+/** FormatRule[] that color-code an enum field's cells by its option colors -
+ *  turns a plain status column into enterprise status pills. */
+export declare function statusPills(entity: EntitySchema, field: string): FormatRule[];
+/** A list screen: an optional faceted filter panel + a rich grid (status pills,
+ *  totals, row actions, drill-through). */
+export declare function listScreen(entity: EntitySchema, meta: {
+    id: string;
+    title: string;
+    order: number;
+}, opts?: {
+    filter?: string[];
+    grid?: GridOpts;
+}): Screen;
+/**
+ * A form-showcase screen: a grid to pick a row + an editable record panel that
+ * renders the full field form (phone / rating / tags / mask / slider editors)
+ * inline. Lets a user see and try the rich editors on load, not just on edit.
+ */
+export declare function formScreen(entity: EntitySchema, meta: {
+    id: string;
+    title: string;
+    order: number;
+}, fields?: string[], grid?: GridOpts, filter?: string[]): Screen;
+/** A record detail-page screen: a full record view (header + status pill + metric
+ *  tiles + tabbed Overview / related timelines) - the signature view for
+ *  relation-heavy records (a customer / deal / patient / trip page). */
+export declare function detailScreen(entity: EntitySchema, meta: {
+    id: string;
+    title: string;
+    order: number;
+}, opts: {
+    titleField: string;
+    subtitleField?: string;
+    statusField?: string;
+    metricFields?: string[];
+    sections?: {
+        label: string;
+        fields: string[];
+    }[];
+    related?: DetailRelated[];
+}): Screen;
+/** The screens a CRUD suite can contain. */
+export type CrudScreenKind = 'list' | 'form' | 'detail' | 'dashboard';
+/** How the suite's rows are edited. `'inline'` edits in the grid, `'form'` opens
+ *  a popup form (the grid default), `'detail'` makes a row click navigate to the
+ *  generated detail page (and leaves the list read-only). */
+export type CrudEditingMode = 'inline' | 'form' | 'detail';
+export type CrudSuiteOptions = {
+    /** Which screens to generate. Default: `['list', 'form']`, plus `'detail'` when
+     *  another entity relates to this one (there are children worth showing). */
+    screens?: CrudScreenKind[];
+    /** Row editing mode. Default `'form'`. */
+    editing?: CrudEditingMode;
+    /** Nav order of the suite's first screen; later screens follow it. Default 0. */
+    navOrder?: number;
+    /** Show a faceted filter panel on the list screen. Defaults to on when the
+     *  entity has filter-friendly (enum / boolean / text) fields. */
+    filter?: boolean;
+    /** Ids and routes already in use. The suite picks non-colliding ones BEFORE it
+     *  wires drill-through, so a rename can never orphan a `rowLink`. */
+    taken?: {
+        ids?: ReadonlySet<string>;
+        routes?: ReadonlySet<string>;
+    };
+};
+/**
+ * The screens for one entity: a list, an edit form, a record detail page, and/or
+ * an overview dashboard - already linked to each other. `entities` is the full
+ * schema set so relations resolve (drill-through targets + child collections).
+ */
+export declare function crudSuiteScreens(entity: EntitySchema, entities: readonly EntitySchema[], opts?: CrudSuiteOptions): Screen[];
+/** Append a full CRUD suite for an existing entity (immutable, like `addScreenFromTemplate`). */
+export declare function addCrudSuite(project: StudioProject, entityName: string, opts?: CrudSuiteOptions): StudioProject;
+export type CrudAppOptions = {
+    title?: string;
+    /** Default source kind for entities with no explicit binding in `sources`. */
+    dataSource?: DataSourceKind;
+    /** Per-entity source binding (a live SQL table, a REST endpoint, PGlite, ...). */
+    sources?: Record<string, EntityDataSource>;
+    /** Per-entity seed rows, merged into memory / PGlite bindings. */
+    seed?: Record<string, Record<string, unknown>[]>;
+    /** Per-entity suite overrides, keyed by entity name. */
+    perEntity?: Record<string, CrudSuiteOptions>;
+    /** Lead with an overview dashboard over the most-referenced entity. Default true. */
+    overviewDashboard?: boolean;
+    theme?: ProjectTheme;
+};
+/**
+ * A complete app from a set of schemas: an overview dashboard plus a CRUD suite
+ * per entity, bound to the given data sources. This is the guided-onboarding
+ * output - the designer wizard and `svgrid-studio init` both land here, so a
+ * database connected from either host scaffolds the same app.
+ */
+export declare function crudAppFromSchemas(schemas: EntitySchema[], opts?: CrudAppOptions): StudioProject;