codecruise 0.1.0

package/config/agents/stack/nextjs/rules/components.md

@@ -0,0 +1,413 @@
+# Component Rules - React & shadcn/ui
+
+Patterns for building maintainable React components.
+
+---
+
+## Component Structure
+
+### COMP-001: Use function components
+
+```typescript
+// GOOD
+function UserCard({ user }: { user: User }) {
+  return <div>...</div>;
+}
+
+// Also good - arrow function for small components
+const Badge = ({ label }: { label: string }) => (
+  <span className="badge">{label}</span>
+);
+
+// Export named, not default (better refactoring)
+export function UserCard({ user }: { user: User }) { ... }
+```
+
+### COMP-002: Prop types with interface
+
+```typescript
+interface UserCardProps {
+  user: User;
+  onEdit?: (user: User) => void;
+  className?: string;
+  children?: React.ReactNode;
+}
+
+function UserCard({ user, onEdit, className, children }: UserCardProps) {
+  return (
+    <Card className={cn('p-4', className)}>
+      <h3>{user.name}</h3>
+      {children}
+      {onEdit && <Button onClick={() => onEdit(user)}>Edit</Button>}
+    </Card>
+  );
+}
+```
+
+### COMP-003: Composition over configuration
+
+```typescript
+// BAD - Too many props
+<Card
+  title="Settings"
+  subtitle="Manage your account"
+  icon={<Settings />}
+  actions={[{ label: 'Save', onClick: save }]}
+  footer={<HelpLink />}
+/>
+
+// GOOD - Composable
+<Card>
+  <CardHeader>
+    <CardIcon><Settings /></CardIcon>
+    <CardTitle>Settings</CardTitle>
+    <CardDescription>Manage your account</CardDescription>
+  </CardHeader>
+  <CardContent>...</CardContent>
+  <CardFooter>
+    <HelpLink />
+    <Button onClick={save}>Save</Button>
+  </CardFooter>
+</Card>
+```
+
+---
+
+## shadcn/ui Patterns
+
+### COMP-004: Use shadcn components correctly
+
+```typescript
+// Button variants
+<Button>Default</Button>
+<Button variant="secondary">Secondary</Button>
+<Button variant="destructive">Delete</Button>
+<Button variant="outline">Outline</Button>
+<Button variant="ghost">Ghost</Button>
+<Button size="sm">Small</Button>
+<Button size="icon"><Plus /></Button>
+
+// With loading state
+<Button disabled={isLoading}>
+  {isLoading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
+  {isLoading ? 'Saving...' : 'Save'}
+</Button>
+
+// As link
+<Button asChild>
+  <Link href="/dashboard">Go to Dashboard</Link>
+</Button>
+```
+
+### COMP-005: Form components with React Hook Form
+
+```typescript
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import {
+  Form,
+  FormControl,
+  FormDescription,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from '@/components/ui/form';
+
+function ProfileForm() {
+  const form = useForm<FormData>({
+    resolver: zodResolver(schema),
+  });
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)}>
+        <FormField
+          control={form.control}
+          name="username"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Username</FormLabel>
+              <FormControl>
+                <Input placeholder="johndoe" {...field} />
+              </FormControl>
+              <FormDescription>
+                This is your public display name.
+              </FormDescription>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+      </form>
+    </Form>
+  );
+}
+```
+
+### COMP-006: Dialog and Sheet patterns
+
+```typescript
+// Controlled dialog
+function EditUserDialog({ user, open, onOpenChange }) {
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Edit User</DialogTitle>
+          <DialogDescription>
+            Make changes to the user profile.
+          </DialogDescription>
+        </DialogHeader>
+        <UserForm user={user} onSuccess={() => onOpenChange(false)} />
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+// With trigger
+function CreateUserButton() {
+  return (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button>Create User</Button>
+      </DialogTrigger>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Create User</DialogTitle>
+        </DialogHeader>
+        <UserForm />
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+---
+
+## State Patterns
+
+### COMP-007: Lift state appropriately
+
+```typescript
+// State lives in lowest common ancestor
+
+// Parent manages shared state
+function UserList() {
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+
+  return (
+    <div className="flex">
+      <UserSidebar
+        selectedId={selectedId}
+        onSelect={setSelectedId}
+      />
+      <UserDetail userId={selectedId} />
+    </div>
+  );
+}
+
+// Children receive props, no local state needed
+function UserSidebar({ selectedId, onSelect }) {
+  const { data: users } = useUsers();
+
+  return (
+    <ul>
+      {users.map(user => (
+        <li
+          key={user.id}
+          className={cn(user.id === selectedId && 'bg-accent')}
+          onClick={() => onSelect(user.id)}
+        >
+          {user.name}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### COMP-008: Use compound components for complex UI
+
+```typescript
+// Compound component pattern
+const TabsContext = createContext<{...} | null>(null);
+
+function Tabs({ children, defaultValue }) {
+  const [value, setValue] = useState(defaultValue);
+
+  return (
+    <TabsContext.Provider value={{ value, setValue }}>
+      <div className="tabs">{children}</div>
+    </TabsContext.Provider>
+  );
+}
+
+function TabsList({ children }) {
+  return <div className="tabs-list">{children}</div>;
+}
+
+function TabsTrigger({ value, children }) {
+  const { value: selected, setValue } = useContext(TabsContext);
+
+  return (
+    <button
+      className={cn('tab', value === selected && 'active')}
+      onClick={() => setValue(value)}
+    >
+      {children}
+    </button>
+  );
+}
+
+function TabsContent({ value, children }) {
+  const { value: selected } = useContext(TabsContext);
+  if (value !== selected) return null;
+  return <div className="tab-content">{children}</div>;
+}
+
+// Usage
+<Tabs defaultValue="account">
+  <TabsList>
+    <TabsTrigger value="account">Account</TabsTrigger>
+    <TabsTrigger value="security">Security</TabsTrigger>
+  </TabsList>
+  <TabsContent value="account">...</TabsContent>
+  <TabsContent value="security">...</TabsContent>
+</Tabs>
+```
+
+---
+
+## Event Handling
+
+### COMP-009: Memoize callbacks appropriately
+
+```typescript
+// Only memoize when passing to memoized children
+// or when callback identity matters
+
+// Usually NOT needed
+function UserList() {
+  const handleClick = (id: string) => {
+    // This is fine, UserItem likely re-renders anyway
+  };
+
+  return users.map(u => <UserItem key={u.id} onClick={() => handleClick(u.id)} />);
+}
+
+// Memoize when passing to virtualized lists or heavy components
+const handleClick = useCallback((id: string) => {
+  setSelected(id);
+}, []);
+
+// Or when used in effects
+const fetchUser = useCallback(async () => {
+  const user = await getUser(userId);
+  setUser(user);
+}, [userId]);
+
+useEffect(() => {
+  fetchUser();
+}, [fetchUser]);
+```
+
+### COMP-010: Handle async actions in forms
+
+```typescript
+function SubmitButton() {
+  const { pending } = useFormStatus();
+
+  return (
+    <Button type="submit" disabled={pending}>
+      {pending ? (
+        <>
+          <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+          Saving...
+        </>
+      ) : (
+        'Save'
+      )}
+    </Button>
+  );
+}
+
+function UserForm() {
+  const [state, formAction] = useFormState(createUser, initialState);
+
+  return (
+    <form action={formAction}>
+      {state?.error && <Alert variant="destructive">{state.error}</Alert>}
+      <Input name="email" />
+      <SubmitButton />
+    </form>
+  );
+}
+```
+
+---
+
+## Accessibility
+
+### COMP-011: Use semantic HTML
+
+```typescript
+// GOOD
+<nav aria-label="Main navigation">
+  <ul>
+    <li><Link href="/">Home</Link></li>
+  </ul>
+</nav>
+
+<main>
+  <article>
+    <h1>Title</h1>
+    <p>Content</p>
+  </article>
+</main>
+
+<button onClick={handleClick}>Click me</button>
+
+// BAD
+<div onClick={handleClick}>Click me</div>
+```
+
+### COMP-012: Accessible forms
+
+```typescript
+// Labels
+<label htmlFor="email">Email</label>
+<input id="email" type="email" aria-describedby="email-hint" />
+<p id="email-hint">We'll never share your email.</p>
+
+// Required fields
+<label htmlFor="name">
+  Name <span aria-hidden="true">*</span>
+  <span className="sr-only">(required)</span>
+</label>
+<input id="name" required aria-required="true" />
+
+// Error states
+<input
+  id="email"
+  aria-invalid={hasError}
+  aria-describedby={hasError ? 'email-error' : undefined}
+/>
+{hasError && <p id="email-error" role="alert">Invalid email</p>}
+```
+
+### COMP-013: Screen reader utilities
+
+```typescript
+// Visually hidden but accessible
+<span className="sr-only">Open menu</span>
+
+// Skip link
+<a href="#main-content" className="sr-only focus:not-sr-only">
+  Skip to main content
+</a>
+
+// Live regions
+<div aria-live="polite" aria-atomic="true">
+  {notification}
+</div>
+```