@fidurcode/dashboard-widgets-skeleton

Reusable Angular components and services for building dynamic dashboard widgets with configurable layout, sizing, colors, and interactive controls.

📦 Installation

npm install @fidurcode/dashboard-widgets-skeleton

🚀 Usage

Import the module:

import { DashboardWidgetsSkeletonModule } from '@fidurcode/dashboard-widgets-skeleton';

@NgModule({
  imports: [DashboardWidgetsSkeletonModule],
})
export class AppModule {}

Use in template:

<fidurcode-dashboard-widgets
  [title]="'My Dashboard'"
  [widgets]="widgets"
  [rowHeight]="80"
  [widgetPadding]="12"
  (widgetChange)="onWidgetChange($event)">
</fidurcode-dashboard-widgets>

🧩 Components Overview

DashboardWidgetsComponent

Selector: fidurcode-dashboard-widgets

Main container component. Manages layout, persistence (localStorage), and edit mode.

Inputs

| Name | Type | Default | Description | |----------------|--------------------|----------------------|--------------------------------------------------| | title | string | (required) | Dashboard header title | | widgets | Widget[] | (required) | Available widget definitions | | storageKey | string | 'dashboard-widgets'| localStorage key for persisting layout | | columns | number or 'auto' | 'auto' | Grid column count or 'auto' for responsive fit | | minTileWidth | number | 200 | Minimum tile width in px (used in auto mode) | | rowHeight | number | 80 | Row height in px | | gap | number | 12 | Gap between widgets in px | | maxColumns | number | 4 | Maximum columns available in widget options | | maxRows | number | 4 | Maximum rows available in widget options | | widgetPadding| number | 12 | Padding inside widget content area in px | | editMode | boolean | true | Initial edit mode state |

Outputs

| Name | Type | Description | |----------------|------------|--------------------------------------------------| | widgetChange | Widget[] | Emits the current widget list on every change |

WidgetComponent

Selector: app-widget

Individual widget wrapper. Renders dynamic content and provides a header with action buttons.

Inputs

| Name | Type | Required | Description | |--------|----------|----------|--------------------------------| | data | Widget | ✅ Yes | Widget configuration object |

Features

• Collapse/expand — toggles widget to header-only view; state is persisted
• Fullscreen — expands widget to cover the full viewport; press Escape to exit
• Inline rename — double-click the title to rename (edit mode only)
• Edit mode guard — settings button hidden when dashboard is locked

WidgetOptionsComponent

Selector: app-widget-options

Settings overlay rendered inside the widget. Visible only in edit mode on unpinned widgets.

Features

• Rename — overrides the widget label with a custom name
• Resize — toggle group for columns (width) and rows (height)
• Color palette — 7 accent colors + default; applied as widget background
• Pin/unpin — pinned widgets cannot be moved or deleted
• Delete — removes widget from dashboard
• Move left/right — reorders widget in the grid

🏗️ Widget Interface

interface Widget {
  id: number;
  label: string;              // translation key
  content: Type<unknown>;     // Angular component to render as content
  rows?: number;
  columns?: number;
  defaultRows?: number;       // initial rows when widget is first added
  defaultColumns?: number;    // initial columns when widget is first added
  color?: string;             // CSS color string (e.g. '#3b82f6')
  pinned?: boolean;
  collapsed?: boolean;
  customLabel?: string;       // user-defined label override (not a translation key)
}

🌍 Required Translation Keys

Add the following keys to your ngx-translate translation files:

{
  "DASHBOARD": {
    "ADD_WIDGET": "Add widget",
    "NO_WIDGETS": "No widgets available",
    "LOCK": "Lock dashboard",
    "UNLOCK": "Unlock dashboard"
  },
  "WIDGET": {
    "WIDTH": "Width",
    "HEIGHT": "Height",
    "RENAME": "Name",
    "COLOR": "Color",
    "COLOR_DEFAULT": "Default",
    "DELETE": "Delete",
    "PIN": "Pin",
    "UNPIN": "Unpin",
    "MOVE_LEFT": "Move left",
    "MOVE_RIGHT": "Move right",
    "CLOSE_OPTIONS": "Close",
    "COLLAPSE": "Collapse",
    "EXPAND": "Expand",
    "FULLSCREEN": "Fullscreen",
    "EXIT_FULLSCREEN": "Exit fullscreen",
    "SETTINGS": "Settings"
  }
}

Widget label fields are also treated as translation keys and resolved at runtime.

💾 Layout Persistence

The dashboard automatically saves and restores widget state via localStorage using the storageKey input. Persisted state includes: position order, rows, columns, color, custom label, collapsed state, and pinned state.

The format is backward compatible — dashboards saved with v1.4.x (IDs only) are migrated automatically on first load.