@k2b/ui 0.49.0 → 0.51.0

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

@@ -0,0 +1,20 @@
+import { map } from "./map";
+import { bar, barGauge, boxplot, donut, gauge, heatmap, histogram, line, pie, scatter, sparkline, stat, stateTimeline } from "./svg-renderers";
+export { map } from "./map";
+export * from "./svg-renderers";
+export declare const charts: {
+    readonly scatter: typeof scatter;
+    readonly line: typeof line;
+    readonly bar: typeof bar;
+    readonly pie: typeof pie;
+    readonly donut: typeof donut;
+    readonly sparkline: typeof sparkline;
+    readonly histogram: typeof histogram;
+    readonly boxplot: typeof boxplot;
+    readonly gauge: typeof gauge;
+    readonly barGauge: typeof barGauge;
+    readonly stat: typeof stat;
+    readonly heatmap: typeof heatmap;
+    readonly map: typeof map;
+    readonly stateTimeline: typeof stateTimeline;
+};

package/dist/types/charts/core/termination.test-fixture.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,5 @@
+/** Conservative proportional-font advances in em, shared by DOM-free SVG label layout.
+ * Wide glyphs retain their natural shape; fitting removes whole code points instead of stretching text.
+ */
+export declare function chartTextWidth(text: string, size: number): number;
+export declare function fitChartText(text: string, width: number, size: number): string;

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

@@ -0,0 +1,20 @@
+import type { chartRenderers } from "./registry";
+/** UI-owned kind union, derived from the renderer registry. */
+export type ChartKind = keyof typeof chartRenderers;
+export declare const chartDatumRoles: readonly ["point", "item", "bin", "box", "outlier", "value", "cell", "interval"];
+export type ChartDatumRole = (typeof chartDatumRoles)[number];
+/** Renderer metadata. Anchors use the containing SVG's coordinate space. */
+export type ChartDatum = {
+    index: number;
+    seriesIndex?: number;
+    role: ChartDatumRole;
+    label?: string;
+    anchor: [number, number];
+    grid?: [number, number];
+    values: {
+        key: string;
+        value: string | number;
+        formatted?: string;
+    }[];
+};
+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,226 @@
+/** 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;
+    compare?: {
+        label: string;
+        data: (number | null)[];
+    };
+    xAxis?: Pick<ChartDescriptionAxis, "label"> & {
+        ordered?: boolean;
+    };
+    yAxis?: ChartDescriptionAxis;
+    colorByBar?: boolean;
+    showValues?: boolean;
+    legend?: boolean;
+    references?: Reference[];
+} | {
+    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[];
+};
+/** 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

@@ -1,5 +1,8 @@
 /**
- * Pure chart renderers that share the `Chart` component's drawing without its Solid wrapper, for hosts that draw
- * SVG themselves, such as server previews and app frames.
+ * 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/BalanceSummary.d.ts

@@ -0,0 +1,29 @@
+import type { JSX } from "solid-js";
+export type BalanceSummaryProps = {
+    /** The balance at the start of the period. */
+    start: number;
+    /** Money that came in during the period, as an amount (the sign is ignored). */
+    in: number;
+    /** Money that went out during the period, as an amount (the sign is ignored). */
+    out: number;
+    /** ISO 4217 currency code, e.g. `"EUR"`. */
+    currency: string;
+    /** Explicit locale override; defaults to the inherited render locale. */
+    locale?: string;
+    /** Fixed fraction digits. Defaults to whole amounts, or cents when whole amounts would not add up. */
+    decimals?: number;
+    /** Replaces the words "Start", "End", "in" and "out". */
+    labels?: {
+        start?: string;
+        end?: string;
+        in?: string;
+        out?: string;
+    };
+    class?: string;
+};
+/**
+ * One line from the start of a period to its end: "Start 18,800 € + ↙ 29,260 € − ↗ 29,520 € = End 18,540 €". In and
+ * out show their direction with `FlowAmount`; start and end are balances and keep their sign.
+ */
+export declare function BalanceSummary(props: BalanceSummaryProps): JSX.Element;
+export default BalanceSummary;

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

@@ -1,118 +1,20 @@
-import type { MapViewport } from "@k2b/stdlib";
-import { charts } from "@k2b/stdlib";
-import type { JSX } from "solid-js";
-import { type BarChartOptions } from "./chart-bar";
-import type { ChartCursor } from "./chart-cursor";
-import { type ChartDatumRef, type ChartKind, type ChartSelection, type ChartTooltipFormatter } from "./chart-inspection-core";
-import { type StateTimelineChartOptions, type StateTimelineDomain } from "./chart-state-timeline";
-/**
- * Chart — minimal Solid wrapper around `stdlib.charts`.
- *
- * **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
- * stdlib chart function — `kind: "line"` brings in exactly the params
- * `charts.line` expects, `kind: "bar"` brings in `charts.bar`'s, etc.
- * Options stay aligned with stdlib 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.
- * If stdlib gains a new option, it's automatically available at every
- * callsite.
- *
- * **Theming.** stdlib charts 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 chart kinds shipped by `stdlib.charts`. */
-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]: {
-        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;
-    } & (K extends "map" ? {
-        /** Target when zooming in from the world view. Defaults to Europe (50, 10). */
-        zoomFocus?: Pick<MapViewport, "latitude" | "longitude">;
-    } : {}) & (K extends "line" ? {
-        /** Largest connected X distance; positive, finite, without area/errorBand fills. */ maxGap?: number;
-        /** Wrap the legend above the plot inside the caller's total chart height. Requires legend=true. */
-        legendPlacement?: "top-start";
-    } : {}) & (K extends "stateTimeline" ? StateTimelineChartOptions : K extends "bar" ? BarChartOptions : Omit<Parameters<(typeof charts)[K]>[0], "width" | "height" | "inspect">);
-}[ChartKind];
-/** Pure renderer options: component layout, events and inspection are configured elsewhere. */
-export type ChartRenderOptions = {
-    [K in ChartKind]: Omit<Extract<ChartProps, {
-        kind: K;
-    }>, "class" | "style" | "labels" | "interactive" | "onSelect" | "selected" | "tooltip" | "cursor" | "legendPlacement">;
-}[ChartKind];
-/** Keep the fixed 28-unit bar-gauge rows inside the shared SSR/browser coordinate space. */
-export declare const chartRenderHeight: (props: ChartRenderOptions) => number;
-/**
- * Internal — strips wrapper-only keys from props and forwards the
- * rest (plus logical size) to `charts[kind]`. The `any` is the
- * price for dispatching one function call across 14 different option
- * types; an explicit per-kind switch would type it but balloon the
- * component for no runtime benefit.
- */
-export declare const renderChartSvg: (props: ChartProps, width: number, height: number, mapViewport?: MapViewport, timelineViewport?: StateTimelineDomain) => string;
-declare const Chart: (props: ChartProps) => JSX.Element;
+import { type JSX } from "solid-js";
+import { chartKinds } from "../charts/core/registry";
+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, {
+    kind: K;
+}>>;
+type ChartComponents = {
+    [Name in keyof typeof chartKinds]: (props: ChartKindProps<(typeof chartKinds)[Name]>) => JSX.Element;
+};
+declare const Chart: typeof ChartRoot & ChartComponents & {
+    Calendar: (props: Omit<Extract<ChartProps, {
+        kind: "heatmap";
+        layout: "calendar";
+    }>, "kind" | "layout">) => JSX.Element;
+};
 export default Chart;

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

@@ -23,14 +23,52 @@ export type ChartLegendEntry = {
     /** A comparison series, drawn hollow like its marks. */
     reference?: boolean;
 };
+/**
+ * The latest read of an explorer's rows, kept apart from the rows on screen. Loading and a failure keep shown rows;
+ * without rows they take the viewport's place at its height.
+ */
+export type ChartFrameRequest = {
+    status: "idle" | "loading" | "error";
+    /** A host sentence for a failure, such as "The query timed out." */
+    reason?: string;
+    /** The range being read, such as "Last 90 days"; while it differs from `range` the subtitle names it. */
+    requestedRange?: string;
+};
 export type ChartExplorerProps<T extends ChartExplorerRow> = {
     cursor?: ChartCursor;
     title: string;
     /** Level of the title heading. Defaults to 3; a chart inside a titled group of charts sits one level below it. */
     headingLevel?: 2 | 3 | 4 | 5 | 6;
     description?: JSX.Element;
-    data: ChartExplorerData<T>;
+    /** Owner actions in the header before Copy data, such as showing the query behind the chart. */
+    actions?: JSX.Element;
+    /**
+     * Rows and the prepared chart. Without `chart`, `children` draws the chart view, such as a live `<Chart>`; the
+     * table and Copy data still come from the typed rows.
+     */
+    data: ChartExplorerData<T> | {
+        rows: readonly T[];
+    };
+    /** The chart view when `data` has no prepared chart. */
+    children?: JSX.Element;
     columns: readonly ChartExplorerColumn<T>[];
+    /**
+     * The read in flight or the last one that failed. With it the explorer shows loading, empty, failure and stale
+     * data in place: the title and subtitle stay, the viewport keeps its height, and nothing moves between states.
+     */
+    request?: ChartFrameRequest;
+    /** When the shown rows were read, formatted by the host ("09:12"); named only when a newer read failed. */
+    asOf?: string;
+    /** The range the shown rows cover, such as "Last 30 days". */
+    range?: string;
+    /** Try again after a failure. Without it a failure has no button. */
+    onRetry?: () => void;
+    /**
+     * The padding of the frame around the explorer, one value or block and inline like CSS `padding` ("14px 16px").
+     * The table view then reaches the frame's left, right and bottom edges without a border of its own, and the frame
+     * keeps its height.
+     */
+    inset?: string;
     view?: "chart" | "table";
     defaultView?: "chart" | "table";
     onViewChange?: (view: "chart" | "table") => void;
@@ -61,7 +99,10 @@ export type ChartExplorerProps<T extends ChartExplorerRow> = {
      * which draws in one row and runs out of narrow columns.
      */
     legend?: readonly ChartLegendEntry[];
-    /** What the viewport shows without rows, for example while they load; defaults to "No data". */
+    /**
+     * What the viewport shows without rows; defaults to "No data". With `request`, write one sentence that says why,
+     * such as "No newsletter was sent in this period."
+     */
     empty?: JSX.Element;
     class?: string;
 };