@lekoala/date-picker 0.1.0 → 0.2.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.
 
@@ -10,12 +10,14 @@ This project fills the gap between a normal editable date field and a full sched
 
 ### `<date-calendar>`
 
-An inline calendar with real month/year navigation, keyboard support and three separate pieces of state:
+An inline calendar with real month/year navigation, keyboard support and three distinct pieces of state:
 
 - `display` — the month being rendered (`YYYY-MM`);
 - `focusedDate` — the roving keyboard target (`YYYY-MM-DD`);
 - `value` — the selected date (`YYYY-MM-DD`, optional).
 
+`display` and `focusedDate` are coupled during navigation/display: changing the displayed month re-clamps the focused day into that month, because the roving-tabbable grid cell must stay visible. `value` and activation stay independent of both.
+
 User activation is exposed separately as `dateactivate`. This is what makes the same calendar useful as a selector **and** as a mini navigator.
 
 ```html
@@ -75,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:
@@ -192,7 +212,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;
@@ -203,15 +223,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,21 @@
             },
             {
               "name": "--dp-gap"
+            },
+            {
+              "name": "--dp-header-control-size"
+            },
+            {
+              "name": "--dp-header-block-gap"
+            },
+            {
+              "name": "--dp-nav-gap"
+            },
+            {
+              "name": "--dp-year-inline-size"
+            },
+            {
+              "name": "--dp-day-radius"
             }
           ]
         }
@@ -228,6 +250,9 @@
             },
             {
               "name": "open-on-focus"
+            },
+            {
+              "name": "month-format"
             }
           ],
           "members": [
@@ -251,6 +276,10 @@
               "kind": "getter",
               "name": "locale"
             },
+            {
+              "kind": "getter",
+              "name": "monthFormat"
+            },
             {
               "kind": "getter",
               "name": "min"
@@ -347,6 +376,21 @@
             },
             {
               "name": "--dp-gap"
+            },
+            {
+              "name": "--dp-header-control-size"
+            },
+            {
+              "name": "--dp-header-block-gap"
+            },
+            {
+              "name": "--dp-nav-gap"
+            },
+            {
+              "name": "--dp-year-inline-size"
+            },
+            {
+              "name": "--dp-day-radius"
             }
           ]
         }

package/dist/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 {