@svgrid/enterprise 2.3.0 → 2.3.1

package/src/studio/samples/shared.ts

@@ -8,9 +8,14 @@
  * parse/serialize and generates a runnable app with no special-casing.
  */
 import type { EntitySchema } from '../../schema.js'
-import type { ChartType } from '@svgrid/grid'
 import { generateValue } from '../sample-data.js'
-import { defaultBlockConfig, sanitizeProject, screenFromTemplate, buildDockLayout, type Block, type BlockConfig, type DetailRelated, type FormatRule, type GridConfig, type GridDensity, type KpiFormat, type Reduce, type RowAction, type RowLink, type Screen, type ScreenTemplate, type StudioProject, type EntityDataSource, type ShellStyle, type SchedulerViewConfig, type SchedulerViewMode, type AuthConfig, type AccessControl } from '../project.js'
+import { gridConfig, type GridOpts } from '../screen-suites.js'
+import { sanitizeProject, screenFromTemplate, buildDockLayout, type Block, type GridConfig, type Screen, type ScreenTemplate, type StudioProject, type EntityDataSource, type ShellStyle, type SchedulerViewConfig, type SchedulerViewMode, type AuthConfig, type AccessControl } from '../project.js'
+
+// The generic screen factories live in `../screen-suites.js` (they are public API
+// now - the guided CRUD suite builds on them). Re-exported here so every sample
+// app keeps importing its whole toolkit from one place.
+export { dashScreen, detailScreen, formScreen, gridConfig, listScreen, statusPills, type GridOpts, type Tile } from '../screen-suites.js'
 
 type Row = Record<string, unknown>
 
@@ -72,135 +77,6 @@ export type SampleApp = {
   build: () => StudioProject
 }
 
-/** 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
-}
-
-/** 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. */
-function gridConfig(entity: EntitySchema, opts: GridOpts): BlockConfig {
-  const base = defaultBlockConfig('grid', entity) as GridConfig
-  return {
-    ...base,
-    ...(opts.format ? { formatRules: opts.format } : {}),
-    ...(opts.rowActions ? { rowActions: opts.rowActions } : {}),
-    ...(opts.rowLink ? { rowLink: opts.rowLink } : {}),
-    ...(opts.summaries ? { rowSummaries: true } : {}),
-    ...(opts.density ? { density: opts.density } : {}),
-    ...(opts.pageSize ? { pageSize: opts.pageSize } : {}),
-  }
-}
-
-/** One dashboard tile -> a Block. Recurses for `tabs` (whose children must be
- *  display blocks: chart / kpi / gauge / pivot / tree). `nextId` yields ids unique
- *  across the WHOLE screen (top-level tiles AND every nested tab child) - a per-level
- *  index would collide (top-level `blk-1` vs each tab's first child `blk-1`), which
- *  makes a keyed each throw `each_key_duplicate`. */
-function tileBlock(entity: EntitySchema, t: Tile, nextId: () => string): Block {
-  const id = nextId()
-  if ('kpi' in t) {
-    const config: BlockConfig = {
-      kind: 'kpi', label: t.kpi, ...(t.measure ? { measure: t.measure } : {}), reduce: t.reduce,
-      ...(t.format ? { format: t.format } : {}), ...(t.trendField ? { trendField: t.trendField } : {}),
-      ...(t.trendReduce ? { trendReduce: t.trendReduce } : {}), ...(t.target != null ? { target: t.target } : {}),
-    }
-    return { id, span: t.span ?? 1, config }
-  }
-  if ('chart' in t) {
-    return { id, span: t.span ?? 2, config: { kind: 'chart', dimension: t.chart, ...(t.measure ? { measure: t.measure } : {}), reduce: t.reduce ?? 'sum', type: t.type ?? 'bar' } }
-  }
-  if ('gauge' in t) {
-    return { id, span: t.span ?? 1, config: { kind: 'gauge', label: t.gauge, ...(t.measure ? { measure: t.measure } : {}), reduce: t.reduce, min: t.min ?? 0, max: t.max ?? 100, ...(t.unit ? { unit: t.unit } : {}) } }
-  }
-  if ('pivot' in t) {
-    return { id, span: t.span ?? 3, config: { kind: 'pivot', rows: t.pivot.rows, cols: t.pivot.cols, ...(t.pivot.measure ? { measure: t.pivot.measure } : {}), aggregate: t.pivot.aggregate ?? 'sum' } }
-  }
-  if ('tree' in t) {
-    return { id, span: t.span ?? 1, config: { kind: 'tree', labelField: t.tree.labelField, parentField: t.tree.parentField } }
-  }
-  if ('filter' in t) {
-    return { id, span: t.span ?? 3, config: { kind: 'filter', fields: t.filter } }
-  }
-  if ('tabs' in t) {
-    return { id, span: t.span ?? 3, config: { kind: 'tabs', tabs: t.tabs.map((tab) => ({ label: tab.label, blocks: tab.tiles.map((tt) => tileBlock(entity, tt, nextId)) })) } }
-  }
-  return { id, span: t.span ?? 3, config: gridConfig(entity, t) }
-}
-
-/** Compose a dashboard screen from explicit tiles (KPI cards + gauges + charts +
- *  pivots + trees + a rich grid). */
-export function dashScreen(
-  entity: EntitySchema,
-  meta: { id: string; title: string; order: number },
-  tiles: Tile[],
-): Screen {
-  let n = 0
-  const nextId = () => `blk-${++n}`
-  const blocks = tiles.map((t) => tileBlock(entity, t, nextId))
-  return { id: meta.id, entity: entity.name, title: meta.title, route: meta.id, blocks, nav: { show: true, label: meta.title, order: meta.order } }
-}
-
-/** FormatRule[] that color-code an enum field's cells by its option colors -
- *  turns a plain status column into enterprise status pills. */
-export function statusPills(entity: EntitySchema, field: string): FormatRule[] {
-  const f = entity.fields.find((x) => x.field === field)
-  if (!f?.options) return []
-  return f.options
-    .filter((o) => o.color)
-    .map((o) => ({ field, op: 'eq' as const, value: o.value as string | number, background: `color-mix(in srgb, ${o.color} 18%, transparent)`, color: o.color, bold: true }))
-}
-
-/** A list screen: an optional faceted filter panel + a rich grid (status pills,
- *  totals, row actions, drill-through). */
-export function listScreen(
-  entity: EntitySchema,
-  meta: { id: string; title: string; order: number },
-  opts: { filter?: string[]; grid?: GridOpts } = {},
-): Screen {
-  const blocks: Block[] = []
-  if (opts.filter?.length) blocks.push({ id: 'filter-1', span: 3, config: { kind: 'filter', fields: opts.filter } })
-  blocks.push({ id: 'grid-1', span: 3, config: gridConfig(entity, opts.grid ?? {}) })
-  return { id: meta.id, entity: entity.name, title: meta.title, route: meta.id, blocks, nav: { show: true, label: meta.title, order: meta.order } }
-}
-
-/**
- * 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 function formScreen(
-  entity: EntitySchema,
-  meta: { id: string; title: string; order: number },
-  fields?: string[],
-  grid?: GridOpts,
-  filter?: string[],
-): Screen {
-  const blocks: Block[] = []
-  if (filter?.length) blocks.push({ id: 'filter-1', span: 3, config: { kind: 'filter', fields: filter } })
-  blocks.push({ id: 'grid-1', span: 3, config: gridConfig(entity, grid ?? {}) })
-  blocks.push({ id: 'record-1', span: 3, config: { kind: 'record', editable: true, ...(fields ? { fields } : {}) } })
-  return { id: meta.id, entity: entity.name, title: meta.title, route: meta.id, blocks, nav: { show: true, label: meta.title, order: meta.order } }
-}
-
 /** A Kanban board screen: an optional filter panel + a board grouping rows by an
  *  enum field into draggable columns (the signature "pipeline" view). */
 export function boardScreen(
@@ -277,25 +153,6 @@ export function workspaceScreen(
   return { ...base, dock: buildDockLayout(base) }
 }
 
-/** 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 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 {
-  const blocks: Block[] = [{ id: 'detail-1', span: 3, config: {
-    kind: 'detail', titleField: opts.titleField,
-    ...(opts.subtitleField ? { subtitleField: opts.subtitleField } : {}),
-    ...(opts.statusField ? { statusField: opts.statusField } : {}),
-    ...(opts.metricFields?.length ? { metricFields: opts.metricFields } : {}),
-    ...(opts.sections?.length ? { sections: opts.sections } : {}),
-    ...(opts.related?.length ? { related: opts.related } : {}),
-  } }]
-  return { id: meta.id, entity: entity.name, title: meta.title, route: meta.id, blocks, nav: { show: true, label: meta.title, order: meta.order } }
-}
-
 /** Build a screen from a template, then override its id / route / title / nav.
  *  `linkScreen` wires a master-detail parent row to drill into a detail screen. */
 export function screen(

package/src/studio/screen-suites.test.ts

@@ -0,0 +1,226 @@
+import { describe, it, expect } from 'vitest'
+import type { EntitySchema } from '../schema.js'
+import { crudSuiteScreens, addCrudSuite, crudAppFromSchemas } from './screen-suites.js'
+import {
+  createProject,
+  parseProject,
+  serializeProject,
+  validateProject,
+  type DetailConfig,
+  type GridConfig,
+  type Screen,
+} from './project.js'
+
+const customers: EntitySchema = {
+  name: 'customers',
+  label: 'Customer',
+  idField: 'id',
+  fields: [
+    { field: 'id', type: 'text', primaryKey: true, readonly: true },
+    { field: 'name', type: 'text', label: 'Customer' },
+    { field: 'city', type: 'text' },
+    { field: 'tier', type: 'enum', options: [
+      { value: 'free', label: 'Free', color: '#64748b' },
+      { value: 'pro', label: 'Pro', color: '#2563eb' },
+    ] },
+    { field: 'spend', type: 'number' },
+  ],
+}
+
+const orders: EntitySchema = {
+  name: 'orders',
+  label: 'Order',
+  idField: 'id',
+  fields: [
+    { field: 'id', type: 'text', primaryKey: true, readonly: true },
+    { field: 'reference', type: 'text' },
+    { field: 'customer_id', type: 'relation', relation: { entity: 'customers', labelField: 'name' } },
+    { field: 'total', type: 'number' },
+    { field: 'status', type: 'enum', options: [{ value: 'paid', label: 'Paid', color: '#16a34a' }] },
+    { field: 'placed', type: 'dateString' },
+  ],
+}
+
+const gridOf = (screen: Screen): GridConfig =>
+  screen.blocks.find((b) => b.config.kind === 'grid')!.config as GridConfig
+const detailOf = (screen: Screen): DetailConfig =>
+  screen.blocks.find((b) => b.config.kind === 'detail')!.config as DetailConfig
+
+describe('crudSuiteScreens', () => {
+  it('defaults to list + form, and adds a detail page when the entity has children', () => {
+    // `customers` is referenced by `orders`, so it earns a detail page.
+    expect(crudSuiteScreens(customers, [customers, orders]).map((s) => s.id))
+      .toEqual(['customers', 'customers-manage', 'customers-detail'])
+    // `orders` has no children pointing at it - list + form only.
+    expect(crudSuiteScreens(orders, [customers, orders]).map((s) => s.id))
+      .toEqual(['orders', 'orders-manage'])
+  })
+
+  it('honours an explicit screen selection', () => {
+    const screens = crudSuiteScreens(customers, [customers, orders], { screens: ['dashboard', 'list'] })
+    expect(screens.map((s) => s.id)).toEqual(['customers-overview', 'customers'])
+  })
+
+  it('puts status pills and a totals row on the list grid', () => {
+    const [list] = crudSuiteScreens(customers, [customers], { screens: ['list'] })
+    const grid = gridOf(list!)
+    expect(grid.formatRules?.map((r) => r.value)).toEqual(['free', 'pro'])
+    expect(grid.rowSummaries).toBe(true)
+  })
+
+  it('seeds a faceted filter panel, and drops it when asked', () => {
+    const [withFacets] = crudSuiteScreens(customers, [customers], { screens: ['list'] })
+    expect(withFacets!.blocks[0]!.config.kind).toBe('filter')
+    const [plain] = crudSuiteScreens(customers, [customers], { screens: ['list'], filter: false })
+    expect(plain!.blocks.every((b) => b.config.kind !== 'filter')).toBe(true)
+  })
+
+  describe('editing modes', () => {
+    it("'form' (the default) edits through a popup form", () => {
+      const [list] = crudSuiteScreens(customers, [customers], { screens: ['list'] })
+      expect(gridOf(list!).editing).toBe('form')
+      expect(gridOf(list!).rowLink).toBeUndefined()
+    })
+
+    it("'inline' edits in the grid", () => {
+      const [list] = crudSuiteScreens(customers, [customers], { screens: ['list'], editing: 'inline' })
+      expect(gridOf(list!).editing).toBe('inline')
+    })
+
+    it("'detail' makes the list read-only and drills into the detail screen", () => {
+      const screens = crudSuiteScreens(customers, [customers, orders], { editing: 'detail' })
+      const list = screens.find((s) => s.id === 'customers')!
+      const detail = screens.find((s) => s.id === 'customers-detail')!
+      expect(gridOf(list).editing).toBe('none')
+      expect(gridOf(list).rowLink).toEqual({ screen: detail.id, targetField: 'id' })
+      // A drill target is reached by clicking a row, so it stays out of the nav.
+      expect(detail.nav?.show).toBe(false)
+    })
+  })
+
+  it('builds related-record tabs from every relation pointing at the entity', () => {
+    const [detail] = crudSuiteScreens(customers, [customers, orders], { screens: ['detail'] })
+    expect(detailOf(detail!).related).toEqual([
+      { entity: 'orders', foreignKey: 'customer_id', label: 'Order', titleField: 'reference', statusField: 'status', dateField: 'placed' },
+    ])
+  })
+
+  it('treats a self-referential FK as a child collection (a hierarchy)', () => {
+    const folders: EntitySchema = {
+      name: 'folders',
+      idField: 'id',
+      fields: [
+        { field: 'id', type: 'text', primaryKey: true },
+        { field: 'name', type: 'text' },
+        { field: 'parent_id', type: 'relation', relation: { entity: 'folders', labelField: 'name' } },
+      ],
+    }
+    const [detail] = crudSuiteScreens(folders, [folders], { screens: ['detail'] })
+    expect(detailOf(detail!).related?.[0]).toMatchObject({ entity: 'folders', foreignKey: 'parent_id' })
+  })
+
+  it('survives an entity with nothing but a primary key', () => {
+    const bare: EntitySchema = { name: 'flags', idField: 'id', fields: [{ field: 'id', type: 'text', primaryKey: true }] }
+    const screens = crudSuiteScreens(bare, [bare])
+    expect(screens.map((s) => s.id)).toEqual(['flags', 'flags-manage'])
+    expect(gridOf(screens[0]!).rowSummaries).toBeFalsy()
+  })
+
+  it('picks non-colliding ids AND routes, keeping drill-through pointed at the real screen', () => {
+    const screens = crudSuiteScreens(customers, [customers, orders], {
+      editing: 'detail',
+      taken: { ids: new Set(['customers', 'customers-detail']), routes: new Set(['customers']) },
+    })
+    const ids = screens.map((s) => s.id)
+    expect(ids).toEqual(['customers-2', 'customers-manage', 'customers-detail-2'])
+    expect(screens.map((s) => s.route)).toEqual(['customers-2', 'customers-manage', 'customers-detail'])
+    // The rowLink must name the RENAMED detail screen, not the original id.
+    expect(gridOf(screens[0]!).rowLink?.screen).toBe('customers-detail-2')
+  })
+})
+
+describe('addCrudSuite', () => {
+  it('appends a suite without disturbing the existing screens', () => {
+    const project = createProject([customers, orders])
+    const next = addCrudSuite(project, 'orders')
+    expect(next.screens.slice(0, 2).map((s) => s.id)).toEqual(['customers', 'orders'])
+    // 'orders' is taken by the default screen, so the suite claims fresh ids.
+    expect(next.screens.slice(2).map((s) => s.id)).toEqual(['orders-2', 'orders-manage'])
+    expect(project.screens).toHaveLength(2) // immutable
+  })
+
+  it('ignores an unknown entity', () => {
+    const project = createProject([customers])
+    expect(addCrudSuite(project, 'nope')).toBe(project)
+  })
+})
+
+describe('crudAppFromSchemas', () => {
+  it('leads with an overview dashboard over the most-referenced entity', () => {
+    const app = crudAppFromSchemas([orders, customers])
+    const first = app.screens[0]!
+    expect(first.title).toBe('Overview')
+    expect(first.entity).toBe('customers') // orders point at customers
+    expect(first.nav?.order).toBe(0)
+    expect(first.blocks.some((b) => b.config.kind === 'kpi')).toBe(true)
+  })
+
+  it('can skip the dashboard', () => {
+    const app = crudAppFromSchemas([customers, orders], { overviewDashboard: false })
+    expect(app.screens[0]!.id).toBe('customers')
+  })
+
+  it('generates a suite per entity with unique ids, routes and ordered nav', () => {
+    const app = crudAppFromSchemas([customers, orders])
+    const ids = app.screens.map((s) => s.id)
+    const routes = app.screens.map((s) => s.route)
+    expect(new Set(ids).size).toBe(ids.length)
+    expect(new Set(routes).size).toBe(routes.length)
+    const orders2 = app.screens.map((s) => s.nav?.order).filter((n): n is number => n != null)
+    expect([...orders2].sort((a, b) => a - b)).toEqual(orders2)
+  })
+
+  it('binds sources per entity and merges seed rows into memory bindings', () => {
+    const app = crudAppFromSchemas([customers], { seed: { customers: [{ id: 'c1', name: 'Acme' }] } })
+    expect(app.dataSources?.customers).toEqual({ kind: 'memory', seed: [{ id: 'c1', name: 'Acme' }] })
+  })
+
+  it('carries seed into a PGlite binding and leaves SQL bindings alone', () => {
+    const app = crudAppFromSchemas([customers, orders], {
+      dataSource: 'sql',
+      sources: { customers: { kind: 'pglite', table: 'customers' }, orders: { kind: 'sql', table: 'orders', dialect: 'postgres' } },
+      seed: { customers: [{ id: 'c1' }], orders: [{ id: 'o1' }] },
+    })
+    expect(app.dataSources?.customers).toEqual({ kind: 'pglite', table: 'customers', seed: [{ id: 'c1' }] })
+    expect(app.dataSources?.orders).toEqual({ kind: 'sql', table: 'orders', dialect: 'postgres' })
+    expect(app.dataSource).toBe('sql')
+  })
+
+  it('applies per-entity overrides', () => {
+    const app = crudAppFromSchemas([customers, orders], {
+      overviewDashboard: false,
+      perEntity: { orders: { screens: ['list'] } },
+    })
+    expect(app.screens.filter((s) => s.entity === 'orders').map((s) => s.id)).toEqual(['orders'])
+  })
+
+  it('produces a valid project that round-trips through parse/serialize', () => {
+    const app = crudAppFromSchemas([customers, orders], { title: 'Sales desk' })
+    expect(validateProject(app).filter((i) => i.level === 'error')).toEqual([])
+    const round = parseProject(serializeProject(app))
+    expect(round).toEqual(app)
+    expect(round.title).toBe('Sales desk')
+  })
+
+  it('every rowLink names a screen that exists', () => {
+    const app = crudAppFromSchemas([customers, orders], { perEntity: { customers: { editing: 'detail' } } })
+    const ids = new Set(app.screens.map((s) => s.id))
+    for (const screen of app.screens) {
+      for (const block of screen.blocks) {
+        if (block.config.kind !== 'grid') continue
+        const link = (block.config as GridConfig).rowLink
+        if (link) expect(ids.has(link.screen), `dangling rowLink -> ${link.screen}`).toBe(true)
+      }
+    }
+  })
+})