@masterteam/dashboard-builder

Dashboard Builder components and services for Angular 21+ with Tailwind CSS 4. The package supports authoring, saving, loading, and rendering dashboards with charts, header widgets, topbar widgets, metadata-driven data sources, source links, and responsive ECharts output.

Features

• Multilingual dashboard item titles stored as clientConfig.title.en/ar.
• Header, topbar, and chart item title editing in builder mode.
• Host-interceptor-owned save messages, with automatic saves marked silent.
• Registry-driven chart query schemas, including safe preview states for incomplete draft charts.
• Stacked-bar query fields switch between auto-stack and manual-stack modes so only the relevant stack property selector is displayed and emitted.
• Quick Manage style changes stay local in the drawer until Apply, with an isolated Preview tab for checking the edited chart config before the dashboard canvas is updated.
• Chart header icons provide preset-based appearance and placement controls, including independent standalone/group visibility and grouped icon-only mode.
• Timeline multi-level queries persist per-level extraProperties and still read legacy extras fields.
• Selected-property chips in dashboard query editors can be removed inline.
• Properties/card-list items normalize null Percentage values to 0 with an empty progress track and never inherit a sibling card's runtime percentage.
• Duplicated charts receive a new local dashboard identity, omit the source link/component IDs so the next save creates a new backend chart, and persist duplicatedFrom as provenance to the source dashboard identity.
• Workspace-aware metadata loading for modules and properties.
• A dedicated chart Filters action separates viewer-facing filter controls and built-in conditions from datasource configuration, using shared mt-* form fields throughout the condition editor.
• Navigation actions expose a Navigation Target selector. Both page and entity navigation default to the current tab and can explicitly open in a new tab through action.config.navigationTarget.
• Progress Update cards render activity HTML through ngx-quill's read-only renderer, preserving the rich-text size, color, font, alignment, direction, and semantic formatting configured in the source editor.
• Persisted dashboards can be deleted from the page-settings drawer after a named, danger-styled confirmation; successful deletion returns the host to its dashboard list while standalone builders keep deletion unavailable.
• Module multi-select serialized as selectors such as Level:1,2,3.
• Source-link chaining with previous result fields, relationship fields, and the Parent option exposed to child-level configuration.
• Distinct aggregation normalization from legacy DisticntCount to DistinctCount.
• Container-aware ECharts option mapping for compact dashboard grid cells, including shared legend placement for donut, pie, bar, line, stacked bar, and other ECharts-based charts. Pie/donut radius, center, and slice-label geometry stay handler-owned to match the old dashboard builder; the shared EChart wrapper reserves the same chart area as the old wrapper and does not apply pie-specific responsive overrides. Native ECharts legend rendering stays authoritative; the wrapper maps legend dimensions before grid offsets and clamps saved percentage grid values against the current card pixels so stacked bar legends keep reserved space after resize. Donut slice labels are hidden so category names stay in the legend instead of being drawn over the ring. Pie legend vertical alignment applies only to left/right legends, so old saved vertical-align values do not move the default bottom legend into the chart body. Compact bar and line charts preserve their configured value-label visibility instead of hiding labels when the card height crosses a responsive breakpoint.

Installation

pnpm add @masterteam/dashboard-builder

Usage

import { Component } from "@angular/core";
import { DashboardBuilder } from "@masterteam/dashboard-builder";

@Component({
  imports: [DashboardBuilder],
  template: ` <mt-dashboard-builder [services]="['pplus', 'splus']" (onSave)="saveDashboard()" /> `,
})
export class MyComponent {
  saveDashboard(): void {
    // React to a completed explicit save.
  }
}

Metadata Contract

Hosts must provide the dashboard metadata endpoints used by DashboardBuilderService:

• GET metadata/workspaces returns workspace options: WorkspaceOption { id: string | number; name: string }.
• GET metadata/modules/tree accepts services, workspaceId, and includeValues. Returned module groups, items, and values may include workspaceId for client-side filtering.
• POST metadata/modules/properties accepts items and optional workspaceId. Each request item may also include workspaceId.

When a workspace changes, the builder clears selections and source links that no longer belong to the selected workspace.

Compatibility Notes

• Saved selectors remain backward-compatible with legacy moduleType/moduleId values and comma-based module ids.
• Existing multilingual title objects are preserved. Plain string titles are normalized to the active title object shape.
• The builder does not show save toasts directly. Save response messages belong to the host HTTP interceptor; automatic/internal save requests are sent with noMessage: true.
• Aggregation requests normalize legacy DisticntCount values to DistinctCount; backends should accept both names and execute distinct-count semantics.
• Table-card status legends support both grouped and flat label payloads, display legacy label text alongside the color indicator, and expose visibility plus per-entry order/color controls in Style Studio for Table, Dialog Table, and PhaseGate Table items.
• ChartDataService.clearCache(dashboardId?) clears LimitedHttpService cache entries by chart item id (serviceConfig.dashboardId) when an id is passed, or clears all chart responses when omitted. Scoped clears also bypass matching in-flight requests so the next fetch cannot reuse stale data after a host create/edit/delete action.
• DashboardViewer.reloadPage() is a host-facing mutation refresh API: it clears the dashboard chart HTTP cache before triggering all chart items, so calls such as viewer()?.reloadPage() always send fresh backend requests.

Development

# Build only the dashboard-builder package
pnpm build:db

# Focused tests for changed specs
pnpm --filter @masterteam/dashboard-builder test -- --watch=false --include=<path>.spec.ts

Do not use the full @masterteam/components build for routine component work unless the caller explicitly approves it.

License

MIT