@blotch/dolan 22.2.2 → 22.2.3

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

@@ -0,0 +1,115 @@
+import {
+  resolveChartFocusStrategy,
+  resolveChartPointerFocus,
+  restoreChartFocusPoint,
+  sameChartPointIdentity,
+} from '@tanstack/charts/cursor/host';
+import { focusDisabled } from '@tanstack/charts/focus/disabled';
+import {
+  findNearestPoint,
+  viewportInteractionPoints,
+} from '@tanstack/charts/scene';
+import type {
+  ChartDefinition,
+  ChartFocusStrategy,
+  ChartPoint,
+  ChartScene,
+} from '@tanstack/charts/types';
+
+/**
+ * Which data points a touch lands on, and the order a screen reader steps
+ * through them.
+ *
+ * A port of TanStack's React Native focus model: it runs the definition's focus
+ * strategy (nearest point, a whole x column for `focus: 'x'`, …) over the
+ * scene's points rather than hit-testing painted shapes, which a single
+ * rasterized `<svg>` couldn't do anyway. One chart-level touch handler plus this
+ * model is also what TanStack recommends for native hosts, instead of a
+ * responder per mark.
+ */
+export type ChartFocusModel = {
+  /** The focused group for a touch at scene coordinates, or `[]`. */
+  resolve(x: number, y: number): readonly ChartPoint[];
+  /** The group that focusing `point` shows (its whole x column, say). */
+  group(point: ChartPoint): readonly ChartPoint[];
+  /** Points in reading order, for stepping with accessibility actions. */
+  readonly navigation: readonly ChartPoint[];
+  /** The same datum's point in a newer scene, or `null` if it's gone. */
+  restore(point: ChartPoint): ChartPoint | null;
+};
+
+/** TanStack's default reach for pointer focus, in scene pixels. */
+const DEFAULT_MAX_FOCUS_DISTANCE = 48;
+
+export const createChartFocusModel = (
+  scene: ChartScene<any, any, any>,
+  definition: ChartDefinition<any, any, any>,
+): ChartFocusModel => {
+  const points = viewportInteractionPoints(scene);
+  const strategy: ChartFocusStrategy<any, any, any> | undefined =
+    definition.focus === false
+      ? focusDisabled
+      : resolveChartFocusStrategy(definition.focus);
+  const spatialIndex =
+    definition.focus === false
+      ? undefined
+      : definition.spatialIndex?.(points, { scene });
+  const maxDistance = definition.maxFocusDistance ?? DEFAULT_MAX_FOCUS_DISTANCE;
+
+  return {
+    resolve(x, y) {
+      const focused = resolveChartPointerFocus(
+        scene,
+        strategy,
+        x,
+        y,
+        maxDistance,
+        points,
+      );
+      if (focused) return focused;
+      const point = spatialIndex
+        ? spatialIndex.findNearest(x, y, maxDistance)
+        : findNearestPoint(scene, x, y, maxDistance, points);
+      const visible = point ? restoreChartFocusPoint(points, point) : null;
+      return visible ? [visible] : [];
+    },
+    group(point) {
+      return strategy?.group(points, { point }) ?? [point];
+    },
+    navigation: strategy?.navigation(points) ?? readingOrder(points),
+    restore(point) {
+      return restoreChartFocusPoint(points, point);
+    },
+  };
+};
+
+/** The point `direction` steps away from `current` in navigation order. */
+export const adjacentFocusPoint = (
+  model: ChartFocusModel,
+  current: ChartPoint | null,
+  direction: -1 | 1,
+): ChartPoint | null => {
+  const { navigation } = model;
+  const index = current
+    ? navigation.findIndex((point) => sameChartPointIdentity(point, current))
+    : -1;
+  const next =
+    index < 0
+      ? direction > 0
+        ? 0
+        : navigation.length - 1
+      : Math.max(0, Math.min(navigation.length - 1, index + direction));
+  return navigation[next] ?? null;
+};
+
+/**
+ * Left to right, then top to bottom; ties keep scene order.
+ */
+const readingOrder = (points: readonly ChartPoint[]): ChartPoint[] =>
+  points
+    .map((point, index) => ({ point, index }))
+    .sort(
+      (a, b) =>
+        a.point.x - b.point.x || a.point.y - b.point.y || a.index - b.index,
+    )
+    .map(({ point }) => point);

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

@@ -0,0 +1,139 @@
+import { describe, expect, it } from 'vitest';
+import { linearAxis, minSpacing, presetAxes } from './chart-presets';
+
+/**
+ * The configured domain of an axis config's scale instance.
+ */
+const domainOf = (axis: { scale: unknown }): number[] =>
+  (axis.scale as { domain: () => number[] }).domain();
+
+describe('linearAxis', () => {
+  const base = { tickCount: 5, grid: true };
+
+  it('fits the data and rounds out to nice values', () => {
+    expect(domainOf(linearAxis({ ...base, values: [3, 47] }))).toEqual([0, 50]);
+  });
+
+  it('keeps fixed ends exact and rounds only the free one', () => {
+    expect(
+      domainOf(linearAxis({ ...base, values: [3, 47], min: 1, max: 2 })),
+    ).toEqual([1, 2]);
+    expect(domainOf(linearAxis({ ...base, values: [3, 47], min: 1 }))).toEqual([
+      1, 50,
+    ]);
+  });
+
+  it('includes extra values, such as a baseline', () => {
+    expect(
+      domainOf(linearAxis({ ...base, values: [5, 10], include: [0] })),
+    ).toEqual([0, 10]);
+  });
+
+  it('gives flat and empty data a span around the value', () => {
+    expect(domainOf(linearAxis({ ...base, values: [10, 10] }))).toEqual([
+      4, 16,
+    ]);
+    expect(domainOf(linearAxis({ ...base, values: [0] }))).toEqual([-1, 1]);
+    expect(domainOf(linearAxis({ ...base, values: [] }))).toEqual([0, 1]);
+    expect(domainOf(linearAxis({ ...base, values: [Number.NaN] }))).toEqual([
+      0, 1,
+    ]);
+  });
+
+  it('orders reversed fixed ends', () => {
+    expect(
+      domainOf(linearAxis({ ...base, values: [], min: 10, max: 0 })),
+    ).toEqual([0, 10]);
+  });
+
+  it('widens by a margin, then by padding fractions', () => {
+    expect(
+      domainOf(linearAxis({ ...base, values: [], min: 0, max: 10, margin: 1 })),
+    ).toEqual([-1, 11]);
+    // 10% each side of a 0–8 domain: the plot spans 10 units, inset 1 each side.
+    const [lo, hi] = domainOf(
+      linearAxis({ ...base, values: [], min: 0, max: 8, padding: [0.1, 0.1] }),
+    );
+    expect(lo).toBeCloseTo(-1);
+    expect(hi).toBeCloseTo(9);
+    // Padding that leaves no plot is ignored.
+    expect(
+      domainOf(
+        linearAxis({
+          ...base,
+          values: [],
+          min: 0,
+          max: 8,
+          padding: [0.6, 0.6],
+        }),
+      ),
+    ).toEqual([0, 8]);
+  });
+
+  it('configures grid, label and ticks', () => {
+    const format = (value: number) => `${value}%`;
+    const axis = linearAxis({
+      ...base,
+      values: [0, 1],
+      label: 'Share',
+      format,
+      grid: false,
+    });
+    expect(axis.grid).toBe(false);
+    expect(axis.axis).toEqual({ label: 'Share', ticks: { count: 5, format } });
+    expect(
+      (
+        linearAxis({ ...base, values: [0, 1], label: '' }).axis as {
+          label?: string;
+        }
+      ).label,
+    ).toBeUndefined();
+  });
+});
+
+describe('minSpacing', () => {
+  it('finds the smallest gap between distinct values', () => {
+    expect(minSpacing([5, 1, 3, 3, 4])).toBe(1);
+    expect(minSpacing([0, 10])).toBe(10);
+  });
+
+  it('defaults to 1 without a gap', () => {
+    expect(minSpacing([])).toBe(1);
+    expect(minSpacing([2])).toBe(1);
+    expect(minSpacing([2, 2])).toBe(1);
+  });
+});
+
+describe('presetAxes', () => {
+  it('maps the shared options onto both axes', () => {
+    const axes = presetAxes(
+      {
+        tickCount: 3,
+        showGrid: false,
+        showXGrid: true,
+        xAxisLabel: 'X',
+        yAxisLabel: 'Y',
+        padding: { left: 0.1, right: 0.1, top: 0.1, bottom: 0.1 },
+        xMin: 0,
+        xMax: 8,
+        yMin: 0,
+        yMax: 8,
+      },
+      { x: [], y: [], xMargin: 0 },
+    );
+    expect(axes.x.grid).toBe(true);
+    expect(axes.y.grid).toBe(false);
+    expect(axes.x.axis).toMatchObject({ label: 'X', ticks: { count: 3 } });
+    expect(axes.y.axis).toMatchObject({ label: 'Y' });
+    expect(domainOf(axes.x)[0]).toBeCloseTo(-1);
+    expect(domainOf(axes.y)[1]).toBeCloseTo(9);
+  });
+
+  it('defaults to five ticks, a y grid and no padding', () => {
+    const axes = presetAxes({}, { x: [0, 10], y: [0, 10], yInclude: [-5] });
+    expect(axes.x.grid).toBe(false);
+    expect(axes.y.grid).toBe(true);
+    expect(domainOf(axes.x)).toEqual([0, 10]);
+    expect(domainOf(axes.y)).toEqual([-10, 10]);
+  });
+});

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

@@ -0,0 +1,271 @@
+import { Directive, input, viewChild } from '@angular/core';
+import { scaleLinear } from '@tanstack/charts/scales/linear';
+import type {
+  ChartPoint,
+  ChartPositionScaleOptions,
+} from '@tanstack/charts/types';
+
+import { UiChart } from './chart';
+import type { ChartColorSchemeOption } from './chart-theme';
+import type { ChartZoomAxes } from './chart-zoom';
+
+/**
+ * Shared pieces of the chart presets (`<ui-line-chart>`, `<ui-bar-chart>`, …).
+ * Each preset is a thin component that turns its inputs into a TanStack
+ * definition for `<ui-chart>`; this file holds the axis handling and the inputs
+ * they all share, so every preset behaves the same way.
+ */
+
+/** A point in x/y data space, the datum the line, area and scatter presets plot. */
+export type XYDatum = {
+  readonly x: number;
+  readonly y: number;
+};
+
+/**
+ * Inner inset per side, as a **fraction** (`0`–`1`) of the plot's width or
+ * height, so the first and last marks don't sit on the frame. Fractions keep
+ * the inset proportional as the chart resizes. Omitted sides default to `0`.
+ */
+export type ChartPadding = {
+  readonly top?: number;
+  readonly right?: number;
+  readonly bottom?: number;
+  readonly left?: number;
+};
+
+/** The axis, grid and tooltip options every cartesian preset takes. */
+export type CartesianPresetOptions = {
+  readonly tickCount?: number;
+  readonly showGrid?: boolean;
+  readonly showXGrid?: boolean;
+  readonly xAxisLabel?: string;
+  readonly yAxisLabel?: string;
+  readonly padding?: ChartPadding;
+  readonly xMin?: number;
+  readonly xMax?: number;
+  readonly yMin?: number;
+  readonly yMax?: number;
+  readonly xTickFormat?: (value: number) => string;
+  readonly yTickFormat?: (value: number) => string;
+  /** `false` turns the tooltip off. */
+  readonly tooltip?: boolean;
+};
+
+/**
+ * The x and y axes for a preset's data, from the shared options: `x` and `y`
+ * are the values each axis fits, `xMargin` widens x by data units (half a bar),
+ * `yInclude` keeps values like a baseline in view.
+ */
+export const presetAxes = (
+  options: CartesianPresetOptions,
+  data: {
+    readonly x: readonly number[];
+    readonly y: readonly number[];
+    readonly xMargin?: number;
+    readonly yInclude?: readonly number[];
+  },
+) => {
+  const { tickCount = 5, padding = {} } = options;
+  return {
+    x: linearAxis({
+      values: data.x,
+      min: options.xMin,
+      max: options.xMax,
+      margin: data.xMargin,
+      tickCount,
+      padding: [padding.left ?? 0, padding.right ?? 0],
+      format: options.xTickFormat,
+      label: options.xAxisLabel,
+      grid: options.showXGrid ?? false,
+    }),
+    y: linearAxis({
+      values: data.y,
+      include: data.yInclude,
+      min: options.yMin,
+      max: options.yMax,
+      tickCount,
+      padding: [padding.bottom ?? 0, padding.top ?? 0],
+      format: options.yTickFormat,
+      label: options.yAxisLabel,
+      grid: options.showGrid ?? true,
+    }),
+  };
+};
+
+export type LinearAxisOptions = {
+  /** Data values on this axis, to fit the domain to. */
+  readonly values: readonly number[];
+  /** Fixed ends; a missing end fits the data. */
+  readonly min?: number;
+  readonly max?: number;
+  /** Values that must stay in view, such as an area's baseline. */
+  readonly include?: readonly number[];
+  readonly tickCount: number;
+  /** Inset at the low and high end, as fractions of the plot (see {@link ChartPadding}). */
+  readonly padding?: readonly [number, number];
+  /** Extra data units added beyond each end, e.g. half a bar so the edge bars fit. */
+  readonly margin?: number;
+  readonly format?: (value: number) => string;
+  readonly label?: string;
+  readonly grid: boolean;
+};
+
+/**
+ * A linear axis config: the domain fits the data (and `include`), is rounded
+ * out to nice tick values unless both ends are fixed, then widened by `margin`
+ * and `padding`. Flat or empty data gets a span around the value so the marks
+ * sit mid-plot instead of collapsing onto one edge.
+ *
+ * The domain is computed here, not left to TanStack's inference, because
+ * padding has to apply after rounding, and a zoomable axis needs a configured
+ * scale to carry its viewport.
+ */
+export const linearAxis = (
+  options: LinearAxisOptions,
+): ChartPositionScaleOptions<number> => {
+  const values = [...options.values, ...(options.include ?? [])].filter(
+    Number.isFinite,
+  );
+  let lo = options.min ?? (values.length ? Math.min(...values) : 0);
+  let hi = options.max ?? (values.length ? Math.max(...values) : 1);
+  if (lo === hi) {
+    const pad = lo === 0 ? 1 : Math.abs(lo) * 0.5;
+    lo -= pad;
+    hi += pad;
+  }
+  if (lo > hi) [lo, hi] = [hi, lo];
+  if (options.min === undefined || options.max === undefined) {
+    const nice = scaleLinear()
+      .domain([lo, hi])
+      .nice(options.tickCount)
+      .domain();
+    lo = options.min ?? nice[0];
+    hi = options.max ?? nice[1];
+  }
+  const margin = options.margin ?? 0;
+  lo -= margin;
+  hi += margin;
+  const [padLo, padHi] = options.padding ?? [0, 0];
+  const keep = 1 - padLo - padHi;
+  if ((padLo || padHi) && keep > 0) {
+    const span = (hi - lo) / keep;
+    lo -= padLo * span;
+    hi = lo + span;
+  }
+  return {
+    scale: scaleLinear().domain([lo, hi]),
+    grid: options.grid,
+    axis: {
+      label: options.label || undefined,
+      ticks: { count: options.tickCount, format: options.format },
+    },
+  };
+};
+
+/** Smallest gap between neighboring values, `1` for fewer than two. */
+export const minSpacing = (values: readonly number[]): number => {
+  const sorted = [...new Set(values)].sort((a, b) => a - b);
+  let spacing = Infinity;
+  for (let i = 1; i < sorted.length; i++) {
+    spacing = Math.min(spacing, sorted[i]! - sorted[i - 1]!);
+  }
+  return Number.isFinite(spacing) && spacing > 0 ? spacing : 1;
+};
+
+/**
+ * The inputs and zoom API every cartesian preset shares. A preset extends this
+ * and adds its own data and mark inputs, and renders `<ui-chart #chart>`
+ * with the shared bindings.
+ */
+@Directive()
+export abstract class UiCartesianPreset<TDatum> {
+  /** Fixed width in px. Omit to fill the container. */
+  readonly width = input<number>();
+  readonly height = input(200);
+  /** Target number of ticks per axis; the axis picks nice values near it. */
+  readonly tickCount = input(5);
+  /** Horizontal gridlines at the y ticks. */
+  readonly showGrid = input(true);
+  /** Vertical gridlines at the x ticks. */
+  readonly showXGrid = input(false);
+  readonly xAxisLabel = input('');
+  readonly yAxisLabel = input('');
+  readonly padding = input<ChartPadding>({});
+  readonly xMin = input<number>();
+  readonly xMax = input<number>();
+  readonly yMin = input<number>();
+  readonly yMax = input<number>();
+  readonly xTickFormat = input<(value: number) => string>();
+  readonly yTickFormat = input<(value: number) => string>();
+  /** Shows a tooltip for the touched point; a tap pins it. */
+  readonly tooltip = input(true);
+  /** What a screen reader announces for the chart. */
+  readonly label = input('Chart');
+  /** Light, dark or `'system'` colors; the chart theme's setting when unset. */
+  readonly colorScheme = input<Exclude<ChartColorSchemeOption, Function>>();
+  readonly zoomable = input(false);
+  readonly zoomAxes = input<ChartZoomAxes>('xy');
+  readonly showZoomControls = input(true);
+  readonly minZoom = input(1);
+  readonly maxZoom = input(8);
+  readonly zoomStep = input(1.4);
+  readonly userClass = input<string>('', { alias: 'class' });
+
+  protected readonly chart = viewChild.required(UiChart);
+
+  /**
+   * The shared inputs, as the options every preset's definition takes.
+   */
+  protected commonOptions(): CartesianPresetOptions {
+    return {
+      tickCount: this.tickCount(),
+      showGrid: this.showGrid(),
+      showXGrid: this.showXGrid(),
+      xAxisLabel: this.xAxisLabel(),
+      yAxisLabel: this.yAxisLabel(),
+      padding: this.padding(),
+      xMin: this.xMin(),
+      xMax: this.xMax(),
+      yMin: this.yMin(),
+      yMax: this.yMax(),
+      xTickFormat: this.xTickFormat(),
+      yTickFormat: this.yTickFormat(),
+      tooltip: this.tooltip(),
+    };
+  }
+
+  /**
+   * The tapped datum, unwrapped from TanStack's point.
+   */
+  protected datumOf(point: ChartPoint | null): TDatum | null {
+    return point ? (point.datum as TDatum) : null;
+  }
+
+  zoomIn(): void {
+    this.chart().zoomIn();
+  }
+
+  zoomOut(): void {
+    this.chart().zoomOut();
+  }
+
+  resetZoom(): void {
+    this.chart().resetZoom();
+  }
+}
+
+/** The `<ui-chart>` bindings a preset passes straight through. */
+export const PRESET_CHART_BINDINGS = `
+  [width]="width()"
+  [height]="height()"
+  [label]="label()"
+  [colorScheme]="colorScheme()"
+  [class]="userClass()"
+  [zoomable]="zoomable()"
+  [zoomAxes]="zoomAxes()"
+  [showZoomControls]="showZoomControls()"
+  [minZoom]="minZoom()"
+  [maxZoom]="maxZoom()"
+  [zoomStep]="zoomStep()"
+`;