@ngxtm/devkit 3.4.0 → 3.4.1

package/rules/react/component-patterns/references/REFERENCE.md

@@ -0,0 +1,126 @@
+# React Component Patterns Reference
+
+Advanced component patterns and composition techniques.
+
+## References
+
+- [**HOC Pattern**](hoc-pattern.md) - Higher-Order Components.
+- [**Render Props**](render-props.md) - Render prop pattern.
+- [**Compound Components**](compound-components.md) - Complex component composition.
+
+## Higher-Order Component (HOC)
+
+```jsx
+// withAuth.jsx
+export function withAuth(Component) {
+  return function AuthenticatedComponent(props) {
+    const { user, loading } = useAuth();
+
+    if (loading) return <Loading />;
+    if (!user) return <Redirect to="/login" />;
+
+    return <Component {...props} user={user} />;
+  };
+}
+
+// Usage
+const ProtectedPage = withAuth(Dashboard);
+```
+
+## Render Props Pattern
+
+```jsx
+// Mouse tracking example
+export function MouseTracker({ render }) {
+  const [position, setPosition] = useState({ x: 0, y: 0 });
+
+  const handleMouseMove = (event) => {
+    setPosition({ x: event.clientX, y: event.clientY });
+  };
+
+  return (
+    <div onMouseMove={handleMouseMove}>
+      {render(position)}
+    </div>
+  );
+}
+
+// Usage
+<MouseTracker
+  render={({ x, y }) => (
+    <p>Mouse position: {x}, {y}</p>
+  )}
+/>
+```
+
+## Compound Components
+
+```jsx
+// Accordion component
+const AccordionContext = createContext();
+
+export function Accordion({ children }) {
+  const [activeIndex, setActiveIndex] = useState(null);
+
+  return (
+    <AccordionContext.Provider value={{ activeIndex, setActiveIndex }}>
+      <div className="accordion">{children}</div>
+    </AccordionContext.Provider>
+  );
+}
+
+Accordion.Item = function AccordionItem({ index, children }) {
+  return <div className="accordion-item">{children}</div>;
+};
+
+Accordion.Header = function AccordionHeader({ index, children }) {
+  const { activeIndex, setActiveIndex } = useContext(AccordionContext);
+  
+  return (
+    <button onClick={() => setActiveIndex(index === activeIndex ? null : index)}>
+      {children}
+    </button>
+  );
+};
+
+Accordion.Body = function AccordionBody({ index, children }) {
+  const { activeIndex } = useContext(AccordionContext);
+  
+  return activeIndex === index ? <div>{children}</div> : null;
+};
+
+// Usage
+<Accordion>
+  <Accordion.Item index={0}>
+    <Accordion.Header index={0}>Section 1</Accordion.Header>
+    <Accordion.Body index={0}>Content 1</Accordion.Body>
+  </Accordion.Item>
+</Accordion>
+```
+
+## Controlled vs Uncontrolled
+
+```jsx
+// Controlled input
+function ControlledInput() {
+  const [value, setValue] = useState('');
+  
+  return (
+    <input
+      value={value}
+      onChange={e => setValue(e.target.value)}
+    />
+  );
+}
+
+// Uncontrolled input
+function UncontrolledInput() {
+  const inputRef = useRef();
+  
+  const handleSubmit = () => {
+    console.log(inputRef.current.value);
+  };
+  
+  return <input ref={inputRef} />;
+}
+```

package/rules/react/hooks/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: React Hooks
+description: Best practices for React Hooks usage and custom hook creation.
+metadata:
+  labels: [react, hooks, custom-hooks, useeffect]
+  triggers:
+    files: ['**/*.tsx', '**/*.jsx']
+    keywords: [useEffect, useCallback, useMemo, useRef, custom hook]
+---
+
+# React Hooks
+
+## **Priority: P1 (OPERATIONAL)**
+
+Effective usage of React Hooks.
+
+## Implementation Guidelines
+
+- **Rules**: Top-level only. Only in React functions.
+- **`useEffect`**: Sync with external systems ONLY. Cleanup required.
+- **`useRef`**: Mutable state without re-renders (DOM, timers, tracking).
+- **`useMemo`/`Callback`**: Measure first. Use for stable refs or heavy computation.
+- **Dependencies**: Exhaustive deps always. Fix logic, don't disable linter.
+- **Custom Hooks**: Extract shared logic. Prefix `use*`.
+- **Refs as Escape Hatch**: Access imperative APIs (focus, scroll).
+- **Stability**: Use `useLatest` pattern (ref) for event handlers to avoid dependency changes.
+- **Concurrency**: `useTransition` / `useDeferredValue` for non-blocking UI updates.
+- **Initialization**: Lazy state `useState(() => expensive())`.
+
+## Anti-Patterns
+
+- **No Effects for Data Flow**: Derive state in render.
+- **No Missing Deps**: Causes stale closures.
+- **No Complex Effects**: Split into multiple simple effects.
+- **No Oversubscription**: Check `why-did-you-render`.
+
+## Code
+
+```tsx
+// Custom Hook
+function useWindowSize() {
+  const [size, setSize] = useState({ w: 0, h: 0 });
+
+  useEffect(() => {
+    const onResize = () =>
+      setSize({ w: window.innerWidth, h: window.innerHeight });
+    window.addEventListener('resize', onResize);
+    return () => window.removeEventListener('resize', onResize);
+  }, []); // Empty = mount only
+
+  return size;
+}
+
+// Lazy Init
+const [state, setState] = useState(() => computeExpensiveValue());
+```
+
+## Reference & Examples
+
+See [references/REFERENCE.md](references/REFERENCE.md).

package/rules/react/hooks/references/REFERENCE.md

@@ -0,0 +1,132 @@
+# React Hooks Reference
+
+Advanced custom hooks and patterns.
+
+## References
+
+- [**Custom Hooks Library**](custom-hooks.md) - Common custom hook implementations.
+- [**Advanced Patterns**](advanced-patterns.md) - Complex hook compositions.
+
+## Custom Hooks Library
+
+```jsx
+// useLocalStorage - Persist state in localStorage
+function useLocalStorage(key, initialValue) {
+  const [storedValue, setStoredValue] = useState(() => {
+    try {
+      const item = window.localStorage.getItem(key);
+      return item ? JSON.parse(item) : initialValue;
+    } catch (error) {
+      console.error(error);
+      return initialValue;
+    }
+  });
+
+  const setValue = (value) => {
+    try {
+      const valueToStore = value instanceof Function ? value(storedValue) : value;
+      setStoredValue(valueToStore);
+      window.localStorage.setItem(key, JSON.stringify(valueToStore));
+    } catch (error) {
+      console.error(error);
+    }
+  };
+
+  return [storedValue, setValue];
+}
+
+// useDebounce - Debounce a value
+function useDebounce(value, delay) {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const handler = setTimeout(() => setDebouncedValue(value), delay);
+    return () => clearTimeout(handler);
+  }, [value, delay]);
+
+  return debouncedValue;
+}
+
+// useWindowSize - Track window dimensions
+function useWindowSize() {
+  const [size, setSize] = useState({
+    width: window.innerWidth,
+    height: window.innerHeight,
+  });
+
+  useEffect(() => {
+    const handleResize = () => {
+      setSize({
+        width: window.innerWidth,
+        height: window.innerHeight,
+      });
+    };
+
+    window.addEventListener('resize', handleResize);
+    return () => window.removeEventListener('resize', handleResize);
+  }, []);
+
+  return size;
+}
+
+// useOnClickOutside - Detect clicks outside an element
+function useOnClickOutside(ref, handler) {
+  useEffect(() => {
+    const listener = (event) => {
+      if (!ref.current || ref.current.contains(event.target)) {
+        return;
+      }
+      handler(event);
+    };
+
+    document.addEventListener('mousedown', listener);
+    document.addEventListener('touchstart', listener);
+
+    return () => {
+      document.removeEventListener('mousedown', listener);
+      document.removeEventListener('touchstart', listener);
+    };
+  }, [ref, handler]);
+}
+
+// useIntersectionObserver - Detect element visibility
+function useIntersectionObserver(ref, options) {
+  const [isIntersecting, setIsIntersecting] = useState(false);
+
+  useEffect(() => {
+    const observer = new IntersectionObserver(([entry]) => {
+      setIsIntersecting(entry.isIntersecting);
+    }, options);
+
+    if (ref.current) {
+      observer.observe(ref.current);
+    }
+
+    return () => observer.disconnect();
+  }, [ref, options]);
+
+  return isIntersecting;
+}
+
+// usePrevious - Get previous value
+function usePrevious(value) {
+  const ref = useRef();
+
+  useEffect(() => {
+    ref.current = value;
+  }, [value]);
+
+  return ref.current;
+}
+
+// useToggle - Boolean toggle
+function useToggle(initialValue = false) {
+  const [value, setValue] = useState(initialValue);
+
+  const toggle = useCallback(() => {
+    setValue(v => !v);
+  }, []);
+
+  return [value, toggle];
+}
+```

package/rules/react/hooks.rule.md

@@ -0,0 +1,79 @@
+---
+id: react-hooks
+version: 1.0.0
+triggers: [hooks, useEffect, useState, custom hooks]
+---
+
+# React Hooks
+
+Modern React with hooks and functional components.
+
+## useState
+
+```tsx
+const [count, setCount] = useState(0);
+const [user, setUser] = useState<User | null>(null);
+
+// Functional updates for derived state
+setCount(prev => prev + 1);
+```
+
+## useEffect
+
+```tsx
+// Run on mount only
+useEffect(() => {
+  fetchData();
+}, []);
+
+// Run when dependency changes
+useEffect(() => {
+  fetchUser(userId);
+}, [userId]);
+
+// Cleanup
+useEffect(() => {
+  const sub = subscribe();
+  return () => sub.unsubscribe();
+}, []);
+```
+
+## Custom Hooks
+
+Extract reusable logic:
+
+```tsx
+function useDebounce<T>(value: T, delay: number): T {
+  const [debounced, setDebounced] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+
+  return debounced;
+}
+```
+
+## useMemo / useCallback
+
+```tsx
+// Memoize expensive computation
+const sorted = useMemo(() => items.sort(compare), [items]);
+
+// Stable callback reference
+const handleClick = useCallback(() => {
+  doSomething(id);
+}, [id]);
+```
+
+## useRef
+
+```tsx
+const inputRef = useRef<HTMLInputElement>(null);
+
+// Focus on mount
+useEffect(() => {
+  inputRef.current?.focus();
+}, []);
+```

package/rules/react/performance/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: React Performance
+description: Optimization strategies for React applications (Client & Server).
+metadata:
+  labels: [react, performance, optimization, nextjs]
+  triggers:
+    files: ['**/*.tsx', '**/*.jsx']
+    keywords: [waterfall, bundle, lazy, suspense, dynamic]
+---
+
+# React Performance
+
+## **Priority: P0 (CRITICAL)**
+
+Strategies to minimize waterfalls, bundle size, and render cost.
+
+## Elimination of Waterfalls (P0)
+
+- **Parallel Data**: Use `Promise.all` for independent fetches. Avoid sequential `await`.
+- **Preload**: Start fetches before render (in event handlers or route loaders).
+- **Suspense**: Use Suspense boundaries to stream partial content.
+
+## Bundle Optimization (P0)
+
+- **No Barrel Files**: Import directly `import { Btn } from './Btn'` vs `import { Btn } from './components'`.
+- **Lazy Load**: `React.lazy` / `next/dynamic` for heavy components (Charts, Modals).
+- **Defer**: Load 3rd-party scripts (Analytics) after hydration.
+
+## Rendering & Re-renders (P1)
+
+- **Isolation**: Move state down. Isolate heavy UI updates.
+- **Context Splitting**: Split Context into `StateContext` (Data) and `DispatchContext` (Actions) to prevent consumers from re-rendering just because they need a setter.
+- **Stability**: Use `useMemo` for passing objects/arrays to children to preserve referential equality checks (`React.memo`).
+- **Virtualization**: `react-window` for lists > 50 items.
+- **Content Visibility**: `content-visibility: auto` for off-screen CSS content.
+- **Static Hoisting**: Extract static objects/JSX outside component scope.
+- **Transitions**: `startTransition` for non-urgent UI updates.
+
+## Parallelization (P1)
+
+- **Web Workers**: Move heavy computation (Encryption, Image processing, Large Data Sorting) off the main thread using `Comlink` or `Worker`.
+
+## Server Performance (RSC) (P1)
+
+- **Caching**: `React.cache` for per-request deduplication.
+- **Serialization**: Minimize props passing to Client Components (only IDs/primitives).
+
+## Anti-Patterns
+
+- **No `export *`**: Breaks tree-shaking.
+- **No Sequential Await**: Causes waterfalls.
+- **No Inline Objects**: `style={{}}` breaks strict equality checks (if memoized).
+- **No Heavy Libs**: Avoid moment/lodash (use dayjs/radash).
+
+## Code
+
+```tsx
+// Parallel Fetching (Good)
+const [user, posts] = await Promise.all([getUser(), getPosts()]);
+
+// Bundle Optimized Import (Good)
+import { Button } from './components/Button'; // Not from './components'
+
+// Static Hoist (Good)
+const STATIC_CONFIG = { theme: 'dark' };
+function Component() {
+  return <div config={STATIC_CONFIG} />;
+}
+```

package/rules/react/performance/references/REFERENCE.md

@@ -0,0 +1,143 @@
+# React Performance Reference
+
+Advanced optimization techniques and profiling.
+
+## References
+
+- [**Profiling**](profiling.md) - React DevTools Profiler usage.
+- [**Bundle Analysis**](bundle-analysis.md) - Analyzing and reducing bundle size.
+
+## React DevTools Profiler
+
+```jsx
+// Wrap components to profile
+import { Profiler } from 'react';
+
+function onRenderCallback(
+  id, // component id
+  phase, // "mount" or "update"
+  actualDuration, // time spent rendering
+  baseDuration, // estimated time without memoization
+  startTime,
+  commitTime,
+  interactions
+) {
+  console.log(`${id} (${phase}) took ${actualDuration}ms`);
+}
+
+export function App() {
+  return (
+    <Profiler id="App" onRender={onRenderCallback}>
+      <Dashboard />
+    </Profiler>
+  );
+}
+```
+
+## Bundle Analysis
+
+```bash
+# Analyze bundle size
+npm install --save-dev webpack-bundle-analyzer
+
+# Add to webpack config or use with Vite
+npm run build -- --analyze
+```
+
+## Image Optimization
+
+```jsx
+// Lazy loading images
+function OptimizedImage({ src, alt }) {
+  return (
+    <img
+      src={src}
+      alt={alt}
+      loading="lazy"
+      decoding="async"
+    />
+  );
+}
+
+// Next.js Image component (automatic optimization)
+import Image from 'next/image';
+
+function Hero() {
+  return (
+    <Image
+      src="/hero.jpg"
+      alt="Hero"
+      width={1200}
+      height={600}
+      priority
+    />
+  );
+}
+```
+
+## Web Workers for Heavy Computation
+
+```jsx
+// worker.js
+self.addEventListener('message', (e) => {
+  const result = heavyComputation(e.data);
+  self.postMessage(result);
+});
+
+// Component
+import { useEffect, useState } from 'react';
+
+function HeavyComponent({ data }) {
+  const [result, setResult] = useState(null);
+
+  useEffect(() => {
+    const worker = new Worker(new URL('./worker.js', import.meta.url));
+    
+    worker.postMessage(data);
+    worker.onmessage = (e) => {
+      setResult(e.data);
+      worker.terminate();
+    };
+
+    return () => worker.terminate();
+  }, [data]);
+
+  return <div>{result}</div>;
+}
+```
+
+## Debouncing and Throttling
+
+```jsx
+import { useDeferredValue, useState } from 'react';
+
+// Built-in deferred value
+function SearchResults() {
+  const [query, setQuery] = useState('');
+  const deferredQuery = useDeferredValue(query);
+
+  return (
+    <>
+      <input value={query} onChange={e => setQuery(e.target.value)} />
+      <Results query={deferredQuery} />
+    </>
+  );
+}
+
+// Manual debounce
+import { useEffect, useState } from 'react';
+
+function useDebounce(value, delay) {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const handler = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+
+    return () => clearTimeout(handler);
+  }, [value, delay]);
+
+  return debouncedValue;
+}
+```

package/rules/react/security/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: React Security
+description: Security practices for React (XSS, Auth, Dependencies).
+metadata:
+  labels: [react, security, xss, auth]
+  triggers:
+    files: ['**/*.tsx', '**/*.jsx']
+    keywords: [dangerouslySetInnerHTML, token, auth, xss]
+---
+
+# React Security
+
+## **Priority: P0 (CRITICAL)**
+
+Preventing vulnerabilities in client-side apps.
+
+## Implementation Guidelines
+
+- **XSS**: Avoid `dangerouslySetInnerHTML`. Sanitize via `DOMPurify` if needed.
+- **URLs**: Validate `javascript:` protocols in user links.
+- **Auth**: Store tokens in `HttpOnly` cookies. Avoid `localStorage`.
+- **Deps**: Run `npm audit`. Pin versions.
+- **Secrets**: Server-side only. No `.env` secrets in build.
+- **CSP**: Strict Content-Security-Policy headers.
+
+## Anti-Patterns
+
+- **No `eval()`**: RCE risk.
+- **No Serialized State**: Don't inject JSON into DOM without escaping.
+- **No Client Logic for Permissions**: Backend must validate.
+
+## Code
+
+```tsx
+import DOMPurify from 'dompurify';
+
+// Safe HTML Injection
+function SafeHtml({ content }) {
+  const clean = DOMPurify.sanitize(content);
+  return <div dangerouslySetInnerHTML={{ __html: clean }} />;
+}
+
+// Bad Link Prevention
+const safeUrl = url.startsWith('javascript:') ? '#' : url;
+<a href={safeUrl}>Link</a>;
+```