@svgrid/enterprise 1.2.0 → 2.0.0

package/src/sources/dashboard.ts

@@ -0,0 +1,136 @@
+/**
+ * Dashboard model - a declarative, schema-driven set of widgets (KPI tiles +
+ * charts) over an entity. This is a *data view*, not a page builder: the spec is
+ * plain data, `SvSchemaDashboard` renders it, and `dashboardFromSchema` proposes
+ * a sensible default from the schema's chart-able fields. KPI tiles reduce a
+ * measure to a single number; charts reuse `SvSchemaChart` (and its `aggregateRows`
+ * / `getAggregate` seam), so nothing here re-implements aggregation.
+ */
+import type { RowData } from '@svgrid/grid'
+import type { EntitySchema } from '../schema'
+import { chartFieldsFromSchema, type AggregateReduce } from './aggregate'
+import type { ChartType } from '@svgrid/grid'
+
+/** A single-number tile: reduce `measure` over the rows (count ignores measure). */
+export type KpiWidget = {
+  kind: 'kpi'
+  label: string
+  measure?: string
+  reduce: AggregateReduce
+  /** Format the number for display (e.g. currency). */
+  format?: (value: number) => string
+}
+
+/** A chart tile bound to a fixed dimension / measure / reduce / type. */
+export type ChartWidget = {
+  kind: 'chart'
+  label?: string
+  dimension: string
+  measure?: string
+  reduce: AggregateReduce
+  type: ChartType
+  /** Columns spanned in the dashboard grid. Default 1. */
+  span?: 1 | 2 | 3
+}
+
+export type DashboardWidget = KpiWidget | ChartWidget
+
+export type DashboardSpec = { widgets: DashboardWidget[] }
+
+const num = (v: unknown): number => {
+  const n = Number(v)
+  return Number.isFinite(n) ? n : 0
+}
+
+/**
+ * Reduce a measure over rows into a single KPI number. `count` returns the row
+ * count; `sum`/`avg`/`min`/`max` fold the measure. An empty set is 0.
+ */
+export function reduceValue<T extends RowData>(
+  rows: ReadonlyArray<T>,
+  request: { measure?: string; reduce: AggregateReduce },
+): number {
+  const { measure, reduce } = request
+  if (reduce === 'count' || !measure) return rows.length
+  if (rows.length === 0) return 0
+  const values = rows.map((r) => num(r[measure]))
+  if (reduce === 'sum') return values.reduce((a, b) => a + b, 0)
+  if (reduce === 'avg') return values.reduce((a, b) => a + b, 0) / values.length
+  if (reduce === 'min') return Math.min(...values)
+  return Math.max(...values) // 'max'
+}
+
+/**
+ * Group rows by `trendField` (sorted, so ISO dates / ordered categories line up)
+ * and reduce `measure` per bucket - the series behind a KPI card's sparkline.
+ */
+export function kpiSeries<T extends RowData>(
+  rows: ReadonlyArray<T>,
+  opts: { trendField: string; measure?: string; reduce: AggregateReduce },
+): number[] {
+  const groups = new Map<string, T[]>()
+  for (const r of rows) {
+    const k = String(r[opts.trendField] ?? '')
+    if (k === '') continue
+    ;(groups.get(k) ?? groups.set(k, []).get(k)!).push(r)
+  }
+  return [...groups.keys()].sort().map((k) => reduceValue(groups.get(k)!, { measure: opts.measure, reduce: opts.reduce }))
+}
+
+/** SVG polyline points for a sparkline in a `w` x `h` box (y grows downward). */
+export function sparklinePoints(values: number[], w = 120, h = 30, pad = 2): string {
+  if (values.length === 0) return ''
+  const min = Math.min(...values)
+  const range = Math.max(...values) - min || 1
+  const dx = values.length > 1 ? (w - pad * 2) / (values.length - 1) : 0
+  return values
+    .map((v, i) => `${(pad + i * dx).toFixed(1)},${(pad + (h - pad * 2) * (1 - (v - min) / range)).toFixed(1)}`)
+    .join(' ')
+}
+
+/** Percent change from the first non-zero point to the last (null when < 2 points). */
+export function seriesDelta(values: number[]): number | null {
+  if (values.length < 2) return null
+  const first = values.find((v) => v !== 0)
+  const last = values[values.length - 1]!
+  if (first == null || first === 0) return null
+  return ((last - first) / Math.abs(first)) * 100
+}
+
+/** Format a KPI number: currency (`$`), percent (`%`), compact (`1.2k`), or grouped. */
+export function formatKpiValue(value: number, format?: 'number' | 'currency' | 'percent' | 'compact'): string {
+  if (format === 'currency') return '$' + value.toLocaleString(undefined, { maximumFractionDigits: 0 })
+  if (format === 'percent') return value.toLocaleString(undefined, { maximumFractionDigits: 1 }) + '%'
+  if (format === 'compact') return new Intl.NumberFormat(undefined, { notation: 'compact', maximumFractionDigits: 1 }).format(value)
+  return value.toLocaleString(undefined, { maximumFractionDigits: 1 })
+}
+
+/**
+ * Propose a default dashboard from a schema: a total-count KPI, a sum/avg KPI on
+ * the first numeric measure (when there is one), and a bar chart on the default
+ * dimension / measure. Built from `chartFieldsFromSchema`.
+ */
+export function dashboardFromSchema(schema: EntitySchema): DashboardSpec {
+  const { defaultDimension, defaultMeasure } = chartFieldsFromSchema(schema)
+  const label = schema.label ?? schema.name
+  const widgets: DashboardWidget[] = [{ kind: 'kpi', label: `Total ${label}`, reduce: 'count' }]
+
+  if (defaultMeasure) {
+    widgets.push({ kind: 'kpi', label: `Total ${defaultMeasure}`, measure: defaultMeasure, reduce: 'sum' })
+    widgets.push({ kind: 'kpi', label: `Avg ${defaultMeasure}`, measure: defaultMeasure, reduce: 'avg' })
+  }
+
+  if (defaultDimension) {
+    widgets.push({
+      kind: 'chart',
+      label: defaultMeasure ? `${defaultMeasure} by ${defaultDimension}` : `Count by ${defaultDimension}`,
+      dimension: defaultDimension,
+      measure: defaultMeasure ?? undefined,
+      reduce: defaultMeasure ? 'sum' : 'count',
+      type: 'bar',
+      span: 2,
+    })
+  }
+
+  return { widgets }
+}

package/src/sources/field-inference.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest'
+import { refineField } from './field-inference'
+import type { EntityField } from '../schema'
+
+const f = (field: string, type: EntityField['type'] = 'text', extra: Partial<EntityField> = {}): EntityField =>
+  ({ field, type, ...extra })
+
+describe('refineField', () => {
+  it('infers formats + editors from text column names', () => {
+    expect(refineField(f('email')).format).toBe('email')
+    expect(refineField(f('contact_email')).format).toBe('email')
+    expect(refineField(f('website')).format).toBe('url')
+    expect(refineField(f('phone')).input?.editorType).toBe('phone')
+    expect(refineField(f('mobile_number')).input?.editorType).toBe('phone')
+    expect(refineField(f('country')).input?.editorType).toBe('country')
+    expect(refineField(f('brand_color')).input?.editorType).toBe('color')
+  })
+
+  it('masks structured codes with the right pattern', () => {
+    expect(refineField(f('ssn')).input).toMatchObject({ editorType: 'mask', mask: '###-##-####' })
+    expect(refineField(f('vin')).input?.mask).toBe('*****************')
+    expect(refineField(f('license_plate')).input?.mask).toBe('AAA-####')
+    expect(refineField(f('isbn')).input?.mask).toBe('###-#-#####-###-#')
+    expect(refineField(f('zip')).input?.mask).toBe('#####')
+    expect(refineField(f('tax_id')).input?.mask).toBe('##-#######')
+  })
+
+  it('routes password fields to a hidden-from-grid password editor', () => {
+    const r = refineField(f('password'))
+    expect(r.input?.editorType).toBe('password')
+    expect(r.hidden).toEqual({ grid: true })
+  })
+
+  it('infers rating / slider from numeric column names', () => {
+    expect(refineField(f('rating', 'number')).input?.editorType).toBe('rating')
+    expect(refineField(f('csat', 'number')).input?.editorType).toBe('rating')
+    expect(refineField(f('progress', 'number')).input?.editorType).toBe('slider')
+    expect(refineField(f('fuel_level', 'number')).input?.editorType).toBe('slider')
+  })
+
+  it('does NOT add range validation (must not reject existing data)', () => {
+    const r = refineField(f('rating', 'number'))
+    expect(r.min).toBeUndefined()
+    expect(r.max).toBeUndefined()
+  })
+
+  it('leaves keys, relations, enums, and explicit editors untouched', () => {
+    expect(refineField(f('phone', 'text', { primaryKey: true })).input).toBeUndefined()
+    expect(refineField(f('email', 'text', { readonly: true })).format).toBeUndefined()
+    expect(refineField({ field: 'ownerId', type: 'relation', relation: { entity: 'users', labelField: 'name' } }).input).toBeUndefined()
+    expect(refineField(f('country', 'enum', { options: [{ value: 'us', label: 'US' }] })).input).toBeUndefined()
+    const explicit = f('phone', 'text', { input: { editorType: 'mask', mask: '###' } })
+    expect(refineField(explicit).input).toEqual({ editorType: 'mask', mask: '###' })
+  })
+
+  it('leaves an ordinary field alone', () => {
+    expect(refineField(f('description'))).toEqual(f('description'))
+    expect(refineField(f('quantity', 'number'))).toEqual(f('quantity', 'number'))
+  })
+})

package/src/sources/field-inference.ts

@@ -0,0 +1,63 @@
+/**
+ * Infer a richer form editor for an introspected field from its name + type, so
+ * a database connected through Studio produces the same rich forms as the curated
+ * sample apps (a `phone` column becomes a phone input, `rating` a star rating,
+ * `email` an email field, `ssn` a masked input) instead of a wall of text boxes.
+ *
+ * DELIBERATELY CONSERVATIVE: it only refines on a clear name match, never touches
+ * a primary key / relation / enum field, and never adds range validation that
+ * could reject rows already in the user's database. Pure + node-safe. Applied by
+ * the shared `buildEntitySchema` (Drizzle / Prisma / PostgREST / sample row) and
+ * by the SQL-catalog path (`introspectDatabase`).
+ */
+import type { RowData } from '@svgrid/grid'
+import type { EntityField } from '../schema.js'
+
+/** Masked-code patterns keyed by a field-name test. `#`=digit, `A`=letter, `*`=alnum. */
+const MASKS: Array<[RegExp, string]> = [
+  [/(^|_)ssn$|social.?security/, '###-##-####'],
+  [/(^|_)vin$/, '*****************'],
+  [/plate|registration/, 'AAA-####'],
+  [/isbn/, '###-#-#####-###-#'],
+  [/zip|postal/, '#####'],
+  [/(^|_)ein$|tax.?id|vat/, '##-#######'],
+]
+
+/**
+ * Return a copy of `field` with an inferred `format` / `input.editorType` when the
+ * name (and type) clearly imply one; otherwise return it unchanged.
+ */
+export function refineField<T extends RowData = RowData>(field: EntityField<T>): EntityField<T> {
+  // Never override an explicit editor, a key, a relation, or an enum.
+  if (field.primaryKey || field.readonly || field.type === 'relation' || field.options?.length || field.input?.editorType) {
+    return field
+  }
+  const name = String(field.field).toLowerCase()
+  const withEditor = (editorType: NonNullable<EntityField['input']>['editorType'], extra: Record<string, unknown> = {}): EntityField<T> =>
+    ({ ...field, input: { ...(field.input ?? {}), editorType, ...extra } })
+
+  if (field.type === 'text') {
+    if (field.format == null) {
+      if (/e-?mail/.test(name)) return { ...field, format: 'email' }
+      if (/url|website|link|homepage|domain/.test(name)) return { ...field, format: 'url' }
+    }
+    if (/phone|mobile|(^|_)fax$|(^|_)tel(ephone)?$/.test(name)) return withEditor('phone')
+    if (/(^|_)country$|nationality/.test(name)) return withEditor('country')
+    if (/password|passwd|(^|_)pwd$/.test(name)) return { ...withEditor('password'), hidden: { grid: true } }
+    if (/colou?r$/.test(name)) return withEditor('color')
+    for (const [re, mask] of MASKS) if (re.test(name)) return withEditor('mask', { mask })
+  }
+
+  if (field.type === 'number') {
+    // Star rating (panel defaults max 5) or a 0-100 slider (panel defaults max 100).
+    if (/(^|_)(rating|score|stars|satisfaction|csat)$/.test(name)) return withEditor('rating')
+    if (/percent|progress|probability|completion|utili[sz]ation|occupancy|fuel.?level/.test(name)) return withEditor('slider')
+  }
+
+  return field
+}
+
+/** Refine every field of a schema's field list (leaves keys/relations/enums alone). */
+export function refineFields<T extends { fields: EntityField[] }>(schema: T): T {
+  return { ...schema, fields: schema.fields.map(refineField) }
+}

package/src/sources/filters.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+import type { ServerFilterModel } from '@svgrid/grid'
+import { normalizeFilters } from './filters'
+
+const model = (columns: ServerFilterModel['columns'], global?: string): ServerFilterModel => ({
+  columns,
+  ...(global !== undefined ? { global } : {}),
+})
+
+describe('normalizeFilters', () => {
+  it('maps each operator to a neutral predicate', () => {
+    const { predicates } = normalizeFilters(
+      model({
+        a: { operator: 'contains', value: 'x' },
+        b: { operator: 'startsWith', value: 'y' },
+        c: { operator: 'equals', value: 'z' },
+        d: { operator: 'greaterThan', value: '5' },
+        e: { operator: 'lessThan', value: '9' },
+        f: { operator: 'between', value: '1', valueTo: '4' },
+        g: { operator: 'isBlank', value: '' },
+      }),
+    )
+    expect(predicates).toEqual([
+      { column: 'a', op: 'contains', value: 'x' },
+      { column: 'b', op: 'startsWith', value: 'y' },
+      { column: 'c', op: 'eq', value: 'z' },
+      { column: 'd', op: 'gt', value: '5' },
+      { column: 'e', op: 'lt', value: '9' },
+      { column: 'f', op: 'between', value: '1', valueTo: '4' },
+      { column: 'g', op: 'isNull' },
+    ])
+  })
+
+  it('prefers selectedValues (set filter) as an in predicate', () => {
+    const { predicates } = normalizeFilters(
+      model({ tier: { operator: 'contains', value: 'ignored', selectedValues: ['pro', 'free'] } }),
+    )
+    expect(predicates).toEqual([{ column: 'tier', op: 'in', values: ['pro', 'free'] }])
+  })
+
+  it('drops empty column values but keeps isBlank', () => {
+    const { predicates } = normalizeFilters(
+      model({ a: { operator: 'contains', value: '   ' }, b: { operator: 'isBlank', value: '' } }),
+    )
+    expect(predicates).toEqual([{ column: 'b', op: 'isNull' }])
+  })
+
+  it('backfills a one-sided between with the given bound', () => {
+    const { predicates } = normalizeFilters(model({ a: { operator: 'between', value: '3', valueTo: '' } }))
+    expect(predicates).toEqual([{ column: 'a', op: 'between', value: '3', valueTo: '3' }])
+  })
+
+  it('trims the global search and omits it when blank', () => {
+    expect(normalizeFilters(model({}, '  hi ')).search).toBe('hi')
+    expect(normalizeFilters(model({}, '   ')).search).toBeUndefined()
+    expect(normalizeFilters(undefined)).toEqual({ predicates: [], search: undefined })
+  })
+})

package/src/sources/filters.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared filter normalization for data-source adapters. The grid emits a
+ * `ServerFilterModel` (per-column `{ operator, value, valueTo, selectedValues }`
+ * plus a global search string); every backend then has to translate that into
+ * its own query language. This turns the grid's model into one small, uniform
+ * list of predicates so each adapter (Supabase, REST, ...) maps a handful of
+ * clear cases instead of re-parsing the raw model.
+ */
+import type { ServerFilterModel } from '@svgrid/grid'
+
+/** A backend-neutral predicate over a single column. */
+export type NormalizedPredicate =
+  | { column: string; op: 'in'; values: string[] }
+  | { column: string; op: 'isNull' }
+  | { column: string; op: 'contains' | 'startsWith' | 'eq' | 'gt' | 'lt'; value: string }
+  | { column: string; op: 'between'; value: string; valueTo: string }
+
+export type NormalizedFilter = {
+  /** Column predicates, empty ones dropped. */
+  predicates: NormalizedPredicate[]
+  /** Free-text global search term (trimmed), if any. */
+  search?: string
+}
+
+/** Map the grid's per-column filter model into neutral predicates. */
+export function normalizeFilters(model: ServerFilterModel | undefined): NormalizedFilter {
+  const predicates: NormalizedPredicate[] = []
+  for (const [column, f] of Object.entries(model?.columns ?? {})) {
+    // Set / checklist filter takes precedence when present.
+    if (f.selectedValues?.length) {
+      predicates.push({ column, op: 'in', values: f.selectedValues })
+      continue
+    }
+    const value = (f.value ?? '').trim()
+    switch (f.operator) {
+      case 'isBlank':
+        predicates.push({ column, op: 'isNull' })
+        break
+      case 'between': {
+        const valueTo = (f.valueTo ?? '').trim()
+        if (value || valueTo) predicates.push({ column, op: 'between', value, valueTo: valueTo || value })
+        break
+      }
+      case 'startsWith':
+        if (value) predicates.push({ column, op: 'startsWith', value })
+        break
+      case 'equals':
+        if (value) predicates.push({ column, op: 'eq', value })
+        break
+      case 'greaterThan':
+        if (value) predicates.push({ column, op: 'gt', value })
+        break
+      case 'lessThan':
+        if (value) predicates.push({ column, op: 'lt', value })
+        break
+      case 'contains':
+      default:
+        if (value) predicates.push({ column, op: 'contains', value })
+        break
+    }
+  }
+  const search = model?.global?.trim()
+  return { predicates, search: search ? search : undefined }
+}

package/src/sources/index.ts

@@ -0,0 +1,67 @@
+/**
+ * Data-source adapters + introspection. Each adapter implements the grid's
+ * `ServerDataSource` over a specific backend, so the grid, edit form, sorting,
+ * filtering, and paging work identically regardless of where the data lives.
+ */
+export { normalizeFilters, type NormalizedFilter, type NormalizedPredicate } from './filters'
+export {
+  buildEntitySchema,
+  pickLabelField,
+  linkRelationLabels,
+  type IntrospectedColumn,
+  type ColumnReference,
+} from './schema-from-columns'
+export { createSupabaseDataSource, type SupabaseDataSourceConfig, type SupabaseClientLike } from './supabase'
+export { createRestDataSource, type RestDataSourceConfig } from './rest'
+export {
+  offsetLimitAdapter,
+  dummyJsonAdapter,
+  jsonServerAdapter,
+  type RestAdapter,
+  type OffsetLimitOptions,
+} from './rest-adapters'
+export { introspectSupabaseTable, type IntrospectSupabaseOptions } from './introspect-supabase'
+export {
+  createSupabaseRealtime,
+  type SupabaseRealtimeConfig,
+  type SupabaseRealtimeClientLike,
+  type SupabaseRealtimeHandle,
+  type RealtimeChannelLike,
+  type RealtimeChange,
+} from './realtime-supabase'
+export {
+  createRelationLookup,
+  type RelationLookup,
+  type RelationLookupConfig,
+  type RelationOption,
+} from './relation-lookup'
+export {
+  createSupabaseAuth,
+  type SupabaseAuthConfig,
+  type SupabaseAuthController,
+  type SupabaseAuthClientLike,
+  type AuthState,
+  type AuthUser,
+} from './auth-supabase'
+export {
+  aggregateRows,
+  chartFieldsFromSchema,
+  type AggregateReduce,
+  type AggregateRequest,
+  type AggregateBucket,
+  type AggregateSource,
+} from './aggregate'
+export { withEntityRules } from './with-entity-rules'
+export { withRelationLabels, type RelationLabelConfig } from './with-relation-labels'
+export {
+  reduceValue,
+  kpiSeries,
+  sparklinePoints,
+  seriesDelta,
+  formatKpiValue,
+  dashboardFromSchema,
+  type DashboardSpec,
+  type DashboardWidget,
+  type KpiWidget,
+  type ChartWidget,
+} from './dashboard'

package/src/sources/introspect-supabase.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest'
+import { introspectSupabaseTable } from './introspect-supabase'
+
+type Parts = { openapi?: unknown; openapiStatus?: number; csv?: string; sample?: unknown }
+
+function resp(opts: { status?: number; json?: unknown; text?: string; headers?: Record<string, string> }) {
+  const status = opts.status ?? 200
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: 'OK',
+    headers: { get: (k: string) => opts.headers?.[k.toLowerCase()] ?? null },
+    json: async () => opts.json,
+    text: async () => opts.text ?? '',
+  } as unknown as Response
+}
+
+function fetchFor(parts: Parts): typeof globalThis.fetch {
+  return (async (url: string | URL, init?: RequestInit) => {
+    const u = String(url)
+    const accept = (init?.headers as Record<string, string>)?.Accept
+    if (u.endsWith('/rest/v1/')) return resp({ status: parts.openapiStatus ?? 200, json: parts.openapi })
+    if (accept === 'text/csv') return resp({ text: parts.csv ?? '' })
+    return resp({ json: parts.sample ?? [] })
+  }) as unknown as typeof globalThis.fetch
+}
+
+const opts = (fetch: typeof globalThis.fetch) => ({ url: 'https://x.supabase.co', key: 'anon', table: 'customers', fetch })
+
+describe('introspectSupabaseTable', () => {
+  it('reads columns, types, and the primary key from the OpenAPI doc', async () => {
+    const openapi = {
+      definitions: {
+        customers: {
+          required: ['name'],
+          properties: {
+            id: { type: 'integer', description: 'Note:\nThis is a Primary Key.<pk/>' },
+            name: { type: 'string' },
+            active: { type: 'boolean' },
+            tier: { type: 'string', enum: ['free', 'pro'] },
+          },
+        },
+      },
+    }
+    const schema = await introspectSupabaseTable(opts(fetchFor({ openapi })))
+    expect(schema?.idField).toBe('id')
+    expect(schema?.fields.map((f) => [f.field, f.type])).toEqual([
+      ['id', 'number'], ['name', 'text'], ['active', 'boolean'], ['tier', 'enum'],
+    ])
+    expect(schema?.fields.find((f) => f.field === 'id')).toMatchObject({ primaryKey: true, readonly: true })
+    expect(schema?.fields.find((f) => f.field === 'name')?.required).toBe(true)
+  })
+
+  it('detects a foreign key from the OpenAPI description', async () => {
+    const openapi = {
+      definitions: {
+        customers: {
+          properties: {
+            id: { type: 'integer', description: '<pk/>' },
+            name: { type: 'string' },
+            company_id: { type: 'integer', description: "Note:\nThis is a Foreign Key to `companies.id`.<fk table='companies' column='id'/>" },
+          },
+        },
+      },
+    }
+    const schema = await introspectSupabaseTable(opts(fetchFor({ openapi })))
+    const rel = schema?.fields.find((f) => f.field === 'company_id')
+    expect(rel?.type).toBe('relation')
+    expect(rel?.relation).toEqual({ entity: 'companies', foreignKey: 'company_id', labelField: 'name' })
+  })
+
+  it('supports the OpenAPI 3 components.schemas shape', async () => {
+    const openapi = { components: { schemas: { customers: { properties: { name: { type: 'string' } } } } } }
+    const schema = await introspectSupabaseTable(opts(fetchFor({ openapi })))
+    expect(schema?.fields.map((f) => f.field)).toEqual(['name'])
+  })
+
+  it('falls back to the CSV header for an empty table when OpenAPI is blocked', async () => {
+    // OpenAPI 404 (CORS/blocked), sample empty, CSV header present.
+    const schema = await introspectSupabaseTable(
+      opts(fetchFor({ openapiStatus: 404, sample: [], csv: 'id,Name\n' })),
+    )
+    expect(schema?.fields.map((f) => f.field)).toEqual(['id', 'Name'])
+    expect(schema?.idField).toBe('id')
+  })
+
+  it('falls back to a sample row when OpenAPI is blocked and the table has data', async () => {
+    const schema = await introspectSupabaseTable(
+      opts(fetchFor({ openapiStatus: 404, sample: [{ id: 1, name: 'Ada', active: true }] })),
+    )
+    expect(schema?.fields.map((f) => [f.field, f.type])).toEqual([
+      ['id', 'number'], ['name', 'text'], ['active', 'boolean'],
+    ])
+  })
+
+  it('returns null when nothing can determine the columns', async () => {
+    const schema = await introspectSupabaseTable(opts(fetchFor({ openapiStatus: 404, sample: [], csv: '' })))
+    expect(schema).toBeNull()
+  })
+})

package/src/sources/introspect-supabase.ts

@@ -0,0 +1,119 @@
+/**
+ * Browser-side introspection for Supabase / PostgREST. Discovers a table's
+ * columns from the REST API alone (URL + anon key), so a screen can adapt to an
+ * arbitrary table with no server. Tries the most informative source first:
+ *
+ *   1. OpenAPI doc   - names + types + primary key (best; sometimes CORS-blocked)
+ *   2. CSV header    - names only, but works on an EMPTY table and is CORS-safe
+ *   3. sample row    - names + types inferred from one row of data
+ *
+ * Returns null when none of them can determine the columns (e.g. an empty table
+ * whose OpenAPI is blocked) - the caller can then ask the user to list columns.
+ */
+import type { RowData } from '@svgrid/grid'
+import type { EntityFieldType, EntitySchema } from '../schema'
+import { buildEntitySchema, type IntrospectedColumn } from './schema-from-columns'
+
+export type IntrospectSupabaseOptions = {
+  /** Project URL, e.g. `https://xxxx.supabase.co`. */
+  url: string
+  /** anon public key. */
+  key: string
+  table: string
+  /** Custom fetch (SSR, tests). Defaults to the global `fetch`. */
+  fetch?: typeof fetch
+}
+
+const mapOpenApiType = (prop: { type?: string; enum?: unknown }): EntityFieldType => {
+  if (Array.isArray(prop.enum)) return 'enum'
+  if (prop.type === 'integer' || prop.type === 'number') return 'number'
+  if (prop.type === 'boolean') return 'boolean'
+  return 'text'
+}
+
+async function viaOpenApi(o: Required<IntrospectSupabaseOptions>, base: string): Promise<IntrospectedColumn[] | null> {
+  let res: Response
+  try {
+    res = await o.fetch(`${base}/rest/v1/`, {
+      headers: { apikey: o.key, Authorization: `Bearer ${o.key}`, Accept: 'application/json' },
+    })
+  } catch {
+    return null // network / CORS - let another path try
+  }
+  if (!res.ok) return null
+  let spec: any
+  try { spec = await res.json() } catch { return null }
+
+  const defs: Record<string, any> = spec?.definitions ?? spec?.components?.schemas ?? {}
+  let def = defs[o.table]
+  if (!def) {
+    const key = Object.keys(defs).find((k) => k.toLowerCase() === o.table.toLowerCase())
+    if (key) def = defs[key]
+  }
+  const props = def?.properties
+  if (!props || !Object.keys(props).length) return null
+
+  const required: string[] = Array.isArray(def.required) ? def.required : []
+  return Object.entries<any>(props).map(([name, prop]) => {
+    const desc: string = prop?.description ?? ''
+    // PostgREST annotates a foreign key in the column description:
+    // "...<fk table='companies' column='id'/>"
+    const fk = /<fk\s+table=['"]([^'"]+)['"]\s+column=['"]([^'"]+)['"]/i.exec(desc)
+    return {
+      name,
+      type: mapOpenApiType(prop),
+      primaryKey: /primary key|<pk\/>/i.test(desc),
+      required: required.includes(name),
+      enumValues: Array.isArray(prop?.enum) ? (prop.enum as string[]) : undefined,
+      references: fk ? { table: fk[1]!, column: fk[2]! } : undefined,
+    }
+  })
+}
+
+async function viaCsv(o: Required<IntrospectSupabaseOptions>, base: string): Promise<IntrospectedColumn[] | null> {
+  let res: Response
+  try {
+    res = await o.fetch(`${base}/rest/v1/${encodeURIComponent(o.table)}?select=*&limit=1`, {
+      headers: { apikey: o.key, Authorization: `Bearer ${o.key}`, Accept: 'text/csv' },
+    })
+  } catch {
+    return null
+  }
+  if (!res.ok) return null
+  const text = (await res.text()).trim()
+  const header = text.split(/\r?\n/)[0] ?? ''
+  const names = header.split(',').map((h) => h.trim().replace(/^"|"$/g, '')).filter(Boolean)
+  return names.length ? names.map((name) => ({ name })) : null
+}
+
+async function viaSample(o: Required<IntrospectSupabaseOptions>, base: string): Promise<IntrospectedColumn[] | null> {
+  let res: Response
+  try {
+    res = await o.fetch(`${base}/rest/v1/${encodeURIComponent(o.table)}?select=*&limit=1`, {
+      headers: { apikey: o.key, Authorization: `Bearer ${o.key}`, Accept: 'application/json' },
+    })
+  } catch {
+    return null
+  }
+  if (!res.ok) return null
+  let rows: any
+  try { rows = await res.json() } catch { return null }
+  const sample = Array.isArray(rows) ? rows[0] : undefined
+  if (!sample) return null
+  return Object.entries(sample).map(([name, v]) => ({
+    name,
+    type: (typeof v === 'number' ? 'number' : typeof v === 'boolean' ? 'boolean' : 'text') as EntityFieldType,
+  }))
+}
+
+/** Introspect a Supabase/PostgREST table into an EntitySchema, or null. */
+export async function introspectSupabaseTable<TData extends RowData = RowData>(
+  options: IntrospectSupabaseOptions,
+): Promise<EntitySchema<TData> | null> {
+  const o: Required<IntrospectSupabaseOptions> = { fetch: globalThis.fetch, ...options }
+  const base = o.url.replace(/\/+$/, '')
+  const columns =
+    (await viaOpenApi(o, base)) ?? (await viaSample(o, base)) ?? (await viaCsv(o, base))
+  if (!columns || !columns.length) return null
+  return buildEntitySchema<TData>(o.table, columns)
+}