forty-cdk 0.34.0 → 0.35.0

package/types/forty-cdk-date-adapter.d.ts

@@ -1,6 +1,5 @@
-import * as i0 from '@angular/core';
-import { InjectionToken, Provider } from '@angular/core';
-
+import * as i0 from "@angular/core";
+import { InjectionToken, Provider } from "@angular/core";
 /**
  * Pluggable, date-library-agnostic seam for `ForCalendar`. Every internal
  * algorithm (paging, the day matrix, comparison, formatting) goes through a
@@ -33,157 +32,157 @@ import { InjectionToken, Provider } from '@angular/core';
  * @typeParam D The immutable date representation the adapter operates on.
  */
 interface DateAdapter<D> {
-    /**
-     * Today's date in the runtime time zone.
-     *
-     * **SSR / hydration caveat.** The result depends on the runtime time zone, so
-     * a server render and a client hydration can disagree by up to a day near
-     * midnight — the server may compute a different calendar day than the
-     * browser. `ForCalendar` reads this on each render to mark the `data-today` /
-     * `aria-current="date"` cell, so a mismatch surfaces there as a hydration
-     * error and a flicker on the highlighted "today" cell.
-     *
-     * **SSR-safe pattern.** Have the consumer supply a fixed "today" (or pin a
-     * time zone) for the server render, or defer the today-highlight to
-     * `afterNextRender` so `today()` is only computed client-side. See the
-     * calendar README's "SSR / hydration" section.
-     */
-    today(): D;
-    /**
-     * Creates a date from its parts.
-     *
-     * @param year Full year (e.g. `2026`).
-     * @param month Month of year, **1-12**.
-     * @param day Day of month, **1-31** (constrained to the month's length).
-     */
-    createDate(year: number, month: number, day: number): D;
-    /** The full year of `date` (e.g. `2026`). */
-    getYear(date: D): number;
-    /** The month of `date`, **1-12**. */
-    getMonth(date: D): number;
-    /** The day of month of `date`, **1-31**. */
-    getDate(date: D): number;
-    /** The day of week of `date`, **0-6** where `0` is Sunday and `6` is Saturday. */
-    getDayOfWeek(date: D): number;
-    /** The number of days in `date`'s month. */
-    getDaysInMonth(date: D): number;
-    /**
-     * The first day of the week as a **0-6** index (`0` = Sunday). Used as the
-     * default when `ForCalendar`'s `firstDayOfWeek` input is `null`. Adapters
-     * return a locale-independent default (`0`); consumers localise it through
-     * the `firstDayOfWeek` input or `provideForCalendarDefaults`.
-     */
-    getFirstDayOfWeek(): number;
-    /** Returns a new date `n` days after `date` (negative goes backwards). */
-    addDays(date: D, n: number): D;
-    /**
-     * Returns a new date `n` months after `date` (negative goes backwards). The
-     * day of month is constrained to the target month's length (e.g. Jan 31 + 1
-     * month is Feb 28/29, never Mar 3).
-     */
-    addMonths(date: D, n: number): D;
-    /**
-     * Returns a new date `n` years after `date` (negative goes backwards). The
-     * day of month is constrained (e.g. Feb 29 + 1 year is Feb 28 in a common
-     * year).
-     */
-    addYears(date: D, n: number): D;
-    /**
-     * Compares two dates by their natural ordering — **the full instant**,
-     * including any time component the adapter's `D` carries. Returns a negative
-     * number when `a` is before `b`, `0` when they are equal, and a positive
-     * number when `a` is after `b`.
-     *
-     * This is the canonical comparator and the only one an adapter must
-     * implement. Time-capable adapters (`Date`, `@internationalized/date`'s
-     * `CalendarDateTime`) order by day *and* time; day-only adapters
-     * (`CalendarDate`) order by day alone because that is all their `D` carries.
-     *
-     * **Bounds granularity.** `minDate` / `maxDate` clamping in the date
-     * primitives compares the full instant through `compare`, so a date-time
-     * `min`/`max` clamps identically on every time-capable adapter (e.g. native
-     * `Date` and `CalendarDateTime` produce the same result for the same input).
-     * For the *calendar grid*, where availability is day-granular so the boundary
-     * day of a date-time `min`/`max` stays selectable, the primitives compare
-     * calendar days instead, through {@link compareDate} when present and
-     * otherwise from the y/m/d getters.
-     */
-    compare(a: D, b: D): number;
-    /**
-     * Optionally compares two dates by calendar day only, ignoring any time
-     * component. Returns a negative number when `a`'s day is before `b`'s, `0`
-     * when they fall on the same calendar day, and a positive number when `a`'s
-     * day is after `b`'s.
-     *
-     * Adapters may **omit** this method: the primitives then derive the
-     * day-only comparison from the {@link getYear} / {@link getMonth} /
-     * {@link getDate} getters, which is correct for any adapter. Implement it only
-     * to override that default (e.g. a bespoke day-granular ordering). This
-     * overrides day-only *ordering* only — it does not change the Gregorian month
-     * structure the grid assumes (see the *Calendar system* note on the interface).
-     * Day-only adapters whose {@link compare} already ignores time need not
-     * implement it.
-     */
-    compareDate?(a: D, b: D): number;
-    /** Whether `a` and `b` fall on the same calendar day. */
-    isSameDay(a: D, b: D): boolean;
-    /** Whether `date` is a valid date of this adapter's type. */
-    isValid(date: D): boolean;
-    /**
-     * The locale this adapter formats in, or `null` for the runtime default. A
-     * segmented date / time field with no `[locale]` of its own takes its segment
-     * order, separators, hour cycle and AM/PM names from it, so they match what
-     * {@link format} produces. Reading a signal here makes every field and
-     * formatted value follow a runtime language switch.
-     */
-    locale?(): string | null;
-    /**
-     * Formats `date` for display. When `locale` is omitted the adapter's own
-     * {@link locale} is used, else the runtime's default locale; pass one to
-     * force a specific locale for month / weekday / day-period names.
-     *
-     * **SSR / hydration caveat.** With no `locale` the result resolves against the
-     * runtime's default locale, so a server render and a client hydration can
-     * produce different strings when the server and browser locales differ —
-     * surfacing as a hydration mismatch on every formatted value (heading, weekday
-     * headers, cell labels). The runtime time zone applies too for adapters that
-     * format through a wall-clock instant.
-     *
-     * **SSR-safe pattern.** Pin a `locale` (or format client-side) for the server
-     * render so both environments resolve the same locale. See the calendar
-     * README's "SSR / hydration" section.
-     *
-     * @param options Standard `Intl.DateTimeFormat` options (e.g.
-     *   `{ month: 'long', year: 'numeric' }` for a calendar heading,
-     *   `{ weekday: 'short' }` for a column header).
-     * @param locale Optional BCP 47 locale tag governing the formatted names;
-     *   falls back to {@link locale}, then the runtime's default locale, when
-     *   omitted.
-     */
-    format(date: D, options: Intl.DateTimeFormatOptions, locale?: string): string;
-    /**
-     * Whether this adapter's `D` can carry a wall-clock time component (hour /
-     * minute / second). Day-only adapters omit the optional time accessors below
-     * and return `false` (or omit this method); time-capable adapters implement
-     * them and return `true`. `ForTimeField` — and the time granularity of the
-     * date primitives — require a time-capable adapter.
-     */
-    supportsTime?(): boolean;
-    /** The hour of `date`, **0-23** (24-hour clock). Time-capable adapters only. */
-    getHours?(date: D): number;
-    /** The minute of `date`, **0-59**. Time-capable adapters only. */
-    getMinutes?(date: D): number;
-    /** The second of `date`, **0-59**. Time-capable adapters only. */
-    getSeconds?(date: D): number;
-    /**
-     * Returns a new date with its time set to the given parts, preserving the
-     * calendar day. Time-capable adapters only.
-     *
-     * @param hours Hour of day, **0-23**.
-     * @param minutes Minute of hour, **0-59**.
-     * @param seconds Second of minute, **0-59**.
-     */
-    setTime?(date: D, hours: number, minutes: number, seconds: number): D;
+  /**
+   * Today's date in the runtime time zone.
+   *
+   * **SSR / hydration caveat.** The result depends on the runtime time zone, so
+   * a server render and a client hydration can disagree by up to a day near
+   * midnight — the server may compute a different calendar day than the
+   * browser. `ForCalendar` reads this on each render to mark the `data-today` /
+   * `aria-current="date"` cell, so a mismatch surfaces there as a hydration
+   * error and a flicker on the highlighted "today" cell.
+   *
+   * **SSR-safe pattern.** Have the consumer supply a fixed "today" (or pin a
+   * time zone) for the server render, or defer the today-highlight to
+   * `afterNextRender` so `today()` is only computed client-side. See the
+   * calendar README's "SSR / hydration" section.
+   */
+  today(): D;
+  /**
+   * Creates a date from its parts.
+   *
+   * @param year Full year (e.g. `2026`).
+   * @param month Month of year, **1-12**.
+   * @param day Day of month, **1-31** (constrained to the month's length).
+   */
+  createDate(year: number, month: number, day: number): D;
+  /** The full year of `date` (e.g. `2026`). */
+  getYear(date: D): number;
+  /** The month of `date`, **1-12**. */
+  getMonth(date: D): number;
+  /** The day of month of `date`, **1-31**. */
+  getDate(date: D): number;
+  /** The day of week of `date`, **0-6** where `0` is Sunday and `6` is Saturday. */
+  getDayOfWeek(date: D): number;
+  /** The number of days in `date`'s month. */
+  getDaysInMonth(date: D): number;
+  /**
+   * The first day of the week as a **0-6** index (`0` = Sunday). Used as the
+   * default when `ForCalendar`'s `firstDayOfWeek` input is `null`. Adapters
+   * return a locale-independent default (`0`); consumers localise it through
+   * the `firstDayOfWeek` input or `provideForCalendarDefaults`.
+   */
+  getFirstDayOfWeek(): number;
+  /** Returns a new date `n` days after `date` (negative goes backwards). */
+  addDays(date: D, n: number): D;
+  /**
+   * Returns a new date `n` months after `date` (negative goes backwards). The
+   * day of month is constrained to the target month's length (e.g. Jan 31 + 1
+   * month is Feb 28/29, never Mar 3).
+   */
+  addMonths(date: D, n: number): D;
+  /**
+   * Returns a new date `n` years after `date` (negative goes backwards). The
+   * day of month is constrained (e.g. Feb 29 + 1 year is Feb 28 in a common
+   * year).
+   */
+  addYears(date: D, n: number): D;
+  /**
+   * Compares two dates by their natural ordering — **the full instant**,
+   * including any time component the adapter's `D` carries. Returns a negative
+   * number when `a` is before `b`, `0` when they are equal, and a positive
+   * number when `a` is after `b`.
+   *
+   * This is the canonical comparator and the only one an adapter must
+   * implement. Time-capable adapters (`Date`, `@internationalized/date`'s
+   * `CalendarDateTime`) order by day *and* time; day-only adapters
+   * (`CalendarDate`) order by day alone because that is all their `D` carries.
+   *
+   * **Bounds granularity.** `minDate` / `maxDate` clamping in the date
+   * primitives compares the full instant through `compare`, so a date-time
+   * `min`/`max` clamps identically on every time-capable adapter (e.g. native
+   * `Date` and `CalendarDateTime` produce the same result for the same input).
+   * For the *calendar grid*, where availability is day-granular so the boundary
+   * day of a date-time `min`/`max` stays selectable, the primitives compare
+   * calendar days instead, through {@link compareDate} when present and
+   * otherwise from the y/m/d getters.
+   */
+  compare(a: D, b: D): number;
+  /**
+   * Optionally compares two dates by calendar day only, ignoring any time
+   * component. Returns a negative number when `a`'s day is before `b`'s, `0`
+   * when they fall on the same calendar day, and a positive number when `a`'s
+   * day is after `b`'s.
+   *
+   * Adapters may **omit** this method: the primitives then derive the
+   * day-only comparison from the {@link getYear} / {@link getMonth} /
+   * {@link getDate} getters, which is correct for any adapter. Implement it only
+   * to override that default (e.g. a bespoke day-granular ordering). This
+   * overrides day-only *ordering* only — it does not change the Gregorian month
+   * structure the grid assumes (see the *Calendar system* note on the interface).
+   * Day-only adapters whose {@link compare} already ignores time need not
+   * implement it.
+   */
+  compareDate?(a: D, b: D): number;
+  /** Whether `a` and `b` fall on the same calendar day. */
+  isSameDay(a: D, b: D): boolean;
+  /** Whether `date` is a valid date of this adapter's type. */
+  isValid(date: D): boolean;
+  /**
+   * The locale this adapter formats in, or `null` for the runtime default. A
+   * segmented date / time field with no `[locale]` of its own takes its segment
+   * order, separators, hour cycle and AM/PM names from it, so they match what
+   * {@link format} produces. Reading a signal here makes every field and
+   * formatted value follow a runtime language switch.
+   */
+  locale?(): string | null;
+  /**
+   * Formats `date` for display. When `locale` is omitted the adapter's own
+   * {@link locale} is used, else the runtime's default locale; pass one to
+   * force a specific locale for month / weekday / day-period names.
+   *
+   * **SSR / hydration caveat.** With no `locale` the result resolves against the
+   * runtime's default locale, so a server render and a client hydration can
+   * produce different strings when the server and browser locales differ —
+   * surfacing as a hydration mismatch on every formatted value (heading, weekday
+   * headers, cell labels). The runtime time zone applies too for adapters that
+   * format through a wall-clock instant.
+   *
+   * **SSR-safe pattern.** Pin a `locale` (or format client-side) for the server
+   * render so both environments resolve the same locale. See the calendar
+   * README's "SSR / hydration" section.
+   *
+   * @param options Standard `Intl.DateTimeFormat` options (e.g.
+   *   `{ month: 'long', year: 'numeric' }` for a calendar heading,
+   *   `{ weekday: 'short' }` for a column header).
+   * @param locale Optional BCP 47 locale tag governing the formatted names;
+   *   falls back to {@link locale}, then the runtime's default locale, when
+   *   omitted.
+   */
+  format(date: D, options: Intl.DateTimeFormatOptions, locale?: string): string;
+  /**
+   * Whether this adapter's `D` can carry a wall-clock time component (hour /
+   * minute / second). Day-only adapters omit the optional time accessors below
+   * and return `false` (or omit this method); time-capable adapters implement
+   * them and return `true`. `ForTimeField` — and the time granularity of the
+   * date primitives — require a time-capable adapter.
+   */
+  supportsTime?(): boolean;
+  /** The hour of `date`, **0-23** (24-hour clock). Time-capable adapters only. */
+  getHours?(date: D): number;
+  /** The minute of `date`, **0-59**. Time-capable adapters only. */
+  getMinutes?(date: D): number;
+  /** The second of `date`, **0-59**. Time-capable adapters only. */
+  getSeconds?(date: D): number;
+  /**
+   * Returns a new date with its time set to the given parts, preserving the
+   * calendar day. Time-capable adapters only.
+   *
+   * @param hours Hour of day, **0-23**.
+   * @param minutes Minute of hour, **0-59**.
+   * @param seconds Second of minute, **0-59**.
+   */
+  setTime?(date: D, hours: number, minutes: number, seconds: number): D;
 }
 /**
  * A {@link DateAdapter} narrowed to one that implements the optional time
@@ -199,8 +198,7 @@ type TimeCapableDateAdapter<D> = DateAdapter<D> & Required<Pick<DateAdapter<D>,
  * There is no application-wide default — a calendar with no adapter in scope
  * throws a descriptive error.
  */
-declare const FOR_DATE_ADAPTER: InjectionToken<DateAdapter<unknown>>;
-
+export declare const FOR_DATE_ADAPTER: InjectionToken<DateAdapter<unknown>>;
 /**
  * Creates a memoized `Intl.DateTimeFormat` factory shared by the date adapters.
  *
@@ -220,8 +218,7 @@ declare const FOR_DATE_ADAPTER: InjectionToken<DateAdapter<unknown>>;
  * @returns A function that returns the cached `Intl.DateTimeFormat` for the
  *   given `locale` (or the runtime default when omitted) and `options`.
  */
-declare function createFormatterCache(): (locale: string | undefined, options: Intl.DateTimeFormatOptions) => Intl.DateTimeFormat;
-
+export declare function createFormatterCache(): (locale: string | undefined, options: Intl.DateTimeFormatOptions) => Intl.DateTimeFormat;
 /**
  * Zero-dependency {@link DateAdapter} over the built-in `Date`. `today` and
  * `createDate` produce days at local midnight, and the calendar grid stays
@@ -239,44 +236,44 @@ declare function createFormatterCache(): (locale: string | undefined, options: I
  * `Date` and the `@internationalized/date` adapters operate on the Gregorian
  * calendar; non-Gregorian calendar systems are not supported.
  */
-declare class NativeDateAdapter implements DateAdapter<Date> {
-    #private;
-    /**
-     * Today at local midnight in the runtime time zone. Subject to the
-     * SSR/hydration caveat on {@link DateAdapter.today}.
-     */
-    today(): Date;
-    createDate(year: number, month: number, day: number): Date;
-    getYear(date: Date): number;
-    getMonth(date: Date): number;
-    getDate(date: Date): number;
-    getDayOfWeek(date: Date): number;
-    getDaysInMonth(date: Date): number;
-    getFirstDayOfWeek(): number;
-    addDays(date: Date, n: number): Date;
-    addMonths(date: Date, n: number): Date;
-    addYears(date: Date, n: number): Date;
-    compare(a: Date, b: Date): number;
-    isSameDay(a: Date, b: Date): boolean;
-    isValid(date: Date): boolean;
-    /**
-     * The locale {@link format} falls back to, or `null` for the runtime default.
-     * Override it in a subclass to format, and lay out every date / time field,
-     * in the app's language.
-     */
-    locale(): string | null;
-    /**
-     * Formats through `locale`, else {@link locale}, else the runtime's default
-     * locale. Subject to the SSR/hydration caveat on {@link DateAdapter.format}.
-     */
-    format(date: Date, options: Intl.DateTimeFormatOptions, locale?: string): string;
-    supportsTime(): boolean;
-    getHours(date: Date): number;
-    getMinutes(date: Date): number;
-    getSeconds(date: Date): number;
-    setTime(date: Date, hours: number, minutes: number, seconds: number): Date;
-    static ɵfac: i0.ɵɵFactoryDeclaration<NativeDateAdapter, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<NativeDateAdapter>;
+export declare class NativeDateAdapter implements DateAdapter<Date> {
+  #private;
+  /**
+   * Today at local midnight in the runtime time zone. Subject to the
+   * SSR/hydration caveat on {@link DateAdapter.today}.
+   */
+  today(): Date;
+  createDate(year: number, month: number, day: number): Date;
+  getYear(date: Date): number;
+  getMonth(date: Date): number;
+  getDate(date: Date): number;
+  getDayOfWeek(date: Date): number;
+  getDaysInMonth(date: Date): number;
+  getFirstDayOfWeek(): number;
+  addDays(date: Date, n: number): Date;
+  addMonths(date: Date, n: number): Date;
+  addYears(date: Date, n: number): Date;
+  compare(a: Date, b: Date): number;
+  isSameDay(a: Date, b: Date): boolean;
+  isValid(date: Date): boolean;
+  /**
+   * The locale {@link format} falls back to, or `null` for the runtime default.
+   * Override it in a subclass to format, and lay out every date / time field,
+   * in the app's language.
+   */
+  locale(): string | null;
+  /**
+   * Formats through `locale`, else {@link locale}, else the runtime's default
+   * locale. Subject to the SSR/hydration caveat on {@link DateAdapter.format}.
+   */
+  format(date: Date, options: Intl.DateTimeFormatOptions, locale?: string): string;
+  supportsTime(): boolean;
+  getHours(date: Date): number;
+  getMinutes(date: Date): number;
+  getSeconds(date: Date): number;
+  setTime(date: Date, hours: number, minutes: number, seconds: number): Date;
+  static ɵfac: i0.ɵɵFactoryDeclaration<NativeDateAdapter, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
 }
 /**
  * Provides the zero-dependency {@link NativeDateAdapter} as the active
@@ -290,7 +287,5 @@ declare class NativeDateAdapter implements DateAdapter<Date> {
  * });
  * ```
  */
-declare function provideNativeDateAdapter(): Provider[];
-
-export { FOR_DATE_ADAPTER, NativeDateAdapter, createFormatterCache, provideNativeDateAdapter };
-export type { DateAdapter, TimeCapableDateAdapter };
+export declare function provideNativeDateAdapter(): Provider[];
+export type { DateAdapter, TimeCapableDateAdapter };