groundwork-method 0.0.1 → 0.11.0

package/src/engineer-skills/groundwork-nextjs-engineer/references/server-components.md

@@ -0,0 +1,394 @@
+# Server Components & Client Boundaries
+
+## Table of Contents
+- [RSC by Default](#rsc-by-default)
+- [When to Add use client](#when-to-add-use-client)
+- [Async Params and SearchParams](#async-params-and-searchparams)
+- [Async Server Functions](#async-server-functions)
+- [Additional Server Functions](#additional-server-functions)
+- [Directives](#directives)
+- [Runtime Selection](#runtime-selection)
+- [Patterns for Crossing the Boundary](#patterns-for-crossing-the-boundary)
+
+---
+
+## RSC by Default
+
+Every component in the Next.js application is a React Server Component unless explicitly marked otherwise. Server Components run on the server, have zero client-side JavaScript overhead, and can directly fetch data, read cookies, and access server-only resources.
+
+Add the `"use client"` directive only when the component strictly requires:
+- React hooks (`useState`, `useEffect`, `useRef`, `useContext`, etc.)
+- Event handlers (`onClick`, `onChange`, `onSubmit`)
+- Browser APIs (`window`, `localStorage`, `IntersectionObserver`)
+- Third-party libraries that rely on browser APIs
+
+If a component only needs interactivity in a small subtree, keep the parent as a Server Component and push the `"use client"` boundary as far down the tree as possible.
+
+```tsx
+// Server Component (default) — no directive needed
+export default async function MeetingPage({ params }: Props) {
+  const { id } = await params;
+  const meeting = await getMeeting(id);
+
+  return (
+    <article>
+      <h1>{meeting.title}</h1>
+      <MeetingStatus status={meeting.status} />  {/* Server Component */}
+      <TranscriptPlayer meetingId={id} />         {/* Client Component — needs audio API */}
+    </article>
+  );
+}
+
+// Only the leaf that needs interactivity is a client component
+// components/meetings/transcript-player.tsx
+'use client';
+
+import { useState, useRef } from 'react';
+
+export function TranscriptPlayer({ meetingId }: { meetingId: string }) {
+  const [isPlaying, setIsPlaying] = useState(false);
+  const audioRef = useRef<HTMLAudioElement>(null);
+  // Browser API usage justified
+  return <audio ref={audioRef}>...</audio>;
+}
+```
+
+---
+
+## When to Add use client
+
+Use this checklist. If none of these apply, the component should remain a Server Component.
+
+| Requires | Example | Needs `"use client"`? |
+|----------|---------|----------------------|
+| `useState`, `useReducer` | Form state, toggle state | Yes |
+| `useEffect`, `useRef` | DOM manipulation, timers | Yes |
+| `useContext` | Theme, auth context | Yes |
+| `onClick`, `onChange`, `onSubmit` | Button clicks, form input | Yes |
+| `window`, `localStorage` | Feature detection, persistence | Yes |
+| `useRouter`, `usePathname`, `useSearchParams` | Client-side navigation | Yes |
+| SWR hooks | Data fetching/revalidation | Yes |
+| Async data fetch | `await getMeeting(id)` | **No** — Server Components can be async |
+| Static rendering | Displaying data, formatting | **No** |
+| Reading `cookies()`, `headers()` | Auth checks, locale | **No** — server functions |
+
+---
+
+## Async Params and SearchParams
+
+In Next.js 15+, `params` and `searchParams` are **asynchronous**. They must be typed as `Promise<...>` and awaited before use.
+
+### Pages and Layouts
+
+```tsx
+type Props = {
+  params: Promise<{ id: string }>;
+  searchParams: Promise<{ query?: string; tab?: string }>;
+};
+
+export default async function MeetingPage({ params, searchParams }: Props) {
+  const { id } = await params;
+  const { query, tab } = await searchParams;
+
+  const meeting = await getMeeting(id);
+  return <MeetingDetail meeting={meeting} activeTab={tab} />;
+}
+```
+
+### Route Handlers
+
+```tsx
+// app/api/meetings/[id]/route.ts
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+  const meeting = await getMeeting(id);
+
+  if (!meeting) {
+    return Response.json({ error: 'Not found' }, { status: 404 });
+  }
+
+  return Response.json(meeting);
+}
+```
+
+### generateMetadata
+
+```tsx
+type Props = { params: Promise<{ id: string }> };
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { id } = await params;
+  const meeting = await getMeeting(id);
+  return {
+    title: meeting.title,
+    description: `Meeting details for ${meeting.title}`,
+  };
+}
+```
+
+### Synchronous Components
+
+When a component cannot be async (e.g., because it also uses hooks), use `React.use()` to unwrap the promise:
+
+```tsx
+'use client';
+
+import { use } from 'react';
+
+type Props = { params: Promise<{ id: string }> };
+
+export default function MeetingPage({ params }: Props) {
+  const { id } = use(params);
+  // Can now use hooks alongside params
+  const { data } = useMeeting(id);
+  return <div>{data?.title}</div>;
+}
+```
+
+---
+
+## Async Server Functions
+
+`cookies()` and `headers()` are asynchronous in Next.js 15+. Always `await` them.
+
+```tsx
+import { cookies, headers } from 'next/headers';
+
+export default async function Page() {
+  const cookieStore = await cookies();
+  const headersList = await headers();
+
+  const theme = cookieStore.get('theme')?.value ?? 'obsidian';
+  const userAgent = headersList.get('user-agent');
+
+  return <Dashboard theme={theme} />;
+}
+```
+
+### Migration
+
+If upgrading from an older codebase where these were synchronous, run the codemod:
+
+```bash
+pnpx @next/codemod@latest next-async-request-api .
+```
+
+---
+
+## Additional Server Functions
+
+| Function | Purpose |
+|----------|---------|
+| `draftMode()` | Enable preview of unpublished CMS content — sets a cookie that opts into dynamic rendering |
+| `connection()` | Wait for the incoming connection before dynamic rendering — use when a component depends on request-time data but doesn't call `cookies()`/`headers()` |
+| `userAgent()` | Parse the `User-Agent` header into structured data (`isBot`, `browser`, `device`, `engine`, `os`, `cpu`) |
+
+```tsx
+import { draftMode } from 'next/headers';
+
+export default async function Page() {
+  const { isEnabled } = await draftMode();
+
+  return isEnabled
+    ? <PreviewContent />
+    : <PublishedContent />;
+}
+```
+
+```tsx
+import { connection } from 'next/server';
+
+export default async function DynamicWidget() {
+  await connection();  // Signals this component needs request-time data
+  const data = await getPersonalisedData();
+  return <Widget data={data} />;
+}
+```
+
+```tsx
+import { userAgent } from 'next/server';
+import { headers } from 'next/headers';
+
+export default async function Page() {
+  const headersList = await headers();
+  const { isBot, browser, device } = userAgent({ headers: headersList });
+
+  if (isBot) return <BotView />;
+  return <UserView browser={browser.name} device={device.type} />;
+}
+```
+
+---
+
+## Directives
+
+### `'use client'`
+
+Marks a file as a Client Component boundary. Everything imported by this file also becomes part of the client bundle.
+
+```tsx
+'use client';
+
+import { useState } from 'react';
+
+export function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(count + 1)}>{count}</button>;
+}
+```
+
+Place the directive at the very top of the file, before any imports. It applies to the entire file — not individual functions.
+
+### `'use server'`
+
+Marks functions as Server Actions. Server Actions are the only functions that can be passed from Server Components to Client Components as props.
+
+```tsx
+// File-level — all exports are Server Actions
+'use server';
+
+export async function createMeeting(formData: FormData) {
+  // Runs on the server
+}
+
+export async function deleteMeeting(id: string) {
+  // Runs on the server
+}
+```
+
+```tsx
+// Inline — within a Server Component
+export default function MeetingPage() {
+  async function handleDelete(id: string) {
+    'use server';
+    await deleteMeeting(id);
+    revalidatePath('/meetings');
+  }
+
+  return <DeleteButton onDelete={handleDelete} />;
+}
+```
+
+### `'use cache'`
+
+Caches a function or component result. Part of Next.js Cache Components.
+
+```tsx
+'use cache';
+
+export async function getCachedMeetings() {
+  return await fetchMeetings();
+}
+```
+
+Requires `cacheComponents: true` in `next.config.ts`. Use `cacheLife()` and `cacheTag()` to control cache duration and invalidation.
+
+---
+
+## Runtime Selection
+
+Default to the **Node.js runtime** for all routes and pages. Only use Edge runtime if the project already uses it or there is a specific geographic latency requirement.
+
+```tsx
+// Default — no config needed (uses Node.js)
+export default function Page() { ... }
+
+// Only if there's a specific edge requirement
+export const runtime = 'edge';
+```
+
+### Decision Checklist
+
+Before adding `runtime = 'edge'`:
+
+1. Does the project already use Edge runtime for other routes?
+2. Is there a documented latency requirement that Node.js cannot meet?
+3. Are all dependencies of this route Edge-compatible? (No `fs`, limited `crypto`, many npm packages won't work)
+
+If the answer to all three is not clearly "yes", use Node.js.
+
+| Feature | Node.js | Edge |
+|---------|---------|------|
+| Full Node.js API | Yes | No |
+| File system (`fs`) | Yes | No |
+| Full `crypto` | Yes | Limited |
+| Database connections | Yes | Limited |
+| npm package compatibility | Most | Few |
+| Cold start | Larger | Smaller |
+| Geographic distribution | No | Yes |
+
+---
+
+## Patterns for Crossing the Boundary
+
+### Pattern 1: Server Parent, Client Leaf
+
+The most common pattern. Server Component fetches data and passes serialised props to a client component that adds interactivity.
+
+```tsx
+// Server Component — fetches and coordinates
+export default async function MeetingsPage() {
+  const meetings = await getMeetings();
+
+  return (
+    <div>
+      <h1>Meetings</h1>
+      <MeetingFilters />        {/* Client — needs useState for filter state */}
+      <MeetingList meetings={meetings} />  {/* Could be server or client */}
+    </div>
+  );
+}
+```
+
+### Pattern 2: Client Component with Server Children
+
+Client Components can render Server Components passed as `children`. This avoids pulling the entire subtree into the client bundle.
+
+```tsx
+// Client wrapper — provides interactive context
+'use client';
+
+export function CollapsibleSection({ children }: { children: React.ReactNode }) {
+  const [isOpen, setIsOpen] = useState(true);
+  return (
+    <section>
+      <button onClick={() => setIsOpen(!isOpen)}>Toggle</button>
+      {isOpen && children}
+    </section>
+  );
+}
+
+// Server Component — passes server-rendered children
+export default async function Page() {
+  return (
+    <CollapsibleSection>
+      <MeetingList />  {/* This remains a Server Component */}
+    </CollapsibleSection>
+  );
+}
+```
+
+### Pattern 3: Hydration Seeding
+
+Fetch data on the server in a Server Component and seed the client-side SWR cache so the client component renders immediately without a loading state.
+
+```tsx
+// Server Component — seeds the cache
+import { SWRConfig } from 'swr';
+import { getMeetings } from '@/lib/api';
+
+export default async function MeetingsPage() {
+  const meetings = await getMeetings();
+
+  return (
+    <SWRConfig value={{ fallback: { '/api/meetings': meetings } }}>
+      <MeetingDashboard />
+    </SWRConfig>
+  );
+}
+```
+
+See `references/data-fetching.md` for the full hydration seeding pattern.

package/src/engineer-skills/groundwork-nextjs-engineer/references/tailwind-and-styling.md

@@ -0,0 +1,134 @@
+# Tailwind & Theming
+
+This reference covers **how** to wire and consume the design system in Tailwind v4 — the mechanics, not the values. Colours, type, spacing, radii, elevation, blur, gradients, surfaces, and motion are per-app decisions projected from `.groundwork/config/brand-tokens.json` into `app/brand.css`; see `references/visual-language.md` for the projection chain. Never bake values into the skill or a component.
+
+## Table of Contents
+- [Tailwind v4 CSS-First Architecture](#tailwind-v4-css-first-architecture)
+- [globals.css and brand.css structure](#globalscss-and-brandcss-structure)
+- [PostCSS Pipeline](#postcss-pipeline)
+- [Dark Mode with @custom-variant](#dark-mode-with-custom-variant)
+- [Consuming tokens as Tailwind utilities](#consuming-tokens-as-tailwind-utilities)
+- [Animations with tw-animate-css](#animations-with-tw-animate-css)
+- [Theming and dual-theme verification](#theming-and-dual-theme-verification)
+- [Common Mistakes](#common-mistakes)
+
+---
+
+## Tailwind v4 CSS-First Architecture
+
+Tailwind v4 eliminates the JavaScript configuration file. All customisation happens in CSS via `@theme` blocks and CSS custom properties. There is no `tailwind.config.ts` in the Next.js application.
+
+| v3 (Forbidden) | v4 (Required) |
+|----------------|---------------|
+| `tailwind.config.ts` | No config file — use `@theme` in CSS |
+| `@apply` with `theme()` | Direct CSS custom properties |
+| `content: ['./app/**/*.tsx']` | Automatic content detection |
+| `darkMode: 'class'` | `@custom-variant dark (&:is(.dark *))` |
+| `plugins: [require('...')]` | `@plugin` directive in CSS |
+
+---
+
+## globals.css and brand.css structure
+
+Styling is split into a **generated value file** and a **static structure file**:
+
+- **`app/brand.css`** — GENERATED by the nextjs-app generator from the design system's `visual` block. It carries the shadcn structural variables (`--background`, `--primary`, …) and the `--gw-*` atmosphere values (blur, elevation stacks, gradients, surface tints, type-role micro, motion profiles), for both light (`:root`) and dark (`.dark`). **Never hand-edit it** — re-run the design system and regenerate.
+- **`app/globals.css`** — STATIC structure. It imports Tailwind, `tw-animate-css`, and `brand.css`; declares the `dark` variant; maps the variables into Tailwind token utilities via `@theme inline`; and defines the surface utility classes (`.surface-glass`, `.surface-elevated`, `.surface-hero`) that compose the `--gw-*` tokens. Extend its structure if a project needs a new mapping or surface class — never bake a literal value into it.
+
+This is the same generated-theme pattern electron-app and flutter-app use. The values change per app; the structure does not.
+
+---
+
+## PostCSS Pipeline
+
+Tailwind v4 uses `@tailwindcss/postcss`:
+
+```js
+// postcss.config.js
+module.exports = {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+Do not add `autoprefixer` separately — `@tailwindcss/postcss` handles vendor prefixing.
+
+---
+
+## Dark Mode with @custom-variant
+
+Class-based dark mode: the `dark` variant activates when `.dark` is on an ancestor.
+
+```css
+@custom-variant dark (&:is(.dark *));
+```
+
+Because the tokens themselves flip in the `.dark` scope (brand.css redefines every structural variable for dark), most components need **no** `dark:` variants — consuming a token utility switches automatically:
+
+```tsx
+<div className="bg-background text-foreground">Auto-switches with the theme</div>
+```
+
+Reach for a `dark:` variant only when the two themes need structurally different styles (a different border, shadow, or opacity), not merely a different colour.
+
+---
+
+## Consuming tokens as Tailwind utilities
+
+`@theme inline` in `globals.css` maps each variable to a Tailwind utility. Consume the utility, in priority order:
+
+1. **Token utilities** — `bg-background`, `text-foreground`, `bg-primary`, `text-muted-foreground`, `border-border`, `shadow-low/mid/high`, `backdrop-blur-subtle/standard/heavy`, the spacing scale (`p-4`, `gap-6`), the radius scale (`rounded-lg`). This is the default path.
+2. **Surface classes** — `.surface-glass` / `.surface-elevated` / `.surface-hero` for composed depth (blur + tint + border + shadow + gradient).
+3. **CSS-variable reference** — for a projected value with no dedicated utility, use the var-reference form `shadow-(--gw-shadow-mid)` or `bg-(--gw-surface-glass-tint)`.
+
+**Never use arbitrary literals.** `bg-[#3b82f6]`, `p-[12px]`, `shadow-[0_1px_2px…]`, `backdrop-blur-[20px]`, and inline gradient strings bypass the design system and **fail the token-conformance lint** (`eslint.config.mjs`). The var-reference form (`(--gw-…)`) is allowed; the literal form (`[…]`) is not.
+
+---
+
+## Animations with tw-animate-css
+
+`tw-animate-css` provides utility-based enter/exit animations without custom keyframes:
+
+```tsx
+<div className="animate-in fade-in duration-200">Appears smoothly</div>
+<DialogContent className="animate-in fade-in slide-in-from-bottom-4 duration-300 data-[state=closed]:animate-out data-[state=closed]:fade-out">
+  Dialog content
+</DialogContent>
+```
+
+### Motion mechanics
+
+The durations, easing, and transforms are the design system's call, projected as `--gw-motion-<context>-{duration,ease,transform}` (hover, press, enter, exit, stagger). Consume those rather than inventing timings. Three mechanics are universal and always apply:
+
+- **Animate compositor-only properties** — `transform` and `opacity` hold frame rate; animating `width`/`height`/`box-shadow`/`top` drops frames.
+- **Respect `prefers-reduced-motion`** — gate non-essential motion behind the reduced-motion query.
+- **Entry eases out, never linear on interface elements** — the specific curve comes from the motion tokens.
+
+---
+
+## Theming and dual-theme verification
+
+The app ships a light and a dark theme; a `ThemeProvider` toggles the `.dark` class on `<html>` (persisted to `localStorage`, honouring the system preference on first load). The theme *names* and *values* belong to the design system — keep the provider generic over "light" and "dark", never hardcode brand-specific theme identities here.
+
+**Every component is verified in both themes before merging.** Watch for:
+
+- Text contrast meeting WCAG AA (4.5:1 body, 3:1 large text) in both themes.
+- Shadow visibility — a stack tuned for light can vanish on dark surfaces (this is why brand.css carries deeper dark-theme elevation).
+- Border visibility — translucent hairline borders can disappear in light mode.
+- Backdrop-blur surfaces rendering correctly against both backgrounds.
+- Semantic colours (success/error/warning) staying readable in both modes.
+
+---
+
+## Common Mistakes
+
+| Mistake | Why It Fails | Fix |
+|---------|-------------|-----|
+| Creating `tailwind.config.ts` | Overrides CSS-first architecture | Use `@theme` in `globals.css` |
+| Hand-editing `brand.css` | Overwritten on regeneration | Change the design system and regenerate |
+| Using `theme()` in CSS | v3 syntax, unsupported | Reference CSS custom properties directly |
+| Arbitrary literal (`bg-[#…]`, `shadow-[…]`, `backdrop-blur-[…]`) | Bypasses tokens; fails lint | Use a token utility, surface class, or `(--gw-…)` var reference |
+| Hardcoding `bg-gray-800` | Ignores the projected palette | Use `bg-background` / `bg-card` / `bg-primary` |
+| Adding `autoprefixer` | `@tailwindcss/postcss` handles it | Remove it |
+| `darkMode: 'class'` in config | v3 syntax | Use `@custom-variant dark` |