@zag-js/radio-group 0.9.2 → 0.10.1

package/package.json

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

package/src/index.ts

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

package/src/radio-group.anatomy.ts

@@ -0,0 +1,12 @@
+import { createAnatomy } from "@zag-js/anatomy"
+
+export const anatomy = createAnatomy("radio-group").parts(
+  "root",
+  "label",
+  "radio",
+  "radioLabel",
+  "radioControl",
+  "radioInput",
+  "indicator",
+)
+export const parts = anatomy.build()

package/src/radio-group.connect.ts

@@ -0,0 +1,224 @@
+import { ariaAttr, dataAttr } from "@zag-js/dom-query"
+import type { NormalizeProps, PropTypes } from "@zag-js/types"
+import { visuallyHiddenStyle } from "@zag-js/visually-hidden"
+import { parts } from "./radio-group.anatomy"
+import { dom } from "./radio-group.dom"
+import type { InputProps, RadioProps, Send, State } from "./radio-group.types"
+
+export function connect<T extends PropTypes>(state: State, send: Send, normalize: NormalizeProps<T>) {
+  const isGroupDisabled = state.context.disabled
+  const isGroupReadOnly = state.context.readOnly
+
+  function getRadioState<T extends RadioProps>(props: T) {
+    const radioState = {
+      isReadOnly: props.readOnly || isGroupReadOnly,
+      isInvalid: props.invalid,
+      isDisabled: props.disabled || isGroupDisabled,
+      isChecked: state.context.value === props.value,
+      isFocused: state.context.focusedId === props.value,
+      isHovered: state.context.hoveredId === props.value,
+      isActive: state.context.activeId === props.value,
+    }
+    return {
+      ...radioState,
+      isInteractive: !(radioState.isReadOnly || radioState.isDisabled),
+    }
+  }
+
+  function getRadioDataAttrs<T extends RadioProps>(props: T) {
+    const radioState = getRadioState(props)
+    return {
+      "data-focus": dataAttr(radioState.isFocused),
+      "data-disabled": dataAttr(radioState.isDisabled),
+      "data-checked": dataAttr(radioState.isChecked),
+      "data-hover": dataAttr(radioState.isHovered),
+      "data-invalid": dataAttr(radioState.isInvalid),
+      "data-readonly": dataAttr(radioState.isReadOnly),
+    }
+  }
+
+  const focus = () => {
+    const firstEnabledAndCheckedInput = dom.getFirstEnabledAndCheckedInputEl(state.context)
+
+    if (firstEnabledAndCheckedInput) {
+      firstEnabledAndCheckedInput.focus()
+      return
+    }
+
+    const firstEnabledInput = dom.getFirstEnabledInputEl(state.context)
+    firstEnabledInput?.focus()
+  }
+
+  return {
+    /**
+     * The current value of the radio group
+     */
+    value: state.context.value,
+    /**
+     * Function to set the value of the radio group
+     */
+    setValue(value: string) {
+      send({ type: "SET_VALUE", value, manual: true })
+    },
+    /**
+     * Function to clear the value of the radio group
+     */
+    clearValue() {
+      send({ type: "SET_VALUE", value: null, manual: true })
+    },
+    /**
+     * Function to focus the radio group
+     */
+    focus,
+    /**
+     * Function to blur the currently focused radio input in the radio group
+     */
+    blur() {
+      const focusedElement = dom.getActiveElement(state.context)
+      const inputEls = dom.getInputEls(state.context)
+      const radioInputIsFocused = inputEls.some((el) => el === focusedElement)
+      if (radioInputIsFocused) focusedElement?.blur()
+    },
+    /**
+     * Returns the state details of a radio input
+     */
+    getRadioState,
+
+    rootProps: normalize.element({
+      ...parts.root.attrs,
+      role: "radiogroup",
+      id: dom.getRootId(state.context),
+      "aria-labelledby": dom.getLabelId(state.context),
+      "data-orientation": state.context.orientation,
+      "aria-orientation": state.context.orientation,
+      dir: state.context.dir,
+    }),
+
+    labelProps: normalize.element({
+      ...parts.label.attrs,
+      id: dom.getLabelId(state.context),
+      onClick: focus,
+    }),
+
+    getRadioProps(props: RadioProps) {
+      const rootState = getRadioState(props)
+
+      return normalize.label({
+        ...parts.radio.attrs,
+        id: dom.getRadioId(state.context, props.value),
+        htmlFor: dom.getRadioInputId(state.context, props.value),
+        ...getRadioDataAttrs(props),
+
+        onPointerMove() {
+          if (!rootState.isInteractive) return
+          send({ type: "SET_HOVERED", value: props.value, hovered: true })
+        },
+        onPointerLeave() {
+          if (!rootState.isInteractive) return
+          send({ type: "SET_HOVERED", value: null })
+        },
+        onPointerDown(event) {
+          if (!rootState.isInteractive) return
+          // On pointerdown, the input blurs and returns focus to the `body`,
+          // we need to prevent this.
+          if (rootState.isFocused && event.pointerType === "mouse") {
+            event.preventDefault()
+          }
+          send({ type: "SET_ACTIVE", value: props.value, active: true })
+        },
+        onPointerUp() {
+          if (!rootState.isInteractive) return
+          send({ type: "SET_ACTIVE", value: null })
+        },
+      })
+    },
+
+    getRadioLabelProps(props: RadioProps) {
+      return normalize.element({
+        ...parts.radioLabel.attrs,
+        id: dom.getRadioLabelId(state.context, props.value),
+        ...getRadioDataAttrs(props),
+      })
+    },
+
+    getRadioControlProps(props: RadioProps) {
+      const controlState = getRadioState(props)
+
+      return normalize.element({
+        ...parts.radioControl.attrs,
+        id: dom.getRadioControlId(state.context, props.value),
+        "data-active": dataAttr(controlState.isActive),
+        "aria-hidden": true,
+        ...getRadioDataAttrs(props),
+      })
+    },
+
+    getRadioInputProps(props: InputProps) {
+      const inputState = getRadioState(props)
+
+      const isRequired = props.required
+      const trulyDisabled = inputState.isDisabled && !props.focusable
+
+      return normalize.input({
+        ...parts.radioInput.attrs,
+        "data-ownedby": dom.getRootId(state.context),
+        id: dom.getRadioInputId(state.context, props.value),
+        type: "radio",
+        name: state.context.name || state.context.id,
+        form: state.context.form,
+        value: props.value,
+        onChange(event) {
+          if (inputState.isReadOnly || inputState.isDisabled) {
+            return
+          }
+          if (event.target.checked) {
+            send({ type: "SET_VALUE", value: props.value })
+          }
+        },
+        onBlur() {
+          send({ type: "SET_FOCUSED", value: null })
+        },
+        onFocus() {
+          send({ type: "SET_FOCUSED", value: props.value, focused: true })
+        },
+        onKeyDown(event) {
+          if (event.key === " ") {
+            send({ type: "SET_ACTIVE", value: props.value, active: true })
+          }
+        },
+        onKeyUp(event) {
+          if (event.key === " ") {
+            send({ type: "SET_ACTIVE", value: null })
+          }
+        },
+        disabled: trulyDisabled,
+        required: isRequired,
+        defaultChecked: inputState.isChecked,
+        "data-disabled": dataAttr(inputState.isDisabled),
+        "aria-required": ariaAttr(isRequired),
+        "aria-invalid": ariaAttr(inputState.isInvalid),
+        readOnly: inputState.isReadOnly,
+        "data-readonly": dataAttr(inputState.isReadOnly),
+        "aria-disabled": ariaAttr(trulyDisabled),
+        "aria-checked": ariaAttr(inputState.isChecked),
+        style: visuallyHiddenStyle,
+      })
+    },
+
+    indicatorProps: normalize.element({
+      id: dom.getIndicatorId(state.context),
+      ...parts.indicator.attrs,
+      "data-orientation": state.context.orientation,
+      style: {
+        "--transition-duration": "150ms",
+        "--transition-property": "left, top, 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/radio-group.dom.ts

@@ -0,0 +1,57 @@
+import { createScope, queryAll } from "@zag-js/dom-query"
+import type { MachineContext as Ctx } from "./radio-group.types"
+
+export const dom = createScope({
+  getRootId: (ctx: Ctx) => ctx.ids?.root ?? `radio-group:${ctx.id}`,
+  getLabelId: (ctx: Ctx) => ctx.ids?.label ?? `radio-group:${ctx.id}:label`,
+  getRadioId: (ctx: Ctx, value: string) => ctx.ids?.radio?.(value) ?? `radio-group:${ctx.id}:radio:${value}`,
+  getRadioInputId: (ctx: Ctx, value: string) =>
+    ctx.ids?.radioInput?.(value) ?? `radio-group:${ctx.id}:radio:input:${value}`,
+  getRadioControlId: (ctx: Ctx, value: string) =>
+    ctx.ids?.radioControl?.(value) ?? `radio-group:${ctx.id}:radio:control:${value}`,
+  getRadioLabelId: (ctx: Ctx, value: string) =>
+    ctx.ids?.radioLabel?.(value) ?? `radio-group:${ctx.id}:radio:label:${value}`,
+  getIndicatorId: (ctx: Ctx) => ctx.ids?.indicator ?? `tabs:${ctx.id}:indicator`,
+
+  getRootEl: (ctx: Ctx) => dom.getById(ctx, dom.getRootId(ctx)),
+  getRadioInputEl: (ctx: Ctx, value: string) => dom.getById<HTMLInputElement>(ctx, dom.getRadioInputId(ctx, value)),
+  getIndicatorEl: (ctx: Ctx) => dom.getById(ctx, dom.getIndicatorId(ctx)),
+
+  getFirstEnabledInputEl: (ctx: Ctx) => dom.getRootEl(ctx)?.querySelector<HTMLInputElement>("input:not(:disabled)"),
+  getFirstEnabledAndCheckedInputEl: (ctx: Ctx) =>
+    dom.getRootEl(ctx)?.querySelector<HTMLInputElement>("input:not(:disabled):checked"),
+
+  getInputEls: (ctx: Ctx) => {
+    const ownerId = CSS.escape(dom.getRootId(ctx))
+    const selector = `input[type=radio][data-ownedby='${ownerId}']:not([disabled])`
+    return queryAll<HTMLInputElement>(dom.getRootEl(ctx), selector)
+  },
+
+  getActiveRadioEl: (ctx: Ctx) => {
+    if (!ctx.value) return
+    return dom.getById(ctx, dom.getRadioId(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 = dom.queryById(ctx, dom.getRadioId(ctx, id))
+    return dom.resolveRect(dom.getOffsetRect(tab))
+  },
+
+  resolveRect(rect: Record<"width" | "height" | "left" | "top", number>) {
+    return {
+      width: `${rect.width}px`,
+      height: `${rect.height}px`,
+      left: `${rect.left}px`,
+      top: `${rect.top}px`,
+    }
+  },
+})

package/src/radio-group.machine.ts

@@ -0,0 +1,138 @@
+import { createMachine } from "@zag-js/core"
+import { nextTick } from "@zag-js/dom-query"
+import { trackElementRect } from "@zag-js/element-rect"
+import { trackFormControl } from "@zag-js/form-utils"
+import { compact, isString } from "@zag-js/utils"
+import { dom } from "./radio-group.dom"
+import type { MachineContext, MachineState, UserDefinedContext } from "./radio-group.types"
+
+export function machine(userContext: UserDefinedContext) {
+  const ctx = compact(userContext)
+  return createMachine<MachineContext, MachineState>(
+    {
+      id: "radio",
+      initial: "idle",
+      context: {
+        previousValue: null,
+        value: null,
+        activeId: null,
+        focusedId: null,
+        hoveredId: null,
+        indicatorRect: {},
+        canIndicatorTransition: false,
+        ...ctx,
+      },
+
+      entry: ["syncIndicatorRect"],
+
+      exit: ["cleanupObserver"],
+
+      activities: ["trackFormControlState"],
+
+      watch: {
+        value: [
+          "setIndicatorTransition",
+          // important to set this after `setIndicatorTransition`
+          "setPreviousValue",
+          "invokeOnChange",
+          "syncIndicatorRect",
+          "syncInputElements",
+        ],
+      },
+
+      on: {
+        SET_VALUE: {
+          actions: ["setValue"],
+        },
+        SET_HOVERED: {
+          actions: "setHovered",
+        },
+        SET_ACTIVE: {
+          actions: "setActive",
+        },
+        SET_FOCUSED: {
+          actions: "setFocused",
+        },
+      },
+
+      states: {
+        idle: {},
+      },
+    },
+
+    {
+      activities: {
+        trackFormControlState(ctx, _evt, { send, initialContext }) {
+          return trackFormControl(dom.getRootEl(ctx), {
+            onFieldsetDisabled() {
+              ctx.disabled = true
+            },
+            onFormReset() {
+              send({ type: "SET_VALUE", value: initialContext.value })
+            },
+          })
+        },
+      },
+
+      actions: {
+        setValue(ctx, evt) {
+          ctx.value = evt.value
+        },
+        setHovered(ctx, evt) {
+          ctx.hoveredId = evt.value
+        },
+        setActive(ctx, evt) {
+          ctx.activeId = evt.value
+        },
+        setFocused(ctx, evt) {
+          ctx.focusedId = evt.value
+        },
+        invokeOnChange(ctx, evt) {
+          ctx.onChange?.({ value: evt.value })
+        },
+        syncInputElements(ctx) {
+          const inputs = dom.getInputEls(ctx)
+          inputs.forEach((input) => {
+            input.checked = input.value === ctx.value
+          })
+        },
+        setPreviousValue(ctx) {
+          ctx.previousValue = ctx.value
+        },
+        setIndicatorTransition(ctx) {
+          ctx.canIndicatorTransition = isString(ctx.previousValue) && isString(ctx.value)
+        },
+        cleanupObserver(ctx) {
+          ctx.indicatorCleanup?.()
+        },
+        syncIndicatorRect(ctx) {
+          ctx.indicatorCleanup?.()
+
+          if (!dom.getIndicatorEl(ctx)) return
+
+          const value = ctx.value
+
+          if (value == null) {
+            ctx.indicatorRect = {}
+            return
+          }
+
+          const radioEl = dom.getActiveRadioEl(ctx)
+          if (!radioEl) return
+
+          ctx.indicatorCleanup = trackElementRect(radioEl, {
+            getRect(el) {
+              return dom.getOffsetRect(el)
+            },
+            onChange(rect) {
+              ctx.indicatorRect = dom.resolveRect(rect)
+              nextTick(() => {
+                ctx.canIndicatorTransition = false
+              })
+            },
+          })
+        },
+      },
+    },
+  )
+}

package/src/radio-group.types.ts

@@ -0,0 +1,131 @@
+import type { StateMachine as S } from "@zag-js/core"
+import type { CommonProperties, Context, DirectionProperty, RequiredBy } from "@zag-js/types"
+
+type ElementIds = Partial<{
+  root: string
+  label: string
+  indicator: string
+  radio(value: string): string
+  radioLabel(value: string): string
+  radioControl(value: string): string
+  radioInput(value: string): string
+}>
+
+type PublicContext = DirectionProperty &
+  CommonProperties & {
+    /**
+     * The ids of the elements in the radio. Useful for composition.
+     */
+    ids?: ElementIds
+    /**
+     * The value of the checked radio
+     */
+    value: string | null
+
+    /**
+     * The name of the input fields in the radio
+     * (Useful for form submission).
+     */
+    name?: string
+    /**
+     * The associate form of the underlying input.
+     */
+    form?: string
+    /**
+     * If `true`, the radio group will be disabled
+     */
+    disabled?: boolean
+    /**
+     * If `true`, the radio group will be readonly
+     */
+    readOnly?: boolean
+    /**
+     * Function called once a radio is checked
+     * @param value the value of the checked radio
+     */
+    onChange?(details: { value: string }): void
+    /**
+     * Orientation of the radio group
+     */
+    orientation?: "horizontal" | "vertical"
+  }
+
+type PrivateContext = Context<{
+  /**
+   * @internal
+   * The id of the active radio
+   */
+  activeId: string | null
+  /**
+   * @internal
+   * The id of the focused radio
+   */
+  focusedId: string | null
+  /**
+   * @internal
+   * The id of the hovered radio
+   */
+  hoveredId: string | null
+  /**
+   * @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
+   * Function to clean up the observer for the active tab's rect
+   */
+  indicatorCleanup?: VoidFunction | null
+  /**
+   * @internal
+   * The previous value of the radio group
+   */
+  previousValue: string | null
+}>
+
+export type UserDefinedContext = RequiredBy<PublicContext, "id">
+
+type ComputedContext = Readonly<{}>
+
+export type MachineContext = PublicContext & PrivateContext & ComputedContext
+
+export type MachineState = {
+  value: "idle"
+}
+
+export type State = S.State<MachineContext, MachineState>
+
+export type Send = S.Send<S.AnyEventObject>
+
+export type RadioProps = {
+  value: string
+  /**
+   * If `true`, the radio will be disabled
+   */
+  disabled?: boolean
+  /**
+   * If `true`, the radio will be readonly
+   */
+  readOnly?: boolean
+  /**
+   * If `true`, the radio is marked as invalid.
+   */
+  invalid?: boolean
+}
+
+export type InputProps = RadioProps & {
+  /**
+   * If `true` and `disabled` is passed, the radio will
+   * remain tabbable but not interactive
+   */
+  focusable?: boolean
+  /**
+   * If `true`, the radio input is marked as required,
+   */
+  required?: boolean
+}