@makolabs/ripple 2.5.9 → 3.0.0

package/dist/adapters/storage/S3Adapter.d.ts

@@ -1,7 +1,36 @@
 import type { FileItem, FileListResult } from './types.js';
 import { BaseAdapter } from './BaseAdapter.js';
 /**
- * S3 storage adapter for the FileBrowser component
+ * S3 storage adapter — the client-side half of the FileBrowser component.
+ *
+ * Talks to **two HTTP endpoints your app must expose**:
+ * - `GET /api/s3/list?prefix=<path>&search=<term>` — returns `{ folders, files }`
+ * - `GET /api/s3/download?key=<objectKey>` — returns a presigned URL as plain text
+ *
+ * The easiest way to implement the server side is with `createS3Handlers`
+ * from `@makolabs/ripple/server`, which keeps AWS credentials server-side
+ * and matches this adapter's expected request/response contract.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { FileBrowser, S3Adapter } from '@makolabs/ripple';
+ *
+ *   // Browse the whole bucket:
+ *   const adapter = new S3Adapter({ basePath: '/' });
+ *
+ *   // Or scope to a prefix and only list CSV/JSON files:
+ *   // const adapter = new S3Adapter({
+ *   //   basePath: 'imports/',
+ *   //   fileExtensions: ['csv', 'json']
+ *   // });
+ * </script>
+ *
+ * <FileBrowser {adapter} />
+ * ```
+ *
+ * @see `createS3Handlers` in `@makolabs/ripple/server` for the matching
+ *      server-side SvelteKit route handlers.
  */
 export declare class S3Adapter extends BaseAdapter {
     private basePath;
@@ -10,9 +39,28 @@ export declare class S3Adapter extends BaseAdapter {
     private displayNameStripPattern;
     /** Default pattern strips common compression extensions (.gz, .bz2, .zip, .zst, .xz, .lz4). */
     private static DEFAULT_STRIP_PATTERN;
+    /**
+     * @param basePathOrOptions Either a plain `basePath` string (e.g. `'imports/'`)
+     *   or an options object. Pass an options object for anything beyond the
+     *   basePath — it's the preferred form. A trailing string arg is supported
+     *   for legacy callers.
+     * @param publicS3BasePath Legacy positional fallback for `basePath`. Prefer
+     *   the options-object form.
+     */
     constructor(basePathOrOptions?: string | {
+        /** Prefix that scopes the browser (e.g. `'imports/'`). Shown as the root. @default '/' */
         basePath?: string;
+        /**
+         * Override the bucket passed to the server endpoints via the
+         * `?bucket=` query param. Only has effect if the server's
+         * `createS3Handlers` was created with `allowBucketOverride: true`.
+         */
         bucket?: string;
+        /**
+         * If set, only files with one of these extensions (case-insensitive,
+         * no dot — e.g. `['csv', 'json']`) appear in the list. Folders are
+         * always shown.
+         */
         fileExtensions?: string[];
         /** Regex applied to the filename to produce displayNameKey. @default strips .gz/.bz2/.zip/.zst/.xz/.lz4 */
         displayNameStripPattern?: RegExp;

package/dist/adapters/storage/S3Adapter.js

@@ -1,6 +1,35 @@
 import { BaseAdapter } from './BaseAdapter.js';
 /**
- * S3 storage adapter for the FileBrowser component
+ * S3 storage adapter — the client-side half of the FileBrowser component.
+ *
+ * Talks to **two HTTP endpoints your app must expose**:
+ * - `GET /api/s3/list?prefix=<path>&search=<term>` — returns `{ folders, files }`
+ * - `GET /api/s3/download?key=<objectKey>` — returns a presigned URL as plain text
+ *
+ * The easiest way to implement the server side is with `createS3Handlers`
+ * from `@makolabs/ripple/server`, which keeps AWS credentials server-side
+ * and matches this adapter's expected request/response contract.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { FileBrowser, S3Adapter } from '@makolabs/ripple';
+ *
+ *   // Browse the whole bucket:
+ *   const adapter = new S3Adapter({ basePath: '/' });
+ *
+ *   // Or scope to a prefix and only list CSV/JSON files:
+ *   // const adapter = new S3Adapter({
+ *   //   basePath: 'imports/',
+ *   //   fileExtensions: ['csv', 'json']
+ *   // });
+ * </script>
+ *
+ * <FileBrowser {adapter} />
+ * ```
+ *
+ * @see `createS3Handlers` in `@makolabs/ripple/server` for the matching
+ *      server-side SvelteKit route handlers.
  */
 export class S3Adapter extends BaseAdapter {
     basePath;
@@ -9,6 +38,14 @@ export class S3Adapter extends BaseAdapter {
     displayNameStripPattern;
     /** Default pattern strips common compression extensions (.gz, .bz2, .zip, .zst, .xz, .lz4). */
     static DEFAULT_STRIP_PATTERN = /\.(gz|bz2|zip|zst|xz|lz4)$/i;
+    /**
+     * @param basePathOrOptions Either a plain `basePath` string (e.g. `'imports/'`)
+     *   or an options object. Pass an options object for anything beyond the
+     *   basePath — it's the preferred form. A trailing string arg is supported
+     *   for legacy callers.
+     * @param publicS3BasePath Legacy positional fallback for `basePath`. Prefer
+     *   the options-object form.
+     */
     constructor(basePathOrOptions, publicS3BasePath) {
         super();
         if (typeof basePathOrOptions === 'object' && basePathOrOptions !== null) {

package/dist/adapters/storage/types.d.ts

@@ -93,18 +93,38 @@ export interface ErrorReportOptions {
     userAction?: string;
 }
 type URLString = string;
+/**
+ * Contract every `FileBrowser` adapter implements. Ripple ships `S3Adapter`
+ * and `GoogleDriveAdapter`; extend `BaseAdapter` (or implement this directly)
+ * to add a new storage backend.
+ */
 export interface StorageAdapter {
+    /** Human-readable provider name for UI display (e.g. `'S3'`, `'Google Drive'`). */
     getName(): string;
+    /**
+     * List folders and files at the given path. `searchQuery` is a
+     * case-insensitive substring filter applied by the adapter.
+     */
     list(path: string, searchQuery?: string): Promise<FileListResult>;
+    /** Returns a URL the browser can GET to download the file (presigned for S3). */
     download(file: FileItem): Promise<URLString>;
+    /** Start an import of a single file. Only implemented by adapters that support import. */
     import?(file: FileItem, options: ImportOptions): Promise<ImportResult>;
+    /** Start a batch import. Only implemented by adapters that support import. */
     batchImport?(files: FileItem[], options: ImportOptions): Promise<BatchImportResult>;
+    /** Poll the status of an in-flight import. */
     getImportStatus?(importId: string, fileKey?: string): Promise<ImportStatus>;
+    /** Report a detailed error for a file import (for telemetry/support). */
     reportError?(importId: string, options: ErrorReportOptions): Promise<boolean>;
+    /** True when the adapter has what it needs to operate (env vars set, tokens valid, etc.). */
     isConfigured(): Promise<boolean>;
+    /** Optional OAuth-style authentication step. Called by the browser on first open. */
     authenticate?(): Promise<boolean>;
+    /** Set a localStorage flag so the browser can auto-reopen after an OAuth redirect. */
     setReopenFlag(): void;
+    /** Check whether the browser should auto-reopen after an OAuth redirect. */
     shouldReopenBrowser(): boolean;
+    /** Clear the auto-reopen flag after the browser has been restored. */
     clearReopenFlag(): void;
 }
 export {};

package/dist/ai/AIChatInterface.svelte

@@ -6,6 +6,7 @@
 	import ThinkingDisplay from './ThinkingDisplay.svelte';
 	import type { ChatMessage, ChatAction, VariantColors, StreamingCallback } from '../index.js';
 	import type { AIAdapter } from '../adapters/ai/index.js';
+	import type { ClassValue } from 'tailwind-variants';
 
 	interface AIChatInterfaceProps {
 		adapter: AIAdapter;
@@ -16,7 +17,7 @@
 		disabled?: boolean;
 		loading?: boolean;
 		messages?: ChatMessage[];
-		class?: string;
+		class?: ClassValue;
 		context?: Record<string, unknown>;
 	}
 

package/dist/ai/AIChatInterface.svelte.d.ts

@@ -1,5 +1,6 @@
 import type { ChatMessage, VariantColors } from '../index.js';
 import type { AIAdapter } from '../adapters/ai/index.js';
+import type { ClassValue } from 'tailwind-variants';
 interface AIChatInterfaceProps {
     adapter: AIAdapter;
     title?: string;
@@ -9,7 +10,7 @@ interface AIChatInterfaceProps {
     disabled?: boolean;
     loading?: boolean;
     messages?: ChatMessage[];
-    class?: string;
+    class?: ClassValue;
     context?: Record<string, unknown>;
 }
 declare const AIChatInterface: import("svelte").Component<AIChatInterfaceProps, {}, "messages">;

package/dist/ai/CodeRenderer.svelte

@@ -1,6 +1,8 @@
 <script lang="ts">
 	import Highlight from 'svelte-highlight';
 	import { HighlightAuto } from 'svelte-highlight';
+	import type { ClassValue } from 'tailwind-variants';
+	import { cn } from '../helper/cls.js';
 
 	// Import common languages
 	import javascript from 'svelte-highlight/languages/javascript';
@@ -31,7 +33,7 @@
 	interface Props {
 		code: string;
 		language?: string;
-		class?: string;
+		class?: ClassValue;
 	}
 
 	let { code, language = 'text', class: className = '' }: Props = $props();
@@ -102,7 +104,10 @@
 </svelte:head>
 
 <div
-	class="code-renderer border-default-700 bg-default-900 my-4 overflow-hidden rounded-lg border {className}"
+	class={cn(
+		'code-renderer border-default-700 bg-default-900 my-4 overflow-hidden rounded-lg border',
+		className
+	)}
 >
 	<!-- Header -->
 	<div

package/dist/ai/CodeRenderer.svelte.d.ts

@@ -1,7 +1,8 @@
+import type { ClassValue } from 'tailwind-variants';
 interface Props {
     code: string;
     language?: string;
-    class?: string;
+    class?: ClassValue;
 }
 declare const CodeRenderer: import("svelte").Component<Props, {}, "">;
 type CodeRenderer = ReturnType<typeof CodeRenderer>;

package/dist/ai/ComposeDropdown.svelte

@@ -163,7 +163,7 @@
 					<Toggle
 						name="thinking-mode"
 						bind:value={thinkingMode}
-						size={Size.BASE}
+						size={Size.MD}
 						color="primary"
 						class="ml-2"
 					/>

package/dist/ai/MessageBox.svelte

@@ -2,7 +2,7 @@
 	import { cn } from '../helper/cls.js';
 	import { formatTime } from '../helper/date.js';
 	import { marked } from 'marked';
-	import { tv } from 'tailwind-variants';
+	import { tv, type ClassValue } from 'tailwind-variants';
 	import type { VariantColors } from '../index.js';
 	import { parseContentSegments } from './content-detector.js';
 	import MermaidRenderer from './MermaidRenderer.svelte';
@@ -13,8 +13,8 @@
 		isUser: boolean;
 		color?: VariantColors;
 		timestamp?: Date;
-		userMessageClass?: string;
-		aiMessageClass?: string;
+		userMessageClass?: ClassValue;
+		aiMessageClass?: ClassValue;
 	}
 
 	let {

package/dist/ai/MessageBox.svelte.d.ts

@@ -1,11 +1,12 @@
+import { type ClassValue } from 'tailwind-variants';
 import type { VariantColors } from '../index.js';
 interface Props {
     content: string;
     isUser: boolean;
     color?: VariantColors;
     timestamp?: Date;
-    userMessageClass?: string;
-    aiMessageClass?: string;
+    userMessageClass?: ClassValue;
+    aiMessageClass?: ClassValue;
 }
 declare const MessageBox: import("svelte").Component<Props, {}, "">;
 type MessageBox = ReturnType<typeof MessageBox>;

package/dist/ai/ThinkingDisplay.svelte

@@ -1,11 +1,12 @@
 <script lang="ts">
-	import { tv } from 'tailwind-variants';
+	import { tv, type ClassValue } from 'tailwind-variants';
+	import { cn } from '../helper/cls.js';
 
 	interface ThinkingDisplayProps {
 		content: string;
 		isComplete?: boolean;
 		isVisible?: boolean;
-		class?: string;
+		class?: ClassValue;
 	}
 
 	let {
@@ -156,7 +157,7 @@
 </script>
 
 {#if isVisible && content}
-	<div bind:this={containerRef} class={`${containerClasses} ${className}`}>
+	<div bind:this={containerRef} class={cn(containerClasses, className)}>
 		<!-- Header -->
 		<div
 			class={headerClasses}

package/dist/ai/ThinkingDisplay.svelte.d.ts

@@ -1,8 +1,9 @@
+import { type ClassValue } from 'tailwind-variants';
 interface ThinkingDisplayProps {
     content: string;
     isComplete?: boolean;
     isVisible?: boolean;
-    class?: string;
+    class?: ClassValue;
 }
 declare const ThinkingDisplay: import("svelte").Component<ThinkingDisplayProps, {}, "">;
 type ThinkingDisplay = ReturnType<typeof ThinkingDisplay>;

package/dist/ai/ai-types.d.ts

@@ -1,39 +1,93 @@
 import type { Component } from 'svelte';
+import type { ClassValue } from 'tailwind-variants';
 import type { FileAction, FileItem, StorageAdapter } from '../adapters/storage/types.js';
+/**
+ * Kind of message in the chat stream:
+ * - `'chat'` — normal user/assistant text turn
+ * - `'action'` — a tool call / structured action emitted by the model
+ * - `'thinking'` — reasoning content (model's internal monologue)
+ */
 export type ChatMessageType = 'chat' | 'action' | 'thinking';
+/** Callback signature for streaming chat responses — fires per chunk. */
 export type StreamingCallback = (response: ChatResponse) => void;
+/**
+ * Structured action emitted by an AI message (tool call, function
+ * invocation, navigation request, etc.). The `type` discriminator is
+ * consumer-defined; `data` carries the action payload.
+ */
 export interface ChatAction {
     type: string;
     data: any;
     metadata?: Record<string, any>;
 }
+/** A single message in the chat history (rendered by `<AIChatInterface>`). */
 export interface ChatMessage {
     id: string;
     type: ChatMessageType;
     content: string;
     timestamp: Date;
     action?: ChatAction;
+    /** Reasoning text rendered separately from `content` (collapsible). */
     thinkingContent?: string;
+    /** Set true once the thinking stream has finished. */
     isThinkingComplete?: boolean;
 }
+/**
+ * Response chunk from a streaming AI adapter. Adapters call the
+ * StreamingCallback once per chunk while a response is in flight; the
+ * final chunk has `isStreamEnd: true`.
+ */
 export interface ChatResponse {
     type: ChatMessageType;
     content: string;
     action?: ChatAction;
+    /** ID of the message being updated (for streaming). */
     messageId?: string;
+    /** Indicates if this is a streaming response. */
     isStreaming?: boolean;
+    /** Indicates if this is the final chunk. */
     isStreamEnd?: boolean;
+    /** Reasoning/thinking content. */
     thinkingContent?: string;
+    /** Indicates if thinking is complete. */
     isThinkingComplete?: boolean;
 }
+/**
+ * Suggested prompt button shown above the input in `<AIChatInterface>`.
+ * Clicking it pre-fills the input with `prompt`.
+ */
 export interface QuickAction {
     label: string;
     prompt: string;
     icon?: Component;
 }
 export interface FileBrowserProps {
+    /**
+     * Storage adapter that backs the browser. Typically `S3Adapter` from
+     * `@makolabs/ripple` paired with `createS3Handlers` from
+     * `@makolabs/ripple/server`, but any class implementing `StorageAdapter`
+     * works (Google Drive adapter ships too).
+     *
+     * @example
+     * ```svelte
+     * <script>
+     *   import { FileBrowser, S3Adapter } from '@makolabs/ripple';
+     *   const adapter = new S3Adapter({ basePath: '/' });
+     * </script>
+     * <FileBrowser {adapter} />
+     * ```
+     */
     adapter: StorageAdapter;
+    /**
+     * Initial path/prefix the browser opens at. For S3, this is a key prefix
+     * like `'imports/2025/'`. @default '' (adapter's root)
+     */
     startPath?: string;
+    /**
+     * Per-file or batch actions shown in the row menu / selection toolbar.
+     * Each entry is either `FileActionSingle` (one file) or `FileActionBatch`
+     * (multi-select). `isAllowed` gates visibility per row/selection.
+     */
     actions?: FileAction[];
     /**
      * Bindable list of selected files as full FileItem objects. Consumers
@@ -54,7 +108,7 @@ export interface FileBrowserProps {
     /** Tailwind height class for the browser container. @default 'h-[500px]' */
     height?: string;
     /** Additional CSS classes for the outer container. */
-    class?: string;
+    class?: ClassValue;
     /**
      * Custom sidebar snippet. When omitted, the FileBrowser renders a default
      * sidebar with Clear All, batch action buttons, and per-file status icons.

package/dist/button/Button.svelte

@@ -8,10 +8,10 @@
 	let {
 		variant = 'solid',
 		color = Color.DEFAULT,
-		size = Size.BASE,
-		rounded = 'base',
+		size = Size.MD,
+		rounded = 'md',
 		disabled = false,
-		isLoading = false,
+		loading = false,
 		class: className = '',
 		testId,
 		children,
@@ -25,7 +25,7 @@
 				color,
 				size,
 				rounded,
-				isLoading
+				loading
 			}),
 			{
 				'opacity-50 pointer-events-none cursor-not-allowed': disabled
@@ -45,7 +45,7 @@
 	<button
 		class={buttonClasses}
 		data-testid={buildTestId('button', undefined, testId)}
-		disabled={disabled || isLoading}
+		disabled={disabled || loading}
 		{...restProps}
 	>
 		{#if children}

package/dist/button/button-types.d.ts

@@ -1,25 +1,70 @@
 import type { ClassValue } from 'tailwind-variants';
 import type { Snippet } from 'svelte';
 import type { HTMLButtonAttributes, HTMLAttributeAnchorTarget } from 'svelte/elements';
-import type { VariantColors, VariantSizes } from '../index.js';
+import type { RoundedSizes, VariantColors, VariantSizes } from '../index.js';
+/**
+ * Shared props for `<Button>` regardless of whether it renders as a
+ * `<button>` or `<a>`. Combine with one of `ButtonHTMLProps` /
+ * `AnchorHTMLProps` via the `ButtonProps` discriminated union — setting
+ * `href` switches to anchor mode.
+ *
+ * @example
+ * ```svelte
+ * <Button color="primary" onclick={save}>Save</Button>
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- Renders as <a> when href is set -->
+ * <Button href="/settings" variant="link">Settings</Button>
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- Async handler with loading state -->
+ * <Button {loading} onclick={async () => { loading = true; await save(); loading = false; }}>
+ *   Save
+ * </Button>
+ * ```
+ */
 export type BaseButtonProps = {
     class?: ClassValue;
+    /**
+     * Visual weight:
+     * - `'solid'` (default) — filled background
+     * - `'outline'` — transparent bg + border
+     * - `'ghost'` — transparent bg + hover tint, no border
+     * - `'link'` — text-only, looks like an underlined link
+     */
     variant?: 'solid' | 'outline' | 'ghost' | 'link';
+    /** @default 'default' */
     color?: VariantColors;
     size?: VariantSizes;
-    rounded?: 'none' | 'xs' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | 'full';
-    disabled?: boolean | undefined | null;
-    isLoading?: boolean;
+    /** Corner radius scale. @default 'md' */
+    rounded?: RoundedSizes;
+    disabled?: boolean;
+    /** Show a loading animation and disable interaction. Async handlers pair well with this. @default false */
+    loading?: boolean;
+    /** Button content. */
     children?: Snippet;
     testId?: string;
 };
+/** Button-mode props: any `<button>` attribute is valid except `href`. */
 export type ButtonHTMLProps = {
     href?: never;
 } & HTMLButtonAttributes;
+/**
+ * Anchor-mode props: setting `href` switches the Button to render as
+ * `<a>` and exposes anchor-specific attributes (`target`, `rel`, etc.).
+ */
 export type AnchorHTMLProps = {
     rel?: string | undefined | null;
     target?: HTMLAttributeAnchorTarget | undefined | null;
     referrerpolicy?: 'no-referrer' | 'no-referrer-when-downgrade' | 'origin' | 'origin-when-cross-origin' | 'same-origin' | 'strict-origin' | 'strict-origin-when-cross-origin' | 'unsafe-url' | undefined | null;
     href: string;
 } & Record<string, unknown>;
+/**
+ * Full `<Button>` props. Discriminated by presence of `href` — with it,
+ * you get anchor attributes; without it, you get `<button>` attributes.
+ */
 export type ButtonProps = BaseButtonProps & (ButtonHTMLProps | AnchorHTMLProps);

package/dist/button/button.d.ts

@@ -17,7 +17,7 @@ export declare const buttonVariants: import("tailwind-variants").TVReturnType<{
     size: {
         xs: string;
         sm: string;
-        base: string;
+        md: string;
         lg: string;
         xl: string;
         "2xl": string;
@@ -26,13 +26,13 @@ export declare const buttonVariants: import("tailwind-variants").TVReturnType<{
         none: string;
         xs: string;
         sm: string;
-        base: string;
+        md: string;
         lg: string;
         xl: string;
         '2xl': string;
         full: string;
     };
-    isLoading: {
+    loading: {
         true: string;
     };
 }, undefined, "\n\t\tinline-flex items-center justify-center font-medium transition-colors focus-visible:outline-none\n\t\tfocus-visible:ring-2 focus-visible:ring-offset-2 cursor-pointer\n\t\t", {
@@ -54,7 +54,7 @@ export declare const buttonVariants: import("tailwind-variants").TVReturnType<{
     size: {
         xs: string;
         sm: string;
-        base: string;
+        md: string;
         lg: string;
         xl: string;
         "2xl": string;
@@ -63,13 +63,13 @@ export declare const buttonVariants: import("tailwind-variants").TVReturnType<{
         none: string;
         xs: string;
         sm: string;
-        base: string;
+        md: string;
         lg: string;
         xl: string;
         '2xl': string;
         full: string;
     };
-    isLoading: {
+    loading: {
         true: string;
     };
 }, undefined, import("tailwind-variants").TVReturnType<{
@@ -91,7 +91,7 @@ export declare const buttonVariants: import("tailwind-variants").TVReturnType<{
     size: {
         xs: string;
         sm: string;
-        base: string;
+        md: string;
         lg: string;
         xl: string;
         "2xl": string;
@@ -100,13 +100,13 @@ export declare const buttonVariants: import("tailwind-variants").TVReturnType<{
         none: string;
         xs: string;
         sm: string;
-        base: string;
+        md: string;
         lg: string;
         xl: string;
         '2xl': string;
         full: string;
     };
-    isLoading: {
+    loading: {
         true: string;
     };
 }, undefined, "\n\t\tinline-flex items-center justify-center font-medium transition-colors focus-visible:outline-none\n\t\tfocus-visible:ring-2 focus-visible:ring-offset-2 cursor-pointer\n\t\t", unknown, unknown, undefined>>;

package/dist/button/button.js

@@ -24,7 +24,7 @@ export const buttonVariants = tv({
         size: {
             [Size.XS]: 'h-7 px-2 text-xs',
             [Size.SM]: 'h-8 px-3 text-sm',
-            [Size.BASE]: 'h-9 px-4 text-sm',
+            [Size.MD]: 'h-9 px-4 text-sm',
             [Size.LG]: 'h-10 px-5 text-base',
             [Size.XL]: 'h-12 px-6 text-lg',
             [Size.XXL]: 'h-14 px-8 text-xl'
@@ -33,13 +33,13 @@ export const buttonVariants = tv({
             none: 'rounded-none',
             xs: 'rounded-xs',
             sm: 'rounded-sm',
-            base: 'rounded-md',
+            md: 'rounded-md',
             lg: 'rounded-lg',
             xl: 'rounded-xl',
             '2xl': 'rounded-2xl',
             full: 'rounded-full'
         },
-        isLoading: {
+        loading: {
             true: 'animate-pulse'
         }
     },
@@ -161,8 +161,8 @@ export const buttonVariants = tv({
     defaultVariants: {
         variant: 'solid',
         color: 'default',
-        size: 'base',
-        rounded: 'base',
-        isLoading: false
+        size: 'md',
+        rounded: 'md',
+        loading: false
     }
 });