@titan-design/react-ui 0.12.0 → 0.13.0

package/src/components/custom/charts/SparkBars.tsx

@@ -0,0 +1,85 @@
+// Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
+import { View, type ViewProps } from 'react-native'
+import { cn } from '../../../utils/cn'
+import { resolveColor } from '../../../theme/resolve-color'
+
+/** Shortest bar drawn, so an all-but-empty series still reads as a series. */
+const MIN_BAR_HEIGHT = 2
+
+export interface SparkBarsProps extends Omit<ViewProps, 'accessibilityLabel'> {
+  /** The series, oldest first. Negative values draw in `negativeColor`. */
+  values: number[]
+  /** Overall bar-field height in px. */
+  height?: number
+  /** Width of a single bar in px. */
+  barWidth?: number
+  /** Gap between bars in px. */
+  gap?: number
+  /** Keep only the last N values — a sparkline is a recent-history glance, not an archive. */
+  maxBars?: number
+  /** Fill for non-negative bars. Defaults to `result-improve`. */
+  color?: string
+  /** Fill for negative bars. Defaults to `result-degrade`. */
+  negativeColor?: string
+  /** Screen-reader description. Defaults to a bar count. */
+  label?: string
+  className?: string
+}
+
+/**
+ * SparkBars — a tiny bar-mark sparkline for a signed series.
+ *
+ * The bar-mark counterpart to {@link Sparkline}: where a line reads a
+ * *trajectory*, bars read *discrete per-period magnitude*, which is what
+ * per-session activity and per-session net growth actually are. Bars are scaled
+ * by absolute value so a negative period is as tall as an equally large
+ * positive one, and tinted with `negativeColor` to carry the sign.
+ *
+ * @example
+ * <SparkBars values={[3, 8, -2, 14]} height={22} />
+ */
+export function SparkBars({
+  values,
+  height = 22,
+  barWidth = 3,
+  gap = 2,
+  maxBars = 24,
+  color,
+  negativeColor,
+  label,
+  className,
+  ...props
+}: SparkBarsProps) {
+  const shown = values.slice(-maxBars)
+  // A per-period delta going up or down is `result-*` (a change in a measurement),
+  // not `status-*` (a thing being broken). See TOKENS.md §1.
+  const positiveFill = color ?? resolveColor('result-improve')
+  const negativeFill = negativeColor ?? resolveColor('result-degrade')
+  // Scaling on magnitude keeps a -100 as tall as a +100; sign is carried by fill.
+  const peak = Math.max(1, ...shown.map((v) => Math.abs(v)))
+
+  return (
+    <View
+      style={{ height, gap }}
+      className={cn('flex-row items-end', className)}
+      accessibilityRole="image"
+      accessibilityLabel={label ?? `Bar sparkline with ${shown.length} values`}
+      testID="spark-bars"
+      {...props}
+    >
+      {shown.map((v, i) => (
+        <View
+          key={i}
+          style={{
+            height: Math.max(MIN_BAR_HEIGHT, Math.round((Math.abs(v) / peak) * height)),
+            width: barWidth,
+            backgroundColor: v < 0 ? negativeFill : positiveFill,
+          }}
+          className="rounded-t-[1px]"
+          accessibilityElementsHidden
+          testID={`spark-bars-bar-${i}`}
+        />
+      ))}
+    </View>
+  )
+}

package/src/components/custom/charts/index.ts

@@ -0,0 +1,3 @@
+// Public chart primitives. `SetBarChart` and `live-rep-growth` are deliberately
+// not re-exported here — they are workout-internal and imported by path.
+export * from './SparkBars'

package/src/components/custom/index.ts

@@ -13,3 +13,6 @@ export * from './Fatigue'
 export * from './Treemap'
 export * from './Scatter'
 export * from './Gauge'
+export * from './charts'
+export * from './ActiveWork'
+export * from './Prose'

package/src/components/custom/stepper/Stepper.stories.tsx

@@ -5,7 +5,16 @@ import { Stepper, Step, StepIndicator, StepLabel, StepContent } from './Stepper'
 const meta: Meta<typeof Stepper> = {
   title: 'Components/Molecules/Stepper',
   component: Stepper,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:candidate', '!status:review'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Composes RN primitives only. The five parts share step index and orientation through ' +
+          'a context, the same shape as **Tabs**.',
+      },
+    },
+  },
   argTypes: {
     activeStep: {
       control: { type: 'number', min: 0, max: 4 },
@@ -124,9 +133,7 @@ export const VerticalWithContent: Story = {
         <StepIndicator />
         <StepLabel>Create Account</StepLabel>
         <StepContent>
-          <Text className="text-text-secondary text-sm">
-            Account creation is complete.
-          </Text>
+          <Text className="text-text-secondary text-sm">Account creation is complete.</Text>
         </StepContent>
       </Step>
       <Step>
@@ -147,9 +154,7 @@ export const VerticalWithContent: Story = {
         <StepIndicator />
         <StepLabel>Configure Settings</StepLabel>
         <StepContent>
-          <Text className="text-text-secondary text-sm">
-            Adjust your preferences.
-          </Text>
+          <Text className="text-text-secondary text-sm">Adjust your preferences.</Text>
         </StepContent>
       </Step>
     </Stepper>
@@ -221,9 +226,7 @@ export const ActiveStepProgression: Story = {
     <View style={{ gap: 24 }}>
       {[0, 1, 2, 3].map((activeStep) => (
         <View key={activeStep}>
-          <Text className="text-text-secondary text-xs mb-2">
-            Active step: {activeStep}
-          </Text>
+          <Text className="text-text-secondary text-xs mb-2">Active step: {activeStep}</Text>
           <Stepper activeStep={activeStep} orientation="horizontal">
             <Step>
               <StepIndicator />

package/src/components/custom/stepper/Stepper.test.tsx

@@ -1,13 +1,7 @@
 import { describe, it, expect } from 'vitest'
 import { render, screen } from '@testing-library/react'
 import { axe } from 'jest-axe'
-import {
-  Stepper,
-  Step,
-  StepIndicator,
-  StepLabel,
-  StepContent,
-} from './Stepper'
+import { Stepper, Step, StepIndicator, StepLabel, StepContent } from './Stepper'
 
 function renderStepper(activeStep = 1) {
   return render(

package/src/components/custom/stepper/Stepper.tsx

@@ -65,9 +65,7 @@ export function Stepper({
             return (
               <>
                 {React.cloneElement(child as React.ReactElement<any>, { index })}
-                {index < React.Children.count(children) - 1 && (
-                  <StepConnector index={index} />
-                )}
+                {index < React.Children.count(children) - 1 && <StepConnector index={index} />}
               </>
             )
           }
@@ -88,22 +86,12 @@ function StepConnector({ index }: StepConnectorProps) {
 
   if (orientation === 'horizontal') {
     return (
-      <View
-        className={cn(
-          'flex-1 h-0.5 mx-2',
-          isCompleted ? 'bg-brand-primary' : 'bg-hairline'
-        )}
-      />
+      <View className={cn('flex-1 h-0.5 mx-2', isCompleted ? 'bg-brand-primary' : 'bg-hairline')} />
     )
   }
 
   return (
-    <View
-      className={cn(
-        'w-0.5 h-8 ml-4 my-1',
-        isCompleted ? 'bg-brand-primary' : 'bg-hairline'
-      )}
-    />
+    <View className={cn('w-0.5 h-8 ml-4 my-1', isCompleted ? 'bg-brand-primary' : 'bg-hairline')} />
   )
 }
 
@@ -123,10 +111,8 @@ export interface StepProps {
 export function Step({ index = 0, status, className, children }: StepProps) {
   const { activeStep, orientation } = useContext(StepperContext)
 
-  const derivedStatus: StepStatus = status || (
-    index < activeStep ? 'completed' :
-    index === activeStep ? 'active' : 'upcoming'
-  )
+  const derivedStatus: StepStatus =
+    status || (index < activeStep ? 'completed' : index === activeStep ? 'active' : 'upcoming')
 
   return (
     <View
@@ -216,10 +202,13 @@ export function StepLabel({ status = 'upcoming', className, children }: StepLabe
       className={cn(
         'text-sm font-medium',
         orientation === 'horizontal' ? 'mt-2' : 'ml-3',
-        status === 'active' ? 'text-text-primary' :
-        status === 'completed' ? 'text-brand-primary' :
-        status === 'error' ? 'text-status-error' :
-        'text-text-secondary',
+        status === 'active'
+          ? 'text-text-primary'
+          : status === 'completed'
+            ? 'text-brand-primary'
+            : status === 'error'
+              ? 'text-status-error'
+              : 'text-text-secondary',
         className
       )}
     >
@@ -242,9 +231,5 @@ export interface StepContentProps {
 export function StepContent({ status = 'upcoming', className, children }: StepContentProps) {
   if (status !== 'active') return null
 
-  return (
-    <View className={cn('ml-11 mt-2 pb-4', className)}>
-      {children}
-    </View>
-  )
+  return <View className={cn('ml-11 mt-2 pb-4', className)}>{children}</View>
 }

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

@@ -20,7 +20,7 @@ import {
 
 const meta: Meta = {
   title: 'Foundations/Icons',
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:candidate', '!status:review'],
   parameters: {
     docs: {
       description: {

package/src/components/icons/icons.tsx

@@ -151,3 +151,54 @@ export function InfoIcon(props: IconProps) {
     </SvgIcon>
   )
 }
+
+// ---------------------------------------------------------------------------
+// AW-132 · App brand marks — the mark half of a `BrandLockup` for each app that
+// is likely to mount the shell. Sized 14 by default, like `VoltrasMark`.
+// ---------------------------------------------------------------------------
+
+/** Headphones glyph (mirrors lucide-react `Headphones`). Audiobook brand mark. */
+export function HeadphonesIcon({ size = 14, ...props }: IconProps) {
+  return (
+    <SvgIcon size={size} {...props}>
+      <path d="M3 14h3a2 2 0 0 1 2 2v3a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-5a9 9 0 0 1 18 0v5a2 2 0 0 1-2 2h-1a2 2 0 0 1-2-2v-3a2 2 0 0 1 2-2h3" />
+    </SvgIcon>
+  )
+}
+
+/** Kanban board glyph (mirrors lucide-react `SquareKanban`). Active-work brand mark. */
+export function KanbanIcon({ size = 14, ...props }: IconProps) {
+  return (
+    <SvgIcon size={size} {...props}>
+      <rect width="18" height="18" x="3" y="3" rx="2" />
+      <path d="M8 7v7" />
+      <path d="M12 7v4" />
+      <path d="M16 7v9" />
+    </SvgIcon>
+  )
+}
+
+/** Robot glyph (mirrors lucide-react `Bot`). Agent-dashboard brand mark. */
+export function BotIcon({ size = 14, ...props }: IconProps) {
+  return (
+    <SvgIcon size={size} {...props}>
+      <path d="M12 8V4H8" />
+      <rect width="16" height="12" x="4" y="8" rx="2" />
+      <path d="M2 14h2" />
+      <path d="M20 14h2" />
+      <path d="M15 13v2" />
+      <path d="M9 13v2" />
+    </SvgIcon>
+  )
+}
+
+/** Brain glyph (mirrors lucide-react `Brain`). Brain-app brand mark. */
+export function BrainIcon({ size = 14, ...props }: IconProps) {
+  return (
+    <SvgIcon size={size} {...props}>
+      <path d="M12 5a3 3 0 1 0-5.997.125 4 4 0 0 0-2.526 5.77 4 4 0 0 0 .556 6.588A4 4 0 1 0 12 18Z" />
+      <path d="M12 5a3 3 0 1 1 5.997.125 4 4 0 0 1 2.526 5.77 4 4 0 0 1-.556 6.588A4 4 0 1 1 12 18Z" />
+      <path d="M15 13a4.5 4.5 0 0 1-3-4 4.5 4.5 0 0 1-3 4" />
+    </SvgIcon>
+  )
+}

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

@@ -0,0 +1,150 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View, Text } from 'react-native'
+import { Surface } from '../ui/surface'
+import { Pill } from '../ui/pill'
+import { Typography } from '../custom/Typography'
+import { BotIcon, BrainIcon, HeadphonesIcon, LayersIcon, StarIcon } from '../icons'
+import { AppShell } from './AppShell'
+import { brandKeys } from './brands'
+import { type SideNavItem } from './SideNav'
+
+const brainNav: SideNavItem[] = [
+  { key: 'notes', label: 'Notes', icon: <LayersIcon size={20} color="currentColor" /> },
+  { key: 'graph', label: 'Graph', icon: <BrainIcon size={20} color="currentColor" /> },
+  { key: 'agents', label: 'Agents', icon: <BotIcon size={20} color="currentColor" /> },
+]
+
+const audiobookNav: SideNavItem[] = [
+  { key: 'library', label: 'Library', icon: <HeadphonesIcon size={20} color="currentColor" /> },
+  { key: 'saved', label: 'Saved', icon: <StarIcon size={20} color="currentColor" /> },
+]
+
+function Page({ title }: { title: string }) {
+  return (
+    <View className="flex-1 gap-1.5 p-7">
+      <Typography variant="h4" color="primary">
+        {title}
+      </Typography>
+      <Typography variant="body2" color="tertiary">
+        A page mounts its content here; the shell keeps the nav + top-bar chrome persistent.
+      </Typography>
+    </View>
+  )
+}
+
+/**
+ * `Pages/AppShell` — the generic dashboard chrome as one registered surface.
+ * The app supplies its brand, its nav categories and its own top-bar chrome.
+ */
+const meta: Meta<typeof AppShell> = {
+  title: 'Pages/AppShell',
+  component: AppShell,
+  tags: ['autodocs', 'status:candidate', '!status:review'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          '**Page shell (generic).** Composes ' +
+          '[SideNav](?path=/docs/shell-sidenav--docs) + ' +
+          '[TopBar](?path=/docs/shell-topbar--docs) over a `children` content slot.\n\n' +
+          '**Composition (AW-132).** It knows nothing about any one app. Chrome arrives ' +
+          'through `topBarTrailing`; categories through `navItems`; `topBar` and `nav` ' +
+          'replace those regions outright. An app builds its own shell by composing this one ' +
+          '— see [WorkoutShell](?path=/docs/pages-workoutshell--docs).',
+      },
+    },
+  },
+  argTypes: {
+    brand: { control: 'select', options: brandKeys },
+    onNavigate: { control: false },
+    topBar: { control: false },
+    nav: { control: false },
+    topBarTrailing: { control: false },
+    navItems: { control: false },
+  },
+  decorators: [
+    (Story) => (
+      <Surface level="base" className="min-h-screen">
+        <Story />
+      </Surface>
+    ),
+  ],
+}
+
+export default meta
+type Story = StoryObj<typeof AppShell>
+
+/** No app chrome at all — the frame on its own. */
+export const Default: Story = {
+  args: { brand: 'voltras', navItems: brainNav, activeKey: 'notes' },
+}
+
+/** The brain app: its own brand, categories, top-bar chrome and page. */
+export const BrainApp: Story = {
+  args: {
+    brand: 'brain',
+    navItems: brainNav,
+    activeKey: 'graph',
+    topBarTrailing: [
+      <Pill key="index" tone="success" leading="dot" size="xs">
+        indexed
+      </Pill>,
+      <Pill key="vaults" tone="neutral" size="xs">
+        4 vaults
+      </Pill>,
+    ],
+  },
+  render: (args) => (
+    <AppShell {...args}>
+      <Page title="Graph" />
+    </AppShell>
+  ),
+}
+
+/** The audiobook app in the same frame — different brand, categories and chrome. */
+export const AudiobookApp: Story = {
+  args: {
+    brand: 'audiobook',
+    navItems: audiobookNav,
+    activeKey: 'library',
+    liveKey: 'saved',
+    topBarTrailing: (
+      <Pill tone="brand-secondary" leading="dot" size="xs">
+        3 downloading
+      </Pill>
+    ),
+  },
+  render: (args) => (
+    <AppShell {...args}>
+      <Page title="Library" />
+    </AppShell>
+  ),
+}
+
+/** Both slots replaced: the app brings its own bar and its own rail. */
+export const ReplacedRegions: Story = {
+  args: { navItems: brainNav, activeKey: 'notes' },
+  render: (args) => (
+    <AppShell
+      {...args}
+      topBar={
+        <Surface level="elevated" className="h-[46px] justify-center border-b border-hairline px-4">
+          <Text className="font-heading text-sm text-text-secondary">an app-owned bar</Text>
+        </Surface>
+      }
+      nav={
+        <Surface
+          level="base"
+          className="w-[60px] items-center justify-center border-r border-hairline"
+        >
+          <Typography variant="microLabel" color="tertiary">
+            rail
+          </Typography>
+        </Surface>
+      }
+    >
+      <Page title="Anything" />
+    </AppShell>
+  ),
+}

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

@@ -0,0 +1,70 @@
+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 { AppShell } from './AppShell'
+import { type SideNavItem } from './SideNav'
+
+const navItems: SideNavItem[] = [
+  { key: 'notes', label: 'Notes', icon: null },
+  { key: 'graph', label: 'Graph', icon: null },
+]
+
+describe('AppShell', () => {
+  it('composes the SideNav rail from the supplied categories', () => {
+    render(<AppShell navItems={navItems} activeKey="notes" />)
+    expect(screen.getByRole('tablist')).toBeInTheDocument()
+    ;['Notes', 'Graph'].forEach((name) => {
+      expect(screen.getByRole('tab', { name })).toBeInTheDocument()
+    })
+  })
+
+  it('renders the content-slot placeholder when no children are given', () => {
+    render(<AppShell navItems={navItems} activeKey="notes" />)
+    expect(screen.getByText('main content region')).toBeInTheDocument()
+  })
+
+  it('mounts children in the content slot and drops the placeholder', () => {
+    render(
+      <AppShell navItems={navItems} activeKey="graph">
+        <Text>my page body</Text>
+      </AppShell>
+    )
+    expect(screen.getByText('my page body')).toBeInTheDocument()
+    expect(screen.queryByText('main content region')).not.toBeInTheDocument()
+  })
+
+  it('forwards nav taps through onNavigate', () => {
+    const onNavigate = vi.fn()
+    render(<AppShell navItems={navItems} activeKey="notes" onNavigate={onNavigate} />)
+    fireEvent.click(screen.getByRole('tab', { name: 'Graph' }))
+    expect(onNavigate).toHaveBeenCalledWith('graph')
+  })
+
+  it('renders app chrome in the top bar without knowing what it is', () => {
+    render(<AppShell navItems={navItems} activeKey="notes" topBarTrailing={<Text>3 jobs</Text>} />)
+    expect(screen.getByText('3 jobs')).toBeInTheDocument()
+  })
+
+  it('takes a whole replacement top bar and nav', () => {
+    render(
+      <AppShell topBar={<Text>my own bar</Text>} nav={<Text>my own rail</Text>}>
+        <Text>body</Text>
+      </AppShell>
+    )
+    expect(screen.getByText('my own bar')).toBeInTheDocument()
+    expect(screen.getByText('my own rail')).toBeInTheDocument()
+    expect(screen.queryByText('VOLTRAS')).not.toBeInTheDocument()
+    expect(screen.queryByRole('tablist')).not.toBeInTheDocument()
+  })
+
+  it('carries the brand through to the top bar', () => {
+    render(<AppShell brand="agents" navItems={navItems} activeKey="notes" />)
+    expect(screen.getByText('AGENTS')).toBeInTheDocument()
+  })
+
+  it('has no a11y violations', async () => {
+    const { container } = render(<AppShell navItems={navItems} activeKey="notes" />)
+    expect(await axe(container)).toHaveNoViolations()
+  })
+})

package/src/components/shell/AppShell.tsx

@@ -0,0 +1,90 @@
+import type { ReactNode } from 'react'
+import { View, Text } from 'react-native'
+import { cn } from '../../utils/cn'
+import { Surface } from '../ui/surface'
+import { SideNav, type SideNavItem } from './SideNav'
+import { TopBar } from './TopBar'
+import { brandPresets, type BrandKey } from './brands'
+
+export interface AppShellProps {
+  /** Which app identity the default {@link TopBar} and nav accent render. */
+  brand?: BrandKey
+  /** Brand subtitle on the default top bar. */
+  subtitle?: string
+  /** App chrome for the default top bar's right cluster (divider-separated). */
+  topBarTrailing?: ReactNode | ReactNode[]
+  /** Replace the whole top bar. Wins over `brand` / `subtitle` / `topBarTrailing`. */
+  topBar?: ReactNode
+  /** Nav categories, top → bottom. */
+  navItems?: SideNavItem[]
+  /** Active nav category key. */
+  activeKey?: string
+  /** A category with off-view live activity → a quiet cue on that item. */
+  liveKey?: string | null
+  onNavigate?: (key: string) => void
+  /** Replace the whole left rail. Wins over `navItems` / `activeKey` / `liveKey`. */
+  nav?: ReactNode
+  /** Main content region. A placeholder renders when omitted. */
+  children?: ReactNode
+  className?: string
+}
+
+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>
+  )
+}
+
+/**
+ * `AppShell` — the generic dashboard chrome: a {@link TopBar} band over a
+ * {@link SideNav} rail and a `children` content region. It knows nothing about
+ * any one app: chrome arrives through the `topBarTrailing` slot (or the whole
+ * `topBar` / `nav` slots), and categories through `navItems`. An app builds its
+ * own shell by composing this one — see `shell/workout/WorkoutShell`.
+ *
+ * @example
+ * <AppShell brand="brain" navItems={brainNavItems} activeKey={key} onNavigate={go}>
+ *   <BrainPage />
+ * </AppShell>
+ */
+export function AppShell({
+  brand = 'voltras',
+  subtitle,
+  topBarTrailing,
+  topBar,
+  navItems = [],
+  activeKey = '',
+  liveKey = null,
+  onNavigate,
+  nav,
+  children,
+  className,
+}: AppShellProps) {
+  const { accentClassName, accentBarClassName } = brandPresets[brand]
+
+  return (
+    // Column: the TopBar spans the FULL width across the top, and the SideNav sits BELOW it
+    // in the content row (not a full-height left rail). This keeps the brand/status band
+    // unbroken edge-to-edge and lets the nav align under it. The shell is the outermost
+    // Surface — it owns the base plane and seeds the on-surface colour context (mode) for
+    // the whole dashboard tree.
+    <Surface level="base" className={cn('flex-1', className)}>
+      {topBar ?? <TopBar brand={brand} subtitle={subtitle} trailing={topBarTrailing} />}
+      <View className="flex-1 flex-row">
+        {nav ?? (
+          <SideNav
+            items={navItems}
+            activeKey={activeKey}
+            liveKey={liveKey}
+            accentClassName={accentClassName}
+            accentBarClassName={accentBarClassName}
+            onNavigate={onNavigate}
+          />
+        )}
+        <View className="flex-1">{children ?? <ContentPlaceholder />}</View>
+      </View>
+    </Surface>
+  )
+}