tiny-essentials 1.24.0 → 1.24.1

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

@@ -0,0 +1,108 @@
+export default TinyHtmlIframe;
+/**
+ * TinyHtmlIframe is a helper class for managing <iframe> elements.
+ * It supports all standard attributes with validation and type safety.
+ *
+ * @example
+ * const iframe = new TinyHtmlIframe({
+ *   src: 'https://example.com',
+ *   width: 600,
+ *   height: 400,
+ *   loading: 'lazy',
+ *   sandbox: 'allow-scripts allow-same-origin',
+ *   referrerpolicy: 'no-referrer',
+ * });
+ *
+ * @extends TinyHtmlTemplate<HTMLIFrameElement>
+ */
+declare class TinyHtmlIframe extends TinyHtmlTemplate<HTMLIFrameElement> {
+    /**
+     * Creates a new TinyHtmlIframe instance with the specified configuration options.
+     *
+     * @param {Object} [config={}] - Configuration object for the iframe element.
+     * @param {string} [config.src] - The URL of the page to embed inside the iframe.
+     * @param {string} [config.srcdoc] - Inline HTML content to display inside the iframe (overrides `src` if provided).
+     * @param {string} [config.name] - A name for the browsing context (used as the target for links or forms).
+     * @param {string} [config.allow] - Permissions policy for the iframe (e.g., `"fullscreen; autoplay"`).
+     * @param {boolean} [config.allowFullScreen=false] - Whether the iframe is allowed to display content in fullscreen mode.
+     * @param {boolean} [config.browsingtopics] - Enables the Browsing Topics API.
+     * @param {boolean} [config.credentialless] - Enables credentialless mode for cross-origin iframes.
+     * @param {string} [config.csp] - Content Security Policy applied specifically to the iframe's content.
+     * @param {string} [config.sandbox] - A space-separated list of sandboxing flags that restrict iframe capabilities.
+     * @param {'no-referrer'|'no-referrer-when-downgrade'|'origin'|'origin-when-cross-origin'|'same-origin'|'strict-origin'|'strict-origin-when-cross-origin'|'unsafe-url'} [config.referrerpolicy] - Referrer policy to control the amount of referrer information sent.
+     * @param {number|string} [config.width] - Width of the iframe in pixels or as a CSS dimension string (e.g., `"100%"`).
+     * @param {number|string} [config.height] - Height of the iframe in pixels or as a CSS dimension string (e.g., `"500px"`).
+     * @param {string} [config.title] - Accessible title for the iframe content.
+     * @param {'lazy'|'eager'} [config.loading] - Loading strategy for the iframe. `"lazy"` defers loading until visible in the viewport.
+     * @param {string|string[]|Set<string>} [config.tags=[]] - Additional tags or identifiers for this instance.
+     * @param {string} [config.mainClass=''] - A main CSS class applied to the iframe element.
+     */
+    constructor({ src, srcdoc, name, allow, allowFullScreen, browsingtopics, credentialless, csp, sandbox, referrerpolicy, width, height, title, loading, tags, mainClass, }?: {
+        src?: string | undefined;
+        srcdoc?: string | undefined;
+        name?: string | undefined;
+        allow?: string | undefined;
+        allowFullScreen?: boolean | undefined;
+        browsingtopics?: boolean | undefined;
+        credentialless?: boolean | undefined;
+        csp?: string | undefined;
+        sandbox?: string | undefined;
+        referrerpolicy?: "origin" | "same-origin" | "no-referrer" | "no-referrer-when-downgrade" | "origin-when-cross-origin" | "strict-origin" | "strict-origin-when-cross-origin" | "unsafe-url" | undefined;
+        width?: string | number | undefined;
+        height?: string | number | undefined;
+        title?: string | undefined;
+        loading?: "eager" | "lazy" | 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} srcdoc */
+    set srcdoc(srcdoc: string);
+    /** @returns {string|null} */
+    get srcdoc(): string | null;
+    /** @param {string} name */
+    set name(name: string);
+    /** @returns {string|null} */
+    get name(): string | null;
+    /** @param {string} allow */
+    set allow(allow: string);
+    /** @returns {string|null} */
+    get allow(): string | null;
+    /** @param {boolean} allowFullScreen */
+    set allowFullScreen(allowFullScreen: boolean);
+    /** @returns {boolean} */
+    get allowFullScreen(): boolean;
+    /** @param {boolean} browsingtopics */
+    set browsingtopics(browsingtopics: boolean);
+    /** @returns {boolean} */
+    get browsingtopics(): boolean;
+    /** @param {boolean} credentialless */
+    set credentialless(credentialless: boolean);
+    /** @returns {boolean} */
+    get credentialless(): boolean;
+    /** @param {string} csp */
+    set csp(csp: string);
+    /** @returns {string|null} */
+    get csp(): string | null;
+    /** @param {string} sandbox */
+    set sandbox(sandbox: string);
+    /** @returns {string|null} */
+    get sandbox(): string | null;
+    /** @param {string} referrerpolicy */
+    set referrerpolicy(referrerpolicy: string);
+    /** @returns {string|null} */
+    get referrerpolicy(): string | null;
+    /** @param {string} title */
+    set title(title: string);
+    /** @returns {string|null} */
+    get title(): string | null;
+    /** @param {'lazy'|'eager'} loading */
+    set loading(loading: "lazy" | "eager");
+    /** @returns {string|null} */
+    get loading(): string | null;
+}
+import TinyHtmlTemplate from './TinyHtmlTemplate.mjs';
+//# sourceMappingURL=TinyHtmlIframe.d.mts.map

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

@@ -0,0 +1,212 @@
+import TinyHtmlTemplate from './TinyHtmlTemplate.mjs';
+/**
+ * TinyHtmlIframe is a helper class for managing <iframe> elements.
+ * It supports all standard attributes with validation and type safety.
+ *
+ * @example
+ * const iframe = new TinyHtmlIframe({
+ *   src: 'https://example.com',
+ *   width: 600,
+ *   height: 400,
+ *   loading: 'lazy',
+ *   sandbox: 'allow-scripts allow-same-origin',
+ *   referrerpolicy: 'no-referrer',
+ * });
+ *
+ * @extends TinyHtmlTemplate<HTMLIFrameElement>
+ */
+class TinyHtmlIframe extends TinyHtmlTemplate {
+    /**
+     * Creates a new TinyHtmlIframe instance with the specified configuration options.
+     *
+     * @param {Object} [config={}] - Configuration object for the iframe element.
+     * @param {string} [config.src] - The URL of the page to embed inside the iframe.
+     * @param {string} [config.srcdoc] - Inline HTML content to display inside the iframe (overrides `src` if provided).
+     * @param {string} [config.name] - A name for the browsing context (used as the target for links or forms).
+     * @param {string} [config.allow] - Permissions policy for the iframe (e.g., `"fullscreen; autoplay"`).
+     * @param {boolean} [config.allowFullScreen=false] - Whether the iframe is allowed to display content in fullscreen mode.
+     * @param {boolean} [config.browsingtopics] - Enables the Browsing Topics API.
+     * @param {boolean} [config.credentialless] - Enables credentialless mode for cross-origin iframes.
+     * @param {string} [config.csp] - Content Security Policy applied specifically to the iframe's content.
+     * @param {string} [config.sandbox] - A space-separated list of sandboxing flags that restrict iframe capabilities.
+     * @param {'no-referrer'|'no-referrer-when-downgrade'|'origin'|'origin-when-cross-origin'|'same-origin'|'strict-origin'|'strict-origin-when-cross-origin'|'unsafe-url'} [config.referrerpolicy] - Referrer policy to control the amount of referrer information sent.
+     * @param {number|string} [config.width] - Width of the iframe in pixels or as a CSS dimension string (e.g., `"100%"`).
+     * @param {number|string} [config.height] - Height of the iframe in pixels or as a CSS dimension string (e.g., `"500px"`).
+     * @param {string} [config.title] - Accessible title for the iframe content.
+     * @param {'lazy'|'eager'} [config.loading] - Loading strategy for the iframe. `"lazy"` defers loading until visible in the viewport.
+     * @param {string|string[]|Set<string>} [config.tags=[]] - Additional tags or identifiers for this instance.
+     * @param {string} [config.mainClass=''] - A main CSS class applied to the iframe element.
+     */
+    constructor({ src, srcdoc, name, allow, allowFullScreen = false, browsingtopics, credentialless, csp, sandbox, referrerpolicy, width, height, title, loading, tags = [], mainClass = '', } = {}) {
+        super(document.createElement('iframe'), tags, mainClass);
+        if (src !== undefined)
+            this.src = src;
+        if (srcdoc !== undefined)
+            this.srcdoc = srcdoc;
+        if (name !== undefined)
+            this.name = name;
+        if (allow !== undefined)
+            this.allow = allow;
+        this.allowFullScreen = allowFullScreen;
+        if (browsingtopics !== undefined)
+            this.browsingtopics = browsingtopics;
+        if (credentialless !== undefined)
+            this.credentialless = credentialless;
+        if (csp !== undefined)
+            this.csp = csp;
+        if (sandbox !== undefined)
+            this.sandbox = sandbox;
+        if (referrerpolicy !== undefined)
+            this.referrerpolicy = referrerpolicy;
+        if (width !== undefined)
+            this.setWidth(width);
+        if (height !== undefined)
+            this.setHeight(height);
+        if (title !== undefined)
+            this.title = title;
+        if (loading !== undefined)
+            this.loading = loading;
+    }
+    // --- attributes ---
+    /** @param {string} src */
+    set src(src) {
+        if (typeof src !== 'string')
+            throw new TypeError('TinyIframe: "src" must be a string.');
+        this.setAttr('src', src);
+    }
+    /** @returns {string|null} */
+    get src() {
+        return this.attrString('src');
+    }
+    /** @param {string} srcdoc */
+    set srcdoc(srcdoc) {
+        if (typeof srcdoc !== 'string')
+            throw new TypeError('TinyIframe: "srcdoc" must be a string.');
+        this.setAttr('srcdoc', srcdoc);
+    }
+    /** @returns {string|null} */
+    get srcdoc() {
+        return this.attrString('srcdoc');
+    }
+    /** @param {string} name */
+    set name(name) {
+        if (typeof name !== 'string')
+            throw new TypeError('TinyIframe: "name" must be a string.');
+        this.setAttr('name', name);
+    }
+    /** @returns {string|null} */
+    get name() {
+        return this.attrString('name');
+    }
+    /** @param {string} allow */
+    set allow(allow) {
+        if (typeof allow !== 'string')
+            throw new TypeError('TinyIframe: "allow" must be a string.');
+        this.setAttr('allow', allow);
+    }
+    /** @returns {string|null} */
+    get allow() {
+        return this.attrString('allow');
+    }
+    /** @param {boolean} allowFullScreen */
+    set allowFullScreen(allowFullScreen) {
+        if (typeof allowFullScreen !== 'boolean')
+            throw new TypeError('TinyIframe: "allowFullScreen" must be a boolean.');
+        if (allowFullScreen)
+            this.addProp('allowfullscreen');
+        else
+            this.removeProp('allowfullscreen');
+    }
+    /** @returns {boolean} */
+    get allowFullScreen() {
+        return this.hasProp('allowfullscreen');
+    }
+    /** @param {boolean} browsingtopics */
+    set browsingtopics(browsingtopics) {
+        if (typeof browsingtopics !== 'boolean')
+            throw new TypeError('TinyIframe: "browsingtopics" must be a boolean.');
+        if (browsingtopics)
+            this.addProp('browsingtopics');
+        else
+            this.removeProp('browsingtopics');
+    }
+    /** @returns {boolean} */
+    get browsingtopics() {
+        return this.hasProp('browsingtopics');
+    }
+    /** @param {boolean} credentialless */
+    set credentialless(credentialless) {
+        if (typeof credentialless !== 'boolean')
+            throw new TypeError('TinyIframe: "credentialless" must be a boolean.');
+        if (credentialless)
+            this.addProp('credentialless');
+        else
+            this.removeProp('credentialless');
+    }
+    /** @returns {boolean} */
+    get credentialless() {
+        return this.hasProp('credentialless');
+    }
+    /** @param {string} csp */
+    set csp(csp) {
+        if (typeof csp !== 'string')
+            throw new TypeError('TinyIframe: "csp" must be a string.');
+        this.setAttr('csp', csp);
+    }
+    /** @returns {string|null} */
+    get csp() {
+        return this.attrString('csp');
+    }
+    /** @param {string} sandbox */
+    set sandbox(sandbox) {
+        if (typeof sandbox !== 'string')
+            throw new TypeError('TinyIframe: "sandbox" must be a string (space-separated tokens).');
+        this.setAttr('sandbox', sandbox);
+    }
+    /** @returns {string|null} */
+    get sandbox() {
+        return this.attrString('sandbox');
+    }
+    /** @param {string} referrerpolicy */
+    set referrerpolicy(referrerpolicy) {
+        const valid = [
+            'no-referrer',
+            'no-referrer-when-downgrade',
+            'origin',
+            'origin-when-cross-origin',
+            'same-origin',
+            'strict-origin',
+            'strict-origin-when-cross-origin',
+            'unsafe-url',
+        ];
+        if (!valid.includes(referrerpolicy))
+            throw new TypeError(`TinyIframe: "referrerpolicy" must be one of: ${valid.join(', ')}.`);
+        this.setAttr('referrerpolicy', referrerpolicy);
+    }
+    /** @returns {string|null} */
+    get referrerpolicy() {
+        return this.attrString('referrerpolicy');
+    }
+    /** @param {string} title */
+    set title(title) {
+        if (typeof title !== 'string')
+            throw new TypeError('TinyIframe: "title" must be a string.');
+        this.setAttr('title', title);
+    }
+    /** @returns {string|null} */
+    get title() {
+        return this.attrString('title');
+    }
+    /** @param {'lazy'|'eager'} loading */
+    set loading(loading) {
+        const valid = ['lazy', 'eager'];
+        if (!valid.includes(loading))
+            throw new TypeError(`TinyIframe: "loading" must be one of: ${valid.join(', ')}.`);
+        this.setAttr('loading', loading);
+    }
+    /** @returns {string|null} */
+    get loading() {
+        return this.attrString('loading');
+    }
+}
+export default TinyHtmlIframe;

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

@@ -0,0 +1,286 @@
+'use strict';
+
+var TinyHtmlTemplate = require('./TinyHtmlTemplate.cjs');
+
+/**
+ * {boolean} [config.fetchMode=TinyHtmlImage.#defaultFetchMode] - Whether to enable or disable fetch mode. Must be a boolean.
+ */
+
+/**
+ * TinyImage is a helper class for managing <img> elements.
+ * It supports modern attributes like srcset, sizes, decoding, fetchpriority,
+ * as well as width, height, alt, crossorigin, loading, and more.
+ *
+ * @example
+ * const img = new TinyHtmlImage({
+ *   src: '/logo.png',
+ *   alt: 'Logo',
+ *   width: 200,
+ *   height: 100,
+ *   loading: 'lazy',
+ *   decoding: 'async',
+ * });
+ *
+ * @extends TinyHtmlTemplate<HTMLImageElement>
+ */
+class TinyHtmlImage extends TinyHtmlTemplate {
+  /** @type {boolean} */
+  // static #defaultFetchMode = false;
+
+  /** @returns {boolean} */
+  // static get defaultFetchMode() {
+  //   return TinyHtmlImage.#defaultFetchMode;
+  // }
+
+  /** @param {boolean} value */
+  // static set defaultFetchMode(value) {
+  //   if (typeof value !== 'boolean')
+  //     throw new TypeError('Expected a boolean value for defaultFetchMode');
+  //   TinyHtmlImage.#defaultFetchMode = value;
+  // }
+
+  /** @type {boolean} */
+  // #fetchMode;
+
+  /** @returns {boolean} */
+  // get fetchMode() {
+  //   return this.#fetchMode;
+  // }
+
+  /**
+   * Creates a new TinyHtmlImage instance wrapping an <img> element.
+   * This class simplifies working with images by providing a structured API
+   * for common attributes and configuration options.
+   *
+   * @param {Object} config - Image configuration object.
+   * @param {string} config.src - Image source URL (**required**).
+   * @param {string} [config.alt=""] - Alternate text for the image. Defaults to an empty string.
+   * @param {number} [config.width] - Width of the image in pixels.
+   * @param {number} [config.height] - Height of the image in pixels.
+   * @param {string|string[]|Set<string>} [config.tags=[]] - Initial CSS classes to apply.
+   * @param {string} [config.mainClass=""] - Main CSS class applied to the element.
+   * @param {string|string[]|boolean} [config.attributionsrc] - Attribution source; may be a string, array of strings, or `true/false`.
+   * @param {"anonymous"|"use-credentials"} [config.crossorigin] - Cross-origin policy for loading the image.
+   * @param {"sync"|"async"|"auto"} [config.decoding] - Decoding mode for the image.
+   * @param {string} [config.elementtiming] - Name used for performance timing attribution.
+   * @param {"high"|"low"|"auto"} [config.fetchpriority] - Fetch priority for the image resource.
+   * @param {boolean} [config.ismap=false] - Whether the image is part of a server-side image map.
+   * @param {"eager"|"lazy"} [config.loading] - Loading behavior hint (`"lazy"` defers off-screen images).
+   * @param {string} [config.referrerpolicy] - Referrer policy when fetching the image.
+   * @param {string} [config.sizes] - Sizes attribute, used with `srcset` for responsive images.
+   * @param {string} [config.srcset] - List of image sources for responsive loading.
+   * @param {string} [config.usemap] - Name of an associated image map to use.
+   */
+  constructor({
+    src,
+    alt,
+    width,
+    height,
+    tags = [],
+    mainClass = '',
+    // fetchMode = TinyHtmlImage.#defaultFetchMode,
+    attributionsrc,
+    crossorigin,
+    decoding,
+    elementtiming,
+    fetchpriority,
+    ismap = false,
+    loading,
+    referrerpolicy,
+    sizes,
+    srcset,
+    usemap,
+  }) {
+    super(document.createElement('img'), tags, mainClass);
+
+    // required
+    this.src = src;
+
+    if (alt !== undefined) this.alt = alt;
+    if (width !== undefined) this.setWidth(width);
+    if (height !== undefined) this.setHeight(height);
+    if (attributionsrc !== undefined) this.attributionsrc = attributionsrc;
+    if (crossorigin !== undefined) this.crossorigin = crossorigin;
+    if (decoding !== undefined) this.decoding = decoding;
+    if (elementtiming !== undefined) this.elementtiming = elementtiming;
+    if (fetchpriority !== undefined) this.fetchpriority = fetchpriority;
+    this.ismap = ismap;
+    if (loading !== undefined) this.loading = loading;
+    if (referrerpolicy !== undefined) this.referrerpolicy = referrerpolicy;
+    if (sizes !== undefined) this.sizes = sizes;
+    if (srcset !== undefined) this.srcset = srcset;
+    if (usemap !== undefined) this.usemap = usemap;
+
+    // if (typeof fetchMode !== 'boolean')
+    //   throw new TypeError('TinyImage: "fetchMode" must be a boolean.');
+    // this.#fetchMode = fetchMode;
+  }
+
+  // --- Attributes ---
+
+  /** @param {string} value */
+  set src(value) {
+    if (typeof value !== 'string') throw new TypeError('TinyImage: "src" must be a string.');
+    this.setAttr('src', value);
+  }
+
+  /** @returns {string|null} */
+  get src() {
+    return this.attrString('src');
+  }
+
+  /** @param {string} value */
+  set alt(value) {
+    if (typeof value !== 'string') throw new TypeError('TinyImage: "alt" must be a string.');
+    this.setAttr('alt', value);
+  }
+
+  /** @returns {string|null} */
+  get alt() {
+    return this.attrString('alt');
+  }
+
+  /** @param {string|string[]|boolean} value */
+  set attributionsrc(value) {
+    if (typeof value === 'boolean') {
+      if (value) this.addProp('attributionsrc');
+      else this.removeProp('attributionsrc');
+      return;
+    }
+    if (typeof value === 'string') {
+      this.setAttr('attributionsrc', value);
+      return;
+    }
+    if (Array.isArray(value)) {
+      this.setAttr('attributionsrc', value.join(','));
+      return;
+    }
+    throw new TypeError(
+      'TinyImage: "attributionsrc" must be a boolean, string, or array of strings.',
+    );
+  }
+
+  /** @returns {string|null} */
+  get attributionsrc() {
+    return this.attrString('attributionsrc');
+  }
+
+  /** @param {'anonymous'|'use-credentials'} value */
+  set crossorigin(value) {
+    if (!['anonymous', 'use-credentials'].includes(value))
+      throw new TypeError('TinyImage: "crossorigin" must be "anonymous" or "use-credentials".');
+    this.setAttr('crossorigin', value);
+  }
+
+  /** @returns {string|null} */
+  get crossorigin() {
+    return this.attrString('crossorigin');
+  }
+
+  /** @param {'sync'|'async'|'auto'} value */
+  set decoding(value) {
+    if (!['sync', 'async', 'auto'].includes(value))
+      throw new TypeError('TinyImage: "decoding" must be "sync", "async" or "auto".');
+    this.setAttr('decoding', value);
+  }
+
+  /** @returns {string|null} */
+  get decoding() {
+    return this.attrString('decoding');
+  }
+
+  /** @param {string} value */
+  set elementtiming(value) {
+    if (typeof value !== 'string')
+      throw new TypeError('TinyImage: "elementtiming" must be a string.');
+    this.setAttr('elementtiming', value);
+  }
+
+  /** @returns {string|null} */
+  get elementtiming() {
+    return this.attrString('elementtiming');
+  }
+
+  /** @param {'high'|'low'|'auto'} value */
+  set fetchpriority(value) {
+    if (!['high', 'low', 'auto'].includes(value))
+      throw new TypeError('TinyImage: "fetchpriority" must be "high", "low" or "auto".');
+    this.setAttr('fetchpriority', value);
+  }
+
+  /** @returns {string|null} */
+  get fetchpriority() {
+    return this.attrString('fetchpriority');
+  }
+
+  /** @param {boolean} value */
+  set ismap(value) {
+    if (typeof value !== 'boolean') throw new TypeError('TinyImage: "ismap" must be a boolean.');
+    if (value) this.addProp('ismap');
+    else this.removeProp('ismap');
+  }
+
+  /** @returns {boolean} */
+  get ismap() {
+    return this.hasProp('ismap');
+  }
+
+  /** @param {'eager'|'lazy'} value */
+  set loading(value) {
+    if (!['eager', 'lazy'].includes(value))
+      throw new TypeError('TinyImage: "loading" must be "eager" or "lazy".');
+    this.setAttr('loading', value);
+  }
+
+  /** @returns {string|null} */
+  get loading() {
+    return this.attrString('loading');
+  }
+
+  /** @param {string} value */
+  set referrerpolicy(value) {
+    if (typeof value !== 'string')
+      throw new TypeError('TinyImage: "referrerpolicy" must be a string.');
+    this.setAttr('referrerpolicy', value);
+  }
+
+  /** @returns {string|null} */
+  get referrerpolicy() {
+    return this.attrString('referrerpolicy');
+  }
+
+  /** @param {string} value */
+  set sizes(value) {
+    if (typeof value !== 'string') throw new TypeError('TinyImage: "sizes" must be a string.');
+    this.setAttr('sizes', value);
+  }
+
+  /** @returns {string|null} */
+  get sizes() {
+    return this.attrString('sizes');
+  }
+
+  /** @param {string} value */
+  set srcset(value) {
+    if (typeof value !== 'string') throw new TypeError('TinyImage: "srcset" must be a string.');
+    this.setAttr('srcset', value);
+  }
+
+  /** @returns {string|null} */
+  get srcset() {
+    return this.attrString('srcset');
+  }
+
+  /** @param {string} value */
+  set usemap(value) {
+    if (typeof value !== 'string') throw new TypeError('TinyImage: "usemap" must be a string.');
+    this.setAttr('usemap', value);
+  }
+
+  /** @returns {string|null} */
+  get usemap() {
+    return this.attrString('usemap');
+  }
+}
+
+module.exports = TinyHtmlImage;