@richardmcquiston01/dashboard-widgets-toolkit 0.4.0 → 0.5.0

package/dist/react.d.cts

@@ -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;
     /**

package/dist/react.d.ts

@@ -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;
     /**

package/dist/react.js

@@ -1783,22 +1783,30 @@ function WidgetDetailDialog({
     }
   );
 }
-function useDetailData(definition, load, enabled) {
+function useDetailData(definition, load, enabled, fallback) {
   const [state, setState] = useState({ status: "loading" });
   const [attempt, setAttempt] = useState(0);
   useEffect(() => {
-    if (!enabled || load === void 0) return void 0;
+    if (!enabled) return void 0;
     const controller = new AbortController();
     setState({ status: "loading" });
     Promise.resolve().then(
-      () => load(definition, {
+      () => load === void 0 ? void 0 : load(definition, {
         signal: controller.signal,
         query: defaultDetailQuery()
       })
     ).then((raw) => {
       if (controller.signal.aborted) return;
+      const data = raw ?? fallback;
+      if (data === void 0) {
+        setState({
+          status: "error",
+          error: `Widget "${definition.key}" detail: no data. The loader returned nothing for this widget and its card does not hold the full data (use a loader that returns rows, or a TABLE without a footer or a BAR_LIST).`
+        });
+        return;
+      }
       const checked = validateDetailData(
-        raw,
+        data,
         `Widget "${definition.key}" detail`
       );
       setState(
@@ -1812,7 +1820,7 @@ function useDetailData(definition, load, enabled) {
       });
     });
     return () => controller.abort();
-  }, [enabled, load, definition, attempt]);
+  }, [enabled, load, fallback, definition, attempt]);
   return { state, reload: () => setAttempt((count) => count + 1) };
 }
 var NARROW_VIEWPORT_QUERY = "(max-width: 640px)";
@@ -1910,12 +1918,16 @@ function DetailHost({
   const options = resolveDetailOptions(definition);
   const pageSize = options?.pageSize ?? 25;
   const [query, setQuery] = useState(defaultDetailQuery(pageSize));
-  const derived = widget.status === "ok" ? deriveDetailData(widget.data, locale) : void 0;
-  const load = useMemo(
-    () => loadDetail ?? (derived === void 0 ? void 0 : () => derived),
-    [loadDetail, derived]
+  const derived = useMemo(
+    () => widget.status === "ok" ? deriveDetailData(widget.data, locale) : void 0,
+    [widget, locale]
+  );
+  const { state, reload } = useDetailData(
+    definition,
+    loadDetail,
+    true,
+    derived
   );
-  const { state, reload } = useDetailData(definition, load, true);
   const title = options?.title ?? definition.title;
   return /* @__PURE__ */ jsx(WidgetDetailDialog, { title, open: true, onClose, children: /* @__PURE__ */ jsx(
     WidgetDetail,
@@ -1923,10 +1935,7 @@ function DetailHost({
       title,
       query,
       onQueryChange: setQuery,
-      status: load === void 0 ? "error" : state.status,
-      ...load === void 0 ? {
-        error: `Widget "${definition.key}" has no detail data: pass loadDetail, or use a TABLE without a footer or a BAR_LIST.`
-      } : {},
+      status: state.status,
       ...state.data === void 0 ? {} : { data: state.data },
       ...state.error === void 0 ? {} : { error: state.error },
       onRetry: reload