@outsidedata/dolex 0.1.0

package/src/patterns/definitions/time/area.ts

@@ -0,0 +1,111 @@
+/**
+ * Area Chart — volume over time with optional stacking.
+ *
+ * Like a line chart but with the area below filled, emphasizing
+ * magnitude. Stacked variant shows composition changing over time.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const areaPattern: VisualizationPattern = {
+  id: 'area',
+  name: 'Area Chart',
+  category: 'time',
+  description:
+    'Filled area chart emphasizing volume and magnitude over time. Supports single-series, multi-series overlapping, stacked, and normalized (100%) stacked modes. Multiple interpolation curves: monotone (smooth), linear, step (staircase), curve (smooth rounded), cardinal, catmullRom. Configurable fill opacity.',
+  bestFor:
+    'Showing volume/magnitude over time. Revenue over time, website traffic, cumulative totals. Stacked: market share over time, revenue by product line. Step curve for discrete intervals (e.g. monthly billing). Normalized for proportion tracking.',
+  notFor:
+    'Comparing exact values across many series (overlapping areas obscure), non-temporal data, precise comparisons (use bar).',
+
+  dataRequirements: {
+    minRows: 3,
+    requiredColumns: [
+      { type: 'date', count: 1, description: 'Time axis' },
+      { type: 'numeric', count: 1, description: 'Value over time' },
+    ],
+    requiresTimeSeries: true,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Time series with intent for volume, area, magnitude, or cumulative',
+      weight: 55,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.hasTimeSeries &&
+          ctx.dataShape.numericColumnCount >= 1 &&
+          /\b(area|volume|magnitude|cumulative|total|fill|stacked\s*area|revenue|traffic|visitors)\b/i.test(ctx.intent)
+        );
+      },
+    },
+    {
+      condition: 'Stacked composition over time with explicit stacked intent',
+      weight: 60,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.hasTimeSeries &&
+          ctx.dataShape.seriesCount >= 2 &&
+          ctx.dataShape.seriesCount <= 8 &&
+          /\b(stacked|composition\s+over\s+time|share\s+over\s+time|breakdown\s+over\s+time|proportion)\b/i.test(ctx.intent)
+        );
+      },
+    },
+    {
+      condition: 'Penalize when no time dimension exists',
+      weight: -50,
+      matches: (ctx) => {
+        return !ctx.dataShape.hasTimeSeries && ctx.dataShape.dateColumnCount === 0;
+      },
+    },
+    {
+      condition: 'Penalize for too many series — visual clutter',
+      weight: -30,
+      matches: (ctx) => {
+        return ctx.dataShape.seriesCount > 8;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const timeCol = columns[0];
+    const valueCol = columns.length > 1 ? columns[1] : columns[0];
+    const seriesCol = columns.length > 2 ? columns[2] : undefined;
+
+    const spec: VisualizationSpec = {
+      pattern: 'area',
+      title: options?.title ?? `${valueCol} over ${timeCol}`,
+      data,
+      encoding: {
+        x: {
+          field: timeCol,
+          type: 'temporal',
+          title: timeCol,
+        },
+        y: {
+          field: valueCol,
+          type: 'quantitative',
+          title: valueCol,
+        },
+        color: seriesCol
+          ? {
+              field: seriesCol,
+              type: 'nominal',
+              title: seriesCol,
+            }
+          : undefined,
+      },
+      config: {
+        timeField: timeCol,
+        valueField: valueCol,
+        seriesField: seriesCol ?? null,
+        stacked: options?.stacked ?? false,
+        normalized: options?.normalized ?? false,
+        curve: options?.curve ?? 'monotone',
+        opacity: options?.opacity ?? 0.7,
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/time/calendar-heatmap.ts

@@ -0,0 +1,121 @@
+/**
+ * Calendar Heatmap — daily patterns.
+ *
+ * Shows values mapped onto a calendar grid, revealing day-of-week
+ * patterns, seasonal effects, and daily variations. Made famous
+ * by GitHub's contribution graph.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const calendarHeatmapPattern: VisualizationPattern = {
+  id: 'calendar-heatmap',
+  name: 'Calendar Heatmap',
+  category: 'time',
+  description:
+    'Values mapped onto a calendar grid (weeks as columns, days as rows). Color intensity encodes magnitude. Reveals day-of-week effects, seasonal patterns, and anomalous days.',
+  bestFor:
+    'Daily data over months or years: website traffic, sales, commits, exercise, temperature. Finding day-of-week and seasonal patterns.',
+  notFor:
+    'Non-daily data (weekly, monthly — use line), very short time spans (use bar), non-temporal data.',
+
+  dataRequirements: {
+    minRows: 30,
+    requiredColumns: [
+      { type: 'date', count: 1, description: 'Daily date' },
+      { type: 'numeric', count: 1, description: 'Value for each day' },
+    ],
+    requiresTimeSeries: true,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Daily data spanning at least a month — calendar heatmap is ideal',
+      weight: 80,
+      matches: (ctx) => {
+        if (!ctx.dataShape.hasTimeSeries || ctx.dataShape.dateColumnCount === 0) return false;
+        const dateCol = ctx.columns.find((c) => c.type === 'date');
+        // Need enough unique dates to represent daily data
+        return dateCol !== undefined && dateCol.uniqueCount >= 28;
+      },
+    },
+    {
+      condition: 'Intent mentions daily patterns, calendar, or day-of-week',
+      weight: 60,
+      matches: (ctx) => {
+        return /\b(daily|calendar|day.of.week|weekday|weekend|heatmap|every\s+day|github|activity|contribution)\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'Large number of time points — calendar is more compact than line for daily data',
+      weight: 30,
+      matches: (ctx) => {
+        return ctx.dataShape.hasTimeSeries && ctx.dataShape.rowCount >= 90;
+      },
+    },
+    {
+      condition: 'Penalize for non-daily granularity (few time points suggests monthly/yearly)',
+      weight: -40,
+      matches: (ctx) => {
+        const dateCol = ctx.columns.find((c) => c.type === 'date');
+        return dateCol !== undefined && dateCol.uniqueCount < 20;
+      },
+    },
+    {
+      condition: 'Penalize for no time dimension',
+      weight: -50,
+      matches: (ctx) => {
+        return !ctx.dataShape.hasTimeSeries;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const dateCol = columns[0];
+    const valueCol = columns.length > 1 ? columns[1] : columns[0];
+
+    // Compute value range for color scale
+    const values = data.map((d) => Number(d[valueCol])).filter((v) => !isNaN(v));
+    const minVal = Math.min(...values);
+    const maxVal = Math.max(...values);
+
+    const spec: VisualizationSpec = {
+      pattern: 'calendar-heatmap',
+      title: options?.title ?? `${valueCol} calendar`,
+      data,
+      encoding: {
+        x: {
+          field: dateCol,
+          type: 'temporal',
+          title: 'Week',
+        },
+        y: {
+          field: '_dayOfWeek',
+          type: 'ordinal',
+          title: 'Day',
+        },
+        color: {
+          field: valueCol,
+          type: 'quantitative',
+          scale: {
+            domain: [minVal, maxVal],
+            range: options?.colorRange ?? ['#ebedf0', '#9be9a8', '#40c463', '#30a14e', '#216e39'],
+          },
+          title: valueCol,
+        },
+      },
+      config: {
+        timeField: dateCol,
+        valueField: valueCol,
+        cellSize: options?.cellSize ?? 15,
+        cellGap: options?.cellGap ?? 2,
+        showMonthLabels: options?.showMonthLabels ?? true,
+        showDayLabels: options?.showDayLabels ?? true,
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/time/horizon-chart.ts

@@ -0,0 +1,105 @@
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const horizonChartPattern: VisualizationPattern = {
+  id: 'horizon-chart',
+  name: 'Horizon Chart',
+  category: 'time',
+  description:
+    'Ultra-compact time series that folds the y-axis into color bands, layering positive values and mirroring negatives. Shows many series in very little vertical space.',
+  bestFor:
+    'Dashboard monitoring of 10-50+ time series simultaneously. Server metrics, stock prices, sensor readings. When you need to spot anomalies across many series at once.',
+  notFor:
+    'Precise value reading, unfamiliar audiences (requires learning), fewer than 5 series.',
+
+  dataRequirements: {
+    minRows: 10,
+    requiredColumns: [
+      { type: 'date', count: 1, description: 'Time axis' },
+      { type: 'numeric', count: 1, description: 'Value to visualize' },
+      { type: 'categorical', count: 1, description: 'Series identifier (10-50 series)' },
+    ],
+    requiresTimeSeries: true,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Explicit horizon chart intent',
+      weight: 80,
+      matches: (ctx) => {
+        return /\bhorizon\b/i.test(ctx.intent);
+      },
+    },
+    {
+      condition: 'Many-series time monitoring with compact or dense intent',
+      weight: 55,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.hasTimeSeries &&
+          ctx.dataShape.seriesCount >= 10 &&
+          ctx.dataShape.numericColumnCount >= 1 &&
+          /\b(compact|dense|monitor|overview|dashboard|anomal|many\s*series|all\s*series|sensor|server|metric)\b/i.test(ctx.intent)
+        );
+      },
+    },
+    {
+      condition: 'Large number of time series (10+) without specific intent',
+      weight: 35,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.hasTimeSeries &&
+          ctx.dataShape.seriesCount >= 10 &&
+          ctx.dataShape.numericColumnCount >= 1
+        );
+      },
+    },
+    {
+      condition: 'Penalize when no time dimension exists',
+      weight: -50,
+      matches: (ctx) => {
+        return !ctx.dataShape.hasTimeSeries && ctx.dataShape.dateColumnCount === 0;
+      },
+    },
+    {
+      condition: 'Penalize for too few series — use line chart instead',
+      weight: -40,
+      matches: (ctx) => {
+        return ctx.dataShape.seriesCount < 5;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const dateCol = columns[0];
+    const valueCol = columns.length > 1 ? columns[1] : columns[0];
+    const seriesCol = columns.length > 2 ? columns[2] : undefined;
+
+    const spec: VisualizationSpec = {
+      pattern: 'horizon-chart',
+      title: options?.title ?? `${valueCol} across series`,
+      data,
+      encoding: {
+        x: {
+          field: dateCol,
+          type: 'temporal',
+          title: dateCol,
+        },
+        color: seriesCol
+          ? {
+              field: seriesCol,
+              type: 'nominal',
+              title: seriesCol,
+            }
+          : undefined,
+      },
+      config: {
+        timeField: dateCol,
+        valueField: valueCol,
+        seriesField: seriesCol ?? null,
+        bands: options?.bands ?? 3,
+        mode: options?.mode ?? 'mirror',
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/time/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Time patterns — for showing change, trends, and patterns over time.
+ */
+
+export { linePattern } from './line.js';
+export { smallMultiplesPattern } from './small-multiples.js';
+export { sparklineGridPattern } from './sparkline-grid.js';
+export { calendarHeatmapPattern } from './calendar-heatmap.js';

package/src/patterns/definitions/time/line.ts

@@ -0,0 +1,120 @@
+/**
+ * Line Chart — standard time series.
+ *
+ * The baseline temporal pattern. Connects data points
+ * chronologically to show trends, cycles, and change over time.
+ * Works best with a single series or 2-5 series.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const linePattern: VisualizationPattern = {
+  id: 'line',
+  name: 'Line Chart',
+  category: 'time',
+  description:
+    'Points connected chronologically by lines. The standard for showing trends, cycles, seasonality, and change over continuous time.',
+  bestFor:
+    'Single time series or comparing 2-5 series. Showing trends, growth patterns, seasonal effects.',
+  notFor:
+    'More than 5 series (spaghetti — use small multiples), categorical data (use bar), distribution (use histogram).',
+
+  dataRequirements: {
+    minRows: 3,
+    requiredColumns: [
+      { type: 'date', count: 1, description: 'Time axis' },
+      { type: 'numeric', count: 1, description: 'Value over time' },
+    ],
+    requiresTimeSeries: true,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Time series data with 1-5 series — line chart is the standard',
+      weight: 60,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.hasTimeSeries &&
+          ctx.dataShape.numericColumnCount >= 1 &&
+          ctx.dataShape.seriesCount <= 5
+        );
+      },
+    },
+    {
+      condition: 'Intent mentions trend, over time, or time series',
+      weight: 40,
+      matches: (ctx) => {
+        return /\b(trend|over\s+time|time\s*series|month|year|quarter|growth|decline|trajectory|progress)\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'Single series with many time points — classic line chart',
+      weight: 30,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.hasTimeSeries &&
+          ctx.dataShape.seriesCount <= 1 &&
+          ctx.dataShape.rowCount >= 5
+        );
+      },
+    },
+    {
+      condition: 'Penalize for too many series — spaghetti chart',
+      weight: -40,
+      matches: (ctx) => {
+        return ctx.dataShape.seriesCount > 5 && ctx.dataShape.hasTimeSeries;
+      },
+    },
+    {
+      condition: 'Penalize when no time dimension exists',
+      weight: -50,
+      matches: (ctx) => {
+        return !ctx.dataShape.hasTimeSeries && ctx.dataShape.dateColumnCount === 0;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const timeCol = columns[0];
+    const valueCol = columns.length > 1 ? columns[1] : columns[0];
+    const seriesCol = columns.length > 2 ? columns[2] : undefined;
+
+    const spec: VisualizationSpec = {
+      pattern: 'line',
+      title: options?.title ?? `${valueCol} over ${timeCol}`,
+      data,
+      encoding: {
+        x: {
+          field: timeCol,
+          type: 'temporal',
+          title: timeCol,
+        },
+        y: {
+          field: valueCol,
+          type: 'quantitative',
+          title: valueCol,
+        },
+        color: seriesCol
+          ? {
+              field: seriesCol,
+              type: 'nominal',
+              title: seriesCol,
+            }
+          : undefined,
+      },
+      config: {
+        timeField: timeCol,
+        valueField: valueCol,
+        seriesField: seriesCol ?? null,
+        showPoints: options?.showPoints ?? (data.length <= 50),
+        showArea: options?.showArea ?? false,
+        interpolation: options?.interpolation ?? 'monotone',
+        strokeWidth: options?.strokeWidth ?? 2,
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/time/small-multiples.ts

@@ -0,0 +1,113 @@
+/**
+ * Small Multiples — N > 5 series, avoids spaghetti.
+ *
+ * Instead of overlaying many lines on one chart (spaghetti),
+ * creates a grid of individual mini-charts, one per series.
+ * Each shares the same axes for easy comparison while keeping
+ * individual patterns readable.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const smallMultiplesPattern: VisualizationPattern = {
+  id: 'small-multiples',
+  name: 'Small Multiples',
+  category: 'time',
+  description:
+    'A grid of small charts, one per series, all sharing the same axes. Avoids the spaghetti problem of overlaying many time series while enabling comparison.',
+  bestFor:
+    'Comparing 5-25 time series: stock prices of multiple companies, temperature by city, sales by product line.',
+  notFor:
+    'Fewer than 4 series (use regular line chart), more than 30 series (use sparkline grid), single series.',
+
+  dataRequirements: {
+    minRows: 20,
+    requiredColumns: [
+      { type: 'date', count: 1, description: 'Shared time axis' },
+      { type: 'numeric', count: 1, description: 'Value to plot' },
+      { type: 'categorical', count: 1, description: 'Series identifier (one chart per value)' },
+    ],
+    requiresTimeSeries: true,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Many series (5-25) over time — small multiples avoids spaghetti',
+      weight: 80,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.hasTimeSeries &&
+          ctx.dataShape.seriesCount >= 5 &&
+          ctx.dataShape.seriesCount <= 25 &&
+          ctx.dataShape.numericColumnCount >= 1
+        );
+      },
+    },
+    {
+      condition: 'Intent mentions comparison of many series over time',
+      weight: 50,
+      matches: (ctx) => {
+        return /\b(small\s*multiple|facet|each\s+(country|city|product|company|region|team)|all\s+.*\s+over\s+time|individual\s+trend)\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'More than 5 series detected on time data — line chart will be spaghetti',
+      weight: 60,
+      matches: (ctx) => {
+        return ctx.dataShape.hasTimeSeries && ctx.dataShape.seriesCount > 5;
+      },
+    },
+    {
+      condition: 'Penalize for few series — regular line chart works fine',
+      weight: -40,
+      matches: (ctx) => {
+        return ctx.dataShape.seriesCount < 4;
+      },
+    },
+    {
+      condition: 'Penalize for no time dimension',
+      weight: -50,
+      matches: (ctx) => {
+        return !ctx.dataShape.hasTimeSeries;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const timeCol = columns[0];
+    const valueCol = columns.length > 1 ? columns[1] : columns[0];
+    const seriesCol = columns.length > 2 ? columns[2] : columns.length > 1 ? columns[1] : columns[0];
+
+    const spec: VisualizationSpec = {
+      pattern: 'small-multiples',
+      title: options?.title ?? `${valueCol} over ${timeCol} by ${seriesCol}`,
+      data,
+      encoding: {
+        x: {
+          field: timeCol,
+          type: 'temporal',
+          title: timeCol,
+        },
+        y: {
+          field: valueCol,
+          type: 'quantitative',
+          title: valueCol,
+        },
+        facet: {
+          field: seriesCol,
+          type: 'nominal',
+          title: seriesCol,
+        },
+      },
+      config: {
+        timeField: timeCol,
+        valueField: valueCol,
+        seriesField: seriesCol,
+      },
+    };
+
+    return spec;
+  },
+};