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

package/src/animation/hooks/useCombinedAnimationDisabledState.ts

@@ -0,0 +1,46 @@
+import {
+  useGlobalAnimationSettings,
+  useAnimationSettings,
+} from '../../providers/animation-settings';
+import type { AnimationRoot } from '../types';
+import { getCombinedAnimationDisabledState, getRootAnimationState } from '../utils';
+
+/**
+ * Hook to combine global, parent, and own animation disabled states
+ *
+ * @description
+ * This hook combines three sources of animation disabled state:
+ * 1. Global state from GlobalAnimationSettingsProvider
+ * 2. Parent state from AnimationSettingsContext (component tree cascading)
+ * 3. Own state from the component's animation prop
+ *
+ * Priority: Global > Parent > Own (global wins if enabled)
+ *
+ * @param animation - Root animation configuration for the component
+ * @returns Combined isAllAnimationsDisabled value
+ *
+ * @example
+ * ```tsx
+ * const isAllAnimationsDisabled = useCombinedAnimationDisabledState(animation);
+ * ```
+ */
+export function useCombinedAnimationDisabledState<TConfig extends Record<string, any>>(
+  animation: AnimationRoot<TConfig> | undefined,
+): boolean {
+  // Get global animation disabled state
+  const { globalIsAllAnimationsDisabled } = useGlobalAnimationSettings();
+
+  // Read parent animation disabled state from global context
+  const parentAnimationSettingsContext = useAnimationSettings();
+  const parentIsAllAnimationsDisabled = parentAnimationSettingsContext?.isAllAnimationsDisabled;
+
+  // Get own animation disabled state
+  const { isAllAnimationsDisabled: ownIsAllAnimationsDisabled } = getRootAnimationState(animation);
+
+  // Combine global, parent, and own disable-all states (global > parent > own)
+  return getCombinedAnimationDisabledState({
+    globalIsAllAnimationsDisabled,
+    parentIsAllAnimationsDisabled,
+    ownIsAllAnimationsDisabled,
+  });
+}

package/src/animation/index.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './hooks';
+export * from './utils';

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/CLAUDE.md

@@ -120,7 +120,7 @@ Where: **styled layer.** Pure styling hint with no behavior or a11y semantics
 Each component follows this structure (see `Button/index.tsx`):
 
 1. **Imports** — RN base components, primitive `Root` and `Slot` from `@cdx-ui/primitives`, `cn` + style context from `@cdx-ui/utils`, variant functions from `./styles`
-2. **Scope constant** — `const SCOPE = 'COMPONENT_NAME'` for `withStyleContext` / `useStyleContext` (or a `ParentContext.Provider` wrapper for static variant context)
+2. **Scope constant** — `const SCOPE = 'COMPONENT_NAME'` for `useStyleContext` with a `ParentContext.Provider` wrapper for static variant context
 3. **Root component** — renders the primitive Root (or a host element directly when no primitive exists), spreads `dataAttributes({ slot: '<component>' })`
 4. **Sub-slots** — each accepts `asChild`, renders a host element via `const Comp = asChild ? Slot : DefaultElement`, spreads `dataAttributes({ slot: '<component>-<slot>' })`. Sub-slots **do not** call `useButtonContext()` (or its equivalent) unless their own styling reacts to interaction state.
 5. **Position-aware sub-slots** — icon/spinner-style slots accept `position?: 'leading' | 'trailing'` and emit `data-icon` via `dataAttributes({ icon: '...' })`.

package/src/components/Card/index.tsx

@@ -1,6 +1,7 @@
-import { forwardRef, type ReactNode } from 'react';
+import { forwardRef, useMemo, type ReactNode } from 'react';
 import { View, type ViewProps } from 'react-native';
-import { cn, useStyleContext, withStyleContext } from '@cdx-ui/utils';
+import { Slot, dataAttributes, mergeDataAttributes } from '@cdx-ui/primitives';
+import { cn, ParentContext, useParentContext, useStyleContext } from '@cdx-ui/utils';
 import {
   cardContentVariants,
   cardFooterVariants,
@@ -17,29 +18,34 @@ import {
 
 const SCOPE = 'CARD';
 
-const Root = withStyleContext(View, SCOPE);
-
 const useCardStyleContext = () => useStyleContext(SCOPE) as CardVariantProps;
 
 export interface CardProps extends ViewProps, CardVariantProps {
+  asChild?: boolean;
   className?: string;
   children?: ReactNode;
 }
 
 const CardRoot = forwardRef<View, CardProps>(
-  ({ className, children, style, fullBleed, ...props }, ref) => {
+  ({ asChild, className, children, style, fullBleed, ...props }, ref) => {
+    const parent = useParentContext();
+    const ctx = useMemo(() => ({ ...parent, [SCOPE]: { fullBleed } }), [parent, fullBleed]);
+
     const computedClassName = cn(cardRootVariants(), className);
+    const Comp = asChild ? Slot : View;
 
     return (
-      <Root
-        ref={ref}
-        className={computedClassName}
-        style={style}
-        context={{ fullBleed }}
-        {...props}
-      >
-        {children}
-      </Root>
+      <ParentContext.Provider value={ctx}>
+        <Comp
+          ref={ref}
+          className={computedClassName}
+          style={style}
+          {...props}
+          {...mergeDataAttributes(props, dataAttributes({ slot: 'card' }))}
+        >
+          {children}
+        </Comp>
+      </ParentContext.Provider>
     );
   },
 );
@@ -51,18 +57,26 @@ CardRoot.displayName = 'Card';
 // =============================================================================
 
 export interface CardHeaderProps extends ViewProps {
+  asChild?: boolean;
   className?: string;
   children?: ReactNode;
 }
 
 const CardHeader = forwardRef<View, CardHeaderProps>(
-  ({ className, children, style, ...props }, ref) => {
+  ({ asChild, className, children, style, ...props }, ref) => {
     const computedClassName = cn(cardHeaderVariants(), className);
+    const Comp = asChild ? Slot : View;
 
     return (
-      <View ref={ref} className={computedClassName} style={style} {...props}>
+      <Comp
+        ref={ref}
+        className={computedClassName}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'card-header' }))}
+      >
         {children}
-      </View>
+      </Comp>
     );
   },
 );
@@ -74,22 +88,30 @@ CardHeader.displayName = 'Card.Header';
 // =============================================================================
 
 export interface CardContentProps extends ViewProps, CardContentVariantProps {
+  asChild?: boolean;
   className?: string;
   children?: ReactNode;
 }
 
 const CardContent = forwardRef<View, CardContentProps>(
-  ({ className, children, style, fullBleed, ...props }, ref) => {
+  ({ asChild, className, children, style, fullBleed, ...props }, ref) => {
     const { fullBleed: fullBleedFromContext } = useCardStyleContext();
     const computedClassName = cn(
       cardContentVariants({ fullBleed: fullBleed ?? fullBleedFromContext }),
       className,
     );
+    const Comp = asChild ? Slot : View;
 
     return (
-      <View ref={ref} className={computedClassName} style={style} {...props}>
+      <Comp
+        ref={ref}
+        className={computedClassName}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'card-content' }))}
+      >
         {children}
-      </View>
+      </Comp>
     );
   },
 );
@@ -101,22 +123,30 @@ CardContent.displayName = 'Card.Content';
 // =============================================================================
 
 export interface CardFooterProps extends ViewProps, CardFooterVariantProps {
+  asChild?: boolean;
   className?: string;
   children?: ReactNode;
 }
 
 const CardFooter = forwardRef<View, CardFooterProps>(
-  ({ className, children, style, fullBleed, ...props }, ref) => {
+  ({ asChild, className, children, style, fullBleed, ...props }, ref) => {
     const { fullBleed: fullBleedFromContext } = useCardStyleContext();
     const computedClassName = cn(
       cardFooterVariants({ fullBleed: fullBleed ?? fullBleedFromContext }),
       className,
     );
+    const Comp = asChild ? Slot : View;
 
     return (
-      <View ref={ref} className={computedClassName} style={style} {...props}>
+      <Comp
+        ref={ref}
+        className={computedClassName}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'card-footer' }))}
+      >
         {children}
-      </View>
+      </Comp>
     );
   },
 );
@@ -133,8 +163,8 @@ type CardCompoundComponent = typeof CardRoot & {
   Footer: typeof CardFooter;
 };
 
-export const Card = CardRoot as CardCompoundComponent;
-
-Card.Header = CardHeader;
-Card.Content = CardContent;
-Card.Footer = CardFooter;
+export const Card = Object.assign(CardRoot, {
+  Header: CardHeader,
+  Content: CardContent,
+  Footer: CardFooter,
+}) as CardCompoundComponent;