@numbered/docs-to-context 0.1.5 → 0.3.0

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

@@ -0,0 +1,29 @@
+# Cache Storage API Calls
+
+`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
+
+```tsx
+const storageCache = new Map<string, string | null>()
+
+function getLocalStorage(key: string) {
+  if (!storageCache.has(key)) {
+    storageCache.set(key, localStorage.getItem(key))
+  }
+  return storageCache.get(key)
+}
+
+function setLocalStorage(key: string, value: string) {
+  localStorage.setItem(key, value)
+  storageCache.set(key, value) // keep cache in sync
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just components.
+
+Invalidate on external changes:
+
+```tsx
+window.addEventListener('storage', (e) => {
+  if (e.key) storageCache.delete(e.key)
+})
+```

package/docs/react/js-combine-iterations.mdx

@@ -0,0 +1,20 @@
+# Combine Multiple Array Iterations
+
+Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
+
+```tsx
+// BAD: 3 iterations
+const admins = users.filter(u => u.isAdmin)
+const testers = users.filter(u => u.isTester)
+const inactive = users.filter(u => !u.isActive)
+
+// GOOD: 1 iteration
+const admins: User[] = []
+const testers: User[] = []
+const inactive: User[] = []
+for (const u of users) {
+  if (u.isAdmin) admins.push(u)
+  if (u.isTester) testers.push(u)
+  if (!u.isActive) inactive.push(u)
+}
+```

package/docs/react/js-early-return.mdx

@@ -0,0 +1,24 @@
+# Early Return from Functions
+
+Return early when result is determined to skip unnecessary processing.
+
+```tsx
+// BAD: processes all items even after finding error
+function validateUsers(users: User[]) {
+  let hasError = false
+  for (const user of users) {
+    if (!user.email) { hasError = true }
+    if (!user.name) { hasError = true }
+  }
+  return hasError ? { valid: false } : { valid: true }
+}
+
+// GOOD: returns immediately on first error
+function validateUsers(users: User[]) {
+  for (const user of users) {
+    if (!user.email) return { valid: false, error: 'Email required' }
+    if (!user.name) return { valid: false, error: 'Name required' }
+  }
+  return { valid: true }
+}
+```

package/docs/react/js-hoist-regexp.mdx

@@ -0,0 +1,21 @@
+# Hoist RegExp Outside Render
+
+Don't create RegExp inside render. Hoist to module scope or memoize.
+
+```tsx
+// BAD: new RegExp every render
+function Highlighter({ text, query }) {
+  const regex = new RegExp(`(${query})`, 'gi')
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+
+// GOOD: memoize when query is dynamic
+function Highlighter({ text, query }) {
+  const regex = useMemo(() => new RegExp(`(${query})`, 'gi'), [query])
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+For static patterns, hoist to module scope. Note: global regexps (`/g`) have `lastIndex` state — reset before reuse or use a new instance.

package/docs/react/js-index-maps.mdx

@@ -0,0 +1,14 @@
+# Build Index Maps for Repeated Lookups
+
+Multiple `.find()` calls by the same key should use a Map.
+
+```tsx
+// BAD: O(n) per lookup
+orders.map(o => ({ ...o, user: users.find(u => u.id === o.userId) }))
+
+// GOOD: O(1) per lookup
+const userById = new Map(users.map(u => [u.id, u]))
+orders.map(o => ({ ...o, user: userById.get(o.userId) }))
+```
+
+Build map once (O(n)), then all lookups are O(1). For 1000 orders x 1000 users: 1M ops → 2K ops.

package/docs/react/js-length-check.mdx

@@ -0,0 +1,12 @@
+# Early Length Check Before Array Comparison
+
+If lengths differ, arrays cannot be equal. Check length first to skip expensive comparisons.
+
+```tsx
+function hasChanges(current: string[], original: string[]) {
+  if (current.length !== original.length) return true
+  const a = current.toSorted()
+  const b = original.toSorted()
+  return a.some((v, i) => v !== b[i])
+}
+```

package/docs/react/js-loop-min-max.mdx

@@ -0,0 +1,14 @@
+# Loop for Min/Max Instead of Sort
+
+Finding min/max only requires a single pass. Sorting is O(n log n) overkill.
+
+```tsx
+// BAD: O(n log n)
+const latest = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)[0]
+
+// GOOD: O(n)
+let latest = projects[0]
+for (let i = 1; i < projects.length; i++) {
+  if (projects[i].updatedAt > latest.updatedAt) latest = projects[i]
+}
+```

package/docs/react/js-set-lookups.mdx

@@ -0,0 +1,12 @@
+# Use Set/Map for O(1) Lookups
+
+Convert arrays to Set/Map for repeated membership checks.
+
+```tsx
+// BAD: O(n) per check
+items.filter(item => allowedIds.includes(item.id))
+
+// GOOD: O(1) per check
+const allowed = new Set(allowedIds)
+items.filter(item => allowed.has(item.id))
+```

package/docs/react/js-tosorted.mdx

@@ -0,0 +1,15 @@
+# Use toSorted() Instead of sort()
+
+`.sort()` mutates the array in place — breaks React state and props. Use `.toSorted()` for immutability.
+
+```tsx
+// BAD: mutates users prop
+const sorted = users.sort((a, b) => a.name.localeCompare(b.name))
+
+// GOOD: creates new array
+const sorted = users.toSorted((a, b) => a.name.localeCompare(b.name))
+```
+
+Also prefer: `.toReversed()`, `.toSpliced()`, `.with()` over their mutating counterparts.
+
+Fallback for older browsers: `[...items].sort(...)`.

package/docs/react/render-activity.mdx

@@ -0,0 +1,17 @@
+# Activity Component for Show/Hide
+
+Use React's `<Activity>` to preserve state/DOM for expensive components that frequently toggle visibility.
+
+```tsx
+import { Activity } from 'react'
+
+function Dropdown({ isOpen }: Props) {
+  return (
+    <Activity mode={isOpen ? 'visible' : 'hidden'}>
+      <ExpensiveMenu />
+    </Activity>
+  )
+}
+```
+
+Avoids expensive re-mount and state loss.

package/docs/react/render-conditional.mdx

@@ -0,0 +1,11 @@
+# Use Explicit Conditional Rendering
+
+Use ternary (`? :`) instead of `&&` when the condition can be `0`, `NaN`, or other falsy values that render.
+
+```tsx
+// BAD: renders "0" when count is 0
+{count && <span className="badge">{count}</span>}
+
+// GOOD: renders nothing when count is 0
+{count > 0 ? <span className="badge">{count}</span> : null}
+```

package/docs/react/render-content-visibility.mdx

@@ -0,0 +1,12 @@
+# CSS content-visibility for Long Lists
+
+Apply `content-visibility: auto` to defer off-screen rendering.
+
+```css
+.message-item {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 80px;
+}
+```
+
+For 1000 messages, browser skips layout/paint for ~990 off-screen items (10x faster initial render).

package/docs/react/render-cx-clsx.mdx

@@ -0,0 +1,12 @@
+# Avoid Unnecessary cx/clsx Wrappers
+
+```tsx
+// BAD: cx with single static class
+<div className={cx("container")} />
+
+// GOOD: plain string
+<div className="container" />
+
+// OK: cx useful for conditionals
+<div className={cx("container", isActive && "active")} />
+```

package/docs/react/render-hoist-jsx.mdx

@@ -0,0 +1,16 @@
+# Hoist Static JSX Elements
+
+Extract static JSX outside components to avoid re-creation. Especially helpful for large SVG nodes.
+
+```tsx
+// BAD: recreates element every render
+function Container() {
+  return <div>{loading && <div className="animate-pulse h-20 bg-gray-200" />}</div>
+}
+
+// GOOD: reuses same element
+const skeleton = <div className="animate-pulse h-20 bg-gray-200" />
+function Container() {
+  return <div>{loading && skeleton}</div>
+}
+```

package/docs/react/render-hydration-flicker.mdx

@@ -0,0 +1,25 @@
+# Prevent Hydration Mismatch Without Flickering
+
+For client-only values (theme, preferences), use an inline script that runs before React hydrates.
+
+```tsx
+function ThemeWrapper({ children }) {
+  return (
+    <>
+      <div id="theme-wrapper">{children}</div>
+      <script dangerouslySetInnerHTML={{ __html: `
+        (function() {
+          try {
+            var t = localStorage.getItem('theme') || 'light';
+            document.getElementById('theme-wrapper').className = t;
+          } catch(e) {}
+        })();
+      `}} />
+    </>
+  )
+}
+```
+
+The inline script executes synchronously before showing the element. No flickering, no hydration mismatch.
+
+Useful for: theme toggles, user preferences, authentication states, any client-only data that should render immediately.

package/docs/react/render-svg-precision.mdx

@@ -0,0 +1,17 @@
+# Optimize SVG Precision
+
+Reduce SVG coordinate precision to decrease file size.
+
+```svg
+<!-- BAD: excessive precision -->
+<path d="M 10.293847 20.847362 L 30.938472 40.192837" />
+
+<!-- GOOD: 1 decimal place -->
+<path d="M 10.3 20.8 L 30.9 40.2" />
+```
+
+Automate with SVGO:
+
+```bash
+npx svgo --precision=1 --multipass icon.svg
+```

package/docs/react/render-svg-wrapper.mdx

@@ -0,0 +1,19 @@
+# Animate SVG Wrapper, Not SVG Element
+
+Many browsers don't hardware-accelerate CSS animations on SVG elements. Wrap in a `<div>`.
+
+```tsx
+// BAD: no hardware acceleration
+<svg className="animate-spin" width="24" height="24" viewBox="0 0 24 24">
+  <circle cx="12" cy="12" r="10" stroke="currentColor" />
+</svg>
+
+// GOOD: GPU-accelerated
+<div className="animate-spin">
+  <svg width="24" height="24" viewBox="0 0 24 24">
+    <circle cx="12" cy="12" r="10" stroke="currentColor" />
+  </svg>
+</div>
+```
+
+Applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`).

package/docs/react/rerender-defer-reads.mdx

@@ -0,0 +1,24 @@
+# Defer State Reads to Usage Point
+
+Don't subscribe to dynamic state if you only read it inside callbacks.
+
+```tsx
+// BAD: subscribes to all searchParams changes
+function ShareButton({ chatId }: { chatId: string }) {
+  const searchParams = useSearchParams()
+  const handleShare = () => {
+    const ref = searchParams.get('ref')
+    shareChat(chatId, { ref })
+  }
+  return <button onClick={handleShare}>Share</button>
+}
+
+// GOOD: reads on demand, no subscription
+function ShareButton({ chatId }: { chatId: string }) {
+  const handleShare = () => {
+    const ref = new URLSearchParams(window.location.search).get('ref')
+    shareChat(chatId, { ref })
+  }
+  return <button onClick={handleShare}>Share</button>
+}
+```

package/docs/react/rerender-derived-state.mdx

@@ -0,0 +1,18 @@
+# Subscribe to Derived State
+
+Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.
+
+```tsx
+// BAD: re-renders on every pixel change
+function Sidebar() {
+  const width = useWindowWidth()
+  const isMobile = width < 768
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+
+// GOOD: re-renders only when boolean changes
+function Sidebar() {
+  const isMobile = useMediaQuery('(max-width: 767px)')
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```

package/docs/react/rerender-inline-objects.mdx

@@ -0,0 +1,18 @@
+# Avoid Inline Objects in JSX
+
+Inline objects create a new reference every render, causing child re-renders.
+
+```tsx
+// BAD: new reference every render
+<Component style={{ padding: 16 }} />
+<Component data={{ id: 1, name: 'Test' }} />
+
+// GOOD: stable reference
+const style = { padding: 16 }
+const data = useMemo(() => ({ id: 1, name: 'Test' }), [])
+<Component style={style} />
+<Component data={data} />
+
+// BEST: Tailwind
+<Component className="p-4" />
+```

package/docs/react/rerender-isolate-state.mdx

@@ -0,0 +1,36 @@
+# Isolate State to Smallest Component
+
+Parent components should not re-render when child state changes.
+
+```tsx
+// BAD: parent re-renders when count changes
+function Parent() {
+  const [count, setCount] = useState(0)
+  return (
+    <div>
+      <button onClick={() => setCount(c => c + 1)}>{count}</button>
+      <ExpensiveList />
+    </div>
+  )
+}
+
+// GOOD: state isolated in child
+function Parent() {
+  return (
+    <div>
+      <Counter />
+      <ExpensiveList />
+    </div>
+  )
+}
+```
+
+Use the children pattern to prevent re-renders:
+
+```tsx
+function StatefulWrapper({ children }) {
+  const [state, setState] = useState(false)
+  return <div onClick={() => setState(!state)}>{children}</div>
+}
+// Usage: <StatefulWrapper><ExpensiveChild /></StatefulWrapper>
+```

package/docs/react/rerender-lazy-init.mdx

@@ -0,0 +1,19 @@
+# Use Lazy State Initialization
+
+Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render.
+
+```tsx
+// BAD: JSON.parse runs on every render
+const [settings, setSettings] = useState(
+  JSON.parse(localStorage.getItem('settings') || '{}')
+)
+
+// GOOD: runs only once
+const [settings, setSettings] = useState(() =>
+  JSON.parse(localStorage.getItem('settings') || '{}')
+)
+```
+
+Use for: localStorage/sessionStorage reads, building data structures, DOM reads, heavy transformations.
+
+Skip for: simple primitives (`useState(0)`), direct references (`useState(props.value)`), cheap literals (`useState({})`).

package/docs/react/rerender-memo-extract.mdx

@@ -0,0 +1,26 @@
+# Extract to Memoized Components
+
+Extract expensive work into memoized components to enable early returns before computation.
+
+```tsx
+// BAD: computes avatar even when loading
+function Profile({ user, loading }: Props) {
+  const avatar = useMemo(() => {
+    const id = computeAvatarId(user)
+    return <Avatar id={id} />
+  }, [user])
+  if (loading) return <Skeleton />
+  return <div>{avatar}</div>
+}
+
+// GOOD: skips computation when loading
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+  const id = useMemo(() => computeAvatarId(user), [user])
+  return <Avatar id={id} />
+})
+
+function Profile({ user, loading }: Props) {
+  if (loading) return <Skeleton />
+  return <div><UserAvatar user={user} /></div>
+}
+```

package/docs/react/rerender-narrow-deps.mdx

@@ -0,0 +1,26 @@
+# Narrow Effect Dependencies
+
+Specify primitive dependencies instead of objects to minimize effect re-runs.
+
+```tsx
+// BAD: re-runs on any user field change
+useEffect(() => { console.log(user.id) }, [user])
+
+// GOOD: re-runs only when id changes
+useEffect(() => { console.log(user.id) }, [user.id])
+```
+
+For derived state, compute outside the effect:
+
+```tsx
+// BAD: runs on width=767, 766, 765...
+useEffect(() => {
+  if (width < 768) enableMobileMode()
+}, [width])
+
+// GOOD: runs only on boolean transition
+const isMobile = width < 768
+useEffect(() => {
+  if (isMobile) enableMobileMode()
+}, [isMobile])
+```

package/docs/react/rerender-transitions.mdx

@@ -0,0 +1,29 @@
+# Use Transitions for Non-Urgent Updates
+
+Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.
+
+```tsx
+// BAD: blocks UI on every scroll
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => setScrollY(window.scrollY)
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+
+// GOOD: non-blocking updates
+import { startTransition } from 'react'
+
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => {
+      startTransition(() => setScrollY(window.scrollY))
+    }
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```

package/docs/react/rerender-use-client-down.mdx

@@ -0,0 +1,34 @@
+# Push "use client" Down
+
+Keep parent as Server Component. Only mark the smallest interactive leaf as Client Component.
+
+```tsx
+// BAD: entire page is client-side
+"use client"
+export default function ProductPage({ product }) {
+  return (
+    <div>
+      <h1>{product.name}</h1>
+      <AddToCartButton product={product} />
+    </div>
+  )
+}
+
+// GOOD: only interactive part is client
+export default function ProductPage({ product }) {
+  return (
+    <div>
+      <h1>{product.name}</h1>
+      <AddToCartButton product={product} />
+    </div>
+  )
+}
+// AddToCartButton.tsx
+"use client"
+export function AddToCartButton({ product }) {
+  const [loading, setLoading] = useState(false)
+  return <button onClick={() => addToCart(product)}>Add to Cart</button>
+}
+```
+
+Only use "use client" when the component uses hooks, event handlers, or browser-only APIs.

package/docs/react/server-lru-cache.mdx

@@ -0,0 +1,24 @@
+# Cross-Request LRU Caching
+
+`React.cache()` only works within one request. For data shared across sequential requests, use an LRU cache.
+
+```tsx
+import { LRUCache } from 'lru-cache'
+
+const cache = new LRUCache<string, any>({
+  max: 1000,
+  ttl: 5 * 60 * 1000, // 5 minutes
+})
+
+export async function getUser(id: string) {
+  const cached = cache.get(id)
+  if (cached) return cached
+  const user = await db.user.findUnique({ where: { id } })
+  cache.set(id, user)
+  return user
+}
+// Request 1: DB query, result cached
+// Request 2: cache hit, no DB query
+```
+
+In serverless, consider Redis for cross-process caching.

package/docs/react/server-parallel-fetching.mdx

@@ -0,0 +1,24 @@
+# Parallel Data Fetching with Component Composition
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize.
+
+```tsx
+// BAD: Sidebar waits for Header's fetch
+export default async function Page() {
+  const header = await fetchHeader()
+  return <div><div>{header}</div><Sidebar /></div>
+}
+
+// GOOD: both fetch simultaneously
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+export default function Page() {
+  return <div><Header /><Sidebar /></div>
+}
+```

package/docs/react/server-react-cache.mdx

@@ -0,0 +1,16 @@
+# Per-Request Deduplication with React.cache()
+
+Use `React.cache()` for server-side request deduplication. Auth and DB queries benefit most.
+
+```tsx
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return db.user.findUnique({ where: { id: session.user.id } })
+})
+// Multiple calls in one request → single query
+```
+
+`React.cache()` only deduplicates within a single request. For cross-request caching, use LRU cache.

package/docs/react/server-rsc-serialization.mdx

@@ -0,0 +1,17 @@
+# Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties. Only pass fields the client actually uses.
+
+```tsx
+// BAD: serializes all 50 fields
+async function Page() {
+  const user = await fetchUser()
+  return <Profile user={user} />
+}
+
+// GOOD: serializes 1 field
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+```

package/package.json

@@ -1,12 +1,13 @@
 {
 	"name": "@numbered/docs-to-context",
-	"version": "0.1.5",
+	"version": "0.3.0",
 	"description": "Generate project docs (component APIs, design system, architecture) and inject index into CLAUDE.md",
 	"bin": {
 		"docs-to-context": "scripts/generate.ts"
 	},
 	"files": [
 		"scripts/*.ts",
+		"docs/**/*.mdx",
 		"README.md"
 	],
 	"scripts": {