@richardmcquiston01/dashboard-widgets-toolkit 0.1.0 → 0.4.0

package/dist/core.d.cts

@@ -1,5 +1,5 @@
-import { e as WidgetDefinition, f as WidgetKind, g as WidgetPayload } from './scale-WlRozDCf.cjs';
-export { h as AlertListItem, A as AlertListWidgetData, i as BarListItem, B as BarListWidgetData, j as DEFAULT_COMPARISON_LABEL, k as DEFAULT_CURRENCY, l as DEFAULT_EMPTY_TEXT, a as DashboardLayout, D as DashboardWidget, m as DeltaDirection, n as DeltaSentiment, E as EMPTY_LAYOUT, o as EmptyWidget, p as ErrorWidget, F as FormatOptions, b as GaugeWidgetData, q as GraphPoint, r as GraphSeries, G as GraphWidgetData, s as KpiDelta, t as KpiDeltaOptions, K as KpiWidgetData, u as LayoutItem, v as LoadingWidget, L as Locale, M as MAX_GRAPH_SERIES, N as NiceDomain, O as OkWidget, R as ResolveOptions, w as ResolvedWidget, x as TableCell, y as TableColumn, T as TableWidgetData, c as TextWidgetData, V as VALUE_FORMATS, z as ValueFormat, C as WIDGET_KINDS, H as WIDGET_SIZES, I as WidgetContext, d as WidgetData, J as WidgetDataOf, P as WidgetEmptyState, Q as WidgetProvider, S as WidgetProviders, W as WidgetSize, U as WidgetStatus, X as defineWidget, Y as emptyTextFor, Z as emptyWidget, _ as failedWidget, $ as formatCount, a0 as formatPercentChange, a1 as formatValue, a2 as hiddenWidgets, a3 as hideWidget, a4 as isHidden, a5 as isMinimized, a6 as isWidgetEmptyState, a7 as isWidgetKind, a8 as isWidgetVisibleTo, a9 as kpiDelta, aa as labelStride, ab as loadingWidgets, ac as minimizeWidget, ad as moveWidget, ae as moveWidgetBy, af as moveWidgetDown, ag as moveWidgetUp, ah as niceDomain, ai as niceStep, aj as parseLayout, ak as percentChange, al as pruneLayout, am as resolvePayload, an as resolveWidget, ao as resolveWidgets, ap as restoreWidget, aq as serializeLayout, ar as shareOf, as as showWidget, at as sortDefinitions, au as toggleHidden, av as toggleMinimized, aw as visibleWidgets, ax as widgetsFor } from './scale-WlRozDCf.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
@@ -33,25 +33,94 @@ interface LegacyWidgetDefinition {
  */
 declare function fromLegacyDefinition(legacy: LegacyWidgetDefinition): WidgetDefinition | null;
 
+/** The parts of a widget definition that decide its place in a grid. */
+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. */
+declare function fillsHeight(fill: WidgetFill | undefined): boolean;
+/**
+ * Columns a size takes in a grid of `columns` tracks: `large` spans
+ * `largeSpan` (default 2), `full` spans every column, anything else one.
+ */
+declare function baseColumnSpan(size: WidgetSize | undefined, columns: number, largeSpan?: number): number;
+/**
+ * Places `items` in a grid of `columns` tracks the way a sparse grid
+ * auto-places them (left to right, wrapping to a new row when an item does
+ * not fit), then gives the columns left over in each row to the items that
+ * `fill` their width, shared evenly (earlier items get the remainder).
+ *
+ * Returns the column span for each width-filling item, keyed by `key`. Items
+ * 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>;
 /**
- * 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.
+ * Like `fillColumnSpans` for a 12-column grid: each item starts at its
+ * `width` (see `itemWidth`) and width-fillers share the leftover twelfths.
  */
-interface Ok<T> {
-    readonly ok: true;
-    readonly value: T;
+declare function fillWidthSpans(items: readonly GridItem[]): Map<string, number>;
+
+/**
+ * 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 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
@@ -90,4 +159,4 @@ declare function validateWidgetData(value: unknown, options?: ValidateWidgetData
  */
 declare function validateWidgetDefinition(value: unknown): Result<WidgetDefinition>;
 
-export { type Err, type LegacyWidgetDefinition, MAX_REPORTED_PROBLEMS, type Ok, type Result, type ValidateWidgetDataOptions, WidgetDefinition, WidgetKind, WidgetPayload, describeUnknownError, err, 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 { e as WidgetDefinition, f as WidgetKind, g as WidgetPayload } from './scale-WlRozDCf.js';
-export { h as AlertListItem, A as AlertListWidgetData, i as BarListItem, B as BarListWidgetData, j as DEFAULT_COMPARISON_LABEL, k as DEFAULT_CURRENCY, l as DEFAULT_EMPTY_TEXT, a as DashboardLayout, D as DashboardWidget, m as DeltaDirection, n as DeltaSentiment, E as EMPTY_LAYOUT, o as EmptyWidget, p as ErrorWidget, F as FormatOptions, b as GaugeWidgetData, q as GraphPoint, r as GraphSeries, G as GraphWidgetData, s as KpiDelta, t as KpiDeltaOptions, K as KpiWidgetData, u as LayoutItem, v as LoadingWidget, L as Locale, M as MAX_GRAPH_SERIES, N as NiceDomain, O as OkWidget, R as ResolveOptions, w as ResolvedWidget, x as TableCell, y as TableColumn, T as TableWidgetData, c as TextWidgetData, V as VALUE_FORMATS, z as ValueFormat, C as WIDGET_KINDS, H as WIDGET_SIZES, I as WidgetContext, d as WidgetData, J as WidgetDataOf, P as WidgetEmptyState, Q as WidgetProvider, S as WidgetProviders, W as WidgetSize, U as WidgetStatus, X as defineWidget, Y as emptyTextFor, Z as emptyWidget, _ as failedWidget, $ as formatCount, a0 as formatPercentChange, a1 as formatValue, a2 as hiddenWidgets, a3 as hideWidget, a4 as isHidden, a5 as isMinimized, a6 as isWidgetEmptyState, a7 as isWidgetKind, a8 as isWidgetVisibleTo, a9 as kpiDelta, aa as labelStride, ab as loadingWidgets, ac as minimizeWidget, ad as moveWidget, ae as moveWidgetBy, af as moveWidgetDown, ag as moveWidgetUp, ah as niceDomain, ai as niceStep, aj as parseLayout, ak as percentChange, al as pruneLayout, am as resolvePayload, an as resolveWidget, ao as resolveWidgets, ap as restoreWidget, aq as serializeLayout, ar as shareOf, as as showWidget, at as sortDefinitions, au as toggleHidden, av as toggleMinimized, aw as visibleWidgets, ax as widgetsFor } from './scale-WlRozDCf.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
@@ -33,25 +33,94 @@ interface LegacyWidgetDefinition {
  */
 declare function fromLegacyDefinition(legacy: LegacyWidgetDefinition): WidgetDefinition | null;
 
+/** The parts of a widget definition that decide its place in a grid. */
+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. */
+declare function fillsHeight(fill: WidgetFill | undefined): boolean;
+/**
+ * Columns a size takes in a grid of `columns` tracks: `large` spans
+ * `largeSpan` (default 2), `full` spans every column, anything else one.
+ */
+declare function baseColumnSpan(size: WidgetSize | undefined, columns: number, largeSpan?: number): number;
+/**
+ * Places `items` in a grid of `columns` tracks the way a sparse grid
+ * auto-places them (left to right, wrapping to a new row when an item does
+ * not fit), then gives the columns left over in each row to the items that
+ * `fill` their width, shared evenly (earlier items get the remainder).
+ *
+ * Returns the column span for each width-filling item, keyed by `key`. Items
+ * 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>;
 /**
- * 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.
+ * Like `fillColumnSpans` for a 12-column grid: each item starts at its
+ * `width` (see `itemWidth`) and width-fillers share the leftover twelfths.
  */
-interface Ok<T> {
-    readonly ok: true;
-    readonly value: T;
+declare function fillWidthSpans(items: readonly GridItem[]): Map<string, number>;
+
+/**
+ * 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 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
@@ -90,4 +159,4 @@ declare function validateWidgetData(value: unknown, options?: ValidateWidgetData
  */
 declare function validateWidgetDefinition(value: unknown): Result<WidgetDefinition>;
 
-export { type Err, type LegacyWidgetDefinition, MAX_REPORTED_PROBLEMS, type Ok, type Result, type ValidateWidgetDataOptions, WidgetDefinition, WidgetKind, WidgetPayload, describeUnknownError, err, 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 };