@kapiuara/ui 0.0.0-stage → 0.1.1

package/dist/hooks/storageLogic.js

@@ -0,0 +1,24 @@
+//#region src/hooks/storageLogic.ts
+var e = "kapi", t = (e, t) => `${e || "kapi"}:${t}`, n = () => {
+	try {
+		return typeof localStorage > "u" ? null : localStorage;
+	} catch {
+		return null;
+	}
+}, r = (e, t, n) => {
+	if (e && t !== n) try {
+		let r = e.getItem(t);
+		if (r === null) return;
+		e.getItem(n) === null && e.setItem(n, r), e.removeItem(t);
+	} catch {}
+}, i = (e, t, n) => {
+	if (!e) return null;
+	n && r(e, n, t);
+	try {
+		return e.getItem(t);
+	} catch {
+		return null;
+	}
+};
+//#endregion
+export { e as DEFAULT_STORAGE_NAMESPACE, n as defaultStorage, r as migrateLegacy, i as readWithLegacy, t as storageKey };

package/dist/hooks/unsavedGuardLogic.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Lógica pura del guard de "cambios sin guardar": una compuerta que convierte la
+ * decisión del usuario (Quedarme / Descartar y salir) en una promesa. Sin React ni DOM.
+ */
+export type LeaveGate = {
+    /** Si no hay cambios resuelve `true` ya; si los hay, abre la confirmación y espera. */
+    request: (dirty: boolean) => Promise<boolean>;
+    /** Resuelve la consulta pendiente (`true` = salir, `false` = quedarse). No-op si no hay. */
+    settle: (leave: boolean) => void;
+    /** ¿Hay una confirmación esperando respuesta? */
+    isPending: () => boolean;
+};
+/**
+ * Crea la compuerta. `onOpenChange(true)` se invoca al pedir confirmación y
+ * `onOpenChange(false)` al resolverla. Pedidos concurrentes comparten la misma promesa.
+ */
+export declare const createLeaveGate: (onOpenChange: (open: boolean) => void) => LeaveGate;

package/dist/hooks/unsavedGuardLogic.js

@@ -0,0 +1,17 @@
+//#region src/hooks/unsavedGuardLogic.ts
+var e = (e) => {
+	let t = null, n = null;
+	return {
+		request: (r) => r ? t || (t = new Promise((e) => {
+			n = e;
+		}), e(!0), t) : Promise.resolve(!0),
+		settle: (r) => {
+			if (!n) return;
+			let i = n;
+			n = null, t = null, e(!1), i(r);
+		},
+		isPending: () => t !== null
+	};
+};
+//#endregion
+export { e as createLeaveGate };

package/dist/hooks/useDragScroll.d.ts

@@ -0,0 +1,12 @@
+import { type RefObject } from "react";
+export type UseDragScrollOptions = {
+    /** Se dispara con DOBLE click derecho (sin arrastrar): abrir un menú custom ahí. */
+    onMenu?: ((x: number, y: number) => void) | undefined;
+};
+/**
+ * Drag-to-scroll con CLICK SECUNDARIO (derecho): mantené el botón derecho y
+ * arrastrá para mover el scroll del elemento. El click izquierdo queda libre.
+ * El menú nativo se suprime en el área; con doble click derecho se llama `onMenu`.
+ * Devolvé el ref al contenedor scrolleable (`<div ref={ref} />`).
+ */
+export declare const useDragScroll: <T extends HTMLElement = HTMLDivElement>(options?: UseDragScrollOptions) => RefObject<T | null>;

package/dist/hooks/useDragScroll.js

@@ -0,0 +1,32 @@
+"use client";
+import { exceedsDragThreshold as e, isDoubleRightClick as t, isInteractiveTarget as n } from "./rightClick.js";
+import { useEffect as r, useRef as i } from "react";
+//#region src/hooks/useDragScroll.ts
+var a = (a = {}) => {
+	let o = i(null), s = i(a);
+	return s.current = a, r(() => {
+		let r = o.current;
+		if (!r) return;
+		let i = !1, a = !1, c = 0, l = 0, u = 0, d = 0, f = 0, p = (e) => {
+			e.button === 2 && (n(e.target) || (e.stopPropagation(), i = !0, a = !1, c = e.pageX, l = e.pageY, u = r.scrollLeft, d = r.scrollTop));
+		}, m = (t) => {
+			if (!i) return;
+			let n = t.pageX - c, o = t.pageY - l;
+			!a && e(n, o) && (a = !0, r.classList.add("kapi-grabbing")), a && (t.preventDefault(), r.scrollLeft = u - n, r.scrollTop = d - o);
+		}, h = () => {
+			i = !1, r.classList.remove("kapi-grabbing");
+		}, g = (e) => {
+			if (e.preventDefault(), e.stopPropagation(), a) {
+				a = !1, f = 0;
+				return;
+			}
+			let n = Date.now();
+			t(n, f) ? (s.current.onMenu?.(e.clientX, e.clientY), f = 0) : f = n;
+		};
+		return r.addEventListener("mousedown", p), window.addEventListener("mousemove", m), window.addEventListener("mouseup", h), r.addEventListener("contextmenu", g), () => {
+			r.removeEventListener("mousedown", p), window.removeEventListener("mousemove", m), window.removeEventListener("mouseup", h), r.removeEventListener("contextmenu", g);
+		};
+	}, []), o;
+};
+//#endregion
+export { a as useDragScroll };

package/dist/hooks/useGlobalRightClick.d.ts

@@ -0,0 +1,14 @@
+export type UseGlobalRightClickOptions = {
+    /** Doble click derecho (sin arrastrar) → posición para abrir el menú del sistema. */
+    onMenu?: ((x: number, y: number) => void) | undefined;
+    /** Desactivá la mecánica completa (incluida la supresión del menú nativo). */
+    enabled?: boolean | undefined;
+};
+/**
+ * Interacción GLOBAL con botón derecho (la usa KapiShell):
+ *  - arrastrar con el derecho → scrollea el contenedor scrolleable bajo el cursor.
+ *  - doble click derecho (sin arrastrar) → `onMenu(x, y)` (menú custom del sistema).
+ *  - se suprime el menú nativo del navegador, salvo en táctil (long-press de Android).
+ * Los contenedores con `useDragScroll` manejan su propio drag/menú (cortan la propagación).
+ */
+export declare const useGlobalRightClick: ({ onMenu, enabled }?: UseGlobalRightClickOptions) => void;

package/dist/hooks/useGlobalRightClick.js

@@ -0,0 +1,35 @@
+"use client";
+import { exceedsDragThreshold as e, findScrollableAncestor as t, isDoubleRightClick as n, isInteractiveTarget as r, shouldInterceptContextMenu as i } from "./rightClick.js";
+import { useEffect as a, useRef as o } from "react";
+//#region src/hooks/useGlobalRightClick.ts
+var s = ({ onMenu: s, enabled: c = !0 } = {}) => {
+	let l = o(s);
+	l.current = s, a(() => {
+		if (!c) return;
+		let a = 0, o = !1, s = !1, u = null, d = 0, f = 0, p = 0, m = 0, h = null, g = (e) => {
+			h = e.pointerType;
+		}, _ = (e) => {
+			e.button === 2 && (r(e.target) || (u = t(e.target), u && (o = !0, s = !1, d = e.pageX, f = e.pageY, p = u.scrollLeft, m = u.scrollTop)));
+		}, v = (t) => {
+			if (!o || !u) return;
+			let n = t.pageX - d, r = t.pageY - f;
+			!s && e(n, r) && (s = !0, document.body.style.userSelect = "none"), s && (t.preventDefault(), u.scrollLeft = p - n, u.scrollTop = m - r);
+		}, y = () => {
+			o = !1, u = null, document.body.style.userSelect = "";
+		}, b = (e) => {
+			let t = "pointerType" in e ? e.pointerType : void 0;
+			if (!i(t, h)) return;
+			if (e.preventDefault(), s) {
+				s = !1, a = 0;
+				return;
+			}
+			let r = Date.now();
+			n(r, a) ? (l.current?.(e.clientX, e.clientY), a = 0) : a = r;
+		};
+		return document.addEventListener("pointerdown", g, !0), document.addEventListener("mousedown", _), window.addEventListener("mousemove", v), window.addEventListener("mouseup", y), document.addEventListener("contextmenu", b), () => {
+			document.removeEventListener("pointerdown", g, !0), document.removeEventListener("mousedown", _), window.removeEventListener("mousemove", v), window.removeEventListener("mouseup", y), document.removeEventListener("contextmenu", b);
+		};
+	}, [c]);
+};
+//#endregion
+export { s as useGlobalRightClick };

package/dist/hooks/useGrowOrigin.d.ts

@@ -0,0 +1,13 @@
+import { type MouseEvent } from "react";
+import { type GrowOrigin } from "./growOriginLogic";
+export type { GrowOrigin } from "./growOriginLogic";
+/**
+ * Captura el centro del botón disparador para que un overlay (p. ej. `KapiModal`
+ * con `growFrom`) "crezca" desde ahí. Uso: `onClick={(e) => { grow.capture(e); setOpen(true); }}`
+ * y `grow.clear()` al cerrar.
+ */
+export declare const useGrowOrigin: () => {
+    origin: GrowOrigin | null;
+    capture: (e: MouseEvent) => void;
+    clear: () => void;
+};

package/dist/hooks/useGrowOrigin.js

@@ -0,0 +1,16 @@
+"use client";
+import { rectCenter as e } from "./growOriginLogic.js";
+import { useCallback as t, useState as n } from "react";
+//#region src/hooks/useGrowOrigin.ts
+var r = () => {
+	let [r, i] = n(null);
+	return {
+		origin: r,
+		capture: t((t) => {
+			i(e(t.currentTarget.getBoundingClientRect()));
+		}, []),
+		clear: t(() => i(null), [])
+	};
+};
+//#endregion
+export { r as useGrowOrigin };

package/dist/hooks/useHotkey.d.ts

@@ -0,0 +1,15 @@
+export type UseHotkeyOptions = {
+    /** Listen only while true. Default true. */
+    enabled?: boolean;
+    /** Call `preventDefault()` on a match (blocks e.g. the browser's Ctrl+K). Default true. */
+    preventDefault?: boolean;
+    /** Also fire while typing in inputs, textareas or contenteditable. Default true when the combo has a modifier, false otherwise. */
+    allowInInputs?: boolean;
+};
+/**
+ * Global keyboard shortcut. `combo` is `+`-separated: modifiers `mod` (Ctrl or Cmd), `ctrl`, `meta`/`cmd`,
+ * `alt`, `shift`, then the key: `"mod+k"`, `"ctrl+shift+p"`, `"/"`. The handler may be an inline function.
+ *
+ * @example useHotkey("mod+k", () => setOpen((o) => !o));
+ */
+export declare const useHotkey: (combo: string, handler: (event: KeyboardEvent) => void, options?: UseHotkeyOptions) => void;

package/dist/hooks/useHotkey.js

@@ -0,0 +1,31 @@
+"use client";
+import { matchesHotkey as e, parseHotkey as t } from "./hotkeyLogic.js";
+import { useEffect as n, useRef as r } from "react";
+//#region src/hooks/useHotkey.ts
+var i = (i, a, o = {}) => {
+	let { enabled: s = !0, preventDefault: c = !0, allowInInputs: l } = o, u = r(a);
+	n(() => {
+		u.current = a;
+	}), n(() => {
+		if (!s) return;
+		let n = t(i);
+		if (!n) return;
+		let r = n.mod || n.ctrl || n.meta || n.alt, a = l ?? r, o = (t) => {
+			if (!(t.defaultPrevented || t.isComposing || !e(t, n))) {
+				if (!a) {
+					let e = t.target;
+					if (e instanceof HTMLElement && (e.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(e.tagName))) return;
+				}
+				c && t.preventDefault(), u.current(t);
+			}
+		};
+		return window.addEventListener("keydown", o), () => window.removeEventListener("keydown", o);
+	}, [
+		i,
+		s,
+		c,
+		l
+	]);
+};
+//#endregion
+export { i as useHotkey };

package/dist/hooks/useKapiTheme.d.ts

@@ -0,0 +1,69 @@
+import { type CSSProperties } from "react";
+export type KapiTheme = "light" | "dark";
+/** Lo que elige la persona: un tema fijo o `system` (sigue a `prefers-color-scheme` del SO). */
+export type KapiThemePreference = KapiTheme | "system";
+/** Media query del modo oscuro del SO. */
+export declare const DARK_SCHEME_QUERY = "(prefers-color-scheme: dark)";
+export type KapiFontKey = "nunito" | "roboto" | "system";
+/** Movimiento: `auto` sigue al SO (prefers-reduced-motion); `reduced` lo apaga siempre. */
+export type KapiMotion = "auto" | "reduced";
+/** Preferencias del tema que se guardan. */
+export type KapiThemeStorageName = "theme" | "accent" | "font" | "motion";
+/** Claves de localStorage del tema para un namespace (default `kapi` → `kapi:theme`…). */
+export declare const themeStorageKeys: (namespace?: string) => Record<KapiThemeStorageName, string>;
+/** Claves viejas (sin namespace): se migran a las nuevas en la primera lectura y se borran. */
+export declare const LEGACY_THEME_KEYS: Record<KapiThemeStorageName, string>;
+export declare const THEME_KEY: string;
+export declare const ACCENT_KEY: string;
+export declare const FONT_KEY: string;
+export declare const MOTION_KEY: string;
+/** Fuentes disponibles. Cambiar la familia es setear el token --kapi-font. */
+export declare const FONTS: Record<KapiFontKey, string>;
+export type KapiThemeState = {
+    /** Tema que se ve (con `system`, el que resuelve el SO). */
+    theme: KapiTheme;
+    /** Preferencia elegida (`light`, `dark` o `system`). */
+    preference: KapiThemePreference;
+    /** Color de acento (hex) o "" para el primario por defecto. */
+    accent: string;
+    font: KapiFontKey;
+    /** Preferencia de movimiento del usuario (independiente del `prefers-reduced-motion` del SO). */
+    motion: KapiMotion;
+    /** Fija un tema (deja de seguir al SO). */
+    setTheme: (t: KapiTheme) => void;
+    /** Elige `light`, `dark` o `system`. */
+    setPreference: (p: KapiThemePreference) => void;
+    /** Alterna sobre el tema que se ve y lo deja fijo. */
+    toggle: () => void;
+    setAccent: (hex?: string | null) => void;
+    setFont: (f: KapiFontKey) => void;
+    setMotion: (m: KapiMotion) => void;
+    /** Alterna entre `auto` y `reduced`. */
+    toggleMotion: () => void;
+};
+/** Lee de localStorage tolerando entornos sin storage (SSR, modo privado). */
+export declare const readStored: (key: string, fallback: string) => string;
+export declare const isTheme: (v: string) => v is KapiTheme;
+export declare const isThemePreference: (v: string) => v is KapiThemePreference;
+/** Tema que se ve: `system` sigue al SO; `light`/`dark` lo ignoran. */
+export declare const resolveTheme: (preference: KapiThemePreference, systemDark: boolean) => KapiTheme;
+/** Preferencia guardada en el namespace (o `light`, el default de siempre). Migra `v2_theme`. */
+export declare const readThemePreference: (namespace?: string) => KapiThemePreference;
+/** Alternar desde el tema que se ve: queda el opuesto, explícito. */
+export declare const toggledPreference: (shown: KapiTheme) => KapiTheme;
+export declare const isFontKey: (v: string) => v is KapiFontKey;
+export declare const isMotion: (v: string) => v is KapiMotion;
+/** Style de la raíz .kapi derivado del estado (fuente + acento como tokens). */
+export declare const themeRootStyle: (state: Pick<KapiThemeState, "font" | "accent">) => CSSProperties;
+export declare const KapiThemeContext: import("react").Context<KapiThemeState>;
+export type KapiThemeStateOptions = {
+    /**
+     * Namespace de las claves de localStorage (default `kapi` → `kapi:theme`, `kapi:accent`…).
+     * Dos apps del design system en el mismo origen pasan uno distinto para no pisarse las preferencias.
+     */
+    namespace?: string | undefined;
+};
+/** Crea el estado del tema (lo usa KapiShell; usalo directo si armás tu propia raíz). */
+export declare const useKapiThemeState: ({ namespace }?: KapiThemeStateOptions) => KapiThemeState;
+/** Consume el tema desde cualquier componente dentro de <KapiShell>. */
+export declare const useKapiTheme: () => KapiThemeState;

package/dist/hooks/useKapiTheme.js

@@ -0,0 +1,88 @@
+"use client";
+import { defaultStorage as e, readWithLegacy as t, storageKey as n } from "./storageLogic.js";
+import { useMediaQuery as r } from "./useMediaQuery.js";
+import { createContext as i, useCallback as a, useContext as o, useEffect as s, useMemo as c, useState as l } from "react";
+//#region src/hooks/useKapiTheme.ts
+var u = "(prefers-color-scheme: dark)", d = (e) => ({
+	theme: n(e, "theme"),
+	accent: n(e, "accent"),
+	font: n(e, "font"),
+	motion: n(e, "motion")
+}), f = {
+	theme: "v2_theme",
+	accent: "v2_accent",
+	font: "v2_font",
+	motion: "v2_motion"
+};
+d().theme, d().accent, d().font, d().motion;
+var p = {
+	nunito: "'Nunito Variable', 'Nunito', system-ui, sans-serif",
+	roboto: "'Roboto', system-ui, sans-serif",
+	system: "system-ui, -apple-system, 'Segoe UI', sans-serif"
+}, m = (n, r, i) => t(e(), d(n)[r], f[r]) || i, h = (e, t) => {
+	try {
+		localStorage.setItem(e, t);
+	} catch {}
+}, g = (e) => e === "light" || e === "dark", _ = (e) => g(e) || e === "system", v = (e, t) => e === "system" ? t ? "dark" : "light" : e, y = (e) => {
+	let t = m(e, "theme", "light");
+	return _(t) ? t : "light";
+}, b = (e) => e === "dark" ? "light" : "dark", x = (e) => e in p, S = (e) => e === "auto" || e === "reduced", C = (e) => ({
+	"--kapi-font": p[e.font] ?? p.nunito,
+	...e.accent ? { "--kapi-primary": e.accent } : {}
+}), w = i({
+	theme: "light",
+	preference: "light",
+	accent: "",
+	font: "nunito",
+	motion: "auto",
+	setTheme: () => {},
+	setPreference: () => {},
+	toggle: () => {},
+	setAccent: () => {},
+	setFont: () => {},
+	setMotion: () => {},
+	toggleMotion: () => {}
+}), T = ({ namespace: e } = {}) => {
+	let t = c(() => d(e), [e]), [n, i] = l(() => y(e)), o = v(n, r(u)), [f, p] = l(() => m(e, "accent", "")), [g, _] = l(() => {
+		let t = m(e, "font", "nunito");
+		return x(t) ? t : "nunito";
+	}), [C, w] = l(() => {
+		let t = m(e, "motion", "auto");
+		return S(t) ? t : "auto";
+	}), [T, E] = l(e);
+	if (T !== e) {
+		E(e), i(y(e)), p(m(e, "accent", ""));
+		let t = m(e, "font", "nunito");
+		_(x(t) ? t : "nunito");
+		let n = m(e, "motion", "auto");
+		w(S(n) ? n : "auto");
+	}
+	s(() => h(t.theme, n), [t, n]), s(() => h(t.accent, f), [t, f]), s(() => h(t.font, g), [t, g]), s(() => h(t.motion, C), [t, C]);
+	let D = a(() => i(b(o)), [o]), O = a((e) => i(e), []), k = a((e) => p(e || ""), []), A = a(() => w((e) => e === "reduced" ? "auto" : "reduced"), []);
+	return c(() => ({
+		theme: o,
+		preference: n,
+		accent: f,
+		font: g,
+		motion: C,
+		setTheme: O,
+		setPreference: i,
+		toggle: D,
+		setAccent: k,
+		setFont: _,
+		setMotion: w,
+		toggleMotion: A
+	}), [
+		o,
+		n,
+		f,
+		g,
+		C,
+		O,
+		D,
+		k,
+		A
+	]);
+}, E = () => o(w);
+//#endregion
+export { u as DARK_SCHEME_QUERY, p as FONTS, w as KapiThemeContext, f as LEGACY_THEME_KEYS, x as isFontKey, S as isMotion, g as isTheme, _ as isThemePreference, y as readThemePreference, v as resolveTheme, C as themeRootStyle, d as themeStorageKeys, b as toggledPreference, E as useKapiTheme, T as useKapiThemeState };

package/dist/hooks/useMediaQuery.d.ts

@@ -0,0 +1,6 @@
+/** Breakpoint móvil del shell (mantener sincronizado con shell.css). */
+export declare const SHELL_MOBILE_QUERY = "(max-width: 768px)";
+/** `matchMedia` seguro (SSR / jsdom sin matchMedia → false). */
+export declare const matchesQuery: (query: string) => boolean;
+/** true mientras el viewport cumple la media query. */
+export declare const useMediaQuery: (query: string) => boolean;

package/dist/hooks/useMediaQuery.js

@@ -0,0 +1,13 @@
+"use client";
+import { useEffect as e, useState as t } from "react";
+//#region src/hooks/useMediaQuery.ts
+var n = "(max-width: 768px)", r = (e) => typeof window < "u" && typeof window.matchMedia == "function" && window.matchMedia(e).matches, i = (n) => {
+	let [i, a] = t(() => r(n));
+	return e(() => {
+		if (typeof window.matchMedia != "function") return;
+		let e = window.matchMedia(n), t = () => a(e.matches);
+		return t(), e.addEventListener("change", t), () => e.removeEventListener("change", t);
+	}, [n]), i;
+};
+//#endregion
+export { n as SHELL_MOBILE_QUERY, r as matchesQuery, i as useMediaQuery };

package/dist/hooks/useObjectUrl.d.ts

@@ -0,0 +1,6 @@
+/**
+ * URL temporal (`blob:`) para mostrar o descargar un Blob. Se revoca al cambiar de Blob y al
+ * desmontar; con `null`/`undefined` devuelve `null`. El primer render con un Blob nuevo devuelve
+ * `null`: la URL se crea en un efecto (así StrictMode no la revoca y la deja en uso).
+ */
+export declare const useObjectUrl: (source: Blob | null | undefined) => string | null;

package/dist/hooks/useObjectUrl.js

@@ -0,0 +1,19 @@
+"use client";
+import { useEffect as e, useState as t } from "react";
+//#region src/hooks/useObjectUrl.ts
+var n = (n) => {
+	let [r, i] = t(null);
+	return e(() => {
+		if (!n || typeof URL.createObjectURL != "function") {
+			i(null);
+			return;
+		}
+		let e = URL.createObjectURL(n);
+		return i({
+			source: n,
+			url: e
+		}), () => URL.revokeObjectURL(e);
+	}, [n]), r && n && r.source === n ? r.url : null;
+};
+//#endregion
+export { n as useObjectUrl };

package/dist/hooks/useOnlineStatus.d.ts

@@ -0,0 +1,7 @@
+import { type OnlineStatus } from "./onlineStatusLogic";
+/**
+ * ¿Hay conexión? Sigue los eventos `online`/`offline` de la ventana. En SSR devuelve conectado.
+ * `since`: instante (`Date.now()`) del último cambio observado, o `null` si no cambió.
+ * Ojo: `navigator.onLine === true` sólo garantiza red local, no que el servidor responda.
+ */
+export declare const useOnlineStatus: () => OnlineStatus;

package/dist/hooks/useOnlineStatus.js

@@ -0,0 +1,7 @@
+"use client";
+import { SERVER_ONLINE_STATUS as e, createOnlineStore as t } from "./onlineStatusLogic.js";
+import { useSyncExternalStore as n } from "react";
+//#region src/hooks/useOnlineStatus.ts
+var r = null, i = () => r ??= t(), a = (e) => i().subscribe(e), o = () => i().getSnapshot(), s = () => e, c = () => n(a, o, s);
+//#endregion
+export { c as useOnlineStatus };

package/dist/hooks/usePersistentState.d.ts

@@ -0,0 +1,19 @@
+import { type Dispatch, type SetStateAction } from "react";
+export type PersistentStateOptions = {
+    /** Versión del esquema guardado; si no coincide se descarta lo guardado. Default 1. */
+    version?: number;
+    /**
+     * Namespace de la clave: con él se guarda en `${namespace}:${key}` (como las claves del design system,
+     * p. ej. `kapi:theme`), así dos apps en el mismo origen no se pisan. Sin él la clave queda tal
+     * cual (compatible con lo guardado antes).
+     */
+    namespace?: string;
+};
+/**
+ * Estado persistido en localStorage (seguro en SSR y con storage bloqueado).
+ * Con `key = null` es estado en memoria puro, sin tocar el storage. Con `options.namespace` la
+ * clave real es `${namespace}:${key}`.
+ */
+export declare const usePersistentState: <T>(rawKey: string | null, initialValue: T, options?: PersistentStateOptions) => [T, Dispatch<SetStateAction<T>>, {
+    clear: () => void;
+}];

package/dist/hooks/usePersistentState.js

@@ -0,0 +1,37 @@
+"use client";
+import { storageKey as e } from "./storageLogic.js";
+import { parseStored as t, serializeStored as n } from "./persistentStateLogic.js";
+import { useCallback as r, useEffect as i, useRef as a, useState as o } from "react";
+//#region src/hooks/usePersistentState.ts
+var s = (e, n, r) => {
+	if (typeof window > "u") return r;
+	try {
+		return t(window.localStorage.getItem(e), n, r);
+	} catch {
+		return r;
+	}
+}, c = (t, c, l) => {
+	let u = l?.version ?? 1, d = l?.namespace, f = t === null || !d ? t : e(d, t), [p, m] = o(() => f === null ? c : s(f, u, c)), h = a(f);
+	return i(() => {
+		h.current !== f && (h.current = f, m(f === null ? c : s(f, u, c)));
+	}, [f, u]), i(() => {
+		if (f !== null && typeof window < "u" && h.current === f) try {
+			window.localStorage.setItem(f, n(p, u));
+		} catch {}
+	}, [
+		f,
+		p,
+		u
+	]), [
+		p,
+		m,
+		{ clear: r(() => {
+			if (f !== null && typeof window < "u") try {
+				window.localStorage.removeItem(f);
+			} catch {}
+			m(c);
+		}, [f]) }
+	];
+};
+//#endregion
+export { c as usePersistentState };

package/dist/hooks/usePlacement.d.ts

@@ -0,0 +1,36 @@
+import { type CSSProperties, type RefObject } from "react";
+import { type KapiPlacePopoverOptions, type KapiPopoverAnchor, type KapiPopoverPlacement, type KapiPopoverSize } from "../components/overlays/popoverLogic";
+export type UsePlacementOptions = KapiPlacePopoverOptions & {
+    /** Sólo se posiciona (y escucha scroll/resize) mientras está abierto. */
+    open: boolean;
+    /** Condición extra (p. ej. que el portal ya tenga raíz). Default `true`. */
+    enabled?: boolean;
+    /** Elemento ancla, o función que devuelve el rect/punto/`null` (sin ancla). */
+    anchor: RefObject<HTMLElement | null> | (() => KapiPopoverAnchor);
+    /** El elemento flotante: se mide (`offsetWidth/Height`) y se observa su tamaño. */
+    floatingRef: RefObject<HTMLElement | null>;
+    /** Tamaño a usar mientras no hay medida (o siempre, con `measure: false`). */
+    estimate?: KapiPopoverSize | undefined;
+    /** Medir el elemento flotante. Default `true`. */
+    measure?: boolean;
+    /**
+     * Ocultar (`visibility: hidden`) hasta la primera medición. Default `true`. Los menús que toman el
+     * foco al abrir lo apagan: un elemento oculto no puede recibir foco.
+     */
+    hideUntilPlaced?: boolean;
+};
+export type UsePlacementResult = {
+    /** `null` hasta la primera medición (y con `open` en false). */
+    placement: KapiPopoverPlacement | null;
+    /** `top`/`left`/`width`/`minWidth` listos para `position: fixed`; oculto hasta medir. */
+    style: CSSProperties;
+    /** Recalcula ya (p. ej. si cambió el contenido sin cambiar de tamaño observable). */
+    update: () => void;
+};
+/**
+ * Posiciona un elemento flotante con el motor `placePopover`: mide el ancla y el flotante (o usa
+ * `estimate`), se reubica con scroll/resize (`onViewportChange`, uno por frame) y con cambios de
+ * tamaño (`ResizeObserver`). La primera medición es sincrónica en el layout effect; una guarda de
+ * igualdad evita re-renders en loop; mientras no hay medida, `style` lo deja oculto.
+ */
+export declare function usePlacement({ open, enabled, anchor, floatingRef, estimate, measure, hideUntilPlaced, ...place }: UsePlacementOptions): UsePlacementResult;

package/dist/hooks/usePlacement.js

@@ -0,0 +1,84 @@
+"use client";
+import { placePopover as e, samePlacement as t } from "../components/overlays/popoverLogic.js";
+import { onViewportChange as n } from "./rafThrottle.js";
+import { useCallback as r, useLayoutEffect as i, useRef as a, useState as o } from "react";
+//#region src/hooks/usePlacement.ts
+var s = (e) => typeof e == "object" ? `max:${e.max}` : String(e);
+function c({ open: c, enabled: l = !0, anchor: u, floatingRef: d, estimate: f, measure: p = !0, hideUntilPlaced: m = !0, ...h }) {
+	let [g, _] = o(null), v = a({
+		anchor: u,
+		floatingRef: d,
+		estimate: f,
+		measure: p,
+		place: h
+	});
+	i(() => {
+		v.current = {
+			anchor: u,
+			floatingRef: d,
+			estimate: f,
+			measure: p,
+			place: h
+		};
+	});
+	let y = r(() => {
+		let { anchor: n, floatingRef: r, estimate: i, measure: a, place: o } = v.current, s;
+		if (typeof n == "function") s = n();
+		else if (n.current) s = n.current.getBoundingClientRect();
+		else return;
+		let c = r.current, l = a && c ? {
+			width: c.offsetWidth,
+			height: c.offsetHeight
+		} : null, u = l && (l.width > 0 || l.height > 0 || !i) ? l : i ?? {
+			width: 0,
+			height: 0
+		}, d = e(s, u, {
+			width: window.innerWidth,
+			height: window.innerHeight
+		}, o);
+		_((e) => t(e, d) ? e : d);
+	}, []), b = [
+		h.side,
+		h.align,
+		h.offset,
+		h.margin,
+		String(h.flip),
+		String(h.shift),
+		h.mainMin,
+		s(h.width),
+		h.dir,
+		h.fallback?.x,
+		h.fallback?.y,
+		f?.width,
+		f?.height,
+		p
+	].join("|");
+	return i(() => {
+		if (!c || !l) {
+			_(null);
+			return;
+		}
+		y();
+		let e = n(y), t = typeof ResizeObserver > "u" ? null : new ResizeObserver(() => y()), { anchor: r, floatingRef: i } = v.current;
+		return i.current && t?.observe(i.current), typeof r != "function" && r.current && t?.observe(r.current), () => {
+			e(), t?.disconnect();
+		};
+	}, [
+		c,
+		l,
+		b,
+		y
+	]), {
+		placement: g,
+		style: {
+			top: g?.top ?? 0,
+			left: g?.left ?? 0,
+			width: g?.width,
+			minWidth: g?.minWidth,
+			visibility: g || !m ? void 0 : "hidden"
+		},
+		update: y
+	};
+}
+//#endregion
+export { c as usePlacement };