@3lineas/grooveskills 1.0.0 → 1.0.3

package/skills/react-advanced/references/component-patterns.md

@@ -0,0 +1,117 @@
+# Advanced Component Patterns
+
+> Source of truth: [useContext](https://react.dev/reference/react/useContext), [createPortal](https://react.dev/reference/react-dom/createPortal), and [Component (error boundaries)](https://react.dev/reference/react/Component).
+
+## Compound Components
+
+Compound components let a parent and its sub-components coordinate through implicit shared state via Context so consumers compose pieces declaratively without prop drilling. In GrooveSkills projects, keep each sub-component under 200 lines or extract sub-components into dedicated files under the same domain folder.
+
+```tsx
+import { createContext, useContext, useMemo, useState, type ReactNode } from "react";
+
+interface TabsContextValue {
+  activeTab: string;
+  setActiveTab: (id: string) => void;
+}
+
+const TabsContext = createContext<TabsContextValue | null>(null);
+
+export function useTabsContext(): TabsContextValue {
+  const ctx = useContext(TabsContext);
+  if (!ctx) {
+    throw new Error("Tab components must be rendered inside <TabsRoot>.");
+  }
+  return ctx;
+}
+
+export function TabsRoot({
+  defaultTab,
+  children,
+}: {
+  defaultTab: string;
+  children: ReactNode;
+}) {
+  const [activeTab, setActiveTab] = useState<string>(defaultTab);
+  const value = useMemo(() => ({ activeTab, setActiveTab }), [activeTab]);
+
+  return <TabsContext value={value}>{children}</TabsContext>;
+}
+```
+
+## Context Optimization
+
+Native context has **no selector**. When a provider value changes, **every** consumer of that context re-renders, regardless of which slice each consumer reads:
+
+- `React.memo` does **not** block context-driven re-renders.
+- `use(Context)` adds *conditional reading* but **not** *selective subscription*.
+- The React Compiler does **not** solve large-context over-rendering.
+
+### Native fix 1 — Memoize the provider value
+
+A provider value object created inline is a new reference every render. Memoize it when passing an object literal:
+
+```tsx
+const authValue = useMemo(() => ({ user, signOut }), [user, signOut]);
+return <AuthContext value={authValue}>{children}</AuthContext>;
+```
+
+### Native fix 2 — Split contexts by change frequency
+
+Separate slow-changing state from fast-changing state so frequent updates never re-render consumers of stable data:
+
+```tsx
+// ❌ BAD: theme (rare) and pointer (frequent) share one context.
+const UIContext = createContext<{ theme: ThemeMode; pointer: Point } | null>(null);
+
+// ✅ GOOD: independent contexts; pointer churn never re-renders theme consumers.
+export const ThemeContext = createContext<ThemeMode>("light");
+export const PointerContext = createContext<Point>({ x: 0, y: 0 });
+```
+
+### Userland fix — `use-context-selector` or External Stores
+
+When a single store holds many slices and consumers must subscribe to a single slice, use `use-context-selector` or a dedicated external store (`useSyncExternalStore` / Zustand / Nanostores).
+
+## Custom Hooks vs Render Props
+
+- **Custom Hooks (`use-*.ts`)**: Default choice for sharing stateful logic cleanly across components.
+- **Render Props**: Useful for headless UI wrappers that own behavior/DOM measurement and delegate markup rendering to the caller.
+
+## Error Boundaries
+
+Error boundaries catch errors thrown during render, lifecycle methods, and constructors of the tree below them. For async and event-handler errors, pair `react-error-boundary` (`useErrorBoundary().showBoundary(error)`) with React 19's root `onCaughtError` / `onUncaughtError` hooks.
+
+```tsx
+import { useErrorBoundary } from "react-error-boundary";
+import { saveRecordAction } from "@/actions/records/save-record.action";
+
+export function SaveRecordButton({ payload }: { payload: string }) {
+  const { showBoundary } = useErrorBoundary();
+
+  async function handleSave(): Promise<void> {
+    try {
+      await saveRecordAction(payload);
+    } catch (error) {
+      showBoundary(error);
+    }
+  }
+
+  return (
+    <button type="button" onClick={handleSave}>
+      Save Changes
+    </button>
+  );
+}
+```
+
+## Portals
+
+`createPortal` renders children into a different DOM node (`document.body`) while keeping them in the same place in the **React tree** (preserving Context and React event bubbling). Use portals for modals, dialogs, tooltips, and toasts that must escape parent `overflow: hidden` or `z-index` stacking contexts.
+
+## Anti-Patterns
+
+| Anti-pattern | Why it is wrong | Detection |
+|---|---|---|
+| One large context for high-frequency state | Every consumer re-renders on any change; `memo` cannot block it | Profiler shows unrelated consumers re-rendering |
+| Expecting `React.memo` to stop context re-renders | Context bypasses prop comparison | Memoized child still re-renders on context change |
+| Expecting native boundaries to catch async/event errors | Native boundaries catch only render-phase errors | Unhandled promise rejections in click handlers |

package/skills/react-advanced/references/concurrent-rendering.md

@@ -0,0 +1,130 @@
+# Concurrent Rendering
+
+> Source of truth: [useTransition](https://react.dev/reference/react/useTransition), [useDeferredValue](https://react.dev/reference/react/useDeferredValue), [Suspense](https://react.dev/reference/react/Suspense), and [renderToPipeableStream](https://react.dev/reference/react-dom/server/renderToPipeableStream).
+
+Concurrent rendering lets React prepare a new UI in the background and interrupt it for more urgent work. Urgent updates (typing, clicking) stay responsive while expensive updates (filtering thousands of rows, navigating) render without blocking input.
+
+## `useTransition`
+
+`useTransition` marks a state update as a non-urgent **transition**. React renders the transition in the background, keeps the current UI interactive, and exposes `isPending` so the UI can show a subtle pending indicator without a hard fallback.
+
+```tsx
+import { useState, useTransition } from "react";
+import { ExpensiveReports } from "@/components/reports/expensive-reports";
+import { HomeOverview } from "@/components/home/home-overview";
+import { TabBar } from "@/components/navigation/tab-bar";
+
+export function TabbedView() {
+  const [tab, setTab] = useState<"home" | "reports">("home");
+  const [isPending, startTransition] = useTransition();
+
+  function selectTab(next: "home" | "reports"): void {
+    startTransition(() => setTab(next));
+  }
+
+  return (
+    <>
+      <TabBar active={tab} onSelect={selectTab} busy={isPending} />
+      {tab === "reports" ? <ExpensiveReports /> : <HomeOverview />}
+    </>
+  );
+}
+```
+
+### React 19 async transitions and the post-`await` gotcha
+
+React 19 allows `startTransition` to receive an async function (an "Action"). Only updates issued **synchronously within the transition scope** belong to the transition. Updates after an `await` run in a fresh task and escape it unless re-wrapped.
+
+```tsx
+// ❌ BAD: setResult runs after await, outside the transition; isPending ends early.
+startTransition(async () => {
+  const data = await fetchData();
+  setResult(data);
+});
+
+// ✅ GOOD: re-wrap the post-await update so it stays part of the transition.
+startTransition(async () => {
+  const data = await fetchData();
+  startTransition(() => setResult(data));
+});
+```
+
+## `startTransition` vs `useDeferredValue`
+
+`startTransition` marks an update non-urgent at the **call site** (event handlers). `useDeferredValue` marks a **value** as allowed to lag when an expensive subtree trails a fast-changing input.
+
+Prefer `useDeferredValue` over a fixed `setTimeout` debounce for expensive *derived renders*: it is interruptible and device-adaptive.
+
+```tsx
+import { useDeferredValue, useState } from "react";
+
+export interface RowItem {
+  id: string;
+  label: string;
+}
+
+export function FilterList({ rows }: { rows: RowItem[] }) {
+  const [text, setText] = useState<string>("");
+  const deferredText = useDeferredValue(text, "");
+
+  const filtered = rows.filter((r) => r.label.includes(deferredText));
+  const isStale = text !== deferredText;
+
+  return (
+    <>
+      <input value={text} onChange={(e) => setText(e.target.value)} />
+      <ul style={{ opacity: isStale ? 0.6 : 1 }}>
+        {filtered.map((r) => (
+          <li key={r.id}>{r.label}</li>
+        ))}
+      </ul>
+    </>
+  );
+}
+```
+
+## Suspense for Data
+
+A component suspends when it reads a not-yet-resolved promise via `use()`. The nearest `<Suspense fallback>` shows until the promise resolves.
+
+```tsx
+import { Suspense, use } from "react";
+import type { User } from "@/types/user.types";
+import { ProfileSkeleton } from "@/components/profile/profile-skeleton";
+
+export function ProfileSection({ userPromise }: { userPromise: Promise<User> }) {
+  return (
+    <Suspense fallback={<ProfileSkeleton />}>
+      <ProfileHeader userPromise={userPromise} />
+    </Suspense>
+  );
+}
+
+function ProfileHeader({ userPromise }: { userPromise: Promise<User> }) {
+  const user = use(userPromise);
+  return <h1>{user.name}</h1>;
+}
+```
+
+### Resetting a boundary with `key`
+
+Changing the `key` on a Suspense boundary (or a component inside it) discards the previous tree and re-suspends when switching the displayed resource:
+
+```tsx
+<Suspense fallback={<ProfileSkeleton />}>
+  <ProfileLoader key={userId} userId={userId} />
+</Suspense>
+```
+
+## Streaming SSR (React Level)
+
+For Node servers, `renderToPipeableStream` streams HTML as Suspense boundaries resolve (`renderToReadableStream` for Web Streams / Edge / Cloudflare Workers). Design a meaningful **shell** (header, navigation, layout) that flushes immediately, and let slower data stream behind Suspense.
+
+## Anti-Patterns
+
+| Anti-pattern | Why it is wrong | Detection |
+|---|---|---|
+| State update after `await` in an async transition | Escapes the transition; `isPending` ends early | UI flips to non-pending mid-operation |
+| Fixed debounce/throttle for expensive derived renders | `useDeferredValue` is interruptible and adaptive | Janky typing on slow devices; hard-coded timers |
+| One root spinner instead of a streamed shell | Blocks first paint on the slowest data | Long blank time-to-first-byte |
+| Suspense fallback that mismatches final layout | Causes layout shift on reveal | Visible jump when content arrives |

package/skills/react-advanced/references/performance.md

@@ -0,0 +1,99 @@
+# Performance Architecture
+
+> Source of truth: [lazy](https://react.dev/reference/react/lazy) and [Suspense](https://react.dev/reference/react/Suspense).
+
+With the React Compiler handling fine-grained memoization, performance engineering focuses on three architectural levers: rendering fewer DOM nodes (**virtualization**), shipping less JavaScript up front (**code-splitting**), and measuring before optimizing (**profiling**).
+
+## Virtualization
+
+A list of thousands of rows mounts thousands of DOM nodes, degrading initial render and scroll responsiveness. Virtualization renders only the rows inside (and near) the viewport.
+
+### Library Comparison
+
+| Library | Character | Use when |
+|---|---|---|
+| `@tanstack/react-virtual` | Modern, headless, strongest TypeScript support; full markup control | Default choice for custom layouts and strict TypeScript projects |
+| `react-virtuoso` | Batteries-included (auto-sizing, grouping, sticky headers, chat feeds) | Rich variable-height list features out of the box |
+| `react-window` | Legacy/minimal fixed-size lists | Maintaining existing codebases |
+
+```tsx
+import { useRef } from "react";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import type { LogEntry } from "@/types/log.types";
+import { LogRowView } from "@/components/logs/log-row-view";
+
+export function VirtualLogList({ rows }: { rows: LogEntry[] }) {
+  const parentRef = useRef<HTMLDivElement>(null);
+  const virtualizer = useVirtualizer({
+    count: rows.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 40,
+    overscan: 8,
+  });
+
+  return (
+    <div ref={parentRef} style={{ height: 600, overflow: "auto" }}>
+      <div style={{ height: virtualizer.getTotalSize(), position: "relative" }}>
+        {virtualizer.getVirtualItems().map((virtualRow) => (
+          <div
+            key={virtualRow.key}
+            style={{
+              position: "absolute",
+              top: 0,
+              transform: `translateY(${virtualRow.start}px)`,
+              width: "100%",
+            }}
+          >
+            <LogRowView row={rows[virtualRow.index]} />
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+**Keep row renderers light:** Once virtualized, per-item render cost becomes the bottleneck. Avoid heavy computation or deep subtrees inside `LogRowView`.
+
+## Code-Splitting
+
+`React.lazy` + `Suspense` defers loading a component's bundle until it is rendered.
+
+```tsx
+import { lazy, Suspense } from "react";
+import { RouteSkeleton } from "@/components/layout/route-skeleton";
+
+const AnalyticsDashboard = lazy(() => import("@/components/analytics/analytics-dashboard"));
+
+export function AnalyticsRoute() {
+  return (
+    <Suspense fallback={<RouteSkeleton />}>
+      <AnalyticsDashboard />
+    </Suspense>
+  );
+}
+```
+
+### Strategy
+
+- **Split by route or heavy feature first** (charts, rich-text editors, admin modals).
+- **Do not over-split** tiny (<10KB) components, which creates network request waterfalls.
+- **Match fallback dimensions** to prevent Cumulative Layout Shift (CLS).
+
+## Profiling Workflow
+
+1. **Profile against a production/profiling build** (development builds add instrumentation overhead).
+2. **Record the interaction** in React DevTools Profiler and inspect the flamegraph and "Why did this render?".
+3. **Verify `"Memo ✨"` badges** to confirm the React Compiler optimized hot-path components.
+
+## Anti-Pattern → Detection → Fix Catalog
+
+| Anti-pattern | Why it is wrong | How to detect | Fix |
+|---|---|---|---|
+| Hand-memoizing everything | Redundant with React Compiler | Compiler on, code cluttered with `useMemo` | Remove; keep only effect-stability escape hatches |
+| Removing manual memo blindly | Breaks effect dependency identity contracts | `preserve-manual-memoization` lint warnings | Restore load-bearing memo |
+| Large high-frequency context | Re-renders all consumers on every tick | Profiler highlights unrelated consumers | Split contexts by change frequency |
+| `use()` inside `try / catch` or inline client `fetch()` | Swallows Suspense signals or loops infinitely | Infinite network requests or uncaught suspense | Use Error Boundary; hoist promise creation |
+| State update after `await` in `startTransition` | Escapes transition; `isPending` ends early | Pending spinner disappears before UI updates | Re-wrap post-`await` setter in `startTransition` |
+| Manual debounce for derived renders | Fixed delay on fast/slow devices alike | Input lag on low-end devices | Use `useDeferredValue` |
+| Unvirtualized lists >100 rows | Mounts thousands of DOM nodes | Slow mount and scroll jank in Profiler | Virtualize with `@tanstack/react-virtual` |

package/skills/react-advanced/references/react-compiler.md

@@ -0,0 +1,90 @@
+# React Compiler — Adoption & Memoization Guidance
+
+> Source of truth: [React Compiler docs](https://react.dev/learn/react-compiler/introduction) and the [1.0 announcement](https://react.dev/blog/2025/10/07/react-compiler-1).
+
+## What the Compiler Is
+
+The React Compiler is a build-time optimizing compiler that rewrites components and hooks to memoize automatically. It reached **1.0 stable on 2025-10-07**. It analyzes which values a component computes, which of those depend on which inputs, and emits memoization at fine granularity — including **conditional** memoization that a hand-written `useMemo` cannot express.
+
+It supports React 17, 18, and 19, and produces the best results on 19. On 17/18 it relies on a runtime helper (`react-compiler-runtime`).
+
+## The Memoization Inversion
+
+Pre-compiler React guidance optimized for reference stability by hand: wrap derived values in `useMemo`, wrap callbacks in `useCallback`, wrap components in `React.memo`. With the compiler enabled, that work is redundant for new code, and over-memoization carries real cost (larger code, more cache slots, harder reading).
+
+### Before (manual, pre-compiler)
+
+```tsx
+export function Dashboard({ items, onSelect }: DashboardProps) {
+  const sorted = useMemo(() => items.slice().sort(byName), [items]);
+  const total = useMemo(() => items.reduce((s, i) => s + i.value, 0), [items]);
+  const handleSelect = useCallback((id: string): void => onSelect(id), [onSelect]);
+
+  return <ItemList items={sorted} total={total} onSelect={handleSelect} />;
+}
+
+const ItemList = React.memo(function ItemList({ items, total, onSelect }: ListProps) {
+  return /* ... */;
+});
+```
+
+### After (compiler enabled)
+
+```tsx
+// Plain code. The compiler memoizes `sorted`, `total`, `handleSelect`,
+// and the ItemList render output as needed — including conditionally.
+export function Dashboard({ items, onSelect }: DashboardProps) {
+  const sorted = items.slice().sort(byName);
+  const total = items.reduce((s, i) => s + i.value, 0);
+  const handleSelect = (id: string): void => onSelect(id);
+
+  return <ItemList items={sorted} total={total} onSelect={handleSelect} />;
+}
+```
+
+## When Manual Memo Still Earns Its Place
+
+Keep manual memo when:
+
+1. **A value is an effect dependency and correctness depends on its reference identity.** The compiler optimizes *render*; it does not guarantee a particular identity contract for an effect's dependency array. A value recreated each render re-fires the effect.
+
+```tsx
+const config = useMemo(() => ({ url, token }), [url, token]);
+useEffect(() => subscribe(config), [config]);
+```
+
+2. **Code the compiler cannot statically analyze.** When the compiler cannot prove a component follows the Rules of React, it safely skips that component rather than risk a miscompile. In a skipped component, manual memo remains a valid local optimization.
+
+## Do Not Strip Existing Manual Memo Blindly
+
+The compiler is designed to *preserve* existing `useMemo`/`useCallback`/`React.memo`. The [`preserve-manual-memoization`](https://react.dev/reference/eslint-plugin-react-hooks/lints/preserve-manual-memoization) lint flags cases where removing or altering manual memo would change behavior. Treat its warnings as a signal that the memo carried meaning beyond performance.
+
+## Adoption Path
+
+1. **Install ESLint support:** `eslint-plugin-react-hooks` v6+ absorbed the former `eslint-plugin-react-compiler`.
+2. **Fix reported Rules of React violations** (mutations during render, conditional hooks).
+3. **Enable the compiler in the build** (Babel, Vite, Metro, Next.js, or Rsbuild).
+
+```ts
+// vite.config.ts
+import react from "@vitejs/plugin-react";
+
+export default {
+  plugins: [
+    react({
+      babel: { plugins: [["babel-plugin-react-compiler", {}]] },
+    }),
+  ],
+};
+```
+
+4. **Verify in DevTools:** React DevTools marks compiler-optimized components with a `"Memo ✨"` badge.
+
+## Detection Checklist
+
+| Symptom | Likely cause | Action |
+|---|---|---|
+| New code still littered with `useMemo`/`useCallback` | Reflex memoization habit | Remove; let the compiler handle it |
+| `preserve-manual-memoization` warnings after cleanup | Removed load-bearing memo | Restore the memo; it stabilized an effect/identity contract |
+| A component shows no `"Memo ✨"` badge | Compiler skipped it (unanalyzable) | Fix Rules of React violations, or keep manual memo there |
+| Effect re-fires every render | A dependency value is recreated each render | Memoize that single dependency by hand |

package/skills/react-advanced/references/react19-actions-and-apis.md

@@ -0,0 +1,145 @@
+# React 19 Platform Hooks & APIs
+
+> Source of truth: [use()](https://react.dev/reference/react/use), [useActionState](https://react.dev/reference/react/useActionState), [useOptimistic](https://react.dev/reference/react/useOptimistic), [useFormStatus](https://react.dev/reference/react-dom/hooks/useFormStatus), and [<form>](https://react.dev/reference/react-dom/components/form).
+
+## The `use()` Hook
+
+`use()` reads the value of a promise or a context. Unlike every other hook, it may be called **conditionally** — after early returns or inside branches. When given a promise, it suspends the component until the promise resolves, integrating with the nearest Suspense boundary.
+
+```tsx
+import { use } from "react";
+import type { CommentItem } from "@/types/comment.types";
+
+export function CommentList({
+  commentsPromise,
+  isVisible,
+}: {
+  commentsPromise: Promise<CommentItem[]>;
+  isVisible: boolean;
+}) {
+  if (!isVisible) {
+    return null;
+  }
+
+  // Legal after an early return — `use` is exempt from the top-level rule.
+  const comments = use(commentsPromise);
+  return (
+    <ul>
+      {comments.map((c) => (
+        <li key={c.id}>{c.text}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### Rules and pitfalls
+
+- **Never wrap `use()` in `try / catch`.** A suspended promise is not a synchronous error; rejections surface through an **Error Boundary**, not `catch`.
+- **Do not create the promise during render on the client.** A promise created in the render body is recreated every render, causing infinite suspension loops. Create it on the server, in a parent loader, or in an event handler, and pass it down.
+
+## Actions (`useActionState`, `useOptimistic`, `useFormStatus`)
+
+Actions are React's built-in async-mutation model, providing pending, error, and optimistic handling at the React level.
+
+### `useActionState`
+
+Runs an action function, tracks `isPending`, and threads the previous result forward (replaces the canary `useFormState`).
+
+```tsx
+import { useActionState } from "react";
+
+interface SaveResult {
+  error?: string;
+}
+
+export function UpdateNameForm({
+  saveName,
+}: {
+  saveName: (name: string) => Promise<SaveResult>;
+}) {
+  const [state, formAction, isPending] = useActionState<SaveResult, FormData>(
+    async (_prev, formData) => {
+      const name = String(formData.get("name") ?? "");
+      return await saveName(name);
+    },
+    {}
+  );
+
+  return (
+    <form action={formAction}>
+      <input name="name" disabled={isPending} />
+      <button type="submit" disabled={isPending}>
+        {isPending ? "Saving..." : "Save"}
+      </button>
+      {state.error && <p role="alert">{state.error}</p>}
+    </form>
+  );
+}
+```
+
+### `useOptimistic`
+
+Renders an optimistic value while an async action is in flight, reverting automatically when the action settles.
+
+```tsx
+import { useOptimistic } from "react";
+
+export function LikeButton({
+  count,
+  onLike,
+}: {
+  count: number;
+  onLike: () => Promise<void>;
+}) {
+  const [optimisticCount, addOptimistic] = useOptimistic(
+    count,
+    (current, delta: number) => current + delta
+  );
+
+  async function handleAction(): Promise<void> {
+    addOptimistic(1);
+    await onLike();
+  }
+
+  return (
+    <form action={handleAction}>
+      <button type="submit">♥ {optimisticCount}</button>
+    </form>
+  );
+}
+```
+
+### `useFormStatus`
+
+Reads the pending state of the enclosing `<form>` from a child component without prop drilling.
+
+```tsx
+import { useFormStatus } from "react-dom";
+
+export function SubmitButton({ label }: { label: string }) {
+  const { pending } = useFormStatus();
+  return (
+    <button type="submit" disabled={pending}>
+      {pending ? "Submitting..." : label}
+    </button>
+  );
+}
+```
+
+## React 19 Ergonomic Changes
+
+1. **`ref` as a plain prop**: `forwardRef` is deprecated. Derive wrapper props from `ComponentProps<"input">` (which already includes `ref`), or add `ref?: React.Ref<HTMLElement>` to custom interfaces.
+2. **`<Context value>` as provider**: Render `<ThemeContext value={theme}>{children}</ThemeContext>` instead of `<ThemeContext.Provider>`.
+3. **Native document metadata**: Render `<title>`, `<meta>`, and `<link>` directly inside components; React hoists them to `<head>` automatically without `react-helmet`.
+
+## Migration Notes from React 17/18
+
+| React 17/18 idiom | React 19 replacement |
+|---|---|
+| `forwardRef((props, ref) => ...)` | `ref` as a plain prop |
+| `<Context.Provider value={...}>` | `<Context value={...}>` |
+| `react-helmet` for `<head>` tags | Native `<title>`, `<meta>`, `<link>` hoisting |
+| `useFormState` (canary) | `useActionState` (from `"react"`) |
+| Manual `isLoading`/`error` state in submit handlers | `useActionState` + `useOptimistic` + `useFormStatus` |
+| Fetch in `useEffect` + store in `useState` | Pass a promise to `use()` under `<Suspense>` |