@react-x11/components 0.1.0 → 0.2.0

package/dist/charts/data.d.ts

@@ -0,0 +1,198 @@
+/** One row, shadcn-style: `{ month: 'Jan', desktop: 186 }`. */
+export type ChartRow = Record<string, unknown>;
+/** Columnar input — the fast path. Arrays may be typed arrays; a column may
+ * hold strings (a category axis). `length` bounds every column. */
+export interface ColumnarData {
+    length: number;
+    columns: Record<string, ArrayLike<number> | ArrayLike<string>>;
+}
+/**
+ * The streaming store's contract, written structurally — deliberately not
+ * `typeof ChartData`. Structural, so a JSX augmentation carrying it
+ * unifies across the src/dist boundary (a class with private state would
+ * not), and so an app can bring its own store: anything that answers
+ * columns and announces appends is a chart data source.
+ */
+export interface ChartDataLike {
+    readonly length: number;
+    /** Bumps when history shifts; derived caches rebuild then. */
+    readonly epoch: number;
+    column(key: string): ResolvedColumn | null;
+    subscribe(listener: (change: ChartDataChange) => void): () => void;
+}
+/** What `data` accepts: rows, columns, or a streaming store. */
+export type ChartSourceData = readonly ChartRow[] | ColumnarData | ChartDataLike;
+export declare function isChartDataLike(data: ChartSourceData): data is ChartDataLike;
+/** A resolved column: raw storage, the valid length (storage may hold slack
+ * capacity), and the identity/version pair the caches key on. */
+export interface ResolvedColumn {
+    values: ArrayLike<number> | ArrayLike<string>;
+    n: number;
+    /** Cache identity — WeakMap key. Stable for the life of the column. */
+    host: object;
+    /** Bumps when history changed under the same host (a window shift). */
+    epoch: number;
+    numeric: boolean;
+}
+/** A resolved numeric column, which is what every renderer consumes. */
+export interface NumericColumn extends ResolvedColumn {
+    values: ArrayLike<number>;
+    numeric: true;
+}
+/**
+ * The column `key` names in `data`, or null when there is none. Cheap to
+ * call every paint: each shape resolves through an identity-keyed cache.
+ */
+export declare function resolveColumn(data: ChartSourceData, key: string): ResolvedColumn | null;
+/** Narrow to numeric, which is what scales and pyramids need. */
+export declare function numericColumn(col: ResolvedColumn | null): NumericColumn | null;
+export interface ChartDataOptions {
+    /** Keep at most this many points, dropping the oldest. The drop happens
+     * in occasional batches (12.5% slack), so appends stay O(1) and the
+     * expensive re-preparation is amortized over many frames. */
+    maxLength?: number;
+    /**
+     * Keep only points whose `key` column is within `ms` of the newest one —
+     * a **time** window where `maxLength` is a count window. A live feed
+     * wants this one: a count window silently turns into "however long that
+     * many points took", and an OS that throttles a hidden window's timers
+     * (it fires them slowly rather than not at all, so no gap heuristic
+     * notices) leaves a minutes-wide, points-thin era in the store — the
+     * dense fresh data then renders squeezed beside honest emptiness until
+     * enough appends push the sparse era out. Age eviction drops it on the
+     * first append instead, hard stalls included. Assumes `key` is appended
+     * in non-decreasing order, which a timestamp is; trims in occasional
+     * batches like `maxLength`.
+     */
+    maxAge?: {
+        key: string;
+        ms: number;
+    };
+}
+export interface ChartDataChange {
+    appended: number;
+    /** History moved (a window shift): everything derived must rebuild. */
+    epoch: number;
+}
+/**
+ * The streaming data store: append-only columns in growable typed arrays.
+ *
+ * This is the "proper data structures and preparations" half of the
+ * performance story. Charts subscribing to a store never rescan history —
+ * an append extends the decimation pyramids incrementally and invalidates
+ * nothing, so a 10Hz feed into a million-point series stays O(appended)
+ * per tick plus one bounded repaint per visible chart.
+ */
+export declare class ChartData {
+    private _cols;
+    private _n;
+    private _epoch;
+    private _listeners;
+    private readonly _maxLength;
+    private readonly _maxAge;
+    constructor(options?: ChartDataOptions);
+    get length(): number;
+    /** Bumps when history shifts; caches keyed on it rebuild then. */
+    get epoch(): number;
+    /** Append one row. Keys never seen before backfill NaN (numeric) or ''
+     * so every column always covers every index. */
+    append(row: Readonly<Record<string, number | string>>): void;
+    /**
+     * Drop every row, keeping the columns and their storage. The reset every
+     * live dashboard eventually wants: a stream resuming after its process
+     * was suspended (a hidden window, a laptop lid) comes back with a time
+     * gap as wide as the sleep, and a windowed store then renders fifty
+     * seconds of data squeezed beside fourteen minutes of nothing until the
+     * gap evicts. Clearing on resume starts the window honestly instead.
+     *
+     * An epoch bump, so every cache keyed on `{epoch, n}` — pyramids, x
+     * indexes, scatter grids — rebuilds, through the same invalidation a
+     * window shift already exercises.
+     */
+    clear(): void;
+    /** Append many rows in one notification. */
+    appendRows(rows: readonly Readonly<Record<string, number | string>>[]): void;
+    private _ensureColumn;
+    /** Drop the oldest points once a window is exceeded by its slack.
+     * Returns true when history moved. */
+    private _enforceWindow;
+    column(key: string): ResolvedColumn | null;
+    /** Hear about appends and window shifts. Returns the unsubscribe. */
+    subscribe(listener: (change: ChartDataChange) => void): () => void;
+    private _notify;
+}
+interface PyramidLevel {
+    /** points per block at this level: BASE << k */
+    size: number;
+    mins: Float64Array;
+    maxs: Float64Array;
+    /** blocks currently valid (the last one may cover a partial tail, and is
+     * correct *for its coverage* — see extend) */
+    blocks: number;
+}
+export interface Pyramid {
+    builtN: number;
+    epoch: number;
+    levels: PyramidLevel[];
+}
+/**
+ * The pyramid for a numeric column, built on first use and extended in
+ * place as the column grows. An epoch change rebuilds from scratch —
+ * history moved, and no incremental repair is worth the bug surface.
+ */
+export declare function pyramidFor(col: NumericColumn): Pyramid;
+/** Reusable min/max result — renderers call this per pixel column, and a
+ * fresh object per call would be a million allocations a second. */
+export interface MinMax {
+    min: number;
+    max: number;
+}
+/**
+ * Exact min/max over `[i0, i1)`, in O(log) block reads plus ≤15 raw points
+ * at each edge: greedy decomposition over the aligned blocks that fit, the
+ * way a sparse segment tree answers range queries. `out.min > out.max`
+ * means the range held no finite value (a gap).
+ */
+export declare function minMaxRange(pyr: Pyramid, values: ArrayLike<number>, i0: number, i1: number, out: MinMax): void;
+export interface XIndex {
+    builtN: number;
+    epoch: number;
+    /** non-decreasing so far — what makes binary search legal */
+    sorted: boolean;
+    /** evenly spaced so far — what makes column→index arithmetic */
+    uniform: boolean;
+    x0: number;
+    dx: number;
+    min: number;
+    max: number;
+}
+/** The sortedness/uniformity/extent record for an x column, incremental
+ * like the pyramid. */
+export declare function xIndexFor(col: NumericColumn): XIndex;
+/** First index whose value is >= x, over a sorted column. */
+export declare function lowerBound(values: ArrayLike<number>, n: number, x: number): number;
+/** First index whose value is > x, over a sorted column. */
+export declare function upperBound(values: ArrayLike<number>, n: number, x: number): number;
+/**
+ * The index range `[i0, i1)` of points whose x falls in `[xMin, xMax]`,
+ * widened by one point each side so a line entering the viewport draws its
+ * crossing segment. Arithmetic for a uniform column, O(log n) for a sorted
+ * one, everything for the rest.
+ */
+export declare function visibleIndexRange(idx: XIndex, values: ArrayLike<number>, n: number, xMin: number, xMax: number): [number, number];
+/**
+ * The nearest index to x, for tooltip snapping. Sorted columns answer in
+ * O(log n); unsorted in O(n) — scatter tooltips over huge unsorted data can
+ * live with the miss being approximate instead.
+ */
+export declare function nearestIndex(idx: XIndex, values: ArrayLike<number>, n: number, x: number): number;
+/**
+ * Cumulative tops for a stack: `tops[j][i]` is the sum of layers `0..j` at
+ * index `i`, NaN treated as 0 so one series' gap does not knock a hole in
+ * the layers above it. The arrays are fresh per build; the caller caches by
+ * its own version key and hands each layer's array back through
+ * `pyramidFor`-compatible columns (a fresh array is its own host).
+ */
+export declare function buildStackTops(layers: readonly ArrayLike<number>[], n: number): Float64Array[];
+export {};
+//# sourceMappingURL=data.d.ts.map

package/dist/charts/data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data.d.ts","sourceRoot":"","sources":["../../src/charts/data.ts"],"names":[],"mappings":"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"}