@kapiuara/ui 0.0.0-stage → 0.1.0

package/dist/components/overlays/KapiOffcanvas.d.ts

@@ -0,0 +1,96 @@
+import { type ReactNode } from "react";
+import { type OffcanvasSide } from "./offcanvasSide";
+import "./KapiOffcanvas.css";
+import { type KapiRootProps } from "../rootProps";
+import type { KapiLabelsOverride } from "../labelsLogic";
+export declare const DEFAULT_OFFCANVAS_WIDTH = 520;
+export type KapiOffcanvasCompanion = {
+    /** Controlado. Con true el panel se acopla junto al drawer, en el mismo borde. */
+    open: boolean;
+    children: ReactNode;
+    title?: ReactNode;
+    subtitle?: ReactNode;
+    /** Ancho: number (px) o string CSS. Default 400. */
+    width?: number | string;
+    /** Zona fija inferior del panel acompañante. */
+    footer?: ReactNode;
+    /** X del encabezado: cierra sólo el acompañante (el padre pone `open: false`). */
+    onClose?: () => void;
+    closeLabel?: string;
+};
+/** `close` es la X del panel (sin `closeLabel`); `closePanel`, la del acompañante. */
+export type KapiOffcanvasLabels = {
+    resize: string;
+    close: string;
+    closePanel: string;
+};
+export declare const DEFAULT_OFFCANVAS_LABELS: KapiOffcanvasLabels;
+/**
+ * `className`/`style`/`id` (`KapiRootProps`) van al `<dialog>` (`.kapi-offc`, el contenedor que
+ * ubica las tarjetas); las variables calculadas (tamaño, empuje) ganan sobre `style`.
+ */
+export type KapiOffcanvasProps = KapiRootProps & {
+    /** Controlado. Al pasar a false corre la animación de salida y recién después se desmonta. */
+    open: boolean;
+    /** Pedido de cierre (X, click en el fondo, Escape). El padre pone `open={false}`. */
+    onClose: () => void;
+    /** Título del header del panel (también nombra al diálogo). */
+    title: ReactNode;
+    /** Texto secundario bajo el título. */
+    subtitle?: ReactNode | undefined;
+    /** Contenido del cuerpo del panel (con scroll propio). */
+    children?: ReactNode | undefined;
+    /** Zona fija inferior (botones). */
+    footer?: ReactNode | undefined;
+    /** Borde desde el que se abre. Default `"right"`. */
+    side?: OffcanvasSide | undefined;
+    /**
+     * Ancho de la tarjeta (sólo `left` / `right`): number (px) o string CSS. Default 520.
+     * En mobile ocupa `calc(100% - 20px)`. Se ignora en `top` / `bottom` (ocupan todo el ancho).
+     */
+    width?: number | string | undefined;
+    /** Alto de la tarjeta (sólo `top` / `bottom`): number (px) o string CSS. Default `"60vh"`. Se ignora en `left` / `right`. */
+    height?: number | string | undefined;
+    /** Cuánto se achica este panel por cada panel abierto encima (0.04 = 4 %). Default 0.04. */
+    pushRatio?: number | undefined;
+    /** Cuánto se corre a la izquierda (px) por nivel, para asomar como carta detrás. Default 16. */
+    pushOffset?: number | undefined;
+    /** Click en el fondo cierra. Default true. */
+    closeOnBackdrop?: boolean | undefined;
+    /** Escape cierra. Default true. */
+    closeOnEscape?: boolean | undefined;
+    /** Textos fijos (handle de redimensionar, la X del panel y la del acompañante sin `closeLabel`). */
+    labels?: KapiLabelsOverride<KapiOffcanvasLabels> | undefined;
+    /** Nombre accesible de la X. Gana sobre `labels.close` ("Cerrar"). */
+    closeLabel?: string | undefined;
+    /**
+     * Panel acompañante opcional, acoplado al lado INTERNO del drawer (a la izquierda de uno
+     * `right`, a la derecha de uno `left`), ambos visibles a la vez en el mismo `<dialog>`.
+     * Se ignora en `top` / `bottom`. En <900px se apila en columna (acompañante arriba).
+     */
+    companion?: KapiOffcanvasCompanion | undefined;
+    /** Se llama cuando terminó la animación de salida y el panel se desmontó. */
+    onExited?: (() => void) | undefined;
+    /** Ancho regulable arrastrando el borde interno (sólo `left` / `right`). Default false. */
+    resizable?: boolean | undefined;
+    /** Ancho mínimo (px) al redimensionar. Default 320. */
+    minWidth?: number | undefined;
+    /** Ancho máximo (px) al redimensionar. Default: 90 % del viewport al momento de arrastrar. */
+    maxWidth?: number | undefined;
+    /** Se llama con el ancho (px) en cada cambio por arrastre o teclado. */
+    onResize?: ((width: number) => void) | undefined;
+};
+/**
+ * Offcanvas: tarjeta flotante que entra desde un borde (`side`, default la
+ * derecha; también izquierda, arriba o abajo), sobre `<dialog>`
+ * nativo (`showModal()`): focus trap, Escape, `::backdrop`, `inert` del fondo y
+ * restauración de foco los da el navegador.
+ *
+ * Es APILABLE: abrir otro `KapiOffcanvas` mientras éste está abierto (anidado
+ * declarativamente, o vía `KapiOffcanvasStack` / `useKapiOffcanvasStack`) empuja
+ * este panel hacia atrás (escala + corrimiento, `pushRatio` / `pushOffset`). El
+ * orden visual lo resuelve el top-layer del navegador (sin z-index).
+ * El empuje aplica a `right` y `left` (espejado); en `top` / `bottom` los paneles
+ * apilados no se empujan entre sí (el apilado vertical queda fuera de alcance).
+ */
+export declare const KapiOffcanvas: ({ open, onExited, ...props }: KapiOffcanvasProps) => import("react").ReactPortal | null;

package/dist/components/overlays/KapiOffcanvas.js

@@ -0,0 +1,209 @@
+"use client";
+import { useLabels as e } from "../locale/KapiLocaleProvider.js";
+import { joinClasses as t } from "../rootProps.js";
+import { maxTransitionMs as n } from "./dialogUtils.js";
+import { getPortalRoot as r, useBackdropClose as i, useNativeDialog as a } from "./useNativeDialog.js";
+import { DEFAULT_PUSH_RATIO as o, depthOf as s, levelOf as c, offcanvasStackStore as l, phaseReducer as u, pushTransform as ee } from "./offcanvasStack.js";
+import { normalizeSide as te, pushForSide as ne, sideDataAttr as d, sizeVar as re } from "./offcanvasSide.js";
+import { companionDockClasses as ie, isCompanionActive as ae, resolveCompanionOrder as oe, resolveCompanionWidth as se } from "./offcanvasCompanion.js";
+import { resolveInitialWidth as ce, resolveMaxWidth as f, stepOffcanvasWidth as le, widthFromDrag as ue } from "./offcanvasResize.js";
+/* empty css                  */
+import { jsx as p, jsxs as m } from "react/jsx-runtime";
+import { useEffect as de, useId as h, useLayoutEffect as g, useReducer as _, useRef as v, useState as y, useSyncExternalStore as fe } from "react";
+import { X as b } from "lucide-react";
+import { createPortal as x } from "react-dom";
+var pe = 120, S = {
+	resize: "Redimensionar panel",
+	close: "Cerrar",
+	closePanel: "Cerrar panel"
+}, C = ({ stackId: r, phase: u, onEntered: _, onExited: x, onClose: C, title: w, subtitle: T, children: me, footer: E, side: he, width: D = 520, height: ge, pushRatio: _e = o, pushOffset: ve = 16, closeOnBackdrop: ye = !0, closeOnEscape: be = !0, closeLabel: xe, labels: Se, className: Ce, style: O, id: k, companion: A, resizable: we = !1, minWidth: j = 320, maxWidth: M, onResize: N }) => {
+	let P = e("offcanvas", S, Se), Te = xe ?? P.close, F = h(), I = h(), L = te(he), R = v(null), z = fe(l.subscribe, l.getSnapshot, l.getServerSnapshot), B = s(z, r), Ee = Math.max(0, c(z, r)), { scale: De, translateX: Oe } = ne(L, ee(B, _e, ve)), [V, ke] = y(() => ce(D, 520)), [Ae, H] = y(!1), U = v(null), W = v(N);
+	W.current = N;
+	let G = (e) => {
+		ke(e), e !== V && W.current?.(e);
+	}, je = (e) => {
+		if (e.button !== 0) return;
+		let t = R.current?.offsetWidth ?? V;
+		U.current = {
+			startX: e.clientX,
+			startWidth: t
+		}, e.currentTarget.setPointerCapture(e.pointerId), H(!0), e.preventDefault();
+	}, Me = (e) => {
+		let t = U.current;
+		if (!t) return;
+		let n = f(M, window.innerWidth);
+		G(ue(L, t.startWidth, t.startX, e.clientX, j, n));
+	}, K = (e) => {
+		U.current = null, e.currentTarget.hasPointerCapture(e.pointerId) && e.currentTarget.releasePointerCapture(e.pointerId), H(!1);
+	}, Ne = (e) => {
+		let t = f(M, window.innerWidth), n = le(L, V, e.key, j, t);
+		n !== null && (e.preventDefault(), e.stopPropagation(), G(n));
+	}, q = u === "open" ? C : void 0, { ref: Pe, dialogProps: Fe } = a({ onRequestClose: be ? q : void 0 }), J = i(ye ? q : void 0);
+	g(() => (l.dispatch({
+		type: "add",
+		id: r
+	}), () => l.dispatch({
+		type: "remove",
+		id: r
+	})), [r]);
+	let Y = v(_);
+	Y.current = _, g(() => {
+		R.current?.getBoundingClientRect(), Y.current();
+	}, []);
+	let X = v(x);
+	X.current = x, de(() => {
+		if (u !== "exit") return;
+		let e = R.current;
+		if (!e) {
+			X.current();
+			return;
+		}
+		let t = getComputedStyle(e), r = n(t.transitionDuration, t.transitionDelay);
+		if (r <= 0) {
+			X.current();
+			return;
+		}
+		let i = !1, a = () => {
+			i || (i = !0, X.current());
+		}, o = (t) => {
+			t.target === e && t.propertyName === "transform" && a();
+		};
+		e.addEventListener("transitionend", o);
+		let s = window.setTimeout(a, r + pe);
+		return () => {
+			i = !0, e.removeEventListener("transitionend", o), window.clearTimeout(s);
+		};
+	}, [u]);
+	let Z = we && (L === "left" || L === "right"), Q = re(L, D, ge, "520px");
+	Z && (Q.value = `${V}px`);
+	let Ie = {
+		...O,
+		[Q.name]: Q.value,
+		"--kapi-offc-push-x": `${Oe}px`,
+		"--kapi-offc-push-s": De
+	}, $ = ae(L, A), Le = /* @__PURE__ */ m("div", {
+		ref: R,
+		className: "kapi-offc__panel",
+		children: [
+			Z && /* @__PURE__ */ p("div", {
+				className: "kapi-offc__resize",
+				role: "separator",
+				"aria-orientation": "vertical",
+				"aria-label": P.resize,
+				"aria-valuemin": j,
+				"aria-valuemax": f(M, typeof window > "u" ? void 0 : window.innerWidth),
+				"aria-valuenow": V,
+				tabIndex: 0,
+				onPointerDown: je,
+				onPointerMove: Me,
+				onPointerUp: K,
+				onPointerCancel: K,
+				onKeyDown: Ne
+			}),
+			/* @__PURE__ */ m("div", {
+				className: "kapi-offc__head",
+				children: [/* @__PURE__ */ m("div", { children: [/* @__PURE__ */ p("div", {
+					id: F,
+					className: "kapi-modal__title",
+					children: w
+				}), T && /* @__PURE__ */ p("div", {
+					className: "kapi-modal__sub",
+					children: T
+				})] }), /* @__PURE__ */ p("button", {
+					type: "button",
+					className: "kapi-modal__x",
+					onClick: q,
+					"aria-label": Te,
+					children: /* @__PURE__ */ p(b, {
+						size: 17,
+						strokeWidth: 2.2
+					})
+				})]
+			}),
+			/* @__PURE__ */ p("div", {
+				className: "kapi-offc__body",
+				children: me
+			}),
+			E && /* @__PURE__ */ p("div", {
+				className: "kapi-offc__foot",
+				children: E
+			})
+		]
+	}, "main"), Re = A && $ ? /* @__PURE__ */ m("div", {
+		className: "kapi-offc__panel kapi-offc__companion",
+		role: "complementary",
+		"aria-labelledby": A.title ? I : void 0,
+		style: { "--kapi-offc-companion-w": se(A.width) },
+		children: [
+			(A.title || A.onClose) && /* @__PURE__ */ m("div", {
+				className: "kapi-offc__head",
+				children: [/* @__PURE__ */ m("div", { children: [/* @__PURE__ */ p("div", {
+					id: I,
+					className: "kapi-modal__title",
+					children: A.title
+				}), A.subtitle && /* @__PURE__ */ p("div", {
+					className: "kapi-modal__sub",
+					children: A.subtitle
+				})] }), A.onClose && /* @__PURE__ */ p("button", {
+					type: "button",
+					className: "kapi-modal__x",
+					onClick: A.onClose,
+					"aria-label": A.closeLabel ?? P.closePanel,
+					children: /* @__PURE__ */ p(b, {
+						size: 17,
+						strokeWidth: 2.2
+					})
+				})]
+			}),
+			/* @__PURE__ */ p("div", {
+				className: "kapi-offc__body",
+				children: A.children
+			}),
+			A.footer && /* @__PURE__ */ p("div", {
+				className: "kapi-offc__foot",
+				children: A.footer
+			})
+		]
+	}, "companion") : null, ze = oe(L).map((e) => e === "main" ? Le : Re).filter((e) => e !== null);
+	return /* @__PURE__ */ p("dialog", {
+		ref: Pe,
+		id: k,
+		className: t("kapi-offc", Ae && "is-resizing", Ce),
+		"data-side": d(L),
+		"data-state": u === "open" ? "open" : "closed",
+		"data-level": Ee,
+		"data-pushed": B > 0 ? "" : void 0,
+		"aria-modal": "true",
+		"aria-labelledby": F,
+		style: Ie,
+		...Fe,
+		...J,
+		children: /* @__PURE__ */ p("div", {
+			className: ie($),
+			children: ze
+		})
+	});
+}, w = ({ open: e, onExited: t, ...n }) => {
+	let i = h(), [a, o] = _(u, "unmounted"), s = v(t);
+	s.current = t, g(() => {
+		o(e ? "open" : "close");
+	}, [e]), g(() => {
+		(a === "exit" || a === "open") && l.dispatch({
+			type: "mark",
+			id: i,
+			state: a === "exit" ? "closing" : "open"
+		});
+	}, [a, i]);
+	let c = r();
+	return a === "unmounted" || !c ? null : x(/* @__PURE__ */ p(C, {
+		...n,
+		stackId: i,
+		phase: a,
+		onEntered: () => o("entered"),
+		onExited: () => {
+			o("exited"), s.current?.();
+		}
+	}), c);
+};
+//#endregion
+export { S as DEFAULT_OFFCANVAS_LABELS, w as KapiOffcanvas };

package/dist/components/overlays/KapiOffcanvasStack.d.ts

@@ -0,0 +1,58 @@
+import { type ReactNode } from "react";
+import { type KapiOffcanvasProps } from "./KapiOffcanvas";
+/** Handle que recibe el contenido de un panel (render-prop) o `useKapiOffcanvasPanel()`. */
+export type KapiOffcanvasPanelApi = {
+    id: string;
+    /** Posición en la pila (0 = primer panel). */
+    level: number;
+    /** Cierra ESTE panel (y los que estén encima de él). */
+    close: () => void;
+    /** Abre otro panel encima de éste. Devuelve su id. */
+    push: (config: KapiOffcanvasPanelConfig) => string;
+};
+export type KapiOffcanvasPanelConfig = Omit<KapiOffcanvasProps, "open" | "onClose" | "children" | "onExited"> & {
+    /** Contenido: nodo, o función que recibe el handle del panel (para `close` / `push`). */
+    content?: ReactNode | ((panel: KapiOffcanvasPanelApi) => ReactNode);
+    /** Se invoca al pedir el cierre; devolver `false` lo cancela (ej. cambios sin guardar). */
+    beforeClose?: () => boolean | void;
+    /** Se invoca cuando el panel efectivamente se está cerrando. */
+    onClose?: () => void;
+    /** Se invoca al terminar la animación de salida. */
+    onExited?: () => void;
+};
+export type KapiOffcanvasStackControls = {
+    /** Abre un panel nuevo encima del último. Devuelve su id. */
+    push: (config: KapiOffcanvasPanelConfig) => string;
+    /** Cierra el panel `id` (y los de arriba). Sin id: el de más arriba. */
+    close: (id?: string) => void;
+    /** Cierra el panel de más arriba. */
+    pop: () => void;
+    /** Cierra todos (animan juntos). */
+    closeAll: () => void;
+    /** Cantidad de paneles abiertos. */
+    size: number;
+};
+/**
+ * Provider de paneles encadenados. Renderiza los paneles él mismo, por eso el
+ * contenido puede usar los hooks de abajo para abrir más paneles encima.
+ *
+ * ```tsx
+ * <KapiOffcanvasStack><App /></KapiOffcanvasStack>
+ *
+ * const stack = useKapiOffcanvasStack();
+ * stack.push({
+ *   title: "Alumno",
+ *   content: ({ push }) => (
+ *     <KapiButton onClick={() => push({ title: "Notas", width: 420, content: <Notas /> })}>Ver notas</KapiButton>
+ *   )
+ * });
+ * ```
+ */
+export declare const KapiOffcanvasStack: ({ children }: {
+    /** Subárbol que puede abrir paneles con `useKapiOffcanvasStack`; los paneles se montan después de él. */
+    children?: ReactNode;
+}) => import("react").JSX.Element;
+/** API imperativa del stack (`push`, `pop`, `close`, `closeAll`). Requiere `<KapiOffcanvasStack>`. */
+export declare const useKapiOffcanvasStack: () => KapiOffcanvasStackControls;
+/** Handle del panel que contiene al componente (para `close()` / `push()` desde adentro). */
+export declare const useKapiOffcanvasPanel: () => KapiOffcanvasPanelApi;

package/dist/components/overlays/KapiOffcanvasStack.js

@@ -0,0 +1,84 @@
+"use client";
+import { panelsReducer as e, topOpenId as t } from "./offcanvasStack.js";
+import { KapiOffcanvas as n } from "./KapiOffcanvas.js";
+import { jsx as r, jsxs as i } from "react/jsx-runtime";
+import { createContext as a, useCallback as o, useContext as s, useLayoutEffect as c, useMemo as l, useReducer as u, useRef as d } from "react";
+//#region src/components/overlays/KapiOffcanvasStack.tsx
+var f = a(null), p = a(null), m = (t, n) => e(t, n), h = ({ children: e }) => {
+	let [a, s] = u(m, []), h = d(a);
+	c(() => {
+		h.current = a;
+	});
+	let g = d(0), _ = o((e) => {
+		g.current += 1;
+		let t = `kapi-offc-${g.current}`;
+		return s({
+			type: "push",
+			id: t,
+			config: e
+		}), t;
+	}, []), v = o((e) => {
+		let n = h.current, r = e ?? t(n), i = n.findIndex((e) => e.id === r);
+		if (i < 0 || !n[i]?.open) return;
+		let a = n.filter((e, t) => t >= i && e.open);
+		for (let e = a.length - 1; e >= 0; --e) if (a[e]?.config.beforeClose?.() === !1) return;
+		s({
+			type: "close",
+			id: n[i].id
+		}), a.forEach((e) => e.config.onClose?.());
+	}, []), y = o(() => {
+		let e = h.current.filter((e) => e.open);
+		if (e.length !== 0) {
+			for (let t = e.length - 1; t >= 0; --t) if (e[t]?.config.beforeClose?.() === !1) return;
+			s({ type: "closeAll" }), e.forEach((e) => e.config.onClose?.());
+		}
+	}, []), b = o(() => v(), [v]), x = a.filter((e) => e.open).length, S = l(() => ({
+		push: _,
+		close: v,
+		pop: b,
+		closeAll: y,
+		size: x
+	}), [
+		_,
+		v,
+		b,
+		y,
+		x
+	]);
+	return /* @__PURE__ */ i(f.Provider, {
+		value: S,
+		children: [e, a.map((e, t) => {
+			let { content: i, beforeClose: a, onClose: o, onExited: c, ...l } = e.config, u = {
+				id: e.id,
+				level: t,
+				close: () => v(e.id),
+				push: _
+			};
+			return /* @__PURE__ */ r(p.Provider, {
+				value: u,
+				children: /* @__PURE__ */ r(n, {
+					...l,
+					open: e.open,
+					onClose: u.close,
+					onExited: () => {
+						s({
+							type: "remove",
+							id: e.id
+						}), c?.();
+					},
+					children: typeof i == "function" ? i(u) : i
+				})
+			}, e.id);
+		})]
+	});
+}, g = () => {
+	let e = s(f);
+	if (!e) throw Error("useKapiOffcanvasStack: falta <KapiOffcanvasStack> más arriba en el árbol.");
+	return e;
+}, _ = () => {
+	let e = s(p);
+	if (!e) throw Error("useKapiOffcanvasPanel: sólo se puede usar dentro del contenido de un panel del stack.");
+	return e;
+};
+//#endregion
+export { h as KapiOffcanvasStack, _ as useKapiOffcanvasPanel, g as useKapiOffcanvasStack };

package/dist/components/overlays/KapiPhotoView.d.ts

@@ -0,0 +1,60 @@
+import { type CSSProperties, type ReactNode } from "react";
+import "./overlays.css";
+import { type KapiRootProps } from "../rootProps";
+import type { KapiLabelsOverride } from "../labelsLogic";
+/** closed → opening → open → closing → closed */
+export type KapiPhotoViewState = "closed" | "opening" | "open" | "closing";
+export type KapiPhotoViewEvent = "open" | "ready" | "close" | "end";
+/** `className`/`style`/`id` van al botón del thumbnail (el visor agrandado es portaleado). */
+export type KapiPhotoViewProps = KapiRootProps & {
+    /** Thumbnail (el elemento que se toca y desde el que viaja el visor). */
+    children: ReactNode;
+    /** Lo que se muestra agrandado (iniciales o una `<img>`). */
+    content: ReactNode;
+    /** Fondo del visor agrandado. */
+    bg?: string;
+    /** Color del texto del visor agrandado. */
+    ink?: string;
+    /**
+     * Nombre accesible del thumbnail (botón) y del visor (diálogo). Sin él, el botón se nombra por su
+     * contenido (alt de la `<img>` o texto) y el visor usa `labels.viewer`.
+     */
+    label?: string;
+    /** Textos fijos (clave `photoView`). */
+    labels?: KapiLabelsOverride<KapiPhotoViewLabels> | undefined;
+};
+export type KapiPhotoViewLabels = {
+    viewer: string;
+};
+export declare const DEFAULT_PHOTO_VIEW_LABELS: KapiPhotoViewLabels;
+type Rect = Pick<DOMRect, "top" | "left" | "width" | "height">;
+type Viewport = {
+    width: number;
+    height: number;
+};
+/** Tamaño máximo del visor abierto (px). */
+export declare const PHOTO_TARGET = 280;
+/** Radio de respaldo del thumbnail cuando no se puede leer el real (círculo/píldora). */
+export declare const PHOTO_PILL_RADIUS = 999;
+/** Si `transitionend` no llega al cerrar, se completa el cierre después de este tiempo. */
+export declare const PHOTO_CLOSE_FALLBACK_MS = 450;
+/** Máquina de estados del visor. Pura: los eventos inválidos para el estado actual se ignoran. */
+export declare const photoViewReducer: (state: KapiPhotoViewState, event: KapiPhotoViewEvent) => KapiPhotoViewState;
+/** Demora del fallback de cierre: inmediato con movimiento reducido (no hay transición). */
+export declare const photoCloseFallbackDelay: (reducedMotion: boolean) => number;
+/**
+ * Radio en px de una esquina a partir del `border-radius` computado (`"12px"`, `"50%"`, `"50% 50%"`…):
+ * toma el primer valor y resuelve el porcentaje contra el lado menor. Sin valor legible, `fallback`.
+ */
+export declare const parseThumbRadius: (value: string, size: Pick<DOMRect, "width" | "height">, fallback?: number) => number;
+/** Dos rects iguales en lo que usa el visor (evita re-renders al refrescar sin cambios). */
+export declare const sameRect: (a: Rect | null, b: Rect | null) => boolean;
+/** Geometría del elemento que viaja: el thumbnail (cerrado/abriendo/cerrando) o el centro (abierto). */
+export declare const photoFlyStyle: (state: KapiPhotoViewState, rect: Rect | null, viewport: Viewport, thumbRadius?: number) => CSSProperties;
+/**
+ * Visor de foto/avatar con animación "que viaja" (FLIP): el thumbnail vuela al centro y crece.
+ * El thumbnail es un botón; el visor es un diálogo modal (foco adentro, Tab atrapado, Escape o click
+ * cierran) y al cerrar el foco vuelve al thumbnail.
+ */
+export declare const KapiPhotoView: ({ children, content, bg, ink, label, labels, className, style, id }: KapiPhotoViewProps) => import("react").JSX.Element;
+export {};

package/dist/components/overlays/KapiPhotoView.js

@@ -0,0 +1,122 @@
+"use client";
+import { useLabels as e } from "../locale/KapiLocaleProvider.js";
+import { resolveKapiRoot as t } from "../../hooks/kapiRoot.js";
+import { onViewportChange as n } from "../../hooks/rafThrottle.js";
+import { joinClasses as r } from "../rootProps.js";
+/* empty css             */
+import { KapiOverlayPortal as i } from "./overlayPortal.js";
+import { prefersReducedMotion as a } from "../../hooks/reducedMotion.js";
+import { trapTabKey as o } from "../../hooks/focusLogic.js";
+import { Fragment as s, jsx as c, jsxs as l } from "react/jsx-runtime";
+import { useEffect as u, useLayoutEffect as d, useReducer as f, useRef as p, useState as m } from "react";
+//#region src/components/overlays/KapiPhotoView.tsx
+var h = { viewer: "Foto ampliada" }, g = 92, _ = 24, v = .42, y = (e, t) => {
+	switch (t) {
+		case "open": return e === "closed" ? "opening" : e;
+		case "ready": return e === "opening" ? "open" : e;
+		case "close": return e === "opening" || e === "open" ? "closing" : e;
+		case "end": return e === "closing" ? "closed" : e;
+	}
+}, b = (e) => e ? 0 : 450, x = (e, t, n = 999) => {
+	let r = e.trim().split(/[\s/]+/)[0] ?? "", i = Number.parseFloat(r);
+	return !Number.isFinite(i) || i < 0 ? n : r.endsWith("%") ? i / 100 * Math.min(t.width, t.height) : r.endsWith("px") || r === String(i) ? i : n;
+}, S = (e, t) => e === t || !!e && !!t && e.top === t.top && e.left === t.left && e.width === t.width && e.height === t.height, C = (e, t, n, r = 999) => {
+	if (e === "open") {
+		let e = Math.max(0, Math.min(280, n.width - 32, n.height - 32));
+		return {
+			top: (n.height - e) / 2,
+			left: (n.width - e) / 2,
+			width: e,
+			height: e,
+			borderRadius: _,
+			fontSize: e * g / 280
+		};
+	}
+	return t ? {
+		top: t.top,
+		left: t.left,
+		width: t.width,
+		height: t.height,
+		borderRadius: r,
+		fontSize: t.height * v
+	} : {};
+}, w = ({ children: g, content: _, bg: v = "var(--kapi-primary-soft)", ink: w = "var(--kapi-primary-ink)", label: T, labels: E, className: D, style: O, id: k }) => {
+	let A = e("photoView", h, E), j = p(null), M = p(null), N = p(!1), [P, F] = f(y, "closed"), [I, L] = m(null), [R, z] = m(999), [B, V] = m(null), H = (e) => {
+		e.stopPropagation();
+		let n = j.current;
+		if (!n) return;
+		let r = n.getBoundingClientRect();
+		L(r);
+		let i = n.firstElementChild ?? n;
+		z(x(getComputedStyle(i).borderRadius, r)), V(t(n)), F("open");
+	}, U = (e) => {
+		e.stopPropagation(), F("close");
+	};
+	d(() => {
+		if (P !== "opening") return;
+		let e = requestAnimationFrame(() => F("ready"));
+		return () => cancelAnimationFrame(e);
+	}, [P]);
+	let W = P === "closed";
+	u(() => {
+		if (!W) return n(() => {
+			let e = j.current;
+			if (!e) return;
+			let t = e.getBoundingClientRect();
+			L((e) => S(e, t) ? e : t);
+		});
+	}, [W]), u(() => {
+		if (P !== "closing") return;
+		let e = window.setTimeout(() => F("end"), b(a(j.current)));
+		return () => window.clearTimeout(e);
+	}, [P]), d(() => {
+		P === "closed" ? (L(null), V(null), N.current && j.current?.focus(), N.current = !1) : P === "opening" && (N.current = !0, M.current?.focus());
+	}, [P]);
+	let G = C(P, I, typeof window > "u" ? {
+		width: 1200,
+		height: 800
+	} : {
+		width: window.innerWidth,
+		height: window.innerHeight
+	}, R);
+	return /* @__PURE__ */ l(s, { children: [/* @__PURE__ */ c("button", {
+		ref: j,
+		type: "button",
+		onClick: H,
+		id: k,
+		className: r("kapi-photo-thumb", D),
+		style: O,
+		"aria-label": T,
+		"aria-haspopup": "dialog",
+		children: g
+	}), P !== "closed" && /* @__PURE__ */ c(i, {
+		root: B,
+		children: /* @__PURE__ */ c("div", {
+			ref: M,
+			className: `kapi-photo-overlay${P === "open" ? " is-open" : ""}`,
+			role: "dialog",
+			"aria-modal": "true",
+			"aria-label": T ?? A.viewer,
+			tabIndex: -1,
+			onClick: U,
+			onKeyDown: (e) => {
+				e.key === "Escape" ? (e.preventDefault(), U(e)) : o(e, M.current);
+			},
+			children: /* @__PURE__ */ c("div", {
+				className: "kapi-photo-fly",
+				style: {
+					...G,
+					background: v,
+					color: w
+				},
+				onTransitionEnd: (e) => {
+					e.target === e.currentTarget && F("end");
+				},
+				onClick: (e) => e.stopPropagation(),
+				children: _
+			})
+		})
+	})] });
+};
+//#endregion
+export { h as DEFAULT_PHOTO_VIEW_LABELS, w as KapiPhotoView, x as parseThumbRadius, b as photoCloseFallbackDelay, C as photoFlyStyle, y as photoViewReducer, S as sameRect };

package/dist/components/overlays/KapiPopover.d.ts

@@ -0,0 +1,46 @@
+import { type CSSProperties, type ReactNode, type RefObject } from "react";
+import { type KapiPopoverAlign, type KapiPopoverSide } from "./popoverLogic";
+import "./KapiPopover.css";
+export type KapiPopoverProps = {
+    /** Muestra u oculta el popover (controlado). */
+    open: boolean;
+    /** Elemento al que se ancla. */
+    anchorRef: RefObject<HTMLElement | null>;
+    /** Pedido de cierre: Escape o click afuera (si están habilitados). El padre pone `open={false}`. */
+    onClose: () => void;
+    /** Lado preferido; da vuelta solo si no entra. Default `"bottom"`. */
+    side?: KapiPopoverSide;
+    /** Default `"start"`. */
+    align?: KapiPopoverAlign;
+    /** Separación con el ancla (px). Default `6`. */
+    offset?: number;
+    /** Margen mínimo al borde del viewport (px). Default `8`. */
+    margin?: number;
+    /** Mismo ancho mínimo que el ancla (útil para listas desplegables). */
+    matchAnchorWidth?: boolean;
+    /** Default `"dialog"`. */
+    role?: string;
+    /** Nombre accesible de la superficie. */
+    "aria-label"?: string;
+    /** `id` de la superficie (p. ej. para el `aria-controls` del ancla). */
+    id?: string;
+    /** Clase de la superficie. */
+    className?: string;
+    /** Estilo de la superficie; la posición calculada (`top`/`left`/ancho) gana sobre él. */
+    style?: CSSProperties;
+    /** Default `true`. */
+    closeOnEscape?: boolean;
+    /** Pointerdown fuera del popover y del ancla. Default `true`. */
+    closeOnOutside?: boolean;
+    /** Al cerrar con Escape devuelve el foco al ancla. Default `true`. */
+    restoreFocus?: boolean;
+    /** Contenido del popover. */
+    children: ReactNode;
+};
+/**
+ * Popover anclado: se portalea a la raíz `.kapi` (o al `<dialog>` abierto), se posiciona con
+ * `usePlacement` (motor `placePopover`) en coordenadas de viewport y se reubica con scroll, resize y
+ * cambios de tamaño.
+ * No maneja el foco al abrir: el contenido decide (un input lo conserva, un menú lo toma).
+ */
+export declare function KapiPopover({ open, anchorRef, onClose, side, align, offset, margin, matchAnchorWidth, role, "aria-label": ariaLabel, id, className, style: styleProp, closeOnEscape, closeOnOutside, restoreFocus, children }: KapiPopoverProps): import("react").JSX.Element | null;