@zag-js/tooltip 0.9.1 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zag-js/tooltip",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Core logic for the tooltip widget implemented as a state machine",
   "keywords": [
     "js",
@@ -17,7 +17,8 @@
   "repository": "https://github.com/chakra-ui/zag/tree/main/packages/tooltip",
   "sideEffects": false,
   "files": [
-    "dist/**/*"
+    "dist",
+    "src"
   ],
   "publishConfig": {
     "access": "public"
@@ -26,14 +27,14 @@
     "url": "https://github.com/chakra-ui/zag/issues"
   },
   "dependencies": {
-    "@zag-js/anatomy": "0.9.1",
-    "@zag-js/core": "0.9.1",
-    "@zag-js/popper": "0.9.1",
-    "@zag-js/dom-query": "0.9.1",
-    "@zag-js/dom-event": "0.9.1",
-    "@zag-js/utils": "0.9.1",
-    "@zag-js/visually-hidden": "0.9.1",
-    "@zag-js/types": "0.9.1"
+    "@zag-js/anatomy": "0.10.0",
+    "@zag-js/core": "0.10.0",
+    "@zag-js/popper": "0.10.0",
+    "@zag-js/dom-query": "0.10.0",
+    "@zag-js/dom-event": "0.10.0",
+    "@zag-js/utils": "0.10.0",
+    "@zag-js/visually-hidden": "0.10.0",
+    "@zag-js/types": "0.10.0"
   },
   "devDependencies": {
     "clean-package": "2.2.0"

package/src/index.ts

@@ -0,0 +1,4 @@
+export { anatomy } from "./tooltip.anatomy"
+export { connect } from "./tooltip.connect"
+export { machine } from "./tooltip.machine"
+export type { UserDefinedContext as Context } from "./tooltip.types"

package/src/tooltip.anatomy.ts

@@ -0,0 +1,4 @@
+import { createAnatomy } from "@zag-js/anatomy"
+
+export const anatomy = createAnatomy("tooltip").parts("trigger", "arrow", "arrowTip", "positioner", "content", "label")
+export const parts = anatomy.build()

package/src/tooltip.connect.ts

@@ -0,0 +1,136 @@
+import { dataAttr } from "@zag-js/dom-query"
+import { getPlacementStyles, PositioningOptions } from "@zag-js/popper"
+import type { NormalizeProps, PropTypes } from "@zag-js/types"
+import { visuallyHiddenStyle } from "@zag-js/visually-hidden"
+import { parts } from "./tooltip.anatomy"
+import { dom } from "./tooltip.dom"
+import { store } from "./tooltip.store"
+import type { Send, State } from "./tooltip.types"
+
+export function connect<T extends PropTypes>(state: State, send: Send, normalize: NormalizeProps<T>) {
+  const id = state.context.id
+  const hasAriaLabel = state.context.hasAriaLabel
+
+  const isOpen = state.hasTag("open")
+
+  const triggerId = dom.getTriggerId(state.context)
+  const contentId = dom.getContentId(state.context)
+
+  const isDisabled = state.context.disabled
+
+  const popperStyles = getPlacementStyles({
+    placement: state.context.currentPlacement,
+  })
+
+  return {
+    /**
+     * Whether the tooltip is open.
+     */
+    isOpen,
+    /**
+     * Function to open the tooltip.
+     */
+    open() {
+      send("OPEN")
+    },
+    /**
+     * Function to close the tooltip.
+     */
+    close() {
+      send("CLOSE")
+    },
+    /**
+     * Returns the animation state of the tooltip.
+     */
+    getAnimationState() {
+      return {
+        enter: store.prevId === null && id === store.id,
+        exit: store.id === null,
+      }
+    },
+    /**
+     * Function to reposition the popover
+     */
+    setPositioning(options: Partial<PositioningOptions> = {}) {
+      send({ type: "SET_POSITIONING", options })
+    },
+
+    triggerProps: normalize.button({
+      ...parts.trigger.attrs,
+      id: triggerId,
+      "data-expanded": dataAttr(isOpen),
+      "aria-describedby": isOpen ? contentId : undefined,
+      onClick() {
+        send("CLICK")
+      },
+      onFocus() {
+        send("FOCUS")
+      },
+      onBlur() {
+        if (id === store.id) {
+          send("BLUR")
+        }
+      },
+      onPointerDown() {
+        if (isDisabled) return
+        if (id === store.id) {
+          send("POINTER_DOWN")
+        }
+      },
+      onPointerMove() {
+        if (isDisabled) return
+        send("POINTER_ENTER")
+      },
+      onPointerLeave() {
+        if (isDisabled) return
+        send("POINTER_LEAVE")
+      },
+      onPointerCancel() {
+        if (isDisabled) return
+        send("POINTER_LEAVE")
+      },
+    }),
+
+    arrowProps: normalize.element({
+      id: dom.getArrowId(state.context),
+      ...parts.arrow.attrs,
+      style: popperStyles.arrow,
+    }),
+
+    arrowTipProps: normalize.element({
+      ...parts.arrowTip.attrs,
+      style: popperStyles.arrowTip,
+    }),
+
+    positionerProps: normalize.element({
+      id: dom.getPositionerId(state.context),
+      ...parts.positioner.attrs,
+      style: popperStyles.floating,
+    }),
+
+    contentProps: normalize.element({
+      ...parts.content.attrs,
+      hidden: !isOpen,
+      role: hasAriaLabel ? undefined : "tooltip",
+      id: hasAriaLabel ? undefined : contentId,
+      "data-placement": state.context.currentPlacement,
+      onPointerEnter() {
+        send("TOOLTIP_POINTER_ENTER")
+      },
+      onPointerLeave() {
+        send("TOOLTIP_POINTER_LEAVE")
+      },
+      style: {
+        pointerEvents: state.context.interactive ? "auto" : "none",
+      },
+    }),
+
+    labelProps: normalize.element({
+      ...parts.label.attrs,
+      id: contentId,
+      role: "tooltip",
+      style: visuallyHiddenStyle,
+      children: state.context["aria-label"],
+    }),
+  }
+}

package/src/tooltip.dom.ts

@@ -0,0 +1,15 @@
+import { createScope, getScrollParent } from "@zag-js/dom-query"
+import type { MachineContext as Ctx } from "./tooltip.types"
+
+export const dom = createScope({
+  getTriggerId: (ctx: Ctx) => ctx.ids?.trigger ?? `tooltip:${ctx.id}:trigger`,
+  getContentId: (ctx: Ctx) => ctx.ids?.content ?? `tooltip:${ctx.id}:content`,
+  getArrowId: (ctx: Ctx) => ctx.ids?.arrow ?? `tooltip:${ctx.id}:arrow`,
+  getPositionerId: (ctx: Ctx) => ctx.ids?.positioner ?? `tooltip:${ctx.id}:popper`,
+
+  getTriggerEl: (ctx: Ctx) => dom.getById(ctx, dom.getTriggerId(ctx)),
+  getContentEl: (ctx: Ctx) => dom.getById(ctx, dom.getContentId(ctx)),
+  getPositionerEl: (ctx: Ctx) => dom.getById(ctx, dom.getPositionerId(ctx)),
+  getArrowEl: (ctx: Ctx) => dom.getById(ctx, dom.getArrowId(ctx)),
+  getScrollParent: (ctx: Ctx) => getScrollParent(dom.getTriggerEl(ctx)!),
+})

package/src/tooltip.machine.ts

@@ -0,0 +1,238 @@
+import { createMachine, subscribe } from "@zag-js/core"
+import { addDomEvent } from "@zag-js/dom-event"
+import { getScrollParents, isHTMLElement, isSafari } from "@zag-js/dom-query"
+import { getPlacement } from "@zag-js/popper"
+import { compact } from "@zag-js/utils"
+import { dom } from "./tooltip.dom"
+import { store } from "./tooltip.store"
+import type { MachineContext, MachineState, UserDefinedContext } from "./tooltip.types"
+
+export function machine(userContext: UserDefinedContext) {
+  const ctx = compact(userContext)
+  return createMachine<MachineContext, MachineState>(
+    {
+      id: "tooltip",
+      initial: "closed",
+
+      context: {
+        openDelay: 1000,
+        closeDelay: 500,
+        closeOnPointerDown: true,
+        closeOnEsc: true,
+        interactive: true,
+        currentPlacement: undefined,
+        ...ctx,
+        positioning: {
+          placement: "bottom",
+          ...ctx.positioning,
+        },
+      },
+
+      computed: {
+        hasAriaLabel: (ctx) => !!ctx["aria-label"],
+      },
+
+      watch: {
+        disabled: ["closeIfDisabled"],
+        open: ["toggleVisibility"],
+      },
+
+      on: {
+        OPEN: "open",
+        CLOSE: "closed",
+      },
+
+      states: {
+        closed: {
+          tags: ["closed"],
+          entry: ["clearGlobalId", "invokeOnClose"],
+          on: {
+            FOCUS: "open",
+            POINTER_ENTER: [
+              {
+                guard: "noVisibleTooltip",
+                target: "opening",
+              },
+              { target: "open" },
+            ],
+          },
+        },
+
+        opening: {
+          tags: ["closed"],
+          activities: ["trackScroll", "trackPointerlockChange"],
+          after: {
+            OPEN_DELAY: "open",
+          },
+          on: {
+            POINTER_LEAVE: "closed",
+            BLUR: "closed",
+            SCROLL: "closed",
+            POINTER_LOCK_CHANGE: "closed",
+            POINTER_DOWN: {
+              guard: "closeOnPointerDown",
+              target: "closed",
+            },
+          },
+        },
+
+        open: {
+          tags: ["open"],
+          activities: [
+            "trackEscapeKey",
+            "trackDisabledTriggerOnSafari",
+            "trackScroll",
+            "trackPointerlockChange",
+            "trackPositioning",
+          ],
+          entry: ["setGlobalId", "invokeOnOpen"],
+          on: {
+            POINTER_LEAVE: [
+              {
+                guard: "isVisible",
+                target: "closing",
+              },
+              { target: "closed" },
+            ],
+            BLUR: "closed",
+            ESCAPE: "closed",
+            SCROLL: "closed",
+            POINTER_LOCK_CHANGE: "closed",
+            TOOLTIP_POINTER_LEAVE: {
+              guard: "isInteractive",
+              target: "closing",
+            },
+            POINTER_DOWN: {
+              guard: "closeOnPointerDown",
+              target: "closed",
+            },
+            CLICK: "closed",
+            SET_POSITIONING: {
+              actions: "setPositioning",
+            },
+          },
+        },
+
+        closing: {
+          tags: ["open"],
+          activities: ["trackStore", "trackPositioning"],
+          after: {
+            CLOSE_DELAY: "closed",
+          },
+          on: {
+            FORCE_CLOSE: "closed",
+            POINTER_ENTER: "open",
+            TOOLTIP_POINTER_ENTER: {
+              guard: "isInteractive",
+              target: "open",
+            },
+          },
+        },
+      },
+    },
+    {
+      activities: {
+        trackPositioning(ctx) {
+          ctx.currentPlacement = ctx.positioning.placement
+          const getPositionerEl = () => dom.getPositionerEl(ctx)
+          return getPlacement(dom.getTriggerEl(ctx), getPositionerEl, {
+            ...ctx.positioning,
+            defer: true,
+            onComplete(data) {
+              ctx.currentPlacement = data.placement
+            },
+            onCleanup() {
+              ctx.currentPlacement = undefined
+            },
+          })
+        },
+        trackPointerlockChange(ctx, _evt, { send }) {
+          const onChange = () => send("POINTER_LOCK_CHANGE")
+          return addDomEvent(dom.getDoc(ctx), "pointerlockchange", onChange, false)
+        },
+        trackScroll(ctx, _evt, { send }) {
+          const trigger = dom.getTriggerEl(ctx)
+          if (!trigger) return
+          const cleanups = getScrollParents(trigger).map((el) => {
+            const opts = { passive: true, capture: true } as const
+            return addDomEvent(el, "scroll", () => send("SCROLL"), opts)
+          })
+          return () => {
+            cleanups.forEach((fn) => fn?.())
+          }
+        },
+        trackStore(ctx, _evt, { send }) {
+          return subscribe(store, () => {
+            if (store.id !== ctx.id) {
+              send("FORCE_CLOSE")
+            }
+          })
+        },
+        trackDisabledTriggerOnSafari(ctx, _evt, { send }) {
+          if (!isSafari()) return
+          const doc = dom.getDoc(ctx)
+          return addDomEvent(doc, "pointermove", (event) => {
+            const selector = "[data-part=trigger][data-expanded]"
+            if (isHTMLElement(event.target) && event.target.closest(selector)) return
+            send("POINTER_LEAVE")
+          })
+        },
+        trackEscapeKey(ctx, _evt, { send }) {
+          if (!ctx.closeOnEsc) return
+          const doc = dom.getDoc(ctx)
+          return addDomEvent(doc, "keydown", (event) => {
+            if (event.key === "Escape") {
+              send("ESCAPE")
+            }
+          })
+        },
+      },
+      actions: {
+        setGlobalId(ctx) {
+          store.setId(ctx.id)
+        },
+        clearGlobalId(ctx) {
+          if (ctx.id === store.id) {
+            store.setId(null)
+          }
+        },
+        invokeOnOpen(ctx, evt) {
+          const omit = ["TOOLTIP_POINTER_ENTER", "POINTER_ENTER"]
+          if (!omit.includes(evt.type)) {
+            ctx.onOpen?.()
+          }
+        },
+        invokeOnClose(ctx) {
+          ctx.onClose?.()
+        },
+        closeIfDisabled(ctx, _evt, { send }) {
+          if (ctx.disabled) {
+            send("CLOSE")
+          }
+        },
+        setPositioning(ctx, evt) {
+          const getPositionerEl = () => dom.getPositionerEl(ctx)
+          getPlacement(dom.getTriggerEl(ctx), getPositionerEl, {
+            ...ctx.positioning,
+            ...evt.options,
+            defer: true,
+            listeners: false,
+          })
+        },
+        toggleVisibility(ctx, _evt, { send }) {
+          send({ type: ctx.open ? "OPEN" : "CLOSE", src: "controlled" })
+        },
+      },
+      guards: {
+        closeOnPointerDown: (ctx) => ctx.closeOnPointerDown,
+        noVisibleTooltip: () => store.id === null,
+        isVisible: (ctx) => ctx.id === store.id,
+        isInteractive: (ctx) => ctx.interactive,
+      },
+      delays: {
+        OPEN_DELAY: (ctx) => ctx.openDelay,
+        CLOSE_DELAY: (ctx) => ctx.closeDelay,
+      },
+    },
+  )
+}

package/src/tooltip.store.ts

@@ -0,0 +1,18 @@
+import { proxy } from "@zag-js/core"
+
+type Id = string | null
+
+type Store = {
+  id: Id
+  prevId: Id
+  setId: (val: Id) => void
+}
+
+export const store = proxy<Store>({
+  id: null,
+  prevId: null,
+  setId(val) {
+    this.prevId = this.id
+    this.id = val
+  },
+})

package/src/tooltip.types.ts

@@ -0,0 +1,95 @@
+import type { StateMachine as S } from "@zag-js/core"
+import type { Placement, PositioningOptions } from "@zag-js/popper"
+import type { CommonProperties, RequiredBy, RootProperties } from "@zag-js/types"
+
+type ElementIds = Partial<{
+  trigger: string
+  content: string
+  arrow: string
+  positioner: string
+}>
+
+type PublicContext = CommonProperties & {
+  /**
+   * The ids of the elements in the tooltip. Useful for composition.
+   */
+  ids?: ElementIds
+  /**
+   * The `id` of the tooltip.
+   */
+  id: string
+  /**
+   * The open delay of the tooltip.
+   */
+  openDelay: number
+  /**
+   * The close delay of the tooltip.
+   */
+  closeDelay: number
+  /**
+   * Whether to close the tooltip on pointerdown.
+   */
+  closeOnPointerDown: boolean
+  /**
+   * Whether to close the tooltip when the Escape key is pressed.
+   */
+  closeOnEsc?: boolean
+  /**
+   * Whether the tooltip's content is interactive.
+   * In this mode, the tooltip will remain open when user hovers over the content.
+   * @see https://www.w3.org/TR/WCAG21/#content-on-hover-or-focus
+   */
+  interactive: boolean
+  /**
+   * Function called when the tooltip is opened.
+   */
+  onOpen?: VoidFunction
+  /**
+   * Function called when the tooltip is closed.
+   */
+  onClose?: VoidFunction
+  /**
+   * Custom label for the tooltip.
+   */
+  "aria-label"?: string
+  /**
+   * The user provided options used to position the popover content
+   */
+  positioning: PositioningOptions
+  /**
+   * Whether the tooltip is disabled
+   */
+  disabled?: boolean
+  /**
+   * Whether the tooltip is open
+   */
+  open?: boolean
+}
+
+export type UserDefinedContext = RequiredBy<PublicContext, "id">
+
+type ComputedContext = Readonly<{
+  /**
+   * @computed Whether an `aria-label` is set.
+   */
+  readonly hasAriaLabel: boolean
+}>
+
+type PrivateContext = RootProperties & {
+  /**
+   * @internal
+   * The computed placement of the tooltip.
+   */
+  currentPlacement?: Placement
+}
+
+export type MachineContext = PublicContext & ComputedContext & PrivateContext
+
+export type MachineState = {
+  value: "opening" | "open" | "closing" | "closed"
+  tags: "open" | "closed"
+}
+
+export type State = S.State<MachineContext, MachineState>
+
+export type Send = S.Send<S.AnyEventObject>