@tapestry-ui/tour 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon Minton
+
+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

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# @tapestry-ui/tour
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A product tour for Preact: **spotlight the thing, explain it, move on.**
+WCAG 2.1 AA, headless behavior, skinned entirely through CSS.
+
+Part of [Tapestry UI](https://github.com/ryurage/brandonminton).
+
+```bash
+npm i @tapestry-ui/tour
+```
+
+```tsx
+import { Tour } from '@tapestry-ui/tour';
+import '@tapestry-ui/tour/styles.css'; // structural only — picks one colour, the dim
+
+<Tour
+  open={touring}
+  onClose={() => setTouring(false)}
+  label="Dashboard tour"
+  steps={[
+    { target: '.fuse', title: 'The countdown', body: 'Days until sell-ready.' },
+    { target: '.property-z', title: 'Every property', body: 'A decade, month by month.' },
+  ]}
+/>
+```
+
+## Atomic parts
+
+Split on Brad Frost's lines, like the accordion:
+
+| | | |
+|---|---|---|
+| `Spotlight` | **atom** | dims the page, cuts a hole around one element |
+| `Coachmark` | *molecule* | a spotlight plus the bubble that explains it — composed inside `Tour` |
+| `Tour` | **organism** | the sequence, with the controls and the keyboard |
+
+`Spotlight` and the pure helpers `placeBubble` / `rectOf` are exported, so you can
+build a different sequence on the same foundation.
+
+## The two contracts
+
+**The component owns the SEQUENCE; the consumer owns the PAGE.** A tour cannot
+know that step four points at something inside a closed drawer. So a step may
+carry `onEnter` — sync or async — that you use to put the page in the right
+state. The tour then waits for the target to appear (up to 1.2s) before pointing
+at it.
+
+```tsx
+{ target: '#epic-editor', body: 'Epics live here.', onEnter: () => openDrawer('epics') }
+```
+
+**The container contract, and its exception.** Tapestry UI components never own
+scrolling — but a tour must, because a step whose target is below the fold points
+at nothing. It scrolls **the target**, never a container of yours, and only when
+the target is actually off screen. A tour that jumps the page on every step is a
+tour nobody finishes.
+
+## A step whose target never arrives still speaks
+
+It is not skipped and it does not throw. The bubble centres itself, the spotlight
+stays dark, and `onMissingTarget` tells you — because a renamed class should cost
+you one highlight, not the whole tour.
+
+## Props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `steps` | `TourStep[]` | `{ target?, title?, body, placement?, padding?, onEnter? }` |
+| `open` | `boolean` | |
+| `onClose` | `(reason) => void` | `'finished'` \| `'skipped'` \| `'escaped'` — they mean different things |
+| `index` / `onIndex` | `number` / `(i) => void` | controlled; the tour reports intent and never drifts |
+| `label` | `string` | names the tour when a step has no title |
+| `nextLabel` `backLabel` `skipLabel` `doneLabel` | `string` | |
+| `showProgress` | `boolean` | "3 of 7" (default true) |
+| `blocking` | `boolean` | block the page outside the spotlight (default true) |
+| `onMissingTarget` | `(step, index) => void` | |
+| `class` / `bubbleClass` / `id` | `string` | skin hooks |
+
+## Keyboard
+
+| Key | Does |
+|---|---|
+| <kbd>→</kbd> | next step, or finish on the last |
+| <kbd>←</kbd> | previous step |
+| <kbd>Esc</kbd> | leave, reported as `'escaped'` |
+| <kbd>Tab</kbd> | cycles within the bubble while blocking |
+
+Focus moves to the bubble on every step, so a keyboard and a screen reader follow
+the tour instead of being left behind in the document. The bubble is a dialog
+that does **not** claim `aria-modal` — the page behind it is the subject of the
+tour, not scenery to be hidden — and the step count is announced from a polite
+live region.
+
+## Styling
+
+| Property | Default |
+|---|---|
+| `--tui-tour-dim` | `rgb(0 0 0 / 0.6)` |
+| `--tui-tour-hole-radius` | `6px` |
+| `--tui-tour-bubble-w` | `min(22rem, calc(100vw - 24px))` |
+| `--tui-tour-bubble-pad` | `1rem` |
+| `--tui-tour-gap` | `0.5em` |
+| `--tui-tour-focus` | `2px solid currentColor` |
+| `--tui-tour-z` / `--tui-tour-bubble-z` | `60` / `61` |
+| `--tui-tour-move` | the hole's transition; honours `prefers-reduced-motion` |
+
+Parts: `root` (`data-placement`), `spotlight` (`data-blocking`), `band`, `hole`,
+`bubble`, `title`, `body`, `controls`, `progress`, `skip`, `back`, `next`,
+`status`.
+
+**How the hole works, in case you want to change it:** the dim is a `box-shadow`
+on the hole itself rather than a fill over the page, which is what lets the hole
+have rounded corners. The four `band` elements around it are what actually catch
+clicks — so the highlighted element stays usable while the rest of the page does
+not. **Never fork the package to restyle it.**
+
+## License
+
+MIT © Brandon Minton

package/dist/tour.d.ts

@@ -0,0 +1,123 @@
+import { type ComponentChildren, type JSX, type Ref } from 'preact';
+/** The two sentences this component assembles. Functions, so a language whose
+ *  "3 of 7" reads differently can simply say so. */
+export interface TourStrings {
+    /** The visible progress line. */
+    progress: (step: number, total: number) => string;
+    /** What the live region announces on each step. */
+    announce: (step: number, total: number) => string;
+}
+export declare const EN_TOUR: TourStrings;
+export type Placement = 'top' | 'bottom' | 'left' | 'right' | 'auto';
+/** Where a mark actually landed; 'center' means there was nothing to point at. */
+export type PlacedAt = Exclude<Placement, 'auto'> | 'center';
+export type TourEnd = 'finished' | 'skipped' | 'escaped';
+export interface TourStep {
+    /** Stable id; defaults to the step's position. */
+    id?: string;
+    /** CSS selector for the element to point at. Omit for a step about the page as a whole. */
+    target?: string;
+    title?: ComponentChildren;
+    body: ComponentChildren;
+    /** Where the bubble sits relative to the target (default: 'auto'). */
+    placement?: Placement;
+    /** Spotlight padding for this step only. */
+    padding?: number;
+    /** Corner radius of the hole, in px — a pill-shaped button wants a pill-shaped hole. */
+    radius?: number;
+    /** Put the page in the state this step needs — open the drawer, switch the tab.
+     *  May be async; the tour waits for the target to appear either way. */
+    onEnter?: () => void | Promise<void>;
+}
+export interface TourProps {
+    steps: TourStep[];
+    open: boolean;
+    /** Why the tour ended: the last step was passed, skip was pressed, or Escape. */
+    onClose: (reason: TourEnd) => void;
+    /** Controlled step index. Omit to let the tour keep its own. */
+    index?: number;
+    onIndex?: (index: number) => void;
+    /** Accessible name for the tour as a whole. */
+    label?: string;
+    nextLabel?: string;
+    backLabel?: string;
+    skipLabel?: string;
+    doneLabel?: string;
+    /** Show "3 of 7" (default true). */
+    showProgress?: boolean;
+    /** Replace the sentences this component builds. Defaults are English. */
+    strings?: Partial<TourStrings>;
+    /** Stop the page being clicked outside the spotlight (default true). */
+    blocking?: boolean;
+    /** Called when a step's target never turned up; the step still shows, centred. */
+    onMissingTarget?: (step: TourStep, index: number) => void;
+    /** skin hooks — tapestry-ui components style through CSS, never props */
+    class?: string;
+    bubbleClass?: string;
+    id?: string;
+}
+export interface Rect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+/** Viewport-space box of an element, or null when it isn't there (or has no box). */
+export declare function rectOf(element: Element | null): Rect | null;
+/**
+ * Where the bubble goes. 'auto' prefers below, then above, then the sides —
+ * whichever first has ROOM_NEEDED. Everything is viewport space, so the caller
+ * can position with `fixed` and never think about scroll offsets.
+ */
+export declare function placeBubble(hole: Rect | null, bubble: {
+    width: number;
+    height: number;
+}, view: {
+    width: number;
+    height: number;
+}, wanted?: Placement): {
+    top: number;
+    left: number;
+    placement: PlacedAt;
+};
+/**
+ * The atom: the page goes dim, one rectangle doesn't.
+ *
+ * The dimming is a box-shadow on the hole itself rather than a filled overlay,
+ * so the hole can have rounded corners. The four bands around it are what
+ * actually catch clicks — which is why the hole stays clickable, and why
+ * `blocking` can be honoured without making the highlighted thing unusable.
+ */
+export declare function Spotlight({ hole, blocking, radius }: {
+    hole: Rect | null;
+    blocking?: boolean;
+    radius?: number;
+}): JSX.Element;
+export interface CoachmarkProps {
+    /** The rectangle to light up, in viewport space. Null dims everything and centres the bubble. */
+    hole: Rect | null;
+    /** What the bubble says — and, in a tour, the controls underneath it. */
+    children: ComponentChildren;
+    placement?: Placement;
+    blocking?: boolean;
+    /** Corner radius of the hole, in px. */
+    radius?: number;
+    /** Accessible name, when the content has no heading to point at. */
+    label?: string;
+    /** Id of the heading inside `children` that names this mark. */
+    labelledBy?: string;
+    /** Handed out so a sequence can move focus here on every step. */
+    bubbleRef?: Ref<HTMLDivElement>;
+    class?: string;
+    bubbleClass?: string;
+}
+/**
+ * The molecule: a spotlight, and the bubble anchored to it.
+ *
+ * It measures its own bubble and places itself, so the thing that owns the
+ * sequence only has to say which rectangle matters. The bubble is a dialog that
+ * does NOT claim aria-modal — the page behind it is the subject of the
+ * explanation, not scenery to be hidden from a screen reader.
+ */
+export declare function Coachmark(props: CoachmarkProps): JSX.Element;
+export declare function Tour(props: TourProps): JSX.Element | null;

package/dist/tour.js

@@ -0,0 +1,278 @@
+import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
+import { useCallback, useEffect, useId, useLayoutEffect, useRef, useState } from 'preact/hooks';
+/** Breathing room, in px, between the target's edge and the spotlight's edge. */
+const DEFAULT_SPOTLIGHT_PAD = 6;
+/** Gap, in px, between the spotlight and the bubble. */
+const BUBBLE_GAP = 12;
+/** Keep the bubble at least this far from the viewport edge. */
+const VIEWPORT_MARGIN = 12;
+/** A step needs this much room on a side before the bubble will go there. */
+const ROOM_NEEDED = 160;
+/** How long to wait for a step's target to appear after onEnter, in ms. */
+const TARGET_WAIT_MS = 1200;
+/** How often to look for it while waiting, in ms. */
+const TARGET_POLL_MS = 50;
+export const EN_TOUR = {
+    progress: (step, total) => `${step} of ${total}`,
+    announce: (step, total) => `Step ${step} of ${total}`,
+};
+const cx = (...parts) => parts.filter(Boolean).join(' ');
+const grow = (rect, by) => ({
+    top: rect.top - by,
+    left: rect.left - by,
+    width: rect.width + by * 2,
+    height: rect.height + by * 2,
+});
+/** Viewport-space box of an element, or null when it isn't there (or has no box). */
+export function rectOf(element) {
+    const box = element?.getBoundingClientRect?.();
+    if (!box)
+        return null;
+    if (box.width === 0 && box.height === 0)
+        return null;
+    return { top: box.top, left: box.left, width: box.width, height: box.height };
+}
+/**
+ * Where the bubble goes. 'auto' prefers below, then above, then the sides —
+ * whichever first has ROOM_NEEDED. Everything is viewport space, so the caller
+ * can position with `fixed` and never think about scroll offsets.
+ */
+export function placeBubble(hole, bubble, view, wanted = 'auto') {
+    if (!hole) {
+        return {
+            top: Math.max(VIEWPORT_MARGIN, (view.height - bubble.height) / 2),
+            left: Math.max(VIEWPORT_MARGIN, (view.width - bubble.width) / 2),
+            placement: 'center',
+        };
+    }
+    const room = {
+        bottom: view.height - (hole.top + hole.height),
+        top: hole.top,
+        right: view.width - (hole.left + hole.width),
+        left: hole.left,
+    };
+    const order = wanted === 'auto' ? ['bottom', 'top', 'right', 'left'] : [wanted];
+    const needed = { bottom: bubble.height, top: bubble.height, right: bubble.width, left: bubble.width };
+    const fits = order.find(side => room[side] >= Math.min(needed[side], ROOM_NEEDED) + BUBBLE_GAP);
+    // nothing fits: take the roomiest side rather than drawing off-screen
+    const side = fits ?? ['bottom', 'top', 'right', 'left']
+        .reduce((best, one) => (room[one] > room[best] ? one : best), 'bottom');
+    const centreX = hole.left + hole.width / 2 - bubble.width / 2;
+    const centreY = hole.top + hole.height / 2 - bubble.height / 2;
+    const raw = {
+        bottom: { top: hole.top + hole.height + BUBBLE_GAP, left: centreX },
+        top: { top: hole.top - bubble.height - BUBBLE_GAP, left: centreX },
+        right: { top: centreY, left: hole.left + hole.width + BUBBLE_GAP },
+        left: { top: centreY, left: hole.left - bubble.width - BUBBLE_GAP },
+    }[side];
+    const clamp = (value, size, limit) => Math.max(VIEWPORT_MARGIN, Math.min(value, limit - size - VIEWPORT_MARGIN));
+    return {
+        top: clamp(raw.top, bubble.height, view.height),
+        left: clamp(raw.left, bubble.width, view.width),
+        placement: side,
+    };
+}
+/**
+ * The atom: the page goes dim, one rectangle doesn't.
+ *
+ * The dimming is a box-shadow on the hole itself rather than a filled overlay,
+ * so the hole can have rounded corners. The four bands around it are what
+ * actually catch clicks — which is why the hole stays clickable, and why
+ * `blocking` can be honoured without making the highlighted thing unusable.
+ */
+export function Spotlight({ hole, blocking = true, radius }) {
+    const ring = hole && (_jsx("div", { class: "tui-tour__hole", "data-part": "hole", style: {
+            top: `${hole.top}px`,
+            left: `${hole.left}px`,
+            width: `${hole.width}px`,
+            height: `${hole.height}px`,
+            ...(radius === undefined ? {} : { borderRadius: `${radius}px` }),
+        } }));
+    if (!blocking)
+        return _jsx("div", { class: "tui-tour__spotlight", "data-part": "spotlight", "data-blocking": "false", children: ring });
+    // four bands, so the page is unclickable everywhere except the hole
+    const bands = hole
+        ? [
+            { top: 0, left: 0, width: '100%', height: `${Math.max(0, hole.top)}px` },
+            { top: `${hole.top + hole.height}px`, left: 0, width: '100%', bottom: 0 },
+            { top: `${hole.top}px`, left: 0, width: `${Math.max(0, hole.left)}px`, height: `${hole.height}px` },
+            { top: `${hole.top}px`, left: `${hole.left + hole.width}px`, right: 0, height: `${hole.height}px` },
+        ]
+        : [{ top: 0, left: 0, right: 0, bottom: 0 }];
+    return (_jsxs("div", { class: "tui-tour__spotlight", "data-part": "spotlight", "data-blocking": "true", children: [bands.map((band, index) => (_jsx("div", { class: "tui-tour__band", "data-part": "band", style: band }, index))), ring] }));
+}
+/**
+ * The molecule: a spotlight, and the bubble anchored to it.
+ *
+ * It measures its own bubble and places itself, so the thing that owns the
+ * sequence only has to say which rectangle matters. The bubble is a dialog that
+ * does NOT claim aria-modal — the page behind it is the subject of the
+ * explanation, not scenery to be hidden from a screen reader.
+ */
+export function Coachmark(props) {
+    const { hole, blocking = true, placement = 'auto' } = props;
+    const own = useRef(null);
+    const bubble = (props.bubbleRef ?? own);
+    const [at, setAt] = useState({ top: 0, left: 0, placement: 'center' });
+    useLayoutEffect(() => {
+        const place = () => {
+            const box = bubble.current?.getBoundingClientRect?.();
+            setAt(placeBubble(hole, { width: box?.width || 320, height: box?.height || 160 }, { width: window.innerWidth, height: window.innerHeight }, placement));
+        };
+        place();
+        window.addEventListener('resize', place);
+        // capture, so a scroll inside any container repositions the mark too
+        window.addEventListener('scroll', place, true);
+        return () => {
+            window.removeEventListener('resize', place);
+            window.removeEventListener('scroll', place, true);
+        };
+    }, [hole?.top, hole?.left, hole?.width, hole?.height, placement]);
+    return (_jsxs("div", { class: cx('tui-tour', props.class), "data-part": "root", "data-placement": at.placement, children: [_jsx(Spotlight, { hole: hole, blocking: blocking, radius: props.radius }), _jsx("div", { ref: bubble, class: cx('tui-tour__bubble', props.bubbleClass), "data-part": "bubble", role: "dialog", "aria-modal": "false", "aria-label": props.labelledBy ? undefined : props.label, "aria-labelledby": props.labelledBy, tabIndex: -1, style: { top: `${at.top}px`, left: `${at.left}px` }, children: props.children })] }));
+}
+export function Tour(props) {
+    const autoId = useId();
+    const base = props.id ?? `tui-tour-${autoId}`;
+    const { steps, open, blocking = true, showProgress = true, nextLabel = 'Next', backLabel = 'Back', skipLabel = 'Skip', doneLabel = 'Done', } = props;
+    const words = { ...EN_TOUR, ...props.strings };
+    const controlled = props.index !== undefined;
+    const [ownIndex, setOwnIndex] = useState(0);
+    const rawIndex = controlled ? props.index : ownIndex;
+    const index = Math.min(Math.max(rawIndex, 0), Math.max(steps.length - 1, 0));
+    const step = steps[index];
+    const [hole, setHole] = useState(null);
+    const bubbleRef = useRef(null);
+    /** Bumped whenever the measured target should be re-read. */
+    const [measureTick, setMeasureTick] = useState(0);
+    const goTo = useCallback((next) => {
+        if (!controlled)
+            setOwnIndex(next);
+        props.onIndex?.(next);
+    }, [controlled, props.onIndex]);
+    const end = useCallback((reason) => {
+        if (!controlled)
+            setOwnIndex(0);
+        props.onClose(reason);
+    }, [controlled, props.onClose]);
+    const next = useCallback(() => {
+        if (index >= steps.length - 1)
+            end('finished');
+        else
+            goTo(index + 1);
+    }, [index, steps.length, end, goTo]);
+    const back = useCallback(() => { if (index > 0)
+        goTo(index - 1); }, [index, goTo]);
+    // ── put the page in this step's state, then wait for the target to turn up
+    useEffect(() => {
+        if (!open || !step)
+            return;
+        let cancelled = false;
+        let timer = 0;
+        const find = () => (step.target ? document.querySelector(step.target) : null);
+        const settle = () => {
+            const target = find();
+            const found = rectOf(target);
+            if (found) {
+                // only scroll when it is actually out of view; a tour that jumps the page
+                // on every step is a tour nobody finishes
+                const offscreen = found.top < 0 || found.top + found.height > window.innerHeight;
+                if (offscreen)
+                    target?.scrollIntoView?.({ block: 'center', behavior: 'smooth' });
+                setMeasureTick(tick => tick + 1);
+                return true;
+            }
+            return false;
+        };
+        const deadline = Date.now() + TARGET_WAIT_MS;
+        const poll = () => {
+            if (cancelled)
+                return;
+            if (settle())
+                return;
+            if (!step.target) {
+                setHole(null);
+                setMeasureTick(tick => tick + 1);
+                return;
+            }
+            if (Date.now() >= deadline) {
+                setHole(null);
+                setMeasureTick(tick => tick + 1);
+                props.onMissingTarget?.(step, index);
+                return;
+            }
+            timer = window.setTimeout(poll, TARGET_POLL_MS);
+        };
+        setHole(null); // the old step's hole must not linger over the new step
+        Promise.resolve(step.onEnter?.()).then(() => { if (!cancelled)
+            poll(); });
+        return () => { cancelled = true; if (timer)
+            window.clearTimeout(timer); };
+    }, [open, index, step?.target]);
+    // ── where this step's target is. The coach mark does its own placing from here.
+    useLayoutEffect(() => {
+        if (!open || !step)
+            return;
+        const measure = () => {
+            const found = rectOf(step.target ? document.querySelector(step.target) : null);
+            setHole(found ? grow(found, step.padding ?? DEFAULT_SPOTLIGHT_PAD) : null);
+        };
+        measure();
+        window.addEventListener('resize', measure);
+        window.addEventListener('scroll', measure, true);
+        return () => {
+            window.removeEventListener('resize', measure);
+            window.removeEventListener('scroll', measure, true);
+        };
+    }, [open, index, measureTick, step?.target, step?.padding]);
+    // ── the keyboard owns the tour: focus follows each step, Escape leaves
+    useEffect(() => {
+        if (!open)
+            return;
+        bubbleRef.current?.focus?.();
+    }, [open, index]);
+    useEffect(() => {
+        if (!open)
+            return;
+        const onKey = (event) => {
+            if (event.key === 'Escape') {
+                event.preventDefault();
+                end('escaped');
+                return;
+            }
+            if (event.key === 'ArrowRight') {
+                event.preventDefault();
+                next();
+                return;
+            }
+            if (event.key === 'ArrowLeft') {
+                event.preventDefault();
+                back();
+                return;
+            }
+            if (event.key !== 'Tab' || !blocking)
+                return;
+            // everything outside the bubble is unreachable anyway; keep Tab inside it
+            const focusable = bubbleRef.current?.querySelectorAll('button:not([disabled]), [href], input, select, textarea, [tabindex]:not([tabindex="-1"])');
+            if (!focusable || focusable.length === 0)
+                return;
+            const first = focusable[0];
+            const last = focusable[focusable.length - 1];
+            const active = document.activeElement;
+            if (event.shiftKey && (active === first || active === bubbleRef.current)) {
+                event.preventDefault();
+                last.focus();
+            }
+            else if (!event.shiftKey && active === last) {
+                event.preventDefault();
+                first.focus();
+            }
+        };
+        document.addEventListener('keydown', onKey);
+        return () => document.removeEventListener('keydown', onKey);
+    }, [open, blocking, next, back, end]);
+    if (!open || !step)
+        return null;
+    const titleId = `${base}-title`;
+    const isLast = index === steps.length - 1;
+    return (_jsxs("div", { id: base, class: cx('tui-tour', props.class), "data-part": "tour", children: [_jsxs(Coachmark, { hole: hole, placement: step.placement, blocking: blocking, radius: step.radius, bubbleRef: bubbleRef, label: step.title === undefined ? props.label ?? 'Tour' : undefined, labelledBy: step.title === undefined ? undefined : titleId, bubbleClass: props.bubbleClass, children: [step.title !== undefined && (_jsx("h2", { id: titleId, class: "tui-tour__title", "data-part": "title", children: step.title })), _jsx("div", { class: "tui-tour__body", "data-part": "body", children: step.body }), _jsxs("div", { class: "tui-tour__controls", "data-part": "controls", children: [showProgress && (_jsx("span", { class: "tui-tour__progress", "data-part": "progress", children: words.progress(index + 1, steps.length) })), _jsx("button", { type: "button", class: "tui-tour__skip", "data-part": "skip", onClick: () => end('skipped'), children: skipLabel }), _jsx("button", { type: "button", class: "tui-tour__back", "data-part": "back", disabled: index === 0, onClick: back, children: backLabel }), _jsx("button", { type: "button", class: "tui-tour__next", "data-part": "next", onClick: next, children: isLast ? doneLabel : nextLabel })] })] }), _jsx("span", { class: "tui-tour__sr", "data-part": "status", role: "status", "aria-live": "polite", children: words.announce(index + 1, steps.length) })] }));
+}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@tapestry-ui/tour",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "A WCAG 2.1 AA product tour for Preact \u2014 spotlight, coach marks, keyboard, headless behavior, skin via CSS. The sequence is the component's; the page is yours.",
+  "license": "MIT",
+  "author": "Brandon Minton",
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/tour.d.ts",
+      "default": "./dist/tour.js"
+    },
+    "./styles.css": "./styles.css"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "styles.css",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "peerDependencies": {
+    "preact": ">=10.24.0"
+  },
+  "devDependencies": {
+    "jsdom": "^25.0.1",
+    "preact": "^10.29.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ryurage/brandonminton.git",
+    "directory": "packages/tapestry-ui/tour"
+  },
+  "keywords": [
+    "preact",
+    "tour",
+    "product-tour",
+    "onboarding",
+    "coachmark",
+    "spotlight",
+    "walkthrough",
+    "a11y",
+    "wcag",
+    "headless",
+    "tapestry-ui"
+  ]
+}

package/styles.css

@@ -0,0 +1,61 @@
+/* @tapestry-ui/tour — STRUCTURAL styles only. The skin is yours: override the
+   custom properties, or ignore this file and style the [data-part] hooks from
+   scratch. The one colour here is the dim, because without it there is no
+   spotlight at all; it is a custom property like everything else. */
+.tui-tour__spotlight { position: fixed; inset: 0; z-index: var(--tui-tour-z, 60); }
+
+/* the bands are what catch clicks; the hole between them is left alone, which is
+   why the highlighted thing stays usable while the rest of the page does not */
+.tui-tour__band { position: fixed; }
+.tui-tour__spotlight[data-blocking="false"] { pointer-events: none; }
+
+/* the dim is a shadow on the hole, not a fill over the page — that is what lets
+   the hole have rounded corners */
+.tui-tour__hole {
+  position: fixed;
+  pointer-events: none;
+  border-radius: var(--tui-tour-hole-radius, 6px);
+  box-shadow: 0 0 0 100vmax var(--tui-tour-dim, rgb(0 0 0 / 0.6));
+  transition: var(--tui-tour-move, top 180ms ease, left 180ms ease, width 180ms ease, height 180ms ease);
+}
+
+.tui-tour__bubble {
+  position: fixed;
+  z-index: var(--tui-tour-bubble-z, 61);
+  box-sizing: border-box;
+  width: var(--tui-tour-bubble-w, min(22rem, calc(100vw - 24px)));
+  padding: var(--tui-tour-bubble-pad, 1rem);
+}
+.tui-tour__bubble:focus-visible { outline: var(--tui-tour-focus, 2px solid currentColor); outline-offset: 2px; }
+.tui-tour__title { margin: 0 0 0.35em; font-size: 1rem; }
+.tui-tour__body > :first-child { margin-top: 0; }
+.tui-tour__body > :last-child { margin-bottom: 0; }
+
+.tui-tour__controls {
+  display: flex;
+  align-items: center;
+  gap: var(--tui-tour-gap, 0.5em);
+  margin-top: var(--tui-tour-controls-top, 0.9em);
+}
+/* the count sits left, the buttons right — Skip furthest from Next, so the one
+   that ends the tour is never the one a thumb reaches for first */
+.tui-tour__progress { margin-right: auto; }
+.tui-tour__controls button { font: inherit; color: inherit; cursor: pointer; }
+.tui-tour__controls button:disabled { cursor: default; opacity: 0.5; }
+
+/* visually hidden, still read aloud */
+.tui-tour__sr {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .tui-tour__hole { transition: none; }
+}