@antadesign/anta 0.3.18 → 0.3.20

package/docs/components/input-autocomplete.md

@@ -0,0 +1,100 @@
+# InputAutocomplete
+
+`InputAutocomplete` is a text field with a suggestion list. Its value remains a
+free-form string: text that is not in the list stays in the field, and selecting
+a suggestion fills the field. Use [Select](./select.md) with `filter` when the
+value must be one of the options.
+
+InputAutocomplete uses an [Input](./input.md) for the field and a [Menu](./menu.md)
+for suggestions. **`onValueChange`** reports field text. `onSelect` runs only
+after someone chooses a suggestion. Use `value` to control it, or `defaultValue`
+for uncontrolled use.
+
+## Free text is the point
+
+The value is always the text in the field. That's what separates this from a
+[Select](./select.md): a Select constrains the value to one of its options, so a Select
+with `filter` already covers "search a fixed list". `InputAutocomplete` is for when
+the list only *suggests* and the user may commit something you didn't list.
+
+The keyboard follows that intent. No suggestion is highlighted as you type, so
+Enter commits the typed text and closes the list. ↓ highlights
+the first suggestion (then ↑/↓ move through them), and
+Enter on a highlighted row picks it. Esc or an outside click
+closes the list; clicking the field to place the caret keeps it open.
+
+## Filtering
+
+`filter` decides how suggestions match the text:
+
+- **`true`** (default): built-in case-insensitive substring match on each option's
+  `value` / `label` / `hint`.
+- **a function** `(option, query) => boolean`: a custom matcher, called for each option.
+- **`false`**: show `suggestions` as-is, doing no local filtering. Use this when you
+  fetch or filter results yourself (async / remote) and feed the current set through
+  `suggestions`.
+
+Suggestions are bare strings or `SelectOption`s, the same option shape
+[Select](./select.md) uses: `value`, `label`, `hint`, `icon`, `tone`, `disabled`.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `suggestions` | string \| SelectOption[] | — | The suggestions: bare strings or `SelectOption`s (`value` / `label` / `hint` /
+ `icon` / `tone` / `disabled`). A flat list; picking one fills the field. |
+| `clearable?` | boolean | — | Show a clear button while the field has text. |
+| `defaultValue?` | string | — | Initial value for uncontrolled use. |
+| `disabled?` | boolean | — | Disable the field. |
+| `filter?` | boolean \| (option, query) => boolean | true | How suggestions match the text. `true` uses the built-in case-insensitive
+ substring match on `value` / `label` / `hint`; a function `(option, query) =>
+ boolean` uses a custom matcher; `false` shows `suggestions` unchanged for
+ application-provided async or remote filtering. |
+| `hint?` | ReactNode | — | Hint under the field. |
+| `label?` | ReactNode | — | Field label. |
+| `leading?` | ReactNode | — | Leading adornment inside the field. |
+| `name?` | string | — | Form field name. |
+| `onSelect?` | (option) => void | — | Fires only when a suggestion is chosen, with that option. |
+| `onValueChange?` | (value) => void | — | Fires as the text changes (typing, picking a suggestion, or clearing) with
+ the new field text. |
+| `placeholder?` | string | — | Placeholder text. |
+| `size?` | 'small' \| 'medium' \| 'large' | medium | Field size. |
+| `status?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' | — | Validation status. |
+| `statusIcon?` | (string & {}) \| false \| IconShape | — | Status icon override, or `false` to drop it. |
+| `tone?` | string | — | Custom accent color — a named tone or any CSS color. |
+| `trailing?` | ReactNode | — | Trailing adornment inside the field. |
+| `value?` | string | — | Controlled value: the field's text, a **free** string not constrained to a
+ suggestion. Leave undefined for uncontrolled. |
+
+`InputAutocomplete` combines an input with a Menu. Reproducing its filtering,
+selection, focus, and popup coordination without the React or Preact wrapper is
+a substantial amount of code.
+
+### Native HTML input with autocomplete
+
+For browser-native suggestions, pair a native input with a `<datalist>`. It
+keeps free-form entry and lets the browser filter and fill matching options,
+while `data-anta` supplies the field appearance.
+
+The browser renders the suggestions popup. Use `InputAutocomplete` for custom
+option content, popup styling, or consistent behavior across browsers.
+
+```html
+<input data-anta type="text" list="people" placeholder="Search people">
+
+<datalist id="people">
+  <option value="Maya Chen">
+  <option value="Noah Williams">
+  <option value="Olivia Martinez">
+  <option value="Liam Johnson">
+</datalist>
+```
+
+**The field** is styled through Input's props (`size`, `status`, `tone`, `round`,
+`leading` / `trailing`) and its `::part`s; set its width with `style` / `className`
+(forwarded to the field). **The suggestion popover** takes Menu's `::part(menu)`.
+
+```tsx
+// Give the field a width; tint it with a custom tone.
+<InputAutocomplete tone="info" style={{ width: '260px' }} suggestions={frameworks} />
+```

package/docs/components/input-date.md

@@ -0,0 +1,401 @@
+# InputDate
+
+**`InputDate`** is a date field that replaces the native `type="date"` (and, with
+`time`, `type="datetime-local"`): a text field you can type into, backed by a
+`Calendar` that opens when you click the field (or press ↓), marked by a
+leading calendar icon. `Calendar`, the month grid it builds on, is documented lower
+down.
+
+The field accepts free text and resolves it on commit (blur / Enter): a lenient
+parser reads the locale's order (`06/07/2026` is June 7 in en-US, July 6 in de-DE),
+month names, and run-together digits, then rewrites the entry to the canonical
+format. An unrecognized entry marks the field until you fix it. The value is an ISO
+`YYYY-MM-DD` string, never a `Date`; it works controlled (`value` + `onValueChange`)
+or uncontrolled (`defaultValue`), and submits under `name`.
+
+## The date field
+
+Type a date and it resolves on blur or Enter, or click the field to open
+the calendar and pick a day. Either way the field settles on the locale's canonical
+format and the value is ISO `YYYY-MM-DD`. A click keeps focus in the field, so you
+can keep typing or click a day; ↓ opens the calendar and moves focus into
+the grid, and Esc closes it back to the field. While you type, the calendar
+previews the entry — it jumps to that month and highlights the day — and commits it on
+Enter (which also closes the calendar); an unrecognized entry keeps the
+calendar open and marks the field.
+
+```tsx
+<InputDate label="Due date" defaultValue="2026-06-15" onValueChange={(v) => save(v)} />
+```
+
+The placeholder shows the locale's format, and parsing follows the same order, so
+`de-DE` reads and writes `TT.MM.JJJJ` while `en-US` uses `MM/DD/YYYY`. `min` / `max`
+bound both the calendar and what a typed date will accept.
+
+```tsx
+<InputDate label="US English" locale="en-US" defaultValue="2026-06-15" />
+<InputDate label="German" locale="de-DE" defaultValue="2026-06-15" />
+```
+
+`time` turns it into a date-time field (value `YYYY-MM-DDTHH:mm`). The menu grows a
+time row under the calendar: an [`InputTime`](./input-time.md) (segmented hour / minute,
+plus AM/PM in 12-hour locales) and a confirm (✓) button. Picking a day keeps the menu
+open so you can set the time. The clock follows the locale (`en-US` is 12-hour, most
+others 24), overridable with `hour12`. The field parses a trailing time after a space
+(`06/15/2026 2:30pm` or `… 14:30`), and typing a 24-hour hour into the 12-hour time
+field converts it (18 → 6 PM).
+
+```tsx
+{/* `size` scales the calendar, the time inputs, the AM/PM toggle, and the buttons together. */}
+<InputDate size="small" label="Small" time defaultValue="2026-06-15T09:00" />
+<InputDate size="medium" label="Medium" time defaultValue="2026-06-15T09:00" />
+<InputDate size="large" label="Large" time defaultValue="2026-06-15T09:00" />
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `clearable?` | boolean | — | Show a clear button once the field has a value. |
+| `defaultValue?` | string | — | Initial value for the uncontrolled case. |
+| `disabled?` | boolean | — | Disable the field and the calendar. |
+| `hint?` | ReactNode | — | Helper text under the field. Replaced by a format hint while the entry is
+ unrecognized. |
+| `hour12?` | boolean | — | Force the time cycle when `time` is on: `true` for 12-hour (AM/PM), `false`
+ for 24-hour. Omit to follow the locale (`en-US` → 12-hour, most others → 24). |
+| `icon?` | false \| IconShape | calendar-days | Leading icon at the start of the field — the calendar affordance. Pass
+ another shape to change it, or `false` to drop it. |
+| `label?` | ReactNode | — | Field label, above the control. |
+| `locale?` | string | navigator.language | BCP-47 locale driving the display format, the placeholder mask, parsing order,
+ and the calendar. |
+| `max?` | string | — | Latest selectable date (ISO). |
+| `min?` | string | — | Earliest selectable date (ISO). Earlier days disable, and a typed date before
+ it stays uncommitted. |
+| `name?` | string | — | Form field name — the ISO value submits under this key. |
+| `offset?` | number | 4 | Gap in pixels between the field and the calendar menu. |
+| `onValueChange?` | (value, attrs) => void | — | Fired after the value resolves (a recognized entry, a calendar pick, a time
+ change, or a clear), with the new ISO value (`''` when cleared) and a
+ `{ value, name }` snapshot. An unrecognized entry does not fire it. |
+| `placeholder?` | string | the locale's format mask (e.g. `MM/DD/YYYY`, `MM/DD/YYYY HH:MM` with `time`) | Placeholder shown when empty. |
+| `placement?` | 'left' \| 'right' \| 'bottom' \| 'top' \| 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end' \| 'right-start' \| 'right-end' \| 'left-start' \| 'left-end' | bottom-start | Preferred placement of the calendar menu relative to the field. Same values as
+ `Menu`; it auto-flips and clamps when space runs out. |
+| `round?` | boolean \| number \| string | — | Round the field corners — `true` for fully round, or a number / CSS length. |
+| `size?` | 'small' \| 'medium' \| 'large' | medium | Field size. Also sizes the calendar and the time row. |
+| `status?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' | neutral | Validation/feedback tone. An unrecognized entry forces `critical` until fixed. |
+| `time?` | boolean | — | Include a time. The value becomes ISO `YYYY-MM-DDTHH:mm`, the field parses a
+ trailing time after a space (`06/15/2026 14:30`, `… 2:30pm`), and the menu
+ shows a time row (hours : minutes, an AM/PM toggle in 12-hour locales, then a
+ Done button) under the calendar. Picking a day keeps the menu open so you can
+ set the time. |
+| `value?` | string | — | Controlled value — ISO `YYYY-MM-DD` (or `YYYY-MM-DDTHH:mm` with `time`), `''`
+ for empty. Pair with `onValueChange`; the field and calendar follow it and a
+ pick only *requests* a change. |
+
+## Calendar
+
+The sections below document `Calendar`, the month grid `InputDate` opens. Reach for
+it directly when you want the grid inline, without a field.
+
+`Calendar` uses Anta components in light DOM; it has no hidden shadow-root UI.
+The day cells and previous/next chevrons are `<Button>`s inside a
+form-associated `<a-calendar>` grid. Date calculations use the
+[Temporal API](https://tc39.es/proposal-temporal/docs/) through
+`temporal-polyfill`.
+
+For a raw grid, import `buildMonth` from `@antadesign/anta`. It returns
+localized weekday headers and day records with ISO values, accessible labels,
+and selected, disabled, today, and outside-month state. It does not manage
+navigation, roving focus, selection, or rendering. The value is an ISO
+`YYYY-MM-DD` string, never a `Date`. Use `value` with `onStateChange` to
+control it, or `defaultValue` for uncontrolled use. It participates in forms
+under `name`.
+
+**Not SSR-safe.** `Calendar` (and `InputDate`, which embeds it) reads the current
+date (`Temporal.Now`) and locale (`navigator.language`) at render, so a server
+render disagrees with the client on the highlighted "today" and on localized
+labels, and the page hydrates with a mismatch. Render it client-side only: Astro
+`client:only`, or a dynamic import inside `useEffect`. Every demo on this page uses
+`client:only` for that reason.
+
+## Selecting a date
+
+Click a day, or focus the grid and press Enter / Space. The
+selected day takes the tertiary-button selected look toned brand — a brand-tinted
+filled cell with a ring. Today shows as a secondary Button, a resting fill.
+
+```tsx
+<Calendar defaultValue="2026-06-12" />
+```
+
+## Size
+
+`size` scales the whole calendar: the day cells, the prev/next chevrons, and the
+weekday and month-heading type. It follows Button's `small` / `medium` (default) /
+`large` scale, with day-cell heights of 24 / 28 / 32px.
+
+```tsx
+<Calendar size="small" defaultValue="2026-06-28" />
+<Calendar defaultValue="2026-06-28" />          {/* medium (default) */}
+<Calendar size="large" defaultValue="2026-06-28" />
+```
+
+## Range
+
+`min` and `max` (ISO strings) bound the selectable range. Days outside it render
+disabled and skip keyboard focus, and the prev/next arrows stop at the range edge.
+The jump menu adapts to how far the range reaches.
+
+No `min` / `max`: the jump menu lists today ±3 years, each a submenu of its months.
+
+```tsx
+<Calendar size="small" defaultValue="2026-06-15" />
+```
+
+A range across years lists each year (here 2026 and 2027) as a submenu of months.
+June 2026 disables days 1–7, and the back arrow stops at the range's start.
+
+```tsx
+<Calendar size="small" defaultValue="2026-06-15" min="2026-06-08" max="2027-06-24" />
+```
+
+A range inside one year skips the year level and lists months directly, March
+through November enabled and the rest disabled.
+
+```tsx
+<Calendar size="small" defaultValue="2026-06-15" min="2026-03-01" max="2026-11-30" />
+```
+
+A range inside one month leaves nowhere to jump. Both arrows and the month/year
+button are disabled, and only the in-range days stay selectable.
+
+```tsx
+<Calendar size="small" defaultValue="2026-06-15" min="2026-06-08" max="2026-06-24" />
+```
+
+## Locale
+
+`Calendar` respects the browser locale by default (`navigator.language`). Pass a
+BCP-47 `locale` to override it: the first day of week comes from the locale's week
+info (never hard-coded to Sunday), and the weekday and month names are localized.
+
+```tsx
+<Calendar defaultValue="2026-06-28" locale="en-US" />  {/* week starts Sunday */}
+<Calendar defaultValue="2026-06-28" locale="fr-FR" />  {/* week starts Monday */}
+<Calendar defaultValue="2026-06-28" locale="ja-JP" />
+```
+
+## Controlled
+
+Uncontrolled by default: pass `defaultValue` and read the date from `onValueChange`
+or at form submit. Make it controlled with `value` + `onStateChange` to drive it
+from your store. The grid then follows `value`, and a pick only *requests* a change:
+answer by updating `value`, reject by doing nothing.
+
+```tsx
+const [date, setDate] = useState('2026-06-28')
+
+<Calendar
+  value={date}
+  onStateChange={(_e, { next }) => setDate(next ?? '')}
+/>
+```
+
+`onStateChange` fires before the element applies, with `(event, { next, prev, reason })`
+where `next` / `prev` are ISO strings. For a `'user'` pick, `event.preventDefault()`
+vetoes it (uncontrolled). A controlled calendar with no `onStateChange` is read-only.
+
+## Disabled
+
+`disabled` dims the whole calendar and removes it from interaction.
+
+```tsx
+<Calendar defaultValue="2026-06-28" disabled />
+```
+
+## Forms
+
+`Calendar` is form-associated. Give it a `name` and it submits the selected ISO
+date under that key, resets to `defaultValue` on form reset, and reports through
+the standard constraint-validation pipeline.
+
+```tsx
+<form>
+  <Calendar name="due-date" defaultValue="2026-06-28" />
+</form>
+```
+
+## Accessibility
+
+The calendar is a labelled **group** of day buttons, a flat grid rather than a
+nested `grid`/`row`/`gridcell` tree. The group is named by the visible month
+(`aria-labelledby`). Each day is a `<button>` whose `aria-label` is its full date
+including weekday ("Sunday, June 28, 2026"), with `aria-pressed` on the selected day
+and `aria-current="date"` on today. The decorative weekday headers are `aria-hidden`,
+since each day already names its weekday. A roving `tabindex` keeps a single tab
+stop, and an `aria-live` region announces the month when it changes.
+
+| Key | Moves focus |
+|---|---|
+| ← / → | by one day |
+| ↑ / ↓ | by one week |
+| Home / End | to the start / end of the week |
+| PageUp / PageDown | by one month |
+| Shift + PageUp / PageDown | by one year |
+| Enter / Space | select the focused day |
+
+## Customization
+
+`InputDate` uses Input, Menu, and Calendar. Calendar uses an `<a-calendar>`
+element for the day grid and a JSX wrapper for navigation. The sections below
+describe which layer provides each behavior and how to recreate the interface
+without React.
+
+### Build it from elements
+
+`InputDate` has no `a-inputdate` element. Its wrapper renders an editable
+`<Input>` and a `<Menu>` containing a `<Calendar>`. When `time` is set, the
+hour/minute fields and AM/PM `Tabs` appear below the grid. The wrapper manages
+draft text, parsing on commit, and the ISO value.
+
+Clicking the field opens the menu while keeping focus in the field. Pressing
+↓ opens the menu and moves focus to the grid. The wrapper passes a
+`focusSignal` to Calendar, which renders `data-focus`; `<a-calendar>` then
+focuses the active day. Calendar and Tabs emit their own `statechange` events,
+but Menu responds only to changes in its own open state.
+
+The `<a-calendar>` element provides grid behavior. It connects the supplied day
+`<button>`s to click and keyboard navigation, including arrows, Home,
+End, PageUp, and PageDown. It stores the form
+value through `ElementInternals` and emits `statechange` / `change` on selection
+and `navigate` when keyboard navigation leaves the displayed month. It is
+framework-agnostic and does not track a current month, `min`, or `max`.
+
+The JSX wrapper renders the controls above the grid as siblings of
+`<a-calendar>`. The previous/next arrows are `<Button>`s. The month/year picker
+is a `<Button>` that opens a `<Menu>` of year `MenuItem`s, each with a month
+submenu. The wrapper stores the displayed-month cursor in state and derives day
+cells and the arrows' `disabled` states from `min` and `max`. A click on an
+arrow, a menu selection, or a `navigate` event updates the cursor and re-renders
+the grid. The wrapper enforces the range. The element only ignores a day that
+was rendered with `disabled`.
+
+The element has no `min` or `max` because the wrapper provides the surrounding
+controls. Without React, render the grid with `buildMonth` and add the
+navigation behavior shown below:
+
+```html
+<!-- `.calendar` scopes this example. Use an application selector instead. -->
+<div class="calendar" style="display: inline-flex; flex-direction: column; gap: 6px">
+  <div style="display: flex; align-items: center">
+    <a-button priority="tertiary" data-prev aria-label="Previous month"><a-icon shape="chevron-left"></a-icon></a-button>
+    <a-button priority="tertiary" data-heading style="flex: 1; justify-content: center" aria-haspopup="menu"></a-button>
+    <a-button priority="tertiary" data-next aria-label="Next month"><a-icon shape="chevron-right"></a-icon></a-button>
+  </div>
+  <!-- The element provides selection, keyboard behavior, form value, and events. -->
+  <a-calendar role="group" name="date"></a-calendar>
+</div>
+<script type="module">
+  import '@antadesign/anta/elements'
+  import { buildMonth, parseISODate } from '@antadesign/anta'
+  import { Temporal } from 'temporal-polyfill'
+
+  const root = document.querySelector('.calendar')
+  const grid = root.querySelector('a-calendar')
+  const heading = root.querySelector('[data-heading]')
+  let cursor = Temporal.Now.plainDateISO()
+
+  function render() {
+    const m = buildMonth({ anchor: cursor, locale: navigator.language })
+    heading.textContent = m.heading
+    grid.replaceChildren()
+    for (const w of m.weekdays) {
+      const s = Object.assign(document.createElement('span'), { textContent: w.narrow })
+      s.setAttribute('data-part', 'weekday')
+      s.setAttribute('aria-hidden', 'true')
+      grid.append(s)
+    }
+    for (const d of m.weeks.flat()) {
+      const b = Object.assign(document.createElement('a-button'), { textContent: String(d.day) })
+      b.setAttribute('priority', 'tertiary')
+      b.setAttribute('data-part', 'day-cell')
+      b.setAttribute('data-date', d.iso)      // the element keys off this
+      b.tabIndex = d.iso === cursor.toString() ? 0 : -1
+      if (d.selected) b.setAttribute('selected', '')
+      if (d.disabled) b.setAttribute('disabled', '')
+      grid.append(b)
+    }
+  }
+
+  root.querySelector('[data-prev]').addEventListener('click', () => { cursor = cursor.subtract({ months: 1 }); render() })
+  root.querySelector('[data-next]').addEventListener('click', () => { cursor = cursor.add({ months: 1 }); render() })
+  // Keyboard paging past the rendered grid: the element asks for a month flip.
+  grid.addEventListener('navigate', (e) => { cursor = parseISODate(e.detail.date) ?? cursor; render() })
+  render()
+</script>
+```
+
+Tracking the cursor, painting the grid from `buildMonth`, and re-rendering on
+`navigate` is what the React `Calendar` packages, plus the year/month jump menu,
+which uses the same `Menu` composition shown on the [Menu](./menu.md) page.
+
+`InputDate` has no host element. Rebuilding its text parsing, dropdown calendar,
+localized day grid, month navigation, keyboard navigation, and focus management
+in vanilla JavaScript is significant work, even with Anta's `buildMonth` and
+`parseISODate` helpers. Use the `InputDate` wrapper when React or Preact is an
+option. Otherwise, a native HTML date input is the practical baseline.
+
+### Native HTML date input
+
+Add `data-anta` to a `date`, `datetime-local`, `month`, `time`, or `week` input.
+Nothing else is required: Anta styles the field while the browser keeps its picker,
+icon, validation, and keyboard model. The picker itself and its date/time
+formatting remain browser- and OS-owned.
+
+`data-anta-size`, `round`, and a custom-color `tone` use the matching Input
+field treatments.
+
+```html
+<!-- `data-anta` styles the field, not the native picker. -->
+<input data-anta type="date" name="due-date" value="2026-06-15">
+<input data-anta type="datetime-local" name="starts-at" value="2026-06-15T09:00">
+<input data-anta type="month" name="billing-month" value="2026-06">
+<input data-anta type="time" name="reminder-at" value="09:00">
+<input data-anta type="week" name="sprint-week" value="2026-W25">
+```
+
+The calendar is **light DOM**, so everything is plain CSS, with no shadow parts or
+hidden internals. The days and chevrons are real `<a-button>`s, so their colors,
+hover, focus ring, and selected look come from the Button styles and theme
+themselves; they sit inside the `<a-calendar>` grid, and the switcher header sits in
+the `.anta-calendar` shell. An un-layered consumer rule beats `@layer anta` without
+`!important`. The class below is for the demo.
+
+```css
+/* Bigger, circular day cells. `className` lands on the outer .anta-calendar
+   shell; `--calendar-cell-width` / `--calendar-cell-height` drive the grid track
+   and the cell box (inherited down), and you target the day Buttons directly. */
+.anta-calendar.roomy { --calendar-cell-width: 40px; --calendar-cell-height: 40px; }
+.anta-calendar.roomy a-button[data-part="day-cell"] { border-radius: 50%; }
+```
+
+Each day is a `<a-button data-part="day-cell" data-date="YYYY-MM-DD">`, so a
+specific date is addressable by its `data-date`: tint it, or hang an event marker
+off a `::after` (give the cell `position: relative` first). Below, three days carry a
+brand dot and one is flagged in the critical color.
+
+```css
+/* Day cells are `<a-button data-part="day-cell" data-date="YYYY-MM-DD">`. Give them a
+   positioning context, dot event days with a `::after`, and tint a date's text. */
+.anta-calendar.events a-button[data-part="day-cell"] { position: relative; }
+.anta-calendar.events a-button[data-part="day-cell"]:is(
+  [data-date="2026-06-05"], [data-date="2026-06-12"], [data-date="2026-06-20"]
+)::after {
+  content: ""; position: absolute; inset-block-end: 3px; inset-inline-start: 50%;
+  inline-size: 4px; block-size: 4px; transform: translateX(-50%);
+  border-radius: 999px; background: var(--text-2-brand);
+}
+.anta-calendar.events a-button[data-part="day-cell"][data-date="2026-06-25"] {
+  color: var(--text-2-critical); font-weight: 600;
+}
+```
+
+The engine (`buildMonth`, `firstDayOfWeek`, …) is exported, so you can render a
+fully custom grid and keep only the `<a-calendar>` form plumbing.

package/docs/components/input-time.md

@@ -0,0 +1,174 @@
+# InputTime
+
+**`InputTime`** is a segmented wall-clock field: one boxed input, like the others,
+holding separate **hour** and **minute** sections — plus an **AM/PM** section in
+12-hour locales — that behave as a single control. Each section is a native text
+input:
+↑/↓ steps its value (wrapping 59 → 00), ←/→
+moves between sections at the caret boundary, and typing a digit fills the section
+and advances to the next once it can't hold more. AM/PM accepts its locale text or
+`a` / `p`.
+
+A leading clock icon marks the affordance (change it with `icon`). Unlike a text
+`Input` (which fills its container), the field **sizes to its content** — a time
+is a small, fixed control — so set a `width` (e.g. `style={{ width: '100%' }}`) if
+you want it to fill. The value is a 24-hour `"HH:mm"` string (`''` until both hour
+and minute are set), never a `Date`. It works controlled (`value` + `onValueChange`)
+or uncontrolled (`defaultValue`), and submits under `name` via the native form APIs.
+
+## The field
+
+Focus a section and edit it with the keyboard: ↑/↓ to step (it
+wraps), PageUp/PageDown for a larger jump on minutes,
+or enter the digits. Home/End, selection, deletion, and
+paste behave as they do in a native text input. Typing
+`9` then `3` `0` lands `09:30` and moves across the sections on its own; an
+out-of-range digit (a `6` in the minutes) commits and advances immediately.
+Backspace on an empty section selects the previous one. The whole thing
+reads as one field while preserving native caret behavior. In a
+12-hour field, typing a 24-hour hour converts it and flips AM/PM — `18` becomes
+`6 PM`, so pasted 24-hour times work.
+
+```tsx
+<InputTime label="Start time" defaultValue="09:30" onValueChange={(_, { value }) => save(value)} />
+```
+
+## Locale
+
+The clock follows the locale: `en-US` shows 12-hour with an AM/PM section, most
+others show 24-hour with none. It's derived from `Intl` (the resolved `hourCycle`),
+and the section **order**, the **separator**, and the **AM/PM text** all come from
+the locale too — Japanese renders the period first (`午後2:05`), Finnish separates
+with a dot (`14.05`), and 24-hour locales drop the AM/PM section entirely. Set
+`hour12` to force one clock regardless of locale.
+
+```tsx
+<InputTime label="US English" locale="en-US" defaultValue="14:05" />   {/* 12-hour: 02 : 05 PM */}
+<InputTime label="German"     locale="de-DE" defaultValue="14:05" />   {/* 24-hour: 14 : 05 */}
+<InputTime label="Japanese"   locale="ja-JP" hour12 defaultValue="14:05" />  {/* 午後 02:05 — period first */}
+<InputTime label="Force 24h"  hour12={false} defaultValue="14:05" />
+```
+
+## Size, status, and clearing
+
+`size` (`small` / `medium` / `large`) matches the other inputs' scale; `status`
+recolors the box and hint (only `critical` marks it invalid); `clearable` adds a
+clear button once a value is set — clearing empties every section back to the
+placeholder dashes. `disabled` behaves as it does on `Input`.
+
+`min` and `max` (24-hour `"HH:mm"`) bound the value: a complete time outside the
+range is clamped to the nearest bound as you step or leave the field, and flags
+`rangeUnderflow` / `rangeOverflow` for form validity in the meantime.
+
+```tsx
+<InputTime label="Meeting" size="small" defaultValue="10:00" clearable />
+<InputTime label="Deadline" status="critical" hint="Pick a time in the future." />
+<InputTime label="Office hours" size="large" min="09:00" max="17:00" defaultValue="09:30" />
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children?` | ReactNode | — | Extra content rendered under the field, above the hint (a no-box child like
+ a `<Tooltip>` takes no space and anchors to the field). |
+| `clearable?` | boolean | — | Show a clear button once the field has a value. |
+| `defaultValue?` | string | — | Initial value for the uncontrolled case (24-hour `"HH:mm"`). |
+| `dimActions?` | boolean | — | Dim the trailing adornments at rest; they brighten on hover / focus. |
+| `disabled?` | boolean | — | Disable the field. |
+| `hint?` | ReactNode | — | Message below the field. `status` recolors it and prefixes a glyph. |
+| `hour12?` | boolean | — | Force the clock: `true` = 12-hour (AM/PM), `false` = 24-hour. Omit to follow
+ the locale. |
+| `icon?` | false \| IconShape | clock | Leading icon at the start of the field — the clock affordance. Pass another
+ shape to change it, or `false` to drop it. |
+| `label?` | ReactNode | — | Field label, shown above the control and used as the segment group's
+ accessible name. |
+| `locale?` | string | navigator.language | BCP-47 locale driving the clock (12h vs 24h), segment order, separator, and
+ the AM/PM text. |
+| `max?` | string | — | Latest allowed time, 24-hour `"HH:mm"`. A complete value above it is clamped
+ down (on step / blur) and flagged `rangeOverflow`. |
+| `min?` | string | — | Earliest allowed time, 24-hour `"HH:mm"`. A complete value below it is
+ clamped up (on step / blur) and flagged `rangeUnderflow` for form validity. |
+| `name?` | string | — | Form field name — the 24-hour value submits under this key. |
+| `onBlur?` | (e) => void | — | Fires when the field loses focus. |
+| `onClearInput?` | (e) => void | — | Fires after the built-in clear button has cleared the field. |
+| `onFocus?` | (e) => void | — | Fires when the field gains focus. |
+| `onValueChange?` | (event, attrs) => void | — | Fires on every edit (`input`), with the native event + an `attrs` snapshot
+ (`value`, `name`, `empty`, `valid`, `validationMessage`). Also fires on
+ `change` (blur) and on clear. |
+| `required?` | boolean | — | Mark the field required (drives native validity). |
+| `round?` | boolean \| number \| string | — | Fully-round the field, or a custom radius (`number` px / CSS length). |
+| `size?` | 'small' \| 'medium' \| 'large' | medium | Size variant. small=24px, medium=28px, large=32px tall. |
+| `status?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' | — | Validation / feedback tone. Only `critical` marks the field invalid; the
+ others are advisory. Omit (or `neutral`) for a plain field. |
+| `statusIcon?` | (string & {}) \| false \| IconShape | — | Glyph before the `hint` when `status` is set (per-status default; pass a
+ shape to override, or `false` to drop it). |
+| `tone?` | string | — | Custom accent color — any literal CSS color tints the resting + hover
+ border (focus ring stays `--focus-ring`); `status` overrides for validation. |
+| `trailing?` | ReactNode | — | Content pinned to the end of the field (after the clear button). |
+| `value?` | string | — | Controlled value — 24-hour `"HH:mm"`. Pair with `onValueChange`. |
+
+Use the web component directly when you are not using React or Preact and a native control does not fit.
+
+Slots supply the field label and leading icon.
+
+```html
+<a-input-time name="start-time" defaultvalue="09:30">
+  <span slot="label">Start time</span>
+  <a-icon slot="leading" shape="clock" aria-hidden="true"></a-icon>
+</a-input-time>
+```
+
+### Native HTML time input
+
+For a form that can use the browser's time picker, add `data-anta` to a regular
+time input. It gives the field Anta's resting chrome while the browser keeps its
+own picker, validation, and keyboard behavior.
+
+`data-anta-size`, `round`, and a custom-color `tone` use the matching Input
+field treatments.
+
+```html
+<input data-anta type="time" name="reminder-at" value="09:00">
+```
+
+## Styling
+
+`InputTime` renders an `<a-input-time>` whose field chrome mirrors `<a-input>`.
+Route feedback color through `status`; everything else is reachable as plain CSS on
+the host or through `::part()`. `segment` targets every editable input. `hour`,
+`minute`, and `period` target one segment type regardless of locale order. `literal`
+targets the localized separator. The element also exposes `field`, `segments`,
+`leading`, `label`, `hint`, `clear`, and `trailing`. Don't override the internal
+`--input-time-*` values directly; they are defaults, not a styling API.
+
+```css
+/* Make one field fill its container (the default is content-width). Style all
+   editable segments, then keep AM/PM and the locale separator quieter. */
+.my-time { width: 100%; }
+.my-time::part(segments) { color: #e5484d; }
+.my-time::part(period) { color: var(--text-3); }
+.my-time::part(literal) { color: var(--text-4); }
+```
+
+Drop the clock icon with the `icon={false}` prop, and point the `segments` part at
+a monospaced family for fixed-width digits — a small `padding-top` re-centers the
+tighter `1em` line:
+
+```tsx
+<InputTime icon={false} className="plain-time" defaultValue="09:30" />
+
+<style>{`
+  .plain-time::part(segments) {
+    font-family: var(--monospace, ui-monospace, monospace);
+    line-height: 1em;
+    padding-top: 2px;
+  }
+`}</style>
+```
+
+For a one-off accent, `tone` takes **any literal CSS color** (e.g. `#7c3aed`) and
+tints the resting + hover border — the focus ring stays the global ring. It's a
+color, not a named tone; the named feedback tones live on `status`.
+
+```tsx
+<InputTime label="Accent" tone="#7c3aed" defaultValue="09:30" />
+```