⏱️ server-time-timer-yolabs-ui

SharePoint-styled React countdown timer UI built on top of 👉 server-time-timer-yolabs (server-synchronized core engine)

A production-ready, enterprise UI component for displaying accurate, tamper-proof countdown timers across all devices.

🚀 Why Use This UI?

Traditional countdown timers rely on the client’s local clock, which is unreliable and easy to manipulate.

server-time-timer-yolabs-ui uses server time as the single source of truth, ensuring:

✅ Key Advantages

• 🔒 Server-trusted time → no client clock manipulation
• 🌍 Same countdown on all devices
• 🧩 Highly configurable UI (layout, size, theme, shape, labels)
• 🕒 Fine-grained control over visible units
• 🏢 Enterprise UI inspired by SharePoint UI / SharePoint
• 📱 Responsive and dashboard-safe

⚡ Difference From Normal Timers

| Feature | Normal Timers | server-time-timer-yolabs-ui | | ------------------------ | ------------- | --------------------------------- | | Time Source | Client | Server (trusted) | | Cross-Device Consistency | ❌ | ✅ | | Drift Handling | ❌ | ✅ Auto-corrected | | Layouts | ❌ Fixed | ✅ Horizontal / Vertical / Compact | | Unit Visibility | ❌ Fixed | ✅ Per-unit control | | Label Control | ❌ | ✅ On / Off | | Unit Shape | ❌ | ✅ Rectangle / Circle | | Equal Unit Sizing | ❌ | ✅ Guaranteed | | Enterprise Styling | ❌ | ✅ SharePoint | | Tamper Resistance | ❌ | ✅ Secure |

📦 Installation

npm install server-time-timer-yolabs-ui

or

yarn add server-time-timer-yolabs-ui

🔧 React / Next.js Usage

import { ServerTimerUI } from 'server-time-timer-yolabs-ui';

export default function App() {
  return (
    <ServerTimerUI
      endTime="2025-12-25T12:10:00Z"

      size="lg"
      layout="horizontal"
      theme="brand"

      showLabels={true}
      innerShape="rectangle"
      equalUnitSize={true}

      showUnits={{
        days: true,
        hours: true,
        minutes: true,
        seconds: true
      }}

      customColors={{
        background: '#fef9f3',
        text: '#323130',
        unitBackground: '#fffbdd'
      }}

      onEnd={() => alert('⏰ Time is up!')}
    />
  );
}

🧩 Props / API

export interface ServerTimerUIProps {
  /** 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 or hide unit labels */
  showLabels?: boolean;

  /** Shape of the inner unit background */
  innerShape?: 'rectangle' | 'circle';

  /** Force equal width & height for all units */
  equalUnitSize?: boolean;

  /** Control visible time units */
  showUnits?: {
    days?: boolean;
    hours?: boolean;
    minutes?: boolean;
    seconds?: boolean;
  };

  /** Optional wrapper class */
  className?: string;

  /** Override theme colors */
  customColors?: {
    background?: string;
    text?: string;
    unitBackground?: string;
  };

  /** Callback when countdown reaches zero */
  onEnd?: () => void;
}

🎨 Layouts

🔹 Horizontal (default)

• Units displayed in a row
• Ideal for dashboards and desktop views

🔹 Vertical

• Units stacked vertically
• Best for mobile screens and side panels

🔹 Compact

• Minimal spacing, label-free by default
• Perfect for cards, headers, and widgets

🎭 Themes

Built-in enterprise themes:

• light – clean light UI
• dark – enterprise dark mode
• brand – SharePoint / corporate branding

<ServerTimerUI theme="dark" />

🔘 Labels Control

<ServerTimerUI showLabels={false} />

• Useful for compact layouts
• Cleaner UI for cards and widgets

🔵 Inner Unit Shape

<ServerTimerUI innerShape="circle" />

Available options:

• rectangle (default)
• circle

✔ SharePoint-style ✔ Pixel-perfect sizing

📐 Equal Unit Sizing

<ServerTimerUI equalUnitSize />

• All units have identical width & height
• Prevents layout jumping
• Recommended for enterprise dashboards

⚡ Custom Colors

customColors={{
  background: '#fff8f0',
  text: '#333',
  unitBackground: '#ffe5b4'
}}

• Optional
• Overrides theme defaults safely

🕒 Optional Units

showUnits={{
  days: false,
  hours: true,
  minutes: true,
  seconds: true
}}

• Hide unused units
• Ideal for short-duration timers

📱 Responsive & Overflow-Safe

• Uses flex + controlled wrapping
• Size-based typography scaling
• No number jumping or reflow
• Vertical layout recommended for small screens

✔ Mobile-safe ✔ Dashboard-safe

🔁 Server Re-Sync (Long Timers)

For long-running sessions, periodically re-sync server time:

setInterval(async () => {
  const res = await fetch('/api/server-time');
  const data = await res.json();
  timer.sync(data.now);
}, 30000);

• Prevents long-term drift
• Enterprise best practice

🔧 Framework-Agnostic Usage

For Angular, Vue, or Vanilla JS, use the core engine directly:

import { createServerTimer } from 'server-time-timer-yolabs';

const timer = createServerTimer({
  endTime: new Date(Date.now() + 10 * 60 * 1000).toISOString()
});

timer.onTick(t => {
  console.log(`${t.hours}h ${t.minutes}m ${t.seconds}s`);
});

timer.start();

• UI layer is optional
• Same trusted logic everywhere

🏢 Use Cases

• 🎟️ Lottery & raffle systems
• 🛒 Flash sales & promotions
• 📝 Online exams & timed quizzes
• 🎮 Games & live events
• 📱 Telegram Mini Apps
• 🌐 Distributed enterprise dashboards
• 🏢 SharePoint / SPFx solutions

📜 License

YonasLabs / YoLabs <+251930327375>

✅ Final Notes

This package is designed for mission-critical countdowns where:

• Accuracy matters
• Client manipulation must be prevented
• UI consistency across platforms is required