@tenorlab/react-dashboard 1.4.7 → 1.5.2

package/README.md

@@ -37,7 +37,7 @@ Import the base styles in your entry file (e.g., `main.tsx`):
 TypeScript
 
 ```
-import '@tenorlab/react-dashboard/dist/style.css'
+import '@tenorlab/react-dashboard/styles.css'
 ```
 
 ------
@@ -169,18 +169,20 @@ export const getWidgetCatalog = async (user: any | null): Promise<TDashboardWidg
     catalogMapEntries.push(createStaticEntry('WidgetRecentPaymentInfo', WidgetRecentPaymentInfo))
   }
 
+  // add bundled widgets (non-lazy)
   catalogMapEntries.push(...localWidgetDiscovery(
     bundledWidgetsSrcPath,
     bundledWidgetModules,
     allMetaModules,
-    false
+    false, // lazy: false
   ))
 
+  // add async-widgets (lazy)
   catalogMapEntries.push(...localWidgetDiscovery(
     asyncWidgetsSrcPath,
     asyncWidgetModules,
     allMetaModules,
-    true
+    true, // lazy: true
   ))
 
   // Optional: Remote discovery of -pre-built widgets hosted on a CDN

package/dist/core.d.ts

@@ -111,11 +111,24 @@ export declare const getNewZoomScaleWithinRange: (currentZoomScale: number, dire
  */
 export declare const getWidgetMetaFromCatalog: <TFrameworkElementType = any, TFrameworkComponentType = any>(widgetKey: TDashboardWidgetKey, widgetsCatalog: TDashboardWidgetCatalogBase<TFrameworkElementType, TFrameworkComponentType>) => TWidgetMetaInfoBase<TFrameworkElementType>;
 
+/**
+ * @name IChildWidgetConfigEntry
+ * @description Interface for a child widget configuration entry
+ * @remarks Used in IDashboardConfig
+ * @see IDashboardConfig
+ */
 export declare interface IChildWidgetConfigEntry {
     parentWidgetKey: TDashboardWidgetKey;
     widgetKey: TDashboardWidgetKey;
 }
 
+/**
+ * @name IDashboardConfig
+ * @description Interface for the dashboard configuration
+ * @remarks Used to store the dashboard state
+ * @see IChildWidgetConfigEntry
+ * @see IDashboardSettingEntry
+ */
 export declare interface IDashboardConfig {
     userID: number | string;
     clientAppKey: string;
@@ -130,12 +143,26 @@ export declare interface IDashboardConfig {
     _stateDescription?: string;
 }
 
+/**
+ * @name IDashboardGridPropsBase
+ * @description Base interface for dashboard grid props passed to widgets.
+ * @remarks
+ * - `zoomScale` represents a uniform zoom applied to the dashboard UI. Default
+ *   behavior in the runtime clamps this value to a minimum of `0.7` and default
+ *   is `1` when not explicitly set.
+ * - `responsiveGrid` toggles responsive layout behaviors vs fixed grid sizing.
+ */
 export declare interface IDashboardGridPropsBase {
     isEditing: boolean;
     zoomScale: number;
     responsiveGrid: boolean;
 }
 
+/**
+ * @name IDashboardSettingEntry
+ * @description Interface for a dashboard setting entry
+ * @see cssSettingsCatalog in dashboard-settings.ts
+ */
 export declare interface IDashboardSettingEntry {
     key: string;
     name: string;
@@ -148,11 +175,35 @@ export declare interface IDashboardSettingEntry {
     value: string;
 }
 
+/**
+ * @name IDashboardStorageService
+ * @description Interface for the dashboard storage service
+ * @remarks Used to define the storage service methods
+ * @see TGetSavedDashboards
+ * @see TSaveDashboards
+ * @see IDashboardConfig
+ */
 export declare interface IDashboardStorageService {
     getSavedDashboards: TGetSavedDashboards;
     saveDashboards: TSaveDashboards;
 }
 
+/**
+ * @name IDashboardWidgetPropsBase
+ * @description Props provided to every widget instance rendered by the dashboard.
+ * @template TExtraProps - Additional, widget-specific props supplied by the
+ * dashboard or integrator via the dynamic loader.
+ * @remarks
+ * - `index` and `maxIndex` indicate the widget's position and the current
+ *   maximum index used for ordering (zero-based indexing is typical).
+ * - `widgetKey` is the stable `TDashboardWidgetKey` identifying the widget
+ *   type; `parentWidgetKey` is set for nested/child widgets.
+ * - Boolean flags like `hideTitle`, `noShadow`, `noBorder`, `noPadding` are
+ *   layout/presentation hints; default behavior should be documented by the
+ *   concrete widget implementation.
+ * - `direction` applies to container widgets only.
+ * - `extraProps` is merged into the widget props by the `DynamicWidgetLoader`.
+ */
 export declare interface IDashboardWidgetPropsBase<TExtraProps = any> {
     index: number;
     maxIndex: number;
@@ -174,12 +225,23 @@ export declare interface IDashboardWidgetPropsBase<TExtraProps = any> {
 }
 
 /**
- * 2. Define the flexible Catalog Entry
- * Definition of a single widget or container in the catalog.
- * It must have EITHER a direct 'component' reference OR a 'loader' function.
- *
- * TFrameworkElementType: see TWidgetMetaInfoBase
- * TFrameworkComponentType: i.e. React.ComponentType<any> (see TWidgetFactoryBase)
+ * @name IDynamicWidgetCatalogEntryBase
+ * @description Catalog entry describing how to create or load a widget.
+ * @template TFrameworkElementType - Framework-specific element type (icon, element)
+ * @template TFrameworkComponentType - Framework-specific component type
+ * @remarks
+ * - `key` must be unique and stable across versions because it is stored in
+ *   saved dashboard configurations.
+ * - `title` is the display name for catalogs and selection UIs.
+ * - `isContainer` indicates a widget that can host children.
+ * - `isRemote` marks entries that are expected to be loaded remotely (CDN,
+ *   external script) and may require extra loading/initialization steps.
+ * - `meta` contains presentation metadata (see `TWidgetMetaInfoBase`).
+ * - `component` is a direct component reference (preferred for static/core widgets).
+ * - `loader` is an async factory used for dynamic/plugin widgets. When both
+ *   `component` and `loader` are provided, loaders are typically used for
+ *   dynamic initialization; concrete loaders/components precedence should be
+ *   defined by the integrator.
  */
 export declare interface IDynamicWidgetCatalogEntryBase<TFrameworkElementType = any, TFrameworkComponentType = any> {
     key: TDashboardWidgetKey;
@@ -204,13 +266,14 @@ export declare const parseContainerTitle: (containerWidgetKey: TDashboardWidgetK
 /**
  * Enhanced helper to derive key and title from widget file paths.
  * Handles:
+ * - widget-total-orders -> WidgetTotalOrders
  * - widget-revenue-trends1 -> WidgetRevenueTrends1
  * - widget-with-extraprops -> WidgetWithExtraprops
  * - widget-revenue-trends-async -> WidgetRevenueTrendsAsync
  */
 export declare const parseKeyAndTitleFromFilePath: (path: string) => {
     key: TDashboardWidgetKey;
-    title: string;
+    name: string;
     folder: string;
 } | null;
 
@@ -231,6 +294,11 @@ export declare const removeEmptyContainers: (dashboardConfig: IDashboardConfig)
  */
 export declare const resolveColorFromClass: (classNames: string | string[], property?: "color" | "backgroundColor") => string;
 
+/**
+ * @name TDashboardUndoStatus
+ * @description Type for the dashboard undo/redo status
+ * @remarks Used in dashboard undo/redo functionality
+ */
 export declare type TDashboardUndoStatus = {
     isUndoDisabled: boolean;
     isRedoDisabled: boolean;
@@ -238,64 +306,190 @@ export declare type TDashboardUndoStatus = {
     _historyLength?: number;
 };
 
+/**
+ * @name TDashboardWidgetCatalogBase
+ * @description Map of available widgets used by the dashboard at runtime.
+ * @template TFrameworkElementType - Framework-specific element type
+ * @template TFrameworkComponentType - Framework-specific component type
+ * @remarks Keys are `TDashboardWidgetKey` and values are catalog entries. The
+ * map is typically treated as a read-only registry; replace the map to update
+ * the available widget set rather than mutating entries in-place.
+ */
 export declare type TDashboardWidgetCatalogBase<TFrameworkElementType = any, TFrameworkComponentType = any> = Map<TDashboardWidgetKey, IDynamicWidgetCatalogEntryBase<TFrameworkElementType, TFrameworkComponentType>>;
 
+/**
+ * @name TDashboardWidgetKey
+ * @description Type for the unique key identifying a dashboard widget.
+ * @remarks
+ * This is a simple alias for `string` to allow flexibility in widget keys.
+ * Recommended formats: stable short strings (e.g. `myApp.ChartWidget`),
+ * namespaced identifiers or UUIDs. Consumers should avoid empty strings.
+ */
 export declare type TDashboardWidgetKey = string;
 
+/**
+ * @name TGetDefaultWidgetMetaFromKey
+ * @description Function that returns default `TWidgetMetaInfoBase` metadata for a widget key.
+ * @remarks Implementations should return a new object (not a shared reference)
+ * so callers can safely mutate the result if needed.
+ * @see TWidgetMetaInfoBase
+ * @see TGetDefaultWidgetMetaFromKeyOptions
+ * @returns `TWidgetMetaInfoBase`
+ */
 export declare type TGetDefaultWidgetMetaFromKey = (widgetKey: TDashboardWidgetKey, options?: TGetDefaultWidgetMetaFromKeyOptions) => TWidgetMetaInfoBase<any>;
 
+/**
+ * @name TGetDefaultWidgetMetaFromKeyOptions
+ * @description Optional overrides when generating default widget metadata.
+ * @remarks Fields provided here override the generated metadata's `title`
+ * and/or `description`.
+ */
 export declare type TGetDefaultWidgetMetaFromKeyOptions = {
-    title?: string;
+    name?: string;
     description?: string;
 };
 
+/**
+ * @name TGetSavedDashboards
+ * @description Function type to get saved dashboards for a user
+ * @remarks Used in IDashboardStorageService
+ * @see IDashboardConfig
+ * @see TDashboardWidgetCatalogBase
+ * @return Promise<IDashboardConfig[]>
+ */
 export declare type TGetSavedDashboards = (userID: number | string, clientAppKey: string, widgetCatalog: TDashboardWidgetCatalogBase, defaultDashboardConfig: IDashboardConfig) => Promise<IDashboardConfig[]>;
 
+/**
+ * @name TManifestEntry
+ * @description Entry describing a remote widget manifest or resource.
+ * @remarks
+ * - `url` should point to the resource or manifest (absolute URLs recommended).
+ * - `meta` contains widget metadata (see `TWidgetMetaInfoBase`) describing the
+ *   remotely loaded widget.
+ */
 export declare type TManifestEntry = {
     url: string;
     meta: TWidgetMetaInfoBase;
 };
 
+/**
+ * @name TSaveDashboards
+ * @description Function type to save dashboards for a user
+ * @remarks Used in IDashboardStorageService
+ * @see IDashboardConfig
+ * @see TDashboardWidgetCatalogBase
+ * @return Promise<boolean>
+ */
 export declare type TSaveDashboards = (userID: number | string, clientAppKey: string, dashboardConfigs: IDashboardConfig[], widgetCatalog: TDashboardWidgetCatalogBase) => Promise<boolean>;
 
+/**
+ * @name TUndoHistoryEntry
+ * @description Type for an undo history entry
+ * @remarks Used in dashboard undo/redo functionality
+ * @see IDashboardConfig
+ */
 export declare type TUndoHistoryEntry = {
     undoIndex: number;
     config: IDashboardConfig;
 };
 
+/**
+ * @name TWidgetCategory
+ * @description Type for widget categories used for grouping and UI filters.
+ * @remarks
+ * Typical usage: categorizing widgets in a palette, grouping by behavior
+ * (for instance `Container` widgets may host child widgets).
+ */
 export declare type TWidgetCategory = 'Widget' | 'Chart' | 'Container';
 
+/**
+ * @name TWidgetDirection
+ * @description Direction for layout flow inside container widgets.
+ * @remarks Only meaningful for container-type widgets that arrange children in
+ * either `row` or `column` flow.
+ */
 export declare type TWidgetDirection = 'row' | 'column';
 
 /**
- * 1. Define the Async Loader type
- * Type for the function that performs the asynchronous dynamic import.
- * It must return a promise that resolves to the module containing the widget component
- * as its default export (or a named export if you change the loading strategy).
- *
- * TFrameworkComponent could be "React.ComponentType<any>"" or "VueComponent" etc
+ * @name TWidgetFactoryBase
+ * @description Async factory used to lazily load a framework component for a widget.
+ * @template TFrameworkComponent - Framework-specific component type (e.g., React component)
+ * @returns Promise resolving to an object with a `default` export containing the component.
+ * @remarks Implementations should throw on unrecoverable load errors so callers
+ * can handle fallbacks; returning a stub is also acceptable when documented.
  */
 export declare type TWidgetFactoryBase<TFrameworkComponent = any> = () => Promise<{
     default: TFrameworkComponent;
 }>;
 
+/**
+ * @name TWidgetMetaInfoBase
+ * @description Base metadata for a widget used by catalogs and tooling.
+ * @template TFrameworkElementType - Framework-specific element type (e.g. React element, Vue component)
+ * @remarks
+ * Fields:
+ * - `name` (required): Human readable widget name.
+ * - `description` (required): Short description shown in tooltips or catalog lists.
+ * - `categories` (required): One or more `TWidgetCategory` values used for grouping.
+ * - `noDuplicatedWidgets` (optional): When true, dashboard UI should prevent
+ *   adding multiple instances of this widget.
+ * - `icon` (optional): Framework-specific icon element or component. May be
+ *   `undefined` when not provided.
+ * - `externalDependencies` (required): Array of package identifiers or CDN
+ *   references (e.g. `react@19.2.3`, `https://cdn.example.com/widget.js`). Use
+ *   semantic versions or absolute URLs as appropriate.
+ *
+ * Example:
+ * {
+ *   name: 'Simple Chart',
+ *   description: 'Displays a time series',
+ *   categories: ['Chart'],
+ *   noDuplicatedWidgets: false,
+ *   icon: undefined,
+ *   externalDependencies: ['d3@7.0.0']
+ * }
+ */
 export declare type TWidgetMetaInfoBase<TFrameworkElementType = any> = {
     name: string;
     description: string;
     categories: TWidgetCategory[];
     noDuplicatedWidgets?: boolean;
-    icon: TFrameworkElementType | undefined;
+    icon?: TFrameworkElementType | undefined;
     externalDependencies: string[];
 };
 
+/**
+ * @name TWidgetSize
+ * @description Size hint for widgets that can affect layout or styling.
+ * @remarks 'default' represents the standard size; 'large' and 'xlarge' are
+ * larger variants where the dashboard may allocate more grid cells.
+ */
 export declare type TWidgetSize = 'default' | 'large' | 'xlarge';
 
 /**
  * @name useDashboardStorageService
  * @description
- * This implementation of IDashboardStorageService uses localStorage to store custom dashboard configurations.
- * Developers can implement their own version of the dashboard storage service to store the data in a database or other way if needed.
- * @returns An instance of IDashboardStorageService
+ * LocalStorage-backed implementation of `IDashboardStorageService`.
+ *
+ * Behavior:
+ * - Persists an array of `IDashboardConfig` objects under the key
+ *   `dashboards_<clientAppKey>_<userID>` in `localStorage`.
+ * - `getSavedDashboards` performs lightweight validation and normalization when
+ *   reading saved data: fills missing `dashboardId`/`dashboardName`, sanitizes
+ *   CSS settings, filters unknown widget keys, and clamps `zoomScale`.
+ * - `saveDashboards` filters invalid widget keys, ensures required metadata
+ *   (`userID`, `clientAppKey`, `responsiveGrid`, `zoomScale`) and writes the
+ *   JSON-serialized dashboards to `localStorage`.
+ *
+ * Notes / limitations:
+ * - Uses synchronous browser `localStorage` with limited quota — not suitable
+ *   for very large datasets or high-frequency writes.
+ * - Does not provide server-side persistence or multi-user synchronization. To
+ *   persist dashboards centrally, implement a custom service that adheres to
+ *   `IDashboardStorageService` and replace this implementation.
+ *
+ * @returns An object implementing `IDashboardStorageService` with
+ * `getSavedDashboards` and `saveDashboards` methods.
  */
 export declare const useDashboardStorageService: () => IDashboardStorageService;
 

package/dist/core.es.js

@@ -156,9 +156,9 @@ const w = [
 }, U = (e) => {
   const t = `${e}`.split("_");
   return t.length > 1 ? t[1].replace(/(\D)(\d+)/, "$1 $2") : "Container";
-}, m = 0.7, p = 1, V = 0.05, D = (e) => {
+}, u = 0.7, p = 1, V = 0.05, D = (e) => {
   let t = Number(e || 0);
-  return t < m && (t = m), t > p && (t = p), t;
+  return t < u && (t = u), t > p && (t = p), t;
 }, j = (e, t) => {
   let a = Number(Number((V * t).toFixed(2)).toFixed(2)), i = Number((Number(e) + a).toFixed(2));
   return D(i);
@@ -193,7 +193,7 @@ const w = [
       parentWidgetKey: n || s
     };
   }), e;
-}, u = (e, t) => {
+}, m = (e, t) => {
   const a = `${e}`.includes("Container"), i = a ? ["Container"] : ["Widget"], s = t?.name || e, n = t?.description || (a ? "Container" : "Unknown");
   return {
     name: s,
@@ -203,8 +203,8 @@ const w = [
     icon: void 0,
     externalDependencies: []
   };
-}, I = (e, t, a) => t[e] || u(e, a), M = (e, t) => t.get(e)?.meta || u(e), k = (e, t, a) => {
-  const i = a || u(e);
+}, I = (e, t, a) => t[e] || m(e, a), M = (e, t) => t.get(e)?.meta || m(e), k = (e, t, a) => {
+  const i = a || m(e);
   return [
     e,
     {
@@ -217,7 +217,7 @@ const w = [
     }
   ];
 }, h = (e, t, a, i) => {
-  const s = i || u(e);
+  const s = i || m(e);
   return [
     e,
     {
@@ -235,7 +235,7 @@ const w = [
     const a = t[1], i = a.split("-"), s = `Widget${i.map((r) => r.charAt(0).toUpperCase() + r.slice(1)).join("")}`, n = i.map((r) => r.charAt(0).toUpperCase() + r.slice(1)).join(" ");
     return {
       key: s,
-      title: n,
+      name: n,
       folder: a
     };
   }
@@ -282,9 +282,10 @@ const w = [
   for (const n in t) {
     const r = t[n], c = F(n);
     if (c && r) {
-      const { key: o, title: d, folder: l } = c;
+      const { key: o, name: d, folder: l } = c;
       let g = $(a, e, l, o);
-      if (g || (g = u(o, {
+      if (g || (g = m(o, {
+        name: d,
         description: `Local ${i ? "dynamic" : "static"} widget`
       })), i)
         s.push(
@@ -343,7 +344,7 @@ const w = [
 ].join(" ").trim();
 export {
   p as DashboardMaxZoomScale,
-  m as DashboardMinZoomScale,
+  u as DashboardMinZoomScale,
   V as DashboardZoomStep,
   z as blankDashboardConfig,
   h as createDynamicEntry,
@@ -353,7 +354,7 @@ export {
   E as dashboardSettingsUtils,
   x as ensureContainersSequence,
   D as ensureZoomScaleIsWithinRange,
-  u as getDefaultWidgetMetaFromKey,
+  m as getDefaultWidgetMetaFromKey,
   I as getDefaultWidgetMetaFromMap,
   Z as getDistinctCssClasses,
   $ as getMetaInfoFromFile,

package/dist/react-dashboard.d.ts

@@ -78,11 +78,24 @@ export declare interface IButtonProps {
     tooltip?: ITooltipProps;
 }
 
+/**
+ * @name IChildWidgetConfigEntry
+ * @description Interface for a child widget configuration entry
+ * @remarks Used in IDashboardConfig
+ * @see IDashboardConfig
+ */
 export declare interface IChildWidgetConfigEntry {
     parentWidgetKey: TDashboardWidgetKey;
     widgetKey: TDashboardWidgetKey;
 }
 
+/**
+ * @name IDashboardConfig
+ * @description Interface for the dashboard configuration
+ * @remarks Used to store the dashboard state
+ * @see IChildWidgetConfigEntry
+ * @see IDashboardSettingEntry
+ */
 export declare interface IDashboardConfig {
     userID: number | string;
     clientAppKey: string;
@@ -106,12 +119,26 @@ export declare interface IDashboardGridProps extends IDashboardGridPropsBase {
     children?: ReactNode;
 }
 
+/**
+ * @name IDashboardGridPropsBase
+ * @description Base interface for dashboard grid props passed to widgets.
+ * @remarks
+ * - `zoomScale` represents a uniform zoom applied to the dashboard UI. Default
+ *   behavior in the runtime clamps this value to a minimum of `0.7` and default
+ *   is `1` when not explicitly set.
+ * - `responsiveGrid` toggles responsive layout behaviors vs fixed grid sizing.
+ */
 export declare interface IDashboardGridPropsBase {
     isEditing: boolean;
     zoomScale: number;
     responsiveGrid: boolean;
 }
 
+/**
+ * @name IDashboardSettingEntry
+ * @description Interface for a dashboard setting entry
+ * @see cssSettingsCatalog in dashboard-settings.ts
+ */
 export declare interface IDashboardSettingEntry {
     key: string;
     name: string;
@@ -124,6 +151,14 @@ export declare interface IDashboardSettingEntry {
     value: string;
 }
 
+/**
+ * @name IDashboardStorageService
+ * @description Interface for the dashboard storage service
+ * @remarks Used to define the storage service methods
+ * @see TGetSavedDashboards
+ * @see TSaveDashboards
+ * @see IDashboardConfig
+ */
 export declare interface IDashboardStorageService {
     getSavedDashboards: TGetSavedDashboards;
     saveDashboards: TSaveDashboards;
@@ -150,6 +185,22 @@ export declare interface IDashboardWidgetProps<TExtraProps = any> extends IDashb
     selectContainer?: (containerKey?: TDashboardWidgetKey) => void;
 }
 
+/**
+ * @name IDashboardWidgetPropsBase
+ * @description Props provided to every widget instance rendered by the dashboard.
+ * @template TExtraProps - Additional, widget-specific props supplied by the
+ * dashboard or integrator via the dynamic loader.
+ * @remarks
+ * - `index` and `maxIndex` indicate the widget's position and the current
+ *   maximum index used for ordering (zero-based indexing is typical).
+ * - `widgetKey` is the stable `TDashboardWidgetKey` identifying the widget
+ *   type; `parentWidgetKey` is set for nested/child widgets.
+ * - Boolean flags like `hideTitle`, `noShadow`, `noBorder`, `noPadding` are
+ *   layout/presentation hints; default behavior should be documented by the
+ *   concrete widget implementation.
+ * - `direction` applies to container widgets only.
+ * - `extraProps` is merged into the widget props by the `DynamicWidgetLoader`.
+ */
 export declare interface IDashboardWidgetPropsBase<TExtraProps = any> {
     index: number;
     maxIndex: number;
@@ -181,12 +232,23 @@ export declare interface IDynamicWidgetCatalogEntry extends IDynamicWidgetCatalo
 }
 
 /**
- * 2. Define the flexible Catalog Entry
- * Definition of a single widget or container in the catalog.
- * It must have EITHER a direct 'component' reference OR a 'loader' function.
- *
- * TFrameworkElementType: see TWidgetMetaInfoBase
- * TFrameworkComponentType: i.e. React.ComponentType<any> (see TWidgetFactoryBase)
+ * @name IDynamicWidgetCatalogEntryBase
+ * @description Catalog entry describing how to create or load a widget.
+ * @template TFrameworkElementType - Framework-specific element type (icon, element)
+ * @template TFrameworkComponentType - Framework-specific component type
+ * @remarks
+ * - `key` must be unique and stable across versions because it is stored in
+ *   saved dashboard configurations.
+ * - `title` is the display name for catalogs and selection UIs.
+ * - `isContainer` indicates a widget that can host children.
+ * - `isRemote` marks entries that are expected to be loaded remotely (CDN,
+ *   external script) and may require extra loading/initialization steps.
+ * - `meta` contains presentation metadata (see `TWidgetMetaInfoBase`).
+ * - `component` is a direct component reference (preferred for static/core widgets).
+ * - `loader` is an async factory used for dynamic/plugin widgets. When both
+ *   `component` and `loader` are provided, loaders are typically used for
+ *   dynamic initialization; concrete loaders/components precedence should be
+ *   defined by the integrator.
  */
 export declare interface IDynamicWidgetCatalogEntryBase<TFrameworkElementType = any, TFrameworkComponentType = any> {
     key: TDashboardWidgetKey;
@@ -297,6 +359,11 @@ declare type TDashboardSlice = {
 
 export declare type TDashboardUndoService = ReturnType<typeof useDashboardUndoService>;
 
+/**
+ * @name TDashboardUndoStatus
+ * @description Type for the dashboard undo/redo status
+ * @remarks Used in dashboard undo/redo functionality
+ */
 export declare type TDashboardUndoStatus = {
     isUndoDisabled: boolean;
     isRedoDisabled: boolean;
@@ -313,8 +380,25 @@ export declare type TDashboardUndoStatus = {
  */
 export declare type TDashboardWidgetCatalog = TDashboardWidgetCatalogBase<TFrameworkElementType, TFrameworkComponentType>;
 
+/**
+ * @name TDashboardWidgetCatalogBase
+ * @description Map of available widgets used by the dashboard at runtime.
+ * @template TFrameworkElementType - Framework-specific element type
+ * @template TFrameworkComponentType - Framework-specific component type
+ * @remarks Keys are `TDashboardWidgetKey` and values are catalog entries. The
+ * map is typically treated as a read-only registry; replace the map to update
+ * the available widget set rather than mutating entries in-place.
+ */
 export declare type TDashboardWidgetCatalogBase<TFrameworkElementType = any, TFrameworkComponentType = any> = Map<TDashboardWidgetKey, IDynamicWidgetCatalogEntryBase<TFrameworkElementType, TFrameworkComponentType>>;
 
+/**
+ * @name TDashboardWidgetKey
+ * @description Type for the unique key identifying a dashboard widget.
+ * @remarks
+ * This is a simple alias for `string` to allow flexibility in widget keys.
+ * Recommended formats: stable short strings (e.g. `myApp.ChartWidget`),
+ * namespaced identifiers or UUIDs. Consumers should avoid empty strings.
+ */
 export declare type TDashboardWidgetKey = string;
 
 declare type TDynamicWidgetLoaderProps<TExtraProps = any> = {
@@ -349,6 +433,14 @@ declare type TFrameworkComponentType = React.ComponentType<any>;
  */
 declare type TFrameworkElementType = React.ElementType;
 
+/**
+ * @name TGetSavedDashboards
+ * @description Function type to get saved dashboards for a user
+ * @remarks Used in IDashboardStorageService
+ * @see IDashboardConfig
+ * @see TDashboardWidgetCatalogBase
+ * @return Promise<IDashboardConfig[]>
+ */
 declare type TGetSavedDashboards = (userID: number | string, clientAppKey: string, widgetCatalog: TDashboardWidgetCatalogBase, defaultDashboardConfig: IDashboardConfig) => Promise<IDashboardConfig[]>;
 
 declare type TIconProps = {
@@ -363,6 +455,14 @@ declare type TListItemChildProps = {
     children?: ReactNode;
 };
 
+/**
+ * @name TManifestEntry
+ * @description Entry describing a remote widget manifest or resource.
+ * @remarks
+ * - `url` should point to the resource or manifest (absolute URLs recommended).
+ * - `meta` contains widget metadata (see `TWidgetMetaInfoBase`) describing the
+ *   remotely loaded widget.
+ */
 export declare type TManifestEntry = {
     url: string;
     meta: TWidgetMetaInfoBase;
@@ -375,6 +475,14 @@ declare type TProps = {
 
 declare type TRemoveWidgetResponse = TAddWidgetResponse;
 
+/**
+ * @name TSaveDashboards
+ * @description Function type to save dashboards for a user
+ * @remarks Used in IDashboardStorageService
+ * @see IDashboardConfig
+ * @see TDashboardWidgetCatalogBase
+ * @return Promise<boolean>
+ */
 declare type TSaveDashboards = (userID: number | string, clientAppKey: string, dashboardConfigs: IDashboardConfig[], widgetCatalog: TDashboardWidgetCatalogBase) => Promise<boolean>;
 
 declare type TSize = 'small' | 'medium';
@@ -387,13 +495,32 @@ export declare type TStackProps = {
     children: React.ReactNode;
 };
 
+/**
+ * @name TUndoHistoryEntry
+ * @description Type for an undo history entry
+ * @remarks Used in dashboard undo/redo functionality
+ * @see IDashboardConfig
+ */
 export declare type TUndoHistoryEntry = {
     undoIndex: number;
     config: IDashboardConfig;
 };
 
+/**
+ * @name TWidgetCategory
+ * @description Type for widget categories used for grouping and UI filters.
+ * @remarks
+ * Typical usage: categorizing widgets in a palette, grouping by behavior
+ * (for instance `Container` widgets may host child widgets).
+ */
 export declare type TWidgetCategory = 'Widget' | 'Chart' | 'Container';
 
+/**
+ * @name TWidgetDirection
+ * @description Direction for layout flow inside container widgets.
+ * @remarks Only meaningful for container-type widgets that arrange children in
+ * either `row` or `column` flow.
+ */
 export declare type TWidgetDirection = 'row' | 'column';
 
 /**
@@ -405,12 +532,12 @@ export declare type TWidgetDirection = 'row' | 'column';
 export declare type TWidgetFactory = TWidgetFactoryBase<TFrameworkComponentType>;
 
 /**
- * 1. Define the Async Loader type
- * Type for the function that performs the asynchronous dynamic import.
- * It must return a promise that resolves to the module containing the widget component
- * as its default export (or a named export if you change the loading strategy).
- *
- * TFrameworkComponent could be "React.ComponentType<any>"" or "VueComponent" etc
+ * @name TWidgetFactoryBase
+ * @description Async factory used to lazily load a framework component for a widget.
+ * @template TFrameworkComponent - Framework-specific component type (e.g., React component)
+ * @returns Promise resolving to an object with a `default` export containing the component.
+ * @remarks Implementations should throw on unrecoverable load errors so callers
+ * can handle fallbacks; returning a stub is also acceptable when documented.
  */
 export declare type TWidgetFactoryBase<TFrameworkComponent = any> = () => Promise<{
     default: TFrameworkComponent;
@@ -423,12 +550,39 @@ export declare type TWidgetFactoryBase<TFrameworkComponent = any> = () => Promis
  */
 export declare type TWidgetMetaInfo = TWidgetMetaInfoBase<TFrameworkElementType | undefined>;
 
+/**
+ * @name TWidgetMetaInfoBase
+ * @description Base metadata for a widget used by catalogs and tooling.
+ * @template TFrameworkElementType - Framework-specific element type (e.g. React element, Vue component)
+ * @remarks
+ * Fields:
+ * - `name` (required): Human readable widget name.
+ * - `description` (required): Short description shown in tooltips or catalog lists.
+ * - `categories` (required): One or more `TWidgetCategory` values used for grouping.
+ * - `noDuplicatedWidgets` (optional): When true, dashboard UI should prevent
+ *   adding multiple instances of this widget.
+ * - `icon` (optional): Framework-specific icon element or component. May be
+ *   `undefined` when not provided.
+ * - `externalDependencies` (required): Array of package identifiers or CDN
+ *   references (e.g. `react@19.2.3`, `https://cdn.example.com/widget.js`). Use
+ *   semantic versions or absolute URLs as appropriate.
+ *
+ * Example:
+ * {
+ *   name: 'Simple Chart',
+ *   description: 'Displays a time series',
+ *   categories: ['Chart'],
+ *   noDuplicatedWidgets: false,
+ *   icon: undefined,
+ *   externalDependencies: ['d3@7.0.0']
+ * }
+ */
 export declare type TWidgetMetaInfoBase<TFrameworkElementType = any> = {
     name: string;
     description: string;
     categories: TWidgetCategory[];
     noDuplicatedWidgets?: boolean;
-    icon: TFrameworkElementType | undefined;
+    icon?: TFrameworkElementType | undefined;
     externalDependencies: string[];
 };
 
@@ -445,6 +599,12 @@ export declare type TWidgetsCatalogFlyoutProps = {
     onDoneClick: () => any;
 };
 
+/**
+ * @name TWidgetSize
+ * @description Size hint for widgets that can affect layout or styling.
+ * @remarks 'default' represents the standard size; 'large' and 'xlarge' are
+ * larger variants where the dashboard may allocate more grid cells.
+ */
 export declare type TWidgetSize = 'default' | 'large' | 'xlarge';
 
 export declare function UndoIcon({ className }: TIconProps): JSX_2.Element;

package/dist/react-dashboard.es.js

@@ -2519,7 +2519,10 @@ function rn({
       `${a.widgetKey}_${f}`
     ))
   } : {};
-  return C ? /* @__PURE__ */ n(xt, { fallback: /* @__PURE__ */ n(nn, { title: `Loading ${h.title}` }), children: /* @__PURE__ */ n(b, { ...l, ...M }) }) : /* @__PURE__ */ n(b, { ...l, ...M });
+  return C ? /* @__PURE__ */ $(xt, { fallback: /* @__PURE__ */ n(nn, { title: `Loading ${h.title}` }), children: [
+    "]",
+    /* @__PURE__ */ n(b, { ...l, ...M })
+  ] }) : /* @__PURE__ */ n(b, { ...l, ...M });
 }
 const ye = "size-5";
 function Ie(e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenorlab/react-dashboard",
-  "version": "1.4.7",
+  "version": "1.5.2",
   "description": "Foundation components for creating user-configurable dashboards in React",
   "author": "Damiano Fusco",
   "type": "module",
@@ -54,7 +54,7 @@
     "zustand": "^5.0.0 || ^5.0.9"
   },
   "devDependencies": {
-    "@tenorlab/dashboard-core": "^1.4.2",
+    "@tenorlab/dashboard-core": "^1.5.1",
     "@types/node": "^24.10.1",
     "@types/react": "19.2.3",
     "@types/react-dom": "19.2.3",