feat(nav): full bookmarkable URL model — retire minimalist-URL + Share-view (E4 S2)

The query string is now the source of truth for the current view, so every URL is
bookmarkable/shareable. Reverses the early minimalist-URL rule (user's call).

- urlState: urlWithParams (read-modify-write delta on the live query, each provider
  owns its keys) + clearParams (strip only transient auth params) replace the whole-
  query stripUrlParams; shareUrl deleted; filterParamUpdates helper.
- NavigationProvider: page + ?chan mirrored to the address bar (pushState URL arg;
  history.state mechanics untouched); loadInitialPage resolves deep links
  (?v->plex, ?pl->playlists, filter/?chan->feed, bare->stored landing).
- FeedFiltersProvider: feed filters mirrored to the URL, gated on page===feed.
- useHistorySubview: optional SubviewUrl mapping; PlexBrowse mirrors the sub-view to
  ?v=<kind>:<args> (show/season/info/person/playlist; grid+player stay ephemeral).
- PlaylistsProvider: selected playlist mirrored to ?pl on the Playlists page.
- App: the 5 stripUrlParams calls become targeted clearParams (link/oauth/admin/
  access/verify/reset); the share-link hydrate effect removed.
- Retire the "Share view" feature: Sidebar + SavedViewsWidget buttons + i18n keys.

Browser tab title stays the short module/channel name (document.title untouched) —
the query never leaks into it, per the user's request.

Gate green: typecheck, knip, eslint (0 err), prettier, 247 vitest (urlState.dom.test
+9). No browser-E2E yet (most visual sprint — flagged for the epic-end review).
This commit is contained in:
2026-08-19 04:47:36 +02:00
parent 48aa1a25f5
commit 8bfc01684f
14 changed files with 362 additions and 115 deletions
+30 -3
View File
@@ -10,15 +10,41 @@
//
// setPage() pushes a clean { sfPage } entry (dropping _sub/_ov), so each page starts at its root.
import { useEffect, useRef, useState } from "react";
import { urlWithParams } from "./urlState";
// --- Sub-views (value carried in history.state._sub) ---------------------------------------
export function useHistorySubview<T>(root: T): {
/** Optional address-bar mirroring for a sub-view, so a deep sub-view (e.g. a Plex show page) is
* bookmarkable. history.state._sub stays the source of truth for Back/Forward; this only adds the URL. */
export interface SubviewUrl<T> {
/** The query key this sub-view mirrors to (e.g. "v" for the Plex sub-view). */
key: string;
/** Serialize a sub-view to the param value, or null for views not mirrored (root / ephemeral ones). */
encode: (view: T) => string | null;
/** Parse a param value back to a sub-view, or null if it isn't a valid one. */
decode: (raw: string) => T | null;
}
export function useHistorySubview<T>(
root: T,
url?: SubviewUrl<T>,
): {
view: T;
open: (next: T) => void;
back: () => void;
} {
const [view, setView] = useState<T>(() => (window.history.state?._sub as T) ?? root);
const [view, setView] = useState<T>(() => {
// Reload of an in-app entry: history.state._sub. Fresh bookmark: decode the ?<key> param.
const fromState = window.history.state?._sub as T | undefined;
if (fromState != null) return fromState;
if (url) {
const raw = new URLSearchParams(window.location.search).get(url.key);
const decoded = raw != null ? url.decode(raw) : null;
if (decoded != null) return decoded;
}
return root;
});
useEffect(() => {
// Back/Forward restores the sub-view from history.state (the browser restores each entry's URL too).
const onPop = () => setView((window.history.state?._sub as T) ?? root);
window.addEventListener("popstate", onPop);
return () => window.removeEventListener("popstate", onPop);
@@ -28,7 +54,8 @@ export function useHistorySubview<T>(root: T): {
view,
open: (next: T) => {
setView(next);
window.history.pushState({ ...window.history.state, _sub: next }, "");
const href = url ? urlWithParams({ [url.key]: url.encode(next) }) : "";
window.history.pushState({ ...window.history.state, _sub: next }, "", href);
},
back: () => window.history.back(),
};