abc-time

A lightweight time utility package providing countdown timer components and time formatting utilities for modern web applications.

📦 Installation

# If using within the monorepo
pnpm add abc-time

# For external usage
pnpm install abc-time

🚀 Features

The abc-time package provides essential time-related components and utilities:

• CountTime - React countdown timer component with pause/resume functionality
• formatTime - Time formatting utility for displaying time in HH:MM:SS format
• replaceYear - Utility function for updating years in text strings
• Responsive design - Mobile-first responsive time display
• TypeScript support - Full type safety with comprehensive interfaces

📖 Usage

Basic Import

// Import from main entry point
import { CountTime, formatTime, replaceYear } from "abc-time";

// Import specific components
import { CountTime, formatTime } from "abc-time/countTime";
import { replaceYear } from "abc-time/utils";

Usage Examples

1. CountTime - Countdown Timer Component

import { CountTime } from "abc-time/countTime";
import { useState } from "react";

const TimerPage = () => {
  const [isPaused, setIsPaused] = useState(false);

  const handleTimeEnd = () => {
    console.log("Time's up!");
    // Handle time end logic
  };

  return (
    <div className="timer-container">
      <h2>Countdown Timer</h2>

      <CountTime
        duration={3600} // 1 hour in seconds
        onEndTime={handleTimeEnd}
        isPause={isPaused}
      />

      <button onClick={() => setIsPaused(!isPaused)}>
        {isPaused ? "Resume" : "Pause"}
      </button>
    </div>
  );
};

Features:

• Countdown timer with automatic time decrement
• Pause/resume functionality
• Callback when time reaches zero
• Responsive time display (HH:MM:SS format)
• Automatic cleanup on component unmount

2. formatTime - Time Formatting Utility

import { formatTime } from "abc-time/countTime";

const TimeDisplay = () => {
  const timeInMs = 3661000; // 1 hour, 1 minute, 1 second in milliseconds

  return (
    <div className="time-display">
      <h3>Formatted Time:</h3>
      {formatTime(timeInMs)}
      {/* Renders: 01:01:01 */}
    </div>
  );
};

Features:

• Converts milliseconds to HH:MM:SS format
• Handles negative values (displays as 00:00:00)
• Returns JSX element with responsive styling
• Zero-padded time display

3. replaceYear - Year Replacement Utility

import { replaceYear } from "abc-time/utils";

const YearUpdater = () => {
  const oldText = "Copyright 2020-2023 Company Name";
  const updatedText = replaceYear(oldText);

  console.log(updatedText); // "Copyright 2024-2024 Company Name" (if current year is 2024)

  return (
    <div>
      <p>Original: {oldText}</p>
      <p>Updated: {updatedText}</p>
    </div>
  );
};

Features:

• Replaces years in text strings with current year
• Only updates years that are less than current year
• Preserves years that are current or future
• Error handling with fallback to original text
• Supports multiple year patterns in single string

4. Advanced Usage with State Management

import { CountTime, formatTime } from "abc-time";
import { useState, useEffect } from "react";

const AdvancedTimer = () => {
  const [duration, setDuration] = useState(0);
  const [isPaused, setIsPaused] = useState(false);
  const [timeLeft, setTimeLeft] = useState(0);

  const handleTimeEnd = () => {
    alert("Time's up!");
    setDuration(0);
    setTimeLeft(0);
  };

  const startTimer = (seconds: number) => {
    setDuration(seconds);
    setTimeLeft(seconds);
  };

  const resetTimer = () => {
    setDuration(0);
    setTimeLeft(0);
    setIsPaused(false);
  };

  return (
    <div className="advanced-timer">
      <div className="controls">
        <button onClick={() => startTimer(300)}>5 Minutes</button>
        <button onClick={() => startTimer(600)}>10 Minutes</button>
        <button onClick={() => startTimer(1800)}>30 Minutes</button>
        <button onClick={resetTimer}>Reset</button>
      </div>

      {duration > 0 && (
        <div className="timer-display">
          <CountTime
            duration={duration}
            onEndTime={handleTimeEnd}
            isPause={isPaused}
          />

          <div className="timer-controls">
            <button onClick={() => setIsPaused(!isPaused)}>
              {isPaused ? "Resume" : "Pause"}
            </button>
          </div>
        </div>
      )}
    </div>
  );
};

🏗️ Project Structure

packages/time/
├── src/
│   ├── countTime/          # Countdown timer component
│   │   ├── index.tsx
│   │   └── CountTime.stories.tsx
│   ├── utils/              # Utility functions
│   │   └── index.ts
│   └── index.ts           # Main exports
├── dist/                  # Built files
├── package.json
├── README.md
└── versions.md

🔧 Configuration

Dependencies

The package has minimal dependencies:

• React - For component functionality
• TypeScript - For type safety

Environment Setup

# Install dependencies
pnpm install

# Development mode
pnpm dev

# Build package
pnpm build

# Type checking
pnpm check-types

# Linting
pnpm lint

🎨 Styling

CSS Classes

The components use Tailwind CSS classes and can be customized:

// Custom timer styling
<CountTime
  duration={3600}
  onEndTime={handleEnd}
  className="text-3xl font-bold text-blue-500"
/>

// The formatTime function returns JSX with these classes:
// - text-xs sm:text-lg (responsive text size)
// - leading-none (tight line height)
// - font-medium (medium font weight)

Responsive Design

Components are built with mobile-first responsive design:

/* Mobile styles */
.timer-display {
  @apply text-xs;
}

/* Desktop styles */
@media (min-width: 640px) {
  .timer-display {
    @apply text-lg;
  }
}

📦 Dependencies

Runtime Dependencies

• React - Component library

Development Dependencies

• @repo/eslint-config - Shared ESLint configuration
• tsup - TypeScript bundler
• TypeScript type definitions

🚀 Development

Prerequisites

• Node.js 18+
• pnpm (recommended package manager)
• React 18+
• TypeScript 5+

Setup

# Install dependencies
pnpm install

# Build package
pnpm build

# Development mode with watch
pnpm dev

# Clean build artifacts
pnpm clean

# Lint code
pnpm lint

# Type checking
pnpm check-types

📝 API Reference

CountTime

Countdown timer React component.

Props:

• duration (number) - Duration in seconds
• onEndTime (function) - Callback when timer reaches zero
• isPause (boolean, optional) - Pause state (default: false)

Features:

• Automatic countdown with 1-second intervals
• Pause/resume functionality
• Automatic cleanup on unmount
• Responsive time display

formatTime

Time formatting utility function.

Parameters:

• time (number) - Time in milliseconds

Returns:

• JSX.Element - Formatted time display (HH:MM:SS)

Features:

• Converts milliseconds to HH:MM:SS format
• Handles negative values
• Responsive text sizing
• Zero-padded display

replaceYear

Year replacement utility function.

Parameters:

• year (string) - Text string containing years

Returns:

• string - Updated text with current year

Features:

• Replaces years less than current year
• Preserves current and future years
• Error handling with fallback
• Supports multiple year patterns

🤝 Contributing

1. Fork repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add some amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

📄 License

This project is part of the monorepo and follows the same license terms.

🆘 Support

For support and questions:

• Create an issue in the repository
• Check existing documentation
• Contact the development team

Note: This is a lightweight time utility package designed for use within the monorepo ecosystem. Components are optimized for performance and ease of use.

📊 Changelog

v0.0.1 (2025-01-11)

• ✅ Initial release with CountTime component
• ✅ formatTime utility function
• ✅ replaceYear utility function
• ✅ TypeScript support
• ✅ Responsive design
• ✅ Storybook integration