@prolibu-suite/cobalt-core 0.1.1 → 0.2.0

package/dist/collection/components/co-calendar/co-calendar.js

@@ -0,0 +1,728 @@
+import { h } from "@stencil/core";
+import { addDays, addMonths, compareYMD, getFullDateLabel, getMonthLabel, getMonthMatrix, getWeekdayLabels, isDisabled, isValidYMD, parseISO, startOfMonth, todayYMD, } from "@prolibu-suite/cobalt-date-utils";
+import { getDateStrings } from "../../utils/dateI18n";
+/**
+ * Accessible month calendar (single-date selection).
+ *
+ * Presentation + interaction only: it renders the month grid, handles month
+ * navigation and full keyboard support (WAI-ARIA grid pattern, roving
+ * tabindex), and distinguishes `today` from `selected`. It holds NO popover and
+ * NO text input — `co-date-picker` composes it with `co-date-field` + a popover.
+ *
+ * Value contract: date-only strings "YYYY-MM-DD". Emits `coSelect` with the
+ * chosen date. Today and selected are deliberately different visual states.
+ *
+ * @part root - The calendar container
+ * @part header - Month navigation header
+ * @part grid - The day grid
+ */
+export class CoCalendar {
+    constructor() {
+        /** Selection mode. */
+        this.mode = 'single';
+        /** BCP-47 locale used for month/weekday labels. */
+        this.locale = 'es-CO';
+        /** First day of the week: 0=Sunday .. 6=Saturday. Default 1 (Monday). */
+        this.firstDayOfWeek = 1;
+        /** Hovered day for range preview (range mode, pointer only). */
+        this.hoverDay = null;
+        /** Header view: day grid, month picker, or year picker. */
+        this.view = 'days';
+        /** When set, focus the matching day cell after the next render. */
+        this.shouldFocusGrid = false;
+        this.handleDayHover = (day) => {
+            if (this.mode === 'range')
+                this.hoverDay = day;
+        };
+        /** Header prev/next — steps by month (days), year (months) or decade (years). */
+        this.handlePrev = () => this.step(-1);
+        this.handleNext = () => this.step(1);
+        /** Title click zooms out: days → months → years; years → back to days. */
+        this.toggleView = () => {
+            this.view = this.view === 'days' ? 'months' : this.view === 'months' ? 'years' : 'days';
+        };
+        this.handleGridKeyDown = (e) => {
+            const cur = this.focused;
+            let handled = true;
+            switch (e.key) {
+                case 'ArrowLeft':
+                    this.moveFocus(addDays(cur, -1));
+                    break;
+                case 'ArrowRight':
+                    this.moveFocus(addDays(cur, 1));
+                    break;
+                case 'ArrowUp':
+                    this.moveFocus(addDays(cur, -7));
+                    break;
+                case 'ArrowDown':
+                    this.moveFocus(addDays(cur, 7));
+                    break;
+                case 'Home':
+                    this.moveFocus(startOfWeek(cur, this.firstDayOfWeek));
+                    break;
+                case 'End':
+                    this.moveFocus(addDays(startOfWeek(cur, this.firstDayOfWeek), 6));
+                    break;
+                case 'PageUp':
+                    this.moveFocus(addMonths(cur, e.shiftKey ? -12 : -1));
+                    break;
+                case 'PageDown':
+                    this.moveFocus(addMonths(cur, e.shiftKey ? 12 : 1));
+                    break;
+                case 'Enter':
+                case ' ':
+                    this.selectDay(cur);
+                    break;
+                default:
+                    handled = false;
+            }
+            if (handled) {
+                // Stop Enter/Space from reaching an enclosing <form> and submitting,
+                // and stop arrows from scrolling the page.
+                e.preventDefault();
+                e.stopPropagation();
+            }
+        };
+    }
+    componentWillLoad() {
+        var _a;
+        const anchor = (_a = this.anchorValue) !== null && _a !== void 0 ? _a : todayYMD();
+        const a = parseISO(anchor);
+        this.viewYear = a.year;
+        this.viewMonth = a.month;
+        this.focused = this.initialFocus();
+    }
+    onValueChange() {
+        if (!this.selectedValue)
+            return;
+        const a = parseISO(this.selectedValue);
+        this.viewYear = a.year;
+        this.viewMonth = a.month;
+        this.focused = this.selectedValue;
+    }
+    /** Move keyboard focus into the grid (used by the picker when the popover opens). */
+    async focusGrid() {
+        this.shouldFocusGrid = true;
+        this.focusFocusedCell();
+    }
+    get selectedValue() {
+        return isValidYMD(this.value) ? this.value : null;
+    }
+    get rangeStartV() {
+        return isValidYMD(this.rangeStart) ? this.rangeStart : null;
+    }
+    get rangeEndV() {
+        return isValidYMD(this.rangeEnd) ? this.rangeEnd : null;
+    }
+    /** The date the grid should anchor on / focus first. */
+    get anchorValue() {
+        return this.mode === 'range' ? this.rangeStartV : this.selectedValue;
+    }
+    get disabledOpts() {
+        return {
+            min: this.min,
+            max: this.max,
+            disabledDates: normalizeStringArray(this.disabledDates),
+            disabledDaysOfWeek: normalizeNumberArray(this.disabledDaysOfWeek),
+        };
+    }
+    isDayDisabled(value) {
+        return isDisabled(value, this.disabledOpts);
+    }
+    /** Best initial focus: selected/start → today → first enabled day of view → 1st. */
+    initialFocus() {
+        const anchor = this.anchorValue;
+        if (anchor && !this.isDayDisabled(anchor))
+            return anchor;
+        const today = todayYMD();
+        const t = parseISO(today);
+        if (t.year === this.viewYear && t.month === this.viewMonth && !this.isDayDisabled(today)) {
+            return today;
+        }
+        const first = `${String(this.viewYear).padStart(4, '0')}-${String(this.viewMonth).padStart(2, '0')}-01`;
+        let cur = first;
+        for (let i = 0; i < 31; i++) {
+            const d = parseISO(cur);
+            if (!d || d.month !== this.viewMonth)
+                break;
+            if (!this.isDayDisabled(cur))
+                return cur;
+            cur = addDays(cur, 1);
+        }
+        return first;
+    }
+    selectDay(value) {
+        if (this.isDayDisabled(value))
+            return;
+        this.focused = value;
+        if (this.mode === 'range') {
+            this.selectRangeDay(value);
+        }
+        else {
+            this.coSelect.emit(value);
+        }
+    }
+    /**
+     * Range click model (controlled by rangeStart/rangeEnd):
+     *   - no start, or both set → start = day, end = null
+     *   - start set, no end → second click sets end (swaps if before start)
+     */
+    selectRangeDay(day) {
+        const start = this.rangeStartV;
+        const end = this.rangeEndV;
+        let next;
+        if (!start || (start && end)) {
+            next = { start: day, end: null };
+        }
+        else if (compareYMD(day, start) < 0) {
+            next = { start: day, end: start };
+        }
+        else {
+            next = { start, end: day };
+        }
+        this.coRangeSelect.emit(next);
+    }
+    moveFocus(next) {
+        this.focused = next;
+        const n = parseISO(next);
+        if (n.year !== this.viewYear || n.month !== this.viewMonth) {
+            this.viewYear = n.year;
+            this.viewMonth = n.month;
+        }
+        this.shouldFocusGrid = true;
+    }
+    step(dir) {
+        if (this.view === 'days') {
+            const m = addMonths(`${this.viewYear}-${String(this.viewMonth).padStart(2, '0')}-01`, dir);
+            const p = parseISO(m);
+            this.viewYear = p.year;
+            this.viewMonth = p.month;
+        }
+        else if (this.view === 'months') {
+            this.viewYear += dir;
+        }
+        else {
+            this.viewYear += dir * 10;
+        }
+    }
+    selectMonth(month) {
+        this.viewMonth = month;
+        this.view = 'days';
+    }
+    selectYear(year) {
+        this.viewYear = year;
+        this.view = 'months';
+    }
+    get decadeStart() {
+        return Math.floor(this.viewYear / 10) * 10;
+    }
+    /** {year, month} of the active selection (single value or range start). */
+    get selectedYM() {
+        const v = this.mode === 'range' ? this.rangeStartV : this.selectedValue;
+        if (!v)
+            return null;
+        const ymd = parseISO(v);
+        return { year: ymd.year, month: ymd.month };
+    }
+    isMonthDisabled(year, month) {
+        const first = `${String(year).padStart(4, '0')}-${String(month).padStart(2, '0')}-01`;
+        const last = addDays(startOfMonth(addMonths(first, 1)), -1);
+        if (this.min && compareYMD(last, this.min) < 0)
+            return true;
+        if (this.max && compareYMD(first, this.max) > 0)
+            return true;
+        return false;
+    }
+    isYearDisabled(year) {
+        const first = `${String(year).padStart(4, '0')}-01-01`;
+        const last = `${String(year).padStart(4, '0')}-12-31`;
+        if (this.min && compareYMD(last, this.min) < 0)
+            return true;
+        if (this.max && compareYMD(first, this.max) > 0)
+            return true;
+        return false;
+    }
+    componentDidRender() {
+        if (this.shouldFocusGrid) {
+            this.shouldFocusGrid = false;
+            this.focusFocusedCell();
+        }
+    }
+    focusFocusedCell() {
+        var _a;
+        const cell = (_a = this.el.shadowRoot) === null || _a === void 0 ? void 0 : _a.querySelector(`[data-date="${this.focused}"]`);
+        cell === null || cell === void 0 ? void 0 : cell.focus();
+    }
+    /** Range endpoint/in-range flags for a cell, accounting for hover preview. */
+    rangeFlags(value) {
+        const start = this.rangeStartV;
+        const end = this.rangeEndV;
+        if (!start)
+            return { isStart: false, isEnd: false, inRange: false };
+        const previewTarget = end !== null && end !== void 0 ? end : (this.hoverDay && !end ? this.hoverDay : null);
+        if (!previewTarget) {
+            return { isStart: compareYMD(value, start) === 0, isEnd: false, inRange: false };
+        }
+        const lo = compareYMD(start, previewTarget) <= 0 ? start : previewTarget;
+        const hi = compareYMD(start, previewTarget) <= 0 ? previewTarget : start;
+        return {
+            isStart: compareYMD(value, lo) === 0,
+            isEnd: compareYMD(value, hi) === 0,
+            inRange: compareYMD(value, lo) > 0 && compareYMD(value, hi) < 0,
+        };
+    }
+    dayClass(value, inMonth, disabled) {
+        const isToday = compareYMD(value, todayYMD()) === 0;
+        if (this.mode === 'range') {
+            const { isStart, isEnd, inRange } = this.rangeFlags(value);
+            const isEndpoint = isStart || isEnd;
+            return {
+                'co-calendar__day': true,
+                'co-calendar__day--outside': !inMonth,
+                'co-calendar__day--today': isToday && !isEndpoint && !inRange,
+                'co-calendar__day--range-start': isStart,
+                'co-calendar__day--range-end': isEnd,
+                'co-calendar__day--in-range': inRange,
+                'co-calendar__day--disabled': disabled,
+            };
+        }
+        const selected = this.selectedValue;
+        const isSelected = !!selected && compareYMD(value, selected) === 0;
+        return {
+            'co-calendar__day': true,
+            'co-calendar__day--outside': !inMonth,
+            'co-calendar__day--today': isToday && !isSelected,
+            'co-calendar__day--selected': isSelected,
+            'co-calendar__day--disabled': disabled,
+        };
+    }
+    headerTitle() {
+        if (this.view === 'months')
+            return String(this.viewYear);
+        if (this.view === 'years')
+            return `${this.decadeStart}–${this.decadeStart + 9}`;
+        return getMonthLabel(this.viewYear, this.viewMonth, this.locale, 'long');
+    }
+    renderDays(t) {
+        const monthLabel = getMonthLabel(this.viewYear, this.viewMonth, this.locale, 'long');
+        const shortLabels = getWeekdayLabels(this.locale, this.firstDayOfWeek, 'short');
+        const longLabels = getWeekdayLabels(this.locale, this.firstDayOfWeek, 'long');
+        const matrix = getMonthMatrix(this.viewYear, this.viewMonth, this.firstDayOfWeek);
+        return (h("div", { class: "co-calendar__grid", part: "grid", role: "grid", "aria-label": monthLabel, onKeyDown: this.handleGridKeyDown }, h("div", { class: "co-calendar__row co-calendar__row--dow", role: "row" }, shortLabels.map((lbl, i) => (h("span", { class: "co-calendar__dow", role: "columnheader", "aria-label": longLabels[i] }, lbl)))), matrix.map((week) => (h("div", { class: "co-calendar__row", role: "row" }, week.map((cell) => {
+            const disabled = this.isDayDisabled(cell.value);
+            const isFocused = compareYMD(cell.value, this.focused) === 0;
+            const isToday = compareYMD(cell.value, todayYMD()) === 0;
+            let isSelectedAria;
+            if (this.mode === 'range') {
+                const { isStart, isEnd } = this.rangeFlags(cell.value);
+                isSelectedAria = isStart || isEnd;
+            }
+            else {
+                const selected = this.selectedValue;
+                isSelectedAria = !!selected && compareYMD(cell.value, selected) === 0;
+            }
+            const dayNum = parseISO(cell.value).day;
+            return (h("button", { type: "button", role: "gridcell", "data-date": cell.value, class: this.dayClass(cell.value, cell.inMonth, disabled), tabIndex: isFocused ? 0 : -1, "aria-selected": isSelectedAria ? 'true' : 'false', "aria-current": isToday ? 'date' : undefined, "aria-disabled": disabled ? 'true' : undefined, "aria-label": getFullDateLabel(cell.value, this.locale), onClick: () => this.selectDay(cell.value), onMouseEnter: () => this.handleDayHover(cell.value), onMouseLeave: () => this.handleDayHover(null) }, dayNum));
+        }))))));
+    }
+    renderMonths() {
+        const sel = this.selectedYM;
+        const now = new Date();
+        return (h("div", { class: "co-calendar__panel", part: "grid" }, Array.from({ length: 12 }, (_, i) => {
+            const month = i + 1;
+            const name = new Intl.DateTimeFormat(this.locale, { month: 'short' }).format(new Date(this.viewYear, i, 1));
+            const disabled = this.isMonthDisabled(this.viewYear, month);
+            const isSelected = !!sel && sel.year === this.viewYear && sel.month === month;
+            const isCurrent = now.getFullYear() === this.viewYear && now.getMonth() === i;
+            return (h("button", { type: "button", class: {
+                    'co-calendar__cell': true,
+                    'co-calendar__cell--selected': isSelected,
+                    'co-calendar__cell--today': isCurrent && !isSelected,
+                    'co-calendar__cell--disabled': disabled,
+                }, disabled: disabled, "aria-current": isCurrent ? 'date' : undefined, onClick: () => this.selectMonth(month) }, name));
+        })));
+    }
+    renderYears() {
+        const sel = this.selectedYM;
+        const nowYear = new Date().getFullYear();
+        const start = this.decadeStart - 1;
+        return (h("div", { class: "co-calendar__panel", part: "grid" }, Array.from({ length: 12 }, (_, i) => {
+            const year = start + i;
+            const disabled = this.isYearDisabled(year);
+            const isSelected = !!sel && sel.year === year;
+            const isCurrent = nowYear === year;
+            return (h("button", { type: "button", class: {
+                    'co-calendar__cell': true,
+                    'co-calendar__cell--muted': year < this.decadeStart || year > this.decadeStart + 9,
+                    'co-calendar__cell--selected': isSelected,
+                    'co-calendar__cell--today': isCurrent && !isSelected,
+                    'co-calendar__cell--disabled': disabled,
+                }, disabled: disabled, "aria-current": isCurrent ? 'date' : undefined, onClick: () => this.selectYear(year) }, year));
+        })));
+    }
+    render() {
+        var _a, _b;
+        const t = getDateStrings(this.locale);
+        return (h("div", { key: '38278f3489400b035c01cfcdb5e5afbcc5000b21', class: "co-calendar", part: "root" }, h("div", { key: '0bcd5c42678b1057fb327853cacad03a8b49cdd1', class: "co-calendar__header", part: "header" }, h("button", { key: '6e7210ea64062171c0f94f463251e6373c01c348', type: "button", class: "co-calendar__nav", onClick: this.handlePrev, "aria-label": (_a = this.prevMonthLabel) !== null && _a !== void 0 ? _a : t.prevMonth }, h("co-icon", { key: '053ff755d082dae52d5cce4b0338f795d56829b7', name: "caret-left", size: 16 })), h("button", { key: '70af310b739b910e850715ac626430c1a30e3479', type: "button", class: "co-calendar__title", "aria-live": "polite", onClick: this.toggleView }, this.headerTitle(), h("co-icon", { key: 'b06bc1fb2aa4c8c31e53fa68eebade370d8026f9', name: "caret-down", size: 12, class: "co-calendar__title-caret" })), h("button", { key: '0eee7bed8085c2d3fd495f8b4152b359c3e246ad', type: "button", class: "co-calendar__nav", onClick: this.handleNext, "aria-label": (_b = this.nextMonthLabel) !== null && _b !== void 0 ? _b : t.nextMonth }, h("co-icon", { key: 'ffc4ff19f0ba3e69cb6b04a2888bc2a093f090be', name: "caret-right", size: 16 }))), this.view === 'days' && this.renderDays(t), this.view === 'months' && this.renderMonths(), this.view === 'years' && this.renderYears()));
+    }
+    static get is() { return "co-calendar"; }
+    static get encapsulation() { return "shadow"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["co-calendar.css"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["co-calendar.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "mode": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'single' | 'range'",
+                    "resolved": "\"range\" | \"single\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Selection mode."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "mode",
+                "defaultValue": "'single'"
+            },
+            "value": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string | null",
+                    "resolved": "null | string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Currently selected date (single mode), \"YYYY-MM-DD\" or null/empty."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "value"
+            },
+            "rangeStart": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string | null",
+                    "resolved": "null | string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Range start (range mode), \"YYYY-MM-DD\" or null."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "range-start"
+            },
+            "rangeEnd": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string | null",
+                    "resolved": "null | string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Range end (range mode), \"YYYY-MM-DD\" or null."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "range-end"
+            },
+            "min": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Earliest selectable date, \"YYYY-MM-DD\"."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "min"
+            },
+            "max": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Latest selectable date, \"YYYY-MM-DD\"."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "max"
+            },
+            "disabledDates": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string[] | string",
+                    "resolved": "string | string[] | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Blocked dates. Accepts a string[] or a JSON/comma string for raw-HTML use."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "disabled-dates"
+            },
+            "disabledDaysOfWeek": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "number[] | string",
+                    "resolved": "number[] | string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Blocked weekdays (0=Sun..6=Sat). Accepts number[] or a JSON/comma string."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "disabled-days-of-week"
+            },
+            "locale": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "BCP-47 locale used for month/weekday labels."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "locale",
+                "defaultValue": "'es-CO'"
+            },
+            "firstDayOfWeek": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "First day of the week: 0=Sunday .. 6=Saturday. Default 1 (Monday)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "first-day-of-week",
+                "defaultValue": "1"
+            },
+            "prevMonthLabel": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Override the \"previous month\" button aria-label (defaults from `locale`)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "prev-month-label"
+            },
+            "nextMonthLabel": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Override the \"next month\" button aria-label (defaults from `locale`)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "next-month-label"
+            }
+        };
+    }
+    static get states() {
+        return {
+            "viewYear": {},
+            "viewMonth": {},
+            "focused": {},
+            "hoverDay": {},
+            "view": {}
+        };
+    }
+    static get events() {
+        return [{
+                "method": "coSelect",
+                "name": "coSelect",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitted when the user selects a day (single mode). Detail = \"YYYY-MM-DD\"."
+                },
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                }
+            }, {
+                "method": "coRangeSelect",
+                "name": "coRangeSelect",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitted on each range edit (range mode) with the draft endpoints."
+                },
+                "complexType": {
+                    "original": "{ start: string | null; end: string | null }",
+                    "resolved": "{ start: string | null; end: string | null; }",
+                    "references": {}
+                }
+            }];
+    }
+    static get methods() {
+        return {
+            "focusGrid": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "Move keyboard focus into the grid (used by the picker when the popover opens).",
+                    "tags": []
+                }
+            }
+        };
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "value",
+                "methodName": "onValueChange"
+            }];
+    }
+}
+/** Monday-first (or configurable) start-of-week for a date. */
+function startOfWeek(value, firstDayOfWeek) {
+    const ymd = parseISO(value);
+    if (!ymd)
+        return value;
+    const dow = new Date(ymd.year, ymd.month - 1, ymd.day).getDay();
+    const back = (dow - firstDayOfWeek + 7) % 7;
+    return addDays(value, -back);
+}
+function normalizeStringArray(v) {
+    if (Array.isArray(v))
+        return v;
+    if (typeof v === 'string' && v.trim()) {
+        const t = v.trim();
+        try {
+            const parsed = JSON.parse(t);
+            if (Array.isArray(parsed))
+                return parsed.map(String);
+        }
+        catch (_a) {
+            /* not JSON — fall back to comma-split */
+        }
+        return t.split(',').map((s) => s.trim()).filter(Boolean);
+    }
+    return [];
+}
+function normalizeNumberArray(v) {
+    if (Array.isArray(v))
+        return v;
+    if (typeof v === 'string' && v.trim()) {
+        const t = v.trim();
+        try {
+            const parsed = JSON.parse(t);
+            if (Array.isArray(parsed))
+                return parsed.map(Number).filter((n) => !Number.isNaN(n));
+        }
+        catch (_a) {
+            /* not JSON */
+        }
+        return t.split(',').map((s) => Number(s.trim())).filter((n) => !Number.isNaN(n));
+    }
+    return [];
+}