@kapiuara/ui 0.0.0-stage → 0.1.0

package/dist/hooks/focusLogic.d.ts

@@ -0,0 +1,18 @@
+/** Selector de elementos enfocables con Tab (sin `tabindex="-1"` ni deshabilitados). */
+export declare const FOCUSABLE_SELECTOR: string;
+/** Elementos enfocables con Tab dentro de `container`, en orden del DOM (ignora los de subárboles `inert`). */
+export declare const focusableWithin: (container: Element | null) => HTMLElement[];
+/**
+ * Índice a enfocar al apretar Tab dentro de una trampa de foco (con vuelta). `current` -1 = el foco
+ * está en el contenedor u otro lado: Tab va al primero y Shift+Tab al último. -1 si no hay enfocables.
+ */
+export declare const nextTrapIndex: (count: number, current: number, shift: boolean) => number;
+/**
+ * Atrapa Tab dentro de `container`: mueve el foco al siguiente/anterior enfocable con vuelta. Sin
+ * enfocables, deja el foco en el contenedor. Devuelve `true` si manejó la tecla.
+ */
+export declare const trapTabKey: (e: {
+    key: string;
+    shiftKey: boolean;
+    preventDefault: () => void;
+}, container: HTMLElement | null) => boolean;

package/dist/hooks/focusLogic.js

@@ -0,0 +1,17 @@
+//#region src/hooks/focusLogic.ts
+var e = [
+	"a[href]",
+	"button:not([disabled])",
+	"input:not([disabled]):not([type='hidden'])",
+	"select:not([disabled])",
+	"textarea:not([disabled])",
+	"[tabindex]:not([tabindex='-1'])",
+	"[contenteditable='true']"
+].join(","), t = (t) => t ? Array.from(t.querySelectorAll(e)).filter((e) => !e.closest("[inert]") && e.tabIndex >= 0) : [], n = (e, t, n) => e === 0 ? -1 : t < 0 ? n ? e - 1 : 0 : n ? (t - 1 + e) % e : (t + 1) % e, r = (e, r) => {
+	if (e.key !== "Tab" || !r) return !1;
+	e.preventDefault();
+	let i = t(r), a = i.indexOf(document.activeElement), o = n(i.length, a, e.shiftKey);
+	return (o < 0 ? r : i[o])?.focus(), !0;
+};
+//#endregion
+export { e as FOCUSABLE_SELECTOR, t as focusableWithin, n as nextTrapIndex, r as trapTabKey };

package/dist/hooks/growOriginLogic.d.ts

@@ -0,0 +1,22 @@
+/** Coordenadas de viewport del centro del disparador. */
+export type GrowOrigin = {
+    x: number;
+    y: number;
+};
+export type GrowRect = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+/** Centro de un rect (típicamente `getBoundingClientRect()` del botón disparador). */
+export declare const rectCenter: (rect: GrowRect) => GrowOrigin;
+/**
+ * Expresa el punto (viewport) en coordenadas LOCALES a la tarjeta, acotado a
+ * `[0, width] × [0, height]`: un disparador lejos de la tarjeta igual da un
+ * `transform-origin` razonable (el borde más cercano).
+ */
+export declare const originWithinCard: (point: GrowOrigin, cardRect: GrowRect) => {
+    x: number;
+    y: number;
+};

package/dist/hooks/growOriginLogic.js

@@ -0,0 +1,10 @@
+//#region src/hooks/growOriginLogic.ts
+var e = (e) => ({
+	x: e.left + e.width / 2,
+	y: e.top + e.height / 2
+}), t = (e, t) => Math.min(Math.max(e, 0), Math.max(t, 0)), n = (e, n) => ({
+	x: t(e.x - n.left, n.width),
+	y: t(e.y - n.top, n.height)
+});
+//#endregion
+export { n as originWithinCard, e as rectCenter };

package/dist/hooks/hotkeyLogic.d.ts

@@ -0,0 +1,22 @@
+/** Pure key-combo parsing/matching for `useHotkey`. */
+export type HotkeyCombo = {
+    /** Ctrl on Windows/Linux, Cmd on macOS (either one satisfies it). */
+    mod: boolean;
+    ctrl: boolean;
+    meta: boolean;
+    alt: boolean;
+    shift: boolean;
+    /** Lowercased `KeyboardEvent.key`. */
+    key: string;
+};
+export type KeyEventLike = {
+    key: string;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    altKey: boolean;
+    shiftKey: boolean;
+};
+/** Parse "mod+k", "ctrl+shift+p", "alt+/" ... Last token is the key. Returns null when invalid. */
+export declare const parseHotkey: (combo: string) => HotkeyCombo | null;
+/** Whether a keyboard event satisfies the combo (modifiers must match exactly). */
+export declare const matchesHotkey: (event: KeyEventLike, combo: HotkeyCombo) => boolean;

package/dist/hooks/hotkeyLogic.js

@@ -0,0 +1,32 @@
+//#region src/hooks/hotkeyLogic.ts
+var e = {
+	esc: "escape",
+	space: " ",
+	spacebar: " ",
+	up: "arrowup",
+	down: "arrowdown",
+	left: "arrowleft",
+	right: "arrowright"
+}, t = (t) => {
+	let n = t.toLowerCase().split("+").map((e) => e.trim());
+	n.length > 1 && n[n.length - 1] === "" && n[n.length - 2] === "" && n.splice(-2, 2, "+");
+	let r = n.pop();
+	if (!r) return null;
+	let i = {
+		mod: !1,
+		ctrl: !1,
+		meta: !1,
+		alt: !1,
+		shift: !1,
+		key: e[r] ?? r
+	};
+	for (let e of n) if (e === "mod") i.mod = !0;
+	else if (e === "ctrl" || e === "control") i.ctrl = !0;
+	else if (e === "meta" || e === "cmd" || e === "command") i.meta = !0;
+	else if (e === "alt" || e === "option") i.alt = !0;
+	else if (e === "shift") i.shift = !0;
+	else return null;
+	return i;
+}, n = (e, t) => e.key.toLowerCase() !== t.key || e.altKey !== t.alt || e.shiftKey !== t.shift ? !1 : t.mod ? e.ctrlKey !== e.metaKey : e.ctrlKey === t.ctrl && e.metaKey === t.meta;
+//#endregion
+export { n as matchesHotkey, t as parseHotkey };

package/dist/hooks/index.d.ts

@@ -0,0 +1,49 @@
+export { useDragScroll } from "./useDragScroll";
+export type { UseDragScrollOptions } from "./useDragScroll";
+export { useGlobalRightClick } from "./useGlobalRightClick";
+export type { UseGlobalRightClickOptions } from "./useGlobalRightClick";
+export { FONTS, KapiThemeContext, DARK_SCHEME_QUERY, resolveTheme, themeStorageKeys, themeRootStyle, useKapiTheme, useKapiThemeState } from "./useKapiTheme";
+export type { KapiFontKey, KapiMotion, KapiTheme, KapiThemePreference, KapiThemeState, KapiThemeStateOptions } from "./useKapiTheme";
+export { DEFAULT_STORAGE_NAMESPACE, storageKey } from "./storageLogic";
+export { clampMenuPosition } from "./rightClick";
+export { useUnsavedGuard, unsavedGuardHandler, DEFAULT_UNSAVED_GUARD_LABELS } from "./useUnsavedGuard";
+export type { BeforeUnloadLike, UnsavedGuard, UnsavedGuardDialogProps, UnsavedGuardLabels, UnsavedGuardOptions } from "./useUnsavedGuard";
+export { KAPI_ROOT_SELECTOR, resolveKapiRoot, useKapiRoot } from "./kapiRoot";
+export { REDUCED_MOTION_QUERY, prefersReducedMotion } from "./reducedMotion";
+export { SHELL_MOBILE_QUERY, matchesQuery, useMediaQuery } from "./useMediaQuery";
+export { useHotkey } from "./useHotkey";
+export type { UseHotkeyOptions } from "./useHotkey";
+export { usePersistentState } from "./usePersistentState";
+export type { PersistentStateOptions } from "./usePersistentState";
+export { serializeStored, parseStored } from "./persistentStateLogic";
+export type { Stored } from "./persistentStateLogic";
+export { useRecent } from "./useRecent";
+export type { UseRecentOptions, UseRecentResult } from "./useRecent";
+export { addRecentEntry, removeRecentEntry } from "./recentLogic";
+export type { RecentEntry } from "./recentLogic";
+export { useGrowOrigin } from "./useGrowOrigin";
+export { rectCenter, originWithinCard } from "./growOriginLogic";
+export type { GrowOrigin, GrowRect } from "./growOriginLogic";
+export { useScrollCollapse } from "./useScrollCollapse";
+export type { ScrollCollapseResult } from "./useScrollCollapse";
+export { collapsedFromIntersection, normalizeRootMargin, DEFAULT_ROOT_MARGIN } from "./scrollCollapseLogic";
+export type { ScrollCollapseOptions } from "./scrollCollapseLogic";
+export { useSlidingIndicator } from "./useSlidingIndicator";
+export type { UseSlidingIndicatorOptions, UseSlidingIndicatorResult } from "./useSlidingIndicator";
+export { slidingIndicatorBox } from "./slidingIndicatorLogic";
+export type { SlidingIndicatorBox } from "./slidingIndicatorLogic";
+export { rafThrottle, onViewportChange } from "./rafThrottle";
+export type { FrameScheduler, RafThrottled, ViewportChangeOptions, ViewportEventTarget } from "./rafThrottle";
+export { usePlacement } from "./usePlacement";
+export type { UsePlacementOptions, UsePlacementResult } from "./usePlacement";
+export { useOnlineStatus } from "./useOnlineStatus";
+export { createOnlineStore, readOnline, SERVER_ONLINE_STATUS } from "./onlineStatusLogic";
+export type { OnlineEventTarget, OnlineStatus, OnlineStore, OnlineStoreOptions } from "./onlineStatusLogic";
+export { useObjectUrl } from "./useObjectUrl";
+export { downloadBlob, fileKind, fileNameFromContentDisposition, fileNameFromUrl, formatFileSize } from "./downloadLogic";
+export type { KapiFileKind } from "./downloadLogic";
+export { formatDate, formatRelativeTime, isoDateTime } from "./dateFormat";
+export { useScrollEdges } from "./useScrollEdges";
+export type { UseScrollEdgesOptions, UseScrollEdgesResult } from "./useScrollEdges";
+export { DEFAULT_PAGE_FRACTION, DEFAULT_SCROLL_EDGE_TOLERANCE, maxScroll, pageSize, pageTarget, revealTarget, sameScrollEdges, scrollEdges } from "./scrollEdgesLogic";
+export type { KapiScrollAxis, ScrollEdges, ScrollMetrics } from "./scrollEdgesLogic";

package/dist/hooks/kapiRoot.d.ts

@@ -0,0 +1,16 @@
+/** Selector de la raíz de tokens/tema del design system. */
+export declare const KAPI_ROOT_SELECTOR = ".kapi";
+/**
+ * Nodo donde montar overlays (menús, popovers) para que hereden los tokens del tema.
+ *
+ * Si `from` está dentro de un `<dialog open>` (modal nativo vía `showModal()`), se monta DENTRO
+ * de ese dialog: el modal vive en el top-layer y deja todo lo de afuera `inert`, así que un overlay
+ * portaleado a `.kapi` (hermano del dialog) quedaría pintado debajo y sin poder clickearse.
+ * El dialog igual está dentro de `.kapi`, por lo que hereda los tokens igual.
+ *
+ * Si no hay dialog, prefiere el `.kapi` ancestro de `from`; si no hay, el primero del
+ * documento; último recurso: `body`. `null` fuera del navegador (SSR).
+ */
+export declare const resolveKapiRoot: (from?: Element | null) => HTMLElement | null;
+/** Destino de portal: se resuelve tras montar (seguro para SSR). */
+export declare const useKapiRoot: () => HTMLElement | null;

package/dist/hooks/kapiRoot.js

@@ -0,0 +1,9 @@
+"use client";
+import { useEffect as e, useState as t } from "react";
+//#region src/hooks/kapiRoot.ts
+var n = ".kapi", r = (e) => typeof document > "u" ? null : e?.closest("dialog[open]") || (e?.closest(".kapi") ?? document.querySelector(".kapi") ?? document.body), i = () => {
+	let [n, i] = t(null);
+	return e(() => i(r()), []), n;
+};
+//#endregion
+export { n as KAPI_ROOT_SELECTOR, r as resolveKapiRoot, i as useKapiRoot };

package/dist/hooks/onlineStatusLogic.d.ts

@@ -0,0 +1,31 @@
+/** Conectado o no, y cuándo cambió por última vez (`Date.now()`); `null` si no cambió desde la carga. */
+export type OnlineStatus = {
+    online: boolean;
+    since: number | null;
+};
+/** Lo mínimo de `window` que usa el store (inyectable en tests). */
+export type OnlineEventTarget = {
+    addEventListener: (type: string, fn: () => void) => void;
+    removeEventListener: (type: string, fn: () => void) => void;
+};
+export type OnlineStoreOptions = {
+    target?: OnlineEventTarget | null;
+    read?: () => boolean;
+    now?: () => number;
+};
+export type OnlineStore = {
+    subscribe: (onChange: () => void) => () => void;
+    getSnapshot: () => OnlineStatus;
+};
+/** Snapshot del servidor (SSR): se asume conectado. */
+export declare const SERVER_ONLINE_STATUS: OnlineStatus;
+/** `navigator.onLine`, o `true` si no hay navigator (SSR) o no expone el dato. */
+export declare const readOnline: (nav?: {
+    onLine?: boolean;
+} | undefined) => boolean;
+/**
+ * Store de conexión: escucha `online`/`offline` en `target` (default `window`). El snapshot se
+ * recalcula al leerlo y conserva la MISMA referencia mientras el valor no cambie (requisito de
+ * `useSyncExternalStore`); al cambiar, guarda el instante en `since`.
+ */
+export declare const createOnlineStore: ({ target, read, now }?: OnlineStoreOptions) => OnlineStore;

package/dist/hooks/onlineStatusLogic.js

@@ -0,0 +1,28 @@
+//#region src/hooks/onlineStatusLogic.ts
+var e = Object.freeze({
+	online: !0,
+	since: null
+}), t = (e = n()) => e?.onLine ?? !0;
+function n() {
+	return typeof navigator > "u" ? void 0 : navigator;
+}
+var r = ({ target: e = typeof window > "u" ? null : window, read: n = () => t(), now: r = Date.now } = {}) => {
+	let i = {
+		online: n(),
+		since: null
+	};
+	return {
+		subscribe: (t) => e ? (e.addEventListener("online", t), e.addEventListener("offline", t), () => {
+			e.removeEventListener("online", t), e.removeEventListener("offline", t);
+		}) : () => {},
+		getSnapshot: () => {
+			let e = n();
+			return e !== i.online && (i = {
+				online: e,
+				since: r()
+			}), i;
+		}
+	};
+};
+//#endregion
+export { e as SERVER_ONLINE_STATUS, r as createOnlineStore, t as readOnline };

package/dist/hooks/persistentStateLogic.d.ts

@@ -0,0 +1,12 @@
+/** Forma guardada en storage: versión + dato. */
+export type Stored<T> = {
+    v: number;
+    data: T;
+};
+/** Serializa el dato junto con su versión. */
+export declare const serializeStored: <T>(data: T, version: number) => string;
+/**
+ * Lee un valor guardado. Devuelve `fallback` ante cualquier problema:
+ * sin dato, JSON inválido, forma incorrecta o versión distinta.
+ */
+export declare const parseStored: <T>(raw: string | null | undefined, version: number, fallback: T) => T;

package/dist/hooks/persistentStateLogic.js

@@ -0,0 +1,17 @@
+//#region src/hooks/persistentStateLogic.ts
+var e = (e, t) => JSON.stringify({
+	v: t,
+	data: e
+}), t = (e, t, n) => {
+	if (e == null) return n;
+	try {
+		let r = JSON.parse(e);
+		if (typeof r != "object" || !r) return n;
+		let i = r;
+		return i.v !== t || !("data" in i) ? n : i.data;
+	} catch {
+		return n;
+	}
+};
+//#endregion
+export { t as parseStored, e as serializeStored };

package/dist/hooks/rafThrottle.d.ts

@@ -0,0 +1,33 @@
+/** Planificador de frames inyectable (tests): `requestAnimationFrame` en el navegador. */
+export type FrameScheduler = {
+    request: (cb: () => void) => number;
+    cancel: (id: number) => void;
+};
+/** Función throttleada a un frame: `cancel` descarta lo pendiente, `flush` lo corre ya. */
+export type RafThrottled<A extends unknown[]> = ((...args: A) => void) & {
+    cancel: () => void;
+    flush: () => void;
+};
+/**
+ * Coalesce las llamadas a `fn` en UNA por frame, con los últimos argumentos. Pensado para trabajo
+ * disparado por scroll/resize/pointermove (lecturas de layout + escrituras de estilo o estado):
+ * muchos eventos por frame → un solo recálculo justo antes de pintar.
+ */
+export declare const rafThrottle: <A extends unknown[]>(fn: (...args: A) => void, scheduler?: FrameScheduler) => RafThrottled<A>;
+/** Lo mínimo de `window` que usa `onViewportChange` (inyectable en tests). */
+export type ViewportEventTarget = {
+    addEventListener: (type: string, fn: () => void, options: AddEventListenerOptions) => void;
+    removeEventListener: (type: string, fn: () => void, options: EventListenerOptions) => void;
+};
+export type ViewportChangeOptions = {
+    /** Default: `window`. */
+    target?: ViewportEventTarget;
+    scheduler?: FrameScheduler;
+};
+/**
+ * Corre `fn` a lo sumo una vez por frame ante cualquier scroll (fase de captura: también los
+ * scrollers anidados) o resize. Los listeners son pasivos (nunca llaman a preventDefault).
+ * Devuelve el cleanup: saca los listeners y cancela el frame pendiente. Pensado para reubicar
+ * overlays posicionados con coordenadas de viewport.
+ */
+export declare const onViewportChange: (fn: () => void, options?: ViewportChangeOptions) => (() => void);

package/dist/hooks/rafThrottle.js

@@ -0,0 +1,33 @@
+//#region src/hooks/rafThrottle.ts
+var e = () => typeof requestAnimationFrame == "function" ? {
+	request: (e) => requestAnimationFrame(e),
+	cancel: (e) => cancelAnimationFrame(e)
+} : {
+	request: (e) => setTimeout(e, 16),
+	cancel: (e) => clearTimeout(e)
+}, t = (t, n = e()) => {
+	let r = null, i = null, a = () => {
+		r = null;
+		let e = i;
+		i = null, e && t(...e);
+	}, o = ((...e) => {
+		i = e, r === null && (r = n.request(a));
+	});
+	return o.cancel = () => {
+		r !== null && n.cancel(r), r = null, i = null;
+	}, o.flush = () => {
+		r !== null && (n.cancel(r), a());
+	}, o;
+}, n = (e, n = {}) => {
+	let r = n.target ?? (typeof window > "u" ? null : window);
+	if (!r) return () => {};
+	let i = t(e, n.scheduler), a = () => i();
+	return r.addEventListener("scroll", a, {
+		capture: !0,
+		passive: !0
+	}), r.addEventListener("resize", a, { passive: !0 }), () => {
+		r.removeEventListener("scroll", a, { capture: !0 }), r.removeEventListener("resize", a, {}), i.cancel();
+	};
+};
+//#endregion
+export { n as onViewportChange, t as rafThrottle };

package/dist/hooks/recentLogic.d.ts

@@ -0,0 +1,9 @@
+export type RecentEntry = {
+    id: string;
+    label: string;
+    meta?: Record<string, unknown>;
+    at: number;
+};
+/** Agrega al frente, deduplica por id y recorta a `max` (descarta los más viejos). */
+export declare const addRecentEntry: (list: RecentEntry[], entry: Omit<RecentEntry, "at">, max: number, now: number) => RecentEntry[];
+export declare const removeRecentEntry: (list: RecentEntry[], id: string) => RecentEntry[];

package/dist/hooks/recentLogic.js

@@ -0,0 +1,10 @@
+//#region src/hooks/recentLogic.ts
+var e = (e, t, n, r) => {
+	let i = e.filter((e) => e.id !== t.id);
+	return [{
+		...t,
+		at: r
+	}, ...i].slice(0, Math.max(0, n));
+}, t = (e, t) => e.filter((e) => e.id !== t);
+//#endregion
+export { e as addRecentEntry, t as removeRecentEntry };

package/dist/hooks/reducedMotion.d.ts

@@ -0,0 +1,13 @@
+/** Media query del SO para movimiento reducido. */
+export declare const REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)";
+type MatchMediaLike = (query: string) => {
+    matches: boolean;
+};
+/**
+ * ¿Hay que reducir el movimiento? Única fuente de verdad en JS, espejo del gate de `kapi.css`:
+ * true si el SO pide `prefers-reduced-motion: reduce` O si el `.kapi` que contiene a
+ * `from` (o el primero del documento, sin `from`) tiene `data-motion="reduced"` (toggle in-app).
+ * `matchMedia` es inyectable para tests; `null` = no disponible (solo decide el toggle).
+ */
+export declare const prefersReducedMotion: (from?: Element | null, matchMedia?: MatchMediaLike | null) => boolean;
+export {};

package/dist/hooks/reducedMotion.js

@@ -0,0 +1,5 @@
+import { KAPI_ROOT_SELECTOR as e } from "./kapiRoot.js";
+//#region src/hooks/reducedMotion.ts
+var t = "(prefers-reduced-motion: reduce)", n = () => typeof window < "u" && typeof window.matchMedia == "function" ? (e) => window.matchMedia(e) : null, r = (t, r = n()) => r?.("(prefers-reduced-motion: reduce)").matches ? !0 : typeof document > "u" ? !1 : (t ? t.closest(e) : document.querySelector(e))?.getAttribute("data-motion") === "reduced";
+//#endregion
+export { t as REDUCED_MOTION_QUERY, r as prefersReducedMotion };

package/dist/hooks/rightClick.d.ts

@@ -0,0 +1,37 @@
+/** Elementos sobre los que el click derecho NO inicia drag (son interactivos). */
+export declare const INTERACTIVE_SELECTOR = "button, a, input, select, textarea, label, [role=button], [data-no-drag]";
+/** Píxeles que hay que mover (|dx|+|dy|) para considerar que es un drag y no un click. */
+export declare const DRAG_THRESHOLD = 4;
+/** Ventana (ms) entre dos clicks derechos para contarlos como "doble". */
+export declare const DOUBLE_CLICK_MS = 450;
+export declare const exceedsDragThreshold: (dx: number, dy: number) => boolean;
+export declare const isDoubleRightClick: (now: number, last: number) => boolean;
+/** Opciones del motor para un menú anclado a un punto: sin vuelta, acotado en ambos ejes. */
+export declare const POINT_MENU_PLACEMENT: {
+    readonly side: "bottom";
+    readonly align: "start";
+    readonly offset: 0;
+    readonly flip: false;
+    readonly shift: "both";
+};
+/** Clampea la posición de un menú flotante para que no se salga del viewport (wrapper de `placePopover`). */
+export declare const clampMenuPosition: (x: number, y: number, size: {
+    width: number;
+    height: number;
+}, viewport: {
+    width: number;
+    height: number;
+}, margin?: number) => {
+    left: number;
+    top: number;
+};
+/** Primer ancestro (incluido el nodo) que realmente scrollea en X o en Y. */
+export declare const findScrollableAncestor: (node: EventTarget | null) => HTMLElement | null;
+export declare const isInteractiveTarget: (target: EventTarget | null) => boolean;
+/**
+ * ¿Hay que suprimir el menú nativo de este `contextmenu`? En táctil, el long-press dispara
+ * `contextmenu` y el menú nativo (copiar, abrir enlace…) es lo único que hay: no se toca.
+ * Manda el `pointerType` del propio evento (Chrome lo emite como PointerEvent); si no viene,
+ * se usa el del último `pointerdown`.
+ */
+export declare const shouldInterceptContextMenu: (eventPointerType: string | undefined, lastPointerType: string | null) => boolean;

package/dist/hooks/rightClick.js

@@ -0,0 +1,30 @@
+import { placePopover as e } from "../components/overlays/popoverLogic.js";
+//#region src/hooks/rightClick.ts
+var t = "button, a, input, select, textarea, label, [role=button], [data-no-drag]", n = (e, t) => Math.abs(e) + Math.abs(t) > 4, r = (e, t) => t > 0 && e - t < 450, i = {
+	side: "bottom",
+	align: "start",
+	offset: 0,
+	flip: !1,
+	shift: "both"
+}, a = (t, n, r, a, o = 8) => {
+	let { left: s, top: c } = e({
+		x: t,
+		y: n
+	}, r, a, {
+		...i,
+		margin: o
+	});
+	return {
+		left: s,
+		top: c
+	};
+}, o = (e) => {
+	for (let t = e; t && t !== document.body; t = t.parentElement) {
+		if (!(t instanceof HTMLElement)) continue;
+		let e = getComputedStyle(t), n = /(auto|scroll)/.test(e.overflowY) && t.scrollHeight > t.clientHeight, r = /(auto|scroll)/.test(e.overflowX) && t.scrollWidth > t.clientWidth;
+		if (n || r) return t;
+	}
+	return null;
+}, s = (e) => e instanceof Element && e.closest("button, a, input, select, textarea, label, [role=button], [data-no-drag]") !== null, c = (e, t) => (e || t) !== "touch";
+//#endregion
+export { t as INTERACTIVE_SELECTOR, i as POINT_MENU_PLACEMENT, a as clampMenuPosition, n as exceedsDragThreshold, o as findScrollableAncestor, r as isDoubleRightClick, s as isInteractiveTarget, c as shouldInterceptContextMenu };

package/dist/hooks/scrollCollapseLogic.d.ts

@@ -0,0 +1,12 @@
+/** Lógica pura del header colapsable (el IntersectionObserver en sí no es testeable). */
+export type ScrollCollapseOptions = {
+    /** Contenedor con scroll; `null`/omitido = viewport. */
+    root?: Element | null;
+    /** rootMargin del observer (ej. "0px 0px 0px 0px"). */
+    rootMargin?: string;
+};
+export declare const DEFAULT_ROOT_MARGIN = "0px";
+/** El header está colapsado cuando el centinela ya no es visible. */
+export declare const collapsedFromIntersection: (isIntersecting: boolean) => boolean;
+/** Normaliza un rootMargin: vacío o solo espacios → valor por defecto. */
+export declare const normalizeRootMargin: (rootMargin?: string) => string;

package/dist/hooks/scrollCollapseLogic.js

@@ -0,0 +1,4 @@
+//#region src/hooks/scrollCollapseLogic.ts
+var e = "0px", t = (e) => !e, n = (e) => e?.trim() || "0px";
+//#endregion
+export { e as DEFAULT_ROOT_MARGIN, t as collapsedFromIntersection, n as normalizeRootMargin };

package/dist/hooks/scrollEdgesLogic.d.ts

@@ -0,0 +1,49 @@
+/** Eje de scroll. */
+export type KapiScrollAxis = "x" | "y";
+/** Geometría de scroll de un eje (los valores del navegador: pueden ser fraccionarios). */
+export type ScrollMetrics = {
+    /** `scrollLeft` / `scrollTop`. */
+    position: number;
+    /** `clientWidth` / `clientHeight`. */
+    clientSize: number;
+    /** `scrollWidth` / `scrollHeight`. */
+    scrollSize: number;
+};
+/** Qué bordes tienen más contenido fuera de vista. */
+export type ScrollEdges = {
+    start: boolean;
+    end: boolean;
+};
+/**
+ * Tolerancia en px. Los navegadores devuelven `scrollLeft` fraccionario con zoom o densidad no
+ * entera, mientras `scrollWidth`/`clientWidth` van redondeados: comparar con `===` fallaría.
+ */
+export declare const DEFAULT_SCROLL_EDGE_TOLERANCE = 1;
+/** Fracción del alto/ancho visible que avanza un "page" (el resto queda como solape de contexto). */
+export declare const DEFAULT_PAGE_FRACTION = 0.85;
+/** Máximo desplazamiento posible (nunca negativo). */
+export declare const maxScroll: ({ clientSize, scrollSize }: Pick<ScrollMetrics, "clientSize" | "scrollSize">) => number;
+/**
+ * ¿Hay más contenido antes (`start`) y/o después (`end`)? Sin desborde, ninguno. Un `position`
+ * fuera de rango (rebote elástico de iOS/macOS) cuenta como en el borde. Sólo LTR: en RTL el
+ * `scrollLeft` es negativo y su convención depende del navegador, así que no se interpreta acá.
+ */
+export declare const scrollEdges: (m: ScrollMetrics, tolerance?: number) => ScrollEdges;
+/** Igualdad estructural de bordes (guarda para no re-renderizar con el mismo resultado). */
+export declare const sameScrollEdges: (a: ScrollEdges, b: ScrollEdges) => boolean;
+/** Cuánto avanza un "page" (px, al menos 1). */
+export declare const pageSize: (clientSize: number, fraction?: number) => number;
+/**
+ * Posición destino de un "page" hacia atrás (`-1`) o adelante (`1`), acotada a `[0, max]`.
+ */
+export declare const pageTarget: (m: ScrollMetrics, direction: -1 | 1, fraction?: number) => number;
+/**
+ * Posición destino para dejar un ítem completamente visible con un margen, moviendo lo mínimo.
+ * `itemStart`/`itemEnd` son los bordes del ítem relativos al borde inicial de la zona visible
+ * (negativo = fuera por atrás; mayor a `clientSize` = fuera por adelante). Si ya está visible
+ * devuelve la posición actual; si es más grande que la zona visible, alinea su inicio.
+ */
+export declare const revealTarget: (m: ScrollMetrics, item: {
+    start: number;
+    end: number;
+}, padding?: number) => number;

package/dist/hooks/scrollEdgesLogic.js

@@ -0,0 +1,19 @@
+//#region src/hooks/scrollEdgesLogic.ts
+var e = 1, t = .85, n = ({ clientSize: e, scrollSize: t }) => Math.max(0, t - e), r = (e, t = 1) => {
+	let r = n(e);
+	return r <= t ? {
+		start: !1,
+		end: !1
+	} : {
+		start: e.position > t,
+		end: e.position < r - t
+	};
+}, i = (e, t) => e.start === t.start && e.end === t.end, a = (e, n = t) => Math.max(1, Math.round(e * n)), o = (e, r, i = t) => {
+	let o = e.position + r * a(e.clientSize, i);
+	return Math.min(n(e), Math.max(0, o));
+}, s = (e, t, r = 0) => {
+	let i = n(e), a = 0;
+	return t.start < r ? a = t.start - r : t.end > e.clientSize - r && (a = Math.min(t.end - (e.clientSize - r), t.start - r)), Math.min(i, Math.max(0, e.position + a));
+};
+//#endregion
+export { t as DEFAULT_PAGE_FRACTION, e as DEFAULT_SCROLL_EDGE_TOLERANCE, n as maxScroll, a as pageSize, o as pageTarget, s as revealTarget, i as sameScrollEdges, r as scrollEdges };

package/dist/hooks/slidingIndicatorLogic.d.ts

@@ -0,0 +1,25 @@
+export type SlidingIndicatorBox = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type BoxLike = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+/**
+ * Caja del indicador deslizante relativa al padding-box del contenedor (origen del `position:absolute`).
+ * Se calcula con rects de viewport + scroll + borde del contenedor, así sirve igual para layouts
+ * verticales, horizontales con scroll, y para ítems dentro de un wrapper intermedio.
+ */
+export declare const slidingIndicatorBox: (item: BoxLike, container: BoxLike, scroll?: {
+    left: number;
+    top: number;
+}, border?: {
+    left: number;
+    top: number;
+}) => SlidingIndicatorBox;
+export {};

package/dist/hooks/slidingIndicatorLogic.js

@@ -0,0 +1,15 @@
+//#region src/hooks/slidingIndicatorLogic.ts
+var e = (e, t, n = {
+	left: 0,
+	top: 0
+}, r = {
+	left: 0,
+	top: 0
+}) => ({
+	x: Math.round(e.left - t.left - r.left + n.left),
+	y: Math.round(e.top - t.top - r.top + n.top),
+	width: Math.round(e.width),
+	height: Math.round(e.height)
+});
+//#endregion
+export { e as slidingIndicatorBox };

package/dist/hooks/storageLogic.d.ts

@@ -0,0 +1,15 @@
+/** Namespace por defecto de las claves del design system. */
+export declare const DEFAULT_STORAGE_NAMESPACE = "kapi";
+/** Lo mínimo de `Storage` que se usa (inyectable para testear). */
+export type StorageLike = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+/** `${namespace}:${name}`; sin namespace (o vacío) usa `kapi`. */
+export declare const storageKey: (namespace: string | undefined, name: string) => string;
+/** `localStorage` si existe y se puede acceder (SSR o modo privado estricto → `null`). */
+export declare const defaultStorage: () => StorageLike | null;
+/**
+ * Migra una clave vieja a la nueva: si hay valor legacy y la nueva está vacía, lo copia; en
+ * cualquier caso borra la legacy (la nueva manda). Nunca tira: el storage puede fallar.
+ */
+export declare const migrateLegacy: (storage: StorageLike | null, legacyKey: string, newKey: string) => void;
+/** Lee `key` migrando antes `legacyKey` (si se pasa). `null` si no hay valor o falla el storage. */
+export declare const readWithLegacy: (storage: StorageLike | null, key: string, legacyKey?: string) => string | null;