From fc2238b5a975db47892dae300743ee7d9e224f19 Mon Sep 17 00:00:00 2001 From: Julien BIANCHI Date: Thu, 12 Nov 2026 11:26:43 +0100 Subject: [PATCH 1/5] refactor: extract the console layout from the operations layout The API docs page reuses the operations console's shell: the sidebar of grouped pages, the header naming the current one, the mobile nav that scrolls sideways, the theme switch and the way back to /dev/null, which a guest finds on a phone too. ConsoleLayout now draws that shell from its props: the brand chip and label, the nav landmark's own label, whether its links prefetch, and a title that falls back to the console's name. OperationsLayout keeps what only operations does (polling, refreshing, the remotes dock) and passes its pages in, with Moderation as an item elsewhere and prefetch off, as before. Nothing changes on screen: captures before and after differ only in the pulsing live dot. --- resources/js/layouts/console/layout.tsx | 284 ++++++++++++++++ resources/js/layouts/operations/layout.tsx | 371 +++++---------------- tests/Unit/ConsoleLayout.test.tsx | 207 ++++++++++++ 3 files changed, 583 insertions(+), 279 deletions(-) create mode 100644 resources/js/layouts/console/layout.tsx create mode 100644 tests/Unit/ConsoleLayout.test.tsx diff --git a/resources/js/layouts/console/layout.tsx b/resources/js/layouts/console/layout.tsx new file mode 100644 index 000000000..1e829b9ca --- /dev/null +++ b/resources/js/layouts/console/layout.tsx @@ -0,0 +1,284 @@ +import { Link } from '@inertiajs/react'; +import type { InertiaLinkProps } from '@inertiajs/react'; +import type { LucideIcon } from 'lucide-react'; +import { ArrowUpRight } from 'lucide-react'; +import { useEffect, useRef } from 'react'; +import type { ReactNode } from 'react'; +import AppLogoIcon from '@/components/app-logo-icon'; +import AppWordmark from '@/components/app-wordmark'; +import AppearanceToggleTab from '@/components/appearance-tabs'; +import { UserAvatar } from '@/components/user-avatar'; +import { cn } from '@/lib/utils'; +import type { User } from '@/types'; + +export type ConsoleNavItem = { + key: string; + title: string; + description: string; + href: NonNullable; + icon: LucideIcon; + external?: boolean; +}; + +export type ConsoleNavGroup = { + label: string; + items: ConsoleNavItem[]; +}; + +const itemClassName = + 'flex h-9 shrink-0 items-center gap-2.5 rounded-lg px-2.5 text-sm font-medium whitespace-nowrap text-muted-foreground transition-colors hover:bg-accent hover:text-foreground'; + +function NavItem({ + item, + isActive, + prefetch, +}: { + item: ConsoleNavItem; + isActive: boolean; + prefetch: boolean; +}) { + if (item.external) { + return ( + + + {item.title} + + + ); + } + + return ( + + + {item.title} + + ); +} + +function Brand({ + chip, + label, + href, + prefetch, +}: { + chip: string; + label: string; + href: NonNullable; + prefetch: boolean; +}) { + return ( + + + + + {chip} + + + ); +} + +/** + * The shell of a standalone console beside the log, such as Operations: a sidebar of grouped pages, a header naming + * the current one, and a way back to /dev/null. Its pages prefetch on hover only when the console asks for it. + */ +export default function ConsoleLayout({ + chip, + label, + navLabel, + brandHref, + prefetch = false, + groups, + current, + backHref, + user, + headerActions, + children, +}: { + chip: string; + label: string; + navLabel: string; + brandHref: NonNullable; + prefetch?: boolean; + groups: ConsoleNavGroup[]; + current: string; + backHref: string; + user: User | null; + headerActions?: ReactNode; + children: ReactNode; +}) { + const items = groups.flatMap((group) => group.items); + const page = items.find((item) => item.key === current && !item.external); + const mobileNav = useRef(null); + + useEffect(() => { + mobileNav.current + ?.querySelector('[aria-current="page"]') + ?.scrollIntoView({ block: 'nearest', inline: 'nearest' }); + }, [current]); + + return ( +
+ + +
+
+
+
+ +
+
+

+ {page?.title ?? navLabel} +

+

+ {page?.description} +

+
+ +
+ {headerActions} + + {user ? ( + + ) : ( + + )} + +
+
+ + +
+ +
+
+

+ {page?.title ?? navLabel} +

+

+ {page?.description} +

+
+ {children} +
+
+
+ ); +} diff --git a/resources/js/layouts/operations/layout.tsx b/resources/js/layouts/operations/layout.tsx index e8c7c913e..22548ec0e 100644 --- a/resources/js/layouts/operations/layout.tsx +++ b/resources/js/layouts/operations/layout.tsx @@ -1,9 +1,6 @@ -import { Link, router, usePage, usePoll } from '@inertiajs/react'; -import type { InertiaLinkProps } from '@inertiajs/react'; -import type { LucideIcon } from 'lucide-react'; +import { router, usePage, usePoll } from '@inertiajs/react'; import { Activity, - ArrowUpRight, ChartNoAxesCombined, Flag, Gauge, @@ -18,7 +15,7 @@ import { ShieldCheck, TrendingUp, } from 'lucide-react'; -import { useEffect, useRef, useState } from 'react'; +import { useState } from 'react'; import type { PropsWithChildren } from 'react'; import EmailController from '@/actions/App/Http/Controllers/EmailController'; import FeatureController from '@/actions/App/Http/Controllers/FeatureController'; @@ -31,13 +28,11 @@ import ProductMetricsController from '@/actions/App/Http/Controllers/ProductMetr import SiteActivityController from '@/actions/App/Http/Controllers/SiteActivityController'; import SystemHealthController from '@/actions/App/Http/Controllers/SystemHealthController'; import TrafficController from '@/actions/App/Http/Controllers/TrafficController'; -import AppLogoIcon from '@/components/app-logo-icon'; -import AppWordmark from '@/components/app-wordmark'; -import AppearanceToggleTab from '@/components/appearance-tabs'; import { ChatDock } from '@/components/chat/chat-dock'; import { Button } from '@/components/ui/button'; -import { UserAvatar } from '@/components/user-avatar'; import { useRemoteAlerts, useRemoteUpdates } from '@/hooks/use-chat'; +import ConsoleLayout from '@/layouts/console/layout'; +import type { ConsoleNavGroup } from '@/layouts/console/layout'; import { backgroundPollOptions } from '@/lib/background-poll'; import { cn } from '@/lib/utils'; import { home } from '@/routes'; @@ -104,35 +99,27 @@ const POLL_PROPS = Object.fromEntries( ]), ) as Record; -type NavEntry = { - page: OperationsPage; - title: string; - description: string; - href: NonNullable; - icon: LucideIcon; -}; - -function navGroups(): { label: string; items: NavEntry[] }[] { +function navGroups(): ConsoleNavGroup[] { return [ { label: 'Monitor', items: [ { - page: 'operations/show', + key: 'operations/show', title: 'Overview', description: 'What needs attention, and what is fine', href: OperationsController.show(), icon: LayoutDashboard, }, { - page: 'operations/health', + key: 'operations/health', title: 'Health', description: 'Services, queues, failed jobs and backlogs', href: SystemHealthController.show(), icon: HeartPulse, }, { - page: 'operations/events', + key: 'operations/events', title: 'Events', description: 'Everything that happened, newest first', href: OperationsEventController.index(), @@ -144,28 +131,28 @@ function navGroups(): { label: string; items: NavEntry[] }[] { label: 'Product', items: [ { - page: 'operations/forecasts', + key: 'operations/forecasts', title: 'Forecasts', description: 'Where the trends are heading next', href: ForecastController.show(), icon: TrendingUp, }, { - page: 'operations/metrics', + key: 'operations/metrics', title: 'Growth', description: 'Acquisition, activation and retention', href: ProductMetricsController.show(), icon: ChartNoAxesCombined, }, { - page: 'operations/activity', + key: 'operations/activity', title: 'Activity', description: 'Commits, replies and signups over time', href: SiteActivityController.show(), icon: Activity, }, { - page: 'operations/traffic', + key: 'operations/traffic', title: 'Traffic', description: 'Visitors and where they come from', href: TrafficController.show(), @@ -177,14 +164,14 @@ function navGroups(): { label: string; items: NavEntry[] }[] { label: 'Control', items: [ { - page: 'operations/features', + key: 'operations/features', title: 'Features', description: 'Choose who can use each feature', href: FeatureController.index(), icon: Flag, }, { - page: 'operations/emails', + key: 'operations/emails', title: 'Emails', description: 'Write to everyone, or the people you pick', href: EmailController.create(), @@ -192,6 +179,19 @@ function navGroups(): { label: string; items: NavEntry[] }[] { }, ], }, + { + label: 'Elsewhere', + items: [ + { + key: 'moderation', + title: 'Moderation', + description: 'Commits waiting for review', + href: ModerationController.show().url, + icon: ShieldCheck, + external: true, + }, + ], + }, ]; } @@ -201,41 +201,6 @@ function Poll({ only }: { only: string[] }) { return null; } -function NavItem({ item, isActive }: { item: NavEntry; isActive: boolean }) { - return ( - - - {item.title} - - ); -} - -function Brand() { - return ( - - - - - ops - - - ); -} - export default function OperationsLayout({ children }: PropsWithChildren) { const { component, props } = usePage(); const page = component as OperationsPage; @@ -243,26 +208,16 @@ export default function OperationsLayout({ children }: PropsWithChildren) { const [isLive, setIsLive] = useState(true); const only = PAGE_PROPS[page] ?? []; const polls = !ON_DEMAND.includes(page); - const groups = navGroups(); - const items = groups.flatMap((group) => group.items); - const current = items.find((item) => item.page === page); const user = props.auth.user; const hasRemotes = user !== null && props.auth.remotes !== null; const backHref = props.auth.log === null ? home().url : LogController.show(props.auth.log).url; - const mobileNav = useRef(null); useRemoteAlerts(hasRemotes ? user.id : null); useRemoteUpdates(hasRemotes ? user.id : null); - useEffect(() => { - mobileNav.current - ?.querySelector('[aria-current="page"]') - ?.scrollIntoView({ block: 'nearest', inline: 'nearest' }); - }, [page]); - const refresh = () => { if (isRefreshing) { return; @@ -285,226 +240,84 @@ export default function OperationsLayout({ children }: PropsWithChildren) { }; return ( -
+ <> {polls && isLive && ( )} - - -
-
-
-
- -
-
-

- {current?.title ?? 'Operations'} -

-

- {current?.description} -

-
- -
- {polls ? ( - - ) : ( - - - on demand - - )} + + {polls ? ( - {user && ( - - - - )} -
-
- - -
- -
-
-

- {current?.title ?? 'Operations'} -

-

- {current?.description} -

-
- {children} -
-
+ + + + } + > + {children} + {hasRemotes && } -
+ ); } diff --git a/tests/Unit/ConsoleLayout.test.tsx b/tests/Unit/ConsoleLayout.test.tsx new file mode 100644 index 000000000..ab0a07fe7 --- /dev/null +++ b/tests/Unit/ConsoleLayout.test.tsx @@ -0,0 +1,207 @@ +/// + +import assert from 'node:assert/strict'; +import { createInertiaApp } from '@inertiajs/react'; +import type { InertiaLinkProps } from '@inertiajs/react'; +import { BookOpen, ShieldCheck, Users } from 'lucide-react'; +import { createElement } from 'react'; +import type { ComponentProps } from 'react'; +import { renderToString } from 'react-dom/server'; +import { beforeEach, test, vi } from 'vite-plus/test'; +import ConsoleLayout from '../../resources/js/layouts/console/layout'; +import type { User } from '../../resources/js/types'; + +const links = vi.hoisted(() => [] as InertiaLinkProps[]); + +// Inertia renders nothing of `prefetch` on the server, so the links' props are read as they are given. +vi.mock('@inertiajs/react', async (importOriginal) => { + const inertia = await importOriginal(); + + return { + ...inertia, + Link: (props: InertiaLinkProps) => { + links.push(props); + + return createElement(inertia.Link, props); + }, + }; +}); + +beforeEach(() => { + links.length = 0; +}); + +function prefetchOf(href: string): InertiaLinkProps['prefetch'][] { + return links + .filter((link) => link.href === href) + .map((link) => link.prefetch); +} + +const groups: ComponentProps['groups'] = [ + { + label: 'Guide', + items: [ + { + key: 'introduction', + title: 'Introduction', + description: 'What the API is for', + href: '/docs/api/introduction', + icon: BookOpen, + }, + ], + }, + { + label: 'Reference', + items: [ + { + key: 'users', + title: 'Users', + description: 'Profiles and who follows whom', + href: '/docs/api/users', + icon: Users, + }, + ], + }, + { + label: 'Elsewhere', + items: [ + { + key: 'moderation', + title: 'Moderation', + description: 'The review queue', + href: '/moderation', + icon: ShieldCheck, + external: true, + }, + ], + }, +]; + +async function render( + props: Partial> = {}, +): Promise { + const result = await createInertiaApp({ + page: { + component: 'console', + props: { errors: {} }, + url: '/docs/api/users', + version: null, + clearHistory: false, + encryptHistory: false, + rescuedProps: [], + rememberedState: {}, + flash: {}, + }, + resolve: () => () => ( + +

content

+
+ ), + render: renderToString, + setup: ({ App, props: appProps }) => , + }); + + return result.body; +} + +test('brands the console with its chip', async () => { + const html = await render(); + + assert.match(html, />api<\/span>/); + assert.match(html, /aria-label="\/dev\/null API"/); +}); + +test('names the navigation after the console, apart from the brand link', async () => { + const html = await render(); + + assert.equal(html.match(/