<bmx-date-picker>

<div class="row">
  <bmx-date-picker label="Start date" description="Type it, or press Down to open the calendar. The field order follows the page's locale."></bmx-date-picker>
</div>
<div class="row">
  <bmx-date-picker id="ex-date-stay" label="Stay" range="true" description="Two clicks. Clicking a date before the start begins again rather than inverting the range."></bmx-date-picker>
</div>
<div class="row">
  <bmx-date-picker id="ex-date-appt" label="Appointment" with-time="true" min="2026-01-01" description="Weekends are unavailable, and the time comes from a native field."></bmx-date-picker>
</div>
<script type="module">
  await customElements.whenDefined('bmx-date-picker');

  // `presets` is an array and `disabled-days-of-week` is one too — both are
  // properties, because neither fits in an attribute.
  document.getElementById('ex-date-stay').presets = [
    { label: 'This weekend', value: ['2026-09-12', '2026-09-13'] },
    { label: 'Next week', value: ['2026-09-14', '2026-09-20'] },
  ];

  document.getElementById('ex-date-appt').disabledDaysOfWeek = [0, 6];
</script>

WHY IT DOES NOT COMPOSE bmx-input

It should. The field is bmx-input's field, the masking is core/mask.ts, and putting one component inside the other is the story the rest of this library tells. It cannot, and the reason is the same one that shaped bmx-radio-group and bmx-select: the input has to carry aria-controls and aria-activedescendant pointing at the calendar, and an IDREF cannot cross a shadow boundary. Nested inside bmx-input's shadow root, the input would be referring to ids it cannot see - a combobox announced as controlling nothing, which looks entirely correct on screen.

So the field is its own, and what is shared is shared as code: the chrome from field-chrome.tsx, the caret arithmetic from core/mask.ts, the surface from overlay-surface.ts. The one thing knowingly not carried across from bmx-input is its undo-stack preservation, which is twenty lines of execCommand for a ten-character field; when a second component needs it, it should be extracted rather than copied.

DATES ARE NOT Dates

Not one Date object crosses into this component. src/core/calendar.ts works on { year, month, day } because new Date('2026-03-29') is the 28th in Honolulu, adding a day across a spring-forward lands on the day it started, and new Date(2026, 1, 31) is the 3rd of March. Every one of those is a booking on the wrong day that looks perfectly fine in testing.

THE LOCALE DECIDES MORE THAN THE MONTH NAMES

It decides the order of the typed fields, and that is the one that does damage: 09/05/2026 is the 9th of May in London and the 5th of September in New York, and both are real dates - so reading it wrong does not throw, it books the wrong day. The order comes from Intl.DateTimeFormat.formatToParts and the mask is built from it, so the placeholder, the mask and the parser can never disagree.

A bare en is not neutral: Intl resolves it to US conventions, so a page that declares lang="en" gets month/day/year whatever its author intended. Host pages meant for the UK must say en-GB.

The first day of the week comes from Intl.Locale's week info where the browser has it and falls back to Monday, the ISO 8601 week start, where it does not. first-day-of-week is the escape hatch for a consumer who cannot wait for a browser.

A KNOWN LIMIT, DELIBERATELY

In range mode the field is read-only and the calendar does the choosing. A masked two-date field with a separator is four times the parsing for a case people overwhelmingly use the calendar for, and the honest upgrade is two fields rather than one cleverer one. Recorded here so it is a decision rather than something nobody noticed.