@espressif/dashboard-ui-components 1.11.2 → 1.12.0

package/dist/components/cards/index.js

@@ -0,0 +1,8 @@
+import { SimpleCard } from "./simple-card.js";
+import { BasicDetailsCard } from "./basic-details-card.js";
+import NoDataCard from "./no-data-card/no-data-card.js";
+import { CollapsibleCard } from "./collapsible-card.js";
+import { SectionCard } from "./section-card.js";
+import { animatedCardAnimations, animatedCardTypeKeys } from "./animated-card/animated-card-animations.js";
+import { AnimatedCard } from "./animated-card/animated-card.js";
+export { AnimatedCard, BasicDetailsCard, CollapsibleCard, NoDataCard, SectionCard, SimpleCard, animatedCardAnimations, animatedCardTypeKeys };

package/dist/components/cards/section-card.js

@@ -2,15 +2,89 @@
 import { cn } from "../../utils/cn.js";
 import { isPresetColor } from "../../utils/color.js";
 import { resolveVariantStyles } from "../../utils/variant.js";
+import { useHasTooltipProvider } from "../../core/animate-ui/primitives/animate/tooltip.js";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "../../core/animate-ui/components/animate/tooltip.js";
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "../../core/collapsible.js";
 import { Card } from "../../core/card.js";
-import { Tooltip, TooltipContent, TooltipTrigger } from "../../core/animate-ui/components/animate/tooltip.js";
 import { Button } from "../button/button.js";
 import { VariantGradientUnderlay } from "../../utils/variant-gradient-underlay.js";
-import { Children, cloneElement, isValidElement, useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { Children, cloneElement, isValidElement, useCallback, useEffect, useId, useLayoutEffect, useRef, useState } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { ChevronDown, ChevronUp } from "lucide-react";
 //#region src/components/cards/section-card.tsx
+/** Hover intent: a pointer just passing over the card does not open it. */
+var HOVER_OPEN_DELAY_MS = 80;
+/** Grace period so brushing past the card's edge does not collapse it. */
+var HOVER_CLOSE_DELAY_MS = 160;
+var HOVER_BODY_CLASS = cn("grid motion-safe:transition-[grid-template-rows]", "motion-safe:duration-[calc(var(--espd-duration-slow,300ms)*5/3)] motion-safe:ease-[cubic-bezier(0.32,0.72,0,1)]", "data-[state=closed]:grid-rows-[0fr] data-[state=open]:grid-rows-[1fr]", "data-[state=closed]:motion-safe:duration-[calc(var(--espd-duration-slow,300ms)*7/6)] data-[state=closed]:motion-safe:ease-[cubic-bezier(0.4,0,0.2,1)]");
+var HOVER_BODY_INNER_CLASS = cn("min-h-0 overflow-hidden motion-safe:transition-[opacity,translate]", "motion-safe:duration-[calc(var(--espd-duration-slow,300ms)*3/2)] motion-safe:delay-[calc(var(--espd-duration-fast,150ms)/2)] motion-safe:ease-out", "group-data-[state=closed]/hover-body:opacity-0 group-data-[state=closed]/hover-body:-translate-y-1", "group-data-[state=closed]/hover-body:motion-safe:duration-[var(--espd-duration-normal,200ms)] group-data-[state=closed]/hover-body:motion-safe:delay-0");
+var HOVER_ICON_CLASS = cn("motion-safe:transition-[scale,rotate]", "motion-safe:duration-[calc(var(--espd-duration-slow,300ms)*3/2)] motion-safe:ease-[cubic-bezier(0.34,1.56,0.64,1)]", "group-data-[state=open]/section-card:scale-115 group-data-[state=open]/section-card:-rotate-8", "group-data-[state=closed]/section-card:motion-safe:duration-[var(--espd-duration-slow,300ms)] group-data-[state=closed]/section-card:motion-safe:ease-out");
+function useHoverExpand(enabled, onOpenChange) {
+	const [hovered, setHovered] = useState(false);
+	const [focusWithin, setFocusWithin] = useState(false);
+	const [tapOpen, setTapOpen] = useState(false);
+	const rootRef = useRef(null);
+	const timerRef = useRef(null);
+	const lastPointerTypeRef = useRef("");
+	const bodyRef = useRef(null);
+	const clearTimer = () => {
+		if (timerRef.current != null) clearTimeout(timerRef.current);
+		timerRef.current = null;
+	};
+	useEffect(() => clearTimer, []);
+	const open = enabled && (hovered || focusWithin || tapOpen);
+	const onOpenChangeRef = useRef(onOpenChange);
+	onOpenChangeRef.current = onOpenChange;
+	const prevOpenRef = useRef(open);
+	useEffect(() => {
+		if (prevOpenRef.current === open) return;
+		prevOpenRef.current = open;
+		onOpenChangeRef.current?.(open);
+	}, [open]);
+	useLayoutEffect(() => {
+		if (bodyRef.current) bodyRef.current.inert = !open;
+	});
+	useEffect(() => {
+		if (!tapOpen) return;
+		const onDown = (e) => {
+			if (!rootRef.current?.contains(e.target)) setTapOpen(false);
+		};
+		document.addEventListener("pointerdown", onDown);
+		return () => document.removeEventListener("pointerdown", onDown);
+	}, [tapOpen]);
+	const rootProps = enabled ? {
+		ref: rootRef,
+		onPointerDown: (e) => {
+			lastPointerTypeRef.current = e.pointerType;
+		},
+		onPointerEnter: (e) => {
+			if (e.pointerType === "touch") return;
+			clearTimer();
+			timerRef.current = setTimeout(() => setHovered(true), HOVER_OPEN_DELAY_MS);
+		},
+		onPointerLeave: (e) => {
+			if (e.pointerType === "touch") return;
+			clearTimer();
+			timerRef.current = setTimeout(() => setHovered(false), HOVER_CLOSE_DELAY_MS);
+		},
+		onFocus: (e) => {
+			if (e.target.matches?.(":focus-visible")) setFocusWithin(true);
+		},
+		onBlur: (e) => {
+			if (!e.currentTarget.contains(e.relatedTarget)) setFocusWithin(false);
+		}
+	} : void 0;
+	const onHeaderClick = () => {
+		if (lastPointerTypeRef.current === "touch") setTapOpen((v) => !v);
+		lastPointerTypeRef.current = "";
+	};
+	return {
+		open,
+		rootProps,
+		bodyRef,
+		onHeaderClick
+	};
+}
 var sizeStyles = {
 	sm: {
 		pad: "p-3",
@@ -74,7 +148,7 @@ function iconSizedForSection(icon, iconClass) {
 var HEADER_WRAP_ROW_CLASS = "flex-wrap";
 var HEADER_MAIN_BASIS_CLASS = "basis-48";
 var HEADER_RIGHT_CLASS = "ml-auto max-w-full shrink-0";
-var cardClassName = "rounded-lg border-border bg-card shadow-none overflow-hidden";
+var cardClassName = "rounded-[var(--espd-own-radius,var(--espd-radius-surface,var(--radius-lg)))] border-border bg-card shadow-[shadow:var(--espd-own-elevation,var(--espd-elevation-surface,0_0_#0000))] overflow-hidden";
 function hasTooltipContent(content) {
 	if (content == null) return false;
 	if (typeof content === "string") return content.length > 0;
@@ -89,6 +163,7 @@ function hasRenderableContent(content) {
 function TruncatedLineWithTooltip({ className, textStyle, tooltipContent, children }) {
 	const textRef = useRef(null);
 	const [isTruncated, setIsTruncated] = useState(false);
+	const hasTooltipProvider = useHasTooltipProvider();
 	const measure = useCallback(() => {
 		const el = textRef.current;
 		if (!el) return;
@@ -115,7 +190,7 @@ function TruncatedLineWithTooltip({ className, textStyle, tooltipContent, childr
 		children
 	});
 	if (!(isTruncated && hasTooltipContent(tooltipContent))) return line;
-	return /* @__PURE__ */ jsxs(Tooltip, {
+	const tooltip = /* @__PURE__ */ jsxs(Tooltip, {
 		side: "top",
 		children: [/* @__PURE__ */ jsx(TooltipTrigger, {
 			className: "block min-w-0 w-full cursor-inherit text-left",
@@ -128,8 +203,18 @@ function TruncatedLineWithTooltip({ className, textStyle, tooltipContent, childr
 			})
 		})]
 	});
+	if (hasTooltipProvider) return tooltip;
+	return /* @__PURE__ */ jsx(TooltipProvider, {
+		openDelay: 300,
+		closeDelay: 100,
+		children: tooltip
+	});
 }
-function SectionCard({ icon, primaryText, secondaryText, truncateSecondaryText = true, actions, allowCollapse = true, hideCollapseIcon = false, defaultOpen = true, open: controlledOpen, size = "default", variant = "outline", color = "gray", children, className, style, fillHeight = false, onOpenChange }) {
+function SectionCard({ icon, primaryText, secondaryText, truncateSecondaryText = true, actions, allowCollapse: allowCollapseProp = true, hideCollapseIcon = false, defaultOpen = true, open: controlledOpen, size = "default", variant = "outline", color = "gray", children, className, style, fillHeight: fillHeightProp = false, onOpenChange, expandOnHover = false, radius, elevation }) {
+	const allowCollapse = expandOnHover ? false : allowCollapseProp;
+	const fillHeight = expandOnHover ? false : fillHeightProp;
+	const hover = useHoverExpand(expandOnHover, onOpenChange);
+	const hoverBodyId = useId();
 	const s = sizeStyles[size];
 	const resolvedColor = color;
 	const variantStyles = variant != null ? resolveVariantStyles(variant, resolvedColor) : null;
@@ -154,7 +239,7 @@ function SectionCard({ icon, primaryText, secondaryText, truncateSecondaryText =
 	const isHeaderRequired = hasIcon || hasHeaderText || hasHeaderRight;
 	const hasBody = hasRenderableContent(children);
 	const headerMain = /* @__PURE__ */ jsxs(Fragment$1, { children: [hasIcon && /* @__PURE__ */ jsx("div", {
-		className: "flex shrink-0 self-center items-center justify-center",
+		className: cn("flex shrink-0 self-center items-center justify-center", expandOnHover && HOVER_ICON_CLASS),
 		style: variantStyles?.foregroundStyle,
 		children: iconSizedForSection(icon, cn(s.icon, variantStyles?.foreground))
 	}), hasHeaderText && /* @__PURE__ */ jsxs("div", {
@@ -201,7 +286,17 @@ function SectionCard({ icon, primaryText, secondaryText, truncateSecondaryText =
 		className: cn("flex items-center gap-2", HEADER_RIGHT_CLASS, s.headerRightPad),
 		children: [actions, showCollapseIcon ? chevronButton : null]
 	}) : null;
-	const header = allowCollapse ? /* @__PURE__ */ jsxs("div", {
+	const header = expandOnHover ? /* @__PURE__ */ jsxs("div", {
+		className: headerRowClass,
+		children: [/* @__PURE__ */ jsx("button", {
+			type: "button",
+			className: cn("section-card-header", "flex min-w-0 flex-1 items-center text-left rounded-md", headerMainPad, s.gap, "cursor-default outline-none", "focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"),
+			"aria-expanded": hasBody ? hover.open : void 0,
+			"aria-controls": hasBody ? hoverBodyId : void 0,
+			onClick: hover.onHeaderClick,
+			children: headerMain
+		}), headerRight]
+	}) : allowCollapse ? /* @__PURE__ */ jsxs("div", {
 		className: headerRowClass,
 		children: [/* @__PURE__ */ jsx(CollapsibleTrigger, {
 			asChild: true,
@@ -224,7 +319,7 @@ function SectionCard({ icon, primaryText, secondaryText, truncateSecondaryText =
 		children
 	}) : null;
 	const isGradientVariant = variant === "gradient";
-	const cardSurfaceClass = variantStyles != null ? cn("rounded-lg shadow-none overflow-hidden", fillHeight && "flex min-h-0 flex-col", variantStyles.container, isGradientVariant && "border-transparent", className) : cn(cardClassName, fillHeight && "flex min-h-0 flex-col", className);
+	const cardSurfaceClass = variantStyles != null ? cn("rounded-[var(--espd-own-radius,var(--espd-radius-surface,var(--radius-lg)))] shadow-[shadow:var(--espd-own-elevation,var(--espd-elevation-surface,0_0_#0000))] overflow-hidden", fillHeight && "flex min-h-0 flex-col", variantStyles.container, isGradientVariant && "border-transparent", className) : cn(cardClassName, fillHeight && "flex min-h-0 flex-col", className);
 	const cardSurfaceStyle = variantStyles != null && isGradientVariant ? {
 		...variantStyles.containerStyle,
 		borderColor: "transparent",
@@ -239,9 +334,37 @@ function SectionCard({ icon, primaryText, secondaryText, truncateSecondaryText =
 		silverShine: variantStyles?.silverShine,
 		silverBorder: variantStyles?.silverBorder
 	}) : null;
+	if (expandOnHover) {
+		const state = hover.open ? "open" : "closed";
+		return /* @__PURE__ */ jsxs(Card, {
+			radius,
+			elevation,
+			className: cn("group/section-card", cardSurfaceClass),
+			style: cardSurfaceStyle,
+			"data-state": state,
+			...hover.rootProps,
+			children: [
+				gradientUnderlay,
+				isHeaderRequired ? header : null,
+				hasBody ? /* @__PURE__ */ jsx("div", {
+					id: hoverBodyId,
+					"data-state": state,
+					ref: hover.bodyRef,
+					className: cn("group/hover-body", HOVER_BODY_CLASS),
+					children: /* @__PURE__ */ jsx("div", {
+						className: HOVER_BODY_INNER_CLASS,
+						children: body
+					})
+				}) : null
+			]
+		});
+	}
 	if (allowCollapse) return /* @__PURE__ */ jsxs(Card, {
+		radius,
+		elevation,
 		className: cardSurfaceClass,
 		style: cardSurfaceStyle,
+		"data-state": open ? "open" : "closed",
 		children: [gradientUnderlay, /* @__PURE__ */ jsxs(Collapsible, {
 			open,
 			onOpenChange: (next) => {
@@ -252,6 +375,8 @@ function SectionCard({ icon, primaryText, secondaryText, truncateSecondaryText =
 		})]
 	});
 	return /* @__PURE__ */ jsxs(Card, {
+		radius,
+		elevation,
 		className: cardSurfaceClass,
 		style: cardSurfaceStyle,
 		children: [

package/dist/components/cards/simple-card.js

@@ -3,10 +3,13 @@ import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "../..
 import * as React$1 from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/cards/simple-card.tsx
-var SimpleCard = React$1.forwardRef(({ noShadow, noBorder, transparent, title, description, children, className }, ref) => {
+var SimpleCard = React$1.forwardRef(({ noShadow, noBorder, transparent, title, description, children, className, radius, elevation, border }, ref) => {
 	return /* @__PURE__ */ jsxs(Card, {
 		ref,
-		className: cn(noShadow && "shadow-none", noBorder && "border-0", transparent && "bg-transparent", className),
+		radius,
+		elevation,
+		border,
+		className: cn(noShadow && elevation === void 0 && "shadow-none", noBorder && border === void 0 && "border-0", transparent && "bg-transparent", className),
 		children: [(title || description) && /* @__PURE__ */ jsxs(CardHeader, {
 			className: "space-y-1",
 			children: [title && /* @__PURE__ */ jsx(CardTitle, {

package/dist/components/carousel/carousel.js

@@ -1,8 +1,11 @@
 "use client";
 import { cn } from "../../utils/cn.js";
+import { Button } from "../button/button.js";
+import { usePrefersReducedMotion } from "../../core/hooks/use-prefers-reduced-motion.js";
 import { Carousel as Carousel$1, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious } from "../../core/carousel/carousel.js";
 import * as React$1 from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { ChevronLeft, ChevronRight } from "lucide-react";
 import Autoplay from "embla-carousel-autoplay";
 //#region src/components/carousel/carousel.tsx
 var MAX_DOTS_MIN = 1;
@@ -46,32 +49,65 @@ function DotsRow({ total, maxDots, selectedIndex, orientation, onDotClick }) {
 		})
 	});
 }
-/**
-* High-level, data-driven carousel. Wraps shadcn/ui's Embla-based primitives
-* with a batteries-included API: pass `data`, pick a `navigation` style, and
-* everything else — autoplay, looping, keyboard arrow keys, dot pagination —
-* is wired up for you.
-*
-* For advanced composition (non-uniform slide widths, controlling multiple
-* carousels from one API, etc.) use `navigation="custom"` with
-* `renderNavigation`; the underlying Embla instance is not exposed.
-*/
-function Carousel({ data, orientation = "horizontal", navigation = "dots", maxDots = MAX_DOTS_DEFAULT, autoplay = false, delay = DELAY_DEFAULT, loop = true, onNext, onPrevious, renderNavigation, className, itemClassName }) {
-	const clampedMaxDots = clamp(maxDots, MAX_DOTS_MIN, MAX_DOTS_MAX, MAX_DOTS_DEFAULT);
-	const clampedDelay = clamp(delay, DELAY_MIN, DELAY_MAX, DELAY_DEFAULT);
-	const autoplayPlugin = React$1.useRef(autoplay ? Autoplay({
-		delay: clampedDelay,
-		stopOnInteraction: true
-	}) : null);
-	React$1.useEffect(() => {
-		if (!autoplayPlugin.current || !autoplay) return;
-		autoplayPlugin.current = Autoplay({
-			delay: clampedDelay,
-			stopOnInteraction: true
-		});
-	}, [autoplay, clampedDelay]);
-	const plugins = React$1.useMemo(() => autoplay && autoplayPlugin.current ? [autoplayPlugin.current] : [], [autoplay, clampedDelay]);
-	const [api, setApi] = React$1.useState();
+/** Two round icon Buttons drawn inside the slide area (`navigationPlacement="overlay"`). */
+function OverlayArrows({ state, labels, className }) {
+	const arrowClass = "size-11 rounded-full bg-card shadow-md";
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "carousel-overlay-navigation",
+		className: cn("absolute bottom-4 right-4 z-10 flex gap-2", className),
+		children: [/* @__PURE__ */ jsx(Button, {
+			variant: "outline",
+			size: "icon",
+			fullWidth: false,
+			usePrimaryColorOnHover: true,
+			className: arrowClass,
+			onClick: state.scrollPrev,
+			disabled: !state.canScrollPrev,
+			"aria-label": labels?.previous ?? "Previous slide",
+			startIcon: /* @__PURE__ */ jsx(ChevronLeft, { "aria-hidden": true })
+		}), /* @__PURE__ */ jsx(Button, {
+			variant: "outline",
+			size: "icon",
+			fullWidth: false,
+			usePrimaryColorOnHover: true,
+			className: arrowClass,
+			onClick: state.scrollNext,
+			disabled: !state.canScrollNext,
+			"aria-label": labels?.next ?? "Next slide",
+			startIcon: /* @__PURE__ */ jsx(ChevronRight, { "aria-hidden": true })
+		})]
+	});
+}
+/** The navigation that belongs at `placement`; nothing when it belongs elsewhere. */
+function CarouselNavigation({ props, state, placement, maxDots }) {
+	const { data, navigation = "dots", navigationPlacement = "below", navigationClassName, orientation = "horizontal", renderNavigation, labels } = props;
+	if ((navigationPlacement === "beside" ? "below" : navigationPlacement) !== placement) return null;
+	if (placement === "overlay") {
+		if (navigation === "custom") return renderNavigation ? /* @__PURE__ */ jsx("div", {
+			className: cn("absolute bottom-4 right-4 z-10", navigationClassName),
+			children: renderNavigation(state)
+		}) : null;
+		return data.length > 1 ? /* @__PURE__ */ jsx(OverlayArrows, {
+			state,
+			labels,
+			className: navigationClassName
+		}) : null;
+	}
+	if (navigation === "dots" && data.length > 1) return /* @__PURE__ */ jsx(DotsRow, {
+		total: data.length,
+		maxDots,
+		selectedIndex: state.selectedIndex,
+		orientation,
+		onDotClick: state.scrollTo
+	});
+	if (navigation === "custom" && renderNavigation) return /* @__PURE__ */ jsx("div", {
+		className: cn(orientation === "horizontal" ? "mt-3" : "ml-3"),
+		children: renderNavigation(state)
+	});
+	return null;
+}
+/** Mirrors Embla's selection into React state and reports the direction of each move. */
+function useCarouselState({ api, loop, onNext, onPrevious }) {
 	const [selectedIndex, setSelectedIndex] = React$1.useState(0);
 	const [scrollSnaps, setScrollSnaps] = React$1.useState([]);
 	const [canScrollPrev, setCanScrollPrev] = React$1.useState(false);
@@ -117,7 +153,7 @@ function Carousel({ data, orientation = "horizontal", navigation = "dots", maxDo
 		onPrevious
 	]);
 	const scrollTo = React$1.useCallback((index) => api?.scrollTo(index), [api]);
-	const navigationState = {
+	return {
 		canScrollPrev,
 		canScrollNext,
 		selectedIndex,
@@ -126,32 +162,84 @@ function Carousel({ data, orientation = "horizontal", navigation = "dots", maxDo
 		scrollNext: React$1.useCallback(() => api?.scrollNext(), [api]),
 		scrollTo
 	};
+}
+/**
+* High-level, data-driven carousel. Wraps shadcn/ui's Embla-based primitives
+* with a batteries-included API: pass `data`, pick a `navigation` style, and
+* everything else — autoplay, looping, keyboard arrow keys, dot pagination —
+* is wired up for you.
+*
+* Autoplay never runs while the person asks for reduced motion, and Embla's
+* autoplay already holds while the tab is hidden. With `pauseOnHover` it
+* also holds while the pointer or focus is inside.
+*
+* For advanced composition (non-uniform slide widths, controlling multiple
+* carousels from one API, etc.) use `navigation="custom"` with
+* `renderNavigation`; the underlying Embla instance is not exposed.
+*/
+function Carousel(props) {
+	const { data, orientation = "horizontal", navigation = "dots", navigationPlacement = "below", maxDots = MAX_DOTS_DEFAULT, autoplay = false, delay = DELAY_DEFAULT, loop = true, align = "center", pauseOnHover = false, labels, onNext, onPrevious, className, itemClassName } = props;
+	const clampedMaxDots = clamp(maxDots, MAX_DOTS_MIN, MAX_DOTS_MAX, MAX_DOTS_DEFAULT);
+	const clampedDelay = clamp(delay, DELAY_MIN, DELAY_MAX, DELAY_DEFAULT);
+	const reducedMotion = usePrefersReducedMotion();
+	const autoplaying = autoplay && !reducedMotion;
+	const plugins = React$1.useMemo(() => autoplaying ? [Autoplay({
+		delay: clampedDelay,
+		stopOnInteraction: !pauseOnHover,
+		stopOnMouseEnter: pauseOnHover,
+		stopOnFocusIn: true
+	})] : [], [
+		autoplaying,
+		clampedDelay,
+		pauseOnHover
+	]);
+	const [api, setApi] = React$1.useState();
+	const state = useCarouselState({
+		api,
+		loop,
+		onNext,
+		onPrevious
+	});
+	const sideArrows = navigation === "arrows" && (navigationPlacement === "below" || navigationPlacement === "beside");
+	const beside = sideArrows && navigationPlacement === "beside";
 	return /* @__PURE__ */ jsxs("div", {
 		className: cn(orientation === "horizontal" ? "flex flex-col" : "flex flex-row", className),
-		children: [
-			/* @__PURE__ */ jsxs(Carousel$1, {
-				setApi,
-				orientation,
-				opts: { loop },
-				plugins,
-				className: "min-w-0 flex-1",
-				children: [/* @__PURE__ */ jsx(CarouselContent, { children: data.map((item) => /* @__PURE__ */ jsx(CarouselItem, {
+		children: [/* @__PURE__ */ jsxs(Carousel$1, {
+			setApi,
+			orientation,
+			opts: {
+				loop,
+				align
+			},
+			plugins,
+			className: cn("min-w-0 flex-1", beside && (orientation === "horizontal" ? "px-11" : "py-11")),
+			"aria-label": labels?.carousel,
+			children: [
+				/* @__PURE__ */ jsx(CarouselContent, { children: data.map((item, index) => /* @__PURE__ */ jsx(CarouselItem, {
 					className: itemClassName,
+					"aria-label": labels?.slide?.(index + 1, data.length),
 					children: item.content
-				}, item.id)) }), navigation === "arrows" && /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(CarouselPrevious, {}), /* @__PURE__ */ jsx(CarouselNext, {})] })]
-			}),
-			navigation === "dots" && data.length > 1 && /* @__PURE__ */ jsx(DotsRow, {
-				total: data.length,
-				maxDots: clampedMaxDots,
-				selectedIndex,
-				orientation,
-				onDotClick: scrollTo
-			}),
-			navigation === "custom" && renderNavigation && /* @__PURE__ */ jsx("div", {
-				className: cn(orientation === "horizontal" ? "mt-3" : "ml-3"),
-				children: renderNavigation(navigationState)
-			})
-		]
+				}, item.id)) }),
+				sideArrows && /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(CarouselPrevious, {
+					"aria-label": labels?.previous,
+					className: cn(beside && (orientation === "horizontal" ? "left-0" : "top-0"))
+				}), /* @__PURE__ */ jsx(CarouselNext, {
+					"aria-label": labels?.next,
+					className: cn(beside && (orientation === "horizontal" ? "right-0" : "bottom-0"))
+				})] }),
+				/* @__PURE__ */ jsx(CarouselNavigation, {
+					props,
+					state,
+					placement: "overlay",
+					maxDots: clampedMaxDots
+				})
+			]
+		}), /* @__PURE__ */ jsx(CarouselNavigation, {
+			props,
+			state,
+			placement: "below",
+			maxDots: clampedMaxDots
+		})]
 	});
 }
 //#endregion

package/dist/components/carousel/index.d.ts

@@ -0,0 +1,130 @@
+import * as React from 'react';
+
+type CarouselOrientation = 'horizontal' | 'vertical';
+type CarouselNavigationStyle = 'dots' | 'arrows' | 'custom';
+/**
+ * Where the navigation sits: `'below'` (default — dots and custom controls
+ * under the slides, arrows on the sides, over the slides' edges), `'overlay'`
+ * (inside the slide area, absolutely placed by `navigationClassName`) or
+ * `'beside'` (arrows in their own gutters to the left and right of the slides,
+ * never over one — for a row of cards or chips; dots and custom controls go
+ * below, as with `'below'`).
+ */
+type CarouselNavigationPlacement = 'below' | 'overlay' | 'beside';
+/** Accessible names. Pass translated strings; English is the fallback. */
+interface CarouselLabels {
+    /** Names the carousel region ("Featured projects"). */
+    carousel?: string;
+    /** The previous-slide arrow. Default "Previous slide". */
+    previous?: string;
+    /** The next-slide arrow. Default "Next slide". */
+    next?: string;
+    /** Each slide's name, 1-based ("2 of 5: Air Mouse"). */
+    slide?: (index: number, total: number) => string;
+}
+/** Where a slide comes to rest in the viewport when it is selected. */
+type CarouselAlign = 'start' | 'center' | 'end';
+interface CarouselItem {
+    id: string | number;
+    content: React.ReactNode;
+}
+/**
+ * State passed to `renderNavigation` when `navigation === 'custom'`.
+ * Everything a caller needs to build their own controls without touching
+ * the underlying Embla API.
+ */
+interface CarouselNavigationState {
+    canScrollPrev: boolean;
+    canScrollNext: boolean;
+    /** 0-based index of the currently selected slide. */
+    selectedIndex: number;
+    /** One entry per snap point (usually one per item). */
+    scrollSnaps: number[];
+    scrollPrev: () => void;
+    scrollNext: () => void;
+    scrollTo: (index: number) => void;
+}
+interface CarouselProps {
+    /** Slides to render. `id` is used as the React key. */
+    data: CarouselItem[];
+    /** Layout axis. Vertical carousels need a bounded `className` height. */
+    orientation?: CarouselOrientation;
+    /**
+     * Built-in navigation style:
+     * - `'dots'` — pagination dots below the carousel (default).
+     * - `'arrows'` — prev/next buttons on the sides.
+     * - `'custom'` — invokes `renderNavigation` below the carousel.
+     */
+    navigation?: CarouselNavigationStyle;
+    /**
+     * Cap on dots rendered when `navigation === 'dots'`. When `data.length`
+     * exceeds this, a sliding window of dots is rendered so the row width is
+     * constant. Clamped to `[1, 10]`. Default `5`.
+     */
+    maxDots?: number;
+    /** Advance slides automatically. Default `false`. */
+    autoplay?: boolean;
+    /**
+     * Milliseconds between autoplay advances. Clamped to `[1000, 10000]`.
+     * Ignored when `autoplay` is `false`. Default `3000`.
+     */
+    delay?: number;
+    /**
+     * Where the selected slide rests: `'center'` (default) or `'start'` / `'end'`.
+     * Use `'start'` for slides of different widths (chips, tags): centring them
+     * and then keeping the row inside its bounds makes the first step barely
+     * move and the next one jump.
+     */
+    align?: CarouselAlign;
+    /**
+     * Where the navigation renders. With `'overlay'`, arrows (or the custom
+     * renderer's output) are drawn inside the slide area at the position
+     * `navigationClassName` gives them; no side arrows render. With `'beside'`,
+     * the arrows sit in gutters beside the slides, which the carousel keeps
+     * clear of them. Default `'below'`.
+     */
+    navigationPlacement?: CarouselNavigationPlacement;
+    /** Positions the overlay navigation (`'absolute bottom-4 right-4'` by default). */
+    navigationClassName?: string;
+    /**
+     * Pause autoplay while the pointer is over the carousel or focus is inside
+     * it, and resume when it leaves. Default `false` (any interaction stops
+     * autoplay for good, as before).
+     */
+    pauseOnHover?: boolean;
+    /** Accessible names for the region, the arrows and each slide. */
+    labels?: CarouselLabels;
+    /** Wrap around at the ends. Default `true`. */
+    loop?: boolean;
+    /** Called after every forward advance (user, keyboard, autoplay, or custom). */
+    onNext?: () => void;
+    /** Called after every backward advance (user, keyboard, autoplay, or custom). */
+    onPrevious?: () => void;
+    /**
+     * Custom navigation renderer. Rendered below the carousel (like dots).
+     * Only invoked when `navigation === 'custom'`.
+     */
+    renderNavigation?: (state: CarouselNavigationState) => React.ReactNode;
+    /** Applied to the outer wrapper. */
+    className?: string;
+    /** Applied to each slide's outer element. */
+    itemClassName?: string;
+}
+
+/**
+ * High-level, data-driven carousel. Wraps shadcn/ui's Embla-based primitives
+ * with a batteries-included API: pass `data`, pick a `navigation` style, and
+ * everything else — autoplay, looping, keyboard arrow keys, dot pagination —
+ * is wired up for you.
+ *
+ * Autoplay never runs while the person asks for reduced motion, and Embla's
+ * autoplay already holds while the tab is hidden. With `pauseOnHover` it
+ * also holds while the pointer or focus is inside.
+ *
+ * For advanced composition (non-uniform slide widths, controlling multiple
+ * carousels from one API, etc.) use `navigation="custom"` with
+ * `renderNavigation`; the underlying Embla instance is not exposed.
+ */
+declare function Carousel(props: CarouselProps): React.JSX.Element;
+
+export { Carousel, type CarouselAlign, type CarouselItem, type CarouselLabels, type CarouselNavigationPlacement, type CarouselNavigationState, type CarouselNavigationStyle, type CarouselOrientation, type CarouselProps };

package/dist/components/carousel/index.js

@@ -0,0 +1,2 @@
+import { Carousel } from "./carousel.js";
+export { Carousel };