@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
298 lines • 13.5 kB
TypeScript
export default class Input {
/** @type {string | null} */
static "__#1@#globalInputClass": string | null;
/** @type {string | null} */
static "__#1@#globalLabelClass": string | null;
/** @type {string | null} */
static "__#1@#globalWrapper": string | null;
/** @type {string | null} */
static "__#1@#globalWrapperClass": string | null;
/**
* Sets a global class attribute for all input elements created by this class.
*
* Validates the input class name(s) to ensure they are strings and conform to
* CSS class naming conventions. The input class name is sanitized and assigned
* to the global input class.
*
* @param {string} [className=''] - A space-separated string of class names to be
* assigned globally.
* @throws {Error} If the className is not a string, or if any class name is invalid.
*/
static setGlobalInputClass(className?: string): void;
/**
* Sets a global class attribute for all label elements created by this class.
*
* Validates the class name(s) to ensure they are strings and conform to CSS class naming conventions.
* The input class name is sanitized and assigned to the global label class.
*
* @param {string} [className=''] - A space-separated string of class names to be assigned globally.
* @throws {Error} If the className is not a string, or if any class name is invalid.
*/
static setGlobalLabelClass(className?: string): void;
/**
* Sets a global wrapper element for all input elements created by this class.
*
* Validates the wrapper element to ensure it is a string and is one of the valid values.
* The input wrapper element is sanitized and assigned to the global wrapper element.
*
* @param {string} [wrapper] - The wrapper element, currently only 'div' and 'td' are supported.
* @throws {Error} If the wrapper is not a string, or if the wrapper is not one of the valid values.
*/
static setGlobalWrapper(wrapper?: string): void;
/**
* Sets a global class attribute for all wrapper elements created by this class.
*
* Validates the class name(s) to ensure they are strings and conform to CSS class naming conventions.
* The input class name is sanitized and assigned to the global wrapper class.
*
* @param {string} [className=''] - A space-separated string of class names to be assigned globally.
* @throws {Error} If the className is not a string, or if any class name is invalid.
*/
static setGlobalWrapperClass(className?: string): void;
/**
* @param {string} [element='select'] - The element to create as the input element.
* Valid values are: `select`, `input`.
* @param {object} [attributes={multiple: false}] - Key-value pairs of attributes to set on the element.
* When the element is `input`, the only current supported attribute is `type` with a value of `number` (which will produce an `input[type="number"]` element).
* When the element is `select`, the `multiple` attribute can be set to `true` to create a multi-select element.
* @throws {Error} If the element parameter is not a string or is not one of the valid values.
*/
constructor(element?: string, attributes?: object);
/**
* Sets the id attribute for the Input instance's DOM element.
*
* Validates the input id to ensure it is a string and conforms to
* CSS id naming conventions. If the id is valid, it is sanitized
* and assigned to the element. If the id has already been set,
* an error is thrown.
*
* @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, or if the id has already been set.
* @returns {Input} The current Input instance for chaining.
*/
id(id?: string): Input;
/**
* Sets the name attribute for the Input instance's DOM element.
*
* Validates the input name to ensure it is a non-empty string. If the name is valid,
* it is sanitized and assigned to the element. If the name is an empty string,
* or 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 {Input} The current Input instance for chaining.
*/
name(name?: string): Input;
/**
* Sets the class attribute for the Input 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 {Input} The current Input instance for chaining.
*/
class(className?: string): Input;
/**
* Sets the class or classes to apply to the label element of the Input instance.
*
* This method validates the provided class name(s) to ensure they are strings
* and conform to CSS class naming conventions. It sanitizes the class name(s)
* and assigns them to the label element. If the class name is already set and
* differs from the provided value, an error is thrown. The class name(s) can be
* space-separated.
*
* @param {string} labelClass - A space-separated string of class names to be
* assigned to the label element.
* @throws {Error} If the labelClass is not a string, or if any class name is invalid.
* @returns {Input} The current Input instance for chaining.
*/
labelClass(labelClass?: string): Input;
/**
* Sets content to be inserted after the label element.
*
* This method allows appending content after the label 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 label element.
* @throws {Error} If content is attempted to be set more than once.
* @returns {Input} The current instance for method chaining.
*/
labelAfter(contents?: string | null): Input;
/**
* Sets the type of HTML element to use as the wrapper element.
*
* If the `wrapper` argument is not provided, the wrapper element will be set to `div`.
* If the `wrapper` argument is provided but is not a string, an error will be thrown.
* If the `wrapper` argument is provided and is a string, it must be one of the following valid values:
* - 'div'
* - 'td'
*
* @param {string} [wrapper='div'] The type of HTML element to use as the wrapper element.
*
* @return {Input} The current instance for method chaining.
*
* @throws {Error} If the `wrapper` argument is not a string or is not one of the valid values.
*/
wrapper(wrapper?: string): Input;
/**
* Sets the class for the wrapper element.
*
* If a wrapper element has not been set, an error will be thrown.
* If the wrapper element has already been set with a class, an error will be thrown.
* This method accepts a string of space-separated class names.
* The class names will be validated to ensure they are valid CSS classes.
* If any of the class names are invalid, an error will be thrown.
*
* @param {string} [wrapperClass=''] - The class for the wrapper element.
* @throws {Error} If the type of wrapperClass is not a string.
* @throws {Error} If the wrapper element has not been set.
* @throws {Error} If the wrapper element has already been set with a class.
* @throws {Error} If any of the class names are invalid.
* @return {Input} - The same instance of Input.
*/
wrapperClass(wrapperClass?: string): Input;
/**
* Sets the data attributes for the input element.
*
* This method accepts an associative array where the keys are the data attribute names
* (without the 'data-' prefix) and the values are the corresponding attribute values.
* These data attributes will be used to form the 'data-*' attributes in the HTML input element.
*
* @param {object} [data={}] An associative array representing data attributes for the input element.
*
* @return {Input} Returns the current instance to allow method chaining.
*/
data(data?: object): Input;
/**
* Sets the disabled property on the input element.
*
* If set to true, the input element will be disabled and the user will not be able to interact with it.
* If set to false, the input element will be enabled and the user will be able to interact with it.
*
* If no parameter is provided, defaults to true.
*
* @param {boolean} [boolValue=true] - Whether the input element should be disabled.
* @returns {Input} The current instance for method chaining.
* @throws {Error} If the type of boolValue is not a boolean.
*/
disabled(boolValue?: boolean): Input;
/**
* Sets the default value of the input element.
*
* @param {string} [value=''] - The default value of the input element.
* @throws {Error} If the type of value is not a string.
* @return {Input} - The same instance of Input.
*/
defaultValue(value?: string): Input;
/**
* Gets or sets the current value of the input element.
*
* When called without arguments, returns the current value.
* When called with a value argument, sets the value and returns the instance for chaining.
*
* Note: This differs from `defaultValue()` which sets the initial/default value.
* This method gets or sets the current live value of the input.
*
* @param {string} [val] - The value to set. If omitted, the method acts as a getter.
* @returns {string|Input} The current value when used as getter, or the instance when used as setter.
* @throws {Error} If the provided value is not a string.
*/
value(val?: string): string | Input;
/**
* Returns an array of option values for select elements.
*
* This method is only applicable to select elements. For input elements,
* it returns an empty array.
*
* @returns {string[]} An array of option values, or empty array if not a select element.
*/
options(): string[];
/**
* Appends the input element to the element matched by the provided element selector.
*
* If a wrapper element has been set, the input element is appended to the wrapper element.
* If a label element has been set, the label element is inserted before the input element.
* If an after element has been set, the after element is inserted after the input element.
*
* @param {string|HTMLElement} [elementSelector=''] - Element selector for the element to append the input element to.
* @throws {Error} If the type of elementSelector is not a string.
* @throws {Error} If the element selector is invalid.
* @throws {Error} If the element selector does not match any element.
* @return {Input} - The same instance of Input.
*/
appendTo(elementSelector?: string | HTMLElement): Input;
/**
* Retrieves the underlying DOM element of the input instance.
*
* @returns {HTMLElement} The DOM element associated with the input instance.
* @readonly
*/
readonly get _domElement(): HTMLElement;
/**
* Whether or not the class has been set.
*
* @returns {boolean}
* @readonly
*/
readonly get _classSet(): boolean;
/**
* The label element.
*
* @returns {HTMLLabelElement}
* @readonly
*/
readonly get _labelElement(): HTMLLabelElement;
/**
* Whether or not the label class has been set.
*
* @returns {boolean}
* @readonly
*/
readonly get _labelClassSet(): boolean;
/**
* The element to insert after the label element.
*
* @returns {DocumentFragment|null}
* @readonly
*/
readonly get _labelAfter(): DocumentFragment | null;
/**
* The wrapper element.
*
* @returns {HTMLElement|null}
* @readonly
*/
readonly get _wrapperElement(): HTMLElement | null;
/**
* Whether or not the wrapper class has been set.
*
* @returns {boolean}
* @readonly
*/
readonly get _wrapperClassSet(): boolean;
/**
* The default value of the input element, set with the defaultValue() method.
*
* @returns {string}
* @readonly
*/
readonly get _defaultValue(): string;
/**
* Whether a wrapper element has been set.
*
* @returns {boolean}
* @readonly
*/
readonly get _hasWrapper(): boolean;
#private;
}
//# sourceMappingURL=Input.d.ts.map