@vezham/hooks 26.0.3 → 26.2.0

package/README.md

@@ -1 +1,48 @@
 # @vezham/hooks
+
+## useLocalStore
+
+```tsx
+import { useLocalStore } from '@vezham/hooks'
+
+const DEFAULTS = { sounds: true }
+const Preferences = () => {
+  const { value, setValue, reset, isReady, isSaved, error } = useLocalStore(
+    'my-app:preferences:v1',
+    DEFAULTS,
+    { debounceMs: 150 }
+  )
+  // Use setValue(next) or setValue(current => next).
+}
+```
+
+Provide a stable default and an optional `parse(unknown)` function to validate
+or migrate stored JSON. One key represents one schema. Reads start after mount,
+so static/prerendered HTML has a deterministic initial value. Failed reads and
+writes retain a usable in-memory value and expose `error`/`isSaved`. Defaults
+are not saved during hydration; successful parser migrations are persisted.
+
+Updates notify consumers in the current document and listen to `storage`
+events from other tabs. Cross-tab conflicts use the latest storage event.
+`reset()` removes only this key. Debounced writes flush on pagehide and final
+unsubscribe; `flush()` can explicitly retry a failed write. Scope keys by host,
+workspace, and user where needed. Do not store credentials.
+
+## useCopyToClipboard
+
+```tsx
+import { useCopyToClipboard } from '@vezham/hooks'
+
+const CopyButton = ({ text }: { text: string }) => {
+  const { copy, isCopied, isUnavailable } = useCopyToClipboard()
+  return (
+    <button onClick={() => void copy(text)}>
+      {isCopied ? 'Copied' : isUnavailable ? 'Copy unavailable' : 'Copy'}
+    </button>
+  )
+}
+```
+
+Uses the Clipboard API when available and falls back to a temporary selection for
+restricted origins. The hook exposes the last copy result as `status`, `isCopied`,
+and `isUnavailable`.

package/dist/index.d.ts

@@ -1,2 +1,5 @@
+export { AppContext, useApp, type AppIdentity } from './lib/use-app';
 export { CommandContext, useCommand } from './lib/use-command';
+export { useLocalStore, type LocalStoreOptions } from './lib/use-local-store';
+export { useCopyToClipboard, type CopyToClipboardStatus } from './lib/use-copy-to-clipboard';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAA;AACpE,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAC9D,OAAO,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAC7E,OAAO,EACL,kBAAkB,EAClB,KAAK,qBAAqB,EAC3B,MAAM,6BAA6B,CAAA"}

package/dist/index.js

@@ -1,2 +1,5 @@
-import { CommandContext, useCommand } from "./lib/use-command.js";
-export { CommandContext, useCommand };
+import { AppContext, useApp } from "./lib/use-app/index.js";
+import { CommandContext, useCommand } from "./lib/use-command/index.js";
+import { useLocalStore } from "./lib/use-local-store/index.js";
+import { useCopyToClipboard } from "./lib/use-copy-to-clipboard/index.js";
+export { AppContext, CommandContext, useApp, useCommand, useCopyToClipboard, useLocalStore };

package/dist/lib/use-app/index.d.ts

@@ -0,0 +1,10 @@
+export interface AppIdentity {
+    readonly id: string;
+    readonly name: string;
+    readonly version: string;
+    readonly environment: string;
+    readonly runtime: string;
+}
+export declare const AppContext: import("react").Context<AppIdentity | undefined>;
+export declare const useApp: () => AppIdentity | undefined;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/use-app/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/use-app/index.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,eAAO,MAAM,UAAU,kDAAoD,CAAA;AAE3E,eAAO,MAAM,MAAM,+BAA+B,CAAA"}

package/dist/lib/use-app/index.js

@@ -0,0 +1,6 @@
+import { createContext, useContext } from "react";
+//#region src/lib/use-app/index.ts
+var AppContext = createContext(void 0);
+var useApp = () => useContext(AppContext);
+//#endregion
+export { AppContext, useApp };

package/dist/lib/{use-command.d.ts → use-command/index.d.ts}

@@ -7,4 +7,4 @@ interface CommandContextValue {
 export declare const CommandContext: import("react").Context<CommandContextValue | null>;
 export declare const useCommand: () => CommandContextValue;
 export {};
-//# sourceMappingURL=use-command.d.ts.map
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/use-command/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/use-command/index.ts"],"names":[],"mappings":"AAEA,UAAU,mBAAmB;IAC3B,MAAM,EAAE,OAAO,CAAA;IACf,WAAW,EAAE,MAAM,IAAI,CAAA;IACvB,YAAY,EAAE,MAAM,IAAI,CAAA;IACxB,aAAa,EAAE,MAAM,IAAI,CAAA;CAC1B;AAED,eAAO,MAAM,cAAc,qDAAkD,CAAA;AAE7E,eAAO,MAAM,UAAU,2BAQtB,CAAA"}

package/dist/lib/{use-command.js → use-command/index.js}

@@ -1,5 +1,5 @@
 import { createContext, useContext } from "react";
-//#region src/lib/use-command.ts
+//#region src/lib/use-command/index.ts
 var CommandContext = createContext(null);
 var useCommand = () => {
 	const context = useContext(CommandContext);

package/dist/lib/use-copy-to-clipboard/index.d.ts

@@ -0,0 +1,8 @@
+export type CopyToClipboardStatus = 'idle' | 'copied' | 'unavailable';
+export declare const useCopyToClipboard: () => {
+    copy: (text: string) => Promise<boolean>;
+    status: CopyToClipboardStatus;
+    isCopied: boolean;
+    isUnavailable: boolean;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/use-copy-to-clipboard/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/use-copy-to-clipboard/index.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,QAAQ,GAAG,aAAa,CAAA;AAErE,eAAO,MAAM,kBAAkB;iBAES,MAAM;;;;CAiB7C,CAAA"}

package/dist/lib/use-copy-to-clipboard/index.js

@@ -0,0 +1,23 @@
+import { writeClipboardText } from "./write-clipboard-text.js";
+import { useCallback, useState } from "react";
+//#region src/lib/use-copy-to-clipboard/index.ts
+var useCopyToClipboard = () => {
+	const [status, setStatus] = useState("idle");
+	return {
+		copy: useCallback(async (text) => {
+			try {
+				await writeClipboardText(text);
+				setStatus("copied");
+				return true;
+			} catch {
+				setStatus("unavailable");
+				return false;
+			}
+		}, []),
+		status,
+		isCopied: status === "copied",
+		isUnavailable: status === "unavailable"
+	};
+};
+//#endregion
+export { useCopyToClipboard };

package/dist/lib/use-copy-to-clipboard/write-clipboard-text.d.ts

@@ -0,0 +1,2 @@
+export declare const writeClipboardText: (text: string) => Promise<void>;
+//# sourceMappingURL=write-clipboard-text.d.ts.map

package/dist/lib/use-copy-to-clipboard/write-clipboard-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-clipboard-text.d.ts","sourceRoot":"","sources":["../../../src/lib/use-copy-to-clipboard/write-clipboard-text.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,GAAU,MAAM,MAAM,kBAkCpD,CAAA"}

package/dist/lib/use-copy-to-clipboard/write-clipboard-text.js

@@ -0,0 +1,26 @@
+//#region src/lib/use-copy-to-clipboard/write-clipboard-text.ts
+var writeClipboardText = async (text) => {
+	if (typeof navigator !== "undefined" && typeof navigator.clipboard?.writeText === "function") try {
+		await navigator.clipboard.writeText(text);
+		return;
+	} catch {}
+	if (typeof document === "undefined" || !document.body) throw new Error("Clipboard copy is unavailable");
+	const input = document.createElement("textarea");
+	input.value = text;
+	input.setAttribute("readonly", "");
+	input.setAttribute("aria-hidden", "true");
+	input.tabIndex = -1;
+	input.style.position = "fixed";
+	input.style.top = "0";
+	input.style.left = "-9999px";
+	input.style.fontSize = "16px";
+	document.body.appendChild(input);
+	input.focus();
+	input.select();
+	input.setSelectionRange(0, text.length);
+	const copied = document.execCommand("copy");
+	input.remove();
+	if (!copied) throw new Error("Clipboard copy is unavailable");
+};
+//#endregion
+export { writeClipboardText };

package/dist/lib/use-local-store/index.d.ts

@@ -0,0 +1,12 @@
+import type { LocalStoreOptions } from './local-store';
+export declare const useLocalStore: <T>(key: string, initialValue: T, options?: LocalStoreOptions<T>) => {
+    setValue: (update: T | ((current: T) => T)) => void;
+    reset: () => void;
+    flush: () => void;
+    value: T;
+    isReady: boolean;
+    isSaved: boolean;
+    error: unknown;
+};
+export type { LocalStoreOptions } from './local-store';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/use-local-store/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/use-local-store/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAItD,eAAO,MAAM,aAAa,GAAI,CAAC,EAC7B,KAAK,MAAM,EACX,cAAc,CAAC,EACf,UAAS,iBAAiB,CAAC,CAAC,CAAM;;;;;;;;CAkBnC,CAAA;AAED,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA"}

package/dist/lib/use-local-store/index.js

@@ -0,0 +1,23 @@
+import { getLocalStore } from "./local-store.js";
+import { useMemo, useSyncExternalStore } from "react";
+//#region src/lib/use-local-store/index.ts
+var useLocalStore = (key, initialValue, options = {}) => {
+	const { parse, debounceMs } = options;
+	const store = useMemo(() => getLocalStore(key, initialValue, {
+		parse,
+		debounceMs
+	}), [
+		key,
+		initialValue,
+		parse,
+		debounceMs
+	]);
+	return {
+		...useSyncExternalStore(store.subscribe, store.getSnapshot, store.getInitialSnapshot),
+		setValue: store.setValue,
+		reset: store.reset,
+		flush: store.flush
+	};
+};
+//#endregion
+export { useLocalStore };

package/dist/lib/use-local-store/local-store.d.ts

@@ -0,0 +1,20 @@
+export interface LocalStoreOptions<T> {
+    parse?: (value: unknown) => T;
+    debounceMs?: number;
+}
+interface Snapshot<T> {
+    value: T;
+    isReady: boolean;
+    isSaved: boolean;
+    error: unknown;
+}
+export declare const getLocalStore: <T>(key: string, initialValue: T, options: LocalStoreOptions<T>) => {
+    getSnapshot: () => Snapshot<T>;
+    getInitialSnapshot: () => Snapshot<T>;
+    setValue: (update: T | ((current: T) => T)) => void;
+    reset: () => void;
+    flush: () => void;
+    subscribe: (listener: () => void) => () => void;
+};
+export {};
+//# sourceMappingURL=local-store.d.ts.map

package/dist/lib/use-local-store/local-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-store.d.ts","sourceRoot":"","sources":["../../../src/lib/use-local-store/local-store.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,CAAA;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,UAAU,QAAQ,CAAC,CAAC;IAClB,KAAK,EAAE,CAAC,CAAA;IACR,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;CACf;AAsHD,eAAO,MAAM,aAAa,GAAI,CAAC,EAC7B,KAAK,MAAM,EACX,cAAc,CAAC,EACf,SAAS,iBAAiB,CAAC,CAAC,CAAC;;;;;;gCA5BC,IAAI;CAmCnC,CAAA"}

package/dist/lib/use-local-store/local-store.js

@@ -0,0 +1,141 @@
+//#region src/lib/use-local-store/local-store.ts
+var createLocalStore = (key, initialValue, { parse, debounceMs = 0 }) => {
+	const initial = {
+		value: initialValue,
+		isReady: false,
+		isSaved: true,
+		error: null
+	};
+	let snapshot = initial;
+	let dirty = false;
+	let timer;
+	const listeners = /* @__PURE__ */ new Set();
+	const emit = () => listeners.forEach((listener) => listener());
+	const cancel = () => {
+		clearTimeout(timer);
+		timer = void 0;
+	};
+	const flush = () => {
+		cancel();
+		if (!dirty || typeof window === "undefined") return;
+		try {
+			window.localStorage.setItem(key, JSON.stringify(snapshot.value));
+			dirty = false;
+			snapshot = {
+				...snapshot,
+				isSaved: true,
+				error: null
+			};
+		} catch (error) {
+			snapshot = {
+				...snapshot,
+				isSaved: false,
+				error
+			};
+		}
+		emit();
+	};
+	const read = () => {
+		try {
+			const raw = window.localStorage.getItem(key);
+			const decoded = raw === null ? initialValue : JSON.parse(raw);
+			const value = raw === null ? initialValue : parse ? parse(decoded) : decoded;
+			snapshot = {
+				value,
+				isReady: true,
+				isSaved: true,
+				error: null
+			};
+			if (raw !== null && parse && JSON.stringify(value) !== raw) {
+				dirty = true;
+				flush();
+			}
+		} catch (error) {
+			snapshot = {
+				value: initialValue,
+				isReady: true,
+				isSaved: false,
+				error
+			};
+		}
+		emit();
+	};
+	const onStorage = (event) => {
+		if (event.key !== null && event.key !== key) return;
+		if (event.storageArea && event.storageArea !== window.localStorage) return;
+		cancel();
+		dirty = false;
+		read();
+	};
+	const setValue = (update) => {
+		if (typeof window === "undefined") return;
+		if (!snapshot.isReady) read();
+		snapshot = {
+			value: typeof update === "function" ? update(snapshot.value) : update,
+			isReady: true,
+			isSaved: false,
+			error: null
+		};
+		dirty = true;
+		emit();
+		cancel();
+		if (debounceMs > 0) timer = setTimeout(flush, debounceMs);
+		else flush();
+	};
+	const reset = () => {
+		cancel();
+		dirty = false;
+		snapshot = {
+			value: initialValue,
+			isReady: true,
+			isSaved: true,
+			error: null
+		};
+		try {
+			window.localStorage.removeItem(key);
+		} catch (error) {
+			snapshot = {
+				...snapshot,
+				isSaved: false,
+				error
+			};
+		}
+		emit();
+	};
+	const store = {
+		getSnapshot: () => snapshot,
+		getInitialSnapshot: () => initial,
+		setValue,
+		reset,
+		flush,
+		subscribe: (listener) => {
+			const first = listeners.size === 0;
+			listeners.add(listener);
+			if (first) {
+				stores.set(key, store);
+				if (!dirty) read();
+				window.addEventListener("storage", onStorage);
+				window.addEventListener("pagehide", flush);
+			}
+			return () => {
+				listeners.delete(listener);
+				if (listeners.size) return;
+				flush();
+				window.removeEventListener("storage", onStorage);
+				window.removeEventListener("pagehide", flush);
+				if (stores.get(key) === store) stores.delete(key);
+			};
+		}
+	};
+	return store;
+};
+var stores = /* @__PURE__ */ new Map();
+var getLocalStore = (key, initialValue, options) => {
+	const existing = stores.get(key);
+	if (existing) return existing;
+	const store = createLocalStore(key, initialValue, options);
+	stores.set(key, store);
+	return store;
+};
+//#endregion
+export { getLocalStore };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vezham/hooks",
-  "version": "26.0.3",
+  "version": "26.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vezham/vx-fe-pkgs.git",

package/dist/lib/use-command.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-command.d.ts","sourceRoot":"","sources":["../../src/lib/use-command.ts"],"names":[],"mappings":"AAEA,UAAU,mBAAmB;IAC3B,MAAM,EAAE,OAAO,CAAA;IACf,WAAW,EAAE,MAAM,IAAI,CAAA;IACvB,YAAY,EAAE,MAAM,IAAI,CAAA;IACxB,aAAa,EAAE,MAAM,IAAI,CAAA;CAC1B;AAED,eAAO,MAAM,cAAc,qDAAkD,CAAA;AAE7E,eAAO,MAAM,UAAU,2BAQtB,CAAA"}