@lekoala/date-picker 0.1.1 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 Small, native-first date picker and inline calendar primitives.
 
-> v0.1: the interaction contract, event names, public styling tokens and the component API are frozen — see [docs/DECISIONS.md](docs/DECISIONS.md). Internal DOM and class names are `.dp-*` implementation details and stay private.
+> v0.2: the interaction contract, event names, public styling tokens and the component API are frozen — see [docs/DECISIONS.md](docs/DECISIONS.md). Internal DOM and class names are `.dp-*` implementation details and stay private.
 
 This project fills the gap between a normal editable date field and a full scheduling calendar. A plain date input remains the right answer for simple CMS/editing forms. This component becomes useful when a date has context: availability, disabled days, annotations, remote state, start/end relationships, or a mini calendar that navigates another view.
 
@@ -77,6 +77,24 @@ const cleanup = linkDateRange(startPicker, endPicker);
 
 The relationship applies `end >= start` and `start <= end` as effective bounds. Neither picker knows about its sibling.
 
+## Date + time
+
+A date pairs with one or two native time companions. The picker owns the civil date; the time inputs own their civil time values:
+
+```html
+<date-picker>
+  <input name="appointment[date]">
+  <input type="time" data-time-start name="appointment[time]">
+</date-picker>
+```
+
+```text
+appointment[date] = 2026-09-10
+appointment[time] = 09:30
+```
+
+The application/server combines these civil values and applies the relevant timezone when a datetime/instant is needed. The picker never constructs a combined datetime value.
+
 ## Availability and per-day metadata
 
 The calendar accepts a source function or `{ load() }` object with the same abortable shape used elsewhere in LeKoala components:
@@ -144,7 +162,9 @@ The calendar follows the WAI-ARIA date-picker/grid interaction model:
 
 The picker popup uses native Popover for the top layer and `@lekoala/floating` for geometry. It has `role="dialog"`, but it is intentionally **not** marked `aria-modal` because the current implementation does not inert the rest of the document.
 
-When the popup opens on the field's focus, grid navigation is reachable via `ArrowDown` (or the trigger button) so the focus-restore/Escape flow stays predictable.
+The calendar trigger is a real button painted inside the field's own box (like the native `input[type=time]` indicator): the field reserves its place with `padding-inline-end`, keeps its own border and background, and its focus ring wraps the trigger too. The trigger draws no chrome of its own and shows a small inner ring when focused.
+
+When the popup opens on the field's focus, grid navigation is reachable via `ArrowDown` (or the trigger button) so the focus-restore/Escape flow stays predictable. Closing returns focus to the control that opened the popover: the field when it opened by focus, the trigger when it was activated. In range mode focus follows the active bound instead, because a first pick moves the workflow to the other bound.
 
 See [docs/ACCESSIBILITY.md](docs/ACCESSIBILITY.md).
 
@@ -161,9 +181,9 @@ Tooling is aligned with the current LeKoala component repos:
 
 - Bun 1.4.2
 - TypeScript 7.0.2 (`checkJs` + declaration emit)
-- Biome 2.5.11
-- Playwright 1.62.1
-- `@lekoala/floating ^0.1.1`
+- Biome 2.5.13
+- Playwright 1.63.0
+- `@lekoala/floating ^0.2.0`
 
 Useful commands:
 
@@ -194,7 +214,7 @@ The default ESM exports point at `src/`, matching the native-first development s
 
 ## Scope
 
-Included in v0.1:
+Included in v0.2:
 
 - inline single-date selection;
 - mini-calendar/navigation-only use;
@@ -205,15 +225,20 @@ Included in v0.1:
 - presentation-only range band (`highlightedRange`);
 - shared-calendar two-field range picker (`<date-picker range>`);
 - linked start/end pickers (`linkDateRange`);
+- native time companions (one or two `input[type=time]` beside the date);
+- `Intl` month/year control order + `month-format="short"`;
+- RTL through the inherited `dir` (no `isRTL` option);
+- readable keyboard focus on disabled/selected days;
+- compact-consumer CSS tokens (`--dp-header-control-size`, `--dp-day-radius`, …);
 - async per-day state with cancellation;
 - custom day decorations that cannot replace the accessible cell;
 - fixed six-row presentation as an opt-in;
 - ISO week numbers;
 - keyboard and focus contracts.
 
-Deliberately out of scope for v0.1:
+Deliberately out of scope for v0.2:
 
-- time or datetime picking;
+- custom time-picker UI and combined datetime values (only native `input[type=time]` companions are supported);
 - timezones;
 - in-place single-calendar range *selection interaction* (use the two-field picker);
 - multi-date selection;

package/custom-elements.json

@@ -37,6 +37,9 @@
             },
             {
               "name": "selection"
+            },
+            {
+              "name": "month-format"
             }
           ],
           "members": [
@@ -72,6 +75,10 @@
               "kind": "getter",
               "name": "selection"
             },
+            {
+              "kind": "getter",
+              "name": "monthFormat"
+            },
             {
               "kind": "getter",
               "name": "highlightedRange"
@@ -190,6 +197,24 @@
             },
             {
               "name": "--dp-gap"
+            },
+            {
+              "name": "--dp-header-control-size"
+            },
+            {
+              "name": "--dp-header-block-gap"
+            },
+            {
+              "name": "--dp-row-gap"
+            },
+            {
+              "name": "--dp-picker-button-size"
+            },
+            {
+              "name": "--dp-year-inline-size"
+            },
+            {
+              "name": "--dp-day-radius"
             }
           ]
         }
@@ -228,6 +253,9 @@
             },
             {
               "name": "open-on-focus"
+            },
+            {
+              "name": "month-format"
             }
           ],
           "members": [
@@ -251,6 +279,10 @@
               "kind": "getter",
               "name": "locale"
             },
+            {
+              "kind": "getter",
+              "name": "monthFormat"
+            },
             {
               "kind": "getter",
               "name": "min"
@@ -287,6 +319,10 @@
               "kind": "getter",
               "name": "isDateDisabled"
             },
+            {
+              "kind": "getter",
+              "name": "coordinateSpace"
+            },
             {
               "kind": "method",
               "name": "validate"
@@ -347,6 +383,24 @@
             },
             {
               "name": "--dp-gap"
+            },
+            {
+              "name": "--dp-header-control-size"
+            },
+            {
+              "name": "--dp-header-block-gap"
+            },
+            {
+              "name": "--dp-row-gap"
+            },
+            {
+              "name": "--dp-picker-button-size"
+            },
+            {
+              "name": "--dp-year-inline-size"
+            },
+            {
+              "name": "--dp-day-radius"
             }
           ]
         }

package/dist/date-picker.css

@@ -1,14 +1,20 @@
 :where(date-calendar, date-picker) {
-  --dp-bg: Canvas;
-  --dp-fg: CanvasText;
-  --dp-muted: color-mix(in srgb, CanvasText 58%, Canvas);
-  --dp-border: color-mix(in srgb, CanvasText 22%, Canvas);
-  --dp-hover: color-mix(in srgb, CanvasText 7%, Canvas);
-  --dp-accent: Highlight;
-  --dp-accent-fg: HighlightText;
+  --dp-bg: #ffffff;
+  --dp-fg: #1f2328;
+  --dp-muted: color-mix(in srgb, var(--dp-fg) 58%, var(--dp-bg));
+  --dp-border: color-mix(in srgb, var(--dp-fg) 16%, var(--dp-bg));
+  --dp-hover: color-mix(in srgb, var(--dp-fg) 5%, var(--dp-bg));
+  --dp-accent: #2563eb;
+  --dp-accent-fg: #fff;
   --dp-radius: 0.5rem;
   --dp-day-size: 2.75rem;
-  --dp-gap: 0.25rem;
+  --dp-gap: 0.375rem;
+  --dp-header-control-size: 2.25rem;
+  --dp-header-block-gap: 0.75rem;
+  --dp-row-gap: 0.375rem;
+  --dp-picker-button-size: 2.5rem;
+  --dp-year-inline-size: 5.5rem;
+  --dp-day-radius: calc(var(--dp-radius) * 0.75);
   color: var(--dp-fg);
   font: inherit;
 }
@@ -39,42 +45,85 @@ 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;
+  /* Uniform horizontal rhythm: the four header controls are self-evident from
+     their kind and position, so no group gets an extra semantic gap. The air
+     belongs to the vertical zones (header -> weekdays -> dates). */
   gap: var(--dp-gap);
-  margin-block-end: 0.4rem;
+  margin-block-end: var(--dp-header-block-gap);
 }
 
-.dp-calendar-header .dp-prev {
-  margin-inline-start: calc(var(--dp-gap) * 2.5);
+/* 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 :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;
 }
 
-.dp-calendar-header select,
 .dp-calendar-header input {
   min-inline-size: 0;
   padding-inline: 0.45rem;
 }
 
+/* Author-drawn caret so the month select matches the nav controls without a
+   hardcoded SVG color (currentColor keeps theming). 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-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;
+  appearance: none;
+  padding-inline: 0.45rem 2rem;
+  background-image:
+    linear-gradient(45deg, transparent 50%, currentColor 50%),
+    linear-gradient(135deg, currentColor 50%, transparent 50%);
+  background-position:
+    calc(100% - 0.9rem) 50%,
+    calc(100% - 0.65rem) 50%;
+  background-size: 0.3rem 0.3rem;
+  background-repeat: no-repeat;
+}
+
+/* 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 {
+  background-position:
+    0.9rem 50%,
+    0.65rem 50%;
 }
 
 .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 +137,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;
@@ -98,6 +155,14 @@ date-calendar {
   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);
+}
+
 .dp-day:hover:not([data-disabled="true"]):not([data-selected="true"]):not([data-range-start="true"]):not(
   [data-range-end="true"]
 ) {
@@ -110,8 +175,8 @@ date-calendar {
 
 .dp-grid {
   border-collapse: separate;
-  /* --dp-gap scopes to the header grid; day-cell spacing stays fixed. */
-  border-spacing: 0 0.25rem;
+  /* --dp-gap scopes to the header grid; vertical week rhythm is --dp-row-gap. */
+  border-spacing: 0 var(--dp-row-gap);
   table-layout: fixed;
 }
 
@@ -124,26 +189,41 @@ date-calendar {
 }
 
 .dp-grid thead th {
-  block-size: 1.6rem;
+  block-size: 1.5rem;
   color: var(--dp-muted);
   font-size: 0.72rem;
-  font-weight: 600;
+  font-weight: 500;
 }
 
 .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;
   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: 1px;
-  z-index: 1;
+  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);
+}
+
+/* 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"] {
@@ -151,14 +231,13 @@ date-calendar {
   color: var(--dp-accent-fg);
 }
 
-.dp-day[data-today="true"]:not([data-selected="true"]) {
+/* Today never competes with a stronger state: a selected day or a range
+   endpoint keeps its own treatment, in normal rendering and in
+   forced-colors alike. */
+.dp-day[data-today="true"]:not([data-selected="true"], [data-range-start="true"], [data-range-end="true"]) {
   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;
@@ -187,13 +266,13 @@ date-calendar {
 }
 
 .dp-day[data-in-range="true"]:first-of-type {
-  border-start-start-radius: var(--dp-radius);
-  border-end-start-radius: var(--dp-radius);
+  border-start-start-radius: var(--dp-day-radius);
+  border-end-start-radius: var(--dp-day-radius);
 }
 
 .dp-day[data-in-range="true"]:last-of-type {
-  border-start-end-radius: var(--dp-radius);
-  border-end-end-radius: var(--dp-radius);
+  border-start-end-radius: var(--dp-day-radius);
+  border-end-end-radius: var(--dp-day-radius);
 }
 
 .dp-day-number {
@@ -201,6 +280,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;
@@ -225,18 +315,95 @@ date-calendar {
 date-picker {
   position: relative;
   display: inline-grid;
-  grid-template-columns: minmax(0, 1fr) auto;
+  grid-template-columns: minmax(0, 1fr);
   align-items: stretch;
   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"]) {
-  grid-column: 1;
   min-inline-size: 0;
 }
 
-date-picker[range] > input:not([type="hidden"]) {
+/* Date fields reserve room for the trigger, which is painted inside the
+   field's own box: the field is the real outer box, so its focus ring wraps
+   the affordance too. `grid-row` must stay explicit, otherwise the trigger
+   (placed with a definite row) claims the row and pushes the field down. */
+date-picker > input:not([type="hidden"]):not([type="time"]) {
   grid-column: 1;
+  grid-row: 1;
+  box-sizing: border-box;
+  inline-size: 100%;
+  padding-inline-end: calc(var(--dp-picker-button-size) + 0.5rem);
+}
+
+/* The trigger is a real button overlaid on the field's inline-end, like the
+   native `input[type=time]` indicator: no chrome of its own, transparent, so
+   the authored field background and border stay visible underneath. */
+.dp-picker-button {
+  display: grid;
+  place-items: center;
+  grid-column: 1;
+  grid-row: 1;
+  justify-self: end;
+  align-self: stretch;
+  inline-size: var(--dp-picker-button-size);
+  min-inline-size: 0;
+  border: 0;
+  background: transparent;
+  color: var(--dp-fg);
+  font: inherit;
+  cursor: pointer;
+}
+
+/* Like the native time indicator: the ring wraps the icon, not the field (the
+   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-offset: -5px;
+  border-radius: var(--dp-radius);
+}
+
+/* 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.
+   Each companion keeps its own box and its own gap: nothing is joined, so
+   focus rings never merge and no neighbour swallows another's focus. */
+date-picker:has(> [data-time-start], > [data-time-end]) {
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+  column-gap: var(--dp-gap);
+}
+
+date-picker:has(> [data-time-start]):has(> [data-time-end]) {
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr) minmax(0, 1fr);
+}
+
+date-picker > input[data-time-start] {
+  grid-column: 2;
+  grid-row: 1;
+  min-inline-size: 0;
+}
+
+date-picker > input[data-time-end] {
+  grid-column: 3;
+  grid-row: 1;
+  min-inline-size: 0;
+}
+
+/* Range: two stacked fields, each owning its trigger, sharing one popup and
+   one calendar. No trigger spans both bounds, so each bound keeps a local
+   affordance and a local focus target. */
+date-picker[range] {
+  row-gap: var(--dp-gap);
 }
 
 date-picker[range] > input[data-range-start] {
@@ -247,35 +414,26 @@ date-picker[range] > input[data-range-end] {
   grid-row: 2;
 }
 
-.dp-picker-button {
-  grid-column: 2;
-  min-inline-size: 2.5rem;
-  border: 1px solid var(--dp-border);
-  border-inline-start: 0;
-  border-start-start-radius: 0;
-  border-end-start-radius: 0;
-  border-start-end-radius: var(--dp-radius);
-  border-end-end-radius: var(--dp-radius);
-  background: var(--dp-bg);
-  color: var(--dp-fg);
-  font: inherit;
-  cursor: pointer;
+date-picker[range] > .dp-picker-button[data-endpoint="start"] {
+  grid-row: 1;
 }
 
-date-picker[range] > .dp-picker-button {
-  grid-row: 1 / span 2;
+date-picker[range] > .dp-picker-button[data-endpoint="end"] {
+  grid-row: 2;
 }
 
 .dp-picker-panel[popover] {
+  /* Safe baseline. show() switches to absolute only when the consumer
+   * explicitly selects document coordinate space. */
   position: fixed;
   inset: auto;
   margin: 0;
-  padding: 0.65rem;
+  padding: 0.875rem 1rem;
   border: 1px solid var(--dp-border);
   border-radius: var(--dp-radius);
   background: var(--dp-bg);
   color: var(--dp-fg);
-  box-shadow: 0 0.5rem 1.5rem rgb(0 0 0 / 0.16);
+  box-shadow: 0 0.5rem 1.5rem rgb(15 23 42 / 0.12);
   max-block-size: var(--available-height, 90svh);
   max-inline-size: calc(100vi - 1rem);
   overflow: auto;
@@ -286,19 +444,22 @@ date-picker[range] > .dp-picker-button {
 }
 
 @media (forced-colors: active) {
-  .dp-day[data-selected="true"] {
-    border: 2px solid Highlight;
-    background-color: Canvas;
-    color: CanvasText;
-    font-weight: 700;
+  /* 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 {
+    appearance: auto;
+    background-image: none;
+    padding-inline: 0.45rem;
   }
 
-  .dp-day[data-range-start="true"],
-  .dp-day[data-range-end="true"] {
+  /* Fills vanish here, so selection and endpoints fall back to a 2px
+     Highlight border. The in-range underline is the only band marker left:
+     the range fill is lost and the browser does not know the semantics. */
+  .dp-day:is([data-selected="true"], [data-range-start="true"], [data-range-end="true"]) {
     border: 2px solid Highlight;
     background-color: Canvas;
     color: CanvasText;
-    font-weight: 700;
   }
 
   .dp-day[data-in-range="true"] {
@@ -314,15 +475,8 @@ date-picker[range] > .dp-picker-button {
     background-color: Highlight;
   }
 
-  .dp-day[data-selected="true"]::before {
-    content: "";
-    position: absolute;
-    inset: 3px;
-    border: 1px solid CanvasText;
-    border-radius: calc(var(--dp-radius) * 0.5);
-    pointer-events: none;
-  }
-
+  /* Pin the today marker: the deterministic accent is a non-system color
+     and would otherwise remap unpredictably here. */
   .dp-day[data-today="true"] {
     border-color: Highlight;
   }
@@ -331,11 +485,4 @@ date-picker[range] > .dp-picker-button {
     color: CanvasText;
     forced-color-adjust: none;
   }
-
-  .dp-day[data-disabled="true"],
-  .dp-calendar-header :where(button, select, input):disabled,
-  .dp-picker-button:disabled {
-    opacity: 1;
-    color: GrayText;
-  }
 }