@lekoala/date-picker 0.1.0 → 0.2.0

package/src/date-picker.css

@@ -9,6 +9,11 @@
   --dp-radius: 0.5rem;
   --dp-day-size: 2.75rem;
   --dp-gap: 0.25rem;
+  --dp-header-control-size: 2.25rem;
+  --dp-header-block-gap: 0.4rem;
+  --dp-nav-gap: calc(var(--dp-gap) * 2.5);
+  --dp-year-inline-size: 5.5rem;
+  --dp-day-radius: calc(var(--dp-radius) * 0.75);
   color: var(--dp-fg);
   font: inherit;
 }
@@ -39,22 +44,46 @@ date-calendar {
 .dp-calendar-header {
   display: grid;
   grid-template-columns: minmax(0, 1fr) auto auto auto;
-  align-items: center;
+  /* 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. */
+  align-items: stretch;
   gap: var(--dp-gap);
-  margin-block-end: 0.4rem;
+  margin-block-end: var(--dp-header-block-gap);
+}
+
+/* Locale year-first order (Intl-derived, direction-independent): the flexible
+   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;
 }
 
 .dp-calendar-header .dp-prev {
-  margin-inline-start: calc(var(--dp-gap) * 2.5);
+  margin-inline-start: var(--dp-nav-gap);
 }
 
 .dp-calendar-header :where(button, select, input) {
-  min-block-size: 2.25rem;
+  min-block-size: var(--dp-header-control-size);
+  box-sizing: border-box;
+  /* 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. */
+  padding-block: 0.15rem;
   border: 1px solid var(--dp-border);
   border-radius: calc(var(--dp-radius) * 0.75);
   background: var(--dp-bg);
   color: var(--dp-fg);
   font: inherit;
+  line-height: 1.2;
+}
+
+/* The select menulist carries UA-internal leading that author padding only
+   adds to (and it ignores line-height), so it gets zero author padding.
+   Equal outer heights come from the header grid's stretch alignment: the row
+   sizes to the tallest control and the others stretch to match. */
+.dp-calendar-header select {
+  padding-block: 0;
 }
 
 .dp-calendar-header select,
@@ -65,16 +94,20 @@ date-calendar {
 
 .dp-month-select {
   inline-size: 100%;
+  /* Long month names in a narrow track (compact consumers, long locales)
+     would paint under the native caret: truncate with an ellipsis instead. */
+  overflow: hidden;
+  text-overflow: ellipsis;
 }
 
 .dp-year-input {
-  inline-size: 5.5rem;
+  inline-size: var(--dp-year-inline-size);
 }
 
 .dp-nav {
   display: grid;
   place-items: center;
-  inline-size: 2.25rem;
+  inline-size: var(--dp-header-control-size);
   padding: 0;
   font-size: 1.35rem;
   line-height: 1;
@@ -88,6 +121,14 @@ date-calendar {
   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-picker-button:disabled {
   cursor: not-allowed;
@@ -104,12 +145,9 @@ date-calendar {
   background: var(--dp-hover);
 }
 
-.dp-calendar-heading {
-  margin: 0 0 0.35rem;
-  font-size: 0.875rem;
-  font-weight: 600;
-  text-align: center;
-}
+/* .dp-calendar-heading is always visually hidden: it names the grid via
+   aria-labelledby and stays the aria-live announcement channel while the
+   month/year selects render the same info visually. */
 
 .dp-grid {
   border-collapse: separate;
@@ -136,7 +174,7 @@ date-calendar {
 .dp-day {
   position: relative;
   border: 1px solid transparent;
-  border-radius: calc(var(--dp-radius) * 0.75);
+  border-radius: var(--dp-day-radius);
   cursor: pointer;
   outline: none;
   vertical-align: middle;
@@ -145,10 +183,21 @@ date-calendar {
 
 .dp-day:focus-visible {
   outline: 2px solid var(--dp-accent);
-  outline-offset: 1px;
+  outline-offset: 2px;
+  /* Separation gap between the cell fill and the ring: invisible on plain
+     days, but keeps the ring readable on accent-filled days (selected, range
+     endpoints) where an accent-on-accent outline would disappear. */
+  box-shadow: 0 0 0 2px var(--dp-bg);
   z-index: 1;
 }
 
+/* Base tint for days outside the displayed month. It stays before the
+   selection states so selected/range endpoints keep their accent-contrast
+   text on the accent fill (equal specificity, source order decides). */
+.dp-day[data-outside-month="true"] {
+  color: var(--dp-muted);
+}
+
 .dp-day[data-selected="true"] {
   background: var(--dp-accent);
   color: var(--dp-accent-fg);
@@ -158,10 +207,6 @@ date-calendar {
   border-color: var(--dp-accent);
 }
 
-.dp-day[data-outside-month="true"] {
-  color: var(--dp-muted);
-}
-
 .dp-day[data-disabled="true"] {
   cursor: not-allowed;
   opacity: 0.42;
@@ -204,6 +249,17 @@ date-calendar {
   font-variant-numeric: tabular-nums;
 }
 
+/* A focused disabled day stays discoverable by keyboard: restore full opacity
+   so the focus outline renders at full strength, and mark the number with the
+   muted tone (same language as outside-month days) instead of the wash-out. */
+.dp-day[data-disabled="true"]:focus-visible {
+  opacity: 1;
+}
+
+.dp-day[data-disabled="true"]:focus-visible .dp-day-number {
+  color: var(--dp-muted);
+}
+
 .dp-day-extra {
   position: absolute;
   inset-inline: 2px;
@@ -238,16 +294,56 @@ date-picker > input:not([type="hidden"]) {
   min-inline-size: 0;
 }
 
+/* Optional native time companions share the date row; authored inputs stay
+   consumer-styled, the picker only reserves their grid cells. Time tracks are
+   flexible (never `auto`) so a wide UA time control cannot squeeze the date. */
+date-picker:has(> [data-time-start], > [data-time-end]) {
+  grid-template-columns: minmax(0, 1fr) auto minmax(0, 1fr);
+}
+
+date-picker:has(> [data-time-start]):has(> [data-time-end]) {
+  grid-template-columns: minmax(0, 1fr) auto minmax(0, 1fr) minmax(0, 1fr);
+}
+
+date-picker > input[data-time-start] {
+  grid-column: 3;
+  grid-row: 1;
+  min-inline-size: 0;
+  inline-size: 100%;
+  margin-inline-start: var(--dp-gap);
+}
+
+date-picker > input[data-time-end] {
+  grid-column: 4;
+  grid-row: 1;
+  min-inline-size: 0;
+  inline-size: 100%;
+}
+
+/* From/to read as one joined control: square the inner corners, but only
+   when both companions are present so a lone time keeps its own radius. */
+date-picker:has(> [data-time-start]):has(> [data-time-end]) > input[data-time-start] {
+  border-start-end-radius: 0;
+  border-end-end-radius: 0;
+}
+
+date-picker:has(> [data-time-start]):has(> [data-time-end]) > input[data-time-end] {
+  border-start-start-radius: 0;
+  border-end-start-radius: 0;
+}
+
 date-picker[range] > input:not([type="hidden"]) {
   grid-column: 1;
 }
 
 date-picker[range] > input[data-range-start] {
   grid-row: 1;
+  border-end-start-radius: 0;
 }
 
 date-picker[range] > input[data-range-end] {
   grid-row: 2;
+  border-start-start-radius: 0;
 }
 
 .dp-picker-button {

package/src/date-picker.js

@@ -5,11 +5,12 @@ import { DateFieldController } from "./date-field.js";
 import { DateRangeController, normalizeRange } from "./date-range.js";
 import { createDateAdapter, formatLongDate, resolveLocale } from "./intl.js";
 import { getDefaultMessages } from "./messages.js";
+import { compareTimes, isTime } from "./time.js";
 
 let uid = 0;
 
 export class DatePickerElement extends HTMLElement {
-  static observedAttributes = ["value", "locale", "min", "max", "open-on-focus"];
+  static observedAttributes = ["value", "locale", "min", "max", "open-on-focus", "month-format"];
 
   constructor() {
     super();
@@ -25,6 +26,10 @@ export class DatePickerElement extends HTMLElement {
     /** @type {DateRangeController | null} */
     this._range = null;
     this._orderTags = new Set();
+    /** Native time companions, [start, end]. @type {[HTMLInputElement | null, HTMLInputElement | null]} */
+    this._timeFields = [null, null];
+    /** Time inputs currently holding our order error. @type {Set<HTMLInputElement>} */
+    this._timeOrderOwned = new Set();
     /** @type {"" | "start" | "end"} */
     this._lastFocusEndpoint = "";
     this._rangeCommitId = 0;
@@ -67,13 +72,16 @@ export class DatePickerElement extends HTMLElement {
   }
 
   _connectSingle() {
-    const input = this.querySelector(":scope > input:not([type=hidden])");
+    const input = this.querySelector(
+      ":scope > input:not([type=hidden]):not([type=time]):not([data-time-start]):not([data-time-end])",
+    );
     if (!(input instanceof HTMLInputElement)) {
       console.warn("<date-picker> expects a direct child text input");
       return;
     }
     this._connected = true;
     this._input = input;
+    this._discoverTimeFields();
     this._field = new DateFieldController(input, { messages: this._messages, locale: this.locale });
     this._field.onAttributesChanged = () => this._syncInputState();
     this._field.confirm = (date) => this._confirmDate(date);
@@ -102,7 +110,37 @@ export class DatePickerElement extends HTMLElement {
     }
   }
 
+  /**
+   * Find optional native time companions. They stay fully native (no hidden
+   * input, no field controller); the picker only coordinates from/to order.
+   * A bad composition never breaks the date picker: warn and leave times alone.
+   */
+  _discoverTimeFields() {
+    this._timeFields = [null, null];
+    /** @type {["data-time-start", "data-time-end"]} */
+    const markers = ["data-time-start", "data-time-end"];
+    for (const [index, marker] of markers.entries()) {
+      const matches = this.querySelectorAll(`:scope > input[${marker}]`);
+      if (matches.length > 1) {
+        console.warn(`<date-picker> expects at most one direct child input[${marker}]; ignoring extras`);
+      }
+      const candidate = matches[0];
+      if (candidate == null) continue;
+      if (!(candidate instanceof HTMLInputElement) || candidate.type !== "time") {
+        console.warn(`<date-picker> input[${marker}] must be an <input type="time">; ignoring it`);
+        continue;
+      }
+      this._timeFields[index] = candidate;
+    }
+    if (this.querySelector(":scope > input[type=time]:not([data-time-start]):not([data-time-end])")) {
+      console.warn("<date-picker> time inputs need [data-time-start] or [data-time-end]; ignoring it");
+    }
+  }
+
   _connectRange() {
+    if (this.querySelector(":scope > input[data-time-start], :scope > input[data-time-end]")) {
+      console.warn("<date-picker range> time companions are not supported yet; leaving them native");
+    }
     const startInput = this.querySelector(":scope > input[data-range-start]");
     const endInput = this.querySelector(":scope > input[data-range-end]");
     if (!(startInput instanceof HTMLInputElement) || !(endInput instanceof HTMLInputElement)) {
@@ -156,6 +194,8 @@ export class DatePickerElement extends HTMLElement {
     this.hide(false);
     this._controller?.abort();
     this._controller = null;
+    this._clearTimeOrderValidity();
+    this._timeFields = [null, null];
     if (this._rangeMode()) {
       for (const field of this._fields || []) this._teardownField(field);
       this._fields = null;
@@ -248,6 +288,16 @@ export class DatePickerElement extends HTMLElement {
     else this.removeAttribute("locale");
   }
 
+  /** @public Visible month-name style forwarded to the popup calendar (`long` | `short`); anything else falls back to `long`. */
+  get monthFormat() {
+    return this.getAttribute("month-format") === "short" ? "short" : "long";
+  }
+
+  set monthFormat(value) {
+    if (value === "short") this.setAttribute("month-format", "short");
+    else this.removeAttribute("month-format");
+  }
+
   /** @public */
   get min() {
     const value = this.getAttribute("min") || "";
@@ -479,6 +529,12 @@ export class DatePickerElement extends HTMLElement {
       },
       { signal },
     );
+    for (const [index, timeInput] of this._timeFields.entries()) {
+      if (!timeInput) continue;
+      const endpoint = index === 1 ? "end" : "start";
+      timeInput.addEventListener("input", () => this._revalidateTimeOrder(endpoint), { signal });
+      timeInput.addEventListener("change", () => this._revalidateTimeOrder(endpoint), { signal });
+    }
     button.addEventListener(
       "click",
       (event) => {
@@ -721,6 +777,7 @@ export class DatePickerElement extends HTMLElement {
     calendar.locale = this.locale;
     calendar.min = this.min;
     calendar.max = this.max;
+    calendar.monthFormat = this.monthFormat;
     calendar.messages = this._messages;
     calendar.source = this._source;
     calendar.dateState = this._dateState;
@@ -959,6 +1016,47 @@ export class DatePickerElement extends HTMLElement {
     }
   }
 
+  /**
+   * Single-mode from/to order on the shared date: `start <= end`.
+   * The order error is attributed to the bound that was just modified; the
+   * other bound only loses a stale order error, never its native validity.
+   * Missing, empty or disabled times fall back to no order constraint: times
+   * are never implicitly required. Equality stays valid (duration rules are
+   * application-owned).
+   * @param {"start" | "end"} which
+   */
+  _revalidateTimeOrder(which) {
+    const [startInput, endInput] = this._timeFields;
+    /** @type {["start", "end"]} */
+    const bounds = ["start", "end"];
+    const inputs = [startInput, endInput];
+    const startValue = startInput && !startInput.disabled ? startInput.value.trim() : "";
+    const endValue = endInput && !endInput.disabled ? endInput.value.trim() : "";
+    const inverted =
+      Boolean(startInput && endInput && startValue && endValue) &&
+      isTime(startValue) &&
+      isTime(endValue) &&
+      compareTimes(endValue, startValue) < 0;
+    for (const [index, bound] of bounds.entries()) {
+      const input = inputs[index];
+      if (!input) continue;
+      const message = bound === "end" ? this._messages.rangeOrderEnd : this._messages.rangeOrderStart;
+      const shouldHaveOrder = inverted && bound === which;
+      if (shouldHaveOrder) {
+        input.setCustomValidity(message);
+        this._timeOrderOwned.add(input);
+      } else if (this._timeOrderOwned.has(input)) {
+        input.setCustomValidity("");
+        this._timeOrderOwned.delete(input);
+      }
+    }
+  }
+
+  _clearTimeOrderValidity() {
+    for (const input of this._timeOrderOwned) input.setCustomValidity("");
+    this._timeOrderOwned.clear();
+  }
+
   _restoreDefault() {
     const field = this._field;
     if (!field) return;
@@ -1051,10 +1149,15 @@ export class DatePickerElement extends HTMLElement {
     if (!input) return true;
     if (!input.value.trim()) {
       input.setCustomValidity("");
-      return input.checkValidity();
+    } else {
+      await this._commitText(false, { force: true });
     }
-    await this._commitText(false, { force: true });
-    return input.checkValidity();
+    // Same start-then-end order as the range path, so a from/to inversion
+    // ends reported on "end". A programmatic time change resyncs here too.
+    this._revalidateTimeOrder("start");
+    this._revalidateTimeOrder("end");
+    const timesValid = this._timeFields.every((timeInput) => timeInput?.checkValidity() ?? true);
+    return input.checkValidity() && timesValid;
   }
 
   /** @public @param {{moveFocus?:boolean}} [options] */

package/src/date.js

@@ -141,11 +141,21 @@ export function dayOfWeek(value) {
   return toUTCDate(parsed).getUTCDay();
 }
 
+/**
+ * Canonical first weekday. 7 is the ISO-style Sunday alias of 0; values 1..6
+ * keep their current meaning. Any other value throws.
+ * @param {number} firstDay
+ */
+export function normalizeFirstDay(firstDay) {
+  if (firstDay === 7) return 0;
+  if (!Number.isInteger(firstDay) || firstDay < 0 || firstDay > 6)
+    throw new RangeError("firstDay must be 0..6 (Sunday=0, 7 accepted as Sunday alias)");
+  return firstDay;
+}
+
 /** @param {string} value @param {number} firstDay */
 export function startOfWeek(value, firstDay = 1) {
-  if (!Number.isInteger(firstDay) || firstDay < 0 || firstDay > 6)
-    throw new RangeError("firstDay must be 0..6");
-  const offset = (dayOfWeek(value) - firstDay + 7) % 7;
+  const offset = (dayOfWeek(value) - normalizeFirstDay(firstDay) + 7) % 7;
   return addDays(value, -offset);
 }
 

package/src/index.js

@@ -8,6 +8,7 @@ export {
   formatLongDate,
   formatMonthYear,
   monthNames,
+  monthYearOrder,
   resolveLocale,
   weekdayNames,
 } from "./intl.js";

package/src/intl.js

@@ -1,4 +1,4 @@
-import { isDate, parseDate, toIntlDate, toISODate } from "./date.js";
+import { isDate, normalizeFirstDay, parseDate, toIntlDate, toISODate } from "./date.js";
 
 const BIDI = /[\u200e\u200f\u061c\u202a-\u202e\u2066-\u2069]/g;
 
@@ -51,6 +51,41 @@ export function formatMonthYear(value, locale = "") {
   }).format(toIntlDate(`${value.slice(0, 7)}-15`));
 }
 
+/**
+ * Locale order of the visible month/year controls, derived from `Intl` so no
+ * `showMonthAfterYear`-style option is needed. Year-like parts cover the
+ * `relatedYear` / `yearName` variants some calendars expose; anything
+ * unrecognized falls back to month-then-year. This is independent of `dir`:
+ * the locale decides the linguistic order, direction only mirrors the layout.
+ * @param {string} [locale] @returns {["month", "year"] | ["year", "month"]}
+ */
+export function monthYearOrder(locale = "") {
+  const resolved = resolveLocale(locale);
+  try {
+    const parts = new Intl.DateTimeFormat(resolved, {
+      calendar: "gregory",
+      year: "numeric",
+      month: "long",
+      timeZone: "UTC",
+    }).formatToParts(toIntlDate("2026-09-15"));
+    let monthIndex = -1;
+    let yearIndex = -1;
+    parts.forEach((part, index) => {
+      const type = /** @type {string} */ (part.type);
+      if (type === "month") {
+        if (monthIndex < 0) monthIndex = index;
+      } else if (type === "year" || type === "relatedYear" || type === "yearName") {
+        if (yearIndex < 0) yearIndex = index;
+      }
+    });
+    if (monthIndex >= 0 && yearIndex >= 0)
+      return yearIndex < monthIndex ? ["year", "month"] : ["month", "year"];
+  } catch {
+    // Fall through to the default below.
+  }
+  return ["month", "year"];
+}
+
 /** @param {string} [locale] @param {"long"|"short"} [style] */
 export function monthNames(locale = "", style = "long") {
   const resolved = resolveLocale(locale);
@@ -72,11 +107,12 @@ export function weekdayNames(locale = "", firstDay = 1, style = "short") {
     weekday: style,
     timeZone: "UTC",
   });
+  const normalized = normalizeFirstDay(firstDay);
   // 2026-01-04 is a Sunday.
   const sunday = toIntlDate("2026-01-04");
   return Array.from({ length: 7 }, (_, index) => {
     const date = new Date(sunday);
-    date.setUTCDate(sunday.getUTCDate() + ((firstDay + index) % 7));
+    date.setUTCDate(sunday.getUTCDate() + ((normalized + index) % 7));
     return formatter.format(date);
   });
 }

package/src/time.js

@@ -0,0 +1,39 @@
+const TIME_RE = /^(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?$/;
+
+/**
+ * Parse one canonical HTML time value (`HH:MM`, `HH:MM:SS`, `HH:MM:SS.fff`).
+ * @param {string} value
+ * @returns {{hour:number, minute:number, second:number, millisecond:number} | null}
+ */
+function parseTimeParts(value) {
+  const match = TIME_RE.exec(String(value || ""));
+  if (!match) return null;
+  const hour = Number(match[1]);
+  const minute = Number(match[2]);
+  const second = match[3] === undefined ? 0 : Number(match[3]);
+  const millisecond = match[4] === undefined ? 0 : Number(match[4].padEnd(3, "0"));
+  if (hour > 23 || minute > 59 || second > 59 || millisecond > 999) return null;
+  return { hour, minute, second, millisecond };
+}
+
+/** Civil time check for canonical `input[type=time]` values. @param {string} value */
+export function isTime(value) {
+  return parseTimeParts(value) !== null;
+}
+
+/** @param {{hour:number, minute:number, second:number, millisecond:number}} parts */
+function toMillis(parts) {
+  return ((parts.hour * 60 + parts.minute) * 60 + parts.second) * 1000 + parts.millisecond;
+}
+
+/**
+ * Compare two canonical time values. `09:30` equals `09:30:00`.
+ * @param {string} a @param {string} b
+ */
+export function compareTimes(a, b) {
+  const left = parseTimeParts(a);
+  const right = parseTimeParts(b);
+  if (!left || !right) throw new TypeError("compareTimes() expects HH:MM values");
+  const diff = toMillis(left) - toMillis(right);
+  return diff === 0 ? 0 : diff < 0 ? -1 : 1;
+}