@titan-design/react-ui 0.12.1 → 0.13.0

package/src/components/custom/ActiveWork/FileActivityRow.tsx

@@ -0,0 +1,130 @@
+// Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
+import { View, Pressable } from 'react-native'
+import { SparkBars } from '../charts'
+import { Typography } from '../Typography'
+import { resolveColor } from '../../../theme/resolve-color'
+import { categoricalPalette } from '../../../theme/tokens/primitives'
+import { FilePathLabel } from './FilePathLabel'
+
+/** Fill per event kind, shared by the row's counts and the detail pane's tiles. */
+export interface FileEventColors {
+  reads: string
+  writes: string
+  edits: string
+}
+
+/**
+ * Reads/writes/edits read as *importance* rather than as peer categories: reads
+ * are cheap and quiet, writes are the consequential ones, edits sit between.
+ */
+export const FILE_EVENT_COLOR_SEMANTIC: FileEventColors = {
+  reads: resolveColor('text-tertiary'),
+  writes: resolveColor('brand-primary'),
+  edits: resolveColor('status-info'),
+}
+
+/**
+ * The same three as *peer categories*, taken in order from the canonical
+ * CVD-safe palette (TOKENS.md §2).
+ */
+export const FILE_EVENT_COLOR_CATEGORICAL: FileEventColors = {
+  reads: categoricalPalette.default[0],
+  writes: categoricalPalette.default[1],
+  edits: categoricalPalette.default[2],
+}
+
+/**
+ * The family default: the three event kinds are peer categories, so they take
+ * the canonical CVD-safe palette in order rather than a hand-picked triple.
+ * Costs three of `CATEGORICAL_CVD_SAFE_MAX` — a view that also plots series
+ * needs to start from index 3, or supply its own `eventColors`.
+ */
+export const FILE_EVENT_COLOR = FILE_EVENT_COLOR_CATEGORICAL
+
+/** Per-file activity mined from session transcripts. */
+export interface FileActivity {
+  /** Repo-relative path. */
+  path: string
+  reads: number
+  writes: number
+  edits: number
+  /** Total events across reads + writes + edits. */
+  touches: number
+  /** Per-session net char delta, oldest first. Drives the sparkline. */
+  timeline: number[]
+}
+
+export interface FileActivityRowProps {
+  file: FileActivity
+  /** Renders the selected treatment (one tone up from the list pane + leading accent bar). */
+  selected?: boolean
+  onSelect?: () => void
+  /** Override the read/write/edit fills. Defaults to {@link FILE_EVENT_COLOR}. */
+  eventColors?: FileEventColors
+}
+
+function EventCount({ value, suffix, color }: { value: number; suffix: string; color: string }) {
+  return (
+    <Typography variant="mono" className="text-xs" style={{ color }}>
+      {`${value}${suffix}`}
+    </Typography>
+  )
+}
+
+/**
+ * FileActivityRow — one file in the ranked "hottest files" list: its path, total
+ * touches, the read/write/edit split, and a sparkline of per-session growth.
+ *
+ * Composes {@link FilePathLabel} and {@link SparkBars}. Used by
+ * {@link FileHistoryExplorer}.
+ */
+export function FileActivityRow({
+  file,
+  selected = false,
+  onSelect,
+  eventColors = FILE_EVENT_COLOR,
+}: FileActivityRowProps) {
+  return (
+    <Pressable
+      onPress={onSelect}
+      // Raw `role`/`aria-selected` rather than `accessibilityState={{ selected }}`:
+      // RNW silently drops the latter, so selection would never reach AT.
+      role="option"
+      aria-selected={selected}
+      accessibilityLabel={`${file.path}, ${file.touches} touches`}
+      testID="file-activity-row"
+      // The row lives inside the lifted list pane (surface-raised), so the selected
+      // fill steps one tone above it. Tone as a state cue; no lift.
+      className={`relative gap-1.5 rounded-md px-3 py-2 ${selected ? 'bg-surface-overlay' : ''}`}
+    >
+      {selected ? (
+        <View
+          testID="file-activity-row-accent"
+          className="absolute bottom-2 left-0 top-2 w-[3px] rounded-r-[3px] bg-brand-primary"
+        />
+      ) : null}
+
+      <View className="flex-row items-center justify-between gap-2.5">
+        <View className="shrink flex-row items-center">
+          <FilePathLabel path={file.path} />
+        </View>
+        <Typography variant="mono" className="text-xs font-bold text-text-secondary">
+          {String(file.touches)}
+        </Typography>
+      </View>
+
+      <View className="flex-row items-center justify-between gap-2.5">
+        <View className="flex-row items-center gap-2">
+          <EventCount value={file.reads} suffix="r" color={eventColors.reads} />
+          <EventCount value={file.writes} suffix="w" color={eventColors.writes} />
+          <EventCount value={file.edits} suffix="e" color={eventColors.edits} />
+        </View>
+        <SparkBars
+          values={file.timeline}
+          height={16}
+          label={`Per-session growth for ${file.path}`}
+        />
+      </View>
+    </Pressable>
+  )
+}

package/src/components/custom/ActiveWork/FileHistoryExplorer.stories.tsx

@@ -0,0 +1,84 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Surface } from '../../ui/surface'
+import { FileHistoryExplorer } from './FileHistoryExplorer'
+import {
+  FILE_HISTORY_CO_EDGES,
+  FILE_HISTORY_FILES,
+  FILE_HISTORY_STATS,
+} from './file-history-fixture'
+
+const meta: Meta<typeof FileHistoryExplorer> = {
+  title: 'Custom/ActiveWork/FileHistoryExplorer',
+  component: FileHistoryExplorer,
+  tags: ['autodocs', 'status:candidate', '!status:review'],
+  decorators: [
+    (Story) => (
+      <Surface level="base" className="min-h-screen p-6" testID="page-surface">
+        <Story />
+      </Surface>
+    ),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          '**Organism.** A file browser ranked by mined activity instead of alphabetised by name: ' +
+          'a KPI strip, a two-pane hottest-files list ⇄ detail, and the repo’s strongest ' +
+          'co-change pairs. The co-change view is the part a plain file tree cannot show. Composes ' +
+          '[Card](?path=/docs/components-molecules-card--docs), ' +
+          '[Tile](?path=/docs/components-atoms-tile--docs), ' +
+          '[Divider](?path=/docs/components-atoms-divider--docs), ' +
+          '[FileActivityRow](?path=/docs/custom-activework-fileactivityrow--docs), ' +
+          '[FileActivityDetail](?path=/docs/custom-activework-fileactivitydetail--docs), ' +
+          '[CoChangeChip](?path=/docs/custom-activework-cochangechip--docs), and ' +
+          '[Eyebrow](?path=/docs/components-molecules-eyebrow--docs). ' +
+          'Presentational only — the caller supplies every prop.',
+      },
+    },
+  },
+  args: {
+    stats: FILE_HISTORY_STATS,
+    files: FILE_HISTORY_FILES,
+    coEdges: FILE_HISTORY_CO_EDGES,
+    provenance:
+      'deterministically mined from Claude Code session transcripts · ranked by total touches',
+  },
+}
+export default meta
+type Story = StoryObj<typeof FileHistoryExplorer>
+
+export const Default: Story = {}
+
+/** Selection is internal by default — pressing a row moves the detail pane. */
+export const NetShrinkSelected: Story = {
+  args: { selectedPath: 'src/utils/fs-atomic.ts' },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'A file that net-*shrank*: negative sparkline bars render in the error token and the ' +
+          'net-change readout flips colour.',
+      },
+    },
+  },
+}
+
+/** No co-change edges mined yet — the bottom strip drops out entirely. */
+export const NoCoChanges: Story = {
+  args: { coEdges: [] },
+}
+
+/** A single file: the ranked list is still a list, and the detail pane fills. */
+export const SingleFile: Story = {
+  args: {
+    files: FILE_HISTORY_FILES.slice(3),
+    coEdges: [],
+    stats: [
+      { label: 'Files', value: '1' },
+      { label: 'File events', value: '55' },
+      { label: 'Sessions', value: '8' },
+      { label: 'Transcripts', value: '11' },
+    ],
+  },
+}

package/src/components/custom/ActiveWork/FileHistoryExplorer.test.tsx

@@ -0,0 +1,99 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { FileHistoryExplorer } from './FileHistoryExplorer'
+import {
+  FILE_HISTORY_CO_EDGES,
+  FILE_HISTORY_FILES,
+  FILE_HISTORY_STATS,
+} from './file-history-fixture'
+
+const base = {
+  stats: FILE_HISTORY_STATS,
+  files: FILE_HISTORY_FILES,
+  coEdges: FILE_HISTORY_CO_EDGES,
+}
+
+describe('FileHistoryExplorer', () => {
+  it('renders a KPI tile per stat', () => {
+    render(<FileHistoryExplorer {...base} />)
+    for (const s of FILE_HISTORY_STATS) {
+      // "Sessions" also appears in the detail pane's growth block, so match loosely.
+      expect(screen.getAllByText(s.label).length).toBeGreaterThan(0)
+    }
+  })
+
+  it('renders the provenance caption only when supplied', () => {
+    const { rerender } = render(<FileHistoryExplorer {...base} />)
+    expect(screen.queryByText('mined deterministically')).not.toBeInTheDocument()
+    rerender(<FileHistoryExplorer {...base} provenance="mined deterministically" />)
+    expect(screen.getByText('mined deterministically')).toBeInTheDocument()
+  })
+
+  it('renders a row per file, capped by maxRows', () => {
+    const { rerender } = render(<FileHistoryExplorer {...base} />)
+    expect(screen.getAllByTestId('file-activity-row')).toHaveLength(4)
+    rerender(<FileHistoryExplorer {...base} maxRows={2} />)
+    expect(screen.getAllByTestId('file-activity-row')).toHaveLength(2)
+  })
+
+  it('selects the first file by default', () => {
+    render(<FileHistoryExplorer {...base} />)
+    const rows = screen.getAllByTestId('file-activity-row')
+    expect(rows[0]).toHaveAttribute('aria-selected', 'true')
+    expect(rows[1]).toHaveAttribute('aria-selected', 'false')
+  })
+
+  it('moves the selection on press when uncontrolled', () => {
+    render(<FileHistoryExplorer {...base} />)
+    fireEvent.click(screen.getAllByTestId('file-activity-row')[1])
+    const rows = screen.getAllByTestId('file-activity-row')
+    expect(rows[0]).toHaveAttribute('aria-selected', 'false')
+    expect(rows[1]).toHaveAttribute('aria-selected', 'true')
+  })
+
+  it('honours selectedPath and does not self-update when controlled', () => {
+    const onSelectFile = vi.fn()
+    render(
+      <FileHistoryExplorer
+        {...base}
+        selectedPath="src/utils/fs-atomic.ts"
+        onSelectFile={onSelectFile}
+      />
+    )
+    expect(screen.getAllByTestId('file-activity-row')[2]).toHaveAttribute('aria-selected', 'true')
+
+    fireEvent.click(screen.getAllByTestId('file-activity-row')[0])
+    expect(onSelectFile).toHaveBeenCalledWith('src/commands/open.ts')
+    expect(screen.getAllByTestId('file-activity-row')[2]).toHaveAttribute('aria-selected', 'true')
+  })
+
+  it('falls back to the first file when selectedPath matches nothing', () => {
+    render(<FileHistoryExplorer {...base} selectedPath="does/not/exist.ts" />)
+    expect(screen.getAllByTestId('file-activity-row')[0]).toHaveAttribute('aria-selected', 'true')
+  })
+
+  it('renders a co-change chip per edge, capped by maxCoEdges', () => {
+    const { rerender } = render(<FileHistoryExplorer {...base} />)
+    expect(screen.getAllByTestId('co-change-chip')).toHaveLength(4)
+    rerender(<FileHistoryExplorer {...base} maxCoEdges={2} />)
+    expect(screen.getAllByTestId('co-change-chip')).toHaveLength(2)
+  })
+
+  it('drops the co-change strip entirely when there are no edges', () => {
+    render(<FileHistoryExplorer {...base} coEdges={[]} />)
+    expect(screen.queryByTestId('co-change-chip')).not.toBeInTheDocument()
+    expect(screen.queryByText('Strongest co-changes across the repo')).not.toBeInTheDocument()
+  })
+
+  it('renders no detail pane when there are no files', () => {
+    render(<FileHistoryExplorer {...base} files={[]} coEdges={[]} />)
+    expect(screen.queryByTestId('file-activity-detail')).not.toBeInTheDocument()
+    expect(screen.getByTestId('file-history-explorer')).toBeInTheDocument()
+  })
+
+  it('has no a11y violations', async () => {
+    const { container } = render(<FileHistoryExplorer {...base} />)
+    expect(await axe(container)).toHaveNoViolations()
+  })
+})

package/src/components/custom/ActiveWork/FileHistoryExplorer.tsx

@@ -0,0 +1,138 @@
+// Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
+import { useState } from 'react'
+import { View, type ViewProps } from 'react-native'
+import { Card } from '../../ui/card'
+import { Divider } from '../../ui/divider'
+import { Tile } from '../../ui/tile'
+import { Typography } from '../Typography'
+import { Eyebrow } from './Eyebrow'
+import { CoChangeChip } from './CoChangeChip'
+import { FileActivityRow } from './FileActivityRow'
+import { FileActivityDetail, type FileActivityDetailData } from './FileActivityDetail'
+
+/**
+ * React Native's `Role` union has `'option'` but omits `'listbox'`, even though
+ * RNW passes it straight through to the DOM. Cast once here rather than drop
+ * the ARIA parent that makes the option rows valid.
+ */
+const LISTBOX_ROLE = 'listbox' as ViewProps['role']
+
+/** A KPI shown in the strip above the explorer. */
+export interface FileHistoryStat {
+  label: string
+  value: string
+}
+
+/** A repo-wide co-change pair, strongest first. */
+export interface CoChangeEdge {
+  a: string
+  b: string
+  count: number
+}
+
+export interface FileHistoryExplorerProps extends ViewProps {
+  /** KPI tiles, e.g. Files / File events / Sessions / Transcripts. */
+  stats: FileHistoryStat[]
+  /** Files for the ranked list, already sorted (typically by descending touches). */
+  files: FileActivityDetailData[]
+  /** Repo-wide co-change pairs, already sorted by descending count. */
+  coEdges?: CoChangeEdge[]
+  /** Caption under the KPI strip explaining where the numbers came from. */
+  provenance?: string
+  /** Cap on ranked rows rendered. */
+  maxRows?: number
+  /** Cap on co-change chips rendered. */
+  maxCoEdges?: number
+  /** Selected file path. Omit to let the explorer manage selection itself. */
+  selectedPath?: string
+  /** Fires on row press. Required for the selection to move when `selectedPath` is set. */
+  onSelectFile?: (path: string) => void
+  className?: string
+}
+
+/**
+ * FileHistoryExplorer — a file browser ranked by mined activity instead of
+ * alphabetised by name: a KPI strip, a two-pane hottest-files list ⇄ detail,
+ * and the repo's strongest co-change pairs.
+ *
+ * Composes Card / Tile / Divider plus {@link FileActivityRow},
+ * {@link FileActivityDetail}, {@link CoChangeChip} and {@link Eyebrow}.
+ * Selection is controlled when `selectedPath` is supplied and internal
+ * otherwise.
+ *
+ * Data plan: presentational only — no fetch or store dependency. The caller
+ * derives `stats`, `files` and `coEdges` from its own source of truth (the
+ * active-work session-history miner). Wiring that export to these props is a
+ * caller-side concern and the integration's only open gap; a shared adapter is
+ * deliberately out of scope for this unit.
+ */
+export function FileHistoryExplorer({
+  stats,
+  files,
+  coEdges = [],
+  provenance,
+  maxRows = 30,
+  maxCoEdges = 8,
+  selectedPath,
+  onSelectFile,
+  className,
+  ...props
+}: FileHistoryExplorerProps) {
+  const [internalPath, setInternalPath] = useState<string | undefined>(files[0]?.path)
+  const activePath = selectedPath ?? internalPath
+  const selected = files.find((f) => f.path === activePath) ?? files[0]
+
+  const select = (path: string) => {
+    if (selectedPath === undefined) setInternalPath(path)
+    onSelectFile?.(path)
+  }
+
+  return (
+    <View className={`gap-3.5 ${className ?? ''}`} testID="file-history-explorer" {...props}>
+      <View className="gap-1.5">
+        <View className="flex-row flex-wrap gap-2.5">
+          {stats.map((s) => (
+            <Tile key={s.label} label={s.label} value={s.value} className="min-w-[130px]" />
+          ))}
+        </View>
+        {provenance ? (
+          <Typography variant="caption" className="text-xs text-text-tertiary">
+            {provenance}
+          </Typography>
+        ) : null}
+      </View>
+
+      <View className="flex-row gap-3.5">
+        <Card className="w-[420px] p-2" testID="file-list-pane">
+          <View className="px-2.5 pb-1.5 pt-1">
+            <Eyebrow>Hottest files</Eyebrow>
+          </View>
+          <Divider />
+          <View className="pt-1" role={LISTBOX_ROLE} aria-label="Hottest files">
+            {files.slice(0, maxRows).map((f) => (
+              <FileActivityRow
+                key={f.path}
+                file={f}
+                selected={f.path === selected?.path}
+                onSelect={() => select(f.path)}
+              />
+            ))}
+          </View>
+        </Card>
+
+        {selected ? <FileActivityDetail file={selected} /> : null}
+      </View>
+
+      {coEdges.length ? (
+        <View className="gap-2">
+          <Eyebrow>Strongest co-changes across the repo</Eyebrow>
+          <View className="flex-row flex-wrap gap-2">
+            {coEdges.slice(0, maxCoEdges).map((e) => (
+              <CoChangeChip key={`${e.a}|${e.b}`} a={e.a} b={e.b} count={e.count} />
+            ))}
+          </View>
+        </View>
+      ) : null}
+    </View>
+  )
+}

package/src/components/custom/ActiveWork/FilePathLabel.stories.tsx

@@ -0,0 +1,39 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { FilePathLabel } from './FilePathLabel'
+
+const meta: Meta<typeof FilePathLabel> = {
+  title: 'Custom/ActiveWork/FilePathLabel',
+  component: FilePathLabel,
+  tags: ['autodocs', 'status:candidate', '!status:review'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '**Molecule.** A file path with the directory dimmed and the basename bright — in a list ' +
+          'of paths the basename is the identifier and the directory is disambiguation, so they get ' +
+          'different weight rather than one flat string. Composes ' +
+          "[Typography](?path=/docs/foundations-typography--docs)'s `mono` variant.",
+      },
+    },
+  },
+  args: { path: 'src/commands/_open-helpers.ts', size: 'md', baseOnly: false },
+}
+export default meta
+type Story = StoryObj<typeof FilePathLabel>
+
+export const Default: Story = {}
+
+/** A bare filename has no directory to dim. */
+export const NoDirectory: Story = {
+  args: { path: 'README.md' },
+}
+
+/** `baseOnly` drops the directory — used at chip size where the prefix is noise. */
+export const BaseOnly: Story = {
+  args: { baseOnly: true },
+}
+
+/** The dense variant, as used inside CoChangeChip and the co-change list. */
+export const Small: Story = {
+  args: { size: 'sm' },
+}

package/src/components/custom/ActiveWork/FilePathLabel.test.tsx

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { FilePathLabel, splitPath } from './FilePathLabel'
+
+describe('splitPath', () => {
+  it('splits a nested path into a trailing-slash dir and a basename', () => {
+    expect(splitPath('src/commands/open.ts')).toEqual({
+      dir: 'src/commands/',
+      base: 'open.ts',
+    })
+  })
+
+  it('returns an empty dir for a bare filename', () => {
+    expect(splitPath('README.md')).toEqual({ dir: '', base: 'README.md' })
+  })
+})
+
+describe('FilePathLabel', () => {
+  it('renders the directory and the basename as separate elements', () => {
+    render(<FilePathLabel path="src/commands/open.ts" />)
+    expect(screen.getByText('src/commands/')).toBeInTheDocument()
+    expect(screen.getByText('open.ts')).toBeInTheDocument()
+  })
+
+  it('omits the directory element for a bare filename', () => {
+    render(<FilePathLabel path="README.md" />)
+    expect(screen.getByText('README.md')).toBeInTheDocument()
+    expect(screen.queryByText('/')).not.toBeInTheDocument()
+  })
+
+  it('drops the directory when baseOnly is set', () => {
+    render(<FilePathLabel path="src/commands/open.ts" baseOnly />)
+    expect(screen.queryByText('src/commands/')).not.toBeInTheDocument()
+    expect(screen.getByText('open.ts')).toBeInTheDocument()
+  })
+
+  // The dir/base size difference now comes from `text-xs` / `text-sm` classes, and
+  // nativewind does not compile classNames in the vitest env — so the rendered size
+  // is not observable here. Asserting it would mean asserting nothing. Left to
+  // visual regression (see the family README's testing follow-up); what remains
+  // testable is that both sizes render their parts.
+  it.each(['sm', 'md'] as const)('renders both parts at size %s', (size) => {
+    render(<FilePathLabel path="src/open.ts" size={size} />)
+    expect(screen.getByText('src/')).toBeInTheDocument()
+    expect(screen.getByText('open.ts')).toBeInTheDocument()
+  })
+
+  it('has no a11y violations', async () => {
+    const { container } = render(<FilePathLabel path="src/commands/open.ts" />)
+    expect(await axe(container)).toHaveNoViolations()
+  })
+})

package/src/components/custom/ActiveWork/FilePathLabel.tsx

@@ -0,0 +1,63 @@
+// Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
+import { View, type ViewProps } from 'react-native'
+import { cn } from '../../../utils/cn'
+import { Typography } from '../Typography'
+
+/** Split a path into its directory prefix (trailing slash kept) and basename. */
+export function splitPath(path: string): { dir: string; base: string } {
+  const i = path.lastIndexOf('/')
+  return i === -1 ? { dir: '', base: path } : { dir: path.slice(0, i + 1), base: path.slice(i + 1) }
+}
+
+/** Basename size on the type scale, with the directory one step quieter. */
+export type FilePathLabelSize = 'sm' | 'md'
+
+const SIZE_CLASS: Record<FilePathLabelSize, { base: string; dir: string }> = {
+  sm: { base: 'text-xs', dir: 'text-xs' },
+  md: { base: 'text-sm', dir: 'text-xs' },
+}
+
+export interface FilePathLabelProps extends ViewProps {
+  /** A repo-relative path, e.g. `src/commands/open.ts`. */
+  path: string
+  /** `md` for standalone rows, `sm` for dense contexts like chips. */
+  size?: FilePathLabelSize
+  /** Render only the basename, dropping the directory prefix. */
+  baseOnly?: boolean
+  className?: string
+}
+
+/**
+ * FilePathLabel — a file path with the directory dimmed and the basename bright.
+ *
+ * In a list of paths the basename is the identifier and the directory is
+ * disambiguation, so they get different weight rather than one flat string. The
+ * directory shrinks first under width pressure; the basename never truncates.
+ */
+export function FilePathLabel({
+  path,
+  size = 'md',
+  baseOnly = false,
+  className,
+  ...props
+}: FilePathLabelProps) {
+  const { dir, base } = splitPath(path)
+  const cls = SIZE_CLASS[size]
+
+  return (
+    <View className={cn('flex-row items-center', className)} {...props}>
+      {dir && !baseOnly ? (
+        <Typography
+          variant="mono"
+          numberOfLines={1}
+          className={cn('shrink text-text-tertiary', cls.dir)}
+        >
+          {dir}
+        </Typography>
+      ) : null}
+      <Typography variant="mono" className={cn('text-text-primary', cls.base)}>
+        {base}
+      </Typography>
+    </View>
+  )
+}

package/src/components/custom/ActiveWork/InitiativeBrief.stories.tsx

@@ -0,0 +1,50 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Card } from '../../ui/card'
+import { Surface } from '../../ui/surface'
+import { InitiativeBrief } from './InitiativeBrief'
+import { sessionLinkers } from './session-linkers'
+import { INITIATIVE_BRIEF_FIXTURE } from './initiative-fixture'
+
+/**
+ * **InitiativeBrief** — a brief's prose, each `##` section a collapsible block
+ * with the first open, references auto-linked.
+ *
+ * Composes `Collapse` · `Eyebrow` · `MarkdownProse` · `Typography`.
+ */
+const meta: Meta<typeof InitiativeBrief> = {
+  title: 'Custom/ActiveWork/InitiativeBrief',
+  component: InitiativeBrief,
+  tags: ['autodocs', 'status:candidate', '!status:review'],
+  args: {
+    brief: INITIATIVE_BRIEF_FIXTURE,
+    linkers: sessionLinkers(),
+  },
+  argTypes: {
+    brief: { table: { disable: true } },
+    linkers: { table: { disable: true } },
+  },
+  decorators: [
+    (Story) => (
+      <Surface level="base" className="min-h-screen w-full max-w-[560px] p-6" testID="page-surface">
+        <Card className="gap-1 p-4">
+          <Story />
+        </Card>
+      </Surface>
+    ),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Composes **Collapse** · **Eyebrow** · **MarkdownProse** · **Typography**. Used-by ↑ the Initiative Reader composition.',
+      },
+    },
+  },
+}
+export default meta
+
+type Story = StoryObj<typeof InitiativeBrief>
+
+/** The active-work brief, its sections collapsible. */
+export const Default: Story = {}