server-time-timer-yolabs-ui 1.0.8 → 1.0.9

package/README.md

@@ -1,51 +1,53 @@
 
-
 # ⏱️ server-time-timer-yolabs-ui
 
-** SharePoint styled React countdown timer UI for `server-time-timer-yolabs`**
+**SharePoint-styled React countdown timer UI built on top of `server-time-timer-yolabs`.**
 
-Professional, **enterprise-grade React UI** for server-synchronized countdowns. Fully dynamic, customizable, and framework-agnostic core logic.
+A **professional, enterprise-grade React UI** for **server-synchronized countdown timers**.
+Designed for **accuracy, consistency, and corporate dashboards**.
 
 ---
 
 ## 🚀 Why Use This UI?
 
-Unlike traditional timers relying on the **client clock**:
+Unlike traditional timers that rely on the **client’s local clock**, this UI uses **server time as the single source of truth**.
+
+### ✅ Key Advantages
 
-* 🔒 **Server time is the single source of truth** → accurate across devices
-* 🌍 **Same countdown across all platforms**
-* 🧩 **Dynamic sizes, layouts, themes, and colors**
-* ⚡ **Optional progress bar**
-* 🕒 **Optional units** (days, hours, minutes, seconds)
-* 🏢 **Enterprise-ready design** with FluentUI / SharePoint style
+* 🔒 **Server-trusted time** → no client clock manipulation
+* 🌍 **Consistent countdown across all devices**
+* 🧩 **Dynamic layouts, sizes, themes, and colors**
+* ⚡ **Optional animated progress bar**
+* 🕒 **Configurable units** (days, hours, minutes, seconds)
+* 🏢 **Enterprise UI** inspired by Fluent UI / SharePoint
 
 ---
 
-### ⚡ Difference From Other Timers
+## ⚡ Difference From Other Timers
 
-| Feature                    | Normal Timers   | `server-time-timer-yolabs-ui`     |
-| -------------------------- | --------------- | --------------------------------- |
-| Source of Time             | Client          | Server (trusted)                  |
-| Consistency Across Devices | ❌ Can differ    | ✅ Always same                     |
-| Drift Handling             | ❌ None          | ✅ Automatic correction            |
-| Layouts                    | ❌ Fixed         | ✅ Horizontal / Vertical / Compact |
-| Unit Display               | ❌ Fixed         | ✅ Optional per unit               |
-| Progress Bar               | ❌ Not built-in  | ✅ Optional & dynamic              |
-| Enterprise UI              | ❌ Simple        | ✅ SharePoint style     |
-| Security                   | ❌ Easy to cheat | ✅ Resistant to manipulation       |
+| Feature                  | Normal Timers   | server-time-timer-yolabs-ui       |
+| ------------------------ | --------------- | --------------------------------- |
+| Time Source              | Client          | **Server (trusted)**              |
+| Cross-Device Consistency | ❌ Can differ    | ✅ Always same                     |
+| Time Drift Handling      | ❌ None          | ✅ Auto-corrected                  |
+| Layouts                  | ❌ Fixed         | ✅ Horizontal / Vertical / Compact |
+| Unit Visibility          | ❌ Fixed         | ✅ Per-unit control                |
+| Progress Bar             | ❌ Missing       | ✅ Built-in                        |
+| Enterprise Styling       | ❌ Basic         | ✅ SharePoint-style                |
+| Tamper Resistance        | ❌ Easy to cheat | ✅ Secure                          |
 
 ---
 
 ## 📦 Installation
 
 ```bash
-npm install server-time-timer-yolabs-ui 
+npm install server-time-timer-yolabs-ui
 ```
 
 or
 
 ```bash
-yarn add server-time-timer-yolabs-ui 
+yarn add server-time-timer-yolabs-ui
 ```
 
 ---
@@ -53,7 +55,6 @@ yarn add server-time-timer-yolabs-ui
 ## 🔧 React / Next.js Usage
 
 ```tsx
-import React from 'react';
 import { ServerTimerUI } from 'server-time-timer-yolabs-ui';
 
 export default function App() {
@@ -61,18 +62,28 @@ export default function App() {
     <ServerTimerUI
       serverNow="2025-12-25T12:00:00Z"
       endTime="2025-12-25T12:10:00Z"
+
       size="lg"
       layout="horizontal"
       theme="brand"
+
       showProgress={true}
+
       customColors={{
         background: '#fef9f3',
         text: '#323130',
         unitBackground: '#fffbdd',
         progress: '#0078d4'
       }}
-      showUnits={{ days: true, hours: true, minutes: true, seconds: true }}
-      onEnd={() => alert('Time is up!')}
+
+      showUnits={{
+        days: true,
+        hours: true,
+        minutes: true,
+        seconds: true
+      }}
+
+      onEnd={() => alert('⏰ Time is up!')}
     />
   );
 }
@@ -84,21 +95,40 @@ export default function App() {
 
 ```ts
 export interface ServerTimerUIProps {
-  serverNow: string;                 
-  endTime: string;                   
-  size?: 'sm' | 'md' | 'lg';         
-  layout?: 'horizontal' | 'vertical' | 'compact'; 
-  theme?: 'light' | 'dark' | 'brand';             
-  showProgress?: boolean;            
-  onEnd?: () => void;                
-  className?: string;                
-  customColors?: {                   
+  /** Server UTC time (ISO string) */
+  serverNow: string;
+
+  /** Countdown end UTC time (ISO string) */
+  endTime: string;
+
+  /** Visual size */
+  size?: 'sm' | 'md' | 'lg';
+
+  /** Layout direction */
+  layout?: 'horizontal' | 'vertical' | 'compact';
+
+  /** Built-in theme */
+  theme?: 'light' | 'dark' | 'brand';
+
+  /** Show animated progress bar */
+  showProgress?: boolean;
+
+  /** Called once when timer reaches zero */
+  onEnd?: () => void;
+
+  /** Optional wrapper class */
+  className?: string;
+
+  /** Override theme colors */
+  customColors?: {
     background?: string;
     text?: string;
     unitBackground?: string;
     progress?: string;
   };
-  showUnits?: {                      
+
+  /** Control visible time units */
+  showUnits?: {
     days?: boolean;
     hours?: boolean;
     minutes?: boolean;
@@ -111,9 +141,38 @@ export interface ServerTimerUIProps {
 
 ## 🎨 Layouts
 
-* **Horizontal** – units in a row
-* **Vertical** – units stacked
-* **Compact** – small, space-saving units
+### Horizontal (default)
+
+Units displayed in a row.
+✔ Dashboards
+✔ Desktop views
+
+### Vertical
+
+Units stacked vertically.
+✔ Mobile
+✔ Side panels
+
+### Compact
+
+Minimal, label-free layout.
+✔ Cards
+✔ Headers
+✔ Space-constrained UIs
+
+---
+
+## 🎭 Themes
+
+Built-in themes are located in the `themes` folder:
+
+* `light` –  light style
+* `dark` – Enterprise dark mode
+* `brand` – Corporate / SharePoint branding
+
+```tsx
+<ServerTimerUI theme="dark" />
+```
 
 ---
 
@@ -128,42 +187,66 @@ customColors={{
 }}
 ```
 
-✅ Optional, fallback to theme defaults.
+✅ Optional
+✅ Automatically overrides theme defaults
 
 ---
 
 ## 🕒 Optional Units
 
 ```ts
-showUnits={{ days: false, hours: true, minutes: true, seconds: true }}
+showUnits={{
+  days: false,
+  hours: true,
+  minutes: true,
+  seconds: true
+}}
 ```
 
-✅ Hide or show units dynamically.
+✔ Hide unused units
+✔ Cleaner UI for short timers
 
 ---
 
-## 🔁 Resync for Long Timers
+## 📱 Responsiveness & Overflow Safety
+
+* Uses `flex-wrap` to prevent overflow
+* Auto-scales typography by `size`
+* Vertical layout recommended for small screens
+* Numbers never jump or resize unexpectedly
+
+✔ Mobile-safe
+✔ Dashboard-safe
+
+---
+
+## 🔁 Server Re-Sync (Long Timers)
+
+For long-running timers, periodically resync with the server:
 
 ```ts
 setInterval(async () => {
   const res = await fetch('/api/server-time');
   const data = await res.json();
   timer.sync(data.now);
-}, 30000); // every 30 seconds
+}, 30000);
 ```
 
+✔ Prevents long-term drift
+✔ Enterprise-grade accuracy
+
 ---
 
 ## 🔧 Angular / Framework-Agnostic Usage
 
-Use the **core package** (`server-time-timer-yolabs`) for Angular or Vanilla JS:
+For Angular, Vue, or Vanilla JS, use the **core engine**:
 
 ```ts
 import { createServerTimer } from 'server-time-timer-yolabs';
 
 const timer = createServerTimer({
   serverNow: new Date().toISOString(),
-  endTime: new Date(Date.now() + 10*60*1000).toISOString()
+  endTime: new Date(Date.now() + 10 * 60 * 1000).toISOString()
 });
 
 timer.onTick((t) => {
@@ -173,24 +256,36 @@ timer.onTick((t) => {
 timer.start();
 ```
 
-✅ Wrap values in your own Angular components for UI.
+✔ Wrap values in your own UI layer
+✔ React UI package remains optional
 
 ---
 
-## 🏢 Use Cases
+## 🏢 Common Use Cases
 
 * 🎟️ Lottery & raffle systems
-* 🛒 Flash sales & limited offers
+* 🛒 Flash sales & promotions
 * 📝 Online exams & quizzes
-* 🎮 Games & events
+* 🎮 Games & live events
 * 📱 Telegram Mini Apps
-* 🌐 Distributed enterprise apps
+* 🌐 Distributed enterprise dashboards
+* 🏢 SharePoint / SPFx solutions
 
 ---
 
 ## 📜 License
 
-yolabs © Yonas
+**Yonas**
+© **YoLabs**
 
 ---
 
+## ✅ Final Notes
+
+This package is designed for **mission-critical timers** where:
+
+* Accuracy matters
+* Client manipulation must be avoided
+* UI consistency is required across platforms
+
+---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "server-time-timer-yolabs-ui",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "FluentUI/SharePoint styled React countdown timer UI for server-time-timer-yoLabs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",