mviz 1.6.6 → 1.6.7

package/dist/components/table-interactivity.d.ts

@@ -6,6 +6,7 @@
  * input), the per-cell `data-sort` attribute for numeric sorting, and one
  * vanilla-JS init function that wires up click/input handlers.
  */
+import type { FormatType } from '../types.js';
 export interface TableInteractivity {
     sortable: boolean;
     filter: boolean;
@@ -22,8 +23,23 @@ export declare function sortableHeaderAttrs(colIdx: number, sortable: boolean):
 /**
  * Generate `data-sort="..."` for a cell so numeric sort doesn't depend on the
  * rendered text (which may be formatted, contain SVG sparklines, etc.).
+ *
+ * When the column declares a `format`, the sort key is derived from that
+ * declaration — `date` → epoch ms, `duration` → seconds, numeric formats →
+ * raw number. This is the preferred path because format removes ambiguity
+ * (e.g. is `"5m"` 5 minutes or 5 million dollars?).
+ *
+ * For untyped columns, two unambiguous string shapes still get a numeric
+ * key as a courtesy: ISO-8601 dates (`YYYY-MM-DD`) and duration strings
+ * that include a seconds segment (`10s`, `1m7s`, `1h2m3s`). Anything else —
+ * including bare `5m` or `1h`, which is ambiguous (5 minutes or 5 million?) —
+ * falls back to locale string sort. Columns that explicitly declare
+ * `fmt: "duration"` still get lenient parsing of `5m`/`1h`; the strict form
+ * only applies to the untyped courtesy path. Pre-formatted currency strings
+ * are intentionally not parsed — pass numeric values and declare
+ * `format: "currency_auto"` (etc.) instead.
  */
-export declare function cellSortAttr(value: unknown): string;
+export declare function cellSortAttr(value: unknown, format?: FormatType): string;
 /**
  * Build the filter toolbar (global search input when `filter: true`).
  */

package/dist/components/table-interactivity.js

@@ -6,6 +6,7 @@
  * input), the per-cell `data-sort` attribute for numeric sorting, and one
  * vanilla-JS init function that wires up click/input handlers.
  */
+import { formatSortKey, parseDurationString, parseIsoDateString, } from '../core/formatting.js';
 /**
  * Read sortable/filter options from a spec. Sort defaults ON, filter defaults OFF.
  */
@@ -27,10 +28,33 @@ export function sortableHeaderAttrs(colIdx, sortable) {
 /**
  * Generate `data-sort="..."` for a cell so numeric sort doesn't depend on the
  * rendered text (which may be formatted, contain SVG sparklines, etc.).
+ *
+ * When the column declares a `format`, the sort key is derived from that
+ * declaration — `date` → epoch ms, `duration` → seconds, numeric formats →
+ * raw number. This is the preferred path because format removes ambiguity
+ * (e.g. is `"5m"` 5 minutes or 5 million dollars?).
+ *
+ * For untyped columns, two unambiguous string shapes still get a numeric
+ * key as a courtesy: ISO-8601 dates (`YYYY-MM-DD`) and duration strings
+ * that include a seconds segment (`10s`, `1m7s`, `1h2m3s`). Anything else —
+ * including bare `5m` or `1h`, which is ambiguous (5 minutes or 5 million?) —
+ * falls back to locale string sort. Columns that explicitly declare
+ * `fmt: "duration"` still get lenient parsing of `5m`/`1h`; the strict form
+ * only applies to the untyped courtesy path. Pre-formatted currency strings
+ * are intentionally not parsed — pass numeric values and declare
+ * `format: "currency_auto"` (etc.) instead.
  */
-export function cellSortAttr(value) {
+export function cellSortAttr(value, format) {
     if (value === null || value === undefined)
         return '';
+    // Format-driven sort (preferred when declared).
+    if (format) {
+        const key = formatSortKey(value, format);
+        if (key !== null)
+            return ` data-sort="${key}"`;
+        // Format declared but value can't be coerced — fall through to the
+        // untyped heuristics so sort still does *something* sensible.
+    }
     if (typeof value === 'number' && !isNaN(value)) {
         return ` data-sort="${value}"`;
     }
@@ -39,6 +63,15 @@ export function cellSortAttr(value) {
         if (!isNaN(n) && String(n) === value.trim()) {
             return ` data-sort="${n}"`;
         }
+        const dateKey = parseIsoDateString(value);
+        if (dateKey !== null)
+            return ` data-sort="${dateKey}"`;
+        // Strict: require a seconds segment so bare "5m" / "1h" don't get parsed
+        // as durations. Those shapes are ambiguous in an untyped column; declare
+        // `fmt: "duration"` to opt into lenient parsing.
+        const durKey = parseDurationString(value, { requireSeconds: true });
+        if (durKey !== null)
+            return ` data-sort="${durKey}"`;
         return ` data-sort="${escapeAttr(value)}"`;
     }
     // Objects/arrays (e.g., sparkline data) are not sortable; omit the attribute.

package/dist/components/table.js

@@ -498,7 +498,7 @@ function buildDataRows(cfg, inlineStyles = false) {
             const cellResult = formatCell(value, col, cfg.colors, cfg.heatmapRanges, cfg.dumbbellRanges, cfg.defaultHeatmapColors, undefined, cfg.currency, cfg.pctMultiplyByColumn);
             // Unwrap `{value, bold, italic}` overrides so numeric sort sees the real value.
             const sortRaw = extractCellValue(value, col).value;
-            const sortAttr = cfg.interactivity.sortable ? cellSortAttr(sortRaw) : '';
+            const sortAttr = cfg.interactivity.sortable ? cellSortAttr(sortRaw, col.fmt) : '';
             if (inlineStyles) {
                 const border = isLast ? `border-bottom: 1px solid ${cfg.colors.text};` : '';
                 const cellBg = cellResult.bgColor ?? rowBg;

package/dist/core/chart-helpers.d.ts

@@ -1,10 +1,14 @@
 /**
- * Shared helpers for scatter-family charts (scatter, bubble).
+ * Shared helpers for chart builders.
  *
- * Consolidates series-grouping, label config, and legend patterns
- * that were duplicated across scatter.ts and bubble.ts.
+ * Consolidates patterns that were duplicated across multiple chart builders:
+ * - scatter-family series grouping/labels (scatter, bubble)
+ * - value-axis format context (bar, line, area, combo)
+ * - x-axis label config (line, area, combo, bar)
+ * - yMin/yMax application (bar, line, area, combo)
+ * - multi-series legend (bar, area, combo)
  */
-import type { DataPoint, ThemeColors } from '../types.js';
+import type { ChartSpec, CurrencyConfig, DataPoint, FormatType, ThemeColors, AxisType } from '../types.js';
 /**
  * Build ECharts label config for persistent point labels.
  * @param labelIndex - Index of the label value in the point array
@@ -15,7 +19,57 @@ export declare function buildPointLabelConfig(labelIndex: number, colors: ThemeC
  */
 export declare function groupDataBySeries<T>(data: DataPoint[], seriesField: string, buildPoint: (d: DataPoint) => T): Map<string, T[]>;
 /**
- * Build ECharts legend config for multi-series charts.
+ * Build ECharts legend config for scatter-style multi-series charts.
+ * Uses small text and no item-width override.
  */
 export declare function buildSeriesLegend(legendData: string[], colors: ThemeColors): Record<string, unknown>;
+/**
+ * Build ECharts legend config for bar/area/combo style charts.
+ * Uses narrow line-style swatches matching the rest of the chart palette.
+ */
+export declare function buildMultiSeriesLegend(legendData: string[], colors: ThemeColors): Record<string, unknown>;
+/**
+ * Resolved format context for a chart's value axis.
+ *
+ * Wraps the recurring (format, currency, pctMultiply, formatter) tuple
+ * so chart builders don't have to re-derive each piece individually.
+ */
+export interface ValueAxisFormatContext {
+    valueFormat: FormatType;
+    currency: CurrencyConfig;
+    pctMultiply: boolean;
+    axisFormatter: {
+        _js_: string;
+    } | null;
+    labelFormatter?: {
+        _js_: string;
+    } | null;
+}
+export interface BuildValueAxisFormatContextOptions {
+    /** Override the inferred format (e.g. combo's secondaryFormat). */
+    formatOverride?: FormatType;
+    /** Also build a label formatter (used by bar). */
+    withLabelFormatter?: boolean;
+}
+/**
+ * Resolve format/currency/pctMultiply and produce axis (and optionally label)
+ * formatters for a chart's value axis.
+ *
+ * Used by bar, line, area, and combo. Combo calls this twice (once per axis).
+ */
+export declare function buildValueAxisFormatContext(spec: ChartSpec, data: DataPoint[], yKeys: string[], opts?: BuildValueAxisFormatContextOptions): ValueAxisFormatContext;
+/**
+ * Build an ECharts xAxis label config based on the resolved axis type.
+ *
+ * - `category`: 45° rotation with truncation for long labels
+ * - `time`:     month-day formatter ("Jan 5")
+ * - `value`:    just hideOverlap
+ */
+export declare function buildXAxisLabelConfig(xAxisType: AxisType): Record<string, unknown>;
+/**
+ * Apply yMin/yMax from a spec onto a value-axis object in place.
+ * The caller passes the right axis object (xAxis for horizontal bars,
+ * yAxis or yAxis[0] for everything else).
+ */
+export declare function applyValueAxisRange(axisObj: Record<string, unknown>, spec: ChartSpec): void;
 //# sourceMappingURL=chart-helpers.d.ts.map

package/dist/core/chart-helpers.js

@@ -1,10 +1,15 @@
 /**
- * Shared helpers for scatter-family charts (scatter, bubble).
+ * Shared helpers for chart builders.
  *
- * Consolidates series-grouping, label config, and legend patterns
- * that were duplicated across scatter.ts and bubble.ts.
+ * Consolidates patterns that were duplicated across multiple chart builders:
+ * - scatter-family series grouping/labels (scatter, bubble)
+ * - value-axis format context (bar, line, area, combo)
+ * - x-axis label config (line, area, combo, bar)
+ * - yMin/yMax application (bar, line, area, combo)
+ * - multi-series legend (bar, area, combo)
  */
-import { FONT_SIZE_TINY } from './themes.js';
+import { FONT_SIZE_TINY, FONT_SIZE_XXS, LEGEND_ITEM_WIDTH, LEGEND_ITEM_HEIGHT, LEGEND_ITEM_GAP, } from './themes.js';
+import { inferFormat, resolveCurrency, shouldPctMultiply, collectNumericFieldValues, getAxisFormatterJs, getLabelFormatterJs, } from './formatting.js';
 /**
  * Build ECharts label config for persistent point labels.
  * @param labelIndex - Index of the label value in the point array
@@ -33,7 +38,8 @@ export function groupDataBySeries(data, seriesField, buildPoint) {
     return groups;
 }
 /**
- * Build ECharts legend config for multi-series charts.
+ * Build ECharts legend config for scatter-style multi-series charts.
+ * Uses small text and no item-width override.
  */
 export function buildSeriesLegend(legendData, colors) {
     return {
@@ -43,4 +49,77 @@ export function buildSeriesLegend(legendData, colors) {
         textStyle: { color: colors.textSecondary, fontSize: FONT_SIZE_TINY },
     };
 }
+/**
+ * Build ECharts legend config for bar/area/combo style charts.
+ * Uses narrow line-style swatches matching the rest of the chart palette.
+ */
+export function buildMultiSeriesLegend(legendData, colors) {
+    return {
+        data: legendData,
+        top: 0,
+        textStyle: { color: colors.textSecondary, fontSize: FONT_SIZE_XXS },
+        itemWidth: LEGEND_ITEM_WIDTH,
+        itemHeight: LEGEND_ITEM_HEIGHT,
+        itemGap: LEGEND_ITEM_GAP,
+    };
+}
+/**
+ * Resolve format/currency/pctMultiply and produce axis (and optionally label)
+ * formatters for a chart's value axis.
+ *
+ * Used by bar, line, area, and combo. Combo calls this twice (once per axis).
+ */
+export function buildValueAxisFormatContext(spec, data, yKeys, opts = {}) {
+    const firstYKey = yKeys[0] ?? 'value';
+    const sampleValue = data.length > 0 && data[0] ? data[0][firstYKey] ?? 0 : 0;
+    const valueFormat = opts.formatOverride ?? spec.format ?? inferFormat(firstYKey, sampleValue);
+    const currency = resolveCurrency(spec.currency);
+    const pctMultiply = shouldPctMultiply(valueFormat, collectNumericFieldValues(data, yKeys));
+    const axisFormatter = getAxisFormatterJs(valueFormat, currency.symbol, currency.locale, pctMultiply);
+    const ctx = { valueFormat, currency, pctMultiply, axisFormatter };
+    if (opts.withLabelFormatter) {
+        ctx.labelFormatter = getLabelFormatterJs(valueFormat, currency.symbol, currency.locale, pctMultiply);
+    }
+    return ctx;
+}
+/**
+ * Month-day formatter used for time-axis labels (e.g. "Jan 5").
+ * Extracted to a constant so all chart builders share the same JS source.
+ */
+const TIME_AXIS_MONTH_DAY_FORMATTER = {
+    _js_: `function(value) {
+            var d = new Date(value);
+            var months = ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'];
+            return months[d.getMonth()] + ' ' + d.getDate();
+          }`,
+};
+/**
+ * Build an ECharts xAxis label config based on the resolved axis type.
+ *
+ * - `category`: 45° rotation with truncation for long labels
+ * - `time`:     month-day formatter ("Jan 5")
+ * - `value`:    just hideOverlap
+ */
+export function buildXAxisLabelConfig(xAxisType) {
+    if (xAxisType === 'category') {
+        return { interval: 0, rotate: 45, overflow: 'truncate', ellipsis: '...', width: 100 };
+    }
+    if (xAxisType === 'time') {
+        return { hideOverlap: true, formatter: TIME_AXIS_MONTH_DAY_FORMATTER };
+    }
+    return { hideOverlap: true };
+}
+/**
+ * Apply yMin/yMax from a spec onto a value-axis object in place.
+ * The caller passes the right axis object (xAxis for horizontal bars,
+ * yAxis or yAxis[0] for everything else).
+ */
+export function applyValueAxisRange(axisObj, spec) {
+    if (spec.yMin !== undefined) {
+        axisObj.min = spec.yMin;
+    }
+    if (spec.yMax !== undefined) {
+        axisObj.max = spec.yMax;
+    }
+}
 //# sourceMappingURL=chart-helpers.js.map

package/dist/core/formatting.d.ts

@@ -26,6 +26,39 @@ export declare function localeFixed(value: number, decimals: number, locale: str
  *   values are in percentage units (via detectPctMultiply).
  */
 export declare function formatNumber(value: number | null | undefined, format?: FormatType, showSign?: boolean, currency?: CurrencyConfig, pctMultiply?: boolean): string;
+/**
+ * Convert a cell value to a numeric (or string) sort key based on the
+ * declared column format. The result is what the table emits as
+ * `data-sort` so the client-side compare always sees comparable values.
+ *
+ * - `date` → epoch ms (accepts Date, ISO string, or numeric ms)
+ * - `duration` → total seconds (accepts number-of-seconds or `1m7s` style)
+ * - currency / pct / num / auto → underlying numeric value
+ *
+ * Returns null when the value can't be coerced for the declared format —
+ * the caller falls back to its untyped heuristic chain.
+ */
+export declare function formatSortKey(value: unknown, format?: FormatType): number | string | null;
+/**
+ * Parse a duration string like `"10s"`, `"1m7s"`, `"25m39s"`, `"1h2m3s"`
+ * into total seconds. Returns null when the input doesn't match.
+ * Exported for the untyped fallback path in `cellSortAttr`.
+ *
+ * When `requireSeconds` is true, only strings that contain an `s` segment
+ * match — bare `5m` or `1h` are rejected. The untyped fallback uses this
+ * stricter form because a bare magnitude like `5m` is ambiguous (5 minutes
+ * or 5 million?); the lenient form is for columns that explicitly declare
+ * `fmt: "duration"`.
+ */
+export declare function parseDurationString(s: string, options?: {
+    requireSeconds?: boolean;
+}): number | null;
+/**
+ * Parse an ISO-8601 date string (`YYYY-MM-DD` with optional time/timezone)
+ * into epoch ms. Returns null for non-ISO strings so they fall back to
+ * locale sort instead of mis-parsing through `Date.parse`.
+ */
+export declare function parseIsoDateString(s: string): number | null;
 /**
  * Detect whether a series of values needs to be multiplied by 100 for percent formatting.
  * Returns true when the series looks fractional (max |v| <= 1). Returns false when any

package/dist/core/formatting.js

@@ -92,6 +92,12 @@ export function formatNumber(value, format, showSign = false, currency, pctMulti
         case 'num0b':
             result = formatNum0b(value);
             break;
+        case 'duration':
+            result = formatDuration(value);
+            break;
+        case 'date':
+            result = formatDateValue(value);
+            break;
         default:
             result = smartFormatNumber(value, false, cur);
     }
@@ -198,6 +204,135 @@ function formatCurrency0b(value, cur) {
     const formatted = cur.symbol + localeFixed(absValue / 1_000_000_000, 1, cur.locale) + 'b';
     return isNegative ? `(${formatted})` : formatted;
 }
+/**
+ * Render a number of seconds as a compact duration string: `"1m7s"`,
+ * `"25m39s"`, `"1h2m3s"`. Sub-second values render as `"0.5s"`. Negatives
+ * are wrapped in parens like the rest of the formatters.
+ */
+function formatDuration(seconds) {
+    if (seconds === 0)
+        return '0s';
+    const neg = seconds < 0;
+    let s = Math.abs(seconds);
+    const h = Math.floor(s / 3600);
+    s -= h * 3600;
+    const m = Math.floor(s / 60);
+    s -= m * 60;
+    let body = '';
+    if (h)
+        body += `${h}h`;
+    if (m)
+        body += `${m}m`;
+    if (s || (!h && !m)) {
+        const secStr = Number.isInteger(s) ? `${s}` : s.toFixed(2).replace(/\.?0+$/, '');
+        body += `${secStr}s`;
+    }
+    return neg ? `(${body})` : body;
+}
+/**
+ * Render an epoch-ms number as an ISO `YYYY-MM-DD` date string.
+ * String inputs are handled separately by the renderer (passed through),
+ * so this only fires when the value is numeric.
+ */
+function formatDateValue(value) {
+    const d = new Date(value);
+    if (isNaN(d.getTime()))
+        return String(value);
+    const yyyy = d.getUTCFullYear();
+    const mm = String(d.getUTCMonth() + 1).padStart(2, '0');
+    const dd = String(d.getUTCDate()).padStart(2, '0');
+    return `${yyyy}-${mm}-${dd}`;
+}
+/**
+ * Convert a cell value to a numeric (or string) sort key based on the
+ * declared column format. The result is what the table emits as
+ * `data-sort` so the client-side compare always sees comparable values.
+ *
+ * - `date` → epoch ms (accepts Date, ISO string, or numeric ms)
+ * - `duration` → total seconds (accepts number-of-seconds or `1m7s` style)
+ * - currency / pct / num / auto → underlying numeric value
+ *
+ * Returns null when the value can't be coerced for the declared format —
+ * the caller falls back to its untyped heuristic chain.
+ */
+export function formatSortKey(value, format) {
+    if (value === null || value === undefined)
+        return null;
+    if (!format)
+        return null;
+    if (format === 'date') {
+        if (value instanceof Date) {
+            const t = value.getTime();
+            return isNaN(t) ? null : t;
+        }
+        if (typeof value === 'number' && !isNaN(value))
+            return value;
+        if (typeof value === 'string') {
+            const t = Date.parse(value);
+            return isNaN(t) ? null : t;
+        }
+        return null;
+    }
+    if (format === 'duration') {
+        if (typeof value === 'number' && !isNaN(value))
+            return value;
+        if (typeof value === 'string') {
+            return parseDurationString(value);
+        }
+        return null;
+    }
+    // Numeric-typed formats (currency*, pct*, num*, auto): pass numeric values
+    // through, parse simple numeric strings. Pre-formatted strings are *not*
+    // parsed — pass numeric values for typed columns.
+    if (typeof value === 'number' && !isNaN(value))
+        return value;
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        const n = parseFloat(trimmed);
+        if (!isNaN(n) && String(n) === trimmed)
+            return n;
+    }
+    return null;
+}
+/**
+ * Parse a duration string like `"10s"`, `"1m7s"`, `"25m39s"`, `"1h2m3s"`
+ * into total seconds. Returns null when the input doesn't match.
+ * Exported for the untyped fallback path in `cellSortAttr`.
+ *
+ * When `requireSeconds` is true, only strings that contain an `s` segment
+ * match — bare `5m` or `1h` are rejected. The untyped fallback uses this
+ * stricter form because a bare magnitude like `5m` is ambiguous (5 minutes
+ * or 5 million?); the lenient form is for columns that explicitly declare
+ * `fmt: "duration"`.
+ */
+export function parseDurationString(s, options = {}) {
+    const trimmed = s.trim();
+    const m = trimmed.match(/^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+(?:\.\d+)?)s)?$/);
+    if (!m)
+        return null;
+    const [, h, mm, ss] = m;
+    if (h === undefined && mm === undefined && ss === undefined)
+        return null;
+    if (options.requireSeconds && ss === undefined)
+        return null;
+    const hours = h ? parseInt(h, 10) : 0;
+    const mins = mm ? parseInt(mm, 10) : 0;
+    const secs = ss ? parseFloat(ss) : 0;
+    return hours * 3600 + mins * 60 + secs;
+}
+/**
+ * Parse an ISO-8601 date string (`YYYY-MM-DD` with optional time/timezone)
+ * into epoch ms. Returns null for non-ISO strings so they fall back to
+ * locale sort instead of mis-parsing through `Date.parse`.
+ */
+export function parseIsoDateString(s) {
+    const trimmed = s.trim();
+    const iso = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+    if (!iso.test(trimmed))
+        return null;
+    const t = Date.parse(trimmed);
+    return isNaN(t) ? null : t;
+}
 /**
  * Detect whether a series of values needs to be multiplied by 100 for percent formatting.
  * Returns true when the series looks fractional (max |v| <= 1). Returns false when any

package/dist/core/linter.d.ts

@@ -16,6 +16,9 @@ export declare class SpecValidationError extends Error {
  * Lint a single spec - validates against schema and performs data validation.
  * Throws SpecValidationError on failure. Logs warnings to stderr.
  *
+ * Columnar specs (`{columns, rows}`) are normalized to the standard
+ * `{data}` shape before validation, so callers do not need to convert first.
+ *
  * @param mode - 'generate' (default) skips lint-only rules so HTML rendering
  *   stays quiet. 'lint' (used by `mviz --lint`) runs every rule, including
  *   advisory ones scoped to the lint command.

package/dist/core/linter.js

@@ -10,7 +10,8 @@ import { readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { executeLintRules, buildLintContext, findSchemaDir } from './lint-rules/index.js';
-import { TYPE_TO_SCHEMA_DEF, VALID_TYPES } from './lint-rules/schema-fields.js';
+import { TYPE_TO_SCHEMA_DEF, VALID_TYPES, VALID_FIELDS } from './lint-rules/schema-fields.js';
+import { convertColumnarFormat } from '../layout/converter.js';
 // Handle default exports for CommonJS/ESM interop
 const Ajv2020 = Ajv2020Module;
 const addFormats = addFormatsModule;
@@ -93,12 +94,37 @@ function filterErrorsNoType(errors) {
 /**
  * Filter errors to only those relevant to a specific schema definition
  */
-function filterErrorsForDef(errors, defName) {
+function filterErrorsForDef(errors, defName, specType) {
     const relevantErrors = errors.filter((e) => e.schemaPath.includes(`/$defs/${defName}/`));
+    // Also keep enum errors from shared $defs (like FormatOption) when the
+    // failing property belongs to this spec's root — otherwise invalid enum
+    // values silently pass because the error lives under `/$defs/FormatOption/enum`
+    // rather than the type's own def.
+    const sharedEnumErrors = findSharedEnumErrors(errors, specType);
     if (relevantErrors.length === 0) {
-        return errors.filter((e) => e.keyword === 'additionalProperties' && e.schemaPath.includes(`/$defs/${defName}`));
+        const additionalPropErrors = errors.filter((e) => e.keyword === 'additionalProperties' && e.schemaPath.includes(`/$defs/${defName}`));
+        return [...additionalPropErrors, ...sharedEnumErrors];
     }
-    return relevantErrors;
+    return [...relevantErrors, ...sharedEnumErrors];
+}
+/**
+ * Find enum errors whose instancePath points to a top-level field of the
+ * spec. These come from shared $defs (e.g. FormatOption) and would otherwise
+ * be dropped by the schemaPath-based filter.
+ */
+function findSharedEnumErrors(errors, specType) {
+    const validFields = VALID_FIELDS[specType];
+    if (!validFields)
+        return [];
+    return errors.filter((e) => {
+        if (e.keyword !== 'enum')
+            return false;
+        // instancePath like "/format" — first segment is the field name.
+        const m = e.instancePath.match(/^\/([^/]+)(?:\/|$)/);
+        if (!m || !m[1])
+            return false;
+        return validFields.has(m[1]);
+    });
 }
 /**
  * Filter schema errors to only show relevant errors for the detected type.
@@ -113,7 +139,7 @@ function filterSchemaErrors(errors, specType) {
     if (!defName) {
         return [createUnknownTypeError(specType)];
     }
-    return filterErrorsForDef(errors, defName);
+    return filterErrorsForDef(errors, defName, specType);
 }
 /**
  * Format a schema error into a readable message
@@ -185,20 +211,38 @@ function logWarnings(warnings) {
     }
     console.error('');
 }
+/**
+ * Normalize a spec for validation.
+ *
+ * Currently this just folds the columnar `{columns, rows}` shape into the
+ * standard `{data}` shape. Linting always runs against the normalized spec so
+ * every entry point (CLI, markdown parser, programmatic) sees the same
+ * contract.
+ */
+function normalizeForLint(spec) {
+    if (spec && typeof spec === 'object' && 'type' in spec) {
+        return convertColumnarFormat(spec);
+    }
+    return spec;
+}
 /**
  * Lint a single spec - validates against schema and performs data validation.
  * Throws SpecValidationError on failure. Logs warnings to stderr.
  *
+ * Columnar specs (`{columns, rows}`) are normalized to the standard
+ * `{data}` shape before validation, so callers do not need to convert first.
+ *
  * @param mode - 'generate' (default) skips lint-only rules so HTML rendering
  *   stays quiet. 'lint' (used by `mviz --lint`) runs every rule, including
  *   advisory ones scoped to the lint command.
  */
 export function lintSpec(spec, mode = 'generate') {
+    const normalized = normalizeForLint(spec);
     // Schema validation
-    validateAgainstSchema(spec);
+    validateAgainstSchema(normalized);
     // Modular lint rules validation
-    if (spec && typeof spec === 'object' && 'type' in spec) {
-        const context = buildLintContext(spec);
+    if (normalized && typeof normalized === 'object' && 'type' in normalized) {
+        const context = buildLintContext(normalized);
         const result = executeLintRules(context, mode);
         // Log warnings to stderr
         if (result.warnings.length > 0) {

package/dist/layout/block-loader.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Phase 2: Load + convert + validate.
+ *
+ * Walks a raw IR (from markdown-parser) and resolves every `RawCodeBlockItem`
+ * into a `ParsedItem` by:
+ *   - reading any `file=` reference (CSV or JSON)
+ *   - parsing inline JSON
+ *   - merging file data with inline options
+ *   - applying columnar -> standard format conversion
+ *   - injecting frontmatter currency / theme defaults
+ *   - linting the resulting spec
+ *
+ * Errors collected during this phase are returned as a string list so the
+ * caller can report them in non-strict mode or short-circuit in strict mode.
+ */
+import type { ParsedFrontmatter, RawSection, Section } from './parser-types.js';
+export interface LoadOptions {
+    baseDir: string | undefined;
+    strict: boolean;
+    lintMode: 'generate' | 'lint';
+    frontmatter: ParsedFrontmatter;
+}
+export interface LoadResult {
+    sections: Section[];
+    errors: string[];
+}
+/**
+ * Resolve all raw items into parsed items. Walks every section/row/item.
+ */
+export declare function loadSections(rawSections: RawSection[], options: LoadOptions): LoadResult;
+//# sourceMappingURL=block-loader.d.ts.map