start-vibing-stacks 2.8.0 → 2.10.0

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

@@ -0,0 +1,509 @@
+---
+name: react-api-standards
+version: 1.0.0
+description: React 19 + Vite + Axios standards for a Laravel-backed JSON API SPA
+  — Page shell + skeleton, async data via `api.get`, form 422 binding, route
+  catch-all, no Inertia. Use for any new React page in a Laravel + Sanctum SPA
+  project. Pairs with `axios-laravel-api` and `laravel-api-architecture`.
+---
+
+# React 19 API-First Standards (Laravel + Axios)
+
+**ALWAYS invoke when creating React pages, components, or layouts in a project
+that uses a Laravel JSON API as backend (NOT Inertia.js).**
+
+## Version Requirements
+
+- **React >= 19** — MANDATORY (`useActionState`, `useOptimistic`, `use`)
+- **Vite >= 5** with `@vitejs/plugin-react`
+- **TailwindCSS >= 4**
+- **Axios >= 1.6** (for `withXSRFToken` support)
+- **TanStack Query >= 5** (recommended for cached lists/details)
+- **react-router-dom >= 6** (client-side routing)
+
+## Folder Structure
+
+```
+resources/js/
+├── app.jsx                       # Root: <BrowserRouter> + <QueryClientProvider>
+├── App.jsx                       # Top-level <Routes> with <ProtectedRoute>
+├── lib/
+│   ├── api.js                    # Axios instance (see axios-laravel-api skill)
+│   ├── auth.js                   # login/logout/fetchCurrentUser
+│   ├── queryClient.ts            # TanStack QueryClient config
+│   └── utils.ts                  # cn(), formatters, date helpers
+├── Pages/
+│   ├── Dashboard/
+│   │   └── Index.tsx             # Renders shell+skeleton; calls api.get
+│   ├── Users/
+│   │   ├── Index.tsx
+│   │   ├── Show.tsx
+│   │   └── _components/          # Page-private components
+│   │       ├── UsersTable.tsx
+│   │       └── UsersTableSkeleton.tsx
+│   └── Auth/
+│       ├── Login.tsx
+│       └── Register.tsx
+├── Components/                   # Reusable cross-page components
+│   ├── ErrorState.tsx
+│   ├── EmptyState.tsx
+│   ├── ProtectedRoute.tsx
+│   └── SectionLoader.tsx
+├── Layouts/
+│   ├── AuthenticatedLayout.tsx
+│   └── GuestLayout.tsx
+├── Icons/                        # Each icon is a separate .svg file
+│   ├── index.js                  # Barrel
+│   ├── CheckIcon.svg
+│   └── AlertIcon.svg
+└── store/                        # Zustand / Context for cross-page UI state
+    └── auth.ts
+```
+
+## The Page Contract
+
+Every Page component MUST:
+
+1. **Render shell + skeleton on first paint** — never block on data.
+2. **Fetch via `api` instance** (or `useQuery`) — never raw `axios`/`fetch`.
+3. **Show error/empty/loading states** before the happy path.
+4. **Define `LABELS` and `STYLES` as `const` ABOVE the component** — stable refs.
+
+```tsx
+import { useEffect, useState } from 'react';
+import api from '@/lib/api';
+import ErrorState from '@/Components/ErrorState';
+import EmptyState from '@/Components/EmptyState';
+import OrdersTable from './_components/OrdersTable';
+import OrdersTableSkeleton from './_components/OrdersTableSkeleton';
+
+const LABELS = {
+    title: 'Orders',
+    empty: 'No orders yet',
+    emptyHint: 'Orders will appear here once customers start checking out.',
+} as const;
+
+const STYLES = {
+    page: 'max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8',
+    heading: 'text-2xl font-bold text-foreground',
+    section: 'mt-6',
+} as const;
+
+export default function OrdersIndexPage() {
+    const [data, setData] = useState<{ data: Order[]; meta: Meta } | null>(null);
+    const [error, setError] = useState<string | null>(null);
+    const [loading, setLoading] = useState(true);
+
+    const load = async () => {
+        try {
+            setError(null);
+            setLoading(true);
+            const res = await api.get('/api/orders');
+            setData(res.data);
+        } catch (e: any) {
+            setError(e.response?.data?.message ?? 'Failed to load orders');
+        } finally {
+            setLoading(false);
+        }
+    };
+
+    useEffect(() => { load(); }, []);
+
+    return (
+        <div className={STYLES.page}>
+            <h1 className={STYLES.heading}>{LABELS.title}</h1>
+
+            <section className={STYLES.section}>
+                {error && <ErrorState error={error} onRetry={load} />}
+                {!error && loading && !data && <OrdersTableSkeleton />}
+                {!error && data && data.data.length === 0 && (
+                    <EmptyState title={LABELS.empty} description={LABELS.emptyHint} />
+                )}
+                {!error && data && data.data.length > 0 && (
+                    <OrdersTable orders={data.data} meta={data.meta} />
+                )}
+            </section>
+        </div>
+    );
+}
+```
+
+## TanStack Query Variant (Preferred for any List/Detail)
+
+```tsx
+import { useQuery } from '@tanstack/react-query';
+import { useSearchParams } from 'react-router-dom';
+import api from '@/lib/api';
+
+const fetchOrders = async (params: { page: number; per_page: number; status?: string }) => {
+    const { data } = await api.get('/api/orders', { params });
+    return data;
+};
+
+export default function OrdersIndexPage() {
+    const [searchParams, setSearchParams] = useSearchParams();
+    const page = Number(searchParams.get('page') ?? 1);
+    const status = searchParams.get('status') ?? undefined;
+
+    const { data, error, isPending, refetch } = useQuery({
+        queryKey: ['orders', { page, status }],
+        queryFn: () => fetchOrders({ page, per_page: 25, status }),
+        placeholderData: (prev) => prev,        // smooth pagination
+    });
+
+    if (error) return <ErrorState error={error} onRetry={refetch} />;
+    if (isPending && !data) return <OrdersTableSkeleton />;
+    if (!data?.data.length) return <EmptyState title={LABELS.empty} />;
+
+    return (
+        <OrdersTable
+            orders={data.data}
+            meta={data.meta}
+            onPageChange={(p) => setSearchParams({ page: String(p), status: status ?? '' })}
+        />
+    );
+}
+```
+
+**Rules:**
+
+- `queryKey` MUST include all filter inputs that change the response.
+- `placeholderData: (prev) => prev` keeps the old table visible while the new
+  page loads — no skeleton flash on pagination.
+- URL state via `useSearchParams` so users can bookmark filtered views.
+
+## Mutations + Optimistic UI
+
+```tsx
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import api from '@/lib/api';
+
+function ToggleArchive({ order }: { order: Order }) {
+    const qc = useQueryClient();
+    const m = useMutation({
+        mutationFn: () => api.post(`/api/orders/${order.id}/archive`),
+        onMutate: async () => {
+            await qc.cancelQueries({ queryKey: ['orders'] });
+            const prev = qc.getQueriesData<any>({ queryKey: ['orders'] });
+            qc.setQueriesData({ queryKey: ['orders'] }, (old: any) => ({
+                ...old,
+                data: old.data.map((o: Order) =>
+                    o.id === order.id ? { ...o, archived: !o.archived } : o,
+                ),
+            }));
+            return { prev };
+        },
+        onError: (_err, _vars, ctx) => {
+            ctx?.prev?.forEach(([key, value]) => qc.setQueryData(key, value));
+        },
+        onSettled: () => qc.invalidateQueries({ queryKey: ['orders'] }),
+    });
+    return <button onClick={() => m.mutate()} disabled={m.isPending}>Archive</button>;
+}
+```
+
+## Forms — 422 Validation Binding
+
+```tsx
+import { useState } from 'react';
+import api from '@/lib/api';
+
+const STYLES = {
+    form: 'space-y-4 max-w-md',
+    label: 'block text-sm font-medium text-foreground mb-1',
+    input: 'w-full h-10 px-3 rounded-md border border-border bg-background',
+    inputError: 'w-full h-10 px-3 rounded-md border border-destructive bg-background',
+    error: 'mt-1 text-sm text-destructive',
+    btn: 'px-4 py-2 bg-primary text-primary-foreground rounded-lg disabled:opacity-50',
+} as const;
+
+export default function CreateOrderForm({ onCreated }: { onCreated: () => void }) {
+    const [form, setForm] = useState({ product_id: '', quantity: 1 });
+    const [errors, setErrors] = useState<Record<string, string[]>>({});
+    const [submitting, setSubmitting] = useState(false);
+
+    const submit = async (e: React.FormEvent) => {
+        e.preventDefault();
+        setErrors({});
+        setSubmitting(true);
+        try {
+            const { data } = await api.post('/api/orders', form);
+            onCreated();
+        } catch (err: any) {
+            if (err.validation) setErrors(err.validation);
+        } finally {
+            setSubmitting(false);
+        }
+    };
+
+    const cls = (field: string) =>
+        errors[field]?.length ? STYLES.inputError : STYLES.input;
+
+    return (
+        <form className={STYLES.form} onSubmit={submit}>
+            <div>
+                <label className={STYLES.label}>Product ID</label>
+                <input
+                    className={cls('product_id')}
+                    value={form.product_id}
+                    onChange={(e) => setForm({ ...form, product_id: e.target.value })}
+                />
+                {errors.product_id?.[0] && (
+                    <p className={STYLES.error}>{errors.product_id[0]}</p>
+                )}
+            </div>
+
+            <button type="submit" disabled={submitting} className={STYLES.btn}>
+                {submitting ? 'Creating…' : 'Create Order'}
+            </button>
+        </form>
+    );
+}
+```
+
+## Authentication Layer
+
+```tsx
+// resources/js/store/auth.ts
+import { create } from 'zustand';
+import api from '@/lib/api';
+import { fetchCurrentUser, login as doLogin, logout as doLogout } from '@/lib/auth';
+
+interface AuthState {
+    user: User | null;
+    booted: boolean;
+    boot: () => Promise<void>;
+    login: (email: string, password: string) => Promise<void>;
+    logout: () => Promise<void>;
+}
+
+export const useAuth = create<AuthState>((set) => ({
+    user: null,
+    booted: false,
+    boot: async () => {
+        try {
+            const user = await fetchCurrentUser();
+            set({ user, booted: true });
+        } catch {
+            set({ user: null, booted: true });
+        }
+    },
+    login: async (email, password) => {
+        await doLogin(email, password);
+        const user = await fetchCurrentUser();
+        set({ user });
+    },
+    logout: async () => {
+        await doLogout();
+        set({ user: null });
+    },
+}));
+```
+
+```tsx
+// resources/js/Components/ProtectedRoute.tsx
+import { Navigate, useLocation } from 'react-router-dom';
+import { useAuth } from '@/store/auth';
+import SectionLoader from './SectionLoader';
+
+export default function ProtectedRoute({ children }: { children: React.ReactNode }) {
+    const { user, booted } = useAuth();
+    const location = useLocation();
+
+    if (!booted) return <SectionLoader />;
+    if (!user) return <Navigate to="/login" state={{ from: location }} replace />;
+
+    return <>{children}</>;
+}
+```
+
+```tsx
+// resources/js/App.tsx
+import { useEffect } from 'react';
+import { Routes, Route } from 'react-router-dom';
+import { useAuth } from './store/auth';
+import ProtectedRoute from './Components/ProtectedRoute';
+import AuthenticatedLayout from './Layouts/AuthenticatedLayout';
+import LoginPage from './Pages/Auth/Login';
+import DashboardPage from './Pages/Dashboard/Index';
+
+export default function App() {
+    const boot = useAuth((s) => s.boot);
+    useEffect(() => { boot(); }, [boot]);
+
+    return (
+        <Routes>
+            <Route path="/login" element={<LoginPage />} />
+            <Route element={<ProtectedRoute><AuthenticatedLayout /></ProtectedRoute>}>
+                <Route path="/" element={<DashboardPage />} />
+                {/* ... */}
+            </Route>
+        </Routes>
+    );
+}
+```
+
+## Skeletons — One per Component, Match the Shape
+
+```tsx
+// resources/js/Pages/Orders/_components/OrdersTableSkeleton.tsx
+const STYLES = {
+    table: 'w-full',
+    headerRow: 'border-b border-border',
+    headerCell: 'h-4 w-24 bg-muted rounded animate-pulse my-3 mx-4',
+    row: 'border-b border-border',
+    cell: 'h-4 w-full bg-muted rounded animate-pulse my-4 mx-4',
+} as const;
+
+export default function OrdersTableSkeleton({ rows = 8 }: { rows?: number }) {
+    return (
+        <div role="status" aria-label="Loading orders" className={STYLES.table}>
+            <div className={STYLES.headerRow}>
+                {Array.from({ length: 4 }).map((_, i) => (
+                    <div key={i} className={STYLES.headerCell} />
+                ))}
+            </div>
+            {Array.from({ length: rows }).map((_, r) => (
+                <div key={r} className={STYLES.row}>
+                    {Array.from({ length: 4 }).map((_, c) => (
+                        <div key={c} className={STYLES.cell} />
+                    ))}
+                </div>
+            ))}
+        </div>
+    );
+}
+```
+
+## Error & Empty States (Reusable)
+
+```tsx
+// resources/js/Components/ErrorState.tsx
+const STYLES = {
+    wrap: 'flex flex-col items-center justify-center py-12 text-center',
+    icon: 'h-12 w-12 rounded-full bg-destructive/10 flex items-center justify-center mb-4',
+    title: 'text-lg font-semibold text-foreground',
+    msg: 'mt-1 text-sm text-muted-foreground max-w-md',
+    btn: 'mt-4 px-4 py-2 bg-primary text-primary-foreground rounded-lg',
+} as const;
+
+export default function ErrorState({
+    error, onRetry, title = 'Something went wrong',
+}: { error: unknown; onRetry?: () => void; title?: string }) {
+    const message = typeof error === 'string'
+        ? error
+        : (error as any)?.message ?? 'Please try again.';
+    return (
+        <div className={STYLES.wrap}>
+            <div className={STYLES.icon}>!</div>
+            <h3 className={STYLES.title}>{title}</h3>
+            <p className={STYLES.msg}>{message}</p>
+            {onRetry && <button className={STYLES.btn} onClick={onRetry}>Try again</button>}
+        </div>
+    );
+}
+```
+
+## TypeScript — Shape Types from Resources
+
+```ts
+// resources/js/types/index.d.ts
+
+export interface PaginatedResponse<T> {
+    data: T[];
+    meta: {
+        current_page: number;
+        last_page: number;
+        per_page: number;
+        total: number;
+    };
+    links: {
+        first: string | null;
+        last: string | null;
+        next: string | null;
+        prev: string | null;
+    };
+}
+
+export interface User {
+    id: string;
+    name: string;
+    email: string;
+    role: 'user' | 'admin' | 'superadmin';
+    created_at: string;
+    updated_at: string;
+}
+
+export interface Order {
+    id: string;
+    product_id: string;
+    quantity: number;
+    status: 'pending' | 'paid' | 'shipped' | 'cancelled';
+    created_at: string;
+}
+```
+
+**Rule:** Types live in `resources/js/types/`, NOT scattered in components.
+Match the field names from your Laravel API Resources exactly.
+
+## Path Aliases (`@/...`)
+
+```js
+// vite.config.js
+import path from 'path';
+
+resolve: {
+    alias: {
+        '@': path.resolve(__dirname, 'resources/js'),
+    },
+},
+```
+
+```json
+// tsconfig.json
+{
+    "compilerOptions": {
+        "baseUrl": ".",
+        "paths": {
+            "@/*": ["resources/js/*"]
+        }
+    }
+}
+```
+
+## Checklist — Before Shipping a Page
+
+- [ ] Renders shell + heading on first paint (no waterfall blocking)
+- [ ] Skeleton matches the shape of the loaded content
+- [ ] Error state with retry handler
+- [ ] Empty state for collections
+- [ ] All API calls go through `@/lib/api` (interceptors apply)
+- [ ] Form errors bound from `error.validation` (422)
+- [ ] LABELS + STYLES defined as `const` above the component
+- [ ] Page is wrapped in `<ProtectedRoute>` if auth required
+- [ ] Filters reflected in URL via `useSearchParams`
+
+## FORBIDDEN
+
+| Pattern | Reason | Use Instead |
+|--------|--------|-------------|
+| `Inertia::render()` for new pages | Blocks first paint on DB | `api.get()` from React |
+| `fetch()` in components | Bypasses CSRF/interceptors | `api.get/post/...` |
+| `axios.get(...)` direct | Bypasses interceptors | `import api from '@/lib/api'` |
+| `useEffect` to derive state | Anti-pattern | `useMemo` |
+| `<a href>` for internal links | Full reload | `<Link>` from react-router-dom |
+| `window.location.assign` for SPA nav | Full reload | `useNavigate()` |
+| `localStorage` for tokens | XSS-readable | HttpOnly session cookie (Sanctum) |
+| Skipping skeleton/empty/error states | Bad UX | All three are mandatory per page |
+| Inline Tailwind class soup | Unstable refs | `STYLES` const at top |
+| `__()`-style i18n inside JSX | React Hook violation | LABELS const at top |
+| `dd()`-style debug | n/a in JS | Controlled debug constant pattern |
+| Storing API tokens in `VITE_*` | Bundled = public | Server-side via session/Sanctum |
+
+## See Also
+
+- `axios-laravel-api` — the `api.js` instance and Sanctum CSRF flow
+- `laravel-api-architecture` — the backend Controller→Service→Resource pipeline
+- `react-patterns` — generic React 19 hooks (`useActionState`, `useOptimistic`)
+- `react-ui-patterns` — loading/error/empty patterns and decision tree
+- `tailwind-patterns` — utility class composition with `cn()`

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

@@ -1,9 +1,18 @@
 ---
 name: inertia-react
-version: 1.0.0
+version: 2.0.0
+description: LEGACY skill — Inertia.js + React frontend integration with
+  Laravel-rendered pages. Use ONLY in pre-existing Inertia projects. For NEW
+  projects use the `react-api` frontend stack (`axios-laravel-api` +
+  `react-api-standards`) which decouples render from data fetching.
 ---
 
-# Inertia.js + React Integration
+# Inertia.js + React Integration (LEGACY)
+
+> **STATUS: LEGACY.** New projects use the **React API SPA** stack — Laravel
+> serves a Vite shell, React owns routing client-side, and data is fetched via
+> Axios with Sanctum cookie auth. See `axios-laravel-api` and
+> `react-api-standards`.
 
 ## Architecture Overview
 

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

@@ -1,9 +1,16 @@
 ---
 name: react-standards
-version: 1.0.0
+version: 2.0.0
+description: LEGACY — React 19 standards for Inertia.js projects (controller
+  props, useForm, Inertia router). Use ONLY in pre-existing Inertia projects.
+  For NEW projects use `react-api-standards` (Axios + TanStack Query + React
+  Router) instead.
 ---
 
-# React 19+ Standards (with Inertia.js)
+# React 19+ Standards with Inertia.js (LEGACY)
+
+> **STATUS: LEGACY.** New projects use `react-api-standards` (API-first SPA).
+> Keep this loaded only for legacy Inertia codebases.
 
 ## Version Requirements