@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
385 lines • 18.5 kB
TypeScript
export default class WebCalendar {
/**
* @type {['purple', 'red', 'green']}
* @private
* @readonly
*/
private static readonly "__#17@#HIGH_CONTRAST";
/**
* @type {['', 'I', 'II', 'III', 'IV']}
* @private
* @readonly
*/
private static readonly "__#17@#PSALTER_WEEK";
/**
* Sanitizes the given input string to prevent XSS attacks.
*
* It uses the DOMParser to parse the string as HTML and then extracts the
* text content of the parsed HTML document. This effectively strips any HTML
* tags from the input string.
*
* @param {string} input - The input string to sanitize.
* @returns {string} The sanitized string.
* @private
* @see https://stackoverflow.com/a/47140708/394921
*/
private static "__#17@#sanitizeInput";
/**
* Validates the given class name to ensure it is a valid CSS class name.
*
* A valid CSS class name is a string that starts with a letter, underscore or dash,
* followed by any number of alphanumeric characters, dashes or underscores.
*
* @param {string} className - The class name to validate.
* @returns {boolean} True if the class name is valid, false otherwise.
* @static
* @private
*/
private static "__#17@#isValidClassName";
/**
* Validates the given ID to ensure it is a valid HTML ID.
*
* A valid HTML ID is a string that starts with a letter, underscore or dash,
* followed by any number of alphanumeric characters, dashes or underscores.
*
* @param {string} id - The ID to validate.
* @returns {boolean} True if the ID is valid, false otherwise.
* @static
* @private
*/
private static "__#17@#isValidId";
/**
* Validates the given element selector to ensure it is a valid HTML element selector.
*
* @param {string} element - The element selector to validate.
* @returns {Element} The DOM element that the selector matches.
* @throws {Error} If the element selector is invalid or does not match any elements.
* @static
* @private
*/
private static "__#17@#validateElementSelector";
/**
* Constructor for the WebCalendar class.
*
* Creates a new instance of the WebCalendar class.
*
* The options object is optional and can contain any of the following properties:
* - class: string, the class to apply to the table element
* - id: string, the id to apply to the table element
* - firstColumnGrouping: Grouping, the grouping for the first column
* - removeHeaderRow: boolean, whether to remove the header row
* - removeCaption: boolean, whether to remove the caption element
* - psalterWeekColumn: boolean, whether to group events by psalter week
* - eventColor: ColorAs, the color to apply to events
* - seasonColor: ColorAs, the color to apply to seasons
* - seasonColorColumns: Column, the columns to apply the season color to
* - eventColorColumns: Column, the columns to apply the event color to
* - monthHeader: boolean, whether to include a month header
* - dateFormat: DateFormat, the format to use for dates
* - columnOrder: ColumnOrder, the order of the columns
* - gradeDisplay: GradeDisplay, the display of grades
*
* @param {Object} [options] - An object containing any of the above properties.
* @throws {Error} If any of the properties in the options object are invalid.
*/
constructor(options?: Object);
/**
* Sets the class attribute for the WebCalendar 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 {WebCalendar} The current WebCalendar instance for chaining.
*/
class(className: string): WebCalendar;
/**
* Sets the id attribute for the WebCalendar instance's DOM 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.
*
* @param {string} id - A string to be assigned to the id attribute of the DOM element.
* @throws {Error} If the id is not a string, or if the id is invalid.
* @returns {WebCalendar} The current WebCalendar instance for chaining.
*/
id(id: string): WebCalendar;
/**
* Sets the date format for the table.
*
* This method sets the format for the dates in the table. The following formats are supported:
* - FULL: The full date format for the locale, e.g. "Friday, March 3, 2023" or "venerdì 3 marzo 2023".
* - LONG: The long date format for the locale, e.g. "March 3, 2023" or "3 marzo 2023".
* - MEDIUM: The medium date format for the locale, e.g. "Mar 3, 2023" or "3 mar 2023".
* - SHORT: The short date format for the locale, e.g. "3/3/23" or "03/03/23".
* - DAY_ONLY: Only the day of the month and the weekday, e.g. "3 Friday" or "3 venerdì".
*
* The default is DateFormat::FULL.
*
* @param {DateFormat} dateFormat The date format to use.
* @throws {Error} If the input is not a string, or if the date format is not recognized.
* @returns {WebCalendar} The current instance of the class.
*/
dateFormat(dateFormat: DateFormat): WebCalendar;
/**
* Sets whether or not the caption should be removed from the table.
*
* This method controls whether or not the caption element is
* generated by the {@link WebCalendar.buildTable()} method. The default is true, meaning
* that the caption should not be generated (= should be removed).
*
* @param {boolean} removeCaption Whether the caption should be removed or not.
*
* @throws {Error} If the input is not a boolean.
* @returns {WebCalendar} The current instance of the class.
*/
removeCaption(removeCaption?: boolean): WebCalendar;
/**
* Sets whether or not the header row should be removed from the table.
*
* This method controls whether or not the header row is
* generated by the {@link WebCalendar.buildTable()} method. The default is true, meaning
* that the header row should not be generated (= should be removed).
*
* @param {boolean} removeHeaderRow Whether the header row should be removed or not.
*
* @throws {Error} If the input is not a boolean.
* @returns {WebCalendar} The current instance of the class.
*/
removeHeaderRow(removeHeaderRow?: boolean): WebCalendar;
/**
* Sets the grouping for the first column.
*
* This method sets the grouping for the first column of the table.
* The following groupings are supported:
* - Grouping.BY_MONTH: the first column will contain month groupings
* - Grouping.BY_LITURGICAL_SEASON: the first column will contain liturgical season groupings
*
* The default is Grouping.BY_LITURGICAL_SEASON.
*
* @param {Grouping} firstColumnGrouping The grouping to use for the first column.
* @throws {Error} If the input is not a valid Grouping.
* @returns {WebCalendar} The current instance of the class.
*/
firstColumnGrouping(firstColumnGrouping: Grouping): WebCalendar;
/**
* Sets the order of the third and fourth columns.
*
* This method sets the order of the third and fourth columns of the table.
* The following orders are supported:
* - ColumnOrder.GRADE_FIRST: the third column will contain the liturgical grade and the fourth column the event details
* - ColumnOrder.EVENT_DETAILS_FIRST: the third column will contain the event details and the fourth column the liturgical grade
*
* The default is ColumnOrder.EVENT_DETAILS_FIRST.
*
* @param {ColumnOrder} columnOrder The order of the third and fourth columns.
* @throws {Error} If the input is not a valid ColumnOrder.
* @returns {WebCalendar} The current instance of the class.
*/
columnOrder(columnOrder: ColumnOrder): WebCalendar;
/**
* Sets whether or not the psalter week grouping should be applied.
*
* This method sets whether or not the psalter week grouping should be applied
* to the table. The psalter week grouping groups events by psalter week.
* The psalter week is a number from 1 to 4 that indicates the week of Ordinary Time
* or the week of a seasonal week (Advent, Christmas, Lent, Easter).
*
* The default is true, meaning that the psalter week grouping should be applied.
*
* @param {boolean} boolVal Whether the psalter week grouping should be applied or not.
*
* @throws {Error} If the input is not a boolean.
* @returns {WebCalendar} The current instance of the class.
*/
psalterWeekColumn(boolVal?: boolean): WebCalendar;
/**
* Sets how the color of a single liturgical event is applied to the table.
*
* This method sets how the color of a single liturgical event is applied to the table.
* The following options are supported:
* - `ColorAs.BACKGROUND`: the color of the event is applied as the background color of the table cells
* - `ColorAs.CSS_CLASS`: the color of the event is applied as a CSS class to the table cells
* - `ColorAs.INDICATOR`: the color of the event is applied as a small 10px inline block element with radius 5px
*
* The default is `ColorAs.INDICATOR`.
*
* @param {ColorAs} eventColor The color representation to use for the events.
* @throws {Error} If the input is not a valid ColorAs.
* @returns {WebCalendar} The current instance of the class.
*/
eventColor(eventColor: ColorAs): WebCalendar;
/**
* Sets how the color of a liturgical season is applied to the table.
*
* This method sets how the color of a liturgical season is applied to the table.
* The following options are supported:
* - ColorAs.BACKGROUND: the color of the season is applied as the background color of the table cells
* - ColorAs.CSS_CLASS: the color of the season is applied as a CSS class to the table cells
* - ColorAs.INDICATOR: the color of the season is applied as a small 10px inline block element with radius 5px
*
* The default is ColorAs.BACKGROUND.
*
* @param {ColorAs} seasonColor The color representation to use for the seasons.
* @throws {Error} If the input is not a valid ColorAs.
* @returns {WebCalendar} The current instance of the class.
*/
seasonColor(seasonColor: ColorAs): WebCalendar;
/**
* Sets which columns to apply the season color to.
*
* This method sets the columns to which the season color will be applied.
* The input should be a number representing a bitfield of column flags.
* The following columns are supported:
* - Column.LITURGICAL_SEASON
* - Column.MONTH
* - Column.DATE
* - Column.EVENT_DETAILS
* - Column.GRADE
* - Column.PSALTER_WEEK
* - Column.ALL
* - Column.NONE
*
* The default is Column.ALL.
*
* @param {number} seasonColorColumns The column flags to set.
* @throws {Error} If the input is not a valid column flags.
* @returns {WebCalendar} The current instance of the class.
*/
seasonColorColumns(seasonColorColumns: number): WebCalendar;
/**
* Sets which columns are affected by the event color settings.
*
* This method configures the columns to which the event color will be applied in the calendar.
* The input should be a number representing a bitfield of column flags. The method ensures
* that the provided flag is valid and sets it for event color application.
*
* @param {number} eventColorColumns The column flags to apply event color to.
* @throws {Error} If the input is not a number or if it does not represent valid column flags.
* @returns {WebCalendar} The current instance of the class for chaining.
*/
eventColorColumns(eventColorColumns: number): WebCalendar;
/**
* Controls whether or not month headers are displayed in the table.
*
* This method controls whether or not month headers are displayed
* in the calendar table.
* The default is true, meaning that month headers should be included.
*
* @param {boolean} [monthHeader=true] Whether or not to include month headers in the table.
*
* @throws {Error} If the input is not a boolean.
* @returns {WebCalendar} The current instance of the class.
*/
monthHeader(monthHeader?: boolean): WebCalendar;
/**
* Sets how the liturgical grade is displayed in the table.
*
* The liturgical grade can be displayed in full or abbreviated form.
* The following options are supported:
* - GradeDisplay.FULL: the grade is displayed with its full rank
* - GradeDisplay.ABBREVIATED: the grade is displayed with an abbreviated rank
*
* The default is GradeDisplay.FULL.
*
* @param {GradeDisplay} gradeDisplay The grade display.
* @throws {Error} If the input is not a valid GradeDisplay.
* @returns {WebCalendar} The current instance of the class.
*/
gradeDisplay(gradeDisplay: GradeDisplay): WebCalendar;
/**
* Sets the Latin interface for the WebCalendar instance.
*
* The Latin interface determines which set of month and weekday names to use
* for the calendar. The following options are supported:
* - LatinInterface.ECCLESIASTICAL: month and weekday names are based on the ecclesiastical calendar
* - LatinInterface.CIVIL: month and weekday names are based on the civil calendar
*
* The default is LatinInterface.ECCLESIASTICAL.
*
* @param {LatinInterface} latinInterface The Latin interface to use.
* @throws {Error} If the input is not a valid LatinInterface.
* @returns {WebCalendar} The current instance of the class.
*/
latinInterface(latinInterface: LatinInterface): WebCalendar;
/**
* Sets the locale for the WebCalendar instance.
*
* The locale determines the language and regional settings for date formatting
* within the calendar. It configures month and date formatters based on the
* specified locale. If the date format is set to DAY_ONLY, it will format the
* date to show the day of the month and the full weekday name; otherwise, it
* uses the configured date style.
*
* @param {string} locale - The locale identifier to set, following BCP 47 language tag format.
* @throws {Error} If the provided locale is not a string or an invalid locale identifier.
* @returns {WebCalendar} The current instance of the class for method chaining.
*/
locale(locale: string): WebCalendar;
/**
* @description Builds the HTML table from the JSON data for the Liturgical Calendar.
* @async
* @returns {WebCalendar} The current instance of the WebCalendar class
*/
buildTable(): WebCalendar;
/**
* Appends the WebCalendar to a given element. If the element does not yet exist in the DOM, the WebCalendar will be appended when the element is inserted.
* @param {string|HTMLElement} elementSelector - DOM element, or Element selector for the DOM element, to append the WebCalendar to
*/
appendTo(elementSelector?: string | HTMLElement): void;
/**
* @deprecated Use appendTo() instead. This method will be removed in a future version.
* @param {string|HTMLElement} elementSelector - DOM element, or Element selector for the DOM element
*/
attachTo(elementSelector?: string | HTMLElement): void;
/**
* Subscribes the WebCalendar instance to the `calendarFetched` event emitted by the ApiClient.
*
* Upon receiving the event, it processes the liturgical calendar data and updates the calendar display.
* The method will validate that the `apiClient` is an instance of ApiClient and listen to
* the `calendarFetched` event on the client's event bus. When the event is triggered, it checks
* the integrity of the received data, ensuring it contains the necessary properties and is of the correct type.
* It then converts event dates from UNIX timestamps to Date objects, updates the internal calendar data,
* and rebuilds the calendar table. If the WebCalendar is attached to a DOM element, the new calendar table
* replaces the current content of the attached element.
*
* @param {ApiClient} apiClient - The API client to listen to for calendar data events.
* @throws {Error} If the provided `apiClient` is not an instance of ApiClient or if the received
* data is invalid or malformed.
* @return {WebCalendar} - Returns the instance of WebCalendar for method chaining.
*/
listenTo(apiClient: ApiClient): WebCalendar;
/**
* The locale used by the WebCalendar instance.
* @type {string}
* @readonly
*/
readonly get _locale(): string;
/**
* The number of days on which liturgical events take place in the current WebCalendar.
* This value is only available after {@link WebCalendar.buildTable()} has been called.
* @type {number}
*/
get _daysCreated(): number;
/**
* Get the number of days on which liturgical events take place in the current WebCalendar.
* @returns {number} The number of days on which liturgical events take place in the current WebCalendar. This value is only available after {@link WebCalendar.buildTable()} has been called.
*/
daysCreated(): number;
#private;
}
import { DateFormat } from '../Enums.js';
import { Grouping } from '../Enums.js';
import { ColumnOrder } from '../Enums.js';
import { ColorAs } from '../Enums.js';
import { GradeDisplay } from '../Enums.js';
import { LatinInterface } from '../Enums.js';
import ApiClient from '../ApiClient/ApiClient.js';
//# sourceMappingURL=WebCalendar.d.ts.map