@titan-design/react-ui 0.4.0 → 0.6.0

package/src/components/shell/DeviceMenu.stories.tsx

@@ -0,0 +1,47 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View } from 'react-native'
+import { DeviceMenu } from './DeviceMenu'
+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 DeviceMenu> = {
+  title: 'Shell/TopBar/DeviceMenu',
+  component: DeviceMenu,
+  tags: ['autodocs'],
+  args: { devices: DEVICES, isOpen: false },
+  argTypes: {
+    devices: { control: 'object' },
+    isOpen: { control: 'boolean' },
+    onOpenChange: { control: false },
+    onSelectDevice: { control: false },
+  },
+  decorators: [
+    (Story) => (
+      <View className="flex-row p-4 pb-48">
+        <Story />
+      </View>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '**Organism.** The device glyph + its dropdown. Composes ' +
+          '[Popover](?path=/docs/components-popover--docs) + ' +
+          '[DeviceIndicator](?path=/docs/shell-topbar-devicemenu-deviceindicator--docs) (trigger) + ' +
+          '[DeviceRow](?path=/docs/shell-topbar-devicemenu-devicerow--docs) (list) + ' +
+          '[Typography](?path=/docs/custom-typography--docs) (header). Aggregates the bound devices ' +
+          '(worst-of) for the glyph state. Click the glyph, or toggle the `isOpen` control.',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof DeviceMenu>
+
+export const Default: Story = {}

package/src/components/shell/DeviceMenu.test.tsx

@@ -0,0 +1,40 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { DeviceMenu } from './DeviceMenu'
+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' },
+]
+
+describe('DeviceMenu', () => {
+  it('renders the trigger glyph and opens the device list on click', () => {
+    render(<DeviceMenu devices={devices} />)
+    const trigger = screen.getByRole('button', { name: 'Devices' })
+    expect(screen.queryByText('Left Cable')).not.toBeInTheDocument()
+    fireEvent.click(trigger)
+    expect(screen.getByText('Left Cable')).toBeInTheDocument()
+    expect(screen.getByText(/2 bound · 1 available/)).toBeInTheDocument()
+  })
+
+  it('reports a controlled open state', () => {
+    render(<DeviceMenu devices={devices} isOpen />)
+    expect(screen.getByText('Right Cable')).toBeInTheDocument()
+  })
+
+  it('fires onSelectDevice when a row is tapped', () => {
+    const onSelectDevice = vi.fn()
+    render(<DeviceMenu devices={devices} isOpen onSelectDevice={onSelectDevice} />)
+    fireEvent.click(screen.getByText('Left Cable'))
+    expect(onSelectDevice).toHaveBeenCalledWith(expect.objectContaining({ id: 'Voltra-A3F2' }))
+  })
+
+  it('renders regardless of the aggregate worst-of state (degraded / lost bound device)', () => {
+    const degraded: Device[] = [{ id: 'D', nickname: 'Left', slot: 'L', state: 'degraded' }]
+    const lost: Device[] = [{ id: 'L', nickname: 'Left', slot: 'L', state: 'lost' }]
+    expect(render(<DeviceMenu devices={degraded} />).container.firstChild).toBeInTheDocument()
+    expect(render(<DeviceMenu devices={lost} />).container.firstChild).toBeInTheDocument()
+  })
+})

package/src/components/shell/DeviceMenu.tsx

@@ -0,0 +1,65 @@
+import { View } from 'react-native'
+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'
+
+export interface DeviceMenuProps {
+  devices: Device[]
+  /** Controlled open state (optional — uncontrolled otherwise). */
+  isOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+  onSelectDevice?: (device: Device) => void
+  className?: string
+}
+
+/** Aggregate the bound devices into a single glyph state (worst-of). */
+function aggregateStatus(devices: Device[]): DeviceConnState {
+  const bound = devices.filter((d) => d.slot)
+  if (bound.some((d) => d.state === 'lost')) return 'lost'
+  if (bound.some((d) => d.state === 'degraded')) return 'degraded'
+  return 'connected'
+}
+
+/**
+ * The device glyph + its dropdown of individual devices (availability, slot
+ * binding, id, connection state). Composes Popover + DeviceIndicator +
+ * DeviceRow. S1 · DeviceMenu.
+ */
+export function DeviceMenu({
+  devices,
+  isOpen,
+  onOpenChange,
+  onSelectDevice,
+  className,
+}: DeviceMenuProps) {
+  const status = aggregateStatus(devices)
+  const boundCount = devices.filter((d) => d.slot).length
+  const availCount = devices.filter((d) => !d.slot).length
+
+  return (
+    <Popover placement="bottom" isOpen={isOpen} onOpenChange={onOpenChange} className={className}>
+      <PopoverTrigger>
+        <DeviceIndicator status={status} />
+      </PopoverTrigger>
+      <PopoverContent className="right-0 left-auto mt-[10px] w-[326px] bg-surface-elevated border border-border-strong rounded-[10px] p-[7px]">
+        <Typography
+          variant="monoLabel"
+          color="tertiary"
+          className="text-[9px] tracking-[0.8px] px-2 pt-[6px] pb-2"
+        >
+          Devices — {boundCount} bound · {availCount} available
+        </Typography>
+        {devices.map((device, i) => (
+          <View key={device.id} className={cn(i > 0 && 'border-t border-border')}>
+            <DeviceRow
+              device={device}
+              onPress={onSelectDevice ? () => onSelectDevice(device) : undefined}
+            />
+          </View>
+        ))}
+      </PopoverContent>
+    </Popover>
+  )
+}

package/src/components/shell/DeviceRow.stories.tsx

@@ -0,0 +1,38 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View } from 'react-native'
+import { DeviceRow } from './DeviceRow'
+
+const meta: Meta<typeof DeviceRow> = {
+  title: 'Shell/TopBar/DeviceMenu/DeviceRow',
+  component: DeviceRow,
+  tags: ['autodocs'],
+  args: {
+    device: { id: 'Voltra-A3F2', nickname: 'Left Cable', slot: 'L', state: 'connected' },
+  },
+  argTypes: {
+    device: { control: 'object' },
+    onPress: { control: false },
+  },
+  decorators: [
+    (Story) => (
+      <View className="w-[320px] bg-surface-elevated rounded-lg p-1">
+        <Story />
+      </View>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '**Molecule.** One device row: status dot · name · Bluetooth id. Composes ' +
+          '[Indicator](?path=/docs/components-indicator--docs) (status dot) + ' +
+          '[Typography](?path=/docs/custom-typography--docs) (`body2` name, `mono` id). ' +
+          'Edit the `device` control (set `state` to `lost` / `available`, `slot` to `null`) to explore.',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof DeviceRow>
+
+export const Default: Story = {}

package/src/components/shell/DeviceRow.test.tsx

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { DeviceRow, type Device } from './DeviceRow'
+
+const bound: Device = { id: 'Voltra-A3F2', nickname: 'Left Cable', slot: 'L', state: 'connected' }
+const unbound: Device = { id: 'Voltra-77E0', nickname: 'Spare', slot: null, state: 'available' }
+
+describe('DeviceRow', () => {
+  it('renders the device name and Bluetooth id', () => {
+    render(<DeviceRow device={bound} />)
+    expect(screen.getByText('Left Cable')).toBeInTheDocument()
+    expect(screen.getByText('Voltra-A3F2')).toBeInTheDocument()
+  })
+
+  it('omits the redundant status text and slot pill (dot + name carry it)', () => {
+    render(<DeviceRow device={bound} />)
+    expect(screen.queryByText('connected')).not.toBeInTheDocument()
+    expect(screen.queryByText('SLOT L')).not.toBeInTheDocument()
+  })
+
+  it('renders an unbound device by name', () => {
+    render(<DeviceRow device={unbound} />)
+    expect(screen.getByText('Spare')).toBeInTheDocument()
+    expect(screen.getByText('Voltra-77E0')).toBeInTheDocument()
+  })
+
+  it('renders every connection state without crashing', () => {
+    const states = ['connected', 'available', 'degraded', 'lost'] as const
+    states.forEach((state) => {
+      const { unmount, container } = render(
+        <DeviceRow device={{ id: 'X', nickname: 'Cable', slot: 'L', state }} />
+      )
+      expect(container.firstChild).toBeInTheDocument()
+      unmount()
+    })
+  })
+})

package/src/components/shell/DeviceRow.tsx

@@ -0,0 +1,58 @@
+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'
+
+export type DeviceRowState = 'connected' | 'available' | 'degraded' | 'lost'
+
+export interface Device {
+  /** Stable device id (e.g. "Voltra-A3F2"). */
+  id: string
+  /** User-assigned slot/device name (e.g. "Left Cable"). */
+  nickname: string
+  /** Bound slot, or null when unbound/available (used for the menu's bound/available tally). */
+  slot?: 'L' | 'R' | null
+  /** Connection/availability state → the status dot color. */
+  state: DeviceRowState
+}
+
+export interface DeviceRowProps extends ViewProps {
+  device: Device
+  onPress?: () => void
+  className?: string
+}
+
+const stateColor: Record<DeviceRowState, IndicatorColor> = {
+  connected: 'success',
+  available: 'info',
+  degraded: 'warning',
+  lost: 'error-vivid',
+}
+
+/**
+ * One device in the DeviceMenu: status dot · name · Bluetooth id. The dot color
+ * carries the connection state (no redundant status text); the name is the one
+ * slot label (no duplicate slot badge). S1 · DeviceRow.
+ */
+export function DeviceRow({ device, onPress, className, ...props }: DeviceRowProps) {
+  const Wrapper = onPress ? Pressable : View
+  return (
+    <Wrapper
+      {...(onPress ? { onPress, accessibilityRole: 'button' } : {})}
+      className={cn('flex-row items-center gap-[10px] px-2 py-[9px] rounded-[7px]', className)}
+      {...props}
+    >
+      <Indicator size="md" color={stateColor[device.state]} />
+      <Typography
+        variant="body2"
+        color={device.slot ? 'primary' : 'secondary'}
+        className="flex-1 font-bold text-[12px]"
+      >
+        {device.nickname}
+      </Typography>
+      <Typography variant="mono" color="tertiary" className="text-[10px]">
+        {device.id}
+      </Typography>
+    </Wrapper>
+  )
+}

package/src/components/shell/README.md

@@ -0,0 +1,86 @@
+# Shell chrome — component family
+
+The persistent dashboard frame (top bar, and — as the decomposition proceeds — side nav, session
+rail, drawers, pinned strip). Components live flat on disk; the tiering below is a documentation
+contract, not a directory layout, so promoting/composing is pure import churn.
+
+This README is the **index**: it maps each component's dependencies (**composes ↓**) and its consumers
+(**used-by ↑**) so you can navigate the tree in both directions and spot where a hand-rolled element
+should be reaching for an existing primitive instead. Storybook mirrors this tree under `Shell/TopBar/…`,
+and every component's autodocs page repeats its "Composes" links.
+
+## Specimen: `TopBar` (the first shell unit, S1)
+
+```
+TopBar ....................... organism — the chrome band (Shell/TopBar)
+├─ BrandLockup ............... molecule
+│  ├─ VoltrasMark ............ icons (shared primitive)
+│  └─ Typography ............. titan · button variant
+├─ SessionStatePill .......... molecule  (= the reusable StatusPill)
+│  ├─ Indicator .............. titan · ping pulse + vivid color
+│  └─ Typography ............. titan · monoLabel
+├─ Divider ................... titan · bg-border-prominent
+├─ DeviceMenu ................ organism
+│  ├─ Popover ................ titan
+│  ├─ DeviceIndicator ........ molecule → BluetoothIcon (icons primitive)
+│  ├─ DeviceRow .............. molecule → Indicator + Typography (body2 / mono)
+│  └─ Typography ............. titan · monoLabel (header)
+├─ DateTime .................. titan · mono variant, live 24h clock
+└─ surfaceGradient.chrome .... theme · gradient primitive
+```
+
+## Dependency map
+
+| Component | Tier | Composes ↓ | Used-by ↑ |
+|---|---|---|---|
+| `TopBar` | organism | BrandLockup, SessionStatePill, Divider, DeviceMenu, DateTime, `surfaceGradient.chrome` | dashboard app root *(planned)* |
+| `BrandLockup` | molecule | VoltrasMark, Typography | TopBar |
+| `SessionStatePill` | molecule | Indicator, Typography | TopBar, **Live-view header** *(planned reuse)* |
+| `DeviceMenu` | organism | Popover, DeviceIndicator, DeviceRow, Typography | TopBar |
+| `DeviceIndicator` | molecule | BluetoothIcon | DeviceMenu |
+| `DeviceRow` | molecule | Indicator, Typography | DeviceMenu |
+| `VoltrasMark` / `BluetoothIcon` | **`components/icons`** primitive | `SvgIcon` base | BrandLockup / DeviceIndicator (+ any consumer) |
+
+## Shared substrates introduced here (reusable beyond the shell)
+
+Building S1 grew the design system — these are now available to every component:
+
+- **`components/icons`** — a shared icon primitive: an `SvgIcon` base (24×24, a11y contract, `currentColor`)
+  + `IconProps`. VoltrasMark / BluetoothIcon live here, and the previously-orphaned Workout icons
+  (Dumbbell / Star) were folded in (re-exported from `Workout/icons` for back-compat).
+- **`theme/gradients.ts`** — `linearGradient(from, to, angle)` + named `surfaceGradient.*`, built on
+  `resolveColor` (themeable web CSS vars + native hex fallback).
+- **`Indicator`** (titan atom) — `pulse: 'ping'` (expanding ring) + `success` / `error-vivid` colors.
+- **`DateTime`** (titan) — `hour12`, `seconds`, self-ticking `live`, and Typography routing via `variant`.
+- **`Typography`** — `mono` (technical readouts) + `monoLabel` (all-caps mono) variants.
+- **Tokens** — a full **vivid** green/red palette + **`border-prominent`** divider token.
+
+## Reuse audit (the "are we failing to use existing components?" check)
+
+Every leaf now composes a primitive rather than hand-rolling it:
+
+| Concern | Uses | Not |
+|---|---|---|
+| status dots | `Indicator` | raw CSS/`View` dots |
+| dividers | `Divider` (`border-prominent`) | hairline `View`s |
+| mono / all-caps text | `Typography` `mono`/`monoLabel` | ad-hoc `font-mono` classes |
+| glyphs | icon atoms (`VoltrasMark`, `BluetoothIcon`) | unicode chars / inline `<svg>` |
+| chrome gradient | `surfaceGradient.chrome` | inline `linear-gradient` strings |
+| colors | semantic tokens (vivid palette) | magic hex |
+
+## Testing
+
+- **Unit** — every component + primitive has a `*.test.tsx` (render, behavior, a11y); shell branch coverage ≈96%.
+- **Visual** — `tests/visual/stories.spec.ts` screenshots the `Shell/*` + `Icons` stories via Playwright
+  (`toHaveScreenshot`), clock-frozen + animations-disabled so the live-clock/animated stories are
+  deterministic. Widen `SCOPE` to cover more of the library. **Baselines must be generated in the pinned
+  container** (`mcr.microsoft.com/playwright:v1.58.2-noble`) — the `visual.yml` "Layer 2" step seeds them as
+  an artifact; commit the `*-chromium-linux.png` and flip the step to the `test:visual:stories` gate.
+- **Lint guardrails** — components may not inline `linear-gradient` (use `surfaceGradient`); shell + icons may
+  not use raw hex (use tokens).
+
+**Watch-list (known gaps to close as we go):**
+- **Dot primitive overlap** — titan has both `StatusDot` (Workout, semantic) and `Indicator` (ui, generic).
+  The shell standardizes on `Indicator`; a future pass could consolidate.
+- **Other hand-rolled gradients** — `MesoCard`, `DeviationBar`, `MesoStatusCard`, `BodyMapDetailPanel` still
+  inline `linear-gradient` strings; they should adopt `surfaceGradient` / `linearGradient`.

package/src/components/shell/SessionStatePill.stories.tsx

@@ -0,0 +1,27 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { SessionStatePill } from './SessionStatePill'
+
+const meta: Meta<typeof SessionStatePill> = {
+  title: 'Shell/TopBar/SessionStatePill',
+  component: SessionStatePill,
+  tags: ['autodocs'],
+  args: { state: 'live' },
+  argTypes: {
+    state: { control: 'select', options: ['live', 'rest', 'idle'] },
+    label: { control: 'text' },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '**Molecule** (= the ledger’s reusable StatusPill — also used by the Live-view header). Composes ' +
+          '[Indicator](?path=/docs/components-indicator--docs) (pulse `ping` + vivid color for live) + ' +
+          '[Typography](?path=/docs/custom-typography--docs) (`monoLabel`). Use the `state` control to switch.',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof SessionStatePill>
+
+export const Default: Story = {}

package/src/components/shell/SessionStatePill.test.tsx

@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { SessionStatePill } from './SessionStatePill'
+
+describe('SessionStatePill', () => {
+  it('labels each state', () => {
+    const { rerender } = render(<SessionStatePill state="live" />)
+    expect(screen.getByText('LIVE')).toBeInTheDocument()
+    rerender(<SessionStatePill state="rest" />)
+    expect(screen.getByText('REST')).toBeInTheDocument()
+    rerender(<SessionStatePill state="idle" />)
+    expect(screen.getByText('IDLE')).toBeInTheDocument()
+  })
+
+  it('supports a custom label', () => {
+    render(<SessionStatePill state="live" label="SET LIVE" />)
+    expect(screen.getByText('SET LIVE')).toBeInTheDocument()
+  })
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(<SessionStatePill state="live" />)
+    expect(await axe(container)).toHaveNoViolations()
+  })
+})

package/src/components/shell/SessionStatePill.tsx

@@ -0,0 +1,46 @@
+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'
+
+export type SessionState = 'live' | 'rest' | 'idle'
+
+export interface SessionStatePillProps extends ViewProps {
+  /** Session state → dot color + pulse + label. */
+  state: SessionState
+  /** Override the default label (LIVE / REST / IDLE). */
+  label?: string
+  className?: string
+}
+
+const stateConfig: Record<
+  SessionState,
+  {
+    label: string
+    color: IndicatorColor
+    pulse: boolean | IndicatorPulse
+    textColor: TypographyColor
+  }
+> = {
+  // live = vivid green with an expanding ring; rest = solid amber (no pulse — operator); idle is dim.
+  live: { label: 'LIVE', color: 'success', pulse: 'ping', textColor: 'primary' },
+  rest: { label: 'REST', color: 'warning', pulse: false, textColor: 'primary' },
+  idle: { label: 'IDLE', color: 'default', pulse: false, textColor: 'secondary' },
+}
+
+/**
+ * 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.
+ */
+export function SessionStatePill({ state, label, className, ...props }: SessionStatePillProps) {
+  const cfg = stateConfig[state]
+  return (
+    <View className={cn('flex-row items-center gap-2', className)} {...props}>
+      <Indicator size="md" color={cfg.color} pulse={cfg.pulse} />
+      <Typography variant="monoLabel" color={cfg.textColor} className="text-[11px]">
+        {label ?? cfg.label}
+      </Typography>
+    </View>
+  )
+}

package/src/components/shell/TopBar.stories.tsx

@@ -0,0 +1,49 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { TopBar } from './TopBar'
+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 TopBar> = {
+  title: 'Shell/TopBar',
+  component: TopBar,
+  tags: ['autodocs'],
+  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** — the persistent shell chrome band, and the root of the top-bar family ' +
+          '(see `shell/README.md` for the full dependency map). Composes ' +
+          '[BrandLockup](?path=/docs/shell-topbar-brandlockup--docs) + ' +
+          '[SessionStatePill](?path=/docs/shell-topbar-sessionstatepill--docs) + ' +
+          '[Divider](?path=/docs/components-divider--docs) (`bg-border-prominent`) + ' +
+          '[DeviceMenu](?path=/docs/shell-topbar-devicemenu--docs) + ' +
+          '[DateTime](?path=/docs/custom-datetime--docs) (`variant="mono"` live clock). ' +
+          'Background = the shared `surfaceGradient.chrome` primitive.\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) — subtitle drops < 1024px, clock < 720px. ' +
+          'Click the device glyph to open the menu.',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof TopBar>
+
+export const Default: Story = {}

package/src/components/shell/TopBar.test.tsx

@@ -0,0 +1,36 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { TopBar } from './TopBar'
+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('TopBar', () => {
+  it('renders brand, state and a 24h clock', () => {
+    render(<TopBar state="live" devices={devices} time={AT_1612} showClock />)
+    expect(screen.getByText('VOLTRAS')).toBeInTheDocument()
+    expect(screen.getByText('LIVE')).toBeInTheDocument()
+    expect(screen.getByText('16:12')).toBeInTheDocument()
+  })
+
+  it('hides the clock when showClock is false', () => {
+    render(<TopBar 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(<TopBar state="rest" devices={devices} showSubtitle={false} />)
+    expect(screen.queryByText('/ wall dashboard')).not.toBeInTheDocument()
+  })
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(<TopBar state="live" devices={devices} time={AT_1612} showClock />)
+    expect(await axe(container)).toHaveNoViolations()
+  })
+})

package/src/components/shell/TopBar.tsx

@@ -0,0 +1,89 @@
+import { useState } 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'
+
+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". */
+  subtitle?: string
+  /** Force the subtitle on/off; defaults to container-responsive (hidden below ~1024px). */
+  showSubtitle?: boolean
+  /** Force the clock on/off; defaults to container-responsive (hidden below ~720px). */
+  showClock?: boolean
+  onSelectDevice?: (device: Device) => void
+  className?: string
+}
+
+// SIZE-D01: responsiveness is container-driven (measured width), not a fixed size prop.
+const SUBTITLE_MIN = 1024
+const CLOCK_MIN = 720
+
+/**
+ * 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.
+ */
+export function TopBar({
+  state,
+  devices,
+  time,
+  subtitle = 'wall dashboard',
+  showSubtitle,
+  showClock,
+  onSelectDevice,
+  className,
+}: TopBarProps) {
+  const [width, setWidth] = useState(SUBTITLE_MIN)
+  const onLayout = (e: LayoutChangeEvent) => setWidth(e.nativeEvent.layout.width)
+
+  const subtitleVisible = showSubtitle ?? width >= SUBTITLE_MIN
+  const clockVisible = showClock ?? width >= CLOCK_MIN
+
+  return (
+    <View
+      onLayout={onLayout}
+      // shared chrome gradient (web); solid bg-surface-elevated is the native fallback
+      style={surfaceGradient.chrome() as object}
+      className={cn(
+        'h-[46px] flex-row items-center gap-[14px] px-4 bg-surface-elevated border-b border-border',
+        className
+      )}
+    >
+      <BrandLockup subtitle={subtitle} showSubtitle={subtitleVisible} />
+
+      {/* right cluster — order: state · device · time (time 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}
+      </View>
+    </View>
+  )
+}

package/src/components/shell/index.ts

@@ -0,0 +1,8 @@
+// Shell chrome — persistent dashboard frame (nav / top bar / rail / drawers / strip).
+// S1 · Top bar family. (Icons live in the shared `components/icons` primitive.)
+export * from './BrandLockup'
+export * from './SessionStatePill'
+export * from './DeviceIndicator'
+export * from './DeviceRow'
+export * from './DeviceMenu'
+export * from './TopBar'