@nerdev/skillset 0.2.1

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

@@ -0,0 +1,291 @@
+---
+name: ask-vaul
+description: Library guide for Vaul: accessible drawer/sheet component with gestures, snap points, spring physics. Load via ask-drawer pattern skill.
+---
+
+# Ask Vaul: Mobile Drawers & Sheets
+
+**When to use:** Bottom sheets, side drawers, mobile navigation, filter panels, any gesture-driven overlay.
+
+**Package:** `vaul`
+
+
+## Installation
+
+```bash
+npm i vaul
+```
+
+
+## Core Components
+
+```tsx
+import {
+  Drawer,
+  DrawerTrigger,
+  DrawerContent,
+  DrawerHeader,
+  DrawerTitle,
+  DrawerDescription,
+  DrawerClose,
+  DrawerOverlay,
+} from 'vaul'
+```
+
+
+## Basic Bottom Sheet
+
+```tsx
+import { Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription, DrawerClose } from 'vaul'
+
+function BottomSheet() {
+  return (
+    <Drawer direction="bottom" snapPoints={[0.5, 0.9, 1]}>
+      <DrawerTrigger asChild>
+        <Button variant="outline">Open Sheet</Button>
+      </DrawerTrigger>
+      <DrawerContent className="rounded-t-2xl">
+        <DrawerHeader>
+          <DrawerTitle>Sheet Title</DrawerTitle>
+          <DrawerDescription>Optional description</DrawerDescription>
+        </DrawerHeader>
+        <div className="p-4 space-y-4">
+          {/* Content */}
+        </div>
+      </DrawerContent>
+    </Drawer>
+  )
+}
+```
+
+
+## Side Drawer (Navigation)
+
+```tsx
+function SideDrawer() {
+  return (
+    <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="flex items-center justify-between p-4 border-b">
+          <DrawerTitle>Menu</DrawerTitle>
+          <DrawerClose asChild>
+            <Button variant="ghost" size="icon" className="md:hidden"><X className="h-5 w-5" /></Button>
+          </DrawerClose>
+        </DrawerHeader>
+        <nav className="p-4 space-y-1">
+          <Link href="/" className="flex items-center gap-3 px-3 py-2 rounded-lg hover:bg-gray-100">
+            <Home className="h-5 w-5" /> Dashboard
+          </Link>
+          <Link href="/projects" className="flex items-center gap-3 px-3 py-2 rounded-lg hover:bg-gray-100">
+            <Folder className="h-5 w-5" /> Projects
+          </Link>
+        </nav>
+      </DrawerContent>
+    </Drawer>
+  )
+}
+```
+
+
+## Snap Points Configuration
+
+| Snap Points | Behavior |
+|-------------|----------|
+| `[0.5, 1]` | Half → Full |
+| `[0.3, 0.6, 1]` | Three tiers |
+| `[1]` | Full only (side drawers) |
+| `[0.4, 0.85]` | Custom percentages |
+
+```tsx
+// Half sheet for quick actions
+<Drawer direction="bottom" snapPoints={[0.4]}>
+
+// Full height for forms
+<Drawer direction="bottom" snapPoints={[1]}>
+
+// Multi-tier for filters
+<Drawer direction="bottom" snapPoints={[0.3, 0.6, 1]}>
+```
+
+
+## Custom Handle / Trigger
+
+```tsx
+function FilterDrawer() {
+  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
+          {hasActiveFilters && <Badge variant="secondary">{count}</Badge>}
+        </Button>
+      </DrawerTrigger>
+      <DrawerContent className="rounded-t-2xl">
+        {/* Custom handle area */}
+        <div className="flex items-center justify-between px-4 py-3 border-b">
+          <DrawerTitle>Filters</DrawerTitle>
+          <Button variant="ghost" size="icon" onClick={resetFilters} disabled={!hasActiveFilters}>
+            <RotateCcw className="h-4 w-4" />
+          </Button>
+        </div>
+        <div className="p-4 space-y-6 max-h-[70vh] overflow-y-auto">
+          {/* Filter sections */}
+        </div>
+        <div className="flex gap-2 p-4 border-t">
+          <Button variant="outline" className="flex-1" onClick={resetFilters}>Reset</Button>
+          <Button className="flex-1" onClick={applyFilters}>Apply ({activeCount})</Button>
+        </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>
+  )
+}
+```
+
+
+## Form in Drawer
+
+```tsx
+function CreateProjectDrawer({ onSuccess }) {
+  const form = useForm<ProjectInput>({ resolver: zodResolver(projectSchema) })
+
+  return (
+    <Drawer direction="bottom" snapPoints={[0.9, 1]}>
+      <DrawerTrigger asChild>
+        <Button><Plus className="h-4 w-4 mr-2" />New Project</Button>
+      </DrawerTrigger>
+      <DrawerContent className="rounded-t-2xl">
+        <DrawerHeader>
+          <DrawerTitle>New Project</DrawerTitle>
+        </DrawerHeader>
+        <Form {...form}>
+          <form onSubmit={form.handleSubmit(onSubmit)} className="p-4 space-y-4 max-h-[75vh] overflow-y-auto">
+            <FormField name="name" label="Name" />
+            <FormField name="description" label="Description" type="textarea" />
+            <FormField name="visibility" label="Visibility" type="select" selectOptions={[
+              { value: 'private', label: 'Private' },
+              { value: 'team', label: 'Team' },
+              { value: 'public', label: 'Public' },
+            ]} />
+            <div className="flex gap-2 pt-4 border-t">
+              <Button type="button" variant="outline" className="flex-1" onClick={onClose}>Cancel</Button>
+              <Button type="submit" className="flex-1" disabled={form.formState.isSubmitting}>
+                {form.formState.isSubmitting ? 'Creating…' : 'Create'}
+              </Button>
+            </div>
+          </form>
+        </Form>
+      </DrawerContent>
+    </Drawer>
+  )
+}
+```
+
+
+## Drawer Props Reference
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `direction` | `'bottom' \| 'top' \| 'left' \| 'right'` | `'bottom'` | Drawer direction |
+| `snapPoints` | `number[]` | `[1]` | Array of 0-1 percentages |
+| `open` | `boolean` | - | Controlled open |
+| `onOpenChange` | `(open: boolean) => void` | - | Open change handler |
+| `dismissible` | `boolean` | `true` | Allow swipe/backdrop dismiss |
+| `snapTo` | `number` | - | Programmatic snap |
+| `overscroll` | `boolean` | `false` | Allow overscroll past snap |
+
+
+## Motion Integration (House-Style)
+
+Vaul uses spring physics internally. For custom animations:
+
+```tsx
+import { motion, AnimatePresence } from 'motion/react'
+
+// Vaul handles the drawer animation
+// Wrap content for custom enter/exit if needed
+<DrawerContent className="rounded-t-2xl">
+  <AnimatePresence mode="wait">
+    {isOpen && <DrawerContentInner />}
+  </AnimatePresence>
+</DrawerContent>
+```
+
+
+## Accessibility (Built-in)
+
+- Focus trap inside drawer
+- ESC to close
+- Backdrop click to close (configurable)
+- Focus restore to trigger on close
+- ARIA attributes on all elements
+- Keyboard navigation (Tab, arrows)
+
+
+## Common Issues
+
+| Issue | Fix |
+|-------|-----|
+| Drawer not opening | Check `DrawerTrigger` wraps a button, not a div |
+| Snap points not working | Ensure values are 0-1, array not empty |
+| Scroll not working | Content must be in `DrawerContent`, not `Drawer` |
+| Z-index issues | Vaul portals to body: check global stacking |
+| Mobile keyboard covers input | Vaul handles this: ensure `snapPoints` includes full height |
+| Gesture conflicts | Set `overscroll={true}` if nested scrollable content |
+
+
+## Related Skills
+
+- `ui/ask-drawer` - Pattern guide for drawers/sheets
+- `ui/ask-base-ui` - Alternative: base-ui Sheet primitive
+- `ui/ask-form` - Forms in drawers
+- `ui/ui-engineering` - Master orchestrator

package/skills/ui/ask-virtual-list/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: ask-virtual-list
+description: Pattern guide for virtualized lists: infinite scroll, variable heights, dynamic content, smooth scrolling. Load via ui-engineering. Invokes pick-ui-library → recommends Virtuoso → loads ask-virtuoso for implementation.
+---
+
+# Ask Virtual List: Infinite Scroll, Variable Heights, Smooth Performance
+
+**When to use:** Long lists: feeds, chat, logs, activity, notifications, search results, any list >100 items.
+
+
+## The Pattern
+
+| Feature | Quality Bar |
+|---------|-------------|
+| **Smooth 60fps** | No jank at 10k+ items, variable heights |
+| **Infinite scroll** | Load more at threshold, skeleton placeholders |
+| **Variable heights** | Dynamic measurement, cache heights, no layout shift |
+| **Scroll restoration** | Restore position on back navigation |
+| **Jump to top/bottom** | Button appears after scroll, smooth scroll |
+| **Pull to refresh** | Mobile: drag down to refresh |
+| **Sticky headers** | Section headers stick during scroll |
+| **End detection** | "No more items" state, not just spinner |
+| **Keyboard** | Home/End, Page Up/Down, arrow keys |
+| **Accessibility** | ARIA feed/listbox, live region for new items |
+
+
+## Quality Checklist
+
+- [ ] **Virtuoso**: Handles variable heights, grouping, infinite scroll out of box
+- [ ] **Overscan**: Render 5-10 items above/below viewport
+- [ ] **Height caching**: Measure once, cache, invalidate on content change
+- [ ] **Skeleton loading**: Same height as real items, shimmer animation
+- [ ] **Intersection Observer**: For load-more trigger (not scroll listener)
+- [ ] **Scroll restoration**: `history.scrollRestoration = 'manual'` + save/restore
+- [ ] **No layout shift**: Reserve space for async images/avatars
+- [ ] **Memory**: Unmount far items, don't accumulate DOM nodes
+
+
+## Anti-Patterns
+
+- ❌ `react-window` fixed height only: Breaks with variable content
+- ❌ No overscan: Flashing blank space on fast scroll
+- ❌ Scroll listener for load-more: Jank, fires too often
+- ❌ No skeleton: Content pops in, layout shift
+- ❌ No scroll restoration: Back button loses position
+- ❌ All items in DOM: 10k items = frozen tab
+- ❌ No sticky headers: Sections lose context
+- ❌ Images without dimensions: Layout shift on load
+
+
+## Implementation Flow
+
+```
+User needs virtual list/infinite scroll
+    │
+    ├─► ui-engineering detects "list/feed/infinite scroll/chat/logs"
+    │
+    ├─► pick-ui-library → recommends Virtuoso
+    │
+    ├─► load ask-virtuoso (library skill)
+    │
+    └─► implement with Virtuoso + infinite scroll + skeletons
+```
+
+
+## Core Setup (Virtuoso)
+
+```tsx
+// components/VirtualList.tsx
+import { Virtuoso } from 'react-virtuoso'
+import { useInView } from 'react-intersection-observer'
+
+interface VirtualListProps<T> {
+  data: T[]
+  renderItem: (item: T, index: number) => React.ReactNode
+  renderSkeleton?: () => React.ReactNode
+  loadMore?: () => Promise<void>
+  hasMore?: boolean
+  isLoading?: boolean
+  endMessage?: string
+  overscan?: number
+  stickyHeader?: React.ReactNode
+  groupBy?: (item: T) => string
+  groupContent?: (key: string) => React.ReactNode
+}
+
+export function VirtualList<T>({
+  data,
+  renderItem,
+  renderSkeleton = DefaultSkeleton,
+  loadMore,
+  hasMore = false,
+  isLoading = false,
+  endMessage = 'No more items',
+  overscan = 100,
+  stickyHeader,
+  groupBy,
+  groupContent,
+}: VirtualListProps<T>) {
+  const { ref: loadMoreRef, inView } = useInView({ threshold: 0.1 })
+
+  useEffect(() => {
+    if (inView && hasMore && !isLoading && loadMore) {
+      loadMore()
+    }
+  }, [inView, hasMore, isLoading, loadMore])
+
+  return (
+    <Virtuoso
+      data={data}
+      overscan={overscan}
+      itemContent={(index, item) => renderItem(item, index)}
+      endContent={
+        hasMore ? (
+          <div className="flex justify-center py-4" ref={loadMoreRef}>
+            {isLoading ? <Spinner className="h-6 w-6" /> : <EndDetector />}
+          </div>
+        ) : (
+          <div className="flex justify-center py-4 text-gray-500">{endMessage}</div>
+        )
+      }
+      header={stickyHeader}
+      groupCounts={groupBy ? data.reduce((acc, item) => {
+        const key = groupBy(item)
+        acc[key] = (acc[key] || 0) + 1
+        return acc
+      }, {} as Record<string, number>) : undefined}
+      groupContent={groupContent}
+      style={{ height: '100%', width: '100%' }}
+      listRef={(el) => { /* scroll restoration */ }}
+    />
+  )
+}
+
+function DefaultSkeleton() {
+  return (
+    <div className="h-16 animate-pulse bg-gray-200 dark:bg-gray-700 rounded" />
+  )
+}
+
+function EndDetector() {
+  return null // Just for intersection observer
+}
+```
+
+
+## Feed Example (Linear/Twitter-style)
+
+```tsx
+// components/ActivityFeed.tsx
+'use client'
+
+import { useState, useCallback } from 'react'
+import { VirtualList } from '@/components/VirtualList'
+import { ActivityItem } from '@/components/ActivityItem'
+import { api } from '@/lib/api'
+
+export function ActivityFeed() {
+  const [activities, setActivities] = useState<Activity[]>([])
+  const [page, setPage] = useState(1)
+  const [hasMore, setHasMore] = useState(true)
+  const [isLoading, setIsLoading] = useState(false)
+
+  const loadMore = useCallback(async () => {
+    if (isLoading || !hasMore) return
+    setIsLoading(true)
+    try {
+      const { data, hasMore: more } = await api.getActivities({ page: page + 1 })
+      setActivities(prev => [...prev, ...data])
+      setPage(p => p + 1)
+      setHasMore(more)
+    } finally {
+      setIsLoading(false)
+    }
+  }, [page, hasMore, isLoading])
+
+  // Initial load
+  useEffect(() => {
+    loadMore()
+  }, [])
+
+  return (
+    <VirtualList
+      data={activities}
+      renderItem={(activity) => <ActivityItem activity={activity} />}
+      renderSkeleton={() => <ActivitySkeleton />}
+      loadMore={loadMore}
+      hasMore={hasMore}
+      isLoading={isLoading}
+      endMessage="All caught up!"
+      overscan={50}
+    />
+  )
+}
+```
+
+
+## Chat/Message List (Variable Heights)
+
+```tsx
+// components/ChatList.tsx
+import { Virtuoso } from 'react-virtuoso'
+import { useRef, useEffect } from 'react'
+
+export function ChatList({ messages, onScrollToBottom }) {
+  const virtuosoRef = useRef<VirtuosoHandle>(null)
+  const [scrolledToBottom, setScrolledToBottom] = useState(true)
+
+  const handleScroll = useCallback((top: number) => {
+    const { scrollHeight, clientHeight, scrollTop } = virtuosoRef.current?.getScrollElement() || {}
+    setScrolledToBottom(scrollHeight - scrollTop - clientHeight < 100)
+  }, [])
+
+  // Auto-scroll on new message if at bottom
+  useEffect(() => {
+    if (scrolledToBottom && messages.length > 0) {
+      virtuosoRef.current?.scrollToIndex({ index: messages.length - 1, align: 'end' })
+    }
+  }, [messages, scrolledToBottom])
+
+  return (
+    <Virtuoso
+      ref={virtuosoRef}
+      data={messages}
+      itemContent={(index, message) => <MessageBubble message={message} />}
+      overscan={20}
+      style={{ height: '100%', width: '100%' }}
+      onScroll={handleScroll}
+      endContent={
+        !scrolledToBottom && (
+          <button
+            className="fixed bottom-4 right-4 z-10 px-3 py-1 rounded-full bg-primary text-primary-foreground shadow-lg"
+            onClick={() => virtuosoRef.current?.scrollToIndex({ index: messages.length - 1, align: 'end' })}
+          >
+            ↓ New messages
+          </button>
+        )
+      }
+    />
+  )
+}
+```
+
+
+## Skeletons (Match Real Item Height)
+
+```tsx
+// components/ActivitySkeleton.tsx
+export function ActivitySkeleton() {
+  return (
+    <div className="p-4 border-b dark:border-gray-800">
+      <div className="flex gap-3">
+        <div className="h-10 w-10 rounded-full animate-pulse bg-gray-200 dark:bg-gray-700" />
+        <div className="flex-1 space-y-2">
+          <div className="h-4 w-3/4 animate-pulse bg-gray-200 dark:bg-gray-700 rounded" />
+          <div className="h-3 w-1/2 animate-pulse bg-gray-200 dark:bg-gray-700 rounded" />
+        </div>
+      </div>
+    </div>
+  )
+}
+```
+
+
+## Scroll Restoration (Back Button)
+
+```tsx
+// hooks/useScrollRestoration.ts
+'use client'
+
+import { useEffect, useRef } from 'react'
+
+export function useScrollRestoration(key: string) {
+  const saved = useRef<number | null>(null)
+
+  useEffect(() => {
+    // Save on unmount
+    return () => {
+      const el = document.querySelector('[data-virtuoso-scroller]')
+      if (el) saved.current = el.scrollTop
+      sessionStorage.setItem(`scroll:${key}`, String(saved.current ?? 0))
+    }
+  }, [key])
+
+  useEffect(() => {
+    // Restore on mount
+    const stored = sessionStorage.getItem(`scroll:${key}`)
+    if (stored) {
+      const el = document.querySelector('[data-virtuoso-scroller]')
+      if (el) el.scrollTop = Number(stored)
+    }
+  }, [key])
+}
+```
+
+
+## When to Escalate
+
+| Need | Escalate To |
+|------|-------------|
+| Table with columns | `ask-table` + `ask-tanstack-table` |
+| Sticky section headers | `ask-virtual-list` built-in groups |
+| Drag to reorder | `ask-animation` + `dnd-kit` |
+| Real-time prepend | `ask-virtual-list` + WebSocket |