@titan-design/react-ui 0.12.1 → 0.14.0

package/src/components/shell/TopBar.tsx

@@ -1,28 +1,34 @@
-import { useState } from 'react'
+import { Fragment, useState, type ReactNode } from 'react'
 import { View, type LayoutChangeEvent } from 'react-native'
 import { cn } from '../../utils/cn'
 import { surfaceGradient } from '../../theme/gradients'
 import { Divider } from '../ui/divider'
 import { DateTime } from '../custom/DateTime'
 import { BrandLockup } from './BrandLockup'
-import { SessionStatePill, type SessionState } from './SessionStatePill'
-import { DeviceMenu } from './DeviceMenu'
-import { type Device } from './DeviceRow'
+import { type BrandKey } from './brands'
 
 export interface TopBarProps {
-  /** Global session state → the status pill. */
-  state: SessionState
-  /** Devices for the connection glyph + dropdown. */
-  devices: Device[]
-  /** The moment to display in the clock (Date/timestamp). Omit for a live ticking clock. */
-  time?: number | Date
-  /** Brand subtitle. Default "wall dashboard". */
+  /** Which app identity the default {@link BrandLockup} renders. */
+  brand?: BrandKey
+  /** Brand subtitle. Defaults to the brand preset's own. */
   subtitle?: string
   /** Force the subtitle on/off; defaults to container-responsive (hidden below ~1024px). */
   showSubtitle?: boolean
+  /**
+   * Replace the whole brand region. Wins over `brand` / `subtitle`, and opts out
+   * of the responsive subtitle collapse — the node owns its own behaviour.
+   */
+  leading?: ReactNode
+  /**
+   * App chrome for the right cluster, left → right. An array is rendered with the
+   * bar's own vertical dividers between the items, so an app supplies its
+   * controls and the shell keeps the divider rhythm.
+   */
+  trailing?: ReactNode | ReactNode[]
+  /** The moment to display in the clock (Date/timestamp). Omit for a live ticking clock. */
+  time?: number | Date
   /** Force the clock on/off; defaults to container-responsive (hidden below ~720px). */
   showClock?: boolean
-  onSelectDevice?: (device: Device) => void
   className?: string
 }
 
@@ -30,20 +36,39 @@ export interface TopBarProps {
 const SUBTITLE_MIN = 1024
 const CLOCK_MIN = 720
 
+function ClusterDivider() {
+  return <Divider orientation="vertical" className="h-4 bg-border-prominent" />
+}
+
+/** Interleave the bar's divider between slot items, skipping empty slots. */
+function dividedCluster(items: ReactNode[]) {
+  return items
+    .filter((item) => item !== null && item !== undefined && item !== false)
+    .map((item, i) => (
+      <Fragment key={i}>
+        {i > 0 ? <ClusterDivider /> : null}
+        {item}
+      </Fragment>
+    ))
+}
+
 /**
- * S1 · TopBar — the persistent shell chrome band. Brand (left) + a right cluster
- * of session state · device glyph · clock (clock edge-pinned so spacing stays
- * stable as the state text changes). Collapses subtitle then clock as its
- * container narrows.
+ * S1 · TopBar — the persistent shell chrome band, generic over the app. Brand
+ * (left) + a `trailing` cluster of app-supplied chrome and the wall clock (clock
+ * edge-pinned so spacing stays stable as the items' text changes). Collapses
+ * subtitle then clock as its container narrows.
+ *
+ * @example
+ * <TopBar brand="brain" trailing={[<IndexStatus />, <SearchScope />]} />
  */
 export function TopBar({
-  state,
-  devices,
-  time,
-  subtitle = 'wall dashboard',
+  brand = 'voltras',
+  subtitle,
   showSubtitle,
+  leading,
+  trailing,
+  time,
   showClock,
-  onSelectDevice,
   className,
 }: TopBarProps) {
   const [width, setWidth] = useState(SUBTITLE_MIN)
@@ -52,6 +77,18 @@ export function TopBar({
   const subtitleVisible = showSubtitle ?? width >= SUBTITLE_MIN
   const clockVisible = showClock ?? width >= CLOCK_MIN
 
+  const clock = clockVisible ? (
+    <DateTime
+      value={time}
+      live={time == null}
+      format="time"
+      hour12={false}
+      variant="mono"
+      color="secondary"
+      className="text-[11px] min-w-[38px] text-right"
+    />
+  ) : null
+
   return (
     <View
       onLayout={onLayout}
@@ -62,27 +99,11 @@ export function TopBar({
         className
       )}
     >
-      <BrandLockup subtitle={subtitle} showSubtitle={subtitleVisible} />
+      {leading ?? <BrandLockup brand={brand} subtitle={subtitle} showSubtitle={subtitleVisible} />}
 
-      {/* right cluster — order: state · device · time (time pinned to the edge) */}
+      {/* right cluster — app chrome then the clock, pinned to the edge */}
       <View className="ml-auto flex-row items-center gap-[12px]">
-        <SessionStatePill state={state} />
-        <Divider orientation="vertical" className="h-4 bg-border-prominent" />
-        <DeviceMenu devices={devices} onSelectDevice={onSelectDevice} />
-        {clockVisible ? (
-          <>
-            <Divider orientation="vertical" className="h-4 bg-border-prominent" />
-            <DateTime
-              value={time}
-              live={time == null}
-              format="time"
-              hour12={false}
-              variant="mono"
-              color="secondary"
-              className="text-[11px] min-w-[38px] text-right"
-            />
-          </>
-        ) : null}
+        {dividedCluster([...(Array.isArray(trailing) ? trailing : [trailing]), clock])}
       </View>
     </View>
   )

package/src/components/shell/brands.tsx

@@ -0,0 +1,66 @@
+import type { ReactNode } from 'react'
+import { BotIcon, BrainIcon, HeadphonesIcon, KanbanIcon, VoltrasMark } from '../icons'
+
+/** The apps that are expected to mount this shell. */
+export type BrandKey = 'voltras' | 'audiobook' | 'active-work' | 'agents' | 'brain'
+
+export interface BrandPreset {
+  /** The mark glyph, rendered at 14px through the accent token via `currentColor`. */
+  mark: ReactNode
+  /** Uppercase product wordmark. */
+  wordmark: string
+  /** Semantic text token that colours the mark. */
+  accentClassName: string
+  /**
+   * The same accent as a background token, for the nav's active bar. Declared as
+   * a literal alongside its `text-*` twin because Tailwind only emits classes it
+   * can see in the source — a name built at runtime is never generated.
+   */
+  accentBarClassName: string
+  /** Default "/ subtitle" for that app's shell. */
+  subtitle: string
+}
+
+// Accents come from `data-*` rather than `status-*`: `data-*` is the library's
+// palette of N distinct, CVD-checked hues with no semantic load, which is exactly
+// what a per-app identity accent needs. Voltras keeps the real brand token.
+export const brandPresets: Record<BrandKey, BrandPreset> = {
+  voltras: {
+    mark: <VoltrasMark size={14} color="currentColor" />,
+    wordmark: 'VOLTRAS',
+    accentClassName: 'text-brand-primary',
+    accentBarClassName: 'bg-brand-primary',
+    subtitle: 'wall dashboard',
+  },
+  audiobook: {
+    mark: <HeadphonesIcon size={14} color="currentColor" />,
+    wordmark: 'AUDIOBOOK',
+    accentClassName: 'text-data-5',
+    accentBarClassName: 'bg-data-5',
+    subtitle: 'library',
+  },
+  'active-work': {
+    mark: <KanbanIcon size={14} color="currentColor" />,
+    wordmark: 'ACTIVE WORK',
+    accentClassName: 'text-data-1',
+    accentBarClassName: 'bg-data-1',
+    subtitle: 'initiatives',
+  },
+  agents: {
+    mark: <BotIcon size={14} color="currentColor" />,
+    wordmark: 'AGENTS',
+    accentClassName: 'text-data-2',
+    accentBarClassName: 'bg-data-2',
+    subtitle: 'fleet',
+  },
+  brain: {
+    mark: <BrainIcon size={14} color="currentColor" />,
+    wordmark: 'BRAIN',
+    accentClassName: 'text-data-3',
+    accentBarClassName: 'bg-data-3',
+    subtitle: 'knowledge',
+  },
+}
+
+/** Every brand key, in the order the stories present them. */
+export const brandKeys = Object.keys(brandPresets) as BrandKey[]

package/src/components/shell/index.ts

@@ -1,13 +1,14 @@
-// Shell chrome — persistent dashboard frame (nav / top bar / rail / drawers / strip).
-// S1 · Top bar family. (Icons live in the shared `components/icons` primitive.)
+// Shell chrome — the GENERIC persistent app frame (nav / top bar / brand).
+// App-specific chrome composes this family; it never leaks back into it.
+// (Icons live in the shared `components/icons` primitive.)
+export * from './brands'
 export * from './BrandLockup'
-export * from './SessionStatePill'
-export * from './DeviceIndicator'
-export * from './DeviceRow'
-export * from './DeviceMenu'
+// S1 · Top bar family.
 export * from './TopBar'
 // S2 · Side nav family.
 export * from './NavItem'
 export * from './SideNav'
-// S3 · Dashboard shell — composes the nav + top-bar chrome over a content slot.
-export * from './DashboardShell'
+// S3 · App shell — composes the nav + top-bar chrome over a content slot.
+export * from './AppShell'
+// AW-132 · Workout-app shell, composed over the generic family above.
+export * from './workout'

package/src/components/shell/{DeviceIndicator.stories.tsx → workout/DeviceIndicator.stories.tsx}

@@ -2,9 +2,9 @@ import type { Meta, StoryObj } from '@storybook/react-vite'
 import { DeviceIndicator } from './DeviceIndicator'
 
 const meta: Meta<typeof DeviceIndicator> = {
-  title: 'Shell/DeviceIndicator',
+  title: 'Shell/Workout/DeviceIndicator',
   component: DeviceIndicator,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:candidate', '!status:review'],
   args: { status: 'connected' },
   argTypes: {
     status: { control: 'select', options: ['connected', 'degraded', 'lost'] },

package/src/components/shell/{DeviceIndicator.tsx → workout/DeviceIndicator.tsx}

@@ -1,6 +1,6 @@
 import { View, Pressable, type ViewProps } from 'react-native'
-import { cn } from '../../utils/cn'
-import { BluetoothIcon } from '../icons'
+import { cn } from '../../../utils/cn'
+import { BluetoothIcon } from '../../icons'
 
 export type DeviceConnState = 'connected' | 'degraded' | 'lost'
 

package/src/components/shell/{DeviceMenu.stories.tsx → workout/DeviceMenu.stories.tsx}

@@ -10,9 +10,9 @@ const DEVICES: Device[] = [
 ]
 
 const meta: Meta<typeof DeviceMenu> = {
-  title: 'Shell/DeviceMenu',
+  title: 'Shell/Workout/DeviceMenu',
   component: DeviceMenu,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:candidate', '!status:review'],
   args: { devices: DEVICES, isOpen: false },
   argTypes: {
     devices: { control: 'object' },

package/src/components/shell/{DeviceMenu.tsx → workout/DeviceMenu.tsx}

@@ -1,7 +1,7 @@
 import { View } from 'react-native'
-import { cn } from '../../utils/cn'
-import { Typography } from '../custom/Typography'
-import { Popover, PopoverTrigger, PopoverContent } from '../ui/popover'
+import { cn } from '../../../utils/cn'
+import { Typography } from '../../custom/Typography'
+import { Popover, PopoverTrigger, PopoverContent } from '../../ui/popover'
 import { DeviceIndicator, type DeviceConnState } from './DeviceIndicator'
 import { DeviceRow, type Device } from './DeviceRow'
 

package/src/components/shell/{DeviceRow.stories.tsx → workout/DeviceRow.stories.tsx}

@@ -3,9 +3,9 @@ import { View } from 'react-native'
 import { DeviceRow } from './DeviceRow'
 
 const meta: Meta<typeof DeviceRow> = {
-  title: 'Shell/DeviceRow',
+  title: 'Shell/Workout/DeviceRow',
   component: DeviceRow,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:candidate', '!status:review'],
   args: {
     device: { id: 'Voltra-A3F2', nickname: 'Left Cable', slot: 'L', state: 'connected' },
   },

package/src/components/shell/{DeviceRow.tsx → workout/DeviceRow.tsx}

@@ -1,7 +1,7 @@
 import { View, Pressable, type ViewProps } from 'react-native'
-import { cn } from '../../utils/cn'
-import { Indicator, type IndicatorColor } from '../ui/indicator'
-import { Typography } from '../custom/Typography'
+import { cn } from '../../../utils/cn'
+import { Indicator, type IndicatorColor } from '../../ui/indicator'
+import { Typography } from '../../custom/Typography'
 
 export type DeviceRowState = 'connected' | 'available' | 'degraded' | 'lost'
 

package/src/components/shell/{SessionStatePill.stories.tsx → workout/SessionStatePill.stories.tsx}

@@ -2,9 +2,9 @@ import type { Meta, StoryObj } from '@storybook/react-vite'
 import { SessionStatePill } from './SessionStatePill'
 
 const meta: Meta<typeof SessionStatePill> = {
-  title: 'Shell/SessionStatePill',
+  title: 'Shell/Workout/SessionStatePill',
   component: SessionStatePill,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:candidate', '!status:review'],
   args: { state: 'live' },
   argTypes: {
     state: { control: 'select', options: ['live', 'rest', 'idle'] },

package/src/components/shell/{SessionStatePill.tsx → workout/SessionStatePill.tsx}

@@ -1,7 +1,7 @@
 import { View, type ViewProps } from 'react-native'
-import { cn } from '../../utils/cn'
-import { Indicator, type IndicatorColor, type IndicatorPulse } from '../ui/indicator'
-import { Typography, type TypographyColor } from '../custom/Typography'
+import { cn } from '../../../utils/cn'
+import { Indicator, type IndicatorColor, type IndicatorPulse } from '../../ui/indicator'
+import { Typography, type TypographyColor } from '../../custom/Typography'
 
 export type SessionState = 'live' | 'rest' | 'idle'
 
@@ -32,6 +32,8 @@ const stateConfig: Record<
  * The global session-state readout (dot + label). Shared: the top bar's status
  * and the Live-view header both use it (this is the ledger's "StatusPill",
  * Family C — built once). S1 · SessionStatePill.
+ *
+ * @deprecated Use `<Pill tone="…" leading="dot">` — removed after AW-127 consumer migration.
  */
 export function SessionStatePill({ state, label, className, ...props }: SessionStatePillProps) {
   const cfg = stateConfig[state]

package/src/components/shell/workout/WorkoutShell.stories.tsx

@@ -0,0 +1,71 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View } from 'react-native'
+import { WorkoutShell } from './WorkoutShell'
+import { Surface } from '../../ui/surface'
+import { Typography } from '../../custom/Typography'
+
+/**
+ * `Pages/WorkoutShell` — the workout wall-dashboard chrome as one registered surface.
+ * Composes the generic AppShell and fills its slots with the workout's own chrome, so
+ * the dashboard app mounts a single component.
+ */
+const meta: Meta<typeof WorkoutShell> = {
+  title: 'Pages/WorkoutShell',
+  component: WorkoutShell,
+  tags: ['autodocs', 'status:candidate', '!status:review'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          '**Page shell (workout app).** Composes ' +
+          '[AppShell](?path=/docs/pages-appshell--docs) and fills its top-bar slot with ' +
+          '[WorkoutTopBar](?path=/docs/shell-workout-workouttopbar--docs) — which pulls in ' +
+          'DeviceMenu, DeviceRow, DeviceIndicator and SessionStatePill — and its nav slot with ' +
+          'the four workout categories. Mount this instead of re-assembling the chrome per ' +
+          'view.\n\nThis is the AW-132 shape: the generic shell knows nothing about devices or ' +
+          'session state; this component is the whole workout-specific surface.',
+      },
+    },
+  },
+  argTypes: {
+    state: { control: 'select', options: ['live', 'rest', 'idle'] },
+    activeKey: { control: 'select', options: ['live', 'review', 'program', 'body'] },
+    liveKey: { control: 'select', options: [null, 'live', 'review', 'program', 'body'] },
+    onNavigate: { control: false },
+    onSelectDevice: { control: false },
+  },
+  decorators: [
+    (Story) => (
+      <Surface level="base" style={{ height: '100vh' as unknown as number }}>
+        <Story />
+      </Surface>
+    ),
+  ],
+}
+
+export default meta
+type Story = StoryObj<typeof WorkoutShell>
+
+export const Default: Story = {
+  args: { activeKey: 'live', state: 'live' },
+}
+
+export const WithContent: Story = {
+  args: { activeKey: 'review', state: 'rest', liveKey: 'live' },
+  render: (args) => (
+    <WorkoutShell {...args}>
+      <View className="flex-1 gap-1.5 p-7">
+        <Typography variant="h4" color="primary">
+          Review
+        </Typography>
+        <Typography variant="body2" color="tertiary">
+          A page mounts its content here; the shell keeps the nav + top-bar chrome persistent.
+        </Typography>
+      </View>
+    </WorkoutShell>
+  ),
+  parameters: {
+    docs: { description: { story: 'The shell with a page mounted in its content slot.' } },
+  },
+}

package/src/components/shell/{DashboardShell.test.tsx → workout/WorkoutShell.test.tsx}

@@ -2,11 +2,11 @@ import { describe, it, expect, vi } from 'vitest'
 import { render, screen, fireEvent } from '@testing-library/react'
 import { Text } from 'react-native'
 import { axe } from 'jest-axe'
-import { DashboardShell } from './DashboardShell'
+import { WorkoutShell, DashboardShell } from './WorkoutShell'
 
-describe('DashboardShell', () => {
+describe('WorkoutShell', () => {
   it('composes the SideNav rail and its categories', () => {
-    render(<DashboardShell activeKey="live" />)
+    render(<WorkoutShell activeKey="live" />)
     expect(screen.getByRole('tablist')).toBeInTheDocument()
     ;['Live', 'Review', 'Plan', 'Body'].forEach((name) => {
       expect(screen.getByRole('tab', { name })).toBeInTheDocument()
@@ -14,15 +14,15 @@ describe('DashboardShell', () => {
   })
 
   it('renders the content-slot placeholder when no children are given', () => {
-    render(<DashboardShell activeKey="live" />)
+    render(<WorkoutShell activeKey="live" />)
     expect(screen.getByText('main content region')).toBeInTheDocument()
   })
 
   it('mounts children in the content slot and drops the placeholder', () => {
     render(
-      <DashboardShell activeKey="review">
+      <WorkoutShell activeKey="review">
         <Text>my page body</Text>
-      </DashboardShell>
+      </WorkoutShell>
     )
     expect(screen.getByText('my page body')).toBeInTheDocument()
     expect(screen.queryByText('main content region')).not.toBeInTheDocument()
@@ -30,13 +30,24 @@ describe('DashboardShell', () => {
 
   it('forwards nav taps through onNavigate', () => {
     const onNavigate = vi.fn()
-    render(<DashboardShell activeKey="live" onNavigate={onNavigate} />)
+    render(<WorkoutShell activeKey="live" onNavigate={onNavigate} />)
     fireEvent.click(screen.getByRole('tab', { name: 'Body' }))
     expect(onNavigate).toHaveBeenCalledWith('body')
   })
 
+  it('fills the generic top-bar slot with the workout chrome', () => {
+    render(<WorkoutShell activeKey="live" state="rest" />)
+    expect(screen.getByText('VOLTRAS')).toBeInTheDocument()
+    expect(screen.getByText('REST')).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Devices' })).toBeInTheDocument()
+  })
+
+  it('still exports the pre-AW-132 DashboardShell name', () => {
+    expect(DashboardShell).toBe(WorkoutShell)
+  })
+
   it('has no a11y violations', async () => {
-    const { container } = render(<DashboardShell activeKey="live" />)
+    const { container } = render(<WorkoutShell activeKey="live" />)
     expect(await axe(container)).toHaveNoViolations()
   })
 })

package/src/components/shell/workout/WorkoutShell.tsx

@@ -0,0 +1,77 @@
+import type { ReactNode } from 'react'
+import { AppShell } from '../AppShell'
+import { type SideNavItem } from '../SideNav'
+import { WorkoutTopBar } from './WorkoutTopBar'
+import { workoutNavItems } from './workoutNavItems'
+import { type Device } from './DeviceRow'
+import { type SessionState } from './SessionStatePill'
+
+/**
+ * `WorkoutShell` — the workout wall-dashboard chrome. Composes the generic
+ * {@link AppShell} and fills its top-bar slot with the workout's own
+ * {@link WorkoutTopBar} (session state + device menu) and its nav slot with the
+ * four workout categories. The generic shell knows none of this; this component
+ * is the whole workout-specific surface. Driven entirely by props.
+ */
+export interface WorkoutShellProps {
+  /** Active nav category key. */
+  activeKey?: string
+  /** Nav categories, top → bottom. Defaults to the four workout categories. */
+  navItems?: SideNavItem[]
+  /** A category with off-view live activity → a quiet cue on that item. */
+  liveKey?: string | null
+  /** Global session state → the TopBar status pill. */
+  state?: SessionState
+  /** Connected devices → the TopBar connection glyph + dropdown. */
+  devices?: Device[]
+  /** TopBar brand subtitle. */
+  subtitle?: string
+  onNavigate?: (key: string) => void
+  onSelectDevice?: (device: Device) => void
+  /** Main content region. A placeholder renders when omitted. */
+  children?: ReactNode
+  className?: string
+}
+
+const DEMO_DEVICES: Device[] = [
+  { id: 'Voltra-A3F2', nickname: 'Left Cable', slot: 'L', state: 'connected' },
+  { id: 'Voltra-9B1C', nickname: 'Right Cable', slot: 'R', state: 'connected' },
+]
+
+export function WorkoutShell({
+  activeKey = 'live',
+  navItems = workoutNavItems,
+  liveKey = null,
+  state = 'live',
+  devices = DEMO_DEVICES,
+  subtitle = 'wall dashboard',
+  onNavigate,
+  onSelectDevice,
+  children,
+  className,
+}: WorkoutShellProps) {
+  return (
+    <AppShell
+      className={className}
+      navItems={navItems}
+      activeKey={activeKey}
+      liveKey={liveKey}
+      onNavigate={onNavigate}
+      topBar={
+        <WorkoutTopBar
+          state={state}
+          devices={devices}
+          subtitle={subtitle}
+          onSelectDevice={onSelectDevice}
+        />
+      }
+    >
+      {children}
+    </AppShell>
+  )
+}
+
+/** @deprecated Renamed to `WorkoutShell` — same props (AW-132). Removed after consumer migration. */
+export const DashboardShell = WorkoutShell
+/** @deprecated Renamed to `WorkoutShellProps` (AW-132). */
+export type DashboardShellProps = WorkoutShellProps

package/src/components/shell/workout/WorkoutTopBar.stories.tsx

@@ -0,0 +1,58 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { WorkoutTopBar } from './WorkoutTopBar'
+import { type Device } from './DeviceRow'
+
+const DEVICES: Device[] = [
+  { id: 'Voltra-A3F2', nickname: 'Left Cable', slot: 'L', state: 'connected' },
+  { id: 'Voltra-9B1C', nickname: 'Right Cable', slot: 'R', state: 'connected' },
+  { id: 'Voltra-77E0', nickname: 'Spare', slot: null, state: 'available' },
+]
+
+const meta: Meta<typeof WorkoutTopBar> = {
+  title: 'Shell/Workout/WorkoutTopBar',
+  component: WorkoutTopBar,
+  tags: ['autodocs', 'status:candidate', '!status:review'],
+  args: { state: 'live', devices: DEVICES },
+  argTypes: {
+    state: { control: 'select', options: ['live', 'rest', 'idle'] },
+    devices: { control: 'object' },
+    subtitle: { control: 'text' },
+    showSubtitle: { control: 'boolean' },
+    showClock: { control: 'boolean' },
+    time: { control: false },
+    onSelectDevice: { control: false },
+  },
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          '**Organism (workout app).** The generic ' +
+          "[TopBar](?path=/docs/shell-topbar--docs) with the workout's own chrome in its " +
+          '`trailing` slot: [SessionStatePill](?path=/docs/shell-workout-sessionstatepill--docs) ' +
+          'then [DeviceMenu](?path=/docs/shell-workout-devicemenu--docs). The bar adds the ' +
+          'dividers and the edge-pinned clock; this component only supplies the items ' +
+          '(AW-132).\n\n' +
+          '**Try it:** use the **Controls** to change `state`, edit `devices` (set one to ' +
+          '`lost` to see the fault), or toggle `showSubtitle` / `showClock`. **Resize the ' +
+          'canvas** to watch the container-responsive collapse (SIZE-D01). Click the device ' +
+          'glyph to open the menu.',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof WorkoutTopBar>
+
+export const Default: Story = {}
+
+/** A lost device — the glyph alone carries the fault. */
+export const DeviceLost: Story = {
+  args: {
+    state: 'rest',
+    devices: [
+      { id: 'Voltra-A3F2', nickname: 'Left Cable', slot: 'L', state: 'connected' },
+      { id: 'Voltra-9B1C', nickname: 'Right Cable', slot: 'R', state: 'lost' },
+    ],
+  },
+}

package/src/components/shell/workout/WorkoutTopBar.test.tsx

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { WorkoutTopBar } from './WorkoutTopBar'
+import { type Device } from './DeviceRow'
+
+const devices: Device[] = [
+  { id: 'Voltra-A3F2', nickname: 'Left Cable', slot: 'L', state: 'connected' },
+  { id: 'Voltra-9B1C', nickname: 'Right Cable', slot: 'R', state: 'connected' },
+]
+
+const AT_1612 = new Date(2024, 0, 1, 16, 12) // local 16:12
+
+describe('WorkoutTopBar', () => {
+  it('renders brand, session state, the device glyph and a 24h clock', () => {
+    render(<WorkoutTopBar state="live" devices={devices} time={AT_1612} showClock />)
+    expect(screen.getByText('VOLTRAS')).toBeInTheDocument()
+    expect(screen.getByText('LIVE')).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Devices' })).toBeInTheDocument()
+    expect(screen.getByText('16:12')).toBeInTheDocument()
+  })
+
+  it('hides the clock when showClock is false', () => {
+    render(<WorkoutTopBar state="live" devices={devices} time={AT_1612} showClock={false} />)
+    expect(screen.queryByText('16:12')).not.toBeInTheDocument()
+  })
+
+  it('hides the subtitle when showSubtitle is false', () => {
+    render(<WorkoutTopBar state="rest" devices={devices} showSubtitle={false} />)
+    expect(screen.queryByText('/ wall dashboard')).not.toBeInTheDocument()
+  })
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(
+      <WorkoutTopBar state="live" devices={devices} time={AT_1612} showClock />
+    )
+    expect(await axe(container)).toHaveNoViolations()
+  })
+})