Mixins / foldkit-mixins-ui

TourSlots

const · packages/mixins-ui/src/tour.ts:45

const TourSlots: Slots.Contract<{ readonly layer: Slot.UnnamedSlot<Capability.Capability<"Container", readonly [Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>]>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>; readonly blocker: Slot.UnnamedSlot<Capability.Capability<"Container", readonly [Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>]>, readonly [Event.EventToken<"click">], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>; readonly spotlight: Slot.UnnamedSlot<Capability.Capability<"Container", readonly [Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>]>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>; readonly panel: Slot.UnnamedSlot<Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>, readonly [Event.EventToken<"keydown">], readonly [Attr.AttrToken<"role">], readonly Slot.RequirementName[], boolean>; readonly arrow: Slot.UnnamedSlot<Capability.Capability<"Container", readonly [Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>]>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>; readonly progress: Slot.UnnamedSlot<Capability.Capability<"Container", readonly [Capability.Capability<"Interactive", readonly …;

A tour, Zag's and Shepherd's: a walk through steps, each a small dialog placed beside the element it explains, with the page dimmed around a cutout over that element. A step without a target, or whose target is not on the page, shows in the middle of the viewport instead. The current step is this Model, which the application keeps and folds with update({ steps }).

start -> step 0 -> ShowStep: the target scrolled into view, the step focused
Next / Back / ArrowRight / ArrowLeft -> step +/- 1; Next on the last -> Ended(completed)
Skip / Escape -> Ended(not completed), focus back to what started it
view: step -> the panel anchored to its target, the cutout following the target

The cutout's place is a browser fact: TrackBox (foldkit-primitives/dom) on the layer follows the target named by its data-target and writes its box as --fk-tour-x, -y, -w and -h, and its corner as --fk-tour-radius, so a stylist reads them and nothing crosses the Model; one layer follows every step, so the cutout can glide between targets. A target not on the page, or gone from it, is told as Spotlit. The dim takes presses outside the cutout, so the page cannot be used mid-step; the target can, unless interactive is false. The tour is drawn in the browser's top layer.

Each step is a non-modal dialog named by its title and described by its text, focused as it shows. Focus is not held in it: a step may ask the reader to use its target, which Tab reaches.