@bitrise/bitkit-v2 0.3.356 → 0.3.357

package/AGENTS.md

@@ -139,6 +139,36 @@ Bitkit components use consistent prop names across the library:
   <BitkitDialog open={open} onExitComplete={() => navigate('/next')} onOpenChange={…} title="…">…</BitkitDialog>
   ```
 
+- **`BitkitTour` is a hook plus one element** — `useBitkitTour` owns the steps and the flow, `<BitkitTour>` renders the card; render it once, anywhere in the tree. Every step is a card anchored to an element, so `target` is required and there is no step `type` to choose. `open` drives it from a value you already have (`dismiss()` and `start()` are there for the imperative side), and each step carries its own `actions` — the last one renders as the primary button:
+  ```tsx
+  const startBuild = useRef<HTMLElement>(null);
+  const tour = useBitkitTour({
+    onStatusChange: ({ status }) => status === 'dismissed' && persistDismissal(),
+    open: shouldShowTour,
+    steps: [
+      {
+        actions: [{ action: 'dismiss', label: 'Got it' }],
+        badge: <BitkitBadge colorVariant="yellow">BETA</BitkitBadge>,
+        content: <img alt="" src="/tour/start-build.gif" />,
+        description: 'Kick off a build for any branch or pull request.',
+        id: 'start-build',
+        secondaryAction: { href: '…', label: 'Learn more' },
+        target: () => startBuild.current,
+        title: 'Start a build',
+      },
+    ],
+  });
+  ```
+  A single-step tour drops the `n of m` label, which is what turns the card into the single-feature presentation. Clicking outside never closes it — the close button, the step's own actions and Escape do. It dims the page and cuts the highlight out of the backdrop itself, so don't add your own overlay, ring or z-index around the target.
+- **Testing a page that renders `BitkitTour` in jsdom needs a `visualViewport` stub** — Zag measures its boundary from that global, which jsdom doesn't implement, and it throws whether the tour is open or not. In the jest setup:
+  ```ts
+  Object.defineProperty(window, 'visualViewport', {
+    value: Object.assign(new EventTarget(), { height: window.innerHeight, width: window.innerWidth }),
+    writable: true,
+  });
+  ```
+  In specs, query the card by its role (`getByRole('alertdialog')`) rather than a test id.
+
 ## Coding rules
 
 - **Only use tokens that exist** — never guess token names. Verify via the Storybook MCP `Docs/Colors - *`, `Docs/Shadows`, `Docs/Text Styles`, etc. pages.

package/dist/components/BitkitTour/BitkitTour.d.ts

@@ -46,6 +46,11 @@ export interface BitkitTourOptions extends Omit<UseTourProps, 'closeOnInteractOu
     onStepsChange?: (details: {
         steps: BitkitTourStep[];
     }) => void;
+    /**
+     * Drives the tour from a value the caller already has — it starts when this turns true and closes
+     * when it turns false. Omit it to drive the tour with `start()` and `dismiss()` instead.
+     */
+    open?: boolean;
     steps: BitkitTourStep[];
 }
 /** The tour api returned by `useBitkitTour` — pass it around to control the tour from anywhere. */
@@ -54,6 +59,8 @@ export type BitkitTourInstance = Omit<UseTourReturn, 'addStep' | 'setSteps' | 's
     setSteps: (steps: BitkitTourStep[]) => void;
     /** The current step, with the Bitkit slots (`badge`, `content`, `secondaryAction`) still typed on it. */
     step: BitkitTourStep | null;
+    /** Closes the tour, the same way its close button does. */
+    dismiss: () => void;
     updateStep: (id: string, stepOverrides: Partial<BitkitTourStep>) => void;
 };
 export type BitkitTourProps = {

package/dist/components/BitkitTour/BitkitTour.js

@@ -2,6 +2,7 @@ import BitkitCloseButton from "../BitkitCloseButton/BitkitCloseButton.js";
 import BitkitButton from "../BitkitButton/BitkitButton.js";
 import { Box } from "@chakra-ui/react/box";
 import { chakra, useSlotRecipe } from "@chakra-ui/react/styled-system";
+import { useCallback, useEffect } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Portal } from "@chakra-ui/react/portal";
 import { Tour, useTour } from "@ark-ui/react/tour";
@@ -32,8 +33,23 @@ var useBitkitTour = (options) => {
 			type: "tooltip"
 		}))
 	});
+	const dismiss = useCallback(() => {
+		const closeTriggerClick = tour.getCloseTriggerProps().onClick;
+		closeTriggerClick?.();
+	}, [tour]);
+	const { open } = options;
+	useEffect(() => {
+		if (open === void 0 || open === tour.open) return;
+		if (open) tour.start();
+		else dismiss();
+	}, [
+		dismiss,
+		open,
+		tour.open
+	]);
 	return {
 		...tour,
+		dismiss,
 		step: tour.step
 	};
 };
@@ -62,6 +78,7 @@ var SecondaryAction = ({ secondaryAction }) => {
 			action,
 			label
 		},
+		"aria-label": label,
 		children: /* @__PURE__ */ jsx(BitkitButton, {
 			size: "sm",
 			variant: "tertiary",
@@ -129,6 +146,7 @@ var BitkitTour = ({ tour }) => {
 								children: actions.map((action, index) => /* @__PURE__ */ jsx(Tour.ActionTrigger, {
 									asChild: true,
 									action,
+									"aria-label": action.label,
 									children: /* @__PURE__ */ jsx(BitkitButton, {
 										size: "sm",
 										variant: index === actions.length - 1 ? "primary" : "secondary",

package/dist/components/BitkitTour/BitkitTour.js.map

@@ -1 +1 @@
-{"version":3,"file":"BitkitTour.js","names":[],"sources":["../../../lib/components/BitkitTour/BitkitTour.tsx"],"sourcesContent":["import {\n  Tour as ArkTour,\n  type TourStepDetails,\n  useTour,\n  type UseTourProps,\n  type UseTourReturn,\n} from '@ark-ui/react/tour';\nimport { Box } from '@chakra-ui/react/box';\nimport { Portal } from '@chakra-ui/react/portal';\nimport { chakra, useSlotRecipe } from '@chakra-ui/react/styled-system';\nimport { type ReactNode } from 'react';\n\nimport BitkitButton from '../BitkitButton/BitkitButton';\nimport BitkitCloseButton from '../BitkitCloseButton/BitkitCloseButton';\n\ntype BitkitTourStepAction = NonNullable<TourStepDetails['actions']>[number];\n\n/**\n * The link-style action in the footer, e.g. `Skip tour` or `Learn more`. It either drives the tour\n * (`action`) or leaves the page (`href`) — the union makes passing both, or neither, a type error.\n */\nexport type BitkitTourSecondaryAction =\n  | {\n      /**\n       * A tour action — `'skip'`, `'dismiss'`, `'next'`, `'prev'`, or a function that receives the\n       * action map (`{ next, prev, dismiss, skip, goto }`) to do something else first.\n       */\n      action: NonNullable<BitkitTourStepAction['action']>;\n      href?: never;\n      label: string;\n    }\n  | {\n      action?: never;\n      /** Renders the action as a link out. */\n      href: string;\n      label: string;\n    };\n\n/**\n * A single step of the tour. On top of Ark's step details it carries the three Bitkit slots —\n * `badge`, `content` and `secondaryAction`. Zag spreads the whole step object when it normalises\n * it, so these reach `tour.step` untouched. (Zag also offers a `meta` bag for this; flat fields\n * read better at the call site, at the cost of a name clash if Zag ever adds one of these.)\n *\n * Ark's step `type` is not part of this: every step is a card anchored to an element, so the hook\n * sets it. `target` is required for the same reason — Zag turns a step without one into a centred\n * dialog, which is a presentation this component doesn't have.\n */\nexport type BitkitTourStep = Omit<TourStepDetails, 'type'> & {\n  /**\n   * Rendered next to the title — a `BitkitBadge` in practice, e.g. `BETA` or `NEW`. Nothing about\n   * the badge is fixed here beyond its placement: the element itself comes from the caller.\n   */\n  badge?: ReactNode;\n  /** Rendered between the description and the footer — an image, a video, a table, anything. */\n  content?: ReactNode;\n  secondaryAction?: BitkitTourSecondaryAction;\n  /** The element the step points at. */\n  target: NonNullable<TourStepDetails['target']>;\n};\n\nexport interface BitkitTourOptions extends Omit<UseTourProps, 'closeOnInteractOutside' | 'onStepsChange' | 'steps'> {\n  /** Refined so the callback reports the Bitkit slots too, like the rest of the api does. */\n  onStepsChange?: (details: { steps: BitkitTourStep[] }) => void;\n  steps: BitkitTourStep[];\n}\n/** The tour api returned by `useBitkitTour` — pass it around to control the tour from anywhere. */\nexport type BitkitTourInstance = Omit<UseTourReturn, 'addStep' | 'setSteps' | 'step' | 'updateStep'> & {\n  addStep: (step: BitkitTourStep) => void;\n  setSteps: (steps: BitkitTourStep[]) => void;\n  /** The current step, with the Bitkit slots (`badge`, `content`, `secondaryAction`) still typed on it. */\n  step: BitkitTourStep | null;\n  updateStep: (id: string, stepOverrides: Partial<BitkitTourStep>) => void;\n};\nexport type BitkitTourProps = {\n  /** The tour instance returned by `useBitkitTour`. Start it with `tour.start()`. */\n  tour: BitkitTourInstance;\n};\n\n/**\n * Creates the tour instance that drives `BitkitTour`. Takes the steps plus the tour-level options\n * (`onStepChange`, `onStatusChange`, `closeOnEscape`, `preventInteraction`, `translations`, …) and\n * returns the api used to control it: `start()`, `next()`, `prev()`, `setStep()`, `step`,\n * `stepIndex`, `totalSteps`. Closing on a click outside isn't among them — see below.\n */\nexport const useBitkitTour = (options: BitkitTourOptions): BitkitTourInstance => {\n  const tour = useTour({\n    // The highlight sits 8 around the target, and the card 12 from the highlight — the 8 the arrow\n    // takes plus the 4 gap the design asks for. Both are measured from the highlight, since Zag\n    // grows the anchor rect by `spotlightOffset` before positioning. `offset.mainAxis` replaces\n    // Zag's own gutter, and Popper adds half the arrow's box on top of it: 6 + 5.65 ≈ the 12.\n    spotlightOffset: { x: 8, y: 8 },\n    // 4 is also Zag's current default, but the design asks for it and a third-party default is not\n    // ours to rely on — the z-index contract already moved under us once between two minors.\n    spotlightRadius: 4,\n    ...options,\n    // Not part of the options, and set after the spread so it can't be turned back on: a tour is a\n    // guided flow with its own ways out — the close button, `Skip tour`, `Done` — and Zag would\n    // otherwise end it on any click outside the card, losing the whole thing to a stray click on\n    // the dimmed page. Escape is a deliberate keystroke rather than a stray click, so it keeps\n    // closing the tour by default — and unlike this one, `closeOnEscape` stays in the options for\n    // callers who want it off.\n    closeOnInteractOutside: false,\n    // Same reason as the cast on `Tour.Root` below: our step type isn't a supertype of Ark's, so a\n    // callback taking ours doesn't match the signature Ark declares. The payload is Ark's.\n    onStepsChange: options.onStepsChange as UseTourProps['onStepsChange'],\n    // Zag's default is `close tour`, and this one is visible rather than screen-reader only: the\n    // close button shows its own aria-label in a tooltip. The rest of Zag's translations\n    // (`nextStep`, `prevStep`, `skip`) stay as they are — those only ever reach assistive tech.\n    translations: { close: 'Close tour', ...options.translations },\n    // `type` last: there is one presentation, so it isn't the caller's to pick.\n    steps: options.steps.map((step) => ({ offset: { mainAxis: 6 }, ...step, type: 'tooltip' as const })),\n  });\n\n  return { ...tour, step: tour.step as BitkitTourStep | null };\n};\n\n// The Ark parts aren't Chakra components, so they're wrapped with the `chakra()` factory to accept\n// `css`. They're deliberately NOT wrapped with `asChild`: each Ark part falls back to the current\n// step's content (title, description, progress text, action label) only when it renders its own\n// children, and `asChild` would replace those children with the wrapper element.\nconst TourBackdrop = chakra(ArkTour.Backdrop);\nconst TourSpotlight = chakra(ArkTour.Spotlight);\nconst TourPositioner = chakra(ArkTour.Positioner);\nconst TourContent = chakra(ArkTour.Content);\nconst TourArrow = chakra(ArkTour.Arrow);\nconst TourArrowTip = chakra(ArkTour.ArrowTip);\nconst TourTitle = chakra(ArkTour.Title);\nconst TourDescription = chakra(ArkTour.Description);\nconst TourControl = chakra(ArkTour.Control);\nconst TourProgressText = chakra(ArkTour.ProgressText);\n\nconst SecondaryAction = ({ secondaryAction }: { secondaryAction: BitkitTourSecondaryAction }) => {\n  const { action, href, label } = secondaryAction;\n\n  if (href !== undefined) {\n    return (\n      <BitkitButton href={href} size=\"sm\" variant=\"tertiary\">\n        {label}\n      </BitkitButton>\n    );\n  }\n\n  if (!action) return null;\n\n  return (\n    <ArkTour.ActionTrigger asChild action={{ action, label }}>\n      <BitkitButton size=\"sm\" variant=\"tertiary\">\n        {label}\n      </BitkitButton>\n    </ArkTour.ActionTrigger>\n  );\n};\n\n/**\n * A guided product tour: a step card anchored to an element on the page, with a spotlight cut out\n * of the dimmed backdrop around that element.\n *\n * The steps and the tour behaviour live on the instance — create it with `useBitkitTour` and render\n * `BitkitTour` once, anywhere in the tree. Each step declares its own action buttons; the last one\n * is rendered as the primary button. A single-step tour drops the `1 of n` label, which is what\n * turns the card into the single-feature presentation.\n */\nconst BitkitTour = ({ tour }: BitkitTourProps) => {\n  const recipe = useSlotRecipe({ key: 'tour' });\n  const styles = recipe();\n  const step = tour.step;\n  const actions = step?.actions ?? [];\n\n  return (\n    // `unmountOnExit` isn't only tidiness: Ark's backdrop applies `hidden: !tour.step?.backdrop`\n    // after merging the presence props, which overrides the presence's own `hidden` — and since the\n    // step is kept after the tour closes, the dimming would stay on screen for good. Unmounting on\n    // exit takes the node out before that can happen.\n    // The cast is the price of refining `step` and the step-mutating methods on the instance: our\n    // step type isn't a supertype of Ark's, so the methods no longer match its api signature. The\n    // object is Ark's api — only the types are ours.\n    <ArkTour.Root unmountOnExit tour={tour as UseTourReturn}>\n      <Portal>\n        <TourBackdrop css={styles.backdrop} />\n        <TourSpotlight css={styles.spotlight} />\n        <TourPositioner css={styles.positioner}>\n          <TourContent css={styles.content}>\n            {/* `hidden={false}` overrides Zag, which hides the arrow until the card has been\n                positioned — while Popper computes that position from the arrow's `clientHeight`, so\n                a hidden arrow measures 0 and the card lands 6 short of the design's 12, then drops\n                by that 6 as soon as anything recomputes. Nothing shows in the meantime: until it is\n                positioned the card itself sits off-screen at `-100vh`. */}\n            <TourArrow css={styles.arrow} hidden={false}>\n              <TourArrowTip css={styles.arrowTip} />\n            </TourArrow>\n            <Box css={styles.header}>\n              <Box css={styles.titleGroup}>\n                {tour.totalSteps > 1 ? <TourProgressText css={styles.progressText} /> : null}\n                <Box css={styles.titleRow}>\n                  <TourTitle css={styles.title} />\n                  {step?.badge ? <Box css={styles.badge}>{step.badge}</Box> : null}\n                </Box>\n              </Box>\n              <ArkTour.CloseTrigger asChild>\n                <BitkitCloseButton css={styles.closeTrigger} size=\"xs\" />\n              </ArkTour.CloseTrigger>\n            </Box>\n            <TourDescription css={styles.description} />\n            {step?.content ? <Box css={styles.media}>{step.content}</Box> : null}\n            <TourControl css={styles.control}>\n              {step?.secondaryAction ? <SecondaryAction secondaryAction={step.secondaryAction} /> : null}\n              <Box css={styles.actions}>\n                {actions.map((action, index) => (\n                  <ArkTour.ActionTrigger key={action.label} asChild action={action}>\n                    <BitkitButton size=\"sm\" variant={index === actions.length - 1 ? 'primary' : 'secondary'}>\n                      {action.label}\n                    </BitkitButton>\n                  </ArkTour.ActionTrigger>\n                ))}\n              </Box>\n            </TourControl>\n          </TourContent>\n        </TourPositioner>\n      </Portal>\n    </ArkTour.Root>\n  );\n};\n\nBitkitTour.displayName = 'BitkitTour';\n\nexport default BitkitTour;\n"],"mappings":"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"}
+{"version":3,"file":"BitkitTour.js","names":[],"sources":["../../../lib/components/BitkitTour/BitkitTour.tsx"],"sourcesContent":["import {\n  Tour as ArkTour,\n  type TourStepDetails,\n  useTour,\n  type UseTourProps,\n  type UseTourReturn,\n} from '@ark-ui/react/tour';\nimport { Box } from '@chakra-ui/react/box';\nimport { Portal } from '@chakra-ui/react/portal';\nimport { chakra, useSlotRecipe } from '@chakra-ui/react/styled-system';\nimport { type ReactNode, useCallback, useEffect } from 'react';\n\nimport BitkitButton from '../BitkitButton/BitkitButton';\nimport BitkitCloseButton from '../BitkitCloseButton/BitkitCloseButton';\n\ntype BitkitTourStepAction = NonNullable<TourStepDetails['actions']>[number];\n\n/**\n * The link-style action in the footer, e.g. `Skip tour` or `Learn more`. It either drives the tour\n * (`action`) or leaves the page (`href`) — the union makes passing both, or neither, a type error.\n */\nexport type BitkitTourSecondaryAction =\n  | {\n      /**\n       * A tour action — `'skip'`, `'dismiss'`, `'next'`, `'prev'`, or a function that receives the\n       * action map (`{ next, prev, dismiss, skip, goto }`) to do something else first.\n       */\n      action: NonNullable<BitkitTourStepAction['action']>;\n      href?: never;\n      label: string;\n    }\n  | {\n      action?: never;\n      /** Renders the action as a link out. */\n      href: string;\n      label: string;\n    };\n\n/**\n * A single step of the tour. On top of Ark's step details it carries the three Bitkit slots —\n * `badge`, `content` and `secondaryAction`. Zag spreads the whole step object when it normalises\n * it, so these reach `tour.step` untouched. (Zag also offers a `meta` bag for this; flat fields\n * read better at the call site, at the cost of a name clash if Zag ever adds one of these.)\n *\n * Ark's step `type` is not part of this: every step is a card anchored to an element, so the hook\n * sets it. `target` is required for the same reason — Zag turns a step without one into a centred\n * dialog, which is a presentation this component doesn't have.\n */\nexport type BitkitTourStep = Omit<TourStepDetails, 'type'> & {\n  /**\n   * Rendered next to the title — a `BitkitBadge` in practice, e.g. `BETA` or `NEW`. Nothing about\n   * the badge is fixed here beyond its placement: the element itself comes from the caller.\n   */\n  badge?: ReactNode;\n  /** Rendered between the description and the footer — an image, a video, a table, anything. */\n  content?: ReactNode;\n  secondaryAction?: BitkitTourSecondaryAction;\n  /** The element the step points at. */\n  target: NonNullable<TourStepDetails['target']>;\n};\n\nexport interface BitkitTourOptions extends Omit<UseTourProps, 'closeOnInteractOutside' | 'onStepsChange' | 'steps'> {\n  /** Refined so the callback reports the Bitkit slots too, like the rest of the api does. */\n  onStepsChange?: (details: { steps: BitkitTourStep[] }) => void;\n  /**\n   * Drives the tour from a value the caller already has — it starts when this turns true and closes\n   * when it turns false. Omit it to drive the tour with `start()` and `dismiss()` instead.\n   */\n  open?: boolean;\n  steps: BitkitTourStep[];\n}\n/** The tour api returned by `useBitkitTour` — pass it around to control the tour from anywhere. */\nexport type BitkitTourInstance = Omit<UseTourReturn, 'addStep' | 'setSteps' | 'step' | 'updateStep'> & {\n  addStep: (step: BitkitTourStep) => void;\n  setSteps: (steps: BitkitTourStep[]) => void;\n  /** The current step, with the Bitkit slots (`badge`, `content`, `secondaryAction`) still typed on it. */\n  step: BitkitTourStep | null;\n  /** Closes the tour, the same way its close button does. */\n  dismiss: () => void;\n  updateStep: (id: string, stepOverrides: Partial<BitkitTourStep>) => void;\n};\nexport type BitkitTourProps = {\n  /** The tour instance returned by `useBitkitTour`. Start it with `tour.start()`. */\n  tour: BitkitTourInstance;\n};\n\n/**\n * Creates the tour instance that drives `BitkitTour`. Takes the steps plus the tour-level options\n * (`onStepChange`, `onStatusChange`, `closeOnEscape`, `preventInteraction`, `translations`, …) and\n * returns the api used to control it: `start()`, `next()`, `prev()`, `setStep()`, `step`,\n * `stepIndex`, `totalSteps`. Closing on a click outside isn't among them — see below.\n */\nexport const useBitkitTour = (options: BitkitTourOptions): BitkitTourInstance => {\n  const tour = useTour({\n    // The highlight sits 8 around the target, and the card 12 from the highlight — the 8 the arrow\n    // takes plus the 4 gap the design asks for. Both are measured from the highlight, since Zag\n    // grows the anchor rect by `spotlightOffset` before positioning. `offset.mainAxis` replaces\n    // Zag's own gutter, and Popper adds half the arrow's box on top of it: 6 + 5.65 ≈ the 12.\n    spotlightOffset: { x: 8, y: 8 },\n    // 4 is also Zag's current default, but the design asks for it and a third-party default is not\n    // ours to rely on — the z-index contract already moved under us once between two minors.\n    spotlightRadius: 4,\n    ...options,\n    // Not part of the options, and set after the spread so it can't be turned back on: a tour is a\n    // guided flow with its own ways out — the close button, `Skip tour`, `Done` — and Zag would\n    // otherwise end it on any click outside the card, losing the whole thing to a stray click on\n    // the dimmed page. Escape is a deliberate keystroke rather than a stray click, so it keeps\n    // closing the tour by default — and unlike this one, `closeOnEscape` stays in the options for\n    // callers who want it off.\n    closeOnInteractOutside: false,\n    // Same reason as the cast on `Tour.Root` below: our step type isn't a supertype of Ark's, so a\n    // callback taking ours doesn't match the signature Ark declares. The payload is Ark's.\n    onStepsChange: options.onStepsChange as UseTourProps['onStepsChange'],\n    // Zag's default is `close tour`, and this one is visible rather than screen-reader only: the\n    // close button shows its own aria-label in a tooltip. The rest of Zag's translations\n    // (`nextStep`, `prevStep`, `skip`) stay as they are — those only ever reach assistive tech.\n    translations: { close: 'Close tour', ...options.translations },\n    // `type` last: there is one presentation, so it isn't the caller's to pick.\n    steps: options.steps.map((step) => ({ offset: { mainAxis: 6 }, ...step, type: 'tooltip' as const })),\n  });\n\n  // Zag's api can start a tour but not stop one. Its close trigger's click handler *is* the\n  // machine's dismiss, so this borrows that instead of reaching into the machine. The cast says\n  // what the handler is rather than manufacturing an event for it: `actionMap.dismiss` takes none.\n  const dismiss = useCallback(() => {\n    const closeTriggerClick = tour.getCloseTriggerProps().onClick as (() => void) | undefined;\n\n    closeTriggerClick?.();\n  }, [tour]);\n\n  const { open } = options;\n  useEffect(() => {\n    if (open === undefined || open === tour.open) {\n      return;\n    }\n\n    if (open) {\n      tour.start();\n    } else {\n      dismiss();\n    }\n    // `tour` is a new object on every render, so the machine's own `open` is the dependency that\n    // matters here.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [dismiss, open, tour.open]);\n\n  return { ...tour, dismiss, step: tour.step as BitkitTourStep | null };\n};\n\n// The Ark parts aren't Chakra components, so they're wrapped with the `chakra()` factory to accept\n// `css`. They're deliberately NOT wrapped with `asChild`: each Ark part falls back to the current\n// step's content (title, description, progress text, action label) only when it renders its own\n// children, and `asChild` would replace those children with the wrapper element.\nconst TourBackdrop = chakra(ArkTour.Backdrop);\nconst TourSpotlight = chakra(ArkTour.Spotlight);\nconst TourPositioner = chakra(ArkTour.Positioner);\nconst TourContent = chakra(ArkTour.Content);\nconst TourArrow = chakra(ArkTour.Arrow);\nconst TourArrowTip = chakra(ArkTour.ArrowTip);\nconst TourTitle = chakra(ArkTour.Title);\nconst TourDescription = chakra(ArkTour.Description);\nconst TourControl = chakra(ArkTour.Control);\nconst TourProgressText = chakra(ArkTour.ProgressText);\n\nconst SecondaryAction = ({ secondaryAction }: { secondaryAction: BitkitTourSecondaryAction }) => {\n  const { action, href, label } = secondaryAction;\n\n  if (href !== undefined) {\n    return (\n      <BitkitButton href={href} size=\"sm\" variant=\"tertiary\">\n        {label}\n      </BitkitButton>\n    );\n  }\n\n  if (!action) return null;\n\n  return (\n    <ArkTour.ActionTrigger asChild action={{ action, label }} aria-label={label}>\n      <BitkitButton size=\"sm\" variant=\"tertiary\">\n        {label}\n      </BitkitButton>\n    </ArkTour.ActionTrigger>\n  );\n};\n\n/**\n * A guided product tour: a step card anchored to an element on the page, with a spotlight cut out\n * of the dimmed backdrop around that element.\n *\n * The steps and the tour behaviour live on the instance — create it with `useBitkitTour` and render\n * `BitkitTour` once, anywhere in the tree. Each step declares its own action buttons; the last one\n * is rendered as the primary button. A single-step tour drops the `1 of n` label, which is what\n * turns the card into the single-feature presentation.\n */\nconst BitkitTour = ({ tour }: BitkitTourProps) => {\n  const recipe = useSlotRecipe({ key: 'tour' });\n  const styles = recipe();\n  const step = tour.step;\n  const actions = step?.actions ?? [];\n\n  return (\n    // `unmountOnExit` isn't only tidiness: Ark's backdrop applies `hidden: !tour.step?.backdrop`\n    // after merging the presence props, which overrides the presence's own `hidden` — and since the\n    // step is kept after the tour closes, the dimming would stay on screen for good. Unmounting on\n    // exit takes the node out before that can happen.\n    // The cast is the price of refining `step` and the step-mutating methods on the instance: our\n    // step type isn't a supertype of Ark's, so the methods no longer match its api signature. The\n    // object is Ark's api — only the types are ours.\n    <ArkTour.Root unmountOnExit tour={tour as UseTourReturn}>\n      <Portal>\n        <TourBackdrop css={styles.backdrop} />\n        <TourSpotlight css={styles.spotlight} />\n        <TourPositioner css={styles.positioner}>\n          <TourContent css={styles.content}>\n            {/* `hidden={false}` overrides Zag, which hides the arrow until the card has been\n                positioned — while Popper computes that position from the arrow's `clientHeight`, so\n                a hidden arrow measures 0 and the card lands 6 short of the design's 12, then drops\n                by that 6 as soon as anything recomputes. Nothing shows in the meantime: until it is\n                positioned the card itself sits off-screen at `-100vh`. */}\n            <TourArrow css={styles.arrow} hidden={false}>\n              <TourArrowTip css={styles.arrowTip} />\n            </TourArrow>\n            <Box css={styles.header}>\n              <Box css={styles.titleGroup}>\n                {tour.totalSteps > 1 ? <TourProgressText css={styles.progressText} /> : null}\n                <Box css={styles.titleRow}>\n                  <TourTitle css={styles.title} />\n                  {step?.badge ? <Box css={styles.badge}>{step.badge}</Box> : null}\n                </Box>\n              </Box>\n              <ArkTour.CloseTrigger asChild>\n                <BitkitCloseButton css={styles.closeTrigger} size=\"xs\" />\n              </ArkTour.CloseTrigger>\n            </Box>\n            <TourDescription css={styles.description} />\n            {step?.content ? <Box css={styles.media}>{step.content}</Box> : null}\n            <TourControl css={styles.control}>\n              {step?.secondaryAction ? <SecondaryAction secondaryAction={step.secondaryAction} /> : null}\n              <Box css={styles.actions}>\n                {actions.map((action, index) => (\n                  // Zag labels the trigger from its own translations (`close tour`, `next step`),\n                  // which would override the visible text as the accessible name — and put two\n                  // `Close tour` buttons on a card whose dismiss action reads `Got it`.\n                  <ArkTour.ActionTrigger key={action.label} asChild action={action} aria-label={action.label}>\n                    <BitkitButton size=\"sm\" variant={index === actions.length - 1 ? 'primary' : 'secondary'}>\n                      {action.label}\n                    </BitkitButton>\n                  </ArkTour.ActionTrigger>\n                ))}\n              </Box>\n            </TourControl>\n          </TourContent>\n        </TourPositioner>\n      </Portal>\n    </ArkTour.Root>\n  );\n};\n\nBitkitTour.displayName = 'BitkitTour';\n\nexport default BitkitTour;\n"],"mappings":";;;;;;;;;;;;;;;AA4FA,IAAa,iBAAiB,YAAmD;CAC/E,MAAM,OAAO,QAAQ;EAKnB,iBAAiB;GAAE,GAAG;GAAG,GAAG;EAAE;EAG9B,iBAAiB;EACjB,GAAG;EAOH,wBAAwB;EAGxB,eAAe,QAAQ;EAIvB,cAAc;GAAE,OAAO;GAAc,GAAG,QAAQ;EAAa;EAE7D,OAAO,QAAQ,MAAM,KAAK,UAAU;GAAE,QAAQ,EAAE,UAAU,EAAE;GAAG,GAAG;GAAM,MAAM;EAAmB,EAAE;CACrG,CAAC;CAKD,MAAM,UAAU,kBAAkB;EAChC,MAAM,oBAAoB,KAAK,qBAAqB,CAAC,CAAC;EAEtD,oBAAoB;CACtB,GAAG,CAAC,IAAI,CAAC;CAET,MAAM,EAAE,SAAS;CACjB,gBAAgB;EACd,IAAI,SAAS,KAAA,KAAa,SAAS,KAAK,MACtC;EAGF,IAAI,MACF,KAAK,MAAM;OAEX,QAAQ;CAKZ,GAAG;EAAC;EAAS;EAAM,KAAK;CAAI,CAAC;CAE7B,OAAO;EAAE,GAAG;EAAM;EAAS,MAAM,KAAK;CAA8B;AACtE;AAMA,IAAM,eAAe,OAAO,KAAQ,QAAQ;AAC5C,IAAM,gBAAgB,OAAO,KAAQ,SAAS;AAC9C,IAAM,iBAAiB,OAAO,KAAQ,UAAU;AAChD,IAAM,cAAc,OAAO,KAAQ,OAAO;AAC1C,IAAM,YAAY,OAAO,KAAQ,KAAK;AACtC,IAAM,eAAe,OAAO,KAAQ,QAAQ;AAC5C,IAAM,YAAY,OAAO,KAAQ,KAAK;AACtC,IAAM,kBAAkB,OAAO,KAAQ,WAAW;AAClD,IAAM,cAAc,OAAO,KAAQ,OAAO;AAC1C,IAAM,mBAAmB,OAAO,KAAQ,YAAY;AAEpD,IAAM,mBAAmB,EAAE,sBAAsE;CAC/F,MAAM,EAAE,QAAQ,MAAM,UAAU;CAEhC,IAAI,SAAS,KAAA,GACX,OACE,oBAAC,cAAD;EAAoB;EAAM,MAAK;EAAK,SAAQ;EACzC,UAAA;CACW,CAAA;CAIlB,IAAI,CAAC,QAAQ,OAAO;CAEpB,OACE,oBAAC,KAAQ,eAAT;EAAuB,SAAA;EAAQ,QAAQ;GAAE;GAAQ;EAAM;EAAG,cAAY;EACpE,UAAA,oBAAC,cAAD;GAAc,MAAK;GAAK,SAAQ;GAC7B,UAAA;EACW,CAAA;CACO,CAAA;AAE3B;;;;;;;;;;AAWA,IAAM,cAAc,EAAE,WAA4B;CAEhD,MAAM,SADS,cAAc,EAAE,KAAK,OAAO,CAC5B,CAAA,CAAO;CACtB,MAAM,OAAO,KAAK;CAClB,MAAM,UAAU,MAAM,WAAW,CAAC;CAElC,OAQE,oBAAC,KAAQ,MAAT;EAAc,eAAA;EAAoB;EAChC,UAAA,qBAAC,QAAD,EAAA,UAAA;GACE,oBAAC,cAAD,EAAc,KAAK,OAAO,SAAW,CAAA;GACrC,oBAAC,eAAD,EAAe,KAAK,OAAO,UAAY,CAAA;GACvC,oBAAC,gBAAD;IAAgB,KAAK,OAAO;IAC1B,UAAA,qBAAC,aAAD;KAAa,KAAK,OAAO;KAAzB,UAAA;MAME,oBAAC,WAAD;OAAW,KAAK,OAAO;OAAO,QAAQ;OACpC,UAAA,oBAAC,cAAD,EAAc,KAAK,OAAO,SAAW,CAAA;MAC5B,CAAA;MACX,qBAAC,KAAD;OAAK,KAAK,OAAO;OAAjB,UAAA,CACE,qBAAC,KAAD;QAAK,KAAK,OAAO;QAAjB,UAAA,CACG,KAAK,aAAa,IAAI,oBAAC,kBAAD,EAAkB,KAAK,OAAO,aAAe,CAAA,IAAI,MACxE,qBAAC,KAAD;SAAK,KAAK,OAAO;SAAjB,UAAA,CACE,oBAAC,WAAD,EAAW,KAAK,OAAO,MAAQ,CAAA,GAC9B,MAAM,QAAQ,oBAAC,KAAD;UAAK,KAAK,OAAO;UAAQ,UAAA,KAAK;SAAW,CAAA,IAAI,IACzD;QACF,CAAA,CAAA;OACL,CAAA,GAAA,oBAAC,KAAQ,cAAT;QAAsB,SAAA;QACpB,UAAA,oBAAC,mBAAD;SAAmB,KAAK,OAAO;SAAc,MAAK;QAAM,CAAA;OACpC,CAAA,CACnB;;MACL,oBAAC,iBAAD,EAAiB,KAAK,OAAO,YAAc,CAAA;MAC1C,MAAM,UAAU,oBAAC,KAAD;OAAK,KAAK,OAAO;OAAQ,UAAA,KAAK;MAAa,CAAA,IAAI;MAChE,qBAAC,aAAD;OAAa,KAAK,OAAO;OAAzB,UAAA,CACG,MAAM,kBAAkB,oBAAC,iBAAD,EAAiB,iBAAiB,KAAK,gBAAkB,CAAA,IAAI,MACtF,oBAAC,KAAD;QAAK,KAAK,OAAO;QACd,UAAA,QAAQ,KAAK,QAAQ,UAIpB,oBAAC,KAAQ,eAAT;SAA0C,SAAA;SAAgB;SAAQ,cAAY,OAAO;SACnF,UAAA,oBAAC,cAAD;UAAc,MAAK;UAAK,SAAS,UAAU,QAAQ,SAAS,IAAI,YAAY;UACzE,UAAA,OAAO;SACI,CAAA;QACO,GAJK,OAAO,KAIZ,CACxB;OACE,CAAA,CACM;;KACF;;GACC,CAAA;EACV,EAAA,CAAA;CACI,CAAA;AAElB;AAEA,WAAW,cAAc"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bitrise/bitkit-v2",
   "private": false,
-  "version": "0.3.356",
+  "version": "0.3.357",
   "description": "Bitrise Design System Components built with Chakra UI V3",
   "keywords": [
     "react",