@fluentui-react-native/tooltip 0.3.2 → 0.4.1

package/CHANGELOG.json

@@ -2,7 +2,22 @@
   "name": "@fluentui-react-native/tooltip",
   "entries": [
     {
-      "date": "Mon, 15 Apr 2024 21:29:45 GMT",
+      "date": "Wed, 08 May 2024 16:21:26 GMT",
+      "version": "0.4.0",
+      "tag": "@fluentui-react-native/tooltip_v0.4.0",
+      "comments": {
+        "minor": [
+          {
+            "author": "gulnazsayed@microsoft.com",
+            "package": "@fluentui-react-native/tooltip",
+            "commit": "16a8753cb5e4e15b7baa1182e60ef3e6c7cd8d4e",
+            "comment": "added layoutEffect hook"
+          }
+        ]
+      }
+    },
+    {
+      "date": "Mon, 15 Apr 2024 21:31:44 GMT",
       "version": "0.3.2",
       "tag": "@fluentui-react-native/tooltip_v0.3.2",
       "comments": {

package/CHANGELOG.md

@@ -1,12 +1,20 @@
 # Change Log - @fluentui-react-native/tooltip
 
-This log was last generated on Mon, 15 Apr 2024 21:29:45 GMT and should not be manually modified.
+This log was last generated on Wed, 08 May 2024 16:21:26 GMT and should not be manually modified.
 
 <!-- Start content -->
 
+## 0.4.0
+
+Wed, 08 May 2024 16:21:26 GMT
+
+### Minor changes
+
+- added layoutEffect hook (gulnazsayed@microsoft.com)
+
 ## 0.3.2
 
-Mon, 15 Apr 2024 21:29:45 GMT
+Mon, 15 Apr 2024 21:31:44 GMT
 
 ### Patches
 

package/SPEC.md

@@ -2,4 +2,131 @@
 
 ## Background
 
-Please write here you documentation...
+A `Tooltip` is a component that displays additional information about another component. The information is displayed above or near the target. At this time, the tooltip is displayed at or near the mouse cursor (target), which is default Win32 behavior.
+
+## Sample Code
+
+Basic Example:
+
+```jsx
+const tooltip = (
+  <Tooltip content={defaultContent}>
+    <ButtonV1 accessibilityDescription={defaultContent}>Default Tooltip</ButtonV1>
+  </Tooltip>
+);
+```
+
+More examples on the [Test pages for Tooltip](../../../apps/fluent-tester/src/TestComponents/Tooltip). Instructions on running the tester app can be found [here](../../../apps/fluent-tester/README.md).
+
+## Visual Examples
+
+### Default Tooltip
+
+Win32:
+
+![Default tooltip](assets/image.png)
+
+```tsx
+const defaultContent = 'Tooltip shows relative to mouse cursor.';
+
+const tooltip = (
+  <Tooltip content={defaultContent}>
+    <ButtonV1 accessibilityDescription={defaultContent}>Default Tooltip</ButtonV1>
+  </Tooltip>
+);
+```
+
+## Variants
+
+### Positioning
+
+Not yet implemented.
+
+The `Tooltip` component will appear in the specified position relative to the anchor (target). In Win32, the positions are denoted by the DirectionalHint: `topLeftEdge`, `topCenter`, `topRightEdge`, `rightTopEdge`, `rightCenter`, `rightBottomEdge`, `bottomLeftEdge`, `bottomCenter`, `bottomRightEdge`, `leftTopEdge`, `leftCenter`, and `leftBottomEdge`.
+
+### Target
+
+Not yet implemented.
+
+The `Tooltip` component can reference a target component that will be used as the position anchor.
+
+## API
+
+### Slots
+
+The `Tooltip` component has one slot, or parts. The slots behave as follows:
+
+- `root` - The outer container representing the `Tooltip` itself. The NativeTooltipViewManager is passed into this.
+
+### Props
+
+Below is the set of props `Tooltip` supports:
+
+```ts
+export type TooltipProps = React.PropsWithChildren<{
+  /**
+   * The text of the tooltip.
+   */
+  content: string;
+
+  /**
+   * Notification when the visibility of the tooltip is changed.
+   */
+  onVisibleChange?: (event, data) => void;
+
+  /**
+   * Positioning of the tooltip relative to the target element.
+   *
+   * @default topCenter
+   */
+  positioning?: DirectionalHint;
+
+  /**
+   * Allow consumers to pass in Style props
+   */
+  style?: ViewStyle;
+
+  /**
+   * Target anchor that tooltip uses for relative positioning. Certain components may proffer a string as an anchor target, such as
+   * anchoring to a point inside the component.
+   *
+   * If not provided, will anchor to the wrapper element.
+   */
+  target?: React.RefObject<React.Component> | string;
+
+  /**
+   * Controls the tooltip visibility and can be used in conjunction with onVisibleChange to modify show/hide behavior. If not provided, will be updated based on hover/focus events on target element.
+   *
+   * @default false
+   */
+  visible?: boolean;
+}>;
+```
+
+### Styling
+
+Styling is handled by the native platform for Win32.
+
+## Behaviors
+
+The user will have the opportunity to see the tooltip on hover or focus of the target component. Tooltips simply display additional information about another component for the user to read.
+
+### Interactions
+
+#### Keyboard Interaction
+
+Focus is set according to the guidelines of the target component (ex. Button). When the component is focused, the `Tooltip` is raisable by Ctrl+Shift+F10.
+
+#### Mouse Interaction
+
+`Tooltip` is visible when target component is hovered. `Tooltip` is dismissed when the mouse cursor moves again.
+
+#### Touch interaction
+
+`Tooltip` is rendered on touch/press.
+
+## Accessibility
+
+### Expected behavior
+
+Narrator will read the contents of the `Tooltip` when visible. The user should use `accessibilityDescription` on the target component to set the full description. Win32 platform infrastructure supports narrator default to reading the full description of the target element.

package/lib/Tooltip.d.ts

@@ -4,14 +4,6 @@
  * @format
  */
 import type { TooltipProps } from './Tooltip.types';
-/**
- * A function which determines if a set of styles should be applied to the component given the current state and props of the tooltip.
- *
- * @param layer The name of the state that is being checked for
- * @param userProps The props that were passed into the tooltip
- * @returns Whether the styles that are assigned to the layer should be applied to the tooltip
- */
-export declare const tooltipLookup: (layer: string, userProps: TooltipProps) => boolean;
 export declare const Tooltip: import("@fluentui-react-native/framework").ComposableFunction<TooltipProps>;
 export default Tooltip;
 //# sourceMappingURL=Tooltip.d.ts.map

package/lib/Tooltip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Tooltip.d.ts","sourceRoot":"","sources":["../src/Tooltip.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAIpD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,UAAW,MAAM,aAAa,YAAY,KAAG,OAEtE,CAAC;AAEF,eAAO,MAAM,OAAO,6EAIlB,CAAC;AAIH,eAAe,OAAO,CAAC"}
+{"version":3,"file":"Tooltip.d.ts","sourceRoot":"","sources":["../src/Tooltip.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAIpD,eAAO,MAAM,OAAO,6EA2BlB,CAAC;AAIH,eAAe,OAAO,CAAC"}

package/lib/Tooltip.js

@@ -6,23 +6,31 @@
 import { __assign } from "tslib";
 /** @jsxRuntime classic */
 import * as React from 'react';
+import { findNodeHandle } from 'react-native';
 import { mergeProps, stagedComponent } from '@fluentui-react-native/framework';
 import { tooltipName } from './Tooltip.types';
 import NativeTooltipView from './TooltipNativeComponent';
-/**
- * A function which determines if a set of styles should be applied to the component given the current state and props of the tooltip.
- *
- * @param layer The name of the state that is being checked for
- * @param userProps The props that were passed into the tooltip
- * @returns Whether the styles that are assigned to the layer should be applied to the tooltip
- */
-export var tooltipLookup = function (layer, userProps) {
-    return userProps[layer];
-};
 export var Tooltip = stagedComponent(function (props) {
-    return function (rest, children) {
-        return React.createElement(NativeTooltipView, __assign({}, mergeProps(props, rest)), children);
+    var target = props.target;
+    var _a = React.useState(null), nativeTarget = _a[0], setNativeTarget = _a[1];
+    React.useLayoutEffect(function () {
+        if (typeof target === 'string') {
+            // Pass string type `target` directly
+            setNativeTarget(target);
+        }
+        else if (target === null || target === void 0 ? void 0 : target.current) {
+            // Pass the tagID for a valid ref `target`
+            setNativeTarget(findNodeHandle(target.current));
+        }
+        else {
+            // Clear `target` so we may fall back on `anchorRect` if provided
+            setNativeTarget(null);
+        }
+    }, [target]);
+    var TooltipComponent = function (rest, children) {
+        return (React.createElement(NativeTooltipView, __assign({}, (nativeTarget && { target: nativeTarget }), mergeProps(props, rest)), children));
     };
+    return TooltipComponent;
 });
 Tooltip.displayName = tooltipName;
 export default Tooltip;

package/lib/Tooltip.js.map

@@ -1 +1 @@
-{"version":3,"file":"Tooltip.js","sourceRoot":"","sources":["../src/Tooltip.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;;AAEH,0BAA0B;AAC1B,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAG/E,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,iBAAiB,MAAM,0BAA0B,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,CAAC,IAAM,aAAa,GAAG,UAAC,KAAa,EAAE,SAAuB;IAClE,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC;AAC1B,CAAC,CAAC;AAEF,MAAM,CAAC,IAAM,OAAO,GAAG,eAAe,CAAC,UAAC,KAAmB;IACzD,OAAO,UAAC,IAAkB,EAAE,QAAyB;QACnD,OAAO,oBAAC,iBAAiB,eAAK,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,QAAQ,CAAqB,CAAC;IACxF,CAAC,CAAC;AACJ,CAAC,CAAC,CAAC;AAEH,OAAO,CAAC,WAAW,GAAG,WAAW,CAAC;AAElC,eAAe,OAAO,CAAC"}
+{"version":3,"file":"Tooltip.js","sourceRoot":"","sources":["../src/Tooltip.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;;AAEH,0BAA0B;AAC1B,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAG/E,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,iBAAiB,MAAM,0BAA0B,CAAC;AAEzD,MAAM,CAAC,IAAM,OAAO,GAAG,eAAe,CAAC,UAAC,KAAmB;IACjD,IAAA,MAAM,GAAK,KAAK,OAAV,CAAW;IAEnB,IAAA,KAAkC,KAAK,CAAC,QAAQ,CAAyB,IAAI,CAAC,EAA7E,YAAY,QAAA,EAAE,eAAe,QAAgD,CAAC;IAErF,KAAK,CAAC,eAAe,CAAC;QACpB,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE;YAC9B,qCAAqC;YACrC,eAAe,CAAC,MAAM,CAAC,CAAC;SACzB;aAAM,IAAI,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,OAAO,EAAE;YAC1B,0CAA0C;YAC1C,eAAe,CAAC,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;SACjD;aAAM;YACL,iEAAiE;YACjE,eAAe,CAAC,IAAI,CAAC,CAAC;SACvB;IACH,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAEb,IAAM,gBAAgB,GAAG,UAAC,IAAkB,EAAE,QAAyB;QACrE,OAAO,CACL,oBAAC,iBAAiB,eAAK,CAAC,YAAY,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,EAAM,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,GAC3F,QAAQ,CACS,CACrB,CAAC;IACJ,CAAC,CAAC;IAEF,OAAO,gBAAgB,CAAC;AAC1B,CAAC,CAAC,CAAC;AAEH,OAAO,CAAC,WAAW,GAAG,WAAW,CAAC;AAElC,eAAe,OAAO,CAAC"}

package/lib-commonjs/Tooltip.d.ts

@@ -4,14 +4,6 @@
  * @format
  */
 import type { TooltipProps } from './Tooltip.types';
-/**
- * A function which determines if a set of styles should be applied to the component given the current state and props of the tooltip.
- *
- * @param layer The name of the state that is being checked for
- * @param userProps The props that were passed into the tooltip
- * @returns Whether the styles that are assigned to the layer should be applied to the tooltip
- */
-export declare const tooltipLookup: (layer: string, userProps: TooltipProps) => boolean;
 export declare const Tooltip: import("@fluentui-react-native/framework").ComposableFunction<TooltipProps>;
 export default Tooltip;
 //# sourceMappingURL=Tooltip.d.ts.map

package/lib-commonjs/Tooltip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Tooltip.d.ts","sourceRoot":"","sources":["../src/Tooltip.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAIpD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,UAAW,MAAM,aAAa,YAAY,KAAG,OAEtE,CAAC;AAEF,eAAO,MAAM,OAAO,6EAIlB,CAAC;AAIH,eAAe,OAAO,CAAC"}
+{"version":3,"file":"Tooltip.d.ts","sourceRoot":"","sources":["../src/Tooltip.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAIpD,eAAO,MAAM,OAAO,6EA2BlB,CAAC;AAIH,eAAe,OAAO,CAAC"}

package/lib-commonjs/Tooltip.js

@@ -5,28 +5,35 @@
  * @format
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Tooltip = exports.tooltipLookup = void 0;
+exports.Tooltip = void 0;
 var tslib_1 = require("tslib");
 /** @jsxRuntime classic */
 var React = tslib_1.__importStar(require("react"));
+var react_native_1 = require("react-native");
 var framework_1 = require("@fluentui-react-native/framework");
 var Tooltip_types_1 = require("./Tooltip.types");
 var TooltipNativeComponent_1 = tslib_1.__importDefault(require("./TooltipNativeComponent"));
-/**
- * A function which determines if a set of styles should be applied to the component given the current state and props of the tooltip.
- *
- * @param layer The name of the state that is being checked for
- * @param userProps The props that were passed into the tooltip
- * @returns Whether the styles that are assigned to the layer should be applied to the tooltip
- */
-var tooltipLookup = function (layer, userProps) {
-    return userProps[layer];
-};
-exports.tooltipLookup = tooltipLookup;
 exports.Tooltip = (0, framework_1.stagedComponent)(function (props) {
-    return function (rest, children) {
-        return React.createElement(TooltipNativeComponent_1.default, tslib_1.__assign({}, (0, framework_1.mergeProps)(props, rest)), children);
+    var target = props.target;
+    var _a = React.useState(null), nativeTarget = _a[0], setNativeTarget = _a[1];
+    React.useLayoutEffect(function () {
+        if (typeof target === 'string') {
+            // Pass string type `target` directly
+            setNativeTarget(target);
+        }
+        else if (target === null || target === void 0 ? void 0 : target.current) {
+            // Pass the tagID for a valid ref `target`
+            setNativeTarget((0, react_native_1.findNodeHandle)(target.current));
+        }
+        else {
+            // Clear `target` so we may fall back on `anchorRect` if provided
+            setNativeTarget(null);
+        }
+    }, [target]);
+    var TooltipComponent = function (rest, children) {
+        return (React.createElement(TooltipNativeComponent_1.default, tslib_1.__assign({}, (nativeTarget && { target: nativeTarget }), (0, framework_1.mergeProps)(props, rest)), children));
     };
+    return TooltipComponent;
 });
 exports.Tooltip.displayName = Tooltip_types_1.tooltipName;
 exports.default = exports.Tooltip;

package/lib-commonjs/Tooltip.js.map

@@ -1 +1 @@
-{"version":3,"file":"Tooltip.js","sourceRoot":"","sources":["../src/Tooltip.tsx"],"names":[],"mappings":";AAAA;;;;GAIG;;;;AAEH,0BAA0B;AAC1B,mDAA+B;AAE/B,8DAA+E;AAG/E,iDAA8C;AAC9C,4FAAyD;AAEzD;;;;;;GAMG;AACI,IAAM,aAAa,GAAG,UAAC,KAAa,EAAE,SAAuB;IAClE,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC;AAC1B,CAAC,CAAC;AAFW,QAAA,aAAa,iBAExB;AAEW,QAAA,OAAO,GAAG,IAAA,2BAAe,EAAC,UAAC,KAAmB;IACzD,OAAO,UAAC,IAAkB,EAAE,QAAyB;QACnD,OAAO,oBAAC,gCAAiB,uBAAK,IAAA,sBAAU,EAAC,KAAK,EAAE,IAAI,CAAC,GAAG,QAAQ,CAAqB,CAAC;IACxF,CAAC,CAAC;AACJ,CAAC,CAAC,CAAC;AAEH,eAAO,CAAC,WAAW,GAAG,2BAAW,CAAC;AAElC,kBAAe,eAAO,CAAC"}
+{"version":3,"file":"Tooltip.js","sourceRoot":"","sources":["../src/Tooltip.tsx"],"names":[],"mappings":";AAAA;;;;GAIG;;;;AAEH,0BAA0B;AAC1B,mDAA+B;AAC/B,6CAA8C;AAE9C,8DAA+E;AAG/E,iDAA8C;AAC9C,4FAAyD;AAE5C,QAAA,OAAO,GAAG,IAAA,2BAAe,EAAC,UAAC,KAAmB;IACjD,IAAA,MAAM,GAAK,KAAK,OAAV,CAAW;IAEnB,IAAA,KAAkC,KAAK,CAAC,QAAQ,CAAyB,IAAI,CAAC,EAA7E,YAAY,QAAA,EAAE,eAAe,QAAgD,CAAC;IAErF,KAAK,CAAC,eAAe,CAAC;QACpB,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE;YAC9B,qCAAqC;YACrC,eAAe,CAAC,MAAM,CAAC,CAAC;SACzB;aAAM,IAAI,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,OAAO,EAAE;YAC1B,0CAA0C;YAC1C,eAAe,CAAC,IAAA,6BAAc,EAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;SACjD;aAAM;YACL,iEAAiE;YACjE,eAAe,CAAC,IAAI,CAAC,CAAC;SACvB;IACH,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAEb,IAAM,gBAAgB,GAAG,UAAC,IAAkB,EAAE,QAAyB;QACrE,OAAO,CACL,oBAAC,gCAAiB,uBAAK,CAAC,YAAY,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,EAAM,IAAA,sBAAU,EAAC,KAAK,EAAE,IAAI,CAAC,GAC3F,QAAQ,CACS,CACrB,CAAC;IACJ,CAAC,CAAC;IAEF,OAAO,gBAAgB,CAAC;AAC1B,CAAC,CAAC,CAAC;AAEH,eAAO,CAAC,WAAW,GAAG,2BAAW,CAAC;AAElC,kBAAe,eAAO,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluentui-react-native/tooltip",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "A cross-platform Tooltip component for React Native.",
   "main": "lib-commonjs/index.js",
   "module": "lib/index.js",
@@ -27,7 +27,7 @@
     "tslib": "^2.3.1"
   },
   "devDependencies": {
-    "@fluentui-react-native/button": "0.37.1",
+    "@fluentui-react-native/button": "0.37.2",
     "@fluentui-react-native/eslint-config-rules": "0.1.1",
     "@fluentui-react-native/scripts": "0.1.1",
     "@fluentui-react-native/test-tools": "0.1.1",

package/src/Tooltip.tsx

@@ -6,6 +6,7 @@
 
 /** @jsxRuntime classic */
 import * as React from 'react';
+import { findNodeHandle } from 'react-native';
 
 import { mergeProps, stagedComponent } from '@fluentui-react-native/framework';
 
@@ -13,21 +14,33 @@ import type { TooltipProps } from './Tooltip.types';
 import { tooltipName } from './Tooltip.types';
 import NativeTooltipView from './TooltipNativeComponent';
 
-/**
- * A function which determines if a set of styles should be applied to the component given the current state and props of the tooltip.
- *
- * @param layer The name of the state that is being checked for
- * @param userProps The props that were passed into the tooltip
- * @returns Whether the styles that are assigned to the layer should be applied to the tooltip
- */
-export const tooltipLookup = (layer: string, userProps: TooltipProps): boolean => {
-  return userProps[layer];
-};
-
 export const Tooltip = stagedComponent((props: TooltipProps) => {
-  return (rest: TooltipProps, children: React.ReactNode) => {
-    return <NativeTooltipView {...mergeProps(props, rest)}>{children}</NativeTooltipView>;
+  const { target } = props;
+
+  const [nativeTarget, setNativeTarget] = React.useState<number | string | null>(null);
+
+  React.useLayoutEffect(() => {
+    if (typeof target === 'string') {
+      // Pass string type `target` directly
+      setNativeTarget(target);
+    } else if (target?.current) {
+      // Pass the tagID for a valid ref `target`
+      setNativeTarget(findNodeHandle(target.current));
+    } else {
+      // Clear `target` so we may fall back on `anchorRect` if provided
+      setNativeTarget(null);
+    }
+  }, [target]);
+
+  const TooltipComponent = (rest: TooltipProps, children: React.ReactNode) => {
+    return (
+      <NativeTooltipView {...(nativeTarget && { target: nativeTarget })} {...mergeProps(props, rest)}>
+        {children}
+      </NativeTooltipView>
+    );
   };
+
+  return TooltipComponent;
 });
 
 Tooltip.displayName = tooltipName;