@richardmcquiston01/dashboard-widgets-toolkit 0.4.1 → 0.5.0

package/README.md

@@ -1,7 +1,8 @@
 # Dashboard Widgets Toolkit
 
-- Author:  Richard McQuiston
+- Author:   Richard McQuiston
 - Website:  https://richardmcquiston.com/
+- Demo:     https://dashboard-widgets-toolkit-demo.vercel.app/
 
 ## Overview
 
@@ -42,375 +43,7 @@ synced yet.' }`.
 
 ## Getting Started
 
-### Prerequisites
-
-- Node.js 18+ or Bun 1.3+ (or any modern browser bundler).
-- React 18 or later, only if you use `/react`.
-- TypeScript is optional; type declarations are included.
-
-### Installation
-
-```bash
-bun add @richardmcquiston01/dashboard-widgets-toolkit
-# or
-npm install @richardmcquiston01/dashboard-widgets-toolkit
-```
-
-Both `import` and `require` work, for every entry:
-
-```js
-const { resolveWidgets } = require('@richardmcquiston01/dashboard-widgets-toolkit/core');
-```
-
-### Usage
-
-**Core: define widgets, register providers, resolve.** Each provider gets
-your context and returns a payload (or throws). One failing provider never
-breaks the dashboard: it comes back as an `error` widget with the reason.
-
-```ts
-import {
-  defineWidget,
-  emptyWidget,
-  resolveWidgets,
-  type WidgetContext,
-  type WidgetProviders,
-} from '@richardmcquiston01/dashboard-widgets-toolkit';
-
-interface ShopContext extends WidgetContext {
-  shopId: string;
-}
-
-const widgets = [
-  defineWidget({ key: 'revenue', title: 'Revenue', kind: 'KPI', sortOrder: 10 }),
-  defineWidget({ key: 'low-stock', title: 'Low stock', kind: 'ALERT_LIST', sortOrder: 20 }),
-  defineWidget({
-    key: 'monthly',
-    title: 'Revenue by month',
-    kind: 'GRAPH',
-    sortOrder: 30,
-    defaultSize: 'large',
-  }),
-  defineWidget({ key: 'audit', title: 'Audit log', kind: 'TABLE', roles: ['admin'] }),
-];
-
-const providers: WidgetProviders<ShopContext> = {
-  revenue: async ({ shopId }) => {
-    const { current, previous } = await loadRevenue(shopId); // your code
-    return { kind: 'KPI', value: current, previous, format: 'currency', label: 'Revenue' };
-  },
-  'low-stock': async ({ shopId }) => {
-    const rows = await loadLowStock(shopId);
-    return {
-      kind: 'ALERT_LIST',
-      items: rows.slice(0, 5).map((row) => ({
-        title: row.title,
-        href: row.url,
-        thumbnailUrl: row.thumbnailUrl,
-        valueLabel: `${row.quantity} left`,
-      })),
-      total: rows.length,
-      emptyText: 'Nothing low on stock.',
-    };
-  },
-  monthly: async ({ shopId }) => {
-    const months = await loadMonthly(shopId);
-    if (months.length === 0) return emptyWidget('No orders synced yet.');
-    return {
-      kind: 'GRAPH',
-      chartType: 'bar',
-      valueFormat: 'currency',
-      xLabel: 'Month',
-      series: [{ name: 'Revenue', points: months.map((m) => ({ label: m.label, value: m.revenue })) }],
-    };
-  },
-};
-
-const resolved = await resolveWidgets(widgets, providers, {
-  shopId: 'shop-1',
-  roles: ['owner'], // "audit" is skipped: it needs "admin"
-});
-// [{ definition, status: 'ok', data }, { definition, status: 'empty', emptyText }, ...]
-```
-
-Payloads are validated by default (turn it off with `{ validate: false }`
-for trusted, typed providers). In a client, check JSON from your API the same
-way:
-
-```ts
-import { resolvePayload, validateWidgetData } from '@richardmcquiston01/dashboard-widgets-toolkit';
-
-const result = validateWidgetData(json, { widgetKey: 'revenue', expectedKind: 'KPI' });
-if (!result.ok) console.warn(result.error);
-// 'Widget "revenue" (KPI): previous must be a finite number, got string.'
-
-const widget = resolvePayload(definition, json); // ok, empty, or error with that message
-```
-
-**React: render a dashboard with the viewer's layout.**
-
-```tsx
-import { useState } from 'react';
-import {
-  parseLayout,
-  serializeLayout,
-  type ResolvedWidget,
-} from '@richardmcquiston01/dashboard-widgets-toolkit';
-import { Dashboard } from '@richardmcquiston01/dashboard-widgets-toolkit/react';
-import '@richardmcquiston01/dashboard-widgets-toolkit/styles.css'; // optional
-
-export function ShopDashboard({ widgets }: { widgets: ResolvedWidget[] }) {
-  const [layout, setLayout] = useState(() => parseLayout(localStorage.getItem('layout')));
-  return (
-    <Dashboard
-      widgets={widgets}
-      layout={layout}
-      onLayoutChange={(next) => {
-        setLayout(next);
-        localStorage.setItem('layout', serializeLayout(next));
-      }}
-      locale="en-US"
-      linkTarget="_blank"
-      onRetry={(key) => refetch(key)}
-    />
-  );
-}
-```
-
-`Dashboard` orders widgets by the saved layout (saved order first, new widgets
-appended by `sortOrder`, hidden ones removed), and gives each card move
-earlier/later, hide and minimize buttons, plus a "Hidden:" bar to bring
-widgets back. A minimized widget leaves the grid (so it stops taking space)
-and waits in a "Minimized:" bar until the viewer expands it. Without `onLayoutChange` it is read-only. Use `loadingWidgets`
-for placeholders while data loads, and `WidgetGrid` for a plain grid with no
-layout controls.
-
-Links open in the same tab unless you set `linkTarget` (for example
-`"_blank"`); links that open a new tab get a small external-link icon and
-"(opens in a new tab)" for screen readers (label `opensInNewTab`).
-
-### Examples
-
-**Layout functions on their own** (pure; the input is never mutated):
-
-```ts
-import {
-  EMPTY_LAYOUT,
-  hideWidget,
-  moveWidgetUp,
-  toggleMinimized,
-  visibleWidgets,
-} from '@richardmcquiston01/dashboard-widgets-toolkit';
-
-const definitions = [
-  { key: 'revenue', sortOrder: 10 },
-  { key: 'low-stock', sortOrder: 20 },
-  { key: 'monthly', sortOrder: 30 },
-];
-let layout = moveWidgetUp(definitions, EMPTY_LAYOUT, 'monthly');
-layout = hideWidget(layout, 'low-stock');
-layout = toggleMinimized(layout, 'revenue');
-visibleWidgets(definitions, layout).map((d) => d.key); // ['revenue', 'monthly']
-```
-
-**KPI deltas and formatting** with an explicit locale:
-
-```ts
-import { formatValue, kpiDelta } from '@richardmcquiston01/dashboard-widgets-toolkit';
-
-formatValue(1234.5, 'currency', { locale: 'en-GB', currency: 'GBP' }); // "£1,234.50"
-kpiDelta(120, 100, { locale: 'en-US' });
-// { percent: 20, direction: 'up', sentiment: 'good', text: '+20%', description: '+20% vs previous period' }
-kpiDelta(120, 100, { higherIsBetter: false })?.sentiment; // 'bad' (e.g. refunds)
-```
-
-**Styling with Tailwind (or any classes).** Components keep their `dwt-*`
-classes and append yours per slot. Skip `styles.css` entirely, or keep it and
-override its custom properties:
-
-```tsx
-<Dashboard
-  widgets={widgets}
-  classNames={{ card: 'rounded-lg shadow-sm', cardTitle: 'text-sm font-semibold' }}
-/>
-```
-
-```css
-.dwt-dashboard {
-  --dwt-series-1: #567d62; /* your brand color for single-series charts */
-  --dwt-radius: 4px;
-}
-```
-
-Dark mode follows the OS setting unless the page sets `data-theme="light"`;
-`data-theme="dark"` or a `dark` class on `<html>` forces it.
-
-**Widget width.** Give a widget a `width` to say how much of the row it
-takes, in twelfths (like a 12-column grid): an integer from 2 to 12. A table
-with many columns might want half the row:
-
-```ts
-defineWidget({ key: 'top-products', title: 'Most popular products', kind: 'TABLE', width: 8 });
-defineWidget({ key: 'ratings', title: 'Rating breakdown', kind: 'BAR_LIST', width: 4 });
-```
-
-When any widget in a grid sets `width`, the grid becomes 12 columns
-(`dwt-grid--twelve`) and each card spans `--dwt-width` columns. Widgets
-without a `width` use one from their `defaultSize` (small 3, medium 4, large
-6, full 12). Narrow grids give widgets more room: under 900px a widget gets
-twice its width, under 560px it takes the whole row. `fill: 'width'` still
-works, sharing the twelfths left over in a row. The validator rejects
-anything but an integer from 2 to 12.
-
-**Detail view.** Set `detail: true` (or `{ title, pageSize, mode }`) on a
-definition and `Dashboard` adds a "View" eye button to the card (the title is
-clickable too). It opens a modal dialog with search, per-column filters,
-sortable headers and paging. Where the data comes from:
-
-```tsx
-<Dashboard
-  widgets={widgets}
-  loadDetail={(definition, { signal, query }) => fetchAllRows(definition.key, signal)}
-/>
-```
-
-- `loadDetail` (close over your own context; the package never fetches)
-  returns a `DetailData` table: columns with a `key`, rows of cells with
-  `text` and an optional `value` used for sorting and filtering.
-- Without it, a TABLE with no `footer` and a BAR_LIST show their own card data;
-  other widgets get no View button until you pass `loadDetail`.
-- `onOpenDetail={(key) => navigate(...)}` replaces the built-in dialog so you
-  can open your own page.
-- The pieces are exported for your own layout: `WidgetDetail` (controlled by
-  a `DetailQuery`), `WidgetDetailDialog` and `useDetailData`. In the core,
-  `queryRows` does the filtering, sorting and paging (case- and
-  accent-insensitive, numeric-aware), `serializeDetailQuery` /
-  `parseDetailQuery` keep the query in a URL, and `validateDetailData` checks
-  what your loader returns.
-
-Server-side paging and URL deep links are next; see
-[docs/design/detail-view.md](./docs/design/detail-view.md).
-
-**Filling space.** By default each card is only as big as its content, so a
-short card beside a tall one leaves a gap. Set `fill` on a widget definition
-to have it use the free space in its grid row:
-
-```ts
-defineWidget({ key: 'countries', title: 'Orders by country', kind: 'BAR_LIST', fill: 'height' });
-defineWidget({ key: 'notes', title: 'Notes', kind: 'TEXT', fill: 'width' });
-defineWidget({ key: 'trend', title: 'Trend', kind: 'GRAPH', defaultSize: 'large', fill: 'both' });
-```
-
-| `fill`   | Effect                                                              |
-| -------- | ------------------------------------------------------------------- |
-| `height` | Stretches the card to the height of its row (`dwt-card--fill-height`). |
-| `width`  | Widens the card to take the columns left over in its row (`dwt-card--fill-width`). |
-| `both`   | Both.                                                               |
-
-`Dashboard` and `WidgetGrid` work out the spans from the rendered grid (so it
-follows your CSS and the container width) and set `grid-column: span N` on
-width-filling cards; on the server, and before the first measurement, the
-grid simply lays out normally. The same helper is exported from the core as
-`fillColumnSpans(items, columns)` for custom layouts, and `WidgetCard` takes
-`fill` and `columnSpan` props.
-
-**Loading data after the page renders.** Render the dashboard first and let
-each widget's data arrive on its own. `useWidgets` returns placeholders
-immediately (so first paint and server rendering never wait), starts every
-provider after mount, and replaces each card as its own data arrives:
-
-```tsx
-import { Dashboard, useWidgets } from '@richardmcquiston01/dashboard-widgets-toolkit/react';
-
-const { widgets, refresh } = useWidgets(definitions, providers, context, {
-  timeoutMs: 8000, // a provider that takes longer becomes an error card
-  refreshMs: 60_000, // optional polling; skips widgets still loading
-});
-
-return <Dashboard widgets={widgets} onRetry={(key) => refresh(key)} />;
-```
-
-Providers receive an `AbortSignal` as a third argument (`(context, definition,
-{ signal })`); pass it to `fetch` so a timeout, a refresh or leaving the page
-stops the request. Existing two-argument providers keep working.
-
-- `loadWhen: 'visible'` also waits until a card is near the viewport. Attach
-  the returned `gridRef` to an element around the dashboard.
-- `cache` (your own `{ get, set }` storage: memory, `localStorage`, ...) shows
-  the last payload instantly as `stale` while a fresh load runs. Cached
-  payloads are validated again, and a failing cache never fails a widget.
-- Keep `definitions`, `providers`, `context` and `cache` referentially stable
-  (module constants or `useMemo`); a changed value restarts loading.
-- Not using React? `createWidgetLoader` (core) is the same logic with
-  `subscribe`/`getSnapshot`, `load`, `refresh` and `dispose`; `resolveWidget`
-  and `resolveWidgets` accept `timeoutMs`, `signal` and `cache` too.
-
-**Charts.** `GRAPH` widgets render as inline SVG with `role="img"`, a
-`<title>` and a `<desc>` summarizing the series (latest, high and low), a
-legend when there are two or more series, a hover and keyboard (arrow keys)
-tooltip, and a collapsible "View as table" with every value. Colors are CSS
-custom properties (`--dwt-series-1` … `--dwt-series-8`) with built-in
-defaults from a palette checked for color-vision deficiency in light and
-dark modes; a graph may have at most eight series.
-
-## Maker Toolkit compatibility
-
-The kind names are upper case, as in Maker Toolkit's `WidgetViewType`, and
-the definition mirrors its `widget` table:
-
-| Maker Toolkit (`widget` table / API) | This package                   |
-| ------------------------------------ | ------------------------------ |
-| `widget_key` / `widgetKey`           | `key`                          |
-| `title`, `description`               | `title`, `description`         |
-| `view_type` / `viewType`             | `kind`                         |
-| `sort_order` / `sortOrder`           | `sortOrder`                    |
-| `roles` (empty = everyone)           | `roles` (absent/empty = everyone) |
-| `active`                             | `active`                       |
-| providers keyed by `widget_key`      | `WidgetProviders` keyed by `key` |
-
-- `TEXT` and `GAUGE` payloads are unchanged.
-- `TABLE` columns and cells became objects (`{label, numeric?}`,
-  `{text, href?}`), and `GRAPH` became multi-series with a chart type and
-  value format. `upgradeLegacyWidgetData()` converts the older
-  `{columns: string[], rows: string[][]}` and `{points}` shapes, and
-  `fromLegacyDefinition()` maps a served definition.
-- `KPI`, `BAR_LIST` and `ALERT_LIST` are new kinds. Add them to the
-  `WidgetViewType` enum before seeding widgets that use them.
-- The desktop app's `dashboard-layout.ts` (order, hidden, minimized) is
-  `layout.ts` here, with the same JSON shape, so saved layouts carry over.
-  It now appends new widgets by `sortOrder` and tolerates corrupt values per
-  field.
-
-```ts
-import {
-  fromLegacyDefinition,
-  upgradeLegacyWidgetData,
-  validateWidgetData,
-} from '@richardmcquiston01/dashboard-widgets-toolkit';
-
-const result = validateWidgetData(upgradeLegacyWidgetData(apiPayload));
-```
-
-## Development
-
-```bash
-bun install
-bun run typecheck
-bun run lint
-bun run format:check
-bun run test
-bun run build      # dist/: ESM (.js), CommonJS (.cjs), .d.ts/.d.cts, styles.css
-```
-
-Branches: `dev` is the integration branch. Branch features off `dev` and open
-pull requests into `dev`; `dev` is merged to `main` for a release. Add a
-changeset (`bun run changeset`) with each user-facing change.
-
-Releases are published to npm by GitHub Actions when a `vX.Y.Z` tag matching
-`package.json` is pushed to `main`. **The `NPM_TOKEN` repository secret (an
-npm automation token) must be added under Settings → Secrets and variables →
-Actions** before the first release. See [CLAUDE.md](./CLAUDE.md) for the
-full flow.
+See [GETTING_STARTED.md](./GETTING_STARTED.md)
 
 ## Buy Me a Coffee
 

package/dist/react.cjs

@@ -1785,22 +1785,30 @@ function WidgetDetailDialog({
     }
   );
 }
-function useDetailData(definition, load, enabled) {
+function useDetailData(definition, load, enabled, fallback) {
   const [state, setState] = react.useState({ status: "loading" });
   const [attempt, setAttempt] = react.useState(0);
   react.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(
@@ -1814,7 +1822,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)";
@@ -1912,12 +1920,16 @@ function DetailHost({
   const options = resolveDetailOptions(definition);
   const pageSize = options?.pageSize ?? 25;
   const [query, setQuery] = react.useState(defaultDetailQuery(pageSize));
-  const derived = widget.status === "ok" ? deriveDetailData(widget.data, locale) : void 0;
-  const load = react.useMemo(
-    () => loadDetail ?? (derived === void 0 ? void 0 : () => derived),
-    [loadDetail, derived]
+  const derived = react.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__ */ jsxRuntime.jsx(WidgetDetailDialog, { title, open: true, onClose, children: /* @__PURE__ */ jsxRuntime.jsx(
     WidgetDetail,
@@ -1925,10 +1937,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