@makolabs/ripple 2.5.9 → 3.0.1

package/dist/elements/pagination/Pagination.svelte

@@ -4,7 +4,35 @@
 	import type { ClassValue } from 'tailwind-variants';
 
 	/**
-	 * Pagination component props
+	 * Props for `<Pagination>` — page navigation controls. Used standalone
+	 * for client-driven lists, or automatically inside `<Table>` when
+	 * `pagination` is on.
+	 *
+	 * `currentPage` is a regular (non-bindable) prop — pass it in and
+	 * update via `onpagechange`, or set `internalState={true}` and omit
+	 * `currentPage` to let the component track pages itself. Most apps
+	 * prefer external state so the URL or a store can drive it.
+	 *
+	 * @example
+	 * ```svelte
+	 * <Pagination
+	 *   currentPage={page}
+	 *   totalItems={42}
+	 *   pageSize={10}
+	 *   onpagechange={(p) => goto(`?page=${p}`)}
+	 * />
+	 * ```
+	 *
+	 * @example
+	 * ```svelte
+	 * <!-- Compact "Page 3 of 7" mode for tight footers -->
+	 * <Pagination
+	 *   {totalItems}
+	 *   pageSize={20}
+	 *   template="compact"
+	 *   showFirstLast={false}
+	 * />
+	 * ```
 	 */
 	export interface PaginationProps {
 		/** Current page number (1-indexed). If not provided, component manages state internally. */
@@ -14,13 +42,13 @@
 		/** Number of items per page */
 		pageSize?: number;
 		/** Callback when page changes */
-		onPageChange?: (page: number) => void;
+		onpagechange?: (page: number) => void;
 		/** Callback when page size changes */
-		onPageSizeChange?: (pageSize: number) => void;
+		onpagesizechange?: (pageSize: number) => void;
 		/** Callback when first page is clicked */
-		onFirstPage?: () => void;
+		onfirstpage?: () => void;
 		/** Callback when last page is clicked */
-		onLastPage?: () => void;
+		onlastpage?: () => void;
 		/** Whether pagination controls are disabled */
 		disabled?: boolean;
 		/** Show page size selector */
@@ -62,10 +90,10 @@
 		currentPage: externalCurrentPage,
 		totalItems,
 		pageSize: externalPageSize,
-		onPageChange,
-		onPageSizeChange,
-		onFirstPage,
-		onLastPage,
+		onpagechange,
+		onpagesizechange,
+		onfirstpage,
+		onlastpage,
 		disabled = false,
 		showPageSize = false,
 		pageSizeOptions = [5, 10, 25, 50, 100],
@@ -140,7 +168,7 @@
 			if (internalState && externalCurrentPage === undefined) {
 				internalCurrentPage = page;
 			}
-			onPageChange?.(page);
+			onpagechange?.(page);
 		}
 	}
 
@@ -150,8 +178,8 @@
 			if (internalState && externalCurrentPage === undefined) {
 				internalCurrentPage = targetPage;
 			}
-			onPageChange?.(targetPage);
-			onFirstPage?.();
+			onpagechange?.(targetPage);
+			onfirstpage?.();
 		}
 	}
 
@@ -161,8 +189,8 @@
 			if (internalState && externalCurrentPage === undefined) {
 				internalCurrentPage = targetPage;
 			}
-			onPageChange?.(targetPage);
-			onLastPage?.();
+			onpagechange?.(targetPage);
+			onlastpage?.();
 		}
 	}
 
@@ -172,7 +200,7 @@
 			if (internalState && externalCurrentPage === undefined) {
 				internalCurrentPage = targetPage;
 			}
-			onPageChange?.(targetPage);
+			onpagechange?.(targetPage);
 		}
 	}
 
@@ -182,7 +210,7 @@
 			if (internalState && externalCurrentPage === undefined) {
 				internalCurrentPage = targetPage;
 			}
-			onPageChange?.(targetPage);
+			onpagechange?.(targetPage);
 		}
 	}
 
@@ -203,14 +231,14 @@
 			if (internalState && externalCurrentPage === undefined) {
 				internalCurrentPage = adjustedPage;
 			}
-			onPageChange?.(adjustedPage);
+			onpagechange?.(adjustedPage);
 		}
 
 		// Update page size
 		if (internalState && externalPageSize === undefined) {
 			internalPageSize = newPageSize;
 		}
-		onPageSizeChange?.(newPageSize);
+		onpagesizechange?.(newPageSize);
 	}
 
 	/**
@@ -246,8 +274,10 @@
 	const shouldShowPagination = $derived(!hideWhenNoItems || validTotalItems > 0);
 	const shouldShowControls = $derived(!hideWhenSinglePage || totalPages > 1);
 
-	// Default classes using ripple-ui design system
-	const defaultWrapperClass = 'flex items-center justify-between p-4';
+	// Default classes using ripple-ui design system.
+	// `flex-wrap` + `gap-y-3` stacks the info row and button row on narrow
+	// viewports instead of squeezing them onto one line.
+	const defaultWrapperClass = 'flex flex-wrap items-center justify-between gap-y-3 p-4';
 	const defaultInfoClass = 'text-default-500 text-sm';
 	const defaultButtonClass =
 		'relative inline-flex items-center rounded-md px-2 py-1 text-sm font-medium';
@@ -293,7 +323,9 @@
 		{/if}
 
 		{#if shouldShowControls && showNavigation}
-			<div class="flex items-center gap-1">
+			<!-- `flex-wrap` lets page-number buttons wrap to a second row
+			     rather than overflowing the container on narrow viewports. -->
+			<div class="flex flex-wrap items-center gap-1">
 				{#if showFirstLast}
 					<button
 						onclick={firstPage}

package/dist/elements/pagination/Pagination.svelte.d.ts

@@ -1,6 +1,34 @@
 import type { ClassValue } from 'tailwind-variants';
 /**
- * Pagination component props
+ * Props for `<Pagination>` — page navigation controls. Used standalone
+ * for client-driven lists, or automatically inside `<Table>` when
+ * `pagination` is on.
+ *
+ * `currentPage` is a regular (non-bindable) prop — pass it in and
+ * update via `onpagechange`, or set `internalState={true}` and omit
+ * `currentPage` to let the component track pages itself. Most apps
+ * prefer external state so the URL or a store can drive it.
+ *
+ * @example
+ * ```svelte
+ * <Pagination
+ *   currentPage={page}
+ *   totalItems={42}
+ *   pageSize={10}
+ *   onpagechange={(p) => goto(`?page=${p}`)}
+ * />
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- Compact "Page 3 of 7" mode for tight footers -->
+ * <Pagination
+ *   {totalItems}
+ *   pageSize={20}
+ *   template="compact"
+ *   showFirstLast={false}
+ * />
+ * ```
  */
 export interface PaginationProps {
     /** Current page number (1-indexed). If not provided, component manages state internally. */
@@ -10,13 +38,13 @@ export interface PaginationProps {
     /** Number of items per page */
     pageSize?: number;
     /** Callback when page changes */
-    onPageChange?: (page: number) => void;
+    onpagechange?: (page: number) => void;
     /** Callback when page size changes */
-    onPageSizeChange?: (pageSize: number) => void;
+    onpagesizechange?: (pageSize: number) => void;
     /** Callback when first page is clicked */
-    onFirstPage?: () => void;
+    onfirstpage?: () => void;
     /** Callback when last page is clicked */
-    onLastPage?: () => void;
+    onlastpage?: () => void;
     /** Whether pagination controls are disabled */
     disabled?: boolean;
     /** Show page size selector */

package/dist/elements/popover/Popover.svelte

@@ -0,0 +1,254 @@
+<script lang="ts">
+	import { cn } from '../../helper/cls.js';
+	import { buildTestId } from '../../helper/testid.js';
+	import type { PopoverProps, PopoverPlacement } from './popover-types.js';
+
+	let {
+		open = $bindable(false),
+		placement = 'bottom',
+		trigger = 'click',
+		arrow = false,
+		delay = 100,
+		hideDelay = 0,
+		closeOnEscape = true,
+		closeOnOutsideClick = true,
+		disabled = false,
+		class: className = '',
+		panelClass = '',
+		children,
+		content,
+		testId
+	}: PopoverProps = $props();
+
+	let wrapper = $state<HTMLSpanElement | undefined>();
+	let panelEl = $state<HTMLDivElement | undefined>();
+	let showTimer: ReturnType<typeof setTimeout> | undefined;
+	let hideTimer: ReturnType<typeof setTimeout> | undefined;
+
+	// Panel position in viewport coordinates — updated on open and on
+	// scroll/resize so the panel tracks the trigger. Kept reactive so the
+	// style attribute re-renders when these change.
+	let panelTop = $state(0);
+	let panelLeft = $state(0);
+	let panelTransform = $state('');
+
+	function show() {
+		if (disabled) return;
+		clearTimeout(showTimer);
+		clearTimeout(hideTimer);
+		if (delay > 0 && trigger === 'hover') {
+			showTimer = setTimeout(() => (open = true), delay);
+		} else {
+			open = true;
+		}
+	}
+
+	function hide() {
+		clearTimeout(showTimer);
+		clearTimeout(hideTimer);
+		if (hideDelay > 0 && trigger === 'hover') {
+			hideTimer = setTimeout(() => (open = false), hideDelay);
+		} else {
+			open = false;
+		}
+	}
+
+	function toggle() {
+		if (disabled) return;
+		if (open) hide();
+		else show();
+	}
+
+	function close() {
+		clearTimeout(showTimer);
+		clearTimeout(hideTimer);
+		open = false;
+	}
+
+	// Clean up any in-flight timers on unmount.
+	$effect(() => {
+		return () => {
+			clearTimeout(showTimer);
+			clearTimeout(hideTimer);
+		};
+	});
+
+	function handleWindowKey(e: KeyboardEvent) {
+		if (closeOnEscape && open && e.key === 'Escape') close();
+	}
+
+	function handleWindowClick(e: MouseEvent) {
+		if (!closeOnOutsideClick || !open) return;
+		const target = e.target as Node;
+		// The panel lives outside the trigger wrapper in the DOM, so check both.
+		if (wrapper?.contains(target) || panelEl?.contains(target)) return;
+		close();
+	}
+
+	/**
+	 * Compute panel position from the trigger's bounding rect. Uses
+	 * `position: fixed` + a very high z-index so the panel sits above
+	 * sibling content (Storybook sidebars, sticky headers, etc.) instead
+	 * of being clipped / layered under it.
+	 *
+	 * The computed position is then clamped to the viewport with an 8px
+	 * gutter — this keeps panels on-screen near viewport edges on narrow
+	 * devices. We measure the panel's own rect so the clamp accounts for
+	 * the `translate(-50%, 0)` etc. transforms that re-anchor the panel.
+	 */
+	function updatePosition() {
+		if (!wrapper || !panelEl) return;
+		const r = wrapper.getBoundingClientRect();
+		const GAP = 8;
+		const VIEWPORT_GUTTER = 8;
+		switch (placement as PopoverPlacement) {
+			case 'top':
+				panelTop = r.top - GAP;
+				panelLeft = r.left + r.width / 2;
+				panelTransform = 'translate(-50%, -100%)';
+				break;
+			case 'bottom':
+				panelTop = r.bottom + GAP;
+				panelLeft = r.left + r.width / 2;
+				panelTransform = 'translate(-50%, 0)';
+				break;
+			case 'left':
+				panelTop = r.top + r.height / 2;
+				panelLeft = r.left - GAP;
+				panelTransform = 'translate(-100%, -50%)';
+				break;
+			case 'right':
+				panelTop = r.top + r.height / 2;
+				panelLeft = r.right + GAP;
+				panelTransform = 'translate(0, -50%)';
+				break;
+		}
+
+		// Clamp to viewport. We re-measure the panel after applying the
+		// transform (next frame) because its true on-screen rect depends
+		// on `panelTransform`. Adjust `panelLeft`/`panelTop` so the rect
+		// ends up inside [VIEWPORT_GUTTER, viewport - VIEWPORT_GUTTER].
+		requestAnimationFrame(() => {
+			if (!panelEl) return;
+			const pr = panelEl.getBoundingClientRect();
+			const vw = window.innerWidth;
+			const vh = window.innerHeight;
+			let dx = 0;
+			let dy = 0;
+			if (pr.left < VIEWPORT_GUTTER) dx = VIEWPORT_GUTTER - pr.left;
+			else if (pr.right > vw - VIEWPORT_GUTTER) dx = vw - VIEWPORT_GUTTER - pr.right;
+			if (pr.top < VIEWPORT_GUTTER) dy = VIEWPORT_GUTTER - pr.top;
+			else if (pr.bottom > vh - VIEWPORT_GUTTER) dy = vh - VIEWPORT_GUTTER - pr.bottom;
+			if (dx !== 0) panelLeft += dx;
+			if (dy !== 0) panelTop += dy;
+		});
+	}
+
+	/**
+	 * Re-measure on every open, and while open, on scroll/resize so the
+	 * panel follows its trigger when the page scrolls.
+	 */
+	$effect(() => {
+		if (!open) return;
+		// Initial placement (defer one frame so panelEl has mounted).
+		requestAnimationFrame(updatePosition);
+
+		const handler = () => updatePosition();
+		window.addEventListener('scroll', handler, true);
+		window.addEventListener('resize', handler);
+		return () => {
+			window.removeEventListener('scroll', handler, true);
+			window.removeEventListener('resize', handler);
+		};
+	});
+
+	/**
+	 * Portal the panel element to `document.body` once it mounts, so any
+	 * ancestor with `transform` / `filter` / `will-change` (Storybook's
+	 * docs container, a scaled preview, a card with transform-based
+	 * hover, etc.) doesn't re-parent our `position: fixed` panel and
+	 * clip / mis-position it. On unmount, we simply remove the node —
+	 * Svelte's own `{#if}` teardown will still work because it tracks
+	 * the element by reference, not by DOM path.
+	 */
+	$effect(() => {
+		if (!panelEl) return;
+		const el = panelEl;
+		document.body.appendChild(el);
+		return () => {
+			if (el.parentNode === document.body) {
+				document.body.removeChild(el);
+			}
+		};
+	});
+
+	const arrowClass = $derived(
+		{
+			top: 'top-full left-1/2 -translate-x-1/2 border-t-white border-l-transparent border-r-transparent border-b-transparent',
+			bottom:
+				'bottom-full left-1/2 -translate-x-1/2 border-b-white border-l-transparent border-r-transparent border-t-transparent',
+			left: 'left-full top-1/2 -translate-y-1/2 border-l-white border-t-transparent border-b-transparent border-r-transparent',
+			right:
+				'right-full top-1/2 -translate-y-1/2 border-r-white border-t-transparent border-b-transparent border-l-transparent'
+		}[placement]
+	);
+</script>
+
+<svelte:window onkeydown={handleWindowKey} onmousedown={handleWindowClick} />
+
+<span
+	bind:this={wrapper}
+	class={cn('relative inline-flex', className)}
+	data-testid={buildTestId('popover', undefined, testId)}
+>
+	{#if trigger === 'click'}
+		<!--
+			Click-mode: forward clicks to toggle. Do NOT add role/tabindex here
+			— consumers pass an interactive child (Button, <a>, etc.) that
+			handles its own focus/keyboard; adding them here would nest
+			interactive elements (invalid HTML + a11y issue). Keyboard support
+			comes via Enter/Space on the inner button dispatching a click,
+			which bubbles to this handler.
+		-->
+		<!-- svelte-ignore a11y_click_events_have_key_events -->
+		<!-- svelte-ignore a11y_no_static_element_interactions -->
+		<span class="inline-flex" aria-haspopup="dialog" aria-expanded={open} onclick={toggle}>
+			{@render children()}
+		</span>
+	{:else if trigger === 'hover'}
+		<span
+			class="inline-flex"
+			role="group"
+			onmouseenter={show}
+			onmouseleave={hide}
+			onfocusin={show}
+			onfocusout={hide}
+		>
+			{@render children()}
+		</span>
+	{:else}
+		<!-- manual — consumer drives `open` -->
+		<span class="inline-flex">{@render children()}</span>
+	{/if}
+</span>
+
+{#if open}
+	<div
+		bind:this={panelEl}
+		role="dialog"
+		tabindex="-1"
+		class={cn(
+			'border-default-200 fixed z-[9999] min-w-[10rem] rounded-lg border bg-white p-2 shadow-lg',
+			panelClass
+		)}
+		style="top: {panelTop}px; left: {panelLeft}px; transform: {panelTransform};"
+		onmouseenter={trigger === 'hover' && hideDelay > 0 ? () => clearTimeout(hideTimer) : undefined}
+		onmouseleave={trigger === 'hover' ? hide : undefined}
+		data-testid={buildTestId('popover', 'panel', testId)}
+	>
+		{#if arrow}
+			<span class={cn('absolute size-0 border-[5px]', arrowClass)} aria-hidden="true"></span>
+		{/if}
+		{@render content({ close })}
+	</div>
+{/if}

package/dist/elements/popover/Popover.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { PopoverProps } from './popover-types.js';
+declare const Popover: import("svelte").Component<PopoverProps, {}, "open">;
+type Popover = ReturnType<typeof Popover>;
+export default Popover;

package/dist/elements/popover/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Popover } from './Popover.svelte';
+export type { PopoverProps, PopoverPlacement, PopoverTrigger } from './popover-types.js';

package/dist/elements/popover/index.js

@@ -0,0 +1 @@
+export { default as Popover } from './Popover.svelte';

package/dist/elements/popover/popover-types.d.ts

@@ -0,0 +1,60 @@
+import type { ClassValue } from 'tailwind-variants';
+import type { Snippet } from 'svelte';
+/**
+ * Where the Popover panel appears relative to its trigger. Popover always
+ * centers along the cross-axis of the placement.
+ */
+export type PopoverPlacement = 'top' | 'bottom' | 'left' | 'right';
+/**
+ * How the Popover opens:
+ * - `'click'` — clicking the trigger toggles open/close (default, most common)
+ * - `'hover'` — opens on mouseenter/focusin. Use `hideDelay` to let users
+ *   cross from trigger into panel without it closing.
+ * - `'manual'` — you drive `open` yourself via `bind:open`. Trigger
+ *   children are just visual (no event handlers attached by Popover).
+ */
+export type PopoverTrigger = 'click' | 'hover' | 'manual';
+export type PopoverProps = {
+    /** Bindable open state. Defaults to false. */
+    open?: boolean;
+    /** Placement relative to the trigger. @default 'bottom' */
+    placement?: PopoverPlacement;
+    /** How the trigger opens the panel. @default 'click' */
+    trigger?: PopoverTrigger;
+    /** Show an arrow pointing at the trigger. @default false */
+    arrow?: boolean;
+    /**
+     * When `trigger='hover'`, delay before showing (ms). Ignored for
+     * click/manual. @default 100
+     */
+    delay?: number;
+    /**
+     * When `trigger='hover'`, delay before hiding after mouseleave (ms).
+     * Non-zero lets users move into the panel. Ignored for click/manual.
+     * @default 0
+     */
+    hideDelay?: number;
+    /** Close when the Escape key is pressed while panel is open. @default true */
+    closeOnEscape?: boolean;
+    /** Close when user clicks outside the panel and trigger. @default true */
+    closeOnOutsideClick?: boolean;
+    /** Disable the trigger and prevent opening. */
+    disabled?: boolean;
+    /** Wrapper class (around trigger). */
+    class?: ClassValue;
+    /** Panel class (the floating element). */
+    panelClass?: ClassValue;
+    /**
+     * The trigger element. Rendered inline — the Popover wraps it in an
+     * inline-flex container so it sits where you put the <Popover>.
+     */
+    children: Snippet;
+    /**
+     * The panel content. Receives `close()` so you can wire buttons inside
+     * the panel that dismiss it.
+     */
+    content: Snippet<[{
+        close: () => void;
+    }]>;
+    testId?: string;
+};

package/dist/elements/popover/popover-types.js

@@ -0,0 +1 @@
+export {};

package/dist/elements/progress/Progress.svelte

@@ -1,12 +1,14 @@
 <script lang="ts">
 	import { cn } from '../../helper/cls.js';
 	import { Color, Size } from '../../variants.js';
+	import { Tween } from 'svelte/motion';
+	import { quintOut } from 'svelte/easing';
 	import type { ProgressProps, VariantColors } from '../../index.js';
 
 	let {
 		value,
 		max = 100,
-		size = Size.BASE,
+		size = Size.MD,
 		color = Color.PRIMARY,
 		showLabel = true,
 		labelPosition = 'right',
@@ -38,12 +40,12 @@
 
 	function getSizeTextClass(size: string): string {
 		if (size === Size.XS || size === Size.SM) return 'text-xs';
-		if (size === Size.BASE) return 'text-sm';
+		if (size === Size.MD) return 'text-sm';
 		return 'text-base'; // For Size.LG, Size.XL
 	}
 
 	// Derived values
-	const percentage = $derived(segments ? 100 : calculatePercentage(value, max));
+	const percentage = $derived(segments ? 100 : calculatePercentage(value ?? 0, max));
 	const segmentPercentages = $derived(
 		segments?.map((segment) => ({
 			...segment,
@@ -51,6 +53,29 @@
 		})) || []
 	);
 
+	// Animate from 0 → target on mount (and on subsequent value changes)
+	// using a tween with quintOut easing for a smooth, non-jittery feel.
+	const tween = new Tween(0, { duration: 800, easing: quintOut });
+
+	// Derive tween instances from the current segment count so that
+	// dynamically-added/removed segments get their own tweens instead of
+	// being stuck at 0. The $derived runs whenever `segments` identity
+	// changes — consumers should pass a stable array unless they truly
+	// want a rebuild.
+	const segmentTweens = $derived(
+		(segments ?? []).map(() => new Tween(0, { duration: 800, easing: quintOut }))
+	);
+
+	$effect(() => {
+		tween.target = percentage;
+	});
+
+	$effect(() => {
+		segmentPercentages.forEach((s, i) => {
+			if (segmentTweens[i]) segmentTweens[i].target = s.percentage;
+		});
+	});
+
 	// Class compositions
 	const containerClass = $derived(
 		cn(
@@ -68,7 +93,7 @@
 		cn('w-full rounded-full bg-default-200', {
 			'h-1.5': size === Size.XS,
 			'h-2': size === Size.SM,
-			'h-2.5': size === Size.BASE,
+			'h-2.5': size === Size.MD,
 			'h-3': size === Size.LG,
 			'h-4': size === Size.XL,
 			'order-2': !segments && labelPosition === 'top',
@@ -78,7 +103,7 @@
 	);
 
 	const fillClass = $derived(
-		cn('h-full rounded-full transition-all', segments ? '' : getColorClass(color), barClass)
+		cn('h-full rounded-full', segments ? '' : getColorClass(color), barClass)
 	);
 
 	const labelTextClass = $derived(
@@ -108,13 +133,13 @@
 				{#if segment.percentage > 0}
 					<div
 						class={cn(getColorClass(segment.color), barClass)}
-						style="width: {segment.percentage}%"
+						style="width: {segmentTweens[index]?.current ?? 0}%"
 						title={segment.label || `${segment.value} (${segment.percentage}%)`}
 					></div>
 				{/if}
 			{/each}
 		{:else}
-			<div class={fillClass} style="width: {percentage}%"></div>
+			<div class={fillClass} style="width: {tween.current}%"></div>
 		{/if}
 	</div>