@jorgerdz/timeview 0.1.0

package/src/timeview/config.ts

@@ -0,0 +1,399 @@
+// config.ts — validation, normalization, and URL-safe config serialization.
+
+import { TV_PALETTES } from "./data";
+import { TV_VISUALIZER_BY_ID, type VisualizerId } from "./registry";
+import type {
+  BandedTimelineSpec,
+  CaptionPosition,
+  Density,
+  DensityHeatmapSpec,
+  HeatmapGroupBy,
+  HeatmapMeasure,
+  HeatmapScaleMode,
+  LaneCalendarSpec,
+  LaneMode,
+  LegendPosition,
+  MetricDefaultDays,
+  MetricStateMode,
+  MetricTimelineSpec,
+  MetricYAxisMode,
+  OverlapMode,
+  SpanMatrixSpec,
+  TimeBucketMode,
+  TimeDataset,
+  TodayValue,
+  ViewSpec,
+} from "./types";
+
+export interface TimeviewConfigV1 {
+  v: 1;
+  visualizer: VisualizerId;
+  dataset: TimeDataset;
+  spec: ViewSpec;
+  palette: string[];
+}
+
+export interface ValidationResult<T> {
+  value: T | null;
+  errors: string[];
+}
+
+const DENSITY_OPTIONS = ["comfortable", "compact"] as const satisfies readonly Density[];
+const LEGEND_OPTIONS = ["top", "bottom", "right", "off"] as const satisfies readonly LegendPosition[];
+const CAPTION_OPTIONS = ["top", "bottom", "off"] as const satisfies readonly CaptionPosition[];
+const OVERLAP_OPTIONS = ["lanes", "packed", "layered", "hatched"] as const satisfies readonly OverlapMode[];
+const LANE_OPTIONS = ["packed", "category"] as const satisfies readonly LaneMode[];
+const BUCKET_OPTIONS = ["day", "week"] as const satisfies readonly TimeBucketMode[];
+const MEASURE_OPTIONS = ["count", "duration"] as const satisfies readonly HeatmapMeasure[];
+const GROUP_OPTIONS = ["category", "none"] as const satisfies readonly HeatmapGroupBy[];
+const SCALE_OPTIONS = ["category", "uniform"] as const satisfies readonly HeatmapScaleMode[];
+const SPAN_ZOOM_MIN = 0.6;
+const SPAN_ZOOM_MAX = 2.5;
+const METRIC_STATE_OPTIONS = ["band", "tint", "off"] as const satisfies readonly MetricStateMode[];
+const METRIC_Y_OPTIONS = ["auto", "full"] as const satisfies readonly MetricYAxisMode[];
+const METRIC_DEFAULT_DAYS_OPTIONS = [30, 90, 180, 365] as const satisfies readonly MetricDefaultDays[];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function validDate(value: unknown): boolean {
+  return typeof value === "string" && !Number.isNaN(new Date(value).getTime());
+}
+
+function hasValue<T extends string>(options: readonly T[], value: unknown): value is T {
+  return typeof value === "string" && (options as readonly string[]).includes(value);
+}
+
+function hasNumberValue<T extends number>(options: readonly T[], value: unknown): value is T {
+  return typeof value === "number" && (options as readonly number[]).includes(value);
+}
+
+function readBool(value: unknown, fallback: boolean): boolean {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+function readNumber(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function clone<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+function pushInvalid(errors: string[], path: string, values: readonly string[]) {
+  errors.push(`${path} must be one of: ${values.join(", ")}.`);
+}
+
+export function validateTimeDataset(value: unknown): ValidationResult<TimeDataset> {
+  const errors: string[] = [];
+  if (!isRecord(value)) return { value: null, errors: ["Root must be a JSON object."] };
+
+  const data = value as Partial<TimeDataset>;
+  if (data.schemaVersion !== "timeview.dataset.v1") errors.push('schemaVersion must be "timeview.dataset.v1".');
+  if (typeof data.timezone !== "string" || !data.timezone.trim()) errors.push("timezone is required.");
+  if (!Array.isArray(data.labels)) errors.push("labels must be an array.");
+  if (!Array.isArray(data.events)) errors.push("events must be an array.");
+  if (!Array.isArray(data.intervals)) errors.push("intervals must be an array.");
+  if (errors.length) return { value: null, errors };
+
+  const ids = new Set<string>();
+  data.labels?.forEach((label, i) => {
+    if (!isRecord(label)) {
+      errors.push(`labels[${i}] must be an object.`);
+      return;
+    }
+    if (typeof label.id !== "string" || !label.id.trim()) errors.push(`labels[${i}].id is required.`);
+    if (typeof label.name !== "string" || !label.name.trim()) errors.push(`labels[${i}].name is required.`);
+    if (typeof label.id === "string") {
+      if (ids.has(label.id)) errors.push(`Duplicate label id "${label.id}".`);
+      ids.add(label.id);
+    }
+  });
+
+  data.events?.forEach((event, i) => {
+    if (!isRecord(event)) {
+      errors.push(`events[${i}] must be an object.`);
+      return;
+    }
+    if (typeof event.id !== "string" || !event.id.trim()) errors.push(`events[${i}].id is required.`);
+    if (typeof event.title !== "string" || !event.title.trim()) errors.push(`events[${i}].title is required.`);
+    if (!validDate(event.at)) errors.push(`events[${i}].at must be a valid date string.`);
+    if (event.labelIds != null && !Array.isArray(event.labelIds)) {
+      errors.push(`events[${i}].labelIds must be an array.`);
+    } else {
+      event.labelIds?.forEach((id) => {
+        if (typeof id !== "string" || !ids.has(id)) errors.push(`events[${i}] references unknown label "${String(id)}".`);
+      });
+    }
+  });
+
+  data.intervals?.forEach((interval, i) => {
+    if (!isRecord(interval)) {
+      errors.push(`intervals[${i}] must be an object.`);
+      return;
+    }
+    if (typeof interval.id !== "string" || !interval.id.trim()) errors.push(`intervals[${i}].id is required.`);
+    if (typeof interval.title !== "string" || !interval.title.trim()) errors.push(`intervals[${i}].title is required.`);
+    const range = interval.range;
+    if (!isRecord(range)) {
+      errors.push(`intervals[${i}].range is required.`);
+      return;
+    }
+    if (!validDate(range.start)) errors.push(`intervals[${i}].range.start must be a valid date string.`);
+    if (!validDate(range.end)) errors.push(`intervals[${i}].range.end must be a valid date string.`);
+    if (validDate(range.start) && validDate(range.end) && new Date(range.end as string).getTime() < new Date(range.start as string).getTime()) {
+      errors.push(`intervals[${i}].range.end must be after start.`);
+    }
+    if (interval.labelIds != null && !Array.isArray(interval.labelIds)) {
+      errors.push(`intervals[${i}].labelIds must be an array.`);
+    } else {
+      interval.labelIds?.forEach((id) => {
+        if (typeof id !== "string" || !ids.has(id)) errors.push(`intervals[${i}] references unknown label "${String(id)}".`);
+      });
+    }
+  });
+
+  if (data.series != null) {
+    if (!isRecord(data.series)) {
+      errors.push("series must be an object.");
+    } else {
+      if (typeof data.series.id !== "string" || !data.series.id.trim()) errors.push("series.id is required.");
+      if (typeof data.series.name !== "string" || !data.series.name.trim()) errors.push("series.name is required.");
+      if (data.series.unit != null && typeof data.series.unit !== "string") errors.push("series.unit must be a string.");
+      if (!Array.isArray(data.series.samples)) {
+        errors.push("series.samples must be an array.");
+      } else {
+        data.series.samples.forEach((sample, i) => {
+          if (!isRecord(sample)) {
+            errors.push(`series.samples[${i}] must be an object.`);
+            return;
+          }
+          if (!validDate(sample.at)) errors.push(`series.samples[${i}].at must be a valid date string.`);
+          if (typeof sample.value !== "number" || !Number.isFinite(sample.value)) errors.push(`series.samples[${i}].value must be a finite number.`);
+        });
+      }
+      if (data.series.target != null) {
+        if (!isRecord(data.series.target)) {
+          errors.push("series.target must be an object.");
+        } else if (typeof data.series.target.value !== "number" || !Number.isFinite(data.series.target.value)) {
+          errors.push("series.target.value must be a finite number.");
+        }
+      }
+    }
+  }
+
+  return { value: errors.length ? null : (value as unknown as TimeDataset), errors };
+}
+
+function normalizeCaption(defaultSpec: ViewSpec, input: Record<string, unknown>, errors: string[]) {
+  const fallback = defaultSpec.caption || { position: "bottom" as CaptionPosition };
+  if (!isRecord(input.caption)) return fallback;
+  const position = input.caption.enabled === false ? "off" : input.caption.position;
+  if (position != null && !hasValue(CAPTION_OPTIONS, position)) pushInvalid(errors, "caption.position", CAPTION_OPTIONS);
+  return {
+    enabled: input.caption.enabled !== false,
+    position: hasValue(CAPTION_OPTIONS, position) ? position : fallback.position,
+    text: typeof input.caption.text === "string" ? input.caption.text : fallback.text,
+  };
+}
+
+function normalizeLegend(defaultSpec: ViewSpec, input: Record<string, unknown>, errors: string[]) {
+  const fallback = defaultSpec.legend || { position: "bottom" as LegendPosition };
+  if (!isRecord(input.legend)) return fallback;
+  const position = input.legend.enabled === false ? "off" : input.legend.position;
+  if (position != null && !hasValue(LEGEND_OPTIONS, position)) pushInvalid(errors, "legend.position", LEGEND_OPTIONS);
+  return {
+    enabled: input.legend.enabled !== false,
+    position: hasValue(LEGEND_OPTIONS, position) ? position : fallback.position,
+  };
+}
+
+function normalizeEvents(defaultSpec: ViewSpec, input: Record<string, unknown>) {
+  const fallback = defaultSpec.events || {};
+  if (!isRecord(input.events)) return fallback;
+  return {
+    showPoints: readBool(input.events.showPoints, fallback.showPoints !== false),
+    showLabels: readBool(input.events.showLabels, fallback.showLabels !== false),
+    showMarkers: readBool(input.events.showMarkers, fallback.showMarkers !== false),
+  };
+}
+
+function common(defaultSpec: ViewSpec, input: Record<string, unknown>, errors: string[]) {
+  if (input.density != null && !hasValue(DENSITY_OPTIONS, input.density)) pushInvalid(errors, "density", DENSITY_OPTIONS);
+  return {
+    title: typeof input.title === "string" ? input.title : defaultSpec.title,
+    density: hasValue(DENSITY_OPTIONS, input.density) ? input.density : defaultSpec.density,
+    caption: normalizeCaption(defaultSpec, input, errors),
+  };
+}
+
+export function normalizeViewSpec(visualizer: VisualizerId, rawSpec: unknown): ValidationResult<ViewSpec> {
+  const entry = TV_VISUALIZER_BY_ID[visualizer];
+  const defaultSpec = entry.defaultSpec;
+  const input = isRecord(rawSpec) ? rawSpec : {};
+  const errors: string[] = [];
+
+  if (!isRecord(rawSpec)) errors.push("Spec root must be a JSON object.");
+  if (input.kind != null && input.kind !== visualizer) errors.push(`kind must be "${visualizer}" for ${entry.label}.`);
+
+  if (visualizer === "bandedTimeline") {
+    if (input.overlapMode != null && !hasValue(OVERLAP_OPTIONS, input.overlapMode)) pushInvalid(errors, "overlapMode", OVERLAP_OPTIONS);
+    const spec: BandedTimelineSpec = {
+      kind: "bandedTimeline",
+      ...common(defaultSpec, input, errors),
+      legend: normalizeLegend(defaultSpec, input, errors),
+      events: normalizeEvents(defaultSpec, input),
+      overlapMode: hasValue(OVERLAP_OPTIONS, input.overlapMode) ? input.overlapMode : (defaultSpec as BandedTimelineSpec).overlapMode,
+    };
+    return { value: spec, errors };
+  }
+
+  if (visualizer === "laneCalendar") {
+    if (input.laneMode != null && !hasValue(LANE_OPTIONS, input.laneMode)) pushInvalid(errors, "laneMode", LANE_OPTIONS);
+    if (input.today != null && input.today !== "auto" && !validDate(input.today)) errors.push('today must be "auto", an ISO date string, null, or omitted.');
+    const spec: LaneCalendarSpec = {
+      kind: "laneCalendar",
+      ...common(defaultSpec, input, errors),
+      legend: normalizeLegend(defaultSpec, input, errors),
+      events: normalizeEvents(defaultSpec, input),
+      laneMode: hasValue(LANE_OPTIONS, input.laneMode) ? input.laneMode : (defaultSpec as LaneCalendarSpec).laneMode,
+      today: input.today === "auto" || validDate(input.today) ? (input.today as TodayValue) : input.today === null ? null : undefined,
+    };
+    return { value: spec, errors };
+  }
+
+  if (visualizer === "spanMatrix") {
+    if (input.bucket != null && !hasValue(BUCKET_OPTIONS, input.bucket)) pushInvalid(errors, "bucket", BUCKET_OPTIONS);
+    if (input.groupBy != null && !hasValue(GROUP_OPTIONS, input.groupBy)) pushInvalid(errors, "groupBy", GROUP_OPTIONS);
+    if (input.today != null && !validDate(input.today)) errors.push("today must be an ISO date string, null, or omitted.");
+    if (
+      input.zoom != null &&
+      (typeof input.zoom !== "number" || !Number.isFinite(input.zoom) || input.zoom < SPAN_ZOOM_MIN || input.zoom > SPAN_ZOOM_MAX)
+    ) {
+      errors.push(`zoom must be a number from ${SPAN_ZOOM_MIN} to ${SPAN_ZOOM_MAX}.`);
+    }
+
+    const spec: SpanMatrixSpec = {
+      kind: "spanMatrix",
+      ...common(defaultSpec, input, errors),
+      legend: normalizeLegend(defaultSpec, input, errors),
+      events: normalizeEvents(defaultSpec, input),
+      bucket: hasValue(BUCKET_OPTIONS, input.bucket) ? input.bucket : (defaultSpec as SpanMatrixSpec).bucket,
+      groupBy: hasValue(GROUP_OPTIONS, input.groupBy) ? input.groupBy : (defaultSpec as SpanMatrixSpec).groupBy,
+      zoom: Math.min(SPAN_ZOOM_MAX, Math.max(SPAN_ZOOM_MIN, readNumber(input.zoom, (defaultSpec as SpanMatrixSpec).zoom || 1))),
+      showCounts: readBool(input.showCounts, (defaultSpec as SpanMatrixSpec).showCounts !== false),
+      today: validDate(input.today) ? (input.today as string) : input.today === null ? null : (defaultSpec as SpanMatrixSpec).today,
+    };
+    return { value: spec, errors };
+  }
+
+  if (visualizer === "metricTimeline") {
+    if (input.stateMode != null && !hasValue(METRIC_STATE_OPTIONS, input.stateMode)) pushInvalid(errors, "stateMode", METRIC_STATE_OPTIONS);
+    if (input.yAxis != null && !hasValue(METRIC_Y_OPTIONS, input.yAxis)) pushInvalid(errors, "yAxis", METRIC_Y_OPTIONS);
+    if (input.defaultDays != null && !hasNumberValue(METRIC_DEFAULT_DAYS_OPTIONS, input.defaultDays)) errors.push("defaultDays must be one of: 30, 90, 180, 365.");
+    if (input.today != null && !validDate(input.today)) errors.push("today must be an ISO date string, null, or omitted.");
+
+    const metricDefault = defaultSpec as MetricTimelineSpec;
+    const spec: MetricTimelineSpec = {
+      kind: "metricTimeline",
+      ...common(defaultSpec, input, errors),
+      legend: normalizeLegend(defaultSpec, input, errors),
+      events: normalizeEvents(defaultSpec, input),
+      stateMode: hasValue(METRIC_STATE_OPTIONS, input.stateMode) ? input.stateMode : metricDefault.stateMode,
+      yAxis: hasValue(METRIC_Y_OPTIONS, input.yAxis) ? input.yAxis : metricDefault.yAxis,
+      defaultDays: hasNumberValue(METRIC_DEFAULT_DAYS_OPTIONS, input.defaultDays) ? input.defaultDays : metricDefault.defaultDays,
+      today: validDate(input.today) ? (input.today as string) : input.today === null ? null : metricDefault.today,
+      showPoints: readBool(input.showPoints, metricDefault.showPoints !== false),
+      showValues: readBool(input.showValues, metricDefault.showValues === true),
+      showTarget: readBool(input.showTarget, metricDefault.showTarget !== false),
+      minimap: readBool(input.minimap, metricDefault.minimap !== false),
+    };
+    return { value: spec, errors };
+  }
+
+  if (input.bucket != null && !hasValue(BUCKET_OPTIONS, input.bucket)) pushInvalid(errors, "bucket", BUCKET_OPTIONS);
+  if (input.measure != null && !hasValue(MEASURE_OPTIONS, input.measure)) pushInvalid(errors, "measure", MEASURE_OPTIONS);
+  if (input.groupBy != null && !hasValue(GROUP_OPTIONS, input.groupBy)) pushInvalid(errors, "groupBy", GROUP_OPTIONS);
+  if (input.scaleMode != null && !hasValue(SCALE_OPTIONS, input.scaleMode)) pushInvalid(errors, "scaleMode", SCALE_OPTIONS);
+
+  const spec: DensityHeatmapSpec = {
+    kind: "densityHeatmap",
+    ...common(defaultSpec, input, errors),
+    bucket: hasValue(BUCKET_OPTIONS, input.bucket) ? input.bucket : (defaultSpec as DensityHeatmapSpec).bucket,
+    measure: hasValue(MEASURE_OPTIONS, input.measure) ? input.measure : (defaultSpec as DensityHeatmapSpec).measure,
+    groupBy: hasValue(GROUP_OPTIONS, input.groupBy) ? input.groupBy : (defaultSpec as DensityHeatmapSpec).groupBy,
+    scaleMode: hasValue(SCALE_OPTIONS, input.scaleMode) ? input.scaleMode : (defaultSpec as DensityHeatmapSpec).scaleMode,
+    showValues: readBool(input.showValues, (defaultSpec as DensityHeatmapSpec).showValues !== false),
+  };
+  return { value: spec, errors };
+}
+
+export function validateViewSpec(visualizer: VisualizerId, value: unknown): ValidationResult<ViewSpec> {
+  const result = normalizeViewSpec(visualizer, value);
+  return { value: result.errors.length ? null : result.value, errors: result.errors };
+}
+
+export function normalizePalette(value: unknown): string[] {
+  return Array.isArray(value) && value.length > 0 && value.every((c) => typeof c === "string") ? value : TV_PALETTES.Studio;
+}
+
+export function normalizeTimeviewConfig(raw: unknown): ValidationResult<TimeviewConfigV1> {
+  const errors: string[] = [];
+  if (!isRecord(raw)) return { value: null, errors: ["Config root must be a JSON object."] };
+  if (raw.v !== 1) errors.push("Config version must be 1.");
+  if (typeof raw.visualizer !== "string" || !(raw.visualizer in TV_VISUALIZER_BY_ID)) errors.push("visualizer must be a known Timeview visualizer.");
+
+  const visualizer = typeof raw.visualizer === "string" && raw.visualizer in TV_VISUALIZER_BY_ID ? (raw.visualizer as VisualizerId) : "bandedTimeline";
+  const dataset = validateTimeDataset(raw.dataset);
+  const spec = normalizeViewSpec(visualizer, raw.spec);
+  errors.push(...dataset.errors.map((error) => `dataset: ${error}`));
+  errors.push(...spec.errors.map((error) => `spec: ${error}`));
+
+  if (!dataset.value || !spec.value || errors.length) return { value: null, errors };
+
+  return {
+    value: {
+      v: 1,
+      visualizer,
+      dataset: dataset.value,
+      spec: spec.value,
+      palette: normalizePalette(raw.palette),
+    },
+    errors: [],
+  };
+}
+
+function base64UrlEncode(text: string): string {
+  const bytes = new TextEncoder().encode(text);
+  let binary = "";
+  bytes.forEach((byte) => {
+    binary += String.fromCharCode(byte);
+  });
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+
+function base64UrlDecode(text: string): string {
+  const padded = text.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(text.length / 4) * 4, "=");
+  const binary = atob(padded);
+  const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+  return new TextDecoder().decode(bytes);
+}
+
+export function encodeTimeviewConfig(config: TimeviewConfigV1): string {
+  return base64UrlEncode(JSON.stringify(config));
+}
+
+export function decodeTimeviewConfig(hashOrToken: string): ValidationResult<TimeviewConfigV1> {
+  const token = hashOrToken.startsWith("#tv=") ? hashOrToken.slice(4) : hashOrToken;
+  if (!token) return { value: null, errors: ["Missing #tv config token."] };
+  try {
+    return normalizeTimeviewConfig(JSON.parse(base64UrlDecode(token)) as unknown);
+  } catch (err) {
+    return { value: null, errors: [err instanceof Error ? err.message : "Invalid encoded config."] };
+  }
+}
+
+export function cloneTimeviewConfig(config: TimeviewConfigV1): TimeviewConfigV1 {
+  return clone(config);
+}