iptvnator/docs/architecture/workspace-dashboard.md

Workspace Dashboard

This document records the current dashboard implementation inside the workspace shell. It replaces the earlier dashboard plan document.

Related:

• Workspace Shell

Summary

• The dashboard is the default /workspace landing page.
• It is a widget-based surface with persisted layout and widget settings.
• The current implementation favors a constrained, stable layout over a full freeform grid system.

Core implementation:

1. libs/workspace/dashboard/feature/src/lib/workspace-dashboard.component.ts
2. libs/workspace/dashboard/feature/src/lib/workspace-dashboard.component.html
3. libs/workspace/dashboard/ui/src/lib/dashboard-widget-host.component.ts
4. libs/workspace/dashboard/data-access/src/lib/dashboard-widget.model.ts
5. libs/workspace/dashboard/data-access/src/lib/dashboard-layout.service.ts
6. libs/workspace/dashboard/data-access/src/lib/dashboard-data.service.ts

Current Widget Set

Registered widget types:

1. source-stats
2. continue-watching
3. recently-watched
4. global-favorites

Default layout:

1. continue-watching
   1. Enabled by default
   2. Size full
2. recently-watched
   1. Enabled by default
   2. Size two-thirds
   3. Scope-aware
3. global-favorites
   1. Enabled by default
   2. Size one-third
   3. Scope-aware
4. source-stats
   1. Present in the registry
   2. Disabled by default
   3. Size one-third

The old refactor summary mentioned Recent Sources, but that widget is not in the current registry and should not be documented as shipped behavior.

Layout And Persistence Contract

The dashboard persists a versioned layout object in local storage.

Current storage details:

1. Storage key: workspace-dashboard-layout-v3
2. Schema version: 12
3. Size presets:
   1. one-third
   2. half
   3. two-thirds
   4. full
4. Scope settings:
   1. providers: Array<'m3u' | 'xtream' | 'stalker'>
   2. playlistIds: string[]

Normalization rules in DashboardLayoutService:

1. Stored widgets are merged against DEFAULT_DASHBOARD_WIDGETS.
2. Missing widgets are restored from defaults.
3. Removed or invalid settings fall back to normalized defaults.
4. Titles and descriptions come from the current code-defined defaults, not stale stored values.
5. Widget order is reindexed after normalization.

Rendering Flow

1. WorkspaceDashboardComponent reads DashboardLayoutService.state().
2. Enabled widgets are filtered and rendered in layout order.
3. DashboardWidgetHostComponent maps widget.type to a concrete widget component.
4. Widgets receive the normalized config, including size and optional scope.
5. Data comes from DashboardDataService and existing provider/state services.
6. Widget actions deep-link back into workspace/provider routes.

Customize Mode

Customize mode is part of the current product, not future work.

Supported actions:

1. Toggle widget visibility.
2. Drag-and-drop reorder for visible widgets.
3. Change widget size within the fixed preset list.
4. Configure provider scope for scoped widgets.
5. Configure playlist scope for scoped widgets.
6. Reset the layout to defaults.

Scope-aware widgets currently rely on a provider/playlist filter model rather than per-widget custom query systems.

UX Rules

1. Widgets should represent user tasks, not provider internals.
2. Each widget must own its loading, empty, and error states.
3. Dashboard failures must stay isolated to the widget that failed.
4. Widget navigation should resolve directly into the relevant content context.
5. New widgets should fit the existing constrained layout model unless the dashboard architecture is explicitly being expanded.

Adding Or Changing Widgets

Current workflow:

1. Add or update the widget type in dashboard-widget.model.ts.
2. Implement the widget UI under libs/workspace/dashboard/ui/src/lib/widgets/.
3. Register the widget in dashboard-widget-host.component.ts.
4. Add default state and migration-safe behavior in dashboard-layout.service.ts.
5. Extend dashboard-data.service.ts or reuse an existing feature service.
6. Ensure the widget has explicit empty/error/loading states and valid workspace deep links.

Deferred Work

These items are intentionally not part of the current contract:

1. Freeform drag/resize grid with collision management.
2. External data widgets such as RSS, sports, or news adapters.
3. A widget marketplace or plugin system.