Proyectos de Subversion Moodle

// This file is part of Moodle - http://moodle.org/

//

// Moodle is free software: you can redistribute it and/or modify

// it under the terms of the GNU General Public License as published by

// the Free Software Foundation, either version 3 of the License, or

// (at your option) any later version.

//

// Moodle is distributed in the hope that it will be useful,

// but WITHOUT ANY WARRANTY; without even the implied warranty of

// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

// GNU General Public License for more details.

//

// You should have received a copy of the GNU General Public License

// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

import $ from 'jquery';

import Dropdown from 'theme_boost/bootstrap/dropdown';

import {debounce} from 'core/utils';

import Pending from 'core/pending';

import {get_string as getString} from 'core/str';

/**

 * The class that manages the state of the search within a combobox.

 *

 * @module    core/comboboxsearch/search_combobox

 * @copyright 2023 Mathew May <mathew.solutions>

 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

export default class {

    // Define our standard lookups.

    selectors = {

        component: this.componentSelector(),

        toggle: '[data-bs-toggle="dropdown"]',

        instance: '[data-region="instance"]',

        input: '[data-action="search"]',

        clearSearch: '[data-action="clearsearch"]',

        dropdown: this.dropdownSelector(),

        resultitems: '[role="option"]',

        viewall: '#select-all',

        combobox: '[role="combobox"]',

    };

    // The results from the called filter function.

    matchedResults = [];

    // What did the user search for?

    searchTerm = '';

    // What the user searched for as a lowercase.

    preppedSearchTerm = null;

    // The DOM nodes after the dropdown render.

    resultNodes = [];

    // Where does the user currently have focus?

    currentNode = null;

    // The current node for the view all link.

    currentViewAll = null;

    dataset = null;

    datasetSize = 0;

    // DOM nodes that persist.

    component = document.querySelector(this.selectors.component);

    instance = this.component.dataset.instance;

    toggle = this.component.querySelector(this.selectors.toggle);

    searchInput = this.component.querySelector(this.selectors.input);

    searchDropdown = this.component.querySelector(this.selectors.dropdown);

    clearSearchButton = this.component.querySelector(this.selectors.clearSearch);

    combobox = this.component.querySelector(this.selectors.combobox);

    $component = $(this.component);

    constructor() {

        // If we have a search input, try to get the value otherwise fallback.

        this.setSearchTerms(this.searchInput?.value ?? '');

        // Begin handling the base search component.

        this.registerClickHandlers();

        // Conditionally set up the input handler since we don't know exactly how we were called.

        // If the combobox is rendered later, then you'll need to call this.registerInputHandlers() manually.

        // An example of this is the collapse columns in the gradebook.

        if (this.searchInput !== null) {

            this.registerInputHandlers();

            this.registerChangeHandlers();

        }

        // If we have a search term, show the clear button.

        if (this.getSearchTerm() !== '') {

            this.clearSearchButton.classList.remove('d-none');

        }

    }

    /**

     * Stub out a required function.

     */

    fetchDataset() {

        throw new Error(`fetchDataset() must be implemented in ${this.constructor.name}`);

    }

    /**

     * Stub out a required function.

     * @param {Array} dataset

     */

    filterDataset(dataset) {

        throw new Error(`filterDataset(${dataset}) must be implemented in ${this.constructor.name}`);

    }

    /**

     * Stub out a required function.

     */

    filterMatchDataset() {

        throw new Error(`filterMatchDataset() must be implemented in ${this.constructor.name}`);

    }

    /**

     * Stub out a required function.

     */

    renderDropdown() {

        throw new Error(`renderDropdown() must be implemented in ${this.constructor.name}`);

    }

    /**

     * Stub out a required function.

     */

    componentSelector() {

        throw new Error(`componentSelector() must be implemented in ${this.constructor.name}`);

    }

    /**

     * Stub out a required function.

     */

    dropdownSelector() {

        throw new Error(`dropdownSelector() must be implemented in ${this.constructor.name}`);

    }

    /**

     * Stub out a required function.

     * @deprecated since Moodle 4.4

     */

    triggerSelector() {

        window.console.warning('triggerSelector() is deprecated. Consider using this.selectors.toggle');

    }

    /**

     * Return the dataset that we will be searching upon.

     *

     * @returns {Promise<null>}

     */

    async getDataset() {

        if (!this.dataset) {

            this.dataset = await this.fetchDataset();

        }

        this.datasetSize = this.dataset.length;

        return this.dataset;

    }

    /**

     * Return the size of the dataset.

     *

     * @returns {number}

     */

    getDatasetSize() {

        return this.datasetSize;

    }

    /**

     * Return the results of the filter upon the dataset.

     *

     * @returns {Array}

     */

    getMatchedResults() {

        return this.matchedResults;

    }

    /**

     * Given a filter has been run across the dataset, store the matched results.

     *

     * @param {Array} result

     */

    setMatchedResults(result) {

        this.matchedResults = result;

    }

    /**

     * Get the value that the user entered.

     *

     * @returns {string}

     */

    getSearchTerm() {

        return this.searchTerm;

    }

    /**

     * Get the transformed search value.

     *

     * @returns {string}

     */

    getPreppedSearchTerm() {

        return this.preppedSearchTerm;

    }

    /**

     * When a user searches for something, set our variable to manage it.

     *

     * @param {string} result

     */

    setSearchTerms(result) {

        this.searchTerm = result;

        this.preppedSearchTerm = result.toLowerCase();

    }

    /**

     * Return an object containing a handfull of dom nodes that we sometimes need the value of.

     *

     * @returns {object}

     */

    getHTMLElements() {

        this.updateNodes();

        return {

            searchDropdown: this.searchDropdown,

            currentViewAll: this.currentViewAll,

            searchInput: this.searchInput,

            clearSearchButton: this.clearSearchButton,

            trigger: this.component.querySelector(this.selectors.trigger),

        };

    }

    /**

     * When called, close the dropdown and reset the input field attributes.

     *

     * @param {Boolean} clear Conditionality clear the input box.

     */

    closeSearch(clear = false) {

        this.toggleDropdown();

        if (clear) {

            // Hide the "clear" search button search bar.

            this.clearSearchButton.classList.add('d-none');

            // Clear the entered search query in the search bar and hide the search results container.

            this.setSearchTerms('');

            this.searchInput.value = "";

        }

    }

    /**

     * Check whether search results are currently visible.

     *

     * @returns {Boolean}

     */

    searchResultsVisible() {

        const {searchDropdown} = this.getHTMLElements();

        // If a Node is not visible, then the offsetParent is null.

        return searchDropdown.offsetParent !== null;

    }

    /**

     * When called, update the dropdown fields.

     *

     * @param {Boolean} on Flag to toggle hiding or showing values.

     */

    toggleDropdown(on = false) {

        if (on) {

            Dropdown.getOrCreateInstance(this.toggle).show();

        } else {

            Dropdown.getOrCreateInstance(this.toggle).hide();

        }

    }

    /**

     * These class members change when a new result set is rendered. So update for fresh data.

     */

    updateNodes() {

        this.resultNodes = [...this.component.querySelectorAll(this.selectors.resultitems)];

        this.currentNode = this.resultNodes.find(r => r.id === document.activeElement.id);

        this.currentViewAll = this.component.querySelector(this.selectors.viewall);

        this.clearSearchButton = this.component.querySelector(this.selectors.clearSearch);

        this.searchInput = this.component.querySelector(this.selectors.input);

        this.searchDropdown = this.component.querySelector(this.selectors.dropdown);

    }

    /**

     * Register clickable event listeners.

     */

    registerClickHandlers() {

        // Register click events within the component.

        this.component.addEventListener('click', this.clickHandler.bind(this));

    }

    /**

     * Register change event listeners.

     */

    registerChangeHandlers() {

        const valueElement = this.component.querySelector(`#${this.combobox.dataset.inputElement}`);

        valueElement.addEventListener('change', this.changeHandler.bind(this));

    }

    /**

     * Register input event listener for the text input area.

     */

    registerInputHandlers() {

        // Register & handle the text input.

        this.searchInput.addEventListener('input', debounce(async() => {

            if (this.getSearchTerm() === this.searchInput.value && this.searchResultsVisible()) {

                window.console.warn(`Search term matches input value - skipping`);

                // The debounce canhappen multiple times quickly. GRrargh

                return;

            }

            this.setSearchTerms(this.searchInput.value);

            const pendingPromise = new Pending();

            if (this.getSearchTerm() === '') {

                this.toggleDropdown();

                this.clearSearchButton.classList.add('d-none');

                await this.filterrenderpipe();

            } else {

                this.clearSearchButton.classList.remove('d-none');

                await this.renderAndShow();

            }

            pendingPromise.resolve();

        }, 300, {pending: true}));

    }

    /**

     * Update any changeable nodes, filter and then render the result.

     *

     * @returns {Promise<void>}

     */

    async filterrenderpipe() {

        this.updateNodes();

        this.setMatchedResults(await this.filterDataset(await this.getDataset()));

        this.filterMatchDataset();

        await this.renderDropdown();

        await this.updateLiveRegion();

    }

    /**

     * A combo method to take the matching fields and render out the results.

     *

     * @returns {Promise<void>}

     */

    async renderAndShow() {

        // User has given something for us to filter against.

        this.setMatchedResults(await this.filterDataset(await this.getDataset()));

        await this.filterMatchDataset();

        // Replace the dropdown node contents and show the results.

        await this.renderDropdown();

        // Set the dropdown to open.

        this.toggleDropdown(true);

        await this.updateLiveRegion();

    }

    /**

     * The handler for when a user interacts with the component.

     *

     * @param {MouseEvent} e The triggering event that we are working with.

     */

    async clickHandler(e) {

        this.updateNodes();

        // The "clear search" button is triggered.

        if (e.target.closest(this.selectors.clearSearch)) {

            this.closeSearch(true);

            this.searchInput.focus();

            // Remove aria-activedescendant when the available options change.

            this.searchInput.removeAttribute('aria-activedescendant');

        }

        // User may have accidentally clicked off the dropdown and wants to reopen it.

        if (

            this.getSearchTerm() !== ''

            && !this.getHTMLElements().searchDropdown.classList.contains('show')

            && e.target.closest(this.selectors.input)

        ) {

            await this.renderAndShow();

        }

    }

    /**

     * The handler for when a user changes the value of the component (selects an option from the dropdown).

     *

     * @param {Event} e The change event.

     */

    // eslint-disable-next-line no-unused-vars

    changeHandler(e) {

        // Components may override this method to do something.

    }

    /**

     * Updates the screen reader live region with the result count.

     */

    async updateLiveRegion() {

        if (!this.searchDropdown?.id) {

            return;

        }

        const idParts = this.searchDropdown.id.split('-');

        if (idParts.length < 3) {

            return;

        }

        const [, instanceId, id] = idParts; // E.g. dialog-12-34 only want the last two parts.

        const liveRegion = document.getElementById(`combobox-status-${instanceId}-${id}`);

        if (!liveRegion) {

            return;

        }

        const resultCount = this.getMatchedResults().length;

        let message;

        if (resultCount === 0) {

            message = await getString('noitemsfound', 'core');

        } else if (resultCount === 1) {

            message = await getString('oneitemfound', 'core');

        } else {

            message = await getString('multipleitemsfound', 'core', resultCount);

        }

        liveRegion.textContent = message;

        // Reset previous timeout if it exists.

        if (this.liveRegionTimeout) {

            clearTimeout(this.liveRegionTimeout);

        }

        // Clear the feedback message after 4 seconds. This is similar to the default timeout of toast messages

        // before disappearing from view. It is important to clear the message to prevent screen reader users from navigating

        // into this region and avoiding confusion.

        this.liveRegionTimeout = setTimeout(() => {

            liveRegion.textContent = '';

            this.liveRegionTimeout = null;

        }, 4000);

    }

}