@mks2508/mks-ui 0.6.8 → 0.8.0

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

@@ -0,0 +1,80 @@
+import type { SidebarProps } from "./Sidebar.types";
+/**
+ * Componente raíz del Sidebar con arquitectura headless
+ *
+ * @description
+ * Componente principal que provee el contexto compartido a todos los
+ * componentes primitivos del sidebar (SidebarNav, SidebarToggle, etc.).
+ *
+ * Este componente NO renderiza ningún elemento visual por sí mismo,
+ * solo provee el Provider de contexto. Los estilos y estructura visual
+ * se definen componiendo los primitivos hijos.
+ *
+ * Soporta dos modos:
+ * - **Uncontrolled**: Usa `defaultOpen` para estado interno
+ * - **Controlled**: Usa `open` + `onOpenChange` para control externo
+ *
+ * También soporta render props para acceder al estado del sidebar:
+ *
+ * @example
+ * ```tsx
+ * // Uso básico (children estáticos)
+ * <Sidebar defaultOpen={true} collapseMode="collapse">
+ *   <SidebarNav>
+ *     <SidebarToggle />
+ *     <SidebarContent>
+ *       <SidebarItem href="/" icon={<HomeIcon />} />
+ *     </SidebarContent>
+ *   </SidebarNav>
+ * </Sidebar>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con render props (acceso al estado)
+ * <Sidebar>
+ *   {({ open, collapsed }) => (
+ *     <>
+ *       <SidebarNav className={cn(!open && 'hidden')}>
+ *         <SidebarContent>
+ *           <SidebarItem label={open ? "Home" : undefined} />
+ *         </SidebarContent>
+ *       </SidebarNav>
+ *       <div>Sidebar is {open ? 'open' : 'closed'}</div>
+ *     </>
+ *   )}
+ * </Sidebar>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Modo controlled
+ * function App() {
+ *   const [open, setOpen] = useState(true)
+ *
+ *   return (
+ *     <Sidebar open={open} onOpenChange={setOpen}>
+ *       <SidebarNav>...</SidebarNav>
+ *     </Sidebar>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con configuración custom
+ * <Sidebar
+ *   collapseMode="hide"
+ *   dimensions={{ expandedWidth: "20rem" }}
+ *   animations={{ widthTransitionDuration: 500 }}
+ * >
+ *   <SidebarNav>...</SidebarNav>
+ * </Sidebar>
+ * ```
+ *
+ * @note
+ * Los colores se obtienen automáticamente de los tokens CSS de shadcn definidos
+ * en globals.css (--sidebar, --sidebar-accent, --sidebar-primary, etc.)
+ */
+export declare function Sidebar({ children, className, style, defaultOpen, open, onOpenChange, collapseMode, hideBehaviour, hideOpensBehavior, layoutBehaviour, dimensions, animations, toggleId, debug, enableFluidIndicator, enableTooltip, as, }: SidebarProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=Sidebar.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Sidebar.d.ts","sourceRoot":"","sources":["../../../../src/react-ui/blocks/Sidebar/Sidebar.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAqB,MAAM,iBAAiB,CAAA;AAGtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AACH,wBAAgB,OAAO,CAAC,EACtB,QAAQ,EACR,SAAS,EACT,KAAK,EACL,WAAwC,EACxC,IAAI,EACJ,YAAY,EACZ,YAA0C,EAC1C,aAA4C,EAC5C,iBAAoD,EACpD,eAAgD,EAChD,UAAU,EACV,UAAU,EACV,QAAkC,EAClC,KAA4B,EAC5B,oBAA4B,EAC5B,aAAoB,EACpB,EAAE,GACH,EAAE,YAAY,2CAmCd"}

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

@@ -0,0 +1,114 @@
+"use client";
+
+import { DEFAULT_CONFIG } from "./Sidebar.constants.js";
+import { SidebarProvider } from "./SidebarContext.js";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/react-ui/blocks/Sidebar/Sidebar.tsx
+/**
+* Componente raíz del Sidebar con arquitectura headless
+*
+* @description
+* Componente principal que provee el contexto compartido a todos los
+* componentes primitivos del sidebar (SidebarNav, SidebarToggle, etc.).
+*
+* Este componente NO renderiza ningún elemento visual por sí mismo,
+* solo provee el Provider de contexto. Los estilos y estructura visual
+* se definen componiendo los primitivos hijos.
+*
+* Soporta dos modos:
+* - **Uncontrolled**: Usa `defaultOpen` para estado interno
+* - **Controlled**: Usa `open` + `onOpenChange` para control externo
+*
+* También soporta render props para acceder al estado del sidebar:
+*
+* @example
+* ```tsx
+* // Uso básico (children estáticos)
+* <Sidebar defaultOpen={true} collapseMode="collapse">
+*   <SidebarNav>
+*     <SidebarToggle />
+*     <SidebarContent>
+*       <SidebarItem href="/" icon={<HomeIcon />} />
+*     </SidebarContent>
+*   </SidebarNav>
+* </Sidebar>
+* ```
+*
+* @example
+* ```tsx
+* // Con render props (acceso al estado)
+* <Sidebar>
+*   {({ open, collapsed }) => (
+*     <>
+*       <SidebarNav className={cn(!open && 'hidden')}>
+*         <SidebarContent>
+*           <SidebarItem label={open ? "Home" : undefined} />
+*         </SidebarContent>
+*       </SidebarNav>
+*       <div>Sidebar is {open ? 'open' : 'closed'}</div>
+*     </>
+*   )}
+* </Sidebar>
+* ```
+*
+* @example
+* ```tsx
+* // Modo controlled
+* function App() {
+*   const [open, setOpen] = useState(true)
+*
+*   return (
+*     <Sidebar open={open} onOpenChange={setOpen}>
+*       <SidebarNav>...</SidebarNav>
+*     </Sidebar>
+*   )
+* }
+* ```
+*
+* @example
+* ```tsx
+* // Con configuración custom
+* <Sidebar
+*   collapseMode="hide"
+*   dimensions={{ expandedWidth: "20rem" }}
+*   animations={{ widthTransitionDuration: 500 }}
+* >
+*   <SidebarNav>...</SidebarNav>
+* </Sidebar>
+* ```
+*
+* @note
+* Los colores se obtienen automáticamente de los tokens CSS de shadcn definidos
+* en globals.css (--sidebar, --sidebar-accent, --sidebar-primary, etc.)
+*/
+function Sidebar({ children, className, style, defaultOpen = DEFAULT_CONFIG.defaultOpen, open, onOpenChange, collapseMode = DEFAULT_CONFIG.collapseMode, hideBehaviour = DEFAULT_CONFIG.hideBehaviour, hideOpensBehavior = DEFAULT_CONFIG.hideOpensBehavior, layoutBehaviour = DEFAULT_CONFIG.layoutBehaviour, dimensions, animations, toggleId = DEFAULT_CONFIG.toggleId, debug = DEFAULT_CONFIG.debug, enableFluidIndicator = false, enableTooltip = true, as }) {
+	return /* @__PURE__ */ jsx(SidebarProvider, {
+		defaultOpen,
+		open,
+		onOpenChange,
+		collapseMode,
+		hideBehaviour,
+		hideOpensBehavior,
+		layoutBehaviour,
+		dimensions,
+		animations,
+		toggleId,
+		debug,
+		enableFluidIndicator,
+		enableTooltip,
+		children: /* @__PURE__ */ jsx(as || "div", {
+			className,
+			style,
+			children: typeof children === "function" ? children({
+				open: open ?? defaultOpen,
+				collapsed: !open && collapseMode === "collapse",
+				collapseMode,
+				layoutBehaviour
+			}) : children
+		})
+	});
+}
+
+//#endregion
+export { Sidebar };

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

@@ -0,0 +1,77 @@
+import type { SidebarDimensions, SidebarAnimations, SidebarCollapseMode, SidebarHideOpensBehavior, SidebarVisualStyle } from "./Sidebar.types";
+import { SidebarLayoutBehaviour } from "./Sidebar.types";
+/**
+ * Configuración para el generador de estilos
+ * @interface
+ */
+interface StyleGeneratorConfig {
+    dimensions: SidebarDimensions;
+    animations: SidebarAnimations;
+    collapseMode: SidebarCollapseMode;
+    hideOpensBehavior: SidebarHideOpensBehavior;
+    layoutBehaviour: SidebarLayoutBehaviour;
+    visualStyle: SidebarVisualStyle;
+}
+/**
+ * Genera los estilos CSS del sidebar usando CSS-in-JS y tokens de mks-ui
+ *
+ * @description
+ * Función que genera todo el CSS necesario para el sidebar,
+ * utilizando los tokens CSS de mks-ui definidos en index.css:
+ *
+ * **Tokens utilizados:**
+ * - `--sidebar`: Color de fondo
+ * - `--sidebar-foreground`: Color de texto
+ * - `--sidebar-primary`: Color primario (indicador, elementos activos)
+ * - `--sidebar-accent`: Color de hover y estados secundarios
+ * - `--sidebar-border`: Color de bordes
+ * - `--sidebar-ring`: Color de focus ring (accesibilidad)
+ *
+ * Usa CSS Layers para organización y control de especificidad:
+ * - sidebar-base: Variables y estilos base
+ * - sidebar-states: Estados (:checked, :hover, etc.)
+ * - sidebar-animations: Transiciones y animaciones
+ *
+ * @param {StyleGeneratorConfig} config - Configuración de dimensiones y animaciones
+ * @returns {string} String con el CSS completo
+ *
+ * @example
+ * ```tsx
+ * const styles = generateSidebarStyles({
+ *   dimensions: DEFAULT_DIMENSIONS,
+ *   animations: DEFAULT_ANIMATIONS,
+ *   collapseMode: SidebarCollapseMode.COLLAPSE,
+ *   hideOpensBehavior: SidebarHideOpensBehavior.COLLAPSED
+ * })
+ *
+ * <style dangerouslySetInnerHTML={{ __html: styles }} />
+ * ```
+ *
+ * @note
+ * Los colores se configuran vía CSS custom properties (--sidebar-bg, etc.)
+ * que se mapean a los tokens de mks-ui para soporte automático de dark/light mode.
+ */
+export declare function generateSidebarStyles({ dimensions, animations, collapseMode, hideOpensBehavior, layoutBehaviour, visualStyle, }: StyleGeneratorConfig): string;
+/**
+ * Genera estilos para el indicador visual usando tokens CSS
+ *
+ * @description
+ * Función auxiliar para generar estilos dinámicos del indicador.
+ * Útil para aplicar estilos inline con estado reactivo.
+ *
+ * Utiliza el token `--sidebar-primary` para el color del indicador,
+ * asegurando consistencia con el theme del sidebar.
+ *
+ * @param {boolean} isVisible - Si el indicador está visible
+ * @returns {React.CSSProperties} Objeto de estilos inline
+ *
+ * @example
+ * ```tsx
+ * const indicatorStyles = generateIndicatorStyles(isHovering && isOverItems)
+ *
+ * <div style={indicatorStyles} />
+ * ```
+ */
+export declare function generateIndicatorStyles(isVisible: boolean): React.CSSProperties;
+export {};
+//# sourceMappingURL=Sidebar.styles.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Sidebar.styles.d.ts","sourceRoot":"","sources":["../../../../src/react-ui/blocks/Sidebar/Sidebar.styles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,kBAAkB,EACnB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AAGxD;;;GAGG;AACH,UAAU,oBAAoB;IAC5B,UAAU,EAAE,iBAAiB,CAAA;IAC7B,UAAU,EAAE,iBAAiB,CAAA;IAC7B,YAAY,EAAE,mBAAmB,CAAA;IACjC,iBAAiB,EAAE,wBAAwB,CAAA;IAC3C,eAAe,EAAE,sBAAsB,CAAA;IACvC,WAAW,EAAE,kBAAkB,CAAA;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,UAAU,EACV,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,WAAW,GACZ,EAAE,oBAAoB,GAAG,MAAM,CAkN/B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,OAAO,GAAG,KAAK,CAAC,aAAa,CAQ/E"}

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

@@ -0,0 +1,274 @@
+import { SidebarLayoutBehaviour } from "./Sidebar.types.js";
+import { DEFAULT_VISUAL_STYLE, SIDEBAR_CSS_VARIABLES } from "./Sidebar.constants.js";
+
+//#region src/react-ui/blocks/Sidebar/Sidebar.styles.ts
+/**
+* Genera los estilos CSS del sidebar usando CSS-in-JS y tokens de mks-ui
+*
+* @description
+* Función que genera todo el CSS necesario para el sidebar,
+* utilizando los tokens CSS de mks-ui definidos en index.css:
+*
+* **Tokens utilizados:**
+* - `--sidebar`: Color de fondo
+* - `--sidebar-foreground`: Color de texto
+* - `--sidebar-primary`: Color primario (indicador, elementos activos)
+* - `--sidebar-accent`: Color de hover y estados secundarios
+* - `--sidebar-border`: Color de bordes
+* - `--sidebar-ring`: Color de focus ring (accesibilidad)
+*
+* Usa CSS Layers para organización y control de especificidad:
+* - sidebar-base: Variables y estilos base
+* - sidebar-states: Estados (:checked, :hover, etc.)
+* - sidebar-animations: Transiciones y animaciones
+*
+* @param {StyleGeneratorConfig} config - Configuración de dimensiones y animaciones
+* @returns {string} String con el CSS completo
+*
+* @example
+* ```tsx
+* const styles = generateSidebarStyles({
+*   dimensions: DEFAULT_DIMENSIONS,
+*   animations: DEFAULT_ANIMATIONS,
+*   collapseMode: SidebarCollapseMode.COLLAPSE,
+*   hideOpensBehavior: SidebarHideOpensBehavior.COLLAPSED
+* })
+*
+* <style dangerouslySetInnerHTML={{ __html: styles }} />
+* ```
+*
+* @note
+* Los colores se configuran vía CSS custom properties (--sidebar-bg, etc.)
+* que se mapean a los tokens de mks-ui para soporte automático de dark/light mode.
+*/
+function generateSidebarStyles({ dimensions, animations, collapseMode, hideOpensBehavior, layoutBehaviour, visualStyle }) {
+	const widthClosed = collapseMode === "hide" ? "0px" : `clamp(3rem, ${dimensions.collapsedWidth}, 6rem)`;
+	const widthOpen = collapseMode === "hide" && hideOpensBehavior === "collapsed" ? `clamp(3rem, ${dimensions.collapsedWidth}, 6rem)` : `clamp(12rem, ${dimensions.expandedWidth}, 20rem)`;
+	const isInline = layoutBehaviour === SidebarLayoutBehaviour.INLINE;
+	const mergedVisualStyle = {
+		...DEFAULT_VISUAL_STYLE,
+		...visualStyle
+	};
+	return `
+    @layer sidebar-base, sidebar-states, sidebar-animations;
+
+    @layer sidebar-base {
+      :root {
+        ${SIDEBAR_CSS_VARIABLES.widthClosed}: ${widthClosed};
+        ${SIDEBAR_CSS_VARIABLES.widthOpen}: ${widthOpen};
+        ${SIDEBAR_CSS_VARIABLES.width}: var(${SIDEBAR_CSS_VARIABLES.widthClosed});
+        ${SIDEBAR_CSS_VARIABLES.layoutBehaviour}: "${layoutBehaviour}";
+        ${SIDEBAR_CSS_VARIABLES.isInline}: ${isInline ? "1" : "0"};
+        ${SIDEBAR_CSS_VARIABLES.tooltipDistance}: ${dimensions.tooltipDistance || "1rem"};
+
+        /* Variables de estilo visual */
+        ${SIDEBAR_CSS_VARIABLES.marginTop}: ${mergedVisualStyle.marginTop};
+        ${SIDEBAR_CSS_VARIABLES.marginBottom}: ${mergedVisualStyle.marginBottom};
+        ${SIDEBAR_CSS_VARIABLES.marginLeft}: ${mergedVisualStyle.marginLeft};
+        ${SIDEBAR_CSS_VARIABLES.marginRight}: ${mergedVisualStyle.marginRight};
+        ${SIDEBAR_CSS_VARIABLES.sidebarHeight}: ${mergedVisualStyle.height};
+        ${SIDEBAR_CSS_VARIABLES.sidebarBorderRadius}: ${mergedVisualStyle.borderRadius};
+        ${SIDEBAR_CSS_VARIABLES.sidebarBoxShadow}: ${mergedVisualStyle.boxShadow};
+      }
+
+      .sidebar-wrapper {
+        ${SIDEBAR_CSS_VARIABLES.background}: var(--sidebar);
+        ${SIDEBAR_CSS_VARIABLES.borderColor}: var(--sidebar-border);
+        ${SIDEBAR_CSS_VARIABLES.hover}: var(--sidebar-accent);
+        ${SIDEBAR_CSS_VARIABLES.indicator}: var(--sidebar-primary);
+        ${SIDEBAR_CSS_VARIABLES.indicatorHeight}: ${dimensions.indicatorHeight};
+        container-type: inline-size;
+        container-name: sidebar;
+        /* Posicionamiento base */
+        position: ${isInline ? "relative" : "absolute"};
+        z-index: ${isInline ? "auto" : "40"};
+        left: ${isInline ? "auto" : "0"};
+        top: ${isInline ? "auto" : "0"};
+      }
+
+      .sidebar-nav {
+        width: min(var(${SIDEBAR_CSS_VARIABLES.width}), 100vw);
+        border-color: var(${SIDEBAR_CSS_VARIABLES.borderColor});
+        position: ${isInline ? "relative" : "absolute"};
+
+        /* Aplicar variables de estilo visual */
+        margin-top: var(--sidebar-margin-top);
+        margin-bottom: var(--sidebar-margin-bottom);
+        margin-left: var(--sidebar-margin-left);
+        margin-right: var(--sidebar-margin-right);
+        height: var(--sidebar-height);
+        border-radius: var(--sidebar-border-radius);
+        box-shadow: var(--sidebar-box-shadow);
+      }
+    }
+
+    @layer sidebar-states {
+      :root:has(#sidebar-toggle:checked) {
+        ${SIDEBAR_CSS_VARIABLES.width}: var(${SIDEBAR_CSS_VARIABLES.widthOpen});
+      }
+
+      :where(.sidebar-wrapper:has(#sidebar-toggle:checked)) .toggle-icon {
+        transform: rotate(180deg);
+      }
+
+      .sidebar-wrapper:has(#sidebar-toggle:checked) .toggle-button-wrapper {
+        left: calc(var(${SIDEBAR_CSS_VARIABLES.widthOpen}) - 0.75rem);
+      }
+
+      .sidebar-wrapper:not(:has(#sidebar-toggle:checked)) .toggle-button-wrapper {
+        left: ${collapseMode === "hide" ? "-0.75rem" : `calc(${dimensions.collapsedWidth} - 0.75rem)`};
+      }
+    }
+
+    @layer sidebar-layout {
+      /* Inline mode - desplaza contenido */
+      body:has(.sidebar-wrapper[data-layout="inline"]) main {
+        margin-left: var(--sidebar-width);
+        transition: margin-left ${animations.widthTransitionDuration}ms ${animations.timingFunction};
+      }
+
+      /* Floating mode - sin desplazamiento (mantener comportamiento actual) */
+      body:has(.sidebar-wrapper[data-layout="floating"]) main {
+        margin-left: 0;
+      }
+
+      /* Responsive adjustments */
+      @media (max-width: 768px) {
+        body:has(.sidebar-wrapper[data-layout="inline"]) main {
+          margin-left: 0;  /* En mobile, siempre floating */
+        }
+
+        .sidebar-wrapper[data-layout="inline"] {
+          position: absolute;
+          z-index: 40;
+          left: 0;
+          top: 0;
+        }
+
+        .sidebar-wrapper[data-layout="inline"] .sidebar-nav {
+          position: absolute;
+        }
+      }
+    }
+
+    @layer sidebar-visual-responsive {
+      /* Ajustes responsive para visual style */
+      @media (max-width: 768px) {
+        .sidebar-nav {
+          /* En mobile, reducir márgenes para mejor uso de espacio */
+          margin-top: calc(var(--sidebar-margin-top) * 0.5);
+          margin-bottom: calc(var(--sidebar-margin-bottom) * 0.5);
+          margin-left: calc(var(--sidebar-margin-left) * 0.5);
+        }
+      }
+
+      /* Ajustes específicos para layout behaviour */
+      body:has(.sidebar-wrapper[data-layout="inline"]) .sidebar-nav {
+        /* En modo inline, mantener margins */
+        margin-left: var(--sidebar-margin-left);
+      }
+
+      body:has(.sidebar-wrapper[data-layout="floating"]) .sidebar-nav {
+        /* En modo floating, margin-left puede ser útil para separación visual */
+        margin-left: var(--sidebar-margin-left);
+      }
+
+      /* Transiciones suaves para cambios de estilo visual */
+      .sidebar-nav {
+        transition:
+          width ${animations.widthTransitionDuration}ms ${animations.timingFunction},
+          margin-top ${animations.widthTransitionDuration}ms ${animations.timingFunction},
+          margin-bottom ${animations.widthTransitionDuration}ms ${animations.timingFunction},
+          margin-left ${animations.widthTransitionDuration}ms ${animations.timingFunction},
+          margin-right ${animations.widthTransitionDuration}ms ${animations.timingFunction},
+          height ${animations.widthTransitionDuration}ms ${animations.timingFunction},
+          border-radius ${animations.widthTransitionDuration}ms ${animations.timingFunction},
+          box-shadow ${animations.widthTransitionDuration}ms ${animations.timingFunction},
+          overflow ${collapseMode === "hide" ? "hidden" : "visible"};
+      }
+    }
+
+    @layer sidebar-animations {
+      .toggle-icon {
+        transition: transform ${animations.widthTransitionDuration}ms ${animations.timingFunction};
+      }
+
+      .toggle-button-wrapper {
+        transition: left ${animations.widthTransitionDuration}ms ${animations.timingFunction};
+      }
+
+      .sidebar-indicator {
+        transition: opacity ${animations.opacityTransitionDuration}ms ${animations.timingFunction};
+      }
+    }
+
+    @container sidebar (max-width: 80px) {
+      .sidebar-item-label {
+        display: none;
+      }
+    }
+
+    @supports selector(:has(*)) {
+      .sidebar-wrapper:has(.sidebar-nav:hover) {
+        ${SIDEBAR_CSS_VARIABLES.borderColor}: color-mix(in srgb, var(--sidebar-primary) 20%, var(--sidebar-border) 80%);
+      }
+    }
+
+    /* Estilos para el hover/focus del icono elevado - CSS-first */
+    .sidebar-item-icon-wrapper {
+      transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+    }
+
+    /* Elevación con keyboard focus (prioridad siempre) */
+    .sidebar-item-icon-wrapper[data-focused="true"] {
+      background: var(--sidebar-accent);
+      transform: translateY(-2px);
+      box-shadow: 0 4px 8px rgba(0, 0, 0, 0.12);
+    }
+
+    /* Elevación con mouse hover (solo si NO hay focus activo) - Mouse Dominance */
+    .sidebar-nav:not(:has([data-focused="true"])) .sidebar-item-icon-wrapper[data-hovered="true"] {
+      background: var(--sidebar-accent);
+      transform: translateY(-2px);
+      box-shadow: 0 4px 8px rgba(0, 0, 0, 0.12);
+    }
+
+    /* Asegurar que el Icono SVG se escale correctamente */
+    .sidebar-item-icon-wrapper svg {
+      width: 1.5rem;
+      height: 1.5rem;
+    }
+  `;
+}
+/**
+* Genera estilos para el indicador visual usando tokens CSS
+*
+* @description
+* Función auxiliar para generar estilos dinámicos del indicador.
+* Útil para aplicar estilos inline con estado reactivo.
+*
+* Utiliza el token `--sidebar-primary` para el color del indicador,
+* asegurando consistencia con el theme del sidebar.
+*
+* @param {boolean} isVisible - Si el indicador está visible
+* @returns {React.CSSProperties} Objeto de estilos inline
+*
+* @example
+* ```tsx
+* const indicatorStyles = generateIndicatorStyles(isHovering && isOverItems)
+*
+* <div style={indicatorStyles} />
+* ```
+*/
+function generateIndicatorStyles(isVisible) {
+	return {
+		background: "var(--sidebar-primary)",
+		transform: "translateY(-50%)",
+		opacity: isVisible ? 1 : 0,
+		height: `var(${SIDEBAR_CSS_VARIABLES.indicatorHeight})`,
+		width: "0.25rem"
+	};
+}
+
+//#endregion
+export { generateIndicatorStyles, generateSidebarStyles };