@svgrid/enterprise 2.5.2 → 2.6.0

package/dist/scheduler-summary.js

@@ -0,0 +1,54 @@
+/**
+ * scheduler-summary - the pure core behind Scheduler Pro's *per-time-column
+ * summary* strip (counts / sums / a custom roll-up aligned to the timeline axis).
+ * No Svelte, no DOM. Each event is clipped to the column it falls in before the
+ * reducer runs, so duration-based reducers (busy minutes) are per-column.
+ */
+const MS_MIN = 60000;
+function overlaps(aStart, aEnd, bStart, bEnd) {
+    return aStart.getTime() < bEnd.getTime() && aEnd.getTime() > bStart.getTime();
+}
+/**
+ * One summary value per column. For each column, collect the events overlapping
+ * it, clip each to the column bounds, then apply `reducer`. Empty columns yield
+ * `0` for `count` / `sum` and `reducer([])` for the function form.
+ */
+export function columnSummaries(events, columns, reducer, opts) {
+    return columns.map((col) => {
+        const items = [];
+        for (const e of events) {
+            const s = opts.startOf(e);
+            const en = opts.endOf(e);
+            if (!overlaps(s, en, col.start, col.end))
+                continue;
+            items.push({
+                row: opts.rowOf(e),
+                start: new Date(Math.max(s.getTime(), col.start.getTime())),
+                end: new Date(Math.min(en.getTime(), col.end.getTime())),
+            });
+        }
+        if (reducer === 'count')
+            return items.length;
+        if (typeof reducer === 'function')
+            return reducer(items);
+        // { sum: field }
+        const field = reducer.sum;
+        let total = 0;
+        for (const it of items) {
+            const v = it.row[field];
+            if (typeof v === 'number' && Number.isFinite(v))
+                total += v;
+        }
+        return total;
+    });
+}
+/** Built-in reducer: sum a numeric row field. */
+export function sumReducer(field) {
+    return { sum: field };
+}
+/** Built-in reducer: count events. */
+export const countReducer = 'count';
+/** Built-in reducer: total column-clipped busy minutes across the column's events. */
+export function busyMinutesReducer() {
+    return (items) => items.reduce((sum, it) => sum + (it.end.getTime() - it.start.getTime()) / MS_MIN, 0);
+}

package/dist/scheduler.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Register the Enterprise scheduler view. Idempotent - safe to call from every
+ * component that uses `scheduler`, or once at app start. Also invoked by
+ * {@link installEnterprise} so wiring the Pro API turns the view on too.
+ */
+export declare function enableSchedulerView(): void;
+export { default as SvGridScheduler } from './SvGridScheduler.svelte';

package/{src/scheduler.ts → dist/scheduler.js}

@@ -15,23 +15,22 @@
  * // then: <SvGrid {data} {columns} scheduler={{ startField: 'start', endField: 'end' }} />
  * ```
  */
-import { registerSchedulerView } from '@svgrid/grid'
-import { isLicenseKeySet } from './license'
-import { emitUnlicensedNudge } from './watermark'
-import SvGridScheduler from './SvGridScheduler.svelte'
-
-let enabled = false
-
+import { registerSchedulerView } from '@svgrid/grid';
+import { isLicenseKeySet } from './license';
+import { emitUnlicensedNudge } from './watermark';
+import SvGridScheduler from './SvGridScheduler.svelte';
+let enabled = false;
 /**
  * Register the Enterprise scheduler view. Idempotent - safe to call from every
  * component that uses `scheduler`, or once at app start. Also invoked by
  * {@link installEnterprise} so wiring the Pro API turns the view on too.
  */
-export function enableSchedulerView(): void {
-  if (enabled) return
-  enabled = true
-  registerSchedulerView(SvGridScheduler as never)
-  if (!isLicenseKeySet()) emitUnlicensedNudge()
+export function enableSchedulerView() {
+    if (enabled)
+        return;
+    enabled = true;
+    registerSchedulerView(SvGridScheduler);
+    if (!isLicenseKeySet())
+        emitUnlicensedNudge();
 }
-
-export { default as SvGridScheduler } from './SvGridScheduler.svelte'
+export { default as SvGridScheduler } from './SvGridScheduler.svelte';

package/dist/scheduling.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Scheduling - client-side, cron-driven automation for grid actions.
+ *
+ * Two everyday jobs that normally need a backend job runner - "email me this
+ * report every weekday at 17:30" and "remind the desk at 09:00 to reconcile" -
+ * are, in a long-lived data app, just a timer plus an action you already have:
+ * an export (`api.exportCsv` / `@svgrid/enterprise` Excel/PDF) or an alert
+ * (`toast`). This module supplies the missing middle: a pure cron matcher and a
+ * small runtime that fires your callback when a schedule comes due.
+ *
+ * Everything here is pure and injectable (`now`), so the matching logic is
+ * unit-testable without wall-clock flakiness, and the render/app layer just
+ * wires `onFire` to whatever action it wants.
+ *
+ * ```ts
+ * import { createScheduler } from '@svgrid/enterprise'
+ * import { toast } from '@svgrid/grid'
+ *
+ * const scheduler = createScheduler({
+ *   schedules: [
+ *     { id: 'eod', name: 'End-of-day CSV', cron: '30 17 * * 1-5' },
+ *     { id: 'standup', name: 'Stand-up reminder', cron: '0 9 * * *' },
+ *   ],
+ *   onFire(schedule) {
+ *     if (schedule.id === 'eod') api.exportCsv({ filename: 'eod' })
+ *     else toast.info(`${schedule.name}`)
+ *   },
+ * })
+ * scheduler.start()   // stop() on teardown
+ * ```
+ *
+ * Caveat, by design: schedules run entirely in the browser tab, so the app has
+ * to be open when a schedule is due. Pair with a server job for guaranteed
+ * delivery; use this for the far more common "the dashboard is always up on the
+ * wall" case where a backend cron is overkill.
+ */
+/** A field in the range [min, max] that a parsed cron sub-expression matches. */
+type CronField = {
+    min: number;
+    max: number;
+    match: (n: number) => boolean;
+};
+export type Schedule = {
+    /** Stable id - used to dedupe fires and to key your `onFire` switch. */
+    id: string;
+    /** Human label shown in a schedules panel / toast. */
+    name?: string;
+    /**
+     * Recurring trigger: a standard 5-field cron expression
+     * `"minute hour day-of-month month day-of-week"`. Ignored when `runAt` is set.
+     * Supports `*`, lists (`1,15`), ranges (`1-5`), and steps (`*​/15`, `9-17/2`).
+     * Day-of-week is `0-6` with Sunday `0` (`7` also accepted for Sunday).
+     */
+    cron?: string;
+    /**
+     * One-off trigger: an ISO datetime string. Fires a single time when the
+     * wall clock reaches that minute, then never again. Takes precedence over
+     * `cron` when both are present.
+     */
+    runAt?: string;
+    /** Set `false` to keep the definition but stop it firing. Default `true`. */
+    enabled?: boolean;
+};
+type ParsedCron = {
+    minute: CronField;
+    hour: CronField;
+    dom: CronField;
+    month: CronField;
+    dow: CronField;
+    /** True when BOTH day-of-month and day-of-week are restricted (not `*`). */
+    domAndDowRestricted: boolean;
+};
+/**
+ * Parse a 5-field cron expression. Throws on the wrong field count or an
+ * unparseable field, so a bad schedule surfaces at setup, not silently at 3am.
+ */
+export declare function parseCron(expr: string): ParsedCron;
+/** Whether a parsed cron matches a specific `Date` to the minute. */
+export declare function cronMatchesParsed(parsed: ParsedCron, date: Date): boolean;
+/** Whether a cron expression matches a `Date` to the minute. */
+export declare function cronMatches(expr: string, date: Date): boolean;
+/** Whether a schedule is due to fire during the minute containing `date`. */
+export declare function isScheduleDue(schedule: Schedule, date: Date): boolean;
+/**
+ * The next `Date` (to the minute) at or after `from` that `schedule` fires,
+ * or `null` if it never will again (past one-off, or no match within a year).
+ * Handy for a "next run" column in a schedules panel.
+ */
+export declare function nextRun(schedule: Schedule, from: Date): Date | null;
+export type SchedulerOptions = {
+    /** The schedules to run. Read once per tick, so you may mutate the array. */
+    schedules: ReadonlyArray<Schedule>;
+    /** Called when a schedule comes due. Receives the schedule + the fire time. */
+    onFire: (schedule: Schedule, firedAt: Date) => void;
+    /**
+     * Clock source, injectable for tests. Default `() => new Date()`.
+     */
+    now?: () => Date;
+    /**
+     * How often to check, in ms. Default 30_000 (twice a minute) so a fire is
+     * never more than ~30s late; per-minute dedupe keeps it firing once.
+     */
+    intervalMs?: number;
+};
+export type Scheduler = {
+    /** Begin ticking. No-op if already started. */
+    start: () => void;
+    /** Stop ticking and clear the timer. */
+    stop: () => void;
+    /**
+     * Run one check against `at` (default now) and fire anything due. Exposed for
+     * tests and for a "run due now" button; the internal tick calls this too.
+     */
+    tick: (at?: Date) => void;
+    /** Upcoming fire time per schedule id, from `at` (default now). */
+    upcoming: (at?: Date) => Array<{
+        id: string;
+        at: Date | null;
+    }>;
+};
+/**
+ * A client-side scheduler: ticks on an interval, fires `onFire` for every
+ * schedule due in the current minute, and guarantees at most one fire per
+ * schedule per minute (and exactly one, ever, for a one-off).
+ */
+export declare function createScheduler(options: SchedulerOptions): Scheduler;
+/** A few common cron expressions, for docs, presets, and pickers. */
+export declare const CRON_PRESETS: ReadonlyArray<{
+    label: string;
+    cron: string;
+}>;
+export {};

package/dist/scheduling.js

@@ -0,0 +1,228 @@
+/**
+ * Scheduling - client-side, cron-driven automation for grid actions.
+ *
+ * Two everyday jobs that normally need a backend job runner - "email me this
+ * report every weekday at 17:30" and "remind the desk at 09:00 to reconcile" -
+ * are, in a long-lived data app, just a timer plus an action you already have:
+ * an export (`api.exportCsv` / `@svgrid/enterprise` Excel/PDF) or an alert
+ * (`toast`). This module supplies the missing middle: a pure cron matcher and a
+ * small runtime that fires your callback when a schedule comes due.
+ *
+ * Everything here is pure and injectable (`now`), so the matching logic is
+ * unit-testable without wall-clock flakiness, and the render/app layer just
+ * wires `onFire` to whatever action it wants.
+ *
+ * ```ts
+ * import { createScheduler } from '@svgrid/enterprise'
+ * import { toast } from '@svgrid/grid'
+ *
+ * const scheduler = createScheduler({
+ *   schedules: [
+ *     { id: 'eod', name: 'End-of-day CSV', cron: '30 17 * * 1-5' },
+ *     { id: 'standup', name: 'Stand-up reminder', cron: '0 9 * * *' },
+ *   ],
+ *   onFire(schedule) {
+ *     if (schedule.id === 'eod') api.exportCsv({ filename: 'eod' })
+ *     else toast.info(`${schedule.name}`)
+ *   },
+ * })
+ * scheduler.start()   // stop() on teardown
+ * ```
+ *
+ * Caveat, by design: schedules run entirely in the browser tab, so the app has
+ * to be open when a schedule is due. Pair with a server job for guaranteed
+ * delivery; use this for the far more common "the dashboard is always up on the
+ * wall" case where a backend cron is overkill.
+ */
+const RANGES = {
+    minute: [0, 59],
+    hour: [0, 23],
+    dom: [1, 31],
+    month: [1, 12],
+    dow: [0, 6],
+};
+/** Parse one cron field (e.g. `*​/15`, `1-5`, `0,30`) into a matcher. */
+function parseField(raw, min, max) {
+    const allowed = new Set();
+    for (const part of raw.split(',')) {
+        const [rangePart, stepPart] = part.split('/');
+        const step = stepPart ? parseInt(stepPart, 10) : 1;
+        if (!Number.isFinite(step) || step < 1) {
+            throw new Error(`Invalid cron step in "${raw}"`);
+        }
+        let lo;
+        let hi;
+        if (rangePart === '*' || rangePart === '') {
+            lo = min;
+            hi = max;
+        }
+        else if (rangePart.includes('-')) {
+            const [a, b] = rangePart.split('-');
+            lo = parseInt(a, 10);
+            hi = parseInt(b, 10);
+        }
+        else {
+            lo = parseInt(rangePart, 10);
+            hi = lo;
+        }
+        if (!Number.isFinite(lo) || !Number.isFinite(hi)) {
+            throw new Error(`Invalid cron field "${raw}"`);
+        }
+        for (let n = lo; n <= hi; n += step) {
+            if (n >= min && n <= max)
+                allowed.add(n);
+        }
+    }
+    return { min, max, match: (n) => allowed.has(n) };
+}
+/**
+ * Parse a 5-field cron expression. Throws on the wrong field count or an
+ * unparseable field, so a bad schedule surfaces at setup, not silently at 3am.
+ */
+export function parseCron(expr) {
+    const fields = expr.trim().split(/\s+/);
+    if (fields.length !== 5) {
+        throw new Error(`Cron needs 5 fields "min hour dom month dow", got ${fields.length}: "${expr}"`);
+    }
+    const [min, hour, dom, month, dow] = fields;
+    // Day-of-week 7 is an alias for Sunday (0); normalize before parsing.
+    const dowNorm = dow.replace(/7/g, '0');
+    return {
+        minute: parseField(min, ...RANGES.minute),
+        hour: parseField(hour, ...RANGES.hour),
+        dom: parseField(dom, ...RANGES.dom),
+        month: parseField(month, ...RANGES.month),
+        dow: parseField(dowNorm, ...RANGES.dow),
+        domAndDowRestricted: dom !== '*' && dow !== '*',
+    };
+}
+/** Whether a parsed cron matches a specific `Date` to the minute. */
+export function cronMatchesParsed(parsed, date) {
+    if (!parsed.minute.match(date.getMinutes()))
+        return false;
+    if (!parsed.hour.match(date.getHours()))
+        return false;
+    if (!parsed.month.match(date.getMonth() + 1))
+        return false;
+    const domOk = parsed.dom.match(date.getDate());
+    const dowOk = parsed.dow.match(date.getDay());
+    // Standard cron semantics: when both day fields are restricted the match is
+    // the UNION (fires if either matches); otherwise plain AND.
+    return parsed.domAndDowRestricted ? domOk || dowOk : domOk && dowOk;
+}
+/** Whether a cron expression matches a `Date` to the minute. */
+export function cronMatches(expr, date) {
+    return cronMatchesParsed(parseCron(expr), date);
+}
+/** Two dates fall in the same wall-clock minute. */
+function sameMinute(a, b) {
+    return (a.getFullYear() === b.getFullYear() &&
+        a.getMonth() === b.getMonth() &&
+        a.getDate() === b.getDate() &&
+        a.getHours() === b.getHours() &&
+        a.getMinutes() === b.getMinutes());
+}
+/** Whether a schedule is due to fire during the minute containing `date`. */
+export function isScheduleDue(schedule, date) {
+    if (schedule.enabled === false)
+        return false;
+    if (schedule.runAt) {
+        const at = new Date(schedule.runAt);
+        return !Number.isNaN(at.getTime()) && sameMinute(at, date);
+    }
+    if (schedule.cron)
+        return cronMatches(schedule.cron, date);
+    return false;
+}
+/**
+ * The next `Date` (to the minute) at or after `from` that `schedule` fires,
+ * or `null` if it never will again (past one-off, or no match within a year).
+ * Handy for a "next run" column in a schedules panel.
+ */
+export function nextRun(schedule, from) {
+    if (schedule.enabled === false)
+        return null;
+    if (schedule.runAt) {
+        const at = new Date(schedule.runAt);
+        if (Number.isNaN(at.getTime()))
+            return null;
+        // Compare at minute granularity - a runAt in the current minute is "now".
+        const floor = new Date(from);
+        floor.setSeconds(0, 0);
+        return at.getTime() >= floor.getTime() ? at : null;
+    }
+    if (!schedule.cron)
+        return null;
+    const parsed = parseCron(schedule.cron);
+    const cursor = new Date(from);
+    cursor.setSeconds(0, 0);
+    // Scan minute-by-minute for up to ~366 days (527040 minutes).
+    for (let i = 0; i < 527040; i += 1) {
+        if (cronMatchesParsed(parsed, cursor))
+            return new Date(cursor);
+        cursor.setMinutes(cursor.getMinutes() + 1);
+    }
+    return null;
+}
+/**
+ * A client-side scheduler: ticks on an interval, fires `onFire` for every
+ * schedule due in the current minute, and guarantees at most one fire per
+ * schedule per minute (and exactly one, ever, for a one-off).
+ */
+export function createScheduler(options) {
+    const now = options.now ?? (() => new Date());
+    const intervalMs = options.intervalMs ?? 30000;
+    // Per-schedule guard: the minute-key we last fired, so a twice-a-minute tick
+    // (or a manual tick) never double-fires the same minute. One-offs are marked
+    // done so they never fire again even across minutes.
+    const lastFiredKey = new Map();
+    const oneOffDone = new Set();
+    let timer = null;
+    const minuteKey = (d) => `${d.getFullYear()}-${d.getMonth()}-${d.getDate()}-${d.getHours()}-${d.getMinutes()}`;
+    function tick(at = now()) {
+        const key = minuteKey(at);
+        for (const schedule of options.schedules) {
+            if (schedule.enabled === false)
+                continue;
+            const oneOff = !!schedule.runAt;
+            if (oneOff && oneOffDone.has(schedule.id))
+                continue;
+            if (lastFiredKey.get(schedule.id) === key)
+                continue;
+            if (!isScheduleDue(schedule, at))
+                continue;
+            lastFiredKey.set(schedule.id, key);
+            if (oneOff)
+                oneOffDone.add(schedule.id);
+            options.onFire(schedule, at);
+        }
+    }
+    return {
+        start() {
+            if (timer != null)
+                return;
+            timer = setInterval(() => tick(), intervalMs);
+        },
+        stop() {
+            if (timer != null) {
+                clearInterval(timer);
+                timer = null;
+            }
+        },
+        tick,
+        upcoming(at = now()) {
+            return options.schedules.map((s) => ({ id: s.id, at: nextRun(s, at) }));
+        },
+    };
+}
+/** A few common cron expressions, for docs, presets, and pickers. */
+export const CRON_PRESETS = [
+    { label: 'Every minute', cron: '* * * * *' },
+    { label: 'Every 15 minutes', cron: '*/15 * * * *' },
+    { label: 'Hourly, on the hour', cron: '0 * * * *' },
+    { label: 'Every weekday at 09:00', cron: '0 9 * * 1-5' },
+    { label: 'Weekdays at 17:30', cron: '30 17 * * 1-5' },
+    { label: 'Daily at midnight', cron: '0 0 * * *' },
+    { label: 'Monday mornings at 08:00', cron: '0 8 * * 1' },
+    { label: 'First of the month at 06:00', cron: '0 6 1 * *' },
+];

package/dist/schema-designer.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Schema-designer logic. The testable core behind `SvSchemaDesigner.svelte`:
+ * immutable operations that edit an `EntitySchema` (add / remove / reorder /
+ * retype fields, set the primary key), validation of the schema being designed,
+ * and sample-row generation for the live grid preview.
+ *
+ * Pure (no Svelte, no DOM), mirroring the pivot-designer / edit-panel split.
+ * Every mutation returns a NEW schema so Svelte reactivity and undo stay simple.
+ */
+import type { EntityField, EntityFieldType, EntitySchema } from './schema';
+/** All field types the designer offers, in menu order. */
+export declare const FIELD_TYPES: ReadonlyArray<EntityFieldType>;
+/** A fresh field with a name unique within the schema. */
+export declare function blankField(schema: EntitySchema): EntityField;
+/** Append a field (a blank one when none is given). */
+export declare function addField(schema: EntitySchema, field?: EntityField): EntitySchema;
+/** Remove a field by name. Clears `idField` if it pointed at the removed field. */
+export declare function removeField(schema: EntitySchema, fieldName: string): EntitySchema;
+/**
+ * Patch a field by name. Setting `primaryKey: true` clears it on every other
+ * field (a schema has at most one). Switching `type` drops now-irrelevant
+ * `options` (leaving enum) / `relation` (leaving relation).
+ */
+export declare function updateField(schema: EntitySchema, fieldName: string, patch: Partial<EntityField>): EntitySchema;
+/** Move a field one slot up (`-1`) or down (`+1`). No-op at the ends. */
+export declare function moveField(schema: EntitySchema, fieldName: string, dir: -1 | 1): EntitySchema;
+export type SchemaIssueLevel = 'error' | 'warning';
+export type SchemaIssue = {
+    level: SchemaIssueLevel;
+    message: string;
+    field?: string;
+};
+/**
+ * Validate the schema under construction. Errors block code generation;
+ * warnings are advisory. Covers: at least one field, unique field names, a
+ * resolvable primary key, enums with options, and complete relations.
+ */
+export declare function validateSchema(schema: EntitySchema): SchemaIssue[];
+/** True when the schema has no error-level issues (warnings are allowed). */
+export declare function isSchemaValid(schema: EntitySchema): boolean;
+/** Deterministic, realistic sample rows for the designer's grid preview. */
+export declare function sampleRows(schema: EntitySchema, count?: number): Array<Record<string, unknown>>;

package/dist/schema-designer.js

@@ -0,0 +1,117 @@
+import { resolveIdField } from './schema';
+import { generateRows } from './studio/sample-data';
+/** All field types the designer offers, in menu order. */
+export const FIELD_TYPES = [
+    'text',
+    'number',
+    'boolean',
+    'date',
+    'dateString',
+    'datetime',
+    'enum',
+    'relation',
+    'json',
+];
+/** A fresh field with a name unique within the schema. */
+export function blankField(schema) {
+    const taken = new Set(schema.fields.map((f) => f.field));
+    let n = schema.fields.length + 1;
+    let name = `field${n}`;
+    while (taken.has(name))
+        name = `field${++n}`;
+    return { field: name, type: 'text' };
+}
+/** Append a field (a blank one when none is given). */
+export function addField(schema, field) {
+    return { ...schema, fields: [...schema.fields, field ?? blankField(schema)] };
+}
+/** Remove a field by name. Clears `idField` if it pointed at the removed field. */
+export function removeField(schema, fieldName) {
+    const fields = schema.fields.filter((f) => f.field !== fieldName);
+    const idField = schema.idField === fieldName ? undefined : schema.idField;
+    return { ...schema, fields, idField };
+}
+/**
+ * Patch a field by name. Setting `primaryKey: true` clears it on every other
+ * field (a schema has at most one). Switching `type` drops now-irrelevant
+ * `options` (leaving enum) / `relation` (leaving relation).
+ */
+export function updateField(schema, fieldName, patch) {
+    const makesPrimary = patch.primaryKey === true;
+    const fields = schema.fields.map((f) => {
+        if (f.field !== fieldName) {
+            return makesPrimary && f.primaryKey ? { ...f, primaryKey: false } : f;
+        }
+        const next = { ...f, ...patch };
+        if (patch.type && patch.type !== f.type) {
+            if (patch.type !== 'enum')
+                delete next.options;
+            if (patch.type !== 'relation')
+                delete next.relation;
+        }
+        return next;
+    });
+    return { ...schema, fields };
+}
+/** Move a field one slot up (`-1`) or down (`+1`). No-op at the ends. */
+export function moveField(schema, fieldName, dir) {
+    const i = schema.fields.findIndex((f) => f.field === fieldName);
+    const j = i + dir;
+    if (i < 0 || j < 0 || j >= schema.fields.length)
+        return schema;
+    const fields = [...schema.fields];
+    const a = fields[i];
+    const b = fields[j];
+    fields[i] = b;
+    fields[j] = a;
+    return { ...schema, fields };
+}
+/**
+ * Validate the schema under construction. Errors block code generation;
+ * warnings are advisory. Covers: at least one field, unique field names, a
+ * resolvable primary key, enums with options, and complete relations.
+ */
+export function validateSchema(schema) {
+    const issues = [];
+    if (schema.fields.length === 0) {
+        issues.push({ level: 'error', message: 'Add at least one field.' });
+    }
+    const seen = new Set();
+    for (const f of schema.fields) {
+        if (!f.field.trim()) {
+            issues.push({ level: 'error', message: 'A field has an empty name.' });
+        }
+        else if (seen.has(f.field)) {
+            issues.push({ level: 'error', message: `Duplicate field name "${f.field}".`, field: f.field });
+        }
+        seen.add(f.field);
+        if (f.type === 'enum' && (!f.options || f.options.length === 0)) {
+            issues.push({ level: 'warning', message: `Enum "${f.field}" has no options.`, field: f.field });
+        }
+        if (f.type === 'relation' && (!f.relation?.entity || !f.relation?.labelField)) {
+            issues.push({
+                level: 'warning',
+                message: `Relation "${f.field}" needs a related entity and label field.`,
+                field: f.field,
+            });
+        }
+    }
+    try {
+        resolveIdField(schema);
+    }
+    catch {
+        issues.push({
+            level: 'error',
+            message: 'No primary key: flag a field as primary key, set idField, or name a field "id".',
+        });
+    }
+    return issues;
+}
+/** True when the schema has no error-level issues (warnings are allowed). */
+export function isSchemaValid(schema) {
+    return !validateSchema(schema).some((i) => i.level === 'error');
+}
+/** Deterministic, realistic sample rows for the designer's grid preview. */
+export function sampleRows(schema, count = 3) {
+    return generateRows(schema.fields, count);
+}