@mks2508/mks-ui 0.6.7 → 0.7.0

package/dist/react-ui/blocks/Sidebar/components/FluidHoverIndicator.js

@@ -0,0 +1,74 @@
+import { cn } from "../../../lib/utils.js";
+import { useFluidAnimation } from "../hooks/use-fluid-animation.js";
+import { useEffect, useRef } from "react";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/react-ui/blocks/Sidebar/components/FluidHoverIndicator.tsx
+/**
+* Fluid Hover Indicator Component
+*
+* A liquid drop-like hover indicator that uses spring physics
+* and morphing to create organic, fluid motion between sidebar items.
+*
+* Features:
+* - Spring physics with anticipation, stretch, overshoot, and settle
+* - Morphing (scale, skew) based on movement direction
+* - Pure CSS + Web Animations API (no Framer Motion)
+* - GPU-accelerated with will-change and transform
+*/
+function FluidHoverIndicator({ targetElement, isVisible, className = "", containerRef }) {
+	const indicatorRef = useRef(null);
+	const { animate, reset } = useFluidAnimation();
+	const isFirstRender = useRef(true);
+	useEffect(() => {
+		if (!targetElement || !indicatorRef.current || !isVisible) {
+			if (!isVisible && indicatorRef.current) {
+				reset();
+				indicatorRef.current.style.opacity = "0";
+				isFirstRender.current = true;
+			}
+			return;
+		}
+		const targetRect = targetElement.getBoundingClientRect();
+		const parentRect = containerRef?.current?.getBoundingClientRect() || targetElement.parentElement?.getBoundingClientRect();
+		if (!parentRect) return;
+		const padding = 8;
+		const position = {
+			x: targetRect.left - parentRect.left + padding,
+			y: targetRect.top - parentRect.top + 4,
+			width: targetRect.width - padding - 4,
+			height: targetRect.height - 8
+		};
+		if (isFirstRender.current) {
+			indicatorRef.current.style.transform = `translate(${position.x}px, ${position.y}px)`;
+			indicatorRef.current.style.width = `${position.width}px`;
+			indicatorRef.current.style.height = `${position.height}px`;
+			indicatorRef.current.style.opacity = "1";
+			isFirstRender.current = false;
+			return;
+		}
+		animate(indicatorRef.current, position);
+	}, [
+		targetElement,
+		isVisible,
+		animate,
+		reset,
+		containerRef
+	]);
+	return /* @__PURE__ */ jsx("div", {
+		ref: indicatorRef,
+		className: cn("pointer-events-none absolute z-20", "rounded-xl", "bg-primary/30 backdrop-blur-md", "border-2 border-primary/80", "shadow-lg shadow-primary/40", "will-change-transform", isVisible ? "opacity-100" : "opacity-0", "transition-opacity duration-200", className),
+		style: {
+			contain: "layout style paint",
+			transform: "translate(0, 0) scale(1) skew(0deg)",
+			opacity: isVisible ? void 0 : 0
+		},
+		children: /* @__PURE__ */ jsx("div", {
+			className: "absolute inset-0 rounded-xl bg-gradient-to-br from-primary/40 to-transparent opacity-80",
+			style: { pointerEvents: "none" }
+		})
+	});
+}
+
+//#endregion
+export { FluidHoverIndicator };

package/dist/react-ui/blocks/Sidebar/hooks/use-fluid-animation.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Position interface
+ */
+interface Position {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Custom hook for fluid animation with spring physics
+ */
+export declare function useFluidAnimation(): {
+    animate: (element: HTMLElement, targetPosition: Position) => Animation;
+    reset: () => void;
+};
+export {};
+//# sourceMappingURL=use-fluid-animation.d.ts.map

package/dist/react-ui/blocks/Sidebar/hooks/use-fluid-animation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-fluid-animation.d.ts","sourceRoot":"","sources":["../../../../../src/react-ui/blocks/Sidebar/hooks/use-fluid-animation.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,UAAU,QAAQ;IAChB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAyID;;GAEG;AACH,wBAAgB,iBAAiB;uBAQO,WAAW,kBAAkB,QAAQ;;EAiF5E"}

package/dist/react-ui/blocks/Sidebar/hooks/use-fluid-animation.js

@@ -0,0 +1,166 @@
+import { useCallback, useRef } from "react";
+
+//#region src/react-ui/blocks/Sidebar/hooks/use-fluid-animation.ts
+/**
+* Spring easing function with damping
+* Simulates spring physics for smooth, bouncy motion
+*/
+const createSpringEasing = (damping = .7, stiffness = .3) => {
+	return `cubic-bezier(0.34, ${1 + stiffness}, ${damping}, 1)`;
+};
+/**
+* Calculate direction and distance between two positions
+*/
+const calculateMovement = (from, to) => {
+	const dx = to.x - from.x;
+	const dy = to.y - from.y;
+	const distance = Math.sqrt(dx * dx + dy * dy);
+	let direction = "horizontal";
+	if (Math.abs(dy) > Math.abs(dx) * 1.5) direction = "vertical";
+	else if (Math.abs(dx) > Math.abs(dy) * 1.5) direction = "horizontal";
+	else direction = "diagonal";
+	const angle = Math.atan2(dy, dx) * (180 / Math.PI);
+	return {
+		dx,
+		dy,
+		distance,
+		direction,
+		angle
+	};
+};
+/**
+* Generate morphing keyframes based on direction
+*/
+const generateMorphingKeyframes = (from, to, direction, angle) => {
+	const fromTransform = `translate(${from.x}px, ${from.y}px) scale(1) skew(0deg)`;
+	const toTransform = `translate(${to.x}px, ${to.y}px) scale(1) skew(0deg)`;
+	let stretchScale = "1.15, 0.95";
+	let overshootScale = "1.05, 1.03";
+	let skewValue = "5deg";
+	if (direction === "vertical") {
+		stretchScale = "0.95, 1.15";
+		skewValue = "-5deg";
+	} else if (direction === "diagonal") {
+		stretchScale = "1.1, 1.1";
+		skewValue = `${angle * .1}deg`;
+	}
+	return [
+		{
+			transform: fromTransform,
+			opacity: "0.95",
+			offset: 0
+		},
+		{
+			transform: `translate(${from.x}px, ${from.y}px) scale(0.95) skew(0deg)`,
+			opacity: "0.98",
+			offset: .15
+		},
+		{
+			transform: `translate(${(from.x + to.x) / 2}px, ${(from.y + to.y) / 2}px) scale(${stretchScale}) skew(${skewValue})`,
+			opacity: "1",
+			offset: .45
+		},
+		{
+			transform: `translate(${to.x + (to.x - from.x) * .1}px, ${to.y + (to.y - from.y) * .1}px) scale(${overshootScale}) skew(${direction === "horizontal" ? "-2deg" : "2deg"})`,
+			opacity: "1",
+			offset: .75
+		},
+		{
+			transform: toTransform,
+			opacity: "0.95",
+			offset: 1
+		}
+	];
+};
+/**
+* Extract current position from element's computed transform
+*/
+const getCurrentPosition = (element) => {
+	const transform = getComputedStyle(element).transform;
+	if (transform === "none") return {
+		x: 0,
+		y: 0
+	};
+	const matrix = new DOMMatrix(transform);
+	return {
+		x: matrix.m41,
+		y: matrix.m42
+	};
+};
+/**
+* Generate fast mode keyframes (simple, direct movement)
+*/
+const generateFastKeyframes = (from, to) => {
+	return [{
+		transform: `translate(${from.x}px, ${from.y}px)`,
+		width: `${from.width}px`,
+		height: `${from.height}px`,
+		offset: 0
+	}, {
+		transform: `translate(${to.x}px, ${to.y}px)`,
+		width: `${to.width}px`,
+		height: `${to.height}px`,
+		offset: 1
+	}];
+};
+/**
+* Custom hook for fluid animation with spring physics
+*/
+function useFluidAnimation() {
+	const previousPositionRef = useRef(null);
+	const animationRef = useRef(null);
+	const lastChangeTimestampRef = useRef(0);
+	return {
+		animate: useCallback((element, targetPosition) => {
+			const now = Date.now();
+			const isFastMode = now - lastChangeTimestampRef.current < 200 && lastChangeTimestampRef.current > 0;
+			lastChangeTimestampRef.current = now;
+			let from;
+			if (animationRef.current) {
+				const currentPos = getCurrentPosition(element);
+				from = {
+					x: currentPos.x,
+					y: currentPos.y,
+					width: previousPositionRef.current?.width || targetPosition.width,
+					height: previousPositionRef.current?.height || targetPosition.height
+				};
+				animationRef.current.cancel();
+			} else from = previousPositionRef.current || targetPosition;
+			const to = targetPosition;
+			const { direction, angle, distance } = calculateMovement(from, to);
+			let keyframes;
+			let duration;
+			let easing;
+			if (isFastMode) {
+				keyframes = generateFastKeyframes(from, to);
+				duration = Math.min(150, Math.max(100, distance * .5));
+				easing = "cubic-bezier(0.25, 0.1, 0.25, 1)";
+			} else {
+				keyframes = generateMorphingKeyframes(from, to, direction, angle);
+				duration = Math.min(450, Math.max(350, distance * 2));
+				easing = createSpringEasing(.65, .4);
+			}
+			const animation = element.animate(keyframes, {
+				duration,
+				easing,
+				fill: "forwards"
+			});
+			animationRef.current = animation;
+			animation.onfinish = () => {
+				previousPositionRef.current = to;
+			};
+			return animation;
+		}, []),
+		reset: useCallback(() => {
+			if (animationRef.current) {
+				animationRef.current.cancel();
+				animationRef.current = null;
+			}
+			previousPositionRef.current = null;
+			lastChangeTimestampRef.current = 0;
+		}, [])
+	};
+}
+
+//#endregion
+export { useFluidAnimation };

package/dist/react-ui/blocks/Sidebar/hooks/useSidebarContext.d.ts

@@ -0,0 +1,48 @@
+import type { SidebarContextValue } from "../Sidebar.types";
+/**
+ * Hook para acceder al contexto del Sidebar
+ *
+ * @description
+ * Hook personalizado que provee acceso al contexto compartido del Sidebar.
+ * Debe ser utilizado dentro de un componente que esté envuelto por
+ * `<Sidebar>` o `<SidebarProvider>`.
+ *
+ * Lanza un error si se utiliza fuera del contexto apropiado, ayudando
+ * a detectar problemas de composición durante el desarrollo.
+ *
+ * @throws {Error} Si se usa fuera de un SidebarProvider
+ *
+ * @returns {SidebarContextValue} El valor del contexto del sidebar
+ *
+ * @example
+ * ```tsx
+ * function CustomToggle() {
+ *   const { open, setOpen } = useSidebarContext()
+ *
+ *   return (
+ *     <button onClick={() => setOpen(!open)}>
+ *       {open ? 'Cerrar' : 'Abrir'}
+ *     </button>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Acceder a configuración
+ * function CustomItem() {
+ *   const { colors, dimensions } = useSidebarContext()
+ *
+ *   return (
+ *     <div style={{
+ *       background: colors.hover,
+ *       width: dimensions.expandedWidth
+ *     }}>
+ *       Item
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export declare function useSidebarContext(): SidebarContextValue;
+//# sourceMappingURL=useSidebarContext.d.ts.map

package/dist/react-ui/blocks/Sidebar/hooks/useSidebarContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSidebarContext.d.ts","sourceRoot":"","sources":["../../../../../src/react-ui/blocks/Sidebar/hooks/useSidebarContext.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,iBAAiB,IAAI,mBAAmB,CAWvD"}

package/dist/react-ui/blocks/Sidebar/hooks/useSidebarContext.js

@@ -0,0 +1,59 @@
+"use client";
+
+import { SidebarContext } from "../SidebarContext.js";
+import { useContext } from "react";
+
+//#region src/react-ui/blocks/Sidebar/hooks/useSidebarContext.ts
+/**
+* Hook para acceder al contexto del Sidebar
+*
+* @description
+* Hook personalizado que provee acceso al contexto compartido del Sidebar.
+* Debe ser utilizado dentro de un componente que esté envuelto por
+* `<Sidebar>` o `<SidebarProvider>`.
+*
+* Lanza un error si se utiliza fuera del contexto apropiado, ayudando
+* a detectar problemas de composición durante el desarrollo.
+*
+* @throws {Error} Si se usa fuera de un SidebarProvider
+*
+* @returns {SidebarContextValue} El valor del contexto del sidebar
+*
+* @example
+* ```tsx
+* function CustomToggle() {
+*   const { open, setOpen } = useSidebarContext()
+*
+*   return (
+*     <button onClick={() => setOpen(!open)}>
+*       {open ? 'Cerrar' : 'Abrir'}
+*     </button>
+*   )
+* }
+* ```
+*
+* @example
+* ```tsx
+* // Acceder a configuración
+* function CustomItem() {
+*   const { colors, dimensions } = useSidebarContext()
+*
+*   return (
+*     <div style={{
+*       background: colors.hover,
+*       width: dimensions.expandedWidth
+*     }}>
+*       Item
+*     </div>
+*   )
+* }
+* ```
+*/
+function useSidebarContext() {
+	const context = useContext(SidebarContext);
+	if (!context) throw new Error("useSidebarContext debe ser utilizado dentro de un componente <Sidebar> o <SidebarProvider>. Asegúrate de que tu componente esté envuelto correctamente en la jerarquía del Sidebar.");
+	return context;
+}
+
+//#endregion
+export { useSidebarContext };

package/dist/react-ui/blocks/Sidebar/hooks/useSidebarIndicator.d.ts

@@ -0,0 +1,72 @@
+import type { MouseEvent } from "react";
+/**
+ * Valor de retorno del hook useSidebarIndicator
+ * @interface
+ */
+interface UseSidebarIndicatorReturn {
+    /** Indica si el indicador está visible */
+    isVisible: boolean;
+    /** Indica si el mouse está sobre el área de items */
+    isOverItems: boolean;
+    /** Elemento del item actualmente hovered o enfocado (para FluidHoverIndicator) */
+    currentItemElement: HTMLElement | null;
+    /** ID del item bajo el indicador (para tooltip con subContent) */
+    hoveredItemId: string | null;
+    /** Label del item hovered (para tooltip simple) */
+    hoveredLabel: string | null;
+    /** Manejador de evento mousemove */
+    handleMouseMove: (e: MouseEvent<HTMLDivElement>) => void;
+    /** Manejador de evento mouseenter */
+    handleMouseEnter: () => void;
+    /** Manejador de evento mouseleave */
+    handleMouseLeave: () => void;
+    /** Manejador de evento focus */
+    handleFocus: () => void;
+    /** Manejador de evento blur */
+    handleBlur: (e: React.FocusEvent) => void;
+    /** Función para limpiar el estado hovered desde fuera (tooltip mouseleave) */
+    clearHoveredState: () => void;
+}
+/**
+ * Hook para gestionar el indicador visual del Sidebar
+ *
+ * @description
+ * Hook que implementa la lógica del indicador visual que sigue al cursor
+ * del mouse dentro del sidebar. El indicador se muestra cuando:
+ * - El mouse está sobre el sidebar (isHovering = true)
+ * - El cursor está en el área de items (isOverItems = true)
+ *
+ * Utiliza requestAnimationFrame para optimizar el rendimiento y evitar
+ * cálculos excesivos durante el movimiento del mouse.
+ *
+ * El indicador también se actualiza cuando se navega por teclado,
+ * integrándose con useSidebarKeyboard.
+ *
+ * @returns {UseSidebarIndicatorReturn} Estado y manejadores de eventos
+ *
+ * @example
+ * ```tsx
+ * function SidebarNav() {
+ *   const {
+ *     isVisible,
+ *     handleMouseMove,
+ *     handleMouseEnter,
+ *     handleMouseLeave
+ *   } = useSidebarIndicator()
+ *
+ *   return (
+ *     <nav
+ *       onMouseMove={handleMouseMove}
+ *       onMouseEnter={handleMouseEnter}
+ *       onMouseLeave={handleMouseLeave}
+ *     >
+ *       <SidebarIndicator visible={isVisible} />
+ *       {children}
+ *     </nav>
+ *   )
+ * }
+ * ```
+ */
+export declare function useSidebarIndicator(): UseSidebarIndicatorReturn;
+export {};
+//# sourceMappingURL=useSidebarIndicator.d.ts.map

package/dist/react-ui/blocks/Sidebar/hooks/useSidebarIndicator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSidebarIndicator.d.ts","sourceRoot":"","sources":["../../../../../src/react-ui/blocks/Sidebar/hooks/useSidebarIndicator.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAGvC;;;GAGG;AACH,UAAU,yBAAyB;IACjC,0CAA0C;IAC1C,SAAS,EAAE,OAAO,CAAA;IAClB,qDAAqD;IACrD,WAAW,EAAE,OAAO,CAAA;IACpB,kFAAkF;IAClF,kBAAkB,EAAE,WAAW,GAAG,IAAI,CAAA;IACtC,kEAAkE;IAClE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,mDAAmD;IACnD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,oCAAoC;IACpC,eAAe,EAAE,CAAC,CAAC,EAAE,UAAU,CAAC,cAAc,CAAC,KAAK,IAAI,CAAA;IACxD,qCAAqC;IACrC,gBAAgB,EAAE,MAAM,IAAI,CAAA;IAC5B,qCAAqC;IACrC,gBAAgB,EAAE,MAAM,IAAI,CAAA;IAC5B,gCAAgC;IAChC,WAAW,EAAE,MAAM,IAAI,CAAA;IACvB,+BAA+B;IAC/B,UAAU,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAA;IACzC,8EAA8E;IAC9E,iBAAiB,EAAE,MAAM,IAAI,CAAA;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,mBAAmB,IAAI,yBAAyB,CA2K/D"}

package/dist/react-ui/blocks/Sidebar/hooks/useSidebarIndicator.js

@@ -0,0 +1,159 @@
+"use client";
+
+import { useSidebarContext } from "./useSidebarContext.js";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+//#region src/react-ui/blocks/Sidebar/hooks/useSidebarIndicator.ts
+/**
+* Hook para gestionar el indicador visual del Sidebar
+*
+* @description
+* Hook que implementa la lógica del indicador visual que sigue al cursor
+* del mouse dentro del sidebar. El indicador se muestra cuando:
+* - El mouse está sobre el sidebar (isHovering = true)
+* - El cursor está en el área de items (isOverItems = true)
+*
+* Utiliza requestAnimationFrame para optimizar el rendimiento y evitar
+* cálculos excesivos durante el movimiento del mouse.
+*
+* El indicador también se actualiza cuando se navega por teclado,
+* integrándose con useSidebarKeyboard.
+*
+* @returns {UseSidebarIndicatorReturn} Estado y manejadores de eventos
+*
+* @example
+* ```tsx
+* function SidebarNav() {
+*   const {
+*     isVisible,
+*     handleMouseMove,
+*     handleMouseEnter,
+*     handleMouseLeave
+*   } = useSidebarIndicator()
+*
+*   return (
+*     <nav
+*       onMouseMove={handleMouseMove}
+*       onMouseEnter={handleMouseEnter}
+*       onMouseLeave={handleMouseLeave}
+*     >
+*       <SidebarIndicator visible={isVisible} />
+*       {children}
+*     </nav>
+*   )
+* }
+* ```
+*/
+function useSidebarIndicator() {
+	const { indicatorRef, navRef, contentRef, showIndicatorForKeyboard, setShowIndicatorForKeyboard, isOverItems, setIsOverItems, currentItemElement, setCurrentItemElement } = useSidebarContext();
+	const [isHovering, setIsHovering] = useState(false);
+	const [refsReady, setRefsReady] = useState(false);
+	const [hoveredItemId, setHoveredItemId] = useState(null);
+	const [hoveredLabel, setHoveredLabel] = useState(null);
+	const rafRef = useRef(null);
+	useEffect(() => {
+		if (indicatorRef.current && navRef.current && contentRef.current) setRefsReady(true);
+	}, [
+		indicatorRef,
+		navRef,
+		contentRef
+	]);
+	/**
+	* Manejador de mousemove con optimización via requestAnimationFrame
+	*
+	* @param {MouseEvent<HTMLDivElement>} e - Evento de mouse
+	*/
+	const handleMouseMove = useCallback((e) => {
+		if (!indicatorRef.current || !navRef.current || !contentRef.current) return;
+		if (rafRef.current) cancelAnimationFrame(rafRef.current);
+		rafRef.current = requestAnimationFrame(() => {
+			if (!indicatorRef.current || !navRef.current || !contentRef.current) return;
+			const navRect = navRef.current.getBoundingClientRect();
+			const contentRect = contentRef.current.getBoundingClientRect();
+			const y = e.clientY - navRect.top;
+			const minY = contentRect.top - navRect.top;
+			const maxY = contentRect.bottom - navRect.top;
+			const clampedY = Math.max(minY, Math.min(maxY, y));
+			indicatorRef.current.style.top = `${clampedY}px`;
+			setIsOverItems(e.clientY >= contentRect.top && e.clientY <= contentRect.bottom);
+			const itemElement = document.elementFromPoint(e.clientX, e.clientY)?.closest("[data-sidebar-item]");
+			if (itemElement) {
+				setCurrentItemElement(itemElement);
+				setHoveredLabel(itemElement.getAttribute("aria-label") || itemElement.getAttribute("title") || null);
+				setHoveredItemId(itemElement.getAttribute("data-item-id") || null);
+			} else {
+				setCurrentItemElement(null);
+				setHoveredItemId(null);
+				setHoveredLabel(null);
+			}
+		});
+	}, [
+		indicatorRef,
+		navRef,
+		contentRef
+	]);
+	/**
+	* Manejador de mouseenter
+	*/
+	const handleMouseEnter = useCallback(() => {
+		setIsHovering(true);
+	}, []);
+	/**
+	* Manejador de mouseleave
+	*/
+	const handleMouseLeave = useCallback(() => {
+		setIsHovering(false);
+		setIsOverItems(false);
+		setShowIndicatorForKeyboard(false);
+		setCurrentItemElement(null);
+		setHoveredLabel(null);
+		if (rafRef.current) cancelAnimationFrame(rafRef.current);
+	}, [setShowIndicatorForKeyboard, setIsOverItems]);
+	/**
+	* Manejador de focus (cuando se enfoca un elemento dentro del sidebar)
+	*/
+	const handleFocus = useCallback(() => {
+		setIsHovering(true);
+		setIsOverItems(true);
+	}, [setIsOverItems]);
+	/**
+	* Manejador de blur (cuando se pierde el focus)
+	*
+	* @param {React.FocusEvent} e - Evento de blur
+	*/
+	const handleBlur = useCallback((e) => {
+		if (!navRef.current?.contains(e.relatedTarget)) {
+			setIsHovering(false);
+			setIsOverItems(false);
+			setShowIndicatorForKeyboard(false);
+		}
+	}, [
+		navRef,
+		setShowIndicatorForKeyboard,
+		setIsOverItems
+	]);
+	/**
+	* Limpia el estado hovered (para cuando el mouse sale del tooltip)
+	*/
+	const clearHoveredState = useCallback(() => {
+		setHoveredLabel(null);
+		setHoveredItemId(null);
+		setCurrentItemElement(null);
+	}, []);
+	return {
+		isVisible: refsReady && (isHovering && isOverItems || showIndicatorForKeyboard),
+		isOverItems,
+		currentItemElement,
+		hoveredItemId,
+		hoveredLabel,
+		handleMouseMove,
+		handleMouseEnter,
+		handleMouseLeave,
+		handleFocus,
+		handleBlur,
+		clearHoveredState
+	};
+}
+
+//#endregion
+export { useSidebarIndicator };

package/dist/react-ui/blocks/Sidebar/hooks/useSidebarKeyboard.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Valor de retorno del hook useSidebarKeyboard
+ * @interface
+ */
+interface UseSidebarKeyboardReturn {
+    /** Índice del item actualmente enfocado (-1 si ninguno) */
+    focusedIndex: number;
+    /** Función para cambiar el índice enfocado manualmente */
+    setFocusedIndex: (index: number) => void;
+    /** Callback para actualizar el indicador según el item enfocado */
+    updateIndicatorForFocus: (index: number) => void;
+}
+/**
+ * Hook para gestionar la navegación por teclado en el Sidebar
+ *
+ * @description
+ * Hook que implementa navegación accesible por teclado para los items
+ * del sidebar, siguiendo las especificaciones WAI-ARIA:
+ *
+ * - ArrowDown: Navegar al siguiente item
+ * - ArrowUp: Navegar al item anterior
+ * - Home: Ir al primer item
+ * - End: Ir al último item
+ * - Tab: Navegación estándar que actualiza el indicador
+ *
+ * También sincroniza el indicador visual con el item enfocado.
+ *
+ * @returns {UseSidebarKeyboardReturn} Estado y funciones para navegación
+ *
+ * @example
+ * ```tsx
+ * function SidebarNav() {
+ *   const { focusedIndex, updateIndicatorForFocus } = useSidebarKeyboard()
+ *
+ *   return (
+ *     <nav>
+ *       {items.map((item, index) => (
+ *         <SidebarItem
+ *           key={item.id}
+ *           focused={index === focusedIndex}
+ *           onFocus={() => updateIndicatorForFocus(index)}
+ *         />
+ *       ))}
+ *     </nav>
+ *   )
+ * }
+ * ```
+ */
+export declare function useSidebarKeyboard(): UseSidebarKeyboardReturn;
+export {};
+//# sourceMappingURL=useSidebarKeyboard.d.ts.map

package/dist/react-ui/blocks/Sidebar/hooks/useSidebarKeyboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSidebarKeyboard.d.ts","sourceRoot":"","sources":["../../../../../src/react-ui/blocks/Sidebar/hooks/useSidebarKeyboard.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,UAAU,wBAAwB;IAChC,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAA;IACpB,0DAA0D;IAC1D,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACxC,mEAAmE;IACnE,uBAAuB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CACjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,kBAAkB,IAAI,wBAAwB,CA+I7D"}