@k2b/ui 0.50.0 → 0.52.0

package/dist/types/charts/core/treemap.d.ts

@@ -0,0 +1,45 @@
+import { type ChartOptions } from "./svg";
+export type TreemapOptions = ChartOptions & {
+    groups: string[];
+    legend?: boolean;
+    data: {
+        label: string;
+        group: string;
+        value: number;
+    }[];
+    locale?: string;
+    format?: (value: number) => string;
+    displayWidth?: number;
+};
+export declare function treemapLayout(spec: TreemapOptions, size?: {
+    width: number;
+    height: number;
+}): {
+    width: number;
+    height: number;
+    total: number;
+    cells: ({
+        label: string;
+        group: string;
+        value: number;
+        index: number;
+    } & {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    })[];
+    header: {
+        svg: string;
+        height: number;
+    };
+    legend: {
+        label: string;
+        x: number;
+        row: number;
+        index: number;
+    }[];
+    legendTop: number;
+    plotHeight: number;
+};
+export declare function renderTreemapSvg(spec: TreemapOptions): string;

package/dist/types/charts/core/types.d.ts

@@ -17,15 +17,4 @@ export type ChartDatum = {
         formatted?: string;
     }[];
 };
-/** Serializable number presentation, compatible with the editor's NumberFormat contract. */
-export type ChartNumberFormat = {
-    style?: "number" | "percent" | "currency";
-    currency?: string;
-    unit?: string;
-    decimals?: number;
-    compact?: boolean;
-};
-export type ChartDateFormat = {
-    date: "day" | "minute" | "second";
-};
-export type ChartFormat = ChartNumberFormat | ChartDateFormat;
+export type { ChartDateFormat, ChartFormat, ChartNumberFormat } from "../description";

package/dist/types/charts/core/waterfall.d.ts

@@ -0,0 +1,68 @@
+import type { ChartDatum } from "./types";
+export type WaterfallOptions = {
+    start: {
+        label: string;
+        value: number;
+    };
+    steps: {
+        label: string;
+        value: number;
+    }[];
+    end: {
+        label: string;
+    };
+    title?: string;
+    subtitle?: string;
+    className?: string;
+    /** Formats balances and absolute changes. */
+    format?: (value: number) => string;
+    locale?: string;
+    /** Displayed width in CSS pixels; defaults to the SVG width. Stretching hosts pass their layout width. */
+    displayWidth?: number;
+};
+export type WaterfallBar = {
+    label: string;
+    value: number;
+    from: number;
+    to: number;
+    total: boolean;
+};
+/** Totals rest on zero; each change starts at the previous running balance. */
+export declare function waterfallLayout(spec: WaterfallOptions, size: {
+    width: number;
+    height: number;
+}): {
+    bars: WaterfallBar[];
+    balance: number;
+    scale: {
+        domain: [number, number];
+        ticks: number[];
+    };
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+    slot: number;
+    ratio: number;
+    project: (value: number) => number;
+    format: {
+        (value: number): string;
+        (value: number | bigint): string;
+        (value: number | bigint | Intl.StringNumericLiteral): string;
+    };
+    amount: (bar: WaterfallBar) => string;
+    datum: (bar: WaterfallBar, index: number, center: number, formattedAmount: string) => ChartDatum;
+};
+export type WaterfallLayout = ReturnType<typeof waterfallLayout>;
+/** Pure SVG, including presentation attributes for PDF and hosts outside .k2b-ui. */
+export declare function renderWaterfallSvg(spec: WaterfallOptions & {
+    width: number;
+    height: number;
+    inspect?: boolean;
+}, responsive?: boolean): string;
+/** Draw the geometry already reserved by a host before its drawing module loads. */
+export declare function renderWaterfallLayoutSvg(spec: WaterfallOptions & {
+    width: number;
+    height: number;
+    inspect?: boolean;
+}, g: WaterfallLayout, responsive?: boolean): string;

package/dist/types/charts/description.d.ts

@@ -0,0 +1,289 @@
+/** JSON number formatting. Functions belong to the rendering host, never the saved description. */
+export type ChartNumberFormat = {
+    style?: "number" | "percent" | "currency";
+    currency?: string;
+    unit?: string;
+    decimals?: number;
+    compact?: boolean;
+};
+export type ChartDateFormat = {
+    date: "day" | "minute" | "second";
+};
+export type ChartFormat = ChartNumberFormat | ChartDateFormat;
+export type ChartLimits = {
+    maxSeries: number;
+    maxValues: number;
+    maxMarks: number;
+};
+export type ChartDescriptionAxis = {
+    label?: string;
+    domain?: number[];
+    ticks?: number;
+    scale?: "linear" | "log";
+    format?: ChartFormat;
+};
+type Reference = {
+    value: number | string;
+    axis?: "x" | "y";
+    label?: string;
+    style?: "solid" | "dashed" | "dotted";
+    tone?: "neutral" | "info" | "success" | "warning" | "danger";
+};
+type Threshold = {
+    value: number;
+    label?: string;
+};
+type Series<N> = {
+    label?: string;
+    data: {
+        x: N | string;
+        y: N;
+    }[];
+    role?: "reference";
+};
+type Common = {
+    title: string;
+    subtitle?: string;
+    tooltip?: {
+        label?: string;
+        format?: ChartNumberFormat;
+    };
+};
+type Variants<N> = {
+    kind: "waterfall";
+    start: {
+        label: string;
+        value: number;
+    };
+    steps: {
+        label: string;
+        value: number;
+    }[];
+    end: {
+        label: string;
+    };
+    format?: ChartNumberFormat;
+} | {
+    kind: "area";
+    layout: "stacked";
+    normalize?: boolean;
+    x: (number | string)[];
+    series: {
+        label: string;
+        data: (number | null)[];
+    }[];
+    legend?: boolean;
+    format?: ChartNumberFormat;
+} | {
+    kind: "bar";
+    data: {
+        label: string;
+        value: N;
+    }[];
+    x?: string[];
+    series?: {
+        label: string;
+        data: (number | null)[];
+    }[];
+    layout?: "columns" | "rows" | "grouped" | "stacked";
+    normalize?: boolean;
+    share?: boolean;
+    limit?: number;
+    tone?: "in" | "out";
+    format?: ChartNumberFormat;
+    compare?: {
+        label: string;
+        data: (number | null)[];
+    };
+    xAxis?: Pick<ChartDescriptionAxis, "label"> & {
+        ordered?: boolean;
+    };
+    yAxis?: ChartDescriptionAxis;
+    colorByBar?: boolean;
+    showValues?: boolean;
+    legend?: boolean;
+    references?: Reference[];
+} | {
+    kind: "funnel";
+    data: {
+        label: string;
+        value: number | null;
+    }[];
+    format?: ChartNumberFormat;
+} | {
+    kind: "hbar";
+    series: string[];
+    rows: {
+        group?: string;
+        label: string;
+        values: (number | null)[];
+    }[];
+    legend?: boolean;
+    format?: ChartNumberFormat;
+} | {
+    kind: "line";
+    series: (Series<N> & {
+        style?: "solid" | "dashed" | "dotted";
+    })[];
+    xAxis?: ChartDescriptionAxis;
+    yAxis?: ChartDescriptionAxis;
+    legend?: boolean;
+    area?: boolean;
+    smooth?: boolean;
+    references?: Reference[];
+} | {
+    kind: "scatter";
+    series: Series<N>[];
+    xAxis?: ChartDescriptionAxis;
+    yAxis?: ChartDescriptionAxis;
+    legend?: boolean;
+    references?: Reference[];
+} | {
+    kind: "pie" | "donut";
+    data: {
+        label: string;
+        value: N;
+    }[];
+    legend?: boolean;
+    showLabels?: boolean;
+    format?: ChartNumberFormat;
+} | {
+    kind: "histogram";
+    data: N[];
+    bins?: number | number[];
+    references?: Reference[];
+} | {
+    kind: "gauge";
+    value: N;
+    min?: number;
+    max?: number;
+    label?: string;
+    unit?: string;
+    format?: ChartNumberFormat;
+    thresholds?: Threshold[];
+} | {
+    kind: "sparkline";
+    data: N[];
+    area?: boolean;
+} | {
+    kind: "boxplot";
+    data: {
+        label: string;
+        values: N[];
+    }[];
+    yAxis?: ChartDescriptionAxis;
+    references?: Reference[];
+} | {
+    kind: "heatmap";
+    layout: "calendar";
+    data: [string, N | null][];
+    scale: "sequential" | "diverging";
+    label?: string;
+    format?: ChartNumberFormat;
+    locale?: string;
+} | {
+    kind: "heatmap";
+    layout?: undefined;
+    data: {
+        x: string;
+        y: string;
+        value: N;
+    }[];
+    format?: ChartNumberFormat;
+    showValues?: boolean;
+    min?: number;
+    max?: number;
+} | {
+    kind: "barGauge";
+    data: {
+        label: string;
+        value: N;
+        min?: number;
+        max?: number;
+    }[];
+    min?: number;
+    max?: number;
+    unit?: string;
+    format?: ChartNumberFormat;
+    thresholds?: Threshold[];
+} | {
+    kind: "stat";
+    value: N;
+    format?: ChartNumberFormat;
+    unit?: string;
+    delta?: N;
+    better?: "up" | "down";
+    sparkline?: N[];
+} | {
+    kind: "treemap";
+    groups: string[];
+    data: {
+        label: string;
+        group: string;
+        value: number;
+    }[];
+    legend?: boolean;
+    format?: ChartNumberFormat;
+    locale?: string;
+} | {
+    kind: "pareto";
+    labels: [string, string];
+    data: {
+        label: string;
+        value: number;
+        prev: number;
+    }[];
+    format?: ChartNumberFormat;
+    locale?: string;
+} | {
+    kind: "bubble";
+    groups: string[];
+    data: {
+        label: string;
+        group: string;
+        x: number;
+        y: number;
+        size?: number;
+    }[];
+    xLabel: string;
+    yLabel: string;
+    sizeLabel?: string;
+    averages?: boolean;
+    legend?: boolean;
+    xFormat?: ChartNumberFormat;
+    yFormat?: ChartNumberFormat;
+    format?: ChartNumberFormat;
+    locale?: string;
+} | {
+    kind: "radar";
+    axes: string[];
+    max: number;
+    unit?: string;
+    series: {
+        label: string;
+        data: number[];
+    }[];
+    format?: ChartNumberFormat;
+    legend?: boolean;
+    locale?: string;
+};
+/** Portable chart node. Dates are ISO text and missing observations are null, never zero. */
+export type ChartDescription = Common & (Exclude<Variants<number | null>, {
+    kind: "bar";
+}> | (Omit<Extract<Variants<number | null>, {
+    kind: "bar";
+}>, "data"> & {
+    data?: {
+        label: string;
+        value: number | null;
+    }[];
+}));
+/** Validated renderer input. The portable validator normalizes null gaps to non-finite numbers for drawing. */
+export type ChartInput = Common & (Exclude<Variants<number>, {
+    kind: "stat";
+}> | (Omit<Extract<Variants<number>, {
+    kind: "stat";
+}>, "delta"> & {
+    delta: number | undefined;
+}));
+export {};

package/dist/types/charts.d.ts

@@ -2,6 +2,7 @@
  * Drawing helpers and portable chart contracts. Import the Solid Chart component from `@k2b/ui`.
  */
 export * from "./charts/core";
+export type * from "./charts/description";
 export type { ChartKindProps, ChartLabels, ChartProps, ChartRenderOptions } from "./content/Chart";
 export { type BarChartLayout, type BarChartOptions, barChartLayout, renderBarChartSvg } from "./content/chart-bar";
 export { calendarInspectionNavigation, mountCalendarScroll } from "./content/chart-calendar";

package/dist/types/content/Chart.d.ts

@@ -1,96 +1,8 @@
-import type { JSX } from "solid-js";
+import { type JSX } from "solid-js";
 import { chartKinds } from "../charts/core/registry";
-import { type ChartDrawingOptions } from "../charts/core/render";
-import type { ChartCursor } from "./chart-cursor";
-import { type ChartDatumRef, type ChartKind, type ChartSelection, type ChartTooltipFormatter } from "./chart-inspection-core";
-/**
- * Chart — Solid interaction and sizing around the portable UI chart core.
- *
- * **Live-update story.** `charts.<kind>(opts)` returns an SVG string;
- * Solid's `innerHTML` is reactive, so any time a prop (signal, store
- * slice, derived value) changes, the SVG re-renders. No manual
- * subscription, no imperative DOM patching. Trade-off: every change
- * is a full SVG re-build, not a diff — fine for dashboard cadences
- * (poll, websocket, store updates). Don't use this for 60fps streaming.
- *
- * **Sizing.** The server and browser render the same logical viewBox. CSS
- * fits Cartesian plots to the container and preserves text/marker sizes;
- * maps fit the whole world and zoom uniformly across the full plot; pies, donuts and gauges retain
- * their aspect ratio. No measurement
- * or hydration redraw is needed. The caller sizes the wrapper, for example
- * `style={{ height: "14rem" }}`. State timelines derive their default height
- * from the row count and legend via `stateTimelineHeight()`.
- *
- * **Why so thin.** The props are a discriminated union over each
- * registered core chart renderer — `kind: "line"` brings in exactly the params
- * `charts.line` expects, `kind: "bar"` brings in `charts.bar`'s, etc.
- * Options stay aligned with the core renderer without renaming. Every chart provides
- * renderer-owned inspection, tooltips and optional selection by default.
- * `interactive` adds bounded pan / zoom and reset controls to maps and state timelines.
- * When a core renderer gains an option, it is automatically available at every
- * callsite.
- *
- * **Theming.** The core renderers use `currentColor` for axes / ticks /
- * tick labels — set the wrapping element's `color` and everything
- * inherits. Series colors come from `--stdlib-chart-c1..c8` CSS
- * custom properties; override on the parent for per-chart palettes.
- *
- * ```tsx
- * <Chart kind="line" style={{ height: "12rem" }}
- *        series={[{ data: points() }]}
- *        yAxis={{ format: v => `€${v}k` }} />
- *
- * <Chart kind="donut" style={{ height: "12rem" }} data={slices()} />
- *
- * <Chart kind="sparkline" style={{ width: "6rem", height: "1.5rem" }} data={trend()} />
- *
- * <Chart kind="map" style={{ height: "16rem" }} series={locations()} interactive />
- * ```
- */
-/** All registered chart kinds. */
-export type { ChartKind } from "./chart-inspection-core";
-export type ChartLabels = Partial<{
-    empty: string;
-    series: string;
-    interactiveMap: string;
-    interactiveTimeline: string;
-    interactiveLine: string;
-    interactiveChart: string;
-    zoomIn: string;
-    zoomOut: string;
-    resetMap: string;
-    resetTimeline: string;
-}>;
-/**
- * Per-kind props: `kind` discriminator + the exact options that
- * `charts.<kind>` accepts, **minus** `width` / `height` (the wrapper
- * owns those — CSS fits a stable coordinate space to the box). Solid's
- * component model handles discriminated unions natively, so callsites
- * get full type safety.
- */
-export type ChartProps = {
-    [K in ChartKind]: Extract<ChartDrawingOptions, {
-        kind: K;
-    }> & {
-        class?: string;
-        style?: JSX.CSSProperties | string;
-        labels?: ChartLabels;
-        /**
-         * Navigation for maps and state timelines: pan, zoom and reset controls.
-         * Arrows pan; Alt+arrows inspect. Every chart shows tooltips and keyboard
-         * inspection without this prop.
-         */
-        interactive?: boolean;
-        onSelect?: (selection: ChartSelection) => void;
-        /** Controlled highlight; indices belong to this exact input snapshot. */
-        selected?: ChartDatumRef | null;
-        /** Customize the always-on tooltip with a title and labeled text rows. */
-        tooltip?: ChartTooltipFormatter;
-        /** Optional shared X cursor for line charts. */
-        cursor?: ChartCursor;
-    };
-}[ChartKind];
+import { type ChartKind, type ChartProps } from "./ChartRoot";
 export { type ChartRenderOptions, chartRenderHeight, renderChartSvg } from "../charts/core/render";
+export type { ChartKind, ChartLabels, ChartProps } from "./ChartRoot";
 declare const ChartRoot: (props: ChartProps) => JSX.Element;
 type KindProps<T> = T extends unknown ? Omit<T, "kind"> : never;
 export type ChartKindProps<K extends ChartKind> = KindProps<Extract<ChartProps, {

package/dist/types/content/ChartRoot.d.ts

@@ -0,0 +1,92 @@
+import type { JSX } from "solid-js";
+import type { ChartDrawingOptions } from "../charts/core/render";
+import type { ChartCursor } from "./chart-cursor";
+import { type ChartDatumRef, type ChartKind, type ChartSelection, type ChartTooltipFormatter } from "./chart-inspection-core";
+/**
+ * Chart — Solid interaction and sizing around the portable UI chart core.
+ *
+ * **Live-update story.** `charts.<kind>(opts)` returns an SVG string;
+ * Solid's `innerHTML` is reactive, so any time a prop (signal, store
+ * slice, derived value) changes, the SVG re-renders. No manual
+ * subscription, no imperative DOM patching. Trade-off: every change
+ * is a full SVG re-build, not a diff — fine for dashboard cadences
+ * (poll, websocket, store updates). Don't use this for 60fps streaming.
+ *
+ * **Sizing.** The server and browser render the same logical viewBox. CSS
+ * fits Cartesian plots to the container and preserves text/marker sizes;
+ * maps fit the whole world and zoom uniformly across the full plot; pies, donuts and gauges retain
+ * their aspect ratio. No measurement
+ * or hydration redraw is needed. The caller sizes the wrapper, for example
+ * `style={{ height: "14rem" }}`. State timelines derive their default height
+ * from the row count and legend via `stateTimelineHeight()`.
+ *
+ * **Why so thin.** The props are a discriminated union over each
+ * registered core chart renderer — `kind: "line"` brings in exactly the params
+ * `charts.line` expects, `kind: "bar"` brings in `charts.bar`'s, etc.
+ * Options stay aligned with the core renderer without renaming. Every chart provides
+ * renderer-owned inspection, tooltips and optional selection by default.
+ * `interactive` adds bounded pan / zoom and reset controls to maps and state timelines.
+ * When a core renderer gains an option, it is automatically available at every
+ * callsite.
+ *
+ * **Theming.** The core renderers use `currentColor` for axes / ticks /
+ * tick labels — set the wrapping element's `color` and everything
+ * inherits. Series colors come from `--stdlib-chart-c1..c8` CSS
+ * custom properties; override on the parent for per-chart palettes.
+ *
+ * ```tsx
+ * <Chart kind="line" style={{ height: "12rem" }}
+ *        series={[{ data: points() }]}
+ *        yAxis={{ format: v => `€${v}k` }} />
+ *
+ * <Chart kind="donut" style={{ height: "12rem" }} data={slices()} />
+ *
+ * <Chart kind="sparkline" style={{ width: "6rem", height: "1.5rem" }} data={trend()} />
+ *
+ * <Chart kind="map" style={{ height: "16rem" }} series={locations()} interactive />
+ * ```
+ */
+/** All registered chart kinds. */
+export type { ChartKind } from "./chart-inspection-core";
+export type ChartLabels = Partial<{
+    empty: string;
+    series: string;
+    interactiveMap: string;
+    interactiveTimeline: string;
+    interactiveLine: string;
+    interactiveChart: string;
+    zoomIn: string;
+    zoomOut: string;
+    resetMap: string;
+    resetTimeline: string;
+}>;
+/**
+ * Per-kind props: `kind` discriminator + the exact options that
+ * `charts.<kind>` accepts, **minus** `width` / `height` (the wrapper
+ * owns those — CSS fits a stable coordinate space to the box). Solid's
+ * component model handles discriminated unions natively, so callsites
+ * get full type safety.
+ */
+export type ChartProps = {
+    [K in ChartKind]: Extract<ChartDrawingOptions, {
+        kind: K;
+    }> & {
+        class?: string;
+        style?: JSX.CSSProperties | string;
+        labels?: K extends "pareto" ? [string, string] : ChartLabels;
+        /**
+         * Navigation for maps and state timelines: pan, zoom and reset controls.
+         * Arrows pan; Alt+arrows inspect. Every chart shows tooltips and keyboard
+         * inspection without this prop.
+         */
+        interactive?: boolean;
+        onSelect?: (selection: ChartSelection) => void;
+        /** Controlled highlight; indices belong to this exact input snapshot. */
+        selected?: ChartDatumRef | null;
+        /** Customize the always-on tooltip with a title and labeled text rows. */
+        tooltip?: ChartTooltipFormatter;
+        /** Optional shared X cursor for line charts. */
+        cursor?: ChartCursor;
+    };
+}[ChartKind];
+export declare const renderChartRoot: (props: ChartProps, renderChartSvg: typeof import("../charts/core/render").renderChartSvg) => JSX.Element;

package/dist/types/content/ChartSparkline.d.ts

@@ -0,0 +1,5 @@
+import { type ChartProps } from "./ChartRoot";
+/** The same chart host and SVG for stat trends, without the catalog dispatcher. */
+export declare function ChartSparkline(props: Omit<Extract<ChartProps, {
+    kind: "sparkline";
+}>, "kind">): import("solid-js").JSX.Element;

package/dist/types/content/Lightbox.d.ts

@@ -10,6 +10,8 @@ export type LightboxImage = {
     downloadUrl?: string;
     /** Actions for this image, shown before Download in the same style. */
     actions?: readonly LightboxAction[];
+    /** A small version for the thumbnail strip, shown from four images on; without it the strip loads `src`. */
+    thumbnail?: string;
 };
 type LightboxProps = {
     images: LightboxImage[];

package/dist/types/content/PdfViewer.d.ts

@@ -0,0 +1,32 @@
+import { type JSX } from "solid-js";
+import { type PdfPageSize } from "./pdf-document";
+export type PdfViewerProps = {
+    /** The PDF itself. A new value opens that document. */
+    data: Blob | ArrayBuffer;
+    /** The document's name, for the scroll area and the page images. */
+    title: string;
+    /** Without the zoom bar, always fit to the width. Defaults to `true`. */
+    zoom?: boolean;
+    /** Shows only this page (zero-based) instead of all pages one below the other. */
+    page?: number;
+    /** The first visible page is drawn; a host can drop its loading state. */
+    onReady?: () => void;
+    /** The document could not be opened, or a page could not be drawn and has no image yet. */
+    onError?: (error: unknown) => void;
+    class?: string;
+};
+/** Steps for − and + in percent; Ctrl or ⌘ with the wheel and two fingers zoom freely between the first and the last. */
+export declare const PDF_ZOOM_STEPS: readonly [25, 50, 75, 100, 125, 150, 200, 300];
+/** The next zoom step above or below `percent`; at either end it stays there. */
+export declare const nextPdfZoomStep: (percent: number, direction: 1 | -1) => number;
+/**
+ * The page width most pages share, at a tie the first page's. "Width" fits every page to the area, so a landscape page
+ * among portrait ones never scrolls sideways; percentages and fixed zoom follow this common width.
+ */
+export declare const commonPageWidth: (pages: readonly PdfPageSize[]) => number;
+/**
+ * A PDF drawn by pdf.js in every browser: pages as images in one scroll area, an invisible text layer over each page
+ * to select, copy, and find text, and a small zoom bar. Only pages near the view are drawn and carry text; the others
+ * keep their size, so the scroll bar is right from the start. Printing and forms stay with the browser's own viewer.
+ */
+export default function PdfViewer(props: PdfViewerProps): JSX.Element;