@richardmcquiston01/dashboard-widgets-toolkit 0.2.0 → 0.4.0

package/dist/core.d.cts

@@ -1,5 +1,5 @@
-import { f as WidgetDefinition, W as WidgetSize, a as WidgetFill, g as WidgetKind, h as WidgetPayload } from './scale-Bhjc5Eqt.cjs';
-export { i as AlertListItem, A as AlertListWidgetData, j as BarListItem, B as BarListWidgetData, k as DEFAULT_COMPARISON_LABEL, l as DEFAULT_CURRENCY, m as DEFAULT_EMPTY_TEXT, b as DashboardLayout, D as DashboardWidget, n as DeltaDirection, o as DeltaSentiment, E as EMPTY_LAYOUT, p as EmptyWidget, q as ErrorWidget, F as FormatOptions, c as GaugeWidgetData, r as GraphPoint, s as GraphSeries, G as GraphWidgetData, t as KpiDelta, u as KpiDeltaOptions, K as KpiWidgetData, v as LayoutItem, w as LoadingWidget, L as Locale, M as MAX_GRAPH_SERIES, N as NiceDomain, O as OkWidget, R as ResolveOptions, x as ResolvedWidget, y as TableCell, z as TableColumn, T as TableWidgetData, d as TextWidgetData, V as VALUE_FORMATS, C as ValueFormat, H as WIDGET_FILLS, I as WIDGET_KINDS, J as WIDGET_SIZES, P as WidgetContext, e as WidgetData, Q as WidgetDataOf, S as WidgetEmptyState, U as WidgetProvider, X as WidgetProviders, Y as WidgetStatus, Z as defineWidget, _ as emptyTextFor, $ as emptyWidget, a0 as failedWidget, a1 as formatCount, a2 as formatPercentChange, a3 as formatValue, a4 as hiddenWidgets, a5 as hideWidget, a6 as isHidden, a7 as isMinimized, a8 as isWidgetEmptyState, a9 as isWidgetKind, aa as isWidgetVisibleTo, ab as kpiDelta, ac as labelStride, ad as loadingWidgets, ae as minimizeWidget, af as moveWidget, ag as moveWidgetBy, ah as moveWidgetDown, ai as moveWidgetUp, aj as niceDomain, ak as niceStep, al as parseLayout, am as percentChange, an as pruneLayout, ao as resolvePayload, ap as resolveWidget, aq as resolveWidgets, ar as restoreWidget, as as serializeLayout, at as shareOf, au as showWidget, av as sortDefinitions, aw as toggleHidden, ax as toggleMinimized, ay as visibleWidgets, az as widgetsFor } from './scale-Bhjc5Eqt.cjs';
+import { b as WidgetDefinition, W as WidgetSize, a as WidgetFill, D as DashboardWidget, j as WidgetContext, R as ResolveOptions, k as WidgetProviders, l as WidgetKind, m as Result, n as WidgetPayload } from './scale-dWDGE1zW.cjs';
+export { o as AlertListItem, A as AlertListWidgetData, p as BarListItem, B as BarListWidgetData, C as CachedPayload, q as DEFAULT_COMPARISON_LABEL, r as DEFAULT_CURRENCY, s as DEFAULT_DETAIL_PAGE_SIZE, t as DEFAULT_EMPTY_TEXT, u as DETAIL_MODES, f as DashboardLayout, v as DeltaDirection, w as DeltaSentiment, x as DetailCell, y as DetailColumn, d as DetailData, z as DetailMode, E as DetailPage, F as DetailProvider, c as DetailProviderOptions, H as DetailProviders, e as DetailQuery, I as DetailSort, J as EMPTY_LAYOUT, M as EmptyWidget, O as Err, P as ErrorWidget, Q as FormatOptions, g as GaugeWidgetData, S as GraphPoint, U as GraphSeries, G as GraphWidgetData, V as KpiDelta, X as KpiDeltaOptions, K as KpiWidgetData, Y as LayoutItem, Z as LoadingWidget, L as Locale, _ as MAX_DETAIL_PAGE_SIZE, $ as MAX_GRAPH_SERIES, N as NiceDomain, a0 as Ok, a1 as OkWidget, a2 as ProviderOptions, a3 as ResolvedDetailOptions, a4 as ResolvedWidget, a5 as SortDirection, a6 as TableCell, a7 as TableColumn, T as TableWidgetData, h as TextWidgetData, a8 as VALUE_FORMATS, a9 as ValueFormat, aa as WIDGET_FILLS, ab as WIDGET_KINDS, ac as WIDGET_SIZES, ad as WidgetCache, i as WidgetData, ae as WidgetDataOf, af as WidgetDetailOptions, ag as WidgetEmptyState, ah as WidgetProvider, ai as WidgetStatus, aj as cacheKeyFor, ak as defaultDetailQuery, al as defineWidget, am as deriveDetailData, an as describeUnknownError, ao as emptyTextFor, ap as emptyWidget, aq as err, ar as failedWidget, as as formatCount, at as formatPercentChange, au as formatValue, av as hiddenWidgets, aw as hideWidget, ax as isHidden, ay as isMinimized, az as isWidgetEmptyState, aA as isWidgetKind, aB as isWidgetVisibleTo, aC as kpiDelta, aD as labelStride, aE as loadingWidgets, aF as minimizeWidget, aG as moveWidget, aH as moveWidgetBy, aI as moveWidgetDown, aJ as moveWidgetUp, aK as niceDomain, aL as niceStep, aM as ok, aN as parseDetailQuery, aO as parseLayout, aP as percentChange, aQ as pruneLayout, aR as queryRows, aS as resolveDetailOptions, aT as resolvePayload, aU as resolveWidget, aV as resolveWidgets, aW as restoreWidget, aX as serializeDetailQuery, aY as serializeLayout, aZ as shareOf, a_ as showWidget, a$ as sortDefinitions, b0 as toggleHidden, b1 as toggleMinimized, b2 as validateDetailData, b3 as visibleWidgets, b4 as widgetsFor } from './scale-dWDGE1zW.cjs';
 
 /**
  * Maker Toolkit compatibility. Its API (`apps/api/src/widgets`) serves
@@ -38,7 +38,21 @@ interface GridItem {
     readonly key: string;
     readonly defaultSize?: WidgetSize;
     readonly fill?: WidgetFill;
+    readonly width?: number;
 }
+/** Columns in a grid that uses widget `width`. */
+declare const WIDTH_COLUMNS = 12;
+/** Smallest and largest `width`, in twelfths of a row. */
+declare const MIN_WIDGET_WIDTH = 2;
+declare const MAX_WIDGET_WIDTH = 12;
+/** Whether `value` is a valid widget `width`: an integer from 2 to 12. */
+declare function isWidgetWidth(value: unknown): value is number;
+/** The width (in twelfths) a `defaultSize` stands for. Default `medium`. */
+declare function widthForSize(size: WidgetSize | undefined): number;
+/** The 12-column width of an item: its `width`, else from its size. */
+declare function itemWidth(item: GridItem): number;
+/** Whether a grid of `items` should use 12 columns (any item sets `width`). */
+declare function usesWidthColumns(items: readonly GridItem[]): boolean;
 /** Whether the widget should take the columns left over in its row. */
 declare function fillsWidth(fill: WidgetFill | undefined): boolean;
 /** Whether the widget should stretch to the height of its row. */
@@ -58,26 +72,55 @@ declare function baseColumnSpan(size: WidgetSize | undefined, columns: number, l
  * that do not fill width keep their normal size and are not in the map.
  */
 declare function fillColumnSpans(items: readonly GridItem[], columns: number, largeSpan?: number): Map<string, number>;
+/**
+ * Like `fillColumnSpans` for a 12-column grid: each item starts at its
+ * `width` (see `itemWidth`) and width-fillers share the leftover twelfths.
+ */
+declare function fillWidthSpans(items: readonly GridItem[]): Map<string, number>;
 
 /**
- * A small Result type. Functions in this package return a Result rather than
- * throwing, so the caller has to look at the outcome. `throw` is reserved for
- * programmer error.
+ * Loads widgets one by one, after the first render, and reports each result
+ * as it arrives. It is the logic behind the React `useWidgets` hook, kept
+ * framework-agnostic and runtime-neutral so it can be tested without a DOM
+ * and reused by other renderers. Like the rest of the core it never fetches
+ * anything itself: providers do the work.
+ *
+ * Lifecycle: `createWidgetLoader` (nothing runs yet; every widget is
+ * `loading`) then `load(key)` / `loadAll()` when you want data (immediately
+ * after mount, or when a card scrolls into view), `refresh()` to reload, and
+ * `dispose()` to cancel everything.
  */
-interface Ok<T> {
-    readonly ok: true;
-    readonly value: T;
+
+interface WidgetLoaderOptions<C extends WidgetContext> extends ResolveOptions {
+    readonly definitions: readonly WidgetDefinition[];
+    readonly providers: WidgetProviders<C>;
+    readonly context: C;
+}
+interface RefreshOptions {
+    /** Leave widgets that are still loading alone instead of restarting them. */
+    readonly skipInFlight?: boolean;
 }
-interface Err {
-    readonly ok: false;
-    /** Specific enough to act on: names the field, the widget and the problem. */
-    readonly error: string;
+interface WidgetLoader {
+    /** The current widgets in display order. A new array after every change. */
+    getSnapshot(): readonly DashboardWidget[];
+    /** Calls `listener` after every change. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    /** Starts loading one widget. Does nothing if it already started. */
+    load(key: string): void;
+    /** Starts loading every widget that has not started yet. */
+    loadAll(): void;
+    /**
+     * Reloads started widgets (or just `key`). The previous call is aborted and
+     * its result ignored. Visible data stays until the new data arrives; an
+     * `error` widget goes back to `loading`. With `skipInFlight`, widgets that
+     * are still loading are left alone (what polling wants: a provider slower
+     * than the interval would otherwise be restarted forever and never finish).
+     */
+    refresh(key?: string, options?: RefreshOptions): void;
+    /** Aborts everything in flight and ignores any later result. */
+    dispose(): void;
 }
-type Result<T> = Ok<T> | Err;
-declare function ok<T>(value: T): Ok<T>;
-declare function err(error: string): Err;
-/** Turns an unknown thrown value into a readable message. */
-declare function describeUnknownError(cause: unknown): string;
+declare function createWidgetLoader<C extends WidgetContext>(options: WidgetLoaderOptions<C>): WidgetLoader;
 
 /**
  * Link and image URL checks. Payloads often come from an API, so a link is
@@ -116,4 +159,4 @@ declare function validateWidgetData(value: unknown, options?: ValidateWidgetData
  */
 declare function validateWidgetDefinition(value: unknown): Result<WidgetDefinition>;
 
-export { type Err, type GridItem, type LegacyWidgetDefinition, MAX_REPORTED_PROBLEMS, type Ok, type Result, type ValidateWidgetDataOptions, WidgetDefinition, WidgetFill, WidgetKind, WidgetPayload, WidgetSize, baseColumnSpan, describeUnknownError, err, fillColumnSpans, fillsHeight, fillsWidth, fromLegacyDefinition, isSafeHref, isSafeImageUrl, ok, upgradeLegacyWidgetData, validateWidgetData, validateWidgetDefinition };
+export { DashboardWidget, type GridItem, type LegacyWidgetDefinition, MAX_REPORTED_PROBLEMS, MAX_WIDGET_WIDTH, MIN_WIDGET_WIDTH, type RefreshOptions, ResolveOptions, Result, type ValidateWidgetDataOptions, WIDTH_COLUMNS, WidgetContext, WidgetDefinition, WidgetFill, WidgetKind, type WidgetLoader, type WidgetLoaderOptions, WidgetPayload, WidgetProviders, WidgetSize, baseColumnSpan, createWidgetLoader, fillColumnSpans, fillWidthSpans, fillsHeight, fillsWidth, fromLegacyDefinition, isSafeHref, isSafeImageUrl, isWidgetWidth, itemWidth, upgradeLegacyWidgetData, usesWidthColumns, validateWidgetData, validateWidgetDefinition, widthForSize };

package/dist/core.d.ts

@@ -1,5 +1,5 @@
-import { f as WidgetDefinition, W as WidgetSize, a as WidgetFill, g as WidgetKind, h as WidgetPayload } from './scale-Bhjc5Eqt.js';
-export { i as AlertListItem, A as AlertListWidgetData, j as BarListItem, B as BarListWidgetData, k as DEFAULT_COMPARISON_LABEL, l as DEFAULT_CURRENCY, m as DEFAULT_EMPTY_TEXT, b as DashboardLayout, D as DashboardWidget, n as DeltaDirection, o as DeltaSentiment, E as EMPTY_LAYOUT, p as EmptyWidget, q as ErrorWidget, F as FormatOptions, c as GaugeWidgetData, r as GraphPoint, s as GraphSeries, G as GraphWidgetData, t as KpiDelta, u as KpiDeltaOptions, K as KpiWidgetData, v as LayoutItem, w as LoadingWidget, L as Locale, M as MAX_GRAPH_SERIES, N as NiceDomain, O as OkWidget, R as ResolveOptions, x as ResolvedWidget, y as TableCell, z as TableColumn, T as TableWidgetData, d as TextWidgetData, V as VALUE_FORMATS, C as ValueFormat, H as WIDGET_FILLS, I as WIDGET_KINDS, J as WIDGET_SIZES, P as WidgetContext, e as WidgetData, Q as WidgetDataOf, S as WidgetEmptyState, U as WidgetProvider, X as WidgetProviders, Y as WidgetStatus, Z as defineWidget, _ as emptyTextFor, $ as emptyWidget, a0 as failedWidget, a1 as formatCount, a2 as formatPercentChange, a3 as formatValue, a4 as hiddenWidgets, a5 as hideWidget, a6 as isHidden, a7 as isMinimized, a8 as isWidgetEmptyState, a9 as isWidgetKind, aa as isWidgetVisibleTo, ab as kpiDelta, ac as labelStride, ad as loadingWidgets, ae as minimizeWidget, af as moveWidget, ag as moveWidgetBy, ah as moveWidgetDown, ai as moveWidgetUp, aj as niceDomain, ak as niceStep, al as parseLayout, am as percentChange, an as pruneLayout, ao as resolvePayload, ap as resolveWidget, aq as resolveWidgets, ar as restoreWidget, as as serializeLayout, at as shareOf, au as showWidget, av as sortDefinitions, aw as toggleHidden, ax as toggleMinimized, ay as visibleWidgets, az as widgetsFor } from './scale-Bhjc5Eqt.js';
+import { b as WidgetDefinition, W as WidgetSize, a as WidgetFill, D as DashboardWidget, j as WidgetContext, R as ResolveOptions, k as WidgetProviders, l as WidgetKind, m as Result, n as WidgetPayload } from './scale-dWDGE1zW.js';
+export { o as AlertListItem, A as AlertListWidgetData, p as BarListItem, B as BarListWidgetData, C as CachedPayload, q as DEFAULT_COMPARISON_LABEL, r as DEFAULT_CURRENCY, s as DEFAULT_DETAIL_PAGE_SIZE, t as DEFAULT_EMPTY_TEXT, u as DETAIL_MODES, f as DashboardLayout, v as DeltaDirection, w as DeltaSentiment, x as DetailCell, y as DetailColumn, d as DetailData, z as DetailMode, E as DetailPage, F as DetailProvider, c as DetailProviderOptions, H as DetailProviders, e as DetailQuery, I as DetailSort, J as EMPTY_LAYOUT, M as EmptyWidget, O as Err, P as ErrorWidget, Q as FormatOptions, g as GaugeWidgetData, S as GraphPoint, U as GraphSeries, G as GraphWidgetData, V as KpiDelta, X as KpiDeltaOptions, K as KpiWidgetData, Y as LayoutItem, Z as LoadingWidget, L as Locale, _ as MAX_DETAIL_PAGE_SIZE, $ as MAX_GRAPH_SERIES, N as NiceDomain, a0 as Ok, a1 as OkWidget, a2 as ProviderOptions, a3 as ResolvedDetailOptions, a4 as ResolvedWidget, a5 as SortDirection, a6 as TableCell, a7 as TableColumn, T as TableWidgetData, h as TextWidgetData, a8 as VALUE_FORMATS, a9 as ValueFormat, aa as WIDGET_FILLS, ab as WIDGET_KINDS, ac as WIDGET_SIZES, ad as WidgetCache, i as WidgetData, ae as WidgetDataOf, af as WidgetDetailOptions, ag as WidgetEmptyState, ah as WidgetProvider, ai as WidgetStatus, aj as cacheKeyFor, ak as defaultDetailQuery, al as defineWidget, am as deriveDetailData, an as describeUnknownError, ao as emptyTextFor, ap as emptyWidget, aq as err, ar as failedWidget, as as formatCount, at as formatPercentChange, au as formatValue, av as hiddenWidgets, aw as hideWidget, ax as isHidden, ay as isMinimized, az as isWidgetEmptyState, aA as isWidgetKind, aB as isWidgetVisibleTo, aC as kpiDelta, aD as labelStride, aE as loadingWidgets, aF as minimizeWidget, aG as moveWidget, aH as moveWidgetBy, aI as moveWidgetDown, aJ as moveWidgetUp, aK as niceDomain, aL as niceStep, aM as ok, aN as parseDetailQuery, aO as parseLayout, aP as percentChange, aQ as pruneLayout, aR as queryRows, aS as resolveDetailOptions, aT as resolvePayload, aU as resolveWidget, aV as resolveWidgets, aW as restoreWidget, aX as serializeDetailQuery, aY as serializeLayout, aZ as shareOf, a_ as showWidget, a$ as sortDefinitions, b0 as toggleHidden, b1 as toggleMinimized, b2 as validateDetailData, b3 as visibleWidgets, b4 as widgetsFor } from './scale-dWDGE1zW.js';
 
 /**
  * Maker Toolkit compatibility. Its API (`apps/api/src/widgets`) serves
@@ -38,7 +38,21 @@ interface GridItem {
     readonly key: string;
     readonly defaultSize?: WidgetSize;
     readonly fill?: WidgetFill;
+    readonly width?: number;
 }
+/** Columns in a grid that uses widget `width`. */
+declare const WIDTH_COLUMNS = 12;
+/** Smallest and largest `width`, in twelfths of a row. */
+declare const MIN_WIDGET_WIDTH = 2;
+declare const MAX_WIDGET_WIDTH = 12;
+/** Whether `value` is a valid widget `width`: an integer from 2 to 12. */
+declare function isWidgetWidth(value: unknown): value is number;
+/** The width (in twelfths) a `defaultSize` stands for. Default `medium`. */
+declare function widthForSize(size: WidgetSize | undefined): number;
+/** The 12-column width of an item: its `width`, else from its size. */
+declare function itemWidth(item: GridItem): number;
+/** Whether a grid of `items` should use 12 columns (any item sets `width`). */
+declare function usesWidthColumns(items: readonly GridItem[]): boolean;
 /** Whether the widget should take the columns left over in its row. */
 declare function fillsWidth(fill: WidgetFill | undefined): boolean;
 /** Whether the widget should stretch to the height of its row. */
@@ -58,26 +72,55 @@ declare function baseColumnSpan(size: WidgetSize | undefined, columns: number, l
  * that do not fill width keep their normal size and are not in the map.
  */
 declare function fillColumnSpans(items: readonly GridItem[], columns: number, largeSpan?: number): Map<string, number>;
+/**
+ * Like `fillColumnSpans` for a 12-column grid: each item starts at its
+ * `width` (see `itemWidth`) and width-fillers share the leftover twelfths.
+ */
+declare function fillWidthSpans(items: readonly GridItem[]): Map<string, number>;
 
 /**
- * A small Result type. Functions in this package return a Result rather than
- * throwing, so the caller has to look at the outcome. `throw` is reserved for
- * programmer error.
+ * Loads widgets one by one, after the first render, and reports each result
+ * as it arrives. It is the logic behind the React `useWidgets` hook, kept
+ * framework-agnostic and runtime-neutral so it can be tested without a DOM
+ * and reused by other renderers. Like the rest of the core it never fetches
+ * anything itself: providers do the work.
+ *
+ * Lifecycle: `createWidgetLoader` (nothing runs yet; every widget is
+ * `loading`) then `load(key)` / `loadAll()` when you want data (immediately
+ * after mount, or when a card scrolls into view), `refresh()` to reload, and
+ * `dispose()` to cancel everything.
  */
-interface Ok<T> {
-    readonly ok: true;
-    readonly value: T;
+
+interface WidgetLoaderOptions<C extends WidgetContext> extends ResolveOptions {
+    readonly definitions: readonly WidgetDefinition[];
+    readonly providers: WidgetProviders<C>;
+    readonly context: C;
+}
+interface RefreshOptions {
+    /** Leave widgets that are still loading alone instead of restarting them. */
+    readonly skipInFlight?: boolean;
 }
-interface Err {
-    readonly ok: false;
-    /** Specific enough to act on: names the field, the widget and the problem. */
-    readonly error: string;
+interface WidgetLoader {
+    /** The current widgets in display order. A new array after every change. */
+    getSnapshot(): readonly DashboardWidget[];
+    /** Calls `listener` after every change. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    /** Starts loading one widget. Does nothing if it already started. */
+    load(key: string): void;
+    /** Starts loading every widget that has not started yet. */
+    loadAll(): void;
+    /**
+     * Reloads started widgets (or just `key`). The previous call is aborted and
+     * its result ignored. Visible data stays until the new data arrives; an
+     * `error` widget goes back to `loading`. With `skipInFlight`, widgets that
+     * are still loading are left alone (what polling wants: a provider slower
+     * than the interval would otherwise be restarted forever and never finish).
+     */
+    refresh(key?: string, options?: RefreshOptions): void;
+    /** Aborts everything in flight and ignores any later result. */
+    dispose(): void;
 }
-type Result<T> = Ok<T> | Err;
-declare function ok<T>(value: T): Ok<T>;
-declare function err(error: string): Err;
-/** Turns an unknown thrown value into a readable message. */
-declare function describeUnknownError(cause: unknown): string;
+declare function createWidgetLoader<C extends WidgetContext>(options: WidgetLoaderOptions<C>): WidgetLoader;
 
 /**
  * Link and image URL checks. Payloads often come from an API, so a link is
@@ -116,4 +159,4 @@ declare function validateWidgetData(value: unknown, options?: ValidateWidgetData
  */
 declare function validateWidgetDefinition(value: unknown): Result<WidgetDefinition>;
 
-export { type Err, type GridItem, type LegacyWidgetDefinition, MAX_REPORTED_PROBLEMS, type Ok, type Result, type ValidateWidgetDataOptions, WidgetDefinition, WidgetFill, WidgetKind, WidgetPayload, WidgetSize, baseColumnSpan, describeUnknownError, err, fillColumnSpans, fillsHeight, fillsWidth, fromLegacyDefinition, isSafeHref, isSafeImageUrl, ok, upgradeLegacyWidgetData, validateWidgetData, validateWidgetDefinition };
+export { DashboardWidget, type GridItem, type LegacyWidgetDefinition, MAX_REPORTED_PROBLEMS, MAX_WIDGET_WIDTH, MIN_WIDGET_WIDTH, type RefreshOptions, ResolveOptions, Result, type ValidateWidgetDataOptions, WIDTH_COLUMNS, WidgetContext, WidgetDefinition, WidgetFill, WidgetKind, type WidgetLoader, type WidgetLoaderOptions, WidgetPayload, WidgetProviders, WidgetSize, baseColumnSpan, createWidgetLoader, fillColumnSpans, fillWidthSpans, fillsHeight, fillsWidth, fromLegacyDefinition, isSafeHref, isSafeImageUrl, isWidgetWidth, itemWidth, upgradeLegacyWidgetData, usesWidthColumns, validateWidgetData, validateWidgetDefinition, widthForSize };