@fusion.dev/helix-core 0.159.0 → 0.161.0

package/dist/utils/calendar/calendar.d.ts

@@ -44,11 +44,13 @@ export type DateCalendar = 'buddhist' | 'gregory' | 'iso8601' | 'japanese' | 'ro
  * The language tag a date family formats with: `locale`, with the calendar it
  * writes dates in.
  *
- * That is `calendar` where it is one of the five `DateCalendar` names, then
- * the locale's own calendar where its months are the Gregorian months, then
- * `gregory`. **A calendar with months of its own, such as `persian` for `fa-IR`
- * or `islamic-umalqura` for `ar-SA` in some engines, is written as `gregory`.**
- * The arithmetic is Gregorian, so a heading in Mehr 1405 over the days of
+ * That is `calendar` where it names a `DateCalendar` or a `MonthCalendar`,
+ * then the locale's own calendar where its months are the Gregorian months,
+ * then `gregory`. **A calendar with months of its own that only the locale
+ * names, such as `persian` for `fa-IR` or `islamic-umalqura` for `ar-SA` in
+ * some engines, is written as `gregory`**, so a page that asked for no other
+ * calendar keeps the Gregorian dates it had. Before the date families drew
+ * such a calendar's own months, a heading in Mehr 1405 over the days of
  * October 2026 named a month the grid did not show.
  *
  * `locale` unchanged where nothing moves, so a page in a Gregorian locale
@@ -69,34 +71,55 @@ export declare const sameMonth: (left: Date, right: Date) => boolean;
  */
 export declare const addMonths: (date: Date, months: number) => Date;
 /**
- * The calendars Date Picker draws with months of their own, when `calendar`
- * names one: the months of the year in Iran, Israel, Saudi Arabia, Ethiopia,
- * Egypt's Coptic church, and India's national calendar. React Aria's
- * `createCalendar` offers the same set.
+ * The calendars the date families draw with months of their own, when
+ * `calendar` names one: the months of the year in Iran, Israel, the Islamic
+ * calendars, Ethiopia, Egypt's Coptic church, India's national calendar, and
+ * the Chinese and Korean lunisolar calendars. Every calendar `Intl` knows
+ * whose months are not the Gregorian months.
  */
-export type MonthCalendar = 'coptic' | 'ethiopic' | 'hebrew' | 'indian' | 'islamic-civil' | 'islamic-umalqura' | 'persian';
+export type MonthCalendar = 'chinese' | 'coptic' | 'dangi' | 'ethioaa' | 'ethiopic' | 'hebrew' | 'indian' | 'islamic' | 'islamic-civil' | 'islamic-rgsa' | 'islamic-tbla' | 'islamic-umalqura' | 'persian';
 /** The `MonthCalendar` names, for a check at run time. */
 export declare const MONTH_CALENDARS: readonly string[];
+/** A date as a calendar counts it: its year, its month from 1, and its day from 1. */
+export interface CalendarParts {
+    day: number;
+    month: number;
+    year: number;
+}
 /**
- * The months of a calendar, as Date Picker pages through them. Every date is
- * still a Gregorian `Date` at midnight UTC, and a month is the run of days
- * from its first.
+ * The days, months, and years of a calendar, as the date families page and
+ * edit them. Every date is still a Gregorian `Date` at midnight UTC, and a
+ * month is the run of days from its first.
  */
 export interface MonthSystem {
     /** A date some months away, its day kept where the month is long enough. */
     add(date: Date, months: number): Date;
+    /**
+     * A date some years away: the month of the same name where the year has
+     * one, so Nisan stays Nisan across a Hebrew leap year, and the day kept
+     * where the month is long enough.
+     */
+    addYears(date: Date, years: number): Date;
     /** The day of its month, from 1. */
     day(date: Date): number;
+    /** How many days a month of a year has. */
+    days(year: number, month: number): number;
+    /** The date of a year, month, and day, the month and the day kept inside the year and the month. */
+    from(year: number, month: number, day: number): Date;
     /** The month a date is in, as `month` writes it: `YYYY-MM`, or its first day where the months are the calendar's own. */
     key(date: Date): string;
+    /** How many months a year has: 12, or 13 in a Hebrew leap year, in Ethiopia, and in a Chinese leap year. */
+    months(year: number): number;
+    /** A date's year, month, and day, as the calendar counts them. */
+    parts(date: Date): CalendarParts;
     /** Whether two dates fall in one month. */
     same(left: Date, right: Date): boolean;
     /** The first day of the month a date is in. */
     start(date: Date): Date;
 }
 /**
- * The months a calendar pages through: its own for a `MonthCalendar` name,
- * and the Gregorian months for every other.
+ * The days, months, and years a calendar pages through: its own for a
+ * `MonthCalendar` name, and the Gregorian months for every other.
  */
 export declare const monthSystem: (calendar?: string) => MonthSystem;
 /** What bars a date, besides `min` and `max`. */
@@ -138,9 +161,9 @@ export declare const yearPageOf: (year: number) => number;
  */
 export declare const periodMove: (key: string, at: number, along: number) => number | null;
 /** Whether a month, as its first day, lies wholly outside `min` and `max`, either of which may be empty. */
-export declare const monthOut: (first: Date, min: string, max: string) => boolean;
+export declare const monthOut: (first: Date, min: string, max: string, system?: MonthSystem) => boolean;
 /** Whether a year lies wholly outside `min` and `max`, either of which may be empty. */
-export declare const yearOut: (year: number, min: string, max: string) => boolean;
+export declare const yearOut: (year: number, min: string, max: string, system?: MonthSystem) => boolean;
 /** One month or year in the months or the years view. */
 export interface PeriodCell {
     /** The month's index in its year, or the year. */
@@ -164,16 +187,19 @@ export interface PeriodPage {
     page: number;
     /** The first of the month the calendar shows. */
     shown: Date;
+    /** The calendar the months and the years are counted in, Gregorian where none is given. */
+    system?: MonthSystem | undefined;
     /** Today, as `YYYY-MM-DD`. */
     today: string;
     /** Which view: `month` for the months of a year, `year` for a page of years. */
     view: 'month' | 'year';
 }
 /**
- * The twelve cells of the months or the years view, in reading order: the
- * months of `page`, or the page of years that holds it.
+ * The cells of the months or the years view, in reading order: the months of
+ * `page`, twelve or the thirteen a calendar's year may have, or the twelve
+ * years on the page that holds it.
  */
-export declare const periodCells: ({ max, min, page, shown, today, view }: PeriodPage) => PeriodCell[];
+export declare const periodCells: ({ max, min, page, shown, system, today, view, }: PeriodPage) => PeriodCell[];
 /**
  * Where a key takes the tab stop in the months or the years, or `null` for a
  * key the grid leaves alone.
@@ -181,9 +207,11 @@ export declare const periodCells: ({ max, min, page, shown, today, view }: Perio
  * `stop` is the month's index or the year the stop is on, `year` the year the
  * months view shows, and `along` which way the inline keys go, as
  * `periodMove` takes it. A move off the months of one year lands in the next
- * or the last, and a move off a page of years turns the page.
+ * or the last, and a move off a page of years turns the page. `months` says
+ * how many months a year has, twelve where it is not given. The page keys
+ * move the months a year, to the month in the same place.
  */
-export declare const periodKey: (view: 'month' | 'year', stop: number, year: number, key: string, along: number) => {
+export declare const periodKey: (view: 'month' | 'year', stop: number, year: number, key: string, along: number, months?: (year: number) => number) => {
     focus: number;
     pageYear: number;
 } | null;

package/dist/utils/calendar/calendar.js

@@ -50,7 +50,7 @@ export const calendarLocale = (locale, calendar = '') => {
     let tag = tagged.get(key);
     if (tag === undefined) {
         const own = new Intl.DateTimeFormat(locale || undefined).resolvedOptions();
-        const wanted = DRAWN.includes(calendar)
+        const wanted = DRAWN.includes(calendar) || MONTH_CALENDARS.includes(calendar)
             ? calendar
             : DRAWN.includes(own.calendar)
                 ? ''
@@ -69,39 +69,64 @@ export const addMonths = (date, months) => {
     return utcDate(target.getUTCFullYear(), target.getUTCMonth(), Math.min(date.getUTCDate(), last));
 };
 export const MONTH_CALENDARS = [
+    'chinese',
     'coptic',
+    'dangi',
+    'ethioaa',
     'ethiopic',
     'hebrew',
     'indian',
+    'islamic',
     'islamic-civil',
+    'islamic-rgsa',
+    'islamic-tbla',
     'islamic-umalqura',
     'persian',
 ];
+const gregorianDays = (year, month) => utcDate(year, month, 0).getUTCDate();
 const GREGORIAN = {
     add: (date, months) => addMonths(date, months),
+    addYears: (date, years) => addMonths(date, years * 12),
     day: (date) => date.getUTCDate(),
+    days: gregorianDays,
+    from: (year, month, day) => {
+        const kept = Math.min(12, Math.max(1, month));
+        return utcDate(year, kept - 1, Math.min(Math.max(1, day), gregorianDays(year, kept)));
+    },
     key: (date) => monthOf(date),
+    months: () => 12,
+    parts: (date) => ({
+        day: date.getUTCDate(),
+        month: date.getUTCMonth() + 1,
+        year: date.getUTCFullYear(),
+    }),
     same: (left, right) => sameMonth(left, right),
     start: (date) => utcDate(date.getUTCFullYear(), date.getUTCMonth(), 1),
 };
 const intlMonths = (calendar) => {
-    const format = new Intl.DateTimeFormat(`en-u-ca-${calendar}-nu-latn`, {
-        day: 'numeric',
-        timeZone: 'UTC',
-    });
-    const days = new Map();
-    const day = (date) => {
-        const at = date.getTime();
-        let found = days.get(at);
+    const tag = `en-u-ca-${calendar}-nu-latn`;
+    const format = new Intl.DateTimeFormat(tag, { day: 'numeric', timeZone: 'UTC', year: 'numeric' });
+    const named = new Intl.DateTimeFormat(tag, { month: 'long', timeZone: 'UTC' });
+    const read = new Map();
+    const at = (date) => {
+        const time = date.getTime();
+        let found = read.get(time);
         if (found === undefined) {
-            found = Number(format.formatToParts(date).find((part) => part.type === 'day')?.value);
-            if (days.size > 4000) {
-                days.clear();
+            const parts = format.formatToParts(date);
+            const part = (type) => Number(parts.find((one) => one.type === type)?.value);
+            const year = part('relatedYear');
+            found = [Number.isNaN(year) ? part('year') : year, part('day')];
+            if (!(found[1] >= 1)) {
+                found[1] = at(addDays(date, -1))[1] + 1;
+            }
+            if (read.size > 4000) {
+                read.clear();
             }
-            days.set(at, found);
+            read.set(time, found);
         }
         return found;
     };
+    const day = (date) => at(date)[1];
     const start = (date) => addDays(date, 1 - day(date));
     const length = (first) => {
         for (const count of [29, 30, 31, 28, 32]) {
@@ -116,16 +141,78 @@ const intlMonths = (calendar) => {
         }
         return 30;
     };
+    const anchor = start(utcDate(2000, 0, 1));
+    const anchorYear = at(anchor)[0];
+    const span = 36_525 / (at(utcDate(2100, 0, 1))[0] - anchorYear);
+    const years = new Map();
+    const firsts = (year) => {
+        let found = years.get(year);
+        if (found !== undefined) {
+            return found;
+        }
+        let probe = addDays(anchor, Math.round((year - anchorYear + 0.5) * span));
+        for (let step = 0; step < 60 && at(probe)[0] !== year; step += 1) {
+            probe = addDays(probe, (year - at(probe)[0]) * 20);
+        }
+        let first = start(probe);
+        while (at(addDays(first, -1))[0] === year) {
+            const earlier = start(addDays(first, -1));
+            if (earlier.getTime() >= first.getTime()) {
+                break;
+            }
+            first = earlier;
+        }
+        found = [];
+        while (at(first)[0] === year && found.length < 14) {
+            found.push(first);
+            first = addDays(first, length(first));
+        }
+        if (years.size > 400) {
+            years.clear();
+        }
+        years.set(year, found);
+        return found;
+    };
+    const months = (year) => Math.max(1, firsts(year).length);
+    const firstOf = (year, month) => firsts(year)[Math.min(months(year), Math.max(1, month)) - 1] ?? anchor;
+    const days = (year, month) => length(firstOf(year, month));
+    const from = (year, month, wanted) => {
+        const first = firstOf(year, month);
+        return addDays(first, Math.min(Math.max(1, wanted), length(first)) - 1);
+    };
+    const parts = (date) => {
+        const [year, dayOf] = at(date);
+        const all = firsts(year);
+        let month = all.length;
+        while (month > 1 && all[month - 1].getTime() > date.getTime()) {
+            month -= 1;
+        }
+        return { day: dayOf, month, year };
+    };
     return {
-        add: (date, months) => {
+        add: (date, count) => {
             let first = start(date);
-            for (let step = 0; step < Math.abs(months); step += 1) {
-                first = months > 0 ? addDays(first, length(first)) : start(addDays(first, -1));
+            for (let step = 0; step < Math.abs(count); step += 1) {
+                first = count > 0 ? addDays(first, length(first)) : start(addDays(first, -1));
             }
             return addDays(first, Math.min(day(date), length(first)) - 1);
         },
+        addYears: (date, count) => {
+            const { day: dayOf, month, year } = parts(date);
+            const name = named.format(firstOf(year, month));
+            const names = firsts(year + count).map((first) => named.format(first));
+            let index = names.indexOf(name);
+            if (index < 0) {
+                index = names.findLastIndex((one) => one.startsWith(name) || name.startsWith(one));
+            }
+            return from(year + count, index < 0 ? month : index + 1, dayOf);
+        },
         day,
+        days,
+        from,
         key: (date) => fromDate(start(date)),
+        months,
+        parts,
         same: (left, right) => start(left).getTime() === start(right).getTime(),
         start,
     };
@@ -181,27 +268,29 @@ export const periodMove = (key, at, along) => {
             return null;
     }
 };
-export const monthOut = (first, min, max) => {
-    const month = monthOf(first);
-    return (min !== '' && month < min.slice(0, 7)) || (max !== '' && month > max.slice(0, 7));
-};
-export const yearOut = (year, min, max) => (min !== '' && year < Number(min.slice(0, 4))) || (max !== '' && year > Number(max.slice(0, 4)));
-export const periodCells = ({ max, min, page, shown, today, view }) => {
+export const monthOut = (first, min, max, system = GREGORIAN) => (min !== '' && fromDate(addDays(system.add(first, 1), -1)) < min) ||
+    (max !== '' && fromDate(first) > max);
+export const yearOut = (year, min, max, system = GREGORIAN) => (min !== '' && fromDate(addDays(system.from(year + 1, 1, 1), -1)) < min) ||
+    (max !== '' && fromDate(system.from(year, 1, 1)) > max);
+export const periodCells = ({ max, min, page, shown, system = GREGORIAN, today, view, }) => {
     const years = view === 'year';
-    const start = years ? yearPageOf(page) : page;
-    return Array.from({ length: 12 }, (_, index) => {
-        const at = years ? start + index : index;
-        const first = utcDate(years ? at : start, years ? 0 : index, 1);
+    const now = asDate(today);
+    const held = system.parts(shown).year;
+    const count = years ? YEARS_SHOWN : system.months(page);
+    const startYear = years ? yearPageOf(page) : page;
+    return Array.from({ length: count }, (_, index) => {
+        const at = years ? startYear + index : index;
+        const first = years ? system.from(at, 1, 1) : system.from(page, index + 1, 1);
         return {
             at,
-            chosen: years ? at === shown.getUTCFullYear() : monthOf(first) === monthOf(shown),
-            current: years ? String(at) === today.slice(0, 4) : monthOf(first) === today.slice(0, 7),
+            chosen: years ? at === held : system.same(first, shown),
+            current: now !== null && (years ? system.parts(now).year === at : system.same(first, now)),
             first,
-            out: years ? yearOut(at, min, max) : monthOut(first, min, max),
+            out: years ? yearOut(at, min, max, system) : monthOut(first, min, max, system),
         };
     });
 };
-export const periodKey = (view, stop, year, key, along) => {
+export const periodKey = (view, stop, year, key, along, months = () => 12) => {
     const index = view === 'year' ? stop - yearPageOf(stop) : stop;
     const delta = periodMove(key, index, along);
     if (delta === null) {
@@ -210,6 +299,19 @@ export const periodKey = (view, stop, year, key, along) => {
     if (view === 'year') {
         return { focus: stop + delta, pageYear: stop + delta };
     }
-    const months = year * 12 + stop + delta;
-    return { focus: ((months % 12) + 12) % 12, pageYear: Math.floor(months / 12) };
+    if (key === 'PageUp' || key === 'PageDown') {
+        const to = year + Math.sign(delta);
+        return { focus: Math.min(stop, months(to) - 1), pageYear: to };
+    }
+    let at = stop + delta;
+    let on = year;
+    while (at < 0) {
+        on -= 1;
+        at += months(on);
+    }
+    while (at >= months(on)) {
+        at -= months(on);
+        on += 1;
+    }
+    return { focus: at, pageYear: on };
 };

package/dist/utils/date-segments/date-segments.d.ts

@@ -1,9 +1,11 @@
+import type { MonthSystem } from '../calendar/calendar.js';
 /** One part of a date or a time a reader sets on its own. */
 export type SegmentKind = 'day' | 'dayPeriod' | 'hour' | 'minute' | 'month' | 'second' | 'year';
 /** What a segmented field holds: a date, or a time of day. */
 export type SegmentedKind = 'date' | 'time';
 /**
- * The parts set so far, each a number: the month 1 to 12, the hour 0 to 23
+ * The parts set so far, each a number: the month 1 to 12, or to 13 in a
+ * calendar whose year can have 13, the hour 0 to 23
  * whatever clock it is shown on, and the half of the day 0 for before noon and
  * 1 for after. A part not yet set is absent.
  */
@@ -37,7 +39,7 @@ export declare const isTwelveHourLayout: (layout: readonly SegmentSlot[]) => boo
  * The lowest and highest a segment can be, as it is shown: the hour on a twelve
  * hour clock is 1 to 12, and a day goes as high as its month allows.
  */
-export declare const segmentRange: (kind: SegmentKind, segments: Segments, twelve: boolean) => {
+export declare const segmentRange: (kind: SegmentKind, segments: Segments, twelve: boolean, system?: MonthSystem) => {
     max: number;
     min: number;
 };
@@ -45,16 +47,16 @@ export declare const segmentRange: (kind: SegmentKind, segments: Segments, twelv
 export declare const shownValue: (kind: SegmentKind, segments: Segments, twelve: boolean) => number | undefined;
 /**
  * Sets a segment from the number shown for it, which on a twelve hour clock
- * is put back together with the half of the day, and keeps the day inside its
- * month.
+ * is put back together with the half of the day, and keeps the month inside
+ * its year and the day inside its month.
  */
-export declare const setSegment: (segments: Segments, kind: SegmentKind, shown: number | undefined, twelve: boolean) => Segments;
+export declare const setSegment: (segments: Segments, kind: SegmentKind, shown: number | undefined, twelve: boolean, system?: MonthSystem) => Segments;
 /**
  * A segment moved by a key's step, wrapping at its ends as a dial does, and
  * starting from where a reader would look for it when it is empty: the lowest
  * going up, the highest going down, and this year for a year.
  */
-export declare const stepSegment: (segments: Segments, kind: SegmentKind, by: number, twelve: boolean, thisYear?: number) => Segments;
+export declare const stepSegment: (segments: Segments, kind: SegmentKind, by: number, twelve: boolean, thisYear?: number, system?: MonthSystem) => Segments;
 /**
  * A digit typed into a segment, given what was typed into it already.
  *
@@ -64,7 +66,7 @@ export declare const stepSegment: (segments: Segments, kind: SegmentKind, by: nu
  * on, which is React Aria's typing: `3` in a month is March and moves to the
  * day, `1` waits for a second digit.
  */
-export declare const typeDigit: (segments: Segments, kind: SegmentKind, typed: string, digit: string, twelve: boolean) => {
+export declare const typeDigit: (segments: Segments, kind: SegmentKind, typed: string, digit: string, twelve: boolean, system?: MonthSystem) => {
     advance: boolean;
     segments: Segments;
     typed: string;
@@ -77,6 +79,8 @@ export interface SegmentKeyState {
     locale: string;
     /** The field's parts. */
     segments: Segments;
+    /** The calendar a date's parts are counted in, Gregorian where none is given. */
+    system?: MonthSystem | undefined;
     /** Whether the field is on a twelve hour clock. */
     twelve: boolean;
     /** The digits typed into the segment so far. */
@@ -92,13 +96,16 @@ export interface SegmentKeyState {
  * the half whose word starts with it. `advance` says the segment is full and
  * focus moves on.
  */
-export declare const segmentKey: (key: string, { kind, locale, segments, twelve, typed }: SegmentKeyState) => {
+export declare const segmentKey: (key: string, { kind, locale, segments, system, twelve, typed }: SegmentKeyState) => {
     advance: boolean;
     segments: Segments;
     typed: string;
 } | null;
-/** The segments a value names, or none where it names nothing whole. */
-export declare const segmentsOf: (kind: SegmentedKind, value: string) => Segments;
+/**
+ * The segments a value names, or none where it names nothing whole: a date's
+ * year, month, and day as `system` counts them, Gregorian where none is given.
+ */
+export declare const segmentsOf: (kind: SegmentedKind, value: string, system?: MonthSystem) => Segments;
 /**
  * The value the segments add up to, or the empty string while any segment the
  * layout shows is unset.
@@ -106,9 +113,9 @@ export declare const segmentsOf: (kind: SegmentedKind, value: string) => Segment
  * A date that does not exist, the thirtieth of February, cannot be reached,
  * the day being kept inside its month as it is set.
  */
-export declare const segmentsValue: (kind: SegmentedKind, segments: Segments, layout: readonly SegmentSlot[]) => string;
+export declare const segmentsValue: (kind: SegmentedKind, segments: Segments, layout: readonly SegmentSlot[], system?: MonthSystem) => string;
 /** Whether a reader has set some segments and not all of them. */
-export declare const isPartial: (kind: SegmentedKind, segments: Segments, layout: readonly SegmentSlot[]) => boolean;
+export declare const isPartial: (kind: SegmentedKind, segments: Segments, layout: readonly SegmentSlot[], system?: MonthSystem) => boolean;
 /**
  * What a segment shows: its number, padded the way the locale pads it, the
  * locale's own word for the half of the day, or dashes while it is unset.
@@ -117,8 +124,33 @@ export declare const segmentText: (kind: SegmentKind, segments: Segments, twelve
 /**
  * What a screen reader hears for a segment's value: what it shows, and for a
  * month its name as well, "8 – August", which is React Aria's reading. A
- * month heard as a number alone leaves a reader counting.
+ * month heard as a number alone leaves a reader counting. In a calendar with
+ * months of its own, the name is that calendar's month in the year the
+ * segments hold, or in this year: "7 – Mehr".
  */
-export declare const segmentValueText: (kind: SegmentKind, segments: Segments, twelve: boolean, locale: string) => string;
+export declare const segmentValueText: (kind: SegmentKind, segments: Segments, twelve: boolean, locale: string, system?: MonthSystem) => string;
 /** What a locale calls a segment, such as "month" or "AM/PM", from `Intl`. */
 export declare const segmentName: (kind: SegmentKind, locale: string) => string;
+/**
+ * The date a reader wrote in the order and the digits of `locale`, as
+ * `YYYY-MM-DD`, or empty where it is no date.
+ *
+ * `8/4/2026` in `en-US` and `4.8.2026` in `de-DE` are August 4, 2026, and a
+ * month written as a word, `Aug 4, 2026` or `4. August 2026`, is read by its
+ * name in the Gregorian calendar. A first number of four digits is a year,
+ * as ISO writes it. A year of two digits is the nearest year within eighty
+ * years back and twenty forward. `Intl` formats and does not parse, so this
+ * reads the numbers back in the order `segmentLayout` finds the locale
+ * writing them. Under `system`, the numbers are that calendar's year, month,
+ * and day.
+ */
+export declare const readWrittenDate: (text: string, locale: string, system?: MonthSystem) => string;
+/**
+ * The time a reader wrote, as `HH:mm`, or `HH:mm:ss` with `seconds`, or empty
+ * where it is no time.
+ *
+ * Reads `2:30 PM`, `2.30pm`, `14h30`, and `3 pm` alike, with the half of the
+ * day in the locale's own words or as `am` and `pm`, and digits in the
+ * locale's own script.
+ */
+export declare const readWrittenTime: (text: string, locale: string, seconds?: boolean) => string;