@steppy/player 0.5.0 → 0.6.0

package/dist/types/templates/controls.d.ts

@@ -11,6 +11,12 @@ export declare function renderCounter(ctx: TemplateContext): TemplateResult;
 export declare function renderPrev(ctx: TemplateContext): TemplateResult;
 export declare function renderNext(ctx: TemplateContext): TemplateResult;
 export declare function renderRestart(ctx: TemplateContext): TemplateResult;
+/**
+ * A locale's name in its own language ("Français", "Nederlands"), the way the
+ * static pages' picker labels it. Falls back to the code itself when the
+ * runtime cannot name it (an invalid tag, or a tag it does not know).
+ */
+export declare function localeLabel(locale: string): string;
 export declare function renderLocaleSelect(ctx: TemplateContext): TemplateResult | typeof nothing;
 export declare function renderLayoutSelect(ctx: TemplateContext): TemplateResult | typeof nothing;
 /** Segmented [Sidebar | Overlay | Inline] control (active = dark fill). */

package/dist/types/tour/api.d.ts

@@ -4,8 +4,10 @@
  */
 import type { TourSource } from './loader.js';
 import type { TourStringOverrides } from './strings.js';
+import type { TourAppearance, TourTheme } from './theme.js';
 export type { TourSource } from './loader.js';
 export type { TourStringOverrides } from './strings.js';
+export type { TourAppearance, TourTheme } from './theme.js';
 export interface TourStartOptions {
     /** Route parameters for the tour's entry (``/invoices/:invoiceId``). */
     params?: Record<string, string | number>;
@@ -44,6 +46,10 @@ export interface TourHostApi {
     source: TourSource | null;
     navigate: TourNavigate | null;
     strings: TourStringOverrides | undefined;
+    /** ``--steppy-tour-*`` values set inline on the element; they win over the page's CSS. */
+    theme: TourTheme | undefined;
+    /** Default palette: ``dark`` (default), ``light``, or ``auto`` (follows the colour scheme). */
+    appearance: TourAppearance;
     /** Start a tour. Resolves true once it started; never rejects. */
     start(tourId: string, options?: TourStartOptions): Promise<boolean>;
     stop(reason?: string): void;

package/dist/types/tour/host.d.ts

@@ -16,6 +16,7 @@ import { type DomAdapter } from './dom.js';
 import { type TourEventDetailMap } from './events.js';
 import { type TourSource } from './loader.js';
 import { type TourStringOverrides } from './strings.js';
+import { type TourAppearance, type TourTheme } from './theme.js';
 export interface SteppyTourHost {
     addEventListener<K extends keyof TourEventDetailMap>(type: K, listener: (this: SteppyTourHost, ev: CustomEvent<TourEventDetailMap[K]>) => void, options?: boolean | AddEventListenerOptions): void;
     addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
@@ -62,6 +63,13 @@ export declare class SteppyTourHost extends LitElement implements TourHostApi {
         strings: {
             attribute: boolean;
         };
+        theme: {
+            attribute: boolean;
+        };
+        appearance: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
     };
     /** Test seam: geometry and timing. */
     static dom: DomAdapter;
@@ -76,6 +84,8 @@ export declare class SteppyTourHost extends LitElement implements TourHostApi {
     source: TourSource | null;
     navigate: TourNavigate | null;
     strings: TourStringOverrides | undefined;
+    theme: TourTheme | undefined;
+    appearance: TourAppearance;
     private _s;
     private _queue;
     private _dispatching;
@@ -93,6 +103,8 @@ export declare class SteppyTourHost extends LitElement implements TourHostApi {
     private _focusPending;
     private _appFocus;
     private _swapSeq;
+    /** The custom properties ``theme`` wrote last, so a changed theme removes the ones it dropped. */
+    private _themed;
     /** While a tour runs: an app that switches language through ``<html lang>`` alone. */
     private _lang;
     private _policy;
@@ -109,6 +121,8 @@ export declare class SteppyTourHost extends LitElement implements TourHostApi {
     protected updated(changed: PropertyValues<this>): void;
     protected firstUpdated(): void;
     protected render(): import("lit-html").TemplateResult | typeof nothing;
+    /** Inline custom properties win over the page's ``:root`` and element rules. */
+    private _applyTheme;
     private _start;
     private _fail;
     private _tryResume;

package/dist/types/tour/index.d.ts

@@ -7,6 +7,7 @@
  */
 export { SteppyTourHost, defineTourHost } from './host.js';
 export type { TourHostApi, TourNavigate, TourNavigateContext, TourPosition, TourSource, TourStartOptions, TourStringOverrides } from './api.js';
+export { TOUR_APPEARANCES, TOUR_THEME_KEYS, themeProperty, type TourAppearance, type TourTheme, type TourThemeKey } from './theme.js';
 export type { TourEventDetailMap, TourEventMeta, TourStepPosition } from './events.js';
 export type { DismissVia, StepReason, TourErrorDetail, TourSourceKind } from './engine.js';
 export { ADVANCE_KINDS, PLACEMENTS, TOUR_ERROR_REASONS, TOUR_EVENTS, TOUR_PARTS, TOUR_SCHEMA_VERSION, type AdvanceKind, type Placement, type TourErrorReason, type TourEventName, type TourPart, } from './contract.js';

package/dist/types/tour/styles.d.ts

@@ -1,13 +1,17 @@
 /**
- * Overlay styles. Theming goes through public ``--steppy-*`` custom
- * properties, read into private ``--_pw-*`` ones on ``:host`` and never
- * declared themselves — so a page sets them on ``:root`` or on the element.
- * Geometry comes from properties the tracker writes through CSSOM.
+ * Overlay styles. Theming goes through public ``--steppy-tour-*`` custom
+ * properties (the keys of ``theme.ts``), read into private ``--_pw-*`` ones on
+ * ``:host`` and never declared themselves — so a page sets them on ``:root``
+ * or on the element, and the host's ``theme`` property sets them inline.
+ * ``appearance="light"`` (or ``"auto"`` under a light colour scheme) swaps the
+ * defaults, never a value the page set. Geometry comes from properties the
+ * tracker writes through CSSOM.
  *
- * Defaults meet WCAG AA (guard: ``test/tour/small-modules.test.ts``). The bubble
- * inherits the app's font unless ``--steppy-font-family`` is set. The
- * bubble's inner layout uses logical properties, so it mirrors under the
- * layer's ``dir`` (an Arabic or Hebrew tour); its placement around the target
- * stays physical.
+ * Defaults meet WCAG AA in both appearances (guard: ``test/tour/small-modules.test.ts``).
+ * The bubble inherits the app's font unless ``--steppy-tour-font-family`` (or
+ * ``--steppy-font-family``) is set. The bubble's inner layout uses logical
+ * properties, so it mirrors under the layer's ``dir`` (an Arabic or Hebrew
+ * tour); its placement around the target stays physical.
  */
-export declare const tourStyles: import("lit").CSSResult;
+import { type CSSResult } from 'lit';
+export declare const tourStyles: CSSResult;

package/dist/types/tour/theme.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The overlay's theme surface: the public ``--steppy-tour-*`` custom
+ * properties, and the ``theme`` object that writes them from code.
+ *
+ * One key list drives the stylesheet (``styles.ts``), the host's ``theme``
+ * property and the docs (guard: ``test/tour/theme.test.ts``). Values come from
+ * the app only — its stylesheet or the ``theme`` property — never from a tour
+ * file, so tour data still cannot reach a style.
+ */
+export declare const TOUR_THEME_KEYS: readonly ["bubbleBg", "bubbleFg", "muted", "accent", "accentFg", "focus", "scrim", "link", "border", "radius", "width", "padding", "shadow", "fontFamily", "fontSize", "lineHeight", "titleSize", "titleWeight", "buttonRadius", "buttonPadding", "buttonWeight", "ringWidth", "spotlightRadius"];
+export type TourThemeKey = (typeof TOUR_THEME_KEYS)[number];
+/** Any subset of the keys, as CSS values: ``{ accent: '#0b5cad', width: '360px' }``. */
+export type TourTheme = Partial<Record<TourThemeKey, string>>;
+/** ``dark`` is the default; ``auto`` follows ``prefers-color-scheme``. */
+export declare const TOUR_APPEARANCES: readonly ["dark", "light", "auto"];
+export type TourAppearance = (typeof TOUR_APPEARANCES)[number];
+export declare const kebab: (key: string) => string;
+/** ``accentFg`` → ``--steppy-tour-accent-fg``. */
+export declare const themeProperty: (key: TourThemeKey) => string;
+/** The private property the stylesheet reads (``--_pw-accent-fg``). */
+export declare const privateProperty: (key: TourThemeKey) => string;
+/** Custom-property declarations for a theme; unknown keys and empty values are dropped. */
+export declare function themeDeclarations(theme: TourTheme | null | undefined): Map<string, string>;

package/dist/types/ui/tokens.d.ts

@@ -51,7 +51,44 @@ export declare const TOUR_DEFAULTS: {
     readonly accentFg: "#ffffff";
     readonly focus: "#f09a6a";
     readonly scrim: "rgba(31, 29, 26, 0.45)";
+    readonly border: "none";
     readonly radius: "6px";
+    readonly width: "320px";
+    readonly padding: "8px 12px";
+    readonly shadow: "0 4px 12px rgba(0, 0, 0, 0.2)";
+    readonly fontFamily: "inherit";
+    readonly fontSize: "14px";
+    readonly lineHeight: "1.4";
+    readonly titleSize: "1em";
+    readonly titleWeight: "600";
+    readonly buttonRadius: "4px";
+    readonly buttonPadding: "4px 10px";
+    readonly buttonWeight: "inherit";
+    readonly ringWidth: "2px";
+};
+/** ``appearance="light"``: a light bubble, same accent; AA-checked like the dark one. */
+export declare const TOUR_LIGHT: {
+    readonly bubbleBg: "#ffffff";
+    readonly bubbleFg: "#1f1d1a";
+    readonly muted: "#5b6b64";
+    readonly focus: "#a8410e";
+    readonly border: "1px solid #e1ddd1";
+    readonly accent: "#a8410e";
+    readonly accentFg: "#ffffff";
+    readonly scrim: "rgba(31, 29, 26, 0.45)";
+    readonly radius: "6px";
+    readonly width: "320px";
+    readonly padding: "8px 12px";
+    readonly shadow: "0 4px 12px rgba(0, 0, 0, 0.2)";
+    readonly fontFamily: "inherit";
+    readonly fontSize: "14px";
+    readonly lineHeight: "1.4";
+    readonly titleSize: "1em";
+    readonly titleWeight: "600";
+    readonly buttonRadius: "4px";
+    readonly buttonPadding: "4px 10px";
+    readonly buttonWeight: "inherit";
+    readonly ringWidth: "2px";
 };
 /** A token value inside a ``css`` template (inserted verbatim, never data). */
 export declare const cssValue: (value: string | number) => CSSResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steppy/player",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Steppy players — the interactive guide (Lit web component + manifest validator) and the in-app tour overlay",
   "license": "Apache-2.0",
   "repository": {