@caddis/cli 0.0.0 → 0.1.0

package/bundles/antigravity-plugin/skills/react-dev/README.md

@@ -0,0 +1,404 @@
+# React TypeScript Development Skill
+
+## Purpose
+
+The `react-dev` skill provides comprehensive TypeScript patterns and best practices for building type-safe React applications. It serves as a complete reference for modern React development with TypeScript, covering React 18-19 features, including Server Components, type-safe routing, and proper event handling.
+
+This skill exists to eliminate TypeScript guesswork in React development by providing compile-time guarantees, confident refactoring, and production-ready patterns that catch bugs before runtime.
+
+## When to Use
+
+Activate this skill when working on:
+
+- **Building typed React components** - Creating new components with proper TypeScript types
+- **Implementing generic components** - Tables, lists, modals, form fields that work with any data type
+- **Typing event handlers and forms** - Mouse events, form submissions, input changes, keyboard events
+- **Using React 19 features** - Actions, Server Components, `use()` hook, `useActionState`
+- **Router integration** - TanStack Router or React Router v7 with type safety
+- **Custom hooks with proper typing** - Creating reusable hooks with correct return types
+- **Migrating to React 19** - Understanding breaking changes and new patterns
+
+**Trigger phrases:**
+- "Build a typed React component"
+- "Type this event handler"
+- "Create a generic Table/List/Modal"
+- "Use React 19 Server Components"
+- "Type-safe routing with TanStack/React Router"
+- "How do I type this hook?"
+- "React TypeScript best practices"
+
+**Not for:**
+- Non-React TypeScript projects
+- Vanilla JavaScript React (without TypeScript)
+- React Native-specific patterns
+
+## How It Works
+
+The skill provides progressive disclosure of React TypeScript knowledge:
+
+1. **Core patterns loaded immediately** - Component props, event handlers, hooks typing
+2. **Advanced patterns referenced on-demand** - Generic components, Server Components, routing
+3. **Reference files for deep dives** - Detailed examples and edge cases only loaded when needed
+4. **React 19 migration guidance** - Breaking changes and new APIs clearly marked
+
+The skill is structured around:
+- **Quick reference sections** - Common patterns you can copy immediately
+- **Detailed reference files** - In-depth examples and explanations
+- **Rules and anti-patterns** - What to always do and what to never do
+- **Version-specific guidance** - React 18 vs React 19 differences highlighted
+
+## Key Features
+
+### 1. React 19 Breaking Changes
+
+Covers all major breaking changes in React 19:
+
+- **ref as prop** - No more `forwardRef`, refs are regular props now
+- **useActionState** - Replaces deprecated `useFormState`
+- **use() hook** - Unwraps promises and context in components
+- **Migration patterns** - Step-by-step guides for updating existing code
+
+### 2. Component Patterns
+
+Type-safe patterns for common component scenarios:
+
+- **Props typing** - Extending native HTML elements with `ComponentPropsWithoutRef`
+- **Children typing** - `ReactNode`, `ReactElement`, render props
+- **Discriminated unions** - Type-safe variant props (e.g., button vs link)
+- **Generic components** - Reusable components that infer types from data
+
+### 3. Event Handler Typing
+
+Specific event types for accurate TypeScript inference:
+
+- Mouse events (`MouseEvent<HTMLButtonElement>`)
+- Form events (`FormEvent<HTMLFormElement>`)
+- Input changes (`ChangeEvent<HTMLInputElement>`)
+- Keyboard events (`KeyboardEvent<HTMLInputElement>`)
+- Focus, drag, clipboard, touch, wheel events (in reference docs)
+
+### 4. Hooks Typing
+
+Proper TypeScript patterns for all React hooks:
+
+- `useState` - Explicit types for unions and nullable values
+- `useRef` - DOM refs (null) vs mutable refs (direct access)
+- `useReducer` - Discriminated union actions
+- `useContext` - Null guard patterns
+- Custom hooks - Tuple returns with `as const`
+
+### 5. Server Components (React 19)
+
+Modern patterns for Server Components and Server Actions:
+
+- Async components with direct data fetching
+- Server Actions with `'use server'` directive
+- Client components consuming Server Actions
+- Promise handoff with `use()` hook
+- Parallel fetching and streaming
+
+### 6. Type-Safe Routing
+
+Comprehensive routing patterns for both major routers:
+
+- **TanStack Router** - Compile-time type safety with Zod validation
+- **React Router v7** - Auto-generated types with Framework Mode
+- Type-safe params, search params, loaders, actions
+
+### 7. Generic Components
+
+Reusable components that work with any data type:
+
+- Tables with type-safe columns
+- Lists with constrained generics
+- Modals, selects, form fields
+- Render props and keyof patterns
+
+## Prerequisites
+
+- **React 18 or 19** - Patterns are optimized for modern React
+- **TypeScript 5.0+** - Uses latest TypeScript features
+- **Router (optional)** - TanStack Router or React Router v7 for routing patterns
+- **Zod (optional)** - For TanStack Router search param validation
+
+## Usage Examples
+
+### Example 1: Type-Safe Button Component
+
+```typescript
+type ButtonProps = {
+  variant: 'primary' | 'secondary';
+} & React.ComponentPropsWithoutRef<'button'>;
+
+function Button({ variant, children, ...props }: ButtonProps) {
+  return (
+    <button
+      className={variant}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+}
+
+// Usage
+<Button variant="primary" onClick={(e) => console.log(e.currentTarget.disabled)}>
+  Click me
+</Button>
+```
+
+### Example 2: Generic Table Component
+
+```typescript
+type Column<T> = {
+  key: keyof T;
+  header: string;
+  render?: (value: T[keyof T], item: T) => React.ReactNode;
+};
+
+type TableProps<T> = {
+  data: T[];
+  columns: Column<T>[];
+  keyExtractor: (item: T) => string | number;
+};
+
+function Table<T>({ data, columns, keyExtractor }: TableProps<T>) {
+  return (
+    <table>
+      <thead>
+        <tr>{columns.map(col => <th key={String(col.key)}>{col.header}</th>)}</tr>
+      </thead>
+      <tbody>
+        {data.map(item => (
+          <tr key={keyExtractor(item)}>
+            {columns.map(col => (
+              <td key={String(col.key)}>
+                {col.render ? col.render(item[col.key], item) : String(item[col.key])}
+              </td>
+            ))}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+
+// Usage - types are inferred!
+type User = { id: number; name: string; email: string };
+const users: User[] = [...];
+
+<Table
+  data={users}
+  columns={[
+    { key: 'name', header: 'Name' },
+    { key: 'email', header: 'Email' }
+  ]}
+  keyExtractor={user => user.id}
+/>
+```
+
+### Example 3: React 19 Server Action with Form
+
+```typescript
+// actions/user.ts
+'use server';
+
+export async function updateUser(userId: string, formData: FormData) {
+  const name = formData.get('name') as string;
+  await db.user.update({
+    where: { id: userId },
+    data: { name }
+  });
+  revalidatePath(`/users/${userId}`);
+  return { success: true };
+}
+
+// UserForm.tsx
+'use client';
+
+import { useActionState } from 'react';
+import { updateUser } from '@/actions/user';
+
+function UserForm({ userId }: { userId: string }) {
+  const [state, formAction, isPending] = useActionState(
+    (prev, formData) => updateUser(userId, formData),
+    {}
+  );
+
+  return (
+    <form action={formAction}>
+      <input name="name" />
+      <button disabled={isPending}>
+        {isPending ? 'Saving...' : 'Save'}
+      </button>
+      {state.success && <p>Saved!</p>}
+    </form>
+  );
+}
+```
+
+### Example 4: Type-Safe Event Handlers
+
+```typescript
+function Form() {
+  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    console.log(Object.fromEntries(formData));
+  };
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    console.log(e.target.value); // Typed correctly!
+  };
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === 'Enter') {
+      e.currentTarget.blur(); // currentTarget is typed as HTMLInputElement
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        onChange={handleChange}
+        onKeyDown={handleKeyDown}
+      />
+    </form>
+  );
+}
+```
+
+### Example 5: Custom Hook with Proper Typing
+
+```typescript
+function useToggle(initial = false) {
+  const [value, setValue] = useState(initial);
+  const toggle = () => setValue(v => !v);
+  return [value, toggle] as const; // Tuple type preserved!
+}
+
+// Usage
+const [isOpen, toggleOpen] = useToggle(false);
+// isOpen is boolean, toggleOpen is () => void
+```
+
+### Example 6: TanStack Router Type-Safe Route
+
+```typescript
+import { createRoute } from '@tanstack/react-router';
+import { z } from 'zod';
+
+const userRoute = createRoute({
+  path: '/users/$userId',
+  component: UserPage,
+  loader: async ({ params }) => ({
+    user: await fetchUser(params.userId)
+  }),
+  validateSearch: z.object({
+    tab: z.enum(['profile', 'settings']).optional(),
+    page: z.number().int().positive().default(1),
+  }),
+});
+
+function UserPage() {
+  // All fully typed from the route definition!
+  const { user } = useLoaderData({ from: userRoute.id });
+  const { tab, page } = useSearch({ from: userRoute.id });
+  const { userId } = useParams({ from: userRoute.id });
+
+  return <div>{user.name} - {tab} - Page {page}</div>;
+}
+```
+
+## Output
+
+The skill provides:
+
+1. **Code examples** - Copy-paste ready TypeScript code
+2. **Type definitions** - Exact types to use for your scenarios
+3. **Pattern explanations** - Why patterns work and when to use them
+4. **Migration guides** - Step-by-step updates for React 19
+5. **Reference links** - Pointers to detailed documentation when needed
+
+## Best Practices
+
+### Always Do
+
+✅ **Use specific event types** - `MouseEvent<HTMLButtonElement>` not `React.MouseEvent`
+✅ **Explicit `useState` for unions/null** - `useState<User | null>(null)`
+✅ **Extend native elements** - `ComponentPropsWithoutRef<'button'>`
+✅ **Discriminated unions for variants** - Type-safe props based on variant
+✅ **`as const` for tuple returns** - Preserve tuple types in custom hooks
+✅ **`ref` as prop in React 19** - No `forwardRef` needed
+✅ **`useActionState` for forms** - Not deprecated `useFormState`
+✅ **Type-safe routing patterns** - Use provided router patterns
+
+### Never Do
+
+❌ **Use `any` for event handlers** - Defeats TypeScript's purpose
+❌ **Use `JSX.Element` for children** - Use `ReactNode` instead
+❌ **Use `forwardRef` in React 19+** - It's deprecated
+❌ **Use `useFormState`** - Deprecated in React 19
+❌ **Forget null handling for DOM refs** - Always use `ref?.current`
+❌ **Mix Server/Client in same file** - Will cause hydration errors
+❌ **Await promises before `use()`** - Defeats streaming/Suspense
+
+### Progressive Enhancement
+
+1. **Start simple** - Basic component props and event handlers
+2. **Add constraints** - Discriminated unions, generic constraints
+3. **Leverage inference** - Let TypeScript infer types from usage
+4. **Reference docs when stuck** - Deep dive into specific patterns
+
+### Reference File Organization
+
+The skill includes detailed reference files:
+
+- **hooks.md** - `useState`, `useRef`, `useReducer`, `useContext`, custom hooks
+- **event-handlers.md** - All event types, generic handlers, edge cases
+- **react-19-patterns.md** - `useActionState`, `use()`, `useOptimistic`, migration
+- **generic-components.md** - Table, Select, List, Modal, FormField patterns
+- **server-components.md** - Async components, Server Actions, streaming
+- **tanstack-router.md** - TanStack Router typed routes, search params, navigation
+- **react-router.md** - React Router v7 loaders, actions, type generation
+
+These files are loaded on-demand to keep context efficient. The skill will reference them when deeper knowledge is needed.
+
+## Context Efficiency
+
+This skill follows progressive disclosure principles:
+
+- **Core patterns in SKILL.md** - Most common use cases immediately available
+- **Reference files on-demand** - Deep dives only when needed
+- **Script-free design** - Pure knowledge, no executable scripts needed
+- **Single-level references** - Direct links, no nested includes
+
+This keeps the skill's context footprint minimal while providing comprehensive coverage when needed.
+
+## Version Compatibility
+
+- **React 18** - All patterns work, ignore React 19-specific sections
+- **React 19** - Full support including Server Components, `use()`, `useActionState`
+- **TypeScript 5.0+** - Recommended for best type inference
+- **TanStack Router** - Any version supporting `createRoute`
+- **React Router v7+** - Framework Mode for auto-generated types
+
+## Getting Started
+
+1. **Install the skill** in Claude Code or add to claude.ai project knowledge
+2. **Mention React TypeScript** in your conversation or request
+3. **Reference specific patterns** - "How do I type this event handler?"
+4. **Let Claude suggest patterns** - Describe what you're building
+5. **Explore reference docs** - Ask for deep dives when needed
+
+## Related Skills
+
+- **typescript-patterns** - General TypeScript patterns beyond React
+- **frontend-testing** - Testing typed React components
+- **component-library** - Building design systems with TypeScript
+
+---
+
+**Version:** 1.0.0
+**Last Updated:** 2026-01-20
+**Maintained by:** Softaworks Agent Skills