@antadesign/anta 0.3.34 → 0.3.35

package/docs/components/input-date.md

@@ -1,49 +1,46 @@
 # 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`.
+Use InputDate to enter a date by typing or choosing a day from a calendar.
+Add `time` when the task also needs a time of day. Use [Calendar](#calendar)
+directly when the month grid should stay visible without a field.
+
+Render InputDate and Calendar only on the client. Their current date and locale
+can differ between server and browser rendering. In Astro, use `client:only`.
+See [Server and worker rendering](../install-config.md#server-and-worker-rendering) for
+setup guidance.
 
 ## 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.
+Enter a date and press Enter or leave the field to confirm it.
+InputDate accepts the locale's date order, month names, and dates without
+separators, then formats the result. An unrecognized entry stays visible and
+marks the field invalid so it can be corrected.
+
+Select the field to open its calendar while keeping focus in the text.
+Press ↓ to open the calendar and focus a day. Press Esc
+to close it and return focus to the field. While you type, the calendar previews
+recognized dates. Pressing Enter confirms the date and closes the
+calendar. An unrecognized entry keeps the calendar open.
 
 ```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.
+Set `locale` to choose the date format. For example, `06/07/2026` means June 7
+in `en-US` and July 6 in `de-DE`. The placeholder shows the expected format.
+Use `min` and `max` to limit both typed dates and calendar choices.
 
 ```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).
+Pass `time` to add a time field and confirmation button to the calendar.
+Choosing a day keeps the calendar open so the time can be entered before
+confirming. The clock follows the locale. Use `hour12` to override it.
+
+You can also type a date and time together, such as `06/15/2026 2:30pm` or
+`06/15/2026 14:30`. In a 12-hour time field, entering `18` converts to `6 PM`.
 
 ```tsx
 {/* `size` scales the calendar, the time inputs, the AM/PM toggle, and the buttons together. */}
@@ -52,6 +49,19 @@ field converts it (18 → 6 PM).
 <InputDate size="large" label="Large" time defaultValue="2026-06-15T09:00" />
 ```
 
+### Manage the value
+
+Use `defaultValue` for an initial date, or pair `value` with `onValueChange`
+to control it. InputDate reports an ISO string: `YYYY-MM-DD`, or
+`YYYY-MM-DDTHH:mm` with `time`. An empty field reports `''`. Add `name` to
+submit that value with a form.
+
+```tsx
+const [date, setDate] = useState('2026-06-15')
+
+<InputDate label="Due date" name="due-date" value={date} onValueChange={setDate} />
+```
+
 ## InputDate props
 
 | Prop | Type | Default | Description |
@@ -79,35 +89,18 @@ field converts it (18 → 6 PM).
 
 ## 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.
+Use Calendar for an inline date picker, such as a booking form with a month
+always in view. It provides day selection, month navigation, keyboard access,
+and form submission.
+
+Like InputDate, Calendar must render only on the client. The examples use
+Astro's `client:only` directive.
 
 ## 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.
+Select a day, or focus it and press Enter or Space.
+The selected day has a brand-colored fill and ring. Today's date has a subtle
+fill when it is not selected.
 
 ```tsx
 <Calendar defaultValue="2026-06-12" />
@@ -160,9 +153,8 @@ button are disabled, and only the in-range days stay selectable.
 
 ## 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.
+Calendar uses the browser's locale by default. Pass a locale tag such as
+`en-US`, `fr-FR`, or `ja-JP` to choose the language and first day of the week.
 
 ```tsx
 <Calendar defaultValue="2026-06-28" locale="en-US" />  {/* week starts Sunday */}
@@ -200,9 +192,9 @@ vetoes it (uncontrolled). A controlled calendar with no `onStateChange` is read-
 
 ## 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.
+Add `name` to submit the selected ISO date with a form. An uncontrolled Calendar
+returns to `defaultValue` on form reset. For a controlled Calendar, handle the
+reset request in `onStateChange` and update `value` as needed.
 
 ```tsx
 <form>
@@ -212,19 +204,13 @@ the standard constraint-validation pipeline.
 
 ## Accessibility
 
-The focused Input field is associated directly with its Calendar dialog through
-ARIA element reflection. The relationship does not require a generated popup ID,
-so separate application roots can render InputDate instances without ID
-collisions. An explicitly authored relationship on a raw Anta Input takes
-precedence.
+InputDate identifies its calendar as a dialog associated with the field.
+Opening it with ↓ moves focus into the calendar. Closing it with
+Esc returns focus to the field.
 
-The calendar is a labelled **group** of day buttons, a flat grid rather than a
-nested `grid`/`row`/`gridcell` tree. The visible month names the group directly.
-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.
+Calendar announces the displayed month and gives each day its full date,
+including the weekday. Screen readers can identify the selected day and today's
+date. The day grid has one Tab stop, and changing months announces the new month.
 
 | Key | Moves focus |
 |---|---|
@@ -237,53 +223,38 @@ stop, and an `aria-live` region announces the month when it changes.
 
 ## 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.
+Use the InputDate and Calendar wrappers for the complete date-entry interface.
+For custom calendar rendering, `buildMonth` supplies localized weekday headers
+and day records with ISO values, accessible labels, and selection and range
+states. Your application supplies rendering and navigation.
 
 ### 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:
+InputDate combines Input, Menu, and Calendar. There is no separate InputDate host
+element. Recreating it requires text parsing, date formatting, popup behavior,
+and focus management. For a form that can use the browser's picker, consider
+[Native HTML date input](#native-html-date-input).
+
+For a custom month grid, use `<a-calendar>` with day buttons marked
+`data-part="day-cell"` and `data-date="YYYY-MM-DD"`. It provides keyboard
+navigation, selection requests, and form submission. Render the surrounding
+month controls yourself and handle `navigate` when focus moves to another date.
+
+`buildMonth` returns the month heading, weekdays, and day records. Pass `min`
+and `max` to it when building a bounded grid, render out-of-range dates with
+`disabled`, and limit your month controls to that range.
+
+This example supplies previous and next month controls and a controlled
+selection:
 
 ```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>
+    <a-button role="button" tabindex="0" priority="tertiary" data-prev aria-label="Previous month"><a-icon shape="chevron-left" aria-hidden="true"></a-icon></a-button>
+    <span data-heading style="flex: 1; text-align: center"></span>
+    <a-button role="button" tabindex="0" priority="tertiary" data-next aria-label="Next month"><a-icon shape="chevron-right" aria-hidden="true"></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">
@@ -295,40 +266,99 @@ navigation behavior shown below:
   const grid = root.querySelector('a-calendar')
   const heading = root.querySelector('[data-heading]')
   let cursor = Temporal.Now.plainDateISO()
+  grid.value = cursor.toString()
+
+  function focusDate(iso) {
+    grid.querySelector(`[data-date="${iso}"]`)?.focus()
+  }
 
   function render() {
-    const m = buildMonth({ anchor: cursor, locale: navigator.language })
-    heading.textContent = m.heading
+    const month = buildMonth({
+      anchor: cursor,
+      locale: navigator.language,
+      selected: parseISODate(grid.value),
+    })
+    heading.textContent = month.heading
+    grid.setAttribute('aria-label', month.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 weekday of month.weekdays) {
+      const label = Object.assign(document.createElement('span'), { textContent: weekday.narrow })
+      label.setAttribute('data-part', 'weekday')
+      label.setAttribute('aria-hidden', 'true')
+      grid.append(label)
     }
-    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)
+    for (const day of month.weeks.flat()) {
+      const button = document.createElement('a-button')
+      const label = Object.assign(document.createElement('a-button-label'), { textContent: String(day.day) })
+      button.append(label)
+      button.setAttribute('role', 'button')
+      button.setAttribute('priority', day.today && !day.selected ? 'secondary' : 'tertiary')
+      button.setAttribute('data-part', 'day-cell')
+      button.setAttribute('data-date', day.iso)
+      button.setAttribute('aria-label', day.label)
+      button.setAttribute('aria-pressed', String(day.selected))
+      button.tabIndex = day.iso === cursor.toString() ? 0 : -1
+      if (day.selected) {
+        button.setAttribute('selected', '')
+        button.setAttribute('tone', 'brand')
+      }
+      if (day.disabled) button.setAttribute('disabled', '')
+      if (day.today) {
+        button.setAttribute('data-today', '')
+        button.setAttribute('aria-current', 'date')
+      }
+      if (day.outside) button.setAttribute('data-outside', '')
+      grid.append(button)
     }
   }
 
-  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() })
+  root.querySelector('[data-prev]').addEventListener('click', () => {
+    cursor = cursor.subtract({ months: 1 })
+    render()
+  })
+  root.querySelector('[data-next]').addEventListener('click', () => {
+    cursor = cursor.add({ months: 1 })
+    render()
+  })
+  grid.addEventListener('statechange', (event) => {
+    grid.value = event.detail.next ?? ''
+    cursor = parseISODate(grid.value) ?? cursor
+    render()
+    focusDate(cursor.toString())
+  })
+  grid.addEventListener('navigate', (event) => {
+    cursor = parseISODate(event.detail.date) ?? cursor
+    render()
+    focusDate(cursor.toString())
+  })
   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.
+Use the Calendar wrapper when you also need its year/month jump menu and
+range-aware controls.
+
+### Raw Calendar value and form API
+
+Use `value` for controlled selection or `defaultvalue` for an uncontrolled
+initial and reset date. The `.value` property returns the applied ISO date, or
+`null` when empty. The `.defaultValue` property returns the authored reset date,
+or `null` when unset.
+
+Assigning a string to `.value` supplies controlled input. An empty `value=""`
+keeps the calendar controlled and empty. Remove `value`, or assign `null` or
+`undefined` to `.value`, to release control while retaining the applied date.
+Uncontrolled picks, reset, and restoration leave those input attributes unchanged.
+
+Accept controlled picks from `statechange` by updating `value`. `change` reports
+applied selection. `navigate` requests a new focus date. The application renders
+the requested month and focuses that day. Author the month label and each day
+button's accessible name. Calendar does not generate those labels.
+
+For Preact, prefer the Calendar wrapper. Raw `<a-calendar value={...}>` bindings
+can retain the old value when assigned `undefined`, or write `value=""` when the
+prop is omitted. Release a raw instance by removing its `value` attribute or
+assigning `null` to `.value`.
 
 ## Calendar props
 
@@ -350,11 +380,8 @@ which uses the same `Menu` composition shown on the [Menu](./menu.md) page.
 
 ## Web Component
 
-`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.
+Use a native date input when the browser's picker fits your form. To build a
+custom picker without JSX, see [Build it from elements](#build-it-from-elements).
 
 ### Native HTML date input
 
@@ -377,12 +404,12 @@ field treatments.
 
 ## Styling
 
-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.
+Use ordinary CSS to style the calendar and its day buttons. `className` applies
+to the outer `.anta-calendar` container. Unlayered consumer rules override Anta's
+defaults. Replace the example classes with your own selectors.
+
+Set `--calendar-cell-width` and `--calendar-cell-height` to make day targets
+larger, then use `border-radius` to shape them:
 
 ```css
 /* Bigger, circular day cells. `className` lands on the outer .anta-calendar
@@ -413,5 +440,5 @@ brand dot and one is flagged in the critical color.
 }
 ```
 
-The engine (`buildMonth`, `firstDayOfWeek`, …) is exported, so you can render a
-fully custom grid and keep only the `<a-calendar>` form plumbing.
+For a custom month layout, use the exported `buildMonth` and `firstDayOfWeek`
+helpers. See [Build it from elements](#build-it-from-elements).

package/docs/components/input-time.md

@@ -1,33 +1,33 @@
 # 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.
+Use InputTime for a time of day, such as a meeting start or office hours.
+The field provides hour and minute sections, with AM/PM in 12-hour locales.
+Enter digits or use the arrow keys to adjust each section.
+
+The value is a 24-hour `HH:mm` string, or `''` while the time is incomplete.
+Use `defaultValue` for an initial time, or pair `value` with `onValueChange`
+to control it. Add `name` to submit the value with a form.
 
 ## 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.
+Focus a section and enter digits. The caret advances when the section is
+complete. For example, entering `9`, `3`, and `0` produces `09:30`.
+In a 12-hour field, entering `18` sets `6 PM`. The period section accepts its
+localized text or `a` and `p`.
+
+Use the keyboard to adjust or move between sections:
+
+- ↑ and ↓ step the value, wrapping at its limits.
+- ← and → move between sections at the caret boundary.
+- PageUp and PageDown make larger minute adjustments.
+- Backspace in an empty section selects the previous section.
+
+Home, End, selection, deletion, and paste keep their native text-field behavior.
+When one digit cannot grow into a valid two-digit value, the field confirms
+that section and advances. Entering `6` in minutes, for example, sets `06`.
+
+The field sizes to its content. Set `width` when it should fill its container.
+Use `icon` to replace the leading clock, or `icon={false}` to remove it.
 
 ```tsx
 <InputTime label="Start time" defaultValue="09:30" onValueChange={(_, { value }) => save(value)} />
@@ -35,12 +35,13 @@ reads as one field while preserving native caret behavior. In a
 
 ## 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.
+Set `locale` to choose the clock format, section order, separator, and AM/PM
+text. For example, `en-US` uses a 12-hour clock and `de-DE` uses a 24-hour clock.
+Japanese can place the period first, and Finnish uses a dot separator.
+Pass `hour12` or `hour12={false}` to override the locale's clock format.
+
+The period section reserves enough space for either label, so switching AM/PM
+does not change the field's width.
 
 ```tsx
 <InputTime label="US English" locale="en-US" defaultValue="14:05" />   {/* 12-hour: 02 : 05 PM */}
@@ -54,7 +55,7 @@ with a dot (`14.05`), and 24-hour locales drop the AM/PM section entirely. Set
 `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`.
+placeholder dashes. `disabled` prevents focus and editing. `readOnly` keeps the time selectable and focusable while preventing edits.
 
 `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
@@ -66,6 +67,25 @@ range is clamped to the nearest bound as you step or leave the field, and flags
 <InputTime label="Office hours" size="large" min="09:00" max="17:00" defaultValue="09:30" />
 ```
 
+## Controlled values and clearing
+
+Update `value` from `onValueChange` to control the time. An incomplete time reports
+an empty string while the native segments retain the text being edited. Call
+`preventDefault()` in `onClearClick` to keep a value when clearing is disallowed.
+
+```tsx
+const [value, setValue] = useState('09:30')
+const [keep, setKeep] = useState(false)
+
+<InputTime label="Meeting" locale="en-US" value={value} clearable
+  onValueChange={(_, attrs) => setValue(attrs.value)}
+  onClearClick={event => { if (keep) event.preventDefault() }} />
+<Checkbox checked={keep} onStateChange={(_, { next }) => setKeep(next === true)}>
+  Keep the value when clearing
+</Checkbox>
+<Tag>{value || 'Incomplete time'}</Tag>
+```
+
 ## InputTime props
 
 | Prop | Type | Default | Description |
@@ -85,9 +105,11 @@ range is clamped to the nearest bound as you step or leave the field, and flags
 | `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. |
+| `onClearClick?` | (e) => void | — | Fires before clearing. Call `preventDefault()` synchronously to keep the value. |
 | `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. |
+| `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. Read-only blur is silent unless committing an edit made before the field became read-only. |
+| `readOnly?` | boolean | — | Keep the time selectable and focusable while preventing edits. Blur emits `change` only if an edit was pending when the field became read-only. |
 | `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. |
@@ -99,9 +121,28 @@ range is clamped to the nearest bound as you step or leave the field, and flags
 
 ## Web Component
 
-Use the web component directly when you are not using React or Preact and a native control does not fit.
+Use `<a-input-time>` directly outside JSX. Its `label`, `leading`, `clear`,
+`trailing`, and `hint` slots accept field content. Use the `hour`, `minute`, and
+`period` parts to style sections independently of their locale order.
+
+If existing selectors target JSX grouping spans, update them to the
+`a-input-time-label`, `a-input-time-leading`, `a-input-time-clear`,
+`a-input-time-trailing`, and `a-input-time-hint` tags or their slot attributes.
+Raw HTML can keep its existing slot markup.
 
-Slots supply the field label and leading icon.
+For styles and renderer setup, follow [Install and configure](../install-config.md).
+Custom colors and dimensions may require external CSS under a strict
+[Content Security Policy](../install-config.md#content-security-policy).
+
+The canonical value remains `HH:mm`, or an empty string for an incomplete time.
+`input` bubbles and is composed; `change` bubbles on commit. A clear action first
+fires cancelable, bubbling `clearclick`, then `input`, `change`, and `clearinput`
+when accepted. Cancel `clearclick` synchronously to retain the value.
+
+A read-only field emits `change` on blur only for an edit made before it became
+read-only. Partial digits remain visible, with an empty canonical value until
+editing resumes and completes the time. Removing the field while blur settles
+still completes a pending commit, including range clamping on an editable field.
 
 ```html
 <a-input-time name="start-time" defaultvalue="09:30">
@@ -125,9 +166,9 @@ field treatments.
 
 ## 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`,
+Use `status` for feedback color and `tone` for a custom accent. Style the host
+with ordinary CSS and its sections with `::part()`. Unlayered consumer rules
+override Anta's defaults. `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
@@ -142,6 +183,8 @@ targets the localized separator. The element also exposes `field`, `segments`,
 .my-time::part(literal) { color: var(--text-4); }
 ```
 
+The example classes are consumer selectors; replace them with your own.
+
 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: