ai-qakit 1.0.0

package/templates/.claude/commands/devkit/frontend/create-page.md

@@ -0,0 +1,484 @@
+---
+description: Generate page/route component following project patterns
+argument-hint: [page-description]
+allowed-tools: Read, Grep, Write, Edit, AskUserQuestion
+---
+
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
+
+---
+
+**Report Protocol**: Follow ./.claude/CLAUDE.md "Sub-Agent Report Generation" protocol before spawning subagents.
+
+# Create Page
+
+Generate page for: $ARGUMENTS
+
+## ⚠️ Plan Before Executing
+
+**Always create a structured plan and get user approval before making changes.**
+
+1. Analyze the request and show page design
+2. Display the page structure with data fetching and layout
+3. Show all files that will be created
+4. Ask for confirmation before writing files
+5. Never create pages without user approval
+
+## Important: Ask for Clarification
+
+**If anything is unclear, DO NOT GUESS. Ask the user:**
+
+- "What route path should this page have? (e.g., /users, /products/:id)"
+- "Does this page need data fetching? Server-side or client-side?"
+- "Should this be a static page or dynamic route?"
+- "What layout should wrap this page?"
+- "Does this page require authentication?"
+- "Should I include loading and error states?"
+- "Are there any SEO requirements (meta tags, title)?"
+
+Use AskUserQuestion tool when you need more context before proceeding.
+
+## Step 1: Reference Project Profile
+
+Read @.claude/CLAUDE.md to understand:
+- Framework (Next.js, React Router, TanStack Router)
+- Routing pattern (file-based vs config-based)
+- Page directory structure
+- Data fetching patterns (SSR, SSG, CSR, TanStack Query)
+- Layout system
+- Authentication patterns
+- SEO/meta handling
+
+If `.claude/CLAUDE.md` doesn't exist, run `/init` first.
+
+## Step 2: Parse Request
+
+Analyze "$ARGUMENTS" to determine:
+- Page name and route path
+- Dynamic segments (e.g., [id], :id, $id)
+- Data requirements
+- Layout needs
+- Authentication requirements
+- SEO requirements
+
+**Common page types:**
+- `List` - Display collection (UserListPage, ProductsPage)
+- `Detail` - Single item view (UserDetailPage, ProductPage)
+- `Form` - Create/Edit forms (CreateUserPage, EditProductPage)
+- `Dashboard` - Analytics/overview (DashboardPage, AdminPage)
+- `Auth` - Authentication (LoginPage, RegisterPage)
+- `Static` - Content pages (AboutPage, ContactPage)
+
+## Step 3: Detect Routing Pattern
+
+**Next.js App Router:**
+```
+app/
+├── page.tsx              # /
+├── users/
+│   ├── page.tsx          # /users
+│   └── [id]/
+│       └── page.tsx      # /users/:id
+└── layout.tsx
+```
+
+**Next.js Pages Router:**
+```
+pages/
+├── index.tsx             # /
+├── users/
+│   ├── index.tsx         # /users
+│   └── [id].tsx          # /users/:id
+└── _app.tsx
+```
+
+**React Router:**
+```
+src/
+├── pages/
+│   ├── HomePage.tsx
+│   ├── UsersPage.tsx
+│   └── UserDetailPage.tsx
+└── routes.tsx
+```
+
+**TanStack Router:**
+```
+src/
+├── routes/
+│   ├── __root.tsx
+│   ├── index.tsx         # /
+│   ├── users.tsx         # /users
+│   └── users.$id.tsx     # /users/:id
+└── routeTree.gen.ts
+```
+
+## Step 4: Review Existing Pages
+
+Find and analyze existing pages to detect:
+- File naming conventions
+- Data fetching patterns
+- Layout usage
+- Error handling approach
+- Loading state patterns
+- SEO/meta patterns
+- Authentication checks
+
+## Step 5: Generate Page
+
+Create page following detected patterns:
+
+### Next.js App Router
+
+**Server Component (default):**
+```typescript
+import { Metadata } from 'next'
+
+export const metadata: Metadata = {
+  title: 'Page Title',
+  description: 'Page description',
+}
+
+interface PageProps {
+  params: { id: string }
+  searchParams: { [key: string]: string | undefined }
+}
+
+export default async function Page({ params, searchParams }: PageProps) {
+  const data = await fetchData(params.id)
+
+  return (
+    <main>
+      <h1>{data.title}</h1>
+    </main>
+  )
+}
+```
+
+**With Loading State:**
+```typescript
+// loading.tsx
+export default function Loading() {
+  return <PageSkeleton />
+}
+```
+
+**With Error Handling:**
+```typescript
+// error.tsx
+'use client'
+
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error
+  reset: () => void
+}) {
+  return (
+    <div>
+      <h2>Something went wrong!</h2>
+      <button onClick={reset}>Try again</button>
+    </div>
+  )
+}
+```
+
+### Next.js Pages Router
+
+```typescript
+import { GetServerSideProps } from 'next'
+import Head from 'next/head'
+
+interface PageProps {
+  data: DataType
+}
+
+export default function Page({ data }: PageProps) {
+  return (
+    <>
+      <Head>
+        <title>Page Title</title>
+        <meta name="description" content="Description" />
+      </Head>
+      <main>
+        <h1>{data.title}</h1>
+      </main>
+    </>
+  )
+}
+
+export const getServerSideProps: GetServerSideProps<PageProps> = async (context) => {
+  const data = await fetchData(context.params?.id)
+  return { props: { data } }
+}
+```
+
+### React Router
+
+```typescript
+import { useParams, useSearchParams } from 'react-router-dom'
+import { useQuery } from '@tanstack/react-query'
+
+export function UserDetailPage() {
+  const { id } = useParams<{ id: string }>()
+  const [searchParams] = useSearchParams()
+
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['user', id],
+    queryFn: () => fetchUser(id!),
+  })
+
+  if (isLoading) return <PageSkeleton />
+  if (error) return <ErrorState error={error} />
+
+  return (
+    <main>
+      <h1>{data.name}</h1>
+    </main>
+  )
+}
+```
+
+### TanStack Router
+
+**File-based Route:**
+```typescript
+// routes/users.$id.tsx
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/users/$id')({
+  loader: ({ params }) => fetchUser(params.id),
+  pendingComponent: () => <PageSkeleton />,
+  errorComponent: ({ error }) => <ErrorState error={error} />,
+  component: UserDetailPage,
+})
+
+function UserDetailPage() {
+  const { id } = Route.useParams()
+  const data = Route.useLoaderData()
+
+  return (
+    <main>
+      <h1>{data.name}</h1>
+    </main>
+  )
+}
+```
+
+**With Search Params:**
+```typescript
+import { createFileRoute } from '@tanstack/react-router'
+import { z } from 'zod'
+
+const searchSchema = z.object({
+  page: z.number().optional().default(1),
+  search: z.string().optional(),
+})
+
+export const Route = createFileRoute('/users')({
+  validateSearch: searchSchema,
+  loaderDeps: ({ search }) => ({ search }),
+  loader: ({ deps }) => fetchUsers(deps.search),
+  component: UsersPage,
+})
+
+function UsersPage() {
+  const { page, search } = Route.useSearch()
+  const data = Route.useLoaderData()
+
+  return (
+    <main>
+      <UserList users={data} />
+    </main>
+  )
+}
+```
+
+## Step 6: Generate Route Configuration
+
+**React Router:**
+```typescript
+// routes.tsx
+import { createBrowserRouter } from 'react-router-dom'
+import { UserDetailPage } from './pages/UserDetailPage'
+import { RootLayout } from './layouts/RootLayout'
+
+export const router = createBrowserRouter([
+  {
+    path: '/',
+    element: <RootLayout />,
+    children: [
+      {
+        path: 'users/:id',
+        element: <UserDetailPage />,
+      },
+    ],
+  },
+])
+```
+
+**TanStack Router (code-based):**
+```typescript
+import { createRoute } from '@tanstack/react-router'
+import { rootRoute } from './__root'
+
+export const userDetailRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/users/$id',
+  loader: ({ params }) => fetchUser(params.id),
+  component: UserDetailPage,
+})
+```
+
+## Step 7: Add Authentication Guard (if needed)
+
+**Next.js Middleware:**
+```typescript
+// middleware.ts
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get('token')
+  if (!token) {
+    return NextResponse.redirect(new URL('/login', request.url))
+  }
+}
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/admin/:path*'],
+}
+```
+
+**React Router:**
+```typescript
+function ProtectedRoute({ children }: { children: React.ReactNode }) {
+  const { user, isLoading } = useAuth()
+  const location = useLocation()
+
+  if (isLoading) return <Loading />
+  if (!user) return <Navigate to="/login" state={{ from: location }} />
+
+  return children
+}
+```
+
+**TanStack Router:**
+```typescript
+export const Route = createFileRoute('/dashboard')({
+  beforeLoad: ({ context }) => {
+    if (!context.auth.isAuthenticated) {
+      throw redirect({ to: '/login' })
+    }
+  },
+  component: DashboardPage,
+})
+```
+
+## Step 8: Generate Test File (if testing exists)
+
+**React Router Test:**
+```typescript
+import { render, screen, waitFor } from '@testing-library/react'
+import { createMemoryRouter, RouterProvider } from 'react-router-dom'
+import { UserDetailPage } from './UserDetailPage'
+
+describe('UserDetailPage', () => {
+  it('renders user data', async () => {
+    const router = createMemoryRouter(
+      [{ path: '/users/:id', element: <UserDetailPage /> }],
+      { initialEntries: ['/users/1'] }
+    )
+
+    render(<RouterProvider router={router} />)
+
+    await waitFor(() => {
+      expect(screen.getByText('John Doe')).toBeInTheDocument()
+    })
+  })
+})
+```
+
+**TanStack Router Test:**
+```typescript
+import { render, screen, waitFor } from '@testing-library/react'
+import { createRouter, RouterProvider } from '@tanstack/react-router'
+import { routeTree } from './routeTree.gen'
+
+describe('UserDetailPage', () => {
+  it('renders user data', async () => {
+    const router = createRouter({
+      routeTree,
+      history: createMemoryHistory({ initialEntries: ['/users/1'] }),
+    })
+
+    render(<RouterProvider router={router} />)
+
+    await waitFor(() => {
+      expect(screen.getByText('John Doe')).toBeInTheDocument()
+    })
+  })
+})
+```
+
+## Step 9: Show Generated Files
+
+Display:
+1. All file paths to create
+2. Full content for each file
+3. Page structure diagram:
+
+```
+┌─────────────────────────────────────┐
+│ PageName                            │
+├─────────────────────────────────────┤
+│ Route: /path/:param                 │
+│ Layout: MainLayout                  │
+│ Auth: Required                      │
+├─────────────────────────────────────┤
+│ Data Fetching:                      │
+│   - TanStack Query / Route Loader   │
+│   - API: GET /api/resource/:id      │
+├─────────────────────────────────────┤
+│ Files:                              │
+│   - page.tsx / route file           │
+│   - loading.tsx (Next.js)           │
+│   - error.tsx (Next.js)             │
+│   - page.test.tsx                   │
+└─────────────────────────────────────┘
+```
+
+## Step 10: Navigation Example
+
+**React Router:**
+```typescript
+import { Link, useNavigate } from 'react-router-dom'
+
+// Link navigation
+<Link to="/users/123">View User</Link>
+
+// Programmatic navigation
+const navigate = useNavigate()
+navigate('/users/123')
+navigate('/users/123', { state: { from: 'list' } })
+```
+
+**TanStack Router:**
+```typescript
+import { Link, useNavigate } from '@tanstack/react-router'
+
+// Link navigation (type-safe)
+<Link to="/users/$id" params={{ id: '123' }}>View User</Link>
+
+// Programmatic navigation
+const navigate = useNavigate()
+navigate({ to: '/users/$id', params: { id: '123' } })
+```
+
+## Step 11: Next Steps
+
+Suggest related actions:
+- Add to navigation menu
+- Create related API endpoints: `/create-api [resource]`
+- Add breadcrumbs
+- Implement search/filter functionality
+
+Generate page now for: $ARGUMENTS