@richardmcquiston01/dashboard-widgets-toolkit 0.1.0

package/dist/scale-WlRozDCf.d.cts

@@ -0,0 +1,416 @@
+/**
+ * Widget data payloads, one shape per kind, discriminated by `kind`.
+ *
+ * The kind names are upper case to stay compatible with Maker Toolkit's
+ * `WidgetViewType` (`TEXT`, `GAUGE`, `TABLE`, `GRAPH`). `KPI`, `BAR_LIST`
+ * and `ALERT_LIST` are new. Every payload is plain JSON: strings, finite
+ * numbers, booleans, null, arrays and objects. No dates (send ISO strings),
+ * no functions, no class instances.
+ */
+/** Every widget kind, in a stable order. */
+declare const WIDGET_KINDS: readonly ["TEXT", "KPI", "GAUGE", "TABLE", "BAR_LIST", "ALERT_LIST", "GRAPH"];
+type WidgetKind = (typeof WIDGET_KINDS)[number];
+declare function isWidgetKind(value: unknown): value is WidgetKind;
+/** How a number is shown: a plain count, money, or a fraction as a percent. */
+declare const VALUE_FORMATS: readonly ["number", "currency", "percent"];
+type ValueFormat = (typeof VALUE_FORMATS)[number];
+/** A single headline value as text, e.g. "12" or "Open". */
+interface TextWidgetData {
+    readonly kind: 'TEXT';
+    readonly value: string;
+    readonly label: string;
+}
+/**
+ * A stat tile: one number, optionally compared with the previous period.
+ *
+ * `value` and `previous` are in major units for `currency` (12.5 is $12.50)
+ * and fractions for `percent` (0.25 is 25%).
+ */
+interface KpiWidgetData {
+    readonly kind: 'KPI';
+    readonly value: number;
+    /** The same measure for the previous period; null or absent for none. */
+    readonly previous?: number | null;
+    readonly format: ValueFormat;
+    /** ISO 4217 code for `currency`, e.g. "USD". Defaults to USD. */
+    readonly currency?: string;
+    readonly label: string;
+    /** Short context under the value, e.g. "Incl. shipping and tax". */
+    readonly hint?: string;
+    /** Whether a rise is good news (default true). Colours the change. */
+    readonly higherIsBetter?: boolean;
+}
+/** A value against a maximum, drawn as a meter. */
+interface GaugeWidgetData {
+    readonly kind: 'GAUGE';
+    readonly value: number;
+    readonly max: number;
+    readonly label: string;
+}
+interface TableColumn {
+    readonly label: string;
+    /** Right-aligned, tabular figures. */
+    readonly numeric?: boolean;
+}
+interface TableCell {
+    readonly text: string;
+    /** Renders the cell as a link (http, https, mailto or relative only). */
+    readonly href?: string;
+}
+interface TableWidgetData {
+    readonly kind: 'TABLE';
+    readonly columns: readonly TableColumn[];
+    /** One array of cells per row, each as long as `columns`. */
+    readonly rows: readonly (readonly TableCell[])[];
+    /** A note under the table, e.g. "and 12 more". */
+    readonly footer?: string;
+}
+interface BarListItem {
+    readonly label: string;
+    readonly value: number;
+    /** Text shown beside the bar; defaults to the formatted value. */
+    readonly display?: string;
+}
+/**
+ * Labelled horizontal bars, e.g. ratings or purchases by country. Bars are a
+ * share of `total` when it is given, otherwise of the largest value.
+ */
+interface BarListWidgetData {
+    readonly kind: 'BAR_LIST';
+    readonly items: readonly BarListItem[];
+    readonly total?: number;
+}
+interface AlertListItem {
+    readonly title: string;
+    /** Renders the title as a link (http, https, mailto or relative only). */
+    readonly href?: string;
+    /** A small square image (http, https or relative only). */
+    readonly thumbnailUrl?: string;
+    /** The short figure on the right, e.g. "2 left" or "31 views". */
+    readonly valueLabel: string;
+    /** A secondary line under the title. */
+    readonly detail?: string;
+}
+/**
+ * Things that need attention (low stock, stale listings...). `items` may be
+ * the first few of `total`; the renderer says "and N more".
+ */
+interface AlertListWidgetData {
+    readonly kind: 'ALERT_LIST';
+    readonly items: readonly AlertListItem[];
+    readonly total: number;
+    /** Shown when there is nothing to flag, e.g. "Nothing low on stock." */
+    readonly emptyText: string;
+}
+interface GraphPoint {
+    /** The category or date label on the x axis, e.g. "Oct 2026". */
+    readonly label: string;
+    readonly value: number;
+}
+interface GraphSeries {
+    readonly name: string;
+    readonly points: readonly GraphPoint[];
+}
+/** The most series a graph may carry: the categorical palette's eight slots. */
+declare const MAX_GRAPH_SERIES = 8;
+/**
+ * A bar (grouped for several series) or line chart. All series share the
+ * x labels of the first series, by position, and one y axis.
+ */
+interface GraphWidgetData {
+    readonly kind: 'GRAPH';
+    readonly series: readonly GraphSeries[];
+    readonly chartType: 'bar' | 'line';
+    readonly valueFormat: ValueFormat;
+    /** ISO 4217 code for `currency`. Defaults to USD. */
+    readonly currency?: string;
+    /** Heading for the label column in the table view, e.g. "Month". */
+    readonly xLabel?: string;
+}
+/** Any widget's data, discriminated by `kind`. */
+type WidgetData = TextWidgetData | KpiWidgetData | GaugeWidgetData | TableWidgetData | BarListWidgetData | AlertListWidgetData | GraphWidgetData;
+/** The payload type for one kind, e.g. `WidgetDataOf<'KPI'>`. */
+type WidgetDataOf<K extends WidgetKind> = Extract<WidgetData, {
+    kind: K;
+}>;
+/**
+ * A widget with nothing to show yet, with the reason as text ("No orders
+ * synced yet."). Any widget may return this instead of its kind's payload.
+ */
+interface WidgetEmptyState {
+    readonly empty: true;
+    readonly text: string;
+}
+/** What a provider or API returns for a widget: its data, or an empty state. */
+type WidgetPayload = WidgetData | WidgetEmptyState;
+/** The default text for an empty widget. */
+declare const DEFAULT_EMPTY_TEXT = "Nothing to show yet.";
+/** Builds an empty state. */
+declare function emptyWidget(text?: string): WidgetEmptyState;
+declare function isWidgetEmptyState(payload: WidgetPayload): payload is WidgetEmptyState;
+/**
+ * The empty text for a payload with nothing in it (a table with no rows, a
+ * list with no items, a graph with no points), or null when it has content.
+ * TEXT, KPI and GAUGE always have content.
+ */
+declare function emptyTextFor(payload: WidgetPayload): string | null;
+
+/** A size hint for grid layouts; renderers may map it to column spans. */
+declare const WIDGET_SIZES: readonly ["small", "medium", "large", "full"];
+type WidgetSize = (typeof WIDGET_SIZES)[number];
+/**
+ * What a widget is, independent of its data. Mirrors Maker Toolkit's
+ * `widget` table (`widget_key`, `title`, `description`, `view_type`,
+ * `roles`, `sort_order`, `active`).
+ */
+interface WidgetDefinition {
+    /** Stable, unique id. Layouts and providers are keyed by it. */
+    readonly key: string;
+    readonly title: string;
+    readonly description?: string;
+    readonly kind: WidgetKind;
+    /** Lower comes first. Default 0; ties keep definition order. */
+    readonly sortOrder?: number;
+    /** Roles allowed to see it. Absent or empty means everyone. */
+    readonly roles?: readonly string[];
+    /** False hides it from every user. Default true. */
+    readonly active?: boolean;
+    readonly defaultSize?: WidgetSize;
+}
+/**
+ * Identity helper that keeps the literal `kind` (so typed providers can be
+ * checked against it) and gives a definition its type without a cast.
+ */
+declare function defineWidget<const D extends WidgetDefinition>(definition: D): D;
+/** Definitions sorted by `sortOrder` (stable: ties keep their input order). */
+declare function sortDefinitions<D extends WidgetDefinition>(definitions: readonly D[]): D[];
+/** Whether a widget is active and visible to someone with these roles. */
+declare function isWidgetVisibleTo(definition: WidgetDefinition, roles: readonly string[] | undefined): boolean;
+
+/**
+ * Number formatting via `Intl`, with an injectable locale (undefined uses
+ * the runtime's default), plus KPI period-over-period deltas.
+ */
+
+type Locale = string | readonly string[] | undefined;
+interface FormatOptions {
+    readonly locale?: Locale;
+    /** ISO 4217 code for `currency`. Default "USD". */
+    readonly currency?: string;
+    /** "1.2K" style, for axis ticks. */
+    readonly compact?: boolean;
+}
+declare const DEFAULT_CURRENCY = "USD";
+/**
+ * Formats `value` as a count ("1,284"), money ("$12.50", major units) or a
+ * percent ("25%" from 0.25).
+ */
+declare function formatValue(value: number, format: ValueFormat, options?: FormatOptions): string;
+/** A plain count, e.g. "1,284". */
+declare function formatCount(value: number, locale?: Locale): string;
+/** `part` as a whole percentage of `total` (0 when total is 0 or less). */
+declare function shareOf(part: number, total: number): number;
+/**
+ * Change from `previous` to `current` in percent (unrounded), or null when
+ * there is nothing to compare: no previous value, or a previous of 0.
+ */
+declare function percentChange(current: number, previous: number | null | undefined): number | null;
+/**
+ * "+12%", "-8%", "±0%". Below 10% one decimal is kept ("+2.5%"), so small
+ * changes don't round away.
+ */
+declare function formatPercentChange(change: number, locale?: Locale): string;
+type DeltaDirection = 'up' | 'down' | 'flat';
+type DeltaSentiment = 'good' | 'bad' | 'neutral';
+interface KpiDelta {
+    /** Percent change, unrounded. */
+    readonly percent: number;
+    readonly direction: DeltaDirection;
+    /** Direction combined with whether higher is better. */
+    readonly sentiment: DeltaSentiment;
+    /** "+12%" */
+    readonly text: string;
+    /** "+12% vs previous period" */
+    readonly description: string;
+}
+interface KpiDeltaOptions {
+    /** Default true. */
+    readonly higherIsBetter?: boolean;
+    readonly locale?: Locale;
+    /** What the change is against. Default "previous period". */
+    readonly comparisonLabel?: string;
+}
+/** The default comparison wording in delta descriptions. */
+declare const DEFAULT_COMPARISON_LABEL = "previous period";
+/**
+ * The period-over-period change for a KPI, or null when it can't be worked
+ * out (no previous value, or a previous of 0).
+ */
+declare function kpiDelta(current: number, previous: number | null | undefined, options?: KpiDeltaOptions): KpiDelta | null;
+
+/**
+ * A viewer's dashboard customisation: order, hidden and minimised widgets.
+ * Pure functions over a small JSON-serialisable object. Persist it however
+ * you like (a settings table, localStorage); `parseLayout` tolerates
+ * anything, so a corrupt saved value never breaks the dashboard.
+ *
+ * Generalised from Maker Toolkit's desktop `dashboard-layout.ts`.
+ */
+/** What layout functions need from a widget definition. */
+interface LayoutItem {
+    readonly key: string;
+    readonly sortOrder?: number;
+}
+interface DashboardLayout {
+    /** Widget keys in display order. Keys not listed follow, by sortOrder. */
+    readonly order: readonly string[];
+    /** Widget keys removed from the dashboard (restorable). */
+    readonly hidden: readonly string[];
+    /** Widget keys collapsed to their header. */
+    readonly minimized: readonly string[];
+}
+declare const EMPTY_LAYOUT: DashboardLayout;
+/**
+ * Reads a saved layout: a JSON string or an already-parsed object. Missing,
+ * corrupt or wrongly typed values give the empty layout (or empty lists for
+ * the fields that are wrong); non-string and duplicate keys are dropped.
+ */
+declare function parseLayout(raw: unknown): DashboardLayout;
+/** The JSON string to persist. */
+declare function serializeLayout(layout: DashboardLayout): string;
+/**
+ * The widgets to show, in order: saved keys first (when still present),
+ * then widgets the layout doesn't know yet, by sortOrder. Hidden widgets
+ * are left out.
+ */
+declare function visibleWidgets<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout): T[];
+/** Hidden widgets, by sortOrder, for a "restore" menu. */
+declare function hiddenWidgets<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout): T[];
+/**
+ * Moves `key` to `toIndex` within the current visible order. Returns the
+ * same layout object when the key isn't visible or the index is out of
+ * range, so callers can skip a save.
+ */
+declare function moveWidget<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, key: string, toIndex: number): DashboardLayout;
+/** Moves `key` by `offset` places (negative is earlier). Clamped at the ends. */
+declare function moveWidgetBy<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, key: string, offset: number): DashboardLayout;
+/** Moves `key` one place earlier. */
+declare function moveWidgetUp<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, key: string): DashboardLayout;
+/** Moves `key` one place later. */
+declare function moveWidgetDown<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, key: string): DashboardLayout;
+declare function isHidden(layout: DashboardLayout, key: string): boolean;
+declare function isMinimized(layout: DashboardLayout, key: string): boolean;
+/** Hides `key`. No-op (same object) if already hidden. */
+declare function hideWidget(layout: DashboardLayout, key: string): DashboardLayout;
+/** Shows `key` again, expanded. No-op (same object) if not hidden. */
+declare function showWidget(layout: DashboardLayout, key: string): DashboardLayout;
+/** Hides or shows `key` (showing also clears its minimised state). */
+declare function toggleHidden(layout: DashboardLayout, key: string): DashboardLayout;
+/** Collapses `key` to its header. No-op (same object) if already minimised. */
+declare function minimizeWidget(layout: DashboardLayout, key: string): DashboardLayout;
+/** Expands `key`. No-op (same object) if not minimised. */
+declare function restoreWidget(layout: DashboardLayout, key: string): DashboardLayout;
+/** Minimises or restores `key`. */
+declare function toggleMinimized(layout: DashboardLayout, key: string): DashboardLayout;
+/**
+ * Drops keys for widgets that no longer exist. Only pass the full list of
+ * definitions (not a role-filtered one), or a viewer's settings for widgets
+ * they temporarily can't see are lost.
+ */
+declare function pruneLayout<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout): DashboardLayout;
+
+/**
+ * Runs each widget's data provider and collects the outcome per widget, so
+ * one failing provider never breaks the rest of the dashboard. The package
+ * never fetches anything itself: providers are the consumer's functions
+ * (a Prisma query, an HTTP call, a computed value).
+ */
+
+/** The minimum a resolve context carries; add whatever your providers need. */
+interface WidgetContext {
+    /** The viewer's roles. Widgets with `roles` need at least one of them. */
+    readonly roles?: readonly string[];
+}
+/** Loads one widget's payload. May be sync or async; may throw. */
+type WidgetProvider<C = WidgetContext> = (context: C, definition: WidgetDefinition) => WidgetPayload | Promise<WidgetPayload>;
+/** Providers keyed by widget key. */
+type WidgetProviders<C = WidgetContext> = Readonly<Record<string, WidgetProvider<C>>>;
+interface OkWidget {
+    readonly definition: WidgetDefinition;
+    readonly status: 'ok';
+    readonly data: WidgetData;
+}
+interface EmptyWidget {
+    readonly definition: WidgetDefinition;
+    readonly status: 'empty';
+    /** Why there is nothing to show, e.g. "No orders synced yet." */
+    readonly emptyText: string;
+}
+interface ErrorWidget {
+    readonly definition: WidgetDefinition;
+    readonly status: 'error';
+    /** Names the widget and what failed. */
+    readonly error: string;
+}
+/** One widget after its provider ran. */
+type ResolvedWidget = OkWidget | EmptyWidget | ErrorWidget;
+/** A widget whose data hasn't arrived yet (for client-side loading states). */
+interface LoadingWidget {
+    readonly definition: WidgetDefinition;
+    readonly status: 'loading';
+}
+/** Anything a dashboard can render: resolved, or still loading. */
+type DashboardWidget = ResolvedWidget | LoadingWidget;
+type WidgetStatus = DashboardWidget['status'];
+interface ResolveOptions {
+    /**
+     * Validate each provider's payload with `validateWidgetData` (and check
+     * its kind matches the definition). Default true; turn off only for
+     * trusted, typed providers.
+     */
+    readonly validate?: boolean;
+}
+/**
+ * Turns a payload (typically JSON from an API) into a resolved widget:
+ * validated against the definition's kind, and marked empty when it has
+ * nothing to show.
+ */
+declare function resolvePayload(definition: WidgetDefinition, payload: unknown, options?: ResolveOptions): ResolvedWidget;
+/** A widget that failed, with the reason. */
+declare function failedWidget(definition: WidgetDefinition, error: string): ErrorWidget;
+/** Loading placeholders for definitions, before their data arrives. */
+declare function loadingWidgets(definitions: readonly WidgetDefinition[]): LoadingWidget[];
+/** Runs one widget's provider, capturing a throw or bad payload as an error. */
+declare function resolveWidget<C extends WidgetContext>(definition: WidgetDefinition, provider: WidgetProvider<C> | undefined, context: C, options?: ResolveOptions): Promise<ResolvedWidget>;
+/**
+ * The widgets a viewer can see: active, allowed for `roles`, in sort order.
+ */
+declare function widgetsFor(definitions: readonly WidgetDefinition[], roles: readonly string[] | undefined): WidgetDefinition[];
+/**
+ * Resolves every widget the context's roles may see, in parallel. Inactive
+ * and role-filtered widgets are skipped (and their providers never run).
+ * Results come back in sort order; a provider that throws, is missing or
+ * returns a bad payload yields an `error` widget and never rejects.
+ */
+declare function resolveWidgets<C extends WidgetContext>(definitions: readonly WidgetDefinition[], providers: WidgetProviders<C>, context: C, options?: ResolveOptions): Promise<ResolvedWidget[]>;
+
+/** Axis maths for charts: clean domains and tick values. Pure. */
+/** The smallest 1, 2 or 5 × 10^n that is at least `value` (1 for 0 or less). */
+declare function niceStep(value: number): number;
+interface NiceDomain {
+    readonly min: number;
+    readonly max: number;
+    /** From min to max inclusive, evenly spaced on a clean step. */
+    readonly ticks: readonly number[];
+}
+/**
+ * A y-axis domain that always includes 0 (bars grow from a single
+ * baseline), rounded out to a clean step, with about `tickCount` intervals.
+ */
+declare function niceDomain(values: readonly number[], tickCount?: number): NiceDomain;
+/**
+ * Show every `n`th x label so at most `maxLabels` appear (always at least 1).
+ */
+declare function labelStride(count: number, maxLabels?: number): number;
+
+export { formatCount as $, type AlertListWidgetData as A, type BarListWidgetData as B, WIDGET_KINDS as C, type DashboardWidget as D, EMPTY_LAYOUT as E, type FormatOptions as F, type GraphWidgetData as G, WIDGET_SIZES as H, type WidgetContext as I, type WidgetDataOf as J, type KpiWidgetData as K, type Locale as L, MAX_GRAPH_SERIES as M, type NiceDomain as N, type OkWidget as O, type WidgetEmptyState as P, type WidgetProvider as Q, type ResolveOptions as R, type WidgetProviders as S, type TableWidgetData as T, type WidgetStatus as U, VALUE_FORMATS as V, type WidgetSize as W, defineWidget as X, emptyTextFor as Y, emptyWidget as Z, failedWidget as _, type DashboardLayout as a, formatPercentChange as a0, formatValue as a1, hiddenWidgets as a2, hideWidget as a3, isHidden as a4, isMinimized as a5, isWidgetEmptyState as a6, isWidgetKind as a7, isWidgetVisibleTo as a8, kpiDelta as a9, labelStride as aa, loadingWidgets as ab, minimizeWidget as ac, moveWidget as ad, moveWidgetBy as ae, moveWidgetDown as af, moveWidgetUp as ag, niceDomain as ah, niceStep as ai, parseLayout as aj, percentChange as ak, pruneLayout as al, resolvePayload as am, resolveWidget as an, resolveWidgets as ao, restoreWidget as ap, serializeLayout as aq, shareOf as ar, showWidget as as, sortDefinitions as at, toggleHidden as au, toggleMinimized as av, visibleWidgets as aw, widgetsFor as ax, type GaugeWidgetData as b, type TextWidgetData as c, type WidgetData as d, type WidgetDefinition as e, type WidgetKind as f, type WidgetPayload as g, type AlertListItem as h, type BarListItem as i, DEFAULT_COMPARISON_LABEL as j, DEFAULT_CURRENCY as k, DEFAULT_EMPTY_TEXT as l, type DeltaDirection as m, type DeltaSentiment as n, type EmptyWidget as o, type ErrorWidget as p, type GraphPoint as q, type GraphSeries as r, type KpiDelta as s, type KpiDeltaOptions as t, type LayoutItem as u, type LoadingWidget as v, type ResolvedWidget as w, type TableCell as x, type TableColumn as y, type ValueFormat as z };