@sahabaplus/mushaf-engine/dist/navigation/navigationSettings.d.ts

TypeScript implementation of a Quran Mushaf navigation engine

import { NavigationBounds } from "./navigationBounds";
import { VersePosition } from "./versePosition";
/**
 * Builder class for NavigationSettings
 */
export declare class NavigationSettingsBuilder {
    private ignoreSuraHeader;
    private bounds;
    /**
     * Sets whether to ignore sura headers in line calculations.
     *
     * @param ignoreSuraHeader - Whether to exclude sura headers from calculations
     * @returns This builder instance
     */
    setIgnoreSuraHeader(ignoreSuraHeader: boolean): NavigationSettingsBuilder;
    /**
     * Sets the navigation bounds directly.
     *
     * @param bounds - Complete navigation bounds configuration
     * @returns This builder instance
     */
    setBounds(bounds: NavigationBounds): NavigationSettingsBuilder;
    /**
     * Sets the iteration limit for the navigation bounds.
     *
     * @param iterationLimit - Maximum number of complete cycles through the range
     * @returns This builder instance
     */
    setIterationLimit(iterationLimit: number): NavigationSettingsBuilder;
    /**
     * Sets the upper bound for navigation.
     *
     * @param upperBound - Upper bound for navigation
     * @returns This builder instance
     * @note When upperBound > lowerBound, excluding mode is enabled
     */
    setUpperBound(upperBound: VersePosition): NavigationSettingsBuilder;
    /**
     * Sets the lower bound for navigation.
     *
     * @param lowerBound - Lower bound for navigation
     * @returns This builder instance
     * @note When upperBound > lowerBound, excluding mode is enabled
     */
    setLowerBound(lowerBound: VersePosition): NavigationSettingsBuilder;
    /**
     * Builds the NavigationSettings instance
     *
     * @returns The configured NavigationSettings
     */
    build(): NavigationSettings;
}
/**
 * Comprehensive settings for verse navigation behavior.
 *
 * `NavigationSettings` combines navigation bounds with additional behavioral options
 * to control how the `VersesNavigator` operates. It serves as the central configuration
 * for all navigation operations.
 *
 * # Key Features
 *
 * ## Bounds Control
 * The `bounds` field contains a `NavigationBounds` that defines:
 * - Iteration limits (how many cycles through a range)
 * - Upper and lower bounds for navigation
 *   - Inclusive mode: upperBound < lowerBound (navigate within range)
 *   - Excluding mode: upperBound > lowerBound (navigate everywhere except the excluded range)
 *
 * ## Header Handling
 * The `ignoreSuraHeader` field controls whether sura headers (bismillah and sura titles)
 * are included in line calculations:
 * - `false` (default): Include sura headers in line calculations
 * - `true`: Exclude sura headers from line calculations
 */
export declare class NavigationSettings {
    readonly ignoreSuraHeader: boolean;
    readonly bounds: NavigationBounds;
    /**
     * Creates new navigation settings with specified header handling and bounds.
     *
     * @param ignoreSuraHeader - Whether to exclude sura headers from line calculations
     * @param bounds - Navigation bounds containing iteration limits and positions
     */
    constructor(ignoreSuraHeader: boolean, bounds: NavigationBounds);
    /**
     * Creates a builder for navigation settings with default values.
     *
     * Default values:
     * - `ignoreSuraHeader`: false (include headers)
     * - `iterationLimit`: 0 (no cycling)
     * - `upperBound`: (1, 1) - beginning of Al-Fatiha
     * - `lowerBound`: (114, 6) - end of An-Nas
     */
    static builder(): NavigationSettingsBuilder;
    /**
     * Get whether to ignore sura headers
     *
     * @returns True if sura headers should be ignored
     */
    getIgnoreSuraHeader(): boolean;
    /**
     * Get the navigation bounds
     *
     * @returns The navigation bounds
     */
    getBounds(): NavigationBounds;
}