Skip to content

armgit / peach

Public Imported from GitHub
0

Peach: Local-first video metadata scraper and media manager.

13.0 KB
Raw Blame
/* 客户端导航(ADR-0031「React Router 外壳阶段接管」):React Router 的 Declarative 模式接管 history。
 * 管理区那几页、播放列表页与关注页、索引页与资料页、目录网格与垃圾队列,以及页面里的页面内组件(首页筛选条、
 * 首页新作行、顶栏搜索下拉)与常驻组件(后台任务、底部批量条、侧栏配色卡、管理区页头、沉浸模式、设置面板、
 * 侧栏、详情舞台)(`managed-routes.tsx`)由这棵树画。每一页、沉浸模式与详情覆盖都由路由按匹配打开
 * (`pages/` 下各元素),壳不接派发:它只订阅历史同步标题与侧栏,换页时写地址。
 *
 * 用底层的 `<Router>`,history 是 `@peach/history` 那一份:应用启动时就要写地址,`<BrowserRouter>`
 * 自己建的 history 只听 `popstate`,看不见壳 push 进去的条目。也不用 `unstable_HistoryRouter`:它的更新
 * 默认包在 `startTransition` 里,接连两次变化会并成一次渲染,后退前进就少开一次。
 *
 * 页面宿主是两组 `<Routes>` 的兄弟,从头活到尾:画着的页面跟着登记的那几条走(`@peach/history` 的
 * `openManagedRoute`,每个容器一条),详情舞台压在上面、地址换成 `/assets/:id` 时它留在原处。
 *
 * 路由分两组:页面组按条目自己记的背景(`usr.backgroundLocation`,启动那一条不读)匹配,详情压在哪一页上就还
 * 匹配那一页,背景页不重挂;覆盖组按真实地址匹配详情与队列那几条(`OVERLAY_PATHS`,`pages/overlay.tsx`)。页面组
 * 里管理区、关注、索引、资料、目录与沉浸各挂按地址打开那一页的元素(`pages/managed.tsx`、`pages/follow.tsx`、
 * `pages/index-entity.tsx`、`pages/catalog.tsx`、`pages/immerse.tsx`);没有背景的覆盖地址也在页面组里挂一格:
 * 作品与队列补画目录网格,关注详情只让出 `#stats`。`path="*"` 是认不出的地址,什么都不打开。
 *
 * 一处渲染错误只带走抛错的那一面:每一面各套一层错误边界(`SurfaceBoundary`),根上不套,两组 `<Routes>` 不随
 * 某一面卸掉。错误经根的 `onCaughtError` 交给 `reportError`,每次一条。 */
import {
  Component, createContext, memo, useContext, useLayoutEffect, useMemo, useRef, useState, type ReactNode,
  type RefObject,
} from 'react';
import { createPortal, flushSync } from 'react-dom';
import type { RootOptions } from 'react-dom/client';
import { Route, Router, Routes, useLocation, useNavigate, type NavigateFunction } from 'react-router';

import {
  failManagedRoute, listenManagedEntry, managedEntries, navigationBackground, OVERLAY_PATHS, peachHistory,
  PREFERENCE_PATHS, isPreferencePath, settingsBackgroundOf, bootEntry,
  type ManagedEntry, type Navigation,
} from '@peach/history';

import { Providers } from '../providers';
import { LibraryProcessingDock } from '../library-processing/library-processing-dock';
import { NetworkBanner } from '../network-banner';
import { TutorialCenter } from '../onboarding/tutorial-center';
import { ClientUpdateBanner } from '../client-updates';
import { SettingsMatch } from './pages/settings';
import { CatalogChrome } from './pages/catalog';
import {
  BROWSE_ROUTES, CATALOG_PATHS, CATALOG_ROUTES, ENTITY_ROUTES, IMMERSE_ROUTES, INDEX_ROUTES, MANAGED_ROUTES, REDIRECT_ROUTES,
  isManagedPath, isRoutedPath, managedPage,
} from './managed-routes';
import { FollowDetailGround, OverlayMatch, QueueRequests } from './pages/overlay';
import type { ShellActions } from './shell-actions';

/* 页面打开序号(`@peach/history` 的 `openEpoch`):没人认领的历史变化各领一个,认领的写地址不领。地址没变的
 * `popstate`(同一条目重放)不会让 Router 的 location 变,代次照样变,按它挂 key 的元素照样重开。 */
const OpenEpoch = createContext(0);

/** 当前这一页是第几次打开:页面元素按它挂 key,重开就重挂,认领的写地址(页内 replace 写参数)不重挂。 */
export const useOpenEpoch = (): number => useContext(OpenEpoch);

/** 壳交进来的能力,管理区那几页经它回到壳。 */
export const ShellActionsContext = createContext<ShellActions | null>(null);

/** 路由根在历史变化的同一调用里同步提交(`flushSync`):`shellNavigate` 与后退前进返回时,两组 `<Routes>`
 *  的匹配已经换成新地址,上一页的元素已经卸掉,壳接着往同一个容器里写骨架不会撕掉 React 还管着的节点。
 *  元素的打开不在这一次提交里跑,各自排进提交之后的微任务。 */
export function PeachRouter({ children }: { children: ReactNode }) {
  const [navigation, setNavigation] = useState<Navigation>(() => peachHistory.navigation);
  useLayoutEffect(() => {
    /* 从读初值到这里订阅之间有过变化的话,补上最新那一次。 */
    setNavigation(peachHistory.navigation);
    return peachHistory.listen((next) => { flushSync(() => setNavigation(next)) });
  }, []);
  return (
    <OpenEpoch.Provider value={navigation.openEpoch}>
      <Router location={navigation.location} navigationType={navigation.action} navigator={peachHistory}>
        {children}
      </Router>
    </OpenEpoch.Provider>
  );
}

/* 跟着地址重渲染的只有这一格:它把当前的 `navigate` 交给管理区宿主,宿主与页面不随导航重渲染。 */
function NavigateInto({ target }: { target: RefObject<NavigateFunction | null> }) {
  const navigate = useNavigate();
  useLayoutEffect(() => { target.current = navigate });
  return null;
}

/** 管理区页面里的跳转:落在管理区那几页上的交给 React Router,别的路径交 `actions.navigate`。两条路都不认领,
 * 各领一个页面打开序号,打开次数与后退前进相同。 */
export function managedGo(path: string, actions: ShellActions, navigate: NavigateFunction): void {
  const target = new URL(path, window.location.href);
  if (!isManagedPath(target.pathname)) { actions.navigate(path); return }
  void navigate(`${target.pathname}${target.search}${target.hash}`);
}

/** 页面宿主:画壳在各个容器里登记的那一页(`#stats`、`#index`、`#grid` 与各页面内组件的容器各一页,互不相收)。
 *
 * 换页与收起都由 `@peach/history` 同步通知,这里用 `flushSync` 当场画完:壳在同一个任务里刚换上宿主
 * (或刚撤掉它),晚一拍画就是一帧空白。每次打开领一个代次,页面按代次重挂,首屏读的是刚取回的缓存。
 * 就地更新(`updateManagedRoute`)只换那一页的 props、代次不变,照常排进下一次渲染:壳的开关可能就是从
 * 页面自己的 effect 里推过来的,那里不能 `flushSync`。 */
function ManagedSurface() {
  const actions = useContext(ShellActionsContext);
  const [entries, setEntries] = useState<readonly ManagedEntry[]>(managedEntries);
  const navigate = useRef<NavigateFunction | null>(null);
  useLayoutEffect(() => {
    setEntries(managedEntries());
    return listenManagedEntry((next, sync) => {
      if (sync) flushSync(() => setEntries(next));
      else setEntries(next);
    });
  }, []);
  const go = useMemo(() => (path: string) => {
    if (actions && navigate.current) managedGo(path, actions, navigate.current);
  }, [actions]);
  return (
    <>
      <NavigateInto target={navigate} />
      {actions ? entries.map((entry) => (
        <SurfaceBoundary key={entry.revision} entry={entry}>
          <ManagedPortal entry={entry} actions={actions} go={go} />
        </SurfaceBoundary>)) : null}
    </>
  );
}

/** 一面一层的错误边界。接住之后这一面画成空,并撤掉它的登记与宿主(`failManagedRoute`),壳下次打开时重开;
 *  按代次挂 key,重开就是一个新的边界实例。上报不在这里:根的 `onCaughtError` 已经报过一次。 */
class SurfaceBoundary extends Component<{ entry: ManagedEntry; children: ReactNode }, { failed: boolean }> {
  override state = { failed: false };

  static getDerivedStateFromError(): { failed: boolean } {
    return { failed: true };
  }

  override componentDidCatch(): void {
    failManagedRoute(this.props.entry.container, this.props.entry.revision);
  }

  override render(): ReactNode {
    return this.state.failed ? null : this.props.children;
  }
}

const ManagedPortal = memo(function ManagedPortal(
  { entry, actions, go }: { entry: ManagedEntry; actions: ShellActions; go: (path: string) => void },
) {
  if (!isRoutedPath(entry.path)) return null;
  return createPortal(managedPage(entry.path, entry.props, actions, go), entry.host, String(entry.revision));
});

/* 页面组的 `location` 一直给(没有背景就给当前地址):给与不给之间 `<Routes>` 会多包一层 `LocationContext`,
 * 来回切换就会把页面元素拆掉重挂。背景读的是当前条目(`navigationBackground`),启动那一条当作没有。
 * 两组按页面分段,段与段之间隔开几行。 */
function RouteGroups({ children }: { children?: ReactNode }) {
  const location = useLocation();
  // 同一条目重放时地址不变、`useLocation` 不触发重渲染,代次照样变:启动那一条重放之后要开始读背景。
  useOpenEpoch();
  const background = navigationBackground();
  const settingsBackground = isPreferencePath(location.pathname) && !bootEntry() ? settingsBackgroundOf(location.state) : null;
  return (
    <>
      <Routes location={background ?? location}>
        {/* ── 管理区 ── */}
        {Object.entries(MANAGED_ROUTES).map(([path, route]) => <Route key={path} path={path} element={route.element} />)}
        {/* 资源同步的旧直达地址转到数据管理下的二级页。 */}
        {Object.entries(REDIRECT_ROUTES).map(([path, route]) => <Route key={path} path={path} element={route.element} />)}



        {/* ── 关注 ── */}
        {Object.entries(BROWSE_ROUTES).map(([path, route]) => <Route key={path} path={path} element={route.element} />)}



        {/* ── 索引 ── */}
        {Object.entries(INDEX_ROUTES).map(([path, route]) => <Route key={path} path={path} element={route.element} />)}



        {/* ── 资料 ── */}
        {Object.entries(ENTITY_ROUTES).map(([path, route]) => <Route key={path} path={path} element={route.element} />)}



        {/* ── 目录 ── 六条路径挂同一个元素(`pages/catalog.tsx`),换路径不重挂,元素按页面自己分 key。 */}
        {CATALOG_PATHS.map((path) => <Route key={path} path={path} element={CATALOG_ROUTES['/'].element} />)}



        {/* ── 沉浸 ── */}
        {Object.entries(IMMERSE_ROUTES).map(([path, route]) => <Route key={path} path={path} element={route.element} />)}



        {/* ── 没有背景的覆盖地址 ── 作品与队列挂目录元素,补画网格;关注详情只让出 `#stats`。 */}
        {OVERLAY_PATHS.map((path) => (
          <Route key={path} path={path} element={path === '/works/:code' ? null
            : path === '/posts/:id' ? <FollowDetailGround /> : CATALOG_ROUTES['/'].element} />
        ))}
        {PREFERENCE_PATHS.map(path => <Route key={path} path={path} element={null} />)}



        {/* 认不出的地址。`children` 只给测试用。 */}
        <Route path="*" element={children} />
      </Routes>



      {/* ── 覆盖 ── */}
      <Routes location={settingsBackground ?? location}>
        {OVERLAY_PATHS.map((path) => <Route key={path} path={path} element={<OverlayMatch path={path} />} />)}
        <Route path="*" element={null} />
      </Routes>
      <Routes>
        {PREFERENCE_PATHS.map(path => <Route key={path} path={path} element={<SettingsMatch />} />)}
        <Route path="*" element={null} />
      </Routes>
    </>
  );
}

/** 整棵路由树。`children` 画在页面组 `path="*"` 的元素里面,只给测试用:跟着它挂一次就说明元素没被重挂。 */
export function RouterRoot({ children, actions = null, background, processing = false }:
  { children?: ReactNode; actions?: ShellActions | null; background?: ReactNode; processing?: boolean }) {
  return (
    <Providers>
      {background}
      <ShellActionsContext.Provider value={actions}>
        <PeachRouter>
          <ManagedSurface />
          <CatalogChrome />
          <QueueRequests />
          {processing && actions ? <LibraryProcessingDock toast={actions.toast} /> : null}
          {processing && actions ? <NetworkBanner /> : null}
          {processing && actions ? <ClientUpdateBanner navigate={actions.navigate} /> : null}
          {processing && actions ? <TutorialCenter actions={actions} /> : null}
          <RouteGroups>{children}</RouteGroups>
        </PeachRouter>
      </ShellActionsContext.Provider>
    </Providers>
  );
}

/** 路由树那棵根的选项。错误边界接住的错误交给全局 `reportError`,和没人接住时 React 的上报同一条路,
 *  控制台与 window 的 `error` 事件各见一次。运行时才取 `reportError`:测试环境里可能没有它。 */
export const ROUTER_ROOT_OPTIONS: RootOptions = {
  onCaughtError: (error) => { globalThis.reportError?.(error) },
};