@pibbl/core 0.0.2 → 0.0.3-alpha.85.1

package/dist/features/viz/lib/domain-navigation.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/viz/lib/domain-navigation.ts"],
+  "sourcesContent": ["import type { LinearDomain, ResolvedContinuousScale } from \"./types.js\";\n/** Explicit hard bounds and minimum mapped extent for continuous-domain navigation. @see {@link panDomain} @see {@link zoomDomain} */\nexport interface DomainNavigationConstraints {\n  /** Finite hard domain endpoints, in either order, valid for the supplied scale. See {@link LinearDomain}. */\n  readonly bounds: LinearDomain;\n  /** Minimum span as a fraction of the mapped hard bounds, greater than zero through one. Defaults to 0.01. */\n  readonly minimumSpanRatio?: number;\n}\n/** Named pan settings with explicit navigation limits. @see {@link panDomain} */\nexport interface PanDomainOptions extends DomainNavigationConstraints {\n  /** Finite displacement in range units; positive shifts mapped values toward increasing range coordinates. */\n  readonly rangeDelta: number;\n}\n/** Named zoom settings with explicit navigation limits. @see {@link zoomDomain} */\nexport interface ZoomDomainOptions extends DomainNavigationConstraints {\n  /** Finite anchor in the scale's range coordinates, using the same units as its range. */\n  readonly rangeAnchor: number;\n  /** Finite positive magnification; greater than one zooms in. */\n  readonly factor: number;\n}\nfunction finite(value: number, name: string): number {\n  if (typeof value !== \"number\" || !Number.isFinite(value))\n    throw new RangeError(`${name} must be finite.`);\n  return value;\n}\nfunction navigate(\n  scale: ResolvedContinuousScale,\n  start: number,\n  end: number,\n  constraints: DomainNavigationConstraints,\n  requestedSpan?: number,\n): LinearDomain {\n  const [r0, r1] = scale.range;\n  if (r0 === r1 || scale.domain[0] === scale.domain[1])\n    throw new RangeError(\n      \"Domain navigation requires noncollapsed domain and range.\",\n    );\n  const { bounds, minimumSpanRatio = 0.01 } = constraints;\n  if (!Array.isArray(bounds) || bounds.length !== 2)\n    throw new RangeError(\"Navigation bounds require two endpoints.\");\n  if (scale.type === \"utc\" && !bounds.every(Number.isSafeInteger))\n    throw new RangeError(\n      \"UTC navigation bounds must be safe integer milliseconds.\",\n    );\n  const b0 = scale.map(finite(bounds[0], \"Lower bound\")),\n    b1 = scale.map(finite(bounds[1], \"Upper bound\"));\n  const lo = Math.min(b0, b1),\n    hi = Math.max(b0, b1),\n    extent = hi - lo;\n  if (!Number.isFinite(extent) || extent <= 0)\n    throw new RangeError(\n      \"Navigation bounds must have a finite nonzero mapped extent.\",\n    );\n  if (\n    !Number.isFinite(minimumSpanRatio) ||\n    minimumSpanRatio <= 0 ||\n    minimumSpanRatio > 1\n  )\n    throw new RangeError(\n      \"minimumSpanRatio must be greater than zero and at most one.\",\n    );\n  finite(start, \"Mapped start\");\n  finite(end, \"Mapped end\");\n  const requested = requestedSpan ?? Math.abs(end - start);\n  if (!Number.isFinite(requested))\n    throw new RangeError(\"Navigation span must be finite.\");\n  const span = Math.min(extent, Math.max(extent * minimumSpanRatio, requested));\n  const center = start / 2 + end / 2;\n  const low = Math.max(lo, Math.min(hi - span, center - span / 2)),\n    high = low + span;\n  let a = scale.invert(r0 < r1 ? low : high),\n    b = scale.invert(r0 < r1 ? high : low);\n  if (scale.type === \"utc\") {\n    a = Math.round(a);\n    b = Math.round(b);\n  }\n  finite(a, \"Domain start\");\n  finite(b, \"Domain end\");\n  if (a === b)\n    throw new RangeError(\n      \"Navigation result collapses at the scale's numeric precision.\",\n    );\n  return Object.freeze([a, b] as const);\n}\n/**\n * Moves the visible continuous domain by a displacement expressed in range units.\n * Positive displacement shifts mapped values toward increasing range coordinates; the returned domain moves oppositely.\n * @param scale - Current resolved continuous mapping. See {@link ResolvedContinuousScale}.\n * @param options - Displacement, bounds, and minimum span. See {@link PanDomainOptions}.\n * @returns A new immutable domain pair. See {@link LinearDomain}.\n * @throws When inputs, bounds, or the resulting extent are invalid or collapsed.\n * @see {@link zoomDomain}\n */\nexport function panDomain(\n  scale: ResolvedContinuousScale,\n  options: PanDomainOptions,\n): LinearDomain {\n  const { rangeDelta } = options;\n  finite(rangeDelta, \"Pan displacement\");\n  return navigate(\n    scale,\n    scale.range[0] - rangeDelta,\n    scale.range[1] - rangeDelta,\n    options,\n    Math.abs(scale.range[1] - scale.range[0]),\n  );\n}\n/**\n * Magnifies a continuous domain around an anchor in range coordinates.\n * Factor greater than one zooms in; hard bounds and minimum span may limit anchor preservation.\n * @param scale - Current resolved continuous mapping. See {@link ResolvedContinuousScale}.\n * @param options - Anchor, magnification, bounds, and minimum span. See {@link ZoomDomainOptions}.\n * @returns A new immutable domain pair. See {@link LinearDomain}.\n * @throws When factor, mapping, bounds, or the resulting extent are invalid or collapsed.\n * @see {@link panDomain}\n */\nexport function zoomDomain(\n  scale: ResolvedContinuousScale,\n  options: ZoomDomainOptions,\n): LinearDomain {\n  const { rangeAnchor, factor } = options;\n  finite(rangeAnchor, \"Zoom anchor\");\n  finite(factor, \"Zoom factor\");\n  if (factor <= 0) throw new RangeError(\"Zoom factor must be positive.\");\n  return navigate(\n    scale,\n    rangeAnchor + (scale.range[0] - rangeAnchor) / factor,\n    rangeAnchor + (scale.range[1] - rangeAnchor) / factor,\n    options,\n  );\n}\n"],
+  "mappings": "AAoBA,SAAS,OAAO,OAAe,MAAsB;AACnD,MAAI,OAAO,UAAU,YAAY,CAAC,OAAO,SAAS,KAAK;AACrD,UAAM,IAAI,WAAW,GAAG,IAAI,kBAAkB;AAChD,SAAO;AACT;AACA,SAAS,SACP,OACA,OACA,KACA,aACA,eACc;AACd,QAAM,CAAC,IAAI,EAAE,IAAI,MAAM;AACvB,MAAI,OAAO,MAAM,MAAM,OAAO,CAAC,MAAM,MAAM,OAAO,CAAC;AACjD,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AACF,QAAM,EAAE,QAAQ,mBAAmB,KAAK,IAAI;AAC5C,MAAI,CAAC,MAAM,QAAQ,MAAM,KAAK,OAAO,WAAW;AAC9C,UAAM,IAAI,WAAW,0CAA0C;AACjE,MAAI,MAAM,SAAS,SAAS,CAAC,OAAO,MAAM,OAAO,aAAa;AAC5D,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AACF,QAAM,KAAK,MAAM,IAAI,OAAO,OAAO,CAAC,GAAG,aAAa,CAAC,GACnD,KAAK,MAAM,IAAI,OAAO,OAAO,CAAC,GAAG,aAAa,CAAC;AACjD,QAAM,KAAK,KAAK,IAAI,IAAI,EAAE,GACxB,KAAK,KAAK,IAAI,IAAI,EAAE,GACpB,SAAS,KAAK;AAChB,MAAI,CAAC,OAAO,SAAS,MAAM,KAAK,UAAU;AACxC,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AACF,MACE,CAAC,OAAO,SAAS,gBAAgB,KACjC,oBAAoB,KACpB,mBAAmB;AAEnB,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AACF,SAAO,OAAO,cAAc;AAC5B,SAAO,KAAK,YAAY;AACxB,QAAM,YAAY,iBAAiB,KAAK,IAAI,MAAM,KAAK;AACvD,MAAI,CAAC,OAAO,SAAS,SAAS;AAC5B,UAAM,IAAI,WAAW,iCAAiC;AACxD,QAAM,OAAO,KAAK,IAAI,QAAQ,KAAK,IAAI,SAAS,kBAAkB,SAAS,CAAC;AAC5E,QAAM,SAAS,QAAQ,IAAI,MAAM;AACjC,QAAM,MAAM,KAAK,IAAI,IAAI,KAAK,IAAI,KAAK,MAAM,SAAS,OAAO,CAAC,CAAC,GAC7D,OAAO,MAAM;AACf,MAAI,IAAI,MAAM,OAAO,KAAK,KAAK,MAAM,IAAI,GACvC,IAAI,MAAM,OAAO,KAAK,KAAK,OAAO,GAAG;AACvC,MAAI,MAAM,SAAS,OAAO;AACxB,QAAI,KAAK,MAAM,CAAC;AAChB,QAAI,KAAK,MAAM,CAAC;AAAA,EAClB;AACA,SAAO,GAAG,cAAc;AACxB,SAAO,GAAG,YAAY;AACtB,MAAI,MAAM;AACR,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AACF,SAAO,OAAO,OAAO,CAAC,GAAG,CAAC,CAAU;AACtC;AAUO,SAAS,UACd,OACA,SACc;AACd,QAAM,EAAE,WAAW,IAAI;AACvB,SAAO,YAAY,kBAAkB;AACrC,SAAO;AAAA,IACL;AAAA,IACA,MAAM,MAAM,CAAC,IAAI;AAAA,IACjB,MAAM,MAAM,CAAC,IAAI;AAAA,IACjB;AAAA,IACA,KAAK,IAAI,MAAM,MAAM,CAAC,IAAI,MAAM,MAAM,CAAC,CAAC;AAAA,EAC1C;AACF;AAUO,SAAS,WACd,OACA,SACc;AACd,QAAM,EAAE,aAAa,OAAO,IAAI;AAChC,SAAO,aAAa,aAAa;AACjC,SAAO,QAAQ,aAAa;AAC5B,MAAI,UAAU,EAAG,OAAM,IAAI,WAAW,+BAA+B;AACrE,SAAO;AAAA,IACL;AAAA,IACA,eAAe,MAAM,MAAM,CAAC,IAAI,eAAe;AAAA,IAC/C,eAAe,MAAM,MAAM,CAAC,IAAI,eAAe;AAAA,IAC/C;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/features/viz/lib/editable-chart-elements.d.ts

@@ -0,0 +1,178 @@
+import { type SignalValue } from "@pibbl/core";
+import { type SignalStyle } from "@pibbl/core/internal";
+import type { ScaleId } from "./types.js";
+/** One numeric x/y domain anchor for {@link EditableTrendLine}. */
+export interface ChartAnchor {
+    /** X-scale domain value; an exact supplied timestamp for a trading-time x scale. */
+    readonly x: number;
+    /** Y-scale numeric domain value. */
+    readonly y: number;
+}
+/** Paint and hit-area fields shared by {@link RangeNavigator} and editable annotations. */
+export interface EditableChartStyle {
+    /** Fill for navigator and reference-band interiors. */
+    readonly fill?: string;
+    /** Stroke color for visible annotation geometry. */
+    readonly stroke?: string;
+    /** Positive width of visible strokes. */
+    readonly strokeWidth?: number;
+    /** Annotation opacity from zero through one; handles remain fully opaque. */
+    readonly opacity?: number;
+    /** Fill color for visible drag handles. */
+    readonly handleFill?: string;
+    /** Stroke color for visible drag handles. */
+    readonly handleStroke?: string;
+    /** Positive square size of the painted handle. */
+    readonly handleSize?: number;
+    /** Positive width and height of each invisible pointer hit region. */
+    readonly hitSize?: number;
+}
+/** {@link EditableChartStyle} accepted by {@link RangeNavigator}. */
+export interface RangeNavigatorStyle extends EditableChartStyle {
+}
+/** {@link EditableChartStyle} accepted by {@link EditableReferenceLine}. */
+export interface EditableReferenceLineStyle extends EditableChartStyle {
+}
+/** {@link EditableChartStyle} accepted by {@link EditableReferenceBand}. */
+export interface EditableReferenceBandStyle extends EditableChartStyle {
+}
+/** {@link EditableChartStyle} accepted by {@link EditableTrendLine}. */
+export interface EditableTrendLineStyle extends EditableChartStyle {
+}
+type Pair = readonly [number, number];
+type StyleInput<S extends EditableChartStyle> = SignalValue<SignalStyle<S>>;
+type Change<T> = (value: T) => void;
+/** Controlled inputs and callbacks for {@link RangeNavigator}. */
+export interface RangeNavigatorProps {
+    /** ID of an ancestor invertible numeric continuous scale. */
+    readonly scale: ScaleId;
+    /** Controlled numeric interval in the scale domain. */
+    readonly values: SignalValue<Pair>;
+    /** Perpendicular local-coordinate start and end for the navigator strip. */
+    readonly span: SignalValue<Pair>;
+    /** Minimum numeric distance between interval endpoints; defaults to zero. */
+    readonly minimumSpan?: number;
+    /** Receives each synchronous controlled drag or keyboard interval. */
+    readonly onChange: Change<Pair>;
+    /** Receives the final interval after a completed pointer or keyboard edit. */
+    readonly onCommit?: Change<Pair>;
+    /** Runs after a cancelled interaction restores its starting interval. */
+    readonly onCancel?: () => void;
+    /** Optional annotation and handle paint inputs. */
+    readonly style?: StyleInput<RangeNavigatorStyle>;
+}
+/** Controlled inputs and callbacks for {@link EditableReferenceLine}. */
+export interface EditableReferenceLineProps {
+    /** ID of an ancestor invertible numeric continuous scale. */
+    readonly scale: ScaleId;
+    /** Axis perpendicular to the drawn line and edited value. */
+    readonly direction: "horizontal" | "vertical";
+    /** Controlled numeric value in the scale domain. */
+    readonly value: SignalValue<number>;
+    /** Local-coordinate extent of the line along its non-edited axis. */
+    readonly span: SignalValue<Pair>;
+    /** Whether endpoint-independent handle geometry is drawn; defaults to true. */
+    readonly selected?: SignalValue<boolean>;
+    /** Finite positive numeric domain increment for arrow-key edits. */
+    readonly keyboardStep: number;
+    /** Runs when a pointer or keyboard interaction selects the line. */
+    readonly onSelect?: () => void;
+    /** Receives each synchronous controlled drag or keyboard value. */
+    readonly onChange: Change<number>;
+    /** Receives the final value after a completed pointer or keyboard edit. */
+    readonly onCommit?: Change<number>;
+    /** Runs after a cancelled interaction restores its starting value. */
+    readonly onCancel?: () => void;
+    /** Optional line and handle paint inputs. */
+    readonly style?: StyleInput<EditableReferenceLineStyle>;
+}
+/** Controlled inputs and callbacks for {@link EditableReferenceBand}. */
+export interface EditableReferenceBandProps {
+    /** ID of an ancestor invertible numeric continuous scale. */
+    readonly scale: ScaleId;
+    /** Axis perpendicular to the band and edited interval. */
+    readonly direction: "horizontal" | "vertical";
+    /** Controlled numeric interval in the scale domain. */
+    readonly values: SignalValue<Pair>;
+    /** Local-coordinate extent of the band along its non-edited axis. */
+    readonly span: SignalValue<Pair>;
+    /** Whether resize handles are drawn; defaults to true. */
+    readonly selected?: SignalValue<boolean>;
+    /** Finite positive numeric domain increment for arrow-key panning. */
+    readonly keyboardStep: number;
+    /** Minimum numeric distance between interval endpoints; defaults to zero. */
+    readonly minimumSpan?: number;
+    /** Runs when a pointer or keyboard interaction selects the band. */
+    readonly onSelect?: () => void;
+    /** Receives each synchronous controlled drag or keyboard interval. */
+    readonly onChange: Change<Pair>;
+    /** Receives the final interval after a completed pointer or keyboard edit. */
+    readonly onCommit?: Change<Pair>;
+    /** Runs after a cancelled interaction restores its starting interval. */
+    readonly onCancel?: () => void;
+    /** Optional band and handle paint inputs. */
+    readonly style?: StyleInput<EditableReferenceBandStyle>;
+}
+/** Controlled inputs and callbacks for {@link EditableTrendLine}. */
+export interface EditableTrendLineProps {
+    /** ID of an ancestor numeric or TradingTimeScale x mapping. */
+    readonly xScale: ScaleId;
+    /** ID of an ancestor invertible numeric y mapping. */
+    readonly yScale: ScaleId;
+    /** Controlled pair of domain anchors forming the line. */
+    readonly anchors: SignalValue<readonly [ChartAnchor, ChartAnchor]>;
+    /** Whether endpoint handles are drawn; defaults to true. */
+    readonly selected?: SignalValue<boolean>;
+    /** Finite positive x and y increments for arrow-key translation. */
+    readonly keyboardStep: {
+        /** Numeric-domain or timestamp increment for x translation. */
+        readonly x: number;
+        /** Numeric-domain increment for y translation. */
+        readonly y: number;
+    };
+    /** Runs when a pointer or keyboard interaction selects the trend line. */
+    readonly onSelect?: () => void;
+    /** Receives each synchronous controlled drag or keyboard anchor pair. */
+    readonly onChange: Change<readonly [ChartAnchor, ChartAnchor]>;
+    /** Receives final anchors after a completed pointer or keyboard edit. */
+    readonly onCommit?: Change<readonly [ChartAnchor, ChartAnchor]>;
+    /** Runs after a cancelled interaction restores its starting anchors. */
+    readonly onCancel?: () => void;
+    /** Optional line and handle paint inputs. */
+    readonly style?: StyleInput<EditableTrendLineStyle>;
+}
+/**
+ * Renders a controlled overview interval with pan and edge-resize handles.
+ *
+ * @param props - Controlled range inputs and callbacks; see {@link RangeNavigatorProps}.
+ * @returns Navigator geometry, handles, or no geometry when outside the visible scale range.
+ * @see {@link EditableReferenceBand} for a directional plot interval.
+ */
+export declare function RangeNavigator(props: RangeNavigatorProps): import("../../../jsx-runtime.js").JSX.Element | null;
+/**
+ * Renders one controlled numeric-domain reference line.
+ *
+ * @param props - Controlled line inputs and callbacks; see {@link EditableReferenceLineProps}.
+ * @returns The line and its selected handle, or no geometry when it is outside the visible range.
+ * @see {@link EditableReferenceBand} for an editable interval.
+ */
+export declare function EditableReferenceLine(props: EditableReferenceLineProps): import("../../../jsx-runtime.js").JSX.Element | null;
+/**
+ * Renders a controlled numeric-domain interval with pan and edge-resize handles.
+ *
+ * @param props - Controlled band inputs and callbacks; see {@link EditableReferenceBandProps}.
+ * @returns Band geometry and selected handles, or no geometry when outside the visible range.
+ * @see {@link RangeNavigator} for an overview-strip interval.
+ */
+export declare function EditableReferenceBand(props: EditableReferenceBandProps): import("../../../jsx-runtime.js").JSX.Element | null;
+/**
+ * Renders two controlled anchors as an editable trend line.
+ *
+ * Trading-time x values snap to supplied observations during pointer and keyboard edits.
+ *
+ * @param props - Controlled anchor inputs and callbacks; see {@link EditableTrendLineProps}.
+ * @returns Line geometry and selected endpoint handles.
+ * @see {@link ChartAnchor} for the controlled anchor shape.
+ */
+export declare function EditableTrendLine(props: EditableTrendLineProps): import("../../../jsx-runtime.js").JSX.Element;
+export {};