@lekoala/date-picker 0.3.0 → 0.5.0

package/src/date-range.js

@@ -45,21 +45,41 @@ export function rangePosition(date, range) {
   return "";
 }
 
+/**
+ * @typedef {object} RangeTransition
+ * @property {"pending" | "complete" | "refused"} status
+ * @property {"start" | "end"} endpoint primary bound the transition speaks through
+ * @property {("start" | "end")[]} changedEndpoints bounds whose value actually moves
+ * @property {DateRange} range the whole resulting pair, not only the moved bound
+ * @property {"" | "start" | "end"} activeEndpoint bound the next pick would target
+ * @property {boolean} [close] the workflow cannot continue in the popup
+ */
+
 /**
  * Pure two-bound state machine for the shared-calendar range picker. Covers
  * start/end state and the active-endpoint transition rules; it knows nothing
  * about DOM, popups or async availability.
  *
- * Interaction contract (U9):
+ * Interaction contract:
  * - opening through a field targets that bound;
  * - a pick outside a complete range extends the corresponding bound;
- * - otherwise activating through `end` refuses a date before `start`;
+ * - while a range is being created (`start` set, no `end`), a second pick
+ *   before the anchor is sorted into `date -> start` instead of refused:
+ *   calendar interaction never produces an inverted range;
+ * - an explicit change to one bound of an already complete pair keeps that
+ *   bound's identity, so moving `end` before `start` is refused rather than
+ *   silently rewriting the other field;
  * - activating through `start` commits `start`, moves the active endpoint to
  *   `end` and leaves the popup open for the second selection.
  *
- * The business range may be temporarily incomplete or inverted; it is the
- * coordinator's job to forward only a displayable range to
- * `calendar.highlightedRange`.
+ * Each rule exists once, as a `project*()` projection; `activate()` and
+ * `moveEndpoint()` only apply one. Hover, keyboard and drag previews read the
+ * same projections, so a second copy of the interaction rules cannot drift
+ * into the DOM layer.
+ *
+ * Text entry is deliberately outside this machine: a typed pair may be
+ * temporarily inverted and report a validation error. It is the coordinator's
+ * job to forward only a displayable range to `calendar.highlightedRange`.
  */
 export class DateRangeController {
   constructor() {
@@ -69,7 +89,7 @@ export class DateRangeController {
     this.end = "";
   }
 
-  /** @returns {{start:string, end:string}} */
+  /** @returns {DateRange} */
   get range() {
     return { start: this.start, end: this.end };
   }
@@ -84,44 +104,178 @@ export class DateRangeController {
     this.activeEndpoint = endpoint;
   }
 
+  /** @param {"start" | "end"} endpoint @returns {RangeTransition} */
+  _refuse(endpoint) {
+    return {
+      status: "refused",
+      endpoint,
+      changedEndpoints: [],
+      range: this.range,
+      activeEndpoint: this.activeEndpoint,
+    };
+  }
+
   /**
-   * Process one grid activation through the active endpoint.
+   * Project one grid activation through the active endpoint, without mutating.
    *
    * `editable(bound)` reports whether a bound can receive a user pick. It
    * guards every commit and the `start -> end` transition: when the next bound
-   * is uneditable the returned result carries `close: true` instead of leaving
-   * the popup targeting a bound that can never change. `status: "complete"`
-   * stays reserved for an actually ordered pair.
+   * is uneditable the returned transition carries `close: true` instead of
+   * leaving the popup targeting a bound that can never change. `status:
+   * "complete"` stays reserved for an actually ordered pair.
    * @param {string} date
    * @param {(bound: "start" | "end") => boolean} [editable]
-   * @returns {{status: "pending" | "complete" | "refused", endpoint: "start" | "end", close?: boolean}}
+   * @returns {RangeTransition}
    */
-  activate(date, editable = () => true) {
+  project(date, editable = () => true) {
     if (!isDate(date)) throw new TypeError(`Invalid range activation: ${date}`);
-    if (this.complete && (compareDates(date, this.start) < 0 || compareDates(date, this.end) > 0)) {
-      const endpoint = compareDates(date, this.start) < 0 ? "start" : "end";
-      if (!editable(endpoint)) return { status: "refused", endpoint };
-      this[endpoint] = date;
-      this.activeEndpoint = endpoint;
-      return { status: "complete", endpoint };
+    const { start, end } = this;
+    if (this.complete && (compareDates(date, start) < 0 || compareDates(date, end) > 0)) {
+      const endpoint = compareDates(date, start) < 0 ? "start" : "end";
+      if (!editable(endpoint)) return this._refuse(endpoint);
+      return {
+        status: "complete",
+        endpoint,
+        changedEndpoints: [endpoint],
+        range: endpoint === "start" ? { start: date, end } : { start, end: date },
+        activeEndpoint: endpoint,
+      };
     }
     if (this.activeEndpoint === "end") {
-      if (this.start && compareDates(date, this.start) < 0) {
-        return { status: "refused", endpoint: "end" };
+      if (start && !end && compareDates(date, start) < 0) {
+        // Second pick of a range being created: sort it instead of refusing.
+        // Both bounds move at once, which is why a transition has to describe
+        // the whole pair rather than a single endpoint.
+        if (!editable("start")) return this._refuse("start");
+        if (!editable("end")) return this._refuse("end");
+        return {
+          status: "complete",
+          endpoint: "end",
+          changedEndpoints: ["start", "end"],
+          range: { start: date, end: start },
+          activeEndpoint: "end",
+        };
       }
-      if (!editable("end")) return { status: "refused", endpoint: "end" };
-      this.end = date;
-      return { status: this.start ? "complete" : "pending", endpoint: "end" };
+      // An existing pair keeps each bound's identity: an `end` before `start`
+      // is refused rather than rewriting `start` behind the user's back.
+      if (start && compareDates(date, start) < 0) return this._refuse("end");
+      if (!editable("end")) return this._refuse("end");
+      return {
+        status: start ? "complete" : "pending",
+        endpoint: "end",
+        changedEndpoints: ["end"],
+        range: { start, end: date },
+        activeEndpoint: "end",
+      };
+    }
+    if (end && !start && compareDates(date, end) > 0) {
+      // Mirror of the end-side sort, for a range anchored by its end: no
+      // calendar interaction may produce an inverted pair, from either side.
+      if (!editable("start")) return this._refuse("start");
+      if (!editable("end")) return this._refuse("end");
+      return {
+        status: "complete",
+        endpoint: "start",
+        changedEndpoints: ["start", "end"],
+        range: { start: end, end: date },
+        activeEndpoint: "start",
+      };
     }
-    if (!editable("start")) return { status: "refused", endpoint: "start" };
-    this.start = date;
-    if (!editable("end")) {
+    if (!editable("start")) return this._refuse("start");
+    const canContinue = editable("end");
+    return {
+      status: "pending",
+      endpoint: "start",
+      changedEndpoints: ["start"],
+      range: { start: date, end },
+      activeEndpoint: canContinue ? "end" : this.activeEndpoint,
       // The range stays incomplete but must close: the next bound cannot
       // receive the complementary pick.
-      return { status: "pending", endpoint: "start", close: true };
-    }
-    this.activeEndpoint = "end";
-    return { status: "pending", endpoint: "start" };
+      ...(canContinue ? {} : { close: true }),
+    };
+  }
+
+  /**
+   * Project a direct move of one bound (endpoint drag), without mutating.
+   *
+   * Only a complete, ordered pair offers two handles to grab, and a handle
+   * never crosses the other one: the candidate is clamped to the opposite
+   * bound, so the previewed band is exactly what a drop commits. Equality is
+   * allowed (a one-day range).
+   * @param {string} date
+   * @param {"start" | "end"} endpoint
+   * @param {(bound: "start" | "end") => boolean} [editable]
+   * @returns {RangeTransition}
+   */
+  projectEndpoint(date, endpoint, editable = () => true) {
+    if (!isDate(date)) throw new TypeError(`Invalid range activation: ${date}`);
+    if (!this.complete || !editable(endpoint)) return this._refuse(endpoint);
+    const { start, end } = this;
+    const previous = endpoint === "start" ? start : end;
+    const target = endpoint === "start" ? earlier(date, end) : later(date, start);
+    return {
+      status: "complete",
+      endpoint,
+      changedEndpoints: target === previous ? [] : [endpoint],
+      range: endpoint === "start" ? { start: target, end } : { start, end: target },
+      activeEndpoint: endpoint,
+    };
+  }
+
+  /**
+   * Displayable band a candidate date would produce, or `null` when there is
+   * nothing to promise. Single source of truth for hover, keyboard and drag
+   * previews: the projection rules with no mutation and no event.
+   *
+   * Without a drag handle a preview only speaks during range creation, when
+   * exactly one bound is anchored and the other is still open. An empty range
+   * has no anchor to project from, and a complete pair is not a promise in
+   * progress — previewing it would repaint the committed band on every hover.
+   * @param {string} date
+   * @param {"" | "start" | "end"} [endpoint] drag handle, empty for a normal pick
+   * @param {(bound: "start" | "end") => boolean} [editable]
+   * @returns {DateRange | null}
+   */
+  previewRange(date, endpoint = "", editable = () => true) {
+    if (!isDate(date)) return null;
+    if (!endpoint && Boolean(this.start) === Boolean(this.end)) return null;
+    const transition = endpoint
+      ? this.projectEndpoint(date, endpoint, editable)
+      : this.project(date, editable);
+    if (transition.status === "refused") return null;
+    const { start, end } = transition.range;
+    if (!start || (end && compareDates(end, start) < 0)) return null;
+    return { start, end };
+  }
+
+  /** @param {RangeTransition} transition @returns {RangeTransition} */
+  _apply(transition) {
+    if (transition.status === "refused") return transition;
+    this.start = transition.range.start;
+    this.end = transition.range.end;
+    this.activeEndpoint = transition.activeEndpoint;
+    return transition;
+  }
+
+  /**
+   * Apply one grid activation through the active endpoint.
+   * @param {string} date
+   * @param {(bound: "start" | "end") => boolean} [editable]
+   * @returns {RangeTransition}
+   */
+  activate(date, editable = () => true) {
+    return this._apply(this.project(date, editable));
+  }
+
+  /**
+   * Apply a direct move of one bound (endpoint drag).
+   * @param {string} date
+   * @param {"start" | "end"} endpoint
+   * @param {(bound: "start" | "end") => boolean} [editable]
+   * @returns {RangeTransition}
+   */
+  moveEndpoint(date, endpoint, editable = () => true) {
+    return this._apply(this.projectEndpoint(date, endpoint, editable));
   }
 }
 

package/src/date.js

@@ -165,9 +165,10 @@ export function endOfWeek(value, firstDay = 1) {
 }
 
 /**
- * True civil weeks covering the anchor month: 4..6 full rows, never padded.
+ * Civil weeks covering the anchor month: 4..6 full rows. Optional fixed weeks
+ * pads to six rows when a full extra week fits inside the canonical window.
  * @param {string} value YYYY-MM or YYYY-MM-DD
- * @param {{firstDay?: number}} [options]
+ * @param {{firstDay?: number, fixedWeeks?: boolean}} [options]
  */
 export function getMonthWeeks(value, options = {}) {
   const firstDay = options.firstDay ?? 1;
@@ -176,15 +177,68 @@ export function getMonthWeeks(value, options = {}) {
   /** @type {string[][]} */
   const weeks = [];
   let cursor = start;
-  while (compareDates(cursor, end) <= 0) {
+  for (;;) {
     const week = [];
     for (let i = 0; i < 7; i++) week.push(addDays(cursor, i));
     weeks.push(week);
+    // Stop from the built week's own end: advancing the cursor past the final
+    // week (e.g. from 9999-12-25 to 10000-01-01) would leave the canonical
+    // window even when every emitted day is valid.
+    if (compareDates(week[6], end) >= 0) {
+      // Another complete week must fit before the last canonical date.
+      if (!options.fixedWeeks || weeks.length >= 6 || compareDates(week[6], addDays("9999-12-31", -7)) > 0)
+        break;
+    }
     cursor = addDays(cursor, 7);
   }
   return weeks;
 }
 
+/**
+ * 0-based civil day count since 0001-01-01. Used to compare instants that may
+ * fall one day outside the canonical 0001..9999 window without building an
+ * invalid ISO string.
+ * @param {number} year @param {number} month @param {number} day
+ */
+function dayOrdinal(year, month, day) {
+  const base = toUTCDate({ year: 1, month: 1, day: 1 });
+  return Math.round((toUTCDate({ year, month, day }).getTime() - base.getTime()) / 86400000);
+}
+
+/**
+ * Nearest month whose true civil weeks stay inside 0001-01-01..9999-12-31, so a
+ * grid can always be built. A month's covering weeks can reach a few days
+ * before or after it, so the earliest and latest displayable months depend on
+ * `firstDay`.
+ * @param {string} value YYYY-MM or YYYY-MM-DD
+ * @param {number} [firstDay]
+ * @returns {string} YYYY-MM
+ */
+export function clampDisplayMonth(value, firstDay = 1) {
+  const normalized = normalizeFirstDay(firstDay);
+  const maxOrdinal = dayOrdinal(9999, 12, 31);
+  let key = monthKey(value);
+  for (;;) {
+    const parsed = parseDate(`${key}-01`);
+    if (!parsed) throw new TypeError(`Invalid civil date/month: ${value}`);
+    const startOrdinal = dayOrdinal(parsed.year, parsed.month, 1);
+    const startOffset = (toUTCDate(parsed).getUTCDay() - normalized + 7) % 7;
+    if (startOrdinal - startOffset < 0) {
+      key = shiftMonth(key, 1);
+      continue;
+    }
+    const lastDay = daysInMonth(parsed.year, parsed.month);
+    const endParts = { year: parsed.year, month: parsed.month, day: lastDay };
+    const endOrdinal = startOrdinal + lastDay - 1;
+    const endOffset = (toUTCDate(endParts).getUTCDay() - normalized + 7) % 7;
+    if (endOrdinal - endOffset + 6 > maxOrdinal) {
+      key = shiftMonth(key, -1);
+      continue;
+    }
+    return key;
+  }
+}
+
 /** @param {string} value @param {string} [min] @param {string} [max] */
 export function clampDate(value, min = "", max = "") {
   if (!isDate(value)) throw new TypeError(`Invalid civil date: ${value}`);

package/src/index.js

@@ -1,4 +1,5 @@
 export { CalendarModel } from "./calendar-model.js";
+export { getDefaultControlClasses, setDefaultControlClasses } from "./control-classes.js";
 export * as dates from "./date.js";
 export { DateCalendarElement } from "./date-calendar.js";
 export { DatePickerElement } from "./date-picker.js";

package/src/intl.js

@@ -2,6 +2,33 @@ import { isDate, normalizeFirstDay, parseDate, toIntlDate, toISODate } from "./d
 
 const BIDI = /[\u200e\u200f\u061c\u202a-\u202e\u2066-\u2069]/g;
 
+/** @type {Map<string, Intl.DateTimeFormat>} */
+const dateFormatters = new Map();
+/** @type {Map<string, Map<string, string>>} */
+const digitMaps = new Map();
+
+/**
+ * Bound retained locales/options even when an application cycles through many.
+ * @template T
+ * @param {Map<string, T>} cache @param {string} key @param {() => T} create
+ * @returns {T}
+ */
+function cached(cache, key, create) {
+  const existing = cache.get(key);
+  if (existing !== undefined) return existing;
+  const value = create();
+  const oldest = cache.keys().next().value;
+  if (cache.size >= 64 && oldest !== undefined) cache.delete(oldest);
+  cache.set(key, value);
+  return value;
+}
+
+/** @param {string} locale @param {Intl.DateTimeFormatOptions} options */
+function dateFormatter(locale, options) {
+  const key = JSON.stringify([locale, options]);
+  return cached(dateFormatters, key, () => new Intl.DateTimeFormat(locale, options));
+}
+
 /** @param {string} [locale] */
 export function resolveLocale(locale = "") {
   if (locale) return locale;
@@ -12,17 +39,22 @@ export function resolveLocale(locale = "") {
 
 /** @param {string} locale */
 function digitMap(locale) {
-  const formatter = new Intl.NumberFormat(locale, { useGrouping: false });
-  const map = new Map();
-  for (let i = 0; i <= 9; i++) map.set(formatter.format(i), String(i));
-  return map;
+  return cached(digitMaps, locale, () => {
+    const formatter = new Intl.NumberFormat(locale, { useGrouping: false });
+    const map = new Map();
+    for (let i = 0; i <= 9; i++) map.set(formatter.format(i), String(i));
+    return map;
+  });
 }
 
-/** @param {string} text @param {string} locale */
-function normalizeDigits(text, locale) {
-  let result = String(text || "")
-    .replace(BIDI, "")
-    .trim();
+/**
+ * @param {string} text @param {string} locale
+ * @param {{trim?: boolean}} [options] `trim` defaults to true; literal segments
+ * must keep their whitespace so the format's own spacing can be matched.
+ */
+function normalizeDigits(text, locale, options = {}) {
+  let result = String(text || "").replace(BIDI, "");
+  if (options.trim !== false) result = result.trim();
   for (const [local, ascii] of digitMap(locale)) result = result.split(local).join(ascii);
   return result;
 }
@@ -30,7 +62,7 @@ function normalizeDigits(text, locale) {
 /** @param {string} value @param {string} [locale] */
 export function formatLongDate(value, locale = "") {
   const resolved = resolveLocale(locale);
-  return new Intl.DateTimeFormat(resolved, {
+  return dateFormatter(resolved, {
     calendar: "gregory",
     weekday: "long",
     year: "numeric",
@@ -43,7 +75,7 @@ export function formatLongDate(value, locale = "") {
 /** @param {string} value @param {string} [locale] */
 export function formatMonthYear(value, locale = "") {
   const resolved = resolveLocale(locale);
-  return new Intl.DateTimeFormat(resolved, {
+  return dateFormatter(resolved, {
     calendar: "gregory",
     year: "numeric",
     month: "long",
@@ -62,7 +94,7 @@ export function formatMonthYear(value, locale = "") {
 export function monthYearOrder(locale = "") {
   const resolved = resolveLocale(locale);
   try {
-    const parts = new Intl.DateTimeFormat(resolved, {
+    const parts = dateFormatter(resolved, {
       calendar: "gregory",
       year: "numeric",
       month: "long",
@@ -89,7 +121,7 @@ export function monthYearOrder(locale = "") {
 /** @param {string} [locale] @param {"long"|"short"} [style] */
 export function monthNames(locale = "", style = "long") {
   const resolved = resolveLocale(locale);
-  const formatter = new Intl.DateTimeFormat(resolved, { calendar: "gregory", month: style, timeZone: "UTC" });
+  const formatter = dateFormatter(resolved, { calendar: "gregory", month: style, timeZone: "UTC" });
   return Array.from({ length: 12 }, (_, index) =>
     formatter.format(toIntlDate(`2026-${String(index + 1).padStart(2, "0")}-15`)),
   );
@@ -102,7 +134,7 @@ export function monthNames(locale = "", style = "long") {
  */
 export function weekdayNames(locale = "", firstDay = 1, style = "short") {
   const resolved = resolveLocale(locale);
-  const formatter = new Intl.DateTimeFormat(resolved, {
+  const formatter = dateFormatter(resolved, {
     calendar: "gregory",
     weekday: style,
     timeZone: "UTC",
@@ -128,7 +160,7 @@ function escapeRegExp(value) {
  */
 export function createDateAdapter(locale = "") {
   const resolved = resolveLocale(locale);
-  const formatter = new Intl.DateTimeFormat(resolved, {
+  const formatter = dateFormatter(resolved, {
     calendar: "gregory",
     year: "numeric",
     month: "2-digit",
@@ -150,8 +182,11 @@ export function createDateAdapter(locale = "") {
     .map((part) => {
       if (part.type === "day" || part.type === "month") return "(\\d{1,2})";
       if (part.type === "year") return "(\\d{4})";
-      const literal = normalizeDigits(part.value, resolved).replace(/\s+/g, " ");
-      return escapeRegExp(literal).replace(/\\ /g, "\\s*");
+      // Literals keep their own spacing, so a run of blanks becomes an optional
+      // separator: locales such as ko-KR ("2026. 09. 06.") or bg-BG ("... г.")
+      // format with spaces the user may omit or retype.
+      const literal = normalizeDigits(part.value, resolved, { trim: false });
+      return escapeRegExp(literal).replace(/\s+/g, "\\s*");
     })
     .join("");
   const regex = new RegExp(`^\\s*${pattern}\\s*$`);

package/src/source.js

@@ -28,17 +28,27 @@ export function normalizeDateStates(payload) {
 
 /**
  * Small fetch adapter for legacy/configUrl-like endpoints.
+ * Resolve and validate the URL immediately against the document or worker location.
  * @param {string | URL} url
  * @param {{map?:(payload:unknown)=>unknown, params?:(range:{start:string,end:string})=>Record<string,string>}} [options]
  */
 export function createFetchSource(url, options = {}) {
+  const base = typeof document !== "undefined" ? document.baseURI : globalThis.location?.href;
+  let resolved;
+  try {
+    resolved = new URL(String(url), base);
+  } catch (cause) {
+    throw new TypeError(
+      base
+        ? `Invalid date source URL: ${url}`
+        : "Date source: absolute URL required outside a document or worker location",
+      { cause },
+    );
+  }
   return {
     /** @param {{start:string,end:string}} range @param {{signal?:AbortSignal}} [context] */
     async load(range, context = {}) {
-      const target = new URL(
-        String(url),
-        typeof document !== "undefined" ? document.baseURI : "http://localhost/",
-      );
+      const target = new URL(resolved);
       const params = options.params ? options.params(range) : range;
       for (const [key, value] of Object.entries(params)) target.searchParams.set(key, String(value));
       const response = await fetch(target, { signal: context.signal });