@contractspec/lib.presentation-runtime-core 3.7.5 → 3.8.0

package/dist/visualization.model.js

@@ -0,0 +1,307 @@
+// @bun
+// src/visualization.utils.ts
+function formatVisualizationValue(value, format) {
+  if (value == null)
+    return "\u2014";
+  if (format === "currency" && typeof value === "number") {
+    return new Intl.NumberFormat(undefined, {
+      style: "currency",
+      currency: "USD"
+    }).format(value);
+  }
+  if (format === "percentage" && typeof value === "number") {
+    return `${(value * 100).toFixed(1)}%`;
+  }
+  if ((format === "date" || format === "dateTime") && value) {
+    const date = value instanceof Date ? value : new Date(String(value));
+    return Number.isNaN(date.getTime()) ? String(value) : new Intl.DateTimeFormat(undefined, {
+      dateStyle: "medium",
+      timeStyle: format === "dateTime" ? "short" : undefined
+    }).format(date);
+  }
+  return String(value);
+}
+function resolveVisualizationRows(data, resultPath) {
+  const value = resultPath ? getAtPath(data, resultPath) : data;
+  const candidate = value ?? data;
+  if (Array.isArray(candidate))
+    return candidate.map(asRow);
+  if (Array.isArray(getAtPath(candidate, "items"))) {
+    return getAtPath(candidate, "items").map(asRow);
+  }
+  if (Array.isArray(getAtPath(candidate, "rows"))) {
+    return getAtPath(candidate, "rows").map(asRow);
+  }
+  if (Array.isArray(getAtPath(candidate, "data"))) {
+    return getAtPath(candidate, "data").map(asRow);
+  }
+  return candidate && typeof candidate === "object" ? [asRow(candidate)] : [];
+}
+function getAtPath(source, path) {
+  if (!path || source == null)
+    return source;
+  return path.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean).reduce((current, segment) => {
+    if (current == null || typeof current !== "object")
+      return;
+    return current[segment];
+  }, source);
+}
+function toNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value))
+    return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+function asRow(value) {
+  return value && typeof value === "object" ? value : { value };
+}
+
+// src/visualization.model.helpers.ts
+function createVisualizationMaps(spec) {
+  return {
+    dimensions: new Map((spec.visualization.dimensions ?? []).map((dimension) => [
+      dimension.key,
+      dimension
+    ])),
+    measures: new Map((spec.visualization.measures ?? []).map((measure) => [
+      measure.key,
+      measure
+    ]))
+  };
+}
+function createVisualizationBaseModel(spec, rows, maps) {
+  const config = spec.visualization;
+  return {
+    kind: config.kind,
+    title: config.title ?? spec.meta.title,
+    description: config.description ?? spec.meta.description,
+    summary: `${spec.meta.title ?? spec.meta.key}: ${rows.length} row${rows.length === 1 ? "" : "s"}`,
+    warnings: rows.length === 0 ? ["No visualization rows available."] : [],
+    palette: config.palette,
+    legend: config.legend,
+    tooltip: config.tooltip,
+    drilldown: config.drilldown,
+    thresholds: config.thresholds ?? [],
+    annotations: (config.annotations ?? []).map((annotation) => resolveAnnotation(annotation, rows[0] ?? {})),
+    table: createTable(config.table?.caption, config, rows)
+  };
+}
+function createMeasureSeries(measureKey, measures, rows, dimension, config) {
+  const measure = measures.get(measureKey);
+  if (!measure)
+    return null;
+  return {
+    key: config?.key ?? measure.key,
+    label: config?.label ?? measure.label,
+    type: config?.type,
+    color: config?.color ?? measure.color,
+    stack: config?.stack,
+    smooth: config?.smooth,
+    points: rows.map((row, index) => ({
+      id: `${measure.key}-${index}`,
+      raw: row,
+      x: dimension ? readDimensionValue(row, dimension) : index,
+      y: numericValue(row, measure),
+      value: numericValue(row, measure)
+    }))
+  };
+}
+function defaultSeries(keys) {
+  return keys.map((key) => ({ key, label: key, measure: key }));
+}
+function createAxis(dimension) {
+  if (!dimension)
+    return;
+  return {
+    key: dimension.key,
+    label: dimension.label,
+    type: dimension.type === "time" ? "time" : dimension.type === "number" ? "number" : "category",
+    format: dimension.format
+  };
+}
+function createValueAxis(key, measures) {
+  const measure = key ? measures.get(key) : undefined;
+  if (!measure)
+    return;
+  return {
+    key: measure.key,
+    label: measure.label,
+    type: "number",
+    format: measure.format
+  };
+}
+function readValue(row, measure) {
+  return measure ? getAtPath(row, measure.dataPath) : undefined;
+}
+function readDimensionValue(row, dimension) {
+  return dimension ? getAtPath(row, dimension.dataPath) : undefined;
+}
+function numericValue(row, measure) {
+  return toNumber(readValue(row, measure));
+}
+function numericPathValue(row, dimension) {
+  return toNumber(readDimensionValue(row, dimension));
+}
+function stringValue(row, dimension) {
+  const value = readDimensionValue(row, dimension);
+  return value == null ? undefined : String(value);
+}
+function createTable(caption, config, rows) {
+  const dimensions = config.dimensions ?? [];
+  const measures = config.measures ?? [];
+  return {
+    caption,
+    columns: [
+      ...dimensions.map((dimension) => ({
+        key: dimension.key,
+        label: dimension.label
+      })),
+      ...measures.map((measure) => ({
+        key: measure.key,
+        label: measure.label
+      }))
+    ],
+    rows: rows.map((row) => ({
+      ...Object.fromEntries(dimensions.map((dimension) => [
+        dimension.key,
+        readDimensionValue(row, dimension)
+      ])),
+      ...Object.fromEntries(measures.map((measure) => [measure.key, readValue(row, measure)]))
+    }))
+  };
+}
+function resolveAnnotation(annotation, row) {
+  return {
+    key: annotation.key,
+    label: annotation.label,
+    kind: annotation.kind,
+    color: annotation.color,
+    x: annotation.xDataPath ? getAtPath(row, annotation.xDataPath) : undefined,
+    y: annotation.yDataPath ? toNumber(getAtPath(row, annotation.yDataPath)) : undefined,
+    start: annotation.startDataPath ? getAtPath(row, annotation.startDataPath) : undefined,
+    end: annotation.endDataPath ? getAtPath(row, annotation.endDataPath) : undefined
+  };
+}
+
+// src/visualization.model.builders.ts
+function buildMetricModel(base, config, rows, maps) {
+  const measure = maps.measures.get(config.measure);
+  const comparison = config.comparisonMeasure ? maps.measures.get(config.comparisonMeasure) : undefined;
+  const currentRow = rows.at(-1) ?? {};
+  const sparkline = config.sparkline ? createMeasureSeries(config.sparkline.measure ?? config.measure, maps.measures, rows, maps.dimensions.get(config.sparkline.dimension)) : null;
+  return {
+    ...base,
+    series: sparkline ? [sparkline] : [],
+    metric: {
+      label: measure?.label ?? config.measure,
+      value: readValue(currentRow, measure),
+      comparisonValue: comparison ? readValue(currentRow, comparison) : undefined,
+      format: measure?.format
+    }
+  };
+}
+function buildCartesianModel(base, config, rows, maps) {
+  const series = (config.series ?? defaultSeries(config.yMeasures ?? [])).map((seriesItem) => createMeasureSeries(seriesItem.measure, maps.measures, rows, maps.dimensions.get(config.xDimension), seriesItem)).filter((item) => Boolean(item));
+  return {
+    ...base,
+    series,
+    xAxis: createAxis(maps.dimensions.get(config.xDimension)),
+    yAxis: createValueAxis(config.yMeasures?.[0], maps.measures)
+  };
+}
+function buildDistributionModel(base, config, rows, maps) {
+  const nameDimension = maps.dimensions.get(config.nameDimension);
+  const valueMeasure = maps.measures.get(config.valueMeasure);
+  return {
+    ...base,
+    series: [
+      {
+        key: valueMeasure?.key ?? config.valueMeasure,
+        label: valueMeasure?.label ?? config.valueMeasure,
+        type: config.kind,
+        points: rows.map((row, index) => ({
+          id: `${config.kind}-${index}`,
+          raw: row,
+          name: stringValue(row, nameDimension),
+          value: numericValue(row, valueMeasure)
+        }))
+      }
+    ]
+  };
+}
+function buildHeatmapModel(base, config, rows, maps) {
+  const xDimension = maps.dimensions.get(config.xDimension);
+  const yDimension = maps.dimensions.get(config.yDimension);
+  const valueMeasure = maps.measures.get(config.valueMeasure);
+  return {
+    ...base,
+    series: [
+      {
+        key: config.valueMeasure,
+        label: valueMeasure?.label ?? config.valueMeasure,
+        type: "heatmap",
+        points: rows.map((row, index) => ({
+          id: `heatmap-${index}`,
+          raw: row,
+          name: stringValue(row, yDimension),
+          x: readDimensionValue(row, xDimension),
+          y: numericValue(row, valueMeasure),
+          value: numericValue(row, valueMeasure)
+        }))
+      }
+    ],
+    xAxis: createAxis(xDimension),
+    yAxis: createAxis(yDimension)
+  };
+}
+function buildGeoModel(base, config, rows, maps) {
+  return {
+    ...base,
+    series: [
+      {
+        key: "geo",
+        label: "Geo",
+        type: config.variant ?? "scatter",
+        points: rows.map((row, index) => ({
+          id: `geo-${index}`,
+          raw: row,
+          name: config.nameDimension ? stringValue(row, maps.dimensions.get(config.nameDimension)) : undefined,
+          value: config.valueMeasure ? numericValue(row, maps.measures.get(config.valueMeasure)) : undefined,
+          latitude: numericPathValue(row, maps.dimensions.get(config.latitudeDimension ?? "")),
+          longitude: numericPathValue(row, maps.dimensions.get(config.longitudeDimension ?? ""))
+        }))
+      }
+    ],
+    geo: {
+      mode: config.mode ?? "chart",
+      variant: config.variant ?? "scatter",
+      geoJson: config.geoJson
+    }
+  };
+}
+
+// src/visualization.model.ts
+function createVisualizationModel(spec, data) {
+  const rows = resolveVisualizationRows(data, spec.source.resultPath);
+  const maps = createVisualizationMaps(spec);
+  const base = createVisualizationBaseModel(spec, rows, maps);
+  switch (spec.visualization.kind) {
+    case "metric":
+      return buildMetricModel(base, spec.visualization, rows, maps);
+    case "cartesian":
+      return buildCartesianModel(base, spec.visualization, rows, maps);
+    case "pie":
+    case "funnel":
+      return buildDistributionModel(base, spec.visualization, rows, maps);
+    case "heatmap":
+      return buildHeatmapModel(base, spec.visualization, rows, maps);
+    case "geo":
+      return buildGeoModel(base, spec.visualization, rows, maps);
+  }
+}
+export {
+  createVisualizationModel
+};

package/dist/visualization.model.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/visualization.types.d.ts

@@ -0,0 +1,74 @@
+import type { VisualizationAnnotation, VisualizationDrilldown, VisualizationGeoJsonSource, VisualizationGeoMode, VisualizationGeoVariant, VisualizationKind, VisualizationThreshold, VisualizationValueFormat } from '@contractspec/lib.contracts-spec/visualizations';
+export interface ContractVisualizationAxisModel {
+    key: string;
+    label: string;
+    type: 'category' | 'number' | 'time';
+    format?: VisualizationValueFormat;
+}
+export interface ContractVisualizationPoint {
+    id: string;
+    raw: Record<string, unknown>;
+    name?: string;
+    x?: unknown;
+    y?: number | null;
+    value?: number | null;
+    latitude?: number | null;
+    longitude?: number | null;
+}
+export interface ContractVisualizationSeriesModel {
+    key: string;
+    label: string;
+    type?: string;
+    color?: string;
+    stack?: string;
+    smooth?: boolean;
+    points: ContractVisualizationPoint[];
+}
+export interface ContractVisualizationMetricModel {
+    label: string;
+    value: unknown;
+    comparisonValue?: unknown;
+    format?: VisualizationValueFormat;
+}
+export interface ContractVisualizationTableAlternative {
+    caption?: string;
+    columns: {
+        key: string;
+        label: string;
+    }[];
+    rows: Record<string, unknown>[];
+}
+export interface ContractVisualizationAnnotationModel {
+    key: string;
+    label: string;
+    kind: VisualizationAnnotation['kind'];
+    color?: string;
+    x?: unknown;
+    y?: number | null;
+    start?: unknown;
+    end?: unknown;
+}
+export interface ContractVisualizationGeoModel {
+    mode: VisualizationGeoMode;
+    variant: VisualizationGeoVariant;
+    geoJson?: VisualizationGeoJsonSource;
+}
+export interface ContractVisualizationRenderModel {
+    kind: VisualizationKind;
+    title?: string;
+    description?: string;
+    summary: string;
+    warnings: string[];
+    palette?: string[];
+    legend?: boolean;
+    tooltip?: boolean;
+    drilldown?: VisualizationDrilldown;
+    series: ContractVisualizationSeriesModel[];
+    thresholds: VisualizationThreshold[];
+    annotations: ContractVisualizationAnnotationModel[];
+    table: ContractVisualizationTableAlternative;
+    metric?: ContractVisualizationMetricModel;
+    xAxis?: ContractVisualizationAxisModel;
+    yAxis?: ContractVisualizationAxisModel;
+    geo?: ContractVisualizationGeoModel;
+}

package/dist/visualization.types.js

@@ -0,0 +1 @@
+// @bun

package/dist/visualization.utils.d.ts

@@ -0,0 +1,5 @@
+import type { VisualizationValueFormat } from '@contractspec/lib.contracts-spec/visualizations';
+export declare function formatVisualizationValue(value: unknown, format?: VisualizationValueFormat): string;
+export declare function resolveVisualizationRows(data: unknown, resultPath?: string): Record<string, unknown>[];
+export declare function getAtPath(source: unknown, path: string): unknown;
+export declare function toNumber(value: unknown): number | null;

package/dist/visualization.utils.js

@@ -0,0 +1,66 @@
+// @bun
+// src/visualization.utils.ts
+function formatVisualizationValue(value, format) {
+  if (value == null)
+    return "\u2014";
+  if (format === "currency" && typeof value === "number") {
+    return new Intl.NumberFormat(undefined, {
+      style: "currency",
+      currency: "USD"
+    }).format(value);
+  }
+  if (format === "percentage" && typeof value === "number") {
+    return `${(value * 100).toFixed(1)}%`;
+  }
+  if ((format === "date" || format === "dateTime") && value) {
+    const date = value instanceof Date ? value : new Date(String(value));
+    return Number.isNaN(date.getTime()) ? String(value) : new Intl.DateTimeFormat(undefined, {
+      dateStyle: "medium",
+      timeStyle: format === "dateTime" ? "short" : undefined
+    }).format(date);
+  }
+  return String(value);
+}
+function resolveVisualizationRows(data, resultPath) {
+  const value = resultPath ? getAtPath(data, resultPath) : data;
+  const candidate = value ?? data;
+  if (Array.isArray(candidate))
+    return candidate.map(asRow);
+  if (Array.isArray(getAtPath(candidate, "items"))) {
+    return getAtPath(candidate, "items").map(asRow);
+  }
+  if (Array.isArray(getAtPath(candidate, "rows"))) {
+    return getAtPath(candidate, "rows").map(asRow);
+  }
+  if (Array.isArray(getAtPath(candidate, "data"))) {
+    return getAtPath(candidate, "data").map(asRow);
+  }
+  return candidate && typeof candidate === "object" ? [asRow(candidate)] : [];
+}
+function getAtPath(source, path) {
+  if (!path || source == null)
+    return source;
+  return path.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean).reduce((current, segment) => {
+    if (current == null || typeof current !== "object")
+      return;
+    return current[segment];
+  }, source);
+}
+function toNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value))
+    return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+function asRow(value) {
+  return value && typeof value === "object" ? value : { value };
+}
+export {
+  toNumber,
+  resolveVisualizationRows,
+  getAtPath,
+  formatVisualizationValue
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/lib.presentation-runtime-core",
-  "version": "3.7.5",
+  "version": "3.8.0",
   "description": "Core presentation runtime for contract-driven UIs",
   "keywords": [
     "contractspec",
@@ -22,18 +22,22 @@
     "clean": "rimraf dist .turbo",
     "dev": "contractspec-bun-build dev",
     "lint": "bun run lint:fix",
-    "lint:fix": "eslint src --fix",
-    "lint:check": "eslint src",
+    "lint:fix": "biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .",
+    "lint:check": "biome check .",
     "prebuild": "contractspec-bun-build prebuild",
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "peerDependencies": {
     "typescript": "^5.9.0"
   },
+  "dependencies": {
+    "@contractspec/lib.contracts-spec": "4.0.0",
+    "echarts": "^6.0.0"
+  },
   "devDependencies": {
-    "@contractspec/tool.typescript": "3.7.5",
+    "@contractspec/tool.typescript": "3.7.6",
     "typescript": "^5.9.3",
-    "@contractspec/tool.bun": "3.7.5"
+    "@contractspec/tool.bun": "3.7.6"
   },
   "files": [
     "dist",
@@ -46,6 +50,62 @@
       "bun": "./dist/index.js",
       "node": "./dist/node/index.js",
       "default": "./dist/index.js"
+    },
+    "./table": {
+      "types": "./dist/table.d.ts",
+      "browser": "./dist/browser/table.js",
+      "bun": "./dist/table.js",
+      "node": "./dist/node/table.js",
+      "default": "./dist/table.js"
+    },
+    "./visualization": {
+      "types": "./dist/visualization.d.ts",
+      "browser": "./dist/browser/visualization.js",
+      "bun": "./dist/visualization.js",
+      "node": "./dist/node/visualization.js",
+      "default": "./dist/visualization.js"
+    },
+    "./visualization.echarts": {
+      "types": "./dist/visualization.echarts.d.ts",
+      "browser": "./dist/browser/visualization.echarts.js",
+      "bun": "./dist/visualization.echarts.js",
+      "node": "./dist/node/visualization.echarts.js",
+      "default": "./dist/visualization.echarts.js"
+    },
+    "./visualization.model": {
+      "types": "./dist/visualization.model.d.ts",
+      "browser": "./dist/browser/visualization.model.js",
+      "bun": "./dist/visualization.model.js",
+      "node": "./dist/node/visualization.model.js",
+      "default": "./dist/visualization.model.js"
+    },
+    "./visualization.model.builders": {
+      "types": "./dist/visualization.model.builders.d.ts",
+      "browser": "./dist/browser/visualization.model.builders.js",
+      "bun": "./dist/visualization.model.builders.js",
+      "node": "./dist/node/visualization.model.builders.js",
+      "default": "./dist/visualization.model.builders.js"
+    },
+    "./visualization.model.helpers": {
+      "types": "./dist/visualization.model.helpers.d.ts",
+      "browser": "./dist/browser/visualization.model.helpers.js",
+      "bun": "./dist/visualization.model.helpers.js",
+      "node": "./dist/node/visualization.model.helpers.js",
+      "default": "./dist/visualization.model.helpers.js"
+    },
+    "./visualization.types": {
+      "types": "./dist/visualization.types.d.ts",
+      "browser": "./dist/browser/visualization.types.js",
+      "bun": "./dist/visualization.types.js",
+      "node": "./dist/node/visualization.types.js",
+      "default": "./dist/visualization.types.js"
+    },
+    "./visualization.utils": {
+      "types": "./dist/visualization.utils.d.ts",
+      "browser": "./dist/browser/visualization.utils.js",
+      "bun": "./dist/visualization.utils.js",
+      "node": "./dist/node/visualization.utils.js",
+      "default": "./dist/visualization.utils.js"
     }
   },
   "publishConfig": {
@@ -57,6 +117,62 @@
         "bun": "./dist/index.js",
         "node": "./dist/node/index.js",
         "default": "./dist/index.js"
+      },
+      "./table": {
+        "types": "./dist/table.d.ts",
+        "browser": "./dist/browser/table.js",
+        "bun": "./dist/table.js",
+        "node": "./dist/node/table.js",
+        "default": "./dist/table.js"
+      },
+      "./visualization": {
+        "types": "./dist/visualization.d.ts",
+        "browser": "./dist/browser/visualization.js",
+        "bun": "./dist/visualization.js",
+        "node": "./dist/node/visualization.js",
+        "default": "./dist/visualization.js"
+      },
+      "./visualization.echarts": {
+        "types": "./dist/visualization.echarts.d.ts",
+        "browser": "./dist/browser/visualization.echarts.js",
+        "bun": "./dist/visualization.echarts.js",
+        "node": "./dist/node/visualization.echarts.js",
+        "default": "./dist/visualization.echarts.js"
+      },
+      "./visualization.model": {
+        "types": "./dist/visualization.model.d.ts",
+        "browser": "./dist/browser/visualization.model.js",
+        "bun": "./dist/visualization.model.js",
+        "node": "./dist/node/visualization.model.js",
+        "default": "./dist/visualization.model.js"
+      },
+      "./visualization.model.builders": {
+        "types": "./dist/visualization.model.builders.d.ts",
+        "browser": "./dist/browser/visualization.model.builders.js",
+        "bun": "./dist/visualization.model.builders.js",
+        "node": "./dist/node/visualization.model.builders.js",
+        "default": "./dist/visualization.model.builders.js"
+      },
+      "./visualization.model.helpers": {
+        "types": "./dist/visualization.model.helpers.d.ts",
+        "browser": "./dist/browser/visualization.model.helpers.js",
+        "bun": "./dist/visualization.model.helpers.js",
+        "node": "./dist/node/visualization.model.helpers.js",
+        "default": "./dist/visualization.model.helpers.js"
+      },
+      "./visualization.types": {
+        "types": "./dist/visualization.types.d.ts",
+        "browser": "./dist/browser/visualization.types.js",
+        "bun": "./dist/visualization.types.js",
+        "node": "./dist/node/visualization.types.js",
+        "default": "./dist/visualization.types.js"
+      },
+      "./visualization.utils": {
+        "types": "./dist/visualization.utils.d.ts",
+        "browser": "./dist/browser/visualization.utils.js",
+        "bun": "./dist/visualization.utils.js",
+        "node": "./dist/node/visualization.utils.js",
+        "default": "./dist/visualization.utils.js"
       }
     },
     "registry": "https://registry.npmjs.org/"