@docentjs/dom 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,293 @@
+import { Alignment, ControllerOptions, Labels, Media, Placement, RenderContext, Renderer, Side, StorageAdapter, Target, TargetSpec, Theme, Tour, TourController, defineTour } from "@docentjs/core";
+//#region src/content.d.ts
+export declare function isSafeUrl(url: string): boolean;
+export declare function renderBody(doc: Document, body: string, format?: 'text' | 'markdown'): DocumentFragment;
+export declare function renderMedia(doc: Document, media: Media): HTMLElement | null;
+//#endregion
+//#region src/theme.d.ts
+/** Token → CSS custom property (without the `--docent-` prefix). */
+export declare const THEME_VARS: Record<keyof Theme, string>;
+/** Write theme tokens as inline custom properties on an element. Clears unset ones. */
+export declare function applyTheme(el: HTMLElement, theme: Theme | undefined): void;
+export declare function mergeThemes(...themes: Array<Theme | undefined>): Theme;
+/**
+ * Regions of the built-in popover that can be replaced. Custom content is
+ * projected through native Shadow DOM slots, so it lives in the page's DOM
+ * and keeps the page's CSS and framework behaviour.
+ */
+type SlotName = 'header' | 'title' | 'close' | 'body' | 'media' | 'footer' | 'progress' | 'buttons';
+/**
+ * What a slot renderer returns:
+ * - a `Node` replaces the region,
+ * - a string replaces it with text,
+ * - `null` removes the region,
+ * - `undefined` keeps the default.
+ */
+type SlotContent = Node | string | null | undefined;
+type SlotRenderer = (ctx: RenderContext, doc: Document) => SlotContent;
+type PopoverSlots = Partial<Record<SlotName, SlotRenderer>>;
+/**
+ * A named bundle of theme, slots and CSS. Tours pick one by name through
+ * `options.template`, which keeps the JSON builder-friendly while the code
+ * that defines the template stays in the app.
+ */
+interface PopoverTemplate {
+  theme?: Theme;
+  slots?: PopoverSlots;
+  /** Extra CSS injected into the shadow root while this template is active. */
+  css?: string;
+}
+/**
+ * Replace the whole popover. The renderer still draws the overlay and
+ * spotlight, positions `container`, sets `data-side` and `--docent-arrow`
+ * on it, and handles keyboard, focus and state. You draw everything inside.
+ */
+interface HeadlessPopover {
+  /** Render the step into `container`. Return a cleanup to run before the next step. */
+  render(ctx: RenderContext, container: HTMLElement): undefined | (() => void);
+}
+//#endregion
+//#region src/renderer.d.ts
+interface DomRendererOptions {
+  /** Document to render into. Defaults to the global document. */
+  document?: Document;
+  /** Override button and progress labels for every tour. */
+  labels?: Labels;
+  /** Distance between target and popover, in px. */
+  gap?: number;
+  /** Spotlight defaults when a tour sets none. */
+  spotlight?: {
+    padding?: number;
+    radius?: number;
+  };
+  /** Base theme tokens. Tours and templates layer on top. */
+  theme?: Theme;
+  /** Replace regions of the built-in popover. */
+  slots?: PopoverSlots;
+  /** Named templates that tours select with `options.template`. */
+  templates?: Record<string, PopoverTemplate>;
+  /** Template to use when a tour names none. */
+  template?: string;
+  /** Bring your own popover. Overlay, spotlight, positioning and keys stay. */
+  headless?: HeadlessPopover;
+  /** Extra CSS injected into the shadow root. */
+  css?: string;
+  /**
+   * Below this viewport width the popover docks to the bottom edge as a sheet
+   * instead of floating beside the target. Default 480; 0 disables.
+   */
+  sheetBreakpoint?: number;
+  /** Scroll past sticky/fixed headers and footers that cover the target. Default true. */
+  avoidOcclusion?: boolean;
+}
+export declare class DomRenderer implements Renderer {
+  private readonly doc;
+  private readonly options;
+  private host;
+  private shadow;
+  private overlay;
+  private templateStyle;
+  private popover;
+  private arrow;
+  private headlessContainer;
+  private ctx;
+  private target;
+  private cleanups;
+  private frame;
+  private previousFocus;
+  /** Set once per step after the sheet has scrolled the target clear. */
+  private sheetAdjusted;
+  constructor(options?: DomRendererOptions);
+  hasTarget(target: Target): boolean;
+  waitForTarget(target: Target, timeoutMs: number, signal: AbortSignal): Promise<boolean>;
+  currentRoute(): string;
+  show(ctx: RenderContext): void;
+  hide(): void;
+  /** Re-measure and re-position everything. Safe to call often. */
+  update(): void;
+  /**
+   * The visible area in layout-viewport coordinates. Uses the visual viewport
+   * so pinch zoom, the on-screen keyboard and pages that overflow on mobile
+   * (where `innerWidth` grows past the screen) all position correctly.
+   */
+  private viewport;
+  private isSheet;
+  /** In sheet mode, scroll once so the target is not hidden behind the sheet. */
+  private keepClearOfSheet;
+  /** Run after a smooth scroll settles (scrollend, or a short fallback), or right away. */
+  private afterScroll;
+  private template;
+  private buildDefault;
+  private buildHeadless;
+  private setTemplateCss;
+  private mount;
+  private teardownStep;
+  private blocksInteraction;
+  /** Returns true when a smooth scroll was started (callers must wait for it to settle). */
+  private scrollIntoView;
+  private scheduleUpdate;
+  private listen;
+  private onKeydown;
+  /** Keep Tab cycling inside the popover when focus is already in it. */
+  private trapTab;
+  private wireAdvance;
+}
+//#endregion
+//#region src/create.d.ts
+interface CreateTourOptions extends Omit<ControllerOptions, 'tour' | 'renderer'> {
+  renderer?: DomRendererOptions;
+  /** Follow browser navigation to pause and resume route-bound steps. Default true. */
+  followRoutes?: boolean;
+}
+/**
+ * A controller pre-wired for the browser: DOM renderer, localStorage
+ * persistence and route change tracking.
+ */
+export declare class DomTourController extends TourController {
+  private readonly cleanups;
+  constructor(tour: Tour, options?: CreateTourOptions);
+  destroy(): Promise<void>;
+}
+/** Create a browser-ready tour. Call `.start()` or `.resume()` on the result. */
+export declare function createTour(tour: Tour, options?: CreateTourOptions): DomTourController;
+//#endregion
+//#region src/position.d.ts
+interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+interface Size {
+  width: number;
+  height: number;
+}
+/**
+ * The visible area, in the same coordinate space as the anchor. `x`/`y` are
+ * the visual viewport's offset within the layout viewport (non-zero when the
+ * page is pinch-zoomed or overflows horizontally on mobile).
+ */
+interface Viewport extends Size {
+  x?: number;
+  y?: number;
+}
+interface PositionInput {
+  /** The spotlighted area, in viewport coordinates. */
+  anchor: Rect;
+  floating: Size;
+  viewport: Viewport;
+  placement: Placement;
+  /** Distance between anchor and popover. */
+  gap?: number;
+  /** Minimum distance from the viewport edges. */
+  edgePadding?: number;
+  /** Arrow size; keeps the arrow clear of the popover corners. */
+  arrowSize?: number;
+}
+interface PositionResult {
+  x: number;
+  y: number;
+  side: Side;
+  align: Alignment;
+  /** Arrow offset along the popover's cross axis, from its top-left corner. */
+  arrow: number;
+}
+export declare function parsePlacement(placement: Placement): {
+  side: Side | 'auto';
+  align: Alignment;
+};
+/** Free space between the anchor and the viewport edge on each side. */
+export declare function availableSpace(anchor: Rect, viewport: Viewport): Record<Side, number>;
+export declare function computePosition(input: PositionInput): PositionResult;
+/** Centre a popover in the viewport, for steps without a target. */
+export declare function centerPosition(floating: Size, viewport: Viewport): {
+  x: number;
+  y: number;
+};
+/** Grow a rect on every side. */
+export declare function inflate(rect: Rect, by: number): Rect;
+//#endregion
+//#region src/occlusion.d.ts
+interface Occluder {
+  el: Element;
+  rect: DOMRect;
+  /** Which edge of the target it covers. */
+  edge: 'top' | 'bottom';
+}
+/**
+ * Find a pinned element covering the target's top or bottom edge.
+ * `ignore` is our own host, which sits above everything.
+ */
+export declare function findOccluder(target: Element, ignore: Element | null, viewport: Viewport): Occluder | null;
+/**
+ * Scroll so nothing pinned covers the target. Returns true if it scrolled.
+ * Runs at most twice to handle a header and a footer together.
+ */
+export declare function uncover(target: Element, ignore: Element | null, viewport: Viewport, margin?: number): boolean;
+//#endregion
+//#region src/overlay.d.ts
+export declare function holePath(viewport: Size, hole: Rect, radius: number): string;
+interface OverlayUpdate {
+  /** Target rect in viewport coordinates, or `null` for a modal step. */
+  target: Rect | null;
+  padding: number;
+  radius: number;
+}
+export declare class Overlay {
+  readonly el: HTMLDivElement;
+  readonly blocker: HTMLDivElement;
+  private lastHole;
+  constructor(doc: Document);
+  /** Current hole, padded, in viewport coordinates. */
+  get hole(): Rect | null;
+  update(viewport: Size, { target, padding, radius }: OverlayUpdate, block: boolean): void;
+}
+//#endregion
+//#region src/popover.d.ts
+export declare const DEFAULT_LABELS: Required<Labels>;
+interface PopoverParts {
+  el: HTMLDivElement;
+  arrow: HTMLDivElement;
+  /** Element to focus when the step opens. */
+  initialFocus: HTMLElement;
+  /** Light-DOM nodes to append to the shadow host so they project into slots. */
+  slotted: Element[];
+}
+export declare function formatProgress(template: string, current: number, total: number): string;
+/**
+ * Resolve slot overrides into light-DOM elements carrying `slot="<name>"`.
+ * A `null` result projects an empty element, which suppresses the fallback.
+ */
+export declare function resolveSlots(doc: Document, slots: PopoverSlots, ctx: RenderContext): Element[];
+export declare function buildPopover(doc: Document, ctx: RenderContext, labels?: Labels, slots?: PopoverSlots): PopoverParts;
+/** Wrapper used in headless mode: a positioned shell that projects the app's own popover. */
+export declare function buildHeadlessShell(doc: Document): {
+  el: HTMLDivElement;
+  arrow: HTMLDivElement;
+};
+//#endregion
+//#region src/storage.d.ts
+/**
+ * `localStorage`-backed adapter. Falls back to memory when storage is
+ * unavailable (private mode, blocked cookies, SSR).
+ */
+export declare function createLocalStorage(storage?: Storage): StorageAdapter;
+//#endregion
+//#region src/target.d.ts
+type QueryRoot = Document | DocumentFragment | Element;
+/** Attribute that `{ name }` targets resolve through. */
+export declare const NAME_ATTRIBUTE = "data-docent";
+export declare function toSpec(target: Target): TargetSpec;
+/** Selectors to try, in order, for a target. */
+export declare function candidateSelectors(target: Target): string[];
+/** Query the root, then every open shadow root beneath it. */
+export declare function queryAllDeep(root: QueryRoot, selector: string): Element[];
+export declare function resolveTarget(target: Target, root?: QueryRoot): Element | null;
+/**
+ * Resolve now, or watch the DOM until the target appears, the timeout passes,
+ * or the signal aborts. Resolves `null` when it never shows up.
+ */
+export declare function waitForTarget(target: Target, timeoutMs: number, signal?: AbortSignal, root?: QueryRoot): Promise<Element | null>;
+//#endregion
+export { type CreateTourOptions, type DomRendererOptions, type HeadlessPopover, type Occluder, type PopoverSlots, type PopoverTemplate, type PositionInput, type PositionResult, type QueryRoot, type Rect, type Size, type SlotContent, type SlotName, type SlotRenderer, defineTour };
+//# sourceMappingURL=index.d.ts.map