@titan-design/react-ui 0.6.0 → 0.8.0

package/src/components/ui/tooltip/Tooltip.stories.tsx

@@ -4,7 +4,7 @@ import { Tooltip } from './Tooltip'
 import { Button, ButtonText } from '../button'
 
 const meta: Meta<typeof Tooltip> = {
-  title: 'Components/Tooltip',
+  title: 'Components/Molecules/Tooltip',
   component: Tooltip,
   tags: ['autodocs'],
   argTypes: {

package/src/examples/react-hook-form/ReactHookForm.stories.tsx

@@ -10,7 +10,7 @@ import { RhfContactForm, type ContactFormValues } from './RhfContactForm'
  * `Controller` render-prop idiom. See `ControlledFields.tsx` for the adapters.
  */
 const meta: Meta<typeof RhfContactForm> = {
-  title: 'Examples/React Hook Form',
+  title: 'Lab/Recipes/React Hook Form',
   component: RhfContactForm,
   tags: ['autodocs'],
   parameters: {

package/src/hooks/index.ts

@@ -0,0 +1,2 @@
+export { useTimer, formatDuration } from './useTimer'
+export type { UseTimerOptions, TimerState, TimerMode } from './useTimer'

package/src/hooks/useTimer.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { useTimer, formatDuration } from './useTimer'
+
+describe('formatDuration', () => {
+  it('formats zero as 0:00', () => {
+    expect(formatDuration(0)).toBe('0:00')
+  })
+
+  it('pads seconds with a leading zero', () => {
+    expect(formatDuration(65000)).toBe('1:05')
+  })
+
+  it('rounds partial seconds up', () => {
+    expect(formatDuration(4500)).toBe('0:05')
+  })
+
+  it('clamps negative input to 0:00', () => {
+    expect(formatDuration(-1000)).toBe('0:00')
+  })
+
+  it('formats multi-minute durations', () => {
+    expect(formatDuration(150000)).toBe('2:30')
+  })
+})
+
+describe('useTimer (controlled, down)', () => {
+  it('derives remaining, progress, and label from elapsedMs', () => {
+    const { result } = renderHook(() =>
+      useTimer({ mode: 'down', durationMs: 100000, elapsedMs: 30000 })
+    )
+    expect(result.current.remainingMs).toBe(70000)
+    expect(result.current.progress).toBeCloseTo(0.3)
+    expect(result.current.label).toBe('1:10')
+    expect(result.current.done).toBe(false)
+  })
+
+  it('clamps remaining to 0 and progress to 1 when elapsed exceeds duration', () => {
+    const { result } = renderHook(() =>
+      useTimer({ mode: 'down', durationMs: 100000, elapsedMs: 200000 })
+    )
+    expect(result.current.remainingMs).toBe(0)
+    expect(result.current.progress).toBe(1)
+    expect(result.current.label).toBe('0:00')
+    expect(result.current.done).toBe(true)
+  })
+
+  it('reports progress 1 and done for a zero-duration countdown', () => {
+    const { result } = renderHook(() => useTimer({ mode: 'down', durationMs: 0, elapsedMs: 0 }))
+    expect(result.current.progress).toBe(1)
+    expect(result.current.done).toBe(true)
+    expect(result.current.label).toBe('0:00')
+  })
+})
+
+describe('useTimer (controlled, up)', () => {
+  it('counts elapsed upward and computes progress against duration', () => {
+    const { result } = renderHook(() =>
+      useTimer({ mode: 'up', durationMs: 120000, elapsedMs: 30000 })
+    )
+    expect(result.current.elapsedMs).toBe(30000)
+    expect(result.current.progress).toBeCloseTo(0.25)
+    expect(result.current.label).toBe('0:30')
+  })
+
+  it('reports progress 0 and never done without a duration', () => {
+    const { result } = renderHook(() => useTimer({ mode: 'up', elapsedMs: 45000 }))
+    expect(result.current.progress).toBe(0)
+    expect(result.current.done).toBe(false)
+    expect(result.current.label).toBe('0:45')
+  })
+})
+
+describe('useTimer (self-ticking)', () => {
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('advances elapsed on each interval while running', () => {
+    vi.useFakeTimers()
+    const { result } = renderHook(() =>
+      useTimer({ mode: 'up', autoTick: true, running: true, tickMs: 1000 })
+    )
+    expect(result.current.elapsedMs).toBe(0)
+    act(() => {
+      vi.advanceTimersByTime(3000)
+    })
+    expect(result.current.elapsedMs).toBe(3000)
+  })
+
+  it('counts a down-timer toward 0 and reports done', () => {
+    vi.useFakeTimers()
+    const { result } = renderHook(() =>
+      useTimer({ mode: 'down', durationMs: 3000, autoTick: true, running: true })
+    )
+    expect(result.current.label).toBe('0:03')
+    act(() => {
+      vi.advanceTimersByTime(3000)
+    })
+    expect(result.current.remainingMs).toBe(0)
+    expect(result.current.label).toBe('0:00')
+    expect(result.current.done).toBe(true)
+  })
+
+  it('does not tick when not running', () => {
+    vi.useFakeTimers()
+    const { result } = renderHook(() => useTimer({ mode: 'up', autoTick: true, running: false }))
+    act(() => {
+      vi.advanceTimersByTime(5000)
+    })
+    expect(result.current.elapsedMs).toBe(0)
+  })
+
+  it('does not tick when a controlled elapsedMs is supplied', () => {
+    vi.useFakeTimers()
+    const { result } = renderHook(() =>
+      useTimer({ mode: 'up', autoTick: true, running: true, elapsedMs: 10000 })
+    )
+    act(() => {
+      vi.advanceTimersByTime(5000)
+    })
+    expect(result.current.elapsedMs).toBe(10000)
+  })
+
+  it('clears the interval on unmount', () => {
+    vi.useFakeTimers()
+    const clearSpy = vi.spyOn(global, 'clearInterval')
+    const { unmount } = renderHook(() => useTimer({ mode: 'up', autoTick: true, running: true }))
+    unmount()
+    expect(clearSpy).toHaveBeenCalled()
+    clearSpy.mockRestore()
+  })
+
+  it('stops ticking after running flips to false', () => {
+    vi.useFakeTimers()
+    const { result, rerender } = renderHook(
+      ({ running }) => useTimer({ mode: 'up', autoTick: true, running }),
+      { initialProps: { running: true } }
+    )
+    act(() => {
+      vi.advanceTimersByTime(2000)
+    })
+    expect(result.current.elapsedMs).toBe(2000)
+    rerender({ running: false })
+    act(() => {
+      vi.advanceTimersByTime(5000)
+    })
+    expect(result.current.elapsedMs).toBe(2000)
+  })
+})

package/src/hooks/useTimer.ts

@@ -0,0 +1,77 @@
+import { useEffect, useState } from 'react'
+
+export type TimerMode = 'up' | 'down'
+
+export interface UseTimerOptions {
+  /** 'up' counts elapsed upward; 'down' counts remaining toward 0. Default 'up'. */
+  mode?: TimerMode
+  /** Total duration in ms. Required for 'down' mode and for progress in 'up' mode. */
+  durationMs?: number
+  /** Controlled elapsed time in ms. When provided, the hook derives everything from it and never ticks. */
+  elapsedMs?: number
+  /** Self-tick only advances while running. */
+  running?: boolean
+  /** Enable the internal interval. Ignored when `elapsedMs` is controlled. */
+  autoTick?: boolean
+  /** Interval step in ms. Default 1000. */
+  tickMs?: number
+}
+
+export interface TimerState {
+  elapsedMs: number
+  remainingMs: number
+  /** 0..1, clamped. */
+  progress: number
+  /** mm:ss for the active direction (remaining when 'down', elapsed when 'up'). */
+  label: string
+  /** True once a down-timer reaches 0 (or an up-timer passes its duration). */
+  done: boolean
+}
+
+/** Format a millisecond duration as mm:ss, rounding partial seconds up. */
+export function formatDuration(ms: number): string {
+  const totalSeconds = Math.max(0, Math.ceil(ms / 1000))
+  const minutes = Math.floor(totalSeconds / 60)
+  const seconds = totalSeconds % 60
+  return `${minutes}:${String(seconds).padStart(2, '0')}`
+}
+
+export function useTimer(options: UseTimerOptions = {}): TimerState {
+  const {
+    mode = 'up',
+    durationMs,
+    elapsedMs: controlledElapsedMs,
+    running = false,
+    autoTick = false,
+    tickMs = 1000,
+  } = options
+
+  const isControlled = controlledElapsedMs != null
+  const [internalElapsedMs, setInternalElapsedMs] = useState(0)
+
+  useEffect(() => {
+    if (isControlled || !autoTick || !running) return
+    const id = setInterval(() => {
+      setInternalElapsedMs((prev) => prev + tickMs)
+    }, tickMs)
+    return () => clearInterval(id)
+  }, [isControlled, autoTick, running, tickMs])
+
+  const elapsedMs = isControlled ? controlledElapsedMs : internalElapsedMs
+
+  const hasDuration = durationMs != null && durationMs > 0
+  const remainingMs = durationMs != null ? Math.max(0, durationMs - elapsedMs) : 0
+
+  let progress: number
+  if (hasDuration) {
+    progress = Math.min(1, Math.max(0, elapsedMs / durationMs))
+  } else {
+    // A zero/undefined duration is trivially complete for a countdown, empty for a stopwatch.
+    progress = mode === 'down' ? 1 : 0
+  }
+
+  const label = formatDuration(mode === 'down' ? remainingMs : elapsedMs)
+  const done = durationMs != null && elapsedMs >= durationMs
+
+  return { elapsedMs, remainingMs, progress, label, done }
+}

package/src/index.ts

@@ -9,3 +9,6 @@ export * from './theme/barrel'
 
 // Utilities
 export * from './utils'
+
+// Hooks
+export * from './hooks'

package/src/pages.ts

@@ -15,7 +15,7 @@ export {
   countCompletedSets,
   deriveWorkoutProgress,
   findActiveExercise,
-  statusToCardState,
+  isUpcomingExercise,
   toActiveCardProps,
   groupExercises,
   type ActiveWorkoutPageProps,

package/src/stories/PresetShowcase.stories.tsx

@@ -438,7 +438,7 @@ function Section({ title, children }: { title: string; children: React.ReactNode
 // ---------------------------------------------------------------------------
 
 const meta: Meta = {
-  title: 'Theme/Preset Showcase',
+  title: 'Lab/Recipes/Theme Preset Showcase',
   parameters: {
     layout: 'fullscreen',
   },

package/src/stories/ThemePresets.stories.tsx

@@ -66,7 +66,7 @@ function PresetShowcase({ preset }: { preset: typeof audiobookPreset }) {
 }
 
 const meta: Meta = {
-  title: 'Theme/Presets',
+  title: 'Foundations/Theme Presets',
   parameters: {
     layout: 'fullscreen',
   },

package/src/theme/ColorSystem.stories.tsx

@@ -13,7 +13,7 @@ import {
 } from './tokens/primitives'
 
 const meta: Meta = {
-  title: 'Design Tokens/Color System',
+  title: 'Foundations/Color/System',
   tags: ['autodocs'],
 }
 export default meta

package/src/theme/Colors.stories.tsx

@@ -4,7 +4,7 @@ import { primitiveColors, discreteRainbow, primitiveRamps, categoricalPalette }
 import { semanticColorsLight, semanticColorsDark } from './tokens/semantic'
 
 const meta: Meta = {
-  title: 'Design Tokens/Colors',
+  title: 'Foundations/Color/Palette',
   tags: ['autodocs'],
 }
 
@@ -79,16 +79,13 @@ export const PrimitiveColors: StoryObj = {
         Primitive Colors
       </Text>
       <Text className="text-text-secondary mb-6">
-        Raw color values. Use semantic tokens instead when building components.
+        Raw color values. Chromatic hues live as OKLCH tonal ramps (see the Tonal Ramps story);
+        these are the achromatic and support scales. Use semantic tokens when building components.
       </Text>
 
-      <ColorScale name="Orange (Primary Brand)" colors={primitiveColors.accent} />
-      <ColorScale name="Steel (Secondary Brand)" colors={primitiveColors.steel} />
       <ColorScale name="Blue" colors={primitiveColors.blue} />
-      <ColorScale name="Green" colors={primitiveColors.green} />
-      <ColorScale name="Teal (Success)" colors={primitiveColors.teal} />
-      <ColorScale name="Red (Error)" colors={primitiveColors.red} />
-      <ColorScale name="Sky (Info)" colors={primitiveColors.sky} />
+      <ColorScale name="Red" colors={primitiveColors.red} />
+      <ColorScale name="Red Vivid" colors={primitiveColors.redVivid} />
       <ColorScale name="Neutral" colors={primitiveColors.neutral} />
       <ColorScale name="Charcoal (Dark Backgrounds)" colors={primitiveColors.charcoal} />
     </View>

package/src/theme/config.ts

@@ -53,6 +53,8 @@ export const lightThemeCSSVars = {
 
   '--color-status-success': semanticColorsLight['status-success'],
   '--color-status-success-subtle': semanticColorsLight['status-success-subtle'],
+  '--color-status-live': semanticColorsLight['status-live'],
+  '--color-status-live-muted': semanticColorsLight['status-live-muted'],
   '--color-status-error': semanticColorsLight['status-error'],
   '--color-status-error-subtle': semanticColorsLight['status-error-subtle'],
   '--color-status-warning': semanticColorsLight['status-warning'],
@@ -172,6 +174,8 @@ export const darkThemeCSSVars = {
 
   '--color-status-success': semanticColorsDark['status-success'],
   '--color-status-success-subtle': semanticColorsDark['status-success-subtle'],
+  '--color-status-live': semanticColorsDark['status-live'],
+  '--color-status-live-muted': semanticColorsDark['status-live-muted'],
   '--color-status-error': semanticColorsDark['status-error'],
   '--color-status-error-subtle': semanticColorsDark['status-error-subtle'],
   '--color-status-warning': semanticColorsDark['status-warning'],

package/src/theme/elevation.stories.tsx

@@ -21,7 +21,7 @@ import { useTheme } from '../utils/useTheme'
 import { Card, CardContent, CardInset } from '../components/ui/card/Card'
 
 const meta: Meta = {
-  title: 'Theme/Elevation System',
+  title: 'Foundations/Elevation',
   tags: ['autodocs'],
 }
 

package/src/theme/global.css

@@ -35,6 +35,8 @@
     --color-status-success-light: #58F69E;
     --color-status-success-dark: #298732;
     --color-status-success-subtle: rgba(46, 213, 115, 0.12);
+    --color-status-live: #2ED573;
+    --color-status-live-muted: #22A444;
     --color-status-error: #D14343;
     --color-status-error-light: #E05254;
     --color-status-error-dark: #A4221C;
@@ -170,6 +172,8 @@
     --color-status-success-light: #58F69E;
     --color-status-success-dark: #298732;
     --color-status-success-subtle: #E3FFEE;
+    --color-status-live: #2ED573;
+    --color-status-live-muted: #22A444;
     --color-status-error: #D14343;
     --color-status-error-light: #E05254;
     --color-status-error-dark: #A4221C;
@@ -369,7 +373,7 @@
     z-index: 0;
     background:
       radial-gradient(ellipse 140% 100% at 15% 5%, rgba(var(--color-brand-primary-rgb, 255, 121, 0), 0.06) 0%, transparent 45%),
-      radial-gradient(ellipse 120% 80% at 85% 95%, rgba(var(--color-brand-secondary-rgb, 64, 109, 135), 0.04) 0%, transparent 45%);
+      radial-gradient(ellipse 120% 80% at 85% 95%, rgba(var(--color-brand-secondary-rgb, 48, 123, 155), 0.04) 0%, transparent 45%);
   }
 
   /* Film grain overlay for vintage texture */

package/src/theme/shadows.stories.tsx

@@ -8,7 +8,7 @@ import {
 } from './shadows'
 
 const meta: Meta = {
-  title: 'Theme/Shadows',
+  title: 'Foundations/Shadows',
 }
 
 export default meta

package/src/theme/tokens/primitives.ts

@@ -6,7 +6,7 @@
  */
 
 export const primitiveColors = {
-  // Blue scale (primary brand)
+  // Blue scale
   blue: {
     50: '#EFF6FF',
     100: '#DBEAFE',
@@ -14,110 +14,40 @@ export const primitiveColors = {
     300: '#93C5FD',
     400: '#60A5FA',
     500: '#3B82F6',
-    600: '#5048E5', // Primary main
-    700: '#3832A0', // Primary dark
+    600: '#5048E5',
+    700: '#3832A0',
     800: '#1E40AF',
     900: '#1E3A8A',
   },
 
-  // Green scale (secondary brand)
-  green: {
-    50: '#ECFDF5',
-    100: '#D1FAE5',
-    200: '#A7F3D0',
-    300: '#6EE7B7',
-    400: '#3FC79A', // Secondary light
-    500: '#10B981', // Secondary main
-    600: '#059669',
-    700: '#0B815A', // Secondary dark
-    800: '#065F46',
-    900: '#064E3B',
-  },
-
-  // Teal scale (success)
-  teal: {
-    50: '#F0FDFA',
-    100: '#CCFBF1',
-    200: '#99F6E4',
-    300: '#5EEAD4',
-    400: '#43C6B7', // Success light
-    500: '#14B8A6', // Success main
-    600: '#0D9488',
-    700: '#0E8074', // Success dark
-    800: '#115E59',
-    900: '#134E4A',
-  },
-
-  // Red scale (error)
+  // Red scale
   red: {
     50: '#FEF2F2',
     100: '#FEE2E2',
     200: '#FECACA',
     300: '#FCA5A5',
-    400: '#DA6868', // Error light
+    400: '#DA6868',
     500: '#EF4444',
-    600: '#D14343', // Error main
-    700: '#922E2E', // Error dark
+    600: '#D14343',
+    700: '#922E2E',
     800: '#991B1B',
     900: '#7F1D1D',
   },
 
-  // Vivid green scale (live/go success)
-  greenVivid: {
-    50: '#E9FBF0',
-    100: '#C8F7DA',
-    200: '#9FF0BF',
-    300: '#6BE79D',
-    400: '#47DE84', // Success vivid light
-    500: '#2ED573', // Success vivid main
-    600: '#22B85F',
-    700: '#1A9950', // Success vivid dark
-    800: '#157A40',
-    900: '#105C30',
-  },
-
-  // Vivid red scale (alert)
+  // Vivid red scale
   redVivid: {
     50: '#FFECEE',
     100: '#FFD6DB',
     200: '#FFB3BC',
     300: '#FF8593',
-    400: '#FF6070', // Error vivid light
-    500: '#FF4757', // Error vivid main
+    400: '#FF6070',
+    500: '#FF4757',
     600: '#E63548',
-    700: '#C42539', // Error vivid dark
+    700: '#C42539',
     800: '#9E1C2C',
     900: '#7A1520',
   },
 
-  // Amber scale (warning)
-  amber: {
-    50: '#FFFBEB',
-    100: '#FEF3C7',
-    200: '#FDE68A',
-    300: '#FCD34D',
-    400: '#FFBF4C', // Warning light
-    500: '#FFB020', // Warning main
-    600: '#B27B16', // Warning dark
-    700: '#B45309',
-    800: '#92400E',
-    900: '#78350F',
-  },
-
-  // Sky/Blue scale (info)
-  sky: {
-    50: '#F0F9FF',
-    100: '#E0F2FE',
-    200: '#BAE6FD',
-    300: '#7DD3FC',
-    400: '#64B6F7', // Info light
-    500: '#2196F3', // Info main
-    600: '#0284C7',
-    700: '#0B79D0', // Info dark
-    800: '#075985',
-    900: '#0C4A6E',
-  },
-
   // Neutral/Gray scale
   neutral: {
     50: '#FAFAFA',
@@ -133,19 +63,6 @@ export const primitiveColors = {
     950: '#030712',
   },
 
-  // Orange scale (accent/brand color)
-  accent: {
-    100: '#FFA860',
-    200: '#FF9630',
-    300: '#FF8500',
-    400: '#FF7900',
-    500: '#F56C00',
-    600: '#E06D10',
-    700: '#D0620C',
-    800: '#B75500',
-    900: '#A34900',
-  },
-
   // Charcoal scale (dark backgrounds)
   charcoal: {
     0: '#6E6E6E',
@@ -161,19 +78,6 @@ export const primitiveColors = {
     900: '#101010',
   },
 
-  // Steel scale (cool accent)
-  steel: {
-    100: '#8AA4B8',
-    200: '#7894A8',
-    300: '#678498',
-    400: '#557488',
-    500: '#406D87',
-    600: '#39617A',
-    700: '#32556D',
-    800: '#243D53',
-    900: '#1D3146',
-  },
-
   // Pure colors
   white: '#FFFFFF',
   black: '#000000',

package/src/theme/tokens/semantic.ts

@@ -46,6 +46,10 @@ export const semanticColorsLight = {
   'status-success-dark': ramp.green[600],
   'status-success-subtle': ramp.green[50],
 
+  // Live-session accent — its OWN role, decoupled from success so the two can diverge
+  'status-live': ramp.green[300],
+  'status-live-muted': ramp.green[500],
+
   'status-error': ramp.red[600],
   'status-error-light': ramp.red[500],
   'status-error-dark': ramp.red[700],
@@ -176,6 +180,10 @@ export const semanticColorsDark = {
   'status-success-dark': ramp.green[600],
   'status-success-subtle': 'rgba(46, 213, 115, 0.12)',
 
+  // Live-session accent — its OWN role, decoupled from success so the two can diverge
+  'status-live': ramp.green[300],
+  'status-live-muted': ramp.green[500],
+
   'status-error': ramp.red[600],
   'status-error-light': ramp.red[500],
   'status-error-dark': ramp.red[700],

package/src/theme/workout-tokens.ts

@@ -8,14 +8,18 @@ export const WORKOUT_TOKENS = {
   // Canonical 4-band performance scale — the single source for BOTH the
   // VelocityStrip zone bars and the SetRow RPE color (TD-03.43). The direction
   // is intentionally inverted between the two consumers: for velocity, green =
-  // fastest/best; for RPE, green = easiest. This is the [0,1,2,4] subsample of
-  // the canonical `sequentialEffort` primitive. The `orange` key is the band
-  // label. Consumed inline (RN).
+  // fastest/best; for RPE, green = easiest. This is the [0,2,3,4] subsample of
+  // the canonical `sequentialEffort` primitive: an EVEN hue walk across the ramp
+  // (green → gold → orange → red). The earlier [0,1,2,4] spent two of its four
+  // bands on adjacent yellows (amber-200 + amber-300) and skipped orange, reading
+  // yellow-heavy with an abrupt jump to red; sampling amber-300 + orange-400
+  // instead gives four cleanly separable bands that hold at 3px strip scale.
+  // Consumed inline (RN).
   scale: {
-    green: sequentialEffort[0],
-    yellow: sequentialEffort[1],
-    orange: sequentialEffort[2], // gold band
-    red: sequentialEffort[4],
+    green: sequentialEffort[0], // green-300
+    yellow: sequentialEffort[2], // amber-300 (gold)
+    orange: sequentialEffort[3], // orange-400 (true orange)
+    red: sequentialEffort[4], // red-600
   },
 
   // BodyMap volume heatmap — the canonical `divergingScale` (under → optimal →

package/tailwind.config.js

@@ -38,6 +38,11 @@ module.exports = {
             dark: 'var(--color-status-success-dark)',
             subtle: 'var(--color-status-success-subtle)',
           },
+          // Live-session accent — own role, decoupled from success
+          live: {
+            DEFAULT: 'var(--color-status-live)',
+            muted: 'var(--color-status-live-muted)',
+          },
           error: {
             DEFAULT: 'var(--color-status-error)',
             light: 'var(--color-status-error-light)',