) => {
+ const lowerTitle = sheetTitle.toLowerCase();
+ const isSm = size === 'sm';
+ const sideButtonSize = isSm ? 'size-7' : 'size-8';
+ const middleHeight = isSm ? 'h-7' : 'h-8';
+
+ return (
+
+
+
+
+
+ Previous
+
+
+
+
+
+ Show all matching {lowerTitle}
+
+
+
+
+
+ Next
+
+
+ );
+};
diff --git a/frontend/src/components/shared/detail-navigation/detail-navigation-sheet.test.tsx b/frontend/src/components/shared/detail-navigation/detail-navigation-sheet.test.tsx
new file mode 100644
index 00000000..9965a92a
--- /dev/null
+++ b/frontend/src/components/shared/detail-navigation/detail-navigation-sheet.test.tsx
@@ -0,0 +1,241 @@
+import type { ReactNode } from 'react';
+
+import { fireEvent, render, screen, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { MemoryRouter, Route, Routes, useLocation } from 'react-router-dom';
+import { describe, expect, it } from 'vitest';
+
+import { TooltipProvider } from '@/components/ui/tooltip';
+
+import { DetailNavigationSheet } from './detail-navigation-sheet';
+import { useDetailNavigation } from './use-detail-navigation';
+
+interface Item {
+ id: string;
+ title: string;
+}
+
+const ITEMS: readonly Item[] = [
+ { id: 'a', title: 'Alpha' },
+ { id: 'b', title: 'Bravo' },
+ { id: 'c', title: 'Charlie' },
+ { id: 'd', title: 'Delta' },
+] as const;
+
+const getHref = (item: Item) => `/items/${item.id}`;
+const getLabel = (item: Item) => item.title;
+const getSearchableText = (item: Item) => item.title;
+
+const LocationReadout = () => {
+ const { pathname, search } = useLocation();
+
+ return (
+
+ {pathname}
+ {search}
+
+ );
+};
+
+interface HarnessProps {
+ currentId?: null | string;
+ filter?: string;
+ items?: readonly Item[];
+}
+
+/**
+ * Render the sheet open by default (`defaultOpen: true`) so keyboard /
+ * focus / a11y interactions can be exercised without round-tripping through
+ * the toolbar's position button. Keeps each test focused on the leaf.
+ */
+const SheetHarness = ({ currentId = 'c', items = ITEMS }: HarnessProps) => {
+ const nav = useDetailNavigation- ({
+ currentId,
+ defaultOpen: true,
+ getHref,
+ getLabel,
+ getSearchableText,
+ items,
+ });
+
+ return (
+
+ controller={nav}
+ sheetTitle="Items"
+ />
+ );
+};
+
+const renderSheet = (props: HarnessProps = {}) => {
+ const filter = props.filter ?? '';
+ const initialId = props.currentId ?? 'c';
+
+ const Wrapper = ({ children }: { children: ReactNode }) => (
+
+
+
+
+ {children}}
+ path="/items/:id"
+ />
+
+
+
+ );
+
+ return render(, { wrapper: Wrapper });
+};
+
+describe('DetailNavigationSheet — a11y / aria contract', () => {
+ it('renders the listbox with the sheet title as accessible name (aria-describedby opt-out preserved)', async () => {
+ renderSheet({ currentId: 'c' });
+
+ const listbox = await screen.findByRole('listbox', { name: 'Items' });
+ expect(listbox).toBeInTheDocument();
+ });
+
+ it('marks the current item with aria-selected', async () => {
+ renderSheet({ currentId: 'c' });
+
+ const listbox = await screen.findByRole('listbox');
+ const current = within(listbox).getByRole('option', { selected: true });
+ expect(current).toHaveAttribute('data-item-id', 'c');
+ });
+});
+
+describe('DetailNavigationSheet — roving tabIndex', () => {
+ it('only the current option carries tabIndex={0}', async () => {
+ renderSheet({ currentId: 'c' });
+
+ const listbox = await screen.findByRole('listbox');
+ const options = within(listbox).getAllByRole('option');
+
+ await waitFor(() => {
+ const focusable = options.filter((option) => option.getAttribute('tabindex') === '0');
+ expect(focusable).toHaveLength(1);
+ expect(focusable[0]).toHaveAttribute('data-item-id', 'c');
+ });
+
+ const nonFocusable = options.filter((option) => option.getAttribute('tabindex') === '-1');
+ expect(nonFocusable.length).toBe(options.length - 1);
+ });
+
+ it('falls back to the first filtered option when current is outside the subset', async () => {
+ renderSheet({ currentId: 'zzz' });
+
+ const listbox = await screen.findByRole('listbox');
+ await waitFor(() => {
+ const focused = within(listbox)
+ .getAllByRole('option')
+ .find((option) => option.getAttribute('tabindex') === '0');
+ expect(focused).toHaveAttribute('data-item-id', 'a');
+ });
+ });
+});
+
+describe('DetailNavigationSheet — keyboard navigation', () => {
+ it('ArrowDown moves roving focus to the next option', async () => {
+ renderSheet({ currentId: 'b' });
+
+ const listbox = await screen.findByRole('listbox');
+ await waitFor(() => {
+ const focused = within(listbox)
+ .getAllByRole('option')
+ .find((option) => option.getAttribute('tabindex') === '0');
+ expect(focused).toHaveAttribute('data-item-id', 'b');
+ });
+
+ fireEvent.keyDown(listbox, { key: 'ArrowDown' });
+
+ await waitFor(() => {
+ const focused = within(listbox)
+ .getAllByRole('option')
+ .find((option) => option.getAttribute('tabindex') === '0');
+ expect(focused).toHaveAttribute('data-item-id', 'c');
+ });
+ });
+
+ it('ArrowUp at the first option clamps (no wrap)', async () => {
+ renderSheet({ currentId: 'a' });
+
+ const listbox = await screen.findByRole('listbox');
+ await waitFor(() => {
+ const focused = within(listbox)
+ .getAllByRole('option')
+ .find((option) => option.getAttribute('tabindex') === '0');
+ expect(focused).toHaveAttribute('data-item-id', 'a');
+ });
+
+ fireEvent.keyDown(listbox, { key: 'ArrowUp' });
+
+ // Focus stays on the first option — no wrap-around.
+ const focused = within(listbox)
+ .getAllByRole('option')
+ .find((option) => option.getAttribute('tabindex') === '0');
+ expect(focused).toHaveAttribute('data-item-id', 'a');
+ });
+
+ it('End jumps roving focus to the last option', async () => {
+ renderSheet({ currentId: 'a' });
+
+ const listbox = await screen.findByRole('listbox');
+ fireEvent.keyDown(listbox, { key: 'End' });
+
+ await waitFor(() => {
+ const focused = within(listbox)
+ .getAllByRole('option')
+ .find((option) => option.getAttribute('tabindex') === '0');
+ expect(focused).toHaveAttribute('data-item-id', 'd');
+ });
+ });
+
+ it('Home jumps roving focus to the first option', async () => {
+ renderSheet({ currentId: 'd' });
+
+ const listbox = await screen.findByRole('listbox');
+ await waitFor(() => {
+ const focused = within(listbox)
+ .getAllByRole('option')
+ .find((option) => option.getAttribute('tabindex') === '0');
+ expect(focused).toHaveAttribute('data-item-id', 'd');
+ });
+
+ fireEvent.keyDown(listbox, { key: 'Home' });
+
+ await waitFor(() => {
+ const focused = within(listbox)
+ .getAllByRole('option')
+ .find((option) => option.getAttribute('tabindex') === '0');
+ expect(focused).toHaveAttribute('data-item-id', 'a');
+ });
+ });
+});
+
+describe('DetailNavigationSheet — selection', () => {
+ it('clicking an option navigates and closes the sheet', async () => {
+ const user = userEvent.setup();
+ renderSheet({ currentId: 'c' });
+
+ const listbox = await screen.findByRole('listbox');
+ await user.click(within(listbox).getByRole('option', { name: 'Alpha' }));
+
+ await waitFor(() => {
+ expect(screen.queryByRole('listbox', { name: 'Items' })).not.toBeInTheDocument();
+ });
+ expect(screen.getByTestId('location').textContent).toContain('/items/a');
+ });
+
+ it('narrows the listbox to filtered items', async () => {
+ renderSheet({ currentId: 'a', filter: 'pha' });
+
+ const listbox = await screen.findByRole('listbox', { name: 'Items' });
+
+ await waitFor(() => {
+ const labels = within(listbox)
+ .getAllByRole('option')
+ .map((option) => option.textContent ?? '');
+ expect(labels).toEqual(['Alpha']);
+ });
+ });
+});
diff --git a/frontend/src/components/shared/detail-navigation/detail-navigation-sheet.tsx b/frontend/src/components/shared/detail-navigation/detail-navigation-sheet.tsx
new file mode 100644
index 00000000..49c176cc
--- /dev/null
+++ b/frontend/src/components/shared/detail-navigation/detail-navigation-sheet.tsx
@@ -0,0 +1,310 @@
+import { type KeyboardEvent, type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { Badge } from '@/components/ui/badge';
+import { ScrollArea } from '@/components/ui/scroll-area';
+import { Sheet, SheetContent, SheetHeader, SheetTitle } from '@/components/ui/sheet';
+import { cn } from '@/lib/utils';
+
+import type { DetailNavigationController } from './use-detail-navigation';
+
+interface DetailNavigationSheetProps {
+ controller: DetailNavigationController;
+ renderItem?: (item: T, isCurrent: boolean) => ReactNode;
+ sheetIcon?: ReactNode;
+ sheetTitle: string;
+}
+
+/**
+ * Listbox-style overlay listing the navigable subset.
+ *
+ * Implements the WAI-ARIA single-select listbox pattern with **roving
+ * tabindex**: only the currently-focused option carries `tabIndex={0}`,
+ * the rest are `tabIndex={-1}`. Tab takes the user *past* the listbox in
+ * one step; arrow keys move focus *within* it.
+ *
+ * Initial focus on open targets the current entry (if it's part of the
+ * filtered subset) so users land oriented inside their own context.
+ */
+export const DetailNavigationSheet = ({
+ controller,
+ renderItem,
+ sheetIcon,
+ sheetTitle,
+}: DetailNavigationSheetProps) => {
+ // Destructure at the top so existing `useMemo` / `useEffect` deps below
+ // read individual fields rather than the controller object — keeps the
+ // identity story the same as before the refactor.
+ const {
+ currentId,
+ currentIndex,
+ filteredItems: items,
+ getId,
+ getLabel,
+ handleItemSelect: onItemSelect,
+ isSheetOpen: open,
+ setSheetOpen: onOpenChange,
+ total,
+ } = controller;
+
+ const listRef = useRef(null);
+ const buttonRefs = useRef(new Map());
+ const [focusedId, setFocusedId] = useState(null);
+
+ const hasEntries = items.length > 0;
+
+ // Build an `id → index` map once per `items`/`getId` change so both the
+ // per-render membership check below and the keyboard handler's lookup
+ // stay O(1) instead of O(n). The IIFE that adjusts focus during render
+ // previously called `items.some(...)` on every commit; the keyboard
+ // handler ran `items.findIndex(...)` on every keystroke. Sharing one
+ // structure between the two also makes the contract explicit: an entry
+ // is "in the filtered subset" iff `indexById.has(id)`.
+ const indexById = useMemo(() => {
+ const map = new Map();
+
+ items.forEach((item, index) => {
+ map.set(String(getId(item)), index);
+ });
+
+ return map;
+ }, [items, getId]);
+
+ // Single render-phase focus reconciliation. React's "adjust state when a
+ // prop changes" idiom — see https://react.dev/reference/react/useState#storing-information-from-previous-renders
+ // — collapsed into one comparison so the next desired focus is decided
+ // once per render and committed in the same pass that prompted it (no
+ // flash of stale focus, no double-setState ping-pong on edge cases like
+ // "items change while the sheet was reopening with no current item").
+ //
+ // Priorities, top-down:
+ // 1. open→close / close→open transition: re-pin to `currentId` (or the
+ // first entry when no current exists) on open, and clear on close.
+ // 2. While the sheet stays open, if the focused entry left the
+ // filtered subset (list page narrowed the filter behind it), fall
+ // back to the first survivor — otherwise the keyboard model would
+ // stall on a row that's no longer rendered.
+ // 3. Otherwise hold whatever focus the user chose via arrow keys.
+ //
+ // `lastOpen` starts at `false` so an initial `open=true` still trips
+ // the open transition on the very first render.
+ const [lastOpen, setLastOpen] = useState(false);
+
+ const desiredFocusId = (() => {
+ if (lastOpen !== open) {
+ if (!open) {
+ return null;
+ }
+
+ const firstItem = items[0];
+
+ if (!firstItem) {
+ return null;
+ }
+
+ // `currentId != null` narrows to `string`; the controller has
+ // already verified `currentId` belongs to the filtered subset
+ // when it computed `currentIndex`, so no re-scan needed.
+ return currentId != null && currentIndex >= 0 ? String(currentId) : String(getId(firstItem));
+ }
+
+ if (open && focusedId !== null && hasEntries && !indexById.has(focusedId)) {
+ const fallbackItem = items[0];
+
+ return fallbackItem ? String(getId(fallbackItem)) : null;
+ }
+
+ return focusedId;
+ })();
+
+ if (lastOpen !== open) {
+ setLastOpen(open);
+ }
+
+ if (desiredFocusId !== focusedId) {
+ setFocusedId(desiredFocusId);
+ }
+
+ // After roving focus moves, push the focus into the DOM. `rAF` defers past
+ // Radix's own focus management so we don't fight its open-time focus trap.
+ useEffect(() => {
+ if (!open || focusedId === null) {
+ return;
+ }
+
+ const id = requestAnimationFrame(() => {
+ const node = buttonRefs.current.get(focusedId);
+
+ if (!node) {
+ return;
+ }
+
+ node.focus();
+
+ if (focusedId === String(currentId ?? '')) {
+ node.scrollIntoView({ block: 'center' });
+ }
+ });
+
+ return () => cancelAnimationFrame(id);
+ }, [open, focusedId, currentId]);
+
+ // Translate arrow / Home / End into roving moves over `items`. Using the
+ // array index instead of `querySelectorAll` keeps the keyboard model in
+ // step with the React tree even if the sheet ever virtualises the list.
+ // O(1) lookup via the shared `indexById` map — `findIndex` would scan on
+ // every keystroke for nothing.
+ const handleListKeyDown = useCallback(
+ (event: KeyboardEvent) => {
+ if (!hasEntries || focusedId === null) {
+ return;
+ }
+
+ const focusedIndex = indexById.get(focusedId);
+
+ if (focusedIndex === undefined) {
+ return;
+ }
+
+ const moveTo = (index: number) => {
+ event.preventDefault();
+ const target = items[index];
+
+ if (target) {
+ setFocusedId(String(getId(target)));
+ }
+ };
+
+ if (event.key === 'ArrowDown') {
+ moveTo(Math.min(focusedIndex + 1, items.length - 1));
+
+ return;
+ }
+
+ if (event.key === 'ArrowUp') {
+ moveTo(Math.max(focusedIndex - 1, 0));
+
+ return;
+ }
+
+ if (event.key === 'Home') {
+ moveTo(0);
+
+ return;
+ }
+
+ if (event.key === 'End') {
+ moveTo(items.length - 1);
+ }
+ },
+ [focusedId, getId, hasEntries, indexById, items],
+ );
+
+ const handleItemClick = useCallback(
+ (item: T) => {
+ onItemSelect(item);
+ },
+ [onItemSelect],
+ );
+
+ // One stable callback ref reused for every button. The previous shape —
+ // `setButtonRef(id) => (node) => …` — manufactured a new closure per id
+ // on every render, which made React re-attach refs (a `delete` + `set`
+ // round-trip on the `Map`) on every list re-render. Reading the id from
+ // `data-item-id` keeps the closure identity-stable and the React-19
+ // cleanup return value handles unmount without leaks.
+ const setButtonRef = useCallback((node: HTMLButtonElement | null) => {
+ if (!node) {
+ return;
+ }
+
+ const id = node.dataset.itemId;
+
+ if (!id) {
+ return;
+ }
+
+ buttonRefs.current.set(id, node);
+
+ return () => {
+ buttonRefs.current.delete(id);
+ };
+ }, []);
+
+ return (
+
+ ` or an explicit
+ // `aria-describedby={undefined}` opt-out. The sheet is just a
+ // listbox of items, the `SheetTitle` already describes it.
+ aria-describedby={undefined}
+ className="flex w-full max-w-sm flex-col gap-0 p-0 sm:max-w-sm"
+ side="right"
+ >
+
+
+ {sheetIcon}
+ {sheetTitle}
+
+ {total}
+
+
+
+ {hasEntries ? (
+
+
+ {items.map((item) => {
+ const id = String(getId(item));
+ const isCurrent = currentId != null && id === String(currentId);
+ const isFocused = id === focusedId;
+
+ return (
+ -
+
+
+ );
+ })}
+
+
+ ) : (
+
+ No items match the current filter.
+
+ )}
+
+
+ );
+};
diff --git a/frontend/src/components/shared/detail-navigation/detail-navigation-toolbar.test.tsx b/frontend/src/components/shared/detail-navigation/detail-navigation-toolbar.test.tsx
new file mode 100644
index 00000000..ebccb3c4
--- /dev/null
+++ b/frontend/src/components/shared/detail-navigation/detail-navigation-toolbar.test.tsx
@@ -0,0 +1,138 @@
+import type { ReactNode } from 'react';
+
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { MemoryRouter, Route, Routes, useLocation } from 'react-router-dom';
+import { describe, expect, it } from 'vitest';
+
+import { TooltipProvider } from '@/components/ui/tooltip';
+
+import { DetailNavigationToolbar } from './detail-navigation-toolbar';
+import { useDetailNavigation } from './use-detail-navigation';
+
+interface Item {
+ id: string;
+ title: string;
+}
+
+const ITEMS: readonly Item[] = [
+ { id: 'a', title: 'Alpha' },
+ { id: 'b', title: 'Bravo' },
+ { id: 'c', title: 'Charlie' },
+ { id: 'd', title: 'Delta' },
+] as const;
+
+const getHref = (item: Item) => `/items/${item.id}`;
+const getLabel = (item: Item) => item.title;
+
+const LocationReadout = () => {
+ const { pathname, search } = useLocation();
+
+ return (
+
+ {pathname}
+ {search}
+
+ );
+};
+
+interface HarnessProps {
+ currentId?: null | string;
+ filter?: string;
+ items?: readonly Item[];
+}
+
+const ToolbarHarness = ({ currentId = 'c', items = ITEMS }: HarnessProps) => {
+ const nav = useDetailNavigation- ({
+ currentId,
+ getHref,
+ getLabel,
+ items,
+ });
+
+ return (
+
+ controller={nav}
+ sheetTitle="Items"
+ />
+ );
+};
+
+const renderToolbar = (props: HarnessProps = {}) => {
+ const filter = props.filter ?? '';
+ const initialId = props.currentId ?? 'c';
+
+ const Wrapper = ({ children }: { children: ReactNode }) => (
+
+
+
+
+ {children}}
+ path="/items/:id"
+ />
+
+
+
+ );
+
+ return render(, { wrapper: Wrapper });
+};
+
+describe('DetailNavigationToolbar', () => {
+ it('renders nothing when raw items is empty', () => {
+ renderToolbar({ items: [] });
+ expect(screen.queryByRole('button', { name: /Previous/i })).not.toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: /Next/i })).not.toBeInTheDocument();
+ });
+
+ it('composes Buttons + Sheet: position button opens the listbox', async () => {
+ const user = userEvent.setup();
+ renderToolbar({ currentId: 'c' });
+
+ // Buttons present (smoke).
+ expect(screen.getByRole('button', { name: /Previous/i })).toBeInTheDocument();
+ expect(screen.getByRole('button', { name: /Next/i })).toBeInTheDocument();
+
+ // Position trigger opens the sheet.
+ await user.click(screen.getByRole('button', { name: /3\/4/ }));
+ const listbox = await screen.findByRole('listbox', { name: 'Items' });
+ expect(listbox).toBeInTheDocument();
+ });
+
+ it('shows `–/total` when current is missing from the filtered subset', () => {
+ renderToolbar({ currentId: 'zzz' });
+ expect(screen.getByRole('button', { name: /–\/4/ })).toBeInTheDocument();
+ });
+
+ it('disables Prev for the first item', () => {
+ renderToolbar({ currentId: 'a' });
+ expect(screen.getByRole('button', { name: /Previous/i })).toBeDisabled();
+ });
+
+ it('disables Next for the last item', () => {
+ renderToolbar({ currentId: 'd' });
+ expect(screen.getByRole('button', { name: /Next/i })).toBeDisabled();
+ });
+
+ it('Next navigates to the next sibling preserving `?q=`', async () => {
+ const user = userEvent.setup();
+ renderToolbar({ currentId: 'a', filter: 'a' });
+
+ await user.click(screen.getByRole('button', { name: /Next/i }));
+
+ await waitFor(() => {
+ expect(screen.getByTestId('location').textContent).toContain('/items/b');
+ });
+ expect(screen.getByTestId('location').textContent).toContain('q=a');
+ });
+
+ it('disables the position button when the filter excludes every item', async () => {
+ renderToolbar({ currentId: 'c', filter: 'qqqqqqqqq' });
+
+ // After debounce settles, the empty subset disables the trigger.
+ await waitFor(() => {
+ expect(screen.getByRole('button', { name: /–\/0/ })).toBeDisabled();
+ });
+ });
+});
diff --git a/frontend/src/components/shared/detail-navigation/detail-navigation-toolbar.tsx b/frontend/src/components/shared/detail-navigation/detail-navigation-toolbar.tsx
new file mode 100644
index 00000000..77d516dd
--- /dev/null
+++ b/frontend/src/components/shared/detail-navigation/detail-navigation-toolbar.tsx
@@ -0,0 +1,49 @@
+import type { ReactNode } from 'react';
+
+import type { DetailNavigationController } from './use-detail-navigation';
+
+import { DetailNavigationButtons } from './detail-navigation-buttons';
+import { DetailNavigationSheet } from './detail-navigation-sheet';
+
+export interface DetailNavigationToolbarProps {
+ controller: DetailNavigationController;
+ renderItem?: (item: T, isCurrent: boolean) => ReactNode;
+ sheetIcon?: ReactNode;
+ sheetTitle: string;
+}
+
+/**
+ * Convenience wrapper that composes `` and
+ * `` against a single `DetailNavigationController`.
+ * Most desktop call sites use this directly; pages with non-standard chrome
+ * (e.g. mobile prev/position/next inside a ``) can compose
+ * the leaves themselves and read from the same controller.
+ *
+ * Renders `null` when the controller reports `itemsEmpty` — saves the user
+ * from a momentary "–/0" flash while the parent provider's data is in flight.
+ */
+export const DetailNavigationToolbar = ({
+ controller,
+ renderItem,
+ sheetIcon,
+ sheetTitle,
+}: DetailNavigationToolbarProps) => {
+ if (controller.itemsEmpty) {
+ return null;
+ }
+
+ return (
+ <>
+
+
+
+ );
+};
diff --git a/frontend/src/components/shared/detail-navigation/index.ts b/frontend/src/components/shared/detail-navigation/index.ts
new file mode 100644
index 00000000..87439002
--- /dev/null
+++ b/frontend/src/components/shared/detail-navigation/index.ts
@@ -0,0 +1,4 @@
+export { DetailNavigationButtons } from './detail-navigation-buttons';
+export { DetailNavigationSheet } from './detail-navigation-sheet';
+export { DetailNavigationToolbar } from './detail-navigation-toolbar';
+export { type DetailNavigationController, useDetailNavigation } from './use-detail-navigation';
diff --git a/frontend/src/components/shared/detail-navigation/text-filter.test.ts b/frontend/src/components/shared/detail-navigation/text-filter.test.ts
new file mode 100644
index 00000000..bdb0e66d
--- /dev/null
+++ b/frontend/src/components/shared/detail-navigation/text-filter.test.ts
@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest';
+
+import { createTextMatcher, matchesTextFilter, normalizeForFilter } from './text-filter';
+
+describe('normalizeForFilter', () => {
+ it('lowercases ASCII text', () => {
+ expect(normalizeForFilter('FooBar')).toBe('foobar');
+ });
+
+ it('strips combining diacritics so accented characters fold to plain', () => {
+ expect(normalizeForFilter('café')).toBe('cafe');
+ expect(normalizeForFilter('résumé')).toBe('resume');
+ expect(normalizeForFilter('naïve')).toBe('naive');
+ });
+
+ it('is idempotent', () => {
+ const once = normalizeForFilter('Café');
+ expect(normalizeForFilter(once)).toBe(once);
+ });
+});
+
+describe('createTextMatcher', () => {
+ it('returns a matcher that accepts everything for an empty query', () => {
+ const matcher = createTextMatcher('');
+
+ expect(matcher('anything')).toBe(true);
+ expect(matcher('')).toBe(true);
+ expect(matcher(null)).toBe(true);
+ expect(matcher(undefined)).toBe(true);
+ });
+
+ it('matches case-insensitively', () => {
+ const matcher = createTextMatcher('Foo');
+
+ expect(matcher('foo')).toBe(true);
+ expect(matcher('FOO')).toBe(true);
+ expect(matcher('hello FOO bar')).toBe(true);
+ expect(matcher('bar')).toBe(false);
+ });
+
+ it('matches across diacritic-folded forms', () => {
+ const matcher = createTextMatcher('cafe');
+
+ expect(matcher('café')).toBe(true);
+ expect(matcher('Café au lait')).toBe(true);
+ expect(matcher('CAFÉ')).toBe(true);
+ });
+
+ it('folds diacritics in the query too', () => {
+ const matcher = createTextMatcher('Café');
+
+ expect(matcher('cafe')).toBe(true);
+ expect(matcher('CAFE')).toBe(true);
+ });
+
+ it('returns false for null and undefined text when query is non-empty', () => {
+ const matcher = createTextMatcher('foo');
+
+ expect(matcher(null)).toBe(false);
+ expect(matcher(undefined)).toBe(false);
+ });
+
+ it('does substring matching, not whole-word or prefix matching', () => {
+ const matcher = createTextMatcher('ell');
+
+ expect(matcher('hello')).toBe(true);
+ expect(matcher('shell shocked')).toBe(true);
+ expect(matcher('apricot')).toBe(false);
+ });
+
+ it('preserves whitespace exactly — does not trim the query', () => {
+ const matcher = createTextMatcher(' foo ');
+
+ expect(matcher(' foo ')).toBe(true);
+ expect(matcher('foo')).toBe(false);
+ });
+
+ it('returns the same matcher behaviour across many invocations (no internal state leak)', () => {
+ const matcher = createTextMatcher('abc');
+
+ for (let i = 0; i < 10; i += 1) {
+ expect(matcher('xxabcyy')).toBe(true);
+ expect(matcher('xyz')).toBe(false);
+ }
+ });
+});
+
+describe('matchesTextFilter', () => {
+ it('delegates to createTextMatcher and produces the same answers', () => {
+ expect(matchesTextFilter('hello', 'ell')).toBe(true);
+ expect(matchesTextFilter('hello', 'world')).toBe(false);
+ expect(matchesTextFilter(null, 'foo')).toBe(false);
+ expect(matchesTextFilter(null, '')).toBe(true);
+ });
+
+ it('folds diacritics symmetrically on both sides', () => {
+ expect(matchesTextFilter('résumé.pdf', 'resume')).toBe(true);
+ expect(matchesTextFilter('resume.pdf', 'résumé')).toBe(true);
+ });
+});
diff --git a/frontend/src/components/shared/detail-navigation/text-filter.ts b/frontend/src/components/shared/detail-navigation/text-filter.ts
new file mode 100644
index 00000000..b3344d67
--- /dev/null
+++ b/frontend/src/components/shared/detail-navigation/text-filter.ts
@@ -0,0 +1,55 @@
+/**
+ * Normalize a string for case- and diacritic-insensitive substring matching.
+ *
+ * `NFKD` decomposes accented characters into base + combining marks, then we
+ * strip the combining marks (`\p{Diacritic}` regex class) so e.g. `café`
+ * matches `cafe`. Lowercasing happens last to fold case differences.
+ *
+ * Exported for callers that need to align their own search semantics with the
+ * one this module uses (e.g. server-side prefiltering).
+ */
+export const normalizeForFilter = (text: string): string =>
+ text
+ .normalize('NFKD')
+ .replace(/\p{Diacritic}/gu, '')
+ .toLowerCase();
+
+/**
+ * Build a reusable text-matcher specialised for `query`. The query is
+ * normalized + lowercased once at factory time — when the resulting matcher
+ * is invoked N times during list filtering, that work is amortised to one
+ * allocation instead of N.
+ *
+ * The matcher uses substring matching semantics, with case + diacritic
+ * folding (`café` matches `cafe`). It is intentionally close to TanStack
+ * Table's default `'includesString'` so a single instance can drive both
+ * the list page's column filter and the detail page's Prev/Next subset
+ * without the two paths drifting out of sync.
+ *
+ * - Empty query → every row passes (matcher returns `true`).
+ * - `text === null | undefined` with a non-empty query → no match.
+ */
+export const createTextMatcher = (query: string): ((text: null | string | undefined) => boolean) => {
+ if (!query.length) {
+ return () => true;
+ }
+
+ const normalizedQuery = normalizeForFilter(query);
+
+ return (text) => {
+ if (text === null || text === undefined) {
+ return false;
+ }
+
+ return normalizeForFilter(text).includes(normalizedQuery);
+ };
+};
+
+/**
+ * One-shot variant of {@link createTextMatcher} for callers that need a
+ * single comparison and don't want to bother with the factory. Equivalent to
+ * `createTextMatcher(query)(text)` — kept as a thin wrapper for readability
+ * at call sites and to preserve the original API.
+ */
+export const matchesTextFilter = (text: null | string | undefined, query: string): boolean =>
+ createTextMatcher(query)(text);
diff --git a/frontend/src/components/shared/detail-navigation/use-detail-navigation.test.tsx b/frontend/src/components/shared/detail-navigation/use-detail-navigation.test.tsx
new file mode 100644
index 00000000..81d0657c
--- /dev/null
+++ b/frontend/src/components/shared/detail-navigation/use-detail-navigation.test.tsx
@@ -0,0 +1,479 @@
+import type { ReactNode } from 'react';
+
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { MemoryRouter, Route, Routes, useLocation, useNavigate } from 'react-router-dom';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { useDetailNavigation } from './use-detail-navigation';
+
+interface Item {
+ id: string;
+ title: string;
+}
+
+const ITEMS: readonly Item[] = [
+ { id: 'a', title: 'Alpha' },
+ { id: 'b', title: 'Bravo' },
+ { id: 'c', title: 'Charlie' },
+] as const;
+
+const getHref = (item: Item) => `/items/${item.id}`;
+const getLabel = (item: Item) => item.title;
+const getSearchableText = (item: Item) => item.title;
+
+const renderInRoute = (initialEntries: string[]) => {
+ const Wrapper = ({ children }: { children: ReactNode }) => (
+
+
+ {children}}
+ path="/items/:id"
+ />
+
+
+ );
+
+ return Wrapper;
+};
+
+beforeEach(() => {
+ localStorage.clear();
+});
+
+afterEach(() => {
+ localStorage.clear();
+});
+
+describe('useDetailNavigation — default getId', () => {
+ it('uses item.id when no `getId` override is provided', () => {
+ const { result } = renderHook(
+ () =>
+ useDetailNavigation
- ({
+ currentId: 'b',
+ getHref,
+ getLabel,
+ getSearchableText,
+ items: ITEMS,
+ }),
+ { wrapper: renderInRoute(['/items/b']) },
+ );
+
+ expect(result.current.getId(ITEMS[1])).toBe('b');
+ });
+});
+
+describe('useDetailNavigation — identity stability', () => {
+ it('keeps the controller reference stable across re-renders with unchanged inputs', () => {
+ const { rerender, result } = renderHook(
+ () =>
+ useDetailNavigation
- ({
+ currentId: 'b',
+ getHref,
+ getLabel,
+ getSearchableText,
+ items: ITEMS,
+ }),
+ { wrapper: renderInRoute(['/items/b']) },
+ );
+
+ const first = result.current;
+ rerender();
+ // Downstream leaf components rely on this identity stability.
+ expect(result.current).toBe(first);
+ });
+
+ it('keeps `goToPrev` / `goToNext` / `handleItemSelect` identity-stable when nothing relevant changes', () => {
+ const { rerender, result } = renderHook(
+ () =>
+ useDetailNavigation
- ({
+ currentId: 'b',
+ getHref,
+ getLabel,
+ getSearchableText,
+ items: ITEMS,
+ }),
+ { wrapper: renderInRoute(['/items/b']) },
+ );
+
+ const firstGoPrev = result.current.goToPrev;
+ const firstGoNext = result.current.goToNext;
+ const firstSelect = result.current.handleItemSelect;
+ const firstOpen = result.current.openSheet;
+ const firstSet = result.current.setSheetOpen;
+ rerender();
+
+ expect(result.current.goToPrev).toBe(firstGoPrev);
+ expect(result.current.goToNext).toBe(firstGoNext);
+ expect(result.current.handleItemSelect).toBe(firstSelect);
+ expect(result.current.openSheet).toBe(firstOpen);
+ expect(result.current.setSheetOpen).toBe(firstSet);
+ });
+});
+
+describe('useDetailNavigation — filter forwarding', () => {
+ it('exposes the URL `?q=` value through `controller.debouncedFilter` (debounced)', async () => {
+ const { result } = renderHook(
+ () =>
+ useDetailNavigation
- ({
+ currentId: 'b',
+ getHref,
+ getLabel,
+ getSearchableText,
+ items: ITEMS,
+ }),
+ { wrapper: renderInRoute(['/items/b?q=alpha']) },
+ );
+
+ // `debouncedFilter` settles after the default 200ms debounce.
+ await waitFor(() => {
+ expect(result.current.debouncedFilter).toBe('alpha');
+ });
+ });
+
+ it('narrows `filteredItems` to the matching subset once the filter settles', async () => {
+ const { result } = renderHook(
+ () =>
+ useDetailNavigation
- ({
+ currentId: 'a',
+ getHref,
+ getLabel,
+ getSearchableText,
+ items: ITEMS,
+ }),
+ { wrapper: renderInRoute(['/items/a?q=pha']) },
+ );
+
+ await waitFor(() => {
+ expect(result.current.filteredItems.map((item) => item.id)).toEqual(['a']);
+ });
+ expect(result.current.total).toBe(1);
+ expect(result.current.currentIndex).toBe(0);
+ });
+});
+
+describe('useDetailNavigation — derived state', () => {
+ it('reports prev/next neighbours for a middle item', () => {
+ const { result } = renderHook(
+ () =>
+ useDetailNavigation
- ({
+ currentId: 'b',
+ getHref,
+ getLabel,
+ getSearchableText,
+ items: ITEMS,
+ }),
+ { wrapper: renderInRoute(['/items/b']) },
+ );
+
+ expect(result.current.currentIndex).toBe(1);
+ expect(result.current.prevId).toBe('a');
+ expect(result.current.nextId).toBe('c');
+ expect(result.current.total).toBe(3);
+ expect(result.current.hasEntries).toBe(true);
+ expect(result.current.itemsEmpty).toBe(false);
+ expect(result.current.positionLabel).toBe('2/3');
+ });
+
+ it('reports `-1` index and `–/total` label when currentId is not in subset', () => {
+ const { result } = renderHook(
+ () =>
+ useDetailNavigation
- ({
+ currentId: 'zzz',
+ getHref,
+ getLabel,
+ getSearchableText,
+ items: ITEMS,
+ }),
+ { wrapper: renderInRoute(['/items/zzz']) },
+ );
+
+ expect(result.current.currentIndex).toBe(-1);
+ expect(result.current.prevId).toBeNull();
+ expect(result.current.nextId).toBeNull();
+ expect(result.current.positionLabel).toBe('–/3');
+ });
+
+ it('reports `itemsEmpty=true` and `–/0` when input list is empty', () => {
+ const { result } = renderHook(
+ () =>
+ useDetailNavigation
- ({
+ currentId: 'b',
+ getHref,
+ getLabel,
+ getSearchableText,
+ items: [],
+ }),
+ { wrapper: renderInRoute(['/items/b']) },
+ );
+
+ expect(result.current.itemsEmpty).toBe(true);
+ expect(result.current.total).toBe(0);
+ expect(result.current.hasEntries).toBe(false);
+ expect(result.current.positionLabel).toBe('–/0');
+ });
+});
+
+describe('useDetailNavigation — navigation actions', () => {
+ it('goToNext() navigates to the next sibling preserving `?q=`', async () => {
+ const LocationProbe = ({ onChange }: { onChange: (loc: string) => void }) => {
+ const { pathname, search } = useLocation();
+ onChange(`${pathname}${search}`);
+
+ return null;
+ };
+
+ const seen: string[] = [];
+ const Wrapper = ({ children }: { children: ReactNode }) => (
+
+ seen.push(loc)} />
+
+ {children}}
+ path="/items/:id"
+ />
+
+
+ );
+
+ const { result } = renderHook(
+ () =>
+ useDetailNavigation
- ({
+ currentId: 'a',
+ getHref,
+ getLabel,
+ getSearchableText,
+ items: ITEMS,
+ }),
+ { wrapper: Wrapper },
+ );
+
+ await waitFor(() => {
+ expect(result.current.debouncedFilter).toBe('a');
+ });
+
+ act(() => {
+ result.current.goToNext();
+ });
+
+ await waitFor(() => {
+ expect(seen.at(-1)).toContain('/items/b');
+ });
+ expect(seen.at(-1)).toContain('q=a');
+ });
+
+ it('goToPrev() is a no-op when prevId is null (no navigate)', async () => {
+ const LocationProbe = ({ onChange }: { onChange: (loc: string) => void }) => {
+ const { pathname } = useLocation();
+ onChange(pathname);
+
+ return null;
+ };
+
+ const seen: string[] = [];
+ const Wrapper = ({ children }: { children: ReactNode }) => (
+
+ seen.push(loc)} />
+
+ {children}}
+ path="/items/:id"
+ />
+
+
+ );
+
+ const { result } = renderHook(
+ () =>
+ useDetailNavigation
- ({
+ currentId: 'a',
+ getHref,
+ getLabel,
+ getSearchableText,
+ items: ITEMS,
+ }),
+ { wrapper: Wrapper },
+ );
+
+ expect(result.current.prevId).toBeNull();
+ const before = seen.length;
+
+ act(() => {
+ result.current.goToPrev();
+ });
+
+ // No path change emitted.
+ expect(seen.length).toBe(before);
+ });
+
+ it('handleItemSelect closes the sheet *before* navigating', async () => {
+ const Wrapper = ({ children }: { children: ReactNode }) => (
+
+
+ {children}}
+ path="/items/:id"
+ />
+
+
+ );
+
+ const { result } = renderHook(
+ () =>
+ useDetailNavigation
- ({
+ currentId: 'a',
+ defaultOpen: true,
+ getHref,
+ getLabel,
+ getSearchableText,
+ items: ITEMS,
+ }),
+ { wrapper: Wrapper },
+ );
+
+ expect(result.current.isSheetOpen).toBe(true);
+
+ act(() => {
+ result.current.handleItemSelect(ITEMS[2]);
+ });
+
+ // Sheet closes synchronously inside the same call — the navigate
+ // that follows can't race with a still-mounted sheet.
+ expect(result.current.isSheetOpen).toBe(false);
+ });
+});
+
+describe('useDetailNavigation — controlled sheet mode', () => {
+ it('respects `open={true}` even when `setSheetOpen(false)` is called', () => {
+ const onOpenChange = vi.fn();
+
+ const { result } = renderHook(
+ () =>
+ useDetailNavigation
- ({
+ currentId: 'b',
+ getHref,
+ getLabel,
+ getSearchableText,
+ items: ITEMS,
+ onOpenChange,
+ open: true,
+ }),
+ { wrapper: renderInRoute(['/items/b']) },
+ );
+
+ expect(result.current.isSheetOpen).toBe(true);
+
+ act(() => {
+ result.current.setSheetOpen(false);
+ });
+
+ // Parent owns the state — controller doesn't flip without a prop change.
+ expect(result.current.isSheetOpen).toBe(true);
+ // But `onOpenChange` fires so the parent can observe the request.
+ expect(onOpenChange).toHaveBeenLastCalledWith(false);
+ });
+
+ it('toggles internal state and fires onOpenChange in uncontrolled mode', () => {
+ const onOpenChange = vi.fn();
+
+ const { result } = renderHook(
+ () =>
+ useDetailNavigation
- ({
+ currentId: 'b',
+ getHref,
+ getLabel,
+ getSearchableText,
+ items: ITEMS,
+ onOpenChange,
+ }),
+ { wrapper: renderInRoute(['/items/b']) },
+ );
+
+ expect(result.current.isSheetOpen).toBe(false);
+
+ act(() => {
+ result.current.openSheet();
+ });
+
+ expect(result.current.isSheetOpen).toBe(true);
+ expect(onOpenChange).toHaveBeenLastCalledWith(true);
+
+ act(() => {
+ result.current.closeSheet();
+ });
+
+ expect(result.current.isSheetOpen).toBe(false);
+ expect(onOpenChange).toHaveBeenLastCalledWith(false);
+ });
+
+ it('honours defaultOpen=true on first render in uncontrolled mode', () => {
+ const { result } = renderHook(
+ () =>
+ useDetailNavigation
- ({
+ currentId: 'b',
+ defaultOpen: true,
+ getHref,
+ getLabel,
+ getSearchableText,
+ items: ITEMS,
+ }),
+ { wrapper: renderInRoute(['/items/b']) },
+ );
+
+ expect(result.current.isSheetOpen).toBe(true);
+ });
+});
+
+describe('useDetailNavigation — current item bookkeeping', () => {
+ it('treats a missing currentId as "no match" without throwing', () => {
+ const { result } = renderHook(
+ () =>
+ useDetailNavigation
- ({
+ currentId: undefined,
+ getHref,
+ getLabel,
+ getSearchableText,
+ items: ITEMS,
+ }),
+ { wrapper: renderInRoute(['/items/b']) },
+ );
+
+ expect(result.current.currentId).toBeNull();
+ expect(result.current.currentIndex).toBe(-1);
+ expect(result.current.filteredItems).toEqual(ITEMS);
+ });
+});
+
+describe('useDetailNavigation — navigation back to list does not leak the filter', () => {
+ it('keeps the URL `?q=` intact after a navigate inside the same router', async () => {
+ const Harness = () => {
+ const navigate = useNavigate();
+ const nav = useDetailNavigation
- ({
+ currentId: 'b',
+ getHref,
+ getLabel,
+ getSearchableText,
+ items: ITEMS,
+ });
+
+ return { nav, navigate };
+ };
+
+ const { result } = renderHook(() => Harness(), {
+ wrapper: renderInRoute(['/items/b?q=alpha']),
+ });
+
+ await waitFor(() => {
+ expect(result.current.nav.debouncedFilter).toBe('alpha');
+ });
+
+ // Navigating to another detail page should not alter the filter
+ // value the hook observes — the URL still carries it.
+ act(() => {
+ result.current.navigate('/items/a?q=alpha');
+ });
+
+ await waitFor(() => {
+ expect(result.current.nav.debouncedFilter).toBe('alpha');
+ });
+ });
+});
diff --git a/frontend/src/components/shared/detail-navigation/use-detail-navigation.ts b/frontend/src/components/shared/detail-navigation/use-detail-navigation.ts
new file mode 100644
index 00000000..fd50f2fd
--- /dev/null
+++ b/frontend/src/components/shared/detail-navigation/use-detail-navigation.ts
@@ -0,0 +1,323 @@
+import { useCallback, useMemo, useState } from 'react';
+import { useNavigate, useSearchParams } from 'react-router-dom';
+
+import { useLatestRef } from '@/hooks/use-latest-ref';
+import { usePageStorageKeys } from '@/hooks/use-page-storage-keys';
+import { useTableQueryFilterReader } from '@/hooks/use-table-query-filter';
+import { mergeHrefWithSearchParams } from '@/lib/url-params';
+
+import { useNavigation } from './use-navigation';
+
+/**
+ * Headless controller for a detail page that walks a filtered list.
+ *
+ * Owns:
+ * - the filtered/sorted subset (pure `computeNavigation`),
+ * - the resolved Prev / Next sibling ids and the pre-formatted position
+ * label (so leaf components don't recompute),
+ * - the sheet open state (controllable via `open` / `onOpenChange`),
+ * - navigation actions that thread the current `?=` into every
+ * prev / next / item-select destination.
+ *
+ * All callbacks are identity-stable across renders that don't change the
+ * inputs the action depends on — ``,
+ * ``, and any custom chrome rendered against the
+ * controller can rely on referential equality for downstream memos.
+ */
+export interface DetailNavigationController {
+ closeSheet: () => void;
+ /** Active `currentId` coerced to a string, or `null` when absent. */
+ currentId: null | string;
+ /** Index of `currentItem` inside `filteredItems`. `-1` when not in subset. */
+ currentIndex: number;
+ /** Item matching `currentId` inside the filtered subset, or `null`. */
+ currentItem: null | T;
+ /** Debounced URL filter the controller is filtering against. */
+ debouncedFilter: string;
+ /** Sorted+filtered subset that drives prev / next / sheet listing. */
+ filteredItems: readonly T[];
+ /** Stable id accessor (defaults to `item.id` when not supplied). */
+ getId: (item: T) => string;
+
+ getLabel: (item: T) => string;
+ /**
+ * Resolved haystack accessor — the caller-supplied `getSearchableText`,
+ * or `getLabel` as a fallback. Exposed for advanced consumers; leaf
+ * components don't read it because filtering already happened on the
+ * way into `filteredItems`.
+ */
+ getSearchableText: (item: T) => null | string | undefined;
+ goToNext: () => void;
+
+ goToPrev: () => void;
+ /** Navigate to the given item and close the sheet. */
+ handleItemSelect: (item: T) => void;
+ /** `true` iff `filteredItems.length > 0`. */
+ hasEntries: boolean;
+ isSheetOpen: boolean;
+
+ /**
+ * `true` iff the raw `items` array is empty (pre-filter). The convenience
+ * `` uses this to render `null` on a fresh detail
+ * mount when the provider's list hasn't arrived yet.
+ */
+ itemsEmpty: boolean;
+ /** ID of the next filtered sibling, or `null` at the end / off-subset. */
+ nextId: null | string;
+ openSheet: () => void;
+
+ /** Pre-formatted `"3/10"` or `"–/0"` for the position trigger. */
+ positionLabel: string;
+ /** ID of the previous filtered sibling, or `null` at the start / off-subset. */
+ prevId: null | string;
+ setSheetOpen: (open: boolean) => void;
+
+ /** Same as `filteredItems.length`, named explicitly for clarity. */
+ total: number;
+}
+
+/**
+ * Restricts the override to strings that start with a `/`. Pure-string types
+ * (`string`) would let an empty `""` or a bare `"flows"` slip through and
+ * either collide on the shared `filter_4_` key or generate a different slot
+ * than the actual list page. Template-literal types catch this at compile
+ * time without runtime guards.
+ */
+type ParentPath = `/${string}`;
+
+interface UseDetailNavigationOptions {
+ currentId: null | string | undefined;
+ /** Initial value for the uncontrolled case. Defaults to `false`. */
+ defaultOpen?: boolean;
+ getHref: (item: T) => string;
+ getId?: (item: T) => string;
+ getLabel: (item: T) => string;
+ getSearchableText?: (item: T) => null | string | undefined;
+ items: readonly T[];
+ onOpenChange?: (open: boolean) => void;
+
+ /**
+ * Controlled-mode opt-in for the sheet. When `open` is `undefined` the
+ * controller owns the state internally; when a value is provided the
+ * caller owns it. `onOpenChange` always fires so a fully-controlled
+ * consumer can observe every set.
+ *
+ * Mirrors the `useControllable` pattern from
+ * `@/components/ui/autocomplete.tsx`.
+ */
+ open?: boolean;
+ /**
+ * Optional override for the parent list path used to look up the shared
+ * filter storage slot. Defaults to the top-level segment of the current
+ * pathname, which works for top-level routes (`/flows`, `/templates`,
+ * `/knowledges`). Nested routes (`/admin/flows/:id`) must pass an
+ * explicit value here because the default would key into `/admin`
+ * rather than `/admin/flows`.
+ */
+ parentPath?: ParentPath;
+ sortFn?: (a: T, b: T) => number;
+}
+
+// Module-level so the reference is stable across renders. Typed against
+// the wider `{ id: string }` so it is assignable to `(item: T) => string`
+// for any `T extends { id: string }` via function-parameter contravariance
+// — no cast at the call site.
+const defaultGetId = (item: { id: string }): string => item.id;
+
+/**
+ * Build the headless `DetailNavigationController` for a detail page.
+ *
+ * Bundles the four moving parts every detail page repeats:
+ * 1. resolving the parent list's storage slot via `usePageStorageKeys`,
+ * 2. subscribing to the URL filter through `useTableQueryFilterReader`
+ * (read-only — the detail page never mutates the filter from here),
+ * 3. running the pure `useNavigation` core against the filtered subset,
+ * 4. wiring identity-stable `goToPrev` / `goToNext` / `handleItemSelect`
+ * with `?=` forwarded through `mergeHrefWithSearchParams`.
+ *
+ * The returned controller drives ``,
+ * ``, and `` (or any custom
+ * chrome a consumer wants to render). All function fields are wrapped in
+ * `useCallback` with `useLatestRef`-stabilized closures over `useSearchParams`
+ * and the caller-supplied accessors — React Router v6 returns a fresh
+ * `URLSearchParams` each render, and threading it through callback deps would
+ * defeat the entire memoization goal.
+ *
+ * Pass per-feature callbacks through `useCallback` (or, as the existing
+ * `use-flow-detail-navigation` / `use-template-detail-navigation` /
+ * `use-knowledge-detail-navigation` do, hoist them to module scope). An
+ * inline arrow would still work — `useLatestRef` reads the most recent
+ * version at fire time — but it forfeits `useNavigation`'s internal
+ * memoization on `getSearchableText`.
+ */
+export const useDetailNavigation = ({
+ currentId,
+ defaultOpen,
+ getHref,
+ getId,
+ getLabel,
+ getSearchableText,
+ items,
+ onOpenChange,
+ open,
+ parentPath,
+ sortFn,
+}: UseDetailNavigationOptions): DetailNavigationController => {
+ const navigate = useNavigate();
+ const [searchParams] = useSearchParams();
+
+ // `parentPath` is typed as `/${string}` so the empty / unprefixed case
+ // is rejected at compile time — we only need to branch on presence here.
+ const hasExplicitParentPath = parentPath !== undefined;
+ const { table: filterStorageKey } = usePageStorageKeys({
+ pathname: hasExplicitParentPath ? parentPath : undefined,
+ useTopLevel: !hasExplicitParentPath,
+ });
+ const { debouncedFilter } = useTableQueryFilterReader({ storageKey: filterStorageKey });
+
+ // Memoize so passing `getId={undefined}` keeps the reference stable when
+ // the caller re-renders for unrelated reasons. Without the memo the
+ // downstream `useNavigation` memo would invalidate on every render.
+ const resolvedGetId = useMemo<(item: T) => string>(() => getId ?? defaultGetId, [getId]);
+ const resolvedGetSearchableText = useMemo<(item: T) => null | string | undefined>(
+ () => getSearchableText ?? getLabel,
+ [getSearchableText, getLabel],
+ );
+
+ const { currentIndex, currentItem, filteredItems, nextId, prevId, total } = useNavigation({
+ currentId,
+ getId: resolvedGetId,
+ getSearchableText: resolvedGetSearchableText,
+ items,
+ query: debouncedFilter,
+ sortFn,
+ });
+
+ // Controlled-mode sheet state (mirrors `useControllable` from
+ // `components/ui/autocomplete.tsx:27-46`). When `open` is provided the
+ // caller owns the state; otherwise the controller owns it.
+ // `onOpenChange` fires on every set so fully-controlled consumers can
+ // observe transitions.
+ const onOpenChangeRef = useLatestRef(onOpenChange);
+ const [internalOpen, setInternalOpen] = useState(defaultOpen ?? false);
+ const isOpenControlled = open !== undefined;
+ const isSheetOpen = isOpenControlled ? open : internalOpen;
+
+ const setSheetOpen = useCallback(
+ (next: boolean) => {
+ if (!isOpenControlled) {
+ setInternalOpen(next);
+ }
+
+ onOpenChangeRef.current?.(next);
+ },
+ [isOpenControlled, onOpenChangeRef],
+ );
+ const openSheet = useCallback(() => setSheetOpen(true), [setSheetOpen]);
+ const closeSheet = useCallback(() => setSheetOpen(false), [setSheetOpen]);
+
+ // `useSearchParams` from React Router v6 returns a fresh `URLSearchParams`
+ // every render. Threading it (or any caller-supplied accessor that might
+ // not be stable) through `useCallback` deps would invalidate every
+ // navigation callback on every render. Stash through `useLatestRef` and
+ // read at fire-time instead — handlers fire from user clicks / keyboard
+ // events, so the one-commit lag documented on `useLatestRef` never bites.
+ const searchParamsRef = useLatestRef(searchParams);
+ const getHrefRef = useLatestRef(getHref);
+ const getIdRef = useLatestRef(resolvedGetId);
+ const filteredItemsRef = useLatestRef(filteredItems);
+
+ const buildHref = useCallback(
+ (item: T) => mergeHrefWithSearchParams(getHrefRef.current(item), searchParamsRef.current),
+ [getHrefRef, searchParamsRef],
+ );
+
+ const handleItemSelect = useCallback(
+ (item: T) => {
+ // Close the sheet *before* navigating — preserves the pre-refactor
+ // ordering so a route change can't unmount the sheet while its
+ // close callback is still in flight.
+ setSheetOpen(false);
+ navigate(buildHref(item), { replace: true });
+ },
+ [buildHref, navigate, setSheetOpen],
+ );
+
+ const goTo = useCallback(
+ (id: null | string) => {
+ if (!id) {
+ return;
+ }
+
+ const target = filteredItemsRef.current.find((item) => String(getIdRef.current(item)) === id);
+
+ if (!target) {
+ return;
+ }
+
+ navigate(buildHref(target), { replace: true });
+ },
+ [buildHref, filteredItemsRef, getIdRef, navigate],
+ );
+
+ const goToPrev = useCallback(() => goTo(prevId), [goTo, prevId]);
+ const goToNext = useCallback(() => goTo(nextId), [goTo, nextId]);
+
+ const positionLabel = useMemo(
+ () => (total === 0 || currentIndex === -1 ? `–/${total}` : `${currentIndex + 1}/${total}`),
+ [currentIndex, total],
+ );
+
+ const normalizedCurrentId = currentId != null ? String(currentId) : null;
+ const hasEntries = filteredItems.length > 0;
+ const itemsEmpty = items.length === 0;
+
+ return useMemo>(
+ () => ({
+ closeSheet,
+ currentId: normalizedCurrentId,
+ currentIndex,
+ currentItem,
+ debouncedFilter,
+ filteredItems,
+ getId: resolvedGetId,
+ getLabel,
+ getSearchableText: resolvedGetSearchableText,
+ goToNext,
+ goToPrev,
+ handleItemSelect,
+ hasEntries,
+ isSheetOpen,
+ itemsEmpty,
+ nextId,
+ openSheet,
+ positionLabel,
+ prevId,
+ setSheetOpen,
+ total,
+ }),
+ [
+ closeSheet,
+ normalizedCurrentId,
+ currentIndex,
+ currentItem,
+ debouncedFilter,
+ filteredItems,
+ resolvedGetId,
+ getLabel,
+ resolvedGetSearchableText,
+ goToNext,
+ goToPrev,
+ handleItemSelect,
+ hasEntries,
+ isSheetOpen,
+ itemsEmpty,
+ nextId,
+ openSheet,
+ positionLabel,
+ prevId,
+ setSheetOpen,
+ total,
+ ],
+ );
+};
diff --git a/frontend/src/components/shared/detail-navigation/use-navigation.test.ts b/frontend/src/components/shared/detail-navigation/use-navigation.test.ts
new file mode 100644
index 00000000..f666cd41
--- /dev/null
+++ b/frontend/src/components/shared/detail-navigation/use-navigation.test.ts
@@ -0,0 +1,280 @@
+import { describe, expect, it } from 'vitest';
+
+import { computeNavigation } from './use-navigation';
+
+interface Row {
+ id: string;
+ title: string;
+}
+
+const getId = (row: Row) => row.id;
+const getTitle = (row: Row) => row.title;
+
+const ROWS: readonly Row[] = [
+ { id: 'a', title: 'Alpha' },
+ { id: 'b', title: 'Bravo' },
+ { id: 'c', title: 'Charlie' },
+ { id: 'd', title: 'Delta' },
+] as const;
+
+describe('computeNavigation', () => {
+ it('returns prev/next neighbours for a middle item', () => {
+ const result = computeNavigation({
+ currentId: 'c',
+ getId,
+ items: ROWS,
+ });
+
+ expect(result.currentIndex).toBe(2);
+ expect(result.prevId).toBe('b');
+ expect(result.nextId).toBe('d');
+ expect(result.total).toBe(4);
+ });
+
+ it('returns null prev for the first item', () => {
+ const result = computeNavigation({
+ currentId: 'a',
+ getId,
+ items: ROWS,
+ });
+
+ expect(result.currentIndex).toBe(0);
+ expect(result.prevId).toBeNull();
+ expect(result.nextId).toBe('b');
+ });
+
+ it('returns null next for the last item', () => {
+ const result = computeNavigation({
+ currentId: 'd',
+ getId,
+ items: ROWS,
+ });
+
+ expect(result.currentIndex).toBe(3);
+ expect(result.prevId).toBe('c');
+ expect(result.nextId).toBeNull();
+ });
+
+ it('reports currentIndex=-1 when the current item is missing from the filtered subset', () => {
+ const result = computeNavigation({
+ currentId: 'zzz',
+ getId,
+ items: ROWS,
+ });
+
+ expect(result.currentIndex).toBe(-1);
+ expect(result.currentItem).toBeNull();
+ expect(result.prevId).toBeNull();
+ expect(result.nextId).toBeNull();
+ expect(result.total).toBe(4);
+ });
+
+ it('reports currentIndex=-1 when currentId is null or undefined', () => {
+ const nullResult = computeNavigation({
+ currentId: null,
+ getId,
+ items: ROWS,
+ });
+
+ expect(nullResult.currentIndex).toBe(-1);
+ expect(nullResult.prevId).toBeNull();
+ expect(nullResult.nextId).toBeNull();
+
+ const undefinedResult = computeNavigation({
+ currentId: undefined,
+ getId,
+ items: ROWS,
+ });
+
+ expect(undefinedResult.currentIndex).toBe(-1);
+ });
+
+ it('honours `query` when narrowing the subset', () => {
+ const result = computeNavigation({
+ currentId: 'c',
+ getId,
+ getSearchableText: getTitle,
+ items: ROWS,
+ // Substring "c" matches "Charlie" (case-insensitive).
+ query: 'c',
+ });
+
+ expect(result.filteredItems.map(getId)).toEqual(['c']);
+ expect(result.currentIndex).toBe(0);
+ expect(result.prevId).toBeNull();
+ expect(result.nextId).toBeNull();
+ expect(result.total).toBe(1);
+ });
+
+ it('drops the current item from the result when it does not match the query', () => {
+ const result = computeNavigation({
+ currentId: 'a',
+ getId,
+ getSearchableText: getTitle,
+ items: ROWS,
+ query: 'Bravo',
+ });
+
+ expect(result.filteredItems.map(getId)).toEqual(['b']);
+ expect(result.currentIndex).toBe(-1);
+ expect(result.prevId).toBeNull();
+ expect(result.nextId).toBeNull();
+ });
+
+ it('treats an empty/undefined query as "no filter" even when getSearchableText is provided', () => {
+ const empty = computeNavigation({
+ currentId: 'c',
+ getId,
+ getSearchableText: getTitle,
+ items: ROWS,
+ query: '',
+ });
+
+ expect(empty.filteredItems.map(getId)).toEqual(['a', 'b', 'c', 'd']);
+
+ const missing = computeNavigation({
+ currentId: 'c',
+ getId,
+ getSearchableText: getTitle,
+ items: ROWS,
+ });
+
+ expect(missing.filteredItems.map(getId)).toEqual(['a', 'b', 'c', 'd']);
+ });
+
+ it('skips filtering silently when query is non-empty but getSearchableText is missing', () => {
+ // Documents the boundary: without a haystack accessor we cannot evaluate
+ // the query against rows, so we degrade to "no filter" instead of
+ // throwing — keeps the hook usable while a caller forgets to wire one up.
+ const result = computeNavigation({
+ currentId: 'c',
+ getId,
+ items: ROWS,
+ query: 'pha',
+ });
+
+ expect(result.filteredItems.map(getId)).toEqual(['a', 'b', 'c', 'd']);
+ });
+
+ it('preserves input order when no sortFn is provided', () => {
+ const reversed = [...ROWS].reverse();
+ const result = computeNavigation({
+ currentId: 'c',
+ getId,
+ items: reversed,
+ });
+
+ expect(result.filteredItems.map(getId)).toEqual(['d', 'c', 'b', 'a']);
+ expect(result.currentIndex).toBe(1);
+ expect(result.prevId).toBe('d');
+ expect(result.nextId).toBe('b');
+ });
+
+ it('applies sortFn to the filtered subset', () => {
+ const result = computeNavigation({
+ currentId: 'b',
+ getId,
+ items: ROWS,
+ sortFn: (a, b) => b.title.localeCompare(a.title),
+ });
+
+ expect(result.filteredItems.map(getId)).toEqual(['d', 'c', 'b', 'a']);
+ expect(result.currentIndex).toBe(2);
+ expect(result.prevId).toBe('c');
+ expect(result.nextId).toBe('a');
+ });
+
+ it('handles an empty items array', () => {
+ const result = computeNavigation({
+ currentId: 'anything',
+ getId,
+ items: [],
+ });
+
+ expect(result.filteredItems).toEqual([]);
+ expect(result.total).toBe(0);
+ expect(result.currentIndex).toBe(-1);
+ expect(result.prevId).toBeNull();
+ expect(result.nextId).toBeNull();
+ });
+
+ it('returns the current item when present', () => {
+ const result = computeNavigation({
+ currentId: 'c',
+ getId,
+ items: ROWS,
+ });
+
+ expect(result.currentItem).toEqual({ id: 'c', title: 'Charlie' });
+ });
+
+ it('does not mutate the input array even when sorting', () => {
+ const before = ROWS.map(getId);
+ computeNavigation({
+ currentId: 'a',
+ getId,
+ items: ROWS,
+ sortFn: (a, b) => b.title.localeCompare(a.title),
+ });
+
+ expect(ROWS.map(getId)).toEqual(before);
+ });
+
+ it('handles "item deleted, currentId still points to it"', () => {
+ // The user was viewing item `b`, then `b` was deleted (removed from
+ // `items`) — currentId stays `b` until the route updates. The hook
+ // must surface this as currentIndex=-1 / no neighbours so the UI
+ // disables Prev/Next rather than jumping to an unrelated row.
+ const trimmed = ROWS.filter((row) => row.id !== 'b');
+ const result = computeNavigation({
+ currentId: 'b',
+ getId,
+ items: trimmed,
+ });
+
+ expect(result.filteredItems.map(getId)).toEqual(['a', 'c', 'd']);
+ expect(result.currentIndex).toBe(-1);
+ expect(result.prevId).toBeNull();
+ expect(result.nextId).toBeNull();
+ expect(result.total).toBe(3);
+ });
+
+ it('folds diacritics + case the same way the list filter does', () => {
+ const accented: readonly Row[] = [
+ { id: '1', title: 'Café' },
+ { id: '2', title: 'naïve' },
+ { id: '3', title: 'resume' },
+ ];
+
+ const result = computeNavigation({
+ currentId: '1',
+ getId,
+ getSearchableText: getTitle,
+ items: accented,
+ query: 'cafe',
+ });
+
+ expect(result.filteredItems.map(getId)).toEqual(['1']);
+ expect(result.currentIndex).toBe(0);
+ });
+
+ it('matches numeric item ids with string currentId', () => {
+ type NumRow = { id: number; title: string };
+ const rows: readonly NumRow[] = [
+ { id: 10, title: 'A' },
+ { id: 20, title: 'B' },
+ { id: 30, title: 'C' },
+ ];
+ const getNumericId = (row: NumRow) => String(row.id);
+
+ const result = computeNavigation({
+ currentId: '20',
+ getId: getNumericId,
+ items: rows,
+ });
+
+ expect(result.currentIndex).toBe(1);
+ expect(result.prevId).toBe('10');
+ expect(result.nextId).toBe('30');
+ });
+});
diff --git a/frontend/src/components/shared/detail-navigation/use-navigation.ts b/frontend/src/components/shared/detail-navigation/use-navigation.ts
new file mode 100644
index 00000000..3c46bcbc
--- /dev/null
+++ b/frontend/src/components/shared/detail-navigation/use-navigation.ts
@@ -0,0 +1,145 @@
+import { useMemo } from 'react';
+
+import { createTextMatcher } from './text-filter';
+
+interface NavigationInput {
+ currentId: null | string | undefined;
+ getId: (item: T) => string;
+ /**
+ * Optional accessor for the text the filter runs against. Only consulted
+ * when `query` is non-empty — pages with no filter don't need it.
+ */
+ getSearchableText?: (item: T) => null | string | undefined;
+ items: readonly T[];
+ /**
+ * Free-text filter to narrow the navigable subset. Empty / `undefined` is
+ * treated as "no filter" and every item passes. Matching reuses
+ * `createTextMatcher`, so behaviour matches the list page's column
+ * filter (substring, case + diacritic insensitive).
+ */
+ query?: string;
+ sortFn?: (a: T, b: T) => number;
+}
+
+interface NavigationResult {
+ currentIndex: number;
+ currentItem: null | T;
+ filteredItems: readonly T[];
+ nextId: null | string;
+ prevId: null | string;
+ total: number;
+}
+
+/**
+ * Pure core of {@link useNavigation}: filter, sort, and resolve Prev/Next
+ * around `currentId`. Exposed without React so the algorithm can be
+ * unit-tested directly — the hook is a thin `useMemo` wrapper around this.
+ *
+ * The Map of `id → index` is built once per invocation so the `currentId`
+ * lookup is O(1) instead of an `Array.find` per render. The map is
+ * intentionally not exposed — callers should walk `filteredItems` or use the
+ * returned `prevId` / `nextId`.
+ */
+export const computeNavigation = ({
+ currentId,
+ getId,
+ getSearchableText,
+ items,
+ query,
+ sortFn,
+}: NavigationInput): NavigationResult => {
+ const hasQuery = query !== undefined && query.length > 0;
+ const filtered =
+ hasQuery && getSearchableText
+ ? items.filter((item) => createTextMatcher(query)(getSearchableText(item)))
+ : items;
+ const ordered = sortFn ? [...filtered].sort(sortFn) : filtered;
+
+ const indexById = new Map();
+
+ ordered.forEach((item, index) => {
+ // Apollo commonly hydrates GraphQL `ID` fields as numbers even though
+ // route params are strings — normalize so lookups stay stable.
+ indexById.set(String(getId(item)), index);
+ });
+
+ const currentIndex = currentId != null ? (indexById.get(String(currentId)) ?? -1) : -1;
+
+ if (currentIndex === -1) {
+ return {
+ currentIndex: -1,
+ currentItem: null,
+ filteredItems: ordered,
+ nextId: null,
+ prevId: null,
+ total: ordered.length,
+ };
+ }
+
+ const prevItem = currentIndex > 0 ? ordered[currentIndex - 1] : null;
+ const nextItem = currentIndex < ordered.length - 1 ? ordered[currentIndex + 1] : null;
+
+ return {
+ currentIndex,
+ currentItem: ordered[currentIndex] ?? null,
+ filteredItems: ordered,
+ nextId: nextItem ? String(getId(nextItem)) : null,
+ prevId: prevItem ? String(getId(prevItem)) : null,
+ total: ordered.length,
+ };
+};
+
+interface UseNavigationOptions {
+ currentId: null | string | undefined;
+ getId: (item: T) => string;
+ /**
+ * Accessor for the text the filter runs against. Only required when
+ * `query` is non-empty.
+ */
+ getSearchableText?: (item: T) => null | string | undefined;
+ items: readonly T[];
+ /** Free-text filter. Empty / `undefined` → unfiltered. */
+ query?: string;
+ /**
+ * Optional comparator. When omitted, the input array order is preserved —
+ * the navigation walks `items` exactly as the caller arranged them, which
+ * matches what list pages already render.
+ */
+ sortFn?: (a: T, b: T) => number;
+}
+
+type UseNavigationResult = NavigationResult;
+
+/**
+ * Resolve Prev/Next siblings for a detail page that's tied to a filtered list.
+ *
+ * The list page holds the same `items` and free-text `query`, so this hook
+ * produces the same ordering as what the user sees in the table — Prev/Next
+ * stays in lockstep with the filter even after the user lands on a detail
+ * URL via a shared link.
+ *
+ * If the current item is missing from the filtered subset (deleted, or no
+ * longer matches the filter), `currentIndex` is `-1` and both `prevId` /
+ * `nextId` are `null` — the caller renders disabled Prev/Next buttons in that
+ * case rather than navigating into an unrelated neighbour.
+ *
+ * Callers pass *data* (`query`, `getSearchableText`) rather than a prebuilt
+ * predicate. That removes the identity-stability footgun the predicate-based
+ * shape had: a fresh-arrow `(item) => …` callback every render would have
+ * defeated the internal `useMemo`. With this shape, only `query` flips per
+ * keystroke, and `getSearchableText` is naturally module-scoped at the
+ * feature level (see `use-flow-detail-navigation` etc.).
+ */
+export const useNavigation = ({
+ currentId,
+ getId,
+ getSearchableText,
+ items,
+ query,
+ sortFn,
+}: UseNavigationOptions): UseNavigationResult => {
+ return useMemo(
+ () => computeNavigation({ currentId, getId, getSearchableText, items, query, sortFn }),
+ [currentId, getId, getSearchableText, items, query, sortFn],
+ );
+};
diff --git a/frontend/src/components/shared/file-manager/file-manager-types.ts b/frontend/src/components/shared/file-manager/file-manager-types.ts
index 4124cd6c..47cc7c7d 100644
--- a/frontend/src/components/shared/file-manager/file-manager-types.ts
+++ b/frontend/src/components/shared/file-manager/file-manager-types.ts
@@ -310,7 +310,7 @@ export interface FileManagerProps {
/**
* When set, the active sort is persisted to `localStorage` under this key
* across page reloads. Ignored in controlled mode (when `sorting` is set).
- * Pass a route-scoped key (e.g. `getSortingStorageKey('/flows/files')`)
+ * Pass a route-scoped key (e.g. `getTableStorageKey('/flows/files')`)
* to avoid collisions across pages.
*/
sortStorageKey?: string;
diff --git a/frontend/src/components/shared/header-button.tsx b/frontend/src/components/shared/header-button.tsx
new file mode 100644
index 00000000..402b111b
--- /dev/null
+++ b/frontend/src/components/shared/header-button.tsx
@@ -0,0 +1,37 @@
+import { forwardRef, type ReactNode } from 'react';
+
+import { Button, type ButtonProps } from '@/components/ui/button';
+import { cn } from '@/lib/utils';
+
+interface HeaderButtonProps extends Omit {
+ endIcon?: ReactNode;
+ icon: ReactNode;
+ label: ReactNode;
+}
+
+// Action button rendered inside a page header. Collapses to an icon-only square
+// on viewports narrower than the `md` breakpoint (matches `useBreakpoint`'s
+// `mobile` threshold of 768px) and expands to icon + label (and optional
+// trailing icon, e.g. a dropdown chevron) on wider screens. `aria-label` is
+// auto-derived from `label` when it's a plain string so the icon-only mobile
+// state stays accessible without the caller having to remember it.
+export const HeaderButton = forwardRef(
+ ({ 'aria-label': ariaLabel, className, endIcon, icon, label, size = 'sm', ...props }, ref) => {
+ const accessibleLabel = ariaLabel ?? (typeof label === 'string' ? label : undefined);
+
+ return (
+
+ );
+ },
+);
+HeaderButton.displayName = 'HeaderButton';
diff --git a/frontend/src/components/shared/inline-edit/index.ts b/frontend/src/components/shared/inline-edit/index.ts
new file mode 100644
index 00000000..1c809b78
--- /dev/null
+++ b/frontend/src/components/shared/inline-edit/index.ts
@@ -0,0 +1,2 @@
+export { InlineEditInput } from './inline-edit-input';
+export { useInlineEdit } from './use-inline-edit';
diff --git a/frontend/src/components/shared/inline-edit/inline-edit-input.tsx b/frontend/src/components/shared/inline-edit/inline-edit-input.tsx
new file mode 100644
index 00000000..bee5a60f
--- /dev/null
+++ b/frontend/src/components/shared/inline-edit/inline-edit-input.tsx
@@ -0,0 +1,113 @@
+import { Check, Loader2, X } from 'lucide-react';
+import { type KeyboardEvent, type Ref } from 'react';
+
+import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput } from '@/components/ui/input-group';
+import { cn } from '@/lib/utils';
+
+interface InlineEditInputProps {
+ /**
+ * Auto-focus the input on mount. Needed for table-cell call sites that
+ * switch into edit mode in-place: the parent flips a flag (e.g.
+ * `editingFlowId === flow.id`) and this component is freshly mounted,
+ * so focus must be requested explicitly.
+ */
+ autoFocus?: boolean;
+ /** Disable input + Save button while a mutation is in flight. */
+ busy?: boolean;
+ /** Optional className passed through to the outer ``. */
+ className?: string;
+ /** Initial value rendered inside the uncontrolled input. */
+ defaultValue?: string;
+ /** Ref to the underlying `` element. Pair with `useInlineEdit().inputRef`. */
+ inputRef?: Ref;
+ /**
+ * Max length applied via the native HTML `maxLength` attribute. Defaults
+ * to a UX-safe `200` to prevent accidental paste-bombs that would break
+ * truncation in tables and breadcrumbs. Override per call site when a
+ * stricter or looser constraint applies; the browser silently stops
+ * typing past the limit without altering programmatically-set
+ * `defaultValue`, so this is a guard rather than a validation gate.
+ */
+ maxLength?: number;
+ onCancel: () => void;
+ /**
+ * Save handler. Read the latest text from the bound `inputRef` — kept
+ * uncontrolled because most callers commit on Enter or click and have
+ * no need to reflect every keystroke into React state.
+ */
+ onSave: () => void;
+ placeholder?: string;
+}
+
+/**
+ * Generic inline-edit input used inside table cells and detail-page
+ * breadcrumbs (rename flows, quick-create entries, in-place note edits).
+ *
+ * Pairs with {@link useInlineEdit} — the parent owns the open/close state
+ * and supplies a ref via that hook; this component owns the presentation
+ * (input + Save/Cancel addon buttons), keyboard semantics (`Enter` saves,
+ * `Escape` cancels), and the loading spinner during save.
+ *
+ * The input is uncontrolled (`defaultValue`) to match the pattern across
+ * the codebase: callers read the value at submit time from `inputRef.current`,
+ * not from React state, which avoids a re-render per keystroke for a value
+ * that's only relevant once.
+ */
+export const InlineEditInput = ({
+ autoFocus = false,
+ busy = false,
+ className,
+ defaultValue,
+ inputRef,
+ maxLength = 200,
+ onCancel,
+ onSave,
+ placeholder,
+}: InlineEditInputProps) => {
+ const handleKeyDown = (event: KeyboardEvent) => {
+ if (event.key === 'Enter') {
+ event.preventDefault();
+ onSave();
+
+ return;
+ }
+
+ if (event.key === 'Escape') {
+ event.preventDefault();
+ onCancel();
+ }
+ };
+
+ return (
+
+
+
+
+ {busy ? : }
+
+
+
+
+
+
+ );
+};
diff --git a/frontend/src/components/shared/inline-edit/use-inline-edit.test.tsx b/frontend/src/components/shared/inline-edit/use-inline-edit.test.tsx
new file mode 100644
index 00000000..e50e505f
--- /dev/null
+++ b/frontend/src/components/shared/inline-edit/use-inline-edit.test.tsx
@@ -0,0 +1,136 @@
+import { act, renderHook } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { useInlineEdit } from './use-inline-edit';
+
+describe('useInlineEdit', () => {
+ it('starts in non-editing state', () => {
+ const { result } = renderHook(() => useInlineEdit({ resetKey: 'a' }));
+ expect(result.current.isEditing).toBe(false);
+ });
+
+ it('startEdit flips to editing, stopEdit flips back', () => {
+ const { result } = renderHook(() => useInlineEdit({ resetKey: 'a' }));
+
+ act(() => result.current.startEdit());
+ expect(result.current.isEditing).toBe(true);
+
+ act(() => result.current.stopEdit());
+ expect(result.current.isEditing).toBe(false);
+ });
+
+ it('exits edit mode when resetKey changes', () => {
+ const { rerender, result } = renderHook(({ resetKey }) => useInlineEdit({ resetKey }), {
+ initialProps: { resetKey: 'a' as null | string | undefined },
+ });
+
+ act(() => result.current.startEdit());
+ expect(result.current.isEditing).toBe(true);
+
+ rerender({ resetKey: 'b' });
+ expect(result.current.isEditing).toBe(false);
+ });
+
+ it('keeps edit mode across rerenders with the same resetKey', () => {
+ const { rerender, result } = renderHook(({ resetKey }) => useInlineEdit({ resetKey }), {
+ initialProps: { resetKey: 'a' as null | string | undefined },
+ });
+
+ act(() => result.current.startEdit());
+ rerender({ resetKey: 'a' });
+ expect(result.current.isEditing).toBe(true);
+ });
+
+ it('treats `null` and `undefined` as distinct keys (state reset on transition)', () => {
+ const { rerender, result } = renderHook(({ resetKey }) => useInlineEdit({ resetKey }), {
+ initialProps: { resetKey: null as null | string | undefined },
+ });
+
+ act(() => result.current.startEdit());
+
+ // Transition null -> undefined trips the reset because they aren't
+ // strictly equal. Documenting this so callers know to keep the
+ // resetKey type stable.
+ rerender({ resetKey: undefined });
+ expect(result.current.isEditing).toBe(false);
+ });
+
+ it('returns a ref object whose .current starts at null', () => {
+ const { result } = renderHook(() => useInlineEdit({ resetKey: 'a' }));
+ expect(result.current.inputRef.current).toBeNull();
+ });
+
+ it('handleDropdownCloseAutoFocus prevents default while editing', () => {
+ const { result } = renderHook(() => useInlineEdit({ resetKey: 'a' }));
+
+ act(() => result.current.startEdit());
+
+ // `Event` is cancelable by default but `defaultPrevented` only flips
+ // once `preventDefault` is called — exactly what the hook does.
+ const event = new Event('autofocus', { cancelable: true });
+ result.current.handleDropdownCloseAutoFocus(event);
+
+ expect(event.defaultPrevented).toBe(true);
+ });
+
+ it('handleDropdownCloseAutoFocus is a no-op when not editing', () => {
+ const { result } = renderHook(() => useInlineEdit({ resetKey: 'a' }));
+
+ const event = new Event('autofocus', { cancelable: true });
+ result.current.handleDropdownCloseAutoFocus(event);
+
+ expect(event.defaultPrevented).toBe(false);
+ });
+
+ it('focuses and selects the input on the next animation frame after startEdit', async () => {
+ const { result } = renderHook(() => useInlineEdit({ resetKey: 'a' }));
+
+ const input = document.createElement('input');
+ input.value = 'hello';
+ document.body.appendChild(input);
+
+ // Attach the ref manually — `useRef` exposes `.current` as writable
+ // even though TypeScript narrows it to readonly. Casting through
+ // an interface keeps the intent visible in the test.
+ (result.current.inputRef as unknown as { current: HTMLInputElement }).current = input;
+
+ act(() => result.current.startEdit());
+
+ // requestAnimationFrame in jsdom resolves in a microtask — wait for it.
+ await act(async () => {
+ await new Promise((resolve) => requestAnimationFrame(() => resolve(null)));
+ });
+
+ expect(document.activeElement).toBe(input);
+ expect(input.selectionStart).toBe(0);
+ expect(input.selectionEnd).toBe(input.value.length);
+
+ document.body.removeChild(input);
+ });
+
+ it('cancels the pending focus when isEditing flips off before the frame fires', async () => {
+ const { result } = renderHook(() => useInlineEdit({ resetKey: 'a' }));
+
+ const input = document.createElement('input');
+ document.body.appendChild(input);
+ (result.current.inputRef as unknown as { current: HTMLInputElement }).current = input;
+
+ const otherInput = document.createElement('input');
+ document.body.appendChild(otherInput);
+ otherInput.focus();
+
+ act(() => result.current.startEdit());
+ act(() => result.current.stopEdit());
+
+ await act(async () => {
+ await new Promise((resolve) => requestAnimationFrame(() => resolve(null)));
+ });
+
+ // Focus must not have moved to the inline input — the effect cleanup
+ // cancelled the rAF before it ran.
+ expect(document.activeElement).toBe(otherInput);
+
+ document.body.removeChild(input);
+ document.body.removeChild(otherInput);
+ });
+});
diff --git a/frontend/src/components/shared/inline-edit/use-inline-edit.ts b/frontend/src/components/shared/inline-edit/use-inline-edit.ts
new file mode 100644
index 00000000..c3a051b9
--- /dev/null
+++ b/frontend/src/components/shared/inline-edit/use-inline-edit.ts
@@ -0,0 +1,112 @@
+import type React from 'react';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+interface UseInlineEditOptions {
+ /**
+ * When this value changes, the edit session is reset (closes any open
+ * input). Use it for the entity id that owns the editor — navigating
+ * between items should not carry a stale draft over.
+ */
+ resetKey?: null | string | undefined;
+}
+
+interface UseInlineEditResult {
+ /**
+ * Spread onto a Radix `` (or any component with the
+ * same `onCloseAutoFocus` semantics) when the dropdown contains a button
+ * that toggles the inline editor. Prevents Radix's default focus-restore
+ * from racing the editor's `requestAnimationFrame`-driven focus below.
+ */
+ handleDropdownCloseAutoFocus: (event: Event) => void;
+ /** Ref to wire to the inline `` element. */
+ inputRef: React.RefObject;
+ isEditing: boolean;
+ /** Begin an inline edit — the input mounts and receives focus on next frame. */
+ startEdit: () => void;
+ /** End the edit session without committing. */
+ stopEdit: () => void;
+}
+
+/**
+ * Shared state machine for inline-edit surfaces (double-click to rename,
+ * quick-add, in-place note edits).
+ *
+ * Combines four micro-responsibilities that every editable surface needs:
+ * - `isEditing` boolean + start/stop helpers,
+ * - a ref for the inline input,
+ * - deferred focus + select-all on the next animation frame, so the focus
+ * lands *after* Radix's dropdown close-focus-restore completes (otherwise
+ * Radix wins the race and the input never receives focus),
+ * - an `onCloseAutoFocus` handler that opts out of Radix's restore while
+ * editing — used together with the deferred focus above.
+ *
+ * Pass the entity id as `resetKey` so navigation between items closes any
+ * stale editor automatically.
+ */
+export const useInlineEdit = ({
+ resetKey,
+}: UseInlineEditOptions = {}): UseInlineEditResult => {
+ const [isEditing, setIsEditing] = useState(false);
+ const inputRef = useRef(null);
+
+ // Reset the edit session when `resetKey` changes. React docs call out
+ // "adjust state when a prop changes" as the canonical render-phase
+ // `setState` pattern — it's preferred over `useEffect` because the new
+ // state lands in the same commit (no flash of stale "still editing" UI
+ // on the new item) and it doesn't trigger the "cascading renders"
+ // lint complaint that an effect-based reset would.
+ const [lastResetKey, setLastResetKey] = useState(resetKey);
+
+ if (lastResetKey !== resetKey) {
+ setLastResetKey(resetKey);
+
+ if (isEditing) {
+ setIsEditing(false);
+ }
+ }
+
+ useEffect(() => {
+ if (!isEditing) {
+ return;
+ }
+
+ const id = requestAnimationFrame(() => {
+ const input = inputRef.current;
+
+ if (!input) {
+ return;
+ }
+
+ input.focus();
+
+ // `` and `