@titan-design/react-ui 0.5.0 → 0.7.0

package/src/components/custom/Workout/ZoneTrack.stories.tsx

@@ -0,0 +1,140 @@
+// Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View } from 'react-native'
+import { ZoneTrack, type ZoneTrackZone } from './ZoneTrack'
+import { WORKOUT_TOKENS } from '../../../theme/workout-tokens'
+
+const { green, yellow, orange, red } = WORKOUT_TOKENS.scale
+
+const FATIGUE_ZONES: ZoneTrackZone[] = [
+  { upTo: 10, color: green },
+  { upTo: 20, color: yellow },
+  { upTo: 30, color: orange },
+  { upTo: 40, color: red },
+]
+
+const FATIGUE_TICKS = [
+  { value: 0, label: 'fresh' },
+  { value: 10, label: 'VL10' },
+  { value: 20, label: 'VL20' },
+  { value: 30, label: 'VL30' },
+  { value: 40, label: 'stop' },
+]
+
+const meta: Meta<typeof ZoneTrack> = {
+  title: 'Workout/DataViz/ZoneTrack',
+  component: ZoneTrack,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '**Primitive.** The shared linear-gauge base: a pill track with an N-band zone ' +
+          'gradient, optional tick marks + labels, and a single value marker — a `needle` line ' +
+          'or a left-anchored `fill` (clip-reveal gradient, or solid trend colour). Used-by ↓ ' +
+          '[FatigueMeter](?path=/docs/workout-dataviz-fatiguemeter--docs); the target base for ' +
+          'TrainingLoadGauge (ACWR) + RpeCalibration (band + marker). Zone colours are literal ' +
+          'ramp-token hex.',
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <View style={{ width: 360, padding: 20, backgroundColor: '#131313' }}>
+        <Story />
+      </View>
+    ),
+  ],
+}
+export default meta
+
+type Story = StoryObj<typeof ZoneTrack>
+
+/** Needle over the fatigue gradient with the VL scale — the FatigueMeter shape. */
+export const Needle: Story = {
+  args: {
+    zones: FATIGUE_ZONES,
+    max: 40,
+    marker: { type: 'needle', value: 21 },
+    ticks: FATIGUE_TICKS,
+  },
+}
+
+/** Fill marker without a colour clip-reveals the gradient up to the value. */
+export const GradientFill: Story = {
+  args: {
+    zones: FATIGUE_ZONES,
+    max: 40,
+    marker: { type: 'fill', value: 24 },
+    ticks: FATIGUE_TICKS,
+  },
+}
+
+/** Fill marker with a colour paints a solid trend-coloured bar (FatigueGauge lineage). */
+export const SolidTrendFill: Story = {
+  args: { zones: FATIGUE_ZONES, max: 40, marker: { type: 'fill', value: 24, color: orange } },
+}
+
+/** A range highlight + needle — the RpeCalibration "predicted CI band vs actual" idiom. */
+export const BandWithMarker: Story = {
+  args: {
+    zones: [
+      { upTo: 7, color: green },
+      { upTo: 8.5, color: yellow },
+      { upTo: 10, color: red },
+    ],
+    min: 6,
+    max: 10,
+    band: { from: 7.2, to: 8.4, color: 'rgba(255,255,255,0.22)' },
+    marker: { type: 'needle', value: 8.1 },
+    ticks: [
+      { value: 6, label: '6' },
+      { value: 7, label: '7' },
+      { value: 8, label: '8' },
+      { value: 9, label: '9' },
+      { value: 10, label: '10' },
+    ],
+  },
+}
+
+/** Bare gradient track — no marker, no ticks. */
+export const BareTrack: Story = {
+  args: { zones: FATIGUE_ZONES, max: 40 },
+}
+
+/** Chunky wall-glanceable density via a taller track. */
+export const WallDensity: Story = {
+  args: {
+    zones: FATIGUE_ZONES,
+    max: 40,
+    marker: { type: 'needle', value: 15 },
+    ticks: FATIGUE_TICKS,
+    trackHeight: 22,
+    needleOverhang: 9,
+  },
+}
+
+/** `marker.glow` haloes the whole track in the marker colour — a "sweet spot" / attention cue. */
+export const Glow: Story = {
+  args: {
+    zones: FATIGUE_ZONES,
+    max: 40,
+    marker: { type: 'fill', value: 20, color: green, glow: true },
+    trackHeight: 12,
+  },
+}
+
+/** Colored + emphasized ticks with tooltips — hover a label to expand the acronym / show the raw value. */
+export const ColoredTooltipTicks: Story = {
+  args: {
+    zones: FATIGUE_ZONES,
+    max: 40,
+    marker: { type: 'needle', value: 22 },
+    trackHeight: 12,
+    ticks: [
+      { value: 10, label: 'VL10', tooltip: '10% velocity loss' },
+      { value: 20, label: 'VL20', emphasized: true, tooltip: '20% velocity loss — threshold' },
+      { value: 30, label: 'STOP', color: red, tooltip: '30% velocity loss — stop the set' },
+    ],
+  },
+}

package/src/components/custom/Workout/ZoneTrack.test.tsx

@@ -0,0 +1,200 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { ZoneTrack, type ZoneTrackZone } from './ZoneTrack'
+import { WORKOUT_TOKENS } from '../../../theme/workout-tokens'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+
+const { green, yellow, orange, red } = WORKOUT_TOKENS.scale
+const t = getSemanticColors('dark')
+
+const ZONES: ZoneTrackZone[] = [
+  { upTo: 10, color: green },
+  { upTo: 20, color: yellow },
+  { upTo: 30, color: orange },
+  { upTo: 40, color: red },
+]
+
+describe('ZoneTrack', () => {
+  it('renders one band per zone', () => {
+    render(<ZoneTrack zones={ZONES} max={40} />)
+    expect(screen.getAllByTestId('zone-track-band')).toHaveLength(4)
+  })
+
+  it('colours each band from the supplied zone token (literal hex, not a var ref)', () => {
+    render(<ZoneTrack zones={ZONES} max={40} />)
+    const bands = screen.getAllByTestId('zone-track-band')
+    expect(bands[0]).toHaveStyle({ backgroundColor: green })
+    expect(bands[3]).toHaveStyle({ backgroundColor: red })
+  })
+
+  it('weights each band by its domain span', () => {
+    render(
+      <ZoneTrack
+        zones={[
+          { upTo: 30, color: green },
+          { upTo: 40, color: red },
+        ]}
+        max={40}
+      />
+    )
+    const bands = screen.getAllByTestId('zone-track-band')
+    expect(bands[0]).toHaveStyle({ flexGrow: 30 })
+    expect(bands[1]).toHaveStyle({ flexGrow: 10 })
+  })
+
+  it('renders no marker when none is supplied', () => {
+    render(<ZoneTrack zones={ZONES} max={40} />)
+    expect(screen.queryByTestId('zone-track-needle')).not.toBeInTheDocument()
+    expect(screen.queryByTestId('zone-track-fill')).not.toBeInTheDocument()
+    expect(screen.queryByTestId('zone-track-unfilled')).not.toBeInTheDocument()
+  })
+
+  it('positions a needle marker at the value fraction of the domain', () => {
+    render(<ZoneTrack zones={ZONES} max={40} marker={{ type: 'needle', value: 10 }} />)
+    expect(screen.getByTestId('zone-track-needle')).toHaveStyle({ left: '25%' })
+  })
+
+  it('clamps a needle past the max to the track end', () => {
+    render(<ZoneTrack zones={ZONES} max={40} marker={{ type: 'needle', value: 100 }} />)
+    expect(screen.getByTestId('zone-track-needle')).toHaveStyle({ left: '100%' })
+  })
+
+  it('clip-reveals the gradient for a fill marker without a colour', () => {
+    render(<ZoneTrack zones={ZONES} max={40} marker={{ type: 'fill', value: 20 }} />)
+    expect(screen.getByTestId('zone-track-unfilled')).toHaveStyle({ left: '50%' })
+    expect(screen.queryByTestId('zone-track-fill')).not.toBeInTheDocument()
+  })
+
+  it('draws a solid trend fill when the fill marker has a colour', () => {
+    render(<ZoneTrack zones={ZONES} max={40} marker={{ type: 'fill', value: 30, color: red }} />)
+    const fill = screen.getByTestId('zone-track-fill')
+    expect(fill).toHaveStyle({ width: '75%', backgroundColor: red })
+  })
+
+  it('renders a tick with its label per entry', () => {
+    render(
+      <ZoneTrack
+        zones={ZONES}
+        max={40}
+        ticks={[
+          { value: 0, label: 'fresh' },
+          { value: 40, label: 'stop' },
+        ]}
+      />
+    )
+    expect(screen.getAllByTestId('zone-track-tick')).toHaveLength(2)
+    expect(screen.getByText('fresh')).toBeInTheDocument()
+    expect(screen.getByText('stop')).toBeInTheDocument()
+  })
+
+  it('draws a range highlight only when a band is supplied', () => {
+    const { rerender } = render(<ZoneTrack zones={ZONES} max={40} />)
+    expect(screen.queryByTestId('zone-track-band-highlight')).not.toBeInTheDocument()
+    rerender(
+      <ZoneTrack
+        zones={ZONES}
+        max={40}
+        band={{ from: 10, to: 20, color: 'rgba(255,255,255,0.2)' }}
+      />
+    )
+    expect(screen.getByTestId('zone-track-band-highlight')).toHaveStyle({
+      left: '25%',
+      width: '25%',
+    })
+  })
+
+  // RNW does not map accessibilityValue → aria-valuenow under jsdom (gotcha #11), so the
+  // value is verified via the marker position + the accessible name, not aria-valuenow.
+  it('exposes the progressbar role with an accessible name', () => {
+    render(
+      <ZoneTrack
+        zones={ZONES}
+        max={40}
+        marker={{ type: 'needle', value: 12 }}
+        accessibilityLabel="Fatigue meter"
+      />
+    )
+    expect(screen.getByRole('progressbar', { name: 'Fatigue meter' })).toBeInTheDocument()
+  })
+
+  describe('accessibility', () => {
+    it('has no accessibility violations', async () => {
+      const { container } = render(
+        <ZoneTrack
+          zones={ZONES}
+          max={40}
+          marker={{ type: 'needle', value: 21 }}
+          ticks={[
+            { value: 0, label: 'fresh' },
+            { value: 40, label: 'stop' },
+          ]}
+          accessibilityLabel="Fatigue meter"
+        />
+      )
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+  })
+
+  describe('glow', () => {
+    it('haloes the track when the marker has glow', () => {
+      render(
+        <ZoneTrack
+          zones={ZONES}
+          max={40}
+          marker={{ type: 'fill', value: 24, color: orange, glow: true }}
+        />
+      )
+      expect((screen.getByTestId('zone-track-track') as HTMLElement).style.boxShadow).not.toBe('')
+    })
+    it('has no glow by default', () => {
+      render(
+        <ZoneTrack zones={ZONES} max={40} marker={{ type: 'fill', value: 24, color: orange }} />
+      )
+      expect((screen.getByTestId('zone-track-track') as HTMLElement).style.boxShadow).toBe('')
+    })
+  })
+
+  describe('ticks (colored lines + labels + tooltip)', () => {
+    it('renders a line and label per tick', () => {
+      render(
+        <ZoneTrack
+          zones={ZONES}
+          max={40}
+          ticks={[
+            { value: 10, label: 'A' },
+            { value: 30, label: 'B' },
+          ]}
+        />
+      )
+      expect(screen.getAllByTestId('zone-track-tick-line')).toHaveLength(2)
+      expect(screen.getAllByTestId('zone-track-tick-label').map((e) => e.textContent)).toEqual([
+        'A',
+        'B',
+      ])
+    })
+    it('colours an emphasized tick line with the brand accent', () => {
+      render(
+        <ZoneTrack zones={ZONES} max={40} ticks={[{ value: 20, label: 'T', emphasized: true }]} />
+      )
+      expect(screen.getByTestId('zone-track-tick-line')).toHaveStyle({
+        backgroundColor: t['brand-primary'],
+      })
+    })
+    it('applies a per-tick color override to the line', () => {
+      render(<ZoneTrack zones={ZONES} max={40} ticks={[{ value: 20, label: 'X', color: red }]} />)
+      expect(screen.getByTestId('zone-track-tick-line')).toHaveStyle({ backgroundColor: red })
+    })
+    it('renders a tooltip label trigger', () => {
+      render(
+        <ZoneTrack
+          zones={ZONES}
+          max={40}
+          ticks={[{ value: 20, label: 'MAV', tooltip: 'Maximum Adaptive Volume' }]}
+        />
+      )
+      expect(screen.getByText('MAV')).toBeInTheDocument()
+    })
+  })
+})

package/src/components/custom/Workout/ZoneTrack.tsx

@@ -0,0 +1,315 @@
+// Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
+import { View, Text, type ViewProps, type DimensionValue } from 'react-native'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+import { primitiveColors } from '../../../theme/tokens/primitives'
+import { alpha } from '../../../utils/colors'
+import { Tooltip } from '../../ui/tooltip/Tooltip'
+
+const t = getSemanticColors('dark')
+
+/** Soft two-stop glow in `color`, for a marker's optional `glow`. */
+function glowShadow(color: string): string {
+  return `0 0 5px 1px ${alpha(color, 0.3)}, 0 0 10px 3px ${alpha(color, 0.12)}`
+}
+
+/** Muted, un-reached track colour — a charcoal step, matches the IntensityBar track family. */
+const DEFAULT_TRACK_COLOR = primitiveColors.charcoal[200]
+/** Default needle / fill-marker colour. */
+const DEFAULT_MARKER_COLOR = primitiveColors.white
+/** Tick mark + tick label colour. */
+const TICK_COLOR = t['text-tertiary']
+
+const DEFAULT_TRACK_HEIGHT = 14
+const DEFAULT_NEEDLE_OVERHANG = 6
+const NEEDLE_WIDTH = 4
+
+/** A single colour band of the zone gradient, spanning `[prev.upTo, upTo]` of the domain. */
+export interface ZoneTrackZone {
+  /** Upper bound of this band in domain units. The last band's `upTo` should reach `max`. */
+  upTo: number
+  /** Band fill colour — a literal hex (RNW-safe), sourced from a ramp/effort-scale token. */
+  color: string
+}
+
+/**
+ * A tick at `value`: a colored line over the track + an optional compact label
+ * below, with an optional tooltip (to expand an acronym / show the raw value so
+ * the label footer can stay light). Multiple ticks are supported.
+ */
+export interface ZoneTrackTick {
+  /** Position of the tick in domain units. */
+  value: number
+  /** Optional compact label rendered under the tick. */
+  label?: string
+  /** Line + label colour. Defaults to a muted tick colour (or brand when `emphasized`). */
+  color?: string
+  /** Emphasize this tick (thicker line, brand colour by default) — e.g. a target landmark. */
+  emphasized?: boolean
+  /** Tooltip content shown on hover (web) / long-press (native) — expand the acronym, show the raw value. */
+  tooltip?: string
+}
+
+/**
+ * The value marker sitting on the track.
+ * - `needle`: a vertical line at `value`, overhanging the track (FatigueMeter / TrainingLoadGauge).
+ * - `fill`: a left-anchored fill from `min` to `value`. Omit `color` to clip-reveal the zone
+ *   gradient up to `value`; supply `color` for a solid trend-coloured fill (FatigueGauge-style).
+ */
+export type ZoneTrackMarker =
+  | { type: 'needle'; value: number; color?: string; glow?: boolean }
+  | { type: 'fill'; value: number; color?: string; glow?: boolean }
+
+/** An optional translucent range highlight (e.g. RpeCalibration's predicted CI band). */
+export interface ZoneTrackBand {
+  /** Range start in domain units. */
+  from: number
+  /** Range end in domain units. */
+  to: number
+  /** Highlight colour (typically a translucent token). */
+  color: string
+}
+
+export interface ZoneTrackProps extends ViewProps {
+  /** Ordered zone bands, laid left→right; each covers `[previous.upTo, upTo]` of the domain. */
+  zones: ZoneTrackZone[]
+  /** Domain maximum (right edge). */
+  max: number
+  /** Domain minimum (left edge). Default 0. */
+  min?: number
+  /** The value marker — a needle line or a left-anchored fill. Omit for a bare gradient track. */
+  marker?: ZoneTrackMarker | null
+  /** Optional tick marks with labels below the track. */
+  ticks?: ZoneTrackTick[]
+  /** Optional translucent range highlight drawn over the gradient. */
+  band?: ZoneTrackBand | null
+  /** Track height in px. Default 14. */
+  trackHeight?: number
+  /** How far a needle marker overhangs the track top + bottom, in px. Default 6. */
+  needleOverhang?: number
+  /** Muted colour of the track behind / beyond the fill. Default a charcoal step. */
+  trackColor?: string
+  className?: string
+}
+
+/** Map a domain value to a clamped 0..1 fraction of the track width. */
+function fraction(value: number, min: number, max: number): number {
+  if (max <= min) return 0
+  return Math.max(0, Math.min(1, (value - min) / (max - min)))
+}
+
+function pct(frac: number): DimensionValue {
+  return `${frac * 100}%`
+}
+
+/**
+ * Low-level gauge primitive: a horizontal pill track carrying an N-band zone gradient,
+ * optional tick marks with labels, and a single value marker (a needle line or a
+ * left-anchored fill). The zone bands are weighted by their domain span, so thresholds
+ * need not be evenly spaced. This is the shared visual base for the linear gauge family
+ * (FatigueMeter needle, TrainingLoadGauge zone bar, RpeCalibration band + marker) — pass
+ * the domain (`min`/`max`), the `zones`, and a `marker`; colours are literal hex from the
+ * ramp tokens (never `var()` refs, so they survive the RNW/vitest alias).
+ */
+export function ZoneTrack({
+  zones,
+  max,
+  min = 0,
+  marker = null,
+  ticks,
+  band = null,
+  trackHeight = DEFAULT_TRACK_HEIGHT,
+  needleOverhang = DEFAULT_NEEDLE_OVERHANG,
+  trackColor = DEFAULT_TRACK_COLOR,
+  className,
+  style,
+  accessibilityLabel,
+  ...props
+}: ZoneTrackProps) {
+  const isNeedle = marker?.type === 'needle'
+  const markerHeight = isNeedle ? trackHeight + needleOverhang * 2 : trackHeight
+  const markerFrac = marker != null ? fraction(marker.value, min, max) : 0
+
+  const bands = zones.map((zone, i) => {
+    const prev = i === 0 ? min : zones[i - 1].upTo
+    const start = Math.max(min, Math.min(max, prev))
+    const end = Math.max(min, Math.min(max, zone.upTo))
+    return { color: zone.color, weight: Math.max(0, end - start) }
+  })
+
+  return (
+    <View
+      className={className}
+      style={[{ width: '100%' }, style]}
+      accessibilityRole="progressbar"
+      accessibilityValue={marker != null ? { min, max, now: marker.value } : { min, max, now: min }}
+      accessibilityLabel={accessibilityLabel ?? `Zone track: ${marker?.value ?? min}`}
+      testID="zone-track"
+      {...props}
+    >
+      <View style={{ position: 'relative', height: markerHeight }}>
+        <View
+          testID="zone-track-track"
+          accessibilityElementsHidden
+          style={{
+            position: 'absolute',
+            top: (markerHeight - trackHeight) / 2,
+            left: 0,
+            right: 0,
+            height: trackHeight,
+            borderRadius: trackHeight / 2,
+            backgroundColor: trackColor,
+            overflow: 'hidden',
+            flexDirection: 'row',
+            // The pill's own box-shadow renders outside its overflow:hidden, so
+            // `glow` haloes the whole track in the marker colour.
+            ...(marker?.glow
+              ? { boxShadow: glowShadow(marker.color ?? DEFAULT_MARKER_COLOR) }
+              : null),
+          }}
+        >
+          {bands.map((b, i) => (
+            <View
+              key={i}
+              testID="zone-track-band"
+              style={{
+                flexGrow: b.weight,
+                flexShrink: 1,
+                flexBasis: 0,
+                minWidth: 0,
+                height: '100%',
+                backgroundColor: b.color,
+              }}
+            />
+          ))}
+
+          {band != null && (
+            <View
+              testID="zone-track-band-highlight"
+              style={{
+                position: 'absolute',
+                top: 0,
+                bottom: 0,
+                left: pct(fraction(band.from, min, max)),
+                width: pct(fraction(band.to, min, max) - fraction(band.from, min, max)),
+                backgroundColor: band.color,
+              }}
+            />
+          )}
+
+          {marker?.type === 'fill' && (
+            <View
+              testID="zone-track-unfilled"
+              style={{
+                position: 'absolute',
+                top: 0,
+                bottom: 0,
+                left: pct(markerFrac),
+                right: 0,
+                backgroundColor: trackColor,
+              }}
+            />
+          )}
+          {marker?.type === 'fill' && marker.color != null && (
+            <View
+              testID="zone-track-fill"
+              style={{
+                position: 'absolute',
+                top: 0,
+                bottom: 0,
+                left: 0,
+                width: pct(markerFrac),
+                backgroundColor: marker.color,
+              }}
+            />
+          )}
+        </View>
+
+        {isNeedle && (
+          <View
+            testID="zone-track-needle"
+            style={{
+              position: 'absolute',
+              top: 0,
+              left: pct(markerFrac),
+              width: NEEDLE_WIDTH,
+              height: markerHeight,
+              borderRadius: NEEDLE_WIDTH / 2,
+              backgroundColor: marker.color ?? DEFAULT_MARKER_COLOR,
+              transform: [{ translateX: -NEEDLE_WIDTH / 2 }],
+            }}
+          />
+        )}
+
+        {/* Colored tick lines over the track (decorative; the labels below carry the a11y). */}
+        {ticks?.map((tick, i) => {
+          const emphasized = tick.emphasized === true
+          const lineColor = tick.color ?? (emphasized ? t['brand-primary'] : TICK_COLOR)
+          const lineWidth = emphasized ? 2 : 1.5
+          return (
+            <View
+              key={`line-${i}`}
+              testID="zone-track-tick-line"
+              accessibilityElementsHidden
+              style={{
+                position: 'absolute',
+                top: (markerHeight - trackHeight) / 2 - 2,
+                left: pct(fraction(tick.value, min, max)),
+                width: lineWidth,
+                height: trackHeight + 4,
+                borderRadius: lineWidth / 2,
+                backgroundColor: lineColor,
+                transform: [{ translateX: -lineWidth / 2 }],
+                zIndex: 3,
+              }}
+            />
+          )
+        })}
+      </View>
+
+      {ticks != null && ticks.length > 0 && (
+        <View style={{ position: 'relative', height: 16, marginTop: 5 }}>
+          {ticks.map((tick, i) => {
+            if (tick.label == null) return null
+            const emphasized = tick.emphasized === true
+            const labelColor = tick.color ?? (emphasized ? t['brand-primary'] : TICK_COLOR)
+            const labelNode = (
+              <Text
+                testID="zone-track-tick-label"
+                style={{
+                  fontSize: 9,
+                  letterSpacing: 0.5,
+                  color: labelColor,
+                  fontFamily: 'monospace',
+                  fontWeight: emphasized ? '700' : '400',
+                }}
+              >
+                {tick.label}
+              </Text>
+            )
+            return (
+              <View
+                key={`label-${i}`}
+                testID="zone-track-tick"
+                style={{
+                  position: 'absolute',
+                  left: pct(fraction(tick.value, min, max)),
+                  transform: [{ translateX: -14 }],
+                  width: 28,
+                  alignItems: 'center',
+                }}
+              >
+                {tick.tooltip != null ? (
+                  <Tooltip label={tick.tooltip} placement="top">
+                    {labelNode}
+                  </Tooltip>
+                ) : (
+                  labelNode
+                )}
+              </View>
+            )
+          })}
+        </View>
+      )}
+    </View>
+  )
+}