@pibbl/core 0.0.1 → 0.0.3-alpha.85.1

package/dist/features/viz/inspection/volume.js

@@ -0,0 +1,95 @@
+import {
+  invertNumericPosition
+} from "../lib/series-position.js";
+import { useRenderedRef } from "./owned-ref.js";
+import { nearestRecordedX } from "./queries.js";
+function useVolumeInspection(_inputs) {
+  return useRenderedRef("volumeInspection", (candidate, geometry) => {
+    const observations = Object.freeze(
+      candidate.marks.map(
+        (mark) => Object.freeze({
+          datum: mark.datum,
+          sourceIndex: mark.sourceIndex,
+          time: mark.time,
+          volume: mark.volume,
+          baseline: mark.baseline,
+          anchorLocal: mark.anchorLocal,
+          anchorRoot: geometry.rootAtLocal(mark.anchorLocal),
+          boundsLocal: mark.boundsLocal
+        })
+      )
+    );
+    const numeric = Object.freeze({
+      observations: Object.freeze(
+        observations.map(
+          (row) => Object.freeze({
+            ...row,
+            domainX: row.time,
+            domainY: row.volume,
+            run: 0
+          })
+        )
+      ),
+      assertLive: geometry.assertLive,
+      domainXAtRoot(point) {
+        const local = geometry.localAtRoot(point);
+        return local ? invertNumericPosition(candidate.xScale, local.x) : void 0;
+      },
+      anchorInsideClips: geometry.anchorInsideClips,
+      anchorAtDomain(point) {
+        geometry.assertLive();
+        const anchorLocal = Object.freeze({
+          x: candidate.xScale.map(point.domainX),
+          y: candidate.yScale.map(point.domainY)
+        });
+        return Object.freeze({
+          anchorLocal,
+          anchorRoot: geometry.rootAtLocal(anchorLocal)
+        });
+      }
+    });
+    return Object.freeze({
+      observations,
+      marks: Object.freeze(candidate.marks.slice()),
+      numeric,
+      assertLive: geometry.assertLive,
+      localAtRoot: geometry.localAtRoot,
+      anchorInsideClips: geometry.anchorInsideClips,
+      timeAtRoot: numeric.domainXAtRoot
+    });
+  });
+}
+function nearestRecordedVolumeX(rendered, options) {
+  const hit = nearestRecordedX(rendered.numeric, {
+    domainX: options.time,
+    filter: options.filter ? (candidate) => options.filter(
+      candidate
+    ) : void 0
+  });
+  if (!hit) return void 0;
+  const row = rendered.observations.find(
+    (row2) => row2.sourceIndex === hit.sourceIndex
+  );
+  return Object.freeze({ ...row, timeDelta: hit.domainDelta });
+}
+function paintedVolumeAt(rendered, options) {
+  rendered.assertLive();
+  if (!Number.isFinite(options.rootPoint.x) || !Number.isFinite(options.rootPoint.y))
+    throw new RangeError("paintedVolumeAt rootPoint must be finite.");
+  const p = rendered.localAtRoot(options.rootPoint);
+  if (!p || !rendered.anchorInsideClips(p)) return void 0;
+  for (let i = rendered.marks.length - 1; i >= 0; i--) {
+    const mark = rendered.marks[i], b = mark.boundsLocal, h = mark.strokeWidthLocal / 2;
+    if (b.height === 0) continue;
+    const inside = p.x >= b.x && p.x <= b.x + b.width && p.y >= b.y && p.y <= b.y + b.height;
+    const outline = h > 0 && p.x >= b.x - h && p.x <= b.x + b.width + h && p.y >= b.y - h && p.y <= b.y + b.height + h && !(p.x > b.x + h && p.x < b.x + b.width - h && p.y > b.y + h && p.y < b.y + b.height - h);
+    if (mark.fill && inside || outline) return rendered.observations[i];
+  }
+  return void 0;
+}
+export {
+  nearestRecordedVolumeX,
+  paintedVolumeAt,
+  useVolumeInspection
+};
+//# sourceMappingURL=volume.js.map

package/dist/features/viz/inspection/volume.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/viz/inspection/volume.ts"],
+  "sourcesContent": ["import {\n  invertNumericPosition,\n  type NumericPositionScale,\n} from \"../lib/series-position.js\";\nimport type { LayoutBox } from \"@pibbl/core\";\nimport type { VolumeSeriesProps } from \"../lib/volume-series.js\";\nimport type { ResolvedContinuousScale } from \"../lib/types.js\";\nimport type {\n  RenderedSeriesPoint,\n  NumericRenderedSeries,\n} from \"./query-types.js\";\nimport { useRenderedRef } from \"./owned-ref.js\";\nimport { nearestRecordedX } from \"./queries.js\";\n\n/** One original volume record and the values/geometry evaluated during paint.\n * @see {@link useVolumeInspection}\n */\nexport interface VolumeObservation<D> {\n  /** Caller-owned original record. */ readonly datum: D;\n  /** Original index including skipped rows. */ readonly sourceIndex: number;\n  /** Evaluated UTC milliseconds. */ readonly time: number;\n  /** Evaluated nonnegative volume. */ readonly volume: number;\n  /** Zero-volume baseline. */ readonly baseline: 0;\n  /** Volume endpoint in series-local logical coordinates. */ readonly anchorLocal: Readonly<RenderedSeriesPoint>;\n  /** Volume endpoint in root-logical coordinates. */ readonly anchorRoot: Readonly<RenderedSeriesPoint>;\n  /** Column bounds in series-local logical coordinates. */ readonly boundsLocal: Readonly<LayoutBox>;\n}\n/** A nearest-time candidate with an explicit optional clip predicate.\n * @see {@link useVolumeInspection}\n */\nexport interface VolumeInspectionCandidate<D> extends VolumeObservation<D> {\n  /** @returns Whether the endpoint lies inside every committed clip. */ anchorInsideClips(): boolean;\n}\n/** A recorded volume selected by timestamp proximity.\n * @see {@link useVolumeInspection}\n */\nexport interface NearestVolumeHit<D> extends VolumeObservation<D> {\n  /** Absolute UTC-millisecond distance from the requested time. */ readonly timeDelta: number;\n}\n/** A recorded volume whose painted column covers the query point.\n * @see {@link useVolumeInspection}\n */\nexport interface PaintedVolumeHit<D> extends VolumeObservation<D> {}\n/** @internal Immutable local renderer capture, without queries or transformed allocation.\n * @see {@link useVolumeInspection}\n */\nexport interface CapturedVolumeMark<D> extends Omit<\n  VolumeObservation<D>,\n  \"anchorRoot\"\n> {\n  /** Whether the rectangle paints its interior. */ readonly fill: boolean;\n  /** Outline width when painted, zero otherwise. */ readonly strokeWidthLocal: number;\n}\n/** Borrowed committed volume values; expires after a new root generation or disposal.\n * @see {@link useVolumeInspection}\n */\nexport interface VolumeRenderedSeries<D> {\n  /** Original observations and evaluated values in source order. */ readonly observations: readonly VolumeObservation<D>[];\n  /** Throws when borrowed values are stale or disposed. */ assertLive(): void;\n  /** Inverts a root-logical point to UTC milliseconds.\n   * @param pointRoot - Root-logical Canvas position.\n   * @returns Timestamp or undefined for unavailable inversion.\n   */ timeAtRoot(pointRoot: Readonly<RenderedSeriesPoint>): number | undefined;\n  /** Tests a local point against the committed clip stack.\n   * @param pointLocal - Series-local position.\n   * @returns Whether every clip includes it.\n   */ anchorInsideClips(pointLocal: Readonly<RenderedSeriesPoint>): boolean;\n  /** @internal Committed paint flags. */ readonly marks: readonly CapturedVolumeMark<D>[];\n  /** @internal Shared numeric query view. */ readonly numeric: NumericRenderedSeries<D>;\n  /** @internal Converts root coordinates to local coordinates.\n   * @param point - Root-logical position.\n   * @returns Local position or undefined for a singular transform.\n   */ localAtRoot(\n    point: Readonly<RenderedSeriesPoint>,\n  ): Readonly<RenderedSeriesPoint> | undefined;\n}\n/** Mount-owned optional volume capture.\n * @see {@link useVolumeInspection}\n */\nexport interface VolumeInspectionRef<D> {\n  /** @returns Borrowed committed values, or undefined before paint/after disposal. */ rendered():\n    VolumeRenderedSeries<D> | undefined;\n  /** @internal Records local values without executing a query.\n   * @param input - Immutable local marks and committed time mapping.\n   */ capture(input: {\n    /** Captured local paint marks. */ marks: readonly CapturedVolumeMark<D>[];\n    /** Committed horizontal mapping. */ xScale: NumericPositionScale;\n    /** Committed volume mapping. */ yScale: ResolvedContinuousScale;\n  }): void;\n}\n/**\n * Creates a stable optional volume receiver without reading data or subscribing.\n * @param _inputs - Data/accessors used only for original datum inference.\n * @returns Ref to pass to exactly one VolumeSeries inspection prop.\n * @see {@link VolumeInspectionRef}\n */\nexport function useVolumeInspection<D>(\n  _inputs: Pick<VolumeSeriesProps<D>, \"data\" | \"time\" | \"volume\">,\n): VolumeInspectionRef<D> {\n  return useRenderedRef<\n    {\n      marks: readonly CapturedVolumeMark<D>[];\n      xScale: NumericPositionScale;\n      yScale: ResolvedContinuousScale;\n    },\n    VolumeRenderedSeries<D>\n  >(\"volumeInspection\", (candidate, geometry) => {\n    const observations = Object.freeze(\n      candidate.marks.map((mark) =>\n        Object.freeze({\n          datum: mark.datum,\n          sourceIndex: mark.sourceIndex,\n          time: mark.time,\n          volume: mark.volume,\n          baseline: mark.baseline,\n          anchorLocal: mark.anchorLocal,\n          anchorRoot: geometry.rootAtLocal(mark.anchorLocal),\n          boundsLocal: mark.boundsLocal,\n        }),\n      ),\n    );\n    const numeric: NumericRenderedSeries<D> = Object.freeze({\n      observations: Object.freeze(\n        observations.map((row) =>\n          Object.freeze({\n            ...row,\n            domainX: row.time,\n            domainY: row.volume,\n            run: 0,\n          }),\n        ),\n      ),\n      assertLive: geometry.assertLive,\n      domainXAtRoot(point: Readonly<RenderedSeriesPoint>) {\n        const local = geometry.localAtRoot(point);\n        return local\n          ? invertNumericPosition(candidate.xScale, local.x)\n          : undefined;\n      },\n      anchorInsideClips: geometry.anchorInsideClips,\n      anchorAtDomain(point: Readonly<{ domainX: number; domainY: number }>) {\n        geometry.assertLive();\n        const anchorLocal = Object.freeze({\n          x: candidate.xScale.map(point.domainX),\n          y: candidate.yScale.map(point.domainY),\n        });\n        return Object.freeze({\n          anchorLocal,\n          anchorRoot: geometry.rootAtLocal(anchorLocal),\n        });\n      },\n    });\n    return Object.freeze({\n      observations,\n      marks: Object.freeze(candidate.marks.slice()),\n      numeric,\n      assertLive: geometry.assertLive,\n      localAtRoot: geometry.localAtRoot,\n      anchorInsideClips: geometry.anchorInsideClips,\n      timeAtRoot: numeric.domainXAtRoot,\n    });\n  });\n}\n/**\n * Selects a recorded volume by timestamp; equal distances choose first source index.\n * @param rendered - Borrowed committed volume values.\n * @param options - UTC-millisecond request and optional pure candidate filter.\n * @returns Captured original volume and time delta, or undefined when no candidate survives.\n * @see {@link NearestVolumeHit}\n */\nexport function nearestRecordedVolumeX<D>(\n  rendered: VolumeRenderedSeries<D>,\n  options: {\n    time: number;\n    filter?: (observation: VolumeInspectionCandidate<D>) => boolean;\n  },\n): NearestVolumeHit<D> | undefined {\n  const hit = nearestRecordedX(rendered.numeric, {\n    domainX: options.time,\n    filter: options.filter\n      ? (candidate) =>\n          options.filter!(\n            candidate as typeof candidate & VolumeInspectionCandidate<D>,\n          )\n      : undefined,\n  });\n  if (!hit) return undefined;\n  const row = rendered.observations.find(\n    (row) => row.sourceIndex === hit.sourceIndex,\n  )!;\n  return Object.freeze({ ...row, timeDelta: hit.domainDelta });\n}\n/**\n * Finds the last-painted volume column covering a root-logical point.\n * @param rendered - Borrowed committed volume values and paint geometry.\n * @param options - Root-logical point; respects clips, zero height and source paint order.\n * @returns Captured original volume, or undefined for gaps/singular transforms.\n * @see {@link PaintedVolumeHit}\n */\nexport function paintedVolumeAt<D>(\n  rendered: VolumeRenderedSeries<D>,\n  options: { rootPoint: Readonly<RenderedSeriesPoint> },\n): PaintedVolumeHit<D> | undefined {\n  rendered.assertLive();\n  if (\n    !Number.isFinite(options.rootPoint.x) ||\n    !Number.isFinite(options.rootPoint.y)\n  )\n    throw new RangeError(\"paintedVolumeAt rootPoint must be finite.\");\n  const p = rendered.localAtRoot(options.rootPoint);\n  if (!p || !rendered.anchorInsideClips(p)) return undefined;\n  for (let i = rendered.marks.length - 1; i >= 0; i--) {\n    const mark = rendered.marks[i],\n      b = mark.boundsLocal,\n      h = mark.strokeWidthLocal / 2;\n    if (b.height === 0) continue;\n    const inside =\n      p.x >= b.x && p.x <= b.x + b.width && p.y >= b.y && p.y <= b.y + b.height;\n    const outline =\n      h > 0 &&\n      p.x >= b.x - h &&\n      p.x <= b.x + b.width + h &&\n      p.y >= b.y - h &&\n      p.y <= b.y + b.height + h &&\n      !(\n        p.x > b.x + h &&\n        p.x < b.x + b.width - h &&\n        p.y > b.y + h &&\n        p.y < b.y + b.height - h\n      );\n    if ((mark.fill && inside) || outline) return rendered.observations[i];\n  }\n  return undefined;\n}\n"],
+  "mappings": "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",
+  "names": ["row"]
+}

package/dist/features/viz/inspection.d.ts

@@ -0,0 +1,19 @@
+/** Optional committed-render inspection. Rendering entries do not import these algorithms. */
+export { useNumericInspection, usePointInspection, } from "./inspection/capture.js";
+export { withInspection } from "./inspection/handler.js";
+export { paintedPointAt } from "./inspection/painted-point.js";
+export { useBarInspection, paintedBarAt } from "./inspection/bar.js";
+export type { BarInspectionRef, BarRenderedSeries, PaintedBarHit, } from "./inspection/bar.js";
+export type { PaintedPointHit } from "./inspection/painted-point.js";
+export type { InspectionContext, InspectionRef } from "./inspection/handler.js";
+export type { NumericInspectionRef, PointInspectionRef, PointRenderedSeries, } from "./inspection/capture-types.js";
+export { nearestRecordedX, nearestRecordedPoint, sampleRecordedX, firstSourceObservation, lastSourceObservation, anchorInsideClips, } from "./inspection/queries.js";
+export type { NumericRenderedSeries, NumericRenderedObservation, RecordedNumericHit, NearestRecordedXHit, NearestRecordedPointHit, RecordedXSample, NumericRenderedFilter, NumericDuplicateResolver, NumericDomainInterpolation, RenderedSeriesPoint, } from "./inspection/query-types.js";
+export type { NumericRenderedSeries as RenderedSeries, InspectionCandidate, NumericRenderedAnchors, } from "./inspection/query-types.js";
+export type { NearestRecordedXOptions, NearestRecordedPointOptions, SampleRecordedXOptions, } from "./inspection/queries.js";
+export { useVolumeInspection, nearestRecordedVolumeX, paintedVolumeAt, } from "./inspection/volume.js";
+export type { VolumeObservation, VolumeInspectionCandidate, NearestVolumeHit, PaintedVolumeHit, VolumeInspectionRef, VolumeRenderedSeries, } from "./inspection/volume.js";
+export { useCandleInspection, nearestRecordedCandleX, paintedCandleAt, } from "./inspection/candle.js";
+export type { CandleObservation, CandleInspectionCandidate, NearestCandleHit, PaintedCandleHit, CandleInspectionRef, CandleRenderedSeries, } from "./inspection/candle.js";
+export { useOhlcBarInspection, nearestRecordedOhlcBarX, paintedOhlcBarAt, } from "./inspection/ohlc-bar.js";
+export type { OhlcBarObservation, OhlcBarInspectionCandidate, NearestOhlcBarHit, PaintedOhlcBarHit, OhlcBarInspectionRef, OhlcBarRenderedSeries, } from "./inspection/ohlc-bar.js";

package/dist/features/viz/inspection.js

@@ -0,0 +1,54 @@
+import {
+  useNumericInspection,
+  usePointInspection
+} from "./inspection/capture.js";
+import { withInspection } from "./inspection/handler.js";
+import { paintedPointAt } from "./inspection/painted-point.js";
+import { useBarInspection, paintedBarAt } from "./inspection/bar.js";
+import {
+  nearestRecordedX,
+  nearestRecordedPoint,
+  sampleRecordedX,
+  firstSourceObservation,
+  lastSourceObservation,
+  anchorInsideClips
+} from "./inspection/queries.js";
+import {
+  useVolumeInspection,
+  nearestRecordedVolumeX,
+  paintedVolumeAt
+} from "./inspection/volume.js";
+import {
+  useCandleInspection,
+  nearestRecordedCandleX,
+  paintedCandleAt
+} from "./inspection/candle.js";
+import {
+  useOhlcBarInspection,
+  nearestRecordedOhlcBarX,
+  paintedOhlcBarAt
+} from "./inspection/ohlc-bar.js";
+export {
+  anchorInsideClips,
+  firstSourceObservation,
+  lastSourceObservation,
+  nearestRecordedCandleX,
+  nearestRecordedOhlcBarX,
+  nearestRecordedPoint,
+  nearestRecordedVolumeX,
+  nearestRecordedX,
+  paintedBarAt,
+  paintedCandleAt,
+  paintedOhlcBarAt,
+  paintedPointAt,
+  paintedVolumeAt,
+  sampleRecordedX,
+  useBarInspection,
+  useCandleInspection,
+  useNumericInspection,
+  useOhlcBarInspection,
+  usePointInspection,
+  useVolumeInspection,
+  withInspection
+};
+//# sourceMappingURL=inspection.js.map

package/dist/features/viz/inspection.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/features/viz/inspection.ts"],
+  "sourcesContent": ["/** Optional committed-render inspection. Rendering entries do not import these algorithms. */\nexport {\n  useNumericInspection,\n  usePointInspection,\n} from \"./inspection/capture.js\";\nexport { withInspection } from \"./inspection/handler.js\";\nexport { paintedPointAt } from \"./inspection/painted-point.js\";\nexport { useBarInspection, paintedBarAt } from \"./inspection/bar.js\";\nexport type {\n  BarInspectionRef,\n  BarRenderedSeries,\n  PaintedBarHit,\n} from \"./inspection/bar.js\";\nexport type { PaintedPointHit } from \"./inspection/painted-point.js\";\nexport type { InspectionContext, InspectionRef } from \"./inspection/handler.js\";\nexport type {\n  NumericInspectionRef,\n  PointInspectionRef,\n  PointRenderedSeries,\n} from \"./inspection/capture-types.js\";\nexport {\n  nearestRecordedX,\n  nearestRecordedPoint,\n  sampleRecordedX,\n  firstSourceObservation,\n  lastSourceObservation,\n  anchorInsideClips,\n} from \"./inspection/queries.js\";\nexport type {\n  NumericRenderedSeries,\n  NumericRenderedObservation,\n  RecordedNumericHit,\n  NearestRecordedXHit,\n  NearestRecordedPointHit,\n  RecordedXSample,\n  NumericRenderedFilter,\n  NumericDuplicateResolver,\n  NumericDomainInterpolation,\n  RenderedSeriesPoint,\n} from \"./inspection/query-types.js\";\n\nexport type {\n  NumericRenderedSeries as RenderedSeries,\n  InspectionCandidate,\n  NumericRenderedAnchors,\n} from \"./inspection/query-types.js\";\nexport type {\n  NearestRecordedXOptions,\n  NearestRecordedPointOptions,\n  SampleRecordedXOptions,\n} from \"./inspection/queries.js\";\nexport {\n  useVolumeInspection,\n  nearestRecordedVolumeX,\n  paintedVolumeAt,\n} from \"./inspection/volume.js\";\nexport type {\n  VolumeObservation,\n  VolumeInspectionCandidate,\n  NearestVolumeHit,\n  PaintedVolumeHit,\n  VolumeInspectionRef,\n  VolumeRenderedSeries,\n} from \"./inspection/volume.js\";\nexport {\n  useCandleInspection,\n  nearestRecordedCandleX,\n  paintedCandleAt,\n} from \"./inspection/candle.js\";\nexport type {\n  CandleObservation,\n  CandleInspectionCandidate,\n  NearestCandleHit,\n  PaintedCandleHit,\n  CandleInspectionRef,\n  CandleRenderedSeries,\n} from \"./inspection/candle.js\";\nexport {\n  useOhlcBarInspection,\n  nearestRecordedOhlcBarX,\n  paintedOhlcBarAt,\n} from \"./inspection/ohlc-bar.js\";\nexport type {\n  OhlcBarObservation,\n  OhlcBarInspectionCandidate,\n  NearestOhlcBarHit,\n  PaintedOhlcBarHit,\n  OhlcBarInspectionRef,\n  OhlcBarRenderedSeries,\n} from \"./inspection/ohlc-bar.js\";\n"],
+  "mappings": "AACA;AAAA,EACE;AAAA,EACA;AAAA,OACK;AACP,SAAS,sBAAsB;AAC/B,SAAS,sBAAsB;AAC/B,SAAS,kBAAkB,oBAAoB;AAa/C;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAwBP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AASP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AASP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;",
+  "names": []
+}

package/dist/features/viz/inspection.mjs

@@ -0,0 +1 @@
+export * from './inspection.js';

package/dist/features/viz/lib/area-series.d.ts

@@ -0,0 +1,62 @@
+import type { Path } from "@pibbl/core";
+import type { FillStyle, PibblEventHandlers, PibblEventParticipationOptions, SignalValue } from "@pibbl/core";
+import type { SignalStyle } from "@pibbl/core/internal";
+import type { LineAccessor, LineSeriesProps } from "./types.js";
+/**
+ * Presentation properties for an {@link AreaSeries}.
+ *
+ * @see {@link FillStyle}
+ * @see {@link AreaSeriesProps}
+ */
+export interface AreaSeriesStyle {
+    /** Paint used for the area interior. */
+    readonly fill?: FillStyle;
+    /** Opacity of the painted area, from zero through one. */
+    readonly opacity?: number;
+    /** Cursor shown while the area target owns pointer presentation. */
+    readonly cursor?: string;
+}
+/**
+ * Authored inputs for {@link AreaSeries}.
+ *
+ * The data, coordinate accessors, scales, and defined predicate use the same
+ * contract as {@link LineSeriesProps}. Each contiguous run of at least two
+ * valid observations is closed to `baseline` in data space.
+ *
+ * @see {@link LineSeriesProps}
+ * @see {@link AreaSeriesStyle}
+ */
+export interface AreaSeriesProps<D> extends PibblEventHandlers, PibblEventParticipationOptions {
+    /** Application data supplied directly or through a signal. */
+    readonly data: LineSeriesProps<D>["data"];
+    /** Property key or callback extracting the horizontal coordinate. */
+    readonly x: LineAccessor<D>;
+    /** Property key or callback extracting the vertical coordinate. */
+    readonly y: LineAccessor<D>;
+    /** Continuous scale used to map horizontal data coordinates. */
+    readonly xScale: LineSeriesProps<D>["xScale"];
+    /** Continuous scale used to map vertical data coordinates and baseline. */
+    readonly yScale: LineSeriesProps<D>["yScale"];
+    /** Selects records that participate in an observed run. */
+    readonly defined?: LineSeriesProps<D>["defined"];
+    /** Curve used to connect successive observed samples. */
+    readonly curve?: LineSeriesProps<D>["curve"];
+    /** Finite data-space value to which each observed run closes. */
+    readonly baseline: SignalValue<number>;
+    /** Shared area presentation. Individual datum styling is not supported. */
+    readonly style?: SignalValue<SignalStyle<AreaSeriesStyle>>;
+}
+/**
+ * Draws each contiguous observed run as a filled polygon closed to an explicit baseline.
+ *
+ * Missing, non-finite, and excluded coordinates split runs. A lone observation has no area.
+ * The component owns one ordinary {@link Path} target, so event participation follows the
+ * standard Path defaults; callers may wrap it in `Clip` when clipping is needed.
+ *
+ * @param props - Data, coordinate accessors, continuous scales, baseline, and presentation.
+ * @returns A Pibbl path node containing all drawable area runs.
+ * @throws When `data` is not an array, the baseline is not finite, or presentation is invalid.
+ *
+ * @see {@link AreaSeriesProps}
+ */
+export declare function AreaSeries<D>({ data: dataInput, x: xInput, y: yInput, xScale: xId, yScale: yId, baseline: baselineInput, defined, curve, style: styleInput, ...eventProps }: AreaSeriesProps<D>): import("../../../jsx-runtime.js").JSX.Element;

package/dist/features/viz/lib/area-series.js

@@ -0,0 +1,120 @@
+import { jsx } from "@pibbl/core/jsx-runtime";
+import { useNumericPosition } from "./series-position.js";
+import { Path, resolveSignalValue } from "@pibbl/core";
+import {
+  useInternalValueMemoSlot,
+  validateTexturePaint
+} from "@pibbl/core/internal";
+import {
+  appendCurveForward,
+  curveGeometry,
+  resolveSeriesCurve
+} from "./curve-definition.js";
+import { opacity } from "./paint.js";
+import { useContinuousScale } from "./use-continuous-scale.js";
+function accessor(input) {
+  return typeof input === "function" ? input : (datum) => datum[input];
+}
+function fill(value) {
+  if (typeof value === "string" || value instanceof CanvasGradient || value instanceof CanvasPattern)
+    return value;
+  try {
+    validateTexturePaint(value);
+    return value;
+  } catch {
+    throw new TypeError("AreaSeries: invalid fill.");
+  }
+}
+function AreaSeries({
+  data: dataInput,
+  x: xInput,
+  y: yInput,
+  xScale: xId,
+  yScale: yId,
+  baseline: baselineInput,
+  defined,
+  curve,
+  style: styleInput,
+  ...eventProps
+}) {
+  const xScale = useNumericPosition(xId);
+  const yScale = useContinuousScale(yId).get();
+  const curveDefinition = resolveSeriesCurve(curve);
+  const x = useInternalValueMemoSlot(
+    "vizAreaXAccessor",
+    () => accessor(xInput),
+    [xInput]
+  );
+  const y = useInternalValueMemoSlot(
+    "vizAreaYAccessor",
+    () => accessor(yInput),
+    [yInput]
+  );
+  const data = resolveSignalValue(dataInput);
+  if (!Array.isArray(data))
+    throw new TypeError(
+      "AreaSeries data must be an array or a signal containing an array."
+    );
+  const baseline = resolveSignalValue(baselineInput);
+  if (typeof baseline !== "number" || !Number.isFinite(baseline))
+    throw new RangeError("AreaSeries baseline must be finite.");
+  const baselineY = yScale.map(baseline);
+  if (!Number.isFinite(baselineY))
+    throw new RangeError(
+      "AreaSeries baseline must map to a finite coordinate."
+    );
+  const style = resolveSignalValue(styleInput) ?? {};
+  if (style === null || typeof style !== "object" || Array.isArray(style))
+    throw new TypeError("AreaSeries: style must be an object.");
+  const areaFill = fill(resolveSignalValue(style.fill) ?? "#2563eb");
+  const alpha = opacity(resolveSignalValue(style.opacity) ?? 0.2, "AreaSeries");
+  const cursor = resolveSignalValue(style.cursor);
+  if (cursor !== void 0 && typeof cursor !== "string")
+    throw new TypeError("AreaSeries: cursor must be a string.");
+  const path = new Path2D();
+  let run = [];
+  const closeRun = () => {
+    if (run.length >= 2) {
+      const first = run[0];
+      const last = run[run.length - 1];
+      const geometry = curveGeometry(curveDefinition, run);
+      path.moveTo(geometry.start[0], geometry.start[1]);
+      appendCurveForward(path, geometry);
+      path.lineTo(last[0], baselineY);
+      path.lineTo(first[0], baselineY);
+      path.closePath();
+    }
+    run = [];
+  };
+  for (let i = 0; i < data.length; i++) {
+    const datum = data[i];
+    if (defined && !defined(datum, i, data)) {
+      closeRun();
+      continue;
+    }
+    const xv = x(datum, i, data);
+    const yv = y(datum, i, data);
+    if (typeof xv !== "number" || typeof yv !== "number" || !Number.isFinite(xv) || !Number.isFinite(yv)) {
+      closeRun();
+      continue;
+    }
+    const point = [xScale.map(xv), yScale.map(yv)];
+    if (!Number.isFinite(point[0]) || !Number.isFinite(point[1])) {
+      closeRun();
+      continue;
+    }
+    run.push(point);
+  }
+  closeRun();
+  return /* @__PURE__ */ jsx(
+    Path,
+    {
+      ...eventProps,
+      style: { d: path, fill: areaFill, opacity: alpha, cursor }
+    }
+  );
+}
+export {
+  AreaSeries
+};
+//# sourceMappingURL=area-series.js.map

package/dist/features/viz/lib/area-series.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/viz/lib/area-series.tsx"],
+  "sourcesContent": ["import { useNumericPosition } from \"./series-position.js\";\nimport { Path, resolveSignalValue } from \"@pibbl/core\";\nimport type {\n  FillStyle,\n  PibblEventHandlers,\n  PibblEventParticipationOptions,\n  SignalValue,\n} from \"@pibbl/core\";\nimport {\n  useInternalValueMemoSlot,\n  validateTexturePaint,\n} from \"@pibbl/core/internal\";\nimport type { SignalStyle } from \"@pibbl/core/internal\";\nimport type { LineAccessor, LineCoordinate, LineSeriesProps } from \"./types.js\";\nimport {\n  appendCurveForward,\n  curveGeometry,\n  resolveSeriesCurve,\n} from \"./curve-definition.js\";\nimport { opacity } from \"./paint.js\";\nimport { useContinuousScale } from \"./use-continuous-scale.js\";\n\n/**\n * Presentation properties for an {@link AreaSeries}.\n *\n * @see {@link FillStyle}\n * @see {@link AreaSeriesProps}\n */\nexport interface AreaSeriesStyle {\n  /** Paint used for the area interior. */\n  readonly fill?: FillStyle;\n  /** Opacity of the painted area, from zero through one. */\n  readonly opacity?: number;\n  /** Cursor shown while the area target owns pointer presentation. */\n  readonly cursor?: string;\n}\n\n/**\n * Authored inputs for {@link AreaSeries}.\n *\n * The data, coordinate accessors, scales, and defined predicate use the same\n * contract as {@link LineSeriesProps}. Each contiguous run of at least two\n * valid observations is closed to `baseline` in data space.\n *\n * @see {@link LineSeriesProps}\n * @see {@link AreaSeriesStyle}\n */\nexport interface AreaSeriesProps<D>\n  extends PibblEventHandlers, PibblEventParticipationOptions {\n  /** Application data supplied directly or through a signal. */\n  readonly data: LineSeriesProps<D>[\"data\"];\n  /** Property key or callback extracting the horizontal coordinate. */\n  readonly x: LineAccessor<D>;\n  /** Property key or callback extracting the vertical coordinate. */\n  readonly y: LineAccessor<D>;\n  /** Continuous scale used to map horizontal data coordinates. */\n  readonly xScale: LineSeriesProps<D>[\"xScale\"];\n  /** Continuous scale used to map vertical data coordinates and baseline. */\n  readonly yScale: LineSeriesProps<D>[\"yScale\"];\n  /** Selects records that participate in an observed run. */\n  readonly defined?: LineSeriesProps<D>[\"defined\"];\n  /** Curve used to connect successive observed samples. */\n  readonly curve?: LineSeriesProps<D>[\"curve\"];\n  /** Finite data-space value to which each observed run closes. */\n  readonly baseline: SignalValue<number>;\n  /** Shared area presentation. Individual datum styling is not supported. */\n  readonly style?: SignalValue<SignalStyle<AreaSeriesStyle>>;\n}\n\nfunction accessor<D>(\n  input: LineAccessor<D>,\n): (datum: D, index: number, data: readonly D[]) => LineCoordinate {\n  return typeof input === \"function\"\n    ? input\n    : (datum) => datum[input] as LineCoordinate;\n}\n\nfunction fill(value: unknown): FillStyle {\n  if (\n    typeof value === \"string\" ||\n    value instanceof CanvasGradient ||\n    value instanceof CanvasPattern\n  )\n    return value;\n  try {\n    validateTexturePaint(value as never);\n    return value as FillStyle;\n  } catch {\n    throw new TypeError(\"AreaSeries: invalid fill.\");\n  }\n}\n\n/**\n * Draws each contiguous observed run as a filled polygon closed to an explicit baseline.\n *\n * Missing, non-finite, and excluded coordinates split runs. A lone observation has no area.\n * The component owns one ordinary {@link Path} target, so event participation follows the\n * standard Path defaults; callers may wrap it in `Clip` when clipping is needed.\n *\n * @param props - Data, coordinate accessors, continuous scales, baseline, and presentation.\n * @returns A Pibbl path node containing all drawable area runs.\n * @throws When `data` is not an array, the baseline is not finite, or presentation is invalid.\n *\n * @see {@link AreaSeriesProps}\n */\nexport function AreaSeries<D>({\n  data: dataInput,\n  x: xInput,\n  y: yInput,\n  xScale: xId,\n  yScale: yId,\n  baseline: baselineInput,\n  defined,\n  curve,\n  style: styleInput,\n  ...eventProps\n}: AreaSeriesProps<D>) {\n  const xScale = useNumericPosition(xId);\n  const yScale = useContinuousScale(yId).get();\n  const curveDefinition = resolveSeriesCurve(curve);\n  const x = useInternalValueMemoSlot(\n    \"vizAreaXAccessor\",\n    () => accessor(xInput),\n    [xInput],\n  );\n  const y = useInternalValueMemoSlot(\n    \"vizAreaYAccessor\",\n    () => accessor(yInput),\n    [yInput],\n  );\n  const data = resolveSignalValue(dataInput);\n  if (!Array.isArray(data))\n    throw new TypeError(\n      \"AreaSeries data must be an array or a signal containing an array.\",\n    );\n  const baseline = resolveSignalValue(baselineInput);\n  if (typeof baseline !== \"number\" || !Number.isFinite(baseline))\n    throw new RangeError(\"AreaSeries baseline must be finite.\");\n  const baselineY = yScale.map(baseline);\n  if (!Number.isFinite(baselineY))\n    throw new RangeError(\n      \"AreaSeries baseline must map to a finite coordinate.\",\n    );\n  const style = resolveSignalValue(styleInput) ?? {};\n  if (style === null || typeof style !== \"object\" || Array.isArray(style))\n    throw new TypeError(\"AreaSeries: style must be an object.\");\n  const areaFill = fill(resolveSignalValue(style.fill) ?? \"#2563eb\");\n  const alpha = opacity(resolveSignalValue(style.opacity) ?? 0.2, \"AreaSeries\");\n  const cursor = resolveSignalValue(style.cursor);\n  if (cursor !== undefined && typeof cursor !== \"string\")\n    throw new TypeError(\"AreaSeries: cursor must be a string.\");\n\n  const path = new Path2D();\n  let run: (readonly [number, number])[] = [];\n  const closeRun = () => {\n    if (run.length >= 2) {\n      const first = run[0];\n      const last = run[run.length - 1];\n      const geometry = curveGeometry(curveDefinition, run);\n      path.moveTo(geometry.start[0], geometry.start[1]);\n      appendCurveForward(path, geometry);\n      path.lineTo(last[0], baselineY);\n      path.lineTo(first[0], baselineY);\n      path.closePath();\n    }\n    run = [];\n  };\n  for (let i = 0; i < data.length; i++) {\n    const datum = data[i];\n    if (defined && !defined(datum, i, data)) {\n      closeRun();\n      continue;\n    }\n    const xv = x(datum, i, data);\n    const yv = y(datum, i, data);\n    if (\n      typeof xv !== \"number\" ||\n      typeof yv !== \"number\" ||\n      !Number.isFinite(xv) ||\n      !Number.isFinite(yv)\n    ) {\n      closeRun();\n      continue;\n    }\n    const point = [xScale.map(xv), yScale.map(yv)] as const;\n    if (!Number.isFinite(point[0]) || !Number.isFinite(point[1])) {\n      closeRun();\n      continue;\n    }\n    run.push(point);\n  }\n  closeRun();\n  return (\n    <Path\n      {...eventProps}\n      style={{ d: path, fill: areaFill, opacity: alpha, cursor }}\n    />\n  );\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/features/viz/lib/axis-labels.d.ts

@@ -0,0 +1,2 @@
+/** Fit text without changing its coordinate or the owning scale. */
+export declare function fitAxisLabel(context: Pick<CanvasRenderingContext2D, "measureText">, text: string, maxWidth: number, overflow: "allow" | "wrap" | "truncate", maxLines: number): readonly string[];

package/dist/features/viz/lib/axis-labels.js

@@ -0,0 +1,41 @@
+function fitAxisLabel(context, text, maxWidth, overflow, maxLines) {
+  if (overflow === "allow") return [text];
+  const graphemes = (value) => Array.from(new Intl.Segmenter(void 0, { granularity: "grapheme" }).segment(value), (part) => part.segment);
+  const truncate = (value, force = false) => {
+    if (!force && context.measureText(value).width <= maxWidth) return value;
+    if (context.measureText("\u2026").width > maxWidth) return "";
+    const parts = graphemes(value);
+    while (parts.length && context.measureText(parts.join("").trimEnd() + "\u2026").width > maxWidth) parts.pop();
+    return parts.join("").trimEnd() + "\u2026";
+  };
+  if (overflow === "truncate") return [truncate(text)];
+  const words = text.trim().split(/\s+/u);
+  const lines = [];
+  let line = "";
+  for (const word of words) {
+    const joined = line ? `${line} ${word}` : word;
+    if (context.measureText(joined).width <= maxWidth) {
+      line = joined;
+      continue;
+    }
+    if (line) {
+      lines.push(line);
+      line = "";
+    }
+    for (const part of graphemes(word)) {
+      if (line && context.measureText(line + part).width > maxWidth) {
+        lines.push(line);
+        line = "";
+      }
+      line += part;
+    }
+  }
+  if (line || !lines.length) lines.push(line);
+  const fitted = lines.slice(0, maxLines).map((value) => truncate(value));
+  if (lines.length > maxLines) fitted[maxLines - 1] = truncate(fitted[maxLines - 1], true);
+  return fitted;
+}
+export {
+  fitAxisLabel
+};
+//# sourceMappingURL=axis-labels.js.map

package/dist/features/viz/lib/axis-labels.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/viz/lib/axis-labels.ts"],
+  "sourcesContent": ["/** Fit text without changing its coordinate or the owning scale. */\nexport function fitAxisLabel(context: Pick<CanvasRenderingContext2D, \"measureText\">, text: string, maxWidth: number, overflow: \"allow\" | \"wrap\" | \"truncate\", maxLines: number): readonly string[] {\n  if (overflow === \"allow\") return [text];\n  const graphemes = (value: string) => Array.from(new Intl.Segmenter(undefined, { granularity: \"grapheme\" }).segment(value), part => part.segment);\n  const truncate = (value: string, force = false) => {\n    if (!force && context.measureText(value).width <= maxWidth) return value;\n    if (context.measureText(\"\u2026\").width > maxWidth) return \"\";\n    const parts = graphemes(value);\n    while (parts.length && context.measureText(parts.join(\"\").trimEnd() + \"\u2026\").width > maxWidth) parts.pop();\n    return parts.join(\"\").trimEnd() + \"\u2026\";\n  };\n  if (overflow === \"truncate\") return [truncate(text)];\n  const words = text.trim().split(/\\s+/u);\n  const lines: string[] = [];\n  let line = \"\";\n  for (const word of words) {\n    const joined = line ? `${line} ${word}` : word;\n    if (context.measureText(joined).width <= maxWidth) { line = joined; continue; }\n    if (line) { lines.push(line); line = \"\"; }\n    for (const part of graphemes(word)) {\n      if (line && context.measureText(line + part).width > maxWidth) { lines.push(line); line = \"\"; }\n      line += part;\n    }\n  }\n  if (line || !lines.length) lines.push(line);\n  const fitted = lines.slice(0, maxLines).map(value => truncate(value));\n  if (lines.length > maxLines) fitted[maxLines - 1] = truncate(fitted[maxLines - 1], true);\n  return fitted;\n}\n"],
+  "mappings": "AACO,SAAS,aAAa,SAAwD,MAAc,UAAkB,UAAyC,UAAqC;AACjM,MAAI,aAAa,QAAS,QAAO,CAAC,IAAI;AACtC,QAAM,YAAY,CAAC,UAAkB,MAAM,KAAK,IAAI,KAAK,UAAU,QAAW,EAAE,aAAa,WAAW,CAAC,EAAE,QAAQ,KAAK,GAAG,UAAQ,KAAK,OAAO;AAC/I,QAAM,WAAW,CAAC,OAAe,QAAQ,UAAU;AACjD,QAAI,CAAC,SAAS,QAAQ,YAAY,KAAK,EAAE,SAAS,SAAU,QAAO;AACnE,QAAI,QAAQ,YAAY,QAAG,EAAE,QAAQ,SAAU,QAAO;AACtD,UAAM,QAAQ,UAAU,KAAK;AAC7B,WAAO,MAAM,UAAU,QAAQ,YAAY,MAAM,KAAK,EAAE,EAAE,QAAQ,IAAI,QAAG,EAAE,QAAQ,SAAU,OAAM,IAAI;AACvG,WAAO,MAAM,KAAK,EAAE,EAAE,QAAQ,IAAI;AAAA,EACpC;AACA,MAAI,aAAa,WAAY,QAAO,CAAC,SAAS,IAAI,CAAC;AACnD,QAAM,QAAQ,KAAK,KAAK,EAAE,MAAM,MAAM;AACtC,QAAM,QAAkB,CAAC;AACzB,MAAI,OAAO;AACX,aAAW,QAAQ,OAAO;AACxB,UAAM,SAAS,OAAO,GAAG,IAAI,IAAI,IAAI,KAAK;AAC1C,QAAI,QAAQ,YAAY,MAAM,EAAE,SAAS,UAAU;AAAE,aAAO;AAAQ;AAAA,IAAU;AAC9E,QAAI,MAAM;AAAE,YAAM,KAAK,IAAI;AAAG,aAAO;AAAA,IAAI;AACzC,eAAW,QAAQ,UAAU,IAAI,GAAG;AAClC,UAAI,QAAQ,QAAQ,YAAY,OAAO,IAAI,EAAE,QAAQ,UAAU;AAAE,cAAM,KAAK,IAAI;AAAG,eAAO;AAAA,MAAI;AAC9F,cAAQ;AAAA,IACV;AAAA,EACF;AACA,MAAI,QAAQ,CAAC,MAAM,OAAQ,OAAM,KAAK,IAAI;AAC1C,QAAM,SAAS,MAAM,MAAM,GAAG,QAAQ,EAAE,IAAI,WAAS,SAAS,KAAK,CAAC;AACpE,MAAI,MAAM,SAAS,SAAU,QAAO,WAAW,CAAC,IAAI,SAAS,OAAO,WAAW,CAAC,GAAG,IAAI;AACvF,SAAO;AACT;",
+  "names": []
+}

package/dist/features/viz/lib/axis-title.d.ts

@@ -0,0 +1,23 @@
+import { type SignalValue } from "@pibbl/core";
+import type { SignalStyle } from "@pibbl/core/internal";
+import type { AxisProps, AxisStyle, ScaleId } from "./types.js";
+/** Scale-aligned axis text; callers reserve the margin outside the plot. See {@link AxisTitle}. */
+export interface AxisTitleProps {
+    /** Ancestor scale whose range supplies the title midpoint. */
+    readonly scale: ScaleId;
+    /** Plot edge; left/right titles rotate along the axis. */
+    readonly position: AxisProps["position"];
+    /** Single-line title. */
+    readonly label: SignalValue<string>;
+    /** Optional unit appended in parentheses; empty string omits it. */
+    readonly unit?: SignalValue<string>;
+    /** Nonnegative finite distance outside the plot edge, default 40 pixels. */
+    readonly offset?: SignalValue<number>;
+    /** Font defaults to 12px sans-serif, fill to #617783, opacity to 1. */
+    readonly style?: SignalValue<SignalStyle<Pick<AxisStyle, "font" | "fill" | "opacity">>>;
+}
+/** Paint an axis title with optional units, without allocating margins or changing ticks.
+ * @param props - Scale geometry and presentation. See {@link AxisTitleProps}.
+ * @returns Decorative chart content in the caller's coordinate space.
+ */
+export declare function AxisTitle(props: AxisTitleProps): import("../../../jsx-runtime.js").JSX.Element;

package/dist/features/viz/lib/axis-title.js

@@ -0,0 +1,23 @@
+import { jsx } from "@pibbl/core/jsx-runtime";
+import { Group, Text, resolveSignalValue } from "@pibbl/core";
+import { lookupScale } from "./scale-context.js";
+import { opacity } from "./paint.js";
+function AxisTitle(props) {
+  if (!["top", "bottom", "left", "right"].includes(props.position)) throw new TypeError("AxisTitle position must be top, bottom, left, or right.");
+  const source = lookupScale(props.scale, "AxisTitle");
+  if (!source) throw new TypeError("AxisTitle requires a scale ID.");
+  const scale = source.get(), label = resolveSignalValue(props.label), unit = resolveSignalValue(props.unit) ?? "";
+  if ([label, unit].some((value) => typeof value !== "string" || /[\r\n]/.test(value))) throw new TypeError("AxisTitle label and unit must be single-line strings.");
+  const offset = resolveSignalValue(props.offset) ?? 40;
+  if (typeof offset !== "number" || !Number.isFinite(offset) || offset < 0) throw new RangeError("AxisTitle offset must be finite and nonnegative.");
+  const horizontal = props.position === "top" || props.position === "bottom";
+  const midpoint = scale.range[0] / 2 + scale.range[1] / 2;
+  const x = horizontal ? midpoint : props.position === "left" ? -offset : scale.frame.width + offset;
+  const y = horizontal ? props.position === "top" ? -offset : scale.frame.height + offset : midpoint;
+  const style = resolveSignalValue(props.style) ?? {};
+  return /* @__PURE__ */ jsx(Group, { style: { translateX: x, translateY: y }, children: /* @__PURE__ */ jsx(Group, { style: { rotationDegrees: horizontal ? 0 : props.position === "left" ? -90 : 90 }, children: /* @__PURE__ */ jsx(Text, { pointerEvents: "none", style: { textAlign: "center", textBaseline: "middle", font: resolveSignalValue(style.font) ?? "12px sans-serif", fill: resolveSignalValue(style.fill) ?? "#617783", opacity: opacity(resolveSignalValue(style.opacity) ?? 1, "AxisTitle") }, children: unit ? `${label} (${unit})` : label }) }) });
+}
+export {
+  AxisTitle
+};
+//# sourceMappingURL=axis-title.js.map

package/dist/features/viz/lib/axis-title.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/viz/lib/axis-title.tsx"],
+  "sourcesContent": ["import { Group, Text, resolveSignalValue, type SignalValue } from \"@pibbl/core\";\nimport type { SignalStyle } from \"@pibbl/core/internal\";\nimport type { AxisProps, AxisStyle, ScaleId } from \"./types.js\";\nimport { lookupScale } from \"./scale-context.js\";\nimport { opacity } from \"./paint.js\";\n/** Scale-aligned axis text; callers reserve the margin outside the plot. See {@link AxisTitle}. */\nexport interface AxisTitleProps {\n  /** Ancestor scale whose range supplies the title midpoint. */\n  readonly scale: ScaleId;\n  /** Plot edge; left/right titles rotate along the axis. */\n  readonly position: AxisProps[\"position\"];\n  /** Single-line title. */\n  readonly label: SignalValue<string>;\n  /** Optional unit appended in parentheses; empty string omits it. */\n  readonly unit?: SignalValue<string>;\n  /** Nonnegative finite distance outside the plot edge, default 40 pixels. */\n  readonly offset?: SignalValue<number>;\n  /** Font defaults to 12px sans-serif, fill to #617783, opacity to 1. */\n  readonly style?: SignalValue<SignalStyle<Pick<AxisStyle, \"font\" | \"fill\" | \"opacity\">>>;\n}\n/** Paint an axis title with optional units, without allocating margins or changing ticks.\n * @param props - Scale geometry and presentation. See {@link AxisTitleProps}.\n * @returns Decorative chart content in the caller's coordinate space.\n */\nexport function AxisTitle(props: AxisTitleProps) {\n  if (![\"top\", \"bottom\", \"left\", \"right\"].includes(props.position)) throw new TypeError(\"AxisTitle position must be top, bottom, left, or right.\");\n  const source = lookupScale(props.scale, \"AxisTitle\");\n  if (!source) throw new TypeError(\"AxisTitle requires a scale ID.\");\n  const scale = source.get(), label = resolveSignalValue(props.label), unit = resolveSignalValue(props.unit) ?? \"\";\n  if ([label, unit].some(value => typeof value !== \"string\" || /[\\r\\n]/.test(value))) throw new TypeError(\"AxisTitle label and unit must be single-line strings.\");\n  const offset = resolveSignalValue(props.offset) ?? 40;\n  if (typeof offset !== \"number\" || !Number.isFinite(offset) || offset < 0) throw new RangeError(\"AxisTitle offset must be finite and nonnegative.\");\n  const horizontal = props.position === \"top\" || props.position === \"bottom\";\n  const midpoint = scale.range[0] / 2 + scale.range[1] / 2;\n  const x = horizontal ? midpoint : props.position === \"left\" ? -offset : scale.frame.width + offset;\n  const y = horizontal ? props.position === \"top\" ? -offset : scale.frame.height + offset : midpoint;\n  const style = resolveSignalValue(props.style) ?? {};\n  return <Group style={{ translateX: x, translateY: y }}><Group style={{ rotationDegrees: horizontal ? 0 : props.position === \"left\" ? -90 : 90 }}>\n    <Text pointerEvents=\"none\" style={{ textAlign: \"center\", textBaseline: \"middle\", font: resolveSignalValue(style.font) ?? \"12px sans-serif\", fill: resolveSignalValue(style.fill) ?? \"#617783\", opacity: opacity(resolveSignalValue(style.opacity) ?? 1, \"AxisTitle\") }}>{unit ? `${label} (${unit})` : label}</Text>\n  </Group></Group>;\n}\n"],
+  "mappings": "AAsCI;AAtCJ,SAAS,OAAO,MAAM,0BAA4C;AAGlE,SAAS,mBAAmB;AAC5B,SAAS,eAAe;AAoBjB,SAAS,UAAU,OAAuB;AAC/C,MAAI,CAAC,CAAC,OAAO,UAAU,QAAQ,OAAO,EAAE,SAAS,MAAM,QAAQ,EAAG,OAAM,IAAI,UAAU,yDAAyD;AAC/I,QAAM,SAAS,YAAY,MAAM,OAAO,WAAW;AACnD,MAAI,CAAC,OAAQ,OAAM,IAAI,UAAU,gCAAgC;AACjE,QAAM,QAAQ,OAAO,IAAI,GAAG,QAAQ,mBAAmB,MAAM,KAAK,GAAG,OAAO,mBAAmB,MAAM,IAAI,KAAK;AAC9G,MAAI,CAAC,OAAO,IAAI,EAAE,KAAK,WAAS,OAAO,UAAU,YAAY,SAAS,KAAK,KAAK,CAAC,EAAG,OAAM,IAAI,UAAU,uDAAuD;AAC/J,QAAM,SAAS,mBAAmB,MAAM,MAAM,KAAK;AACnD,MAAI,OAAO,WAAW,YAAY,CAAC,OAAO,SAAS,MAAM,KAAK,SAAS,EAAG,OAAM,IAAI,WAAW,kDAAkD;AACjJ,QAAM,aAAa,MAAM,aAAa,SAAS,MAAM,aAAa;AAClE,QAAM,WAAW,MAAM,MAAM,CAAC,IAAI,IAAI,MAAM,MAAM,CAAC,IAAI;AACvD,QAAM,IAAI,aAAa,WAAW,MAAM,aAAa,SAAS,CAAC,SAAS,MAAM,MAAM,QAAQ;AAC5F,QAAM,IAAI,aAAa,MAAM,aAAa,QAAQ,CAAC,SAAS,MAAM,MAAM,SAAS,SAAS;AAC1F,QAAM,QAAQ,mBAAmB,MAAM,KAAK,KAAK,CAAC;AAClD,SAAO,oBAAC,SAAM,OAAO,EAAE,YAAY,GAAG,YAAY,EAAE,GAAG,8BAAC,SAAM,OAAO,EAAE,iBAAiB,aAAa,IAAI,MAAM,aAAa,SAAS,MAAM,GAAG,GAC5I,8BAAC,QAAK,eAAc,QAAO,OAAO,EAAE,WAAW,UAAU,cAAc,UAAU,MAAM,mBAAmB,MAAM,IAAI,KAAK,mBAAmB,MAAM,mBAAmB,MAAM,IAAI,KAAK,WAAW,SAAS,QAAQ,mBAAmB,MAAM,OAAO,KAAK,GAAG,WAAW,EAAE,GAAI,iBAAO,GAAG,KAAK,KAAK,IAAI,MAAM,OAAM,GAC/S,GAAQ;AACV;",
+  "names": []
+}

package/dist/features/viz/lib/axis.d.ts

@@ -7,4 +7,4 @@ import type { AxisProps } from "./types.js";
  *
  * @see {@link AxisProps}
  */
-export declare function Axis(props: AxisProps): (import("../../../jsx-runtime.js").JSX.Element[] | import("../../../jsx-runtime.js").JSX.Element)[];
+export declare function Axis(props: AxisProps): ((import("../../../jsx-runtime.js").JSX.Element[] | null)[] | import("../../../jsx-runtime.js").JSX.Element)[];