@blotch/dolan 22.2.2 → 22.2.4

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

@@ -0,0 +1,335 @@
+import {
+  Component,
+  Injector,
+  type Type,
+  computed,
+  input,
+  output,
+  signal,
+  viewChild,
+} from '@angular/core';
+import {
+  fireEvent,
+  render,
+  waitForUpdate,
+} from '@blotch/angular-lynx-testing-library';
+import { defineChart, dot } from '@tanstack/charts/universal';
+import { describe, expect, it } from 'vitest';
+import { UiChart, tooltip } from './chart';
+import {
+  type CartesianPresetOptions,
+  PRESET_CHART_BINDINGS,
+  UiCartesianPreset,
+  type XYDatum,
+  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]);
+  });
+});
+
+/**
+ * The smallest preset: a dot per datum on the shared axes, built the way the
+ * library's presets (`<ui-line-chart>`, …) build theirs.
+ */
+@Component({
+  selector: 'test-dot-chart',
+  imports: [UiChart],
+  template: `
+    <ui-chart
+      #chart
+      [definition]="definition()"
+      ${PRESET_CHART_BINDINGS}
+      (pointSelect)="pointTap.emit(datumOf($event))"
+    />
+  `,
+})
+class DotChart extends UiCartesianPreset<XYDatum> {
+  readonly data = input.required<readonly XYDatum[]>();
+  /** The tapped datum, or `null` for a tap on empty space. */
+  readonly pointTap = output<XYDatum | null>();
+
+  protected readonly definition = computed(() => {
+    const options = this.commonOptions();
+    const data = this.data();
+    return defineChart({
+      marks: [dot(data, { x: 'x', y: 'y' })],
+      scales: presetAxes(options, {
+        x: data.map((d) => d.x),
+        y: data.map((d) => d.y),
+      }),
+      tooltip: options.tooltip === false ? false : tooltip,
+    });
+  });
+}
+
+@Component({
+  imports: [DotChart],
+  template: `
+    <test-dot-chart
+      [data]="data"
+      [width]="300"
+      [height]="160"
+      label="Sales"
+      class="mt-2"
+      [xAxisLabel]="xAxisLabel()"
+      yAxisLabel="Units"
+      [zoomable]="true"
+      zoomAxes="x"
+      (pointTap)="tapped.push($event)"
+    />
+  `,
+})
+class PresetHost {
+  readonly data: readonly XYDatum[] = [
+    { x: 0, y: 100 },
+    { x: 5, y: 300 },
+    { x: 10, y: 500 },
+  ];
+  readonly xAxisLabel = signal('Day');
+  /** Every `pointTap`, in order. */
+  readonly tapped: (XYDatum | null)[] = [];
+  readonly preset = viewChild.required(DotChart);
+}
+
+/**
+ * The chart's own view, which takes every touch.
+ */
+const chartRoot = (container: Element) =>
+  container.querySelector('[accessibility-label]')!;
+
+/**
+ * Where the chart drew each dot, read from its marks layer.
+ */
+const dotsDrawn = (container: Element) =>
+  [
+    ...container
+      .querySelectorAll('svg')[1]!
+      .getAttribute('content')!
+      .matchAll(/<circle cx="([\d.-]+)" cy="([\d.-]+)"/g),
+  ].map(([, x, y]) => ({ x: Number(x), y: Number(y) }));
+
+/**
+ * Touches a spot and lifts the finger right there: a tap.
+ */
+const tap = async (root: Element, at: { x: number; y: number }) => {
+  fireEvent.touchstart(root, { touches: [at] });
+  fireEvent.touchend(root, { touches: [at] });
+  await waitForUpdate();
+};
+
+describe('UiCartesianPreset', () => {
+  it('starts every preset from the same defaults', () => {
+    // Angular builds a preset through the base's factory, with the preset's
+    // own type, so no preset runs that factory's default: build the base alone.
+    const base = Injector.create({
+      providers: [
+        {
+          provide: UiCartesianPreset,
+          useClass: UiCartesianPreset as unknown as Type<
+            UiCartesianPreset<XYDatum>
+          >,
+        },
+      ],
+    }).get(UiCartesianPreset);
+    const options = (
+      base as unknown as { commonOptions(): CartesianPresetOptions }
+    ).commonOptions();
+    expect(options).toEqual({
+      tickCount: 5,
+      showGrid: true,
+      showXGrid: false,
+      xAxisLabel: '',
+      yAxisLabel: '',
+      padding: {},
+      xMin: undefined,
+      xMax: undefined,
+      yMin: undefined,
+      yMax: undefined,
+      xTickFormat: undefined,
+      yTickFormat: undefined,
+      tooltip: true,
+    });
+    expect(base.height()).toBe(200);
+    expect(base.label()).toBe('Chart');
+    expect(base.zoomable()).toBe(false);
+    expect(base.zoomAxes()).toBe('xy');
+  });
+
+  it('passes the shared inputs through to its chart', async () => {
+    const { container, componentRef, getByText } = await render(PresetHost);
+    const root = chartRoot(container);
+    expect(root.getAttribute('accessibility-label')).toBe('Sales');
+    expect(root.getAttribute('class')).toContain('mt-2');
+    expect(root.getAttribute('style')).toContain('height: 160px');
+    expect(getByText('Units')).toBeTruthy();
+    expect(getByText('Day')).toBeTruthy();
+
+    (componentRef.instance as PresetHost).xAxisLabel.set('Week');
+    await waitForUpdate();
+    expect(getByText('Week')).toBeTruthy();
+  });
+
+  it('hands a tap over as the datum, or null off the points', async () => {
+    const { container, componentRef } = await render(PresetHost);
+    const host = componentRef.instance as PresetHost;
+    const root = chartRoot(container);
+    const middle = dotsDrawn(container)[1]!;
+    await tap(root, { x: middle.x + 1, y: middle.y + 1 });
+    await tap(root, { x: -100, y: -100 });
+    expect(host.tapped).toEqual([host.data[1], null]);
+  });
+
+  it('zooms its chart in and out, and resets it', async () => {
+    const { componentRef, queryByText } = await render(PresetHost);
+    const preset = (componentRef.instance as PresetHost).preset();
+    // The x axis spans 0–10; zoomed in around the middle, its last tick goes.
+    expect(queryByText('10')).not.toBeNull();
+    preset.zoomIn();
+    await waitForUpdate();
+    expect(queryByText('10')).toBeNull();
+    preset.zoomOut();
+    await waitForUpdate();
+    expect(queryByText('10')).not.toBeNull();
+
+    preset.zoomIn();
+    preset.resetZoom();
+    await waitForUpdate();
+    expect(queryByText('10')).not.toBeNull();
+  });
+});

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

@@ -0,0 +1,278 @@
+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;
+};
+
+/**
+ * `UiChart`, for `viewChild()`. A call rather than the class itself: for a
+ * class, Angular's test build keeps an arrow function that nothing calls,
+ * which an app's coverage report would show as uncovered.
+ */
+const chartType = () => UiChart;
+
+/**
+ * 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(chartType());
+
+  /**
+   * 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()"
+`;