@umbra.ui/core 0.1.0

package/src/components/dialogs/Toast/README.md

@@ -0,0 +1,522 @@
+# Toast
+
+A comprehensive toast notification system built with Vue 3 Composition API and TypeScript. The Toast component provides a flexible interface for displaying temporary messages, notifications, and user feedback with smooth animations, multiple styles, and global state management.
+
+## Installation/Import
+
+```typescript
+import { Toast, ToastContainer, useToast, ToastPlugin } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- @umbra-ui/core (IconButton component)
+- @umbra-ui/icons (for icons)
+- GSAP (for animations)
+- tinycolor2 (for color calculations)
+
+## Basic Usage
+
+### Setup (App Level)
+
+```vue
+<script setup lang="ts">
+import { createApp } from "vue";
+import { ToastPlugin } from "@umbra-ui/core";
+import App from "./App.vue";
+
+const app = createApp(App);
+app.use(ToastPlugin);
+app.mount("#app");
+</script>
+```
+
+### Using the Composable
+
+```vue
+<script setup lang="ts">
+import { useToast } from "@umbra-ui/core";
+
+const { showSuccess, showError, showWarning, showInfo } = useToast();
+
+const handleSuccess = () => {
+  showSuccess("Success!", "Your action was completed successfully.");
+};
+
+const handleError = () => {
+  showError("Error", "Something went wrong. Please try again.");
+};
+
+const handleWarning = () => {
+  showWarning("Warning", "Please review your input before proceeding.");
+};
+
+const handleInfo = () => {
+  showInfo("Information", "Here's some helpful information for you.");
+};
+</script>
+
+<template>
+  <div>
+    <button @click="handleSuccess">Show Success</button>
+    <button @click="handleError">Show Error</button>
+    <button @click="handleWarning">Show Warning</button>
+    <button @click="handleInfo">Show Info</button>
+  </div>
+</template>
+```
+
+### Include ToastContainer
+
+```vue
+<template>
+  <div>
+    <!-- Your app content -->
+    <ToastContainer />
+  </div>
+</template>
+```
+
+## Props
+
+### Toast Component
+
+| Prop Name    | Type                                | Required | Default | Description                                         |
+| ------------ | ----------------------------------- | -------- | ------- | --------------------------------------------------- |
+| `toast`      | `ToastInstance`                     | Yes      | -       | Toast instance data containing all toast properties |
+| `toastStyle` | `"bar" \| "full" \| "notification"` | No       | `"bar"` | Visual style variant of the toast                   |
+
+### ToastContainer Component
+
+This component does not accept props. It automatically manages all toasts through the global toast manager.
+
+## Events
+
+### Toast Component
+
+| Event Name | Payload Type | Description                                               |
+| ---------- | ------------ | --------------------------------------------------------- |
+| `dismiss`  | `string`     | Emitted when the toast is dismissed, returns the toast ID |
+
+## Slots
+
+These components do not use slots.
+
+## Exposed Methods/Refs
+
+### useToast Composable
+
+The `useToast` composable provides the following methods:
+
+| Method Name       | Parameters                                                               | Return Type       | Description                         |
+| ----------------- | ------------------------------------------------------------------------ | ----------------- | ----------------------------------- |
+| `addToast`        | `(options: ToastOptions)`                                                | `Promise<string>` | Adds a new toast and returns its ID |
+| `removeToast`     | `(id: string)`                                                           | `void`            | Removes a toast by ID               |
+| `removeAllToasts` | `()`                                                                     | `void`            | Removes all active toasts           |
+| `setToastStyle`   | `(style: "bar" \| "full" \| "notification")`                             | `void`            | Sets the global toast style         |
+| `showSuccess`     | `(title: string, description?: string, options?: Partial<ToastOptions>)` | `Promise<string>` | Shows a success toast               |
+| `showError`       | `(title: string, description?: string, options?: Partial<ToastOptions>)` | `Promise<string>` | Shows an error toast                |
+| `showWarning`     | `(title: string, description?: string, options?: Partial<ToastOptions>)` | `Promise<string>` | Shows a warning toast               |
+| `showInfo`        | `(title: string, description?: string, options?: Partial<ToastOptions>)` | `Promise<string>` | Shows an info toast                 |
+
+## Types
+
+### ToastOptions
+
+```typescript
+interface ToastOptions {
+  title: string;
+  description?: string;
+  iconName?: string;
+  position?: "Top" | "Bottom";
+  toastType?: "success" | "error" | "warning" | "info" | string;
+  duration?: number; // Auto dismiss duration in ms (0 = no auto dismiss)
+  dismissible?: boolean;
+  actions?: ToastAction[];
+  onDismiss?: () => void;
+  className?: string;
+  role?: "alert" | "status";
+}
+```
+
+### ToastAction
+
+```typescript
+interface ToastAction {
+  label: string;
+  action: () => void;
+  style?: "primary" | "secondary";
+}
+```
+
+### ToastInstance
+
+```typescript
+interface ToastInstance
+  extends Required<
+    Omit<ToastOptions, "actions" | "onDismiss" | "className" | "role">
+  > {
+  id: string;
+  show: boolean;
+  actions?: ToastAction[];
+  onDismiss?: () => void;
+  className?: string;
+  role?: "alert" | "status";
+}
+```
+
+## CSS Customization
+
+The Toast component uses CSS custom properties for easy theming and customization:
+
+```css
+/* Toast type colors */
+--toast-success-bg: #30a46c;
+--toast-error-bg: #e5484d;
+--toast-warning-bg: #ffe629;
+--toast-info-bg: #5b5bd6;
+--toast-custom-bg: #6b7280;
+
+/* Toast shadow colors */
+--toast-shadow: rgba(0, 0, 0, 0.08);
+--toast-border: rgba(0, 0, 0, 0.08);
+
+/* Toast description opacity */
+--toast-description-opacity: 0.8;
+```
+
+## Examples
+
+### Basic Toast Types
+
+```vue
+<script setup lang="ts">
+import { useToast } from "@umbra-ui/core";
+
+const { showSuccess, showError, showWarning, showInfo } = useToast();
+
+const showToasts = () => {
+  showSuccess("Success!", "Operation completed successfully.");
+  showError("Error", "Something went wrong.");
+  showWarning("Warning", "Please check your input.");
+  showInfo("Info", "Here's some information.");
+};
+</script>
+
+<template>
+  <div>
+    <button @click="showToasts">Show All Toast Types</button>
+  </div>
+</template>
+```
+
+### Custom Toast with Actions
+
+```vue
+<script setup lang="ts">
+import { useToast } from "@umbra-ui/core";
+
+const { addToast } = useToast();
+
+const showCustomToast = () => {
+  addToast({
+    title: "File Uploaded",
+    description: "Your file has been uploaded successfully.",
+    toastType: "success",
+    duration: 0, // Persistent
+    actions: [
+      {
+        label: "View",
+        action: () => console.log("View file"),
+        style: "primary",
+      },
+      {
+        label: "Dismiss",
+        action: () => console.log("Dismissed"),
+        style: "secondary",
+      },
+    ],
+  });
+};
+</script>
+
+<template>
+  <div>
+    <button @click="showCustomToast">Show Custom Toast</button>
+  </div>
+</template>
+```
+
+### Different Toast Styles
+
+```vue
+<script setup lang="ts">
+import { useToast } from "@umbra-ui/core";
+
+const { addToast, setToastStyle } = useToast();
+
+const showBarToast = () => {
+  setToastStyle("bar");
+  addToast({
+    title: "Bar Style Toast",
+    description: "This is a bar-style toast notification.",
+    toastType: "info",
+  });
+};
+
+const showFullToast = () => {
+  setToastStyle("full");
+  addToast({
+    title: "Full Style Toast",
+    description: "This is a full-width toast notification.",
+    toastType: "success",
+  });
+};
+
+const showNotificationToast = () => {
+  setToastStyle("notification");
+  addToast({
+    title: "Notification Style Toast",
+    description: "This is a notification-style toast.",
+    toastType: "warning",
+  });
+};
+</script>
+
+<template>
+  <div>
+    <button @click="showBarToast">Bar Style</button>
+    <button @click="showFullToast">Full Style</button>
+    <button @click="showNotificationToast">Notification Style</button>
+  </div>
+</template>
+```
+
+### Custom Colors and Icons
+
+```vue
+<script setup lang="ts">
+import { useToast } from "@umbra-ui/core";
+
+const { addToast } = useToast();
+
+const showCustomColorToast = () => {
+  addToast({
+    title: "Custom Color Toast",
+    description: "This toast uses a custom color.",
+    toastType: "#8b5cf6", // Custom purple color
+    iconName: "star",
+  });
+};
+
+const showCustomIconToast = () => {
+  addToast({
+    title: "Custom Icon Toast",
+    description: "This toast uses a custom icon.",
+    toastType: "info",
+    iconName: "heart",
+  });
+};
+</script>
+
+<template>
+  <div>
+    <button @click="showCustomColorToast">Custom Color</button>
+    <button @click="showCustomIconToast">Custom Icon</button>
+  </div>
+</template>
+```
+
+### Form Validation Toasts
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { useToast } from "@umbra-ui/core";
+
+const { showSuccess, showError } = useToast();
+const email = ref("");
+const password = ref("");
+
+const validateForm = () => {
+  const errors = [];
+
+  if (!email.value) {
+    errors.push("Email is required");
+  }
+
+  if (!password.value) {
+    errors.push("Password is required");
+  }
+
+  if (password.value.length < 8) {
+    errors.push("Password must be at least 8 characters");
+  }
+
+  if (errors.length > 0) {
+    errors.forEach((error) => {
+      showError("Validation Error", error);
+    });
+  } else {
+    showSuccess("Success", "Form submitted successfully!");
+  }
+};
+</script>
+
+<template>
+  <form @submit.prevent="validateForm">
+    <input v-model="email" type="email" placeholder="Email" />
+    <input v-model="password" type="password" placeholder="Password" />
+    <button type="submit">Submit</button>
+  </form>
+</template>
+```
+
+### API Response Toasts
+
+```vue
+<script setup lang="ts">
+import { useToast } from "@umbra-ui/core";
+
+const { showSuccess, showError, showInfo } = useToast();
+
+const simulateApiCall = async () => {
+  showInfo("Loading", "Sending request to server...");
+
+  try {
+    // Simulate API call
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+
+    // Simulate success
+    showSuccess("Success", "Data saved successfully!");
+  } catch (error) {
+    showError("Error", "Failed to save data. Please try again.");
+  }
+};
+</script>
+
+<template>
+  <div>
+    <button @click="simulateApiCall">Save Data</button>
+  </div>
+</template>
+```
+
+### Persistent Toasts
+
+```vue
+<script setup lang="ts">
+import { useToast } from "@umbra-ui/core";
+
+const { addToast } = useToast();
+
+const showPersistentToast = () => {
+  addToast({
+    title: "Important Notice",
+    description: "This toast will not auto-dismiss. Click the X to close it.",
+    toastType: "warning",
+    duration: 0, // No auto-dismiss
+    dismissible: true,
+  });
+};
+
+const showNonDismissibleToast = () => {
+  addToast({
+    title: "Critical Alert",
+    description: "This toast cannot be dismissed manually.",
+    toastType: "error",
+    duration: 0,
+    dismissible: false,
+  });
+};
+</script>
+
+<template>
+  <div>
+    <button @click="showPersistentToast">Persistent Toast</button>
+    <button @click="showNonDismissibleToast">Non-Dismissible Toast</button>
+  </div>
+</template>
+```
+
+### Toast Management
+
+```vue
+<script setup lang="ts">
+import { useToast } from "@umbra-ui/core";
+
+const { addToast, removeAllToasts, toasts } = useToast();
+
+const addMultipleToasts = () => {
+  for (let i = 1; i <= 5; i++) {
+    addToast({
+      title: `Toast ${i}`,
+      description: `This is toast number ${i}`,
+      toastType: "info",
+    });
+  }
+};
+
+const clearAllToasts = () => {
+  removeAllToasts();
+};
+</script>
+
+<template>
+  <div>
+    <button @click="addMultipleToasts">Add 5 Toasts</button>
+    <button @click="clearAllToasts">Clear All Toasts</button>
+    <p>Active toasts: {{ toasts.length }}</p>
+  </div>
+</template>
+```
+
+### Different Positions
+
+```vue
+<script setup lang="ts">
+import { useToast } from "@umbra-ui/core";
+
+const { addToast } = useToast();
+
+const showTopToast = () => {
+  addToast({
+    title: "Top Position",
+    description: "This toast appears at the top.",
+    toastType: "info",
+    position: "Top",
+  });
+};
+
+const showBottomToast = () => {
+  addToast({
+    title: "Bottom Position",
+    description: "This toast appears at the bottom.",
+    toastType: "success",
+    position: "Bottom",
+  });
+};
+</script>
+
+<template>
+  <div>
+    <button @click="showTopToast">Top Toast</button>
+    <button @click="showBottomToast">Bottom Toast</button>
+  </div>
+</template>
+```
+
+## Notes
+
+- The Toast system uses Vue's `Teleport` to render toasts outside the component tree for proper z-index layering
+- Toasts include smooth GSAP animations for enter/exit transitions
+- The system supports multiple toast styles: bar, full, and notification
+- Toasts can be positioned at the top or bottom of the screen
+- The component automatically handles text color contrast based on background color
+- Toasts support custom colors, icons, and actions
+- The system includes accessibility features with proper ARIA labels and roles
+- Auto-dismiss functionality is built-in with configurable duration
+- The toast manager is a singleton that can be used throughout the application
+- Toasts are automatically stacked and animated when multiple are present
+- The system supports both light and dark themes through CSS custom properties