server-time-timer-yolabs-ui 1.0.0

package/README.md

@@ -0,0 +1,172 @@
+Perfect! Here’s a **professional README** for your `server-time-timer-ui` package, fully detailed for enterprise usage:
+
+---
+
+# ⏱️ server-time-timer-ui
+
+**Enterprise-grade server-synchronized countdown timer UI for React and Next.js**
+Designed for **consistent countdown across all devices**, with optional **customization, layouts, and progress display**.
+
+---
+
+## 🚀 Key Features
+
+* 🔒 **Server time is the single source of truth** (uses `server-time-timer-yoLabs`)
+* 🌍 Same countdown across **all platforms**
+* 🧩 **Dynamic sizes**: `sm`, `md`, `lg`
+* 🖌️ **Custom themes and colors**: light, dark, brand, or custom colors
+* ⚡ Optional **progress bar**
+* 🕒 Optional **unit display**: days, hours, minutes, seconds
+* 🏢 **Enterprise-ready, React / Next.js / Telegram Mini Apps compatible**
+
+---
+
+## 📦 Installation
+
+```bash
+npm install server-time-timer-ui server-time-timer-yoLabs
+```
+
+or
+
+```bash
+yarn add server-time-timer-ui server-time-timer-yoLabs
+```
+
+---
+
+## 🧠 How It Works
+
+1️⃣ Server sends the **current time** (`serverNow`)
+2️⃣ Client calculates **offset**
+3️⃣ Countdown runs locally using offset
+4️⃣ Optional **re-sync** keeps everything accurate
+
+✅ Result: perfect synchronized countdown across devices.
+
+---
+
+## 🔧 Props / Options
+
+```ts
+export interface ServerTimerUIProps {
+  serverNow: string;                 // Current server time (UTC)
+  endTime: string;                   // Countdown target time (UTC)
+  size?: 'sm' | 'md' | 'lg';         // Default: 'md'
+  layout?: 'horizontal' | 'vertical' | 'compact'; // Default: 'horizontal'
+  theme?: 'light' | 'dark' | 'brand';             // Default: 'light'
+  showProgress?: boolean;            // Show progress bar, default true
+  onEnd?: () => void;                // Callback when countdown ends
+  className?: string;                // Optional wrapper className
+  customColors?: {                   // Optional colors
+    background?: string;
+    text?: string;
+    unitBackground?: string;
+    progress?: string;
+  };
+  showUnits?: {                      // Optional unit display
+    days?: boolean;
+    hours?: boolean;
+    minutes?: boolean;
+    seconds?: boolean;
+  };
+}
+```
+
+---
+
+## 🔧 Basic Usage
+
+```tsx
+import React from 'react';
+import { ServerTimerUI } from 'server-time-timer-ui';
+
+export default function App() {
+  return (
+    <ServerTimerUI
+      serverNow="2025-12-25T12:00:00Z"
+      endTime="2025-12-25T12:10:00Z"
+      size="lg"
+      theme="brand"
+      showProgress={true}
+      customColors={{
+        background: '#fef9f3',
+        text: '#323130',
+        unitBackground: '#fffbdd',
+        progress: '#0078d4'
+      }}
+      showUnits={{ days: false, hours: true, minutes: true, seconds: true }}
+      onEnd={() => alert('Time is up!')}
+    />
+  );
+}
+```
+
+---
+
+## 🎨 Layouts
+
+* **Horizontal (default)**: Units aligned in a row
+* **Vertical**: Units stacked in a column
+* **Compact**: Smaller units for tight spaces
+
+```tsx
+<ServerTimerUI layout="vertical" />
+<ServerTimerUI layout="compact" />
+```
+
+---
+
+## ⚡ Custom Colors
+
+```tsx
+customColors={{
+  background: '#fff8f0',
+  text: '#333',
+  unitBackground: '#ffe5b4',
+  progress: '#0078d4'
+}}
+```
+
+✅ Fully optional; uses theme defaults if not provided.
+
+---
+
+## 🕒 Optional Units
+
+```tsx
+showUnits={{ days: false, hours: true, minutes: true, seconds: true }}
+```
+
+✅ Hide days, hours, minutes, or seconds dynamically based on UI needs.
+
+---
+
+## 🔁 Resync (Recommended for long timers)
+
+```ts
+setInterval(async () => {
+  const res = await fetch('/api/server-time');
+  const data = await res.json();
+  timer.sync(data.now);
+}, 30000);
+```
+
+---
+
+## 🏢 Use Cases
+
+* 🎟️ Lottery & raffle countdowns
+* 🛒 Flash sales & limited offers
+* 📝 Online exams
+* 🎮 Games & event timers
+* 📱 Telegram Mini Apps
+* 🌐 Distributed systems
+
+---
+
+## 📜 License
+
+YonasLabs
+
+---

package/dist/hooks/useServerTimer.d.ts

@@ -0,0 +1,12 @@
+export declare function useServerTimer({ serverNow, endTime, onEnd }: {
+    serverNow: string;
+    endTime: string;
+    onEnd?: () => void;
+}): {
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+    totalMs: number;
+    progress: number;
+};

package/dist/hooks/useServerTimer.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useServerTimer = useServerTimer;
+const react_1 = require("react");
+const server_time_timer_yoLabs_1 = require("server-time-timer-yoLabs");
+function useServerTimer({ serverNow, endTime, onEnd }) {
+    const [time, setTime] = (0, react_1.useState)({
+        days: 0,
+        hours: 0,
+        minutes: 0,
+        seconds: 0,
+        totalMs: 0,
+        progress: 100
+    });
+    (0, react_1.useEffect)(() => {
+        const timer = (0, server_time_timer_yoLabs_1.createServerTimer)({ serverNow, endTime });
+        timer.onTick((t) => {
+            const totalDuration = new Date(endTime).getTime() - new Date(serverNow).getTime();
+            setTime({
+                days: t.days,
+                hours: t.hours,
+                minutes: t.minutes,
+                seconds: t.seconds,
+                totalMs: t.totalMs,
+                progress: Math.max(0, (t.totalMs / totalDuration) * 100)
+            });
+            if (t.totalMs <= 0 && onEnd)
+                onEnd();
+        });
+        timer.start();
+        return () => timer.stop();
+    }, [serverNow, endTime, onEnd]);
+    return time;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { ServerTimerUI } from './ui/ServerTimerUI';
+export type { ServerTimerUIProps } from './ui/types';

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServerTimerUI = void 0;
+var ServerTimerUI_1 = require("./ui/ServerTimerUI");
+Object.defineProperty(exports, "ServerTimerUI", { enumerable: true, get: function () { return ServerTimerUI_1.ServerTimerUI; } });

package/dist/ui/ServerTimerUI.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+import { ServerTimerUIProps } from './types';
+export declare const ServerTimerUI: React.FC<ServerTimerUIProps>;

package/dist/ui/ServerTimerUI.js

@@ -0,0 +1,16 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServerTimerUI = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const TimerContainer_1 = __importDefault(require("./components/TimerContainer"));
+const TimerUnit_1 = __importDefault(require("./components/TimerUnit"));
+const TimerProgress_1 = __importDefault(require("./components/TimerProgress"));
+const useServerTimer_1 = require("../hooks/useServerTimer");
+const ServerTimerUI = ({ serverNow, endTime, size = 'md', theme = 'light', layout = 'horizontal', showProgress = true, customColors, showUnits = { days: true, hours: true, minutes: true, seconds: true }, onEnd }) => {
+    const time = (0, useServerTimer_1.useServerTimer)({ serverNow, endTime, onEnd });
+    return ((0, jsx_runtime_1.jsxs)(TimerContainer_1.default, { size: size, background: customColors === null || customColors === void 0 ? void 0 : customColors.background, color: customColors === null || customColors === void 0 ? void 0 : customColors.text, children: [showUnits.days && (0, jsx_runtime_1.jsx)(TimerUnit_1.default, { label: "Days", value: time.days, size: size, background: customColors === null || customColors === void 0 ? void 0 : customColors.unitBackground }), showUnits.hours && (0, jsx_runtime_1.jsx)(TimerUnit_1.default, { label: "Hours", value: time.hours, size: size, background: customColors === null || customColors === void 0 ? void 0 : customColors.unitBackground }), showUnits.minutes && (0, jsx_runtime_1.jsx)(TimerUnit_1.default, { label: "Minutes", value: time.minutes, size: size, background: customColors === null || customColors === void 0 ? void 0 : customColors.unitBackground }), showUnits.seconds && (0, jsx_runtime_1.jsx)(TimerUnit_1.default, { label: "Seconds", value: time.seconds, size: size, background: customColors === null || customColors === void 0 ? void 0 : customColors.unitBackground }), showProgress && (0, jsx_runtime_1.jsx)(TimerProgress_1.default, { value: time.progress, color: customColors === null || customColors === void 0 ? void 0 : customColors.progress })] }));
+};
+exports.ServerTimerUI = ServerTimerUI;

package/dist/ui/components/TimerContainer.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+import { TimerSize } from '../types';
+interface TimerContainerProps {
+    children: React.ReactNode;
+    size?: TimerSize;
+    className?: string;
+    background?: string;
+    color?: string;
+}
+declare const TimerContainer: React.FC<TimerContainerProps>;
+export default TimerContainer;

package/dist/ui/components/TimerContainer.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const jsx_runtime_1 = require("react/jsx-runtime");
+const paddingMap = {
+    sm: '0.5rem 1rem',
+    md: '1rem 1.5rem',
+    lg: '1.5rem 2rem'
+};
+const TimerContainer = ({ children, size = 'md', className, background = '#ffffff', color = '#323130' }) => ((0, jsx_runtime_1.jsx)("div", { className: className, style: {
+        backgroundColor: background,
+        color,
+        border: '1px solid #e1e1e1',
+        borderRadius: '4px',
+        boxShadow: '0 1px 3px rgba(0,0,0,0.1)',
+        padding: paddingMap[size],
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: '0.75rem',
+        fontFamily: `'Segoe UI', sans-serif`,
+        fontSize: '1rem'
+    }, children: children }));
+exports.default = TimerContainer;

package/dist/ui/components/TimerFinished.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+declare const TimerFinished: React.FC;
+export default TimerFinished;

package/dist/ui/components/TimerFinished.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const jsx_runtime_1 = require("react/jsx-runtime");
+const TimerFinished = () => ((0, jsx_runtime_1.jsx)("div", { style: {
+        padding: '0.75rem 1rem',
+        backgroundColor: '#f8d7da',
+        color: '#a4262c',
+        borderRadius: '4px',
+        fontWeight: 600,
+        fontFamily: `'Segoe UI', sans-serif`,
+        textAlign: 'center'
+    }, children: "\u23F0 Time\u2019s up!" }));
+exports.default = TimerFinished;

package/dist/ui/components/TimerProgress.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+interface TimerProgressProps {
+    value: number;
+    color?: string;
+}
+declare const TimerProgress: React.FC<TimerProgressProps>;
+export default TimerProgress;

package/dist/ui/components/TimerProgress.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const jsx_runtime_1 = require("react/jsx-runtime");
+const TimerProgress = ({ value, color = '#0078d4' }) => ((0, jsx_runtime_1.jsx)("div", { style: {
+        flex: 1,
+        height: '6px',
+        background: '#e1e1e1',
+        borderRadius: '3px',
+        overflow: 'hidden',
+        marginLeft: '0.5rem'
+    }, children: (0, jsx_runtime_1.jsx)("div", { style: {
+            width: `${value}%`,
+            background: color,
+            height: '100%'
+        } }) }));
+exports.default = TimerProgress;

package/dist/ui/components/TimerUnit.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+import { TimerSize } from '../types';
+export interface TimerUnitProps {
+    label: string;
+    value: number;
+    size?: TimerSize;
+    background?: string;
+    color?: string;
+}
+declare const TimerUnit: React.FC<TimerUnitProps>;
+export default TimerUnit;

package/dist/ui/components/TimerUnit.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const jsx_runtime_1 = require("react/jsx-runtime");
+const paddingMap = {
+    sm: '0.25rem 0.5rem',
+    md: '0.5rem 1rem',
+    lg: '0.75rem 1.5rem'
+};
+const fontSizeMap = {
+    sm: '0.625rem',
+    md: '0.75rem',
+    lg: '0.875rem'
+};
+const TimerUnit = ({ label, value, size = 'md', background = '#f3f2f1', color = '#323130' }) => ((0, jsx_runtime_1.jsxs)("div", { style: {
+        backgroundColor: background,
+        color,
+        borderRadius: '4px',
+        padding: paddingMap[size],
+        minWidth: '2.5rem',
+        textAlign: 'center'
+    }, children: [(0, jsx_runtime_1.jsx)("div", { style: { fontWeight: 600, fontSize: fontSizeMap[size] }, children: String(value).padStart(2, '0') }), (0, jsx_runtime_1.jsx)("div", { style: { fontSize: fontSizeMap[size], opacity: 0.8 }, children: label })] }));
+exports.default = TimerUnit;

package/dist/ui/layouts/CompactLayout.d.ts

@@ -0,0 +1,4 @@
+import React from 'react';
+export declare const CompactLayout: React.FC<{
+    children: React.ReactNode;
+}>;

package/dist/ui/layouts/CompactLayout.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompactLayout = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const CompactLayout = ({ children }) => ((0, jsx_runtime_1.jsx)("div", { style: { display: 'inline-flex', gap: '0.25rem', fontSize: '0.875rem' }, children: children }));
+exports.CompactLayout = CompactLayout;

package/dist/ui/layouts/HorizontalLayout.d.ts

@@ -0,0 +1,4 @@
+import React from 'react';
+export declare const HorizontalLayout: React.FC<{
+    children: React.ReactNode;
+}>;

package/dist/ui/layouts/HorizontalLayout.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HorizontalLayout = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const HorizontalLayout = ({ children }) => ((0, jsx_runtime_1.jsx)("div", { style: { display: 'flex', gap: '0.5rem' }, children: children }));
+exports.HorizontalLayout = HorizontalLayout;

package/dist/ui/layouts/VerticalLayout.d.ts

@@ -0,0 +1,4 @@
+import React from 'react';
+export declare const VerticalLayout: React.FC<{
+    children: React.ReactNode;
+}>;

package/dist/ui/layouts/VerticalLayout.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VerticalLayout = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const VerticalLayout = ({ children }) => ((0, jsx_runtime_1.jsx)("div", { style: { display: 'flex', flexDirection: 'column', gap: '0.25rem' }, children: children }));
+exports.VerticalLayout = VerticalLayout;

package/dist/ui/themes/brand.d.ts

@@ -0,0 +1,4 @@
+export declare const brand: {
+    background: string;
+    color: string;
+};

package/dist/ui/themes/brand.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.brand = void 0;
+exports.brand = { background: '#0078d4', color: '#ffffff' };

package/dist/ui/themes/dark.d.ts

@@ -0,0 +1,4 @@
+export declare const dark: {
+    background: string;
+    color: string;
+};

package/dist/ui/themes/dark.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dark = void 0;
+exports.dark = { background: '#323130', color: '#f3f2f1' };

package/dist/ui/themes/light.d.ts

@@ -0,0 +1,4 @@
+export declare const light: {
+    background: string;
+    color: string;
+};

package/dist/ui/themes/light.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.light = void 0;
+exports.light = { background: '#f3f2f1', color: '#323130' };

package/dist/ui/types/index.d.ts

@@ -0,0 +1,25 @@
+export type TimerSize = 'sm' | 'md' | 'lg';
+export type TimerLayout = 'horizontal' | 'vertical' | 'compact';
+export type TimerTheme = 'light' | 'dark' | 'brand';
+export interface ServerTimerUIProps {
+    serverNow: string;
+    endTime: string;
+    size?: TimerSize;
+    layout?: TimerLayout;
+    theme?: TimerTheme;
+    showProgress?: boolean;
+    onEnd?: () => void;
+    className?: string;
+    customColors?: {
+        background?: string;
+        text?: string;
+        unitBackground?: string;
+        progress?: string;
+    };
+    showUnits?: {
+        days?: boolean;
+        hours?: boolean;
+        minutes?: boolean;
+        seconds?: boolean;
+    };
+}

package/dist/ui/types/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "server-time-timer-yolabs-ui",
+  "version": "1.0.0",
+  "description": "FluentUI/SharePoint styled React countdown timer UI for server-time-timer-yoLabs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "server-time-timer-yoLabs": "^1.0.0"
+  },
+  "keywords": [
+    "timer",
+    "countdown",
+    "react",
+    "server-time",
+    "fluentui",
+    "sharepoint",
+    "enterprise",
+    "ui"
+  ],
+  "license": "yolabs",
+  "author": "Yonas <+251930327375>",
+  "dependencies": {
+    "server-time-timer-yolabs": "^1.0.2"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "^5.9.3"
+  }
+}