@cdevhub/ngx-tw 0.2.0

package/types/cdevhub-ngx-tw-calendar-luxon.d.ts

@@ -0,0 +1,200 @@
+import { DateTime } from 'luxon';
+import { DateAdapter, TwDateNameStyle } from '@cdevhub/ngx-tw/calendar';
+import * as i0 from '@angular/core';
+import { EnvironmentProviders } from '@angular/core';
+
+/**
+ * Display-format descriptor used by `LuxonDateAdapter.format()` and
+ * `LuxonDateAdapter.parse()`.
+ *
+ * Two shapes are supported:
+ * - `{ format: 'yyyy-LL-dd' }` — a Luxon `toFormat`/`fromFormat` token string.
+ * - `{ preset: DateTime.DATE_FULL }` — a Luxon preset (an `Intl.DateTimeFormatOptions` bag).
+ *
+ * If both are provided, `format` (the explicit token) wins.
+ */
+interface TwLuxonDateFormat {
+    /** Luxon token string consumed by `DateTime#toFormat` / `DateTime.fromFormat`. */
+    readonly format?: string;
+    /** Luxon preset (e.g. `DateTime.DATE_FULL`) consumed by `DateTime#toLocaleString`. */
+    readonly preset?: Intl.DateTimeFormatOptions;
+}
+/**
+ * Luxon-backed `DateAdapter`. Honors the calendar's `TZ_OVERRIDE` injection
+ * token so `today()` resolves against the consumer-configured timezone, and
+ * implements the §20.2 TZ-aware virtuals (`getTimezone`, `withTimezone`,
+ * `isDST`, `resolveAmbiguous`).
+ *
+ * `create()` accepts **1-based** months (matching the abstract contract and
+ * Luxon's `DateTime.fromObject({ month })` convention), while `getMonth()`
+ * returns **0-based** months (also per the abstract contract — see
+ * `NativeDateAdapter`).
+ */
+declare class LuxonDateAdapter extends DateAdapter<DateTime> {
+    /**
+     * Optional per-instance timezone override (§4.3, §7.4). Resolved lazily so
+     * the constructor stays SSR-safe — Luxon's default zone reads from the host
+     * environment which we want to defer until first use.
+     */
+    private readonly _tzOverride;
+    /**
+     * Locale is resolved lazily on first read so the constructor stays
+     * SSR-safe (no `navigator` access at class-construction time — §31.1).
+     */
+    private _locale;
+    private get locale();
+    /**
+     * Returns the configured timezone for new dates. Precedence: per-instance
+     * `TZ_OVERRIDE` → Luxon's `Settings.defaultZone` → `'local'`.
+     */
+    private get zone();
+    /** Builds a `DateTime` in the adapter's configured zone + locale. */
+    private inZone;
+    today(): DateTime;
+    /**
+     * Constructs a `DateTime`. **`month` is 1-based** — `create(2026, 1, 1)`
+     * yields January 1, 2026 at 00:00 in the adapter's configured zone.
+     */
+    create(year: number, month: number, day: number): DateTime;
+    clone(date: DateTime): DateTime;
+    setLocale(locale: string): void;
+    getLocale(): string;
+    getYear(date: DateTime): number;
+    /**
+     * Returns the **0-based** month (0 = January, 11 = December) to match the
+     * abstract `DateAdapter` contract and the `NativeDateAdapter`. Luxon's
+     * `DateTime.month` is 1-based, so we subtract one.
+     */
+    getMonth(date: DateTime): number;
+    getDate(date: DateTime): number;
+    /**
+     * Day of week mapped to the Sunday-based scheme used by the abstract
+     * contract: `0 = Sunday`, `6 = Saturday`. Luxon's `weekday` is
+     * `1 = Monday … 7 = Sunday`, so Sunday gets re-anchored to `0`.
+     */
+    getDayOfWeek(date: DateTime): number;
+    getNumDaysInMonth(date: DateTime): number;
+    getHours(date: DateTime): number;
+    getMinutes(date: DateTime): number;
+    getSeconds(date: DateTime): number;
+    withTime(date: DateTime, hours: number, minutes: number, seconds: number): DateTime;
+    /**
+     * Locale-aware first day of week (§19.2). Mirrors `NativeDateAdapter` —
+     * derives from `Intl.Locale.getWeekInfo()` when available, falling back to
+     * Monday (`1`) when the locale is unknown to ICU. ICU/CLDR returns
+     * `1=Monday … 7=Sunday`; we normalize to the project's `0=Sunday … 6=Saturday`
+     * convention so both adapters report identical values for identical locales.
+     */
+    getFirstDayOfWeek(): number;
+    getMonthNames(style: TwDateNameStyle): string[];
+    /**
+     * Day-of-week names starting at Sunday. Luxon's `Info.weekdays` starts at
+     * Monday, so the array is rotated to put Sunday first to match the abstract
+     * contract (and the native adapter).
+     */
+    getDayOfWeekNames(style: TwDateNameStyle): string[];
+    getDateNames(_style?: TwDateNameStyle): string[];
+    getYearName(date: DateTime): string;
+    /**
+     * Formats a date for display.
+     *
+     * Accepts either a Luxon token string (e.g. `'yyyy-LL-dd'`), a
+     * {@link TwLuxonDateFormat} descriptor, or a Luxon preset bag
+     * (`Intl.DateTimeFormatOptions`). When no format is supplied the
+     * adapter falls back to a locale-aware medium date.
+     */
+    format(date: DateTime, displayFormat: unknown): string;
+    addYears(date: DateTime, years: number): DateTime;
+    addMonths(date: DateTime, months: number): DateTime;
+    addDays(date: DateTime, days: number): DateTime;
+    addHours(date: DateTime, hours: number): DateTime;
+    addMinutes(date: DateTime, minutes: number): DateTime;
+    compare(first: DateTime, second: DateTime): number;
+    sameDate(first: DateTime | null | undefined, second: DateTime | null | undefined): boolean;
+    /**
+     * Start-of-day normalization in the adapter's zone. Luxon's `startOf('day')`
+     * is DST-aware — on spring-forward days it returns the wall-clock instant the
+     * zone considers the first valid moment of the day.
+     */
+    startOfDay(date: DateTime): DateTime;
+    isValid(date: DateTime): boolean;
+    /** Returns Luxon's invalid sentinel (an invalid `DateTime`). */
+    invalid(): DateTime;
+    /**
+     * Parses a value into a `DateTime`. Accepts:
+     * - `DateTime` (cloned),
+     * - JS `Date` (re-anchored to the adapter's zone + locale),
+     * - number (epoch milliseconds),
+     * - string — when `parseFormat` is a Luxon token, uses `fromFormat`;
+     *   otherwise parses strict ISO 8601 only.
+     *
+     * The free-form-string path is intentionally narrow: SQL and RFC 2822
+     * fallbacks were dropped so the Luxon adapter's acceptance surface matches
+     * `NativeDateAdapter.parse()` (which only accepts strings parseable by
+     * `new Date(value)`). Callers that need bespoke string formats should pass
+     * an explicit `parseFormat` token.
+     *
+     * Returns `null` on empty input or unrecognised value types, mirroring the
+     * native adapter's contract.
+     */
+    parse(value: unknown, parseFormat?: unknown): DateTime | null;
+    /**
+     * Coerce an incoming form value. Returns `null` for empty input, an invalid
+     * `DateTime` sentinel for malformed input (so validators can flag it), and a
+     * cloned valid `DateTime` otherwise.
+     */
+    deserialize(value: unknown): DateTime | null;
+    /**
+     * ISO 8601 date serialization (`YYYY-MM-DD`). Calendar dates have no
+     * time component — `toIso` returns just the date portion.
+     */
+    toIso(date: DateTime): string;
+    /**
+     * Parses an ISO-8601 string to a `DateTime`. Overrides the base
+     * implementation to use Luxon's optimised `fromISO` parser.
+     */
+    fromIso(iso: string): DateTime | null;
+    /** Returns the adapter's configured IANA zone name (e.g. `'America/New_York'`). */
+    getTimezone(): string;
+    /** Returns a copy of `date` reinterpreted in `tz`. */
+    withTimezone(date: DateTime, tz: string): DateTime;
+    /** Whether `date` is currently observing daylight-saving time in its zone. */
+    isDST(date: DateTime): boolean;
+    /**
+     * Resolves an ambiguous wall-clock time during DST fall-back. On fall-back
+     * days a single wall-clock hour repeats — e.g. 2024-11-03 01:30 in
+     * `America/New_York` happens once at offset -04:00 (EDT) and again at
+     * offset -05:00 (EST). Luxon's `DateTime.fromObject({...}, { zone })` always
+     * returns the **earlier** of the two candidates, so we reconstruct the
+     * "later" occurrence explicitly: rebuild the candidate at the date's
+     * wall-clock fields (anchoring it on the earlier occurrence) and add one
+     * hour to land on the same wall-clock's second occurrence in the
+     * post-fall-back offset.
+     *
+     * Non-ambiguous wall-clocks return unchanged for both `prefer` values:
+     * after `plus({ hour: 1 })` the wall-clock hour increments (no DST
+     * repetition), so the candidate is rejected and we return `date` as-is.
+     */
+    resolveAmbiguous(date: DateTime, prefer: 'earlier' | 'later'): DateTime;
+    static ɵfac: i0.ɵɵFactoryDeclaration<LuxonDateAdapter, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<LuxonDateAdapter>;
+}
+
+/**
+ * Provides {@link LuxonDateAdapter} as the calendar's `DateAdapter`.
+ *
+ * Wire at app or route level so the adapter stays constant for the
+ * component's lifetime (§11.7 of the calendar spec):
+ *
+ * ```ts
+ * import { provideLuxonDateAdapter } from '@cdevhub/ngx-tw/calendar/luxon';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideLuxonDateAdapter()],
+ * });
+ * ```
+ */
+declare function provideLuxonDateAdapter(): EnvironmentProviders;
+
+export { LuxonDateAdapter, provideLuxonDateAdapter };
+export type { TwLuxonDateFormat };

package/types/cdevhub-ngx-tw-calendar-testing.d.ts

@@ -0,0 +1,113 @@
+import { ComponentHarness, BaseHarnessFilters, HarnessPredicate } from '@angular/cdk/testing';
+
+/** Filters accepted by `CalendarCellHarness.with`. */
+interface CalendarCellHarnessFilters extends BaseHarnessFilters {
+    /** Match by the cell's visible display text (`1`, `Apr`, `2026`, etc.). */
+    text?: string | RegExp;
+    /** Match selected / unselected cells. */
+    selected?: boolean;
+    /** Match disabled / enabled cells. */
+    disabled?: boolean;
+}
+/** Harness for interacting with a single calendar cell in tests. */
+declare class CalendarCellHarness extends ComponentHarness {
+    static hostSelector: string;
+    private readonly button;
+    /** Predicate for `locatorFor` / `locatorForAll`. */
+    static with(options?: CalendarCellHarnessFilters): HarnessPredicate<CalendarCellHarness>;
+    /** The cell's rendered text, trimmed. */
+    getText(): Promise<string>;
+    /** The cell's `aria-label`. */
+    getAriaLabel(): Promise<string | null>;
+    /** Whether the cell carries `aria-selected="true"`. */
+    isSelected(): Promise<boolean>;
+    /** Whether the cell is disabled — true if the button has `disabled` or carries `aria-disabled="true"`. */
+    isDisabled(): Promise<boolean>;
+    /** Whether the cell represents today's date (`aria-current="date"`). */
+    isToday(): Promise<boolean>;
+    /** Click the cell. */
+    select(): Promise<void>;
+    /** Dispatches `mouseenter` and `mousemove` on the cell to drive range-hover preview. */
+    hover(): Promise<void>;
+    /** Programmatically focus the cell. */
+    focus(): Promise<void>;
+    /** Whether the cell's button is the active document element. */
+    isFocused(): Promise<boolean>;
+    /** Dispatches a `keydown` for `key` on the cell button (e.g. `'ArrowRight'`, `'Enter'`, `' '`, `'PageUp'`). */
+    pressKey(key: string, modifiers?: {
+        shift?: boolean;
+        meta?: boolean;
+        ctrl?: boolean;
+        alt?: boolean;
+    }): Promise<void>;
+}
+
+/** The available calendar views, mirrored so consumers don't have to import from the library's main entry point. */
+type CalendarHarnessView = 'day' | 'month' | 'year';
+/** Filters accepted by `CalendarHarness.with`. */
+type CalendarHarnessFilters = BaseHarnessFilters;
+/** Harness for interacting with a `<tw-calendar>` in tests. */
+declare class CalendarHarness extends ComponentHarness {
+    static hostSelector: string;
+    private readonly headerNavButtons;
+    private readonly grid;
+    /** Predicate for `locatorFor` / `locatorForAll`. */
+    static with(options?: CalendarHarnessFilters): HarnessPredicate<CalendarHarness>;
+    /** The header period label (e.g. `"October 2026"`, `"2026"`, `"2024 – 2047"`). */
+    getPeriodLabel(): Promise<string>;
+    /** Click the previous-page nav button. */
+    goToPreviousPage(): Promise<void>;
+    /** Click the next-page nav button. */
+    goToNextPage(): Promise<void>;
+    /** Whether the previous nav button is disabled. */
+    isPreviousDisabled(): Promise<boolean>;
+    /** Whether the next nav button is disabled. */
+    isNextDisabled(): Promise<boolean>;
+    /**
+     * Click the period label button to move up one view (`day` → `month` → `year`).
+     * Accepts an optional `target` to call it multiple times until the current view matches.
+     */
+    switchView(target?: CalendarHarnessView): Promise<void>;
+    /** Identify the currently rendered view by inspecting which view component is present. */
+    getCurrentView(): Promise<CalendarHarnessView>;
+    /** All cell harnesses in the currently rendered view. */
+    getCells(filters?: CalendarCellHarnessFilters): Promise<CalendarCellHarness[]>;
+    /** Click the cell whose text matches exactly. Throws if no match. */
+    selectCell(text: string): Promise<void>;
+    /**
+     * Selects a date range by clicking the cell whose text matches `start`, then
+     * the cell whose text matches `end`. Caller is responsible for ensuring the
+     * calendar is in `mode: 'range'` and that both cells are visible in the
+     * current view.
+     */
+    selectRange(start: string, end: string): Promise<void>;
+    /** Hovers the cell whose text matches `text` (dispatches `mouseenter` + `mousemove`). Throws if no match. */
+    hoverCell(text: string): Promise<void>;
+    /**
+     * Dispatches a `keydown` for `key` on the currently focused cell — falls back
+     * to the calendar grid host when no cell owns focus. Supports `'ArrowLeft'`,
+     * `'ArrowRight'`, `'ArrowUp'`, `'ArrowDown'`, `'Home'`, `'End'`, `'PageUp'`,
+     * `'PageDown'`, `'Enter'`, and `' '` (Space).
+     */
+    pressKey(key: string, modifiers?: {
+        shift?: boolean;
+        meta?: boolean;
+        ctrl?: boolean;
+        alt?: boolean;
+    }): Promise<void>;
+    /** All cells currently rendered with `aria-selected="true"`. */
+    getSelectedCells(): Promise<CalendarCellHarness[]>;
+    /** The cell representing today, or `null` if not visible in the current view. */
+    getTodayCell(): Promise<CalendarCellHarness | null>;
+    /** All disabled cells in the current view. */
+    getDisabledCells(): Promise<CalendarCellHarness[]>;
+    /** Whether the calendar host carries `aria-disabled="true"`. */
+    isDisabled(): Promise<boolean>;
+    /** @internal Returns the header buttons in [prev, period, next] order. */
+    private orderedHeaderButtons;
+    /** @internal Resolves the first cell whose text matches `text`. Throws if no match. */
+    private findCellByText;
+}
+
+export { CalendarCellHarness, CalendarHarness };
+export type { CalendarCellHarnessFilters, CalendarHarnessFilters, CalendarHarnessView };