@cdx-ui/components 0.1.5 → 0.1.7

package/src/components/sheet-header/index.tsx

@@ -0,0 +1,148 @@
+import { forwardRef, type ComponentRef, type ReactNode, type Ref } from 'react';
+import { Platform, View, type ViewProps } from 'react-native';
+import { cn } from '@cdx-ui/utils';
+import { ArrowBack, Close, type ForgeIcon } from '@cdx-ui/icons';
+import { Heading } from '../Heading';
+import { IconButton } from '../IconButton';
+import { Text } from '../Text';
+import {
+  SHEET_HEADER_BUTTON_SPACER,
+  SHEET_HEADER_DEFAULT_BACKGROUND,
+  SHEET_HEADER_FOCUSABLE_TITLE,
+  sheetHeaderVariants,
+} from './styles';
+
+// Shared back / title / close header row for sheet-style surfaces. Not exported from the package.
+
+const WEB_PROGRAMMATIC_FOCUS = Platform.OS === 'web' ? { tabIndex: -1 } : undefined;
+
+export type SheetHeaderTitleRef = ComponentRef<typeof Heading>;
+
+export interface SheetHeaderProps extends Omit<ViewProps, 'children'> {
+  title?: string;
+  subtitle?: string;
+  children?: ReactNode;
+  className?: string;
+  onClose?: () => void;
+  closeAccessibilityLabel?: string;
+  onBack?: () => void;
+  backAccessibilityLabel?: string;
+  /** `nativeID` for the default title, so a host surface can point `aria-labelledby` at it. */
+  titleNativeID?: string;
+  /** Ref to the default title. Not attached when `children` replaces the title. */
+  titleRef?: Ref<SheetHeaderTitleRef>;
+  /** Lets the host move focus to the default title. On web it gets `tabIndex={-1}`, so it stays out of the tab order. */
+  titleFocusable?: boolean;
+  /** Replaces the default header surface class. */
+  backgroundClassName?: string;
+}
+
+export const SheetHeader = forwardRef<View, SheetHeaderProps>(
+  (
+    {
+      title,
+      subtitle,
+      children,
+      className,
+      onClose,
+      closeAccessibilityLabel = 'Close',
+      onBack,
+      backAccessibilityLabel = 'Go back',
+      titleNativeID,
+      titleRef,
+      titleFocusable = false,
+      backgroundClassName = SHEET_HEADER_DEFAULT_BACKGROUND,
+      ...props
+    },
+    ref,
+  ) => {
+    const hasTitle = title !== undefined && title !== '';
+    const hasContent = hasTitle || !!children || !!onBack;
+    const computedClassName = cn(
+      sheetHeaderVariants({ hasTitle: hasContent }),
+      backgroundClassName,
+      className,
+    );
+
+    return (
+      <View ref={ref} className={computedClassName} {...props}>
+        {onBack ? (
+          <SheetHeaderButton
+            as={ArrowBack}
+            onPress={onBack}
+            accessibilityLabel={backAccessibilityLabel}
+          />
+        ) : (
+          <SheetHeaderButtonSpacer />
+        )}
+        <View className="flex-1">
+          {children ??
+            (hasTitle ? (
+              <View>
+                <Heading
+                  ref={titleRef}
+                  size="sm"
+                  className={cn('text-center', titleFocusable && SHEET_HEADER_FOCUSABLE_TITLE)}
+                  nativeID={titleNativeID}
+                  {...(titleFocusable ? WEB_PROGRAMMATIC_FOCUS : undefined)}
+                >
+                  {title}
+                </Heading>
+                {subtitle ? (
+                  <Text size="sm" className="text-center text-content-secondary">
+                    {subtitle}
+                  </Text>
+                ) : null}
+              </View>
+            ) : null)}
+        </View>
+        {onClose ? (
+          <SheetHeaderButton
+            as={Close}
+            onPress={onClose}
+            accessibilityLabel={closeAccessibilityLabel}
+          />
+        ) : (
+          <SheetHeaderButtonSpacer />
+        )}
+      </View>
+    );
+  },
+);
+
+SheetHeader.displayName = 'SheetHeader';
+
+interface SheetHeaderButtonProps {
+  as: ForgeIcon;
+  onPress: () => void;
+  accessibilityLabel: string;
+}
+
+function SheetHeaderButton({ as, onPress, accessibilityLabel }: Readonly<SheetHeaderButtonProps>) {
+  return (
+    <IconButton
+      as={as}
+      variant="solid"
+      color="neutral"
+      size="default"
+      onPress={onPress}
+      hitSlop={12}
+      accessibilityLabel={accessibilityLabel}
+    />
+  );
+}
+
+SheetHeaderButton.displayName = 'SheetHeader.Button';
+
+function SheetHeaderButtonSpacer() {
+  return (
+    <View
+      className={SHEET_HEADER_BUTTON_SPACER}
+      accessibilityElementsHidden
+      importantForAccessibility="no-hide-descendants"
+      aria-hidden
+    />
+  );
+}
+
+SheetHeaderButtonSpacer.displayName = 'SheetHeader.ButtonSpacer';

package/src/components/sheet-header/styles.ts

@@ -0,0 +1,28 @@
+import { cva, type VariantProps } from '@cdx-ui/utils';
+import { iconButtonSizeClassNames } from '../IconButton/styles';
+
+/** Surface behind the header row unless the host passes `backgroundClassName`. */
+export const SHEET_HEADER_DEFAULT_BACKGROUND = 'bg-surface-primary';
+
+/** Holds an absent back or close button's place so the title stays centered. */
+export const SHEET_HEADER_BUTTON_SPACER = iconButtonSizeClassNames.default;
+
+/** The title only takes programmatic focus, so it never shows a focus ring. */
+export const SHEET_HEADER_FOCUSABLE_TITLE = 'web:outline-none';
+
+export const sheetHeaderVariants = cva(
+  ['flex-row items-center justify-between min-h-11 px-4 pt-3 pb-2.5', 'text-content-primary'],
+  {
+    variants: {
+      hasTitle: {
+        true: '',
+        false: 'justify-end',
+      },
+    },
+    defaultVariants: {
+      hasTitle: true,
+    },
+  },
+);
+
+export type SheetHeaderVariants = VariantProps<typeof sheetHeaderVariants>;

package/src/providers/toast/provider.tsx

@@ -177,6 +177,7 @@ export function ToastProvider({
   disableFullWindowOverlay = false,
   unstable_accessibilityContainerViewIsModal,
   announceLabel,
+  container,
 }: Readonly<ToastProviderProps>) {
   const [toasts, dispatch] = useReducer(toastReducer, []);
 
@@ -185,7 +186,19 @@ export function ToastProvider({
    */
   const globalConfig = useMemo<ToastGlobalConfig | undefined>(() => defaultProps, [defaultProps]);
 
-  const isToastVisible = toasts.length > 0;
+  const usesWebPortal =
+    Platform.OS === 'web' && createPortalFn !== undefined && typeof document !== 'undefined';
+
+  /**
+   * A `null` container renders no viewport, so no toast can play its exit
+   * transition or be seen. Timers hold until it attaches, and hides remove
+   * directly instead of waiting on a transition that will never run.
+   */
+  const isViewportDetached = usesWebPortal && container === null;
+  const viewportDetachedRef = useRef(isViewportDetached);
+  viewportDetachedRef.current = isViewportDetached;
+
+  const isToastVisible = toasts.length > 0 && !isViewportDetached;
 
   const placementStacks = useToastPlacementStacks();
 
@@ -287,12 +300,13 @@ export function ToastProvider({
    * On web this only marks toasts as `pendingRemoval` so their CSS exit
    * transition can play; the actual removal happens when the toast
    * component calls `remove(id)` on transition end.
-   * On native this dispatches removal directly — Reanimated's `exiting`
-   * layout animation plays before unmount.
+   * On native, and on web while the container is `null`, this dispatches
+   * removal directly — Reanimated's `exiting` layout animation plays before
+   * unmount, and a detached web viewport has no transition to wait on.
    */
   const hide = useCallback(
     (ids?: (string & {}) | string[] | 'all') => {
-      const isWeb = Platform.OS === 'web';
+      const playsWebExit = Platform.OS === 'web' && !viewportDetachedRef.current;
 
       if (ids === undefined) {
         if (toasts.length === 0) return;
@@ -318,7 +332,7 @@ export function ToastProvider({
           lastToast.onHide();
         }
 
-        if (isWeb) {
+        if (playsWebExit) {
           dispatch({ type: 'MARK_CLOSED', payload: { ids: [lastToast.id] } });
         } else {
           remove([lastToast.id]);
@@ -340,7 +354,7 @@ export function ToastProvider({
 
         if (targetIds.length === 0) return;
 
-        if (isWeb) {
+        if (playsWebExit) {
           dispatch({ type: 'MARK_CLOSED', payload: { ids: targetIds } });
         } else {
           remove(targetIds);
@@ -367,7 +381,7 @@ export function ToastProvider({
 
         if (targetIds.length === 0) return;
 
-        if (isWeb) {
+        if (playsWebExit) {
           dispatch({ type: 'MARK_CLOSED', payload: { ids: targetIds } });
         } else {
           remove(targetIds);
@@ -404,6 +418,7 @@ export function ToastProvider({
    */
   const resumeAll = useCallback(() => {
     pausedRef.current = false;
+    if (viewportDetachedRef.current) return;
 
     const now = Date.now();
     timersRef.current.forEach((entry, id) => {
@@ -421,6 +436,24 @@ export function ToastProvider({
     });
   }, []);
 
+  useEffect(() => {
+    if (isViewportDetached) {
+      pauseAll();
+    } else {
+      resumeAll();
+    }
+  }, [isViewportDetached, pauseAll, resumeAll]);
+
+  /**
+   * Detaching the container unmounts toasts mid-exit, and an unmounted toast
+   * never reports its transition end.
+   */
+  useEffect(() => {
+    if (!isViewportDetached) return;
+    const pendingIds = toasts.filter((toast) => toast.pendingRemoval).map((toast) => toast.id);
+    if (pendingIds.length > 0) remove(pendingIds);
+  }, [isViewportDetached, remove, toasts]);
+
   const lifecycleContextValue = useMemo<ToastLifecycleContextValue>(() => {
     const pending = new Set<string>();
     const frontmostByPlacement = new Map<ToastPlacement, string>();
@@ -541,7 +574,7 @@ export function ToastProvider({
           };
           timersRef.current.set(id, entry);
 
-          if (pausedRef.current) {
+          if (pausedRef.current || viewportDetachedRef.current) {
             clearTimeout(timer);
             entry.timer = null;
           }
@@ -567,7 +600,7 @@ export function ToastProvider({
   );
 
   useOverlayStackRegistration({
-    active: toasts.length > 0,
+    active: isToastVisible,
     capabilities: [],
     id: 'forge-ui-toast-viewport',
     groupId: 'forge-ui-notifications',
@@ -619,10 +652,11 @@ export function ToastProvider({
       </InsetsContainer>
     ) : null;
 
-  const renderedToastViewport =
-    Platform.OS === 'web' && toastViewport && createPortalFn && typeof document !== 'undefined'
-      ? createPortalFn(toastViewport, document.body)
-      : toastViewport;
+  let renderedToastViewport: React.ReactNode = toastViewport;
+  if (usesWebPortal && toastViewport && createPortalFn) {
+    renderedToastViewport =
+      container === null ? null : createPortalFn(toastViewport, container ?? document.body);
+  }
 
   return (
     <ToastConfigContext.Provider value={globalConfig}>

package/src/providers/toast/types.ts

@@ -105,6 +105,16 @@ export interface ToastProviderProps {
    * @platform web
    */
   announceLabel?: string;
+  /**
+   * Element that receives the toast viewport instead of `document.body`.
+   *
+   * Use it to keep toasts inside an embedded surface, such as a device preview. The fixed
+   * viewport stays inside the container only when an ancestor of it creates a containing
+   * block for fixed descendants, for example through a `transform`. While `null`, such as
+   * before a callback ref attaches, no viewport renders.
+   * @platform web
+   */
+  container?: Element | null;
   /**
    * Children to render
    */
@@ -170,8 +180,9 @@ export interface ToastShowConfig extends Pick<
    */
   duration?: number | 'persistent';
   /**
-   * Optional ID for the toast
-   * If not provided, one will be generated automatically
+   * Optional ID for the toast.
+   * If omitted, one is generated. If a toast with this id is already in the
+   * stack, `show` returns that id and does not add another.
    */
   id?: string;
   /**
@@ -221,8 +232,9 @@ export interface ToastShowConfig extends Pick<
  */
 export interface ToastShowOptionsWithComponent {
   /**
-   * Optional ID for the toast
-   * If not provided, one will be generated automatically
+   * Optional ID for the toast.
+   * If omitted, one is generated. If a toast with this id is already in the
+   * stack, `show` returns that id and does not add another.
    */
   id?: string;
   /**