@richardmcquiston01/dashboard-widgets-toolkit 0.4.1 → 0.6.0

package/dist/react.d.cts

@@ -1,5 +1,5 @@
 import { ReactNode, RefObject } from 'react';
-import { D as DashboardWidget, W as WidgetSize, a as WidgetFill, G as GraphWidgetData, N as NiceDomain, b as WidgetDefinition, c as DetailProviderOptions, d as DetailData, e as DetailQuery, L as Locale, f as DashboardLayout, A as AlertListWidgetData, B as BarListWidgetData, g as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, h as TextWidgetData, i as WidgetData, R as ResolveOptions, j as WidgetContext, k as WidgetProviders } from './scale-dWDGE1zW.cjs';
+import { D as DashboardWidget, W as WidgetSize, a as WidgetFill, G as GraphWidgetData, N as NiceDomain, b as WidgetDefinition, c as DetailProviderOptions, d as DetailData, e as DetailQuery, L as Locale, f as DashboardLayout, A as AlertListWidgetData, B as BarListWidgetData, g as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, R as ResolvedTableControls, h as TextWidgetData, i as WidgetData, j as ResolveOptions, k as WidgetContext, l as WidgetProviders } from './scale-D51ZGIF4.cjs';
 
 interface WidgetCardProps {
     readonly title: string;
@@ -88,8 +88,10 @@ declare function GraphWidget({ data, title, }: {
 /**
  * Loads a widget's full detail data. Close over your own context (a Prisma
  * client, a fetch) here; the package never fetches. See `DetailProvider`.
+ * Return `undefined` for a widget you have no extra data for: the card's own
+ * data is used when it is complete (see `deriveDetailData`).
  */
-type DetailLoader = (definition: WidgetDefinition, options: DetailProviderOptions) => DetailData | Promise<DetailData>;
+type DetailLoader = (definition: WidgetDefinition, options: DetailProviderOptions) => DetailData | undefined | Promise<DetailData | undefined>;
 interface WidgetDetailProps {
     /** Table caption: the widget's title. */
     readonly title: string;
@@ -135,9 +137,12 @@ interface DetailLoadState {
 /**
  * Loads a widget's detail data while `enabled`: calls `load` with an abort
  * signal (aborted on close, retry or unmount), validates the result and
- * reports loading, ok or error. `reload` runs it again.
+ * reports loading, ok or error. When `load` is missing or returns
+ * `undefined`, `fallback` (for example the card's own complete data) is used
+ * instead. `reload` runs it again. Keep `load` and `fallback` referentially
+ * stable (`useCallback` / `useMemo`): a new value restarts the load.
  */
-declare function useDetailData(definition: WidgetDefinition, load: DetailLoader | undefined, enabled: boolean): {
+declare function useDetailData(definition: WidgetDefinition, load: DetailLoader | undefined, enabled: boolean, fallback?: DetailData): {
     readonly state: DetailLoadState;
     readonly reload: () => void;
 };
@@ -228,9 +233,10 @@ interface DashboardProps extends WidgetSettings {
     readonly onRetry?: (key: string) => void;
     /**
      * Loads the full data for a widget's detail view (widgets whose definition
-     * sets `detail`). Close over your own context. Without it, TABLE widgets
-     * with no footer and BAR_LIST widgets show their card data; other widgets
-     * get no View button.
+     * sets `detail`). Close over your own context. Return `undefined` for a
+     * widget you have no extra data for: a TABLE with no footer or a BAR_LIST
+     * then shows its card data. Without `loadDetail`, those two still work and
+     * other widgets get no View button.
      */
     readonly loadDetail?: DetailLoader;
     /**
@@ -292,8 +298,10 @@ declare function GaugeWidget({ data, }: {
     readonly data: GaugeWidgetData;
 }): ReactNode;
 /** TABLE: a data table; cells with a safe `href` become links. */
-declare function TableWidget({ data, }: {
+declare function TableWidget({ data, controls, }: {
     readonly data: TableWidgetData;
+    /** Search box and sortable headers; see `WidgetDefinition.tableControls`. */
+    readonly controls?: ResolvedTableControls | undefined;
 }): ReactNode;
 /**
  * BAR_LIST: labelled horizontal bars. One series, so one color (slot 1)
@@ -307,8 +315,10 @@ declare function AlertListWidget({ data, }: {
     readonly data: AlertListWidgetData;
 }): ReactNode;
 /** Renders any payload with the renderer for its kind. */
-declare function WidgetContent({ data, }: {
+declare function WidgetContent({ data, tableControls, }: {
     readonly data: WidgetData;
+    /** Search and sort for TABLE data; see `resolveTableControls`. */
+    readonly tableControls?: ResolvedTableControls | undefined;
 }): ReactNode;
 
 interface UseWidgetsOptions extends ResolveOptions {

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import { ReactNode, RefObject } from 'react';
-import { D as DashboardWidget, W as WidgetSize, a as WidgetFill, G as GraphWidgetData, N as NiceDomain, b as WidgetDefinition, c as DetailProviderOptions, d as DetailData, e as DetailQuery, L as Locale, f as DashboardLayout, A as AlertListWidgetData, B as BarListWidgetData, g as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, h as TextWidgetData, i as WidgetData, R as ResolveOptions, j as WidgetContext, k as WidgetProviders } from './scale-dWDGE1zW.js';
+import { D as DashboardWidget, W as WidgetSize, a as WidgetFill, G as GraphWidgetData, N as NiceDomain, b as WidgetDefinition, c as DetailProviderOptions, d as DetailData, e as DetailQuery, L as Locale, f as DashboardLayout, A as AlertListWidgetData, B as BarListWidgetData, g as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, R as ResolvedTableControls, h as TextWidgetData, i as WidgetData, j as ResolveOptions, k as WidgetContext, l as WidgetProviders } from './scale-D51ZGIF4.js';
 
 interface WidgetCardProps {
     readonly title: string;
@@ -88,8 +88,10 @@ declare function GraphWidget({ data, title, }: {
 /**
  * Loads a widget's full detail data. Close over your own context (a Prisma
  * client, a fetch) here; the package never fetches. See `DetailProvider`.
+ * Return `undefined` for a widget you have no extra data for: the card's own
+ * data is used when it is complete (see `deriveDetailData`).
  */
-type DetailLoader = (definition: WidgetDefinition, options: DetailProviderOptions) => DetailData | Promise<DetailData>;
+type DetailLoader = (definition: WidgetDefinition, options: DetailProviderOptions) => DetailData | undefined | Promise<DetailData | undefined>;
 interface WidgetDetailProps {
     /** Table caption: the widget's title. */
     readonly title: string;
@@ -135,9 +137,12 @@ interface DetailLoadState {
 /**
  * Loads a widget's detail data while `enabled`: calls `load` with an abort
  * signal (aborted on close, retry or unmount), validates the result and
- * reports loading, ok or error. `reload` runs it again.
+ * reports loading, ok or error. When `load` is missing or returns
+ * `undefined`, `fallback` (for example the card's own complete data) is used
+ * instead. `reload` runs it again. Keep `load` and `fallback` referentially
+ * stable (`useCallback` / `useMemo`): a new value restarts the load.
  */
-declare function useDetailData(definition: WidgetDefinition, load: DetailLoader | undefined, enabled: boolean): {
+declare function useDetailData(definition: WidgetDefinition, load: DetailLoader | undefined, enabled: boolean, fallback?: DetailData): {
     readonly state: DetailLoadState;
     readonly reload: () => void;
 };
@@ -228,9 +233,10 @@ interface DashboardProps extends WidgetSettings {
     readonly onRetry?: (key: string) => void;
     /**
      * Loads the full data for a widget's detail view (widgets whose definition
-     * sets `detail`). Close over your own context. Without it, TABLE widgets
-     * with no footer and BAR_LIST widgets show their card data; other widgets
-     * get no View button.
+     * sets `detail`). Close over your own context. Return `undefined` for a
+     * widget you have no extra data for: a TABLE with no footer or a BAR_LIST
+     * then shows its card data. Without `loadDetail`, those two still work and
+     * other widgets get no View button.
      */
     readonly loadDetail?: DetailLoader;
     /**
@@ -292,8 +298,10 @@ declare function GaugeWidget({ data, }: {
     readonly data: GaugeWidgetData;
 }): ReactNode;
 /** TABLE: a data table; cells with a safe `href` become links. */
-declare function TableWidget({ data, }: {
+declare function TableWidget({ data, controls, }: {
     readonly data: TableWidgetData;
+    /** Search box and sortable headers; see `WidgetDefinition.tableControls`. */
+    readonly controls?: ResolvedTableControls | undefined;
 }): ReactNode;
 /**
  * BAR_LIST: labelled horizontal bars. One series, so one color (slot 1)
@@ -307,8 +315,10 @@ declare function AlertListWidget({ data, }: {
     readonly data: AlertListWidgetData;
 }): ReactNode;
 /** Renders any payload with the renderer for its kind. */
-declare function WidgetContent({ data, }: {
+declare function WidgetContent({ data, tableControls, }: {
     readonly data: WidgetData;
+    /** Search and sort for TABLE data; see `resolveTableControls`. */
+    readonly tableControls?: ResolvedTableControls | undefined;
 }): ReactNode;
 
 interface UseWidgetsOptions extends ResolveOptions {