@richardmcquiston01/dashboard-widgets-toolkit 0.1.0 → 0.2.0

package/dist/react.d.cts

@@ -1,5 +1,5 @@
 import { ReactNode } from 'react';
-import { D as DashboardWidget, W as WidgetSize, G as GraphWidgetData, N as NiceDomain, L as Locale, a as DashboardLayout, A as AlertListWidgetData, B as BarListWidgetData, b as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, c as TextWidgetData, d as WidgetData } from './scale-WlRozDCf.cjs';
+import { D as DashboardWidget, W as WidgetSize, a as WidgetFill, G as GraphWidgetData, N as NiceDomain, L as Locale, b as DashboardLayout, A as AlertListWidgetData, B as BarListWidgetData, c as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, d as TextWidgetData, e as WidgetData } from './scale-Bhjc5Eqt.cjs';
 
 interface WidgetCardProps {
     readonly title: string;
@@ -17,6 +17,13 @@ interface WidgetCardProps {
     readonly onRetry?: () => void;
     readonly footer?: ReactNode;
     readonly size?: WidgetSize;
+    /** Fill free space in the grid row (height, width or both). */
+    readonly fill?: WidgetFill;
+    /**
+     * Explicit grid column span, set by `Dashboard` and `WidgetGrid` to give a
+     * width-filling card the columns left over in its row.
+     */
+    readonly columnSpan?: number;
     /** 2 to 6; default 2. */
     readonly headingLevel?: 2 | 3 | 4 | 5 | 6;
     readonly className?: string;
@@ -26,11 +33,13 @@ interface WidgetCardProps {
  * The frame every widget sits in: title, optional description and actions,
  * a minimise toggle, and loading, empty and error states.
  */
-declare function WidgetCard({ title, description, actions, minimized, onToggleMinimized, status, emptyText, error, onRetry, footer, size, headingLevel, className, children, }: WidgetCardProps): ReactNode;
+declare function WidgetCard({ title, description, actions, minimized, onToggleMinimized, status, emptyText, error, onRetry, footer, size, fill, columnSpan, headingLevel, className, children, }: WidgetCardProps): ReactNode;
 /** The title to show: alert lists add their total, e.g. "Low stock (3)". */
 declare function widgetTitle(widget: DashboardWidget): string;
 interface ResolvedWidgetCardProps {
     readonly widget: DashboardWidget;
+    /** See `WidgetCardProps.columnSpan`. */
+    readonly columnSpan?: number;
     readonly actions?: ReactNode;
     readonly minimized?: boolean;
     readonly onToggleMinimized?: () => void;

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import { ReactNode } from 'react';
-import { D as DashboardWidget, W as WidgetSize, G as GraphWidgetData, N as NiceDomain, L as Locale, a as DashboardLayout, A as AlertListWidgetData, B as BarListWidgetData, b as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, c as TextWidgetData, d as WidgetData } from './scale-WlRozDCf.js';
+import { D as DashboardWidget, W as WidgetSize, a as WidgetFill, G as GraphWidgetData, N as NiceDomain, L as Locale, b as DashboardLayout, A as AlertListWidgetData, B as BarListWidgetData, c as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, d as TextWidgetData, e as WidgetData } from './scale-Bhjc5Eqt.js';
 
 interface WidgetCardProps {
     readonly title: string;
@@ -17,6 +17,13 @@ interface WidgetCardProps {
     readonly onRetry?: () => void;
     readonly footer?: ReactNode;
     readonly size?: WidgetSize;
+    /** Fill free space in the grid row (height, width or both). */
+    readonly fill?: WidgetFill;
+    /**
+     * Explicit grid column span, set by `Dashboard` and `WidgetGrid` to give a
+     * width-filling card the columns left over in its row.
+     */
+    readonly columnSpan?: number;
     /** 2 to 6; default 2. */
     readonly headingLevel?: 2 | 3 | 4 | 5 | 6;
     readonly className?: string;
@@ -26,11 +33,13 @@ interface WidgetCardProps {
  * The frame every widget sits in: title, optional description and actions,
  * a minimise toggle, and loading, empty and error states.
  */
-declare function WidgetCard({ title, description, actions, minimized, onToggleMinimized, status, emptyText, error, onRetry, footer, size, headingLevel, className, children, }: WidgetCardProps): ReactNode;
+declare function WidgetCard({ title, description, actions, minimized, onToggleMinimized, status, emptyText, error, onRetry, footer, size, fill, columnSpan, headingLevel, className, children, }: WidgetCardProps): ReactNode;
 /** The title to show: alert lists add their total, e.g. "Low stock (3)". */
 declare function widgetTitle(widget: DashboardWidget): string;
 interface ResolvedWidgetCardProps {
     readonly widget: DashboardWidget;
+    /** See `WidgetCardProps.columnSpan`. */
+    readonly columnSpan?: number;
     readonly actions?: ReactNode;
     readonly minimized?: boolean;
     readonly onToggleMinimized?: () => void;

package/dist/react.js

@@ -1,8 +1,52 @@
-import { createContext, useContext, useId, useState } from 'react';
+import { createContext, useContext, useId, useState, useRef, useEffect, useMemo } from 'react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 
 // src/react/card.tsx
 
+// src/core/grid.ts
+function fillsWidth(fill) {
+  return fill === "width" || fill === "both";
+}
+function fillsHeight(fill) {
+  return fill === "height" || fill === "both";
+}
+function baseColumnSpan(size, columns, largeSpan = 2) {
+  if (size === "full") return columns;
+  if (size === "large") return Math.min(largeSpan, columns);
+  return 1;
+}
+function fillColumnSpans(items, columns, largeSpan = 2) {
+  const trackCount = Math.max(1, Math.floor(columns));
+  const spans = /* @__PURE__ */ new Map();
+  let row = [];
+  let used = 0;
+  function closeRow() {
+    const fillers = row.filter(({ item }) => fillsWidth(item.fill));
+    const leftover = trackCount - used;
+    if (fillers.length > 0) {
+      const share = Math.floor(leftover / fillers.length);
+      const remainder = leftover % fillers.length;
+      fillers.forEach(({ item, span }, index) => {
+        spans.set(item.key, span + share + (index < remainder ? 1 : 0));
+      });
+    }
+    row = [];
+    used = 0;
+  }
+  for (const item of items) {
+    const span = baseColumnSpan(
+      item.defaultSize,
+      trackCount,
+      largeSpan
+    );
+    if (used + span > trackCount && row.length > 0) closeRow();
+    row.push({ item, span });
+    used += span;
+  }
+  closeRow();
+  return spans;
+}
+
 // src/core/format.ts
 var DEFAULT_CURRENCY = "USD";
 function localeArgument(locale) {
@@ -902,6 +946,8 @@ function WidgetCard({
   onRetry,
   footer,
   size,
+  fill,
+  columnSpan,
   headingLevel = 2,
   className,
   children
@@ -947,8 +993,11 @@ function WidgetCard({
         `dwt-card--${status}`,
         minimized && "dwt-card--minimized",
         size !== void 0 && `dwt-card--size-${size}`,
+        fillsHeight(fill) && "dwt-card--fill-height",
+        fillsWidth(fill) && "dwt-card--fill-width",
         className
       ),
+      ...columnSpan === void 0 ? {} : { style: { gridColumn: `span ${columnSpan}` } },
       children: [
         /* @__PURE__ */ jsxs("header", { className: slot("cardHeader", "dwt-card-header"), children: [
           /* @__PURE__ */ jsxs("div", { className: "dwt-card-heading", children: [
@@ -1012,6 +1061,7 @@ function ResolvedWidgetCard({
       status: widget.status,
       ...definition.description === void 0 ? {} : { description: definition.description },
       ...definition.defaultSize === void 0 ? {} : { size: definition.defaultSize },
+      ...definition.fill === void 0 ? {} : { fill: definition.fill },
       ...widget.status === "empty" ? { emptyText: widget.emptyText } : {},
       ...widget.status === "error" ? { error: widget.error } : {},
       children: widget.status === "ok" ? /* @__PURE__ */ jsx(WidgetContent, { data: widget.data }) : null
@@ -1105,6 +1155,41 @@ function restoreWidget(layout, key) {
 function toggleMinimized(layout, key) {
   return isMinimized(layout, key) ? restoreWidget(layout, key) : minimizeWidget(layout, key);
 }
+var NARROW_VIEWPORT_QUERY = "(max-width: 640px)";
+function useFillSpans(definitions, gridRef) {
+  const [metrics, setMetrics] = useState(void 0);
+  const needsSpans = definitions.some(
+    (definition) => fillsWidth(definition.fill)
+  );
+  useEffect(() => {
+    const grid = gridRef.current;
+    if (!needsSpans || grid === null || typeof ResizeObserver === "undefined") {
+      setMetrics(void 0);
+      return void 0;
+    }
+    function measure() {
+      if (grid === null) return;
+      const tracks = getComputedStyle(grid).gridTemplateColumns;
+      const columns = tracks === "" || tracks === "none" ? 0 : tracks.trim().split(/\s+/).length;
+      const largeSpan = window.matchMedia(NARROW_VIEWPORT_QUERY).matches ? 1 : 2;
+      setMetrics(
+        (previous) => columns === 0 ? void 0 : previous?.columns === columns && previous.largeSpan === largeSpan ? previous : { columns, largeSpan }
+      );
+    }
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(grid);
+    return () => observer.disconnect();
+  }, [needsSpans, gridRef]);
+  return useMemo(
+    () => metrics === void 0 ? /* @__PURE__ */ new Map() : fillColumnSpans(definitions, metrics.columns, metrics.largeSpan),
+    [definitions, metrics]
+  );
+}
+function spanProps(spans, key) {
+  const columnSpan = spans.get(key);
+  return columnSpan === void 0 ? {} : { columnSpan };
+}
 function WidgetGrid({
   widgets,
   onRetry,
@@ -1112,10 +1197,14 @@ function WidgetGrid({
   className
 }) {
   const slot = useSlotClassName();
-  return /* @__PURE__ */ jsx("div", { className: slot("grid", "dwt-grid", className), children: widgets.map((widget) => /* @__PURE__ */ jsx(
+  const gridRef = useRef(null);
+  const definitions = widgets.map((w) => w.definition);
+  const spans = useFillSpans(definitions, gridRef);
+  return /* @__PURE__ */ jsx("div", { ref: gridRef, className: slot("grid", "dwt-grid", className), children: widgets.map((widget) => /* @__PURE__ */ jsx(
     ResolvedWidgetCard,
     {
       widget,
+      ...spanProps(spans, widget.definition.key),
       ...headingLevel === void 0 ? {} : { headingLevel },
       ...onRetry === void 0 || widget.status !== "error" ? {} : { onRetry: () => onRetry(widget.definition.key) }
     },
@@ -1139,6 +1228,8 @@ function DashboardInner({
   const visible = visibleWidgets(definitions, layout);
   const hidden = hiddenWidgets(definitions, layout);
   const editable = onLayoutChange !== void 0;
+  const gridRef = useRef(null);
+  const spans = useFillSpans(visible, gridRef);
   function change(next) {
     if (next !== layout) onLayoutChange?.(next);
   }
@@ -1160,7 +1251,7 @@ function DashboardInner({
         definition.key
       ))
     ] }),
-    visible.length === 0 ? /* @__PURE__ */ jsx("p", { className: slot("empty", "dwt-empty", "dwt-dashboard-empty"), children: definitions.length === 0 ? labels.noWidgets : labels.allHidden }) : /* @__PURE__ */ jsx("div", { className: slot("grid", "dwt-grid"), children: visible.map((definition, index) => {
+    visible.length === 0 ? /* @__PURE__ */ jsx("p", { className: slot("empty", "dwt-empty", "dwt-dashboard-empty"), children: definitions.length === 0 ? labels.noWidgets : labels.allHidden }) : /* @__PURE__ */ jsx("div", { ref: gridRef, className: slot("grid", "dwt-grid"), children: visible.map((definition, index) => {
       const widget = byKey.get(
         definition.key
       );
@@ -1208,6 +1299,7 @@ function DashboardInner({
         ResolvedWidgetCard,
         {
           widget,
+          ...spanProps(spans, key),
           minimized: isMinimized(layout, key),
           ...actions === void 0 ? {} : { actions },
           ...editable ? {