@mks2508/mks-ui 0.6.8 → 0.7.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"SidebarIndicator.d.ts","sourceRoot":"","sources":["../../../../src/react-ui/blocks/Sidebar/SidebarIndicator.tsx"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,qBAAqB,EAA8B,MAAM,iBAAiB,CAAA;AAGxF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,eAAO,MAAM,gBAAgB,kHAkE5B,CAAA"}

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

@@ -0,0 +1,106 @@
+"use client";
+
+import { SIDEBAR_DATA_ATTRIBUTES, SIDEBAR_TAILWIND_CLASSES } from "./Sidebar.constants.js";
+import { useSidebarContext } from "./hooks/useSidebarContext.js";
+import { useSidebarIndicator } from "./hooks/useSidebarIndicator.js";
+import { forwardRef } from "react";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/react-ui/blocks/Sidebar/SidebarIndicator.tsx
+/**
+* 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 }} />
+* ```
+*/
+const SidebarIndicator = forwardRef(function SidebarIndicator({ children, className = "", style, as, ...props }, forwardedRef) {
+	const { indicatorRef } = useSidebarContext();
+	const { isVisible } = useSidebarIndicator();
+	const isRenderProp = typeof children === "function";
+	const indicatorState = {
+		visible: isVisible,
+		position: 0
+	};
+	const Component = as || "div";
+	const indicatorStyles = {
+		background: "var(--sidebar-primary)",
+		transform: "translateY(-50%)",
+		opacity: isVisible ? 1 : 0,
+		height: "var(--sidebar-indicator-height, 3rem)",
+		width: "0.25rem",
+		anchorName: "--sidebar-indicator",
+		...style
+	};
+	const setRefs = (node) => {
+		if (indicatorRef && "current" in indicatorRef) indicatorRef.current = node;
+		if (typeof forwardedRef === "function") forwardedRef(node);
+		else if (forwardedRef) forwardedRef.current = node;
+	};
+	if (isRenderProp) return /* @__PURE__ */ jsx(Component, {
+		ref: setRefs,
+		...props,
+		children: children(indicatorState)
+	});
+	return /* @__PURE__ */ jsx(Component, {
+		ref: setRefs,
+		className: `sidebar-indicator ${SIDEBAR_TAILWIND_CLASSES.indicator} ${className}`,
+		style: indicatorStyles,
+		"aria-hidden": "true",
+		[SIDEBAR_DATA_ATTRIBUTES.VISIBLE]: isVisible,
+		...props,
+		children
+	});
+});
+
+//#endregion
+export { SidebarIndicator };

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

@@ -0,0 +1,82 @@
+import type { SidebarItemProps } from "./Sidebar.types";
+/**
+ * Componente item de navegación del Sidebar
+ *
+ * @description
+ * Item individual de navegación dentro del sidebar.
+ * Renderiza un `<a>` por defecto, pero puede ser cualquier elemento
+ * o componente (ej: React Router Link, Next.js Link).
+ *
+ * Características:
+ * - Soporta iconos y labels
+ * - Gestiona estados de hover y focus
+ * - Se registra automáticamente para navegación por teclado
+ * - Aplica data attributes para styling
+ * - Soporta render props para control total
+ * - Compatible con React Router, Next.js, etc. via prop `as`
+ * - Label oculto automáticamente cuando sidebar está colapsado (via CSS container queries)
+ *
+ * @example
+ * ```tsx
+ * // Uso básico
+ * <SidebarItem
+ *   href="/"
+ *   icon={<HomeIcon />}
+ *   label="Home"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con React Router
+ * <SidebarItem
+ *   as={Link}
+ *   to="/dashboard"
+ *   icon={<DashboardIcon />}
+ *   label="Dashboard"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con Next.js Link
+ * <SidebarItem
+ *   LinkComponent={Link}
+ *   href="/profile"
+ *   icon={<UserIcon />}
+ *   label="Profile"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con render props
+ * <SidebarItem href="/settings">
+ *   {({ focused, hovered, disabled }) => (
+ *     <div className={cn(
+ *       'flex items-center gap-2',
+ *       focused && 'ring-2',
+ *       hovered && 'bg-zinc-800',
+ *       disabled && 'opacity-50'
+ *     )}>
+ *       <SettingsIcon />
+ *       <span>Settings</span>
+ *     </div>
+ *   )}
+ * </SidebarItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con callbacks
+ * <SidebarItem
+ *   href="/analytics"
+ *   icon={<ChartIcon />}
+ *   label="Analytics"
+ *   onHover={() => prefetchAnalytics()}
+ *   onClick={() => trackNavigation('analytics')}
+ * />
+ * ```
+ */
+export declare const SidebarItem: import("react").ForwardRefExoticComponent<SidebarItemProps & import("react").RefAttributes<HTMLAnchorElement>>;
+//# sourceMappingURL=SidebarItem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SidebarItem.d.ts","sourceRoot":"","sources":["../../../../src/react-ui/blocks/Sidebar/SidebarItem.tsx"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,gBAAgB,EAAiD,MAAM,iBAAiB,CAAA;AAQtG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,eAAO,MAAM,WAAW,gHAwKtB,CAAA"}

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

@@ -0,0 +1,209 @@
+"use client";
+
+import { SIDEBAR_ARIA_ROLES, SIDEBAR_DATA_ATTRIBUTES } from "./Sidebar.constants.js";
+import { useSidebarContext } from "./hooks/useSidebarContext.js";
+import { useSubContent } from "./hooks/useSubContent.js";
+import { SidebarSubContent } from "./SidebarSubContent.js";
+import { Children, forwardRef, isValidElement, useEffect, useId, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/react-ui/blocks/Sidebar/SidebarItem.tsx
+/**
+* Componente item de navegación del Sidebar
+*
+* @description
+* Item individual de navegación dentro del sidebar.
+* Renderiza un `<a>` por defecto, pero puede ser cualquier elemento
+* o componente (ej: React Router Link, Next.js Link).
+*
+* Características:
+* - Soporta iconos y labels
+* - Gestiona estados de hover y focus
+* - Se registra automáticamente para navegación por teclado
+* - Aplica data attributes para styling
+* - Soporta render props para control total
+* - Compatible con React Router, Next.js, etc. via prop `as`
+* - Label oculto automáticamente cuando sidebar está colapsado (via CSS container queries)
+*
+* @example
+* ```tsx
+* // Uso básico
+* <SidebarItem
+*   href="/"
+*   icon={<HomeIcon />}
+*   label="Home"
+* />
+* ```
+*
+* @example
+* ```tsx
+* // Con React Router
+* <SidebarItem
+*   as={Link}
+*   to="/dashboard"
+*   icon={<DashboardIcon />}
+*   label="Dashboard"
+* />
+* ```
+*
+* @example
+* ```tsx
+* // Con Next.js Link
+* <SidebarItem
+*   LinkComponent={Link}
+*   href="/profile"
+*   icon={<UserIcon />}
+*   label="Profile"
+* />
+* ```
+*
+* @example
+* ```tsx
+* // Con render props
+* <SidebarItem href="/settings">
+*   {({ focused, hovered, disabled }) => (
+*     <div className={cn(
+*       'flex items-center gap-2',
+*       focused && 'ring-2',
+*       hovered && 'bg-zinc-800',
+*       disabled && 'opacity-50'
+*     )}>
+*       <SettingsIcon />
+*       <span>Settings</span>
+*     </div>
+*   )}
+* </SidebarItem>
+* ```
+*
+* @example
+* ```tsx
+* // Con callbacks
+* <SidebarItem
+*   href="/analytics"
+*   icon={<ChartIcon />}
+*   label="Analytics"
+*   onHover={() => prefetchAnalytics()}
+*   onClick={() => trackNavigation('analytics')}
+* />
+* ```
+*/
+const SidebarItem = forwardRef(function SidebarItem({ href, icon, label, children, LinkComponent, linkProps = {}, className = "", style, onHover, onClick, disabled = false, as, ...props }, forwardedRef) {
+	const { registerItem, unregisterItem } = useSidebarContext();
+	const { registerSubContent, unregisterSubContent } = useSubContent();
+	const [isHovered, setIsHovered] = useState(false);
+	const [isFocused, setIsFocused] = useState(false);
+	const itemId = useId();
+	let subContentElement = null;
+	let otherChildren = null;
+	if (children && typeof children !== "function") Children.forEach(children, (child) => {
+		if (isValidElement(child) && child.type === SidebarSubContent) subContentElement = child;
+		else otherChildren = child;
+	});
+	const isRenderProp = typeof children === "function";
+	const itemState = {
+		focused: isFocused,
+		hovered: isHovered,
+		disabled
+	};
+	const Component = as || LinkComponent || "a";
+	const itemStyles = {
+		paddingTop: "calc(var(--sidebar-items-gap) / 2)",
+		paddingBottom: "calc(var(--sidebar-items-gap) / 2)",
+		flex: "1 1 auto",
+		minHeight: "3rem",
+		...style
+	};
+	const handleMouseEnter = () => {
+		setIsHovered(true);
+		onHover?.();
+	};
+	const handleMouseLeave = () => {
+		setIsHovered(false);
+	};
+	const handleFocus = () => {
+		setIsFocused(true);
+	};
+	const handleBlur = () => {
+		setIsFocused(false);
+	};
+	const handleClick = (e) => {
+		if (disabled) {
+			e.preventDefault();
+			return;
+		}
+		onClick?.();
+	};
+	useEffect(() => {
+		const element = forwardedRef && "current" in forwardedRef ? forwardedRef.current : null;
+		if (element) {
+			registerItem(element);
+			return () => unregisterItem(element);
+		}
+	}, [
+		registerItem,
+		unregisterItem,
+		forwardedRef
+	]);
+	useEffect(() => {
+		if (subContentElement) {
+			registerSubContent(itemId, {
+				itemId,
+				subContent: subContentElement.props.children,
+				title: subContentElement.props.title
+			});
+			return () => unregisterSubContent(itemId);
+		}
+	}, [
+		itemId,
+		subContentElement,
+		registerSubContent,
+		unregisterSubContent
+	]);
+	const baseProps = {
+		ref: forwardedRef,
+		className: `flex items-center justify-center w-full h-12 rounded-lg transition-colors focus-visible:outline-none ${className}`,
+		style: itemStyles,
+		onMouseEnter: handleMouseEnter,
+		onMouseLeave: handleMouseLeave,
+		onFocus: handleFocus,
+		onBlur: handleBlur,
+		onClick: handleClick,
+		role: SIDEBAR_ARIA_ROLES.listitem,
+		"aria-label": label,
+		title: label,
+		tabIndex: disabled ? -1 : 0,
+		[SIDEBAR_DATA_ATTRIBUTES.ITEM]: "",
+		[SIDEBAR_DATA_ATTRIBUTES.FOCUSED]: isFocused,
+		[SIDEBAR_DATA_ATTRIBUTES.HOVERED]: isHovered,
+		[SIDEBAR_DATA_ATTRIBUTES.DISABLED]: disabled,
+		"data-item-id": itemId,
+		...props
+	};
+	if (isRenderProp) return /* @__PURE__ */ jsx(Component, {
+		...baseProps,
+		children: children(itemState)
+	});
+	if (otherChildren) return /* @__PURE__ */ jsx(Component, {
+		href,
+		...linkProps,
+		...baseProps,
+		children: otherChildren
+	});
+	return /* @__PURE__ */ jsxs(Component, {
+		href,
+		...linkProps,
+		...baseProps,
+		children: [icon && /* @__PURE__ */ jsx("span", {
+			className: "sidebar-item-icon-wrapper relative z-[15] inline-flex items-center justify-center p-2 rounded-xl transition-all duration-300",
+			"data-hovered": isHovered,
+			"data-focused": isFocused,
+			children: icon
+		}), label && /* @__PURE__ */ jsx("span", {
+			className: "sidebar-item-label sr-only",
+			children: label
+		})]
+	});
+});
+
+//#endregion
+export { SidebarItem };

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

@@ -0,0 +1,48 @@
+import type { SidebarNavProps } from "./Sidebar.types";
+/**
+ * Componente de navegación del Sidebar
+ *
+ * @description
+ * Contenedor de navegación que renderiza un elemento `<nav>` por defecto.
+ * Gestiona los eventos de mouse y teclado para el indicador visual y
+ * la navegación accesible.
+ *
+ * Este componente:
+ * - Aplica data attributes para reflejar el estado (open/collapsed)
+ * - Gestiona eventos de mouse para el indicador visual
+ * - Gestiona navegación por teclado (arrows, home, end)
+ * - Expone una ref al elemento DOM para mediciones
+ *
+ * Usa forwardRef para permitir acceso al elemento DOM desde componentes padre.
+ *
+ * @example
+ * ```tsx
+ * <Sidebar>
+ *   <SidebarNav className="bg-zinc-900 border-zinc-800">
+ *     <SidebarToggle />
+ *     <SidebarIndicator />
+ *     <SidebarContent>
+ *       <SidebarItem href="/" />
+ *     </SidebarContent>
+ *   </SidebarNav>
+ * </Sidebar>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con data attributes para styling
+ * <SidebarNav className="data-[open=true]:w-64 data-[open=false]:w-16">
+ *   {children}
+ * </SidebarNav>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con elemento personalizado
+ * <SidebarNav as="aside" aria-label="Navegación lateral">
+ *   {children}
+ * </SidebarNav>
+ * ```
+ */
+export declare const SidebarNav: import("react").ForwardRefExoticComponent<SidebarNavProps & import("react").RefAttributes<HTMLElement>>;
+//# sourceMappingURL=SidebarNav.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SidebarNav.d.ts","sourceRoot":"","sources":["../../../../src/react-ui/blocks/Sidebar/SidebarNav.tsx"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAYtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,UAAU,yGAmVrB,CAAA"}