@usels/core 0.0.1

package/dist/shared/normalizeTargets/index.js

@@ -0,0 +1,36 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var normalizeTargets_exports = {};
+__export(normalizeTargets_exports, {
+  normalizeTargets: () => normalizeTargets
+});
+module.exports = __toCommonJS(normalizeTargets_exports);
+var import_useRef = require("../../elements/useRef$");
+function normalizeTargets(target) {
+  if (target == null) return [];
+  const arr = Array.isArray(target) ? target : [target];
+  return arr.map((t) => {
+    return (0, import_useRef.getElement)(t);
+  }).filter((el) => el != null);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  normalizeTargets
+});
+//# sourceMappingURL=index.js.map

package/dist/shared/normalizeTargets/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/shared/normalizeTargets/index.ts"],"sourcesContent":["import { getElement, type MaybeElement } from \"../../elements/useRef$\";\n\n/**\n * Normalizes one or more observable-element targets into a plain Element[].\n *\n * - `Ref$<T>` — calls `.get()` and unwraps the OpaqueObject via `.valueOf()`\n * - `Observable<OpaqueObject<Element> | null>` — calls `.get()` and unwraps via `.valueOf()`\n * - `Document` / `Window` — filtered out (not an Element, handled by callers)\n * - `null` — filtered out\n *\n * When called inside `useObserve`, reading `.get()` registers observable\n * dependencies so the observer re-fires when a tracked target changes.\n *\n * Currently shared by useResizeObserver.\n * useIntersectionObserver, useMutationObserver will use this once implemented.\n */\nexport function normalizeTargets(\n  target?: MaybeElement | MaybeElement[],\n): Element[] {\n  if (target == null) return [];\n  const arr = Array.isArray(target) ? target : [target];\n  return arr\n    .map((t) => {\n      return getElement(t) as any;\n    })\n    .filter((el): el is Element => el != null);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,oBAA8C;AAgBvC,SAAS,iBACd,QACW;AACX,MAAI,UAAU,KAAM,QAAO,CAAC;AAC5B,QAAM,MAAM,MAAM,QAAQ,MAAM,IAAI,SAAS,CAAC,MAAM;AACpD,SAAO,IACJ,IAAI,CAAC,MAAM;AACV,eAAO,0BAAW,CAAC;AAAA,EACrB,CAAC,EACA,OAAO,CAAC,OAAsB,MAAM,IAAI;AAC7C;","names":[]}

package/dist/shared/normalizeTargets/index.mjs

@@ -0,0 +1,12 @@
+import { getElement } from "../../elements/useRef$";
+function normalizeTargets(target) {
+  if (target == null) return [];
+  const arr = Array.isArray(target) ? target : [target];
+  return arr.map((t) => {
+    return getElement(t);
+  }).filter((el) => el != null);
+}
+export {
+  normalizeTargets
+};
+//# sourceMappingURL=index.mjs.map

package/dist/shared/normalizeTargets/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/shared/normalizeTargets/index.ts"],"sourcesContent":["import { getElement, type MaybeElement } from \"../../elements/useRef$\";\n\n/**\n * Normalizes one or more observable-element targets into a plain Element[].\n *\n * - `Ref$<T>` — calls `.get()` and unwraps the OpaqueObject via `.valueOf()`\n * - `Observable<OpaqueObject<Element> | null>` — calls `.get()` and unwraps via `.valueOf()`\n * - `Document` / `Window` — filtered out (not an Element, handled by callers)\n * - `null` — filtered out\n *\n * When called inside `useObserve`, reading `.get()` registers observable\n * dependencies so the observer re-fires when a tracked target changes.\n *\n * Currently shared by useResizeObserver.\n * useIntersectionObserver, useMutationObserver will use this once implemented.\n */\nexport function normalizeTargets(\n  target?: MaybeElement | MaybeElement[],\n): Element[] {\n  if (target == null) return [];\n  const arr = Array.isArray(target) ? target : [target];\n  return arr\n    .map((t) => {\n      return getElement(t) as any;\n    })\n    .filter((el): el is Element => el != null);\n}\n"],"mappings":"AAAA,SAAS,kBAAqC;AAgBvC,SAAS,iBACd,QACW;AACX,MAAI,UAAU,KAAM,QAAO,CAAC;AAC5B,QAAM,MAAM,MAAM,QAAQ,MAAM,IAAI,SAAS,CAAC,MAAM;AACpD,SAAO,IACJ,IAAI,CAAC,MAAM;AACV,WAAO,WAAW,CAAC;AAAA,EACrB,CAAC,EACA,OAAO,CAAC,OAAsB,MAAM,IAAI;AAC7C;","names":[]}

package/dist/shared/utils.d.mts

@@ -0,0 +1,15 @@
+declare const isClient: boolean;
+declare const noop: () => void;
+declare const clamp: (n: number, min: number, max: number) => number;
+declare const isDef: <T>(val?: T) => val is T;
+declare const notNullish: <T>(val?: T | null) => val is T;
+declare const isObject: (val: unknown) => val is object;
+declare const isIOS: boolean;
+declare function toArray<T>(v: T | T[]): T[];
+declare function objectPick<O extends object, T extends keyof O>(obj: O, keys: T[]): Pick<O, T>;
+declare function objectOmit<O extends object, T extends keyof O>(obj: O, keys: T[]): Omit<O, T>;
+declare function promiseTimeout(ms: number, throwOnTimeout?: boolean): Promise<void>;
+declare function increaseWithUnit(target: number, delta: number): number;
+declare function increaseWithUnit(target: string, delta: number): string;
+
+export { clamp, increaseWithUnit, isClient, isDef, isIOS, isObject, noop, notNullish, objectOmit, objectPick, promiseTimeout, toArray };

package/dist/shared/utils.d.ts

@@ -0,0 +1,15 @@
+declare const isClient: boolean;
+declare const noop: () => void;
+declare const clamp: (n: number, min: number, max: number) => number;
+declare const isDef: <T>(val?: T) => val is T;
+declare const notNullish: <T>(val?: T | null) => val is T;
+declare const isObject: (val: unknown) => val is object;
+declare const isIOS: boolean;
+declare function toArray<T>(v: T | T[]): T[];
+declare function objectPick<O extends object, T extends keyof O>(obj: O, keys: T[]): Pick<O, T>;
+declare function objectOmit<O extends object, T extends keyof O>(obj: O, keys: T[]): Omit<O, T>;
+declare function promiseTimeout(ms: number, throwOnTimeout?: boolean): Promise<void>;
+declare function increaseWithUnit(target: number, delta: number): number;
+declare function increaseWithUnit(target: string, delta: number): string;
+
+export { clamp, increaseWithUnit, isClient, isDef, isIOS, isObject, noop, notNullish, objectOmit, objectPick, promiseTimeout, toArray };

package/dist/shared/utils.js

@@ -0,0 +1,87 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var utils_exports = {};
+__export(utils_exports, {
+  clamp: () => clamp,
+  increaseWithUnit: () => increaseWithUnit,
+  isClient: () => isClient,
+  isDef: () => isDef,
+  isIOS: () => isIOS,
+  isObject: () => isObject,
+  noop: () => noop,
+  notNullish: () => notNullish,
+  objectOmit: () => objectOmit,
+  objectPick: () => objectPick,
+  promiseTimeout: () => promiseTimeout,
+  toArray: () => toArray
+});
+module.exports = __toCommonJS(utils_exports);
+const isClient = typeof window !== "undefined" && typeof document !== "undefined";
+const noop = () => {
+};
+const clamp = (n, min, max) => Math.min(max, Math.max(min, n));
+const isDef = (val) => typeof val !== "undefined";
+const notNullish = (val) => val != null;
+const isObject = (val) => Object.prototype.toString.call(val) === "[object Object]";
+const isIOS = isClient && /iPad|iPhone|iPod/.test(navigator.userAgent) && !window.MSStream;
+function toArray(v) {
+  return Array.isArray(v) ? v : [v];
+}
+function objectPick(obj, keys) {
+  return keys.reduce(
+    (n, k) => {
+      if (k in obj) n[k] = obj[k];
+      return n;
+    },
+    {}
+  );
+}
+function objectOmit(obj, keys) {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([k]) => !keys.includes(k))
+  );
+}
+function promiseTimeout(ms, throwOnTimeout = false) {
+  return new Promise(
+    (resolve, reject) => throwOnTimeout ? setTimeout(() => reject(new Error(`Timeout ${ms}ms`)), ms) : setTimeout(resolve, ms)
+  );
+}
+function increaseWithUnit(target, delta) {
+  if (typeof target === "number") return target + delta;
+  const match = target.match(/^(-?\d*\.?\d+)([a-z%]*)$/i);
+  if (!match) return target;
+  const [, num, unit] = match;
+  return `${Number(num) + delta}${unit}`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clamp,
+  increaseWithUnit,
+  isClient,
+  isDef,
+  isIOS,
+  isObject,
+  noop,
+  notNullish,
+  objectOmit,
+  objectPick,
+  promiseTimeout,
+  toArray
+});
+//# sourceMappingURL=utils.js.map

package/dist/shared/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/shared/utils.ts"],"sourcesContent":["// ---------------------------------------------------------------------------\n// TIER 0-B: Shared pure utility functions (VueUse equivalents, no dependencies)\n// ---------------------------------------------------------------------------\n\nexport const isClient =\n  typeof window !== \"undefined\" && typeof document !== \"undefined\";\n\nexport const noop = () => {};\n\nexport const clamp = (n: number, min: number, max: number) =>\n  Math.min(max, Math.max(min, n));\n\nexport const isDef = <T>(val?: T): val is T => typeof val !== \"undefined\";\n\nexport const notNullish = <T>(val?: T | null): val is T => val != null;\n\nexport const isObject = (val: unknown): val is object =>\n  Object.prototype.toString.call(val) === \"[object Object]\";\n\nexport const isIOS =\n  /* #__PURE__ */ isClient &&\n  /iPad|iPhone|iPod/.test(navigator.userAgent) &&\n  !(window as any).MSStream;\n\nexport function toArray<T>(v: T | T[]): T[] {\n  return Array.isArray(v) ? v : [v];\n}\n\nexport function objectPick<O extends object, T extends keyof O>(\n  obj: O,\n  keys: T[],\n): Pick<O, T> {\n  return keys.reduce(\n    (n, k) => {\n      if (k in obj) n[k] = obj[k];\n      return n;\n    },\n    {} as Pick<O, T>,\n  );\n}\n\nexport function objectOmit<O extends object, T extends keyof O>(\n  obj: O,\n  keys: T[],\n): Omit<O, T> {\n  return Object.fromEntries(\n    Object.entries(obj).filter(([k]) => !keys.includes(k as T)),\n  ) as Omit<O, T>;\n}\n\nexport function promiseTimeout(ms: number, throwOnTimeout = false): Promise<void> {\n  return new Promise((resolve, reject) =>\n    throwOnTimeout\n      ? setTimeout(() => reject(new Error(`Timeout ${ms}ms`)), ms)\n      : setTimeout(resolve, ms),\n  );\n}\n\nexport function increaseWithUnit(target: number, delta: number): number;\nexport function increaseWithUnit(target: string, delta: number): string;\nexport function increaseWithUnit(target: number | string, delta: number): number | string {\n  if (typeof target === \"number\") return target + delta;\n  const match = target.match(/^(-?\\d*\\.?\\d+)([a-z%]*)$/i);\n  if (!match) return target;\n  const [, num, unit] = match;\n  return `${Number(num) + delta}${unit}`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAIO,MAAM,WACX,OAAO,WAAW,eAAe,OAAO,aAAa;AAEhD,MAAM,OAAO,MAAM;AAAC;AAEpB,MAAM,QAAQ,CAAC,GAAW,KAAa,QAC5C,KAAK,IAAI,KAAK,KAAK,IAAI,KAAK,CAAC,CAAC;AAEzB,MAAM,QAAQ,CAAI,QAAsB,OAAO,QAAQ;AAEvD,MAAM,aAAa,CAAI,QAA6B,OAAO;AAE3D,MAAM,WAAW,CAAC,QACvB,OAAO,UAAU,SAAS,KAAK,GAAG,MAAM;AAEnC,MAAM,QACK,YAChB,mBAAmB,KAAK,UAAU,SAAS,KAC3C,CAAE,OAAe;AAEZ,SAAS,QAAW,GAAiB;AAC1C,SAAO,MAAM,QAAQ,CAAC,IAAI,IAAI,CAAC,CAAC;AAClC;AAEO,SAAS,WACd,KACA,MACY;AACZ,SAAO,KAAK;AAAA,IACV,CAAC,GAAG,MAAM;AACR,UAAI,KAAK,IAAK,GAAE,CAAC,IAAI,IAAI,CAAC;AAC1B,aAAO;AAAA,IACT;AAAA,IACA,CAAC;AAAA,EACH;AACF;AAEO,SAAS,WACd,KACA,MACY;AACZ,SAAO,OAAO;AAAA,IACZ,OAAO,QAAQ,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,SAAS,CAAM,CAAC;AAAA,EAC5D;AACF;AAEO,SAAS,eAAe,IAAY,iBAAiB,OAAsB;AAChF,SAAO,IAAI;AAAA,IAAQ,CAAC,SAAS,WAC3B,iBACI,WAAW,MAAM,OAAO,IAAI,MAAM,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,IACzD,WAAW,SAAS,EAAE;AAAA,EAC5B;AACF;AAIO,SAAS,iBAAiB,QAAyB,OAAgC;AACxF,MAAI,OAAO,WAAW,SAAU,QAAO,SAAS;AAChD,QAAM,QAAQ,OAAO,MAAM,2BAA2B;AACtD,MAAI,CAAC,MAAO,QAAO;AACnB,QAAM,CAAC,EAAE,KAAK,IAAI,IAAI;AACtB,SAAO,GAAG,OAAO,GAAG,IAAI,KAAK,GAAG,IAAI;AACtC;","names":[]}

package/dist/shared/utils.mjs

@@ -0,0 +1,52 @@
+const isClient = typeof window !== "undefined" && typeof document !== "undefined";
+const noop = () => {
+};
+const clamp = (n, min, max) => Math.min(max, Math.max(min, n));
+const isDef = (val) => typeof val !== "undefined";
+const notNullish = (val) => val != null;
+const isObject = (val) => Object.prototype.toString.call(val) === "[object Object]";
+const isIOS = isClient && /iPad|iPhone|iPod/.test(navigator.userAgent) && !window.MSStream;
+function toArray(v) {
+  return Array.isArray(v) ? v : [v];
+}
+function objectPick(obj, keys) {
+  return keys.reduce(
+    (n, k) => {
+      if (k in obj) n[k] = obj[k];
+      return n;
+    },
+    {}
+  );
+}
+function objectOmit(obj, keys) {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([k]) => !keys.includes(k))
+  );
+}
+function promiseTimeout(ms, throwOnTimeout = false) {
+  return new Promise(
+    (resolve, reject) => throwOnTimeout ? setTimeout(() => reject(new Error(`Timeout ${ms}ms`)), ms) : setTimeout(resolve, ms)
+  );
+}
+function increaseWithUnit(target, delta) {
+  if (typeof target === "number") return target + delta;
+  const match = target.match(/^(-?\d*\.?\d+)([a-z%]*)$/i);
+  if (!match) return target;
+  const [, num, unit] = match;
+  return `${Number(num) + delta}${unit}`;
+}
+export {
+  clamp,
+  increaseWithUnit,
+  isClient,
+  isDef,
+  isIOS,
+  isObject,
+  noop,
+  notNullish,
+  objectOmit,
+  objectPick,
+  promiseTimeout,
+  toArray
+};
+//# sourceMappingURL=utils.mjs.map

package/dist/shared/utils.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/shared/utils.ts"],"sourcesContent":["// ---------------------------------------------------------------------------\n// TIER 0-B: Shared pure utility functions (VueUse equivalents, no dependencies)\n// ---------------------------------------------------------------------------\n\nexport const isClient =\n  typeof window !== \"undefined\" && typeof document !== \"undefined\";\n\nexport const noop = () => {};\n\nexport const clamp = (n: number, min: number, max: number) =>\n  Math.min(max, Math.max(min, n));\n\nexport const isDef = <T>(val?: T): val is T => typeof val !== \"undefined\";\n\nexport const notNullish = <T>(val?: T | null): val is T => val != null;\n\nexport const isObject = (val: unknown): val is object =>\n  Object.prototype.toString.call(val) === \"[object Object]\";\n\nexport const isIOS =\n  /* #__PURE__ */ isClient &&\n  /iPad|iPhone|iPod/.test(navigator.userAgent) &&\n  !(window as any).MSStream;\n\nexport function toArray<T>(v: T | T[]): T[] {\n  return Array.isArray(v) ? v : [v];\n}\n\nexport function objectPick<O extends object, T extends keyof O>(\n  obj: O,\n  keys: T[],\n): Pick<O, T> {\n  return keys.reduce(\n    (n, k) => {\n      if (k in obj) n[k] = obj[k];\n      return n;\n    },\n    {} as Pick<O, T>,\n  );\n}\n\nexport function objectOmit<O extends object, T extends keyof O>(\n  obj: O,\n  keys: T[],\n): Omit<O, T> {\n  return Object.fromEntries(\n    Object.entries(obj).filter(([k]) => !keys.includes(k as T)),\n  ) as Omit<O, T>;\n}\n\nexport function promiseTimeout(ms: number, throwOnTimeout = false): Promise<void> {\n  return new Promise((resolve, reject) =>\n    throwOnTimeout\n      ? setTimeout(() => reject(new Error(`Timeout ${ms}ms`)), ms)\n      : setTimeout(resolve, ms),\n  );\n}\n\nexport function increaseWithUnit(target: number, delta: number): number;\nexport function increaseWithUnit(target: string, delta: number): string;\nexport function increaseWithUnit(target: number | string, delta: number): number | string {\n  if (typeof target === \"number\") return target + delta;\n  const match = target.match(/^(-?\\d*\\.?\\d+)([a-z%]*)$/i);\n  if (!match) return target;\n  const [, num, unit] = match;\n  return `${Number(num) + delta}${unit}`;\n}\n"],"mappings":"AAIO,MAAM,WACX,OAAO,WAAW,eAAe,OAAO,aAAa;AAEhD,MAAM,OAAO,MAAM;AAAC;AAEpB,MAAM,QAAQ,CAAC,GAAW,KAAa,QAC5C,KAAK,IAAI,KAAK,KAAK,IAAI,KAAK,CAAC,CAAC;AAEzB,MAAM,QAAQ,CAAI,QAAsB,OAAO,QAAQ;AAEvD,MAAM,aAAa,CAAI,QAA6B,OAAO;AAE3D,MAAM,WAAW,CAAC,QACvB,OAAO,UAAU,SAAS,KAAK,GAAG,MAAM;AAEnC,MAAM,QACK,YAChB,mBAAmB,KAAK,UAAU,SAAS,KAC3C,CAAE,OAAe;AAEZ,SAAS,QAAW,GAAiB;AAC1C,SAAO,MAAM,QAAQ,CAAC,IAAI,IAAI,CAAC,CAAC;AAClC;AAEO,SAAS,WACd,KACA,MACY;AACZ,SAAO,KAAK;AAAA,IACV,CAAC,GAAG,MAAM;AACR,UAAI,KAAK,IAAK,GAAE,CAAC,IAAI,IAAI,CAAC;AAC1B,aAAO;AAAA,IACT;AAAA,IACA,CAAC;AAAA,EACH;AACF;AAEO,SAAS,WACd,KACA,MACY;AACZ,SAAO,OAAO;AAAA,IACZ,OAAO,QAAQ,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,SAAS,CAAM,CAAC;AAAA,EAC5D;AACF;AAEO,SAAS,eAAe,IAAY,iBAAiB,OAAsB;AAChF,SAAO,IAAI;AAAA,IAAQ,CAAC,SAAS,WAC3B,iBACI,WAAW,MAAM,OAAO,IAAI,MAAM,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,IACzD,WAAW,SAAS,EAAE;AAAA,EAC5B;AACF;AAIO,SAAS,iBAAiB,QAAyB,OAAgC;AACxF,MAAI,OAAO,WAAW,SAAU,QAAO,SAAS;AAChD,QAAM,QAAQ,OAAO,MAAM,2BAA2B;AACtD,MAAI,CAAC,MAAO,QAAO;AACnB,QAAM,CAAC,EAAE,KAAK,IAAI,IAAI;AACtB,SAAO,GAAG,OAAO,GAAG,IAAI,KAAK,GAAG,IAAI;AACtC;","names":[]}

package/dist/types.d.mts

@@ -0,0 +1,52 @@
+import { Observable } from '@legendapp/state';
+
+/**
+ * @usels/core - Utility functions for Legend-State
+ */
+
+/**
+ * A value that can be either a raw value or an Observable
+ * Similar to VueUse's MaybeRef pattern
+ *
+ * @example
+ * ```ts
+ * const value: MaybeObservable<string> = 'hello'
+ * const obs: MaybeObservable<string> = observable('hello')
+ * ```
+ */
+type MaybeObservable<T = any> = T | Observable<T>;
+/**
+ * Either the whole `T` can be an Observable, OR each individual property of `T` can be an Observable.
+ *
+ * Unlike `MaybeObservable<T>` which only wraps the outer object, `DeepMaybeObservable<T>` also
+ * allows every field to independently accept `Observable<FieldType>`.
+ *
+ * @example
+ * ```ts
+ * type Options = DeepMaybeObservable<{ count: number; label: string }>
+ * // All of these are valid:
+ * const a: Options = { count: 1, label: 'hi' }                           // plain object
+ * const b: Options = { count: observable(1), label: observable('hi') }   // per-field observables
+ * const c: Options = observable({ count: 1, label: 'hi' })               // whole object observable
+ * ```
+ */
+type DeepMaybeObservable<T> = Observable<T> | {
+    [K in keyof T]?: MaybeObservable<NonNullable<T[K]>>;
+};
+type Fn = () => void;
+type AnyFn = (...args: any[]) => any;
+type Arrayable<T> = T[] | T;
+type Awaitable<T> = Promise<T> | T;
+type TimerHandle = ReturnType<typeof setTimeout> | undefined;
+interface Pausable {
+    readonly isActive: Observable<boolean>;
+    pause: Fn;
+    resume: Fn;
+}
+interface Stoppable<StartFnArgs extends any[] = any[]> {
+    readonly isPending: Observable<boolean>;
+    stop: Fn;
+    start: (...args: StartFnArgs) => void;
+}
+
+export type { AnyFn, Arrayable, Awaitable, DeepMaybeObservable, Fn, MaybeObservable, Pausable, Stoppable, TimerHandle };

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+import { Observable } from '@legendapp/state';
+
+/**
+ * @usels/core - Utility functions for Legend-State
+ */
+
+/**
+ * A value that can be either a raw value or an Observable
+ * Similar to VueUse's MaybeRef pattern
+ *
+ * @example
+ * ```ts
+ * const value: MaybeObservable<string> = 'hello'
+ * const obs: MaybeObservable<string> = observable('hello')
+ * ```
+ */
+type MaybeObservable<T = any> = T | Observable<T>;
+/**
+ * Either the whole `T` can be an Observable, OR each individual property of `T` can be an Observable.
+ *
+ * Unlike `MaybeObservable<T>` which only wraps the outer object, `DeepMaybeObservable<T>` also
+ * allows every field to independently accept `Observable<FieldType>`.
+ *
+ * @example
+ * ```ts
+ * type Options = DeepMaybeObservable<{ count: number; label: string }>
+ * // All of these are valid:
+ * const a: Options = { count: 1, label: 'hi' }                           // plain object
+ * const b: Options = { count: observable(1), label: observable('hi') }   // per-field observables
+ * const c: Options = observable({ count: 1, label: 'hi' })               // whole object observable
+ * ```
+ */
+type DeepMaybeObservable<T> = Observable<T> | {
+    [K in keyof T]?: MaybeObservable<NonNullable<T[K]>>;
+};
+type Fn = () => void;
+type AnyFn = (...args: any[]) => any;
+type Arrayable<T> = T[] | T;
+type Awaitable<T> = Promise<T> | T;
+type TimerHandle = ReturnType<typeof setTimeout> | undefined;
+interface Pausable {
+    readonly isActive: Observable<boolean>;
+    pause: Fn;
+    resume: Fn;
+}
+interface Stoppable<StartFnArgs extends any[] = any[]> {
+    readonly isPending: Observable<boolean>;
+    stop: Fn;
+    start: (...args: StartFnArgs) => void;
+}
+
+export type { AnyFn, Arrayable, Awaitable, DeepMaybeObservable, Fn, MaybeObservable, Pausable, Stoppable, TimerHandle };

package/dist/types.js

@@ -0,0 +1,17 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\n * @usels/core - Utility functions for Legend-State\n */\n\nimport type { Observable } from \"@legendapp/state\";\n\n/**\n * A value that can be either a raw value or an Observable\n * Similar to VueUse's MaybeRef pattern\n *\n * @example\n * ```ts\n * const value: MaybeObservable<string> = 'hello'\n * const obs: MaybeObservable<string> = observable('hello')\n * ```\n */\nexport type MaybeObservable<T = any> = T | Observable<T>;\n\n/**\n * Either the whole `T` can be an Observable, OR each individual property of `T` can be an Observable.\n *\n * Unlike `MaybeObservable<T>` which only wraps the outer object, `DeepMaybeObservable<T>` also\n * allows every field to independently accept `Observable<FieldType>`.\n *\n * @example\n * ```ts\n * type Options = DeepMaybeObservable<{ count: number; label: string }>\n * // All of these are valid:\n * const a: Options = { count: 1, label: 'hi' }                           // plain object\n * const b: Options = { count: observable(1), label: observable('hi') }   // per-field observables\n * const c: Options = observable({ count: 1, label: 'hi' })               // whole object observable\n * ```\n */\nexport type DeepMaybeObservable<T> = Observable<T> | {\n  [K in keyof T]?: MaybeObservable<NonNullable<T[K]>>;\n};\n\n// --- TIER 0-A: Base utility types (VueUse equivalents) ---\n\nexport type Fn = () => void\nexport type AnyFn = (...args: any[]) => any\nexport type Arrayable<T> = T[] | T\nexport type Awaitable<T> = Promise<T> | T\nexport type TimerHandle = ReturnType<typeof setTimeout> | undefined\n\nexport interface Pausable {\n  readonly isActive: Observable<boolean>\n  pause: Fn\n  resume: Fn\n}\n\nexport interface Stoppable<StartFnArgs extends any[] = any[]> {\n  readonly isPending: Observable<boolean>\n  stop: Fn\n  start: (...args: StartFnArgs) => void\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/types.mjs

@@ -0,0 +1 @@
+//# sourceMappingURL=types.mjs.map

package/dist/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@usels/core",
+  "version": "0.0.1",
+  "description": "Utility functions for Legend-State",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "es-toolkit": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@legendapp/state": "^2.0.0 || ^3.0.0-beta.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@legendapp/state": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "jsdom": "^25.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3"
+  },
+  "keywords": [
+    "legendapp",
+    "legend-state",
+    "utilities",
+    "helpers"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "test:watch": "vitest --watch"
+  }
+}

package/src/browser/useEventListener/index.md

@@ -0,0 +1,109 @@
+---
+title: useEventListener
+category: browser
+---
+
+Registers an event listener with `addEventListener` on mount and automatically removes it with `removeEventListener` on unmount.
+Targets can be `Ref$`, `Observable<Element|null>`, a plain `Element`, `Window`, or `Document`.
+The listener is always called with the latest closure value — state changes never cause stale callbacks.
+
+## Usage
+
+### Window (default target)
+
+When no target is provided, the listener is attached to `window`.
+
+```tsx
+import { useEventListener } from '@usels/core'
+
+function Component() {
+  useEventListener('keydown', (ev) => {
+    console.log(ev.key)
+  })
+
+  return null
+}
+```
+
+### Element target
+
+```tsx
+import { useRef$, useEventListener } from '@usels/core'
+
+function Component() {
+  const el$ = useRef$<HTMLDivElement>()
+
+  useEventListener(el$, 'click', (ev) => {
+    console.log('clicked', ev.target)
+  })
+
+  return <div ref={el$} />
+}
+```
+
+### Reactive Ref$ target
+
+When an `Ref$` or `Observable<Element>` is passed as the target, the listener is automatically re-registered whenever the element changes.
+
+```tsx
+const el$ = useRef$<HTMLButtonElement>()
+
+useEventListener(el$, 'pointerdown', (ev) => {
+  ev.preventDefault()
+})
+
+return <button ref={el$} />
+```
+
+### Multiple events
+
+```tsx
+useEventListener(el$, ['mouseenter', 'mouseleave'], (ev) => {
+  console.log(ev.type)
+})
+```
+
+### Multiple listeners
+
+```tsx
+useEventListener(el$, 'click', [onClickA, onClickB])
+```
+
+### Document / Window target
+
+```tsx
+useEventListener(document, 'visibilitychange', () => {
+  console.log(document.visibilityState)
+})
+```
+
+### AddEventListenerOptions
+
+```tsx
+useEventListener(el$, 'scroll', onScroll, { passive: true })
+```
+
+### Manual cleanup
+
+The hook returns a cleanup function for imperative removal before unmount.
+
+```tsx
+const stop = useEventListener('resize', onResize)
+
+// remove the listener early
+stop()
+```
+
+## Notes
+
+**Plain element targets are not reactive.** If you pass a plain `HTMLElement` or `null` value and that reference changes after mount (e.g. via `useState`), the hook does not detect the change. Use `Ref$` or `Observable<Element>` for targets that change over time.
+
+```tsx
+// ❌ listener stays on the original element if el changes via state
+const [el, setEl] = useState<HTMLDivElement | null>(null)
+useEventListener(el, 'click', handler)
+
+// ✅ listener is re-registered automatically when el$ changes
+const el$ = useRef$<HTMLDivElement>()
+useEventListener(el$, 'click', handler)
+```