@sahabaplus/mushaf-engine/dist/navigation/navigationSettings.js

TypeScript implementation of a Quran Mushaf navigation engine

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.NavigationSettings = exports.NavigationSettingsBuilder = void 0;
const navigationBounds_1 = require("./navigationBounds");
/**
 * Builder class for NavigationSettings
 */
class NavigationSettingsBuilder {
    constructor() {
        this.ignoreSuraHeader = false;
        this.bounds = navigationBounds_1.NavigationBounds.default();
    }
    /**
     * Sets whether to ignore sura headers in line calculations.
     *
     * @param ignoreSuraHeader - Whether to exclude sura headers from calculations
     * @returns This builder instance
     */
    setIgnoreSuraHeader(ignoreSuraHeader) {
        this.ignoreSuraHeader = ignoreSuraHeader;
        return this;
    }
    /**
     * Sets the navigation bounds directly.
     *
     * @param bounds - Complete navigation bounds configuration
     * @returns This builder instance
     */
    setBounds(bounds) {
        this.bounds = bounds;
        return this;
    }
    /**
     * Sets the iteration limit for the navigation bounds.
     *
     * @param iterationLimit - Maximum number of complete cycles through the range
     * @returns This builder instance
     */
    setIterationLimit(iterationLimit) {
        this.bounds = new navigationBounds_1.NavigationBounds(iterationLimit, this.bounds.upperBound, this.bounds.lowerBound);
        return this;
    }
    /**
     * 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) {
        this.bounds = new navigationBounds_1.NavigationBounds(this.bounds.iterationLimit, upperBound, this.bounds.lowerBound);
        return this;
    }
    /**
     * 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) {
        this.bounds = new navigationBounds_1.NavigationBounds(this.bounds.iterationLimit, this.bounds.upperBound, lowerBound);
        return this;
    }
    /**
     * Builds the NavigationSettings instance
     *
     * @returns The configured NavigationSettings
     */
    build() {
        return new NavigationSettings(this.ignoreSuraHeader, this.bounds);
    }
}
exports.NavigationSettingsBuilder = NavigationSettingsBuilder;
/**
 * 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
 */
class NavigationSettings {
    /**
     * 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, bounds) {
        this.ignoreSuraHeader = ignoreSuraHeader;
        this.bounds = bounds;
    }
    /**
     * 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() {
        return new NavigationSettingsBuilder();
    }
    /**
     * Get whether to ignore sura headers
     *
     * @returns True if sura headers should be ignored
     */
    getIgnoreSuraHeader() {
        return this.ignoreSuraHeader;
    }
    /**
     * Get the navigation bounds
     *
     * @returns The navigation bounds
     */
    getBounds() {
        return this.bounds;
    }
}
exports.NavigationSettings = NavigationSettings;