@zeyos/zx 4.1.1 → 4.3.0

package/dist/types/components/calendar/calendar.d.ts

@@ -0,0 +1,517 @@
+import { Component } from '../../core/component.js';
+export type CalendarEvent = import('./calendar-model.js').CalendarEvent;
+export type CalendarView = import('./calendar-model.js').CalendarView;
+export type CalendarReader = import('./calendar-model.js').CalendarReader;
+export type CalendarOptions = {
+    /**
+     * Event records.
+     */
+    events?: Record<string, any>[];
+    /**
+     * Initial local anchor date; null uses today.
+     */
+    date?: Date | string | number | null;
+    /**
+     * Initial view.
+     */
+    view?: CalendarView;
+    /**
+     * Allowed views.
+     */
+    views?: CalendarView[];
+    /**
+     * Intl locale override.
+     */
+    locale?: string | string[];
+    /**
+     * First weekday, 0 (Sunday) through 6 (Saturday).
+     */
+    weekStart?: number;
+    /**
+     * Show ISO week numbers in month view.
+     */
+    weekNumbers?: boolean;
+    /**
+     * Show Monday–Friday in the week time grid.
+     */
+    workweek?: boolean;
+    /**
+     * Number of days in agenda view.
+     */
+    agendaDays?: number;
+    /**
+     * Time-grid snap interval in minutes.
+     */
+    slotDuration?: number;
+    /**
+     * First visible minute of the day.
+     */
+    slotMinTime?: number;
+    /**
+     * Exclusive last visible minute of the day.
+     */
+    slotMaxTime?: number;
+    /**
+     * Minute initially scrolled into view.
+     */
+    scrollTime?: number;
+    /**
+     * Maximum visible month lanes before a More button.
+     */
+    eventLimit?: number;
+    /**
+     * Enable pointer time-range selection.
+     */
+    selectable?: boolean;
+    /**
+     * Enable event moving and resizing.
+     */
+    editable?: boolean;
+    /**
+     * Global move override; null inherits editable.
+     */
+    eventStartEditable?: boolean | null;
+    /**
+     * Global resize override; null inherits editable.
+     */
+    eventDurationEditable?: boolean | null;
+    /**
+     * Apply event proposals locally before persistence confirms.
+     */
+    optimistic?: boolean;
+    /**
+     * Show the current-time line in day/week views.
+     */
+    nowIndicator?: boolean;
+    /**
+     * Current-time override for deterministic rendering.
+     */
+    now?: Date | (() => Date) | null;
+    /**
+     * Disable toolbar, date, selection, and editing controls.
+     */
+    disabled?: boolean;
+    /**
+     * Event ID reader.
+     */
+    eventId?: CalendarReader;
+    /**
+     * Event title reader.
+     */
+    eventTitle?: CalendarReader;
+    /**
+     * Event start reader.
+     */
+    eventStart?: CalendarReader;
+    /**
+     * Event end reader.
+     */
+    eventEnd?: CalendarReader;
+    /**
+     * Event all-day reader.
+     */
+    eventAllDay?: CalendarReader;
+    /**
+     * Event colour reader.
+     */
+    eventColor?: CalendarReader;
+    /**
+     * Event location reader.
+     */
+    eventLocation?: CalendarReader;
+    /**
+     * Per-event move reader.
+     */
+    eventEditable?: CalendarReader;
+    /**
+     * Per-event resize reader.
+     */
+    eventDurationEditable?: CalendarReader;
+    /**
+     * Unit for numeric event dates.
+     */
+    dateUnit?: 'milliseconds' | 'seconds';
+    /**
+     * Localized component messages.
+     */
+    msg?: Record<string, string>;
+    /**
+     * Optional safe event-content renderer.
+     */
+    renderEvent?: (event: CalendarEvent) => Node | string | null;
+    /**
+     * Programmatic event-data listener.
+     */
+    oneventschange?: (event: CustomEvent<{
+        events: CalendarEvent[];
+    }>) => void;
+    /**
+     * View listener.
+     */
+    onviewchange?: (event: CustomEvent<{
+        view: CalendarView;
+        oldView: CalendarView;
+    }>) => void;
+    /**
+     * Visible-range listener.
+     */
+    ondateschange?: (event: CustomEvent<{
+        view: CalendarView;
+        start: Date;
+        end: Date;
+    }>) => void;
+    /**
+     * Event activation listener.
+     */
+    oneventclick?: (event: CustomEvent<{
+        event: CalendarEvent;
+        jsEvent: Event;
+    }>) => void;
+    /**
+     * Event double-activation listener.
+     */
+    oneventdblclick?: (event: CustomEvent<{
+        event: CalendarEvent;
+        jsEvent: Event;
+    }>) => void;
+    /**
+     * Date/time activation listener.
+     */
+    ondateclick?: (event: CustomEvent<{
+        date: Date;
+        allDay: boolean;
+        view: CalendarView;
+        jsEvent: Event;
+    }>) => void;
+    /**
+     * Range-selection listener.
+     */
+    onselect?: (event: CustomEvent<{
+        start: Date;
+        end: Date;
+        allDay: boolean;
+        view: CalendarView;
+        jsEvent: Event;
+    }>) => void;
+    /**
+     * Move/resize proposal listener.
+     */
+    oneventchange?: (event: CustomEvent<CalendarEventChangeDetail>) => void;
+    /**
+     * New-event command listener.
+     */
+    onnew?: (event: CustomEvent<{
+        date: Date;
+        view: CalendarView;
+        jsEvent: Event;
+    }>) => void;
+    /**
+     * Month-overflow listener.
+     */
+    onmoreclick?: (event: CustomEvent<{
+        date: Date;
+        count: number;
+        jsEvent: Event;
+    }>) => void;
+};
+export type CalendarEventChangeDetail = {
+    /**
+     * Proposed event.
+     */
+    event: CalendarEvent;
+    /**
+     * Previous event.
+     */
+    oldEvent: CalendarEvent;
+    /**
+     * Edit action.
+     */
+    action: 'move' | 'resize';
+    /**
+     * Edit delta.
+     */
+    delta: {
+        milliseconds: number;
+        days: number;
+        minutes: number;
+        endMilliseconds: number;
+    };
+    /**
+     * Originating pointer or keyboard event.
+     */
+    jsEvent: Event;
+    /**
+     * Idempotent optimistic revert callback.
+     */
+    revert: () => boolean;
+};
+export type CalendarSetOptions = {
+    silent?: boolean;
+};
+/**
+ * Accessible, dependency-free agenda/day/week/month/year scheduling surface.
+ * @fires Calendar#viewchange
+ * @fires Calendar#dateschange
+ * @fires Calendar#eventclick
+ * @fires Calendar#eventdblclick
+ * @fires Calendar#dateclick
+ * @fires Calendar#select
+ * @fires Calendar#eventchange
+ * @fires Calendar#eventschange
+ * @fires Calendar#new
+ * @fires Calendar#moreclick
+ * @extends {Component<CalendarOptions>}
+ */
+export declare class Calendar extends Component<CalendarOptions> {
+    _createdRoot: boolean;
+    _original: {
+        attributes: string[][];
+        children: ChildNode[];
+    };
+    _views: import("./calendar-model.js").CalendarView[];
+    _view: any;
+    _date: Date;
+    _events: any;
+    _loading: boolean;
+    _destroyed: boolean;
+    _pointer: {
+        type: string;
+        pointerId: number;
+        startX: number;
+        startY: number;
+        oldEvent: import("./calendar-model.js").CalendarEvent;
+        event: import("./calendar-model.js").CalendarEvent;
+        action: string;
+        control: any;
+        timeOffsetMinutes: number;
+        dayOffset: number;
+        moved: boolean;
+        start?: undefined;
+        end?: undefined;
+    } | {
+        oldEvent?: undefined;
+        event?: undefined;
+        action?: undefined;
+        timeOffsetMinutes?: undefined;
+        dayOffset?: undefined;
+        type: string;
+        pointerId: number;
+        startX: number;
+        startY: number;
+        start: Date;
+        end: Date;
+        control: any;
+        moved: boolean;
+    };
+    _keyboardEdit: {
+        oldEvent: import("./calendar-model.js").CalendarEvent;
+        event: import("./calendar-model.js").CalendarEvent;
+        action: string;
+        control: HTMLElement;
+    };
+    _mutationVersions: Map<any, any>;
+    _mutationSerial: number;
+    _suppressClickId: string;
+    _suppressDateClick: boolean;
+    _focusedSlot: any;
+    _selection: any;
+    _nowTimer: number;
+    _range: {
+        start: Date;
+        end: Date;
+    };
+    static cssName: string;
+    /** @type {CalendarOptions} */
+    static defaults: CalendarOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Returns defensive copies of every normalized event. @returns {CalendarEvent[]} */
+    getEvents(): CalendarEvent[];
+    /** Replaces all source records atomically. @param {Record<string, any>[]} events @param {CalendarSetOptions} [options={}] @returns {this} */
+    setEvents(events: Record<string, any>[], options?: CalendarSetOptions): this;
+    /** Adds one source event. @param {Record<string, any>} event @param {CalendarSetOptions} [options={}] @returns {this} */
+    addEvent(event: Record<string, any>, options?: CalendarSetOptions): this;
+    /**
+     * Updates one normalized event. Date changes accept valid Date objects, ISO strings, or numeric
+     * values in the configured date unit.
+     * @param {string|number} id Event id.
+     * @param {Partial<CalendarEvent>} changes Normalized event changes.
+     * @param {CalendarSetOptions} [options={}] Update behavior.
+     * @returns {this}
+     */
+    updateEvent(id: string | number, changes: Partial<CalendarEvent>, options?: CalendarSetOptions): this;
+    /** Removes one event when present. @param {string|number} id Event id. @param {CalendarSetOptions} [options={}] @returns {this} */
+    removeEvent(id: string | number, options?: CalendarSetOptions): this;
+    /** Returns a copy of the current anchor date. @returns {Date} */
+    getDate(): Date;
+    /** Sets the anchor date and visible period. @param {Date|string|number} date @param {CalendarSetOptions} [options={}] @returns {this} */
+    setDate(date: Date | string | number, options?: CalendarSetOptions): this;
+    /** Returns the current view. @returns {CalendarView} */
+    getView(): CalendarView;
+    /** Changes view while retaining the anchor date. @param {CalendarView} view @param {CalendarSetOptions} [options={}] @returns {this} */
+    setView(view: CalendarView, options?: CalendarSetOptions): this;
+    /** Moves to the previous visible period. @returns {this} */
+    prev(): this;
+    /** Moves to the next visible period. @returns {this} */
+    next(): this;
+    /** Moves to today. @returns {this} */
+    today(): this;
+    /** Toggles loading state without discarding the rendered calendar. @param {boolean} [loading=true] @returns {this} */
+    setLoading(loading?: boolean): this;
+    /** Focuses an event in the current view when rendered. @param {string|number} id Event id. @returns {this} */
+    focusEvent(id: string | number): this;
+    /** Restores an enhanced target or removes the owned root and releases timers. @returns {void} */
+    destroy(): void;
+    /** @param {string} action @param {string} label @param {string|null} [iconName=null] @returns {HTMLButtonElement} */
+    _toolbarButton(action: string, label: string, iconName?: string | null): HTMLButtonElement;
+    /** @returns {import('./calendar-model.js').CalendarNormalizeOptions} */
+    _normalizeOptions(): import('./calendar-model.js').CalendarNormalizeOptions;
+    /** @param {{emitDates?: boolean, preserveFocus?: boolean, scroll?: boolean}} [options={}] @returns {void} */
+    _renderView(options?: {
+        emitDates?: boolean;
+        preserveFocus?: boolean;
+        scroll?: boolean;
+    }): void;
+    /** @param {{start: Date, end: Date}} range @returns {HTMLElement} */
+    _renderAgenda(range: {
+        start: Date;
+        end: Date;
+    }): HTMLElement;
+    /** @param {{start: Date, end: Date}} range @returns {HTMLElement} */
+    _renderTimeGrid(range: {
+        start: Date;
+        end: Date;
+    }): HTMLElement;
+    /** @param {Date[]} days @returns {HTMLElement} */
+    _renderAllDayRail(days: Date[]): HTMLElement;
+    /** @param {{start: Date, end: Date}} range @returns {HTMLElement} */
+    _renderMonth(range: {
+        start: Date;
+        end: Date;
+    }): HTMLElement;
+    /** @param {{start: Date, end: Date}} range @returns {HTMLElement} */
+    _renderYear(range: {
+        start: Date;
+        end: Date;
+    }): HTMLElement;
+    /**
+     * @param {CalendarEvent} event
+     * @param {{variant: 'agenda'|'timed'|'span'|'month', day: Date, resizable?: boolean}} context
+     * @returns {HTMLElement}
+     */
+    _eventElement(event: CalendarEvent, context: {
+        variant: 'agenda' | 'timed' | 'span' | 'month';
+        day: Date;
+        resizable?: boolean;
+    }): HTMLElement;
+    /** @param {Date[]} days @param {number} min @param {number} max @returns {HTMLElement} */
+    _nowLine(days: Date[], min: number, max: number): HTMLElement;
+    /** @param {Event} event @returns {void} */
+    _onClick(event: Event): void;
+    /** @param {Event} event @returns {void} */
+    _onDoubleClick(event: Event): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onKeydown(event: KeyboardEvent): void;
+    /** @param {KeyboardEvent} event @param {HTMLElement} control @returns {void} */
+    _onEventKeydown(event: KeyboardEvent, control: HTMLElement): void;
+    /** @param {KeyboardEvent} event @param {HTMLElement} slot @returns {void} */
+    _onSlotKeydown(event: KeyboardEvent, slot: HTMLElement): void;
+    /** @param {KeyboardEvent} event @param {HTMLElement} day @returns {void} */
+    _onDayKeydown(event: KeyboardEvent, day: HTMLElement): void;
+    /** @param {PointerEvent} event @returns {void} */
+    _onPointerDown(event: PointerEvent): void;
+    /** @param {PointerEvent} event @returns {void} */
+    _onPointerMove(event: PointerEvent): void;
+    /** @param {PointerEvent} event @returns {void} */
+    _onPointerUp(event: PointerEvent): void;
+    /** @param {PointerEvent} event @returns {void} */
+    _cancelPointer(event: PointerEvent): void;
+    /** @param {CalendarEvent} event @param {'move'|'resize'} action @param {number} x @param {number} y @returns {CalendarEvent|null} */
+    _proposalAtPoint(event: CalendarEvent, action: 'move' | 'resize', x: number, y: number): CalendarEvent | null;
+    /** @param {number} x @param {number} y @param {Date|null} [fixedDay=null] @returns {Date|null} */
+    _timeAtPoint(x: number, y: number, fixedDay?: Date | null): Date | null;
+    /** @param {number} x @param {number} y @returns {Date|null} */
+    _dayAtPoint(x: number, y: number): Date | null;
+    /** @param {CalendarEvent} event @param {number} x @param {number} y @returns {{minutes: number, days: number}} */
+    _dragOffsetForEvent(event: CalendarEvent, x: number, y: number): {
+        minutes: number;
+        days: number;
+    };
+    /** @param {Date} day @returns {number} */
+    _timeGridDayIndex(day: Date): number;
+    /** @param {CalendarEvent} event @returns {string|null} */
+    _timedPreviewHeight(event: CalendarEvent): string | null;
+    /** @param {number} pointerId @returns {void} */
+    _capturePointer(pointerId: number): void;
+    /** @param {number} pointerId @returns {void} */
+    _releasePointerCapture(pointerId: number): void;
+    /** @param {Date} start @param {Date} end @returns {void} */
+    _previewSelection(start: Date, end: Date): void;
+    /** @returns {void} */
+    _clearSelectionPreview(): void;
+    /** @returns {void} */
+    _cancelKeyboardEdit(): void;
+    /** @param {CalendarEvent} oldEvent @param {CalendarEvent} proposed @param {'move'|'resize'} action @param {Event} jsEvent @returns {void} */
+    _commitMutation(oldEvent: CalendarEvent, proposed: CalendarEvent, action: 'move' | 'resize', jsEvent: Event): void;
+    /** @param {CalendarEvent} event @returns {void} */
+    _replaceNormalizedEvent(event: CalendarEvent): void;
+    /** @param {CalendarEvent} event @returns {boolean} */
+    _canMove(event: CalendarEvent): boolean;
+    /** @param {CalendarEvent} event @returns {boolean} */
+    _canResize(event: CalendarEvent): boolean;
+    /** @param {string|number} id @returns {CalendarEvent|null} */
+    _eventById(id: string | number): CalendarEvent | null;
+    /** @param {string|number} id @returns {number} */
+    _eventIndex(id: string | number): number;
+    /** @param {number} direction @returns {this} */
+    _page(direction: number): this;
+    /** @param {{start: Date, end: Date}} range @returns {string} */
+    _rangeTitle(range: {
+        start: Date;
+        end: Date;
+    }): string;
+    /** @param {CalendarEvent} event @param {Date} day @returns {string} */
+    _eventTime(event: CalendarEvent, day: Date): string;
+    /** @param {CalendarEvent} event @returns {string} */
+    _eventLabel(event: CalendarEvent): string;
+    /** @param {Date} date @returns {string} */
+    _dateTimeLabel(date: Date): string;
+    /** @param {Date} date @param {Intl.DateTimeFormatOptions} options @returns {string} */
+    _format(date: Date, options: Intl.DateTimeFormatOptions): string;
+    /** @returns {Date} */
+    _now(): Date;
+    /** @param {HTMLElement} target @returns {Date|null} */
+    _dateFromTarget(target: HTMLElement): Date | null;
+    /** @param {HTMLElement} target @returns {void} */
+    _rememberFocusedDate(target: HTMLElement): void;
+    /** @returns {{eventId?: string, eventAction?: string, date?: string, slot?: string}|null} */
+    _focusIdentity(): {
+        eventId?: string;
+        eventAction?: string;
+        date?: string;
+        slot?: string;
+    } | null;
+    /** @param {{eventId?: string, eventAction?: string, date?: string, slot?: string}} identity @returns {void} */
+    _restoreFocus(identity: {
+        eventId?: string;
+        eventAction?: string;
+        date?: string;
+        slot?: string;
+    }): void;
+    /** @returns {void} */
+    _scrollTimeGrid(): void;
+    /** @returns {void} */
+    _refreshNowIndicator(): void;
+    /** @param {string} message @returns {void} */
+    _announce(message: string): void;
+}
+/** @event Calendar#viewchange @type {CustomEvent<{view: CalendarView, oldView: CalendarView}>} */
+/** @event Calendar#dateschange @type {CustomEvent<{view: CalendarView, start: Date, end: Date}>} */
+/** @event Calendar#eventclick @type {CustomEvent<{event: CalendarEvent, jsEvent: Event}>} */
+/** @event Calendar#eventdblclick @type {CustomEvent<{event: CalendarEvent, jsEvent: Event}>} */
+/** @event Calendar#dateclick @type {CustomEvent<{date: Date, allDay: boolean, view: CalendarView, jsEvent: Event}>} */
+/** @event Calendar#select @type {CustomEvent<{start: Date, end: Date, allDay: boolean, view: CalendarView, jsEvent: Event}>} */
+/** @event Calendar#eventchange @type {CustomEvent<CalendarEventChangeDetail>} */
+/** @event Calendar#eventschange @type {CustomEvent<{events: CalendarEvent[]}>} */
+/** @event Calendar#new @type {CustomEvent<{date: Date, view: CalendarView, jsEvent: Event}>} */
+/** @event Calendar#moreclick @type {CustomEvent<{date: Date, count: number, jsEvent: Event}>} */