@pibbl/core 0.0.1 → 0.0.3-alpha.109.1

package/dist/features/viz/lib/trading-time-scale.d.ts

@@ -0,0 +1,83 @@
+import { type SignalValue, type PibblNode, type Signal } from "@pibbl/core";
+import type { ScaleId, ScaleRange, ScaleLayoutStyle } from "./types.js";
+import type { SignalStyle } from "@pibbl/core/internal";
+/** Controlled gapless observation slots; UTCScale retains elapsed-time semantics.
+ * @see {@link TradingTimeScale}
+ */
+export interface TradingTimeScaleProps {
+    /** Ancestor scale identity. */ readonly id: ScaleId;
+    /** Strictly increasing, unique UTC-millisecond observations; copied by the mapping. */ readonly timestamps: SignalValue<readonly number[]>;
+    /** Visible logical slot endpoints, possibly fractional/reversed; default covers supplied slots. */ readonly logicalRange?: SignalValue<readonly [number, number]>;
+    /** Output in local logical units or the receiving allocation's width/height. */ readonly range: SignalValue<ScaleRange>;
+    /** Reverses physical output without reordering supplied observations. */ readonly reverse?: SignalValue<boolean>;
+    /** Receiving scale frame allocation and layout participation. */ readonly style?: SignalValue<SignalStyle<ScaleLayoutStyle>>;
+    /** Descendant visualization composition. */ readonly children?: PibblNode;
+}
+/** Dedicated exact-time/slot mapping; no interpolated UTC timestamps are fabricated.
+ * @see {@link TradingTimeScale}
+ */
+export interface ResolvedTradingTimeScale {
+    /** Describes this resolved mapping. */ readonly type: "trading-time";
+    /** Owned supplied timestamps in ascending order, also used as the data domain. */ readonly timestamps: readonly number[];
+    /** Owned supplied timestamp domain, not logical slot endpoints. */ readonly domain: readonly number[];
+    /** Controlled viewport endpoints in logical slot units. */ readonly logicalRange: readonly [
+        number,
+        number
+    ];
+    /** Output local-logical endpoints. */ readonly range: readonly [
+        number,
+        number
+    ];
+    /** Receiving allocation in local logical units. */ readonly frame: Readonly<{
+        /** Local allocation x. */ x: number;
+        /** Local allocation y. */ y: number;
+        /** Local width. */ width: number;
+        /** Local height. */ height: number;
+    }>;
+    /** Maps an exact supplied UTC timestamp; unknown timestamps throw.
+     * @param time - Supplied UTC milliseconds.
+     * @returns Series-local coordinate.
+     */ map(time: number): number;
+    /** Maps a possibly fractional logical slot, including viewport whitespace.
+     * @param slot - Logical observation slot.
+     * @returns Series-local coordinate.
+     */ mapSlot(slot: number): number;
+    /** Exact timestamp lookup.
+     * @param time - UTC milliseconds.
+     * @returns Supplied slot index, or undefined.
+     */ slotAtTime(time: number): number | undefined;
+    /** Exact integer slot lookup.
+     * @param slot - Integer logical observation slot.
+     * @returns Supplied timestamp, or undefined.
+     */ timeAtSlot(slot: number): number | undefined;
+    /** Inverts local geometry to fractional slots.
+     * @param position - Series-local logical coordinate.
+     * @returns Fractional logical slot.
+     */ slotAtPosition(position: number): number;
+    /** Selects a supplied timestamp; ties choose earlier, outside positions clamp.
+     * @param position - Series-local logical coordinate.
+     * @returns Supplied UTC milliseconds, or undefined for empty input.
+     */ nearestTimeAtPosition(position: number): number | undefined;
+    /** Chooses at most count visible supplied observations as date ticks.
+     * @param count - Integer maximum from zero through 100, default five.
+     * @returns Original UTC timestamps in physical axis order.
+     */ ticks(count?: number): readonly number[];
+    /** Formats supplied or finite valid UTC timestamps without inferring sessions.
+     * @param time - UTC milliseconds in Date range.
+     * @returns ISO UTC timestamp.
+     */ formatTick(time: number): string;
+}
+/**
+ * Reads a stable dedicated ancestor trading-time signal.
+ * @param id - Ancestor TradingTimeScale identity.
+ * @returns Readonly mapping with explicit timestamp and logical-slot operations.
+ * @see {@link TradingTimeScale}
+ */
+export declare function useTradingTimeScale(id: ScaleId): Signal<ResolvedTradingTimeScale>;
+/**
+ * Provides gapless positions for ordered supplied observations, leaving application-owned viewport control explicit.
+ * @param props - Timestamps, optional logical viewport, output range and children.
+ * @returns Descendant composition in the named mapping scope.
+ * @see {@link TradingTimeScaleProps}
+ */
+export declare function TradingTimeScale(props: TradingTimeScaleProps): PibblNode;

package/dist/features/viz/lib/trading-time-scale.js

@@ -0,0 +1,96 @@
+import {
+  resolveSignalValue,
+  useLayoutBox
+} from "@pibbl/core";
+import { createTradingTimeMapping } from "./trading-time-mapping.js";
+import { resolveLinearScale } from "./linear-scale.js";
+import { useScaleProvider } from "./scale-provider.js";
+import { scaleView } from "./scale-view.js";
+const views = /* @__PURE__ */ new WeakMap();
+function useTradingTimeScale(id) {
+  return scaleView(
+    views,
+    id,
+    "useTradingTimeScale",
+    (kind) => kind === "trading-time"
+  );
+}
+function TradingTimeScale(props) {
+  const { width, height } = useLayoutBox();
+  useScaleProvider(
+    props.id,
+    "trading-time",
+    () => {
+      const timestamps = Object.freeze([
+        ...resolveSignalValue(props.timestamps)
+      ]);
+      const logicalRange = Object.freeze([
+        ...props.logicalRange ? resolveSignalValue(props.logicalRange) : [-0.5, Math.max(0.5, timestamps.length - 0.5)]
+      ]);
+      const linear = resolveLinearScale(
+        logicalRange,
+        resolveSignalValue(props.range),
+        resolveSignalValue(props.reverse ?? false),
+        width,
+        height
+      );
+      const mapping = createTradingTimeMapping({
+        timestamps,
+        logicalRange,
+        range: linear.range
+      });
+      return Object.freeze({
+        type: "trading-time",
+        timestamps,
+        domain: timestamps,
+        logicalRange,
+        range: linear.range,
+        frame: linear.frame,
+        map: mapping.mapTime,
+        mapSlot: linear.map,
+        slotAtTime: mapping.slotAtTime,
+        timeAtSlot: mapping.timeAtSlot,
+        slotAtPosition: mapping.slotAtPosition,
+        nearestTimeAtPosition: mapping.nearestTimeAtPosition,
+        ticks(count = 5) {
+          if (!Number.isInteger(count) || count < 0 || count > 100)
+            throw new RangeError(
+              "TradingTime ticks count must be an integer 0\u2013100."
+            );
+          const lo = Math.max(0, Math.ceil(Math.min(...logicalRange))), hi = Math.min(
+            timestamps.length - 1,
+            Math.floor(Math.max(...logicalRange))
+          ), n = Math.max(0, hi - lo + 1), m = Math.min(n, count);
+          const result = Array.from(
+            { length: m },
+            (_, i) => timestamps[lo + (m === 1 ? 0 : Math.round(i * (n - 1) / (m - 1)))]
+          );
+          return Object.freeze(
+            logicalRange[0] > logicalRange[1] ? result.reverse() : result
+          );
+        },
+        formatTick(time) {
+          if (!Number.isFinite(time) || Math.abs(time) > 864e13)
+            throw new RangeError(
+              "TradingTime format requires UTC milliseconds within Date range."
+            );
+          return new Date(time).toISOString();
+        }
+      });
+    },
+    [
+      props.timestamps,
+      props.logicalRange,
+      props.range,
+      props.reverse,
+      width,
+      height
+    ]
+  );
+  return props.children;
+}
+export {
+  TradingTimeScale,
+  useTradingTimeScale
+};
+//# sourceMappingURL=trading-time-scale.js.map

package/dist/features/viz/lib/trading-time-scale.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/viz/lib/trading-time-scale.ts"],
+  "sourcesContent": ["import {\n  resolveSignalValue,\n  useLayoutBox,\n  type SignalValue,\n  type PibblNode,\n  type Signal,\n} from \"@pibbl/core\";\nimport type {\n  ScaleId,\n  ScaleRange,\n  ScaleLayoutStyle,\n  ResolvedScale,\n} from \"./types.js\";\nimport type { SignalStyle } from \"@pibbl/core/internal\";\nimport { createTradingTimeMapping } from \"./trading-time-mapping.js\";\nimport { resolveLinearScale } from \"./linear-scale.js\";\nimport { useScaleProvider } from \"./scale-provider.js\";\nimport { scaleView } from \"./scale-view.js\";\n\n/** Controlled gapless observation slots; UTCScale retains elapsed-time semantics.\n * @see {@link TradingTimeScale}\n */\nexport interface TradingTimeScaleProps {\n  /** Ancestor scale identity. */ readonly id: ScaleId;\n  /** Strictly increasing, unique UTC-millisecond observations; copied by the mapping. */ readonly timestamps: SignalValue<\n    readonly number[]\n  >;\n  /** Visible logical slot endpoints, possibly fractional/reversed; default covers supplied slots. */ readonly logicalRange?: SignalValue<\n    readonly [number, number]\n  >;\n  /** Output in local logical units or the receiving allocation's width/height. */ readonly range: SignalValue<ScaleRange>;\n  /** Reverses physical output without reordering supplied observations. */ readonly reverse?: SignalValue<boolean>;\n  /** Receiving scale frame allocation and layout participation. */ readonly style?: SignalValue<\n    SignalStyle<ScaleLayoutStyle>\n  >;\n  /** Descendant visualization composition. */ readonly children?: PibblNode;\n}\n/** Dedicated exact-time/slot mapping; no interpolated UTC timestamps are fabricated.\n * @see {@link TradingTimeScale}\n */\nexport interface ResolvedTradingTimeScale {\n  /** Describes this resolved mapping. */ readonly type: \"trading-time\";\n  /** Owned supplied timestamps in ascending order, also used as the data domain. */ readonly timestamps: readonly number[];\n  /** Owned supplied timestamp domain, not logical slot endpoints. */ readonly domain: readonly number[];\n  /** Controlled viewport endpoints in logical slot units. */ readonly logicalRange: readonly [\n    number,\n    number,\n  ];\n  /** Output local-logical endpoints. */ readonly range: readonly [\n    number,\n    number,\n  ];\n  /** Receiving allocation in local logical units. */ readonly frame: Readonly<{\n    /** Local allocation x. */ x: number;\n    /** Local allocation y. */ y: number;\n    /** Local width. */ width: number;\n    /** Local height. */ height: number;\n  }>;\n  /** Maps an exact supplied UTC timestamp; unknown timestamps throw.\n   * @param time - Supplied UTC milliseconds.\n   * @returns Series-local coordinate.\n   */ map(time: number): number;\n  /** Maps a possibly fractional logical slot, including viewport whitespace.\n   * @param slot - Logical observation slot.\n   * @returns Series-local coordinate.\n   */ mapSlot(slot: number): number;\n  /** Exact timestamp lookup.\n   * @param time - UTC milliseconds.\n   * @returns Supplied slot index, or undefined.\n   */ slotAtTime(time: number): number | undefined;\n  /** Exact integer slot lookup.\n   * @param slot - Integer logical observation slot.\n   * @returns Supplied timestamp, or undefined.\n   */ timeAtSlot(slot: number): number | undefined;\n  /** Inverts local geometry to fractional slots.\n   * @param position - Series-local logical coordinate.\n   * @returns Fractional logical slot.\n   */ slotAtPosition(position: number): number;\n  /** Selects a supplied timestamp; ties choose earlier, outside positions clamp.\n   * @param position - Series-local logical coordinate.\n   * @returns Supplied UTC milliseconds, or undefined for empty input.\n   */ nearestTimeAtPosition(position: number): number | undefined;\n  /** Chooses at most count visible supplied observations as date ticks.\n   * @param count - Integer maximum from zero through 100, default five.\n   * @returns Original UTC timestamps in physical axis order.\n   */ ticks(count?: number): readonly number[];\n  /** Formats supplied or finite valid UTC timestamps without inferring sessions.\n   * @param time - UTC milliseconds in Date range.\n   * @returns ISO UTC timestamp.\n   */ formatTick(time: number): string;\n}\nconst views = new WeakMap<\n  Signal<ResolvedScale>,\n  Signal<ResolvedTradingTimeScale>\n>();\n/**\n * Reads a stable dedicated ancestor trading-time signal.\n * @param id - Ancestor TradingTimeScale identity.\n * @returns Readonly mapping with explicit timestamp and logical-slot operations.\n * @see {@link TradingTimeScale}\n */\nexport function useTradingTimeScale(\n  id: ScaleId,\n): Signal<ResolvedTradingTimeScale> {\n  return scaleView(\n    views,\n    id,\n    \"useTradingTimeScale\",\n    (kind) => kind === \"trading-time\",\n  );\n}\n/**\n * Provides gapless positions for ordered supplied observations, leaving application-owned viewport control explicit.\n * @param props - Timestamps, optional logical viewport, output range and children.\n * @returns Descendant composition in the named mapping scope.\n * @see {@link TradingTimeScaleProps}\n */\nexport function TradingTimeScale(props: TradingTimeScaleProps): PibblNode {\n  const { width, height } = useLayoutBox();\n  useScaleProvider(\n    props.id,\n    \"trading-time\",\n    () => {\n      const timestamps = Object.freeze([\n        ...resolveSignalValue(props.timestamps),\n      ]);\n      const logicalRange = Object.freeze([\n        ...(props.logicalRange\n          ? resolveSignalValue(props.logicalRange)\n          : [-0.5, Math.max(0.5, timestamps.length - 0.5)]),\n      ]) as readonly [number, number];\n      const linear = resolveLinearScale(\n        logicalRange,\n        resolveSignalValue(props.range),\n        resolveSignalValue(props.reverse ?? false),\n        width,\n        height,\n      );\n      const mapping = createTradingTimeMapping({\n        timestamps,\n        logicalRange,\n        range: linear.range,\n      });\n      return Object.freeze({\n        type: \"trading-time\" as const,\n        timestamps,\n        domain: timestamps,\n        logicalRange,\n        range: linear.range,\n        frame: linear.frame,\n        map: mapping.mapTime,\n        mapSlot: linear.map,\n        slotAtTime: mapping.slotAtTime,\n        timeAtSlot: mapping.timeAtSlot,\n        slotAtPosition: mapping.slotAtPosition,\n        nearestTimeAtPosition: mapping.nearestTimeAtPosition,\n        ticks(count = 5) {\n          if (!Number.isInteger(count) || count < 0 || count > 100)\n            throw new RangeError(\n              \"TradingTime ticks count must be an integer 0\u2013100.\",\n            );\n          const lo = Math.max(0, Math.ceil(Math.min(...logicalRange))),\n            hi = Math.min(\n              timestamps.length - 1,\n              Math.floor(Math.max(...logicalRange)),\n            ),\n            n = Math.max(0, hi - lo + 1),\n            m = Math.min(n, count);\n          const result = Array.from(\n            { length: m },\n            (_, i) =>\n              timestamps[\n                lo + (m === 1 ? 0 : Math.round((i * (n - 1)) / (m - 1)))\n              ]!,\n          );\n          return Object.freeze(\n            logicalRange[0] > logicalRange[1] ? result.reverse() : result,\n          );\n        },\n        formatTick(time: number) {\n          if (!Number.isFinite(time) || Math.abs(time) > 8_640_000_000_000_000)\n            throw new RangeError(\n              \"TradingTime format requires UTC milliseconds within Date range.\",\n            );\n          return new Date(time).toISOString();\n        },\n      });\n    },\n    [\n      props.timestamps,\n      props.logicalRange,\n      props.range,\n      props.reverse,\n      width,\n      height,\n    ],\n  );\n  return props.children;\n}\n"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,OAIK;AAQP,SAAS,gCAAgC;AACzC,SAAS,0BAA0B;AACnC,SAAS,wBAAwB;AACjC,SAAS,iBAAiB;AA0E1B,MAAM,QAAQ,oBAAI,QAGhB;AAOK,SAAS,oBACd,IACkC;AAClC,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA,CAAC,SAAS,SAAS;AAAA,EACrB;AACF;AAOO,SAAS,iBAAiB,OAAyC;AACxE,QAAM,EAAE,OAAO,OAAO,IAAI,aAAa;AACvC;AAAA,IACE,MAAM;AAAA,IACN;AAAA,IACA,MAAM;AACJ,YAAM,aAAa,OAAO,OAAO;AAAA,QAC/B,GAAG,mBAAmB,MAAM,UAAU;AAAA,MACxC,CAAC;AACD,YAAM,eAAe,OAAO,OAAO;AAAA,QACjC,GAAI,MAAM,eACN,mBAAmB,MAAM,YAAY,IACrC,CAAC,MAAM,KAAK,IAAI,KAAK,WAAW,SAAS,GAAG,CAAC;AAAA,MACnD,CAAC;AACD,YAAM,SAAS;AAAA,QACb;AAAA,QACA,mBAAmB,MAAM,KAAK;AAAA,QAC9B,mBAAmB,MAAM,WAAW,KAAK;AAAA,QACzC;AAAA,QACA;AAAA,MACF;AACA,YAAM,UAAU,yBAAyB;AAAA,QACvC;AAAA,QACA;AAAA,QACA,OAAO,OAAO;AAAA,MAChB,CAAC;AACD,aAAO,OAAO,OAAO;AAAA,QACnB,MAAM;AAAA,QACN;AAAA,QACA,QAAQ;AAAA,QACR;AAAA,QACA,OAAO,OAAO;AAAA,QACd,OAAO,OAAO;AAAA,QACd,KAAK,QAAQ;AAAA,QACb,SAAS,OAAO;AAAA,QAChB,YAAY,QAAQ;AAAA,QACpB,YAAY,QAAQ;AAAA,QACpB,gBAAgB,QAAQ;AAAA,QACxB,uBAAuB,QAAQ;AAAA,QAC/B,MAAM,QAAQ,GAAG;AACf,cAAI,CAAC,OAAO,UAAU,KAAK,KAAK,QAAQ,KAAK,QAAQ;AACnD,kBAAM,IAAI;AAAA,cACR;AAAA,YACF;AACF,gBAAM,KAAK,KAAK,IAAI,GAAG,KAAK,KAAK,KAAK,IAAI,GAAG,YAAY,CAAC,CAAC,GACzD,KAAK,KAAK;AAAA,YACR,WAAW,SAAS;AAAA,YACpB,KAAK,MAAM,KAAK,IAAI,GAAG,YAAY,CAAC;AAAA,UACtC,GACA,IAAI,KAAK,IAAI,GAAG,KAAK,KAAK,CAAC,GAC3B,IAAI,KAAK,IAAI,GAAG,KAAK;AACvB,gBAAM,SAAS,MAAM;AAAA,YACnB,EAAE,QAAQ,EAAE;AAAA,YACZ,CAAC,GAAG,MACF,WACE,MAAM,MAAM,IAAI,IAAI,KAAK,MAAO,KAAK,IAAI,MAAO,IAAI,EAAE,EACxD;AAAA,UACJ;AACA,iBAAO,OAAO;AAAA,YACZ,aAAa,CAAC,IAAI,aAAa,CAAC,IAAI,OAAO,QAAQ,IAAI;AAAA,UACzD;AAAA,QACF;AAAA,QACA,WAAW,MAAc;AACvB,cAAI,CAAC,OAAO,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,IAAI;AAC7C,kBAAM,IAAI;AAAA,cACR;AAAA,YACF;AACF,iBAAO,IAAI,KAAK,IAAI,EAAE,YAAY;AAAA,QACpC;AAAA,MACF,CAAC;AAAA,IACH;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,MAAM;AAAA,MACN,MAAM;AAAA,MACN,MAAM;AAAA,MACN;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACA,SAAO,MAAM;AACf;",
+  "names": []
+}

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

@@ -0,0 +1,71 @@
+import type { PibblEventHandlers, PibblEventParticipationOptions, SignalValue, StrokeStyle } from "@pibbl/core";
+import type { SignalStyle } from "@pibbl/core/internal";
+import type { LineAccessor, ScaleId, SeriesAccessor } from "./types.js";
+/** Shared path appearance for {@link TrajectorySeries}. */
+export interface TrajectorySeriesStyle {
+    /** Path paint. Defaults to `#2563eb`. */
+    readonly stroke?: StrokeStyle;
+    /** Visible path width in local units. Defaults to 2. */
+    readonly strokeWidth?: number;
+    /** Pointer targeting width. Defaults to `strokeWidth`. */
+    readonly lineInteractionWidth?: number;
+    /** Path opacity in [0, 1]. Defaults to 1. */
+    readonly opacity?: number;
+    /** Cursor while the batched path owns pointer presentation. */
+    readonly cursor?: string;
+}
+/**
+ * A participant or specimen identity property or callback.
+ *
+ * Nullish identities deliberately omit a row. Numeric identities must be finite.
+ * @param datum - Source observation.
+ * @param index - Zero-based source index.
+ * @param data - Complete source data array.
+ * @returns A finite numeric or string identity, or a nullish omitted identity.
+ * @see {@link TrajectorySeriesProps}
+ */
+export type TrajectoryGroupAccessor<D> = {
+    [K in keyof D]-?: D[K] extends string | number | null | undefined ? K : never;
+}[keyof D] | ((datum: D, index: number, data: readonly D[]) => string | number | null | undefined);
+/**
+ * Authoring inputs for {@link TrajectorySeries}.
+ *
+ * Rows are connected in source encounter order within each group. The component
+ * neither sorts time values nor invents visits, summaries, or missing values.
+ */
+export interface TrajectorySeriesProps<D> extends PibblEventHandlers, PibblEventParticipationOptions {
+    /** Source observations or a signal containing them. */
+    readonly data: SignalValue<readonly D[]>;
+    /** Stable participant or specimen identity. Nullish identities omit that row. */
+    readonly group: TrajectoryGroupAccessor<D>;
+    /** Encounter-time or scheduled-visit coordinate. */
+    readonly x: SeriesAccessor<D>;
+    /** Numeric observed outcome coordinate. */
+    readonly y: LineAccessor<D>;
+    /** Scale mapping encounter-time or visit coordinates. */
+    readonly xScale: ScaleId;
+    /** Numeric scale mapping outcomes. */
+    readonly yScale: ScaleId;
+    /**
+     * Ends that group's current run without reading coordinate accessors.
+     * @param datum - Candidate source datum.
+     * @param index - Zero-based source index.
+     * @param data - Complete source data array.
+     * @returns Whether this datum contributes a coordinate to its group.
+     */
+    readonly defined?: (datum: D, index: number, data: readonly D[]) => boolean;
+    /** Shared path style, including whole-object and shallow field signals. */
+    readonly style?: SignalValue<SignalStyle<TrajectorySeriesStyle>>;
+}
+/**
+ * Draws one shared-style path connecting each participant or specimen trajectory.
+ *
+ * A missing, excluded, or non-finite coordinate ends only that group's current
+ * run. Interleaved groups retain their source encounter order; trajectories are
+ * never sorted by either actual or scheduled time.
+ *
+ * @param props - Observations, identities, coordinates, scales, and shared path paint.
+ * @returns One batched ordinary Pibbl path containing source-ordered trajectory segments.
+ * @see {@link TrajectorySeriesProps}
+ */
+export declare function TrajectorySeries<D>({ data: input, group: groupInput, x: xInput, y: yInput, xScale: xId, yScale: yId, defined, style: styleInput, ...events }: TrajectorySeriesProps<D>): import("../../../jsx-runtime.js").JSX.Element;

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

@@ -0,0 +1,111 @@
+import { jsx } from "@pibbl/core/jsx-runtime";
+import { Path, resolveSignalValue } from "@pibbl/core";
+import { withHooksForbidden } from "@pibbl/core/internal";
+import { opacity, width } from "./paint.js";
+import { pointAccessor, pointData } from "./point-data.js";
+import {
+  mapSeriesPosition,
+  seriesAccessor,
+  useNumericPosition,
+  useSeriesPosition
+} from "./series-position.js";
+function style(input) {
+  if (input === null || typeof input !== "object" || Array.isArray(input))
+    throw new TypeError("TrajectorySeries: style must be an object.");
+  const value = input;
+  for (const field of Object.keys(value))
+    if (![
+      "stroke",
+      "strokeWidth",
+      "lineInteractionWidth",
+      "opacity",
+      "cursor"
+    ].includes(field))
+      throw new TypeError(
+        `TrajectorySeries: unsupported style field ${field}.`
+      );
+  const stroke = resolveSignalValue(value.stroke) ?? "#2563eb";
+  const strokeWidth = width(
+    resolveSignalValue(value.strokeWidth) ?? 2,
+    "TrajectorySeries strokeWidth"
+  );
+  const lineInteractionWidth = width(
+    resolveSignalValue(value.lineInteractionWidth) ?? strokeWidth,
+    "TrajectorySeries lineInteractionWidth"
+  );
+  const cursor = resolveSignalValue(value.cursor);
+  if (cursor !== void 0 && typeof cursor !== "string")
+    throw new TypeError("TrajectorySeries: cursor must be a string.");
+  return {
+    stroke,
+    strokeWidth,
+    lineInteractionWidth,
+    opacity: opacity(
+      resolveSignalValue(value.opacity) ?? 1,
+      "TrajectorySeries opacity"
+    ),
+    cursor
+  };
+}
+function TrajectorySeries({
+  data: input,
+  group: groupInput,
+  x: xInput,
+  y: yInput,
+  xScale: xId,
+  yScale: yId,
+  defined,
+  style: styleInput,
+  ...events
+}) {
+  const xs = useSeriesPosition(xId);
+  const ys = useNumericPosition(yId);
+  const data = pointData(resolveSignalValue(input), "TrajectorySeries");
+  const x = seriesAccessor(xInput);
+  const y = pointAccessor(yInput);
+  const group = typeof groupInput === "function" ? groupInput : (datum) => datum[groupInput];
+  const resolved = style(resolveSignalValue(styleInput) ?? {});
+  const last = /* @__PURE__ */ new Map();
+  const path = new Path2D();
+  for (let i = 0; i < data.length; i++) {
+    const datum = data[i];
+    const row = withHooksForbidden(
+      "TrajectorySeries: accessors cannot call hooks.",
+      () => {
+        const identity = group(datum, i, data);
+        if (defined && !defined(datum, i, data)) return { group: identity };
+        return {
+          group: identity,
+          x: x(datum, i, data),
+          y: y(datum, i, data)
+        };
+      }
+    );
+    if (!row || row.group == null) continue;
+    if (typeof row.group !== "string" && typeof row.group !== "number" || typeof row.group === "number" && !Number.isFinite(row.group))
+      throw new TypeError(
+        "TrajectorySeries: group must be a string or number."
+      );
+    if (!("x" in row) || !("y" in row)) {
+      last.delete(row.group);
+      continue;
+    }
+    const px = mapSeriesPosition(xs, row.x);
+    const py = mapSeriesPosition(ys, row.y);
+    if (px === void 0 || py === void 0) {
+      last.delete(row.group);
+      continue;
+    }
+    const prior = last.get(row.group);
+    if (prior) {
+      path.moveTo(prior[0], prior[1]);
+      path.lineTo(px, py);
+    }
+    last.set(row.group, [px, py]);
+  }
+  return /* @__PURE__ */ jsx(Path, { ...events, style: { d: path, ...resolved } });
+}
+export {
+  TrajectorySeries
+};
+//# sourceMappingURL=trajectory-series.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/viz/lib/trajectory-series.tsx"],
+  "sourcesContent": ["import { Path, resolveSignalValue } from \"@pibbl/core\";\nimport type {\n  PibblEventHandlers,\n  PibblEventParticipationOptions,\n  SignalValue,\n  StrokeStyle,\n} from \"@pibbl/core\";\nimport { withHooksForbidden } from \"@pibbl/core/internal\";\nimport type { SignalStyle } from \"@pibbl/core/internal\";\nimport type { LineAccessor, ScaleId, SeriesAccessor } from \"./types.js\";\nimport { opacity, width } from \"./paint.js\";\nimport { pointAccessor, pointData } from \"./point-data.js\";\nimport {\n  mapSeriesPosition,\n  seriesAccessor,\n  useNumericPosition,\n  useSeriesPosition,\n} from \"./series-position.js\";\n\n/** Shared path appearance for {@link TrajectorySeries}. */\nexport interface TrajectorySeriesStyle {\n  /** Path paint. Defaults to `#2563eb`. */\n  readonly stroke?: StrokeStyle;\n  /** Visible path width in local units. Defaults to 2. */\n  readonly strokeWidth?: number;\n  /** Pointer targeting width. Defaults to `strokeWidth`. */\n  readonly lineInteractionWidth?: number;\n  /** Path opacity in [0, 1]. Defaults to 1. */\n  readonly opacity?: number;\n  /** Cursor while the batched path owns pointer presentation. */\n  readonly cursor?: string;\n}\n\n/**\n * A participant or specimen identity property or callback.\n *\n * Nullish identities deliberately omit a row. Numeric identities must be finite.\n * @param datum - Source observation.\n * @param index - Zero-based source index.\n * @param data - Complete source data array.\n * @returns A finite numeric or string identity, or a nullish omitted identity.\n * @see {@link TrajectorySeriesProps}\n */\nexport type TrajectoryGroupAccessor<D> =\n  | {\n      [K in keyof D]-?: D[K] extends string | number | null | undefined\n        ? K\n        : never;\n    }[keyof D]\n  | ((\n      datum: D,\n      index: number,\n      data: readonly D[],\n    ) => string | number | null | undefined);\n\n/**\n * Authoring inputs for {@link TrajectorySeries}.\n *\n * Rows are connected in source encounter order within each group. The component\n * neither sorts time values nor invents visits, summaries, or missing values.\n */\nexport interface TrajectorySeriesProps<D>\n  extends PibblEventHandlers, PibblEventParticipationOptions {\n  /** Source observations or a signal containing them. */\n  readonly data: SignalValue<readonly D[]>;\n  /** Stable participant or specimen identity. Nullish identities omit that row. */\n  readonly group: TrajectoryGroupAccessor<D>;\n  /** Encounter-time or scheduled-visit coordinate. */\n  readonly x: SeriesAccessor<D>;\n  /** Numeric observed outcome coordinate. */\n  readonly y: LineAccessor<D>;\n  /** Scale mapping encounter-time or visit coordinates. */\n  readonly xScale: ScaleId;\n  /** Numeric scale mapping outcomes. */\n  readonly yScale: ScaleId;\n  /**\n   * Ends that group's current run without reading coordinate accessors.\n   * @param datum - Candidate source datum.\n   * @param index - Zero-based source index.\n   * @param data - Complete source data array.\n   * @returns Whether this datum contributes a coordinate to its group.\n   */\n  readonly defined?: (datum: D, index: number, data: readonly D[]) => boolean;\n  /** Shared path style, including whole-object and shallow field signals. */\n  readonly style?: SignalValue<SignalStyle<TrajectorySeriesStyle>>;\n}\n\ninterface ResolvedTrajectoryStyle {\n  readonly stroke: StrokeStyle;\n  readonly strokeWidth: number;\n  readonly lineInteractionWidth: number;\n  readonly opacity: number;\n  readonly cursor?: string;\n}\n\nfunction style(input: unknown): ResolvedTrajectoryStyle {\n  if (input === null || typeof input !== \"object\" || Array.isArray(input))\n    throw new TypeError(\"TrajectorySeries: style must be an object.\");\n  const value = input as Record<string, unknown>;\n  for (const field of Object.keys(value))\n    if (\n      ![\n        \"stroke\",\n        \"strokeWidth\",\n        \"lineInteractionWidth\",\n        \"opacity\",\n        \"cursor\",\n      ].includes(field)\n    )\n      throw new TypeError(\n        `TrajectorySeries: unsupported style field ${field}.`,\n      );\n  const stroke = resolveSignalValue(value.stroke) ?? \"#2563eb\";\n  const strokeWidth = width(\n    (resolveSignalValue(value.strokeWidth) ?? 2) as number,\n    \"TrajectorySeries strokeWidth\",\n  );\n  const lineInteractionWidth = width(\n    (resolveSignalValue(value.lineInteractionWidth) ?? strokeWidth) as number,\n    \"TrajectorySeries lineInteractionWidth\",\n  );\n  const cursor = resolveSignalValue(value.cursor);\n  if (cursor !== undefined && typeof cursor !== \"string\")\n    throw new TypeError(\"TrajectorySeries: cursor must be a string.\");\n  return {\n    stroke: stroke as StrokeStyle,\n    strokeWidth,\n    lineInteractionWidth,\n    opacity: opacity(\n      (resolveSignalValue(value.opacity) ?? 1) as number,\n      \"TrajectorySeries opacity\",\n    ),\n    cursor,\n  };\n}\n\n/**\n * Draws one shared-style path connecting each participant or specimen trajectory.\n *\n * A missing, excluded, or non-finite coordinate ends only that group's current\n * run. Interleaved groups retain their source encounter order; trajectories are\n * never sorted by either actual or scheduled time.\n *\n * @param props - Observations, identities, coordinates, scales, and shared path paint.\n * @returns One batched ordinary Pibbl path containing source-ordered trajectory segments.\n * @see {@link TrajectorySeriesProps}\n */\nexport function TrajectorySeries<D>({\n  data: input,\n  group: groupInput,\n  x: xInput,\n  y: yInput,\n  xScale: xId,\n  yScale: yId,\n  defined,\n  style: styleInput,\n  ...events\n}: TrajectorySeriesProps<D>) {\n  const xs = useSeriesPosition(xId);\n  const ys = useNumericPosition(yId);\n  const data = pointData(resolveSignalValue(input), \"TrajectorySeries\");\n  const x = seriesAccessor(xInput);\n  const y = pointAccessor(yInput);\n  const group =\n    typeof groupInput === \"function\"\n      ? groupInput\n      : (datum: D) => datum[groupInput] as string | number | null | undefined;\n  const resolved = style(resolveSignalValue(styleInput) ?? {});\n  const last = new Map<string | number, readonly [number, number]>();\n  const path = new Path2D();\n  for (let i = 0; i < data.length; i++) {\n    const datum = data[i];\n    const row = withHooksForbidden(\n      \"TrajectorySeries: accessors cannot call hooks.\",\n      () => {\n        const identity = group(datum, i, data);\n        if (defined && !defined(datum, i, data)) return { group: identity };\n        return {\n          group: identity,\n          x: x(datum, i, data),\n          y: y(datum, i, data),\n        };\n      },\n    );\n    if (!row || row.group == null) continue;\n    if (\n      (typeof row.group !== \"string\" && typeof row.group !== \"number\") ||\n      (typeof row.group === \"number\" && !Number.isFinite(row.group))\n    )\n      throw new TypeError(\n        \"TrajectorySeries: group must be a string or number.\",\n      );\n    if (!(\"x\" in row) || !(\"y\" in row)) {\n      last.delete(row.group);\n      continue;\n    }\n    const px = mapSeriesPosition(xs, row.x);\n    const py = mapSeriesPosition(ys, row.y);\n    if (px === undefined || py === undefined) {\n      last.delete(row.group);\n      continue;\n    }\n    const prior = last.get(row.group);\n    if (prior) {\n      path.moveTo(prior[0], prior[1]);\n      path.lineTo(px, py);\n    }\n    last.set(row.group, [px, py]);\n  }\n  return <Path {...events} style={{ d: path, ...resolved }} />;\n}\n"],
+  "mappings": "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",
+  "names": []
+}

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

@@ -1,12 +1,13 @@
 import type { BarCategoryAccessor } from "./bar-series.js";
-import type { Scale } from "./scale.js";
+import type { LinearScale } from "./linear-scale-component.js";
 import type { nearestDomainValue } from "./nearest.js";
-import type { useScale } from "./use-scale.js";
+import type { useLinearScale } from "./use-linear-scale.js";
 import type { Axis } from "./axis.js";
 import type { PointAccessor } from "./point-types.js";
 import type { ScaleAdjust } from "./scale-adjust.js";
 import type { BoxStyle, PibblNode, LayoutItemStyle, LayoutBox, SignalValue } from "@pibbl/core";
 import type { SignalStyle } from "@pibbl/core/internal";
+import type { SeriesCurve } from "./curve-definition.js";
 /**
  * A string or symbol identifying a scale within visualization context.
  *
@@ -34,7 +35,7 @@ export type ScaleRange = "width" | "height" | readonly [number, number];
  *
  * @see {@link ScaleRange}
  * @see {@link ScaleId}
- * @see {@link BandScaleProps}
+ * @see {@link BarScaleProps}
  */
 export type BandScaleRange = ScaleRange | {
     /** Identifier of a parent band scale whose bandwidth supplies this range. See {@link ScaleId}. */
@@ -58,13 +59,11 @@ export type ScaleLayoutStyle = Pick<BoxStyle, "width" | "height"> & LayoutItemSt
  * @see {@link SignalStyle}
  * @see {@link ScaleLayoutStyle}
  * @see {@link PibblNode}
- * @see {@link BandScaleProps}
+ * @see {@link BarScaleProps}
  */
 export interface LinearScaleProps {
     /** Stable identifier of this resource or connection. See {@link ScaleId}. */
     readonly id: ScaleId;
-    /** The literal "linear" identifying this variant. See {@link LinearScaleProps}. */
-    readonly type: "linear";
     /**
      * Data values or endpoints accepted by the scale. See {@link SignalValue}, {@link LinearDomain}
      * .
@@ -97,7 +96,7 @@ export type BandCategory = string | number;
  * The ordered categories allocated by a band scale.
  *
  * @see {@link BandCategory}
- * @see {@link BandScaleProps}
+ * @see {@link BarScaleProps}
  * @see {@link ResolvedBandScale}
  */
 export type BandDomain = readonly BandCategory[];
@@ -108,11 +107,9 @@ export type BandDomain = readonly BandCategory[];
  * @see {@link SignalValue}
  * @see {@link BandDomain}
  * @see {@link BandScaleRange}
- * @see {@link ScaleProps}
+ * @see {@link LinearScaleProps}
  */
-export interface BandScaleProps extends Omit<LinearScaleProps, "type" | "domain" | "range"> {
-    /** The literal "band" identifying this variant. See {@link BandScaleProps}. */
-    readonly type: "band";
+export interface BarScaleProps extends Omit<LinearScaleProps, "domain" | "range"> {
     /**
      * Data values or endpoints accepted by the scale. See {@link SignalValue}, {@link BandDomain}.
      */
@@ -131,10 +128,15 @@ export interface BandScaleProps extends Omit<LinearScaleProps, "type" | "domain"
  * Authored inputs for Scale, including the declared data and presentation options.
  *
  * @see {@link LinearScaleProps}
- * @see {@link BandScaleProps}
- * @see {@link Scale}
+ * @see {@link BarScaleProps}
+ * @see {@link LinearScale}
  */
-export type ScaleProps = LinearScaleProps | BandScaleProps;
+/** UTC timestamps use numeric epoch milliseconds. See {@link LinearDomain}. */
+export type UtcDomain = LinearDomain;
+/** Numeric endpoints shared by continuous scales. See {@link LinearDomain}. */
+export type NumericDomain = LinearDomain;
+/** Calendar-aware UTC scale inputs. See {@link LinearScaleProps}. */
+export type UTCScaleProps = LinearScaleProps;
 /**
  * A resolved categorical mapping with its frame, bandwidth, and step.
  *
@@ -207,9 +209,73 @@ export interface ResolvedLinearScale {
  *
  * @see {@link ResolvedLinearScale}
  * @see {@link ResolvedBandScale}
- * @see {@link useScale}
+ * @see {@link useLinearScale}
  */
-export type ResolvedScale = ResolvedLinearScale | ResolvedBandScale;
+/** UTC continuous mapping with stateless ISO formatting. See {@link ResolvedLinearScale}. */
+export interface ResolvedUtcScale extends Omit<ResolvedLinearScale, "type"> {
+    /** UTC calendar scale discriminant. See {@link UTCScaleProps}. */
+    readonly type: "utc";
+    /**
+     * Formats a timestamp as full UTC ISO text without changing tick geometry.
+     * @param value - Finite epoch milliseconds inside the Date range.
+     * @returns ISO text with millisecond precision. See {@link ResolvedUtcScale}.
+     */
+    formatTick(value: number): string;
+}
+/** Any supported numeric mapping. See {@link ResolvedUtcScale}. */
+export type ResolvedContinuousScale = ResolvedLinearScale | ResolvedUtcScale | ResolvedLogScale | ResolvedSymlogScale;
+/** Positive logarithmic provider inputs. See {@link LinearScaleProps}. */
+export interface LogScaleProps extends LinearScaleProps {
+    /** Base for power ticks; finite and greater than one, default 10. Mapping is base-independent. */
+    readonly base?: SignalValue<number>;
+}
+/** Positive logarithmic mapping with numeric inverse. See {@link ResolvedLinearScale}. */
+export interface ResolvedLogScale extends Omit<ResolvedLinearScale, "type"> {
+    /** Logarithmic mapping discriminant. See {@link LogScaleProps}. */
+    readonly type: "log";
+    /** Resolved base used for power ticks. See {@link LogScaleProps}. */
+    readonly base: number;
+}
+/** A numeric or categorical mapping snapshot. See {@link ResolvedContinuousScale}. */
+export type ResolvedScale = ResolvedContinuousScale | ResolvedBandScale | ResolvedPointScale | import("./trading-time-scale.js").ResolvedTradingTimeScale;
+/** Signed logarithmic scale inputs. See {@link LinearScaleProps}. */
+export interface SymlogScaleProps extends LinearScaleProps {
+    /** Positive linear-to-log transition constant in domain units, default 1. */
+    readonly constant?: SignalValue<number>;
+}
+/** Signed logarithmic mapping through zero. See {@link ResolvedLinearScale}. */
+export interface ResolvedSymlogScale extends Omit<ResolvedLinearScale, "type"> {
+    /** Signed logarithmic discriminant. See {@link SymlogScaleProps}. */
+    readonly type: "symlog";
+    /** Positive transition constant. See {@link SymlogScaleProps}. */
+    readonly constant: number;
+}
+/** Equally spaced categorical positions. See {@link LinearScaleProps}. */
+export interface PointScaleProps extends Omit<LinearScaleProps, "domain"> {
+    /** Ordered unique string or finite numeric categories; accepts signals. See {@link BandDomain}. */
+    readonly domain: SignalValue<BandDomain>;
+    /** Nonnegative outer padding in step units, default 0. */
+    readonly padding?: SignalValue<number>;
+}
+/** Zero-width categorical point positions. See {@link ResolvedBandScale}. */
+export interface ResolvedPointScale extends Omit<ResolvedBandScale, "type" | "bandwidth"> {
+    /** Categorical point discriminant. See {@link PointScaleProps}. */
+    readonly type: "point";
+    /** Resolved outer padding. See {@link PointScaleProps}. */
+    readonly padding: number;
+    /**
+     * Finds the nearest category, clamping outside coordinates; ties choose first domain order.
+     * @param pixel - Finite range coordinate.
+     * @returns Category or undefined for an empty domain. See {@link BandCategory}.
+     */
+    invert(pixel: number): BandCategory | undefined;
+    /**
+     * Selects evenly spaced categories including endpoints when count permits.
+     * @param count - Integer maximum count 0–100, default 5.
+     * @returns Frozen categories in domain order. See {@link BandDomain}.
+     */
+    ticks(count?: number): BandDomain;
+}
 import type { PibblEventHandlers, PibblEventParticipationOptions, FillStyle, StrokeStyle } from "@pibbl/core";
 /**
  * Supported geometry and presentation properties for Axis.
@@ -247,6 +313,18 @@ interface AxisBaseProps {
      * @returns Text to draw for the tick label.
      */
     readonly tickFormat?: (value: number | string, index: number) => string;
+    /** Label collision policy; allow preserves all labels (default), skip measures and omits overlaps without removing ticks. */
+    readonly labelOverlap?: SignalValue<"allow" | "skip">;
+    /** Minimum distance between visible labels in logical pixels; defaults to 8. */
+    readonly labelGap?: SignalValue<number>;
+    /** Long-label policy, default allow. Wrap/truncate require labelMaxWidth; coordinates remain unchanged. */
+    readonly labelOverflow?: SignalValue<"allow" | "wrap" | "truncate">;
+    /** Maximum measured line width in logical pixels, positive and finite. Required for wrap/truncate. */
+    readonly labelMaxWidth?: SignalValue<number>;
+    /** Maximum wrapped lines, integer 1–20; default 2. Excess text receives an ellipsis. */
+    readonly labelMaxLines?: SignalValue<number>;
+    /** Positive line advance in logical pixels; default is measured font height plus 4. */
+    readonly labelLineHeight?: SignalValue<number>;
     /**
      * Declared presentation and layout properties. See {@link SignalValue}, {@link SignalStyle},
      * {@link AxisStyle}.
@@ -292,12 +370,25 @@ export type LineCoordinate = number | null | undefined;
 export type LineAccessor<D> = {
     [K in keyof D]-?: D[K] extends LineCoordinate ? K : never;
 }[keyof D] | ((datum: D, index: number, data: readonly D[]) => LineCoordinate);
+/** A numeric or categorical position, or a missing value. @see {@link SeriesAccessor} */
+export type SeriesCoordinate = number | string | null | undefined;
+/**
+ * Extracts one position for a line, point, or custom mark.
+ * @param datum - Original record.
+ * @param index - Original record index.
+ * @param data - Complete source records.
+ * @returns A numeric or categorical position. See {@link SeriesCoordinate}.
+ * @see {@link LineSeriesProps}
+ */
+export type SeriesAccessor<D> = {
+    [K in keyof D]-?: D[K] extends SeriesCoordinate ? K : never;
+}[keyof D] | ((datum: D, index: number, data: readonly D[]) => SeriesCoordinate);
 /**
  * The supported interpolation mode for a line series.
  *
  * @see {@link LineSeriesProps}
  */
-export type LineCurve = "linear";
+export type LineCurve = "linear" | SeriesCurve;
 /**
  * Supported geometry and presentation properties for LineSeries.
  *
@@ -336,10 +427,12 @@ export interface LineSeriesProps<D> extends PibblEventHandlers, PibblEventPartic
      * Application data supplied to the component or reported by the event. See {@link SignalValue}.
      */
     readonly data: SignalValue<readonly D[]>;
+    /** Optional committed numeric observation capture; no query execution during paint. */
+    readonly inspection?: import("../inspection/capture-types.js").NumericInspectionRef<D>;
     /** Property key or callback extracting the horizontal domain coordinate. See {@link LineAccessor}. */
-    readonly x: LineAccessor<D>;
+    readonly x: SeriesAccessor<D>;
     /** Property key or callback extracting the vertical domain coordinate. See {@link LineAccessor}. */
-    readonly y: LineAccessor<D>;
+    readonly y: SeriesAccessor<D>;
     /** The scale used to map horizontal data coordinates. See {@link ScaleId}. */
     readonly xScale: ScaleId;
     /** The scale used to map vertical data coordinates. See {@link ScaleId}. */
@@ -372,7 +465,7 @@ type ScaleAdjustX = {
      * Horizontal coordinate or displacement in the containing coordinate system. See
      * {@link SignalValue}.
      */
-    readonly x: SignalValue<number>;
+    readonly x: SignalValue<BandCategory>;
     /** The scale used to map horizontal data coordinates. See {@link ScaleId}. */
     readonly xScale: ScaleId;
 } | {
@@ -392,7 +485,7 @@ type ScaleAdjustY = {
      * Vertical coordinate or displacement in the containing coordinate system. See
      * {@link SignalValue}.
      */
-    readonly y: SignalValue<number>;
+    readonly y: SignalValue<BandCategory>;
     /** The scale used to map vertical data coordinates. See {@link ScaleId}. */
     readonly yScale: ScaleId;
 } | {