aigroup-workflow 2.1.2 → 2.2.1

package/skills/frontend/nextjs-developer/references/server-components.md

@@ -0,0 +1,384 @@
+# React Server Components
+
+## Server Components (Default)
+
+```tsx
+// app/page.tsx - Server Component by default
+import { db } from '@/lib/db'
+
+export default async function Page() {
+  // Data fetching in Server Component
+  const users = await db.user.findMany()
+
+  return (
+    <div>
+      <h1>Users</h1>
+      <ul>
+        {users.map(user => (
+          <li key={user.id}>{user.name}</li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+```
+
+## Benefits of Server Components
+
+- **Zero bundle size** - Server Components don't add JavaScript to client bundle
+- **Direct backend access** - Query databases, read files, use secrets
+- **Automatic code splitting** - Only Client Components add to bundle
+- **Streaming** - Send UI progressively as data loads
+- **No client-side waterfalls** - Fetch all data in parallel on server
+
+## Client Components
+
+```tsx
+// components/counter.tsx
+'use client' // Required directive
+
+import { useState } from 'react'
+
+export function Counter() {
+  const [count, setCount] = useState(0)
+
+  return (
+    <button onClick={() => setCount(count + 1)}>
+      Count: {count}
+    </button>
+  )
+}
+```
+
+## When to Use Client Components
+
+Use `'use client'` when you need:
+- **Interactivity** - onClick, onChange, event handlers
+- **State** - useState, useReducer
+- **Effects** - useEffect, useLayoutEffect
+- **Browser APIs** - localStorage, window, document
+- **Custom hooks** - Any hook using client-only features
+- **Class components** - Component lifecycle methods
+
+## Composition Pattern
+
+```tsx
+// app/page.tsx - Server Component
+import { ClientWrapper } from './client-wrapper'
+import { db } from '@/lib/db'
+
+export default async function Page() {
+  const data = await db.query()
+
+  return (
+    <div>
+      {/* Server Component content */}
+      <h1>Server Content</h1>
+
+      {/* Pass data to Client Component */}
+      <ClientWrapper initialData={data}>
+        {/* Server Component as children */}
+        <ServerSidebar />
+      </ClientWrapper>
+    </div>
+  )
+}
+
+// components/client-wrapper.tsx
+'use client'
+
+export function ClientWrapper({
+  children,
+  initialData,
+}: {
+  children: React.ReactNode
+  initialData: Data
+}) {
+  const [data, setData] = useState(initialData)
+
+  return (
+    <div>
+      {/* Client Component UI */}
+      <button onClick={() => refresh()}>Refresh</button>
+      {/* Server Component children */}
+      {children}
+    </div>
+  )
+}
+```
+
+## Streaming with Suspense
+
+```tsx
+// app/page.tsx
+import { Suspense } from 'react'
+import { SlowComponent } from './slow-component'
+import { FastComponent } from './fast-component'
+
+export default function Page() {
+  return (
+    <div>
+      {/* Renders immediately */}
+      <FastComponent />
+
+      {/* Shows fallback while loading */}
+      <Suspense fallback={<div>Loading...</div>}>
+        <SlowComponent />
+      </Suspense>
+    </div>
+  )
+}
+
+// components/slow-component.tsx
+async function getData() {
+  await new Promise(resolve => setTimeout(resolve, 3000))
+  return { data: 'Loaded!' }
+}
+
+export async function SlowComponent() {
+  const data = await getData()
+  return <div>{data.data}</div>
+}
+```
+
+## Parallel Data Fetching
+
+```tsx
+// app/dashboard/page.tsx
+async function getUser() {
+  return fetch('https://api.example.com/user')
+}
+
+async function getPosts() {
+  return fetch('https://api.example.com/posts')
+}
+
+export default async function Dashboard() {
+  // Fetch in parallel
+  const [user, posts] = await Promise.all([
+    getUser(),
+    getPosts(),
+  ])
+
+  return (
+    <div>
+      <UserProfile user={user} />
+      <PostsList posts={posts} />
+    </div>
+  )
+}
+```
+
+## Sequential Data Fetching
+
+```tsx
+// app/artist/[id]/page.tsx
+async function getArtist(id: string) {
+  return fetch(`https://api.example.com/artists/${id}`)
+}
+
+async function getAlbums(artistId: string) {
+  return fetch(`https://api.example.com/artists/${artistId}/albums`)
+}
+
+export default async function ArtistPage({ params }: { params: { id: string } }) {
+  // Sequential: albums depends on artist
+  const artist = await getArtist(params.id)
+  const albums = await getAlbums(artist.id)
+
+  return (
+    <div>
+      <h1>{artist.name}</h1>
+      <Albums albums={albums} />
+    </div>
+  )
+}
+```
+
+## Preloading Data
+
+```tsx
+// lib/data.ts
+import { cache } from 'react'
+
+export const getUser = cache(async (id: string) => {
+  return db.user.findUnique({ where: { id } })
+})
+
+// components/user-profile.tsx
+export async function UserProfile({ userId }: { userId: string }) {
+  const user = await getUser(userId)
+  return <div>{user.name}</div>
+}
+
+// app/page.tsx
+import { getUser } from '@/lib/data'
+import { UserProfile } from '@/components/user-profile'
+
+export default async function Page() {
+  // Preload
+  getUser('123')
+
+  return (
+    <div>
+      {/* This will use cached result */}
+      <UserProfile userId="123" />
+    </div>
+  )
+}
+```
+
+## Server Component Patterns
+
+### Pattern: Layout with Data Fetching
+
+```tsx
+// app/dashboard/layout.tsx
+import { auth } from '@/lib/auth'
+import { db } from '@/lib/db'
+
+export default async function DashboardLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const session = await auth()
+  const user = await db.user.findUnique({ where: { id: session.userId } })
+
+  return (
+    <div>
+      <Sidebar user={user} />
+      <main>{children}</main>
+    </div>
+  )
+}
+```
+
+### Pattern: Conditional Client Components
+
+```tsx
+// app/page.tsx
+import { ClientComponent } from './client-component'
+
+export default async function Page() {
+  const data = await fetchData()
+
+  // Only render Client Component when needed
+  if (data.requiresInteractivity) {
+    return <ClientComponent data={data} />
+  }
+
+  return <div>{data.content}</div>
+}
+```
+
+### Pattern: Server Component with Client Island
+
+```tsx
+// app/blog/[slug]/page.tsx
+import { LikeButton } from './like-button'
+
+export default async function BlogPost({ params }: { params: { slug: string } }) {
+  const post = await getPost(params.slug)
+
+  return (
+    <article>
+      {/* Server-rendered content */}
+      <h1>{post.title}</h1>
+      <div dangerouslySetInnerHTML={{ __html: post.content }} />
+
+      {/* Client island for interactivity */}
+      <LikeButton postId={post.id} initialLikes={post.likes} />
+    </article>
+  )
+}
+```
+
+## Context in Server/Client Components
+
+```tsx
+// app/providers.tsx
+'use client'
+
+import { ThemeProvider } from 'next-themes'
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <ThemeProvider>{children}</ThemeProvider>
+}
+
+// app/layout.tsx
+import { Providers } from './providers'
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
+}
+```
+
+## Third-Party Components
+
+```tsx
+// components/carousel-wrapper.tsx
+'use client'
+
+import { Carousel } from 'third-party-carousel'
+
+export function CarouselWrapper({ items }: { items: Item[] }) {
+  return <Carousel items={items} />
+}
+
+// app/page.tsx
+import { CarouselWrapper } from '@/components/carousel-wrapper'
+
+export default async function Page() {
+  const items = await fetchItems()
+  return <CarouselWrapper items={items} />
+}
+```
+
+## Edge Runtime
+
+```tsx
+// app/api/route.ts
+export const runtime = 'edge'
+
+export async function GET() {
+  return new Response('Hello from Edge!')
+}
+
+// app/page.tsx
+export const runtime = 'edge'
+
+export default async function Page() {
+  return <div>Edge-rendered page</div>
+}
+```
+
+## Quick Reference
+
+| Capability | Server Component | Client Component |
+|------------|------------------|------------------|
+| Data fetching | ✅ Yes | ⚠️ Use SWR/React Query |
+| Backend access | ✅ Yes (DB, files) | ❌ No |
+| Event handlers | ❌ No | ✅ Yes |
+| State/Effects | ❌ No | ✅ Yes |
+| Browser APIs | ❌ No | ✅ Yes |
+| Bundle size | 0 KB | Adds to bundle |
+| Streaming | ✅ Yes | ❌ No |
+
+## Best Practices
+
+1. **Default to Server Components** - Only use 'use client' when needed
+2. **Move Client Components down** - Push them to leaves of component tree
+3. **Pass data down** - Fetch in Server Components, pass to Client Components
+4. **Use composition** - Nest Server Components inside Client Components via children
+5. **Cache expensive operations** - Use React cache() for deduplication

package/skills/frontend/react-expert/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: react-expert
+description: Use when building React 18+ applications in .jsx or .tsx files, Next.js App Router projects, or create-react-app setups. Creates components, implements custom hooks, debugs rendering issues, migrates class components to functional, and implements state management. Invoke for Server Components, Suspense boundaries, useActionState forms, performance optimization, or React 19 features.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: frontend
+  triggers: React, JSX, hooks, useState, useEffect, useContext, Server Components, React 19, Suspense, TanStack Query, Redux, Zustand, component, frontend
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: fullstack-guardian, playwright-expert, test-master
+---
+
+# React Expert
+
+Senior React specialist with deep expertise in React 19, Server Components, and production-grade application architecture.
+
+## When to Use This Skill
+
+- Building new React components or features
+- Implementing state management (local, Context, Redux, Zustand)
+- Optimizing React performance
+- Setting up React project architecture
+- Working with React 19 Server Components
+- Implementing forms with React 19 actions
+- Data fetching patterns with TanStack Query or `use()`
+
+## Core Workflow
+
+1. **Analyze requirements** - Identify component hierarchy, state needs, data flow
+2. **Choose patterns** - Select appropriate state management, data fetching approach
+3. **Implement** - Write TypeScript components with proper types
+4. **Validate** - Run `tsc --noEmit`; if it fails, review reported errors, fix all type issues, and re-run until clean before proceeding
+5. **Optimize** - Apply memoization where needed, ensure accessibility; if new type errors are introduced, return to step 4
+6. **Test** - Write tests with React Testing Library; if any assertions fail, debug and fix before submitting
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Server Components | `references/server-components.md` | RSC patterns, Next.js App Router |
+| React 19 | `references/react-19-features.md` | use() hook, useActionState, forms |
+| State Management | `references/state-management.md` | Context, Zustand, Redux, TanStack |
+| Hooks | `references/hooks-patterns.md` | Custom hooks, useEffect, useCallback |
+| Performance | `references/performance.md` | memo, lazy, virtualization |
+| Testing | `references/testing-react.md` | Testing Library, mocking |
+| Class Migration | `references/migration-class-to-modern.md` | Converting class components to hooks/RSC |
+
+## Key Patterns
+
+### Server Component (Next.js App Router)
+```tsx
+// app/users/page.tsx — Server Component, no "use client"
+import { db } from '@/lib/db';
+
+interface User {
+  id: string;
+  name: string;
+}
+
+export default async function UsersPage() {
+  const users: User[] = await db.user.findMany();
+
+  return (
+    <ul>
+      {users.map((user) => (
+        <li key={user.id}>{user.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### React 19 Form with `useActionState`
+```tsx
+'use client';
+import { useActionState } from 'react';
+
+async function submitForm(_prev: string, formData: FormData): Promise<string> {
+  const name = formData.get('name') as string;
+  // perform server action or fetch
+  return `Hello, ${name}!`;
+}
+
+export function GreetForm() {
+  const [message, action, isPending] = useActionState(submitForm, '');
+
+  return (
+    <form action={action}>
+      <input name="name" required />
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Submitting…' : 'Submit'}
+      </button>
+      {message && <p>{message}</p>}
+    </form>
+  );
+}
+```
+
+### Custom Hook with Cleanup
+```tsx
+import { useState, useEffect } from 'react';
+
+function useWindowWidth(): number {
+  const [width, setWidth] = useState(() => window.innerWidth);
+
+  useEffect(() => {
+    const handler = () => setWidth(window.innerWidth);
+    window.addEventListener('resize', handler);
+    return () => window.removeEventListener('resize', handler); // cleanup
+  }, []);
+
+  return width;
+}
+```
+
+## Constraints
+
+### MUST DO
+- Use TypeScript with strict mode
+- Implement error boundaries for graceful failures
+- Use `key` props correctly (stable, unique identifiers)
+- Clean up effects (return cleanup function)
+- Use semantic HTML and ARIA for accessibility
+- Memoize when passing callbacks/objects to memoized children
+- Use Suspense boundaries for async operations
+
+### MUST NOT DO
+- Mutate state directly
+- Use array index as key for dynamic lists
+- Create functions inside JSX (causes re-renders)
+- Forget useEffect cleanup (memory leaks)
+- Ignore React strict mode warnings
+- Skip error boundaries in production
+
+## Output Templates
+
+When implementing React features, provide:
+1. Component file with TypeScript types
+2. Test file if non-trivial logic
+3. Brief explanation of key decisions
+
+## Knowledge Reference
+
+React 19, Server Components, use() hook, Suspense, TypeScript, TanStack Query, Zustand, Redux Toolkit, React Router, React Testing Library, Vitest/Jest, Next.js App Router, accessibility (WCAG)

package/skills/frontend/react-expert/references/hooks-patterns.md

@@ -0,0 +1,162 @@
+# Hooks Patterns
+
+## Custom Hook Pattern
+
+```tsx
+// useApi - Data fetching hook
+function useApi<T>(url: string) {
+  const [data, setData] = useState<T | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const controller = new AbortController();
+
+    fetch(url, { signal: controller.signal })
+      .then(res => {
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        return res.json();
+      })
+      .then(setData)
+      .catch(err => {
+        if (err.name !== 'AbortError') setError(err);
+      })
+      .finally(() => setLoading(false));
+
+    return () => controller.abort();
+  }, [url]);
+
+  return { data, error, loading };
+}
+```
+
+## useDebounce
+
+```tsx
+function useDebounce<T>(value: T, delay: number): T {
+  const [debounced, setDebounced] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+
+  return debounced;
+}
+
+// Usage
+function Search() {
+  const [query, setQuery] = useState('');
+  const debouncedQuery = useDebounce(query, 300);
+
+  useEffect(() => {
+    if (debouncedQuery) search(debouncedQuery);
+  }, [debouncedQuery]);
+}
+```
+
+## useLocalStorage
+
+```tsx
+function useLocalStorage<T>(key: string, initialValue: T) {
+  const [value, setValue] = useState<T>(() => {
+    if (typeof window === 'undefined') return initialValue;
+    const stored = localStorage.getItem(key);
+    return stored ? JSON.parse(stored) : initialValue;
+  });
+
+  useEffect(() => {
+    localStorage.setItem(key, JSON.stringify(value));
+  }, [key, value]);
+
+  return [value, setValue] as const;
+}
+```
+
+## useMediaQuery
+
+```tsx
+function useMediaQuery(query: string): boolean {
+  const [matches, setMatches] = useState(() =>
+    typeof window !== 'undefined' && window.matchMedia(query).matches
+  );
+
+  useEffect(() => {
+    const media = window.matchMedia(query);
+    const listener = (e: MediaQueryListEvent) => setMatches(e.matches);
+
+    media.addEventListener('change', listener);
+    return () => media.removeEventListener('change', listener);
+  }, [query]);
+
+  return matches;
+}
+
+// Usage
+function Layout() {
+  const isMobile = useMediaQuery('(max-width: 768px)');
+  return isMobile ? <MobileNav /> : <DesktopNav />;
+}
+```
+
+## useCallback & useMemo
+
+```tsx
+// useCallback: Memoize functions (for child dependencies)
+const handleClick = useCallback((id: string) => {
+  setSelected(id);
+}, []); // Empty deps = stable reference
+
+// useMemo: Memoize expensive calculations
+const sortedItems = useMemo(() =>
+  [...items].sort((a, b) => a.name.localeCompare(b.name)),
+  [items]
+);
+
+// When to use:
+// - useCallback: When passing to memoized children
+// - useMemo: When calculation is expensive AND deps rarely change
+```
+
+## Effect Cleanup
+
+```tsx
+useEffect(() => {
+  const subscription = api.subscribe(handler);
+
+  // Cleanup function
+  return () => subscription.unsubscribe();
+}, []);
+
+// Async effect pattern
+useEffect(() => {
+  let cancelled = false;
+
+  async function fetchData() {
+    const data = await api.getData();
+    if (!cancelled) setData(data);
+  }
+
+  fetchData();
+  return () => { cancelled = true };
+}, []);
+```
+
+## Quick Reference
+
+| Hook | Purpose |
+|------|---------|
+| useState | Component state |
+| useEffect | Side effects, subscriptions |
+| useCallback | Memoize functions |
+| useMemo | Memoize values |
+| useRef | Mutable ref, DOM access |
+| useContext | Read context |
+| useReducer | Complex state logic |
+
+| Custom Hook | Use Case |
+|-------------|----------|
+| useDebounce | Input delay |
+| useLocalStorage | Persistent state |
+| useMediaQuery | Responsive logic |
+| useApi | Data fetching |