@nerdev/skillset 0.2.1

package/skills/ui/ask-drawer/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: ask-drawer
+description: Pattern guide for mobile drawers/sheets: bottom sheets, side drawers, swipe gestures, nested drawers. Load via ui-engineering. Invokes pick-ui-library → recommends Vaul → loads ask-vaul for implementation.
+---
+
+# Ask Drawer: Mobile Bottom Sheets, Side Drawers
+
+**When to use:** Mobile-first overlays: filters, actions, navigation, forms, any sheet that slides from bottom/side.
+
+
+## The Pattern
+
+| Drawer Type | Use When | Key Behaviors |
+|-------------|----------|---------------|
+| **Bottom Sheet** | Mobile filters, share, actions | Drag handle, snap points (half/full), swipe down dismiss, backdrop |
+| **Side Drawer** | Mobile nav, settings panel | Swipe from edge, backdrop, ESC closes, focus trap |
+| **Nested Drawer** | Drill-down (category → subcategory) | Stack, back gesture, breadcrumb |
+
+
+## Quality Checklist
+
+- [ ] **Vaul**: Headless, accessible, gesture-driven, spring physics
+- [ ] **Drag handle**: Visual indicator, click/tap toggles
+- [ ] **Snap points**: Half (50%), Full (90%), custom percentages
+- [ ] **Swipe to dismiss**: Velocity-based, spring back if slow
+- [ ] **Backdrop**: Blur + dim, click closes
+- [ ] **Focus trap**: Inside drawer, restore on close
+- [ ] **Keyboard**: ESC closes, Tab cycles
+- [ ] **Animation**: Spring (stiffness: 500, damping: 30), 200ms
+- [ ] **Reduced motion**: Instant snap
+- [ ] **Safe area**: Respects home indicator, notch
+- [ ] **Scroll lock**: Body locked, drawer scrolls independently
+
+
+## Anti-Patterns
+
+- ❌ Custom div + transform: No gestures, no physics, no accessibility
+- ❌ Fixed height: Doesn't adapt to content
+- ❌ No drag handle: User doesn't know it's draggable
+- ❌ No snap points: Awkward intermediate states
+- ❌ No swipe dismiss: Must hunt for close button
+- ❌ No focus trap: Keyboard trap
+- ❌ Z-index wars: Portal to root
+- ❌ Ignores safe area: Content under home indicator
+
+
+## Implementation Flow
+
+```
+User needs mobile drawer/sheet
+    │
+    ├─► ui-engineering detects "drawer/bottom sheet/side drawer/mobile sheet"
+    │
+    ├─► pick-ui-library → recommends Vaul
+    │
+    ├─► load ask-vaul (library skill)
+    │
+    └─► implement with Vaul + custom composition
+```
+
+
+## Vaul Primitives
+
+```tsx
+import { Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription, DrawerClose } from 'vaul'
+
+// Bottom Sheet
+<Drawer direction="bottom" snapPoints={[0.5, 1]} onOpenChange={setIsOpen}>
+  <DrawerTrigger asChild>
+    <Button variant="outline">Open Filters</Button>
+  </DrawerTrigger>
+  <DrawerContent className="rounded-t-2xl">
+    <DrawerHeader>
+      <DrawerTitle>Filters</DrawerTitle>
+      <DrawerDescription>Refine your results</DrawerDescription>
+    </DrawerHeader>
+    <div className="p-4 space-y-4 max-h-[80vh] overflow-y-auto">
+      {/* Content */}
+    </div>
+  </DrawerContent>
+</Drawer>
+
+// Side Drawer (Navigation)
+<Drawer direction="right" snapPoints={[1]}>
+  <DrawerTrigger asChild>
+    <Button variant="ghost" className="md:hidden"><Menu className="h-6 w-6" /></Button>
+  </DrawerTrigger>
+  <DrawerContent className="w-72 max-w-[85vw]">
+    <DrawerHeader className="border-b p-4">
+      <DrawerTitle>Menu</DrawerTitle>
+    </DrawerHeader>
+    <nav className="p-4 space-y-2">
+      {/* Navigation links */}
+    </nav>
+  </DrawerContent>
+</Drawer>
+```
+
+
+## Composition Examples
+
+### Filter Bottom Sheet (Linear-style)
+```tsx
+function FilterDrawer({ filters, onChange, onApply, onReset }) {
+  return (
+    <Drawer direction="bottom" snapPoints={[0.4, 0.85, 1]}>
+      <DrawerTrigger asChild>
+        <Button variant="outline" className="gap-2">
+          <Filter className="h-4 w-4" />
+          Filters
+          {Object.values(filters).some(v => v) && <Badge variant="secondary">{activeCount}</Badge>}
+        </Button>
+      </DrawerTrigger>
+      <DrawerContent className="rounded-t-2xl">
+        <div className="flex items-center justify-between p-4 border-b">
+          <DrawerTitle>Filters</DrawerTitle>
+          <Button variant="ghost" size="icon" onClick={onReset} disabled={!hasActiveFilters}>
+            <RotateCcw className="h-4 w-4" />
+          </Button>
+        </div>
+        <div className="p-4 space-y-6 max-h-[70vh] overflow-y-auto">
+          <FilterSection title="Status" options={statusOptions} value={filters.status} onChange={v => onChange('status', v)} />
+          <FilterSection title="Assignee" options={assignees} value={filters.assignee} onChange={v => onChange('assignee', v)} multi />
+          <FilterSection title="Date Range" render={<DateRangePicker value={filters.dateRange} onChange={v => onChange('dateRange', v)} />} />
+        </div>
+        <div className="flex gap-2 p-4 border-t">
+          <Button variant="outline" className="flex-1" onClick={onReset}>Reset</Button>
+          <Button className="flex-1" onClick={onApply}>Apply ({activeCount})</Button>
+        </div>
+      </DrawerContent>
+    </Drawer>
+  )
+}
+```
+
+### Mobile Nav Drawer (Raycast-style)
+```tsx
+function MobileNavDrawer() {
+  const navigation = [
+    { href: '/', label: 'Dashboard', icon: Home },
+    { href: '/projects', label: 'Projects', icon: Folder },
+    { href: '/tasks', label: 'Tasks', icon: CheckSquare },
+    { href: '/settings', label: 'Settings', icon: Settings },
+  ]
+
+  return (
+    <Drawer direction="left" snapPoints={[1]}>
+      <DrawerTrigger asChild>
+        <Button variant="ghost" className="md:hidden p-2" aria-label="Open menu">
+          <Menu className="h-6 w-6" />
+        </Button>
+      </DrawerTrigger>
+      <DrawerContent className="w-72 max-w-[85vw]">
+        <DrawerHeader className="flex items-center justify-between p-4 border-b">
+          <DrawerTitle>Navigation</DrawerTitle>
+          <DrawerClose asChild>
+            <Button variant="ghost" size="icon" className="md:hidden"><X className="h-5 w-5" /></Button>
+          </DrawerClose>
+        </DrawerHeader>
+        <nav className="flex-1 overflow-y-auto p-4 space-y-1">
+          {navigation.map((item) => (
+            <Link
+              key={item.href}
+              href={item.href}
+              className="flex items-center gap-3 px-3 py-2 rounded-lg text-gray-700 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800"
+              onClick={() => drawer.close()}
+            >
+              <item.icon className="h-5 w-5" />
+              {item.label}
+            </Link>
+          ))}
+        </nav>
+        <div className="p-4 border-t">
+          <p className="text-xs text-gray-500 text-center">v1.2.3</p>
+        </div>
+      </DrawerContent>
+    </Drawer>
+  )
+}
+```
+
+
+## Nested Drawers (Drill-down)
+
+```tsx
+function NestedCategoryDrawer({ categories, onSelect }) {
+  const [stack, setStack] = useState<Category[]>([rootCategory])
+
+  const current = stack[stack.length - 1]
+
+  return (
+    <Drawer direction="bottom" snapPoints={[1]}>
+      <DrawerContent className="rounded-t-2xl">
+        <DrawerHeader className="flex items-center justify-between p-4 border-b">
+          <DrawerTitle>{current.name}</DrawerTitle>
+          <div className="flex gap-2">
+            {stack.length > 1 && (
+              <DrawerClose asChild>
+                <Button variant="ghost" size="icon" onClick={() => setStack(s => s.slice(0, -1))}>
+                  <ChevronLeft className="h-5 w-5" />
+                </Button>
+              </DrawerClose>
+            )}
+            <DrawerClose asChild>
+              <Button variant="ghost" size="icon"><X className="h-5 w-5" /></Button>
+            </DrawerClose>
+          </div>
+        </DrawerHeader>
+        <div className="p-4 space-y-2 max-h-[70vh] overflow-y-auto">
+          {current.children?.map((child) => (
+            <Button
+              key={child.id}
+              variant="outline"
+              className="w-full justify-between"
+              onClick={() => child.children ? setStack(s => [...s, child]) : onSelect(child)}
+            >
+              {child.name}
+              {child.children && <ChevronRight className="h-4 w-4" />}
+            </Button>
+          ))}
+        </div>
+      </DrawerContent>
+    </Drawer>
+  )
+}
+```
+
+
+## When to Escalate
+
+| Need | Escalate To |
+|------|-------------|
+| Form in drawer | `ask-form` + `ask-rhf` |
+| Toast on action | `ask-toast` + `ask-sonner` |
+| Complex animation | `ask-animation` + `ask-motion` |

package/skills/ui/ask-form/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: ask-form
+description: Pattern guide for forms, validation, server actions, submission states. Load via ui-engineering. Invokes pick-ui-library → recommends react-hook-form + zod → loads ask-rhf for implementation.
+---
+
+# Ask Form: Forms, Validation, Server Actions
+
+**When to use:** Any form: settings, onboarding, auth, checkout, data entry, filters, search.
+
+
+## The Pattern (What Good Looks Like)
+
+| Form Type | Use When | Key Behaviors |
+|-----------|----------|---------------|
+| **Simple** | Login, search, quick settings | Client validation, instant feedback |
+| **Multi-step** | Onboarding, wizards | Progress, save draft, resume |
+| **Server action** | Mutations, creates, updates | Loading state, optimistic UI, error handling |
+| **Complex** | Nested fields, arrays, conditionals | Field arrays, watch, dynamic validation |
+| **File upload** | Avatars, documents, media | Drag-drop, preview, progress, validation |
+
+
+## Quality Checklist
+
+- [ ] **React Hook Form**: Uncontrolled, performant, minimal re-renders
+- [ ] **Zod schema**: Single source of truth for validation (client + server)
+- [ ] **Inline validation**: On blur (not on change), show error at field
+- [ ] **Submit handling**: Loading state, disabled, prevent double-submit
+- [ ] **Server errors**: Map to fields, show at top + inline
+- [ ] **Optimistic UI**: Update immediately, rollback on error
+- [ ] **Keyboard**: Enter submits (except textarea), Tab navigates
+- [ ] **Accessibility**: Labels, `aria-describedby` for errors, `aria-invalid`
+- [ ] **Auto-focus**: First error on submit, first field on mount
+- [ ] **Dirty tracking**: Warn on leave if unsaved changes
+- [ ] **Reset**: Clear errors on change, reset form after success
+
+
+## Anti-Patterns
+
+- ❌ Controlled inputs with `useState` per field: Slow, boilerplate
+- ❌ No schema: Validation scattered, inconsistent client/server
+- ❌ Validate on change: Annoying, shows errors before user finishes
+- ❌ No loading state: Double submits, no feedback
+- ❌ Server errors only at top: User hunts for field
+- ❌ No optimistic UI: Feels slow, no instant feedback
+- ❌ `onSubmit` in `<form>` without `preventDefault`: Page reload
+- ❌ File upload without preview/progress: Broken UX
+
+
+## Implementation Flow
+
+```
+User needs form
+    │
+    ├─► ui-engineering detects "form/validation/server action"
+    │
+    ├─► pick-ui-library → recommends react-hook-form + zod
+    │
+    ├─► load ask-rhf (library skill)
+    │
+    └─► implement with RHF + Zod + server actions + toast feedback
+```
+
+
+## Schema First (Zod)
+
+```tsx
+// schemas/project.ts
+import { z } from 'zod'
+
+export const projectSchema = z.object({
+  name: z.string().min(1, 'Name is required').max(100),
+  description: z.string().max(500).optional(),
+  visibility: z.enum(['private', 'team', 'public']),
+  tags: z.array(z.string()).max(5).optional(),
+})
+
+export type ProjectInput = z.infer<typeof projectSchema>
+```
+
+
+## Form Component (RHF + Zod + Server Action)
+
+```tsx
+// components/forms/ProjectForm.tsx
+'use client'
+
+import { useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { toast } from 'sonner'
+import { projectSchema, type ProjectInput } from '@/schemas/project'
+
+export function ProjectForm({ initialData, onSuccess }) {
+  const form = useForm<ProjectInput>({
+    resolver: zodResolver(projectSchema),
+    defaultValues: initialData,
+    mode: 'onBlur', // Validate on blur
+  })
+
+  async function onSubmit(data: ProjectInput) {
+    const toastId = toast.loading('Saving…')
+    try {
+      const result = await api.createProject(data) // Server action
+      toast.success('Project created', {
+        id: toastId,
+        action: { label: 'View', onClick: () => router.push(`/projects/${result.id}`) }
+      })
+      onSuccess?.(result)
+      form.reset()
+    } catch (err) {
+      toast.error('Failed to create', { id: toastId })
+      // Map server errors to fields
+      if (err.fieldErrors) {
+        Object.entries(err.fieldErrors).forEach(([field, messages]) => {
+          form.setError(field as keyof ProjectInput, { message: messages[0] })
+        })
+      }
+    }
+  }
+
+  return (
+    <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4" noValidate>
+      <div>
+        <label htmlFor="name" className="block text-sm font-medium mb-1">Name</label>
+        <input
+          id="name"
+          {...form.register('name')}
+          className={cn('w-full rounded-lg border px-3 py-2', form.formState.errors.name && 'border-red-500 focus:border-red-500')}
+        />
+        {form.formState.errors.name && (
+          <p className="mt-1 text-sm text-red-600" role="alert">{form.formState.errors.name.message}</p>
+        )}
+      </div>
+
+      <div>
+        <label htmlFor="description" className="block text-sm font-medium mb-1">Description</label>
+        <textarea
+          id="description"
+          {...form.register('description')}
+          rows={3}
+          className="w-full rounded-lg border px-3 py-2"
+        />
+      </div>
+
+      <div>
+        <label className="block text-sm font-medium mb-1">Visibility</label>
+        <select {...form.register('visibility')} className="w-full rounded-lg border px-3 py-2">
+          <option value="private">Private</option>
+          <option value="team">Team</option>
+          <option value="public">Public</option>
+        </select>
+      </div>
+
+      <div className="flex justify-end gap-2">
+        <Button type="button" variant="outline" onClick={onCancel}>Cancel</Button>
+        <Button type="submit" disabled={form.formState.isSubmitting}>
+          {form.formState.isSubmitting ? 'Saving…' : 'Create'}
+        </Button>
+      </div>
+    </form>
+  )
+}
+```
+
+
+## Server Action + Optimistic UI (Linear-style)
+
+```tsx
+// actions/project.ts
+'use server'
+
+import { revalidatePath } from 'next/cache'
+import { projectSchema, type ProjectInput } from '@/schemas/project'
+
+export async function createProject(data: ProjectInput) {
+  const validated = projectSchema.parse(data)
+  const project = await db.project.create({ data: validated })
+  revalidatePath('/projects')
+  return project
+}
+
+export async function updateProject(id: string, data: Partial<ProjectInput>) {
+  const validated = projectSchema.partial().parse(data)
+  const project = await db.project.update({ where: { id }, data: validated })
+  revalidatePath(`/projects/${id}`)
+  return project
+}
+```
+
+
+## Field Array (Dynamic Fields)
+
+```tsx
+import { useFieldArray, Controller } from 'react-hook-form'
+
+function TagFieldArray({ control }) {
+  const { fields, append, remove } = useFieldArray({ control, name: 'tags' })
+
+  return (
+    <div className="space-y-2">
+      {fields.map((field, index) => (
+        <div key={field.id} className="flex gap-2">
+          <Controller
+            name={`tags.${index}`}
+            control={control}
+            rules={{ required: 'Tag required' }}
+            render={({ field }) => (
+              <input {...field} className="flex-1 rounded-lg border px-3 py-2" placeholder="Tag" />
+            )}
+          />
+          <Button type="button" variant="ghost" size="icon" onClick={() => remove(index)}>
+            <X className="h-4 w-4" />
+          </Button>
+        </div>
+      ))}
+      <Button type="button" variant="outline" onClick={() => append('')}>Add Tag</Button>
+    </div>
+  )
+}
+```
+
+
+## When to Escalate
+
+| Need | Escalate To |
+|------|-------------|
+| Toast on submit | `ask-toast` + `ask-sonner` |
+| Modal form | `ask-modal` + `ask-base-ui` |
+| Complex validation | Zod refinements, `superRefine` |
+| Multi-step wizard | `ask-form` + state machine |