# @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.
- 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.
- Workspace-aware metadata loading for modules and properties.
- 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. Pie/donut legends render through the
  package custom legend outside the ECharts canvas, and 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.

## Installation

```bash
pnpm add @masterteam/dashboard-builder
```

## Usage

```typescript
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 and
  display legacy `label` text alongside the color indicator.

## Development

```bash
# 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
