@fluentui-react-native/callout 0.28.0 → 0.28.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/CHANGELOG.md +39 -0
  2. package/lib/Callout.d.ts +2 -8
  3. package/lib/Callout.js +48 -50
  4. package/lib/Callout.settings.d.ts +1 -1
  5. package/lib/Callout.settings.js +12 -12
  6. package/lib/Callout.settings.macos.d.ts +1 -1
  7. package/lib/Callout.settings.macos.js +15 -15
  8. package/lib/Callout.types.d.ts +163 -210
  9. package/lib/Callout.types.d.ts.map +1 -1
  10. package/lib/Callout.types.js +1 -1
  11. package/lib/CalloutNativeComponent.d.ts +42 -2
  12. package/lib/CalloutNativeComponent.d.ts.map +1 -1
  13. package/lib/CalloutNativeComponent.js +2 -2
  14. package/lib/CalloutNativeComponent.js.map +1 -1
  15. package/lib/CalloutNativeComponent.macos.d.ts +42 -2
  16. package/lib/CalloutNativeComponent.macos.d.ts.map +1 -1
  17. package/lib/CalloutNativeComponent.macos.js +4 -6
  18. package/lib/CalloutNativeComponent.macos.js.map +1 -1
  19. package/lib/__tests__/Callout.test.d.ts +1 -1
  20. package/lib/__tests__/Callout.test.js +7 -7
  21. package/lib/index.d.ts +3 -12
  22. package/lib/index.d.ts.map +1 -1
  23. package/lib/index.js +1 -1
  24. package/lib-commonjs/Callout.d.ts +2 -8
  25. package/lib-commonjs/Callout.js +91 -112
  26. package/lib-commonjs/Callout.settings.d.ts +1 -1
  27. package/lib-commonjs/Callout.settings.js +15 -15
  28. package/lib-commonjs/Callout.settings.macos.d.ts +1 -1
  29. package/lib-commonjs/Callout.settings.macos.js +18 -18
  30. package/lib-commonjs/Callout.types.d.ts +163 -210
  31. package/lib-commonjs/Callout.types.d.ts.map +1 -1
  32. package/lib-commonjs/Callout.types.js +3 -3
  33. package/lib-commonjs/CalloutNativeComponent.d.ts +42 -2
  34. package/lib-commonjs/CalloutNativeComponent.d.ts.map +1 -1
  35. package/lib-commonjs/CalloutNativeComponent.js +9 -11
  36. package/lib-commonjs/CalloutNativeComponent.js.map +1 -1
  37. package/lib-commonjs/CalloutNativeComponent.macos.d.ts +42 -2
  38. package/lib-commonjs/CalloutNativeComponent.macos.d.ts.map +1 -1
  39. package/lib-commonjs/CalloutNativeComponent.macos.js +10 -14
  40. package/lib-commonjs/CalloutNativeComponent.macos.js.map +1 -1
  41. package/lib-commonjs/__tests__/Callout.test.d.ts +1 -1
  42. package/lib-commonjs/__tests__/Callout.test.js +41 -58
  43. package/lib-commonjs/index.d.ts +3 -12
  44. package/lib-commonjs/index.d.ts.map +1 -1
  45. package/lib-commonjs/index.js +7 -17
  46. package/macos/FRNCalloutManager.m +2 -1
  47. package/package.json +26 -25
  48. package/src/Callout.types.ts +4 -36
  49. package/src/CalloutNativeComponent.macos.ts +62 -5
  50. package/src/CalloutNativeComponent.ts +60 -1
  51. package/src/index.ts +1 -1
  52. package/eslint.config.js +0 -3
  53. package/lib/CalloutNativeComponent.types.d.ts +0 -30
  54. package/lib/CalloutNativeComponent.types.d.ts.map +0 -1
  55. package/lib/CalloutNativeComponent.types.js +0 -2
  56. package/lib/CalloutNativeComponent.types.js.map +0 -1
  57. package/lib/CalloutNativeComponent.types.macos.d.ts +0 -29
  58. package/lib/CalloutNativeComponent.types.macos.d.ts.map +0 -1
  59. package/lib/CalloutNativeComponent.types.macos.js +0 -2
  60. package/lib/CalloutNativeComponent.types.macos.js.map +0 -1
  61. package/lib/CalloutNativeComponent.win32.d.ts +0 -5
  62. package/lib/CalloutNativeComponent.win32.d.ts.map +0 -1
  63. package/lib/CalloutNativeComponent.win32.js +0 -8
  64. package/lib/CalloutNativeComponent.win32.js.map +0 -1
  65. package/lib-commonjs/CalloutNativeComponent.types.d.ts +0 -30
  66. package/lib-commonjs/CalloutNativeComponent.types.d.ts.map +0 -1
  67. package/lib-commonjs/CalloutNativeComponent.types.js +0 -3
  68. package/lib-commonjs/CalloutNativeComponent.types.js.map +0 -1
  69. package/lib-commonjs/CalloutNativeComponent.types.macos.d.ts +0 -29
  70. package/lib-commonjs/CalloutNativeComponent.types.macos.d.ts.map +0 -1
  71. package/lib-commonjs/CalloutNativeComponent.types.macos.js +0 -3
  72. package/lib-commonjs/CalloutNativeComponent.types.macos.js.map +0 -1
  73. package/lib-commonjs/CalloutNativeComponent.win32.d.ts +0 -5
  74. package/lib-commonjs/CalloutNativeComponent.win32.d.ts.map +0 -1
  75. package/lib-commonjs/CalloutNativeComponent.win32.js +0 -16
  76. package/lib-commonjs/CalloutNativeComponent.win32.js.map +0 -1
  77. package/src/CalloutNativeComponent.types.macos.ts +0 -31
  78. package/src/CalloutNativeComponent.types.ts +0 -31
  79. package/src/CalloutNativeComponent.win32.ts +0 -11
  80. package/src/codegenTypes.d.ts +0 -2
package/CHANGELOG.md CHANGED
@@ -1,5 +1,44 @@
1
1
  # Change Log - @fluentui-react-native/callout
2
2
 
3
+ ## 0.28.3
4
+
5
+ ### Patch Changes
6
+
7
+ - 9cf4444: Migrate from ESLint to oxlint
8
+ - Updated dependencies [9cf4444]
9
+ - @uifabricshared/foundation-composable@0.14.3
10
+ - @uifabricshared/foundation-settings@0.16.3
11
+ - @uifabricshared/foundation-compose@1.16.3
12
+ - @fluentui-react-native/adapters@0.14.3
13
+ - @fluentui-react-native/tokens@0.24.3
14
+
15
+ ## 0.28.2
16
+
17
+ ### Patch Changes
18
+
19
+ - 8a7b549: Update to the latest rnx-kit versions, fix some typing issues, and correct the vscode settings
20
+ - Updated dependencies [8a7b549]
21
+ - @uifabricshared/foundation-composable@0.14.2
22
+ - @uifabricshared/foundation-settings@0.16.2
23
+ - @uifabricshared/foundation-compose@1.16.2
24
+ - @fluentui-react-native/adapters@0.14.2
25
+ - @fluentui-react-native/tokens@0.24.2
26
+
27
+ ## 0.28.1
28
+
29
+ ### Patch Changes
30
+
31
+ - f72b43a: Fix codegen definitions for native components in repo
32
+ - 0d6e9c1: chore: migrate to `oxfmt`
33
+ - ac6e7af: Ensure packages have a default export that references the typescript entrypoint and clean up build dependency ordering
34
+ - Updated dependencies [0d6e9c1]
35
+ - Updated dependencies [ac6e7af]
36
+ - @uifabricshared/foundation-composable@0.14.1
37
+ - @uifabricshared/foundation-settings@0.16.1
38
+ - @uifabricshared/foundation-compose@1.16.1
39
+ - @fluentui-react-native/adapters@0.14.1
40
+ - @fluentui-react-native/tokens@0.24.1
41
+
3
42
  ## 0.28.0
4
43
 
5
44
  ### Minor Changes
package/lib/Callout.d.ts CHANGED
@@ -4,12 +4,6 @@
4
4
  * @format
5
5
  */
6
6
  import type { ICalloutProps, ICalloutSlotProps } from './Callout.types';
7
- export declare const Callout: import('@uifabricshared/foundation-compose').IComposeReturnType<
8
- ICalloutProps,
9
- ICalloutSlotProps,
10
- import('./Callout.types').ICalloutTokens,
11
- object,
12
- object
13
- >;
7
+ export declare const Callout: import("@uifabricshared/foundation-compose").IComposeReturnType<ICalloutProps, ICalloutSlotProps, import("./Callout.types").ICalloutTokens, object, object>;
14
8
  export default Callout;
15
- //# sourceMappingURL=Callout.d.ts.map
9
+ //# sourceMappingURL=Callout.d.ts.map
package/lib/Callout.js CHANGED
@@ -13,55 +13,53 @@ import { calloutName } from './Callout.types';
13
13
  import NativeCalloutView from './CalloutNativeComponent';
14
14
  import { Commands } from './CalloutNativeComponent';
15
15
  export const Callout = compose({
16
- displayName: calloutName,
17
- usePrepareProps: (props, useStyling) => {
18
- const { componentRef, target, ...rest } = props;
19
- React.useImperativeHandle(
20
- componentRef,
21
- () => ({
22
- blurWindow() {
23
- if (componentRef.current != null) {
24
- Commands.blurWindow(nativeComponentRef.current);
25
- }
26
- },
27
- focusWindow() {
28
- if (componentRef.current != null) {
29
- Commands.focusWindow(nativeComponentRef.current);
30
- }
31
- },
32
- }),
33
- [componentRef],
34
- );
35
- const nativeComponentRef = React.useRef(null);
36
- const [nativeTarget, setNativeTarget] = React.useState(null);
37
- React.useLayoutEffect(() => {
38
- if (typeof target === 'string') {
39
- // Pass string type `target` directly
40
- setNativeTarget(target);
41
- } else if (target?.current) {
42
- // Pass the tagID for a valid ref `target`
43
- setNativeTarget(findNodeHandle(target.current));
44
- } else {
45
- // Clear `target` so we may fall back on `anchorRect` if provided
46
- setNativeTarget(null);
47
- }
48
- }, [target]);
49
- const slotProps = mergeSettings(useStyling(props), {
50
- root: {
51
- ref: nativeComponentRef,
52
- ...(nativeTarget && { target: nativeTarget }),
53
- ...rest,
54
- },
55
- });
56
- return { slotProps };
57
- },
58
- settings: settings,
59
- slots: {
60
- root: NativeCalloutView,
61
- },
62
- styles: {
63
- root: [backgroundColorTokens, borderTokens],
64
- },
16
+ displayName: calloutName,
17
+ usePrepareProps: (props, useStyling) => {
18
+ const { componentRef, target, ...rest } = props;
19
+ React.useImperativeHandle(componentRef, () => ({
20
+ blurWindow() {
21
+ if (componentRef.current != null) {
22
+ Commands.blurWindow(nativeComponentRef.current);
23
+ }
24
+ },
25
+ focusWindow() {
26
+ if (componentRef.current != null) {
27
+ Commands.focusWindow(nativeComponentRef.current);
28
+ }
29
+ },
30
+ }), [componentRef]);
31
+ const nativeComponentRef = React.useRef(null);
32
+ const [nativeTarget, setNativeTarget] = React.useState(null);
33
+ React.useLayoutEffect(() => {
34
+ if (typeof target === 'string') {
35
+ // Pass string type `target` directly
36
+ setNativeTarget(target);
37
+ }
38
+ else if (target?.current) {
39
+ // Pass the tagID for a valid ref `target`
40
+ setNativeTarget(findNodeHandle(target.current));
41
+ }
42
+ else {
43
+ // Clear `target` so we may fall back on `anchorRect` if provided
44
+ setNativeTarget(null);
45
+ }
46
+ }, [target]);
47
+ const slotProps = mergeSettings(useStyling(props), {
48
+ root: {
49
+ ref: nativeComponentRef,
50
+ ...(nativeTarget && { target: nativeTarget }),
51
+ ...rest,
52
+ },
53
+ });
54
+ return { slotProps };
55
+ },
56
+ settings: settings,
57
+ slots: {
58
+ root: NativeCalloutView,
59
+ },
60
+ styles: {
61
+ root: [backgroundColorTokens, borderTokens],
62
+ },
65
63
  });
66
64
  export default Callout;
67
- //# sourceMappingURL=Callout.js.map
65
+ //# sourceMappingURL=Callout.js.map
@@ -1,4 +1,4 @@
1
1
  import type { IComposeSettings } from '@uifabricshared/foundation-compose';
2
2
  import type { ICalloutType } from './Callout.types';
3
3
  export declare const settings: IComposeSettings<ICalloutType>;
4
- //# sourceMappingURL=Callout.settings.d.ts.map
4
+ //# sourceMappingURL=Callout.settings.d.ts.map
@@ -1,16 +1,16 @@
1
1
  import { calloutName } from './Callout.types';
2
2
  export const settings = [
3
- {
4
- tokens: {
5
- backgroundColor: 'bodyStandoutBackground',
6
- beakWidth: 20,
7
- borderColor: 'bodyFrameBackground',
8
- borderWidth: 1,
9
- directionalHint: 'bottonLeftEdge',
10
- gapSpace: 0,
11
- minPadding: 0,
3
+ {
4
+ tokens: {
5
+ backgroundColor: 'bodyStandoutBackground',
6
+ beakWidth: 20,
7
+ borderColor: 'bodyFrameBackground',
8
+ borderWidth: 1,
9
+ directionalHint: 'bottonLeftEdge',
10
+ gapSpace: 0,
11
+ minPadding: 0,
12
+ },
12
13
  },
13
- },
14
- calloutName,
14
+ calloutName,
15
15
  ];
16
- //# sourceMappingURL=Callout.settings.js.map
16
+ //# sourceMappingURL=Callout.settings.js.map
@@ -1,4 +1,4 @@
1
1
  import type { IComposeSettings } from '@uifabricshared/foundation-compose';
2
2
  import type { ICalloutType } from './Callout.types';
3
3
  export declare const settings: IComposeSettings<ICalloutType>;
4
- //# sourceMappingURL=Callout.settings.macos.d.ts.map
4
+ //# sourceMappingURL=Callout.settings.macos.d.ts.map
@@ -1,19 +1,19 @@
1
1
  import { calloutName } from './Callout.types';
2
2
  export const settings = [
3
- {
4
- tokens: {
5
- backgroundColor: 'bodyStandoutBackground',
6
- borderColor: 'transparent',
7
- borderWidth: 0,
8
- borderRadius: 5,
9
- directionalHint: 'bottonLeftEdge',
3
+ {
4
+ tokens: {
5
+ backgroundColor: 'bodyStandoutBackground',
6
+ borderColor: 'transparent',
7
+ borderWidth: 0,
8
+ borderRadius: 5,
9
+ directionalHint: 'bottonLeftEdge',
10
+ },
11
+ root: {
12
+ style: {
13
+ position: 'absolute',
14
+ },
15
+ },
10
16
  },
11
- root: {
12
- style: {
13
- position: 'absolute',
14
- },
15
- },
16
- },
17
- calloutName,
17
+ calloutName,
18
18
  ];
19
- //# sourceMappingURL=Callout.settings.macos.js.map
19
+ //# sourceMappingURL=Callout.settings.macos.js.map
@@ -1,233 +1,186 @@
1
1
  import type * as React from 'react';
2
- import type { KeyboardMetrics, ViewStyle, ViewProps } from 'react-native';
2
+ import type { KeyboardMetrics, ViewStyle } from 'react-native';
3
3
  import type { IViewProps } from '@fluentui-react-native/adapters';
4
4
  import type { IBackgroundColorTokens, IBorderTokens } from '@fluentui-react-native/tokens';
5
5
  import type { IRenderData } from '@uifabricshared/foundation-composable';
6
- import type { CalloutNativeCommands } from './CalloutNativeComponent.types';
7
- export declare const calloutName = 'Callout';
8
- import type { DirectEventHandler, Double, Int32 } from 'react-native/Libraries/Types/CodegenTypes';
6
+ import type { CalloutNativeCommands } from './CalloutNativeComponent';
7
+ export declare const calloutName = "Callout";
9
8
  /**
10
9
  * Properties and Tokens for FluentUI React Native Callout
11
10
  */
12
- export type DirectionalHint =
13
- | 'leftTopEdge'
14
- | 'leftCenter'
15
- | 'leftBottomEdge'
16
- | 'topLeftEdge'
17
- | 'topAutoEdge'
18
- | 'topCenter'
19
- | 'topRightEdge'
20
- | 'rightTopEdge'
21
- | 'rightCenter'
22
- | 'rightBottomEdge'
23
- | 'bottonLeftEdge'
24
- | 'bottomAutoEdge'
25
- | 'bottomCenter'
26
- | 'bottomRightEdge';
11
+ export type DirectionalHint = 'leftTopEdge' | 'leftCenter' | 'leftBottomEdge' | 'topLeftEdge' | 'topAutoEdge' | 'topCenter' | 'topRightEdge' | 'rightTopEdge' | 'rightCenter' | 'rightBottomEdge' | 'bottomLeftEdge' | 'bottonLeftEdge' | 'bottomAutoEdge' | 'bottomCenter' | 'bottomRightEdge';
27
12
  export type DismissBehaviors = 'preventDismissOnKeyDown' | 'preventDismissOnClickOutside';
28
13
  export interface RestoreFocusEvent {
29
- nativeEvent: {
30
- /**
31
- * containsFocus is true if the Callout had focus while being dismissed.
32
- */
33
- containsFocus: boolean;
34
- };
14
+ nativeEvent: {
15
+ /**
16
+ * containsFocus is true if the Callout had focus while being dismissed.
17
+ */
18
+ containsFocus: boolean;
19
+ };
35
20
  }
36
21
  interface OmittedBorderTokens {
37
- borderStyle?: ViewStyle['borderStyle'];
22
+ borderStyle?: ViewStyle['borderStyle'];
38
23
  }
39
24
  type CalloutBorderTokens = Omit<IBorderTokens, keyof OmittedBorderTokens>;
40
25
  export interface ICalloutTokens extends IBackgroundColorTokens, CalloutBorderTokens {
41
- /**
42
- * AnchorRect arbitrary anchor rectangle; coordinate system is in DIPs, relative
43
- * to the React surface origin.
44
- */
45
- anchorRect?: KeyboardMetrics;
46
- /**
47
- * Width of the beak on the Callout indicating its anchor.
48
- */
49
- beakWidth?: number;
50
- /**
51
- * Defines the suggested drop direction and alignment for the Callout to use, relative
52
- * to the anchor information.
53
- */
54
- directionalHint?: DirectionalHint;
55
- /**
56
- * Defines variations on how the callout dismissal may be controlled. the async eventing
57
- * of React-Native makes passing some aspects of dismissal control over to JS difficult.
58
- * Moreover, the native platform or host may have competing priorities with regards to transient UI
59
- * that generate bi-directional lifetime management between JS (which mounts and unmounts the
60
- * component) and native (which may tear down the transient UI without JS input).
61
- *
62
- * This property provides control over the latter issue, enabling relevant native platform
63
- * interactions with transient UI to be managed from JS.
64
- *
65
- * These behaviors should generally be orthogonal, and therefore combinable.
66
- */
67
- dismissBehaviors?: DismissBehaviors[];
68
- /**
69
- * Defines the size of the gap between the anchor and the Callout. Not used if
70
- * no anchor information is provided.
71
- */
72
- gapSpace?: number;
73
- /**
74
- * Defines a maximum height for the Callout.
75
- */
76
- maxHeight?: number | `${number}%`;
77
- /**
78
- * Defines a maximum width for the Callout.
79
- */
80
- maxWidth?: number | `${number}%`;
81
- /**
82
- * Defines a minimum width for the Callout.
83
- */
84
- minWidth?: number | `${number}%`;
85
- /**
86
- * Defines the minimum padding between the Callout and the display edges.
87
- */
88
- minPadding?: number;
26
+ /**
27
+ * AnchorRect arbitrary anchor rectangle; coordinate system is in DIPs, relative
28
+ * to the React surface origin.
29
+ */
30
+ anchorRect?: KeyboardMetrics;
31
+ /**
32
+ * Width of the beak on the Callout indicating its anchor.
33
+ */
34
+ beakWidth?: number;
35
+ /**
36
+ * Defines the suggested drop direction and alignment for the Callout to use, relative
37
+ * to the anchor information.
38
+ */
39
+ directionalHint?: DirectionalHint;
40
+ /**
41
+ * Defines variations on how the callout dismissal may be controlled. the async eventing
42
+ * of React-Native makes passing some aspects of dismissal control over to JS difficult.
43
+ * Moreover, the native platform or host may have competing priorities with regards to transient UI
44
+ * that generate bi-directional lifetime management between JS (which mounts and unmounts the
45
+ * component) and native (which may tear down the transient UI without JS input).
46
+ *
47
+ * This property provides control over the latter issue, enabling relevant native platform
48
+ * interactions with transient UI to be managed from JS.
49
+ *
50
+ * These behaviors should generally be orthogonal, and therefore combinable.
51
+ */
52
+ dismissBehaviors?: DismissBehaviors[];
53
+ /**
54
+ * Defines the size of the gap between the anchor and the Callout. Not used if
55
+ * no anchor information is provided.
56
+ */
57
+ gapSpace?: number;
58
+ /**
59
+ * Defines a maximum height for the Callout.
60
+ */
61
+ maxHeight?: number | `${number}%`;
62
+ /**
63
+ * Defines a maximum width for the Callout.
64
+ */
65
+ maxWidth?: number | `${number}%`;
66
+ /**
67
+ * Defines a minimum width for the Callout.
68
+ */
69
+ minWidth?: number | `${number}%`;
70
+ /**
71
+ * Defines the minimum padding between the Callout and the display edges.
72
+ */
73
+ minPadding?: number;
89
74
  }
90
75
  export interface ICalloutProps extends IViewProps, ICalloutTokens {
91
- /**
92
- * A string that should be announced when the callout is shown.
93
- * @platform win32
94
- */
95
- accessibilityOnShowAnnouncement?: string;
96
- /**
97
- * A RefObject to access the IFocusable interface. Use this to access the public methods and properties of the component.
98
- */
99
- componentRef?: React.RefObject<CalloutNativeCommands>;
100
- /**
101
- * Defines event redirection behaviors for pointer events relative to the Callout control.
102
- *
103
- * Pointer events (i.e. mouse, pen, touch) often have the effect of initiating and dismissing Callout controls.
104
- * Typically the instigating events are click events, but when using a mouse may also include pointer enter
105
- * and leave events i.e. hover. Once opened, many Callout scenarios desire modal-like interactions, where
106
- * the user must interact with or relative to the Callout before interacting with other controls again. A common
107
- * example is context menus, where pointer events away from the menu may dismiss the context menu. Such an interaction
108
- * can initiate unintended actions such as invoking a button or otherwise pointer-responsive surface. The modal-like
109
- * behavior is the most common case of Callout usage, and having "safe" areas to press-dismiss the Callout without
110
- * invoking additional actions is useful.
111
- *
112
- * This modal-like behavior, where true modal behavior would specifically require interacting with the modal component until
113
- * it is dismissed, has implications for canonical event routing in React-Native. Canonically all pointer events are passed in
114
- * a Capture phase from the root element to the target element, then bubbled back from the target element to the root element.
115
- * This structure allows many interaction patterns to be implemented that may include stopping event routing in each phase.
116
- * This event routing can disrupt the modal-like behavior desired by a Callout control, which in native frameworks may take
117
- * advantage of a "take event capture" feature -- making the Callout the first handler of the pointer event. The event may optionally
118
- * be forwarded afterwards to the canonical event routing pattern for further handling (and often is not forwarded).
119
- *
120
- * One impact of "taking event capture" is the implicit behavior for mouse events on the parent surface of the Callout -- if
121
- * event capture is taken by the Callout, paired events may fire such as a mouse leave event. This makes sense if we think about
122
- * the event behavior after the Callout has taken capture; mouse enter and mouse leave events would only propagate to the parent surface
123
- * if the Callout event handling decided to forward said events (often not). As paired events, however, there should not be a
124
- * mouse enter event without a corresponding mouse leave event (or vice versa). Since mouse enter and mouse leave events would not
125
- * naturally fire on the parent surface when the Callout has pointer capture, the parent surface should receive a mouse leave event when
126
- * the Callout takes capture.
127
- *
128
- * Coming back to the start of this comment, some Callout scenarios may be initiated by mouse enter/leave events. A common example is
129
- * tooltips, which are supported on lower-level React-Native components, but such behavior is not exclusive to tooltips.
130
- * The Callout control is generally used for more advanced scenarios, as mentioned before often desiring modal-like behavior and accordingly
131
- * the default behavior of the Callout control is to take pointer capture. Accounting for the paired mouse enter/leave events in the paragraph
132
- * above, it is difficult to have a mouse enter/leave-invoked Callout that takes pointer capture -- without significant workarounds,
133
- * the Callout would open and close cyclically from repeated mouse enter/leave events. There are other scenarios where taking pointer capture
134
- * is not desirable, such as a semi-persistent Callout; to support these scenarios the doNotTakePointerCapture property is offered to
135
- * specify if the Callout should not take pointer capture when it opens.
136
- *
137
- * While pointer capture is generally managed in native frameworks via imperative APIs, managing pointer capture is offered as a property that
138
- * only affects the Callout's on-show behavior when it would typically take pointer capture. This design implies that changing this property after
139
- * the Callout has been shown has no effect -- similar to the Callout's onShow callback. Doing so simplifies Callout usage for developers,
140
- * not needing to mind native platform pointer capture that may be complex particularly when React-Native is integrated into a larger app.
141
- * Pointer capture may be lost (and regained) but is otherwise abstracted away from the developer. More advanced control of pointer capture
142
- * would need to be provided by a native module independent of any particular control.
143
- *
144
- * When the Callout is closed, pointer capture is released by the Callout and further handled by the native platform -- generally returning
145
- * pointer capture to the parent surface.
146
- * @platform win32
147
- */
148
- doNotTakePointerCapture?: boolean;
149
- /**
150
- * Adds a beak to the Callout, pointing to the anchor target.
151
- * Notable Win32 limitation: Beak rendering currently limits the border width to its default, and the
152
- * border width prop will not be honored.
153
- * @platform win32
154
- */
155
- isBeakVisible?: boolean;
156
- /**
157
- * Callback invoked when the callout has been dismissed.
158
- */
159
- onDismiss?: () => void;
160
- /**
161
- * Callback invoked during callout dismissal; if set, focus will not be restored by the callout and onRestoreFocus must
162
- * result in focus being moved to the appropriate focusable target.
163
- *
164
- * The callee should carefully consider their scenarios to avoid dropping focus, or inappropriately
165
- * moving focus from another component. Focus is not guaranteed to have entered the React-Native surface at all, and
166
- * this callback is most appropriate for components strictly controlling focus.
167
- *
168
- * restoreFocusEvent.nativeEvent.containsFocus is true if the Callout had focus while being dismissed.
169
- * @platform win32
170
- */
171
- onRestoreFocus?: (restoreFocusEvent: RestoreFocusEvent) => void;
172
- /**
173
- * Callback invoked when the callout has been shown.
174
- */
175
- onShow?: () => void;
176
- /**
177
- * Determines whether the Callout sets focus when displayed.
178
- * On macOS: this determines whether the Callout becomes the key window.
179
- * On win32: If true then the callout will attempt to focus the first focusable element that it contains.
180
- * If it doesn't find an element, no focus will be set. This means that it's the contents responsibility
181
- * to either set focus or have focusable items.
182
- */
183
- setInitialFocus?: boolean;
184
- /**
185
- * Target node the callout uses for relative positioning; the anchor of the callout.
186
- * A ref is the typical usage; certain components may proffer a string as an anchor target, such as
187
- * anchoring to a point inside the component.
188
- */
189
- target?: React.RefObject<React.Component> | string;
76
+ /**
77
+ * A string that should be announced when the callout is shown.
78
+ * @platform win32
79
+ */
80
+ accessibilityOnShowAnnouncement?: string;
81
+ /**
82
+ * A RefObject to access the IFocusable interface. Use this to access the public methods and properties of the component.
83
+ */
84
+ componentRef?: React.RefObject<CalloutNativeCommands>;
85
+ /**
86
+ * Defines event redirection behaviors for pointer events relative to the Callout control.
87
+ *
88
+ * Pointer events (i.e. mouse, pen, touch) often have the effect of initiating and dismissing Callout controls.
89
+ * Typically the instigating events are click events, but when using a mouse may also include pointer enter
90
+ * and leave events i.e. hover. Once opened, many Callout scenarios desire modal-like interactions, where
91
+ * the user must interact with or relative to the Callout before interacting with other controls again. A common
92
+ * example is context menus, where pointer events away from the menu may dismiss the context menu. Such an interaction
93
+ * can initiate unintended actions such as invoking a button or otherwise pointer-responsive surface. The modal-like
94
+ * behavior is the most common case of Callout usage, and having "safe" areas to press-dismiss the Callout without
95
+ * invoking additional actions is useful.
96
+ *
97
+ * This modal-like behavior, where true modal behavior would specifically require interacting with the modal component until
98
+ * it is dismissed, has implications for canonical event routing in React-Native. Canonically all pointer events are passed in
99
+ * a Capture phase from the root element to the target element, then bubbled back from the target element to the root element.
100
+ * This structure allows many interaction patterns to be implemented that may include stopping event routing in each phase.
101
+ * This event routing can disrupt the modal-like behavior desired by a Callout control, which in native frameworks may take
102
+ * advantage of a "take event capture" feature -- making the Callout the first handler of the pointer event. The event may optionally
103
+ * be forwarded afterwards to the canonical event routing pattern for further handling (and often is not forwarded).
104
+ *
105
+ * One impact of "taking event capture" is the implicit behavior for mouse events on the parent surface of the Callout -- if
106
+ * event capture is taken by the Callout, paired events may fire such as a mouse leave event. This makes sense if we think about
107
+ * the event behavior after the Callout has taken capture; mouse enter and mouse leave events would only propagate to the parent surface
108
+ * if the Callout event handling decided to forward said events (often not). As paired events, however, there should not be a
109
+ * mouse enter event without a corresponding mouse leave event (or vice versa). Since mouse enter and mouse leave events would not
110
+ * naturally fire on the parent surface when the Callout has pointer capture, the parent surface should receive a mouse leave event when
111
+ * the Callout takes capture.
112
+ *
113
+ * Coming back to the start of this comment, some Callout scenarios may be initiated by mouse enter/leave events. A common example is
114
+ * tooltips, which are supported on lower-level React-Native components, but such behavior is not exclusive to tooltips.
115
+ * The Callout control is generally used for more advanced scenarios, as mentioned before often desiring modal-like behavior and accordingly
116
+ * the default behavior of the Callout control is to take pointer capture. Accounting for the paired mouse enter/leave events in the paragraph
117
+ * above, it is difficult to have a mouse enter/leave-invoked Callout that takes pointer capture -- without significant workarounds,
118
+ * the Callout would open and close cyclically from repeated mouse enter/leave events. There are other scenarios where taking pointer capture
119
+ * is not desirable, such as a semi-persistent Callout; to support these scenarios the doNotTakePointerCapture property is offered to
120
+ * specify if the Callout should not take pointer capture when it opens.
121
+ *
122
+ * While pointer capture is generally managed in native frameworks via imperative APIs, managing pointer capture is offered as a property that
123
+ * only affects the Callout's on-show behavior when it would typically take pointer capture. This design implies that changing this property after
124
+ * the Callout has been shown has no effect -- similar to the Callout's onShow callback. Doing so simplifies Callout usage for developers,
125
+ * not needing to mind native platform pointer capture that may be complex particularly when React-Native is integrated into a larger app.
126
+ * Pointer capture may be lost (and regained) but is otherwise abstracted away from the developer. More advanced control of pointer capture
127
+ * would need to be provided by a native module independent of any particular control.
128
+ *
129
+ * When the Callout is closed, pointer capture is released by the Callout and further handled by the native platform -- generally returning
130
+ * pointer capture to the parent surface.
131
+ * @platform win32
132
+ */
133
+ doNotTakePointerCapture?: boolean;
134
+ /**
135
+ * Adds a beak to the Callout, pointing to the anchor target.
136
+ * Notable Win32 limitation: Beak rendering currently limits the border width to its default, and the
137
+ * border width prop will not be honored.
138
+ * @platform win32
139
+ */
140
+ isBeakVisible?: boolean;
141
+ /**
142
+ * Callback invoked when the callout has been dismissed.
143
+ */
144
+ onDismiss?: () => void;
145
+ /**
146
+ * Callback invoked during callout dismissal; if set, focus will not be restored by the callout and onRestoreFocus must
147
+ * result in focus being moved to the appropriate focusable target.
148
+ *
149
+ * The callee should carefully consider their scenarios to avoid dropping focus, or inappropriately
150
+ * moving focus from another component. Focus is not guaranteed to have entered the React-Native surface at all, and
151
+ * this callback is most appropriate for components strictly controlling focus.
152
+ *
153
+ * restoreFocusEvent.nativeEvent.containsFocus is true if the Callout had focus while being dismissed.
154
+ * @platform win32
155
+ */
156
+ onRestoreFocus?: (restoreFocusEvent: RestoreFocusEvent) => void;
157
+ /**
158
+ * Callback invoked when the callout has been shown.
159
+ */
160
+ onShow?: () => void;
161
+ /**
162
+ * Determines whether the Callout sets focus when displayed.
163
+ * On macOS: this determines whether the Callout becomes the key window.
164
+ * On win32: If true then the callout will attempt to focus the first focusable element that it contains.
165
+ * If it doesn't find an element, no focus will be set. This means that it's the contents responsibility
166
+ * to either set focus or have focusable items.
167
+ */
168
+ setInitialFocus?: boolean;
169
+ /**
170
+ * Target node the callout uses for relative positioning; the anchor of the callout.
171
+ * A ref is the typical usage; certain components may proffer a string as an anchor target, such as
172
+ * anchoring to a point inside the component.
173
+ */
174
+ target?: React.RefObject<React.Component> | string;
190
175
  }
191
176
  export type ICalloutSlotProps = {
192
- root: ICalloutProps;
177
+ root: ICalloutProps;
193
178
  };
194
179
  export type ICalloutRenderData = IRenderData<ICalloutSlotProps>;
195
180
  export interface ICalloutType {
196
- props: ICalloutProps;
197
- slotProps: ICalloutSlotProps;
198
- tokens: ICalloutTokens;
199
- }
200
- type AnchorRect = {
201
- screenX: Double;
202
- screenY: Double;
203
- width: Double;
204
- height: Double;
205
- };
206
- /**
207
- * Shared native props specific to Callout native component
208
- */
209
- export interface NativePropsBase extends ViewProps {
210
- accessibilityLabel?: string;
211
- accessibilityOnShowAnnouncement?: string;
212
- anchorRect?: AnchorRect;
213
- dismissBehaviors?: string[];
214
- doNotTakePointerCapture?: boolean;
215
- focusable?: boolean;
216
- isBeakVisible?: boolean;
217
- maxHeight?: Int32;
218
- maxWidth?: Int32;
219
- setInitialFocus?: boolean;
220
- testID?: string;
221
- onRestoreFocus?: DirectEventHandler<{
222
- target: Int32;
223
- containsFocus: boolean;
224
- }>;
225
- onDismiss?: DirectEventHandler<{
226
- target: Int32;
227
- }>;
228
- onShow?: DirectEventHandler<{
229
- target: Int32;
230
- }>;
181
+ props: ICalloutProps;
182
+ slotProps: ICalloutSlotProps;
183
+ tokens: ICalloutTokens;
231
184
  }
232
185
  export {};
233
- //# sourceMappingURL=Callout.types.d.ts.map
186
+ //# sourceMappingURL=Callout.types.d.ts.map