@glowhop/core-tour 1.3.1 → 1.5.0

package/config/index.js

@@ -12,17 +12,6 @@ function cloneStepProps(props) {
       ...props.popover,
       animation: props.popover.animation && { ...props.popover.animation },
       arrow: props.popover.arrow && { ...props.popover.arrow },
-      keyboardShortcuts: props.popover.keyboardShortcuts && {
-        previous: props.popover.keyboardShortcuts.previous && [
-          ...props.popover.keyboardShortcuts.previous
-        ],
-        advance: props.popover.keyboardShortcuts.advance && [
-          ...props.popover.keyboardShortcuts.advance
-        ],
-        cancel: props.popover.keyboardShortcuts.cancel && [
-          ...props.popover.keyboardShortcuts.cancel
-        ]
-      },
       placementTryOrder: props.popover.placementTryOrder && [...props.popover.placementTryOrder]
     },
     indicator: props.indicator && {
@@ -31,9 +20,29 @@ function cloneStepProps(props) {
       placementTryOrder: props.indicator.placementTryOrder && [
         ...props.indicator.placementTryOrder
       ]
-    }
+    },
+    behavior: props.behavior && {
+      ...props.behavior,
+      missingTarget: props.behavior.missingTarget && { ...props.behavior.missingTarget },
+      scroll: props.behavior.scroll && { ...props.behavior.scroll }
+    },
+    controls: cloneControls(props.controls),
+    classNames: cloneClassNames(props.classNames)
   };
 }
+function cloneControls(controls) {
+  return controls && Object.freeze({
+    previous: cloneControl(controls.previous),
+    advance: cloneControl(controls.advance),
+    cancel: cloneControl(controls.cancel)
+  });
+}
+function cloneControl(control) {
+  return control && Object.freeze({ state: control.state, keys: control.keys && Object.freeze([...control.keys]) });
+}
+function cloneClassNames(classNames) {
+  return classNames && Object.freeze({ ...classNames });
+}
 function freezeStepProps(props) {
   const cloned = cloneStepProps(props);
   if (cloned.data)
@@ -46,14 +55,6 @@ function freezeStepProps(props) {
     Object.freeze(cloned.popover.animation);
   if (cloned.popover?.arrow)
     Object.freeze(cloned.popover.arrow);
-  if (cloned.popover?.keyboardShortcuts?.previous)
-    Object.freeze(cloned.popover.keyboardShortcuts.previous);
-  if (cloned.popover?.keyboardShortcuts?.advance)
-    Object.freeze(cloned.popover.keyboardShortcuts.advance);
-  if (cloned.popover?.keyboardShortcuts?.cancel)
-    Object.freeze(cloned.popover.keyboardShortcuts.cancel);
-  if (cloned.popover?.keyboardShortcuts)
-    Object.freeze(cloned.popover.keyboardShortcuts);
   if (cloned.popover?.placementTryOrder)
     Object.freeze(cloned.popover.placementTryOrder);
   if (cloned.popover)
@@ -64,6 +65,12 @@ function freezeStepProps(props) {
     Object.freeze(cloned.indicator.placementTryOrder);
   if (cloned.indicator)
     Object.freeze(cloned.indicator);
+  if (cloned.behavior?.missingTarget)
+    Object.freeze(cloned.behavior.missingTarget);
+  if (cloned.behavior?.scroll)
+    Object.freeze(cloned.behavior.scroll);
+  if (cloned.behavior)
+    Object.freeze(cloned.behavior);
   return Object.freeze(cloned);
 }
 // packages/core/src/definition/workflow-definition.ts
@@ -84,11 +91,6 @@ function freezePopover(options) {
     ...options,
     animation: freezeAnimation(options.animation),
     arrow: options.arrow && freezeRecord({ ...options.arrow }),
-    keyboardShortcuts: options.keyboardShortcuts && freezeRecord({
-      previous: options.keyboardShortcuts.previous && freezeRecord([...options.keyboardShortcuts.previous]),
-      advance: options.keyboardShortcuts.advance && freezeRecord([...options.keyboardShortcuts.advance]),
-      cancel: options.keyboardShortcuts.cancel && freezeRecord([...options.keyboardShortcuts.cancel])
-    }),
     placementTryOrder: options.placementTryOrder && freezeRecord([...options.placementTryOrder])
   });
 }
@@ -103,17 +105,11 @@ function freezeStep(draft) {
   return freezeRecord({
     id: draft.id,
     target: draft.target,
-    resetPropsOnEnter: draft.resetPropsOnEnter,
     props: freezeStepProps(draft.props),
-    behavior: draft.behavior && freezeRecord({
-      ...draft.behavior,
-      scroll: draft.behavior.scroll && freezeRecord({ ...draft.behavior.scroll })
-    }),
     actions: freezeRecord(draft.actions.map((action) => action)),
-    eventHandlers: freezeRecord(draft.eventHandlers.map((handler) => freezeRecord({ ...handler }))),
-    advanceAction: draft.advanceAction,
-    previousAction: draft.previousAction,
-    cancelAction: draft.cancelAction
+    targetEvents: freezeRecord(draft.targetEvents.map((handler) => freezeRecord({ ...handler }))),
+    beforeEnter: draft.beforeEnter,
+    beforeLeave: draft.beforeLeave
   });
 }
 function freezeOptions(options) {
@@ -122,8 +118,11 @@ function freezeOptions(options) {
     overlay: freezeOverlay(options.overlay),
     popover: freezePopover(options.popover),
     indicator: freezeIndicator(options.indicator),
+    classNames: cloneClassNames(options.classNames),
+    controls: cloneControls(options.controls),
     behavior: options.behavior && freezeRecord({
       ...options.behavior,
+      missingTarget: options.behavior.missingTarget && freezeRecord({ ...options.behavior.missingTarget }),
       scroll: options.behavior.scroll && freezeRecord({ ...options.behavior.scroll })
     })
   });
@@ -133,7 +132,7 @@ function cloneWorkflowStepDraft(definition) {
     ...definition,
     props: cloneStepProps(definition.props),
     actions: definition.actions.map((action) => action),
-    eventHandlers: [...definition.eventHandlers]
+    targetEvents: [...definition.targetEvents]
   };
 }
 function assertUniqueStepIds(name, drafts) {
@@ -246,21 +245,21 @@ class WorkflowBuilder {
     this.currentStep = new WorkflowStepBuilder(this, {
       id: options.id,
       target: options.target,
-      resetPropsOnEnter: options.resetPropsOnEnter,
       props: {
         title: options.title,
         content: options.content,
         data: cloneStepProps(options).data,
         overlay: options.overlay,
         popover: options.popover,
-        indicator: options.indicator
+        indicator: options.indicator,
+        behavior: options.behavior,
+        controls: options.controls,
+        classNames: options.classNames
       },
-      behavior: options.behavior,
       actions: [],
-      eventHandlers: [],
-      advanceAction: null,
-      previousAction: null,
-      cancelAction: null
+      targetEvents: [],
+      beforeEnter: null,
+      beforeLeave: null
     });
     return this.currentStep;
   }
@@ -364,19 +363,14 @@ class WorkflowStepBuilder {
     this.draft.actions.push(callback);
     return this;
   }
-  beforeAdvance(callback) {
+  beforeEnter(callback) {
     this.assertActive();
-    this.draft.advanceAction = callback;
+    this.draft.beforeEnter = callback;
     return this;
   }
-  beforePrevious(callback) {
+  beforeLeave(callback) {
     this.assertActive();
-    this.draft.previousAction = callback;
-    return this;
-  }
-  beforeCancel(callback) {
-    this.assertActive();
-    this.draft.cancelAction = callback;
+    this.draft.beforeLeave = callback;
     return this;
   }
   onTargetEvent(eventOrEvents, callback) {
@@ -387,7 +381,7 @@ class WorkflowStepBuilder {
     for (const event of events) {
       if (event.length === 0)
         throw new TypeError("event name must not be empty");
-      this.draft.eventHandlers.push({
+      this.draft.targetEvents.push({
         event,
         callback
       });
@@ -419,14 +413,15 @@ ${summary}`);
 
 // packages/core/src/config/validate.ts
 var TOP_LEVEL_KEYS = [
+  "version",
   "name",
-  "cancellable",
-  "allowScroll",
   "overlay",
   "popover",
   "indicator",
   "animated",
   "behavior",
+  "controls",
+  "classNames",
   "onStart",
   "onCancel",
   "onFinish",
@@ -435,58 +430,58 @@ var TOP_LEVEL_KEYS = [
 var STEP_KEYS = [
   "id",
   "target",
-  "resetPropsOnEnter",
   "overlay",
   "popover",
   "indicator",
   "behavior",
+  "controls",
+  "classNames",
   "title",
   "content",
   "data",
   "actions",
-  "eventHandlers",
-  "advanceAction",
-  "previousAction",
-  "cancelAction"
+  "targetEvents",
+  "beforeEnter",
+  "beforeLeave"
 ];
 var EVENT_HANDLER_KEYS = ["event", "action"];
 var ANIMATION_KEYS = ["duration", "easing"];
 var OVERLAY_KEYS = ["animated", "animation", "color", "opacity", "padding", "radius"];
-var INDICATOR_KEYS = ["animated", "animation", "disabled", "gap", "placementTryOrder"];
-var POPOVER_KEYS = [
-  "animated",
-  "animation",
-  "placementTryOrder",
-  "arrow",
-  "hideFooter",
-  "disablePreviousButton",
-  "hidePreviousButton",
-  "disableAdvanceButton",
-  "hideAdvanceButton",
-  "gap",
-  "keyboardShortcuts"
+var INDICATOR_KEYS = ["animated", "animation", "hidden", "gap", "placementTryOrder"];
+var POPOVER_KEYS = ["animated", "animation", "placementTryOrder", "arrow", "gap"];
+var CONTROL_KEYS = ["advance", "previous", "cancel"];
+var CONTROL_FIELD_KEYS = ["state", "keys"];
+var CLASS_NAME_KEYS = [
+  "overlay",
+  "popover",
+  "pointer",
+  "header",
+  "content",
+  "footer",
+  ...CONTROL_KEYS
 ];
 var POPOVER_ARROW_KEYS = [
-  "disabled",
+  "hidden",
   "color",
   "size",
   "borderWidth",
   "borderRadius",
   "edgePadding",
   "styleNonce",
-  "disableAutoStyles"
+  "autoStyles"
 ];
-var KEYBOARD_SHORTCUT_KEYS = ["previous", "advance", "cancel"];
+var MISSING_TARGET_KEYS = ["strategy", "timeout"];
 var BEHAVIOR_KEYS = [
   "allowInteraction",
-  "disableAutoFocus",
-  "disableAutoScroll",
-  "missingTargetStrategy",
+  "allowScroll",
+  "autoFocus",
+  "autoScroll",
+  "missingTarget",
   "scroll",
-  "targetTimeout",
   "overlayClick"
 ];
-var SCROLL_KEYS = ["behavior", "block", "inline"];
+var SCROLL_KEYS = ["behavior", "block", "inline", "returnDelay"];
+var CONFIG_VERSION = "1.1";
 var BUILTIN_ACTION_KEYS = {
   wait: ["type", "ms"],
   waitUntilElement: ["type", "selector", "interval", "timeout"],
@@ -513,16 +508,19 @@ function validateWorkflowConfigShape(value, issues, validateContent) {
     return;
   }
   assertNoUnknownKeys(value, TOP_LEVEL_KEYS, "", issues);
+  if (value.version !== CONFIG_VERSION) {
+    issues.push({ path: "version", message: `version must be "${CONFIG_VERSION}"` });
+  }
   if (typeof value.name !== "string" || value.name.length === 0) {
     issues.push({ path: "name", message: "name must be a non-empty string" });
   }
-  validateOptionalBoolean("cancellable", value.cancellable, issues);
-  validateOptionalBoolean("allowScroll", value.allowScroll, issues);
   validateOptionalBoolean("animated", value.animated, issues);
   validateOverlayShape("overlay", value.overlay, issues);
   validatePopoverShape("popover", value.popover, issues);
   validateIndicatorShape("indicator", value.indicator, issues);
   validateBehaviorShape("behavior", value.behavior, issues);
+  validateControlsShape("controls", value.controls, issues);
+  validateClassNamesShape("classNames", value.classNames, issues);
   validateLifecycleActionRefShape("onStart", value.onStart, issues);
   validateLifecycleActionRefShape("onCancel", value.onCancel, issues);
   validateLifecycleActionRefShape("onFinish", value.onFinish, issues);
@@ -564,17 +562,18 @@ function validateStepConfigShape(value, path, issues, validateContent) {
       message: "target must be a non-empty CSS selector string"
     });
   }
-  const titleError = validateContent(value.title, `${path}.title`);
+  const titleError = value.title === undefined ? null : validateContent(value.title, `${path}.title`);
   if (titleError)
     issues.push({ path: `${path}.title`, message: titleError });
   const contentError = validateContent(value.content, `${path}.content`);
   if (contentError)
     issues.push({ path: `${path}.content`, message: contentError });
-  validateOptionalBoolean(`${path}.resetPropsOnEnter`, value.resetPropsOnEnter, issues);
   validateOverlayShape(`${path}.overlay`, value.overlay, issues);
   validatePopoverShape(`${path}.popover`, value.popover, issues);
   validateIndicatorShape(`${path}.indicator`, value.indicator, issues);
   validateBehaviorShape(`${path}.behavior`, value.behavior, issues);
+  validateControlsShape(`${path}.controls`, value.controls, issues);
+  validateClassNamesShape(`${path}.classNames`, value.classNames, issues);
   validateDataShape(`${path}.data`, value.data, issues);
   if (value.actions !== undefined) {
     if (!Array.isArray(value.actions)) {
@@ -585,22 +584,21 @@ function validateStepConfigShape(value, path, issues, validateContent) {
       }
     }
   }
-  if (value.eventHandlers !== undefined) {
-    if (!Array.isArray(value.eventHandlers)) {
-      issues.push({ path: `${path}.eventHandlers`, message: "eventHandlers must be an array" });
+  if (value.targetEvents !== undefined) {
+    if (!Array.isArray(value.targetEvents)) {
+      issues.push({ path: `${path}.targetEvents`, message: "targetEvents must be an array" });
     } else {
-      for (const [index, handler] of value.eventHandlers.entries()) {
-        validateEventHandlerConfigShape(handler, `${path}.eventHandlers[${index}]`, issues);
+      for (const [index, handler] of value.targetEvents.entries()) {
+        validateTargetEventConfigShape(handler, `${path}.targetEvents[${index}]`, issues);
       }
     }
   }
-  validateTransitionActionRefShape(`${path}.advanceAction`, value.advanceAction, issues);
-  validateTransitionActionRefShape(`${path}.previousAction`, value.previousAction, issues);
-  validateTransitionActionRefShape(`${path}.cancelAction`, value.cancelAction, issues);
+  validateHookActionRefShape(`${path}.beforeEnter`, value.beforeEnter, issues);
+  validateHookActionRefShape(`${path}.beforeLeave`, value.beforeLeave, issues);
 }
-function validateEventHandlerConfigShape(value, path, issues) {
+function validateTargetEventConfigShape(value, path, issues) {
   if (!isPlainObject(value)) {
-    issues.push({ path, message: "Event handler must be a plain object" });
+    issues.push({ path, message: "Target event must be a plain object" });
     return;
   }
   assertNoUnknownKeys(value, EVENT_HANDLER_KEYS, path, issues);
@@ -626,7 +624,7 @@ function validateStepActionRefShape(value, path, issues) {
     message: 'must be a function, or a built-in action object with a known "type"'
   });
 }
-function validateTransitionActionRefShape(path, value, issues) {
+function validateHookActionRefShape(path, value, issues) {
   if (value === undefined)
     return;
   if (typeof value === "function")
@@ -637,7 +635,7 @@ function validateTransitionActionRefShape(path, value, issues) {
   });
 }
 function validateLifecycleActionRefShape(path, value, issues) {
-  validateTransitionActionRefShape(path, value, issues);
+  validateHookActionRefShape(path, value, issues);
 }
 function validateBuiltinActionShape(value, path, issues) {
   const type = value.type;
@@ -746,7 +744,7 @@ function validateIndicatorShape(path, value, issues) {
   }
   assertNoUnknownKeys(value, INDICATOR_KEYS, path, issues);
   validateBaseOptionsShape(path, value, issues);
-  validateOptionalBoolean(`${path}.disabled`, value.disabled, issues);
+  validateOptionalBoolean(`${path}.hidden`, value.hidden, issues);
   validateOptionalFiniteNonNegative(`${path}.gap`, value.gap, issues);
   validateOptionalStringArray(`${path}.placementTryOrder`, value.placementTryOrder, issues, [
     "top",
@@ -763,26 +761,14 @@ function validatePopoverArrowShape(path, value, issues) {
     return;
   }
   assertNoUnknownKeys(value, POPOVER_ARROW_KEYS, path, issues);
-  validateOptionalBoolean(`${path}.disabled`, value.disabled, issues);
+  validateOptionalBoolean(`${path}.hidden`, value.hidden, issues);
   validateOptionalString(`${path}.color`, value.color, issues);
   validateOptionalFiniteNonNegative(`${path}.size`, value.size, issues);
   validateOptionalFiniteNonNegative(`${path}.borderWidth`, value.borderWidth, issues);
   validateOptionalFiniteNonNegative(`${path}.borderRadius`, value.borderRadius, issues);
   validateOptionalFiniteNonNegative(`${path}.edgePadding`, value.edgePadding, issues);
   validateOptionalString(`${path}.styleNonce`, value.styleNonce, issues);
-  validateOptionalBoolean(`${path}.disableAutoStyles`, value.disableAutoStyles, issues);
-}
-function validateKeyboardShortcutsShape(path, value, issues) {
-  if (value === undefined)
-    return;
-  if (!isPlainObject(value)) {
-    issues.push({ path, message: "must be an object" });
-    return;
-  }
-  assertNoUnknownKeys(value, KEYBOARD_SHORTCUT_KEYS, path, issues);
-  for (const key of KEYBOARD_SHORTCUT_KEYS) {
-    validateOptionalStringArray(`${path}.${key}`, value[key], issues);
-  }
+  validateOptionalBoolean(`${path}.autoStyles`, value.autoStyles, issues);
 }
 function validatePopoverShape(path, value, issues) {
   if (value === undefined)
@@ -800,13 +786,55 @@ function validatePopoverShape(path, value, issues) {
     "right"
   ]);
   validatePopoverArrowShape(`${path}.arrow`, value.arrow, issues);
-  validateOptionalBoolean(`${path}.hideFooter`, value.hideFooter, issues);
-  validateOptionalBoolean(`${path}.disablePreviousButton`, value.disablePreviousButton, issues);
-  validateOptionalBoolean(`${path}.hidePreviousButton`, value.hidePreviousButton, issues);
-  validateOptionalBoolean(`${path}.disableAdvanceButton`, value.disableAdvanceButton, issues);
-  validateOptionalBoolean(`${path}.hideAdvanceButton`, value.hideAdvanceButton, issues);
   validateOptionalFiniteNonNegative(`${path}.gap`, value.gap, issues);
-  validateKeyboardShortcutsShape(`${path}.keyboardShortcuts`, value.keyboardShortcuts, issues);
+}
+function validateClassNamesShape(path, value, issues) {
+  if (value === undefined)
+    return;
+  if (!isPlainObject(value)) {
+    issues.push({ path, message: "must be an object" });
+    return;
+  }
+  assertNoUnknownKeys(value, CLASS_NAME_KEYS, path, issues);
+  for (const key of CLASS_NAME_KEYS) {
+    if (typeof value[key] !== "string") {
+      validateOptionalStringArray(`${path}.${key}`, value[key], issues);
+    }
+  }
+}
+function validateControlsShape(path, value, issues) {
+  if (value === undefined)
+    return;
+  if (!isPlainObject(value)) {
+    issues.push({ path, message: "must be an object" });
+    return;
+  }
+  assertNoUnknownKeys(value, CONTROL_KEYS, path, issues);
+  for (const key of CONTROL_KEYS) {
+    validateControlShape(`${path}.${key}`, value[key], issues);
+  }
+}
+function validateControlShape(path, value, issues) {
+  if (value === undefined)
+    return;
+  if (!isPlainObject(value)) {
+    issues.push({ path, message: "must be an object" });
+    return;
+  }
+  assertNoUnknownKeys(value, CONTROL_FIELD_KEYS, path, issues);
+  validateOptionalEnum(`${path}.state`, value.state, ["enabled", "disabled"], issues);
+  validateOptionalStringArray(`${path}.keys`, value.keys, issues);
+}
+function validateMissingTargetShape(path, value, issues) {
+  if (value === undefined)
+    return;
+  if (!isPlainObject(value)) {
+    issues.push({ path, message: "must be an object" });
+    return;
+  }
+  assertNoUnknownKeys(value, MISSING_TARGET_KEYS, path, issues);
+  validateOptionalEnum(`${path}.strategy`, value.strategy, ["wait", "skip", "error", "detached"], issues);
+  validateOptionalFiniteNonNegative(`${path}.timeout`, value.timeout, issues);
 }
 function validateScrollShape(path, value, issues) {
   if (value === undefined)
@@ -819,6 +847,8 @@ function validateScrollShape(path, value, issues) {
   validateOptionalEnum(`${path}.behavior`, value.behavior, ["auto", "smooth"], issues);
   validateOptionalEnum(`${path}.block`, value.block, ["start", "center", "end", "nearest"], issues);
   validateOptionalEnum(`${path}.inline`, value.inline, ["start", "center", "end", "nearest"], issues);
+  if (value.returnDelay !== false)
+    validateOptionalFiniteNonNegative(`${path}.returnDelay`, value.returnDelay, issues);
 }
 function validateBehaviorShape(path, value, issues) {
   if (value === undefined)
@@ -829,11 +859,11 @@ function validateBehaviorShape(path, value, issues) {
   }
   assertNoUnknownKeys(value, BEHAVIOR_KEYS, path, issues);
   validateOptionalBoolean(`${path}.allowInteraction`, value.allowInteraction, issues);
-  validateOptionalBoolean(`${path}.disableAutoFocus`, value.disableAutoFocus, issues);
-  validateOptionalBoolean(`${path}.disableAutoScroll`, value.disableAutoScroll, issues);
-  validateOptionalEnum(`${path}.missingTargetStrategy`, value.missingTargetStrategy, ["wait", "skip", "error"], issues);
+  validateOptionalBoolean(`${path}.allowScroll`, value.allowScroll, issues);
+  validateOptionalBoolean(`${path}.autoFocus`, value.autoFocus, issues);
+  validateOptionalBoolean(`${path}.autoScroll`, value.autoScroll, issues);
+  validateMissingTargetShape(`${path}.missingTarget`, value.missingTarget, issues);
   validateScrollShape(`${path}.scroll`, value.scroll, issues);
-  validateOptionalFiniteNonNegative(`${path}.targetTimeout`, value.targetTimeout, issues);
   validateOptionalEnum(`${path}.overlayClick`, value.overlayClick, ["none", "advance", "cancel"], issues);
 }
 function validateDataShape(path, value, issues) {
@@ -865,13 +895,13 @@ function assertNoUnknownKeys(value, allowedKeys, path, issues) {
 function createWorkflowFromConfig(config, options = {}) {
   const validated = validateWorkflowConfig(config, options);
   const builder = new WorkflowBuilder(validated.name, {
-    cancellable: validated.cancellable,
-    allowScroll: validated.allowScroll,
     overlay: validated.overlay,
     popover: validated.popover,
     indicator: validated.indicator,
     animated: validated.animated,
     behavior: validated.behavior,
+    controls: validated.controls,
+    classNames: validated.classNames,
     onStart: validated.onStart,
     onCancel: validated.onCancel,
     onFinish: validated.onFinish
@@ -886,11 +916,12 @@ function applyStepConfig(builder, stepConfig, path) {
   const step = builder.step({
     id: stepConfig.id,
     target: stepConfig.target,
-    resetPropsOnEnter: stepConfig.resetPropsOnEnter,
     overlay: stepConfig.overlay,
     popover: stepConfig.popover,
     indicator: stepConfig.indicator,
     behavior: stepConfig.behavior,
+    controls: stepConfig.controls,
+    classNames: stepConfig.classNames,
     title: stepConfig.title,
     content: stepConfig.content,
     data: stepConfig.data
@@ -898,15 +929,13 @@ function applyStepConfig(builder, stepConfig, path) {
   for (const [index, actionRef] of (stepConfig.actions ?? []).entries()) {
     applyStepActionRef(step, actionRef, `${path}.actions[${index}]`);
   }
-  for (const [index, handler] of (stepConfig.eventHandlers ?? []).entries()) {
-    applyEventHandler(step, handler, `${path}.eventHandlers[${index}]`);
+  for (const [index, handler] of (stepConfig.targetEvents ?? []).entries()) {
+    applyTargetEvent(step, handler, `${path}.targetEvents[${index}]`);
   }
-  if (stepConfig.advanceAction)
-    step.beforeAdvance(stepConfig.advanceAction);
-  if (stepConfig.previousAction)
-    step.beforePrevious(stepConfig.previousAction);
-  if (stepConfig.cancelAction)
-    step.beforeCancel(stepConfig.cancelAction);
+  if (stepConfig.beforeEnter)
+    step.beforeEnter(stepConfig.beforeEnter);
+  if (stepConfig.beforeLeave)
+    step.beforeLeave(stepConfig.beforeLeave);
 }
 function applyStepActionRef(step, ref, path) {
   if (typeof ref === "function") {
@@ -936,8 +965,8 @@ function applyBuiltinAction(step, builtin, path) {
       throw new Error(`Unknown built-in action type at ${path}`);
   }
 }
-function applyEventHandler(step, handler, path) {
-  const action = resolveEventHandlerAction(handler.action, `${path}.action`);
+function applyTargetEvent(step, handler, path) {
+  const action = resolveTargetEventAction(handler.action, `${path}.action`);
   const events = typeof handler.event === "string" ? [handler.event] : handler.event;
   for (const event of events) {
     step.onTargetEvent(event, async (_event, context) => {
@@ -945,7 +974,7 @@ function applyEventHandler(step, handler, path) {
     });
   }
 }
-function resolveEventHandlerAction(ref, path) {
+function resolveTargetEventAction(ref, path) {
   if (typeof ref === "function")
     return ref;
   const scratch = new WorkflowBuilder("__config_event_handler_scratch__");

package/config/types.d.ts

@@ -1,5 +1,5 @@
 import type { WorkflowDefinition } from "../definition";
-import type { IndicatorOptions, LifecycleHookContext, OverlayOptions, PopoverOptions, PrimitiveValue, StepAction, StepBehavior, StepTransitionAction } from "../types";
+import type { IndicatorOptions, LifecycleHookContext, OverlayOptions, PopoverOptions, PrimitiveValue, StepAction, StepBehavior, StepHookAction, TourClassNames, TourControls } from "../types";
 /**
  * A tour-level lifecycle hook callback (`onStart`, `onCancel`, `onFinish`), generic over the
  * config's content type `T` (defaults to `string`, the untrusted-JSON case).
@@ -42,23 +42,23 @@ export type BuiltinAction = {
  *   builder verb.
  * - anything else is a validation error.
  *
- * Used for `actions[]` and `eventHandlers[].action`, which both run against a full `StepContext`
+ * Used for `actions[]` and `targetEvents[].action`, which both run against a full `StepContext`
  * (`target`, `signal`, navigation methods) — the same context `BuiltinAction`'s verbs assume, so
  * builtins are valid here.
  */
 export type StepActionRef<T = string> = BuiltinAction | StepAction<T>;
 /**
- * A reference to a transition hook (`advanceAction`/`previousAction`/`cancelAction`).
+ * A reference to a step hook (`beforeEnter`/`beforeLeave`).
  *
- * `BeforeActionStepContext` has a `target` but no `signal`/navigation methods, which the
- * `BuiltinAction` verbs (`wait`, `waitUntilElement`, `clickTarget`, `focusTarget`) all need — none
- * of them can run in this slot. With no registry to fall back on, a transition hook is therefore
- * only expressible as a same-runtime JS function, never as plain JSON. This is a plain function
- * type (not a union) precisely because there is nothing else valid to put here.
+ * Step hooks run while a transition is in progress. The `BuiltinAction` verbs describe a step's
+ * own action sequence (`wait` would stall the transition, `clickTarget` would act on a step that
+ * is not shown yet or is being left), so they are not accepted here. With no registry to fall back
+ * on, a step hook is only expressible as a same-runtime JS function, never as plain JSON. This is a
+ * plain function type (not a union) precisely because there is nothing else valid to put here.
  */
-export type TransitionActionRef<T = string> = StepTransitionAction<T>;
+export type StepHookActionRef<T = string> = StepHookAction<T>;
 /** JSON config form of a single `onTargetEvent` registration. */
-export interface EventHandlerConfig<T = string> {
+export interface TargetEventConfig<T = string> {
     /** Event name, or multiple event names sharing the same action. */
     readonly event: string | readonly string[];
     readonly action: StepActionRef<T>;
@@ -75,19 +75,23 @@ export interface StepConfig<T = string> {
     readonly id: string;
     /** CSS selector for the step's target. Functions and `HTMLElement` are not supported in config form. */
     readonly target: string;
-    readonly resetPropsOnEnter?: boolean;
     readonly overlay?: OverlayOptions;
     readonly popover?: PopoverOptions;
     readonly indicator?: IndicatorOptions;
     readonly behavior?: StepBehavior;
-    readonly title: T;
+    /** Navigation controls for this step, overriding the workflow ones field by field. */
+    readonly controls?: TourControls;
+    /** Classes added to the tour components on this step, overriding the workflow ones per component. */
+    readonly classNames?: TourClassNames;
+    readonly title?: T;
     readonly content: T;
     readonly data?: Record<string, PrimitiveValue>;
     readonly actions?: readonly StepActionRef<T>[];
-    readonly eventHandlers?: readonly EventHandlerConfig<T>[];
-    readonly advanceAction?: TransitionActionRef<T>;
-    readonly previousAction?: TransitionActionRef<T>;
-    readonly cancelAction?: TransitionActionRef<T>;
+    readonly targetEvents?: readonly TargetEventConfig<T>[];
+    /** Runs after the target is resolved and before the step is shown. Mirrors `beforeEnter`. */
+    readonly beforeEnter?: StepHookActionRef<T>;
+    /** Runs before navigating away from the step, never on cancel. Mirrors `beforeLeave`. */
+    readonly beforeLeave?: StepHookActionRef<T>;
 }
 /**
  * A complete, JSON-serializable tour definition.
@@ -96,14 +100,18 @@ export interface StepConfig<T = string> {
  * and same-runtime configs carrying framework content (`ReactNode`, `VNode`, `JSX.Element`, ...).
  */
 export interface WorkflowConfig<T = string> {
+    /** Version of the config format, required. It does not follow the package version. */
+    readonly version: "1.1";
     readonly name: string;
-    readonly cancellable?: boolean;
-    readonly allowScroll?: boolean;
     readonly overlay?: OverlayOptions;
     readonly popover?: PopoverOptions;
     readonly indicator?: IndicatorOptions;
     readonly animated?: boolean;
     readonly behavior?: StepBehavior;
+    /** Navigation controls for every step. */
+    readonly controls?: TourControls;
+    /** Classes added to the tour components on every step. */
+    readonly classNames?: TourClassNames;
     readonly onStart?: LifecycleActionRef<T>;
     readonly onCancel?: LifecycleActionRef<T>;
     readonly onFinish?: LifecycleActionRef<T>;
@@ -111,7 +119,7 @@ export interface WorkflowConfig<T = string> {
 }
 /** A single validation failure, with a path pointing at the offending config field. */
 export interface ConfigValidationIssue {
-    /** Path into the config, e.g. `steps[2].eventHandlers[0].action`. */
+    /** Path into the config, e.g. `steps[2].targetEvents[0].action`. */
     readonly path: string;
     readonly message: string;
 }