numbl 0.4.6 → 0.4.8

package/dist-graphics/graphics/FigureView.d.ts

@@ -0,0 +1,6 @@
+import type { FigureState } from "./figuresReducer.js";
+interface FigureViewProps {
+    figure: FigureState;
+}
+export declare function FigureView({ figure }: FigureViewProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist-graphics/graphics/SurfView.d.ts

@@ -0,0 +1,18 @@
+import type { SurfTrace, Plot3Trace, Bar3Trace, Quiver3Trace, PatchTrace } from "./types.js";
+interface SurfViewProps {
+    surfTraces: SurfTrace[];
+    plot3Traces?: Plot3Trace[];
+    bar3Traces?: Bar3Trace[];
+    bar3hTraces?: Bar3Trace[];
+    quiver3Traces?: Quiver3Trace[];
+    /** 3-D patches (e.g. from trimesh(T,x,y,z)). 2-D patches are placed at z=0. */
+    patchTraces?: PatchTrace[];
+    shading?: "faceted" | "flat" | "interp";
+    colorbar?: boolean;
+    colorbarLocation?: string;
+    colormap?: string;
+    /** `axis off` hides the axes box/lines (the plotted surfaces remain). */
+    axisVisible?: boolean;
+}
+export declare function SurfView({ surfTraces, plot3Traces, bar3Traces, bar3hTraces, quiver3Traces, patchTraces, shading, colorbar, colorbarLocation, colormap, axisVisible, }: SurfViewProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist-graphics/graphics/axisLimits.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Pure computation of the current axis limits for an `AxesState`.
+ *
+ * This is the source of truth for the query form `lim = axis`: the numbl
+ * runtime reduces its accumulated plot instructions into an `AxesState` and
+ * asks this module for the limit vector. It is deliberately rendering-free
+ * (no canvas, no DOM) so numbl-core can import it.
+ *
+ * For an axis with an explicit limit, that limit is returned verbatim (a
+ * `null` bound falls back to the data-derived bound). For a fully automatic
+ * axis the data extent is computed across every trace type and padded the
+ * same way `drawPlot` pads a default 2-D view, so the reported limits track
+ * what is drawn.
+ */
+import type { AxesState } from "./figuresReducer.js";
+/** Does this axes hold any 3-D content (so limits are a 6-vector)? */
+export declare function axesIs3D(axes: AxesState): boolean;
+/**
+ * Compute the limit vector for `lim = axis`.
+ * Returns 4 elements `[xmin xmax ymin ymax]` for a 2-D view, or 6 elements
+ * `[xmin xmax ymin ymax zmin zmax]` when the axes holds 3-D content.
+ */
+export declare function computeAxisLimits(axes: AxesState): number[];

package/dist-graphics/graphics/drawPlot.d.ts

@@ -0,0 +1,2 @@
+import type { PlotTrace, ImagescTrace, PcolorTrace, ContourTrace, BarTrace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace, QuiverTrace, PatchTrace } from "./types.js";
+export declare function drawPlot(canvas: HTMLCanvasElement, traces: PlotTrace[], title?: string, xlabel?: string, ylabel?: string, legend?: string[], gridOn?: boolean, imagescTrace?: ImagescTrace, contourTraces?: ContourTrace[], colormap?: string, axisMode?: string, axisScale?: "linear" | "semilogx" | "semilogy" | "loglog", barTraces?: BarTrace[], barhTraces?: BarTrace[], errorBarTraces?: ErrorBarTrace[], boxTraces?: BoxTrace[], pieTrace?: PieTrace, heatmapTrace?: HeatmapTrace, areaTraces?: PlotTrace[], areaBaseValue?: number, pcolorTraces?: PcolorTrace[], shading?: "faceted" | "flat" | "interp", colorbar?: boolean, colorbarLocation?: string, caxis?: [number, number], colormapData?: number[][], quiverTraces?: QuiverTrace[], xlim?: [number | null, number | null], ylim?: [number | null, number | null], yDir?: "normal" | "reverse", axisVisible?: boolean, boxOn?: boolean, patchTraces?: PatchTrace[]): void;

package/dist-graphics/graphics/exportFigureHdf5.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Export a figure's data to a self-describing HDF5 file ("numbl figure HDF5
+ * layout v1"). The file holds everything needed to recreate the figure:
+ * numeric data arrays are stored as gzip-compressed datasets, and all styling /
+ * scalar metadata as attributes. The schema is documented in
+ * docs/figure-hdf5-format.md.
+ *
+ * h5wasm (the only mature in-browser HDF5 writer) is loaded lazily via dynamic
+ * import so its ~MB of JS+wasm never enters the main bundle — it is fetched the
+ * first time a user actually downloads a figure. h5wasm's browser build needs
+ * no COOP/COEP (no SharedArrayBuffer), and in Node it reads its wasm from disk.
+ *
+ * Tensors in numbl are column-major; 2-D grids (surf/imagesc/pcolor/...) are
+ * transposed to row-major [rows, cols] datasets so generic HDF5 viewers
+ * (h5web, Panoply, h5py) render them correctly without numbl conventions.
+ */
+import type { FigureState } from "./figuresReducer.js";
+export declare function exportFigureHdf5(figure: FigureState): Promise<Uint8Array>;
+/** Build the HDF5 bytes for a figure and trigger a browser download.
+ *  Browser-only (uses the DOM). `handle` is used for the default filename. */
+export declare function downloadFigureHdf5(figure: FigureState, handle: number): Promise<void>;

package/dist-graphics/graphics/figureHashTransport.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Encode/decode a figure into a URL hash fragment, for handing a figure from
+ * numbl to the figure viewer in a new tab.
+ *
+ * Why the URL and not postMessage: numbl sets COOP `same-origin` (for
+ * SharedArrayBuffer / crossOriginIsolated), which severs the opener⇄popup
+ * relationship for a cross-origin viewer tab — `window.opener` is null and the
+ * opener's window handle reports `closed`, so postMessage can't reach it. The
+ * navigation URL is the one channel that survives, so the figure rides in the
+ * hash.
+ *
+ * Payload = gzip(JSON(figure)) → base64url. JSON is made NaN/Infinity-safe with
+ * sentinels (JSON.stringify would otherwise turn them into null). Encoding is
+ * synchronous so the caller can `window.open` within the click gesture.
+ */
+import type { FigureState } from "./figuresReducer.js";
+export declare const FIGURE_HASH_KEY = "fig";
+export declare function bytesToBase64url(bytes: Uint8Array): string;
+export declare function base64urlToBytes(s: string): Uint8Array;
+/** `fig=<base64url(gzip(json))>` — append to a viewer URL after `#`. */
+export declare function encodeFigureToHash(figure: FigureState): string;
+/** Parse a figure out of a `location.hash` (or any `fig=…` string); null if
+ *  absent or malformed. */
+export declare function decodeFigureFromHash(hash: string): FigureState | null;

package/dist-graphics/graphics/figureHdf5Schema.d.ts

@@ -0,0 +1,19 @@
+/** Shared constants for the "numbl figure HDF5 layout". The on-disk schema is
+ *  documented in docs/figure-hdf5-format.md; the writer is exportFigureHdf5.ts
+ *  and the reader is importFigureHdf5.ts. Keeping these tables in one place
+ *  keeps the two directions in sync. */
+/** Version written as the root `numbl_figure_version` attribute. Bump on
+ *  incompatible schema changes. */
+export declare const FIGURE_HDF5_VERSION = 1;
+/** Per-kind fields that are flat column-major rows×cols grids — stored as
+ *  row-major `[rows, cols]` datasets (transposed on write, untransposed on
+ *  read). */
+export declare const GRID_FIELDS: Record<string, string[]>;
+/** Maps a trace's `kind` attribute to the AxesState field it belongs in.
+ *  `single` marks the one-per-axes traces (imagesc/pie/heatmap). */
+export declare const KIND_TO_CATEGORY: Record<string, {
+    field: string;
+    single?: boolean;
+}>;
+/** Trace boolean fields, stored as 0/1 int attributes; coerced back on read. */
+export declare const TRACE_BOOLEAN_FIELDS: Set<string>;

package/dist-graphics/graphics/figureUpload.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Fallback figure hand-off for figures too large to fit in a URL hash: upload
+ * the figure (as an encrypted `.h5`) to a temporary file host and pass only the
+ * download URL + decryption key to the viewer.
+ *
+ * Privacy: the figure is AES-GCM encrypted in the browser before upload, and the
+ * key travels only in the viewer URL's fragment (never sent to any server), so
+ * the host stores opaque bytes. See loadFigureFromHash for the viewer side.
+ *
+ * The uploader is pluggable (FigureUploader) — numbl's own figure-store relay
+ * (a Cloudflare Worker on a numbl.org subdomain) is the default; swap it via
+ * setFigureUploader for any service that returns its own download URL. The
+ * viewer just fetches whatever URL it's handed.
+ */
+import type { FigureState } from "./figuresReducer.js";
+/** Uploads bytes to a temporary host and resolves to a URL the viewer can GET
+ *  (cross-origin) to retrieve them. Throws on failure. */
+export type FigureUploader = (data: Uint8Array, filename: string) => Promise<string>;
+/** numbl's figure-store relay (Cloudflare Worker). See figure-store-spec.md.
+ *  Override for local/staging via: localStorage["numblFigureStoreUrl"]. */
+export declare const DEFAULT_FIGURE_STORE_URL = "https://figures.numbl.org/";
+/** Default uploader: numbl's figure-store relay. Uploads the opaque (encrypted)
+ *  bytes as a raw octet-stream body and returns the download URL from the
+ *  response `{ url }`. Until the service is deployed, this rejects and the
+ *  caller falls back to the manual download/upload message. */
+export declare const numblStoreUploader: FigureUploader;
+/** Swap the temporary-host uploader (e.g. a self-hosted service). */
+export declare function setFigureUploader(uploader: FigureUploader): void;
+/**
+ * Export the figure to an encrypted `.h5`, upload it, and return a viewer URL
+ * referencing it: `<base>#u=<download-url>&k=<key>&iv=<iv>`. Throws if the
+ * upload fails (callers fall back to manual download). Asynchronous, so the
+ * caller can't `window.open` the result directly (popup blocking) — surface the
+ * URL as a link for the user to click.
+ */
+export declare function uploadFigureForViewer(figure: FigureState, opts?: {
+    viewerUrl?: string;
+    uploader?: FigureUploader;
+}): Promise<string>;
+/**
+ * Viewer side: load a figure from a viewer URL hash. Handles both the direct
+ * (`fig=…`) and uploaded (`u=…&k=…&iv=…`) forms. Returns null if the hash
+ * carries no figure; throws if a referenced upload can't be fetched/decrypted.
+ */
+export declare function loadFigureFromHash(hash: string): Promise<FigureState | null>;

package/dist-graphics/graphics/figuresReducer.d.ts

@@ -0,0 +1,86 @@
+import type { PlotTrace, Plot3Trace, PatchTrace, SurfTrace, ImagescTrace, PcolorTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace, QuiverTrace, Quiver3Trace, PlotInstruction } from "./types.js";
+export type AxesState = {
+    holdOn: boolean;
+    traces: PlotTrace[];
+    plot3Traces: Plot3Trace[];
+    surfTraces: SurfTrace[];
+    imagescTrace?: ImagescTrace;
+    pcolorTraces: PcolorTrace[];
+    contourTraces: ContourTrace[];
+    barTraces: BarTrace[];
+    barhTraces: BarTrace[];
+    bar3Traces: Bar3Trace[];
+    bar3hTraces: Bar3Trace[];
+    errorBarTraces: ErrorBarTrace[];
+    boxTraces: BoxTrace[];
+    pieTrace?: PieTrace;
+    heatmapTrace?: HeatmapTrace;
+    quiverTraces: QuiverTrace[];
+    quiver3Traces: Quiver3Trace[];
+    areaTraces: PlotTrace[];
+    areaBaseValue: number;
+    patchTraces: PatchTrace[];
+    title?: string;
+    xlabel?: string;
+    ylabel?: string;
+    zlabel?: string;
+    shading?: "faceted" | "flat" | "interp";
+    legend?: string[];
+    gridOn?: boolean;
+    /** Axes border. Undefined/true → full rectangle (numbl's default, matching
+     *  MATLAB `box on`); false → only the left and bottom axis lines (`box off`). */
+    boxOn?: boolean;
+    colorbar?: boolean;
+    colorbarLocation?: string;
+    colormap?: string;
+    colormapData?: number[][];
+    view?: {
+        az: number;
+        el: number;
+    };
+    axisMode?: string;
+    axisScale?: "linear" | "semilogx" | "semilogy" | "loglog";
+    caxis?: [number, number];
+    /** Explicit axis limits from `axis([...])` / `xlim` / `ylim`. Each bound
+     *  may be `null`, meaning "use the data-derived bound" (partial limits). An
+     *  absent field means the whole axis is automatic. */
+    xlim?: [number | null, number | null];
+    ylim?: [number | null, number | null];
+    zlim?: [number | null, number | null];
+    /** y-axis direction: "reverse" is `axis ij` (origin at top-left). */
+    yDir?: "normal" | "reverse";
+    /** Axes lines/background visibility (`axis off` sets this false). */
+    axisVisible?: boolean;
+};
+export type FigureState = {
+    subplotGrid?: {
+        rows: number;
+        cols: number;
+    };
+    currentAxesIndex: number;
+    sgtitle?: string;
+    axes: {
+        [index: number]: AxesState;
+    };
+    /** When set, this figure is an HTML UI component (MATLAB `uihtml`): the
+     *  `html` string is rendered in an iframe instead of the axes/trace canvas.
+     *  Takes precedence over `axes`. `data` is the JSON-encoded `Data` property
+     *  (from `jsonencode`), pushed into the page's `htmlComponent`. */
+    uihtml?: {
+        id: string;
+        html: string;
+        data?: string;
+    };
+};
+export type FiguresState = {
+    currentHandle: number;
+    figs: {
+        [handle: number]: FigureState;
+    };
+};
+/** Actions accepted by the figures reducer: any PlotInstruction, plus "clear" for UI resets. */
+export type FiguresAction = PlotInstruction | {
+    type: "clear";
+};
+export declare const initialFiguresState: FiguresState;
+export declare const figuresReducer: (state: FiguresState, action: FiguresAction) => FiguresState;

package/dist-graphics/graphics/importFigureHdf5.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Read a "numbl figure HDF5 layout v1" file (see docs/figure-hdf5-format.md)
+ * back into a `FigureState` that `FigureView` can render. The inverse of
+ * exportFigureHdf5.ts. h5wasm is loaded lazily via dynamic import, same as the
+ * writer.
+ */
+import type { FigureState } from "./figuresReducer.js";
+/** Parse a numbl-figure HDF5 file into a renderable `FigureState`. */
+export declare function importFigureHdf5(bytes: Uint8Array): Promise<FigureState>;

package/dist-graphics/graphics/openInFigureViewer.d.ts

@@ -0,0 +1,26 @@
+import type { FigureState } from "./figuresReducer.js";
+/** Deployed numbl figure viewer (concept-collection). */
+export declare const DEFAULT_FIGURE_VIEWER_URL = "https://concept-collection.github.io/numbl-figure-viewer/";
+/** Resolve the viewer URL: explicit arg › localStorage dev override › default.
+ *  For local development, set in the numbl tab's console:
+ *    localStorage.setItem("numblFigureViewerUrl", "http://localhost:5173/") */
+export declare function resolveFigureViewerUrl(explicit?: string): string;
+export interface FigureViewerLink {
+    /** Viewer URL with the figure embedded in the hash, or null if too large. */
+    url: string | null;
+    /** Viewer base URL (open empty, for loading a downloaded .h5 manually). */
+    baseUrl: string;
+    /** True when the figure won't fit in a URL and must be handed over as a file. */
+    tooLarge: boolean;
+}
+/**
+ * Build the link that opens the figure viewer with `figure` embedded in the URL
+ * hash (gzip+base64url, NaN-safe — see figureHashTransport). The hash is the one
+ * channel that survives numbl's COOP isolation (postMessage to a cross-origin
+ * popup is blocked there).
+ *
+ * Pure — it opens nothing. The caller decides: open `url` in response to the
+ * user's click when it fits, or, when `tooLarge`, show an in-page message with a
+ * link to `baseUrl` so the user can open the viewer and load a downloaded .h5.
+ */
+export declare function buildFigureViewerLink(figure: FigureState, viewerUrl?: string): FigureViewerLink;

package/dist-graphics/graphics/plotHelpers.d.ts

@@ -0,0 +1,6 @@
+import type { PlotTrace } from "./types.js";
+export declare function rgbToCSS(rgb: [number, number, number]): string;
+export declare function traceColor(trace: PlotTrace, index: number): string;
+export declare function getLineDash(style: string | undefined): number[];
+export declare function generateTicks(min: number, max: number, maxTicks: number): number[];
+export declare function formatTick(v: number): string;

package/dist-graphics/graphics/plotLegend.d.ts

@@ -0,0 +1,2 @@
+import type { PlotTrace } from "./types.js";
+export declare function drawLegend(ctx: CanvasRenderingContext2D, traces: PlotTrace[], labels: string[], plotRight: number, plotTop: number): void;

package/dist-graphics/graphics/plotMarkers.d.ts

@@ -0,0 +1,2 @@
+import type { PlotTrace } from "./types.js";
+export declare function drawMarkers(ctx: CanvasRenderingContext2D, trace: PlotTrace, toCanvasX: (v: number) => number, toCanvasY: (v: number) => number, defaultColor: string): void;

package/dist-graphics/graphics/restoreNaNs.d.ts

@@ -0,0 +1,2 @@
+import type { PlotInstruction } from "./types.js";
+export declare function restoreNaNs(instr: PlotInstruction): void;

package/dist-graphics/graphics/surfColormap.d.ts

@@ -0,0 +1,2 @@
+/** Parula-inspired colormap for surface plots */
+export declare function colormapLookup(t: number): [number, number, number];