@ankhorage/surface 4.3.0 → 4.4.0

package/src/features/popover/adapters/inbound/PopoverOverlay.tsx

@@ -0,0 +1,72 @@
+import React from 'react';
+import { Pressable, StyleSheet, View, type ViewStyle } from 'react-native';
+
+import { Portal } from '../../../../internal/overlay/Portal';
+import type { PopoverPlacement } from '../../../../types/popover';
+import { usePopoverLayout } from './usePopoverLayout';
+
+/*** Renders and positions one mounted popover overlay for an open anchor. */
+export function PopoverOverlay({
+  anchorRef,
+  children,
+  closeOnOutsidePress,
+  offset,
+  onClose,
+  passive,
+  placement,
+  testID,
+}: PopoverOverlayProps) {
+  const { onContentLayout, position, ready } = usePopoverLayout({
+    anchorRef,
+    offset,
+    open: true,
+    placement,
+  });
+
+  return (
+    <Portal layer="popover" visible={ready}>
+      <View pointerEvents="box-none" style={styles.overlay}>
+        {closeOnOutsidePress ? (
+          <Pressable
+            accessibilityLabel="Close popover"
+            onPress={passive ? undefined : onClose}
+            style={styles.backdrop}
+            testID={testID ? `${testID}-backdrop` : undefined}
+          />
+        ) : null}
+        <View
+          onLayout={onContentLayout}
+          style={[styles.content, position]}
+          testID={testID ? `${testID}-content` : undefined}
+        >
+          {children}
+        </View>
+      </View>
+    </Portal>
+  );
+}
+
+interface PopoverOverlayProps {
+  anchorRef: React.RefObject<View | null>;
+  children?: React.ReactNode;
+  closeOnOutsidePress: boolean;
+  offset: number;
+  onClose: () => void;
+  passive: boolean;
+  placement: PopoverPlacement;
+  testID?: string;
+}
+
+const absoluteFill: ViewStyle = {
+  bottom: 0,
+  left: 0,
+  position: 'absolute',
+  right: 0,
+  top: 0,
+};
+
+const styles = StyleSheet.create({
+  backdrop: absoluteFill,
+  content: { position: 'absolute' },
+  overlay: absoluteFill,
+});

package/src/features/popover/adapters/inbound/usePopoverLayout.ts

@@ -0,0 +1,51 @@
+import React from 'react';
+import {
+  type LayoutChangeEvent,
+  type LayoutRectangle,
+  useWindowDimensions,
+  type View,
+} from 'react-native';
+
+import type { PopoverPlacement } from '../../../../types/popover';
+import { resolvePopoverPosition } from '../../utils/resolvePopoverPosition';
+
+/*** Measures the anchor and resolves the current viewport-safe popover position. */
+export function usePopoverLayout({ anchorRef, offset, open, placement }: UsePopoverLayoutInput) {
+  const [anchorLayout, setAnchorLayout] = React.useState<LayoutRectangle | null>(null);
+  const [contentSize, setContentSize] = React.useState({ height: 0, width: 0 });
+  const { height: viewportHeight, width: viewportWidth } = useWindowDimensions();
+
+  const measureAnchor = React.useCallback(() => {
+    anchorRef.current?.measureInWindow((x, y, width, height) => {
+      setAnchorLayout({ height, width, x, y });
+    });
+  }, [anchorRef]);
+
+  React.useEffect(() => {
+    if (open) measureAnchor();
+  }, [measureAnchor, open]);
+
+  const onContentLayout = React.useCallback((event: LayoutChangeEvent) => {
+    setContentSize(event.nativeEvent.layout);
+  }, []);
+
+  const position = anchorLayout
+    ? resolvePopoverPosition({
+        anchor: anchorLayout,
+        contentSize,
+        offset,
+        placement,
+        viewport: { height: viewportHeight, width: viewportWidth },
+        viewportPadding: 8,
+      })
+    : undefined;
+
+  return { measureAnchor, onContentLayout, position, ready: Boolean(anchorLayout) };
+}
+
+interface UsePopoverLayoutInput {
+  anchorRef: React.RefObject<View | null>;
+  offset: number;
+  open: boolean;
+  placement: PopoverPlacement;
+}

package/src/features/popover/public.ts

@@ -0,0 +1,2 @@
+export type { PopoverAnchorRenderProps, PopoverPlacement, PopoverProps } from '../../types/popover';
+export { Popover } from './adapters/inbound/Popover';

package/src/features/popover/utils/resolvePopoverPosition.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'bun:test';
+
+import { resolvePopoverPosition } from './resolvePopoverPosition';
+
+describe('resolvePopoverPosition', () => {
+  it('places bottom-start content below the anchor', () => {
+    expect(
+      resolvePopoverPosition({
+        anchor: { height: 40, width: 120, x: 100, y: 80 },
+        contentSize: { height: 180, width: 240 },
+        offset: 8,
+        placement: 'bottom-start',
+        viewport: { height: 800, width: 1200 },
+        viewportPadding: 8,
+      }),
+    ).toEqual({ left: 100, top: 128 });
+  });
+
+  it('clamps content to the available viewport', () => {
+    expect(
+      resolvePopoverPosition({
+        anchor: { height: 40, width: 80, x: 980, y: 700 },
+        contentSize: { height: 240, width: 300 },
+        offset: 8,
+        placement: 'bottom-end',
+        viewport: { height: 800, width: 1200 },
+        viewportPadding: 8,
+      }),
+    ).toEqual({ left: 760, top: 552 });
+  });
+});

package/src/features/popover/utils/resolvePopoverPosition.ts

@@ -0,0 +1,40 @@
+import type { PopoverPlacement } from '../../../types/popover';
+
+/*** Resolves a viewport-clamped anchored position for popover content. */
+export function resolvePopoverPosition({
+  anchor,
+  contentSize,
+  offset,
+  placement,
+  viewport,
+  viewportPadding,
+}: {
+  anchor: { height: number; width: number; x: number; y: number };
+  contentSize: { height: number; width: number };
+  offset: number;
+  placement: PopoverPlacement;
+  viewport: { height: number; width: number };
+  viewportPadding: number;
+}): { left: number; top: number } {
+  const anchorCenterX = anchor.x + anchor.width / 2;
+  const rawLeft = placement.endsWith('-start')
+    ? anchor.x
+    : placement.endsWith('-end')
+      ? anchor.x + anchor.width - contentSize.width
+      : anchorCenterX - contentSize.width / 2;
+  const rawTop = placement.startsWith('top')
+    ? anchor.y - contentSize.height - offset
+    : anchor.y + anchor.height + offset;
+  const maxLeft = Math.max(viewportPadding, viewport.width - contentSize.width - viewportPadding);
+  const maxTop = Math.max(viewportPadding, viewport.height - contentSize.height - viewportPadding);
+
+  return {
+    left: clamp(rawLeft, viewportPadding, maxLeft),
+    top: clamp(rawTop, viewportPadding, maxTop),
+  };
+}
+
+/*** Clamps one numeric position into the available viewport range. */
+function clamp(value: number, minimum: number, maximum: number): number {
+  return Math.min(Math.max(value, minimum), maximum);
+}

package/src/{components/toast → features/toast/adapters/inbound}/Toast.tsx

@@ -1,45 +1,15 @@
 import React from 'react';
-import { Pressable } from 'react-native';
+import { Pressable, StyleSheet, type ViewStyle } from 'react-native';
 
-import { Box } from '../../features/layout/public';
-import { Surface } from '../../features/surface/public';
-import { Text } from '../../features/typography/public';
-import { Inline } from '../../layout';
-import type { SurfaceColor } from '../../surfaceColor';
-import { useTheme } from '../../theme/ThemeContext';
-import type { SurfaceTheme } from '../../theme/types';
-import type { ToastProps } from './types';
-
-function resolveToastStatusColor(theme: SurfaceTheme, status: ToastProps['status']) {
-  switch (status) {
-    case 'success':
-      return theme.semantics.success.base;
-    case 'warning':
-      return theme.semantics.warning.base;
-    case 'error':
-      return theme.semantics.error.base;
-    case 'info':
-      return theme.semantics.info.base;
-    default:
-      return theme.semantics.action.primary.base;
-  }
-}
-
-function resolveToastStatusTextColor(status: ToastProps['status']): SurfaceColor {
-  switch (status) {
-    case 'success':
-      return 'success';
-    case 'warning':
-      return 'warning';
-    case 'error':
-      return 'error';
-    case 'info':
-      return 'info';
-    default:
-      return 'primary';
-  }
-}
+import type { SurfaceColor } from '../../../../surfaceColor';
+import { useTheme } from '../../../../theme/ThemeContext';
+import type { SurfaceTheme } from '../../../../theme/types';
+import type { ToastProps } from '../../../../types/toast';
+import { Box, Stack } from '../../../layout/public';
+import { Surface } from '../../../surface/public';
+import { Text } from '../../../typography/public';
 
+/*** Renders one transient toast notification. */
 export function Toast({
   title,
   description,
@@ -52,22 +22,14 @@ export function Toast({
   const statusColor = resolveToastStatusColor(theme, status);
   const statusTextColor = resolveToastStatusTextColor(status);
   const passive = interactionPolicy === 'passive';
+  const statusStyle = React.useMemo<ViewStyle>(
+    () => ({ borderLeftColor: statusColor }),
+    [statusColor],
+  );
 
   return (
-    <Surface
-      p="m"
-      style={{
-        borderLeftColor: statusColor,
-        borderLeftWidth: 3,
-        minWidth: 280,
-        shadowOpacity: 0.14,
-        shadowRadius: 12,
-        shadowOffset: { width: 0, height: 6 },
-      }}
-      testID={testID}
-      variant="raised"
-    >
-      <Inline align="center" justify="space-between">
+    <Surface p="m" style={[styles.root, statusStyle]} testID={testID} variant="raised">
+      <Stack align="center" direction="row" justify="space-between">
         <Box flex={1}>
           {title ? (
             <Text variant="label" weight="medium">
@@ -86,7 +48,49 @@ export function Toast({
             <Text color={statusTextColor}>×</Text>
           </Pressable>
         ) : null}
-      </Inline>
+      </Stack>
     </Surface>
   );
 }
+
+/*** Resolves the border color representing a toast status. */
+function resolveToastStatusColor(theme: SurfaceTheme, status: ToastProps['status']) {
+  switch (status) {
+    case 'success':
+      return theme.semantics.success.base;
+    case 'warning':
+      return theme.semantics.warning.base;
+    case 'error':
+      return theme.semantics.error.base;
+    case 'info':
+      return theme.semantics.info.base;
+    default:
+      return theme.semantics.action.primary.base;
+  }
+}
+
+/*** Resolves the semantic text color representing a toast status. */
+function resolveToastStatusTextColor(status: ToastProps['status']): SurfaceColor {
+  switch (status) {
+    case 'success':
+      return 'success';
+    case 'warning':
+      return 'warning';
+    case 'error':
+      return 'error';
+    case 'info':
+      return 'info';
+    default:
+      return 'primary';
+  }
+}
+
+const styles = StyleSheet.create({
+  root: {
+    borderLeftWidth: 3,
+    minWidth: 280,
+    shadowOffset: { height: 6, width: 0 },
+    shadowOpacity: 0.14,
+    shadowRadius: 12,
+  },
+});

package/src/features/toast/adapters/inbound/ToastProvider.tsx

@@ -0,0 +1,47 @@
+import React from 'react';
+import { StyleSheet, type ViewStyle } from 'react-native';
+
+import { Portal } from '../../../../internal/overlay/Portal';
+import { resolveOverlayAnimation } from '../../../../internal/resolvers';
+import type { ToastProviderProps } from '../../../../types/toast';
+import { Stack } from '../../../layout/public';
+import { ToastContext } from '../../composition/ToastContext';
+import { useToastRuntime } from '../../composition/useToastRuntime';
+import { Toast } from './Toast';
+
+/*** Provides the toast runtime context and renders its shared portal host. */
+export function ToastProvider({ children, defaultDuration = 4000 }: ToastProviderProps) {
+  const animation = resolveOverlayAnimation('toast');
+  const { controller, toasts } = useToastRuntime(defaultDuration);
+  const animationStyle = React.useMemo<ViewStyle>(
+    () => ({ paddingTop: 16 + animation.offset }),
+    [animation.offset],
+  );
+
+  return (
+    <ToastContext value={controller}>
+      {children}
+      <Portal layer="toast" visible={toasts.length > 0}>
+        <Stack gap="s" pointerEvents="box-none" style={[styles.container, animationStyle]}>
+          {toasts.map((toast) => (
+            <Toast
+              description={toast.description}
+              key={toast.id}
+              onDismiss={() => controller.dismissToast(toast.id)}
+              status={toast.status}
+              testID={toast.testID}
+              title={toast.title}
+            />
+          ))}
+        </Stack>
+      </Portal>
+    </ToastContext>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    alignItems: 'flex-end',
+    padding: 16,
+  },
+});

package/src/features/toast/adapters/inbound/useToast.test.tsx

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'bun:test';
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+
+import { useToast } from './useToast';
+
+describe('useToast', () => {
+  it('requires ToastProvider', () => {
+    function Consumer() {
+      useToast();
+      return null;
+    }
+
+    expect(() => renderToStaticMarkup(<Consumer />)).toThrow(
+      'useToast must be used within <ToastProvider>.',
+    );
+  });
+});

package/src/features/toast/adapters/inbound/useToast.ts

@@ -0,0 +1,15 @@
+import { use } from 'react';
+
+import type { ToastController } from '../../../../types/toast';
+import { ToastContext } from '../../composition/ToastContext';
+
+/*** Returns the toast controller installed by ToastProvider. */
+export function useToast(): ToastController {
+  const controller = use(ToastContext);
+
+  if (!controller) {
+    throw new Error('useToast must be used within <ToastProvider>.');
+  }
+
+  return controller;
+}

package/src/features/toast/composition/ToastContext.ts

@@ -0,0 +1,6 @@
+import { createContext } from 'react';
+
+import type { ToastController } from '../../../types/toast';
+
+/*** Stores the toast controller shared by ToastProvider and useToast. */
+export const ToastContext = createContext<ToastController | null>(null);

package/src/features/toast/composition/useToastRuntime.ts

@@ -0,0 +1,76 @@
+import React from 'react';
+
+import type { ToastController, ToastOptions } from '../../../types/toast';
+
+/*** Owns the toast queue, dismissal timers, and imperative controller state. */
+export function useToastRuntime(defaultDuration: number) {
+  const [toasts, setToasts] = React.useState<ToastEntry[]>([]);
+  const timersRef = React.useRef(new Map<string, ReturnType<typeof setTimeout>>());
+  const counterRef = React.useRef(0);
+
+  const dismissToast = React.useCallback((id: string) => {
+    const timer = timersRef.current.get(id);
+    if (timer) {
+      clearTimeout(timer);
+      timersRef.current.delete(id);
+    }
+    setToasts((current) => current.filter((toast) => toast.id !== id));
+  }, []);
+
+  const showToast = React.useCallback((options: ToastOptions) => {
+    const id = options.id ?? `toast-${counterRef.current++}`;
+    setToasts((current) => [...current, { ...options, id }]);
+    return id;
+  }, []);
+
+  useToastTimers({ defaultDuration, dismissToast, timersRef, toasts });
+
+  const controller = React.useMemo<ToastController>(
+    () => ({ dismissToast, showToast }),
+    [dismissToast, showToast],
+  );
+
+  return { controller, toasts };
+}
+
+interface ToastEntry extends ToastOptions {
+  id: string;
+}
+
+interface UseToastTimersInput {
+  defaultDuration: number;
+  dismissToast: (id: string) => void;
+  timersRef: React.RefObject<Map<string, ReturnType<typeof setTimeout>>>;
+  toasts: readonly ToastEntry[];
+}
+
+/*** Synchronizes toast lifetimes with timer side effects and cleans them up on unmount. */
+function useToastTimers({ defaultDuration, dismissToast, timersRef, toasts }: UseToastTimersInput) {
+  React.useEffect(() => {
+    const timers = timersRef.current;
+
+    toasts.forEach((toast) => {
+      if (timers.has(toast.id)) return;
+
+      const timer = setTimeout(() => dismissToast(toast.id), toast.duration ?? defaultDuration);
+      timers.set(toast.id, timer);
+    });
+
+    const activeToastIds = new Set(toasts.map((toast) => toast.id));
+    timers.forEach((timer, id) => {
+      if (!activeToastIds.has(id)) {
+        clearTimeout(timer);
+        timers.delete(id);
+      }
+    });
+  }, [defaultDuration, dismissToast, timersRef, toasts]);
+
+  React.useEffect(() => {
+    const timers = timersRef.current;
+
+    return () => {
+      timers.forEach((timer) => clearTimeout(timer));
+      timers.clear();
+    };
+  }, [timersRef]);
+}

package/src/features/toast/public.ts

@@ -0,0 +1,10 @@
+export type {
+  ToastController,
+  ToastOptions,
+  ToastProps,
+  ToastProviderProps,
+  ToastStatus,
+} from '../../types/toast';
+export { Toast } from './adapters/inbound/Toast';
+export { ToastProvider } from './adapters/inbound/ToastProvider';
+export { useToast } from './adapters/inbound/useToast';

package/src/index.test.ts

@@ -28,7 +28,9 @@ const expectedFeatureRootExports = [
   "export { Image } from './features/image/public';",
   "export { KeyboardAvoidingView } from './features/keyboard-avoiding-view/public';",
   "export { Box, Container, Divider, Grid, Stack } from './features/layout/public';",
+  "export { Popover } from './features/popover/public';",
   "export { Surface } from './features/surface/public';",
+  "export { Toast, ToastProvider, useToast } from './features/toast/public';",
   "export { Heading, Text } from './features/typography/public';",
 ] as const;
 
@@ -42,7 +44,6 @@ const expectedLegacyRootExports = [
   "export { Switch } from './components/switch';",
   "export { Tab, TabList, TabPanel, Tabs } from './components/tabs';",
   "export { Textarea } from './components/textarea';",
-  "export { Toast, ToastProvider, useToast } from './components/toast';",
   "export { Tooltip } from './components/tooltip';",
   "export type { InteractionPolicy, InteractionPolicyProps } from './interactionPolicy';",
   "export * from './core/responsive';",
@@ -63,6 +64,7 @@ describe('feature-owned root barrel contract', () => {
       './components/icon-button',
       './components/radio',
       './components/text-input',
+      './components/toast',
       './primitives/heading',
       './primitives/icon',
       './primitives/image',

package/src/index.ts

@@ -16,8 +16,6 @@ export type { TabListProps, TabPanelProps, TabProps, TabsProps } from './compone
 export { Tab, TabList, TabPanel, Tabs } from './components/tabs';
 export type { TextareaProps } from './components/textarea';
 export { Textarea } from './components/textarea';
-export type { ToastOptions, ToastProps, ToastStatus } from './components/toast';
-export { Toast, ToastProvider, useToast } from './components/toast';
 export type { TooltipProps } from './components/tooltip';
 export { Tooltip } from './components/tooltip';
 export type { FontRuntime } from './context/FontContext';
@@ -76,8 +74,22 @@ export type {
   StackProps,
 } from './features/layout/public';
 export { Box, Container, Divider, Grid, Stack } from './features/layout/public';
+export type {
+  PopoverAnchorRenderProps,
+  PopoverPlacement,
+  PopoverProps,
+} from './features/popover/public';
+export { Popover } from './features/popover/public';
 export type { SurfaceProps, SurfaceVariant } from './features/surface/public';
 export { Surface } from './features/surface/public';
+export type {
+  ToastController,
+  ToastOptions,
+  ToastProps,
+  ToastProviderProps,
+  ToastStatus,
+} from './features/toast/public';
+export { Toast, ToastProvider, useToast } from './features/toast/public';
 export type { HeadingLevel, HeadingProps, TextProps } from './features/typography/public';
 export { Heading, Text } from './features/typography/public';
 export type { InteractionPolicy, InteractionPolicyProps } from './interactionPolicy';

package/src/internal/overlay/OverlayProvider.tsx

@@ -22,10 +22,7 @@ const styles = StyleSheet.create({
   },
 });
 
-function overlayZIndex(zIndex: number): ViewStyle {
-  return { zIndex };
-}
-
+/*** Installs the shared overlay stack used by portal-based Surface features. */
 export function OverlayProvider({ children }: { children: React.ReactNode }) {
   const orderRef = React.useRef(0);
   const [overlays, setOverlays] = React.useState<OverlayEntry[]>([]);
@@ -65,8 +62,8 @@ export function OverlayProvider({ children }: { children: React.ReactNode }) {
   );
 
   return (
-    <OverlayStackActionsContext.Provider value={actions}>
-      <OverlayStackContext.Provider value={value}>
+    <OverlayStackActionsContext value={actions}>
+      <OverlayStackContext value={value}>
         {children}
         <View {...boxNonePointerEvents.props} style={[boxNonePointerEvents.style, styles.fill]}>
           {overlays.map((overlay) => (
@@ -79,7 +76,12 @@ export function OverlayProvider({ children }: { children: React.ReactNode }) {
             </View>
           ))}
         </View>
-      </OverlayStackContext.Provider>
-    </OverlayStackActionsContext.Provider>
+      </OverlayStackContext>
+    </OverlayStackActionsContext>
   );
 }
+
+/*** Resolves a per-entry z-index style for the overlay host. */
+function overlayZIndex(zIndex: number): ViewStyle {
+  return { zIndex };
+}

package/src/internal/overlay/useOverlayStack.ts

@@ -48,7 +48,7 @@ export const OverlayStackContext = React.createContext<OverlayStackRuntime | nul
 export const OverlayStackActionsContext = React.createContext<OverlayStackActions | null>(null);
 
 export function useOverlayStackActions(): OverlayStackActions | null {
-  return React.useContext(OverlayStackActionsContext);
+  return React.use(OverlayStackActionsContext);
 }
 
 export function createOverlayEntry(

package/src/internal/resolvers/resolveOverlayZIndex.test.ts

@@ -5,7 +5,8 @@ import { resolveOverlayZIndex } from './resolveOverlayZIndex';
 describe('resolveOverlayZIndex', () => {
   it('assigns higher base layers to later overlay types', () => {
     expect(resolveOverlayZIndex('modal')).toBeLessThan(resolveOverlayZIndex('menu'));
-    expect(resolveOverlayZIndex('menu')).toBeLessThan(resolveOverlayZIndex('tooltip'));
+    expect(resolveOverlayZIndex('menu')).toBeLessThan(resolveOverlayZIndex('popover'));
+    expect(resolveOverlayZIndex('popover')).toBeLessThan(resolveOverlayZIndex('tooltip'));
     expect(resolveOverlayZIndex('tooltip')).toBeLessThan(resolveOverlayZIndex('toast'));
   });
 

package/src/internal/resolvers/resolveOverlayZIndex.ts

@@ -1,9 +1,10 @@
-export type OverlayLayer = 'modal' | 'drawer' | 'menu' | 'tooltip' | 'toast';
+export type OverlayLayer = 'modal' | 'drawer' | 'menu' | 'popover' | 'tooltip' | 'toast';
 
 const BASE_Z_INDEX: Record<OverlayLayer, number> = {
   modal: 1000,
   drawer: 1100,
   menu: 1200,
+  popover: 1250,
   tooltip: 1300,
   toast: 1400,
 };

package/src/layout/AppBar.tsx

@@ -26,7 +26,7 @@ export function AppBar({
   ...props
 }: AppBarProps) {
   const { theme } = useTheme();
-  const insets = React.useContext(SafeAreaInsetsContext);
+  const insets = React.use(SafeAreaInsetsContext);
   const topInset = safeAreaTop ? (insets?.top ?? 0) : 0;
   const safeAreaStyle: ViewStyle | undefined =
     topInset === 0 ? undefined : { paddingTop: topInset };