@smicolon/ai-kit 0.1.0 → 0.1.1

package/packs/tanstack-router/skills/router-patterns/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: TanStack Router Patterns
+description: >-
+  Auto-enforce TanStack Router file-based routing conventions. Activates when
+  creating routes, configuring navigation, handling route params, or working
+  with search params in React SPA applications.
+version: 1.0.0
+---
+
+# TanStack Router Patterns
+
+This skill enforces TanStack Router best practices for file-based routing in React SPA applications.
+
+## Route File Naming Conventions
+
+| Pattern | Example | URL Path | Purpose |
+|---------|---------|----------|---------|
+| `__root.tsx` | `routes/__root.tsx` | - | Root layout, wraps all routes |
+| `index.tsx` | `routes/index.tsx` | `/` | Index route |
+| `about.tsx` | `routes/about.tsx` | `/about` | Static segment |
+| `posts.tsx` | `routes/posts.tsx` | `/posts` | Layout route (has `<Outlet />`) |
+| `posts.index.tsx` | `routes/posts.index.tsx` | `/posts` | Posts index (nested in layout) |
+| `posts.$postId.tsx` | `routes/posts.$postId.tsx` | `/posts/:postId` | Dynamic parameter |
+| `posts_.$postId.edit.tsx` | `routes/posts_.$postId.edit.tsx` | `/posts/:postId/edit` | Pathless parent layout |
+| `_auth.tsx` | `routes/_auth.tsx` | - | Pathless layout (no URL segment) |
+| `_auth.login.tsx` | `routes/_auth.login.tsx` | `/login` | Child of pathless layout |
+| `(marketing)/` | `routes/(marketing)/about.tsx` | `/about` | Route group (organization only) |
+| `$.tsx` | `routes/$.tsx` | `/*` | Catch-all/splat route |
+
+## Route File Structure
+
+### Basic Route
+```typescript
+// routes/about.tsx
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/about')({
+  component: AboutPage,
+})
+
+function AboutPage() {
+  return <div>About Page</div>
+}
+```
+
+### Route with Loader
+```typescript
+// routes/posts.$postId.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { postQueryOptions } from '@/features/posts/queries'
+
+export const Route = createFileRoute('/posts/$postId')({
+  loader: ({ context: { queryClient }, params }) =>
+    queryClient.ensureQueryData(postQueryOptions(params.postId)),
+  component: PostDetailPage,
+})
+
+function PostDetailPage() {
+  const { postId } = Route.useParams()
+  const post = Route.useLoaderData()
+
+  return <PostDetail post={post} />
+}
+```
+
+### Route with Search Params
+```typescript
+// routes/posts.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { z } from 'zod'
+
+const postsSearchSchema = z.object({
+  page: z.number().default(1),
+  sort: z.enum(['newest', 'oldest', 'popular']).default('newest'),
+  search: z.string().optional(),
+})
+
+export const Route = createFileRoute('/posts')({
+  validateSearch: postsSearchSchema,
+  component: PostsPage,
+})
+
+function PostsPage() {
+  const { page, sort, search } = Route.useSearch()
+  const navigate = Route.useNavigate()
+
+  const setPage = (newPage: number) => {
+    navigate({ search: (prev) => ({ ...prev, page: newPage }) })
+  }
+
+  return <PostList page={page} sort={sort} search={search} onPageChange={setPage} />
+}
+```
+
+### Root Route with Context
+```typescript
+// routes/__root.tsx
+import { createRootRouteWithContext, Outlet } from '@tanstack/react-router'
+import type { QueryClient } from '@tanstack/react-query'
+
+interface RouterContext {
+  queryClient: QueryClient
+}
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+  component: RootComponent,
+  beforeLoad: async ({ context }) => {
+    // Auth check, theme loading, etc.
+    return { user: await getUser() }
+  },
+})
+
+function RootComponent() {
+  return (
+    <div>
+      <Header />
+      <Outlet />
+      <Footer />
+    </div>
+  )
+}
+```
+
+### Pathless Layout Route
+```typescript
+// routes/_auth.tsx
+import { createFileRoute, Outlet, redirect } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_auth')({
+  beforeLoad: async ({ context }) => {
+    if (!context.user) {
+      throw redirect({ to: '/login' })
+    }
+  },
+  component: AuthLayout,
+})
+
+function AuthLayout() {
+  return (
+    <div className="authenticated-layout">
+      <Sidebar />
+      <main>
+        <Outlet />
+      </main>
+    </div>
+  )
+}
+```
+
+## Navigation Patterns
+
+### Declarative Navigation
+```typescript
+import { Link } from '@tanstack/react-router'
+
+// Basic link
+<Link to="/about">About</Link>
+
+// With params
+<Link to="/posts/$postId" params={{ postId: '123' }}>
+  View Post
+</Link>
+
+// With search params
+<Link to="/posts" search={{ page: 2, sort: 'newest' }}>
+  Page 2
+</Link>
+
+// Active styling
+<Link
+  to="/posts"
+  activeProps={{ className: 'active' }}
+  inactiveProps={{ className: 'inactive' }}
+>
+  Posts
+</Link>
+```
+
+### Imperative Navigation
+```typescript
+import { useNavigate } from '@tanstack/react-router'
+
+function PostCard({ post }) {
+  const navigate = useNavigate()
+
+  const handleClick = () => {
+    navigate({
+      to: '/posts/$postId',
+      params: { postId: post.id },
+      search: { tab: 'comments' }
+    })
+  }
+
+  return <div onClick={handleClick}>{post.title}</div>
+}
+```
+
+### Programmatic Redirect
+```typescript
+import { redirect } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/admin')({
+  beforeLoad: async ({ context }) => {
+    if (!context.user?.isAdmin) {
+      throw redirect({ to: '/', search: { error: 'unauthorized' } })
+    }
+  },
+})
+```
+
+## Error Handling
+
+### Route Error Boundary
+```typescript
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    const post = await getPost(params.postId)
+    if (!post) {
+      throw new Error('Post not found')
+    }
+    return post
+  },
+  errorComponent: ({ error }) => (
+    <div className="error">
+      <h2>Error loading post</h2>
+      <p>{error.message}</p>
+    </div>
+  ),
+  component: PostPage,
+})
+```
+
+### Pending Component
+```typescript
+export const Route = createFileRoute('/posts')({
+  pendingComponent: () => <div>Loading posts...</div>,
+  pendingMinMs: 500, // Show pending after 500ms
+  pendingMs: 1000,   // Minimum pending display time
+  component: PostsPage,
+})
+```
+
+## Conventions to Enforce
+
+1. **Always use `createFileRoute`** - Never manual route configuration
+2. **Type-safe params** - Use `Route.useParams()` for full type inference
+3. **Validate search params** - Use Zod schemas with `validateSearch`
+4. **Loaders for data** - Prefetch with `ensureQueryData`, not direct fetches
+5. **Context for shared data** - Auth, theme, queryClient in root context
+6. **Error boundaries** - Always provide `errorComponent` for data routes
+7. **Pathless layouts** - Use `_` prefix for auth guards, feature layouts
+
+## Anti-Patterns to Block
+
+```typescript
+// ❌ WRONG: Manual route definition
+const router = createRouter({
+  routes: [{ path: '/posts', component: Posts }]
+})
+
+// ✅ CORRECT: File-based routes
+// routes/posts.tsx with createFileRoute
+
+// ❌ WRONG: useParams from react-router-dom
+import { useParams } from 'react-router-dom'
+
+// ✅ CORRECT: Route-specific useParams
+const { postId } = Route.useParams()
+
+// ❌ WRONG: Unvalidated search params
+const search = new URLSearchParams(window.location.search)
+
+// ✅ CORRECT: Validated with Zod
+const { page, sort } = Route.useSearch()
+
+// ❌ WRONG: Direct fetch in loader
+loader: async () => {
+  const response = await fetch('/api/posts')
+  return response.json()
+}
+
+// ✅ CORRECT: Use query client
+loader: ({ context: { queryClient } }) =>
+  queryClient.ensureQueryData(postsQueryOptions())
+```

package/packs/tanstack-router/skills/store-patterns/SKILL.md

@@ -0,0 +1,351 @@
+---
+name: TanStack Store Patterns (Alpha)
+description: >-
+  TanStack Store patterns for framework-agnostic reactive state. Activates when
+  implementing client-side state, global stores, or reactive state management
+  in React applications. NOTE: Alpha library - API may change.
+version: 1.0.0
+---
+
+# TanStack Store Patterns (Alpha)
+
+> **Alpha Library**: TanStack Store is in alpha. APIs may change between versions.
+
+This skill covers TanStack Store for framework-agnostic reactive state management.
+
+## Basic Store
+
+```typescript
+// lib/stores/counter-store.ts
+import { Store } from '@tanstack/store'
+
+export const counterStore = new Store({
+  count: 0,
+})
+
+// Actions
+export const increment = () => {
+  counterStore.setState((state) => ({
+    ...state,
+    count: state.count + 1,
+  }))
+}
+
+export const decrement = () => {
+  counterStore.setState((state) => ({
+    ...state,
+    count: state.count - 1,
+  }))
+}
+
+export const reset = () => {
+  counterStore.setState((state) => ({
+    ...state,
+    count: 0,
+  }))
+}
+```
+
+## Using Store in React
+
+```typescript
+import { useStore } from '@tanstack/react-store'
+import { counterStore, increment, decrement, reset } from '@/lib/stores/counter-store'
+
+function Counter() {
+  const count = useStore(counterStore, (state) => state.count)
+
+  return (
+    <div>
+      <span>Count: {count}</span>
+      <button onClick={decrement}>-</button>
+      <button onClick={increment}>+</button>
+      <button onClick={reset}>Reset</button>
+    </div>
+  )
+}
+```
+
+## Complex Store with Derived State
+
+```typescript
+// lib/stores/cart-store.ts
+import { Store } from '@tanstack/store'
+
+interface CartItem {
+  id: string
+  name: string
+  price: number
+  quantity: number
+}
+
+interface CartState {
+  items: CartItem[]
+}
+
+export const cartStore = new Store<CartState>({
+  items: [],
+})
+
+// Derived selectors
+export const selectCartItems = (state: CartState) => state.items
+
+export const selectCartTotal = (state: CartState) =>
+  state.items.reduce((sum, item) => sum + item.price * item.quantity, 0)
+
+export const selectCartCount = (state: CartState) =>
+  state.items.reduce((sum, item) => sum + item.quantity, 0)
+
+// Actions
+export const addToCart = (item: Omit<CartItem, 'quantity'>) => {
+  cartStore.setState((state) => {
+    const existing = state.items.find((i) => i.id === item.id)
+    if (existing) {
+      return {
+        ...state,
+        items: state.items.map((i) =>
+          i.id === item.id ? { ...i, quantity: i.quantity + 1 } : i
+        ),
+      }
+    }
+    return {
+      ...state,
+      items: [...state.items, { ...item, quantity: 1 }],
+    }
+  })
+}
+
+export const removeFromCart = (itemId: string) => {
+  cartStore.setState((state) => ({
+    ...state,
+    items: state.items.filter((i) => i.id !== itemId),
+  }))
+}
+
+export const updateQuantity = (itemId: string, quantity: number) => {
+  if (quantity <= 0) {
+    removeFromCart(itemId)
+    return
+  }
+  cartStore.setState((state) => ({
+    ...state,
+    items: state.items.map((i) =>
+      i.id === itemId ? { ...i, quantity } : i
+    ),
+  }))
+}
+
+export const clearCart = () => {
+  cartStore.setState(() => ({ items: [] }))
+}
+```
+
+## Using Complex Store
+
+```typescript
+import { useStore } from '@tanstack/react-store'
+import {
+  cartStore,
+  selectCartItems,
+  selectCartTotal,
+  selectCartCount,
+  updateQuantity,
+  removeFromCart,
+} from '@/lib/stores/cart-store'
+
+function CartSummary() {
+  const count = useStore(cartStore, selectCartCount)
+  const total = useStore(cartStore, selectCartTotal)
+
+  return (
+    <div>
+      <span>{count} items</span>
+      <span>${total.toFixed(2)}</span>
+    </div>
+  )
+}
+
+function CartItems() {
+  const items = useStore(cartStore, selectCartItems)
+
+  return (
+    <ul>
+      {items.map((item) => (
+        <li key={item.id}>
+          <span>{item.name}</span>
+          <input
+            type="number"
+            value={item.quantity}
+            onChange={(e) => updateQuantity(item.id, parseInt(e.target.value))}
+            min={0}
+          />
+          <button onClick={() => removeFromCart(item.id)}>Remove</button>
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+## Store with Persistence
+
+```typescript
+// lib/stores/theme-store.ts
+import { Store } from '@tanstack/store'
+
+type Theme = 'light' | 'dark' | 'system'
+
+interface ThemeState {
+  theme: Theme
+}
+
+const getInitialTheme = (): Theme => {
+  if (typeof window === 'undefined') return 'system'
+  const stored = localStorage.getItem('theme')
+  if (stored === 'light' || stored === 'dark' || stored === 'system') {
+    return stored
+  }
+  return 'system'
+}
+
+export const themeStore = new Store<ThemeState>({
+  theme: getInitialTheme(),
+})
+
+// Subscribe to persist changes
+themeStore.subscribe(() => {
+  const { theme } = themeStore.state
+  localStorage.setItem('theme', theme)
+
+  // Apply theme to document
+  const root = document.documentElement
+  if (theme === 'system') {
+    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches
+    root.classList.toggle('dark', prefersDark)
+  } else {
+    root.classList.toggle('dark', theme === 'dark')
+  }
+})
+
+export const setTheme = (theme: Theme) => {
+  themeStore.setState(() => ({ theme }))
+}
+```
+
+## Store Factory Pattern
+
+```typescript
+// lib/stores/create-entity-store.ts
+import { Store } from '@tanstack/store'
+
+interface EntityState<T> {
+  entities: Record<string, T>
+  ids: string[]
+  loading: boolean
+  error: string | null
+}
+
+export function createEntityStore<T extends { id: string }>() {
+  const store = new Store<EntityState<T>>({
+    entities: {},
+    ids: [],
+    loading: false,
+    error: null,
+  })
+
+  return {
+    store,
+
+    selectAll: (state: EntityState<T>) =>
+      state.ids.map((id) => state.entities[id]),
+
+    selectById: (id: string) => (state: EntityState<T>) =>
+      state.entities[id],
+
+    setMany: (items: T[]) => {
+      store.setState((state) => ({
+        ...state,
+        entities: items.reduce((acc, item) => ({ ...acc, [item.id]: item }), state.entities),
+        ids: [...new Set([...state.ids, ...items.map((i) => i.id)])],
+      }))
+    },
+
+    setOne: (item: T) => {
+      store.setState((state) => ({
+        ...state,
+        entities: { ...state.entities, [item.id]: item },
+        ids: state.ids.includes(item.id) ? state.ids : [...state.ids, item.id],
+      }))
+    },
+
+    removeOne: (id: string) => {
+      store.setState((state) => {
+        const { [id]: removed, ...entities } = state.entities
+        return {
+          ...state,
+          entities,
+          ids: state.ids.filter((i) => i !== id),
+        }
+      })
+    },
+
+    setLoading: (loading: boolean) => {
+      store.setState((state) => ({ ...state, loading }))
+    },
+
+    setError: (error: string | null) => {
+      store.setState((state) => ({ ...state, error }))
+    },
+  }
+}
+
+// Usage
+const usersStore = createEntityStore<User>()
+```
+
+## When to Use TanStack Store vs Query
+
+| Use Case | Solution |
+|----------|----------|
+| Server data | TanStack Query |
+| URL state | TanStack Router |
+| Form state | TanStack Form |
+| Local UI state | React useState |
+| Shared client state | TanStack Store |
+| Theme/preferences | TanStack Store + localStorage |
+| Cart/wishlist | TanStack Store |
+
+## Conventions
+
+1. **Separate stores by domain** - One store per feature/concern
+2. **Selector functions** - Define selectors for derived state
+3. **Action functions** - Export actions, don't expose setState directly
+4. **Type safety** - Always type your store state
+5. **Persistence** - Use subscribe for localStorage sync
+6. **Prefer Query** - Use Query for server state, Store for client-only
+
+## Anti-Patterns
+
+```typescript
+// ❌ WRONG: Mutating state directly
+cartStore.state.items.push(newItem)
+
+// ✅ CORRECT: Using setState
+cartStore.setState((state) => ({
+  ...state,
+  items: [...state.items, newItem],
+}))
+
+// ❌ WRONG: Storing server data
+const postsStore = new Store({ posts: [] })
+
+// ✅ CORRECT: Use Query for server data
+const { data: posts } = useQuery(postsQueryOptions())
+
+// ❌ WRONG: Exposing setState directly
+export { counterStore }
+// Component: counterStore.setState(...)
+
+// ✅ CORRECT: Export action functions
+export const increment = () => counterStore.setState(...)
+```