@svgrid/enterprise 2.5.3 → 2.6.1

package/dist/sources/index.js

@@ -0,0 +1,18 @@
+/**
+ * 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 } from './filters';
+export { buildEntitySchema, pickLabelField, linkRelationLabels, } from './schema-from-columns';
+export { createSupabaseDataSource } from './supabase';
+export { createRestDataSource } from './rest';
+export { offsetLimitAdapter, dummyJsonAdapter, jsonServerAdapter, } from './rest-adapters';
+export { introspectSupabaseTable, listSupabaseTables } from './introspect-supabase';
+export { createSupabaseRealtime, } from './realtime-supabase';
+export { createRelationLookup, } from './relation-lookup';
+export { createSupabaseAuth, } from './auth-supabase';
+export { aggregateRows, chartFieldsFromSchema, } from './aggregate';
+export { withEntityRules } from './with-entity-rules';
+export { withRelationLabels } from './with-relation-labels';
+export { reduceValue, kpiSeries, sparklinePoints, seriesDelta, formatKpiValue, dashboardFromSchema, } from './dashboard';

package/dist/sources/introspect-supabase.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 { EntitySchema } from '../schema.js';
+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;
+};
+/** List a Supabase project's tables from its PostgREST OpenAPI doc (URL + anon key).
+ *  Returns the exposed table names (sorted), or `[]` when the doc can't be read
+ *  (CORS-blocked, bad key). Lets the Studio wizard offer a table picker instead of
+ *  making the user hand-type the table name. */
+export declare function listSupabaseTables(url: string, key: string, fetchFn?: typeof fetch): Promise<string[]>;
+/** Introspect a Supabase/PostgREST table into an EntitySchema, or null. */
+export declare function introspectSupabaseTable<TData extends RowData = RowData>(options: IntrospectSupabaseOptions): Promise<EntitySchema<TData> | null>;

package/dist/sources/introspect-supabase.js

@@ -0,0 +1,134 @@
+import { buildEntitySchema } from './schema-from-columns.js';
+const mapOpenApiType = (prop) => {
+    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, base) {
+    let res;
+    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;
+    try {
+        spec = await res.json();
+    }
+    catch {
+        return null;
+    }
+    const defs = 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 = Array.isArray(def.required) ? def.required : [];
+    return Object.entries(props).map(([name, prop]) => {
+        const desc = 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 : undefined,
+            references: fk ? { table: fk[1], column: fk[2] } : undefined,
+        };
+    });
+}
+async function viaCsv(o, base) {
+    let res;
+    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, base) {
+    let res;
+    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;
+    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'),
+    }));
+}
+/** List a Supabase project's tables from its PostgREST OpenAPI doc (URL + anon key).
+ *  Returns the exposed table names (sorted), or `[]` when the doc can't be read
+ *  (CORS-blocked, bad key). Lets the Studio wizard offer a table picker instead of
+ *  making the user hand-type the table name. */
+export async function listSupabaseTables(url, key, fetchFn = globalThis.fetch) {
+    const base = url.replace(/\/+$/, '');
+    let res;
+    try {
+        res = await fetchFn(`${base}/rest/v1/`, { headers: { apikey: key, Authorization: `Bearer ${key}`, Accept: 'application/json' } });
+    }
+    catch {
+        return [];
+    }
+    if (!res.ok)
+        return [];
+    let spec;
+    try {
+        spec = await res.json();
+    }
+    catch {
+        return [];
+    }
+    const defs = spec?.definitions ?? spec?.components?.schemas ?? {};
+    // PostgREST also lists RPCs under `paths` as `/rpc/...`; `definitions` are the tables/views.
+    return Object.keys(defs).sort((a, b) => a.localeCompare(b));
+}
+/** Introspect a Supabase/PostgREST table into an EntitySchema, or null. */
+export async function introspectSupabaseTable(options) {
+    const o = { 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(o.table, columns);
+}

package/dist/sources/realtime-supabase.d.ts

@@ -0,0 +1,37 @@
+/** A normalized change event. `new` is the row after the change (INSERT/UPDATE); `old` its prior identity (UPDATE/DELETE). */
+export type RealtimeChange<TData> = {
+    type: 'INSERT' | 'UPDATE' | 'DELETE';
+    new: TData | null;
+    old: Partial<TData> | null;
+};
+/** The slice of a `supabase-js` client + channel this needs. */
+export type RealtimeChannelLike = {
+    on(type: 'postgres_changes', filter: Record<string, unknown>, cb: (payload: any) => void): RealtimeChannelLike;
+    subscribe(cb?: (status: string) => void): RealtimeChannelLike;
+};
+export type SupabaseRealtimeClientLike = {
+    channel(name: string): RealtimeChannelLike;
+    removeChannel(channel: RealtimeChannelLike): void;
+};
+export type SupabaseRealtimeConfig<TData> = {
+    client: SupabaseRealtimeClientLike;
+    table: string;
+    /** Postgres schema. Default `'public'`. */
+    schema?: string;
+    /** Only these events. Default `'*'` (all). */
+    event?: 'INSERT' | 'UPDATE' | 'DELETE' | '*';
+    /** PostgREST-style row filter, e.g. `'tier=eq.pro'`. */
+    filter?: string;
+    /** Unique channel name. Default `svgrid:{schema}:{table}`. */
+    channelName?: string;
+    /** Coalesce bursts: call `onChange` at most once per this window (trailing). */
+    debounceMs?: number;
+    /** Called for each change (or the last of a debounced burst). */
+    onChange: (change: RealtimeChange<TData>) => void;
+    /** Subscription status callback (`SUBSCRIBED`, `CHANNEL_ERROR`, ...). */
+    onStatus?: (status: string) => void;
+};
+export type SupabaseRealtimeHandle = {
+    unsubscribe(): void;
+};
+export declare function createSupabaseRealtime<TData = Record<string, unknown>>(config: SupabaseRealtimeConfig<TData>): SupabaseRealtimeHandle;

package/dist/sources/realtime-supabase.js

@@ -0,0 +1,52 @@
+/**
+ * createSupabaseRealtime - live updates for a Studio screen via Supabase
+ * Realtime (Postgres change streams). Subscribe to a table's INSERT / UPDATE /
+ * DELETE events and react - typically by refreshing the current page so the grid
+ * stays in sync with the database, no polling.
+ *
+ *     const live = createSupabaseRealtime({
+ *       client, table: 'customers',
+ *       debounceMs: 200,
+ *       onChange: () => controller.refresh(),  // re-fetch the current page
+ *     })
+ *     // later: live.unsubscribe()
+ *
+ * You bring the same `supabase-js` client used for reads (BYO, no dependency).
+ * Because the server model is paged, the correct default is to `refresh()` on a
+ * change - that respects the active sort / filter / page. Use `debounceMs` to
+ * coalesce bursts into a single refetch. For per-row effects (e.g. flashing a
+ * changed row) read the normalized event passed to `onChange`.
+ */
+import { nudgeEnterprise } from '../license';
+export function createSupabaseRealtime(config) {
+    nudgeEnterprise('Studio'); // soft-gate; never blocks
+    const schema = config.schema ?? 'public';
+    const channelName = config.channelName ?? `svgrid:${schema}:${config.table}`;
+    let timer;
+    const emit = (change) => {
+        if (!config.debounceMs) {
+            config.onChange(change);
+            return;
+        }
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => config.onChange(change), config.debounceMs);
+    };
+    const channel = config.client
+        .channel(channelName)
+        .on('postgres_changes', { event: config.event ?? '*', schema, table: config.table, ...(config.filter ? { filter: config.filter } : {}) }, (payload) => {
+        emit({
+            type: payload.eventType,
+            new: (payload.new ?? null),
+            old: (payload.old ?? null),
+        });
+    })
+        .subscribe(config.onStatus);
+    return {
+        unsubscribe() {
+            if (timer)
+                clearTimeout(timer);
+            config.client.removeChannel(channel);
+        },
+    };
+}

package/dist/sources/relation-lookup.d.ts

@@ -0,0 +1,50 @@
+/**
+ * createRelationLookup - powers a foreign-key "lookup" field: search the related
+ * entity for options, and resolve a stored key back to its human label. It runs
+ * over the SAME `ServerDataSource` contract as everything else, so the related
+ * options can come from Supabase, REST, SQL, or in-memory - whatever backs the
+ * related table.
+ *
+ *     const companyLookup = createRelationLookup({
+ *       source: companiesSource,     // the related entity's ServerDataSource
+ *       schema: companiesSchema,     // resolves the related primary key
+ *       labelField: 'name',          // what the user sees
+ *     })
+ *     await companyLookup.search('acme')   // -> [{ value: '12', label: 'Acme Inc' }, ...]
+ *     await companyLookup.labelFor('12')   // -> 'Acme Inc'
+ *
+ * Pass it to `<SvGridEditPanel lookups={{ companyId: companyLookup }} />` and the
+ * `companyId` relation field renders a searchable picker instead of a raw input.
+ */
+import type { RowData, ServerDataSource } from '@svgrid/grid';
+import { type EntitySchema } from '../schema';
+export type RelationOption = {
+    value: string;
+    label: string;
+    row: RowData;
+};
+export type RelationLookup = {
+    /** Search the related entity (global search); returns a page of options. */
+    search(query: string): Promise<RelationOption[]>;
+    /** Resolve a stored key to its label (cached). Returns the key itself if not found. */
+    labelFor(value: unknown): Promise<string | null>;
+    /**
+     * Resolve many keys at once (cached), fetching only the misses in a SINGLE
+     * request (a set / `IN` filter) - avoids the N+1 of calling `labelFor` per
+     * row. Returns a `value -> label` map (unresolved keys map to themselves).
+     */
+    labelsFor(values: ReadonlyArray<unknown>): Promise<Map<string, string>>;
+};
+export type RelationLookupConfig<TRelated extends RowData> = {
+    /** The related entity's read source (only `getRows` is used). */
+    source: Pick<ServerDataSource<TRelated>, 'getRows'>;
+    /** Field on the related row shown to the user. */
+    labelField: string;
+    /** Related primary-key field. Default: resolved from `schema`, else `'id'`. */
+    valueField?: string;
+    /** Related schema, used to resolve the key when `valueField` is omitted. */
+    schema?: EntitySchema<TRelated>;
+    /** Options fetched per search. Default 20. */
+    pageSize?: number;
+};
+export declare function createRelationLookup<TRelated extends RowData>(config: RelationLookupConfig<TRelated>): RelationLookup;

package/dist/sources/relation-lookup.js

@@ -0,0 +1,77 @@
+import { resolveIdField } from '../schema';
+export function createRelationLookup(config) {
+    const pageSize = config.pageSize ?? 20;
+    const valueField = config.valueField ?? (config.schema ? resolveIdField(config.schema) : 'id');
+    const { labelField, source } = config;
+    const cache = new Map(); // value -> label
+    const toOption = (row) => {
+        const value = String(row[valueField] ?? '');
+        const label = String(row[labelField] ?? value);
+        cache.set(value, label);
+        return { value, label, row };
+    };
+    const request = (over) => ({
+        startRow: 0,
+        endRow: pageSize,
+        pageIndex: 0,
+        pageSize,
+        sortModel: [],
+        filterModel: {},
+        ...over,
+    });
+    return {
+        async search(query) {
+            const term = query.trim();
+            const { rows } = await source.getRows(request({ filterModel: term ? { global: term } : {} }));
+            return rows.map((r) => toOption(r));
+        },
+        async labelFor(value) {
+            if (value == null || value === '')
+                return null;
+            const key = String(value);
+            const cached = cache.get(key);
+            if (cached != null)
+                return cached;
+            const { rows } = await source.getRows(request({
+                endRow: 1,
+                pageSize: 1,
+                filterModel: { columns: { [valueField]: { operator: 'equals', value: key } } },
+            }));
+            const row = rows[0];
+            return row ? toOption(row).label : key;
+        },
+        async labelsFor(values) {
+            const result = new Map();
+            const missing = [];
+            for (const v of values) {
+                if (v == null || v === '')
+                    continue;
+                const key = String(v);
+                if (result.has(key))
+                    continue;
+                const cached = cache.get(key);
+                if (cached != null)
+                    result.set(key, cached);
+                else if (!missing.includes(key))
+                    missing.push(key);
+            }
+            if (missing.length > 0) {
+                // One request for every miss: a set (`IN`) filter on the key field.
+                const { rows } = await source.getRows(request({
+                    endRow: missing.length,
+                    pageSize: missing.length,
+                    filterModel: { columns: { [valueField]: { operator: 'in', value: '', selectedValues: missing } } },
+                }));
+                for (const row of rows) {
+                    const opt = toOption(row);
+                    result.set(opt.value, opt.label);
+                }
+                // Anything still unresolved maps to the key itself.
+                for (const key of missing)
+                    if (!result.has(key))
+                        result.set(key, key);
+            }
+            return result;
+        },
+    };
+}

package/dist/sources/rest-adapters.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Wire-format adapters for `createRestDataSource`. A public / third-party API
+ * rarely speaks our default `offset&limit&sort` dialect - it uses `skip`, or
+ * `page`, or `_start`, and wraps its rows under `products` / `data` / a bare
+ * array with an `X-Total-Count` header. An adapter is just the `{ buildQuery,
+ * parse }` pair that teaches the REST source that dialect:
+ *
+ *     createRestDataSource({ url: 'https://dummyjson.com/products',
+ *                            ...dummyJsonAdapter() })
+ *
+ * `offsetLimitAdapter` is the configurable base; `dummyJsonAdapter` and
+ * `jsonServerAdapter` are ready-made presets for two very common shapes.
+ */
+import type { RowData } from '@svgrid/grid';
+import type { RestDataSourceConfig } from './rest';
+/** The parts of a REST config that describe a backend's wire format. */
+export type RestAdapter<TData extends RowData> = Required<Pick<RestDataSourceConfig<TData>, 'buildQuery' | 'parse'>>;
+export type OffsetLimitOptions = {
+    /** Query param for the first-row offset (default `offset`). */
+    offsetParam?: string;
+    /** Query param for the page size (default `limit`). */
+    limitParam?: string;
+    /** If set, single-column sort emits `<sortByParam>=<col>` + `<orderParam>=asc|desc`. */
+    sortByParam?: string;
+    orderParam?: string;
+    /** If set, the global search term is sent as `<searchParam>=<term>`. */
+    searchParam?: string;
+    /** Response key holding the row array (tried in order; falls back to `data`/`rows`/`items`). */
+    rowsKey?: string;
+    /** Response key holding the total count (tried in order; falls back to `total`/`count`). */
+    totalKey?: string;
+};
+/**
+ * The `?offset=..&limit=..` family (Supabase-ish REST, DummyJSON with `skip`,
+ * many hand-rolled APIs). Configure the param names + response keys once.
+ */
+export declare function offsetLimitAdapter<TData extends RowData>(opts?: OffsetLimitOptions): RestAdapter<TData>;
+/**
+ * DummyJSON (`https://dummyjson.com/<collection>`): `skip`/`limit` paging,
+ * `sortBy`/`order` sort, rows under `products`* + a `total` field.
+ * (*`rowsKey` defaults to `products`; pass one for `users`, `posts`, etc.)
+ */
+export declare function dummyJsonAdapter<TData extends RowData>(rowsKey?: string): RestAdapter<TData>;
+/**
+ * `json-server` / JSONPlaceholder: `_start`/`_limit` paging, `_sort`/`_order`
+ * multi-column sort, a bare JSON array with the total in `X-Total-Count`.
+ */
+export declare function jsonServerAdapter<TData extends RowData>(): RestAdapter<TData>;

package/dist/sources/rest-adapters.js

@@ -0,0 +1,85 @@
+import { normalizeFilters } from './filters';
+const pick = (body, keys) => {
+    const b = (body ?? {});
+    for (const k of keys)
+        if (b[k] != null)
+            return b[k];
+    return undefined;
+};
+/**
+ * The `?offset=..&limit=..` family (Supabase-ish REST, DummyJSON with `skip`,
+ * many hand-rolled APIs). Configure the param names + response keys once.
+ */
+export function offsetLimitAdapter(opts = {}) {
+    const offsetParam = opts.offsetParam ?? 'offset';
+    const limitParam = opts.limitParam ?? 'limit';
+    const rowsKeys = [opts.rowsKey, 'data', 'rows', 'items'].filter(Boolean);
+    const totalKeys = [opts.totalKey, 'total', 'count', 'rowCount'].filter(Boolean);
+    return {
+        buildQuery(request) {
+            const params = {
+                [offsetParam]: String(request.startRow),
+                [limitParam]: String(request.endRow - request.startRow),
+            };
+            const first = request.sortModel[0];
+            if (opts.sortByParam && first) {
+                params[opts.sortByParam] = first.id;
+                if (opts.orderParam)
+                    params[opts.orderParam] = first.desc ? 'desc' : 'asc';
+            }
+            if (opts.searchParam) {
+                const { search } = normalizeFilters(request.filterModel);
+                if (search)
+                    params[opts.searchParam] = search;
+            }
+            return params;
+        },
+        parse(body) {
+            const rows = (pick(body, rowsKeys) ?? []);
+            const total = pick(body, totalKeys);
+            return { rows, rowCount: total != null ? Number(total) : rows.length };
+        },
+    };
+}
+/**
+ * DummyJSON (`https://dummyjson.com/<collection>`): `skip`/`limit` paging,
+ * `sortBy`/`order` sort, rows under `products`* + a `total` field.
+ * (*`rowsKey` defaults to `products`; pass one for `users`, `posts`, etc.)
+ */
+export function dummyJsonAdapter(rowsKey = 'products') {
+    return offsetLimitAdapter({
+        offsetParam: 'skip',
+        limitParam: 'limit',
+        sortByParam: 'sortBy',
+        orderParam: 'order',
+        rowsKey,
+        totalKey: 'total',
+    });
+}
+/**
+ * `json-server` / JSONPlaceholder: `_start`/`_limit` paging, `_sort`/`_order`
+ * multi-column sort, a bare JSON array with the total in `X-Total-Count`.
+ */
+export function jsonServerAdapter() {
+    return {
+        buildQuery(request) {
+            const params = {
+                _start: String(request.startRow),
+                _limit: String(request.endRow - request.startRow),
+            };
+            if (request.sortModel.length) {
+                params._sort = request.sortModel.map((s) => s.id).join(',');
+                params._order = request.sortModel.map((s) => (s.desc ? 'desc' : 'asc')).join(',');
+            }
+            const { search } = normalizeFilters(request.filterModel);
+            if (search)
+                params.q = search;
+            return params;
+        },
+        parse(body, response) {
+            const rows = Array.isArray(body) ? body : [];
+            const header = response.headers.get('x-total-count');
+            return { rows, rowCount: header != null ? Number(header) : rows.length };
+        },
+    };
+}

package/dist/sources/rest.d.ts

@@ -0,0 +1,38 @@
+/**
+ * createRestDataSource - a `ServerDataSource` over an HTTP/JSON API. Handles the
+ * request lifecycle and the four CRUD calls; you point it at a collection URL.
+ * The default request/response shaping suits a conventional REST endpoint, and
+ * every part is overridable (`buildQuery`, `parse`, `headers`, `fetch`) for
+ * bespoke or legacy APIs.
+ *
+ *     const source = createRestDataSource({ url: '/api/customers', schema })
+ *
+ * Default wire format:
+ *   read    GET    {url}?offset&limit&sort&search&<col>=<op>:<value>
+ *   create  POST   {url}                 body: the new row
+ *   update  PATCH  {url}/{id}            body: the patch
+ *   delete  DELETE {url}/{id}
+ * where `sort` is a comma list with `-` for descending (e.g. `-createdAt,name`).
+ */
+import type { RowData, ServerRequest, ServerResult } from '@svgrid/grid';
+import { type EntitySchema } from '../schema';
+import type { WritableDataSource } from '../sveltekit/types';
+export type RestDataSourceConfig<TData extends RowData> = {
+    /** Collection endpoint, e.g. `/api/customers`. */
+    url: string;
+    /** Used to resolve the id field for update/delete when `idField` is omitted. */
+    schema?: EntitySchema<TData>;
+    /** Primary key property (default: from `schema`, else `'id'`). */
+    idField?: string;
+    /** Custom fetch (SSR, auth). Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Extra request headers, static or computed per call. */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /** Static query params merged into every read (e.g. an API key or filter). */
+    query?: Record<string, string>;
+    /** Build read query params from the grid request. Override for bespoke APIs. */
+    buildQuery?: (request: ServerRequest) => Record<string, string>;
+    /** Parse a read response body into rows + total. Override for bespoke shapes. */
+    parse?: (body: unknown, response: Response) => ServerResult<TData>;
+};
+export declare function createRestDataSource<TData extends RowData>(config: RestDataSourceConfig<TData>): WritableDataSource<TData>;

package/dist/sources/rest.js

@@ -0,0 +1,86 @@
+import { resolveIdField } from '../schema';
+import { nudgeEnterprise } from '../license';
+import { normalizeFilters } from './filters';
+const encodePredicate = (p) => {
+    if (p.op === 'in')
+        return `in:${p.values.join(',')}`;
+    if (p.op === 'isNull')
+        return 'isNull';
+    if (p.op === 'between')
+        return `between:${p.value},${p.valueTo}`;
+    return `${p.op}:${p.value}`;
+};
+function defaultBuildQuery(request) {
+    const params = {
+        offset: String(request.startRow),
+        limit: String(request.endRow - request.startRow),
+    };
+    if (request.sortModel.length) {
+        params.sort = request.sortModel.map((s) => (s.desc ? '-' : '') + s.id).join(',');
+    }
+    const { predicates, search } = normalizeFilters(request.filterModel);
+    if (search)
+        params.search = search;
+    for (const p of predicates)
+        params[p.column] = encodePredicate(p);
+    return params;
+}
+function defaultParse(body, response) {
+    if (Array.isArray(body)) {
+        // Total from a Content-Range header (`items 0-9/240`) when present.
+        const range = response.headers.get('content-range');
+        const total = range && /\/(\d+)\s*$/.exec(range);
+        return { rows: body, rowCount: total ? Number(total[1]) : body.length };
+    }
+    const b = (body ?? {});
+    const rows = (b.rows ?? b.data ?? b.items ?? []);
+    const rowCount = Number(b.rowCount ?? b.total ?? b.count ?? rows.length);
+    return { rows, rowCount };
+}
+export function createRestDataSource(config) {
+    nudgeEnterprise('Studio'); // soft-gate; never blocks
+    const doFetch = config.fetch ?? globalThis.fetch;
+    const idField = config.idField ?? (config.schema ? resolveIdField(config.schema) : 'id');
+    const base = config.url.replace(/\/+$/, '');
+    const buildQuery = config.buildQuery ?? defaultBuildQuery;
+    const parse = config.parse ?? defaultParse;
+    const headers = (extra) => {
+        const h = typeof config.headers === 'function' ? config.headers() : (config.headers ?? {});
+        return { ...h, ...extra };
+    };
+    const send = async (url, init) => {
+        const res = await doFetch(url, init);
+        if (!res.ok)
+            throw new Error(`REST ${init?.method ?? 'GET'} ${url} -> ${res.status} ${res.statusText}`);
+        const parsed = res.status === 204 ? undefined : await res.json().catch(() => undefined);
+        return { body: parsed, res };
+    };
+    return {
+        async getRows(request) {
+            // Static `query` params first; the built paging/sort/filter params win on conflict.
+            const qs = new URLSearchParams({ ...config.query, ...buildQuery(request) }).toString();
+            const url = qs ? `${base}?${qs}` : base;
+            const { body, res } = (await send(url, { headers: headers() }));
+            return parse(body, res);
+        },
+        async createRow(input) {
+            const { body } = (await send(base, {
+                method: 'POST',
+                headers: headers({ 'content-type': 'application/json' }),
+                body: JSON.stringify(input),
+            }));
+            return (body ?? input);
+        },
+        async updateRow(id, patch) {
+            const { body } = (await send(`${base}/${encodeURIComponent(id)}`, {
+                method: 'PATCH',
+                headers: headers({ 'content-type': 'application/json' }),
+                body: JSON.stringify(patch),
+            }));
+            return (body ?? { ...patch, [idField]: id });
+        },
+        async deleteRow(id) {
+            await send(`${base}/${encodeURIComponent(id)}`, { method: 'DELETE', headers: headers() });
+        },
+    };
+}