tiny-essentials 1.24.0 → 1.24.1

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

@@ -0,0 +1,65 @@
+export default TinyHtmlDatalist;
+/**
+ * TinyHtmlDatalist is a helper class for creating and managing <datalist> elements.
+ * A <datalist> provides predefined options for <input> elements via the `list` attribute.
+ *
+ * Only <option> children are valid inside <datalist>.
+ *
+ * @example
+ * const datalist = new TinyHtmlDatalist({ id: 'browsers' });
+ * datalist.addOption({ value: 'Firefox' });
+ * datalist.addOption({ value: 'Chrome' });
+ * document.body.appendChild(datalist.el);
+ *
+ * <input list="browsers">
+ *
+ * @extends TinyHtmlTemplate<HTMLDataListElement>
+ */
+declare class TinyHtmlDatalist extends TinyHtmlTemplate<HTMLDataListElement> {
+    /**
+     * Creates a new TinyHtmlDatalist instance.
+     * @param {Object} config - Configuration object.
+     * @param {string} [config.id] - The unique identifier for the datalist (to be linked with <input list="...">).
+     * @param {string|string[]|Set<string>} [config.tags=[]] - Initial CSS classes.
+     * @param {string} [config.mainClass=""] - Main CSS class.
+     * @param {Array<{value: string, label?: string}>} [config.options=[]] - Initial <option> elements.
+     */
+    constructor({ id, tags, mainClass, options }?: {
+        id?: string | undefined;
+        tags?: string | string[] | Set<string> | undefined;
+        mainClass?: string | undefined;
+        options?: {
+            value: string;
+            label?: string;
+        }[] | undefined;
+    });
+    /** @param {Array<{value: string, label?: string}>} options */
+    set options(options: Array<{
+        value: string;
+        label?: string;
+    }>);
+    /** @returns {Array<{value: string, label: string|null}>} */
+    get options(): Array<{
+        value: string;
+        label: string | null;
+    }>;
+    /**
+     * Adds a new <option> to the datalist.
+     * @param {Object} config - Option configuration.
+     * @param {string} config.value - The value of the option (required).
+     * @param {string} [config.label] - Optional label for accessibility or display.
+     * @returns {HTMLOptionElement} The created <option> element.
+     */
+    addOption({ value, label }: {
+        value: string;
+        label?: string | undefined;
+    }): HTMLOptionElement;
+    /**
+     * Removes an option by its value.
+     * @param {string} value - The value of the option to remove.
+     * @returns {boolean} True if an option was removed, false otherwise.
+     */
+    removeOption(value: string): boolean;
+}
+import TinyHtmlTemplate from './TinyHtmlTemplate.mjs';
+//# sourceMappingURL=TinyHtmlDatalist.d.mts.map

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

@@ -0,0 +1,91 @@
+import TinyHtmlTemplate from './TinyHtmlTemplate.mjs';
+/**
+ * TinyHtmlDatalist is a helper class for creating and managing <datalist> elements.
+ * A <datalist> provides predefined options for <input> elements via the `list` attribute.
+ *
+ * Only <option> children are valid inside <datalist>.
+ *
+ * @example
+ * const datalist = new TinyHtmlDatalist({ id: 'browsers' });
+ * datalist.addOption({ value: 'Firefox' });
+ * datalist.addOption({ value: 'Chrome' });
+ * document.body.appendChild(datalist.el);
+ *
+ * <input list="browsers">
+ *
+ * @extends TinyHtmlTemplate<HTMLDataListElement>
+ */
+class TinyHtmlDatalist extends TinyHtmlTemplate {
+    /**
+     * Creates a new TinyHtmlDatalist instance.
+     * @param {Object} config - Configuration object.
+     * @param {string} [config.id] - The unique identifier for the datalist (to be linked with <input list="...">).
+     * @param {string|string[]|Set<string>} [config.tags=[]] - Initial CSS classes.
+     * @param {string} [config.mainClass=""] - Main CSS class.
+     * @param {Array<{value: string, label?: string}>} [config.options=[]] - Initial <option> elements.
+     */
+    constructor({ id, tags = [], mainClass = '', options = [] } = {}) {
+        super(document.createElement('datalist'), tags, mainClass);
+        if (id !== undefined)
+            this.id = id;
+        if (options !== undefined)
+            this.options = options;
+    }
+    /** @param {Array<{value: string, label?: string}>} options */
+    set options(options) {
+        if (!Array.isArray(options)) {
+            throw new TypeError('TinyHtmlDatalist: "options" must be an array.');
+        }
+        // limpa opções anteriores
+        this.el.innerHTML = '';
+        for (const opt of options) {
+            this.addOption(opt);
+        }
+    }
+    /** @returns {Array<{value: string, label: string|null}>} */
+    get options() {
+        return Array.from(this.el.children)
+            .filter((child) => child instanceof HTMLOptionElement)
+            .map((opt) => ({
+            value: opt.value,
+            label: opt.label || null,
+        }));
+    }
+    /**
+     * Adds a new <option> to the datalist.
+     * @param {Object} config - Option configuration.
+     * @param {string} config.value - The value of the option (required).
+     * @param {string} [config.label] - Optional label for accessibility or display.
+     * @returns {HTMLOptionElement} The created <option> element.
+     */
+    addOption({ value, label }) {
+        if (typeof value !== 'string') {
+            throw new TypeError('TinyHtmlDatalist.addOption: "value" must be a string.');
+        }
+        if (label !== undefined && typeof label !== 'string') {
+            throw new TypeError('TinyHtmlDatalist.addOption: "label" must be a string if provided.');
+        }
+        const option = document.createElement('option');
+        option.value = value;
+        if (label)
+            option.label = label;
+        this.el.appendChild(option);
+        return option;
+    }
+    /**
+     * Removes an option by its value.
+     * @param {string} value - The value of the option to remove.
+     * @returns {boolean} True if an option was removed, false otherwise.
+     */
+    removeOption(value) {
+        if (typeof value !== 'string')
+            throw new TypeError('TinyHtmlDatalist.removeOption: "value" must be a string.');
+        const option = Array.from(this.el.children).find((child) => child instanceof HTMLOptionElement && child.value === value);
+        if (option) {
+            option.remove();
+            return true;
+        }
+        return false;
+    }
+}
+export default TinyHtmlDatalist;

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

@@ -0,0 +1,80 @@
+'use strict';
+
+var TinyHtmlTemplate = require('./TinyHtmlTemplate.cjs');
+
+/**
+ * TinyHtmlEmbed is a helper class for creating and managing <embed> elements,
+ * typically used to embed external interactive content or media such as PDFs or plugins.
+ *
+ * Supported attributes:
+ * - `src`: The URL of the resource being embedded.
+ * - `type`: The MIME type used to select the plug-in to instantiate.
+ * - `width`: Display width in CSS pixels (absolute value, no percentages).
+ * - `height`: Display height in CSS pixels (absolute value, no percentages).
+ *
+ * @example
+ * const embed = new TinyHtmlEmbed({
+ *   src: '/docs/sample.pdf',
+ *   type: 'application/pdf',
+ *   width: 800,
+ *   height: 600,
+ * });
+ *
+ * @extends TinyHtmlTemplate<HTMLEmbedElement>
+ */
+class TinyHtmlEmbed extends TinyHtmlTemplate {
+  /**
+   * Creates a new TinyHtmlEmbed instance.
+   *
+   * @param {Object} [config={}] - Configuration object.
+   * @param {string} [config.src=""] - The resource URL to embed.
+   * @param {string} [config.type=""] - The MIME type of the resource (e.g. "application/pdf").
+   * @param {number|string} [config.width] - Width in CSS pixels. Must be an absolute value (no percentages).
+   * @param {number|string} [config.height] - Height in CSS pixels. Must be an absolute value (no percentages).
+   * @param {string|string[]|Set<string>} [config.tags=[]] - CSS classes to apply.
+   * @param {string} [config.mainClass=""] - Main CSS class.
+   *
+   * @throws {TypeError} If `src` is not a string.
+   * @throws {TypeError} If `type` is not a string.
+   * @throws {TypeError} If `width` is not a number or string.
+   * @throws {TypeError} If `height` is not a number or string.
+   */
+  constructor({ src = '', type = '', width, height, tags = [], mainClass = '' } = {}) {
+    super(document.createElement('embed'), tags, mainClass);
+
+    // src
+    if (src) this.src = src;
+    // type
+    if (type) this.type = type;
+    // width
+    if (width !== undefined) this.setWidth(width);
+    // height
+    if (height !== undefined) this.setHeight(height);
+  }
+
+  /** @param {string} src */
+  set src(src) {
+    if (typeof src !== 'string')
+      throw new TypeError(`TinyHtmlEmbed: "src" must be a string. Got: ${typeof src}`);
+    this.setAttr('src', src);
+  }
+
+  /** @returns {string|null} */
+  get src() {
+    return this.attrString('src');
+  }
+
+  /** @param {string} type */
+  set type(type) {
+    if (typeof type !== 'string')
+      throw new TypeError(`TinyHtmlEmbed: "type" must be a string. Got: ${typeof type}`);
+    this.setAttr('type', type);
+  }
+
+  /** @returns {string|null} */
+  get type() {
+    return this.attrString('type');
+  }
+}
+
+module.exports = TinyHtmlEmbed;

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

@@ -0,0 +1,57 @@
+export default TinyHtmlEmbed;
+/**
+ * TinyHtmlEmbed is a helper class for creating and managing <embed> elements,
+ * typically used to embed external interactive content or media such as PDFs or plugins.
+ *
+ * Supported attributes:
+ * - `src`: The URL of the resource being embedded.
+ * - `type`: The MIME type used to select the plug-in to instantiate.
+ * - `width`: Display width in CSS pixels (absolute value, no percentages).
+ * - `height`: Display height in CSS pixels (absolute value, no percentages).
+ *
+ * @example
+ * const embed = new TinyHtmlEmbed({
+ *   src: '/docs/sample.pdf',
+ *   type: 'application/pdf',
+ *   width: 800,
+ *   height: 600,
+ * });
+ *
+ * @extends TinyHtmlTemplate<HTMLEmbedElement>
+ */
+declare class TinyHtmlEmbed extends TinyHtmlTemplate<HTMLEmbedElement> {
+    /**
+     * Creates a new TinyHtmlEmbed instance.
+     *
+     * @param {Object} [config={}] - Configuration object.
+     * @param {string} [config.src=""] - The resource URL to embed.
+     * @param {string} [config.type=""] - The MIME type of the resource (e.g. "application/pdf").
+     * @param {number|string} [config.width] - Width in CSS pixels. Must be an absolute value (no percentages).
+     * @param {number|string} [config.height] - Height in CSS pixels. Must be an absolute value (no percentages).
+     * @param {string|string[]|Set<string>} [config.tags=[]] - CSS classes to apply.
+     * @param {string} [config.mainClass=""] - Main CSS class.
+     *
+     * @throws {TypeError} If `src` is not a string.
+     * @throws {TypeError} If `type` is not a string.
+     * @throws {TypeError} If `width` is not a number or string.
+     * @throws {TypeError} If `height` is not a number or string.
+     */
+    constructor({ src, type, width, height, tags, mainClass }?: {
+        src?: string | undefined;
+        type?: string | undefined;
+        width?: string | number | undefined;
+        height?: string | number | undefined;
+        tags?: string | string[] | Set<string> | undefined;
+        mainClass?: string | undefined;
+    });
+    /** @param {string} src */
+    set src(src: string);
+    /** @returns {string|null} */
+    get src(): string | null;
+    /** @param {string} type */
+    set type(type: string);
+    /** @returns {string|null} */
+    get type(): string | null;
+}
+import TinyHtmlTemplate from './TinyHtmlTemplate.mjs';
+//# sourceMappingURL=TinyHtmlEmbed.d.mts.map

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

@@ -0,0 +1,75 @@
+import TinyHtmlTemplate from './TinyHtmlTemplate.mjs';
+/**
+ * TinyHtmlEmbed is a helper class for creating and managing <embed> elements,
+ * typically used to embed external interactive content or media such as PDFs or plugins.
+ *
+ * Supported attributes:
+ * - `src`: The URL of the resource being embedded.
+ * - `type`: The MIME type used to select the plug-in to instantiate.
+ * - `width`: Display width in CSS pixels (absolute value, no percentages).
+ * - `height`: Display height in CSS pixels (absolute value, no percentages).
+ *
+ * @example
+ * const embed = new TinyHtmlEmbed({
+ *   src: '/docs/sample.pdf',
+ *   type: 'application/pdf',
+ *   width: 800,
+ *   height: 600,
+ * });
+ *
+ * @extends TinyHtmlTemplate<HTMLEmbedElement>
+ */
+class TinyHtmlEmbed extends TinyHtmlTemplate {
+    /**
+     * Creates a new TinyHtmlEmbed instance.
+     *
+     * @param {Object} [config={}] - Configuration object.
+     * @param {string} [config.src=""] - The resource URL to embed.
+     * @param {string} [config.type=""] - The MIME type of the resource (e.g. "application/pdf").
+     * @param {number|string} [config.width] - Width in CSS pixels. Must be an absolute value (no percentages).
+     * @param {number|string} [config.height] - Height in CSS pixels. Must be an absolute value (no percentages).
+     * @param {string|string[]|Set<string>} [config.tags=[]] - CSS classes to apply.
+     * @param {string} [config.mainClass=""] - Main CSS class.
+     *
+     * @throws {TypeError} If `src` is not a string.
+     * @throws {TypeError} If `type` is not a string.
+     * @throws {TypeError} If `width` is not a number or string.
+     * @throws {TypeError} If `height` is not a number or string.
+     */
+    constructor({ src = '', type = '', width, height, tags = [], mainClass = '' } = {}) {
+        super(document.createElement('embed'), tags, mainClass);
+        // src
+        if (src)
+            this.src = src;
+        // type
+        if (type)
+            this.type = type;
+        // width
+        if (width !== undefined)
+            this.setWidth(width);
+        // height
+        if (height !== undefined)
+            this.setHeight(height);
+    }
+    /** @param {string} src */
+    set src(src) {
+        if (typeof src !== 'string')
+            throw new TypeError(`TinyHtmlEmbed: "src" must be a string. Got: ${typeof src}`);
+        this.setAttr('src', src);
+    }
+    /** @returns {string|null} */
+    get src() {
+        return this.attrString('src');
+    }
+    /** @param {string} type */
+    set type(type) {
+        if (typeof type !== 'string')
+            throw new TypeError(`TinyHtmlEmbed: "type" must be a string. Got: ${typeof type}`);
+        this.setAttr('type', type);
+    }
+    /** @returns {string|null} */
+    get type() {
+        return this.attrString('type');
+    }
+}
+export default TinyHtmlEmbed;

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

@@ -0,0 +1,244 @@
+'use strict';
+
+var TinyHtmlTemplate = require('./TinyHtmlTemplate.cjs');
+
+/**
+ * TinyHtmlForm is a helper for creating and managing <form> elements
+ * with full attribute support and validation.
+ *
+ * @example
+ * const form = new TinyHtmlForm({
+ *   action: '/submit',
+ *   method: 'post',
+ *   enctype: 'multipart/form-data',
+ *   autocomplete: 'on',
+ *   novalidate: true,
+ *   target: '_blank',
+ *   tags: ['form', 'signup'],
+ *   mainClass: 'primary-form'
+ * });
+ *
+ * @extends TinyHtmlTemplate<HTMLFormElement>
+ */
+class TinyHtmlForm extends TinyHtmlTemplate {
+  /**
+   * Creates a new TinyHtmlForm instance.
+   *
+   * The constructor accepts a single `config` object with named options to
+   * configure the created `<form>` element. Validation is performed for each
+   * option and a `TypeError` is thrown when an invalid type or value is
+   * provided. Deprecated attributes are accepted but will emit a console.warn.
+   *
+   * @param {Object} [config={}] - Configuration object.
+   * @param {string} [config.action=""] - The URL that processes the form submission.
+   *   If omitted the form will submit to the current document URL.
+   * @param {'get'|'post'|'dialog'} [config.method='get'] - The HTTP method to submit the form with.
+   *   - `get` (default): form data appended to the action URL.
+   *   - `post`: form data sent in request body; `enctype` is relevant.
+   *   - `dialog`: when the form is inside a `<dialog>`, closes the dialog and fires a submit event without sending data.
+   * @param {'application/x-www-form-urlencoded'|'multipart/form-data'|'text/plain'} [config.enctype]
+   *   The encoding type for form submission (only used when method is `post`).
+   * @param {string} [config.acceptCharset] - The character encoding accepted by the server (e.g. "UTF-8").
+   *   The specification recommends "UTF-8".
+   * @param {'none'|'off'|'sentences'|'on'|'words'|'characters'} [config.autocapitalize]
+   *   Controls automatic capitalization for text inputs inside the form.
+   * @param {'on'|'off'} [config.autocomplete] - Hint to the browser whether autofill is allowed for controls in the form.
+   * @param {string} [config.name] - The form name. Must be a non-empty string when provided.
+   * @param {string} [config.rel] - Space-separated relationship tokens describing the form's link semantics.
+   * @param {boolean} [config.novalidate=false] - When true, disables built-in form validation on submit.
+   * @param {string} [config.target] - Target browsing context for the response.
+   *   Can be one of `_self`, `_blank`, `_parent`, `_top`, `_unfencedTop` or a valid browsing context name
+   *   (pattern: starts with a letter/underscore, then alphanumeric/`-`/`_`).
+   * @param {string|string[]|Set<string>} [config.tags=[]] - Initial CSS classes to apply to the form element.
+   * @param {string} [config.mainClass=''] - Main CSS class to append to the element.
+   *
+   * @throws {TypeError} If `action` is provided and is not a string.
+   * @throws {TypeError} If `method` is not one of 'get', 'post' or 'dialog'.
+   * @throws {TypeError} If `enctype` is provided and is not one of the allowed encodings.
+   * @throws {TypeError} If `acceptCharset` is provided and is not a string.
+   * @throws {TypeError} If `autocapitalize` is provided and is not one of the allowed tokens.
+   * @throws {TypeError} If `autocomplete` is provided and is not 'on' or 'off'.
+   * @throws {TypeError} If `name` is provided and is not a non-empty string.
+   * @throws {TypeError} If `rel` is provided and is not a string.
+   * @throws {TypeError} If `novalidate` is not a boolean.
+   * @throws {TypeError} If `target` is not a valid target keyword or a valid browsing context name.
+   */
+  constructor({
+    action = '',
+    method = 'get',
+    enctype,
+    acceptCharset,
+    autocapitalize,
+    autocomplete,
+    name,
+    rel,
+    novalidate = false,
+    target,
+    tags = [],
+    mainClass = '',
+  } = {}) {
+    super(document.createElement('form'), tags, mainClass);
+
+    // action
+    this.action = action;
+    // method
+    this.method = method;
+    // enctype
+    if (enctype !== undefined) this.enctype = enctype;
+    // accept-charset
+    if (acceptCharset !== undefined) this.acceptCharset = acceptCharset;
+    // autocapitalize
+    if (autocapitalize !== undefined) this.autocapitalize = autocapitalize;
+    // autocomplete
+    if (autocomplete !== undefined) this.autocomplete = autocomplete;
+    // name
+    if (name !== undefined) this.name = name;
+    // rel
+    if (rel !== undefined) this.rel = rel;
+    // novalidate
+    this.novalidate = novalidate;
+    // target
+    if (target !== undefined) this.target = target;
+  }
+
+  /** @param {string} action */
+  set action(action) {
+    if (typeof action !== 'string') throw new TypeError('TinyForm: "action" must be a string.');
+    if (action) this.setAttr('action', action);
+  }
+  /** @returns {string|null} */
+  get action() {
+    return this.attrString('action');
+  }
+
+  /** @param {'get'|'post'|'dialog'} method */
+  set method(method) {
+    if (typeof method !== 'string') throw new TypeError('TinyForm: "method" must be a string.');
+    const valid = ['get', 'post', 'dialog'];
+    const norm = method.toLowerCase();
+    if (!valid.includes(norm))
+      throw new TypeError(`TinyForm: "method" must be one of ${valid.join(', ')}.`);
+    this.setAttr('method', norm);
+  }
+  /** @returns {string|null} */
+  get method() {
+    return this.attrString('method');
+  }
+
+  /** @param {'application/x-www-form-urlencoded'|'multipart/form-data'|'text/plain'} enctype */
+  set enctype(enctype) {
+    const valid = ['application/x-www-form-urlencoded', 'multipart/form-data', 'text/plain'];
+    if (!valid.includes(enctype))
+      throw new TypeError(`TinyForm: "enctype" must be one of ${valid.join(', ')}.`);
+    this.setAttr('enctype', enctype);
+  }
+  /** @returns {string|null} */
+  get enctype() {
+    return this.attrString('enctype');
+  }
+
+  /** @param {string} charset */
+  set acceptCharset(charset) {
+    if (typeof charset !== 'string')
+      throw new TypeError('TinyForm: "acceptCharset" must be a string.');
+    if (charset.toUpperCase() !== 'UTF-8')
+      console.warn('TinyForm: Only "UTF-8" is recommended for accept-charset.');
+    this.setAttr('accept-charset', charset);
+  }
+  /** @returns {string|null} */
+  get acceptCharset() {
+    return this.attrString('accept-charset');
+  }
+
+  /** @param {'none'|'off'|'sentences'|'on'|'words'|'characters'} value */
+  set autocapitalize(value) {
+    const valid = ['none', 'off', 'sentences', 'on', 'words', 'characters'];
+    if (!valid.includes(value))
+      throw new TypeError(`TinyForm: "autocapitalize" must be one of ${valid.join(', ')}.`);
+    this.setAttr('autocapitalize', value);
+  }
+  /** @returns {string|null} */
+  get autocapitalize() {
+    return this.attrString('autocapitalize');
+  }
+
+  /** @param {'on'|'off'} value */
+  set autocomplete(value) {
+    if (!['on', 'off'].includes(value))
+      throw new TypeError('TinyForm: "autocomplete" must be "on" or "off".');
+    this.setAttr('autocomplete', value);
+  }
+  /** @returns {string|null} */
+  get autocomplete() {
+    return this.attrString('autocomplete');
+  }
+
+  /** @param {string} name */
+  set name(name) {
+    if (typeof name !== 'string') throw new TypeError('TinyForm: "name" must be a string.');
+    if (name.trim() === '') throw new TypeError('TinyForm: "name" cannot be empty.');
+    this.setAttr('name', name);
+  }
+  /** @returns {string|null} */
+  get name() {
+    return this.attrString('name');
+  }
+
+  /** @param {string} rel */
+  set rel(rel) {
+    if (typeof rel !== 'string') throw new TypeError('TinyForm: "rel" must be a string.');
+    this.setAttr('rel', rel);
+  }
+  /** @returns {string|null} */
+  get rel() {
+    return this.attrString('rel');
+  }
+
+  /** @param {boolean} novalidate */
+  set novalidate(novalidate) {
+    if (typeof novalidate !== 'boolean')
+      throw new TypeError('TinyForm: "novalidate" must be a boolean.');
+    if (novalidate) this.addProp('novalidate');
+    else this.removeProp('novalidate');
+  }
+  /** @returns {boolean} */
+  get novalidate() {
+    return this.hasProp('novalidate');
+  }
+
+  /** @param {string} target */
+  set target(target) {
+    if (typeof target !== 'string') throw new TypeError('TinyForm: "target" must be a string.');
+    const validTargets = ['_self', '_blank', '_parent', '_top', '_unfencedTop'];
+    const validName = /^[a-zA-Z_][\w-]*$/;
+    if (!validTargets.includes(target) && !validName.test(target))
+      throw new TypeError(
+        `TinyForm: "target" must be a valid context name or one of ${validTargets.join(', ')}.`,
+      );
+    this.setAttr('target', target);
+  }
+  /** @returns {string|null} */
+  get target() {
+    return this.attrString('target');
+  }
+
+  /**
+   * Programmatically submits the form.
+   * @returns {this}
+   */
+  submit() {
+    this.el.submit();
+    return this;
+  }
+
+  /**
+   * Resets the form.
+   * @returns {this}
+   */
+  reset() {
+    this.el.reset();
+    return this;
+  }
+}
+
+module.exports = TinyHtmlForm;