@zero-studio/library 1.0.0

package/dist/ztl.cjs.js

@@ -0,0 +1,1148 @@
+/*!
+ * @zero-studio/library v1.0.0
+ * ZERO Technology Library — A futuristic, modular UI component library for the modern web. 150+ libraries, 500+ components.
+ * (c) 2026 ZERO | MIT License
+ * https://docs.zero-tech.dev
+ */
+'use strict';
+/*!
+ * ZERO Technology Library (ZTL) v1.0.0
+ * MIT License — https://zero-tech.dev
+ * @author ZERO
+ */
+
+'use strict';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CONSTANTS & DEFAULTS
+// ─────────────────────────────────────────────────────────────────────────────
+const ZTL_VERSION = '1.0.0';
+
+const DEFAULTS = {
+  theme:    'dark',
+  accent:   '#00f5a0',
+  rtl:      false,
+  lang:     'en',
+  toastPosition: 'br', // bl | br | tl | tr | tc
+  toastDuration: 4000,
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// UTILS
+// ─────────────────────────────────────────────────────────────────────────────
+const $ = (selector, context = document) => context.querySelector(selector);
+const $$ = (selector, context = document) => [...context.querySelectorAll(selector)];
+
+function uid() {
+  return 'ztl-' + Math.random().toString(36).slice(2, 9);
+}
+
+function merge(...objects) {
+  return Object.assign({}, ...objects);
+}
+
+function emit(el, eventName, detail = {}) {
+  el.dispatchEvent(new CustomEvent(`ztl:${eventName}`, { bubbles: true, detail }));
+}
+
+function onClickOutside(el, callback) {
+  const handler = (e) => {
+    if (!el.contains(e.target)) {
+      callback(e);
+      document.removeEventListener('click', handler);
+    }
+  };
+  setTimeout(() => document.addEventListener('click', handler), 0);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// i18n — INTERNATIONALIZATION
+// English (primary) + Arabic (secondary)
+// ─────────────────────────────────────────────────────────────────────────────
+const i18n = {
+  en: {
+    close:      'Close',
+    confirm:    'Confirm',
+    cancel:     'Cancel',
+    ok:         'OK',
+    copy:       'Copy',
+    copied:     'Copied!',
+    loading:    'Loading…',
+    noData:     'No data available',
+    error:      'An error occurred',
+    success:    'Success',
+    warning:    'Warning',
+    info:       'Info',
+    required:   'This field is required',
+    minLength:  (n) => `Minimum ${n} characters`,
+    maxLength:  (n) => `Maximum ${n} characters`,
+    invalid:    'Invalid input',
+    search:     'Search…',
+    prev:       'Previous',
+    next:       'Next',
+    showing:    (from, to, total) => `Showing ${from}–${to} of ${total}`,
+    deleteConfirm: 'Are you sure? This action cannot be undone.',
+    uploadDrop:    'Drop files here or click to browse',
+    uploadLimit:   (mb) => `Max file size: ${mb}MB`,
+  },
+  ar: {
+    close:      'إغلاق',
+    confirm:    'تأكيد',
+    cancel:     'إلغاء',
+    ok:         'موافق',
+    copy:       'نسخ',
+    copied:     'تم النسخ!',
+    loading:    'جارٍ التحميل…',
+    noData:     'لا توجد بيانات',
+    error:      'حدث خطأ',
+    success:    'تم بنجاح',
+    warning:    'تحذير',
+    info:       'معلومة',
+    required:   'هذا الحقل مطلوب',
+    minLength:  (n) => `الحد الأدنى ${n} أحرف`,
+    maxLength:  (n) => `الحد الأقصى ${n} حرف`,
+    invalid:    'مدخل غير صالح',
+    search:     'بحث…',
+    prev:       'السابق',
+    next:       'التالي',
+    showing:    (from, to, total) => `عرض ${from}–${to} من ${total}`,
+    deleteConfirm: 'هل أنت متأكد؟ لا يمكن التراجع عن هذا الإجراء.',
+    uploadDrop:    'أسقط الملفات هنا أو اضغط للتصفح',
+    uploadLimit:   (mb) => `الحجم الأقصى: ${mb} ميغابايت`,
+  },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TOAST MANAGER
+// ─────────────────────────────────────────────────────────────────────────────
+class ToastManager {
+  constructor(position = 'br', lang = 'en') {
+    this._lang = lang;
+    this._stack = this._createStack(position);
+    document.body.appendChild(this._stack);
+  }
+
+  _createStack(position) {
+    const el = document.createElement('div');
+    el.className = `ztl-toast-stack ztl-toast-stack-${position}`;
+    el.setAttribute('aria-live', 'polite');
+    el.setAttribute('aria-atomic', 'false');
+    return el;
+  }
+
+  /**
+   * Show a toast notification.
+   * @param {string} message
+   * @param {'success'|'danger'|'warning'|'info'} type
+   * @param {Object} [options]
+   * @param {number}  [options.duration=4000]
+   * @param {string}  [options.icon]
+   * @param {boolean} [options.closable=true]
+   */
+  show(message, type = 'info', options = {}) {
+    const opts = merge({ duration: DEFAULTS.toastDuration, closable: true }, options);
+    const iconMap = { success: '✅', danger: '❌', warning: '⚠️', info: 'ℹ️' };
+    const icon = opts.icon || iconMap[type] || 'ℹ️';
+
+    const toast = document.createElement('div');
+    toast.className = `ztl-toast ztl-toast-${type}`;
+    toast.setAttribute('role', 'alert');
+    toast.innerHTML = `
+      <span class="ztl-toast-icon" aria-hidden="true">${icon}</span>
+      <span class="ztl-toast-text">${message}</span>
+      ${opts.closable ? `<button class="ztl-toast-close" aria-label="${i18n[this._lang]?.close || i18n.en.close}">✕</button>` : ''}
+    `;
+
+    this._stack.appendChild(toast);
+
+    if (opts.closable) {
+      $('.ztl-toast-close', toast).addEventListener('click', () => this._remove(toast));
+    }
+
+    const timer = setTimeout(() => this._remove(toast), opts.duration);
+    toast._timer = timer;
+
+    // Pause on hover
+    toast.addEventListener('mouseenter', () => clearTimeout(toast._timer));
+    toast.addEventListener('mouseleave', () => {
+      toast._timer = setTimeout(() => this._remove(toast), opts.duration / 2);
+    });
+
+    emit(this._stack, 'toast:show', { message, type });
+    return toast;
+  }
+
+  _remove(toast) {
+    if (!toast.parentNode) return;
+    toast.classList.add('ztl-removing');
+    toast.addEventListener('animationend', () => toast.remove(), { once: true });
+    setTimeout(() => toast.remove(), 400);
+  }
+
+  success(msg, opts) { return this.show(msg, 'success', opts); }
+  danger(msg, opts)  { return this.show(msg, 'danger', opts); }
+  warning(msg, opts) { return this.show(msg, 'warning', opts); }
+  info(msg, opts)    { return this.show(msg, 'info', opts); }
+  clear()            { $$('.ztl-toast', this._stack).forEach(t => this._remove(t)); }
+
+  destroy() { this._stack.remove(); }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MODAL
+// ─────────────────────────────────────────────────────────────────────────────
+class Modal {
+  /**
+   * @param {Object} options
+   * @param {string}   [options.title]
+   * @param {string}   [options.body]
+   * @param {string}   [options.size=''] - sm | lg | xl | full
+   * @param {boolean}  [options.closable=true]
+   * @param {Function} [options.onConfirm]
+   * @param {Function} [options.onCancel]
+   * @param {string}   [options.confirmLabel]
+   * @param {string}   [options.cancelLabel]
+   * @param {string}   [options.lang='en']
+   */
+  constructor(options = {}) {
+    this._opts = merge({
+      title: '', body: '', size: '', closable: true,
+      onConfirm: null, onCancel: null,
+      confirmLabel: null, cancelLabel: null,
+      lang: 'en',
+    }, options);
+
+    this._t = i18n[this._opts.lang] || i18n.en;
+    this._el = this._build();
+    document.body.appendChild(this._el);
+    this._bindEvents();
+  }
+
+  _build() {
+    const sizeClass = this._opts.size ? `ztl-modal-${this._opts.size}` : '';
+    const overlay = document.createElement('div');
+    overlay.className = 'ztl-overlay';
+    overlay.setAttribute('role', 'dialog');
+    overlay.setAttribute('aria-modal', 'true');
+    overlay.setAttribute('aria-labelledby', 'ztl-modal-title');
+
+    overlay.innerHTML = `
+      <div class="ztl-modal ${sizeClass}">
+        ${this._opts.title ? `
+          <div class="ztl-modal-header">
+            <span class="ztl-modal-title" id="ztl-modal-title">${this._opts.title}</span>
+            ${this._opts.closable ? `<button class="ztl-btn ztl-btn-ghost ztl-btn-sm ztl-modal-close-btn" aria-label="${this._t.close}">✕</button>` : ''}
+          </div>` : ''}
+        <div class="ztl-modal-body">${this._opts.body}</div>
+        ${(this._opts.onConfirm || this._opts.cancelLabel) ? `
+          <div class="ztl-modal-footer">
+            <button class="ztl-btn ztl-btn-ghost ztl-btn-sm ztl-modal-cancel-btn">${this._opts.cancelLabel || this._t.cancel}</button>
+            <button class="ztl-btn ztl-btn-primary ztl-btn-sm ztl-modal-confirm-btn">${this._opts.confirmLabel || this._t.confirm}</button>
+          </div>` : ''}
+      </div>
+    `;
+    return overlay;
+  }
+
+  _bindEvents() {
+    // Close on overlay click
+    this._el.addEventListener('click', (e) => {
+      if (e.target === this._el && this._opts.closable) this.close();
+    });
+
+    // Close button
+    const closeBtn = $('.ztl-modal-close-btn', this._el);
+    if (closeBtn) closeBtn.addEventListener('click', () => this.close());
+
+    // Cancel
+    const cancelBtn = $('.ztl-modal-cancel-btn', this._el);
+    if (cancelBtn) cancelBtn.addEventListener('click', () => {
+      if (this._opts.onCancel) this._opts.onCancel();
+      this.close();
+    });
+
+    // Confirm
+    const confirmBtn = $('.ztl-modal-confirm-btn', this._el);
+    if (confirmBtn) confirmBtn.addEventListener('click', () => {
+      if (this._opts.onConfirm) this._opts.onConfirm();
+      this.close();
+    });
+
+    // Escape key
+    this._keyHandler = (e) => { if (e.key === 'Escape' && this._opts.closable) this.close(); };
+    document.addEventListener('keydown', this._keyHandler);
+  }
+
+  open() {
+    this._el.classList.add('ztl-open');
+    document.body.style.overflow = 'hidden';
+    emit(this._el, 'modal:open');
+    return this;
+  }
+
+  close() {
+    this._el.classList.remove('ztl-open');
+    document.body.style.overflow = '';
+    document.removeEventListener('keydown', this._keyHandler);
+    emit(this._el, 'modal:close');
+    return this;
+  }
+
+  destroy() {
+    this.close();
+    setTimeout(() => this._el.remove(), 300);
+  }
+
+  setBody(html) {
+    $('.ztl-modal-body', this._el).innerHTML = html;
+    return this;
+  }
+
+  setTitle(text) {
+    const t = $('#ztl-modal-title', this._el);
+    if (t) t.textContent = text;
+    return this;
+  }
+}
+
+// Shorthand: confirm dialog
+Modal.confirm = function(message, opts = {}) {
+  return new Promise((resolve) => {
+    const m = new Modal(merge({
+      title: opts.title || (i18n[opts.lang || 'en'] || i18n.en).confirm,
+      body: `<p style="color:var(--ztl-text-muted);font-size:14px;line-height:1.7">${message}</p>`,
+      size: 'sm',
+      onConfirm: () => { resolve(true); m.destroy(); },
+      onCancel:  () => { resolve(false); m.destroy(); },
+      ...opts,
+    }));
+    m.open();
+  });
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DROPDOWN
+// ─────────────────────────────────────────────────────────────────────────────
+class Dropdown {
+  /**
+   * @param {HTMLElement} trigger
+   * @param {HTMLElement|string} menu - element or CSS selector
+   */
+  constructor(trigger, menu) {
+    this._trigger = typeof trigger === 'string' ? $(trigger) : trigger;
+    this._menu    = typeof menu === 'string' ? $(menu) : menu;
+    this._parent  = this._trigger.closest('.ztl-dropdown') || this._trigger.parentElement;
+    this._bindEvents();
+  }
+
+  _bindEvents() {
+    this._trigger.addEventListener('click', (e) => {
+      e.stopPropagation();
+      this.isOpen() ? this.close() : this.open();
+    });
+  }
+
+  isOpen()  { return this._parent.classList.contains('ztl-open'); }
+
+  open() {
+    this._parent.classList.add('ztl-open');
+    this._trigger.setAttribute('aria-expanded', 'true');
+    emit(this._parent, 'dropdown:open');
+    onClickOutside(this._parent, () => this.close());
+  }
+
+  close() {
+    this._parent.classList.remove('ztl-open');
+    this._trigger.setAttribute('aria-expanded', 'false');
+    emit(this._parent, 'dropdown:close');
+  }
+
+  toggle() { this.isOpen() ? this.close() : this.open(); }
+  destroy() { /* cleanup if needed */ }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TABS
+// ─────────────────────────────────────────────────────────────────────────────
+class Tabs {
+  /**
+   * @param {HTMLElement|string} container
+   * @param {Object} [options]
+   * @param {Function} [options.onChange]
+   */
+  constructor(container, options = {}) {
+    this._el   = typeof container === 'string' ? $(container) : container;
+    this._opts = merge({ onChange: null }, options);
+    this._init();
+  }
+
+  _init() {
+    this._buttons = $$('.ztl-tab-btn', this._el);
+    this._panels  = $$('.ztl-tab-panel', this._el);
+
+    this._buttons.forEach((btn, i) => {
+      btn.setAttribute('role', 'tab');
+      btn.setAttribute('aria-selected', btn.classList.contains('ztl-active'));
+      btn.addEventListener('click', () => this.activate(i));
+    });
+
+    this._panels.forEach((panel) => {
+      panel.setAttribute('role', 'tabpanel');
+    });
+  }
+
+  activate(index) {
+    const prev = this._buttons.findIndex(b => b.classList.contains('ztl-active'));
+
+    this._buttons.forEach((btn, i) => {
+      btn.classList.toggle('ztl-active', i === index);
+      btn.setAttribute('aria-selected', i === index);
+    });
+
+    this._panels.forEach((panel, i) => {
+      panel.classList.toggle('ztl-active', i === index);
+    });
+
+    if (this._opts.onChange) this._opts.onChange(index, prev);
+    emit(this._el, 'tabs:change', { index, prev });
+  }
+
+  getActive() {
+    return this._buttons.findIndex(b => b.classList.contains('ztl-active'));
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PROGRESS BAR
+// ─────────────────────────────────────────────────────────────────────────────
+class ProgressBar {
+  /**
+   * @param {HTMLElement|string} element - the .ztl-progress-fill element
+   * @param {Object} [options]
+   * @param {number} [options.value=0]
+   * @param {number} [options.min=0]
+   * @param {number} [options.max=100]
+   * @param {boolean} [options.animate=true]
+   */
+  constructor(element, options = {}) {
+    this._el   = typeof element === 'string' ? $(element) : element;
+    this._opts = merge({ value: 0, min: 0, max: 100, animate: true }, options);
+    this.set(this._opts.value);
+  }
+
+  set(value) {
+    const clamped = Math.max(this._opts.min, Math.min(this._opts.max, value));
+    const pct = ((clamped - this._opts.min) / (this._opts.max - this._opts.min)) * 100;
+    this._el.style.width = `${pct}%`;
+    this._el.setAttribute('aria-valuenow', clamped);
+    this._current = clamped;
+    emit(this._el, 'progress:change', { value: clamped, percent: pct });
+    return this;
+  }
+
+  increment(by = 1) { return this.set(this._current + by); }
+  decrement(by = 1) { return this.set(this._current - by); }
+  complete()        { return this.set(this._opts.max); }
+  reset()           { return this.set(this._opts.min); }
+  get value()       { return this._current; }
+
+  /**
+   * Animate progress from current to target value.
+   * @param {number} target
+   * @param {number} [duration=800] ms
+   */
+  animateTo(target, duration = 800) {
+    const start = this._current;
+    const diff  = target - start;
+    const begin = performance.now();
+
+    const step = (now) => {
+      const elapsed = now - begin;
+      const progress = Math.min(elapsed / duration, 1);
+      const ease = 1 - Math.pow(1 - progress, 3); // ease-out-cubic
+      this.set(start + diff * ease);
+      if (progress < 1) requestAnimationFrame(step);
+    };
+
+    requestAnimationFrame(step);
+    return this;
+  }
+}
+
+// Circular progress
+class CircularProgress {
+  /**
+   * @param {HTMLElement|string} container  - .ztl-progress-circle
+   * @param {Object} options
+   * @param {number} [options.value=0]
+   * @param {number} [options.size=80]
+   * @param {number} [options.strokeWidth=6]
+   * @param {string} [options.color]
+   */
+  constructor(container, options = {}) {
+    this._el   = typeof container === 'string' ? $(container) : container;
+    this._opts = merge({ value: 0, size: 80, strokeWidth: 6, color: 'var(--ztl-accent)' }, options);
+    this._init();
+  }
+
+  _init() {
+    const { size, strokeWidth } = this._opts;
+    const r = (size / 2) - strokeWidth;
+    const circ = 2 * Math.PI * r;
+    this._circ = circ;
+    this._r    = r;
+
+    this._el.style.width  = size + 'px';
+    this._el.style.height = size + 'px';
+
+    this._el.innerHTML = `
+      <svg viewBox="0 0 ${size} ${size}" width="${size}" height="${size}">
+        <circle class="ztl-progress-circle-track" cx="${size/2}" cy="${size/2}" r="${r}" stroke-width="${strokeWidth}"/>
+        <circle class="ztl-progress-circle-fill"  cx="${size/2}" cy="${size/2}" r="${r}" stroke-width="${strokeWidth}"
+          stroke="${this._opts.color}"
+          stroke-dasharray="${circ}"
+          stroke-dashoffset="${circ}"/>
+      </svg>
+      <span class="ztl-progress-circle-label">0%</span>
+    `;
+
+    this._fill  = $('circle.ztl-progress-circle-fill', this._el);
+    this._label = $('.ztl-progress-circle-label', this._el);
+    this.set(this._opts.value);
+  }
+
+  set(value) {
+    const clamped = Math.max(0, Math.min(100, value));
+    const offset  = this._circ * (1 - clamped / 100);
+    this._fill.style.strokeDashoffset = offset;
+    this._label.textContent = `${Math.round(clamped)}%`;
+    this._current = clamped;
+    return this;
+  }
+
+  animateTo(target, duration = 800) {
+    const start = this._current || 0;
+    const diff  = target - start;
+    const begin = performance.now();
+    const step  = (now) => {
+      const p = Math.min((now - begin) / duration, 1);
+      this.set(start + diff * (1 - Math.pow(1 - p, 3)));
+      if (p < 1) requestAnimationFrame(step);
+    };
+    requestAnimationFrame(step);
+    return this;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TOOLTIP (programmatic)
+// ─────────────────────────────────────────────────────────────────────────────
+class Tooltip {
+  /**
+   * @param {HTMLElement|string} element
+   * @param {string} text
+   * @param {'top'|'bottom'|'left'|'right'} [position='top']
+   */
+  constructor(element, text, position = 'top') {
+    this._el = typeof element === 'string' ? $(element) : element;
+    this._el.setAttribute('data-ztl-tip', text);
+    if (position !== 'top') this._el.setAttribute('data-ztl-tip-pos', position);
+  }
+
+  update(text) { this._el.setAttribute('data-ztl-tip', text); return this; }
+
+  destroy() {
+    this._el.removeAttribute('data-ztl-tip');
+    this._el.removeAttribute('data-ztl-tip-pos');
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// FORM VALIDATOR
+// ─────────────────────────────────────────────────────────────────────────────
+class FormValidator {
+  /**
+   * @param {HTMLFormElement|string} form
+   * @param {Object} rules  - { fieldName: [...rules] }
+   * @param {Object} [options]
+   * @param {string} [options.lang='en']
+   */
+  constructor(form, rules, options = {}) {
+    this._form  = typeof form === 'string' ? $(form) : form;
+    this._rules = rules;
+    this._opts  = merge({ lang: 'en', onSubmit: null }, options);
+    this._t     = i18n[this._opts.lang] || i18n.en;
+    this._errors = {};
+    this._bindEvents();
+  }
+
+  _bindEvents() {
+    this._form.setAttribute('novalidate', '');
+    this._form.addEventListener('submit', (e) => {
+      e.preventDefault();
+      const valid = this.validate();
+      if (valid && this._opts.onSubmit) {
+        this._opts.onSubmit(this.getValues(), e);
+      }
+    });
+
+    // Live validation
+    $$('input, select, textarea', this._form).forEach(el => {
+      el.addEventListener('blur', () => this._validateField(el.name || el.id, el.value));
+    });
+  }
+
+  _validateField(name, value) {
+    const rules  = this._rules[name];
+    if (!rules) return true;
+
+    const errors = [];
+
+    rules.forEach(rule => {
+      if (rule === 'required' && !value.trim()) {
+        errors.push(this._t.required);
+      }
+      if (rule.type === 'minLength' && value.length < rule.value) {
+        errors.push(this._t.minLength(rule.value));
+      }
+      if (rule.type === 'maxLength' && value.length > rule.value) {
+        errors.push(this._t.maxLength(rule.value));
+      }
+      if (rule.type === 'pattern' && !rule.value.test(value)) {
+        errors.push(rule.message || this._t.invalid);
+      }
+      if (rule.type === 'email' && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
+        errors.push(this._t.invalid);
+      }
+      if (rule.type === 'custom') {
+        const result = rule.validate(value);
+        if (result !== true) errors.push(result || this._t.invalid);
+      }
+    });
+
+    this._setFieldError(name, errors[0] || null);
+    return errors.length === 0;
+  }
+
+  _setFieldError(name, message) {
+    const field = this._form.querySelector(`[name="${name}"], #${name}`);
+    if (!field) return;
+
+    const wrap = field.closest('.ztl-field') || field.parentElement;
+    let errorEl = wrap.querySelector('.ztl-field-error');
+
+    if (message) {
+      field.classList.add('ztl-input-error');
+      field.classList.remove('ztl-input-success');
+      if (!errorEl) {
+        errorEl = document.createElement('span');
+        errorEl.className = 'ztl-field-error';
+        wrap.appendChild(errorEl);
+      }
+      errorEl.textContent = message;
+      this._errors[name] = message;
+    } else {
+      field.classList.remove('ztl-input-error');
+      field.classList.add('ztl-input-success');
+      if (errorEl) errorEl.remove();
+      delete this._errors[name];
+    }
+  }
+
+  validate() {
+    let valid = true;
+    Object.entries(this._rules).forEach(([name]) => {
+      const field = this._form.querySelector(`[name="${name}"], #${name}`);
+      if (field && !this._validateField(name, field.value)) valid = false;
+    });
+    emit(this._form, 'validate', { valid, errors: this._errors });
+    return valid;
+  }
+
+  getValues() {
+    const data = {};
+    new FormData(this._form).forEach((val, key) => { data[key] = val; });
+    return data;
+  }
+
+  clearErrors() {
+    $$('.ztl-field-error', this._form).forEach(el => el.remove());
+    $$('.ztl-input-error, .ztl-input-success', this._form).forEach(el => {
+      el.classList.remove('ztl-input-error', 'ztl-input-success');
+    });
+    this._errors = {};
+  }
+
+  setErrors(errors) {
+    Object.entries(errors).forEach(([name, msg]) => this._setFieldError(name, msg));
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TAGS / CHIPS INPUT
+// ─────────────────────────────────────────────────────────────────────────────
+class TagInput {
+  /**
+   * @param {HTMLElement|string} container - .ztl-tag-input-wrap
+   * @param {Object} [options]
+   * @param {string[]} [options.initial=[]]
+   * @param {number}   [options.max=Infinity]
+   * @param {Function} [options.onChange]
+   * @param {Function} [options.onAdd]
+   * @param {Function} [options.onRemove]
+   */
+  constructor(container, options = {}) {
+    this._el   = typeof container === 'string' ? $(container) : container;
+    this._opts = merge({ initial: [], max: Infinity, onChange: null, onAdd: null, onRemove: null }, options);
+    this._tags = [...this._opts.initial];
+    this._input = document.createElement('input');
+    this._input.placeholder = '+ Add tag';
+    this._el.appendChild(this._input);
+    this._renderAll();
+    this._bindEvents();
+  }
+
+  _renderAll() {
+    $$('.ztl-tag', this._el).forEach(t => t.remove());
+    this._tags.forEach(tag => this._renderTag(tag));
+    this._el.appendChild(this._input);
+  }
+
+  _renderTag(text) {
+    const tag = document.createElement('span');
+    tag.className = 'ztl-tag ztl-tag-removable';
+    tag.innerHTML = `${text} <span class="ztl-tag-remove" aria-label="Remove ${text}">×</span>`;
+    tag.querySelector('.ztl-tag-remove').addEventListener('click', () => this.remove(text));
+    this._el.insertBefore(tag, this._input);
+  }
+
+  _bindEvents() {
+    this._input.addEventListener('keydown', (e) => {
+      if ((e.key === 'Enter' || e.key === ',') && this._input.value.trim()) {
+        e.preventDefault();
+        this.add(this._input.value.trim().replace(/,$/, ''));
+        this._input.value = '';
+      }
+      if (e.key === 'Backspace' && !this._input.value && this._tags.length) {
+        this.remove(this._tags[this._tags.length - 1]);
+      }
+    });
+
+    this._el.addEventListener('click', () => this._input.focus());
+  }
+
+  add(text) {
+    if (this._tags.includes(text) || this._tags.length >= this._opts.max) return this;
+    this._tags.push(text);
+    this._renderTag(text);
+    if (this._opts.onAdd) this._opts.onAdd(text, this._tags);
+    if (this._opts.onChange) this._opts.onChange(this._tags);
+    emit(this._el, 'tag:add', { tag: text, tags: this._tags });
+    return this;
+  }
+
+  remove(text) {
+    this._tags = this._tags.filter(t => t !== text);
+    this._renderAll();
+    if (this._opts.onRemove) this._opts.onRemove(text, this._tags);
+    if (this._opts.onChange) this._opts.onChange(this._tags);
+    emit(this._el, 'tag:remove', { tag: text, tags: this._tags });
+    return this;
+  }
+
+  getTags()  { return [...this._tags]; }
+  clear()    { this._tags = []; this._renderAll(); return this; }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// COPY TO CLIPBOARD
+// ─────────────────────────────────────────────────────────────────────────────
+function copyToClipboard(text, lang = 'en') {
+  const t = i18n[lang] || i18n.en;
+  return navigator.clipboard.writeText(text).then(() => {
+    emit(document, 'clipboard:copy', { text });
+    return { success: true, message: t.copied };
+  }).catch(() => {
+    // fallback for older browsers
+    const ta = document.createElement('textarea');
+    ta.value = text;
+    ta.style.cssText = 'position:fixed;opacity:0;top:0;left:0';
+    document.body.appendChild(ta);
+    ta.focus();
+    ta.select();
+    try { document.execCommand('copy'); return { success: true, message: t.copied }; }
+    catch { return { success: false, message: 'Copy failed' }; }
+    finally { ta.remove(); }
+  });
+}
+
+// Auto-bind copy buttons
+function initCopyButtons(lang = 'en') {
+  $$('[data-ztl-copy]').forEach(btn => {
+    btn.addEventListener('click', async () => {
+      const target = btn.getAttribute('data-ztl-copy');
+      const text = target
+        ? ($(target) ? $(target).textContent : target)
+        : btn.textContent;
+
+      const result = await copyToClipboard(text, lang);
+      const original = btn.textContent;
+      btn.textContent = result.message;
+      btn.disabled = true;
+      setTimeout(() => { btn.textContent = original; btn.disabled = false; }, 2000);
+    });
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SCROLL REVEAL
+// ─────────────────────────────────────────────────────────────────────────────
+function initScrollReveal(selector = '[data-ztl-reveal]') {
+  if (!('IntersectionObserver' in window)) return;
+
+  const observer = new IntersectionObserver((entries) => {
+    entries.forEach(entry => {
+      if (entry.isIntersecting) {
+        const el = entry.target;
+        const animation = el.getAttribute('data-ztl-reveal') || 'slide-up';
+        el.classList.add(`ztl-animate-${animation}`);
+        el.style.opacity = '1';
+        observer.unobserve(el);
+      }
+    });
+  }, { threshold: 0.15 });
+
+  $$(selector).forEach(el => {
+    el.style.opacity = '0';
+    observer.observe(el);
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// COUNTER ANIMATION
+// ─────────────────────────────────────────────────────────────────────────────
+function animateCounter(el, target, options = {}) {
+  const opts = merge({ duration: 1200, prefix: '', suffix: '', decimals: 0 }, options);
+  const start   = parseFloat(el.textContent) || 0;
+  const diff    = target - start;
+  const begin   = performance.now();
+
+  const step = (now) => {
+    const elapsed  = now - begin;
+    const progress = Math.min(elapsed / opts.duration, 1);
+    const ease     = 1 - Math.pow(1 - progress, 3);
+    const current  = start + diff * ease;
+    el.textContent = opts.prefix + current.toFixed(opts.decimals) + opts.suffix;
+    if (progress < 1) requestAnimationFrame(step);
+    else el.textContent = opts.prefix + target.toFixed(opts.decimals) + opts.suffix;
+  };
+
+  requestAnimationFrame(step);
+}
+
+// Init counter elements automatically
+function initCounters(selector = '[data-ztl-count]') {
+  if (!('IntersectionObserver' in window)) return;
+
+  const observer = new IntersectionObserver((entries) => {
+    entries.forEach(entry => {
+      if (entry.isIntersecting) {
+        const el      = entry.target;
+        const target  = parseFloat(el.getAttribute('data-ztl-count'));
+        const suffix  = el.getAttribute('data-ztl-suffix') || '';
+        const prefix  = el.getAttribute('data-ztl-prefix') || '';
+        const duration = parseInt(el.getAttribute('data-ztl-duration') || 1200);
+        animateCounter(el, target, { suffix, prefix, duration });
+        observer.unobserve(el);
+      }
+    });
+  }, { threshold: 0.5 });
+
+  $$(selector).forEach(el => observer.observe(el));
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// THEME MANAGER
+// ─────────────────────────────────────────────────────────────────────────────
+class ThemeManager {
+  constructor(options = {}) {
+    this._opts = merge({ storageKey: 'ztl-theme', default: 'dark' }, options);
+    this._current = localStorage.getItem(this._opts.storageKey) || this._opts.default;
+    this.apply(this._current);
+  }
+
+  apply(theme) {
+    document.documentElement.setAttribute('data-ztl-theme', theme);
+    this._current = theme;
+    localStorage.setItem(this._opts.storageKey, theme);
+    emit(document, 'theme:change', { theme });
+  }
+
+  toggle() {
+    this.apply(this._current === 'dark' ? 'light' : 'dark');
+  }
+
+  setAccent(color) {
+    document.documentElement.style.setProperty('--ztl-accent', color);
+    emit(document, 'theme:accent', { color });
+  }
+
+  get current() { return this._current; }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SKELETON LOADER HELPER
+// ─────────────────────────────────────────────────────────────────────────────
+function skeleton(container, count = 3) {
+  const el = typeof container === 'string' ? $(container) : container;
+  el.innerHTML = Array(count).fill(`
+    <div style="display:flex;flex-direction:column;gap:8px;margin-bottom:16px">
+      <div class="ztl-skeleton ztl-skeleton-title" style="width:${40 + Math.random() * 30}%"></div>
+      <div class="ztl-skeleton ztl-skeleton-text"></div>
+      <div class="ztl-skeleton ztl-skeleton-text" style="width:80%"></div>
+    </div>
+  `).join('');
+
+  return {
+    clear: () => { el.innerHTML = ''; },
+    replace: (html) => { el.innerHTML = html; },
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DATA TABLE (Simple)
+// ─────────────────────────────────────────────────────────────────────────────
+class DataTable {
+  /**
+   * @param {HTMLElement|string} container
+   * @param {Object} options
+   * @param {Array<{key,label,sortable?,render?}>} options.columns
+   * @param {Array<Object>}  options.data
+   * @param {number}         [options.pageSize=10]
+   * @param {boolean}        [options.searchable=true]
+   * @param {string}         [options.lang='en']
+   */
+  constructor(container, options) {
+    this._el   = typeof container === 'string' ? $(container) : container;
+    this._opts = merge({ pageSize: 10, searchable: true, lang: 'en' }, options);
+    this._t    = i18n[this._opts.lang] || i18n.en;
+    this._data = [...this._opts.data];
+    this._filtered  = [...this._data];
+    this._page      = 1;
+    this._sortKey   = null;
+    this._sortDir   = 'asc';
+    this._render();
+  }
+
+  _render() {
+    const { pageSize } = this._opts;
+    const start = (this._page - 1) * pageSize;
+    const rows  = this._filtered.slice(start, start + pageSize);
+    const total = this._filtered.length;
+    const pages = Math.ceil(total / pageSize);
+
+    this._el.innerHTML = `
+      ${this._opts.searchable ? `
+        <div class="ztl-search-wrap" style="margin-bottom:12px">
+          <span class="ztl-search-icon">🔍</span>
+          <input class="ztl-input ztl-table-search" placeholder="${this._t.search}" value="${this._searchQuery || ''}">
+        </div>` : ''}
+      <div class="ztl-table-wrap">
+        <table class="ztl-table">
+          <thead>
+            <tr>${this._opts.columns.map(col => `
+              <th ${col.sortable ? `data-sort="${col.key}" style="cursor:pointer"` : ''}>
+                ${col.label}${this._sortKey === col.key ? (this._sortDir === 'asc' ? ' ↑' : ' ↓') : ''}
+              </th>`).join('')}
+            </tr>
+          </thead>
+          <tbody>
+            ${rows.length ? rows.map(row => `
+              <tr>${this._opts.columns.map(col => `
+                <td>${col.render ? col.render(row[col.key], row) : (row[col.key] ?? '—')}</td>`).join('')}
+              </tr>`).join('')
+            : `<tr><td colspan="${this._opts.columns.length}" style="text-align:center;color:var(--ztl-text-muted);padding:32px">${this._t.noData}</td></tr>`}
+          </tbody>
+        </table>
+      </div>
+      ${pages > 1 ? `
+        <div style="display:flex;align-items:center;justify-content:space-between;margin-top:12px;font-size:12px;color:var(--ztl-text-muted)">
+          <span>${this._t.showing(start + 1, Math.min(start + pageSize, total), total)}</span>
+          <div style="display:flex;gap:6px">
+            <button class="ztl-btn ztl-btn-ghost ztl-btn-sm ztl-dt-prev" ${this._page <= 1 ? 'disabled' : ''}>${this._t.prev}</button>
+            <button class="ztl-btn ztl-btn-ghost ztl-btn-sm ztl-dt-next" ${this._page >= pages ? 'disabled' : ''}>${this._t.next}</button>
+          </div>
+        </div>` : ''}
+    `;
+
+    this._bindTableEvents();
+  }
+
+  _bindTableEvents() {
+    // Search
+    const searchEl = $('.ztl-table-search', this._el);
+    if (searchEl) {
+      searchEl.addEventListener('input', (e) => {
+        this._searchQuery = e.target.value.toLowerCase();
+        this._filtered = this._data.filter(row =>
+          Object.values(row).some(v => String(v).toLowerCase().includes(this._searchQuery))
+        );
+        this._page = 1;
+        this._render();
+      });
+    }
+
+    // Sorting
+    $$('[data-sort]', this._el).forEach(th => {
+      th.addEventListener('click', () => {
+        const key = th.getAttribute('data-sort');
+        this._sortDir = this._sortKey === key && this._sortDir === 'asc' ? 'desc' : 'asc';
+        this._sortKey = key;
+        this._filtered.sort((a, b) => {
+          const av = a[key], bv = b[key];
+          return this._sortDir === 'asc'
+            ? (av > bv ? 1 : av < bv ? -1 : 0)
+            : (av < bv ? 1 : av > bv ? -1 : 0);
+        });
+        this._render();
+      });
+    });
+
+    // Pagination
+    const prev = $('.ztl-dt-prev', this._el);
+    const next = $('.ztl-dt-next', this._el);
+    if (prev) prev.addEventListener('click', () => { this._page--; this._render(); });
+    if (next) next.addEventListener('click', () => { this._page++; this._render(); });
+  }
+
+  update(data) {
+    this._data     = [...data];
+    this._filtered = [...data];
+    this._page     = 1;
+    this._render();
+    return this;
+  }
+
+  setPage(page) { this._page = page; this._render(); return this; }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AUTO-INIT (data-ztl-* attributes)
+// ─────────────────────────────────────────────────────────────────────────────
+function autoInit() {
+  // Tabs
+  $$('[data-ztl="tabs"]').forEach(el => new Tabs(el));
+
+  // Dropdowns
+  $$('[data-ztl="dropdown"]').forEach(wrapper => {
+    const trigger = $('[data-ztl-trigger]', wrapper) || wrapper.firstElementChild;
+    new Dropdown(trigger, wrapper);
+  });
+
+  // Scroll reveal
+  initScrollReveal();
+
+  // Counters
+  initCounters();
+
+  // Copy buttons
+  initCopyButtons();
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MAIN ZTL OBJECT
+// ─────────────────────────────────────────────────────────────────────────────
+const ZTL = {
+  version: ZTL_VERSION,
+
+  /**
+   * Initialize the library.
+   * @param {Object} [config]
+   * @param {string}  [config.theme='dark']
+   * @param {string}  [config.accent='#00f5a0']
+   * @param {boolean} [config.rtl=false]
+   * @param {string}  [config.lang='en']
+   * @param {string}  [config.toastPosition='br']
+   * @param {number}  [config.toastDuration=4000]
+   * @param {boolean} [config.autoInit=true]
+   */
+  init(config = {}) {
+    const opts = merge(DEFAULTS, config);
+
+    // Language
+    this.lang = opts.lang;
+    this._t   = i18n[opts.lang] || i18n.en;
+
+    // Theme
+    this.theme = new ThemeManager({ default: opts.theme });
+    if (opts.accent && opts.accent !== DEFAULTS.accent) {
+      this.theme.setAccent(opts.accent);
+    }
+
+    // RTL
+    if (opts.rtl || opts.lang === 'ar') {
+      document.documentElement.setAttribute('dir', 'rtl');
+      document.documentElement.setAttribute('lang', opts.lang);
+    } else {
+      document.documentElement.setAttribute('dir', 'ltr');
+      document.documentElement.setAttribute('lang', opts.lang);
+    }
+
+    // Toast manager
+    DEFAULTS.toastDuration = opts.toastDuration;
+    this.toast = new ToastManager(opts.toastPosition, opts.lang);
+
+    // Auto-init data-ztl-* components
+    if (opts.autoInit !== false) {
+      if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', autoInit);
+      } else {
+        autoInit();
+      }
+    }
+
+    console.log(`%c⚡ ZTL v${ZTL_VERSION} initialized | lang: ${opts.lang} | theme: ${opts.theme}`,
+      'color:#00f5a0;font-family:monospace;font-weight:bold');
+
+    return this;
+  },
+
+  // ── Component constructors ──
+  Modal,
+  Tabs,
+  Dropdown,
+  ProgressBar,
+  CircularProgress,
+  Tooltip,
+  FormValidator,
+  TagInput,
+  DataTable,
+  ThemeManager,
+  ToastManager,
+
+  // ── Utilities ──
+  copyToClipboard,
+  animateCounter,
+  skeleton,
+  initScrollReveal,
+  initCounters,
+  initCopyButtons,
+
+  // ── i18n ──
+  i18n,
+  t(key, ...args) {
+    const translation = (i18n[this.lang] || i18n.en)[key];
+    return typeof translation === 'function' ? translation(...args) : (translation || key);
+  },
+
+  // ── DOM helpers ──
+  $,
+  $$,
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// EXPORTS
+// ─────────────────────────────────────────────────────────────────────────────
+module.exports = ZTL;
+
+