@zag-js/pin-input 0.9.2 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zag-js/pin-input",
-  "version": "0.9.2",
+  "version": "0.10.1",
   "description": "Core logic for the pin-input widget implemented as a state machine",
   "keywords": [
     "js",
@@ -17,7 +17,8 @@
   "repository": "https://github.com/chakra-ui/zag/tree/main/packages/pin-input",
   "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.2",
-    "@zag-js/dom-query": "0.9.2",
-    "@zag-js/dom-event": "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/dom-event": "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 "./pin-input.anatomy"
+export { connect } from "./pin-input.connect"
+export { machine } from "./pin-input.machine"
+export type { UserDefinedContext as Context } from "./pin-input.types"

package/src/pin-input.anatomy.ts

@@ -0,0 +1,4 @@
+import { createAnatomy } from "@zag-js/anatomy"
+
+export const anatomy = createAnatomy("pinInput").parts("root", "label", "hiddenInput", "input", "control")
+export const parts = anatomy.build()

package/src/pin-input.connect.ts

@@ -0,0 +1,174 @@
+import { EventKeyMap, getEventKey, getNativeEvent, isModifiedEvent } from "@zag-js/dom-event"
+import { ariaAttr, dataAttr } from "@zag-js/dom-query"
+import type { NormalizeProps, PropTypes } from "@zag-js/types"
+import { invariant } from "@zag-js/utils"
+import { visuallyHiddenStyle } from "@zag-js/visually-hidden"
+import { parts } from "./pin-input.anatomy"
+import { dom } from "./pin-input.dom"
+import type { Send, State } from "./pin-input.types"
+
+export function connect<T extends PropTypes>(state: State, send: Send, normalize: NormalizeProps<T>) {
+  const isValueComplete = state.context.isValueComplete
+  const isInvalid = state.context.invalid
+  const focusedIndex = state.context.focusedIndex
+  const translations = state.context.translations
+
+  function focus() {
+    dom.getFirstInputEl(state.context)?.focus()
+  }
+
+  return {
+    /**
+     * The value of the input as an array of strings.
+     */
+    value: state.context.value,
+    /**
+     * The value of the input as a string.
+     */
+    valueAsString: state.context.valueAsString,
+    /**
+     * Whether all inputs are filled.
+     */
+    isValueComplete: isValueComplete,
+    /**
+     * Function to set the value of the inputs.
+     */
+    setValue(value: string[]) {
+      if (!Array.isArray(value)) {
+        invariant("[pin-input/setValue] value must be an array")
+      }
+      send({ type: "SET_VALUE", value })
+    },
+    /**
+     * Function to clear the value of the inputs.
+     */
+    clearValue() {
+      send({ type: "CLEAR_VALUE" })
+    },
+    /**
+     * Function to set the value of the input at a specific index.
+     */
+    setValueAtIndex(index: number, value: string) {
+      send({ type: "SET_VALUE", value, index })
+    },
+    /**
+     * Function to focus the pin-input. This will focus the first input.
+     */
+    focus,
+
+    rootProps: normalize.element({
+      dir: state.context.dir,
+      ...parts.root.attrs,
+      id: dom.getRootId(state.context),
+      "data-invalid": dataAttr(isInvalid),
+      "data-disabled": dataAttr(state.context.disabled),
+      "data-complete": dataAttr(isValueComplete),
+    }),
+
+    labelProps: normalize.label({
+      ...parts.label.attrs,
+      htmlFor: dom.getHiddenInputId(state.context),
+      id: dom.getLabelId(state.context),
+      "data-invalid": dataAttr(isInvalid),
+      "data-disabled": dataAttr(state.context.disabled),
+      "data-complete": dataAttr(isValueComplete),
+      onClick: (event) => {
+        event.preventDefault()
+        focus()
+      },
+    }),
+
+    hiddenInputProps: normalize.input({
+      ...parts.hiddenInput.attrs,
+      "aria-hidden": true,
+      type: "text",
+      tabIndex: -1,
+      id: dom.getHiddenInputId(state.context),
+      name: state.context.name,
+      form: state.context.form,
+      style: visuallyHiddenStyle,
+      maxLength: state.context.valueLength,
+      defaultValue: state.context.valueAsString,
+    }),
+
+    controlProps: normalize.element({
+      ...parts.control.attrs,
+      id: dom.getControlId(state.context),
+    }),
+
+    getInputProps({ index }: { index: number }) {
+      const inputType = state.context.type === "numeric" ? "tel" : "text"
+      return normalize.input({
+        ...parts.input.attrs,
+        disabled: state.context.disabled,
+        "data-disabled": dataAttr(state.context.disabled),
+        "data-complete": dataAttr(isValueComplete),
+        id: dom.getInputId(state.context, index.toString()),
+        "data-ownedby": dom.getRootId(state.context),
+        "aria-label": translations.inputLabel(index, state.context.valueLength),
+        inputMode: state.context.otp || state.context.type === "numeric" ? "numeric" : "text",
+        "aria-invalid": ariaAttr(isInvalid),
+        "data-invalid": dataAttr(isInvalid),
+        type: state.context.mask ? "password" : inputType,
+        defaultValue: state.context.value[index] || "",
+        autoCapitalize: "none",
+        autoComplete: state.context.otp ? "one-time-code" : "off",
+        placeholder: focusedIndex === index ? "" : state.context.placeholder,
+        onChange(event) {
+          const evt = getNativeEvent(event)
+          const { value } = event.currentTarget
+          if (evt.inputType === "insertFromPaste" || value.length > 2) {
+            send({ type: "PASTE", value })
+            event.preventDefault()
+            return
+          }
+
+          if (evt.inputType === "deleteContentBackward") {
+            send("BACKSPACE")
+            return
+          }
+          send({ type: "INPUT", value, index })
+        },
+        onKeyDown(event) {
+          const evt = getNativeEvent(event)
+          if (evt.isComposing || isModifiedEvent(evt)) return
+
+          const keyMap: EventKeyMap = {
+            Backspace() {
+              send("BACKSPACE")
+            },
+            Delete() {
+              send("DELETE")
+            },
+            ArrowLeft() {
+              send("ARROW_LEFT")
+            },
+            ArrowRight() {
+              send("ARROW_RIGHT")
+            },
+            Enter() {
+              send("ENTER")
+            },
+          }
+
+          const key = getEventKey(event, { dir: state.context.dir })
+          const exec = keyMap[key]
+
+          if (exec) {
+            exec(event)
+            event.preventDefault()
+          } else {
+            if (key === "Tab") return
+            send({ type: "KEY_DOWN", value: key, preventDefault: () => event.preventDefault() })
+          }
+        },
+        onFocus() {
+          send({ type: "FOCUS", index })
+        },
+        onBlur() {
+          send({ type: "BLUR", index })
+        },
+      })
+    },
+  }
+}

package/src/pin-input.dom.ts

@@ -0,0 +1,21 @@
+import { createScope, queryAll } from "@zag-js/dom-query"
+import type { MachineContext as Ctx } from "./pin-input.types"
+
+export const dom = createScope({
+  getRootId: (ctx: Ctx) => ctx.ids?.root ?? `pin-input:${ctx.id}`,
+  getInputId: (ctx: Ctx, id: string) => ctx.ids?.input?.(id) ?? `pin-input:${ctx.id}:${id}`,
+  getHiddenInputId: (ctx: Ctx) => ctx.ids?.hiddenInput ?? `pin-input:${ctx.id}:hidden`,
+  getLabelId: (ctx: Ctx) => ctx.ids?.label ?? `pin-input:${ctx.id}:label`,
+  getControlId: (ctx: Ctx) => ctx.ids?.control ?? `pin-input:${ctx.id}:control`,
+
+  getRootEl: (ctx: Ctx) => dom.getById(ctx, dom.getRootId(ctx)),
+  getElements: (ctx: Ctx) => {
+    const ownerId = CSS.escape(dom.getRootId(ctx))
+    const selector = `input[data-ownedby=${ownerId}]`
+    return queryAll<HTMLInputElement>(dom.getRootEl(ctx), selector)
+  },
+  getInputEl: (ctx: Ctx, id: string) => dom.getById<HTMLInputElement>(ctx, dom.getInputId(ctx, id)),
+  getFocusedInputEl: (ctx: Ctx) => dom.getElements(ctx)[ctx.focusedIndex],
+  getFirstInputEl: (ctx: Ctx) => dom.getElements(ctx)[0],
+  getHiddenInputEl: (ctx: Ctx) => dom.getById<HTMLInputElement>(ctx, dom.getHiddenInputId(ctx)),
+})

package/src/pin-input.machine.ts

@@ -0,0 +1,284 @@
+import { createMachine, guards } from "@zag-js/core"
+import { raf } from "@zag-js/dom-query"
+import { dispatchInputValueEvent } from "@zag-js/form-utils"
+import { compact } from "@zag-js/utils"
+import { dom } from "./pin-input.dom"
+import type { MachineContext, MachineState, UserDefinedContext } from "./pin-input.types"
+
+const { and, not } = guards
+
+export function machine(userContext: UserDefinedContext) {
+  const ctx = compact(userContext)
+  return createMachine<MachineContext, MachineState>(
+    {
+      id: "pin-input",
+      initial: ctx.autoFocus ? "focused" : "idle",
+      context: {
+        value: [],
+        focusedIndex: -1,
+        placeholder: "○",
+        otp: false,
+        type: "numeric",
+        ...ctx,
+        translations: {
+          inputLabel: (index, length) => `pin code ${index + 1} of ${length}`,
+          ...ctx.translations,
+        },
+      },
+
+      computed: {
+        valueLength: (ctx) => ctx.value.length,
+        filledValueLength: (ctx) => ctx.value.filter((v) => v?.trim() !== "").length,
+        isValueComplete: (ctx) => ctx.valueLength === ctx.filledValueLength,
+        valueAsString: (ctx) => ctx.value.join(""),
+        focusedValue: (ctx) => ctx.value[ctx.focusedIndex],
+      },
+
+      watch: {
+        focusedIndex: ["focusInput", "setInputSelection"],
+        value: ["dispatchInputEvent", "syncInputElements"],
+        isValueComplete: ["invokeOnComplete", "blurFocusedInputIfNeeded"],
+      },
+
+      entry: ctx.autoFocus ? ["setupValue", "setFocusIndexToFirst"] : ["setupValue"],
+
+      on: {
+        SET_VALUE: [
+          {
+            guard: "hasIndex",
+            actions: ["setValueAtIndex", "invokeOnChange"],
+          },
+          { actions: ["setValue", "invokeOnChange"] },
+        ],
+        CLEAR_VALUE: [
+          {
+            guard: "isDisabled",
+            actions: ["clearValue", "invokeOnChange"],
+          },
+          {
+            actions: ["clearValue", "invokeOnChange", "setFocusIndexToFirst"],
+          },
+        ],
+      },
+
+      states: {
+        idle: {
+          on: {
+            FOCUS: {
+              target: "focused",
+              actions: "setFocusedIndex",
+            },
+          },
+        },
+        focused: {
+          on: {
+            INPUT: [
+              {
+                guard: and("isFinalValue", "isValidValue"),
+                actions: ["setFocusedValue", "invokeOnChange", "syncInputValue"],
+              },
+              {
+                guard: "isValidValue",
+                actions: ["setFocusedValue", "invokeOnChange", "setNextFocusedIndex", "syncInputValue"],
+              },
+            ],
+            PASTE: [
+              {
+                guard: "isValidValue",
+                actions: ["setPastedValue", "invokeOnChange", "setLastValueFocusIndex"],
+              },
+              { actions: ["resetFocusedValue", "invokeOnChange"] },
+            ],
+            BLUR: {
+              target: "idle",
+              actions: "clearFocusedIndex",
+            },
+            DELETE: {
+              guard: "hasValue",
+              actions: ["clearFocusedValue", "invokeOnChange"],
+            },
+            ARROW_LEFT: {
+              actions: "setPrevFocusedIndex",
+            },
+            ARROW_RIGHT: {
+              actions: "setNextFocusedIndex",
+            },
+            BACKSPACE: [
+              {
+                guard: "hasValue",
+                actions: ["clearFocusedValue", "invokeOnChange"],
+              },
+              {
+                actions: ["setPrevFocusedIndex", "clearFocusedValue", "invokeOnChange"],
+              },
+            ],
+            ENTER: {
+              guard: "isValueComplete",
+              actions: "requestFormSubmit",
+            },
+            KEY_DOWN: {
+              guard: not("isValidValue"),
+              actions: ["preventDefault", "invokeOnInvalid"],
+            },
+          },
+        },
+      },
+    },
+    {
+      guards: {
+        autoFocus: (ctx) => !!ctx.autoFocus,
+        isValueEmpty: (_ctx, evt) => evt.value === "",
+        hasValue: (ctx) => ctx.value[ctx.focusedIndex] !== "",
+        isValueComplete: (ctx) => ctx.isValueComplete,
+        isValidValue: (ctx, evt) => {
+          if (!ctx.pattern) return isValidType(evt.value, ctx.type)
+          const regex = new RegExp(ctx.pattern, "g")
+          return regex.test(evt.value)
+        },
+        isFinalValue: (ctx) => {
+          return (
+            ctx.filledValueLength + 1 === ctx.valueLength &&
+            ctx.value.findIndex((v) => v.trim() === "") === ctx.focusedIndex
+          )
+        },
+        isLastInputFocused: (ctx) => ctx.focusedIndex === ctx.valueLength - 1,
+        hasIndex: (_ctx, evt) => evt.index !== undefined,
+        isDisabled: (ctx) => !!ctx.disabled,
+      },
+      actions: {
+        setupValue: (ctx) => {
+          if (ctx.value.length) return
+          const inputs = dom.getElements(ctx)
+          const emptyValues = Array.from<string>({ length: inputs.length }).fill("")
+          assign(ctx, emptyValues)
+        },
+        focusInput: (ctx) => {
+          raf(() => {
+            if (ctx.focusedIndex === -1) return
+            dom.getFocusedInputEl(ctx)?.focus()
+          })
+        },
+        setInputSelection: (ctx) => {
+          raf(() => {
+            if (ctx.focusedIndex === -1) return
+            const input = dom.getFocusedInputEl(ctx)
+            const length = input.value.length
+            input.selectionStart = ctx.selectOnFocus ? 0 : length
+            input.selectionEnd = length
+          })
+        },
+        invokeOnComplete: (ctx) => {
+          if (!ctx.isValueComplete) return
+          ctx.onComplete?.({ value: Array.from(ctx.value), valueAsString: ctx.valueAsString })
+        },
+        invokeOnChange: (ctx) => {
+          ctx.onChange?.({ value: Array.from(ctx.value) })
+        },
+        dispatchInputEvent: (ctx) => {
+          const inputEl = dom.getHiddenInputEl(ctx)
+          dispatchInputValueEvent(inputEl, { value: ctx.valueAsString })
+        },
+        invokeOnInvalid: (ctx, evt) => {
+          ctx.onInvalid?.({ value: evt.value, index: ctx.focusedIndex })
+        },
+        clearFocusedIndex: (ctx) => {
+          ctx.focusedIndex = -1
+        },
+        setValue: (ctx, evt) => {
+          assign(ctx, evt.value)
+        },
+        setFocusedIndex: (ctx, evt) => {
+          ctx.focusedIndex = evt.index
+        },
+        setFocusedValue: (ctx, evt) => {
+          ctx.value[ctx.focusedIndex] = getNextValue(ctx.focusedValue, evt.value)
+        },
+        syncInputValue(ctx, evt) {
+          const input = dom.getInputEl(ctx, evt.index.toString())
+          if (!input) return
+          input.value = ctx.value[evt.index]
+        },
+        syncInputElements(ctx) {
+          const inputs = dom.getElements(ctx)
+          inputs.forEach((input, index) => {
+            input.value = ctx.value[index]
+          })
+        },
+        setPastedValue(ctx, evt) {
+          raf(() => {
+            const startIndex = ctx.focusedValue ? 1 : 0
+            const value = evt.value.substring(startIndex, startIndex + ctx.valueLength)
+            assign(ctx, value)
+          })
+        },
+        setValueAtIndex: (ctx, evt) => {
+          ctx.value[evt.index] = getNextValue(ctx.focusedValue, evt.value)
+        },
+        clearValue: (ctx) => {
+          const nextValue = Array.from<string>({ length: ctx.valueLength }).fill("")
+          assign(ctx, nextValue)
+        },
+        clearFocusedValue: (ctx) => {
+          ctx.value[ctx.focusedIndex] = ""
+        },
+        resetFocusedValue: (ctx) => {
+          const input = dom.getFocusedInputEl(ctx)
+          input.value = ctx.focusedValue
+        },
+        setFocusIndexToFirst: (ctx) => {
+          ctx.focusedIndex = 0
+        },
+        setNextFocusedIndex: (ctx) => {
+          ctx.focusedIndex = Math.min(ctx.focusedIndex + 1, ctx.valueLength - 1)
+        },
+        setPrevFocusedIndex: (ctx) => {
+          ctx.focusedIndex = Math.max(ctx.focusedIndex - 1, 0)
+        },
+        setLastValueFocusIndex: (ctx) => {
+          raf(() => {
+            ctx.focusedIndex = Math.min(ctx.filledValueLength, ctx.valueLength - 1)
+          })
+        },
+        preventDefault(_, evt) {
+          evt.preventDefault()
+        },
+        blurFocusedInputIfNeeded(ctx) {
+          if (!ctx.blurOnComplete) return
+          raf(() => {
+            dom.getFocusedInputEl(ctx)?.blur()
+          })
+        },
+        requestFormSubmit(ctx) {
+          if (!ctx.name || !ctx.isValueComplete) return
+          const input = dom.getHiddenInputEl(ctx)
+          input?.form?.requestSubmit()
+        },
+      },
+    },
+  )
+}
+
+const REGEX = {
+  numeric: /^[0-9]+$/,
+  alphabetic: /^[A-Za-z]+$/,
+  alphanumeric: /^[a-zA-Z0-9]+$/i,
+}
+
+function isValidType(value: string, type: MachineContext["type"]) {
+  if (!type) return true
+  return !!REGEX[type]?.test(value)
+}
+
+function assign(ctx: MachineContext, value: string | string[]) {
+  const arr = Array.isArray(value) ? value : value.split("").filter(Boolean)
+  arr.forEach((value, index) => {
+    ctx.value[index] = value
+  })
+}
+
+function getNextValue(current: string, next: string) {
+  let nextValue = next
+  if (current[0] === next[0]) nextValue = next[1]
+  else if (current[0] === next[1]) nextValue = next[0]
+  return nextValue
+}

package/src/pin-input.types.ts

@@ -0,0 +1,139 @@
+import type { StateMachine as S } from "@zag-js/core"
+import type { CommonProperties, Context, DirectionProperty, RequiredBy } from "@zag-js/types"
+
+type IntlTranslations = {
+  inputLabel: (index: number, length: number) => string
+}
+
+type ElementIds = Partial<{
+  root: string
+  hiddenInput: string
+  label: string
+  control: string
+  input(id: string): string
+}>
+
+type PublicContext = DirectionProperty &
+  CommonProperties & {
+    /**
+     * The name of the input element. Useful for form submission.
+     */
+    name?: string
+    /**
+     * The associate form of the underlying input element.
+     */
+    form?: string
+    /**
+     * The regular expression that the user-entered input value is checked against.
+     */
+    pattern?: string
+    /**
+     * The ids of the elements in the pin input. Useful for composition.
+     */
+    ids?: ElementIds
+    /**
+     * Whether the inputs are disabled
+     */
+    disabled?: boolean
+    /**
+     * The placeholder text for the input
+     */
+    placeholder?: string
+    /**
+     * Whether to auto-focus the first input.
+     */
+    autoFocus?: boolean
+    /**
+     * Whether the pin input is in the invalid state
+     */
+    invalid?: boolean
+    /**
+     * If `true`, the pin input component signals to its fields that they should
+     * use `autocomplete="one-time-code"`.
+     */
+    otp?: boolean
+    /**
+     * The value of the the pin input.
+     */
+    value: string[]
+    /**
+     * The type of value the pin-input should allow
+     */
+    type?: "alphanumeric" | "numeric" | "alphabetic"
+    /**
+     * Function called when all inputs have valid values
+     */
+    onComplete?: (details: { value: string[]; valueAsString: string }) => void
+    /**
+     * Function called on input change
+     */
+    onChange?: (details: { value: string[] }) => void
+    /**
+     * Function called when an invalid value is entered
+     */
+    onInvalid?: (details: { value: string; index: number }) => void
+    /**
+     * If `true`, the input's value will be masked just like `type=password`
+     */
+    mask?: boolean
+    /**
+     * Whether to blur the input when the value is complete
+     */
+    blurOnComplete?: boolean
+    /**
+     * Whether to select input value when input is focused
+     */
+    selectOnFocus?: boolean
+    /**
+     * Specifies the localized strings that identifies the accessibility elements and their states
+     */
+    translations: IntlTranslations
+  }
+
+export type UserDefinedContext = RequiredBy<PublicContext, "id">
+
+type ComputedContext = Readonly<{
+  /**
+   * @computed
+   * The number of inputs
+   */
+  valueLength: number
+  /**
+   * @computed
+   * The number of inputs that are not empty
+   */
+  filledValueLength: number
+  /**
+   * @computed
+   * Whether all input values are valid
+   */
+  isValueComplete: boolean
+  /**
+   * @computed
+   * The string representation of the input values
+   */
+  valueAsString: string
+  /**
+   * @computed
+   * The value at focused index
+   */
+  focusedValue: string
+}>
+
+type PrivateContext = Context<{
+  /**
+   * @internal
+   * The index of the input field that has focus
+   */
+  focusedIndex: number
+}>
+
+export type MachineContext = PublicContext & PrivateContext & ComputedContext
+
+export type MachineState = {
+  value: "idle" | "focused"
+}
+
+export type State = S.State<MachineContext, MachineState>
+
+export type Send = S.Send<S.AnyEventObject>