@titan-design/react-ui 0.5.0 → 0.6.0

package/src/components/icons/SvgIcon.tsx

@@ -0,0 +1,50 @@
+import type { ReactNode } from 'react'
+
+export interface IconProps {
+  /** Rendered width/height in px (viewBox is fixed 24×24). */
+  size?: number
+  /** Stroke color (or fill, for solid icons). Defaults to `currentColor` so a wrapper's text token drives it. */
+  color?: string
+  /** Stroke width for outline icons. */
+  strokeWidth?: number
+  /** Fill color; defaults to `none` (outline). */
+  fill?: string
+  /** Accessible title — sets `role="img"` + `<title>`. Omit for a decorative icon (hidden from AT). */
+  title?: string
+}
+
+export interface SvgIconProps extends IconProps {
+  children: ReactNode
+}
+
+/**
+ * Base SVG wrapper for the titan icon set — a 24×24 web-`<svg>` with the shared
+ * accessibility contract (titled → `role="img"` + `<title>`; untitled →
+ * `aria-hidden`) and `currentColor` inheritance. Icons pass their paths as
+ * children plus their stroke/fill defaults.
+ */
+export function SvgIcon({
+  size = 24,
+  color = 'currentColor',
+  strokeWidth = 2,
+  fill = 'none',
+  title,
+  children,
+}: SvgIconProps) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill={fill}
+      stroke={color}
+      strokeWidth={strokeWidth}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      {...(title ? { role: 'img', 'aria-label': title } : { 'aria-hidden': true })}
+    >
+      {title ? <title>{title}</title> : null}
+      {children}
+    </svg>
+  )
+}

package/src/components/icons/icons.stories.tsx

@@ -0,0 +1,57 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import type { ReactNode } from 'react'
+import { View, Text } from 'react-native'
+import { VoltrasMark, BluetoothIcon, DumbbellIcon, StarIcon } from './icons'
+
+const meta: Meta = {
+  title: 'Icons',
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'The shared icon primitive — 24×24 web-`<svg>` glyphs on a common `SvgIcon` base ' +
+          '(a11y contract: titled → `role="img"`, untitled → `aria-hidden`; `currentColor` inheritance). ' +
+          'Reusable design-system-wide (the shell, Workout badges, etc. compose these).',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj
+
+function Swatch({ label, children }: { label: string; children: ReactNode }) {
+  return (
+    <View className="items-center gap-2">
+      {children}
+      <Text className="font-mono text-[10px] text-text-tertiary">{label}</Text>
+    </View>
+  )
+}
+
+export const All: Story = {
+  render: () => (
+    <View className="flex-row gap-8 p-4 items-start">
+      <Swatch label="VoltrasMark">
+        <View className="text-brand-primary">
+          <VoltrasMark size={28} />
+        </View>
+      </Swatch>
+      <Swatch label="BluetoothIcon">
+        <View className="text-status-success">
+          <BluetoothIcon size={28} />
+        </View>
+      </Swatch>
+      <Swatch label="DumbbellIcon">
+        <View className="text-text-primary">
+          <DumbbellIcon size={28} />
+        </View>
+      </Swatch>
+      <Swatch label="StarIcon (fill)">
+        <View className="text-brand-primary">
+          <StarIcon size={28} fill="currentColor" />
+        </View>
+      </Swatch>
+    </View>
+  ),
+}

package/src/components/icons/icons.test.tsx

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { VoltrasMark, BluetoothIcon, DumbbellIcon, StarIcon } from './icons'
+import { SvgIcon } from './SvgIcon'
+
+describe('icon primitives', () => {
+  it('every icon renders an svg', () => {
+    ;[VoltrasMark, BluetoothIcon, DumbbellIcon, StarIcon].forEach((Icon) => {
+      const { container, unmount } = render(<Icon />)
+      expect(container.querySelector('svg')).toBeInTheDocument()
+      unmount()
+    })
+  })
+
+  it('a titled icon is exposed as an accessible image', () => {
+    render(<BluetoothIcon title="Devices" />)
+    expect(screen.getByRole('img', { name: 'Devices' })).toBeInTheDocument()
+  })
+
+  it('an untitled icon is decorative (aria-hidden, no role)', () => {
+    const { container } = render(<VoltrasMark />)
+    const svg = container.querySelector('svg')!
+    expect(svg.getAttribute('aria-hidden')).toBe('true')
+    expect(svg.getAttribute('role')).toBeNull()
+  })
+
+  it('honors size + strokeWidth via the SvgIcon base', () => {
+    const { container } = render(
+      <SvgIcon size={32} strokeWidth={3}>
+        <path d="M0 0" />
+      </SvgIcon>
+    )
+    const svg = container.querySelector('svg')!
+    expect(svg.getAttribute('width')).toBe('32')
+    expect(svg.getAttribute('stroke-width')).toBe('3')
+  })
+
+  it('a decorative icon has no accessibility violations', async () => {
+    const { container } = render(<StarIcon />)
+    expect(await axe(container)).toHaveNoViolations()
+  })
+})

package/src/components/icons/icons.tsx

@@ -0,0 +1,45 @@
+import { SvgIcon, type IconProps } from './SvgIcon'
+
+/**
+ * Voltras brand mark — the ◇ diamond (outline). Pass `fill` for a solid mark.
+ */
+export function VoltrasMark({ size = 14, ...props }: IconProps) {
+  return (
+    <SvgIcon size={size} {...props}>
+      <path d="M12 2 22 12 12 22 2 12Z" />
+    </SvgIcon>
+  )
+}
+
+/**
+ * Bluetooth glyph (stroked) — e.g. device-connection state (color via `currentColor`).
+ */
+export function BluetoothIcon({ size = 18, ...props }: IconProps) {
+  return (
+    <SvgIcon size={size} {...props}>
+      <path d="M7 7 17 17 12 22 12 2 17 7 7 17" />
+    </SvgIcon>
+  )
+}
+
+/** Dumbbell glyph (mirrors lucide-react `Dumbbell`). Outline-only by default. */
+export function DumbbellIcon(props: IconProps) {
+  return (
+    <SvgIcon {...props}>
+      <path d="M14.4 14.4 9.6 9.6" />
+      <path d="M18.657 21.485a2 2 0 1 1-2.829-2.828l-1.767 1.768a2 2 0 1 1-2.829-2.829l6.364-6.364a2 2 0 1 1 2.829 2.829l-1.768 1.767a2 2 0 1 1 2.828 2.829z" />
+      <path d="m21.5 21.5-1.4-1.4" />
+      <path d="M3.9 3.9 2.5 2.5" />
+      <path d="M6.404 12.768a2 2 0 1 1-2.829-2.829l1.768-1.767a2 2 0 1 1-2.828-2.829l2.828-2.828a2 2 0 1 1 2.829 2.828l1.767-1.768a2 2 0 1 1 2.829 2.829z" />
+    </SvgIcon>
+  )
+}
+
+/** Star glyph (mirrors lucide-react `Star`). Pass `fill` for a solid star. */
+export function StarIcon(props: IconProps) {
+  return (
+    <SvgIcon {...props}>
+      <path d="M11.525 2.295a.53.53 0 0 1 .95 0l2.31 4.679a2.123 2.123 0 0 0 1.595 1.16l5.166.756a.53.53 0 0 1 .294.904l-3.736 3.638a2.123 2.123 0 0 0-.611 1.878l.882 5.14a.53.53 0 0 1-.771.56l-4.618-2.428a2.122 2.122 0 0 0-1.973 0L6.396 21.01a.53.53 0 0 1-.77-.56l.881-5.139a2.122 2.122 0 0 0-.611-1.879L2.16 9.795a.53.53 0 0 1 .294-.906l5.165-.755a2.122 2.122 0 0 0 1.597-1.16z" />
+    </SvgIcon>
+  )
+}

package/src/components/icons/index.ts

@@ -0,0 +1,4 @@
+// Icon primitives — the shared, design-system-wide icon set. A base `SvgIcon`
+// wrapper (24×24 web SVG + a11y contract + currentColor) and the icon glyphs.
+export { SvgIcon, type IconProps, type SvgIconProps } from './SvgIcon'
+export * from './icons'

package/src/components/index.ts

@@ -1,5 +1,11 @@
+// Icon primitives (shared, design-system-wide)
+export * from './icons'
+
 // Re-export all UI components
 export * from './ui'
 
 // Re-export custom components
 export * from './custom'
+
+// Re-export shell chrome components
+export * from './shell'

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

@@ -0,0 +1,27 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { BrandLockup } from './BrandLockup'
+
+const meta: Meta<typeof BrandLockup> = {
+  title: 'Shell/TopBar/BrandLockup',
+  component: BrandLockup,
+  tags: ['autodocs'],
+  args: { subtitle: 'wall dashboard', showSubtitle: true },
+  argTypes: {
+    subtitle: { control: 'text' },
+    showSubtitle: { control: 'boolean' },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '**Molecule.** Composes [VoltrasMark](?path=/docs/icons--docs) (icon) + ' +
+          '[Typography](?path=/docs/custom-typography--docs) (wordmark + subtitle). ' +
+          'Toggle `showSubtitle` to see the responsive collapse.',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof BrandLockup>
+
+export const Default: Story = {}

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

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { BrandLockup } from './BrandLockup'
+
+describe('BrandLockup', () => {
+  it('renders the wordmark', () => {
+    render(<BrandLockup />)
+    expect(screen.getByText('VOLTRAS')).toBeInTheDocument()
+  })
+
+  it('shows the subtitle by default and hides it when showSubtitle is false', () => {
+    const { rerender } = render(<BrandLockup subtitle="wall dashboard" />)
+    expect(screen.getByText('/ wall dashboard')).toBeInTheDocument()
+    rerender(<BrandLockup subtitle="wall dashboard" showSubtitle={false} />)
+    expect(screen.queryByText('/ wall dashboard')).not.toBeInTheDocument()
+  })
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(<BrandLockup />)
+    expect(await axe(container)).toHaveNoViolations()
+  })
+})

package/src/components/shell/BrandLockup.tsx

@@ -0,0 +1,47 @@
+import { View, type ViewProps } from 'react-native'
+import { cn } from '../../utils/cn'
+import { Typography } from '../custom/Typography'
+import { VoltrasMark } from '../icons'
+
+export interface BrandLockupProps extends ViewProps {
+  /** The "/ subtitle" that follows the wordmark. Default "wall dashboard". */
+  subtitle?: string
+  /** Show the subtitle. Hidden at tablet width and below (S1-Q4 responsive). */
+  showSubtitle?: boolean
+  className?: string
+}
+
+/**
+ * Product identity lockup for the top bar: ◇ mark + VOLTRAS wordmark + optional
+ * subtitle. Composes the VoltrasMark icon + Typography. S1 · BrandLockup.
+ */
+export function BrandLockup({
+  subtitle = 'wall dashboard',
+  showSubtitle = true,
+  className,
+  ...props
+}: BrandLockupProps) {
+  return (
+    <View className={cn('flex-row items-center gap-[7px]', className)} {...props}>
+      <View className="text-brand-primary">
+        <VoltrasMark size={14} color="currentColor" />
+      </View>
+      <Typography
+        variant="button"
+        color="primary"
+        className="text-[12px] font-extrabold tracking-[1.5px]"
+      >
+        VOLTRAS
+      </Typography>
+      {showSubtitle && subtitle ? (
+        <Typography
+          variant="button"
+          color="tertiary"
+          className="text-[10px] font-semibold tracking-[0.4px]"
+        >
+          / {subtitle}
+        </Typography>
+      ) : null}
+    </View>
+  )
+}

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

@@ -0,0 +1,28 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { DeviceIndicator } from './DeviceIndicator'
+
+const meta: Meta<typeof DeviceIndicator> = {
+  title: 'Shell/TopBar/DeviceMenu/DeviceIndicator',
+  component: DeviceIndicator,
+  tags: ['autodocs'],
+  args: { status: 'connected' },
+  argTypes: {
+    status: { control: 'select', options: ['connected', 'degraded', 'lost'] },
+    label: { control: 'text' },
+    onPress: { control: false },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '**Molecule.** Composes [BluetoothIcon](?path=/docs/icons--docs), color-coded by ' +
+          'connection state via a `text-status-*-vivid` token — the glyph color alone carries the fault ' +
+          '(no separate badge). Switch the `status` control to see connected / degraded / lost.',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof DeviceIndicator>
+
+export const Default: Story = {}

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

@@ -0,0 +1,26 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { DeviceIndicator } from './DeviceIndicator'
+
+describe('DeviceIndicator', () => {
+  it('renders each connection state', () => {
+    const states = ['connected', 'degraded', 'lost'] as const
+    states.forEach((status) => {
+      const { unmount, container } = render(<DeviceIndicator status={status} />)
+      expect(container.firstChild).toBeInTheDocument()
+      unmount()
+    })
+  })
+
+  it('exposes a button role and fires onPress when interactive', () => {
+    const onPress = vi.fn()
+    render(<DeviceIndicator onPress={onPress} />)
+    fireEvent.click(screen.getByRole('button', { name: 'Devices' }))
+    expect(onPress).toHaveBeenCalledTimes(1)
+  })
+
+  it('renders the lost state (red glyph, no separate badge)', () => {
+    const { container } = render(<DeviceIndicator status="lost" />)
+    expect(container.firstChild).toBeInTheDocument()
+  })
+})

package/src/components/shell/DeviceIndicator.tsx

@@ -0,0 +1,52 @@
+import { View, Pressable, type ViewProps } from 'react-native'
+import { cn } from '../../utils/cn'
+import { BluetoothIcon } from '../icons'
+
+export type DeviceConnState = 'connected' | 'degraded' | 'lost'
+
+export interface DeviceIndicatorProps extends ViewProps {
+  /** Aggregate connection state (worst-of the bound devices) → glyph color. */
+  status?: DeviceConnState
+  /** Tap handler. When omitted the glyph is non-interactive (e.g. inside a PopoverTrigger). */
+  onPress?: () => void
+  /** Accessible label (names the glyph / the wrapping trigger button). */
+  label?: string
+  className?: string
+}
+
+// currentColor drives the stroke → color the wrapper's text token by state (vivid, matches LIVE).
+// The glyph color alone carries the fault (red on lost) — no separate alert badge.
+const statusTextClass: Record<DeviceConnState, string> = {
+  connected: 'text-status-success',
+  degraded: 'text-status-warning',
+  lost: 'text-status-error-vivid',
+}
+
+/**
+ * The device/BLE connection glyph — a color-coded bluetooth mark, no label.
+ * Opens the DeviceMenu when tapped. S1 · DeviceIndicator.
+ */
+export function DeviceIndicator({
+  status = 'connected',
+  onPress,
+  label = 'Devices',
+  className,
+  ...props
+}: DeviceIndicatorProps) {
+  const Wrapper = onPress ? Pressable : View
+  return (
+    <Wrapper
+      accessibilityLabel={label}
+      {...(onPress ? { onPress, accessibilityRole: 'button' } : {})}
+      className={cn(
+        'w-[26px] h-[28px] items-center justify-center rounded-[7px]',
+        statusTextClass[status],
+        className
+      )}
+      {...props}
+    >
+      {/* the SVG title names the wrapping trigger button (RNW drops aria-label on non-accessible Views) */}
+      <BluetoothIcon size={18} color="currentColor" title={label} />
+    </Wrapper>
+  )
+}

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()
+    })
+  })
+})