@richardmcquiston01/dashboard-widgets-toolkit 0.8.0 → 0.9.0

package/dist/react.d.cts

@@ -37,6 +37,8 @@ interface WidgetCardProps {
      * which card scrolled into view. `ResolvedWidgetCard` sets it for you.
      */
     readonly widgetKey?: string;
+    /** Marks the card as being edited (dashed outline); set by `Dashboard`. */
+    readonly editing?: boolean;
     /** 2 to 6; default 2. */
     readonly headingLevel?: 2 | 3 | 4 | 5 | 6;
     readonly className?: string;
@@ -46,7 +48,7 @@ interface WidgetCardProps {
  * The frame every widget sits in: title, optional description and actions,
  * a minimize toggle, and loading, empty and error states.
  */
-declare function WidgetCard({ title, description, actions, minimized, onToggleMinimized, onView, status, emptyText, error, onRetry, footer, size, fill, columnSpan, width, widgetKey, headingLevel, className, children, }: WidgetCardProps): ReactNode;
+declare function WidgetCard({ title, description, actions, minimized, onToggleMinimized, onView, status, emptyText, error, onRetry, footer, size, fill, columnSpan, width, widgetKey, editing, 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 {
@@ -61,6 +63,8 @@ interface ResolvedWidgetCardProps {
     /** See `WidgetCardProps.onView`. */
     readonly onView?: () => void;
     readonly onRetry?: () => void;
+    /** See `WidgetCardProps.editing`. */
+    readonly editing?: boolean;
     readonly headingLevel?: 2 | 3 | 4 | 5 | 6;
     readonly className?: string;
 }
@@ -148,7 +152,7 @@ declare function useDetailData(definition: WidgetDefinition, load: DetailLoader
 };
 
 /** Every element that carries a stable `dwt-*` class, for `classNames`. */
-type DashboardClassSlot = 'dashboard' | 'hiddenBar' | 'grid' | 'card' | 'cardHeader' | 'cardTitle' | 'cardDescription' | 'cardActions' | 'cardBody' | 'cardFooter' | 'button' | 'status' | 'empty' | 'error' | 'text' | 'kpi' | 'gauge' | 'table' | 'barList' | 'alertList' | 'chart' | 'legend' | 'tooltip' | 'tableTwin' | 'detail';
+type DashboardClassSlot = 'dashboard' | 'hiddenBar' | 'toolbar' | 'grid' | 'card' | 'cardHeader' | 'cardTitle' | 'cardDescription' | 'cardActions' | 'cardBody' | 'cardFooter' | 'button' | 'status' | 'empty' | 'error' | 'text' | 'kpi' | 'gauge' | 'table' | 'barList' | 'alertList' | 'chart' | 'legend' | 'tooltip' | 'tableTwin' | 'detail';
 /**
  * Extra classes per slot, appended to the `dwt-*` class (never replacing
  * it), e.g. `{ card: 'rounded-lg shadow-sm' }` for Tailwind.
@@ -167,6 +171,25 @@ interface DashboardLabels {
     readonly moveLater: (title: string) => string;
     readonly hiddenWidgets: string;
     readonly minimizedWidgets: string;
+    /** Edit mode toolbar (`editMode="toggle"`). */
+    readonly customize: string;
+    readonly done: string;
+    readonly reset: string;
+    readonly revertChanges: string;
+    readonly confirmReset: string;
+    readonly confirmRevert: string;
+    /** Accessible names of the inline "✓" and "X" confirmation buttons. */
+    readonly confirmYes: string;
+    readonly confirmNo: string;
+    /** Announced when edit mode starts and ends. */
+    readonly editingOn: string;
+    readonly editingOff: string;
+    /** Names the toolbar group for assistive technology. */
+    readonly dashboardControls: string;
+    /** The lock icon on a locked card, e.g. "Revenue is locked". */
+    readonly locked: (title: string) => string;
+    /** The lock icon on a card shown to an administrator (`overrideLocks`). */
+    readonly lockedForViewers: (title: string) => string;
     /** Added to the accessible name of links that open in a new tab. */
     readonly opensInNewTab: string;
     /** The card's View button, opening the detail view. */
@@ -237,6 +260,23 @@ interface DashboardProps extends WidgetSettings {
      * everyone else (`enforceLocks`). It never changes the locks themselves.
      */
     readonly overrideLocks?: boolean;
+    /**
+     * `always` (default): move and hide controls show whenever `onLayoutChange`
+     * is set. `toggle`: they show only while editing, behind a Customize
+     * button, so a stray click can't rearrange the page. Minimize and its bar
+     * work in both modes.
+     */
+    readonly editMode?: 'always' | 'toggle';
+    /** Controlled editing state (`editMode="toggle"`). */
+    readonly editing?: boolean;
+    /** Initial editing state when uncontrolled. Default false. */
+    readonly defaultEditing?: boolean;
+    /** Called when the viewer starts or finishes editing. */
+    readonly onEditingChange?: (editing: boolean) => void;
+    /** What Reset layout restores. Default: the empty layout (sortOrder order). */
+    readonly defaultLayout?: DashboardLayout;
+    /** Show the built-in Customize/Done/Reset toolbar (toggle mode). Default true. */
+    readonly toolbar?: boolean;
     readonly onRetry?: (key: string) => void;
     /**
      * Loads the full data for a widget's detail view (widgets whose definition

package/dist/react.d.ts

@@ -37,6 +37,8 @@ interface WidgetCardProps {
      * which card scrolled into view. `ResolvedWidgetCard` sets it for you.
      */
     readonly widgetKey?: string;
+    /** Marks the card as being edited (dashed outline); set by `Dashboard`. */
+    readonly editing?: boolean;
     /** 2 to 6; default 2. */
     readonly headingLevel?: 2 | 3 | 4 | 5 | 6;
     readonly className?: string;
@@ -46,7 +48,7 @@ interface WidgetCardProps {
  * The frame every widget sits in: title, optional description and actions,
  * a minimize toggle, and loading, empty and error states.
  */
-declare function WidgetCard({ title, description, actions, minimized, onToggleMinimized, onView, status, emptyText, error, onRetry, footer, size, fill, columnSpan, width, widgetKey, headingLevel, className, children, }: WidgetCardProps): ReactNode;
+declare function WidgetCard({ title, description, actions, minimized, onToggleMinimized, onView, status, emptyText, error, onRetry, footer, size, fill, columnSpan, width, widgetKey, editing, 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 {
@@ -61,6 +63,8 @@ interface ResolvedWidgetCardProps {
     /** See `WidgetCardProps.onView`. */
     readonly onView?: () => void;
     readonly onRetry?: () => void;
+    /** See `WidgetCardProps.editing`. */
+    readonly editing?: boolean;
     readonly headingLevel?: 2 | 3 | 4 | 5 | 6;
     readonly className?: string;
 }
@@ -148,7 +152,7 @@ declare function useDetailData(definition: WidgetDefinition, load: DetailLoader
 };
 
 /** Every element that carries a stable `dwt-*` class, for `classNames`. */
-type DashboardClassSlot = 'dashboard' | 'hiddenBar' | 'grid' | 'card' | 'cardHeader' | 'cardTitle' | 'cardDescription' | 'cardActions' | 'cardBody' | 'cardFooter' | 'button' | 'status' | 'empty' | 'error' | 'text' | 'kpi' | 'gauge' | 'table' | 'barList' | 'alertList' | 'chart' | 'legend' | 'tooltip' | 'tableTwin' | 'detail';
+type DashboardClassSlot = 'dashboard' | 'hiddenBar' | 'toolbar' | 'grid' | 'card' | 'cardHeader' | 'cardTitle' | 'cardDescription' | 'cardActions' | 'cardBody' | 'cardFooter' | 'button' | 'status' | 'empty' | 'error' | 'text' | 'kpi' | 'gauge' | 'table' | 'barList' | 'alertList' | 'chart' | 'legend' | 'tooltip' | 'tableTwin' | 'detail';
 /**
  * Extra classes per slot, appended to the `dwt-*` class (never replacing
  * it), e.g. `{ card: 'rounded-lg shadow-sm' }` for Tailwind.
@@ -167,6 +171,25 @@ interface DashboardLabels {
     readonly moveLater: (title: string) => string;
     readonly hiddenWidgets: string;
     readonly minimizedWidgets: string;
+    /** Edit mode toolbar (`editMode="toggle"`). */
+    readonly customize: string;
+    readonly done: string;
+    readonly reset: string;
+    readonly revertChanges: string;
+    readonly confirmReset: string;
+    readonly confirmRevert: string;
+    /** Accessible names of the inline "✓" and "X" confirmation buttons. */
+    readonly confirmYes: string;
+    readonly confirmNo: string;
+    /** Announced when edit mode starts and ends. */
+    readonly editingOn: string;
+    readonly editingOff: string;
+    /** Names the toolbar group for assistive technology. */
+    readonly dashboardControls: string;
+    /** The lock icon on a locked card, e.g. "Revenue is locked". */
+    readonly locked: (title: string) => string;
+    /** The lock icon on a card shown to an administrator (`overrideLocks`). */
+    readonly lockedForViewers: (title: string) => string;
     /** Added to the accessible name of links that open in a new tab. */
     readonly opensInNewTab: string;
     /** The card's View button, opening the detail view. */
@@ -237,6 +260,23 @@ interface DashboardProps extends WidgetSettings {
      * everyone else (`enforceLocks`). It never changes the locks themselves.
      */
     readonly overrideLocks?: boolean;
+    /**
+     * `always` (default): move and hide controls show whenever `onLayoutChange`
+     * is set. `toggle`: they show only while editing, behind a Customize
+     * button, so a stray click can't rearrange the page. Minimize and its bar
+     * work in both modes.
+     */
+    readonly editMode?: 'always' | 'toggle';
+    /** Controlled editing state (`editMode="toggle"`). */
+    readonly editing?: boolean;
+    /** Initial editing state when uncontrolled. Default false. */
+    readonly defaultEditing?: boolean;
+    /** Called when the viewer starts or finishes editing. */
+    readonly onEditingChange?: (editing: boolean) => void;
+    /** What Reset layout restores. Default: the empty layout (sortOrder order). */
+    readonly defaultLayout?: DashboardLayout;
+    /** Show the built-in Customize/Done/Reset toolbar (toggle mode). Default true. */
+    readonly toolbar?: boolean;
     readonly onRetry?: (key: string) => void;
     /**
      * Loads the full data for a widget's detail view (widgets whose definition