@svelte-atoms/core 1.0.0-alpha.14

package/dist/components/scrollable/bond.svelte.d.ts

@@ -0,0 +1,268 @@
+import { Bond, BondState, type BondStateProps } from '../../shared/bond.svelte';
+/**
+ * Properties for the scrollable state containing all scroll-related data
+ * Extends BondStateProps with scrollable-specific properties
+ */
+export type ScrollableStateProps = BondStateProps & {
+    /** Current horizontal scroll position in pixels */
+    scrollX: number;
+    /** Current vertical scroll position in pixels */
+    scrollY: number;
+    /** Total scrollable width of content in pixels */
+    scrollWidth: number;
+    /** Total scrollable height of content in pixels */
+    scrollHeight: number;
+    /** Visible width of the scrollable area in pixels */
+    clientWidth: number;
+    /** Visible height of the scrollable area in pixels */
+    clientHeight: number;
+    /** Whether scrolling is disabled */
+    disabled: boolean;
+    /** Whether custom scrollbars should be hidden */
+    open: boolean;
+    /** Indicates if the user is currently scrolling */
+    isScrolling?: boolean;
+};
+/**
+ * DOM elements managed by the scrollable bond
+ * Each element represents a part of the scrollable interface
+ */
+export type ScrollableDomElements = {
+    /** The root scrollable container element (acts as both root and scroll container) */
+    root: HTMLElement;
+    /** The container wrapper element that holds scrollable content and UI */
+    container: HTMLElement;
+    /** The content wrapper element that defines scrollable bounds */
+    content: HTMLElement;
+    /** Horizontal scrollbar track element */
+    trackX: HTMLElement;
+    /** Vertical scrollbar track element */
+    trackY: HTMLElement;
+    /** Horizontal scrollbar thumb element */
+    thumbX: HTMLElement;
+    /** Vertical scrollbar thumb element */
+    thumbY: HTMLElement;
+};
+/**
+ * Main bond class that manages scrollable state and DOM element interactions
+ * Extends the base Bond class with scrollable-specific functionality
+ */
+export declare class ScrollableBond extends Bond<ScrollableStateProps, ScrollableState, ScrollableDomElements> {
+    #private;
+    /** Unique key for identifying this bond type in the context system */
+    static CONTEXT_KEY: string;
+    /**
+     * Creates a new scrollable bond instance
+     * @param state - The scrollable state instance to manage
+     */
+    constructor(state: ScrollableState);
+    /**
+     * Gets the parent scrollable bond if this is a nested scrollable
+     * @returns The parent bond or undefined if this is the root scrollable
+     */
+    get parent(): ScrollableBond | undefined;
+    /**
+     * Shares this bond instance through the context system
+     * Makes this bond available to child components
+     * @returns This bond instance for chaining
+     */
+    share(): this;
+    /**
+     * Retrieves the current scrollable bond from context
+     * @returns The active scrollable bond or undefined if none exists
+     */
+    static get(): ScrollableBond | undefined;
+    /**
+     * Sets the scrollable bond in context for child components
+     * @param bond - The bond instance to set in context
+     * @returns The bond that was set
+     */
+    static set(bond: ScrollableBond): ScrollableBond;
+    /**
+     * Creates props for the root element with hidden overflow
+     * The root element contains the entire scrollable interface but doesn't scroll itself
+     * @param props - Additional props to merge with the generated props
+     * @returns Object containing all necessary props for the root element
+     */
+    root(props?: Record<string, unknown>): {
+        'data-atom': string;
+        'data-kind': string;
+        'data-disabled': boolean;
+        'data-open': boolean;
+    };
+    /**
+     * Creates props for the scrollable container element
+     * This element is the actual scrollable area that handles scroll events
+     * @param props - Additional props to merge with the generated props
+     * @returns Object containing all necessary props for the container element
+     */
+    container(props?: Record<string, unknown>): {
+        'data-atom': string;
+        'data-kind': string;
+        onscroll: (e: Event) => void;
+    };
+    /**
+     * Creates props for the scrollable content wrapper element
+     * This element defines the boundaries and size of the scrollable content
+     * @param props - Additional props to merge with the generated props
+     * @returns Object containing all necessary props for the content element
+     */
+    content(props?: Record<string, unknown>): {
+        'data-atom': string;
+        'data-kind': string;
+    };
+    /**
+     * Creates props for the horizontal scrollbar track element
+     * Provides click-to-scroll functionality for horizontal navigation
+     * @param props - Additional props to merge with the generated props
+     * @returns Object containing all necessary props for the horizontal track element
+     */
+    trackX(props?: Record<string, unknown>): {
+        onclick: (e: MouseEvent) => void;
+        'data-atom': string;
+        'data-kind': string;
+        'data-visible': boolean;
+    };
+    /**
+     * Creates props for the vertical scrollbar track element
+     * Provides click-to-scroll functionality for vertical navigation
+     * @param props - Additional props to merge with the generated props
+     * @returns Object containing all necessary props for the vertical track element
+     */
+    trackY(props?: Record<string, unknown>): {
+        onclick: (e: MouseEvent) => void;
+        'data-atom': string;
+        'data-kind': string;
+        'data-visible': boolean;
+    };
+    /**
+     * Creates props for the horizontal scrollbar thumb element
+     * Provides drag-to-scroll functionality and automatic positioning/sizing
+     * @param props - Additional props to merge with the generated props
+     * @returns Object containing all necessary props for the horizontal thumb element
+     */
+    thumbX(props?: Record<string, unknown>): {
+        style: string;
+        onmousedown: (e: MouseEvent) => void;
+        'data-atom': string;
+        'data-kind': string;
+    };
+    /**
+     * Creates props for the vertical scrollbar thumb element
+     * Provides drag-to-scroll functionality and automatic positioning/sizing
+     * @param props - Additional props to merge with the generated props
+     * @returns Object containing all necessary props for the vertical thumb element
+     */
+    thumbY(props?: Record<string, unknown>): {
+        style: string;
+        onmousedown: (e: MouseEvent) => void;
+        'data-atom': string;
+        'data-kind': string;
+    };
+    /**
+     * Creates props for a unified track element that can be oriented horizontally or vertically
+     * This method provides a single interface for both horizontal and vertical tracks
+     * @param orientation - The track orientation ('horizontal' or 'vertical')
+     * @param props - Additional props to merge with the generated props
+     * @returns Object containing all necessary props for the track element
+     */
+    track(orientation: 'horizontal' | 'vertical', props?: Record<string, unknown>): {
+        onclick: (e: MouseEvent) => void;
+        'data-atom': string;
+        'data-kind': string;
+        'data-direction': "horizontal" | "vertical";
+        'data-visible': boolean;
+    };
+    /**
+     * Creates props for a unified thumb element that can be oriented horizontally or vertically
+     * This method provides a single interface for both horizontal and vertical thumbs
+     * @param orientation - The thumb orientation ('horizontal' or 'vertical')
+     * @param props - Additional props to merge with the generated props
+     * @returns Object containing all necessary props for the thumb element
+     */
+    thumb(orientation: 'horizontal' | 'vertical', props?: Record<string, unknown>): {
+        onmousedown: (e: MouseEvent) => void;
+        'data-atom': string;
+        'data-kind': string;
+        'data-direction': "horizontal" | "vertical";
+    };
+    /**
+     * Handles click events on scrollbar tracks for jump-to-position scrolling
+     * Calculates the click position as a percentage and scrolls to that position
+     * @param e - The mouse event from the track click
+     * @param axis - The scroll axis ('x' for horizontal, 'y' for vertical)
+     */
+    private handleTrackClick;
+    /**
+     * Handles mouse drag events on scrollbar thumbs for precise scrolling control
+     * Sets up mouse event listeners for drag-to-scroll functionality
+     * @param e - The initial mousedown event on the thumb
+     * @param axis - The scroll axis ('x' for horizontal, 'y' for vertical)
+     */
+    private handleThumbDrag;
+    /**
+     * Scrolls to an absolute position in the scrollable area
+     * @param x - The horizontal scroll position in pixels
+     * @param y - The vertical scroll position in pixels
+     */
+    scrollTo(x: number, y: number): void;
+    /**
+     * Scrolls by a relative amount from the current position
+     * @param x - The horizontal scroll delta in pixels
+     * @param y - The vertical scroll delta in pixels
+     */
+    scrollBy(x: number, y: number): void;
+    /**
+     * Scrolls an element into view within the scrollable area
+     * @param element - The element to scroll into view
+     * @param options - Optional scroll behavior configuration
+     */
+    scrollIntoView(element: Element, options?: ScrollIntoViewOptions): void;
+    /**
+     * Updates the internal scroll state based on current DOM measurements
+     * This method should be called when the scroll position or content size changes
+     * TODO: Implement reactive binding updates for scroll properties
+     */
+    updateScrollState(): void;
+    /**
+     * Calculates the horizontal thumb position as a percentage
+     * @returns The left position of the horizontal thumb (0-100%)
+     */
+    getThumbXPosition(): number;
+    /**
+     * Calculates the vertical thumb position as a percentage
+     * @returns The top position of the vertical thumb (0-100%)
+     */
+    getThumbYPosition(): number;
+    /**
+     * Calculates the horizontal thumb size as a percentage
+     * @returns The width of the horizontal thumb (0-100%)
+     */
+    getThumbXSize(): number;
+    /**
+     * Calculates the vertical thumb size as a percentage
+     * @returns The height of the vertical thumb (0-100%)
+     */
+    getThumbYSize(): number;
+    /**
+     * Determines if horizontal scrolling is possible
+     * @returns True if content width exceeds visible area width
+     */
+    get canScrollX(): boolean;
+    /**
+     * Determines if vertical scrolling is possible
+     * @returns True if content height exceeds visible area height
+     */
+    get canScrollY(): boolean;
+}
+/**
+ * Reactive state container for scrollable component properties
+ * Extends BondState to provide typed access to scroll-related data
+ */
+export declare class ScrollableState extends BondState<ScrollableStateProps> {
+    /**
+     * Creates a new scrollable state instance
+     * @param props - Function that returns the current state properties
+     */
+    constructor(props: () => ScrollableStateProps);
+}