@antadesign/anta 0.2.2 → 0.3.0

package/README.md

@@ -203,3 +203,17 @@ To use the Antithesis fonts, register your own `@font-face` declarations and ove
   --monospace: "Antithesis mono", monospace;
 }
 ```
+
+## Browser support
+
+Anta targets evergreen browsers and ships **no polyfills and no feature detection** for its baseline. The floor is set by the [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) (used by `<a-menu>` and `<a-tooltip>` for top-layer rendering):
+
+| Browser | Minimum version |
+| --- | --- |
+| Chrome / Edge | 114 (May 2023) |
+| Safari | 17 (Sep 2023) |
+| Firefox | 125 (Apr 2024) |
+
+This corresponds roughly to [Baseline 2024](https://web.dev/baseline). Within that floor, anta freely relies on: `popover` / `showPopover()` / `:popover-open`, `color-mix(in oklch, …)` and relative `oklch(from …)` colors, `:has()`, `dvh` units, CSS cascade layers, and constructable shadow DOM. On an older browser these fail hard (e.g. `showPopover()` throws) — there is no degraded mode by design; gate anta usage on your own support matrix instead.
+
+Two features are used as **progressive enhancement** with explicit fallbacks: `checkVisibility()` (falls back to `getClientRects()`), and CSS typed `attr()` for `<a-icon size>` (Chrome 133+ / Safari 18.2+; elsewhere use the `<Icon size>` wrapper or the `--icon-size` variable, see the `a-icon` docs).

package/dist/anta_helpers.d.ts

@@ -1,4 +1,26 @@
 export declare function hasChildren(children: React.ReactNode): boolean;
+/**
+ * Unwrap a `statechange` (or any) `CustomEvent` a renderer may deliver wrapped:
+ * React hands a synthetic event with the real one on `.nativeEvent`; Preact passes
+ * the native event directly. Returns the native event and its `detail`. Shared by
+ * every stateful wrapper (`Menu`, `Expander`, `Checkbox`, `RadioGroup`) — don't
+ * re-implement it per component.
+ */
+export declare function nativeStateChange<D>(e: CustomEvent<D> | {
+    nativeEvent: CustomEvent<D>;
+}): {
+    event: CustomEvent<D>;
+    detail?: D;
+};
+/** The six named tones every toned component shares. Anything else is a literal
+ *  CSS colour the element resolves through its `--{component}-tone-source` var. */
+export declare const NAMED_TONES: Set<string>;
+/**
+ * Inline-style helper for a custom (non-named) tone: hands the literal colour to
+ * the element via `varName` (e.g. `--radio-tone-source`) so the element's CSS
+ * derives the fill/text/border curve in oklch. Named tones return `base` unchanged.
+ */
+export declare function toneStyle(tone: string | undefined, varName: string, base?: React.CSSProperties): React.CSSProperties | undefined;
 /**
  * `HTMLElement` in browsers, a noop class in Node/Worker environments.
  * Use this as the base for custom element classes so importing the
@@ -6,4 +28,20 @@ export declare function hasChildren(children: React.ReactNode): boolean;
  * Instantiation in non-DOM environments still fails, but no consumer
  * should be doing that.
  */
-export declare const HTMLElementBase: typeof HTMLElement;
+declare const NativeHTMLElement: typeof HTMLElement;
+/**
+ * Base for Anta custom elements. Adds realm-correct `view` / `doc` getters:
+ * the class may be defined in one realm while the element lives in another
+ * (the docs playground renders into an iframe but reuses the parent page's
+ * element class), so the module-global `window` / `document` can point at the
+ * wrong frame. Anything viewport- or document-scoped — clamping,
+ * `getComputedStyle`, scroll / key / pointer listeners — must go through these
+ * so it's correct in any frame. Shared by a-tooltip and a-menu.
+ */
+export declare class HTMLElementBase extends NativeHTMLElement {
+    /** This element's own window (the iframe's window when nested). */
+    protected get view(): Window & typeof globalThis;
+    /** This element's own document (the iframe's document when nested). */
+    protected get doc(): Document;
+}
+export {};

package/dist/anta_helpers.js

@@ -1,9 +1,37 @@
 function hasChildren(children) {
   return Array.isArray(children) ? children.length > 0 : children != null;
 }
-const HTMLElementBase = typeof HTMLElement !== "undefined" ? HTMLElement : class {
+function nativeStateChange(e) {
+  const event = "nativeEvent" in e ? e.nativeEvent : e;
+  return { event, detail: event?.detail };
+}
+const NAMED_TONES = /* @__PURE__ */ new Set([
+  "brand",
+  "neutral",
+  "info",
+  "success",
+  "warning",
+  "critical"
+]);
+function toneStyle(tone, varName, base) {
+  return tone != null && !NAMED_TONES.has(tone) ? { ...base, [varName]: tone } : base;
+}
+const NativeHTMLElement = typeof HTMLElement !== "undefined" ? HTMLElement : class {
 };
+class HTMLElementBase extends NativeHTMLElement {
+  /** This element's own window (the iframe's window when nested). */
+  get view() {
+    return this.ownerDocument?.defaultView ?? window;
+  }
+  /** This element's own document (the iframe's document when nested). */
+  get doc() {
+    return this.ownerDocument ?? document;
+  }
+}
 export {
   HTMLElementBase,
-  hasChildren
+  NAMED_TONES,
+  hasChildren,
+  nativeStateChange,
+  toneStyle
 };

package/dist/components/Button.d.ts

@@ -7,13 +7,14 @@ export type BaseButtonProps = {
      *  tertiary, and quaternary take its hue and pin lightness/chroma to the
      *  brand curve so any input stays legible.
      *  @defaultValue neutral */
-    tone?: 'neutral' | 'brand' | 'critical' | 'info' | 'success' | 'warning' | (string & {});
+    tone?: 'neutral' | 'brand' | 'info' | 'success' | 'warning' | 'critical' | (string & {});
     /** Size variant. small=24px, medium=28px, large=32px. Omit the
      *  attribute or pass `'medium'` for the default — both render
      *  identically and emit no DOM attribute.
      *  @defaultValue medium */
     size?: 'small' | 'medium' | 'large';
-    /** Show a rotating loading indicator. Blocks clicks. */
+    /** Show a rotating loading indicator. Blocks clicks and keyboard
+     *  activation, and removes the button from the tab order while active. */
     loading?: boolean;
     /** Disable the button. */
     disabled?: boolean;
@@ -22,8 +23,10 @@ export type BaseButtonProps = {
     /** Click handler. */
     onClick?: (e: any) => void;
     /** Tab order. The button is keyboard-focusable by default (`0`) and
-     *  becomes `-1` automatically while `disabled` — `<a-button>` and
-     *  `<a role="button">` aren't focusable without an explicit tabindex.
+     *  becomes `-1` automatically while `disabled` or `loading` — `<a-button>`
+     *  and `<a role="button">` aren't focusable without an explicit tabindex,
+     *  and a loading button must stay out of the tab order so Enter/Space can't
+     *  fire it mid-flight.
      *  @defaultValue 0 */
     tabIndex?: number;
 };

package/dist/components/Button.js

@@ -1,12 +1,5 @@
 import { Fragment, jsx, jsxs } from "@antadesign/anta/jsx-runtime";
-const NAMED_TONES = /* @__PURE__ */ new Set([
-  "brand",
-  "neutral",
-  "critical",
-  "info",
-  "success",
-  "warning"
-]);
+import { toneStyle } from "../anta_helpers";
 const wrapChildren = (kids) => {
   if (kids == null) return kids;
   const arr = Array.isArray(kids) ? kids : [kids];
@@ -42,8 +35,7 @@ const Button = ({
   ...rest
 }) => {
   const toneAttr = tone || void 0;
-  const isCustomTone = toneAttr != null && !NAMED_TONES.has(toneAttr);
-  const computedStyle = isCustomTone ? { ...style, ["--button-tone-source"]: toneAttr } : style;
+  const computedStyle = toneStyle(toneAttr, "--button-tone-source", style);
   const isIconOnly = icon != null && label == null && children == null && iconTrailing == null;
   const sharedAttrs = {
     priority,
@@ -60,7 +52,10 @@ const Button = ({
     loading: loading ? "" : void 0,
     disabled: disabled ? "" : void 0,
     selected: selected ? "" : void 0,
-    tabIndex: disabled ? -1 : 0,
+    // Disabled AND loading both leave the keyboard tab order — a loading
+    // button blocks the mouse (pointer-events), so it must block Enter/Space
+    // activation too, else the loading guard would be mouse-only.
+    tabIndex: disabled || loading ? -1 : 0,
     "aria-disabled": disabled || loading ? "true" : void 0,
     "aria-busy": loading ? "true" : void 0,
     "aria-pressed": selected ? "true" : void 0,

package/dist/components/Checkbox.d.ts

@@ -0,0 +1,97 @@
+import type { BaseProps } from "../general_types";
+/** The wrapper-level checked value: a boolean for the binary axis, the string
+ *  `'indeterminate'` for the third state. Mirrors Radix's `Checkbox.Root`. */
+export type CheckboxValue = boolean | 'indeterminate';
+/** The element-level state enum (the string vocabulary on `<a-checkbox>`'s
+ *  `state` / `default-state` attributes and its `statechange` event detail). */
+type CheckboxState = 'checked' | 'unchecked' | 'indeterminate';
+/** The element's `statechange` event payload. */
+type StateDetail = {
+    next: CheckboxState;
+    prev: CheckboxState;
+};
+type StateChangeEvent = CustomEvent<StateDetail>;
+/** Snapshot passed as the 2nd argument to `onAnyChange` — the new value plus
+ *  form-relevant fields, so you don't poke at `event.target`. Mirrors `Input`'s
+ *  `onAnyChange` convention. */
+export interface CheckboxChangeAttrs {
+    checked: boolean;
+    indeterminate: boolean;
+    name?: string;
+    value: string;
+}
+export interface CheckboxProps extends BaseProps {
+    /** Visible label — the *value* of the checkbox (clicked along with the box).
+     *  Convenience for the common single-string case; for richer content (markup,
+     *  a link, an info icon) use `children`. When both are supplied, `label`
+     *  renders first. Required unless `children` or `aria-label` is provided
+     *  (a `role="checkbox"` takes its name from the author, not the markup). */
+    label?: string;
+    /** Secondary text rendered under the label — explanatory copy, like
+     *  Input's hint. Not part of the accessible name. */
+    hint?: React.ReactNode;
+    /** Controlled checked state. When provided the checkbox is controlled — it
+     *  renders exactly this and never self-applies; `onStateChange` is a *request*
+     *  the consumer accepts by updating this prop. Use `defaultChecked` for an
+     *  uncontrolled checkbox. `'indeterminate'` shows the minus glyph and takes
+     *  visual precedence; clicking it requests `true`. */
+    checked?: CheckboxValue;
+    /** Initial checked state for an uncontrolled checkbox. Read once; later
+     *  changes ignored (the element then owns the state).
+     *  @defaultValue false */
+    defaultChecked?: CheckboxValue;
+    /** Disable the checkbox (no interaction, dropped from the tab order). */
+    disabled?: boolean;
+    /** Form field name. Inside a `<form>` the checkbox submits under this name,
+     *  contributing `value` when checked — like a native checkbox. */
+    name?: string;
+    /** Value submitted with the form when checked — like a native checkbox.
+     *  @defaultValue "on" */
+    value?: string;
+    /** Colour variant, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`)
+     *  for a one-off custom tone. Tints fill, label, hint, and the unselected box
+     *  border. Named tones track light/dark mode automatically via the theme-aware
+     *  role tokens; a custom colour keeps its hue + chroma and pins lightness to the
+     *  fill curve.
+     *  @defaultValue 'neutral' */
+    tone?: 'brand' | 'neutral' | 'info' | 'success' | 'warning' | 'critical' | (string & {});
+    /** Size variant. small=14px, medium=16px, large=18px box.
+     *  @defaultValue 'medium' */
+    size?: 'small' | 'medium' | 'large';
+    /** Visual priority. `primary` fills the checked box with the tone colour and
+     *  draws a white checkmark; `secondary` keeps the box unfilled and draws the
+     *  border + checkmark in the tone colour (an outlined look).
+     *  @defaultValue 'primary' */
+    priority?: 'primary' | 'secondary';
+    /** Fired on click / Space *before* the element applies any change. Event-first
+     *  so `event.preventDefault()` is the synchronous veto (uncontrolled mode);
+     *  `detail` carries `{ next, prev }`. In controlled mode the element never
+     *  self-applies — answer by updating `checked`, reject by doing nothing. */
+    onStateChange?: (event: StateChangeEvent, detail: {
+        next: CheckboxValue;
+        prev: CheckboxValue;
+    }) => void;
+    /** Fired *after* the checked state changes — a native `change` event (the
+     *  post-apply counterpart to `onStateChange`). Not cancelable. For a controlled
+     *  checkbox this fires once you've updated `checked`. */
+    onChange?: (event: Event) => void;
+    /** Like `onChange`, but with a `{ checked, indeterminate, name, value }` snapshot
+     *  as the 2nd argument — the ergonomic "just give me the new value" callback
+     *  (mirrors `Input`'s `onAnyChange`). */
+    onAnyChange?: (event: Event, attrs: CheckboxChangeAttrs) => void;
+}
+/**
+ * Checkbox. Renders an `<a-checkbox>` web component that owns the visual
+ * state; controlled via `checked` + `onStateChange`, or uncontrolled via
+ * `defaultChecked`. Label is `label` (or `children`); `hint` adds secondary
+ * text under the label. Requires `@antadesign/anta/elements`.
+ *
+ * ```tsx
+ * <Checkbox checked={agreed} onStateChange={(e, { next }) => setAgreed(next)}>
+ *   I agree
+ * </Checkbox>
+ * <Checkbox defaultChecked label="Remember me" hint="On this device" />
+ * ```
+ */
+export declare const Checkbox: ({ checked, defaultChecked, disabled, tone, size, priority, onStateChange, onChange, onAnyChange, label, hint, className, style, children, tabIndex, ...rest }: CheckboxProps) => any;
+export {};

package/dist/components/Checkbox.js

@@ -0,0 +1,77 @@
+import { jsx, jsxs } from "@antadesign/anta/jsx-runtime";
+import { nativeStateChange, toneStyle } from "../anta_helpers";
+const valueToState = (v) => v === "indeterminate" ? "indeterminate" : v ? "checked" : "unchecked";
+const stateToValue = (s) => s === "indeterminate" ? "indeterminate" : s === "checked";
+const checkboxAttrsOf = (el) => ({
+  checked: !!el?.checked,
+  indeterminate: !!el?.indeterminate,
+  name: el?.getAttribute?.("name") ?? void 0,
+  value: el?.getAttribute?.("value") ?? "on"
+});
+const Checkbox = ({
+  checked,
+  defaultChecked,
+  disabled,
+  tone,
+  size,
+  priority,
+  onStateChange,
+  onChange,
+  onAnyChange,
+  label,
+  hint,
+  className,
+  style,
+  children,
+  tabIndex,
+  ...rest
+}) => {
+  const computedStyle = toneStyle(tone, "--checkbox-tone-source", style);
+  const explicitAriaLabel = rest["aria-label"];
+  const ariaLabel = (typeof explicitAriaLabel === "string" ? explicitAriaLabel : void 0) ?? label ?? (typeof children === "string" ? children : void 0);
+  const onstatechange = onStateChange ? (e) => {
+    const { event, detail } = nativeStateChange(e);
+    if (!detail) return;
+    onStateChange(event, {
+      next: stateToValue(detail.next),
+      prev: stateToValue(detail.prev)
+    });
+  } : void 0;
+  const onchange = onChange || onAnyChange ? (e) => {
+    onChange?.(e);
+    onAnyChange?.(e, checkboxAttrsOf(e.currentTarget));
+  } : void 0;
+  const stateAttr = checked !== void 0 ? valueToState(checked) : void 0;
+  const defaultStateAttr = checked === void 0 && defaultChecked !== void 0 ? valueToState(defaultChecked) : void 0;
+  const hasLabel = label != null || children != null;
+  return /* @__PURE__ */ jsxs(
+    "a-checkbox",
+    {
+      role: "checkbox",
+      "aria-disabled": disabled ? "true" : void 0,
+      "aria-label": ariaLabel,
+      ...rest,
+      state: stateAttr,
+      "default-state": defaultStateAttr,
+      disabled: disabled ? "" : void 0,
+      tone: tone && tone !== "neutral" ? tone : void 0,
+      size: size && size !== "medium" ? size : void 0,
+      priority: priority && priority !== "primary" ? priority : void 0,
+      tabIndex: disabled ? -1 : tabIndex ?? 0,
+      onstatechange,
+      onchange,
+      class: className,
+      style: computedStyle,
+      children: [
+        hasLabel && /* @__PURE__ */ jsxs("a-checkbox-label", { children: [
+          label,
+          children
+        ] }),
+        hint != null && /* @__PURE__ */ jsx("a-checkbox-hint", { children: hint })
+      ]
+    }
+  );
+};
+export {
+  Checkbox
+};

package/dist/components/Expander.d.ts

@@ -0,0 +1,74 @@
+import type { BaseProps } from "../general_types";
+/** Public props for the `<Expander>` disclosure. `title` is the always-
+ *  visible summary; `children` is the collapsible body. */
+export interface ExpanderProps extends Omit<BaseProps, "title"> {
+    /** Summary (header) content. A string is rendered with the `level`
+     *  type scale; pass a node (e.g. a `<Title>`) for full control or real
+     *  heading semantics in the document outline. */
+    title: React.ReactNode;
+    /** Heading type scale applied to a string `title` (mirrors `<Title>`'s
+     *  levels). Visual only — for outline semantics, pass a `<Title>` as
+     *  the title.
+     *  @defaultValue 5 */
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Semantic tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`)
+     *  for a one-off custom tone. Named tones re-point the text and (on filled
+     *  priorities) the surface to the matching palette; a custom color keeps
+     *  its hue while lightness/chroma are pinned. `'neutral'` (the default) is
+     *  the same as omitting it.
+     *  @defaultValue 'neutral' */
+    tone?: "neutral" | "brand" | "info" | "success" | "warning" | "critical" | (string & {});
+    /** Surface emphasis. `secondary` (the default) is a subtle fill;
+     *  `primary` is a more pronounced card; `tertiary` is transparent (the
+     *  bare disclosure).
+     *  @defaultValue 'secondary' */
+    priority?: "primary" | "secondary" | "tertiary";
+    /** Outdent the chevron into the left gutter so the title and body sit
+     *  flush with surrounding content (the docs-header layout). Only takes
+     *  effect with `priority="tertiary"` — on the filled priorities the
+     *  container edge has to bound the chevron, so it's a no-op there. */
+    outdent?: boolean;
+    /** Header actions (e.g. buttons, tags) rendered at the end of the
+     *  header row, OUTSIDE the toggle trigger — clicking them never
+     *  toggles, they're separately focusable, and screen readers see them
+     *  as separate controls. */
+    actions?: React.ReactNode;
+    /** Disables the header: not clickable or focusable, hover affordance
+     *  off, text dimmed. The open state freezes as-is — disabling an open
+     *  expander keeps it open. `actions` stay live; disable them
+     *  separately if needed. */
+    disabled?: boolean;
+    /** Controlled open state. When provided, the consumer owns open/close:
+     *  the expander only follows this prop, and clicking the summary just
+     *  requests a change via `onStateChange` (so a toggle can be rejected by
+     *  not updating). Leave undefined for uncontrolled. */
+    open?: boolean;
+    /** Initial open state for the uncontrolled case. */
+    defaultOpen?: boolean;
+    /** Fired before the open state changes. `event` is the cancelable
+     *  `statechange` — call `event.preventDefault()` to veto an *uncontrolled*
+     *  toggle (e.g. confirm before closing). `detail.next` is the requested
+     *  open state, `detail.prev` the current one (booleans). In controlled
+     *  mode, apply `detail.next` to `open` to accept, or do nothing to reject. */
+    onStateChange?: (event: CustomEvent, detail: {
+        next: boolean;
+        prev: boolean;
+    }) => void;
+}
+/**
+ * `<Expander>` — a collapsible disclosure section.
+ *
+ * A pure, stateless pass-through to `<a-expander>`: the element owns all
+ * interaction (toggle, keyboard, ARIA, animation), so the wrapper holds
+ * no state and grabs no ref — it only maps props to attributes (safe
+ * wherever the host DOM is reconciled, incl. off the UI thread).
+ *
+ * Uncontrolled (`defaultOpen`): the element owns its open state. The wrapper
+ * emits `default-state="open"` — never `state` — so the DOM carries no stale
+ * controlled attribute. Controlled (`open` + `onStateChange`): the wrapper
+ * emits `state="open" | "closed"`; the element treats the attribute as the
+ * source of truth and clicks only dispatch the cancelable `statechange` event,
+ * giving real controlled semantics (a consumer can reject a toggle). See
+ * STATEFUL-COMPONENTS.md.
+ */
+export declare const Expander: ({ title, level, tone, priority, outdent, actions, disabled, open, defaultOpen, onStateChange, className, style, children, ...rest }: ExpanderProps) => any;

package/dist/components/Expander.js

@@ -0,0 +1,53 @@
+import { jsx, jsxs } from "@antadesign/anta/jsx-runtime";
+import { nativeStateChange, toneStyle } from "../anta_helpers";
+const Expander = ({
+  title,
+  level,
+  tone,
+  priority,
+  outdent,
+  actions,
+  disabled,
+  open,
+  defaultOpen,
+  onStateChange,
+  className,
+  style,
+  children,
+  ...rest
+}) => {
+  const controlled = open !== void 0;
+  const computedStyle = 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 });
+  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: tone && tone !== "neutral" ? tone : void 0,
+      priority: priority && priority !== "secondary" ? priority : void 0,
+      outdent: outdent ? "" : void 0,
+      disabled: disabled ? "" : void 0,
+      onstatechange: onStateChange ? (e) => {
+        const { event, detail } = nativeStateChange(e);
+        if (detail)
+          onStateChange(event, {
+            next: detail.next === "open",
+            prev: detail.prev === "open"
+          });
+      } : void 0,
+      class: className,
+      style: computedStyle,
+      ...rest,
+      children: [
+        titleNode,
+        actions != null && /* @__PURE__ */ jsx("span", { slot: "actions", style: { display: "contents" }, children: actions }),
+        /* @__PURE__ */ jsx("a-expander-details", { children })
+      ]
+    }
+  );
+};
+export {
+  Expander
+};

package/dist/components/Input.d.ts

@@ -0,0 +1,159 @@
+import type { BaseProps, DOMEventHandlers } from '../general_types';
+import type { IconShape } from '../elements/a-icon.shapes';
+/** Convenience snapshot passed as the 2nd argument to `onAnyChange`. */
+export interface InputChangeAttrs {
+    /** Current value. */
+    value: string;
+    /** The field's `name` — handy for keyed updates: `s => ({ ...s, [name]: value })`.
+     *  The one caller-provided field carried here, for that pattern; read anything
+     *  else (`id`, `type`, `className`) off `event.target`. */
+    name?: string;
+    /** `true` when the value is empty. */
+    empty: boolean;
+    /** Whether the field currently passes validation (native + `error`). `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 just anchors to the field — consistent with how tooltips attach
+     *  to any other element. Use the named `leading` / `trailing` props for
+     *  in-field content. */
+    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). */
+    label?: React.ReactNode;
+    /** Message below the field. Neutral helper text by default; `status` recolors
+     *  it and prefixes the matching glyph. */
+    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. */
+    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. */
+    statusIcon?: IconShape | (string & {}) | false;
+    /** Custom accent colour — any literal CSS colour tints the resting + hover
+     *  border (focus ring stays the global `--focus-ring`). For consistency with the
+     *  other controls' custom-tone knob; a `status` still overrides for validation. */
+    tone?: string;
+    /** 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/24 + 18px).
+     *  @defaultValue medium */
+    size?: 'small' | 'medium' | 'large';
+    /** Controlled value. Pair with `onChange` / `onInput`. */
+    value?: string;
+    /** Initial value for the uncontrolled case. */
+    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. */
+    multiline?: boolean;
+    /** Fixed visible row count — a constant-height `<textarea>` (implies
+     *  `multiline`). */
+    rows?: number;
+    /** Cap the autogrow height (in rows) of a `multiline` field with no `rows`.
+     *  Omit for unbounded growth. */
+    maxRows?: number;
+    /** Show a clear button as the first trailing item once the field has a
+     *  value. */
+    clearable?: boolean;
+    /** Content pinned to the start of the field (e.g. an icon). */
+    leading?: React.ReactNode;
+    /** Content pinned to the end of the field (e.g. icons, buttons), after the
+     *  clear button when `clearable`. */
+    trailing?: React.ReactNode;
+    /** Single-line input type. Ignored when `multiline`. (`search` is omitted
+     *  deliberately — it triggers browser-injected clear/search affordances.)
+     *  @defaultValue text */
+    type?: 'text' | '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`. */
+    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`. */
+    inputMode?: 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url';
+    /** Form field name — submitted with the form via ElementInternals. */
+    name?: string;
+    /** Placeholder shown when empty. */
+    placeholder?: string;
+    /** Disable the field. */
+    disabled?: boolean;
+    /** Make the field read-only. */
+    readOnly?: 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). */
+    dimActions?: boolean;
+    /** Toggle native spell-checking. */
+    spellCheck?: boolean;
+    /** Max input length. */
+    maxLength?: number;
+    /** Min input length. */
+    minLength?: number;
+    /** Validation pattern (single-line). */
+    pattern?: string;
+    /** Min / max / step — for `type="number"`. */
+    min?: number | string;
+    max?: number | string;
+    step?: number | string;
+    /** Fires on every keystroke. 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 `onAnyChange`
+     *  (both) for live updates. 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`. */
+    onAnyChange?: (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. */
+    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. */
+    onClearInput?: (e: CustomEvent) => void;
+    /** Fires when the field gains focus. */
+    onFocus?: (e: any) => void;
+    /** Fires when the field loses focus. */
+    onBlur?: (e: any) => void;
+}
+/**
+ * `<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)`.
+ *
+ * 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)`.
+ *
+ * Requires `@antadesign/anta/elements` to be imported (client-side only).
+ *
+ * @example
+ * ```tsx
+ * <Input label="Email" type="email" placeholder="you@example.com" clearable />
+ * ```
+ */
+export declare const Input: ({ label, hint, status, statusIcon, tone, size, value, defaultValue, multiline, rows, maxRows, clearable, leading, trailing, type, autoComplete, inputMode, name, placeholder, disabled, readOnly, required, dimActions, spellCheck, maxLength, minLength, pattern, min, max, step, onInput, onChange, onAnyChange, onClearClick, onClearInput, children, className, style, ...rest }: InputProps) => any;