Documentation
¶
Overview ¶
Package tour is a GoFastr plugin that ships a trusted, host-page guided-tour runtime (Appcues-style product tours). Unlike the richtext/mermaid plugins it does NOT run inside a sandboxed opaque-origin iframe: a tour MUST reach the host page's real DOM to spotlight elements, so it cannot be opaque-origin.
The plugin serves two non-framed host-page assets (tour.js + tour.css) plus three JSON endpoints (read a tour definition, mark a tour seen, query seen state). Tours themselves are registered server-side via WithTour. The runtime is injected into host pages through UIHostOption (a host app mounts a UIHost with it) or loaded by the self-contained demo page (see WithDemoPage).
Index ¶
Constants ¶
const ( Name = "tour" Version = "0.1.0" RoutePrefix = "/__gofastr/plugin/tour" // Host-page runtime assets (NON-framed — same-origin scripts/stylesheets // the host page loads directly, no CORP relaxation, normal CSP). TourJSURL = RoutePrefix + "/tour.js" TourCSSURL = RoutePrefix + "/tour.css" // JSON endpoints consumed by the runtime. ToursBaseURL = RoutePrefix + "/tours" SeenURL = RoutePrefix + "/seen" // Demo page (only mounted under WithDemoPage). DemoURL = "/tour" SchemaVersion = "tour-v1" )
Identity and route constants. Both this plugin and js/src/tour.ts hard-code these exactly — they ARE the contract.
Variables ¶
This section is empty.
Functions ¶
func DefaultCapabilities ¶
func DefaultCapabilities() []string
DefaultCapabilities is the grant set this plugin advertises. The runtime only needs to read tour definitions and persist completion state.
func UIHostOption ¶
UIHostOption returns the uihost.Option that injects the tour runtime into every UIHost-rendered page. Apps using a UIHost pass this to uihost.New; the runtime then loads its own stylesheet via TourCSSURL and auto-runs any tour whose id is listed in window.gofastrTourAuto (or invoked explicitly).
The platform broker is NOT needed (the tour is a trusted host-page plugin, no sandboxed iframe), so only the runtime script is injected.
Types ¶
type Action ¶
type Action struct {
Type string `json:"type"` // "click" | "wait" | "navigate"
Selector string `json:"selector,omitempty"` // target for click / wait
URL string `json:"url,omitempty"` // target for navigate
}
Action is a UI action the runtime performs on the host page as part of a step — the mechanism for reaching BURIED targets: open a sidebar, expand a toggle, or navigate before spotlighting an element that isn't visible yet.
{"type": "click", "selector": "#open-settings"} // reveal a panel
{"type": "wait", "selector": "#panel .item"} // wait for it to appear
{"type": "navigate", "url": "/settings"} // go to another page/route
type Option ¶
type Option func(*Plugin)
Option configures a Plugin.
func WithCapabilities ¶
WithCapabilities overrides the grant set advertised by DefaultCapabilities.
func WithDemoPage ¶
func WithDemoPage() Option
WithDemoPage registers the self-contained demo page at DemoURL. The page injects the tour runtime + stylesheet and exposes a couple of demo tour trigger buttons.
func WithDevGrantAll ¶
func WithDevGrantAll() Option
WithDevGrantAll bypasses the auth.HasScope capability gate so a host with no auth wired can still run tours (demos, dev). Default OFF (enforcing).
func WithSeenHandler ¶
func WithSeenHandler(h SeenHandler) Option
WithSeenHandler overrides the default in-memory completion store. Use it to persist per-user tour state in a real database.
func WithTour ¶
WithTour registers a tour definition the runtime can fetch by id. Multiple tours may be registered; the last WithTour for a given id wins its steps. Any options set via WithTourOptions are preserved regardless of call order. Empty steps are rejected at Init time (a step-less tour is a misconfiguration).
func WithTourOptions ¶
func WithTourOptions(id string, opts TourOptions) Option
WithTourOptions sets tour-level options for a tour id (registration order with WithTour does not matter — steps and options merge onto the same tour).
type Placement ¶
type Placement string
Placement is the side of the target element the tooltip bubble anchors to. "auto" picks the side with the most viewport room.
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin is the guided-tour plugin. It implements framework.Plugin.
func New ¶
New constructs a Plugin with the given options. Unset options fall back to defaults so the plugin works with zero configuration.
func (*Plugin) Capabilities ¶
Capabilities returns the grant set this plugin advertises.
func (*Plugin) Init ¶
Init implements framework.Plugin. It registers the host-page assets and the three JSON endpoints on the app's router. The assets are NON-framed (trusted host-page scripts), so the AssetServer emits them with no CORP / frame-ancestors relaxation — just correct Content-Types.
type SeenHandler ¶
type SeenHandler interface {
Mark(ctx context.Context, tourID string) error
IsSeen(ctx context.Context, tourID string) (bool, error)
}
SeenHandler is the persistence hook for tour completion. Mark records the tour as seen for the caller; IsSeen reports whether it was previously seen. Implementations must be safe for concurrent use.
type Step ¶
type Step struct {
Selector string `json:"selector"`
Title string `json:"title"`
Body string `json:"body"`
Placement Placement `json:"placement"`
Before []Action `json:"before,omitempty"`
After []Action `json:"after,omitempty"`
// HTML is trusted, app-authored bubble content that overrides Title/Body.
// (Passing a live DOM node or a render function is a JS-API-only capability.)
HTML string `json:"html,omitempty"`
ClassName string `json:"className,omitempty"` // extra class on the bubble
}
Step is one ordered step of a tour. Selector is a CSS selector for the spotlighted element; Title/Body render in the tooltip bubble; Placement hints where the bubble sits relative to the target. Before runs when the step is entered (reveal the target); After runs when it is advanced past (e.g. close what Before opened).
type Tour ¶
type Tour struct {
ID string `json:"id"`
Steps []Step `json:"steps"`
Options *TourOptions `json:"options,omitempty"`
}
Tour is a registered tour definition served by GET /tours/{id}.
type TourOptions ¶
type TourOptions struct {
ShowProgress *bool `json:"showProgress,omitempty"` // "Step N of M" line
ShowDots *bool `json:"showDots,omitempty"` // progress dots
AllowKeyboard *bool `json:"allowKeyboard,omitempty"` // arrow/enter navigation
CloseOnEscape *bool `json:"closeOnEscape,omitempty"` // Esc dismisses
Backdrop *bool `json:"backdrop,omitempty"` // dim/scrim the page
Accent string `json:"accent,omitempty"` // accent color (--gofastr-tour-accent)
Width string `json:"width,omitempty"` // bubble max-width, e.g. "420px"
ClassName string `json:"className,omitempty"` // extra class on every bubble
}
TourOptions are tour-level toggles. Each is a *bool so "unset" means "use the runtime default" (all default ON) — a caller overrides only what it wants.
Source Files