refactor(e10): move the platform components into components/ui/ and enforce the boundary

The app HAS a platform layer -- AnchoredPopover (22 importers, with arrows/typeahead/Escape/anchor-flip), QueryState (21), Modal (17), PageShell, DataTable, Tabs, Tooltip and ~26 more -- but it sat flat among ~160 feature components with nothing marking it as one. Several of those files describe themselves as 'the one place' or 'canonical' and were still bypassed by hand-rolled markup, because a layer nobody can see is a layer nobody uses; three separate inventory passes of this codebase misread it the same way. Moves the 33 domain-free modules into components/ui/, rewrites the imports in 89 files, and makes the boundary a lint rule rather than a convention: inside ui/ a one-level-up import (a feature component) and any lib/api slice are errors. The rule was verified to fire on both and to leave generic lib/ helpers alone. README.md states which side of the line a component belongs on and why. No behaviour change: 3x tsc, eslint, knip, prettier and 687 vitest tests all green; no backend file touched.
2026-09-05 16:58:29 +02:00
parent 31fa554b87
commit 5bfcf5d83a
138 changed files with 262 additions and 189 deletions
@@ -0,0 +1,44 @@
+# `components/ui/` — the platform layer
+
+Everything in this directory is a **platform component**: generic, reusable, and **domain-free**.
+Everything in `components/` above it is a **module component**: it knows about videos, channels,
+playlists, Plex or downloads.
+
+That boundary is the whole point of this directory. Before E10 S1 these 33 modules sat flat among
+~160 feature components, and the platform was invisible — several of them literally describe
+themselves as "the one place", "shared", "canonical", "app-wide", and were still routinely bypassed
+by a hand-rolled `<button>` or a re-implemented popover. A layer you cannot see is a layer nobody
+uses.
+
+## The rule
+
+A component belongs here **iff its props and imports name no domain concept**. It may import:
+
+- sibling primitives in this directory,
+- generic helpers from `lib/` (`layerStack`, `history`, `columnSort`, `useScrollFade`, …),
+- i18n, React, and third-party UI libraries.
+
+It may **not** import a feature component (`../Feed`) or a domain API slice (`lib/api/*`). This is
+enforced by `no-restricted-imports` in `eslint.config.js` — not by this README, which is only the
+explanation. If a primitive needs domain data, take it as a prop or a render-prop and let the module
+supply it.
+
+Counter-examples, deliberately NOT here: `PosterTile` (knows about Plex montage posters), `KeyGate`
+(secure-messaging key setup), `plexCards`, `downloadRow`, `channelColumns` — all shared, none
+domain-free.
+
+## What lives here
+
+| area                   | components                                                                                                                                            |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| overlays & anchoring   | `AnchoredPopover` (the popover engine: arrows, typeahead, Escape, anchor-flip), `ActionMenu`, `Modal`, `Overlay`, `SidePanel`, `Tooltip`, `Toaster`   |
+| actions & inputs       | `Button`, `form`, `DraftSaveBar`, `Combobox`, `FilterSelect`, `SegmentedToggle`, `SortControl`, `ColumnSortControl`, `PriorityStepper`, `UndoToolbar` |
+| data display           | `DataTable`, `tableHeader`, `Pager`, `VirtualGrid`, `readAhead`, `Carousel`, `Avatar`, `CountBadge`, `ItemCount`, `FilterChipGroup`                   |
+| page & panel structure | `PageShell`, `PageScroller`, `PanelGroup`, `PanelGroups`, `Tabs`, `BackToTop`                                                                         |
+| state & messaging      | `QueryState`, `Banner`, `InlineNotice`                                                                                                                |
+
+## Adding one
+
+Move a component in when a second module needs it and it is domain-free — not on speculation. Adding
+a variant to an existing primitive beats adding a primitive; a second component that paints the same
+thing differently is how the last inconsistency happened.