@richardmcquiston01/dashboard-widgets-toolkit 0.16.0 → 0.17.0

package/dist/{storage-oivwB7al.d.cts → storage-CRBfjiVZ.d.cts}

@@ -431,6 +431,14 @@ interface ProviderOptions {
      * and check them again on the server.
      */
     readonly options: OptionValues;
+    /**
+     * The view being loaded: `base` (the widget's own kind) unless the viewer
+     * chose a view the provider supplies (a `views` entry without `convert`), in
+     * which case it is that view's key and the payload must be of that view's
+     * kind. Converted views never reach the provider: they are built from the
+     * `base` payload.
+     */
+    readonly view: string;
 }
 /**
  * Loads one widget's payload. May be sync or async; may throw. The third
@@ -450,6 +458,11 @@ interface OkWidget {
     readonly stale?: boolean;
     /** The widget's resolved option values; present when it declares options. */
     readonly options?: OptionValues;
+    /**
+     * The view this data was loaded for (`base` or a provider-supplied view's
+     * key); present when the widget declares `views`.
+     */
+    readonly view?: string;
 }
 interface EmptyWidget {
     readonly definition: WidgetDefinition;
@@ -500,6 +513,13 @@ interface ResolveOptions extends OptionContext {
      * and the option's default is used.
      */
     readonly optionValues?: Readonly<Record<string, Readonly<Record<string, unknown>> | undefined>>;
+    /**
+     * The view each widget shows, by widget key. Only views the provider
+     * supplies matter here (the provider is asked for that view); converted
+     * views are applied later from the base payload. An empty string means no
+     * choice (the widget's `defaultView`).
+     */
+    readonly viewValues?: Readonly<Record<string, string | undefined>>;
     /**
      * Validate each provider's payload with `validateWidgetData` (and check
      * its kind matches the definition). Default true; turn off only for
@@ -668,7 +688,7 @@ interface DetailQuery {
     readonly pageSize: number;
 }
 /** What a detail provider receives beyond the usual arguments. */
-interface DetailProviderOptions extends ProviderOptions {
+interface DetailProviderOptions extends Omit<ProviderOptions, 'view'> {
     readonly query: DetailQuery;
 }
 /**
@@ -795,8 +815,14 @@ interface WidgetView {
     readonly label: string;
     /** What this view renders; must match what the conversion produces. */
     readonly kind: WidgetKind;
-    /** Builds this view from the widget's payload. */
-    readonly convert: ViewConversion;
+    /**
+     * Builds this view from the widget's payload. Leave it out and the provider
+     * supplies the view instead: it is called with `options.view` set to this
+     * view's key and returns a payload of `kind`. That costs one load per view
+     * (cached apart), and is the way to show data a conversion can't build, such
+     * as a trend behind a KPI.
+     */
+    readonly convert?: ViewConversion;
 }
 /** What these functions need from a definition. */
 type ViewsItem = Pick<WidgetDefinition, 'key' | 'kind'> & Partial<Pick<WidgetDefinition, 'views' | 'defaultView' | 'baseViewLabel'>>;
@@ -812,6 +838,8 @@ declare function viewChoices(item: ViewsItem): readonly {
     label: string;
     kind: WidgetKind;
 }[];
+/** Whether the provider supplies this view's payload (it has no `convert`). */
+declare function isProviderView(view: Pick<WidgetView, 'convert'>): boolean;
 /**
  * The view in effect: the viewer's pick when the definition declares it,
  * else `defaultView`, else the base. Always a valid key.
@@ -819,6 +847,14 @@ declare function viewChoices(item: ViewsItem): readonly {
 declare function effectiveViewKey(item: ViewsItem, chosen: string | undefined): string;
 /** The kind the widget renders as under this view key. */
 declare function viewKind(item: ViewsItem, chosen: string | undefined): WidgetKind;
+/**
+ * The view the provider is asked for under the viewer's choice: the chosen
+ * view when the provider supplies it, else `base` (converted views are built
+ * from the base payload, so switching among them never reloads).
+ */
+declare function loadViewKey(item: ViewsItem, chosen: string | undefined): string;
+/** The kind of payload the provider returns for `loadViewKey`. */
+declare function loadViewKind(item: ViewsItem, chosen: string | undefined): WidgetKind;
 /** Options for `convertView`. */
 interface ConvertViewOptions {
     /** Locale for numbers a conversion has to format (graph to table). */
@@ -837,10 +873,13 @@ declare function convertView(widgetKey: string, view: Pick<WidgetView, 'key' | '
  */
 declare function viewNote(view: WidgetView, data: WidgetData | undefined): string;
 /**
- * The widget as the chosen view shows it: the payload converted and the
- * definition's `kind` set to the view's kind, so renderers work unchanged.
- * A widget that isn't `ok`, or whose view is the base, comes back as is; a
- * failed conversion becomes an `error` widget naming the fix.
+ * The widget as the chosen view shows it. A converted view gets the payload
+ * converted; a view the provider supplies already holds its own payload. The
+ * definition's `kind` becomes the view's kind, so renderers work unchanged. A
+ * failed conversion becomes an `error` widget naming the fix, and data that
+ * was loaded for a different view (a switch is still loading) shows as
+ * `loading` rather than in the wrong shape. A widget that isn't `ok`, or whose
+ * view is the base, comes back as is.
  */
 declare function applyView<W extends DashboardWidget>(widget: W, chosen: string | undefined, options?: ConvertViewOptions): DashboardWidget;
 
@@ -1110,6 +1149,18 @@ declare function optionValuesFromLayout(definitions: readonly Pick<SettingsItem,
 }, options?: {
     readonly overrideLocks?: boolean;
 }): Record<string, Readonly<Record<string, OptionValue>>>;
+/**
+ * What to pass `useWidgets({ viewValues })` so views the provider supplies
+ * follow the layout: for every widget that declares one, the viewer's chosen
+ * view key, or an empty string for no choice (its `defaultView`). Listing
+ * every such widget means a cleared choice reaches the loader too. Widgets
+ * with only converted views are left out: they need no provider call.
+ */
+declare function viewValuesFromLayout(definitions: readonly Pick<SettingsItem, 'key' | 'views' | 'locked'>[], layout: {
+    readonly settings?: LayoutSettings;
+}, options?: {
+    readonly overrideLocks?: boolean;
+}): Record<string, string>;
 /** Fields `setWidgetSettings` can change; `undefined` clears one. */
 interface WidgetSettingsPatch {
     readonly title?: string | undefined;
@@ -1662,4 +1713,4 @@ interface LayoutPersistence {
  */
 declare function createLayoutPersistence(adapter: StorageAdapter, options?: LayoutPersistenceOptions): LayoutPersistence;
 
-export { DEFAULT_MAX_LAYOUT_BYTES as $, type AlertListWidgetData as A, type BarListWidgetData as B, type CloneOptions as C, type DashboardWidget as D, type BooleanOption as E, type CachedPayload as F, type GraphWidgetData as G, type ChoiceOption as H, type CloneItem as I, type ColorOption as J, type KpiWidgetData as K, type Locale as L, type ColumnsOption as M, type NiceDomain as N, type OptionValues as O, type PageItem as P, type ConflictPolicy as Q, type ResolvedTableControls as R, type StoreScope as S, type TableWidgetData as T, type ConvertViewOptions as U, DATE_RANGE_PRESETS as V, type WidgetSize as W, DEFAULT_COMPARISON_LABEL as X, DEFAULT_CURRENCY as Y, DEFAULT_DETAIL_PAGE_SIZE as Z, DEFAULT_EMPTY_TEXT as _, type WidgetFill as a, type SortOption as a$, DEFAULT_PAGE_KEY as a0, DEFAULT_PAGE_ROWS as a1, DETAIL_MODES as a2, type DateRangeOption as a3, type DateRangePreset as a4, type DeltaDirection as a5, type DeltaSentiment as a6, type DetailCell as a7, type DetailColumn as a8, type DetailMode as a9, MAX_PARSED_CLONES as aA, MAX_PARSED_PAGES as aB, MAX_PARSED_SETTINGS as aC, MAX_TEXT_OPTION_LENGTH as aD, MAX_WIDGET_OPTIONS as aE, MAX_WIDGET_TITLE_LENGTH as aF, MAX_WIDGET_VIEWS as aG, MAX_WIDGET_WIDTH as aH, MIN_WIDGET_WIDTH as aI, type NormalizeSettingsOptions as aJ, type NumberOption as aK, OPTION_KEY_PATTERN as aL, type Ok as aM, type OkWidget as aN, type OptionContext as aO, type OptionValue as aP, type PageRoom as aQ, type PlacedRow as aR, type ProviderOptions as aS, type ResolvedDetailOptions as aT, type ResolvedWidget as aU, type ResolvedWidgetLock as aV, type RetryOptions as aW, type SaveOptions as aX, type SavedLayout as aY, type SettingsItem as aZ, type SortDirection as a_, type DetailPage as aa, type DetailProvider as ab, type DetailProviders as ac, EMPTY_LAYOUT as ad, type EmptyWidget as ae, type EncodingOptions as af, type EnforceLocksOptions as ag, type Err as ah, type ErrorWidget as ai, type FormatOptions as aj, type GraphPoint as ak, type GraphSeries as al, type GridItem as am, type KpiDelta as an, type KpiDeltaOptions as ao, LAYOUT_ENVELOPE_VERSION as ap, type LayoutItem as aq, type LayoutPage as ar, type LayoutPersistenceOptions as as, type LayoutSettings as at, type LoadedLayout as au, type LoadingWidget as av, MAX_DETAIL_PAGE_SIZE as aw, MAX_GRAPH_SERIES as ax, MAX_PAGE_ROWS as ay, MAX_PAGE_TITLE_LENGTH as az, type WidgetDefinition as b, hasPages as b$, type StorageAdapter as b0, type StorageLogEvent as b1, type StoreErrorCode as b2, type StoreResult as b3, type StoredValue as b4, type TableCell as b5, type TableColumn as b6, type TextOption as b7, VALUE_FORMATS as b8, VIEW_CONVERSIONS as b9, clearWidgetSettings as bA, cloneNumber as bB, coerceOptionValue as bC, convertView as bD, createLayoutPersistence as bE, defaultDetailQuery as bF, defaultOptionValue as bG, defineWidget as bH, deriveDetailData as bI, describeUnknownError as bJ, effectiveDefinitions as bK, effectiveViewKey as bL, emptyTextFor as bM, emptyWidget as bN, enforceLocks as bO, err as bP, failedWidget as bQ, fillColumnSpans as bR, fillWidthSpans as bS, fillsHeight as bT, fillsWidth as bU, finalizeWidget as bV, findView as bW, fitCount as bX, formatCount as bY, formatPercentChange as bZ, formatValue as b_, type ValueFormat as ba, type ViewConversion as bb, type ViewsItem as bc, WIDGET_FILLS as bd, WIDGET_KINDS as be, WIDGET_OPTION_TYPES as bf, WIDGET_SIZES as bg, WIDTH_COLUMNS as bh, type WidgetCache as bi, type WidgetDataOf as bj, type WidgetDetailOptions as bk, type WidgetEmptyState as bl, type WidgetLock as bm, type WidgetOption as bn, type WidgetProvider as bo, type WidgetStatus as bp, type WidgetTableControls as bq, type WidgetView as br, addPage as bs, applyClientOptions as bt, applySettings as bu, applyView as bv, assignPages as bw, baseColumnSpan as bx, cacheKeyFor as by, cleanClones as bz, type DetailProviderOptions as c, resolveWidgetUnapplied as c$, hasViews as c0, hiddenWidgets as c1, hideWidget as c2, isClientApplied as c3, isColumnKeyFor as c4, isFlexible as c5, isHidden as c6, isIsoInterval as c7, isMinimized as c8, isOptionsLocked as c9, optionValuesFromLayout as cA, optionsCacheSuffix as cB, pageLayout as cC, pageList as cD, pageOf as cE, pageRoom as cF, pageWidgets as cG, parseClones as cH, parseDetailQuery as cI, parseLayout as cJ, parseSettings as cK, parseSortValue as cL, percentChange as cM, placeRows as cN, pruneLayout as cO, queryRows as cP, readOnly as cQ, removePage as cR, renamePage as cS, resolveDateRange as cT, resolveDetailOptions as cU, resolveOptionValues as cV, resolvePageKey as cW, resolvePayload as cX, resolveTableControls as cY, resolveWidget as cZ, resolveWidgetLock as c_, isTitleInUse as ca, isWidgetEmptyState as cb, isWidgetKind as cc, isWidgetVisibleTo as cd, isWidgetWidth as ce, itemWidth as cf, kindLabel as cg, kpiDelta as ch, labelStride as ci, loadingWidgets as cj, memoryAdapter as ck, minimizeWidget as cl, movePage as cm, moveWidget as cn, moveWidgetBy as co, moveWidgetDown as cp, moveWidgetToPage as cq, moveWidgetUp as cr, nextPageKey as cs, niceDomain as ct, niceStep as cu, normalizeLayout as cv, normalizeSettings as cw, normalizeTitle as cx, ok as cy, optionValuesFor as cz, type DetailData as d, resolveWidgets as d0, restoreWidget as d1, sameOptionValues as d2, serializeClones as d3, serializeDetailQuery as d4, serializeLayout as d5, serializeSettings as d6, setWidgetSettings as d7, shareOf as d8, showWidget as d9, sortDefinitions as da, sortFromOptions as db, tableDetailData as dc, toggleHidden as dd, toggleMinimized as de, usesWidthColumns as df, utf8Length as dg, validateDetailData as dh, viewChoices as di, viewKind as dj, viewNote as dk, visibleWidgets as dl, widgetOptionValues as dm, widgetsFor as dn, widthForSize as dp, widthRange as dq, widthShareLabel as dr, withClones as ds, withEncoding as dt, withFallback as du, withLogging as dv, withPageLayout as dw, withPrefix as dx, withReadCache as dy, withRetry as dz, type DetailQuery as e, type DashboardLayout as f, type WidgetViewerSettings as g, type WidgetSettingsPatch as h, type GaugeWidgetData as i, type DetailSort as j, type TextWidgetData as k, type WidgetData as l, type LayoutPersistence as m, type NormalizeOptions as n, type ResolveOptions as o, type WidgetContext as p, type WidgetProviders as q, type PageOptions as r, type Result as s, type WidgetClone as t, type WidgetKind as u, type WidgetPayload as v, type AddPageOptions as w, type AlertListItem as x, BASE_VIEW_KEY as y, type BarListItem as z };
+export { DEFAULT_MAX_LAYOUT_BYTES as $, type AlertListWidgetData as A, type BarListWidgetData as B, type CloneOptions as C, type DashboardWidget as D, type BooleanOption as E, type CachedPayload as F, type GraphWidgetData as G, type ChoiceOption as H, type CloneItem as I, type ColorOption as J, type KpiWidgetData as K, type Locale as L, type ColumnsOption as M, type NiceDomain as N, type OptionValues as O, type PageItem as P, type ConflictPolicy as Q, type ResolvedTableControls as R, type StoreScope as S, type TableWidgetData as T, type ConvertViewOptions as U, DATE_RANGE_PRESETS as V, type WidgetSize as W, DEFAULT_COMPARISON_LABEL as X, DEFAULT_CURRENCY as Y, DEFAULT_DETAIL_PAGE_SIZE as Z, DEFAULT_EMPTY_TEXT as _, type WidgetFill as a, type SortOption as a$, DEFAULT_PAGE_KEY as a0, DEFAULT_PAGE_ROWS as a1, DETAIL_MODES as a2, type DateRangeOption as a3, type DateRangePreset as a4, type DeltaDirection as a5, type DeltaSentiment as a6, type DetailCell as a7, type DetailColumn as a8, type DetailMode as a9, MAX_PARSED_CLONES as aA, MAX_PARSED_PAGES as aB, MAX_PARSED_SETTINGS as aC, MAX_TEXT_OPTION_LENGTH as aD, MAX_WIDGET_OPTIONS as aE, MAX_WIDGET_TITLE_LENGTH as aF, MAX_WIDGET_VIEWS as aG, MAX_WIDGET_WIDTH as aH, MIN_WIDGET_WIDTH as aI, type NormalizeSettingsOptions as aJ, type NumberOption as aK, OPTION_KEY_PATTERN as aL, type Ok as aM, type OkWidget as aN, type OptionContext as aO, type OptionValue as aP, type PageRoom as aQ, type PlacedRow as aR, type ProviderOptions as aS, type ResolvedDetailOptions as aT, type ResolvedWidget as aU, type ResolvedWidgetLock as aV, type RetryOptions as aW, type SaveOptions as aX, type SavedLayout as aY, type SettingsItem as aZ, type SortDirection as a_, type DetailPage as aa, type DetailProvider as ab, type DetailProviders as ac, EMPTY_LAYOUT as ad, type EmptyWidget as ae, type EncodingOptions as af, type EnforceLocksOptions as ag, type Err as ah, type ErrorWidget as ai, type FormatOptions as aj, type GraphPoint as ak, type GraphSeries as al, type GridItem as am, type KpiDelta as an, type KpiDeltaOptions as ao, LAYOUT_ENVELOPE_VERSION as ap, type LayoutItem as aq, type LayoutPage as ar, type LayoutPersistenceOptions as as, type LayoutSettings as at, type LoadedLayout as au, type LoadingWidget as av, MAX_DETAIL_PAGE_SIZE as aw, MAX_GRAPH_SERIES as ax, MAX_PAGE_ROWS as ay, MAX_PAGE_TITLE_LENGTH as az, type WidgetDefinition as b, hasPages as b$, type StorageAdapter as b0, type StorageLogEvent as b1, type StoreErrorCode as b2, type StoreResult as b3, type StoredValue as b4, type TableCell as b5, type TableColumn as b6, type TextOption as b7, VALUE_FORMATS as b8, VIEW_CONVERSIONS as b9, clearWidgetSettings as bA, cloneNumber as bB, coerceOptionValue as bC, convertView as bD, createLayoutPersistence as bE, defaultDetailQuery as bF, defaultOptionValue as bG, defineWidget as bH, deriveDetailData as bI, describeUnknownError as bJ, effectiveDefinitions as bK, effectiveViewKey as bL, emptyTextFor as bM, emptyWidget as bN, enforceLocks as bO, err as bP, failedWidget as bQ, fillColumnSpans as bR, fillWidthSpans as bS, fillsHeight as bT, fillsWidth as bU, finalizeWidget as bV, findView as bW, fitCount as bX, formatCount as bY, formatPercentChange as bZ, formatValue as b_, type ValueFormat as ba, type ViewConversion as bb, type ViewsItem as bc, WIDGET_FILLS as bd, WIDGET_KINDS as be, WIDGET_OPTION_TYPES as bf, WIDGET_SIZES as bg, WIDTH_COLUMNS as bh, type WidgetCache as bi, type WidgetDataOf as bj, type WidgetDetailOptions as bk, type WidgetEmptyState as bl, type WidgetLock as bm, type WidgetOption as bn, type WidgetProvider as bo, type WidgetStatus as bp, type WidgetTableControls as bq, type WidgetView as br, addPage as bs, applyClientOptions as bt, applySettings as bu, applyView as bv, assignPages as bw, baseColumnSpan as bx, cacheKeyFor as by, cleanClones as bz, type DetailProviderOptions as c, resolveTableControls as c$, hasViews as c0, hiddenWidgets as c1, hideWidget as c2, isClientApplied as c3, isColumnKeyFor as c4, isFlexible as c5, isHidden as c6, isIsoInterval as c7, isMinimized as c8, isOptionsLocked as c9, normalizeTitle as cA, ok as cB, optionValuesFor as cC, optionValuesFromLayout as cD, optionsCacheSuffix as cE, pageLayout as cF, pageList as cG, pageOf as cH, pageRoom as cI, pageWidgets as cJ, parseClones as cK, parseDetailQuery as cL, parseLayout as cM, parseSettings as cN, parseSortValue as cO, percentChange as cP, placeRows as cQ, pruneLayout as cR, queryRows as cS, readOnly as cT, removePage as cU, renamePage as cV, resolveDateRange as cW, resolveDetailOptions as cX, resolveOptionValues as cY, resolvePageKey as cZ, resolvePayload as c_, isProviderView as ca, isTitleInUse as cb, isWidgetEmptyState as cc, isWidgetKind as cd, isWidgetVisibleTo as ce, isWidgetWidth as cf, itemWidth as cg, kindLabel as ch, kpiDelta as ci, labelStride as cj, loadViewKey as ck, loadViewKind as cl, loadingWidgets as cm, memoryAdapter as cn, minimizeWidget as co, movePage as cp, moveWidget as cq, moveWidgetBy as cr, moveWidgetDown as cs, moveWidgetToPage as ct, moveWidgetUp as cu, nextPageKey as cv, niceDomain as cw, niceStep as cx, normalizeLayout as cy, normalizeSettings as cz, type DetailData as d, resolveWidget as d0, resolveWidgetLock as d1, resolveWidgetUnapplied as d2, resolveWidgets as d3, restoreWidget as d4, sameOptionValues as d5, serializeClones as d6, serializeDetailQuery as d7, serializeLayout as d8, serializeSettings as d9, withPageLayout as dA, withPrefix as dB, withReadCache as dC, withRetry as dD, setWidgetSettings as da, shareOf as db, showWidget as dc, sortDefinitions as dd, sortFromOptions as de, tableDetailData as df, toggleHidden as dg, toggleMinimized as dh, usesWidthColumns as di, utf8Length as dj, validateDetailData as dk, viewChoices as dl, viewKind as dm, viewNote as dn, viewValuesFromLayout as dp, visibleWidgets as dq, widgetOptionValues as dr, widgetsFor as ds, widthForSize as dt, widthRange as du, widthShareLabel as dv, withClones as dw, withEncoding as dx, withFallback as dy, withLogging as dz, type DetailQuery as e, type DashboardLayout as f, type WidgetViewerSettings as g, type WidgetSettingsPatch as h, type GaugeWidgetData as i, type DetailSort as j, type TextWidgetData as k, type WidgetData as l, type LayoutPersistence as m, type NormalizeOptions as n, type ResolveOptions as o, type WidgetContext as p, type WidgetProviders as q, type PageOptions as r, type Result as s, type WidgetClone as t, type WidgetKind as u, type WidgetPayload as v, type AddPageOptions as w, type AlertListItem as x, BASE_VIEW_KEY as y, type BarListItem as z };

package/dist/{storage-oivwB7al.d.ts → storage-CRBfjiVZ.d.ts}

@@ -431,6 +431,14 @@ interface ProviderOptions {
      * and check them again on the server.
      */
     readonly options: OptionValues;
+    /**
+     * The view being loaded: `base` (the widget's own kind) unless the viewer
+     * chose a view the provider supplies (a `views` entry without `convert`), in
+     * which case it is that view's key and the payload must be of that view's
+     * kind. Converted views never reach the provider: they are built from the
+     * `base` payload.
+     */
+    readonly view: string;
 }
 /**
  * Loads one widget's payload. May be sync or async; may throw. The third
@@ -450,6 +458,11 @@ interface OkWidget {
     readonly stale?: boolean;
     /** The widget's resolved option values; present when it declares options. */
     readonly options?: OptionValues;
+    /**
+     * The view this data was loaded for (`base` or a provider-supplied view's
+     * key); present when the widget declares `views`.
+     */
+    readonly view?: string;
 }
 interface EmptyWidget {
     readonly definition: WidgetDefinition;
@@ -500,6 +513,13 @@ interface ResolveOptions extends OptionContext {
      * and the option's default is used.
      */
     readonly optionValues?: Readonly<Record<string, Readonly<Record<string, unknown>> | undefined>>;
+    /**
+     * The view each widget shows, by widget key. Only views the provider
+     * supplies matter here (the provider is asked for that view); converted
+     * views are applied later from the base payload. An empty string means no
+     * choice (the widget's `defaultView`).
+     */
+    readonly viewValues?: Readonly<Record<string, string | undefined>>;
     /**
      * Validate each provider's payload with `validateWidgetData` (and check
      * its kind matches the definition). Default true; turn off only for
@@ -668,7 +688,7 @@ interface DetailQuery {
     readonly pageSize: number;
 }
 /** What a detail provider receives beyond the usual arguments. */
-interface DetailProviderOptions extends ProviderOptions {
+interface DetailProviderOptions extends Omit<ProviderOptions, 'view'> {
     readonly query: DetailQuery;
 }
 /**
@@ -795,8 +815,14 @@ interface WidgetView {
     readonly label: string;
     /** What this view renders; must match what the conversion produces. */
     readonly kind: WidgetKind;
-    /** Builds this view from the widget's payload. */
-    readonly convert: ViewConversion;
+    /**
+     * Builds this view from the widget's payload. Leave it out and the provider
+     * supplies the view instead: it is called with `options.view` set to this
+     * view's key and returns a payload of `kind`. That costs one load per view
+     * (cached apart), and is the way to show data a conversion can't build, such
+     * as a trend behind a KPI.
+     */
+    readonly convert?: ViewConversion;
 }
 /** What these functions need from a definition. */
 type ViewsItem = Pick<WidgetDefinition, 'key' | 'kind'> & Partial<Pick<WidgetDefinition, 'views' | 'defaultView' | 'baseViewLabel'>>;
@@ -812,6 +838,8 @@ declare function viewChoices(item: ViewsItem): readonly {
     label: string;
     kind: WidgetKind;
 }[];
+/** Whether the provider supplies this view's payload (it has no `convert`). */
+declare function isProviderView(view: Pick<WidgetView, 'convert'>): boolean;
 /**
  * The view in effect: the viewer's pick when the definition declares it,
  * else `defaultView`, else the base. Always a valid key.
@@ -819,6 +847,14 @@ declare function viewChoices(item: ViewsItem): readonly {
 declare function effectiveViewKey(item: ViewsItem, chosen: string | undefined): string;
 /** The kind the widget renders as under this view key. */
 declare function viewKind(item: ViewsItem, chosen: string | undefined): WidgetKind;
+/**
+ * The view the provider is asked for under the viewer's choice: the chosen
+ * view when the provider supplies it, else `base` (converted views are built
+ * from the base payload, so switching among them never reloads).
+ */
+declare function loadViewKey(item: ViewsItem, chosen: string | undefined): string;
+/** The kind of payload the provider returns for `loadViewKey`. */
+declare function loadViewKind(item: ViewsItem, chosen: string | undefined): WidgetKind;
 /** Options for `convertView`. */
 interface ConvertViewOptions {
     /** Locale for numbers a conversion has to format (graph to table). */
@@ -837,10 +873,13 @@ declare function convertView(widgetKey: string, view: Pick<WidgetView, 'key' | '
  */
 declare function viewNote(view: WidgetView, data: WidgetData | undefined): string;
 /**
- * The widget as the chosen view shows it: the payload converted and the
- * definition's `kind` set to the view's kind, so renderers work unchanged.
- * A widget that isn't `ok`, or whose view is the base, comes back as is; a
- * failed conversion becomes an `error` widget naming the fix.
+ * The widget as the chosen view shows it. A converted view gets the payload
+ * converted; a view the provider supplies already holds its own payload. The
+ * definition's `kind` becomes the view's kind, so renderers work unchanged. A
+ * failed conversion becomes an `error` widget naming the fix, and data that
+ * was loaded for a different view (a switch is still loading) shows as
+ * `loading` rather than in the wrong shape. A widget that isn't `ok`, or whose
+ * view is the base, comes back as is.
  */
 declare function applyView<W extends DashboardWidget>(widget: W, chosen: string | undefined, options?: ConvertViewOptions): DashboardWidget;
 
@@ -1110,6 +1149,18 @@ declare function optionValuesFromLayout(definitions: readonly Pick<SettingsItem,
 }, options?: {
     readonly overrideLocks?: boolean;
 }): Record<string, Readonly<Record<string, OptionValue>>>;
+/**
+ * What to pass `useWidgets({ viewValues })` so views the provider supplies
+ * follow the layout: for every widget that declares one, the viewer's chosen
+ * view key, or an empty string for no choice (its `defaultView`). Listing
+ * every such widget means a cleared choice reaches the loader too. Widgets
+ * with only converted views are left out: they need no provider call.
+ */
+declare function viewValuesFromLayout(definitions: readonly Pick<SettingsItem, 'key' | 'views' | 'locked'>[], layout: {
+    readonly settings?: LayoutSettings;
+}, options?: {
+    readonly overrideLocks?: boolean;
+}): Record<string, string>;
 /** Fields `setWidgetSettings` can change; `undefined` clears one. */
 interface WidgetSettingsPatch {
     readonly title?: string | undefined;
@@ -1662,4 +1713,4 @@ interface LayoutPersistence {
  */
 declare function createLayoutPersistence(adapter: StorageAdapter, options?: LayoutPersistenceOptions): LayoutPersistence;
 
-export { DEFAULT_MAX_LAYOUT_BYTES as $, type AlertListWidgetData as A, type BarListWidgetData as B, type CloneOptions as C, type DashboardWidget as D, type BooleanOption as E, type CachedPayload as F, type GraphWidgetData as G, type ChoiceOption as H, type CloneItem as I, type ColorOption as J, type KpiWidgetData as K, type Locale as L, type ColumnsOption as M, type NiceDomain as N, type OptionValues as O, type PageItem as P, type ConflictPolicy as Q, type ResolvedTableControls as R, type StoreScope as S, type TableWidgetData as T, type ConvertViewOptions as U, DATE_RANGE_PRESETS as V, type WidgetSize as W, DEFAULT_COMPARISON_LABEL as X, DEFAULT_CURRENCY as Y, DEFAULT_DETAIL_PAGE_SIZE as Z, DEFAULT_EMPTY_TEXT as _, type WidgetFill as a, type SortOption as a$, DEFAULT_PAGE_KEY as a0, DEFAULT_PAGE_ROWS as a1, DETAIL_MODES as a2, type DateRangeOption as a3, type DateRangePreset as a4, type DeltaDirection as a5, type DeltaSentiment as a6, type DetailCell as a7, type DetailColumn as a8, type DetailMode as a9, MAX_PARSED_CLONES as aA, MAX_PARSED_PAGES as aB, MAX_PARSED_SETTINGS as aC, MAX_TEXT_OPTION_LENGTH as aD, MAX_WIDGET_OPTIONS as aE, MAX_WIDGET_TITLE_LENGTH as aF, MAX_WIDGET_VIEWS as aG, MAX_WIDGET_WIDTH as aH, MIN_WIDGET_WIDTH as aI, type NormalizeSettingsOptions as aJ, type NumberOption as aK, OPTION_KEY_PATTERN as aL, type Ok as aM, type OkWidget as aN, type OptionContext as aO, type OptionValue as aP, type PageRoom as aQ, type PlacedRow as aR, type ProviderOptions as aS, type ResolvedDetailOptions as aT, type ResolvedWidget as aU, type ResolvedWidgetLock as aV, type RetryOptions as aW, type SaveOptions as aX, type SavedLayout as aY, type SettingsItem as aZ, type SortDirection as a_, type DetailPage as aa, type DetailProvider as ab, type DetailProviders as ac, EMPTY_LAYOUT as ad, type EmptyWidget as ae, type EncodingOptions as af, type EnforceLocksOptions as ag, type Err as ah, type ErrorWidget as ai, type FormatOptions as aj, type GraphPoint as ak, type GraphSeries as al, type GridItem as am, type KpiDelta as an, type KpiDeltaOptions as ao, LAYOUT_ENVELOPE_VERSION as ap, type LayoutItem as aq, type LayoutPage as ar, type LayoutPersistenceOptions as as, type LayoutSettings as at, type LoadedLayout as au, type LoadingWidget as av, MAX_DETAIL_PAGE_SIZE as aw, MAX_GRAPH_SERIES as ax, MAX_PAGE_ROWS as ay, MAX_PAGE_TITLE_LENGTH as az, type WidgetDefinition as b, hasPages as b$, type StorageAdapter as b0, type StorageLogEvent as b1, type StoreErrorCode as b2, type StoreResult as b3, type StoredValue as b4, type TableCell as b5, type TableColumn as b6, type TextOption as b7, VALUE_FORMATS as b8, VIEW_CONVERSIONS as b9, clearWidgetSettings as bA, cloneNumber as bB, coerceOptionValue as bC, convertView as bD, createLayoutPersistence as bE, defaultDetailQuery as bF, defaultOptionValue as bG, defineWidget as bH, deriveDetailData as bI, describeUnknownError as bJ, effectiveDefinitions as bK, effectiveViewKey as bL, emptyTextFor as bM, emptyWidget as bN, enforceLocks as bO, err as bP, failedWidget as bQ, fillColumnSpans as bR, fillWidthSpans as bS, fillsHeight as bT, fillsWidth as bU, finalizeWidget as bV, findView as bW, fitCount as bX, formatCount as bY, formatPercentChange as bZ, formatValue as b_, type ValueFormat as ba, type ViewConversion as bb, type ViewsItem as bc, WIDGET_FILLS as bd, WIDGET_KINDS as be, WIDGET_OPTION_TYPES as bf, WIDGET_SIZES as bg, WIDTH_COLUMNS as bh, type WidgetCache as bi, type WidgetDataOf as bj, type WidgetDetailOptions as bk, type WidgetEmptyState as bl, type WidgetLock as bm, type WidgetOption as bn, type WidgetProvider as bo, type WidgetStatus as bp, type WidgetTableControls as bq, type WidgetView as br, addPage as bs, applyClientOptions as bt, applySettings as bu, applyView as bv, assignPages as bw, baseColumnSpan as bx, cacheKeyFor as by, cleanClones as bz, type DetailProviderOptions as c, resolveWidgetUnapplied as c$, hasViews as c0, hiddenWidgets as c1, hideWidget as c2, isClientApplied as c3, isColumnKeyFor as c4, isFlexible as c5, isHidden as c6, isIsoInterval as c7, isMinimized as c8, isOptionsLocked as c9, optionValuesFromLayout as cA, optionsCacheSuffix as cB, pageLayout as cC, pageList as cD, pageOf as cE, pageRoom as cF, pageWidgets as cG, parseClones as cH, parseDetailQuery as cI, parseLayout as cJ, parseSettings as cK, parseSortValue as cL, percentChange as cM, placeRows as cN, pruneLayout as cO, queryRows as cP, readOnly as cQ, removePage as cR, renamePage as cS, resolveDateRange as cT, resolveDetailOptions as cU, resolveOptionValues as cV, resolvePageKey as cW, resolvePayload as cX, resolveTableControls as cY, resolveWidget as cZ, resolveWidgetLock as c_, isTitleInUse as ca, isWidgetEmptyState as cb, isWidgetKind as cc, isWidgetVisibleTo as cd, isWidgetWidth as ce, itemWidth as cf, kindLabel as cg, kpiDelta as ch, labelStride as ci, loadingWidgets as cj, memoryAdapter as ck, minimizeWidget as cl, movePage as cm, moveWidget as cn, moveWidgetBy as co, moveWidgetDown as cp, moveWidgetToPage as cq, moveWidgetUp as cr, nextPageKey as cs, niceDomain as ct, niceStep as cu, normalizeLayout as cv, normalizeSettings as cw, normalizeTitle as cx, ok as cy, optionValuesFor as cz, type DetailData as d, resolveWidgets as d0, restoreWidget as d1, sameOptionValues as d2, serializeClones as d3, serializeDetailQuery as d4, serializeLayout as d5, serializeSettings as d6, setWidgetSettings as d7, shareOf as d8, showWidget as d9, sortDefinitions as da, sortFromOptions as db, tableDetailData as dc, toggleHidden as dd, toggleMinimized as de, usesWidthColumns as df, utf8Length as dg, validateDetailData as dh, viewChoices as di, viewKind as dj, viewNote as dk, visibleWidgets as dl, widgetOptionValues as dm, widgetsFor as dn, widthForSize as dp, widthRange as dq, widthShareLabel as dr, withClones as ds, withEncoding as dt, withFallback as du, withLogging as dv, withPageLayout as dw, withPrefix as dx, withReadCache as dy, withRetry as dz, type DetailQuery as e, type DashboardLayout as f, type WidgetViewerSettings as g, type WidgetSettingsPatch as h, type GaugeWidgetData as i, type DetailSort as j, type TextWidgetData as k, type WidgetData as l, type LayoutPersistence as m, type NormalizeOptions as n, type ResolveOptions as o, type WidgetContext as p, type WidgetProviders as q, type PageOptions as r, type Result as s, type WidgetClone as t, type WidgetKind as u, type WidgetPayload as v, type AddPageOptions as w, type AlertListItem as x, BASE_VIEW_KEY as y, type BarListItem as z };
+export { DEFAULT_MAX_LAYOUT_BYTES as $, type AlertListWidgetData as A, type BarListWidgetData as B, type CloneOptions as C, type DashboardWidget as D, type BooleanOption as E, type CachedPayload as F, type GraphWidgetData as G, type ChoiceOption as H, type CloneItem as I, type ColorOption as J, type KpiWidgetData as K, type Locale as L, type ColumnsOption as M, type NiceDomain as N, type OptionValues as O, type PageItem as P, type ConflictPolicy as Q, type ResolvedTableControls as R, type StoreScope as S, type TableWidgetData as T, type ConvertViewOptions as U, DATE_RANGE_PRESETS as V, type WidgetSize as W, DEFAULT_COMPARISON_LABEL as X, DEFAULT_CURRENCY as Y, DEFAULT_DETAIL_PAGE_SIZE as Z, DEFAULT_EMPTY_TEXT as _, type WidgetFill as a, type SortOption as a$, DEFAULT_PAGE_KEY as a0, DEFAULT_PAGE_ROWS as a1, DETAIL_MODES as a2, type DateRangeOption as a3, type DateRangePreset as a4, type DeltaDirection as a5, type DeltaSentiment as a6, type DetailCell as a7, type DetailColumn as a8, type DetailMode as a9, MAX_PARSED_CLONES as aA, MAX_PARSED_PAGES as aB, MAX_PARSED_SETTINGS as aC, MAX_TEXT_OPTION_LENGTH as aD, MAX_WIDGET_OPTIONS as aE, MAX_WIDGET_TITLE_LENGTH as aF, MAX_WIDGET_VIEWS as aG, MAX_WIDGET_WIDTH as aH, MIN_WIDGET_WIDTH as aI, type NormalizeSettingsOptions as aJ, type NumberOption as aK, OPTION_KEY_PATTERN as aL, type Ok as aM, type OkWidget as aN, type OptionContext as aO, type OptionValue as aP, type PageRoom as aQ, type PlacedRow as aR, type ProviderOptions as aS, type ResolvedDetailOptions as aT, type ResolvedWidget as aU, type ResolvedWidgetLock as aV, type RetryOptions as aW, type SaveOptions as aX, type SavedLayout as aY, type SettingsItem as aZ, type SortDirection as a_, type DetailPage as aa, type DetailProvider as ab, type DetailProviders as ac, EMPTY_LAYOUT as ad, type EmptyWidget as ae, type EncodingOptions as af, type EnforceLocksOptions as ag, type Err as ah, type ErrorWidget as ai, type FormatOptions as aj, type GraphPoint as ak, type GraphSeries as al, type GridItem as am, type KpiDelta as an, type KpiDeltaOptions as ao, LAYOUT_ENVELOPE_VERSION as ap, type LayoutItem as aq, type LayoutPage as ar, type LayoutPersistenceOptions as as, type LayoutSettings as at, type LoadedLayout as au, type LoadingWidget as av, MAX_DETAIL_PAGE_SIZE as aw, MAX_GRAPH_SERIES as ax, MAX_PAGE_ROWS as ay, MAX_PAGE_TITLE_LENGTH as az, type WidgetDefinition as b, hasPages as b$, type StorageAdapter as b0, type StorageLogEvent as b1, type StoreErrorCode as b2, type StoreResult as b3, type StoredValue as b4, type TableCell as b5, type TableColumn as b6, type TextOption as b7, VALUE_FORMATS as b8, VIEW_CONVERSIONS as b9, clearWidgetSettings as bA, cloneNumber as bB, coerceOptionValue as bC, convertView as bD, createLayoutPersistence as bE, defaultDetailQuery as bF, defaultOptionValue as bG, defineWidget as bH, deriveDetailData as bI, describeUnknownError as bJ, effectiveDefinitions as bK, effectiveViewKey as bL, emptyTextFor as bM, emptyWidget as bN, enforceLocks as bO, err as bP, failedWidget as bQ, fillColumnSpans as bR, fillWidthSpans as bS, fillsHeight as bT, fillsWidth as bU, finalizeWidget as bV, findView as bW, fitCount as bX, formatCount as bY, formatPercentChange as bZ, formatValue as b_, type ValueFormat as ba, type ViewConversion as bb, type ViewsItem as bc, WIDGET_FILLS as bd, WIDGET_KINDS as be, WIDGET_OPTION_TYPES as bf, WIDGET_SIZES as bg, WIDTH_COLUMNS as bh, type WidgetCache as bi, type WidgetDataOf as bj, type WidgetDetailOptions as bk, type WidgetEmptyState as bl, type WidgetLock as bm, type WidgetOption as bn, type WidgetProvider as bo, type WidgetStatus as bp, type WidgetTableControls as bq, type WidgetView as br, addPage as bs, applyClientOptions as bt, applySettings as bu, applyView as bv, assignPages as bw, baseColumnSpan as bx, cacheKeyFor as by, cleanClones as bz, type DetailProviderOptions as c, resolveTableControls as c$, hasViews as c0, hiddenWidgets as c1, hideWidget as c2, isClientApplied as c3, isColumnKeyFor as c4, isFlexible as c5, isHidden as c6, isIsoInterval as c7, isMinimized as c8, isOptionsLocked as c9, normalizeTitle as cA, ok as cB, optionValuesFor as cC, optionValuesFromLayout as cD, optionsCacheSuffix as cE, pageLayout as cF, pageList as cG, pageOf as cH, pageRoom as cI, pageWidgets as cJ, parseClones as cK, parseDetailQuery as cL, parseLayout as cM, parseSettings as cN, parseSortValue as cO, percentChange as cP, placeRows as cQ, pruneLayout as cR, queryRows as cS, readOnly as cT, removePage as cU, renamePage as cV, resolveDateRange as cW, resolveDetailOptions as cX, resolveOptionValues as cY, resolvePageKey as cZ, resolvePayload as c_, isProviderView as ca, isTitleInUse as cb, isWidgetEmptyState as cc, isWidgetKind as cd, isWidgetVisibleTo as ce, isWidgetWidth as cf, itemWidth as cg, kindLabel as ch, kpiDelta as ci, labelStride as cj, loadViewKey as ck, loadViewKind as cl, loadingWidgets as cm, memoryAdapter as cn, minimizeWidget as co, movePage as cp, moveWidget as cq, moveWidgetBy as cr, moveWidgetDown as cs, moveWidgetToPage as ct, moveWidgetUp as cu, nextPageKey as cv, niceDomain as cw, niceStep as cx, normalizeLayout as cy, normalizeSettings as cz, type DetailData as d, resolveWidget as d0, resolveWidgetLock as d1, resolveWidgetUnapplied as d2, resolveWidgets as d3, restoreWidget as d4, sameOptionValues as d5, serializeClones as d6, serializeDetailQuery as d7, serializeLayout as d8, serializeSettings as d9, withPageLayout as dA, withPrefix as dB, withReadCache as dC, withRetry as dD, setWidgetSettings as da, shareOf as db, showWidget as dc, sortDefinitions as dd, sortFromOptions as de, tableDetailData as df, toggleHidden as dg, toggleMinimized as dh, usesWidthColumns as di, utf8Length as dj, validateDetailData as dk, viewChoices as dl, viewKind as dm, viewNote as dn, viewValuesFromLayout as dp, visibleWidgets as dq, widgetOptionValues as dr, widgetsFor as ds, widthForSize as dt, widthRange as du, widthShareLabel as dv, withClones as dw, withEncoding as dx, withFallback as dy, withLogging as dz, type DetailQuery as e, type DashboardLayout as f, type WidgetViewerSettings as g, type WidgetSettingsPatch as h, type GaugeWidgetData as i, type DetailSort as j, type TextWidgetData as k, type WidgetData as l, type LayoutPersistence as m, type NormalizeOptions as n, type ResolveOptions as o, type WidgetContext as p, type WidgetProviders as q, type PageOptions as r, type Result as s, type WidgetClone as t, type WidgetKind as u, type WidgetPayload as v, type AddPageOptions as w, type AlertListItem as x, BASE_VIEW_KEY as y, type BarListItem as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@richardmcquiston01/dashboard-widgets-toolkit",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Framework-agnostic dashboard widget toolkit: typed widget definitions and data payloads (KPI, gauge, table, bar list, alert list, chart), user layout (order, hide, minimise), and React renderers. Bring your own data providers.",
   "keywords": [
     "dashboard",