refactor(tour): prefer userland z-index

.changeset/ten-islands-search.md

@@ -0,0 +1,5 @@
+---
+"@zag-js/tour": patch
+---
+
+Remove `zIndex` from your elements in favor of userland control.

packages/machines/tour/src/tour.connect.ts

@@ -1,5 +1,5 @@
 import { mergeProps } from "@zag-js/core"
-import { dataAttr, MAX_Z_INDEX } from "@zag-js/dom-query"
+import { dataAttr } from "@zag-js/dom-query"
 import { getPlacementStyles } from "@zag-js/popper"
 import type { NormalizeProps, PropTypes } from "@zag-js/types"
 import { parts } from "./tour.anatomy"
@@ -111,12 +111,13 @@ export function connect<T extends PropTypes>(state: State, send: Send, normalize
         dir: state.context.dir,
         hidden: !open,
         "data-state": open ? "open" : "closed",
+        "data-type": step?.type,
         style: {
+          "--tour-layer": 0,
           clipPath: isTooltipStep(step) ? `path("${clipPath}")` : undefined,
           position: "absolute",
           inset: "0",
           willChange: "clip-path",
-          zIndex: MAX_Z_INDEX,
         },
       })
     },
@@ -126,6 +127,7 @@ export function connect<T extends PropTypes>(state: State, send: Send, normalize
         ...parts.spotlight.attrs,
         hidden: !open || !step?.target?.(),
         style: {
+          "--tour-layer": 1,
           position: "absolute",
           width: `${targetRect.width}px`,
           height: `${targetRect.height}px`,
@@ -150,7 +152,10 @@ export function connect<T extends PropTypes>(state: State, send: Send, normalize
         id: dom.getPositionerId(state.context),
         "data-type": step?.type,
         "data-placement": state.context.currentPlacement,
-        style: step?.type === "tooltip" ? popperStyles.floating : { zIndex: MAX_Z_INDEX },
+        style: {
+          "--tour-layer": 2,
+          ...(step?.type === "tooltip" && popperStyles.floating),
+        },
       })
     },
 
@@ -190,7 +195,6 @@ export function connect<T extends PropTypes>(state: State, send: Send, normalize
         "aria-labelledby": dom.getTitleId(state.context),
         "aria-describedby": dom.getDescriptionId(state.context),
         tabIndex: -1,
-        style: { zIndex: MAX_Z_INDEX },
         onKeyDown(event) {
           if (event.defaultPrevented) return
           if (!state.context.keyboardNavigation) return

shared/src/css/layout.css

@@ -2,6 +2,10 @@
   --ring-color: blue;
 }
 
+body {
+  position: relative;
+}
+
 * {
   box-sizing: border-box;
   font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Open Sans",

website/data/components/tour.mdx

@@ -285,6 +285,112 @@ const Lifecycle = () => {
 }
 ```
 
+## Styling guide
+
+### Prerequisites
+
+Ensure the `box-sizing` is set to `border-box` for the means of measuring the
+tour target.
+
+```css
+* {
+  box-sizing: border-box;
+}
+```
+
+Ensure the `body` has a `position` of `relative`.
+
+```css
+body {
+  position: relative;
+}
+```
+
+### Overview
+
+Each tour part has a `data-part` attribute that can be used to style them in the
+DOM.
+
+```css
+[data-scope="tour"][data-part="content"] {
+  /* styles for the content part */
+}
+
+[data-scope="tour"][data-part="positioner"] {
+  /* styles for the positioner part */
+}
+
+[data-scope="tour"][data-part="arrow"] {
+  /* styles for the arrow part */
+}
+
+[data-scope="tour"][data-part="title"] {
+  /* styles for the title part */
+}
+
+[data-scope="tour"][data-part="description"] {
+  /* styles for the description part */
+}
+
+[data-scope="tour"][data-part="progress-text"] {
+  /* styles for the progress text part */
+}
+
+[data-scope="tour"][data-part="action-trigger"] {
+  /* styles for the action trigger part */
+}
+
+[data-scope="tour"][data-part="backdrop"] {
+  /* styles for the backdrop part */
+}
+```
+
+### Step types
+
+The tour component supports two types: `dialog` and `floating`. You can apply
+specific styles based on the tour type:
+
+```css
+[data-scope="tour"][data-part="content"][data-type="dialog"] {
+  /* styles for content when step is dialog type */
+}
+
+[data-scope="tour"][data-part="content"][data-type="floating"] {
+  /* styles for content when step is floating type */
+}
+
+[data-scope="tour"][data-part="positioner"][data-type="dialog"] {
+  /* styles for positioner when step is dialog type */
+}
+
+[data-scope="tour"][data-part="positioner"][data-type="floating"] {
+  /* styles for positioner when step is floating type */
+}
+```
+
+### Placement Styles
+
+For floating type tours, you can style based on the placement using the
+`data-placement` attribute:
+
+```css
+[data-scope="tour"][data-part="positioner"][data-type="floating"][data-placement*="bottom"] {
+  /* styles for bottom placement */
+}
+
+[data-scope="tour"][data-part="positioner"][data-type="floating"][data-placement*="top"] {
+  /* styles for top placement */
+}
+
+[data-scope="tour"][data-part="positioner"][data-type="floating"][data-placement*="start"] {
+  /* styles for start placement */
+}
+
+[data-scope="tour"][data-part="positioner"][data-type="floating"][data-placement*="end"] {
+  /* styles for end placement */
+}
+```
+
 ## Methods and Properties
 
 ### Machine Context

website/next-env.d.ts

@@ -2,4 +2,4 @@
 /// <reference types="next/image-types/global" />
 
 // NOTE: This file should not be edited
-// see https://nextjs.org/docs/pages/building-your-application/configuring/typescript for more information.
+// see https://nextjs.org/docs/pages/api-reference/config/typescript for more information.

website/styles/machines/tour.css

@@ -1,3 +1,7 @@
+:root {
+  --tour-z-index: 100;
+}
+
 .tour-trigger {
   display: inline-flex;
   align-items: center;
@@ -20,9 +24,13 @@
   border-radius: 4px;
   box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
   width: 300px;
+  position: relative;
+  z-index: calc(var(--tour-layer) + var(--tour-z-index));
 }
 
 [data-scope="tour"][data-part="positioner"] {
+  z-index: calc(var(--tour-layer) + var(--tour-z-index));
+
   &[data-type="floating"] {
     position: absolute;
 
@@ -55,8 +63,6 @@
 }
 
 [data-scope="tour"][data-part="content"] {
-  position: relative;
-
   &[data-type="dialog"] {
     width: 500px;
     background: var(--colors-bg-subtle);
@@ -105,10 +111,12 @@
 
 [data-scope="tour"][data-part="backdrop"] {
   background-color: rgba(0, 0, 0, 0.5);
+  z-index: calc(var(--tour-layer) + var(--tour-z-index));
 }
 
 [data-scope="tour"][data-part="spotlight"] {
   border: 3px solid var(--colors-bg-primary-subtle);
+  z-index: calc(var(--tour-layer) + var(--tour-z-index));
 }
 
 [data-scope="tour"][data-part="close-trigger"] {