@richardmcquiston01/dashboard-widgets-toolkit 0.14.0 → 0.15.0

package/dist/{storage-_Eb8Y98-.d.cts → storage-DwJ-vGJg.d.cts}

@@ -738,6 +738,112 @@ declare function tableDetailData(data: TableWidgetData): DetailData;
  */
 declare function deriveDetailData(data: WidgetData, locale?: Locale): DetailData | undefined;
 
+/**
+ * Alternate views: other ways to show the same data. A widget declares
+ * `views`, each one built from the widget's own payload by a named,
+ * parameterized conversion (data, not functions, so definitions stay JSON).
+ * Switching is instant: no second load. Pure functions, no I/O.
+ */
+
+/** The key of the widget's own kind, always available as a view. */
+declare const BASE_VIEW_KEY = "base";
+/** Most views one widget may declare, the base view not counted. */
+declare const MAX_WIDGET_VIEWS = 8;
+/** How a view is built from the widget's payload. */
+type ViewConversion = {
+    readonly type: 'tableToBarList';
+    /** Column index of the bar labels. */
+    readonly label: number;
+    /** Column index of the bar values (cells need a numeric `value`). */
+    readonly value: number;
+} | {
+    readonly type: 'tableToGraph';
+    /** Column index of the x labels. */
+    readonly label: number;
+    /** Column indexes of the series (cells need a numeric `value`). */
+    readonly values: readonly number[];
+    readonly chartType: 'bar' | 'line';
+    /** How the numbers read. Default `number`. */
+    readonly valueFormat?: ValueFormat;
+    readonly currency?: string;
+} | {
+    readonly type: 'barListToTable';
+    /** Heading of the label column. Default "Name". */
+    readonly labelHeading?: string;
+    /** Heading of the value column. Default "Value". */
+    readonly valueHeading?: string;
+} | {
+    readonly type: 'graphToTable';
+} | {
+    readonly type: 'barListToGraph';
+    readonly chartType: 'bar' | 'line';
+    /** Name of the one series. Default "Value". */
+    readonly seriesName?: string;
+    readonly valueFormat?: ValueFormat;
+    readonly currency?: string;
+};
+/** The kinds a conversion reads and produces. */
+declare const VIEW_CONVERSIONS: Readonly<Record<ViewConversion['type'], {
+    from: WidgetKind;
+    to: WidgetKind;
+}>>;
+/** One alternate way to show a widget. */
+interface WidgetView {
+    /** Unique within the widget; not `base`. Stored in the viewer's settings. */
+    readonly key: string;
+    /** What the viewer sees in the View field, e.g. "Bars". */
+    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;
+}
+/** What these functions need from a definition. */
+type ViewsItem = Pick<WidgetDefinition, 'key' | 'kind'> & Partial<Pick<WidgetDefinition, 'views' | 'defaultView' | 'baseViewLabel'>>;
+/** A kind's plain name, used for the base view unless `baseViewLabel` is set. */
+declare function kindLabel(kind: WidgetKind): string;
+/** Whether the definition offers a choice of views. */
+declare function hasViews(item: Pick<ViewsItem, 'views'>): boolean;
+/** The view with this key, or undefined (`base` is not a declared view). */
+declare function findView(item: Pick<ViewsItem, 'views'>, key: string): WidgetView | undefined;
+/** Every view a viewer may pick: the base first, then the declared ones. */
+declare function viewChoices(item: ViewsItem): readonly {
+    key: string;
+    label: string;
+    kind: WidgetKind;
+}[];
+/**
+ * The view in effect: the viewer's pick when the definition declares it,
+ * else `defaultView`, else the base. Always a valid key.
+ */
+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;
+/** Options for `convertView`. */
+interface ConvertViewOptions {
+    /** Locale for numbers a conversion has to format (graph to table). */
+    readonly locale?: Locale;
+}
+/**
+ * Builds a view's payload from the widget's payload. The error names the
+ * widget, the view and what to fix, for example `Widget "top-products" view
+ * "bars": row 3, column 2 ("Sold") has no numeric value. Add value to the
+ * cells.` Never throws.
+ */
+declare function convertView(widgetKey: string, view: Pick<WidgetView, 'key' | 'convert'>, data: WidgetData, options?: ConvertViewOptions): Result<WidgetData>;
+/**
+ * What a view keeps of a table, for the dialog: "Shows Name and Sold only."
+ * Empty when the view loses nothing worth saying.
+ */
+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.
+ */
+declare function applyView<W extends DashboardWidget>(widget: W, chosen: string | undefined, options?: ConvertViewOptions): DashboardWidget;
+
 /** 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];
@@ -815,6 +921,16 @@ interface WidgetDefinition {
      * `ProviderOptions.options`. See `options.ts`.
      */
     readonly options?: readonly WidgetOption[];
+    /**
+     * Other ways to show this widget, built from its payload by a named
+     * conversion (a table as bars or a chart). The widget's own `kind` is
+     * always available as the view `base`. See `views.ts`.
+     */
+    readonly views?: readonly WidgetView[];
+    /** The view shown until a viewer picks another: `base` or a `views` key. Default `base`. */
+    readonly defaultView?: string;
+    /** What the base view is called in the View field. Default: its kind's name. */
+    readonly baseViewLabel?: string;
 }
 /** What a viewer may not do to a locked widget. */
 interface WidgetLock {
@@ -927,6 +1043,8 @@ interface WidgetViewerSettings {
     readonly flexible?: boolean;
     /** Values for declared options, by option key. */
     readonly options?: Readonly<Record<string, OptionValue>>;
+    /** The view to show: `base` or a key from the definition's `views`. */
+    readonly view?: string;
 }
 /** Viewer settings by widget key. */
 type LayoutSettings = Readonly<Record<string, WidgetViewerSettings>>;
@@ -938,7 +1056,7 @@ declare const MAX_WIDGET_TITLE_LENGTH = 80;
  */
 declare const MAX_PARSED_SETTINGS = 500;
 /** What these functions need from a definition. */
-type SettingsItem = Pick<WidgetDefinition, 'key'> & Partial<Pick<WidgetDefinition, 'title' | 'width' | 'minWidth' | 'maxWidth' | 'fill' | 'locked' | 'options'>>;
+type SettingsItem = Pick<WidgetDefinition, 'key'> & Partial<Pick<WidgetDefinition, 'title' | 'width' | 'minWidth' | 'maxWidth' | 'fill' | 'locked' | 'options' | 'views' | 'defaultView'>>;
 /**
  * Reads the `settings` field of a saved layout. Anything malformed is
  * dropped (wrong types, titles over the limit are cut, widths outside 2 to
@@ -999,6 +1117,8 @@ interface WidgetSettingsPatch {
     readonly flexible?: boolean | undefined;
     /** Replaces all of the widget's option values (`undefined` clears them). */
     readonly options?: Readonly<Record<string, OptionValue>> | undefined;
+    /** The view key (`base` or a declared view); `undefined` clears it. */
+    readonly view?: string | undefined;
 }
 type LayoutWithSettings<L> = L & {
     readonly settings?: LayoutSettings;
@@ -1471,4 +1591,4 @@ interface LayoutPersistence {
  */
 declare function createLayoutPersistence(adapter: StorageAdapter, options?: LayoutPersistenceOptions): LayoutPersistence;
 
-export { type DeltaDirection as $, type AlertListWidgetData as A, type BarListWidgetData as B, type CachedPayload as C, type DashboardWidget as D, type ColumnsOption as E, type ConflictPolicy as F, type GraphWidgetData as G, DATE_RANGE_PRESETS as H, DEFAULT_COMPARISON_LABEL as I, DEFAULT_CURRENCY as J, type KpiWidgetData as K, type Locale as L, DEFAULT_DETAIL_PAGE_SIZE as M, type NiceDomain as N, type OptionValues as O, type PageItem as P, DEFAULT_EMPTY_TEXT as Q, type ResolvedTableControls as R, type StoreScope as S, type TableWidgetData as T, DEFAULT_MAX_LAYOUT_BYTES as U, DEFAULT_PAGE_KEY as V, type WidgetSize as W, DEFAULT_PAGE_ROWS as X, DETAIL_MODES as Y, type DateRangeOption as Z, type DateRangePreset as _, type WidgetFill as a, type TableColumn as a$, type DeltaSentiment as a0, type DetailCell as a1, type DetailColumn as a2, type DetailMode as a3, type DetailPage as a4, type DetailProvider as a5, type DetailProviders as a6, EMPTY_LAYOUT as a7, type EmptyWidget as a8, type EncodingOptions as a9, MIN_WIDGET_WIDTH as aA, type NormalizeSettingsOptions as aB, type NumberOption as aC, OPTION_KEY_PATTERN as aD, type Ok as aE, type OkWidget as aF, type OptionContext as aG, type OptionValue as aH, type PageOptions as aI, type PageRoom as aJ, type PlacedRow as aK, type ProviderOptions as aL, type ResolvedDetailOptions as aM, type ResolvedWidget as aN, type ResolvedWidgetLock as aO, type RetryOptions as aP, type SaveOptions as aQ, type SavedLayout as aR, type SettingsItem as aS, type SortDirection as aT, type SortOption as aU, type StorageAdapter as aV, type StorageLogEvent as aW, type StoreErrorCode as aX, type StoreResult as aY, type StoredValue as aZ, type TableCell as a_, type EnforceLocksOptions as aa, type Err as ab, type ErrorWidget as ac, type FormatOptions as ad, type GraphPoint as ae, type GraphSeries as af, type GridItem as ag, type KpiDelta as ah, type KpiDeltaOptions as ai, LAYOUT_ENVELOPE_VERSION as aj, type LayoutItem as ak, type LayoutPage as al, type LayoutPersistenceOptions as am, type LayoutSettings as an, type LoadedLayout as ao, type LoadingWidget as ap, MAX_DETAIL_PAGE_SIZE as aq, MAX_GRAPH_SERIES as ar, MAX_PAGE_ROWS as as, MAX_PAGE_TITLE_LENGTH as at, MAX_PARSED_PAGES as au, MAX_PARSED_SETTINGS as av, MAX_TEXT_OPTION_LENGTH as aw, MAX_WIDGET_OPTIONS as ax, MAX_WIDGET_TITLE_LENGTH as ay, MAX_WIDGET_WIDTH as az, type WidgetDefinition as b, labelStride as b$, type TextOption as b0, VALUE_FORMATS as b1, type ValueFormat as b2, WIDGET_FILLS as b3, WIDGET_KINDS as b4, WIDGET_OPTION_TYPES as b5, WIDGET_SIZES as b6, WIDTH_COLUMNS as b7, type WidgetCache as b8, type WidgetDataOf as b9, failedWidget as bA, fillColumnSpans as bB, fillWidthSpans as bC, fillsHeight as bD, fillsWidth as bE, finalizeWidget as bF, fitCount as bG, formatCount as bH, formatPercentChange as bI, formatValue as bJ, hasPages as bK, hiddenWidgets as bL, hideWidget as bM, isClientApplied as bN, isColumnKeyFor as bO, isFlexible as bP, isHidden as bQ, isIsoInterval as bR, isMinimized as bS, isOptionsLocked as bT, isTitleInUse as bU, isWidgetEmptyState as bV, isWidgetKind as bW, isWidgetVisibleTo as bX, isWidgetWidth as bY, itemWidth as bZ, kpiDelta as b_, type WidgetDetailOptions as ba, type WidgetEmptyState as bb, type WidgetLock as bc, type WidgetOption as bd, type WidgetProvider as be, type WidgetStatus as bf, type WidgetTableControls as bg, addPage as bh, applyClientOptions as bi, applySettings as bj, assignPages as bk, baseColumnSpan as bl, cacheKeyFor as bm, clearWidgetSettings as bn, coerceOptionValue as bo, createLayoutPersistence as bp, defaultDetailQuery as bq, defaultOptionValue as br, defineWidget as bs, deriveDetailData as bt, describeUnknownError as bu, effectiveDefinitions as bv, emptyTextFor as bw, emptyWidget as bx, enforceLocks as by, err as bz, type DetailProviderOptions as c, widgetsFor as c$, loadingWidgets as c0, memoryAdapter as c1, minimizeWidget as c2, movePage as c3, moveWidget as c4, moveWidgetBy as c5, moveWidgetDown as c6, moveWidgetToPage as c7, moveWidgetUp as c8, nextPageKey as c9, resolveDetailOptions as cA, resolveOptionValues as cB, resolvePageKey as cC, resolvePayload as cD, resolveTableControls as cE, resolveWidget as cF, resolveWidgetLock as cG, resolveWidgetUnapplied as cH, resolveWidgets as cI, restoreWidget as cJ, sameOptionValues as cK, serializeDetailQuery as cL, serializeLayout as cM, serializeSettings as cN, setWidgetSettings as cO, shareOf as cP, showWidget as cQ, sortDefinitions as cR, sortFromOptions as cS, tableDetailData as cT, toggleHidden as cU, toggleMinimized as cV, usesWidthColumns as cW, utf8Length as cX, validateDetailData as cY, visibleWidgets as cZ, widgetOptionValues as c_, niceDomain as ca, niceStep as cb, normalizeLayout as cc, normalizeSettings as cd, normalizeTitle as ce, ok as cf, optionValuesFor as cg, optionValuesFromLayout as ch, optionsCacheSuffix as ci, pageLayout as cj, pageList as ck, pageOf as cl, pageRoom as cm, pageWidgets as cn, parseDetailQuery as co, parseLayout as cp, parseSettings as cq, parseSortValue as cr, percentChange as cs, placeRows as ct, pruneLayout as cu, queryRows as cv, readOnly as cw, removePage as cx, renamePage as cy, resolveDateRange as cz, type DetailData as d, widthForSize as d0, widthRange as d1, widthShareLabel as d2, withEncoding as d3, withFallback as d4, withLogging as d5, withPageLayout as d6, withPrefix as d7, withReadCache as d8, withRetry as d9, 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 Result as r, type WidgetKind as s, type WidgetPayload as t, type AddPageOptions as u, type AlertListItem as v, type BarListItem as w, type BooleanOption as x, type ChoiceOption as y, type ColorOption as z };
+export { type DateRangeOption as $, type AlertListWidgetData as A, type BarListWidgetData as B, type CachedPayload as C, type DashboardWidget as D, type ColorOption as E, type ColumnsOption as F, type GraphWidgetData as G, type ConflictPolicy as H, type ConvertViewOptions as I, DATE_RANGE_PRESETS as J, type KpiWidgetData as K, type Locale as L, DEFAULT_COMPARISON_LABEL as M, type NiceDomain as N, type OptionValues as O, type PageItem as P, DEFAULT_CURRENCY as Q, type ResolvedTableControls as R, type StoreScope as S, type TableWidgetData as T, DEFAULT_DETAIL_PAGE_SIZE as U, DEFAULT_EMPTY_TEXT as V, type WidgetSize as W, DEFAULT_MAX_LAYOUT_BYTES as X, DEFAULT_PAGE_KEY as Y, DEFAULT_PAGE_ROWS as Z, DETAIL_MODES as _, type WidgetFill as a, type StoreResult as a$, type DateRangePreset as a0, type DeltaDirection as a1, type DeltaSentiment as a2, type DetailCell as a3, type DetailColumn as a4, type DetailMode as a5, type DetailPage as a6, type DetailProvider as a7, type DetailProviders as a8, EMPTY_LAYOUT as a9, MAX_WIDGET_TITLE_LENGTH as aA, MAX_WIDGET_VIEWS as aB, MAX_WIDGET_WIDTH as aC, MIN_WIDGET_WIDTH as aD, type NormalizeSettingsOptions as aE, type NumberOption as aF, OPTION_KEY_PATTERN as aG, type Ok as aH, type OkWidget as aI, type OptionContext as aJ, type OptionValue as aK, type PageOptions as aL, type PageRoom as aM, type PlacedRow as aN, type ProviderOptions as aO, type ResolvedDetailOptions as aP, type ResolvedWidget as aQ, type ResolvedWidgetLock as aR, type RetryOptions as aS, type SaveOptions as aT, type SavedLayout as aU, type SettingsItem as aV, type SortDirection as aW, type SortOption as aX, type StorageAdapter as aY, type StorageLogEvent as aZ, type StoreErrorCode as a_, type EmptyWidget as aa, type EncodingOptions as ab, type EnforceLocksOptions as ac, type Err as ad, type ErrorWidget as ae, type FormatOptions as af, type GraphPoint as ag, type GraphSeries as ah, type GridItem as ai, type KpiDelta as aj, type KpiDeltaOptions as ak, LAYOUT_ENVELOPE_VERSION as al, type LayoutItem as am, type LayoutPage as an, type LayoutPersistenceOptions as ao, type LayoutSettings as ap, type LoadedLayout as aq, type LoadingWidget as ar, MAX_DETAIL_PAGE_SIZE as as, MAX_GRAPH_SERIES as at, MAX_PAGE_ROWS as au, MAX_PAGE_TITLE_LENGTH as av, MAX_PARSED_PAGES as aw, MAX_PARSED_SETTINGS as ax, MAX_TEXT_OPTION_LENGTH as ay, MAX_WIDGET_OPTIONS as az, type WidgetDefinition as b, isFlexible as b$, type StoredValue as b0, type TableCell as b1, type TableColumn as b2, type TextOption as b3, VALUE_FORMATS as b4, VIEW_CONVERSIONS as b5, type ValueFormat as b6, type ViewConversion as b7, type ViewsItem as b8, WIDGET_FILLS as b9, defaultOptionValue as bA, defineWidget as bB, deriveDetailData as bC, describeUnknownError as bD, effectiveDefinitions as bE, effectiveViewKey as bF, emptyTextFor as bG, emptyWidget as bH, enforceLocks as bI, err as bJ, failedWidget as bK, fillColumnSpans as bL, fillWidthSpans as bM, fillsHeight as bN, fillsWidth as bO, finalizeWidget as bP, findView as bQ, fitCount as bR, formatCount as bS, formatPercentChange as bT, formatValue as bU, hasPages as bV, hasViews as bW, hiddenWidgets as bX, hideWidget as bY, isClientApplied as bZ, isColumnKeyFor as b_, WIDGET_KINDS as ba, WIDGET_OPTION_TYPES as bb, WIDGET_SIZES as bc, WIDTH_COLUMNS as bd, type WidgetCache as be, type WidgetDataOf as bf, type WidgetDetailOptions as bg, type WidgetEmptyState as bh, type WidgetLock as bi, type WidgetOption as bj, type WidgetProvider as bk, type WidgetStatus as bl, type WidgetTableControls as bm, type WidgetView as bn, addPage as bo, applyClientOptions as bp, applySettings as bq, applyView as br, assignPages as bs, baseColumnSpan as bt, cacheKeyFor as bu, clearWidgetSettings as bv, coerceOptionValue as bw, convertView as bx, createLayoutPersistence as by, defaultDetailQuery as bz, type DetailProviderOptions as c, setWidgetSettings as c$, isHidden as c0, isIsoInterval as c1, isMinimized as c2, isOptionsLocked as c3, isTitleInUse as c4, isWidgetEmptyState as c5, isWidgetKind as c6, isWidgetVisibleTo as c7, isWidgetWidth as c8, itemWidth as c9, pageWidgets as cA, parseDetailQuery as cB, parseLayout as cC, parseSettings as cD, parseSortValue as cE, percentChange as cF, placeRows as cG, pruneLayout as cH, queryRows as cI, readOnly as cJ, removePage as cK, renamePage as cL, resolveDateRange as cM, resolveDetailOptions as cN, resolveOptionValues as cO, resolvePageKey as cP, resolvePayload as cQ, resolveTableControls as cR, resolveWidget as cS, resolveWidgetLock as cT, resolveWidgetUnapplied as cU, resolveWidgets as cV, restoreWidget as cW, sameOptionValues as cX, serializeDetailQuery as cY, serializeLayout as cZ, serializeSettings as c_, kindLabel as ca, kpiDelta as cb, labelStride as cc, loadingWidgets as cd, memoryAdapter as ce, minimizeWidget as cf, movePage as cg, moveWidget as ch, moveWidgetBy as ci, moveWidgetDown as cj, moveWidgetToPage as ck, moveWidgetUp as cl, nextPageKey as cm, niceDomain as cn, niceStep as co, normalizeLayout as cp, normalizeSettings as cq, normalizeTitle as cr, ok as cs, optionValuesFor as ct, optionValuesFromLayout as cu, optionsCacheSuffix as cv, pageLayout as cw, pageList as cx, pageOf as cy, pageRoom as cz, type DetailData as d, shareOf as d0, showWidget as d1, sortDefinitions as d2, sortFromOptions as d3, tableDetailData as d4, toggleHidden as d5, toggleMinimized as d6, usesWidthColumns as d7, utf8Length as d8, validateDetailData as d9, viewChoices as da, viewKind as db, viewNote as dc, visibleWidgets as dd, widgetOptionValues as de, widgetsFor as df, widthForSize as dg, widthRange as dh, widthShareLabel as di, withEncoding as dj, withFallback as dk, withLogging as dl, withPageLayout as dm, withPrefix as dn, withReadCache as dp, withRetry as dq, 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 Result as r, type WidgetKind as s, type WidgetPayload as t, type AddPageOptions as u, type AlertListItem as v, BASE_VIEW_KEY as w, type BarListItem as x, type BooleanOption as y, type ChoiceOption as z };

package/dist/{storage-_Eb8Y98-.d.ts → storage-DwJ-vGJg.d.ts}

@@ -738,6 +738,112 @@ declare function tableDetailData(data: TableWidgetData): DetailData;
  */
 declare function deriveDetailData(data: WidgetData, locale?: Locale): DetailData | undefined;
 
+/**
+ * Alternate views: other ways to show the same data. A widget declares
+ * `views`, each one built from the widget's own payload by a named,
+ * parameterized conversion (data, not functions, so definitions stay JSON).
+ * Switching is instant: no second load. Pure functions, no I/O.
+ */
+
+/** The key of the widget's own kind, always available as a view. */
+declare const BASE_VIEW_KEY = "base";
+/** Most views one widget may declare, the base view not counted. */
+declare const MAX_WIDGET_VIEWS = 8;
+/** How a view is built from the widget's payload. */
+type ViewConversion = {
+    readonly type: 'tableToBarList';
+    /** Column index of the bar labels. */
+    readonly label: number;
+    /** Column index of the bar values (cells need a numeric `value`). */
+    readonly value: number;
+} | {
+    readonly type: 'tableToGraph';
+    /** Column index of the x labels. */
+    readonly label: number;
+    /** Column indexes of the series (cells need a numeric `value`). */
+    readonly values: readonly number[];
+    readonly chartType: 'bar' | 'line';
+    /** How the numbers read. Default `number`. */
+    readonly valueFormat?: ValueFormat;
+    readonly currency?: string;
+} | {
+    readonly type: 'barListToTable';
+    /** Heading of the label column. Default "Name". */
+    readonly labelHeading?: string;
+    /** Heading of the value column. Default "Value". */
+    readonly valueHeading?: string;
+} | {
+    readonly type: 'graphToTable';
+} | {
+    readonly type: 'barListToGraph';
+    readonly chartType: 'bar' | 'line';
+    /** Name of the one series. Default "Value". */
+    readonly seriesName?: string;
+    readonly valueFormat?: ValueFormat;
+    readonly currency?: string;
+};
+/** The kinds a conversion reads and produces. */
+declare const VIEW_CONVERSIONS: Readonly<Record<ViewConversion['type'], {
+    from: WidgetKind;
+    to: WidgetKind;
+}>>;
+/** One alternate way to show a widget. */
+interface WidgetView {
+    /** Unique within the widget; not `base`. Stored in the viewer's settings. */
+    readonly key: string;
+    /** What the viewer sees in the View field, e.g. "Bars". */
+    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;
+}
+/** What these functions need from a definition. */
+type ViewsItem = Pick<WidgetDefinition, 'key' | 'kind'> & Partial<Pick<WidgetDefinition, 'views' | 'defaultView' | 'baseViewLabel'>>;
+/** A kind's plain name, used for the base view unless `baseViewLabel` is set. */
+declare function kindLabel(kind: WidgetKind): string;
+/** Whether the definition offers a choice of views. */
+declare function hasViews(item: Pick<ViewsItem, 'views'>): boolean;
+/** The view with this key, or undefined (`base` is not a declared view). */
+declare function findView(item: Pick<ViewsItem, 'views'>, key: string): WidgetView | undefined;
+/** Every view a viewer may pick: the base first, then the declared ones. */
+declare function viewChoices(item: ViewsItem): readonly {
+    key: string;
+    label: string;
+    kind: WidgetKind;
+}[];
+/**
+ * The view in effect: the viewer's pick when the definition declares it,
+ * else `defaultView`, else the base. Always a valid key.
+ */
+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;
+/** Options for `convertView`. */
+interface ConvertViewOptions {
+    /** Locale for numbers a conversion has to format (graph to table). */
+    readonly locale?: Locale;
+}
+/**
+ * Builds a view's payload from the widget's payload. The error names the
+ * widget, the view and what to fix, for example `Widget "top-products" view
+ * "bars": row 3, column 2 ("Sold") has no numeric value. Add value to the
+ * cells.` Never throws.
+ */
+declare function convertView(widgetKey: string, view: Pick<WidgetView, 'key' | 'convert'>, data: WidgetData, options?: ConvertViewOptions): Result<WidgetData>;
+/**
+ * What a view keeps of a table, for the dialog: "Shows Name and Sold only."
+ * Empty when the view loses nothing worth saying.
+ */
+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.
+ */
+declare function applyView<W extends DashboardWidget>(widget: W, chosen: string | undefined, options?: ConvertViewOptions): DashboardWidget;
+
 /** 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];
@@ -815,6 +921,16 @@ interface WidgetDefinition {
      * `ProviderOptions.options`. See `options.ts`.
      */
     readonly options?: readonly WidgetOption[];
+    /**
+     * Other ways to show this widget, built from its payload by a named
+     * conversion (a table as bars or a chart). The widget's own `kind` is
+     * always available as the view `base`. See `views.ts`.
+     */
+    readonly views?: readonly WidgetView[];
+    /** The view shown until a viewer picks another: `base` or a `views` key. Default `base`. */
+    readonly defaultView?: string;
+    /** What the base view is called in the View field. Default: its kind's name. */
+    readonly baseViewLabel?: string;
 }
 /** What a viewer may not do to a locked widget. */
 interface WidgetLock {
@@ -927,6 +1043,8 @@ interface WidgetViewerSettings {
     readonly flexible?: boolean;
     /** Values for declared options, by option key. */
     readonly options?: Readonly<Record<string, OptionValue>>;
+    /** The view to show: `base` or a key from the definition's `views`. */
+    readonly view?: string;
 }
 /** Viewer settings by widget key. */
 type LayoutSettings = Readonly<Record<string, WidgetViewerSettings>>;
@@ -938,7 +1056,7 @@ declare const MAX_WIDGET_TITLE_LENGTH = 80;
  */
 declare const MAX_PARSED_SETTINGS = 500;
 /** What these functions need from a definition. */
-type SettingsItem = Pick<WidgetDefinition, 'key'> & Partial<Pick<WidgetDefinition, 'title' | 'width' | 'minWidth' | 'maxWidth' | 'fill' | 'locked' | 'options'>>;
+type SettingsItem = Pick<WidgetDefinition, 'key'> & Partial<Pick<WidgetDefinition, 'title' | 'width' | 'minWidth' | 'maxWidth' | 'fill' | 'locked' | 'options' | 'views' | 'defaultView'>>;
 /**
  * Reads the `settings` field of a saved layout. Anything malformed is
  * dropped (wrong types, titles over the limit are cut, widths outside 2 to
@@ -999,6 +1117,8 @@ interface WidgetSettingsPatch {
     readonly flexible?: boolean | undefined;
     /** Replaces all of the widget's option values (`undefined` clears them). */
     readonly options?: Readonly<Record<string, OptionValue>> | undefined;
+    /** The view key (`base` or a declared view); `undefined` clears it. */
+    readonly view?: string | undefined;
 }
 type LayoutWithSettings<L> = L & {
     readonly settings?: LayoutSettings;
@@ -1471,4 +1591,4 @@ interface LayoutPersistence {
  */
 declare function createLayoutPersistence(adapter: StorageAdapter, options?: LayoutPersistenceOptions): LayoutPersistence;
 
-export { type DeltaDirection as $, type AlertListWidgetData as A, type BarListWidgetData as B, type CachedPayload as C, type DashboardWidget as D, type ColumnsOption as E, type ConflictPolicy as F, type GraphWidgetData as G, DATE_RANGE_PRESETS as H, DEFAULT_COMPARISON_LABEL as I, DEFAULT_CURRENCY as J, type KpiWidgetData as K, type Locale as L, DEFAULT_DETAIL_PAGE_SIZE as M, type NiceDomain as N, type OptionValues as O, type PageItem as P, DEFAULT_EMPTY_TEXT as Q, type ResolvedTableControls as R, type StoreScope as S, type TableWidgetData as T, DEFAULT_MAX_LAYOUT_BYTES as U, DEFAULT_PAGE_KEY as V, type WidgetSize as W, DEFAULT_PAGE_ROWS as X, DETAIL_MODES as Y, type DateRangeOption as Z, type DateRangePreset as _, type WidgetFill as a, type TableColumn as a$, type DeltaSentiment as a0, type DetailCell as a1, type DetailColumn as a2, type DetailMode as a3, type DetailPage as a4, type DetailProvider as a5, type DetailProviders as a6, EMPTY_LAYOUT as a7, type EmptyWidget as a8, type EncodingOptions as a9, MIN_WIDGET_WIDTH as aA, type NormalizeSettingsOptions as aB, type NumberOption as aC, OPTION_KEY_PATTERN as aD, type Ok as aE, type OkWidget as aF, type OptionContext as aG, type OptionValue as aH, type PageOptions as aI, type PageRoom as aJ, type PlacedRow as aK, type ProviderOptions as aL, type ResolvedDetailOptions as aM, type ResolvedWidget as aN, type ResolvedWidgetLock as aO, type RetryOptions as aP, type SaveOptions as aQ, type SavedLayout as aR, type SettingsItem as aS, type SortDirection as aT, type SortOption as aU, type StorageAdapter as aV, type StorageLogEvent as aW, type StoreErrorCode as aX, type StoreResult as aY, type StoredValue as aZ, type TableCell as a_, type EnforceLocksOptions as aa, type Err as ab, type ErrorWidget as ac, type FormatOptions as ad, type GraphPoint as ae, type GraphSeries as af, type GridItem as ag, type KpiDelta as ah, type KpiDeltaOptions as ai, LAYOUT_ENVELOPE_VERSION as aj, type LayoutItem as ak, type LayoutPage as al, type LayoutPersistenceOptions as am, type LayoutSettings as an, type LoadedLayout as ao, type LoadingWidget as ap, MAX_DETAIL_PAGE_SIZE as aq, MAX_GRAPH_SERIES as ar, MAX_PAGE_ROWS as as, MAX_PAGE_TITLE_LENGTH as at, MAX_PARSED_PAGES as au, MAX_PARSED_SETTINGS as av, MAX_TEXT_OPTION_LENGTH as aw, MAX_WIDGET_OPTIONS as ax, MAX_WIDGET_TITLE_LENGTH as ay, MAX_WIDGET_WIDTH as az, type WidgetDefinition as b, labelStride as b$, type TextOption as b0, VALUE_FORMATS as b1, type ValueFormat as b2, WIDGET_FILLS as b3, WIDGET_KINDS as b4, WIDGET_OPTION_TYPES as b5, WIDGET_SIZES as b6, WIDTH_COLUMNS as b7, type WidgetCache as b8, type WidgetDataOf as b9, failedWidget as bA, fillColumnSpans as bB, fillWidthSpans as bC, fillsHeight as bD, fillsWidth as bE, finalizeWidget as bF, fitCount as bG, formatCount as bH, formatPercentChange as bI, formatValue as bJ, hasPages as bK, hiddenWidgets as bL, hideWidget as bM, isClientApplied as bN, isColumnKeyFor as bO, isFlexible as bP, isHidden as bQ, isIsoInterval as bR, isMinimized as bS, isOptionsLocked as bT, isTitleInUse as bU, isWidgetEmptyState as bV, isWidgetKind as bW, isWidgetVisibleTo as bX, isWidgetWidth as bY, itemWidth as bZ, kpiDelta as b_, type WidgetDetailOptions as ba, type WidgetEmptyState as bb, type WidgetLock as bc, type WidgetOption as bd, type WidgetProvider as be, type WidgetStatus as bf, type WidgetTableControls as bg, addPage as bh, applyClientOptions as bi, applySettings as bj, assignPages as bk, baseColumnSpan as bl, cacheKeyFor as bm, clearWidgetSettings as bn, coerceOptionValue as bo, createLayoutPersistence as bp, defaultDetailQuery as bq, defaultOptionValue as br, defineWidget as bs, deriveDetailData as bt, describeUnknownError as bu, effectiveDefinitions as bv, emptyTextFor as bw, emptyWidget as bx, enforceLocks as by, err as bz, type DetailProviderOptions as c, widgetsFor as c$, loadingWidgets as c0, memoryAdapter as c1, minimizeWidget as c2, movePage as c3, moveWidget as c4, moveWidgetBy as c5, moveWidgetDown as c6, moveWidgetToPage as c7, moveWidgetUp as c8, nextPageKey as c9, resolveDetailOptions as cA, resolveOptionValues as cB, resolvePageKey as cC, resolvePayload as cD, resolveTableControls as cE, resolveWidget as cF, resolveWidgetLock as cG, resolveWidgetUnapplied as cH, resolveWidgets as cI, restoreWidget as cJ, sameOptionValues as cK, serializeDetailQuery as cL, serializeLayout as cM, serializeSettings as cN, setWidgetSettings as cO, shareOf as cP, showWidget as cQ, sortDefinitions as cR, sortFromOptions as cS, tableDetailData as cT, toggleHidden as cU, toggleMinimized as cV, usesWidthColumns as cW, utf8Length as cX, validateDetailData as cY, visibleWidgets as cZ, widgetOptionValues as c_, niceDomain as ca, niceStep as cb, normalizeLayout as cc, normalizeSettings as cd, normalizeTitle as ce, ok as cf, optionValuesFor as cg, optionValuesFromLayout as ch, optionsCacheSuffix as ci, pageLayout as cj, pageList as ck, pageOf as cl, pageRoom as cm, pageWidgets as cn, parseDetailQuery as co, parseLayout as cp, parseSettings as cq, parseSortValue as cr, percentChange as cs, placeRows as ct, pruneLayout as cu, queryRows as cv, readOnly as cw, removePage as cx, renamePage as cy, resolveDateRange as cz, type DetailData as d, widthForSize as d0, widthRange as d1, widthShareLabel as d2, withEncoding as d3, withFallback as d4, withLogging as d5, withPageLayout as d6, withPrefix as d7, withReadCache as d8, withRetry as d9, 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 Result as r, type WidgetKind as s, type WidgetPayload as t, type AddPageOptions as u, type AlertListItem as v, type BarListItem as w, type BooleanOption as x, type ChoiceOption as y, type ColorOption as z };
+export { type DateRangeOption as $, type AlertListWidgetData as A, type BarListWidgetData as B, type CachedPayload as C, type DashboardWidget as D, type ColorOption as E, type ColumnsOption as F, type GraphWidgetData as G, type ConflictPolicy as H, type ConvertViewOptions as I, DATE_RANGE_PRESETS as J, type KpiWidgetData as K, type Locale as L, DEFAULT_COMPARISON_LABEL as M, type NiceDomain as N, type OptionValues as O, type PageItem as P, DEFAULT_CURRENCY as Q, type ResolvedTableControls as R, type StoreScope as S, type TableWidgetData as T, DEFAULT_DETAIL_PAGE_SIZE as U, DEFAULT_EMPTY_TEXT as V, type WidgetSize as W, DEFAULT_MAX_LAYOUT_BYTES as X, DEFAULT_PAGE_KEY as Y, DEFAULT_PAGE_ROWS as Z, DETAIL_MODES as _, type WidgetFill as a, type StoreResult as a$, type DateRangePreset as a0, type DeltaDirection as a1, type DeltaSentiment as a2, type DetailCell as a3, type DetailColumn as a4, type DetailMode as a5, type DetailPage as a6, type DetailProvider as a7, type DetailProviders as a8, EMPTY_LAYOUT as a9, MAX_WIDGET_TITLE_LENGTH as aA, MAX_WIDGET_VIEWS as aB, MAX_WIDGET_WIDTH as aC, MIN_WIDGET_WIDTH as aD, type NormalizeSettingsOptions as aE, type NumberOption as aF, OPTION_KEY_PATTERN as aG, type Ok as aH, type OkWidget as aI, type OptionContext as aJ, type OptionValue as aK, type PageOptions as aL, type PageRoom as aM, type PlacedRow as aN, type ProviderOptions as aO, type ResolvedDetailOptions as aP, type ResolvedWidget as aQ, type ResolvedWidgetLock as aR, type RetryOptions as aS, type SaveOptions as aT, type SavedLayout as aU, type SettingsItem as aV, type SortDirection as aW, type SortOption as aX, type StorageAdapter as aY, type StorageLogEvent as aZ, type StoreErrorCode as a_, type EmptyWidget as aa, type EncodingOptions as ab, type EnforceLocksOptions as ac, type Err as ad, type ErrorWidget as ae, type FormatOptions as af, type GraphPoint as ag, type GraphSeries as ah, type GridItem as ai, type KpiDelta as aj, type KpiDeltaOptions as ak, LAYOUT_ENVELOPE_VERSION as al, type LayoutItem as am, type LayoutPage as an, type LayoutPersistenceOptions as ao, type LayoutSettings as ap, type LoadedLayout as aq, type LoadingWidget as ar, MAX_DETAIL_PAGE_SIZE as as, MAX_GRAPH_SERIES as at, MAX_PAGE_ROWS as au, MAX_PAGE_TITLE_LENGTH as av, MAX_PARSED_PAGES as aw, MAX_PARSED_SETTINGS as ax, MAX_TEXT_OPTION_LENGTH as ay, MAX_WIDGET_OPTIONS as az, type WidgetDefinition as b, isFlexible as b$, type StoredValue as b0, type TableCell as b1, type TableColumn as b2, type TextOption as b3, VALUE_FORMATS as b4, VIEW_CONVERSIONS as b5, type ValueFormat as b6, type ViewConversion as b7, type ViewsItem as b8, WIDGET_FILLS as b9, defaultOptionValue as bA, defineWidget as bB, deriveDetailData as bC, describeUnknownError as bD, effectiveDefinitions as bE, effectiveViewKey as bF, emptyTextFor as bG, emptyWidget as bH, enforceLocks as bI, err as bJ, failedWidget as bK, fillColumnSpans as bL, fillWidthSpans as bM, fillsHeight as bN, fillsWidth as bO, finalizeWidget as bP, findView as bQ, fitCount as bR, formatCount as bS, formatPercentChange as bT, formatValue as bU, hasPages as bV, hasViews as bW, hiddenWidgets as bX, hideWidget as bY, isClientApplied as bZ, isColumnKeyFor as b_, WIDGET_KINDS as ba, WIDGET_OPTION_TYPES as bb, WIDGET_SIZES as bc, WIDTH_COLUMNS as bd, type WidgetCache as be, type WidgetDataOf as bf, type WidgetDetailOptions as bg, type WidgetEmptyState as bh, type WidgetLock as bi, type WidgetOption as bj, type WidgetProvider as bk, type WidgetStatus as bl, type WidgetTableControls as bm, type WidgetView as bn, addPage as bo, applyClientOptions as bp, applySettings as bq, applyView as br, assignPages as bs, baseColumnSpan as bt, cacheKeyFor as bu, clearWidgetSettings as bv, coerceOptionValue as bw, convertView as bx, createLayoutPersistence as by, defaultDetailQuery as bz, type DetailProviderOptions as c, setWidgetSettings as c$, isHidden as c0, isIsoInterval as c1, isMinimized as c2, isOptionsLocked as c3, isTitleInUse as c4, isWidgetEmptyState as c5, isWidgetKind as c6, isWidgetVisibleTo as c7, isWidgetWidth as c8, itemWidth as c9, pageWidgets as cA, parseDetailQuery as cB, parseLayout as cC, parseSettings as cD, parseSortValue as cE, percentChange as cF, placeRows as cG, pruneLayout as cH, queryRows as cI, readOnly as cJ, removePage as cK, renamePage as cL, resolveDateRange as cM, resolveDetailOptions as cN, resolveOptionValues as cO, resolvePageKey as cP, resolvePayload as cQ, resolveTableControls as cR, resolveWidget as cS, resolveWidgetLock as cT, resolveWidgetUnapplied as cU, resolveWidgets as cV, restoreWidget as cW, sameOptionValues as cX, serializeDetailQuery as cY, serializeLayout as cZ, serializeSettings as c_, kindLabel as ca, kpiDelta as cb, labelStride as cc, loadingWidgets as cd, memoryAdapter as ce, minimizeWidget as cf, movePage as cg, moveWidget as ch, moveWidgetBy as ci, moveWidgetDown as cj, moveWidgetToPage as ck, moveWidgetUp as cl, nextPageKey as cm, niceDomain as cn, niceStep as co, normalizeLayout as cp, normalizeSettings as cq, normalizeTitle as cr, ok as cs, optionValuesFor as ct, optionValuesFromLayout as cu, optionsCacheSuffix as cv, pageLayout as cw, pageList as cx, pageOf as cy, pageRoom as cz, type DetailData as d, shareOf as d0, showWidget as d1, sortDefinitions as d2, sortFromOptions as d3, tableDetailData as d4, toggleHidden as d5, toggleMinimized as d6, usesWidthColumns as d7, utf8Length as d8, validateDetailData as d9, viewChoices as da, viewKind as db, viewNote as dc, visibleWidgets as dd, widgetOptionValues as de, widgetsFor as df, widthForSize as dg, widthRange as dh, widthShareLabel as di, withEncoding as dj, withFallback as dk, withLogging as dl, withPageLayout as dm, withPrefix as dn, withReadCache as dp, withRetry as dq, 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 Result as r, type WidgetKind as s, type WidgetPayload as t, type AddPageOptions as u, type AlertListItem as v, BASE_VIEW_KEY as w, type BarListItem as x, type BooleanOption as y, type ChoiceOption as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@richardmcquiston01/dashboard-widgets-toolkit",
-  "version": "0.14.0",
+  "version": "0.15.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",