feat(e5): first-class combobox platform mode + universal Combobox (A11Y-1)

The E5 filter pickers were a hand-rolled floating-ui combobox (MultiSelectChips)
with no combobox ARIA, no arrow-nav, and options in a body-portal — keyboard/SR
users could not operate it, and the bare role=listbox/option wiring actively
misled screen readers (deep-review A11Y-1, CONFIRMED 3/3 medium). Rather than
one-off-hack the a11y, add combobox as a first-class mode of the AnchoredPopover
platform and rebuild the pickers on a reusable component.

Platform (AnchoredPopover):
- new mode "combobox": reuses the whole positioning core (offset/flip/shift/size/
  hide, isPositioned + transform-clobber flash guards, FloatingPortal + fullscreen
  re-parent, topmost-only Escape layer). Differs only in the focus model — no
  useClick (open is field-driven), useRole role="combobox" so Floating UI wires the
  full ARIA tree (input role=combobox + aria-expanded/controls/autocomplete/
  activedescendant, listbox surface, option ids), and useListNavigation virtual:true
  so ↑/↓ move an aria-activedescendant pointer while DOM focus STAYS on the input.
- PopoverSurface: combobox surfaces host the item registry but are NOT focus-trapped.
- PopoverItem: virtual mode carries a stable id (the activedescendant target), never
  takes roving DOM focus, keeps the input focused on click (mousedown preventDefault),
  and its checked/selected truth wins over getItemProps' single-select guess.

Component (Combobox.tsx, new): the universal react-select/Overseerr combi-input —
chips-in-field + typed search + checklist. Supports multi/single select, client OR
server (async) filtering, custom rows, the big-vocabulary render cap + refine footer,
and a selected-label cache so a server-narrowed single-select still names its chip.

Rollout: MultiSelectChips (genre/age-rating/studio) → Combobox; the CollectionPicker
"+Add" popover → a single-select async Combobox (also fixes its arrow-keys-eaten
story), unifying the two filter idioms. PlexSearchBox is a documented future consumer.

Gate green (tsc, vitest 351, eslint, prettier, knip). Browser E2E on localdev:
role=combobox confirmed on both pickers; ↑/↓ moves aria-activedescendant with focus
staying on the input; Enter + click select; multi-select chips accumulate; Backspace
removes the last chip; async collection server-search picks + closes. No backend change.
This commit is contained in:
2026-08-21 05:43:36 +02:00
parent 0c746f5bcd
commit 5316f48af2
6 changed files with 571 additions and 476 deletions
+47 -102
View File
@@ -1,20 +1,18 @@
import { useEffect, useRef, useState } from "react";
import { useState } from "react";
import { qk } from "../lib/queryKeys";
import { useTranslation } from "react-i18next";
import { plexLang } from "../i18n";
import { useQuery, useQueryClient } from "@tanstack/react-query";
import { Layers, ListMusic, Plus, Search, SlidersHorizontal, X } from "lucide-react";
import { PopoverItem, PopoverSurface, useAnchoredPopover } from "./AnchoredPopover";
import { ListMusic, Plus, SlidersHorizontal, X } from "lucide-react";
import { api, plexFilterCount, type PlexFilters } from "../lib/api";
import { type PanelLayout } from "../lib/panelLayout";
import { type MediaSourceKind } from "../lib/mediaSource";
import { useDebounced } from "../lib/useDebounced";
import { useScrollFade } from "../lib/useScrollFade";
import FilterRail from "./FilterRail";
import { type PanelItem } from "./PanelGroups";
import SegmentedToggle from "./SegmentedToggle";
import FilterChipGroup from "./FilterChipGroup";
import MultiSelectChips from "./MultiSelectChips";
import Combobox, { type ComboboxOption } from "./Combobox";
import { usePlexClearFilters } from "./usePlexActiveFilters";
import { usePlex, usePlexActions } from "./PlexProvider";
@@ -205,15 +203,10 @@ export default function PlexSidebar({ layout, setLayout, collapsed, onToggleColl
{
id: "collection",
title: t("plex.filter.collection"),
body: filters.collection ? (
<div className="flex flex-wrap gap-1.5">
<RemovableChip
label={filters.collectionTitle || filters.collection}
onRemove={() => patch({ collection: null, collectionTitle: null })}
/>
</div>
) : (
body: (
<CollectionPicker
value={filters.collection}
title={filters.collectionTitle}
onPick={(id, title) => patch({ collection: id, collectionTitle: title })}
/>
),
@@ -248,7 +241,7 @@ export default function PlexSidebar({ layout, setLayout, collapsed, onToggleColl
/>
</div>
)}
<MultiSelectChips
<Combobox
label={t("plex.filter.genre")}
options={facets.genres}
selected={filters.genres}
@@ -329,7 +322,7 @@ export default function PlexSidebar({ layout, setLayout, collapsed, onToggleColl
id: "contentrating",
title: t("plex.filter.contentRating"),
body: (
<MultiSelectChips
<Combobox
label={t("plex.filter.contentRating")}
options={facets.content_ratings}
selected={filters.contentRatings}
@@ -345,7 +338,7 @@ export default function PlexSidebar({ layout, setLayout, collapsed, onToggleColl
id: "studio",
title: t("plex.filter.studio"),
body: (
<MultiSelectChips
<Combobox
label={t("plex.filter.studio")}
options={facets.studios}
selected={filters.studios}
@@ -383,103 +376,55 @@ export default function PlexSidebar({ layout, setLayout, collapsed, onToggleColl
);
}
// The collection filter as a compact "+ Add" → searchable popover (E5 S7), matching the genre/studio
// pickers instead of an always-expanded inline search + list. Single-select: picking a collection sets
// the filter and closes; the selected one then shows as a removable chip (handled by the caller).
function CollectionPicker({ onPick }: { onPick: (id: string, title: string) => void }) {
// The collection filter (E5 S7 → combobox rework): a single-select combi-input matching the
// genre/studio pickers, its vocabulary searched SERVER-side (the union can run to hundreds). The
// generic <Combobox> owns the field/keyboard/ARIA; this wrapper only owns the query→fetch (gated on
// `open`) and maps collections to options. Picking sets the filter (id + title for the chip); clearing
// the chip drops it.
function CollectionPicker({
value,
title,
onPick,
}: {
value: string | null | undefined;
title: string | null | undefined;
onPick: (id: string | null, title: string | null) => void;
}) {
const { t } = useTranslation();
const [open, setOpen] = useState(false);
const [search, setSearch] = useState("");
const searchDeb = useDebounced(search.trim(), 300);
const inputRef = useRef<HTMLInputElement>(null);
const fade = useScrollFade();
const q = useQuery({
queryKey: qk.plexCollections("union", searchDeb),
queryFn: () => api.plexCollections(undefined, searchDeb || undefined),
enabled: open, // only fetch while the picker is open
});
const collections = q.data?.collections ?? [];
// Search narrows server-side; cap the client render so a large union (hundreds) stays light.
const visibleCollections = collections.slice(0, 50);
const hiddenCollections = collections.length - visibleCollections.length;
const pop = useAnchoredPopover({
open,
onOpenChange: setOpen,
mode: "menu",
placement: "bottom-start",
hostsInput: true,
});
useEffect(() => {
if (open) inputRef.current?.focus();
else setSearch("");
}, [open]);
const options: ComboboxOption[] = (q.data?.collections ?? []).map((c) => ({
value: c.id,
label: c.title,
count: c.child_count ?? undefined,
}));
return (
<>
<button
ref={pop.refs.setReference}
type="button"
aria-label={t("plex.filter.add")}
className="glass-card glass-hover inline-flex items-center gap-1.5 rounded-lg px-2 py-1 text-xs text-muted transition hover:text-accent"
{...pop.getReferenceProps()}
>
<Plus className="h-3.5 w-3.5" />
{t("plex.filter.add")}
</button>
<PopoverSurface
popover={pop}
ariaLabel={t("plex.filter.collection")}
className="glass-menu w-60 rounded-xl p-1.5 animate-[popIn_0.16s_ease]"
>
<div className="relative mb-1">
<Search className="pointer-events-none absolute left-2 top-1/2 h-3.5 w-3.5 -translate-y-1/2 text-muted" />
<input
ref={inputRef}
value={search}
onChange={(e) => setSearch(e.target.value)}
onKeyDown={(e) => {
if (e.key === "Escape") return; // let the popover dismiss handle it
e.stopPropagation(); // keep text editing out of the surface's list-nav/typeahead
}}
placeholder={t("plex.filter.collectionSearch")}
className="w-full rounded-lg border border-border bg-surface py-1 pl-7 pr-2 text-sm focus:outline-hidden focus:ring-2 focus:ring-accent/40"
/>
</div>
<div ref={fade.ref} style={fade.style} className="max-h-64 overflow-y-auto no-scrollbar">
{collections.length === 0 ? (
<p className="px-2 py-1.5 text-xs text-muted">{t("plex.filter.collectionEmpty")}</p>
) : (
<>
{visibleCollections.map((c) => (
<PopoverItem
key={c.id}
role="option"
onSelect={() => {
onPick(c.id, c.title);
setOpen(false);
}}
label={c.title}
className="flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-left text-sm text-muted outline-hidden transition"
>
<Layers className="h-3.5 w-3.5 shrink-0" />
<span className="flex-1 truncate">{c.title}</span>
{c.child_count != null && (
<span className="shrink-0 text-2xs tabular-nums text-muted">
{c.child_count}
</span>
)}
</PopoverItem>
))}
{hiddenCollections > 0 && (
<p className="px-2 py-1.5 text-2xs text-muted">
{t("plex.filter.moreRefine", { count: hiddenCollections })}
</p>
)}
</>
)}
</div>
</PopoverSurface>
</>
<Combobox
label={t("plex.filter.collection")}
multiple={false}
clientFilter={false} // the server already narrows to `search`
options={options}
selected={value ? [value] : []}
selectedLabels={value && title ? { [value]: title } : undefined}
query={search}
onQueryChange={setSearch}
onOpenChange={setOpen}
loading={q.isFetching}
placeholder={t("plex.filter.collectionSearch")}
emptyText={t("plex.filter.collectionEmpty")}
onChange={(next) => {
const id = next[0] ?? null;
const picked = options.find((o) => o.value === id);
onPick(id, id ? (picked?.label ?? title ?? id) : null);
}}
/>
);
}