@mks2508/mks-ui 0.6.8 → 0.7.0

package/dist/react-ui/blocks/Sidebar/Sidebar.types.js

@@ -0,0 +1,149 @@
+//#region src/react-ui/blocks/Sidebar/Sidebar.types.ts
+/**
+* Modo de colapso del sidebar
+* @enum {string}
+*/
+let SidebarCollapseMode = /* @__PURE__ */ function(SidebarCollapseMode) {
+	/** Colapsa el sidebar a un ancho mínimo mostrando solo iconos */
+	SidebarCollapseMode["COLLAPSE"] = "collapse";
+	/** Oculta completamente el sidebar */
+	SidebarCollapseMode["HIDE"] = "hide";
+	return SidebarCollapseMode;
+}({});
+/**
+* Comportamiento del sidebar cuando está en modo hide
+* @enum {string}
+*/
+let SidebarHideBehaviour = /* @__PURE__ */ function(SidebarHideBehaviour) {
+	/** Muestra un botón indicador para reabrir el sidebar */
+	SidebarHideBehaviour["SHOW_INDICATOR"] = "showIndicator";
+	/** El sidebar es completamente controlado externamente sin indicador */
+	SidebarHideBehaviour["CONTROLLED"] = "controlled";
+	return SidebarHideBehaviour;
+}({});
+/**
+* Comportamiento al abrir desde el estado hide
+* @enum {string}
+*/
+let SidebarHideOpensBehavior = /* @__PURE__ */ function(SidebarHideOpensBehavior) {
+	/** Abre al tamaño colapsado (solo iconos) */
+	SidebarHideOpensBehavior["COLLAPSED"] = "collapsed";
+	/** Abre al tamaño expandido completo */
+	SidebarHideOpensBehavior["EXPANDED"] = "expanded";
+	return SidebarHideOpensBehavior;
+}({});
+/**
+* Comportamiento de layout del sidebar
+* @enum {string}
+*/
+let SidebarLayoutBehaviour = /* @__PURE__ */ function(SidebarLayoutBehaviour) {
+	/** Sidebar flotante con z-index que NO desplaza el contenido (default) */
+	SidebarLayoutBehaviour["FLOATING"] = "floating";
+	/** Sidebar como parte del layout que SÍ desplaza el contenido */
+	SidebarLayoutBehaviour["INLINE"] = "inline";
+	return SidebarLayoutBehaviour;
+}({});
+/**
+* Anchos predefinidos del sidebar
+* @enum {string}
+*/
+let SidebarWidth = /* @__PURE__ */ function(SidebarWidth) {
+	/** Ancho en estado colapsado (solo iconos) */
+	SidebarWidth["COLLAPSED"] = "5rem";
+	/** Ancho expandido completo */
+	SidebarWidth["EXPANDED"] = "16rem";
+	/** Ancho mínimo absoluto */
+	SidebarWidth["MIN"] = "3rem";
+	/** Ancho máximo absoluto */
+	SidebarWidth["MAX"] = "20rem";
+	return SidebarWidth;
+}({});
+/**
+* Duraciones de transición en milisegundos
+* @enum {number}
+*/
+let SidebarTransitionDuration = /* @__PURE__ */ function(SidebarTransitionDuration) {
+	/** Transición rápida para cambios de opacidad */
+	SidebarTransitionDuration[SidebarTransitionDuration["FAST"] = 200] = "FAST";
+	/** Transición normal para width y transforms */
+	SidebarTransitionDuration[SidebarTransitionDuration["NORMAL"] = 300] = "NORMAL";
+	/** Transición lenta para animaciones complejas */
+	SidebarTransitionDuration[SidebarTransitionDuration["SLOW"] = 500] = "SLOW";
+	return SidebarTransitionDuration;
+}({});
+/**
+* Índices Z para capas del sidebar
+* @enum {number}
+*/
+let SidebarZIndex = /* @__PURE__ */ function(SidebarZIndex) {
+	/** Base del contenedor wrapper */
+	SidebarZIndex[SidebarZIndex["BASE"] = 0] = "BASE";
+	/** Indicador visual */
+	SidebarZIndex[SidebarZIndex["INDICATOR"] = 5] = "INDICATOR";
+	/** Contenido interno del sidebar */
+	SidebarZIndex[SidebarZIndex["CONTENT"] = 10] = "CONTENT";
+	/** Botón de toggle */
+	SidebarZIndex[SidebarZIndex["TOGGLE"] = 30] = "TOGGLE";
+	return SidebarZIndex;
+}({});
+/**
+* Radios de borde predefinidos
+* @enum {string}
+*/
+let SidebarBorderRadius = /* @__PURE__ */ function(SidebarBorderRadius) {
+	/** Sin radio de borde */
+	SidebarBorderRadius["NONE"] = "0";
+	/** Radio pequeño */
+	SidebarBorderRadius["SM"] = "0.25rem";
+	/** Radio medio */
+	SidebarBorderRadius["MD"] = "0.5rem";
+	/** Radio grande */
+	SidebarBorderRadius["LG"] = "1rem";
+	/** Radio completo (circular) */
+	SidebarBorderRadius["FULL"] = "9999px";
+	return SidebarBorderRadius;
+}({});
+/**
+* Posiciones para SidebarSafeArea
+* @enum {string}
+*/
+let SidebarSafeAreaPosition = /* @__PURE__ */ function(SidebarSafeAreaPosition) {
+	/** Área segura superior */
+	SidebarSafeAreaPosition["TOP"] = "top";
+	/** Área segura inferior */
+	SidebarSafeAreaPosition["BOTTOM"] = "bottom";
+	return SidebarSafeAreaPosition;
+}({});
+/**
+* Timing functions para transiciones CSS
+* @enum {string}
+*/
+let SidebarTimingFunction = /* @__PURE__ */ function(SidebarTimingFunction) {
+	/** Ease estándar */
+	SidebarTimingFunction["EASE"] = "ease";
+	/** Linear (velocidad constante) */
+	SidebarTimingFunction["LINEAR"] = "linear";
+	/** Ease in (aceleración) */
+	SidebarTimingFunction["EASE_IN"] = "ease-in";
+	/** Ease out (desaceleración) */
+	SidebarTimingFunction["EASE_OUT"] = "ease-out";
+	/** Ease in out (aceleración y desaceleración) */
+	SidebarTimingFunction["EASE_IN_OUT"] = "ease-in-out";
+	/** Cubic bezier personalizado */
+	SidebarTimingFunction["CUSTOM"] = "cubic-bezier(0.4, 0, 0.2, 1)";
+	return SidebarTimingFunction;
+}({});
+/**
+* Librería de iconos a utilizar
+* @enum {string}
+*/
+let SidebarIconLibrary = /* @__PURE__ */ function(SidebarIconLibrary) {
+	/** Iconos de lucide-react */
+	SidebarIconLibrary["LUCIDE"] = "lucide";
+	/** Iconos custom proporcionados por el usuario */
+	SidebarIconLibrary["CUSTOM"] = "custom";
+	return SidebarIconLibrary;
+}({});
+
+//#endregion
+export { SidebarBorderRadius, SidebarCollapseMode, SidebarHideBehaviour, SidebarHideOpensBehavior, SidebarIconLibrary, SidebarLayoutBehaviour, SidebarSafeAreaPosition, SidebarTimingFunction, SidebarTransitionDuration, SidebarWidth, SidebarZIndex };

package/dist/react-ui/blocks/Sidebar/SidebarContent.d.ts

@@ -0,0 +1,46 @@
+import type { SidebarContentProps } from "./Sidebar.types";
+/**
+ * Componente de contenido del Sidebar (contenedor de items)
+ *
+ * @description
+ * Contenedor que agrupa los items de navegación (SidebarItem).
+ * Renderiza un `<div>` por defecto y aplica estilos de layout flex.
+ *
+ * Este componente:
+ * - Registra su ref en el contexto para cálculos del indicador
+ * - Aplica rol ARIA "list" para accesibilidad
+ * - Centra y distribuye items verticalmente
+ * - Permite customización completa con className y style
+ *
+ * Los items dentro de este contenedor son utilizados por:
+ * - useSidebarIndicator: Para calcular posición del indicador
+ * - useSidebarKeyboard: Para navegación por teclado
+ *
+ * @example
+ * ```tsx
+ * <SidebarNav>
+ *   <SidebarContent>
+ *     <SidebarItem href="/" icon={<HomeIcon />} />
+ *     <SidebarItem href="/settings" icon={<SettingsIcon />} />
+ *   </SidebarContent>
+ * </SidebarNav>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con estilos custom
+ * <SidebarContent className="gap-2 py-4">
+ *   <SidebarItem href="/" />
+ * </SidebarContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Como lista semántica
+ * <SidebarContent as="ul">
+ *   <SidebarItem as="li" href="/" />
+ * </SidebarContent>
+ * ```
+ */
+export declare const SidebarContent: import("react").ForwardRefExoticComponent<SidebarContentProps & import("react").RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=SidebarContent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SidebarContent.d.ts","sourceRoot":"","sources":["../../../../src/react-ui/blocks/Sidebar/SidebarContent.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAG1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,cAAc,gHAuDzB,CAAA"}

package/dist/react-ui/blocks/Sidebar/SidebarContent.js

@@ -0,0 +1,86 @@
+"use client";
+
+import { SIDEBAR_ARIA_ROLES, SIDEBAR_TAILWIND_CLASSES } from "./Sidebar.constants.js";
+import { useSidebarContext } from "./hooks/useSidebarContext.js";
+import { forwardRef, useEffect, useRef } from "react";
+import { jsxs } from "react/jsx-runtime";
+
+//#region src/react-ui/blocks/Sidebar/SidebarContent.tsx
+/**
+* Componente de contenido del Sidebar (contenedor de items)
+*
+* @description
+* Contenedor que agrupa los items de navegación (SidebarItem).
+* Renderiza un `<div>` por defecto y aplica estilos de layout flex.
+*
+* Este componente:
+* - Registra su ref en el contexto para cálculos del indicador
+* - Aplica rol ARIA "list" para accesibilidad
+* - Centra y distribuye items verticalmente
+* - Permite customización completa con className y style
+*
+* Los items dentro de este contenedor son utilizados por:
+* - useSidebarIndicator: Para calcular posición del indicador
+* - useSidebarKeyboard: Para navegación por teclado
+*
+* @example
+* ```tsx
+* <SidebarNav>
+*   <SidebarContent>
+*     <SidebarItem href="/" icon={<HomeIcon />} />
+*     <SidebarItem href="/settings" icon={<SettingsIcon />} />
+*   </SidebarContent>
+* </SidebarNav>
+* ```
+*
+* @example
+* ```tsx
+* // Con estilos custom
+* <SidebarContent className="gap-2 py-4">
+*   <SidebarItem href="/" />
+* </SidebarContent>
+* ```
+*
+* @example
+* ```tsx
+* // Como lista semántica
+* <SidebarContent as="ul">
+*   <SidebarItem as="li" href="/" />
+* </SidebarContent>
+* ```
+*/
+const SidebarContent = forwardRef(function SidebarContent({ children, className = "", style, as, ...props }, forwardedRef) {
+	const { contentRef, debug, safeAreas } = useSidebarContext();
+	const Component = as || "div";
+	const localContentRef = useRef(null);
+	const contentHeight = 100 - safeAreas.topPercent - safeAreas.bottomPercent;
+	useEffect(() => {
+		const node = localContentRef.current;
+		if (!node) return;
+		if (contentRef && "current" in contentRef) contentRef.current = node;
+		if (typeof forwardedRef === "function") forwardedRef(node);
+		else if (forwardedRef) forwardedRef.current = node;
+	}, [contentRef, forwardedRef]);
+	const debugClasses = debug ? "bg-zinc-900/70 border-y-2 border-dashed border-emerald-400/60 relative" : "";
+	return /* @__PURE__ */ jsxs(Component, {
+		ref: localContentRef,
+		className: `${SIDEBAR_TAILWIND_CLASSES.content} ${debugClasses} ${className}`,
+		style: {
+			height: `${contentHeight}%`,
+			...style
+		},
+		role: SIDEBAR_ARIA_ROLES.list,
+		...props,
+		children: [debug && /* @__PURE__ */ jsxs("span", {
+			className: "absolute top-1 right-1 text-[10px] text-emerald-300 font-mono z-50 bg-black/60 px-1.5 py-0.5 rounded",
+			children: [
+				"CONTENT ",
+				contentHeight,
+				"%"
+			]
+		}), children]
+	});
+});
+
+//#endregion
+export { SidebarContent };

package/dist/react-ui/blocks/Sidebar/SidebarContext.d.ts

@@ -0,0 +1,85 @@
+import type { ReactNode } from "react";
+export interface SubContentData {
+    itemId: string;
+    subContent: ReactNode;
+    title?: string;
+}
+export declare const SubContentContext: import("react").Context<{
+    subContentMap: Map<string, SubContentData>;
+    registerSubContent: (itemId: string, data: SubContentData) => void;
+    unregisterSubContent: (itemId: string) => void;
+    getSubContent: (itemId: string) => SubContentData | undefined;
+} | null>;
+import type { SidebarContextValue, SidebarCollapseMode, SidebarHideBehaviour, SidebarHideOpensBehavior, SidebarLayoutBehaviour, SidebarDimensions, SidebarSafeAreas, SidebarAnimations } from "./Sidebar.types";
+/**
+ * Contexto del Sidebar para compartir estado entre componentes primitivos
+ * @constant
+ */
+export declare const SidebarContext: import("react").Context<SidebarContextValue | null>;
+/**
+ * Props del SidebarProvider
+ * @interface
+ */
+interface SidebarProviderProps {
+    /** Contenido hijo (componentes primitivos del sidebar) */
+    children: ReactNode;
+    /** Estado inicial abierto (modo uncontrolled) */
+    defaultOpen?: boolean;
+    /** Estado abierto (modo controlled) */
+    open?: boolean;
+    /** Callback cuando cambia el estado open */
+    onOpenChange?: (open: boolean) => void;
+    /** Modo de colapso del sidebar */
+    collapseMode?: SidebarCollapseMode;
+    /** Comportamiento en modo hide */
+    hideBehaviour?: SidebarHideBehaviour;
+    /** Comportamiento al abrir desde hide */
+    hideOpensBehavior?: SidebarHideOpensBehavior;
+    /** Comportamiento de layout del sidebar */
+    layoutBehaviour?: SidebarLayoutBehaviour;
+    /** Configuración de dimensiones */
+    dimensions?: Partial<SidebarDimensions>;
+    /** Configuración de safe areas */
+    safeAreas?: Partial<SidebarSafeAreas>;
+    /** Configuración de animaciones */
+    animations?: Partial<SidebarAnimations>;
+    /** ID del toggle input */
+    toggleId?: string;
+    /** Modo debug para visualizar safe areas */
+    debug?: boolean;
+    /** Habilitar FluidHoverIndicator (glassmorphism + spring physics) */
+    enableFluidIndicator?: boolean;
+    /** Habilitar tooltip en hover (muestra label o subcategorías) */
+    enableTooltip?: boolean;
+}
+/**
+ * Provider del contexto del Sidebar
+ *
+ * @description
+ * Componente que provee el contexto compartido a todos los componentes
+ * primitivos del sidebar. Gestiona el estado global (open/closed) y
+ * referencias a elementos DOM necesarios para funcionalidades como
+ * el indicador visual y navegación por teclado.
+ *
+ * Soporta tanto modo controlled (pasando prop `open`) como uncontrolled
+ * (usando `defaultOpen`).
+ *
+ * @example
+ * ```tsx
+ * // Modo uncontrolled
+ * <SidebarProvider defaultOpen={true}>
+ *   <SidebarNav>...</SidebarNav>
+ * </SidebarProvider>
+ *
+ * // Modo controlled
+ * <SidebarProvider
+ *   open={isOpen}
+ *   onOpenChange={setIsOpen}
+ * >
+ *   <SidebarNav>...</SidebarNav>
+ * </SidebarProvider>
+ * ```
+ */
+export declare function SidebarProvider({ children, defaultOpen, open: controlledOpen, onOpenChange, collapseMode, hideBehaviour, hideOpensBehavior, layoutBehaviour, dimensions: dimensionsProp, safeAreas: safeAreasProp, animations: animationsProp, toggleId, debug, enableFluidIndicator, enableTooltip, }: SidebarProviderProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=SidebarContext.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SidebarContext.d.ts","sourceRoot":"","sources":["../../../../src/react-ui/blocks/Sidebar/SidebarContext.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,OAAO,CAAA;AAEjD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,SAAS,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,eAAO,MAAM,iBAAiB;mBACb,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC;wBACtB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,KAAK,IAAI;0BAC5C,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI;mBAC/B,CAAC,MAAM,EAAE,MAAM,KAAK,cAAc,GAAG,SAAS;SAChD,CAAA;AAEf,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EACxB,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,iBAAiB,CAAA;AASxB;;;GAGG;AACH,eAAO,MAAM,cAAc,qDAAkD,CAAA;AAE7E;;;GAGG;AACH,UAAU,oBAAoB;IAC5B,0DAA0D;IAC1D,QAAQ,EAAE,SAAS,CAAA;IACnB,iDAAiD;IACjD,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,uCAAuC;IACvC,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,4CAA4C;IAC5C,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC,kCAAkC;IAClC,YAAY,CAAC,EAAE,mBAAmB,CAAA;IAClC,kCAAkC;IAClC,aAAa,CAAC,EAAE,oBAAoB,CAAA;IACpC,yCAAyC;IACzC,iBAAiB,CAAC,EAAE,wBAAwB,CAAA;IAC5C,2CAA2C;IAC3C,eAAe,CAAC,EAAE,sBAAsB,CAAA;IACxC,mCAAmC;IACnC,UAAU,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAA;IACvC,kCAAkC;IAClC,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;IACrC,mCAAmC;IACnC,UAAU,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAA;IACvC,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,qEAAqE;IACrE,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B,iEAAiE;IACjE,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,eAAe,CAAC,EAC9B,QAAQ,EACR,WAAwC,EACxC,IAAI,EAAE,cAAc,EACpB,YAAY,EACZ,YAA0C,EAC1C,aAA4C,EAC5C,iBAAoD,EACpD,eAAgD,EAChD,UAAU,EAAE,cAAc,EAC1B,SAAS,EAAE,aAAa,EACxB,UAAU,EAAE,cAAc,EAC1B,QAAkC,EAClC,KAA4B,EAC5B,oBAA4B,EAC5B,aAAoB,GACrB,EAAE,oBAAoB,2CA8KtB"}

package/dist/react-ui/blocks/Sidebar/SidebarContext.js

@@ -0,0 +1,178 @@
+"use client";
+
+import { DEFAULT_ANIMATIONS, DEFAULT_CONFIG, DEFAULT_DIMENSIONS, DEFAULT_SAFE_AREAS } from "./Sidebar.constants.js";
+import { createContext, useCallback, useMemo, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/react-ui/blocks/Sidebar/SidebarContext.tsx
+const SubContentContext = createContext(null);
+/**
+* Contexto del Sidebar para compartir estado entre componentes primitivos
+* @constant
+*/
+const SidebarContext = createContext(null);
+/**
+* Provider del contexto del Sidebar
+*
+* @description
+* Componente que provee el contexto compartido a todos los componentes
+* primitivos del sidebar. Gestiona el estado global (open/closed) y
+* referencias a elementos DOM necesarios para funcionalidades como
+* el indicador visual y navegación por teclado.
+*
+* Soporta tanto modo controlled (pasando prop `open`) como uncontrolled
+* (usando `defaultOpen`).
+*
+* @example
+* ```tsx
+* // Modo uncontrolled
+* <SidebarProvider defaultOpen={true}>
+*   <SidebarNav>...</SidebarNav>
+* </SidebarProvider>
+*
+* // Modo controlled
+* <SidebarProvider
+*   open={isOpen}
+*   onOpenChange={setIsOpen}
+* >
+*   <SidebarNav>...</SidebarNav>
+* </SidebarProvider>
+* ```
+*/
+function SidebarProvider({ children, defaultOpen = DEFAULT_CONFIG.defaultOpen, open: controlledOpen, onOpenChange, collapseMode = DEFAULT_CONFIG.collapseMode, hideBehaviour = DEFAULT_CONFIG.hideBehaviour, hideOpensBehavior = DEFAULT_CONFIG.hideOpensBehavior, layoutBehaviour = DEFAULT_CONFIG.layoutBehaviour, dimensions: dimensionsProp, safeAreas: safeAreasProp, animations: animationsProp, toggleId = DEFAULT_CONFIG.toggleId, debug = DEFAULT_CONFIG.debug, enableFluidIndicator = false, enableTooltip = true }) {
+	const [internalOpen, setInternalOpen] = useState(defaultOpen);
+	const open = controlledOpen !== void 0 ? controlledOpen : internalOpen;
+	const setOpen = useCallback((newOpen) => {
+		if (controlledOpen === void 0) setInternalOpen(newOpen);
+		onOpenChange?.(newOpen);
+	}, [controlledOpen, onOpenChange]);
+	const navRef = useRef(null);
+	const contentRef = useRef(null);
+	const indicatorRef = useRef(null);
+	const [items, setItems] = useState([]);
+	const [showIndicatorForKeyboard, setShowIndicatorForKeyboard] = useState(false);
+	const [isOverItems, setIsOverItems] = useState(false);
+	const [currentItemElement, setCurrentItemElement] = useState(null);
+	const [subContentMap] = useState(() => /* @__PURE__ */ new Map());
+	/**
+	* Registrar subContent de un item
+	*/
+	const registerSubContent = useCallback((itemId, data) => {
+		subContentMap.set(itemId, data);
+	}, [subContentMap]);
+	/**
+	* Des-registrar subContent de un item
+	*/
+	const unregisterSubContent = useCallback((itemId) => {
+		subContentMap.delete(itemId);
+	}, [subContentMap]);
+	/**
+	* Obtener subContent de un item
+	*/
+	const getSubContent = useCallback((itemId) => {
+		return subContentMap.get(itemId);
+	}, [subContentMap]);
+	/**
+	* Registrar un item para navegación por teclado
+	*/
+	const registerItem = useCallback((element) => {
+		setItems((prev) => {
+			if (prev.includes(element)) return prev;
+			return [...prev, element];
+		});
+	}, []);
+	/**
+	* Des-registrar un item cuando se desmonta
+	*/
+	const unregisterItem = useCallback((element) => {
+		setItems((prev) => prev.filter((item) => item !== element));
+	}, []);
+	const dimensions = useMemo(() => ({
+		...DEFAULT_DIMENSIONS,
+		...dimensionsProp
+	}), [dimensionsProp]);
+	const safeAreas = useMemo(() => ({
+		...DEFAULT_SAFE_AREAS,
+		...safeAreasProp
+	}), [safeAreasProp]);
+	const animations = useMemo(() => ({
+		...DEFAULT_ANIMATIONS,
+		...animationsProp
+	}), [animationsProp]);
+	const contextValue = useMemo(() => ({
+		defaultOpen,
+		open,
+		setOpen,
+		collapseMode,
+		hideBehaviour,
+		hideOpensBehavior,
+		layoutBehaviour,
+		dimensions,
+		safeAreas,
+		animations,
+		toggleId,
+		debug,
+		navRef,
+		contentRef,
+		indicatorRef,
+		registerItem,
+		unregisterItem,
+		items,
+		showIndicatorForKeyboard,
+		setShowIndicatorForKeyboard,
+		isOverItems,
+		setIsOverItems,
+		enableFluidIndicator,
+		enableTooltip,
+		currentItemElement,
+		setCurrentItemElement
+	}), [
+		defaultOpen,
+		open,
+		setOpen,
+		collapseMode,
+		hideBehaviour,
+		hideOpensBehavior,
+		layoutBehaviour,
+		dimensions,
+		safeAreas,
+		animations,
+		toggleId,
+		debug,
+		navRef,
+		contentRef,
+		indicatorRef,
+		registerItem,
+		unregisterItem,
+		items,
+		showIndicatorForKeyboard,
+		setShowIndicatorForKeyboard,
+		isOverItems,
+		setIsOverItems,
+		enableFluidIndicator,
+		enableTooltip,
+		currentItemElement,
+		setCurrentItemElement
+	]);
+	const subContentContextValue = useMemo(() => ({
+		subContentMap,
+		registerSubContent,
+		unregisterSubContent,
+		getSubContent
+	}), [
+		subContentMap,
+		registerSubContent,
+		unregisterSubContent,
+		getSubContent
+	]);
+	return /* @__PURE__ */ jsx(SidebarContext.Provider, {
+		value: contextValue,
+		children: /* @__PURE__ */ jsx(SubContentContext.Provider, {
+			value: subContentContextValue,
+			children
+		})
+	});
+}
+
+//#endregion
+export { SidebarContext, SidebarProvider, SubContentContext };

package/dist/react-ui/blocks/Sidebar/SidebarFluidIndicator.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Props del SidebarFluidIndicator
+ * @interface
+ */
+export interface SidebarFluidIndicatorProps {
+    /** Elemento del item actualmente hovered/focused */
+    targetElement: HTMLElement | null;
+    /** Indica si el indicador está visible */
+    isVisible: boolean;
+}
+/**
+ * SidebarFluidIndicator - Wrapper around FluidHoverIndicator
+ *
+ * @description
+ * Este componente usa FluidHoverIndicator que implementa spring physics
+ * con anticipation, stretch, overshoot y settle para animaciones fluidas.
+ * - Spring physics con morphing basado en dirección de movimiento
+ * - WAAPI para animaciones de alto rendimiento
+ * - Soporta containerRef para posicionamiento relativo
+ *
+ * @example
+ * ```tsx
+ * <SidebarNav>
+ *   <SidebarIndicator />
+ *   <SidebarFluidIndicator targetElement={currentItemElement} isVisible={isVisible} />
+ *   <SidebarContent>...</SidebarContent>
+ * </SidebarNav>
+ * ```
+ */
+export declare function SidebarFluidIndicator({ targetElement, isVisible }: SidebarFluidIndicatorProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=SidebarFluidIndicator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SidebarFluidIndicator.d.ts","sourceRoot":"","sources":["../../../../src/react-ui/blocks/Sidebar/SidebarFluidIndicator.tsx"],"names":[],"mappings":"AAKA;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,oDAAoD;IACpD,aAAa,EAAE,WAAW,GAAG,IAAI,CAAA;IACjC,0CAA0C;IAC1C,SAAS,EAAE,OAAO,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,aAAa,EAAE,SAAS,EAAE,EAAE,0BAA0B,2CAU7F"}

package/dist/react-ui/blocks/Sidebar/SidebarFluidIndicator.js

@@ -0,0 +1,37 @@
+"use client";
+
+import { useSidebarContext } from "./hooks/useSidebarContext.js";
+import { FluidHoverIndicator } from "./components/FluidHoverIndicator.js";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/react-ui/blocks/Sidebar/SidebarFluidIndicator.tsx
+/**
+* SidebarFluidIndicator - Wrapper around FluidHoverIndicator
+*
+* @description
+* Este componente usa FluidHoverIndicator que implementa spring physics
+* con anticipation, stretch, overshoot y settle para animaciones fluidas.
+* - Spring physics con morphing basado en dirección de movimiento
+* - WAAPI para animaciones de alto rendimiento
+* - Soporta containerRef para posicionamiento relativo
+*
+* @example
+* ```tsx
+* <SidebarNav>
+*   <SidebarIndicator />
+*   <SidebarFluidIndicator targetElement={currentItemElement} isVisible={isVisible} />
+*   <SidebarContent>...</SidebarContent>
+* </SidebarNav>
+* ```
+*/
+function SidebarFluidIndicator({ targetElement, isVisible }) {
+	const { navRef } = useSidebarContext();
+	return /* @__PURE__ */ jsx(FluidHoverIndicator, {
+		targetElement,
+		isVisible,
+		containerRef: navRef
+	});
+}
+
+//#endregion
+export { SidebarFluidIndicator };

package/dist/react-ui/blocks/Sidebar/SidebarIndicator.d.ts

@@ -0,0 +1,59 @@
+import type { SidebarIndicatorProps } from "./Sidebar.types";
+/**
+ * Componente de indicador visual del Sidebar
+ *
+ * @description
+ * Indicador visual que sigue al cursor del mouse (o item enfocado) dentro
+ * del área de navegación. Proporciona feedback visual claro al usuario.
+ *
+ * Características:
+ * - Se muestra solo cuando el mouse está sobre el área de items
+ * - Sigue al cursor con animación suave
+ * - Se posiciona en el item enfocado al navegar por teclado
+ * - Totalmente customizable con className y style
+ * - Soporta render props para control total del contenido
+ * - Color y dimensiones configurables via contexto
+ *
+ * El indicador se oculta automáticamente cuando:
+ * - El mouse sale del sidebar
+ * - El cursor está fuera del área de items
+ * - Se pierde el focus del sidebar
+ *
+ * @example
+ * ```tsx
+ * // Uso básico con estilos por defecto
+ * <SidebarNav>
+ *   <SidebarIndicator />
+ *   <SidebarContent>...</SidebarContent>
+ * </SidebarNav>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con estilos custom
+ * <SidebarIndicator className="bg-red-500 w-1" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con render props
+ * <SidebarIndicator>
+ *   {({ visible, position }) => (
+ *     <div
+ *       className={cn('indicator', visible && 'opacity-100')}
+ *       style={{ top: position }}
+ *     >
+ *       <span>→</span>
+ *     </div>
+ *   )}
+ * </SidebarIndicator>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Como elemento custom
+ * <SidebarIndicator as={motion.div} animate={{ opacity: 1 }} />
+ * ```
+ */
+export declare const SidebarIndicator: import("react").ForwardRefExoticComponent<SidebarIndicatorProps & import("react").RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=SidebarIndicator.d.ts.map