@titan-design/react-ui 0.12.1 → 0.13.0

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

@@ -33,7 +33,8 @@ export const RED = '#D14343' // red 600
 export const ORANGE = '#FF7900' // orange 400
 export const AMBER = '#F9B415' // amber 300
 export const GREEN = '#2ED573' // green 300
-export const velColor = (v: number): string => (v < 0.5 ? RED : v < 0.75 ? ORANGE : v < 1.0 ? AMBER : GREEN)
+export const velColor = (v: number): string =>
+  v < 0.5 ? RED : v < 0.75 ? ORANGE : v < 1.0 ? AMBER : GREEN
 
 // active-set pulse: each segment eases along its own ramp (adjacent lighter/darker steps) through the pin.
 export const PULSE_CSS = `
@@ -42,7 +43,16 @@ export const PULSE_CSS = `
 @keyframes s3pAmber{0%,100%{background:#FFD352}50%{background:#E08C00}}
 @keyframes s3pGreen{0%,100%{background:#58F69E}50%{background:#21C05D}}`
 export const pulseAnim = (c: string): string | undefined => {
-  const name = c === RED ? 's3pRed' : c === ORANGE ? 's3pOrange' : c === AMBER ? 's3pAmber' : c === GREEN ? 's3pGreen' : null
+  const name =
+    c === RED
+      ? 's3pRed'
+      : c === ORANGE
+        ? 's3pOrange'
+        : c === AMBER
+          ? 's3pAmber'
+          : c === GREEN
+            ? 's3pGreen'
+            : null
   return name ? `${name} 1.9s ease-in-out infinite` : undefined
 }
 
@@ -50,9 +60,23 @@ export const pulseAnim = (c: string): string | undefined => {
 const INTER = 'Inter, sans-serif'
 const SRL_SEP = '#6B7280'
 function SRLCell({ children, color = T_PRIMARY }: { children: ReactNode; color?: string }) {
-  return <span style={{ fontFamily: INTER, fontSize: 11, fontWeight: 600, letterSpacing: 1, color }}>{children}</span>
+  return (
+    <span style={{ fontFamily: INTER, fontSize: 11, fontWeight: 600, letterSpacing: 1, color }}>
+      {children}
+    </span>
+  )
 }
-export function SetsRepsLoad({ sets, reps, load, unit = 'lb' }: { sets: number; reps: number | string; load: number; unit?: string }) {
+export function SetsRepsLoad({
+  sets,
+  reps,
+  load,
+  unit = 'lb',
+}: {
+  sets: number
+  reps: number | string
+  load: number
+  unit?: string
+}) {
   return (
     <span style={{ display: 'inline-flex', alignItems: 'baseline', whiteSpace: 'nowrap' }}>
       <SRLCell>{sets}</SRLCell>
@@ -66,7 +90,10 @@ export function SetsRepsLoad({ sets, reps, load, unit = 'lb' }: { sets: number;
 }
 
 // ---- per-set bar: one continuous bar, rep intensities as butted segments (no gaps); active segments pulse
-export type SetState = { status: 'done'; reps: number[] } | { status: 'active'; reps: number[]; planned: number } | { status: 'todo'; planned: number }
+export type SetState =
+  | { status: 'done'; reps: number[] }
+  | { status: 'active'; reps: number[]; planned: number }
+  | { status: 'todo'; planned: number }
 export function setColors(s: SetState): string[] {
   if (s.status === 'todo') return [GREY]
   if (s.status === 'done') return s.reps.map(velColor)
@@ -74,9 +101,26 @@ export function setColors(s: SetState): string[] {
 }
 function SetBar({ colors, h, pulse }: { colors: string[]; h: number; pulse?: boolean }) {
   return (
-    <div style={{ display: 'flex', flex: 1, minWidth: 0, height: h, borderRadius: 2, overflow: 'hidden' }}>
+    <div
+      style={{
+        display: 'flex',
+        flex: 1,
+        minWidth: 0,
+        height: h,
+        borderRadius: 2,
+        overflow: 'hidden',
+      }}
+    >
       {colors.map((c, i) => (
-        <div key={i} style={{ flex: 1, height: '100%', background: c, animation: pulse && c !== GREY ? pulseAnim(c) : undefined }} />
+        <div
+          key={i}
+          style={{
+            flex: 1,
+            height: '100%',
+            background: c,
+            animation: pulse && c !== GREY ? pulseAnim(c) : undefined,
+          }}
+        />
       ))}
     </div>
   )
@@ -95,17 +139,48 @@ export function Indicator({ kind }: { kind: 'pr' | 'issue' | 'info' }) {
   const map = { pr: ['★', ORANGE], issue: ['!', RED], info: ['i', '#2196F3'] } as const
   const [glyph, color] = map[kind]
   return (
-    <span style={{ width: 16, height: 16, borderRadius: 8, border: `1px solid ${color}`, color, fontSize: 10, fontWeight: 800, display: 'inline-flex', alignItems: 'center', justifyContent: 'center' }}>{glyph}</span>
+    <span
+      style={{
+        width: 16,
+        height: 16,
+        borderRadius: 8,
+        border: `1px solid ${color}`,
+        color,
+        fontSize: 10,
+        fontWeight: 800,
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+      }}
+    >
+      {glyph}
+    </span>
   )
 }
 
 const labelStyle = { fontSize: 14, fontWeight: 800, color: T_PRIMARY } as const
 
 // ---- the finalized heading unit
-export type Exercise = { name: string; sets: number; reps: number | string; load: number; tempo: [number, number, number, number]; indicator?: 'pr' | 'issue' | 'info'; setStates: SetState[]; upcoming?: boolean }
+export type Exercise = {
+  name: string
+  sets: number
+  reps: number | string
+  load: number
+  tempo: [number, number, number, number]
+  indicator?: 'pr' | 'issue' | 'info'
+  setStates: SetState[]
+  upcoming?: boolean
+}
 export function Heading({ ex, stripH }: { ex: Exercise; stripH: number }) {
   return (
-    <div style={{ padding: '9px 12px', display: 'flex', flexDirection: 'column', opacity: ex.upcoming ? 0.55 : 1 }}>
+    <div
+      style={{
+        padding: '9px 12px',
+        display: 'flex',
+        flexDirection: 'column',
+        opacity: ex.upcoming ? 0.55 : 1,
+      }}
+    >
       <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
         <span style={labelStyle}>{ex.name}</span>
         <div style={{ flex: 1 }} />
@@ -124,21 +199,80 @@ export function Heading({ ex, stripH }: { ex: Exercise; stripH: number }) {
 }
 
 // ---- sample session (per-rep mean velocities; sets fatigue across the workout, reps decay in-set)
-export const reps = (n: number, start: number, span = 0.4): number[] => Array.from({ length: n }, (_, r) => +(start - (span * r) / Math.max(1, n - 1)).toFixed(3))
+export const reps = (n: number, start: number, span = 0.4): number[] =>
+  Array.from({ length: n }, (_, r) => +(start - (span * r) / Math.max(1, n - 1)).toFixed(3))
 export const SESSION: Exercise[] = [
-  { name: 'Seated Cable Row', sets: 5, reps: 8, load: 145, tempo: [3, 1, 2, 0], indicator: 'pr', setStates: [1.0, 0.9, 0.8, 0.7, 0.6].map((s) => ({ status: 'done', reps: reps(8, s) })) },
-  { name: 'Incline DB Press', sets: 3, reps: 8, load: 70, tempo: [3, 0, 3, 0], setStates: [0.72, 0.62, 0.54].map((s) => ({ status: 'done', reps: reps(8, s) })) },
-  { name: 'Cable Chest Press', sets: 3, reps: 10, load: 90, tempo: [2, 1, 2, 0], indicator: 'info', setStates: [{ status: 'done', reps: reps(10, 0.72) }, { status: 'active', reps: reps(5, 0.62), planned: 10 }, { status: 'todo', planned: 10 }] },
-  { name: 'Standing Calf Raise', sets: 5, reps: 20, load: 25, tempo: [2, 1, 2, 0], upcoming: true, setStates: [1, 2, 3, 4, 5].map(() => ({ status: 'todo', planned: 20 })) },
-  { name: 'Face Pull', sets: 3, reps: '15-20', load: 40, tempo: [2, 1, 2, 0], upcoming: true, setStates: [1, 2, 3].map(() => ({ status: 'todo', planned: 18 })) },
+  {
+    name: 'Seated Cable Row',
+    sets: 5,
+    reps: 8,
+    load: 145,
+    tempo: [3, 1, 2, 0],
+    indicator: 'pr',
+    setStates: [1.0, 0.9, 0.8, 0.7, 0.6].map((s) => ({ status: 'done', reps: reps(8, s) })),
+  },
+  {
+    name: 'Incline DB Press',
+    sets: 3,
+    reps: 8,
+    load: 70,
+    tempo: [3, 0, 3, 0],
+    setStates: [0.72, 0.62, 0.54].map((s) => ({ status: 'done', reps: reps(8, s) })),
+  },
+  {
+    name: 'Cable Chest Press',
+    sets: 3,
+    reps: 10,
+    load: 90,
+    tempo: [2, 1, 2, 0],
+    indicator: 'info',
+    setStates: [
+      { status: 'done', reps: reps(10, 0.72) },
+      { status: 'active', reps: reps(5, 0.62), planned: 10 },
+      { status: 'todo', planned: 10 },
+    ],
+  },
+  {
+    name: 'Standing Calf Raise',
+    sets: 5,
+    reps: 20,
+    load: 25,
+    tempo: [2, 1, 2, 0],
+    upcoming: true,
+    setStates: [1, 2, 3, 4, 5].map(() => ({ status: 'todo', planned: 20 })),
+  },
+  {
+    name: 'Face Pull',
+    sets: 3,
+    reps: '15-20',
+    load: 40,
+    tempo: [2, 1, 2, 0],
+    upcoming: true,
+    setStates: [1, 2, 3].map(() => ({ status: 'todo', planned: 18 })),
+  },
 ]
 
 // ---- shell chrome (neumorphic): flat raised nav + heading plane; sunk inset exercise list
 export function NavStub() {
   return (
-    <div style={{ width: 60, alignSelf: 'stretch', position: 'relative', zIndex: 2, background: RAISED, display: 'flex', flexDirection: 'column', alignItems: 'center', paddingTop: 12, gap: 8 }}>
+    <div
+      style={{
+        width: 60,
+        alignSelf: 'stretch',
+        position: 'relative',
+        zIndex: 2,
+        background: RAISED,
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        paddingTop: 12,
+        gap: 8,
+      }}
+    >
       {['Live', 'Plan', 'Body'].map((t) => (
-        <span key={t} style={{ fontSize: 8, color: T_TERTIARY, fontWeight: 700 }}>{t}</span>
+        <span key={t} style={{ fontSize: 8, color: T_TERTIARY, fontWeight: 700 }}>
+          {t}
+        </span>
       ))}
     </div>
   )
@@ -146,17 +280,39 @@ export function NavStub() {
 export function Rail({ stripH, footer }: { stripH: number; footer?: ReactNode }) {
   return (
     <div style={{ width: 246, background: INSET, display: 'flex', flexDirection: 'column' }}>
-      <div style={{ position: 'relative', zIndex: 2, padding: '11px 12px 10px', background: RAISED }}>
-        <div style={{ fontSize: 9, fontWeight: 800, letterSpacing: 1, textTransform: 'uppercase', color: T_TERTIARY, display: 'flex', alignItems: 'center', gap: 5 }}>
+      <div
+        style={{ position: 'relative', zIndex: 2, padding: '11px 12px 10px', background: RAISED }}
+      >
+        <div
+          style={{
+            fontSize: 9,
+            fontWeight: 800,
+            letterSpacing: 1,
+            textTransform: 'uppercase',
+            color: T_TERTIARY,
+            display: 'flex',
+            alignItems: 'center',
+            gap: 5,
+          }}
+        >
           <span style={{ width: 6, height: 6, borderRadius: 3, background: GREEN }} />
           Live session
         </div>
-        <div style={{ fontSize: 14, fontWeight: 800, marginTop: 3, color: T_PRIMARY }}>Pull A · Intensification</div>
-        <div style={{ fontSize: 10, color: T_SECONDARY, marginTop: 2, fontFamily: 'monospace' }}>ex 3/5 · set 2 live</div>
+        <div style={{ fontSize: 14, fontWeight: 800, marginTop: 3, color: T_PRIMARY }}>
+          Pull A · Intensification
+        </div>
+        <div style={{ fontSize: 10, color: T_SECONDARY, marginTop: 2, fontFamily: 'monospace' }}>
+          ex 3/5 · set 2 live
+        </div>
       </div>
       <div style={{ flex: 1, background: INSET, boxShadow: INSET_SHADOW }}>
         {SESSION.map((ex, i) => (
-          <div key={i} style={{ borderBottom: i < SESSION.length - 1 ? `1px solid ${BORDER_SUBTLE}` : undefined }}>
+          <div
+            key={i}
+            style={{
+              borderBottom: i < SESSION.length - 1 ? `1px solid ${BORDER_SUBTLE}` : undefined,
+            }}
+          >
             <Heading ex={ex} stripH={stripH} />
           </div>
         ))}
@@ -167,9 +323,28 @@ export function Rail({ stripH, footer }: { stripH: number; footer?: ReactNode })
 }
 
 // ---- page scaffold shared by the sheets
-export function Page({ title, note, children }: { title: string; note: string; children: ReactNode }) {
+export function Page({
+  title,
+  note,
+  children,
+}: {
+  title: string
+  note: string
+  children: ReactNode
+}) {
   return (
-    <div style={{ minHeight: '100vh', background: '#0A0A0A', color: T_PRIMARY, padding: 28, display: 'flex', flexDirection: 'column', gap: 22, fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif' }}>
+    <div
+      style={{
+        minHeight: '100vh',
+        background: '#0A0A0A',
+        color: T_PRIMARY,
+        padding: 28,
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 22,
+        fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+      }}
+    >
       <style>{PULSE_CSS}</style>
       <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
         <span style={{ fontSize: 20, fontWeight: 800 }}>{title}</span>
@@ -179,5 +354,11 @@ export function Page({ title, note, children }: { title: string; note: string; c
     </div>
   )
 }
-export const sectionTitle = { fontSize: 11, fontWeight: 800, letterSpacing: 1.2, textTransform: 'uppercase', color: ORANGE } as const
+export const sectionTitle = {
+  fontSize: 11,
+  fontWeight: 800,
+  letterSpacing: 1.2,
+  textTransform: 'uppercase',
+  color: ORANGE,
+} as const
 export const monoTag = { fontFamily: 'monospace', fontSize: 11, color: T_SECONDARY } as const

package/src/components/custom/charts/README.md

@@ -0,0 +1,61 @@
+# `custom/charts` — shared chart substrate
+
+Two marks and one hook, extracted so every value-height bar family in the library
+draws the same bar rather than each re-rolling geometry and entrance animation.
+This is a substrate family: it holds no domain knowledge, and colour, reference
+overlays and labels are passed in by the consumer.
+
+This README is the **index**: **composes ↓** and **used-by ↑** for each member,
+so the tree navigates both ways and a hand-rolled bar shows up as a gap. Counts
+come from [`src/arch/arch-graph.json`](../../../arch/arch-graph.json).
+
+## Dependency map
+
+| Member            | Kind | Composes ↓                                      | Used-by ↑                                              | Exported     |
+| ----------------- | ---- | ----------------------------------------------- | ------------------------------------------------------ | ------------ |
+| `SparkBars`       | atom | `resolveColor`, `cn`                            | FileActivityDetail, FileActivityRow (ActiveWork)       | yes          |
+| `SetBarChart`     | atom | `barPaper`, `SurfaceContext`, `live-rep-growth` | RomProgressionChart (Fatigue), VelocityStrip (Workout) | no — by path |
+| `live-rep-growth` | hook | `Animated`, `Easing`                            | SetBarChart, VelocityStrip                             | no — by path |
+
+`SetBarChart` and `live-rep-growth` are deliberately absent from `index.ts`: they
+are workout-internal and imported by path, so the public barrel stays one mark
+wide. Adding them to the barrel is a decision, not a tidy-up.
+
+## What each owns
+
+**`SetBarChart`** owns the chart _geometry_ — value→height scaling, the shared
+`scaleMax` override, plot-width-driven adaptive bar width and gap stepping, value
+label thinning — plus the shared bar _language_: paper treatment, the
+grow-from-bottom live rep, up/down orientation, the set-type slot vocabulary. Bar
+colour and the reference overlay (velocity VL bands, ROM working/short lines) are
+props. A spacing or entrance improvement therefore lands once for both consumers.
+Value-height only: `VelocityStrip`'s flat 3 px `mini` strip stays its own mark.
+
+**`SparkBars`** is a signed-series sparkline: bars over a baseline, negatives in
+`result-degrade`, a `MIN_BAR_HEIGHT` floor so an almost-empty series still reads
+as a series, and `maxBars` because a sparkline is a recent-history glance.
+
+**`live-rep-growth`** is the newest-rep entrance, promoted out of `VelocityStrip`
+so every value-height family animates the live rep identically. It carries the
+12% `PEAK_OVERSHOOT` for a new-peak bar and honours `prefers-reduced-motion`.
+
+## Reuse audit
+
+| Leaf                  | Should compose        | Status                                                                                                                                   |
+| --------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Bar geometry          | `SetBarChart`         | **Closed** for Fatigue and VelocityStrip's expanded charts; `VelocityStrip` mini is a deliberate exception.                              |
+| Live-rep entrance     | `live-rep-growth`     | **Closed.** Both consumers use the hook.                                                                                                 |
+| Colour blending       | `theme/color-math`    | **Open.** `SetBarChart.tsx` carries a local `mixHex`. Roadmap decision 8 collapses the four copies into one module; this is one of them. |
+| Surface-relative fill | `SurfaceContext`      | **Closed.** `SetBarChart` reads `useSurface`/`useOnSurfaceColor` rather than assuming a plane.                                           |
+| Inline colour         | `resolveColor(token)` | **Closed** for `SparkBars`; the family is in the token-pure eslint error block.                                                          |
+
+## Watch list
+
+- **`mixHex` duplication** (above) is the family's only open token debt. Until
+  decision 8 lands, do not add a third copy — import the one in `SetBarChart`.
+- **`SetBarChart` has no story.** `SparkBars` does; the chart is only seen through
+  its consumers' stories (`Custom/Fatigue/*`, `Custom/Workout/VelocityStrip`).
+  That is why it reads `status:candidate` — see [`MATURITY.md`](../../../../MATURITY.md).
+- **Both marks are `keep-internal`** in the arch graph: two in-repo consumers
+  each, zero external. Neither is public API yet; treat prop changes as cheap
+  while that holds.

package/src/components/custom/charts/SetBarChart.test.tsx

@@ -1,7 +1,14 @@
 import { describe, it, expect } from 'vitest'
 import { render, screen } from '@testing-library/react'
 import { axe } from 'jest-axe'
-import { SetBarChart, sideLabelText, valueLabelFontSize, type SetSlot } from './SetBarChart'
+import {
+  SetBarChart,
+  sideLabelText,
+  valueLabelFontSize,
+  estimateValueLabelWidth,
+  shouldFlipEdgeLabel,
+  type SetSlot,
+} from './SetBarChart'
 
 const reps = (values: number[]): SetSlot[] => values.map((v) => ({ kind: 'rep', value: v }))
 const silver = () => '#C7CBD1'
@@ -18,6 +25,28 @@ describe('valueLabelFontSize', () => {
   })
 })
 
+describe('shouldFlipEdgeLabel (TD-07.10)', () => {
+  it.each([
+    // [roomPx, labelWidthPx, expected]
+    [30, 20, false], // half-width (10) comfortably clears the room (30)
+    [30, 70, true], // half-width (35) exceeds the room (30)
+    [10, 20, false], // half-width (10) exactly equals the room — still a fit (not flipped)
+    [9, 20, true], // half-width (10) just exceeds the room (9)
+  ])('roomPx=%d labelWidthPx=%d -> flip=%s', (roomPx, labelWidthPx, expected) => {
+    expect(shouldFlipEdgeLabel(roomPx, labelWidthPx)).toBe(expected)
+  })
+})
+
+describe('estimateValueLabelWidth', () => {
+  it('scales with both character count and font size', () => {
+    expect(estimateValueLabelWidth('1.02', 12)).toBeCloseTo(4 * 12 * 0.62)
+    expect(estimateValueLabelWidth('1.02', 8)).toBeLessThan(estimateValueLabelWidth('1.02', 12))
+    expect(estimateValueLabelWidth('10.02', 12)).toBeGreaterThan(
+      estimateValueLabelWidth('1.02', 12)
+    )
+  })
+})
+
 describe('sideLabelText', () => {
   it('keeps the full name when the vertical extent has room', () => {
     expect(sideLabelText('Left Arm', 200)).toBe('Left Arm')

package/src/components/custom/charts/SetBarChart.tsx

@@ -133,6 +133,14 @@ export interface SetBarChartProps {
   showValueLabels?: boolean
   /** Format a rep value for its label. Default `String`. */
   formatValue?: (value: number) => string
+  /**
+   * The LAST column has no sibling to its right to absorb an overflowing value label, so a wide
+   * label there can bleed past the plot's right edge and crowd the reference line that also runs
+   * flush to it (TD-07.10). Default false (unchanged for every existing consumer — the single
+   * hero and ROM chart). When true, that column's label flips from centered to right-anchored
+   * (grows left) once {@link shouldFlipEdgeLabel} says it doesn't fit.
+   */
+  flipEdgeLabel?: boolean
   /**
    * To-do placeholder treatment. `solid` (default) — a solid surface-relative section (the plane
    * blended toward the on-surface neutral). `dashed` — a dashed outline stub. Exists so ROM can keep
@@ -198,6 +206,25 @@ export function valueLabelFontSize(height: number): number {
   return Math.round(Math.max(8, Math.min(12, height * 0.11)))
 }
 
+/** Average glyph width for the bold numeric value-label font, as a fraction of its font size — a
+ * measurement-free estimate (RN text can't be synchronously measured) good enough to catch overflow. */
+const LABEL_GLYPH_WIDTH_RATIO = 0.62
+
+/** Estimate a value label's rendered width (px) from its formatted text and font size. */
+export function estimateValueLabelWidth(text: string, fontSize: number): number {
+  return text.length * fontSize * LABEL_GLYPH_WIDTH_RATIO
+}
+
+/**
+ * Whether a value label needs to flip from its default centered anchor to a right-anchored
+ * (left-growing) placement to clear the plot's right edge (TD-07.10). `roomPx` is the space
+ * available to the right of the label's centered position; `labelWidthPx` is its measured or
+ * estimated rendered width.
+ */
+export function shouldFlipEdgeLabel(roomPx: number, labelWidthPx: number): boolean {
+  return labelWidthPx / 2 > roomPx
+}
+
 // --- Hero geometry -----------------------------------------------------------
 /** Default plot height (px) — tall enough to read a set's shape across a room. */
 export const SET_BAR_DEFAULT_HEIGHT = 220
@@ -281,6 +308,7 @@ export function SetBarChart({
   flat = false,
   showValueLabels: showValueLabelsProp = false,
   formatValue = String,
+  flipEdgeLabel = false,
   todoVariant = 'solid',
   minColumns,
   renderReference,
@@ -462,6 +490,17 @@ export function SetBarChart({
           // duplicate them); its own label shows otherwise, fading in with `expandProgress`.
           const ownLabel = showValueLabels && !renderBarOverlay && showBarLabel(repIndex)
           const labelBottom = (expandProgress ? valueBarHeight(best) : barHeight(best)) + LABEL_GAP
+          // Only the LAST cell has no sibling to its right to absorb an overflowing label
+          // (TD-07.10) — flip it right-anchored (grows left) when it doesn't fit.
+          const isLastCell = i === cells.length - 1
+          const labelText = formatValue(value)
+          const flipLabel =
+            flipEdgeLabel &&
+            isLastCell &&
+            shouldFlipEdgeLabel(
+              barWidth / 2,
+              estimateValueLabelWidth(labelText, valueLabelFontSize(height))
+            )
           return (
             <View key={i} accessibilityElementsHidden={renderBarOverlay == null} style={column}>
               {ownLabel && (
@@ -471,9 +510,8 @@ export function SetBarChart({
                   style={{
                     position: 'absolute',
                     bottom: labelBottom,
-                    left: 0,
-                    right: 0,
-                    alignItems: 'center',
+                    ...(flipLabel ? { right: 0 } : { left: 0, right: 0 }),
+                    alignItems: flipLabel ? 'flex-end' : 'center',
                     ...(expandProgress ? { opacity: expandProgress } : null),
                   }}
                   pointerEvents="none"
@@ -483,7 +521,7 @@ export function SetBarChart({
                     style={[{ fontSize: valueLabelFontSize(height), fontWeight: '700' }, flipStyle]}
                     testID={`${testIDPrefix}-label-${repIndex}`}
                   >
-                    {formatValue(value)}
+                    {labelText}
                   </Text>
                 </Animated.View>
               )}

package/src/components/custom/charts/SparkBars.stories.tsx

@@ -0,0 +1,55 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { SparkBars } from './SparkBars'
+
+const meta: Meta<typeof SparkBars> = {
+  title: 'Custom/Charts/SparkBars',
+  component: SparkBars,
+  tags: ['autodocs', 'status:candidate', '!status:review'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '**Atom.** A tiny bar-mark sparkline for a signed series — the counterpart to ' +
+          '[Sparkline](?path=/docs/custom-workout-dataviz-sparkline--docs). Where a line reads a *trajectory*, ' +
+          'bars read *discrete per-period magnitude*. Bars scale on absolute value so a negative ' +
+          'period is as tall as an equally large positive one, with the sign carried by fill colour.',
+      },
+    },
+  },
+  args: {
+    values: [120, 340, -80, 910, 420, 0, 1580, 260, -310, 740, 1120, 90],
+    height: 22,
+    barWidth: 3,
+    gap: 2,
+    maxBars: 24,
+  },
+}
+export default meta
+type Story = StoryObj<typeof SparkBars>
+
+export const Default: Story = {}
+
+/** All-positive — the plain growth case. */
+export const AllPositive: Story = {
+  args: { values: [40, 120, 260, 310, 480, 520, 900] },
+}
+
+/** All-negative — every bar takes the error token. */
+export const AllNegative: Story = {
+  args: { values: [-40, -120, -260, -310, -480] },
+}
+
+/** Taller field, as used in the file-history growth block. */
+export const Tall: Story = {
+  args: { height: 34, barWidth: 5, gap: 3 },
+}
+
+/** `maxBars` keeps only the most recent values — a sparkline is a glance, not an archive. */
+export const Truncated: Story = {
+  args: { values: Array.from({ length: 60 }, (_, i) => (i % 7) * 30 - 40), maxBars: 12 },
+}
+
+/** An empty series renders an empty field rather than collapsing the layout. */
+export const Empty: Story = {
+  args: { values: [] },
+}

package/src/components/custom/charts/SparkBars.test.tsx

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { SparkBars } from './SparkBars'
+
+describe('SparkBars', () => {
+  it('renders one bar per value', () => {
+    render(<SparkBars values={[1, 2, 3, 4]} />)
+    expect(screen.getAllByTestId(/^spark-bars-bar-/)).toHaveLength(4)
+  })
+
+  it('keeps only the last maxBars values', () => {
+    render(<SparkBars values={[1, 2, 3, 4, 5, 6]} maxBars={2} />)
+    expect(screen.getAllByTestId(/^spark-bars-bar-/)).toHaveLength(2)
+  })
+
+  it('renders no bars for an empty series but keeps the field', () => {
+    render(<SparkBars values={[]} />)
+    expect(screen.queryByTestId(/^spark-bars-bar-/)).not.toBeInTheDocument()
+    expect(screen.getByTestId('spark-bars')).toBeInTheDocument()
+  })
+
+  it('tints bars by sign with the result-* tokens', () => {
+    // Asserts the token, not its current value: resolveColor emits the CSS var on
+    // web, which is what keeps the chart theme-correct.
+    render(<SparkBars values={[10, -10]} />)
+    expect(screen.getByTestId('spark-bars-bar-0')).toHaveStyle({
+      backgroundColor: 'var(--color-result-improve)',
+    })
+    expect(screen.getByTestId('spark-bars-bar-1')).toHaveStyle({
+      backgroundColor: 'var(--color-result-degrade)',
+    })
+  })
+
+  it('honours explicit color overrides', () => {
+    render(<SparkBars values={[10, -10]} color="#00ff00" negativeColor="#ff00ff" />)
+    expect(screen.getByTestId('spark-bars-bar-0')).toHaveStyle({
+      backgroundColor: 'rgb(0, 255, 0)',
+    })
+    expect(screen.getByTestId('spark-bars-bar-1')).toHaveStyle({
+      backgroundColor: 'rgb(255, 0, 255)',
+    })
+  })
+
+  it('scales bars on magnitude, so equal-magnitude values are equally tall', () => {
+    render(<SparkBars values={[100, -100, 50]} height={40} />)
+    const [a, b, c] = ['0', '1', '2'].map((i) => screen.getByTestId(`spark-bars-bar-${i}`))
+    expect(a).toHaveStyle({ height: '40px' })
+    expect(b).toHaveStyle({ height: '40px' })
+    expect(c).toHaveStyle({ height: '20px' })
+  })
+
+  it('gives a zero value the minimum bar height rather than collapsing it', () => {
+    render(<SparkBars values={[100, 0]} height={40} />)
+    expect(screen.getByTestId('spark-bars-bar-1')).toHaveStyle({ height: '2px' })
+  })
+
+  it('exposes a default accessible label and accepts an override', () => {
+    const { rerender } = render(<SparkBars values={[1, 2]} />)
+    expect(screen.getByLabelText('Bar sparkline with 2 values')).toBeInTheDocument()
+    rerender(<SparkBars values={[1, 2]} label="Growth for open.ts" />)
+    expect(screen.getByLabelText('Growth for open.ts')).toBeInTheDocument()
+  })
+
+  it('has no a11y violations', async () => {
+    const { container } = render(<SparkBars values={[3, -1, 4]} />)
+    expect(await axe(container)).toHaveNoViolations()
+  })
+})