snice 4.9.0 → 4.10.0

package/docs/components/toast.md

@@ -1,506 +1,167 @@
-# Toast Components
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/toast.md instead)
 
-The toast notification system provides temporary, non-blocking messages to users. It consists of two components and a static API for programmatic toast creation.
+# Toast
+`<snice-toast-container>`
 
-## Table of Contents
-- [Components](#components)
-- [Basic Usage](#basic-usage)
-- [Static API](#static-api)
-- [Properties](#properties)
-- [Methods](#methods)
-- [Examples](#examples)
-
-## Components
-
-### `<snice-toast>`
-Individual toast notification element.
-
-### `<snice-toast-container>`
-Container that manages and positions multiple toast notifications.
+Temporary, non-blocking notification messages. Includes a static `Toast` API for programmatic creation.
 
 ## Basic Usage
 
-### Using the Static API (Recommended)
-
 ```typescript
 import Toast from 'snice/components/toast/snice-toast-container';
+```
 
-// Show different toast types
+```typescript
 Toast.success('Operation completed successfully!');
 Toast.error('An error occurred');
 Toast.warning('Please review your input');
 Toast.info('New update available');
-
-// With options
-Toast.show('Custom message', {
-  type: 'success',
-  duration: 5000,
-  position: 'top-right',
-  closable: true,
-  icon: true
-});
-```
-
-### Using Container Element
-
-```html
-<snice-toast-container id="toaster" position="bottom-center"></snice-toast-container>
-
-<script type="module">
-  import 'snice/components/toast/snice-toast-container';
-
-  const container = document.querySelector('#toaster');
-
-  // Show a toast
-  const id = container.show('Hello, world!', { type: 'success' });
-
-  // Hide specific toast
-  container.hide(id);
-
-  // Clear all toasts
-  container.clear();
-</script>
 ```
 
-## Static API
-
-### `Toast.show(message, options?): Promise<string>`
-Show a toast with any type.
+## Importing
 
+**ESM (bundler)**
 ```typescript
-const id = await Toast.show('Message', {
-  type: 'info',
-  duration: 4000,
-  position: 'bottom-center',
-  closable: true,
-  icon: true
-});
-```
-
-### `Toast.success(message, options?): Promise<string>`
-Show a success toast (green).
-
-```typescript
-await Toast.success('Profile updated successfully');
-```
-
-### `Toast.error(message, options?): Promise<string>`
-Show an error toast (red).
-
-```typescript
-await Toast.error('Failed to save changes');
-```
-
-### `Toast.warning(message, options?): Promise<string>`
-Show a warning toast (orange).
-
-```typescript
-await Toast.warning('Your session will expire soon');
+import Toast from 'snice/components/toast/snice-toast-container';
 ```
 
-### `Toast.info(message, options?): Promise<string>`
-Show an info toast (blue).
-
-```typescript
-await Toast.info('5 new messages');
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-toast-container.min.js"></script>
 ```
 
-### `Toast.hide(id: string): void`
-Hide a specific toast by its ID.
+## Examples
 
-```typescript
-const id = await Toast.show('Saving...');
-// Later...
-Toast.hide(id);
-```
+### Static API
 
-### `Toast.clear(): void`
-Clear all visible toasts.
+Use the static `Toast` class for the simplest usage. A container is created automatically.
 
 ```typescript
-Toast.clear();
+Toast.success('Profile updated');
+Toast.error('Failed to save changes');
+Toast.warning('Session expires soon');
+Toast.info('5 new messages');
 ```
 
-## Properties
-
-### Toast Container
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `position` | `ToastPosition` | `'bottom-center'` | Container position on screen |
-
-**ToastPosition:**
-- `'top-left'`
-- `'top-center'`
-- `'top-right'`
-- `'bottom-left'`
-- `'bottom-center'`
-- `'bottom-right'`
+### Custom Options
 
-### Individual Toast
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `type` | `ToastType` | `'info'` | Visual style of toast |
-| `message` | `string` | `''` | Toast message text |
-| `closable` | `boolean` | `true` | Show close button |
-| `icon` | `boolean` | `true` | Show type icon |
-
-**ToastType:**
-- `'success'` - Green, checkmark icon
-- `'error'` - Red, error icon
-- `'warning'` - Orange, warning icon
-- `'info'` - Blue, info icon
-
-## Methods
-
-### Container Methods
-
-#### `show(message: string, options?: ToastOptions): string`
-Show a new toast and return its ID.
+Pass options to control duration, position, and appearance.
 
 ```typescript
-const id = container.show('Success!', {
+Toast.show('Custom message', {
   type: 'success',
-  duration: 3000,
+  duration: 5000,
+  position: 'top-right',
   closable: true,
-  icon: true,
-  id: 'custom-id' // Optional custom ID
+  icon: true
 });
 ```
 
-**ToastOptions:**
-```typescript
-interface ToastOptions {
-  type?: ToastType;        // Default: 'info'
-  duration?: number;       // ms, 0 for no auto-dismiss, default: 4000
-  position?: ToastPosition; // Only used with static API
-  closable?: boolean;      // Default: true
-  icon?: boolean;          // Default: true
-  id?: string;             // Custom ID, auto-generated if not provided
-}
-```
-
-#### `hide(id: string): void`
-Hide a specific toast by ID.
-
-```typescript
-container.hide('toast-1');
-```
-
-#### `clear(): void`
-Remove all toasts from the container.
-
-```typescript
-container.clear();
-```
-
-### Toast Methods
-
-#### `hide(): void`
-Start the hide animation for this toast.
-
-```typescript
-toast.hide();
-```
-
-## Examples
-
-### Basic Notifications
-
-```typescript
-import Toast from 'snice/components/toast/snice-toast-container';
-
-// Success notification
-document.querySelector('#saveBtn').addEventListener('click', async () => {
-  try {
-    await saveData();
-    Toast.success('Changes saved successfully');
-  } catch (error) {
-    Toast.error('Failed to save changes');
-  }
-});
-
-// Info notification
-Toast.info('Welcome back, John!');
-
-// Warning notification
-if (diskSpace < 10) {
-  Toast.warning('Low disk space');
-}
-```
+### Loading Pattern
 
-### Custom Duration
+Show a persistent toast during an async operation, then replace it.
 
 ```typescript
-// Short toast (2 seconds)
-Toast.show('Quick message', { duration: 2000 });
-
-// Long toast (10 seconds)
-Toast.show('Important message', { duration: 10000 });
-
-// Persistent toast (no auto-dismiss)
-const id = Toast.show('Click X to close', { duration: 0 });
+const id = await Toast.info('Loading...', { duration: 0 });
+await fetchData();
+Toast.hide(id);
+Toast.success('Data loaded');
 ```
 
 ### Position Variants
 
-```html
-<button onclick="Toast.show('Top Left', { position: 'top-left' })">
-  Top Left
-</button>
-<button onclick="Toast.show('Top Center', { position: 'top-center' })">
-  Top Center
-</button>
-<button onclick="Toast.show('Top Right', { position: 'top-right' })">
-  Top Right
-</button>
-<button onclick="Toast.show('Bottom Left', { position: 'bottom-left' })">
-  Bottom Left
-</button>
-<button onclick="Toast.show('Bottom Center', { position: 'bottom-center' })">
-  Bottom Center
-</button>
-<button onclick="Toast.show('Bottom Right', { position: 'bottom-right' })">
-  Bottom Right
-</button>
-```
-
-### Manual Control
+Use the `position` option to place toasts anywhere on screen.
 
 ```typescript
-// Show loading toast
-const loadingId = Toast.info('Loading data...', { duration: 0 });
-
-// Fetch data
-const data = await fetchData();
-
-// Hide loading toast
-Toast.hide(loadingId);
-
-// Show success
-Toast.success('Data loaded');
+Toast.show('Top Left', { position: 'top-left' });
+Toast.show('Top Center', { position: 'top-center' });
+Toast.show('Top Right', { position: 'top-right' });
+Toast.show('Bottom Left', { position: 'bottom-left' });
+Toast.show('Bottom Center', { position: 'bottom-center' });
+Toast.show('Bottom Right', { position: 'bottom-right' });
 ```
 
-### Without Icon
-
-```typescript
-Toast.show('Plain message', { icon: false });
-```
+### Container Element
 
-### Non-Closable
-
-```typescript
-Toast.show('Cannot be closed manually', {
-  closable: false,
-  duration: 3000 // Will auto-dismiss
-});
-```
-
-### Multiple Containers
+Use a container element directly for more control.
 
 ```html
-<snice-toast-container id="alerts" position="top-right"></snice-toast-container>
-<snice-toast-container id="messages" position="bottom-left"></snice-toast-container>
-
-<script type="module">
-  import 'snice/components/toast/snice-toast-container';
-
-  const alerts = document.querySelector('#alerts');
-  const messages = document.querySelector('#messages');
+<snice-toast-container id="toaster" position="bottom-center"></snice-toast-container>
 
-  alerts.show('System alert', { type: 'warning' });
-  messages.show('New message', { type: 'info' });
+<script>
+  const container = document.querySelector('#toaster');
+  const id = container.show('Hello!', { type: 'success' });
+  container.hide(id);
+  container.clear();
 </script>
 ```
 
 ### Form Validation
 
 ```typescript
-const form = document.querySelector('form');
-
-form.addEventListener('submit', async (e) => {
-  e.preventDefault();
-
-  const formData = new FormData(form);
-
-  // Validate
-  if (!formData.get('email')) {
-    Toast.error('Email is required');
-    return;
-  }
-
-  if (!formData.get('password')) {
-    Toast.error('Password is required');
-    return;
-  }
-
-  // Show loading
-  const loadingId = Toast.info('Submitting...', { duration: 0 });
-
-  try {
-    await submitForm(formData);
-    Toast.hide(loadingId);
-    Toast.success('Form submitted successfully');
-  } catch (error) {
-    Toast.hide(loadingId);
-    Toast.error(error.message);
-  }
-});
-```
-
-### File Upload Progress
-
-```typescript
-async function uploadFile(file) {
-  const uploadId = Toast.info(`Uploading ${file.name}...`, { duration: 0 });
-
-  try {
-    await upload(file);
-    Toast.hide(uploadId);
-    Toast.success(`${file.name} uploaded`);
-  } catch (error) {
-    Toast.hide(uploadId);
-    Toast.error(`Failed to upload ${file.name}`);
-  }
-}
-```
-
-### Batch Operations
-
-```typescript
-async function deleteMultiple(ids) {
-  Toast.info(`Deleting ${ids.length} items...`);
-
-  const results = await Promise.allSettled(
-    ids.map(id => deleteItem(id))
-  );
-
-  const succeeded = results.filter(r => r.status === 'fulfilled').length;
-  const failed = results.filter(r => r.status === 'rejected').length;
-
-  if (succeeded > 0) {
-    Toast.success(`Deleted ${succeeded} items`);
-  }
-
-  if (failed > 0) {
-    Toast.error(`Failed to delete ${failed} items`);
-  }
-}
-```
-
-### Undo Action
-
-```typescript
-let undoTimeout;
-
-function deleteItem(id) {
-  const item = getItem(id);
-  item.deleted = true;
-
-  const toastId = Toast.warning('Item deleted', {
-    duration: 5000,
-    closable: false
-  });
-
-  // Create undo button
-  setTimeout(() => {
-    Toast.hide(toastId);
-    Toast.show('Click to undo', {
-      duration: 5000,
-      type: 'info'
-    });
-  }, 100);
-
-  undoTimeout = setTimeout(() => {
-    permanentlyDelete(id);
-  }, 5000);
-}
-
-function undo() {
-  clearTimeout(undoTimeout);
-  item.deleted = false;
-  Toast.success('Deletion cancelled');
+try {
+  await submitForm(formData);
+  Toast.success('Form submitted');
+} catch (error) {
+  Toast.error(error.message);
 }
 ```
 
-### Network Status
-
-```typescript
-window.addEventListener('online', () => {
-  Toast.success('Back online');
-});
-
-window.addEventListener('offline', () => {
-  Toast.error('No internet connection', { duration: 0 });
-});
-```
+## Properties
 
-## Accessibility
+### snice-toast-container
 
-- **role="alert"**: Each toast has `role="alert"` to announce to screen readers
-- **aria-live="polite"**: Non-intrusive announcements
-- **Close button**: Keyboard accessible with aria-label
-- **Focus management**: Close button receives focus when interacted with
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `position` | `'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'` | `'bottom-center'` | Position on screen |
 
-## Behavior
+### snice-toast
 
-### Auto-Dismiss
-- Default duration: 4000ms (4 seconds)
-- Set `duration: 0` to disable auto-dismiss
-- Toast fades out with animation before removal
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `type` | `'success' \| 'error' \| 'warning' \| 'info'` | `'info'` | Visual style |
+| `message` | `string` | `''` | Toast message text |
+| `closable` | `boolean` | `true` | Show close button |
+| `icon` | `boolean` | `true` | Show type icon |
 
-### Positioning
-- **Top positions**: New toasts appear at top (newest first)
-- **Bottom positions**: New toasts appear at bottom (newest last)
+## Events
 
-### Animation
-- Slide in from top/bottom based on position
-- Slide out when closing
-- 300ms animation duration
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `close-toast` | -- | Toast close button clicked |
 
-### Global Container
-- Static API automatically creates/reuses a global container
-- First container element becomes the global container
-- Position can be changed dynamically
+## Methods
 
-## Browser Support
+### Static API (Toast class)
 
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires Custom Elements v1 and Shadow DOM support
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `Toast.show()` | `message: string, options?: ToastOptions` | Show toast, returns `Promise<string>` (ID) |
+| `Toast.success()` | `message: string, options?: ToastOptions` | Show success toast |
+| `Toast.error()` | `message: string, options?: ToastOptions` | Show error toast |
+| `Toast.warning()` | `message: string, options?: ToastOptions` | Show warning toast |
+| `Toast.info()` | `message: string, options?: ToastOptions` | Show info toast |
+| `Toast.hide()` | `id: string` | Hide specific toast |
+| `Toast.clear()` | -- | Clear all toasts |
 
-## Best Practices
+### Container Methods
 
-1. **Keep messages short**: Toasts should be scannable at a glance
-2. **Use appropriate types**: Match the toast type to the message severity
-3. **Set reasonable durations**: 2-5 seconds for normal messages
-4. **Avoid too many toasts**: Clear old toasts before showing many new ones
-5. **Don't rely solely on color**: Icons help distinguish toast types
-6. **Provide actions when needed**: Use persistent toasts with manual dismiss for important actions
-7. **Position consistently**: Choose one primary position for your app's toasts
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `show()` | `message: string, options?: ToastOptions` | Show toast, returns `string` (ID) |
+| `hide()` | `id: string` | Hide specific toast |
+| `clear()` | -- | Clear all toasts |
 
-## Common Patterns
+### ToastOptions
 
-### Success/Error Pattern
 ```typescript
-try {
-  await action();
-  Toast.success('Success message');
-} catch (error) {
-  Toast.error(error.message);
+interface ToastOptions {
+  type?: 'success' | 'error' | 'warning' | 'info';
+  duration?: number;       // ms, 0 = no auto-dismiss, default: 4000
+  position?: ToastPosition;
+  closable?: boolean;      // default: true
+  icon?: boolean;          // default: true
+  id?: string;             // custom ID
 }
 ```
-
-### Loading Pattern
-```typescript
-const id = Toast.info('Loading...', { duration: 0 });
-await operation();
-Toast.hide(id);
-Toast.success('Complete');
-```
-
-### Temporary Undo Pattern
-```typescript
-const id = Toast.warning('Item deleted. Click to undo', { duration: 5000 });
-// Provide undo mechanism within 5 seconds
-```