@brookmind/ai-toolkit 1.1.7 → 1.2.0

package/skills/react-best-practices/rules/async-suspense-boundaries.md

@@ -1,100 +0,0 @@
----
-title: Strategic Suspense Boundaries
-impact: HIGH
-impactDescription: faster initial paint
-tags: async, suspense, layout-shift, react-19
----
-
-## Strategic Suspense Boundaries
-
-Use Suspense boundaries to show wrapper UI immediately while data loads asynchronously. This improves perceived performance by not blocking the entire UI.
-
-**Incorrect (entire component waits for data):**
-
-```tsx
-function Page() {
-  const { data, isLoading } = useQuery(["data"], fetchData);
-
-  if (isLoading) return <Skeleton />;
-
-  return (
-    <div>
-      <div>Sidebar</div>
-      <div>Header</div>
-      <div>
-        <DataDisplay data={data} />
-      </div>
-      <div>Footer</div>
-    </div>
-  );
-}
-```
-
-The entire layout waits for data even though only the middle section needs it.
-
-**Correct (wrapper shows immediately, data section has its own loading state):**
-
-```tsx
-function Page() {
-  return (
-    <div>
-      <div>Sidebar</div>
-      <div>Header</div>
-      <div>
-        <Suspense fallback={<Skeleton />}>
-          <DataDisplay />
-        </Suspense>
-      </div>
-      <div>Footer</div>
-    </div>
-  );
-}
-
-function DataDisplay() {
-  const { data } = useSuspenseQuery(["data"], fetchData);
-  return <div>{data.content}</div>;
-}
-```
-
-Sidebar, Header, and Footer render immediately. Only DataDisplay shows a skeleton while loading.
-
-**Alternative with React 19 use() hook (share promise across components):**
-
-```tsx
-function Page() {
-  // Start fetch immediately, but don't await
-  const dataPromise = useMemo(() => fetchData(), []);
-
-  return (
-    <div>
-      <div>Sidebar</div>
-      <div>Header</div>
-      <Suspense fallback={<Skeleton />}>
-        <DataDisplay dataPromise={dataPromise} />
-        <DataSummary dataPromise={dataPromise} />
-      </Suspense>
-      <div>Footer</div>
-    </div>
-  );
-}
-
-function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
-  const data = use(dataPromise); // React 19: unwraps the promise
-  return <div>{data.content}</div>;
-}
-
-function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
-  const data = use(dataPromise); // Reuses the same promise
-  return <div>{data.summary}</div>;
-}
-```
-
-Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
-
-**When NOT to use this pattern:**
-
-- Critical data needed for layout decisions (affects positioning)
-- Small, fast queries where suspense overhead isn't worth it
-- When you want to avoid layout shift (loading → content jump)
-
-**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.

package/skills/react-best-practices/rules/bundle-barrel-imports.md

@@ -1,42 +0,0 @@
----
-title: Avoid Barrel File Imports
-impact: CRITICAL
-impactDescription: 200-800ms import cost, slow builds
-tags: bundle, imports, tree-shaking, barrel-files, performance
----
-
-## Avoid Barrel File Imports
-
-Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
-
-Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
-
-**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
-
-**Incorrect (imports entire library):**
-
-```tsx
-import { Check, X, Menu } from "lucide-react";
-// Loads 1,583 modules, takes ~2.8s extra in dev
-// Runtime cost: 200-800ms on every cold start
-
-import { Button, TextField } from "@mui/material";
-// Loads 2,225 modules, takes ~4.2s extra in dev
-```
-
-**Correct (imports only what you need):**
-
-```tsx
-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";
-// Loads only 3 modules (~2KB vs ~1MB)
-
-import Button from "@mui/material/Button";
-import TextField from "@mui/material/TextField";
-// Loads only what you use
-```
-
-Direct imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
-
-Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.

package/skills/react-best-practices/rules/bundle-conditional.md

@@ -1,106 +0,0 @@
----
-title: Conditional Module Loading
-impact: HIGH
-impactDescription: loads large data only when needed
-tags: bundle, conditional-loading, lazy-loading, react-19, suspense
----
-
-## Conditional Module Loading
-
-Load large data or modules only when a feature is activated, reducing initial bundle size.
-
-**React 19 with use() and Suspense (Recommended):**
-
-```tsx
-import { use, Suspense, useMemo } from "react";
-
-function AnimationPlayer({ enabled }: { enabled: boolean }) {
-  // Create promise only when enabled
-  const framesPromise = useMemo(
-    () =>
-      enabled ? import("./animation-frames.js").then((m) => m.frames) : null,
-    [enabled],
-  );
-
-  if (!framesPromise) return null;
-
-  const frames = use(framesPromise); // React 19: unwraps promise
-  return <Canvas frames={frames} />;
-}
-
-// Wrap in Suspense
-function AnimationSection({ enabled }: { enabled: boolean }) {
-  return (
-    <Suspense fallback={<Skeleton />}>
-      <AnimationPlayer enabled={enabled} />
-    </Suspense>
-  );
-}
-```
-
-**With React.lazy for component splitting:**
-
-```tsx
-import { lazy, Suspense } from "react";
-
-// Component is only loaded when rendered
-const HeavyEditor = lazy(() => import("./HeavyEditor"));
-
-function EditorSection({ showEditor }: { showEditor: boolean }) {
-  if (!showEditor) return null;
-
-  return (
-    <Suspense fallback={<EditorSkeleton />}>
-      <HeavyEditor />
-    </Suspense>
-  );
-}
-```
-
-**Traditional pattern with useEffect (pre-React 19):**
-
-```tsx
-function AnimationPlayer({ enabled }: { enabled: boolean }) {
-  const [frames, setFrames] = useState<Frame[] | null>(null);
-  const [error, setError] = useState<Error | null>(null);
-
-  useEffect(() => {
-    if (enabled && !frames) {
-      import("./animation-frames.js")
-        .then((mod) => setFrames(mod.frames))
-        .catch(setError);
-    }
-  }, [enabled, frames]);
-
-  if (error) return <ErrorMessage error={error} />;
-  if (!frames) return <Skeleton />;
-  return <Canvas frames={frames} />;
-}
-```
-
-**With React Query for data modules:**
-
-```tsx
-import { useQuery } from "@tanstack/react-query";
-
-function AnimationPlayer({ enabled }: { enabled: boolean }) {
-  const { data: frames, isLoading } = useQuery({
-    queryKey: ["animation-frames"],
-    queryFn: () => import("./animation-frames.js").then((m) => m.frames),
-    enabled, // Only fetch when enabled
-  });
-
-  if (!enabled) return null;
-  if (isLoading) return <Skeleton />;
-  return <Canvas frames={frames} />;
-}
-```
-
-**Key benefits:**
-
-- Reduces initial bundle size
-- Improves Time to Interactive (TTI)
-- Loads resources on-demand
-- Works with code splitting
-
-Reference: [React lazy](https://react.dev/reference/react/lazy)

package/skills/react-best-practices/rules/bundle-preload.md

@@ -1,44 +0,0 @@
----
-title: Preload Based on User Intent
-impact: MEDIUM
-impactDescription: reduces perceived latency
-tags: bundle, preload, user-intent, hover
----
-
-## Preload Based on User Intent
-
-Preload heavy bundles before they're needed to reduce perceived latency.
-
-**Example (preload on hover/focus):**
-
-```tsx
-function EditorButton({ onClick }: { onClick: () => void }) {
-  const preload = () => {
-    void import("./monaco-editor");
-  };
-
-  return (
-    <button onMouseEnter={preload} onFocus={preload} onClick={onClick}>
-      Open Editor
-    </button>
-  );
-}
-```
-
-**Example (preload when feature flag is enabled):**
-
-```tsx
-function FlagsProvider({ children, flags }: Props) {
-  useEffect(() => {
-    if (flags.editorEnabled) {
-      void import("./monaco-editor").then((mod) => mod.init());
-    }
-  }, [flags.editorEnabled]);
-
-  return (
-    <FlagsContext.Provider value={flags}>{children}</FlagsContext.Provider>
-  );
-}
-```
-
-Preloading on user intent (hover, focus) or feature activation reduces perceived latency when the user actually clicks.

package/skills/react-best-practices/rules/client-event-listeners.md

@@ -1,131 +0,0 @@
----
-title: Deduplicate Global Event Listeners
-impact: MEDIUM
-impactDescription: single listener for N components
-tags: client, event-listeners, useSyncExternalStore, subscription
----
-
-## Deduplicate Global Event Listeners
-
-Use `useSyncExternalStore` to share global event listeners across component instances. This is the React 18+ standard pattern for subscribing to external stores.
-
-**Incorrect (N instances = N listeners):**
-
-```tsx
-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]);
-}
-```
-
-When using `useKeyboardShortcut` multiple times, each instance registers a new listener.
-
-**Correct (N instances = 1 listener with useSyncExternalStore):**
-
-```tsx
-import { useSyncExternalStore, useCallback, useEffect } from "react";
-
-// Module-level store for keyboard shortcuts
-const keyCallbacks = new Map<string, Set<() => void>>();
-const listeners = new Set<() => void>();
-
-function subscribeToKeyboard(onStoreChange: () => void) {
-  if (listeners.size === 0) {
-    // First subscriber - add the global listener
-    window.addEventListener("keydown", handleKeyDown);
-  }
-  listeners.add(onStoreChange);
-
-  return () => {
-    listeners.delete(onStoreChange);
-    if (listeners.size === 0) {
-      // Last subscriber - remove the global listener
-      window.removeEventListener("keydown", handleKeyDown);
-    }
-  };
-}
-
-function handleKeyDown(e: KeyboardEvent) {
-  if (e.metaKey && keyCallbacks.has(e.key)) {
-    keyCallbacks.get(e.key)!.forEach((cb) => cb());
-  }
-}
-
-function useKeyboardShortcut(key: string, callback: () => void) {
-  // Register callback in the module-level Map
-  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]);
-
-  // Subscribe to the shared keyboard listener
-  useSyncExternalStore(
-    subscribeToKeyboard,
-    () => null, // getSnapshot - we don't need state, just subscription
-    () => null, // getServerSnapshot
-  );
-}
-
-// Usage - multiple shortcuts share single listener
-function Profile() {
-  useKeyboardShortcut("p", () => openProfile());
-  useKeyboardShortcut("k", () => openSearch());
-  useKeyboardShortcut("/", () => focusCommandBar());
-  // All share ONE keydown listener!
-}
-```
-
-**Simpler pattern for single-use subscriptions:**
-
-```tsx
-import { useSyncExternalStore } from "react";
-
-function useOnlineStatus() {
-  return useSyncExternalStore(
-    (callback) => {
-      window.addEventListener("online", callback);
-      window.addEventListener("offline", callback);
-      return () => {
-        window.removeEventListener("online", callback);
-        window.removeEventListener("offline", callback);
-      };
-    },
-    () => navigator.onLine,
-    () => true, // Server snapshot
-  );
-}
-
-function StatusIndicator() {
-  const isOnline = useOnlineStatus();
-  return <span>{isOnline ? "🟢" : "🔴"}</span>;
-}
-```
-
-**Why useSyncExternalStore?**
-
-- Official React API for external subscriptions
-- Handles concurrent rendering correctly
-- Automatic cleanup on unmount
-- Works with React 18+ concurrent features
-- No external dependencies required
-
-Reference: [React useSyncExternalStore](https://react.dev/reference/react/useSyncExternalStore)

package/skills/react-best-practices/rules/client-swr-dedup.md

@@ -1,133 +0,0 @@
----
-title: Use React Query for Automatic Deduplication
-impact: MEDIUM-HIGH
-impactDescription: automatic deduplication and caching
-tags: client, react-query, tanstack-query, deduplication, data-fetching
----
-
-## Use React Query for Automatic Deduplication
-
-TanStack Query (React Query 5) enables request deduplication, caching, background refetching, and stale-while-revalidate patterns across component instances.
-
-**Incorrect (no deduplication, each instance fetches):**
-
-```tsx
-function UserList() {
-  const [users, setUsers] = useState<User[]>([]);
-  const [isLoading, setIsLoading] = useState(true);
-
-  useEffect(() => {
-    fetch("/api/users")
-      .then((r) => r.json())
-      .then(setUsers)
-      .finally(() => setIsLoading(false));
-  }, []);
-
-  if (isLoading) return <Skeleton />;
-  return (
-    <ul>
-      {users.map((u) => (
-        <li key={u.id}>{u.name}</li>
-      ))}
-    </ul>
-  );
-}
-```
-
-Multiple instances of `UserList` = multiple network requests.
-
-**Correct (multiple instances share one request):**
-
-```tsx
-import { useQuery } from "@tanstack/react-query";
-
-function UserList() {
-  const { data: users, isLoading } = useQuery({
-    queryKey: ["users"],
-    queryFn: () => fetch("/api/users").then((r) => r.json()),
-  });
-
-  if (isLoading) return <Skeleton />;
-  return (
-    <ul>
-      {users.map((u) => (
-        <li key={u.id}>{u.name}</li>
-      ))}
-    </ul>
-  );
-}
-```
-
-Multiple instances = single request, shared cache.
-
-**With Suspense (React 19):**
-
-```tsx
-import { useSuspenseQuery } from "@tanstack/react-query";
-
-function UserList() {
-  const { data: users } = useSuspenseQuery({
-    queryKey: ["users"],
-    queryFn: fetchUsers,
-  });
-
-  return (
-    <ul>
-      {users.map((u) => (
-        <li key={u.id}>{u.name}</li>
-      ))}
-    </ul>
-  );
-}
-
-// Parent component
-<Suspense fallback={<Skeleton />}>
-  <UserList />
-</Suspense>;
-```
-
-**For mutations:**
-
-```tsx
-import { useMutation, useQueryClient } from "@tanstack/react-query";
-
-function UpdateButton({ userId }: { userId: string }) {
-  const queryClient = useQueryClient();
-
-  const { mutate, isPending } = useMutation({
-    mutationFn: (data: UserUpdate) => updateUser(userId, data),
-    onSuccess: () => {
-      // Invalidate and refetch
-      queryClient.invalidateQueries({ queryKey: ["users"] });
-    },
-  });
-
-  return (
-    <button onClick={() => mutate({ name: "New Name" })} disabled={isPending}>
-      {isPending ? "Updating..." : "Update"}
-    </button>
-  );
-}
-```
-
-**For immutable/static data:**
-
-```tsx
-const { data } = useQuery({
-  queryKey: ["config"],
-  queryFn: fetchConfig,
-  staleTime: Infinity, // Never refetch
-  gcTime: Infinity, // Never garbage collect
-});
-```
-
-**Key benefits:**
-
-- Automatic request deduplication
-- Built-in caching with configurable stale times
-- Background refetching
-- Optimistic updates
-- Suspense support (React 19)
-- DevTools for debugging
-
-Reference: [https://tanstack.com/query](https://tanstack.com/query)

package/skills/react-best-practices/rules/js-batch-dom-css.md

@@ -1,82 +0,0 @@
----
-title: Batch DOM CSS Changes
-impact: MEDIUM
-impactDescription: reduces reflows/repaints
-tags: javascript, dom, css, performance, reflow
----
-
-## Batch DOM CSS Changes
-
-Avoid changing styles one property at a time. Group multiple CSS changes together via classes or `cssText` to minimize browser reflows.
-
-**Incorrect (multiple reflows):**
-
-```typescript
-function updateElementStyles(element: HTMLElement) {
-  // Each line triggers a reflow
-  element.style.width = '100px'
-  element.style.height = '200px'
-  element.style.backgroundColor = 'blue'
-  element.style.border = '1px solid black'
-}
-```
-
-**Correct (add class - single reflow):**
-
-```typescript
-// CSS file
-.highlighted-box {
-  width: 100px;
-  height: 200px;
-  background-color: blue;
-  border: 1px solid black;
-}
-
-// JavaScript
-function updateElementStyles(element: HTMLElement) {
-  element.classList.add('highlighted-box')
-}
-```
-
-**Correct (change cssText - single reflow):**
-
-```typescript
-function updateElementStyles(element: HTMLElement) {
-  element.style.cssText = `
-    width: 100px;
-    height: 200px;
-    background-color: blue;
-    border: 1px solid black;
-  `
-}
-```
-
-**React example:**
-
-```tsx
-// Incorrect: changing styles one by one
-function Box({ isHighlighted }: { isHighlighted: boolean }) {
-  const ref = useRef<HTMLDivElement>(null)
-  
-  useEffect(() => {
-    if (ref.current && isHighlighted) {
-      ref.current.style.width = '100px'
-      ref.current.style.height = '200px'
-      ref.current.style.backgroundColor = 'blue'
-    }
-  }, [isHighlighted])
-  
-  return <div ref={ref}>Content</div>
-}
-
-// Correct: toggle class
-function Box({ isHighlighted }: { isHighlighted: boolean }) {
-  return (
-    <div className={isHighlighted ? 'highlighted-box' : ''}>
-      Content
-    </div>
-  )
-}
-```
-
-Prefer CSS classes over inline styles when possible. Classes are cached by the browser and provide better separation of concerns.