@cdx-ui/components 0.0.1-beta.15 → 0.0.1-beta.151

package/src/animation/types.ts

@@ -0,0 +1,128 @@
+import type {
+  BaseAnimationBuilder,
+  EntryOrExitLayoutType,
+  LayoutAnimationFunction,
+  WithSpringConfig,
+  WithTimingConfig,
+} from 'react-native-reanimated';
+
+/**
+ * Universal animation prop type
+ * - `true` or `undefined`: Use default animations
+ * - `false` or `"disabled"`: Disable all animations
+ * - `object`: Custom animation configuration
+ *   - Can include `state?: 'disabled' | boolean | undefined` to disable animations while customizing properties
+ */
+export type Animation<TConfig extends Record<string, any> = Record<string, any>> =
+  | boolean
+  | 'disabled'
+  | (TConfig & { state?: 'disabled' | boolean });
+
+export type AnimationDisabled = 'disabled' | false;
+
+/**
+ * Root-level animation prop type with cascading control
+ * - `true` or `undefined`: Use default animations
+ * - `false` or `"disabled"`: Disable only root animations (children can still animate)
+ * - `"disable-all"`: Disable all animations including children (cascades down)
+ * - `object`: Custom animation configuration
+ *   - Can include `state?: 'disabled' | 'disable-all' | boolean` to disable animations while customizing properties
+ */
+export type AnimationRoot<TConfig extends Record<string, any> = Record<string, any>> =
+  | boolean
+  | 'disabled'
+  | 'disable-all'
+  | (TConfig & { state?: 'disabled' | 'disable-all' | boolean });
+
+export type AnimationRootDisableAll = Extract<AnimationRoot, 'disable-all'>;
+
+/**
+ * Animation value that can be a custom config
+ * Used for granular animation control within a component
+ */
+export type AnimationValue<TConfig extends Record<string, any> = Record<string, any>> = TConfig;
+
+export type LayoutTransition =
+  | BaseAnimationBuilder
+  | LayoutAnimationFunction
+  | typeof BaseAnimationBuilder
+  | undefined;
+
+/**
+ * Spring animation configuration
+ */
+export interface SpringAnimationConfig {
+  type: 'spring';
+  config?: WithSpringConfig;
+}
+
+/**
+ * Timing animation configuration
+ */
+export interface TimingAnimationConfig {
+  type: 'timing';
+  config?: WithTimingConfig;
+}
+
+/**
+ * Animation configuration for popup overlay components (Dialog, Select, BottomSheet, Popover, etc.)
+ * Supports both progress-based opacity animation and entering/exiting animations
+ */
+export type PopupOverlayAnimation = Animation<{
+  /**
+   * Opacity animation configuration (progress-based)
+   * Takes effect for bottom-sheet/dialog presentation
+   * @default [0, 1, 0] - opacity values for [idle, open, close] states
+   */
+  opacity?: AnimationValue<{
+    /**
+     * Opacity values [idle, open, close]
+     * @default [0, 1, 0]
+     */
+    value?: [number, number, number];
+  }>;
+  /**
+   * Takes effect for popover presentation
+   * @default FadeIn with duration 200ms
+   */
+  entering?: EntryOrExitLayoutType;
+  /**
+   * Takes effect for popover presentation
+   * @default FadeOut with duration 150ms
+   */
+  exiting?: EntryOrExitLayoutType;
+}>;
+
+/**
+ * Animation configuration for popup dialog content components (Dialog, Select dialog presentation)
+ * Supports opacity and scale animations
+ */
+export type PopupDialogContentAnimation = Animation<{
+  /**
+   * Custom Keyframe animation for entering transition
+   * @default Keyframe with scale, and opacity (200ms)
+   */
+  entering?: EntryOrExitLayoutType;
+  /**
+   * Custom Keyframe animation for exiting transition
+   * @default Keyframe mirroring entering animation (150ms)
+   */
+  exiting?: EntryOrExitLayoutType;
+}>;
+
+/**
+ * Animation configuration for popup popover content components (Popover, Select popover presentation)
+ * Supports custom Keyframe animations for entering and exiting transitions
+ */
+export type PopupPopoverContentAnimation = Animation<{
+  /**
+   * Custom Keyframe animation for entering transition
+   * @default Keyframe with translateY/translateX, scale, and opacity (200ms)
+   */
+  entering?: EntryOrExitLayoutType;
+  /**
+   * Custom Keyframe animation for exiting transition
+   * @default Keyframe mirroring entering animation (150ms)
+   */
+  exiting?: EntryOrExitLayoutType;
+}>;

package/src/animation/utils.ts

@@ -0,0 +1,249 @@
+import type { Animation, AnimationRoot, AnimationValue } from './types';
+
+/**
+ * Check if the entire animation is disabled
+ * @param animation - Animation configuration
+ * @returns true if animation is disabled
+ */
+export function isAnimationDisabled<TConfig extends Record<string, any>>(
+  animation: Animation<TConfig> | AnimationRoot<TConfig> | undefined,
+): boolean {
+  // Check top-level disabled values
+  if (animation === false || animation === 'disabled') {
+    return true;
+  }
+
+  // Check state property in config objects
+  if (typeof animation === 'object' && animation !== null && 'state' in animation) {
+    const state = animation.state;
+    return state === false || state === 'disabled';
+  }
+
+  return false;
+}
+
+/**
+ * Check if root animation should cascade disable to all children
+ * @param animation - Root animation configuration
+ * @returns true if all animations should be disabled (including children)
+ */
+export function shouldDisableAll<TConfig extends Record<string, any>>(
+  animation: AnimationRoot<TConfig> | undefined,
+): boolean {
+  // Check top-level disable-all value
+  if (animation === 'disable-all') {
+    return true;
+  }
+
+  // Check state property in config objects
+  if (typeof animation === 'object' && animation !== null && 'state' in animation) {
+    const state = animation.state;
+    return state === 'disable-all';
+  }
+
+  return false;
+}
+
+/**
+ * Get animation state including config and disabled status
+ * @param animation - Animation configuration
+ * @returns Object with animationConfig and isAnimationDisabled
+ */
+export function getAnimationState<TConfig extends Record<string, any>>(
+  animation: Animation<TConfig> | undefined,
+): {
+  animationConfig: TConfig | undefined;
+  isAnimationDisabled: boolean;
+} {
+  const isDisabled = isAnimationDisabled(animation);
+  // Always extract config when it's an object, regardless of disabled state
+  // This allows users to customize colors/properties even when animations are disabled
+  const config =
+    typeof animation === 'object' && animation !== null ? (animation as TConfig) : undefined;
+
+  return {
+    animationConfig: config,
+    isAnimationDisabled: isDisabled,
+  };
+}
+
+/**
+ * Get root animation state including config, disabled status, and cascade flag
+ * @param animation - Root animation configuration
+ * @returns Object with animationConfig, isAnimationDisabled, and isAllAnimationsDisabled
+ */
+export function getRootAnimationState<TConfig extends Record<string, any>>(
+  animation: AnimationRoot<TConfig> | undefined,
+): {
+  animationConfig: TConfig | undefined;
+  isAnimationDisabled: boolean;
+  isAllAnimationsDisabled: boolean;
+} {
+  const shouldCascade = shouldDisableAll(animation);
+  const isDisabled = isAnimationDisabled(animation) || shouldCascade;
+  // Always extract config when it's an object, regardless of disabled state
+  // This allows users to customize colors/properties even when animations are disabled
+  const config =
+    typeof animation === 'object' && animation !== null ? (animation as TConfig) : undefined;
+
+  return {
+    animationConfig: config,
+    isAnimationDisabled: isDisabled,
+    isAllAnimationsDisabled: shouldCascade,
+  };
+}
+
+/**
+ * Get animation value property or return default
+ * Extracts a property from the animation value config object
+ *
+ * @param options - Object containing animationValue, property, and defaultValue
+ * @param options.animationValue - The animation value configuration
+ * @param options.property - Property name to extract
+ * @param options.defaultValue - Default value if property is not found
+ * @returns The property value or default (never undefined)
+ *
+ * @example
+ * const scaleValue = getAnimationValueProperty({
+ *   animationValue: animation?.scale,
+ *   property: 'value',
+ *   defaultValue: 0.95
+ * });
+ */
+export function getAnimationValueProperty<
+  TConfig extends Record<string, any>,
+  K extends keyof TConfig,
+  D extends NonNullable<TConfig[K]>,
+>(options: {
+  animationValue: AnimationValue<TConfig> | undefined;
+  property: K;
+  defaultValue: D;
+}): D {
+  // If animation value is undefined, return default
+  if (options.animationValue === undefined) {
+    return options.defaultValue;
+  }
+
+  // Return the property value if it exists, otherwise return default
+  return options.animationValue[options.property] ?? options.defaultValue;
+}
+
+/**
+ * Get animation value merged config or return default
+ * Merges the animation value config with defaults, useful when you need multiple properties
+ *
+ * @param options - Object containing animationValue, property, and defaultValue
+ * @param options.animationValue - The animation value configuration
+ * @param options.property - Property name to extract from the config
+ * @param options.defaultValue - Default configuration object
+ * @returns The merged config object or default
+ *
+ * @example
+ * const scaleConfig = getAnimationValueMergedConfig({
+ *   animationValue: animation?.scale,
+ *   property: 'timingConfig',
+ *   defaultValue: { duration: 150 }
+ * });
+ */
+export function getAnimationValueMergedConfig<
+  TConfig extends Record<string, any>,
+  K extends keyof TConfig,
+>(options: {
+  animationValue: AnimationValue<TConfig> | undefined;
+  property: K;
+  defaultValue: TConfig[K];
+}): TConfig[K] {
+  // If animation value is undefined, return default
+  if (options.animationValue === undefined) {
+    return options.defaultValue;
+  }
+
+  const value = options.animationValue[options.property];
+
+  // If the specific property value is undefined or not an object, return default
+  if (value === undefined || typeof value !== 'object') {
+    return options.defaultValue;
+  }
+
+  // Merge with defaults to ensure all properties exist
+  return { ...options.defaultValue, ...value };
+}
+
+/**
+ * Determine if animations should be disabled based on disabled flags
+ * Priority: isAllAnimationsDisabled > isAnimationDisabled
+ *
+ * @param options - Object containing isAnimationDisabled and isAllAnimationsDisabled
+ * @param options.isAnimationDisabled - Whether animation is explicitly disabled
+ * @param options.isAllAnimationsDisabled - Whether all animations should be disabled (cascading from root/global)
+ * @returns true if animations should be disabled, false otherwise
+ *
+ * @example
+ * const isDisabled = getIsAnimationDisabledValue({
+ *   isAnimationDisabled: false,
+ *   isAllAnimationsDisabled: true
+ * });
+ * // Returns: true (all animations disabled takes priority)
+ */
+export function getIsAnimationDisabledValue(options: {
+  isAnimationDisabled: boolean;
+  isAllAnimationsDisabled: boolean | undefined;
+}): boolean {
+  const { isAnimationDisabled: isDisabled, isAllAnimationsDisabled } = options;
+
+  // First priority: if all animations are disabled, return true
+  if (isAllAnimationsDisabled === true) {
+    return true;
+  }
+
+  // Second priority: if this animation is disabled, return true
+  if (isDisabled) {
+    return true;
+  }
+
+  // Default: animations are enabled
+  return false;
+}
+
+/**
+ * Combine global, parent, and own animation disabled states
+ * Priority: Global > Parent > Own (global wins if enabled)
+ *
+ * @param options - Object containing globalIsAllAnimationsDisabled, parentIsAllAnimationsDisabled, and ownIsAllAnimationsDisabled
+ * @param options.globalIsAllAnimationsDisabled - Whether global provider has disable-all (from GlobalAnimationSettingsProvider)
+ * @param options.parentIsAllAnimationsDisabled - Whether parent context has disable-all (from AnimationSettingsContext)
+ * @param options.ownIsAllAnimationsDisabled - Whether own animation prop has disable-all
+ * @returns Combined isAllAnimationsDisabled value (global || parent || own)
+ *
+ * @example
+ * const combined = getCombinedAnimationDisabledState({
+ *   globalIsAllAnimationsDisabled: true,
+ *   parentIsAllAnimationsDisabled: false,
+ *   ownIsAllAnimationsDisabled: false
+ * });
+ * // Returns: true (global wins)
+ */
+export function getCombinedAnimationDisabledState(options: {
+  globalIsAllAnimationsDisabled?: boolean;
+  parentIsAllAnimationsDisabled: boolean | undefined;
+  ownIsAllAnimationsDisabled: boolean;
+}): boolean {
+  const {
+    globalIsAllAnimationsDisabled,
+    parentIsAllAnimationsDisabled,
+    ownIsAllAnimationsDisabled,
+  } = options;
+
+  // Global always wins if it has disable-all
+  if (globalIsAllAnimationsDisabled === true) {
+    return true;
+  }
+
+  // Parent wins if it has disable-all
+  if (parentIsAllAnimationsDisabled === true) {
+    return true;
+  }
+
+  // Otherwise use own value
+  return ownIsAllAnimationsDisabled;
+}

package/src/components/Alert/index.tsx

@@ -0,0 +1,318 @@
+import React, { forwardRef, useMemo, type ReactNode } from 'react';
+import { Text, View, type TextProps, type ViewProps } from 'react-native';
+import { Slot, dataAttributes, mergeDataAttributes } from '@cdx-ui/primitives';
+import type { ForgeIcon } from '@cdx-ui/icons';
+import { CheckCircle, EmergencyHome, Info, Warning } from '@cdx-ui/icons';
+import { cn, ParentContext, useParentContext, useStyleContext } from '@cdx-ui/utils';
+import { Icon, type IconProps } from '../Icon';
+import {
+  alertActionsVariants,
+  alertBodyVariants,
+  alertDescriptionVariants,
+  alertIconVariants,
+  alertRootVariants,
+  alertTextVariants,
+  alertTitleVariants,
+  type AlertSeverity,
+  type AlertVariantProps,
+} from './styles';
+
+// =============================================================================
+// CONTEXT
+// =============================================================================
+
+const SCOPE = 'ALERT';
+
+interface AlertContextValue {
+  severity: AlertSeverity;
+}
+
+const useAlertStyleContext = (): AlertContextValue => {
+  const ctx = useStyleContext(SCOPE) as { severity?: AlertSeverity };
+  return { severity: ctx?.severity ?? 'info' };
+};
+
+// Severity → default icon mapping
+const SEVERITY_ICONS: Record<AlertSeverity, ForgeIcon> = {
+  danger: EmergencyHome,
+  warning: Warning,
+  success: CheckCircle,
+  info: Info,
+};
+
+// =============================================================================
+// ROOT
+// =============================================================================
+
+export interface AlertProps extends ViewProps, AlertVariantProps {
+  /**
+   * Replace the root element with the consumer's child element via `Slot`.
+   * When `true`, children are rendered as-is (no automatic icon/text/actions
+   * layout splitting). Severity context is still provided so sub-components
+   * receive the correct styles.
+   */
+  asChild?: boolean;
+  /** Severity level that controls background colour, icon, and live-region urgency. */
+  severity?: AlertSeverity;
+  className?: string;
+  /**
+   * Sub-components (`Alert.Icon`, `Alert.Title`, `Alert.Description`,
+   * `Alert.Actions`) must be rendered as **direct** children — wrapping them
+   * in HOCs or `memo()` will break the automatic layout splitting.
+   */
+  children?: ReactNode;
+}
+
+const AlertRoot = forwardRef<View, AlertProps>(
+  ({ asChild, severity = 'info', className, style, children, ...props }, ref) => {
+    const isAssertive = severity === 'danger' || severity === 'warning';
+    const parent = useParentContext();
+    const ctx = useMemo(() => ({ ...parent, [SCOPE]: { severity } }), [parent, severity]);
+
+    const rootClassName = cn(alertRootVariants({ severity }), className);
+    const role = isAssertive ? 'alert' : 'status';
+    const liveRegion = isAssertive ? 'assertive' : 'polite';
+    const dataProps = mergeDataAttributes(props, dataAttributes({ slot: 'alert' }));
+
+    if (asChild) {
+      return (
+        <ParentContext.Provider value={ctx}>
+          <Slot
+            ref={ref}
+            className={rootClassName}
+            style={style}
+            role={role}
+            accessibilityLiveRegion={liveRegion}
+            {...props}
+            {...dataProps}
+          >
+            {children}
+          </Slot>
+        </ParentContext.Provider>
+      );
+    }
+
+    // Split children into three regions:
+    //   1. Alert.Icon    — rendered at inline-start (left)
+    //   2. Alert.Actions — rendered at inline-end (right), beside the text
+    //   3. Everything else (Title, Description) — text column, flex-1
+    //
+    // Layout: [Icon]  [flex-1 flex-row: [text flex-1]  [Actions]]
+    const childArray = React.Children.toArray(children);
+    const iconChild = childArray.find(
+      (child) =>
+        React.isValidElement(child) && (child as React.ReactElement).type === AlertIconComponent,
+    );
+    const actionsChild = childArray.find(
+      (child) => React.isValidElement(child) && (child as React.ReactElement).type === AlertActions,
+    );
+    const textChildren = childArray.filter(
+      (child) =>
+        !React.isValidElement(child) ||
+        ((child as React.ReactElement).type !== AlertIconComponent &&
+          (child as React.ReactElement).type !== AlertActions),
+    );
+    const hasBody = textChildren.length > 0 || !!actionsChild;
+
+    return (
+      <ParentContext.Provider value={ctx}>
+        <View
+          ref={ref}
+          className={rootClassName}
+          style={style}
+          role={role}
+          accessibilityLiveRegion={liveRegion}
+          {...props}
+          {...dataProps}
+        >
+          {iconChild}
+          {hasBody ? (
+            <View className={alertBodyVariants()}>
+              {textChildren.length > 0 ? (
+                <View className={alertTextVariants()}>{textChildren}</View>
+              ) : null}
+              {actionsChild}
+            </View>
+          ) : null}
+        </View>
+      </ParentContext.Provider>
+    );
+  },
+);
+
+AlertRoot.displayName = 'Alert';
+
+// =============================================================================
+// ICON
+// =============================================================================
+
+export interface AlertIconProps extends Omit<IconProps, 'as'> {
+  asChild?: boolean;
+  /**
+   * Override the auto-rendered severity icon. Omit to use the default icon for
+   * the current severity (EmergencyHome, Warning, CheckCircle, or Info).
+   * Not required when `asChild` is set.
+   */
+  as?: ForgeIcon;
+}
+
+const AlertIconComponent = forwardRef<View, AlertIconProps>(
+  ({ asChild, as: asOverride, className, style, ...props }, ref) => {
+    const { severity } = useAlertStyleContext();
+    const computedClassName = cn(alertIconVariants({ severity }), className);
+
+    if (asChild) {
+      return (
+        <Slot
+          ref={ref}
+          className={computedClassName}
+          style={style}
+          {...props}
+          {...mergeDataAttributes(props, dataAttributes({ slot: 'alert-icon' }))}
+        />
+      );
+    }
+
+    return (
+      <Icon
+        as={asOverride ?? SEVERITY_ICONS[severity]}
+        className={computedClassName}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'alert-icon' }))}
+      />
+    );
+  },
+);
+
+AlertIconComponent.displayName = 'Alert.Icon';
+
+// =============================================================================
+// TITLE
+// =============================================================================
+
+export interface AlertTitleProps extends TextProps {
+  asChild?: boolean;
+  className?: string;
+  children?: ReactNode;
+}
+
+const AlertTitle = forwardRef<Text, AlertTitleProps>(
+  ({ asChild, className, style, children, ...props }, ref) => {
+    const { severity } = useAlertStyleContext();
+    const computedClassName = cn(alertTitleVariants({ severity }), className);
+    const Comp = asChild ? Slot : Text;
+
+    return (
+      <Comp
+        ref={ref}
+        className={computedClassName}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'alert-title' }))}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+AlertTitle.displayName = 'Alert.Title';
+
+// =============================================================================
+// DESCRIPTION
+// =============================================================================
+
+export interface AlertDescriptionProps extends TextProps {
+  asChild?: boolean;
+  className?: string;
+  children?: ReactNode;
+}
+
+const AlertDescription = forwardRef<Text, AlertDescriptionProps>(
+  ({ asChild, className, style, children, ...props }, ref) => {
+    const { severity } = useAlertStyleContext();
+    const computedClassName = cn(alertDescriptionVariants({ severity }), className);
+    const Comp = asChild ? Slot : Text;
+
+    return (
+      <Comp
+        ref={ref}
+        className={computedClassName}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'alert-description' }))}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+AlertDescription.displayName = 'Alert.Description';
+
+// =============================================================================
+// ACTIONS
+// =============================================================================
+
+export interface AlertActionsProps extends ViewProps {
+  /**
+   * Replace the wrapper element with the consumer's child via `Slot`.
+   * **Note:** when `true`, automatic `color={severity}` injection on
+   * direct `Button`/`IconButton` children is bypassed — the consumer
+   * must set `color` explicitly.
+   */
+  asChild?: boolean;
+  className?: string;
+  children?: ReactNode;
+}
+
+const AlertActions = forwardRef<View, AlertActionsProps>(
+  ({ asChild, className, style, children, ...props }, ref) => {
+    const { severity } = useAlertStyleContext();
+    const computedClassName = cn(alertActionsVariants(), className);
+    const Comp = asChild ? Slot : View;
+
+    // Auto-inject color={severity} on direct Button / IconButton children unless
+    // the consumer already provides a color prop.
+    const injectedChildren = React.Children.map(children, (child) => {
+      if (!React.isValidElement<{ color?: unknown }>(child)) return child;
+      if ('color' in child.props) return child;
+      return React.cloneElement(child, { color: severity });
+    });
+
+    return (
+      <Comp
+        ref={ref}
+        className={computedClassName}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'alert-actions' }))}
+      >
+        {asChild ? children : injectedChildren}
+      </Comp>
+    );
+  },
+);
+
+AlertActions.displayName = 'Alert.Actions';
+
+// =============================================================================
+// COMPOUND EXPORT
+// =============================================================================
+
+type AlertCompoundComponent = typeof AlertRoot & {
+  Icon: typeof AlertIconComponent;
+  Title: typeof AlertTitle;
+  Description: typeof AlertDescription;
+  Actions: typeof AlertActions;
+};
+
+export const Alert = Object.assign(AlertRoot, {
+  Icon: AlertIconComponent,
+  Title: AlertTitle,
+  Description: AlertDescription,
+  Actions: AlertActions,
+}) as AlertCompoundComponent;
+
+export type { AlertVariantProps, AlertSeverity };