@blotch/dolan 22.2.2 → 22.2.4

package/dist/ui/components/radio-group/radio-group.ts

@@ -70,36 +70,36 @@ export class UiRadioGroupItem {
   readonly itemValue = input.required<string>({ alias: 'value' });
   readonly userClass = input<string>('', { alias: 'class' });
 
-  readonly dotRef = viewChild<ElementRef>('dot');
+  readonly dotRef = viewChild.required<ElementRef>('dot');
   #dotAnim?: AnimationHandle;
-  #previousSelected?: boolean;
+  #mounted = false;
 
   protected readonly isSelected = computed(
     () => this.#group.value() === this.itemValue(),
   );
 
-  constructor() {
-    // Same guard pattern as UiCheckbox: `#previousSelected === undefined` skips
-    // the first run so a pre-selected item doesn't animate in on mount.
-    // The equality guard prevents duplicate animations if the effect re-runs.
-    effect(() => {
-      const selected = this.isSelected();
-      const el = this.dotRef()?.nativeElement;
-      if (!el || this.#previousSelected === undefined) {
-        this.#previousSelected = selected;
-        return;
-      }
-      // Defensive early return: with only `isSelected()` as a reactive input,
-      // Angular's computed equality dedupes same-value emissions so the effect
-      // never re-runs with an unchanged `selected`. Kept for safety on-device.
-      /* v8 ignore next 1 */
-      if (selected === this.#previousSelected) return;
-      this.#previousSelected = selected;
-
-      this.#dotAnim?.cancel();
-      this.#dotAnim = selected ? popIn(el) : popOut(el);
-    });
-  }
+  /**
+   * Pops the dot in when the item is selected and out when it's deselected.
+   * A field rather than a constructor: Angular's test build keeps a function
+   * for a constructor that nothing calls, which an app's coverage report
+   * would show as uncovered.
+   *
+   * The first run is the mount, skipped so a pre-selected item doesn't
+   * animate in. Every later run is a change of selection: `isSelected` is a
+   * computed, which only notifies when its value changes, and the dot is
+   * always in the template, so its query never changes.
+   */
+  protected readonly dotAnimation = effect(() => {
+    const selected = this.isSelected();
+    const el = this.dotRef().nativeElement;
+    if (!this.#mounted) {
+      this.#mounted = true;
+      return;
+    }
+
+    this.#dotAnim?.cancel();
+    this.#dotAnim = selected ? popIn(el) : popOut(el);
+  });
 
   protected readonly itemClass = computed(() =>
     cn(

package/dist/ui/components/scatter-chart/index.ts

@@ -1,6 +1,5 @@
 export {
+  type ScatterChartOptions,
   UiScatterChart,
-  UiScatterSeries,
-  computeDots,
-  type DotShape,
+  scatterChartDefinition,
 } from './scatter-chart';

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

@@ -1,35 +1,140 @@
+import { Component, signal } from '@angular/core';
+import {
+  fireEvent,
+  render,
+  waitForUpdate,
+} from '@blotch/angular-lynx-testing-library';
+import { createChartRuntime } from '@tanstack/charts/runtime';
+import type {
+  ChartDefinition,
+  SceneDot,
+  SceneNode,
+} from '@tanstack/charts/types';
 import { describe, expect, it } from 'vitest';
-import { computeDots } from './scatter-chart';
-
-describe('computeDots', () => {
-  it('centers a dot on its point (top-left offset by the radius)', () => {
-    const [dot] = computeDots([{ cx: 50, cy: 30, r: 4 }]);
-    expect(dot.left).toBe(46); // cx - r
-    expect(dot.top).toBe(26); // cy - r
-    expect(dot.size).toBe(8); // r * 2 — the box the circle fills
+import type { XYDatum } from '../chart/chart-presets';
+import { UiScatterChart, scatterChartDefinition } from './scatter-chart';
+
+const data = [
+  { x: 150, y: 50 },
+  { x: 160, y: 65 },
+  { x: 170, y: 70 },
+];
+
+/**
+ * Every dot in a definition's scene.
+ */
+const dots = (definition: ChartDefinition<any, any, any>) => {
+  const scene = createChartRuntime().render(definition, {
+    width: 300,
+    height: 200,
+  });
+  const found: SceneDot[] = [];
+  const walk = (nodes: readonly SceneNode[]) => {
+    for (const node of nodes) {
+      if (node.kind === 'group') {
+        if (!node.focus) walk(node.children);
+      } else if (node.kind === 'dot') found.push(node);
+    }
+  };
+  walk(scene.nodes);
+  return { scene, found };
+};
+
+describe('scatterChartDefinition', () => {
+  it('draws a dot per point, inset from the frame', () => {
+    const { scene, found } = dots(scatterChartDefinition({ data }));
+    expect(found).toHaveLength(3);
+    expect(found[0]!.radius).toBe(4);
+    expect(found[0]!.style?.fill).toBe('var(--primary)');
+    // The 4% inset widens the x domain past the data.
+    expect(scene.scales['x']!.domain[0]).toBeLessThan(150);
   });
 
-  it('honors a per-point radius (a bubble chart)', () => {
-    const [small, big] = computeDots([
-      { cx: 10, cy: 10, r: 2 },
-      { cx: 40, cy: 40, r: 9 },
-    ]);
-    expect(small.size).toBe(4);
-    expect(small.left).toBe(8);
-    expect(big.size).toBe(18);
-    expect(big.left).toBe(31); // 40 - 9
+  it('sizes points individually for a bubble chart', () => {
+    const { found } = dots(
+      scatterChartDefinition({ data, sizes: [2, 8], radius: 5 }),
+    );
+    expect(found.map((dot) => dot.radius)).toEqual([2, 8, 5]);
   });
 
-  it('keeps each dot centered on its own coordinates', () => {
-    const dots = computeDots([
-      { cx: 0, cy: 100, r: 3 },
-      { cx: 100, cy: 0, r: 3 },
-    ]);
-    expect(dots[0]).toEqual({ left: -3, top: 97, size: 6 });
-    expect(dots[1]).toEqual({ left: 97, top: -3, size: 6 });
+  it('cycles per-point colors and keeps explicit padding', () => {
+    const { scene, found } = dots(
+      scatterChartDefinition({
+        data,
+        colors: ['red', 'blue'],
+        xMin: 150,
+        xMax: 170,
+        padding: { left: 0, right: 0, top: 0, bottom: 0 },
+        tooltip: false,
+      }),
+    );
+    expect(found.map((dot) => dot.style?.fill)).toEqual(['red', 'blue', 'red']);
+    expect(scene.scales['x']!.domain).toEqual([150, 170]);
   });
+});
+
+@Component({
+  imports: [UiScatterChart],
+  template: `
+    <ui-scatter-chart
+      [data]="data"
+      [width]="300"
+      [radius]="radius()"
+      (pointTap)="tapped.push($event)"
+    />
+  `,
+})
+class ScatterChartHost {
+  readonly data = data;
+  readonly radius = signal(7);
+  /** Every `pointTap`, in order. */
+  readonly tapped: XYDatum[] = [];
+}
+
+/**
+ * The SVG the chart's marks layer draws.
+ */
+const marksSvg = (container: Element) =>
+  container.querySelectorAll('svg')[1]!.getAttribute('content')!;
+
+/**
+ * Where the chart drew each dot, and how big.
+ */
+const dotsDrawn = (container: Element) =>
+  [
+    ...marksSvg(container).matchAll(
+      /<circle cx="([\d.-]+)" cy="([\d.-]+)" r="([\d.-]+)"/g,
+    ),
+  ].map(([, x, y, r]) => ({ x: Number(x), y: Number(y), r: Number(r) }));
+
+/**
+ * Touches a spot of the chart and lifts the finger right there: a tap.
+ */
+const tap = async (container: Element, at: { x: number; y: number }) => {
+  const root = container.querySelector('[accessibility-label]')!;
+  fireEvent.touchstart(root, { touches: [at] });
+  fireEvent.touchend(root, { touches: [at] });
+  await waitForUpdate();
+};
+
+describe('UiScatterChart', () => {
+  it('draws a dot per datum with its inputs', async () => {
+    const { componentRef, container } = await render(ScatterChartHost);
+    expect(dotsDrawn(container).map((dot) => dot.r)).toEqual([7, 7, 7]);
+
+    (componentRef.instance as ScatterChartHost).radius.set(3);
+    await waitForUpdate();
+    expect(dotsDrawn(container).map((dot) => dot.r)).toEqual([3, 3, 3]);
+  });
+
+  it("emits a tapped point's datum, and nothing for a tap off the points", async () => {
+    const { componentRef, container } = await render(ScatterChartHost);
+    const host = componentRef.instance as ScatterChartHost;
+    const last = dotsDrawn(container)[2]!;
+    await tap(container, { x: last.x, y: last.y });
+    expect(host.tapped).toEqual([data[2]]);
 
-  it('returns an empty array for no points', () => {
-    expect(computeDots([])).toEqual([]);
+    await tap(container, { x: -100, y: -100 });
+    expect(host.tapped).toEqual([data[2]]);
   });
 });

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

@@ -2,276 +2,130 @@ import {
   Component,
   ViewEncapsulation,
   computed,
-  inject,
   input,
   output,
 } from '@angular/core';
-import { LYNX_ELEMENTS } from '@blotch/angular-lynx';
+import { defineChart, dot } from '@tanstack/charts/universal';
+import type { ChartPoint } from '@tanstack/charts/types';
 
+import { UiChart, tooltip } from '../chart/chart';
 import {
-  type ChartPadding,
-  type ChartPoint,
-  UiCartesianChart,
-  niceScale,
-} from '../cartesian-chart/cartesian-chart';
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-// A scatter mark is just an (x, y) datum, so it reuses the shared `ChartPoint`
-// rather than defining its own. That also lets a scatter series and a line
-// series (e.g. a regression line) share one dataset on the same axes.
-
-/** One point after projection into plot-local pixel space, with its dot radius. */
-type ProjectedDot = {
-  /** Center x of the dot, in px. */
-  cx: number;
-  /** Center y of the dot, in px. */
-  cy: number;
-  /** Dot radius in px (varies per point for a bubble chart). */
-  r: number;
-};
-
-/** A square (rendered as a circle via border-radius) in plot-local pixel space. */
-export type DotShape = { left: number; top: number; size: number };
-
-// ---------------------------------------------------------------------------
-// Pure geometry (exported so it can be unit-tested without Angular)
-// ---------------------------------------------------------------------------
-
-/**
- * Turns projected points — already in plot-local pixel space — into square boxes
- * centered on each point, ready to render as circular `<view>`s (the caller sets
- * `border-radius` to half the size). A scatter mark is the simplest chart mark
- * of all: one box per datum, positioned so the point sits at its center.
- *
- * Each dot's radius comes from the point itself, so a per-point radius (a bubble
- * chart) and a uniform radius (a plain scatter) share this one mapping.
- */
-export const computeDots = (dots: readonly ProjectedDot[]): DotShape[] =>
-  dots.map((d) => ({ left: d.cx - d.r, top: d.cy - d.r, size: d.r * 2 }));
-
-// ---------------------------------------------------------------------------
-// Rendering helpers (mirror the equivalents in line-chart.ts / bar-chart.ts —
-// kept local so this module stays self-contained when scaffolded by `dolan add`)
-// ---------------------------------------------------------------------------
+  type CartesianPresetOptions,
+  PRESET_CHART_BINDINGS,
+  UiCartesianPreset,
+  type XYDatum,
+  presetAxes,
+} from '../chart/chart-presets';
+
+export type ScatterChartOptions = {
+  readonly data: readonly XYDatum[];
+  /** Any CSS color; theme tokens like `var(--primary)` follow dark mode. */
+  readonly color?: string;
+  /** One color per point, cycling; overrides `color` when not empty. */
+  readonly colors?: readonly string[];
+  /** Dot radius in px. */
+  readonly radius?: number;
+  /** One radius per point (a bubble chart); points past its end use `radius`. */
+  readonly sizes?: readonly number[];
+} & CartesianPresetOptions;
 
 /**
- * Formats a pixel value for an inline style, avoiding scientific notation.
+ * Scatter plots inset every side by 4% unless told otherwise, so dots at the
+ * extremes aren't cut in half by the frame.
  */
-const px = (n: number): string => `${n.toFixed(2)}px`;
-
-/**
- * Default axis label formatter — plain JS only (no `Intl`, absent in Lynx).
- */
-const defaultTickFormat = (value: number): string =>
-  String(Math.round(value * 100) / 100);
-
-// Default inner inset (fraction of the plot) for the wrapper. Unlike the line
-// chart, a scatter's marks are dots at the data extremes, so a small inset on
-// every side keeps the edge dots from being clipped by the frame.
 const SCATTER_INSET = 0.04;
 
-/**
- * A single scatter series drawn inside a `<ui-cartesian-chart>`. Reads the shared
- * scales from the parent chart via DI and renders one circular `<view>` per datum
- * at its (x, y) position.
- *
- * ## Why the host is `position: absolute; width/height: 100%`
- * Identical to `UiLineSeries`: Lynx resolves an absolute child against its
- * **direct parent** (there is no `position: static`), so the host itself must be
- * the plot-sized containing block. Every dot is a direct child of it.
- *
- * ## Per-point colors and sizes
- * `color` fills every dot by default; pass `colors` to tint each dot (a
- * categorical scatter) — the palette cycles if it is shorter than the data. Pass
- * `sizes` to give each dot its own radius (a bubble chart); a point with no entry
- * falls back to the uniform `radius`.
- */
-@Component({
-  selector: 'ui-scatter-series',
-  standalone: true,
-  imports: [LYNX_ELEMENTS],
-  encapsulation: ViewEncapsulation.None,
-  host: {
-    style:
-      'position: absolute; left: 0px; top: 0px; width: 100%; height: 100%;',
-    '[class]': 'userClass()',
-  },
-  template: `
-    @for (dot of dots(); track $index) {
-      <view [style]="dot.style" (bindtap)="onPointTap(dot.point)"></view>
-    }
-  `,
-})
-export class UiScatterSeries {
-  readonly #chart = inject(UiCartesianChart);
-
-  readonly data = input.required<ChartPoint[]>();
-  /** Fill for every dot. Overridden per dot by `colors` when that is set. */
-  readonly color = input('var(--primary)');
-  /** Per-dot fills (a categorical palette). Cycles when shorter than the data;
-   * an empty array falls back to `color`. */
-  readonly colors = input<string[]>([]);
-  /** Uniform dot radius in px. Overridden per dot by `sizes`. */
-  readonly radius = input(4);
-  /** Per-dot radii in px (a bubble chart). A point with no entry uses `radius`. */
-  readonly sizes = input<number[]>([]);
-  readonly userClass = input<string>('', { alias: 'class' });
-
-  readonly pointTap = output<ChartPoint>();
-
-  // Project each datum into plot-local pixel space via the shared scales, picking
-  // up a per-point radius when `sizes` supplies one. Reading the chart's scale
-  // signals here makes this recompute whenever the domain or plot size changes.
-  readonly #projected = computed(() => {
-    const scaleX = this.#chart.xScale();
-    const scaleY = this.#chart.yScale();
-    const sizes = this.sizes();
-    const r = this.radius();
-    return this.data().map((point, i) => ({
-      cx: scaleX(point.x),
-      cy: scaleY(point.y),
-      r: sizes[i] ?? r,
-      point,
-    }));
-  });
-
-  protected readonly dots = computed(() => {
-    const projected = this.#projected();
-    const fallback = this.color();
-    const palette = this.colors();
-    // computeDots works purely from the projected pixel fields; zip its output
-    // back with each source point so a dot's tap can emit the original datum.
-    // A circle is a square with border-radius of half its size.
-    return computeDots(projected).map((shape, i) => {
-      const fill = palette.length ? palette[i % palette.length] : fallback;
-      return {
-        point: projected[i].point,
-        style:
-          `position: absolute; left: ${px(shape.left)}; top: ${px(shape.top)}; ` +
-          `width: ${px(shape.size)}; height: ${px(shape.size)}; ` +
-          `background-color: ${fill}; border-radius: ${px(shape.size / 2)};`,
-      };
-    });
+/** The definition `<ui-scatter-chart>` renders. */
+export const scatterChartDefinition = (options: ScatterChartOptions) => {
+  const {
+    data,
+    color = 'var(--primary)',
+    colors = [],
+    radius = 4,
+    sizes = [],
+  } = options;
+  const padding = options.padding ?? {};
+  return defineChart({
+    marks: [
+      dot(data, {
+        x: 'x',
+        y: 'y',
+        r: sizes.length ? (_d, { index }) => sizes[index] ?? radius : radius,
+        // dot's fill is a single color, so per-point colors go through the
+        // color scale, keyed by point index.
+        ...(colors.length
+          ? { color: (_d: XYDatum, { index }: { index: number }) => index }
+          : { fill: color }),
+      }),
+    ],
+    scales: presetAxes(
+      {
+        ...options,
+        padding: {
+          top: padding.top ?? SCATTER_INSET,
+          right: padding.right ?? SCATTER_INSET,
+          bottom: padding.bottom ?? SCATTER_INSET,
+          left: padding.left ?? SCATTER_INSET,
+        },
+      },
+      { x: data.map((d) => d.x), y: data.map((d) => d.y) },
+    ),
+    ...(colors.length
+      ? {
+          color: {
+            domain: data.map((_d, index) => index),
+            range: data.map((_d, index) => colors[index % colors.length]!),
+          },
+        }
+      : {}),
+    tooltip: options.tooltip === false ? false : tooltip,
   });
-
-  protected onPointTap(point: ChartPoint): void {
-    this.pointTap.emit(point);
-  }
-}
+};
 
 /**
- * A ready-to-use scatter chart for the common single-series case. Composes a
- * `<ui-cartesian-chart>` with one `<ui-scatter-series>` and auto-derives rounded
- * axis domains + ticks from the data. For a regression/trend line on top, or
- * full control over the axes, use `<ui-cartesian-chart>` with a
- * `<ui-scatter-series>` (and optionally a `<ui-line-series>`) directly.
+ * A scatter plot, or a bubble chart with `sizes`. For a trend line or several
+ * groups with a legend, build a definition with `dot` (and `linearRegressionY`)
+ * and render it with `<ui-chart>`.
+ *
+ * ```html
+ * <ui-scatter-chart [data]="heightWeight" xAxisLabel="Height" yAxisLabel="Weight" />
+ * ```
  */
 @Component({
   selector: 'ui-scatter-chart',
-  standalone: true,
-  imports: [LYNX_ELEMENTS, UiCartesianChart, UiScatterSeries],
+  imports: [UiChart],
   encapsulation: ViewEncapsulation.None,
   template: `
-    <ui-cartesian-chart
-      [xDomain]="xAxis().domain"
-      [yDomain]="yAxis().domain"
-      [xTicks]="xAxis().ticks"
-      [yTicks]="yAxis().ticks"
-      [width]="width()"
-      [height]="height()"
-      [tickCount]="tickCount()"
-      [showXGrid]="showXGrid()"
-      [xAxisLabel]="xAxisLabel()"
-      [yAxisLabel]="yAxisLabel()"
-      [padding]="effectivePadding()"
-      [xTickFormat]="xTickFormat()"
-      [yTickFormat]="yTickFormat()"
-      [zoomable]="zoomable()"
-      [zoomAxes]="zoomAxes()"
-      [showZoomControls]="showZoomControls()"
-      [minZoom]="minZoom()"
-      [maxZoom]="maxZoom()"
-      [zoomStep]="zoomStep()"
-      [class]="userClass()"
-    >
-      <ui-scatter-series
-        [data]="data()"
-        [color]="color()"
-        [colors]="colors()"
-        [radius]="radius()"
-        [sizes]="sizes()"
-        (pointTap)="pointTap.emit($event)"
-      />
-    </ui-cartesian-chart>
+    <ui-chart
+      [definition]="definition()"
+      ${PRESET_CHART_BINDINGS}
+      (pointSelect)="onSelect($event)"
+    />
   `,
 })
-export class UiScatterChart {
-  readonly data = input.required<ChartPoint[]>();
+export class UiScatterChart extends UiCartesianPreset<XYDatum> {
+  readonly data = input.required<readonly XYDatum[]>();
   readonly color = input('var(--primary)');
-  readonly colors = input<string[]>([]);
+  readonly colors = input<readonly string[]>([]);
   readonly radius = input(4);
-  readonly sizes = input<number[]>([]);
-  readonly width = input(320);
-  readonly height = input(200);
-  readonly tickCount = input(5);
-  /** Draw vertical gridlines at each x tick (horizontal ones are on by default). */
-  readonly showXGrid = input(false);
-  /** Title for the x-axis (centered below the tick labels). */
-  readonly xAxisLabel = input<string>('');
-  /** Title for the y-axis (rotated in the left gutter). */
-  readonly yAxisLabel = input<string>('');
-  /** Inner inset of the plot area — merged over the default all-side inset
-   * (below), so any side you set wins. See {@link ChartPadding}. */
-  readonly padding = input<ChartPadding>({});
-  /** Force the x-axis lower/upper bound instead of deriving it from the data.
-   * Omitted bounds fall back to the data extremes. */
-  readonly xMin = input<number | undefined>(undefined);
-  readonly xMax = input<number | undefined>(undefined);
-  /** Force the y-axis lower/upper bound (e.g. to compare two charts on one scale). */
-  readonly yMin = input<number | undefined>(undefined);
-  readonly yMax = input<number | undefined>(undefined);
-  readonly xTickFormat = input<(value: number) => string>(defaultTickFormat);
-  readonly yTickFormat = input<(value: number) => string>(defaultTickFormat);
-  readonly userClass = input<string>('', { alias: 'class' });
-
-  // Pan/zoom — forwarded to the underlying <ui-cartesian-chart>. Off by default.
-  readonly zoomable = input(false);
-  readonly zoomAxes = input<'x' | 'y' | 'xy'>('xy');
-  readonly showZoomControls = input(true);
-  readonly minZoom = input(1);
-  readonly maxZoom = input(8);
-  readonly zoomStep = input(1.4);
-
-  readonly pointTap = output<ChartPoint>();
-
-  // Auto-compute rounded axes from the data extremes, letting an explicit
-  // min/max override either end. Unlike the bar/area charts there is no baseline
-  // to fold in — both axes simply fit the data. `Math.min/max(...[])` yield
-  // ±Infinity for empty data, which `niceScale` handles by padding.
-  protected readonly xAxis = computed(() => {
-    const xs = this.data().map((p) => p.x);
-    const lo = this.xMin() ?? Math.min(...xs);
-    const hi = this.xMax() ?? Math.max(...xs);
-    return niceScale(lo, hi, this.tickCount());
-  });
-  protected readonly yAxis = computed(() => {
-    const ys = this.data().map((p) => p.y);
-    const lo = this.yMin() ?? Math.min(...ys);
-    const hi = this.yMax() ?? Math.max(...ys);
-    return niceScale(lo, hi, this.tickCount());
-  });
-
-  // Dots sit at the data extremes, so without an inset the edge dots would be
-  // clipped by the frame. Default a small inset on every side; user `padding` is
-  // spread last, so an explicit side wins.
-  protected readonly effectivePadding = computed<ChartPadding>(() => ({
-    top: SCATTER_INSET,
-    right: SCATTER_INSET,
-    bottom: SCATTER_INSET,
-    left: SCATTER_INSET,
-    ...this.padding(),
-  }));
+  readonly sizes = input<readonly number[]>([]);
+
+  /** The tapped point's datum. */
+  readonly pointTap = output<XYDatum>();
+
+  protected readonly definition = computed(() =>
+    scatterChartDefinition({
+      ...this.commonOptions(),
+      data: this.data(),
+      color: this.color(),
+      colors: this.colors(),
+      radius: this.radius(),
+      sizes: this.sizes(),
+    }),
+  );
+
+  protected onSelect(point: ChartPoint | null): void {
+    const datum = this.datumOf(point);
+    if (datum) this.pointTap.emit(datum);
+  }
 }