usethishook 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Bump `version` in `package.json` in the same change as the notes below, then run
+**Actions → Publish npm** (manual). Create GitHub Release **vX.Y.Z** from the matching section.
+Do not publish from a push or tag.
+
+## [0.2.0] - 2026-09-12
+
+### Added
+
+- `useEventListener` — window / document / node / ref listener with a stable handler
+- `useTimeout` — one-shot delay (`null` pauses)
+- `useHover` — `{ ref, isHovered }`
+- `useKeyPress` — key held down; ignores editable fields
+- `usePreferredColorScheme` — OS `light` | `dark` via `matchMedia`
+- Playground **Home** control in the sidebar
+- Smooth-scroll to top when changing playground routes
+- Radix Scroll Area on the playground sidebar hook list
+
+## [0.1.1] - 2026-09-12
+
+### Changed
+
+- `repository` and `bugs` URLs use the camelCase GitHub repo `useThisHook`.
+- Playground GitHub Pages build uses relative asset URLs so `/useThisHook/` loads scripts.
+
+## [0.1.0] - 2026-09-12
+
+### Added
+
+- First public release of `usethishook` with state, browser, and app hooks.
+- Playground documentation with live previews and API reference.

package/README.md

@@ -1,5 +1,9 @@
 # useThisHook
 
+[![npm](https://img.shields.io/npm/v/usethishook.svg)](https://www.npmjs.com/package/usethishook)
+[![license](https://img.shields.io/npm/l/usethishook.svg)](LICENSE)
+[![CI](https://github.com/senthilkumar979/useThisHook/actions/workflows/ci.yml/badge.svg)](https://github.com/senthilkumar979/useThisHook/actions/workflows/ci.yml)
+
 **useThisHook** is an open-source TypeScript library of named React hooks for everyday UI, forms, lists, overlays, and browser APIs. Import only what you need — the package is tree-shakeable.
 
 The npm package name is lowercase: [`usethishook`](https://www.npmjs.com/package/usethishook).
@@ -8,7 +12,7 @@ The npm package name is lowercase: [`usethishook`](https://www.npmjs.com/package
 npm install usethishook
 ```
 
-**Peer dependency:** React 18 or later (React 19 is supported).
+**Peer dependencies:** React 18 or later, and **React DOM** 18 or later for confirm, prompt, overlay, and step-flow hooks (React 19 is supported).
 
 ## Why use it
 
@@ -19,17 +23,25 @@ npm install usethishook
 
 ## Documentation playground
 
+- Hosted: [usethishook.mentorbridge.in](https://usethishook.mentorbridge.in) (Vercel)
+- Mirror: [senthilkumar979.github.io/useThisHook](https://senthilkumar979.github.io/useThisHook/) (GitHub Pages)
+
 ```bash
 npm install
 npm run playground
 ```
 
-Open the URL Vite prints (usually `http://localhost:5173`).
+Open the URL Vite prints (usually `http://localhost:5173`). Light mode is the default; use the sun/moon icon at the top right to switch theme.
 
 - Home (`#/`): what the library is, install, and the hook index
 - Hook pages (`#/useToggle`, `#/useConfirm`, …): description, live preview, API, example
 
-See [`playground/README.md`](playground/README.md). Build a static site with `npm run playground:build` (output in `playground/dist`).
+See [`playground/README.md`](playground/README.md).
+
+- `npm run playground:build` — static site with `base: /` (Vercel / custom domain)
+- `npm run playground:build:pages` — same site with `base: /useThisHook/` for project GitHub Pages
+
+Output is `playground/dist`. Hash routes (`#/…`) work on Pages without extra rewrite rules. In the GitHub repo, set **Settings → Pages → Source** to **GitHub Actions**.
 
 ## Usage
 
@@ -46,9 +58,7 @@ export const SearchBox = () => {
       <button type="button" onClick={toggle}>
         {isOpen ? 'Hide' : 'Show'} search
       </button>
-      {isOpen && (
-        <input value={query} onChange={(event) => setQuery(event.target.value)} />
-      )}
+      {isOpen && <input value={query} onChange={(event) => setQuery(event.target.value)} />}
       <p>Searching for: {debouncedQuery}</p>
     </div>
   );
@@ -87,60 +97,73 @@ Playground paths are hash routes on the local docs app (for example `#/useToggle
 
 ### State
 
-| Hook | Purpose | Preview |
-| --- | --- | --- |
-| `useToggle` | Boolean with `toggle`, `setTrue`, `setFalse` | `#/useToggle` |
-| `useCounter` | Increment, decrement, reset | `#/useCounter` |
-| `useDisclosure` | Open / close / toggle for menus and dialogs | `#/useDisclosure` |
-| `useDebounce` | Debounce a rapidly changing value | `#/useDebounce` |
-| `usePrevious` | Previous render’s value | `#/usePrevious` |
-| `useInterval` | Declarative `setInterval` (`null` pauses) | `#/useInterval` |
-| `useCopyToClipboard` | Clipboard write + last copied text | `#/useCopyToClipboard` |
-| `useLocalStorage` | JSON state persisted in `localStorage` | `#/useLocalStorage` |
-| `useDocumentTitle` | Set `document.title` while mounted | `#/useDocumentTitle` |
+| Hook                 | Purpose                                      | Preview                |
+| -------------------- | -------------------------------------------- | ---------------------- |
+| `useToggle`          | Boolean with `toggle`, `setTrue`, `setFalse` | `#/useToggle`          |
+| `useCounter`         | Increment, decrement, reset                  | `#/useCounter`         |
+| `useDisclosure`      | Open / close / toggle for menus and dialogs  | `#/useDisclosure`      |
+| `useDebounce`        | Debounce a rapidly changing value            | `#/useDebounce`        |
+| `usePrevious`        | Previous render’s value                      | `#/usePrevious`        |
+| `useInterval`        | Declarative `setInterval` (`null` pauses)    | `#/useInterval`        |
+| `useCopyToClipboard` | Clipboard write + last copied text           | `#/useCopyToClipboard` |
+| `useLocalStorage`    | JSON state persisted in `localStorage`       | `#/useLocalStorage`    |
+| `useDocumentTitle`   | Set `document.title` while mounted           | `#/useDocumentTitle`   |
 
 ### Browser
 
-| Hook | Purpose | Preview |
-| --- | --- | --- |
-| `useOnlineStatus` | `navigator.onLine` plus online/offline events | `#/useOnlineStatus` |
-| `useMediaQuery` | Subscribe to a CSS media query | `#/useMediaQuery` |
-| `useWindowSize` | Viewport width and height | `#/useWindowSize` |
-| `useOnClickOutside` | Handler when the user presses outside a ref | `#/useOnClickOutside` |
-| `useOverlay` | Promise-based custom overlay | `#/useOverlay` |
-| `useStepFlow` | Multi-step wizard that resolves when finished | `#/useStepFlow` |
-| `useAsyncSelect` | Native file picker as a Promise | `#/useAsyncSelect` |
+| Hook                | Purpose                                       | Preview               |
+| ------------------- | --------------------------------------------- | --------------------- |
+| `useOnlineStatus`   | `navigator.onLine` plus online/offline events | `#/useOnlineStatus`   |
+| `useMediaQuery`     | Subscribe to a CSS media query                | `#/useMediaQuery`     |
+| `useWindowSize`     | Viewport width and height                     | `#/useWindowSize`     |
+| `useOnClickOutside` | Handler when the user presses outside a ref   | `#/useOnClickOutside` |
+| `useOverlay`        | Promise-based custom overlay                  | `#/useOverlay`        |
+| `useStepFlow`       | Multi-step wizard that resolves when finished | `#/useStepFlow`       |
+| `useAsyncSelect`            | Native file picker as a Promise                  | `#/useAsyncSelect`            |
+| `useEventListener`          | DOM / window listener with a stable handler      | `#/useEventListener`          |
+| `useTimeout`                | One-shot timer (`null` pauses)                   | `#/useTimeout`                |
+| `useHover`                  | Pointer over a ref                               | `#/useHover`                  |
+| `useKeyPress`               | Key held down (ignores inputs)                   | `#/useKeyPress`               |
+| `usePreferredColorScheme`   | OS `prefers-color-scheme`                        | `#/usePreferredColorScheme`   |
 
 ### App
 
-| Hook | Purpose | Preview |
-| --- | --- | --- |
-| `useStableCallback` | Stable function identity, always-latest body | `#/useStableCallback` |
-| `useOnChange` | Callback when a value changes, not on mount | `#/useOnChange` |
-| `useResetState` | Local state that resets when a source key changes | `#/useResetState` |
-| `useAsyncAction` | Pending / error / data around one async action | `#/useAsyncAction` |
-| `useDebouncedCallback` | Debounce calling a function | `#/useDebouncedCallback` |
-| `useFields` | Small form object, optional Zod-shaped schema | `#/useFields` |
-| `useList` | Insert, update, remove, reorder by `id` | `#/useList` |
-| `useSelection` | Single or multi select ids | `#/useSelection` |
-| `useSearchState` | URL search params as React state | `#/useSearchState` |
-| `useConfirm` | Await a yes/no dialog | `#/useConfirm` |
-| `usePrompt` | Await a string from a dialog | `#/usePrompt` |
-| `useControllableState` | Controlled and uncontrolled in one setter | `#/useControllableState` |
-| `useUnsavedChanges` | Tab-close warning and in-app leave confirm | `#/useUnsavedChanges` |
-| `useElementSize` | Element size via `ResizeObserver` | `#/useElementSize` |
-| `useInView` | Element vs viewport via `IntersectionObserver` | `#/useInView` |
-| `usePagination` | Page, offset, next/prev with clamping | `#/usePagination` |
+| Hook                   | Purpose                                           | Preview                  |
+| ---------------------- | ------------------------------------------------- | ------------------------ |
+| `useStableCallback`    | Stable function identity, always-latest body      | `#/useStableCallback`    |
+| `useOnChange`          | Callback when a value changes, not on mount       | `#/useOnChange`          |
+| `useResetState`        | Local state that resets when a source key changes | `#/useResetState`        |
+| `useAsyncAction`       | Pending / error / data around one async action    | `#/useAsyncAction`       |
+| `useDebouncedCallback` | Debounce calling a function                       | `#/useDebouncedCallback` |
+| `useFields`            | Small form object, optional Zod-shaped schema     | `#/useFields`            |
+| `useList`              | Insert, update, remove, reorder by `id`           | `#/useList`              |
+| `useSelection`         | Single or multi select ids                        | `#/useSelection`         |
+| `useSearchState`       | URL search params as React state                  | `#/useSearchState`       |
+| `useConfirm`           | Await a yes/no dialog                             | `#/useConfirm`           |
+| `usePrompt`            | Await a string from a dialog                      | `#/usePrompt`            |
+| `useControllableState` | Controlled and uncontrolled in one setter         | `#/useControllableState` |
+| `useUnsavedChanges`    | Tab-close warning and in-app leave confirm        | `#/useUnsavedChanges`    |
+| `useElementSize`       | Element size via `ResizeObserver`                 | `#/useElementSize`       |
+| `useInView`            | Element vs viewport via `IntersectionObserver`    | `#/useInView`            |
+| `usePagination`        | Page, offset, next/prev with clamping             | `#/usePagination`        |
+
+## Server rendering
+
+Hooks that read `window`, `document`, `navigator`, or observers are safe to _call_ on the server when they fall back (typical values: `false`, `{ width: 0, height: 0 }`, or an empty query). They subscribe after mount.
+
+- `useMediaQuery`, `useWindowSize`, `useOnlineStatus`, `useLocalStorage`, `useSearchState`, `useDocumentTitle`, `useOnClickOutside`, `useElementSize`, `useInView`, `useUnsavedChanges`, `useEventListener`, `useTimeout`, `useHover`, `useKeyPress`, and `usePreferredColorScheme` must not assume a browser until after hydration.
+- Confirm, prompt, overlay, and step-flow still need `render()` in the client tree.
 
 ## Scripts
 
-| Command | What it does |
-| --- | --- |
-| `npm test` | Vitest (jsdom) |
-| `npm run typecheck` | `tsc --noEmit` |
-| `npm run build` | ESM + CJS + types via tsup (`dist/`) |
-| `npm run playground` | Docs app |
-| `npm run playground:build` | Static playground |
+| Command                    | What it does                         |
+| -------------------------- | ------------------------------------ |
+| `npm test`                 | Vitest (jsdom)                       |
+| `npm run typecheck`        | Library + playground `tsc --noEmit`  |
+| `npm run lint`             | ESLint + Prettier check              |
+| `npm run build`            | ESM + CJS + types via tsup (`dist/`) |
+| `npm run playground`       | Docs app                             |
+| `npm run playground:build` | Static playground (`base: /`)        |
 
 `prepublishOnly` runs typecheck, tests, and build.
 
@@ -155,14 +178,29 @@ npm run playground
 
 Guidelines for adding a hook: [`CONTRIBUTING.md`](CONTRIBUTING.md).
 
-## Publish to npm
+## Publish
+
+**npm** is the install path for everyone: `npm install usethishook`. Publishing to the public registry is **manual only** — it does not run on push.
+
+1. Bump `version` in `package.json` and add a [`CHANGELOG.md`](CHANGELOG.md) section in the same commit.
+2. Add a repo secret named `NPM_TOKEN` (npm access token with publish rights). Publish stays **Actions → Publish npm → Run workflow** — never on push.
+3. After publish, link the npm package on the GitHub repo if it is not already connected.
+
+[`.github/workflows/npm-publish.yml`](.github/workflows/npm-publish.yml) runs `npm publish --access public`. `prepublishOnly` still typechecks, tests, and builds.
 
-1. Push the public GitHub repository.
-2. `npm login`
-3. Confirm the name is free: `npm view usethishook`
-4. `npm publish --access public`
+**GitHub Packages** is a second registry and also does not publish on push. It needs a scoped name (`@owner/package`). The committed `package.json` stays `usethishook`. [`.github/workflows/github-packages.yml`](.github/workflows/github-packages.yml) renames it to `@senthilkumar979/usethishook` only for that job.
 
-Later releases: `npm version patch|minor|major`, then publish again.
+**Actions → Publish GitHub Package → Run workflow**, or create a GitHub Release.
+
+Install from GitHub Packages (optional; still requires a GitHub token for the registry):
+
+```bash
+npm install @senthilkumar979/usethishook
+```
+
+```ini
+@senthilkumar979:registry=https://npm.pkg.github.com
+```
 
 ## License
 
@@ -183,4 +221,4 @@ The full legal text is in [`LICENSE`](LICENSE).
 - Website: [senthilkumar.mentorbridge.in](https://senthilkumar.mentorbridge.in)
 - LinkedIn: [linkedin.com/in/senthilk979](https://www.linkedin.com/in/senthilk979)
 
-Issues and ideas: [GitHub issues](https://github.com/senthilkumar979/usethishook/issues).
+Issues and ideas: [GitHub issues](https://github.com/senthilkumar979/useThisHook/issues).

package/dist/index.cjs

@@ -143,6 +143,90 @@ var useOnClickOutside = (ref, handler) => {
     };
   }, [handler, ref]);
 };
+function resolveTarget(target) {
+  if (target == null) return null;
+  if (typeof target === "object" && "current" in target) return target.current;
+  return target;
+}
+var useEventListener = (target, type, handler, options) => {
+  const handlerRef = react.useRef(handler);
+  handlerRef.current = handler;
+  const element = resolveTarget(target);
+  react.useEffect(() => {
+    if (typeof window === "undefined" || !element) return;
+    const listener = (event) => {
+      handlerRef.current(event);
+    };
+    element.addEventListener(type, listener, options);
+    return () => {
+      element.removeEventListener(type, listener, options);
+    };
+  }, [element, options, type]);
+};
+var useTimeout = (callback, delayMs) => {
+  const savedCallback = react.useRef(callback);
+  react.useEffect(() => {
+    savedCallback.current = callback;
+  }, [callback]);
+  react.useEffect(() => {
+    if (delayMs === null || typeof window === "undefined") return;
+    const timeoutId = window.setTimeout(() => {
+      savedCallback.current();
+    }, delayMs);
+    return () => {
+      window.clearTimeout(timeoutId);
+    };
+  }, [delayMs]);
+};
+var useHover = () => {
+  const ref = react.useRef(null);
+  const [isHovered, setIsHovered] = react.useState(false);
+  react.useEffect(() => {
+    const node = ref.current;
+    if (!node) return;
+    const handleEnter = () => setIsHovered(true);
+    const handleLeave = () => setIsHovered(false);
+    node.addEventListener("pointerenter", handleEnter);
+    node.addEventListener("pointerleave", handleLeave);
+    return () => {
+      node.removeEventListener("pointerenter", handleEnter);
+      node.removeEventListener("pointerleave", handleLeave);
+    };
+  }, []);
+  return { ref, isHovered };
+};
+function isEditableTarget(target) {
+  if (!(target instanceof HTMLElement)) return false;
+  const tag = target.tagName;
+  if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return true;
+  return target.isContentEditable;
+}
+var useKeyPress = (key) => {
+  const [isPressed, setIsPressed] = react.useState(false);
+  react.useEffect(() => {
+    if (typeof window === "undefined") return;
+    const handleDown = (event) => {
+      if (isEditableTarget(event.target)) return;
+      if (event.key === key) setIsPressed(true);
+    };
+    const handleUp = (event) => {
+      if (event.key === key) setIsPressed(false);
+    };
+    window.addEventListener("keydown", handleDown);
+    window.addEventListener("keyup", handleUp);
+    return () => {
+      window.removeEventListener("keydown", handleDown);
+      window.removeEventListener("keyup", handleUp);
+    };
+  }, [key]);
+  return isPressed;
+};
+
+// src/hooks/usePreferredColorScheme.ts
+var usePreferredColorScheme = () => {
+  const isDark = useMediaQuery("(prefers-color-scheme: dark)");
+  return isDark ? "dark" : "light";
+};
 var useCopyToClipboard = () => {
   const [copiedText, setCopiedText] = react.useState(null);
   const copy = react.useCallback(async (text) => {
@@ -233,9 +317,7 @@ var useStepFlow = (steps) => {
   const [currentStepIndex, setCurrentStepIndex] = react.useState(0);
   const [isActive, setIsActive] = react.useState(false);
   const resultsRef = react.useRef([]);
-  const resolverRef = react.useRef(
-    null
-  );
+  const resolverRef = react.useRef(null);
   const next = react.useCallback(() => {
     setIsActive(true);
     setCurrentStepIndex(0);
@@ -522,9 +604,12 @@ var useSelection = ({ mode = "multiple", initial = [] } = {}) => {
   const selectOnly = react.useCallback((id) => {
     setSelected([id]);
   }, []);
-  const selectAll = react.useCallback((ids) => {
-    setSelected(mode === "single" ? ids.slice(0, 1) : [...new Set(ids)]);
-  }, [mode]);
+  const selectAll = react.useCallback(
+    (ids) => {
+      setSelected(mode === "single" ? ids.slice(0, 1) : [...new Set(ids)]);
+    },
+    [mode]
+  );
   const clear = react.useCallback(() => {
     setSelected([]);
   }, []);
@@ -594,10 +679,19 @@ var panelStyle = {
   padding: "1.25rem",
   boxShadow: "0 24px 80px rgba(0,0,0,0.45)"
 };
-var DialogFrame = ({ title, children }) => /* @__PURE__ */ jsxRuntime.jsx("div", { style: backdropStyle, children: /* @__PURE__ */ jsxRuntime.jsxs("div", { role: "dialog", "aria-modal": "true", "aria-labelledby": "usethishook-dialog-title", style: panelStyle, children: [
-  /* @__PURE__ */ jsxRuntime.jsx("h2", { id: "usethishook-dialog-title", style: { margin: "0 0 0.75rem", fontSize: "1.05rem" }, children: title }),
-  children
-] }) });
+var DialogFrame = ({ title, children }) => /* @__PURE__ */ jsxRuntime.jsx("div", { style: backdropStyle, children: /* @__PURE__ */ jsxRuntime.jsxs(
+  "div",
+  {
+    role: "dialog",
+    "aria-modal": "true",
+    "aria-labelledby": "usethishook-dialog-title",
+    style: panelStyle,
+    children: [
+      /* @__PURE__ */ jsxRuntime.jsx("h2", { id: "usethishook-dialog-title", style: { margin: "0 0 0.75rem", fontSize: "1.05rem" }, children: title }),
+      children
+    ]
+  }
+) });
 var buttonRowStyle = { display: "flex", gap: "0.5rem", marginTop: "1rem" };
 var dialogButtonRowStyle = buttonRowStyle;
 var primaryButtonStyle = {
@@ -633,7 +727,10 @@ var ConfirmDialog = ({
         "button",
         {
           type: "button",
-          style: { ...primaryButtonStyle, background: danger ? "#e11d48" : primaryButtonStyle.background },
+          style: {
+            ...primaryButtonStyle,
+            background: danger ? "#e11d48" : primaryButtonStyle.background
+          },
           onClick: () => close(true),
           children: confirmLabel
         }
@@ -832,9 +929,12 @@ exports.useDebouncedCallback = useDebouncedCallback;
 exports.useDisclosure = useDisclosure;
 exports.useDocumentTitle = useDocumentTitle;
 exports.useElementSize = useElementSize;
+exports.useEventListener = useEventListener;
 exports.useFields = useFields;
+exports.useHover = useHover;
 exports.useInView = useInView;
 exports.useInterval = useInterval;
+exports.useKeyPress = useKeyPress;
 exports.useList = useList;
 exports.useLocalStorage = useLocalStorage;
 exports.useMediaQuery = useMediaQuery;
@@ -843,6 +943,7 @@ exports.useOnClickOutside = useOnClickOutside;
 exports.useOnlineStatus = useOnlineStatus;
 exports.useOverlay = useOverlay;
 exports.usePagination = usePagination;
+exports.usePreferredColorScheme = usePreferredColorScheme;
 exports.usePrevious = usePrevious;
 exports.usePrompt = usePrompt;
 exports.useResetState = useResetState;
@@ -850,6 +951,7 @@ exports.useSearchState = useSearchState;
 exports.useSelection = useSelection;
 exports.useStableCallback = useStableCallback;
 exports.useStepFlow = useStepFlow;
+exports.useTimeout = useTimeout;
 exports.useToggle = useToggle;
 exports.useUnsavedChanges = useUnsavedChanges;
 exports.useWindowSize = useWindowSize;