@makolabs/ripple 2.5.8 → 3.0.0

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

@@ -2,53 +2,149 @@ import type { ClassValue } from 'tailwind-variants';
 import type { Snippet } from 'svelte';
 import type { Component } from 'svelte';
 import type { VariantSizes } from '../../index.js';
+/** Single menu entry in a `<Dropdown>` section. */
 export type DropdownItem = {
+    /** Visible text. */
     label: string;
+    /** If set, renders the item as a link; otherwise as a button. Typed to SvelteKit routes. */
     href?: `/${string}`;
+    /** Optional icon rendered on the left. */
     icon?: Component;
+    /** Click handler (ignored when `href` is set — native navigation wins). */
     onclick?: () => void;
+    /** Visually highlight the item as the current route/selection. */
     active?: boolean;
 };
+/** A visually grouped subset of items — renders with a separator between sections. */
 export type DropSection = {
     items: DropdownItem[];
 };
+/**
+ * Optional header at the top of the dropdown panel (user profile snippet,
+ * workspace switcher heading, etc.).
+ */
 export type DropHeaderConfig = {
     title?: string;
     subtitle?: string;
+    /** Custom header content. Takes precedence over `title`/`subtitle`. */
     content?: Snippet<[]>;
     class?: ClassValue;
     titleClass?: ClassValue;
     subtitleClass?: ClassValue;
+    /** Click handler for the header row. */
     onclick?: () => void;
 };
+/**
+ * Props for `<Dropdown>` — an action menu attached to a trigger button.
+ * Use for context actions, overflow menus, user profile menus, etc.
+ *
+ * For *form* selection (picking one of many values), use `<Select>`
+ * instead — that's a controlled form input.
+ *
+ * @example
+ * ```svelte
+ * <Dropdown
+ *   label="Actions"
+ *   sections={[
+ *     {
+ *       items: [
+ *         { label: 'Edit', icon: EditIcon, onclick: () => edit() },
+ *         { label: 'Duplicate', icon: CopyIcon, onclick: () => duplicate() }
+ *       ]
+ *     },
+ *     { items: [{ label: 'Delete', icon: TrashIcon, onclick: () => remove() }] }
+ *   ]}
+ * />
+ * ```
+ */
 export type DropdownMenuProps = {
+    /** Bindable open state. @default false */
     open?: boolean;
+    /** Ordered sections of items. A divider renders between adjacent sections. */
     sections: DropSection[];
+    /** Trigger button label. */
     label?: string;
+    /** Trigger button icon (rendered instead of or alongside `label`). */
     icon?: Component;
+    /** Classes on the outer positioned wrapper. */
     containerClass?: ClassValue;
+    /** Classes on each item button. */
     itemClass?: ClassValue;
+    /** Classes on the trigger button. */
     class?: ClassValue;
     size?: VariantSizes;
     disabled?: boolean;
+    /**
+     * Panel placement anchored to the trigger's corner:
+     * - `'bottom-right'` (default) — typical dropdown to the right
+     * - `'bottom-left'` — dropdown aligned to the trigger's left edge
+     * - `'top-right'` / `'top-left'` — upward-opening (use when near page bottom)
+     */
     position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    /**
+     * Explicit panel width. Accepts any CSS value (`'200px'`, `'12rem'`,
+     * `'100%'`). @default auto-sized to content
+     */
     width?: string;
+    /** Optional header shown above the first section. */
     header?: DropHeaderConfig;
     testId?: string;
 };
+/** Single option in a `<Select>` list. */
 export type SelectItem = {
+    /** Visible text. */
     label: string;
+    /** Underlying form value. */
     value: string;
     disabled?: boolean;
+    /** Optional icon rendered next to the label. */
     icon?: Component;
+    /** Short helper text shown below the label in the dropdown. */
     description?: string;
+    /**
+     * Group name — items with the same `group` are rendered together
+     * under a group heading. Items without `group` render at the top.
+     */
     group?: string;
 };
+/**
+ * Props for `<Select>` — a controlled single- or multi-select form input
+ * with optional search. For free-typing + filter UX prefer `<ComboBox>`;
+ * for a short list of radio-style options use `<RadioGroup>`.
+ *
+ * @example
+ * ```svelte
+ * <Select
+ *   items={[
+ *     { value: 'draft', label: 'Draft' },
+ *     { value: 'published', label: 'Published' },
+ *     { value: 'archived', label: 'Archived' }
+ *   ]}
+ *   bind:value={status}
+ * />
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- Multi-select with server-side search -->
+ * <Select
+ *   multiple
+ *   searchable
+ *   items={[]}
+ *   onsearch={async (q) => await api.searchTags(q)}
+ *   bind:value={selectedTags}
+ * />
+ * ```
+ */
 export type SelectProps = {
+    /** Static list of options. Omit + pair with `onsearch` for server-side search. */
     items?: SelectItem[];
+    /** Bindable selected value (string) or values (`multiple` mode). */
     value?: string | string[];
+    /** Allow selecting multiple items. Changes `value` to `string[]`. @default false */
     multiple?: boolean;
     placeholder?: string;
+    /** Show a search input at the top of the dropdown. @default false */
     searchable?: boolean;
     disabled?: boolean;
     size?: VariantSizes;
@@ -58,21 +154,39 @@ export type SelectProps = {
     itemClass?: ClassValue;
     triggerClass?: ClassValue;
     searchInputClass?: ClassValue;
+    /** Show a × when a value is selected. @default true */
     clearable?: boolean;
+    /** Icon rendered in the trigger (e.g. search icon for an "Add filter" menu). */
     icon?: Component;
     iconClass?: ClassValue;
     errors?: string[];
+    /** Fires on selection change. Value shape depends on `multiple`. */
     onselect?: ({ value }: {
         value: string | string[];
     }) => void;
+    /** Fires when the dropdown panel opens. */
     onopen?: () => void;
+    /** Fires when the dropdown panel closes. */
     onclose?: () => void;
     testId?: string;
+    /**
+     * Server-side search handler. When set, local filtering is bypassed
+     * and this is called (debounced by `debounceMs`) whenever the user
+     * types. Return items to display.
+     */
     onsearch?: (query: string) => SelectItem[] | Promise<SelectItem[]>;
+    /** Debounce delay for `onsearch`. @default 200 */
     debounceMs?: number;
+    /** Minimum query length before `onsearch` fires. @default 0 */
     minSearchLength?: number;
+    /** Text shown while an async `onsearch` is in flight. @default 'Loading…' */
     loadingText?: string;
+    /** Text shown when the item list is empty. @default 'No results' */
     emptyText?: string;
+    /**
+     * Per-item custom rendering. Receives the item and its state flags.
+     * Use for rich options (avatars, two-line cards, etc.).
+     */
     itemSnippet?: Snippet<[SelectItem, {
         highlighted: boolean;
         selected: boolean;

package/dist/elements/dropdown/dropdown.d.ts

@@ -30,7 +30,7 @@ export declare const dropdownMenu: import("tailwind-variants").TVReturnType<{
             headerTitle: string;
             headerSubtitle: string;
         };
-        base: {
+        md: {
             trigger: string;
             item: string;
             itemIcon: string;
@@ -113,7 +113,7 @@ export declare const dropdownMenu: import("tailwind-variants").TVReturnType<{
             headerTitle: string;
             headerSubtitle: string;
         };
-        base: {
+        md: {
             trigger: string;
             item: string;
             itemIcon: string;
@@ -196,7 +196,7 @@ export declare const dropdownMenu: import("tailwind-variants").TVReturnType<{
             headerTitle: string;
             headerSubtitle: string;
         };
-        base: {
+        md: {
             trigger: string;
             item: string;
             itemIcon: string;

package/dist/elements/dropdown/dropdown.js

@@ -44,7 +44,7 @@ export const dropdownMenu = tv({
                 headerTitle: 'text-xs',
                 headerSubtitle: 'text-xs'
             },
-            [Size.BASE]: {
+            [Size.MD]: {
                 trigger: 'px-3 py-2 text-sm',
                 item: 'px-4 py-2 text-sm',
                 itemIcon: 'mr-3 size-5',
@@ -88,7 +88,7 @@ export const dropdownMenu = tv({
     },
     defaultVariants: {
         position: 'bottom-right',
-        size: Size.BASE,
+        size: Size.MD,
         isOpen: false,
         iconOnly: false
     }

package/dist/elements/dropdown/select.d.ts

@@ -14,7 +14,7 @@ export declare const selectTV: import("tailwind-variants").TVReturnType<{
             item: string;
             base: string;
         };
-        base: {
+        md: {
             trigger: string;
             triggerIcon: string;
             container: string;
@@ -85,7 +85,7 @@ export declare const selectTV: import("tailwind-variants").TVReturnType<{
             item: string;
             base: string;
         };
-        base: {
+        md: {
             trigger: string;
             triggerIcon: string;
             container: string;
@@ -156,7 +156,7 @@ export declare const selectTV: import("tailwind-variants").TVReturnType<{
             item: string;
             base: string;
         };
-        base: {
+        md: {
             trigger: string;
             triggerIcon: string;
             container: string;

package/dist/elements/dropdown/select.js

@@ -32,7 +32,7 @@ export const selectTV = tv({
                 item: 'px-2.5 py-1.5 text-xs',
                 base: 'min-w-32'
             },
-            [Size.BASE]: {
+            [Size.MD]: {
                 trigger: 'h-10 px-3 py-2 text-base gap-2',
                 triggerIcon: 'h-4 w-4',
                 container: 'max-h-60',
@@ -80,7 +80,7 @@ export const selectTV = tv({
         }
     },
     defaultVariants: {
-        size: 'base',
+        size: 'md',
         disabled: false,
         multiple: false,
         error: false

package/dist/elements/empty-state/EmptyState.svelte

@@ -8,7 +8,7 @@
 	let {
 		title,
 		description,
-		size = Size.BASE,
+		size = Size.MD,
 		class: className = '',
 		icon,
 		action,

package/dist/elements/empty-state/empty-state-types.d.ts

@@ -1,12 +1,43 @@
 import type { ClassValue } from 'tailwind-variants';
 import type { Snippet } from 'svelte';
-export type EmptyStateSize = 'sm' | 'base' | 'lg' | 'xl';
+/** Density variants specific to EmptyState. */
+export type EmptyStateSize = 'sm' | 'md' | 'lg' | 'xl';
+/**
+ * Props for `<EmptyState>` — centered placeholder shown when a list,
+ * table, or panel has no content to display yet. Put an illustration,
+ * a clear title, a helpful description, and a primary action that
+ * breaks the blank-page anxiety.
+ *
+ * @example
+ * ```svelte
+ * <EmptyState
+ *   title="No customers yet"
+ *   description="Once you import or create a customer they'll appear here."
+ * >
+ *   {#snippet icon()}
+ *     <svg viewBox="0 0 24 24">…</svg>
+ *   {/snippet}
+ *   {#snippet action()}
+ *     <Button color="primary" onclick={create}>Add customer</Button>
+ *   {/snippet}
+ * </EmptyState>
+ * ```
+ */
 export type EmptyStateProps = {
+    /** Heading — keep short, focus on what's missing. */
     title: string;
+    /** One-sentence explanation of what's missing and what to do. */
     description?: string;
+    /** @default 'md' */
     size?: EmptyStateSize;
     class?: ClassValue;
+    /**
+     * Icon/illustration snippet. Unlike other components that take an icon
+     * `Component`, EmptyState uses a `Snippet` so consumers can inline SVGs
+     * or illustrations with arbitrary markup (common empty-state pattern).
+     */
     icon?: Snippet;
+    /** Primary action snippet — usually a single Button. */
     action?: Snippet;
     testId?: string;
 };

package/dist/elements/empty-state/empty-state.d.ts

@@ -6,7 +6,7 @@ export declare const emptyState: import("tailwind-variants").TVReturnType<{
             title: string;
             description: string;
         };
-        base: {
+        md: {
             wrapper: string;
             iconWrapper: string;
             title: string;
@@ -39,7 +39,7 @@ export declare const emptyState: import("tailwind-variants").TVReturnType<{
             title: string;
             description: string;
         };
-        base: {
+        md: {
             wrapper: string;
             iconWrapper: string;
             title: string;
@@ -72,7 +72,7 @@ export declare const emptyState: import("tailwind-variants").TVReturnType<{
             title: string;
             description: string;
         };
-        base: {
+        md: {
             wrapper: string;
             iconWrapper: string;
             title: string;

package/dist/elements/empty-state/empty-state.js

@@ -16,7 +16,7 @@ export const emptyState = tv({
                 title: 'text-sm',
                 description: 'text-xs'
             },
-            [Size.BASE]: {
+            [Size.MD]: {
                 wrapper: 'gap-3 p-8',
                 iconWrapper: 'h-10 w-10',
                 title: 'text-base',
@@ -37,6 +37,6 @@ export const emptyState = tv({
         }
     },
     defaultVariants: {
-        size: Size.BASE
+        size: Size.MD
     }
 });

package/dist/elements/file-upload/FileUpload.svelte

@@ -4,6 +4,9 @@
 	import Button from '../../button/Button.svelte';
 	import Spinner from '../spinner/Spinner.svelte';
 	import { Size, Color } from '../../variants.js';
+	import { fade } from 'svelte/transition';
+	import { flip } from 'svelte/animate';
+	import { quintOut } from 'svelte/easing';
 	import type { FileUploadProps, StagedFile } from '../../index.js';
 
 	let {
@@ -330,6 +333,8 @@
 						class={cn('flex items-center gap-3 px-3 py-2', status === 'success' && 'opacity-60')}
 						data-fileupload-row=""
 						data-status={status}
+						transition:fade={{ duration: 300, easing: quintOut }}
+						animate:flip={{ duration: 350, easing: quintOut }}
 					>
 						{#if status === 'ready'}
 							<span

package/dist/elements/file-upload/file-upload-types.d.ts

@@ -24,6 +24,54 @@ export interface StagedFile {
     /** Optional error message rendered under the file name while status='error'. */
     error?: string;
 }
+/**
+ * Props for `<FileUpload>` — a flexible drag-and-drop zone that supports
+ * single-file pick, multi-file staging, and "rich mode" with per-file
+ * upload progress.
+ *
+ * **Mode selection** is via `maxFiles`:
+ * - `maxFiles=1` (default) → single-file: `onfiles` fires immediately.
+ * - `maxFiles>1` (omit `bind:files`) → simple multi-file staging.
+ * - `maxFiles>1` + `bind:files` + `clearAfterUpload={false}` → rich mode
+ *   with per-file status icons + progress bars driven by the consumer.
+ *
+ * For browsing files already on a remote storage (S3, GDrive), use
+ * `<FileBrowser>` instead.
+ *
+ * @example
+ * ```svelte
+ * <!-- Simple single-file -->
+ * <FileUpload allowedMimeTypes={['.csv']} onfiles={(files) => upload(files[0])} />
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- Multi-file rich mode with per-row progress -->
+ * <script lang="ts">
+ *   let files = $state<StagedFile[]>([]);
+ *   async function handleFiles(toUpload: File[]) {
+ *     for (const file of toUpload) {
+ *       const item = files.find(f => f.file === file)!;
+ *       item.status = 'uploading';
+ *       try {
+ *         await api.upload(file, (pct) => (item.progress = pct));
+ *         item.status = 'success';
+ *       } catch (err) {
+ *         item.status = 'error';
+ *         item.error = String(err);
+ *       }
+ *     }
+ *   }
+ * </script>
+ *
+ * <FileUpload
+ *   maxFiles={10}
+ *   bind:files
+ *   clearAfterUpload={false}
+ *   onfiles={handleFiles}
+ * />
+ * ```
+ */
 export interface FileUploadProps {
     /**
      * Array of allowed file MIME types or extensions.
@@ -119,12 +167,23 @@ export interface FileUploadProps {
     /** Optional snippet rendered above the dropzone (for titles, selects, banners). */
     header?: Snippet;
 }
+/**
+ * Props for `<FilesPreview>` — renders a list of already-uploaded files
+ * with per-row delete affordance. Pair with `<FileUpload>` to show the
+ * "files uploaded so far" beneath the dropzone.
+ */
 export interface FilePreviewProps {
     files: UploadedFile[];
+    /** Fires when the user clicks the × on a file row. */
     ondelete?: (fileId: string, index: number) => void;
     class?: ClassValue;
     testId?: string;
 }
+/**
+ * A file that has already been uploaded to your backend (vs `StagedFile`,
+ * which represents a file in flight). Field naming mirrors common
+ * server-returned shapes — adapt as needed.
+ */
 export interface UploadedFile {
     FileID: string;
     OriginalFilename: string;

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}