@titan-design/react-ui 0.2.7 → 0.4.0

package/src/theme/manifest/design-freeze.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect } from 'vitest'
+import {
+  buildFreezeTagName,
+  buildFreezeTagMessage,
+  assertFileCommitted,
+  slugifyVariant,
+  generateSpecimenSkeleton,
+  parseArgs,
+} from '../../../scripts/design-freeze.mjs'
+
+describe('buildFreezeTagName', () => {
+  it('namespaces the tag under design-freeze/ with the component and version', () => {
+    expect(buildFreezeTagName('e1rm-badge', '2026-06-30')).toBe(
+      'design-freeze/e1rm-badge-2026-06-30'
+    )
+  })
+
+  it('throws when component is missing', () => {
+    expect(() => buildFreezeTagName('', '1')).toThrow(/requires a component name/)
+  })
+})
+
+describe('buildFreezeTagMessage', () => {
+  it('records the prototype path and selector the freeze covers', () => {
+    const message = buildFreezeTagMessage({
+      component: 'status-dot',
+      htmlPath: 'docs/prototypes/component-demo.html',
+      selector: '.status-dot',
+    })
+
+    expect(message).toContain('Design freeze: status-dot')
+    expect(message).toContain('docs/prototypes/component-demo.html')
+    expect(message).toContain('.status-dot')
+    expect(message).toContain('re-freeze')
+  })
+})
+
+describe('assertFileCommitted', () => {
+  it('does not throw for a clean porcelain result', () => {
+    expect(() => assertFileCommitted('', 'docs/prototypes/component-demo.html')).not.toThrow()
+    expect(() => assertFileCommitted('   \n', 'docs/prototypes/component-demo.html')).not.toThrow()
+  })
+
+  it('throws with the porcelain output when the file has uncommitted changes', () => {
+    expect(() =>
+      assertFileCommitted(
+        ' M docs/prototypes/component-demo.html\n',
+        'docs/prototypes/component-demo.html'
+      )
+    ).toThrow(/uncommitted changes/)
+  })
+
+  it('throws for an untracked file', () => {
+    expect(() => assertFileCommitted('?? new-prototype.html\n', 'new-prototype.html')).toThrow(
+      /uncommitted changes/
+    )
+  })
+})
+
+describe('slugifyVariant', () => {
+  it('returns an empty string when there are no variant axes', () => {
+    expect(slugifyVariant(undefined)).toBe('')
+    expect(slugifyVariant({})).toBe('')
+  })
+
+  it('joins axis/value pairs with hyphens', () => {
+    expect(slugifyVariant({ size: 'md' })).toBe('size-md')
+    expect(slugifyVariant({ variant: 'solid', size: 'md' })).toBe('variant-solid-size-md')
+  })
+})
+
+describe('generateSpecimenSkeleton', () => {
+  it('embeds the frozen markup and a TODO placeholder for the React side', () => {
+    const skeleton = generateSpecimenSkeleton({
+      component: 'e1rm-badge',
+      htmlSnippet: '<div class="e1rm-badge md">217 lbs</div>',
+    })
+
+    expect(skeleton).toContain('testId="compare-e1rm-badge"')
+    expect(skeleton).toContain('label="e1rm-badge"')
+    expect(skeleton).toContain('<div class="e1rm-badge md">217 lbs</div>')
+    expect(skeleton).toContain('<ComparisonPair')
+    expect(skeleton).toContain('render <e1rm-badge /> here')
+  })
+
+  it('suffixes testId and label with the slugified baseVariant', () => {
+    const skeleton = generateSpecimenSkeleton({
+      component: 'status-dot',
+      htmlSnippet: '<div class="status-dot sm success"></div>',
+      baseVariant: { size: 'sm', variant: 'success' },
+    })
+
+    expect(skeleton).toContain('testId="compare-status-dot-size-sm-variant-success"')
+    expect(skeleton).toContain('label="status-dot size sm variant success"')
+  })
+
+  it('escapes backticks in the markup so the template literal stays valid', () => {
+    const skeleton = generateSpecimenSkeleton({
+      component: 'quote',
+      htmlSnippet: '<div>`backtick`</div>',
+    })
+
+    expect(skeleton).toContain('\\`backtick\\`')
+  })
+
+  it('throws when required fields are missing', () => {
+    expect(() => generateSpecimenSkeleton({ component: '', htmlSnippet: '<div></div>' })).toThrow(
+      /requires a component name/
+    )
+    expect(() => generateSpecimenSkeleton({ component: 'x', htmlSnippet: '' })).toThrow(
+      /requires an htmlSnippet/
+    )
+  })
+})
+
+describe('parseArgs', () => {
+  it('parses positional args and design-freeze-specific flags', () => {
+    const result = parseArgs([
+      'docs/prototypes/component-demo.html',
+      '.e1rm-badge',
+      'e1rm-badge',
+      '--out-manifest',
+      'src/theme/manifest/e1rm-badge.manifest.json',
+      '--out-skeleton',
+      'e1rm-badge.skeleton.tsx',
+      '--tag-version',
+      '2026-06-30',
+      '--variant',
+      'size=md',
+    ])
+
+    expect(result).toMatchObject({
+      htmlPath: 'docs/prototypes/component-demo.html',
+      selector: '.e1rm-badge',
+      component: 'e1rm-badge',
+      outManifest: 'src/theme/manifest/e1rm-badge.manifest.json',
+      outSkeleton: 'e1rm-badge.skeleton.tsx',
+      version: '2026-06-30',
+      baseVariant: { size: 'md' },
+      skipGitTag: false,
+    })
+  })
+
+  it('defaults tag version to an ISO date and recognizes --skip-git-tag', () => {
+    const result = parseArgs([
+      'docs/prototypes/component-demo.html',
+      '.badge',
+      'badge',
+      '--skip-git-tag',
+    ])
+
+    expect(result.skipGitTag).toBe(true)
+    expect(result.version).toMatch(/^\d{4}-\d{2}-\d{2}$/)
+  })
+})

package/src/theme/manifest/extract-css-properties.fixture.html

@@ -0,0 +1,29 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>CSS extraction fixture — button specimen</title>
+  </head>
+  <body>
+    <button
+      data-testid="button"
+      style="
+        background-color: rgb(255, 121, 0);
+        color: rgb(255, 255, 255);
+        border-color: rgba(0, 0, 0, 0);
+        border-style: solid;
+        border-width: 0px;
+        border-radius: 6px;
+        font-family: Inter, sans-serif;
+        font-size: 16px;
+        font-weight: 600;
+        padding-top: 10px;
+        padding-right: 20px;
+        padding-bottom: 10px;
+        padding-left: 20px;
+      "
+    >
+      Start workout
+    </button>
+  </body>
+</html>

package/src/theme/manifest/extract-css-properties.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  DEFAULT_VISUAL_PROPERTIES,
+  buildCssPropertyManifest,
+  readComputedStyleMap,
+  styleMapToProperties,
+  toKebabCase,
+  parseArgs,
+} from '../../../scripts/extract-css-properties.mjs'
+import { validateCssPropertyManifest } from './css-property-manifest.validate'
+
+const loadFixtureBody = (fileName: string): string => {
+  const html = readFileSync(join(__dirname, fileName), 'utf-8')
+  return new DOMParser().parseFromString(html, 'text/html').body.innerHTML
+}
+
+describe('toKebabCase', () => {
+  it('converts camelCase CSS property names to kebab-case', () => {
+    expect(toKebabCase('backgroundColor')).toBe('background-color')
+    expect(toKebabCase('paddingLeft')).toBe('padding-left')
+    expect(toKebabCase('color')).toBe('color')
+  })
+})
+
+describe('styleMapToProperties', () => {
+  it('drops empty computed values and tags each entry with a null token', () => {
+    const properties = styleMapToProperties({
+      backgroundColor: 'rgb(255, 121, 0)',
+      borderRadius: '  6px  ',
+      letterSpacing: '',
+      lineHeight: '   ',
+    })
+
+    expect(properties).toEqual([
+      { property: 'backgroundColor', token: null, resolvedValue: 'rgb(255, 121, 0)' },
+      { property: 'borderRadius', token: null, resolvedValue: '6px' },
+    ])
+  })
+})
+
+describe('buildCssPropertyManifest', () => {
+  it('throws when no property has a non-empty computed value', () => {
+    expect(() =>
+      buildCssPropertyManifest({ component: 'button', styleMap: { color: '' } })
+    ).toThrow(/No non-empty computed CSS properties/)
+  })
+
+  it('includes baseVariant and description only when provided', () => {
+    const manifest = buildCssPropertyManifest({
+      component: 'button',
+      styleMap: { color: 'rgb(255, 255, 255)' },
+      baseVariant: { variant: 'solid' },
+      description: 'from fixture',
+    })
+
+    expect(manifest).toMatchObject({
+      component: 'button',
+      description: 'from fixture',
+      baseVariant: { variant: 'solid' },
+    })
+  })
+})
+
+describe('parseArgs', () => {
+  it('parses positional args, --out, and repeated --variant flags', () => {
+    const result = parseArgs([
+      'specimen/index.html',
+      '.btn',
+      'button',
+      '--out',
+      'out.json',
+      '--variant',
+      'variant=solid',
+      '--variant',
+      'size=md',
+    ])
+
+    expect(result).toEqual({
+      htmlPath: 'specimen/index.html',
+      selector: '.btn',
+      component: 'button',
+      out: 'out.json',
+      baseVariant: { variant: 'solid', size: 'md' },
+    })
+  })
+})
+
+describe('extraction pipeline against a fixture specimen', () => {
+  it('produces a manifest that validates against the css-property-manifest schema', () => {
+    document.body.innerHTML = loadFixtureBody('extract-css-properties.fixture.html')
+    const element = document.querySelector('[data-testid="button"]')
+    expect(element).not.toBeNull()
+
+    const styleMap = readComputedStyleMap(element as Element, DEFAULT_VISUAL_PROPERTIES, (el) =>
+      getComputedStyle(el as Element)
+    )
+    const manifest = buildCssPropertyManifest({
+      component: 'button',
+      styleMap,
+      baseVariant: { variant: 'solid' },
+      description: 'Extracted from extract-css-properties.fixture.html',
+    })
+
+    expect(validateCssPropertyManifest(manifest)).toEqual({ valid: true, errors: [] })
+    const properties = manifest.properties.map((entry) => entry.property)
+    expect(properties).toContain('backgroundColor')
+    expect(properties).toContain('paddingLeft')
+    expect(manifest.properties.every((entry) => entry.token === null)).toBe(true)
+  })
+})

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]
+}

package/src/theme/tokens-css.ts

@@ -2,9 +2,11 @@
  * Token CSS Generator
  *
  * Emits a static `:root {}` CSS block from the canonical theme token maps
- * (`darkThemeCSSVars` / `lightThemeCSSVars`). HTML prototypes import the
- * generated stylesheet so they always resolve to the exact same values as
- * the design system. Pure codegen: deterministic and diffable against source.
+ * (`darkThemeCSSVars` / `lightThemeCSSVars`). Those maps mirror every `:root`
+ * custom property in `theme/global.css` — completeness and value parity are
+ * enforced by `config.completeness.test.ts`, so HTML prototypes that import the
+ * generated stylesheet resolve to the exact same values as the design system.
+ * Pure codegen: deterministic and diffable against source.
  *
  * Dark mode is the default (`:root`); light mode is activated with `.light`,
  * matching the convention in `theme/global.css`.

package/src/theme/workout-tokens.ts

@@ -3,8 +3,15 @@
  * Use these inline instead of Tailwind classes.
  */
 export const WORKOUT_TOKENS = {
-  // Velocity zones (not in Tailwind)
-  velocity: {
+  // 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. Each component maps its own
+  // thresholds onto these four colors. Kept as vivid data-viz values (distinct
+  // from the muted status tokens) and theme-independent, so — like the heatmap
+  // scale below — they are consumed inline as a JS import rather than CSS vars.
+  // A JS import also resolves on native RN, unlike var(--…) strings.
+  scale: {
     green: '#2ed573',
     yellow: '#ffd43b',
     orange: '#ffa502',
@@ -25,18 +32,9 @@ export const WORKOUT_TOKENS = {
   // Badge border-radius (rounded-sm is 4px, we need 2px)
   badgeRadius: 2,
 
-  // Border colors (use inline to avoid 'border' class pitfall)
-  border: {
-    default: '#1F1F1F',
-    strong: '#2C2C2C',
-    subtle: '#1C1C1C',
-  },
-
-  // Surface colors for inline use
-  surface: {
-    raised: '#1C1C1C',
-    elevated: '#191919',
-  },
+  // Surface and border colors were removed here: those flip with the theme, so
+  // components use the CSS custom properties (var(--color-surface-*/border-*))
+  // directly. Only theme-independent data-viz values remain below.
 
   // Intensity bar specific
   intensity: {

package/src/utils/index.ts

@@ -27,3 +27,13 @@ export type {
   FormErrors,
   FormTouched,
 } from './form'
+export {
+  roundRpe,
+  rpeColor,
+  roundWeight,
+  formatVelocity,
+  roundTempo,
+  formatSignedPct,
+  formatPrescription,
+} from './workout-format'
+export type { PrescriptionInput } from './workout-format'

package/src/utils/workout-format.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect } from 'vitest'
+import {
+  roundRpe,
+  rpeColor,
+  roundWeight,
+  formatVelocity,
+  roundTempo,
+  formatSignedPct,
+  formatPrescription,
+} from './workout-format'
+import { WORKOUT_TOKENS } from '../theme/workout-tokens'
+
+describe('roundRpe', () => {
+  it('rounds an exact RPE to the nearest 0.5', () => {
+    expect(roundRpe(8.3)).toBe(8.5)
+    expect(roundRpe(8.24)).toBe(8)
+    expect(roundRpe(9)).toBe(9)
+    expect(roundRpe(7.75)).toBe(8)
+  })
+})
+
+describe('rpeColor', () => {
+  it('bands onto the canonical scale, red for hardest', () => {
+    expect(rpeColor(9.5)).toBe(WORKOUT_TOKENS.scale.red)
+    expect(rpeColor(8.5)).toBe(WORKOUT_TOKENS.scale.orange)
+    expect(rpeColor(7)).toBe(WORKOUT_TOKENS.scale.yellow)
+    expect(rpeColor(6.9)).toBe(WORKOUT_TOKENS.scale.green)
+  })
+})
+
+describe('roundWeight', () => {
+  it('rounds to a whole unit', () => {
+    expect(roundWeight(62.4)).toBe(62)
+    expect(roundWeight(62.5)).toBe(63)
+    expect(roundWeight(60)).toBe(60)
+  })
+})
+
+describe('formatVelocity', () => {
+  it('formats m/s to 2 decimal places', () => {
+    expect(formatVelocity(0.6)).toBe('0.60')
+    expect(formatVelocity(1.234)).toBe('1.23')
+  })
+})
+
+describe('roundTempo', () => {
+  it('rounds each phase to 1 dp', () => {
+    expect(roundTempo([2.34, 0, 1.06, 0.5])).toEqual([2.3, 0, 1.1, 0.5])
+  })
+})
+
+describe('formatSignedPct', () => {
+  it('renders a signed percentage from a ratio', () => {
+    expect(formatSignedPct(0.09)).toBe('+9%')
+    expect(formatSignedPct(-0.05)).toBe('-5%')
+    expect(formatSignedPct(0)).toBe('0%')
+  })
+})
+
+describe('formatPrescription', () => {
+  it('builds a full prescription string', () => {
+    expect(formatPrescription({ repsLow: 8, repsHigh: 10, weightLbs: 62, rpe: 8 })).toBe(
+      '8–10 @ 62 lb · RPE 8'
+    )
+  })
+
+  it('collapses an equal rep range to a single number', () => {
+    expect(formatPrescription({ repsLow: 5, repsHigh: 5, weightLbs: 100 })).toBe('5 @ 100 lb')
+  })
+
+  it('omits missing parts', () => {
+    expect(formatPrescription({ rpe: 7 })).toBe('RPE 7')
+    expect(formatPrescription({ weightLbs: 50 })).toBe('50 lb')
+  })
+
+  it('returns null when there is nothing to show', () => {
+    expect(formatPrescription(null)).toBeNull()
+    expect(formatPrescription(undefined)).toBeNull()
+    expect(formatPrescription({})).toBeNull()
+  })
+})

package/src/utils/workout-format.ts

@@ -0,0 +1,83 @@
+// Font mapping context: presentation-only helpers, no rendering.
+import { WORKOUT_TOKENS } from '../theme/workout-tokens'
+
+/**
+ * Presentation helpers for workout metrics.
+ *
+ * The data layer (`@voltras/workout-analytics` view-model derivations) supplies
+ * EXACT, unrounded values; these turn them into the rounded / banded / formatted
+ * forms a view renders. Keeping display munging here — in the design system, not
+ * the analytics layer — is the render half of the model↔render split: one view
+ * can round while another (or a hover) shows the exact value from the same real
+ * data. Workout components consume these so the rules live in one place.
+ */
+
+/** Round an exact RPE onto its conventional 0.5 granularity for display. */
+export function roundRpe(rpe: number): number {
+  return Math.round(rpe * 2) / 2
+}
+
+/**
+ * Color band for an RPE on the canonical performance scale. Higher RPE = harder
+ * = red (direction inverted vs velocity, which shares the same scale). Bands:
+ * `<7` green, `7–8.5` yellow, `8.5–9.5` orange, `≥9.5` red.
+ */
+export function rpeColor(rpe: number): string {
+  if (rpe >= 9.5) return WORKOUT_TOKENS.scale.red
+  if (rpe >= 8.5) return WORKOUT_TOKENS.scale.orange
+  if (rpe >= 7) return WORKOUT_TOKENS.scale.yellow
+  return WORKOUT_TOKENS.scale.green
+}
+
+/** Round a weight or e1RM to a whole unit for compact display. */
+export function roundWeight(weight: number): number {
+  return Math.round(weight)
+}
+
+/** Format an exact velocity (m/s) to the 2-dp string shown on the velocity strip. */
+export function formatVelocity(velocity: number): string {
+  return velocity.toFixed(2)
+}
+
+/** Round an exact tempo tuple (seconds) to 1 dp per phase for display. */
+export function roundTempo(
+  tempo: [number, number, number, number]
+): [number, number, number, number] {
+  return tempo.map((v) => Math.round(v * 10) / 10) as [number, number, number, number]
+}
+
+/** Signed percentage label for a deviation ratio, e.g. `+9%` / `-5%` / `0%`. */
+export function formatSignedPct(ratio: number): string {
+  const pct = Math.round(ratio * 100)
+  return `${pct > 0 ? '+' : ''}${pct}%`
+}
+
+/** Structured prescription for the active exercise (from the plan). */
+export interface PrescriptionInput {
+  repsLow?: number
+  repsHigh?: number
+  weightLbs?: number
+  rpe?: number
+}
+
+/**
+ * Human prescription string, e.g. `"8–10 @ 62 lb · RPE 8"`. `null` when there is
+ * nothing to show. Presentation-only: the plan supplies the numbers, this shapes
+ * the label.
+ */
+export function formatPrescription(p: PrescriptionInput | null | undefined): string | null {
+  if (p == null) return null
+  let reps: string | null = null
+  if (p.repsLow != null && p.repsHigh != null) {
+    reps = p.repsLow === p.repsHigh ? `${p.repsLow}` : `${p.repsLow}–${p.repsHigh}`
+  } else if (p.repsLow != null) {
+    reps = `${p.repsLow}`
+  }
+  const weight = p.weightLbs != null ? `${p.weightLbs} lb` : null
+  const head = [reps, weight].filter((s): s is string => s != null).join(' @ ')
+  const rpe = p.rpe != null ? `RPE ${p.rpe}` : null
+  const full = [head.length > 0 ? head : null, rpe]
+    .filter((s): s is string => s != null)
+    .join(' · ')
+  return full.length > 0 ? full : null
+}