@blotch/dolan 22.2.2 → 22.2.3

package/dist/ui/components/chart/chart-theme.ts

@@ -0,0 +1,198 @@
+import { InjectionToken, type Provider } from '@angular/core';
+import type { ChartTheme } from '@tanstack/charts/types';
+
+/**
+ * Theme for `<ui-chart>`.
+ *
+ * ## Why colors live in TypeScript as well as CSS
+ * A chart's marks are drawn by Lynx's native `<svg>` element, which parses an
+ * SVG string by itself: it never sees the page's CSS, so `var(--primary)` means
+ * nothing to it, and Lynx has no computed-style API to read the variable's value
+ * from JS. So the scene keeps CSS-shaped paints (`var(--primary)`, the palette's
+ * `var(--chart-1)`), and the chart swaps each for the value in the active color
+ * table below just before it writes the SVG.
+ *
+ * The tables mirror `default.css` and `dark.css` (a test in the theme folder
+ * keeps them in step). If you change a color there, change it here too, or pass
+ * your own with {@link provideChartTheme}. Axis labels are native `<text>`, so
+ * they read the CSS variables directly and always match the page.
+ */
+
+/** Theme token name (without `--`) to a complete CSS color. */
+export type ChartColorTokens = Readonly<Record<string, string>>;
+
+export type ChartColorScheme = 'light' | 'dark';
+
+/**
+ * Which colors a chart draws with: a fixed scheme, `'system'` to follow the
+ * device appearance (`LynxTheme`), or a function reading the app's own theme
+ * state.
+ *
+ * It has to match how the app switches its CSS theme, because axis labels use
+ * the CSS variables while the marks use the tables below. The ui theme's dark
+ * mode is opt-in (the app toggles the `.dark` class), so the default is
+ * `'light'`: a chart in an app without dark mode stays readable when the
+ * device is dark. An app that toggles `.dark` from `LynxTheme` (see the dark
+ * mode guide) uses `'system'`.
+ */
+export type ChartColorSchemeOption =
+  | ChartColorScheme
+  | 'system'
+  | (() => ChartColorScheme);
+
+export type UiChartTheme = {
+  /** Token values for light mode; mirrors `default.css`. */
+  readonly light: ChartColorTokens;
+  /** Token values for dark mode; mirrors `dark.css`. */
+  readonly dark: ChartColorTokens;
+  /** See {@link ChartColorSchemeOption}; `'light'` when unset. */
+  readonly colorScheme?: ChartColorSchemeOption;
+  /**
+   * The theme TanStack Charts builds scenes with. Its paints should be
+   * `var(--token)` strings, so one scene serves both color schemes.
+   */
+  readonly chart: Partial<ChartTheme>;
+};
+
+export const CHART_LIGHT_COLORS: ChartColorTokens = {
+  background: 'rgba(255, 255, 255, 1)',
+  foreground: 'rgba(9, 9, 11, 1)',
+  card: 'rgba(255, 255, 255, 1)',
+  'card-foreground': 'rgba(9, 9, 11, 1)',
+  primary: 'rgba(24, 24, 27, 1)',
+  'primary-foreground': 'rgba(250, 250, 250, 1)',
+  secondary: 'rgba(244, 244, 245, 1)',
+  'secondary-foreground': 'rgba(24, 24, 27, 1)',
+  muted: 'rgba(244, 244, 245, 1)',
+  'muted-foreground': 'rgba(113, 113, 122, 1)',
+  accent: 'rgba(244, 244, 245, 1)',
+  'accent-foreground': 'rgba(24, 24, 27, 1)',
+  destructive: 'rgba(239, 68, 68, 1)',
+  'destructive-foreground': 'rgba(250, 250, 250, 1)',
+  'destructive-subtle': 'rgba(239, 68, 68, 0.1)',
+  border: 'rgba(228, 228, 231, 1)',
+  input: 'rgba(228, 228, 231, 1)',
+  ring: 'rgba(24, 24, 27, 1)',
+  'ring-subtle': 'rgba(24, 24, 27, 0.4)',
+  'chart-1': 'rgba(231, 110, 80, 1)',
+  'chart-2': 'rgba(42, 157, 144, 1)',
+  'chart-3': 'rgba(39, 71, 84, 1)',
+  'chart-4': 'rgba(232, 196, 104, 1)',
+  'chart-5': 'rgba(244, 164, 98, 1)',
+};
+
+export const CHART_DARK_COLORS: ChartColorTokens = {
+  background: 'rgba(9, 9, 11, 1)',
+  foreground: 'rgba(250, 250, 250, 1)',
+  card: 'rgba(9, 9, 11, 1)',
+  'card-foreground': 'rgba(250, 250, 250, 1)',
+  primary: 'rgba(250, 250, 250, 1)',
+  'primary-foreground': 'rgba(24, 24, 27, 1)',
+  secondary: 'rgba(39, 39, 42, 1)',
+  'secondary-foreground': 'rgba(250, 250, 250, 1)',
+  muted: 'rgba(39, 39, 42, 1)',
+  'muted-foreground': 'rgba(161, 161, 170, 1)',
+  accent: 'rgba(39, 39, 42, 1)',
+  'accent-foreground': 'rgba(250, 250, 250, 1)',
+  destructive: 'rgba(127, 29, 29, 1)',
+  'destructive-foreground': 'rgba(250, 250, 250, 1)',
+  'destructive-subtle': 'rgba(127, 29, 29, 0.1)',
+  border: 'rgba(39, 39, 42, 1)',
+  input: 'rgba(39, 39, 42, 1)',
+  ring: 'rgba(212, 212, 216, 1)',
+  'ring-subtle': 'rgba(212, 212, 216, 0.4)',
+  'chart-1': 'rgba(38, 98, 217, 1)',
+  'chart-2': 'rgba(46, 184, 138, 1)',
+  'chart-3': 'rgba(232, 140, 48, 1)',
+  'chart-4': 'rgba(175, 87, 219, 1)',
+  'chart-5': 'rgba(226, 54, 112, 1)',
+};
+
+/**
+ * TanStack's own defaults paint everything `currentColor` at reduced opacity
+ * (grid lines at 0.11, tick labels at 0.72), which reads well on any background.
+ * The same roles map onto theme tokens: text and grid follow the foreground,
+ * secondary text the muted foreground, and series cycle through `--chart-*`.
+ */
+export const DEFAULT_CHART_THEME: Partial<ChartTheme> = {
+  foreground: 'var(--foreground)',
+  muted: 'var(--muted-foreground)',
+  grid: 'var(--foreground)',
+  background: 'transparent',
+  palette: [
+    'var(--chart-1)',
+    'var(--chart-2)',
+    'var(--chart-3)',
+    'var(--chart-4)',
+    'var(--chart-5)',
+  ],
+};
+
+export const UI_CHART_THEME = new InjectionToken<UiChartTheme>(
+  'UI_CHART_THEME',
+  {
+    providedIn: 'root',
+    factory: () => ({
+      light: CHART_LIGHT_COLORS,
+      dark: CHART_DARK_COLORS,
+      chart: DEFAULT_CHART_THEME,
+    }),
+  },
+);
+
+/**
+ * Overrides chart colors, merged over the defaults: pass only the tokens you
+ * changed in your theme CSS, or a different TanStack theme (e.g. a palette).
+ *
+ * ```ts
+ * providers: [provideChartTheme({ light: { 'chart-1': 'rgba(37, 99, 235, 1)' } })]
+ * // An app that switches .dark with the device appearance:
+ * providers: [provideChartTheme({ colorScheme: 'system' })]
+ * ```
+ */
+export const provideChartTheme = (theme: {
+  light?: ChartColorTokens;
+  dark?: ChartColorTokens;
+  chart?: Partial<ChartTheme>;
+  colorScheme?: ChartColorSchemeOption;
+}): Provider => ({
+  provide: UI_CHART_THEME,
+  useValue: {
+    light: { ...CHART_LIGHT_COLORS, ...theme.light },
+    dark: { ...CHART_DARK_COLORS, ...theme.dark },
+    chart: { ...DEFAULT_CHART_THEME, ...theme.chart },
+    colorScheme: theme.colorScheme,
+  } satisfies UiChartTheme,
+});
+
+/**
+ * Turns a CSS-shaped paint into a concrete color an SVG parser can draw:
+ * `var(--token)` (with or without a fallback) becomes the token's value,
+ * `currentColor` the foreground. Anything else (`#2563eb`, `rgba(…)`, a
+ * gradient's `url(#id)`) is already concrete and passes through.
+ */
+export const resolveChartPaint = (
+  paint: string,
+  colors: ChartColorTokens,
+): string => {
+  const value = paint.trim();
+  if (value === 'currentColor' || value === 'CanvasText') {
+    return colors['foreground'] ?? value;
+  }
+  if (value === 'Canvas') return colors['background'] ?? value;
+  if (!value.startsWith('var(') || !value.endsWith(')')) return value;
+
+  const inner = value.slice(4, -1);
+  // A custom property name can't contain a comma or parenthesis, so the first
+  // comma always separates the name from the fallback.
+  const comma = inner.indexOf(',');
+  const name = (comma < 0 ? inner : inner.slice(0, comma)).trim();
+  const token = colors[name.replace(/^--/, '')];
+  if (token !== undefined) return token;
+  // An unknown token falls back the way CSS does: to the var()'s fallback when
+  // it has one (TanStack's own palette is `var(--ts-chart-1, #2563eb)`), and
+  // otherwise to the foreground so the mark stays visible.
+  return comma < 0
+    ? (colors['foreground'] ?? value)
+    : resolveChartPaint(inner.slice(comma + 1), colors);
+};

package/dist/ui/components/chart/chart-zoom.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, it } from 'vitest';
+import type { ResolvedScale } from '@tanstack/charts/types';
+import {
+  axisContentWindow,
+  axisVisibleWindow,
+  clampWindow,
+  isFullWindow,
+  panWindow,
+  toViewportDomain,
+  withViewport,
+  zoomWindow,
+} from './chart-zoom';
+
+const scale = (
+  domain: readonly unknown[],
+  extra: Partial<ResolvedScale> = {},
+): ResolvedScale =>
+  ({
+    id: 'x',
+    type: 'linear',
+    domain,
+    map: () => 0,
+    ticks: [],
+    bandwidth: 0,
+    ...extra,
+  }) as ResolvedScale;
+
+describe('window math', () => {
+  it('clamps a window inside the base, keeping its span', () => {
+    expect(clampWindow([0, 10], [8, 12])).toEqual([6, 10]);
+    expect(clampWindow([0, 10], [-3, 1])).toEqual([0, 4]);
+    expect(clampWindow([0, 10], [-5, 20])).toEqual([0, 10]);
+  });
+
+  it('pans by a data delta, stopping at the edges', () => {
+    expect(panWindow([0, 10], [2, 4], 3)).toEqual([5, 7]);
+    expect(panWindow([0, 10], [2, 4], 100)).toEqual([8, 10]);
+  });
+
+  it('zooms around a focal value within the zoom limits', () => {
+    expect(zoomWindow([0, 10], [0, 10], 2, 5, 8)).toEqual([2.5, 7.5]);
+    // Never past maxZoom…
+    expect(zoomWindow([0, 10], [4, 6], 100, 5, 4)).toEqual([3.75, 6.25]);
+    // …nor out past the whole base.
+    expect(zoomWindow([0, 10], [4, 6], 0.01, 5, 8)).toEqual([0, 10]);
+    // A zero factor counts as 1, and zero limits mean the base span.
+    expect(zoomWindow([0, 10], [0, 10], 0, 5, 0, 0)).toEqual([0, 10]);
+    // A zero-width window zooms about its middle.
+    expect(zoomWindow([0, 10], [5, 5], 1, 5, 8)).toEqual([4.375, 5.625]);
+  });
+
+  it('knows a window covering the base is at rest', () => {
+    expect(isFullWindow([0, 10], [0, 10])).toBe(true);
+    expect(isFullWindow([0, 10], [0, 9])).toBe(false);
+    expect(isFullWindow([3, 3], [3, 3])).toBe(true);
+  });
+});
+
+describe('axis windows', () => {
+  it('reads a continuous axis as numbers, ordered', () => {
+    expect(axisContentWindow(scale([0, 10]))).toEqual([0, 10]);
+    expect(axisContentWindow(scale([10, 0]))).toEqual([0, 10]);
+    expect(axisContentWindow(scale([new Date(1), new Date(5)]))).toEqual([
+      1, 5,
+    ]);
+  });
+
+  it("prefers a viewport's complete content domain", () => {
+    expect(
+      axisContentWindow(
+        scale([2, 4], {
+          viewport: {
+            contentDomain: [0, 10],
+            domain: [2, 4],
+            translate: 0,
+            map: () => 0,
+          },
+        }),
+      ),
+    ).toEqual([0, 10]);
+  });
+
+  it("rejects axes that can't zoom", () => {
+    expect(axisContentWindow(undefined)).toBeNull();
+    expect(axisContentWindow(scale(['a', 'b'], { bandwidth: 20 }))).toBeNull();
+    expect(axisContentWindow(scale([1, 2, 3]))).toBeNull();
+    expect(axisContentWindow(scale([1, 1]))).toBeNull();
+    expect(axisContentWindow(scale(['a', 'b']))).toBeNull();
+    expect(axisContentWindow(scale([0, Number.NaN]))).toBeNull();
+  });
+
+  it('reads the visible window from the viewport, else the whole axis', () => {
+    const viewport = (domain: readonly unknown[]) =>
+      scale([0, 10], {
+        viewport: {
+          contentDomain: [0, 10],
+          domain: domain as never,
+          translate: 0,
+          map: () => 0,
+        },
+      });
+    expect(axisVisibleWindow(viewport([6, 2]))).toEqual([2, 6]);
+    expect(axisVisibleWindow(viewport(['a', 'b']))).toEqual([0, 10]);
+    expect(axisVisibleWindow(scale([0, 10]))).toEqual([0, 10]);
+    expect(axisVisibleWindow(undefined)).toBeNull();
+  });
+
+  it("converts a window to the axis's value type", () => {
+    expect(toViewportDomain([1, 2], scale([0, 10]))).toEqual([1, 2]);
+    expect(
+      toViewportDomain([1, 2], scale([new Date(0), new Date(10)])),
+    ).toEqual([new Date(1), new Date(2)]);
+  });
+});
+
+describe('withViewport', () => {
+  const definition = {
+    marks: [],
+    scales: { x: { scale: 'x-scale' }, y: { scale: 'y-scale' } },
+  } as never;
+
+  it('returns the definition untouched without a window', () => {
+    expect(withViewport(definition, {})).toBe(definition);
+  });
+
+  it('sets the viewport on the windowed, configured axes', () => {
+    const result = withViewport(definition, { x: [1, 2] }) as {
+      scales: Record<string, unknown>;
+    };
+    expect(result.scales['x']).toEqual({
+      scale: 'x-scale',
+      viewport: { domain: [1, 2] },
+    });
+    expect(result.scales['y']).toEqual({ scale: 'y-scale' });
+  });
+
+  it('skips axes the definition leaves to inference', () => {
+    const partial = { marks: [], scales: { y: { scale: 'y' } } } as never;
+    expect(withViewport(partial, { x: [1, 2] })).toEqual(partial);
+    const none = { marks: [] } as never;
+    expect(withViewport(none, { x: [1, 2] })).toBe(none);
+  });
+
+  it("applies the viewport to a responsive definition's spec", () => {
+    const responsive = {
+      chart: () => ({ marks: [], scales: { x: { scale: 's' } } }),
+      tooltip: false,
+    } as never;
+    const result = withViewport(responsive, { x: [3, 4] }) as {
+      chart: (context: unknown) => { scales: Record<string, unknown> };
+      tooltip: boolean;
+    };
+    expect(result.tooltip).toBe(false);
+    expect(result.chart({}).scales['x']).toEqual({
+      scale: 's',
+      viewport: { domain: [3, 4] },
+    });
+  });
+});

package/dist/ui/components/chart/chart-zoom.ts

@@ -0,0 +1,162 @@
+import type { ChartDefinition, ResolvedScale } from '@tanstack/charts/types';
+
+/**
+ * Pan and zoom for `<ui-chart>`, as a visible window over each continuous
+ * axis. TanStack Charts already has the concept: a scale's `viewport.domain` is
+ * "a semantic window over the scale's complete domain", which it maps into the
+ * plot and clips to. So zooming never touches the data or the marks; the chart
+ * only rewrites that one option and re-renders. Windows are plain numbers; a
+ * time axis converts to and from epoch milliseconds at the edges.
+ */
+
+/** An inclusive `[low, high]` window in data units. */
+export type ChartWindow = readonly [number, number];
+
+export type ChartZoomAxes = 'x' | 'y' | 'xy';
+
+/** A viewport domain as TanStack takes it: numbers, or `Date`s on a time axis. */
+export type ChartViewportDomain =
+  | readonly [number, number]
+  | readonly [Date, Date];
+
+/** The visible window per axis; a missing axis is fully zoomed out. */
+export type ChartViewport = {
+  readonly x?: ChartViewportDomain;
+  readonly y?: ChartViewportDomain;
+};
+
+const clampValue = (value: number, lo: number, hi: number): number =>
+  Math.min(hi, Math.max(lo, value));
+
+/**
+ * Keeps `window` inside `base`: never wider than it, never past either edge.
+ * Span is preserved where possible (the window slides rather than resizes), so
+ * panning into an edge stops instead of secretly zooming.
+ */
+export const clampWindow = (
+  base: ChartWindow,
+  window: ChartWindow,
+): ChartWindow => {
+  const span = Math.min(window[1] - window[0], base[1] - base[0]);
+  const lo = clampValue(window[0], base[0], base[1] - span);
+  return [lo, lo + span];
+};
+
+/** Slides `current` by `delta` data units, stopping at the edges of `base`. */
+export const panWindow = (
+  base: ChartWindow,
+  current: ChartWindow,
+  delta: number,
+): ChartWindow => clampWindow(base, [current[0] + delta, current[1] + delta]);
+
+/**
+ * Zooms `current` by `factor` (>1 in, <1 out) around the data value `focal`,
+ * which keeps its place on screen. The span stays within
+ * `[baseSpan / maxZoom, baseSpan / minZoom]`.
+ */
+export const zoomWindow = (
+  base: ChartWindow,
+  current: ChartWindow,
+  factor: number,
+  focal: number,
+  maxZoom: number,
+  minZoom = 1,
+): ChartWindow => {
+  const baseSpan = base[1] - base[0];
+  const span = current[1] - current[0];
+  const minSpan = maxZoom > 0 ? baseSpan / maxZoom : baseSpan;
+  const maxSpan = minZoom > 0 ? baseSpan / minZoom : baseSpan;
+  const nextSpan = clampValue(span / (factor || 1), minSpan, maxSpan);
+  const fraction = span === 0 ? 0.5 : (focal - current[0]) / span;
+  const lo = focal - fraction * nextSpan;
+  return clampWindow(base, [lo, lo + nextSpan]);
+};
+
+/** Whether `window` covers (practically) all of `base`, i.e. is at rest. */
+export const isFullWindow = (
+  base: ChartWindow,
+  window: ChartWindow,
+): boolean => {
+  const baseSpan = base[1] - base[0];
+  return baseSpan === 0 || window[1] - window[0] >= baseSpan * (1 - 1e-6);
+};
+
+/**
+ * The complete domain of a rendered continuous axis, as numbers, or `null` for
+ * an axis that can't zoom: a band/point scale, a missing scale, or a degenerate
+ * domain. With a viewport applied, the scene still reports the full domain as
+ * `viewport.contentDomain`.
+ */
+export const axisContentWindow = (
+  scale: ResolvedScale | undefined,
+): ChartWindow | null => {
+  if (!scale || scale.bandwidth > 0) return null;
+  const domain = scale.viewport?.contentDomain ?? scale.domain;
+  if (domain.length !== 2) return null;
+  const lo = toNumber(domain[0]);
+  const hi = toNumber(domain[1]);
+  if (lo === null || hi === null || lo === hi) return null;
+  return lo < hi ? [lo, hi] : [hi, lo];
+};
+
+/** The window currently shown on a zoomable axis: its viewport, else all of it. */
+export const axisVisibleWindow = (
+  scale: ResolvedScale | undefined,
+): ChartWindow | null => {
+  const content = axisContentWindow(scale);
+  const viewport = scale?.viewport?.domain;
+  if (!content || !viewport) return content;
+  const lo = toNumber(viewport[0]);
+  const hi = toNumber(viewport[1]);
+  return lo === null || hi === null
+    ? content
+    : [Math.min(lo, hi), Math.max(lo, hi)];
+};
+
+/**
+ * `window` in the axis's own value type: `Date`s for a time scale, so the
+ * viewport compares like with like against its domain.
+ */
+export const toViewportDomain = (
+  window: ChartWindow,
+  scale: ResolvedScale,
+): ChartViewportDomain =>
+  scale.domain[0] instanceof Date
+    ? [new Date(window[0]), new Date(window[1])]
+    : [window[0], window[1]];
+
+const toNumber = (value: unknown): number | null => {
+  const number = value instanceof Date ? value.getTime() : value;
+  return typeof number === 'number' && Number.isFinite(number) ? number : null;
+};
+
+/**
+ * `definition` with each windowed axis's `viewport` set. Only axes the
+ * definition configures (`scales.x` / `scales.y`) can carry a viewport, which
+ * every zoomable preset does. A responsive definition (`chart: (size) => …`)
+ * gets the viewport applied to the spec its builder returns.
+ */
+export const withViewport = <
+  TDefinition extends ChartDefinition<any, any, any>,
+>(
+  definition: TDefinition,
+  viewport: ChartViewport,
+): TDefinition => {
+  if (!viewport.x && !viewport.y) return definition;
+  if ('chart' in definition && typeof definition.chart === 'function') {
+    const build = definition.chart as (context: unknown) => TDefinition;
+    return {
+      ...definition,
+      chart: (context: unknown) => withViewport(build(context), viewport),
+    };
+  }
+  const scales = (definition as { scales?: Record<string, object> }).scales;
+  if (!scales) return definition;
+  const next: Record<string, object> = { ...scales };
+  for (const axis of ['x', 'y'] as const) {
+    const domain = viewport[axis];
+    const options = scales[axis];
+    if (domain && options) next[axis] = { ...options, viewport: { domain } };
+  }
+  return { ...definition, scales: next };
+};