@pond-ts/charts 0.56.2 → 0.58.0

package/dist/selection-fixtures.d.ts

@@ -0,0 +1,174 @@
+import type { ReactNode } from 'react';
+import { BoundedSequence, Sequence } from 'pond-ts';
+import type { SelectInfo } from './context.js';
+/**
+ * **Chart fixtures for the selection matrix** (`Interactions/Selector/*`,
+ * `Interactions/MultiSelector/*`).
+ *
+ * The selection stories are a **matrix**: one feature set × one fixture per
+ * chart type, generated by `selection-stories.tsx`. This file supplies the
+ * columns; that file supplies the rows.
+ *
+ * **Why generated rather than hand-written per column.** A matrix is only a
+ * review instrument if a difference between two columns is a difference in the
+ * *library* — if each cell were written by hand, a divergence could equally be
+ * someone having wired the story differently, and you'd have to read both to
+ * know which. Generating every cell from one definition makes any visible
+ * difference a real one. (It also makes a new chart type ~10 lines instead of a
+ * dozen near-copies, which is what makes widening the matrix survivable.)
+ *
+ * That is not hypothetical: half a built matrix already surfaced two defects —
+ * categorical hover being ink-only where the time axis claims the whole slot,
+ * and `<RangeCursor>` on an ordinal axis suppressing the row's cursor entirely.
+ *
+ * **Capabilities are declared, not assumed.** `sequence` and `rangeCursor` are
+ * absent on fixtures that cannot support them, so the factory omits those
+ * stories rather than generating one that silently does nothing. A gap in the
+ * matrix is information; a story that renders nothing is a trap.
+ */
+export interface ChartFixture {
+    /** Sub-folder name in the Storybook tree (`Interactions/Selector/<name>`). */
+    readonly name: string;
+    /** Container props this chart needs — a `range` for a time axis. */
+    readonly container: Record<string, unknown>;
+    /** The primary y-axis. */
+    readonly axis: {
+        id: string;
+        min: number;
+        max: number;
+        label: string;
+    };
+    /** The layer under test, tagged with `id` (identity — see RFC Q8). */
+    renderLayer(id: string): ReactNode;
+    /** A second row's axis + layer, for the row-scoping story. */
+    readonly secondary: {
+        axis: {
+            id: string;
+            min: number;
+            max: number;
+            label: string;
+        };
+        renderLayer(id: string): ReactNode;
+    };
+    /** Marks an *external* control can pick — drives the controlled-selection
+     *  story, the case `<Selector enabled={false}>` exists to protect. */
+    readonly picks: readonly {
+        label: string;
+        info: SelectInfo;
+    }[];
+    /** How a hit reads in a caption. */
+    describe(hit: SelectInfo): string;
+    /**
+     * Whether the layer publishes `beginSweep` — i.e. whether it can be
+     * **swept at all**. Without one a mounted `<MultiSelector>` has neither a
+     * drag nor a resting block preview, so every cell of that column would
+     * render a chart that quietly ignores the component under test.
+     *
+     * `false` on the **2-D family** — scatter and heat map — whose marks do not
+     * reduce to a run of columns, so the gesture they need is
+     * [PND-INTERACT2D]'s rect rather than this one on a new layer. The list
+     * family still owes the sweep too ([PND-INTERACTCONF]).
+     */
+    readonly sweep: boolean;
+    /** A snapping sequence, where the axis has one. Ordinal axes do not. */
+    readonly sequence?: () => Sequence | BoundedSequence;
+    /** Whether `<RangeCursor>` draws here — it gates on a continuous x
+     *  (`brush.tsx`), so mounting one on a category axis is not just inert, it
+     *  takes the row's cursor with it. */
+    readonly rangeCursor: boolean;
+    /**
+     * Present only where the x axis **collapses closed-market time**, which is
+     * what makes a snap block's relationship to the session grid a question at
+     * all. Supplies the two bucketings that answer it — see the pair of stories
+     * `makeSessionStories` generates.
+     */
+    readonly sessions?: {
+        /** A bucketing that **agrees** with the session grid: one block per
+         *  session, so a block's edges land exactly on the dividers. */
+        conforming: () => BoundedSequence;
+        /** A bucketing that **doesn't**: a wall-clock period whose boundaries fall
+         *  mid-session, so a block starts inside one session, crosses the collapsed
+         *  gap, and ends inside the next. */
+        crossing: () => Sequence;
+    };
+}
+declare const DAY = 86400000;
+declare const D0: number;
+export declare const categoricalBars: ChartFixture;
+export declare const timeBars: ChartFixture;
+/**
+ * **A stacked bar chart** — the column where a bin holds *many* marks.
+ *
+ * Every other column is one mark per x position, so "the mark under the
+ * pointer" and "the bin under the pointer" are the same thing and nothing
+ * distinguishes them. Here they come apart: a wide series carries no stable
+ * per-bin `mark`, so a segment's identity is the pair **`(key = bin begin,
+ * label = group)`** and one bin's three segments share a key. That is the
+ * axis this column exercises — click resolves to a segment, while a sweep
+ * materialises *every* drawn segment of every covered bin.
+ */
+export declare const stackedBars: ChartFixture;
+/** The default shape: a q1→q3 body with thin stems and end caps. The stems are
+ *  the interesting part for selection — they are drawn ink far from the body. */
+export declare const boxWhisker: ChartFixture;
+/** The candlestick look: a light outer bar over the full range, a darker inner
+ *  body, no stems. The mark is one solid rect, so the hittable area is the
+ *  whole p5→p95 span rather than a body plus two thin stems. */
+export declare const boxSolid: ChartFixture;
+/**
+ * **A candlestick column** — the mark whose *hue is its meaning*.
+ *
+ * Every other column is free to recolour on selection: a bar swaps its fill, a
+ * box rotates its whole tint ladder. A candle cannot. Rising vs falling is the
+ * first thing anyone reads off it, and that read lives in exactly the channel
+ * the other marks use to announce state — so this column exists to check that
+ * a selected candle still says which way the price went.
+ *
+ * It sweeps like the rest: a candle owns one `[x, xEnd)` column, same as a box.
+ */
+export declare const candles: ChartFixture;
+/**
+ * **A scatter column** — the first mark that does *not* own a column.
+ *
+ * Every fixture before this one is an interval on the key axis: a bar, a
+ * stacked bin, a box, a candle. A scatter point is a position, `(x, y)`, with
+ * no span either side of it — so "the marks between here and there" is a
+ * question about a **region**, not about a run of columns, and `sweep1D`'s
+ * two binary searches have nothing to cut.
+ *
+ * Hence `sweep: false`, and hence [PND-INTERACT2D] rather than a quick wiring
+ * job: the 2-D rect is a different gesture, not the same one on a new layer.
+ */
+export declare const scatterPoints: ChartFixture;
+/**
+ * **A heat-map column** — a *grid* of cells, `(bin × row)`.
+ *
+ * A heat map's bins do own columns, so an x-only sweep would be well defined —
+ * and it would also be the wrong gesture. Selecting every row of a covered bin
+ * ignores the y dimension the mark exists to show, and the rect that reads it
+ * is [PND-INTERACT2D]'s, so this declares `sweep: false` rather than shipping
+ * the half of the gesture that happens to be easy.
+ */
+export declare const heatGrid: ChartFixture;
+/**
+ * **A trading-time axis** — closed-market time collapsed, session dividers
+ * drawn. Selection on a *continuous* axis never has to ask where a block's
+ * edges fall relative to the data's own structure; here it does, because the
+ * axis has seams and a wall-clock bucketing knows nothing about them.
+ *
+ * `sessionDividers: 'all'` is part of the fixture rather than of one story:
+ * every cell in this column is about the session grid, so the grid should be
+ * visible in all of them.
+ */
+export declare const tradingSessions: ChartFixture;
+/** Every column of the matrix, in tree order. */
+export declare const FIXTURES: readonly [ChartFixture, ChartFixture, ChartFixture, ChartFixture, ChartFixture, ChartFixture, ChartFixture, ChartFixture, ChartFixture];
+/** Shared caption styling, so every cell reads identically. */
+export declare const caption: {
+    readonly font: "13px system-ui";
+    readonly color: "#667";
+    readonly marginTop: 4;
+    readonly maxWidth: 640;
+};
+export { DAY, D0 };
+//# sourceMappingURL=selection-fixtures.d.ts.map