@antadesign/anta 0.3.34 → 0.3.35

package/dist/components/Expander.js

@@ -1,5 +1,6 @@
-import { Fragment, jsx, jsxs } from "@antadesign/anta/jsx-runtime";
-import { nativeStateChange, neutralToneAttr, toneStyle, roundStyle, roundAttr } from "../anta_helpers";
+import { jsx, jsxs } from "@antadesign/anta/jsx-runtime";
+import { hasChildren, nativeStateChange, neutralToneAttr, toneStyle, roundStyle, roundAttr } from "../anta_helpers";
+import { useNativeEventProps } from "../native-event-props";
 const Expander = ({
   title,
   level,
@@ -20,44 +21,44 @@ const Expander = ({
   ...rest
 }) => {
   const controlled = open !== void 0;
-  const presetIndicator = typeof indicator === "string" && (indicator === "chevron" || indicator === "triangle" || indicator === "plus") ? indicator : void 0;
+  const eventProps = useNativeEventProps({
+    onstatechange: onStateChange ? (e) => {
+      const { event, detail, isOwn } = nativeStateChange(e);
+      if (isOwn && detail)
+        onStateChange(event, {
+          next: detail.next === "open",
+          prev: detail.prev === "open"
+        });
+    } : void 0
+  });
+  const hasActions = hasChildren(actions) && typeof actions !== "boolean" && (typeof actions !== "string" || Boolean(actions.trim()));
+  const presetIndicator = indicator == null ? "chevron" : typeof indicator === "string" && (indicator === "chevron" || indicator === "triangle" || indicator === "plus") ? indicator : void 0;
   const pairedIndicator = indicator != null && typeof indicator === "object" && "closed" in indicator && "open" in indicator ? indicator : void 0;
-  const useCustomSlot = indicator != null && !presetIndicator && !pairedIndicator;
+  const useCustomIndicator = indicator != null && !presetIndicator && !pairedIndicator;
   const customIndicator = typeof indicator === "object" ? indicator : null;
+  const indicatorNodes = pairedIndicator ? [
+    /* @__PURE__ */ jsx("a-expander-indicator", { "data-when": "closed", "aria-hidden": "true", inert: true, children: pairedIndicator.closed }, "indicator-closed"),
+    /* @__PURE__ */ jsx("a-expander-indicator", { "data-when": "open", "aria-hidden": "true", inert: true, children: pairedIndicator.open }, "indicator-open")
+  ] : [/* @__PURE__ */ jsx("a-expander-indicator", { shape: presetIndicator, "aria-hidden": "true", inert: true, children: useCustomIndicator ? customIndicator : null }, "indicator")];
   const computedStyle = roundStyle(round, "--expander-round", toneStyle(tone, "--expander-tone-source", style));
-  const titleNode = typeof title === "object" && title !== null ? /* @__PURE__ */ jsx("span", { slot: "title", style: { display: "contents" }, children: title }) : /* @__PURE__ */ jsx("a-expander-summary", { slot: "title", children: title });
+  const titleNode = typeof title === "object" && title !== null ? /* @__PURE__ */ jsx("a-expander-title", { children: title }, "title") : /* @__PURE__ */ jsx("a-expander-summary", { level: level != null ? String(level) : void 0, children: title }, "title");
+  const actionsNode = hasActions ? /* @__PURE__ */ jsx("a-expander-actions", { children: actions }, "actions") : null;
   return /* @__PURE__ */ jsxs(
     "a-expander",
     {
       state: controlled ? open ? "open" : "closed" : void 0,
       "default-state": !controlled && defaultOpen ? "open" : void 0,
-      level: level != null ? String(level) : void 0,
       tone: neutralToneAttr(tone),
       priority: priority && priority !== "secondary" ? priority : void 0,
       outdent: outdent ? "" : void 0,
       round: roundAttr(round),
       disabled: disabled ? "" : void 0,
-      indicator: presetIndicator,
-      "indicator-placement": indicatorPlacement && indicatorPlacement !== "start" ? indicatorPlacement : void 0,
-      onstatechange: onStateChange ? (e) => {
-        const { event, detail, isOwn } = nativeStateChange(e);
-        if (isOwn && detail)
-          onStateChange(event, {
-            next: detail.next === "open",
-            prev: detail.prev === "open"
-          });
-      } : void 0,
+      ...eventProps,
       class: className,
       style: computedStyle,
       ...rest,
       children: [
-        titleNode,
-        actions != null && /* @__PURE__ */ jsx("span", { slot: "actions", children: actions }),
-        pairedIndicator && /* @__PURE__ */ jsxs(Fragment, { children: [
-          /* @__PURE__ */ jsx("span", { slot: "indicator", "data-when": "closed", "aria-hidden": "true", inert: true, children: pairedIndicator.closed }),
-          /* @__PURE__ */ jsx("span", { slot: "indicator", "data-when": "open", "aria-hidden": "true", inert: true, children: pairedIndicator.open })
-        ] }),
-        useCustomSlot && /* @__PURE__ */ jsx("span", { slot: "indicator", "aria-hidden": "true", inert: true, children: customIndicator }),
+        indicatorPlacement === "end" ? [titleNode, actionsNode, ...indicatorNodes] : [...indicatorNodes, titleNode, actionsNode],
         /* @__PURE__ */ jsx("a-expander-details", { children })
       ]
     }

package/dist/components/Icon.d.ts

@@ -16,26 +16,20 @@ export interface IconProps extends BaseProps {
     label?: string;
 }
 /**
- * Renders an `<a-icon>` web component. Color follows `currentColor`;
- * size is set via the `size` prop (defaults to 16).
+ * Displays an icon in the current text color. Pass `size` for custom dimensions
+ * and `label` when the icon conveys meaning without accompanying text.
  *
- * Requires `@antadesign/anta/elements` to be imported (client-side only)
- * to register the underlying custom element and load the icon
- * stylesheets.
+ * Icon needs CSS without element registration. See
+ * [Install and configure](https://anta.design/install/) for stylesheet setup.
  *
- * @example Decorative icon paired with text — no label needed
+ * @example Decorative icon beside status text
  * ```tsx
- * <button>
- *   <Icon shape="trash" />
- *   Delete
- * </button>
+ * <Text><Icon shape="check" /> Saved</Text>
  * ```
  *
- * @example Meaningful icon-only control — pass a label
+ * @example Standalone icon with an accessible name
  * ```tsx
- * <button aria-label="Delete">
- *   <Icon shape="trash" label="Delete" />
- * </button>
+ * <Icon shape="warning-triangle" label="Warning" />
  * ```
  */
 export declare const Icon: ({ shape, size, label, className, style, ...rest }: IconProps) => any;

package/dist/components/Input.d.ts

@@ -10,40 +10,33 @@ export interface InputChangeAttrs {
     name?: string;
     /** `true` when the value is empty. */
     empty: boolean;
-    /** Whether the field currently passes validation (native + `error`). `undefined`
+    /** Whether the field currently passes validation (native constraints and `status`). `undefined`
      *  where `ElementInternals` is unsupported. */
     valid?: boolean;
     /** Current validation message (`''` when valid). */
     validationMessage: string;
 }
 export interface InputProps extends BaseProps, DOMEventHandlers {
-    /** Extra content rendered directly under the field, above the hint/error (it
-     *  pushes the message down). A no-box child like an Anta `<Tooltip>` takes no
-     *  space and anchors to the field — consistent with how tooltips attach
-     *  to any other element. Use the named `leading` / `trailing` props for
-     *  in-field content. */
+    /** Extra content between the field and hint. A `Tooltip` child anchors to the
+     * field. Use `leading` and `trailing` for content inside the field. */
     children?: React.ReactNode;
-    /** Field label, shown above the control. A string is rendered with the
-     *  label type scale; pass a node for full control. Associated with the
-     *  control as its accessible name (the element mirrors the label text to
-     *  `aria-label`, since `<label for>` can't cross the shadow boundary). */
+    /** Explain what to enter. Accepts text or JSX and also names the field for
+     * screen readers. */
     label?: React.ReactNode;
-    /** Message below the field. Neutral helper text by default; `status` recolors
-     *  it and prefixes the matching glyph. */
+    /** Persistent help or feedback below the field. `status` colors the message and
+     * adds a status icon. */
     hint?: React.ReactNode;
-    /** Validation / feedback tone — colors the border + `hint` and prefixes a
-     *  glyph. Only `critical` marks the field invalid (`aria-invalid`, blocks form
-     *  submission, `:state(invalid)`); `success` / `warning` / `info` / `brand`
-     *  are advisory and stay valid. Omit (or `neutral`) for a plain field. */
+    /** Feedback for the field and hint. Use `critical` for an error that must be
+     * fixed before submission. Other statuses provide feedback without adding a
+     * validation error. Required fields and other validation rules still apply. */
     status?: 'neutral' | 'brand' | 'info' | 'success' | 'warning' | 'critical';
-    /** Glyph shown before the `hint` when `status` is set. Each status has a
-     *  default (critical → `warning-diamond`, warning → `warning-triangle`,
-     *  success → `circle-check`, info → `info`, brand → `circle-small-solid`); pass a
-     *  shape to override, or `false` to drop it. `neutral` has no default glyph. */
+    /** Icon before the hint. The defaults are `warning-diamond` for critical,
+     * `warning-triangle` for warning, `circle-check` for success, `info` for info,
+     * and `circle-small-solid` for brand. Pass a shape to replace it or `false` to
+     * hide it. Neutral has no default icon. */
     statusIcon?: IconShape | (string & {}) | false;
-    /** Custom accent color — any literal CSS color tints the border when shown
-     *  (focus ring stays the global `--focus-ring`). For consistency with the
-     *  other controls' custom-tone knob; a `status` still overrides for validation. */
+    /** Custom CSS border color. A non-neutral `status` takes precedence. The focus
+     * ring uses the global `--focus-ring`. */
     tone?: string;
     /** Field emphasis. `primary` has a fill and border, `secondary` keeps the
      *  border without a fill, and `tertiary` makes the border transparent until
@@ -51,52 +44,49 @@ export interface InputProps extends BaseProps, DOMEventHandlers {
      *  Status borders remain visible at rest.
      *  @defaultValue primary */
     priority?: 'primary' | 'secondary' | 'tertiary';
-    /** Size variant. small=24px, medium=28px, large=32px tall; the type scale and
-     *  icon track the size (small 13/16 + 14px icon · medium 15/20 + 16px ·
-     *  large 17/22 + 18px).
-     *  @defaultValue medium */
+    /** Adjust the field, text, icons, and action buttons together to suit the
+     * surrounding interface.
+     * @defaultValue medium */
     size?: 'small' | 'medium' | 'large';
-    /** Controlled value. Pair with `onChange` / `onInput`. */
+    /** Controlled value. Update it with `onInput` or `onValueChange` for live
+     * editing. */
     value?: string;
-    /** Initial value for the uncontrolled case. */
+    /** Initial value for an uncontrolled field, restored on form reset. */
     defaultValue?: string;
-    /** Render a `<textarea>` instead of an `<input>`. Without `rows` it grows
-     *  with its content from one line (capped by `maxRows` if set). Autogrow uses
-     *  CSS `field-sizing` where supported (Chrome/Edge, Safari ≥ 26.2) and falls
-     *  back to a built-in JS resize elsewhere (Firefox, older Safari), so it grows
-     *  in every browser. */
+    /** Allow longer text and grow the field as someone types. Use `maxRows` to
+     * limit growth or `rows` to keep a fixed height. */
     multiline?: boolean;
-    /** Fixed visible row count — a constant-height `<textarea>` (implies
-     *  `multiline`). */
+    /** Fixed visible row count. Also enables `multiline`. */
     rows?: number;
-    /** Cap the autogrow height (in rows) of a `multiline` field with no `rows`.
-     *  Omit for unbounded growth. */
+    /** Maximum row count for autogrow when `rows` is unset. Omit for unlimited
+     * growth. */
     maxRows?: number;
-    /** Show a clear button as the first trailing item once the field has a
-     *  value. */
+    /** Show a clear button before trailing content when an editable field has a
+     * value. */
     clearable?: boolean;
-    /** Content pinned to the start of the field (e.g. an icon). */
+    /** Content at the start of the field, such as an icon or text. */
     leading?: React.ReactNode;
-    /** Content pinned to the end of the field (e.g. icons, buttons), after the
-     *  clear button when `clearable`. */
+    /** Content at the end of the field, after the clear button. Anta buttons fit
+     * the field height and keep their padding. Icon-only Buttons are square; text
+     * buttons keep their natural width. Pass buttons directly or in
+     * a fragment for compact spacing. Other wrapping elements keep the text inset.
+     * Override either inset with the `--input-trailing-inset` CSS property. */
     trailing?: React.ReactNode;
-    /** Single-line input type. Ignored when `multiline`. `search` is a
-     *  **wrapper-only** shorthand: it defaults a leading search icon and a clear
-     *  button (both overridable — pass your own `leading`, or `clearable={false}`)
-     *  and sets `inputmode="search"`, but the DOM input stays `type="text"`. The
-     *  native `search` type never reaches the element, so the browser's own
-     *  clear/search affordances never appear — Anta owns that chrome.
-     *  @defaultValue text */
+    /** Choose the kind of information to enter. Ignored for multiline fields.
+     * `search` adds a search icon and clear button. Replace the icon with
+     * `leading` or hide the button with `clearable={false}`.
+     * @defaultValue text */
     type?: 'text' | 'search' | 'email' | 'password' | 'tel' | 'url' | 'number';
-    /** Native autocomplete token. Overrides the value derived from `type`
-     *  (`email` / `tel` / `url`) — set it for the cases `type` can't express, e.g.
-     *  `username`, `current-password`, `new-password`, `one-time-code`, or `off`. */
+    /** Native autocomplete token describing the field purpose. Overrides the token
+     * derived from the email, tel, or url type. Set an explicit token for other
+     * purposes, such as `username`, `current-password`, or `one-time-code`. */
     autoComplete?: 'off' | 'on' | 'name' | 'username' | 'email' | 'current-password' | 'new-password' | 'one-time-code' | 'tel' | 'url' | (string & {});
-    /** Virtual-keyboard hint. Overrides the value derived from `type`. */
+    /** Virtual keyboard hint. Overrides the value derived from `type` without
+     * changing validation. */
     inputMode?: 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url';
     /** Focus this field when its containing `Dialog` opens. */
     autoFocus?: boolean;
-    /** Form field name — submitted with the form via ElementInternals. */
+    /** Form field name for submission, named form lookup, and attribute selectors. */
     name?: string;
     /** Placeholder shown when empty. */
     placeholder?: string;
@@ -114,71 +104,62 @@ export interface InputProps extends BaseProps, DOMEventHandlers {
     button?: boolean;
     /** Mark the field required (drives native validity). */
     required?: boolean;
-    /** Dim the `leading` / `trailing` adornments at rest; they brighten to full
-     *  when the field is hovered or focused (a quiet-until-engaged affordance for
-     *  trailing actions). */
+    /** Keep leading, trailing, and clear content subtle until someone hovers over
+     * or focuses the field. */
     dimActions?: boolean;
-    /** Fully-round the field (`border-radius: 999px`). Pass a `number` (px) or a CSS
-     *  length string for a custom radius. The `clearable` × button always rounds to
-     *  a circle to match (it isn't sized by a custom field value). */
+    /** Give the field fully rounded corners. Pass a number in pixels or a CSS
+     * length for a custom radius. The clear button stays circular. */
     round?: boolean | number | string;
     /** Toggle native spell-checking. */
     spellCheck?: boolean;
-    /** Max input length. */
+    /** Maximum text length for native types that support it. */
     maxLength?: number;
-    /** Min input length. */
+    /** Minimum text length for native types that support it. */
     minLength?: number;
-    /** Validation pattern (single-line). */
+    /** Validation pattern for supported single-line types. Checks validity without
+     * preventing typing. */
     pattern?: string;
-    /** Min / max / step — for `type="number"`. */
+    /** Minimum value for `type="number"`. */
     min?: number | string;
+    /** Maximum value for `type="number"`. */
     max?: number | string;
+    /** Allowed increment for `type="number"`. */
     step?: number | string;
-    /** Fires on every keystroke. Read `e.target.value`. */
+    /** Fires when editing changes the value or the field is cleared. Read
+     * `e.target.value`. */
     onInput?: (e: any) => void;
-    /** Fires on **commit** (blur / Enter) — the platform `change` semantics, **not**
-     *  React's per-keystroke `onChange`. This is a web component, so `onChange` keeps
-     *  the native meaning; reach for `onInput` (every keystroke) or `onValueChange`
-     *  (both) for live updates. Read `e.target.value`. */
+    /** Fires on native commit, such as blur or Enter, and on clear. Use `onInput` or
+     * `onValueChange` for live edits. Read `e.target.value`. */
     onChange?: (e: any) => void;
-    /** Unified value-change handler — the easy path for state. Fires on `input`
-     *  *and* `change` (and on clear), with the native `event` plus a convenience
-     *  `attrs` snapshot (`value`, `name`, `empty`, `valid`, `validationMessage`) so
-     *  you can do `setForm(s => ({ ...s, [attrs.name]: attrs.value }))` without
-     *  digging into the event. Use `event.type` to tell a live edit (`input`) from
-     *  a commit (`change`); read `id` / `type` / `className` off `event.target`. */
+    /** Receive the current text, field name, and validation result while editing
+     * and when an edit is committed, including clear. Can run more than once for
+     * the same value. Use `event.type` to distinguish the events. */
     onValueChange?: (event: any, attrs: InputChangeAttrs) => void;
-    /** Fires when the built-in clear button (`clearable`) is clicked, *before*
-     *  the field is cleared. Call `e.preventDefault()` to keep the current value
-     *  — the clear is cancelled and `onClearInput` won't fire. Backed by the
-     *  element's cancelable, bubbling `clearclick` event. */
+    /** Fires before the built-in clear action. Call `e.preventDefault()`
+     * synchronously to keep the value and cancel `onClearInput`. Corresponds to the
+     * cancelable, bubbling `clearclick` event. */
     onClearClick?: (e: CustomEvent) => void;
-    /** Fires after the built-in clear button (`clearable`) has cleared the field
-     *  — so `onInput` / `onChange` fire too — making this useful for reacting
-     *  specifically to a clear. Doesn't fire if `onClearClick` cancelled the
-     *  clear. Backed by the element's bubbling `clearinput` event. */
+    /** Fires after clearing, following `onInput` and `onChange`. Does not fire when
+     * clearing is canceled. Corresponds to the bubbling `clearinput` event. */
     onClearInput?: (e: CustomEvent) => void;
     /** Fires when the field gains focus. */
     onFocus?: (e: any) => void;
     /** Fires when the field loses focus. */
     onBlur?: (e: any) => void;
-    /** ARIA `role` for the field — e.g. `combobox` when the input drives a
-     *  suggestion `listbox` (see `InputAutocomplete`). The custom element
-     *  delegates it, together with standard `aria-*` props, to the focused native
-     *  shadow control. Left unset by default. */
+    /** ARIA role for the native control, such as `combobox` for an InputAutocomplete
+     * trigger. The element delegates this and standard `aria-*` props to its native
+     * shadow control. */
     role?: string;
 }
 /**
- * `<Input>` — a text field. Renders an `<a-input>` web component whose real
- * `<input>` / `<textarea>` lives in shadow DOM, so it's self-contained: focus,
- * forms (via `ElementInternals`), IME, and autofill are all native, and the
- * control is reachable for styling through `::part(input)`.
+ * Text field for single-line or multiline input, with labels, hints, and actions.
+ * Supports native form submission, validation, autofill, and input methods.
+ * Pass `multiline` for a textarea and `clearable` to offer a clear action.
  *
- * The wrapper is stateless — it maps props to attributes and slots. The clear
- * button is dropped into `slot="trailing"`; its click finds the host and calls
- * `clear()`, and its visibility is CSS off the element's `:state(filled)`.
+ * Use `leading` and `trailing` for content inside the field. Style the editable
+ * control through `::part(input)`.
  *
- * Requires `@antadesign/anta/elements` to be imported (client-side only).
+ * See [Install and configure](https://anta.design/install/) for runtime setup.
  *
  * @example
  * ```tsx

package/dist/components/Input.js

@@ -1,15 +1,16 @@
 import { jsx, jsxs } from "@antadesign/anta/jsx-runtime";
+import { CLEAR_TRIGGER } from "../input-events";
 import { nativeStateChange, neutralToneAttr, toneStyle, roundStyle, roundAttr } from "../anta_helpers";
 import { Button } from "./Button";
 import { Icon } from "./Icon";
+import { useNativeEventProps } from "../native-event-props";
 const presence = (on) => on ? "" : void 0;
-const isStringish = (n) => typeof n === "string" || typeof n === "number";
 const attrsOf = (e) => {
   const el = e?.target ?? {};
   const value = el.value ?? "";
   return {
     value,
-    name: el.getAttribute?.("name") ?? void 0,
+    name: el.name || void 0,
     empty: !value,
     valid: el.validity ? el.validity.valid : void 0,
     validationMessage: el.validationMessage ?? ""
@@ -77,6 +78,18 @@ const Input = ({
   style,
   ...rest
 }) => {
+  const eventProps = useNativeEventProps({
+    oninput: onInput || onValueChange ? (e) => {
+      onInput?.(e);
+      onValueChange?.(e, attrsOf(e));
+    } : void 0,
+    onchange: onChange || onValueChange ? (e) => {
+      onChange?.(e);
+      onValueChange?.(e, attrsOf(e));
+    } : void 0,
+    onclearclick: onClearClick ? (e) => onClearClick(nativeStateChange(e).event) : void 0,
+    onclearinput: onClearInput ? (e) => onClearInput(nativeStateChange(e).event) : void 0
+  });
   const statusTone = status && status !== "neutral" ? status : void 0;
   const glyph = statusIcon === void 0 ? statusTone ? STATUS_ICON[statusTone] : void 0 : statusIcon;
   const isSearch = type === "search";
@@ -117,32 +130,15 @@ const Input = ({
       step,
       "aria-invalid": status === "critical" ? "true" : void 0,
       role: role ?? (isSearch ? "searchbox" : void 0),
-      oninput: onInput || onValueChange ? (e) => {
-        onInput?.(e);
-        onValueChange?.(e, attrsOf(e));
-      } : void 0,
-      onchange: onChange || onValueChange ? (e) => {
-        onChange?.(e);
-        onValueChange?.(e, attrsOf(e));
-      } : void 0,
-      onclearclick: onClearClick ? (e) => onClearClick(nativeStateChange(e).event) : void 0,
-      onclearinput: onClearInput ? (e) => onClearInput(nativeStateChange(e).event) : void 0,
+      ...eventProps,
       class: className,
       style: roundStyle(round, "--input-round", toneStyle(tone, "--input-tone-source", style)),
       ...rest,
       children: [
-        label != null && (isStringish(label) ? /* @__PURE__ */ jsx("span", { slot: "label", children: label }) : /* @__PURE__ */ jsx("span", { slot: "label", style: { display: "contents" }, children: label })),
-        resolvedLeading != null && /* @__PURE__ */ jsx("span", { slot: "leading", style: { display: "contents" }, children: resolvedLeading }),
-        resolvedClearable && // A real <a-button> (light DOM → fully styled, keyboard-focusable) in
-        // the element's `clear` slot — the element controls its visibility (shown
-        // only when filled + editable). It fires the bubbling `clearrequest`
-        // event via a-button's global listener, so clearing works even without
-        // framework hydration; the element turns that into clearclick→clear().
-        // CONTRACT: the `data-custom-event` value below MUST match `CLEAR_TRIGGER`
-        // in the element (src/elements/a-input.ts). The string is duplicated, not
-        // shared — importing the element module here would self-register it and
-        // break the wrapper/element decoupling. Rename in both places.
-        /* @__PURE__ */ jsx("span", { slot: "clear", style: { display: "contents" }, children: /* @__PURE__ */ jsx(
+        label != null && /* @__PURE__ */ jsx("a-input-label", { slot: "label", children: label }),
+        resolvedLeading != null && /* @__PURE__ */ jsx("a-input-leading", { slot: "leading", children: resolvedLeading }),
+        resolvedClearable && // The UI element handles the clear lifecycle before framework hydration.
+        /* @__PURE__ */ jsx("a-input-clear", { slot: "clear", children: /* @__PURE__ */ jsx(
           Button,
           {
             priority: "tertiary",
@@ -150,11 +146,11 @@ const Input = ({
             round: !!round,
             icon: "x",
             "aria-label": "Clear",
-            "data-custom-event": "clearrequest"
+            "data-custom-event": CLEAR_TRIGGER
           }
         ) }),
-        trailing != null && /* @__PURE__ */ jsx("span", { slot: "trailing", style: { display: "contents" }, children: trailing }),
-        hint != null && /* @__PURE__ */ jsxs("span", { slot: "hint", style: { display: "contents" }, children: [
+        trailing != null && /* @__PURE__ */ jsx("a-input-trailing", { slot: "trailing", children: trailing }),
+        hint != null && /* @__PURE__ */ jsxs("a-input-hint", { slot: "hint", children: [
           glyph && /* @__PURE__ */ jsx(Icon, { shape: glyph, "aria-hidden": "true" }),
           /* @__PURE__ */ jsx("span", { children: hint })
         ] }),

package/dist/components/InputAutocomplete.d.ts

@@ -1,24 +1,31 @@
-import type { BaseProps } from '../general_types';
+import type { BaseProps, DOMEventHandlers } from '../general_types';
 import type { IconShape } from '../elements/a-icon.shapes';
 import type { SelectOption } from './Select';
-export interface InputAutocompleteProps extends Omit<BaseProps, 'children'> {
+export interface InputAutocompleteProps extends Omit<BaseProps, 'children'>, Omit<DOMEventHandlers, 'onSelect'> {
     /** The suggestions: bare strings or `SelectOption`s (`value` / `label` / `hint` /
      *  `icon` / `tone` / `disabled`). A flat list; picking one fills the field. */
     suggestions: (string | SelectOption)[];
-    /** Controlled value: the field's text, a **free** string not constrained to a
-     *  suggestion. Leave undefined for uncontrolled. */
+    /** The controlled field text. Any string is valid, including `''` for an empty
+     * field. Omit or pass `undefined` for uncontrolled use. Parent updates do not
+     * call `onValueChange`. Releasing control retains the latest controlled text. */
     value?: string;
-    /** Initial value for uncontrolled use. */
+    /** Initial uncontrolled text and the value restored by a form reset. Resetting
+     * an unfocused field does not open suggestions or move focus. */
     defaultValue?: string;
-    /** Fires as the text changes (typing, picking a suggestion, or clearing) with
-     *  the new field text. */
+    /** Reports text changes from typing, picking a suggestion, clearing, or form
+     * reset. */
     onValueChange?: (value: string) => void;
-    /** Fires only when a suggestion is chosen, with that option. */
+    /** Fires after `onValueChange` when a suggestion is chosen, with the normalized
+     * option. This reports the choice even if a controlled parent rejects the value.
+     * Typing and clearing do not call it. */
     onSelect?: (option: SelectOption) => void;
     /** 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.
+     *  boolean` receives the original field text, including whitespace, once per
+     *  option on each render, including when empty. Custom matching has no automatic
+     *  highlighting. `false` shows `suggestions` unchanged for application-provided
+     *  async or remote filtering, without automatic highlighting. Replacing results
+     *  updates an open list but does not reopen a dismissed list.
      *  @defaultValue true */
     filter?: boolean | ((option: SelectOption, query: string) => boolean);
     /** Placeholder text. */
@@ -46,6 +53,18 @@ export interface InputAutocompleteProps extends Omit<BaseProps, 'children'> {
     leading?: React.ReactNode;
     /** Trailing adornment inside the field. */
     trailing?: React.ReactNode;
+    /** Observe focus before the suggestion list opens. */
+    onFocus?: (event: any) => void;
+    /** Observe focus loss. The suggestion list closes without changing the text. */
+    onBlur?: (event: any) => void;
+    /** Observe editing before `onValueChange`. The input event reports text that
+     * has already changed; `preventDefault()` does not reject that text. */
+    onInput?: (event: any) => void;
+    /** Observe keys before the wrapper's plain-Enter dismissal. `preventDefault()`
+     * keeps that dismissal from running. Menu handles navigation and active-option
+     * activation earlier, in document capture; this callback cannot veto those
+     * actions. Composing keys remain with the input method. */
+    onKeyDown?: (event: any) => void;
 }
 /**
  * `<InputAutocomplete>` is a text field with a suggestion dropdown. Its value is

package/dist/components/InputAutocomplete.js

@@ -1,6 +1,6 @@
 import { Fragment, jsx, jsxs } from "@antadesign/anta/jsx-runtime";
 import { useState, useMemo } from "../jsx-runtime";
-import { optionPresentationAttrs } from "../anta_helpers";
+import { isComposingKey, optionPresentationAttrs, useSelectionMirror } from "../anta_helpers";
 import { normalizeOpt, matchQueryRegex, matchesQuery, highlight } from "./select-options";
 import { Input } from "./Input";
 import { Menu } from "./Menu";
@@ -12,13 +12,18 @@ const InputAutocomplete = (props) => {
     defaultValue,
     onValueChange,
     onSelect,
+    onFocus,
+    onBlur,
+    onInput,
+    onKeyDown,
     filter = true,
     ...rest
   } = props;
   const controlled = value !== void 0;
-  const [internal, setInternal] = useState(defaultValue ?? "");
-  const text = controlled ? value : internal;
-  const [open, setOpen] = useState(false);
+  const [mirroredText, setInternal] = useSelectionMirror(value, defaultValue ?? "");
+  const text = mirroredText ?? "";
+  const [{ open }, setPopup] = useState({ open: false, focused: false });
+  const setOpen = (next) => setPopup((prev) => ({ ...prev, open: next }));
   const options = useMemo(() => suggestions.map(normalizeOpt), [suggestions]);
   const custom = typeof filter === "function";
   const queryRe = filter !== false && !custom ? matchQueryRegex(text) : null;
@@ -39,18 +44,29 @@ const InputAutocomplete = (props) => {
       {
         ...rest,
         value: text,
+        defaultValue,
         "data-menu-search": "",
         role: "combobox",
         "aria-haspopup": "listbox",
         "aria-expanded": menuOpen ? "true" : "false",
         "aria-autocomplete": "list",
-        onFocus: () => setOpen(true),
+        onFocus: (e) => {
+          onFocus?.(e);
+          setPopup({ open: true, focused: true });
+        },
+        onBlur: (e) => {
+          onBlur?.(e);
+          setPopup({ open: false, focused: false });
+        },
         onInput: (e) => {
-          setText(e.currentTarget.value);
-          setOpen(true);
+          const next = e.currentTarget.value;
+          onInput?.(e);
+          setText(next);
+          setPopup((prev) => ({ ...prev, open: prev.focused }));
         },
         onKeyDown: (e) => {
-          if (e.key === "Enter" && !e.defaultPrevented) setOpen(false);
+          onKeyDown?.(e);
+          if (e.key === "Enter" && !e.defaultPrevented && !isComposingKey(e)) setOpen(false);
         }
       }
     ),
@@ -69,6 +85,7 @@ const InputAutocomplete = (props) => {
             {
               ...optionAttrs,
               role: "option",
+              tabIndex: -1,
               icon: opt.icon,
               label: highlight(opt.label ?? opt.value, queryRe),
               hint: opt.hint ? highlight(opt.hint, queryRe) : opt.hint,

package/dist/components/InputDate.js

@@ -1,6 +1,6 @@
 import { Fragment, jsx, jsxs } from "@antadesign/anta/jsx-runtime";
 import { useMemo, useState } from "../jsx-runtime";
-import { isModifiedNavigationKey } from "../anta_helpers";
+import { isModifiedNavigationKey, unwrapNativeEvent } from "../anta_helpers";
 import { Temporal } from "temporal-polyfill";
 import {
   parseISODate,
@@ -195,7 +195,7 @@ const InputDate = ({
                 "aria-label": "Time",
                 value: hasTime ? `${String(h24).padStart(2, "0")}:${curM}` : "",
                 onValueChange: (e, { value: t }) => {
-                  const ev = "nativeEvent" in e ? e.nativeEvent : e;
+                  const ev = unwrapNativeEvent(e);
                   if (ev?.type !== "change") return;
                   const base = dateISO || Temporal.Now.plainDateISO().toString();
                   commit(t ? `${base}T${t}` : base);