@fluentui-react-native/callout 0.28.5 → 0.29.2

package/src/Callout.types.ts

@@ -1,17 +1,8 @@
 import type * as React from 'react';
-import type { KeyboardMetrics, ViewStyle } from 'react-native';
+import type { AnimatableNumericValue, ColorValue, KeyboardMetrics, ViewProps } from 'react-native';
 
-import type { IViewProps } from '@fluentui-react-native/adapters';
-import type { IBackgroundColorTokens, IBorderTokens } from '@fluentui-react-native/tokens';
-import type { IRenderData } from '@uifabricshared/foundation-composable';
-
-import type { CalloutNativeCommands } from './CalloutNativeComponent';
 export const calloutName = 'Callout';
 
-/**
- * Properties and Tokens for FluentUI React Native Callout
- */
-
 export type DirectionalHint =
   | 'leftTopEdge'
   | 'leftCenter'
@@ -24,7 +15,6 @@ export type DirectionalHint =
   | 'rightCenter'
   | 'rightBottomEdge'
   | 'bottomLeftEdge'
-  | 'bottonLeftEdge' // Typo in the original code, should be 'bottomLeftEdge'
   | 'bottomAutoEdge'
   | 'bottomCenter'
   | 'bottomRightEdge';
@@ -33,196 +23,84 @@ export type DismissBehaviors = 'preventDismissOnKeyDown' | 'preventDismissOnClic
 
 export interface RestoreFocusEvent {
   nativeEvent: {
-    /**
-     * containsFocus is true if the Callout had focus while being dismissed.
-     */
+    /** True when the Callout contained focus while it was dismissed. */
     containsFocus: boolean;
   };
 }
 
-interface OmittedBorderTokens {
-  borderStyle?: ViewStyle['borderStyle'];
-}
-
-type CalloutBorderTokens = Omit<IBorderTokens, keyof OmittedBorderTokens>;
-
-export interface ICalloutTokens extends IBackgroundColorTokens, CalloutBorderTokens {
-  /**
-   * AnchorRect arbitrary anchor rectangle; coordinate system is in DIPs, relative
-   * to the React surface origin.
-   */
+/**
+ * Optional native appearance and positioning values. Callout applies only values
+ * supplied by the caller and does not resolve theme defaults.
+ */
+export interface CalloutTokens {
+  /** Anchor rectangle in DIPs relative to the React surface origin. */
   anchorRect?: KeyboardMetrics;
-
-  /**
-   * Width of the beak on the Callout indicating its anchor.
-   */
+  /** Native Callout background color. */
+  backgroundColor?: ColorValue;
+  /** Width of the beak that points toward the anchor. */
   beakWidth?: number;
-
-  /**
-   * Defines the suggested drop direction and alignment for the Callout to use, relative
-   * to the anchor information.
-   */
+  /** Native Callout border color. */
+  borderColor?: ColorValue;
+  /** Native Callout corner radius. */
+  borderRadius?: AnimatableNumericValue | string;
+  /** Native Callout border width. */
+  borderWidth?: number;
+  /** Preferred placement relative to the anchor. */
   directionalHint?: DirectionalHint;
-
-  /**
-   * Defines variations on how the callout dismissal may be controlled.  the async eventing
-   * of React-Native makes passing some aspects of dismissal control over to JS difficult.
-   * Moreover, the native platform or host may have competing priorities with regards to transient UI
-   * that generate bi-directional lifetime management between JS (which mounts and unmounts the
-   * component) and native (which may tear down the transient UI without JS input).
-   *
-   * This property provides control over the latter issue, enabling relevant native platform
-   * interactions with transient UI to be managed from JS.
-   *
-   * These behaviors should generally be orthogonal, and therefore combinable.
-   */
+  /** Native dismissal behaviors that may be combined. */
   dismissBehaviors?: DismissBehaviors[];
-
-  /**
-   * Defines the size of the gap between the anchor and the Callout.  Not used if
-   * no anchor information is provided.
-   */
+  /** Gap between the anchor and Callout. */
   gapSpace?: number;
-
-  /**
-   * Defines a maximum height for the Callout.
-   */
+  /** Maximum Callout height. */
   maxHeight?: number | `${number}%`;
-
-  /**
-   * Defines a maximum width for the Callout.
-   */
+  /** Maximum Callout width. */
   maxWidth?: number | `${number}%`;
-
-  /**
-   * Defines a minimum width for the Callout.
-   */
+  /** Minimum padding from display edges. */
+  minPadding?: number;
+  /** Minimum Callout width. */
   minWidth?: number | `${number}%`;
+}
 
-  /**
-   * Defines the minimum padding between the Callout and the display edges.
-   */
-  minPadding?: number;
+export interface CalloutHandle {
+  /** Makes the native Callout window resign key status. */
+  blurWindow: () => void;
+  /** Makes the native Callout window key. */
+  focusWindow: () => void;
 }
 
-export interface ICalloutProps extends IViewProps, ICalloutTokens {
+export interface CalloutProps extends ViewProps, CalloutTokens {
   /**
-   * A string that should be announced when the callout is shown.
+   * A string announced when the Callout is shown.
    * @platform win32
    */
   accessibilityOnShowAnnouncement?: string;
-
+  /** Ref used to invoke native Callout window commands. */
+  componentRef?: React.Ref<CalloutHandle>;
   /**
-   * A RefObject to access the IFocusable interface. Use this to access the public methods and properties of the component.
-   */
-  componentRef?: React.RefObject<CalloutNativeCommands>;
-
-  /**
-   * Defines event redirection behaviors for pointer events relative to the Callout control.
-   *
-   * Pointer events (i.e. mouse, pen, touch) often have the effect of initiating and dismissing Callout controls.
-   * Typically the instigating events are click events, but when using a mouse may also include pointer enter
-   * and leave events i.e. hover.  Once opened, many Callout scenarios desire modal-like interactions, where
-   * the user must interact with or relative to the Callout before interacting with other controls again. A common
-   * example is context menus, where pointer events away from the menu may dismiss the context menu.  Such an interaction
-   * can initiate unintended actions such as invoking a button or otherwise pointer-responsive surface.  The modal-like
-   * behavior is the most common case of Callout usage, and having "safe" areas to press-dismiss the Callout without
-   * invoking additional actions is useful.
-   *
-   * This modal-like behavior, where true modal behavior would specifically require interacting with the modal component until
-   * it is dismissed, has implications for canonical event routing in React-Native.  Canonically all pointer events are passed in
-   * a Capture phase from the root element to the target element, then bubbled back from the target element to the root element.
-   * This structure allows many interaction patterns to be implemented that may include stopping event routing in each phase.
-   * This event routing can disrupt the modal-like behavior desired by a Callout control, which in native frameworks may take
-   * advantage of a "take event capture" feature -- making the Callout the first handler of the pointer event.  The event may optionally
-   * be forwarded afterwards to the canonical event routing pattern for further handling (and often is not forwarded).
-   *
-   * One impact of "taking event capture" is the implicit behavior for mouse events on the parent surface of the Callout -- if
-   * event capture is taken by the Callout, paired events may fire such as a mouse leave event.  This makes sense if we think about
-   * the event behavior after the Callout has taken capture; mouse enter and mouse leave events would only propagate to the parent surface
-   * if the Callout event handling decided to forward said events (often not).  As paired events, however, there should not be a
-   * mouse enter event without a corresponding mouse leave event (or vice versa).  Since mouse enter and mouse leave events would not
-   * naturally fire on the parent surface when the Callout has pointer capture, the parent surface should receive a mouse leave event when
-   * the Callout takes capture.
-   *
-   * Coming back to the start of this comment, some Callout scenarios may be initiated by mouse enter/leave events.  A common example is
-   * tooltips, which are supported on lower-level React-Native components, but such behavior is not exclusive to tooltips.
-   * The Callout control is generally used for more advanced scenarios, as mentioned before often desiring modal-like behavior and accordingly
-   * the default behavior of the Callout control is to take pointer capture.  Accounting for the paired mouse enter/leave events in the paragraph
-   * above, it is difficult to have a mouse enter/leave-invoked Callout that takes pointer capture -- without significant workarounds,
-   * the Callout would open and close cyclically from repeated mouse enter/leave events.  There are other scenarios where taking pointer capture
-   * is not desirable, such as a semi-persistent Callout; to support these scenarios the doNotTakePointerCapture property is offered to
-   * specify if the Callout should not take pointer capture when it opens.
-   *
-   * While pointer capture is generally managed in native frameworks via imperative APIs, managing pointer capture is offered as a property that
-   * only affects the Callout's on-show behavior when it would typically take pointer capture.  This design implies that changing this property after
-   * the Callout has been shown has no effect -- similar to the Callout's onShow callback.  Doing so simplifies Callout usage for developers,
-   * not needing to mind native platform pointer capture that may be complex particularly when React-Native is integrated into a larger app.
-   * Pointer capture may be lost (and regained) but is otherwise abstracted away from the developer.  More advanced control of pointer capture
-   * would need to be provided by a native module independent of any particular control.
-   *
-   * When the Callout is closed, pointer capture is released by the Callout and further handled by the native platform -- generally returning
-   * pointer capture to the parent surface.
+   * Prevents the native Callout from taking pointer capture when shown.
    * @platform win32
    */
   doNotTakePointerCapture?: boolean;
-
-  /**
-   * Adds a beak to the Callout, pointing to the anchor target.
-   * Notable Win32 limitation: Beak rendering currently limits the border width to its default, and the
-   * border width prop will not be honored.
-   * @platform win32
-   */
+  /** Displays a beak that points toward the anchor. */
   isBeakVisible?: boolean;
-
-  /**
-   * Callback invoked when the callout has been dismissed.
-   */
+  /** Invoked after native dismissal. */
   onDismiss?: () => void;
-
   /**
-   * Callback invoked during callout dismissal; if set, focus will not be restored by the callout and onRestoreFocus must
-   * result in focus being moved to the appropriate focusable target.
-   *
-   * The callee should carefully consider their scenarios to avoid dropping focus, or inappropriately
-   * moving focus from another component.  Focus is not guaranteed to have entered the React-Native surface at all, and
-   * this callback is most appropriate for components strictly controlling focus.
-   *
-   * restoreFocusEvent.nativeEvent.containsFocus is true if the Callout had focus while being dismissed.
+   * Invoked during dismissal when the caller owns focus restoration.
    * @platform win32
    */
-  onRestoreFocus?: (restoreFocusEvent: RestoreFocusEvent) => void;
-
-  /**
-   * Callback invoked when the callout has been shown.
-   */
+  onRestoreFocus?: (event: RestoreFocusEvent) => void;
+  /** Invoked after the Callout is shown. */
   onShow?: () => void;
-
-  /**
-   * Determines whether the Callout sets focus when displayed.
-   * On macOS: this determines whether the Callout becomes the key window.
-   * On win32: If true then the callout will attempt to focus the first focusable element that it contains.
-   * If it doesn't find an element, no focus will be set. This means that it's the contents responsibility
-   * to either set focus or have focusable items.
-   */
+  /** Requests initial focus when the Callout is shown. */
   setInitialFocus?: boolean;
-
-  /**
-   * Target node the callout uses for relative positioning; the anchor of the callout.
-   * A ref is the typical usage; certain components may proffer a string as an anchor target, such as
-   * anchoring to a point inside the component.
-   */
-  target?: React.RefObject<React.Component> | string;
+  /** Ref or registered native anchor identifier used for relative positioning. */
+  target?: React.RefObject<React.Component | null> | string;
 }
 
-export type ICalloutSlotProps = {
-  root: ICalloutProps;
-};
-
-export type ICalloutRenderData = IRenderData<ICalloutSlotProps>;
-
-export interface ICalloutType {
-  props: ICalloutProps;
-  slotProps: ICalloutSlotProps;
-  tokens: ICalloutTokens;
-}
+/** @deprecated Use CalloutProps. */
+export type ICalloutProps = CalloutProps;
+/** @deprecated Use CalloutTokens. */
+export type ICalloutTokens = CalloutTokens;
+/** @deprecated Use CalloutHandle. */
+export type CalloutNativeCommands = CalloutHandle;

package/src/CalloutNativeComponent.ts

@@ -19,12 +19,16 @@ export interface NativeProps extends ViewProps {
   accessibilityOnShowAnnouncement?: string;
   anchorRect?: AnchorRect;
 
+  beakWidth?: Int32;
   dismissBehaviors?: string[];
   doNotTakePointerCapture?: boolean;
   focusable?: boolean;
+  gapSpace?: Int32;
   isBeakVisible?: boolean;
   maxHeight?: Int32;
   maxWidth?: Int32;
+  minPadding?: Int32;
+  minWidth?: Int32;
   setInitialFocus?: boolean;
 
   // targetAnchor?: string; // Win32 only Callout can target an anchor registered in the anchor registry // Can be a node id or an anchor ID - This need to be reworked as Mixed types are not supported going forward
@@ -46,24 +50,25 @@ export interface NativeProps extends ViewProps {
     | 'rightCenter'
     | 'rightBottomEdge'
     | 'bottomLeftEdge'
-    | 'bottonLeftEdge' // Typo in the original code, should be 'bottomLeftEdge'
     | 'bottomAutoEdge'
     | 'bottomCenter'
     | 'bottomRightEdge',
-    'bottonLeftEdge'
+    'bottomLeftEdge'
   >;
   target?: UnsafeMixed;
 }
 
 export type CalloutComponentType = HostComponent<NativeProps>;
 
-export interface CalloutNativeCommands {
+interface NativeCalloutCommands {
   focusWindow: (viewRef: React.ElementRef<CalloutComponentType>) => void;
   blurWindow: (viewRef: React.ElementRef<CalloutComponentType>) => void;
 }
 
-export const Commands: CalloutNativeCommands = codegenNativeCommands<CalloutNativeCommands>({
+export const Commands: NativeCalloutCommands = codegenNativeCommands<NativeCalloutCommands>({
   supportedCommands: ['blurWindow', 'focusWindow'],
 });
 
-export default codegenNativeComponent<NativeProps>('RCTCallout') as CalloutComponentType;
+export default codegenNativeComponent<NativeProps>('Callout', {
+  paperComponentName: 'RCTCallout',
+}) as CalloutComponentType;

package/src/__tests__/Callout.test.tsx

@@ -1,13 +1,157 @@
-import { act } from 'react';
+/** @jsxImportSource @fluentui-react-native/framework-base */
+import * as React from 'react';
+import { StyleSheet, Text, View } from 'react-native';
 
-import * as renderer from 'react-test-renderer';
+import { act, render } from '@testing-library/react-native';
+import { isPhasedComponent, useSlot } from '@fluentui-react-native/framework-base';
+import type { SlotProp } from '@fluentui-react-native/framework-base';
 
-import { Callout } from '..';
+import { Callout } from '../Callout';
+import type { CalloutHandle } from '../Callout.types';
+import { Commands } from '../CalloutNativeComponent';
 
-it('Callout default props', () => {
-  let component: renderer.ReactTestRenderer;
-  act(() => {
-    component = renderer.create(<Callout />);
+jest.mock('react-native/Libraries/ReactNative/RendererProxy', () => ({
+  ...jest.requireActual('react-native/Libraries/ReactNative/RendererProxy'),
+  findNodeHandle: jest.fn(() => 42),
+}));
+
+type CalloutSlotConsumerProps = {
+  callout: SlotProp<typeof Callout>;
+};
+
+function CalloutSlotConsumer({ callout }: CalloutSlotConsumerProps) {
+  const CalloutSlot = useSlot(Callout, callout);
+  return (
+    <CalloutSlot accessibilityHint="rendered as a slot" testID="slotted-callout">
+      <Text>Slot content</Text>
+    </CalloutSlot>
+  );
+}
+
+describe('Callout', () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('uses phased rendering and applies native-safe default styling', async () => {
+    expect(isPhasedComponent(Callout)).toBe(true);
+
+    const component = await render(<Callout testID="callout" />);
+    const callout = component.getByTestId('callout');
+
+    expect(callout.type).toBe('RCTCallout');
+    expect(StyleSheet.flatten(callout.props.style)).toMatchSnapshot();
+  });
+
+  it('translates caller-supplied appearance values and preserves user style precedence', async () => {
+    const component = await render(
+      <Callout
+        backgroundColor="red"
+        borderColor="green"
+        borderRadius={8}
+        borderWidth={2}
+        maxHeight={240}
+        maxWidth="80%"
+        minWidth={120}
+        style={{ backgroundColor: 'blue', opacity: 0.5 }}
+        testID="callout"
+      />,
+    );
+    const callout = component.getByTestId('callout');
+
+    expect(StyleSheet.flatten(callout.props.style)).toEqual({
+      position: 'absolute',
+      backgroundColor: 'blue',
+      borderColor: 'green',
+      borderRadius: 8,
+      borderWidth: 2,
+      maxHeight: 240,
+      maxWidth: '80%',
+      minWidth: 120,
+      opacity: 0.5,
+    });
+    expect(callout.props.backgroundColor).toBeUndefined();
+    expect(callout.props.maxHeight).toBe(240);
+    expect(callout.props.maxWidth).toBeUndefined();
+    expect(callout.props.minWidth).toBe(120);
+  });
+
+  it('forwards native behavior, accessibility, callbacks, and children', async () => {
+    const onDismiss = jest.fn();
+    const onShow = jest.fn();
+    const anchorRect = { screenX: 10, screenY: 20, width: 30, height: 40 };
+    const component = await render(
+      <Callout
+        accessibilityLabel="Formatting options"
+        anchorRect={anchorRect}
+        beakWidth={12}
+        directionalHint="rightTopEdge"
+        dismissBehaviors={['preventDismissOnClickOutside']}
+        gapSpace={4}
+        minPadding={8}
+        onDismiss={onDismiss}
+        onShow={onShow}
+        target="editor-anchor"
+        testID="callout"
+      >
+        <Text>Callout content</Text>
+      </Callout>,
+    );
+    const callout = component.getByTestId('callout');
+
+    expect(callout.props).toMatchObject({
+      accessibilityLabel: 'Formatting options',
+      anchorRect,
+      beakWidth: 12,
+      directionalHint: 'rightTopEdge',
+      dismissBehaviors: ['preventDismissOnClickOutside'],
+      gapSpace: 4,
+      minPadding: 8,
+      onDismiss,
+      onShow,
+      target: 'editor-anchor',
+    });
+    expect(component.getByText('Callout content')).toBeTruthy();
+  });
+
+  it('resolves a React target ref to its native handle', async () => {
+    const target = React.createRef<View>();
+    const component = await render(
+      <>
+        <View ref={target} />
+        <Callout target={target} testID="callout" />
+      </>,
+    );
+
+    expect(target.current).not.toBeNull();
+    expect(component.getByTestId('callout').props.target).toBe(42);
+  });
+
+  it('exposes native window commands through componentRef', async () => {
+    const focusWindow = jest.spyOn(Commands, 'focusWindow').mockImplementation(() => undefined);
+    const blurWindow = jest.spyOn(Commands, 'blurWindow').mockImplementation(() => undefined);
+    const componentRef = React.createRef<CalloutHandle>();
+
+    await render(<Callout componentRef={componentRef} testID="callout" />);
+
+    await act(async () => {
+      componentRef.current?.focusWindow();
+      componentRef.current?.blurWindow();
+    });
+
+    expect(focusWindow).toHaveBeenCalledTimes(1);
+    expect(blurWindow).toHaveBeenCalledTimes(1);
+  });
+
+  it('can be consumed as a slot with merged render props', async () => {
+    const component = await render(<CalloutSlotConsumer callout={{ accessibilityLabel: 'Slotted Callout', target: 'slot-anchor' }} />);
+    const callout = component.getByTestId('slotted-callout');
+
+    expect(callout.props).toMatchObject({
+      accessibilityHint: 'rendered as a slot',
+      accessibilityLabel: 'Slotted Callout',
+      target: 'slot-anchor',
+    });
+    expect(component.getByText('Slot content')).toBeTruthy();
   });
-  expect(component!.toJSON()).toMatchSnapshot();
 });

package/src/__tests__/Callout.types.test.ts

@@ -0,0 +1,30 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import * as React from 'react';
+
+import type { SlotProp } from '@fluentui-react-native/framework-base';
+
+import type { Callout } from '../Callout';
+import type { CalloutHandle, CalloutProps, ICalloutProps } from '../Callout.types';
+
+const componentRef = React.createRef<CalloutHandle>();
+const target = React.createRef<React.Component>();
+
+const props: CalloutProps = {
+  accessibilityLabel: 'Formatting options',
+  componentRef,
+  directionalHint: 'bottomCenter',
+  target,
+};
+
+const calloutSlot: SlotProp<typeof Callout> = props;
+const legacyProps: ICalloutProps = props;
+
+// @ts-expect-error Callout targets must be a ref or registered native anchor identifier.
+const invalidTarget: CalloutProps = { target: 42 };
+
+describe('Callout types', () => {
+  it('accepts public props as a slot contract', () => {
+    expect(calloutSlot).toBeDefined();
+    expect(legacyProps).toBeDefined();
+  });
+});

package/src/__tests__/__snapshots__/Callout.test.tsx.snap

@@ -1,13 +1,11 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`Callout default props 1`] = `
-<RCTCallout
-  style={
-    {
-      "backgroundColor": "#faf9f8",
-      "borderColor": "#ffffff",
-      "borderWidth": 1,
-    }
-  }
-/>
+exports[`Callout uses phased rendering and applies native-safe default styling 1`] = `
+{
+  "backgroundColor": "#00000000",
+  "borderColor": "#00000000",
+  "borderRadius": 0,
+  "borderWidth": 0,
+  "position": "absolute",
+}
 `;

package/src/index.ts

@@ -1,13 +1,13 @@
 export { calloutName } from './Callout.types';
 export type {
+  CalloutHandle,
+  CalloutNativeCommands,
+  CalloutProps,
+  CalloutTokens,
   DirectionalHint,
   DismissBehaviors,
   ICalloutProps,
-  ICalloutRenderData,
-  ICalloutSlotProps,
   ICalloutTokens,
-  ICalloutType,
   RestoreFocusEvent,
 } from './Callout.types';
-export type { CalloutNativeCommands } from './CalloutNativeComponent';
 export { Callout } from './Callout';

package/tsconfig.json

@@ -7,24 +7,13 @@
     "tsBuildInfoFile": ".cache/tsconfig.tsbuildinfo"
   },
   "include": ["src"],
+  "exclude": ["**/*.stories.ts", "**/*.stories.tsx"],
   "references": [
     {
-      "path": "../../utils/adapters/tsconfig.json"
+      "path": "../../framework-base/tsconfig.json"
     },
     {
       "path": "../../../scripts/tsconfig.json"
-    },
-    {
-      "path": "../../utils/tokens/tsconfig.json"
-    },
-    {
-      "path": "../../deprecated/foundation-composable/tsconfig.json"
-    },
-    {
-      "path": "../../deprecated/foundation-compose/tsconfig.json"
-    },
-    {
-      "path": "../../deprecated/foundation-settings/tsconfig.json"
     }
   ]
 }