@titan-design/react-ui 0.12.1 → 0.14.0

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

@@ -0,0 +1,55 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { SparkBars } from './SparkBars'
+
+const meta: Meta<typeof SparkBars> = {
+  title: 'Custom/Charts/SparkBars',
+  component: SparkBars,
+  tags: ['autodocs', 'status:candidate', '!status:review'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '**Atom.** A tiny bar-mark sparkline for a signed series — the counterpart to ' +
+          '[Sparkline](?path=/docs/custom-workout-dataviz-sparkline--docs). Where a line reads a *trajectory*, ' +
+          'bars read *discrete per-period magnitude*. Bars scale on absolute value so a negative ' +
+          'period is as tall as an equally large positive one, with the sign carried by fill colour.',
+      },
+    },
+  },
+  args: {
+    values: [120, 340, -80, 910, 420, 0, 1580, 260, -310, 740, 1120, 90],
+    height: 22,
+    barWidth: 3,
+    gap: 2,
+    maxBars: 24,
+  },
+}
+export default meta
+type Story = StoryObj<typeof SparkBars>
+
+export const Default: Story = {}
+
+/** All-positive — the plain growth case. */
+export const AllPositive: Story = {
+  args: { values: [40, 120, 260, 310, 480, 520, 900] },
+}
+
+/** All-negative — every bar takes the error token. */
+export const AllNegative: Story = {
+  args: { values: [-40, -120, -260, -310, -480] },
+}
+
+/** Taller field, as used in the file-history growth block. */
+export const Tall: Story = {
+  args: { height: 34, barWidth: 5, gap: 3 },
+}
+
+/** `maxBars` keeps only the most recent values — a sparkline is a glance, not an archive. */
+export const Truncated: Story = {
+  args: { values: Array.from({ length: 60 }, (_, i) => (i % 7) * 30 - 40), maxBars: 12 },
+}
+
+/** An empty series renders an empty field rather than collapsing the layout. */
+export const Empty: Story = {
+  args: { values: [] },
+}

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

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { SparkBars } from './SparkBars'
+
+describe('SparkBars', () => {
+  it('renders one bar per value', () => {
+    render(<SparkBars values={[1, 2, 3, 4]} />)
+    expect(screen.getAllByTestId(/^spark-bars-bar-/)).toHaveLength(4)
+  })
+
+  it('keeps only the last maxBars values', () => {
+    render(<SparkBars values={[1, 2, 3, 4, 5, 6]} maxBars={2} />)
+    expect(screen.getAllByTestId(/^spark-bars-bar-/)).toHaveLength(2)
+  })
+
+  it('renders no bars for an empty series but keeps the field', () => {
+    render(<SparkBars values={[]} />)
+    expect(screen.queryByTestId(/^spark-bars-bar-/)).not.toBeInTheDocument()
+    expect(screen.getByTestId('spark-bars')).toBeInTheDocument()
+  })
+
+  it('tints bars by sign with the result-* tokens', () => {
+    // Asserts the token, not its current value: resolveColor emits the CSS var on
+    // web, which is what keeps the chart theme-correct.
+    render(<SparkBars values={[10, -10]} />)
+    expect(screen.getByTestId('spark-bars-bar-0')).toHaveStyle({
+      backgroundColor: 'var(--color-result-improve)',
+    })
+    expect(screen.getByTestId('spark-bars-bar-1')).toHaveStyle({
+      backgroundColor: 'var(--color-result-degrade)',
+    })
+  })
+
+  it('honours explicit color overrides', () => {
+    render(<SparkBars values={[10, -10]} color="#00ff00" negativeColor="#ff00ff" />)
+    expect(screen.getByTestId('spark-bars-bar-0')).toHaveStyle({
+      backgroundColor: 'rgb(0, 255, 0)',
+    })
+    expect(screen.getByTestId('spark-bars-bar-1')).toHaveStyle({
+      backgroundColor: 'rgb(255, 0, 255)',
+    })
+  })
+
+  it('scales bars on magnitude, so equal-magnitude values are equally tall', () => {
+    render(<SparkBars values={[100, -100, 50]} height={40} />)
+    const [a, b, c] = ['0', '1', '2'].map((i) => screen.getByTestId(`spark-bars-bar-${i}`))
+    expect(a).toHaveStyle({ height: '40px' })
+    expect(b).toHaveStyle({ height: '40px' })
+    expect(c).toHaveStyle({ height: '20px' })
+  })
+
+  it('gives a zero value the minimum bar height rather than collapsing it', () => {
+    render(<SparkBars values={[100, 0]} height={40} />)
+    expect(screen.getByTestId('spark-bars-bar-1')).toHaveStyle({ height: '2px' })
+  })
+
+  it('exposes a default accessible label and accepts an override', () => {
+    const { rerender } = render(<SparkBars values={[1, 2]} />)
+    expect(screen.getByLabelText('Bar sparkline with 2 values')).toBeInTheDocument()
+    rerender(<SparkBars values={[1, 2]} label="Growth for open.ts" />)
+    expect(screen.getByLabelText('Growth for open.ts')).toBeInTheDocument()
+  })
+
+  it('has no a11y violations', async () => {
+    const { container } = render(<SparkBars values={[3, -1, 4]} />)
+    expect(await axe(container)).toHaveNoViolations()
+  })
+})

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/flatBarGeometry.test.ts

@@ -0,0 +1,41 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { SET_LEVEL_FLAT_BAR, REP_LEVEL_FLAT_BAR } from './flatBarGeometry'
+
+const DIR = path.dirname(fileURLToPath(import.meta.url))
+const segmentedBarSource = readFileSync(path.join(DIR, '../Workout/SegmentedBar.tsx'), 'utf8')
+const setBarChartSource = readFileSync(path.join(DIR, 'SetBarChart.tsx'), 'utf8')
+
+describe('flat-bar geometry (VW-86)', () => {
+  it('documents intentionally different set-level and rep-level sizes', () => {
+    expect(SET_LEVEL_FLAT_BAR).toEqual({ height: 8, gap: 5, radius: 2 })
+    expect(REP_LEVEL_FLAT_BAR).toEqual({ height: null, gapFloor: 2, radius: 5 })
+  })
+
+  it('SegmentedBar imports its geometry from the shared module rather than its own literals', () => {
+    expect(segmentedBarSource).toMatch(
+      /import\s*\{\s*SET_LEVEL_FLAT_BAR\s*\}\s*from\s*'\.\.\/charts\/flatBarGeometry'/
+    )
+    // The old hardcoded defaults must be gone from the component's own prop destructuring.
+    expect(segmentedBarSource).not.toMatch(/height\s*=\s*8\b/)
+    expect(segmentedBarSource).not.toMatch(/radius\s*=\s*2\b/)
+    expect(segmentedBarSource).toMatch(/height\s*=\s*SET_LEVEL_FLAT_BAR\.height/)
+    expect(segmentedBarSource).toMatch(/radius\s*=\s*SET_LEVEL_FLAT_BAR\.radius/)
+  })
+
+  it('SetBarChart imports its geometry from the shared module rather than its own literals', () => {
+    expect(setBarChartSource).toMatch(
+      /import\s*\{\s*REP_LEVEL_FLAT_BAR\s*\}\s*from\s*'\.\/flatBarGeometry'/
+    )
+    expect(setBarChartSource).not.toMatch(/const MIN_BAR_GAP = 2\b/)
+    expect(setBarChartSource).not.toMatch(/const DEFAULT_BAR_RADIUS = 5\b/)
+    expect(setBarChartSource).toMatch(/const MIN_BAR_GAP = REP_LEVEL_FLAT_BAR\.gapFloor/)
+    expect(setBarChartSource).toMatch(/const DEFAULT_BAR_RADIUS = REP_LEVEL_FLAT_BAR\.radius/)
+  })
+
+  it('SegmentedBar keeps SEGMENTED_BAR_GAP derived from the shared set-level gap', () => {
+    expect(segmentedBarSource).toMatch(/const SEGMENTED_BAR_GAP = SET_LEVEL_FLAT_BAR\.gap/)
+  })
+})

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

@@ -0,0 +1,32 @@
+/**
+ * The flat-bar geometry `SegmentedBar` (set-level: one row per SET, e.g. SetStrip/SessionRail)
+ * and `SetBarChart` (rep-level: one bar per REP within a set) each declare as their own component
+ * defaults. VW-86 named the fact that these lived in two files with no shared source as the drift
+ * risk: a future edit to one could silently diverge from the other without anyone noticing they
+ * were ever meant to be compared.
+ *
+ * They are NOT unified into one set of numbers — a strip of SETS across a session and a chart of
+ * REPS within one set are genuinely different sizes by design. This module exists so that
+ * difference is a documented, single-sourced choice instead of two numbers that happen to match
+ * or drift by accident.
+ */
+
+/** `SegmentedBar`'s own default geometry (set-level: one row per SET). */
+export const SET_LEVEL_FLAT_BAR = {
+  /** Track height (px). */
+  height: 8,
+  /** Gap between segment slots (px) — also SetStrip's between-set gap, see `SEGMENTED_BAR_GAP`. */
+  gap: 5,
+  /** Corner radius (px). */
+  radius: 2,
+} as const
+
+/** `SetBarChart`'s own default geometry (rep-level: one bar per REP within a set). */
+export const REP_LEVEL_FLAT_BAR = {
+  /** No fixed height default — SetBarChart's `height` is a required prop set by the caller. */
+  height: null,
+  /** Inter-bar gap is proportional (`gapRatio · barWidth`), floored at this many px. */
+  gapFloor: 2,
+  /** Corner radius (px) default. */
+  radius: 5,
+} as const

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
@@ -175,6 +161,13 @@ export function StepIndicator({
     error: 'bg-status-error border-status-error',
   }
 
+  const glyphStyles: Record<StepStatus, string> = {
+    completed: 'text-on-brand-primary',
+    active: 'text-on-brand-primary',
+    upcoming: 'text-text-secondary',
+    error: 'text-on-status-error',
+  }
+
   return (
     <View
       className={cn(
@@ -184,12 +177,7 @@ export function StepIndicator({
       )}
     >
       {icon || (
-        <Text
-          className={cn(
-            'text-sm font-semibold',
-            status === 'upcoming' ? 'text-text-secondary' : 'text-white'
-          )}
-        >
+        <Text className={cn('text-sm font-semibold', glyphStyles[status])}>
           {status === 'completed' ? '✓' : index + 1}
         </Text>
       )}
@@ -216,10 +204,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 +233,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>
+  )
+}