Skip to content

Fully autonomous AI Agents system capable of performing complex penetration testing tasks

refactor(frontend): headless controller for DetailNavigation

Sergey Kozyrenko7dae4be61d3e
diff --git a/frontend/src/components/shared/detail-navigation/detail-navigation-buttons.tsx b/frontend/src/components/shared/detail-navigation/detail-navigation-buttons.tsx
index 323a601c..04608860 100644
--- a/frontend/src/components/shared/detail-navigation/detail-navigation-buttons.tsx
+++ b/frontend/src/components/shared/detail-navigation/detail-navigation-buttons.tsx
@@ -2,43 +2,40 @@ import { ChevronLeft, ChevronRight } from 'lucide-react';
import { Button } from '@/components/ui/button';
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
+import { cn } from '@/lib/utils';
-interface DetailNavigationButtonsProps {
- /** Disable the position-button when the filtered subset is empty. */
- hasEntries: boolean;
- /** No next sibling — disable the right chevron. */
- nextDisabled: boolean;
- onNext: () => void;
- onOpen: () => void;
- onPrev: () => void;
- /** Pre-formatted `"3/10"` (or `"–/0"` when no current). */
- positionLabel: string;
- /** No previous sibling — disable the left chevron. */
- prevDisabled: boolean;
+import type { DetailNavigationController } from './use-detail-navigation';
+
+interface DetailNavigationButtonsProps<T extends { id: string }> {
+ controller: DetailNavigationController<T>;
/** Lowercased plural used in the aria-label / tooltip ("flows", "templates"). */
sheetTitle: string;
+ /**
+ * Size variant. `'default'` is the desktop toolbar's `size-8` cluster;
+ * `'sm'` shrinks the cluster to `size-7` for embedding inside a
+ * `<DropdownMenuItem>` on mobile, where the host row is already padded.
+ */
+ size?: 'default' | 'sm';
}
/**
- * Prev / Position / Next button cluster for a detail page. Stateless and
- * presentation-only — `DetailNavigationToolbar` owns the navigation logic
- * and feeds the resolved indices, labels, and click handlers down.
+ * Prev / Position / Next button cluster bound to a `DetailNavigationController`.
+ * Stateless: the controller owns navigation, `isSheetOpen`, and the
+ * pre-formatted `positionLabel`.
*
- * Kept separate from `DetailNavigationSheet` so the same buttons could in
- * principle be reused without the sheet (e.g. a future variant that ships
- * keyboard-only navigation without an overlay).
+ * Reused in both the desktop toolbar (`size="default"`) and the mobile
+ * dropdown row (`size="sm"`) — same a11y contract, same tooltips, same
+ * keyboard semantics in both places.
*/
-export const DetailNavigationButtons = ({
- hasEntries,
- nextDisabled,
- onNext,
- onOpen,
- onPrev,
- positionLabel,
- prevDisabled,
+export const DetailNavigationButtons = <T extends { id: string }>({
+ controller,
sheetTitle,
-}: DetailNavigationButtonsProps) => {
+ size = 'default',
+}: DetailNavigationButtonsProps<T>) => {
const lowerTitle = sheetTitle.toLowerCase();
+ const isSm = size === 'sm';
+ const sideButtonSize = isSm ? 'size-7' : 'size-8';
+ const middleHeight = isSm ? 'h-7' : 'h-8';
return (
<div className="flex items-center">
@@ -46,9 +43,9 @@ export const DetailNavigationButtons = ({
<TooltipTrigger asChild>
<Button
aria-label="Previous"
- className="size-8 rounded-r-none border-r-0 p-0"
- disabled={prevDisabled}
- onClick={onPrev}
+ className={cn(sideButtonSize, 'rounded-r-none border-r-0 p-0')}
+ disabled={!controller.prevId}
+ onClick={controller.goToPrev}
size="icon"
variant="outline"
>
@@ -60,13 +57,13 @@ export const DetailNavigationButtons = ({
<Tooltip>
<TooltipTrigger asChild>
<Button
- aria-label={`Open ${lowerTitle} list (${positionLabel})`}
- className="h-8 min-w-12 rounded-none border-x px-2 font-mono text-xs tabular-nums"
- disabled={!hasEntries}
- onClick={onOpen}
+ aria-label={`Open ${lowerTitle} list (${controller.positionLabel})`}
+ className={cn(middleHeight, 'min-w-12 rounded-none border-x px-2 font-mono text-xs tabular-nums')}
+ disabled={!controller.hasEntries}
+ onClick={controller.openSheet}
variant="outline"
>
- {positionLabel}
+ {controller.positionLabel}
</Button>
</TooltipTrigger>
<TooltipContent>Show all matching {lowerTitle}</TooltipContent>
@@ -75,9 +72,9 @@ export const DetailNavigationButtons = ({
<TooltipTrigger asChild>
<Button
aria-label="Next"
- className="size-8 rounded-l-none border-l-0 p-0"
- disabled={nextDisabled}
- onClick={onNext}
+ className={cn(sideButtonSize, 'rounded-l-none border-l-0 p-0')}
+ disabled={!controller.nextId}
+ onClick={controller.goToNext}
size="icon"
variant="outline"
>
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 (
+ <span data-testid="location">
+ {pathname}
+ {search}
+ </span>
+ );
+};
+
+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<Item>({
+ currentId,
+ defaultOpen: true,
+ getHref,
+ getLabel,
+ getSearchableText,
+ items,
+ });
+
+ return (
+ <DetailNavigationSheet<Item>
+ controller={nav}
+ sheetTitle="Items"
+ />
+ );
+};
+
+const renderSheet = (props: HarnessProps = {}) => {
+ const filter = props.filter ?? '';
+ const initialId = props.currentId ?? 'c';
+
+ const Wrapper = ({ children }: { children: ReactNode }) => (
+ <MemoryRouter initialEntries={[`/items/${initialId}?q=${filter}`]}>
+ <TooltipProvider>
+ <LocationReadout />
+ <Routes>
+ <Route
+ element={<>{children}</>}
+ path="/items/:id"
+ />
+ </Routes>
+ </TooltipProvider>
+ </MemoryRouter>
+ );
+
+ return render(<SheetHarness {...props} />, { 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
index 9eb54a56..49c176cc 100644
--- a/frontend/src/components/shared/detail-navigation/detail-navigation-sheet.tsx
+++ b/frontend/src/components/shared/detail-navigation/detail-navigation-sheet.tsx
@@ -5,26 +5,13 @@ import { ScrollArea } from '@/components/ui/scroll-area';
import { Sheet, SheetContent, SheetHeader, SheetTitle } from '@/components/ui/sheet';
import { cn } from '@/lib/utils';
-interface DetailNavigationSheetProps<T> {
- currentId: null | string | undefined;
- /**
- * Pre-computed index of `currentId` inside `items` (or `-1` when the
- * current entry doesn't belong to the filtered subset). Supplied by the
- * parent toolbar so the sheet doesn't re-scan `items` for membership.
- */
- currentIndex: number;
- getId: (item: T) => string;
- getLabel: (item: T) => string;
- /** Filtered + sorted items rendered as the sheet's listbox. */
- items: readonly T[];
- onItemSelect: (item: T) => void;
- onOpenChange: (open: boolean) => void;
- open: boolean;
+import type { DetailNavigationController } from './use-detail-navigation';
+
+interface DetailNavigationSheetProps<T extends { id: string }> {
+ controller: DetailNavigationController<T>;
renderItem?: (item: T, isCurrent: boolean) => ReactNode;
sheetIcon?: ReactNode;
sheetTitle: string;
- /** Total count shown in the header — same as `items.length`, named explicitly for clarity. */
- total: number;
}
/**
@@ -38,20 +25,27 @@ interface DetailNavigationSheetProps<T> {
* 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 function DetailNavigationSheet<T>({
- currentId,
- currentIndex,
- getId,
- getLabel,
- items,
- onItemSelect,
- onOpenChange,
- open,
+export const DetailNavigationSheet = <T extends { id: string }>({
+ controller,
renderItem,
sheetIcon,
sheetTitle,
- total,
-}: DetailNavigationSheetProps<T>) {
+}: DetailNavigationSheetProps<T>) => {
+ // 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<HTMLUListElement>(null);
const buttonRefs = useRef(new Map<string, HTMLButtonElement>());
const [focusedId, setFocusedId] = useState<null | string>(null);
@@ -107,7 +101,7 @@ export function DetailNavigationSheet<T>({
return null;
}
- // `currentId != null` narrows to `string`; the parent toolbar
+ // `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));
@@ -313,4 +307,4 @@ export function DetailNavigationSheet<T>({
</SheetContent>
</Sheet>
);
-}
+};
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
index de5af7a1..ebccb3c4 100644
--- a/frontend/src/components/shared/detail-navigation/detail-navigation-toolbar.test.tsx
+++ b/frontend/src/components/shared/detail-navigation/detail-navigation-toolbar.test.tsx
@@ -1,6 +1,6 @@
import type { ReactNode } from 'react';
-import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/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';
@@ -8,6 +8,7 @@ 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;
@@ -21,9 +22,8 @@ const ITEMS: readonly Item[] = [
{ id: 'd', title: 'Delta' },
] as const;
-const getId = (item: Item) => item.id;
-const getLabel = (item: Item) => item.title;
const getHref = (item: Item) => `/items/${item.id}`;
+const getLabel = (item: Item) => item.title;
const LocationReadout = () => {
const { pathname, search } = useLocation();
@@ -36,9 +36,34 @@ const LocationReadout = () => {
);
};
-const renderToolbar = (overrides: { currentId?: null | string; filter?: string; items?: readonly Item[] } = {}) => {
+interface HarnessProps {
+ currentId?: null | string;
+ filter?: string;
+ items?: readonly Item[];
+}
+
+const ToolbarHarness = ({ currentId = 'c', items = ITEMS }: HarnessProps) => {
+ const nav = useDetailNavigation<Item>({
+ currentId,
+ getHref,
+ getLabel,
+ items,
+ });
+
+ return (
+ <DetailNavigationToolbar<Item>
+ controller={nav}
+ sheetTitle="Items"
+ />
+ );
+};
+
+const renderToolbar = (props: HarnessProps = {}) => {
+ const filter = props.filter ?? '';
+ const initialId = props.currentId ?? 'c';
+
const Wrapper = ({ children }: { children: ReactNode }) => (
- <MemoryRouter initialEntries={['/items/c?q=' + (overrides.filter ?? '')]}>
+ <MemoryRouter initialEntries={[`/items/${initialId}?q=${filter}`]}>
<TooltipProvider>
<LocationReadout />
<Routes>
@@ -51,33 +76,28 @@ const renderToolbar = (overrides: { currentId?: null | string; filter?: string;
</MemoryRouter>
);
- return render(
- <DetailNavigationToolbar<Item>
- currentId={overrides.currentId ?? 'c'}
- filter={overrides.filter ?? ''}
- getHref={getHref}
- getId={getId}
- getLabel={getLabel}
- items={overrides.items ?? ITEMS}
- sheetTitle="Items"
- />,
- { wrapper: Wrapper },
- );
+ return render(<ToolbarHarness {...props} />, { wrapper: Wrapper });
};
describe('DetailNavigationToolbar', () => {
- it('renders nothing when items list is empty', () => {
+ it('renders nothing when raw items is empty', () => {
renderToolbar({ items: [] });
- // The toolbar should not emit any of its own controls — the wrapper
- // tree still renders the location readout, so assert on absent
- // toolbar elements instead of "container empty".
expect(screen.queryByRole('button', { name: /Previous/i })).not.toBeInTheDocument();
expect(screen.queryByRole('button', { name: /Next/i })).not.toBeInTheDocument();
});
- it('shows `${currentIndex + 1}/${total}` for a matched current item', () => {
+ it('composes Buttons + Sheet: position button opens the listbox', async () => {
+ const user = userEvent.setup();
renderToolbar({ currentId: 'c' });
- expect(screen.getByRole('button', { name: /3\/4/ })).toBeInTheDocument();
+
+ // 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', () => {
@@ -97,254 +117,22 @@ describe('DetailNavigationToolbar', () => {
it('Next navigates to the next sibling preserving `?q=`', async () => {
const user = userEvent.setup();
- // Filter 'a' matches every item (substring), so prev/next stays
- // navigable across the full set while still proving the `?q=` URL
- // round-trip on click.
renderToolbar({ currentId: 'a', filter: 'a' });
await user.click(screen.getByRole('button', { name: /Next/i }));
await waitFor(() => {
- const location = screen.getByTestId('location').textContent ?? '';
- expect(location).toContain('/items/b');
+ expect(screen.getByTestId('location').textContent).toContain('/items/b');
});
expect(screen.getByTestId('location').textContent).toContain('q=a');
});
- it('opens the sheet listbox when the position button is clicked', async () => {
- const user = userEvent.setup();
- renderToolbar({ currentId: 'c' });
-
- await user.click(screen.getByRole('button', { name: /3\/4/ }));
-
- const listbox = await screen.findByRole('listbox', { name: 'Items' });
- expect(listbox).toBeInTheDocument();
- expect(within(listbox).getAllByRole('option')).toHaveLength(4);
- });
-
- it('narrows the listbox to filtered items', async () => {
- const user = userEvent.setup();
- // "pha" matches only "Alpha" — substring is case-insensitive and
- // diacritic-insensitive (see ./text-filter tests).
- renderToolbar({ currentId: 'a', filter: 'pha' });
-
- await user.click(screen.getByRole('button', { name: /1\/1/ }));
-
- const listbox = await screen.findByRole('listbox', { name: 'Items' });
- const labels = within(listbox)
- .getAllByRole('option')
- .map((option) => option.textContent ?? '');
- expect(labels).toEqual(['Alpha']);
- });
-
- it('marks the current item with aria-selected and font-medium', async () => {
- const user = userEvent.setup();
- renderToolbar({ currentId: 'c' });
-
- await user.click(screen.getByRole('button', { name: /3\/4/ }));
-
- const listbox = await screen.findByRole('listbox');
- const current = within(listbox).getByRole('option', { selected: true });
- expect(current).toHaveAttribute('data-item-id', 'c');
- });
-
- it('applies roving tabIndex — only the current option is focusable', async () => {
- const user = userEvent.setup();
- renderToolbar({ currentId: 'c' });
-
- await user.click(screen.getByRole('button', { name: /3\/4/ }));
-
- const listbox = await screen.findByRole('listbox');
- const options = within(listbox).getAllByRole('option');
-
- // Wait for the open-time roving focus to land on the current entry.
- 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('ArrowDown moves roving focus to the next option', async () => {
- const user = userEvent.setup();
- renderToolbar({ currentId: 'b' });
-
- await user.click(screen.getByRole('button', { name: /2\/4/ }));
-
- 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 () => {
- const user = userEvent.setup();
- renderToolbar({ currentId: 'a' });
-
- await user.click(screen.getByRole('button', { name: /1\/4/ }));
-
- 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 () => {
- const user = userEvent.setup();
- renderToolbar({ currentId: 'a' });
-
- await user.click(screen.getByRole('button', { name: /1\/4/ }));
-
- 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 () => {
- const user = userEvent.setup();
- renderToolbar({ currentId: 'd' });
-
- await user.click(screen.getByRole('button', { name: /4\/4/ }));
-
- const listbox = await screen.findByRole('listbox');
- // Wait for the open-time focus on the current ('d') before issuing Home.
- 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');
- });
- });
-
- it('clicking an option in the sheet navigates and closes it', async () => {
- const user = userEvent.setup();
- renderToolbar({ currentId: 'c' });
-
- await user.click(screen.getByRole('button', { name: /3\/4/ }));
-
- 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('disables the position button when the filter excludes every item', () => {
+ it('disables the position button when the filter excludes every item', async () => {
renderToolbar({ currentId: 'c', filter: 'qqqqqqqqq' });
- // With nothing to navigate to, the sheet trigger is disabled — the
- // empty-state copy lives inside the sheet but the button gating
- // prevents opening it in the first place.
- const positionButton = screen.getByRole('button', { name: /–\/0/ });
- expect(positionButton).toBeDisabled();
- });
-
- it('falls back to the first filtered option when current is outside the subset', async () => {
- const user = userEvent.setup();
- renderToolbar({ currentId: 'zzz' });
-
- await user.click(screen.getByRole('button', { name: /–\/4/ }));
-
- const listbox = await screen.findByRole('listbox');
+ // After debounce settles, the empty subset disables the trigger.
await waitFor(() => {
- const focused = within(listbox)
- .getAllByRole('option')
- .find((option) => option.getAttribute('tabindex') === '0');
- expect(focused).toHaveAttribute('data-item-id', 'a');
- });
- });
-});
-
-describe('DetailNavigationToolbar — predicate stability', () => {
- it('updates the filtered subset when the filter prop changes', async () => {
- const user = userEvent.setup();
-
- const Wrapper = ({ children }: { children: ReactNode }) => (
- <MemoryRouter initialEntries={['/items/a']}>
- <TooltipProvider>
- <Routes>
- <Route
- element={<>{children}</>}
- path="/items/:id"
- />
- </Routes>
- </TooltipProvider>
- </MemoryRouter>
- );
-
- const { rerender } = render(
- <DetailNavigationToolbar<Item>
- currentId="a"
- filter=""
- getHref={getHref}
- getId={getId}
- getLabel={getLabel}
- items={ITEMS}
- sheetTitle="Items"
- />,
- { wrapper: Wrapper },
- );
-
- expect(screen.getByRole('button', { name: /1\/4/ })).toBeInTheDocument();
-
- rerender(
- <DetailNavigationToolbar<Item>
- currentId="a"
- filter="Alpha"
- getHref={getHref}
- getId={getId}
- getLabel={getLabel}
- items={ITEMS}
- sheetTitle="Items"
- />,
- );
-
- expect(screen.getByRole('button', { name: /1\/1/ })).toBeInTheDocument();
- await act(async () => {
- await user.tab();
+ 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
index 79cc7307..77d516dd 100644
--- a/frontend/src/components/shared/detail-navigation/detail-navigation-toolbar.tsx
+++ b/frontend/src/components/shared/detail-navigation/detail-navigation-toolbar.tsx
@@ -1,183 +1,49 @@
-import { type ReactNode, useCallback, useMemo, useState } from 'react';
-import { useNavigate, useSearchParams } from 'react-router-dom';
+import type { ReactNode } from 'react';
-import { mergeHrefWithSearchParams } from '@/lib/url-params';
+import type { DetailNavigationController } from './use-detail-navigation';
import { DetailNavigationButtons } from './detail-navigation-buttons';
import { DetailNavigationSheet } from './detail-navigation-sheet';
-import { useNavigation } from './use-navigation';
-export interface DetailNavigationToolbarProps<T> {
- currentId: null | string | undefined;
- /**
- * Current free-text filter the list page applies. The toolbar narrows the
- * navigable subset by running the same `matchesTextFilter` semantics the
- * list uses — so Prev/Next never drifts out of sync with what the user
- * sees in the table.
- */
- filter: string;
- /**
- * Build a navigation target for the given item. The current value of
- * `?<filterParamName>=` is forwarded so detail-page navigation preserves
- * the filter the user picked on the list.
- */
- getHref: (item: T) => string;
- /**
- * Stable accessor for the row's ID. The toolbar uses it for keying both
- * the navigation lookup and the rendered Sheet list.
- */
- getId: (item: T) => string;
- /**
- * Default label for items in the Sheet list. Used when `renderItem` is
- * not provided. Also acts as the default haystack for the filter when
- * `getSearchableText` is omitted (matches the common case where the list
- * column filter targets the same field as the label).
- */
- getLabel: (item: T) => string;
- /**
- * Optional override for the haystack the filter runs against. Pass when
- * the list column filter is keyed on a different field than the visible
- * label (e.g. label is `title || #id`, filter is plain `title`).
- */
- getSearchableText?: (item: T) => null | string | undefined;
- items: readonly T[];
- /**
- * Optional override for the row in the Sheet. Receives the item and a
- * boolean indicating whether it's the current detail page.
- */
+export interface DetailNavigationToolbarProps<T extends { id: string }> {
+ controller: DetailNavigationController<T>;
renderItem?: (item: T, isCurrent: boolean) => ReactNode;
sheetIcon?: ReactNode;
sheetTitle: string;
- /** Optional comparator. When omitted, items appear in input order. */
- sortFn?: (a: T, b: T) => number;
}
/**
- * Prev / Position / Next toolbar shown on detail pages whose list page
- * supports a free-text filter.
+ * Convenience wrapper that composes `<DetailNavigationButtons>` and
+ * `<DetailNavigationSheet>` against a single `DetailNavigationController`.
+ * Most desktop call sites use this directly; pages with non-standard chrome
+ * (e.g. mobile prev/position/next inside a `<DropdownMenuItem>`) can compose
+ * the leaves themselves and read from the same controller.
*
- * - "Prev" / "Next" walk the same filtered subset the list page renders.
- * - The middle button opens `<DetailNavigationSheet>`, a listbox of every
- * entry in the filtered subset with the current one highlighted — the
- * user can jump anywhere in one click.
- * - When the current item is missing from the filtered subset (e.g. the
- * server-loaded record doesn't match the active filter, or the record
- * was just deleted) prev/next are disabled and the position label falls
- * back to `"–/total"` so the user can still open the Sheet to pick a
- * neighbour.
- * - Sibling navigation uses `replace: true` so paging through a list of 50
- * items doesn't push 50 history entries the user has to back through.
- *
- * Returns `null` when there are no items at all — there's nothing useful to
- * render and a "–/0" disabled toolbar would just be visual noise.
+ * 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 function DetailNavigationToolbar<T>({
- currentId,
- filter,
- getHref,
- getId,
- getLabel,
- getSearchableText,
- items,
+export const DetailNavigationToolbar = <T extends { id: string }>({
+ controller,
renderItem,
sheetIcon,
sheetTitle,
- sortFn,
-}: DetailNavigationToolbarProps<T>) {
- const navigate = useNavigate();
- const [searchParams] = useSearchParams();
- const [isSheetOpen, setIsSheetOpen] = useState(false);
-
- // The toolbar owns the haystack-resolution rule so list and detail always
- // agree on what "matches the filter" means — callers only describe the
- // data shape (`getSearchableText` / `getLabel`), never the comparison.
- const haystack = getSearchableText ?? getLabel;
-
- const { currentIndex, filteredItems, nextId, prevId, total } = useNavigation({
- currentId,
- getId,
- getSearchableText: haystack,
- items,
- query: filter,
- sortFn,
- });
-
- // Forward the current filter (and any other URL state) when navigating
- // to a sibling — without it the user would lose `?q=` the moment they
- // hit Prev/Next, breaking the "stay inside the filtered subset" promise.
- // `mergeHrefWithSearchParams` round-trips through `URL` so the hash
- // fragment survives and getHref's own query params win on collision.
- const buildHref = useCallback(
- (item: T) => mergeHrefWithSearchParams(getHref(item), searchParams),
- [getHref, searchParams],
- );
-
- const goTo = useCallback(
- (id: null | string) => {
- if (!id) {
- return;
- }
-
- const target = filteredItems.find((item) => String(getId(item)) === id);
-
- if (!target) {
- return;
- }
-
- navigate(buildHref(target), { replace: true });
- },
- [buildHref, filteredItems, getId, navigate],
- );
-
- const handleItemSelect = useCallback(
- (item: T) => {
- setIsSheetOpen(false);
- navigate(buildHref(item), { replace: true });
- },
- [buildHref, navigate],
- );
-
- const goToPrev = useCallback(() => goTo(prevId), [goTo, prevId]);
- const goToNext = useCallback(() => goTo(nextId), [goTo, nextId]);
- const openSheet = useCallback(() => setIsSheetOpen(true), []);
-
- const positionLabel = useMemo(
- () => (total === 0 || currentIndex === -1 ? `–/${total}` : `${currentIndex + 1}/${total}`),
- [currentIndex, total],
- );
-
- // Nothing meaningful to render before items show up — saves the user from
- // a momentary "–/0" flash while the parent provider's data is in flight.
- if (items.length === 0) {
+}: DetailNavigationToolbarProps<T>) => {
+ if (controller.itemsEmpty) {
return null;
}
return (
<>
<DetailNavigationButtons
- hasEntries={total > 0}
- nextDisabled={!nextId}
- onNext={goToNext}
- onOpen={openSheet}
- onPrev={goToPrev}
- positionLabel={positionLabel}
- prevDisabled={!prevId}
+ controller={controller}
sheetTitle={sheetTitle}
/>
- <DetailNavigationSheet<T>
- currentId={currentId}
- currentIndex={currentIndex}
- getId={getId}
- getLabel={getLabel}
- items={filteredItems}
- onItemSelect={handleItemSelect}
- onOpenChange={setIsSheetOpen}
- open={isSheetOpen}
+ <DetailNavigationSheet
+ controller={controller}
renderItem={renderItem}
sheetIcon={sheetIcon}
sheetTitle={sheetTitle}
- total={total}
/>
</>
);
-}
+};
diff --git a/frontend/src/components/shared/detail-navigation/index.ts b/frontend/src/components/shared/detail-navigation/index.ts
index c05684b3..87439002 100644
--- a/frontend/src/components/shared/detail-navigation/index.ts
+++ b/frontend/src/components/shared/detail-navigation/index.ts
@@ -1,5 +1,4 @@
+export { DetailNavigationButtons } from './detail-navigation-buttons';
export { DetailNavigationSheet } from './detail-navigation-sheet';
export { DetailNavigationToolbar } from './detail-navigation-toolbar';
-export type { DetailNavigationToolbarProps } from './detail-navigation-toolbar';
-export { useDetailNavigation } from './use-detail-navigation';
-export { useNavigation } from './use-navigation';
+export { type DetailNavigationController, useDetailNavigation } from './use-detail-navigation';
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
index 3976490f..81d0657c 100644
--- a/frontend/src/components/shared/detail-navigation/use-detail-navigation.test.tsx
+++ b/frontend/src/components/shared/detail-navigation/use-detail-navigation.test.tsx
@@ -1,8 +1,8 @@
import type { ReactNode } from 'react';
import { act, renderHook, waitFor } from '@testing-library/react';
-import { MemoryRouter, Route, Routes, useNavigate, useSearchParams } from 'react-router-dom';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+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';
@@ -58,10 +58,31 @@ describe('useDetailNavigation — default getId', () => {
{ wrapper: renderInRoute(['/items/b']) },
);
- expect(result.current.toolbarProps.getId(ITEMS[1])).toBe('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<Item>({
+ 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 `toolbarProps` reference stable when the caller re-renders without changes', () => {
+ it('keeps `goToPrev` / `goToNext` / `handleItemSelect` identity-stable when nothing relevant changes', () => {
const { rerender, result } = renderHook(
() =>
useDetailNavigation<Item>({
@@ -74,15 +95,23 @@ describe('useDetailNavigation — default getId', () => {
{ wrapper: renderInRoute(['/items/b']) },
);
- const first = result.current.toolbarProps;
+ 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();
- // Downstream toolbar memos rely on this identity stability.
- expect(result.current.toolbarProps).toBe(first);
+
+ 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 `toolbarProps.filter` (debounced)', async () => {
+ it('exposes the URL `?q=` value through `controller.debouncedFilter` (debounced)', async () => {
const { result } = renderHook(
() =>
useDetailNavigation<Item>({
@@ -95,58 +124,302 @@ describe('useDetailNavigation — filter forwarding', () => {
{ wrapper: renderInRoute(['/items/b?q=alpha']) },
);
- // `toolbarProps.filter` is the debounced value — wait for the debounce
- // to settle (default 200ms) before asserting equality.
+ // `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<Item>({
+ currentId: 'a',
+ getHref,
+ getLabel,
+ getSearchableText,
+ items: ITEMS,
+ }),
+ { wrapper: renderInRoute(['/items/a?q=pha']) },
+ );
+
await waitFor(() => {
- expect(result.current.toolbarProps.filter).toBe('alpha');
+ expect(result.current.filteredItems.map((item) => item.id)).toEqual(['a']);
});
- expect(result.current.debouncedFilter).toBe('alpha');
+ 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<Item>({
+ 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<Item>({
+ 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<Item>({
+ 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 }) => (
+ <MemoryRouter initialEntries={['/items/a?q=a']}>
+ <LocationProbe onChange={(loc) => seen.push(loc)} />
+ <Routes>
+ <Route
+ element={<>{children}</>}
+ path="/items/:id"
+ />
+ </Routes>
+ </MemoryRouter>
+ );
+
+ const { result } = renderHook(
+ () =>
+ useDetailNavigation<Item>({
+ currentId: 'a',
+ getHref,
+ getLabel,
+ getSearchableText,
+ items: ITEMS,
+ }),
+ { wrapper: Wrapper },
+ );
- it('does NOT replay `localStorage` into the URL on a fresh detail mount', async () => {
- // Detail pages use `useTableQueryFilterReader` under the hood, which
- // is explicitly storage-blind. A shared `/items/abc` link should not
- // gain a stale `?q=` from a previous tab's filter.
- localStorage.setItem('table_4_/items', JSON.stringify({ filter: 'stored' }));
+ await waitFor(() => {
+ expect(result.current.debouncedFilter).toBe('a');
+ });
- const ProbeChild = ({ onMount }: { onMount: (search: string) => void }) => {
- const [searchParams] = useSearchParams();
- onMount(searchParams.toString());
+ 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[] = [];
- renderHook(
- () => {
- const nav = useDetailNavigation<Item>({
+ const Wrapper = ({ children }: { children: ReactNode }) => (
+ <MemoryRouter initialEntries={['/items/a']}>
+ <LocationProbe onChange={(loc) => seen.push(loc)} />
+ <Routes>
+ <Route
+ element={<>{children}</>}
+ path="/items/:id"
+ />
+ </Routes>
+ </MemoryRouter>
+ );
+
+ const { result } = renderHook(
+ () =>
+ useDetailNavigation<Item>({
+ 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 }) => (
+ <MemoryRouter initialEntries={['/items/a']}>
+ <Routes>
+ <Route
+ element={<>{children}</>}
+ path="/items/:id"
+ />
+ </Routes>
+ </MemoryRouter>
+ );
+
+ const { result } = renderHook(
+ () =>
+ useDetailNavigation<Item>({
+ 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<Item>({
currentId: 'b',
getHref,
getLabel,
getSearchableText,
items: ITEMS,
- });
+ onOpenChange,
+ open: true,
+ }),
+ { wrapper: renderInRoute(['/items/b']) },
+ );
+
+ expect(result.current.isSheetOpen).toBe(true);
- return nav;
- },
+ 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<Item>({
+ currentId: 'b',
+ getHref,
+ getLabel,
+ getSearchableText,
+ items: ITEMS,
+ onOpenChange,
+ }),
{ wrapper: renderInRoute(['/items/b']) },
);
- // Drain pending tasks — any storage→URL replay would land here.
- await act(async () => {
- await Promise.resolve();
+ expect(result.current.isSheetOpen).toBe(false);
+
+ act(() => {
+ result.current.openSheet();
});
- renderHook(() => null, {
- wrapper: ({ children }) => (
- <MemoryRouter initialEntries={['/items/b']}>
- <ProbeChild onMount={(search) => seen.push(search)} />
- {children}
- </MemoryRouter>
- ),
+ expect(result.current.isSheetOpen).toBe(true);
+ expect(onOpenChange).toHaveBeenLastCalledWith(true);
+
+ act(() => {
+ result.current.closeSheet();
});
- expect(seen.every((search) => !search.includes('q='))).toBe(true);
+ expect(result.current.isSheetOpen).toBe(false);
+ expect(onOpenChange).toHaveBeenLastCalledWith(false);
+ });
+
+ it('honours defaultOpen=true on first render in uncontrolled mode', () => {
+ const { result } = renderHook(
+ () =>
+ useDetailNavigation<Item>({
+ currentId: 'b',
+ defaultOpen: true,
+ getHref,
+ getLabel,
+ getSearchableText,
+ items: ITEMS,
+ }),
+ { wrapper: renderInRoute(['/items/b']) },
+ );
+
+ expect(result.current.isSheetOpen).toBe(true);
});
});
@@ -164,8 +437,9 @@ describe('useDetailNavigation — current item bookkeeping', () => {
{ wrapper: renderInRoute(['/items/b']) },
);
- expect(result.current.toolbarProps.currentId).toBeUndefined();
- expect(result.current.toolbarProps.items).toBe(ITEMS);
+ expect(result.current.currentId).toBeNull();
+ expect(result.current.currentIndex).toBe(-1);
+ expect(result.current.filteredItems).toEqual(ITEMS);
});
});
diff --git a/frontend/src/components/shared/detail-navigation/use-detail-navigation.ts b/frontend/src/components/shared/detail-navigation/use-detail-navigation.ts
index a415e216..fd50f2fd 100644
--- a/frontend/src/components/shared/detail-navigation/use-detail-navigation.ts
+++ b/frontend/src/components/shared/detail-navigation/use-detail-navigation.ts
@@ -1,23 +1,80 @@
-import { useMemo } from 'react';
+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 type { DetailNavigationToolbarProps } from './detail-navigation-toolbar';
+import { useNavigation } from './use-navigation';
/**
- * Data-only slice of `DetailNavigationToolbarProps<T>`. Derived from the
- * single source of truth in `detail-navigation-toolbar.tsx` so a new
- * required prop (or a rename) can't silently desync the two surfaces.
+ * Headless controller for a detail page that walks a filtered list.
*
- * Presentation-only fields (`sheetTitle`, `sheetIcon`, `renderItem`,
- * `sortFn`) are intentionally excluded — those are supplied per-page at the
- * call site of the toolbar, not by the navigation hook.
+ * 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 `?<filter>=` into every
+ * prev / next / item-select destination.
+ *
+ * All callbacks are identity-stable across renders that don't change the
+ * inputs the action depends on — `<DetailNavigationButtons>`,
+ * `<DetailNavigationSheet>`, and any custom chrome rendered against the
+ * controller can rely on referential equality for downstream memos.
*/
-type DetailNavigationToolbarDataProps<T> = Pick<
- DetailNavigationToolbarProps<T>,
- 'currentId' | 'filter' | 'getHref' | 'getId' | 'getLabel' | 'getSearchableText' | 'items'
->;
+export interface DetailNavigationController<T extends { id: string }> {
+ 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
+ * `<DetailNavigationToolbar>` 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
@@ -25,19 +82,30 @@ type DetailNavigationToolbarDataProps<T> = Pick<
* 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.
- *
- * `${string}` is unconstrained on purpose — we only care that the value
- * begins with a slash, not what follows.
*/
type ParentPath = `/${string}`;
interface UseDetailNavigationOptions<T extends { id: string }> {
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
@@ -45,18 +113,9 @@ interface UseDetailNavigationOptions<T extends { id: string }> {
* `/knowledges`). Nested routes (`/admin/flows/:id`) must pass an
* explicit value here because the default would key into `/admin`
* rather than `/admin/flows`.
- *
- * Typed as a slash-prefixed string so the compiler rejects empty or
- * unprefixed overrides — those used to silently fall back to the
- * top-level path, which produced surprising key collisions. Pass an
- * explicit slash path (e.g. `'/admin/flows'`) when overriding.
*/
parentPath?: ParentPath;
-}
-
-interface UseDetailNavigationResult<T extends { id: string }> {
- debouncedFilter: string;
- toolbarProps: DetailNavigationToolbarDataProps<T>;
+ sortFn?: (a: T, b: T) => number;
}
// Module-level so the reference is stable across renders. Typed against
@@ -66,30 +125,47 @@ interface UseDetailNavigationResult<T extends { id: string }> {
const defaultGetId = (item: { id: string }): string => item.id;
/**
- * Convenience wrapper for detail pages that need a Prev/Next toolbar tied
- * to the parent list's free-text filter.
+ * Build the headless `DetailNavigationController<T>` for a detail page.
*
- * The hook bundles the three things every detail page repeats:
+ * 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. supplying a default `getId` (most domain types use a plain `id`).
+ * 3. running the pure `useNavigation` core against the filtered subset,
+ * 4. wiring identity-stable `goToPrev` / `goToNext` / `handleItemSelect`
+ * with `?<filter>=` forwarded through `mergeHrefWithSearchParams`.
*
- * The returned `toolbarProps` plug straight into `<DetailNavigationToolbar>` —
- * callers add presentation-only props (`sheetTitle`, `renderItem`, etc.).
+ * The returned controller drives `<DetailNavigationToolbar>`,
+ * `<DetailNavigationButtons>`, and `<DetailNavigationSheet>` (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 each callback through `useCallback`: the toolbar's filter memo relies
- * on identity stability, and an inline arrow defeats it.
+ * 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 = <T extends { id: string }>({
currentId,
+ defaultOpen,
getHref,
getId,
getLabel,
getSearchableText,
items,
+ onOpenChange,
+ open,
parentPath,
-}: UseDetailNavigationOptions<T>): UseDetailNavigationResult<T> => {
+ sortFn,
+}: UseDetailNavigationOptions<T>): DetailNavigationController<T> => {
+ 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;
@@ -101,21 +177,147 @@ export const useDetailNavigation = <T extends { id: string }>({
// Memoize so passing `getId={undefined}` keeps the reference stable when
// the caller re-renders for unrelated reasons. Without the memo the
- // `toolbarProps` memo below would invalidate on every render.
+ // 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<T>({
+ 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 toolbarProps = useMemo<DetailNavigationToolbarDataProps<T>>(
+ 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<DetailNavigationController<T>>(
() => ({
- currentId,
- filter: debouncedFilter,
- getHref,
+ closeSheet,
+ currentId: normalizedCurrentId,
+ currentIndex,
+ currentItem,
+ debouncedFilter,
+ filteredItems,
getId: resolvedGetId,
getLabel,
- getSearchableText,
- items,
+ getSearchableText: resolvedGetSearchableText,
+ goToNext,
+ goToPrev,
+ handleItemSelect,
+ hasEntries,
+ isSheetOpen,
+ itemsEmpty,
+ nextId,
+ openSheet,
+ positionLabel,
+ prevId,
+ setSheetOpen,
+ total,
}),
- [currentId, debouncedFilter, getHref, getLabel, getSearchableText, items, resolvedGetId],
+ [
+ closeSheet,
+ normalizedCurrentId,
+ currentIndex,
+ currentItem,
+ debouncedFilter,
+ filteredItems,
+ resolvedGetId,
+ getLabel,
+ resolvedGetSearchableText,
+ goToNext,
+ goToPrev,
+ handleItemSelect,
+ hasEntries,
+ isSheetOpen,
+ itemsEmpty,
+ nextId,
+ openSheet,
+ positionLabel,
+ prevId,
+ setSheetOpen,
+ total,
+ ],
);
-
- return { debouncedFilter, toolbarProps };
};
diff --git a/frontend/src/features/flows/use-flow-detail-navigation.ts b/frontend/src/features/flows/use-flow-detail-navigation.ts
index 01d25e7b..3b0cd1c7 100644
--- a/frontend/src/features/flows/use-flow-detail-navigation.ts
+++ b/frontend/src/features/flows/use-flow-detail-navigation.ts
@@ -9,11 +9,11 @@ const getHref = (item: Flow) => `/flows/${item.id}`;
/**
* Detail-page navigation wired up for flows. Encapsulates the getter
* callbacks and the call to `useDetailNavigation` so each detail page just
- * spreads the returned `toolbarProps` onto `<DetailNavigationToolbar<Flow>>`
- * and adds the presentation-only props (`sheetTitle`, `renderItem`, etc.).
+ * passes the returned controller to `<DetailNavigationToolbar controller={nav}>`
+ * (or to its leaf primitives for custom chrome).
*
* Pass `null` instead of an id while the page is in a non-viewing state
- * (e.g. `/flows/new`) so the toolbar reports an unmatched current item.
+ * (e.g. `/flows/new`) so the controller reports an unmatched current item.
*/
export const useFlowDetailNavigation = (currentId: null | string | undefined) => {
const { flows } = useFlows();
diff --git a/frontend/src/features/knowledges/knowledge-header.tsx b/frontend/src/features/knowledges/knowledge-header.tsx
index 5e2e5f0e..5ffb0cdf 100644
--- a/frontend/src/features/knowledges/knowledge-header.tsx
+++ b/frontend/src/features/knowledges/knowledge-header.tsx
@@ -1,14 +1,18 @@
import type { ReactNode } from 'react';
-import { ChevronLeft, ChevronRight, Ellipsis, LibraryBig, Loader2, Pencil, Trash } from 'lucide-react';
-import { useCallback, useMemo, useState } from 'react';
-import { useNavigate, useSearchParams } from 'react-router-dom';
+import { Ellipsis, LibraryBig, Loader2, Pencil, Trash } from 'lucide-react';
+import { useCallback, useState } from 'react';
+import { useNavigate } from 'react-router-dom';
import { toast } from 'sonner';
import type { KnowledgeDocumentFragmentFragment } from '@/graphql/types';
import ConfirmationDialog from '@/components/shared/confirmation-dialog';
-import { DetailNavigationSheet, DetailNavigationToolbar, useNavigation } from '@/components/shared/detail-navigation';
+import {
+ DetailNavigationButtons,
+ DetailNavigationSheet,
+ DetailNavigationToolbar,
+} from '@/components/shared/detail-navigation';
import { InlineEditInput, useInlineEdit } from '@/components/shared/inline-edit';
import { Badge } from '@/components/ui/badge';
import { Breadcrumb, BreadcrumbItem, BreadcrumbList, BreadcrumbPage } from '@/components/ui/breadcrumb';
@@ -24,7 +28,6 @@ import { Separator } from '@/components/ui/separator';
import { SidebarTrigger } from '@/components/ui/sidebar';
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
import { useBreakpoint } from '@/hooks/use-breakpoint';
-import { mergeHrefWithSearchParams } from '@/lib/url-params';
import { type Knowledge, useKnowledges } from '@/providers/knowledges-provider';
import { useKnowledgeDetailNavigation } from './use-knowledge-detail-navigation';
@@ -42,9 +45,20 @@ interface KnowledgeHeaderProps {
saveButton?: ReactNode;
}
+const renderKnowledgeItem = (item: Knowledge, isCurrent: boolean): ReactNode => (
+ <>
+ <Badge
+ className="shrink-0 text-[10px] whitespace-nowrap"
+ variant="outline"
+ >
+ {item.docType}
+ </Badge>
+ <span className={isCurrent ? 'truncate font-medium' : 'truncate'}>{item.question}</span>
+ </>
+);
+
export const KnowledgeHeader = ({ isNew, knowledge, onBeforeNavigateAway, saveButton }: KnowledgeHeaderProps) => {
const navigate = useNavigate();
- const [searchParams] = useSearchParams();
const { isMobile } = useBreakpoint();
const { deleteKnowledge, updateKnowledge } = useKnowledges();
const [isRenaming, setIsRenaming] = useState(false);
@@ -53,57 +67,9 @@ export const KnowledgeHeader = ({ isNew, knowledge, onBeforeNavigateAway, saveBu
const knowledgeId = knowledge?.id ?? null;
- const { toolbarProps: knowledgeToolbarProps } = useKnowledgeDetailNavigation(knowledgeId);
-
- // Mirror what `<DetailNavigationToolbar>` computes internally so the
- // mobile menu items share the same filtered subset as the desktop toolbar.
- const mobileNav = useNavigation<Knowledge>({
- currentId: knowledgeToolbarProps.currentId,
- getId: knowledgeToolbarProps.getId,
- getSearchableText: knowledgeToolbarProps.getSearchableText ?? knowledgeToolbarProps.getLabel,
- items: knowledgeToolbarProps.items,
- query: knowledgeToolbarProps.filter,
- });
- const [isMobileNavSheetOpen, setIsMobileNavSheetOpen] = useState(false);
-
- const mobileNavGoTo = useCallback(
- (id: null | string) => {
- if (!id) {
- return;
- }
-
- const target = mobileNav.filteredItems.find(
- (item) => String(knowledgeToolbarProps.getId(item)) === id,
- );
-
- if (!target) {
- return;
- }
-
- navigate(mergeHrefWithSearchParams(knowledgeToolbarProps.getHref(target), searchParams), {
- replace: true,
- });
- },
- [knowledgeToolbarProps, mobileNav.filteredItems, navigate, searchParams],
- );
-
- const mobileNavSelectItem = useCallback(
- (item: Knowledge) => {
- setIsMobileNavSheetOpen(false);
- navigate(mergeHrefWithSearchParams(knowledgeToolbarProps.getHref(item), searchParams), {
- replace: true,
- });
- },
- [knowledgeToolbarProps, navigate, searchParams],
- );
-
- const mobilePositionLabel = useMemo(
- () =>
- mobileNav.total === 0 || mobileNav.currentIndex === -1
- ? `–/${mobileNav.total}`
- : `${mobileNav.currentIndex + 1}/${mobileNav.total}`,
- [mobileNav.currentIndex, mobileNav.total],
- );
+ // Single controller drives both the desktop toolbar and the mobile
+ // dropdown row + sheet — no separate state mirroring required.
+ const knowledgeNav = useKnowledgeDetailNavigation(knowledgeId);
// Title source-of-truth is the server-side `question`. We intentionally do
// not read it from the form draft below — the inline rename flow in this
@@ -219,20 +185,8 @@ export const KnowledgeHeader = ({ isNew, knowledge, onBeforeNavigateAway, saveBu
<div className="flex shrink-0 items-center gap-2">
{canShowActions && !isMobile && (
<DetailNavigationToolbar<Knowledge>
- {...knowledgeToolbarProps}
- renderItem={(item, isCurrent) => (
- <>
- <Badge
- className="shrink-0 text-[10px] whitespace-nowrap"
- variant="outline"
- >
- {item.docType}
- </Badge>
- <span className={isCurrent ? 'truncate font-medium' : 'truncate'}>
- {item.question}
- </span>
- </>
- )}
+ controller={knowledgeNav}
+ renderItem={renderKnowledgeItem}
sheetIcon={<LibraryBig className="size-4" />}
sheetTitle="Knowledges"
/>
@@ -255,7 +209,7 @@ export const KnowledgeHeader = ({ isNew, knowledge, onBeforeNavigateAway, saveBu
className="min-w-24"
onCloseAutoFocus={handleDropdownCloseAutoFocus}
>
- {isMobile && mobileNav.total > 0 && (
+ {isMobile && knowledgeNav.total > 0 && (
<>
<DropdownMenuItem
className="cursor-default hover:bg-transparent focus:bg-transparent"
@@ -264,35 +218,11 @@ export const KnowledgeHeader = ({ isNew, knowledge, onBeforeNavigateAway, saveBu
<LibraryBig className="size-4" />
Knowledges
<div className="-my-1.5 -mr-2 ml-auto flex items-center">
- <Button
- aria-label="Previous"
- className="size-7 rounded-r-none border-r-0 p-0"
- disabled={!mobileNav.prevId}
- onClick={() => mobileNavGoTo(mobileNav.prevId)}
- size="icon"
- variant="outline"
- >
- <ChevronLeft />
- </Button>
- <Button
- aria-label="Open knowledges list"
- className="h-7 min-w-12 rounded-none border-x px-2 font-mono text-xs tabular-nums"
- disabled={mobileNav.currentIndex === -1}
- onClick={() => setIsMobileNavSheetOpen(true)}
- variant="outline"
- >
- {mobilePositionLabel}
- </Button>
- <Button
- aria-label="Next"
- className="size-7 rounded-l-none border-l-0 p-0"
- disabled={!mobileNav.nextId}
- onClick={() => mobileNavGoTo(mobileNav.nextId)}
- size="icon"
- variant="outline"
- >
- <ChevronRight />
- </Button>
+ <DetailNavigationButtons<Knowledge>
+ controller={knowledgeNav}
+ sheetTitle="Knowledges"
+ size="sm"
+ />
</div>
</DropdownMenuItem>
<DropdownMenuSeparator />
@@ -326,28 +256,10 @@ export const KnowledgeHeader = ({ isNew, knowledge, onBeforeNavigateAway, saveBu
</header>
{isMobile && canShowActions && (
<DetailNavigationSheet<Knowledge>
- currentId={knowledgeToolbarProps.currentId}
- currentIndex={mobileNav.currentIndex}
- getId={knowledgeToolbarProps.getId}
- getLabel={knowledgeToolbarProps.getLabel}
- items={mobileNav.filteredItems}
- onItemSelect={mobileNavSelectItem}
- onOpenChange={setIsMobileNavSheetOpen}
- open={isMobileNavSheetOpen}
- renderItem={(item, isCurrent) => (
- <>
- <Badge
- className="shrink-0 text-[10px] whitespace-nowrap"
- variant="outline"
- >
- {item.docType}
- </Badge>
- <span className={isCurrent ? 'truncate font-medium' : 'truncate'}>{item.question}</span>
- </>
- )}
+ controller={knowledgeNav}
+ renderItem={renderKnowledgeItem}
sheetIcon={<LibraryBig className="size-4" />}
sheetTitle="Knowledges"
- total={mobileNav.total}
/>
)}
<ConfirmationDialog
diff --git a/frontend/src/features/knowledges/use-knowledge-detail-navigation.ts b/frontend/src/features/knowledges/use-knowledge-detail-navigation.ts
index c9f90fe6..1497d5da 100644
--- a/frontend/src/features/knowledges/use-knowledge-detail-navigation.ts
+++ b/frontend/src/features/knowledges/use-knowledge-detail-navigation.ts
@@ -5,7 +5,9 @@ const getLabel = (item: Knowledge) => item.question;
const getHref = (item: Knowledge) => `/knowledges/${item.id}`;
/**
- * Detail-page navigation wired up for knowledge documents. The list page
+ * Detail-page navigation wired up for knowledge documents. Returns a
+ * `DetailNavigationController<Knowledge>` for `<DetailNavigationToolbar>` /
+ * `<DetailNavigationButtons>` / `<DetailNavigationSheet>`. The list page
* filters on `question` and the header shows the same, so `getLabel`
* doubles as the default searchable text.
*/
diff --git a/frontend/src/features/templates/use-template-detail-navigation.ts b/frontend/src/features/templates/use-template-detail-navigation.ts
index 56f7bd7d..9e93c193 100644
--- a/frontend/src/features/templates/use-template-detail-navigation.ts
+++ b/frontend/src/features/templates/use-template-detail-navigation.ts
@@ -6,9 +6,12 @@ const getId = (item: Template) => String(item.id);
const getHref = (item: Template) => `/templates/${item.id}`;
/**
- * Detail-page navigation wired up for templates. The list page filters on
- * `title` and the breadcrumb shows the same, so `getLabel` doubles as the
- * default searchable text (no explicit `getSearchableText` needed).
+ * Detail-page navigation wired up for templates. Returns a
+ * `DetailNavigationController<Template>` for `<DetailNavigationToolbar>` /
+ * `<DetailNavigationButtons>` / `<DetailNavigationSheet>`. The list page
+ * filters on `title` and the breadcrumb shows the same, so `getLabel`
+ * doubles as the default searchable text (no explicit `getSearchableText`
+ * needed).
*/
export const useTemplateDetailNavigation = (currentId: null | string | undefined) => {
const { templates } = useTemplates();
diff --git a/frontend/src/pages/flows/flow.tsx b/frontend/src/pages/flows/flow.tsx
index 4efa6556..8f48e40f 100644
--- a/frontend/src/pages/flows/flow.tsx
+++ b/frontend/src/pages/flows/flow.tsx
@@ -1,7 +1,7 @@
+import type { ReactNode } from 'react';
+
import {
ChevronDown,
- ChevronLeft,
- ChevronRight,
Copy,
Download,
Ellipsis,
@@ -15,14 +15,18 @@ import {
Star,
Trash,
} from 'lucide-react';
-import { useCallback, useEffect, useMemo, useState } from 'react';
-import { useNavigate, useSearchParams } from 'react-router-dom';
+import { useCallback, useEffect, useState } from 'react';
+import { useNavigate } from 'react-router-dom';
import { toast } from 'sonner';
import { FlowStatusIcon } from '@/components/icons/flow-status-icon';
import { ProviderIcon } from '@/components/icons/provider-icon';
import ConfirmationDialog from '@/components/shared/confirmation-dialog';
-import { DetailNavigationSheet, DetailNavigationToolbar, useNavigation } from '@/components/shared/detail-navigation';
+import {
+ DetailNavigationButtons,
+ DetailNavigationSheet,
+ DetailNavigationToolbar,
+} from '@/components/shared/detail-navigation';
import { HeaderButton } from '@/components/shared/header-button';
import { InlineEditInput, useInlineEdit } from '@/components/shared/inline-edit';
import { Badge } from '@/components/ui/badge';
@@ -47,12 +51,27 @@ import { useBreakpoint } from '@/hooks/use-breakpoint';
import { useFlowTabDetection } from '@/hooks/use-flow-tab-detection';
import { Log } from '@/lib/log';
import { copyToClipboard, downloadTextFile, generateFileName, generateReport } from '@/lib/report';
-import { mergeHrefWithSearchParams } from '@/lib/url-params';
import { formatName } from '@/lib/utils/format';
import { useFavorites } from '@/providers/favorites-provider';
import { useFlow } from '@/providers/flow-provider';
import { type Flow as FlowItem, useFlows } from '@/providers/flows-provider';
+const renderFlowItem = (item: FlowItem, isCurrent: boolean): ReactNode => (
+ <>
+ <FlowStatusIcon
+ className="size-3 shrink-0"
+ status={item.status}
+ />
+ <span className={isCurrent ? 'truncate font-medium' : 'truncate'}>{item.title || `Flow #${item.id}`}</span>
+ <Badge
+ className="ml-auto shrink-0 font-mono text-[10px]"
+ variant="outline"
+ >
+ #{item.id}
+ </Badge>
+ </>
+);
+
const FlowReportDropdown = () => {
const { flowData, flowId } = useFlow();
const flow = flowData?.flow;
@@ -171,7 +190,6 @@ const FlowReportDropdown = () => {
const Flow = () => {
const { isDesktop, isMobile } = useBreakpoint();
const navigate = useNavigate();
- const [searchParams] = useSearchParams();
const { flowData, flowError, flowId, isLoading: isFlowLoading } = useFlow();
const { deleteFlow, finishFlow } = useFlows();
@@ -181,56 +199,10 @@ const Flow = () => {
const flowTitle = flow?.title ?? '';
const isFlowRunning = flow ? ![StatusType.Failed, StatusType.Finished].includes(flow.status) : false;
- // Walk the same `?q=` filtered subset the list page renders. The hook
- // also restores the filter from `localStorage` when the page is opened
- // via a bookmark, so the toolbar stays in lockstep with the user's last
- // persisted intent.
- const { toolbarProps: flowToolbarProps } = useFlowDetailNavigation(flowId);
-
- // Mirror what `<DetailNavigationToolbar>` computes internally so the
- // mobile menu items (Previous / Open list / Next) and the sheet trigger
- // share the same filtered subset and ordering as the desktop toolbar.
- const mobileNav = useNavigation<FlowItem>({
- currentId: flowToolbarProps.currentId,
- getId: flowToolbarProps.getId,
- getSearchableText: flowToolbarProps.getSearchableText ?? flowToolbarProps.getLabel,
- items: flowToolbarProps.items,
- query: flowToolbarProps.filter,
- });
- const [isMobileNavSheetOpen, setIsMobileNavSheetOpen] = useState(false);
-
- const mobileNavGoTo = useCallback(
- (id: null | string) => {
- if (!id) {
- return;
- }
-
- const target = mobileNav.filteredItems.find((item) => String(flowToolbarProps.getId(item)) === id);
-
- if (!target) {
- return;
- }
-
- navigate(mergeHrefWithSearchParams(flowToolbarProps.getHref(target), searchParams), { replace: true });
- },
- [flowToolbarProps, mobileNav.filteredItems, navigate, searchParams],
- );
-
- const mobileNavSelectItem = useCallback(
- (item: FlowItem) => {
- setIsMobileNavSheetOpen(false);
- navigate(mergeHrefWithSearchParams(flowToolbarProps.getHref(item), searchParams), { replace: true });
- },
- [flowToolbarProps, navigate, searchParams],
- );
-
- const mobilePositionLabel = useMemo(
- () =>
- mobileNav.total === 0 || mobileNav.currentIndex === -1
- ? `–/${mobileNav.total}`
- : `${mobileNav.currentIndex + 1}/${mobileNav.total}`,
- [mobileNav.currentIndex, mobileNav.total],
- );
+ // Single controller drives the desktop toolbar AND the mobile dropdown
+ // row + sheet — Prev/Next, sheet open state, and the position label all
+ // live on one source of truth.
+ const flowNav = useFlowDetailNavigation(flowId);
const {
handleDropdownCloseAutoFocus,
@@ -389,24 +361,8 @@ const Flow = () => {
<div className="flex shrink-0 items-center gap-2">
{flow && !isMobile && (
<DetailNavigationToolbar<FlowItem>
- {...flowToolbarProps}
- renderItem={(item, isCurrent) => (
- <>
- <FlowStatusIcon
- className="size-3 shrink-0"
- status={item.status}
- />
- <span className={isCurrent ? 'truncate font-medium' : 'truncate'}>
- {item.title || `Flow #${item.id}`}
- </span>
- <Badge
- className="ml-auto shrink-0 font-mono text-[10px]"
- variant="outline"
- >
- #{item.id}
- </Badge>
- </>
- )}
+ controller={flowNav}
+ renderItem={renderFlowItem}
sheetIcon={<GitFork className="size-4" />}
sheetTitle="Flows"
/>
@@ -438,15 +394,13 @@ const Flow = () => {
className="min-w-24"
onCloseAutoFocus={handleDropdownCloseAutoFocus}
>
- {isMobile && mobileNav.total > 0 && (
+ {isMobile && flowNav.total > 0 && (
<>
{/* Single row that mirrors the desktop toolbar: label on
the left, prev / position / next button group on the
right. `onSelect={preventDefault}` stops the menu from
- closing on label clicks; the inner buttons own their
- own click handlers and don't bubble into menu-item
- selection. Position button doubles as the sheet
- trigger, matching the toolbar's middle-button role. */}
+ closing on label clicks; `<DetailNavigationButtons>`
+ owns its own click handlers and tooltips. */}
<DropdownMenuItem
className="cursor-default hover:bg-transparent focus:bg-transparent"
onSelect={(event) => event.preventDefault()}
@@ -454,35 +408,11 @@ const Flow = () => {
<GitFork className="size-4" />
Flows
<div className="-my-1.5 -mr-2 ml-auto flex items-center">
- <Button
- aria-label="Previous"
- className="size-7 rounded-r-none border-r-0 p-0"
- disabled={!mobileNav.prevId}
- onClick={() => mobileNavGoTo(mobileNav.prevId)}
- size="icon"
- variant="outline"
- >
- <ChevronLeft />
- </Button>
- <Button
- aria-label="Open flows list"
- className="h-7 min-w-12 rounded-none border-x px-2 font-mono text-xs tabular-nums"
- disabled={mobileNav.currentIndex === -1}
- onClick={() => setIsMobileNavSheetOpen(true)}
- variant="outline"
- >
- {mobilePositionLabel}
- </Button>
- <Button
- aria-label="Next"
- className="size-7 rounded-l-none border-l-0 p-0"
- disabled={!mobileNav.nextId}
- onClick={() => mobileNavGoTo(mobileNav.nextId)}
- size="icon"
- variant="outline"
- >
- <ChevronRight />
- </Button>
+ <DetailNavigationButtons<FlowItem>
+ controller={flowNav}
+ sheetTitle="Flows"
+ size="sm"
+ />
</div>
</DropdownMenuItem>
{flowId && (
@@ -549,34 +479,10 @@ const Flow = () => {
</header>
{isMobile && flow && (
<DetailNavigationSheet<FlowItem>
- currentId={flowToolbarProps.currentId}
- currentIndex={mobileNav.currentIndex}
- getId={flowToolbarProps.getId}
- getLabel={flowToolbarProps.getLabel}
- items={mobileNav.filteredItems}
- onItemSelect={mobileNavSelectItem}
- onOpenChange={setIsMobileNavSheetOpen}
- open={isMobileNavSheetOpen}
- renderItem={(item, isCurrent) => (
- <>
- <FlowStatusIcon
- className="size-3 shrink-0"
- status={item.status}
- />
- <span className={isCurrent ? 'truncate font-medium' : 'truncate'}>
- {item.title || `Flow #${item.id}`}
- </span>
- <Badge
- className="ml-auto shrink-0 font-mono text-[10px]"
- variant="outline"
- >
- #{item.id}
- </Badge>
- </>
- )}
+ controller={flowNav}
+ renderItem={renderFlowItem}
sheetIcon={<GitFork className="size-4" />}
sheetTitle="Flows"
- total={mobileNav.total}
/>
)}
<div className="relative flex h-[calc(100dvh-3rem)] w-full max-w-full flex-1">
diff --git a/frontend/src/pages/templates/template.tsx b/frontend/src/pages/templates/template.tsx
index 676f7725..60d819b1 100644
--- a/frontend/src/pages/templates/template.tsx
+++ b/frontend/src/pages/templates/template.tsx
@@ -1,8 +1,8 @@
+import type { ReactNode } from 'react';
+
import { zodResolver } from '@hookform/resolvers/zod';
import {
ChevronDown,
- ChevronLeft,
- ChevronRight,
Ellipsis,
FileSymlink,
FileText,
@@ -15,12 +15,16 @@ import {
} from 'lucide-react';
import { useCallback, useEffect, useMemo, useState } from 'react';
import { useForm } from 'react-hook-form';
-import { useNavigate, useParams, useSearchParams } from 'react-router-dom';
+import { useNavigate, useParams } from 'react-router-dom';
import { toast } from 'sonner';
import { z } from 'zod';
import ConfirmationDialog from '@/components/shared/confirmation-dialog';
-import { DetailNavigationSheet, DetailNavigationToolbar, useNavigation } from '@/components/shared/detail-navigation';
+import {
+ DetailNavigationButtons,
+ DetailNavigationSheet,
+ DetailNavigationToolbar,
+} from '@/components/shared/detail-navigation';
import { InlineEditInput, useInlineEdit } from '@/components/shared/inline-edit';
import { Badge } from '@/components/ui/badge';
import { Breadcrumb, BreadcrumbItem, BreadcrumbList, BreadcrumbPage } from '@/components/ui/breadcrumb';
@@ -45,7 +49,6 @@ import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip
import { useTemplateDetailNavigation } from '@/features/templates/use-template-detail-navigation';
import { useFlowTemplateQuery } from '@/graphql/types';
import { useBreakpoint } from '@/hooks/use-breakpoint';
-import { mergeHrefWithSearchParams } from '@/lib/url-params';
import { cn } from '@/lib/utils';
import { type Template, useTemplates } from '@/providers/templates-provider';
@@ -233,9 +236,12 @@ Action plan:
},
];
+const renderTemplateItem = (item: Template, isCurrent: boolean): ReactNode => (
+ <span className={isCurrent ? 'truncate font-medium' : 'truncate'}>{item.title}</span>
+);
+
const Template = () => {
const navigate = useNavigate();
- const [searchParams] = useSearchParams();
const { templateId } = useParams<{ templateId?: string }>();
const { createTemplate, deleteTemplate, updateTemplate } = useTemplates();
@@ -245,55 +251,7 @@ const Template = () => {
// Pass `null` while creating a new template — there is no "current item"
// to highlight, and the toolbar shouldn't render at all anyway (gated
// below by `canShowActions`).
- const { toolbarProps: templateToolbarProps } = useTemplateDetailNavigation(isNew ? null : templateId);
-
- // Mirror what `<DetailNavigationToolbar>` computes internally so the
- // mobile menu items share the same filtered subset as the desktop toolbar.
- const mobileNav = useNavigation<Template>({
- currentId: templateToolbarProps.currentId,
- getId: templateToolbarProps.getId,
- getSearchableText: templateToolbarProps.getSearchableText ?? templateToolbarProps.getLabel,
- items: templateToolbarProps.items,
- query: templateToolbarProps.filter,
- });
- const [isMobileNavSheetOpen, setIsMobileNavSheetOpen] = useState(false);
-
- const mobileNavGoTo = useCallback(
- (id: null | string) => {
- if (!id) {
- return;
- }
-
- const target = mobileNav.filteredItems.find((item) => String(templateToolbarProps.getId(item)) === id);
-
- if (!target) {
- return;
- }
-
- navigate(mergeHrefWithSearchParams(templateToolbarProps.getHref(target), searchParams), {
- replace: true,
- });
- },
- [mobileNav.filteredItems, navigate, searchParams, templateToolbarProps],
- );
-
- const mobileNavSelectItem = useCallback(
- (item: Template) => {
- setIsMobileNavSheetOpen(false);
- navigate(mergeHrefWithSearchParams(templateToolbarProps.getHref(item), searchParams), {
- replace: true,
- });
- },
- [navigate, searchParams, templateToolbarProps],
- );
-
- const mobilePositionLabel = useMemo(
- () =>
- mobileNav.total === 0 || mobileNav.currentIndex === -1
- ? `–/${mobileNav.total}`
- : `${mobileNav.currentIndex + 1}/${mobileNav.total}`,
- [mobileNav.currentIndex, mobileNav.total],
- );
+ const templateNav = useTemplateDetailNavigation(isNew ? null : templateId);
const [isAsideOpen, setIsAsideOpen] = useState(false);
const [expandedPresetIndex, setExpandedPresetIndex] = useState<null | number>(null);
@@ -491,7 +449,8 @@ const Template = () => {
<div className="flex shrink-0 items-center gap-2">
{canShowActions && !isMobile && (
<DetailNavigationToolbar<Template>
- {...templateToolbarProps}
+ controller={templateNav}
+ renderItem={renderTemplateItem}
sheetIcon={<FileText className="size-4" />}
sheetTitle="Templates"
/>
@@ -519,7 +478,7 @@ const Template = () => {
className="min-w-24"
onCloseAutoFocus={handleDropdownCloseAutoFocus}
>
- {isMobile && mobileNav.total > 0 && (
+ {isMobile && templateNav.total > 0 && (
<>
<DropdownMenuItem
className="cursor-default hover:bg-transparent focus:bg-transparent"
@@ -528,35 +487,11 @@ const Template = () => {
<FileText className="size-4" />
Templates
<div className="-my-1.5 -mr-2 ml-auto flex items-center">
- <Button
- aria-label="Previous"
- className="size-7 rounded-r-none border-r-0 p-0"
- disabled={!mobileNav.prevId}
- onClick={() => mobileNavGoTo(mobileNav.prevId)}
- size="icon"
- variant="outline"
- >
- <ChevronLeft />
- </Button>
- <Button
- aria-label="Open templates list"
- className="h-7 min-w-12 rounded-none border-x px-2 font-mono text-xs tabular-nums"
- disabled={mobileNav.currentIndex === -1}
- onClick={() => setIsMobileNavSheetOpen(true)}
- variant="outline"
- >
- {mobilePositionLabel}
- </Button>
- <Button
- aria-label="Next"
- className="size-7 rounded-l-none border-l-0 p-0"
- disabled={!mobileNav.nextId}
- onClick={() => mobileNavGoTo(mobileNav.nextId)}
- size="icon"
- variant="outline"
- >
- <ChevronRight />
- </Button>
+ <DetailNavigationButtons<Template>
+ controller={templateNav}
+ sheetTitle="Templates"
+ size="sm"
+ />
</div>
</DropdownMenuItem>
<DropdownMenuSeparator />
@@ -590,17 +525,10 @@ const Template = () => {
</header>
{isMobile && canShowActions && (
<DetailNavigationSheet<Template>
- currentId={templateToolbarProps.currentId}
- currentIndex={mobileNav.currentIndex}
- getId={templateToolbarProps.getId}
- getLabel={templateToolbarProps.getLabel}
- items={mobileNav.filteredItems}
- onItemSelect={mobileNavSelectItem}
- onOpenChange={setIsMobileNavSheetOpen}
- open={isMobileNavSheetOpen}
+ controller={templateNav}
+ renderItem={renderTemplateItem}
sheetIcon={<FileText className="size-4" />}
sheetTitle="Templates"
- total={mobileNav.total}
/>
)}
</>