feat: add support for id composition

packages/machines/accordion/src/accordion.connect.ts

@@ -35,7 +35,7 @@ export function connect<T extends PropTypes = ReactPropTypes>(state: State, send
       const { isOpen, isFocused } = api.getItemState(props)
       return normalize.element<T>({
         "data-part": "item",
-        id: dom.getGroupId(state.context, props.value),
+        id: dom.getItemId(state.context, props.value),
         "data-expanded": dataAttr(isOpen),
         "data-focus": dataAttr(isFocused),
       })

packages/machines/accordion/src/accordion.dom.ts

@@ -5,10 +5,10 @@ import type { MachineContext as Ctx } from "./accordion.types"
 export const dom = {
   getDoc: (ctx: Ctx) => ctx.doc ?? document,
 
-  getRootId: (ctx: Ctx) => `accordion-${ctx.uid}`,
-  getGroupId: (ctx: Ctx, id: string) => `accordion-${ctx.uid}-item-${id}`,
-  getContentId: (ctx: Ctx, id: string) => `accordion-${ctx.uid}-content-${id}`,
-  getTriggerId: (ctx: Ctx, id: string) => `accordion-${ctx.uid}-trigger-${id}`,
+  getRootId: (ctx: Ctx) => ctx.ids?.root ?? `accordion-${ctx.uid}`,
+  getItemId: (ctx: Ctx, value: string) => ctx.ids?.item?.(value) ?? `accordion-${ctx.uid}-item-${value}`,
+  getContentId: (ctx: Ctx, value: string) => ctx.ids?.content?.(value) ?? `accordion-${ctx.uid}-content-${value}`,
+  getTriggerId: (ctx: Ctx, value: string) => ctx.ids?.trigger?.(value) ?? `accordion-${ctx.uid}-trigger-${value}`,
 
   getRootEl: (ctx: Ctx) => dom.getDoc(ctx).getElementById(dom.getRootId(ctx)),
   getTriggers: (ctx: Ctx) => {

packages/machines/accordion/src/accordion.types.ts

@@ -1,7 +1,18 @@
 import type { StateMachine as S } from "@zag-js/core"
 import type { Context } from "@zag-js/types"
 
+type IdMap = Partial<{
+  root: string
+  item(value: string): string
+  content(value: string): string
+  trigger(value: string): string
+}>
+
 export type MachineContext = Context<{
+  /**
+   * The ids of the elements in the accordion. Useful for composition.
+   */
+  ids?: IdMap
   /**
    * Whether multple accordion items can be open at the same time.
    * @default false

packages/machines/combobox/src/combobox.dom.ts

@@ -6,16 +6,16 @@ import type { MachineContext as Ctx } from "./combobox.types"
 export const dom = {
   getDoc: (ctx: Ctx) => ctx.doc ?? document,
 
-  getRootId: (ctx: Ctx) => `combobox-${ctx.uid}-root`,
-  getLabelId: (ctx: Ctx) => `combobox-${ctx.uid}-label`,
-  getControlId: (ctx: Ctx) => `combobox-${ctx.uid}`,
-  getInputId: (ctx: Ctx) => `combobox-${ctx.uid}-input`,
-  getListboxId: (ctx: Ctx) => `combobox-${ctx.uid}-listbox`,
-  getPositionerId: (ctx: Ctx) => `combobox-${ctx.uid}-popover`,
-  getToggleBtnId: (ctx: Ctx) => `combobox-${ctx.uid}-toggle-btn`,
-  getClearBtnId: (ctx: Ctx) => `combobox-${ctx.uid}-clear-btn`,
-  getOptionId: (ctx: Ctx, id: number | string, index?: number) =>
-    [`combobox-${ctx.uid}-option-${id}`, index].filter((v) => v != null).join("-"),
+  getRootId: (ctx: Ctx) => ctx.ids?.root ?? `combobox-${ctx.uid}-root`,
+  getLabelId: (ctx: Ctx) => ctx.ids?.label ?? `combobox-${ctx.uid}-label`,
+  getControlId: (ctx: Ctx) => ctx.ids?.control ?? `combobox-${ctx.uid}`,
+  getInputId: (ctx: Ctx) => ctx.ids?.input ?? `combobox-${ctx.uid}-input`,
+  getListboxId: (ctx: Ctx) => ctx.ids?.listbox ?? `combobox-${ctx.uid}-listbox`,
+  getPositionerId: (ctx: Ctx) => `combobox-${ctx.uid}-popper`,
+  getToggleBtnId: (ctx: Ctx) => ctx.ids?.toggleBtn ?? `combobox-${ctx.uid}-toggle-btn`,
+  getClearBtnId: (ctx: Ctx) => ctx.ids?.clearBtn ?? `combobox-${ctx.uid}-clear-btn`,
+  getOptionId: (ctx: Ctx, id: string, index?: number) =>
+    ctx.ids?.option?.(id, index) ?? [`combobox-${ctx.uid}-option-${id}`, index].filter((v) => v != null).join("-"),
 
   getActiveOptionEl: (ctx: Ctx) => (ctx.activeId ? dom.getDoc(ctx).getElementById(ctx.activeId) : null),
   getListboxEl: (ctx: Ctx) => dom.getDoc(ctx).getElementById(dom.getListboxId(ctx)),

packages/machines/combobox/src/combobox.types.ts

@@ -15,7 +15,22 @@ type IntlMessages = {
   navigationHint?: string
 }
 
+type IdMap = Partial<{
+  root: string
+  label: string
+  control: string
+  input: string
+  listbox: string
+  toggleBtn: string
+  clearBtn: string
+  option(id: string, index?: number): string
+}>
+
 export type MachineContext = Context<{
+  /**
+   * The ids of the elements in the combobox. Useful for composition.
+   */
+  ids?: IdMap
   /**
    * The current value of the combobox's input
    */

packages/machines/dialog/src/dialog.dom.ts

@@ -3,13 +3,14 @@ import { MachineContext as Ctx } from "./dialog.types"
 export const dom = {
   getDoc: (ctx: Ctx) => ctx.doc ?? document,
   getWin: (ctx: Ctx) => dom.getDoc(ctx).defaultView ?? window,
-  getUnderlayId: (ctx: Ctx) => `dialog-underlay-${ctx.uid}`,
-  getBackdropId: (ctx: Ctx) => `dialog-backdrop-${ctx.uid}`,
-  getContentId: (ctx: Ctx) => `dialog-content-${ctx.uid}`,
-  getTriggerId: (ctx: Ctx) => `dialog-trigger-${ctx.uid}`,
-  getTitleId: (ctx: Ctx) => `dialog-title-${ctx.uid}`,
-  getDescriptionId: (ctx: Ctx) => `dialog-desc-${ctx.uid}`,
-  getCloseButtonId: (ctx: Ctx) => `dialog-close-btn-${ctx.uid}`,
+
+  getUnderlayId: (ctx: Ctx) => ctx.ids?.underlay ?? `dialog-underlay-${ctx.uid}`,
+  getBackdropId: (ctx: Ctx) => ctx.ids?.backdrop ?? `dialog-backdrop-${ctx.uid}`,
+  getContentId: (ctx: Ctx) => ctx.ids?.content ?? `dialog-content-${ctx.uid}`,
+  getTriggerId: (ctx: Ctx) => ctx.ids?.trigger ?? `dialog-trigger-${ctx.uid}`,
+  getTitleId: (ctx: Ctx) => ctx.ids?.title ?? `dialog-title-${ctx.uid}`,
+  getDescriptionId: (ctx: Ctx) => ctx.ids?.description ?? `dialog-desc-${ctx.uid}`,
+  getCloseButtonId: (ctx: Ctx) => ctx.ids?.closeBtn ?? `dialog-close-btn-${ctx.uid}`,
 
   getContentEl: (ctx: Ctx) => dom.getDoc(ctx).getElementById(dom.getContentId(ctx)) as HTMLElement,
   getUnderlayEl: (ctx: Ctx) => dom.getDoc(ctx).getElementById(dom.getUnderlayId(ctx)) as HTMLElement,

packages/machines/dialog/src/dialog.types.ts

@@ -1,6 +1,20 @@
 import type { Context, MaybeElement } from "@zag-js/types"
 
+type IdMap = Partial<{
+  trigger: string
+  underlay: string
+  backdrop: string
+  content: string
+  closeBtn: string
+  title: string
+  description: string
+}>
+
 export type MachineContext = Context<{
+  /**
+   * The ids of the elements in the dialog. Useful for composition.
+   */
+  ids?: IdMap
   /**
    * @internal Whether the dialog title is rendered
    */

packages/machines/editable/src/editable.dom.ts

@@ -6,15 +6,15 @@ type HTMLInputEl = HTMLInputElement | null
 export const dom = {
   getDoc: (ctx: Ctx) => ctx.doc ?? document,
 
-  getRootId: (ctx: Ctx) => `editable-${ctx.uid}`,
-  getAreaId: (ctx: Ctx) => `editable-${ctx.uid}-area`,
-  getLabelId: (ctx: Ctx) => `editable-${ctx.uid}-label`,
-  getPreviewId: (ctx: Ctx) => `editable-${ctx.uid}-preview`,
-  getInputId: (ctx: Ctx) => `editable-${ctx.uid}-input`,
-  getControlGroupId: (ctx: Ctx) => `editable-${ctx.uid}-controls`,
-  getSubmitBtnId: (ctx: Ctx) => `editable-${ctx.uid}-submit-btn`,
-  getCancelBtnId: (ctx: Ctx) => `editable-${ctx.uid}-cancel-btn`,
-  getEditBtnId: (ctx: Ctx) => `editable-${ctx.uid}-edit-btn`,
+  getRootId: (ctx: Ctx) => ctx.ids?.root ?? `editable-${ctx.uid}`,
+  getAreaId: (ctx: Ctx) => ctx.ids?.area ?? `editable-${ctx.uid}-area`,
+  getLabelId: (ctx: Ctx) => ctx.ids?.label ?? `editable-${ctx.uid}-label`,
+  getPreviewId: (ctx: Ctx) => ctx.ids?.preview ?? `editable-${ctx.uid}-preview`,
+  getInputId: (ctx: Ctx) => ctx.ids?.input ?? `editable-${ctx.uid}-input`,
+  getControlGroupId: (ctx: Ctx) => ctx.ids?.controlGroup ?? `editable-${ctx.uid}-controls`,
+  getSubmitBtnId: (ctx: Ctx) => ctx.ids?.submitBtn ?? `editable-${ctx.uid}-submit-btn`,
+  getCancelBtnId: (ctx: Ctx) => ctx.ids?.cancelBtn ?? `editable-${ctx.uid}-cancel-btn`,
+  getEditBtnId: (ctx: Ctx) => ctx.ids?.editBtn ?? `editable-${ctx.uid}-edit-btn`,
 
   getInputEl: (ctx: Ctx) => dom.getDoc(ctx).getElementById(dom.getInputId(ctx)) as HTMLInputEl,
   getPreviewEl: (ctx: Ctx) => dom.getDoc(ctx).getElementById(dom.getPreviewId(ctx)) as HTMLInputEl,

packages/machines/editable/src/editable.types.ts

@@ -12,7 +12,23 @@ type IntlMessages = {
   input: string
 }
 
+type IdMap = Partial<{
+  root: string
+  area: string
+  label: string
+  preview: string
+  input: string
+  controlGroup: string
+  submitBtn: string
+  cancelBtn: string
+  editBtn: string
+}>
+
 export type MachineContext = Context<{
+  /**
+   * The ids of the elements in the editable. Useful for composition.
+   */
+  ids?: IdMap
   /**
    * Whether the input's value is invalid.
    */

packages/machines/menu/src/menu.dom.ts

@@ -7,13 +7,13 @@ type HTMLEl = HTMLElement | null
 export const dom = {
   getDoc: (ctx: Ctx) => ctx.doc ?? document,
 
-  getTriggerId: (ctx: Ctx) => `menu-${ctx.uid}-trigger`,
-  getContextTriggerId: (ctx: Ctx) => `menu-${ctx.uid}-context-trigger`,
-  getContentId: (ctx: Ctx) => `menu-${ctx.uid}-menulist`,
-  getArrowId: (ctx: Ctx) => `popover-${ctx.uid}--arrow`,
-  getPositionerId: (ctx: Ctx) => `tooltip-${ctx.uid}--popper`,
-  getGroupId: (ctx: Ctx, id: string) => `menu-${ctx.uid}-group-${id}`,
-  getLabelId: (ctx: Ctx, id: string) => `menu-${ctx.uid}-label-${id}`,
+  getTriggerId: (ctx: Ctx) => ctx.ids?.trigger ?? `menu-${ctx.uid}-trigger`,
+  getContextTriggerId: (ctx: Ctx) => ctx.ids?.contextTrigger ?? `menu-${ctx.uid}-context-trigger`,
+  getContentId: (ctx: Ctx) => ctx.ids?.content ?? `menu-${ctx.uid}-menulist`,
+  getArrowId: (ctx: Ctx) => `menu-${ctx.uid}--arrow`,
+  getPositionerId: (ctx: Ctx) => `menu-${ctx.uid}--popper`,
+  getGroupId: (ctx: Ctx, id: string) => ctx.ids?.group?.(id) ?? `menu-${ctx.uid}-group-${id}`,
+  getLabelId: (ctx: Ctx, id: string) => ctx.ids?.label?.(id) ?? `menu-${ctx.uid}-label-${id}`,
 
   getContentEl: (ctx: Ctx) => dom.getDoc(ctx).getElementById(dom.getContentId(ctx)) as HTMLEl,
   getPositionerEl: (ctx: Ctx) => dom.getDoc(ctx).getElementById(dom.getPositionerId(ctx)),

packages/machines/menu/src/menu.types.ts

@@ -10,7 +10,19 @@ export type MachineState = {
   tags: "visible"
 }
 
+type IdMap = Partial<{
+  trigger: string
+  contextTrigger: string
+  content: string
+  label(id: string): string
+  group(id: string): string
+}>
+
 export type MachineContext = Context<{
+  /**
+   * The ids of the elements in the menu. Useful for composition.
+   */
+  ids?: IdMap
   /**
    * The values of radios and checkboxes in the menu.
    */

packages/machines/number-input/src/number-input.dom.ts

@@ -9,13 +9,13 @@ export const dom = {
   getDoc: (ctx: Ctx) => ctx.doc ?? document,
   getWin: (ctx: Ctx) => dom.getDoc(ctx).defaultView ?? window,
 
-  getInputId: (ctx: Ctx) => `number-input-${ctx.uid}-input`,
-  getIncButtonId: (ctx: Ctx) => `number-input-${ctx.uid}-inc-btn`,
-  getDecButtonId: (ctx: Ctx) => `number-input-${ctx.uid}-dec-btn`,
-  getScrubberId: (ctx: Ctx) => `number-input-${ctx.uid}-scrubber`,
+  getInputId: (ctx: Ctx) => ctx.ids?.input ?? `number-input-${ctx.uid}-input`,
+  getIncButtonId: (ctx: Ctx) => ctx.ids?.incBtn ?? `number-input-${ctx.uid}-inc-btn`,
+  getDecButtonId: (ctx: Ctx) => ctx.ids?.decBtn ?? `number-input-${ctx.uid}-dec-btn`,
+  getScrubberId: (ctx: Ctx) => ctx.ids?.scrubber ?? `number-input-${ctx.uid}-scrubber`,
   getCursorId: (ctx: Ctx) => `number-input-${ctx.uid}-cursor`,
-  getLabelId: (ctx: Ctx) => `number-input-${ctx.uid}-label`,
-  getRootId: (ctx: Ctx) => `number-input-${ctx.uid}-root`,
+  getLabelId: (ctx: Ctx) => ctx.ids?.label ?? `number-input-${ctx.uid}-label`,
+  getRootId: (ctx: Ctx) => ctx.ids?.root ?? `number-input-${ctx.uid}-root`,
 
   getInputEl: (ctx: Ctx) => dom.getDoc(ctx).getElementById(dom.getInputId(ctx)) as InputEl,
   getIncButtonEl: (ctx: Ctx) => dom.getDoc(ctx).getElementById(dom.getIncButtonId(ctx)) as ButtonEl,

packages/machines/number-input/src/number-input.types.ts

@@ -6,6 +6,15 @@ type ValidityState = "rangeUnderflow" | "rangeOverflow"
 
 type InputSelection = Record<"start" | "end", number | null>
 
+type IdMap = Partial<{
+  root: string
+  label: string
+  input: string
+  incBtn: string
+  decBtn: string
+  scrubber: string
+}>
+
 type IntlMessages = {
   /**
    * Function that returns the human-readable value.
@@ -23,6 +32,10 @@ type IntlMessages = {
 }
 
 export type MachineContext = Context<{
+  /**
+   * The ids of the elements in the number input. Useful for composition.
+   */
+  ids?: IdMap
   /**
    * The name attribute of the number input. Useful for form submission.
    */

packages/machines/pin-input/src/pin-input.connect.ts

@@ -53,7 +53,7 @@ export function connect<T extends PropTypes = ReactPropTypes>(
         disabled: state.context.disabled,
         "data-disabled": dataAttr(state.context.disabled),
         "data-complete": dataAttr(isValueComplete),
-        id: dom.getInputId(state.context, index),
+        id: dom.getInputId(state.context, index.toString()),
         "data-ownedby": dom.getRootId(state.context),
         "aria-label": messages.inputLabel(index, state.context.valueLength),
         inputMode: state.context.otp || state.context.type === "numeric" ? "numeric" : "text",

packages/machines/pin-input/src/pin-input.dom.ts

@@ -4,8 +4,8 @@ import { MachineContext as Ctx } from "./pin-input.types"
 export const dom = {
   getDoc: (ctx: Ctx) => ctx.doc ?? document,
 
-  getRootId: (ctx: Ctx) => `pin-input-${ctx.uid}`,
-  getInputId: (ctx: Ctx, id: string | number) => `pin-input-${ctx.uid}-${id}`,
+  getRootId: (ctx: Ctx) => ctx.ids?.root ?? `pin-input-${ctx.uid}`,
+  getInputId: (ctx: Ctx, id: string) => ctx.ids?.input?.(id) ?? `pin-input-${ctx.uid}-${id}`,
 
   getRootEl: (ctx: Ctx) => dom.getDoc(ctx).getElementById(dom.getRootId(ctx)),
   getElements: (ctx: Ctx) => {

packages/machines/pin-input/src/pin-input.types.ts

@@ -4,7 +4,16 @@ type IntlMessages = {
   inputLabel: (index: number, length: number) => string
 }
 
+type IdMap = Partial<{
+  root: string
+  input(id: string): string
+}>
+
 export type MachineContext = Context<{
+  /**
+   * The ids of the elements in the pin input. Useful for composition.
+   */
+  ids?: IdMap
   /**
    * Whether the inputs are disabled
    */

packages/machines/popover/src/popover.dom.ts

@@ -6,14 +6,14 @@ export const dom = {
   getDoc: (ctx: Ctx) => ctx.doc ?? document,
   getActiveEl: (ctx: Ctx) => dom.getDoc(ctx).activeElement,
 
-  getAnchorId: (ctx: Ctx) => `popover-${ctx.uid}-anchor`,
-  getTriggerId: (ctx: Ctx) => `popover-${ctx.uid}-trigger`,
-  getContentId: (ctx: Ctx) => `popover-${ctx.uid}-content`,
+  getAnchorId: (ctx: Ctx) => ctx.ids?.anchor ?? `popover-${ctx.uid}-anchor`,
+  getTriggerId: (ctx: Ctx) => ctx.ids?.trigger ?? `popover-${ctx.uid}-trigger`,
+  getContentId: (ctx: Ctx) => ctx.ids?.content ?? `popover-${ctx.uid}-content`,
   getPositionerId: (ctx: Ctx) => `popover-${ctx.uid}-popper`,
-  getTitleId: (ctx: Ctx) => `popover-${ctx.uid}-title`,
-  getDescriptionId: (ctx: Ctx) => `popover-${ctx.uid}-desc`,
-  getCloseButtonId: (ctx: Ctx) => `popover-${ctx.uid}-close-button`,
   getArrowId: (ctx: Ctx) => `popover-${ctx.uid}-arrow`,
+  getTitleId: (ctx: Ctx) => ctx.ids?.title ?? `popover-${ctx.uid}-title`,
+  getDescriptionId: (ctx: Ctx) => ctx.ids?.description ?? `popover-${ctx.uid}-desc`,
+  getCloseButtonId: (ctx: Ctx) => ctx.ids?.closeBtn ?? `popover-${ctx.uid}-close-button`,
 
   getAnchorEl: (ctx: Ctx) => dom.getDoc(ctx).getElementById(dom.getAnchorId(ctx)),
   getTriggerEl: (ctx: Ctx) => dom.getDoc(ctx).getElementById(dom.getTriggerId(ctx)),

packages/machines/popover/src/popover.types.ts

@@ -1,7 +1,20 @@
 import type { PositioningOptions, Placement } from "@zag-js/popper"
 import type { Context, MaybeElement } from "@zag-js/types"
 
+type IdMap = Partial<{
+  anchor: string
+  trigger: string
+  content: string
+  title: string
+  description: string
+  closeBtn: string
+}>
+
 export type MachineContext = Context<{
+  /**
+   * The ids of the elements in the popover. Useful for composition.
+   */
+  ids?: IdMap
   /**
    * @internal Whether the dialog title is rendered
    */
@@ -10,6 +23,12 @@ export type MachineContext = Context<{
    * @internal Whether the dialog description is rendered
    */
   isDescriptionRendered: boolean
+  /**
+   *
+   * @internal Whether the reference element is rendered to be used as the
+   * positioning reference
+   */
+  isAnchorRendered: boolean
   /**
    * Whether the popover should be modal. When set to `true`:
    * - interaction with outside elements will be disabled
@@ -53,12 +72,6 @@ export type MachineContext = Context<{
    * Function invoked when the popover is closed.
    */
   onClose?: () => void
-  /**
-   *
-   * @internal Whether the reference element is rendered to be used as the
-   * positioning reference
-   */
-  isAnchorRendered: boolean
   /**
    * The user provided options used to position the popover content
    */

packages/machines/range-slider/src/range-slider.dom.ts

@@ -57,14 +57,14 @@ export function getRangeStyle(ctx: Ctx): Style {
 export const dom = {
   getDoc: (ctx: Ctx) => ctx.doc ?? document,
 
-  getRootId: (ctx: Ctx) => `slider-${ctx.uid}`,
-  getThumbId: (ctx: Ctx, index: number) => `slider-thumb-${ctx.uid}-${index}`,
+  getRootId: (ctx: Ctx) => ctx.ids?.root ?? `slider-${ctx.uid}`,
+  getThumbId: (ctx: Ctx, index: number) => ctx.ids?.thumb?.(index) ?? `slider-thumb-${ctx.uid}-${index}`,
   getInputId: (ctx: Ctx, index: number) => `slider-input-${ctx.uid}-${index}`,
-  getControlId: (ctx: Ctx) => `slider-${ctx.uid}-root`,
-  getTrackId: (ctx: Ctx) => `slider-${ctx.uid}-track`,
-  getRangeId: (ctx: Ctx) => `slider-${ctx.uid}-range`,
-  getLabelId: (ctx: Ctx) => `slider-${ctx.uid}-label`,
-  getOutputId: (ctx: Ctx) => `slider-${ctx.uid}-output`,
+  getControlId: (ctx: Ctx) => ctx.ids?.control ?? `slider-${ctx.uid}-root`,
+  getTrackId: (ctx: Ctx) => ctx.ids?.track ?? `slider-${ctx.uid}-track`,
+  getRangeId: (ctx: Ctx) => ctx.ids?.range ?? `slider-${ctx.uid}-range`,
+  getLabelId: (ctx: Ctx) => ctx.ids?.label ?? `slider-${ctx.uid}-label`,
+  getOutputId: (ctx: Ctx) => ctx.ids?.output ?? `slider-${ctx.uid}-output`,
   getMarkerId: (ctx: Ctx, value: number) => `slider-marker-${ctx.uid}-${value}`,
 
   getThumbEl: (ctx: Ctx, index: number) => dom.getDoc(ctx).getElementById(dom.getThumbId(ctx, index)),