@react-md/core 1.0.0-next.0

package/dist/tooltip/useTooltip.d.ts

@@ -0,0 +1,242 @@
+import type { CSSProperties, FocusEvent, MouseEvent, Ref, TouchEvent } from "react";
+import type { SimplePosition } from "../positioning/types.js";
+import type { FixedPositioningTransitionCallbacks } from "../positioning/useFixedPositioning.js";
+import type { UseStateSetter } from "../types.js";
+import type { TooltipPositionHookOptions } from "./useTooltipPosition.js";
+declare module "react" {
+    interface CSSProperties {
+        "--rmd-tooltip-background-color"?: string;
+        "--rmd-tooltip-color"?: string;
+        "--rmd-tooltip-spacing"?: string | number;
+    }
+}
+/** @remarks \@since 2.8.0 */
+export interface TooltipPositioningOptions {
+    style?: CSSProperties;
+    /**
+     * @defaultValue `DEFAULT_TOOLTIP_MARGIN`
+     * @see {@link DEFAULT_TOOLTIP_MARGIN}
+     */
+    vwMargin?: number;
+    /**
+     * @defaultValue `DEFAULT_TOOLTIP_MARGIN`
+     * @see {@link DEFAULT_TOOLTIP_MARGIN}
+     */
+    vhMargin?: number;
+    /**
+     * @defaultValue `false`
+     */
+    dense?: boolean;
+    /**
+     * @defaultValue `DEFAULT_TOOLTIP_SPACING`
+     * @see {@link DEFAULT_TOOLTIP_SPACING}
+     */
+    spacing?: number | string;
+    /**
+     * @defaultValue `DEFAULT_TOOLTIP_DENSE_SPACING`
+     * @see {@link DEFAULT_TOOLTIP_DENSE_SPACING}
+     */
+    denseSpacing?: number | string;
+    /**
+     * @defaultValue `false`
+     */
+    disableSwapping?: boolean;
+    /**
+     * @defaultValue `false`
+     */
+    disableAutoSpacing?: boolean;
+}
+/**
+ * @remarks
+ * \@since 2.8.0
+ * \@since 6.0.0 Removed the `TooltipTouchEventHandlers` and
+ * `TooltipKeyboardEventHandlers` types, removed the need for the `onKeyDown`
+ * event, and infer element typeparam while calling instead of at hook level.
+ */
+export interface TooltippedElementEventHandlers {
+    onBlur?<E extends HTMLElement>(event: FocusEvent<E>): void;
+    onFocus?<E extends HTMLElement>(event: FocusEvent<E>): void;
+    onMouseEnter?<E extends HTMLElement>(event: MouseEvent<E>): void;
+    onMouseLeave?<E extends HTMLElement>(event: MouseEvent<E>): void;
+    onTouchStart?<E extends HTMLElement>(event: TouchEvent<E>): void;
+    onTouchEnd?<E extends HTMLElement>(event: TouchEvent<E>): void;
+    onContextMenu?<E extends HTMLElement>(event: MouseEvent<E>): void;
+}
+/** @remarks \@since 2.8.0 */
+export interface ProvidedTooltippedElementProps extends Required<TooltippedElementEventHandlers> {
+    "aria-describedby": string | undefined;
+    id: string;
+}
+/**
+ * @remarks
+ * \@since 2.8.0
+ * \@since 6.0.0 A major API change for the hover mode behavior and no longer
+ * requires a `baseId`/`id` for the tooltip. Also renamed from
+ * `TooltipHookOptions` to `TooltipOptions` to match other hook naming
+ * conventions.
+ */
+export interface TooltipOptions extends FixedPositioningTransitionCallbacks, TooltippedElementEventHandlers, TooltipPositioningOptions, TooltipPositionHookOptions {
+    /**
+     * @defaultValue `"tooltip-" + useId()`
+     */
+    id?: string;
+    /**
+     * An optional override for the `aria-describedby`
+     */
+    describedBy?: string;
+    /**
+     * Any styles to be merged with the fixed positioning styles for the tooltip.
+     */
+    style?: CSSProperties;
+    /**
+     * Boolean if the event handlers should no longer attempt to show a tooltip. This
+     * should be set to `true` when your component might not have a tooltip associated
+     * with it.
+     *
+     * @example
+     * Real World Example
+     * ```tsx
+     * import { Button, ButtonProps, Tooltip, useTooltip  } from "@react-md/core";
+     * import type { ReactElement, ReactNode } from "react";
+     *
+     * export interface TooltippedButtonProps extends ButtonProps {
+     *   tooltip?: ReactNode;
+     * }
+     *
+     * export function TooltippedButton({
+     *   id,
+     *   tooltip,
+     *   children,
+     *   onBlur,
+     *   onFocus,
+     *   onMouseEnter,
+     *   onMouseLeave,
+     *   onTouchStart,
+     *   onTouchEnd,
+     *   onContextMenu,
+     *   ...props
+     * }: TooltippedButtonProps): ReactElement {
+     *   const { elementProps, tooltipProps } = useTooltip({
+     *     id,
+     *     disabled: !tooltip,
+     *     onBlur,
+     *     onFocus,
+     *     onMouseEnter,
+     *     onMouseLeave,
+     *     onTouchStart,
+     *     onTouchEnd,
+     *     onContextMenu,
+     *   });
+     *
+     *   return (
+     *     <>
+     *       <Button {...props} {...elementProps}>
+     *         {children}
+     *       </Button>
+     *       <Tooltip {...tooltipProps}>{tooltip}</Tooltip>
+     *     </>
+     *   );
+     * }
+     * ```
+     *
+     * @defaultValue `false`
+     * @remarks \@since 5.1.0
+     */
+    disabled?: boolean;
+    /**
+     * The amount of time (in ms) to hover an element before the tooltip becomes
+     * visible.
+     *
+     * The default value is really the current hover timeout from the
+     * `TooltipHoverModeProvider`.
+     *
+     * @defaultValue `DEFAULT_TOOLTIP_DELAY`
+     */
+    hoverTime?: number;
+    /**
+     * The amount of time to wait before triggering the exit animation for the
+     * tooltip.
+     *
+     * The default value is really the current leaveTimeout timeout from the
+     * `TooltipHoverModeProvider`.
+     *
+     * @defaultValue `0`
+     */
+    leaveTime?: number;
+}
+/**
+ * @remarks
+ * \@since 2.8.0
+ * \@since 6.0.0 This was renamed from `TooltipHookProvidedTooltipProps`
+ */
+export interface ProvidedTooltipProps extends Required<FixedPositioningTransitionCallbacks> {
+    id: string;
+    ref: Ref<HTMLSpanElement>;
+    dense: boolean;
+    style: CSSProperties;
+    visible: boolean;
+    position: SimplePosition;
+}
+/**
+ * @remarks
+ * \@since 2.8.0
+ * \@since 6.0.0 No longer returns any properties from the hover mode provider
+ * because of the major API change to hover mode.. Also renamed from
+ * `TooltipHookReturnValue` to `TooltipImplementation` to match other hook
+ * naming conventions.
+ */
+export interface TooltipImplementation {
+    visible: boolean;
+    setVisible: UseStateSetter<boolean>;
+    animatedOnce: boolean;
+    elementProps: ProvidedTooltippedElementProps;
+    tooltipProps: ProvidedTooltipProps;
+    /**
+     * This is a wrapper around the {@link setVisible} behavior that will also
+     * clear any pending timeouts.
+     */
+    hideTooltip(): void;
+}
+/**
+ * @example
+ * Simple Usage
+ * ```tsx
+ * import { Button, useTooltip, Tooltip } from "@react-md/core";
+ *
+ * function Example() {
+ *   const { elementProps, tooltipProps } = useTooltip();
+ *
+ *   return (
+ *     <>
+ *       <Button {...elementProps}>Button</Button>
+ *       <Tooltip {...tooltipProps}>
+ *         Tooltip Content
+ *       </Tooltip>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * ## Inspecting Tooltip Styles
+ *
+ * Since tooltips will disappear on blur, mouseleave, etc, it is a bit hard to
+ * inspect the tooltip styles. In dev mode, you can manually set the visibility
+ * to `true` through the dev tools.
+ * - find your tooltip implementation
+ * - expand the Tooltip hook
+ * - expand the HoverMode hook
+ * - set the first boolean state to `true`
+ *
+ * The tooltip will now remain visible allowing you to find it within the
+ * "Inspector" tab in the dev tools.
+ *
+ * @remarks
+ * \@since 2.8.0
+ * \@since 6.0.0 Uses a separate `TooltipHoverModeProvider`.
+ *
+ * TODO: I need to fix the tooltip for click events and history changes since
+ * the mouseleave event will not be correctly bubbled if hovering a child
+ * element when the click or history update happens. this causes the tooltip to
+ * stay visible
+ */
+export declare function useTooltip(options?: TooltipOptions): TooltipImplementation;

package/dist/tooltip/useTooltip.js

@@ -0,0 +1,258 @@
+"use client";
+import { cnb } from "cnbuilder";
+import { useCallback, useEffect, useId, useRef } from "react";
+import { useHoverMode } from "../hoverMode/useHoverMode.js";
+import { useUserInteractionMode } from "../interaction/UserInteractionModeProvider.js";
+import { useFixedPositioning } from "../positioning/useFixedPositioning.js";
+import { usePageInactive } from "../usePageInactive.js";
+import { parseCssLengthUnit } from "../utils/parseCssLengthUnit.js";
+import { useTooltipHoverMode } from "./TooltipHoverModeProvider.js";
+import { DEFAULT_TOOLTIP_DENSE_SPACING, DEFAULT_TOOLTIP_MARGIN, DEFAULT_TOOLTIP_POSITION, DEFAULT_TOOLTIP_SPACING, DEFAULT_TOOLTIP_THRESHOLD, TOOLTIP_SPACING_VAR } from "./constants.js";
+import { useTooltipPosition } from "./useTooltipPosition.js";
+import { getAnchor } from "./utils.js";
+const noop = ()=>{
+// do nothing
+};
+/**
+ * @example
+ * Simple Usage
+ * ```tsx
+ * import { Button, useTooltip, Tooltip } from "@react-md/core";
+ *
+ * function Example() {
+ *   const { elementProps, tooltipProps } = useTooltip();
+ *
+ *   return (
+ *     <>
+ *       <Button {...elementProps}>Button</Button>
+ *       <Tooltip {...tooltipProps}>
+ *         Tooltip Content
+ *       </Tooltip>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * ## Inspecting Tooltip Styles
+ *
+ * Since tooltips will disappear on blur, mouseleave, etc, it is a bit hard to
+ * inspect the tooltip styles. In dev mode, you can manually set the visibility
+ * to `true` through the dev tools.
+ * - find your tooltip implementation
+ * - expand the Tooltip hook
+ * - expand the HoverMode hook
+ * - set the first boolean state to `true`
+ *
+ * The tooltip will now remain visible allowing you to find it within the
+ * "Inspector" tab in the dev tools.
+ *
+ * @remarks
+ * \@since 2.8.0
+ * \@since 6.0.0 Uses a separate `TooltipHoverModeProvider`.
+ *
+ * TODO: I need to fix the tooltip for click events and history changes since
+ * the mouseleave event will not be correctly bubbled if hovering a child
+ * element when the click or history update happens. this causes the tooltip to
+ * stay visible
+ */ export function useTooltip(options = {}) {
+    const { id: propId, style: propStyle, disabled = false, describedBy, dense = false, hoverTime, leaveTime, vwMargin = DEFAULT_TOOLTIP_MARGIN, vhMargin = DEFAULT_TOOLTIP_MARGIN, spacing = DEFAULT_TOOLTIP_SPACING, denseSpacing = DEFAULT_TOOLTIP_DENSE_SPACING, disableSwapping, disableAutoSpacing, position: determinedPosition, defaultPosition = DEFAULT_TOOLTIP_POSITION, threshold = DEFAULT_TOOLTIP_THRESHOLD, onBlur = noop, onFocus = noop, onMouseEnter = noop, onMouseLeave = noop, onTouchStart = noop, onTouchEnd = noop, onContextMenu = noop, onEnter = noop, onEntering, onEntered = noop, onExited } = options;
+    const fallbackId = useId();
+    const id = propId || fallbackId;
+    const tooltipId = `${id}-tooltip`;
+    const { animatedOnceRef, hoverTimeoutRef, leaveTimeoutRef, enableHoverMode, disableHoverMode, startDisableTimer, clearDisableTimer } = useTooltipHoverMode();
+    const { visible, setVisible, startShowFlow, startHideFlow, clearVisibilityTimeout } = useHoverMode({
+        hoverTime,
+        hoverTimeoutRef,
+        leaveTime,
+        leaveTimeoutRef,
+        enableHoverMode,
+        disableHoverMode,
+        startDisableTimer,
+        clearDisableTimer
+    });
+    const [position, updatePosition] = useTooltipPosition({
+        position: determinedPosition,
+        defaultPosition,
+        threshold
+    });
+    const mode = useUserInteractionMode();
+    const elementRef = useRef(null);
+    const tooltipRef = useRef(null);
+    const initiatedBy = useRef(null);
+    const { ref, style, callbacks } = useFixedPositioning({
+        nodeRef: tooltipRef,
+        style: propStyle,
+        fixedTo: elementRef,
+        anchor: getAnchor(position),
+        disableSwapping: disableSwapping ?? !!determinedPosition,
+        getFixedPositionOptions () {
+            let tooltipSpacing = dense ? denseSpacing : spacing;
+            const tooltip = tooltipRef.current;
+            if (!disableAutoSpacing && tooltip) {
+                tooltipSpacing = window.getComputedStyle(tooltip).getPropertyValue(TOOLTIP_SPACING_VAR) || spacing;
+            }
+            const currentSpacing = parseCssLengthUnit({
+                value: tooltipSpacing
+            });
+            const horizontal = position === "left" || position === "right";
+            return {
+                vwMargin,
+                vhMargin,
+                xMargin: horizontal ? currentSpacing : undefined,
+                yMargin: horizontal ? undefined : currentSpacing
+            };
+        },
+        onEnter (appearing) {
+            onEnter(appearing);
+            // This allows you to inspect the tooltip styles through the element
+            // inspector without first hovering or focusing the tooltipped element
+            // beforehand by setting the `HoverMode` hook to `true`
+            if (process.env.NODE_ENV !== "production" && !elementRef.current) {
+                elementRef.current = document.getElementById(id);
+            }
+        },
+        onEntering,
+        onEntered (appearing) {
+            onEntered(appearing);
+            animatedOnceRef.current = true;
+        },
+        onExited
+    });
+    const hideTooltip = useCallback(()=>{
+        initiatedBy.current = null;
+        disableHoverMode();
+        clearVisibilityTimeout();
+        setVisible(false);
+    }, [
+        clearVisibilityTimeout,
+        disableHoverMode,
+        setVisible
+    ]);
+    useEffect(()=>{
+        if (!visible) {
+            return;
+        }
+        const handleKeyDown = (event)=>{
+            if (event.key === "Escape") {
+                hideTooltip();
+            }
+        };
+        window.addEventListener("keydown", handleKeyDown);
+        window.addEventListener("scroll", hideTooltip, true);
+        window.addEventListener("touchend", hideTooltip, true);
+        return ()=>{
+            window.removeEventListener("keydown", handleKeyDown);
+            window.removeEventListener("scroll", hideTooltip, true);
+            window.removeEventListener("touchend", hideTooltip, true);
+        };
+    }, [
+        hideTooltip,
+        visible
+    ]);
+    const refocusFrame = useRef(0);
+    const pageInactive = useRef(false);
+    usePageInactive({
+        disabled,
+        onDisabledCleanup: hideTooltip,
+        onChange (active) {
+            if (active) {
+                refocusFrame.current = window.requestAnimationFrame(()=>{
+                    pageInactive.current = false;
+                });
+                return;
+            }
+            pageInactive.current = true;
+            hideTooltip();
+        }
+    });
+    return {
+        visible,
+        setVisible,
+        hideTooltip,
+        animatedOnce: animatedOnceRef.current,
+        tooltipProps: {
+            id: tooltipId,
+            ref,
+            dense,
+            style,
+            visible,
+            position,
+            ...callbacks
+        },
+        elementProps: {
+            "aria-describedby": cnb(visible && tooltipId, describedBy) || undefined,
+            id,
+            onMouseEnter (event) {
+                onMouseEnter(event);
+                if (disabled || mode === "touch" || initiatedBy.current !== null) {
+                    return;
+                }
+                initiatedBy.current = "mouse";
+                elementRef.current = event.currentTarget;
+                updatePosition(event.currentTarget);
+                startShowFlow(id);
+            },
+            onMouseLeave (event) {
+                onMouseLeave(event);
+                if (disabled || initiatedBy.current !== "mouse") {
+                    return;
+                }
+                startHideFlow();
+                initiatedBy.current = null;
+            },
+            onBlur (event) {
+                onBlur(event);
+                if (disabled) {
+                    return;
+                }
+                initiatedBy.current = null;
+                startHideFlow();
+            },
+            onFocus (event) {
+                onFocus(event);
+                // skip the focus events when the browser is re-focused if the user
+                // pressed alt-tab, minimized the browser, etc
+                if (disabled || mode !== "keyboard" || initiatedBy.current !== null || pageInactive.current) {
+                    pageInactive.current = false;
+                    return;
+                }
+                initiatedBy.current = "keyboard";
+                elementRef.current = event.currentTarget;
+                updatePosition(event.currentTarget);
+                startShowFlow(id);
+            },
+            onTouchStart (event) {
+                onTouchStart(event);
+                if (disabled || initiatedBy.current !== null) {
+                    return;
+                }
+                initiatedBy.current = "touch";
+                elementRef.current = event.currentTarget;
+                updatePosition(event.currentTarget);
+                startShowFlow(id);
+            },
+            onTouchEnd (event) {
+                onTouchEnd(event);
+                if (disabled) {
+                    return;
+                }
+                initiatedBy.current = null;
+                startHideFlow();
+            },
+            onContextMenu (event) {
+                onContextMenu(event);
+                if (disabled || initiatedBy.current !== "touch") {
+                    return;
+                }
+                event.preventDefault();
+                const selection = window.getSelection();
+                const node = selection?.anchorNode?.parentElement;
+                if (node && event.currentTarget.contains(node)) {
+                    selection.empty();
+                }
+            }
+        }
+    };
+}
+
+//# sourceMappingURL=useTooltip.js.map

package/dist/tooltip/useTooltip.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tooltip/useTooltip.ts"],"sourcesContent":["\"use client\";\nimport { cnb } from \"cnbuilder\";\nimport type {\n  CSSProperties,\n  FocusEvent,\n  MouseEvent,\n  Ref,\n  TouchEvent,\n} from \"react\";\nimport { useCallback, useEffect, useId, useRef } from \"react\";\nimport { useHoverMode } from \"../hoverMode/useHoverMode.js\";\nimport type { UserInteractionMode } from \"../interaction/UserInteractionModeProvider.js\";\nimport { useUserInteractionMode } from \"../interaction/UserInteractionModeProvider.js\";\nimport type { SimplePosition } from \"../positioning/types.js\";\nimport type { FixedPositioningTransitionCallbacks } from \"../positioning/useFixedPositioning.js\";\nimport { useFixedPositioning } from \"../positioning/useFixedPositioning.js\";\nimport type { UseStateSetter } from \"../types.js\";\nimport { usePageInactive } from \"../usePageInactive.js\";\nimport { parseCssLengthUnit } from \"../utils/parseCssLengthUnit.js\";\nimport { useTooltipHoverMode } from \"./TooltipHoverModeProvider.js\";\nimport {\n  DEFAULT_TOOLTIP_DENSE_SPACING,\n  DEFAULT_TOOLTIP_MARGIN,\n  DEFAULT_TOOLTIP_POSITION,\n  DEFAULT_TOOLTIP_SPACING,\n  DEFAULT_TOOLTIP_THRESHOLD,\n  TOOLTIP_SPACING_VAR,\n} from \"./constants.js\";\nimport type { TooltipPositionHookOptions } from \"./useTooltipPosition.js\";\nimport { useTooltipPosition } from \"./useTooltipPosition.js\";\nimport { getAnchor } from \"./utils.js\";\n\ndeclare module \"react\" {\n  interface CSSProperties {\n    \"--rmd-tooltip-background-color\"?: string;\n    \"--rmd-tooltip-color\"?: string;\n    \"--rmd-tooltip-spacing\"?: string | number;\n  }\n}\n\nconst noop = (): void => {\n  // do nothing\n};\n\n/** @remarks \\@since 2.8.0 */\nexport interface TooltipPositioningOptions {\n  style?: CSSProperties;\n\n  /**\n   * @defaultValue `DEFAULT_TOOLTIP_MARGIN`\n   * @see {@link DEFAULT_TOOLTIP_MARGIN}\n   */\n  vwMargin?: number;\n\n  /**\n   * @defaultValue `DEFAULT_TOOLTIP_MARGIN`\n   * @see {@link DEFAULT_TOOLTIP_MARGIN}\n   */\n  vhMargin?: number;\n\n  /**\n   * @defaultValue `false`\n   */\n  dense?: boolean;\n\n  /**\n   * @defaultValue `DEFAULT_TOOLTIP_SPACING`\n   * @see {@link DEFAULT_TOOLTIP_SPACING}\n   */\n  spacing?: number | string;\n\n  /**\n   * @defaultValue `DEFAULT_TOOLTIP_DENSE_SPACING`\n   * @see {@link DEFAULT_TOOLTIP_DENSE_SPACING}\n   */\n  denseSpacing?: number | string;\n\n  /**\n   * @defaultValue `false`\n   */\n  disableSwapping?: boolean;\n\n  /**\n   * @defaultValue `false`\n   */\n  disableAutoSpacing?: boolean;\n}\n\n/**\n * @remarks\n * \\@since 2.8.0\n * \\@since 6.0.0 Removed the `TooltipTouchEventHandlers` and\n * `TooltipKeyboardEventHandlers` types, removed the need for the `onKeyDown`\n * event, and infer element typeparam while calling instead of at hook level.\n */\nexport interface TooltippedElementEventHandlers {\n  onBlur?<E extends HTMLElement>(event: FocusEvent<E>): void;\n  onFocus?<E extends HTMLElement>(event: FocusEvent<E>): void;\n  onMouseEnter?<E extends HTMLElement>(event: MouseEvent<E>): void;\n  onMouseLeave?<E extends HTMLElement>(event: MouseEvent<E>): void;\n  onTouchStart?<E extends HTMLElement>(event: TouchEvent<E>): void;\n  onTouchEnd?<E extends HTMLElement>(event: TouchEvent<E>): void;\n  onContextMenu?<E extends HTMLElement>(event: MouseEvent<E>): void;\n}\n\n/** @remarks \\@since 2.8.0 */\nexport interface ProvidedTooltippedElementProps\n  extends Required<TooltippedElementEventHandlers> {\n  \"aria-describedby\": string | undefined;\n  id: string;\n}\n\n/**\n * @remarks\n * \\@since 2.8.0\n * \\@since 6.0.0 A major API change for the hover mode behavior and no longer\n * requires a `baseId`/`id` for the tooltip. Also renamed from\n * `TooltipHookOptions` to `TooltipOptions` to match other hook naming\n * conventions.\n */\nexport interface TooltipOptions\n  extends FixedPositioningTransitionCallbacks,\n    TooltippedElementEventHandlers,\n    TooltipPositioningOptions,\n    TooltipPositionHookOptions {\n  /**\n   * @defaultValue `\"tooltip-\" + useId()`\n   */\n  id?: string;\n\n  /**\n   * An optional override for the `aria-describedby`\n   */\n  describedBy?: string;\n\n  /**\n   * Any styles to be merged with the fixed positioning styles for the tooltip.\n   */\n  style?: CSSProperties;\n\n  /**\n   * Boolean if the event handlers should no longer attempt to show a tooltip. This\n   * should be set to `true` when your component might not have a tooltip associated\n   * with it.\n   *\n   * @example\n   * Real World Example\n   * ```tsx\n   * import { Button, ButtonProps, Tooltip, useTooltip  } from \"@react-md/core\";\n   * import type { ReactElement, ReactNode } from \"react\";\n   *\n   * export interface TooltippedButtonProps extends ButtonProps {\n   *   tooltip?: ReactNode;\n   * }\n   *\n   * export function TooltippedButton({\n   *   id,\n   *   tooltip,\n   *   children,\n   *   onBlur,\n   *   onFocus,\n   *   onMouseEnter,\n   *   onMouseLeave,\n   *   onTouchStart,\n   *   onTouchEnd,\n   *   onContextMenu,\n   *   ...props\n   * }: TooltippedButtonProps): ReactElement {\n   *   const { elementProps, tooltipProps } = useTooltip({\n   *     id,\n   *     disabled: !tooltip,\n   *     onBlur,\n   *     onFocus,\n   *     onMouseEnter,\n   *     onMouseLeave,\n   *     onTouchStart,\n   *     onTouchEnd,\n   *     onContextMenu,\n   *   });\n   *\n   *   return (\n   *     <>\n   *       <Button {...props} {...elementProps}>\n   *         {children}\n   *       </Button>\n   *       <Tooltip {...tooltipProps}>{tooltip}</Tooltip>\n   *     </>\n   *   );\n   * }\n   * ```\n   *\n   * @defaultValue `false`\n   * @remarks \\@since 5.1.0\n   */\n  disabled?: boolean;\n\n  /**\n   * The amount of time (in ms) to hover an element before the tooltip becomes\n   * visible.\n   *\n   * The default value is really the current hover timeout from the\n   * `TooltipHoverModeProvider`.\n   *\n   * @defaultValue `DEFAULT_TOOLTIP_DELAY`\n   */\n  hoverTime?: number;\n\n  /**\n   * The amount of time to wait before triggering the exit animation for the\n   * tooltip.\n   *\n   * The default value is really the current leaveTimeout timeout from the\n   * `TooltipHoverModeProvider`.\n   *\n   * @defaultValue `0`\n   */\n  leaveTime?: number;\n}\n\n/**\n * @remarks\n * \\@since 2.8.0\n * \\@since 6.0.0 This was renamed from `TooltipHookProvidedTooltipProps`\n */\nexport interface ProvidedTooltipProps\n  extends Required<FixedPositioningTransitionCallbacks> {\n  id: string;\n  ref: Ref<HTMLSpanElement>;\n  dense: boolean;\n  style: CSSProperties;\n  visible: boolean;\n  position: SimplePosition;\n}\n\n/**\n * @remarks\n * \\@since 2.8.0\n * \\@since 6.0.0 No longer returns any properties from the hover mode provider\n * because of the major API change to hover mode.. Also renamed from\n * `TooltipHookReturnValue` to `TooltipImplementation` to match other hook\n * naming conventions.\n */\nexport interface TooltipImplementation {\n  visible: boolean;\n  setVisible: UseStateSetter<boolean>;\n  animatedOnce: boolean;\n  elementProps: ProvidedTooltippedElementProps;\n  tooltipProps: ProvidedTooltipProps;\n\n  /**\n   * This is a wrapper around the {@link setVisible} behavior that will also\n   * clear any pending timeouts.\n   */\n  hideTooltip(): void;\n}\n\n/**\n * @example\n * Simple Usage\n * ```tsx\n * import { Button, useTooltip, Tooltip } from \"@react-md/core\";\n *\n * function Example() {\n *   const { elementProps, tooltipProps } = useTooltip();\n *\n *   return (\n *     <>\n *       <Button {...elementProps}>Button</Button>\n *       <Tooltip {...tooltipProps}>\n *         Tooltip Content\n *       </Tooltip>\n *     </>\n *   );\n * }\n * ```\n *\n * ## Inspecting Tooltip Styles\n *\n * Since tooltips will disappear on blur, mouseleave, etc, it is a bit hard to\n * inspect the tooltip styles. In dev mode, you can manually set the visibility\n * to `true` through the dev tools.\n * - find your tooltip implementation\n * - expand the Tooltip hook\n * - expand the HoverMode hook\n * - set the first boolean state to `true`\n *\n * The tooltip will now remain visible allowing you to find it within the\n * \"Inspector\" tab in the dev tools.\n *\n * @remarks\n * \\@since 2.8.0\n * \\@since 6.0.0 Uses a separate `TooltipHoverModeProvider`.\n *\n * TODO: I need to fix the tooltip for click events and history changes since\n * the mouseleave event will not be correctly bubbled if hovering a child\n * element when the click or history update happens. this causes the tooltip to\n * stay visible\n */\nexport function useTooltip(\n  options: TooltipOptions = {}\n): TooltipImplementation {\n  const {\n    id: propId,\n    style: propStyle,\n    disabled = false,\n    describedBy,\n    dense = false,\n    hoverTime,\n    leaveTime,\n    vwMargin = DEFAULT_TOOLTIP_MARGIN,\n    vhMargin = DEFAULT_TOOLTIP_MARGIN,\n    spacing = DEFAULT_TOOLTIP_SPACING,\n    denseSpacing = DEFAULT_TOOLTIP_DENSE_SPACING,\n    disableSwapping,\n    disableAutoSpacing,\n    position: determinedPosition,\n    defaultPosition = DEFAULT_TOOLTIP_POSITION,\n    threshold = DEFAULT_TOOLTIP_THRESHOLD,\n    onBlur = noop,\n    onFocus = noop,\n    onMouseEnter = noop,\n    onMouseLeave = noop,\n    onTouchStart = noop,\n    onTouchEnd = noop,\n    onContextMenu = noop,\n    onEnter = noop,\n    onEntering,\n    onEntered = noop,\n    onExited,\n  } = options;\n\n  const fallbackId = useId();\n  const id = propId || fallbackId;\n  const tooltipId = `${id}-tooltip`;\n  const {\n    animatedOnceRef,\n    hoverTimeoutRef,\n    leaveTimeoutRef,\n    enableHoverMode,\n    disableHoverMode,\n    startDisableTimer,\n    clearDisableTimer,\n  } = useTooltipHoverMode();\n  const {\n    visible,\n    setVisible,\n    startShowFlow,\n    startHideFlow,\n    clearVisibilityTimeout,\n  } = useHoverMode({\n    hoverTime,\n    hoverTimeoutRef,\n    leaveTime,\n    leaveTimeoutRef,\n    enableHoverMode,\n    disableHoverMode,\n    startDisableTimer,\n    clearDisableTimer,\n  });\n  const [position, updatePosition] = useTooltipPosition({\n    position: determinedPosition,\n    defaultPosition,\n    threshold,\n  });\n\n  const mode = useUserInteractionMode();\n  const elementRef = useRef<HTMLElement | null>(null);\n  const tooltipRef = useRef<HTMLSpanElement>(null);\n  const initiatedBy = useRef<UserInteractionMode | null>(null);\n  const { ref, style, callbacks } = useFixedPositioning({\n    nodeRef: tooltipRef,\n    style: propStyle,\n    fixedTo: elementRef,\n    anchor: getAnchor(position),\n    disableSwapping: disableSwapping ?? !!determinedPosition,\n    getFixedPositionOptions() {\n      let tooltipSpacing = dense ? denseSpacing : spacing;\n      const tooltip = tooltipRef.current;\n      if (!disableAutoSpacing && tooltip) {\n        tooltipSpacing =\n          window\n            .getComputedStyle(tooltip)\n            .getPropertyValue(TOOLTIP_SPACING_VAR) || spacing;\n      }\n\n      const currentSpacing = parseCssLengthUnit({\n        value: tooltipSpacing,\n      });\n      const horizontal = position === \"left\" || position === \"right\";\n\n      return {\n        vwMargin,\n        vhMargin,\n        xMargin: horizontal ? currentSpacing : undefined,\n        yMargin: horizontal ? undefined : currentSpacing,\n      };\n    },\n    onEnter(appearing) {\n      onEnter(appearing);\n\n      // This allows you to inspect the tooltip styles through the element\n      // inspector without first hovering or focusing the tooltipped element\n      // beforehand by setting the `HoverMode` hook to `true`\n      if (process.env.NODE_ENV !== \"production\" && !elementRef.current) {\n        elementRef.current = document.getElementById(id);\n      }\n    },\n    onEntering,\n    onEntered(appearing) {\n      onEntered(appearing);\n\n      animatedOnceRef.current = true;\n    },\n    onExited,\n  });\n\n  const hideTooltip = useCallback(() => {\n    initiatedBy.current = null;\n    disableHoverMode();\n    clearVisibilityTimeout();\n    setVisible(false);\n  }, [clearVisibilityTimeout, disableHoverMode, setVisible]);\n\n  useEffect(() => {\n    if (!visible) {\n      return;\n    }\n\n    const handleKeyDown = (event: KeyboardEvent): void => {\n      if (event.key === \"Escape\") {\n        hideTooltip();\n      }\n    };\n\n    window.addEventListener(\"keydown\", handleKeyDown);\n    window.addEventListener(\"scroll\", hideTooltip, true);\n    window.addEventListener(\"touchend\", hideTooltip, true);\n    return () => {\n      window.removeEventListener(\"keydown\", handleKeyDown);\n      window.removeEventListener(\"scroll\", hideTooltip, true);\n      window.removeEventListener(\"touchend\", hideTooltip, true);\n    };\n  }, [hideTooltip, visible]);\n\n  const refocusFrame = useRef(0);\n  const pageInactive = useRef(false);\n  usePageInactive({\n    disabled,\n    onDisabledCleanup: hideTooltip,\n    onChange(active) {\n      if (active) {\n        refocusFrame.current = window.requestAnimationFrame(() => {\n          pageInactive.current = false;\n        });\n        return;\n      }\n\n      pageInactive.current = true;\n      hideTooltip();\n    },\n  });\n\n  return {\n    visible,\n    setVisible,\n    hideTooltip,\n    animatedOnce: animatedOnceRef.current,\n    tooltipProps: {\n      id: tooltipId,\n      ref,\n      dense,\n      style,\n      visible,\n      position,\n      ...callbacks,\n    },\n    elementProps: {\n      \"aria-describedby\": cnb(visible && tooltipId, describedBy) || undefined,\n      id,\n      onMouseEnter(event) {\n        onMouseEnter(event);\n        if (disabled || mode === \"touch\" || initiatedBy.current !== null) {\n          return;\n        }\n\n        initiatedBy.current = \"mouse\";\n        elementRef.current = event.currentTarget;\n        updatePosition(event.currentTarget);\n        startShowFlow(id);\n      },\n      onMouseLeave(event) {\n        onMouseLeave(event);\n        if (disabled || initiatedBy.current !== \"mouse\") {\n          return;\n        }\n\n        startHideFlow();\n        initiatedBy.current = null;\n      },\n      onBlur(event) {\n        onBlur(event);\n        if (disabled) {\n          return;\n        }\n\n        initiatedBy.current = null;\n        startHideFlow();\n      },\n      onFocus(event) {\n        onFocus(event);\n        // skip the focus events when the browser is re-focused if the user\n        // pressed alt-tab, minimized the browser, etc\n        if (\n          disabled ||\n          mode !== \"keyboard\" ||\n          initiatedBy.current !== null ||\n          pageInactive.current\n        ) {\n          pageInactive.current = false;\n          return;\n        }\n\n        initiatedBy.current = \"keyboard\";\n        elementRef.current = event.currentTarget;\n        updatePosition(event.currentTarget);\n        startShowFlow(id);\n      },\n      onTouchStart(event) {\n        onTouchStart(event);\n        if (disabled || initiatedBy.current !== null) {\n          return;\n        }\n\n        initiatedBy.current = \"touch\";\n        elementRef.current = event.currentTarget;\n        updatePosition(event.currentTarget);\n        startShowFlow(id);\n      },\n      onTouchEnd(event) {\n        onTouchEnd(event);\n        if (disabled) {\n          return;\n        }\n\n        initiatedBy.current = null;\n        startHideFlow();\n      },\n      onContextMenu(event) {\n        onContextMenu(event);\n        if (disabled || initiatedBy.current !== \"touch\") {\n          return;\n        }\n\n        event.preventDefault();\n        const selection = window.getSelection();\n        const node = selection?.anchorNode?.parentElement;\n        if (node && event.currentTarget.contains(node)) {\n          selection.empty();\n        }\n      },\n    },\n  };\n}\n"],"names":["cnb","useCallback","useEffect","useId","useRef","useHoverMode","useUserInteractionMode","useFixedPositioning","usePageInactive","parseCssLengthUnit","useTooltipHoverMode","DEFAULT_TOOLTIP_DENSE_SPACING","DEFAULT_TOOLTIP_MARGIN","DEFAULT_TOOLTIP_POSITION","DEFAULT_TOOLTIP_SPACING","DEFAULT_TOOLTIP_THRESHOLD","TOOLTIP_SPACING_VAR","useTooltipPosition","getAnchor","noop","useTooltip","options","id","propId","style","propStyle","disabled","describedBy","dense","hoverTime","leaveTime","vwMargin","vhMargin","spacing","denseSpacing","disableSwapping","disableAutoSpacing","position","determinedPosition","defaultPosition","threshold","onBlur","onFocus","onMouseEnter","onMouseLeave","onTouchStart","onTouchEnd","onContextMenu","onEnter","onEntering","onEntered","onExited","fallbackId","tooltipId","animatedOnceRef","hoverTimeoutRef","leaveTimeoutRef","enableHoverMode","disableHoverMode","startDisableTimer","clearDisableTimer","visible","setVisible","startShowFlow","startHideFlow","clearVisibilityTimeout","updatePosition","mode","elementRef","tooltipRef","initiatedBy","ref","callbacks","nodeRef","fixedTo","anchor","getFixedPositionOptions","tooltipSpacing","tooltip","current","window","getComputedStyle","getPropertyValue","currentSpacing","value","horizontal","xMargin","undefined","yMargin","appearing","process","env","NODE_ENV","document","getElementById","hideTooltip","handleKeyDown","event","key","addEventListener","removeEventListener","refocusFrame","pageInactive","onDisabledCleanup","onChange","active","requestAnimationFrame","animatedOnce","tooltipProps","elementProps","currentTarget","preventDefault","selection","getSelection","node","anchorNode","parentElement","contains","empty"],"mappings":"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"}

package/dist/tooltip/useTooltipPosition.d.ts

@@ -0,0 +1,55 @@
+import type { SimplePosition } from "../positioning/types.js";
+/**
+ * @remarks \@since 2.8.0
+ */
+export interface TooltipPositionHookOptions {
+    /**
+     * An optional controlled position to use that will disable the functionality
+     * to determine the "best" position to render the tooltip within the viewport.
+     */
+    position?: SimplePosition;
+    /**
+     * An optional position to use before the positioning calculation has
+     * occurred. This is also used to determine if the position should be
+     * horizontal vs vertical.
+     *
+     * Vertical - `"below"` or `"above"`
+     * Horizontal - `"left"` or `"right"`
+     *
+     * @defaultValue `DEFAULT_TOOLTIP_POSITION`
+     * @see {@link DEFAULT_TOOLTIP_POSITION}
+     */
+    defaultPosition?: SimplePosition;
+    /**
+     * This value should be between 0 and 1 and will be multiplied by either the
+     * viewport height or viewport width to determine the best position to render
+     * the tooltip based on available space within the viewport.
+     *
+     * You _probably_ won't ever really need to update this value.
+     *
+     * @defaultValue `DEFAULT_TOOLTIP_THRESHOLD`
+     * @see {@link DEFAULT_TOOLTIP_THRESHOLD}
+     */
+    threshold?: number;
+}
+/**
+ * @internal
+ * @remarks \@since 2.8.0
+ */
+export type UpdateTooltipPosition = (container: HTMLElement) => void;
+/**
+ * @internal
+ * @remarks \@since 2.8.0
+ */
+export type TooltipPositionHookReturnValue = [
+    SimplePosition,
+    UpdateTooltipPosition
+];
+/**
+ * A hook that's used to determine the "best" position to render the tooltip
+ * within the viewport.
+ *
+ * @internal
+ * @remarks \@since 2.8.0
+ */
+export declare function useTooltipPosition(options: TooltipPositionHookOptions): TooltipPositionHookReturnValue;

package/dist/tooltip/useTooltipPosition.js

@@ -0,0 +1,39 @@
+"use client";
+import { useCallback, useState } from "react";
+import { DEFAULT_TOOLTIP_POSITION, DEFAULT_TOOLTIP_THRESHOLD } from "./constants.js";
+import { getPosition } from "./utils.js";
+/** @internal */ const noop = ()=>{
+// do nothing
+};
+/**
+ * A hook that's used to determine the "best" position to render the tooltip
+ * within the viewport.
+ *
+ * @internal
+ * @remarks \@since 2.8.0
+ */ export function useTooltipPosition(options) {
+    const { position: determinedPosition, threshold = DEFAULT_TOOLTIP_THRESHOLD, defaultPosition = DEFAULT_TOOLTIP_POSITION } = options;
+    const [position, setPosition] = useState(defaultPosition);
+    const updatePosition = useCallback((container)=>{
+        setPosition(getPosition({
+            container,
+            threshold,
+            defaultPosition
+        }));
+    }, [
+        defaultPosition,
+        threshold
+    ]);
+    if (typeof determinedPosition !== "undefined") {
+        return [
+            determinedPosition,
+            noop
+        ];
+    }
+    return [
+        position,
+        updatePosition
+    ];
+}
+
+//# sourceMappingURL=useTooltipPosition.js.map

package/dist/tooltip/useTooltipPosition.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tooltip/useTooltipPosition.ts"],"sourcesContent":["\"use client\";\nimport { useCallback, useState } from \"react\";\nimport type { SimplePosition } from \"../positioning/types.js\";\nimport {\n  DEFAULT_TOOLTIP_POSITION,\n  DEFAULT_TOOLTIP_THRESHOLD,\n} from \"./constants.js\";\nimport { getPosition } from \"./utils.js\";\n\n/** @internal */\nconst noop = (): void => {\n  // do nothing\n};\n\n/**\n * @remarks \\@since 2.8.0\n */\nexport interface TooltipPositionHookOptions {\n  /**\n   * An optional controlled position to use that will disable the functionality\n   * to determine the \"best\" position to render the tooltip within the viewport.\n   */\n  position?: SimplePosition;\n\n  /**\n   * An optional position to use before the positioning calculation has\n   * occurred. This is also used to determine if the position should be\n   * horizontal vs vertical.\n   *\n   * Vertical - `\"below\"` or `\"above\"`\n   * Horizontal - `\"left\"` or `\"right\"`\n   *\n   * @defaultValue `DEFAULT_TOOLTIP_POSITION`\n   * @see {@link DEFAULT_TOOLTIP_POSITION}\n   */\n  defaultPosition?: SimplePosition;\n\n  /**\n   * This value should be between 0 and 1 and will be multiplied by either the\n   * viewport height or viewport width to determine the best position to render\n   * the tooltip based on available space within the viewport.\n   *\n   * You _probably_ won't ever really need to update this value.\n   *\n   * @defaultValue `DEFAULT_TOOLTIP_THRESHOLD`\n   * @see {@link DEFAULT_TOOLTIP_THRESHOLD}\n   */\n  threshold?: number;\n}\n\n/**\n * @internal\n * @remarks \\@since 2.8.0\n */\nexport type UpdateTooltipPosition = (container: HTMLElement) => void;\n\n/**\n * @internal\n * @remarks \\@since 2.8.0\n */\nexport type TooltipPositionHookReturnValue = [\n  SimplePosition,\n  UpdateTooltipPosition,\n];\n\n/**\n * A hook that's used to determine the \"best\" position to render the tooltip\n * within the viewport.\n *\n * @internal\n * @remarks \\@since 2.8.0\n */\nexport function useTooltipPosition(\n  options: TooltipPositionHookOptions\n): TooltipPositionHookReturnValue {\n  const {\n    position: determinedPosition,\n    threshold = DEFAULT_TOOLTIP_THRESHOLD,\n    defaultPosition = DEFAULT_TOOLTIP_POSITION,\n  } = options;\n\n  const [position, setPosition] = useState(defaultPosition);\n  const updatePosition = useCallback<UpdateTooltipPosition>(\n    (container) => {\n      setPosition(\n        getPosition({\n          container,\n          threshold,\n          defaultPosition,\n        })\n      );\n    },\n    [defaultPosition, threshold]\n  );\n\n  if (typeof determinedPosition !== \"undefined\") {\n    return [determinedPosition, noop];\n  }\n\n  return [position, updatePosition];\n}\n"],"names":["useCallback","useState","DEFAULT_TOOLTIP_POSITION","DEFAULT_TOOLTIP_THRESHOLD","getPosition","noop","useTooltipPosition","options","position","determinedPosition","threshold","defaultPosition","setPosition","updatePosition","container"],"mappings":"AAAA;AACA,SAASA,WAAW,EAAEC,QAAQ,QAAQ,QAAQ;AAE9C,SACEC,wBAAwB,EACxBC,yBAAyB,QACpB,iBAAiB;AACxB,SAASC,WAAW,QAAQ,aAAa;AAEzC,cAAc,GACd,MAAMC,OAAO;AACX,aAAa;AACf;AAqDA;;;;;;CAMC,GACD,OAAO,SAASC,mBACdC,OAAmC;IAEnC,MAAM,EACJC,UAAUC,kBAAkB,EAC5BC,YAAYP,yBAAyB,EACrCQ,kBAAkBT,wBAAwB,EAC3C,GAAGK;IAEJ,MAAM,CAACC,UAAUI,YAAY,GAAGX,SAASU;IACzC,MAAME,iBAAiBb,YACrB,CAACc;QACCF,YACER,YAAY;YACVU;YACAJ;YACAC;QACF;IAEJ,GACA;QAACA;QAAiBD;KAAU;IAG9B,IAAI,OAAOD,uBAAuB,aAAa;QAC7C,OAAO;YAACA;YAAoBJ;SAAK;IACnC;IAEA,OAAO;QAACG;QAAUK;KAAe;AACnC"}

package/dist/tooltip/utils.d.ts

@@ -0,0 +1,11 @@
+import type { PositionAnchor, SimplePosition } from "../positioning/types.js";
+/** @internal */
+export declare function getAnchor(position: SimplePosition): PositionAnchor;
+/** @internal */
+export interface GetPositionOptions {
+    container: HTMLElement;
+    threshold: number;
+    defaultPosition: SimplePosition;
+}
+/** @internal */
+export declare function getPosition(options: GetPositionOptions): SimplePosition;