@docentjs/dom 0.3.1 → 0.5.0

package/dist/index.d.ts

@@ -1,4 +1,11 @@
-import { Alignment, ControllerOptions, Docent, DocentEnvironment, DocentOptions, Labels, Media, Placement, RenderContext, Renderer, Side, StorageAdapter, Target, TargetSpec, Theme, Tour, TourController, defineTour } from "@docentjs/core";
+import { Alignment, ArrowStyle, ControllerOptions, Docent, DocentEnvironment, DocentOptions, Labels, Media, OverlayOptions, Placement, RenderContext, Renderer, Side, SpotlightOptions, SpotlightShape, StorageAdapter, Target, TargetSpec, Theme, Tour, TourController, defineTour } from "@docentjs/core";
+//#region src/arrows.d.ts
+export declare const CONNECTOR_STYLES: readonly ["line", "dashed", "dotted", "curve", "curve-dashed", "squiggle", "loop", "elbow", "sketch", "pin"];
+type ConnectorStyle = (typeof CONNECTOR_STYLES)[number];
+export declare function isConnector(style: ArrowStyle): style is ConnectorStyle;
+/** Space between target and popover for a style: connectors need room to be seen. */
+export declare function arrowGap(style: ArrowStyle): number;
+//#endregion
 //#region src/content.d.ts
 export declare function isSafeUrl(url: string): boolean;
 export declare function renderBody(doc: Document, body: string, format?: 'text' | 'markdown'): DocumentFragment;
@@ -34,6 +41,10 @@ type PopoverSlots = Partial<Record<SlotName, SlotRenderer>>;
 interface PopoverTemplate {
   theme?: Theme;
   slots?: PopoverSlots;
+  /** Arrow style for tours using this template. */
+  arrow?: ArrowStyle;
+  spotlight?: SpotlightOptions;
+  overlay?: OverlayOptions;
   /** Extra CSS injected into the shadow root while this template is active. */
   css?: string;
 }
@@ -55,11 +66,12 @@ interface DomRendererOptions {
   labels?: Labels;
   /** Distance between target and popover, in px. */
   gap?: number;
-  /** Spotlight defaults when a tour sets none. */
-  spotlight?: {
-    padding?: number;
-    radius?: number;
-  };
+  /** Spotlight defaults when a tour sets none: padding, radius, shape, ring. */
+  spotlight?: SpotlightOptions;
+  /** Arrow style when a tour sets none. Default `caret`. */
+  arrow?: ArrowStyle;
+  /** Overlay defaults when a tour sets none: style, color, opacity, blur. */
+  overlay?: OverlayOptions;
   /** Base theme tokens. Tours and templates layer on top. */
   theme?: Theme;
   /** Replace regions of the built-in popover. */
@@ -97,14 +109,42 @@ export declare class DomRenderer implements Renderer {
   private previousFocus;
   /** Set once per step after the sheet has scrolled the target clear. */
   private sheetAdjusted;
+  private connector;
+  /** Loaded on first use: connector styles cost nothing for tours that never use them. */
+  private connectorModule;
+  private connectorLoading;
+  /** Arrow, spotlight and overlay settings for the current step. */
+  private look;
+  /** Until then the step's own transition runs; scroll updates may animate. */
+  private settleUntil;
+  /** Play the connector draw-in on its next render. */
+  private drawConnector;
+  private trackingFrame;
   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;
+  /**
+   * Re-measure and re-position everything. Safe to call often. `tracking`
+   * marks updates caused by scroll or resize: once the step's own transition
+   * has finished, those follow the target instantly instead of trailing it.
+   */
+  update(tracking?: boolean): void;
+  /** Draw the connector for connector arrow styles; clear it otherwise. */
+  private renderConnector;
+  /** Fetch the connector module once, then draw with it. */
+  private loadConnector;
+  /** Add the connector layer and its styles, beneath any popover. */
+  private attachConnector;
+  private resolveLook;
+  /** Expose the look to the stylesheet as host attributes and variables. */
+  private applyLook;
+  /** The current transition duration in ms, from the --docent-duration token. */
+  private duration;
+  /** Disable transitions for this frame so scroll-driven moves stay glued to the target. */
+  private markTracking;
   /**
    * The visible area in layout-viewport coordinates. Uses the visual viewport
    * so pinch zoom, the on-screen keyboard and pages that overflow on mobile
@@ -263,15 +303,22 @@ interface OverlayUpdate {
   target: Rect | null;
   padding: number;
   radius: number;
+  shape?: SpotlightShape;
 }
 export declare class Overlay {
   readonly el: HTMLDivElement;
   readonly blocker: HTMLDivElement;
+  /** Hairline of light around the cutout. */
+  readonly ring: HTMLDivElement;
   private lastHole;
   constructor(doc: Document);
+  /** Move the ring to a rect; a zero-size rect collapses it (modal steps). */
+  private placeRing;
   /** Current hole, padded, in viewport coordinates. */
   get hole(): Rect | null;
-  update(viewport: Size, { target, padding, radius }: OverlayUpdate, block: boolean): void;
+  update(viewport: Size, { target, padding, radius, shape }: OverlayUpdate, block: boolean): void;
+  /** Exposed for the vignette style, which is centred on the cutout. */
+  private setCentre;
 }
 //#endregion
 //#region src/popover.d.ts
@@ -320,5 +367,5 @@ export declare function resolveTarget(target: Target, root?: QueryRoot): Element
  */
 export declare function waitForTarget(target: Target, timeoutMs: number, signal?: AbortSignal, root?: QueryRoot): Promise<Element | null>;
 //#endregion
-export { type CreateDocentOptions, 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 };
+export { type ConnectorStyle, type CreateDocentOptions, 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