ngwr 13.0.0 → 14.0.0

package/fesm2022/ngwr-date.mjs

@@ -1,6 +1,5 @@
 import * as i0 from '@angular/core';
-import { InjectionToken, inject, PLATFORM_ID, Service, makeEnvironmentProviders } from '@angular/core';
-import { isPlatformBrowser } from '@angular/common';
+import { InjectionToken, inject, LOCALE_ID, Service, makeEnvironmentProviders } from '@angular/core';
 
 /**
  * @license
@@ -42,31 +41,38 @@ class WrDateAdapter {
  */
 /**
  * BCP 47 locale tag the {@link WrDateAdapter} implementations read. Defaults to
- * `navigator.language` in the browser and `'en-US'` on the server; override via
- * {@link provideWrDateAdapter}'s `locale` option.
+ * Angular's `LOCALE_ID`; override via {@link provideWrDateAdapter}'s `locale`
+ * option.
+ *
+ * **It used to default to `navigator.language`, and that was wrong in the
+ * documented case.** The provider's own first example is the no-argument call,
+ * so the path a reader copies was the broken one: an app that set
+ * `LOCALE_ID: 'ru-RU'` and translated every string still rendered `March 2026`,
+ * `SUN MON TUE …` and a week starting on Sunday, because the calendar was
+ * asking the browser rather than the application. `navigator.language` is the
+ * user's browser preference; `LOCALE_ID` is what the app says it is, and only
+ * the app can be right about that. Reading the browser also made a prerendered
+ * page and its hydrated self disagree — the server has no `navigator.language`
+ * to match. An app that genuinely wants the browser's tag can still say so:
+ * `provideWrDateAdapter({ locale: navigator.language })`.
+ *
+ * The token is a plain string, resolved once. It is therefore the *pinned* date
+ * locale, not a live one — `WrI18n.use()` moves catalog text and cannot move
+ * this. `WrI18n`'s class docs carry the full precedence and `use()` warns about
+ * the gap in dev mode.
  *
  * **How far it reaches depends on the adapter, and the difference matters.**
- * The luxon adapter threads it through everything — every `DateTime` is
- * constructed with it, and `format` / `parse` call `setLocale`. The date-fns
- * adapter reads it only for locale-DERIVED defaults (first day of week); its
- * `format` and `parse` pass no locale to date-fns, so they stay on that
- * library's module default. Setting this token and expecting French month names
- * out of `WrDateFnsAdapter` gets English ones, and the parse side of that
- * mismatch is silent rather than loud — see the adapter's own class docs for the
- * lever (`setDefaultOptions`).
+ * The native and luxon adapters thread it through everything. The date-fns
+ * adapter cannot: date-fns resolves its patterns against a `Locale` OBJECT, not
+ * a tag, so this token drives only the parts that go through `Intl` (the month
+ * and weekday names) and the OBJECT drives `format` / `parse`. Pass it as
+ * `provideWrDateFnsAdapter({ dateFnsLocale: ru })` — with only a tag the calendar
+ * headings localize and the field does not, which the adapter warns about once
+ * in dev mode.
  */
 const WR_DATE_LOCALE = new InjectionToken('WR_DATE_LOCALE', {
     providedIn: 'root',
-    factory: () => {
-        // Node 21+ also defines `navigator`, and reports the *build machine's*
-        // locale — so a `typeof` probe silently bakes that locale into
-        // prerendered output (wrong month names, wrong first day of week).
-        // Ask the platform instead.
-        if (isPlatformBrowser(inject(PLATFORM_ID)) && navigator.language) {
-            return navigator.language;
-        }
-        return 'en-US';
-    },
+    factory: () => inject(LOCALE_ID),
 });
 
 /**
@@ -83,6 +89,90 @@ const NAMED_KEYS = new Set([
     'shortDateTime',
     'mediumDateTime',
 ]);
+/**
+ * Bidi control marks ICU embeds in a right-to-left date pattern — ar-SA writes its
+ * separator as U+200F followed by a slash. No keyboard produces one, so both the
+ * pattern and the typed string drop them before they are compared.
+ */
+const BIDI_RE = /[\u200e\u200f\u061c\u2066-\u2069]/g;
+const REGEX_META_RE = /[.*+?^${}()|[\]\\]/g;
+function stripBidi(value) {
+    return value.replace(BIDI_RE, '');
+}
+function escapeRegex(value) {
+    return value.replace(REGEX_META_RE, '\\$&');
+}
+/**
+ * One literal run of an `Intl` pattern, as a regex fragment.
+ *
+ * Whitespace inside a literal is advisory, not exact: ICU separates `02:30` from `PM`
+ * with a NARROW NO-BREAK SPACE (U+202F) and no keyboard emits one, so every whitespace
+ * run matches `\s*`. A literal that is nothing BUT whitespace keeps `\s+` — relaxing it
+ * there would let `15 2026` also read as `152026`, which is how a lenient parser invents
+ * a date nobody typed.
+ */
+function literalToRegex(literal) {
+    const text = stripBidi(literal);
+    if (!text)
+        return '';
+    if (!text.trim())
+        return '\\s+';
+    return text.split(/\s+/).map(escapeRegex).join('\\s*');
+}
+/** Longest first, so `March` is never consumed as `Mar` with `ch` left over. */
+function alternation(names) {
+    return [...new Set(names)]
+        .sort((a, b) => b.length - a.length)
+        .map(name => escapeRegex(stripBidi(name)))
+        .join('|');
+}
+/**
+ * The ten digits a locale's numbering system writes, index 0 to 9 — `null` when the
+ * system is algorithmic (roman, hebrew) and there is no digit-by-digit reading to do.
+ */
+function numeralsFor(locale, numberingSystem) {
+    let formatter;
+    try {
+        formatter = new Intl.NumberFormat(locale, { numberingSystem, useGrouping: false });
+    }
+    catch {
+        return null;
+    }
+    const digits = [];
+    for (let i = 0; i < 10; i++) {
+        const digit = formatter.format(i);
+        if ([...digit].length !== 1 || digits.includes(digit))
+            return null;
+        digits.push(digit);
+    }
+    return digits;
+}
+/** A character class accepting the locale's own digits AND ASCII ones. */
+function digitClass(numerals) {
+    const extra = numerals
+        .filter(digit => digit < '0' || digit > '9')
+        .map(digit => `\\u${digit.codePointAt(0).toString(16).padStart(4, '0')}`)
+        .join('');
+    return `[0-9${extra}]`;
+}
+/** `١٥` to `15`, and ASCII through unchanged. `NaN` for anything else. */
+function digitsToNumber(text, numerals) {
+    let out = '';
+    for (const ch of text) {
+        if (ch >= '0' && ch <= '9') {
+            out += ch;
+            continue;
+        }
+        const index = numerals.indexOf(ch);
+        if (index < 0)
+            return Number.NaN;
+        out += String(index);
+    }
+    return out ? Number(out) : Number.NaN;
+}
+function isAllDigits(text, numerals) {
+    return text.length > 0 && !Number.isNaN(digitsToNumber(text, numerals));
+}
 const INTL_OPTIONS = {
     shortDate: { year: 'numeric', month: 'numeric', day: 'numeric' },
     mediumDate: { year: 'numeric', month: 'short', day: 'numeric' },
@@ -107,24 +197,30 @@ function pad(n, width = 2) {
 function isNamedFormat(value) {
     return NAMED_KEYS.has(value);
 }
-function tokenToRegex(token) {
+/**
+ * `digits` is a character class rather than `\d`, and it always accepts ASCII as well as
+ * the locale's own numerals. The token formatter WRITES ASCII, so the round trip never
+ * needed more — but a reader on an Arabic keyboard types `١٥` into the same field, and
+ * `\d` made that silently unparseable with no feedback anywhere.
+ */
+function tokenToRegex(token, digits) {
     switch (token) {
         case 'yyyy':
-            return '(\\d{4})';
+            return `(${digits}{4})`;
         case 'yy':
-            return '(\\d{2})';
+            return `(${digits}{2})`;
         case 'MM':
         case 'dd':
         case 'HH':
         case 'hh':
         case 'mm':
         case 'ss':
-            return '(\\d{2})';
+            return `(${digits}{2})`;
         case 'M':
         case 'd':
         case 'H':
         case 'h':
-            return '(\\d{1,2})';
+            return `(${digits}{1,2})`;
         case 'a':
             return '(am|pm|AM|PM)';
         default:
@@ -238,14 +334,28 @@ class WrNativeDateAdapter extends WrDateAdapter {
         }
         return this.formatWithTokens(date, formatKeyOrString);
     }
+    /**
+     * Read back what {@link format} wrote.
+     *
+     * A named format used to delegate to `new Date(raw)`, which understands only
+     * Anglo-American forms — so the field could not read its own output anywhere else.
+     * `new Date('15.3.2026')` and `new Date('14:30')` are both `Invalid Date`, while
+     * `new Date('1')` is 1 January 2001: retyping a de-DE date committed the year 2001 on
+     * the first keystroke and then refused every one after it, and `mode="time"` collapsed
+     * to midnight in EVERY locale, en-US included. The named branch now builds its parser
+     * from the SAME `Intl.DateTimeFormat` that printed the string, so the round trip holds
+     * by construction rather than by luck.
+     *
+     * Returns `null` rather than a guess whenever the string does not match — the caller's
+     * committed value is then left exactly as it was, which is the contract
+     * `wr-input-number` follows for unparseable text.
+     */
     parse(value, formatKeyOrString) {
         const raw = value?.trim();
         if (!raw)
             return null;
-        // Named formats fall back to `new Date()` parsing — best-effort, locale-fragile.
         if (isNamedFormat(formatKeyOrString)) {
-            const d = new Date(raw);
-            return this.isValid(d) ? d : null;
+            return this.parseNamed(raw, formatKeyOrString);
         }
         return this.parseWithTokens(raw, formatKeyOrString);
     }
@@ -277,16 +387,32 @@ class WrNativeDateAdapter extends WrDateAdapter {
      * can be this simple.
      */
     formatters = new Map();
+    /**
+     * Every `Intl` call this adapter makes pins `calendar: 'gregory'`, and that is a
+     * correctness fix rather than a preference.
+     *
+     * The value type is a JS `Date`, every accessor on this class (`getYear`,
+     * `getMonth`, `getDate`) is Gregorian, `createDate` builds a Gregorian date and the
+     * calendar grid draws Gregorian months. A locale whose DEFAULT calendar is something
+     * else — `fa-IR` resolves to `persian`, `th-TH` to `buddhist`, `ar-SA` to
+     * `islamic-umalqura` in several engines — printed a field the grid beside it could
+     * never agree with (`۱۴۰۴/۱۲/۲۴` over a grid headed 2026), and no parser can turn
+     * that back into the `Date` it came from. Pinning the calendar makes format and parse
+     * describe the same one.
+     */
+    intlOptions(options) {
+        return { ...options, calendar: 'gregory' };
+    }
     intl(key) {
         let found = this.formatters.get(key);
         if (!found) {
-            found = new Intl.DateTimeFormat(this.locale, INTL_OPTIONS[key]);
+            found = new Intl.DateTimeFormat(this.locale, this.intlOptions(INTL_OPTIONS[key]));
             this.formatters.set(key, found);
         }
         return found;
     }
     getDayOfWeekNames(style) {
-        const formatter = new Intl.DateTimeFormat(this.locale, { weekday: style });
+        const formatter = new Intl.DateTimeFormat(this.locale, this.intlOptions({ weekday: style }));
         const first = this.getFirstDayOfWeek();
         // Pick a reference Sunday and walk seven days.
         const base = new Date(2024, 0, 7); // Sunday 7 Jan 2024
@@ -298,15 +424,96 @@ class WrNativeDateAdapter extends WrDateAdapter {
         }
         return out;
     }
+    /**
+     * Month names in the STANDALONE (nominative) form — what a calendar heading wants.
+     * Inside a date the same name often declines; {@link monthNames} serves that form to
+     * the token formatter, and this method deliberately keeps the heading one.
+     */
     getMonthNames(style) {
-        const formatter = new Intl.DateTimeFormat(this.locale, { month: style });
-        const out = [];
-        for (let i = 0; i < 12; i++) {
-            out.push(formatter.format(new Date(2024, i, 15)));
+        return this.monthNames(style, 'standalone');
+    }
+    numeralsCache = null;
+    /** The locale's own ten digits, cached — empty when its system is algorithmic. */
+    localeNumerals() {
+        this.numeralsCache ??=
+            numeralsFor(this.locale, new Intl.NumberFormat(this.locale).resolvedOptions().numberingSystem) ?? [];
+        return this.numeralsCache;
+    }
+    dayPeriodCache = null;
+    /**
+     * `[am, pm]` as the LOCALE writes them — `PM`, `م`, `午後`.
+     *
+     * The `a` token used to return a hard-coded lowercase `pm`, byte for byte identical in
+     * every locale, which made it the one token in the pattern language that could not be
+     * localised at all. `Intl` is the source rather than the i18n catalog because
+     * `ngwr/date` deliberately depends on nothing: the panel next to it reads
+     * `datePicker.am` / `datePicker.pm`, so an app that wants its own wording overrides it
+     * there and passes a 24-hour pattern here.
+     */
+    dayPeriods() {
+        if (this.dayPeriodCache)
+            return this.dayPeriodCache;
+        let periods = ['AM', 'PM'];
+        try {
+            const formatter = new Intl.DateTimeFormat(this.locale, this.intlOptions({ hour: 'numeric', hour12: true }));
+            const read = (hour) => formatter.formatToParts(new Date(2024, 0, 15, hour)).find(p => p.type === 'dayPeriod')?.value ?? '';
+            const [am, pm] = [read(9), read(21)];
+            if (am && pm && am !== pm)
+                periods = [am, pm];
+        }
+        catch {
+            // No `Intl` day period for this locale — the English pair stays.
+        }
+        this.dayPeriodCache = periods;
+        return periods;
+    }
+    monthNameCache = new Map();
+    /**
+     * `context: 'format'` asks `Intl` for the month name as it appears BESIDE A DAY, which
+     * is where a case language stops using the nominative: ru writes `15 марта`, not
+     * `15 март`, and fi writes `maaliskuuta`, not `maaliskuu`. The name comes out of a
+     * `{ day, month }` formatter's parts, because a `{ month }` formatter alone can only
+     * ever answer with the standalone form.
+     *
+     * Some locales write the month NUMERICALLY in that position — fi abbreviates `15.3.`,
+     * ja writes `3` with `月` as a separate literal — and there the standalone name is the
+     * only name there is, so a purely numeric answer falls back to it. Without that guard
+     * `dd MMMM yyyy` would render `15 3 2026` in Japanese.
+     */
+    monthNames(style, context) {
+        const cacheKey = `${style}:${context}`;
+        const cached = this.monthNameCache.get(cacheKey);
+        if (cached)
+            return cached;
+        const standaloneFormatter = new Intl.DateTimeFormat(this.locale, this.intlOptions({ month: style }));
+        const standalone = [];
+        for (let i = 0; i < 12; i++)
+            standalone.push(standaloneFormatter.format(new Date(2024, i, 15)));
+        let out = standalone;
+        if (context === 'format') {
+            const numerals = numeralsFor(this.locale, standaloneFormatter.resolvedOptions().numberingSystem) ?? [];
+            const inDate = new Intl.DateTimeFormat(this.locale, this.intlOptions({ day: 'numeric', month: style }));
+            out = standalone.map((name, i) => {
+                const part = inDate.formatToParts(new Date(2024, i, 15)).find(p => p.type === 'month')?.value;
+                if (!part || isAllDigits(part, numerals))
+                    return name;
+                return part;
+            });
         }
+        this.monthNameCache.set(cacheKey, out);
         return out;
     }
     // Internals: token-based format / parse
+    /** Whether a token pattern also writes the day, which decides the month's form. */
+    hasDayToken(pattern) {
+        let found = false;
+        pattern.replace(PART_RE, (part, quoted) => {
+            if (quoted === undefined && (part === 'd' || part === 'dd'))
+                found = true;
+            return part;
+        });
+        return found;
+    }
     formatWithTokens(date, pattern) {
         const year = date.getFullYear();
         const month = date.getMonth();
@@ -315,8 +522,11 @@ class WrNativeDateAdapter extends WrDateAdapter {
         const hours12 = hours24 % 12 === 0 ? 12 : hours24 % 12;
         const minutes = date.getMinutes();
         const seconds = date.getSeconds();
-        const monthNames = this.getMonthNames('long');
-        const monthShort = this.getMonthNames('short');
+        // A pattern that writes the day wants the month declined for that position — `MMMM`
+        // used to hand `15 март 2026` to a Russian field, which reads as machine output.
+        const context = this.hasDayToken(pattern) ? 'format' : 'standalone';
+        const monthNames = this.monthNames('long', context);
+        const monthShort = this.monthNames('short', context);
         return pattern.replace(PART_RE, (part, quoted) => {
             // A quoted run is emitted as-is; `''` is how a single quote is written.
             if (quoted !== undefined)
@@ -352,15 +562,19 @@ class WrNativeDateAdapter extends WrDateAdapter {
                 case 'ss':
                     return pad(seconds);
                 case 'a':
-                    return hours24 < 12 ? 'am' : 'pm';
+                    return this.dayPeriods()[hours24 < 12 ? 0 : 1];
             }
             return token;
         });
     }
     parseWithTokens(value, pattern) {
         const tokens = [];
-        const monthLong = this.getMonthNames('long');
-        const monthShort = this.getMonthNames('short');
+        // Both forms are accepted on the way IN: the formatter writes the declined one beside
+        // a day (`15 марта`), and a heading or an older stored string carries the nominative.
+        const monthLong = [this.monthNames('long', 'format'), this.monthNames('long', 'standalone')];
+        const monthShort = [this.monthNames('short', 'format'), this.monthNames('short', 'standalone')];
+        const numerals = this.localeNumerals();
+        const digits = digitClass(numerals);
         const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
         const regex = escaped.replace(PART_RE, (part, quoted) => {
             if (quoted !== undefined) {
@@ -369,83 +583,266 @@ class WrNativeDateAdapter extends WrDateAdapter {
                 return quoted === '' ? "'" : quoted;
             }
             tokens.push(part);
-            return tokenToRegex(part);
+            // `a` is the one token whose text is locale-dependent, so its alternation is built
+            // here rather than in the pure `tokenToRegex`: the marker this adapter now PRINTS
+            // has to be one the same adapter can read.
+            if (part === 'a')
+                return `(${alternation([...this.dayPeriods(), 'am', 'pm'])})`;
+            return tokenToRegex(part, digits);
         });
-        const match = new RegExp(`^${regex}$`).exec(value);
+        const match = new RegExp(`^${regex}$`, 'i').exec(value);
         if (!match)
             return null;
-        let year = new Date().getFullYear();
-        let month = 0;
-        let day = 1;
-        let hours = 0;
-        let minutes = 0;
-        let seconds = 0;
-        let isPm = false;
-        let hadHour12 = false;
-        let hour12 = 0;
+        const parts = {};
         for (let i = 0; i < tokens.length; i++) {
             const token = tokens[i];
             const raw = match[i + 1];
-            const n = Number(raw);
+            const n = digitsToNumber(raw, numerals);
             switch (token) {
                 case 'yyyy':
-                    year = n;
+                    parts.year = n;
                     break;
                 case 'yy':
-                    year = 2000 + n;
+                    parts.year = 2000 + n;
                     break;
                 case 'MM':
                 case 'M':
-                    month = n - 1;
+                    parts.month = n - 1;
                     break;
                 case 'MMM':
                 case 'MMMM': {
-                    const names = token === 'MMM' ? monthShort : monthLong;
-                    const found = names.findIndex(name => name.toLowerCase() === raw.toLowerCase());
-                    if (found < 0)
+                    const sets = token === 'MMM' ? monthShort : monthLong;
+                    const wanted = raw.toLowerCase();
+                    const found = sets
+                        .map(names => names.findIndex(name => name.toLowerCase() === wanted))
+                        .find(index => index >= 0);
+                    if (found === undefined)
                         return null;
-                    month = found;
+                    parts.month = found;
                     break;
                 }
                 case 'dd':
                 case 'd':
-                    day = n;
+                    parts.day = n;
                     break;
                 case 'HH':
                 case 'H':
-                    hours = n;
+                    parts.hours = n;
                     break;
                 case 'hh':
                 case 'h':
-                    hadHour12 = true;
-                    hour12 = n;
+                    parts.hour12 = n;
                     break;
                 case 'mm':
-                    minutes = n;
+                    parts.minutes = n;
                     break;
                 case 'ss':
-                    seconds = n;
+                    parts.seconds = n;
                     break;
-                case 'a':
-                    isPm = raw.toLowerCase() === 'pm';
+                case 'a': {
+                    const marker = raw.toLowerCase();
+                    parts.isPm = marker === 'pm' || marker === this.dayPeriods()[1].toLowerCase();
                     break;
+                }
             }
         }
-        if (hadHour12) {
-            hours = (hour12 % 12) + (isPm ? 12 : 0);
+        return this.compose(parts);
+    }
+    /**
+     * Build the parser for one named format out of the very formatter that prints it.
+     *
+     * `formatToParts` is the only honest source for a locale's field ORDER and its
+     * literals — ru writes `dd.MM.y` with a two-digit month while its own
+     * `{ month: 'numeric' }` request says one digit, ja puts the year first, and ar-SA
+     * separates fields with U+200F. Names (a month, AM/PM) become an alternation of the
+     * real strings; numbers accept the locale's digits AND ASCII, because a physical
+     * keyboard produces the latter whatever the display shows.
+     *
+     * Returns `null` — meaning "this format cannot be read back" — rather than guessing,
+     * for a field type nothing here asks for (an era, a weekday) or a numbering system
+     * with no digit-by-digit reading (roman numerals). `parse` then refuses, which leaves
+     * the caller's committed value untouched.
+     */
+    buildNamedParser(key) {
+        const formatter = this.intl(key);
+        const resolved = formatter.resolvedOptions();
+        const numerals = numeralsFor(this.locale, resolved.numberingSystem);
+        if (!numerals)
+            return null;
+        const digits = digitClass(numerals);
+        // Distinct values in every field, so nothing below can read one field's reference
+        // value out of another's position.
+        const reference = new Date(2024, 0, 15, 13, 45, 56);
+        const fields = [];
+        const fragments = [];
+        for (const part of formatter.formatToParts(reference)) {
+            switch (part.type) {
+                case 'literal':
+                    fragments.push({ source: literalToRegex(part.value), literal: true });
+                    break;
+                case 'year':
+                    fields.push({ kind: 'year' });
+                    // Exactly two digits or exactly four — the shapes a year is actually written
+                    // in. `{1,4}` would let the third keystroke of `15.3.2026` read as the year 2
+                    // and commit it, which is a smaller version of the defect this replaces.
+                    fragments.push({ source: `(${digits}{2}|${digits}{4})`, literal: false });
+                    break;
+                case 'month': {
+                    const names = this.namedMonthNames(formatter);
+                    if (names.every(name => isAllDigits(name, numerals))) {
+                        fields.push({ kind: 'month' });
+                        fragments.push({ source: `(${digits}{1,2})`, literal: false });
+                    }
+                    else {
+                        fields.push({ kind: 'monthName', names });
+                        fragments.push({ source: `(${alternation(names)})`, literal: false });
+                    }
+                    break;
+                }
+                case 'day':
+                    fields.push({ kind: 'day' });
+                    fragments.push({ source: `(${digits}{1,2})`, literal: false });
+                    break;
+                case 'hour':
+                    fields.push({ kind: 'hour' });
+                    fragments.push({ source: `(${digits}{1,2})`, literal: false });
+                    break;
+                case 'minute':
+                    fields.push({ kind: 'minute' });
+                    fragments.push({ source: `(${digits}{1,2})`, literal: false });
+                    break;
+                case 'second':
+                    fields.push({ kind: 'second' });
+                    fragments.push({ source: `(${digits}{1,2})`, literal: false });
+                    break;
+                case 'dayPeriod': {
+                    const names = this.dayPeriodNames(formatter);
+                    fields.push({ kind: 'dayPeriod', names });
+                    fragments.push({ source: `(${alternation(names)})`, literal: false });
+                    break;
+                }
+                default:
+                    return null;
+            }
+        }
+        if (!fields.length)
+            return null;
+        // A trailing literal is optional. ru's medium date ends ` г.` and fi's short date
+        // ends with a bare `.`; someone retyping the field types the fields and stops, and
+        // refusing that would reintroduce the very "cannot read its own output" defect for
+        // the one part of the string that carries no information.
+        const source = fragments
+            .map((fragment, i) => i === fragments.length - 1 && fragment.literal && fragment.source ? `(?:${fragment.source})?` : fragment.source)
+            .join('');
+        return { regex: new RegExp(`^${source}$`, 'iu'), fields, numerals, hourCycle: resolved.hourCycle };
+    }
+    /** The twelve month strings THIS formatter writes, in its own style and context. */
+    namedMonthNames(formatter) {
+        const out = [];
+        for (let i = 0; i < 12; i++) {
+            out.push(formatter.formatToParts(new Date(2024, i, 15)).find(p => p.type === 'month')?.value ?? '');
+        }
+        return out;
+    }
+    /** `[am, pm]` as THIS formatter writes them — `ص` / `م` in Arabic, not AM / PM. */
+    dayPeriodNames(formatter) {
+        const read = (hour) => formatter.formatToParts(new Date(2024, 0, 15, hour, 30)).find(p => p.type === 'dayPeriod')?.value ?? '';
+        return [read(9), read(21)];
+    }
+    namedParsers = new Map();
+    parseNamed(raw, key) {
+        let parser = this.namedParsers.get(key);
+        if (parser === undefined) {
+            parser = this.buildNamedParser(key);
+            this.namedParsers.set(key, parser);
         }
-        // `new Date(2025, 12, 45)` does not fail — it rolls forward into the next year — and
-        // `isValid` is happy with the result, so a text field turned nonsense into a confident
-        // wrong answer. The clock parts are range-checked directly; the month and the day are
-        // checked by comparing what came back, which catches every rollover including a month
-        // of 12 or -1.
+        if (!parser)
+            return null;
+        const match = parser.regex.exec(stripBidi(raw));
+        if (!match)
+            return null;
+        const parts = {};
+        const twelveHour = parser.fields.some(field => field.kind === 'dayPeriod');
+        for (let i = 0; i < parser.fields.length; i++) {
+            const field = parser.fields[i];
+            const captured = match[i + 1] ?? '';
+            if (field.kind === 'monthName' || field.kind === 'dayPeriod') {
+                const wanted = stripBidi(captured).toLowerCase();
+                const index = (field.names ?? []).findIndex(name => stripBidi(name).toLowerCase() === wanted);
+                if (index < 0)
+                    return null;
+                if (field.kind === 'monthName')
+                    parts.month = index;
+                else
+                    parts.isPm = index === 1;
+                continue;
+            }
+            const n = digitsToNumber(captured, parser.numerals);
+            if (Number.isNaN(n))
+                return null;
+            switch (field.kind) {
+                case 'year':
+                    // Two digits mean this century, the same reading the `yy` token gives — the
+                    // picker's own doc promises `1/5/25` cleans up to 2025.
+                    parts.year = captured.length <= 2 ? 2000 + n : n;
+                    break;
+                case 'month':
+                    parts.month = n - 1;
+                    break;
+                case 'day':
+                    parts.day = n;
+                    break;
+                case 'hour':
+                    if (twelveHour)
+                        parts.hour12 = n;
+                    // `hourCycle: 'h24'` numbers midnight 24 rather than 0.
+                    else
+                        parts.hours = n === 24 && parser.hourCycle === 'h24' ? 0 : n;
+                    break;
+                case 'minute':
+                    parts.minutes = n;
+                    break;
+                case 'second':
+                    parts.seconds = n;
+                    break;
+            }
+        }
+        return this.compose(parts);
+    }
+    /**
+     * Assemble whatever was read into a `Date`, or refuse.
+     *
+     * `new Date(2025, 12, 45)` does not fail — it rolls forward into the next year — and
+     * `isValid` is happy with the result, so a text field used to turn nonsense into a
+     * confident wrong answer. The clock parts are range-checked directly; the month and the
+     * day are checked by comparing what came back, which catches every rollover including a
+     * month of 12 or -1.
+     */
+    compose(parts) {
+        const now = new Date();
+        const year = parts.year ?? now.getFullYear();
+        const month = parts.month ?? now.getMonth();
+        let hours = parts.hours ?? 0;
+        if (parts.hour12 !== undefined)
+            hours = (parts.hour12 % 12) + (parts.isPm ? 12 : 0);
+        const minutes = parts.minutes ?? 0;
+        const seconds = parts.seconds ?? 0;
         if (hours < 0 || hours > 23 || minutes < 0 || minutes > 59 || seconds < 0 || seconds > 59)
             return null;
+        // A time-only format carries no date, and the date it should imply is TODAY — the
+        // previous default was 1 January, so a picker in `mode="time"` moved the model back
+        // to New Year's Day as a side effect of reading a clock. The default is clamped to
+        // the month it lands in, because an unclamped 31st would roll a February string
+        // forward and the rollover check below would then refuse a well-formed string.
+        const monthLength = new Date(year, month + 1, 0).getDate();
+        const day = parts.day ?? Math.min(now.getDate(), monthLength);
         const out = new Date(year, month, day, hours, minutes, seconds);
+        // Same trap `createDate` documents: a year under 100 maps onto 1900 + year unless it
+        // is written back explicitly, so `0025-08-11` used to parse as 1925.
+        if (year >= 0 && year < 100)
+            out.setFullYear(year);
         if (!this.isValid(out))
             return null;
-        // The day is range-checked by construction: anything the calendar rolled over comes
-        // back as a different month or a different day.
         if (out.getMonth() !== month || out.getDate() !== day)
             return null;
         return out;
@@ -467,12 +864,16 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.4", ngImpor
  * Register the date adapter and locale used by the calendar / date picker /
  * time picker. Call once at bootstrap.
  *
+ * Omit `locale` and dates follow Angular's `LOCALE_ID`, which is what the app
+ * already says it is. Pass one only to pin dates to something else — see
+ * {@link WR_DATE_LOCALE}, and `WrI18n` for how the three locale inputs rank.
+ *
  * @example
  * ```ts
  * bootstrapApplication(AppComponent, {
  *   providers: [
- *     provideWrDateAdapter(),                 // native, browser locale
- *     // provideWrDateAdapter({ locale: 'ru-RU' }),
+ *     provideWrDateAdapter(),                 // native adapter, LOCALE_ID
+ *     // provideWrDateAdapter({ locale: 'ru-RU' }),        // pin the dates
  *     // provideWrDateAdapter({ adapter: MyDateFnsAdapter, locale: 'fr' }),
  *   ],
  * });