tessl/npm-date-io--moment

TypeScript adapter providing a unified interface for the Moment.js date library through the date-io abstraction layer.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Localization Support

Name: tessl/npm-date-io--moment
Author: tessl

This capability provides comprehensive localization functionality including locale detection, meridiem text, format helpers, and locale-specific date/time behavior. All localization features respect the locale specified during MomentUtils initialization.

Locale Information

Current Locale Code

getCurrentLocaleCode(): string

Returns the current locale code being used by the MomentUtils instance.

Returns: ISO locale code string (e.g., "en", "fr", "de", "es")

Usage:

// Default instance (usually "en")
const defaultUtils = new MomentUtils();
const defaultLocale = defaultUtils.getCurrentLocaleCode(); // "en"

// Specific locale
const frenchUtils = new MomentUtils({ locale: "fr" });
const frenchLocale = frenchUtils.getCurrentLocaleCode(); // "fr"

// Dynamic locale checking
function formatDateForUser(date: Moment, utils: MomentUtils) {
  const locale = utils.getCurrentLocaleCode();
  console.log(`Formatting date for locale: ${locale}`);
  
  switch (locale) {
    case "en":
      return utils.format(date, "fullDate"); // "Oct 30, 2023"
    case "fr":
      return utils.format(date, "fullDate"); // "30 oct. 2023"
    default:
      return utils.toISO(date); // Fallback to ISO format
  }
}

Time Format Detection

12-Hour Cycle Detection

is12HourCycleInCurrentLocale(): boolean

Determines if the current locale typically uses 12-hour time format (with AM/PM) or 24-hour format.

Returns: true if locale uses 12-hour format, false for 24-hour format

Usage:

// US English - typically uses 12-hour format
const usUtils = new MomentUtils({ locale: "en" });
const uses12Hour = usUtils.is12HourCycleInCurrentLocale(); // true

// German - typically uses 24-hour format
const deUtils = new MomentUtils({ locale: "de" });
const germanUses12Hour = deUtils.is12HourCycleInCurrentLocale(); // false

// Adaptive time formatting based on locale
function formatTimeForLocale(date: Moment, utils: MomentUtils) {
  if (utils.is12HourCycleInCurrentLocale()) {
    return utils.format(date, "fullTime12h"); // "2:30:45 PM"
  } else {
    return utils.format(date, "fullTime24h"); // "14:30:45"
  }
}

// Building locale-aware time picker
function buildTimePicker(utils: MomentUtils) {
  const is12Hour = utils.is12HourCycleInCurrentLocale();
  
  return {
    format: is12Hour ? "h:mm A" : "HH:mm",
    showMeridiem: is12Hour,
    hourRange: is12Hour ? [1, 12] : [0, 23],
    defaultTime: is12Hour ? "12:00 PM" : "12:00"
  };
}

Format Helper Text

Format Helper Generation

getFormatHelperText(format: string): string

Generates user-friendly helper text that describes what a given format string will produce. This is particularly useful for showing users examples of expected input formats in different locales.

Parameters:

format - Moment.js format string to generate helper text for

Returns: Localized helper text showing the format pattern

Usage:

const utils = new MomentUtils({ locale: "en" });

// Common format helpers
const dateHelper = utils.getFormatHelperText("YYYY-MM-DD"); // "yyyy-mm-dd"
const timeHelper = utils.getFormatHelperText("HH:mm"); // "hh:mm"
const datetimeHelper = utils.getFormatHelperText("YYYY-MM-DD HH:mm"); // "yyyy-mm-dd hh:mm"

// Format-specific helpers
const shortDateHelper = utils.getFormatHelperText("MM/DD/YYYY"); // "mm/dd/yyyy"
const longDateHelper = utils.getFormatHelperText("MMMM Do, YYYY"); // "mmmm do, yyyy"

// Practical usage in forms
function createDateInput(format: string, utils: MomentUtils) {
  const helperText = utils.getFormatHelperText(format);
  
  return {
    placeholder: `Enter date (${helperText})`,
    helperText: `Format: ${helperText}`,
    pattern: format.toLowerCase().replace(/[a-z]/g, '\\d')
  };
}

const dateInput = createDateInput("DD/MM/YYYY", utils);
// {
//   placeholder: "Enter date (dd/mm/yyyy)",
//   helperText: "Format: dd/mm/yyyy",
//   pattern: "\\d\\d/\\d\\d/\\d\\d\\d\\d"
// }

Meridiem Text

AM/PM Localization

getMeridiemText(ampm: "am" | "pm"): string

Returns localized text for AM/PM indicators according to the current locale.

Parameters:

ampm - Either "am" or "pm"

Returns: Localized meridiem text

Usage:

// English locale
const enUtils = new MomentUtils({ locale: "en" });
const enAM = enUtils.getMeridiemText("am"); // "AM"
const enPM = enUtils.getMeridiemText("pm"); // "PM"

// French locale
const frUtils = new MomentUtils({ locale: "fr" });
const frAM = frUtils.getMeridiemText("am"); // "AM" (or locale-specific equivalent)
const frPM = frUtils.getMeridiemText("pm"); // "PM" (or locale-specific equivalent)

// Building custom time display
function formatCustomTime(date: Moment, utils: MomentUtils) {
  if (utils.is12HourCycleInCurrentLocale()) {
    const hour = utils.getHours(date);
    const minute = utils.getMinutes(date);
    const isAM = hour < 12;
    const displayHour = hour === 0 ? 12 : hour > 12 ? hour - 12 : hour;
    const meridiem = utils.getMeridiemText(isAM ? "am" : "pm");
    
    return `${displayHour}:${minute.toString().padStart(2, '0')} ${meridiem}`;
  } else {
    return utils.formatByString(date, "HH:mm");
  }
}

// Custom time picker with localized meridiem
function buildMeridiemSelector(utils: MomentUtils) {
  if (!utils.is12HourCycleInCurrentLocale()) {
    return null; // No meridiem selector needed for 24-hour format
  }
  
  return {
    am: {
      value: "am",
      label: utils.getMeridiemText("am")
    },
    pm: {
      value: "pm", 
      label: utils.getMeridiemText("pm")
    }
  };
}

Locale-Specific Behavior Examples

Multi-Locale Date Formatting

// Demonstrate formatting differences across locales
function demonstrateLocaleFormatting() {
  const date = utils.parseISO("2023-10-30T14:30:45.000Z");
  const locales = ["en", "fr", "de", "es", "ja"];
  
  locales.forEach(locale => {
    const localeUtils = new MomentUtils({ locale });
    
    console.log(`Locale: ${locale}`);
    console.log(`  Full Date: ${localeUtils.format(date, "fullDate")}`);
    console.log(`  Full Time: ${localeUtils.format(date, "fullTime")}`);
    console.log(`  12-Hour Format: ${localeUtils.is12HourCycleInCurrentLocale()}`);
    console.log(`  Weekdays: ${localeUtils.getWeekdays().join(", ")}`);
    console.log(`  AM Text: ${localeUtils.getMeridiemText("am")}`);
    console.log(`  PM Text: ${localeUtils.getMeridiemText("pm")}`);
    console.log("---");
  });
}

Locale-Aware Component Factory

function createLocalizedDatePicker(locale: string) {
  const utils = new MomentUtils({ locale });
  const is12Hour = utils.is12HourCycleInCurrentLocale();
  
  return {
    locale: utils.getCurrentLocaleCode(),
    
    // Time format configuration
    timeFormat: is12Hour ? "h:mm A" : "HH:mm",
    showMeridiem: is12Hour,
    meridiemLabels: is12Hour ? {
      am: utils.getMeridiemText("am"),
      pm: utils.getMeridiemText("pm")
    } : null,
    
    // Calendar configuration
    weekdays: utils.getWeekdays(),
    firstDayOfWeek: utils.startOfWeek(utils.date()).day(),
    
    // Format helpers for user input
    dateFormatHelper: utils.getFormatHelperText("YYYY-MM-DD"),
    timeFormatHelper: utils.getFormatHelperText(is12Hour ? "h:mm A" : "HH:mm"),
    
    // Utility methods bound to this locale
    formatDate: (date: Moment) => utils.format(date, "fullDate"),
    formatTime: (date: Moment) => utils.format(date, is12Hour ? "fullTime12h" : "fullTime24h"),
    formatDateTime: (date: Moment) => utils.format(date, is12Hour ? "fullDateTime12h" : "fullDateTime24h")
  };
}

// Usage examples
const englishPicker = createLocalizedDatePicker("en");
const frenchPicker = createLocalizedDatePicker("fr");
const germanPicker = createLocalizedDatePicker("de");

// Each picker is configured for its specific locale
console.log(englishPicker.timeFormat); // "h:mm A"
console.log(frenchPicker.timeFormat);  // "HH:mm" (assuming French uses 24-hour)
console.log(germanPicker.weekdays[0]); // "Montag"

Custom Locale Configuration

// Example of using custom moment instance with specific locale
import moment from 'moment';
import 'moment/locale/fr'; // Import French locale

const customMoment = moment();
customMoment.locale('fr');

const customUtils = new MomentUtils({ 
  locale: "fr",
  instance: customMoment,
  formats: {
    // Override formats for French users
    fullDate: "DD MMMM YYYY",  // "30 octobre 2023"
    shortDate: "DD/MM/YYYY",   // "30/10/2023"
    fullTime: "HH:mm:ss"       // "14:30:45"
  }
});

const date = customUtils.parseISO("2023-10-30T14:30:45.000Z");
console.log(customUtils.format(date, "fullDate")); // "30 octobre 2023"
console.log(customUtils.getCurrentLocaleCode()); // "fr"