start-vibing-stacks 2.0.0 → 2.0.2

package/dist/ui.js

@@ -2,7 +2,7 @@
  * Start Vibing Stacks — Terminal UI
  */
 import chalk from 'chalk';
-const VERSION = '2.0.0';
+const VERSION = '2.0.2';
 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.0",
+  "version": "2.0.2",
   "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/preline-ui/SKILL.md

@@ -12,31 +12,49 @@ Preline is a **semantic token-based design system** built on TailwindCSS. It pro
 
 ## Installation (Laravel + Inertia)
 
+### Step 1: Install
+
 ```bash
-npm install preline
+npm install preline @tailwindcss/forms
+```
+
+### Step 2: CSS Config
+
+```css
+/* resources/css/app.css */
+@import "tailwindcss";
+
+/* Preline — MUST be in this order */
+@source "./node_modules/preline/dist/*.js";    /* JS component scanning */
+@import "./node_modules/preline/variants.css";  /* CSS variants */
+@plugin "@tailwindcss/forms";                   /* Forms plugin */
+@import "./node_modules/preline/themes/theme.css"; /* Base theme */
 ```
 
+### Step 3: Vite Config
+
 ```js
 // vite.config.js
+import { defineConfig } from 'vite';
+import laravel from 'laravel-vite-plugin';
+import react from '@vitejs/plugin-react';
+
 export default defineConfig({
   plugins: [
-    laravel({ input: ['resources/css/app.css', 'resources/js/app.tsx'] }),
+    laravel({ input: ['resources/css/app.css', 'resources/js/app.tsx'], refresh: true }),
+    react(),
   ],
 });
 ```
 
-```css
-/* resources/css/app.css */
-@import "tailwindcss";
-@import "preline/themes/theme.css";
-```
+### Step 4: Init Preline in Inertia (MANDATORY)
 
 ```tsx
-// resources/js/app.tsx — init Preline after Inertia navigation
+// resources/js/app.tsx
 import { router } from '@inertiajs/react';
 
+// Re-init Preline components after every SPA navigation
 router.on('navigate', () => {
-  // Re-init Preline components after SPA navigation
   setTimeout(() => {
     import('preline/preline').then(({ HSStaticMethods }) => {
       HSStaticMethods.autoInit();
@@ -45,6 +63,77 @@ router.on('navigate', () => {
 });
 ```
 
+**Rule:** Without `HSStaticMethods.autoInit()`, dropdowns, modals, and accordions will NOT work after Inertia navigation.
+
+## Templates & Components (840+ free)
+
+### Where to Find
+
+| Source | URL | What |
+|---|---|---|
+| **Docs (components)** | https://preline.co/docs | Buttons, modals, forms, tables, navs |
+| **Examples (blocks)** | https://preline.co/examples.html | 220+ UI blocks (hero, testimonials, pricing, etc.) |
+| **Pro templates** | https://preline.co/pro/templates.html | 21 dashboard/app templates (paid) |
+| **GitHub** | https://github.com/htmlstreamofficial/preline | Source + examples |
+
+### How to Use Templates
+
+1. Browse https://preline.co/examples.html
+2. Click a block → copy the HTML/JSX
+3. Adapt to React + Inertia:
+   - Replace `<a href>` with `<Link href>` (Inertia)
+   - Replace `class=` with `className=`
+   - Add Preline `data-*` attributes for interactive components
+   - Use `usePage().props` for dynamic data
+
+### Example: Copy a Hero Block
+
+```tsx
+// From preline.co/examples.html → Hero sections
+// Adapt HTML to React component:
+export default function HeroSection() {
+  return (
+    <div className="relative overflow-hidden">
+      <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-24">
+        <div className="text-center">
+          <h1 className="text-4xl sm:text-6xl font-bold text-foreground">
+            Build your next idea
+          </h1>
+          <p className="mt-4 text-lg text-muted-foreground max-w-2xl mx-auto">
+            Preline UI is an open-source set of prebuilt UI components.
+          </p>
+          <div className="mt-8 flex justify-center gap-3">
+            <Link href="/register"
+              className="px-6 py-3 bg-primary text-primary-foreground rounded-lg hover:bg-primary-hover font-medium transition-colors">
+              Get Started
+            </Link>
+            <Link href="/docs"
+              className="px-6 py-3 bg-layer border border-layer-line text-layer-foreground rounded-lg hover:bg-layer-hover font-medium transition-colors">
+              Documentation
+            </Link>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### Key Component Categories (free)
+
+| Category | Count | Examples |
+|---|---|---|
+| **Navigation** | 20+ | Navbar, sidebar, breadcrumb, pagination |
+| **Hero** | 11 | Landing page headers |
+| **Cards** | 15+ | Product, blog, profile, pricing |
+| **Forms** | 20+ | Login, register, contact, checkout |
+| **Tables** | 10+ | Sortable, paginated, striped |
+| **Modals** | 8+ | Confirmation, form, full-screen |
+| **Dropdowns** | 10+ | Menu, select, multi-select |
+| **Testimonials** | 10+ | Quotes, carousel, grid |
+| **Pricing** | 8+ | Monthly/yearly toggle, comparison |
+| **Dashboard** | 5+ | Stats, charts, activity feed |
+
 ## Token Architecture
 
 ```

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

@@ -0,0 +1,298 @@
+# React UI Patterns — Loading, Errors, Empty States & Forms
+
+**ALWAYS invoke when handling async UI states, forms, or user feedback.**
+
+## Core Principles
+
+1. **Never show stale UI** — loading only when actually loading
+2. **Always surface errors** — users must KNOW when something fails
+3. **Optimistic updates** — make UI feel instant
+4. **Progressive disclosure** — show content as it becomes available
+5. **Disable during operations** — prevent double-submit
+
+## Loading State Decision Tree
+
+```
+Error?
+  → Yes: Show ErrorState with retry
+  → No ↓
+
+Loading AND no data?
+  → Yes: Show Skeleton or Spinner
+  → No ↓
+
+Has data?
+  → Yes + items: Render data
+  → Yes + empty: Show EmptyState
+  → No: Show Spinner (fallback)
+```
+
+```tsx
+// ✅ CORRECT — only loading when no data
+const { data, isLoading, error, refetch } = useQuery(...);
+
+if (error) return <ErrorState error={error} onRetry={refetch} />;
+if (isLoading && !data) return <Skeleton />;
+if (!data?.items.length) return <EmptyState />;
+return <ItemList items={data.items} />;
+
+// ❌ WRONG — flashes spinner on refetch when cached data exists
+if (isLoading) return <Spinner />;
+```
+
+### Skeleton vs Spinner
+
+| Use Skeleton | Use Spinner |
+|---|---|
+| Known content shape (cards, tables, lists) | Unknown shape (modals, inline actions) |
+| Initial page load | Button submissions |
+| Content placeholders | Small inline operations |
+
+```tsx
+// Skeleton component
+function CardSkeleton() {
+  return (
+    <div className="bg-card border border-card-line rounded-xl p-6 animate-pulse">
+      <div className="h-4 w-3/4 bg-muted rounded" />
+      <div className="mt-3 h-3 w-1/2 bg-muted rounded" />
+      <div className="mt-6 h-10 w-full bg-muted rounded" />
+    </div>
+  );
+}
+
+// Skeleton grid
+function ListSkeleton({ count = 6 }: { count?: number }) {
+  return (
+    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+      {Array.from({ length: count }, (_, i) => <CardSkeleton key={i} />)}
+    </div>
+  );
+}
+```
+
+## Error Handling Hierarchy
+
+```
+Level 1 — Inline error      → Field validation (under input)
+Level 2 — Toast notification → Recoverable, user can retry
+Level 3 — Error banner      → Page-level, data partially usable
+Level 4 — Full error screen → Unrecoverable, needs user action
+```
+
+```tsx
+// Reusable ErrorState
+interface ErrorStateProps {
+  error: Error | string;
+  onRetry?: () => void;
+  title?: string;
+}
+
+function ErrorState({ error, onRetry, title }: ErrorStateProps) {
+  const message = typeof error === 'string' ? error : error.message;
+  return (
+    <div className="flex flex-col items-center justify-center py-12 text-center">
+      <div className="h-12 w-12 rounded-full bg-destructive/10 flex items-center justify-center mb-4">
+        <AlertCircle className="h-6 w-6 text-destructive" />
+      </div>
+      <h3 className="text-lg font-semibold text-foreground">{title ?? 'Something went wrong'}</h3>
+      <p className="mt-1 text-sm text-muted-foreground max-w-md">{message}</p>
+      {onRetry && (
+        <button onClick={onRetry}
+          className="mt-4 px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary-hover transition-colors">
+          Try Again
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+### NEVER Swallow Errors
+
+```tsx
+// ✅ CORRECT — error surfaced to user
+const mutation = useMutation({
+  mutationFn: createItem,
+  onSuccess: () => toast.success('Item created!'),
+  onError: (error) => {
+    console.error('createItem failed:', error);
+    toast.error('Failed to create item');
+  },
+});
+
+// ❌ WRONG — user sees nothing
+try { await createItem(data); }
+catch (e) { console.log(e); }  // Silent failure!
+```
+
+## Empty States
+
+**Every list/collection MUST have an empty state.**
+
+```tsx
+// ✅ With empty state
+function UserList({ users }: { users: User[] }) {
+  if (!users.length) {
+    return (
+      <EmptyState
+        icon={<Users className="h-8 w-8" />}
+        title="No users yet"
+        description="Invite your first team member"
+        action={{ label: 'Invite User', onClick: () => router.visit('/users/invite') }}
+      />
+    );
+  }
+  return <div className="space-y-2">{users.map(u => <UserCard key={u.id} user={u} />)}</div>;
+}
+
+// Reusable EmptyState
+function EmptyState({ icon, title, description, action }: {
+  icon: ReactNode;
+  title: string;
+  description: string;
+  action?: { label: string; onClick: () => void };
+}) {
+  return (
+    <div className="flex flex-col items-center justify-center py-16 text-center">
+      <div className="text-muted-foreground mb-4">{icon}</div>
+      <h3 className="text-lg font-semibold text-foreground">{title}</h3>
+      <p className="mt-1 text-sm text-muted-foreground max-w-sm">{description}</p>
+      {action && (
+        <button onClick={action.onClick}
+          className="mt-4 px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary-hover transition-colors">
+          {action.label}
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+## Button States
+
+```tsx
+// ✅ CORRECT — disabled + loading indicator
+<button
+  onClick={handleSubmit}
+  disabled={!isValid || isSubmitting}
+  className="bg-primary text-primary-foreground px-4 py-2 rounded-lg hover:bg-primary-hover disabled:opacity-50 disabled:cursor-not-allowed transition-colors"
+>
+  {isSubmitting ? (
+    <span className="flex items-center gap-2">
+      <Loader className="h-4 w-4 animate-spin" />
+      Saving...
+    </span>
+  ) : 'Save'}
+</button>
+
+// ❌ WRONG — user can click multiple times
+<button onClick={handleSubmit}>
+  {isSubmitting ? 'Submitting...' : 'Submit'}
+</button>
+```
+
+## Form Pattern (Inertia.js)
+
+```tsx
+import { useForm } from '@inertiajs/react';
+
+export default function CreateUser() {
+  const { data, setData, post, processing, errors, reset } = useForm({
+    name: '',
+    email: '',
+  });
+
+  const submit = (e: React.FormEvent) => {
+    e.preventDefault();
+    post('/users', {
+      onSuccess: () => {
+        toast.success('User created!');
+        reset();
+      },
+      onError: () => toast.error('Failed to create user'),
+    });
+  };
+
+  return (
+    <form onSubmit={submit} className="space-y-4">
+      <div>
+        <label className="block text-sm font-medium text-foreground mb-1">Name</label>
+        <input
+          value={data.name}
+          onChange={e => setData('name', e.target.value)}
+          className="w-full h-10 px-3 rounded-md border border-border bg-background text-foreground"
+        />
+        {errors.name && <p className="mt-1 text-sm text-destructive">{errors.name}</p>}
+      </div>
+
+      <div>
+        <label className="block text-sm font-medium text-foreground mb-1">Email</label>
+        <input
+          type="email"
+          value={data.email}
+          onChange={e => setData('email', e.target.value)}
+          className="w-full h-10 px-3 rounded-md border border-border bg-background text-foreground"
+        />
+        {errors.email && <p className="mt-1 text-sm text-destructive">{errors.email}</p>}
+      </div>
+
+      <button
+        type="submit"
+        disabled={processing}
+        className="bg-primary text-primary-foreground px-6 py-2 rounded-lg hover:bg-primary-hover disabled:opacity-50 transition-colors"
+      >
+        {processing ? (
+          <span className="flex items-center gap-2">
+            <Loader className="h-4 w-4 animate-spin" /> Creating...
+          </span>
+        ) : 'Create User'}
+      </button>
+    </form>
+  );
+}
+```
+
+## Optimistic Updates
+
+```tsx
+// Show result immediately, rollback on error
+function ToggleFavorite({ item }: { item: Item }) {
+  const [optimistic, setOptimistic] = useState(item.isFavorite);
+
+  const toggle = () => {
+    setOptimistic(!optimistic);  // Instant UI
+    router.post(`/items/${item.id}/favorite`, {}, {
+      preserveState: true,
+      onError: () => {
+        setOptimistic(item.isFavorite);  // Rollback
+        toast.error('Failed to update');
+      },
+    });
+  };
+
+  return (
+    <button onClick={toggle} className="text-xl">
+      {optimistic ? '❤️' : '🤍'}
+    </button>
+  );
+}
+```
+
+## Checklist — Before Shipping Any UI Component
+
+- [ ] Error state handled and shown to user
+- [ ] Loading state only when no data exists (no flash on refetch)
+- [ ] Empty state for every collection/list
+- [ ] Buttons disabled during async operations
+- [ ] Buttons show loading indicator
+- [ ] Form errors shown inline under fields
+- [ ] Mutations have onError with user feedback
+- [ ] Skeleton matches content layout shape
+
+## FORBIDDEN
+
+1. **`if (loading) return <Spinner />`** — check `loading && !data` instead
+2. **Silent catch** — always toast/display errors to user
+3. **No empty state** — every list needs one
+4. **Clickable button during submit** — always `disabled={processing}`
+5. **Console.log-only errors** — user must see feedback