@retoo/borda 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,1561 @@
+/** Event names emitted by the borda widget event bus. */
+declare enum BordaEvent {
+    /** Fired when the borda instance is destroyed. */
+    ON_BORDA_DESTROY = "borda:on-destroy",
+    /** Fired when the close button is clicked. */
+    ON_CLOSE_CLICK = "close:click",
+    /** Fired when the overlay backdrop is clicked or activated via Enter/Space. */
+    ON_OVERLAY_CLICK = "overlay:click",
+    /** Fired when the tour initialises (on mount). */
+    ON_TOUR_START = "tour:start",
+    /** Fired when the last step is completed. */
+    ON_TOUR_FINISH = "tour:finish",
+    /** Fired when the tour is dismissed before completion (close button, backdrop or Escape). */
+    ON_TOUR_CLOSE = "tour:close",
+    /** Fired when advancing to the next step (not on last step → finish). */
+    ON_TOUR_NEXT = "tour:next",
+    /** Fired when navigating to the previous step. */
+    ON_TOUR_PREV = "tour:prev",
+    /** Fired when the ArrowRight key is pressed during an active tour. */
+    ON_KEYBOARD_NEXT = "keyboard:next",
+    /** Fired when the ArrowLeft key is pressed during an active tour. */
+    ON_KEYBOARD_PREV = "keyboard:prev",
+    /** Fired when the active step changes. */
+    ON_TOUR_STEP_CHANGE = "tour:step-change",
+    /** Fired when the "don't show again" checkbox changes value. */
+    ON_SKIP_CHANGE = "skip:change",
+    /** Fired when the skip state is cleared via {@link BordaSkipApi.clear}. */
+    ON_SKIP_CLEAR = "skip:clear",
+    /** Fired when the widget becomes visible. */
+    ON_VISIBILITY_SHOW = "visibility:show",
+    /** Fired when the widget becomes hidden. */
+    ON_VISIBILITY_HIDE = "visibility:hide"
+}
+
+/** Callback invoked when a subscribed event is emitted. */
+type BordaEventHandler<T = unknown> = (data: T) => void;
+/** Internal storage: event name → set of handlers. */
+type BordaEventMap<T = unknown> = Map<BordaEvent, Set<BordaEventHandler<T>>>;
+/** Pub/sub event bus for communication between borda components. */
+interface BordaEventEmitter {
+    /** Subscribe a handler to an event. */
+    on(eventName: BordaEvent, handler: BordaEventHandler): void;
+    /** Subscribe a handler to an event; auto-unsubscribes after first call. */
+    once(eventName: BordaEvent, handler: BordaEventHandler): void;
+    /** Unsubscribe a specific handler from an event. */
+    off(eventName: BordaEvent, handler: BordaEventHandler): void;
+    /** Emit an event, calling all subscribed handlers with optional data. */
+    emit<T>(eventName: BordaEvent, data?: T): void;
+    /** Remove all handlers for a specific event. */
+    remove(eventName: BordaEvent): void;
+    /** Remove all handlers for all events. */
+    clear(): void;
+}
+
+/**
+ * Creates a pub/sub event emitter instance.
+ *
+ * @returns A {@link BordaEventEmitter} with `on`/`off`/`emit`/`remove`/`clear` methods.
+ */
+declare function useEventEmitter(): BordaEventEmitter;
+
+/** T-shirt size scale used for component sizing. */
+declare enum ComponentSize {
+    XS = "xs",
+    SM = "sm",
+    MD = "md",
+    LG = "lg",
+    XL = "xl",
+    XXL = "xxl"
+}
+/** Placement of a component within its container (3×3 grid). */
+declare enum ComponentPlacement {
+    TOP_START = "top-start",
+    TOP_CENTER = "top-center",
+    TOP_END = "top-end",
+    MIDDLE_START = "middle-start",
+    MIDDLE_CENTER = "middle-center",
+    MIDDLE_END = "middle-end",
+    BOTTOM_START = "bottom-start",
+    BOTTOM_CENTER = "bottom-center",
+    BOTTOM_END = "bottom-end"
+}
+/** Shape variant for components (affects border-radius and aspect ratio). */
+declare enum ComponentShape {
+    CIRCLE = "circle",
+    LANDSCAPE = "landscape",
+    PORTRAIT = "portrait",
+    SQUARE = "square"
+}
+/** Possible values for the `aria-pressed` attribute. */
+declare enum ComponentAriaPressed {
+    MIXED = "mixed"
+}
+/** Possible values for the `aria-haspopup` attribute. */
+declare enum ComponentAriaHaspopup {
+    MENU = "menu",
+    TREE = "tree",
+    GRID = "grid",
+    DIALOG = "dialog",
+    LISTBOX = "listbox"
+}
+
+/** Built-in animation effects for Borda components. */
+declare enum AnimationEffect {
+    NONE = "none",
+    FADE = "fade",
+    SCALE = "scale",
+    SLIDE = "slide"
+}
+
+/** Named override layer. */
+declare enum OverrideLayer {
+    RESPONSIVE = "responsive",
+    /** Per-step component overrides — applied on top of RESPONSIVE, cleared between steps. */
+    STEP = "step"
+}
+
+/** Shape of any component instance that exposes its DOM elements via `getElements()`. */
+type ComponentRef<T> = {
+    getElements(): T;
+};
+/** Inline styles — a raw CSS string or a partial `CSSStyleDeclaration` object. */
+type ComponentStyles = string | Partial<CSSStyleDeclaration>;
+/**
+ * Class binding value.
+ * Accepts a string, falsy values (skipped), an object whose truthy keys
+ * are added as classes, or a nested array of the same.
+ */
+type ComponentClasses = string | number | false | null | undefined | Record<string, boolean> | ComponentClasses[];
+/** Common ARIA attributes shared across interactive components. */
+interface ComponentAriaProps {
+    ariaLabel?: string;
+    ariaLabelledby?: string;
+    ariaDescribedby?: string;
+    ariaDisabled?: boolean;
+    ariaExpanded?: boolean;
+    ariaControls?: string;
+    ariaPressed?: ComponentAriaPressed;
+    ariaHaspopup?: ComponentAriaHaspopup;
+}
+
+/** Internal return type for component snippets. */
+type ComponentSnippetReturn = any;
+/**
+ * Typed Svelte 5 snippet reference.
+ * Produces a descriptive compile-time error when used incorrectly
+ * (e.g. called as a function instead of `{@render ...}`).
+ */
+interface ComponentSnippet<Parameters extends unknown[] = []> {
+    (this: void, ...args: number extends Parameters['length'] ? never : Parameters): {
+        '{@render ...} must be called with a Snippet': "import type { ComponentSnippet } from '@retoo/borda'";
+    } & ComponentSnippetReturn;
+}
+
+/** Custom CSS class overrides for the container widget. */
+interface BordaContainerCustomClasses {
+    root: ComponentClasses;
+}
+/** Custom inline style overrides for the container widget. */
+interface BordaContainerCustomStyles {
+    root: ComponentStyles;
+}
+/** Props for the BordaContainer widget. */
+interface BordaContainerProps {
+    id: string;
+    customClasses: Partial<BordaContainerCustomClasses>;
+    customStyles: Partial<BordaContainerCustomStyles>;
+}
+/** Snippet slots for the container widget. */
+interface BordaContainerSnippets {
+    children: ComponentSnippet;
+}
+/** DOM elements exposed by the outer container component. */
+interface BordaContainerElements {
+    root: HTMLDivElement | null;
+}
+/** Component ref for the outer container. */
+interface BordaContainerRef {
+    getElements: () => BordaContainerElements;
+}
+
+/** Shape of the button element. */
+declare enum BordaButtonShape {
+    RECTANGLE = "rectangle",
+    CIRCLE = "circle",
+    SQUARE = "square"
+}
+/** Visual variant of the button. */
+declare enum BordaButtonVariant {
+    /** Solid background fill. */
+    FILLED = "filled",
+    /** Transparent background, bordered. */
+    OUTLINED = "outlined",
+    /** Transparent background, subtle hover surface. */
+    GHOST = "ghost",
+    /** Transparent background, text only. */
+    TEXT = "text"
+}
+/** HTML `type` attribute for the button element. */
+declare enum BordaButtonType {
+    BUTTON = "button",
+    SUBMIT = "submit",
+    RESET = "reset"
+}
+
+/** Custom CSS class overrides for the base button. */
+interface BordaButtonComponentClasses {
+    root: ComponentClasses;
+}
+/** Custom inline style overrides for the base button. */
+interface BordaButtonComponentStyles {
+    root: ComponentStyles;
+}
+/** Configuration props for the base borda button component. */
+interface BordaButtonProps {
+    id: string;
+    disabled: boolean;
+    autosize: boolean;
+    size: ComponentSize;
+    shape: BordaButtonShape;
+    variant: BordaButtonVariant;
+    type: BordaButtonType;
+    aria: Partial<ComponentAriaProps>;
+    customClasses: Partial<BordaButtonComponentClasses>;
+    customStyles: Partial<BordaButtonComponentStyles>;
+}
+/** Event handlers for the base button. */
+interface BordaButtonEvents {
+    onclick: (event: Event) => void;
+}
+/** Snippet slots for the base button. */
+interface BordaButtonSnippets {
+    children: ComponentSnippet;
+}
+/** DOM element references for the base button. */
+interface BordaButtonElements {
+    root: HTMLButtonElement | null;
+}
+
+interface BordaIconCustomClasses {
+    root: ComponentClasses;
+}
+interface BordaIconCustomStyles {
+    root: ComponentStyles;
+}
+interface BordaIconProps {
+    id: string;
+    viewBox: string;
+    size: ComponentSize;
+    customClasses: Partial<BordaIconCustomClasses>;
+    customStyles: Partial<BordaIconCustomStyles>;
+}
+interface BordaIconSnippets {
+    children: ComponentSnippet;
+}
+interface BordaIconElements {
+    root: SVGSVGElement | null;
+}
+
+/** Custom CSS class overrides for the close button and its sub-components. */
+interface BordaCloseButtonComponentClasses {
+    root: ComponentClasses;
+    button: ComponentClasses;
+    cross: ComponentClasses;
+}
+/** Custom inline style overrides for the close button and its sub-components. */
+interface BordaCloseButtonComponentStyles {
+    root: ComponentStyles;
+    button: ComponentStyles;
+    cross: ComponentStyles;
+}
+/** Custom HTML override for the close button. */
+interface BordaCloseButtonComponentHtml {
+    button: string;
+}
+/** Configuration props for the close button widget. */
+interface BordaCloseButtonProps {
+    id: string;
+    size: ComponentSize;
+    shape: ComponentShape;
+    aria: Partial<ComponentAriaProps>;
+    customClasses: Partial<BordaCloseButtonComponentClasses>;
+    customStyles: Partial<BordaCloseButtonComponentStyles>;
+    customHtml: Partial<BordaCloseButtonComponentHtml>;
+    onClose: (event: Event) => void;
+}
+/** DOM elements exposed by the close button component. */
+interface BordaCloseButtonElements {
+    root: HTMLDivElement | null;
+    cross: BordaIconElements | null;
+    button: BordaButtonElements | null;
+}
+/** Component ref for the close button. */
+interface BordaCloseButtonRef {
+    getElements: () => BordaCloseButtonElements;
+}
+
+/** Per-button customization: all BordaButton props (except id) plus a text label. */
+type BordaTourButtonConfig = Partial<Omit<BordaButtonProps, 'id'>> & {
+    label?: string;
+};
+/** A button config resolved with its computed root classes and merged inline styles. */
+type BordaTourResolvedButton = BordaTourButtonConfig & {
+    classes: ComponentClasses;
+    styles: string | undefined;
+};
+/** Custom CSS class overrides for the tour buttons bar. */
+interface BordaTourButtonsComponentClasses {
+    root: ComponentClasses;
+    next: ComponentClasses;
+    prev: ComponentClasses;
+    finish: ComponentClasses;
+    skip: ComponentClasses;
+}
+/** Custom inline style overrides for the tour buttons bar. */
+interface BordaTourButtonsComponentStyles {
+    root: ComponentStyles;
+    next: ComponentStyles;
+    prev: ComponentStyles;
+    finish: ComponentStyles;
+    skip: ComponentStyles;
+}
+/** Custom HTML overrides for the tour buttons. */
+interface BordaTourButtonsComponentHtml {
+    next: string;
+    prev: string;
+    finish: string;
+    skip: string;
+}
+/** Props for the BordaTourButtons component. */
+interface BordaTourButtonsProps {
+    id: string;
+    currentStep: number;
+    totalSteps: number;
+    /** Default size applied to every button; overridable per button. */
+    size: ComponentSize;
+    /** Prev button config. Pass `false` to hide. */
+    prev: BordaTourButtonConfig | false;
+    /** Next button config (shown on non-last steps). Pass `false` to hide. */
+    next: BordaTourButtonConfig | false;
+    /** Finish button config (replaces next on the last step). Pass `false` to hide. */
+    finish: BordaTourButtonConfig | false;
+    /** Skip button config. Pass `false` to hide (default). */
+    skip: BordaTourButtonConfig | false;
+    /** ARIA attributes for accessibility. */
+    aria: Partial<ComponentAriaProps>;
+    customClasses: Partial<BordaTourButtonsComponentClasses>;
+    customStyles: Partial<BordaTourButtonsComponentStyles>;
+    customHtml: Partial<BordaTourButtonsComponentHtml>;
+}
+/** Event handlers for the tour buttons. */
+interface BordaTourButtonsEvents {
+    onPrev: () => void;
+    onNext: () => void;
+    onFinish: () => void;
+    onSkip: () => void;
+}
+/** Snippet slots for the tour buttons. */
+interface BordaTourButtonsSnippets {
+    /** Generic center slot rendered between prev and next buttons. */
+    center: ComponentSnippet;
+}
+/** DOM element references exposed via `getElements()`. */
+interface BordaTourButtonsElements {
+    root: HTMLDivElement | null;
+}
+/** Public ref exposed by the BordaTourButtons component via `bind:this`. */
+interface BordaTourButtonsRef {
+    getElements: () => BordaTourButtonsElements;
+}
+
+declare const bordaTourPrevButtonDefault: BordaTourButtonConfig;
+declare const bordaTourNextButtonDefault: BordaTourButtonConfig;
+declare const bordaTourFinishButtonDefault: BordaTourButtonConfig;
+declare const bordaTourSkipButtonDefault: BordaTourButtonConfig;
+
+/** Visual presentation of the tooltip image. */
+declare enum BordaTourImageVariant {
+    /** Inset within the tooltip padding, with its own rounded corners. */
+    DEFAULT = "default",
+    /** Stretched to the tooltip edges; only the top corners are rounded. */
+    BLEED = "bleed"
+}
+
+/** Custom CSS class overrides for the image. */
+interface BordaImageCustomClasses {
+    root: ComponentClasses;
+}
+/** Custom inline style overrides for the image. */
+interface BordaImageCustomStyles {
+    root: ComponentStyles;
+}
+/** Custom HTML override that fully replaces the rendered image. */
+interface BordaImageCustomHtml {
+    root: string;
+}
+/** Configuration props for the image component. */
+interface BordaImageProps {
+    id: string;
+    /** Image source URL. */
+    src: string;
+    /** Alternative text describing the image. */
+    alt: string;
+    /** ARIA attributes for accessibility. */
+    aria: Partial<ComponentAriaProps>;
+    customClasses: Partial<BordaImageCustomClasses>;
+    customStyles: Partial<BordaImageCustomStyles>;
+    customHtml: Partial<BordaImageCustomHtml>;
+}
+/** DOM element references exposed via `getElements()`. */
+interface BordaImageElements {
+    root: HTMLImageElement | null;
+}
+/** Public ref exposed by the BordaImage component via `bind:this`. */
+interface BordaImageRef {
+    getElements: () => BordaImageElements;
+}
+
+/** Props for the BordaTourImage widget. Mirrors the shared image primitive it wraps. */
+interface BordaTourImageProps {
+    id: string;
+    /** Image source URL. */
+    src: string;
+    /** Alternative text describing the image. */
+    alt: string;
+    /** Visual presentation — inset (`default`) or stretched to the tooltip edges (`bleed`). */
+    variant: BordaTourImageVariant;
+    /** ARIA attributes for accessibility. */
+    aria: Partial<ComponentAriaProps>;
+    customClasses: Partial<BordaImageCustomClasses>;
+    customStyles: Partial<BordaImageCustomStyles>;
+    customHtml: Partial<BordaImageCustomHtml>;
+}
+/** DOM element references exposed via `getElements()`. */
+interface BordaTourImageElements {
+    root: HTMLImageElement | null;
+}
+/** Public ref exposed by the BordaTourImage widget via `bind:this`. */
+interface BordaTourImageRef {
+    getElements: () => BordaTourImageElements;
+}
+
+/** Custom CSS class overrides for the overlay widget. */
+interface BordaTourOverlayComponentClasses {
+    root: ComponentClasses;
+    backdrop: ComponentClasses;
+}
+/** Custom inline style overrides for the overlay widget. */
+interface BordaTourOverlayComponentStyles {
+    root: ComponentStyles;
+    backdrop: ComponentStyles;
+}
+/** Props for the BordaTourOverlay widget. */
+interface BordaTourOverlayProps {
+    id: string;
+    targetElement: HTMLElement | null;
+    padding: number;
+    borderRadius: number;
+    isAnimated: boolean;
+    hasCloseOnBackdropClick: boolean;
+    aria: Partial<ComponentAriaProps>;
+    customClasses: Partial<BordaTourOverlayComponentClasses>;
+    customStyles: Partial<BordaTourOverlayComponentStyles>;
+}
+/** Event handlers for the overlay widget. */
+interface BordaTourOverlayEvents {
+    onClose: (event: MouseEvent) => void;
+}
+/** DOM element references exposed via `getElements()`. */
+interface BordaTourOverlayElements {
+    root: SVGSVGElement | null;
+    backdrop: SVGPathElement | null;
+}
+/** Public ref exposed by the BordaTourOverlay widget via `bind:this`. */
+interface BordaTourOverlayRef {
+    getElements: () => BordaTourOverlayElements;
+}
+/** Props accepted by the overlay spotlight hook. */
+interface UseOverlayProps {
+    getTargetElement: () => HTMLElement | null;
+    getBorderRadius: () => number;
+    getPadding: () => number;
+    getIsAnimated: () => boolean;
+}
+/** Reactive state returned by the overlay spotlight hook. */
+interface UseOverlayReturns {
+    backdropPath: string;
+    /** True for a short window after a target change — lets CSS animate the spotlight transition. */
+    isTransitioning: boolean;
+    /** Document width (used as SVG `width` attribute). */
+    width: number;
+    /** Document height (used as SVG `height` attribute). */
+    height: number;
+}
+
+declare function useOverlay({ getTargetElement, getBorderRadius, getPadding, getIsAnimated }: UseOverlayProps): UseOverlayReturns;
+
+/** Custom CSS class overrides for the skip widget. */
+interface BordaTourSkipComponentClasses {
+    root: ComponentClasses;
+    input: ComponentClasses;
+    label: ComponentClasses;
+}
+/** Custom inline style overrides for the skip widget. */
+interface BordaTourSkipComponentStyles {
+    root: ComponentStyles;
+    input: ComponentStyles;
+    label: ComponentStyles;
+}
+/** Custom HTML override for the skip widget. */
+interface BordaTourSkipComponentHtml {
+    input: string;
+    label: string;
+}
+/** Props for the BordaTourSkip widget. */
+interface BordaTourSkipProps {
+    id: string;
+    checked: boolean;
+    label: string;
+    disabled: boolean;
+    /** ARIA attributes for accessibility. */
+    aria: Partial<ComponentAriaProps>;
+    customClasses: Partial<BordaTourSkipComponentClasses>;
+    customStyles: Partial<BordaTourSkipComponentStyles>;
+    customHtml: Partial<BordaTourSkipComponentHtml>;
+}
+/** Event handlers for the skip widget. */
+interface BordaTourSkipEvents {
+    onSkipChange: (checked: boolean) => void;
+}
+/** DOM element references exposed via `getElements()`. */
+interface BordaTourSkipElements {
+    root: HTMLLabelElement | null;
+    input: HTMLInputElement | null;
+}
+/** Public ref exposed by the BordaTourSkip widget via `bind:this`. */
+interface BordaTourSkipRef {
+    getElements: () => BordaTourSkipElements;
+}
+
+/** Which edge of the tooltip the arrow sits on. */
+declare enum BordaTooltipArrowSide {
+    TOP = "top",
+    BOTTOM = "bottom",
+    LEFT = "left",
+    RIGHT = "right"
+}
+
+/** Animation settings consumed by the tooltip widget. */
+interface BordaTourTooltipAnimation {
+    enter: AnimationEffect;
+    exit: AnimationEffect;
+    enterDuration: number;
+    exitDuration: number;
+    easing: string;
+}
+/** Custom CSS classes for tooltip elements. */
+interface BordaTourTooltipComponentClasses {
+    root: ComponentClasses;
+    header: ComponentClasses;
+    title: ComponentClasses;
+    description: ComponentClasses;
+}
+/** Custom inline styles for tooltip elements. */
+interface BordaTourTooltipComponentStyles {
+    root: ComponentStyles;
+    header: ComponentStyles;
+    title: ComponentStyles;
+    description: ComponentStyles;
+}
+/** Custom HTML overrides for the tooltip content. */
+interface BordaTourTooltipComponentHtml {
+    title: string;
+    description: string;
+}
+/** Spatial parameters controlling tooltip placement relative to the spotlight and viewport. */
+interface BordaTourTooltipPositionProps {
+    offset: number;
+    margin: number;
+    padding: number;
+}
+/** Arrow configuration. Pass `false` to disable the arrow entirely. */
+interface BordaTourTooltipArrowProps {
+    placement: ComponentPlacement;
+}
+/**
+ * Auto-flip placement when the requested placement does not fit in the viewport.
+ * The first placement from `fallback` that fits wins; if none fit, the originally
+ * requested placement is kept (and clamped to the viewport).
+ */
+interface BordaTourTooltipAutoPlacement {
+    /** Ordered list of placements to try after the requested one. First fit wins. */
+    fallback: ComponentPlacement[];
+}
+/** Full props accepted by the BordaTourTooltip component. */
+interface BordaTourTooltipProps extends BordaTourTooltipPositionProps {
+    id: string;
+    title: string;
+    description: string;
+    /** Size variant scaling the tooltip padding, gap, min-width and font sizes. */
+    size: ComponentSize;
+    placement: ComponentPlacement;
+    targetElement: HTMLElement | null;
+    arrow: BordaTourTooltipArrowProps | false;
+    aria: Partial<ComponentAriaProps>;
+    customClasses: Partial<BordaTourTooltipComponentClasses>;
+    customStyles: Partial<BordaTourTooltipComponentStyles>;
+    customHtml: Partial<BordaTourTooltipComponentHtml>;
+    /** Whether the tooltip should currently be hidden — drives the enter/exit animation. */
+    isHidden: boolean;
+    /** Whether the tooltip glides its position between steps (CSS transition on top/left). */
+    hasGlide: boolean;
+    /** Animation timings/kind. Pass `false` to disable animation completely. */
+    animation: BordaTourTooltipAnimation | false;
+    /**
+     * Auto-flip placement to fit the viewport.
+     * - `true` — enabled with a mirrored default fallback (e.g. `bottom-start` → `top-start`).
+     * - `false` — disabled, use the requested placement as-is (clamped).
+     * - Object — custom fallback chain.
+     */
+    autoPlacement: BordaTourTooltipAutoPlacement | boolean;
+}
+/** Snippet slots for the tooltip. */
+interface BordaTourTooltipSnippets {
+    image: ComponentSnippet;
+    close: ComponentSnippet;
+    skip: ComponentSnippet;
+    progress: ComponentSnippet;
+    footer: ComponentSnippet;
+}
+/** DOM element references exposed via `getElements()`. */
+interface BordaTourTooltipElements {
+    root: HTMLDivElement | null;
+}
+/** Public ref API exposed by the component via `bind:this`. */
+interface BordaTourTooltipRef {
+    getElements: () => BordaTourTooltipElements;
+}
+/** Props accepted by the tooltip position hook. */
+interface UseTooltipPositionProps {
+    getTargetElement: () => HTMLElement | null;
+    getTooltipElement: () => HTMLElement | null;
+    getPlacement: () => ComponentPlacement;
+    getOffset: () => number;
+    getMargin: () => number;
+    getPadding: () => number;
+    getAutoPlacement: () => BordaTourTooltipAutoPlacement | boolean;
+    /**
+     * Reactive getter for the arrow side, sourced from `useTooltipArrow().side`.
+     * Drives `arrowOffset` computation along the perpendicular axis.
+     * `null` (no arrow) skips arrow offset updates.
+     */
+    getArrowSide: () => BordaTooltipArrowSide | null;
+}
+/** Reactive position returned by the tooltip position hook. */
+interface UseTooltipPositionReturns {
+    top: number;
+    left: number;
+    /** The placement actually used after auto-flip resolution. */
+    effectivePlacement: ComponentPlacement;
+    /**
+     * Offset (px) along the tooltip edge where the arrow should be anchored,
+     * measured from the tooltip's top-left corner. Used to point the arrow at
+     * the target's center regardless of placement variant (start/center/end).
+     */
+    arrowOffset: number;
+}
+/** Props accepted by the tooltip arrow hook. */
+interface UseTooltipArrowProps {
+    getArrow: () => BordaTourTooltipArrowProps | false | undefined;
+    getPlacement: () => ComponentPlacement;
+}
+/** Reactive state returned by the tooltip arrow hook. */
+interface UseTooltipArrowReturns {
+    /** Which edge of the tooltip the arrow sits on, or `null` when hidden. */
+    side: BordaTooltipArrowSide | null;
+    /** CSS classes to apply on the arrow element, or `null` when the arrow is hidden. */
+    classes: string[] | null;
+}
+/** Lightweight subset of DOMRect used internally by the tooltip position hook. */
+interface BordaTooltipRect {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+    width: number;
+    height: number;
+}
+/** A computed top/left pair (document-relative). */
+interface BordaTooltipPosition {
+    top: number;
+    left: number;
+}
+/** The tooltip's rendered size in pixels. */
+interface BordaTooltipSize {
+    width: number;
+    height: number;
+}
+/** A placement that fits the viewport, together with its resolved position. */
+interface BordaTooltipPlacementFit {
+    placement: ComponentPlacement;
+    position: BordaTooltipPosition;
+}
+/** Min/max top/left (document coordinates) that keep the tooltip inside the viewport. */
+interface BordaTooltipViewportBounds {
+    minTop: number;
+    maxTop: number;
+    minLeft: number;
+    maxLeft: number;
+}
+/**
+ * Per-side overflow of a candidate position past the viewport (px).
+ * Positive means the tooltip overflows that side; negative is the spare gap.
+ */
+interface BordaTooltipOverflow {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** Props accepted by the tooltip layout hook — a snapshot of everything the geometry depends on. */
+interface UseTooltipLayoutProps {
+    /** The DOM element the tooltip points at. */
+    target: HTMLElement;
+    /** The tooltip root element (read for its rendered size). */
+    tooltip: HTMLElement;
+    /** The requested placement. */
+    placement: ComponentPlacement;
+    /** Extra pixel gap between anchor and tooltip along the main axis. */
+    offset: number;
+    /** Minimum gap to keep from each viewport edge (added to `offset`). */
+    margin: number;
+    /** Pixels the target rect is expanded by before positioning. */
+    padding: number;
+    /** Auto-flip configuration. */
+    autoPlacement: BordaTourTooltipAutoPlacement | boolean;
+    /** The tooltip edge the arrow sits on, or `null` when hidden. */
+    arrowSide: BordaTooltipArrowSide | null;
+    /** The viewport size in pixels. */
+    viewport: BordaTooltipSize;
+}
+/** Resolved tooltip geometry returned by the tooltip layout hook. */
+interface UseTooltipLayoutReturns {
+    /** The resolved top/left in document coordinates. */
+    position: BordaTooltipPosition;
+    /** The placement actually used (after auto-flip). */
+    placement: ComponentPlacement;
+    /** The arrow's perpendicular-axis offset in pixels. */
+    arrowOffset: number;
+}
+
+/**
+ * Reactive tooltip arrow hook.
+ *
+ * Resolves which edge of the tooltip the arrow sits on (top/bottom/left/right)
+ * for the current placement, and builds the matching CSS classes. The exact
+ * position along that edge is computed by `useTooltipPosition.arrowOffset`
+ * and applied as an inline CSS variable in the component.
+ *
+ * @param props - Reactive getters for the arrow config and current placement.
+ * @returns Reactive `side` and `classes` (both `null` when the arrow is hidden).
+ */
+declare function useTooltipArrow({ getArrow, getPlacement }: UseTooltipArrowProps): UseTooltipArrowReturns;
+
+/**
+ * Reactive tooltip positioning hook with auto-flip support.
+ *
+ * Thin reactive shell over {@link useTooltipLayout}: tracks the target,
+ * tooltip, placement props, viewport size and scroll position, recomputes the
+ * layout on every change, and exposes the placement that was actually used as
+ * `effectivePlacement` (so the arrow can point in the right direction).
+ *
+ * @param props - Reactive getters for target/tooltip elements, placement, spatial params, and auto-flip config.
+ * @returns Reactive `top`, `left`, `effectivePlacement`, and `arrowOffset` values.
+ */
+declare function useTooltipPosition({ getTargetElement, getTooltipElement, getPlacement, getPadding, getOffset, getMargin, getAutoPlacement, getArrowSide }: UseTooltipPositionProps): UseTooltipPositionReturns;
+
+/** Controls when a component becomes visible relative to the scroll animation. */
+declare enum BordaScrollAppearance {
+    DURING_SCROLL = "during-scroll",
+    AFTER_SCROLL = "after-scroll"
+}
+/** How the tooltip moves between steps. */
+declare enum BordaTooltipTransition {
+    /** Hide the tooltip while scrolling/transitioning, then fade it in at the new step. */
+    FADE = "fade",
+    /** Keep the tooltip visible and glide its position to the new step. */
+    GLIDE = "glide"
+}
+
+/** Tooltip enter/exit animation settings. */
+interface BordaTooltipAnimation {
+    /** Animation effect played on enter. */
+    enter: AnimationEffect;
+    /** Animation effect played on exit. */
+    exit: AnimationEffect;
+    /** Enter animation duration in ms. */
+    enterDuration: number;
+    /** Exit animation duration in ms. */
+    exitDuration: number;
+    /** CSS easing applied to the animation. */
+    easing: string;
+    /** When to reveal the tooltip relative to the scroll animation (fade transition only). */
+    appearance: BordaScrollAppearance;
+    /** How the tooltip moves between steps: `fade` (hide + fade in) or `glide` (stay + slide). */
+    transition: BordaTooltipTransition;
+}
+/** Overlay/spotlight transition between steps. */
+interface BordaOverlayAnimation {
+    /** Duration in ms used to wait for the overlay to settle between steps. */
+    transitionDuration: number;
+    /** CSS easing applied to the overlay transition. */
+    easing: string;
+}
+/** Full animation feature config covering tooltip + overlay timings. */
+interface BordaAnimationConfig {
+    /** Master switch for all animations. */
+    isEnabled: boolean;
+    /** Tooltip animation settings. Unspecified keys fall back to defaults. */
+    tooltip: Partial<BordaTooltipAnimation>;
+    /** Overlay/spotlight animation settings. Unspecified keys fall back to defaults. */
+    overlay: Partial<BordaOverlayAnimation>;
+}
+/** Public API for inspecting the animation feature at runtime. */
+interface BordaAnimationApi {
+    /** Whether animations are enabled globally. */
+    isEnabled: boolean;
+    /** Resolved tooltip animation settings. */
+    tooltip: BordaTooltipAnimation;
+    /** Resolved overlay animation settings. */
+    overlay: BordaOverlayAnimation;
+}
+/** Return value of {@link useBordaAnimation}. */
+interface UseBordaAnimationReturns {
+    apply: () => void;
+    api: BordaAnimationApi;
+}
+
+/**
+ * Centralizes animation timings for the tooltip and overlay.
+ *
+ * Config is read reactively, so `mergeConfig({ animation: ... })` at runtime
+ * is picked up on the next access. Pass `animation: false` to fully disable.
+ */
+declare function useBordaAnimation(config: UseBordaConfigReturns): UseBordaAnimationReturns;
+
+/** Public API for controlling the tour at runtime. */
+interface BordaControllerApi {
+    /** `true` when the tour has at least one step. */
+    isActivated: boolean;
+    /** Current 1-based step number. */
+    currentStep: number;
+    /** Current 0-based step index. */
+    currentStepIndex: number;
+    /** Total number of steps. */
+    totalSteps: number;
+    /** `true` when there is a step after the current one. */
+    hasNextStep: boolean;
+    /** `true` when there is a step before the current one. */
+    hasPrevStep: boolean;
+    /** Resolved DOM element for the current step's target. */
+    currentTarget: HTMLElement | null;
+    /** Full data object of the current step, including any per-step overrides. */
+    step: BordaStepConfig | undefined;
+    /** Navigate to a step by 0-based index. Waits for `prepareElement` if defined. */
+    changeStep: (index: number) => Promise<void>;
+    /** Navigate to the previous step. */
+    prev: () => Promise<void>;
+    /** Navigate to the next step (calls finish on the last step). */
+    next: () => Promise<void>;
+    /** Emit ON_TOUR_FINISH and end the tour. */
+    finish: () => void;
+    /**
+     * `true` while a navigation is paused via {@link BordaControllerApi.preventMove}.
+     * Resets to `false` after {@link BordaControllerApi.continue} or {@link BordaControllerApi.clearMovePrevented}.
+     */
+    isMovePrevented: boolean;
+    /** Pause the in-progress navigation. Call {@link BordaControllerApi.continue} to resume. */
+    preventMove: () => void;
+    /** Resume a navigation paused by {@link BordaControllerApi.preventMove}. */
+    continue: () => void;
+    /** Cancel a paused navigation without completing it. */
+    clearMovePrevented: () => void;
+}
+/** Return value of {@link useBordaController}. */
+interface UseBordaControllerReturns {
+    /** Apply the initial step from config. */
+    apply: () => void;
+    /** Reactive public API for controlling the tour. */
+    api: BordaControllerApi;
+}
+
+/**
+ * Manages the active tour step state at the entrypoint level.
+ *
+ * Returns an API object equivalent to {@link BordaControllerApi} with reactive state
+ * and buttons methods, plus an `apply()` to initialize from config.
+ */
+declare function useBordaController(config: UseBordaConfigReturns, eventEmitter: BordaEventEmitter): UseBordaControllerReturns;
+
+/** Return value of {@link useBordaHighlight}. */
+interface UseBordaHighlightReturns {
+    /**
+     * Spotlights a single element. Accepts the same data as a tour step plus
+     * optional top-level config, and mounts a one-step tour.
+     */
+    highlight: (step: BordaStepConfig, config?: BordaHighlightConfig, target?: BordaTarget) => Promise<BordaInstance>;
+}
+
+/**
+ * Provides the `highlight` shortcut — spotlights a single element by mounting
+ * a one-step tour through the factory's {@link mount}.
+ *
+ * @param mount - The factory's mount method, used to render the one-step tour.
+ * @returns The highlight API exposing {@link UseBordaHighlightReturns.highlight}.
+ */
+declare function useBordaHighlight(mount: UseBordaReturns['mount']): UseBordaHighlightReturns;
+
+/** Return value of {@link useBordaKeyboard}. */
+interface UseBordaKeyboardReturns {
+    /** Attach keyboard listeners. Call once after mount. */
+    apply: () => void;
+    /** Remove keyboard listeners. Call on unmount. */
+    destroy: () => void;
+}
+
+/**
+ * Manages keyboard navigation for the borda widget.
+ *
+ * When `tour.hasKeyboardControl` is not `false`, attaches a document-level
+ * `keydown` listener that maps:
+ * - ArrowRight → emits {@link BordaEvent.ON_KEYBOARD_NEXT}
+ * - ArrowLeft  → emits {@link BordaEvent.ON_KEYBOARD_PREV}
+ * - Escape     → emits {@link BordaEvent.ON_TOUR_CLOSE}
+ *
+ * Keypresses originating from form controls are ignored so the widget
+ * does not interfere with text input.
+ *
+ * @param config - The reactive config store.
+ * @param eventEmitter - The shared event bus.
+ * @returns `apply` and `destroy` lifecycle methods.
+ */
+declare function useBordaKeyboard(config: UseBordaConfigReturns, eventEmitter: BordaEventEmitter): UseBordaKeyboardReturns;
+
+/** Return value of {@link useBordaOverrides}. */
+interface UseBordaOverridesReturns {
+    /** The resolved config with all override layers applied (reactive). */
+    resolved: BordaConfig;
+    /** Compute and return the resolved config snapshot. */
+    resolve: () => BordaConfig;
+    /** Set an override factory function for a named layer, or `null` to clear that layer. */
+    set: (layer: OverrideLayer, value: (() => Partial<BordaConfig>) | null) => void;
+    /** Apply per-step component overrides from the given step, or clear them if `undefined`. */
+    applyStep: (step: BordaStepConfig | null) => void;
+}
+
+/**
+ * Manages runtime config overrides via named layers and a deep-merge strategy.
+ *
+ * Each layer is identified by name and merged in a fixed order,
+ * so higher-priority layers always win.
+ *
+ * @param config - The reactive config store to overlay overrides on.
+ * @returns A reactive `resolved` config and methods to `set`/`resolve` overrides.
+ */
+declare function useBordaOverrides(config: UseBordaConfigReturns): UseBordaOverridesReturns;
+
+/** Public API for the responsive feature. */
+interface BordaResponsiveApi {
+    /** The currently active breakpoint (max-width in px), or `null` if none matched. */
+    activeBreakpoint: number | null;
+}
+/** Return value of {@link useBordaResponsive}. */
+interface UseBordaResponsiveReturns {
+    /** Set up matchMedia listeners and apply the initial breakpoint. */
+    apply: () => void;
+    /** Remove all listeners and clear responsive overrides. */
+    destroy: () => void;
+    /** Reactive responsive API. */
+    api: BordaResponsiveApi;
+}
+/** Responsive config — object of breakpoints mapped to partial overrides. */
+type BordaResponsiveConfig = Record<number, Partial<BordaOverrides>>;
+
+/**
+ * Manages responsive breakpoint overrides for the borda widget.
+ *
+ * Listens to viewport width changes via `matchMedia` and applies
+ * the matching breakpoint's component overrides as a named layer
+ * in the overrides system (below preview priority).
+ *
+ * @param config - The reactive config store.
+ * @param configOverrides - The config overrides manager.
+ * @returns Methods to apply/destroy and a reactive API with activeBreakpoint.
+ */
+declare function useBordaResponsive(config: UseBordaConfigReturns, configOverrides: UseBordaOverridesReturns): UseBordaResponsiveReturns;
+
+/** Built-in scroll easing presets. */
+declare enum BordaScrollEasingName {
+    LINEAR = "linear",
+    EASE = "ease",
+    EASE_IN = "ease-in",
+    EASE_OUT = "ease-out",
+    EASE_IN_OUT = "ease-in-out"
+}
+
+/** Easing function signature: maps `progress` in [0, 1] to the eased value. */
+type BordaScrollEasingFn = (progress: number) => number;
+/** Easing identifier — a built-in {@link BordaScrollEasingName} or a custom {@link BordaScrollEasingFn}. */
+type BordaScrollEasing = BordaScrollEasingName | BordaScrollEasingFn;
+
+/** Pixel offsets applied to the resolved scroll destination. */
+interface BordaScrollOffset {
+    x: number;
+    y: number;
+}
+/** Config for the scroll feature (smooth-follow the active step target). */
+interface BordaScrollConfig {
+    /** Vertical alignment of the target after scroll. */
+    block: ScrollLogicalPosition;
+    /** Horizontal alignment of the target after scroll. */
+    inline: ScrollLogicalPosition;
+    /** Animation duration in ms. Use `0` for an instant jump. */
+    duration: number;
+    /** Easing function or built-in name. */
+    easing: BordaScrollEasing;
+    /** Pixel offsets applied on top of the alignment-resolved coordinates. Unspecified axes default to `0`. */
+    offset: Partial<BordaScrollOffset>;
+    /** Block manual page scroll while the tour is active so the spotlight stays put. Defaults to `true`; set `false` to allow scrolling. */
+    isLocked: boolean;
+}
+/** Public API for controlling scroll behavior at runtime. */
+interface BordaScrollApi {
+    /** Whether a scroll-to-target animation is currently in progress. */
+    isScrolling: boolean;
+    /** Whether manual page scroll is currently blocked. */
+    isLocked: boolean;
+    /** Scroll to bring an element into view; resolves once the animation finishes. */
+    scrollTo: (element: HTMLElement | null) => Promise<void>;
+}
+/** Return value of {@link useBordaScroll}. */
+interface UseBordaScrollReturns {
+    apply: () => void;
+    destroy: () => void;
+    api: BordaScrollApi;
+}
+/** Scroll animation handle. */
+interface BordaActiveScrollAnimation {
+    cancel: () => void;
+}
+
+/**
+ * Manages the scroll feature that smoothly follows the active tour step.
+ *
+ * Uses a custom rAF animation so `duration`, `easing` and `offset` are fully
+ * configurable. Setting `scroll: false` makes `scrollTo` a no-op. Disabling
+ * animations globally (`animation: false` or `animation.isEnabled: false`)
+ * keeps the scroll itself but turns it into an instant jump.
+ *
+ * @param config - The reactive config store.
+ * @returns Methods to apply initial state, and a reactive scroll API.
+ */
+declare function useBordaScroll(config: UseBordaConfigReturns): UseBordaScrollReturns;
+
+/** Config for the skip ("don't show again") feature. */
+interface BordaSkipConfig {
+    storageKey: string;
+}
+/** Public API for controlling the skip feature at runtime. */
+interface BordaSkipApi {
+    /** Whether the skip flag is currently set. */
+    isSkipped: boolean;
+    /** Effective storage key (from config or the default). */
+    storageKey: string;
+    /** Sets the skip flag and persists it. No-op when `skip` is disabled in config. */
+    set: (value: boolean) => void;
+    /** Clears the persisted flag. Works even when `skip` is disabled in config. */
+    clear: () => void;
+}
+/** Return value of {@link useBordaSkip}. */
+interface UseBordaSkipReturns {
+    apply: () => void;
+    api: BordaSkipApi;
+}
+
+/**
+ * Manages the "don't show again" skip feature.
+ *
+ * Reads and writes the skip flag to localStorage under a configurable key.
+ * Enabled by default — pass `skip: false` in the config to disable entirely.
+ *
+ * @param config - The reactive config store.
+ * @param eventEmitter - The shared event bus for emitting skip events.
+ * @returns Methods to apply initial state, and a reactive skip API.
+ */
+declare function useBordaSkip(config: UseBordaConfigReturns, eventEmitter: BordaEventEmitter): UseBordaSkipReturns;
+
+/** Return value of {@link useBordaVisibility}. */
+interface UseBordaVisibilityReturns {
+    /** Apply initial visibility state from config defaults. */
+    apply: () => void;
+    /** Reactive public API for controlling widget visibility. */
+    api: BordaVisibilityApi;
+}
+/** Public API for controlling widget visibility at runtime. */
+interface BordaVisibilityApi {
+    /** Whether the widget is currently hidden. */
+    isHidden: boolean;
+    /** Show the widget (set `isHidden` to `false`). */
+    show: () => void;
+    /** Hide the widget (set `isHidden` to `true`). */
+    hide: () => void;
+}
+/** Visibility feature configuration options. */
+interface BordaVisibilityConfig {
+    /** Start the widget in a hidden state. */
+    isHidden: boolean;
+    /** Enable CSS animations for show/hide transitions. */
+    isAnimated: boolean;
+}
+
+/**
+ * Manages the show/hide visibility feature for the borda widget.
+ *
+ * Reads initial visibility settings from config and provides
+ * `show`/`hide` methods to toggle the widget at runtime.
+ *
+ * @param config - The reactive config store.
+ * @param eventEmitter - The shared event bus for emitting visibility events.
+ * @returns Methods to apply initial state, and a reactive visibility API.
+ */
+declare function useBordaVisibility(config: UseBordaConfigReturns, eventEmitter: BordaEventEmitter): UseBordaVisibilityReturns;
+
+/** Data-attribute matcher for {@link BordaStepTargetQuery.data}. */
+interface BordaStepTargetQueryData {
+    name: string;
+    value: string;
+}
+/** Structured query for resolving a step target element for {@link BordaStepTarget}. */
+interface BordaStepTargetQuery {
+    id: string;
+    class: string;
+    data: Partial<BordaStepTargetQueryData> & Pick<BordaStepTargetQueryData, 'name'>;
+}
+/** Accepted shapes for {@link BordaStep.target}. */
+type BordaStepTarget = string | HTMLElement | Partial<BordaStepTargetQuery>;
+/** Structured image for {@link BordaStep.image}, carrying its own alt text. */
+interface BordaStepImage {
+    src: string;
+    alt?: string;
+}
+/** Accepted shapes for {@link BordaStep.image}. A bare string sets the source with empty alt. */
+type BordaStepImageSource = string | BordaStepImage;
+/** A single step in the onboarding tour. */
+interface BordaStep {
+    /** Element to spotlight. Accepts a CSS selector string, an HTMLElement, or a structured query. */
+    target: BordaStepTarget;
+    /** Tooltip heading text. */
+    title: string;
+    /** Tooltip body text. */
+    description: string;
+    /** Image shown above the tooltip heading. A string sets the source (empty alt); an object carries its own alt. */
+    image?: BordaStepImageSource;
+    /** Preferred tooltip placement relative to the target element. */
+    placement: ComponentPlacement;
+    /**
+     * Called before this step's target is highlighted, after any async `prepareElement` resolves.
+     * Fires before the reactive step index changes.
+     */
+    onBeforeHighlighted?: () => void;
+    /** Called after this step's target is highlighted (step index has been updated). */
+    onHighlighted?: () => void;
+    /** Called when navigating away from this step, before the next step is prepared. */
+    onDeselected?: () => void;
+    /** Step-level next handler; called alongside the tour-level `onNext`. */
+    onNext?: () => void;
+    /** Step-level previous handler; called alongside the tour-level `onPrev`. */
+    onPrev?: () => void;
+    /**
+     * Async preparation hook called before entering this step.
+     * Use it to mount dynamic content, expand sections, or fetch data the tooltip depends on.
+     * Navigation waits for the returned Promise to settle before proceeding.
+     */
+    prepareElement?: () => Promise<void> | void;
+}
+
+/** Visual variant of the tour progress indicator (dots, text, or line). */
+declare enum BordaTourProgressVariant {
+    DOTS = "dots",
+    TEXT = "text",
+    LINE = "line"
+}
+
+/** Custom CSS class overrides for the progress widget. */
+interface BordaTourProgressComponentClasses {
+    root: ComponentClasses;
+    item: ComponentClasses;
+}
+/** Custom inline style overrides for the progress widget. */
+interface BordaTourProgressComponentStyles {
+    root: ComponentStyles;
+    item: ComponentStyles;
+}
+/** Custom HTML override for the progress widget. */
+interface BordaTourProgressComponentHtml {
+    progress: string;
+}
+/** Props for the BordaTourProgress widget. */
+interface BordaTourProgressProps {
+    id: string;
+    currentStep: number;
+    totalSteps: number;
+    variant: BordaTourProgressVariant;
+    /** ARIA attributes for accessibility. */
+    aria: Partial<ComponentAriaProps>;
+    customClasses: Partial<BordaTourProgressComponentClasses>;
+    customStyles: Partial<BordaTourProgressComponentStyles>;
+    customHtml: Partial<BordaTourProgressComponentHtml>;
+}
+/** DOM element references exposed via `getElements()`. */
+interface BordaTourProgressElements {
+    root: HTMLDivElement | null;
+}
+/** Public ref exposed by the BordaTourProgress widget via `bind:this`. */
+interface BordaTourProgressRef {
+    getElements: () => BordaTourProgressElements;
+}
+
+/** Props for the BordaTour step composition component. */
+interface BordaTourProps {
+    step: BordaStep;
+    currentTarget: HTMLElement | null;
+    currentStep: number;
+    totalSteps: number;
+    size: ComponentSize;
+    shape: ComponentShape;
+    isSkipChecked: boolean;
+    /** Hides the tooltip (fade transition) while scrolling/transitioning between steps. */
+    isHidden: boolean;
+    /** Enables position gliding of the tooltip between steps (glide transition). */
+    hasGlide: boolean;
+    tourTooltipAnimation: BordaTourTooltipAnimation | false;
+    tourTooltipProps: Partial<BordaTourTooltipProps>;
+    tourImageProps: Partial<BordaTourImageProps> | false;
+    tourButtonsProps: Partial<BordaTourButtonsProps> | false;
+    tourProgressProps: Partial<BordaTourProgressProps> | false;
+    tourSkipProps: Partial<BordaTourSkipProps> | false;
+    closeButtonProps: Partial<BordaCloseButtonProps> | false;
+}
+/** Event handlers for the BordaTour component. */
+interface BordaTourEvents {
+    onPrev: () => void;
+    onNext: () => void;
+    onFinish: () => void;
+    onSkip: () => void;
+    onSkipChange: (checked: boolean) => void;
+}
+/** Registry of child component refs exposed by BordaTour. */
+interface BordaTourComponents {
+    tourTooltip: BordaTourTooltipRef | null;
+    tourImage: BordaTourImageRef | null;
+    tourButtons: BordaTourButtonsRef | null;
+    tourSkip: BordaTourSkipRef | null;
+    closeButton: BordaCloseButtonRef | null;
+}
+/** Public ref exposed by the BordaTour component via `bind:this`. */
+interface BordaTourRef {
+    getComponents: () => BordaTourComponents;
+}
+/** Config for the tour feature. */
+interface BordaTourConfig {
+    startStep: number;
+    /** Called once when the tour initialises (on mount). */
+    onStart: () => void;
+    /** Called when advancing to the next step (not fired on the last step → finish). */
+    onNext: () => void;
+    /** Called when navigating to the previous step. */
+    onPrev: () => void;
+    /** Called when the tour finishes, before the unmount animation. */
+    onFinish: () => void;
+    /** Called when the tour is dismissed before completion (close button, backdrop or Escape), before the unmount animation. */
+    onClose: () => void;
+    /**
+     * Enable keyboard navigation: ArrowRight/ArrowLeft for next/prev, Escape to close.
+     * Defaults to `true`. Set to `false` to disable all keyboard handling.
+     */
+    hasKeyboardControl: boolean;
+}
+
+/**
+ * A step definition with optional per-step component overrides.
+ * Override fields shadow the global config while this step is active.
+ * Pass `false` to disable a component for this step only.
+ */
+interface BordaStepConfig extends BordaStep {
+    /** Spotlight overlay props for this step. Pass `false` to disable. */
+    tourOverlay?: Partial<BordaTourOverlayProps> | false;
+    /** Tooltip props for this step. Pass `false` to disable. */
+    tourTooltip?: Partial<BordaTourTooltipProps> | false;
+    /** Tooltip image props for this step (classes/styles); source and alt come from `image`. Pass `false` to disable. */
+    tourImage?: Partial<BordaTourImageProps> | false;
+    /** Buttons props for this step. Pass `false` to disable. */
+    tourButtons?: Partial<BordaTourButtonsProps> | false;
+    /** Progress indicator props for this step. Pass `false` to disable. */
+    tourProgress?: Partial<BordaTourProgressProps> | false;
+    /** Skip checkbox props for this step. Pass `false` to disable. */
+    tourSkip?: Partial<BordaTourSkipProps> | false;
+    /** Close button props for this step. Pass `false` to disable. */
+    closeButton?: Partial<BordaCloseButtonProps> | false;
+}
+/** Per-component property overrides. Pass `false` to disable a component entirely. */
+interface BordaOverrides {
+    /** Global size propagated to sized components (e.g. close button, tour buttons). */
+    size: ComponentSize;
+    /** Global shape propagated to shaped components (e.g. close button). */
+    shape: ComponentShape;
+    /** Steps for the onboarding tour. */
+    steps: BordaStepConfig[];
+    /** Outer container props. */
+    container: Partial<BordaContainerProps>;
+    /** Spotlight overlay props. Pass `false` to disable. */
+    tourOverlay: Partial<BordaTourOverlayProps> | false;
+    /** Tooltip props. Pass `false` to disable. */
+    tourTooltip: Partial<BordaTourTooltipProps> | false;
+    /** Tooltip image props (classes/styles); source and alt come from each step's `image`. Pass `false` to disable. */
+    tourImage: Partial<BordaTourImageProps> | false;
+    /** Buttons props. Pass `false` to disable. */
+    tourButtons: Partial<BordaTourButtonsProps> | false;
+    /** Progress indicator props. Pass `false` to disable. */
+    tourProgress: Partial<BordaTourProgressProps> | false;
+    /** "Don't show again" skip checkbox props. Pass `false` to disable. */
+    tourSkip: Partial<BordaTourSkipProps> | false;
+    /** Close button props. Pass `false` to disable. */
+    closeButton: Partial<BordaCloseButtonProps> | false;
+}
+/** Component override config. All overrides are optional except `steps` which is required. */
+type BordaConfigOverrides = Partial<BordaOverrides> & Pick<BordaOverrides, 'steps'>;
+/** Feature-specific sections of the widget config. */
+interface BordaFeatures {
+    /** Tour buttons state (startStep, etc.). */
+    tour: Partial<BordaTourConfig>;
+    /** Visibility transitions and initial hidden state. */
+    visibility: Partial<BordaVisibilityConfig>;
+    /** Responsive breakpoint overrides. */
+    responsive: BordaResponsiveConfig;
+    /** Smooth-scroll the page to the active step target. Pass `false` to disable. */
+    scroll: Partial<BordaScrollConfig> | false;
+    /** Skip feature ("don't show again"). Pass `false` to disable. */
+    skip: Partial<BordaSkipConfig> | false;
+    /** Animations and transitions for tooltip/overlay. Pass `false` to disable. */
+    animation: Partial<BordaAnimationConfig> | false;
+}
+/** Optional feature config. All feature sections are optional at the top level. */
+type BordaConfigFeatures = Partial<BordaFeatures>;
+/** Root configuration object accepted by `useBorda().mount()`. `steps` is required. */
+type BordaConfig = BordaConfigOverrides & BordaConfigFeatures;
+/**
+ * Configuration accepted by `useBorda().highlight()`.
+ * Identical to {@link BordaConfig} but without `steps` — the single step is passed separately.
+ */
+type BordaHighlightConfig = Omit<BordaConfig, 'steps'>;
+/** Reactive config store returned by {@link useBordaConfig}. */
+interface UseBordaConfigReturns {
+    /** Current resolved config snapshot. */
+    current: BordaConfig;
+    /** Returns the current config object. */
+    getConfig: () => BordaConfig;
+    /** Replaces the entire config with a new value. */
+    setConfig: (value: BordaConfig) => void;
+    /** Deeply merges a partial config into the current one. */
+    mergeConfig: (partial: Partial<BordaConfig>) => void;
+}
+
+/** Mount target — a regular DOM element or a Shadow DOM root. */
+type BordaTarget = HTMLElement | ShadowRoot;
+/** Handle returned after mounting; provides runtime access to the widget. */
+interface BordaInstance {
+    /** Public widget API. */
+    api: BordaApi;
+    /** Reference to the mounted Svelte component. */
+    component: BordaRef;
+    /** Reactive config store for reading and updating the widget config. */
+    config: UseBordaConfigReturns;
+    /** Responsive feature API (activeBreakpoint). */
+    responsive: BordaResponsiveApi;
+    /** Scroll feature API (scrollTo). */
+    scroll: BordaScrollApi;
+    /** Animation feature API (resolved tooltip/overlay timings). */
+    animation: BordaAnimationApi;
+    /** Skip feature API ("don't show again" state). */
+    skip: BordaSkipApi;
+    /** Visibility feature API (show, hide, isHidden). */
+    visibility: BordaVisibilityApi;
+}
+/** Registry of all component refs within a mounted borda widget. Nullable refs correspond to optional components. */
+interface BordaComponents {
+    container: BordaContainerRef;
+    tourOverlay: BordaTourOverlayRef | null;
+    tourTooltip: BordaTourTooltipRef | null;
+    tourImage: BordaTourImageRef | null;
+    tourButtons: BordaTourButtonsRef | null;
+    tourSkip: BordaTourSkipRef | null;
+    closeButton: BordaCloseButtonRef | null;
+}
+/** Top-level API returned by {@link useBorda}. */
+interface UseBordaReturns {
+    /** Library name. */
+    NAME: string;
+    /** Library version. */
+    VERSION: string;
+    /** Mount the widget into a target element with the given config. */
+    mount: (config: BordaConfig, target?: BordaTarget) => Promise<BordaInstance>;
+    /** Unmount a previously mounted widget instance. */
+    unmount: (instance: BordaInstance) => Promise<void>;
+    /**
+     * Spotlights a single element. Accepts the same data as a tour step plus
+     * optional top-level config, and mounts a one-step tour.
+     */
+    highlight: (step: BordaStepConfig, config?: BordaHighlightConfig, target?: BordaTarget) => Promise<BordaInstance>;
+}
+/** Internal props passed to the root Borda Svelte component. */
+interface BordaProps {
+    /** Resolved widget config (with overrides applied). */
+    config: BordaConfig;
+    /** Tour controller, created at the entrypoint level. */
+    controller: BordaControllerApi;
+    /** Scroll feature API, created at the entrypoint level. */
+    scroll: BordaScrollApi;
+    /** Animation feature API, created at the entrypoint level. */
+    animation: BordaAnimationApi;
+    /** Skip feature API, created at the entrypoint level. */
+    skip: BordaSkipApi;
+    /** Shared event bus created by the factory. */
+    eventEmitter: BordaEventEmitter;
+    /** Callback invoked when the component is mounted. */
+    mount: () => void;
+    /** Callback invoked when the component requests unmount. */
+    unmount: () => void;
+    /** Callback invoked when the component requests an early dismissal of the tour. */
+    close: () => void;
+}
+/** Top-level API surface exposed by a mounted borda widget. */
+interface BordaApi {
+    /** Tour controller (currentStep, next, prev, changeStep, etc.). */
+    controller: BordaControllerApi;
+    /** References to all child component instances. */
+    components: BordaComponents;
+    /** Pub/sub event bus for widget events. */
+    events: BordaEventEmitter;
+}
+/** Reference to the root Borda Svelte component. */
+interface BordaRef {
+    /** Top-level widget API. */
+    api: BordaApi;
+}
+
+declare function useBorda(): UseBordaReturns;
+
+/**
+ * Creates a reactive config store for the borda widget.
+ *
+ * Provides getter, setter, and deep-merge methods for managing
+ * the widget configuration at runtime.
+ *
+ * @param initial - The initial widget configuration.
+ * @returns A reactive config store with `current`, `getConfig`, `setConfig`, and `mergeConfig`.
+ */
+declare function useBordaConfig(initial: BordaConfig): UseBordaConfigReturns;
+
+/** The HTML tag name used for the borda custom element. */
+type BordaElementTag = 'borda-tour-widget';
+
+declare const TAG_NAME: BordaElementTag;
+
+/**
+ * SSR-safe `HTMLElement` constructor.
+ *
+ * On the server `HTMLElement` is undefined, which would throw at module
+ * evaluation time when used as a base class. Falling back to an empty stub
+ * lets the module be imported in SSR environments (Nuxt, Next, etc.) without
+ * forcing consumers to client-only the import itself.
+ */
+declare const SAFE_HTML_ELEMENT: typeof HTMLElement;
+
+/**
+ * Returns the custom element constructor if it has already been registered.
+ *
+ * @returns The registered `CustomElementConstructor`, or `undefined` if not yet defined.
+ */
+declare function getBordaElement(): CustomElementConstructor | undefined;
+/**
+ * Registers the `<borda-tour-widget>` custom element in the browser.
+ *
+ * Safe to call multiple times — skips registration if the element is already defined.
+ */
+declare function defineBordaElement(): void;
+
+/** Svelte context shared across all borda child components. */
+interface BordaContext {
+    /** Widget-wide event bus. */
+    eventEmitter: BordaEventEmitter;
+    /** Trigger the component mount lifecycle. */
+    mount: () => void;
+    /** Trigger the component unmount lifecycle (raw teardown). */
+    unmount: () => void;
+    /** Dismiss the tour before completion — fires the close lifecycle, then unmounts. */
+    close: () => void;
+}
+
+/**
+ * Svelte context pair for sharing {@link BordaContext} across the component tree.
+ *
+ * - `getBordaContext` — retrieve the context in a child component.
+ * - `setBordaContext` — provide the context in a parent component.
+ */
+declare const getBordaContext: () => BordaContext;
+declare const setBordaContext: (context: BordaContext) => BordaContext;
+
+/** Custom CSS class overrides for the linear progress bar. */
+interface BordaProgressLineComponentClasses {
+    root: ComponentClasses;
+    track: ComponentClasses;
+    progress: ComponentClasses;
+}
+/** Custom inline style overrides for the linear progress bar. */
+interface BordaProgressLineComponentStyles {
+    root: ComponentStyles;
+    track: ComponentStyles;
+    progress: ComponentStyles;
+}
+/** Props for the linear progress bar. */
+interface BordaProgressLineProps {
+    id: string;
+    current: number;
+    total: number;
+    aria: Partial<ComponentAriaProps>;
+    customClasses: Partial<BordaProgressLineComponentClasses>;
+    customStyles: Partial<BordaProgressLineComponentStyles>;
+}
+/** Custom CSS class overrides for dots and text progress variants. */
+interface BordaProgressItemComponentClasses {
+    root: ComponentClasses;
+    item: ComponentClasses;
+}
+/** Custom inline style overrides for dots and text progress variants. */
+interface BordaProgressItemComponentStyles {
+    root: ComponentStyles;
+    item: ComponentStyles;
+}
+/** Props for discrete progress indicators (dots, text). */
+interface BordaProgressItemProps {
+    id: string;
+    current: number;
+    total: number;
+    aria: Partial<ComponentAriaProps>;
+    customClasses: Partial<BordaProgressItemComponentClasses>;
+    customStyles: Partial<BordaProgressItemComponentStyles>;
+}
+
+export { AnimationEffect, BordaButtonShape, BordaButtonType, BordaButtonVariant, BordaEvent, BordaScrollAppearance, BordaTooltipArrowSide, BordaTooltipTransition, BordaTourImageVariant, BordaTourProgressVariant, ComponentAriaHaspopup, ComponentAriaPressed, ComponentPlacement, ComponentShape, ComponentSize, OverrideLayer, SAFE_HTML_ELEMENT, TAG_NAME, bordaTourFinishButtonDefault, bordaTourNextButtonDefault, bordaTourPrevButtonDefault, bordaTourSkipButtonDefault, defineBordaElement, getBordaContext, getBordaElement, setBordaContext, useBorda, useBordaAnimation, useBordaConfig, useBordaController, useBordaHighlight, useBordaKeyboard, useBordaOverrides, useBordaResponsive, useBordaScroll, useBordaSkip, useBordaVisibility, useEventEmitter, useOverlay, useTooltipArrow, useTooltipPosition };
+export type { BordaActiveScrollAnimation, BordaAnimationApi, BordaAnimationConfig, BordaApi, BordaButtonComponentClasses, BordaButtonComponentStyles, BordaButtonElements, BordaButtonEvents, BordaButtonProps, BordaButtonSnippets, BordaCloseButtonComponentClasses, BordaCloseButtonComponentHtml, BordaCloseButtonComponentStyles, BordaCloseButtonElements, BordaCloseButtonProps, BordaCloseButtonRef, BordaComponents, BordaConfig, BordaConfigFeatures, BordaConfigOverrides, BordaContainerCustomClasses, BordaContainerCustomStyles, BordaContainerElements, BordaContainerProps, BordaContainerRef, BordaContainerSnippets, BordaContext, BordaControllerApi, BordaElementTag, BordaEventEmitter, BordaEventHandler, BordaEventMap, BordaFeatures, BordaHighlightConfig, BordaIconCustomClasses, BordaIconCustomStyles, BordaIconElements, BordaIconProps, BordaIconSnippets, BordaImageCustomClasses, BordaImageCustomHtml, BordaImageCustomStyles, BordaImageElements, BordaImageProps, BordaImageRef, BordaInstance, BordaOverlayAnimation, BordaOverrides, BordaProgressItemComponentClasses, BordaProgressItemComponentStyles, BordaProgressItemProps, BordaProgressLineComponentClasses, BordaProgressLineComponentStyles, BordaProgressLineProps, BordaProps, BordaRef, BordaResponsiveApi, BordaResponsiveConfig, BordaScrollApi, BordaScrollConfig, BordaScrollOffset, BordaSkipApi, BordaSkipConfig, BordaStepConfig, BordaTarget, BordaTooltipAnimation, BordaTooltipOverflow, BordaTooltipPlacementFit, BordaTooltipPosition, BordaTooltipRect, BordaTooltipSize, BordaTooltipViewportBounds, BordaTourButtonConfig, BordaTourButtonsComponentClasses, BordaTourButtonsComponentHtml, BordaTourButtonsComponentStyles, BordaTourButtonsElements, BordaTourButtonsEvents, BordaTourButtonsProps, BordaTourButtonsRef, BordaTourButtonsSnippets, BordaTourComponents, BordaTourConfig, BordaTourEvents, BordaTourImageElements, BordaTourImageProps, BordaTourImageRef, BordaTourOverlayComponentClasses, BordaTourOverlayComponentStyles, BordaTourOverlayElements, BordaTourOverlayEvents, BordaTourOverlayProps, BordaTourOverlayRef, BordaTourProgressComponentClasses, BordaTourProgressComponentHtml, BordaTourProgressComponentStyles, BordaTourProgressElements, BordaTourProgressProps, BordaTourProgressRef, BordaTourProps, BordaTourRef, BordaTourResolvedButton, BordaTourSkipComponentClasses, BordaTourSkipComponentHtml, BordaTourSkipComponentStyles, BordaTourSkipElements, BordaTourSkipEvents, BordaTourSkipProps, BordaTourSkipRef, BordaTourTooltipAnimation, BordaTourTooltipArrowProps, BordaTourTooltipAutoPlacement, BordaTourTooltipComponentClasses, BordaTourTooltipComponentHtml, BordaTourTooltipComponentStyles, BordaTourTooltipElements, BordaTourTooltipPositionProps, BordaTourTooltipProps, BordaTourTooltipRef, BordaTourTooltipSnippets, BordaVisibilityApi, BordaVisibilityConfig, ComponentAriaProps, ComponentClasses, ComponentRef, ComponentSnippet, ComponentSnippetReturn, ComponentStyles, UseBordaAnimationReturns, UseBordaConfigReturns, UseBordaControllerReturns, UseBordaHighlightReturns, UseBordaKeyboardReturns, UseBordaOverridesReturns, UseBordaResponsiveReturns, UseBordaReturns, UseBordaScrollReturns, UseBordaSkipReturns, UseBordaVisibilityReturns, UseOverlayProps, UseOverlayReturns, UseTooltipArrowProps, UseTooltipArrowReturns, UseTooltipLayoutProps, UseTooltipLayoutReturns, UseTooltipPositionProps, UseTooltipPositionReturns };