@flamingo-stack/openframe-frontend-core 0.0.685 → 0.0.686-2463.7461.1

package/src/components/chat/chat-top-navigation.tsx

@@ -0,0 +1,109 @@
+'use client';
+
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import { cn } from '../../utils/cn';
+import { Settings01Icon, SidebarIcon } from '../icons-v2-generated';
+import { Skeleton } from '../ui/skeleton';
+import { SquareAvatar } from '../ui/square-avatar';
+
+export interface ChatTopNavigationProps extends HTMLAttributes<HTMLElement> {
+  /** Who the user is talking to. */
+  name: string;
+  /** Line under the name (e.g. "Your AI Assistant", "IT Technician"). */
+  subtitle?: string;
+  avatarUrl?: string | null;
+  /** Actions after the identity (e.g. "Request a Technician"). */
+  actions?: ReactNode;
+  /** Shows the sidebar toggle at the start of the bar. */
+  onToggleSidebar?: () => void;
+  /** Whether the sidebar is currently shown; drives the toggle's state. */
+  sidebarOpen?: boolean;
+  /** Shows the settings button at the end of the bar. */
+  onOpenSettings?: () => void;
+  /** Content above the bar, full width (e.g. a "Back to ..." strip). */
+  before?: ReactNode;
+  /** Identity still resolving: placeholders instead of a default name that
+   *  would flash before the tenant's branding lands. */
+  isLoading?: boolean;
+}
+
+const edgeButtonClass = cn(
+  'flex size-14 shrink-0 items-center justify-center border-ods-border text-ods-text-secondary',
+  'hover:text-ods-text-primary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ods-focus',
+  '[&_svg]:size-6',
+);
+
+/**
+ * Top bar of the fae chat v2 layout (Figma `chat-top-navigation`): an optional
+ * sidebar toggle, the counterpart's avatar, name and role, the host's actions
+ * and an optional settings button, split by vertical dividers.
+ */
+const ChatTopNavigation = forwardRef<HTMLElement, ChatTopNavigationProps>(
+  (
+    {
+      className,
+      name,
+      subtitle,
+      avatarUrl,
+      actions,
+      onToggleSidebar,
+      sidebarOpen,
+      onOpenSettings,
+      before,
+      isLoading,
+      ...props
+    },
+    ref,
+  ) => (
+    <header ref={ref} className={cn('flex shrink-0 flex-col bg-ods-bg', className)} {...props}>
+      {before}
+      <div className="flex h-14 items-stretch border-b border-ods-border">
+        {onToggleSidebar && (
+          <button
+            type="button"
+            onClick={onToggleSidebar}
+            aria-label={sidebarOpen ? 'Hide sidebar' : 'Show sidebar'}
+            aria-expanded={sidebarOpen}
+            className={cn(edgeButtonClass, 'border-r')}
+          >
+            <SidebarIcon />
+          </button>
+        )}
+        <div className="flex min-w-0 flex-1 items-center gap-[var(--spacing-system-m)] px-[var(--spacing-system-m)]">
+          {isLoading ? (
+            <>
+              <Skeleton className="size-10 shrink-0 rounded-full" />
+              <div className="flex min-w-0 flex-1 flex-col gap-[var(--spacing-system-xxs)]">
+                <Skeleton className="h-5 w-24" />
+                <Skeleton className="h-4 w-32" />
+              </div>
+            </>
+          ) : (
+            <>
+              <SquareAvatar src={avatarUrl ?? undefined} alt={name} fallback={name} size="md" variant="round" />
+              <div className="flex min-w-0 flex-1 flex-col">
+                <p className="truncate text-ods-text-primary text-h3">{name}</p>
+                {subtitle && <p className="truncate text-ods-text-secondary text-h6">{subtitle}</p>}
+              </div>
+            </>
+          )}
+          {actions && <div className="flex shrink-0 items-center gap-[var(--spacing-system-xs)]">{actions}</div>}
+        </div>
+        {onOpenSettings && (
+          <button
+            type="button"
+            onClick={onOpenSettings}
+            aria-label="Settings"
+            className={cn(edgeButtonClass, 'border-l')}
+          >
+            <Settings01Icon />
+          </button>
+        )}
+      </div>
+    </header>
+  ),
+);
+
+ChatTopNavigation.displayName = 'ChatTopNavigation';
+
+export { ChatTopNavigation };

package/src/components/chat/error-message-display.tsx

@@ -3,9 +3,11 @@
 import { forwardRef, useState } from 'react';
 import { cn } from '../../utils/cn';
 import { AlertCircleIcon } from '../icons-v2-generated';
+import { useChatAppearance } from './chat-appearance-context';
 import { ExpandChevron } from './expand-chevron';
 import { useCollapsible } from './hooks/use-collapsible';
 import type { ErrorMessageDisplayProps } from './types';
+import { CHAT_APPEARANCE } from './types/chat.types';
 
 const iconTint = {
   error: 'text-ods-error',
@@ -18,11 +20,20 @@ const ErrorMessageDisplay = forwardRef<HTMLDivElement, ErrorMessageDisplayProps>
     const [expanded, setExpanded] = useState(false);
     const { innerRef, containerStyle } = useCollapsible({ expanded });
     const hasDetails = Boolean(details);
+    // v2 (fae chat `chat-info-block`): outlined on the page surface, the title
+    // always reads as a heading, and the row spacing comes from the thread.
+    const isV2 = useChatAppearance() === CHAT_APPEARANCE.V2;
 
     return (
       <div
         ref={ref}
-        className={cn('mb-[var(--spacing-system-xsf)] rounded-md bg-ods-card p-[var(--spacing-system-xsf)]', className)}
+        className={cn(
+          'rounded-md',
+          isV2
+            ? 'border border-ods-border bg-ods-bg p-[var(--spacing-system-xs)]'
+            : 'mb-[var(--spacing-system-xsf)] bg-ods-card p-[var(--spacing-system-xsf)]',
+          className,
+        )}
         {...props}
       >
         <button
@@ -40,7 +51,8 @@ const ErrorMessageDisplay = forwardRef<HTMLDivElement, ErrorMessageDisplayProps>
           <span
             className={cn(
               'min-w-0 flex-1 text-h5',
-              expanded ? 'text-ods-text-primary' : 'truncate text-ods-text-secondary',
+              expanded || isV2 ? 'text-ods-text-primary' : 'text-ods-text-secondary',
+              !expanded && 'truncate',
             )}
           >
             {title}
@@ -50,7 +62,13 @@ const ErrorMessageDisplay = forwardRef<HTMLDivElement, ErrorMessageDisplayProps>
 
         {hasDetails && (
           <div style={containerStyle}>
-            <div ref={innerRef} className="px-[var(--spacing-system-lf)] pt-[var(--spacing-system-xsf)]">
+            <div
+              ref={innerRef}
+              className={cn(
+                'px-[var(--spacing-system-lf)]',
+                isV2 ? 'pt-[var(--spacing-system-xs)]' : 'pt-[var(--spacing-system-xsf)]',
+              )}
+            >
               <p className="text-ods-text-primary text-h6">{details}</p>
             </div>
           </div>

package/src/components/chat/index.ts

@@ -6,7 +6,9 @@ export * from './approval-batch-message';
 export * from './escalation-offer-message';
 export * from './ticket-escalated-message';
 export * from './ticket-event-message';
+export * from './system-event-message';
 export * from './ai-assistant-info';
+export * from './chat-appearance-context';
 export * from './context-compaction-display';
 export * from './expand-chevron';
 export * from './thinking-display';
@@ -47,6 +49,10 @@ export * from './context-items-list';
 export * from './chat-archive-page';
 export * from './model-display';
 export * from './chat-sidebar';
+export * from './chat-nav-sidebar';
+export * from './chat-list-empty-state';
+export * from './chat-top-navigation';
+export * from './onboarding-carousel';
 export type { ChatRef } from './chat-ref.types';
 export { remarkCardLinks } from './remark-card-links';
 export { remarkMentionChips } from './remark-mention-chips';

package/src/components/chat/msp-organization-card.tsx

@@ -22,6 +22,12 @@ export interface MspOrganizationCardProps {
   href?: string;
   /** Click handler for the trailing action (used when `href` is not set). */
   onOpenWebsite?: () => void;
+  /**
+   * `card` (default): the welcome-screen card, title with the website beneath.
+   * `footer`: the compact sidebar footer of the fae chat v2 layout, a caption
+   * "Your IT is managed by" over the name, no website line, no card chrome.
+   */
+  variant?: 'card' | 'footer';
   /** Appended to the root element. */
   className?: string;
 }
@@ -44,10 +50,39 @@ export function MspOrganizationCard({
   title,
   href,
   onOpenWebsite,
+  variant = 'card',
   className,
 }: MspOrganizationCardProps) {
   const actionLabel = website ? `Open ${website}` : 'Open organization website';
 
+  if (variant === 'footer') {
+    return (
+      <div
+        className={cn(
+          'flex items-center gap-[var(--spacing-system-s)] px-[var(--spacing-system-m)] py-[var(--spacing-system-s)]',
+          className,
+        )}
+      >
+        <SquareAvatar src={logoUrl} alt={name} fallback={name} size="sm" variant="square" />
+        <div className="flex min-w-0 flex-1 flex-col">
+          <span className="truncate text-ods-text-secondary text-h6">Your IT is managed by</span>
+          <span className="truncate text-ods-text-primary text-h4">{title ?? name}</span>
+        </div>
+        {href ? (
+          <Button asChild variant="outline" size="icon-sm" aria-label={actionLabel}>
+            <a href={href} target="_blank" rel="noreferrer noopener">
+              <ExternalLinkIcon />
+            </a>
+          </Button>
+        ) : onOpenWebsite ? (
+          <Button variant="outline" size="icon-sm" aria-label={actionLabel} onClick={onOpenWebsite}>
+            <ExternalLinkIcon />
+          </Button>
+        ) : null}
+      </div>
+    );
+  }
+
   return (
     <div
       className={cn(

package/src/components/chat/onboarding-carousel.tsx

@@ -0,0 +1,162 @@
+'use client';
+
+import { type CSSProperties, type KeyboardEvent, type ReactNode, useState } from 'react';
+import { cn } from '../../utils/cn';
+import { Button } from '../ui/button';
+
+export interface OnboardingCarouselStep {
+  id: string;
+  /** Glyph in the 64px tile above the title. Pass it sized to 28px. */
+  icon: ReactNode;
+  title: ReactNode;
+  description?: ReactNode;
+}
+
+export interface OnboardingCarouselProps {
+  steps: OnboardingCarouselStep[];
+  /** The last step's primary action. */
+  onComplete: () => void;
+  /** Label of the last step's primary action. */
+  completeLabel?: string;
+  previousLabel?: string;
+  nextLabel?: string;
+  /** Accessible name of the carousel region. */
+  label?: string;
+  className?: string;
+}
+
+/**
+ * Step-by-step introduction: one card at a time in the middle, its neighbours
+ * peeking in from the sides under an edge fade, dots below, Previous / Next
+ * underneath. The last step swaps Next for `completeLabel`. There is no skip:
+ * the design walks every step. Fills the height its parent gives it: the cards
+ * stretch, the dots and buttons keep their size.
+ */
+export function OnboardingCarousel({
+  steps,
+  onComplete,
+  completeLabel = 'Start Chat',
+  previousLabel = 'Previous Step',
+  nextLabel = 'Next Step',
+  label = 'Introduction',
+  className,
+}: OnboardingCarouselProps) {
+  const [index, setIndex] = useState(0);
+  const lastIndex = steps.length - 1;
+  const isFirst = index === 0;
+  const isLast = index === lastIndex;
+
+  const goTo = (next: number) => setIndex(Math.min(Math.max(next, 0), lastIndex));
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLElement>) => {
+    if (event.key === 'ArrowRight') goTo(index + 1);
+    else if (event.key === 'ArrowLeft') goTo(index - 1);
+    else return;
+    event.preventDefault();
+  };
+
+  // Card width and the gap between cards drive both the card size and the
+  // track offset, so they live in one place. Percentages resolve against the
+  // viewport width in both uses (the track is as wide as the viewport).
+  const trackStyle = {
+    '--onboarding-card-w': 'min(600px, calc(100% - 2 * var(--spacing-system-xl)))',
+    '--onboarding-gap': 'var(--spacing-system-lf)',
+    transform: `translateX(calc(${-index} * (var(--onboarding-card-w) + var(--onboarding-gap))))`,
+  } as CSSProperties;
+
+  // The design's large steps (card padding, dots to buttons) are 80px at the
+  // app's 1024px default width, where `--spacing-system-xxl` is still 48px:
+  // spelled as twice the fixed 40px step.
+  return (
+    <section
+      aria-roledescription="carousel"
+      aria-label={label}
+      onKeyDown={handleKeyDown}
+      className={cn(
+        'flex min-h-0 w-full flex-1 flex-col items-center gap-[calc(2*var(--spacing-system-xlf))]',
+        className,
+      )}
+    >
+      <div className="flex min-h-0 w-full flex-1 flex-col items-center gap-[var(--spacing-system-xs)]">
+        <div className="relative flex min-h-0 w-full flex-1 overflow-hidden">
+          <div
+            className="flex w-full gap-[var(--onboarding-gap)] transition-transform duration-300 ease-out motion-reduce:transition-none"
+            style={trackStyle}
+          >
+            {steps.map((step, i) => {
+              const isCurrent = i === index;
+              return (
+                <div
+                  key={step.id}
+                  role="group"
+                  aria-roledescription="slide"
+                  aria-label={`${i + 1} of ${steps.length}`}
+                  aria-hidden={!isCurrent}
+                  inert={!isCurrent || undefined}
+                  className={cn(
+                    'flex w-[var(--onboarding-card-w)] shrink-0 flex-col items-center justify-center gap-[var(--spacing-system-m)] rounded-md border border-ods-border bg-ods-card px-[var(--spacing-system-xl)] py-[calc(2*var(--spacing-system-xlf))] text-center',
+                    i === 0 && 'ml-[calc((100%-var(--onboarding-card-w))/2)]',
+                  )}
+                >
+                  <span className="flex size-16 shrink-0 items-center justify-center rounded-md border border-ods-border bg-ods-bg text-ods-accent">
+                    {step.icon}
+                  </span>
+                  <div className="flex flex-col gap-[var(--spacing-system-l)] text-ods-text-primary [word-break:break-word]">
+                    <h2 className="text-h2">{step.title}</h2>
+                    {step.description && <p className="whitespace-pre-line text-h6">{step.description}</p>}
+                  </div>
+                </div>
+              );
+            })}
+          </div>
+          <div className="pointer-events-none absolute inset-y-0 left-0 w-[120px] bg-gradient-to-r from-ods-bg to-transparent" />
+          <div className="pointer-events-none absolute inset-y-0 right-0 w-[120px] bg-gradient-to-l from-ods-bg to-transparent" />
+        </div>
+
+        {/* The slides only toggle visibility, which is not announced. */}
+        <p className="sr-only" aria-live="polite">
+          Step {index + 1} of {steps.length}: {steps[index]?.title}
+        </p>
+
+        <div className="flex items-center" role="group" aria-label="Choose step">
+          {steps.map((step, i) => {
+            const isCurrent = i === index;
+            return (
+              <Button
+                key={step.id}
+                variant="transparent"
+                aria-current={isCurrent ? 'step' : undefined}
+                aria-label={`Go to step ${i + 1}`}
+                onClick={() => goTo(i)}
+                className="flex size-6 shrink-0 items-center justify-center rounded-full p-0 md:h-6"
+              >
+                <span
+                  className={cn(
+                    'size-1.5 rounded-full transition-colors duration-150',
+                    isCurrent ? 'bg-ods-accent' : 'bg-ods-text-secondary',
+                  )}
+                />
+              </Button>
+            );
+          })}
+        </div>
+      </div>
+
+      <div className="flex flex-wrap items-center justify-center gap-[var(--spacing-system-m)]">
+        {/* aria-disabled, not disabled: stepping back onto the first card must
+            not drop keyboard focus from the button the user just pressed. */}
+        <Button
+          variant="outline"
+          className="w-[200px]"
+          aria-disabled={isFirst || undefined}
+          onClick={() => goTo(index - 1)}
+        >
+          {previousLabel}
+        </Button>
+        <Button variant="accent" className="w-[200px]" onClick={isLast ? onComplete : () => goTo(index + 1)}>
+          {isLast ? completeLabel : nextLabel}
+        </Button>
+      </div>
+    </section>
+  );
+}

package/src/components/chat/system-event-message.tsx

@@ -0,0 +1,54 @@
+'use client';
+
+import { forwardRef, type HTMLAttributes } from 'react';
+import { InfoCircleIcon } from '../icons-v2-generated';
+import { SquareAvatar } from '../ui/square-avatar';
+import { AiAssistantInfo } from './ai-assistant-info';
+
+// The chat backend announces a technician taking the chat over (or handing it
+// back) as a plain system line: "{name} joined the chat" / "{name} left the
+// chat". The copy is fixed server-side, so these two shapes are the contract.
+const JOINED = /^(.+) joined the chat$/;
+const LEFT = /^(.+) left the chat$/;
+
+export interface SystemEventMessageProps extends HTMLAttributes<HTMLDivElement> {
+  /** The system line as the backend sent it. */
+  text: string;
+  timestamp?: Date;
+}
+
+/**
+ * A system line in the fae chat v2 thread (`ai-assistant-info`,
+ * type=direct-chat): a technician joining becomes "Technician Joined" with
+ * their initials; any other line keeps its own wording under an info icon.
+ */
+const SystemEventMessage = forwardRef<HTMLDivElement, SystemEventMessageProps>(({ text, timestamp, ...props }, ref) => {
+  const joined = JOINED.exec(text)?.[1];
+  if (joined) {
+    return (
+      <AiAssistantInfo
+        ref={ref}
+        leading={<SquareAvatar alt={joined} fallback={joined} size="lg" variant="round" className="shrink-0" />}
+        title="Technician Joined"
+        body={`You're now chatting with ${joined}.`}
+        timestamp={timestamp}
+        {...props}
+      />
+    );
+  }
+  const left = LEFT.exec(text)?.[1];
+  return (
+    <AiAssistantInfo
+      ref={ref}
+      icon={<InfoCircleIcon className="size-6 text-ods-accent" />}
+      title={left ? 'Technician Left' : text}
+      body={left ? `${left} left the conversation.` : undefined}
+      timestamp={timestamp}
+      {...props}
+    />
+  );
+});
+
+SystemEventMessage.displayName = 'SystemEventMessage';
+
+export { SystemEventMessage };

package/src/components/chat/types/chat.types.ts

@@ -81,6 +81,21 @@ export const APPROVAL_BLOCK_VARIANT = {
 
 export type ApprovalBlockVariant = (typeof APPROVAL_BLOCK_VARIANT)[keyof typeof APPROVAL_BLOCK_VARIANT];
 
+/**
+ * Visual generation of a chat thread. `v2` is the fae chat v2 design: author
+ * names without the trailing colon, a 24px assistant avatar, 16px between
+ * messages, and in-thread info/error blocks on the page surface. `classic`
+ * (default) is everything that predates it. The Fae client opts in first;
+ * Mingo and the admin views stay classic until their own redesign lands, then
+ * `classic` goes away.
+ */
+export const CHAT_APPEARANCE = {
+  CLASSIC: 'classic',
+  V2: 'v2',
+} as const;
+
+export type ChatAppearance = (typeof CHAT_APPEARANCE)[keyof typeof CHAT_APPEARANCE];
+
 // ========== Connection Status Definitions ==========
 
 export const CONNECTION_STATUS = {

package/src/components/chat/types/component.types.ts

@@ -3,12 +3,14 @@
  */
 
 import type { ComponentType, HTMLAttributes, ReactNode, TextareaHTMLAttributes } from 'react';
+import type { AvatarStackPerson } from '../../ui/avatar-stack';
 import type { ChatRef } from '../chat-ref.types';
 import type { MspOrganizationCardProps } from '../msp-organization-card';
 import type {
   ApprovalBlockVariant,
   AssistantType,
   AuthorType,
+  ChatAppearance,
   ChatApprovalStatus,
   ConnectionStatus,
 } from './chat.types';
@@ -141,6 +143,9 @@ export interface ChatMessageEnhancedProps extends Omit<HTMLAttributes<HTMLDivEle
    *  (Fae desktop app) title-only card. Forwarded to
    *  ApprovalRequestMessage / ApprovalBatchMessage. */
   approvalVariant?: ApprovalBlockVariant;
+  /** Visual generation of the row. Omit to inherit the thread's
+   *  (`ChatMessageList.appearance`); `classic` outside a list. */
+  appearance?: ChatAppearance;
   assistantIcon?: ReactNode;
   avatar?: string | null;
   timestamp?: Date;
@@ -288,6 +293,9 @@ export interface ChatMessageListProps extends HTMLAttributes<HTMLDivElement> {
    *  `'client'` ONLY on true end-client surfaces — admin views of a Fae
    *  dialog (tickets dialog client tab) keep the default. */
   approvalVariant?: ApprovalBlockVariant;
+  /** Visual generation of the whole thread, blocks included. Default
+   *  `classic`; the Fae client passes `v2`. See `ChatAppearance`. */
+  appearance?: ChatAppearance;
   assistantIcon?: ReactNode;
   pendingApprovals?: MessageSegment[];
   onApprove?: ApprovalResolutionHandler;
@@ -442,7 +450,19 @@ export interface ChatInputProps extends Omit<TextareaHTMLAttributes<HTMLTextArea
   onSend?: (message: string) => void | boolean | Promise<boolean | void>;
   onStop?: () => void | Promise<void>;
   sending?: boolean;
+  /** Replaces the editor with the hand-off bar: the conversation is with the
+   *  technicians now, and the client waits for one of them to reply. */
   awaitingResponse?: boolean;
+  /** Faces shown in the v2 hand-off bar (the tenant's technicians). Omit or
+   *  pass an empty list for a text-only bar. */
+  awaitingTeam?: AvatarStackPerson[];
+  /** Size of the whole team when `awaitingTeam` is only a sample of it: the
+   *  bar shows those faces and "+N" for the rest. */
+  awaitingTeamCount?: number;
+  /** `v2`: the fae chat v2 hand-off bar ("Handed off to your technical
+   *  support team" + faces). `classic` (default): "Waiting for Technician
+   *  Response". Only the awaiting state differs. */
+  appearance?: ChatAppearance;
   /** Same `fullWidth` semantics as `ChatHeaderProps.fullWidth` — drops
    *  the default `max-w-ods-content-narrow` so the input fills the
    *  parent. */

package/src/components/ui/__tests__/avatar-stack.test.tsx

@@ -0,0 +1,25 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { AvatarStack } from '../avatar-stack';
+
+const people = [{ name: 'Ada Lin' }, { name: 'Roman Smith' }, { name: 'Michael Johnson' }];
+
+describe('AvatarStack', () => {
+  it('counts the overflow from the people it gets', () => {
+    render(<AvatarStack people={[...people, { name: 'Kim Park' }]} max={3} label="Technicians" />);
+    expect(screen.getByText('+1')).toHaveAttribute('title', 'Kim Park');
+  });
+
+  it('counts everyone not shown when the people are a sample of a larger group', () => {
+    render(<AvatarStack people={people} total={7} max={3} label="Technicians" />);
+    expect(screen.getByText('+4')).toHaveAttribute('title', '4 more');
+    expect(screen.getByRole('group')).toHaveAccessibleName(
+      'Technicians: Ada Lin, Roman Smith, Michael Johnson and 4 more',
+    );
+  });
+
+  it('shows no overflow when the sample is the whole group', () => {
+    render(<AvatarStack people={people} total={3} max={3} label="Technicians" />);
+    expect(screen.queryByText(/^\+/)).not.toBeInTheDocument();
+  });
+});

package/src/components/ui/__tests__/tab-navigation.test.tsx

@@ -1,7 +1,7 @@
 import { render, fireEvent, screen } from '@testing-library/react';
 import { describe, it, expect, beforeAll, vi } from 'vitest';
-import { mockReplace, setMockSearchParams } from '../../../../vitest.setup';
-import { TabNavigation, type TabItem } from '../tab-navigation';
+import { mockPush, mockReplace, setMockSearchParams } from '../../../../vitest.setup';
+import { TabNavigation, type TabItem, type TabNavigationUrlSyncOptions } from '../tab-navigation';
 
 beforeAll(() => {
   // jsdom ships no ResizeObserver; the tab strip observes itself on mount to
@@ -156,6 +156,60 @@ describe('TabNavigation with urlSync', () => {
       expect(nav.active).toBe('general');
     });
   });
+
+  describe('with sync options', () => {
+    function renderWith(options: TabNavigationUrlSyncOptions) {
+      let seen = '__never-rendered__';
+      render(
+        <TabNavigation tabs={TABS} urlSync={options}>
+          {active => {
+            seen = active;
+            return null;
+          }}
+        </TabNavigation>,
+      );
+      return {
+        get active() {
+          return seen;
+        },
+      };
+    }
+
+    it('reads and writes the param it was given, leaving `tab` alone', () => {
+      setMockSearchParams(new URLSearchParams('tab=general&view=software'));
+      const nav = renderWith({ paramName: 'view' });
+      expect(nav.active).toBe('software');
+
+      fireEvent.click(screen.getByText('General'));
+      expect(mockReplace).toHaveBeenCalledWith('/?tab=general&view=general', { scroll: false });
+    });
+
+    it('pushes a history entry when `replaceState` is off', () => {
+      setMockSearchParams(new URLSearchParams('tab=general'));
+      renderWith({ replaceState: false });
+      fireEvent.click(screen.getByText('Software'));
+
+      expect(mockPush).toHaveBeenCalledWith('/?tab=software', { scroll: false });
+      expect(mockReplace).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('a tab with a badge', () => {
+    it('draws the stamp after the label and names the tab with it', () => {
+      setMockSearchParams(new URLSearchParams('tab=general'));
+      render(
+        <TabNavigation tabs={[...TABS, { id: 'logs', label: 'Device Logs', badge: 'Beta' }]} urlSync>
+          {() => null}
+        </TabNavigation>,
+      );
+
+      const tab = screen.getByRole('button', { name: 'Device Logs (Beta)' });
+      expect(tab.textContent).toBe('Device LogsBeta');
+      // Tabs without a badge keep their label as the accessible name.
+      expect(screen.getByRole('button', { name: 'General' }).textContent).toBe('General');
+    });
+  });
+
   describe('the underline', () => {
     it('is sized in real pixels rather than a scaled 1px bar', () => {
       // Regression guard. The underline used to be `w-px` stretched with