@malva-ui/core 0.1.13 → 0.1.14

package/types/malva-ui-core-calendar.d.ts

@@ -0,0 +1,339 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, WritableSignal, Type, Provider } from '@angular/core';
+import * as _malva_ui_i18n from '@malva-ui/i18n';
+import { BooleanInput } from '@angular/cdk/coercion';
+
+type MlvCalendarView = 'month' | 'year' | 'multi-year';
+/**
+ * Selected range value used by range-enabled calendar instances.
+ */
+interface MlvCalendarRangeValue<D = Date> {
+    start: D | null;
+    end: D | null;
+}
+interface CalendarDayCell<D> {
+    date: D;
+    currentMonth: boolean;
+}
+declare class MlvCalendar<D = Date> {
+    /** @private The active date adapter — a provided `MLV_DATE_ADAPTER`, or the native fallback. */
+    private readonly _dateAdapter;
+    /** @protected The component's i18n strings signal. */
+    protected readonly _i18n: _angular_core.Signal<_malva_ui_i18n.MlvCalendarI18n>;
+    /** @private Resolver for ICU parameterized i18n strings. */
+    private readonly _resolver;
+    /** @private Host element used to locate the roving-focus cell. */
+    private readonly _elementRef;
+    /** @private Normalizes horizontal calendar navigation for RTL layouts. */
+    private readonly _rtlService;
+    /** @private Injector for scheduling post-render focus of the active cell. */
+    private readonly _injector;
+    /** Currently selected single date value. */
+    readonly value: _angular_core.ModelSignal<D | null>;
+    /** Currently selected range value when range mode is enabled. */
+    readonly rangeValue: _angular_core.ModelSignal<MlvCalendarRangeValue<D> | null>;
+    /** Minimum selectable date. */
+    readonly min: _angular_core.InputSignal<D | null>;
+    /** Maximum selectable date. */
+    readonly max: _angular_core.InputSignal<D | null>;
+    /** Optional predicate for disabling arbitrary dates. */
+    readonly disabledDates: _angular_core.InputSignal<((date: D) => boolean) | null>;
+    /** Initial view shown by the calendar. */
+    readonly startView: _angular_core.InputSignal<MlvCalendarView>;
+    /** First day of the week where `0` is Sunday. */
+    readonly firstDayOfWeek: _angular_core.InputSignal<number>;
+    /** Enables range selection mode. */
+    readonly range: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Removes standalone surface chrome when rendered inside another container such as a popup. */
+    readonly embedded: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * Date currently focused by navigation and view state.
+     *
+     * Two-way bindable via `[(activeDate)]` so a parent can coordinate
+     * navigation across multiple calendars (e.g. the side-by-side panels in
+     * `mlv-date-range-picker`). Defaults to the selected value when present,
+     * otherwise to today.
+     */
+    readonly activeDate: _angular_core.ModelSignal<D>;
+    /** Current calendar view mode. */
+    readonly currentView: _angular_core.WritableSignal<MlvCalendarView>;
+    /** @private Transient range endpoint used only for pointer/keyboard preview. */
+    private readonly _rangePreviewDate;
+    /**
+     * @protected Chronologically ordered interval currently painted in the grid.
+     * A committed end date wins; otherwise the hovered/focused preview date is
+     * paired with the selected anchor without mutating `rangeValue`.
+     */
+    protected readonly _displayRange: _angular_core.Signal<{
+        start: D;
+        end: D;
+    } | null>;
+    /** Whether the painted interval is a transient hover/focus preview. */
+    readonly isRangePreviewing: _angular_core.Signal<boolean>;
+    /** Whether both selected endpoints are set and the primary range band is committed. */
+    readonly hasCompletedRange: _angular_core.Signal<boolean>;
+    /** Localized weekday labels rotated by `firstDayOfWeek`. */
+    readonly weekdays: _angular_core.Signal<string[]>;
+    /** Month grid cells, including adjacent-month overflow days. */
+    readonly monthDays: _angular_core.Signal<CalendarDayCell<D>[]>;
+    /**
+     * Month grid cells grouped into week rows (arrays of 7) so the template can
+     * render each week as a `role="row"` inside the `role="grid"` structure.
+     */
+    readonly monthWeeks: _angular_core.Signal<CalendarDayCell<D>[][]>;
+    /** Localized month labels used by the year view. */
+    readonly months: _angular_core.Signal<string[]>;
+    /** Consecutive 24-year block used by the multi-year view. */
+    readonly years: _angular_core.Signal<number[]>;
+    /** Localized header label for the active view. */
+    readonly headerLabel: _angular_core.Signal<string>;
+    /**
+     * @protected Localized aria-label for the view-switching header button.
+     * Announces the view the button will switch to (month → year → multi-year → month).
+     */
+    protected readonly _switchViewLabel: _angular_core.Signal<string>;
+    constructor();
+    /** Navigates to the previous visible period when available. */
+    navigatePrev(): void;
+    /** Navigates to the next visible period when available. */
+    navigateNext(): void;
+    /** Cycles between month, year, and multi-year views. */
+    switchView(): void;
+    /** Selects a date or extends the current range selection. */
+    selectDate(date: D): void;
+    /** Selects a month in the current year and returns to month view. */
+    selectMonth(month: number): void;
+    /** Selects a year and returns to year view. */
+    selectYear(year: number): void;
+    /** Returns `true` when the date is outside the allowed selection rules. */
+    isDateDisabled(date: D): boolean;
+    /** Returns `true` when the date matches today according to the adapter. */
+    isToday(date: D): boolean;
+    /** Returns `true` when the date matches the selected single value. */
+    isSelected(date: D): boolean;
+    /** Returns `true` when the date is the current range start. */
+    isRangeStart(date: D): boolean;
+    /** Returns `true` when the date is the current range end. */
+    isRangeEnd(date: D): boolean;
+    /** Returns `true` when the date is the leading endpoint currently painted. */
+    isDisplayRangeStart(date: D): boolean;
+    /** Returns `true` when the date is the trailing endpoint currently painted. */
+    isDisplayRangeEnd(date: D): boolean;
+    /** Returns `true` when the date lies inside the selected or previewed interval. */
+    isInDisplayRange(date: D): boolean;
+    /** Previews a potential range end without changing the selected range value. */
+    previewRange(date: D): void;
+    /** Clears the transient range preview when pointer/focus leaves the day grid. */
+    clearRangePreview(): void;
+    /** Returns `true` when the date lies inside the selected range. */
+    isInRange(date: D): boolean;
+    /** Returns `true` when the date is the active navigated date. */
+    isActive(date: D): boolean;
+    /** Returns `true` when the given year matches the active year. */
+    isCurrentYear(year: number): boolean;
+    /** Returns `true` when the given month index matches the active month. */
+    isCurrentMonthIndex(month: number): boolean;
+    /** Returns `true` when an entire month has no selectable dates. */
+    isMonthDisabled(month: number): boolean;
+    /** Returns `true` when an entire year has no selectable dates. */
+    isYearDisabled(year: number): boolean;
+    /** Returns `true` when navigating to the previous period is allowed. */
+    canNavigatePrev(): boolean;
+    /** Returns `true` when navigating to the next period is allowed. */
+    canNavigateNext(): boolean;
+    /** Produces a localized accessible label for a day cell. */
+    getDayLabel(date: D): string;
+    /** Produces a localized day-of-month label for a day cell. */
+    getDayNumber(date: D): string;
+    /** Produces the localized ARIA label for the year-view month grid. */
+    getYearViewLabel(): string;
+    /** Produces a localized year label for multi-year buttons and ranges. */
+    getYearOptionLabel(year: number): string;
+    /** Stable tracking key for month grid cells. */
+    trackDay(_index: number, day: CalendarDayCell<D>): string;
+    /** Dispatches keyboard events to the active view's handler. */
+    onKeydown(event: KeyboardEvent): void;
+    /** @private Keyboard navigation for the month (day grid) view. */
+    private _handleMonthViewKeydown;
+    /** @private Keyboard navigation for the year (month grid, 4 columns) view. */
+    private _handleYearViewKeydown;
+    /** @private Keyboard navigation for the multi-year (year grid, 4 columns) view. */
+    private _handleMultiYearViewKeydown;
+    /**
+     * Moves keyboard focus to the active cell of the current view (the day, month,
+     * or year button carrying `tabindex="0"`). Public entry point for consumers
+     * (e.g. `mlv-day-picker`, `mlv-date-range-picker`) that open the calendar in
+     * a popup and want focus to land inside the grid.
+     */
+    focus(): void;
+    /**
+     * @private Schedule a focus move to the active cell after the next render, so
+     * the roving `tabindex="0"` element (re-rendered after `activeDate` changes)
+     * exists in the DOM before we focus it. Only invoked from keyboard handlers,
+     * so programmatic `activeDate` changes never steal focus.
+     */
+    private _scheduleFocusActiveCell;
+    /** @private Focus the current view's active cell (roving `tabindex="0"`). */
+    private _focusActiveCell;
+    /** @private Resolves the initial active date from the selected value/range, falling back to today. */
+    private _getInitialActiveDate;
+    /** @private Returns the first year of the 24-year block containing the given date. */
+    private _yearBlockStart;
+    /** @private Whether at least one selectable (non-disabled, in-bounds) date exists in the inclusive range. */
+    private _hasSelectableDateInRange;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvCalendar<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvCalendar<any>, "mlv-calendar", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "rangeValue": { "alias": "rangeValue"; "required": false; "isSignal": true; }; "min": { "alias": "min"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "disabledDates": { "alias": "disabledDates"; "required": false; "isSignal": true; }; "startView": { "alias": "startView"; "required": false; "isSignal": true; }; "firstDayOfWeek": { "alias": "firstDayOfWeek"; "required": false; "isSignal": true; }; "range": { "alias": "range"; "required": false; "isSignal": true; }; "embedded": { "alias": "embedded"; "required": false; "isSignal": true; }; "activeDate": { "alias": "activeDate"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "rangeValue": "rangeValueChange"; "activeDate": "activeDateChange"; }, never, never, true, never>;
+}
+
+/**
+ * Formatting options accepted by Malva UI date adapters.
+ *
+ * Adapters may interpret these through `Intl.DateTimeFormat`, a library-specific
+ * formatter, or another localization layer, but the default implementation uses
+ * the standard `Intl` options shape.
+ */
+type MlvDateFormatOptions = Intl.DateTimeFormatOptions;
+/**
+ * Application-level locale token consumed by Malva UI date adapters.
+ *
+ * Defaults to `navigator.language` when available and falls back to `en-US`.
+ */
+declare const MLV_DATE_LOCALE: InjectionToken<string>;
+/**
+ * Injection token for the active Malva UI date adapter.
+ *
+ * Applications can provide a custom adapter implementation when they need
+ * a different date object model or library-backed date math.
+ */
+declare const MLV_DATE_ADAPTER: InjectionToken<MlvDateAdapter<unknown>>;
+/**
+ * Registers a custom Malva UI date adapter and optionally overrides the locale.
+ *
+ * @param adapter Adapter class to instantiate for date operations.
+ * @param locale Optional locale string passed to `MLV_DATE_LOCALE`.
+ */
+declare function provideMlvDateAdapter<D>(adapter: Type<MlvDateAdapter<D>>, locale?: string): Provider[];
+/**
+ * Abstract date-manipulation and localization contract used by calendar-aware
+ * Malva UI components.
+ *
+ * Implementations may wrap native `Date`, Luxon, Moment, date-fns-backed value
+ * objects, or any other date representation, as long as they provide calendar
+ * arithmetic, comparison, parsing, and localized labels through this surface.
+ */
+declare abstract class MlvDateAdapter<D> {
+    /** Reactive locale used by formatting and label methods. */
+    readonly locale: WritableSignal<string>;
+    /** Sets the active locale for this adapter. */
+    setLocale(locale: string): void;
+    /** Compares two dates by year, month, and day. */
+    compareDate(first: D, second: D): number;
+    /** Returns `true` when both values represent the same calendar day. */
+    sameDate(first: D | null, second: D | null): boolean;
+    /** Produces a localized accessible label for a full calendar date. */
+    getDateLabel(date: D): string;
+    /** Produces a localized month-and-year header label. */
+    getMonthYearLabel(date: D): string;
+    /** Produces a localized year label. */
+    getYearLabel(date: D): string;
+    /** Produces a localized day-of-month label. */
+    getDayOfMonthLabel(date: D): string;
+    /** Returns the adapter's representation of today's date. */
+    abstract today(): D;
+    /** Creates a safe clone of the provided date instance. */
+    abstract clone(date: D): D;
+    /** Creates a date instance from year, month, and day values. */
+    abstract createDate(year: number, month: number, day: number): D;
+    /** Returns the calendar year of the provided date. */
+    abstract getYear(date: D): number;
+    /** Returns the zero-based month index of the provided date. */
+    abstract getMonth(date: D): number;
+    /** Returns the day-of-month of the provided date. */
+    abstract getDate(date: D): number;
+    /** Returns the day-of-week index of the provided date. */
+    abstract getDayOfWeek(date: D): number;
+    /** Returns the number of days in the provided date's month. */
+    abstract getNumDaysInMonth(date: D): number;
+    /** Returns localized month names in the requested width. */
+    abstract getMonthNames(style: 'long' | 'short' | 'narrow'): string[];
+    /** Returns localized weekday names in the requested width. */
+    abstract getDayOfWeekNames(style: 'long' | 'short' | 'narrow'): string[];
+    /** Adds calendar days and returns a new date instance. */
+    abstract addCalendarDays(date: D, days: number): D;
+    /** Adds calendar months and returns a new date instance. */
+    abstract addCalendarMonths(date: D, months: number): D;
+    /** Adds calendar years and returns a new date instance. */
+    abstract addCalendarYears(date: D, years: number): D;
+    /** Formats the provided date using adapter-specific localization rules. */
+    abstract format(date: D, displayFormat: MlvDateFormatOptions): string;
+    /** Returns a stable ISO-like string for tracking and identity purposes. */
+    abstract toIso8601(date: D): string;
+    /** Deserializes an unknown value into the adapter's date type. */
+    abstract deserialize(value: unknown): D | null;
+    /** Returns `true` when the value is already a date instance understood by this adapter. */
+    abstract isDateInstance(value: unknown): value is D;
+    /** Returns `true` when the provided date instance is valid. */
+    abstract isValid(date: D): boolean;
+}
+
+/**
+ * Default Malva UI date adapter backed by native `Date` and `Intl.DateTimeFormat`.
+ *
+ * This implementation keeps the adapter contract lightweight while still
+ * providing localized labels, month names, weekday names, parsing, and
+ * calendar arithmetic for apps that do not need a third-party date library.
+ */
+declare class MlvNativeDateAdapter extends MlvDateAdapter<Date> {
+    /** @private Locale injected at construction and applied via `setLocale`. */
+    private readonly _initialLocale;
+    /** @private Cache of `Intl.DateTimeFormat` instances keyed by locale + format options. */
+    private readonly _intlCache;
+    constructor();
+    /** Returns today's date normalized to local midnight. */
+    today(): Date;
+    /** Clones and normalizes a native `Date`. */
+    clone(date: Date): Date;
+    /** Creates a valid local date or throws when the input is invalid. */
+    createDate(year: number, month: number, day: number): Date;
+    /** Returns the year part of the given date. */
+    getYear(date: Date): number;
+    /** Returns the zero-based month index of the given date. */
+    getMonth(date: Date): number;
+    /** Returns the day-of-month of the given date. */
+    getDate(date: Date): number;
+    /** Returns the weekday index of the given date. */
+    getDayOfWeek(date: Date): number;
+    /** Returns the number of days in the given date's month. */
+    getNumDaysInMonth(date: Date): number;
+    /** Returns localized month names using `Intl.DateTimeFormat`. */
+    getMonthNames(style: 'long' | 'short' | 'narrow'): string[];
+    /** Returns localized weekday names using `Intl.DateTimeFormat`. */
+    getDayOfWeekNames(style: 'long' | 'short' | 'narrow'): string[];
+    /** Adds calendar days while preserving local calendar semantics. */
+    addCalendarDays(date: Date, days: number): Date;
+    /** Adds calendar months and clamps the day when needed. */
+    addCalendarMonths(date: Date, months: number): Date;
+    /** Adds calendar years and clamps the day when needed. */
+    addCalendarYears(date: Date, years: number): Date;
+    /** Formats a date with the current locale and `Intl` options. */
+    format(date: Date, displayFormat: MlvDateFormatOptions): string;
+    /** Returns a stable `YYYY-MM-DD` string for the given local date. */
+    toIso8601(date: Date): string;
+    /** Deserializes native `Date`, ISO-like strings, and timestamps. */
+    deserialize(value: unknown): Date | null;
+    /** Returns `true` when the value is a native `Date` instance. */
+    isDateInstance(value: unknown): value is Date;
+    /** Returns `true` when the `Date` has a valid timestamp. */
+    isValid(date: Date): boolean;
+    /** @private Strips the time component, returning a new `Date` at local midnight. */
+    private _normalizeDate;
+    /** @private Builds a date for the given fields, clamping the day to the target month's length. */
+    private _createClampedDate;
+    /** @private Returns a cached (or freshly created) `Intl.DateTimeFormat` for the current locale and format. */
+    private _getFormatter;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvNativeDateAdapter, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<MlvNativeDateAdapter>;
+}
+
+export { MLV_DATE_ADAPTER, MLV_DATE_LOCALE, MlvCalendar, MlvDateAdapter, MlvNativeDateAdapter, provideMlvDateAdapter };
+export type { MlvCalendarRangeValue, MlvCalendarView, MlvDateFormatOptions };

package/types/malva-ui-core-card.d.ts

@@ -0,0 +1,88 @@
+import * as i0 from '@angular/core';
+import { BooleanInput } from '@angular/cdk/coercion';
+import { MlvStructural } from '@malva-ui/cdk/utils';
+
+declare class MlvCardHeaderDef extends MlvStructural {
+    static ɵfac: i0.ɵɵFactoryDeclaration<MlvCardHeaderDef, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MlvCardHeaderDef, "[mlvCardHeaderDef]", never, {}, {}, never, never, true, never>;
+}
+declare class MlvCardHeader {
+    static ɵfac: i0.ɵɵFactoryDeclaration<MlvCardHeader, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MlvCardHeader, "[mlvCardHeader]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Structural directive responsible for rendering the card subheader template.
+ */
+declare class MlvCardSubheaderDef extends MlvStructural {
+    static ɵfac: i0.ɵɵFactoryDeclaration<MlvCardSubheaderDef, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MlvCardSubheaderDef, "[mlvCardSubheaderDef]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Subheader directive. Used to apply correct classes to the element.
+ */
+declare class MlvCardSubheader {
+    static ɵfac: i0.ɵɵFactoryDeclaration<MlvCardSubheader, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MlvCardSubheader, "[mlvCardSubheader]", never, {}, {}, never, never, true, never>;
+}
+
+declare class MlvCardActionsDef extends MlvStructural {
+    static ɵfac: i0.ɵɵFactoryDeclaration<MlvCardActionsDef, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MlvCardActionsDef, "[mlvCardActionsDef]", never, {}, {}, never, never, true, never>;
+}
+declare class MlvCardActions {
+    static ɵfac: i0.ɵɵFactoryDeclaration<MlvCardActions, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MlvCardActions, "[mlvCardActions]", never, {}, {}, never, never, true, never>;
+}
+
+declare class MlvCardFooterDef extends MlvStructural {
+    static ɵfac: i0.ɵɵFactoryDeclaration<MlvCardFooterDef, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MlvCardFooterDef, "[mlvCardFooterDef]", never, {}, {}, never, never, true, never>;
+}
+declare class MlvCardFooter {
+    readonly withBorder: i0.InputSignalWithTransform<boolean, BooleanInput>;
+    readonly fullWidth: i0.InputSignalWithTransform<boolean, BooleanInput>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MlvCardFooter, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MlvCardFooter, "[mlvCardFooter]", never, { "withBorder": { "alias": "withBorder"; "required": false; "isSignal": true; }; "fullWidth": { "alias": "fullWidth"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+type MlvCardSize = 's' | 'm' | 'l';
+/**
+ * Layout applied to the card's projected body.
+ *
+ * - `'none'` — the body is a plain block; children lay themselves out.
+ * - `'stack'` — the body becomes a vertical flex stack separated by
+ *   `--mlv-card-body-gap`.
+ */
+type MlvCardBodyLayout = 'none' | 'stack';
+declare class MlvCard {
+    /** Size preset controlling the card spacing, radius, and typography. */
+    readonly size: i0.InputSignal<MlvCardSize>;
+    /** Whether the card uses the elevated visual treatment. */
+    readonly elevated: i0.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Optional background image URL rendered behind the card content. */
+    readonly backgroundImage: i0.InputSignal<string | null>;
+    /**
+     * Layout of the projected body. Defaults to `'none'`, which leaves the body
+     * a plain block exactly as before.
+     *
+     * `'stack'` turns the body into a vertical stack separated by
+     * `--mlv-card-body-gap` — a size-aware default that a consumer can override
+     * per card. It replaces the wrapper `<div>` with its own `gap` that every
+     * multi-child card used to hand-roll.
+     */
+    readonly bodyLayout: i0.InputSignal<MlvCardBodyLayout>;
+    /** @protected Header slot template projected via `[mlvCardHeader]`. */
+    protected readonly headerRef: i0.Signal<MlvCardHeaderDef | undefined>;
+    /** @protected Subheader slot template projected via `[mlvCardSubheader]`. */
+    protected readonly subheaderRef: i0.Signal<MlvCardSubheaderDef | undefined>;
+    /** @protected Actions slot template projected via `[mlvCardActions]`. */
+    protected readonly actionsRef: i0.Signal<MlvCardActionsDef | undefined>;
+    /** @protected Footer slot template projected via `[mlvCardFooter]`. */
+    protected readonly footerRef: i0.Signal<MlvCardFooterDef | undefined>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MlvCard, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MlvCard, "mlv-card", never, { "size": { "alias": "size"; "required": false; "isSignal": true; }; "elevated": { "alias": "elevated"; "required": false; "isSignal": true; }; "backgroundImage": { "alias": "backgroundImage"; "required": false; "isSignal": true; }; "bodyLayout": { "alias": "bodyLayout"; "required": false; "isSignal": true; }; }, {}, ["headerRef", "subheaderRef", "actionsRef", "footerRef"], ["*"], true, never>;
+}
+
+export { MlvCard, MlvCardActions, MlvCardActionsDef, MlvCardFooter, MlvCardFooterDef, MlvCardHeader, MlvCardHeaderDef, MlvCardSubheader, MlvCardSubheaderDef };
+export type { MlvCardBodyLayout, MlvCardSize };