@numbered/docs-to-context 0.1.5 → 0.3.1

package/docs/liquid/schema-blocks-over-settings.mdx

@@ -0,0 +1,35 @@
+# Use Blocks for Repeatable Content
+
+Use section blocks instead of numbered settings for repeatable items.
+
+```json
+{% comment %} BAD: hardcoded number of items {% endcomment %}
+{% schema %}
+{
+  "settings": [
+    { "type": "text", "id": "slide_1_title" },
+    { "type": "image_picker", "id": "slide_1_image" },
+    { "type": "text", "id": "slide_2_title" },
+    { "type": "image_picker", "id": "slide_2_image" }
+  ]
+}
+{% endschema %}
+
+{% comment %} GOOD: dynamic, reorderable blocks {% endcomment %}
+{% schema %}
+{
+  "blocks": [
+    {
+      "type": "slide",
+      "name": "Slide",
+      "settings": [
+        { "type": "text", "id": "title" },
+        { "type": "image_picker", "id": "image" }
+      ]
+    }
+  ]
+}
+{% endschema %}
+```
+
+Blocks are reorderable, addable, and removable by editors.

package/docs/liquid/schema-section-settings.mdx

@@ -0,0 +1,36 @@
+# Keep Section Schema Lean
+
+Only expose settings that editors actually need. Large schemas slow the theme editor.
+
+```json
+{% comment %} BAD: excessive settings {% endcomment %}
+{% schema %}
+{
+  "settings": [
+    { "type": "text", "id": "title", "label": "Title" },
+    { "type": "text", "id": "title_tag", "label": "Title HTML tag" },
+    { "type": "text", "id": "title_class", "label": "Title CSS class" },
+    { "type": "text", "id": "title_style", "label": "Title inline style" }
+  ]
+}
+{% endschema %}
+
+{% comment %} GOOD: only what editors control {% endcomment %}
+{% schema %}
+{
+  "settings": [
+    { "type": "text", "id": "title", "label": "Title" },
+    {
+      "type": "select", "id": "title_size", "label": "Title size",
+      "options": [
+        { "value": "sm", "label": "Small" },
+        { "value": "lg", "label": "Large" }
+      ],
+      "default": "lg"
+    }
+  ]
+}
+{% endschema %}
+```
+
+Map setting values to Tailwind classes in the template, not in the schema.

package/docs/react/README.mdx

@@ -0,0 +1,99 @@
+# React & Next.js Best Practices
+
+Read this index first. Load only the files relevant to your current task.
+
+## 1. Eliminating Waterfalls — CRITICAL
+
+| File | Pattern |
+|---|---|
+| `async-defer-await.mdx` | Move await into branches where it's used |
+| `async-promise-all.mdx` | Promise.all for independent operations |
+| `async-start-early.mdx` | Start promises early, await late |
+| `async-suspense-boundaries.mdx` | Suspense to stream content progressively |
+
+## 2. Bundle Size — CRITICAL
+
+| File | Pattern |
+|---|---|
+| `bundle-barrel-imports.mdx` | Import from source, not barrel files |
+| `bundle-dynamic-imports.mdx` | next/dynamic for heavy components |
+| `bundle-defer-third-party.mdx` | Load analytics/logging after hydration |
+| `bundle-preload-intent.mdx` | Preload on hover/focus/feature-flag |
+| `bundle-conditional-loading.mdx` | Load modules only when feature activates |
+
+## 3. Server-Side Performance — HIGH
+
+| File | Pattern |
+|---|---|
+| `server-react-cache.mdx` | React.cache() for per-request dedup |
+| `server-lru-cache.mdx` | LRU cache for cross-request data |
+| `server-rsc-serialization.mdx` | Pass only used fields across RSC boundary |
+| `server-parallel-fetching.mdx` | Component composition for parallel fetches |
+
+## 4. Client-Side Data Fetching — MEDIUM-HIGH
+
+| File | Pattern |
+|---|---|
+| `client-swr-dedup.mdx` | SWR for request dedup and caching |
+| `client-event-listeners.mdx` | Deduplicate global event listeners |
+
+## 5. Re-render Optimization — MEDIUM
+
+| File | Pattern |
+|---|---|
+| `rerender-use-client-down.mdx` | Push "use client" to smallest leaf |
+| `rerender-isolate-state.mdx` | Isolate state to smallest component |
+| `rerender-inline-objects.mdx` | Avoid inline objects in JSX |
+| `rerender-narrow-deps.mdx` | Use primitives in effect dependencies |
+| `rerender-defer-reads.mdx` | Read dynamic state only in callbacks |
+| `rerender-lazy-init.mdx` | Lazy state initialization for expensive values |
+| `rerender-derived-state.mdx` | Subscribe to derived booleans, not raw values |
+| `rerender-memo-extract.mdx` | Extract to memoized components for early return |
+| `rerender-transitions.mdx` | startTransition for non-urgent updates |
+
+## 6. useEffect Rules — MEDIUM
+
+| File | Pattern |
+|---|---|
+| `effect-derive-state.mdx` | Calculate during render, not in effects |
+| `effect-use-memo.mdx` | useMemo for expensive calculations |
+| `effect-event-handlers.mdx` | Event logic in handlers, not effects |
+| `effect-key-reset.mdx` | Key prop to reset state, not effects |
+| `effect-no-chains.mdx` | Batch in event handlers, avoid chained effects |
+| `effect-notify-parents.mdx` | Notify parents via handlers, not effects |
+
+## 7. Rendering Performance — MEDIUM
+
+| File | Pattern |
+|---|---|
+| `render-svg-wrapper.mdx` | Animate wrapper div, not SVG element |
+| `render-content-visibility.mdx` | content-visibility for off-screen items |
+| `render-hoist-jsx.mdx` | Hoist static JSX outside components |
+| `render-hydration-flicker.mdx` | Inline script to prevent hydration flicker |
+| `render-conditional.mdx` | Ternary over && for falsy values |
+| `render-activity.mdx` | Activity component for show/hide |
+| `render-svg-precision.mdx` | SVGO to reduce SVG file size |
+| `render-cx-clsx.mdx` | Skip cx/clsx for single static classes |
+
+## 8. JavaScript Patterns — LOW-MEDIUM
+
+| File | Pattern |
+|---|---|
+| `js-index-maps.mdx` | Map for O(1) repeated lookups |
+| `js-set-lookups.mdx` | Set for O(1) membership checks |
+| `js-combine-iterations.mdx` | Single loop instead of multiple filter/map |
+| `js-tosorted.mdx` | toSorted() for immutable sorting |
+| `js-loop-min-max.mdx` | Loop for min/max instead of sort |
+| `js-length-check.mdx` | Check length before expensive comparison |
+| `js-batch-css.mdx` | CSS classes over inline style mutations |
+| `js-cache-property.mdx` | Cache deep property access in loops |
+| `js-cache-storage.mdx` | Cache localStorage/sessionStorage reads |
+| `js-early-return.mdx` | Return early to skip unnecessary work |
+| `js-hoist-regexp.mdx` | Hoist RegExp to module scope or useMemo |
+
+## 9. Advanced Patterns — LOW
+
+| File | Pattern |
+|---|---|
+| `advanced-handler-refs.mdx` | Store event handlers in refs |
+| `advanced-use-latest.mdx` | useLatest for stable callback refs |

package/docs/react/advanced-handler-refs.mdx

@@ -0,0 +1,15 @@
+# Store Event Handlers in Refs
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+```tsx
+function useWindowEvent(event: string, handler: () => void) {
+  const ref = useRef(handler)
+  useEffect(() => { ref.current = handler }, [handler])
+  useEffect(() => {
+    const listener = () => ref.current()
+    window.addEventListener(event, listener)
+    return () => window.removeEventListener(event, listener)
+  }, [event])
+}
+```

package/docs/react/advanced-use-latest.mdx

@@ -0,0 +1,21 @@
+# useLatest for Stable Callback Refs
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+```tsx
+function useLatest<T>(value: T) {
+  const ref = useRef(value)
+  useEffect(() => { ref.current = value }, [value])
+  return ref
+}
+
+// Usage: stable effect, fresh callback
+function SearchInput({ onSearch }) {
+  const [query, setQuery] = useState('')
+  const ref = useLatest(onSearch)
+  useEffect(() => {
+    const t = setTimeout(() => ref.current(query), 300)
+    return () => clearTimeout(t)
+  }, [query])
+}
+```

package/docs/react/async-defer-await.mdx

@@ -0,0 +1,19 @@
+# Defer Await Until Needed
+
+Move `await` into the branch where it's actually used.
+
+```tsx
+// BAD: blocks both branches
+async function handleRequest(userId: string, skip: boolean) {
+  const data = await fetchUserData(userId)
+  if (skip) return { skipped: true }
+  return processUserData(data)
+}
+
+// GOOD: only fetches when needed
+async function handleRequest(userId: string, skip: boolean) {
+  if (skip) return { skipped: true }
+  const data = await fetchUserData(userId)
+  return processUserData(data)
+}
+```

package/docs/react/async-promise-all.mdx

@@ -0,0 +1,17 @@
+# Promise.all for Independent Operations
+
+When async operations have no interdependencies, execute them concurrently.
+
+```tsx
+// BAD: sequential — 3 round trips
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+
+// GOOD: parallel — 1 round trip
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments(),
+])
+```

package/docs/react/async-start-early.mdx

@@ -0,0 +1,25 @@
+# Start Promises Early, Await Late
+
+Start independent operations immediately, even if you don't await them yet.
+
+```tsx
+// BAD: config waits for auth
+export async function GET(request: Request) {
+  const session = await auth()
+  const config = await fetchConfig()
+  const data = await fetchData(session.user.id)
+  return Response.json({ data, config })
+}
+
+// GOOD: auth and config start immediately
+export async function GET(request: Request) {
+  const sessionPromise = auth()
+  const configPromise = fetchConfig()
+  const session = await sessionPromise
+  const [config, data] = await Promise.all([
+    configPromise,
+    fetchData(session.user.id),
+  ])
+  return Response.json({ data, config })
+}
+```

package/docs/react/async-suspense-boundaries.mdx

@@ -0,0 +1,35 @@
+# Suspense Boundaries to Stream Content
+
+Use Suspense to show wrapper UI immediately while data loads.
+
+```tsx
+// BAD: entire page blocked by data
+async function Page() {
+  const data = await fetchData()
+  return (
+    <div>
+      <Header />
+      <DataDisplay data={data} />
+      <Footer />
+    </div>
+  )
+}
+
+// GOOD: shell renders immediately, data streams in
+function Page() {
+  return (
+    <div>
+      <Header />
+      <Suspense fallback={<Skeleton />}>
+        <DataDisplay />
+      </Suspense>
+      <Footer />
+    </div>
+  )
+}
+
+async function DataDisplay() {
+  const data = await fetchData()
+  return <div>{data.content}</div>
+}
+```

package/docs/react/bundle-barrel-imports.mdx

@@ -0,0 +1,25 @@
+# Avoid Barrel File Imports
+
+Import directly from source files instead of barrel files to avoid loading thousands of unused modules.
+
+```tsx
+// BAD: loads entire library (1,583 modules)
+import { Check, X, Menu } from 'lucide-react'
+
+// GOOD: loads only 3 modules
+import Check from 'lucide-react/dist/esm/icons/check'
+import X from 'lucide-react/dist/esm/icons/x'
+import Menu from 'lucide-react/dist/esm/icons/menu'
+```
+
+Or use `optimizePackageImports` in next.config to keep ergonomic imports:
+
+```js
+module.exports = {
+  experimental: {
+    optimizePackageImports: ['lucide-react', '@mui/material'],
+  },
+}
+```
+
+Commonly affected: `lucide-react`, `@mui/material`, `@tabler/icons-react`, `react-icons`, `@radix-ui/react-*`, `lodash`, `date-fns`.

package/docs/react/bundle-conditional-loading.mdx

@@ -0,0 +1,21 @@
+# Conditional Module Loading
+
+Load large data or modules only when a feature is activated.
+
+```tsx
+function AnimationPlayer({ enabled }: { enabled: boolean }) {
+  const [frames, setFrames] = useState<Frame[] | null>(null)
+
+  useEffect(() => {
+    if (enabled && !frames && typeof window !== 'undefined') {
+      import('./animation-frames.js')
+        .then(mod => setFrames(mod.frames))
+    }
+  }, [enabled, frames])
+
+  if (!frames) return <Skeleton />
+  return <Canvas frames={frames} />
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling for SSR.

package/docs/react/bundle-defer-third-party.mdx

@@ -0,0 +1,15 @@
+# Defer Non-Critical Third-Party Libraries
+
+Analytics, logging, and error tracking don't block user interaction. Load them after hydration.
+
+```tsx
+// BAD: blocks initial bundle
+import { Analytics } from '@vercel/analytics/react'
+
+// GOOD: loads after hydration
+import dynamic from 'next/dynamic'
+const Analytics = dynamic(
+  () => import('@vercel/analytics/react').then(m => m.Analytics),
+  { ssr: false }
+)
+```

package/docs/react/bundle-dynamic-imports.mdx

@@ -0,0 +1,15 @@
+# Dynamic Imports for Heavy Components
+
+Use `next/dynamic` to lazy-load large components not needed on initial render.
+
+```tsx
+// BAD: Monaco bundles with main chunk (~300KB)
+import { MonacoEditor } from './monaco-editor'
+
+// GOOD: loads on demand
+import dynamic from 'next/dynamic'
+const MonacoEditor = dynamic(
+  () => import('./monaco-editor').then(m => m.MonacoEditor),
+  { ssr: false }
+)
+```

package/docs/react/bundle-preload-intent.mdx

@@ -0,0 +1,24 @@
+# Preload Based on User Intent
+
+Preload heavy bundles before they're needed to reduce perceived latency.
+
+```tsx
+function EditorButton({ onClick }: { onClick: () => void }) {
+  const preload = () => { void import('./monaco-editor') }
+  return (
+    <button onMouseEnter={preload} onFocus={preload} onClick={onClick}>
+      Open Editor
+    </button>
+  )
+}
+```
+
+Also works with feature flags:
+
+```tsx
+useEffect(() => {
+  if (flags.editorEnabled) {
+    void import('./monaco-editor').then(mod => mod.init())
+  }
+}, [flags.editorEnabled])
+```

package/docs/react/client-event-listeners.mdx

@@ -0,0 +1,45 @@
+# Deduplicate Global Event Listeners
+
+N component instances should share 1 listener, not register N listeners.
+
+```tsx
+// BAD: N instances = N listeners
+function useKeyboardShortcut(key: string, callback: () => void) {
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && e.key === key) callback()
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  }, [key, callback])
+}
+
+// GOOD: N instances = 1 listener via useSWRSubscription
+import useSWRSubscription from 'swr/subscription'
+
+const keyCallbacks = new Map<string, Set<() => void>>()
+
+function useKeyboardShortcut(key: string, callback: () => void) {
+  useEffect(() => {
+    if (!keyCallbacks.has(key)) keyCallbacks.set(key, new Set())
+    keyCallbacks.get(key)!.add(callback)
+    return () => {
+      const set = keyCallbacks.get(key)
+      if (set) {
+        set.delete(callback)
+        if (set.size === 0) keyCallbacks.delete(key)
+      }
+    }
+  }, [key, callback])
+
+  useSWRSubscription('global-keydown', () => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && keyCallbacks.has(e.key)) {
+        keyCallbacks.get(e.key)!.forEach(cb => cb())
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  })
+}
+```

package/docs/react/client-swr-dedup.mdx

@@ -0,0 +1,40 @@
+# SWR for Automatic Request Deduplication
+
+SWR enables request deduplication, caching, and revalidation across component instances.
+
+```tsx
+// BAD: no deduplication, each instance fetches
+function UserList() {
+  const [users, setUsers] = useState([])
+  useEffect(() => {
+    fetch('/api/users').then(r => r.json()).then(setUsers)
+  }, [])
+}
+
+// GOOD: multiple instances share one request
+import useSWR from 'swr'
+
+function UserList() {
+  const { data: users } = useSWR('/api/users', fetcher)
+}
+```
+
+For immutable data:
+
+```tsx
+const { data } = useSWR('/api/config', fetcher, {
+  revalidateOnFocus: false,
+  revalidateOnReconnect: false,
+})
+```
+
+For mutations:
+
+```tsx
+import useSWRMutation from 'swr/mutation'
+
+function UpdateButton() {
+  const { trigger } = useSWRMutation('/api/user', updateUser)
+  return <button onClick={() => trigger()}>Update</button>
+}
+```

package/docs/react/effect-derive-state.mdx

@@ -0,0 +1,12 @@
+# Derive State During Render
+
+Don't use effects for derived state. Calculate during render instead.
+
+```tsx
+// BAD: redundant state + unnecessary effect
+const [fullName, setFullName] = useState('')
+useEffect(() => { setFullName(first + ' ' + last) }, [first, last])
+
+// GOOD: calculate during render
+const fullName = first + ' ' + last
+```

package/docs/react/effect-event-handlers.mdx

@@ -0,0 +1,16 @@
+# Handle Events in Handlers, Not Effects
+
+Event logic belongs in event handlers, not effects.
+
+```tsx
+// BAD: event logic in effect
+useEffect(() => {
+  if (product.isInCart) showNotification(`Added ${product.name}!`)
+}, [product])
+
+// GOOD: event logic in handler
+function handleBuy() {
+  addToCart(product)
+  showNotification(`Added ${product.name}!`)
+}
+```

package/docs/react/effect-key-reset.mdx

@@ -0,0 +1,11 @@
+# Reset State with Key Prop
+
+Don't use effects to reset state on prop change. Use the `key` prop.
+
+```tsx
+// BAD: effect to reset state
+useEffect(() => { setComment('') }, [userId])
+
+// GOOD: key prop resets component state
+<Profile userId={userId} key={userId} />
+```

package/docs/react/effect-no-chains.mdx

@@ -0,0 +1,22 @@
+# Avoid Chained Effects
+
+Cascading effects cause multiple re-renders. Batch updates in event handlers instead.
+
+```tsx
+// BAD: cascading effects
+useEffect(() => {
+  if (card?.gold) setGoldCardCount(c => c + 1)
+}, [card])
+useEffect(() => {
+  if (goldCardCount > 3) { setRound(r => r + 1); setGoldCardCount(0) }
+}, [goldCardCount])
+
+// GOOD: batch in event handler
+function handlePlaceCard(nextCard) {
+  setCard(nextCard)
+  if (nextCard.gold) {
+    if (goldCardCount < 3) setGoldCardCount(goldCardCount + 1)
+    else { setGoldCardCount(0); setRound(round + 1) }
+  }
+}
+```

package/docs/react/effect-notify-parents.mdx

@@ -0,0 +1,18 @@
+# Notify Parents via Handlers, Not Effects
+
+```tsx
+// BAD: effect to notify parent
+useEffect(() => { onChange(isOn) }, [isOn, onChange])
+
+// GOOD: update together in handler
+function handleClick() {
+  const next = !isOn
+  setIsOn(next)
+  onChange(next)
+}
+
+// BEST: lift state to parent (controlled component)
+function Toggle({ isOn, onChange }) {
+  return <button onClick={() => onChange(!isOn)}>{isOn ? 'ON' : 'OFF'}</button>
+}
+```

package/docs/react/effect-use-memo.mdx

@@ -0,0 +1,17 @@
+# useMemo for Expensive Calculations
+
+Don't use effects for derived data. Use useMemo.
+
+```tsx
+// BAD: effect for derived data
+const [visibleTodos, setVisibleTodos] = useState([])
+useEffect(() => {
+  setVisibleTodos(getFilteredTodos(todos, filter))
+}, [todos, filter])
+
+// GOOD: useMemo
+const visibleTodos = useMemo(
+  () => getFilteredTodos(todos, filter),
+  [todos, filter]
+)
+```

package/docs/react/js-batch-css.mdx

@@ -0,0 +1,23 @@
+# Batch DOM CSS Changes via Classes
+
+Avoid changing styles one property at a time. Group via classes to minimize browser reflows.
+
+```tsx
+// BAD: multiple reflows
+el.style.width = '100px'
+el.style.height = '200px'
+el.style.backgroundColor = 'blue'
+
+// GOOD: single reflow
+el.classList.add('highlighted-box')
+```
+
+In React: prefer `className` over inline `style` mutations.
+
+```tsx
+// BAD
+<div ref={ref} /> + ref.current.style.width = '100px'
+
+// GOOD
+<div className={isHighlighted ? 'highlighted-box' : ''} />
+```

package/docs/react/js-cache-property.mdx

@@ -0,0 +1,17 @@
+# Cache Property Access in Loops
+
+Cache object property lookups in hot paths.
+
+```tsx
+// BAD: 3 lookups x N iterations
+for (let i = 0; i < arr.length; i++) {
+  process(obj.config.settings.value)
+}
+
+// GOOD: 1 lookup total
+const value = obj.config.settings.value
+const len = arr.length
+for (let i = 0; i < len; i++) {
+  process(value)
+}
+```