@erquhart/heroui-native 1.0.0-beta.10.1

package/src/components/toast/toast.md

@@ -0,0 +1,417 @@
+# Toast
+
+Displays temporary notification messages that appear at the top or bottom of the screen.
+
+## Imports
+
+Note: Before importing this component, ensure you have completed the setup as per the [Quick Start guide](../../../README.md).
+
+```tsx
+import { Toast, useToast } from 'heroui-native';
+```
+
+## Usage
+
+### Usage Pattern 1: Simple String
+
+Show a toast with a simple string message.
+
+```tsx
+const { toast } = useToast();
+
+toast.show('This is a toast message');
+```
+
+### Usage Pattern 2: Config Object
+
+Show a toast with label, description, variant, and action button using a config object.
+
+```tsx
+const { toast } = useToast();
+
+toast.show({
+  variant: 'success',
+  label: 'You have upgraded your plan',
+  description: 'You can continue using HeroUI Chat',
+  icon: <Icon name="check" />,
+  actionLabel: 'Close',
+  onActionPress: ({ hide }) => hide(),
+});
+```
+
+### Usage Pattern 3: Custom Component
+
+Show a toast with a fully custom component for complete control over styling and layout.
+
+```tsx
+const { toast } = useToast();
+
+toast.show({
+  component: (props) => (
+    <Toast variant="accent" placement="top" {...props}>
+      <Toast.Title>Custom Toast</Toast.Title>
+      <Toast.Description>This is a custom toast component</Toast.Description>
+      <Toast.Close />
+    </Toast>
+  ),
+});
+```
+
+**Note**: Toast items are memoized for performance. If you need to pass external state (like loading state) to a custom toast component, it will not update automatically. Use shared state techniques instead, such as React Context, state management libraries, or refs to ensure state updates propagate to the toast component.
+
+### Disabling All Animations
+
+Disable all animations including children by using `"disable-all"`. This cascades down to all child components (like Button in Toast.Action).
+
+```tsx
+const { toast } = useToast();
+
+toast.show({
+  variant: 'success',
+  label: 'Operation completed',
+  description: 'All animations are disabled',
+  animation: 'disable-all',
+});
+```
+
+Or with a custom component:
+
+```tsx
+const { toast } = useToast();
+
+toast.show({
+  component: (props) => (
+    <Toast variant="accent" animation="disable-all" {...props}>
+      <Toast.Title>No animations</Toast.Title>
+      <Toast.Description>
+        This toast has all animations disabled
+      </Toast.Description>
+      <Toast.Action>Action</Toast.Action>
+    </Toast>
+  ),
+});
+```
+
+## Example
+
+```tsx
+import { Button, Toast, useToast, useThemeColor } from 'heroui-native';
+import { View } from 'react-native';
+
+export default function ToastExample() {
+  const { toast } = useToast();
+  const themeColorForeground = useThemeColor('foreground');
+
+  return (
+    <View className="gap-4 p-4">
+      <Button
+        onPress={() =>
+          toast.show({
+            variant: 'success',
+            label: 'You have upgraded your plan',
+            description: 'You can continue using HeroUI Chat',
+            actionLabel: 'Close',
+            onActionPress: ({ hide }) => hide(),
+          })
+        }
+      >
+        Show Success Toast
+      </Button>
+
+      <Button
+        onPress={() =>
+          toast.show({
+            component: (props) => (
+              <Toast variant="accent" {...props}>
+                <Toast.Title>Custom Toast</Toast.Title>
+                <Toast.Description>
+                  This uses a custom component
+                </Toast.Description>
+                <Toast.Action onPress={() => props.hide()}>Undo</Toast.Action>
+                <Toast.Close className="absolute top-0 right-0" />
+              </Toast>
+            ),
+          })
+        }
+      >
+        Show Custom Toast
+      </Button>
+    </View>
+  );
+}
+```
+
+## Anatomy
+
+```tsx
+<Toast>
+  <Toast.Title>...</Toast.Title>
+  <Toast.Description>...</Toast.Description>
+  <Toast.Action>...</Toast.Action>
+  <Toast.Close />
+</Toast>
+```
+
+- **Toast**: Main container that displays notification messages. Handles positioning, animations, and swipe gestures.
+- **Toast.Title**: Title text of the toast notification. Inherits variant styling from parent Toast context.
+- **Toast.Description**: Descriptive text content displayed below the title.
+- **Toast.Action**: Action button within the toast. Button variant is automatically determined based on toast variant but can be overridden.
+- **Toast.Close**: Close button for dismissing the toast. Renders as an icon-only button that calls hide when pressed.
+
+## Global Configuration
+
+Configure toast behavior globally using `HeroUINativeProvider` config prop. Global configs serve as defaults for all toasts unless overridden locally.
+
+### Insets
+
+Insets control the distance of toast sides from screen edges. Insets are added to safe area insets. To set all toasts to have a side distance of 20px from screen edges, configure insets:
+
+```tsx
+<HeroUINativeProvider
+  config={{
+    toast: {
+      insets: {
+        top: 20,
+        bottom: 20,
+        left: 20,
+        right: 20,
+      },
+    },
+  }}
+>
+  {children}
+</HeroUINativeProvider>
+```
+
+### Content Wrapper with KeyboardAvoidingView
+
+Wrap toast content with KeyboardAvoidingView to ensure toasts adjust when the keyboard appears:
+
+```tsx
+import {
+  KeyboardAvoidingView,
+  KeyboardProvider,
+} from 'react-native-keyboard-controller';
+import { HeroUINativeProvider } from 'heroui-native';
+import { useCallback } from 'react';
+
+function AppContent() {
+  const contentWrapper = useCallback(
+    (children: React.ReactNode) => (
+      <KeyboardAvoidingView
+        pointerEvents="box-none"
+        behavior="padding"
+        keyboardVerticalOffset={12}
+        className="flex-1"
+      >
+        {children}
+      </KeyboardAvoidingView>
+    ),
+    []
+  );
+
+  return (
+    <KeyboardProvider>
+      <HeroUINativeProvider
+        config={{
+          toast: {
+            contentWrapper,
+          },
+        }}
+      >
+        {children}
+      </HeroUINativeProvider>
+    </KeyboardProvider>
+  );
+}
+```
+
+### Default Props
+
+Set global defaults for variant, placement, animation, and swipe behavior:
+
+```tsx
+<HeroUINativeProvider
+  config={{
+    toast: {
+      defaultProps: {
+        variant: 'accent',
+        placement: 'bottom',
+        isSwipeable: false,
+      },
+    },
+  }}
+>
+  {children}
+</HeroUINativeProvider>
+```
+
+## Styling Notes
+
+### Border as Padding
+
+Toast uses `border-[16px]` class which serves as padding. This is intentional because when visible toasts have different heights, the toast adapts to the last visible toast height. In cases where a toast originally has one height and gets smaller when a new toast comes to stack, content might be visible behind the last toast without proper padding. The border ensures consistent spacing regardless of toast height changes.
+
+For padding, use `border` classes. For actual borders, use `outline` classes.
+
+## API Reference
+
+### Toast
+
+| prop                    | type                                                          | default     | description                                                               |
+| ----------------------- | ------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
+| `variant`               | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Visual variant of the toast                                               |
+| `placement`             | `'top' \| 'bottom'`                                           | `'top'`     | Placement of the toast on screen                                          |
+| `isSwipeable`           | `boolean`                                                     | `true`      | Whether the toast can be swiped to dismiss and dragged with rubber effect |
+| `animation`             | `ToastRootAnimation`                                          | -           | Animation configuration                                                   |
+| `isAnimatedStyleActive` | `boolean`                                                     | `true`      | Whether animated styles (react-native-reanimated) are active              |
+| `className`             | `string`                                                      | -           | Additional CSS class for the toast container                              |
+| `...ViewProps`          | `ViewProps`                                                   | -           | All standard React Native View props are supported                        |
+
+#### ToastRootAnimation
+
+Animation configuration for Toast component. Can be:
+
+- `false` or `"disabled"`: Disable only root animations
+- `"disable-all"`: Disable all animations including children
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                      | type                                     | default                                                                                                                   | description                                                                      |
+| ------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `state`                   | `'disabled' \| 'disable-all' \| boolean` | -                                                                                                                         | Disable animations while customizing properties                                  |
+| `opacity.value`           | `[number, number]`                       | `[1, 0]`                                                                                                                  | Opacity interpolation values for fade effect as toasts move beyond visible stack |
+| `opacity.timingConfig`    | `WithTimingConfig`                       | `{ duration: 300 }`                                                                                                       | Animation timing configuration for opacity transitions                           |
+| `translateY.value`        | `[number, number]`                       | `[0, 10]`                                                                                                                 | Translate Y interpolation values for peek effect of stacked toasts               |
+| `translateY.timingConfig` | `WithTimingConfig`                       | `{ duration: 300 }`                                                                                                       | Animation timing configuration for translateY transitions                        |
+| `scale.value`             | `[number, number]`                       | `[1, 0.97]`                                                                                                               | Scale interpolation values for depth effect of stacked toasts                    |
+| `scale.timingConfig`      | `WithTimingConfig`                       | `{ duration: 300 }`                                                                                                       | Animation timing configuration for scale transitions                             |
+| `entering.top`            | `EntryOrExitLayoutType`                  | `FadeInUp`<br/>`.springify()`<br/>`.withInitialValues({ opacity: 1, transform: [{ translateY: -100 }] })`<br/>`.mass(3)`  | Custom entering animation for top placement                                      |
+| `entering.bottom`         | `EntryOrExitLayoutType`                  | `FadeInDown`<br/>`.springify()`<br/>`.withInitialValues({ opacity: 1, transform: [{ translateY: 100 }] })`<br/>`.mass(3)` | Custom entering animation for bottom placement                                   |
+| `exiting.top`             | `EntryOrExitLayoutType`                  | Keyframe animation with<br/>`translateY: -100, scale: 0.97, opacity: 0.5`                                                 | Custom exiting animation for top placement                                       |
+| `exiting.bottom`          | `EntryOrExitLayoutType`                  | Keyframe animation with<br/>`translateY: 100, scale: 0.97, opacity: 0.5`                                                  | Custom exiting animation for bottom placement                                    |
+
+### Toast.Title
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Content to be rendered as title                    |
+| `className`    | `string`          | -       | Additional CSS classes                             |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
+
+### Toast.Description
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Content to be rendered as description              |
+| `className`    | `string`          | -       | Additional CSS classes                             |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
+
+### Toast.Action
+
+Toast.Action extends all props from [Button](../button/button.md) component. Button variant is automatically determined based on toast variant but can be overridden.
+
+| prop        | type                   | default | description                                                                  |
+| ----------- | ---------------------- | ------- | ---------------------------------------------------------------------------- |
+| `children`  | `React.ReactNode`      | -       | Content to be rendered as action button label                                |
+| `variant`   | `ButtonVariant`        | -       | Button variant. If not provided, automatically determined from toast variant |
+| `size`      | `'sm' \| 'md' \| 'lg'` | `'sm'`  | Size of the action button                                                    |
+| `className` | `string`               | -       | Additional CSS classes                                                       |
+
+For inherited props including `onPress`, `isDisabled`, and all Button props, see [Button API Reference](../button/button.md#api-reference).
+
+### Toast.Close
+
+Toast.Close extends all props from [Button](../button/button.md) component.
+
+| prop        | type                                | default | description                                    |
+| ----------- | ----------------------------------- | ------- | ---------------------------------------------- |
+| `children`  | `React.ReactNode`                   | -       | Custom close icon. Defaults to CloseIcon       |
+| `iconProps` | `{ size?: number; color?: string }` | -       | Props for the default close icon               |
+| `size`      | `'sm' \| 'md' \| 'lg'`              | `'sm'`  | Size of the close button                       |
+| `className` | `string`                            | -       | Additional CSS classes                         |
+| `onPress`   | `(event: any) => void`              | -       | Custom press handler. Defaults to hiding toast |
+
+For inherited props including `isDisabled` and all Button props, see [Button API Reference](../button/button.md#api-reference).
+
+### ToastProviderProps
+
+Props for configuring toast behavior globally via `HeroUINativeProvider` config prop.
+
+| prop               | type                                                | default | description                                                      |
+| ------------------ | --------------------------------------------------- | ------- | ---------------------------------------------------------------- |
+| `defaultProps`     | `ToastGlobalConfig`                                 | -       | Global toast configuration used as defaults for all toasts       |
+| `insets`           | `ToastInsets`                                       | -       | Insets for spacing from screen edges (added to safe area insets) |
+| `maxVisibleToasts` | `number`                                            | `3`     | Maximum number of visible toasts before opacity starts fading    |
+| `contentWrapper`   | `(children: React.ReactNode) => React.ReactElement` | -       | Custom wrapper function to wrap toast content                    |
+| `children`         | `React.ReactNode`                                   | -       | Children to render                                               |
+
+#### ToastGlobalConfig
+
+Global toast configuration used as defaults for all toasts unless overridden locally.
+
+| prop          | type                                                          | description                                                               |
+| ------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `variant`     | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | Visual variant of the toast                                               |
+| `placement`   | `'top' \| 'bottom'`                                           | Placement of the toast on screen                                          |
+| `isSwipeable` | `boolean`                                                     | Whether the toast can be swiped to dismiss and dragged with rubber effect |
+| `animation`   | `ToastRootAnimation`                                          | Animation configuration for toast                                         |
+
+#### ToastInsets
+
+Insets for spacing from screen edges. Values are added to safe area insets.
+
+| prop     | type     | default | description                                                                                               |
+| -------- | -------- | ------- | --------------------------------------------------------------------------------------------------------- |
+| `top`    | `number` | -       | Inset from the top edge in pixels (added to safe area inset). Platform-specific: iOS = 0, Android = 12    |
+| `bottom` | `number` | -       | Inset from the bottom edge in pixels (added to safe area inset). Platform-specific: iOS = 6, Android = 12 |
+| `left`   | `number` | -       | Inset from the left edge in pixels (added to safe area inset). Default: 12                                |
+| `right`  | `number` | -       | Inset from the right edge in pixels (added to safe area inset). Default: 12                               |
+
+### useToast
+
+Hook to access toast functionality. Must be used within a `ToastProvider` (provided by `HeroUINativeProvider`).
+
+| return value     | type           | description                              |
+| ---------------- | -------------- | ---------------------------------------- |
+| `toast`          | `ToastManager` | Toast manager with show and hide methods |
+| `isToastVisible` | `boolean`      | Whether any toast is currently visible   |
+
+#### ToastManager
+
+| method | type                                              | description                                                                                                                          |
+| ------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `show` | `(options: string \| ToastShowOptions) => string` | Show a toast. Returns the ID of the shown toast. Supports three usage patterns: simple string, config object, or custom component    |
+| `hide` | `(ids?: string \| string[] \| 'all') => void`     | Hide one or more toasts. No argument hides the last toast, 'all' hides all toasts, single ID or array of IDs hides specific toast(s) |
+
+#### ToastShowOptions
+
+Options for showing a toast. Can be either a config object with default styling or a custom component.
+
+**When using config object (without component):**
+
+| prop            | type                                                                                                                              | default | description                                                                         |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
+| `variant`       | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'`                                                                     | -       | Visual variant of the toast                                                         |
+| `placement`     | `'top' \| 'bottom'`                                                                                                               | -       | Placement of the toast on screen                                                    |
+| `isSwipeable`   | `boolean`                                                                                                                         | -       | Whether the toast can be swiped to dismiss                                          |
+| `animation`     | `ToastRootAnimation \| false \| "disabled" \| "disable-all"`                                                                      | -       | Animation configuration for toast                                                   |
+| `duration`      | `number \| 'persistent'`                                                                                                          | `4000`  | Duration in milliseconds before auto-hide. Set to 'persistent' to prevent auto-hide |
+| `id`            | `string`                                                                                                                          | -       | Optional ID for the toast. If not provided, one will be generated                   |
+| `label`         | `string`                                                                                                                          | -       | Label text for the toast                                                            |
+| `description`   | `string`                                                                                                                          | -       | Description text for the toast                                                      |
+| `actionLabel`   | `string`                                                                                                                          | -       | Action button label text                                                            |
+| `onActionPress` | `(helpers: { show: (options: string \| ToastShowOptions) => string; hide: (ids?: string \| string[] \| 'all') => void }) => void` | -       | Callback function called when the action button is pressed                          |
+| `icon`          | `React.ReactNode`                                                                                                                 | -       | Icon element to display in the toast                                                |
+| `onShow`        | `() => void`                                                                                                                      | -       | Callback function called when the toast is shown                                    |
+| `onHide`        | `() => void`                                                                                                                      | -       | Callback function called when the toast is hidden                                   |
+
+**When using custom component:**
+
+| prop        | type                                                 | default | description                                                                         |
+| ----------- | ---------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
+| `id`        | `string`                                             | -       | Optional ID for the toast. If not provided, one will be generated                   |
+| `component` | `(props: ToastComponentProps) => React.ReactElement` | -       | A function that receives toast props and returns a React element                    |
+| `duration`  | `number \| 'persistent'`                             | `4000`  | Duration in milliseconds before auto-hide. Set to 'persistent' to prevent auto-hide |
+| `onShow`    | `() => void`                                         | -       | Callback function called when the toast is shown                                    |
+| `onHide`    | `() => void`                                         | -       | Callback function called when the toast is hidden                                   |

package/src/components/toast/toast.styles.ts

@@ -0,0 +1,91 @@
+import { StyleSheet } from 'react-native';
+import { tv } from 'tailwind-variants';
+import { combineStyles } from '../../helpers/theme/utils/combine-styles';
+
+/**
+ * Toast root styles
+ *
+ * @note ANIMATED PROPERTIES (cannot be set via className):
+ * The following properties are animated and cannot be overridden using Tailwind classes:
+ * - `opacity` - Animated for visibility transitions when toasts are pushed beyond visible stack limits
+ * - `transform` (translateY) - Animated for vertical position transitions when toasts are stacked, and for swipe-to-dismiss gestures
+ * - `transform` (scale) - Animated for size scaling transitions when toasts are stacked (toasts behind active one are scaled down)
+ * - `height` - Animated for height transitions when toast content changes
+ *
+ * To customize these properties, use the `animation` prop on `Toast.Root`:
+ * ```tsx
+ * <Toast.Root
+ *   animation={{
+ *     opacity: {
+ *       value: [1, 0],
+ *       timingConfig: { duration: 300 }
+ *     },
+ *     translateY: {
+ *       value: [0, 10],
+ *       timingConfig: { duration: 300 }
+ *     },
+ *     scale: {
+ *       value: [1, 0.97],
+ *       timingConfig: { duration: 300 }
+ *     }
+ *   }}
+ * />
+ * ```
+ *
+ * To completely disable animated styles and apply your own via className or style prop,
+ * set `isAnimatedStyleActive={false}` on `Toast.Root`.
+ */
+const root = tv({
+  base: 'rounded-3xl bg-surface border-[16px] border-surface outline outline-muted/5 shadow-2xl shadow-black/5 overflow-hidden',
+});
+
+const label = tv({
+  base: 'text-base font-medium',
+  variants: {
+    variant: {
+      default: 'text-foreground',
+      accent: 'text-foreground',
+      success: 'text-success',
+      warning: 'text-warning',
+      danger: 'text-danger',
+    },
+  },
+  defaultVariants: {
+    variant: 'default',
+  },
+});
+
+const description = tv({
+  base: 'text-sm text-muted',
+});
+
+const action = tv({
+  base: '',
+  variants: {
+    variant: {
+      default: '',
+      accent: '',
+      success: 'bg-success',
+      warning: 'bg-warning',
+      danger: '',
+    },
+  },
+  defaultVariants: {
+    variant: 'default',
+  },
+});
+
+const toastStyles = combineStyles({
+  root,
+  label,
+  description,
+  action,
+});
+
+export const styleSheet = StyleSheet.create({
+  root: {
+    borderCurve: 'continuous',
+  },
+});
+
+export default toastStyles;