storybook-stories

name	storybook-stories
description	Write Storybook stories for PostHog UI components. Covers the provider stack stories run inside, the key gotcha that tRPC/useHostTRPC queries never resolve in Storybook (so data-fetching components render empty), and the pure-presentational split that makes a component storyable. Use when adding or fixing a *.stories.tsx file under packages/ui.

Storybook stories in PostHog

Stories live next to components as *.stories.tsx and are collected by apps/code/.storybook/main.ts (its glob includes packages/ui/src/**/*.stories.tsx). Run/build:

pnpm --filter code storybook        # dev server on :6006
pnpm --filter code build-storybook  # static build (also a good CI/typecheck gate)

Every story is already wrapped (don't re-wrap)

apps/code/.storybook/preview.tsx applies two global decorators, so a story should not add its own providers or <Theme>:

• withAppProviders — a QueryClient, the host tRPC context, a DI ServiceProvider, and a minimal TanStack Router. So useHostTRPC(), useService(), useRouterState(), etc. render instead of throwing "must be used within a Provider".
• A <Theme> (Radix) bound to the dark/light toolbar global.

Add a per-story decorator only to constrain layout (e.g. wrap in a maxWidth div so a full-width component sizes realistically).

The gotcha: data never arrives in Storybook

This is the thing that wastes time. In withAppProviders the tRPC ipcLink is a no-op (apps/code/.storybook/mocks/electron-trpc.ts), so:

• Any query issued through useHostTRPC() (and hooks built on it, like useClaudeCliSessions) stays pending forever — query.data is undefined, permanently.
• useService(TOKEN) returns an inert proxy stub for anything not explicitly bound (service.foo().bar never throws, but calls are no-ops). Only a few tokens resolve for real: HOST_TRPC_CLIENT (a no-op client with a handful of stubbed methods), IMPERATIVE_QUERY_CLIENT, DIFF_WORKER_FACTORY.

So a component that fetches its own data renders its empty/loading branch in Storybook — frequently null. Storying it directly shows nothing.

The fix: split a pure presentational component

Separate the data/wiring from the rendering, and story the pure part — which also satisfies the repo rule "components render; hooks wrap exactly one query" (AGENTS.md). Keep both in the same file:

// Pure — takes data + handlers as props. This is what the story targets.
export function WidgetList({ items, onPick }: WidgetListProps) { … }

// Container — does the tRPC/useService wiring, renders <WidgetList/>.
export function Widget({ repoPath }: WidgetProps) {
  const { data } = useSomeQuery(repoPath);
  return <WidgetList items={data?.items ?? []} onPick={…} />;
}

Then each story is just args for WidgetList — one per visual state (empty, single, over-limit, in-flight/disabled, fallback text, …). Real example: packages/ui/src/features/task-detail/components/ContinueCliSessions.tsx + .stories.tsx.

Filtering/branching that lives in the container (not the pure view) isn't exercised by these visual stories — cover it with a small unit test if it's worth pinning.

Conventions

• title groups in the sidebar, e.g. "Task Detail/ContinueCliSessions".
• Build fixtures with a small factory (session(overrides)) rather than repeating object literals across stories.
• Date.now()/new Date() are fine in stories, but fixed ISO strings keep relative-time output stable enough for visual review.
• Typecheck covers stories (they're .tsx under the package); a build-storybook additionally catches Storybook-specific breakage.