@titan-design/react-ui 0.6.0 → 0.7.0

package/src/components/shell/DashboardShell.tsx

@@ -0,0 +1,74 @@
+import type { ReactNode } from 'react'
+import { View, Text } from 'react-native'
+import { cn } from '../../utils/cn'
+import { SideNav, type SideNavItem } from './SideNav'
+import { TopBar } from './TopBar'
+import { type Device } from './DeviceRow'
+import { type SessionState } from './SessionStatePill'
+
+/**
+ * `DashboardShell` — the wall-dashboard chrome: a persistent {@link SideNav} rail +
+ * {@link TopBar} over a main content region. A thin frame that wires the shell-nav
+ * organisms together and exposes a `children` content slot, so the dashboard app
+ * mounts one component instead of re-assembling the chrome. Driven entirely by props.
+ */
+export interface DashboardShellProps {
+  /** Active nav category key. */
+  activeKey?: string
+  /** Nav categories, top → bottom. Defaults to SideNav's four dashboard 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' },
+]
+
+function ContentPlaceholder() {
+  return (
+    <View className="flex-1 items-center justify-center">
+      <Text className="font-heading text-sm text-text-tertiary">main content region</Text>
+    </View>
+  )
+}
+
+export function DashboardShell({
+  activeKey = 'live',
+  navItems,
+  liveKey = null,
+  state = 'live',
+  devices = DEMO_DEVICES,
+  subtitle = 'wall dashboard',
+  onNavigate,
+  onSelectDevice,
+  children,
+  className,
+}: DashboardShellProps) {
+  return (
+    <View className={cn('flex-1 flex-row bg-surface-base', className)}>
+      <SideNav activeKey={activeKey} items={navItems} liveKey={liveKey} onNavigate={onNavigate} />
+      <View className="flex-1">
+        <TopBar
+          state={state}
+          devices={devices}
+          subtitle={subtitle}
+          onSelectDevice={onSelectDevice}
+        />
+        <View className="flex-1">{children ?? <ContentPlaceholder />}</View>
+      </View>
+    </View>
+  )
+}

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

@@ -2,7 +2,7 @@ import type { Meta, StoryObj } from '@storybook/react-vite'
 import { DeviceIndicator } from './DeviceIndicator'
 
 const meta: Meta<typeof DeviceIndicator> = {
-  title: 'Shell/TopBar/DeviceMenu/DeviceIndicator',
+  title: 'Shell/DeviceIndicator',
   component: DeviceIndicator,
   tags: ['autodocs'],
   args: { status: 'connected' },
@@ -15,7 +15,7 @@ const meta: Meta<typeof DeviceIndicator> = {
     docs: {
       description: {
         component:
-          '**Molecule.** Composes [BluetoothIcon](?path=/docs/icons--docs), color-coded by ' +
+          '**Molecule.** Composes [BluetoothIcon](?path=/docs/foundations-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.',
       },

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

@@ -10,7 +10,7 @@ const DEVICES: Device[] = [
 ]
 
 const meta: Meta<typeof DeviceMenu> = {
-  title: 'Shell/TopBar/DeviceMenu',
+  title: 'Shell/DeviceMenu',
   component: DeviceMenu,
   tags: ['autodocs'],
   args: { devices: DEVICES, isOpen: false },
@@ -32,10 +32,10 @@ const meta: Meta<typeof DeviceMenu> = {
       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 ' +
+          '[Popover](?path=/docs/components-molecules-popover--docs) + ' +
+          '[DeviceIndicator](?path=/docs/shell-deviceindicator--docs) (trigger) + ' +
+          '[DeviceRow](?path=/docs/shell-devicerow--docs) (list) + ' +
+          '[Typography](?path=/docs/foundations-typography--docs) (header). Aggregates the bound devices ' +
           '(worst-of) for the glyph state. Click the glyph, or toggle the `isOpen` control.',
       },
     },

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

@@ -3,7 +3,7 @@ import { View } from 'react-native'
 import { DeviceRow } from './DeviceRow'
 
 const meta: Meta<typeof DeviceRow> = {
-  title: 'Shell/TopBar/DeviceMenu/DeviceRow',
+  title: 'Shell/DeviceRow',
   component: DeviceRow,
   tags: ['autodocs'],
   args: {
@@ -25,8 +25,8 @@ const meta: Meta<typeof DeviceRow> = {
       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). ' +
+          '[Indicator](?path=/docs/components-atoms-indicator--docs) (status dot) + ' +
+          '[Typography](?path=/docs/foundations-typography--docs) (`body2` name, `mono` id). ' +
           'Edit the `device` control (set `state` to `lost` / `available`, `slot` to `null`) to explore.',
       },
     },

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

@@ -0,0 +1,52 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View } from 'react-native'
+import { NavItem } from './NavItem'
+import { ActivityIcon } from '../icons'
+
+const meta: Meta<typeof NavItem> = {
+  title: 'Shell/NavItem',
+  component: NavItem,
+  tags: ['autodocs'],
+  args: { label: 'Live', active: false, live: false },
+  argTypes: {
+    label: { control: 'text' },
+    active: { control: 'boolean' },
+    live: { control: 'boolean' },
+    icon: { control: false },
+    onPress: { action: 'press' },
+  },
+  decorators: [
+    (Story) => (
+      <View className="w-[60px] items-center bg-background-base py-2">
+        <Story />
+      </View>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '**Molecule.** One category button — a glyph over an uppercase micro-label in a 46×46 target, ' +
+          'spanning the full 60px rail so the active accent bar sits flush to the edge. Composes an ' +
+          '[icon](?path=/docs/foundations-icons--docs) + [Typography](?path=/docs/foundations-typography--docs). Toggle ' +
+          '`active` / `live` to see the states.',
+      },
+    },
+  },
+  render: (args) => <NavItem {...args} icon={<ActivityIcon size={20} color="currentColor" />} />,
+}
+export default meta
+type Story = StoryObj<typeof NavItem>
+
+export const Default: Story = {}
+export const Active: Story = { args: { active: true } }
+export const LiveElsewhere: Story = {
+  args: { live: true },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Not the active view, but a set is running for this category → muted-green label.',
+      },
+    },
+  },
+}

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

@@ -0,0 +1,35 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { NavItem } from './NavItem'
+import { ActivityIcon } from '../icons'
+
+const icon = <ActivityIcon size={20} color="currentColor" />
+
+describe('NavItem', () => {
+  it('renders the label and is exposed as a tab', () => {
+    render(<NavItem icon={icon} label="Live" />)
+    expect(screen.getByRole('tab', { name: 'Live' })).toBeInTheDocument()
+  })
+
+  it('shows the accent bar when active', () => {
+    render(<NavItem icon={icon} label="Live" active />)
+    expect(screen.getByTestId('nav-item-accent')).toBeInTheDocument()
+  })
+
+  it('hides the accent bar when inactive', () => {
+    render(<NavItem icon={icon} label="Live" />)
+    expect(screen.queryByTestId('nav-item-accent')).toBeNull()
+  })
+
+  it('fires onPress when tapped', () => {
+    const onPress = vi.fn()
+    render(<NavItem icon={icon} label="Live" onPress={onPress} />)
+    fireEvent.click(screen.getByRole('tab', { name: 'Live' }))
+    expect(onPress).toHaveBeenCalledTimes(1)
+  })
+
+  it('renders the live-elsewhere state', () => {
+    const { container } = render(<NavItem icon={icon} label="Live" live />)
+    expect(container.firstChild).toBeInTheDocument()
+  })
+})

package/src/components/shell/NavItem.tsx

@@ -0,0 +1,75 @@
+import type { ReactNode } from 'react'
+import { Pressable, View } from 'react-native'
+import { cn } from '../../utils/cn'
+import { Typography } from '../custom/Typography'
+
+export interface NavItemProps {
+  /** The nav glyph (an icon from `components/icons`, rendered ~20px via `currentColor`). */
+  icon: ReactNode
+  /** Short label shown under the glyph (uppercased for display; used as the accessible name). */
+  label: string
+  /** Active category → left accent bar + brand-colored glyph & label. */
+  active?: boolean
+  /**
+   * A set is running for this category while it is NOT the active view
+   * (live-elsewhere) → a quiet muted-green label tint. Ignored when `active`.
+   */
+  live?: boolean
+  onPress?: () => void
+  className?: string
+}
+
+/**
+ * Shell S2 · NavItem — one category button in the {@link SideNav}: a 20px glyph
+ * over an uppercase micro-label in a 46×46 target. The button spans the full 60px
+ * rail so the active **left accent bar** sits flush to the rail's edge. States:
+ * active = accent bar + `brand-primary`; `live` (while not active) tints only the
+ * label `status-success-dark` (the glyph stays dim); otherwise dim `text-tertiary`.
+ */
+export function NavItem({
+  icon,
+  label,
+  active = false,
+  live = false,
+  onPress,
+  className,
+}: NavItemProps) {
+  const glyphColor = active ? 'text-brand-primary' : 'text-text-tertiary'
+  const labelColor = active
+    ? 'text-brand-primary'
+    : live
+      ? 'text-status-live-muted'
+      : 'text-text-tertiary'
+
+  return (
+    <Pressable
+      accessibilityRole="tab"
+      accessibilityState={{ selected: active }}
+      accessibilityLabel={label}
+      onPress={onPress}
+      className={cn('relative h-[46px] w-[60px] items-center justify-center', className)}
+    >
+      {active ? (
+        <View
+          testID="nav-item-accent"
+          className="absolute left-0 top-[13px] bottom-[13px] w-[3px] rounded-r-[3px] bg-brand-primary"
+        />
+      ) : null}
+      <View
+        className={cn(
+          'h-[46px] w-[46px] items-center justify-center gap-[3px] rounded-[11px]',
+          glyphColor
+        )}
+      >
+        {icon}
+        <Typography
+          variant="button"
+          color="inherit"
+          className={cn('text-[8.5px] font-bold uppercase tracking-[0.4px]', labelColor)}
+        >
+          {label}
+        </Typography>
+      </View>
+    </Pressable>
+  )
+}

package/src/components/shell/README.md

@@ -9,6 +9,23 @@ This README is the **index**: it maps each component's dependencies (**composes
 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: `SideNav` (the second shell unit, S2)
+
+```
+SideNav ...................... organism — the 60px left rail (Shell/SideNav)
+├─ NavItem ................... molecule × 4 (Live · Review · Plan · Body)
+│  ├─ icon ................... icons (shared primitive) — Activity/History/Layers/PersonStanding
+│  └─ Typography ............. titan · button variant (uppercase micro-label)
+└─ (accent bar) .............. bg-brand-primary edge bar on the active item
+```
+
+Decisions locked 2026-07-08 (specimen `coordination/design-explorations/shell/S2-sidenav/`): lucide glyphs
+(activity · history · layers · figure) · **Plan** label (narrower than "Program") · active = **left accent
+bar** (short, centered on the icon+label) · **60px** icon+micro-label · live cue = **muted-green label**
+(`status-live-muted`) on the Live item while a set runs off-Live · four items, no footer, no top-nav. Fixed
+60px at every width (labels sit under the glyph). `SideNav` is presentational — `activeKey` / `onNavigate` /
+`liveKey`; the app owns routing + which key is live.
+
 ## Specimen: `TopBar` (the first shell unit, S1)
 
 ```
@@ -33,6 +50,8 @@ TopBar ....................... organism — the chrome band (Shell/TopBar)
 
 | Component | Tier | Composes ↓ | Used-by ↑ |
 |---|---|---|---|
+| `SideNav` | organism | NavItem ×4, `components/icons` (Activity/History/Layers/PersonStanding) | dashboard app root *(planned)* |
+| `NavItem` | molecule | icon, Typography | SideNav |
 | `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)* |
@@ -79,8 +98,19 @@ Every leaf now composes a primitive rather than hand-rolling it:
 - **Lint guardrails** — components may not inline `linear-gradient` (use `surfaceGradient`); shell + icons may
   not use raw hex (use tokens).
 
+**S2 shared substrate:** four nav glyphs added to `components/icons` (`ActivityIcon`, `HistoryIcon`,
+`LayersIcon`, `PersonStandingIcon` — lucide-mirrored, like Dumbbell/Star), available system-wide.
+
 **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`.
+- **`status-live` token family (new, decoupled from success)** — introduced `status-live` (green-300, the
+  vivid LIVE-pill green) + `status-live-muted` (green-500 `#22A444`, the quiet nav cue) so "live" has its own
+  role: changing `status-success` no longer affects live, and vice-versa. Wired the full chain (semantic →
+  config → global.css → tailwind); `Indicator` gained a `live` color; the S1 LIVE pill was repointed
+  `success`→`live` (value-preserving). This realized a slice of TD-05.09 Fork 1b (wiring ramp steps as tokens).
+- **`aria-selected` on `NavItem`** — RNW does not emit `aria-selected` from `accessibilityState={{selected}}`
+  in the jsdom test env, so active-state is asserted via the accent-bar testID. Confirm the on-device/RNW
+  build exposes selection to AT (may need an explicit `aria-selected` for full tab semantics).