@zag-js/tabs 0.9.1 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zag-js/tabs",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Core logic for the tabs widget implemented as a state machine",
   "keywords": [
     "js",
@@ -17,7 +17,8 @@
   "repository": "https://github.com/chakra-ui/zag/tree/main/packages/tabs",
   "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/dom-query": "0.9.1",
-    "@zag-js/dom-event": "0.9.1",
-    "@zag-js/element-rect": "0.9.1",
-    "@zag-js/tabbable": "0.9.1",
-    "@zag-js/utils": "0.9.1",
-    "@zag-js/core": "0.9.1",
-    "@zag-js/types": "0.9.1"
+    "@zag-js/anatomy": "0.10.0",
+    "@zag-js/dom-query": "0.10.0",
+    "@zag-js/dom-event": "0.10.0",
+    "@zag-js/element-rect": "0.10.0",
+    "@zag-js/tabbable": "0.10.0",
+    "@zag-js/utils": "0.10.0",
+    "@zag-js/core": "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 "./tabs.anatomy"
+export { connect } from "./tabs.connect"
+export { machine } from "./tabs.machine"
+export type { UserDefinedContext as Context, TriggerProps, ContentProps } from "./tabs.types"

package/src/tabs.anatomy.ts

@@ -0,0 +1,4 @@
+import { createAnatomy } from "@zag-js/anatomy"
+
+export const anatomy = createAnatomy("tabs").parts("root", "tablist", "trigger", "contentGroup", "content", "indicator")
+export const parts = anatomy.build()

package/src/tabs.connect.ts

@@ -0,0 +1,168 @@
+import { EventKeyMap, getEventKey } from "@zag-js/dom-event"
+import { dataAttr, isSafari } from "@zag-js/dom-query"
+import type { NormalizeProps, PropTypes } from "@zag-js/types"
+import { parts } from "./tabs.anatomy"
+import { dom } from "./tabs.dom"
+import type { ContentProps, Send, State, TriggerProps } from "./tabs.types"
+
+export function connect<T extends PropTypes>(state: State, send: Send, normalize: NormalizeProps<T>) {
+  const translations = state.context.translations
+  const isFocused = state.matches("focused")
+
+  return {
+    /**
+     * The current value of the tabs.
+     */
+    value: state.context.value,
+    /**
+     * The value of the tab that is currently focused.
+     */
+    focusedValue: state.context.focusedValue,
+    /**
+     * The previous values of the tabs in sequence of selection.
+     */
+    previousValues: Array.from(state.context.previousValues),
+    /**
+     * Sets the value of the tabs.
+     */
+    setValue(value: string) {
+      send({ type: "SET_VALUE", value })
+    },
+    /**
+     * Clears the value of the tabs.
+     */
+    clearValue() {
+      send({ type: "CLEAR_VALUE" })
+    },
+    /**
+     * Sets the indicator rect to the tab with the given id.
+     */
+    setIndicatorRect(id: string | null | undefined) {
+      send({ type: "SET_INDICATOR_RECT", id })
+    },
+
+    rootProps: normalize.element({
+      ...parts.root.attrs,
+      id: dom.getRootId(state.context),
+      "data-orientation": state.context.orientation,
+      "data-focus": dataAttr(isFocused),
+      dir: state.context.dir,
+    }),
+
+    tablistProps: normalize.element({
+      ...parts.tablist.attrs,
+      id: dom.getTablistId(state.context),
+      role: "tablist",
+      "data-focus": dataAttr(isFocused),
+      "aria-orientation": state.context.orientation,
+      "data-orientation": state.context.orientation,
+      "aria-label": translations.tablistLabel,
+      onKeyDown(event) {
+        const keyMap: EventKeyMap = {
+          ArrowDown() {
+            send("ARROW_DOWN")
+          },
+          ArrowUp() {
+            send("ARROW_UP")
+          },
+          ArrowLeft() {
+            send("ARROW_LEFT")
+          },
+          ArrowRight() {
+            send("ARROW_RIGHT")
+          },
+          Home() {
+            send("HOME")
+          },
+          End() {
+            send("END")
+          },
+          Enter() {
+            send({ type: "ENTER", value: state.context.focusedValue })
+          },
+        }
+
+        let key = getEventKey(event, state.context)
+        const exec = keyMap[key]
+
+        if (exec) {
+          event.preventDefault()
+          exec(event)
+        }
+      },
+    }),
+
+    getTriggerProps(props: TriggerProps) {
+      const { value, disabled } = props
+      const selected = state.context.value === value
+
+      return normalize.button({
+        ...parts.trigger.attrs,
+        role: "tab",
+        type: "button",
+        disabled,
+        "data-orientation": state.context.orientation,
+        "data-disabled": dataAttr(disabled),
+        "aria-disabled": disabled,
+        "data-value": value,
+        "aria-selected": selected,
+        "data-selected": dataAttr(selected),
+        "aria-controls": dom.getContentId(state.context, value),
+        "data-ownedby": dom.getTablistId(state.context),
+        id: dom.getTriggerId(state.context, value),
+        tabIndex: selected ? 0 : -1,
+        onFocus() {
+          send({ type: "TAB_FOCUS", value })
+        },
+        onBlur(event) {
+          const target = event.relatedTarget as HTMLElement | null
+          if (target?.getAttribute("role") !== "tab") {
+            send({ type: "TAB_BLUR" })
+          }
+        },
+        onClick(event) {
+          if (disabled) return
+          if (isSafari()) {
+            event.currentTarget.focus()
+          }
+          send({ type: "TAB_CLICK", value })
+        },
+      })
+    },
+
+    contentGroupProps: normalize.element({
+      ...parts.contentGroup.attrs,
+      id: dom.getContentGroupId(state.context),
+      "data-orientation": state.context.orientation,
+    }),
+
+    getContentProps({ value }: ContentProps) {
+      const selected = state.context.value === value
+      return normalize.element({
+        ...parts.content.attrs,
+        id: dom.getContentId(state.context, value),
+        tabIndex: 0,
+        "aria-labelledby": dom.getTriggerId(state.context, value),
+        role: "tabpanel",
+        "data-ownedby": dom.getTablistId(state.context),
+        hidden: !selected,
+      })
+    },
+
+    indicatorProps: normalize.element({
+      id: dom.getIndicatorId(state.context),
+      ...parts.indicator.attrs,
+      "data-orientation": state.context.orientation,
+      style: {
+        "--transition-duration": "150ms",
+        "--transition-property": "left, right, top, bottom, width, height",
+        position: "absolute",
+        willChange: "var(--transition-property)",
+        transitionProperty: "var(--transition-property)",
+        transitionDuration: state.context.canIndicatorTransition ? "var(--transition-duration)" : "0ms",
+        transitionTimingFunction: "var(--transition-timing-function)",
+        ...state.context.indicatorRect,
+      },
+    }),
+  }
+}

package/src/tabs.dom.ts

@@ -0,0 +1,59 @@
+import { createScope, itemById, nextById, prevById, queryAll } from "@zag-js/dom-query"
+import { first, last } from "@zag-js/utils"
+import type { MachineContext as Ctx } from "./tabs.types"
+
+export const dom = createScope({
+  getRootId: (ctx: Ctx) => ctx.ids?.root ?? `tabs:${ctx.id}`,
+  getTablistId: (ctx: Ctx) => ctx.ids?.tablist ?? `tabs:${ctx.id}:list`,
+  getContentId: (ctx: Ctx, id: string) => ctx.ids?.content ?? `tabs:${ctx.id}:content-${id}`,
+  getContentGroupId: (ctx: Ctx) => ctx.ids?.contentGroup ?? `tabs:${ctx.id}:content-group`,
+  getTriggerId: (ctx: Ctx, id: string) => ctx.ids?.trigger ?? `tabs:${ctx.id}:trigger-${id}`,
+  getIndicatorId: (ctx: Ctx) => ctx.ids?.indicator ?? `tabs:${ctx.id}:indicator`,
+
+  getTablistEl: (ctx: Ctx) => dom.getById(ctx, dom.getTablistId(ctx)),
+  getContentEl: (ctx: Ctx, id: string) => dom.getById(ctx, dom.getContentId(ctx, id)),
+  getTriggerEl: (ctx: Ctx, id: string) => dom.getById(ctx, dom.getTriggerId(ctx, id)),
+  getIndicatorEl: (ctx: Ctx) => dom.getById(ctx, dom.getIndicatorId(ctx)),
+
+  getElements: (ctx: Ctx) => {
+    const ownerId = CSS.escape(dom.getTablistId(ctx))
+    const selector = `[role=tab][data-ownedby='${ownerId}']:not([disabled])`
+    return queryAll(dom.getTablistEl(ctx), selector)
+  },
+
+  getFirstEl: (ctx: Ctx) => first(dom.getElements(ctx)),
+  getLastEl: (ctx: Ctx) => last(dom.getElements(ctx)),
+  getNextEl: (ctx: Ctx, id: string) => nextById(dom.getElements(ctx), dom.getTriggerId(ctx, id), ctx.loop),
+  getPrevEl: (ctx: Ctx, id: string) => prevById(dom.getElements(ctx), dom.getTriggerId(ctx, id), ctx.loop),
+  getActiveContentEl: (ctx: Ctx) => {
+    if (!ctx.value) return
+    return dom.getContentEl(ctx, ctx.value)
+  },
+  getActiveTabEl: (ctx: Ctx) => {
+    if (!ctx.value) return
+    return dom.getTriggerEl(ctx, ctx.value)
+  },
+
+  getOffsetRect: (el: HTMLElement | undefined) => {
+    return {
+      left: el?.offsetLeft ?? 0,
+      top: el?.offsetTop ?? 0,
+      width: el?.offsetWidth ?? 0,
+      height: el?.offsetHeight ?? 0,
+    }
+  },
+
+  getRectById: (ctx: Ctx, id: string) => {
+    const tab = itemById(dom.getElements(ctx), dom.getTriggerId(ctx, id))
+    return dom.resolveRect(dom.getOffsetRect(tab), ctx.orientation)
+  },
+
+  resolveRect(rect: Record<"width" | "height" | "left" | "top", number>, orientation?: "horizontal" | "vertical") {
+    const sizeProp = orientation === "vertical" ? "height" : "width"
+    const placementProp = orientation === "vertical" ? "top" : "left"
+    return {
+      [placementProp]: `${rect[placementProp]}px`,
+      [sizeProp]: `${rect[sizeProp]}px`,
+    }
+  },
+})

package/src/tabs.machine.ts

@@ -0,0 +1,256 @@
+import { createMachine, guards } from "@zag-js/core"
+import { nextTick, raf } from "@zag-js/dom-query"
+import { trackElementRect } from "@zag-js/element-rect"
+import { getFocusables } from "@zag-js/tabbable"
+import { compact } from "@zag-js/utils"
+import { dom } from "./tabs.dom"
+import type { MachineContext, MachineState, UserDefinedContext } from "./tabs.types"
+
+const { not } = guards
+
+export function machine(userContext: UserDefinedContext) {
+  const ctx = compact(userContext)
+  return createMachine<MachineContext, MachineState>(
+    {
+      initial: "idle",
+
+      context: {
+        dir: "ltr",
+        orientation: "horizontal",
+        activationMode: "automatic",
+        value: null,
+        focusedValue: null,
+        previousValues: [],
+        indicatorRect: {
+          left: "0px",
+          top: "0px",
+          width: "0px",
+          height: "0px",
+        },
+        canIndicatorTransition: false,
+        isIndicatorRendered: false,
+        loop: true,
+        translations: {},
+        ...ctx,
+      },
+
+      computed: {
+        isHorizontal: (ctx) => ctx.orientation === "horizontal",
+        isVertical: (ctx) => ctx.orientation === "vertical",
+      },
+
+      created: ["setPrevSelectedTabs"],
+
+      entry: ["checkRenderedElements", "syncIndicatorRect", "setContentTabIndex"],
+
+      exit: ["cleanupObserver"],
+
+      watch: {
+        focusedValue: "invokeOnFocus",
+        value: [
+          "enableIndicatorTransition",
+          "invokeOnChange",
+          "setPrevSelectedTabs",
+          "syncIndicatorRect",
+          "setContentTabIndex",
+        ],
+        dir: ["syncIndicatorRect"],
+        orientation: ["syncIndicatorRect"],
+      },
+
+      on: {
+        SET_VALUE: {
+          actions: "setValue",
+        },
+        CLEAR_VALUE: {
+          actions: "clearValue",
+        },
+        SET_INDICATOR_RECT: {
+          actions: "setIndicatorRect",
+        },
+      },
+
+      states: {
+        idle: {
+          on: {
+            TAB_FOCUS: [
+              {
+                guard: "selectOnFocus",
+                target: "focused",
+                actions: ["setFocusedValue", "setValue"],
+              },
+              {
+                target: "focused",
+                actions: "setFocusedValue",
+              },
+            ],
+            TAB_CLICK: {
+              target: "focused",
+              actions: ["setFocusedValue", "setValue"],
+            },
+          },
+        },
+        focused: {
+          on: {
+            TAB_CLICK: {
+              target: "focused",
+              actions: ["setFocusedValue", "setValue"],
+            },
+            ARROW_LEFT: {
+              guard: "isHorizontal",
+              actions: "focusPrevTab",
+            },
+            ARROW_RIGHT: {
+              guard: "isHorizontal",
+              actions: "focusNextTab",
+            },
+            ARROW_UP: {
+              guard: "isVertical",
+              actions: "focusPrevTab",
+            },
+            ARROW_DOWN: {
+              guard: "isVertical",
+              actions: "focusNextTab",
+            },
+            HOME: {
+              actions: "focusFirstTab",
+            },
+            END: {
+              actions: "focusLastTab",
+            },
+            ENTER: {
+              guard: not("selectOnFocus"),
+              actions: "setValue",
+            },
+            TAB_FOCUS: [
+              {
+                guard: "selectOnFocus",
+                actions: ["setFocusedValue", "setValue"],
+              },
+              { actions: "setFocusedValue" },
+            ],
+            TAB_BLUR: {
+              target: "idle",
+              actions: "clearFocusedValue",
+            },
+          },
+        },
+      },
+    },
+    {
+      guards: {
+        isVertical: (ctx) => ctx.isVertical,
+        isHorizontal: (ctx) => ctx.isHorizontal,
+        selectOnFocus: (ctx) => ctx.activationMode === "automatic",
+      },
+
+      actions: {
+        setFocusedValue(ctx, evt) {
+          ctx.focusedValue = evt.value
+        },
+        clearFocusedValue(ctx) {
+          ctx.focusedValue = null
+        },
+        setValue(ctx, evt) {
+          ctx.value = evt.value
+        },
+        clearValue(ctx) {
+          ctx.value = null
+        },
+        focusFirstTab(ctx) {
+          raf(() => dom.getFirstEl(ctx)?.focus())
+        },
+        focusLastTab(ctx) {
+          raf(() => dom.getLastEl(ctx)?.focus())
+        },
+        focusNextTab(ctx) {
+          if (!ctx.focusedValue) return
+          const next = dom.getNextEl(ctx, ctx.focusedValue)
+          raf(() => next?.focus())
+        },
+        focusPrevTab(ctx) {
+          if (!ctx.focusedValue) return
+          const prev = dom.getPrevEl(ctx, ctx.focusedValue)
+          raf(() => prev?.focus())
+        },
+        checkRenderedElements(ctx) {
+          ctx.isIndicatorRendered = !!dom.getIndicatorEl(ctx)
+        },
+        invokeOnChange(ctx) {
+          ctx.onChange?.({ value: ctx.value })
+        },
+        invokeOnFocus(ctx) {
+          ctx.onFocus?.({ value: ctx.focusedValue })
+        },
+        setPrevSelectedTabs(ctx) {
+          if (ctx.value != null) {
+            ctx.previousValues = pushUnique(ctx.previousValues, ctx.value)
+          }
+        },
+        // if tab panel contains focusable elements, remove the tabindex attribute
+        setContentTabIndex(ctx) {
+          raf(() => {
+            const panel = dom.getActiveContentEl(ctx)
+            if (!panel) return
+            const focusables = getFocusables(panel)
+            if (focusables.length > 0) {
+              panel.removeAttribute("tabindex")
+            } else {
+              panel.setAttribute("tabindex", "0")
+            }
+          })
+        },
+        cleanupObserver(ctx) {
+          ctx.indicatorCleanup?.()
+        },
+        enableIndicatorTransition(ctx) {
+          ctx.canIndicatorTransition = true
+        },
+        setIndicatorRect(ctx, evt) {
+          const value = evt.id ?? ctx.value
+          if (!ctx.isIndicatorRendered || !value) return
+
+          const tabEl = dom.getTriggerEl(ctx, value)
+          if (!tabEl) return
+
+          ctx.indicatorRect = dom.getRectById(ctx, value)
+          nextTick(() => {
+            ctx.canIndicatorTransition = false
+          })
+        },
+        syncIndicatorRect(ctx) {
+          ctx.indicatorCleanup?.()
+
+          const value = ctx.value
+          if (!ctx.isIndicatorRendered || !value) return
+
+          const tabEl = dom.getActiveTabEl(ctx)
+          if (!tabEl) return
+
+          ctx.indicatorCleanup = trackElementRect(tabEl, {
+            getRect(el) {
+              return dom.getOffsetRect(el)
+            },
+            onChange(rect) {
+              ctx.indicatorRect = dom.resolveRect(rect, ctx.orientation)
+              nextTick(() => {
+                ctx.canIndicatorTransition = false
+              })
+            },
+          })
+        },
+      },
+    },
+  )
+}
+
+// function to push value array and remove previous instances of value
+function pushUnique(arr: string[], value: any) {
+  const newArr = Array.from(arr).slice()
+  const index = newArr.indexOf(value)
+  if (index > -1) {
+    newArr.splice(index, 1)
+  }
+  newArr.push(value)
+  return newArr
+}

package/src/tabs.types.ts

@@ -0,0 +1,130 @@
+import type { StateMachine as S } from "@zag-js/core"
+import type { CommonProperties, Context, DirectionProperty, RequiredBy } from "@zag-js/types"
+
+type IntlTranslations = {
+  tablistLabel?: string
+}
+
+type ElementIds = Partial<{
+  root: string
+  trigger: string
+  tablist: string
+  contentGroup: string
+  content: string
+  indicator: string
+}>
+
+export type TriggerProps = {
+  value: string
+  disabled?: boolean
+}
+
+export type ContentProps = {
+  value: string
+}
+
+type PublicContext = DirectionProperty &
+  CommonProperties & {
+    /**
+     * The ids of the elements in the tabs. Useful for composition.
+     */
+    ids?: ElementIds
+    /**
+     * Specifies the localized strings that identifies the accessibility elements and their states
+     */
+    translations: IntlTranslations
+    /**
+     * Whether the keyboard navigation will loop from last tab to first, and vice versa.
+     * @default true
+     */
+    loop: boolean
+    /**
+     * The selected tab id
+     */
+    value: string | null
+    /**
+     * The orientation of the tabs. Can be `horizontal` or `vertical`
+     * - `horizontal`: only left and right arrow key navigation will work.
+     * - `vertical`: only up and down arrow key navigation will work.
+     *
+     * @default "horizontal"
+     */
+    orientation?: "horizontal" | "vertical"
+    /**
+     * The activation mode of the tabs. Can be `manual` or `automatic`
+     * - `manual`: Tabs are activated when clicked or press `enter` key.
+     * - `automatic`: Tabs are activated when receiving focus
+     * @default "automatic"
+     */
+    activationMode?: "manual" | "automatic"
+    /**
+     * Callback to be called when the selected/active tab changes
+     */
+    onChange?: (details: { value: string | null }) => void
+    /**
+     * Callback to be called when the focused tab changes
+     */
+    onFocus?: (details: { value: string | null }) => void
+    /**
+     * Callback to be called when a tab's close button is clicked
+     */
+    onDelete?: (details: { value: string }) => void
+  }
+
+export type UserDefinedContext = RequiredBy<PublicContext, "id">
+
+type ComputedContext = Readonly<{
+  /**
+   * @computed
+   * Whether the tab is in the horizontal orientation
+   */
+  isHorizontal: boolean
+  /**
+   * @computed
+   * Whether the tab is in the vertical orientation
+   */
+  isVertical: boolean
+}>
+
+type PrivateContext = Context<{
+  /**
+   * @internal
+   * The focused tab id
+   */
+  focusedValue: string | null
+  /**
+   * @internal
+   * Whether the indicator is rendered.
+   */
+  isIndicatorRendered: boolean
+  /**
+   * @internal
+   * The active tab indicator's dom rect
+   */
+  indicatorRect?: Partial<{ left: string; top: string; width: string; height: string }>
+  /**
+   * @internal
+   * Whether the active tab indicator's rect can transition
+   */
+  canIndicatorTransition?: boolean
+  /**
+   * @internal
+   * The previously selected tab ids. This is useful for performance optimization
+   */
+  previousValues: string[]
+  /**
+   * @internal
+   * Function to clean up the observer for the active tab's rect
+   */
+  indicatorCleanup?: VoidFunction | null
+}>
+
+export type MachineContext = PublicContext & ComputedContext & PrivateContext
+
+export type MachineState = {
+  value: "idle" | "focused"
+}
+
+export type State = S.State<MachineContext, MachineState>
+
+export type Send = S.Send<S.AnyEventObject>