@tenorlab/react-dashboard 1.3.5 → 1.3.7

package/dist/react-dashboard.d.ts

@@ -10,18 +10,75 @@ import { UseBoundStore } from 'zustand';
 
 export declare function AddIcon({ className }: TIconProps): JSX_2.Element;
 
+export declare const blankDashboardConfig: IDashboardConfig;
+
 export declare function Button(props: IButtonProps): JSX_2.Element;
 
 export declare function CircleQuestionMark({ className }: TIconProps): JSX_2.Element;
 
+/**
+ * @name createDynamicEntry
+ * Helper function to create dynamic entries
+ * This helps keep the catalog registration clean
+ */
+export declare const createDynamicEntry: (key: string, loader: TWidgetFactoryBase, metaData: TWidgetMetaInfoBase) => [string, IDynamicWidgetCatalogEntryBase];
+
+/**
+ * @name createStaticEntry
+ * Helper function to create static entries
+ * This helps keep the catalog registration clean
+ */
+export declare const createStaticEntry: <TFrameworkComponentType = any>(key: string, component: TFrameworkComponentType, metaData?: TWidgetMetaInfoBase) => [string, IDynamicWidgetCatalogEntryBase];
+
 export declare function CrosshairIcon({ className }: TIconProps): JSX_2.Element;
 
+export declare const cssSettingsCatalog: IDashboardSettingEntry[];
+
+/**
+ * @name cssVarsUtils
+ * @description Provides helpers method like getCssVariableValue, setCssVariableValue etc
+ */
+export declare const cssVarsUtils: {
+    /**
+     * @name getCssVariableValue
+     * @description Return the value of a CSS custom property from the current HTML document
+     * @param cssPropertyName
+     * @returns
+     */
+    getCssVariableValue: (cssPropertyName: string) => string | null;
+    /**
+     * @name setCssVariableValue
+     * @description Sets the value of a CSS custom property on the current HTML document
+     * @param cssPropertyName
+     * @param value
+     */
+    setCssVariableValue: (cssPropertyName: string, value: string) => void;
+    /**
+     * @name restoreCssVarsFromSettings
+     * @description
+     * Sets the values of many CSS custom properties on the current HTML document
+     * from the list of dashboard settings provided
+     * @param settings, an array of IDashboardSettingEntry
+     */
+    restoreCssVarsFromSettings: (settings: IDashboardSettingEntry[]) => void;
+};
+
 export declare const DashboardGrid: ForwardRefExoticComponent<IDashboardGridProps & RefAttributes<HTMLDivElement>>;
 
+export declare const DashboardMaxZoomScale: 1;
+
+export declare const DashboardMinZoomScale: 0.7;
+
+export declare const dashboardSettingsUtils: {
+    incrementOrDecrementValue: (item: IDashboardSettingEntry, direction: -1 | 1) => IDashboardSettingEntry;
+};
+
 export declare const DashboardWidgetBase: (props: IDashboardWidgetProps & {
     ref?: React.ForwardedRef<HTMLDivElement>;
 }) => React.ReactElement | null;
 
+export declare const DashboardZoomStep: 0.05;
+
 export declare function DeleteIcon({ className }: TIconProps): JSX_2.Element;
 
 export declare const DraggablePanel: ForwardRefExoticComponent<DraggablePanelProps & RefAttributes<HTMLDivElement>>;
@@ -45,6 +102,45 @@ export declare function DynamicWidgetLoader({ index, maxIndex, widgetKey, parent
 
 export declare function EditIcon({ className }: TIconProps): JSX_2.Element;
 
+/**
+ * @name ensureContainersSequence
+ * @description
+ * Ensures that the container widgets are numbered sequentially in the dashboardConfig, but the original order is preserved.
+ */
+export declare const ensureContainersSequence: (dashboardConfig: IDashboardConfig) => IDashboardConfig;
+
+export declare const ensureZoomScaleIsWithinRange: (value: number) => number;
+
+export declare const getDefaultWidgetMetaFromKey: TGetDefaultWidgetMetaFromKey;
+
+/**
+ * @name getDefaultWidgetMetaFromMap
+ * @description Helper to get widget meta info from the catalog by key.
+ */
+export declare const getDefaultWidgetMetaFromMap: <TFrameworkElementType = any>(widgetKey: TDashboardWidgetKey, defaultWidgetMetaMap: Record<TDashboardWidgetKey, TWidgetMetaInfoBase<TFrameworkElementType>>, options?: {
+    title?: string;
+    description?: string;
+}) => TWidgetMetaInfoBase<TFrameworkElementType>;
+
+/**
+ * @name getDistinctCssClasses
+ * @description Ensures a distinct list off css classes, avoiding duplicates
+ * @param defaultClasses
+ * @param additionalClasses
+ * @returns the distinct list as a string
+ */
+export declare const getDistinctCssClasses: (defaultClasses: string, ...additionalClasses: string[]) => string;
+
+export declare const getMetaInfoFromFile: (widgetMetaModules: Record<string, Record<string, TWidgetMetaInfoBase>>, baseSrcPath: string, folder: string, key: string) => TWidgetMetaInfoBase | undefined;
+
+export declare const getNewZoomScaleWithinRange: (currentZoomScale: number, direction: -1 | 1) => number;
+
+/**
+ * @name getWidgetMetaFromCatalog
+ * @description Helper to get widget meta info from the catalog by key.
+ */
+export declare const getWidgetMetaFromCatalog: <TFrameworkElementType = any, TFrameworkComponentType = any>(widgetKey: TDashboardWidgetKey, widgetsCatalog: TDashboardWidgetCatalogBase<TFrameworkElementType, TFrameworkComponentType>) => TWidgetMetaInfoBase<TFrameworkElementType>;
+
 export declare function GridIcon({ className }: TIconProps): JSX_2.Element;
 
 export declare function HandGrabIcon({ className }: TIconProps): JSX_2.Element;
@@ -78,12 +174,12 @@ export declare interface IButtonProps {
     tooltip?: ITooltipProps;
 }
 
-declare interface IChildWidgetConfigEntry {
+export declare interface IChildWidgetConfigEntry {
     parentWidgetKey: TDashboardWidgetKey;
     widgetKey: TDashboardWidgetKey;
 }
 
-declare interface IDashboardConfig {
+export declare interface IDashboardConfig {
     userID: number | string;
     clientAppKey: string;
     dashboardId: string;
@@ -101,13 +197,13 @@ export declare interface IDashboardGridProps extends IDashboardGridPropsBase {
     children?: ReactNode;
 }
 
-declare interface IDashboardGridPropsBase {
+export declare interface IDashboardGridPropsBase {
     isEditing: boolean;
     zoomScale: number;
     responsiveGrid: boolean;
 }
 
-declare interface IDashboardSettingEntry {
+export declare interface IDashboardSettingEntry {
     key: string;
     name: string;
     description: string;
@@ -119,6 +215,11 @@ declare interface IDashboardSettingEntry {
     value: string;
 }
 
+export declare interface IDashboardStorageService {
+    getSavedDashboards: TGetSavedDashboards;
+    saveDashboards: TSaveDashboards;
+}
+
 export declare interface IDashboardWidget extends JSX.Element {
 }
 
@@ -129,7 +230,7 @@ export declare interface IDashboardWidgetProps<TExtraProps = any> extends IDashb
     selectContainer?: (containerKey?: TDashboardWidgetKey) => void;
 }
 
-declare interface IDashboardWidgetPropsBase<TExtraProps = any> {
+export declare interface IDashboardWidgetPropsBase<TExtraProps = any> {
     index: number;
     maxIndex: number;
     widgetKey: TDashboardWidgetKey;
@@ -160,7 +261,7 @@ export declare interface IDynamicWidgetCatalogEntry extends IDynamicWidgetCatalo
  * TFrameworkElementType: see TWidgetMetaInfoBase
  * TFrameworkComponentType: i.e. React.ComponentType<any> (see TWidgetFactoryBase)
  */
-declare interface IDynamicWidgetCatalogEntryBase<TFrameworkElementType = any, TFrameworkComponentType = any> {
+export declare interface IDynamicWidgetCatalogEntryBase<TFrameworkElementType = any, TFrameworkComponentType = any> {
     key: TDashboardWidgetKey;
     title: string;
     isContainer?: boolean;
@@ -206,6 +307,14 @@ export declare const ListItemMiddleChild: ForwardRefExoticComponent<TListItemChi
 
 export declare const ListItemRightChild: ForwardRefExoticComponent<TListItemChildProps & RefAttributes<HTMLDivElement>>;
 
+/**
+ * @name localWidgetDiscovery
+ * @description Scans local directories for widgets.
+ * If lazy is true, it registers loaders. If false, it registers static components.
+ */
+export declare const localWidgetDiscovery: (baseSrcPath: string, // e.g., "/src/async-widgets" or "/src/bundled-widgets"
+widgetModules: Record<string, any>, widgetMetaModules: Record<string, any>, lazy?: boolean) => [string, IDynamicWidgetCatalogEntryBase][];
+
 export declare function MonitorIcon({ className }: TIconProps): JSX_2.Element;
 
 export declare function MonitorSmartphoneIcon({ className }: TIconProps): JSX_2.Element;
@@ -214,8 +323,40 @@ export declare function MoveLeftIcon({ className }: TIconProps): JSX_2.Element;
 
 export declare function MoveRightIcon({ className }: TIconProps): JSX_2.Element;
 
+export declare const parseContainerTitle: (containerWidgetKey: TDashboardWidgetKey) => string;
+
+/**
+ * Enhanced helper to derive key and title from widget file paths.
+ * Handles:
+ * - widget-revenue-trends1 -> WidgetRevenueTrends1
+ * - widget-with-extraprops -> WidgetWithExtraprops
+ * - widget-revenue-trends-async -> WidgetRevenueTrendsAsync
+ */
+export declare const parseKeyAndTitleFromFilePath: (path: string) => {
+    key: TDashboardWidgetKey;
+    title: string;
+    folder: string;
+} | null;
+
 export declare function RedoIcon({ className }: TIconProps): JSX_2.Element;
 
+export declare const remoteWidgetDiscovery: (manifestUrl: string) => Promise<{
+    entries: [string, IDynamicWidgetCatalogEntryBase][];
+    message: string;
+    details: string;
+}>;
+
+export declare const removeEmptyContainers: (dashboardConfig: IDashboardConfig) => IDashboardConfig;
+
+/**
+ * @name resolveColorFromClass
+ * @description Resolves the current computed color using your existing CSS classes
+ * @param classNames, i.e. 'bg-primary'
+ * @param property to resolve, i.e. 'backgroundColor'
+ * @returns
+ */
+export declare const resolveColorFromClass: (classNames: string | string[], property?: "color" | "backgroundColor") => string;
+
 export declare function SettingsIcon({ className }: TIconProps): JSX_2.Element;
 
 export declare const showToast: (options: any) => void;
@@ -268,7 +409,7 @@ declare type TDashboardSlice = {
 
 export declare type TDashboardUndoService = ReturnType<typeof useDashboardUndoService>;
 
-declare type TDashboardUndoStatus = {
+export declare type TDashboardUndoStatus = {
     isUndoDisabled: boolean;
     isRedoDisabled: boolean;
     _currentIndex?: number;
@@ -277,9 +418,9 @@ declare type TDashboardUndoStatus = {
 
 export declare type TDashboardWidgetCatalog = TDashboardWidgetCatalogBase<TFrameworkElementType, TFrameworkComponentType>;
 
-declare type TDashboardWidgetCatalogBase<TFrameworkElementType = any, TFrameworkComponentType = any> = Map<TDashboardWidgetKey, IDynamicWidgetCatalogEntryBase<TFrameworkElementType, TFrameworkComponentType>>;
+export declare type TDashboardWidgetCatalogBase<TFrameworkElementType = any, TFrameworkComponentType = any> = Map<TDashboardWidgetKey, IDynamicWidgetCatalogEntryBase<TFrameworkElementType, TFrameworkComponentType>>;
 
-declare type TDashboardWidgetKey = string;
+export declare type TDashboardWidgetKey = string;
 
 declare type TDynamicWidgetLoaderProps<TExtraProps = any> = {
     index: number;
@@ -305,6 +446,15 @@ declare type TFrameworkComponentType = React.ComponentType<any>;
 
 declare type TFrameworkElementType = React.ElementType;
 
+export declare type TGetDefaultWidgetMetaFromKey = (widgetKey: TDashboardWidgetKey, options?: TGetDefaultWidgetMetaFromKeyOptions) => TWidgetMetaInfoBase<any>;
+
+export declare type TGetDefaultWidgetMetaFromKeyOptions = {
+    title?: string;
+    description?: string;
+};
+
+export declare type TGetSavedDashboards = (userID: number | string, clientAppKey: string, widgetCatalog: TDashboardWidgetCatalogBase, defaultDashboardConfig: IDashboardConfig) => Promise<IDashboardConfig[]>;
+
 declare type TIconProps = {
     className?: string;
 };
@@ -317,6 +467,11 @@ declare type TListItemChildProps = {
     children?: ReactNode;
 };
 
+export declare type TManifestEntry = {
+    url: string;
+    meta: TWidgetMetaInfoBase;
+};
+
 declare type TProps = {
     children: React.ReactNode;
     addCssClasses?: string;
@@ -324,6 +479,8 @@ declare type TProps = {
 
 declare type TRemoveWidgetResponse = TAddWidgetResponse;
 
+export declare type TSaveDashboards = (userID: number | string, clientAppKey: string, dashboardConfigs: IDashboardConfig[], widgetCatalog: TDashboardWidgetCatalogBase) => Promise<boolean>;
+
 declare type TSize = 'small' | 'medium';
 
 export declare type TStackProps = {
@@ -334,14 +491,14 @@ export declare type TStackProps = {
     children: React.ReactNode;
 };
 
-declare type TUndoHistoryEntry = {
+export declare type TUndoHistoryEntry = {
     undoIndex: number;
     config: IDashboardConfig;
 };
 
-declare type TWidgetCategory = 'Widget' | 'Chart' | 'Container';
+export declare type TWidgetCategory = 'Widget' | 'Chart' | 'Container';
 
-declare type TWidgetDirection = 'row' | 'column';
+export declare type TWidgetDirection = 'row' | 'column';
 
 export declare type TWidgetFactory = TWidgetFactoryBase<TFrameworkComponentType>;
 
@@ -353,13 +510,13 @@ export declare type TWidgetFactory = TWidgetFactoryBase<TFrameworkComponentType>
  *
  * TFrameworkComponent could be "React.ComponentType<any>"" or "VueComponent" etc
  */
-declare type TWidgetFactoryBase<TFrameworkComponent = any> = () => Promise<{
+export declare type TWidgetFactoryBase<TFrameworkComponent = any> = () => Promise<{
     default: TFrameworkComponent;
 }>;
 
 export declare type TWidgetMetaInfo = TWidgetMetaInfoBase<TFrameworkElementType | undefined>;
 
-declare type TWidgetMetaInfoBase<TFrameworkElementType = any> = {
+export declare type TWidgetMetaInfoBase<TFrameworkElementType = any> = {
     name: string;
     description: string;
     categories: TWidgetCategory[];
@@ -381,10 +538,12 @@ export declare type TWidgetsCatalogFlyoutProps = {
     onDoneClick: () => any;
 };
 
-declare type TWidgetSize = 'default' | 'large' | 'xlarge';
+export declare type TWidgetSize = 'default' | 'large' | 'xlarge';
 
 export declare function UndoIcon({ className }: TIconProps): JSX_2.Element;
 
+export declare const useDashboardStorageService: () => IDashboardStorageService;
+
 export declare const useDashboardStore: UseBoundStore<StoreApi<TDashboardSlice>>;
 
 export declare const useDashboardUndoService: () => {

package/dist/styles.css

@@ -0,0 +1 @@
+html{--bwj-dashboard-num-columns: 3;--bwj-dashboard-gap: 1.25rem;--bwj-dashboard-transform-scale: 1;--bwj-dashboard-add-cols: 1;--bwj-widget-width: 21rem;--bwj-widget-border-radius: .33rem;--bwj-widget-inner-px: 1rem;--bwj-widget-inner-py: .75rem;--bwj-widget-header-px: var(--bwj-widget-inner-px);--bwj-widget-header-py: 1rem;--bwj-widget-title-size: .8rem;--bwj-widget-title-weight: 600;--bwj-dashboard-debug-container-flex-row: none;--bwj-dashboard-debug-container-flex-column: none;--bwj-dashboard-debug-container-grid-large-inner: none}html .dashboard-main-grid{width:100%;display:grid;grid-template-columns:repeat(var(--bwj-dashboard-num-columns, 4),minmax(var(--bwj-widget-width),1fr));gap:var(--bwj-dashboard-gap, 1.5rem);transform:scale(var(--bwj-dashboard-transform-scale, 1));transform-origin:top left}html .dashboard-main-grid.editing{row-gap:calc(var(--bwj-dashboard-gap) + .8rem)}html .dashboard-main-grid:not(.responsive-grid){max-width:min-content}html .dashboard-main-grid.responsive-grid{width:100%}html .dashboard-widget-container{--bwj-border-opacity: .5;flex:1 1 0%;width:100%}html .dashboard-widget-container .widget-container-header{display:none;position:absolute;height:1.85rem;inset:-1.85rem -1px auto;cursor:pointer;padding:0 .33rem}html .dashboard-widget-container .widget-container-header .actions-inner{transition:all .3s ease-in-out;width:100%;display:none;align-items:center;justify-content:space-between;font-size:.8rem}html .dashboard-widget-container.editing{border-top:none!important;border-bottom-left-radius:var(--bwj-widget-border-radius, .3rem);border-bottom-right-radius:var(--bwj-widget-border-radius, .3rem)}html .dashboard-widget-container.editing .widget-container-header{display:flex;border-bottom:none!important;border-top-left-radius:var(--bwj-widget-border-radius, .3rem);border-top-right-radius:var(--bwj-widget-border-radius, .3rem)}html .dashboard-widget-container.editing .widget-container-header>.actions-inner{display:flex!important}html .dashboard-widget-container.editing.highlight-container:before{content:"";position:absolute;inset:-1.85rem 0 0;box-shadow:0 2px 10px 6px oklch(var(--bwj-primary-okl) var(--bwj-primary-okc) var(--bwj-primary-okh) / .5);pointer-events:none}html .dashboard-widget{flex:1 1 0%;display:flex;flex-direction:column;position:relative;border-radius:var(--bwj-widget-border-radius, .3rem);height:100%;width:100%}html .dashboard-widget:not(.no-shadow){box-shadow:1px 2px 8px #0000001a}html .dashboard-widget.no-shadow{box-shadow:none}html .dashboard-widget.transparent-widget{background-color:transparent}html .dashboard-widget .widget-title-wrapper .widget-title{font-size:var(--bwj-widget-title-size, .75rem);font-weight:var(--bwj-widget-title-weight, 600)}html .dashboard-widget .widget-inner{flex:1 1 0%;display:flex;flex-direction:column;justify-content:space-between}html .dashboard-widget:not(.no-padding) .widget-inner{padding:var(--bwj-widget-inner-py, 1rem) var(--bwj-widget-inner-px, 1.5rem)}html .dashboard-widget.no-padding .widget-inner{padding:0}html .dashboard-widget .widget-header{padding:var(--bwj-widget-header-py, 1rem) var(--bwj-widget-header-px, 1.5rem)}html .dashboard-widget-container .widget-container-inner{padding:0;gap:var(--bwj-dashboard-gap, 1.5rem)}html .dashboard-widget-container.direction-row.widget-container-flex{grid-column:1 / -1;width:100%;outline:var(--bwj-dashboard-debug-container-flex-row)}html .dashboard-widget-container.direction-row.widget-container-flex .widget-container-inner{display:flex;flex-direction:row;height:100%}html .dashboard-widget-container.direction-row.widget-container-flex .widget-container-inner .dashboard-widget{min-width:5%;max-width:100%}html .dashboard-widget-container.direction-column.widget-container-flex .widget-container-inner{display:flex;flex-direction:column;height:100%;outline:var(--bwj-dashboard-debug-container-flex-column)}html .dashboard-widget-container.direction-column.widget-container-flex .widget-container-inner .dashboard-widget{min-width:5%;max-width:100%}html .dashboard-widget-container.large-widget.widget-container-grid .widget-container-inner{display:grid;grid-template-columns:repeat(2,minmax(var(--bwj-widget-width),1fr));outline:var(--bwj-dashboard-debug-container-grid-large-inner)}html .dashboard-main-grid.responsive-grid .dashboard-widget-container:not(.large-widget):not(.xlarge-widget),html .dashboard-main-grid.responsive-grid .dashboard-widget:not(.large-widget):not(.xlarge-widget){min-width:20%;max-width:100%}html .dashboard-main-grid:not(.responsive-grid) .dashboard-widget-container:not(.widget-container-flex):not(.large-widget):not(.xlarge-widget),html .widget-container-flex:not(.direction-row) .dashboard-main-grid:not(.responsive-grid) .dashboard-widget:not(.large-widget):not(.xlarge-widget){min-width:var(--bwj-widget-width);max-width:var(--bwj-widget-width)}html .dashboard-widget-container.large-widget,html .dashboard-widget.large-widget{grid-column:span 2}html .dashboard-main-grid:not(.responsive-grid) .dashboard-widget-container.large-widget,html .dashboard-main-grid:not(.responsive-grid) .dashboard-widget.large-widget{max-width:calc(680px + var(--bwj-dashboard-gap, 1.5rem))}html .dashboard-widget-container.xlarge-widget,html .dashboard-widget.xlarge-widget{grid-column:span 3}html .dashboard-main-grid:not(.responsive-grid) .dashboard-widget-container.xlarge-widget,html .dashboard-main-grid:not(.responsive-grid) .dashboard-widget.xlarge-widget{max-width:calc(1020px + (var(--bwj-dashboard-gap, 1.5rem) * 2))}html .widget-header .actions-inner{display:none;align-items:center;gap:.25rem}html .widget-header .actions-inner .actions-buttons-container{align-items:center;gap:.25rem}html .dashboard-widget.editing:hover .actions-inner{display:flex!important}html .dashboard-widget-container.editing .widget-container-header .actions-inner{display:flex}html .actions-buttons-container{display:flex!important;align-items:center!important;gap:.25rem!important}html .dashboard-number{font-variant-numeric:tabular-nums;font-size:2.5rem;font-weight:700}html .dashboard-number.number-xl{font-size:3.5rem}html .dashboard-number.number-lg{font-size:2.5rem}html .dashboard-number.number-base{font-size:1.5rem}html .dashboard-progress-bar{padding:0;width:100%;height:1.5rem;border-radius:.75rem}html .dashboard-progress{padding:0;height:1.25rem;border-radius:.75rem}@media(max-width:769px){html .dashboard-main-grid{display:flex;flex-direction:column;width:100%;max-width:100%!important}html .dashboard-widget-container.widget-container-flex.direction-row{max-width:100%;grid-column:auto}html .dashboard-widget-container.widget-container-flex.direction-row .widget-container-inner{display:flex;flex-wrap:wrap;flex-direction:column!important;width:100%}}@media(min-width:770px){html .dashboard-main-grid{--bwj-dashboard-num-columns: calc(2 + var(--bwj-dashboard-add-cols))}}@media(max-width:1119px){html .dashboard-widget-container.widget-container-flex.direction-row{max-width:100%;grid-column:auto}html .dashboard-widget-container.widget-container-flex.direction-row .widget-container-inner{display:flex;flex-wrap:wrap;flex-direction:column!important;width:100%}}@media(min-width:1120px){html .dashboard-main-grid{--bwj-dashboard-num-columns: calc(3 + var(--bwj-dashboard-add-cols))}}@media(min-width:1480px){html .dashboard-main-grid{--bwj-dashboard-num-columns: calc(4 + var(--bwj-dashboard-add-cols))}}@media(min-width:1840px){html .dashboard-main-grid{--bwj-dashboard-num-columns: calc(5 + var(--bwj-dashboard-add-cols))}}@media(min-width:2220px){html .dashboard-main-grid{--bwj-dashboard-num-columns: calc(6 + var(--bwj-dashboard-add-cols))}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenorlab/react-dashboard",
-  "version": "1.3.5",
+  "version": "1.3.7",
   "description": "Foundation components for creating user-configurable dashboards in React",
   "author": "Damiano Fusco",
   "type": "module",
@@ -42,7 +42,8 @@
     "./core": {
       "types": "./dist/core.d.ts",
       "import": "./dist/core.es.js" 
-    }
+    },
+    "./styles.css": "./dist/style.css"
   },
   "types": "./dist/react-dashboard.d.ts",
   "main": "./dist/react-dashboard.es.js",