From cd4121f7984f28b514231589407e9fbbb50c32ba Mon Sep 17 00:00:00 2001 From: 4gray Date: Thu, 26 Mar 2026 08:11:49 +0100 Subject: [PATCH] chore: remove outdated workspace UI refactor summary documentation Entire-Checkpoint: e6dee91f3aee --- .../workspace-ui-refactor-summary.md | 253 ------------------ 1 file changed, 253 deletions(-) delete mode 100644 docs/architecture/workspace-ui-refactor-summary.md diff --git a/docs/architecture/workspace-ui-refactor-summary.md b/docs/architecture/workspace-ui-refactor-summary.md deleted file mode 100644 index bc1fadbaf..000000000 --- a/docs/architecture/workspace-ui-refactor-summary.md +++ /dev/null @@ -1,253 +0,0 @@ -# Workspace UI Refactor Summary - -Date: 2026-02-22 - -## 1) What Was Refactored - -The app moved from a setup-first flow (playlist management first, then provider-specific UI) to a **workspace shell** flow with a persistent app frame: - -1. Fixed left navigation rail (global + context links). -2. Persistent top header (playlist switcher, search, actions, favorites shortcut, sorting where relevant). -3. Secondary left panel for: - 1. Sources filters on `/workspace/sources`. - 2. Provider category context for Xtream/Stalker content sections. -4. Unified workspace routing with dashboard and sources as first-class views. - -Core entrypoint: - -1. `apps/web/src/app/workspace/workspace-shell.component.ts` -2. `apps/web/src/app/workspace/workspace-shell.component.html` - -Shared rail link model: - -1. `apps/web/src/app/shared/navigation/portal-rail-links.ts` -2. `apps/web/src/app/shared/navigation/portal-rail-links.component.ts` - -## 2) New Dashboard (Current State) - -The dashboard is now a real widget host with persisted layout and customization. - -Key parts: - -1. Widget model and defaults: - 1. `libs/workspace/dashboard/data-access/src/lib/dashboard-widget.model.ts` -2. Persisted layout store with migration support: - 1. `libs/workspace/dashboard/data-access/src/lib/dashboard-layout.service.ts` -3. Widget host: - 1. `libs/workspace/dashboard/ui/src/lib/dashboard-widget-host.component.ts` - 2. `libs/workspace/dashboard/ui/src/lib/dashboard-widget-host.component.html` -4. Dashboard page (view + customize mode): - 1. `libs/workspace/dashboard/feature/src/lib/workspace-dashboard.component.ts` - 2. `libs/workspace/dashboard/feature/src/lib/workspace-dashboard.component.html` - -Active widget set: - -1. Recent Sources -2. Source Statistics -3. Continue Watching -4. Recently Watched (global, scope-aware) -5. Global Favorites (global, scope-aware) - -Notes: - -1. Widget scope settings (provider + playlist filtering) are implemented for scoped widgets. - -## 2.1) Dashboard Idea and Widget Implementation - -### Product idea - -The dashboard is designed as a content-first operational home, not a source setup page. - -Goals: - -1. Show high-value content immediately after app start. -2. Reduce context switching between Xtream, Stalker, and M3U flows. -3. Keep widgets independent so one data failure does not break the page. -4. Allow gradual customization without introducing heavy layout complexity too early. - -Design principles: - -1. Widgets are about user tasks (continue watching, favorites, recent activity), not provider internals. -2. Each widget must have explicit loading/empty/error states. -3. Widget settings should be persistent and reversible. -4. Navigation from widget cards should deep-link directly to the right route and content context. - -### Implementation shape - -Core implementation files: - -1. Dashboard page and orchestration: - 1. `libs/workspace/dashboard/feature/src/lib/workspace-dashboard.component.ts` - 2. `libs/workspace/dashboard/feature/src/lib/workspace-dashboard.component.html` -2. Widget metadata contract: - 1. `libs/workspace/dashboard/data-access/src/lib/dashboard-widget.model.ts` -3. Layout + settings persistence: - 1. `libs/workspace/dashboard/data-access/src/lib/dashboard-layout.service.ts` -4. Widget rendering host: - 1. `libs/workspace/dashboard/ui/src/lib/dashboard-widget-host.component.ts` -5. Data aggregation and widget inputs: - 1. `libs/workspace/dashboard/data-access/src/lib/dashboard-data.service.ts` -6. Shared activity item renderer (used by multiple widgets): - 1. `libs/workspace/dashboard/ui/src/lib/widgets/dashboard-activity-items.component.ts` - -### How widget rendering works - -1. `workspace-dashboard` reads layout state (widget list, order, enabled state, settings). -2. For each enabled widget, `dashboard-widget-host` maps `widget.type` to a concrete widget component. -3. The host passes widget config (`scope`, `settings`, mode flags) into the widget. -4. Widget requests data through `dashboard-data.service` and/or existing provider services/stores. -5. Widget emits navigation actions, which are translated into direct route deep-links. - -### How persistence works - -Layout is stored as a versioned dashboard configuration: - -1. Widget identity and type -2. Visibility (`enabled`) -3. Order -4. Scope (`providers`, optional `playlistIds`) -5. Widget-specific `settings` - -On load: - -1. Stored layout is validated against current widget registry/defaults. -2. Missing or removed widgets are migrated safely. -3. Invalid settings fall back to defaults, preventing dashboard hard-fail. - -### Widget UX behavior implemented - -1. `Recently Watched` and `Global Favorites`: - 1. Content-kind chips (channels/vod/series) - 2. List/grid toggle - 3. Shared item styles - 4. Deep-link navigation into details/views -2. `Continue Watching`: - 1. Resume-oriented content block -3. `Recent Sources`: - 1. Source activity with truncation-safe titles -4. `Source Statistics`: - 1. Aggregated per-provider/source counters -5. `Recent Activity` was intentionally removed from scope. - -### How to add a new widget (current workflow) - -1. Add a new `type` in `dashboard-widget.model.ts`. -2. Implement widget component under `libs/workspace/dashboard/ui/src/lib/widgets/`. -3. Register it in `dashboard-widget-host.component.ts` type mapping. -4. Add default config in layout defaults/migration path (`dashboard-layout.service.ts`). -5. Extend `dashboard-data.service.ts` or reuse existing feature services for data. -6. Add explicit loading/empty/error UI states and deep-link behavior. - -### Current boundaries - -1. Advanced drag/resize grid and collision engine is not implemented yet. -2. External adapters (RSS/sports/news) are intentionally deferred. - -## 3) Route Generalization (Current Routing Topology) - -Primary app routing now starts in workspace: - -1. `/` -> `/workspace` -2. `/workspace/dashboard` -3. `/workspace/sources` -4. `/workspace/playlists/:id` (M3U player in workspace frame) -5. `/workspace/xtreams/:id/...` (workspace layout applied) -6. `/workspace/stalker/:id/...` (workspace layout applied) - -Defined in: - -1. `apps/web/src/app/app.routes.ts` - -Mechanism: - -1. Existing provider route trees (`xtreamRoutes`, `stalkerRoutes`) are wrapped by `withWorkspaceLayout(...)` and receive `data.layout = 'workspace'`. -2. Provider shells/components use `isWorkspaceLayout` to hide legacy local sidebars/header pieces. - -## 4) Generalized UX Behaviors Added - -1. Playlist switcher integrated into persistent header and used as cross-context navigator: - 1. `libs/ui/components/src/lib/playlist-switcher/playlist-switcher.component.ts` -2. Header search unified, with debounced apply for route/store updates: - 1. `apps/web/src/app/workspace/workspace-shell.component.ts` -3. Sources filtering moved to dedicated panel: - 1. `apps/web/src/app/workspace/workspace-sources-filters-panel.component.ts` -4. Context categories moved to shared workspace panel: - 1. `apps/web/src/app/workspace/workspace-context-panel.component.ts` -5. Dashboard activity items deep-link directly to content context/details; Xtream live entries auto-play on open. - -## 5) Legacy/Old Parts Still Present - -### A) Legacy routes kept for compatibility - -In `apps/web/src/app/app.routes.ts`: - -1. `/home` -2. `/playlists` -3. `/iptv` -4. `/playlists/:id` -5. Non-workspace provider routes: - 1. `/xtreams/:id/...` - 2. `/stalker/:id/...` -6. Alias `/portals/:id` -> `StalkerMainContainerComponent` - -### B) Legacy Xtream module tree kept as fallback - -1. `apps/web/src/app/xtream/*` - -This is still used by `legacyXtreamRouteFallback` when `!window.electron`. - -### C) Dual-layout branching across provider components - -Many provider components still have workspace/non-workspace conditional branches via `isWorkspaceLayout` (for sidebar/header/body behavior). This is intentional compatibility, but increases maintenance. - -Examples: - -1. `apps/web/src/app/xtream-electron/xtream-shell.component.html` -2. `apps/web/src/app/stalker/stalker-shell.component.html` -3. `apps/web/src/app/xtream-electron/xtream-main-container.component.html` -4. `apps/web/src/app/stalker/stalker-main-container.component.html` -5. `apps/web/src/app/home/video-player/video-player.component.html` - -### D) Unused placeholder artifact - -1. `apps/web/src/app/workspace/dashboard-placeholder.component.ts` -2. `apps/web/src/app/workspace/dashboard-placeholder.component.html` -3. `apps/web/src/app/workspace/dashboard-placeholder.component.scss` - -These files are no longer routed. - -## 6) Potential Removals (With Preconditions) - -### Low risk (can remove soon) - -1. Remove unused dashboard placeholder files (`dashboard-placeholder.*`). - -### Medium risk (requires product decision) - -1. Remove `/portals/:id` alias route if no external/deeplink dependency remains. -2. Remove legacy entry routes (`/home`, `/iptv`, `/playlists`, `/playlists/:id`) if workspace-only navigation is desired. - -### High risk (requires platform/support policy decision) - -1. Remove legacy fallback module `apps/web/src/app/xtream/*` and `legacyXtreamRouteFallback` only if non-Electron fallback is officially dropped. -2. Remove non-workspace provider routes (`/xtreams/:id/...`, `/stalker/:id/...`) only after verifying all deeplinks/bookmarks/integration paths have migrated to `/workspace/...`. - -## 7) Recommended Cleanup Sequence - -1. Remove unused placeholder files. -2. Decide whether non-workspace URLs must remain public and supported. -3. If workspace-only is approved: - 1. Deprecate legacy routes with redirects. - 2. Remove non-workspace route trees. - 3. Remove `isWorkspaceLayout` branches and simplify provider layouts. -4. If non-Electron fallback is not required: - 1. Remove `legacyXtreamRouteFallback`. - 2. Remove `apps/web/src/app/xtream/*`. - -## 8) Current Plan Items Still Open - -From current plan scope, remaining work is primarily: - -1. Widget settings UX improvements (scope presets, bulk provider toggles). -2. Phase 3 dashboard advanced layout system (drag/resize/collision handling). -3. Phase 4 external widget framework (RSS/scores/news adapters + reliability controls).