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

package/README.md

@@ -1,67 +1,73 @@
 # @contractspec/lib.presentation-runtime-core
 
-Website: https://contractspec.io/
+Website: https://contractspec.io
 
+**Core presentation runtime for contract-driven UIs.**
 
-Core logic for ContractSpec presentation runtimes.
+## What It Provides
 
-## Purpose
-
-To provide the shared, framework-agnostic state management and logic for executing workflows and rendering presentations defined in ContractSpec.
+- **Layer**: lib.
+- **Consumers**: presentation-runtime-react, presentation-runtime-react-native.
+- Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`.
+- Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`.
 
 ## Installation
 
-```bash
-npm install @contractspec/lib.presentation-runtime-core
-# or
-bun add @contractspec/lib.presentation-runtime-core
-```
-
-## Key Concepts
-
-- **Workflow State**: Manages the progression of steps in a `WorkflowSpec`.
-- **Step Navigation**: Logic for next/previous/submit actions.
-- **Validation**: Integration with Zod schemas for step validation.
+`npm install @contractspec/lib.presentation-runtime-core`
 
-## Exports
+or
 
-- Types and state machines for workflows.
-- Validation helpers.
+`bun add @contractspec/lib.presentation-runtime-core`
 
 ## Usage
 
-Typically used internally by `@contractspec/lib.presentation-runtime-react` or `@contractspec/lib.presentation-runtime-react-native`.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+Import the root entrypoint from `@contractspec/lib.presentation-runtime-core`, or choose a documented subpath when you only need one part of the package surface.
+
+## Architecture
+
+- `src/index.ts` is the root public barrel and package entrypoint.
+- `src/metro.cjs` is part of the package's public or composition surface.
+- `src/next.mjs` is part of the package's public or composition surface.
+- `src/table.ts` is part of the package's public or composition surface.
+- `src/visualization.echarts.ts` is part of the package's public or composition surface.
+- `src/visualization.model.builders.ts` is part of the package's public or composition surface.
+- `src/visualization.model.helpers.ts` is part of the package's public or composition surface.
+
+## Public Entry Points
+
+- Export `.` resolves through `./src/index.ts`.
+- Export `./table` resolves through `./src/table.ts`.
+- Export `./visualization` resolves through `./src/visualization.ts`.
+- Export `./visualization.echarts` resolves through `./src/visualization.echarts.ts`.
+- Export `./visualization.model` resolves through `./src/visualization.model.ts`.
+- Export `./visualization.model.builders` resolves through `./src/visualization.model.builders.ts`.
+- Export `./visualization.model.helpers` resolves through `./src/visualization.model.helpers.ts`.
+- Export `./visualization.types` resolves through `./src/visualization.types.ts`.
+- Export `./visualization.utils` resolves through `./src/visualization.utils.ts`.
+
+## Local Commands
+
+- `bun run dev` — contractspec-bun-build dev
+- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
+- `bun run lint` — bun run lint:fix
+- `bun run lint:check` — biome check .
+- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
+- `bun run typecheck` — tsc --noEmit -p tsconfig.json
+- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
+- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
+- `bun run clean` — rimraf dist .turbo
+- `bun run build:bundle` — contractspec-bun-build transpile
+- `bun run build:types` — contractspec-bun-build types
+- `bun run prebuild` — contractspec-bun-build prebuild
+
+## Recent Updates
+
+- Replace eslint+prettier by biomejs to optimize speed.
+- Add data visualization capabilities.
+- Add table capabilities.
+
+## Notes
+
+- Core runtime interface is consumed by all presentation runtimes — changes here affect both web and mobile.
+- Must remain platform-agnostic; no React or React Native imports allowed.
+- API surface changes require coordinated updates in both downstream runtimes.

package/dist/browser/index.js

@@ -1,3 +1,471 @@
+// src/table.ts
+function createEmptyTableState() {
+  return {
+    sorting: [],
+    pagination: {
+      pageIndex: 0,
+      pageSize: 25
+    },
+    columnVisibility: {},
+    columnSizing: {},
+    columnPinning: {
+      left: [],
+      right: []
+    },
+    expanded: {},
+    rowSelection: {}
+  };
+}
+
+// src/visualization.utils.ts
+function formatVisualizationValue(value, format) {
+  if (value == null)
+    return "—";
+  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);
+  }
+}
+// src/visualization.echarts.ts
+function buildVisualizationEChartsOption(model) {
+  const thresholdLines = model.thresholds.map((threshold) => ({
+    yAxis: threshold.value,
+    name: threshold.label,
+    lineStyle: {
+      color: threshold.color ?? "#ef4444",
+      type: "dashed"
+    }
+  }));
+  const annotationLines = model.annotations.filter((annotation) => annotation.kind === "line" && annotation.y != null).map((annotation) => toMarkLine(annotation));
+  switch (model.kind) {
+    case "cartesian":
+      const cartesianSeries = model.series.map((series) => ({
+        name: series.label,
+        type: resolveCartesianSeriesType(series.type),
+        smooth: series.smooth,
+        stack: series.stack,
+        areaStyle: series.type === "area" ? {} : undefined,
+        itemStyle: series.color ? { color: series.color } : undefined,
+        lineStyle: series.color ? { color: series.color } : undefined,
+        data: series.points.filter((point) => point.y != null).map((point) => [point.x, point.y]),
+        markLine: thresholdLines.length || annotationLines.length ? { data: [...thresholdLines, ...annotationLines] } : undefined
+      }));
+      return {
+        color: model.palette,
+        tooltip: model.tooltip === false ? undefined : { trigger: "axis" },
+        legend: { show: model.legend ?? model.series.length > 1 },
+        xAxis: { type: model.xAxis?.type === "time" ? "time" : "category" },
+        yAxis: { type: "value", name: model.yAxis?.label },
+        series: cartesianSeries
+      };
+    case "pie":
+      const pieSeries = [
+        {
+          type: "pie",
+          radius: ["0%", "70%"],
+          data: model.series[0]?.points.filter((point) => point.value != null).map((point) => ({
+            name: point.name ?? "",
+            value: point.value
+          })) ?? []
+        }
+      ];
+      return {
+        color: model.palette,
+        tooltip: model.tooltip === false ? undefined : { trigger: "item" },
+        series: pieSeries
+      };
+    case "heatmap":
+      const heatmapSeries = [
+        {
+          type: "heatmap",
+          data: model.series[0]?.points.filter((point) => point.value != null && point.name != null).map((point) => [point.x, point.name, point.value]) ?? []
+        }
+      ];
+      return {
+        color: model.palette,
+        tooltip: model.tooltip === false ? undefined : { position: "top" },
+        xAxis: {
+          type: "category",
+          data: uniqueValues(model.series[0]?.points.map((point) => point.x))
+        },
+        yAxis: {
+          type: "category",
+          data: uniqueValues(model.series[0]?.points.map((point) => point.name))
+        },
+        visualMap: {
+          min: 0,
+          max: maxValue(model.series[0]?.points.map((point) => point.value)),
+          calculable: true,
+          orient: "horizontal",
+          left: "center",
+          bottom: 0
+        },
+        series: heatmapSeries
+      };
+    case "funnel":
+      const funnelSeries = [
+        {
+          type: "funnel",
+          data: model.series[0]?.points.filter((point) => point.value != null).map((point) => ({
+            name: point.name ?? "",
+            value: point.value
+          })) ?? []
+        }
+      ];
+      return {
+        color: model.palette,
+        tooltip: model.tooltip === false ? undefined : { trigger: "item" },
+        series: funnelSeries
+      };
+    case "geo":
+      if (!model.geo || model.geo.mode === "slippy-map" || !model.geo.geoJson) {
+        return {};
+      }
+      const geoSeries = [
+        {
+          type: model.geo.variant === "heatmap" ? "heatmap" : "scatter",
+          coordinateSystem: "geo",
+          data: model.series[0]?.points.filter((point) => point.longitude != null && point.latitude != null && point.value != null).map((point) => ({
+            name: point.name ?? "",
+            value: [
+              point.longitude,
+              point.latitude,
+              point.value
+            ]
+          })) ?? []
+        }
+      ];
+      return {
+        color: model.palette,
+        tooltip: model.tooltip === false ? undefined : { trigger: "item" },
+        geo: {
+          map: "contractspec-visualization-geo",
+          roam: true
+        },
+        series: geoSeries
+      };
+    default:
+      return {};
+  }
+}
+function uniqueValues(values) {
+  return Array.from(new Set((values ?? []).filter((value) => value != null).map(String)));
+}
+function maxValue(values) {
+  return Math.max(...(values ?? []).map((value) => value ?? 0), 1);
+}
+function toMarkLine(annotation) {
+  return {
+    yAxis: annotation.y,
+    name: annotation.label,
+    lineStyle: {
+      color: annotation.color ?? "#2563eb",
+      type: "solid"
+    }
+  };
+}
+function resolveCartesianSeriesType(type) {
+  if (type === "bar")
+    return "bar";
+  if (type === "scatter")
+    return "scatter";
+  return "line";
+}
+
 // src/index.ts
 function withPresentationNextAliases(config, opts = {}) {
   const uiWeb = opts.uiKitWeb ?? "@contractspec/lib.ui-kit-web";
@@ -51,5 +519,9 @@ function withPresentationMetroAliases(config, opts = {}) {
 }
 export {
   withPresentationNextAliases,
-  withPresentationMetroAliases
+  withPresentationMetroAliases,
+  formatVisualizationValue,
+  createVisualizationModel,
+  createEmptyTableState,
+  buildVisualizationEChartsOption
 };

package/dist/browser/table.js

@@ -0,0 +1,21 @@
+// src/table.ts
+function createEmptyTableState() {
+  return {
+    sorting: [],
+    pagination: {
+      pageIndex: 0,
+      pageSize: 25
+    },
+    columnVisibility: {},
+    columnSizing: {},
+    columnPinning: {
+      left: [],
+      right: []
+    },
+    expanded: {},
+    rowSelection: {}
+  };
+}
+export {
+  createEmptyTableState
+};