@astryxdesign/core 0.7.8 → 0.7.9-canary.0200dfe

package/dist/utils/calendarSystem.d.ts

@@ -0,0 +1,176 @@
+/**
+ * @file calendarSystem.ts
+ * @input A calendar identifier and Gregorian PlainDates
+ * @output Calendar months located by their Gregorian days, their year and
+ *   month numbers, month and year steps, dates from calendar fields,
+ *   availability of each calendar, and calendar labels and digits
+ * @position Shared date utility; read by the i18n calendar resolution, by
+ *   the date components, and by Calendar's public hooks. Values stay Gregorian PlainDates. Temporal owns the arithmetic of
+ *   every calendar whose months are not Gregorian.
+ */
+import type { Locale } from '../i18n/types.js';
+import type { PlainDate } from './dateTypes.js';
+/**
+ * A calendar system that date components can show: the calendars that
+ * ECMA-402 and Temporal require. Values stay Gregorian ISO dates in every
+ * calendar.
+ */
+export type CalendarSystem = 'gregory' | 'iso8601' | 'buddhist' | 'roc' | 'japanese' | 'persian' | 'indian' | 'hebrew' | 'chinese' | 'dangi' | 'coptic' | 'ethiopic' | 'ethioaa' | 'islamic-civil' | 'islamic-tbla' | 'islamic-umalqura';
+export declare const CALENDAR_SYSTEMS: ReadonlyArray<CalendarSystem>;
+/**
+ * Whether `<input type="date">` can show the calendar. The native control is
+ * Gregorian by specification, so only `gregory` and `iso8601` qualify.
+ */
+export declare function isGregorianCalendar(calendar: CalendarSystem): boolean;
+/** Whether the calendar's months and days are the Gregorian ones. */
+export declare function isGregorianAligned(calendar: CalendarSystem): boolean;
+export declare function isCalendarSystem(value: string): value is CalendarSystem;
+/**
+ * Whether this runtime can show the calendar. Gregorian-aligned calendars
+ * always can. The others need a `Temporal` that knows the calendar: a
+ * polyfill build without non-ISO calendars throws for them.
+ */
+export declare function isCalendarSystemAvailable(calendar: CalendarSystem): boolean;
+/** A month of a calendar, located by its first and last Gregorian days. */
+export interface CalendarMonth {
+    readonly start: PlainDate;
+    readonly end: PlainDate;
+    readonly length: number;
+}
+/** The day of the calendar month that a Gregorian date falls on. */
+export declare function calendarDayOfMonth(calendar: CalendarSystem, pd: PlainDate): number;
+/** The calendar month that contains a Gregorian date. */
+export declare function calendarMonthOf(calendar: CalendarSystem, pd: PlainDate): CalendarMonth;
+/**
+ * A calendar month by its year and its position in that year, as
+ * `Temporal.PlainDate` numbers them: month 13 exists in a Hebrew leap year.
+ */
+export interface CalendarYearMonth {
+    readonly year: number;
+    readonly month: number;
+}
+/** The year and month numbers of a calendar month. */
+export declare function calendarYearMonthOf(calendar: CalendarSystem, month: CalendarMonth): CalendarYearMonth;
+/**
+ * The calendar month with these year and month numbers. A month past the end
+ * of its year becomes the last month of that year, as Temporal constrains it.
+ */
+export declare function calendarMonthFromYearMonth(calendar: CalendarSystem, { year, month }: CalendarYearMonth): CalendarMonth;
+/** The calendar month `n` months after `month`, or before it when negative. */
+export declare function calendarAddMonths(calendar: CalendarSystem, month: CalendarMonth, n: number): CalendarMonth;
+/**
+ * Moves a date by `n` calendar months. It keeps the day of the month and
+ * clamps it to the length of the target month.
+ */
+export declare function calendarShiftMonths(calendar: CalendarSystem, pd: PlainDate, n: number): PlainDate;
+/**
+ * Moves a date by `n` calendar years, to the same month of the target year.
+ * It clamps the day of the month. A leap month that the target year does not
+ * have becomes its common counterpart, because Temporal keeps the month code
+ * and constrains it.
+ */
+export declare function calendarShiftYears(calendar: CalendarSystem, pd: PlainDate, n: number): PlainDate;
+/** Whether a Gregorian date falls inside a calendar month. */
+export declare function isInCalendarMonth(pd: PlainDate, month: CalendarMonth): boolean;
+/**
+ * The day that names a calendar month: its middle day. In the Japanese
+ * calendar an era can start inside a month, and most days of that month then
+ * belong to the era of its middle day.
+ */
+export declare function calendarMonthLabelDay(month: CalendarMonth): PlainDate;
+/**
+ * The stand-alone month and year label of a calendar month, such as
+ * "Aban 1405 AP", named by `calendarMonthLabelDay`. When `day` is given and the
+ * month spans an era change, it formats that day instead, clamped to the
+ * month, so January 1989 reads 昭和64年1月 on the 3rd and 平成元年1月 on the
+ * 22nd.
+ */
+export declare function formatCalendarMonthLabel(calendar: CalendarSystem, month: CalendarMonth, locale: Locale, day?: number): string;
+/**
+ * Formats a Gregorian date in the calendar, such as "Friday, Aban 8, 1405 AP".
+ * The label always names the month and day that the grid shows. Intl and the
+ * runtime's Temporal can disagree on where a month of the Chinese or Dangi
+ * calendar starts; the label then takes its month and year from the middle of
+ * the Temporal month, and its day from Temporal. With `relatedYear`, a
+ * Chinese or Dangi year that the locale names only by its place in the 60-year
+ * cycle becomes the related Gregorian year.
+ */
+export declare function formatCalendarDate(calendar: CalendarSystem, pd: PlainDate, options: Intl.DateTimeFormatOptions, locale: Locale, labelOptions?: {
+    readonly relatedYear?: boolean;
+}): string;
+/** The parts of `formatCalendarDate`'s label. */
+export declare function formatCalendarDateToParts(calendar: CalendarSystem, pd: PlainDate, options: Intl.DateTimeFormatOptions, locale: Locale, { relatedYear }?: {
+    readonly relatedYear?: boolean;
+}): Intl.DateTimeFormatPart[];
+/**
+ * Formats an instant as `formatCalendarDate` formats the day it falls on in
+ * `timeZone`, the host's zone when omitted. Intl writes any time of day that
+ * `options` asks for.
+ */
+export declare function formatCalendarInstant(calendar: CalendarSystem, instant: Date, options: Intl.DateTimeFormatOptions, locale: Locale, timeZone?: string): string;
+/**
+ * Formats the range between two instants. Intl writes the fields that both
+ * ends share once. Where Intl names another month or day than Temporal at
+ * either end, the range writes each end in full.
+ */
+export declare function formatCalendarInstantRange(calendar: CalendarSystem, start: Date, end: Date, options: Intl.DateTimeFormatOptions, locale: Locale, timeZone?: string): string;
+/**
+ * The fields of a date written in a calendar. A field gives either `year` or
+ * `era` with `eraYear`, and either `monthCode` (such as `M05L` for a leap
+ * month) or `month`, the month's position in its year.
+ */
+export interface CalendarDateFields {
+    readonly year?: number;
+    readonly era?: string;
+    readonly eraYear?: number;
+    readonly monthCode?: string;
+    readonly month?: number;
+    readonly day: number;
+}
+/**
+ * The Gregorian date for fields written in a calendar that needs Temporal,
+ * or null when the calendar does not have that date. Temporal validates the
+ * fields and never adjusts them: 30 Esfand in a common Persian year is null.
+ */
+export declare function calendarDateFromFields(calendar: CalendarSystem, fields: CalendarDateFields): PlainDate | null;
+/** The number of months in the calendar year that contains a date. */
+export declare function calendarMonthsInYear(calendar: CalendarSystem, pd: PlainDate): number;
+/**
+ * The number of calendar months from the month `from` to the month `to`:
+ * positive when `to` is later.
+ */
+export declare function calendarMonthsBetween(calendar: CalendarSystem, from: CalendarMonth, to: CalendarMonth): number;
+/**
+ * The calendar month at a position in a year of the calendar. A
+ * Gregorian-aligned calendar counts Gregorian years here; the others count
+ * years as {@link calendarYearMonthOf} does.
+ */
+export declare function calendarMonthOfYear(calendar: CalendarSystem, year: number, month: number): CalendarMonth;
+/** The number of months in a year of the calendar. */
+export declare function calendarMonthsInCalendarYear(calendar: CalendarSystem, year: number): number;
+/**
+ * The name of a calendar month, such as "Adar I". It formats the middle day of
+ * the month, for the reason {@link formatCalendarMonthLabel} gives.
+ */
+export declare function formatCalendarMonthName(calendar: CalendarSystem, month: CalendarMonth, locale: Locale): string;
+/**
+ * Whether the first and last days of a year of the calendar fall in different
+ * eras, as the Japanese year 2019 does (Heisei, then Reiwa). Only an era change
+ * counts: other parts, such as a Chinese related year, can disagree at the
+ * edges of a year when Intl and Temporal place a month start one day apart.
+ */
+export declare function calendarYearSpansEras(calendar: CalendarSystem, year: number, locale: Locale): boolean;
+/**
+ * The label of a year of the calendar, with its era where the locale writes
+ * one in a date, such as "令和8" in `ja-JP` or "1405 AP" in English. It uses the
+ * era and year parts of a long date, in the locale's order and digits, with the
+ * text between them. A year that spans an era change takes its era from `at`,
+ * a month position and a day clamped to that month, so 2019 reads "平成31" in
+ * January and "令和元" in May. Without `at`, and for every other year, the label
+ * comes from the middle of the year. Gregorian years are plain numbers.
+ */
+export declare function formatCalendarYearLabel(calendar: CalendarSystem, year: number, locale: Locale, at?: {
+    readonly month: number;
+    readonly day: number;
+}): string;
+//# sourceMappingURL=calendarSystem.d.ts.map

package/dist/utils/calendarSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calendarSystem.d.ts","sourceRoot":"","sources":["../../src/utils/calendarSystem.ts"],"names":[],"mappings":"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"}