@cdx-ui/components 0.0.1-beta.79 → 0.0.1-beta.80

package/src/components/Toast/types.ts

@@ -0,0 +1,332 @@
+import { View } from 'react-native';
+import type { EntryOrExitLayoutType, WithTimingConfig } from 'react-native-reanimated';
+import type { ToastRootProps } from '@cdx-ui/primitives';
+import { ForgeIcon } from '@cdx-ui/icons';
+import type { AnimationRoot, AnimationValue } from '../../animation';
+import type { ToastComponentProps, ToastShowOptions } from '../../providers/toast';
+import type { ButtonProps } from '../Button';
+import type { IconButtonProps } from '../IconButton';
+import type { IconProps } from '../Icon';
+import { ToastColorProps } from './styles';
+
+/**
+ * Toast color types
+ */
+export type ToastColor = ToastColorProps['color'];
+
+/**
+ * Toast placement types.
+ *
+ * On web, `-start` and `-end` variants position the toast at the
+ * corresponding horizontal edge with a `max-width` of 460 px.
+ * The plain `top` / `bottom` values centre the toast horizontally.
+ *
+ * On native (iOS / Android), `-start` and `-end` degrade gracefully
+ * to edge-to-edge layout identical to their base `top` / `bottom`
+ * counterpart — the toast still spans the full width.
+ */
+export type ToastPlacement =
+  | 'top-start'
+  | 'top'
+  | 'top-end'
+  | 'bottom-start'
+  | 'bottom'
+  | 'bottom-end';
+
+/**
+ * Animation configuration for toast root component
+ */
+export type ToastRootAnimation = AnimationRoot<{
+  opacity?: AnimationValue<{
+    /**
+     * Opacity interpolation values [start, end]
+     * Controls how fast toast items fade out as they move beyond the visible stack limits.
+     * When toasts are pushed out of view (beyond the last few visible items), their opacity
+     * gradually decreases to create a smooth disappearing effect.
+     * - First value: fully visible opacity (1) for items within visible stack
+     * - Second value: hidden opacity (0) for items pushed out of view
+     * @default [1, 0]
+     */
+    value?: [number, number];
+    /**
+     * Animation timing configuration
+     * @default { duration: 300 }
+     */
+    timingConfig?: WithTimingConfig;
+  }>;
+  translateY?: AnimationValue<{
+    /**
+     * Translate Y interpolation values [start, end]
+     * Controls how much of a toast item is visible when it's positioned behind the last visible toast.
+     * This creates a "peek" effect where stacked toasts are slightly offset vertically,
+     * allowing users to see a portion of the toast behind the current one.
+     * - First value: no offset (0) for the last/active toast
+     * - Second value: vertical offset in pixels (10) for toasts behind the last one
+     * Note: The offset direction is automatically adjusted based on placement (top/bottom)
+     * @default [0, 10] (multiplied by placement sign)
+     */
+    value?: [number, number];
+    /**
+     * Animation timing configuration
+     * @default { duration: 300 }
+     */
+    timingConfig?: WithTimingConfig;
+  }>;
+  scale?: AnimationValue<{
+    /**
+     * Scale interpolation values [start, end]
+     * Controls the size scaling of toast items in the stack.
+     * Toasts behind the active one are slightly scaled down to create depth and visual hierarchy.
+     * - First value: normal scale (1) for the active/last toast
+     * - Second value: scaled down value (0.97) for toasts positioned behind
+     * @default [1, 0.97]
+     */
+    value?: [number, number];
+    /**
+     * Animation timing configuration
+     * @default { duration: 300 }
+     */
+    timingConfig?: WithTimingConfig;
+  }>;
+  entering?: AnimationValue<{
+    /**
+     * Custom entering animation for top placement
+     * @default FadeInUp.springify().withInitialValues({ opacity: 1, transform: [{ translateY: -100 }] }).mass(3)
+     */
+    top?: EntryOrExitLayoutType;
+    /**
+     * Custom entering animation for bottom placement
+     * @default FadeInDown.springify().withInitialValues({ opacity: 1, transform: [{ translateY: 100 }] }).mass(3)
+     */
+    bottom?: EntryOrExitLayoutType;
+  }>;
+  exiting?: AnimationValue<{
+    /**
+     * Custom exiting animation for top placement
+     * @default Keyframe animation with translateY: -100, scale: 0.97, opacity: 0.5
+     */
+    top?: EntryOrExitLayoutType;
+    /**
+     * Custom exiting animation for bottom placement
+     * @default Keyframe animation with translateY: 100, scale: 0.97, opacity: 0.5
+     */
+    bottom?: EntryOrExitLayoutType;
+  }>;
+}>;
+
+/**
+ * Props for the Toast.Root component
+ */
+export interface ToastProps extends ToastRootProps, Omit<ToastComponentProps, 'id'> {
+  /**
+   * Color of the toast
+   * @default 'default'
+   */
+  color?: ToastColor;
+  /**
+   * Placement of the toast
+   * @default 'bottom'
+   */
+  placement?: ToastPlacement;
+  /**
+   * Additional CSS class for the toast container
+   *
+   * @note The following style properties are occupied by animations and cannot be set via className:
+   * - `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:
+   * ```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 use your own via className or style prop, set `isAnimatedStyleActive={false}`.
+   */
+  className?: string;
+  /**
+   * Animation configuration for toast
+   * - `false` or `"disabled"`: Disable only root animations
+   * - `"disable-all"`: Disable all animations including children
+   * - `true` or `undefined`: Use default animations
+   * - `object`: Custom animation configuration
+   */
+  animation?: ToastRootAnimation;
+  /**
+   * Whether the toast can be swiped to dismiss and dragged with rubber effect
+   * @default true
+   */
+  isSwipeable?: boolean;
+  /**
+   * Whether animated styles (react-native-reanimated) are active
+   * When `false`, the animated style is removed and you can implement custom logic
+   * This prop should only be used when you want to write custom styling logic instead of the default animated styles
+   * @default true
+   */
+  isAnimatedStyleActive?: boolean;
+}
+
+/**
+ * Props for the Toast.Title component
+ */
+export interface ToastTitleProps {
+  /**
+   * Content to be rendered as title
+   */
+  children?: React.ReactNode;
+  /**
+   * Additional CSS class for the title
+   */
+  className?: string;
+}
+
+/**
+ * Props for the Toast.Description component
+ */
+export interface ToastDescriptionProps {
+  /**
+   * Content to be rendered as description
+   */
+  children?: React.ReactNode;
+  /**
+   * Additional CSS class for the description
+   */
+  className?: string;
+}
+
+/**
+ * Props for the Toast.Icon component
+ */
+export interface ToastIconProps extends Omit<IconProps, 'children' | 'as'> {
+  asChild?: boolean;
+  /**
+   * Forge icon component to render. Required unless `asChild` is set.
+   */
+  as?: IconProps['as'];
+  /**
+   * Child element to render when `asChild` is set.
+   */
+  children?: React.ReactNode;
+}
+
+/**
+ * Props for the Toast.Action component
+ */
+export type ToastActionProps = ButtonProps;
+
+/**
+ * Props for the Toast.Close component
+ */
+export type ToastCloseProps = Omit<IconButtonProps, 'as'> & {
+  /**
+   * Forge icon component to render (icon-only control).
+   * @default CloseIcon
+   */
+  as?: ForgeIcon;
+};
+
+/**
+ * Context values shared between Toast components
+ */
+export interface ToastContextValue {
+  /**
+   * Color of the toast
+   */
+  color?: ToastColor;
+  /**
+   * Function to hide the toast
+   */
+  hide?: (ids?: (string & {}) | string[] | 'all') => void;
+  /**
+   * ID of the toast
+   */
+  id?: string;
+}
+
+/**
+ * Ref type for the Toast.Root component
+ */
+export type ToastRootRef = React.ComponentRef<typeof View>;
+
+/**
+ * Props for useToastRootAnimation hook
+ * Picks required properties from ToastRootProps and adds id from ToastComponentProps
+ */
+export type UseToastRootAnimationOptions = Pick<
+  ToastProps,
+  | 'animation'
+  | 'index'
+  | 'total'
+  | 'heights'
+  | 'placement'
+  | 'hide'
+  | 'isSwipeable'
+  | 'maxVisibleToasts'
+> &
+  Pick<ToastComponentProps, 'id'>;
+
+/**
+ * Props for the DefaultToast component
+ * Used internally when showing toasts with string or config object (without component)
+ */
+export interface DefaultToastProps extends ToastComponentProps {
+  /**
+   * Color of the toast
+   * @default 'default'
+   */
+  color?: ToastProps['color'];
+  /**
+   * Placement of the toast
+   * @default 'bottom'
+   */
+  placement?: ToastProps['placement'];
+  /**
+   * Animation configuration for toast
+   */
+  animation?: ToastProps['animation'];
+  /**
+   * Whether the toast can be swiped to dismiss and dragged with rubber effect
+   */
+  isSwipeable?: ToastProps['isSwipeable'];
+  /**
+   * Label text for the toast
+   */
+  label?: string;
+  /**
+   * Description text for the toast
+   */
+  description?: string;
+  /**
+   * Action button label text
+   */
+  actionLabel?: string;
+  /**
+   * Callback function called when the action button is pressed
+   * Receives show and hide functions for programmatic toast control
+   */
+  onActionPress?: (helpers: {
+    show: (options: string | ToastShowOptions) => string;
+    hide: (ids?: (string & {}) | string[] | 'all') => void;
+  }) => void;
+  /**
+   * Forge icon component to display in the toast.
+   * Rendered via `Toast.Icon` internally — inherits color-aware coloring automatically.
+   */
+  icon?: ForgeIcon;
+}

package/src/components/index.ts

@@ -26,6 +26,7 @@ export * from './Select';
 export * from './VirtualizedList';
 export * from './Switch';
 export * from './Tile';
+export * from './Toast';
 export { HStack, VStack } from './Stack';
 export * from './Heading';
 export * from './Text';

package/src/index.ts

@@ -2,5 +2,7 @@
 export * from './components';
 export * from './hooks';
 export * from './navigation';
+export { ToastProvider, useToast } from './providers/toast';
+export type * from './providers/toast';
 export { View, ScrollView, KeyboardAvoidingView } from 'react-native';
 export { SafeAreaView, useSafeAreaInsets } from 'react-native-safe-area-context';

package/src/providers/animation-settings/index.ts

@@ -0,0 +1,11 @@
+export {
+  GlobalAnimationSettingsProvider,
+  AnimationSettingsProvider,
+  useGlobalAnimationSettings,
+  useAnimationSettings,
+} from './provider';
+export type {
+  GlobalAnimationSettingsContextValue,
+  GlobalAnimationSettingsProviderProps,
+  AnimationSettingsContextValue,
+} from './types';

package/src/providers/animation-settings/provider.tsx

@@ -0,0 +1,54 @@
+import React from 'react';
+import { useReducedMotion } from 'react-native-reanimated';
+import { createContext } from '@cdx-ui/utils';
+import type {
+  GlobalAnimationSettingsContextValue,
+  GlobalAnimationSettingsProviderProps,
+  AnimationSettingsContextValue,
+} from './types';
+
+const [GlobalAnimationSettingsProviderComponent, useGlobalAnimationSettings] =
+  createContext<GlobalAnimationSettingsContextValue>('GlobalAnimationSettingsContext', {
+    strict: false,
+    defaultValue: { globalIsAllAnimationsDisabled: false },
+  });
+
+export { useGlobalAnimationSettings };
+
+/**
+ * GlobalAnimationSettingsProvider Component
+ *
+ * @description
+ * Provider component that controls global animation settings across the application.
+ * When animation is set to 'disable-all', all animations will be disabled globally.
+ * Additionally, if the user has enabled reduce motion in accessibility settings,
+ * all animations will be disabled automatically.
+ *
+ * The global setting is read directly via `useGlobalAnimationSettings`; the
+ * separate `AnimationSettingsProvider` handles per-subtree cascading. Both
+ * contexts are non-strict, so components can read them without a provider
+ * mounted (falling back to "animations enabled").
+ *
+ * @param {GlobalAnimationSettingsProviderProps} props - Provider props
+ * @param {AnimationRootDisableAll} [props.animation] - Global animation setting
+ * @param {ReactNode} props.children - Child components to wrap
+ */
+export const GlobalAnimationSettingsProvider: React.FC<GlobalAnimationSettingsProviderProps> = ({
+  animation,
+  children,
+}) => {
+  const reducedMotion = useReducedMotion();
+  const globalIsAllAnimationsDisabled = animation === 'disable-all' || reducedMotion;
+
+  return (
+    <GlobalAnimationSettingsProviderComponent value={{ globalIsAllAnimationsDisabled }}>
+      {children}
+    </GlobalAnimationSettingsProviderComponent>
+  );
+};
+
+export const [AnimationSettingsProvider, useAnimationSettings] =
+  createContext<AnimationSettingsContextValue>('AnimationSettingsContext', {
+    strict: false,
+    defaultValue: { isAllAnimationsDisabled: false },
+  });

package/src/providers/animation-settings/types.ts

@@ -0,0 +1,37 @@
+import type { ReactNode } from 'react';
+import type { AnimationRootDisableAll } from '../../animation';
+
+/**
+ * Props for GlobalAnimationSettingsProvider component
+ */
+export interface GlobalAnimationSettingsProviderProps {
+  /**
+   * Global animation setting
+   * When set to 'disable-all', all animations across the app will be disabled
+   */
+  animation?: AnimationRootDisableAll;
+  /**
+   * Child components to render within the provider
+   */
+  children: ReactNode;
+}
+
+/**
+ * Context value for global animation settings
+ */
+export interface GlobalAnimationSettingsContextValue {
+  /**
+   * Whether all animations should be disabled globally
+   */
+  globalIsAllAnimationsDisabled: boolean;
+}
+
+/**
+ * Context value for global animation settings
+ */
+export interface AnimationSettingsContextValue {
+  /**
+   * Whether all animations should be disabled (cascading from parent)
+   */
+  isAllAnimationsDisabled: boolean;
+}

package/src/providers/forge-design/index.ts

@@ -0,0 +1,2 @@
+export { default as ForgeDesignProvider } from './provider';
+export * from './types';

package/src/providers/forge-design/provider.tsx

@@ -0,0 +1,61 @@
+import React from 'react';
+import { SafeAreaListener } from 'react-native-safe-area-context';
+import { Uniwind } from 'uniwind';
+import { PortalHost } from '@cdx-ui/primitives';
+import { GlobalAnimationSettingsProvider } from '../animation-settings';
+import { TextComponentProvider } from '../text-component/provider';
+import { ToastProvider } from '../toast/provider';
+import type { ForgeDesignProviderProps } from './types';
+
+/**
+ * ForgeDesignProvider Component
+ *
+ * @description
+ * Main provider component for HeroUI Native that configures the application
+ * with global settings. This component should wrap your entire application
+ * or the section where you want to use HeroUI Native components.
+ *
+ * Currently provides:
+ * - Global animation settings
+ * - Global text component configuration
+ * - Toast notification system
+ * - Portal management for overlays
+ *
+ * @param {ForgeDesignProviderProps} props - Provider configuration props
+ * @param {ReactNode} props.children - Child components to wrap
+ * @param {ForgeDesignConfig} [props.config] - Configuration object
+ *
+ */
+const ForgeDesignProvider: React.FC<ForgeDesignProviderProps> = ({ children, config = {} }) => {
+  const { textProps, toast, animation } = config;
+
+  // Determine if toast should be enabled and get props
+  const isToastEnabled = toast !== false && toast !== 'disabled';
+  const toastProps = typeof toast === 'object' ? toast : {};
+
+  return (
+    <SafeAreaListener
+      onChange={({ insets }) => {
+        Uniwind.updateInsets(insets);
+      }}
+    >
+      <GlobalAnimationSettingsProvider animation={animation}>
+        <TextComponentProvider value={{ textProps }}>
+          {isToastEnabled ? (
+            <ToastProvider {...toastProps}>
+              {children}
+              <PortalHost />
+            </ToastProvider>
+          ) : (
+            <>
+              {children}
+              <PortalHost />
+            </>
+          )}
+        </TextComponentProvider>
+      </GlobalAnimationSettingsProvider>
+    </SafeAreaListener>
+  );
+};
+
+export default ForgeDesignProvider;

package/src/providers/forge-design/types.ts

@@ -0,0 +1,84 @@
+import type { ReactNode } from 'react';
+import type { AnimationRootDisableAll } from '../../animation';
+import type { TextComponentContextValue } from '../text-component/types';
+import type { ToastProviderProps } from '../toast/types';
+
+/**
+ * Configuration object for ForgeDesignProvider
+ *
+ * @interface ForgeDesignConfig
+ * @extends TextComponentContextValue
+ *
+ * @description
+ * Contains configuration options for the HeroUI Native provider.
+ * Additional configuration options can be added in future versions.
+ */
+export interface ForgeDesignConfig extends TextComponentContextValue {
+  /**
+   * Global animation configuration
+   *
+   * @description
+   * When set to 'disable-all', all animations across the application will be disabled.
+   */
+  animation?: AnimationRootDisableAll;
+  /**
+   * Toast configuration
+   *
+   * @description
+   * Configure the global toast system including insets and wrapper components.
+   * Set to `false` or `'disabled'` to disable the toast provider entirely.
+   * Provide a `ToastProviderProps` object for custom configuration.
+   */
+  toast?: boolean | 'disabled' | ToastProviderProps;
+}
+
+/**
+ * Props for ForgeDesignProvider component
+ *
+ * @interface ForgeDesignProviderProps
+ *
+ * @description
+ * Main provider component props that wraps the entire application
+ * or a section of it to provide HeroUI Native functionality.
+ *
+ * @example
+ * ```tsx
+ * <ForgeDesignProvider config={{
+ *   textProps: {
+ *     allowFontScaling: false,
+ *     maxFontSizeMultiplier: 1.5
+ *   }
+ * }}>
+ *   <App />
+ * </ForgeDesignProvider>
+ * ```
+ */
+export interface ForgeDesignProviderProps {
+  /**
+   * Child components to render within the provider
+   *
+   * @description
+   * All children will have access to HeroUI Native theme
+   * and configuration through the provider.
+   */
+  children: ReactNode;
+
+  /**
+   * Configuration object for the provider
+   *
+   * @description
+   * Contains all configuration options including global text component configuration.
+   *
+   * @example
+   * ```tsx
+   * const config: ForgeDesignConfig = {
+   *   textProps: {
+   *     allowFontScaling: false,
+   *     adjustsFontSizeToFit: false,
+   *     maxFontSizeMultiplier: 1.5
+   *   }
+   * };
+   * ```
+   */
+  config?: ForgeDesignConfig;
+}

package/src/providers/text-component/index.ts

@@ -0,0 +1,2 @@
+export * from './provider';
+export * from './types';

package/src/providers/text-component/provider.tsx

@@ -0,0 +1,7 @@
+import { createContext } from '@cdx-ui/utils';
+import type { TextComponentContextValue } from './types';
+
+const [TextComponentProvider, useTextComponent] =
+  createContext<TextComponentContextValue>('TextComponentContext');
+
+export { TextComponentProvider, useTextComponent };

package/src/providers/text-component/types.ts

@@ -0,0 +1,52 @@
+import type { TextProps } from 'react-native';
+
+/**
+ * Global text component configuration props.
+ * These props are carefully selected to include only those that make sense
+ * to configure globally across all Text components in the application.
+ *
+ * @description
+ * Includes accessibility and font scaling settings that typically
+ * should be consistent throughout the app for better UX.
+ */
+export interface TextComponentProps {
+  /**
+   * Specifies whether fonts should be scaled down automatically to fit given style constraints.
+   *
+   * @default false
+   */
+  adjustsFontSizeToFit?: TextProps['adjustsFontSizeToFit'];
+  /**
+   * Specifies whether fonts should scale to respect Text Size accessibility settings.
+   *
+   * @default true
+   */
+  allowFontScaling?: TextProps['allowFontScaling'];
+  /**
+   * Specifies the largest possible scale a font can reach when `allowFontScaling` is enabled.
+   *
+   * Possible values:
+   *
+   * - `null` or `undefined`: inherit from the parent node or the global default (0)
+   * - `0`: no max, ignore parent/global default
+   * - `>= 1`: sets the `maxFontSizeMultiplier` of this node to this value
+   *
+   * @default `undefined`
+   */
+  maxFontSizeMultiplier?: TextProps['maxFontSizeMultiplier'];
+  /**
+   * Specifies the smallest possible scale a font can reach when adjustsFontSizeToFit is enabled. (values 0.01-1.0).
+   *
+   * iOS only
+   *
+   * @default `undefined`
+   */
+  minimumFontScale?: TextProps['minimumFontScale'];
+}
+
+/**
+ * Context value for text component configuration
+ */
+export interface TextComponentContextValue {
+  textProps?: TextComponentProps;
+}

package/src/providers/toast/index.ts

@@ -0,0 +1,4 @@
+export { ToastProvider, useToast } from './provider';
+export { useToastConfig } from './toast-config.context';
+export { useToastLifecycle } from './lifecycle.context';
+export type * from './types';