@fidurcode/dashboard-widgets-skeleton

Reusable Angular components and services for building dynamic dashboard widgets with configurable layout, responsive sizing, and focused edit controls.

Requirements

• Angular ^22.0.0
• Node.js >=26.0.0

This package is built from a workspace using Angular CLI ^22.0.1, @angular/build:ng-packagr, ng-packagr ^22.0.0, and TypeScript ^6.0.3.

📦 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 |

Content contract

Every component passed as widget content must expose a widgetSize input. The dashboard updates it with the actual content area available inside the widget.

import { Component, input, InputSignal } from '@angular/core';
import {
  DashboardWidgetContentComponent,
  DashboardWidgetContentSize,
} from '@fidurcode/dashboard-widgets-skeleton';

@Component({
  selector: 'app-sales-widget',
  template: '<section class="sales-widget">...</section>',
  styles: [`
    :host,
    .sales-widget {
      display: block;
      width: 100%;
      height: 100%;
      min-width: 0;
      min-height: 0;
      box-sizing: border-box;
    }
  `],
})
export class SalesWidgetComponent implements DashboardWidgetContentComponent {
  widgetSize: InputSignal<DashboardWidgetContentSize> = input.required();
}

The content component should render within width: 100% and height: 100%; use the numeric widgetSize.width, widgetSize.height, widgetSize.rows, and widgetSize.columns values for charts, canvases, tables, or other components that need explicit dimensions.

WidgetOptionsComponent

Selector: app-widget-options

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

Features

• Resize — toggle group for columns (width) and rows (height)
• 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<DashboardWidgetContentComponent>;
  rows?: number;
  columns?: number;
  defaultRows?: number;       // initial rows when widget is first added
  defaultColumns?: number;    // initial columns when widget is first added
}

🌍 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",
    "DELETE": "Delete",
    "MOVE_LEFT": "Move left",
    "MOVE_RIGHT": "Move right",
    "CLOSE_OPTIONS": "Close",
    "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, and columns.

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