@titan-design/react-ui 0.3.0 → 0.5.0

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

@@ -8,13 +8,28 @@ export { WeightBadge, type WeightBadgeProps, type WeightBadgeSize } from './Weig
 export { PrBadge, type PrBadgeProps, type PRType } from './PrBadge'
 export { StatusDot, type StatusDotVariant, type StatusDotProps } from './StatusDot'
 export { PlaceholderStrip, type PlaceholderStripProps } from './PlaceholderStrip'
-export { TempoDisplay, type TempoDisplayProps } from './TempoDisplay'
+export {
+  TempoDisplay,
+  type TempoDisplayProps,
+  type TempoLivePhase,
+  type TempoLiveState,
+} from './TempoDisplay'
+export {
+  TempoBar,
+  type TempoBarProps,
+  type TempoPhaseKey,
+  type TempoPacingState,
+  TEMPO_PACING,
+  getTempoPacingState,
+  getTempoFillPct,
+} from './TempoBar'
 export { DeviationBar, type DeviationBarProps } from './DeviationBar'
 export { IntensityBar, type IntensityBarProps } from './IntensityBar'
 export { WorkoutPill, type WorkoutPillProps, type WorkoutPillStatus } from './WorkoutPill'
 export {
   VelocityStrip,
   type VelocityStripProps,
+  type VelocityZoneBandProp,
   getVelocityZoneColor,
   getVelocityZoneName,
   calculateVelocityLoss,
@@ -94,37 +109,29 @@ export type {
   TrainingStatusMuscle,
   TrainingStatusSummary,
 } from './TrainingStatusPage'
-export {
-  ProgramPlanningPage,
-  deriveNavLevel,
-  toProgressBarMesos,
-  findMeso,
-  findWeek,
-  findWorkout,
-  buildBreadcrumbs,
-  type ProgramPlanningPageProps,
-  type PlanMeso,
-  type PlanWeek,
-  type PlanWorkout,
-  type ProgramNavLevel,
-  type ProgramSelection,
-  type ProgramBreadcrumb,
+// ActiveWorkoutPage / ExerciseDetailPage / ProgramPlanningPage are page-level
+// organisms demoted to the `@titan-design/react-ui/pages` subpath (titan 0.5.0).
+// Their VALUE exports (components + derivation helpers) live there; only
+// type-only re-exports stay on this barrel (erased at build, no runtime pull).
+export type {
+  ProgramPlanningPageProps,
+  PlanMeso,
+  PlanWeek,
+  PlanWorkout,
+  ProgramNavLevel,
+  ProgramSelection,
+  ProgramBreadcrumb,
 } from './ProgramPlanningPage'
-export {
-  ExerciseDetailPage,
-  deriveExerciseStats,
-  toExerciseCardProps,
-  summarizeVbt,
-  EXERCISE_DETAIL_TABS,
-  type ExerciseDetailPageProps,
-  type ExerciseDetailTab,
-  type ExerciseDetailHeader,
-  type ExerciseDetailEntry,
-  type ExerciseTrend,
-  type ExerciseVbtSet,
-  type ExerciseVbt,
-  type ExerciseDetailStats,
-  type VbtSummary,
+export type {
+  ExerciseDetailPageProps,
+  ExerciseDetailTab,
+  ExerciseDetailHeader,
+  ExerciseDetailEntry,
+  ExerciseTrend,
+  ExerciseVbtSet,
+  ExerciseVbt,
+  ExerciseDetailStats,
+  VbtSummary,
 } from './ExerciseDetailPage'
 // muscleTaxonomy imports `react-native-body-highlighter` at runtime. Its value
 // exports (incl. the MuscleGroup / SimpleMuscleGroup enums) live behind the
@@ -135,20 +142,13 @@ export type {
   MovementCategory,
   VolumeLandmarks,
 } from './muscleTaxonomy'
-export {
-  ActiveWorkoutPage,
-  countCompletedSets,
-  deriveWorkoutProgress,
-  findActiveExercise,
-  statusToCardState,
-  toActiveCardProps,
-  groupExercises,
-  type ActiveWorkoutPageProps,
-  type ActiveWorkoutExercise,
-  type ActiveWorkoutSuperset,
-  type ActiveWorkoutInput,
-  type ActiveWorkoutRest,
-  type ActiveExerciseStatus,
-  type WorkoutProgress,
-  type WorkoutGroup,
+export type {
+  ActiveWorkoutPageProps,
+  ActiveWorkoutExercise,
+  ActiveWorkoutSuperset,
+  ActiveWorkoutInput,
+  ActiveWorkoutRest,
+  ActiveExerciseStatus,
+  WorkoutProgress,
+  WorkoutGroup,
 } from './ActiveWorkoutPage'

package/src/index.ts

@@ -3,8 +3,9 @@
 // Components
 export * from './components'
 
-// Theme
-export * from './theme'
+// Theme (nativewind-free surface; ThemeProvider value lives on the /theme
+// subpath so the root barrel does not pull the nativewind import chain)
+export * from './theme/barrel'
 
 // Utilities
 export * from './utils'

package/src/pages.ts

@@ -0,0 +1,61 @@
+// Subpath entry: @titan-design/react-ui/pages
+//
+// Page-level organisms — phone-shaped reference screens (ActiveWorkoutPage,
+// ExerciseDetailPage, ProgramPlanningPage). Demoted out of the root barrel for
+// titan 0.5.0: they are full app screens, orphaned by both consumers, and their
+// successors are the form-factor-responsive level views (plan B2). Their VALUE
+// exports (components + derivation helpers) live HERE; type-only re-exports
+// stay on the root barrel so consumers can still type props without importing
+// the screens. Mirrors the `/bodymap` isolation pattern.
+//
+// TrainingStatusPage is NOT here — it depends on react-native-body-highlighter
+// and lives under `@titan-design/react-ui/bodymap`.
+export {
+  ActiveWorkoutPage,
+  countCompletedSets,
+  deriveWorkoutProgress,
+  findActiveExercise,
+  statusToCardState,
+  toActiveCardProps,
+  groupExercises,
+  type ActiveWorkoutPageProps,
+  type ActiveWorkoutExercise,
+  type ActiveWorkoutSuperset,
+  type ActiveWorkoutInput,
+  type ActiveWorkoutRest,
+  type ActiveExerciseStatus,
+  type WorkoutProgress,
+  type WorkoutGroup,
+} from './components/custom/Workout/ActiveWorkoutPage'
+export {
+  ExerciseDetailPage,
+  deriveExerciseStats,
+  toExerciseCardProps,
+  summarizeVbt,
+  EXERCISE_DETAIL_TABS,
+  type ExerciseDetailPageProps,
+  type ExerciseDetailTab,
+  type ExerciseDetailHeader,
+  type ExerciseDetailEntry,
+  type ExerciseTrend,
+  type ExerciseVbtSet,
+  type ExerciseVbt,
+  type ExerciseDetailStats,
+  type VbtSummary,
+} from './components/custom/Workout/ExerciseDetailPage'
+export {
+  ProgramPlanningPage,
+  deriveNavLevel,
+  toProgressBarMesos,
+  findMeso,
+  findWeek,
+  findWorkout,
+  buildBreadcrumbs,
+  type ProgramPlanningPageProps,
+  type PlanMeso,
+  type PlanWeek,
+  type PlanWorkout,
+  type ProgramNavLevel,
+  type ProgramSelection,
+  type ProgramBreadcrumb,
+} from './components/custom/Workout/ProgramPlanningPage'

package/src/test/nativewind-stub.ts

@@ -0,0 +1,13 @@
+// Web test stub for `nativewind`.
+//
+// The real `nativewind` pulls react-native-css-interop → RN's Flow-typed
+// sources, which the jsdom/react-native-web test environment can't parse
+// ("Unexpected token 'typeof'"). Only `ThemeProvider` imports nativewind (for
+// `vars()`), and only for its NATIVE behavior — on web the color tokens resolve
+// from `global.css`, so an identity `vars()` is a faithful web stand-in.
+// Aliased in `vitest.config.ts`; the real package is used at build/native.
+
+/** Identity stand-in for nativewind's `vars()` — returns the token map as-is. */
+export function vars(values: Record<string, string>): Record<string, string> {
+  return values
+}

package/src/test/stories-smoke.test.tsx

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest'
+import { render } from '@testing-library/react'
+import { composeStories } from '@storybook/react'
+
+/**
+ * Storybook → render-test bridge (TD-04.11 / VW-20).
+ *
+ * The design system has a complete `*.stories.tsx` set but no test consumed it.
+ * This uses Storybook's portable-stories `composeStories` to mount EVERY story
+ * (with its args/decorators applied) through the same react-native-web + jsdom
+ * pipeline the unit tests use, asserting each renders without throwing and emits
+ * output. It's broad, near-free coverage that catches "this organism/variant
+ * crashes on render" regressions across the whole component set — the long tail
+ * the hand-written per-organism tests don't enumerate.
+ *
+ * Project annotations (the preview's theme decorator) are intentionally NOT
+ * applied: a smoke test only needs to prove each story renders, and skipping
+ * them avoids importing global.css / addon-themes into the test env.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type StoryModule = Record<string, any>
+
+const storyModules = import.meta.glob<StoryModule>('../components/**/*.stories.tsx', {
+  eager: true,
+})
+
+describe('storybook stories render (composeStories smoke)', () => {
+  const entries = Object.entries(storyModules)
+
+  it('discovers a non-trivial number of story modules', () => {
+    expect(entries.length).toBeGreaterThan(10)
+  })
+
+  for (const [file, mod] of entries) {
+    const label = file.replace('../components/', '')
+    const composed = composeStories(mod)
+    for (const [name, Story] of Object.entries(composed)) {
+      it(`${label} › ${name} renders`, () => {
+        // Smoke level: every story must MOUNT without throwing. `firstChild` is
+        // not asserted — portal/modal organisms (PrHistoryModal) render into
+        // document.body, and empty-state stories legitimately render null; the
+        // hand-written per-organism tests own the detailed output assertions.
+        const result = render(<Story />)
+        expect(result.unmount).toBeTypeOf('function')
+        result.unmount()
+      })
+    }
+  }
+})

package/src/theme/ThemeProvider.test.tsx

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { Text } from 'react-native'
+import { ThemeProvider } from './ThemeProvider'
+
+describe('ThemeProvider', () => {
+  it('renders its children', () => {
+    render(
+      <ThemeProvider>
+        <Text>inside</Text>
+      </ThemeProvider>,
+    )
+    expect(screen.getByText('inside')).toBeInTheDocument()
+  })
+
+  it('accepts a light mode without error', () => {
+    render(
+      <ThemeProvider mode="light">
+        <Text>light</Text>
+      </ThemeProvider>,
+    )
+    expect(screen.getByText('light')).toBeInTheDocument()
+  })
+})

package/src/theme/ThemeProvider.tsx

@@ -0,0 +1,50 @@
+// Cross-platform theme provider (TD native-theming).
+//
+// Registers titan's semantic color tokens as runtime CSS variables via
+// nativewind's `vars()` so that className color tokens (`text-text-secondary`,
+// `bg-surface-raised`, `border-border`, …) resolve on NATIVE React Native — the
+// native equivalent of the `:root {}` block `global.css` provides on web.
+//
+// Why this exists: titan's Workout organisms reference semantic colors as CSS
+// variables. On web (the dashboard, react-native-web) those come from
+// `global.css`. On native (the mobile app) nothing defined them, so any titan
+// component using a `--color-*` token rendered with an unresolved (black) color.
+// Wrap the mobile app root in `<ThemeProvider>` and the tokens resolve on-device.
+//
+// The var maps are the SAME canonical `darkThemeCSSVars` / `lightThemeCSSVars`
+// that generate `global.css`, so native and web resolve to identical values.
+import { vars } from 'nativewind'
+import { View, type ViewProps } from 'react-native'
+import { darkThemeCSSVars, lightThemeCSSVars } from './config'
+
+export type ThemeProviderMode = 'dark' | 'light'
+
+// Precomputed once — `vars()` is pure, so the same style object is reused across
+// renders. Native == web because these are the maps `tokens-css` emits.
+const MODE_VARS = {
+  dark: vars(darkThemeCSSVars),
+  light: vars(lightThemeCSSVars),
+}
+
+export interface ThemeProviderProps extends ViewProps {
+  /** Theme mode to register. Mobile is dark-only today; defaults to `dark`. */
+  mode?: ThemeProviderMode
+}
+
+/**
+ * Wrap the app root so descendant titan components' `--color-*` className tokens
+ * resolve on native. Fills its parent (`flex: 1`) by default; pass `style` to
+ * override. On web it is harmless (the dashboard already loads `global.css`).
+ */
+export function ThemeProvider({
+  mode = 'dark',
+  style,
+  children,
+  ...props
+}: ThemeProviderProps): React.JSX.Element {
+  return (
+    <View style={[MODE_VARS[mode], { flex: 1 }, style]} {...props}>
+      {children}
+    </View>
+  )
+}

package/src/theme/barrel.ts

@@ -0,0 +1,53 @@
+// Theme surface WITHOUT the ThemeProvider value (dep hygiene, titan 0.5.0).
+//
+// `ThemeProvider` imports `nativewind` (`vars()`). Re-exporting it from the root
+// barrel dragged the whole nativewind import chain into every consumer of
+// `@titan-design/react-ui` — the web SPA paid for a native-only provider. This
+// file is the nativewind-free theme surface: the root barrel re-exports THIS,
+// and the `/theme` subpath (`./index.ts`) layers the `ThemeProvider` value on
+// top for the native consumers that deliberately import it.
+export * from './tokens'
+export * from './config'
+export * from './shadows'
+export * from './elevation'
+export * from './manifest'
+export { resolveColor } from './resolve-color'
+
+// ThemeProvider TYPES may stay on the root (erased at build — no nativewind
+// pull). Only the ThemeProvider VALUE moves to the `/theme` subpath.
+export type { ThemeProviderProps, ThemeProviderMode } from './ThemeProvider'
+
+// Re-export commonly used items
+export { getSemanticColors, type ThemeMode } from './tokens/semantic'
+export { getThemeCSSVars, gluestackConfig } from './config'
+export {
+  neumorphicShadows,
+  // Color math utilities (HSV-based)
+  lighten,
+  darken,
+  getHoverColors,
+  isDark,
+  hexToRgb,
+  rgbToHsv,
+  // Shadow creation functions
+  createRaisedShadow,
+  createRaisedHoverShadow,
+  createPressedShadow,
+  createPressedHoverShadow,
+  createFlatShadow,
+  shadowColors,
+  type ShadowIntensity,
+  type ShadowSurface,
+} from './shadows'
+export {
+  getElevationConfig,
+  getElevationSurface,
+  getElevationShadow,
+  getBaseSurfaceColor,
+  getValidatedElevation,
+  componentElevationRanges,
+  type ElevationLevel,
+  type ElevationConfig,
+  type ComponentType,
+} from './elevation'
+export * from './presets'

package/src/theme/index.ts

@@ -1,41 +1,8 @@
-// Theme exports
-export * from './tokens'
-export * from './config'
-export * from './shadows'
-export * from './elevation'
-export * from './manifest'
-
-// Re-export commonly used items
-export { getSemanticColors, type ThemeMode } from './tokens/semantic'
-export { getThemeCSSVars, gluestackConfig } from './config'
-export {
-  neumorphicShadows,
-  // Color math utilities (HSV-based)
-  lighten,
-  darken,
-  getHoverColors,
-  isDark,
-  hexToRgb,
-  rgbToHsv,
-  // Shadow creation functions
-  createRaisedShadow,
-  createRaisedHoverShadow,
-  createPressedShadow,
-  createPressedHoverShadow,
-  createFlatShadow,
-  shadowColors,
-  type ShadowIntensity,
-  type ShadowSurface,
-} from './shadows'
-export {
-  getElevationConfig,
-  getElevationSurface,
-  getElevationShadow,
-  getBaseSurfaceColor,
-  getValidatedElevation,
-  componentElevationRanges,
-  type ElevationLevel,
-  type ElevationConfig,
-  type ComponentType,
-} from './elevation'
-export * from './presets'
+// Theme subpath entry: @titan-design/react-ui/theme
+//
+// The full theme surface. This is the nativewind-free `./barrel` PLUS the
+// `ThemeProvider` value — which imports `nativewind` and therefore does NOT
+// belong on the root barrel (that split happened in titan 0.5.0). Native
+// consumers wrap their app root in `<ThemeProvider>` and import it from HERE.
+export * from './barrel'
+export { ThemeProvider } from './ThemeProvider'

package/src/theme/native-theming-guard.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect } from 'vitest'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { darkThemeCSSVars, lightThemeCSSVars } from './config'
+import { getSemanticColors } from './tokens/semantic'
+
+/**
+ * Native-theming guard (TD-04.11 / VW-20).
+ *
+ * On native, titan resolves colors two ways, and BOTH can silently render black
+ * if a token is undefined:
+ *   1. `className` (e.g. `text-text-secondary`) → tailwind config → a
+ *      `var(--color-*)` custom property that `ThemeProvider` registers at runtime
+ *      via nativewind `vars(darkThemeCSSVars)`. A tailwind color pointing at a var
+ *      the theme maps don't define is unset on native → black text/fill.
+ *   2. `resolveColor(token)` → `getSemanticColors(mode)[token]` hex on native /
+ *      `var(--color-${token})` on web. A token missing a hex value, or whose
+ *      `--color-<token>` var is undefined, renders black (native) or unset (web).
+ *
+ * This is the exact class of bug that shipped in the 09.33a swap and was only
+ * caught on-device. `config.completeness.test.ts` proves the theme maps mirror
+ * global.css (the definition side); this guard covers the USAGE side — every
+ * color token the design system references must resolve to a defined token in
+ * both modes. Static (no render), so it runs in the fast project.
+ */
+
+const require = createRequire(import.meta.url)
+const uiRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const tailwindConfig = require(path.join(uiRoot, 'tailwind.config.js')) as any
+const colorTree = tailwindConfig.theme?.extend?.colors ?? {}
+
+// Flatten the nested tailwind color tree into `class-suffix -> leaf value`.
+// `DEFAULT` collapses onto its parent (tailwind's `brand.primary.DEFAULT` -> the
+// `brand-primary` class).
+function flattenColors(
+  node: Record<string, unknown>,
+  prefix: string[] = [],
+): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [key, value] of Object.entries(node)) {
+    const nextPrefix = key === 'DEFAULT' ? prefix : [...prefix, key]
+    if (value && typeof value === 'object') {
+      Object.assign(out, flattenColors(value as Record<string, unknown>, nextPrefix))
+    } else if (typeof value === 'string') {
+      out[nextPrefix.join('-')] = value
+    }
+  }
+  return out
+}
+
+const colorLeaves = flattenColors(colorTree)
+const definedDark = new Set(Object.keys(darkThemeCSSVars))
+const definedLight = new Set(Object.keys(lightThemeCSSVars))
+
+function varReference(value: string): string | null {
+  const match = value.match(/var\((--color-[a-z0-9-]+)\)/)
+  return match ? match[1] : null
+}
+
+// Accept hex, rgb/rgba, and hsl/hsla; reject empty/undefined. (No token should be
+// literally "#000"/"black" in these maps, but that's a design choice, not a
+// resolution bug, so we only assert a *valid, present* color here.)
+const VALID_COLOR = /^(#[0-9a-f]{3,8}|rgba?\([^)]+\)|hsla?\([^)]+\))$/i
+
+describe('native theming guard (no color token renders black on native)', () => {
+  it('sanity: tailwind colors and theme maps flattened to non-trivial sets', () => {
+    expect(Object.keys(colorLeaves).length).toBeGreaterThan(50)
+    expect(definedDark.size).toBeGreaterThan(90)
+    expect(definedLight.size).toBe(definedDark.size)
+  })
+
+  it('every tailwind color className resolves to a var defined in BOTH native vars maps', () => {
+    const undefinedDark: string[] = []
+    const undefinedLight: string[] = []
+    for (const [suffix, value] of Object.entries(colorLeaves)) {
+      const ref = varReference(value)
+      if (!ref) continue // literal color (nativewind preset default) — always resolves
+      if (!definedDark.has(ref)) undefinedDark.push(`${suffix} -> ${value}`)
+      if (!definedLight.has(ref)) undefinedLight.push(`${suffix} -> ${value}`)
+    }
+    expect(
+      undefinedDark,
+      'tailwind colors point at vars missing from darkThemeCSSVars (className renders black on native dark)',
+    ).toEqual([])
+    expect(
+      undefinedLight,
+      'tailwind colors point at vars missing from lightThemeCSSVars (className renders black on native light)',
+    ).toEqual([])
+  })
+
+  it('every resolveColor/getSemanticColors token has a valid hex AND a matching --color-<token> var', () => {
+    for (const mode of ['dark', 'light'] as const) {
+      const colors = getSemanticColors(mode)
+      const defined = mode === 'dark' ? definedDark : definedLight
+      const invalidValues: string[] = []
+      const missingVars: string[] = []
+      for (const [token, value] of Object.entries(colors)) {
+        if (typeof value !== 'string' || !VALID_COLOR.test(value)) {
+          invalidValues.push(`${token} = ${JSON.stringify(value)}`)
+        }
+        // resolveColor's web path returns `var(--color-${token})`; that var must exist.
+        if (!defined.has(`--color-${token}`)) missingVars.push(token)
+      }
+      expect(
+        invalidValues,
+        `getSemanticColors('${mode}') has tokens with no valid color (renders black/unset on native)`,
+      ).toEqual([])
+      expect(
+        missingVars,
+        `resolveColor tokens missing a --color-<token> in ${mode} vars (renders unset on web)`,
+      ).toEqual([])
+    }
+  })
+})

package/src/theme/resolve-color.ts

@@ -0,0 +1,19 @@
+import { Platform } from 'react-native'
+import { getSemanticColors, type ThemeMode } from './tokens/semantic'
+
+type ColorToken = keyof ReturnType<typeof getSemanticColors>
+
+/**
+ * Resolve a semantic color token for an inline style where a nativewind
+ * className can't apply — gradients (`backgroundImage`), per-edge borders
+ * (`borderTopColor`, …), SVG attributes, and conditional hex/token mixes.
+ *
+ * The companion to className color tokens: on **web** it returns the CSS
+ * variable (`var(--color-…)`), so the dashboard's light/dark switching keeps
+ * working exactly as `global.css` intends; on **native** it returns the
+ * resolved hex from `getSemanticColors` (mobile is dark-only). This is why
+ * these spots stay theme-correct on web while also rendering on-device.
+ */
+export function resolveColor(token: ColorToken, mode: ThemeMode = 'dark'): string {
+  return Platform.OS === 'web' ? `var(--color-${token})` : getSemanticColors(mode)[token]
+}