npm - @zero-studio/library - Versions diffs - 1.0.0 - Mend

@zero-studio/library 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,755 @@
+# ⚡ ZERO Technology Library (ZTL) &nbsp;[![npm](https://img.shields.io/npm/v/@zero-tech/library.svg?color=00f5a0)](https://www.npmjs.com/package/@zero-tech/library) [![License: MIT](https://img.shields.io/badge/License-MIT-00f5a0.svg)](LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-3b82f6.svg)]()
+> **English** (primary) · [**العربية**](#-الوثائق-العربية) (secondary)
+A futuristic, modular UI component library built for the modern web.
+Integrates 150+ libraries · Ships 500+ ready-to-use components · Zero config required.
+---
+## Table of Contents
+- [Features](#-features)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Components](#-components)
+  - [Toast](#toast)
+  - [Modal](#modal)
+  - [Tabs](#tabs)
+  - [Dropdown](#dropdown)
+  - [Progress](#progress)
+  - [Form Validator](#form-validator)
+  - [Data Table](#data-table)
+  - [Tag Input](#tag-input)
+  - [Theme Manager](#theme-manager)
+  - [Utilities](#utilities)
+- [i18n (Arabic & English)](#-i18n--arabic--english)
+- [CSS Classes Reference](#-css-classes-reference)
+- [TypeScript](#-typescript)
+- [Browser Support](#-browser-support)
+- [الوثائق العربية](#-الوثائق-العربية)
+- [License](#-license)
+---
+## ✨ Features
+| Feature | Description |
+|---|---|
+| 🎨 **CSS Design System** | 80+ CSS custom properties (design tokens), dark + light themes |
+| 🧩 **Rich Components** | Toast, Modal, Tabs, Dropdown, Progress, DataTable, TagInput, FormValidator |
+| 🌍 **Built-in i18n** | English (primary) + Arabic with RTL support out of the box |
+| 🔷 **TypeScript Ready** | Full `.d.ts` declarations — IntelliSense in every IDE |
+| ⚡ **Zero Dependencies** | Pure ES2020+ JavaScript, no frameworks required |
+| 📦 **Tree-Shakeable** | ESM build — bundlers only include what you use |
+| ♿ **Accessible** | ARIA roles, keyboard navigation, focus management |
+| 🎯 **Auto-init** | `data-ztl-*` attribute API for HTML-first usage |
+| 🖌️ **Customizable** | Override any token via CSS custom properties |
+---
+## 📦 Installation
+```bash
+# npm
+npm install @zero-tech/library
+# yarn
+yarn add @zero-tech/library
+# pnpm
+pnpm add @zero-tech/library
+```
+### CDN (no build step)
+```html
+<!-- CSS -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@zero-tech/library/dist/ztl.min.css">
+<!-- JS (UMD — exposes global ZTL) -->
+<script src="https://cdn.jsdelivr.net/npm/@zero-tech/library/dist/ztl.umd.js"></script>
+```
+---
+## 🚀 Quick Start
+### ESM / bundler
+```js
+import ZTL from '@zero-tech/library';
+import '@zero-tech/library/css';   // or: import '@zero-tech/library/dist/ztl.min.css'
+ZTL.init({
+  theme:         'dark',   // 'dark' | 'light'
+  accent:        '#00f5a0',
+  lang:          'en',     // 'en' | 'ar'
+  toastPosition: 'br',     // bottom-right
+});
+// Show a toast
+ZTL.toast.success('Library initialized! 🚀');
+```
+### HTML / CDN
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@zero-tech/library/dist/ztl.min.css">
+</head>
+<body class="ztl-body">
+  <!-- Auto-initialized tab component -->
+  <div data-ztl="tabs">
+    <div class="ztl-tabs-nav">
+      <button class="ztl-tab-btn ztl-active">Overview</button>
+      <button class="ztl-tab-btn">Docs</button>
+    </div>
+    <div class="ztl-tab-panel ztl-active"><p>Tab 1 content</p></div>
+    <div class="ztl-tab-panel"><p>Tab 2 content</p></div>
+  </div>
+  <script src="https://cdn.jsdelivr.net/npm/@zero-tech/library/dist/ztl.umd.js"></script>
+  <script>
+    ZTL.init({ lang: 'en' });
+  </script>
+</body>
+</html>
+```
+---
+## 🧩 Components
+### Toast
+```js
+// Basic
+ZTL.toast.success('Saved successfully!');
+ZTL.toast.danger('Something went wrong.');
+ZTL.toast.warning('Subscription expires soon.');
+ZTL.toast.info('New version available.');
+// With options
+ZTL.toast.show('Custom message', 'success', {
+  duration: 6000,
+  icon:     '🎉',
+  closable: true,
+});
+// Clear all toasts
+ZTL.toast.clear();
+```
+### Modal
+```js
+// Simple alert-style modal
+const m = new ZTL.Modal({
+  title: 'Confirm Action',
+  body:  '<p>This cannot be undone. Proceed?</p>',
+  size:  'sm',         // 'sm' | 'lg' | 'xl' | 'full'
+  lang:  'en',
+  onConfirm: () => console.log('Confirmed!'),
+  onCancel:  () => console.log('Cancelled.'),
+});
+m.open();
+// Promise-based confirm dialog
+const confirmed = await ZTL.Modal.confirm(
+  'Delete this record permanently?',
+  { lang: 'en', title: 'Delete Record' }
+);
+if (confirmed) deleteRecord();
+// Dynamic content
+m.setBody('<p>Updated content</p>');
+m.setTitle('New Title');
+m.close();
+m.destroy(); // removes from DOM
+```
+### Tabs
+```html
+<!-- HTML Structure -->
+<div id="myTabs">
+  <div class="ztl-tabs-nav">
+    <button class="ztl-tab-btn ztl-active">Tab 1</button>
+    <button class="ztl-tab-btn">Tab 2</button>
+    <button class="ztl-tab-btn">Tab 3</button>
+  </div>
+  <div class="ztl-tab-panel ztl-active">Content 1</div>
+  <div class="ztl-tab-panel">Content 2</div>
+  <div class="ztl-tab-panel">Content 3</div>
+</div>
+```
+```js
+const tabs = new ZTL.Tabs('#myTabs', {
+  onChange: (index, prev) => console.log(`${prev} → ${index}`),
+});
+tabs.activate(2);      // programmatic switch
+tabs.getActive();      // → 2
+```
+### Dropdown
+```html
+<div class="ztl-dropdown" data-ztl="dropdown">
+  <button class="ztl-btn ztl-btn-primary" data-ztl-trigger>
+    Options ▾
+  </button>
+  <div class="ztl-dropdown-menu">
+    <button class="ztl-dropdown-item">✏️ Edit</button>
+    <button class="ztl-dropdown-item">📋 Copy</button>
+    <div class="ztl-dropdown-divider"></div>
+    <button class="ztl-dropdown-item ztl-dropdown-item-danger">🗑️ Delete</button>
+  </div>
+</div>
+```
+```js
+// Programmatic
+const dd = new ZTL.Dropdown('#myTrigger', '#myMenu');
+dd.open();
+dd.close();
+dd.toggle();
+```
+### Progress
+```js
+// Linear progress bar
+const bar = new ZTL.ProgressBar('#myProgressFill', { value: 0 });
+bar.set(75);
+bar.animateTo(100, 1000);   // animate to 100% in 1s
+bar.increment(5);
+bar.decrement(10);
+// Circular progress
+const circle = new ZTL.CircularProgress('#myCircle', {
+  value:       0,
+  size:        100,
+  strokeWidth: 8,
+  color:       'var(--ztl-accent)',
+});
+circle.animateTo(72);
+```
+```html
+<!-- HTML for linear progress -->
+<div class="ztl-progress">
+  <div id="myProgressFill" class="ztl-progress-fill ztl-progress-success" style="width:0%"></div>
+</div>
+<!-- HTML for circular progress -->
+<div id="myCircle" class="ztl-progress-circle"></div>
+```
+### Form Validator
+```html
+<form id="myForm">
+  <div class="ztl-field">
+    <label class="ztl-label-text">Email <span class="ztl-required">*</span></label>
+    <input class="ztl-input" name="email" type="email">
+  </div>
+  <div class="ztl-field">
+    <label class="ztl-label-text">Password <span class="ztl-required">*</span></label>
+    <input class="ztl-input" name="password" type="password">
+  </div>
+  <button class="ztl-btn ztl-btn-primary" type="submit">Sign In</button>
+</form>
+```
+```js
+const validator = new ZTL.FormValidator('#myForm', {
+  email: [
+    'required',
+    { type: 'email' },
+  ],
+  password: [
+    'required',
+    { type: 'minLength', value: 8 },
+    { type: 'maxLength', value: 64 },
+  ],
+}, {
+  lang:     'en',
+  onSubmit: (values, event) => {
+    console.log('Valid! Values:', values);
+    // { email: '...', password: '...' }
+  },
+});
+// Manual control
+validator.validate();          // → true | false
+validator.getValues();         // → { email, password }
+validator.setErrors({ email: 'Already in use' });
+validator.clearErrors();
+```
+### Data Table
+```js
+const table = new ZTL.DataTable('#myTable', {
+  lang:       'en',
+  pageSize:   10,
+  searchable: true,
+  columns: [
+    { key: 'name',   label: 'Name',    sortable: true },
+    { key: 'role',   label: 'Role',    sortable: true },
+    { key: 'status', label: 'Status',  render: (val) => `<span class="ztl-badge ztl-badge-${val === 'active' ? 'success' : 'neutral'}">${val}</span>` },
+    { key: 'joined', label: 'Joined',  sortable: true },
+  ],
+  data: [
+    { name: 'Alice',   role: 'Engineer',  status: 'active',   joined: '2024-01' },
+    { name: 'Bob',     role: 'Designer',  status: 'inactive', joined: '2023-08' },
+    { name: 'Charlie', role: 'Manager',   status: 'active',   joined: '2022-03' },
+  ],
+});
+// Update data dynamically
+table.update(newDataArray);
+table.setPage(2);
+```
+### Tag Input
+```html
+<div id="tagInput" class="ztl-tag-input-wrap"></div>
+```
+```js
+const tags = new ZTL.TagInput('#tagInput', {
+  initial:  ['React', 'TypeScript'],
+  max:      10,
+  onChange: (tags) => console.log('Tags:', tags),
+  onAdd:    (tag) => console.log('Added:', tag),
+  onRemove: (tag) => console.log('Removed:', tag),
+});
+tags.add('Vue.js');
+tags.remove('React');
+tags.getTags();   // → ['TypeScript', 'Vue.js']
+tags.clear();
+```
+### Theme Manager
+```js
+const theme = new ZTL.ThemeManager({ default: 'dark' });
+theme.apply('light');       // switch to light
+theme.toggle();             // dark ↔ light
+theme.setAccent('#7c3aed'); // change brand color live
+theme.current;              // → 'light'
+```
+### Utilities
+```js
+// Clipboard
+const result = await ZTL.copyToClipboard('Text to copy!', 'en');
+// → { success: true, message: 'Copied!' }
+// Animate number counter
+ZTL.animateCounter(document.getElementById('count'), 1500, {
+  duration: 1200,
+  suffix:   '+',
+  decimals: 0,
+});
+// Skeleton loader
+const sk = ZTL.skeleton('#container', 3);
+// ... load data
+sk.replace('<p>Real content</p>');
+// or
+sk.clear();
+// Scroll reveal (reads data-ztl-reveal attribute)
+ZTL.initScrollReveal('[data-ztl-reveal]');
+// Usage in HTML: <div data-ztl-reveal="slide-up">...</div>
+// Animated counters (reads data-ztl-count attribute)
+ZTL.initCounters('[data-ztl-count]');
+// Usage in HTML: <span data-ztl-count="1500" data-ztl-suffix="+">0</span>
+// Copy button binding (reads data-ztl-copy attribute)
+ZTL.initCopyButtons('en');
+// Usage: <button data-ztl-copy="#codeBlock">Copy</button>
+```
+---
+## 🌍 i18n — Arabic & English
+ZTL ships bilingual out of the box. All component text (labels, errors, placeholders) adapts automatically when you set `lang`.
+```js
+// English (default)
+ZTL.init({ lang: 'en' });
+ZTL.toast.success('Saved!');                    // → 'Saved!'
+// Arabic with RTL
+ZTL.init({ lang: 'ar', rtl: true });
+ZTL.toast.success('تم الحفظ!');                // RTL layout applied automatically
+new ZTL.FormValidator('#form', rules, { lang: 'ar' });
+// Errors → 'هذا الحقل مطلوب', 'الحد الأدنى 8 أحرف', etc.
+// Access translation strings directly
+ZTL.i18n.en.required       // → 'This field is required'
+ZTL.i18n.ar.required       // → 'هذا الحقل مطلوب'
+ZTL.i18n.en.minLength(8)   // → 'Minimum 8 characters'
+ZTL.i18n.ar.minLength(8)   // → 'الحد الأدنى 8 أحرف'
+// Translate via shorthand
+ZTL.t('cancel')            // → 'Cancel' (or 'إلغاء' if lang='ar')
+```
+---
+## 🎨 CSS Classes Reference
+### Buttons
+```html
+<button class="ztl-btn ztl-btn-primary">Primary</button>
+<button class="ztl-btn ztl-btn-secondary">Secondary</button>
+<button class="ztl-btn ztl-btn-ghost">Ghost</button>
+<button class="ztl-btn ztl-btn-danger">Danger</button>
+<button class="ztl-btn ztl-btn-purple">Purple</button>
+<button class="ztl-btn ztl-btn-link">Link</button>
+<!-- Sizes -->
+<button class="ztl-btn ztl-btn-primary ztl-btn-xs">XS</button>
+<button class="ztl-btn ztl-btn-primary ztl-btn-sm">SM</button>
+<button class="ztl-btn ztl-btn-primary ztl-btn-lg">LG</button>
+<button class="ztl-btn ztl-btn-primary ztl-btn-xl">XL</button>
+<!-- Full width -->
+<button class="ztl-btn ztl-btn-primary ztl-btn-full">Full Width</button>
+<!-- Group -->
+<div class="ztl-btn-group">
+  <button class="ztl-btn ztl-btn-ghost">Left</button>
+  <button class="ztl-btn ztl-btn-ghost">Center</button>
+  <button class="ztl-btn ztl-btn-ghost">Right</button>
+</div>
+```
+### Badges
+```html
+<span class="ztl-badge ztl-badge-success"><span class="ztl-badge-dot"></span>Active</span>
+<span class="ztl-badge ztl-badge-danger">Error</span>
+<span class="ztl-badge ztl-badge-warning">Warning</span>
+<span class="ztl-badge ztl-badge-info">Info</span>
+<span class="ztl-badge ztl-badge-purple">Premium</span>
+<span class="ztl-badge ztl-badge-neutral">Disabled</span>
+```
+### Alerts
+```html
+<div class="ztl-alert ztl-alert-success">
+  <span class="ztl-alert-icon">✅</span>
+  <div class="ztl-alert-body">
+    <div class="ztl-alert-title">Success</div>
+    <div class="ztl-alert-text">Your changes have been saved.</div>
+  </div>
+  <button class="ztl-alert-close">✕</button>
+</div>
+```
+### Avatar
+```html
+<!-- Sizes: xs sm md lg xl -->
+<div class="ztl-avatar ztl-avatar-md ztl-avatar-green">AB</div>
+<!-- With status -->
+<div class="ztl-avatar ztl-avatar-lg ztl-avatar-purple" style="position:relative">
+  ZR
+  <span class="ztl-avatar-status ztl-status-online"></span>
+</div>
+<!-- Group -->
+<div class="ztl-avatar-group">
+  <div class="ztl-avatar ztl-avatar-sm ztl-avatar-green">A</div>
+  <div class="ztl-avatar ztl-avatar-sm ztl-avatar-purple">B</div>
+  <div class="ztl-avatar ztl-avatar-sm ztl-avatar-amber">C</div>
+</div>
+```
+### CSS Custom Properties (Design Tokens)
+Override in your CSS to fully customize the theme:
+```css
+:root {
+  --ztl-accent:    #00f5a0;   /* brand green */
+  --ztl-accent-2:  #7c3aed;   /* brand purple */
+  --ztl-bg:        #050508;   /* page background */
+  --ztl-surface:   #0d0d14;   /* card background */
+  --ztl-text:      #e8e8f0;   /* primary text */
+  --ztl-radius:    10px;      /* default border radius */
+  --ztl-font-sans: 'YourFont', sans-serif;
+}
+```
+---
+## 🔷 TypeScript
+Full TypeScript declarations are included in the package.
+```ts
+import ZTL, {
+  Modal,
+  ToastManager,
+  FormValidator,
+  DataTable,
+  type ZTLConfig,
+  type ZTLLang,
+  type ValidationRule,
+  type TableColumn,
+} from '@zero-tech/library';
+ZTL.init({ lang: 'en', theme: 'dark' } satisfies ZTLConfig);
+const rules: Record<string, ValidationRule[]> = {
+  email: ['required', { type: 'email' }],
+};
+const columns: TableColumn<{ name: string; role: string }>[] = [
+  { key: 'name', label: 'Name', sortable: true },
+  { key: 'role', label: 'Role' },
+];
+```
+---
+## 🌐 Browser Support
+| Browser  | Version |
+|----------|---------|
+| Chrome   | 90+     |
+| Firefox  | 88+     |
+| Safari   | 14+     |
+| Edge     | 90+     |
+| Opera    | 76+     |
+| iOS      | 14+     |
+| Android  | 10+     |
+> Internet Explorer is **not** supported.
+---
+## 📁 Package Structure
+```
+@zero-tech/library/
+├── dist/
+│   ├── ztl.esm.js       ← ES Module (tree-shakeable)
+│   ├── ztl.cjs.js       ← CommonJS (Node / older bundlers)
+│   ├── ztl.umd.js       ← UMD (browser <script> tag)
+│   ├── ztl.min.css      ← Minified CSS (production)
+│   ├── ztl.css          ← Readable CSS (development)
+│   └── index.d.ts       ← TypeScript declarations
+└── src/
+    ├── index.js          ← Source JS
+    └── ztl.css           ← Source CSS
+```
+---
+## 🗺️ Roadmap
+| Phase | Timeline | Status |
+|-------|----------|--------|
+| **v1.0** — Core library (150 libs, 500 components) | Q2 2026 | ✅ Released |
+| **v1.1** — React & Vue wrappers                    | Q3 2026 | 🔄 Planned |
+| **v1.2** — ZERO AI Copilot (code generation)       | Q4 2026 | 🔄 Planned |
+| **v2.0** — Figma design kit + Storybook            | Q1 2027 | 🔄 Planned |
+---
+---
+# 🌙 الوثائق العربية
+> هذه الوثائق باللغة العربية — اللغة الثانوية لمكتبة ZTL.
+> للوثائق الكاملة والمفصّلة، راجع [النسخة الإنجليزية](#-zero-technology-library-ztl).
+---
+## 🚀 البدء السريع
+```bash
+npm install @zero-tech/library
+```
+```js
+import ZTL from '@zero-tech/library';
+import '@zero-tech/library/css';
+ZTL.init({
+  theme: 'dark',
+  lang:  'ar',    // يفعّل الترجمة العربية تلقائياً
+  rtl:   true,    // يفعّل اتجاه RTL
+});
+// رسالة توست بالعربية
+ZTL.toast.success('تم الحفظ بنجاح! 🎉');
+```
+---
+## 📦 المكونات الرئيسية
+### Toast — رسائل التنبيه
+```js
+ZTL.toast.success('تمت العملية بنجاح');
+ZTL.toast.danger('حدث خطأ ما');
+ZTL.toast.warning('تحذير: الاشتراك ينتهي قريباً');
+ZTL.toast.info('يتوفر إصدار جديد');
+```
+### Modal — نافذة الحوار
+```js
+// نافذة تأكيد
+const confirmed = await ZTL.Modal.confirm(
+  'هل أنت متأكد؟ لا يمكن التراجع عن هذا الإجراء.',
+  { lang: 'ar', title: 'تأكيد الحذف' }
+);
+if (confirmed) deleteItem();
+// نافذة مخصصة
+const modal = new ZTL.Modal({
+  title:        'إضافة مستخدم جديد',
+  body:         '<p>محتوى النافذة هنا</p>',
+  lang:         'ar',
+  confirmLabel: 'حفظ',
+  cancelLabel:  'إلغاء',
+  onConfirm:    () => saveUser(),
+});
+modal.open();
+```
+### FormValidator — التحقق من النماذج
+```js
+const validator = new ZTL.FormValidator('#myForm', {
+  email: ['required', { type: 'email' }],
+  password: [
+    'required',
+    { type: 'minLength', value: 8 },
+  ],
+}, {
+  lang:     'ar', // رسائل الخطأ بالعربية تلقائياً
+  onSubmit: (values) => {
+    console.log('البيانات:', values);
+  },
+});
+```
+رسائل الخطأ بالعربية:
+- `هذا الحقل مطلوب`
+- `الحد الأدنى 8 أحرف`
+- `الحد الأقصى 64 حرف`
+- `مدخل غير صالح`
+### DataTable — جداول البيانات
+```js
+const table = new ZTL.DataTable('#myTable', {
+  lang:       'ar',  // أزرار وتسميات بالعربية
+  pageSize:   10,
+  searchable: true,  // مربع البحث: 'بحث...'
+  columns: [
+    { key: 'name',   label: 'الاسم',    sortable: true },
+    { key: 'role',   label: 'الدور',    sortable: true },
+    { key: 'status', label: 'الحالة' },
+  ],
+  data: myDataArray,
+});
+```
+---
+## 🎨 مرجع فئات CSS
+يمكنك استخدام مكونات الـ CSS دون أي كود JavaScript:
+```html
+<!-- أزرار -->
+<button class="ztl-btn ztl-btn-primary">زر أساسي</button>
+<button class="ztl-btn ztl-btn-secondary">زر ثانوي</button>
+<button class="ztl-btn ztl-btn-danger ztl-btn-sm">حذف</button>
+<!-- شارات -->
+<span class="ztl-badge ztl-badge-success">نشط</span>
+<span class="ztl-badge ztl-badge-warning">تحذير</span>
+<!-- تنبيهات -->
+<div class="ztl-alert ztl-alert-success">
+  <span class="ztl-alert-icon">✅</span>
+  <div class="ztl-alert-body">
+    <div class="ztl-alert-title">تم بنجاح</div>
+    <div class="ztl-alert-text">تم حفظ التغييرات.</div>
+  </div>
+</div>
+<!-- شريط التقدم -->
+<div class="ztl-progress">
+  <div class="ztl-progress-fill ztl-progress-success" style="width:75%"></div>
+</div>
+<!-- مفتاح Toggle -->
+<label class="ztl-switch">
+  <input type="checkbox" checked>
+  <span class="ztl-switch-track"></span>
+  <span class="ztl-switch-label">تفعيل الإشعارات</span>
+</label>
+```
+---
+## 🌐 دعم RTL الكامل
+تدعم مكتبة ZTL اتجاه RTL بشكل كامل وتلقائي:
+```js
+ZTL.init({ lang: 'ar', rtl: true });
+// يضيف dir="rtl" lang="ar" على <html> تلقائياً
+```
+جميع المكونات (Sidebar، Navbar، Dropdown، Timeline، Form، إلخ) تتكيف مع RTL عبر CSS `[dir="rtl"]` دون أي تدخل يدوي.
+---
+## 📞 الدعم والمساهمة
+- 📚 التوثيق: [docs.zero-tech.dev](https://docs.zero-tech.dev)
+- 🐛 الأخطاء: [GitHub Issues](https://github.com/zero-tech/library/issues)
+- 💬 النقاشات: [GitHub Discussions](https://github.com/zero-tech/library/discussions)
+- 📧 البريد: [dev@zero-tech.dev](mailto:dev@zero-tech.dev)
+---
+## 📄 License / الرخصة
+[MIT](LICENSE) © 2026 ZERO Technology
+> Free for personal and commercial use. Attribution appreciated.
+> مجاني للاستخدام الشخصي والتجاري. يُقدَّر ذكر المصدر.