@lekoala/date-picker 0.3.0 → 0.4.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

@@ -176,15 +176,64 @@ 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) 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/intl.js

@@ -18,11 +18,14 @@ function digitMap(locale) {
   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;
 }
@@ -150,8 +153,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*$`);