@liturgical-calendar/components-js
Version:
Liturgical calendar components for javascript: an html select populated with liturgical calendars supported by the Liturgical Calendar API; form controls for parameters that are supported by the Liturgical Calendar API; a webcalendar; and liturgy of the d
419 lines • 22.9 kB
TypeScript
/**
* Creates a select menu populated with available liturgical calendars from the Liturgical Calendar API
*
* @example
* const calendarSelect = new CalendarSelect();
* calendarSelect.appendTo( '#calendar-select' );
*
* @example
* const calendarSelect = new CalendarSelect('it-IT');
* calendarSelect.allowNull().label({
class: 'form-label d-block mb-1',
id: 'liturgicalCalendarSelectItaLabel',
text: 'Seleziona calendario'
}).wrapper({
class: 'form-group col col-md-3',
id: 'liturgicalCalendarSelectItaWrapper'
}).id('liturgicalCalendarSelectEng').class('form-select').replace( '#calendar-select' );
*
* @author [John Romano D'Orazio](https://github.com/JohnRDOrazio)
* @license Apache-2.0
* @see https://github.com/Liturgical-Calendar/liturgy-components-js
*/
export default class CalendarSelect {
static "__#10@#metadata": null;
static "__#10@#nationalCalendars": any[];
static "__#10@#diocesanCalendars": any[];
static "__#10@#nationalCalendarsWithDioceses": any[];
/**
* Validates if the given class name adheres to standard CSS class naming conventions.
*
* The regex pattern used to validate class names:
* - `^` asserts the start of a line
* - `(?!\d|--|-?\d)` is a negative lookahead that prevents the class name
* from starting with a digit, or a sequence of dashes, or a number with a leading dash
* - `[a-zA-Z_-]` matches any character that is a letter, a dash or an underscore
* - `[a-zA-Z\d_-]{1,}` matches any alphanumeric character, a dash or an underscore at least once
* - `$` asserts the end of a line
*
* @param {string} className - The class name to validate.
* @returns {boolean} True if the class name is valid, false otherwise.
* @private
* @static
*/
private static "__#10@#isValidClassName";
/**
* Validates if the given ID adheres to HTML and CSS ID naming conventions.
*
* The regex pattern used to validate IDs:
* - `^` asserts the start of a line
* - `(?!\d|--|-?\d)` is a negative lookahead that prevents the ID
* from starting with a digit, a sequence of dashes, or a number with a leading dash
* - `(?:[_-][a-zA-Z][\w\-]*|[a-zA-Z][\w\-]*)` matches either a sequence starting with an underscore or dash
* followed by a letter and zero or more word characters or dashes,
* or it matches a letter followed by zero or more word characters or dashes
* - `$` asserts the end of a line
*
* Note: While ID attribute values can contain any Unicode character,
* they must be valid CSS identifiers when used in CSS selectors or with JavaScript methods like `querySelector`.
*
* @param {string} id - The ID to validate.
* @returns {boolean} True if the ID is valid, false otherwise.
* @private
* @static
*/
private static "__#10@#isValidId";
/**
* Returns true if we have already stored a national calendar with dioceses for the given nation,
* that is when diocesan calendars belong to the same national calendar, and false otherwise.
*
* @param {string} nation - The nation to check.
* @returns {boolean} True if we have stored a national calendar with dioceses for the given nation, false otherwise.
* @private
* @static
*/
private static "__#10@#hasNationalCalendarWithDioceses";
/**
* Adds a national calendar with dioceses for the given nation.
*
* This internal method is used to add a national calendar with dioceses to the list of national calendars with dioceses.
* This will also initialize diocese select options for the given nation.
*
* @param {string} nation - The nation for which we should add the national calendar.
* @private
* @static
*/
private static "__#10@#addNationalCalendarWithDioceses";
/**
* Initializes the CalendarSelect class.
*
* This method initializes the CalendarSelect class by storing the metadata obtained from the ApiClient
* class in a private class property. This method must be called before any CalendarSelect instances are created.
* If the ApiClient class has not been initialized, or failed to initialize, an error will be thrown.
*
* @throws {Error} If the ApiClient class has not been initialized.
* @throws {Error} If the ApiClient class failed to initialize.
* @throws {Error} If the ApiClient class initialized with an invalid object.
* @throws {Error} If the ApiClient class initialized with an object that does not contain the expected properties.
* @static
* @private
*/
private static "__#10@#init";
/**
* Constructor for the CalendarSelect class.
*
* @param {Object|string} [options] - The options object or locale string. An options object can have the following properties:
* - locale: The locale to use for the CalendarSelect UI elements.
* - id: The ID of the CalendarSelect element.
* - class: The class name for the CalendarSelect element.
* - name: The name for the CalendarSelect element.
* - filter: The CalendarSelectFilter to apply to the CalendarSelect element.
* - after: an html string to append after the CalendarSelect element.
* - allowNull: a boolean to indicate if the CalendarSelect element should allow null values.
* - disabled: a boolean to indicate if the CalendarSelect element should be disabled.
* - label: The label for the CalendarSelect element (an object with a `text` property, and optionally `class` and `id` properties).
* - wrapper: The wrapper for the CalendarSelect element (an object with an `as` property, and optionally `class` and `id` properties).
* If a string is passed, it is expected to be the locale code to use for the CalendarSelect UI elements.
* The locale should be a valid string that can be parsed by the Intl.getCanonicalLocales function.
* If the locale string contains an underscore, the underscore will be replaced with a hyphen.
*
* @throws {Error} If the locale is invalid.
*/
constructor(options?: Object | string);
/**
* Retrieves the HTML string for the nation options.
*
* This getter method concatenates all the nation options into a single HTML string,
* which can be used to populate a select element with nation options.
*
* @returns {string} A concatenated string of all nation options in HTML format.
*/
get nationsInnerHtml(): string;
/**
* Retrieves the HTML string for the diocese options grouped by nation.
*
* This getter method concatenates all the diocese options grouped by nation into a single HTML string,
* which can be used to populate a select element with diocese options for each nation.
*
* @returns {string} A concatenated string of all diocese options grouped by nation in HTML format.
*/
get diocesesInnerHtml(): string;
/**
* Sets the filter for the select element.
*
* The filter can be either `CalendarSelectFilter.NATIONAL_CALENDARS`, `CalendarSelectFilter.DIOCESAN_CALENDARS`, or `CalendarSelectFilter.NONE`.
* - `CalendarSelectFilter.NATIONAL_CALENDARS` will show only the nation options.
* - `CalendarSelectFilter.DIOCESAN_CALENDARS` will show only the diocese options grouped by nation.
* - `CalendarSelectFilter.NONE` will show all options, that is, for all calendars whether national or diocesan.
*
* If the filter is set to a value that is not a valid value for the `CalendarSelectFilter` enum,
* an error will be thrown.
*
* If the filter is set to a value that is different from the current filter,
* the innerHTML of the select element will be updated accordingly, and will not be able to be set again.
*
* @param {string} [filter=CalendarSelectFilter.NONE] The filter to set.
* @returns {this}
*/
filter(filter?: string): this;
/**
* Sets the class attribute for the CalendarSelect instance's DOM element.
*
* Validates the input class name(s) to ensure they are strings and conform to
* CSS class naming conventions. If the class name is valid, it is sanitized
* and assigned to the element. If the class name is an empty string, the
* class attribute is removed.
*
* @param {string} className - A space-separated string of class names to be
* assigned to the DOM element.
* @throws {Error} If the className is not a string, or if any class name is
* invalid.
* @returns {CalendarSelect} The current CalendarSelect instance for chaining.
*/
class(className: string): CalendarSelect;
/**
* Sets the id attribute of the select element.
*
* Validates the input id to ensure it is a string and conforms to
* HTML id attribute naming conventions. If the id is valid, it is sanitized
* and assigned to the element. If the id is an empty string, the
* id attribute is removed.
*
* If the id has already been set, an error will be thrown.
*
* If the label has already been set, the for attribute of the label element
* will be updated to match the new id.
*
* @param {string} id The id attribute of the select element.
* @throws {Error} If the id is not a string, or if the id is invalid.
* @returns {CalendarSelect} The current CalendarSelect instance for chaining.
*/
id(id: string): CalendarSelect;
/**
* Sets the name attribute of the select element.
*
* Validates the input name to ensure it is a string. If the name is valid,
* it is sanitized and assigned to the element. If the name is an empty
* string, the name attribute is removed.
*
* If the name has already been set, an error will be thrown.
*
* @param {string} name The name attribute of the select element.
* @throws {Error} If the name is not a string, or if the name has already been set.
* @returns {CalendarSelect} The current CalendarSelect instance for chaining.
*/
name(name: string): CalendarSelect;
/**
* Configures the label element for the CalendarSelect instance.
*
* If label options are not provided, the label will not be created and
* any existing label will be removed. If an object is provided, it
* can specify label attributes such as class, id, and text. The method
* validates the options and sets the label accordingly.
*
* @param {Object|null} labelOptions An object specifying label options or null to disable the label.
* @param {string} [labelOptions.class] CSS classes to apply to the label element.
* @param {string} [labelOptions.id] The id attribute for the label element.
* @param {string} [labelOptions.text] The text content for the label element.
*
* @throws {Error} If the label options are not an object, or if the class, id, or text are not valid strings.
*
* @returns {CalendarSelect} The current CalendarSelect instance for chaining.
*/
label(labelOptions?: Object | null): CalendarSelect;
/**
* Sets the wrapper element for the calendar select element.
*
* The wrapper element is an HTML element that will wrap the select element.
* The wrapper element can be an HTML element of type `div` or `td`.
*
* If the `wrapperOptions` argument is not provided, the wrapper element will be set to `null`.
* If the `wrapperOptions` argument is provided but is not an object, an error will be thrown.
*
* The `wrapperOptions` object can contain the following properties:
* - `as`: The type of HTML element to use as the wrapper element.
* Must be one of `div` or `td`.
* If not provided, defaults to `div`.
* - `class`: The class attribute for the wrapper element.
* If not provided, no class will be set.
* - `id`: The id attribute for the wrapper element.
* If not provided, no id will be set.
*
* @param {object|null} [wrapperOptions=null]
* @returns {CalendarSelect}
* @throws {Error} If the `wrapperOptions` argument is not an object or is an array.
* @throws {Error} If the `wrapperOptions.as` property is not a string.
* @throws {Error} If the `wrapperOptions.as` property is not one of `div` or `td`.
* @throws {Error} If the `wrapperOptions.class` property is not a string.
* @throws {Error} If the `wrapperOptions.id` property is not a string.
* @throws {Error} If the `wrapperOptions.id` property is not a valid CSS selector.
*/
wrapper(wrapperOptions?: object | null): CalendarSelect;
/**
* Sets content to be inserted after the current element.
*
* This method allows appending content after the current element by creating
* a DocumentFragment from the provided content string. The content string is
* sanitized to remove PHP and script tags for security purposes. If no content
* is provided (null), it removes any previously set content. Throws an error
* if the method is called more than once since the content can only be set once.
*
* @param {string|null} contents - The content to be set after the current element.
* If null, any existing content is cleared.
* @throws {Error} If content is attempted to be set more than once.
* @returns {CalendarSelect} The current instance for method chaining.
*/
after(contents?: string | null): CalendarSelect;
/**
* Set whether the select element should include an empty option as the first option.
*
* If set to true, the select element will include an empty option as the first option.
* This can be useful when you want to allow the user to select no option.
* This also represents a value of "General Roman Calendar" for the API,
* since no national or diocesan calendar is selected.
* Selecting this empty value will enable the ApiOptions that can be set for the General Roman Calendar,
* but not for national or diocesan calendars, when an ApiOptions instance is listening to the current WebCalendar instance.
*
* If set to false, the select element will not include an empty option as the first option.
*
* If not provided, defaults to true.
*
* @param {boolean} [allowNull=true] - Whether the select element should include an empty option as the first option.
* @returns {CalendarSelect} The current instance for method chaining.
* @throws {Error} If allowNull has already been set on the CalendarSelect instance.
* @throws {Error} If the type of allowNull is not a boolean.
*/
allowNull(allowNull?: boolean): CalendarSelect;
/**
* Sets the disabled property on the select element.
*
* If set to true, the select element will be disabled and the user will not be able to interact with it.
* If set to false, the select element will be enabled and the user will be able to interact with it.
*
* If not provided, defaults to true.
*
* @param {boolean} [disabled=true] - Whether the select element should be disabled.
* @returns {CalendarSelect} The current instance for method chaining.
* @throws {Error} If the type of disabled is not a boolean.
*/
disabled(disabled?: boolean): CalendarSelect;
/**
* Replaces the element matched by the provided element selector with the select element.
*
* If a wrapper element has been set, the wrapper element is used to replace the element,
* and the select element is appended to the wrapper element.
* If a label element has been set, the label element is inserted before the select element.
* If an after element has been set, the after element is inserted after the select element.
*
* @param {string|HTMLElement} element - The element or elector of the element to be replaced.
* @throws {Error} If the type of element is not a string.
* @throws {Error} If the element selector is invalid.
*/
replace(element: string | HTMLElement): void;
/**
* Appends the select element to the element matched by the provided element selector (or the element provided directly).
*
* If a wrapper element has been set, the wrapper element is used to append the select element,
* and the select element is appended to the wrapper element.
* If a label element has been set, the label element is inserted before the select element.
* If an after element has been set, the after element is inserted after the select element.
*
* @param {string|HTMLElement} element - The element selector of the element to append the select element to.
* @throws {Error} If the type of element is not a string.
* @throws {Error} If the element selector is invalid.
*/
appendTo(element: string | HTMLElement): void;
/**
* Inserts the select element before the element matched by the provided element selector (or the element provided directly).
*
* If a wrapper element has been set, the wrapper element is used to insert the select element,
* and the select element is appended to the wrapper element.
* If a label element has been set, the label element is inserted before the select element.
* If an after element has been set, the after element is inserted after the select element.
*
* @param {string|HTMLElement|Input} element - The element selector of the element to insert the select element before.
* @throws {Error} If the type of element is not a string.
* @throws {Error} If the element selector is invalid.
*/
insertBefore(element: string | HTMLElement | Input): void;
/**
* Inserts the select element after the element matched by the provided element selector (or the element provided directly).
*
* If a wrapper element has been set, the wrapper element is used to insert the select element,
* and the select element is appended to the wrapper element.
* If a label element has been set, the label element is inserted before the select element.
* If an after element has been set, the after element is inserted after the select element.
*
* @param {string|HTMLElement|Input} element - The element selector of the element to insert the select element after.
* @throws {Error} If the type of element is not a string.
* @throws {Error} If the element selector is invalid.
*/
insertAfter(element: string | HTMLElement | Input): void;
/**
* Gets the underlying DOM element of the CalendarSelect instance.
*
* @returns {HTMLElement} The underlying DOM element of the CalendarSelect instance.
* @readonly
*/
readonly get _domElement(): HTMLElement;
/**
* Gets the current filter of the CalendarSelect instance.
*
* The filter can be either `CalendarSelectFilter.NATIONAL_CALENDARS`, `CalendarSelectFilter.DIOCESAN_CALENDARS`, or `CalendarSelectFilter.NONE`.
* - `CalendarSelectFilter.NATIONAL_CALENDARS` will show only the nation options.
* - `CalendarSelectFilter.DIOCESAN_CALENDARS` will show only the diocese options grouped by nation.
* - `CalendarSelectFilter.NONE` will show all options, that is, both nation and diocese options.
*
* @returns {string} The current filter of the CalendarSelect instance.
* @readonly
*/
readonly get _filter(): string;
/**
* Retrieves the status of whether a wrapper element has been set for the CalendarSelect instance.
*
* @returns {boolean} True if a wrapper element has been set; otherwise, false.
* @readonly
*/
readonly get _hasWrapper(): boolean;
/**
* Gets the wrapper element for the CalendarSelect instance.
*
* The wrapper element is an HTML element that will wrap the select element.
* The wrapper element can be an HTML element of type `div` or `td`.
*
* If the `wrapperOptions` argument was not provided when calling the `wrapper` method,
* this will be `null`.
*
* @returns {HTMLElement|null} The wrapper element for the CalendarSelect instance, or `null` if no wrapper element was set.
* @readonly
*/
readonly get _wrapperElement(): HTMLElement | null;
/**
* Gets the status of whether the current CalendarSelect instance allows a null selected value.
*
* When `true`, the CalendarSelect instance will have an option for "None" or "No selection", and the `value` property
* will return `null` when this option is selected.
*
* When `false`, the CalendarSelect instance will not have an option for "None" or "No selection", and the `value` property
* will return an empty string when no option is selected.
*
* @returns {boolean} True if the current CalendarSelect instance allows a null selected value; otherwise, false.
* @readonly
*/
readonly get _allowNull(): boolean;
/**
* Links the current `dioceses` filtered CalendarSelect instance to a `nations` filtered CalendarSelect instance.
* When the selected nation is changed in the linked `nations` filtered CalendarSelect instance, the diocese options
* of the current `dioceses` filtered CalendarSelect instance will be filtered accordingly.
* @param {CalendarSelect} calendarSelectInstance - The `nations` filtered CalendarSelect instance to link to the current `dioceses` filtered CalendarSelect instance.
* @returns {CalendarSelect} - The current `dioceses` filtered CalendarSelect instance.
* @throws {Error} If the current `dioceses` filtered CalendarSelect instance is already linked to another `nations` filtered CalendarSelect instance.
* @throws {Error} If the type of calendarSelectInstance is not a `CalendarSelect`.
* @throws {Error} If the filter of the current `dioceses` filtered CalendarSelect instance is not `dioceses`.
* @throws {Error} If the filter of the linked `nations` filtered CalendarSelect instance is not `nations`.
*/
linkToNationsSelect(calendarSelectInstance: CalendarSelect): CalendarSelect;
#private;
}
import Input from '../ApiOptions/Input/Input.js';
//# sourceMappingURL=CalendarSelect.d.ts.map