@lekoala/date-picker 0.3.0 → 0.5.0

package/src/date-calendar.js

@@ -1,13 +1,15 @@
 import { CalendarModel } from "./calendar-model.js";
+import { getDefaultControlClasses, resolveControlClasses, sameControlClasses } from "./control-classes.js";
 import {
   addDays,
   clampDate,
+  clampDisplayMonth,
   compareDates,
+  endOfMonth,
   getMonthWeeks,
   isDate,
   isoWeekNumber,
   monthKey,
-  shiftMonth,
   todayISO,
 } from "./date.js";
 import { normalizeRange, rangePosition } from "./date-range.js";
@@ -46,20 +48,43 @@ function yearOf(month) {
   return Number(month.slice(0, 4));
 }
 
+/**
+ * Step a `YYYY-MM` key by ±1, or `null` when the step leaves the canonical
+ * 0001-01..9999-12 window. Pure arithmetic, so an out-of-range intermediate
+ * date is never constructed and the calendar edges cannot throw.
+ * @param {string} month
+ * @param {number} amount
+ * @returns {string | null}
+ */
+function stepMonthKey(month, amount) {
+  const [year, index] = month.split("-").map(Number);
+  const absolute = year * 12 + (index - 1) + amount;
+  const stepYear = Math.floor(absolute / 12);
+  const stepMonth = (((absolute % 12) + 12) % 12) + 1;
+  if (stepYear < 1 || stepYear > 9999) return null;
+  return `${String(stepYear).padStart(4, "0")}-${String(stepMonth).padStart(2, "0")}`;
+}
+
+/**
+ * Band attributes for one day position. Markup and in-place band updates read
+ * the same map, so the two paths cannot disagree about a cell's state.
+ * @param {"" | "start" | "in" | "end" | "single"} position
+ * @returns {Record<string, boolean>}
+ */
+function rangeAttributeMap(position) {
+  return {
+    "data-range-start": position === "start" || position === "single",
+    "data-range-end": position === "end" || position === "single",
+    "data-in-range": position === "in",
+  };
+}
+
 /** @param {"" | "start" | "in" | "end" | "single"} position */
 function rangeAttributes(position) {
-  switch (position) {
-    case "single":
-      return ' data-range-start="true" data-range-end="true"';
-    case "start":
-      return ' data-range-start="true"';
-    case "end":
-      return ' data-range-end="true"';
-    case "in":
-      return ' data-in-range="true"';
-    default:
-      return "";
-  }
+  return Object.entries(rangeAttributeMap(position))
+    .filter(([, on]) => on)
+    .map(([name]) => ` ${name}="true"`)
+    .join("");
 }
 
 /** @param {"" | "start" | "in" | "end" | "single"} position */
@@ -125,7 +150,16 @@ export class DateCalendarElement extends HTMLElement {
     this._isDateDisabled = null;
     /** @type {DateRange} */
     this._highlightedRange = { start: "", end: "" };
+    // Bounds and preview flag the cells were last painted with. The preview
+    // flag changes the accessible names (a proposal drops the committed
+    // range-start/range-end suffix), so a repaint is due when either changes.
+    /** @type {DateRange} */
+    this._paintedRange = { start: "", end: "" };
+    this._paintedPreview = false;
+    /** @type {Map<string, DateState>} States of the current rendered grid. */
+    this._renderedStates = new Map();
     this._messages = getDefaultMessages();
+    this._controlClasses = getDefaultControlClasses();
     this._onClick = this._onClick.bind(this);
     this._onChange = this._onChange.bind(this);
     this._onKeyDown = this._onKeyDown.bind(this);
@@ -262,9 +296,17 @@ export class DateCalendarElement extends HTMLElement {
 
   set highlightedRange(value) {
     const next = normalizeRange(value);
-    if (next.start === this._highlightedRange.start && next.end === this._highlightedRange.end) return;
+    const preview = this.hasAttribute("data-range-preview");
+    // Repaint when the preview mode changed even if the bounds are identical:
+    // entering/leaving a preview rewrites every cell's accessible name.
+    if (
+      next.start === this._paintedRange.start &&
+      next.end === this._paintedRange.end &&
+      preview === this._paintedPreview
+    )
+      return;
     this._highlightedRange = next;
-    if (this._connected) this.render();
+    if (this._connected) this._updateRangeDom();
   }
 
   /** @public */
@@ -285,6 +327,23 @@ export class DateCalendarElement extends HTMLElement {
     this.toggleAttribute("show-week-numbers", Boolean(value));
   }
 
+  /**
+   * Author classes for header controls; merged with global defaults.
+   * @public
+   * @returns {import("./control-classes.js").ControlClasses}
+   */
+  get controlClasses() {
+    return { ...this._controlClasses };
+  }
+
+  /** @param {Partial<import("./control-classes.js").ControlClasses> | null} value */
+  set controlClasses(value) {
+    const classes = resolveControlClasses(value);
+    if (sameControlClasses(classes, this._controlClasses)) return;
+    this._controlClasses = classes;
+    if (this._connected) this.render();
+  }
+
   /** @public */
   get messages() {
     return this._messages;
@@ -343,7 +402,7 @@ export class DateCalendarElement extends HTMLElement {
     const attrDisplay = this.getAttribute("display") || "";
     if (attrDisplay) {
       try {
-        this._model.setDisplay(attrDisplay);
+        this._model.setDisplay(clampDisplayMonth(attrDisplay, firstDay));
       } catch {
         // Invalid author markup falls back to the current model display.
       }
@@ -368,20 +427,24 @@ export class DateCalendarElement extends HTMLElement {
 
   /** @param {string} value */
   _clamp(value) {
-    return clampDate(value, this.min, this.max);
+    const bounded = clampDate(value, this.min, this.max);
+    const month = monthKey(bounded);
+    const safeMonth = clampDisplayMonth(month, this.firstDay);
+    if (safeMonth === month) return bounded;
+    // The renderable window excludes this month (a calendar edge): keep the
+    // day-of-month where the target month has it, else fall back to its last
+    // day, so the focused date always exists in the rendered grid.
+    const day = Number(bounded.slice(8, 10)) || 1;
+    const candidate = addDays(`${safeMonth}-01`, day - 1);
+    const last = endOfMonth(safeMonth);
+    return compareDates(candidate, last) > 0 ? last : candidate;
   }
 
   _weeks(display = this.display) {
-    const weeks = getMonthWeeks(display, { firstDay: this.firstDay });
-    if (!this.fixedWeeks || weeks.length >= 6) return weeks;
-    let cursor = weeks[weeks.length - 1]?.[6] || "";
-    while (weeks.length < 6 && cursor) {
-      const week = [];
-      for (let i = 1; i <= 7; i++) week.push(addDays(cursor, i));
-      weeks.push(week);
-      cursor = week[6];
-    }
-    return weeks;
+    return getMonthWeeks(clampDisplayMonth(display, this.firstDay), {
+      firstDay: this.firstDay,
+      fixedWeeks: this.fixedWeeks,
+    });
   }
 
   /** @param {HTMLElement} element @returns {string} */
@@ -491,7 +554,7 @@ export class DateCalendarElement extends HTMLElement {
   /** @param {string} display @param {{emit?:boolean}} [options] */
   _setDisplay(display, options = {}) {
     const previous = this._model.display;
-    this._model.setDisplay(display);
+    this._model.setDisplay(clampDisplayMonth(display, this.firstDay));
     this._model.focused = this._clamp(this._model.focused);
     this._model.display = monthKey(this._model.focused);
     this._reflect("display", this._model.display);
@@ -512,12 +575,12 @@ export class DateCalendarElement extends HTMLElement {
 
   /** @public */
   previousMonth() {
-    return this._setDisplay(shiftMonth(this.display, -1));
+    return this._setDisplay(stepMonthKey(this.display, -1) ?? this.display);
   }
 
   /** @public */
   nextMonth() {
-    return this._setDisplay(shiftMonth(this.display, 1));
+    return this._setDisplay(stepMonthKey(this.display, 1) ?? this.display);
   }
 
   /** @public @param {string} date @param {{moveFocus?:boolean}} [options] */
@@ -572,14 +635,72 @@ export class DateCalendarElement extends HTMLElement {
     return false;
   }
 
+  /**
+   * Accessible name of one day cell. The band contribution is dropped while a
+   * preview is projected onto `highlightedRange`: a proposal must not be
+   * announced as a committed range start/end.
+   * @param {string} date @param {DateState} state
+   * @param {"" | "start" | "in" | "end" | "single"} position
+   */
+  _dayLabel(date, state, position) {
+    const rangeLabel = this.hasAttribute("data-range-preview") ? "" : rangeLabelKey(position);
+    const description = typeof state.description === "string" ? state.description : "";
+    return [
+      formatLongDate(date, this.locale),
+      description,
+      rangeLabel ? this._messages[rangeLabel] : "",
+      state.disabled ? this._messages.unavailable : "",
+    ]
+      .filter(Boolean)
+      .join(". ");
+  }
+
+  /**
+   * Repaint the range band over the cells already rendered. The band is
+   * presentation on top of the same grid, so it must never rebuild it: a full
+   * render would drop `renderDay()` nodes and fight the roving focus on every
+   * hover of a live range preview.
+   */
+  _updateRangeDom() {
+    const previousRange = this._paintedRange;
+    const previousPreview = this._paintedPreview;
+    this._paintedRange = { ...this._highlightedRange };
+    this._paintedPreview = this.hasAttribute("data-range-preview");
+    for (const cell of this.querySelectorAll(".dp-day[data-date]")) {
+      if (!(cell instanceof HTMLTableCellElement)) continue;
+      const date = cell.dataset.date || "";
+      const position = rangePosition(date, this._highlightedRange);
+      if (position === rangePosition(date, previousRange) && previousPreview === this._paintedPreview)
+        continue;
+      for (const [name, on] of Object.entries(rangeAttributeMap(position))) {
+        if (on) cell.setAttribute(name, "true");
+        else cell.removeAttribute(name);
+      }
+      // A moving preview changes only the band. Its accessible labels always
+      // omit range roles; entering/leaving preview still updates those labels.
+      if (!previousPreview || !this._paintedPreview) {
+        const state = this._renderedStates.get(date) || {};
+        const label = this._dayLabel(date, state, position);
+        if (cell.getAttribute("aria-label") !== label) cell.setAttribute("aria-label", label);
+      }
+    }
+  }
+
   /** @public */
   focusGrid() {
     const target = this.querySelector(`.dp-day[data-date="${CSS.escape(this.focusedDate)}"]`);
     if (target instanceof HTMLElement) target.focus();
   }
 
-  /** @param {string} date @returns {Promise<boolean>} */
-  async _activate(date) {
+  /**
+   * Run one explicit activation: availability check, then the cancelable
+   * `dateactivate` seam, then selection. Click, keyboard and any other input
+   * device share this single path, so an application that cancels
+   * `dateactivate` cannot be bypassed by a new interaction.
+   * @public
+   * @param {string} date @returns {Promise<boolean>}
+   */
+  async activateDate(date) {
     // Guarantee remote state before deciding: a date clicked before the
     // source resolves must not be treated as available, and a cancelled or
     // failed load must not authorize it either.
@@ -633,7 +754,7 @@ export class DateCalendarElement extends HTMLElement {
     this._model.setFocused(this._clamp(date));
     this._reflect("display", this._model.display);
     if (previousDisplay !== this.display) this._emitDisplayChange();
-    void this._activate(date);
+    void this.activateDate(date);
   }
 
   /** @param {Event} event */
@@ -645,7 +766,9 @@ export class DateCalendarElement extends HTMLElement {
     }
     if (target instanceof HTMLInputElement && target.matches(".dp-year-input")) {
       const year = Number(target.value);
-      if (!Number.isInteger(year) || year < 1 || year > 9999) {
+      // 9999 is a valid civil year but its December grid overflows into 10000,
+      // so the editable range stops one year short of the unrenderable month.
+      if (!Number.isInteger(year) || year < 1 || year > 9998) {
         if (this._connected) this.render(false);
         return;
       }
@@ -653,12 +776,22 @@ export class DateCalendarElement extends HTMLElement {
     }
   }
 
-  /** @param {FocusEvent} event */
+  /**
+   * Real DOM focus is the single source of truth for `datefocus`: the model is
+   * synced here and the event is announced from here, so the temporary focus
+   * arithmetic in `_onKeyDown` cannot emit phantom events, and setting
+   * `focusedDate` without moving focus stays silent.
+   * @param {FocusEvent} event
+   */
   _onFocusIn(event) {
     const target = event.target;
     if (!(target instanceof HTMLTableCellElement) || !target.matches(".dp-day[data-date]")) return;
     const date = target.dataset.date || "";
-    if (isDate(date)) this._model.focused = date;
+    if (!isDate(date)) return;
+    this._model.focused = date;
+    this.dispatchEvent(
+      new CustomEvent("datefocus", { detail: { date, state: this.getDateState(date) }, bubbles: true }),
+    );
   }
 
   /** @param {KeyboardEvent} event */
@@ -668,7 +801,7 @@ export class DateCalendarElement extends HTMLElement {
     const date = target.dataset.date || this.focusedDate;
     if (event.key === "Enter" || event.key === " ") {
       event.preventDefault();
-      void this._activate(date);
+      void this.activateDate(date);
       return;
     }
     // Movement primitives live in CalendarModel; the DOM only syncs render/focus.
@@ -712,8 +845,10 @@ export class DateCalendarElement extends HTMLElement {
     const gridId = `${this._id}-grid`;
     const minMonth = this.min ? monthKey(this.min) : "";
     const maxMonth = this.max ? monthKey(this.max) : "";
-    const prevDisabled = Boolean(minMonth && shiftMonth(display, -1) < minMonth);
-    const nextDisabled = Boolean(maxMonth && shiftMonth(display, 1) > maxMonth);
+    const prevKey = stepMonthKey(display, -1);
+    const nextKey = stepMonthKey(display, 1);
+    const prevDisabled = Boolean(minMonth && prevKey !== null && prevKey < minMonth);
+    const nextDisabled = Boolean(maxMonth && nextKey !== null && nextKey > maxMonth);
     const minYearAttr = this.min ? ` min="${Number(this.min.slice(0, 4))}"` : "";
     const maxYearAttr = this.max ? ` max="${Number(this.max.slice(0, 4))}"` : "";
     const showWeeks = this.showWeekNumbers && this.firstDay === 1;
@@ -737,6 +872,7 @@ export class DateCalendarElement extends HTMLElement {
       )
       .join("");
 
+    this._renderedStates.clear();
     const rows = weeks
       .map((week) => {
         const weekNumber = showWeeks
@@ -745,21 +881,13 @@ export class DateCalendarElement extends HTMLElement {
         const cells = week
           .map((date) => {
             const state = this.getDateState(date);
+            this._renderedStates.set(date, state);
             const outside = monthKey(date) !== display;
             const selected = this.value === date;
             const focused = this.focusedDate === date;
             const isToday = date === today;
             const position = rangePosition(date, this._highlightedRange);
-            const rangeLabel = rangeLabelKey(position);
-            const description = typeof state.description === "string" ? state.description : "";
-            const label = [
-              formatLongDate(date, locale),
-              description,
-              rangeLabel ? this._messages[rangeLabel] : "",
-              state.disabled ? this._messages.unavailable : "",
-            ]
-              .filter(Boolean)
-              .join(". ");
+            const label = this._dayLabel(date, state, position);
             return `<td class="dp-day" data-date="${date}"${outside ? ' data-outside-month="true"' : ""}${isToday ? ' data-today="true" aria-current="date"' : ""}${selected ? ' data-selected="true" aria-selected="true"' : ""}${rangeAttributes(position)}${state.disabled ? ' data-disabled="true" aria-disabled="true"' : ""} tabindex="${focused ? "0" : "-1"}" aria-label="${escapeHtml(label)}"><span class="dp-day-number" aria-hidden="true">${Number(date.slice(8, 10))}</span><span class="dp-day-extra" aria-hidden="true"></span></td>`;
           })
           .join("");
@@ -778,10 +906,14 @@ export class DateCalendarElement extends HTMLElement {
     // select via `data-year-first`.
     const yearFirst = monthYearOrder(locale)[0] === "year";
     this.toggleAttribute("data-year-first", yearFirst);
+    const classes = this._controlClasses;
+    const monthClass = escapeHtml(classes.month || "dp-skin");
+    const yearClass = escapeHtml(classes.year || "dp-skin");
+    const navClass = escapeHtml(classes.nav || "dp-skin");
     const monthControl = `<label class="dp-visually-hidden" for="${this._id}-month">${escapeHtml(this._messages.month)}</label>
-          <select id="${this._id}-month" class="dp-month-select" aria-label="${escapeHtml(this._messages.month)}">${monthOptions}</select>`;
+          <select id="${this._id}-month" class="dp-month-select ${monthClass}" aria-label="${escapeHtml(this._messages.month)}">${monthOptions}</select>`;
     const yearControl = `<label class="dp-visually-hidden" for="${this._id}-year">${escapeHtml(this._messages.year)}</label>
-          <input id="${this._id}-year" class="dp-year-input" type="number" inputmode="numeric" value="${displayYear}"${minYearAttr}${maxYearAttr} aria-label="${escapeHtml(this._messages.year)}">`;
+          <input id="${this._id}-year" class="dp-year-input ${yearClass}" type="number" inputmode="numeric" value="${displayYear}"${minYearAttr}${maxYearAttr} aria-label="${escapeHtml(this._messages.year)}">`;
 
     this._rendering = true;
     this.innerHTML = `
@@ -789,8 +921,8 @@ export class DateCalendarElement extends HTMLElement {
         <div class="dp-calendar-header">
           ${yearFirst ? yearControl : monthControl}
           ${yearFirst ? monthControl : yearControl}
-          <button type="button" class="dp-nav dp-prev" data-calendar-action="previous" aria-label="${escapeHtml(this._messages.previousMonth)}"${prevDisabled ? " disabled" : ""}><svg aria-hidden="true" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="m10 4-4 4 4 4"/></svg></button>
-          <button type="button" class="dp-nav dp-next" data-calendar-action="next" aria-label="${escapeHtml(this._messages.nextMonth)}"${nextDisabled ? " disabled" : ""}><svg aria-hidden="true" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="m6 4 4 4-4 4"/></svg></button>
+          <button type="button" class="dp-nav dp-prev ${navClass}" data-calendar-action="previous" aria-label="${escapeHtml(this._messages.previousMonth)}"${prevDisabled ? " disabled" : ""}><svg aria-hidden="true" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="m4 10 4-4 4 4"/></svg></button>
+          <button type="button" class="dp-nav dp-next ${navClass}" data-calendar-action="next" aria-label="${escapeHtml(this._messages.nextMonth)}"${nextDisabled ? " disabled" : ""}><svg aria-hidden="true" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="m4 6 4 4 4-4"/></svg></button>
         </div>
         <h2 id="${headingId}" class="dp-calendar-heading dp-visually-hidden" aria-live="polite">${escapeHtml(formatMonthYear(`${display}-15`, locale))}</h2>
         <table id="${gridId}" class="dp-grid" role="grid" aria-labelledby="${headingId}">
@@ -799,6 +931,8 @@ export class DateCalendarElement extends HTMLElement {
         </table>
       </div>`;
     this._rendering = false;
+    this._paintedRange = { ...this._highlightedRange };
+    this._paintedPreview = this.hasAttribute("data-range-preview");
 
     if (focusKey) {
       queueMicrotask(() => {
@@ -822,7 +956,7 @@ export class DateCalendarElement extends HTMLElement {
         const date = cell.dataset.date || "";
         const extra = cell.querySelector(".dp-day-extra");
         if (!(extra instanceof HTMLElement)) continue;
-        const content = this._renderDay(date, this.getDateState(date));
+        const content = this._renderDay(date, this._renderedStates.get(date) || {});
         if (content instanceof Node) extra.append(content);
         else if (content !== undefined && content !== null) extra.textContent = String(content);
       }

package/src/date-field.js

@@ -33,8 +33,9 @@ export class DateFieldController {
     this.onAttributesChanged = null;
     /**
      * Async availability gate for a parsed date. Returning `{ ok: false }`
-     * marks the target unavailable. Swappable at runtime.
-     * @type {((date: string) => Promise<{ok: boolean, message?: string}>) | null}
+     * marks the target unavailable. Swappable at runtime. The commit options
+     * are forwarded so the gate can honor `moveDisplay`.
+     * @type {((date: string, options?: {moveDisplay?: boolean}) => Promise<{ok: boolean, message?: string}>) | null}
      */
     this.confirm = null;
   }
@@ -137,16 +138,19 @@ export class DateFieldController {
       input.setCustomValidity("");
       return;
     }
-    input.setCustomValidity(text === canonical ? "" : this.messages.invalidDate);
+    input.setCustomValidity(this.messages.invalidDate);
   }
 
   /**
    * Commit the visible text. Returns the parsed canonical date on success, the
    * empty string on a clear, or a falsy marker for invalid/stale commits. The
    * caller applies the canonical value so reflection and events stay central.
+   * `options` is forwarded to the `confirm` gate so a revalidation can ask it
+   * not to move the calendar display (source reloads must not re-home it).
+   * @param {{moveDisplay?: boolean}} [options]
    * @returns {Promise<{status: "ok" | "clear" | "invalid" | "stale", value?: string}>}
    */
-  async commit() {
+  async commit(options = {}) {
     const input = this.input;
     const commitId = ++this._commitId;
     const text = input.value.trim();
@@ -163,7 +167,7 @@ export class DateFieldController {
       return { status: "invalid" };
     }
     if (this.confirm) {
-      const result = await this.confirm(parsed);
+      const result = await this.confirm(parsed, options);
       if (commitId !== this._commitId) return { status: "stale" };
       if (!result?.ok) {
         if (this.hidden) this.hidden.value = "";

package/src/date-picker.css

@@ -6,6 +6,8 @@
   --dp-hover: color-mix(in srgb, var(--dp-fg) 5%, var(--dp-bg));
   --dp-accent: #2563eb;
   --dp-accent-fg: #fff;
+  --dp-focus: var(--dp-accent);
+  --dp-focus-width: 2px;
   --dp-radius: 0.5rem;
   --dp-day-size: 2.75rem;
   --dp-gap: 0.375rem;
@@ -44,7 +46,7 @@ date-calendar {
 
 .dp-calendar-header {
   display: grid;
-  grid-template-columns: minmax(0, 1fr) auto auto auto;
+  grid-template-columns: minmax(0, 1fr) var(--dp-year-inline-size) auto auto;
   /* Stretch (not center): once a UA natural height exceeds
      --dp-header-control-size, the row grows to the tallest control and the
      others stretch to match, so month/year/nav stay equal. */
@@ -60,12 +62,16 @@ date-calendar {
    track stays under the month select so the fixed-width year input never
    stretches. Visual mirroring itself is left to the inherited `dir`. */
 date-calendar[data-year-first] .dp-calendar-header {
-  grid-template-columns: auto minmax(0, 1fr) auto auto;
+  grid-template-columns: var(--dp-year-inline-size) minmax(0, 1fr) auto auto;
 }
 
 .dp-calendar-header :where(button, select, input) {
-  min-block-size: var(--dp-header-control-size);
   box-sizing: border-box;
+  min-inline-size: 0;
+}
+
+.dp-calendar-header .dp-skin {
+  min-block-size: var(--dp-header-control-size);
   /* Shared vertical metrics: UA default padding/line-height differ per control
      (up to ~13px apart), which only shows once --dp-header-control-size drops
      below content size. */
@@ -78,8 +84,7 @@ date-calendar[data-year-first] .dp-calendar-header {
   line-height: 1.2;
 }
 
-.dp-calendar-header input {
-  min-inline-size: 0;
+.dp-calendar-header input.dp-skin {
   padding-inline: 0.45rem;
 }
 
@@ -89,11 +94,13 @@ date-calendar[data-year-first] .dp-calendar-header {
    control and the others stretch to match. */
 .dp-month-select {
   inline-size: 100%;
-  min-inline-size: 0;
   /* Long month names in a narrow track (compact consumers, long locales)
      would paint under the caret: truncate with an ellipsis instead. */
   overflow: hidden;
   text-overflow: ellipsis;
+}
+
+.dp-month-select.dp-skin {
   appearance: none;
   padding-inline: 0.45rem 2rem;
   background-image:
@@ -109,18 +116,18 @@ date-calendar[data-year-first] .dp-calendar-header {
 /* Inherited RTL mirrors the header layout via the grid. The logical
    `padding-inline` already flips, so only the physically-positioned caret has
    to follow it to the other side. */
-[dir="rtl"] .dp-month-select,
-html[dir="rtl"] .dp-month-select {
+[dir="rtl"] .dp-month-select.dp-skin,
+html[dir="rtl"] .dp-month-select.dp-skin {
   background-position:
     0.9rem 50%,
     0.65rem 50%;
 }
 
 .dp-year-input {
-  inline-size: var(--dp-year-inline-size);
+  inline-size: 100%;
 }
 
-.dp-nav {
+.dp-nav.dp-skin {
   display: grid;
   place-items: center;
   inline-size: var(--dp-header-control-size);
@@ -137,30 +144,23 @@ html[dir="rtl"] .dp-month-select {
   pointer-events: none;
 }
 
-/* Inherited RTL mirrors the header layout via the grid; mirror the nav glyphs
-   so previous/next keep their visual sense. Actions stay chronological: no
-   button swap, no keyboard remapping. */
-[dir="rtl"] .dp-nav svg,
-html[dir="rtl"] .dp-nav svg {
-  transform: scaleX(-1);
-}
-
-.dp-calendar-header :where(button, select, input):disabled,
+.dp-calendar-header .dp-skin:disabled,
 .dp-picker-button:disabled {
   cursor: not-allowed;
   opacity: 0.45;
 }
 
-.dp-nav:hover:not(:disabled) {
+.dp-nav.dp-skin:hover:not(:disabled) {
   background: var(--dp-hover);
 }
 
-/* Shared control focus: accent border + light halo. Day cells keep their
-   dedicated outline ring below; the picker trigger has its own inner ring. */
-.dp-calendar-header :where(button, select, input):focus-visible {
-  outline: none;
-  border-color: var(--dp-accent);
-  box-shadow: 0 0 0 3px color-mix(in srgb, var(--dp-accent) 22%, transparent);
+/* Inner outlines survive forced colors and keep focus inside each control.
+   The picker trigger uses a tighter inset around its icon below. */
+.dp-calendar-header .dp-skin:focus-visible,
+date-picker > input:not([type="hidden"]):focus-visible,
+.dp-day:focus-visible {
+  outline: var(--dp-focus-width) solid var(--dp-focus);
+  outline-offset: calc(var(--dp-focus-width) * -1);
 }
 
 .dp-day:hover:not([data-disabled="true"]):not([data-selected="true"]):not([data-range-start="true"]):not(
@@ -205,15 +205,6 @@ html[dir="rtl"] .dp-nav svg {
   font-size: 0.875rem;
 }
 
-/* Inner ring: keyboard focus stays inside the cell instead of reading as a
-   second selected state or bleeding onto a neighbouring range band. It is an
-   `outline` (not an inset box-shadow) because forced colors computes
-   box-shadow to `none`, which would erase the keyboard indicator entirely. */
-.dp-day:focus-visible {
-  outline: 2px solid var(--dp-accent);
-  outline-offset: -2px;
-}
-
 /* On an accent-filled cell the ring inverts so it stays readable. */
 .dp-day:is([data-selected="true"], [data-range-start="true"], [data-range-end="true"]):focus-visible {
   outline-color: var(--dp-accent-fg);
@@ -275,6 +266,28 @@ html[dir="rtl"] .dp-nav svg {
   border-end-end-radius: var(--dp-day-radius);
 }
 
+/* Projected band: the range the next commit would produce. It reads as one
+   step short of the committed band, so a hovered, keyboard or dragged preview
+   is never mistaken for the selection itself. */
+[data-range-preview] .dp-day:is([data-range-start="true"], [data-range-end="true"]) {
+  background: color-mix(in srgb, var(--dp-accent) 58%, var(--dp-bg));
+}
+
+[data-range-preview] .dp-day[data-in-range="true"] {
+  background: color-mix(in srgb, var(--dp-accent) 11%, var(--dp-bg));
+}
+
+/* Endpoint handles are draggable only while the committed range is complete
+   and its two ends sit on different days. */
+[data-range-drag] .dp-day:is([data-range-start="true"], [data-range-end="true"]) {
+  cursor: grab;
+}
+
+[data-range-drag="active"],
+[data-range-drag="active"] .dp-day {
+  cursor: grabbing;
+}
+
 .dp-day-number {
   display: block;
   font-variant-numeric: tabular-nums;
@@ -320,14 +333,6 @@ date-picker {
   max-inline-size: 100%;
 }
 
-/* Visible focus is normalized to --dp-accent so the component holds together
-   without a consumer stylesheet; the field's own look stays consumer-owned. */
-date-picker > input:not([type="hidden"]):focus-visible {
-  border-color: var(--dp-accent);
-  outline: none;
-  box-shadow: 0 0 0 3px color-mix(in srgb, var(--dp-accent) 20%, transparent);
-}
-
 /* Every authored control is a grid item. */
 date-picker > input:not([type="hidden"]) {
   min-inline-size: 0;
@@ -368,7 +373,7 @@ date-picker > input:not([type="hidden"]):not([type="time"]) {
    field already shows its own ring through :focus-visible). Same radius as
    everywhere else: no bespoke shape. */
 .dp-picker-button:focus-visible {
-  outline: 2px solid var(--dp-accent);
+  outline: var(--dp-focus-width) solid var(--dp-focus);
   outline-offset: -5px;
   border-radius: var(--dp-radius);
 }
@@ -446,8 +451,8 @@ date-picker[range] > .dp-picker-button[data-endpoint="end"] {
 @media (forced-colors: active) {
   /* The author-drawn caret is a gradient and disappears here: hand the
      control back to the browser instead of trying to rebuild it. */
-  .dp-month-select,
-  [dir="rtl"] .dp-month-select {
+  .dp-month-select.dp-skin,
+  [dir="rtl"] .dp-month-select.dp-skin {
     appearance: auto;
     background-image: none;
     padding-inline: 0.45rem;