@smicolon/ai-kit 0.0.1 → 0.1.1

package/packs/tanstack-router/commands/form-create.md

@@ -0,0 +1,313 @@
+---
+name: form-create
+description: Create TanStack Form components with Zod validation
+args:
+  - name: name
+    description: Form name (e.g., CreatePost, EditUser, Login)
+    required: false
+  - name: feature
+    description: Feature the form belongs to (e.g., posts, users, auth)
+    required: false
+---
+
+# Create TanStack Form
+
+Create a form component with TanStack Form and Zod validation.
+
+## Instructions
+
+1. **Gather Information** (if not provided via args):
+   - Ask for the form name (e.g., `CreatePostForm`, `EditUserForm`)
+   - Ask for the feature it belongs to
+   - Ask for the fields the form should have
+   - Ask if it should integrate with a mutation hook
+
+2. **Create Zod Schema** in `src/features/{feature}/schemas/{name}Schema.ts`:
+   ```typescript
+   import { z } from 'zod'
+
+   export const {name}Schema = z.object({
+     title: z.string().min(3, 'Title must be at least 3 characters'),
+     content: z.string().min(10, 'Content must be at least 10 characters'),
+     email: z.string().email('Invalid email address'),
+     // Add more fields as needed
+   })
+
+   export type {Name}FormData = z.infer<typeof {name}Schema>
+   ```
+
+3. **Create Form Component** in `src/features/{feature}/components/{Name}Form.tsx`:
+
+   For a **create form**:
+   ```typescript
+   import { useForm } from '@tanstack/react-form'
+   import { zodValidator } from '@tanstack/zod-form-adapter'
+   import { {name}Schema, type {Name}FormData } from '../schemas/{name}Schema'
+   import { useCreate{Feature} } from '../hooks'
+   import { FormField } from '@/components/ui/FormField'
+
+   interface {Name}FormProps {
+     onSuccess?: () => void
+   }
+
+   export function {Name}Form({ onSuccess }: {Name}FormProps) {
+     const create{Feature} = useCreate{Feature}()
+
+     const form = useForm({
+       defaultValues: {
+         title: '',
+         content: '',
+         // ... default values for all fields
+       } satisfies {Name}FormData,
+       onSubmit: async ({ value }) => {
+         await create{Feature}.mutateAsync(value)
+         onSuccess?.()
+       },
+       validatorAdapter: zodValidator(),
+       validators: {
+         onChange: {name}Schema,
+       },
+     })
+
+     return (
+       <form
+         onSubmit={(e) => {
+           e.preventDefault()
+           form.handleSubmit()
+         }}
+         className="space-y-4"
+       >
+         <form.Field
+           name="title"
+           children={(field) => (
+             <div className="form-field">
+               <label htmlFor={field.name}>Title</label>
+               <input
+                 id={field.name}
+                 value={field.state.value}
+                 onChange={(e) => field.handleChange(e.target.value)}
+                 onBlur={field.handleBlur}
+                 aria-invalid={field.state.meta.errors.length > 0}
+                 aria-describedby={`${field.name}-error`}
+               />
+               {field.state.meta.isTouched && field.state.meta.errors.length > 0 && (
+                 <span id={`${field.name}-error`} className="error" role="alert">
+                   {field.state.meta.errors[0]}
+                 </span>
+               )}
+             </div>
+           )}
+         />
+
+         <form.Field
+           name="content"
+           children={(field) => (
+             <div className="form-field">
+               <label htmlFor={field.name}>Content</label>
+               <textarea
+                 id={field.name}
+                 value={field.state.value}
+                 onChange={(e) => field.handleChange(e.target.value)}
+                 onBlur={field.handleBlur}
+                 rows={5}
+                 aria-invalid={field.state.meta.errors.length > 0}
+               />
+               {field.state.meta.isTouched && field.state.meta.errors.length > 0 && (
+                 <span className="error" role="alert">
+                   {field.state.meta.errors[0]}
+                 </span>
+               )}
+             </div>
+           )}
+         />
+
+         {/* Add more fields as needed */}
+
+         <form.Subscribe
+           selector={(state) => [state.canSubmit, state.isSubmitting]}
+           children={([canSubmit, isSubmitting]) => (
+             <button
+               type="submit"
+               disabled={!canSubmit || isSubmitting}
+               className="btn btn-primary"
+             >
+               {isSubmitting ? 'Saving...' : 'Save'}
+             </button>
+           )}
+         />
+
+         {create{Feature}.isError && (
+           <div className="error" role="alert">
+             {create{Feature}.error.message}
+           </div>
+         )}
+       </form>
+     )
+   }
+   ```
+
+   For an **edit form** with initial data:
+   ```typescript
+   import { useForm } from '@tanstack/react-form'
+   import { zodValidator } from '@tanstack/zod-form-adapter'
+   import { {name}Schema, type {Name}FormData } from '../schemas/{name}Schema'
+   import { useUpdate{Feature} } from '../hooks'
+   import type { {Feature} } from '../types'
+
+   interface {Name}FormProps {
+     {feature}: {Feature}
+     onSuccess?: () => void
+   }
+
+   export function {Name}Form({ {feature}, onSuccess }: {Name}FormProps) {
+     const update{Feature} = useUpdate{Feature}()
+
+     const form = useForm({
+       defaultValues: {
+         title: {feature}.title,
+         content: {feature}.content,
+         // ... populate from existing data
+       } satisfies {Name}FormData,
+       onSubmit: async ({ value }) => {
+         await update{Feature}.mutateAsync({ id: {feature}.id, ...value })
+         onSuccess?.()
+       },
+       validatorAdapter: zodValidator(),
+       validators: {
+         onChange: {name}Schema,
+       },
+     })
+
+     return (
+       <form onSubmit={(e) => { e.preventDefault(); form.handleSubmit() }}>
+         {/* Same field structure as create form */}
+       </form>
+     )
+   }
+   ```
+
+4. **Create Reusable Form Field Component** (if not exists) in `src/components/ui/FormField.tsx`:
+   ```typescript
+   import type { FieldApi } from '@tanstack/react-form'
+
+   interface FormFieldProps<T> {
+     field: FieldApi<any, any, any, any, T>
+     label: string
+     type?: 'text' | 'email' | 'password' | 'textarea' | 'number'
+     placeholder?: string
+   }
+
+   export function FormField<T extends string | number>({
+     field,
+     label,
+     type = 'text',
+     placeholder,
+   }: FormFieldProps<T>) {
+     const hasError = field.state.meta.isTouched && field.state.meta.errors.length > 0
+
+     const inputProps = {
+       id: field.name,
+       name: field.name,
+       value: field.state.value,
+       onChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => {
+         const value = type === 'number' ? Number(e.target.value) : e.target.value
+         field.handleChange(value as T)
+       },
+       onBlur: field.handleBlur,
+       placeholder,
+       'aria-invalid': hasError,
+       'aria-describedby': hasError ? `${field.name}-error` : undefined,
+     }
+
+     return (
+       <div className="form-field">
+         <label htmlFor={field.name}>{label}</label>
+         {type === 'textarea' ? (
+           <textarea {...inputProps} rows={5} />
+         ) : (
+           <input type={type} {...inputProps} />
+         )}
+         {hasError && (
+           <span id={`${field.name}-error`} className="error" role="alert">
+             {field.state.meta.errors[0]}
+           </span>
+         )}
+       </div>
+     )
+   }
+   ```
+
+5. **Handle Array Fields** (if needed):
+   ```typescript
+   <form.Field
+     name="tags"
+     mode="array"
+     children={(field) => (
+       <div className="form-field">
+         <label>Tags</label>
+         {field.state.value.map((_, index) => (
+           <div key={index} className="flex gap-2">
+             <form.Field
+               name={`tags[${index}]`}
+               children={(tagField) => (
+                 <input
+                   value={tagField.state.value}
+                   onChange={(e) => tagField.handleChange(e.target.value)}
+                 />
+               )}
+             />
+             <button type="button" onClick={() => field.removeValue(index)}>
+               Remove
+             </button>
+           </div>
+         ))}
+         <button type="button" onClick={() => field.pushValue('')}>
+           Add Tag
+         </button>
+       </div>
+     )}
+   />
+   ```
+
+6. **Add Async Validation** (if needed):
+   ```typescript
+   <form.Field
+     name="username"
+     validators={{
+       onChange: z.string().min(3),
+       onChangeAsyncDebounceMs: 500,
+       onChangeAsync: async ({ value }) => {
+         const exists = await checkUsernameExists(value)
+         return exists ? 'Username already taken' : undefined
+       },
+     }}
+     children={(field) => (
+       <div>
+         <input {...inputProps} />
+         {field.state.meta.isValidating && <span>Checking...</span>}
+         {/* error display */}
+       </div>
+     )}
+   />
+   ```
+
+7. **Update Barrel Exports**:
+   ```typescript
+   // src/features/{feature}/components/index.ts
+   export { {Name}Form } from './{Name}Form'
+
+   // src/features/{feature}/schemas/index.ts
+   export * from './{name}Schema'
+   ```
+
+## Quality Checklist
+
+- [ ] Zod schema validates all fields
+- [ ] Form uses `zodValidator()` adapter
+- [ ] All fields have proper labels with htmlFor
+- [ ] Error messages use role="alert" for accessibility
+- [ ] aria-invalid and aria-describedby properly set
+- [ ] Submit button disabled during submission
+- [ ] Mutation errors displayed to user
+- [ ] defaultValues use `satisfies` for type checking
+- [ ] Form prevents default submission

package/packs/tanstack-router/commands/query-create.md

@@ -0,0 +1,263 @@
+---
+name: query-create
+description: Create TanStack Query options, mutations, and hooks with factory pattern
+args:
+  - name: feature
+    description: Feature name (e.g., posts, users, orders)
+    required: false
+  - name: type
+    description: Query type (query, mutation, infinite)
+    required: false
+---
+
+# Create TanStack Query
+
+Create query options, mutations, and hooks following the factory pattern.
+
+## Instructions
+
+1. **Gather Information** (if not provided via args):
+   - Ask for the feature name (e.g., `posts`, `users`)
+   - Ask for the query type: query, mutation, or infinite query
+   - Ask for the operation (e.g., list, detail, create, update, delete)
+
+2. **Create Feature Directory Structure** (if new feature):
+   ```
+   src/features/{feature}/
+   ├── api/
+   │   └── {feature}Api.ts
+   ├── queries/
+   │   ├── {feature}Queries.ts
+   │   └── index.ts
+   ├── hooks/
+   │   ├── use{Operation}{Feature}.ts
+   │   └── index.ts
+   ├── types.ts
+   └── index.ts
+   ```
+
+3. **Create/Update Query Keys** in `src/lib/query-keys.ts`:
+   ```typescript
+   export const queryKeys = {
+     {feature}: {
+       all: () => ['{feature}'] as const,
+       lists: () => [...queryKeys.{feature}.all(), 'list'] as const,
+       list: (filters: {Feature}Filters) => [...queryKeys.{feature}.lists(), filters] as const,
+       details: () => [...queryKeys.{feature}.all(), 'detail'] as const,
+       detail: (id: string) => [...queryKeys.{feature}.details(), id] as const,
+     },
+   } as const
+   ```
+
+4. **Create API Functions** in `src/features/{feature}/api/{feature}Api.ts`:
+   ```typescript
+   import { apiClient } from '@/lib/api-client'
+   import type { {Feature}, Create{Feature}Input, Update{Feature}Input, {Feature}Filters } from '../types'
+
+   export const {feature}Api = {
+     get{Feature}s: async (filters?: {Feature}Filters): Promise<{Feature}[]> => {
+       const response = await apiClient.get('/{feature}', { params: filters })
+       return response.data
+     },
+
+     get{Feature}: async (id: string): Promise<{Feature}> => {
+       const response = await apiClient.get(`/{feature}/${id}`)
+       return response.data
+     },
+
+     create{Feature}: async (input: Create{Feature}Input): Promise<{Feature}> => {
+       const response = await apiClient.post('/{feature}', input)
+       return response.data
+     },
+
+     update{Feature}: async ({ id, ...input }: Update{Feature}Input): Promise<{Feature}> => {
+       const response = await apiClient.patch(`/{feature}/${id}`, input)
+       return response.data
+     },
+
+     delete{Feature}: async (id: string): Promise<void> => {
+       await apiClient.delete(`/{feature}/${id}`)
+     },
+   }
+   ```
+
+5. **Create Query Options** in `src/features/{feature}/queries/{feature}Queries.ts`:
+
+   For **list query**:
+   ```typescript
+   import { queryOptions } from '@tanstack/react-query'
+   import { queryKeys } from '@/lib/query-keys'
+   import { {feature}Api } from '../api/{feature}Api'
+   import type { {Feature}Filters } from '../types'
+
+   export const {feature}sQueryOptions = (filters: {Feature}Filters = {}) =>
+     queryOptions({
+       queryKey: queryKeys.{feature}.list(filters),
+       queryFn: () => {feature}Api.get{Feature}s(filters),
+       staleTime: 1 * 60 * 1000, // 1 minute
+     })
+   ```
+
+   For **detail query**:
+   ```typescript
+   export const {feature}QueryOptions = (id: string) =>
+     queryOptions({
+       queryKey: queryKeys.{feature}.detail(id),
+       queryFn: () => {feature}Api.get{Feature}(id),
+       staleTime: 5 * 60 * 1000, // 5 minutes
+     })
+   ```
+
+   For **infinite query**:
+   ```typescript
+   import { infiniteQueryOptions } from '@tanstack/react-query'
+
+   export const {feature}sInfiniteQueryOptions = (filters: {Feature}Filters = {}) =>
+     infiniteQueryOptions({
+       queryKey: queryKeys.{feature}.list({ ...filters, infinite: true }),
+       queryFn: ({ pageParam = 1 }) =>
+         {feature}Api.get{Feature}s({ ...filters, page: pageParam }),
+       getNextPageParam: (lastPage) =>
+         lastPage.hasMore ? lastPage.nextPage : undefined,
+       initialPageParam: 1,
+     })
+   ```
+
+6. **Create Mutation Hooks** in `src/features/{feature}/hooks/`:
+
+   For **create mutation** (`useCreate{Feature}.ts`):
+   ```typescript
+   import { useMutation, useQueryClient } from '@tanstack/react-query'
+   import { queryKeys } from '@/lib/query-keys'
+   import { {feature}Api } from '../api/{feature}Api'
+
+   export function useCreate{Feature}() {
+     const queryClient = useQueryClient()
+
+     return useMutation({
+       mutationFn: {feature}Api.create{Feature},
+       onSuccess: () => {
+         queryClient.invalidateQueries({ queryKey: queryKeys.{feature}.lists() })
+       },
+     })
+   }
+   ```
+
+   For **update mutation** with optimistic update (`useUpdate{Feature}.ts`):
+   ```typescript
+   import { useMutation, useQueryClient } from '@tanstack/react-query'
+   import { queryKeys } from '@/lib/query-keys'
+   import { {feature}Api } from '../api/{feature}Api'
+   import type { {Feature}, Update{Feature}Input } from '../types'
+
+   export function useUpdate{Feature}() {
+     const queryClient = useQueryClient()
+
+     return useMutation({
+       mutationFn: {feature}Api.update{Feature},
+       onMutate: async (newData: Update{Feature}Input) => {
+         await queryClient.cancelQueries({
+           queryKey: queryKeys.{feature}.detail(newData.id)
+         })
+
+         const previous = queryClient.getQueryData<{Feature}>(
+           queryKeys.{feature}.detail(newData.id)
+         )
+
+         queryClient.setQueryData(
+           queryKeys.{feature}.detail(newData.id),
+           (old: {Feature} | undefined) => old ? { ...old, ...newData } : undefined
+         )
+
+         return { previous }
+       },
+       onError: (err, newData, context) => {
+         if (context?.previous) {
+           queryClient.setQueryData(
+             queryKeys.{feature}.detail(newData.id),
+             context.previous
+           )
+         }
+       },
+       onSettled: (data, error, variables) => {
+         queryClient.invalidateQueries({
+           queryKey: queryKeys.{feature}.detail(variables.id)
+         })
+       },
+     })
+   }
+   ```
+
+   For **delete mutation** (`useDelete{Feature}.ts`):
+   ```typescript
+   import { useMutation, useQueryClient } from '@tanstack/react-query'
+   import { queryKeys } from '@/lib/query-keys'
+   import { {feature}Api } from '../api/{feature}Api'
+
+   export function useDelete{Feature}() {
+     const queryClient = useQueryClient()
+
+     return useMutation({
+       mutationFn: {feature}Api.delete{Feature},
+       onSuccess: () => {
+         queryClient.invalidateQueries({ queryKey: queryKeys.{feature}.all() })
+       },
+     })
+   }
+   ```
+
+7. **Create Types** in `src/features/{feature}/types.ts`:
+   ```typescript
+   export interface {Feature} {
+     id: string
+     // ... feature fields
+     createdAt: string
+     updatedAt: string
+   }
+
+   export interface Create{Feature}Input {
+     // ... creation fields
+   }
+
+   export interface Update{Feature}Input extends Partial<Create{Feature}Input> {
+     id: string
+   }
+
+   export interface {Feature}Filters {
+     page?: number
+     pageSize?: number
+     search?: string
+     // ... filter fields
+   }
+   ```
+
+8. **Create Barrel Exports**:
+
+   `src/features/{feature}/queries/index.ts`:
+   ```typescript
+   export * from './{feature}Queries'
+   ```
+
+   `src/features/{feature}/hooks/index.ts`:
+   ```typescript
+   export * from './useCreate{Feature}'
+   export * from './useUpdate{Feature}'
+   export * from './useDelete{Feature}'
+   ```
+
+   `src/features/{feature}/index.ts`:
+   ```typescript
+   export * from './queries'
+   export * from './hooks'
+   export * from './types'
+   ```
+
+## Quality Checklist
+
+- [ ] Query keys follow factory pattern
+- [ ] Query options use `queryOptions()` helper
+- [ ] Mutations invalidate relevant queries
+- [ ] Optimistic updates include rollback logic
+- [ ] Types are properly defined and exported
+- [ ] Barrel exports are in place
+- [ ] API functions match expected backend endpoints