tiny-essentials 1.23.2 → 1.24.1

package/dist/v1/libs/TinyHtml/TinyHtmlSelect.mjs

@@ -0,0 +1,251 @@
+import TinyHtml from '../TinyHtml.mjs';
+import TinyHtmlTemplate from './TinyHtmlTemplate.mjs';
+/**
+ * TinyHtmlSelect is a helper class for managing <select> elements.
+ * It supports all standard attributes (multiple, autocomplete, autofocus, disabled, etc.)
+ * and provides helpers for managing <option> elements.
+ *
+ * @example
+ * const select = new TinyHtmlSelect({
+ *   options: [
+ *     { value: '1', label: 'One' },
+ *     { value: '2', label: 'Two', selected: true }
+ *   ],
+ *   multiple: true,
+ *   required: true,
+ *   size: 5,
+ *   name: 'numbers',
+ * });
+ *
+ * @extends TinyHtmlTemplate<HTMLSelectElement>
+ */
+class TinyHtmlSelect extends TinyHtmlTemplate {
+    /**
+     * Creates a new custom <select> element with configurable options and attributes.
+     *
+     * @param {Object} [config={}] Configuration object for the select element.
+     * @param {Array<{
+     *   value: string,
+     *   label: string | Element | TinyHtml<any>,
+     *   selected?: boolean,
+     *   allowHtml?: boolean
+     * }>} [config.options=[]]
+     *   An array of option definitions. Each option must provide a `value` and a `label`.
+     *   The `label` can be a string, a DOM element, or a TinyHtml instance.
+     *   The `selected` flag sets the option as initially selected.
+     *   If `allowHtml` is true, the label will be interpreted as HTML instead of plain text.
+     *
+     * @param {boolean} [config.multiple=false]
+     *   If true, allows selecting multiple options.
+     *
+     * @param {string} [config.autocomplete]
+     *   Provides autocomplete hints for the control.
+     *   Possible values include `"on"` or `"off"`.
+     *
+     * @param {boolean} [config.autofocus=false]
+     *   If true, the element will automatically receive focus when the page loads.
+     *
+     * @param {boolean} [config.disabled=false]
+     *   If true, disables the select element so it cannot be interacted with.
+     *
+     * @param {string} [config.form]
+     *   Associates the select element with the `id` of a form element.
+     *
+     * @param {string} [config.name]
+     *   The name of the select control, used when submitting forms.
+     *
+     * @param {boolean} [config.required=false]
+     *   If true, the control must be selected before submitting the form.
+     *
+     * @param {number} [config.size]
+     *   Defines the number of visible options in the dropdown (without scrolling).
+     *
+     * @param {string | string[] | Set<string>} [config.tags=[]]
+     *   A set of tags or CSS classes that can be used for styling or categorization.
+     *
+     * @param {string} [config.mainClass='']
+     *   A primary CSS class name to be applied to the select element.
+     */
+    constructor({ options = [], multiple = false, autocomplete, autofocus = false, disabled = false, form, name, required = false, size, tags = [], mainClass = '', } = {}) {
+        super(document.createElement('select'), tags, mainClass);
+        this.multiple = multiple;
+        if (autocomplete !== undefined)
+            this.autocomplete = autocomplete;
+        this.autofocus = autofocus;
+        this.disabled = disabled;
+        if (form !== undefined)
+            this.form = form;
+        if (name !== undefined)
+            this.name = name;
+        this.required = required;
+        if (size !== undefined)
+            this.sizeEl = size;
+        for (const opt of options) {
+            this.addOption(opt);
+        }
+    }
+    /** @param {boolean} multiple */
+    set multiple(multiple) {
+        if (typeof multiple !== 'boolean')
+            throw new TypeError('"multiple" must be a boolean.');
+        if (multiple)
+            this.addProp('multiple');
+        else
+            this.removeProp('multiple');
+    }
+    /** @returns {boolean} */
+    get multiple() {
+        return this.hasProp('multiple');
+    }
+    /** @param {string} autocomplete */
+    set autocomplete(autocomplete) {
+        if (typeof autocomplete !== 'string')
+            throw new TypeError('"autocomplete" must be a string.');
+        this.setAttr('autocomplete', autocomplete);
+    }
+    /** @returns {string|null} */
+    get autocomplete() {
+        return this.attrString('autocomplete');
+    }
+    /** @param {boolean} autofocus */
+    set autofocus(autofocus) {
+        if (typeof autofocus !== 'boolean')
+            throw new TypeError('"autofocus" must be a boolean.');
+        if (autofocus)
+            this.addProp('autofocus');
+        else
+            this.removeProp('autofocus');
+    }
+    /** @returns {boolean} */
+    get autofocus() {
+        return this.hasProp('autofocus');
+    }
+    /** @param {boolean} disabled */
+    set disabled(disabled) {
+        if (typeof disabled !== 'boolean')
+            throw new TypeError('"disabled" must be a boolean.');
+        if (disabled)
+            this.addProp('disabled');
+        else
+            this.removeProp('disabled');
+    }
+    /** @returns {boolean} */
+    get disabled() {
+        return this.hasProp('disabled');
+    }
+    /** @param {string} form */
+    set form(form) {
+        if (typeof form !== 'string')
+            throw new TypeError('"form" must be a string (form id).');
+        this.setAttr('form', form);
+    }
+    /** @returns {string|null} */
+    get form() {
+        return this.attrString('form');
+    }
+    /** @param {string} name */
+    set name(name) {
+        if (typeof name !== 'string')
+            throw new TypeError('"name" must be a string.');
+        this.setAttr('name', name);
+    }
+    /** @returns {string|null} */
+    get name() {
+        return this.attrString('name');
+    }
+    /** @param {boolean} required */
+    set required(required) {
+        if (typeof required !== 'boolean')
+            throw new TypeError('"required" must be a boolean.');
+        if (required)
+            this.addProp('required');
+        else
+            this.removeProp('required');
+    }
+    /** @returns {boolean} */
+    get required() {
+        return this.hasProp('required');
+    }
+    /** @param {number} size */
+    set sizeEl(size) {
+        if (!Number.isInteger(size) || size < 0)
+            throw new TypeError('"size" must be a non-negative integer.');
+        this.setAttr('size', size);
+    }
+    /** @returns {number|null} */
+    get sizeEl() {
+        return this.attrNumber('size');
+    }
+    /**
+     * Adds an option element.
+     * @param {{ value: string, label: string|Element|TinyHtml<any>, selected?: boolean, allowHtml?: boolean }} option
+     * @returns {this}
+     */
+    addOption({ value, label, allowHtml = false, selected = false }) {
+        if (typeof value !== 'string')
+            throw new TypeError('"value" must be a string.');
+        if (typeof selected !== 'boolean')
+            throw new TypeError('"selected" must be a boolean.');
+        const opt = new TinyHtml(document.createElement('option'));
+        opt.setAttr('value', value);
+        if (typeof label === 'string') {
+            if (!allowHtml)
+                opt.setText(label);
+            else
+                opt.setHtml(label);
+        }
+        else if (label instanceof Element || label instanceof TinyHtml) {
+            if (!allowHtml)
+                throw new Error('addOption: Passing an Element/TinyHtml requires allowHtml=true.');
+            opt.append(label);
+        }
+        else {
+            throw new TypeError('"label" must be a string, Element, or TinyHtml instance.');
+        }
+        if (selected)
+            opt.addProp('selected');
+        this.append(opt);
+        return this;
+    }
+    /** @returns {string} */
+    get value() {
+        if (this.multiple)
+            throw new Error('TinyHtmlSelect.value: Use "values" getter for multiple selects.');
+        return this.valTxt();
+    }
+    /** @param {string} val */
+    set value(val) {
+        if (this.multiple)
+            throw new Error('TinyHtmlSelect.value: Use "values" setter for multiple selects.');
+        if (typeof val !== 'string')
+            throw new TypeError('"value" must be a string.');
+        this.setValue(val);
+    }
+    /** @returns {string[]} */
+    get values() {
+        if (!this.multiple)
+            throw new Error('TinyHtmlSelect.values: Use "value" getter for single select.');
+        return Array.from(this.prop('selectedOptions')).map((o) => o.value);
+    }
+    /** @param {string[]} vals */
+    set values(vals) {
+        if (!this.multiple)
+            throw new Error('TinyHtmlSelect.values: Use "value" setter for single select.');
+        if (!Array.isArray(vals) || !vals.every((v) => typeof v === 'string'))
+            throw new TypeError('"values" must be an array of strings.');
+        this.setValue(vals);
+    }
+    /**
+     * Internal: apply selection to options.
+     * @param {string|string[]} value
+     * @returns {this}
+     */
+    setValue(value) {
+        const values = Array.isArray(value) ? value : [value];
+        for (const opt of this.prop('options')) {
+            opt.selected = values.includes(opt.value);
+        }
+        return this;
+    }
+}
+export default TinyHtmlSelect;

package/dist/v1/libs/TinyHtml/TinyHtmlStyle.cjs

@@ -0,0 +1,110 @@
+'use strict';
+
+var TinyHtmlTemplate = require('./TinyHtmlTemplate.cjs');
+
+/**
+ * TinyHtmlStyle is a lightweight helper class for managing <style> elements.
+ * It provides a simple API to configure attributes like `media`, `nonce`,
+ * `blocking`, and `title`, while extending TinyHtmlTemplate for DOM operations.
+ *
+ * @example
+ * const style = new TinyHtmlStyle({
+ *   media: 'screen and (max-width: 600px)',
+ *   blocking: 'render',
+ * });
+ * style.content = 'body { background: pink; }';
+ *
+ * @extends TinyHtmlTemplate<HTMLStyleElement>
+ */
+class TinyHtmlStyle extends TinyHtmlTemplate {
+  /**
+   * Creates a new TinyHtmlStyle instance.
+   * @param {Object} config - Configuration object.
+   * @param {string} [config.blocking] - Space-separated list of blocking tokens (currently only `"render"` is valid).
+   * @param {string} [config.media="all"] - Media query that the stylesheet applies to. Defaults to `"all"`.
+   * @param {string} [config.nonce] - Cryptographic nonce used in Content-Security-Policy for inline styles.
+   * @param {string} [config.title] - Specifies an alternate style sheet set.
+   * @param {string|string[]|Set<string>} [config.tags=[]] - Initial CSS classes.
+   * @param {string} [config.mainClass=""] - Main CSS class to apply.
+   */
+  constructor({ blocking, media = 'all', nonce, title, tags = [], mainClass = '' } = {}) {
+    super(document.createElement('style'), tags, mainClass);
+
+    if (blocking !== undefined) this.blocking = blocking;
+    if (media !== undefined) this.media = media;
+    if (nonce !== undefined) this.nonce = nonce;
+    if (title !== undefined) this.title = title;
+  }
+
+  /** @param {string} blocking */
+  set blocking(blocking) {
+    if (typeof blocking !== 'string')
+      throw new TypeError('TinyHtmlStyle: "blocking" must be a string.');
+    const validTokens = ['render'];
+    const tokens = blocking.trim().split(/\s+/).filter(Boolean);
+    for (const token of tokens) {
+      if (!validTokens.includes(token)) {
+        throw new Error(
+          `TinyHtmlStyle: invalid blocking token "${token}". Only "render" is allowed.`,
+        );
+      }
+    }
+    if (tokens.length) this.setAttr('blocking', tokens.join(' '));
+    else this.removeAttr('blocking');
+  }
+
+  /** @returns {string|null} */
+  get blocking() {
+    return this.attrString('blocking');
+  }
+
+  /** @param {string} media */
+  set media(media) {
+    if (typeof media !== 'string') throw new TypeError('TinyHtmlStyle: "media" must be a string.');
+    if (media.trim()) this.setAttr('media', media.trim());
+    else this.removeAttr('media');
+  }
+
+  /** @returns {string|null} */
+  get media() {
+    return this.attrString('media');
+  }
+
+  /** @param {string} nonce */
+  set nonce(nonce) {
+    if (typeof nonce !== 'string') throw new TypeError('TinyHtmlStyle: "nonce" must be a string.');
+    if (nonce.trim()) this.setAttr('nonce', nonce.trim());
+    else this.removeAttr('nonce');
+  }
+
+  /** @returns {string|null} */
+  get nonce() {
+    return this.attrString('nonce');
+  }
+
+  /** @param {string} title */
+  set title(title) {
+    if (typeof title !== 'string') throw new TypeError('TinyHtmlStyle: "title" must be a string.');
+    if (title.trim()) this.setAttr('title', title.trim());
+    else this.removeAttr('title');
+  }
+
+  /** @returns {string|null} */
+  get title() {
+    return this.attrString('title');
+  }
+
+  /** @param {string} cssText */
+  set content(cssText) {
+    if (typeof cssText !== 'string')
+      throw new TypeError('TinyHtmlStyle: "content" must be a string.');
+    this.el.textContent = cssText;
+  }
+
+  /** @returns {string} */
+  get content() {
+    return this.el.textContent ?? '';
+  }
+}
+
+module.exports = TinyHtmlStyle;

package/dist/v1/libs/TinyHtml/TinyHtmlStyle.d.mts

@@ -0,0 +1,57 @@
+export default TinyHtmlStyle;
+/**
+ * TinyHtmlStyle is a lightweight helper class for managing <style> elements.
+ * It provides a simple API to configure attributes like `media`, `nonce`,
+ * `blocking`, and `title`, while extending TinyHtmlTemplate for DOM operations.
+ *
+ * @example
+ * const style = new TinyHtmlStyle({
+ *   media: 'screen and (max-width: 600px)',
+ *   blocking: 'render',
+ * });
+ * style.content = 'body { background: pink; }';
+ *
+ * @extends TinyHtmlTemplate<HTMLStyleElement>
+ */
+declare class TinyHtmlStyle extends TinyHtmlTemplate<HTMLStyleElement> {
+    /**
+     * Creates a new TinyHtmlStyle instance.
+     * @param {Object} config - Configuration object.
+     * @param {string} [config.blocking] - Space-separated list of blocking tokens (currently only `"render"` is valid).
+     * @param {string} [config.media="all"] - Media query that the stylesheet applies to. Defaults to `"all"`.
+     * @param {string} [config.nonce] - Cryptographic nonce used in Content-Security-Policy for inline styles.
+     * @param {string} [config.title] - Specifies an alternate style sheet set.
+     * @param {string|string[]|Set<string>} [config.tags=[]] - Initial CSS classes.
+     * @param {string} [config.mainClass=""] - Main CSS class to apply.
+     */
+    constructor({ blocking, media, nonce, title, tags, mainClass }?: {
+        blocking?: string | undefined;
+        media?: string | undefined;
+        nonce?: string | undefined;
+        title?: string | undefined;
+        tags?: string | string[] | Set<string> | undefined;
+        mainClass?: string | undefined;
+    });
+    /** @param {string} blocking */
+    set blocking(blocking: string);
+    /** @returns {string|null} */
+    get blocking(): string | null;
+    /** @param {string} media */
+    set media(media: string);
+    /** @returns {string|null} */
+    get media(): string | null;
+    /** @param {string} nonce */
+    set nonce(nonce: string);
+    /** @returns {string|null} */
+    get nonce(): string | null;
+    /** @param {string} title */
+    set title(title: string);
+    /** @returns {string|null} */
+    get title(): string | null;
+    /** @param {string} cssText */
+    set content(cssText: string);
+    /** @returns {string} */
+    get content(): string;
+}
+import TinyHtmlTemplate from './TinyHtmlTemplate.mjs';
+//# sourceMappingURL=TinyHtmlStyle.d.mts.map

package/dist/v1/libs/TinyHtml/TinyHtmlStyle.mjs

@@ -0,0 +1,108 @@
+import TinyHtmlTemplate from './TinyHtmlTemplate.mjs';
+/**
+ * TinyHtmlStyle is a lightweight helper class for managing <style> elements.
+ * It provides a simple API to configure attributes like `media`, `nonce`,
+ * `blocking`, and `title`, while extending TinyHtmlTemplate for DOM operations.
+ *
+ * @example
+ * const style = new TinyHtmlStyle({
+ *   media: 'screen and (max-width: 600px)',
+ *   blocking: 'render',
+ * });
+ * style.content = 'body { background: pink; }';
+ *
+ * @extends TinyHtmlTemplate<HTMLStyleElement>
+ */
+class TinyHtmlStyle extends TinyHtmlTemplate {
+    /**
+     * Creates a new TinyHtmlStyle instance.
+     * @param {Object} config - Configuration object.
+     * @param {string} [config.blocking] - Space-separated list of blocking tokens (currently only `"render"` is valid).
+     * @param {string} [config.media="all"] - Media query that the stylesheet applies to. Defaults to `"all"`.
+     * @param {string} [config.nonce] - Cryptographic nonce used in Content-Security-Policy for inline styles.
+     * @param {string} [config.title] - Specifies an alternate style sheet set.
+     * @param {string|string[]|Set<string>} [config.tags=[]] - Initial CSS classes.
+     * @param {string} [config.mainClass=""] - Main CSS class to apply.
+     */
+    constructor({ blocking, media = 'all', nonce, title, tags = [], mainClass = '' } = {}) {
+        super(document.createElement('style'), tags, mainClass);
+        if (blocking !== undefined)
+            this.blocking = blocking;
+        if (media !== undefined)
+            this.media = media;
+        if (nonce !== undefined)
+            this.nonce = nonce;
+        if (title !== undefined)
+            this.title = title;
+    }
+    /** @param {string} blocking */
+    set blocking(blocking) {
+        if (typeof blocking !== 'string')
+            throw new TypeError('TinyHtmlStyle: "blocking" must be a string.');
+        const validTokens = ['render'];
+        const tokens = blocking.trim().split(/\s+/).filter(Boolean);
+        for (const token of tokens) {
+            if (!validTokens.includes(token)) {
+                throw new Error(`TinyHtmlStyle: invalid blocking token "${token}". Only "render" is allowed.`);
+            }
+        }
+        if (tokens.length)
+            this.setAttr('blocking', tokens.join(' '));
+        else
+            this.removeAttr('blocking');
+    }
+    /** @returns {string|null} */
+    get blocking() {
+        return this.attrString('blocking');
+    }
+    /** @param {string} media */
+    set media(media) {
+        if (typeof media !== 'string')
+            throw new TypeError('TinyHtmlStyle: "media" must be a string.');
+        if (media.trim())
+            this.setAttr('media', media.trim());
+        else
+            this.removeAttr('media');
+    }
+    /** @returns {string|null} */
+    get media() {
+        return this.attrString('media');
+    }
+    /** @param {string} nonce */
+    set nonce(nonce) {
+        if (typeof nonce !== 'string')
+            throw new TypeError('TinyHtmlStyle: "nonce" must be a string.');
+        if (nonce.trim())
+            this.setAttr('nonce', nonce.trim());
+        else
+            this.removeAttr('nonce');
+    }
+    /** @returns {string|null} */
+    get nonce() {
+        return this.attrString('nonce');
+    }
+    /** @param {string} title */
+    set title(title) {
+        if (typeof title !== 'string')
+            throw new TypeError('TinyHtmlStyle: "title" must be a string.');
+        if (title.trim())
+            this.setAttr('title', title.trim());
+        else
+            this.removeAttr('title');
+    }
+    /** @returns {string|null} */
+    get title() {
+        return this.attrString('title');
+    }
+    /** @param {string} cssText */
+    set content(cssText) {
+        if (typeof cssText !== 'string')
+            throw new TypeError('TinyHtmlStyle: "content" must be a string.');
+        this.el.textContent = cssText;
+    }
+    /** @returns {string} */
+    get content() {
+        return this.el.textContent ?? '';
+    }
+}
+export default TinyHtmlStyle;