@ox0/hooks 0.2.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Erik Sturcke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,225 @@
+# @ox0/hooks
+
+Shared React hooks for ox0 applications. Every hook is SSR-safe unless noted.
+
+## Installation
+
+```bash
+pnpm add @ox0/hooks
+```
+
+## Hooks
+
+### State and control
+
+#### `useControllableState<T>(options)`
+
+Controlled/uncontrolled state bridge. Pass `value` + `onChange` for controlled mode; omit `value`
+for uncontrolled. When uncontrolled, internal state resets to `defaultValue` whenever `defaultValue`
+changes — pass stable primitives to avoid surprise resets.
+
+```ts
+const [val, setVal] = useControllableState({ defaultValue: "initial", value, onChange })
+```
+
+#### `useDisclosure(initialOpen?)`
+
+Boolean open/close state. Returns `{ isOpen, onOpen, onClose, onToggle }` with stable callbacks.
+
+```ts
+const { isOpen, onOpen, onClose } = useDisclosure()
+```
+
+---
+
+### Persistence
+
+All storage hooks require a `<StorageProvider scope={userId ?? null}>` ancestor. The scope string
+prefixes every key so different users sharing a browser do not mix data. Pass `scope={null}` to
+opt out of scoping.
+
+```tsx
+import { StorageProvider } from "@ox0/hooks"
+
+function App() {
+  return <StorageProvider scope={currentUserId}>{children}</StorageProvider>
+}
+```
+
+#### `usePersistentState(key, parser, options)`
+
+`localStorage`, tab-private. Changes are not visible in other open tabs.
+
+#### `usePersistentSharedState(key, parser, options)`
+
+`localStorage`, shared across tabs. Changes broadcast via `BroadcastChannel` and the `storage`
+event. All tabs with the same key stay in sync.
+
+#### `useSessionState(key, parser, options)`
+
+`sessionStorage`, tab-private.
+
+#### `useSessionSharedState(key, parser, options)`
+
+`sessionStorage`, shared within the tab (multiple hook instances on the same key sync via
+in-tab pub/sub).
+
+**Shared options:**
+
+```ts
+type StoredStateOptions<T> = {
+  defaultValue: T
+  version?: number // @default 1
+  migrate?: (value: unknown, fromVersion: number) => T
+}
+```
+
+Pass any object with a `.parse(unknown): T` method as the `parser` (Zod schemas work directly).
+Use `version` + `migrate` to transform stored data when the shape changes:
+
+```ts
+const [theme, setTheme] = usePersistentSharedState("ui:theme", ThemeSchema, {
+  defaultValue: "system",
+  version: 2,
+  migrate: (old, from) => (from === 1 ? "system" : "system"),
+})
+```
+
+---
+
+### Interaction
+
+#### `usePress(props)` — re-export from React Aria
+
+Cross-device press normalization for mouse, touch, keyboard (Space/Enter), and virtual pointer
+(screen reader). Handles iOS text-selection conflicts and scroll-gesture cancellation. Prefer this
+over raw `onClick` for custom interactive elements.
+
+#### `useLongPress(options)`
+
+Returns pointer event handlers that fire `onLongPress` after the pointer has been held for
+`delayMs` (default 500ms) without moving beyond `moveThresholdPx` (default 8px). Cancels on
+pointer up or excessive movement; suppresses the subsequent click.
+
+#### `useKeyDown(key, callback, options?)`
+
+Attaches a `keydown` listener to `window`. Modifier options: `ctrl`, `meta`, `shift`, `alt`.
+Pass `enabled: false` to disable without removing the hook call.
+
+---
+
+### DOM and browser
+
+#### `useContainerSize<T extends HTMLElement>()`
+
+Measures element content size via `ResizeObserver`. Returns `[ref, { width, height }]`. Attach
+the ref to the element to observe.
+
+```ts
+const [ref, { width }] = useContainerSize<HTMLDivElement>()
+```
+
+#### `useEventListener(type, listener, target?)`
+
+Attaches a typed event listener to `window` (default), a `Document`, `HTMLElement`, or a ref.
+The listener ref is always up to date — no stale-closure issues.
+
+#### `useHover<T extends HTMLElement>()`
+
+Returns `[ref, isHovered]`. Uses `pointerenter`/`pointerleave` events.
+
+---
+
+### Viewport and layout
+
+#### `useBreakpoint()`
+
+Tracks the current responsive breakpoint. Returns
+`{ breakpoint, isMobile, isTablet, isDesktop, isMobileOrTablet, isTabletOrDesktop }`.
+
+Breakpoints: mobile ≤ 767px, tablet ≤ 1023px, desktop > 1023px.
+
+#### `useWindowSize()`
+
+Tracks `{ width, height }` from `window.innerWidth`/`innerHeight`.
+
+#### `useViewport()`
+
+Tracks `{ visualViewportHeight, keyboardOpen }`. `keyboardOpen` is true when the on-screen
+keyboard reduces the visual viewport by more than 150px — useful for mobile layouts.
+
+---
+
+### Media queries and preferences
+
+#### `useMediaQuery(query)`
+
+Returns `true` when the CSS media query matches. Updates on change.
+
+#### `usePointerCoarse()`
+
+Returns `true` when the primary pointer is coarse (touch screen). Shorthand for
+`useMediaQuery("(pointer: coarse)")`.
+
+#### `usePrefersReducedMotion()`
+
+Returns `true` when the user has requested reduced motion.
+
+#### `useNavigatorOnline()`
+
+Returns `true` when the browser reports a network connection. Updates on `online`/`offline` events.
+
+---
+
+### OS and environment
+
+#### `useOS(override?)`
+
+Detects the runtime OS: `"mac" | "windows" | "linux" | "mobile"`. Useful for keyboard shortcut
+labels. Pass `override` to force a value in tests or demos.
+
+---
+
+### Timing
+
+#### `useDebouncedValue<T>(value, delay?)`
+
+Returns a debounced copy of `value` that only updates after `delay` ms (default 200ms) of no
+changes.
+
+#### `useInterval(callback, delay)`
+
+Calls `callback` every `delay` ms. Pass `delay = null` to pause. Callback ref is always current.
+
+#### `useTimeout(callback, delay)`
+
+Calls `callback` once after `delay` ms. Pass `delay = null` to disable. Callback ref is always
+current.
+
+#### `useNow(options?)`
+
+Returns the current `Date.now()` value, updating every `update` ms (default 1000ms). Pass
+`update: false` to get a stable snapshot.
+
+---
+
+### Utilities
+
+#### `usePrevious<T>(value)`
+
+Returns the value from the previous render. Returns `undefined` on the first render.
+
+#### `useCopyToClipboard(resetMs?)`
+
+Returns `{ copy: (text: string) => Promise<void>, copied: boolean }`. `copied` resets to `false`
+after `resetMs` ms (default 2000ms).
+
+#### `useBeforeUnloadWarning(enabled)`
+
+Shows the browser's native "leave page?" dialog when `enabled` is `true`. Use for unsaved-changes
+guards.
+
+#### `useDeferredPresence(options)`
+
+Manages show/hide lifecycle with entry delay, minimum visible time, and exit duration. Returns
+`"hidden" | "visible" | "exiting"`. Useful for tooltips, toasts, and animated presence.

package/dist/index.js

@@ -284,8 +284,12 @@ function useKeyDown(key, callback, { ctrl = false, meta = false, shift = false,
 const instanceId = `${Date.now()}-${Math.random().toString(16).slice(2)}`;
 const tabSubscribers = new Map();
 function tabSubscribe(key, fn) {
-    if (!tabSubscribers.has(key)) tabSubscribers.set(key, new Set());
-    tabSubscribers.get(key).add(fn);
+    let tabSet = tabSubscribers.get(key);
+    if (!tabSet) {
+        tabSet = new Set();
+        tabSubscribers.set(key, tabSet);
+    }
+    tabSet.add(fn);
     return ()=>{
         const set = tabSubscribers.get(key);
         set?.delete(fn);
@@ -308,8 +312,12 @@ function getChannel() {
     return broadcastChannel;
 }
 function crossTabSubscribe(key, fn) {
-    if (!crossTabSubscribers.has(key)) crossTabSubscribers.set(key, new Set());
-    crossTabSubscribers.get(key).add(fn);
+    let crossTabSet = crossTabSubscribers.get(key);
+    if (!crossTabSet) {
+        crossTabSet = new Set();
+        crossTabSubscribers.set(key, crossTabSet);
+    }
+    crossTabSet.add(fn);
     getChannel();
     return ()=>{
         const set = crossTabSubscribers.get(key);

package/dist/use-controllable-state.d.ts

@@ -3,5 +3,13 @@ export interface UseControllableStateOptions<TValue> {
     readonly onChange?: (value: TValue) => void;
     readonly value?: TValue;
 }
+/**
+ * Controlled/uncontrolled state bridge.
+ *
+ * Design decision: in uncontrolled mode, internal state resets to `defaultValue` whenever
+ * `defaultValue` changes. This is intentional — it supports controlled→uncontrolled transitions
+ * (e.g. when a parent stops passing `value`). Pass a stable primitive as `defaultValue` to avoid
+ * surprise resets.
+ */
 export declare function useControllableState<TValue>(options: UseControllableStateOptions<TValue>): [TValue, (nextValue: TValue) => void];
 //# sourceMappingURL=use-controllable-state.d.ts.map

package/dist/use-controllable-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-controllable-state.d.ts","sourceRoot":"","sources":["../src/use-controllable-state.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,2BAA2B,CAAC,MAAM;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EACzC,OAAO,EAAE,2BAA2B,CAAC,MAAM,CAAC,GAC3C,CAAC,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC,CAoBvC"}
+{"version":3,"file":"use-controllable-state.d.ts","sourceRoot":"","sources":["../src/use-controllable-state.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,2BAA2B,CAAC,MAAM;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EACzC,OAAO,EAAE,2BAA2B,CAAC,MAAM,CAAC,GAC3C,CAAC,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC,CAoBvC"}

package/dist/use-controllable-state.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=use-controllable-state.test.d.ts.map

package/dist/use-controllable-state.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-controllable-state.test.d.ts","sourceRoot":"","sources":["../src/use-controllable-state.test.ts"],"names":[],"mappings":""}

package/dist/use-debounced-value.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-debounced-value.d.ts","sourceRoot":"","sources":["../src/use-debounced-value.ts"],"names":[],"mappings":"AAEA,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,SAAM,GAAG,MAAM,CAc5E"}
+{"version":3,"file":"use-debounced-value.d.ts","sourceRoot":"","sources":["../src/use-debounced-value.ts"],"names":[],"mappings":"AAEA,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,SAAM,GAAG,MAAM,CAe5E"}

package/dist/use-debounced-value.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=use-debounced-value.test.d.ts.map

package/dist/use-debounced-value.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-debounced-value.test.d.ts","sourceRoot":"","sources":["../src/use-debounced-value.test.ts"],"names":[],"mappings":""}

package/dist/use-disclosure.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=use-disclosure.test.d.ts.map

package/dist/use-disclosure.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-disclosure.test.d.ts","sourceRoot":"","sources":["../src/use-disclosure.test.ts"],"names":[],"mappings":""}

package/dist/use-media-query.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=use-media-query.test.d.ts.map

package/dist/use-media-query.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-media-query.test.d.ts","sourceRoot":"","sources":["../src/use-media-query.test.ts"],"names":[],"mappings":""}

package/dist/use-stored-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-stored-state.d.ts","sourceRoot":"","sources":["../src/use-stored-state.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,2EAA2E;AAC3E,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI;IAAE,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,CAAA;CAAE,CAAA;AAExD,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI;IAClC,YAAY,EAAE,CAAC,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC,CAAA;CACrD,CAAA;AAkHD,wBAAgB,eAAe,CAAC,EAC9B,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,QAAQ,EAAE,SAAS,CAAA;CACpB,sGAEA;AAuID,iCAAiC;AACjC,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,uCAzHO,IAAI,EA4H1C;AAED,wCAAwC;AACxC,wBAAgB,wBAAwB,CAAC,CAAC,EACxC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,uCAlIO,IAAI,EAqI1C;AAED,mCAAmC;AACnC,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,uCAxI1D,IAAI,EA0I1C;AAED,yCAAyC;AACzC,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,uCAhJO,IAAI,EAmJ1C"}
+{"version":3,"file":"use-stored-state.d.ts","sourceRoot":"","sources":["../src/use-stored-state.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,2EAA2E;AAC3E,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI;IAAE,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,CAAA;CAAE,CAAA;AAExD,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI;IAClC,YAAY,EAAE,CAAC,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC,CAAA;CACrD,CAAA;AA0HD,wBAAgB,eAAe,CAAC,EAC9B,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,QAAQ,EAAE,SAAS,CAAA;CACpB,sGAEA;AAuID,iCAAiC;AACjC,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,uCAzHO,IAAI,EA4H1C;AAED,wCAAwC;AACxC,wBAAgB,wBAAwB,CAAC,CAAC,EACxC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,uCAlIO,IAAI,EAqI1C;AAED,mCAAmC;AACnC,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,uCAxI1D,IAAI,EA0I1C;AAED,yCAAyC;AACzC,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,uCAhJO,IAAI,EAmJ1C"}

package/dist/use-stored-state.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=use-stored-state.test.d.ts.map

package/dist/use-stored-state.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-stored-state.test.d.ts","sourceRoot":"","sources":["../src/use-stored-state.test.tsx"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@ox0/hooks",
-  "version": "0.2.0",
+  "version": "0.2.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/esturcke/ox0-platform.git",
+    "directory": "packages/hooks"
+  },
   "files": [
     "dist"
   ],