@makolabs/ripple 2.5.9 → 3.0.0

package/dist/user-management/user-management-types.d.ts

@@ -1,23 +1,37 @@
 import type { ClassValue } from 'tailwind-variants';
+/** Args passed to `UserManagementAdapter.getUsers`. */
 export interface GetUsersOptions {
+    /** 1-indexed page number. */
     page: number;
+    /** Rows per page. */
     pageSize: number;
+    /** Field to sort by. Adapter-specific. */
     sortBy?: string;
     sortOrder?: 'asc' | 'desc';
+    /** Free-text search query. */
     query?: string;
 }
+/** Result returned by `UserManagementAdapter.getUsers`. */
 export interface GetUsersResult {
     users: User[];
+    /** Total count across all pages — used for pagination. */
     totalUsers: number;
 }
+/** A single email address attached to a user. */
 export interface UserEmail {
     email_address: string;
     verified?: boolean;
 }
+/** A single phone number attached to a user. */
 export interface UserPhone {
     phone_number: string;
     verified?: boolean;
 }
+/**
+ * User shape consumed by `<UserManagement>` and friends. Field naming
+ * mirrors common identity providers (Clerk, Stytch) — adapt your adapter
+ * to map your backend's shape to this one.
+ */
 export interface User {
     id: string;
     first_name?: string;
@@ -30,69 +44,125 @@ export interface User {
     last_sign_in_at?: number;
     private_metadata?: Record<string, unknown>;
     public_metadata?: Record<string, unknown>;
+    /** Permission keys the user has been granted. */
     permissions?: string[];
+    /** Role identifier (matches `Role.value`). */
     role?: string;
 }
+/** A single permission flag the system recognises. */
 export interface Permission {
     id: string;
     name: string;
     description?: string;
+    /** Logical grouping (rendered as a section header in the UI). */
     category?: string;
 }
+/** A role bundles a set of permissions under a single label. */
 export interface Role {
     value: string;
     label: string;
     description?: string;
+    /** Permission keys this role grants. */
     permissions: string[];
 }
+/**
+ * Props for `<UserTable>` — a paginated, sortable, action-aware table
+ * of users. Usually consumed via the higher-level `<UserManagement>`
+ * dashboard, but exposed for custom layouts.
+ */
 export interface UserTableProps {
     users: User[];
     loading?: boolean;
     currentPage?: number;
     pageSize?: number;
     totalUsers?: number;
-    onPageChange: (page: number) => void;
-    onPageSizeChange: (size: number) => void;
-    onSort?: (state: {
+    onpagechange: (page: number) => void;
+    onpagesizechange: (size: number) => void;
+    onsort?: (state: {
         column: string | null;
         direction: 'asc' | 'desc' | null;
     }) => void;
-    onView: (user: User) => void;
-    onEdit: (user: User) => void;
-    onDelete: (userId: string) => void;
+    /** Fires when the user clicks the View action on a row. */
+    onview: (user: User) => void;
+    /** Fires when the user clicks the Edit action on a row. */
+    onedit: (user: User) => void;
+    /** Fires when the user confirms a Delete action on a row. */
+    ondelete: (userId: string) => void;
     class?: ClassValue;
     testId?: string;
 }
+/**
+ * Payload for `UserModalProps.onsave`. Discriminated by `mode` so
+ * create-mode consumers don't have to invent a fake `id`.
+ */
+export type UserModalSavePayload = {
+    mode: 'create';
+    user: Omit<User, 'id'>;
+} | {
+    mode: 'edit';
+    user: User;
+};
+/**
+ * Props for `<UserModal>` — the create/edit user form. Wraps `<Modal>`
+ * with role + permission selection + validation.
+ */
 export interface UserModalProps {
     open?: boolean;
+    /** User being edited. Pass `null`/`undefined` to create a new one. */
     user?: User | null;
     roles?: Role[];
+    /** Adapter for permission lookups (only the permission-related methods are used). */
     adapter?: UserManagementAdapter;
+    /** True while the parent is fetching the user's permission set. */
     loadingPermissions?: boolean;
-    onSave: (user: User, mode: 'create' | 'edit') => void | Promise<void>;
-    onClose?: () => void;
+    /**
+     * Fires when the form is submitted. Return a promise to keep the modal
+     * open during save. Payload is discriminated by `mode` — create-mode
+     * payloads carry an `Omit<User, 'id'>` so you don't have to invent an id.
+     */
+    onsave: (payload: UserModalSavePayload) => void | Promise<void>;
+    onclose?: () => void;
     class?: ClassValue;
     testId?: string;
 }
+/**
+ * Props for `<UserViewModal>` — read-only user details panel with
+ * optional Edit button and API key regeneration affordance.
+ */
 export interface UserViewModalProps {
     open?: boolean;
     user: User | null;
     permissions?: Permission[];
     roles?: Role[];
-    onEdit?: (user: User) => void;
-    onRegenerateApiKey?: (userId: string) => Promise<void>;
-    onClose: () => void;
+    /** When provided, an Edit button appears that calls this. */
+    onedit?: (user: User) => void;
+    /** When provided, a "Regenerate API key" button appears. Async. */
+    onregenerateapikey?: (userId: string) => Promise<void>;
+    onclose: () => void;
     class?: ClassValue;
     testId?: string;
 }
 /**
- * User Management Adapter Interface
+ * Adapter contract for `<UserManagement>` and its subcomponents. The
+ * adapter wires the UI to your backend — every method can be a
+ * SvelteKit remote function (`query`/`command`) or a plain async
+ * function. `PromiseLike` accepts both.
  *
- * Defines the contract for user management adapters.
- * Adapters can be remote function modules (returning RemoteQuery/RemoteCommand)
- * or regular async function modules (returning Promise).
+ * @example
+ * ```ts
+ * // src/lib/users/adapter.remote.ts
+ * import { query, command } from '$app/server';
  *
- * Uses PromiseLike to accept both Promise and RemoteQuery/RemoteCommand types.
+ * export const getUsers = query(async ({ page, pageSize }) => {
+ *   const users = await db.users.list({ page, pageSize });
+ *   return { users, totalUsers: await db.users.count() };
+ * });
+ * // …createUser, updateUser, etc.
+ *
+ * // src/routes/+page.svelte
+ * import * as adapter from '../users/adapter.remote';
+ * <UserManagement {adapter} {roles} />
+ * ```
  */
 export interface UserManagementAdapter {
     getUsers: (options: GetUsersOptions) => PromiseLike<GetUsersResult>;
@@ -108,6 +178,10 @@ export interface UserManagementAdapter {
         userId: string;
         permissions: string[];
     }) => PromiseLike<void>;
+    /**
+     * Optional — present only on adapters that issue API keys. When set,
+     * the UserViewModal renders a "Regenerate API key" button.
+     */
     generateApiKey?: (options: {
         userId: string;
         permissions: string[];
@@ -118,6 +192,7 @@ export interface UserManagementAdapter {
         message: string;
         verificationWarning?: string;
     }>;
+    /** Optional — used by the API-key panel to verify scopes after regeneration. */
     verifyToken?: (options: {
         apiKey: string;
     }) => PromiseLike<{
@@ -127,30 +202,42 @@ export interface UserManagementAdapter {
         token?: string;
     }>;
 }
+/**
+ * Props for `<UserManagement>` — the all-in-one user dashboard
+ * combining table, search, filters, create/edit/view modals, and
+ * permission management. Pass an adapter and a list of roles; the
+ * component handles the rest.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { UserManagement } from '@makolabs/ripple';
+ *   import * as adapter from '../users/adapter.remote';
+ *
+ *   const roles = [
+ *     { value: 'admin', label: 'Admin', permissions: ['read', 'write', 'delete'] },
+ *     { value: 'viewer', label: 'Viewer', permissions: ['read'] }
+ *   ];
+ * </script>
+ *
+ * <UserManagement {adapter} {roles} />
+ * ```
+ */
 export interface UserManagementProps {
     /**
-     * Adapter module containing remote functions or async functions
-     * Should be imported from a .remote.ts file
-     * If not provided, uses the default adapter from @makolabs/ripple
-     *
-     * Example:
-     * ```ts
-     * import * as adapter from './adapter.remote';
-     * <UserManagement adapter={adapter} roles={roles} />
-     * ```
+     * Adapter module containing remote functions or async functions.
+     * Should be imported from a `.remote.ts` file (SvelteKit remote
+     * functions) or a plain `.ts` module of async functions.
      */
     adapter: UserManagementAdapter;
-    /**
-     * Available roles for user assignment
-     */
+    /** Available roles for user assignment. */
     roles?: Role[];
-    /**
-     * Available permissions for display (optional)
-     */
+    /** Available permissions for display (optional). */
     permissions?: Permission[];
     class?: ClassValue;
     testId?: string;
 }
+/** Map of field name → error message for in-form validation errors. */
 export interface FormErrors {
     [key: string]: string;
 }

package/dist/variants.d.ts

@@ -11,7 +11,7 @@ export declare const Color: {
 export declare const Size: {
     readonly XS: "xs";
     readonly SM: "sm";
-    readonly BASE: "base";
+    readonly MD: "md";
     readonly LG: "lg";
     readonly XL: "xl";
     readonly XXL: "2xl";

package/dist/variants.js

@@ -10,7 +10,7 @@ export const Color = {
 export const Size = {
     XS: 'xs',
     SM: 'sm',
-    BASE: 'base',
+    MD: 'md',
     LG: 'lg',
     XL: 'xl',
     XXL: '2xl'

package/package.json

@@ -1,11 +1,11 @@
 {
 	"name": "@makolabs/ripple",
-	"version": "2.5.9",
+	"version": "3.0.0",
 	"description": "Simple Svelte 5 powered component library ✨",
 	"license": "SEE LICENSE IN LICENSE",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/makolabsai/ripple-ui.git"
+		"url": "git+https://github.com/makolabsai/ripple-ui.git"
 	},
 	"scripts": {
 		"dev": "vite dev",
@@ -29,7 +29,9 @@
 	"files": [
 		"dist",
 		"!dist/**/*.test.*",
-		"!dist/**/*.spec.*"
+		"!dist/**/*.spec.*",
+		"!dist/**/*TestWrapper.svelte",
+		"!dist/**/*TestWrapper.svelte.d.ts"
 	],
 	"sideEffects": [
 		"**/*.css"
@@ -52,7 +54,8 @@
 		}
 	},
 	"peerDependencies": {
-		"svelte": "^5.0.0 || ^6.0.0"
+		"svelte": "^5.0.0 || ^6.0.0",
+		"@sveltejs/kit": "^2.0.0"
 	},
 	"devDependencies": {
 		"@eslint/compat": "^1.4.1",

package/dist/config/ai.d.ts

@@ -1,13 +0,0 @@
-export interface AIConfig {
-    provider: 'openai' | 'anthropic' | 'ollama';
-    apiKey?: string;
-    model?: string;
-    baseUrl?: string;
-}
-export declare function getAIConfig(): AIConfig;
-export declare function validateAIConfig(config: AIConfig): boolean;
-export declare const ENV_GUIDE: {
-    openai: string[];
-    anthropic: string[];
-    ollama: string[];
-};

package/dist/config/ai.js

@@ -1,44 +0,0 @@
-import { browser } from '$app/environment';
-import { dev } from '$app/environment';
-export function getAIConfig() {
-    if (!browser) {
-        return {
-            provider: 'openai'
-        };
-    }
-    const config = {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        provider: import.meta.env.VITE_AI_PROVIDER || 'openai',
-        apiKey: import.meta.env.VITE_OPENAI_API_KEY,
-        model: import.meta.env.VITE_OPENAI_MODEL || 'gpt-4-turbo-preview',
-        baseUrl: import.meta.env.VITE_OPENAI_BASE_URL || 'https://api.openai.com/v1'
-    };
-    // In development, provide helpful warnings
-    if (dev && !config.apiKey && config.provider === 'openai') {
-        console.warn('⚠️ OpenAI API key not found. Set VITE_OPENAI_API_KEY in your .env file');
-        console.warn('💡 Create a .env file with: VITE_OPENAI_API_KEY=sk-your-key-here');
-    }
-    return config;
-}
-export function validateAIConfig(config) {
-    switch (config.provider) {
-        case 'openai':
-            return !!config.apiKey;
-        case 'anthropic':
-            return !!config.apiKey;
-        case 'ollama':
-            return !!config.baseUrl;
-        default:
-            return false;
-    }
-}
-// Environment variables guide
-export const ENV_GUIDE = {
-    openai: [
-        'VITE_OPENAI_API_KEY=sk-your-openai-key',
-        'VITE_OPENAI_MODEL=gpt-4-turbo-preview (optional)',
-        'VITE_OPENAI_BASE_URL=https://api.openai.com/v1 (optional)'
-    ],
-    anthropic: ['VITE_ANTHROPIC_API_KEY=your-anthropic-key', 'VITE_AI_PROVIDER=anthropic'],
-    ollama: ['VITE_OLLAMA_BASE_URL=http://localhost:11434', 'VITE_AI_PROVIDER=ollama']
-};

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

@@ -1,25 +0,0 @@
-<script lang="ts">
-	import EmptyState from './EmptyState.svelte';
-	import type { EmptyStateProps } from '../../index.js';
-
-	type Props = Omit<EmptyStateProps, 'icon' | 'action'> & {
-		iconText?: string;
-		actionText?: string;
-	};
-
-	let { iconText, actionText, ...rest }: Props = $props();
-</script>
-
-{#snippet iconSnippet()}
-	<span data-testid="wrapper-icon">{iconText}</span>
-{/snippet}
-
-{#snippet actionSnippet()}
-	<button type="button" data-testid="wrapper-action">{actionText}</button>
-{/snippet}
-
-<EmptyState
-	{...rest}
-	icon={iconText ? iconSnippet : undefined}
-	action={actionText ? actionSnippet : undefined}
-/>

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

@@ -1,8 +0,0 @@
-import type { EmptyStateProps } from '../../index.js';
-type Props = Omit<EmptyStateProps, 'icon' | 'action'> & {
-    iconText?: string;
-    actionText?: string;
-};
-declare const EmptyStateTestWrapper: import("svelte").Component<Props, {}, "">;
-type EmptyStateTestWrapper = ReturnType<typeof EmptyStateTestWrapper>;
-export default EmptyStateTestWrapper;

package/dist/elements/tooltip/TooltipTestWrapper.svelte

@@ -1,14 +0,0 @@
-<script lang="ts">
-	import Tooltip from './Tooltip.svelte';
-	import type { TooltipProps } from '../../index.js';
-
-	type Props = Omit<TooltipProps, 'children'> & {
-		triggerText?: string;
-	};
-
-	let { triggerText = 'trigger', ...rest }: Props = $props();
-</script>
-
-<Tooltip {...rest}>
-	<button type="button">{triggerText}</button>
-</Tooltip>

package/dist/elements/tooltip/TooltipTestWrapper.svelte.d.ts

@@ -1,7 +0,0 @@
-import type { TooltipProps } from '../../index.js';
-type Props = Omit<TooltipProps, 'children'> & {
-    triggerText?: string;
-};
-declare const TooltipTestWrapper: import("svelte").Component<Props, {}, "">;
-type TooltipTestWrapper = ReturnType<typeof TooltipTestWrapper>;
-export default TooltipTestWrapper;

package/dist/helper/deprecation.d.ts

@@ -1,14 +0,0 @@
-/**
- * Logs a console.warn once per component+prop combination when a deprecated prop is used.
- * @param component - Component name (e.g. 'Modal', 'Card')
- * @param props - The raw props object from $props()
- * @param map - Map of deprecated prop names to their replacements (e.g. { titleclass: 'titleClass' })
- */
-export declare function warnDeprecatedProps(component: string, props: Record<string, unknown>, map: Record<string, string>): void;
-/**
- * Reset warnings — only for testing.
- * Note: In SSR, the warned Set persists across requests within the same process,
- * so warnings will only fire once per server lifetime. This is acceptable for
- * development-time deprecation notices.
- */
-export declare function resetDeprecationWarnings(): void;

package/dist/helper/deprecation.js

@@ -1,24 +0,0 @@
-const warned = new Set();
-/**
- * Logs a console.warn once per component+prop combination when a deprecated prop is used.
- * @param component - Component name (e.g. 'Modal', 'Card')
- * @param props - The raw props object from $props()
- * @param map - Map of deprecated prop names to their replacements (e.g. { titleclass: 'titleClass' })
- */
-export function warnDeprecatedProps(component, props, map) {
-    for (const [oldName, newName] of Object.entries(map)) {
-        if (props[oldName] !== undefined && !warned.has(`${component}.${oldName}`)) {
-            warned.add(`${component}.${oldName}`);
-            console.warn(`[ripple-ui] ${component}: "${oldName}" is deprecated, use "${newName}" instead.`);
-        }
-    }
-}
-/**
- * Reset warnings — only for testing.
- * Note: In SSR, the warned Set persists across requests within the same process,
- * so warnings will only fire once per server lifetime. This is acceptable for
- * development-time deprecation notices.
- */
-export function resetDeprecationWarnings() {
-    warned.clear();
-}

package/dist/modal/ModalFooterTestWrapper.svelte

@@ -1,17 +0,0 @@
-<script lang="ts">
-	import ModalFooter from './ModalFooter.svelte';
-
-	let {
-		text = '',
-		align,
-		class: className
-	}: {
-		text?: string;
-		align?: 'start' | 'center' | 'end' | 'between';
-		class?: string;
-	} = $props();
-</script>
-
-<ModalFooter {align} class={className}>
-	<button type="button">{text}</button>
-</ModalFooter>

package/dist/modal/ModalFooterTestWrapper.svelte.d.ts

@@ -1,8 +0,0 @@
-type $$ComponentProps = {
-    text?: string;
-    align?: 'start' | 'center' | 'end' | 'between';
-    class?: string;
-};
-declare const ModalFooterTestWrapper: import("svelte").Component<$$ComponentProps, {}, "">;
-type ModalFooterTestWrapper = ReturnType<typeof ModalFooterTestWrapper>;
-export default ModalFooterTestWrapper;