@tenorlab/vue-dashboard 1.0.0

package/README.md

@@ -0,0 +1,49 @@
+# @tenorlab/react-dashboard
+
+Foundation components for creating user-configurable, high-performance dashboards in React.
+
+---
+
+### Part of the Built With JavaScript Ecosystem
+**Tenorlab** is the specialized software foundry for the [@builtwithjavascript](https://github.com/builtwithjavascript) ecosystem, focusing on modular, type-safe utilities and UI kits.
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+Install the package via npm or pnpm:
+
+```bash
+npm install @tenorlab/react-dashboard
+# or
+pnpm add @tenorlab/react-dashboard
+```
+
+## Basic Usage
+Import the styles in your entry tsx file (usually main.tsx):
+```typescript
+import '@tenorlab/react-dashboard/styles.css'
+```
+
+TODO:
+
+
+## Features
+
+- **Type-Safe:** Built with TypeScript for excellent IDE support and error catching.
+- **Configurable:** Allow end-users to add/remove widgets.
+- **Vite Optimized:** Tree-shakeable and lightweight for modern build pipelines.
+- **Themeable:** Easy integration with Tailwind CSS or CSS Variables.
+
+
+
+## Licensing
+
+This project is dual-licensed:
+
+1. **Non-Commercial / Personal Use:** Licensed under the [Polyform Non-Commercial 1.0.0](https://polyformproject.org/licenses/non-commercial/1.0.0/). Free to use for students, hobbyists, and open-source projects.
+2. **Commercial Use:** Requires a **Tenorlab Commercial License**.
+
+If you are using this library to build a product that generates revenue, or within a commercial entity, please visit [tenorlab.com/license](https://tenorlab.com/license) to purchase a commercial seat.

package/dist/core.d.ts

@@ -0,0 +1,301 @@
+export declare const blankDashboardConfig: IDashboardConfig;
+
+/**
+ * @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];
+
+/**
+ * @name cssSettingsCatalog
+ * @description Catalog of available dashboard settings (array of IDashboardSettingEntry)
+ * @see IDashboardSettingEntry
+ * @remarks step should never be less than 0.1 as we do some rounding in other places ...
+ */
+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 DashboardMaxZoomScale: 1;
+
+export declare const DashboardMinZoomScale: 0.7;
+
+/**
+ * @name dashboardSettingsUtils
+ * @description Contains utils for the dashboard custom settings
+ */
+export declare const dashboardSettingsUtils: {
+    /**
+     * @name incrementOrDecrementValue
+     * @description Increments or decrement a value based on the direction parameter
+     * @param item: an instance of IDashboardSettingEntry
+     * @param direction: -1 (for decrement) or 1 (for increment)
+     * @returns the update item
+     */
+    incrementOrDecrementValue: (item: IDashboardSettingEntry, direction: -1 | 1) => IDashboardSettingEntry;
+};
+
+export declare const DashboardZoomStep: 0.05;
+
+/**
+ * @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 interface IChildWidgetConfigEntry {
+    parentWidgetKey: TDashboardWidgetKey;
+    widgetKey: TDashboardWidgetKey;
+}
+
+export declare interface IDashboardConfig {
+    userID: number | string;
+    clientAppKey: string;
+    dashboardId: string;
+    dashboardName: string;
+    zoomScale: number;
+    responsiveGrid: boolean;
+    widgets: TDashboardWidgetKey[];
+    childWidgetsConfig: IChildWidgetConfigEntry[];
+    cssSettings: IDashboardSettingEntry[];
+    _version?: number;
+    _stateDescription?: string;
+}
+
+export declare interface IDashboardGridPropsBase {
+    isEditing: boolean;
+    zoomScale: number;
+    responsiveGrid: boolean;
+}
+
+export declare interface IDashboardSettingEntry {
+    key: string;
+    name: string;
+    description: string;
+    cssProperty: string;
+    step: number;
+    defaultUnit: string;
+    minValue: number;
+    defaultValue: string;
+    value: string;
+}
+
+export declare interface IDashboardStorageService {
+    getSavedDashboards: TGetSavedDashboards;
+    saveDashboards: TSaveDashboards;
+}
+
+export declare interface IDashboardWidgetPropsBase<TExtraProps = any> {
+    index: number;
+    maxIndex: number;
+    widgetKey: TDashboardWidgetKey;
+    parentWidgetKey?: TDashboardWidgetKey;
+    isEditing: boolean;
+    highlight?: boolean;
+    testId?: string;
+    title?: string;
+    size?: TWidgetSize;
+    borderCssClasses?: string;
+    backgroundCssClasses?: string;
+    hideTitle?: boolean;
+    noShadow?: boolean;
+    noBorder?: boolean;
+    noPadding?: boolean;
+    direction?: TWidgetDirection;
+    extraProps?: TExtraProps;
+}
+
+/**
+ * 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)
+ */
+export declare interface IDynamicWidgetCatalogEntryBase<TFrameworkElementType = any, TFrameworkComponentType = any> {
+    key: TDashboardWidgetKey;
+    title: string;
+    isContainer?: boolean;
+    meta?: TWidgetMetaInfoBase<TFrameworkElementType>;
+    component?: TFrameworkComponentType;
+    loader?: TWidgetFactoryBase<TFrameworkComponentType>;
+}
+
+/**
+ * @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 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 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 type TDashboardUndoStatus = {
+    isUndoDisabled: boolean;
+    isRedoDisabled: boolean;
+    _currentIndex?: number;
+    _historyLength?: number;
+};
+
+export declare type TDashboardWidgetCatalogBase<TFrameworkElementType = any, TFrameworkComponentType = any> = Map<TDashboardWidgetKey, IDynamicWidgetCatalogEntryBase<TFrameworkElementType, TFrameworkComponentType>>;
+
+export declare type TDashboardWidgetKey = string;
+
+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[]>;
+
+export declare type TManifestEntry = {
+    url: string;
+    meta: TWidgetMetaInfoBase;
+};
+
+export declare type TSaveDashboards = (userID: number | string, clientAppKey: string, dashboardConfigs: IDashboardConfig[], widgetCatalog: TDashboardWidgetCatalogBase) => Promise<boolean>;
+
+export declare type TUndoHistoryEntry = {
+    undoIndex: number;
+    config: IDashboardConfig;
+};
+
+export declare type TWidgetCategory = 'Widget' | 'Chart' | 'Container';
+
+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
+ */
+export declare type TWidgetFactoryBase<TFrameworkComponent = any> = () => Promise<{
+    default: TFrameworkComponent;
+}>;
+
+export declare type TWidgetMetaInfoBase<TFrameworkElementType = any> = {
+    name: string;
+    description: string;
+    categories: TWidgetCategory[];
+    noDuplicatedWidgets?: boolean;
+    icon: TFrameworkElementType | undefined;
+    externalDependencies: string[];
+};
+
+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
+ */
+export declare const useDashboardStorageService: () => IDashboardStorageService;
+
+export { }