skillstore-cli 1.0.0

package/data/shared/framework/skills/frontend-development/references/routing-forms-realtime.md

@@ -0,0 +1,374 @@
+# Routing, Forms & Real-Time Data Patterns
+
+## File-Based Routing vs Config-Based Routing
+
+### File-Based (Next.js App Router)
+
+```
+app/
+├── layout.tsx                 → root layout
+├── page.tsx                   → /
+├── blog/
+│   ├── page.tsx               → /blog
+│   └── [slug]/
+│       └── page.tsx           → /blog/:slug
+├── (marketing)/               → route group (no URL segment)
+│   ├── about/page.tsx         → /about
+│   └── pricing/page.tsx       → /pricing
+└── api/
+    └── webhook/route.ts       → /api/webhook
+```
+
+### File-Based (Nuxt 3)
+
+```
+pages/
+├── index.vue                  → /
+├── blog/
+│   ├── index.vue              → /blog
+│   └── [slug].vue             → /blog/:slug
+```
+
+### File-Based (SvelteKit)
+
+```
+src/routes/
+├── +page.svelte               → /
+├── blog/
+│   ├── +page.svelte           → /blog
+│   └── [slug]/
+│       └── +page.svelte       → /blog/:slug
+```
+
+### Config-Based (React Router v7)
+
+```tsx
+import { createBrowserRouter, RouterProvider } from 'react-router';
+
+const router = createBrowserRouter([
+  {
+    path: '/',
+    element: <RootLayout />,
+    children: [
+      { index: true, element: <Home /> },
+      { path: 'blog', element: <Blog /> },
+      { path: 'blog/:slug', element: <BlogPost />, loader: postLoader },
+    ],
+  },
+]);
+
+export default function App() {
+  return <RouterProvider router={router} />;
+}
+```
+
+---
+
+## Nested Layouts, Parallel Routes & Intercepting Routes (Next.js)
+
+### Nested Layouts
+
+```tsx
+// app/dashboard/layout.tsx — persists across all /dashboard/* pages
+export default function DashboardLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="flex">
+      <Sidebar />
+      <main className="flex-1">{children}</main>
+    </div>
+  );
+}
+```
+
+### Parallel Routes
+
+Use `@slot` folders to render multiple pages simultaneously in the same layout.
+
+```
+app/
+├── layout.tsx                → receives { analytics, team } as props
+├── @analytics/page.tsx       → rendered in the analytics slot
+├── @team/page.tsx            → rendered in the team slot
+└── page.tsx                  → default page
+```
+
+```tsx
+// app/layout.tsx
+export default function Layout({
+  children,
+  analytics,
+  team,
+}: {
+  children: React.ReactNode;
+  analytics: React.ReactNode;
+  team: React.ReactNode;
+}) {
+  return (
+    <div>
+      {children}
+      <div className="grid grid-cols-2">
+        {analytics}
+        {team}
+      </div>
+    </div>
+  );
+}
+```
+
+### Intercepting Routes
+
+Show a modal on soft navigation while preserving the full page on hard navigation.
+
+```
+app/
+├── feed/
+│   └── page.tsx
+├── photo/[id]/
+│   └── page.tsx              → full page on direct visit
+└── @modal/
+    └── (.)photo/[id]/
+        └── page.tsx          → intercepted as modal from /feed
+```
+
+---
+
+## React Hook Form + Zod Validation
+
+```tsx
+'use client';
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+
+const schema = z.object({
+  email: z.string().email('Invalid email address'),
+  password: z.string().min(8, 'Must be at least 8 characters'),
+  role: z.enum(['admin', 'user'], { required_error: 'Select a role' }),
+});
+
+type FormValues = z.infer<typeof schema>;
+
+export function SignUpForm() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isSubmitting },
+  } = useForm<FormValues>({
+    resolver: zodResolver(schema),
+    defaultValues: { email: '', password: '', role: 'user' },
+  });
+
+  const onSubmit = async (data: FormValues) => {
+    const res = await fetch('/api/signup', {
+      method: 'POST',
+      body: JSON.stringify(data),
+    });
+    if (!res.ok) throw new Error('Signup failed');
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)} noValidate>
+      <input {...register('email')} type="email" />
+      {errors.email && <p>{errors.email.message}</p>}
+
+      <input {...register('password')} type="password" />
+      {errors.password && <p>{errors.password.message}</p>}
+
+      <select {...register('role')}>
+        <option value="user">User</option>
+        <option value="admin">Admin</option>
+      </select>
+      {errors.role && <p>{errors.role.message}</p>}
+
+      <button type="submit" disabled={isSubmitting}>Sign Up</button>
+    </form>
+  );
+}
+```
+
+---
+
+## VeeValidate + Yup for Vue
+
+```vue
+<script setup lang="ts">
+import { useForm } from 'vee-validate';
+import * as yup from 'yup';
+
+const schema = yup.object({
+  email: yup.string().required().email(),
+  password: yup.string().required().min(8),
+});
+
+const { defineField, handleSubmit, errors } = useForm({ validationSchema: schema });
+
+const [email, emailAttrs] = defineField('email');
+const [password, passwordAttrs] = defineField('password');
+
+const onSubmit = handleSubmit(async (values) => {
+  await $fetch('/api/signup', { method: 'POST', body: values });
+});
+</script>
+
+<template>
+  <form @submit="onSubmit">
+    <input v-model="email" v-bind="emailAttrs" type="email" />
+    <span>{{ errors.email }}</span>
+    <input v-model="password" v-bind="passwordAttrs" type="password" />
+    <span>{{ errors.password }}</span>
+    <button type="submit">Sign Up</button>
+  </form>
+</template>
+```
+
+---
+
+## Real-Time Data Patterns
+
+### WebSocket Integration (React)
+
+```tsx
+'use client';
+import { useEffect, useRef, useState } from 'react';
+
+export function useWebSocket<T>(url: string) {
+  const ws = useRef<WebSocket | null>(null);
+  const [messages, setMessages] = useState<T[]>([]);
+  const [status, setStatus] = useState<'connecting' | 'open' | 'closed'>('connecting');
+
+  useEffect(() => {
+    ws.current = new WebSocket(url);
+    ws.current.onopen = () => setStatus('open');
+    ws.current.onclose = () => setStatus('closed');
+    ws.current.onmessage = (e) => {
+      const data: T = JSON.parse(e.data);
+      setMessages((prev) => [...prev, data]);
+    };
+    return () => ws.current?.close();
+  }, [url]);
+
+  const send = (data: unknown) => ws.current?.send(JSON.stringify(data));
+  return { messages, status, send };
+}
+```
+
+### Server-Sent Events (SSE)
+
+```tsx
+'use client';
+import { useEffect, useState } from 'react';
+
+export function useSSE<T>(url: string) {
+  const [data, setData] = useState<T | null>(null);
+
+  useEffect(() => {
+    const source = new EventSource(url);
+    source.onmessage = (e) => setData(JSON.parse(e.data));
+    source.onerror = () => source.close();
+    return () => source.close();
+  }, [url]);
+
+  return data;
+}
+```
+
+### Polling with TanStack Query
+
+```tsx
+import { useQuery } from '@tanstack/react-query';
+
+function Notifications() {
+  const { data } = useQuery({
+    queryKey: ['notifications'],
+    queryFn: () => fetch('/api/notifications').then(r => r.json()),
+    refetchInterval: 5_000,       // poll every 5 seconds
+    refetchIntervalInBackground: false,
+  });
+  return <ul>{data?.map((n: any) => <li key={n.id}>{n.text}</li>)}</ul>;
+}
+```
+
+---
+
+## Optimistic UI Updates with TanStack Query
+
+```tsx
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+
+function useToggleLike(postId: string) {
+  const qc = useQueryClient();
+
+  return useMutation({
+    mutationFn: () => fetch(`/api/posts/${postId}/like`, { method: 'POST' }),
+    onMutate: async () => {
+      await qc.cancelQueries({ queryKey: ['post', postId] });
+      const prev = qc.getQueryData<Post>(['post', postId]);
+      qc.setQueryData<Post>(['post', postId], (old) =>
+        old ? { ...old, liked: !old.liked, likes: old.likes + (old.liked ? -1 : 1) } : old,
+      );
+      return { prev };
+    },
+    onError: (_err, _vars, ctx) => {
+      if (ctx?.prev) qc.setQueryData(['post', postId], ctx.prev);
+    },
+    onSettled: () => {
+      qc.invalidateQueries({ queryKey: ['post', postId] });
+    },
+  });
+}
+```
+
+---
+
+## tRPC End-to-End Type Safety
+
+### Server Setup
+
+```ts
+// server/trpc.ts
+import { initTRPC } from '@trpc/server';
+import { z } from 'zod';
+
+const t = initTRPC.create();
+
+export const appRouter = t.router({
+  user: t.router({
+    byId: t.procedure
+      .input(z.object({ id: z.string() }))
+      .query(async ({ input }) => {
+        return db.user.findUnique({ where: { id: input.id } });
+      }),
+    create: t.procedure
+      .input(z.object({ name: z.string(), email: z.string().email() }))
+      .mutation(async ({ input }) => {
+        return db.user.create({ data: input });
+      }),
+  }),
+});
+
+export type AppRouter = typeof appRouter;
+```
+
+### Client Usage (React)
+
+```tsx
+// utils/trpc.ts
+import { createTRPCReact } from '@trpc/react-query';
+import type { AppRouter } from '@/server/trpc';
+
+export const trpc = createTRPCReact<AppRouter>();
+```
+
+```tsx
+// components/user-profile.tsx
+'use client';
+import { trpc } from '@/utils/trpc';
+
+export function UserProfile({ userId }: { userId: string }) {
+  const { data: user, isLoading } = trpc.user.byId.useQuery({ id: userId });
+  const createUser = trpc.user.create.useMutation();
+
+  if (isLoading) return <p>Loading...</p>;
+  return <div>{user?.name}</div>;
+}
+```

package/data/shared/framework/skills/frontend-development/references/ssr-rsc-patterns.md

@@ -0,0 +1,284 @@
+# SSR & React Server Components Patterns
+
+## Next.js App Router: Server Components vs Client Components
+
+### Decision Tree
+
+```
+Does the component need...
+├── Browser APIs (window, document, localStorage)? → 'use client'
+├── Event handlers (onClick, onChange, onSubmit)?   → 'use client'
+├── React hooks (useState, useEffect, useRef)?      → 'use client'
+├── Third-party client libs (framer-motion, etc.)?  → 'use client'
+└── None of the above?                              → Server Component (default)
+```
+
+Key principle: keep `'use client'` as far down the tree as possible. Wrap only the
+interactive leaf, not the entire page.
+
+```tsx
+// app/dashboard/page.tsx — Server Component (default, no directive)
+import { db } from '@/lib/db';
+import { InteractiveChart } from './interactive-chart';
+
+export default async function DashboardPage() {
+  const stats = await db.stats.findMany();      // runs on server, zero client JS
+  return (
+    <section>
+      <h1>Dashboard</h1>
+      <InteractiveChart data={stats} />          {/* only this ships JS */}
+    </section>
+  );
+}
+```
+
+```tsx
+// app/dashboard/interactive-chart.tsx
+'use client';
+import { useState } from 'react';
+
+export function InteractiveChart({ data }: { data: Stat[] }) {
+  const [range, setRange] = useState<'7d' | '30d'>('7d');
+  return <canvas /* ... */ />;
+}
+```
+
+---
+
+## Server Actions — Form Submissions & Mutations
+
+Server Actions run on the server and can be called directly from Client Components
+or forms without creating an API route.
+
+```tsx
+// app/contacts/actions.ts
+'use server';
+import { revalidatePath } from 'next/cache';
+import { z } from 'zod';
+
+const ContactSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+});
+
+export async function createContact(formData: FormData) {
+  const parsed = ContactSchema.safeParse(Object.fromEntries(formData));
+  if (!parsed.success) {
+    return { errors: parsed.error.flatten().fieldErrors };
+  }
+  await db.contacts.create({ data: parsed.data });
+  revalidatePath('/contacts');
+}
+```
+
+```tsx
+// app/contacts/page.tsx — progressive enhancement: works without JS
+import { createContact } from './actions';
+
+export default function ContactsPage() {
+  return (
+    <form action={createContact}>
+      <input name="name" required />
+      <input name="email" type="email" required />
+      <button type="submit">Save</button>
+    </form>
+  );
+}
+```
+
+---
+
+## Streaming + Suspense for Data Fetching
+
+Use `loading.tsx` for route-level streaming, or `<Suspense>` for granular control.
+
+```
+app/
+├── dashboard/
+│   ├── page.tsx          ← main layout, instant shell
+│   ├── loading.tsx       ← shown while page.tsx streams
+│   └── components/
+│       └── revenue.tsx   ← slow data, wrapped in Suspense
+```
+
+```tsx
+// app/dashboard/page.tsx
+import { Suspense } from 'react';
+import { RevenueSummary } from './components/revenue';
+import { Skeleton } from '@/components/ui/skeleton';
+
+export default function DashboardPage() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      <Suspense fallback={<Skeleton className="h-48 w-full" />}>
+        <RevenueSummary />    {/* async Server Component */}
+      </Suspense>
+    </div>
+  );
+}
+```
+
+```tsx
+// app/dashboard/components/revenue.tsx — async Server Component
+export async function RevenueSummary() {
+  const data = await fetch('https://api.example.com/revenue', {
+    next: { revalidate: 60 },
+  }).then(r => r.json());
+  return <div>{/* render data */}</div>;
+}
+```
+
+---
+
+## Static vs Dynamic Rendering
+
+| Strategy | When to use | How |
+|----------|-------------|-----|
+| **Static (SSG)** | Content rarely changes, same for all users | Default in App Router if no dynamic APIs used |
+| **Dynamic (SSR)** | Per-request data (auth, cookies, search params) | Use `cookies()`, `headers()`, or `searchParams` |
+| **ISR** | Mostly static but needs periodic refresh | `fetch(..., { next: { revalidate: 60 } })` |
+
+### ISR — Incremental Static Regeneration
+
+```tsx
+// Revalidate every 5 minutes
+export const revalidate = 300;
+
+export default async function BlogPage() {
+  const posts = await fetch('https://cms.example.com/posts', {
+    next: { revalidate: 300 },
+  }).then(r => r.json());
+  return <PostList posts={posts} />;
+}
+```
+
+On-demand revalidation via route handler:
+
+```ts
+// app/api/revalidate/route.ts
+import { revalidatePath, revalidateTag } from 'next/cache';
+import { NextRequest } from 'next/server';
+
+export async function POST(req: NextRequest) {
+  const { tag, path } = await req.json();
+  if (tag) revalidateTag(tag);
+  if (path) revalidatePath(path);
+  return Response.json({ revalidated: true, now: Date.now() });
+}
+```
+
+---
+
+## Nuxt 3 Patterns
+
+### Server Routes & Universal Rendering
+
+```ts
+// server/api/users.get.ts — auto-registered at /api/users
+export default defineEventHandler(async (event) => {
+  const users = await db.user.findMany();
+  return users;
+});
+```
+
+### useFetch / useAsyncData
+
+```vue
+<script setup lang="ts">
+// useFetch — shorthand, auto-dedupes and SSR-safe
+const { data: users, pending, error } = await useFetch('/api/users');
+
+// useAsyncData — more control, custom key
+const { data: profile } = await useAsyncData('profile', () => {
+  return $fetch(`/api/users/${route.params.id}`);
+});
+</script>
+```
+
+---
+
+## SvelteKit Patterns
+
+### Load Functions & Form Actions
+
+```ts
+// src/routes/posts/+page.server.ts
+import type { PageServerLoad, Actions } from './$types';
+
+export const load: PageServerLoad = async ({ locals }) => {
+  const posts = await locals.db.post.findMany();
+  return { posts };
+};
+
+export const actions: Actions = {
+  create: async ({ request, locals }) => {
+    const data = await request.formData();
+    const title = data.get('title') as string;
+    await locals.db.post.create({ data: { title } });
+    return { success: true };
+  },
+};
+```
+
+```svelte
+<!-- src/routes/posts/+page.svelte -->
+<script lang="ts">
+  import type { PageData } from './$types';
+  export let data: PageData;
+</script>
+
+<form method="POST" action="?/create">
+  <input name="title" required />
+  <button>Create</button>
+</form>
+
+{#each data.posts as post}
+  <article>{post.title}</article>
+{/each}
+```
+
+---
+
+## Middleware Patterns
+
+### Next.js Middleware (auth redirects, rewrites, geolocation)
+
+```ts
+// middleware.ts (project root)
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get('session')?.value;
+
+  // Auth redirect
+  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
+    return NextResponse.redirect(new URL('/login', request.url));
+  }
+
+  // Geolocation-based rewrite
+  const country = request.geo?.country ?? 'US';
+  if (request.nextUrl.pathname === '/') {
+    return NextResponse.rewrite(new URL(`/${country.toLowerCase()}`, request.url));
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
+};
+```
+
+### Nuxt Middleware
+
+```ts
+// middleware/auth.global.ts — runs on every route
+export default defineNuxtRouteMiddleware((to) => {
+  const { loggedIn } = useUserSession();
+  if (!loggedIn.value && to.path.startsWith('/dashboard')) {
+    return navigateTo('/login');
+  }
+});
+```