@makolabs/ripple 1.2.2 → 1.2.4

package/dist/user-management/README.md

@@ -0,0 +1,417 @@
+# User Management Module
+
+A comprehensive, self-contained user management system built with Svelte 5 and TypeScript. This module provides all the components needed to build a complete user management interface with CRUD operations, role management, and permissions.
+
+## Features
+
+- 📊 **User Table**: Fully-featured data table with sorting, pagination, and search
+- ✏️ **User Modal**: Create and edit users with role and permission management
+- 👁️ **User View Modal**: View detailed user information in a read-only modal
+- 🎯 **User Management**: Complete orchestrator component that combines all features
+- 🔐 **Role-Based Access**: Built-in support for roles and permissions
+- 🎨 **Customizable**: All components accept custom classes and styling
+- ♿ **Accessible**: Built with accessibility in mind
+- 📱 **Responsive**: Works seamlessly on all screen sizes
+- 🧪 **Well-Tested**: Comprehensive test suite included
+- 📖 **Storybook Ready**: Full Storybook stories for all components
+
+## Installation
+
+The user management module is included in `@makolabs/ripple`. Simply import the components you need:
+
+```typescript
+import { UserManagement, UserTable, UserModal, UserViewModal } from '@makolabs/ripple';
+```
+
+## Components
+
+### UserManagement
+
+The main orchestrator component that combines all user management functionality.
+
+```svelte
+<script lang="ts">
+	import { UserManagement } from '@makolabs/ripple';
+	import type { User } from '@makolabs/ripple';
+
+	let users = $state<User[]>([
+		/* your users */
+	]);
+	let totalUsers = $state(100);
+	let currentPage = $state(1);
+	let pageSize = $state(10);
+
+	const roles = [
+		{
+			value: 'admin',
+			label: 'Administrator',
+			description: 'Full access',
+			permissions: ['read', 'write', 'delete']
+		},
+		{
+			value: 'user',
+			label: 'User',
+			description: 'Basic access',
+			permissions: ['read']
+		}
+	];
+
+	async function handleCreateUser(userData: Partial<User>) {
+		// Your create logic
+		console.log('Creating user:', userData);
+	}
+
+	async function handleUpdateUser(userId: string, userData: Partial<User>) {
+		// Your update logic
+		console.log('Updating user:', userId, userData);
+	}
+
+	async function handleDeleteUser(userId: string) {
+		// Your delete logic
+		console.log('Deleting user:', userId);
+	}
+</script>
+
+<UserManagement
+	{users}
+	{totalUsers}
+	{currentPage}
+	{pageSize}
+	{roles}
+	onPageChange={(page) => (currentPage = page)}
+	onPageSizeChange={(size) => (pageSize = size)}
+	onCreateUser={handleCreateUser}
+	onUpdateUser={handleUpdateUser}
+	onDeleteUser={handleDeleteUser}
+/>
+```
+
+### UserTable
+
+Display users in a sortable, paginated table.
+
+```svelte
+<script lang="ts">
+	import { UserTable } from '@makolabs/ripple';
+	import type { User } from '@makolabs/ripple';
+
+	let users = $state<User[]>([
+		/* your users */
+	]);
+
+	function handleView(user: User) {
+		console.log('View user:', user);
+	}
+
+	function handleEdit(user: User) {
+		console.log('Edit user:', user);
+	}
+
+	function handleDelete(userId: string) {
+		console.log('Delete user:', userId);
+	}
+</script>
+
+<UserTable
+	{users}
+	totalUsers={100}
+	currentPage={1}
+	pageSize={10}
+	onPageChange={(page) => console.log('Page:', page)}
+	onPageSizeChange={(size) => console.log('Size:', size)}
+	onView={handleView}
+	onEdit={handleEdit}
+	onDelete={handleDelete}
+/>
+```
+
+### UserModal
+
+Create or edit users with role and permission selection.
+
+```svelte
+<script lang="ts">
+	import { UserModal } from '@makolabs/ripple';
+	import type { User, Role } from '@makolabs/ripple';
+
+	let open = $state(false);
+	let selectedUser = $state<User | null>(null);
+
+	const roles: Role[] = [
+		{
+			value: 'admin',
+			label: 'Administrator',
+			description: 'Full access',
+			permissions: ['read', 'write', 'delete']
+		}
+	];
+
+	async function handleSave(user: User, mode: 'create' | 'edit') {
+		console.log('Save user:', user, 'Mode:', mode);
+		// Your save logic here
+		open = false;
+	}
+</script>
+
+<button onclick={() => (open = true)}>Open Modal</button>
+
+<UserModal
+	bind:open
+	bind:user={selectedUser}
+	{roles}
+	onSave={handleSave}
+	onClose={() => (open = false)}
+/>
+```
+
+### UserViewModal
+
+View user details in a read-only modal with tabs for profile and permissions.
+
+```svelte
+<script lang="ts">
+	import { UserViewModal } from '@makolabs/ripple';
+	import type { User } from '@makolabs/ripple';
+
+	let open = $state(false);
+	let selectedUser = $state<User | null>(null);
+
+	function handleEdit(user: User) {
+		console.log('Edit user:', user);
+		open = false;
+	}
+</script>
+
+<UserViewModal
+	bind:open
+	bind:user={selectedUser}
+	onEdit={handleEdit}
+	onClose={() => (open = false)}
+/>
+```
+
+## TypeScript Types
+
+### User
+
+```typescript
+interface User {
+	id: string;
+	first_name?: string;
+	last_name?: string;
+	username?: string;
+	email_addresses?: UserEmail[];
+	phone_numbers?: UserPhone[];
+	image_url?: string;
+	created_at?: number;
+	last_sign_in_at?: number;
+	private_metadata?: Record<string, any>;
+	public_metadata?: Record<string, any>;
+	permissions?: string[];
+	role?: string;
+}
+```
+
+### Role
+
+```typescript
+interface Role {
+	value: string;
+	label: string;
+	description?: string;
+	permissions: string[];
+}
+```
+
+### Permission
+
+```typescript
+interface Permission {
+	id: string;
+	name: string;
+	description?: string;
+	category?: string;
+}
+```
+
+## Utility Functions
+
+### createUser
+
+Create a user object with default values:
+
+```typescript
+import { createUser } from '@makolabs/ripple';
+
+const newUser = createUser({
+	first_name: 'John',
+	last_name: 'Doe',
+	email_addresses: [{ email_address: 'john@example.com' }]
+});
+```
+
+### getUserDisplayName
+
+Get a user's display name:
+
+```typescript
+import { getUserDisplayName } from '@makolabs/ripple';
+
+const displayName = getUserDisplayName(user);
+// Returns: "John Doe" or username or email or ID
+```
+
+### getUserInitials
+
+Get a user's initials for avatars:
+
+```typescript
+import { getUserInitials } from '@makolabs/ripple';
+
+const initials = getUserInitials(user);
+// Returns: "J" or "?" if no name
+```
+
+## Styling
+
+All components accept a `class` prop for custom styling:
+
+```svelte
+<UserManagement
+	class="my-custom-class"
+	{users}
+	{totalUsers}
+	{currentPage}
+	{pageSize}
+	onPageChange={handlePageChange}
+	onPageSizeChange={handlePageSizeChange}
+/>
+```
+
+Components use Tailwind CSS classes by default, but you can override them with your own styles.
+
+## Data Flow
+
+The user management module is designed to be **data-driven** and **framework-agnostic**. It doesn't make any API calls directly. Instead, you provide the data and handle the API calls:
+
+```svelte
+<script lang="ts">
+	import { UserManagement } from '@makolabs/ripple';
+	import type { User } from '@makolabs/ripple';
+
+	// Your data source
+	let users = $state<User[]>([]);
+	let totalUsers = $state(0);
+	let currentPage = $state(1);
+	let pageSize = $state(10);
+	let loading = $state(false);
+
+	// Fetch users when page or size changes
+	$effect(() => {
+		loadUsers();
+	});
+
+	async function loadUsers() {
+		loading = true;
+		try {
+			const response = await fetch(`/api/users?page=${currentPage}&size=${pageSize}`);
+			const data = await response.json();
+			users = data.users;
+			totalUsers = data.total;
+		} catch (error) {
+			console.error('Failed to load users:', error);
+		} finally {
+			loading = false;
+		}
+	}
+
+	async function handleCreateUser(userData: Partial<User>) {
+		const response = await fetch('/api/users', {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify(userData)
+		});
+		if (response.ok) {
+			await loadUsers(); // Reload the list
+		}
+	}
+
+	// Similar handlers for update, delete, etc.
+</script>
+
+<UserManagement
+	{users}
+	{totalUsers}
+	{loading}
+	{currentPage}
+	{pageSize}
+	onPageChange={(page) => (currentPage = page)}
+	onPageSizeChange={(size) => {
+		pageSize = size;
+		currentPage = 1;
+	}}
+	onCreateUser={handleCreateUser}
+	onUpdateUser={handleUpdateUser}
+	onDeleteUser={handleDeleteUser}
+/>
+```
+
+## Examples
+
+Check out the Storybook stories for interactive examples:
+
+```bash
+npm run storybook
+```
+
+Then navigate to:
+
+- **User Management > User Management** - Full user management interface
+- **User Management > User Table** - Table component examples
+- **User Management > User Modal** - Modal component examples (if available)
+- **User Management > User View Modal** - View modal examples (if available)
+
+## Testing
+
+Run the test suite:
+
+```bash
+npm run test:unit
+```
+
+Tests are located in:
+
+- `UserTable.svelte.test.ts`
+- `UserModal.svelte.test.ts`
+- (Additional test files as needed)
+
+## Browser Support
+
+The user management module supports all modern browsers:
+
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+- Mobile browsers (iOS Safari, Chrome Mobile)
+
+## Accessibility
+
+All components are built with accessibility in mind:
+
+- ✅ Keyboard navigation
+- ✅ ARIA labels and roles
+- ✅ Screen reader support
+- ✅ Focus management
+- ✅ Semantic HTML
+
+## License
+
+Part of `@makolabs/ripple` - see main package for license information.
+
+## Contributing
+
+Contributions are welcome! Please see the main repository for contribution guidelines.
+
+## Support
+
+For issues, questions, or feature requests, please open an issue on the main repository.

package/dist/user-management/UserManagement.svelte

@@ -0,0 +1,184 @@
+<script lang="ts">
+	import { PageHeader, MetricCard, Button, cn } from '../index.js';
+	import UserTable from './UserTable.svelte';
+	import UserModal from './UserModal.svelte';
+	import UserViewModal from './UserViewModal.svelte';
+	import type { User, UserManagementProps } from './user-management.js';
+	import { SvelteSet } from 'svelte/reactivity';
+
+	let {
+		users = [],
+		totalUsers = 0,
+		loading = false,
+		currentPage = 1,
+		pageSize = 10,
+		roles = [],
+		permissions = [],
+		onPageChange,
+		onPageSizeChange,
+		onSort,
+		onCreateUser,
+		onUpdateUser,
+		onDeleteUser,
+		onDeleteUsers,
+		class: className
+	}: UserManagementProps = $props();
+
+	// Modal states
+	let showEditCreateModal = $state(false);
+	let showViewModal = $state(false);
+	let selectedUser = $state<User | null>(null);
+
+	// Bulk action states
+	let selectedUsers = new SvelteSet<string>();
+	let bulkAction = $state<'delete' | ''>('');
+
+	// Derived states
+	const hasSelectedUsers = $derived(selectedUsers.size > 0);
+	const activeUsers = $derived(users.filter((u) => !!u.id));
+
+	// Modal handlers
+	function openViewModal(user: User) {
+		selectedUser = user;
+		showViewModal = true;
+	}
+
+	function openEditModal(user: User) {
+		selectedUser = user;
+		showEditCreateModal = true;
+	}
+
+	function openCreateModal() {
+		selectedUser = null;
+		showEditCreateModal = true;
+	}
+
+	function handleEditFromView() {
+		showViewModal = false;
+		if (selectedUser) {
+			openEditModal(selectedUser);
+		}
+	}
+
+	// Save handlers
+	async function handleUserSave(user: User, mode: 'create' | 'edit') {
+		if (mode === 'create' && onCreateUser) {
+			await onCreateUser(user);
+		} else if (mode === 'edit' && onUpdateUser) {
+			await onUpdateUser(user.id, user);
+		}
+	}
+
+	// Delete handlers
+	async function handleDeleteUser(userId: string) {
+		if (!confirm('Are you sure you want to delete this user? This action cannot be undone.')) {
+			return;
+		}
+		if (onDeleteUser) {
+			await onDeleteUser(userId);
+		}
+	}
+
+	// Bulk actions
+	async function executeBulkAction() {
+		if (!bulkAction || selectedUsers.size === 0) return;
+
+		const userIds = Array.from(selectedUsers);
+
+		if (!confirm(`Are you sure you want to ${bulkAction} ${userIds.length} user(s)?`)) {
+			return;
+		}
+
+		if (bulkAction === 'delete' && onDeleteUsers) {
+			await onDeleteUsers(userIds);
+			selectedUsers.clear();
+			selectedUsers = new SvelteSet(selectedUsers);
+			bulkAction = '';
+		}
+	}
+</script>
+
+{#snippet PlusIcon()}
+	<svg class="mr-2 h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+		<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 4v16m8-8H4"></path>
+	</svg>
+{/snippet}
+
+<div class={cn(className)}>
+	<!-- Page Header -->
+	<PageHeader
+		title="User Management"
+		subtitle="Manage and monitor user accounts"
+		layout="horizontal"
+		class="mb-6"
+	>
+		<Button onclick={openCreateModal} color="primary" disabled={!onCreateUser}>
+			{@render PlusIcon()}
+			Add User
+		</Button>
+	</PageHeader>
+
+	<!-- Stats Cards -->
+	<div class="mb-8 grid grid-cols-1 gap-6 md:grid-cols-2">
+		<MetricCard title="Total Users" value={totalUsers.toLocaleString()} />
+		<MetricCard title="Active Users" value={activeUsers.length.toLocaleString()} />
+	</div>
+
+	<!-- Bulk Actions Bar -->
+	{#if hasSelectedUsers}
+		<div
+			class="mb-4 flex flex-wrap items-center justify-between gap-3 rounded-lg border border-amber-200 bg-amber-50 p-4"
+		>
+			<div class="flex items-center">
+				<span class="text-sm font-medium text-amber-900">
+					{selectedUsers.size} user{selectedUsers.size === 1 ? '' : 's'} selected
+				</span>
+			</div>
+			<div class="flex items-center gap-2">
+				<select
+					bind:value={bulkAction}
+					class="rounded-md border-amber-300 text-sm focus:border-amber-500 focus:ring-amber-500"
+				>
+					<option value="">Select Action</option>
+					<option value="delete">Delete Selected</option>
+				</select>
+				<Button onclick={executeBulkAction} disabled={!bulkAction} color="warning" size="sm">
+					Execute
+				</Button>
+			</div>
+		</div>
+	{/if}
+
+	<!-- Users Table Component -->
+	<UserTable
+		{users}
+		{loading}
+		{currentPage}
+		{pageSize}
+		{totalUsers}
+		{onPageChange}
+		{onPageSizeChange}
+		{onSort}
+		onView={openViewModal}
+		onEdit={openEditModal}
+		onDelete={handleDeleteUser}
+	/>
+
+	<!-- User View Modal -->
+	<UserViewModal
+		bind:open={showViewModal}
+		bind:user={selectedUser}
+		{permissions}
+		onEdit={handleEditFromView}
+		onClose={() => (selectedUser = null)}
+	/>
+
+	<!-- User Edit/Create Modal -->
+	<UserModal
+		bind:open={showEditCreateModal}
+		bind:user={selectedUser}
+		{roles}
+		onSave={handleUserSave}
+		onClose={() => (selectedUser = null)}
+	/>
+</div>

package/dist/user-management/UserManagement.svelte.d.ts

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

package/dist/user-management/UserManagementTestWrapper.svelte

@@ -0,0 +1,47 @@
+<script lang="ts">
+	import UserManagement from './UserManagement.svelte';
+	import type { UserManagementProps } from './user-management.js';
+
+	interface Props extends UserManagementProps {
+		testId?: string;
+	}
+
+	let {
+		users = [],
+		totalUsers = 0,
+		loading = false,
+		currentPage = 1,
+		pageSize = 10,
+		roles = [],
+		permissions = [],
+		onPageChange = () => {},
+		onPageSizeChange = () => {},
+		onSort,
+		onCreateUser,
+		onUpdateUser,
+		onDeleteUser,
+		onDeleteUsers,
+		testId,
+		...rest
+	}: Props = $props();
+</script>
+
+<div data-testid={testId}>
+	<UserManagement
+		{users}
+		{totalUsers}
+		{loading}
+		{currentPage}
+		{pageSize}
+		{roles}
+		{permissions}
+		{onPageChange}
+		{onPageSizeChange}
+		{onSort}
+		{onCreateUser}
+		{onUpdateUser}
+		{onDeleteUser}
+		{onDeleteUsers}
+		{...rest}
+	/>
+</div>

package/dist/user-management/UserManagementTestWrapper.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { UserManagementProps } from './user-management.js';
+interface Props extends UserManagementProps {
+    testId?: string;
+}
+declare const UserManagementTestWrapper: import("svelte").Component<Props, {}, "">;
+type UserManagementTestWrapper = ReturnType<typeof UserManagementTestWrapper>;
+export default UserManagementTestWrapper;