@niko464/react-kit 0.0.1 → 0.1.0

package/README.md

@@ -1,3 +1,88 @@
 # @niko464/react-kit
 
-Placeholder until v0.1. Plan: [Niko464/conventions#2](https://github.com/Niko464/conventions/issues/2).
+React hooks that replace `useEffect` in Niko464's TypeScript projects. [`@niko464/eslint-config`](../eslint-config)'s `react` block bans the effect hooks; these three hooks and the patterns in [Instead of an effect](#instead-of-an-effect) cover what effects were used for. None of the hooks takes a dependency list.
+
+## Install
+
+```bash
+pnpm add @niko464/react-kit
+```
+
+React 19.2 or later is required: the hooks use `useEffectEvent`.
+
+## `useMountEffect(fn)`
+
+`fn` runs once after mount. The cleanup it returns runs on unmount. In development, `<StrictMode>` mounts each component twice, so `fn` and its cleanup run one extra time there.
+
+```tsx
+import { useMountEffect } from '@niko464/react-kit';
+
+const PreviewFrame = ({ draft }: { draft: Draft }) => {
+  useMountEffect(() => {
+    window.parent.postMessage({ type: 'draft', draft }, '*');
+  });
+  return <Preview draft={draft} />;
+};
+
+<PreviewFrame key={message.id} draft={message.draft} />;
+```
+
+To run it again when a value changes, give the component a `key` with that value: React mounts a new one.
+
+## `useEventListener(target, type, handler, options?)`
+
+Listens to `type` on `target` while the component is mounted.
+
+- `target` is `window`, `document` or a ref to an element. A ref must point to its element when the component mounts.
+- The event type is checked against the target, so `'keydown'` on `window` gives a `KeyboardEvent`.
+- `handler` always sees the latest props and state, without re-subscribing.
+- `options` are `addEventListener`'s options. Changing `target`, `type` or `options` re-subscribes.
+
+```tsx
+import { useEventListener } from '@niko464/react-kit';
+import { useRef } from 'react';
+
+const Dialog = ({ onClose }: { onClose: () => void }) => {
+  useEventListener(window, 'keydown', (event) => {
+    if (event.key === 'Escape') onClose();
+  });
+  return <div role="dialog">…</div>;
+};
+
+const ColourPicker = ({ onPick }: { onPick: (colour: string) => void }) => {
+  const input = useRef<HTMLInputElement>(null);
+  useEventListener(input, 'change', () => {
+    if (input.current) onPick(input.current.value);
+  });
+  return <input ref={input} type="color" />;
+};
+```
+
+## `useInterval(fn, ms, { delay, enabled })`
+
+`fn` runs every `ms` milliseconds while `enabled`.
+
+- `delay` is the wait before the first run, in milliseconds. It defaults to `ms`.
+- `enabled` defaults to `true`. When it turns `false`, the interval stops.
+- Changing `ms`, `delay` or `enabled` restarts the interval from the beginning.
+- `fn` always sees the latest props and state. Changing it does not restart the interval.
+
+```tsx
+import { useInterval } from '@niko464/react-kit';
+import { useState } from 'react';
+
+const Slideshow = ({ photos, paused }: { photos: Photo[]; paused: boolean }) => {
+  const [index, setIndex] = useState(0);
+  useInterval(() => setIndex((index + 1) % photos.length), 4000, { enabled: !paused });
+  return <img src={photos[index]?.url} alt="" />;
+};
+```
+
+## Instead of an effect
+
+| To                                       | Use                                                                                                    |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| Start over when a value changes          | A `key` with that value, so React mounts a new component                                               |
+| Measure, place or set up a DOM node      | A ref callback: `<img ref={(node) => place(node)} />`, which may return a cleanup                      |
+| Keep a value in sync with props or state | Derive it during render: `const total = items.reduce(…)`, not a state that an effect updates           |
+| Animate                                  | [Motion](https://motion.dev): `<motion.div animate={{ x }} />`, its `useSpring`, and `drag` for swipes |

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { useEventListener } from './use-event-listener.ts';
+export { useInterval, type IntervalOptions } from './use-interval.ts';
+export { useMountEffect } from './use-mount-effect.ts';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { useEventListener } from "./use-event-listener.js";
+export { useInterval } from "./use-interval.js";
+export { useMountEffect } from "./use-mount-effect.js";

package/dist/use-event-listener.d.ts

@@ -0,0 +1,6 @@
+import { type RefObject } from 'react';
+type ListenerOptions = boolean | AddEventListenerOptions;
+export declare function useEventListener<Type extends keyof WindowEventMap>(target: Window, type: Type, handler: (event: WindowEventMap[Type]) => void, options?: ListenerOptions): void;
+export declare function useEventListener<Type extends keyof DocumentEventMap>(target: Document, type: Type, handler: (event: DocumentEventMap[Type]) => void, options?: ListenerOptions): void;
+export declare function useEventListener<Type extends keyof HTMLElementEventMap>(target: RefObject<HTMLElement | null>, type: Type, handler: (event: HTMLElementEventMap[Type]) => void, options?: ListenerOptions): void;
+export {};

package/dist/use-event-listener.js

@@ -0,0 +1,18 @@
+import { useEffect, useEffectEvent } from 'react';
+export function useEventListener(target, type, handler, options) {
+    const onEvent = useEffectEvent(handler);
+    const { capture = false, once = false, passive, signal, } = typeof options === 'boolean' ? { capture: options } : (options ?? {});
+    useEffect(() => {
+        const element = 'addEventListener' in target ? target : target.current;
+        if (element === null)
+            return;
+        const listener = (event) => onEvent(event);
+        const listenerOptions = { capture, once };
+        if (passive !== undefined)
+            listenerOptions.passive = passive;
+        if (signal !== undefined)
+            listenerOptions.signal = signal;
+        element.addEventListener(type, listener, listenerOptions);
+        return () => element.removeEventListener(type, listener, { capture });
+    }, [target, type, capture, once, passive, signal]);
+}

package/dist/use-interval.d.ts

@@ -0,0 +1,5 @@
+export type IntervalOptions = {
+    delay?: number;
+    enabled?: boolean;
+};
+export declare const useInterval: (fn: () => void, ms: number, { delay, enabled }?: IntervalOptions) => void;

package/dist/use-interval.js

@@ -0,0 +1,17 @@
+import { useEffect, useEffectEvent } from 'react';
+export const useInterval = (fn, ms, { delay = ms, enabled = true } = {}) => {
+    const tick = useEffectEvent(fn);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        let intervalId;
+        const timeoutId = setTimeout(() => {
+            tick();
+            intervalId = setInterval(() => tick(), ms);
+        }, delay);
+        return () => {
+            clearTimeout(timeoutId);
+            clearInterval(intervalId);
+        };
+    }, [ms, delay, enabled]);
+};

package/dist/use-mount-effect.d.ts

@@ -0,0 +1,2 @@
+import { type EffectCallback } from 'react';
+export declare const useMountEffect: (fn: EffectCallback) => void;

package/dist/use-mount-effect.js

@@ -0,0 +1,4 @@
+import { useEffect } from 'react';
+export const useMountEffect = (fn) => {
+    useEffect(fn, []);
+};

package/package.json

@@ -1,7 +1,37 @@
 {
   "name": "@niko464/react-kit",
-  "version": "0.0.1",
-  "description": "Placeholder until v0.1: see https://github.com/Niko464/conventions/issues/2",
-  "repository": { "type": "git", "url": "git+https://github.com/Niko464/conventions.git", "directory": "packages/react-kit" },
-  "license": "MIT"
-}
+  "version": "0.1.0",
+  "description": "React hooks that replace useEffect: useMountEffect, useEventListener and useInterval",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Niko464/conventions.git",
+    "directory": "packages/react-kit"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": "^19.2.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "10.4.2",
+    "@testing-library/react": "16.3.3",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "jsdom": "30.1.2",
+    "react": "19.3.0",
+    "react-dom": "19.3.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "test": "vitest run"
+  }
+}