date-formatting

name	date-formatting
description	Date and time formatting for applications. Use when displaying dates, timestamps, or formatting time in UI components. Use centralized utilities instead of native JS date methods. Triggers on date, time, timestamp, formatDate, formatTime, toLocaleDateString, toLocaleString, dateUtils, locale, format, display date, show time, datetime, calendar.
allowed-tools	Read, Grep, Glob

Date Formatting

Guidelines for consistent date and time formatting across applications.

Critical Rule

Use centralized date utilities for consistency:

// ❌ AVOID - Inconsistent across locales/platforms
date.toLocaleDateString()
date.toLocaleString()
new Intl.DateTimeFormat().format(date)

// ✅ CORRECT - Use centralized utility
import { formatDate } from '@{scope}/shared/src/utils/dateUtils';
formatDate(date, { hideSeconds: true });

Quick Reference

Function	Use Case	Example Output
formatDate(date, options?)	Full date and time	2024/01/15, 14:30
formatTime(date, options?)	Time only	14:30:45
formatRelativeDate(date)	Relative display	Today, Yesterday
formatDistanceToNow(date)	Time distance	2 hours ago
formatDateFns(date, format?)	Custom format	Based on template

Common Patterns

Transaction History

import { formatDate } from '@{scope}/shared/src/utils/dateUtils';

// Hide year if current year, hide seconds
<Text>
  {formatDate(item.createdAt, { hideTheYear: true, hideSeconds: true })}
</Text>

Custom Format

// Use format template
{formatDate(item.timestamp, { formatTemplate: 'yyyy-LL-dd HH:mm' })}

React Hook (for dynamic updates)

import { useFormatDate } from '@{scope}/kit/src/hooks/useFormatDate';

function MyComponent() {
  const { formatDate } = useFormatDate();
  return <Text>{formatDate(date, { hideSeconds: true })}</Text>;
}

Format Options

interface IFormatDateOptions {
  hideYear?: boolean;        // Always hide year
  hideMonth?: boolean;       // Always hide month
  hideTheYear?: boolean;     // Hide year if current year
  hideTheMonth?: boolean;    // Hide month if current month
  hideTimeForever?: boolean; // Hide time portion
  hideSeconds?: boolean;     // Hide seconds (HH:mm)
  formatTemplate?: string;   // Custom date-fns format
}

Detailed Guide

For comprehensive date formatting rules and examples, see date-formatting.md.

Topics covered:

• Core utilities for date formatting
• Available formatting functions
• Options reference and format templates
• Common patterns for transactions, history, and relative time
• React hooks for dynamic updates
• Locale-aware formatting
• Real-world examples
• Troubleshooting

Key Files (Example Structure)

Purpose	File Path
Core utilities	packages/shared/src/utils/dateUtils.ts
React hook	packages/kit/src/hooks/useFormatDate.ts
Locale mapping	packages/shared/src/locale/dateLocaleMap.ts

Related Skills

• /i18n - Internationalization and locale handling
• /coding-patterns - General coding patterns