@webority/ui-elements 0.148.0 → 0.150.0

package/types/server/serverActions.d.ts

@@ -0,0 +1,33 @@
+/** Id of the shared confirm dialog. */
+export declare const CONFIRM_DIALOG_ID: string;
+/** Every value data-wui-confirm-tone takes; absent is a plain confirmation. */
+export declare const CONFIRM_TONES: readonly string[];
+/** Every value data-wui-flash-variant takes. */
+export declare const FLASH_VARIANTS: readonly ["success", "info", "warning", "danger"];
+type ToastVariant = (typeof FLASH_VARIANTS)[number];
+export declare const isToastVariant: (value: string) => value is ToastVariant;
+/** Where a toast waits across the reload or redirect of data-wui-post. */
+export declare const FLASH_STORAGE_KEY: string;
+/** The words the behaviours say on their own. */
+export declare const SERVER_ACTION_TEXT: Readonly<{
+    confirmTitle: string;
+    confirmLabel: string;
+    cancelLabel: string;
+    failed: string;
+    forbidden: string;
+    network: string;
+}>;
+/**
+ * Ask in the shared confirm dialog from script, and on Confirm run `proceed` with `trigger` let
+ * through: a click on it, or a submit of it, that `proceed` makes does not ask its own
+ * data-wui-confirm question a second time.
+ *
+ * @param trigger  the link, button or form the person acted on
+ * @param options  the dialog's words, and the tone when the action is dangerous
+ * @param proceed  runs once the person confirms
+ */
+export declare function confirmAction(trigger: Element, options: unknown, proceed: () => void): void;
+export declare function storeFlash(message: string | null | undefined, variant: string): void;
+/** Wire the delegated confirm and post listeners once per document, and toast every flash under `root`. */
+export declare function initServerActions(root?: Document | Element): void;
+export {};

package/types/server/serverTable.d.ts

@@ -0,0 +1,48 @@
+import { type WuiResult } from "./wuiHttp.ts";
+/** Typing pause before a search box refetches. */
+export declare const SEARCH_DEBOUNCE_MS: number;
+/** What the table says when the page gives it nothing more specific. */
+export declare const SERVER_TABLE_TEXT: Readonly<{
+    loading: string;
+    error: string;
+    network: string;
+    forbidden: string;
+    retry: string;
+    actionFailed: string;
+    actionForbidden: string;
+    empty: string;
+}>;
+/** A value a query param takes; null, undefined and "" remove the param. */
+export type QueryValue = string | number | null | undefined;
+/** The params `setQuery` replaces; an array repeats its param. */
+export type QueryPatch = Record<string, QueryValue | QueryValue[]>;
+export interface SaveRowOptions {
+    url?: string;
+    method?: string;
+    body?: BodyInit;
+    key?: string | number | null;
+    row?: HTMLTableRowElement | string;
+}
+export interface ReloadOptions {
+    quiet?: boolean;
+}
+export interface ServerTableSelection {
+    keys(): (string | undefined)[];
+    count(): number;
+    allMatching(): boolean;
+    selectAllMatching(): void;
+    clear(): void;
+}
+export interface ServerTableHandle {
+    el: HTMLElement;
+    reload(options?: ReloadOptions): Promise<WuiResult | null>;
+    query(): URLSearchParams;
+    setQuery(patch?: QueryPatch): Promise<WuiResult>;
+    saveRow(options?: SaveRowOptions): Promise<boolean>;
+    setActiveRow(key: string | null | undefined): void;
+    selection: ServerTableSelection;
+}
+/** Wire every server-paged table under `root`. */
+export declare function initServerTables(root?: Document | Element): void;
+/** The handle of the server table `el` belongs to, or null. */
+export declare function getServerTable(el: Node | null | undefined): ServerTableHandle | null;

package/types/server/shellParts.d.ts

@@ -0,0 +1,24 @@
+/** A count above this shows as "99+" (UnreadCap in AppShellNotificationsTagHelper.cs). */
+export declare const UNREAD_CAP: number;
+/** One year, in seconds: how long the remembered rail state lasts. */
+export declare const COLLAPSED_COOKIE_MAX_AGE: number;
+export interface ShellHandle {
+    el: HTMLElement;
+    setUnread(n: number): void;
+    refreshNotifications(): Promise<void>;
+    collapsed: boolean;
+}
+/**
+ * Write the remembered rail state the server reads on the next request ("1" collapsed, "0" expanded).
+ * A sandboxed frame without allow-same-origin throws SecurityError on cookie access; it remembers nothing.
+ */
+export declare function writeCollapsedCookie(name: string, collapsed: boolean, doc?: Pick<Document, "cookie">): void;
+/**
+ * Add or remove one folded nav group key in the cookie the server reads on the first paint. The value is
+ * the folded keys joined by "." (keys are lower-case letters, digits and hyphens, so "." cannot clash).
+ */
+export declare function writeFoldedCookie(name: string, key: string | undefined, folded: boolean, doc?: Pick<Document, "cookie">): void;
+/** Wire the shell parts under `root`. */
+export declare function initShellParts(root?: ParentNode): void;
+/** The handle of the shell `el` belongs to, or null. */
+export declare function getShell(el: Element | null): ShellHandle | null;

package/types/server/toastAction.d.ts

@@ -0,0 +1,7 @@
+import { type WuiResult, type WuiToastAction } from "./wuiHttp.ts";
+export declare const TOAST_ACTION_MS: number;
+export declare function wuiHost(): WuiHost;
+/** Toasts a settled answer's message, with its action button when it carries one. */
+export declare function showResultToast(result: WuiResult | null | undefined, variant?: string): void;
+/** Posts the action and settles it: its answer toasts (and may carry an action of its own), and the tables reload. */
+export declare function runToastAction(action: WuiToastAction): Promise<void>;

package/types/server/toastHeader.d.ts

@@ -0,0 +1,8 @@
+export interface ToastActionHeader {
+    label: string;
+    url: string;
+    method: string;
+}
+export declare const TOAST_ACTION_METHODS: readonly string[];
+/** Reads the header's JSON. A value that is not a usable action is warned about and ignored. */
+export declare function parseToastAction(raw: string | null | undefined): ToastActionHeader | null;

package/types/server/unsavedChanges.d.ts

@@ -0,0 +1,17 @@
+/** The words the guard says on its own. */
+export declare const UNSAVED_TEXT: Readonly<{
+    title: string;
+    message: string;
+    leaveLabel: string;
+}>;
+export declare function formValues(form: HTMLFormElement): string;
+/**
+ * The starting values `base` with every field that joined the form since they were taken added at its
+ * current value. A field `base` already holds keeps its starting value, so an edit made meanwhile
+ * still counts.
+ */
+export declare function withAddedFields(form: HTMLFormElement, base: string): string;
+/** Take the starting values of every guarded form under `root`, and wire the guard once per document. */
+export declare function initUnsavedChanges(root?: Document | Element): void;
+/** The guarded form's current values count as saved: for a page that saves the form by its own fetch. */
+export declare function resetUnsavedChanges(form: HTMLElement | null): void;

package/types/server/wuiHttp.d.ts

@@ -0,0 +1,86 @@
+/** Name of the meta tag `<app-csrf-meta />` renders. */
+export declare const CSRF_META_NAME = "wui-csrf";
+/** Header the token travels in when the meta tag names none. */
+export declare const DEFAULT_CSRF_HEADER = "RequestVerificationToken";
+export interface CsrfNames {
+    metaName: string;
+    header: string;
+}
+/**
+ * Sets the names the antiforgery token travels under, for a host whose layout renders its own meta tag or whose
+ * antiforgery header is not the default. Call before the first request; no argument restores the defaults.
+ */
+export declare function configureCsrf({ metaName, header }?: Partial<CsrfNames>): void;
+/** Request header naming every request this layer sends; the server side is `WuiRequest.Header`. */
+export declare const WUI_REQUEST_HEADER = "Wui-Request";
+/** Response headers of the fragment contract. */
+export declare const WUI_HEADERS: Readonly<{
+    fragment: string;
+    message: string;
+    redirect: string;
+    result: string;
+    keepOpen: string;
+    toastVariant: string;
+    toastAction: string;
+    data: string;
+    next: string;
+}>;
+/**
+ * Every `kind` a request settles as.
+ * ok: 2xx. validation: 422 (the form re-rendered with its errors). forbidden: 403.
+ * client: any other 4xx. server: 5xx. network: no answer at all. aborted: the caller (or a newer
+ * request on the same queue) cancelled it. stale: answered, but a newer request on the same queue
+ * started meanwhile. session: the sign-in expired and the browser is being sent to sign in.
+ */
+export type HttpKind = "ok" | "validation" | "forbidden" | "client" | "server" | "network" | "aborted" | "stale" | "session";
+export declare const HTTP_KINDS: readonly HttpKind[];
+export interface WuiToastAction {
+    label: string;
+    url: string;
+    method: string;
+}
+export interface WuiFetchOptions {
+    method?: string;
+    body?: BodyInit;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    /** Replaces the session-expiry navigation (tests, or a host that wants to show a "signed out" notice first). */
+    navigate?: (url: string) => void;
+}
+export interface WuiResult {
+    kind: HttpKind;
+    ok: boolean;
+    status: number;
+    html: string;
+    response: Response | null;
+    message: string | null;
+    redirect: string | null;
+    result: string | null;
+    keepOpen: boolean;
+    toastVariant: string | null;
+    toastAction: WuiToastAction | null;
+    fragment: boolean;
+    data: unknown;
+    next: string | null;
+}
+export interface RequestQueue {
+    run(url: string, options?: WuiFetchOptions): Promise<WuiResult>;
+    abort(): void;
+}
+/** The antiforgery token from the configured meta tag (default meta name wui-csrf), or null when the page has none. */
+export declare function readCsrf(doc?: Document): {
+    header: string;
+    token: string;
+} | null;
+/** Classify a status code. Exported so a caller holding a raw Response applies the same rule. */
+export declare function classifyStatus(status: number): HttpKind;
+/**
+ * Fetch `url` and settle as a classified result; never rejects for an HTTP or network failure; it rejects with a TypeError when an answer's Wui-Data header is not JSON (a server defect).
+ */
+export declare function wuiFetch(url: string, options?: WuiFetchOptions): Promise<WuiResult>;
+/**
+ * A "latest wins" lane for one control (a table, a search box, a modal): each `run` aborts the
+ * request before it, and an answer that lands after a newer request started settles as `stale`
+ * so a slow old page can never overwrite a newer one.
+ */
+export declare function createRequestQueue(): RequestQueue;

package/types/shortcutKeys.d.ts

@@ -0,0 +1,59 @@
+/** `<html data-wui-shortcuts="off">` turns every single-key shortcut off (a person's setting). */
+export declare const SHORTCUTS_OFF_ATTRIBUTE = "data-wui-shortcuts";
+/** Marks the element a set of shortcuts belongs to (a split view, a queue page's list). */
+export declare const SHORTCUT_SCOPE_ATTRIBUTE = "data-shortcut-scope";
+/** Raised (bubbling, cancelable) by <wui-shortcuts> for a listed key it has no built-in action for. */
+export declare const SHORTCUT_EVENT = "wui:shortcut";
+export declare const SHORTCUT_TEXT: {
+    title: string;
+    close: string;
+    help: string;
+};
+/** The list keys J, K and Enter, as a legend lists them. */
+export declare const LIST_KEYS: {
+    key: string;
+    label: string;
+}[];
+/** The X key of a list whose items carry a checkbox. */
+export declare const SELECT_KEY: {
+    key: string;
+    label: string;
+};
+type KeyLike = Pick<KeyboardEvent, "key"> & Partial<Pick<KeyboardEvent, "ctrlKey" | "metaKey" | "altKey" | "shiftKey">>;
+type HandlerMap = Record<string, ((event: KeyboardEvent) => void) | undefined>;
+/**
+ * The name a keydown goes by in a handler map: `j`, `k`, `x` or any other single character in
+ * lower case, and `enter`, `slash`, `help` (`?`) and `esc`. Null for a key held with Ctrl, Cmd or
+ * Alt (those belong to the browser and the screen reader) and for keys with no name here.
+ */
+export declare function shortcutName(event: KeyLike | null | undefined): string | null;
+/**
+ * How a key is written on its chip and in `data-shortcut`: one character in upper case, or
+ * `Enter`, `Esc`, `/` and `?` for their names. Anything longer (`Shift A`) is kept as written.
+ */
+export declare function shortcutKey(key: string | undefined): string;
+/** The `aria-keyshortcuts` value for a chip's text: words joined with `+`, `Esc` as `Escape`. */
+export declare function ariaKeyShortcuts(key: string | undefined): string;
+/** A key pressed here is text, not a shortcut. A checkbox or a button keeps its shortcuts. */
+export declare function isTypingTarget(node: Node | null | undefined): boolean;
+/** True when the person has turned single-key shortcuts off for the page. */
+export declare function shortcutsOff(doc?: Document | null | undefined): boolean;
+/**
+ * Whether a key pressed on `target` belongs to `scope`: anything inside it does, and with focus on
+ * the page itself (nothing focused) the first scope on the page does. No scope takes every key.
+ */
+export declare function inShortcutScope(target: Node | null | undefined, scope: Element | null): boolean;
+/**
+ * Runs the handler a keydown names, from a map keyed by `shortcutName` (`{ j, k, enter, x, slash,
+ * help, esc, e }`). Skips a key already handled, a key typed into a field, a key outside `scope`,
+ * and Enter on a link or button (the browser opens those). Returns true when a handler ran; the
+ * key's default is then prevented.
+ */
+export declare function runShortcut(event: KeyboardEvent, handlers: HandlerMap | null | undefined, scope?: Element | null): boolean;
+/**
+ * Moves focus one step through `items` (J is +1, K is -1) and returns the item focused. It starts
+ * from the focused item (or the row holding the focused control), else the item marked
+ * `aria-current`, else the first or last; it stops at either end.
+ */
+export declare function moveFocus(items: HTMLElement[], step: number): HTMLElement | null;
+export {};

package/types/statusIconImages.d.ts

@@ -0,0 +1 @@
+export declare const STATUS_IMAGES: Readonly<Record<string, string>>;

package/types/statusIcons.d.ts

@@ -0,0 +1,12 @@
+import { ElementBase } from "./elementBase.ts";
+export declare const STATUS_TONES: string[];
+/**
+ * `<wui-status-icon tone="delete" size="104">` — decorative, aria-hidden. The dialog's
+ * title and message carry the meaning.
+ */
+export declare class WuiStatusIcon extends ElementBase {
+    static get observedAttributes(): string[];
+    connectedCallback(): void;
+    attributeChangedCallback(): void;
+    render(): void;
+}

package/types/stepperHeader.d.ts

@@ -0,0 +1,31 @@
+export type StepStatus = "pending" | "active" | "done" | "error" | "skipped";
+export type StepHeaderItem = {
+    index: number;
+    status: StepStatus;
+    className: string;
+    glyph: {
+        icon: string;
+    } | {
+        number: number;
+    };
+    current: boolean;
+    line: null | {
+        done: boolean;
+    };
+};
+/**
+ * Status from position: before active done, at active active, after pending; no active index means pending.
+ */
+export declare function deriveStepStatus(index: number, active: number | null | undefined): StepStatus;
+/**
+ * The header model both the stepper and the wizard draw: done check, error alert-triangle, skipped minus, else the step icon, else the number; className "step" or "step <status>"; a line after each step but the last when journey and connectors.
+ */
+export declare function stepperHeaderItems(steps: {
+    label: string;
+    status?: StepStatus;
+    icon?: string;
+}[], options: {
+    statusOf: (index: number) => StepStatus;
+    journey: boolean;
+    connectors: boolean;
+}): StepHeaderItem[];

package/types/submitOnce.d.ts

@@ -0,0 +1,3 @@
+export declare const SUBMIT_ONCE_ATTRIBUTE = "data-wui-submit-once";
+/** Blocks a second submit of a <form method="post"> while the first is in flight: marks the form data-wui-submit-pending, disables its submitter and shows it a spinner with aria-busy; skips forms with data-wui-submit-once="off" or target="_blank"; clears on pageshow. @param root */
+export declare function initSubmitOnce(root: Document | Element): void;

package/types/tableSelect.d.ts

@@ -0,0 +1,34 @@
+export declare const SELECT_ALL_LABEL = "Select all rows";
+export declare const SELECT_ROW_LABEL = "Select row";
+export declare const SELECT_CELL_CLASS = "wui-select-cell";
+/** `<th class="wui-select-cell">` holding the select-all box. */
+export declare function createSelectHeaderCell(doc?: Document): HTMLTableCellElement;
+/** `<td class="wui-select-cell">` holding one row's box, disabled when the row cannot be selected. */
+export declare function createSelectRowCell(doc?: Document, { disabled }?: {
+    disabled?: boolean;
+}): HTMLTableCellElement;
+/** The empty `<td class="wui-select-cell">` a totals row gets. */
+export declare function createSelectSpacerCell(doc?: Document): HTMLTableCellElement;
+/** Give each body row that has none its leading select cell. Safe to call after every row swap. */
+export declare function addRowSelectCells(rows: Iterable<HTMLTableRowElement>): void;
+/**
+ * Insert the whole select column into `table` once: the header box, a box on every body row and a
+ * spacer on every footer row. Returns the select-all box, or null when the table has no header row.
+ */
+export declare function addSelectColumn(table: HTMLTableElement): HTMLInputElement | null;
+/**
+ * Bring the header box and the row highlight in step with the body boxes: checked when every row
+ * is, indeterminate when some are. Returns the counts on the rows in the table now.
+ */
+export declare function syncSelectAll(table: HTMLTableElement): {
+    selected: number;
+    total: number;
+};
+/**
+ * Shift+click on a row box selects the range from the last row box clicked: every box between the
+ * two takes the state the clicked box just got. `onRange(boxes, checked)` receives the other boxes
+ * that changed (the clicked one raises its own `change`), for a table that keeps its selection
+ * outside the DOM. The anchor is forgotten once its row leaves the document, so a page swap never
+ * ranges across pages.
+ */
+export declare function attachShiftRange(table: HTMLTableElement, onRange?: (boxes: HTMLInputElement[], checked: boolean) => void): void;

package/types/textMatch.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @param text The label to split.
+ * @param query What the user typed. Surrounding whitespace is ignored.
+ * @returns Runs in order; joined, they equal `text`.
+ */
+export declare function matchSegments(text: string | null | undefined, query: string | null | undefined): {
+    text: string;
+    match: boolean;
+}[];

package/types/themeTransition.d.ts

@@ -0,0 +1,88 @@
+export type ThemeMode = "light" | "dark" | "auto";
+export type ThemeEffect = "wave" | "circle" | "slide" | "blinds" | "fade" | "none";
+export type ResolvedTheme = "light" | "dark";
+type Point = {
+    x: number;
+    y: number;
+};
+type KeyframeBox = {
+    width: number;
+    height: number;
+    to?: ResolvedTheme;
+    origin?: Point;
+};
+type ThemeKeyframe = {
+    clipPath: string;
+    opacity?: number;
+};
+export declare const THEME_MODES: readonly ThemeMode[];
+/** The page-wide effects a switch can run. `none` switches instantly. */
+export declare const THEME_EFFECTS: readonly ThemeEffect[];
+export declare const DEFAULT_THEME_EFFECT: ThemeEffect;
+export declare const DEFAULT_THEME_STORAGE_KEY = "theme";
+/** How long each effect takes to cross the screen, in ms. A caller's `duration` overrides it. */
+export declare const THEME_EFFECT_DURATION: Record<ThemeEffect, number>;
+/** Set on <html> for the length of a switch; the theme CSS keys the transition rules on it. */
+export declare const THEME_SWITCHING_CLASS = "wui-theme-switching";
+/**
+ * Fired on `document` by applyTheme, with `{ mode, preference }`: `mode` is the theme the page
+ * shows (light or dark) and `preference` the choice behind it (light, dark or auto). Every toggle
+ * on a page follows one press through it, and a page that draws its own colours redraws on it.
+ */
+export declare const THEME_CHANGE_EVENT = "wui:theme:change";
+/** The theme the page actually shows for a mode: `auto` follows the system preference. */
+export declare function resolveTheme(mode: string | undefined): ResolvedTheme;
+/**
+ * The stored choice, or `auto` (follow the device) when nothing valid is stored. A control that
+ * offers only light and dark shows an `auto` as resolveTheme() reads it; the page stays on auto.
+ */
+export declare function readStoredTheme(storageKey?: string): ThemeMode;
+/** Remember a choice. Storage failures are swallowed: the page still switches for this visit. */
+export declare function storeTheme(mode: ThemeMode, storageKey?: string): void;
+/** Write the mode and its resolved theme onto <html>, which is where the design system reads them. */
+export declare function applyTheme(mode: ThemeMode): void;
+export declare const THEME_BOOT_SCRIPT_BODY: string;
+/**
+ * The source of the inline `<head>` script that puts the stored theme on `<html>` before first
+ * paint: `data-theme` (light, dark, or auto when nothing is stored) and the resolved
+ * `data-bs-theme`, then follows device changes while on auto. Render it as the content of a
+ * `<script>` before any stylesheet; under a Content Security Policy give that script the page's
+ * nonce. The text is fixed for a given key, so a hash-based policy works too.
+ *
+ * @param storageKey The key the toggle stores the choice under.
+ * @returns JavaScript source, without the `<script>` tags.
+ */
+export declare function themeBootScript(storageKey?: string): string;
+/** The mode a press moves to: light to dark to (auto to) light. */
+export declare function nextTheme(mode: string, { includeAuto }?: {
+    includeAuto?: boolean;
+}): ThemeMode;
+/**
+ * Re-apply an `auto` choice when the system preference changes while the page is open. Returns
+ * the function that stops listening.
+ */
+export declare function watchSystemTheme(onChange: (theme: ResolvedTheme) => void): () => void;
+/**
+ * The clip-path keyframes of one effect, from nothing of the new page showing to all of it.
+ * `to` is the resolved theme the page is moving to: dark comes up from the bottom and light
+ * comes down from the top, for the effects that have a direction. `origin` is where a circle
+ * starts, in viewport px; it defaults to the centre.
+ */
+export declare function themeKeyframes(effect: ThemeEffect, { width, height, to, origin }: KeyframeBox): ThemeKeyframe[];
+/**
+ * Run `apply` (the function that flips the page to the new theme) under the chosen effect.
+ * Resolves to true when it animated and false when it switched instantly.
+ *
+ * @param apply Writes the new theme to the page (applyTheme, store, your own state).
+ * @param options.effect One of THEME_EFFECTS.
+ * @param options.to The resolved theme being applied; decides the direction.
+ * @param options.origin Where a circle starts, in viewport px.
+ * @param options.duration Length in ms; defaults per effect (THEME_EFFECT_DURATION).
+ */
+export declare function transitionTheme(apply: () => void, { effect, to, origin, duration, }?: {
+    effect?: ThemeEffect;
+    to?: ResolvedTheme;
+    origin?: Point;
+    duration?: number;
+}): Promise<boolean>;
+export {};

package/types/toastTypes.d.ts

@@ -0,0 +1,20 @@
+export type ToastVariant = "success" | "info" | "warning" | "danger";
+export type ToastAnimation = "rise" | "organic" | "jelly" | "spring";
+export type ToastShape = "rounded" | "pill" | "sharp";
+export type ToastSurface = "auto" | "inverse";
+export interface ToastOptions {
+    variant?: ToastVariant | null;
+    duration?: number;
+    delay?: number;
+    title?: string;
+    action?: {
+        label?: string;
+        onClick?: () => void;
+    };
+    id?: string;
+    html?: string;
+    animation?: ToastAnimation | null;
+    shape?: ToastShape | null;
+    surface?: ToastSurface | null;
+    progress?: number;
+}

package/types/tokenCommit.d.ts

@@ -0,0 +1,13 @@
+/** KeyboardEvent.key for a separator name, or undefined for an unknown name. */
+export declare const separatorKey: (name: string) => string | undefined;
+/** The character a separator name splits pasted text on, or undefined for an unknown name. */
+export declare const separatorChar: (name: string) => string | undefined;
+/**
+ * Split text on ANY of the given characters into trimmed, non-empty tokens. Text containing
+ * none of them comes back as a single token (or none, when it is blank).
+ *
+ * @param chars Single-character separators.
+ */
+export declare function splitTokens(text: string | null | undefined, chars: string[]): string[];
+/** Whether the text contains any of the separator characters. */
+export declare const hasSeparator: (text: string | null | undefined, chars: string[]) => boolean;

package/types/tourAdvance.d.ts

@@ -0,0 +1,51 @@
+type AdvanceStep = {
+    target?: string;
+    advanceOn?: string;
+    actionLabel?: string;
+};
+type AdvanceView = {
+    layer: HTMLElement;
+    spot: HTMLElement;
+    card: HTMLElement;
+};
+type Target = HTMLElement | SVGElement;
+/**
+ * Show the step's cue, or clear the previous step's: the click-through spotlight, the tapping
+ * pointer, the hint above the buttons and Next as a link. Call it once per step shown, before the
+ * card is placed, since the hint changes the card's height.
+ * @param host the <wui-tour> element, which carries `advance-label`
+ * @param view the tour's layer and its spot and card
+ * @param step
+ * @param target the step's target
+ * @returns the hint shown, for the step's announcement; empty when there is none
+ */
+export declare function renderAdvance(host: HTMLElement, { layer, spot, card }: AdvanceView, step: AdvanceStep | null, target: Target | null): string;
+/**
+ * Start listening for the step's advance action. Called each time a step shows; the returned
+ * function is called when that step ends or the tour closes.
+ * @param step
+ * @param target the step's target
+ * @param advance moves the tour to the next step
+ */
+export declare function bindAdvance(step: AdvanceStep | null, target: Target | null, advance: () => void): () => void;
+/**
+ * Whether focus may rest on `node` while the step shows. Anything else is pulled back to the card.
+ * @param layer the tour's layer
+ * @param step
+ * @param target the step's target
+ * @param node the element that took focus
+ */
+export declare function keepsFocus(layer: HTMLElement, step: AdvanceStep | null, target: Target | null, node: Node): boolean;
+/**
+ * Keep Tab and Shift+Tab cycling through the card's buttons and, on a click-to-advance step,
+ * the target after them.
+ * @param e the Tab keydown
+ * @param context `active` is the focused element, read through the tour's shadow root when isolated.
+ */
+export declare function cycleFocus(e: KeyboardEvent, { card, active, step, target }: {
+    card: HTMLElement;
+    active: Element | null;
+    step: AdvanceStep | null;
+    target: Target | null;
+}): void;
+export {};

package/types/tourEnd.d.ts

@@ -0,0 +1,17 @@
+type EndDialogText = {
+    title: string;
+    message: string;
+    button: string;
+    nextLabel?: string;
+    nextHref?: string;
+};
+/**
+ * Show the closing dialog in the tour's layer. The tour awaits the returned promise, which settles
+ * with `"next"` when the person takes the next link, or with `"done"` when they dismiss the dialog
+ * by its button or Escape, or when `signal` aborts (the tour stopped), before it closes. The keys
+ * are listened for from the start, so an Escape while the step card is still leaving dismisses it too.
+ * @param layer the tour's layer, still on the page, holding the spot, the step card and the live region
+ * @param signal aborted when the tour is torn down while the dialog shows
+ */
+export declare function showEndDialog(layer: HTMLElement, text: EndDialogText, signal?: AbortSignal): Promise<"next" | "done">;
+export {};

package/types/tourGlobal.d.ts

@@ -0,0 +1,4 @@
+import { ElementBase } from "./elementBase.ts";
+export declare class WuiTourStep extends ElementBase {
+    constructor();
+}

package/types/tourIsolated.d.ts

@@ -0,0 +1,2 @@
+export declare const THEME_TOKENS: Record<string, string>;
+export declare const TOUR_ISOLATED_CSS: string;

package/types/tourMedia.d.ts

@@ -0,0 +1,19 @@
+interface MediaStep {
+    target?: string;
+    media?: string;
+    mediaAlt?: string;
+    mediaPoster?: string;
+    mediaType?: string;
+}
+interface MediaLabels {
+    pause: string;
+    play: string;
+}
+/**
+ * Show the step's media on the card, or none when the step has no `media`. Replaces the previous
+ * step's frame, so call it once per step shown, before the card is placed.
+ * @param card the tour card
+ * @param labels the pause button's name while the loop plays, and while it is paused
+ */
+export declare function renderMedia(card: HTMLElement, step: MediaStep, labels?: MediaLabels): void;
+export {};

package/types/tourMotion.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The card has been placed for a new step and is about to take focus. It fades and lifts in
+ * toward its target, after the spot's glide when the spot is moving, and reads `shown` once in.
+ * @param card the tour card
+ */
+export declare function enterCard(card: HTMLElement): void;
+/**
+ * The next step has been found and the card is about to change. The tour awaits a returned
+ * promise before it shows that step; nothing returned shows it at once.
+ * @param card the tour card
+ * @returns settles when the card has faded out
+ */
+export declare function leaveCard(card: HTMLElement): Promise<void> | null;
+/**
+ * Take the tour's layer off the page as the tour closes. Focus has not moved back yet, and the
+ * close event has not fired; neither may wait for an exit animation, so the layer fades out on its
+ * own, inert and click-through, and is removed when the fade ends.
+ * @param outer the element the tour appended to <body>
+ */
+export declare function removeLayer(outer: HTMLElement): void;

package/types/tourOpenMark.d.ts

@@ -0,0 +1 @@
+export declare const TOUR_OPEN_MARK: string;