@makolabs/ripple 2.5.9 → 3.0.1

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

@@ -1,22 +1,69 @@
 import type { ClassValue } from 'tailwind-variants';
 import type { VariantColors, VariantSizes } from '../../index.js';
+/** One segment of a multi-segment progress bar (`ProgressProps.segments`). */
 export type ProgressSegment = {
+    /** Segment size. Treated as a share of `max` (so segment values should sum to ≤ `max`). */
     value: number;
+    /** Segment fill color. */
     color: VariantColors;
+    /** Optional label rendered inside the legend when `showLabels` is set. */
     label?: string;
 };
+/**
+ * Props for `<Progress>` — a horizontal progress bar. Supports two modes:
+ * 1. **Single value** — pass `value` (and optionally `max`). Renders one filled bar.
+ * 2. **Segmented** — pass `segments: ProgressSegment[]`. Renders a stacked bar with
+ *    per-segment colors and an optional legend below.
+ *
+ * For KPI-style displays where the progress bar is part of a card,
+ * `<MetricCard>` accepts the same `percent`/`segments` props directly.
+ *
+ * @example
+ * ```svelte
+ * <!-- Simple -->
+ * <Progress value={68} showLabel />
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- Multi-segment with legend -->
+ * <Progress
+ *   max={100}
+ *   segments={[
+ *     { value: 50, color: 'success', label: 'Healthy' },
+ *     { value: 30, color: 'warning', label: 'Warning' },
+ *     { value: 20, color: 'danger', label: 'Critical' }
+ *   ]}
+ *   showLabels
+ *   showValues
+ * />
+ * ```
+ */
 export type ProgressProps = {
-    value: number;
+    /** Current value (single-mode). Ignored when `segments` is provided. @default 0 */
+    value?: number;
+    /** Max scale value. @default 100 */
     max?: number;
     size?: VariantSizes;
+    /** Fill color for single-mode. @default 'primary' */
     color?: VariantColors;
+    /** Show "value / max" label next to the bar (single-mode). @default false */
     showLabel?: boolean;
+    /** Where to render the label. @default 'top' */
     labelPosition?: 'top' | 'bottom' | 'right';
+    /**
+     * Segmented bars — when provided, takes precedence over `value`.
+     * Each segment renders in its own color, and an optional legend
+     * appears below when `showLabels` or `showValues` is set.
+     */
     segments?: ProgressSegment[];
+    /** Show the legend under segmented bars. @default false */
     showLabels?: boolean;
+    /** Show numeric values alongside labels in the legend. @default false */
     showValues?: boolean;
     class?: ClassValue;
     labelClass?: ClassValue;
+    /** Classes on the inner bar element(s). */
     barClass?: ClassValue;
     testId?: string;
 };

package/dist/elements/skeleton/Skeleton.svelte

@@ -0,0 +1,56 @@
+<script lang="ts">
+	import { cn } from '../../helper/cls.js';
+	import { buildTestId } from '../../helper/testid.js';
+	import type { SkeletonProps } from './skeleton-types.js';
+
+	let {
+		class: className = '',
+		variant = 'pulse',
+		rounded = 'rounded-md',
+		ariaLabel = 'Loading',
+		style,
+		testId
+	}: SkeletonProps = $props();
+</script>
+
+<div
+	class={cn(
+		'bg-default-200',
+		rounded,
+		variant === 'pulse' && 'animate-pulse',
+		variant === 'shimmer' && 'ripple-skeleton-shimmer overflow-hidden',
+		className
+	)}
+	{style}
+	role="status"
+	aria-label={ariaLabel}
+	aria-busy="true"
+	data-testid={buildTestId('skeleton', undefined, testId)}
+></div>
+
+<style>
+	/* Shimmer variant: gradient sweep using a CSS animation. Kept here (not Tailwind)
+	   because moving gradients aren't expressible with Tailwind utilities. */
+	.ripple-skeleton-shimmer {
+		position: relative;
+		isolation: isolate;
+	}
+	.ripple-skeleton-shimmer::after {
+		content: '';
+		position: absolute;
+		inset: 0;
+		background: linear-gradient(90deg, transparent, rgba(255, 255, 255, 0.55), transparent);
+		transform: translateX(-100%);
+		animation: ripple-skeleton-shimmer 1.6s infinite;
+	}
+	@keyframes ripple-skeleton-shimmer {
+		100% {
+			transform: translateX(100%);
+		}
+	}
+	@media (prefers-reduced-motion: reduce) {
+		.ripple-skeleton-shimmer::after {
+			animation: none;
+		}
+	}
+</style>

package/dist/elements/skeleton/Skeleton.svelte.d.ts

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

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

@@ -0,0 +1,2 @@
+export { default as Skeleton } from './Skeleton.svelte';
+export type { SkeletonProps, SkeletonVariant } from './skeleton-types.js';

package/dist/elements/skeleton/index.js

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

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

@@ -0,0 +1,50 @@
+import type { ClassValue } from 'tailwind-variants';
+/**
+ * Animation style for `<Skeleton>`.
+ * - `'pulse'` — subtle opacity pulse (Tailwind's `animate-pulse`)
+ * - `'shimmer'` — gradient slides across the block
+ */
+export type SkeletonVariant = 'pulse' | 'shimmer';
+/**
+ * Props for `<Skeleton>` — a placeholder block that mimics the shape of
+ * content while it loads. Use to preserve layout and avoid layout shift
+ * when the real content arrives.
+ *
+ * For wholesale "is my component loading?" UX, most components expose
+ * a `loading` prop that renders skeletons automatically (`<Card loading>`,
+ * `<Table loading>`, etc.). Use `<Skeleton>` directly when composing
+ * custom placeholder layouts.
+ *
+ * @example
+ * ```svelte
+ * <!-- Three-line text placeholder -->
+ * <div class="space-y-2">
+ *   <Skeleton class="h-4 w-48" />
+ *   <Skeleton class="h-4 w-64" />
+ *   <Skeleton class="h-4 w-40" />
+ * </div>
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- Avatar placeholder -->
+ * <Skeleton class="size-10" rounded="rounded-full" variant="shimmer" />
+ * ```
+ */
+export interface SkeletonProps {
+    /** Additional Tailwind classes — typically `w-*` and `h-*` to size the block. */
+    class?: ClassValue;
+    /**
+     * Animation style.
+     * - `pulse` (default): subtle opacity pulse via Tailwind's animate-pulse
+     * - `shimmer`: gradient slides across the block
+     */
+    variant?: SkeletonVariant;
+    /** Override the rounded class. Pass `''` to suppress default rounding. @default 'rounded-md' */
+    rounded?: string;
+    /** Optional accessible label announced by screen readers. @default 'Loading' */
+    ariaLabel?: string;
+    /** Inline style — useful for dynamic widths/heights that Tailwind can't express. */
+    style?: string;
+    testId?: string;
+}

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

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

package/dist/elements/spinner/Spinner.svelte

@@ -6,7 +6,7 @@
 	import type { SpinnerProps } from '../../index.js';
 
 	let {
-		size = Size.BASE,
+		size = Size.MD,
 		color = Color.DEFAULT,
 		label,
 		class: className = '',

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

@@ -1,8 +1,28 @@
 import type { ClassValue } from 'tailwind-variants';
 import type { VariantColors, VariantSizes } from '../../index.js';
+/**
+ * Props for `<Spinner>` — an animated loading indicator. Use for
+ * short-lived waits ("loading the next page of results"). For longer
+ * waits where layout shape matters, prefer `<Skeleton>`.
+ *
+ * @example
+ * ```svelte
+ * <Spinner />
+ *
+ * <!-- With accessible label -->
+ * <Spinner size="lg" color="primary" label="Loading users" />
+ * ```
+ */
 export type SpinnerProps = {
+    /** @default 'md' */
     size?: VariantSizes;
+    /** @default 'primary' */
     color?: VariantColors;
+    /**
+     * Accessible text announced to screen readers. Visible labels are
+     * rendered next to the spinner; omit for a bare spinner (an
+     * `aria-label='Loading'` is still applied).
+     */
     label?: string;
     class?: ClassValue;
     testId?: string;

package/dist/elements/spinner/spinner.d.ts

@@ -8,7 +8,7 @@ export declare const spinner: import("tailwind-variants").TVReturnType<{
             svg: string;
             label: string;
         };
-        base: {
+        md: {
             svg: string;
             label: string;
         };
@@ -62,7 +62,7 @@ export declare const spinner: import("tailwind-variants").TVReturnType<{
             svg: string;
             label: string;
         };
-        base: {
+        md: {
             svg: string;
             label: string;
         };
@@ -116,7 +116,7 @@ export declare const spinner: import("tailwind-variants").TVReturnType<{
             svg: string;
             label: string;
         };
-        base: {
+        md: {
             svg: string;
             label: string;
         };

package/dist/elements/spinner/spinner.js

@@ -10,7 +10,7 @@ export const spinner = tv({
         size: {
             [Size.XS]: { svg: 'h-3 w-3', label: 'text-xs' },
             [Size.SM]: { svg: 'h-4 w-4', label: 'text-xs' },
-            [Size.BASE]: { svg: 'h-5 w-5', label: 'text-sm' },
+            [Size.MD]: { svg: 'h-5 w-5', label: 'text-sm' },
             [Size.LG]: { svg: 'h-6 w-6', label: 'text-base' },
             [Size.XL]: { svg: 'h-8 w-8', label: 'text-lg' },
             [Size.XXL]: { svg: 'h-12 w-12', label: 'text-xl' }
@@ -26,7 +26,7 @@ export const spinner = tv({
         }
     },
     defaultVariants: {
-        size: Size.BASE,
+        size: Size.MD,
         color: Color.DEFAULT
     }
 });

package/dist/elements/tooltip/Tooltip.svelte

@@ -1,12 +1,19 @@
 <script lang="ts">
 	import { cn } from '../../helper/cls.js';
 	import { buildTestId } from '../../helper/testid.js';
-	import type { TooltipProps } from '../../index.js';
+	import { scale } from 'svelte/transition';
+	import { quintOut } from 'svelte/easing';
+	import type { TooltipProps, TooltipSize, TooltipVariant } from '../../index.js';
 
 	let {
 		content,
+		body,
 		placement = 'top',
+		size = 'sm',
+		variant = 'dark',
+		arrow = true,
 		delay = 100,
+		hideDelay = 0,
 		disabled = false,
 		class: className = '',
 		tooltipClass = '',
@@ -16,10 +23,12 @@
 
 	let visible = $state(false);
 	let showTimer: ReturnType<typeof setTimeout> | undefined;
+	let hideTimer: ReturnType<typeof setTimeout> | undefined;
 
 	function show() {
 		if (disabled) return;
 		clearTimeout(showTimer);
+		clearTimeout(hideTimer);
 		if (delay > 0) {
 			showTimer = setTimeout(() => {
 				visible = true;
@@ -31,7 +40,19 @@
 
 	function hide() {
 		clearTimeout(showTimer);
-		visible = false;
+		clearTimeout(hideTimer);
+		if (hideDelay > 0) {
+			hideTimer = setTimeout(() => {
+				visible = false;
+			}, hideDelay);
+		} else {
+			visible = false;
+		}
+	}
+
+	/** Keep tooltip open while the user mouses over its body (only meaningful with hideDelay > 0). */
+	function cancelHide() {
+		if (hideDelay > 0) clearTimeout(hideTimer);
 	}
 
 	const placementClass = $derived(
@@ -43,16 +64,78 @@
 		}[placement]
 	);
 
+	const sizeClasses: Record<TooltipSize, string> = {
+		sm: 'px-2 py-1 text-xs rounded',
+		md: 'px-3 py-1.5 text-sm rounded-md',
+		lg: 'px-4 py-2 text-base rounded-lg'
+	};
+
+	type VariantStyles = {
+		bg: string;
+		text: string;
+		arrow: { t: string; b: string; l: string; r: string };
+	};
+
+	const variantStyles: Record<TooltipVariant, VariantStyles> = {
+		dark: {
+			bg: 'bg-default-800',
+			text: 'text-white',
+			arrow: {
+				t: 'border-t-default-800',
+				b: 'border-b-default-800',
+				l: 'border-l-default-800',
+				r: 'border-r-default-800'
+			}
+		},
+		light: {
+			bg: 'bg-white border border-default-200',
+			text: 'text-default-900',
+			arrow: { t: 'border-t-white', b: 'border-b-white', l: 'border-l-white', r: 'border-r-white' }
+		},
+		primary: {
+			bg: 'bg-primary-600',
+			text: 'text-white',
+			arrow: {
+				t: 'border-t-primary-600',
+				b: 'border-b-primary-600',
+				l: 'border-l-primary-600',
+				r: 'border-r-primary-600'
+			}
+		},
+		danger: {
+			bg: 'bg-danger-600',
+			text: 'text-white',
+			arrow: {
+				t: 'border-t-danger-600',
+				b: 'border-b-danger-600',
+				l: 'border-l-danger-600',
+				r: 'border-r-danger-600'
+			}
+		},
+		success: {
+			bg: 'bg-success-600',
+			text: 'text-white',
+			arrow: {
+				t: 'border-t-success-600',
+				b: 'border-b-success-600',
+				l: 'border-l-success-600',
+				r: 'border-r-success-600'
+			}
+		}
+	};
+
+	const styles = $derived(variantStyles[variant]);
+
 	const arrowClass = $derived(
 		{
-			top: 'top-full left-1/2 -translate-x-1/2 border-t-default-800 border-l-transparent border-r-transparent border-b-transparent',
-			bottom:
-				'bottom-full left-1/2 -translate-x-1/2 border-b-default-800 border-l-transparent border-r-transparent border-t-transparent',
-			left: 'left-full top-1/2 -translate-y-1/2 border-l-default-800 border-t-transparent border-b-transparent border-r-transparent',
-			right:
-				'right-full top-1/2 -translate-y-1/2 border-r-default-800 border-t-transparent border-b-transparent border-l-transparent'
+			top: `top-full left-1/2 -translate-x-1/2 ${styles.arrow.t} border-l-transparent border-r-transparent border-b-transparent`,
+			bottom: `bottom-full left-1/2 -translate-x-1/2 ${styles.arrow.b} border-l-transparent border-r-transparent border-t-transparent`,
+			left: `left-full top-1/2 -translate-y-1/2 ${styles.arrow.l} border-t-transparent border-b-transparent border-r-transparent`,
+			right: `right-full top-1/2 -translate-y-1/2 ${styles.arrow.r} border-t-transparent border-b-transparent border-l-transparent`
 		}[placement]
 	);
+
+	const bodyIsInteractive = $derived(hideDelay > 0);
 </script>
 
 <span
@@ -69,14 +152,28 @@
 		<span
 			role="tooltip"
 			data-tooltip-visible="true"
+			transition:scale={{ duration: 500, start: 0.9, opacity: 0, easing: quintOut }}
 			class={cn(
-				'bg-default-800 pointer-events-none absolute z-50 rounded px-2 py-1 text-xs whitespace-nowrap text-white shadow-lg',
+				'absolute z-50 shadow-lg',
+				!bodyIsInteractive && 'pointer-events-none',
+				body ? '' : 'whitespace-nowrap',
+				sizeClasses[size],
+				styles.bg,
+				styles.text,
 				placementClass,
 				tooltipClass
 			)}
+			onmouseenter={cancelHide}
+			onmouseleave={hide}
 		>
-			{content}
-			<span class={cn('absolute h-0 w-0 border-4', arrowClass)} aria-hidden="true"></span>
+			{#if body}
+				{@render body()}
+			{:else}
+				{content}
+			{/if}
+			{#if arrow}
+				<span class={cn('absolute h-0 w-0 border-4', arrowClass)} aria-hidden="true"></span>
+			{/if}
 		</span>
 	{/if}
 </span>

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

@@ -1,13 +1,61 @@
 import type { ClassValue } from 'tailwind-variants';
 import type { Snippet } from 'svelte';
+/** Placement of the tooltip panel relative to its trigger. */
 export type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
+/** Size variants specific to Tooltip — a narrower subset of the global `VariantSizes`. */
+export type TooltipSize = 'sm' | 'md' | 'lg';
+/** Tooltip color palette. `'dark'` on light pages, `'light'` on dark pages. */
+export type TooltipVariant = 'dark' | 'light' | 'primary' | 'danger' | 'success';
+/**
+ * Props for `<Tooltip>` — small hover/focus-triggered label for a UI
+ * element. For longer or interactive content (links, buttons inside
+ * the panel), prefer `<Popover trigger="hover" hideDelay={200}>` —
+ * Tooltip closes immediately on mouseleave by default.
+ *
+ * @example
+ * ```svelte
+ * <Tooltip content="Delete this user">
+ *   <Button variant="ghost" color="danger"><TrashIcon /></Button>
+ * </Tooltip>
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- Rich content + interactive (keeps open while mouse is over body) -->
+ * <Tooltip variant="light" placement="right" hideDelay={200}>
+ *   {#snippet body()}
+ *     <div>
+ *       <strong>Keyboard shortcut</strong>
+ *       <p class="text-xs">Press ⌘ + K to open search</p>
+ *     </div>
+ *   {/snippet}
+ *   <kbd>⌘ K</kbd>
+ * </Tooltip>
+ * ```
+ */
 export type TooltipProps = {
-    content: string;
+    /** Plain text content. Ignored if `body` snippet is also provided. */
+    content?: string;
+    /** Rich content snippet — takes precedence over `content`. Use for HTML, links, icons, etc. */
+    body?: Snippet;
+    /** @default 'top' */
     placement?: TooltipPlacement;
+    /** Padding/text size. @default 'sm' */
+    size?: TooltipSize;
+    /** Color palette. @default 'dark' */
+    variant?: TooltipVariant;
+    /** Show arrow pointing at the trigger. @default true */
+    arrow?: boolean;
+    /** Delay before showing (ms). @default 100 */
     delay?: number;
+    /** Delay before hiding after mouseleave (ms). Non-zero lets users move into the tooltip. @default 0 */
+    hideDelay?: number;
     disabled?: boolean;
+    /** Classes for the trigger wrapper. */
     class?: ClassValue;
+    /** Classes for the tooltip panel. */
     tooltipClass?: ClassValue;
+    /** Trigger element(s). */
     children: Snippet;
     testId?: string;
 };

package/dist/file-browser/FileBrowser.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
 	import { onMount } from 'svelte';
 	import { cn } from '../helper/cls.js';
-	import { Button, Table, Color, Size, Spinner } from '../index.js';
+	import { Button, Table, Color, Size, Spinner, Skeleton } from '../index.js';
 	import type { TableColumn, FileBrowserProps } from '../index.js';
 	import { formatDate } from '../utils/dateUtils.js';
 	import type {
@@ -27,7 +27,7 @@
 	let files = $state<FileItem[]>([]);
 	let displayFiles = $state<FileItem[]>([]);
 	let currentPath = $state(startPath || '');
-	let isLoading = $state(true);
+	let loading = $state(true);
 	let isAuthenticated = $state(false);
 	let error = $state<string | null>(null);
 	let breadcrumbs = $state<Breadcrumb[]>([]);
@@ -162,7 +162,7 @@
 
 	// Loading files using the adapter
 	async function listFiles(path: string) {
-		isLoading = true;
+		loading = true;
 		error = null;
 
 		// Remember the previous selection before loading new files
@@ -192,7 +192,7 @@
 			console.error('Error fetching files:', err);
 			error = err instanceof Error ? err.message : 'An unknown error occurred';
 		} finally {
-			isLoading = false;
+			loading = false;
 		}
 	}
 
@@ -647,7 +647,7 @@
 	];
 
 	async function handleUnauthenticated() {
-		isLoading = true;
+		loading = true;
 
 		try {
 			// Use the adapter's method to set the reopening flag
@@ -664,11 +664,11 @@
 			}
 
 			// Note: authentication usually redirects the page, so code below won't run
-			isLoading = false;
+			loading = false;
 		} catch (error) {
 			console.error('Authentication error:', error);
 			console.error('Authentication error');
-			isLoading = false;
+			loading = false;
 		}
 	}
 
@@ -914,9 +914,18 @@
 			</div>
 
 			<div class="min-h-0 flex-1 overflow-auto">
-				{#if isLoading}
-					<div class="flex h-full items-center justify-center py-16">
-						<div class="text-default-500">Loading files...</div>
+				{#if loading}
+					<div class="divide-default-100 divide-y px-4" aria-label="Loading files">
+						{#each Array(6) as _, i (i)}
+							<div class="flex items-center gap-3 py-3">
+								<Skeleton class="size-5 shrink-0" />
+								<Skeleton class="size-6 shrink-0" rounded="rounded-md" />
+								<Skeleton class="h-4 flex-1" style="max-width: {200 + i * 30}px" />
+								<Skeleton class="h-3 w-16 shrink-0" />
+								<Skeleton class="h-3 w-24 shrink-0" />
+								<Skeleton class="h-7 w-16 shrink-0" rounded="rounded-md" />
+							</div>
+						{/each}
 					</div>
 				{:else if error}
 					<div class="flex h-full flex-col items-center justify-center py-16">
@@ -931,10 +940,10 @@
 					<Table
 						{columns}
 						data={displayFiles}
-						loading={isLoading}
+						{loading}
 						bordered={false}
 						onrowclick={handleRowClick}
-						rowclass={(row) => {
+						rowClass={(row: FileItem) => {
 							let classes = row.isFolder ? 'hover:bg-amber-50 cursor-pointer' : 'hover:bg-blue-50';
 							if (isRowSelected(row)) {
 								classes += ' bg-primary-50';