@glowhop/core-tour 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @glowhop/core-tour
+
+## 1.0.0
+
+### Major Changes
+
+- e6da5bf: GlowTour.js V.1.0.0 release

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Glowhop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,50 @@
+# @glowhop/core-tour
+
+ESM-only, framework-agnostic workflow controller and DOM driver. Core owns workflow state, navigation, target resolution, and DOM-level tour behavior; adapters provide component rendering and composition. Connecting a root succeeds without a popover; running a non-empty workflow fails if the root or popover is missing. The adapter-author entry point is [`@glowhop/core-tour/adapter`](https://github.com/Glowhop/GlowTour.js/blob/main/packages/core/src/adapter.ts).
+
+Compatibility: framework-independent ESM package. Core provides no SSR-rendered UI; hydration is not applicable to Core itself.
+
+<!-- glow-tour:snippet core-workflow -->
+```ts
+import { createGlowTour } from "@glowhop/core-tour";
+
+const tour = createGlowTour();
+const workflow = tour.create("intro").step({ id: "welcome", target: "#welcome", title: "Welcome", content: "Hello." }).build();
+// Pass tour to a mounted adapter/default composition, then call:
+// await tour.run(workflow);
+```
+
+## Builder and controller
+
+`createGlowTour<T>(options?: GlowTourOptions)` returns a controller. `tour.create(name, options)` returns a builder; call `.step(...)`, then `.build()` to obtain an immutable workflow. Targets may be a selector, an `HTMLElement`, or a resolver `(context) => HTMLElement | null | Promise<HTMLElement | null>`.
+
+| Capability | API | Notes |
+| --- | --- | --- |
+| Placement | `popover.placementTryOrder`, `indicator.placementTryOrder` | Try `top`, `bottom`, `left`, `right`; the resolved position may be `center`. |
+| Interaction | `behavior.allowInteraction` | Allows pointer interaction through the overlay. |
+| Scroll | step/start `scroll` | Uses `behavior`, `block`, and `inline` scroll options. |
+| Callbacks | `onStart`, `onCancel`, `onFinish`; `beforeAdvance`, `beforePrevious`, `beforeCancel` | Start callbacks are workflow options; transition callbacks are step builder methods. |
+| Actions | `.do(fn)`, `.wait(ms)`, `.waitUntil(fn)`, `.waitUntilElement(selector)` | `waitUntil` defaults to a 16 ms interval and 3000 ms timeout. |
+| Target events | `.onTargetEvent("click", fn)` | Handlers receive the event and step context. |
+
+`tour.state.get()` returns status, current step, navigation capabilities, and errors; `tour.state.subscribe(listener)` observes changes. The controller exposes `run`, `advance`, `previous`, `goToStep`, and `cancel`. A new run or navigation cancels the previous operation; `dispose()` cancels pending work, releases the root, and makes the controller unusable.
+
+## Errors and rendering fallbacks
+
+Pass `onSubscriberError(error)` in `GlowTourOptions` to observe failures from state and step-props subscribers:
+
+```ts
+import { createGlowTour } from "@glowhop/core-tour";
+
+const tour = createGlowTour({
+  onSubscriberError(error) {
+    console.error("Tour subscriber failed", error);
+  },
+});
+```
+
+Subscriber failures are isolated and normalized to `Error`; they do not fail the tour transition. If `onSubscriberError` throws or returns a rejected promise, that failure is reported asynchronously outside the transition.
+
+Web Animations are optional. When the capability is missing or unsupported, Core applies the final DOM state immediately and continues without animation.
+
+A failure from a mounted rendering layer is fatal: the command rejects, and the next published state has `status === "error"` with the failure in `state.error`. Core does not publish `active` for the failed step.

package/adapter.d.ts

@@ -0,0 +1,35 @@
+import { type CssStyleRecord, OVERLAY_IDLE_ATTRIBUTES, OVERLAY_IDLE_STYLE, OVERLAY_PATH_IDLE_ATTRIBUTES, POINTER_IDLE_ATTRIBUTES, POINTER_IDLE_STYLE, POPOVER_IDLE_ATTRIBUTES, POPOVER_IDLE_STYLE, styleRecordToCamelCase, styleRecordToCssText } from "./elements/idle-presentation";
+import { type AdapterRootBinding, type AdapterRootIds } from "./runtime/adapter-contract";
+import type { GlowTour } from "./types";
+export type { AdapterRootBinding, AdapterRootIds, CssStyleRecord };
+/**
+ * The idle (pre-bind / server-rendered) presentation for tour elements.
+ *
+ * Framework adapters render these directly into their markup so the popover,
+ * pointer and overlay are out of flow and invisible before a tour's runtime
+ * ever touches the DOM — on the server, and in the window between hydration
+ * and an adapter binding its elements. `initializeProps()` on the
+ * corresponding core element classes applies the same constants
+ * imperatively, so rendered markup and runtime application can never drift.
+ *
+ * Excludes the overlay's `viewBox`, which depends on the live viewport and
+ * can only be computed once the element exists in a real DOM.
+ */
+export { OVERLAY_IDLE_ATTRIBUTES, OVERLAY_IDLE_STYLE, OVERLAY_PATH_IDLE_ATTRIBUTES, POINTER_IDLE_ATTRIBUTES, POINTER_IDLE_STYLE, POPOVER_IDLE_ATTRIBUTES, POPOVER_IDLE_STYLE, styleRecordToCamelCase, styleRecordToCssText, };
+/**
+ * Connects a GlowTour.js instance to a DOM root element.
+ *
+ * Framework adapters call this to initialize tour UI bindings. It must be called
+ * with a valid GlowTour instance created via createGlowTour.
+ *
+ * @param tour The GlowTour instance.
+ * @param options Configuration for the adapter root binding.
+ * @param options.root The DOM element where tour UI will be rendered.
+ * @param options.idPrefix Optional prefix for internal element IDs.
+ * @returns The adapter root binding for managing the tour UI.
+ * @throws Throws if the tour is not a valid GlowTour instance.
+ */
+export declare function connectGlowTourRoot<T>(tour: GlowTour<T>, options: {
+    readonly idPrefix?: string;
+    readonly root: HTMLElement;
+}): AdapterRootBinding;

package/adapter.js

@@ -0,0 +1,84 @@
+// packages/core/src/elements/idle-presentation.ts
+var OVERLAY_IDLE_STYLE = {
+  "clip-rule": "evenodd",
+  "fill-rule": "evenodd",
+  height: "100%",
+  left: "0px",
+  "pointer-events": "none",
+  position: "fixed",
+  "stroke-linejoin": "round",
+  "stroke-miterlimit": "2",
+  top: "0px",
+  width: "100%",
+  "z-index": "10000"
+};
+var OVERLAY_IDLE_ATTRIBUTES = {
+  "aria-hidden": "true",
+  "data-glow-tour-allow-interaction": "false",
+  inert: "true"
+};
+var OVERLAY_PATH_IDLE_ATTRIBUTES = {
+  cursor: "auto",
+  opacity: "0",
+  "pointer-events": "auto"
+};
+var POINTER_IDLE_STYLE = {
+  left: "0px",
+  opacity: "0",
+  "pointer-events": "none",
+  position: "fixed",
+  top: "0px",
+  "will-change": "top, left, transform, opacity",
+  "z-index": "10002"
+};
+var POINTER_IDLE_ATTRIBUTES = {
+  "aria-hidden": "true"
+};
+var POPOVER_IDLE_STYLE = {
+  left: "0px",
+  opacity: "0",
+  position: "fixed",
+  top: "0px",
+  "transform-origin": "center center",
+  "z-index": "10001"
+};
+var POPOVER_IDLE_ATTRIBUTES = {
+  "aria-hidden": "true",
+  inert: "true",
+  tabindex: "-1"
+};
+function styleRecordToCssText(style) {
+  return Object.entries(style).map(([property, value]) => `${property}: ${value};`).join(" ");
+}
+function styleRecordToCamelCase(style) {
+  const result = {};
+  for (const [property, value] of Object.entries(style)) {
+    result[property.replace(/-([a-z0-9])/g, (_match, char) => char.toUpperCase())] = value;
+  }
+  return result;
+}
+
+// packages/core/src/runtime/adapter-contract.ts
+var ADAPTER_BRIDGE_SYMBOL = Symbol.for("@glowhop/core-tour/adapter-bridge/v1");
+var ADAPTER_BRIDGE_VERSION = 1;
+
+// packages/core/src/adapter.ts
+function connectGlowTourRoot(tour, options) {
+  const bridge = Reflect.get(tour, ADAPTER_BRIDGE_SYMBOL);
+  if (typeof bridge !== "object" || bridge === null || Reflect.get(bridge, "version") !== ADAPTER_BRIDGE_VERSION || typeof Reflect.get(bridge, "connectRoot") !== "function") {
+    throw new Error("Incompatible GlowTour.js adapter bridge");
+  }
+  return bridge.connectRoot(options);
+}
+export {
+  styleRecordToCssText,
+  styleRecordToCamelCase,
+  connectGlowTourRoot,
+  POPOVER_IDLE_STYLE,
+  POPOVER_IDLE_ATTRIBUTES,
+  POINTER_IDLE_STYLE,
+  POINTER_IDLE_ATTRIBUTES,
+  OVERLAY_PATH_IDLE_ATTRIBUTES,
+  OVERLAY_IDLE_STYLE,
+  OVERLAY_IDLE_ATTRIBUTES
+};

package/builder/index.d.ts

@@ -0,0 +1,148 @@
+import { type WorkflowDefinition, type WorkflowStepDraft } from "../definition";
+import type { EventHandler, StartOptions, StepAction, StepContext, StepParameters, StepTransitionAction, WaitUntilOptions } from "../types";
+declare const STEP_BUILDER_INTERNAL: unique symbol;
+/** Standard DOM event names supported by HTML elements. */
+export type EventName = keyof HTMLElementEventMap;
+type EventForName<TEventName extends EventName> = HTMLElementEventMap[TEventName];
+/** Predicate polled by `.waitUntil()` until it returns `true` or the wait times out. */
+type WaitUntilPredicate<T> = (context: StepContext<T>) => Promise<boolean> | boolean;
+/** Builder for constructing a tour workflow step-by-step. */
+export declare class WorkflowBuilder<T> {
+    readonly name: string;
+    private readonly options;
+    private readonly steps;
+    private currentStep;
+    private definition;
+    /**
+     * Creates a new workflow builder.
+     * @param name The name of the workflow.
+     * @param options Tour start options (lifecycle hooks, display options, behavior).
+     */
+    constructor(name: string, options?: StartOptions<T>);
+    /**
+     * Add a new step to the workflow.
+     * @param options Step configuration.
+     * @returns A WorkflowStepBuilder for chaining additional configuration.
+     */
+    step(options: StepParameters<T>): WorkflowStepBuilder<T>;
+    /**
+     * Append another workflow's steps to this workflow.
+     * @param workflow The workflow to append.
+     * @returns A WorkflowStepBuilder for the last appended step.
+     */
+    append(workflow: WorkflowDefinition<T>): WorkflowStepBuilder<T>;
+    /**
+     * Build and return the workflow definition. Can be called multiple times.
+     * @returns A frozen workflow definition ready to run.
+     */
+    build(): WorkflowDefinition<T>;
+    private assertBuilding;
+    private commitCurrentStep;
+}
+/** Builder for configuring a single tour step with actions and event handlers. */
+export declare class WorkflowStepBuilder<T> {
+    private readonly owner;
+    private readonly draft;
+    private active;
+    /**
+     * Creates a step builder for the given workflow.
+     * @param owner The parent WorkflowBuilder.
+     * @param draft The step definition being built.
+     */
+    constructor(owner: WorkflowBuilder<T>, draft: WorkflowStepDraft<T>);
+    /**
+     * Add another step to the workflow after this one.
+     * @param options The new step configuration.
+     * @returns The new WorkflowStepBuilder.
+     */
+    step(options: StepParameters<T>): WorkflowStepBuilder<T>;
+    /**
+     * Append another workflow's steps after this step.
+     * @param workflow The workflow to append.
+     * @returns The WorkflowStepBuilder for the last appended step.
+     */
+    append(workflow: WorkflowDefinition<T>): WorkflowStepBuilder<T>;
+    /**
+     * Build and return the workflow definition.
+     * @returns A frozen workflow definition ready to run.
+     */
+    build(): WorkflowDefinition<T>;
+    /**
+     * Add an action that clicks the target element when the step is entered.
+     * @returns This builder for chaining.
+     */
+    clickTarget(): this;
+    /**
+     * Add an action that focuses the target element when the step is entered.
+     * @returns This builder for chaining.
+     */
+    focusTarget(): this;
+    /**
+     * Add a delay action.
+     * @param timeMs The delay duration in milliseconds.
+     * @returns This builder for chaining.
+     */
+    wait(timeMs: number): this;
+    /**
+     * Add an action that waits for a condition before continuing.
+     * @param predicate Function that returns true when the condition is met.
+     * @param options Timeout and polling interval options.
+     * @returns This builder for chaining.
+     */
+    waitUntil(predicate: WaitUntilPredicate<T>, options?: WaitUntilOptions): this;
+    /**
+     * Add an action that waits for an element to appear in the DOM.
+     * @param selector CSS selector for the element to wait for.
+     * @param options Timeout and polling interval options.
+     * @returns This builder for chaining.
+     */
+    waitUntilElement(selector: string, options?: WaitUntilOptions): this;
+    /**
+     * Add a custom action callback to run when the step is entered.
+     * @param callback The action callback.
+     * @returns This builder for chaining.
+     */
+    do(callback: StepAction<T>): this;
+    /**
+     * Add a callback that runs before advancing to the next step.
+     * @param callback The transition callback.
+     * @returns This builder for chaining.
+     */
+    beforeAdvance(callback: StepTransitionAction<T>): this;
+    /**
+     * Add a callback that runs before going to the previous step.
+     * @param callback The transition callback.
+     * @returns This builder for chaining.
+     */
+    beforePrevious(callback: StepTransitionAction<T>): this;
+    /**
+     * Add a callback that runs before cancelling the tour.
+     * @param callback The transition callback.
+     * @returns This builder for chaining.
+     */
+    beforeCancel(callback: StepTransitionAction<T>): this;
+    /**
+     * Add an event listener to the target element for a specific event name.
+     * @param event The event name.
+     * @param callback The handler function.
+     * @returns This builder for chaining.
+     */
+    onTargetEvent<const TEventName extends EventName>(event: TEventName, callback: EventHandler<T, EventForName<TEventName>>["callback"]): this;
+    /**
+     * Add an event listener to the target element for multiple event names.
+     * @param events Array of event names.
+     * @param callback The handler function.
+     * @returns This builder for chaining.
+     */
+    onTargetEvent<const TEventNames extends readonly EventName[]>(events: TEventNames, callback: EventHandler<T, EventForName<TEventNames[number]>>["callback"]): this;
+    /**
+     * Add an event listener to the target element for a custom event.
+     * @param event The event name.
+     * @param callback The handler function.
+     * @returns This builder for chaining.
+     */
+    onTargetEvent<TEvent extends Event>(event: string, callback: EventHandler<T, TEvent>["callback"]): this;
+    [STEP_BUILDER_INTERNAL](): WorkflowStepDraft<T>;
+    private assertActive;
+}
+export {};

package/config/from-config.d.ts

@@ -0,0 +1,26 @@
+import type { WorkflowDefinitionFromConfig } from "./types";
+import { type ValidateWorkflowConfigOptions } from "./validate";
+/** Options accepted by `createWorkflowFromConfig`. */
+export type CreateWorkflowFromConfigOptions = ValidateWorkflowConfigOptions;
+/**
+ * Builds a `WorkflowDefinition<T>` from a JSON-serializable `WorkflowConfig<T>`. Defaults to
+ * `T = string`, the untrusted-JSON case; instantiate with a framework content type (e.g.
+ * `createWorkflowFromConfig<ReactNode>(...)`) for a same-runtime config carrying rich content.
+ *
+ * Validates the whole config first (structure, strict unknown-key rejection, and slot-appropriate
+ * action shapes), collecting all issues into a single `ConfigValidationError` rather than failing
+ * on the first one, then drives the existing `WorkflowBuilder<T>` to produce the definition.
+ *
+ * By default `title`/`content` must be plain strings, regardless of `T`, since the runtime cannot
+ * otherwise know what `T` is. Pass `options.validateContent` to accept a richer `T`.
+ *
+ * The returned definition carries the original (frozen) config as `.source`, so a future JSON
+ * exporter can round-trip without re-deriving the config from the built definition.
+ *
+ * @param config The parsed JSON (or equivalent plain object) to build from. Accepts `unknown` so
+ *   callers can pass `JSON.parse(...)` output directly; it is validated and narrowed internally.
+ * @param options Options; see {@link CreateWorkflowFromConfigOptions}.
+ * @throws {ConfigValidationError} When the config is invalid.
+ * @returns A frozen `WorkflowDefinition<T>` with `.source` attached.
+ */
+export declare function createWorkflowFromConfig<T = string>(config: unknown, options?: CreateWorkflowFromConfigOptions): WorkflowDefinitionFromConfig<T>;

package/config/index.d.ts

@@ -0,0 +1,6 @@
+export type { CreateWorkflowFromConfigOptions } from "./from-config";
+export { createWorkflowFromConfig } from "./from-config";
+export type { BuiltinAction, ConfigValidationIssue, EventHandlerConfig, LifecycleActionRef, StepActionRef, StepConfig, TransitionActionRef, WorkflowConfig, WorkflowDefinitionFromConfig, } from "./types";
+export { ConfigValidationError } from "./types";
+export type { ValidateWorkflowConfigOptions } from "./validate";
+export { validateWorkflowConfig } from "./validate";