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

package/dist/visualization.model.builders.js

@@ -0,0 +1,291 @@
+// @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
+    }
+  };
+}
+export {
+  buildMetricModel,
+  buildHeatmapModel,
+  buildGeoModel,
+  buildDistributionModel,
+  buildCartesianModel
+};

package/dist/visualization.model.d.ts

@@ -0,0 +1,3 @@
+import type { VisualizationSpec } from '@contractspec/lib.contracts-spec/visualizations';
+import type { ContractVisualizationRenderModel } from './visualization.types';
+export declare function createVisualizationModel(spec: VisualizationSpec, data: unknown): ContractVisualizationRenderModel;

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

@@ -0,0 +1,60 @@
+import type { VisualizationDimension, VisualizationMeasure, VisualizationSpec } from '@contractspec/lib.contracts-spec/visualizations';
+import type { ContractVisualizationAnnotationModel, ContractVisualizationAxisModel, ContractVisualizationTableAlternative } from './visualization.types';
+export interface VisualizationModelMaps {
+    dimensions: Map<string, VisualizationDimension>;
+    measures: Map<string, VisualizationMeasure>;
+}
+export declare function createVisualizationMaps(spec: VisualizationSpec): VisualizationModelMaps;
+export declare function createVisualizationBaseModel(spec: VisualizationSpec, rows: Record<string, unknown>[], maps: VisualizationModelMaps): {
+    kind: "heatmap" | "metric" | "cartesian" | "pie" | "funnel" | "geo";
+    title: string | undefined;
+    description: string;
+    summary: string;
+    warnings: string[];
+    palette: string[] | undefined;
+    legend: boolean | undefined;
+    tooltip: boolean | undefined;
+    drilldown: import("@contractspec/lib.contracts-spec").VisualizationDrilldown | undefined;
+    thresholds: import("@contractspec/lib.contracts-spec").VisualizationThreshold[];
+    annotations: ContractVisualizationAnnotationModel[];
+    table: ContractVisualizationTableAlternative;
+};
+export declare function createMeasureSeries(measureKey: string, measures: Map<string, VisualizationMeasure>, rows: Record<string, unknown>[], dimension?: VisualizationDimension, config?: {
+    key: string;
+    label: string;
+    type?: string;
+    color?: string;
+    stack?: string;
+    smooth?: boolean;
+}): {
+    key: string;
+    label: string;
+    type: string | undefined;
+    color: string | undefined;
+    stack: string | undefined;
+    smooth: boolean | undefined;
+    points: {
+        id: string;
+        raw: Record<string, unknown>;
+        x: unknown;
+        y: number | null;
+        value: number | null;
+    }[];
+} | null;
+export declare function defaultSeries(keys: string[]): {
+    key: string;
+    label: string;
+    measure: string;
+}[];
+export declare function createAxis(dimension?: VisualizationDimension): ContractVisualizationAxisModel | undefined;
+export declare function createValueAxis(key: string | undefined, measures: Map<string, VisualizationMeasure>): {
+    key: string;
+    label: string;
+    type: "number";
+    format: import("@contractspec/lib.contracts-spec").VisualizationValueFormat | undefined;
+} | undefined;
+export declare function readValue(row: Record<string, unknown>, measure?: VisualizationMeasure): unknown;
+export declare function readDimensionValue(row: Record<string, unknown>, dimension?: VisualizationDimension): unknown;
+export declare function numericValue(row: Record<string, unknown>, measure?: VisualizationMeasure): number | null;
+export declare function numericPathValue(row: Record<string, unknown>, dimension?: VisualizationDimension): number | null;
+export declare function stringValue(row: Record<string, unknown>, dimension?: VisualizationDimension): string | undefined;

package/dist/visualization.model.helpers.js

@@ -0,0 +1,200 @@
+// @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
+  };
+}
+export {
+  stringValue,
+  readValue,
+  readDimensionValue,
+  numericValue,
+  numericPathValue,
+  defaultSeries,
+  createVisualizationMaps,
+  createVisualizationBaseModel,
+  createValueAxis,
+  createMeasureSeries,
+  createAxis
+};