From 2451b1a9e796df68f69a88f7c3da9b068fed8633 Mon Sep 17 00:00:00 2001
From: David Ali <alidavid2122@gmail.com>
Date: Tue, 6 Jan 2026 01:50:20 +0100
Subject: [PATCH] version 1.1.0

---
 .gitignore      |   3 +-
 .npmignore      |  13 ------
 CHANGELOG.md    |  23 ++++++++++
 Dockerfile      |   1 +
 Jenkinsfile     |   6 +--
 README.md       |  78 +++++++++++++++++++++++----------
 package.json    |   3 +-
 src/wc-timer.js | 114 +++++++++++++++++++++++++++++-------------------
 8 files changed, 153 insertions(+), 88 deletions(-)
 delete mode 100644 .npmignore
 create mode 100644 CHANGELOG.md

diff --git a/.gitignore b/.gitignore
index 790865c..a852954 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,2 @@
-e2e/cypress/screenshots/*
\ No newline at end of file
+e2e/cypress/screenshots/*
+*.old
diff --git a/.npmignore b/.npmignore
deleted file mode 100644
index 5811047..0000000
--- a/.npmignore
+++ /dev/null
@@ -1,13 +0,0 @@
-# Ignoruj narzędzia CI/CD
-Jenkinsfile
-Dockerfile
-docker-compose.test.yml
-.git
-.gitignore
-
-# Ignoruj testy i demo
-e2e/
-public/
-
-# Ignoruj konfigurację IDE
-.vscode/
\ No newline at end of file
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..476b6cb
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,23 @@
+# CHANGELOG
+
+## [1.1.0] : Refactor and Optimization
+
+### Performance
+* **IntlCache**: Implemented caching for `Intl` objects. Date formatting no longer creates new instances on every refresh.
+* **Shared Styles**: Used `adoptedStyleSheets` instead of `<style>` tags. The browser parses CSS only once.
+* **Date Math**: Removed `while` loops for year/month calculations. Replaced them with faster O(1) mathematical formulas.
+
+### Stability and UI
+* **Layout Shift (CLS)**: Fixed content jumping on load. The component now has a default `min-height`.
+* **Initialization**: Added a non-breaking space (`\u00A0`) at start. This prevents zero height before the first render.
+* **TickHub Safety**: Iteration over subscribers now uses a copy. An error in one timer will not stop others.
+
+### Code Quality
+* **Private Fields**: Changed `_variable` convention to native private fields `#variable`. Internal state is now fully protected.
+* **Attribute Handling**: Improved attribute update logic (`#isAttrUpdate`). This eliminates unnecessary render cycles.
+* **Auto-restart**: The stopped timer restarts automatically if the target date changes to the future.
+* **Fallback**: Added a safety check returning `00:00:00` if formatting results in an empty string.
+
+## [1.0.1] : Added README.md
+
+## [1.0.0] : First version
\ No newline at end of file
diff --git a/Dockerfile b/Dockerfile
index 83430d0..324414e 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -7,6 +7,7 @@ WORKDIR /app/wc-timer
 # Kopiowanie plików manifestu i instalacja zależności
 COPY package.json ./
 COPY README.md ./
+COPY CHANGELOG.md ./
 RUN npm install
 
 # Kopiowanie reszty plików projektu (kod źródłowy)
diff --git a/Jenkinsfile b/Jenkinsfile
index 6fe24c9..f80d90c 100644
--- a/Jenkinsfile
+++ b/Jenkinsfile
@@ -68,10 +68,10 @@ pipeline {
             }
 
             if (versionExists) {
-              echo "❌ BŁĄD: Wersja ${localVersion} jest już opublikowana w NPM!"
+              echo "[ERROR] BŁĄD: Wersja ${localVersion} jest już opublikowana w NPM!"
               error("Przerwano publikację: Wersja ${localVersion} już istnieje.")
             } else {
-              echo "🚀 Wersja ${localVersion} jest nowa. Publikuję..."
+              echo "[OK] Wersja ${localVersion} jest nowa. Publikuję..."
               
               sh """
                 docker compose -f docker-compose.test.yml run --rm \
@@ -81,7 +81,7 @@ pipeline {
                 sh -c "echo '//registry.npmjs.org/:_authToken=\${NPM_TOKEN}' > .npmrc && npm publish --access public"
               """
               
-              echo "✅ SUKCES: Wersja ${localVersion} została opublikowana."
+              echo "[OK] SUKCES: Wersja ${localVersion} została opublikowana."
             }
           }
         }
diff --git a/README.md b/README.md
index 27b3da5..9339d14 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,14 @@
 # wc-timer
 
-A lightweight, dependency-free Web Component for countdowns and elapsed time. It uses the native `Intl` API for formatting and supports automatic language detection.
+A high-performance, dependency-free Web Component for countdowns, elapsed time, and static dates. It uses a shared ticker and cached `Intl` formatters for maximum efficiency.
 
 ## Features
 
-* **Zero Dependencies**: Built with standard Web Components API.
-* **Smart Formatting**: Supports various presets like `hms`, `dhms`, or `ydhms`.
-* **Performance**: Uses a shared global ticker (TickHub) to sync all instances and save CPU.
-* **Light DOM**: Renders text directly, making it easy to style with global CSS.
-* **Responsive**: Automatically updates when attributes change.
+* **High Performance**: Uses a shared global ticker (TickHub) to sync all instances. It calculates dates using O(1) math and caches `Intl` objects to save memory.
+* **Smart Formatting**: Supports `Intl.DurationFormat` with a robust fallback for older browsers.
+* **Versatile Presets**: Choose from `hms`, `dhms`, `ydhms`, `auto`, or static `date`.
+* **Light DOM**: Renders as a standard Text Node. The text is selectable and inherits global CSS styles easily.
+* **Auto-Restart**: If you update the target to a future date, the timer restarts automatically.
 
 ## Installation
 
@@ -23,24 +23,26 @@ npm install wc-timer
 
 ```javascript
 import 'wc-timer';
-// Or via script tag
-// <script type="module" src="path/to/wc-timer.js"></script>
+// Or via script tag:
+// <script type="module" src="wc-timer.js"></script>
 
 ```
 
-2. **Use the tag in HTML**:
+2. **Use in HTML**:
 
 ```html
-<wc-timer target="2025-12-31T23:59:59Z"></wc-timer>
+<wc-timer target="2026-01-01T00:00:00Z"></wc-timer>
 
 <wc-timer 
-  target="2026-01-01T00:00:00Z" 
+  target="2026-06-01T12:00:00Z" 
   preset="dhms" 
-  labels="short" 
-  compact
-  locale="en-US">
+  labels="long" 
+  compact 
+  locale="pl">
 </wc-timer>
 
+<wc-timer preset="date" target="2025-12-31"></wc-timer>
+
 ```
 
 ## API Reference
@@ -49,32 +51,60 @@ import 'wc-timer';
 
 | Attribute | Type | Default | Description |
 | --- | --- | --- | --- |
-| `target` | `ISO 8601` | `now` | The target date/time (e.g., `2025-12-31T23:59:59Z`). |
-| `preset` | `string` | `auto` | Format preset: `auto`, `hms`, `dhms`, `ydhms`, `date`. |
-| `labels` | `string` | `long` | Unit labels: `none` (00:00:00), `short` (1h 5m), `long` (1 hour 5 minutes). |
-| `compact` | `boolean` | `false` | If present, hides zero-value units (e.g., skips "0 years"). |
-| `locale` | `BCP 47` | `auto` | Forces a specific language (e.g., `pl`, `en`, `de`). Defaults to browser settings. |
+| `target` | `string` | `now` | The target date (ISO 8601 string or Date compatible). |
+| `preset` | `string` | `auto` | formatting mode: `auto`, `hms`, `dhms`, `ydhms`, `date`. |
+| `labels` | `string` | `short` | unit labels: `none` (00:00:00), `short` (1h 5m), `long` (1 hour 5 minutes). |
+| `compact` | `boolean` | `false` | if present, hides zero-value high units (e.g. hides "0 years"). |
+| `locale` | `string` | `auto` | overrides browser language (e.g. `pl`, `en-US`). |
+
+### Presets Details
+
+* **auto**: shows `HH:MM:SS`. If duration > 30 days, it adds days.
+* **hms**: hours, minutes, seconds.
+* **dhms**: days, hours, minutes, seconds.
+* **ydhms**: years, months, days, hours, minutes, seconds.
+* **date**: static date formatted via `Intl.DateTimeFormat`.
 
 ### JavaScript Properties
 
-All attributes are reflected as properties on the DOM element.
+You can control the element programmatically.
 
 ```javascript
 const el = document.querySelector('wc-timer');
 
-// Update target dynamically
+// Update target (accepts Date object, string, or timestamp)
 el.target = new Date('2030-01-01');
 
-// Change configuration
+// Change settings on the fly
 el.preset = 'ydhms';
 el.compact = true;
+el.labels = 'long';
+
+```
+
+## Styling
+
+Since `wc-timer` uses Light DOM, you can style it with standard CSS.
+
+```css
+wc-timer {
+  font-family: 'Courier New', monospace;
+  font-weight: bold;
+  color: #2563eb;
+}
 
 ```
 
 ## Browser Support
 
-Works in all modern browsers supporting Web Components and `Intl.DurationFormat` (or falls back gracefully).
+Works in all modern browsers. It uses `Intl.DurationFormat` if available. Otherwise, it falls back to a custom formatter using `Intl.PluralRules`.
 
 ## License
 
-MIT
+Copyright 2026 Dávid Ali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/package.json b/package.json
index d6b0d4f..7e19592 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "wc-timer",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "A lightweight, dependency-free countdown timer Web Component.",
   "type": "module",
   "main": "src/wc-timer.js",
@@ -9,6 +9,7 @@
   },
   "files": [
     "src/wc-timer.js",
+    "CHANGELOG.md",
     "README.md"
   ],
   "scripts": {
diff --git a/src/wc-timer.js b/src/wc-timer.js
index faf20e5..bb3686a 100644
--- a/src/wc-timer.js
+++ b/src/wc-timer.js
@@ -1,16 +1,18 @@
 /**
- * wc-timer.js — Web Component (Refactored)
+ * wc-timer
+ * @version 1.1.0
+ * @description A lightweight, efficient countdown/uptimer Web Component.
+ * @license MIT
  */
 
-/* ---------------- Memoizacja Intl ----------------
- * Obiekty Intl są kosztowne. Tworzymy je raz i używamy wielokrotnie.
- * Kluczem cache jest locale i zserializowane opcje.
+/**
+ * Internal cache for Intl objects to optimize performance.
+ * @private
  */
 const IntlCache = (() => {
   const cache = new Map();
 
   function get(Ctor, locale, opts = {}) {
-    // Tworzymy unikalny klucz dla kombinacji konstruktora, języka i opcji.
     const key = `${Ctor.name}:${locale}:${JSON.stringify(opts)}`;
     if (!cache.has(key)) {
       cache.set(key, new Ctor(locale, opts));
@@ -22,12 +24,14 @@ const IntlCache = (() => {
     dtf: (loc, opts) => get(Intl.DateTimeFormat, loc, opts),
     pr: (loc) => get(Intl.PluralRules, loc),
     df: (loc, opts) => get(Intl.DurationFormat, loc, opts),
-    // Sprawdzamy wsparcie tylko raz
     hasIDF: typeof Intl !== 'undefined' && 'DurationFormat' in Intl
   };
 })();
 
-/* ---------------- Global synced tick ---------------- */
+/**
+ * Centralized ticker to sync all instances and prevent drift.
+ * @private
+ */
 const TickHub = (() => {
   const subs = new Set();
   let timer = null;
@@ -35,12 +39,10 @@ const TickHub = (() => {
   function scheduleNext() {
     if (subs.size === 0) return;
     const now = performance.now();
-    // Wyrównanie do pełnej sekundy
     const msToNext = 1000 - (Math.floor(now) % 1000);
-    
+
     timer = setTimeout(() => {
       const t = Date.now();
-      // Kopiujemy Set, aby uniknąć problemów przy dodawaniu/usuwaniu w trakcie pętli
       for (const cb of [...subs]) {
         try { cb(t); } catch (e) { console.error(e); }
       }
@@ -63,7 +65,7 @@ const TickHub = (() => {
   };
 })();
 
-/* ---------------- Locale & Helpers ---------------- */
+/* ---------------- Locale Helpers ---------------- */
 const LABELS = {
   en: {
     y: { long: { one: 'year', other: 'years' }, short: 'y' },
@@ -89,9 +91,8 @@ function resolveLocale(el) {
   return (navigator.language || 'en').toLowerCase();
 }
 
-/* ---------------- Algorytmy dat ---------------- */
+/* ---------------- Date Logic ---------------- */
 
-// Obliczanie różnicy kalendarzowej bez pętli (O(1))
 function diffCalendar(a, b, wantY, wantM) {
   let anchor = new Date(a);
   let y = 0;
@@ -99,7 +100,6 @@ function diffCalendar(a, b, wantY, wantM) {
 
   if (wantY) {
     y = b.getFullYear() - anchor.getFullYear();
-    // Sprawdzamy, czy "przeskoczyliśmy" datę końcową
     const probe = new Date(anchor);
     probe.setFullYear(anchor.getFullYear() + y);
     if (probe > b) y--;
@@ -107,7 +107,6 @@ function diffCalendar(a, b, wantY, wantM) {
   }
 
   if (wantM) {
-    // Różnica w miesiącach całkowitych
     M = (b.getFullYear() - anchor.getFullYear()) * 12 + (b.getMonth() - anchor.getMonth());
     const probe = new Date(anchor);
     probe.setMonth(anchor.getMonth() + M);
@@ -120,8 +119,6 @@ function diffCalendar(a, b, wantY, wantM) {
 
 function collapseForUnits(start, end, show) {
   const { y, M, anchor } = diffCalendar(start, end, !!show.y, !!show.M);
-  
-  // Jeśli liczyliśmy Y/M, resztę liczymy od 'anchor'. Jeśli nie, od 'start'.
   const base = (show.y || show.M) ? anchor : start;
   let rest = Math.max(0, end - base);
 
@@ -136,40 +133,36 @@ function collapseForUnits(start, end, show) {
   return res;
 }
 
-/* ---------------- Formatter ---------------- */
+/* ---------------- Formatting ---------------- */
 const pad2 = (n) => String(n ?? 0).padStart(2, '0');
 
 function formatDurationSmart(locale, labelsMode, show, parts) {
-  // Tryb: none (czysty tekst z dwukropkami)
   if (labelsMode === 'none') {
     const head = [];
     if (show.y) head.push(parts.years);
     if (show.M) head.push(parts.months);
     if (show.d) head.push(parts.days);
-    
+
     const hms = [pad2(parts.hours), pad2(parts.minutes), pad2(parts.seconds)];
-    if (!show.h) hms.shift(); // jeśli ukryte godziny, usuń
-    
+    if (!show.h) hms.shift();
+
     return [...head, hms.join(':')].join(' ');
   }
 
-  // Tryb: Intl.DurationFormat (jeśli dostępny)
   if (IntlCache.hasIDF) {
     const opts = { style: labelsMode === 'short' ? 'short' : 'long' };
     if (show.h) opts.hours = '2-digit';
     if (show.m) opts.minutes = '2-digit';
     if (show.s) opts.seconds = '2-digit';
 
-    // Przekazujemy tylko niezerowe/wymagane jednostki
     const inParts = {};
     for (const key in parts) {
-      // Mapowanie kluczy (years -> years) jest 1:1 w tym przypadku
       if (show[key.slice(0, 1)] || show[key.slice(0, 2)]) inParts[key] = parts[key];
     }
     return IntlCache.df(locale, opts).format(inParts);
   }
 
-  // Tryb: Fallback (słownikowy)
+  // Fallback
   const lang2 = LABELS[locale.slice(0, 2)] ? locale.slice(0, 2) : 'en';
   const L = LABELS[lang2];
   const pr = IntlCache.pr(locale);
@@ -195,20 +188,19 @@ function formatDurationSmart(locale, labelsMode, show, parts) {
 
 function getShowConfig(preset, diffMs) {
   const base = { y: false, M: false, d: true, h: true, m: true, s: true };
-  
+
   switch (preset) {
     case 'hms': return { ...base, d: false };
     case 'dhms': return base;
     case 'ydhms': return { y: true, M: true, d: true, h: true, m: true, s: true };
     case 'auto':
-      // Jeśli więcej niż 30 dni, pokaż dni.
       return diffMs >= 2592000000 ? base : { ...base, d: false };
     default: return base;
   }
 }
 
 /* ---------------- Web Component ---------------- */
-// Style współdzielone (wydajność pamięci)
+
 const sheet = new CSSStyleSheet();
 sheet.replaceSync(`
   :host {
@@ -218,13 +210,26 @@ sheet.replaceSync(`
     font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
     font-variant-numeric: tabular-nums;
     white-space: nowrap;
+    min-height: 1.2em;
+    line-height: 1.2;
   }
 `);
 
+/**
+ * A versatile countdown/uptimer Web Component that renders as selectable text.
+ * @element wc-timer
+ * @attr {string} target - The target date/time (ISO string or anything Date.parse accepts).
+ * @attr {string} [preset="auto"] - Display configuration ('auto', 'hms', 'dhms', 'ydhms', 'date').
+ * @attr {string} [labels="short"] - Label style ('none', 'short', 'long').
+ * @attr {boolean} [compact] - If set, hides high-order units that are zero.
+ * @attr {string} [locale] - Force a specific locale (e.g. 'pl', 'en-US').
+ * @example
+ * <wc-timer target="2025-01-01T00:00:00Z"></wc-timer>
+ * <wc-timer preset="dhms" labels="long" compact></wc-timer>
+ */
 class WcTimer extends HTMLElement {
   static get observedAttributes() { return ['target', 'preset', 'labels', 'locale', 'lang', 'compact']; }
-  
-  // Pola prywatne
+
   #target = new Date();
   #preset = 'auto';
   #labels = 'short';
@@ -242,10 +247,10 @@ class WcTimer extends HTMLElement {
   }
 
   connectedCallback() {
-    // Inicjalizacja węzła tekstowego w Light DOM
+    // Ensures element has dimensions before JS runs (CLS prevention)
     if (!this.firstChild || this.firstChild.nodeType !== Node.TEXT_NODE) {
       this.textContent = '';
-      this.#textNode = document.createTextNode('');
+      this.#textNode = document.createTextNode('\u00A0');
       this.appendChild(this.#textNode);
     } else {
       this.#textNode = this.firstChild;
@@ -262,10 +267,8 @@ class WcTimer extends HTMLElement {
   attributeChangedCallback() {
     if (this.#isAttrUpdate) return;
     this.#syncAttrs();
-    // Renderujemy natychmiast po zmianie atrybutu
     this.#render(Date.now());
-    // Jeśli zmieniono cel na przyszły, upewnij się, że zegar tyka
-    this.#checkRestart(); 
+    this.#checkRestart();
   }
 
   #syncAttrs() {
@@ -294,7 +297,6 @@ class WcTimer extends HTMLElement {
   }
 
   #checkRestart() {
-    // Jeśli mamy przyszły target, a zegar stoi -> wznów go
     const now = Date.now();
     if (this.#target > now && !this.#unsub) {
       this.#startTicking();
@@ -304,7 +306,6 @@ class WcTimer extends HTMLElement {
   #render(nowMs) {
     if (!this.#textNode) return;
 
-    // Tryb daty statycznej
     if (this.#preset === 'date') {
       const dtf = IntlCache.dtf(this.#locale, {
         year: 'numeric', month: '2-digit', day: '2-digit',
@@ -319,8 +320,7 @@ class WcTimer extends HTMLElement {
     const now = new Date(nowMs);
     const diff = this.#target - now;
     const isFuture = diff >= 0;
-    
-    // Auto-stop, jeśli minęliśmy czas
+
     if (!isFuture && this.#unsub) {
       this.#stopTicking();
     }
@@ -329,25 +329,31 @@ class WcTimer extends HTMLElement {
     const end = isFuture ? this.#target : now;
 
     let show = getShowConfig(this.#preset, Math.abs(diff));
-    
-    // Logika compact (ukrywanie zerowych jednostek wysokiego rzędu)
+
     if (this.#compact) {
       const probe = collapseForUnits(start, end, show);
       if (show.y && probe.years === 0) show.y = false;
       if (show.M && !show.y && probe.months === 0) show.M = false;
       if (show.d && !show.y && !show.M && probe.days === 0) show.d = false;
-      // Przelicz ponownie po redukcji jednostek
+
       const probe2 = collapseForUnits(start, end, show);
       if (show.d && show.h && probe2.hours === 0) show.h = false;
     }
 
     const parts = collapseForUnits(start, end, show);
-    const txt = formatDurationSmart(this.#locale, this.#labels, show, parts);
-    
+
+    let txt = formatDurationSmart(this.#locale, this.#labels, show, parts);
+    if (!txt) txt = '00:00:00';
+
     if (this.#textNode.data !== txt) this.#textNode.data = txt;
   }
 
   /* Public API */
+
+  /**
+   * The target date object.
+   * @type {Date}
+   */
   get target() { return new Date(this.#target); }
   set target(val) {
     const d = new Date(val);
@@ -358,6 +364,10 @@ class WcTimer extends HTMLElement {
     this.#checkRestart();
   }
 
+  /**
+   * Current preset configuration.
+   * @type {string} - 'auto' | 'hms' | 'dhms' | 'ydhms' | 'date'
+   */
   get preset() { return this.#preset; }
   set preset(val) {
     this.#preset = String(val).toLowerCase();
@@ -365,6 +375,10 @@ class WcTimer extends HTMLElement {
     this.#render(Date.now());
   }
 
+  /**
+   * Label display mode.
+   * @type {string} - 'none' | 'short' | 'long'
+   */
   get labels() { return this.#labels; }
   set labels(val) {
     this.#labels = String(val).toLowerCase();
@@ -372,16 +386,24 @@ class WcTimer extends HTMLElement {
     this.#render(Date.now());
   }
 
+  /**
+   * Whether compact mode is enabled (hides empty high units).
+   * @type {boolean}
+   */
   get compact() { return this.#compact; }
   set compact(val) {
     this.#compact = !!val;
     if (this.#compact) this.setAttribute('compact', '');
     else this.removeAttribute('compact');
-    this.#isAttrUpdate = true; // Flaga dla AttributeChanged
+    this.#isAttrUpdate = true;
     this.#render(Date.now());
     this.#isAttrUpdate = false;
   }
 
+  /**
+   * Current locale override.
+   * @type {string}
+   */
   set locale(val) {
     if (!val) return;
     this.#locale = String(val).toLowerCase();