@titan-design/react-ui 0.12.1 → 0.14.0

package/src/components/custom/Fatigue/panel-layout.ts

@@ -0,0 +1,185 @@
+/**
+ * The {@link LiveFatiguePanel}'s responsive layout, as one pure function (TD-03.58).
+ *
+ * The panel is container-responsive, not prop-sized (SIZE-D01): it measures its own width
+ * in `onLayout` and feeds it here. Everything the two columns need — whether they stack,
+ * the padding, the gap, the card's width, and the split of the ONE body height — comes out
+ * of this one call, so the hero and the card cannot disagree about any of it.
+ *
+ * Pure, with no `react-native` import, so the breakpoint behaviour is unit-testable
+ * without `onLayout` (which never fires under jsdom).
+ *
+ * SOURCED vs CHOSEN. The breakpoint edges are titan's own `primitiveBreakpoints` — not
+ * invented here. The per-tier padding/gap/card numbers below the `md` edge, the `xl`
+ * card-width ratio and its cap, and the stacked height share ARE chosen; each is a single
+ * named constant and each is called out in the PR body.
+ */
+import { primitiveBreakpoints } from '../../../theme/tokens/primitives'
+
+/** titan's breakpoint scale, re-exported as the panel's tier edges. Sourced, not chosen. */
+export const PANEL_BREAKPOINTS = primitiveBreakpoints
+
+export type PanelTier = keyof typeof PANEL_BREAKPOINTS
+
+/**
+ * The `md` edge (1000) is where the two columns fit side by side: the card's own default
+ * 318 plus the hero's usable minimum plus the padding and gap. Below it they stack.
+ */
+const ROW_TIER_MIN = PANEL_BREAKPOINTS.md
+
+/**
+ * The tier for a measured container width. An unmeasured container (0, before the first
+ * `onLayout`) resolves to `md` — today's side-by-side geometry — so the first paint matches
+ * what the panel has always rendered rather than flashing a stacked layout.
+ */
+export function panelTier(width: number): PanelTier {
+  if (width <= 0) return 'md'
+  if (width >= PANEL_BREAKPOINTS.xl) return 'xl'
+  if (width >= PANEL_BREAKPOINTS.lg) return 'lg'
+  if (width >= PANEL_BREAKPOINTS.md) return 'md'
+  if (width >= PANEL_BREAKPOINTS.sm) return 'sm'
+  return 'xs'
+}
+
+/** titan's long-standing card column width, and the floor every wider tier clamps to. */
+export const CARD_WIDTH_BASE = 318
+
+/**
+ * CHOSEN. At wall width a 318px card is ~17% of the content row against ~34% at the `md`
+ * edge, so it reads as a sliver beside the hero. 0.22 pulls it back toward the `md`
+ * proportion without letting the hero lose its lead.
+ */
+export const CARD_WIDTH_XL_RATIO = 0.22
+
+/**
+ * CHOSEN. The cap. The card's internal charts (`RomProgressionChart`, `GhostSpark`) were
+ * drawn around ~318 and go sparse rather than richer past roughly 1.5x that, so the
+ * expansion stops at 460 (reached at 2091px) instead of tracking the container forever.
+ */
+export const CARD_WIDTH_MAX = 460
+
+/**
+ * CHOSEN. Stacked, the CARD takes the larger share of the one body height. Its sections
+ * have hard floors — the verdict hero, the three lights, the ROM chart and the ghost spark —
+ * while the velocity hero is a bar plot that scales continuously, so squeezing the hero
+ * degrades gracefully and squeezing the card overflows it.
+ */
+export const CARD_HEIGHT_SHARE_STACKED = 0.55
+
+/** What the hero reserves above its plot for the `VELOCITY · this set` eyebrow, px. */
+export const HERO_EYEBROW_ALLOWANCE = 26
+
+// --- the card's own height arithmetic ------------------------------------------------
+// It lives here rather than inside LiveFatigueCard so the panel can reason about the card's
+// floor without importing a component (this module stays react-native-free and testable).
+
+/** Floor for the ghost-spark plot inside the card, px. */
+export const CARD_MIN_CHART_HEIGHT = 168
+/** Ceiling for the ghost-spark plot inside the card, px. */
+export const CARD_MAX_CHART_HEIGHT = 240
+/** Share of a pinned card height the ghost-spark plot takes, before the clamp. */
+export const CARD_CHART_HEIGHT_RATIO = 0.4
+/** What an unpinned card gives the ghost-spark plot, px. */
+export const CARD_NATURAL_CHART_HEIGHT = 172
+
+/** The ghost-spark plot height for a card height, or the natural height when unpinned. */
+export function cardChartHeight(cardHeight?: number): number {
+  if (cardHeight == null) return CARD_NATURAL_CHART_HEIGHT
+  const scaled = cardHeight * CARD_CHART_HEIGHT_RATIO
+  return Math.round(Math.min(CARD_MAX_CHART_HEIGHT, Math.max(CARD_MIN_CHART_HEIGHT, scaled)))
+}
+
+/**
+ * MEASURED, not chosen: everything in the card that is not the ghost-spark plot — the 18px
+ * padding top and bottom, the verdict hero, the three lights, the two 16px minimum spacers
+ * and the ROM chart. Taken from the rendered card in Storybook (`scrollHeight` 384 at the
+ * {@link CARD_MIN_CHART_HEIGHT} floor), so a change to those sections needs re-measuring.
+ */
+export const CARD_CHROME_HEIGHT = 216
+
+/**
+ * The shortest a stacked card can be drawn without its content spilling past the rounded
+ * edge. Before this floor existed, an `xs` panel at `bodyHeight` 560 gave the card 301px
+ * against a 384px content height and the ghost spark rendered outside the card.
+ */
+export const CARD_MIN_HEIGHT_STACKED = CARD_CHROME_HEIGHT + CARD_MIN_CHART_HEIGHT
+
+/** Padding and column gap per tier. `md` and up hold today's values exactly. */
+const TIER_SPACING: Record<PanelTier, { padding: number; gap: number }> = {
+  xs: { padding: 16, gap: 12 },
+  sm: { padding: 20, gap: 14 },
+  md: { padding: 24, gap: 18 },
+  lg: { padding: 24, gap: 18 },
+  xl: { padding: 24, gap: 18 },
+}
+
+export interface PanelLayout {
+  tier: PanelTier
+  /** Card below the hero rather than beside it. */
+  stacked: boolean
+  /** Uniform padding around the body row, px. */
+  padding: number
+  /** Gap between the hero and the card, px — column gap when row, row gap when stacked. */
+  gap: number
+  /**
+   * Card width, px. Stacked, this is the full content width, so the card takes a real
+   * number rather than needing a second `onLayout` of its own to size its charts.
+   */
+  cardWidth: number
+}
+
+/** The card column width for a row tier, before any explicit `cardWidth` override. */
+function rowCardWidth(tier: PanelTier, width: number): number {
+  if (tier !== 'xl') return CARD_WIDTH_BASE
+  const fluid = Math.round(width * CARD_WIDTH_XL_RATIO)
+  return Math.min(CARD_WIDTH_MAX, Math.max(CARD_WIDTH_BASE, fluid))
+}
+
+/** The whole layout for a measured container width. */
+export function panelLayout(width: number): PanelLayout {
+  const tier = panelTier(width)
+  const { padding, gap } = TIER_SPACING[tier]
+  const stacked = width > 0 && width < ROW_TIER_MIN
+  const cardWidth = stacked
+    ? Math.max(0, Math.round(width - padding * 2))
+    : rowCardWidth(tier, width)
+  return { tier, stacked, padding, gap, cardWidth }
+}
+
+export interface PanelBodySplit {
+  /** Height handed to the velocity hero's plot, px. */
+  heroHeight: number
+  /** Height handed to the fatigue card, px. */
+  cardHeight: number
+}
+
+/**
+ * CHOSEN. The shortest the velocity plot is still worth drawing. Below this the bars stop
+ * being readable across a room, so the stacked panel grows past `bodyHeight` rather than
+ * flattening the hero any further.
+ */
+export const HERO_MIN_PLOT_HEIGHT = 140
+
+/**
+ * The ONE body height split across the hero and the card (TD-03.60). Side by side both
+ * take the full height; stacked they share it by {@link CARD_HEIGHT_SHARE_STACKED} with the
+ * gap taken out first, and neither drops below its floor. Either way both numbers come from
+ * this one call, so changing `bodyHeight` moves both or neither.
+ */
+export function panelBodySplit(bodyHeight: number, layout: PanelLayout): PanelBodySplit {
+  if (!layout.stacked) {
+    return {
+      heroHeight: Math.max(0, bodyHeight - HERO_EYEBROW_ALLOWANCE),
+      cardHeight: Math.max(0, bodyHeight),
+    }
+  }
+  const usable = Math.max(0, bodyHeight - layout.gap)
+  const cardHeight = Math.max(
+    CARD_MIN_HEIGHT_STACKED,
+    Math.round(usable * CARD_HEIGHT_SHARE_STACKED)
+  )
+  return {
+    heroHeight: Math.max(HERO_MIN_PLOT_HEIGHT, usable - cardHeight - HERO_EYEBROW_ALLOWANCE),
+    cardHeight,
+  }
+}

package/src/components/custom/Gauge/Gauge.stories.tsx

@@ -1,10 +1,13 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { Gauge } from './Gauge'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+
+const t = getSemanticColors('dark')
 
 const meta: Meta<typeof Gauge> = {
-  title: 'Components/DataViz/Gauge',
+  title: 'Custom/Charts/Gauge',
   component: Gauge,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:candidate', '!status:review'],
   argTypes: {
     value: { control: { type: 'range', min: 0, max: 100, step: 1 } },
     size: { control: { type: 'range', min: 100, max: 320, step: 10 } },
@@ -32,7 +35,7 @@ export const ArbitraryDomain: Story = {
 
 /** Single-color override ignores the threshold bands. */
 export const OverrideColor: Story = {
-  args: { value: 55, unit: '%', label: 'Coverage', color: '#5B9BD5', size: 180 },
+  args: { value: 55, unit: '%', label: 'Coverage', color: t['data-7'], size: 180 },
 }
 
 /** Value above max is clamped for the fill but shown verbatim. */

package/src/components/custom/Gauge/Gauge.test.tsx

@@ -50,7 +50,7 @@ describe('Gauge', () => {
           { value: 0, color: '#14B8A6' },
           { value: 50, color: '#D14343' },
         ]}
-      />,
+      />
     )
     expect(screen.getByTestId('gauge-value')).toHaveStyle({ color: '#14B8A6' })
   })

package/src/components/custom/Gauge/Gauge.tsx

@@ -1,6 +1,8 @@
 import { View, Text, type ViewProps } from 'react-native'
 import { cn } from '../../../utils/cn'
 import { getSemanticColors } from '../../../theme/tokens/semantic'
+import { primitiveColors } from '../../../theme/tokens/primitives'
+import { alpha } from '../../../utils/colors'
 
 const sem = getSemanticColors('dark')
 
@@ -36,7 +38,7 @@ export interface GaugeProps extends Omit<ViewProps, 'children'> {
 const STATUS_SUCCESS = sem['status-success']
 const STATUS_WARNING = sem['status-warning']
 const STATUS_ERROR = sem['status-error']
-const TRACK = 'rgba(255,255,255,0.08)'
+const TRACK = alpha(primitiveColors.white, 0.08)
 
 /** Titan status-token bands for a 0–100 score. */
 const DEFAULT_THRESHOLDS: GaugeThreshold[] = [
@@ -152,7 +154,10 @@ export function Gauge({
       ))}
 
       {/* Center readout — Metric visual language. */}
-      <View style={{ position: 'absolute', top: 0, left: 0, width: size, height: size }} className="items-center justify-center">
+      <View
+        style={{ position: 'absolute', top: 0, left: 0, width: size, height: size }}
+        className="items-center justify-center"
+      >
         <View className="flex-row items-baseline gap-0.5">
           <Text testID="gauge-value" className="text-3xl font-bold" style={{ color: displayColor }}>
             {formatValue(value)}

package/src/components/custom/Metric/Metric.stories.tsx

@@ -5,7 +5,16 @@ import { Metric, MetricGroup } from './Metric'
 const meta: Meta<typeof Metric> = {
   title: 'Components/Molecules/Metric',
   component: Metric,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:candidate', '!status:review'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Composes RN primitives only. `MetricGroup` arranges several with a divider rule ' +
+          'between them.',
+      },
+    },
+  },
   argTypes: {
     value: {
       control: 'text',

package/src/components/custom/Metric/Metric.test.tsx

@@ -60,9 +60,7 @@ describe('Metric', () => {
 
   describe('accessibility', () => {
     it('has no accessibility violations', async () => {
-      const { container } = render(
-        <Metric value="42" label="Reps" unit="reps" trend="up" />
-      )
+      const { container } = render(<Metric value="42" label="Reps" unit="reps" trend="up" />)
       const results = await axe(container)
       expect(results).toHaveNoViolations()
     })

package/src/components/custom/Metric/Metric.tsx

@@ -46,18 +46,10 @@ export function Metric({
     <View className={cn('items-center', className)} {...props}>
       <View className="flex-row items-baseline gap-1">
         <Text className={cn(styles.value, 'text-text-primary')}>{value}</Text>
-        {unit && (
-          <Text className={cn(styles.unit, 'text-text-tertiary')}>{unit}</Text>
-        )}
-        {trend && (
-          <Text className={cn(styles.unit, trendColors[trend])}>
-            {trendArrows[trend]}
-          </Text>
-        )}
+        {unit && <Text className={cn(styles.unit, 'text-text-tertiary')}>{unit}</Text>}
+        {trend && <Text className={cn(styles.unit, trendColors[trend])}>{trendArrows[trend]}</Text>}
       </View>
-      <Text className={cn(styles.label, 'text-text-secondary mt-1')}>
-        {label}
-      </Text>
+      <Text className={cn(styles.label, 'text-text-secondary mt-1')}>{label}</Text>
     </View>
   )
 }
@@ -67,11 +59,7 @@ export interface MetricGroupProps extends ViewProps {
   children: React.ReactNode
 }
 
-export function MetricGroup({
-  className,
-  children,
-  ...props
-}: MetricGroupProps) {
+export function MetricGroup({ className, children, ...props }: MetricGroupProps) {
   const items = React.Children.toArray(children)
 
   return (
@@ -80,10 +68,7 @@ export function MetricGroup({
         <React.Fragment key={i}>
           <View className="flex-1 items-center">{child}</View>
           {i < items.length - 1 && (
-            <View
-              className="w-px h-8 bg-divider mx-2"
-              testID="metric-divider"
-            />
+            <View className="w-px h-8 bg-divider mx-2" testID="metric-divider" />
           )}
         </React.Fragment>
       ))}

package/src/components/custom/Prose/MarkdownProse.stories.tsx

@@ -0,0 +1,88 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View } from 'react-native'
+import { MarkdownProse, type ProseLinker } from './MarkdownProse'
+
+const SAMPLE = `# Shipped AW-17 and AW-18
+
+Resolved the cwd to an initiative via the registered worktree, then folded the
+result into [[bootstrap-prompt]]. See #42 for the file-history explorer.
+
+## What changed
+
+- \`active-work open\` now resolves **worktree-registered** cwds first
+- A missing worktree no longer aborts the launch; AW-116 tracks the prune
+- TD-07.14 unified the greys, so the shell planes moved with it
+
+### Follow-ups
+
+Nothing blocks AW-22; the reader is next.`
+
+const TASK_LINKER: ProseLinker = {
+  id: 'task',
+  pattern: /\b[A-Z]{2,}-\d+(?:\.\d+)?\b/,
+  tone: 'brand',
+}
+const WIKI_LINKER: ProseLinker = {
+  id: 'wiki',
+  pattern: /\[\[[^\]]+\]\]/,
+  tone: 'link',
+  label: (ref) => ref.slice(2, -2),
+}
+const PR_LINKER: ProseLinker = { id: 'pr', pattern: /#\d+\b/, tone: 'muted' }
+
+/**
+ * **MarkdownProse** — a small markdown subset (headings, bullets, paragraphs,
+ * bold, code) rendered as themed prose, with caller-described references
+ * auto-linked in one of three tones.
+ *
+ * Composes `Typography`. Used by `SessionDetail` and the initiative reader.
+ */
+const meta: Meta<typeof MarkdownProse> = {
+  title: 'Custom/Prose/MarkdownProse',
+  component: MarkdownProse,
+  tags: ['autodocs', 'status:candidate', '!status:review'],
+  args: {
+    body: SAMPLE,
+    linkers: [TASK_LINKER, WIKI_LINKER, PR_LINKER],
+  },
+  argTypes: {
+    linkers: { table: { disable: true } },
+  },
+  decorators: [
+    (Story) => (
+      <View className="w-full max-w-[640px] p-4">
+        <Story />
+      </View>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Composes **Typography**. Linkers are tried in order; a match renders in its tone and, when the linker carries `onPress`, as a pressable link.',
+      },
+    },
+  },
+}
+export default meta
+
+type Story = StoryObj<typeof MarkdownProse>
+
+/** Task ids in brand, `[[links]]` as links, PR numbers muted. */
+export const Default: Story = {}
+
+/** The same body with no linkers: plain prose. */
+export const NoLinkers: Story = {
+  args: { linkers: [] },
+}
+
+/** Pressable references: each linker carries an `onPress`. */
+export const Pressable: Story = {
+  args: {
+    linkers: [
+      { ...TASK_LINKER, onPress: (id) => console.log('task', id) },
+      { ...WIKI_LINKER, onPress: (name) => console.log('link', name) },
+      { ...PR_LINKER, onPress: (ref) => console.log('pr', ref) },
+    ],
+  },
+}

package/src/components/custom/Prose/MarkdownProse.test.tsx

@@ -0,0 +1,87 @@
+import { describe, it, expect, vi } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { MarkdownProse, parseProseBlocks, type ProseLinker } from './MarkdownProse'
+
+const taskLinker: ProseLinker = { id: 'task', pattern: /\b[A-Z]{2,}-\d+\b/, tone: 'brand' }
+const wikiLinker: ProseLinker = {
+  id: 'wiki',
+  pattern: /\[\[[^\]]+\]\]/,
+  tone: 'link',
+  label: (ref) => ref.slice(2, -2),
+}
+
+describe('parseProseBlocks', () => {
+  it('joins consecutive lines into one paragraph and splits on blank lines', () => {
+    const blocks = parseProseBlocks('one\ntwo\n\nthree')
+    expect(blocks).toEqual([
+      { type: 'p', text: 'one two' },
+      { type: 'p', text: 'three' },
+    ])
+  })
+
+  it('reads headings and bullets, flattening deep headings to h3', () => {
+    const blocks = parseProseBlocks('# Title\n## Section\n#### Deep\n- item\n* other')
+    expect(blocks.map((b) => b.type)).toEqual(['h1', 'h2', 'h3', 'li', 'li'])
+    expect(blocks[2]!.text).toBe('Deep')
+    expect(blocks[4]!.text).toBe('other')
+  })
+
+  it('folds an indented continuation line into the bullet above it', () => {
+    const blocks = parseProseBlocks('- first `code\n  span` continues\nnot indented')
+    expect(blocks).toEqual([
+      { type: 'li', text: 'first `code span` continues' },
+      { type: 'p', text: 'not indented' },
+    ])
+  })
+
+  it('renders nothing for an empty body', () => {
+    expect(parseProseBlocks('')).toEqual([])
+  })
+})
+
+describe('MarkdownProse', () => {
+  it('renders bold and code spans without their markers', () => {
+    render(<MarkdownProse body="a **bold** and `code` span" />)
+    expect(screen.getByText('bold')).toBeInTheDocument()
+    expect(screen.getByText('code')).toBeInTheDocument()
+    expect(screen.queryByText(/\*\*/)).not.toBeInTheDocument()
+  })
+
+  it('auto-links each linker in its tone and applies the label', () => {
+    render(
+      <MarkdownProse body="See AW-22 and [[memory-note]]." linkers={[taskLinker, wikiLinker]} />
+    )
+    expect(screen.getByTestId('prose-ref-task')).toHaveTextContent('AW-22')
+    expect(screen.getByTestId('prose-ref-wiki')).toHaveTextContent('memory-note')
+    expect(screen.queryByText('[[memory-note]]')).not.toBeInTheDocument()
+  })
+
+  it('makes a reference pressable only when its linker has a handler', () => {
+    const onPress = vi.fn()
+    render(
+      <MarkdownProse body="AW-1 then [[note]]" linkers={[{ ...taskLinker, onPress }, wikiLinker]} />
+    )
+    fireEvent.click(screen.getByTestId('prose-ref-task'))
+    expect(onPress).toHaveBeenCalledWith('AW-1')
+    expect(screen.getByTestId('prose-ref-task')).toHaveAttribute('role', 'link')
+    expect(screen.getByTestId('prose-ref-wiki')).not.toHaveAttribute('role')
+  })
+
+  it('lets the first matching linker win when two patterns overlap', () => {
+    const broad: ProseLinker = { id: 'broad', pattern: /\b[A-Z]+-\d+\b/ }
+    render(<MarkdownProse body="AW-9" linkers={[taskLinker, broad]} />)
+    expect(screen.getByTestId('prose-ref-task')).toBeInTheDocument()
+    expect(screen.queryByTestId('prose-ref-broad')).not.toBeInTheDocument()
+  })
+
+  it('has no a11y violations', async () => {
+    const { container } = render(
+      <MarkdownProse
+        body="# Head\n\nBody with AW-3.\n\n- a bullet"
+        linkers={[{ ...taskLinker, onPress: () => {} }]}
+      />
+    )
+    expect(await axe(container)).toHaveNoViolations()
+  })
+})