tiny-essentials 1.24.0 → 1.24.1

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

@@ -0,0 +1,264 @@
+import TinyHtmlTemplate from './TinyHtmlTemplate.mjs';
+/**
+ * TinyHtmlLink is a lightweight helper class for managing <link> elements.
+ * It provides a strict API for configuring preload, stylesheets, icons,
+ * and other external resource references.
+ *
+ * @example
+ * const link = new TinyHtmlLink({
+ *   rel: 'stylesheet',
+ *   href: '/styles/main.css',
+ *   media: 'screen',
+ *   blocking: 'render',
+ * });
+ *
+ * document.head.appendChild(link.el);
+ *
+ * @extends TinyHtmlTemplate<HTMLLinkElement>
+ */
+class TinyHtmlLink extends TinyHtmlTemplate {
+    /**
+     * Creates a new TinyHtmlLink instance.
+     * @param {Object} config - Configuration object.
+     * @param {string} [config.as] - Type of content being loaded (valid only for preload/modulepreload).
+     * @param {'render'} [config.blocking] - Blocking behavior (only "render").
+     * @param {'anonymous'|'use-credentials'} [config.crossorigin] - CORS mode ("anonymous" or "use-credentials").
+     * @param {boolean} [config.disabled=false] - Whether the stylesheet is disabled (rel=stylesheet only).
+     * @param {'auto'|'high'|'low'} [config.fetchpriority="auto"] - Fetch priority ("high", "low", "auto").
+     * @param {string} [config.href] - URL of the linked resource.
+     * @param {string} [config.hreflang] - Language of the linked resource (RFC 5646).
+     * @param {string} [config.imagesizes] - Sizes attribute for preload images.
+     * @param {string} [config.imagesrcset] - Srcset attribute for preload images.
+     * @param {string} [config.integrity] - Subresource Integrity metadata.
+     * @param {string} [config.media="all"] - Media query (mainly for stylesheets).
+     * @param {string} [config.referrerpolicy] - Referrer policy ("no-referrer", etc.).
+     * @param {string} [config.rel] - Relationship (stylesheet, preload, icon, etc.).
+     * @param {string} [config.sizes] - Icon sizes.
+     * @param {string} [config.title] - Title (alternate stylesheet sets).
+     * @param {string} [config.type] - MIME type of the resource (e.g., "text/css").
+     * @param {string|string[]|Set<string>} [config.tags=[]] - Initial CSS classes.
+     * @param {string} [config.mainClass=""] - Main CSS class.
+     */
+    constructor({ as, blocking, crossorigin, disabled = false, fetchpriority = 'auto', href, hreflang, imagesizes, imagesrcset, integrity, media = 'all', referrerpolicy, rel, sizes, title, type, tags = [], mainClass = '', } = {}) {
+        super(document.createElement('link'), tags, mainClass);
+        if (rel !== undefined)
+            this.rel = rel;
+        if (as !== undefined)
+            this.as = as;
+        if (blocking !== undefined)
+            this.blocking = blocking;
+        if (crossorigin !== undefined)
+            this.crossorigin = crossorigin;
+        this.disabled = disabled;
+        if (fetchpriority !== undefined)
+            this.fetchpriority = fetchpriority;
+        if (href !== undefined)
+            this.href = href;
+        if (hreflang !== undefined)
+            this.hreflang = hreflang;
+        if (imagesizes !== undefined)
+            this.imagesizes = imagesizes;
+        if (imagesrcset !== undefined)
+            this.imagesrcset = imagesrcset;
+        if (integrity !== undefined)
+            this.integrity = integrity;
+        if (media !== undefined)
+            this.media = media;
+        if (referrerpolicy !== undefined)
+            this.referrerpolicy = referrerpolicy;
+        if (sizes !== undefined)
+            this.sizes = sizes;
+        if (title !== undefined)
+            this.title = title;
+        if (type !== undefined)
+            this.type = type;
+    }
+    /** @param {string} rel */
+    set rel(rel) {
+        if (typeof rel !== 'string' || !rel.trim())
+            throw new TypeError('TinyHtmlLink: "rel" must be a non-empty string.');
+        this.setAttr('rel', rel.trim());
+    }
+    /** @returns {string|null} */
+    get rel() {
+        return this.attrString('rel');
+    }
+    /** @param {string} as */
+    set as(as) {
+        const validAs = [
+            'audio',
+            'document',
+            'embed',
+            'fetch',
+            'font',
+            'image',
+            'object',
+            'script',
+            'style',
+            'track',
+            'video',
+            'worker',
+        ];
+        if (!validAs.includes(as))
+            throw new TypeError(`TinyHtmlLink: "as" must be one of ${validAs.join(', ')}.`);
+        this.setAttr('as', as);
+    }
+    /** @returns {string|null} */
+    get as() {
+        return this.attrString('as');
+    }
+    /** @param {'render'} blocking */
+    set blocking(blocking) {
+        if (blocking !== 'render')
+            throw new TypeError('TinyHtmlLink: "blocking" only accepts "render".');
+        this.setAttr('blocking', blocking);
+    }
+    /** @returns {string|null} */
+    get blocking() {
+        return this.attrString('blocking');
+    }
+    /** @param {'anonymous'|'use-credentials'} crossorigin */
+    set crossorigin(crossorigin) {
+        const valid = ['anonymous', 'use-credentials'];
+        if (!valid.includes(crossorigin))
+            throw new TypeError(`TinyHtmlLink: "crossorigin" must be one of ${valid.join(', ')}.`);
+        this.setAttr('crossorigin', crossorigin);
+    }
+    /** @returns {string|null} */
+    get crossorigin() {
+        return this.attrString('crossorigin');
+    }
+    /** @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 {'auto'|'high'|'low'} fetchpriority */
+    set fetchpriority(fetchpriority) {
+        const valid = ['auto', 'high', 'low'];
+        if (!valid.includes(fetchpriority))
+            throw new TypeError(`TinyHtmlLink: "fetchpriority" must be one of ${valid.join(', ')}.`);
+        this.setAttr('fetchpriority', fetchpriority);
+    }
+    /** @returns {string|null} */
+    get fetchpriority() {
+        return this.attrString('fetchpriority');
+    }
+    /** @param {string} href */
+    set href(href) {
+        if (typeof href !== 'string')
+            throw new TypeError('TinyHtmlLink: "href" must be a string.');
+        this.setAttr('href', href);
+    }
+    /** @returns {string|null} */
+    get href() {
+        return this.attrString('href');
+    }
+    /** @param {string} hreflang */
+    set hreflang(hreflang) {
+        if (typeof hreflang !== 'string')
+            throw new TypeError('TinyHtmlLink: "hreflang" must be a string.');
+        this.setAttr('hreflang', hreflang);
+    }
+    /** @returns {string|null} */
+    get hreflang() {
+        return this.attrString('hreflang');
+    }
+    /** @param {string} imagesizes */
+    set imagesizes(imagesizes) {
+        if (typeof imagesizes !== 'string')
+            throw new TypeError('TinyHtmlLink: "imagesizes" must be a string.');
+        this.setAttr('imagesizes', imagesizes);
+    }
+    /** @returns {string|null} */
+    get imagesizes() {
+        return this.attrString('imagesizes');
+    }
+    /** @param {string} imagesrcset */
+    set imagesrcset(imagesrcset) {
+        if (typeof imagesrcset !== 'string')
+            throw new TypeError('TinyHtmlLink: "imagesrcset" must be a string.');
+        this.setAttr('imagesrcset', imagesrcset);
+    }
+    /** @returns {string|null} */
+    get imagesrcset() {
+        return this.attrString('imagesrcset');
+    }
+    /** @param {string} integrity */
+    set integrity(integrity) {
+        if (typeof integrity !== 'string')
+            throw new TypeError('TinyHtmlLink: "integrity" must be a string.');
+        this.setAttr('integrity', integrity);
+    }
+    /** @returns {string|null} */
+    get integrity() {
+        return this.attrString('integrity');
+    }
+    /** @param {string} media */
+    set media(media) {
+        if (typeof media !== 'string')
+            throw new TypeError('TinyHtmlLink: "media" must be a string.');
+        if (media.trim())
+            this.setAttr('media', media.trim());
+    }
+    /** @returns {string|null} */
+    get media() {
+        return this.attrString('media');
+    }
+    /** @param {string} referrerpolicy */
+    set referrerpolicy(referrerpolicy) {
+        const validPolicies = [
+            'no-referrer',
+            'no-referrer-when-downgrade',
+            'origin',
+            'origin-when-cross-origin',
+            'unsafe-url',
+        ];
+        if (!validPolicies.includes(referrerpolicy))
+            throw new TypeError(`TinyHtmlLink: "referrerpolicy" must be one of ${validPolicies.join(', ')}.`);
+        this.setAttr('referrerpolicy', referrerpolicy);
+    }
+    /** @returns {string|null} */
+    get referrerpolicy() {
+        return this.attrString('referrerpolicy');
+    }
+    /** @param {string} sizes */
+    set sizes(sizes) {
+        if (typeof sizes !== 'string')
+            throw new TypeError('TinyHtmlLink: "sizes" must be a string.');
+        this.setAttr('sizes', sizes);
+    }
+    /** @returns {string|null} */
+    get sizes() {
+        return this.attrString('sizes');
+    }
+    /** @param {string} title */
+    set title(title) {
+        if (typeof title !== 'string')
+            throw new TypeError('TinyHtmlLink: "title" must be a string.');
+        this.setAttr('title', title);
+    }
+    /** @returns {string|null} */
+    get title() {
+        return this.attrString('title');
+    }
+    /** @param {string} type */
+    set type(type) {
+        if (typeof type !== 'string')
+            throw new TypeError('TinyHtmlLink: "type" must be a string.');
+        this.setAttr('type', type);
+    }
+    /** @returns {string|null} */
+    get type() {
+        return this.attrString('type');
+    }
+}
+export default TinyHtmlLink;

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

@@ -0,0 +1,358 @@
+'use strict';
+
+var TinyHtmlTemplate = require('./TinyHtmlTemplate.cjs');
+
+/** @typedef {import('./TinyHtmlTemplate.mjs').ClassSetter} ClassSetter */
+
+/**
+ * TinyHtmlMedia is a base helper for <audio> and <video> elements.
+ * It provides a consistent API to control media playback and access
+ * standard {@link HTMLMediaElement} properties and methods.
+ *
+ * @template {HTMLMediaElement} TinyHtmlT
+ * @extends TinyHtmlTemplate<TinyHtmlT>
+ */
+class TinyHtmlMedia extends TinyHtmlTemplate {
+  /**
+   * Creates a new TinyHtmlMedia instance.
+   * @param {TinyHtmlT} tag - The HTML tag name (e.g., 'audio', 'video').
+   * @param {ClassSetter} [tags=[]] - Initial CSS classes to apply.
+   * @param {ClassSetter} [mainClass=[]] - Main CSS classes to apply.
+   */
+  constructor(tag, tags = [], mainClass = []) {
+    super(tag, tags, mainClass);
+  }
+
+  // ------------------------
+  // Core playback controls
+  // ------------------------
+
+  /**
+   * Plays all attached media elements.
+   * @returns {Promise<void>} Resolves when all play calls complete.
+   */
+  playMedia() {
+    return this.el.play();
+  }
+
+  /**
+   * Pauses all attached media elements.
+   * @returns {this}
+   */
+  pauseMedia() {
+    this.el.pause();
+    return this;
+  }
+
+  /**
+   * Toggles play/pause state for all attached media elements.
+   * @returns {this}
+   */
+  togglePlayMedia() {
+    const el = this.el;
+    el.paused ? el.play() : el.pause();
+    return this;
+  }
+
+  /**
+   * Stops all media by pausing and resetting the current time to `0`.
+   * @returns {this}
+   */
+  stopMedia() {
+    this.pauseMedia();
+    this.currentTime = 0;
+    return this;
+  }
+
+  /**
+   * Reloads all attached media elements.
+   * @returns {this}
+   */
+  loadMedia() {
+    this.el.load();
+    return this;
+  }
+
+  // ------------------------
+  // Methods
+  // ------------------------
+
+  /**
+   * Adds a new text track to the first media element.
+   * @param {TextTrackKind} kind - A string representing the TextTrack.kind property (subtitles, captions, descriptions, chapters, or metadata).
+   * @param {string} [label] - A string representing the TextTrack.label property.
+   * @param {string} [language] - A string representing the TextTrack.language property.
+   * @returns {TextTrack}
+   */
+  addTextTrack(kind, label, language) {
+    return this.el.addTextTrack(kind, label, language);
+  }
+
+  /**
+   * Checks if a given MIME type can be played.
+   * @param {string} type - MIME type (e.g., 'video/mp4').
+   * @returns {CanPlayTypeResult} Either "", "probably", or "maybe".
+   */
+  canPlayType(type) {
+    return this.el.canPlayType(type);
+  }
+
+  /**
+   * Seeks quickly to a given time if supported.
+   * @param {number} time - Target time in seconds.
+   * @returns {this}
+   */
+  fastSeek(time) {
+    this.el.fastSeek(time);
+    return this;
+  }
+
+  /**
+   * Sets custom MediaKeys on the first media element.
+   * @param {MediaKeys|null} keys - Media keys to set.
+   * @returns {Promise<void>}
+   */
+  setMediaKeys(keys) {
+    return this.el.setMediaKeys(keys);
+  }
+
+  /**
+   * Assigns a sink ID (output device) to the first media element.
+   * @param {string} id - The sink ID (device ID).
+   * @returns {Promise<void>}
+   */
+  setSinkId(id) {
+    return this.el.setSinkId(id);
+  }
+
+  // ------------------------
+  // Properties (wrappers)
+  // ------------------------
+
+  /** @type {boolean} Autoplay state of the media. */
+  get autoplay() {
+    return this.el.autoplay;
+  }
+  set autoplay(v) {
+    this.setProp('autoplay', v);
+  }
+
+  /** @returns {TimeRanges} The buffered time ranges. */
+  get buffered() {
+    return this.el.buffered;
+  }
+
+  /** @type {boolean} Whether default controls are visible. */
+  get controls() {
+    return this.el.controls;
+  }
+  set controls(v) {
+    this.setProp('controls', v);
+  }
+
+  /** @type {string|null} The list of controls available. */
+  get controlsList() {
+    return this.attr('controlsList');
+  }
+  set controlsList(v) {
+    this.setAttr('controlsList', v);
+  }
+
+  /** @type {string|null} CORS setting for the media. */
+  get crossOrigin() {
+    return this.attr('crossOrigin');
+  }
+  set crossOrigin(v) {
+    this.setAttr('crossOrigin', v);
+  }
+
+  /** @returns {string} The resolved source URL currently playing. */
+  get currentSrc() {
+    return this.el.currentSrc;
+  }
+
+  /** @type {number} The current playback position in seconds. */
+  get currentTime() {
+    return this.el.currentTime;
+  }
+  set currentTime(t) {
+    this.el.currentTime = t;
+  }
+
+  /** @type {boolean} Whether media is muted by default. */
+  get defaultMuted() {
+    return this.el.defaultMuted;
+  }
+  set defaultMuted(v) {
+    this.setProp('defaultMuted', v);
+  }
+
+  /** @type {number} Default playback rate (1 = normal speed). */
+  get defaultPlaybackRate() {
+    return this.el.defaultPlaybackRate;
+  }
+  set defaultPlaybackRate(v) {
+    this.el.defaultPlaybackRate = v;
+  }
+
+  /** @type {boolean} Whether remote playback is disabled. */
+  get disableRemotePlayback() {
+    return this.el.disableRemotePlayback;
+  }
+  set disableRemotePlayback(v) {
+    this.setProp('disableRemotePlayback', v);
+  }
+
+  /** @returns {number} The duration of the media in seconds. */
+  get duration() {
+    return this.el.duration;
+  }
+
+  /** @returns {boolean} Whether the media has ended. */
+  get ended() {
+    return this.el.ended;
+  }
+
+  /** @returns {MediaError|null} Error state if media failed to load. */
+  get error() {
+    return this.el.error;
+  }
+
+  /** @type {boolean} Whether the media should loop. */
+  get loop() {
+    return this.el.loop;
+  }
+  set loop(v) {
+    this.setProp('loop', v);
+  }
+
+  /** @type {string|null} Media group name for synchronization. */
+  get mediaGroup() {
+    return this.attr('mediaGroup');
+  }
+  set mediaGroup(v) {
+    this.setAttr('mediaGroup', v);
+  }
+
+  /** @returns {MediaKeys|null} The associated MediaKeys object. */
+  get mediaKeys() {
+    return this.el.mediaKeys;
+  }
+
+  /** @type {boolean} Whether the media is muted. */
+  get muted() {
+    return this.el.muted;
+  }
+  set muted(state) {
+    this.el.muted = state;
+  }
+
+  /** @returns {number} Network state (see `HTMLMediaElement.networkState`). */
+  get networkState() {
+    return this.el.networkState;
+  }
+
+  /** @returns {boolean} Whether the media is currently paused. */
+  get paused() {
+    return this.el.paused;
+  }
+
+  /** @type {number} Current playback rate (1 = normal speed). */
+  get playbackRate() {
+    return this.el.playbackRate;
+  }
+  set playbackRate(rate) {
+    this.el.playbackRate = rate;
+  }
+
+  /** @returns {TimeRanges} Played time ranges. */
+  get played() {
+    return this.el.played;
+  }
+
+  /** @type {"" | "metadata" | "none" | "auto"} Preload strategy ('none', 'metadata', 'auto'). */
+  get preload() {
+    return this.el.preload;
+  }
+  set preload(v) {
+    const valid = ['auto', 'metadata', 'none'];
+    if (!valid.includes(v))
+      throw new TypeError(`TinyVideo: "preload" must be one of ${valid.join(', ')}.`);
+    this.setAttr('preload', v);
+  }
+
+  /** @type {boolean} Whether pitch is preserved when rate changes. */
+  get preservesPitch() {
+    return this.el.preservesPitch;
+  }
+  set preservesPitch(v) {
+    this.setProp('preservesPitch', v);
+  }
+
+  /** @returns {number} Ready state of the media. */
+  get readyState() {
+    return this.el.readyState;
+  }
+
+  /** @returns {RemotePlayback|null} Remote playback interface. */
+  get remote() {
+    return this.el.remote;
+  }
+
+  /** @returns {TimeRanges} Seekable time ranges. */
+  get seekable() {
+    return this.el.seekable;
+  }
+
+  /** @returns {boolean} Whether the media is currently seeking. */
+  get seeking() {
+    return this.el.seeking;
+  }
+
+  /** @returns {string} Current sink ID (output device). */
+  get sinkId() {
+    return this.el.sinkId;
+  }
+
+  /** @type {string|null} Source URL of the media. */
+  get src() {
+    return this.attr('src');
+  }
+  set src(v) {
+    this.setAttr('src', v);
+  }
+
+  /** @type {MediaProvider|null} Current `srcObject` (e.g., MediaStream). */
+  get srcObject() {
+    return this.el.srcObject;
+  }
+  set srcObject(v) {
+    this.el.srcObject = v;
+  }
+
+  /** @returns {TextTrackList} Available text tracks. */
+  get textTracks() {
+    return this.el.textTracks;
+  }
+
+  /**
+   * Gets the current volume.
+   * @returns {number} Value between 0.0 and 1.0.
+   */
+  get volume() {
+    return this.el.volume;
+  }
+  /**
+   * Sets the volume level.
+   * @param {number} level - Value between 0.0 and 1.0.
+   * @throws {TypeError} If not a number.
+   */
+  set volume(level) {
+    if (typeof level !== 'number' || level < 0 || level > 1) {
+      throw new TypeError('TinyVideo: "volume" must be a number between 0.0 and 1.0.');
+    }
+    this.el.volume = level;
+  }
+}
+
+module.exports = TinyHtmlMedia;