@svgrid/enterprise 2.5.2 → 2.6.0

package/dist/designer/index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>SvGrid Studio - Designer</title>
-    <script type="module" crossorigin src="./assets/index-CM5xvaOy.js"></script>
+    <script type="module" crossorigin src="./assets/index-BF0UH638.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/rolldown-runtime-Dd_uD5pT.js">
     <link rel="modulepreload" crossorigin href="./assets/disclose-version-CIm4S9xS.js">
     <link rel="modulepreload" crossorigin href="./assets/export-format-DwjuTfrQ.js">
@@ -16,7 +16,7 @@
     <link rel="modulepreload" crossorigin href="./assets/easing-zaypKrr0.js">
     <link rel="modulepreload" crossorigin href="./assets/chart-DHEgt4lN.js">
     <link rel="modulepreload" crossorigin href="./assets/SvGridChart-BEDNTdc5.js">
-    <link rel="modulepreload" crossorigin href="./assets/src-D-ET9Mmo.js">
+    <link rel="modulepreload" crossorigin href="./assets/src-BPJruwB9.js">
     <link rel="modulepreload" crossorigin href="./assets/SvListBox-BVzVfCG3.js">
     <link rel="stylesheet" crossorigin href="./assets/dismissable-BF-9TJSd.css">
     <link rel="stylesheet" crossorigin href="./assets/SvDateTimePicker-Cygij-dr.css">

package/dist/edit-panel.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Edit-panel logic. The testable core behind `SvGridEditPanel.svelte`: build a
+ * form's initial values from a schema + row, resolve which control renders each
+ * field, validate the whole form, and produce the payload to submit through a
+ * `ServerController`'s `createRow` / `updateRow`. Keeping this pure (no Svelte,
+ * no DOM) mirrors the pivot designer split and lets it be unit-tested.
+ */
+import type { RowData } from '@svgrid/grid';
+import { type EntitySchema, type FormFieldDescriptor, type ValidationRuleSpec } from './schema.js';
+import type { PredicateExpr } from './expressions/expression-types.js';
+export type EditMode = 'create' | 'edit';
+/** The native control a field renders as. */
+export type ControlKind = 'text' | 'number' | 'date' | 'datetime' | 'time' | 'checkbox' | 'select' | 'textarea';
+/** Create mode when there's no row to edit, edit mode otherwise. */
+export declare function editMode<TData extends RowData>(row: TData | null | undefined): EditMode;
+/** Map a field's editor type to the control the panel renders. */
+export declare function controlKind(field: Pick<FormFieldDescriptor, 'editorType'>): ControlKind;
+/** A `Date` -> a **local** `yyyy-MM-dd` string (matches the native date input; no UTC shift). */
+export declare function toDateString(d: Date | null | undefined): string;
+/** A `Date` -> a **local** `yyyy-MM-ddTHH:mm` string (matches `datetime-local`; no UTC shift). */
+export declare function toDateTimeString(d: Date | null | undefined): string;
+/** Stored value -> `SvNumberInput.value` (number | null); non-numbers become null. */
+export declare function toNumberValue(raw: unknown): number | null;
+/** `SvNumberInput.onChange` payload -> stored value; null becomes '' (the empty convention). */
+export declare function fromNumberValue(v: number | null): number | '';
+/** Stored value -> `SvSlider.value`; falls back to `min` when unset. */
+export declare function toSliderValue(raw: unknown, min: number): number;
+/** Stored value -> `SvTagsInput.value` (string[]); splits a comma string, else wraps. */
+export declare function toTags(raw: unknown): string[];
+/**
+ * Built-in validation from the field's own constraints - number validity,
+ * min/max, length, email/url format, regex - so forms validate out of the box
+ * without any external library. Returns the first violation, or null.
+ */
+export declare function builtInError(field: FormFieldDescriptor, value: unknown): string | null;
+/** Whether a field is shown, editable, and demanded, for the current values. */
+export type FieldState = {
+    visible: boolean;
+    disabled: boolean;
+    required: boolean;
+};
+/**
+ * Resolve a field's live state from its `when` conditions. Read-only always
+ * wins over a `disabled` condition, and `when.required` replaces the static
+ * `required` flag rather than adding to it, so a rule can make a normally
+ * required field optional as well as the other way round.
+ */
+export declare function fieldState(field: FormFieldDescriptor, values: Record<string, unknown>): FieldState;
+/** Whether a form section's `visibleWhen` holds for the current values. */
+export declare function sectionVisible(expr: PredicateExpr, values: Record<string, unknown>): boolean;
+/** The fields the form currently shows, in order. */
+export declare function visibleFormFields<TData extends RowData>(schema: EntitySchema<TData>, values: Record<string, unknown>): FormFieldDescriptor[];
+/** True when any field's behaviour depends on the values (i.e. has a `when`). */
+export declare function hasFieldConditions<TData extends RowData>(schema: EntitySchema<TData>): boolean;
+/**
+ * Drop the values of fields hidden by a `when.visible` condition.
+ *
+ * The edit panel already leaves them out via `toSubmitValues`; a server that
+ * builds its own payload (the generated SSR route reads a `FormData`) runs it
+ * through this so both paths write exactly the same fields. Without it, a field
+ * the user could not see would still be saved from a posted form.
+ */
+export declare function stripHiddenValues<TData extends RowData>(schema: EntitySchema<TData>, values: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Run the schema's no-code validation rules (`EntitySchema.validations`).
+ *
+ * These already compile into the generated app's server-side `hooks.validate`;
+ * this is the matching interpreter, so the same rule also fires live in the edit
+ * panel and the designer preview instead of only after a round-trip to a
+ * generated server. The comparisons mirror `compileValidation` in
+ * `studio/emit-schema.ts` exactly - string equality for eq/ne, numeric ordering
+ * for lt/lte/gt/gte, length for minLen/maxLen - so a rule cannot mean one thing
+ * in the form and another on the server.
+ */
+export declare function evalValidationRules(rules: ReadonlyArray<ValidationRuleSpec>, values: Record<string, unknown>): Record<string, string>;
+/**
+ * Seed the form's editable state. Uses the row's value when editing, else the
+ * field's `defaultValue`, else a type-appropriate empty. Covers every field the
+ * form shows (`schemaToFormFields`), including the read-only primary key so it
+ * can be displayed.
+ */
+export declare function buildInitialValues<TData extends RowData>(schema: EntitySchema<TData>, row: TData | null | undefined): Record<string, unknown>;
+/**
+ * Validate a single field, for checking as the user leaves it rather than making
+ * them submit to find out. Includes the schema-level rules that name this field,
+ * so a cross-field rule surfaces on the field it blames.
+ */
+export declare function validateOne<TData extends RowData>(schema: EntitySchema<TData>, field: string, values: Record<string, unknown>): Promise<string | null>;
+/**
+ * Validate every editable field: required-but-empty first, then the field's
+ * Standard Schema validator (if any), then the schema-level cross-field
+ * `hooks.validate` (e.g. "end date must be after start date"). Returns a
+ * `{ field: message }` map with only the failing fields, so an empty object
+ * means the form is valid. Per-field errors take precedence over cross-field.
+ */
+export declare function validateAll<TData extends RowData>(schema: EntitySchema<TData>, values: Record<string, unknown>): Promise<Record<string, string>>;
+/**
+ * Build the payload to send to `createRow` / `updateRow`. Read-only fields
+ * (including the primary key) are never submitted; the id for an update is
+ * resolved separately via `rowId`. Values are coerced back to their runtime
+ * type (number strings to numbers, checkbox state to booleans).
+ */
+export declare function toSubmitValues<TData extends RowData>(schema: EntitySchema<TData>, values: Record<string, unknown>): Partial<TData>;
+/** The stable id of the row being edited, as a string (for `updateRow`). */
+export declare function rowId<TData extends RowData>(schema: EntitySchema<TData>, row: TData): string;

package/dist/edit-panel.js

@@ -0,0 +1,350 @@
+import { resolveIdField, schemaToFormFields, validateEntity, validateField, } from './schema.js';
+import { evaluatePredicate } from './expressions/evaluate.js';
+/** Create mode when there's no row to edit, edit mode otherwise. */
+export function editMode(row) {
+    return row == null ? 'create' : 'edit';
+}
+/** Map a field's editor type to the control the panel renders. */
+export function controlKind(field) {
+    switch (field.editorType) {
+        case 'checkbox':
+            return 'checkbox';
+        case 'number':
+            return 'number';
+        case 'date':
+            return 'date';
+        case 'datetime':
+            return 'datetime';
+        case 'time':
+            return 'time';
+        case 'textarea':
+            return 'textarea';
+        case 'select':
+        case 'rich-select':
+        case 'list':
+        case 'chips':
+            return 'select';
+        default:
+            return 'text';
+    }
+}
+function emptyFor(field) {
+    return field.type === 'boolean' ? false : '';
+}
+// --- Editor value coercion --------------------------------------------------
+// Pure conversions between the form's stored value and the shape each rich
+// editor's `value` / `onChange` expects. Kept here (not inline in the .svelte)
+// so the tricky bits - local date formatting, number <-> '' , tag arrays - are
+// unit-testable without a DOM.
+const _p2 = (n) => String(n).padStart(2, '0');
+/** A `Date` -> a **local** `yyyy-MM-dd` string (matches the native date input; no UTC shift). */
+export function toDateString(d) {
+    return d ? `${d.getFullYear()}-${_p2(d.getMonth() + 1)}-${_p2(d.getDate())}` : '';
+}
+/** A `Date` -> a **local** `yyyy-MM-ddTHH:mm` string (matches `datetime-local`; no UTC shift). */
+export function toDateTimeString(d) {
+    return d ? `${toDateString(d)}T${_p2(d.getHours())}:${_p2(d.getMinutes())}` : '';
+}
+/** Stored value -> `SvNumberInput.value` (number | null); non-numbers become null. */
+export function toNumberValue(raw) {
+    return typeof raw === 'number' && Number.isFinite(raw) ? raw : null;
+}
+/** `SvNumberInput.onChange` payload -> stored value; null becomes '' (the empty convention). */
+export function fromNumberValue(v) {
+    return v == null ? '' : v;
+}
+/** Stored value -> `SvSlider.value`; falls back to `min` when unset. */
+export function toSliderValue(raw, min) {
+    return typeof raw === 'number' && Number.isFinite(raw) ? raw : min;
+}
+/** Stored value -> `SvTagsInput.value` (string[]); splits a comma string, else wraps. */
+export function toTags(raw) {
+    if (Array.isArray(raw))
+        return raw.map((t) => String(t));
+    if (raw == null || raw === '')
+        return [];
+    return String(raw).split(',').map((s) => s.trim()).filter(Boolean);
+}
+function isEmpty(value) {
+    return value == null || value === '';
+}
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const URL_RE = /^https?:\/\/.+/;
+/**
+ * Built-in validation from the field's own constraints - number validity,
+ * min/max, length, email/url format, regex - so forms validate out of the box
+ * without any external library. Returns the first violation, or null.
+ */
+export function builtInError(field, value) {
+    if (isEmpty(value))
+        return null;
+    if (field.type === 'number') {
+        const n = Number(value);
+        if (!Number.isFinite(n))
+            return `${field.label} must be a number`;
+        if (field.min != null && n < field.min)
+            return `${field.label} must be at least ${field.min}`;
+        if (field.max != null && n > field.max)
+            return `${field.label} must be at most ${field.max}`;
+        return null;
+    }
+    const s = String(value);
+    if (field.minLength != null && s.length < field.minLength) {
+        return `${field.label} must be at least ${field.minLength} characters`;
+    }
+    if (field.maxLength != null && s.length > field.maxLength) {
+        return `${field.label} must be at most ${field.maxLength} characters`;
+    }
+    if (field.format === 'email' && !EMAIL_RE.test(s))
+        return `${field.label} must be a valid email`;
+    if (field.format === 'url' && !URL_RE.test(s))
+        return `${field.label} must be a valid URL`;
+    if (field.pattern && !new RegExp(field.pattern).test(s))
+        return `${field.label} is not in the right format`;
+    return null;
+}
+/**
+ * Evaluate one of a field's `when` conditions against the values currently in
+ * the form. A malformed condition falls back rather than throwing: a bad rule
+ * should not make the form unusable, and the safe answer differs per flag
+ * (a field stays visible, stays enabled, keeps its static required flag).
+ */
+function test(expr, values, fallback) {
+    if (!expr)
+        return fallback;
+    try {
+        const result = evaluatePredicate(expr, { row: values });
+        // An unrecognised node evaluates to undefined rather than throwing, so a
+        // non-boolean answer counts as "no opinion" and takes the fallback too.
+        return typeof result === 'boolean' ? result : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Resolve a field's live state from its `when` conditions. Read-only always
+ * wins over a `disabled` condition, and `when.required` replaces the static
+ * `required` flag rather than adding to it, so a rule can make a normally
+ * required field optional as well as the other way round.
+ */
+export function fieldState(field, values) {
+    return {
+        visible: test(field.when?.visible, values, true),
+        disabled: field.readonly || test(field.when?.disabled, values, false),
+        required: field.when?.required ? test(field.when.required, values, false) : field.required,
+    };
+}
+/** Whether a form section's `visibleWhen` holds for the current values. */
+export function sectionVisible(expr, values) {
+    return test(expr, values, true);
+}
+/** The fields the form currently shows, in order. */
+export function visibleFormFields(schema, values) {
+    return schemaToFormFields(schema).filter((f) => fieldState(f, values).visible);
+}
+/** True when any field's behaviour depends on the values (i.e. has a `when`). */
+export function hasFieldConditions(schema) {
+    return schema.fields.some((f) => !!f.when && (!!f.when.visible || !!f.when.disabled || !!f.when.required));
+}
+/**
+ * Drop the values of fields hidden by a `when.visible` condition.
+ *
+ * The edit panel already leaves them out via `toSubmitValues`; a server that
+ * builds its own payload (the generated SSR route reads a `FormData`) runs it
+ * through this so both paths write exactly the same fields. Without it, a field
+ * the user could not see would still be saved from a posted form.
+ */
+export function stripHiddenValues(schema, values) {
+    if (!hasFieldConditions(schema))
+        return values;
+    const out = {};
+    const shown = new Set(visibleFormFields(schema, values).map((f) => f.field));
+    for (const [field, value] of Object.entries(values)) {
+        if (!schema.fields.some((f) => f.field === field) || shown.has(field))
+            out[field] = value;
+    }
+    return out;
+}
+/**
+ * Run the schema's no-code validation rules (`EntitySchema.validations`).
+ *
+ * These already compile into the generated app's server-side `hooks.validate`;
+ * this is the matching interpreter, so the same rule also fires live in the edit
+ * panel and the designer preview instead of only after a round-trip to a
+ * generated server. The comparisons mirror `compileValidation` in
+ * `studio/emit-schema.ts` exactly - string equality for eq/ne, numeric ordering
+ * for lt/lte/gt/gte, length for minLen/maxLen - so a rule cannot mean one thing
+ * in the form and another on the server.
+ */
+export function evalValidationRules(rules, values) {
+    const errors = {};
+    for (const rule of rules) {
+        if (errors[rule.field])
+            continue; // first failing rule per field wins
+        const left = values[rule.field];
+        const num = () => (rule.compareTo ? Number(values[rule.compareTo]) : Number(rule.value));
+        const str = () => (rule.compareTo ? String(values[rule.compareTo]) : String(rule.value ?? ''));
+        const len = String(left ?? '').length;
+        let holds;
+        switch (rule.op) {
+            case 'eq':
+                holds = String(left) === str();
+                break;
+            case 'ne':
+                holds = String(left) !== str();
+                break;
+            case 'lt':
+                holds = Number(left) < num();
+                break;
+            case 'lte':
+                holds = Number(left) <= num();
+                break;
+            case 'gt':
+                holds = Number(left) > num();
+                break;
+            case 'gte':
+                holds = Number(left) >= num();
+                break;
+            case 'required':
+                holds = left != null && left !== '';
+                break;
+            case 'maxLen':
+                holds = len <= Number(rule.value);
+                break;
+            case 'minLen':
+                holds = len >= Number(rule.value);
+                break;
+            default: holds = true;
+        }
+        if (!holds)
+            errors[rule.field] = rule.message;
+    }
+    return errors;
+}
+/**
+ * Seed the form's editable state. Uses the row's value when editing, else the
+ * field's `defaultValue`, else a type-appropriate empty. Covers every field the
+ * form shows (`schemaToFormFields`), including the read-only primary key so it
+ * can be displayed.
+ */
+export function buildInitialValues(schema, row) {
+    const values = {};
+    const source = (row ?? null);
+    for (const f of schemaToFormFields(schema)) {
+        if (source && f.field in source)
+            values[f.field] = source[f.field];
+        else if (f.defaultValue !== undefined)
+            values[f.field] = f.defaultValue;
+        else
+            values[f.field] = emptyFor(f);
+    }
+    return values;
+}
+/**
+ * The error for one field, or null. Required-but-empty first, then the field's
+ * own constraints, then its Standard Schema validator. Read-only and
+ * condition-hidden fields never produce one: the user cannot act on them, so an
+ * error there would be a dead end.
+ *
+ * Shared by whole-form validation and by the panel's on-blur check, so a field
+ * cannot pass one and fail the other.
+ */
+async function fieldError(f, values) {
+    if (f.readonly)
+        return null;
+    const state = fieldState(f, values);
+    if (!state.visible)
+        return null;
+    const value = values[f.field];
+    if (state.required && f.type !== 'boolean' && isEmpty(value))
+        return `${f.label} is required`;
+    const builtIn = builtInError(f, value);
+    if (builtIn)
+        return builtIn;
+    if (!isEmpty(value))
+        return (await validateField(f, value)) ?? null;
+    return null;
+}
+/**
+ * Validate a single field, for checking as the user leaves it rather than making
+ * them submit to find out. Includes the schema-level rules that name this field,
+ * so a cross-field rule surfaces on the field it blames.
+ */
+export async function validateOne(schema, field, values) {
+    const descriptor = schemaToFormFields(schema).find((f) => f.field === field);
+    if (!descriptor)
+        return null;
+    const own = await fieldError(descriptor, values);
+    if (own)
+        return own;
+    if (schema.validations?.length) {
+        const byRule = evalValidationRules(schema.validations, values)[field];
+        if (byRule)
+            return byRule;
+    }
+    return (await validateEntity(schema, values))[field] ?? null;
+}
+/**
+ * Validate every editable field: required-but-empty first, then the field's
+ * Standard Schema validator (if any), then the schema-level cross-field
+ * `hooks.validate` (e.g. "end date must be after start date"). Returns a
+ * `{ field: message }` map with only the failing fields, so an empty object
+ * means the form is valid. Per-field errors take precedence over cross-field.
+ */
+export async function validateAll(schema, values) {
+    const errors = {};
+    for (const f of schemaToFormFields(schema)) {
+        const msg = await fieldError(f, values);
+        if (msg)
+            errors[f.field] = msg;
+    }
+    // No-code rules, then the cross-field hook. Neither overwrites a per-field error.
+    if (schema.validations?.length) {
+        for (const [field, message] of Object.entries(evalValidationRules(schema.validations, values))) {
+            if (!errors[field])
+                errors[field] = message;
+        }
+    }
+    const crossField = await validateEntity(schema, values);
+    for (const [field, message] of Object.entries(crossField)) {
+        if (!errors[field])
+            errors[field] = message;
+    }
+    return errors;
+}
+function coerceOut(field, value) {
+    if (field.type === 'number') {
+        if (isEmpty(value))
+            return null;
+        const n = Number(value);
+        return Number.isFinite(n) ? n : null;
+    }
+    if (field.type === 'boolean')
+        return value === true || value === 'true';
+    return value;
+}
+/**
+ * Build the payload to send to `createRow` / `updateRow`. Read-only fields
+ * (including the primary key) are never submitted; the id for an update is
+ * resolved separately via `rowId`. Values are coerced back to their runtime
+ * type (number strings to numbers, checkbox state to booleans).
+ */
+export function toSubmitValues(schema, values) {
+    const out = {};
+    for (const f of schemaToFormFields(schema)) {
+        if (f.readonly)
+            continue;
+        // A field hidden by its `when.visible` condition is left out entirely, so a
+        // value the user can no longer see is never written back.
+        if (!fieldState(f, values).visible)
+            continue;
+        out[f.field] = coerceOut(f, values[f.field]);
+    }
+    return out;
+}
+/** The stable id of the row being edited, as a string (for `updateRow`). */
+export function rowId(schema, row) {
+    const idField = resolveIdField(schema);
+    return String(row[idField]);
+}

package/dist/export-conditional.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Carry the grid's conditional formatting (color scales, data bars, icon sets,
+ * predicate rules) into the styled export formats - PDF, xlsx, HTML, and the
+ * print view. The grid's engine (`resolveCellFormat`) is pure and reused here
+ * via the Svelte-free `@svgrid/grid/format` subpath; this module turns a
+ * `ResolvedCellFormat` into the primitives the exporters can render:
+ * `{ fill, color, bold, icon }`.
+ *
+ * Data formats (csv / tsv / json / xml / md) are unstyled, so conditional
+ * formatting is ignored there. Data bars can't render as partial-width bars in
+ * a spreadsheet cell / PDF cell, so they degrade to a light fill of the bar
+ * color; icon sets prepend the icon glyph to the cell text.
+ */
+import { type ConditionalFormat } from '@svgrid/grid/format';
+import type { RowData } from '@svgrid/grid';
+import type { ExportColumn } from './export';
+/** The visual primitives an exporter can apply to one cell. */
+export type ExportCellVisual = {
+    fill?: string;
+    color?: string;
+    bold?: boolean;
+    /** Icon-set glyph to prepend to the cell text. */
+    icon?: string;
+};
+export type ExportCellVisualFn = (rowIdx: number, colIdx: number) => ExportCellVisual | undefined;
+/**
+ * Precompute per-column stats (for color scales / data bars) and return a
+ * `(rowIdx, colIdx) => ExportCellVisual | undefined` lookup over the given
+ * rows + columns. Returns a no-op when there are no formats.
+ */
+export declare function buildConditionalResolver<TData extends RowData>(cols: ReadonlyArray<ExportColumn<TData>>, rows: ReadonlyArray<TData>, formats: ReadonlyArray<ConditionalFormat<TData>> | undefined): ExportCellVisualFn;

package/dist/export-conditional.js

@@ -0,0 +1,65 @@
+/**
+ * Carry the grid's conditional formatting (color scales, data bars, icon sets,
+ * predicate rules) into the styled export formats - PDF, xlsx, HTML, and the
+ * print view. The grid's engine (`resolveCellFormat`) is pure and reused here
+ * via the Svelte-free `@svgrid/grid/format` subpath; this module turns a
+ * `ResolvedCellFormat` into the primitives the exporters can render:
+ * `{ fill, color, bold, icon }`.
+ *
+ * Data formats (csv / tsv / json / xml / md) are unstyled, so conditional
+ * formatting is ignored there. Data bars can't render as partial-width bars in
+ * a spreadsheet cell / PDF cell, so they degrade to a light fill of the bar
+ * color; icon sets prepend the icon glyph to the cell text.
+ */
+import { computeColumnStat, formatsNeedingStats, resolveCellFormat, } from '@svgrid/grid/format';
+/** Lighten a hex color toward white by `amt` (0..1). Returns input if unparseable. */
+function mixWhite(hex, amt) {
+    const m = /^#?([0-9a-f]{6})$/i.exec(hex.trim());
+    if (!m)
+        return hex;
+    const int = parseInt(m[1], 16);
+    const ch = [(int >> 16) & 255, (int >> 8) & 255, int & 255];
+    return ('#' +
+        ch.map((c) => Math.round(c + (255 - c) * amt).toString(16).padStart(2, '0')).join(''));
+}
+function toVisual(resolved) {
+    const v = {};
+    if (resolved.background)
+        v.fill = resolved.background;
+    // Data bar -> a light fill of the bar color (no partial-width bars in cells).
+    if (!v.fill && resolved.dataBar)
+        v.fill = mixWhite(resolved.dataBar.color, 0.72);
+    if (resolved.color && resolved.color !== 'transparent')
+        v.color = resolved.color;
+    if (resolved.fontWeight === 'bold' ||
+        (typeof resolved.fontWeight === 'number' && resolved.fontWeight >= 600)) {
+        v.bold = true;
+    }
+    if (resolved.icon)
+        v.icon = resolved.icon;
+    return Object.keys(v).length > 0 ? v : undefined;
+}
+/**
+ * Precompute per-column stats (for color scales / data bars) and return a
+ * `(rowIdx, colIdx) => ExportCellVisual | undefined` lookup over the given
+ * rows + columns. Returns a no-op when there are no formats.
+ */
+export function buildConditionalResolver(cols, rows, formats) {
+    if (!formats || formats.length === 0)
+        return () => undefined;
+    const stats = new Map();
+    if (formatsNeedingStats(formats)) {
+        for (const c of cols) {
+            stats.set(c.field, computeColumnStat(rows.map((r) => r[c.field])));
+        }
+    }
+    return (rowIdx, colIdx) => {
+        const col = cols[colIdx];
+        const row = rows[rowIdx];
+        if (!col || !row)
+            return undefined;
+        const raw = row[col.field];
+        const resolved = resolveCellFormat(raw, row, col.field, formats, stats.get(col.field) ?? null);
+        return toVisual(resolved);
+    };
+}

package/dist/export-ooxml.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Native OOXML (.xlsx) writer. The vendored Smart exporter only applies uniform
+ * header/row styles - it ignores per-cell styles, and can't do color scales /
+ * data bars - so conditional-formatting colors never reached Excel. This writer
+ * builds a real xlsx workbook from scratch (styles.xml + sheet.xml, zipped with
+ * jszip) so we get, together, in one file:
+ *   - typed number / date cells with a number format (Excel sums + sorts them),
+ *   - true PER-CELL fills / font color / bold (conditional formatting),
+ *   - a frozen header (and optional frozen columns),
+ *   - auto-fit / explicit column widths,
+ *   - real cell hyperlinks.
+ *
+ * It's split into a pure `buildXlsxParts` (returns the XML parts - fully unit
+ * testable) and `packageXlsx` (zips them into a Blob via a provided JSZip).
+ */
+/** One worksheet cell, already resolved by the caller. */
+export type XlsxCell = {
+    /** 'n' number, 'd' date, 's' string, 'b' boolean. */
+    t: 'n' | 'd' | 's' | 'b';
+    value: number | string | boolean | Date | null | undefined;
+    /** Excel number-format code (for 'n' / 'd'). */
+    numFmt?: string;
+    align?: 'left' | 'center' | 'right';
+    /** Background fill hex (e.g. '#fee2e2'). */
+    fill?: string;
+    /** Font color hex. */
+    color?: string;
+    bold?: boolean;
+    /** Hyperlink URL. */
+    link?: string;
+};
+/**
+ * A native Excel Table (ListObject) over the data: filter dropdowns, banded
+ * rows, structured references, and (optionally) a totals row with SUBTOTAL
+ * formulas per numeric column.
+ */
+export type XlsxTableSpec = {
+    /** Table name (no spaces; must start with a letter). E.g. 'Table1'. */
+    name: string;
+    /** Add a totals row. */
+    totalsRow: boolean;
+    /** Table style id (default 'TableStyleMedium2'). */
+    style?: string;
+    /** Per-column totals function, aligned with `header`. */
+    totalsFns: ReadonlyArray<'sum' | 'average' | 'count' | undefined>;
+};
+/**
+ * Native Excel conditional formatting over a whole column's data range - a
+ * data bar or a 2/3-stop color scale. Unlike per-cell fills, Excel computes
+ * these itself (and recomputes when the user edits), so they're interactive
+ * and higher fidelity.
+ */
+export type XlsxCondFormat = {
+    kind: 'dataBar';
+    colIdx: number;
+    color: string;
+} | {
+    kind: 'colorScale';
+    colIdx: number;
+    colors: ReadonlyArray<string>;
+};
+export type XlsxModel = {
+    sheetName: string;
+    /** Header labels (row 1). */
+    header: ReadonlyArray<string>;
+    /** Data rows (each an array of cells, column-aligned with `header`). */
+    rows: ReadonlyArray<ReadonlyArray<XlsxCell>>;
+    /** Per-column widths in pixels (optional). */
+    widths?: ReadonlyArray<number>;
+    /** Freeze the header row. */
+    freezeHeader?: boolean;
+    /** Freeze this many leading columns. */
+    freezeColumns?: number;
+    /** Native column conditional formatting (data bars / color scales). */
+    condFormats?: ReadonlyArray<XlsxCondFormat>;
+    /** Wrap the data in a native Excel Table. */
+    table?: XlsxTableSpec;
+};
+/** 0-based column index -> Excel letter (0 -> A, 26 -> AA). */
+export declare function colName(index: number): string;
+/**
+ * Build the OOXML package parts for a single-sheet workbook. Returns a map of
+ * `path -> xml string` ready to be zipped by {@link packageXlsx}.
+ */
+export declare function buildXlsxParts(model: XlsxModel): Record<string, string>;
+/** Zip the parts into an xlsx Blob using a provided JSZip constructor. */
+export declare function packageXlsx(parts: Record<string, string>, JSZip: new () => {
+    file(path: string, data: string): void;
+    generateAsync(opts: {
+        type: 'blob';
+        mimeType?: string;
+    }): Promise<Blob>;
+}): Promise<Blob>;