@makolabs/ripple 2.5.9 → 3.0.1

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

@@ -1,45 +1,10 @@
 export declare const selectTV: import("tailwind-variants").TVReturnType<{
     size: {
-        xs: {
+        [k: string]: {
             trigger: string;
             triggerIcon: string;
-            container: string;
-            item: string;
-            base: string;
-        };
-        sm: {
-            trigger: string;
-            triggerIcon: string;
-            container: string;
             item: string;
-            base: string;
-        };
-        base: {
-            trigger: string;
-            triggerIcon: string;
             container: string;
-            item: string;
-            base: string;
-        };
-        lg: {
-            trigger: string;
-            triggerIcon: string;
-            container: string;
-            item: string;
-            base: string;
-        };
-        xl: {
-            trigger: string;
-            triggerIcon: string;
-            container: string;
-            item: string;
-            base: string;
-        };
-        "2xl": {
-            trigger: string;
-            triggerIcon: string;
-            container: string;
-            item: string;
             base: string;
         };
     };
@@ -71,46 +36,11 @@ export declare const selectTV: import("tailwind-variants").TVReturnType<{
     emptyMessage: string;
 }, undefined, {
     size: {
-        xs: {
-            trigger: string;
-            triggerIcon: string;
-            container: string;
-            item: string;
-            base: string;
-        };
-        sm: {
-            trigger: string;
-            triggerIcon: string;
-            container: string;
-            item: string;
-            base: string;
-        };
-        base: {
-            trigger: string;
-            triggerIcon: string;
-            container: string;
-            item: string;
-            base: string;
-        };
-        lg: {
+        [k: string]: {
             trigger: string;
             triggerIcon: string;
-            container: string;
             item: string;
-            base: string;
-        };
-        xl: {
-            trigger: string;
-            triggerIcon: string;
             container: string;
-            item: string;
-            base: string;
-        };
-        "2xl": {
-            trigger: string;
-            triggerIcon: string;
-            container: string;
-            item: string;
             base: string;
         };
     };
@@ -142,46 +72,11 @@ export declare const selectTV: import("tailwind-variants").TVReturnType<{
     emptyMessage: string;
 }, import("tailwind-variants").TVReturnType<{
     size: {
-        xs: {
+        [k: string]: {
             trigger: string;
             triggerIcon: string;
-            container: string;
             item: string;
-            base: string;
-        };
-        sm: {
-            trigger: string;
-            triggerIcon: string;
             container: string;
-            item: string;
-            base: string;
-        };
-        base: {
-            trigger: string;
-            triggerIcon: string;
-            container: string;
-            item: string;
-            base: string;
-        };
-        lg: {
-            trigger: string;
-            triggerIcon: string;
-            container: string;
-            item: string;
-            base: string;
-        };
-        xl: {
-            trigger: string;
-            triggerIcon: string;
-            container: string;
-            item: string;
-            base: string;
-        };
-        "2xl": {
-            trigger: string;
-            triggerIcon: string;
-            container: string;
-            item: string;
             base: string;
         };
     };

package/dist/elements/dropdown/select.js

@@ -1,15 +1,49 @@
 import { tv } from 'tailwind-variants';
 import { Size } from '../../variants.js';
+import { formSizeTokens } from '../../forms/form-size.js';
+// Build the per-size slot overrides from the canonical form-size tokens
+// so Select coordinates visually with Input/Textarea/NumberInput at the
+// same `size` prop. Container max-heights and base min-widths stay here
+// because they're Select-specific (not tied to field sizing).
+const containerHeights = {
+    [Size.XS]: 'max-h-32',
+    [Size.SM]: 'max-h-40',
+    [Size.MD]: 'max-h-56',
+    [Size.LG]: 'max-h-64',
+    [Size.XL]: 'max-h-72',
+    [Size.XXL]: 'max-h-80'
+};
+const minWidths = {
+    [Size.XS]: 'min-w-20',
+    [Size.SM]: 'min-w-28',
+    [Size.MD]: 'min-w-32',
+    [Size.LG]: 'min-w-40',
+    [Size.XL]: 'min-w-48',
+    [Size.XXL]: 'min-w-56'
+};
+const sizeVariants = Object.fromEntries(Object.keys(formSizeTokens).map((key) => {
+    const t = formSizeTokens[key];
+    return [
+        key,
+        {
+            trigger: `${t.height} ${t.padX} ${t.padY} ${t.text} ${t.gap} ${t.radius} ${t.shadow}`,
+            triggerIcon: t.iconSize,
+            item: `${t.padX} ${t.padY} ${t.text}`,
+            container: containerHeights[key],
+            base: minWidths[key]
+        }
+    ];
+}));
 export const selectTV = tv({
     slots: {
         base: 'w-full',
         trigger: `relative flex items-center justify-between w-full text-left bg-white border
-			border-default-300 text-sm focus-within:outline-none focus-within:ring-2 focus-within:ring-offset-2 focus-within:border-primary-500 focus-within:ring-primary-500 rounded-lg shadow-xs cursor-pointer transition-colors hover:border-default-400`,
+			border-default-300 focus-within:outline-none focus-within:ring-2 focus-within:ring-offset-2 focus-within:border-primary-500 focus-within:ring-primary-500 cursor-pointer transition-colors hover:border-default-400`,
         triggerIcon: 'transition-transform duration-200 text-default-500',
         container: 'absolute z-50 w-full mt-1 bg-white overflow-clip border border-default-200 rounded-md shadow-sm origin-top-left top-full left-0 mt-2',
         searchInput: 'flex items-center gap-x-3 w-full outline-none px-2 h-10 border-b border-b-default-200',
         list: 'py-1 max-h-60 overflow-x-clip overflow-y-auto h-full',
-        item: `w-full px-3 py-2 text-sm text-left
+        item: `w-full text-left
 		data-[highlighted=true]:bg-default-100 data-[highlighted=true]:text-default-700
 		data-[selected=true]:bg-info-100 data-[selected=true]:text-info-500 data-[selected=true]:font-medium
 		data-[selected=true]:data-[highlighted=true]:bg-info-200 data-[selected=true]:data-[highlighted=true]:text-info-500
@@ -17,50 +51,7 @@ export const selectTV = tv({
         emptyMessage: 'px-3 py-2 text-sm text-default-500'
     },
     variants: {
-        size: {
-            [Size.XS]: {
-                trigger: 'h-6 px-2 py-1 text-xs gap-1',
-                triggerIcon: 'h-3 w-3',
-                container: 'max-h-40',
-                item: 'px-2 py-1 text-xs',
-                base: 'min-w-24'
-            },
-            [Size.SM]: {
-                trigger: 'h-8 px-3 py-2 text-sm gap-1.5',
-                triggerIcon: 'h-3.5 w-3.5',
-                container: 'max-h-48',
-                item: 'px-2.5 py-1.5 text-xs',
-                base: 'min-w-32'
-            },
-            [Size.BASE]: {
-                trigger: 'h-10 px-3 py-2 text-base gap-2',
-                triggerIcon: 'h-4 w-4',
-                container: 'max-h-60',
-                item: 'px-3 py-2 text-sm',
-                base: 'min-w-40'
-            },
-            [Size.LG]: {
-                trigger: 'h-12 px-3 py-2 text-lg gap-2.5',
-                triggerIcon: 'h-5 w-5',
-                container: 'max-h-72',
-                item: 'px-4 py-2.5 text-base',
-                base: 'min-w-48'
-            },
-            [Size.XL]: {
-                trigger: 'h-12 px-5 py-3 text-lg gap-3',
-                triggerIcon: 'h-6 w-6',
-                container: 'max-h-80',
-                item: 'px-5 py-3 text-lg',
-                base: 'min-w-56'
-            },
-            [Size.XXL]: {
-                trigger: 'h-14 px-6 py-3.5 text-xl gap-4',
-                triggerIcon: 'h-7 w-7',
-                container: 'max-h-96',
-                item: 'px-6 py-3.5 text-xl',
-                base: 'min-w-64'
-            }
-        },
+        size: sizeVariants,
         disabled: {
             true: {
                 trigger: 'opacity-50 cursor-not-allowed hover:border-default-300',
@@ -80,7 +71,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;