@cdx-ui/components 0.3.4 → 0.3.6

package/src/components/SystemAlert/index.tsx

@@ -0,0 +1,684 @@
+import {
+  forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentType,
+  type ForwardedRef,
+  type ReactNode,
+} from 'react';
+import {
+  AccessibilityInfo,
+  Platform,
+  Text,
+  View,
+  type LayoutChangeEvent,
+  type TextProps,
+  type ViewProps,
+  type ViewStyle,
+} from 'react-native';
+import Animated from 'react-native-reanimated';
+import { SafeAreaInsetsContext } from 'react-native-safe-area-context';
+import { Slot, dataAttributes, mergeDataAttributes } from '@cdx-ui/primitives';
+import type { ForgeIcon } from '@cdx-ui/icons';
+import {
+  CheckCircle,
+  Close,
+  EmergencyHome,
+  Error as ErrorIcon,
+  Info,
+  Warning,
+} from '@cdx-ui/icons';
+import {
+  cn,
+  createContext,
+  getTextContent,
+  mergeRefs,
+  ParentContext,
+  useParentContext,
+  useStyleContext,
+} from '@cdx-ui/utils';
+import type { AnimationRootDisableAll } from '../../animation';
+import { Button, type ButtonProps } from '../Button';
+import { Icon, type IconProps } from '../Icon';
+import { IconButton, type IconButtonProps } from '../IconButton';
+import {
+  useSystemAlertPresence,
+  useSystemAlertSurfaceStyle,
+  type SystemAlertPresence as SystemAlertPresenceState,
+} from './animation';
+import {
+  systemAlertActionLabelVariants,
+  systemAlertActionVariants,
+  systemAlertActionsVariants,
+  systemAlertBodyVariants,
+  systemAlertCloseIconVariants,
+  systemAlertCloseVariants,
+  systemAlertDescriptionVariants,
+  systemAlertIconActionIconVariants,
+  systemAlertIconActionVariants,
+  systemAlertIconVariants,
+  systemAlertPresenceClipVariants,
+  systemAlertPresenceSurfaceVariants,
+  systemAlertPresenceVariants,
+  systemAlertRootVariants,
+  type SystemAlertColor,
+  type SystemAlertVariantProps,
+} from './styles';
+
+// =============================================================================
+// CONTEXT
+// =============================================================================
+
+const SCOPE = 'SYSTEM_ALERT';
+
+interface SystemAlertContextValue {
+  color: SystemAlertColor;
+  hasClose: boolean;
+}
+
+const useSystemAlertStyleContext = (): SystemAlertContextValue => {
+  const ctx = useStyleContext(SCOPE) as Partial<SystemAlertContextValue> | undefined;
+  return { color: ctx?.color ?? 'info', hasClose: ctx?.hasClose ?? false };
+};
+
+interface SystemAlertDescriptionRegistry {
+  /** `owner` identifies the Description instance, so one unmounting never clears another's text. */
+  registerDescription: (owner: object, text: string | null) => void;
+}
+
+// Provided only in presence mode, so a static banner's Description never registers.
+const [SystemAlertDescriptionRegistryProvider, useSystemAlertDescriptionRegistry] = createContext<
+  SystemAlertDescriptionRegistry | undefined
+>('SystemAlertDescriptionRegistry', { strict: false });
+
+const COLOR_ICONS: Record<SystemAlertColor, ForgeIcon> = {
+  danger: EmergencyHome,
+  warning: Warning,
+  success: CheckCircle,
+  info: Info,
+  brand: ErrorIcon,
+};
+
+// =============================================================================
+// PRESENCE (internal, `isOpen` only)
+// =============================================================================
+
+const AnimatedSlot = Animated.createAnimatedComponent(Slot as ComponentType<ViewProps>);
+
+// Screen-reader focus on a leaving surface would land somewhere unpredictable.
+const EXITING_SURFACE_PROPS = {
+  importantForAccessibility: 'no-hide-descendants',
+  accessibilityElementsHidden: true,
+  pointerEvents: 'none',
+} as const satisfies ViewProps;
+
+// `scroll` clips like `hidden` on iOS and Android, but Yoga caps a child's flex-basis height at
+// its parent's height unless the parent's overflow is `scroll`. Under `hidden`, the moving
+// wrapper's fixed height caps the surface, iOS lays the description out as one clipped line,
+// and the banner jumps by a line when it settles. Inline because Uniwind compiles
+// `overflow-scroll` to `{ x, y }` keys that React Native ignores.
+const NATIVE_WRAPPER_STYLE = { overflow: 'scroll' } as const satisfies ViewStyle;
+
+// RNW ignores the native hiding props and deprecates the `pointerEvents` prop.
+const WEB_EXITING_SURFACE_PROPS = { 'aria-hidden': true } as const satisfies ViewProps;
+const WEB_EXITING_SURFACE_STYLE = { pointerEvents: 'none' } as const satisfies ViewStyle;
+
+interface SystemAlertPresenceSurfaceProps extends ViewProps {
+  presence: SystemAlertPresenceState;
+  asChild?: boolean;
+  className: string;
+  surfaceRef: ForwardedRef<View>;
+}
+
+function SystemAlertPresenceSurface({
+  presence,
+  asChild,
+  surfaceRef,
+  style,
+  onLayout,
+  children,
+  ...props
+}: SystemAlertPresenceSurfaceProps) {
+  const { setSurfaceHeight, phase } = presence;
+  const isWeb = Platform.OS === 'web';
+  const nodeRef = useRef<View | null>(null);
+  const ref = useMemo(() => mergeRefs(surfaceRef, nodeRef), [surfaceRef]);
+  const surfaceStyle = useSystemAlertSurfaceStyle(presence);
+
+  useLayoutEffect(() => {
+    const node = nodeRef.current;
+    // RNW's `measure` is deferred, which would let the first frames transition toward 0.
+    if (isWeb) {
+      const element = node as unknown as HTMLElement | null;
+      if (typeof element?.getBoundingClientRect === 'function') {
+        setSurfaceHeight(element.getBoundingClientRect().height);
+      }
+      return;
+    }
+    if (typeof node?.measure !== 'function') return;
+    node.measure((_x, _y, _width, height) => {
+      setSurfaceHeight(height);
+    });
+  }, [isWeb, setSurfaceHeight]);
+
+  const handleLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      onLayout?.(event);
+      setSurfaceHeight(event.nativeEvent.layout.height);
+    },
+    [onLayout, setSurfaceHeight],
+  );
+
+  const isExiting = phase === 'exiting';
+
+  if (isWeb) {
+    const WebComp = asChild ? Slot : View;
+    return (
+      <WebComp
+        ref={ref}
+        style={[style, isExiting ? WEB_EXITING_SURFACE_STYLE : undefined]}
+        {...props}
+        {...(isExiting ? WEB_EXITING_SURFACE_PROPS : undefined)}
+        onLayout={handleLayout}
+      >
+        {children}
+      </WebComp>
+    );
+  }
+
+  const Comp = asChild ? AnimatedSlot : Animated.View;
+
+  return (
+    <Comp
+      ref={ref}
+      style={[style, surfaceStyle]}
+      {...props}
+      {...(isExiting ? EXITING_SURFACE_PROPS : undefined)}
+      onLayout={handleLayout}
+    >
+      {children}
+    </Comp>
+  );
+}
+
+interface SystemAlertPresenceProps extends Omit<SystemAlertPresenceSurfaceProps, 'presence'> {
+  isOpen: boolean;
+  animation: AnimationRootDisableAll | undefined;
+  collapsedHeight: number;
+  isAssertive: boolean;
+  liveRegion: ViewProps['accessibilityLiveRegion'];
+}
+
+function SystemAlertPresence({
+  isOpen,
+  animation,
+  collapsedHeight,
+  isAssertive,
+  liveRegion,
+  ...surfaceProps
+}: SystemAlertPresenceProps) {
+  const presence = useSystemAlertPresence({ isOpen, animation, collapsedHeight });
+
+  const descriptionRef = useRef<{ owner: object; text: string } | null>(null);
+  const registerDescription = useCallback((owner: object, text: string | null) => {
+    if (text !== null) {
+      descriptionRef.current = { owner, text };
+    } else if (descriptionRef.current?.owner === owner) {
+      descriptionRef.current = null;
+    }
+  }, []);
+  const registry = useMemo(() => ({ registerDescription }), [registerDescription]);
+
+  // iOS has no live regions. Announce on the open edge only, after the newly mounted
+  // Description has registered, and without waiting for the slide.
+  const wasOpenRef = useRef(isOpen);
+  useEffect(() => {
+    const wasOpen = wasOpenRef.current;
+    wasOpenRef.current = isOpen;
+    if (!isOpen || wasOpen || Platform.OS !== 'ios') return;
+
+    const text = descriptionRef.current?.text ?? '';
+    if (!text) {
+      if (__DEV__) {
+        console.warn(
+          '[SystemAlert] Opened without an announcement: `SystemAlert.Description` children must contain text. Text a component resolves itself, outside its children, cannot be read.',
+        );
+      }
+      return;
+    }
+    AccessibilityInfo.announceForAccessibilityWithOptions(text, { queue: !isAssertive });
+  }, [isOpen, isAssertive]);
+
+  const surface = presence.isSurfaceMounted ? (
+    <SystemAlertPresenceSurface presence={presence} {...surfaceProps} />
+  ) : null;
+
+  // Web announces the surface's `role` insertion; an `aria-live` wrapper around it could
+  // announce it twice.
+  if (Platform.OS === 'web') {
+    return (
+      <SystemAlertDescriptionRegistryProvider value={registry}>
+        <View
+          ref={presence.wrapperRef}
+          className={systemAlertPresenceVariants()}
+          style={{ height: presence.webWrapperHeight, minHeight: collapsedHeight }}
+          {...dataAttributes({ state: presence.webState })}
+        >
+          <View
+            className={systemAlertPresenceClipVariants()}
+            style={{ height: presence.webWrapperHeight }}
+            {...dataAttributes({ state: presence.webState })}
+          >
+            {surface}
+          </View>
+        </View>
+      </SystemAlertDescriptionRegistryProvider>
+    );
+  }
+
+  // The live region sits on the wrapper, which stays mounted while closed, so TalkBack
+  // hears the open as a change inside an existing region.
+  return (
+    <SystemAlertDescriptionRegistryProvider value={registry}>
+      <Animated.View
+        className={systemAlertPresenceVariants()}
+        style={[NATIVE_WRAPPER_STYLE, presence.wrapperStyle]}
+        accessibilityLiveRegion={liveRegion}
+      >
+        {surface}
+      </Animated.View>
+    </SystemAlertDescriptionRegistryProvider>
+  );
+}
+
+// =============================================================================
+// ROOT
+// =============================================================================
+
+export interface SystemAlertProps extends ViewProps, SystemAlertVariantProps {
+  /**
+   * Replace the root element with the consumer's child element via `Slot`.
+   * When `true`, children render as-is: no body row and no close button.
+   * The `color` context is still provided so sub-components receive the correct styles.
+   */
+  asChild?: boolean;
+  /**
+   * Colour treatment. Drives the surface, the default icon, and live-region urgency:
+   * `danger` and `warning` announce assertively, the rest politely.
+   * @default 'info'
+   */
+  color?: SystemAlertColor;
+  /**
+   * Pad the top of the root by the top safe-area inset so the surface paints behind
+   * the status bar and the content row starts below it. Set `false` for a banner that
+   * does not sit at the top edge of the screen. The inset is zero on web and without a
+   * safe-area provider.
+   * @default true
+   */
+  hasSafeAreaInset?: boolean;
+  /** Renders a dismiss button as the last control in the row. */
+  onClose?: () => void;
+  /**
+   * Accessible name for the dismiss button.
+   * @default 'Dismiss alert'
+   */
+  closeAccessibilityLabel?: string;
+  /**
+   * Controlled presence. Omit it for a banner that shows while mounted, with no motion.
+   * When set, SystemAlert stays mounted and owns presence: `false` → `true` slides the
+   * banner down from the top edge and pushes the content below it, and `true` → `false`
+   * reverses that, then removes the surface. `true` on first render shows the banner in
+   * place without motion. While closed with `hasSafeAreaInset`, a transparent strip the
+   * height of the top inset stays reserved, so the header below never applies the inset.
+   * Pick one mode per mount: switching between omitted and set is not supported.
+   */
+  isOpen?: boolean;
+  /**
+   * Pass `'disable-all'` to open and close in one frame, without motion. Has no effect
+   * without `isOpen`.
+   */
+  animation?: AnimationRootDisableAll;
+  className?: string;
+  /**
+   * Rendered in order inside the content row, typically `SystemAlert.Icon`,
+   * `SystemAlert.Description`, and `SystemAlert.Actions`.
+   */
+  children?: ReactNode;
+}
+
+const SystemAlertRoot = forwardRef<View, SystemAlertProps>(
+  (
+    {
+      asChild,
+      isOpen,
+      animation,
+      color = 'info',
+      hasSafeAreaInset = true,
+      onClose,
+      closeAccessibilityLabel = 'Dismiss alert',
+      className,
+      style,
+      children,
+      ...props
+    },
+    ref,
+  ) => {
+    const insets = useContext(SafeAreaInsetsContext);
+    const hasClose = !!onClose;
+    const parent = useParentContext();
+    const ctx = useMemo(
+      () => ({ ...parent, [SCOPE]: { color, hasClose } }),
+      [parent, color, hasClose],
+    );
+
+    const isAssertive = color === 'danger' || color === 'warning';
+    const role = isAssertive ? 'alert' : 'status';
+    const liveRegion = isAssertive ? 'assertive' : 'polite';
+    const insetTop = hasSafeAreaInset ? (insets?.top ?? 0) : 0;
+    const rootStyle = hasSafeAreaInset ? [{ paddingTop: insetTop }, style] : style;
+    const dataProps = mergeDataAttributes(props, dataAttributes({ slot: 'system-alert' }));
+
+    const body = asChild ? null : (
+      <View className={systemAlertBodyVariants()}>
+        {children}
+        {onClose ? (
+          <IconButton
+            as={Close}
+            variant="ghost"
+            size="small"
+            onPress={onClose}
+            accessibilityLabel={closeAccessibilityLabel}
+            className={systemAlertCloseVariants({ color })}
+            iconClassName={systemAlertCloseIconVariants({ color })}
+            {...dataAttributes({ slot: 'system-alert-close' })}
+          />
+        ) : null}
+      </View>
+    );
+
+    if (isOpen !== undefined) {
+      return (
+        <ParentContext.Provider value={ctx}>
+          <SystemAlertPresence
+            isOpen={isOpen}
+            animation={animation}
+            collapsedHeight={insetTop}
+            isAssertive={isAssertive}
+            liveRegion={liveRegion}
+            surfaceRef={ref}
+            asChild={asChild}
+            className={cn(
+              systemAlertRootVariants({ color }),
+              systemAlertPresenceSurfaceVariants(),
+              className,
+            )}
+            style={rootStyle}
+            role={role}
+            {...props}
+            {...dataProps}
+          >
+            {asChild ? children : body}
+          </SystemAlertPresence>
+        </ParentContext.Provider>
+      );
+    }
+
+    const rootClassName = cn(systemAlertRootVariants({ color }), className);
+
+    if (asChild) {
+      return (
+        <ParentContext.Provider value={ctx}>
+          <Slot
+            ref={ref}
+            className={rootClassName}
+            style={rootStyle}
+            role={role}
+            accessibilityLiveRegion={liveRegion}
+            {...props}
+            {...dataProps}
+          >
+            {children}
+          </Slot>
+        </ParentContext.Provider>
+      );
+    }
+
+    return (
+      <ParentContext.Provider value={ctx}>
+        <View
+          ref={ref}
+          className={rootClassName}
+          style={rootStyle}
+          role={role}
+          accessibilityLiveRegion={liveRegion}
+          {...props}
+          {...dataProps}
+        >
+          {body}
+        </View>
+      </ParentContext.Provider>
+    );
+  },
+);
+
+SystemAlertRoot.displayName = 'SystemAlert';
+
+// =============================================================================
+// ICON
+// =============================================================================
+
+export interface SystemAlertIconProps extends Omit<IconProps, 'as' | 'color'> {
+  asChild?: boolean;
+  /**
+   * Override the default icon for the current `color` (`EmergencyHome`, `Warning`,
+   * `CheckCircle`, `Info`, or `Error` for `brand`). Not required when `asChild` is set.
+   */
+  as?: ForgeIcon;
+}
+
+const SystemAlertIcon = forwardRef<View, SystemAlertIconProps>(
+  ({ asChild, as: asOverride, className, style, ...props }, ref) => {
+    const { color } = useSystemAlertStyleContext();
+    const computedClassName = cn(systemAlertIconVariants({ color }), className);
+    const dataProps = mergeDataAttributes(props, dataAttributes({ slot: 'system-alert-icon' }));
+
+    if (asChild) {
+      return (
+        <Slot ref={ref} className={computedClassName} style={style} {...props} {...dataProps} />
+      );
+    }
+
+    return (
+      <Icon
+        as={asOverride ?? COLOR_ICONS[color]}
+        className={computedClassName}
+        style={style}
+        {...props}
+        {...dataProps}
+      />
+    );
+  },
+);
+
+SystemAlertIcon.displayName = 'SystemAlert.Icon';
+
+// =============================================================================
+// DESCRIPTION
+// =============================================================================
+
+export interface SystemAlertDescriptionProps extends TextProps {
+  asChild?: boolean;
+  className?: string;
+  /**
+   * Message text. Wraps by default; pass `numberOfLines` to clamp it. With `isOpen` on the
+   * root, its plain text is what iOS announces when the banner opens, so it must be passed
+   * as children rather than resolved inside a child component.
+   */
+  children?: ReactNode;
+}
+
+const SystemAlertDescription = forwardRef<Text, SystemAlertDescriptionProps>(
+  ({ asChild, className, style, children, ...props }, ref) => {
+    const { color } = useSystemAlertStyleContext();
+    const registry = useSystemAlertDescriptionRegistry();
+    const [owner] = useState(() => ({}));
+    const text = registry ? getTextContent(children) : '';
+
+    useLayoutEffect(() => {
+      registry?.registerDescription(owner, text);
+    }, [registry, owner, text]);
+
+    useLayoutEffect(() => () => registry?.registerDescription(owner, null), [registry, owner]);
+
+    const computedClassName = cn(systemAlertDescriptionVariants({ color }), className);
+    const Comp = asChild ? Slot : Text;
+
+    return (
+      <Comp
+        ref={ref}
+        className={computedClassName}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'system-alert-description' }))}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+SystemAlertDescription.displayName = 'SystemAlert.Description';
+
+// =============================================================================
+// ACTIONS
+// =============================================================================
+
+export interface SystemAlertActionsProps extends ViewProps {
+  asChild?: boolean;
+  className?: string;
+  /** Typically `SystemAlert.Action` and `SystemAlert.IconAction`. */
+  children?: ReactNode;
+}
+
+const SystemAlertActions = forwardRef<View, SystemAlertActionsProps>(
+  ({ asChild, className, style, children, ...props }, ref) => {
+    const { hasClose } = useSystemAlertStyleContext();
+    const computedClassName = cn(systemAlertActionsVariants({ hasClose }), className);
+    const Comp = asChild ? Slot : View;
+
+    return (
+      <Comp
+        ref={ref}
+        className={computedClassName}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'system-alert-actions' }))}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+SystemAlertActions.displayName = 'SystemAlert.Actions';
+
+// =============================================================================
+// ACTION
+// =============================================================================
+
+export interface SystemAlertActionProps extends Omit<
+  ButtonProps,
+  'variant' | 'color' | 'size' | 'fullWidth' | 'asChild'
+> {
+  className?: string;
+  /** Label text, rendered inside `Button.Label`. */
+  children?: ReactNode;
+}
+
+const SystemAlertAction = forwardRef<View, SystemAlertActionProps>(
+  ({ className, children, ...props }, ref) => {
+    const { color } = useSystemAlertStyleContext();
+
+    return (
+      <Button
+        ref={ref}
+        variant="ghost"
+        size="small"
+        className={cn(systemAlertActionVariants({ color }), className)}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'system-alert-action' }))}
+      >
+        <Button.Label className={systemAlertActionLabelVariants({ color })}>
+          {children}
+        </Button.Label>
+      </Button>
+    );
+  },
+);
+
+SystemAlertAction.displayName = 'SystemAlert.Action';
+
+// =============================================================================
+// ICON ACTION
+// =============================================================================
+
+export interface SystemAlertIconActionProps extends Omit<
+  IconButtonProps,
+  'variant' | 'color' | 'size' | 'accessibilityLabel'
+> {
+  /** Forge icon component to render. */
+  as: ForgeIcon;
+  /** Accessible name. Required: the control has no visible text. */
+  accessibilityLabel: string;
+}
+
+const SystemAlertIconAction = forwardRef<View, SystemAlertIconActionProps>(
+  ({ className, iconClassName, ...props }, ref) => {
+    const { color } = useSystemAlertStyleContext();
+
+    return (
+      <IconButton
+        ref={ref}
+        variant="ghost"
+        size="small"
+        className={cn(systemAlertIconActionVariants({ color }), className)}
+        iconClassName={cn(systemAlertIconActionIconVariants({ color }), iconClassName)}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'system-alert-icon-action' }))}
+      />
+    );
+  },
+);
+
+SystemAlertIconAction.displayName = 'SystemAlert.IconAction';
+
+// =============================================================================
+// COMPOUND EXPORT
+// =============================================================================
+
+type SystemAlertCompoundComponent = typeof SystemAlertRoot & {
+  Icon: typeof SystemAlertIcon;
+  Description: typeof SystemAlertDescription;
+  Actions: typeof SystemAlertActions;
+  Action: typeof SystemAlertAction;
+  IconAction: typeof SystemAlertIconAction;
+};
+
+export const SystemAlert = Object.assign(SystemAlertRoot, {
+  Icon: SystemAlertIcon,
+  Description: SystemAlertDescription,
+  Actions: SystemAlertActions,
+  Action: SystemAlertAction,
+  IconAction: SystemAlertIconAction,
+}) as SystemAlertCompoundComponent;
+
+export type { SystemAlertColor, SystemAlertVariantProps };
+export {
+  useSystemAlertStatusBarStyle,
+  type SystemAlertStatusBarStyle,
+} from './useSystemAlertStatusBarStyle';