@titan-design/react-ui 0.2.6 → 0.2.7

package/src/theme/manifest/css-property-manifest.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import {
+  isCssPropertyManifest,
+  validateCssPropertyManifest,
+} from './css-property-manifest.validate'
+
+const readJson = (fileName: string): unknown =>
+  JSON.parse(readFileSync(join(__dirname, fileName), 'utf-8'))
+
+describe('css-property-manifest.schema.json', () => {
+  it('is well-formed JSON Schema with the documented top-level shape', () => {
+    const schema = readJson('css-property-manifest.schema.json') as Record<string, unknown>
+
+    expect(schema.$schema).toBe('https://json-schema.org/draft/2020-12/schema')
+    expect(schema.required).toEqual(['component', 'properties'])
+    expect(schema.$defs).toHaveProperty('cssPropertyEntry')
+    expect(schema.$defs).toHaveProperty('variantOverride')
+  })
+})
+
+describe('validateCssPropertyManifest', () => {
+  it('accepts the button example manifest', () => {
+    const example = readJson('css-property-manifest.example.json')
+
+    const result = validateCssPropertyManifest(example)
+
+    expect(result).toEqual({ valid: true, errors: [] })
+    expect(isCssPropertyManifest(example)).toBe(true)
+  })
+
+  it('rejects a manifest missing required top-level fields', () => {
+    const result = validateCssPropertyManifest({ component: 'button' })
+
+    expect(result.valid).toBe(false)
+    expect(result.errors).toContain('properties must be a non-empty array')
+  })
+
+  it('rejects a property entry missing a resolvedValue', () => {
+    const candidate = {
+      component: 'button',
+      properties: [{ property: 'backgroundColor', token: 'brand-primary' }],
+    }
+
+    const result = validateCssPropertyManifest(candidate)
+
+    expect(result.valid).toBe(false)
+    expect(result.errors).toContain('properties[0].resolvedValue must be a non-empty string')
+  })
+
+  it('rejects a variantOverride missing variant axes', () => {
+    const candidate = {
+      component: 'button',
+      properties: [
+        {
+          property: 'backgroundColor',
+          token: 'brand-primary',
+          resolvedValue: 'rgb(255, 121, 0)',
+          variantOverrides: [{ resolvedValue: 'rgba(0, 0, 0, 0)' }],
+        },
+      ],
+    }
+
+    const result = validateCssPropertyManifest(candidate)
+
+    expect(result.valid).toBe(false)
+    expect(result.errors).toContain(
+      'properties[0].variantOverrides[0].variant must be a non-empty string-keyed object'
+    )
+  })
+
+  it('allows token to be null for literal (non-tokenized) values', () => {
+    const candidate = {
+      component: 'button',
+      properties: [{ property: 'borderRadius', token: null, resolvedValue: '6px' }],
+    }
+
+    expect(validateCssPropertyManifest(candidate)).toEqual({ valid: true, errors: [] })
+  })
+})

package/src/theme/manifest/css-property-manifest.types.ts

@@ -0,0 +1,49 @@
+/**
+ * TypeScript mirror of css-property-manifest.schema.json.
+ *
+ * A manifest records, per component, which visual CSS properties are tracked,
+ * which design token each one resolves from, the expected computed style
+ * value, and any per-variant overrides. Manifests are the fixtures consumed
+ * by Playwright computed-style assertions (see packages/ui/tests/visual).
+ */
+
+/** Variant axis name/value pairs, e.g. { variant: 'solid', color: 'primary', size: 'md' }. */
+export type VariantAxes = Record<string, string>
+
+/** A resolvedValue/token override that applies when the given variant axes match. */
+export interface VariantOverride {
+  /** Partial variant axis values that trigger this override, merged onto baseVariant. */
+  variant: VariantAxes
+  /** Semantic token key for this override, or null for a literal (non-tokenized) value. */
+  token?: string | null
+  /** CSS custom property backing the token for this override, if any. */
+  cssVariable?: string | null
+  /** Expected getComputedStyle value when the variant axes match. */
+  resolvedValue: string
+}
+
+/** A single tracked CSS property for a component. */
+export interface CssPropertyEntry {
+  /** CSS property name in camelCase, as returned by window.getComputedStyle (e.g. "backgroundColor"). */
+  property: string
+  /** Semantic token key this property is sourced from, or null if not backed by a token. */
+  token: string | null
+  /** CSS custom property backing the token (e.g. "--color-brand-primary"), if any. */
+  cssVariable?: string | null
+  /** Expected computed style value for baseVariant. */
+  resolvedValue: string
+  /** Overrides of token/resolvedValue for specific variant axis combinations. */
+  variantOverrides?: VariantOverride[]
+}
+
+/** The full per-component CSS property manifest. */
+export interface CssPropertyManifest {
+  /** Component identifier matching its src/components/ui/{component} directory and Storybook id. */
+  component: string
+  /** Optional human-readable note about what this manifest covers. */
+  description?: string
+  /** Variant axis values each property's top-level resolvedValue was captured against. */
+  baseVariant?: VariantAxes
+  /** Tracked CSS properties for this component. */
+  properties: CssPropertyEntry[]
+}

package/src/theme/manifest/css-property-manifest.validate.ts

@@ -0,0 +1,84 @@
+import type { CssPropertyManifest, VariantAxes } from './css-property-manifest.types'
+
+/** Result of validating a candidate manifest: valid iff errors is empty. */
+export interface ManifestValidationResult {
+  valid: boolean
+  errors: string[]
+}
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const isVariantAxes = (value: unknown): value is VariantAxes =>
+  isPlainObject(value) &&
+  Object.keys(value).length > 0 &&
+  Object.values(value).every((axisValue) => typeof axisValue === 'string')
+
+function collectVariantOverrideErrors(override: unknown, path: string): string[] {
+  if (!isPlainObject(override)) return [`${path} must be an object`]
+  const errors: string[] = []
+  if (!isVariantAxes(override.variant))
+    errors.push(`${path}.variant must be a non-empty string-keyed object`)
+  if (
+    override.token !== undefined &&
+    override.token !== null &&
+    typeof override.token !== 'string'
+  ) {
+    errors.push(`${path}.token must be a string or null`)
+  }
+  if (typeof override.resolvedValue !== 'string' || override.resolvedValue.length === 0) {
+    errors.push(`${path}.resolvedValue must be a non-empty string`)
+  }
+  return errors
+}
+
+function collectPropertyErrors(entry: unknown, path: string): string[] {
+  if (!isPlainObject(entry)) return [`${path} must be an object`]
+  const errors: string[] = []
+  if (typeof entry.property !== 'string' || entry.property.length === 0) {
+    errors.push(`${path}.property must be a non-empty string`)
+  }
+  if (entry.token !== null && typeof entry.token !== 'string') {
+    errors.push(`${path}.token must be a string or null`)
+  }
+  if (typeof entry.resolvedValue !== 'string' || entry.resolvedValue.length === 0) {
+    errors.push(`${path}.resolvedValue must be a non-empty string`)
+  }
+  if (entry.variantOverrides !== undefined) {
+    if (!Array.isArray(entry.variantOverrides)) {
+      errors.push(`${path}.variantOverrides must be an array`)
+    } else {
+      entry.variantOverrides.forEach((override, i) =>
+        errors.push(...collectVariantOverrideErrors(override, `${path}.variantOverrides[${i}]`))
+      )
+    }
+  }
+  return errors
+}
+
+/** Structurally validates a candidate value against the CssPropertyManifest shape. */
+export function validateCssPropertyManifest(candidate: unknown): ManifestValidationResult {
+  if (!isPlainObject(candidate)) return { valid: false, errors: ['manifest must be an object'] }
+
+  const errors: string[] = []
+  if (typeof candidate.component !== 'string' || candidate.component.length === 0) {
+    errors.push('component must be a non-empty string')
+  }
+  if (candidate.baseVariant !== undefined && !isVariantAxes(candidate.baseVariant)) {
+    errors.push('baseVariant must be a non-empty string-keyed object')
+  }
+  if (!Array.isArray(candidate.properties) || candidate.properties.length === 0) {
+    errors.push('properties must be a non-empty array')
+  } else {
+    candidate.properties.forEach((entry, i) =>
+      errors.push(...collectPropertyErrors(entry, `properties[${i}]`))
+    )
+  }
+
+  return { valid: errors.length === 0, errors }
+}
+
+/** Type guard variant of validateCssPropertyManifest for use in narrowing contexts. */
+export function isCssPropertyManifest(candidate: unknown): candidate is CssPropertyManifest {
+  return validateCssPropertyManifest(candidate).valid
+}

package/src/theme/manifest/index.ts

@@ -0,0 +1,11 @@
+export type {
+  CssPropertyEntry,
+  CssPropertyManifest,
+  VariantAxes,
+  VariantOverride,
+} from './css-property-manifest.types'
+export {
+  isCssPropertyManifest,
+  validateCssPropertyManifest,
+  type ManifestValidationResult,
+} from './css-property-manifest.validate'

package/src/theme/tokens-css.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect } from 'vitest'
+import { generateTokensCss } from './tokens-css'
+import { darkThemeCSSVars, lightThemeCSSVars } from './config'
+
+describe('generateTokensCss', () => {
+  const css = generateTokensCss()
+
+  it('emits a default :root block and a .light override block', () => {
+    expect(css).toContain(':root {')
+    expect(css).toContain('.light, :root.light {')
+  })
+
+  it('emits every dark token in :root with its exact value', () => {
+    for (const [name, value] of Object.entries(darkThemeCSSVars)) {
+      expect(css).toContain(`  ${name}: ${value};`)
+    }
+  })
+
+  it('emits every light token with its exact value', () => {
+    for (const [name, value] of Object.entries(lightThemeCSSVars)) {
+      expect(css).toContain(`  ${name}: ${value};`)
+    }
+  })
+
+  it('is deterministic across invocations', () => {
+    expect(generateTokensCss()).toBe(css)
+  })
+})

package/src/theme/tokens-css.ts

@@ -0,0 +1,34 @@
+/**
+ * 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.
+ *
+ * Dark mode is the default (`:root`); light mode is activated with `.light`,
+ * matching the convention in `theme/global.css`.
+ */
+
+import { darkThemeCSSVars, lightThemeCSSVars } from './config'
+
+type CSSVarMap = Record<string, string>
+
+const GENERATED_HEADER = '/* Generated from theme token maps. Do not edit by hand. */'
+
+function formatBlock(selector: string, vars: CSSVarMap): string {
+  const declarations = Object.entries(vars)
+    .map(([name, value]) => `  ${name}: ${value};`)
+    .join('\n')
+  return `${selector} {\n${declarations}\n}`
+}
+
+/**
+ * Build the full `tokens.css` contents: a default (dark) `:root` block plus a
+ * `.light` override block, driven entirely by the exported token maps.
+ */
+export function generateTokensCss(): string {
+  const root = formatBlock(':root', darkThemeCSSVars)
+  const light = formatBlock('.light, :root.light', lightThemeCSSVars)
+  return `${GENERATED_HEADER}\n\n${root}\n\n${light}\n`
+}

package/src/theme/workout-tokens.ts

@@ -0,0 +1,61 @@
+/**
+ * Workout-specific tokens not yet in the main Tailwind config.
+ * Use these inline instead of Tailwind classes.
+ */
+export const WORKOUT_TOKENS = {
+  // Velocity zones (not in Tailwind)
+  velocity: {
+    green: '#2ed573',
+    yellow: '#ffd43b',
+    orange: '#ffa502',
+    red: '#ff4757',
+  },
+
+  // BodyMap volume heatmap scale (drive dynamic SVG fills, so inline values).
+  // Maps weekly-volume status against MEV/MAV/MRV landmarks to a fill color.
+  heatmap: {
+    none: '#E0E0E0', // gray — no training data
+    under: '#4A90D9', // cool blue — below MEV
+    maintenance: '#F5C842', // warm yellow — MEV to MAV
+    productive: '#4CAF50', // green — MAV to MRV
+    approaching: '#FFA502', // orange — near MRV
+    over: '#FF6B35', // red-orange — over MRV
+  },
+
+  // 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',
+  },
+
+  // Intensity bar specific
+  intensity: {
+    track: '#333333',
+    over1: '#D14343',
+    over2: '#A62626',
+    over3: '#7A1C1C',
+    targetLine: 'rgba(33, 150, 243, 0.5)',
+    atTargetGlow:
+      '0 0 5px 1px rgba(33, 150, 243, 0.35), 0 0 10px 3px rgba(33, 150, 243, 0.15)',
+  },
+
+  // Placeholder strip
+  placeholder: {
+    fill: '#3A3A3A',
+  },
+
+  // Deviation bar
+  deviation: {
+    track: '#333333',
+  },
+} as const