Zag

The Drawer machine package is organized into specific files based on their responsibility. Use this guide to locate logic for types, state management, DOM connection, or gesture handling:

• Types: Defined in drawer.types.ts. Contains SwipeDirection, snap point shapes, and service/API types.
• State Machine: Defined in drawer.machine.ts. Manages states such as open, closing, closed, swiping-open, and swipe-area-dragging, along with transitions, guards, actions, and DOM subscription effects.
• DOM Connection: Defined in drawer.connect.ts. Provides props for the DOM (CSS variables, data-* attributes, pointer handlers) and contains presentation math for translation and movement.
• Public API: The index.ts file re-exports the machine, connect, props, types, and stack helpers.

The @zag-js/dismissable utility provides a layering system with the following capabilities:

• Built-in Dismiss Mechanism: Layers close when the user interacts outside the layer or when focus is programmatically moved outside the layer.
• Focus Management: It tracks descendants to ensure focus remains within the layer, even if a previously focused descendant is removed from the DOM.
• Nesting Support: Allows for nesting multiple layers.
• Top-layer Dismissal: The dismiss mechanism is designed to only work for the topmost layer in a stack.

The @zag-js/date-picker machine provides a robust set of features for date selection:

• Selection Modes: Supports single, multiple, and range selection.
• Calendar View: Displays a calendar for visual date selection.
• Date Constraints: Supports disabling specific dates and setting min/max dates.
• Presets: Supports date range presets.
• Localization: Works with localization, timezones, and custom calendar systems.
• Accessibility: Provides keyboard accessibility for navigating the calendar.
• Advanced Display: Supports week numbers and custom format/parse logic.

Note: The date picker is built on top of the @internationalized/date library.

Different frameworks have subtle differences in how they handle JSX attributes and styles. normalizeProps is a utility provided by Zag adapters to automatically convert machine-generated props into a format compatible with your specific framework.

Examples of differences handled by normalizeProps:

• Event Listeners:
  • React/Solid use onKeyDown.
  • Vue uses onKeydown.
• Styles:
  • React accepts numeric values for margins: { marginBottom: 4 }.
  • Solid requires string values with units: { "margin-bottom": "4px" }.
  • Vue requires string values with units: { marginBottom: "4px" }.

The Context Menu machine provides accessible logic for dropdowns and context menus triggered by right-clicks or long-presses (approx. 700ms on pen/touch).

It exports two primary functions:

• machine: The core behavior logic.
• connect: A function that maps the machine's behavior to JSX props and event handlers.

To implement a context menu, you should pass a unique id to useMachine to ensure generated element IDs remain predictable. To handle the right-click trigger, use api.getContextTriggerProps() provided by the machine.

import * as menu from "@zag-js/menu"

// Inside your component:
const service = useMachine(menu.machine, { id: 'my-menu' });
const { api, ...props } = connect(service, menu.connect);

// Apply context trigger props to your trigger element
<div {...api.getContextTriggerProps()} />

The Password Input provides options for managing browser and password manager behavior:

• Ignore password managers: Set ignorePasswordManagers: true to attempt to bypass supported managers (1Password, LastPass, Bitwarden, Dashlane, and Proton Pass). This is useful for non-login scenarios like 'secure notes' or 'confirm password' steps.
• Autocompletion: Use the autoComplete option to specify the expected behavior:
  • new-password: For creating a new password.
  • current-password: For entering an existing password.

// Ignore password managers
const service = useMachine(passwordInput.machine, {
  id: useId(),
  ignorePasswordManagers: true,
})

// Manage autocompletion
const service = useMachine(passwordInput.machine, {
  id: useId(),
  autoComplete: "new-password",
})