@jgamaraalv/ts-dev-kit 1.0.0

package/skills/react-best-practices/references/js-performance.md

@@ -0,0 +1,210 @@
+# JavaScript Performance
+
+Low-level JS optimizations for DOM manipulation, caching, and data structures.
+
+## Table of Contents
+
+- [Avoid Layout Thrashing](#avoid-layout-thrashing)
+- [Cache Repeated Function Calls](#cache-repeated-function-calls)
+- [Cache Storage API Calls](#cache-storage-api-calls)
+- [Build Index Maps for Repeated Lookups](#build-index-maps-for-repeated-lookups)
+- [Use Loop for Min/Max Instead of Sort](#use-loop-for-minmax-instead-of-sort)
+
+---
+
+## Avoid Layout Thrashing
+
+Avoid interleaving style writes with layout reads. Reading layout properties (`offsetWidth`, `getBoundingClientRect()`, `getComputedStyle()`) between style changes forces a synchronous reflow.
+
+**Incorrect (interleaved reads and writes):**
+
+```typescript
+function layoutThrashing(element: HTMLElement) {
+  element.style.width = "100px";
+  const width = element.offsetWidth; // Forces reflow
+  element.style.height = "200px";
+  const height = element.offsetHeight; // Forces another reflow
+}
+```
+
+**Correct (batch writes, then read once):**
+
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  element.style.width = "100px";
+  element.style.height = "200px";
+  element.style.backgroundColor = "blue";
+  element.style.border = "1px solid black";
+
+  const { width, height } = element.getBoundingClientRect();
+}
+```
+
+**Better: use CSS classes:**
+
+```typescript
+element.classList.add("highlighted-box");
+const { width, height } = element.getBoundingClientRect();
+```
+
+**React example:**
+
+```tsx
+// Incorrect
+useEffect(() => {
+  ref.current.style.width = "100px";
+  const width = ref.current.offsetWidth; // Forces layout
+  ref.current.style.height = "200px";
+}, [isHighlighted]);
+
+// Correct: toggle class
+<div className={isHighlighted ? "highlighted-box" : ""}>Content</div>;
+```
+
+Prefer CSS classes over inline styles. See [layout-forcing properties gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) for more information.
+
+---
+
+## Cache Repeated Function Calls
+
+Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs.
+
+**Incorrect (redundant computation):**
+
+```typescript
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map((project) => {
+        const slug = slugify(project.name); // Called 100+ times for same names
+        return <ProjectCard key={project.id} slug={slug} />;
+      })}
+    </div>
+  );
+}
+```
+
+**Correct (cached results):**
+
+```typescript
+const slugifyCache = new Map<string, string>();
+
+function cachedSlugify(text: string): string {
+  if (slugifyCache.has(text)) return slugifyCache.get(text)!;
+  const result = slugify(text);
+  slugifyCache.set(text, result);
+  return result;
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+Reference: [How we made the Vercel Dashboard twice as fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
+
+---
+
+## Cache Storage API Calls
+
+`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
+
+**Incorrect (reads storage on every call):**
+
+```typescript
+function getTheme() {
+  return localStorage.getItem("theme") ?? "light";
+}
+// Called 10 times = 10 storage reads
+```
+
+**Correct (Map cache):**
+
+```typescript
+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);
+}
+```
+
+**Invalidate on external changes:**
+
+```typescript
+window.addEventListener("storage", (e) => {
+  if (e.key) storageCache.delete(e.key);
+});
+
+document.addEventListener("visibilitychange", () => {
+  if (document.visibilityState === "visible") storageCache.clear();
+});
+```
+
+---
+
+## Build Index Maps for Repeated Lookups
+
+Multiple `.find()` calls by the same key should use a Map.
+
+**Incorrect (O(n) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  return orders.map((order) => ({
+    ...order,
+    user: users.find((u) => u.id === order.userId),
+  }));
+}
+```
+
+**Correct (O(1) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  const userById = new Map(users.map((u) => [u.id, u]));
+
+  return orders.map((order) => ({
+    ...order,
+    user: userById.get(order.userId),
+  }));
+}
+```
+
+Build map once O(n), then all lookups are O(1). For 1000 orders x 1000 users: 1M ops down to 2K ops.
+
+---
+
+## Use Loop for Min/Max Instead of Sort
+
+Finding the smallest or largest element only requires a single pass. Sorting is O(n log n) waste.
+
+**Incorrect (O(n log n)):**
+
+```typescript
+function getLatestProject(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt);
+  return sorted[0];
+}
+```
+
+**Correct (O(n)):**
+
+```typescript
+function getLatestProject(projects: Project[]) {
+  if (projects.length === 0) return null;
+
+  let latest = projects[0];
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt > latest.updatedAt) latest = projects[i];
+  }
+  return latest;
+}
+```
+
+`Math.min(...arr)` / `Math.max(...arr)` works for small arrays but throws on very large arrays due to spread operator limitations (~124K in Chrome, ~638K in Safari).

package/skills/react-best-practices/references/rendering-performance.md

@@ -0,0 +1,209 @@
+# Rendering Performance
+
+Optimize DOM rendering, hydration, and visual transitions.
+
+## Table of Contents
+
+- [Animate SVG Wrapper Instead of SVG Element](#animate-svg-wrapper-instead-of-svg-element)
+- [CSS content-visibility for Long Lists](#css-content-visibility-for-long-lists)
+- [Hoist Static JSX Elements](#hoist-static-jsx-elements)
+- [Prevent Hydration Mismatch Without Flickering](#prevent-hydration-mismatch-without-flickering)
+- [Use useTransition Over Manual Loading States](#use-usetransition-over-manual-loading-states)
+
+---
+
+## Animate SVG Wrapper Instead of SVG Element
+
+Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `<div>` and animate the wrapper instead.
+
+**Incorrect (no hardware acceleration):**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <svg className="animate-spin" width="24" height="24" viewBox="0 0 24 24">
+      <circle cx="12" cy="12" r="10" stroke="currentColor" />
+    </svg>
+  );
+}
+```
+
+**Correct (hardware accelerated):**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <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`).
+
+---
+
+## 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;
+}
+```
+
+```tsx
+function MessageList({ messages }: { messages: Message[] }) {
+  return (
+    <div className="overflow-y-auto h-screen">
+      {messages.map((msg) => (
+        <div key={msg.id} className="message-item">
+          <Avatar user={msg.author} />
+          <div>{msg.content}</div>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+For 1000 messages, browser skips layout/paint for ~990 off-screen items (10x faster initial render).
+
+---
+
+## Hoist Static JSX Elements
+
+Extract static JSX outside components to avoid re-creation.
+
+**Incorrect (recreates element every render):**
+
+```tsx
+function LoadingSkeleton() {
+  return <div className="animate-pulse h-20 bg-gray-200" />;
+}
+
+function Container() {
+  return <div>{loading && <LoadingSkeleton />}</div>;
+}
+```
+
+**Correct (reuses same element):**
+
+```tsx
+const loadingSkeleton = <div className="animate-pulse h-20 bg-gray-200" />;
+
+function Container() {
+  return <div>{loading && loadingSkeleton}</div>;
+}
+```
+
+Especially helpful for large and static SVG nodes. React Compiler automatically hoists static JSX when enabled.
+
+---
+
+## Prevent Hydration Mismatch Without Flickering
+
+When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous inline script that updates the DOM before React hydrates.
+
+**Incorrect (visual flickering):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  const [theme, setTheme] = useState("light");
+
+  useEffect(() => {
+    const stored = localStorage.getItem("theme");
+    if (stored) setTheme(stored);
+  }, []);
+
+  return <div className={theme}>{children}</div>;
+}
+```
+
+**Correct (no flicker, no hydration mismatch):**
+
+Use an inline `<script>` tag with a self-executing function that reads localStorage synchronously and sets the className on the wrapper element before React hydrates. The script runs before the browser paints, ensuring correct initial render.
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <div id="theme-wrapper">{children}</div>
+      {/* Inline script reads localStorage and sets className synchronously */}
+      <ThemeScript />
+    </>
+  );
+}
+```
+
+The inline script executes synchronously before showing the element. Useful for theme toggles, user preferences, and authentication states.
+
+---
+
+## Use useTransition Over Manual Loading States
+
+Use `useTransition` instead of manual `useState` for loading states. Provides built-in `isPending` state and automatically manages transitions.
+
+**Incorrect (manual loading state):**
+
+```tsx
+function SearchResults() {
+  const [query, setQuery] = useState("");
+  const [results, setResults] = useState([]);
+  const [isLoading, setIsLoading] = useState(false);
+
+  const handleSearch = async (value: string) => {
+    setIsLoading(true);
+    setQuery(value);
+    const data = await fetchResults(value);
+    setResults(data);
+    setIsLoading(false);
+  };
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isLoading && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  );
+}
+```
+
+**Correct (useTransition):**
+
+```tsx
+import { useTransition, useState } from "react";
+
+function SearchResults() {
+  const [query, setQuery] = useState("");
+  const [results, setResults] = useState([]);
+  const [isPending, startTransition] = useTransition();
+
+  const handleSearch = (value: string) => {
+    setQuery(value);
+
+    startTransition(async () => {
+      const data = await fetchResults(value);
+      setResults(data);
+    });
+  };
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isPending && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  );
+}
+```
+
+Benefits: automatic pending state, error resilience, better responsiveness, interrupt handling (new transitions cancel pending ones).
+
+Reference: [useTransition](https://react.dev/reference/react/useTransition)