chore(template): clean-slate template snapshot from bb4a0c7

Curated, product-agnostic snapshot of the post-story-04 tree: demo content deleted, auth-only reference feature, web-next shell, all gates green. Product-specific docs, ADRs 027-029, PRDs/epics/archive, editor library traces, and product naming are curated out; generic template repairs (coverage provider devDeps, root test:coverage script, live lint fixes, root-only release-please) are kept. See TEMPLATE.md for provenance, curation list, and usage. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016j8z4VHjedXDTjEDNg7qHK
2026-07-12 20:40:54 +02:00
commit f77e6ea881
1062 changed files with 105156 additions and 0 deletions
--- a/docs/guides/building-feature-ui.md
+++ b/docs/guides/building-feature-ui.md
@@ -0,0 +1,498 @@
+# Building Feature UI — Components, Hooks & Data Fetching
+
+Each feature owns its UI layer inside `src/ui/`. This guide covers how to
+create React components that fetch their own data via tRPC + React Query,
+how to wire them into Next.js and TanStack Start apps, and how the server
+prefetch + client hydration pattern works.
+
+> **Prerequisites:** `@repo/core-trpc` must be scaffolded
+> (`pnpm turbo gen core-package trpc`). The tRPC providers must be wired
+> into the app's root layout (see [App wiring](#app-wiring) below).
+
+---
+
+## Feature `src/ui/` folder structure
+
+```
+packages/<feature>/src/ui/
+  index.ts                        # Barrel — re-exports server components as public API
+  query.ts                        # Query builder functions (framework-agnostic)
+  hooks/
+    use-<entity>.ts               # "use client" hooks wrapping tRPC + useSuspenseQuery
+    use-<entity>-list.ts
+  components/
+    <entity>-card.tsx             # Presentational (receives props, no hooks)
+    <entity>-list.server.tsx      # Server component — DI + prefetch + HydrationBoundary
+    <entity>-list.client.tsx      # "use client" — calls hook, owns rendering
+    <entity>-detail.server.tsx
+    <entity>-detail.client.tsx
+```
+
+### Naming convention
+
+| File suffix        | Directive                    | Role                                                                                 | Exported from barrel?                                                        |
+| ------------------ | ---------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| `.server.tsx`      | _(none — server by default)_ | Resolves controller from DI, prefetches data, wraps `.client` in `HydrationBoundary` | **Yes** — under the clean name (e.g. `ArticleList`)                          |
+| `.client.tsx`      | `"use client"`               | Calls hooks, renders UI                                                              | **No** — internal to the feature; only imported by its `.server` counterpart |
+| `.tsx` (no suffix) | _(none)_                     | Presentational — receives data via props, no hooks                                   | Yes, if useful standalone (e.g. `ArticleCard`)                               |
+
+The **server component is the public face** — the barrel exports it under
+the clean component name (`ArticleList`, `ArticleDetail`, `PageContent`).
+The `.client.tsx` suffix signals "internal, not for direct consumption" —
+consumers never see it.
+
+### Component roles
+
+- **Server components** (`.server.tsx`) — resolve the controller from the
+  feature's DI container, call it to prefetch data, seed the React Query
+  cache via `setQueryData`, and wrap the client component in
+  `HydrationBoundary`. This gives SSR + instant hydration.
+- **Client components** (`.client.tsx`) — `"use client"`. Call hooks from
+  `hooks/` to get data via `useSuspenseQuery`. Handle rendering + interactivity.
+  Never imported by app pages directly.
+- **Hooks** (`hooks/`) — own data fetching; one hook per query.
+  Always `"use client"`. Import `useTRPC` from `@repo/core-trpc` and
+  `useSuspenseQuery` from `@tanstack/react-query`.
+- **Presentational components** (`.tsx`, no suffix) — receive data via props.
+  No `"use client"` unless they need browser APIs. Can be shared by
+  multiple client components.
+
+---
+
+## Component composition & `@repo/core-ui` reuse
+
+Feature components **must** reuse primitives from `@repo/core-ui` rather
+than hand-rolling HTML with raw Tailwind classes. `core-ui` follows
+**Atomic Design**:
+
+| Tier          | Location                 | Examples                            | Rule                                          |
+| ------------- | ------------------------ | ----------------------------------- | --------------------------------------------- |
+| **Atoms**     | `core-ui/src/atoms/`     | `Button`, `Input`, `Label`          | Smallest building blocks. No business logic.  |
+| **Molecules** | `core-ui/src/molecules/` | `FormField` (Label + Input + error) | Compose atoms. Still generic.                 |
+| **Organisms** | `core-ui/src/organisms/` | `CookieConsentBanner`               | Compose molecules/atoms. May own local state. |
+| **Templates** | `core-ui/src/templates/` | Page shells, layout grids           | Structural — define slots, no data.           |
+
+**Import direction is strictly upward:** atoms never import molecules;
+molecules never import organisms. The ESLint rule
+`atomic-tier-import-direction` enforces this.
+
+### Where feature components fit
+
+Feature components are **consumers** of core-ui, not replacements.
+They sit above the atomic tiers:
+
+```
+App page (imports feature component, passes route props)
+  └── Feature server component (.server.tsx — DI + prefetch + HydrationBoundary)
+        └── Feature client component (.client.tsx — "use client", calls hook)
+              └── Feature presentational component (receives props)
+                    └── core-ui atoms/molecules (Button, Input, FormField, ...)
+```
+
+**Guidelines:**
+
+- **Always check `core-ui` first.** Before creating a `<Card>` or
+  `<Badge>` in a feature, check if `core-ui` already exports it. Use
+  Storybook (`pnpm dev --filter @repo/storybook`) or the barrel at
+  `packages/core-ui/src/index.ts`.
+- **If a primitive is missing, add it to `core-ui`** — not to the
+  feature. Scaffold via `pnpm turbo gen core-ui-component`. Feature
+  packages should not contain generic UI primitives.
+- **Feature components compose, not duplicate.** A feature's
+  `<ArticleCard>` should render a `core-ui` `<Card>` (when it exists)
+  with feature-specific content inside — not re-implement card styling.
+- **Tailwind utility classes are fine** for layout and spacing within
+  feature components (flex, grid, padding, margin). But visual
+  primitives (buttons, inputs, badges, cards) come from `core-ui`.
+
+### Adding `core-ui` as a dependency
+
+Feature packages that use core-ui atoms need:
+
+```jsonc
+// package.json
+"dependencies": {
+  "@repo/core-ui": "workspace:*"
+}
+```
+
+---
+
+## Step 1: Create a hook
+
+Hooks live in `src/ui/hooks/` and wrap a single tRPC query:
+
+```typescript
+// packages/blog/src/ui/hooks/use-article-list.ts
+"use client";
+
+import { useSuspenseQuery } from "@tanstack/react-query";
+import { useTRPC } from "@repo/core-trpc";
+import type { Article } from "../../entities/models/article";
+
+export function useArticleList(options?: {
+  status?: "draft" | "published";
+  limit?: number;
+}) {
+  const trpc = useTRPC();
+  return useSuspenseQuery(
+    trpc.blog.listArticles.queryOptions({
+      status: options?.status ?? "published",
+      limit: options?.limit ?? 20,
+    }),
+  ) as { data: Article[] };
+}
+```
+
+> **TS2742 workaround:** Feature packages set `declaration: true` (from
+> the base tsconfig). The `as { data: T }` cast avoids a non-portable
+> return type error caused by `@trpc/client` resolving to different
+> `.pnpm` paths per package.
+
+### Dependencies
+
+Feature packages that have hooks need these dependencies:
+
+```jsonc
+// package.json
+"dependencies": {
+  "@repo/core-trpc": "workspace:*",
+  "@tanstack/react-query": "^5.66.0",
+  "@trpc/client": "^11.17.0",  // for type portability
+  "react": "^19.0.0"
+}
+```
+
+---
+
+## Step 2: Create components
+
+### Server component (public face)
+
+The server component resolves the controller from DI, prefetches, and
+wraps the client component in `HydrationBoundary`:
+
+```typescript
+// packages/blog/src/ui/components/article-list.server.tsx
+import { dehydrate, HydrationBoundary } from "@tanstack/react-query";
+import { getQueryClient } from "@repo/core-trpc";
+import { blogContainer } from "../../di/container";
+import { BLOG_SYMBOLS } from "../../di/symbols";
+import type { IGetArticlesController } from "../../interface-adapters/controllers/get-articles.controller";
+import { ArticleList as ArticleListClient } from "./article-list.client";
+
+export async function ArticleList() {
+  const controller = blogContainer.get<IGetArticlesController>(
+    BLOG_SYMBOLS.IGetArticlesController,
+  );
+  const articles = await controller({ status: "published", limit: 20 });
+  const queryClient = getQueryClient();
+  queryClient.setQueryData(
+    ["blog", "listArticles", { input: { status: "published", limit: 20 } }],
+    articles,
+  );
+
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <ArticleListClient />
+    </HydrationBoundary>
+  );
+}
+```
+
+### Client component (internal)
+
+```typescript
+// packages/blog/src/ui/components/article-list.client.tsx
+"use client";
+
+import { useArticleList } from "../hooks/use-article-list";
+import { ArticleCard } from "./article-card";
+
+export function ArticleList() {
+  const { data: articles } = useArticleList();
+
+  if (articles.length === 0) {
+    return <p className="text-muted-foreground">No articles yet.</p>;
+  }
+
+  return (
+    <div className="grid gap-4">
+      {articles.map((article) => (
+        <ArticleCard key={article.id} article={article} />
+      ))}
+    </div>
+  );
+}
+```
+
+### Presentational component (receives props)
+
+```typescript
+// packages/blog/src/ui/components/article-card.tsx
+import type { Article } from "../../entities/models/article";
+
+export type ArticleCardProps = { article: Article };
+
+export function ArticleCard({ article }: ArticleCardProps) {
+  return (
+    <article className="rounded-lg border border-border bg-card p-4">
+      <a href={`/blog/${article.slug}`}>
+        <h3 className="text-lg font-semibold">{article.title}</h3>
+      </a>
+      <time className="text-sm text-muted-foreground"
+        dateTime={article.createdAt.toISOString()}>
+        {article.createdAt.toLocaleDateString()}
+      </time>
+    </article>
+  );
+}
+```
+
+> **No `renderLink` props.** Client components are `"use client"` —
+> functions cannot be passed from server components. Use plain `<a>` tags
+> or import the framework's Link component directly if the feature has
+> that framework as a dependency.
+
+---
+
+## Step 3: Export from the barrel
+
+The barrel exports **server components** under clean names. Client
+components are internal — never re-exported:
+
+```typescript
+// packages/blog/src/ui/index.ts
+export { articleBySlugQuery, listArticlesQuery } from "./query";
+export { useArticleList } from "./hooks/use-article-list";
+export { useArticleBySlug } from "./hooks/use-article-by-slug";
+export { ArticleCard, type ArticleCardProps } from "./components/article-card";
+export { ArticleList } from "./components/article-list.server";
+export { ArticleDetail } from "./components/article-detail.server";
+```
+
+Apps import from `@repo/<feature>/ui` — they get the server component
+which handles prefetch + hydration internally:
+
+```typescript
+import { ArticleList } from "@repo/blog/ui";
+import { SiteHeader } from "@repo/navigation/ui";
+```
+
+---
+
+## App wiring
+
+### Next.js (`apps/web-next`)
+
+#### Root layout — DI + providers
+
+`bindAll()` runs once in the root layout. `NextTrpcProvider` wraps all
+pages with the tRPC client and React Query.
+
+```typescript
+// apps/web-next/src/app/layout.tsx
+import { bindAll } from "../server/bind-production";
+import { Providers } from "./providers";
+
+export default async function RootLayout({ children }) {
+  await bindAll();
+  return (
+    <html lang="en">
+      <body><Providers>{children}</Providers></body>
+    </html>
+  );
+}
+```
+
+```typescript
+// apps/web-next/src/app/providers.tsx
+"use client";
+import { NextTrpcProvider } from "@repo/core-trpc/next";
+
+export function Providers({ children }) {
+  return <NextTrpcProvider>{children}</NextTrpcProvider>;
+}
+```
+
+#### Pages — just import and render
+
+Feature server components handle prefetch + hydration internally. App
+pages are thin — they import the component and pass route-derived props
+(slug, id, etc.). No `appRouter`, no `queryClient`, no `HydrationBoundary`
+in the app layer:
+
+```typescript
+// apps/web-next/src/app/page.tsx
+import { ArticleList } from "@repo/blog/ui";
+
+export default function Home() {
+  return <ArticleList />;
+}
+```
+
+```typescript
+// apps/web-next/src/app/blog/[slug]/page.tsx
+import { ArticleDetail } from "@repo/blog/ui";
+
+export default async function BlogPostPage({ params }) {
+  const { slug } = await params;
+  return <ArticleDetail slug={slug} />;
+}
+```
+
+The server component inside the feature resolves its controller from DI,
+prefetches data, seeds the query cache, and wraps the client component
+in `HydrationBoundary`. This gives:
+
+- Full HTML on first paint (SSR)
+- Instant hydration (no loading flash)
+- Background refetch on the client via `/api/trpc`
+
+> **Cache key format:** tRPC generates keys as
+> `[routerName, procedureName, { input }]`. The `setQueryData` key in the
+> server component must match what the client hook's `queryOptions`
+> generates, or the client will re-fetch instead of hydrating.
+
+#### tRPC HTTP endpoint
+
+Client-side queries hit `/api/trpc` after hydration:
+
+```typescript
+// apps/web-next/src/app/api/trpc/[trpc]/route.ts
+import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
+import { appRouter } from "@repo/core-api";
+
+const handler = async (req: Request) =>
+  fetchRequestHandler({
+    endpoint: "/api/trpc",
+    req,
+    router: appRouter,
+    createContext: () => ({}),
+  });
+
+export { handler as GET, handler as POST };
+```
+
+### TanStack Start (`apps/web-tanstack`)
+
+Same pattern but with `TanstackTrpcProvider` from `@repo/core-trpc/tanstack`
+in the root route, and TanStack Router loaders for server prefetch.
+
+---
+
+## Tailwind CSS in the apps
+
+Both apps and Storybook need their own CSS entry point because Tailwind v4
+scans for utility classes only in files it knows about. Monorepo packages
+live outside the app directory, so `@source` directives are required.
+
+```css
+/* apps/web-next/src/styles/app.css */
+@import "tailwindcss";
+@source "../../../../packages/core-ui/src";
+@source "../../../../packages/navigation/src";
+@source "../../../../packages/blog/src";
+/* ... all feature packages with UI components */
+
+@import "../../../../packages/core-ui/src/styles/theme.css";
+```
+
+- **Next.js** uses `@tailwindcss/postcss` via `postcss.config.mjs`
+- **Storybook** uses `@tailwindcss/vite` prepended in `viteFinal`
+- **Theme tokens** live in `packages/core-ui/src/styles/theme.css` (single
+  source of truth). Both `globals.css` and app CSS files import it.
+
+---
+
+## Seed data & DI binding
+
+### Dev seed (`USE_DEV_SEED=true` or default in development)
+
+Each feature has `src/__seeds__/dev.ts` that builds realistic mock data
+using factories from `src/__factories__/`. The dev-seed binder
+(`src/di/bind-dev-seed.ts`) populates the mock repository with this data.
+
+```typescript
+// packages/blog/src/__seeds__/dev.ts
+import { articleFactory } from "../__factories__/article.factory";
+
+export function buildDevArticles(): Article[] {
+  return [
+    articleFactory.build({
+      slug: "hello-world",
+      title: "Hello World",
+      status: "published",
+    }),
+    articleFactory.build({
+      slug: "second-post",
+      title: "Second Post",
+      status: "published",
+    }),
+  ];
+}
+```
+
+### Production (`USE_DEV_SEED=false` or `NODE_ENV=production`)
+
+Production binders (`src/di/bind-production.ts`) replace mock repositories
+with Payload-backed implementations. They receive a `BindProductionContext`
+with `config`, `tracer`, `logger`, `queue`.
+
+### Boot dispatcher
+
+`apps/web-next/src/server/bind-production.ts` picks the mode:
+
+| Condition             | Mode                 |
+| --------------------- | -------------------- |
+| `USE_DEV_SEED=false`  | Production (Payload) |
+| `USE_DEV_SEED=true`   | Dev seed (mocks)     |
+| `NODE_ENV=production` | Production           |
+| Default               | Dev seed             |
+
+Root `.env` is loaded globally via `dotenv-cli` wrapping Turbo
+(`"dev": "dotenv -- turbo run dev"` in root `package.json`).
+
+### Adding a new use case to an existing feature
+
+1. Add the use case to `feature.manifest.ts`
+2. Create input/output schemas in the use-case file
+3. Write the use case factory + controller
+4. Add the tRPC procedure to `integrations/api/router.ts`
+5. Wire into both `bind-production.ts` and `bind-dev-seed.ts`
+6. Add seed data to `__seeds__/dev.ts` if applicable
+7. Create a hook in `src/ui/hooks/use-<name>.ts`
+8. Create client component in `src/ui/components/<name>.client.tsx`
+9. Create server component in `src/ui/components/<name>.server.tsx`
+10. Export the server component from `src/ui/index.ts` under the clean name
+
+---
+
+## Cross-feature boundaries in UI
+
+- Features **may** import another feature's **root barrel** (types, schemas,
+  errors) but **not** its `./ui` subpath. UI composition across features
+  happens in the app layer.
+- Navigation's `<SiteHeader>` receives `siteName`/`siteDescription` as
+  **props** — it does not import from `@repo/marketing-pages`. The app
+  page passes these scalars (the only case where the app fetches data
+  that crosses feature boundaries).
+- If a page renders components from multiple features, the app page
+  imports and renders them side by side — each feature component handles
+  its own data fetching internally.
+
+---
+
+## Checklist for new feature UI
+
+- [ ] Check `core-ui` for existing atoms/molecules before creating new primitives
+- [ ] Hook in `src/ui/hooks/use-<x>.ts` with `"use client"` + `useSuspenseQuery`
+- [ ] Component(s) in `src/ui/components/` composing `core-ui` primitives (atoms -> molecules -> organisms)
+- [ ] Barrel exports in `src/ui/index.ts`
+- [ ] Server component (`.server.tsx`) with DI resolve + prefetch + `HydrationBoundary`
+- [ ] Barrel exports server component under clean name (no `Server` suffix)
+- [ ] `@repo/core-trpc`, `@tanstack/react-query`, `@trpc/client`, `react` in `package.json`
+- [ ] App page just imports and renders: `<ArticleList />` or `<ArticleDetail slug={slug} />`
+- [ ] `@source` directive in app CSS for the feature package (if it has Tailwind classes)
+- [ ] Seed data in `__seeds__/dev.ts` (for dev mode)
+- [ ] Both `bind-production.ts` and `bind-dev-seed.ts` wire the new use case