@antadesign/anta 0.3.4 → 0.3.6

package/dist/components/InputDate.js

@@ -17,7 +17,7 @@ import { Menu } from "./Menu";
 import { Calendar } from "./Calendar";
 import { Button } from "./Button";
 import { Icon } from "./Icon";
-import { Tabs } from "./Tabs";
+import { InputTime } from "./InputTime";
 import styles from "./InputDate.module.css";
 const InputDate = ({
   value,
@@ -67,47 +67,21 @@ const InputDate = ({
   const hasTime = !!current && current.length >= 16 && current[10] === "T";
   const h24 = hasTime ? parseInt(current.slice(11, 13), 10) || 0 : 0;
   const curM = hasTime ? current.slice(14, 16) : "00";
-  const curMer = h24 < 12 ? "AM" : "PM";
-  const curHourShown = twelveHour ? String((h24 + 11) % 12 + 1).padStart(2, "0") : String(h24).padStart(2, "0");
   const [text, setText] = useState(() => fmt(current));
   const [open, setOpen] = useState(false);
   const [invalid, setInvalid] = useState(false);
   const [focusNonce, setFocusNonce] = useState(0);
-  const [hourText, setHourText] = useState(curHourShown);
-  const [minuteText, setMinuteText] = useState(curM);
-  const meridiem = curMer;
   const [lastValue, setLastValue] = useState(current);
   if (current !== lastValue) {
     setLastValue(current);
     setText(fmt(current));
     setInvalid(false);
   }
-  const [lastTime, setLastTime] = useState(`${h24}:${curM}`);
-  if (time && `${h24}:${curM}` !== lastTime) {
-    setLastTime(`${h24}:${curM}`);
-    setHourText(curHourShown);
-    setMinuteText(curM);
-  }
   const commit = (iso) => {
     if (!controlled) setInternal(iso || void 0);
     onValueChange?.(iso, { value: iso, name });
   };
-  const clampPad = (v, hi) => String(Math.min(Math.max(parseInt(String(v || "0"), 10) || 0, 0), hi)).padStart(2, "0");
-  const resolveHour = (raw, mer) => {
-    let n = parseInt(String(raw || "0"), 10) || 0;
-    if (!twelveHour) {
-      const h = Math.min(Math.max(n, 0), 23);
-      return { h24: h, shown: String(h).padStart(2, "0"), mer };
-    }
-    if (n === 0) return { h24: 0, shown: "12", mer: "AM" };
-    if (n > 23) n = 23;
-    if (n > 12) return { h24: n, shown: String(n - 12).padStart(2, "0"), mer: "PM" };
-    return { h24: mer === "AM" ? n % 12 : n % 12 + 12, shown: String(n).padStart(2, "0"), mer };
-  };
-  const withTime = (d) => {
-    const { h24: h } = resolveHour(hourText, meridiem);
-    return `${d}T${String(h).padStart(2, "0")}:${clampPad(minuteText, 59)}`;
-  };
+  const withTime = (d) => `${d}T${String(h24).padStart(2, "0")}:${curM}`;
   const apply = (iso) => {
     setInvalid(false);
     if (iso === (current ?? "")) setText(fmt(iso));
@@ -119,24 +93,25 @@ const InputDate = ({
       setInvalid(false);
       if (current) commit("");
       else setText("");
-      return;
+      return true;
     }
     const parsed = time ? parseDateTimeInput(t, resolvedLocale, { min: minD, max: maxD }) : parseDateInput(t, resolvedLocale, { min: minD, max: maxD });
     if (!parsed) {
       setInvalid(true);
-      return;
+      return false;
     }
     const iso = time ? parsed.toString({ smallestUnit: "minute" }) : parsed.toString();
     apply(iso);
+    return true;
   };
-  const commitTime = (hRaw, mRaw, mer) => {
-    const { h24: h, shown } = resolveHour(hRaw, mer);
-    const mm = clampPad(mRaw, 59);
-    setHourText(shown);
-    setMinuteText(mm);
-    const base = dateISO || Temporal.Now.plainDateISO().toString();
-    commit(`${base}T${String(h).padStart(2, "0")}:${mm}`);
-  };
+  const parsedPreview = useMemo(() => {
+    const t = text.trim();
+    if (!t) return dateISO;
+    const parsed = time ? parseDateTimeInput(t, resolvedLocale, { min: minD, max: maxD }) : parseDateInput(t, resolvedLocale, { min: minD, max: maxD });
+    return parsed ? parsed.toString().slice(0, 10) : null;
+  }, [text, time, resolvedLocale, dateISO, min, max]);
+  const [previewISO, setPreviewISO] = useState(dateISO);
+  if (parsedPreview !== null && parsedPreview !== previewISO) setPreviewISO(parsedPreview);
   return /* @__PURE__ */ jsxs(Fragment, { children: [
     /* @__PURE__ */ jsx(
       Input,
@@ -148,7 +123,7 @@ const InputDate = ({
         round,
         disabled,
         clearable,
-        leading: /* @__PURE__ */ jsx(Icon, { shape: icon ?? "calendar-days" }),
+        leading: icon === false ? void 0 : /* @__PURE__ */ jsx(Icon, { shape: icon ?? "calendar-days" }),
         value: text,
         placeholder: pattern,
         inputMode: time ? "text" : "numeric",
@@ -166,6 +141,10 @@ const InputDate = ({
             if (!open) e.currentTarget.click();
             setFocusNonce((n) => n + 1);
           }
+          if (e.key === "Enter" && !disabled) {
+            e.preventDefault();
+            if (resolve(e.currentTarget.value)) setOpen(false);
+          }
         },
         className: cn(styles.dateField, className),
         style,
@@ -177,13 +156,14 @@ const InputDate = ({
       {
         open,
         placement: "bottom-start",
+        autoWidth: true,
         className: styles.calendarMenu,
         onStateChange: (_e, { next }) => setOpen(next),
         children: /* @__PURE__ */ jsxs("div", { "data-menu-open": "", children: [
           /* @__PURE__ */ jsx(
             Calendar,
             {
-              value: dateISO,
+              value: previewISO,
               min,
               max,
               locale,
@@ -199,58 +179,23 @@ const InputDate = ({
             }
           ),
           time && /* @__PURE__ */ jsxs("div", { className: styles.timeRow, children: [
-            /* @__PURE__ */ jsxs("div", { className: styles.time, role: "group", "aria-label": "Time", children: [
-              /* @__PURE__ */ jsx(Icon, { shape: "clock", "aria-hidden": "true", className: styles.clock }),
-              /* @__PURE__ */ jsx(
-                Input,
-                {
-                  size,
-                  className: styles.timeField,
-                  value: hourText,
-                  placeholder: "HH",
-                  type: "number",
-                  inputMode: "numeric",
-                  "aria-label": "Hours",
-                  disabled,
-                  onInput: (e) => setHourText(e.currentTarget.value.replace(/\D/g, "").slice(0, 2)),
-                  onChange: (e) => commitTime(e.currentTarget.value, minuteText, meridiem)
-                }
-              ),
-              /* @__PURE__ */ jsx("span", { className: styles.sep, "aria-hidden": "true", children: ":" }),
-              /* @__PURE__ */ jsx(
-                Input,
-                {
-                  size,
-                  className: styles.timeField,
-                  value: minuteText,
-                  placeholder: "MM",
-                  type: "number",
-                  inputMode: "numeric",
-                  "aria-label": "Minutes",
-                  disabled,
-                  onInput: (e) => setMinuteText(e.currentTarget.value.replace(/\D/g, "").slice(0, 2)),
-                  onChange: (e) => commitTime(hourText, e.currentTarget.value, meridiem)
-                }
-              ),
-              twelveHour && /* @__PURE__ */ jsx(
-                Tabs,
-                {
-                  className: styles.meridiem,
-                  size,
-                  priority: "primary",
-                  "aria-label": "AM or PM",
-                  options: [
-                    { value: "AM", label: "AM" },
-                    { value: "PM", label: "PM" }
-                  ],
-                  value: meridiem,
-                  onStateChange: (_e, { next }) => {
-                    if (next === "AM" || next === "PM") commitTime(hourText, minuteText, next);
-                  },
-                  disabled
+            /* @__PURE__ */ jsx(
+              InputTime,
+              {
+                size,
+                locale,
+                hour12,
+                disabled,
+                "aria-label": "Time",
+                value: hasTime ? `${String(h24).padStart(2, "0")}:${curM}` : "",
+                onValueChange: (e, { value: t }) => {
+                  const ev = "nativeEvent" in e ? e.nativeEvent : e;
+                  if (ev?.type !== "change") return;
+                  const base = dateISO || Temporal.Now.plainDateISO().toString();
+                  commit(t ? `${base}T${t}` : base);
                 }
-              )
-            ] }),
+              }
+            ),
             /* @__PURE__ */ jsx(
               Button,
               {

package/dist/components/InputDate.module.css

@@ -1 +1 @@
-.calendarMenu{--menu-padding: 8px}.timeRow{display:flex;align-items:center;justify-content:space-between;gap:12px;margin-top:6px;padding-top:8px;border-top:1px solid var(--border-3)}.time{display:flex;align-items:center;gap:4px}.clock{flex:none;color:var(--text-5);margin-inline-end:2px}.sep{color:var(--text-3);user-select:none}.timeField{width:2.25rem}.timeField[size=small]{width:2rem}.timeField[size=large]{width:2.5rem}.timeField::part(input){text-align:center;font-variant-numeric:tabular-nums;font-weight:500}.meridiem{margin-inline-start:4px;--tab-padding-x: 6px;--tabs-gap: 0px;--tab-padding-y: max(0px, calc((10px - var(--_pb)) / 2 - 2px))}.meridiem a-tab{font-weight:400}.dateField::part(input){text-overflow:ellipsis}
+.calendarMenu{--menu-padding: 8px}.timeRow{display:flex;align-items:center;justify-content:space-between;gap:12px;margin-top:6px;padding-top:8px;border-top:1px solid var(--border-3)}.dateField::part(input){text-overflow:ellipsis}

package/dist/components/InputTime.d.ts

@@ -0,0 +1,105 @@
+import type { BaseProps, DOMEventHandlers } from '../general_types';
+import type { IconShape } from '../elements/a-icon.shapes';
+/** Convenience snapshot passed as the 2nd argument to `onValueChange`. */
+export interface InputTimeChangeAttrs {
+    /** Current value — 24-hour `"HH:mm"`, `''` when incomplete. */
+    value: string;
+    /** The field's `name`, for keyed updates: `s => ({ ...s, [name]: value })`. */
+    name?: string;
+    /** `true` when the value is empty / incomplete. */
+    empty: boolean;
+    /** Whether the field currently passes validation. `undefined` where
+     *  `ElementInternals` is unsupported. */
+    valid?: boolean;
+    /** Current validation message (`''` when valid). */
+    validationMessage: string;
+}
+export interface InputTimeProps extends BaseProps, DOMEventHandlers {
+    /** Extra content rendered under the field, above the hint (a no-box child like
+     *  a `<Tooltip>` takes no space and just anchors to the field). */
+    children?: React.ReactNode;
+    /** Field label, shown above the control and used as the segment group's
+     *  accessible name. */
+    label?: React.ReactNode;
+    /** Message below the field. `status` recolors it and prefixes a glyph. */
+    hint?: React.ReactNode;
+    /** Validation / feedback tone. Only `critical` marks the field invalid; the
+     *  others are advisory. Omit (or `neutral`) for a plain field. */
+    status?: 'neutral' | 'brand' | 'info' | 'success' | 'warning' | 'critical';
+    /** Glyph before the `hint` when `status` is set (per-status default; pass a
+     *  shape to override, or `false` to drop it). */
+    statusIcon?: IconShape | (string & {}) | false;
+    /** Custom accent colour — any literal CSS colour tints the resting + hover
+     *  border (focus ring stays `--focus-ring`); `status` overrides for validation. */
+    tone?: string;
+    /** Size variant. small=24px, medium=28px, large=32px tall.
+     *  @defaultValue medium */
+    size?: 'small' | 'medium' | 'large';
+    /** Controlled value — 24-hour `"HH:mm"`. Pair with `onValueChange`. */
+    value?: string;
+    /** Initial value for the uncontrolled case (24-hour `"HH:mm"`). */
+    defaultValue?: string;
+    /** BCP-47 locale driving the clock (12h vs 24h), segment order, separator, and
+     *  the AM/PM text.
+     *  @defaultValue navigator.language */
+    locale?: string;
+    /** Force the clock: `true` = 12-hour (AM/PM), `false` = 24-hour. Omit to follow
+     *  the locale. */
+    hour12?: boolean;
+    /** Earliest allowed time, 24-hour `"HH:mm"`. A complete value below it is
+     *  clamped up (on step / blur) and flagged `rangeUnderflow` for form validity. */
+    min?: string;
+    /** Latest allowed time, 24-hour `"HH:mm"`. A complete value above it is clamped
+     *  down (on step / blur) and flagged `rangeOverflow`. */
+    max?: string;
+    /** Form field name — the 24-hour value submits under this key. */
+    name?: string;
+    /** Disable the field. */
+    disabled?: boolean;
+    /** Mark the field required (drives native validity). */
+    required?: boolean;
+    /** Leading icon at the start of the field — the clock affordance. Pass another
+     *  shape to change it, or `false` to drop it.
+     *  @defaultValue clock */
+    icon?: IconShape | false;
+    /** Show a clear button once the field has a value. */
+    clearable?: boolean;
+    /** Dim the trailing adornments at rest; they brighten on hover / focus. */
+    dimActions?: boolean;
+    /** Content pinned to the end of the field (after the clear button). */
+    trailing?: React.ReactNode;
+    /** Fully-round the field, or a custom radius (`number` px / CSS length). */
+    round?: boolean | number | string;
+    /** 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: any, attrs: InputTimeChangeAttrs) => void;
+    /** Fires after the built-in clear button has cleared the field. */
+    onClearInput?: (e: CustomEvent) => void;
+    /** Fires when the field gains focus. */
+    onFocus?: (e: any) => void;
+    /** Fires when the field loses focus. */
+    onBlur?: (e: any) => void;
+}
+/**
+ * `<InputTime>` — a segmented wall-clock time field. One boxed input (matching
+ * the other inputs) with separate hour / minute / (12-hour) AM-PM sections that
+ * behave as one control: each is a `role="spinbutton"` — ↑/↓ steps with wrap,
+ * ←/→ moves between them, typing digits auto-advances, and AM/PM toggles with
+ * ↑/↓ or `a`/`p`. Renders an `<a-input-time>` web component that owns the
+ * segments, keyboard, and form value (via `ElementInternals`).
+ *
+ * The clock and layout follow the locale (`en-US` → 12-hour, most others 24),
+ * overridable with `hour12`. The value is a 24-hour `"HH:mm"` string; controlled
+ * (`value` + `onValueChange`) or uncontrolled (`defaultValue`), submitting under
+ * `name`.
+ *
+ * Requires `@antadesign/anta/elements` (client-side only). Reads
+ * `navigator.language` at render, so render client-side (not SSR-safe).
+ *
+ * @example
+ * ```tsx
+ * <InputTime label="Start" defaultValue="09:30" onValueChange={(_, { value }) => save(value)} />
+ * ```
+ */
+export declare const InputTime: ({ label, hint, status, statusIcon, tone, size, round, value, defaultValue, locale, hour12, min, max, name, disabled, required, icon, clearable, dimActions, trailing, onValueChange, onClearInput, children, className, style, ...rest }: InputTimeProps) => any;

package/dist/components/InputTime.js

@@ -0,0 +1,110 @@
+import { jsx, jsxs } from "@antadesign/anta/jsx-runtime";
+import { nativeStateChange, toneStyle, roundStyle } from "../anta_helpers";
+import { Button } from "./Button";
+import { Icon } from "./Icon";
+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,
+    empty: !value,
+    valid: el.validity ? el.validity.valid : void 0,
+    validationMessage: el.validationMessage ?? ""
+  };
+};
+const STATUS_ICON = {
+  critical: "warning-diamond",
+  warning: "warning-triangle",
+  success: "circle-check",
+  info: "info",
+  brand: "circle-small-solid"
+};
+const InputTime = ({
+  label,
+  hint,
+  status,
+  statusIcon,
+  tone,
+  size,
+  round,
+  value,
+  defaultValue,
+  locale,
+  hour12,
+  min,
+  max,
+  name,
+  disabled,
+  required,
+  icon,
+  clearable,
+  dimActions,
+  trailing,
+  onValueChange,
+  onClearInput,
+  children,
+  className,
+  style,
+  ...rest
+}) => {
+  const statusTone = status && status !== "neutral" ? status : void 0;
+  const glyph = statusIcon === void 0 ? statusTone ? STATUS_ICON[statusTone] : void 0 : statusIcon;
+  return /* @__PURE__ */ jsxs(
+    "a-input-time",
+    {
+      size: size && size !== "medium" ? size : void 0,
+      round: round ? "" : void 0,
+      value,
+      defaultvalue: defaultValue,
+      locale,
+      hour12: hour12 === void 0 ? void 0 : hour12 ? "true" : "false",
+      min,
+      max,
+      status: statusTone,
+      tone: tone || void 0,
+      name,
+      disabled: presence(disabled),
+      required: presence(required),
+      "dim-actions": presence(dimActions),
+      "aria-invalid": status === "critical" ? "true" : void 0,
+      oninput: onValueChange ? (e) => onValueChange(e, attrsOf(e)) : void 0,
+      onchange: onValueChange ? (e) => onValueChange(e, attrsOf(e)) : void 0,
+      onclearinput: onClearInput ? (e) => onClearInput(nativeStateChange(e).event) : void 0,
+      class: className,
+      style: roundStyle(round, "--input-time-round", toneStyle(tone, "--input-time-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 })),
+        icon !== false && /* @__PURE__ */ jsx("span", { slot: "leading", style: { display: "contents" }, children: /* @__PURE__ */ jsx(Icon, { shape: icon ?? "clock" }) }),
+        clearable && // Real <a-button> in the element's `clear` slot; the element owns its
+        // visibility (shown only when filled). It fires `clearrequest`, which the
+        // element turns into clear(). CONTRACT: `data-custom-event` MUST match
+        // CLEAR_TRIGGER in src/elements/a-input-time.ts (string duplicated, not
+        // shared, to keep the wrapper/element decoupled).
+        /* @__PURE__ */ jsx("span", { slot: "clear", style: { display: "contents" }, children: /* @__PURE__ */ jsx(
+          Button,
+          {
+            priority: "tertiary",
+            size,
+            round: !!round,
+            icon: "x",
+            "aria-label": "Clear",
+            "data-custom-event": "clearrequest"
+          }
+        ) }),
+        trailing != null && /* @__PURE__ */ jsx("span", { slot: "trailing", style: { display: "contents" }, children: trailing }),
+        hint != null && /* @__PURE__ */ jsxs("span", { slot: "hint", style: { display: "contents" }, children: [
+          glyph && /* @__PURE__ */ jsx(Icon, { shape: glyph, "aria-hidden": "true" }),
+          /* @__PURE__ */ jsx("span", { children: hint })
+        ] }),
+        children
+      ]
+    }
+  );
+};
+export {
+  InputTime
+};

package/dist/components/Menu.d.ts

@@ -22,6 +22,11 @@ export interface MenuProps extends BaseProps {
     /** Gap in pixels between the trigger and the menu.
      *  @defaultValue 4 */
     offset?: number;
+    /** Size the menu to its content instead of flooring its width to the trigger.
+     *  A root menu is never narrower than its trigger by default; set this for a
+     *  content menu under a wide trigger (e.g. a calendar below a full-width field)
+     *  so it wraps its content and left-aligns under the trigger. */
+    autoWidth?: boolean;
     /** Controlled open state. Omit for the default **uncontrolled** menu (it
      *  opens/closes itself via its triggers). Pass a boolean to **control** it:
      *  the menu's visibility follows `open`, and user dismiss (Esc, outside-click,
@@ -53,6 +58,9 @@ export interface MenuProps extends BaseProps {
     onactivedescendant?: (e: CustomEvent<{
         id: string | null;
     }>) => void;
+    /** ARIA role of the menu surface.
+     *  @defaultValue menu */
+    role?: string;
     /** The menu's contents: `MenuItem`, `MenuSeparator`, `MenuGroup`, or any
      *  custom element. */
     children?: React.ReactNode;
@@ -83,4 +91,4 @@ export interface MenuProps extends BaseProps {
  * </Menu>
  * ```
  */
-export declare const Menu: ({ placement, context, coord, nohover, offset, open, onStateChange, round, className, style, children, ...rest }: MenuProps) => any;
+export declare const Menu: ({ placement, context, coord, nohover, offset, autoWidth, open, onStateChange, round, role, className, style, children, ...rest }: MenuProps) => any;

package/dist/components/Menu.js

@@ -6,9 +6,11 @@ const Menu = ({
   coord,
   nohover,
   offset,
+  autoWidth,
   open,
   onStateChange,
   round,
+  role = "menu",
   className,
   style,
   children,
@@ -22,6 +24,7 @@ const Menu = ({
       coord: coord ? "" : void 0,
       nohover: nohover ? "" : void 0,
       offset: offset != null ? String(offset) : void 0,
+      autowidth: autoWidth ? "" : void 0,
       state: open === void 0 ? void 0 : open ? "open" : "closed",
       onstatechange: onStateChange ? (e) => {
         const { event, detail } = nativeStateChange(e);
@@ -32,7 +35,7 @@ const Menu = ({
           });
       } : void 0,
       round: round ? "" : void 0,
-      role: "menu",
+      role,
       "aria-orientation": "vertical",
       class: className,
       style: roundStyle(round, "--menu-round", style),

package/dist/components/MenuItem.d.ts

@@ -75,6 +75,14 @@ export interface MenuItemProps extends BaseProps {
         value?: string | number;
         label?: React.ReactNode;
     }) => void;
+    /** Raw `mousedown` on the row. Mainly to `preventDefault()` so the row doesn't
+     *  take focus on a mouse press — e.g. a combobox option keeping focus in its
+     *  input field while the click still selects. */
+    onMouseDown?: (event: any) => void;
+    /** ARIA role override. Defaults to the role implied by `selectionIndicator`
+     *  (`menuitem` / `menuitemcheckbox` / `menuitemradio`); set it to reparent the
+     *  row under a different container role — e.g. `option` inside a `listbox`. */
+    role?: string;
     /** Item content. With `label` set, children are extra content — most
      *  notably the nested `<Menu>` for a submenu parent. */
     children?: React.ReactNode;
@@ -99,4 +107,4 @@ export interface MenuItemProps extends BaseProps {
  * </MenuItem>
  * ```
  */
-export declare const MenuItem: ({ icon, label, hint, kbd, iconTrailing, disabled, selected, selectionIndicator, indeterminate, indicator, tone, toneSelected, submenu, value, onSelect, className, style, children, ...rest }: MenuItemProps) => any;
+export declare const MenuItem: ({ icon, label, hint, kbd, iconTrailing, disabled, selected, selectionIndicator, indeterminate, indicator, tone, toneSelected, submenu, value, onSelect, role: roleOverride, className, style, children, ...rest }: MenuItemProps) => any;

package/dist/components/MenuItem.js

@@ -16,6 +16,7 @@ const MenuItem = ({
   submenu,
   value,
   onSelect,
+  role: roleOverride,
   className,
   style,
   children,
@@ -30,7 +31,7 @@ const MenuItem = ({
   return /* @__PURE__ */ jsxs(
     "a-menu-item",
     {
-      role,
+      role: roleOverride ?? role,
       tabIndex: 0,
       disabled: disabled ? "" : void 0,
       selected: keepTint ? "" : void 0,

package/dist/components/Select.d.ts

@@ -97,8 +97,10 @@ export interface TriggerState {
 }
 /** Snapshot passed as the 2nd argument to `onValueChange` — describes *what*
  *  changed, alongside the new full value in the 1st argument. A discriminated
- *  union: a row toggle carries `value` + `option`; the "Select all" row carries
- *  `all: true` instead. Narrow on `'all' in attrs` before reading `option`. */
+ *  union: a row toggle carries `value` + `option`; a bulk change (the "Select all"
+ *  row, or the `clearable` "Clear" footer) carries `all: true` instead. **Always
+ *  narrow on `'all' in attrs` before reading `option`** — the `all` variant fires
+ *  for single-select too (via `clearable`), not just multiple. */
 export type SelectChangeAttrs = {
     /** The option value that changed — the chosen value (single) or the toggled
      *  row (multiple). */
@@ -108,9 +110,11 @@ export type SelectChangeAttrs = {
     /** Multiple only: whether the change turned selection **on** (true) or off. */
     selected?: boolean;
 } | {
-    /** Marks the change as coming from the "Select all" row (multiple only). */
+    /** Marks the change as a bulk one with no single `option`: the "Select all"
+     *  row (multiple), or the `clearable` "Clear" footer (single or multiple). */
     all: true;
-    /** Whether Select-all turned everything **on** (true) or cleared it. */
+    /** Whether the bulk change turned everything **on** (true) or cleared it
+     *  (false — always false for a "Clear"). */
     selected: boolean;
 };
 /** Props shared by both selection modes, intersected into `SelectProps`. Exported
@@ -139,6 +143,11 @@ export interface SelectCommonProps extends Omit<BaseProps, 'children'> {
      *  `leading` slot). With a custom `renderTrigger`, it's passed through as
      *  `state.icon` instead — the consumer places it. */
     icon?: IconShape;
+    /** Arbitrary content for the default trigger's leading slot (piped straight to
+     *  `Input`'s `leading`) — e.g. a key prefix before the value. Overrides the
+     *  `icon`-derived glyph when both are set; include your own `<Icon>` if you want
+     *  one alongside. Ignored with a custom `renderTrigger`. */
+    leading?: React.ReactNode;
     /** Field label, above the trigger (Input's `label`). */
     label?: string;
     /** Helper text under the field (Input's `hint`). */
@@ -167,13 +176,23 @@ export interface SelectCommonProps extends Omit<BaseProps, 'children'> {
      *  option's **value / label / hint**. Pass a **function** `(option, query) =>
      *  boolean` for custom matching (called per option; return `true` to keep it). */
     filter?: boolean | ((option: SelectOption, query: string) => boolean);
-    /** `multiple` only: add a "Select all" row at the top that toggles every enabled
+    /** `multiple` only: a "Select all" row at the top that toggles every enabled
      *  option (the currently-visible ones when a `filter` query is active); its box
-     *  shows the mixed state when only some are selected. */
+     *  shows the mixed state when only some are selected. On by default in
+     *  `multiple` mode — set `false` to drop the row (and with it the Alt/⌥-click
+     *  isolate accelerator it gates).
+     *  @defaultValue true */
     selectAll?: boolean;
     /** Label for the `selectAll` row.
      *  @defaultValue Select all */
     selectAllLabel?: string;
+    /** Add a "Clear" row pinned in the menu **footer** that empties the selection
+     *  (single → none, multiple → `[]`). Shown only while something is selected, so
+     *  it never scrolls away in a long or filtered list. */
+    clearable?: boolean;
+    /** Label for the `clearable` footer row.
+     *  @defaultValue Clear */
+    clearLabel?: string;
     /** Render the **content** of each option row yourself, replacing the built-in
      *  `label`/`hint`/`icon` layout. Select still supplies the row box, click, ARIA,
      *  and the selection indicator — you return only what goes *inside*. Read extra
@@ -194,8 +213,10 @@ export interface SelectCommonProps extends Omit<BaseProps, 'children'> {
      *  the menu anchors to it (its own previous DOM sibling) and opens it on click,
      *  so a fragment, multiple siblings, or a non-focusable wrapper will misanchor
      *  (the menu warns in the console if the trigger has no focusable element). Give
-     *  the element `aria-haspopup="menu"` plus `aria-expanded={state.open}`. The field
-     *  props (`label`, `hint`, `size`, `status`, `placeholder`, `round`) don't apply. */
+     *  the element `aria-haspopup="menu"` plus `aria-expanded={state.open}`. The custom
+     *  trigger owns its own styling: the field props (`label`, `hint`, `size`, `status`,
+     *  `placeholder`, `round`) and `className` / `style` apply to the *default* trigger
+     *  only — put your own on the element you return. */
     renderTrigger?: (state: TriggerState) => React.ReactNode;
     /** Render content in the menu body when the (filtered) option list is empty —
      *  a "no results" message, a loading indicator (gated on your own external