start-vibing-stacks 2.0.2 → 2.0.4

package/dist/ui.js

@@ -2,7 +2,7 @@
  * Start Vibing Stacks — Terminal UI
  */
 import chalk from 'chalk';
-const VERSION = '2.0.2';
+const VERSION = '2.0.4';
 const gradient = (text) => {
     const colors = [chalk.hex('#FF6B6B'), chalk.hex('#FF8E53'), chalk.hex('#FFBD2E'), chalk.hex('#48BB78'), chalk.hex('#4299E1'), chalk.hex('#9F7AEA')];
     return text.split('').map((c, i) => colors[i % colors.length](c)).join('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/frontend/react/skills/react-patterns/SKILL.md

@@ -104,10 +104,121 @@ const Heavy = lazy(() => import('./HeavyComponent'));
 <Suspense fallback={<Loading />}><Heavy /></Suspense>
 ```
 
+## React 19 Hooks
+
+```tsx
+// useActionState — form submission state
+import { useActionState } from 'react';
+
+function LoginForm() {
+  const [state, formAction, isPending] = useActionState(
+    async (prev, formData: FormData) => {
+      const result = await login(formData);
+      if (result.error) return { error: result.error };
+      redirect('/dashboard');
+    },
+    { error: null }
+  );
+
+  return (
+    <form action={formAction}>
+      <input name="email" type="email" />
+      {state.error && <p className="text-destructive">{state.error}</p>}
+      <button disabled={isPending}>
+        {isPending ? 'Signing in...' : 'Sign In'}
+      </button>
+    </form>
+  );
+}
+
+// useOptimistic — instant UI feedback
+import { useOptimistic } from 'react';
+
+function TodoList({ todos }: { todos: Todo[] }) {
+  const [optimisticTodos, addOptimistic] = useOptimistic(
+    todos,
+    (state, newTodo: Todo) => [...state, newTodo]
+  );
+
+  const addTodo = async (formData: FormData) => {
+    const todo = { id: crypto.randomUUID(), title: formData.get('title') as string, done: false };
+    addOptimistic(todo);  // Instant UI
+    await saveTodo(todo);  // Server sync
+  };
+
+  return <ul>{optimisticTodos.map(t => <li key={t.id}>{t.title}</li>)}</ul>;
+}
+```
+
+## State Management Selection
+
+| Complexity | Solution | When |
+|---|---|---|
+| Simple local | `useState` | Single component, simple values |
+| Complex local | `useReducer` | Multiple related state transitions |
+| Parent-child | Lift state up | 1-2 levels |
+| Subtree | Context + `useReducer` | Theme, auth, 3+ levels |
+| Server state | React Query / SWR | API data, caching, refetch |
+| Complex global | Zustand | Cross-feature, many consumers |
+
+## Error Boundaries
+
+```tsx
+import { Component, type ReactNode } from 'react';
+
+class ErrorBoundary extends Component<
+  { children: ReactNode; fallback?: ReactNode },
+  { hasError: boolean; error?: Error }
+> {
+  state = { hasError: false, error: undefined as Error | undefined };
+
+  static getDerivedStateFromError(error: Error) {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, info: React.ErrorInfo) {
+    console.error('ErrorBoundary caught:', error, info);
+    // Send to Sentry/logging
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback ?? (
+        <div className="p-8 text-center">
+          <h2 className="text-lg font-semibold text-foreground">Something went wrong</h2>
+          <button onClick={() => this.setState({ hasError: false })}
+            className="mt-4 px-4 py-2 bg-primary text-primary-foreground rounded-lg">
+            Try Again
+          </button>
+        </div>
+      );
+    }
+    return this.props.children;
+  }
+}
+
+// Usage: wrap routes/features
+<ErrorBoundary fallback={<ErrorPage />}>
+  <DashboardFeature />
+</ErrorBoundary>
+```
+
+## Component Types
+
+| Type | Use | Example |
+|---|---|---|
+| **Server** (RSC) | Data fetching, static content | Page-level components |
+| **Client** (`'use client'`) | Interactivity, hooks, browser APIs | Forms, modals, dropdowns |
+| **Presentational** | Pure display, props only | `<Badge>`, `<Avatar>` |
+| **Container** | Logic + state, renders presentational | `<UserListContainer>` |
+
 ## FORBIDDEN
 
-1. **Class components** — function components only
+1. **Class components** — function components only (except ErrorBoundary)
 2. **Prop drilling** — use context or composition
 3. **Inline objects/functions in JSX** — causes re-renders
 4. **useEffect for derived state** — use useMemo
 5. **Mutating state directly** — always setState/dispatch
+6. **Index as key** — use stable unique ID (`uuid`, `id`)
+7. **Premature optimization** — profile first with React DevTools
+8. **useEffect for everything** — prefer server components for data

package/stacks/frontend/react/skills/react-standards/SKILL.md

@@ -49,27 +49,139 @@ export default function Dashboard() {
 
 **Rule:** Never leave raw `console.log`. Always use controlled debug pattern.
 
-## TailwindCSS Class Organization
+## TailwindCSS Class Organization (CONST Pattern)
+
+**MANDATORY:** Define all CSS classes as constants at the TOP of the file, before the component.
+
+### Why
+
+1. **No re-renders** — string constants have stable references (no new object per render)
+2. **Single source of truth** — change style once, updates everywhere
+3. **Clean JSX** — readable templates, no class soup
+4. **Prevents React state warnings** — no inline objects/strings changing reference
+5. **Easy theming** — swap tokens in one place
+
+### Pattern
 
 ```tsx
-// ✅ Classes as CONST — clean JSX
-const STYLES = {
-    container: 'flex flex-col gap-4 p-6 bg-white rounded-lg shadow-sm',
-    title: 'text-2xl font-bold text-gray-900',
-    button: 'px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 transition',
-    grid: 'grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6',
-};
+// ═══════════════════════════════════════════
+// 1. TRANSLATIONS (before hooks)
+// ═══════════════════════════════════════════
+const LABELS = {
+    title: __('dashboard.title'),
+    save: __('common.save'),
+} as const;
 
+// ═══════════════════════════════════════════
+// 2. STYLES (semantic tokens, not raw colors)
+// ═══════════════════════════════════════════
+const STYLES = {
+    // Layout
+    page: 'max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8',
+    section: 'space-y-6',
+    grid: 'grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4',
+
+    // Cards
+    card: 'bg-card border border-card-line rounded-xl p-6 hover:shadow-md transition-shadow',
+    cardHeader: 'flex items-center justify-between border-b border-card-divider pb-4 mb-4',
+    cardTitle: 'text-lg font-semibold text-foreground',
+    cardDescription: 'text-sm text-muted-foreground mt-1',
+
+    // Table
+    table: 'w-full text-sm',
+    tableHeader: 'text-left text-muted-foreground font-medium border-b border-border',
+    tableRow: 'border-b border-border hover:bg-muted/50 transition-colors',
+    tableCell: 'px-4 py-3 text-foreground',
+
+    // Buttons
+    btnPrimary: 'px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary-hover font-medium disabled:opacity-50 disabled:cursor-not-allowed transition-colors',
+    btnSecondary: 'px-4 py-2 bg-layer border border-layer-line text-layer-foreground rounded-lg hover:bg-layer-hover font-medium transition-colors',
+    btnDestructive: 'px-4 py-2 bg-destructive text-destructive-foreground rounded-lg hover:bg-destructive-hover font-medium transition-colors',
+    btnGhost: 'px-4 py-2 text-muted-foreground hover:bg-muted rounded-lg transition-colors',
+
+    // Forms
+    input: 'w-full h-10 px-3 rounded-md border border-border bg-background text-foreground placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-ring focus:border-transparent transition-colors',
+    label: 'block text-sm font-medium text-foreground mb-1',
+    fieldError: 'mt-1 text-sm text-destructive',
+
+    // Status badges
+    badgeSuccess: 'inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400',
+    badgeWarning: 'inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-yellow-100 text-yellow-800 dark:bg-yellow-900/30 dark:text-yellow-400',
+    badgeDanger: 'inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-red-100 text-red-800 dark:bg-red-900/30 dark:text-red-400',
+
+    // Typography
+    heading: 'text-2xl font-bold text-foreground',
+    subheading: 'text-lg font-semibold text-foreground',
+    body: 'text-sm text-foreground',
+    muted: 'text-sm text-muted-foreground',
+} as const;
+
+// ═══════════════════════════════════════════
+// 3. COMPONENT
+// ═══════════════════════════════════════════
 export default function Dashboard() {
+    const [data, setData] = useState(null);
+
     return (
-        <div className={STYLES.container}>
-            <h1 className={STYLES.title}>{LABELS.title}</h1>
+        <div className={STYLES.page}>
+            <h1 className={STYLES.heading}>{LABELS.title}</h1>
+            <div className={STYLES.grid}>
+                <div className={STYLES.card}>
+                    <h2 className={STYLES.cardTitle}>Stats</h2>
+                    <p className={STYLES.cardDescription}>Overview</p>
+                </div>
+            </div>
         </div>
     );
 }
+```
+
+### Composing Styles
 
-// ❌ Inline class soup
-<div className="flex flex-col gap-4 p-6 bg-white rounded-lg shadow-sm"> // ❌
+```tsx
+// ✅ Combine with template literal when conditional
+<tr className={`${STYLES.tableRow} ${isSelected ? 'bg-primary/5' : ''}`}>
+
+// ✅ clsx/cn for complex conditions
+import { cn } from '@/lib/utils';
+<button className={cn(STYLES.btnPrimary, isFullWidth && 'w-full', className)}>
+```
+
+### Rules
+
+1. **CONST at top** — before hooks, before component
+2. **`as const`** — TypeScript ensures immutability
+3. **Semantic tokens** — `bg-card` not `bg-white`, `text-foreground` not `text-gray-900`
+4. **No inline class strings > 3 utilities** — extract to STYLES
+5. **Shared styles** — create a `styles.ts` file for cross-component constants
+
+```tsx
+// resources/js/styles.ts — shared across components
+export const SHARED_STYLES = {
+    page: 'max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8',
+    btnPrimary: 'px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary-hover ...',
+    input: 'w-full h-10 px-3 rounded-md border border-border bg-background ...',
+} as const;
+```
+
+### ❌ FORBIDDEN
+
+```tsx
+// ❌ Inline class soup — unreadable, unstable reference
+<div className="flex flex-col gap-4 p-6 bg-white rounded-lg shadow-sm">
+
+// ❌ Raw colors instead of tokens
+const STYLES = { card: 'bg-white text-gray-900' };  // ❌ Breaks dark mode
+
+// ❌ Dynamic class construction (breaks Tailwind purge)
+const color = 'blue';
+<div className={`bg-${color}-500`}>  // ❌ Purged!
+
+// ❌ Styles inside component (new object every render)
+export default function Bad() {
+    const styles = { card: 'bg-card p-4' };  // ❌ Inside = new ref every render
+    return <div className={styles.card} />;
+}
 ```
 
 ## SVG Icons