@girardmedia/bootspring 1.2.0 → 2.0.3

package/skills/patterns/state/url-state.md

@@ -1,482 +0,0 @@
-# URL State Management Patterns
-
-Patterns for managing state in URL search params.
-
-## useSearchParams Hook
-
-```typescript
-// hooks/useUrlState.ts
-'use client'
-
-import { useSearchParams, usePathname, useRouter } from 'next/navigation'
-import { useCallback, useMemo } from 'react'
-
-export function useUrlState<T extends Record<string, string | string[] | undefined>>(
-  defaults?: Partial<T>
-) {
-  const searchParams = useSearchParams()
-  const pathname = usePathname()
-  const router = useRouter()
-
-  const state = useMemo(() => {
-    const params: Record<string, string | string[]> = {}
-
-    searchParams.forEach((value, key) => {
-      const existing = params[key]
-      if (existing) {
-        params[key] = Array.isArray(existing)
-          ? [...existing, value]
-          : [existing, value]
-      } else {
-        params[key] = value
-      }
-    })
-
-    return { ...defaults, ...params } as T
-  }, [searchParams, defaults])
-
-  const setParams = useCallback(
-    (updates: Partial<T>, options?: { replace?: boolean; scroll?: boolean }) => {
-      const params = new URLSearchParams(searchParams.toString())
-
-      Object.entries(updates).forEach(([key, value]) => {
-        if (value === undefined || value === null || value === '') {
-          params.delete(key)
-        } else if (Array.isArray(value)) {
-          params.delete(key)
-          value.forEach(v => params.append(key, v))
-        } else {
-          params.set(key, String(value))
-        }
-      })
-
-      const url = `${pathname}?${params.toString()}`
-
-      if (options?.replace) {
-        router.replace(url, { scroll: options?.scroll ?? false })
-      } else {
-        router.push(url, { scroll: options?.scroll ?? false })
-      }
-    },
-    [searchParams, pathname, router]
-  )
-
-  const clearParams = useCallback(
-    (keys?: string[]) => {
-      const params = new URLSearchParams(searchParams.toString())
-
-      if (keys) {
-        keys.forEach(key => params.delete(key))
-      } else {
-        // Clear all
-        for (const key of params.keys()) {
-          params.delete(key)
-        }
-      }
-
-      router.push(`${pathname}?${params.toString()}`)
-    },
-    [searchParams, pathname, router]
-  )
-
-  return { state, setParams, clearParams }
-}
-```
-
-## Typed URL State
-
-```typescript
-// hooks/useTypedUrlState.ts
-'use client'
-
-import { useSearchParams, usePathname, useRouter } from 'next/navigation'
-import { useCallback, useMemo } from 'react'
-import { z } from 'zod'
-
-export function useTypedUrlState<T extends z.ZodObject<any>>(schema: T) {
-  type State = z.infer<T>
-
-  const searchParams = useSearchParams()
-  const pathname = usePathname()
-  const router = useRouter()
-
-  const state = useMemo(() => {
-    const raw: Record<string, any> = {}
-
-    searchParams.forEach((value, key) => {
-      raw[key] = value
-    })
-
-    // Parse and validate with schema
-    const result = schema.safeParse(raw)
-
-    if (result.success) {
-      return result.data as State
-    }
-
-    // Return defaults from schema
-    return schema.parse({}) as State
-  }, [searchParams, schema])
-
-  const setParams = useCallback(
-    (updates: Partial<State>) => {
-      const params = new URLSearchParams(searchParams.toString())
-
-      Object.entries(updates).forEach(([key, value]) => {
-        if (value === undefined || value === null) {
-          params.delete(key)
-        } else if (typeof value === 'boolean') {
-          params.set(key, value ? 'true' : 'false')
-        } else if (typeof value === 'number') {
-          params.set(key, String(value))
-        } else {
-          params.set(key, String(value))
-        }
-      })
-
-      router.push(`${pathname}?${params.toString()}`, { scroll: false })
-    },
-    [searchParams, pathname, router]
-  )
-
-  return { state, setParams }
-}
-
-// Usage
-const filterSchema = z.object({
-  search: z.string().optional().default(''),
-  page: z.coerce.number().optional().default(1),
-  sort: z.enum(['newest', 'oldest', 'popular']).optional().default('newest'),
-  category: z.string().optional()
-})
-
-function ProductList() {
-  const { state, setParams } = useTypedUrlState(filterSchema)
-
-  return (
-    <div>
-      <input
-        value={state.search}
-        onChange={e => setParams({ search: e.target.value, page: 1 })}
-      />
-      <select
-        value={state.sort}
-        onChange={e => setParams({ sort: e.target.value as any })}
-      >
-        <option value="newest">Newest</option>
-        <option value="oldest">Oldest</option>
-        <option value="popular">Popular</option>
-      </select>
-    </div>
-  )
-}
-```
-
-## Pagination with URL State
-
-```tsx
-// components/Pagination.tsx
-'use client'
-
-import { useUrlState } from '@/hooks/useUrlState'
-import { ChevronLeft, ChevronRight } from 'lucide-react'
-import { cn } from '@/lib/utils'
-
-interface PaginationProps {
-  totalPages: number
-  pageParam?: string
-}
-
-export function Pagination({ totalPages, pageParam = 'page' }: PaginationProps) {
-  const { state, setParams } = useUrlState({ [pageParam]: '1' })
-  const currentPage = parseInt(state[pageParam] as string) || 1
-
-  const goToPage = (page: number) => {
-    setParams({ [pageParam]: String(page) })
-  }
-
-  const pages = getPageNumbers(currentPage, totalPages)
-
-  return (
-    <nav className="flex items-center gap-1">
-      <button
-        onClick={() => goToPage(currentPage - 1)}
-        disabled={currentPage <= 1}
-        className="p-2 rounded hover:bg-gray-100 disabled:opacity-50"
-      >
-        <ChevronLeft className="h-4 w-4" />
-      </button>
-
-      {pages.map((page, i) =>
-        page === '...' ? (
-          <span key={`ellipsis-${i}`} className="px-2">
-            ...
-          </span>
-        ) : (
-          <button
-            key={page}
-            onClick={() => goToPage(page as number)}
-            className={cn(
-              'px-3 py-1 rounded',
-              currentPage === page
-                ? 'bg-blue-600 text-white'
-                : 'hover:bg-gray-100'
-            )}
-          >
-            {page}
-          </button>
-        )
-      )}
-
-      <button
-        onClick={() => goToPage(currentPage + 1)}
-        disabled={currentPage >= totalPages}
-        className="p-2 rounded hover:bg-gray-100 disabled:opacity-50"
-      >
-        <ChevronRight className="h-4 w-4" />
-      </button>
-    </nav>
-  )
-}
-
-function getPageNumbers(current: number, total: number): (number | string)[] {
-  if (total <= 7) {
-    return Array.from({ length: total }, (_, i) => i + 1)
-  }
-
-  if (current <= 3) {
-    return [1, 2, 3, 4, '...', total]
-  }
-
-  if (current >= total - 2) {
-    return [1, '...', total - 3, total - 2, total - 1, total]
-  }
-
-  return [1, '...', current - 1, current, current + 1, '...', total]
-}
-```
-
-## Filters with URL State
-
-```tsx
-// components/ProductFilters.tsx
-'use client'
-
-import { useUrlState } from '@/hooks/useUrlState'
-
-interface FilterState {
-  search?: string
-  category?: string
-  minPrice?: string
-  maxPrice?: string
-  inStock?: string
-  sort?: string
-}
-
-export function ProductFilters() {
-  const { state, setParams, clearParams } = useUrlState<FilterState>({
-    sort: 'newest'
-  })
-
-  const hasActiveFilters =
-    state.search ||
-    state.category ||
-    state.minPrice ||
-    state.maxPrice ||
-    state.inStock
-
-  return (
-    <div className="space-y-4">
-      {/* Search */}
-      <input
-        type="text"
-        placeholder="Search..."
-        value={state.search ?? ''}
-        onChange={e => setParams({ search: e.target.value || undefined })}
-        className="w-full rounded border px-3 py-2"
-      />
-
-      {/* Category */}
-      <select
-        value={state.category ?? ''}
-        onChange={e => setParams({ category: e.target.value || undefined })}
-        className="w-full rounded border px-3 py-2"
-      >
-        <option value="">All Categories</option>
-        <option value="electronics">Electronics</option>
-        <option value="clothing">Clothing</option>
-        <option value="books">Books</option>
-      </select>
-
-      {/* Price Range */}
-      <div className="flex gap-2">
-        <input
-          type="number"
-          placeholder="Min price"
-          value={state.minPrice ?? ''}
-          onChange={e => setParams({ minPrice: e.target.value || undefined })}
-          className="w-1/2 rounded border px-3 py-2"
-        />
-        <input
-          type="number"
-          placeholder="Max price"
-          value={state.maxPrice ?? ''}
-          onChange={e => setParams({ maxPrice: e.target.value || undefined })}
-          className="w-1/2 rounded border px-3 py-2"
-        />
-      </div>
-
-      {/* In Stock */}
-      <label className="flex items-center gap-2">
-        <input
-          type="checkbox"
-          checked={state.inStock === 'true'}
-          onChange={e =>
-            setParams({ inStock: e.target.checked ? 'true' : undefined })
-          }
-        />
-        In Stock Only
-      </label>
-
-      {/* Sort */}
-      <select
-        value={state.sort}
-        onChange={e => setParams({ sort: e.target.value })}
-        className="w-full rounded border px-3 py-2"
-      >
-        <option value="newest">Newest</option>
-        <option value="price-asc">Price: Low to High</option>
-        <option value="price-desc">Price: High to Low</option>
-        <option value="popular">Most Popular</option>
-      </select>
-
-      {/* Clear Filters */}
-      {hasActiveFilters && (
-        <button
-          onClick={() =>
-            clearParams(['search', 'category', 'minPrice', 'maxPrice', 'inStock'])
-          }
-          className="text-sm text-blue-600 hover:underline"
-        >
-          Clear all filters
-        </button>
-      )}
-    </div>
-  )
-}
-```
-
-## Server Component URL State
-
-```tsx
-// app/products/page.tsx
-import { prisma } from '@/lib/db'
-import { ProductFilters } from '@/components/ProductFilters'
-import { Pagination } from '@/components/Pagination'
-
-interface SearchParams {
-  search?: string
-  category?: string
-  minPrice?: string
-  maxPrice?: string
-  inStock?: string
-  sort?: string
-  page?: string
-}
-
-export default async function ProductsPage({
-  searchParams
-}: {
-  searchParams: SearchParams
-}) {
-  const page = parseInt(searchParams.page ?? '1')
-  const limit = 20
-
-  // Build Prisma query from URL params
-  const where: any = {}
-
-  if (searchParams.search) {
-    where.OR = [
-      { name: { contains: searchParams.search, mode: 'insensitive' } },
-      { description: { contains: searchParams.search, mode: 'insensitive' } }
-    ]
-  }
-
-  if (searchParams.category) {
-    where.category = searchParams.category
-  }
-
-  if (searchParams.minPrice || searchParams.maxPrice) {
-    where.price = {}
-    if (searchParams.minPrice) {
-      where.price.gte = parseFloat(searchParams.minPrice)
-    }
-    if (searchParams.maxPrice) {
-      where.price.lte = parseFloat(searchParams.maxPrice)
-    }
-  }
-
-  if (searchParams.inStock === 'true') {
-    where.stock = { gt: 0 }
-  }
-
-  // Sort
-  const orderBy: any = {}
-  switch (searchParams.sort) {
-    case 'price-asc':
-      orderBy.price = 'asc'
-      break
-    case 'price-desc':
-      orderBy.price = 'desc'
-      break
-    case 'popular':
-      orderBy.salesCount = 'desc'
-      break
-    default:
-      orderBy.createdAt = 'desc'
-  }
-
-  const [products, total] = await Promise.all([
-    prisma.product.findMany({
-      where,
-      orderBy,
-      skip: (page - 1) * limit,
-      take: limit
-    }),
-    prisma.product.count({ where })
-  ])
-
-  const totalPages = Math.ceil(total / limit)
-
-  return (
-    <div className="container py-8">
-      <div className="grid grid-cols-4 gap-8">
-        <aside>
-          <ProductFilters />
-        </aside>
-
-        <main className="col-span-3">
-          <div className="mb-4 text-sm text-gray-600">
-            {total} products found
-          </div>
-
-          <div className="grid grid-cols-3 gap-4">
-            {products.map(product => (
-              <ProductCard key={product.id} product={product} />
-            ))}
-          </div>
-
-          <Pagination totalPages={totalPages} />
-        </main>
-      </div>
-    </div>
-  )
-}
-```
-
-## When to Use
-
-- Shareable filter states
-- Pagination
-- Search results
-- Bookmarkable views