peter
b5d37ca142
Third and last slice of the E11 keyboard layer (S4c). S4a/S4b covered every card grid and rail; the table-shaped pages — the channel manager, a playlist, the download center — were still Tab-stop country: a channel row carries a priority stepper, four action buttons and a tag picker before the next row's name. - `ui/DataTable keyboardNav`: the rows are the items, Enter clicks the element a column marks `data-nav-open`. DataTable renders its rows twice (a table, and a card list below `md`); both register and `lib/listNav` now walks only lists on screen (`checkVisibility`), so `j` past the last row never carries on into the hidden copy. - `lib/listNav` leaves a key something before it already handled (`defaultPrevented`): during a keyboard drag a playlist row's grip moves the row with the arrows, and dnd-kit takes the key on the document before listNav's window listener. Without the guard ↓ moved the focus off the grip and dropped the drag. - `ui/NavGrid as="tbody"` for a table whose body is the list (the playlist, under dnd-kit's SortableContext). - Wired: Subscriptions and Discovery tables, the card layout (`ChannelLayoutGrid` → VirtualGrid `keyboardNav`), Hidden/Blocked cards (the ChannelLink name is a channel's open element); a playlist's rows (the title plays; the grip keeps Space/Enter); the download queue, library and shared lists (the play button opens, `IconBtn open`; a row without one opens nothing). - `listNav.wiring.contract.test`: `VirtualGrid` and `DataTable` must say `keyboardNav` like `Carousel`, `DownloadRow` is a card; the audit log's table is the one exemption (its rows open nothing), and an exemption that no longer matches a tag fails the test. Measured in Chrome: Channels table j → row, ring round the whole row; a row walked down keeps 12px above the viewport edge, walked up clears the sticky header by 35px; Enter opens the channel. Cards 3 columns: → 0→1, ↓ 1→4. Hidden and Discovery: j + Enter open the channel. Playlist: j + Enter plays, Escape returns focus to the row; a keyboard drag (Enter on the grip, ↓) moves the row with focus kept on the grip, and Escape cancels with the order unchanged. Downloads library: Enter plays a video row, does nothing on a plain file row.
7.1 KiB
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.
The direction is one-way from below, too: lib/ may not import from components/ — this directory
included, not even a type (same lint file). A contract both layers need lives in lib/: the Column
/ FilterMap shape and filterRows are lib/tableColumns, which tableHeader and DataTable import.
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, ContextMenu + useContextMenu (the SAME menu, opened by right-click / long-press / Shift+F10), Modal, Overlay, SidePanel, Tooltip, Toaster, CommandPalette, KeyboardHelp |
| actions & inputs | Button, form, DraftSaveBar, Combobox, FilterSelect, SegmentedToggle, SortControl, ColumnSortControl, PriorityStepper, UndoToolbar |
| data display | DataTable, tableHeader, Pager, VirtualGrid + gridColumns (the column/width maths, incl. the ultrawide maxCols cap), readAhead, Carousel, NavGrid (a plain grid, list or table body the keyboard walks — DataTable, VirtualGrid and Carousel take keyboardNav), Avatar, CountBadge, ItemCount, FilterChipGroup |
| page & panel structure | PageShell, PageScroller, PanelGroup, PanelGroups, Tabs, BackToTop |
| state & messaging | QueryState, Banner, InlineNotice |
The size contract (E10 S1c)
The app optimises for 1024x768 (tablet landscape) as the floor; below it we owe an honest message, above it correct rendering all the way up. That contract lives in these components, not in the ~160 call sites, because a rule repeated in 160 places is a rule that is already broken somewhere:
- Geometry is a ladder, not a free choice.
Button'sSIZESare the rungs, derived from what the app actually used. Pick a rung; do not hand-roll padding on a primitive. - Type, padding and box geometry are rem-derived, so the Settings text-size slider (
--font-scaleon the root font-size) scales boxes and padding with the label. Atext-[Npx]font size is an eslint error for exactly this reason. The deliberate exceptions are the layout-engine measurements —VirtualGrid'sminCol/colMaxWidthandgridColumns'GRID_GAP— which are compared against a container's own pixel width rather than sized against text. Two px box values are NOT deliberate and are worth converting when touched:Tooltip'smax-w-[240px](it does not widen with the slider while its text does, so the tooltip re-wraps at large text sizes) andform.tsx'sleft-[18px]toggle knob. - Minimum target: 2.75rem, on coarse pointers only (
.touch-target, index.css). A 32px icon button is fine with a mouse and not with a thumb, so the box grows where there is no precise pointer. It grows the real box rather than painting an invisible hit area: two expanded hit areas on neighbouring icon buttons would overlap, and an overlap fires the wrong button. linkis excluded from the minimum: it is text inside a sentence.
Controls outside this directory (chips, list rows, the player's overlay buttons) are not covered yet -- they are the next thing to bring under the contract, not evidence that there isn't one.
Keeping it honest
Two of this directory's promises are load-bearing enough that prose was not enough, so each has a test rather than a paragraph:
- the import boundary above →
lib/uiBoundary.contract.test.tsruns eslint over fixture imports. It exists because the first cut of that rule wrote its regexes in plain"..."literals, where\.collapses to the any-char.— it read like a boundary and let the two commonest violations through, with a green gate saying nothing (E10 review round 1). - the chip lanes' clip →
lib/chipLane.contract.test.tscounts measurers against lanes per file.
If you add a rule here, ask what would fail if it stopped being true — and if the answer is "nothing", write the test instead of the sentence.
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.