tiny-essentials 1.25.0 → 1.25.2

package/dist/v1/libs/TinyAnalogClock.mjs

@@ -0,0 +1,653 @@
+/**
+ * Configuration object for the Analog Clock.
+ * @typedef {Object} ClockConfig
+ * @property {string} bgColor - The background color of the clock face (e.g., '#ffffff', 'rgb(0,0,0)').
+ * @property {string} borderColor - The color of the clock's outer border.
+ * @property {number} borderWidth - The thickness of the outer border in pixels.
+ * @property {string} markColor - The color of the minute/hour tick marks.
+ * @property {string} hourHandColor - The color of the hour hand.
+ * @property {string} minuteHandColor - The color of the minute hand.
+ * @property {string} secondHandColor - The color of the second hand.
+ * @property {string} textColor - The color of the numbers on the clock face.
+ * @property {string|null} skinUrl - The URL of an image to use as the clock face background. Set to null to use bgColor.
+ * @property {boolean} showNumbers - Whether to render the numbers (1-12) on the clock face.
+ * @property {boolean} showSeconds - Whether to display the second hand.
+ * @property {number} size - The total width and height of the clock in pixels.
+ * @property {number} sizeAdjust - Scale factor for the font size of the numbers relative to the clock size.
+ * @property {number} padding - Padding in pixels between the clock edge and the tick marks.
+ * @property {number} angleDistance - Distance multiplier (0-1) for placing numbers relative to the radius.
+ * @property {number} pwH - Hour tick width as a percentage of clock size (0.0 to 1.0).
+ * @property {number} phH - Hour tick height as a percentage of clock size (0.0 to 1.0).
+ * @property {number} pwM - Minute tick width as a percentage of clock size (0.0 to 1.0).
+ * @property {number} phM - Minute tick height as a percentage of clock size (0.0 to 1.0).
+ */
+class TinyAnalogClock {
+    /** @type {HTMLElement} */
+    #element;
+    /** @type {HTMLElement} */
+    #faceLayer;
+    /** @type {HTMLElement} */
+    #skinLayer;
+    /** @type {ClockConfig} */
+    #config;
+    /** @type {number|null} */
+    #animationFrame = null;
+    /**
+     * Retrieves the current date and extracts the specific hour, minute, and second components.
+     * @returns {{ now: Date, s: number, m: number, h: number }}
+     * @private
+     */
+    _getDate() {
+        const now = new Date();
+        const s = now.getSeconds();
+        const m = now.getMinutes();
+        const h = now.getHours();
+        return { now, s, m, h };
+    }
+    /**
+     * Creates an instance of TinyAnalogClock.
+     * Initializes the DOM structure and starts the animation loop.
+     * @param {Partial<ClockConfig>} [options] - Optional configuration overrides.
+     */
+    constructor(options = {}) {
+        this.#config = {
+            bgColor: '#f0f0f0',
+            borderColor: '#333',
+            borderWidth: 8,
+            markColor: '#333',
+            hourHandColor: '#000',
+            minuteHandColor: '#444',
+            secondHandColor: '#d81c1c',
+            textColor: '#000',
+            skinUrl: null,
+            showNumbers: true,
+            showSeconds: true,
+            size: 800,
+            sizeAdjust: 0.04,
+            padding: 45,
+            angleDistance: 0.95,
+            pwH: 0.008,
+            phH: 0.08,
+            pwM: 0.005,
+            phM: 0.03,
+            ...options,
+        };
+        this.#element = document.createElement('div');
+        this.#element.className = 'analog-clock-container';
+        // Base styles for the container
+        this.#element.style.position = 'relative';
+        this.#element.style.borderRadius = '50%';
+        this.#element.style.overflow = 'hidden';
+        this.#element.style.boxSizing = 'border-box';
+        // 1. Skin Layer (Background Image)
+        this.#skinLayer = document.createElement('div');
+        this.#skinLayer.style.position = 'absolute';
+        this.#skinLayer.style.inset = '0';
+        this.#skinLayer.style.backgroundSize = 'cover';
+        this.#skinLayer.style.backgroundPosition = 'center';
+        this.#skinLayer.style.zIndex = '0';
+        // 2. Face Layer (Ticks and Numbers)
+        this.#faceLayer = document.createElement('div');
+        this.#faceLayer.style.position = 'absolute';
+        this.#faceLayer.style.inset = '0';
+        this.#faceLayer.style.zIndex = '1';
+        this.#faceLayer.style.pointerEvents = 'none';
+        // 3. Hands Layer (Hour, Minute, Second hands)
+        const handsLayer = document.createElement('div');
+        handsLayer.style.position = 'absolute';
+        handsLayer.style.inset = '0';
+        handsLayer.style.zIndex = '2';
+        handsLayer.style.pointerEvents = 'none';
+        handsLayer.innerHTML = `
+            <div class="hand hour-hand"></div>
+            <div class="hand minute-hand"></div>
+            <div class="hand second-hand"></div>
+            <div class="center-pin"></div>
+        `;
+        this.#element.appendChild(this.#skinLayer);
+        this.#element.appendChild(this.#faceLayer);
+        this.#element.appendChild(handsLayer);
+        // Inject Styles dynamically to keep the class self-contained
+        const style = document.createElement('style');
+        style.textContent = `
+            .analog-clock-container .hand {
+                position: absolute;
+                bottom: 50%;
+                left: 50%;
+                transform-origin: bottom center;
+                border-radius: 4px;
+                transform: translateX(-50%) rotate(0deg);
+                z-index: 5;
+            }
+            .analog-clock-container .center-pin {
+                position: absolute;
+                top: 50%; left: 50%;
+                width: 12px; height: 12px;
+                background: #333;
+                border-radius: 50%;
+                transform: translate(-50%, -50%);
+                z-index: 10;
+            }
+            .analog-clock-container .clock-mark {
+                position: absolute;
+                top: 50%; left: 50%;
+                background: currentColor;
+                transform-origin: center center;
+            }
+            .analog-clock-container .clock-number {
+                position: absolute;
+                top: 50%; left: 50%;
+                transform: translate(-50%, -50%);
+                font-family: sans-serif;
+                font-weight: bold;
+                text-align: center;
+                line-height: 1;
+            }
+        `;
+        this.#element.appendChild(style);
+        this._applyConfig();
+        this._renderFace();
+        this._startTicker();
+    }
+    /**
+     * Applies the current configuration to the DOM elements (colors, sizes, visibility).
+     * @private
+     */
+    _applyConfig() {
+        const s = this.#element.style;
+        const c = this.#config;
+        s.width = `${c.size}px`;
+        s.height = `${c.size}px`;
+        s.border = `${c.borderWidth}px solid ${c.borderColor}`;
+        s.backgroundColor = c.bgColor;
+        if (c.skinUrl) {
+            this.#skinLayer.style.backgroundImage = `url(${c.skinUrl})`;
+            this.#skinLayer.style.display = 'block';
+        }
+        else {
+            this.#skinLayer.style.display = 'none';
+        }
+        /**
+         * Helper to safely query elements within the clock.
+         * @param {string} sel
+         * @returns {HTMLDivElement}
+         */
+        const q = (sel) => {
+            const result = this.#element.querySelector(sel);
+            if (!(result instanceof HTMLDivElement))
+                throw new Error(`TinyAnalogClock: Element ${sel} not found.`);
+            return result;
+        };
+        // Hour Hand
+        const hHand = q('.hour-hand');
+        hHand.style.backgroundColor = c.hourHandColor;
+        hHand.style.width = `${c.size * 0.025}px`;
+        hHand.style.height = `${c.size * 0.25}px`;
+        hHand.style.marginLeft = `${(c.size * 0.025) / -2}px`; // Center alignment fix
+        hHand.style.bottom = '50%';
+        hHand.style.left = '50%';
+        hHand.style.transformOrigin = 'bottom center';
+        // Minute Hand
+        const mHand = q('.minute-hand');
+        mHand.style.backgroundColor = c.minuteHandColor;
+        mHand.style.width = `${c.size * 0.015}px`;
+        mHand.style.height = `${c.size * 0.35}px`;
+        mHand.style.marginLeft = `${(c.size * 0.015) / -2}px`;
+        // Second Hand
+        const sHand = q('.second-hand');
+        if (c.showSeconds) {
+            sHand.style.display = 'block';
+            sHand.style.backgroundColor = c.secondHandColor;
+            sHand.style.width = `${c.size * 0.005}px`;
+            sHand.style.height = `${c.size * 0.4}px`;
+            sHand.style.marginLeft = `${(c.size * 0.005) / -2}px`;
+        }
+        else {
+            sHand.style.display = 'none';
+        }
+        q('.center-pin').style.background = c.borderColor;
+    }
+    /**
+     * Renders the clock face, including tick marks and numbers, based on the current size and config.
+     * Uses trigonometry to position elements perfectly from the center.
+     * @private
+     */
+    _renderFace() {
+        this.#faceLayer.innerHTML = '';
+        const radius = this.#config.size / 2 - this.#config.borderWidth;
+        // 1. Render Ticks (Lines)
+        for (let i = 0; i < 60; i++) {
+            const isHour = i % 5 === 0;
+            const el = document.createElement('div');
+            el.className = 'clock-mark';
+            const w = isHour
+                ? this.#config.size * this.#config.pwH
+                : this.#config.size * this.#config.pwM;
+            const h = isHour
+                ? this.#config.size * this.#config.phH
+                : this.#config.size * this.#config.phM;
+            const color = this.#config.markColor;
+            el.style.width = `${w}px`;
+            el.style.height = `${h}px`;
+            el.style.color = color;
+            // Distance from center to the TICK's center
+            // We want the tick to be close to the edge.
+            // Distance = radius - padding - (half of tick height)
+            const distanceFromCenter = radius - this.#config.padding - h / 2;
+            // Logic: Start at center (50% 50%) -> Rotate -> Push Outwards
+            el.style.transform = `translate(-50%, -50%) rotate(${i * 6}deg) translate(0, -${distanceFromCenter}px)`;
+            this.#faceLayer.appendChild(el);
+        }
+        // 2. Render Numbers
+        if (this.#config.showNumbers) {
+            for (let i = 1; i <= 12; i++) {
+                const angle = i * 30 * (Math.PI / 180);
+                // Adjust radius for text position (80% of total radius)
+                const dist = radius * this.#config.angleDistance;
+                const x = radius + Math.sin(angle) * dist;
+                const y = radius - Math.cos(angle) * dist;
+                const num = document.createElement('div');
+                num.className = 'clock-number';
+                num.innerText = i.toString();
+                num.style.left = `${x}px`;
+                num.style.top = `${y}px`;
+                num.style.color = this.#config.textColor;
+                num.style.fontSize = `${this.#config.size * this.#config.sizeAdjust}px`;
+                this.#faceLayer.appendChild(num);
+            }
+        }
+    }
+    /**
+     * Starts the RequestAnimationFrame loop to update hand positions.
+     * @private
+     */
+    _startTicker() {
+        if (this.#animationFrame)
+            return;
+        const update = () => {
+            const { s, m, h } = this._getDate();
+            // Calculate degrees
+            const sDeg = s * 6;
+            const mDeg = m * 6 + s * 0.1;
+            const hDeg = (h % 12) * 30 + m * 0.5;
+            /**
+             * @param {string} sel
+             * @returns {HTMLDivElement}
+             */
+            const q = (sel) => {
+                const result = this.#element.querySelector(sel);
+                if (!(result instanceof HTMLDivElement))
+                    throw new Error(`${sel} not found.`);
+                return result;
+            };
+            if (this.#element.querySelector('.second-hand')) {
+                q('.second-hand').style.transform = `rotate(${sDeg}deg)`;
+            }
+            q('.minute-hand').style.transform = `rotate(${mDeg}deg)`;
+            q('.hour-hand').style.transform = `rotate(${hDeg}deg)`;
+            this.#animationFrame = requestAnimationFrame(update);
+        };
+        update();
+    }
+    // ==========================================
+    // GETTERS & SETTERS (Full Access)
+    // ==========================================
+    /**
+     * Gets the main HTML element of the clock.
+     * @returns {HTMLElement} The clock container.
+     */
+    get element() {
+        return this.#element;
+    }
+    /**
+     * Sets the size of the clock.
+     * @param {number} value - The new size in pixels. Must be a positive number.
+     * @throws {Error} If value is not a positive number.
+     */
+    set size(value) {
+        if (typeof value !== 'number' || value <= 0 || isNaN(value)) {
+            throw new Error(`TinyAnalogClock: 'size' must be a positive number. Received: ${value}`);
+        }
+        this.#config.size = value;
+        this._applyConfig();
+        this._renderFace();
+    }
+    /** * Gets the clock size in pixels.
+     * @returns {number}
+     */
+    get size() {
+        return this.#config.size;
+    }
+    /**
+     * Sets the background image (skin) of the clock.
+     * @param {string|null} url - The URL string of the image, or null to remove the skin.
+     * @throws {Error} If value is not a string or null.
+     */
+    set skinUrl(url) {
+        if (url !== null && typeof url !== 'string') {
+            throw new Error(`TinyAnalogClock: 'skin' must be a URL string or null. Received type: ${typeof url}`);
+        }
+        this.#config.skinUrl = url;
+        this._applyConfig();
+    }
+    /**
+     * Gets the skin URL.
+     * @returns {string|null}
+     */
+    get skinUrl() {
+        return this.#config.skinUrl;
+    }
+    /**
+     * Sets the primary border color.
+     * @param {string} color - A valid CSS color string.
+     * @throws {Error} If value is not a non-empty string.
+     */
+    set borderColor(color) {
+        if (typeof color !== 'string' || color.trim() === '') {
+            throw new Error(`TinyAnalogClock: 'borderColor' must be a non-empty string. Received: ${color}`);
+        }
+        this.#config.borderColor = color;
+        this._applyConfig();
+        this._renderFace();
+    }
+    /**
+     * Gets the border color.
+     * @returns {string}
+     */
+    get borderColor() {
+        return this.#config.borderColor;
+    }
+    /**
+     * Sets the primary marks color.
+     * @param {string} color - A valid CSS color string.
+     * @throws {Error} If value is not a non-empty string.
+     */
+    set markColor(color) {
+        if (typeof color !== 'string' || color.trim() === '') {
+            throw new Error(`TinyAnalogClock: 'markColor' must be a non-empty string. Received: ${color}`);
+        }
+        this.#config.markColor = color;
+        this._applyConfig();
+        this._renderFace();
+    }
+    /**
+     * Gets the tick marks color.
+     * @returns {string}
+     */
+    get markColor() {
+        return this.#config.markColor;
+    }
+    /**
+     * Sets the primary text color.
+     * @param {string} color - A valid CSS color string.
+     * @throws {Error} If value is not a non-empty string.
+     */
+    set textColor(color) {
+        if (typeof color !== 'string' || color.trim() === '') {
+            throw new Error(`TinyAnalogClock: 'textColor' must be a non-empty string. Received: ${color}`);
+        }
+        this.#config.textColor = color;
+        this._applyConfig();
+        this._renderFace();
+    }
+    /**
+     * Gets the text color.
+     * @returns {string}
+     */
+    get textColor() {
+        return this.#config.textColor;
+    }
+    /**
+     * Toggles the visibility of numbers on the clock face.
+     * @param {boolean} value - True to show numbers, false to hide.
+     * @throws {Error} If value is not a boolean.
+     */
+    set showNumbers(value) {
+        if (typeof value !== 'boolean') {
+            throw new Error(`TinyAnalogClock: 'showNumbers' must be a boolean. Received type: ${typeof value}`);
+        }
+        this.#config.showNumbers = value;
+        this._renderFace();
+    }
+    /**
+     * Gets numbers visibility.
+     * @returns {boolean}
+     */
+    get showNumbers() {
+        return this.#config.showNumbers;
+    }
+    /**
+     * Sets the background color.
+     * @param {string} value
+     */
+    set bgColor(value) {
+        if (typeof value !== 'string' || !value)
+            throw new Error("TinyAnalogClock: 'bgColor' must be a non-empty string.");
+        this.#config.bgColor = value;
+        this._applyConfig();
+    }
+    /**
+     * Gets the background color.
+     * @returns {string}
+     */
+    get bgColor() {
+        return this.#config.bgColor;
+    }
+    /**
+     * Sets the border thickness in pixels.
+     * @param {number} value
+     */
+    set borderWidth(value) {
+        if (typeof value !== 'number' || value < 0)
+            throw new Error("TinyAnalogClock: 'borderWidth' must be a non-negative number.");
+        this.#config.borderWidth = value;
+        this._applyConfig();
+        this._renderFace(); // Radius changes, so we must re-render face
+    }
+    /**
+     * Gets the border thickness.
+     * @returns {number}
+     */
+    get borderWidth() {
+        return this.#config.borderWidth;
+    }
+    /**
+     * Sets the hour hand color.
+     * @param {string} value
+     */
+    set hourHandColor(value) {
+        if (typeof value !== 'string' || !value)
+            throw new Error("TinyAnalogClock: 'hourHandColor' must be a non-empty string.");
+        this.#config.hourHandColor = value;
+        this._applyConfig();
+    }
+    /**
+     * Gets the hour hand color.
+     * @returns {string}
+     */
+    get hourHandColor() {
+        return this.#config.hourHandColor;
+    }
+    /**
+     * Sets the minute hand color.
+     * @param {string} value
+     */
+    set minuteHandColor(value) {
+        if (typeof value !== 'string' || !value)
+            throw new Error("TinyAnalogClock: 'minuteHandColor' must be a non-empty string.");
+        this.#config.minuteHandColor = value;
+        this._applyConfig();
+    }
+    /**
+     * Gets the minute hand color.
+     * @returns {string}
+     */
+    get minuteHandColor() {
+        return this.#config.minuteHandColor;
+    }
+    /**
+     * Sets the second hand color.
+     * @param {string} value
+     */
+    set secondHandColor(value) {
+        if (typeof value !== 'string' || !value)
+            throw new Error("TinyAnalogClock: 'secondHandColor' must be a non-empty string.");
+        this.#config.secondHandColor = value;
+        this._applyConfig();
+    }
+    /**
+     * Gets the second hand color.
+     * @returns {string}
+     */
+    get secondHandColor() {
+        return this.#config.secondHandColor;
+    }
+    /**
+     * Toggle second hand visibility.
+     * @param {boolean} value
+     */
+    set showSeconds(value) {
+        if (typeof value !== 'boolean')
+            throw new Error("TinyAnalogClock: 'showSeconds' must be a boolean.");
+        this.#config.showSeconds = value;
+        this._applyConfig();
+    }
+    /**
+     * Gets second hand visibility.
+     * @returns {boolean}
+     */
+    get showSeconds() {
+        return this.#config.showSeconds;
+    }
+    /**
+     * Sets the font size adjustment factor.
+     * @param {number} value - Positive number.
+     */
+    set sizeAdjust(value) {
+        if (typeof value !== 'number' || value <= 0)
+            throw new Error("TinyAnalogClock: 'sizeAdjust' must be a positive number.");
+        this.#config.sizeAdjust = value;
+        this._renderFace();
+    }
+    /**
+     * Gets the font size adjustment factor.
+     * @returns {number}
+     */
+    get sizeAdjust() {
+        return this.#config.sizeAdjust;
+    }
+    /**
+     * Sets the padding from edge to ticks.
+     * @param {number} value - Non-negative number in pixels.
+     */
+    set padding(value) {
+        if (typeof value !== 'number' || value < 0)
+            throw new Error("TinyAnalogClock: 'padding' must be a non-negative number.");
+        this.#config.padding = value;
+        this._renderFace();
+    }
+    /**
+     * Gets the padding.
+     * @returns {number}
+     */
+    get padding() {
+        return this.#config.padding;
+    }
+    /**
+     * Sets the angle distance multiplier for numbers placement.
+     * @param {number} value - Positive number.
+     */
+    set angleDistance(value) {
+        if (typeof value !== 'number' || value <= 0)
+            throw new Error("TinyAnalogClock: 'angleDistance' must be a positive number.");
+        this.#config.angleDistance = value;
+        this._renderFace();
+    }
+    /**
+     * Gets the angle distance multiplier.
+     * @returns {number}
+     */
+    get angleDistance() {
+        return this.#config.angleDistance;
+    }
+    /**
+     * Sets the Hour tick width percentage.
+     * @param {number} value - Positive number.
+     */
+    set pwH(value) {
+        if (typeof value !== 'number' || value <= 0)
+            throw new Error("TinyAnalogClock: 'pwH' must be a positive number.");
+        this.#config.pwH = value;
+        this._renderFace();
+    }
+    /**
+     * Gets the Hour tick width percentage.
+     * @returns {number}
+     */
+    get pwH() {
+        return this.#config.pwH;
+    }
+    /**
+     * Sets the Hour tick height percentage.
+     * @param {number} value - Positive number.
+     */
+    set phH(value) {
+        if (typeof value !== 'number' || value <= 0)
+            throw new Error("TinyAnalogClock: 'phH' must be a positive number.");
+        this.#config.phH = value;
+        this._renderFace();
+    }
+    /**
+     * Gets the Hour tick height percentage.
+     * @returns {number}
+     */
+    get phH() {
+        return this.#config.phH;
+    }
+    /**
+     * Sets the Minute tick width percentage.
+     * @param {number} value - Positive number.
+     */
+    set pwM(value) {
+        if (typeof value !== 'number' || value <= 0)
+            throw new Error("TinyAnalogClock: 'pwM' must be a positive number.");
+        this.#config.pwM = value;
+        this._renderFace();
+    }
+    /**
+     * Gets the Minute tick width percentage.
+     * @returns {number}
+     */
+    get pwM() {
+        return this.#config.pwM;
+    }
+    /**
+     * Sets the Minute tick height percentage.
+     * @param {number} value - Positive number.
+     */
+    set phM(value) {
+        if (typeof value !== 'number' || value <= 0)
+            throw new Error("TinyAnalogClock: 'phM' must be a positive number.");
+        this.#config.phM = value;
+        this._renderFace();
+    }
+    /**
+     * Gets the Minute tick height percentage.
+     * @returns {number}
+     */
+    get phM() {
+        return this.#config.phM;
+    }
+    /**
+     * Destroys the clock instance, stops animations, and removes the element from DOM.
+     * @returns {void}
+     */
+    destroy() {
+        if (this.#animationFrame) {
+            cancelAnimationFrame(this.#animationFrame);
+            this.#animationFrame = null;
+        }
+        this.#element.remove();
+    }
+}
+export default TinyAnalogClock;