@pibbl/core 0.0.1 → 0.0.3-alpha.109.1

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 {};