@webority/ui-elements 0.148.0 → 0.150.0

package/types/chartAdapter.d.ts

@@ -0,0 +1,160 @@
+import type { ECElementEvent, EChartsCoreOption } from "echarts/core";
+import type { NormalizedSpec } from "./chartSpec.ts";
+import { waterfallBars } from "./chartSpec.ts";
+/** The resolved colours and motion a chart is drawn in. */
+export interface ChartTheme {
+    palette: string[];
+    neutral: string;
+    seq: string[];
+    surface: string;
+    grid: string;
+    axis: string;
+    label: string;
+    text: string;
+    textBody: string;
+    textMuted: string;
+    shadow: string;
+    font: string;
+    dark: boolean;
+    reducedMotion: boolean;
+}
+/** The drawing surface in px. */
+export interface ChartSize {
+    width: number;
+    height: number;
+}
+/** The zoom window a long line keeps across a redraw, in percent of its data. */
+export interface ZoomWindow {
+    start: number;
+    end: number;
+}
+/** What the element asks a draw to show: the hidden legend keys, the renderer and the motion. */
+export interface ChartHandleView {
+    hidden: Set<string>;
+    renderer: "svg" | "canvas";
+    animation?: boolean;
+    zoom?: ZoomWindow | null;
+}
+/** The engine's callback parameter for a mark, as the tooltip and label formatters read it. */
+export interface EngineParams {
+    name: string;
+    value: unknown;
+    percent: number;
+    color: string;
+    dataIndex: number;
+    seriesIndex: number;
+    dataType: string;
+    componentType: string;
+    data: {
+        row?: number;
+    } | undefined;
+}
+/** The handle the element drives: the mounted engine instance, owned by mountChart. */
+export interface ChartHandle {
+    renderer: "svg" | "canvas";
+    render(spec: NormalizedSpec, theme: ChartTheme, size: ChartSize, view: ChartHandleView, options?: {
+        replace?: boolean;
+    }): void;
+    focusPoint(seriesIndex: number, row: number): void;
+    clearFocus(): void;
+    resize(): void;
+    onSelect(listener: (hit: {
+        seriesIndex: number;
+        dataIndex: number;
+    }) => void): void;
+    onFinished(listener: () => void): void;
+    dispose(): void;
+}
+type WaterfallBar = ReturnType<typeof waterfallBars>[number];
+/** The ECharts option a chart is drawn with: what buildOption returns and setOption takes. */
+export type ChartOption = EChartsCoreOption;
+/** Below this width (the chart's own, not the page's) labels thin out and the donut drops its outside labels. */
+export declare const COMPACT_WIDTH: number;
+/** `color` at `a` opacity, for washes and shadows. A colour this cannot read comes back as it was. */
+export declare function alpha(color: unknown, a: number): string;
+/** `a` blended `t` (0 to 1) of the way toward `b`: a tint of a series colour on the surface. */
+export declare function mixColours(a: string, b: string, t: number): string;
+/** The ink that reads on `fill`: the theme's text or its surface, whichever contrasts more. */
+export declare function readableInk(fill: unknown, theme: ChartTheme): string;
+/**
+ * The ECharts option for a spec. Pure: the same inputs always give the same option, which is
+ * built whole every time (a merge would keep the previous theme's colours wherever a field was
+ * left out).
+ *
+ * @param spec normalised spec (chartSpec.normalizeSpec)
+ * @param theme resolved colours and motion: { palette, neutral, surface, grid, axis,
+ *   label, text, textBody, shadow, font, dark, reducedMotion }
+ * @param size the drawing surface in px
+ * @param view { hidden: Set<string>, renderer: 'svg'|'canvas', animation?: boolean }
+ */
+export declare function buildOption(spec: NormalizedSpec, theme: ChartTheme, size: ChartSize, view: ChartHandleView): ChartOption;
+/** The calendar's cell size, and the first day it shows: as many whole weeks as fit the width, newest kept. */
+export declare function calendarLayout(spec: NormalizedSpec, size: ChartSize): {
+    cell: number;
+    from: number;
+    to: number;
+};
+export declare function waterfallBreak(bars: WaterfallBar[]): {
+    start: number;
+    end: number;
+} | null;
+/**
+ * The axisLabel fragment a column chart's category names take in a labelFit mode. `all` keeps every name
+ * (wrap or turn, as a waterfall does) and hides none; `auto` keeps the engine's own overlap hiding.
+ */
+export declare function categoryLabelFit(mode: "auto" | "all" | "rotate" | "ellipsis" | undefined, names: string[], plotWidth: number): Record<string, unknown>;
+/**
+ * How a waterfall labels its steps in the width it has. Every step keeps its name: a name wraps
+ * inside its own slot while its longest word fits there, and turns on its side when even one word
+ * does not. The values over the bars print only when every one fits its slot; otherwise none do,
+ * and the tooltip carries them.
+ */
+export declare function waterfallLabels(names: string[], values: string[], plotWidth: number): {
+    nameSize: number;
+    valueSize: number;
+    category: Record<string, unknown>;
+    showValues: boolean;
+};
+/** A treemap's parents in order, each with its row indexes largest first: the order the engine's tree is built in. */
+export declare function treemapGroups(spec: NormalizedSpec): Array<{
+    name: string;
+    rows: number[];
+}>;
+export declare function sankeyDepths(spec: NormalizedSpec): Map<string, number>;
+/**
+ * The least-squares line through points, as its two end points, or null with fewer than two
+ * distinct x. The ends are cut where the line leaves the points' own y range, so it never pulls the
+ * axis past the data.
+ */
+export declare function trendLine(points: Array<[number, number]>): Array<[number, number]> | null;
+/**
+ * Where a spec's row sits in the engine, for the keyboard: { seriesIndex, dataIndex } as the
+ * engine's own actions take them. `series` is the index into spec.series, `row` the data row.
+ */
+export declare function locatePoint(spec: NormalizedSpec, series: number, row: number): {
+    seriesIndex: number;
+    dataIndex: number;
+    dataType?: string;
+    tip?: boolean;
+};
+/** The inverse: what an engine click means in spec terms, { series, row }, or null for a mark that is no row. */
+export declare function rowOf(spec: NormalizedSpec, p: ECElementEvent): {
+    series: number;
+    row: number;
+} | null;
+/**
+ * A PNG of the chart as a data URL, drawn on a throwaway canvas at `pixelRatio` with the surface
+ * colour behind it. The SVG renderer cannot hand out a PNG, and a canvas copy keeps the page's
+ * web font, which an SVG drawn into an image would lose.
+ */
+export declare function renderPng(spec: NormalizedSpec, theme: ChartTheme, size: ChartSize, view: ChartHandleView, { pixelRatio }?: {
+    pixelRatio?: number;
+}): string;
+/**
+ * Start the engine in `container`. The handle is all the element ever calls: draw, point the
+ * keyboard at a data point, resize, report clicks and the end of drawing, and stop.
+ */
+export declare function mountChart(container: HTMLElement, { renderer }: {
+    renderer: "svg" | "canvas";
+}): ChartHandle;
+export {};

package/types/chartSpec.d.ts

@@ -0,0 +1,382 @@
+import type { DatePattern, FormatStyle, FormatUnit } from "./formatters.ts";
+import { compactFormatOf, formatValue } from "./formatters.ts";
+export type ChartType = "line" | "area" | "column" | "bar" | "donut" | "heatmap" | "calendar" | "funnel" | "gauge" | "waterfall" | "treemap" | "sankey" | "scatter" | "bubble" | "multiples";
+export type StackMode = "none" | "stacked" | "percent";
+export type XKind = "category" | "time" | "value";
+export type LabelFit = "auto" | "all" | "rotate" | "ellipsis";
+export type Renderer = "auto" | "svg" | "canvas";
+export type ChartState = "ready" | "loading" | "empty" | "error";
+export type ChartView = "chart" | "table";
+/** A cell of a data row: a category, a number, or a gap. */
+export type ChartRow = Record<string, string | number | null>;
+/**
+ * How a value is printed (formatters.ts).
+ */
+export type FormatSpec = {
+    /** `percent` takes a ratio, as Intl does: 0.125 shows as 12.5%. */
+    style: FormatStyle;
+    /** For currency and compact: an ISO 4217 code (three capital letters), INR when omitted. */
+    currency?: string;
+    /** What the value counts: `rupees` (default) or `paise` for money, `ms`, `s` (default), `min` or `h` for a duration. */
+    unit?: FormatUnit;
+    /** Fraction digits: fixed for currency (default 0), a cap otherwise. */
+    decimals?: number;
+    /** For `date` (default `day`, 04-Oct-2026 in the time zone of the chart (IST by default)). */
+    pattern?: DatePattern;
+};
+/** The x column: the column holding the x value (see the spec's description of each type). */
+export type XColumn = {
+    key: string;
+    kind?: XKind;
+    format?: FormatSpec;
+    label?: string;
+    labelFit?: LabelFit;
+};
+/** A value column, in the order it takes its colour. */
+export type SeriesColumn = {
+    key: string;
+    label: string;
+    format?: FormatSpec;
+};
+/** A column that names a second dimension (group, to, size). */
+export type KeyedColumn = {
+    key: string;
+    label?: string;
+    format?: FormatSpec;
+};
+/** The one value axis. */
+export type YAxis = {
+    label?: string;
+    format?: FormatSpec;
+    min?: number;
+    max?: number;
+    wholeNumbers?: boolean;
+};
+/** A gauge band: the stretch of the scale up to `upTo`. */
+export type GaugeBand = {
+    upTo: number;
+    label: string;
+};
+/**
+ * What each `type` reads from `data` (one row per mark unless noted). Every type but `multiples`
+ * draws ONE series (`series[0]` is the measure); the keys named here carry the other dimensions.
+ * - `line`, `area`, `column`, `bar`: one row per x position, one column per series.
+ * - `donut`: one row per slice, `x` names the slice.
+ * - `heatmap`: one row per cell: `x` is the column, `group` the row, `series[0]` the value.
+ * - `calendar`: one row per day: `x` (kind `time`) is the day, `series[0]` the value.
+ * - `funnel`: one row per stage, in order: `x` names the stage, `series[0]` the count.
+ * - `gauge`: one row: `series[0]` is the value on the scale `y.min` to `y.max` (default 0 to 100),
+ *   `x` optionally names it, `bands` names the stretches of the scale.
+ * - `waterfall`: the first row is the starting total, the middle rows are signed changes, the last
+ *   row is the closing total (given, and checked against the steps).
+ * - `treemap`: one row per leaf: `group` is its parent, `x` its name, `series[0]` its size.
+ * - `sankey`: one row per flow: `x` is where it starts, `to` where it ends, `series[0]` its size.
+ * - `scatter`, `bubble`: one row per point: `x` is a number, `series[0]` the y number, `group` the
+ *   optional colour group (at most 3), `size` (bubble) the area.
+ * - `multiples`: like `line`, but each series gets its own small chart under one shared x axis,
+ *   with linked tooltips. It replaces a second y axis.
+ */
+export type ChartSpec = {
+    /** `column` is vertical bars, `bar` horizontal. */
+    type: ChartType;
+    /** Required. Names the chart for assistive tech and names exported files. */
+    title: string;
+    /** One sentence read before the automatic summary. */
+    description?: string;
+    /** The rows (see above). */
+    data: ChartRow[];
+    /**
+     * The column holding the x value. `time` takes epoch ms, an ISO instant, or a "YYYY-MM-DD" day, and
+     * shows it in the time zone of the chart (IST by default). `value` (scatter and bubble only) is a number. `label` heads the table's first column.
+     * `labelFit` sets how a column chart fits its category names: `auto` (the default) hides those that overlap, `all` shows every name,
+     * `rotate` turns them, and `ellipsis` cuts each to its slot; a bar chart has the room already, so it ignores this.
+     */
+    x: XColumn;
+    /**
+     * The value columns, in the order they take colours. At most 8; every type but `line`, `area`, `column`, `bar` and
+     * `multiples` takes exactly one.
+     */
+    series: SeriesColumn[];
+    /** The second dimension: a heatmap's rows, a treemap's parents, a scatter or bubble's colour groups (at most 3). */
+    group?: KeyedColumn;
+    /** A sankey's end of each flow. */
+    to?: KeyedColumn;
+    /** A bubble's area. */
+    size?: KeyedColumn;
+    /** A scatter or bubble's straight trend line through the visible points. */
+    trend?: boolean;
+    /** Print each bar's value on it. Column and bar only; ignored on a stacked chart. */
+    valueLabels?: boolean;
+    /** A zoom slider under a line or area. Default: on above 5,000 rows. */
+    zoom?: boolean;
+    /** A gauge's named stretches, each up to a value. */
+    bands?: GaugeBand[];
+    /** For area, column and bar. Several series with `none` sit side by side (grouped columns, overlapping areas). Default `none`. */
+    stack?: StackMode;
+    /**
+     * The one value axis. There is no second axis by design: show another measure as its own chart.
+     */
+    y?: YAxis;
+    /** A dashed reference line. */
+    target?: {
+        value: number;
+        label: string;
+    };
+    /** The caption under the total in a donut's centre. Default "Total". Donut only. */
+    centerLabel?: string;
+    /** In px, the axis labels included. Default 320; a gauge 240, a calendar 200, a treemap and a sankey 340, small multiples 100 per chart. */
+    height?: number;
+    /** `loading` after a first render keeps that render on screen, dimmed, until the new data arrives. Default `ready`. */
+    state?: ChartState;
+    /** Replaces the default empty message. */
+    emptyText?: string;
+    /** Replaces the default error message. Say what the person can do. */
+    errorText?: string;
+    /** Replaces the default loading message (read aloud while the chart loads). Default "Loading chart". */
+    loadingText?: string;
+    /** `auto` draws SVG, and canvas above 5,000 points. Default `auto`. */
+    renderer?: Renderer;
+    /** IANA zone dates are read and shown in (Asia/Kolkata when omitted). */
+    timeZone?: string;
+};
+/** What normalizeSpec accepts: the valid shape, with every optional key a caller may pass. Anything else is warned and ignored. */
+export type ChartInput = ChartSpec;
+/** The spec after validation: every default filled in, every unknown value dropped. */
+export type NormalizedSpec = {
+    type: ChartType;
+    title: string;
+    description: string;
+    data: ChartRow[];
+    allData: ChartRow[];
+    x: {
+        key: string;
+        kind: XKind;
+        format?: FormatSpec;
+        label: string;
+        labelFit: LabelFit;
+    };
+    series: SeriesColumn[];
+    group: KeyedColumn | null;
+    to: KeyedColumn | null;
+    size: KeyedColumn | null;
+    trend: boolean;
+    zoom: boolean;
+    bands: GaugeBand[];
+    stack: StackMode;
+    y: {
+        label: string;
+        format?: FormatSpec;
+        min?: number;
+        max?: number;
+        wholeNumbers: boolean;
+    };
+    target: {
+        value: number;
+        label: string;
+    } | null;
+    centerLabel: string;
+    valueLabels: boolean;
+    height: number;
+    state: ChartState;
+    emptyText: string;
+    errorText: string;
+    loadingText: string;
+    renderer: Renderer;
+    timeZone: string;
+    otherIndex: number;
+};
+export type NormalizeResult = {
+    spec: NormalizedSpec;
+    problem: null;
+} | {
+    spec: null;
+    problem: string;
+};
+export type TooltipRow = {
+    color?: string;
+    line?: boolean;
+    label: string;
+    value: string;
+};
+export type TooltipModel = {
+    title: string;
+    rows: TooltipRow[];
+    foot: string;
+};
+export type TableRow = {
+    head: string;
+    cells: string[];
+};
+export type TableModel = {
+    caption: string;
+    head: string[];
+    rows: TableRow[];
+    total: number;
+    truncated: boolean;
+};
+export type ChartColours = {
+    palette: string[];
+    neutral: string;
+    seq?: string[];
+};
+export type Focus = {
+    index: number;
+    series: number;
+};
+export type HeatBucket = {
+    from: number;
+    to: number;
+    colour: string | undefined;
+};
+export type WaterfallBar = {
+    index: number;
+    total: boolean;
+    value: number;
+    from: number;
+    to: number;
+    level: number;
+};
+export declare const CHART_TYPES: readonly ChartType[];
+export declare const STACK_MODES: readonly StackMode[];
+export declare const X_KINDS: readonly XKind[];
+export declare const RENDERERS: readonly Renderer[];
+export declare const CHART_STATES: readonly ChartState[];
+export declare const CHART_VIEWS: readonly ChartView[];
+export declare const MAX_SERIES: number;
+export declare const MAX_SLICES: number;
+/** Colour groups a scatter or bubble keeps apart: past three, pairs of hues stop being tellable apart. */
+export declare const MAX_GROUPS: number;
+/** Above this many points `auto` draws on canvas, which stays fast where SVG would not. */
+export declare const CANVAS_POINT_THRESHOLD: number;
+export declare const DEFAULT_HEIGHT: number;
+/** Rows the table shows; the CSV always carries every row. */
+export declare const TABLE_ROW_LIMIT: number;
+export declare const OTHER_LABEL: string;
+export declare const DEFAULT_EMPTY_TEXT: string;
+export declare const DEFAULT_ERROR_TEXT: string;
+export declare const DEFAULT_LOADING_TEXT: string;
+/** True for a type that draws exactly one series. */
+export declare const isSingleSeries: (type: ChartType) => boolean;
+/** Warn once when `value` is outside `allowed`; nullish means omitted and passes. */
+export declare function checkValue(path: string, value: unknown, allowed: readonly unknown[]): void;
+/**
+ * Validate a spec and return the shape the element and adapter work from. Never throws: a spec
+ * the chart cannot draw comes back with `problem` set, a message fit to show the person, and the
+ * reason goes to the console. Every value a caller got wrong is warned once.
+ *
+ * @param raw the caller's spec, unchecked
+ */
+export declare function normalizeSpec(raw: unknown): NormalizeResult;
+/** The value of a series at a row: a finite number, or null for a gap. */
+export declare function valueAt(spec: NormalizedSpec, seriesKey: string, index: number): number | null;
+/** Whether any series has a number to plot: a ready spec without one is shown as empty. A gauge draws a missing value as "-". */
+export declare function hasValues(spec: NormalizedSpec): boolean;
+/** The x value of a row as text: a category as given (or through x.format), a time in the zone of the chart. */
+export declare function xText(spec: NormalizedSpec, index: number): string;
+/** Epoch ms of a time row's x value (NaN when it cannot be read). */
+export declare function xInstant(spec: NormalizedSpec, index: number): number;
+/** A row's group (heatmap row, treemap parent, scatter colour group) as text. */
+export declare function groupText(spec: NormalizedSpec, index: number): string;
+/** A sankey row's end as text. */
+export declare function toText(spec: NormalizedSpec, index: number): string;
+/** The distinct groups in the order they first appear: also each group's colour slot. */
+export declare function groupNames(spec: NormalizedSpec): string[];
+/** How many points the chart plots: what `auto` weighs against the canvas threshold. */
+export declare function pointCount(spec: NormalizedSpec): number;
+/** The renderer to draw with. */
+export declare function resolveRenderer(spec: NormalizedSpec): "svg" | "canvas";
+/** Identity of each legend entry: series keys, slice names for a donut, group names for a scatter. */
+export declare function legendKeys(spec: NormalizedSpec): string[];
+/** What each legend entry says: the series' label, or the slice or group itself. */
+export declare function legendLabels(spec: NormalizedSpec): string[];
+/** Whether a row is switched off through the legend (a donut's slice, a scatter's group). */
+export declare function rowHidden(spec: NormalizedSpec, index: number, hidden: Set<string>): boolean;
+/** Each visible series' share of its row, as a ratio (0 to 1), for a percent stack. */
+export declare function percentShares(spec: NormalizedSpec, hidden: Set<string>): Record<string, number | null>[];
+/** "Sun, 04-Oct-2026": the weekday in the zone, then the date. */
+export declare function weekdayDate(instant: number, timeZone?: string): string;
+export declare const share: (part: number | null, whole: number | null | undefined) => string;
+/**
+ * The five equal-width buckets a heatmap and a calendar colour by, lowest first: `{ from, to,
+ * colour }`, where each bucket takes `from` up to (not including) `to` and the last takes its `to`
+ * as well. One bucket when every value is the same; none without values.
+ */
+export declare function heatBuckets(values: readonly unknown[], seq: string[]): HeatBucket[];
+/** The colour of a value among its buckets. */
+export declare function heatColour(buckets: HeatBucket[], value: number | null): string | undefined;
+/** A funnel's stage colours: the sequential ramp from its darkest end, spread over the stages. */
+export declare function funnelColours(count: number, seq: string[]): (string | undefined)[];
+/** A gauge's reading: the band the value falls in (the last band when past them all), if any. */
+export declare function gaugeBand(spec: NormalizedSpec, value: number): GaugeBand | null;
+/** A gauge's scale: its y min and max, else 0 to 100. */
+export declare function gaugeScale(spec: NormalizedSpec): {
+    min: number;
+    max: number;
+};
+/**
+ * A waterfall's bars, one per row: the first and last rows are totals, the others signed steps.
+ * `from` and `to` are the running levels either side of the bar.
+ */
+export declare function waterfallBars(spec: NormalizedSpec): WaterfallBar[];
+/** A sankey's node colours: each start takes the next palette slot, the rest follow their largest inflow. */
+export declare function sankeyColours(spec: NormalizedSpec, palette: string[]): Map<string, string | undefined>;
+/** A treemap's totals: each parent's size in the order parents first appear. */
+export declare function treemapTotals(spec: NormalizedSpec): Map<string, number>;
+/**
+ * The colour of one row's mark, the one the tooltip's swatch shows: a palette slot, the funnel's
+ * ramp, the heatmap bucket, the gauge band, the waterfall's green or red, the neutral for Other.
+ */
+export declare function markColour(spec: NormalizedSpec, index: number, colours: ChartColours): string | undefined;
+/**
+ * What a tooltip shows for one position: a title, a row per visible series (or the slice), and a
+ * footer. Text only: renderTooltip turns it into DOM and tooltipText into a sentence.
+ *
+ * @param spec normalised spec
+ * @param index the row (slice) index
+ * @param hidden legend keys switched off
+ * @param colours the palette, the neutral colour and the sequential ramp
+ */
+export declare function tooltipModel(spec: NormalizedSpec, index: number, hidden: Set<string>, colours: ChartColours): TooltipModel;
+/** A signed figure: a plus before a rise, the true minus before a fall; `suffix` follows the number. */
+export declare function signed(value: number, format: Parameters<typeof formatValue>[1], suffix?: string): string;
+/** The colour of a donut slice: its palette slot, or the neutral for the folded Other slice. */
+export declare function sliceColour(spec: NormalizedSpec, index: number, colours: ChartColours): string | undefined;
+/** A tooltip's DOM, built with textContent only: no string from the data is ever parsed as HTML. */
+export declare function renderTooltip(model: TooltipModel): HTMLDivElement;
+/** The same content as one sentence, for the live region the keyboard drives. */
+export declare function tooltipText(model: TooltipModel): string;
+/**
+ * The data table: a caption, the column heads, and the rows as text. The first column is the x
+ * value (a row header), then one column per series, with the extra columns each type needs (a
+ * donut's share, a funnel's step rates, a heatmap's columns). At most TABLE_ROW_LIMIT rows;
+ * `truncated` says how many there are in all.
+ */
+export declare function tableModel(input: NormalizedSpec): TableModel;
+/**
+ * Every row as CSV: a byte-order mark (so a spreadsheet reads the ₹ and the Indian digits right),
+ * the column labels with their units, raw numbers (money in rupees, also when the data is in
+ * paise, and a percent ratio in percent units under its "(%)" head), dates in the time zone of the chart, CRLF line ends, and a leading = + - @ in text neutralised so a cell can
+ * never run as a formula. A heatmap, treemap, sankey, scatter and bubble write one row per
+ * mark with their group, parent, end or size beside it.
+ */
+export declare function toCsv(input: NormalizedSpec): string;
+/** The file name an export uses: the title in lower case with hyphens. */
+export declare function fileStem(spec: NormalizedSpec | null | undefined): string;
+/**
+ * The summary a screen reader hears after the title: the description, then what kind of chart
+ * it is, what it plots, how far x runs, and each series' lowest and highest value. `hidden` leaves out
+ * the legend entries switched off, so the description matches what is drawn.
+ */
+export declare function summaryText(spec: NormalizedSpec, hidden?: Set<string>): string;
+/** The y axis' tick format: the compact form of the value format, or percent for a percent stack. */
+export declare function axisFormat(spec: NormalizedSpec): ReturnType<typeof compactFormatOf>;
+/**
+ * Where the keyboard focus moves: { index, series } (series is the index into spec.series), or
+ * null when Escape clears it. Left and right walk along x (up and down on a horizontal bar chart,
+ * whose categories run down the page); the other pair steps between visible series. A donut, a
+ * funnel, a waterfall, a treemap, a sankey, a scatter and a bubble chart walk their visible marks
+ * with any arrow (a scatter in x order). A heatmap moves across its grid, and a calendar by day
+ * (up and down) and week (left and right). Home and End jump to the first and last position.
+ * Returns the focus unchanged for any other key.
+ */
+export declare function stepFocus(spec: NormalizedSpec, focus: Focus | null, key: string, hidden: Set<string>): Focus | null;

package/types/codeHighlight.d.ts

@@ -0,0 +1,25 @@
+/** The languages the block highlights; "text" shows the source as written. */
+export declare const CODE_LANGUAGES: readonly ["text", "json", "js", "cs", "sql", "bash", "http", "html", "css"];
+/** The name the block's header shows when it has no label. */
+export declare const CODE_LANGUAGE_NAMES: Readonly<Record<(typeof CODE_LANGUAGES)[number], string>>;
+/** Source longer than this is not tokenized. */
+export declare const MAX_HIGHLIGHT_CHARS = 100000;
+type Token = [string, string];
+/**
+ * Splits source into [type, text] pairs. Types: plain, comment, string, number, keyword,
+ * literal, function, type, attr, tag, variable, punct. Joining the texts gives the source back.
+ *
+ * @param code
+ * @param language One of CODE_LANGUAGES; an unknown one stays plain.
+ */
+export declare function tokenize(code: string | null | undefined, language: string): Token[];
+/**
+ * The same tokens grouped by line, so a block can draw one element per line. A token that spans
+ * lines (a block comment, a template string) is cut at each break. A trailing newline does not
+ * add an empty last line.
+ *
+ * @param code
+ * @param language
+ */
+export declare function highlightLines(code: string, language: string): Token[][];
+export {};

package/types/collapsibleSearch.d.ts

@@ -0,0 +1,7 @@
+export declare const SEARCH_OPEN_KEY = "/";
+/** Shows the field, marks the toggle expanded and focuses the input. */
+export declare function openSearch(wrap: HTMLElement): void;
+/** Folds the field back into its button, unless the field holds a value. */
+export declare function collapseSearch(wrap: HTMLElement): void;
+/** Wires every collapsible search under `root` that is not wired yet, and the "/" key once per document. */
+export declare function initCollapsibleSearch(root?: Document | Element): void;

package/types/commandShortcut.d.ts

@@ -0,0 +1,12 @@
+export declare const COMMAND_SHORTCUT_ATTRIBUTE = "data-wui-command-shortcut";
+/**
+ * Ctrl or Cmd plus key, no Alt, no Shift, no auto-repeat; key matched case-insensitively.
+ * @param event
+ * @param key
+ */
+export declare function isCommandChord(event: KeyboardEvent, key: string): boolean;
+/**
+ * For each [data-wui-command-shortcut] under root: the chord opens a command palette host or focuses a search input, and the browser's own use of the chord is stopped.
+ * @param root
+ */
+export declare function initCommandShortcuts(root: Document | Element): void;

package/types/commentText.d.ts

@@ -0,0 +1,40 @@
+import type { HttpKind } from "./server/wuiHttp.ts";
+export type CommentIntent = "post" | "reply" | "edit" | "delete" | "react";
+/** The reactions offered when the thread names none. */
+export declare const COMMENT_REACTIONS: readonly string[];
+/** What a change asks the server or the host to do. */
+export declare const COMMENT_INTENTS: readonly CommentIntent[];
+export declare const FAILED_CLIENT = "This did not go through. Refresh the page and try again.";
+export declare const FAILED_SERVER = "Something went wrong on our side. Try again in a moment.";
+/** The words of a thread. React AppCommentThread and the Razor tag helper render the same. */
+export declare const COMMENT_TEXT: Readonly<{
+    listName: "Comments";
+    empty: "No comments yet.";
+    deleted: "This comment was deleted.";
+    edited: "Edited";
+    reply: "Reply";
+    edit: "Edit";
+    delete: "Delete";
+    cancel: "Cancel";
+    save: "Save";
+    post: "Comment";
+    confirmDelete: "Delete this comment?";
+    composerLabel: "Add a comment";
+    composerPlaceholder: "Write a comment. Type @ to mention someone.";
+    replyLabel: (author: string) => string;
+    replyPlaceholder: "Write a reply";
+    editLabel: "Edit comment";
+    repliesName: (author: string) => string;
+    reactions: "Reactions";
+    addReaction: "Add a reaction";
+    pickerName: "Choose a reaction";
+    emptyBody: "Write something first.";
+    done: Readonly<{
+        post: "Comment posted.";
+        reply: "Reply posted.";
+        edit: "Comment saved.";
+        delete: "Comment deleted.";
+        react: "";
+    }>;
+    failed: Partial<Record<HttpKind, string>>;
+}>;

package/types/consentBannerGlobal.d.ts

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

package/types/consentBannerStandalone.d.ts

@@ -0,0 +1,2 @@
+export declare const THEME_DEFAULTS: Readonly<Record<string, string>>;
+export declare const CONSENT_BANNER_STANDALONE_CSS: string;

package/types/copyText.d.ts

@@ -0,0 +1,10 @@
+/** Feedback window for copy-button label/icon swap on both surfaces. */
+export declare const COPY_FEEDBACK_MS = 2000;
+/**
+ * Copy plain text to the clipboard. Tries `navigator.clipboard.writeText`, then falls
+ * back to a hidden textarea + `document.execCommand("copy")`. Never throws.
+ *
+ * @param text
+ * @returns true when the copy succeeded
+ */
+export declare function copyTextToClipboard(text: string): Promise<boolean>;

package/types/countries.d.ts

@@ -0,0 +1,3 @@
+export declare const COUNTRIES: readonly (readonly [string, string, string])[];
+export declare const dialOf: (iso: string | null | undefined) => string;
+export declare const nameOf: (iso: string | null | undefined) => string;

package/types/currency.d.ts

@@ -0,0 +1,6 @@
+export declare const DEFAULT_CURRENCY = "INR";
+export declare const CURRENCY_SYMBOLS: Readonly<Record<string, string>>;
+/** Whether `value` looks like an ISO 4217 code (three capital letters). */
+export declare const isCurrencyCode: (value: unknown) => boolean;
+/** What goes before an amount: the symbol, or the code and a space when there is no symbol. */
+export declare const currencyPrefix: (code?: string) => string;