mirror of
https://github.com/4gray/iptvnator.git
synced 2026-10-08 09:01:03 -08:00
UI-24 from the UI consistency audit.
- No-artwork slides paint their gradient in CSS from the slide hue: a light
tint in the light theme, unchanged near-black in the dark one. The dark
gradient under the light page-coloured scrim read as a grey slab.
- The side scrim holds 88% of the page colour up to the slide's right edge
(inset + min(560px, 55%)), so the end of a full slide no longer sits on
about 45%.
- Narrow layout (container <= 720px): a full-bleed 90% scrim behind the text
block, a scrim-coloured text shadow, and an entrance without a fade so
that scrim never flashes the art on a rotation.
- --hero-body is 85% of the heading colour (was 72%).
- Light --app-rating-color #a16207 -> #7a4a00: measured 3.36:1 on the chip
over artwork, now 5.10:1. The details pages share the chip and token.
- Buttons cap at the slide width and end long labels in an ellipsis.
- The page gets one visually hidden h1 ("Dashboard"); slide titles are h2.
- One live region outside the re-created slide announces slide changes;
progress bars are named and VOD ones read "N% watched"; dots are 24px.
dashboard-hero-legibility.e2e.ts replaces every image with a checkerboard
and measures each piece of slide text from the screen in both themes, wide
and narrow, for backdrop, poster, no-artwork and live slides. On master the
worst cases were 2.35:1 (body text) and 2.65:1 (pills).
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
467 lines
29 KiB
Markdown
467 lines
29 KiB
Markdown
# Workspace Dashboard
|
|
|
|
This document records the current dashboard implementation inside the workspace
|
|
shell.
|
|
|
|
Related:
|
|
|
|
- [Workspace Shell](./workspace-shell.md)
|
|
|
|
## Summary
|
|
|
|
- The dashboard is the default `/workspace` landing page.
|
|
- It is a **rail-based** content surface (Netflix / Apple TV pattern), not a
|
|
customizable widget grid.
|
|
- Layout order is static and curated — there is no edit mode, drag-drop, or
|
|
size stepper. Each rail has a persisted show/hide toggle
|
|
(`Settings.dashboardRails`, `DashboardRailsSettings` in
|
|
`libs/shared/interfaces/src/lib/settings.interface.ts`, surfaced under
|
|
Settings → Dashboard); every template rail is gated by
|
|
`dashboardRails().<key>`. Rails additionally auto-hide when empty.
|
|
- First-run users see the shared welcome empty-state with a single primary
|
|
CTA to add their first playlist.
|
|
|
|
Core implementation:
|
|
|
|
1. `libs/workspace/dashboard/feature/src/lib/rails/workspace-dashboard-rails.component.ts`
|
|
— the page-level facade.
|
|
2. `libs/workspace/dashboard/feature/src/lib/rails/dashboard-rail.component.ts`
|
|
— the reusable horizontal rail.
|
|
3. `libs/workspace/dashboard/data-access/src/lib/dashboard-data.service.ts`
|
|
— data aggregation (recent items, favorites, playlist stats). Shared across
|
|
rails.
|
|
4. `libs/playlist/shared/ui/src/lib/recent-playlists/empty-state/empty-state.component.ts`
|
|
— reused welcome state with the primary "Add your first playlist" CTA.
|
|
|
|
## Page Structure
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ Hero — rotating cinematic banner (resume · live · discovery) │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ Continue Watching · See all → │
|
|
│ [poster][poster][poster][poster] →→ │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ Live now on your favorites · See all → │
|
|
│ [channel][channel][channel][channel] →→ │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ Recently watched live TV · See all → │
|
|
│ [channel][channel][channel][channel] →→ │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ Favorite movies & series · See all → │
|
|
│ [poster][poster][poster][poster] →→ │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ Recently Used Sources · See all → │
|
|
│ [tile][tile][tile][tile] →→ │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ Recently Added on Xtream (aggregated across providers) │
|
|
│ [poster][poster][poster] →→ │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ Because you watched X (TMDB, opt-in, Electron-only) │
|
|
│ [poster][poster][poster] →→ │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ Trending this week (TMDB, opt-in, Electron-only) │
|
|
│ [poster][poster][poster] →→ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
Render rules:
|
|
|
|
1. Dashboard rails render independently as their data sources resolve. The
|
|
page no longer uses `dashboardReady()` as a page-wide skeleton gate.
|
|
Initial hero/recent/favorites loading states render scoped skeletons so one
|
|
slow rail does not hide already available content.
|
|
2. `hasPlaylists() === false` → render `<app-empty-state [type]="'welcome-dashboard'">`
|
|
full-bleed. All rails and the hero are skipped.
|
|
3. The hero (`lib-dashboard-hero`) renders when it has at least one slide;
|
|
see [Cinematic Hero](#cinematic-hero). It shows its own skeleton while
|
|
it has no slide and any of its sources (history, favorites, Xtream
|
|
recently added) is still on its first load, or a live candidate still
|
|
waits for its first programme answer (portal or XMLTV, for at most
|
|
`DASHBOARD_HERO_LIVE_ANSWER_WAIT_MS`, 2 s, from the hero's creation).
|
|
Dropping it earlier removed the hero and inserted it again when a later
|
|
source featured a title, moving every rail below twice. Once the
|
|
skeleton has gone it does not come back. An item enters recent history only after
|
|
its stream has really played (see "Recently Viewed Confirmation" in
|
|
`embedded-inline-playback.md`), so a channel that failed at once never
|
|
becomes a hero slide.
|
|
4. Each rail is emitted via `@if (cards.length > 0)`. Empty rails are hidden
|
|
— there is no "empty widget" placeholder.
|
|
5. Hero slides prefer a stored `backdrop_url`, then the TMDB backdrop; when
|
|
both are missing the poster becomes a blurred wash plus key art on the
|
|
right instead of a flat panel.
|
|
6. Live favorites are promoted into their own live rail; movie/series
|
|
favorites render in a separate `Favorite movies & series` rail
|
|
(`favoriteMoviesAndSeriesCards`, `data-test-id="dashboard-favorite-vod-rail"`,
|
|
mapped from `globalFavoriteItems()` filtered to movie/series). Full mixed
|
|
favorites management stays on `/workspace/global-favorites`.
|
|
7. The live favorites rail keeps its scoped skeleton until the initial global
|
|
favorites load has completed for both Xtream-backed and playlist-backed
|
|
favorites. This avoids first-paint partial counts such as a single Stalker
|
|
favorite appearing before M3U favorites finish resolving.
|
|
|
|
## Cinematic Hero
|
|
|
|
`DashboardHeroComponent` renders a full-bleed banner: it cancels the page's
|
|
`--dashboard-gutter`/top padding and the centred `--dashboard-max-width`
|
|
(the page host is the `dashboard` inline-size container), keeps
|
|
`clamp(320px, 42vh, 520px)` so the first rail starts above the fold, and uses
|
|
`--app-content-bg` as its scrim so it dissolves into the page in both themes.
|
|
|
|
Slides (`pickDashboardHeroSources`, at most four, stable order, each title
|
|
once):
|
|
|
|
1. the newest unfinished movie/series (`isPortalPlaybackWatched` rows skip);
|
|
2. a live channel with a programme on air — the first of
|
|
`selectDashboardHeroLiveCandidates` (up to three favourites, then two
|
|
recently watched channels) whose EPG answer has a title;
|
|
3. one favourite movie/series and one Xtream recently-added title;
|
|
4. remaining places round-robin over the next items of those lists;
|
|
5. only when nothing qualifies, the newest history row of any kind (a
|
|
detail action: it can be a finished title).
|
|
|
|
While live candidates exist but none has answered yet, one place stays
|
|
reserved for the live slide, so its late arrival never evicts a slide the
|
|
user may be viewing.
|
|
|
|
The live candidates are derived and pinned by `DashboardLiveEpgPresenter`
|
|
itself (XMLTV lookup and portal queue), independent of the live rails, so the
|
|
slide works with those rails hidden. Actions: a resume slide keeps the resume
|
|
handoff and adds a detail-only "Details" when a series episode can resume;
|
|
discovery slides open the detail page; live slides open the channel. TMDB
|
|
extras (backdrop, rating, genres, overview, year) come from
|
|
`DashboardHeroTmdbService` per featured title and vanish when TMDB is off.
|
|
|
|
Artwork: a title's backdrop, else its poster blurred and scaled past the
|
|
edges (no second, sharp copy); a live channel's logo sits on the right as key
|
|
art over its own wash. Series titles drop their season marker
|
|
(`splitSeasonSuffix`) — the `S1·E1` chip names the season. Chips are
|
|
`app-meta-chip`; the primary is the details pages' light primary
|
|
(`light-primary-button` from `libs/ui/styles`). With no artwork at all the
|
|
stage is a gradient in the title's hue (`--hero-hue`), light in the light
|
|
theme and near-black in the dark one; a dark gradient under the light
|
|
theme's page-coloured scrim read as a grey slab behind dark text.
|
|
|
|
Legibility: slide text stays at 4.5:1 or more over any artwork. The side
|
|
scrim holds 88% of the page colour up to the slide's right edge
|
|
(`--hero-text-edge`: the inset plus `min(560px, 55%)`, the slide's own
|
|
`max-width`) before it opens onto the art. In the narrow layout (`dashboard`
|
|
container ≤ 720px) the slide spans the width, so a full-bleed scrim sits
|
|
behind the text block (90%, fading in just above the eyebrow), the copy gets
|
|
a scrim-coloured text shadow, and the slide enters without a fade so that
|
|
scrim never flashes the art on a rotation. Body text is 85% of the heading
|
|
colour; the rating chip uses `--app-rating-color`, set per theme in
|
|
`m3-theme.scss`. Buttons end long labels in an ellipsis.
|
|
`dashboard-hero-legibility.e2e.ts` replaces every image with a black-and-white
|
|
checkerboard and measures each piece of slide text from the screen in both
|
|
themes, at a wide and a narrow width, for a backdrop, a blurred-poster, a
|
|
no-artwork and a live slide.
|
|
|
|
Semantics: the page has one stable, visually hidden `h1` ("Dashboard",
|
|
`dashboard-page-heading`); each slide title is an `h2`, like the rail titles.
|
|
Slide changes are announced by one polite live region
|
|
(`dashboard-hero-announcement`, position and title) that lives outside the
|
|
re-created slide and is silent while the slides rotate on their own. A
|
|
slide's progress bar is named after its title (a live slide: the programme)
|
|
and a title's reads "N% watched". The dots are 24px targets (WCAG 2.5.8).
|
|
|
|
Rotation is the active dot's CSS fill animation (8 s); its `animationend`
|
|
advances. The fill animates `transform` only (a bar sliding in under the
|
|
pill's rounded clip), so it runs on the compositor; animating `width` there
|
|
cost a style, layout and paint pass on every frame of an idle dashboard.
|
|
Hover, focus inside the hero, a hidden document and the pause button pause
|
|
it; an explicit Play clears the hover/focus pause until they re-arm; under
|
|
`prefers-reduced-motion` nothing auto-advances. The hero is a focusable
|
|
region: ←/→ switch slides and Enter follows the primary action. The active slide is tracked
|
|
by id, so a late live slide never moves the user off the current one. Test
|
|
hooks: `dashboard-hero`, `dashboard-hero-slide` (`data-hero-kind`),
|
|
`dashboard-hero-dot`, `dashboard-hero-pause`,
|
|
`dashboard-hero-primary-action`, `dashboard-hero-secondary-action`.
|
|
`dashboard-hero-rotation.e2e.ts` drives the real fill animation (with a
|
|
shortened `--hero-rotation-ms`) to prove its `animationend` still advances
|
|
and that pause holds the slide.
|
|
|
|
## Rail Contract
|
|
|
|
`DashboardRailComponent` is purely presentational:
|
|
|
|
1. Inputs: `label`, `items: DashboardRailCard[]`, optional `seeAllLink`,
|
|
optional `aspectRatio` (default `'2 / 3'`), optional `testId`.
|
|
2. Behavior: horizontal flex track with `scroll-snap-type: x mandatory`.
|
|
The track scrolls back to the start and re-observes its cards only when
|
|
the ids or order of `items` change. Hosts rebuild card objects on every
|
|
clock tick (live progress, expiry badges), and such a rebuild must not
|
|
move a rail the user scrolled.
|
|
3. Chevron buttons fade in on hover (desktop only via `@media (hover: none)`).
|
|
Edge fades follow the chevrons' visibility. The track bleeds
|
|
`--rail-bleed` past the viewport on every side so card focus rings and
|
|
hover lift are not clipped; the fades are offset by the same variable so
|
|
they reach the track's clipping edge and no card strip shows beyond them.
|
|
4. Cards are keyboard-focusable router links; `scroll-snap-align: start`
|
|
means arrow-key nav lands on card boundaries. A card that receives
|
|
keyboard or script focus scrolls fully into the viewport: Chromium skips
|
|
its own focus scroll once 32px of an element shows, so the track's
|
|
`focusin` handler moves to the first card-start snap position revealing
|
|
the whole card (a card wider than the viewport aligns at its own start).
|
|
Focus caused by a press inside the track (within 100ms of `pointerdown`,
|
|
650ms for touch) leaves the rail still, so the card does not slide from
|
|
under the pointer before the click.
|
|
5. Image handling: `loading="lazy"`, `decoding="async"`, fallback icon tile
|
|
when `imageUrl` is missing or `error` fires.
|
|
6. Dashboard hero, rail containers, rail viewports and tracks, rail cards and
|
|
their links, and "Manage all" links expose stable `data-test-id` hooks. Treat these as the supported Electron E2E
|
|
selector surface; do not target internal CSS class names.
|
|
|
|
## Data Flow
|
|
|
|
1. `WorkspaceDashboardRailsComponent` injects `DashboardDataService`.
|
|
2. It derives the dashboard surface via `computed()`:
|
|
1. The hero slides — built by `DashboardHeroSlidesPresenter`, see
|
|
[Cinematic Hero](#cinematic-hero).
|
|
2. `continueWatchingCards` — maps `globalRecentVodItems()` to movie/series
|
|
cover cards. Portal playback positions are bulk-loaded per playlist so
|
|
hero and cards can show progress, remaining time, and series season/
|
|
episode badges. Whether an item is looked up as a movie (one `vod`
|
|
row) or a series (episode rows under the parent id) is its WATCH
|
|
kind, `resolvePortalActivityWatchKind`, not its routing `type`. The
|
|
shape that needs the distinction is a Stalker embedded-VOD row: its
|
|
stored entry carries a `series[]` episode array but no `is_series`
|
|
flag, so `extractStalkerItemType` reports `movie` (deliberately — the
|
|
item belongs in the VOD catalog) while its progress lives in episode
|
|
rows. The mappers give both it and a lazy Ministra `is_series` row
|
|
(already typed `series`) `watch_kind: 'series'`. Series lookup uses
|
|
keyed maps for both direct episode ids and parent series ids; card
|
|
renders must not scan the full playback-position map. The badge uses saved `seasonNumber` /
|
|
`episodeNumber` metadata and does not infer it from provider payloads;
|
|
legacy rows without that metadata remain badge-less until replay.
|
|
Dashboard-originated Xtream and Stalker series clicks also carry that
|
|
exact episode target through the global-recent inline-detail handoff.
|
|
Once the series metadata and playback positions load, the detail player
|
|
consumes the target once and resumes the saved episode. Opening the same
|
|
item normally from the global recent grid remains a detail-only action.
|
|
Continue Watching cards carry no provider/content-kind subtitle: their
|
|
meta row is the S·E chip plus a "N min left" label (`remainingLabel`,
|
|
from `formatRemainingLabel`), and the row is not rendered when both are
|
|
absent. The hero subtitle is the source name alone, through
|
|
`playlistDisplayLabel`.
|
|
3. `liveFavoriteCardsEnriched` and `recentLiveCardsEnriched` — two
|
|
independent rails (`dashboard-live-favorites-rail` and
|
|
`dashboard-recent-live-rail`); there is no fallback from one to the
|
|
other. M3U cards carry an `epg_lookup_key` using the app-wide XMLTV
|
|
fallback order (`tvg-id` -> `tvg-name` -> channel name); EPG enrichment
|
|
must use that key before falling back to the card title. Both rails are
|
|
enriched by `DashboardLiveEpgPresenter`, the one component-provided
|
|
facade for live EPG: it owns the XMLTV lookup described under "Scoped
|
|
lookups" in `m3u-playlist-module.md`, forwards everything portal-shaped
|
|
to `DashboardPortalLiveEpgPresenter`, and `enrich()` returns the cards
|
|
with their "now on air" row filled in.
|
|
One component-provided `DashboardLiveEpgClock` drives every live
|
|
refresh and progress bar on the page. It ticks every 30 s only while
|
|
the XMLTV lookup has cards or the portal presenter wants one, and
|
|
only while the document is visible; it reads the clock at once when
|
|
it starts again. A tick re-reads progress for every live card. It
|
|
re-asks an XMLTV scope only after one of its programmes has ended,
|
|
while a key has no programme, or once the answer is five minutes old
|
|
(`LIVE_EPG_MAX_ANSWER_AGE_MS`), because a guide refreshed elsewhere
|
|
can correct a programme still on air. A guide import or source change
|
|
(`EpgService.epgAvailable$`) re-asks at once. An unchanged answer is
|
|
not re-emitted.
|
|
Xtream and Stalker cards have no XMLTV key of their own; their "now on
|
|
air" line comes from the portal, **lazily and per card**:
|
|
- `buildDashboardPortalLiveEpgEntry` (dashboard data-access) turns a
|
|
live `PortalActivityItem` into the `UnifiedCollectionItem` the
|
|
collection pages hand `StreamResolverService.loadEpgForItems`, keyed
|
|
by the collection uid — favourites and recent rows of one channel
|
|
share the answer. Radio rows and rows without a usable provider id
|
|
get no entry. Cards carry that key as `liveEpgSourceKey`.
|
|
- `lib-dashboard-rail` reports the cards inside its track viewport
|
|
(plus ~one card of `rootMargin`) through `visibleCardsChanged`, from
|
|
an `IntersectionObserver` rooted at the track; without the API every
|
|
card counts as visible. Cards that leave the list are reported gone
|
|
at once.
|
|
- `DashboardPortalLiveEpgPresenter` (component-provided) unions the
|
|
visible keys of both rails with the pinned hero keys and calls
|
|
`DashboardPortalLiveEpgService.sync()` with exactly those entries —
|
|
on every change, on each tick of the shared live-EPG clock, and on
|
|
a display-offset change.
|
|
It is reached through `DashboardLiveEpgPresenter`, which derives the
|
|
portal rows itself from the enabled rails and pins the hero's live
|
|
candidates, so the page component only forwards what a rail can see. The queue lives in
|
|
the root service, so leaving the dashboard hands the wanted set back
|
|
(`sync([])` on destroy); otherwise the queue would keep asking for
|
|
cards on a page that is gone.
|
|
- `DashboardPortalLiveEpgService` (root) owns the queue: at most two
|
|
requests in flight, 200 ms between starts (the numbers
|
|
`EpgQueueService` proved against real panels), one card per request,
|
|
each answer published the moment it lands in `programs`, so the page
|
|
never waits and a slow portal delays no other card. Only wanted keys
|
|
are dequeued, so a card scrolled past before its turn is never
|
|
requested. A programme lives 60 s; a programme that ended is asked
|
|
again, but not within 30 s of the last answer (a portal may keep
|
|
returning the stale row). An answer with **no** programme lives only
|
|
30 s, because the resolver reports a failed portal and a guide-less
|
|
channel identically (it files per-channel failures as `null`), so
|
|
there is no failure cooldown to keep and the short TTL is what lets
|
|
an outage recover on the next tick.
|
|
- Every answer is "at the provider clock" and against one XMLTV source
|
|
set. A request captures both the display offset and
|
|
`EpgSourceSettingsService.revision()` — the same fence
|
|
`EpgService.guard()` uses — and a completion whose either fact moved
|
|
is discarded and requeued instead of published. That requeue has to
|
|
happen in the completion: while the key is in flight the retire pass
|
|
cannot queue a replacement, and without it the pre-change answer
|
|
would be trusted for a full TTL (the repo's late-result
|
|
invalidation contract).
|
|
- Desktop only in practice: the shared collection resolver is gated on
|
|
the local XMLTV bridge (`supportsProgramLookup`) and answers nothing
|
|
without it, so `sync()` returns immediately in the PWA rather than
|
|
filing an empty answer for every card. Lifting that gate for portal
|
|
lookups would change the collection pages too and is deliberately
|
|
out of scope here.
|
|
- `DashboardLiveEpgPresenter.enrich()` prefers the portal answer, falls
|
|
back to the XMLTV title match when the portal said "nothing on air",
|
|
and marks a card
|
|
`nowPlayingState: 'pending'` only before its FIRST answer — the
|
|
channel layout then shows a shimmer placeholder in the programme
|
|
slot; a refresh keeps the previous answer on screen.
|
|
4. `xtreamRecentlyAddedCards` — maps `xtreamRecentlyAddedItems()` to rail
|
|
cards. Aggregates newly added VOD and series across *all* Xtream
|
|
playlists via `DashboardDataService.reloadXtreamRecentlyAddedItems()`,
|
|
which calls `getGlobalRecentlyAdded('all', limit, 'xtream')` with the
|
|
DB-level `playlists.type = 'xtream'` filter. The rail is Electron-only
|
|
(PWA returns `[]`) and auto-hides when empty, so users without Xtream
|
|
playlists never see it. Cards carry the source name as their subtitle
|
|
(`playlistDisplayLabel`) so users can tell where each item was added;
|
|
the content kind is not repeated on every card. Driven by an
|
|
effect that re-runs whenever the Xtream playlist count changes, but the
|
|
first run waits for `globalFavoritesLoaded()` so the slower
|
|
recently-added DB query does not block the live favorites rail on
|
|
startup.
|
|
5. `recommendationCards` / `trendingCards` — the two TMDB rails. Both
|
|
need the TMDB opt-in AND the Electron DB worker that answers
|
|
`DB_MATCH_TITLES` (each is hidden in the PWA), and both load after
|
|
`globalFavoritesLoaded()` so the batched title match never competes
|
|
for the worker at startup. `recommendationCards` is seeded from
|
|
recently watched movies/series and only shows titles present in an
|
|
imported library, hiding itself below five matched cards; its rail
|
|
label names the seed ("Because you watched X") when exactly one
|
|
seed contributed. `trendingCards` shows TMDB's weekly trending and
|
|
falls back to a prefilled global search for unmatched titles.
|
|
Contracts: `docs/architecture/tmdb-metadata-enrichment.md`
|
|
("Dashboard Integration").
|
|
6. `sourceCards` — maps `recentPlaylists()` to rail cards. `recentPlaylists()`
|
|
ranks M3U, Xtream, and Stalker sources by their latest recent activity
|
|
from `globalRecentItems()`, then falls back to playlist
|
|
`updateDate` / `importDate` for sources that have never been used.
|
|
3. `DashboardDataService` is passive on construction. The dashboard feature
|
|
owns the initial reloads for recent items, favorites, and Xtream recently
|
|
added rows on page entry.
|
|
4. No dashboard-local `Layout` state, no localStorage keys, no migrations.
|
|
Per-rail visibility is the one persisted preference, and it lives in the
|
|
global settings store (`Settings.dashboardRails`), not in a
|
|
dashboard-owned layout blob.
|
|
5. Navigation state + deep-link targets come from the existing
|
|
`getRecentItemLink()` / `getGlobalFavoriteLink()` / `getPlaylistLink()`
|
|
helpers on `DashboardDataService` and reuse the workspace navigation
|
|
helpers in `@iptvnator/portal/shared/util`.
|
|
6. Xtream VOD and series detail pages opportunistically backfill
|
|
`content.backdrop_url` when metadata exposes a backdrop, but that write
|
|
must not refresh recently viewed ordering by itself.
|
|
7. The dashboard feature triggers a fresh reload of DB-backed recent/favorite
|
|
rows on dashboard entry so newly backfilled backdrop data is visible as soon
|
|
as the user returns from a detail page.
|
|
8. Playback-position reloads are keyed by the VOD/series recent set and should
|
|
call `reloadPlaybackPositions()` through `untracked()` so live-only recent
|
|
changes do not trigger unnecessary IPC round-trips.
|
|
9. Electron M3U dashboard favorites should use
|
|
`PlaylistsService.getM3uFavoriteChannels()` first. That method checks the
|
|
SQLite playlist migration flag and then calls
|
|
`dbGetAppPlaylistFavoriteChannels(playlistId)`, letting the DB worker return
|
|
only matched favorite channels instead of sending the full playlist payload
|
|
back to the renderer. If the bridge method is missing or migration is
|
|
incomplete, the dashboard falls back to the full playlist read.
|
|
10. Electron playlist summary loads should use
|
|
`dbGetAppPlaylistMetas()` through `PlaylistsService.getAllPlaylists()`.
|
|
This keeps dashboard/source/sidebar startup on a metadata-only SQLite path
|
|
and avoids parsing full M3U `payload` blobs for surfaces that only need
|
|
playlist title, type, counts, favorites, recent activity, and source
|
|
connection fields. Workflows that need channel payloads still call
|
|
`getPlaylistById()`.
|
|
|
|
## Empty State
|
|
|
|
The welcome state is rendered via the existing
|
|
`EmptyStateComponent` (`type="welcome-dashboard"`) from
|
|
`libs/playlist/shared/ui`:
|
|
|
|
1. Illustration + headline + description from the existing M3U welcome
|
|
strings (`HOME.PLAYLISTS.WELCOME_*`).
|
|
2. Primary button emits `addPlaylistClicked`. The dashboard page wires this
|
|
to `WORKSPACE_SHELL_ACTIONS.openAddPlaylistDialog()`.
|
|
3. Feature chips (M3U / Xtream / Stalker) are provided by the component.
|
|
|
|
## UX Rules
|
|
|
|
1. Rails represent content the user is likely to resume, not provider
|
|
internals. Never surface raw API objects.
|
|
2. Each rail must auto-hide when its data source is empty.
|
|
3. Image assets must degrade to a typed icon fallback — never show broken
|
|
images or empty tiles.
|
|
4. The page must never show "No widgets" style text. If there is no content
|
|
and no playlists, render the welcome state; otherwise render whatever
|
|
rails have data.
|
|
5. Navigation from a rail card must deep-link into the appropriate workspace
|
|
route without switching the active playlist in the header switcher.
|
|
6. Xtream and Stalker series hero/Continue Watching clicks with a saved episode
|
|
position must resume that exact episode while preserving the
|
|
collection-owned detail and Back behavior. Do not apply autoplay to
|
|
ordinary collection-grid clicks.
|
|
7. `Recently Used Sources` reflects recent source usage across all provider
|
|
types, not just recent imports.
|
|
8. The live rail title key must match the rendered source: favorites use
|
|
`WORKSPACE.DASHBOARD.LIVE_FAVORITES`; the recently-watched-live rail uses
|
|
`WORKSPACE.DASHBOARD.RECENTLY_WATCHED_LIVE_TV`
|
|
(`liveRailTitleKeyForSource` in `rails/dashboard-rail.utils.ts`).
|
|
|
|
## Adding Or Changing Rails
|
|
|
|
Current workflow:
|
|
|
|
1. Add a new `computed()` signal for the card list in
|
|
`WorkspaceDashboardRailsComponent`, mapping your source data to
|
|
`DashboardRailCard`.
|
|
2. Drop a `<lib-dashboard-rail>` in the template, gated by
|
|
`@if (cards.length > 0)`.
|
|
3. If the data source is new, extend `DashboardDataService` rather than
|
|
reaching into DB services directly from the component.
|
|
4. Provide a `seeAllLink` only if there is a dedicated "manage all" route
|
|
for that content type.
|
|
|
|
## Deferred Work
|
|
|
|
Intentionally out of scope:
|
|
|
|
1. Customizable layout (drag/drop, resize, freeform reordering). The rail
|
|
order stays curated and opinionated. (Per-rail show/hide toggles have
|
|
since shipped via `Settings.dashboardRails` — see Summary.)
|
|
2. Freeform widget grid with collision management.
|
|
3. External data rails such as RSS, sports, or news adapters.
|
|
4. Per-user A/B variants of rail ordering.
|
|
|
|
## Source subscription expiry
|
|
|
|
Source cards show a passive subscription-expiry chip: amber within seven days,
|
|
error-toned once expired. Account details stay behind the Account info menu.
|
|
`DashboardSourceExpiryService` in `libs/workspace/dashboard/data-access` reads
|
|
Xtream expiry from cached `PortalStatusService.checkPortalStatusDetails()`
|
|
(`exp_date`). Stalker uses the persisted `stalkerAccountInfo` snapshot from the
|
|
playlist payload, not the metadata row; each source therefore needs one memoized
|
|
full-playlist read. The chip is not a separate account-refresh request.
|
|
The badge only changes at day boundaries, so the rails do not poll the clock:
|
|
`createSourceExpiryClock` arms one timer for the earliest boundary among the
|
|
known facts (`nextSourceExpiryChangeMs`), capped at an hour because timers do
|
|
not follow system sleep. It arms no timer while the page is hidden or the
|
|
sources rail is disabled, and re-reads the clock when the page becomes visible. It schedules from the real
|
|
time, so facts that arrive long after the last tick are not scheduled late.
|
|
Facts whose badge can no longer change arm no timer.
|