@antadesign/anta 0.3.12 → 0.3.14

package/dist/components/Select.d.ts

@@ -1,15 +1,23 @@
 import type { BaseProps } from '../general_types';
 import type { IconShape } from '../elements/a-icon.shapes';
 import { type MenuProps } from './Menu';
+/** The type an option `value` may take: `string`, `number`, or `boolean`. Selection
+ *  compares values with `===`. Object-shaped values are out of scope; give the option a
+ *  stable primitive `value` and read the object back off `attrs.option` (or, in
+ *  `SelectFaceted`, use a `custom` facet). */
+export type OptionValue = string | number | boolean;
 /** One option in a `<Select>`. Pass a bare string as shorthand for
  *  `{ value: s, label: s }`. Carries an index signature so you can attach
  *  arbitrary fields (a `ranAt` date, a `status`, …) and read them back in
- *  `renderOption`; the built-in filter still matches on `value`/`label`/`hint`. */
-export interface SelectOption {
-    /** The option's value — its identity, what `value` / `defaultValue` name, and what
-     *  `onValueChange` reports. Unique across the whole `options` tree (selection is
+ *  `renderOption`; the built-in filter still matches on `value`/`label`/`hint`.
+ *
+ *  Generic in the value type `V` (defaults to `string`): `Select` infers `V` from your
+ *  `options`, so `{ value: 365 }` round-trips as `number` through `onValueChange`. */
+export interface SelectOption<V extends OptionValue = string> {
+    /** The option's value (`V`) — its identity, what `value` / `defaultValue` name, and
+     *  what `onValueChange` reports. Unique across the whole `options` tree (selection is
      *  value-keyed and global across groups / submenus). */
-    value: string;
+    value: V;
     /** Visible label. Defaults to `value`. */
     label?: string;
     /** Secondary text under the label (the option row's `hint`). */
@@ -32,11 +40,11 @@ export interface SelectOption {
 /** A titled group of options rendered **inline** under a heading (like `MenuGroup`).
  *  Selection stays global — a group only organizes; its heading isn't selectable.
  *  `disabled` cascades to every descendant. Nest groups / submenus freely. */
-export interface SelectGroup {
+export interface SelectGroup<V extends OptionValue = string> {
     /** The section heading (non-interactive). */
     label: string;
     /** The grouped items — options, or further groups / submenus. */
-    options: SelectItem[];
+    options: SelectItem<V>[];
     /** Disable the whole group (cascades to all descendants). */
     disabled?: boolean;
 }
@@ -44,13 +52,13 @@ export interface SelectGroup {
  *  Navigation only — the parent row opens the submenu and is never itself selectable.
  *  While a filter query is active the tree flattens and a submenu collapses into a
  *  group (its `label` becomes the heading). `disabled` cascades to descendants. */
-export interface SelectSubmenu {
+export interface SelectSubmenu<V extends OptionValue = string> {
     /** The parent row's label — and the group heading when filtering flattens it. */
     label: string;
     /** Leading icon on the parent row. */
     icon?: IconShape;
     /** The submenu's items — options, or further groups / submenus. */
-    submenu: SelectItem[];
+    submenu: SelectItem<V>[];
     /** Disable the whole branch (cascades to all descendants). */
     disabled?: boolean;
 }
@@ -58,13 +66,13 @@ export interface SelectSubmenu {
  *  inline `SelectGroup`, or a flyout `SelectSubmenu`. Discriminated by shape — an
  *  `options` array is a group, a `submenu` array is a submenu, else it's an option.
  *  (`options` / `submenu` are therefore reserved keys on an option object.) */
-export type SelectItem = string | SelectOption | SelectGroup | SelectSubmenu;
+export type SelectItem<V extends OptionValue = string> = string | SelectOption<V> | SelectGroup<V> | SelectSubmenu<V>;
 /** Per-row snapshot passed to `renderOption` / `renderIndicator`. Everything here
  *  is known at render time; the combobox "active" cursor is deliberately absent
  *  (it's a live element state the DOM owns, not a render-time value). */
-export interface OptionState {
+export interface OptionState<V extends OptionValue = string> {
     /** The option's value. */
-    value: string;
+    value: V;
     /** Whether this row is currently selected. */
     selected: boolean;
     /** Whether this row is disabled. */
@@ -81,15 +89,15 @@ export interface EmptyState {
 }
 /** Snapshot passed to `renderTrigger` so a custom trigger can reflect the current
  *  selection and open state. */
-export interface TriggerState {
+export interface TriggerState<V extends OptionValue = string> {
     /** Whether the menu is open — use it for `aria-expanded` and a chevron. */
     open: boolean;
-    /** The current selection: a string (single), a string array (`multiple`), or
+    /** The current selection: a single value (single), an array (`multiple`), or
      *  `undefined` when nothing is chosen. */
-    value: string | string[] | undefined;
+    value: V | V[] | undefined;
     /** The resolved option objects for the current selection (empty when none).
      *  `selected.length` is the multi-select count. */
-    selected: SelectOption[];
+    selected: SelectOption<V>[];
     /** Whether the whole select is disabled. */
     disabled: boolean;
     /** The `icon` shape passed to `Select`, if any — hand it to your trigger
@@ -102,12 +110,12 @@ export interface TriggerState {
  *  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 = {
+export type SelectChangeAttrs<V extends OptionValue = string> = {
     /** The option value that changed — the chosen value (single) or the toggled
      *  row (multiple). */
-    value: string;
+    value: V;
     /** The resolved option object for `value`. */
-    option: SelectOption;
+    option: SelectOption<V>;
     /** Multiple only: whether the change turned selection **on** (true) or off. */
     selected?: boolean;
 } | {
@@ -121,17 +129,21 @@ export type SelectChangeAttrs = {
 /** Props shared by both selection modes, intersected into `SelectProps`. Exported
  *  (and kept as an interface intersected — not a union base via `extends`) so its
  *  members read as `Select`'s *own* props in the generated docs, not inherited. */
-export interface SelectCommonProps extends Omit<BaseProps, 'children'> {
+export interface SelectCommonProps<V extends OptionValue = string> extends Omit<BaseProps, 'children'> {
     /** The options to choose from — bare strings, `SelectOption` objects, `SelectGroup`s
      *  (inline titled sections), or `SelectSubmenu`s (flyout branches). Groups and
      *  submenus nest and mix with plain options. Selection stays global (one `value`,
      *  leaf options only); a filter query flattens the tree into grouped results.
      *
+     *  `Select` infers its value type `V` from these options: `{ value: 365 }` makes
+     *  `onValueChange` report `number`. A mix of value types widens `V` to the union.
+     *
      *  Each leaf `value` is the option's identity and must be **unique across the whole
-     *  tree** — selection is value-keyed, so a value repeated in two sections is one
-     *  logical pick (both rows toggle together; the trigger resolves to the last). Dev
-     *  builds `console.warn` on a duplicate. */
-    options: SelectItem[];
+     *  tree** (selection is value-keyed, so a value repeated in two sections is one logical
+     *  pick: both rows toggle together, the trigger resolves to the last). Values that
+     *  stringify alike (`365` and `"365"`) also collide as row keys; dev builds
+     *  `console.warn` on either. */
+    options: SelectItem<V>[];
     /** Preferred placement of the options menu relative to the trigger. The menu
      *  auto-flips vertically and clamps horizontally when needed.
      *  @defaultValue bottom-start */
@@ -183,7 +195,7 @@ export interface SelectCommonProps extends Omit<BaseProps, 'children'> {
      *  type. `true` uses the built-in matcher — a case-insensitive substring of the
      *  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);
+    filter?: boolean | ((option: SelectOption<V>, query: string) => boolean);
     /** `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. On by default in
@@ -208,13 +220,31 @@ export interface SelectCommonProps extends Omit<BaseProps, 'children'> {
      *  `OptionState` (`value`/`selected`/`disabled`). Filtering still works (it
      *  matches the option's `value`/`label`/`hint`), but match-highlighting is
      *  skipped — your content owns its own display. */
-    renderOption?: (option: SelectOption, state: OptionState) => React.ReactNode;
+    renderOption?: (option: SelectOption<V>, state: OptionState<V>) => React.ReactNode;
     /** Replace each row's selection **mark** with your own node, drawn at the
      *  leading edge. The row stays the control (`role` + `aria-checked` from
      *  `indicator` / `selection`); only the drawn mark changes, so pair it with an
      *  `indicator` (`'check'` / `'radio'`) or `selection="multiple"` for the
      *  semantics. Composes with `renderOption`. */
-    renderIndicator?: (state: OptionState) => React.ReactNode;
+    renderIndicator?: (state: OptionState<V>) => React.ReactNode;
+    /** `multiple` only: spell the picks out in the count summary — `3 selected:
+     *  A, B, C` (labels comma-joined) in place of the bare `3 selected`. Applies
+     *  to the multi-count case only: `All` stays `All`, a single pick stays its
+     *  own label, and an empty selection stays the `placeholder`. The list flows
+     *  into the read-only field, so it ellipsizes at the field's width when long
+     *  (`3 selected: Engineering, Des… `). `renderSummary` overrides this. */
+    verbose?: boolean;
+    /** `multiple` only: build the trigger's selection summary text yourself,
+     *  replacing the built-in "`All` / one label / `N selected`" logic. Receives
+     *  the resolved selected options (`selected.length` is the count) and runs only
+     *  while something is selected — an empty selection still shows the
+     *  `placeholder`. Return a **string**: it flows into the default trigger's
+     *  read-only field, so a long summary ellipsizes at the field's width just
+     *  like a long value (`Engineering, Design, … `). Return `undefined` to fall
+     *  back to the default for that case (e.g. customize only the count, keeping
+     *  the single-label case built-in). For rich content (chips, multiple nodes)
+     *  use `renderTrigger`, which replaces the whole field. */
+    renderSummary?: (selected: SelectOption<V>[]) => string | undefined;
     /** Render your own trigger in place of the default field. Receives a
      *  `TriggerState` (`open` / `value` / `selected` / `disabled` / `icon`) to drive
      *  its look. **Return exactly one focusable element** (an Anta `Button`, say) —
@@ -225,7 +255,7 @@ export interface SelectCommonProps extends Omit<BaseProps, 'children'> {
      *  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;
+    renderTrigger?: (state: TriggerState<V>) => 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
      *  loading state), or a "create from the query" row. Receives an `EmptyState`
@@ -239,37 +269,37 @@ export interface SelectCommonProps extends Omit<BaseProps, 'children'> {
  * `<Select>` props. `selection` discriminates the value shape: single mode
  * (`value: string`) or `multiple` (`value: string[]`).
  */
-export type SelectProps = SelectCommonProps & ({
-    /** Selection mode. `'single'` (the default) keeps `value` a string and
+export type SelectProps<V extends OptionValue = string> = SelectCommonProps<V> & ({
+    /** Selection mode. `'single'` (the default) keeps `value` a single value and
      *  closes the menu on pick. Switch to `'multiple'` for checkboxes + an
      *  array value.
      *  @defaultValue single */
     selection?: 'single';
-    /** Controlled value — the `value` string of the selected option. When
-     *  provided, the consumer owns selection: the field follows this prop and a
-     *  pick only *requests* a change via `onValueChange` (reject by not updating).
-     *  Leave undefined for uncontrolled. */
-    value?: string;
-    /** Initial value (an option's `value` string) for the uncontrolled case — the
+    /** Controlled value — the `value` of the selected option. When provided, the
+     *  consumer owns selection: the field follows this prop and a pick only
+     *  *requests* a change via `onValueChange` (reject by not updating). Leave
+     *  undefined for uncontrolled. */
+    value?: V;
+    /** Initial value (an option's `value`) for the uncontrolled case — the
      *  wrapper then owns it. */
-    defaultValue?: string;
+    defaultValue?: V;
     /** Fires after the selection changes, with the new value and a
      *  `{ value, option }` snapshot. Select has no discrete element state, so
      *  there is no cancelable `onStateChange` (see the Input event-model note). */
-    onValueChange?: (value: string, attrs: SelectChangeAttrs) => void;
+    onValueChange?: (value: V, attrs: SelectChangeAttrs<V>) => void;
 } | {
     /** Multi-select: checkboxes on every row, the menu stays open while
      *  toggling, the field shows an "N selected" count, and `value` is an array. */
     selection: 'multiple';
-    /** Controlled values — the `value` strings of the selected options (see the
+    /** Controlled values — the `value`s of the selected options (see the
      *  single-select `value` note). */
-    value?: string[];
-    /** Initial values (option `value` strings) for the uncontrolled case. */
-    defaultValue?: string[];
+    value?: V[];
+    /** Initial values (option `value`s) for the uncontrolled case. */
+    defaultValue?: V[];
     /** Fires after any toggle, with the new value array and a `{ value, option,
      *  selected }` snapshot of the row that changed (or `{ all: true }` for the
      *  Select-all row). */
-    onValueChange?: (value: string[], attrs: SelectChangeAttrs) => void;
+    onValueChange?: (value: V[], attrs: SelectChangeAttrs<V>) => void;
 });
 /** Rolled-up selection of a group / submenu subtree: `'none'` / `'all'` of the
  *  descendant leaves selected, or `'some'` in between. On `SelectedGroup` /
@@ -277,26 +307,26 @@ export type SelectProps = SelectCommonProps & ({
 export type SelectionState = 'none' | 'some' | 'all';
 /** A leaf option annotated with its current selection — a `SelectOption` plus
  *  `selected`. Returned by {@link optionsWithSelection}. */
-export type SelectedOption = SelectOption & {
+export type SelectedOption<V extends OptionValue = string> = SelectOption<V> & {
     selected: boolean;
 };
 /** A group with its descendants annotated and a rolled-up `selectionState`.
  *  Returned by {@link optionsWithSelection}. */
-export interface SelectedGroup extends Omit<SelectGroup, 'options'> {
-    options: SelectedItem[];
+export interface SelectedGroup<V extends OptionValue = string> extends Omit<SelectGroup<V>, 'options'> {
+    options: SelectedItem<V>[];
     selectionState: SelectionState;
 }
 /** A submenu with its descendants annotated and a rolled-up `selectionState`.
  *  Returned by {@link optionsWithSelection}. */
-export interface SelectedSubmenu extends Omit<SelectSubmenu, 'submenu'> {
-    submenu: SelectedItem[];
+export interface SelectedSubmenu<V extends OptionValue = string> extends Omit<SelectSubmenu<V>, 'submenu'> {
+    submenu: SelectedItem<V>[];
     selectionState: SelectionState;
 }
 /** One node of the tree from {@link optionsWithSelection}: a leaf `SelectedOption`
  *  (with `selected`), or a `SelectedGroup` / `SelectedSubmenu` (annotated children
  *  + rolled-up `selectionState`). Mirrors `SelectItem` minus the bare-string
  *  shorthand — strings are normalized to `SelectedOption`. */
-export type SelectedItem = SelectedOption | SelectedGroup | SelectedSubmenu;
+export type SelectedItem<V extends OptionValue = string> = SelectedOption<V> | SelectedGroup<V> | SelectedSubmenu<V>;
 /**
  * Project a `Select` `options` tree onto a set of selected values: returns a mirror
  * of the tree with every leaf marked `selected` and every group / submenu carrying a
@@ -319,7 +349,7 @@ export type SelectedItem = SelectedOption | SelectedGroup | SelectedSubmenu;
  * //   { value: 'eng-fe', label: 'Frontend', selected: false }, … ] }
  * ```
  */
-export declare function optionsWithSelection(options: SelectItem[], values: string | string[] | undefined): SelectedItem[];
+export declare function optionsWithSelection<V extends OptionValue = string>(options: SelectItem<V>[], values: V | V[] | undefined): SelectedItem<V>[];
 /**
  * `<Select>` — a single- or multi-select dropdown, composed from `<Input>` (a
  * read-only trigger) and `<Menu>` (the options). `selection` sets behaviour:
@@ -345,4 +375,4 @@ export declare function optionsWithSelection(options: SelectItem[], values: stri
  * />
  * ```
  */
-export declare const Select: (props: SelectProps) => any;
+export declare const Select: <V extends OptionValue = string>(props: SelectProps<V>) => any;

package/dist/components/Select.js

@@ -62,6 +62,8 @@ const Select = (props) => {
     clearLabel = "Clear",
     renderOption,
     renderIndicator,
+    verbose,
+    renderSummary,
     renderTrigger,
     renderEmpty,
     className,
@@ -96,9 +98,10 @@ const Select = (props) => {
   collectLeaves(options, void 0, false, allLeaves);
   const seenValues = /* @__PURE__ */ new Set();
   for (const l of allLeaves) {
-    if (seenValues.has(l.opt.value))
-      console.warn(`[anta] <Select> duplicate option value=${JSON.stringify(l.opt.value)} \u2014 values must be unique.`);
-    seenValues.add(l.opt.value);
+    const key = String(l.opt.value);
+    if (seenValues.has(key))
+      console.warn(`[anta] <Select> duplicate option value=${JSON.stringify(l.opt.value)} \u2014 values must be unique (compared as strings for row keys).`);
+    seenValues.add(key);
   }
   const byValue = new Map(allLeaves.map((l) => [l.opt.value, l.opt]));
   const filtering = filter !== void 0 && filter !== false;
@@ -111,13 +114,22 @@ const Select = (props) => {
   const selectedValues = Array.isArray(currentRaw) ? currentRaw : currentRaw != null ? [currentRaw] : [];
   const isSelected = (v) => selectedValues.includes(v);
   const selectedOptions = selectedValues.map((v) => byValue.get(v)).filter(Boolean);
+  const allEnabledValues = allLeaves.filter((l) => !l.disabled).map((l) => l.opt.value);
+  const everythingSelected = multiple && allEnabledValues.length > 1 && allEnabledValues.every((v) => selectedValues.includes(v));
+  const labelOf = (o) => o.label ?? String(o.value);
   let display = "";
   if (multiple) {
-    if (selectedOptions.length === 1) display = selectedOptions[0].label ?? selectedOptions[0].value;
-    else if (selectedOptions.length > 1) display = `${selectedOptions.length} selected`;
+    const custom = selectedOptions.length > 0 ? renderSummary?.(selectedOptions) : void 0;
+    if (custom != null && custom !== "") display = custom;
+    else if (everythingSelected) display = "All";
+    else if (selectedOptions.length === 1) display = labelOf(selectedOptions[0]);
+    else if (selectedOptions.length > 1) {
+      const count = `${selectedOptions.length} selected`;
+      display = verbose ? `${count}: ${selectedOptions.map(labelOf).join(", ")}` : count;
+    }
   } else if (currentRaw != null) {
     const o = byValue.get(currentRaw);
-    display = o ? o.label ?? o.value : "";
+    display = o ? labelOf(o) : "";
   }
   const choose = (o, e) => {
     if (multiple) {
@@ -166,7 +178,7 @@ const Select = (props) => {
         selectionIndicator: menuItemIndicator,
         ...ariaSelectable,
         indicator: customMark ?? void 0,
-        label: custom ? void 0 : highlight(o.label ?? o.value, queryRe),
+        label: custom ? void 0 : highlight(o.label ?? String(o.value), queryRe),
         hint: custom ? void 0 : o.hint ? highlight(o.hint, queryRe) : o.hint,
         icon: custom ? void 0 : o.icon,
         tone: o.tone,
@@ -177,10 +189,10 @@ const Select = (props) => {
         onSelect: (e) => choose(o, e),
         children: [
           custom,
-          tip && /* @__PURE__ */ jsx(Tooltip, { ...hintOnly ? { follow: true, delay: 700 } : {}, children: tip })
+          tip && /* @__PURE__ */ jsx(Tooltip, { follow: true, ...hintOnly ? { delay: 700 } : {}, children: tip })
         ]
       },
-      o.value
+      String(o.value)
     );
   };
   const renderTree = (items, disabled2) => {

package/dist/components/SelectFaceted.d.ts

@@ -1,6 +1,6 @@
 import type { BaseProps } from '../general_types';
 import type { IconShape } from '../elements/a-icon.shapes';
-import type { SelectItem, SelectOption } from './Select';
+import type { OptionValue, SelectItem, SelectOption } from './Select';
 import { type MenuProps } from './Menu';
 interface FacetBase {
     /** The facet's namespace — the key its value is stored under in the value
@@ -15,26 +15,27 @@ interface FacetBase {
 /** A per-facet option-list filter (like `Select`'s `filter`): `true` uses the
  *  built-in case-insensitive substring match on an option's value / label /
  *  hint; a function `(option, query) => boolean` does custom matching. */
-export type FacetFilter = boolean | ((option: SelectOption, query: string) => boolean);
-/** Pick **one** option. Value: the chosen option's `value` string (or
- *  `undefined` when cleared). Re-picking the selected option clears it. Options
- *  are `Select`'s `SelectItem`s — bare strings or `SelectOption`s carrying the
- *  same fields (`value`, `label`, `hint`, `icon`, `tone`, `disabled`). */
+export type FacetFilter = boolean | ((option: SelectOption<OptionValue>, query: string) => boolean);
+/** Pick **one** option. Value: the chosen option's `value` (or `undefined` when
+ *  cleared). Re-picking the selected option clears it. Options are `Select`'s
+ *  `SelectItem`s — bare strings or `SelectOption`s carrying the same fields
+ *  (`value`, `label`, `hint`, `icon`, `tone`, `disabled`). Option `value`s may be
+ *  `string` / `number` / `boolean` and round-trip unchanged. */
 export interface SelectFacetSingle extends FacetBase {
     kind: 'single';
     /** The options — bare strings or `SelectOption`s (groups / submenus are
      *  flattened to their leaves). */
-    options: SelectItem[];
+    options: SelectItem<OptionValue>[];
     /** Add a search field atop this facet's flyout that filters its options. */
     filter?: FacetFilter;
 }
-/** Pick **any number** of options. Value: an array of the chosen `value`
- *  strings (empty array clears the facet). Options are the same `SelectItem`s
- *  as `single`. */
+/** Pick **any number** of options. Value: an array of the chosen `value`s
+ *  (empty array clears the facet). Options are the same `SelectItem`s as `single`,
+ *  with the same `string` / `number` / `boolean` value support. */
 export interface SelectFacetMultiple extends FacetBase {
     kind: 'multiple';
     /** The options — bare strings or `SelectOption`s (groups / submenus flattened). */
-    options: SelectItem[];
+    options: SelectItem<OptionValue>[];
     /** Add a search field atop this facet's flyout that filters its options. */
     filter?: FacetFilter;
     /** A "Select all" row that toggles every option. On by default — set `false`
@@ -75,9 +76,11 @@ export interface SelectFacetCustom<V = unknown> extends FacetBase {
 }
 /** One facet (dimension) of the filter, discriminated by `kind`. */
 export type SelectFacet = SelectFacetSingle | SelectFacetMultiple | SelectFacetText | SelectFacetCustom;
-/** The filter value: a facet key → that facet's value. Per kind the value is a
- *  `string` (single / text), a `string[]` (multiple), or your own `V` (custom).
- *  A cleared facet is absent from the record (not a falsy entry). */
+/** The filter value: a facet key → that facet's value. Per kind: an option value
+ *  (`string` / `number` / `boolean`) for `single`, a `string` for `text`, an array for
+ *  `multiple`, or your own `V` for `custom`. Values are stored and reported unchanged.
+ *  Typed loosely as `unknown` since facets in one control can hold different value
+ *  types; narrow per facet when you read it. A cleared facet is absent from the record. */
 export type SelectFacetedValue = Record<string, unknown>;
 /** Second argument to `onValueChange` — what changed. A single-facet edit
  *  carries `facet` / `kind` / the facet's new `value`; the "Clear all" row
@@ -122,8 +125,10 @@ export interface SelectFacetedProps extends Omit<BaseProps, 'children'> {
     value?: SelectFacetedValue;
     /** Initial value for the uncontrolled case (the wrapper then owns it). */
     defaultValue?: SelectFacetedValue;
-    /** Fires after any facet changes, with the new full value record and an
-     *  attrs snapshot of what changed. */
+    /** Fires after any facet changes. `value` is the whole new record (a facet key →
+     *  that facet's value; a cleared facet is absent). `attrs` says what changed:
+     *  `{ facet, kind, value }` for a single facet edit, or `{ all: true }` for the
+     *  "Clear all" row — narrow on `'all' in attrs` before reading `facet`. */
     onValueChange?: (value: SelectFacetedValue, attrs: SelectFacetedChangeAttrs) => void;
     /** Default trigger's button label.
      *  @defaultValue Filter */

package/dist/components/SelectFaceted.js

@@ -120,7 +120,7 @@ const SelectFaceted = (props) => {
   const optionRow = (facet, opt, keyPrefix = "") => {
     const shared = {
       icon: opt.icon,
-      label: opt.label ?? opt.value,
+      label: opt.label ?? String(opt.value),
       hint: opt.hint,
       tone: opt.tone,
       toneSelected,
@@ -151,7 +151,7 @@ const SelectFaceted = (props) => {
         selectionIndicator: "checkbox",
         selected: arr.includes(opt.value),
         onSelect: (e) => isolable && e?.altKey ? setFacet(facet, [opt.value]) : setFacet(facet, arr.includes(opt.value) ? arr.filter((v) => v !== opt.value) : [...arr, opt.value]),
-        children: tip && /* @__PURE__ */ jsx(Tooltip, { ...hintOnly ? { follow: true, delay: 700 } : {}, children: tip })
+        children: tip && /* @__PURE__ */ jsx(Tooltip, { follow: true, ...hintOnly ? { delay: 700 } : {}, children: tip })
       },
       `${keyPrefix}${opt.value}`
     );
@@ -196,7 +196,7 @@ const SelectFaceted = (props) => {
     const applied = current[facet.key] ?? "";
     const draft = drafts[facet.key] ?? applied;
     const apply = () => {
-      const next = draft.trim() || void 0;
+      const next = draft.trim() === "" ? void 0 : draft;
       if (next !== (applied || void 0)) setFacet(facet, next);
     };
     return (
@@ -312,7 +312,7 @@ const SelectFaceted = (props) => {
           searchable && rootQuery.trim() ? renderFlatResults() : facets.map((facet) => /* @__PURE__ */ jsxs(MenuItem, { submenu: true, icon: facet.icon, label: facet.label, children: [
             (() => {
               const s = summaryOf(facet);
-              return s != null ? /* @__PURE__ */ jsx(Tag, { size: "small", tone: "brand", children: s }) : null;
+              return s != null ? /* @__PURE__ */ jsx(Tag, { size: "small", tone: "brand", children: /* @__PURE__ */ jsx("span", { className: styles.summary, children: s }) }) : null;
             })(),
             renderEditor(facet)
           ] }, facet.key)),

package/dist/components/SelectFaceted.module.css

@@ -1 +1 @@
-.search{padding:var(--menu-padding, 4px)}.footer{padding:var(--menu-padding, 4px);border-top:1px solid var(--border-4)}
+.search{padding:var(--menu-padding, 4px)}.summary{display:block;max-width:160px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.footer{padding:var(--menu-padding, 4px);border-top:1px solid var(--border-4)}

package/dist/components/Text.d.ts

@@ -18,11 +18,11 @@ export type ExpandMode = {
     collapsible?: boolean;
 };
 export type TextProps = BaseProps & {
-    /** Visual priority. Maps to text-1..text-5 (`primary` = text-1, the
+    /** Visual priority. Maps to text-1..text-4 (`primary` = text-1, the
      *  strongest). The default is `secondary` (text-2) — body text reads a
      *  step softer than the strongest foreground; pass `primary` for emphasis.
      *  @defaultValue secondary */
-    priority?: 'primary' | 'secondary' | 'tertiary' | 'quaternary' | 'quinary';
+    priority?: 'primary' | 'secondary' | 'tertiary' | 'quaternary';
     /** Color tint. `neutral` (the default) is the untinted `--text-{N}` scale; a
      *  named tone applies the matching `--text-{N}-{tone}` palette. Any literal CSS
      *  color (`'#ff1493'`, `'rebeccapurple'`) is a one-off custom tone — its hue is

package/dist/components/Title.d.ts

@@ -5,9 +5,9 @@ export interface TitleProps extends BaseProps {
      *  (h1 is typically reserved for the page title).
      *  @defaultValue 2 */
     level?: 1 | 2 | 3 | 4 | 5 | 6;
-    /** Visual priority. Maps to text-1..text-5 (`primary` = text-1).
+    /** Visual priority. Maps to text-1..text-4 (`primary` = text-1).
      *  @defaultValue primary */
-    priority?: 'primary' | 'secondary' | 'tertiary' | 'quaternary' | 'quinary';
+    priority?: 'primary' | 'secondary' | 'tertiary' | 'quaternary';
     /** Color tint. `neutral` (the default) is the untinted `--text-{N}` scale; a
      *  named tone applies the matching `--text-{N}-{tone}` palette. Any literal CSS
      *  color (`'#ff1493'`, `'rebeccapurple'`) is a one-off custom tone — its hue is

package/dist/components/Toaster.d.ts

@@ -0,0 +1,48 @@
+import type { BaseProps } from "../general_types";
+import { type Toaster as ToasterStore } from "../toaster";
+export interface ToasterProps extends BaseProps {
+    /** The store this region renders. Omit to bind the default store driven by
+     *  `Toaster.manager`; pass a `createToaster()` for an isolated region. */
+    toaster?: ToasterStore;
+    /** Accessible label for the region landmark.
+     *  @defaultValue 'Notifications' */
+    label?: string;
+}
+/**
+ * `<Toaster>` — the mounted notification region. Keep one mounted somewhere in
+ * your app (a portal is fine); toasts are added imperatively through the store
+ * (`Toaster.manager`, or a `createToaster()` you pass as `toaster`). It
+ * subscribes to the store and renders each toast through the reconciler, so
+ * React/Preact owns the toast nodes.
+ *
+ * Announcement is opt-in **per toast** (`add(render, { politeness })`), not a
+ * blanket live region on the whole toaster.
+ *
+ * Requires `@antadesign/anta/elements` to be imported (client-side only) to
+ * register the underlying custom elements.
+ *
+ * @example
+ * ```tsx
+ * <Toaster />   // mount once, keep it mounted
+ *
+ * // A bare string is auto-wrapped in a dismissible Banner:
+ * Toaster.manager.add(() => 'Saved', { placement: 'bottom-right' })
+ *
+ * // Or toast a Banner yourself and wire its dismiss to the toast:
+ * Toaster.manager.add((id) => (
+ *   <Banner tone="success" message="Saved" onDismiss={() => Toaster.manager.dismiss(id)} />
+ * ))
+ * ```
+ */
+declare const ToasterImpl: ({ toaster, label, className, style, children: _children, ...rest }: ToasterProps) => any;
+/**
+ * The `<Toaster>` component, carrying the default toast store as a static:
+ * `Toaster.manager.add(render, opts)`. A function-with-a-static (like
+ * `Component.displayName`) — no class component, which would couple to a renderer.
+ */
+export declare const Toaster: typeof ToasterImpl & {
+    /** The default toast store, bound to a `<Toaster>` mounted with no `toaster`. */
+    readonly manager: ToasterStore;
+};
+export { createToaster } from "../toaster";
+export type { Toaster as ToasterManager, ToastOptions, ToastPlacement, ToastContent, ToastRender, } from "../toaster";

package/dist/components/Toaster.js

@@ -0,0 +1,56 @@
+import { jsx } from "@antadesign/anta/jsx-runtime";
+import { useMemo, useSyncExternalStore } from "../jsx-runtime";
+import { createToaster } from "../toaster";
+import { Banner } from "./Banner";
+const ToastItem = ({ entry, store }) => {
+  const content = useMemo(() => entry.render(entry.id), [entry.id, entry.rev]);
+  const isNode = typeof Node !== "undefined" && content instanceof Node;
+  const isText = typeof content === "string" || typeof content === "number";
+  const common = {
+    slot: entry.placement,
+    duration: entry.duration,
+    leaving: entry.leaving ? "" : void 0,
+    rev: entry.rev,
+    // Opt-in per-toast announcement. role=status/alert (not a bare aria-live) so
+    // it announces when inserted — a plain aria-live region must pre-exist before
+    // its content changes, which a freshly-added toast can't satisfy. Omitted (no
+    // announcement) unless requested.
+    role: entry.politeness === "assertive" ? "alert" : entry.politeness === "polite" ? "status" : void 0,
+    // Fires after the exit animation; that's when the entry actually leaves.
+    ondismiss: () => store.remove(entry.id)
+  };
+  if (isNode) return /* @__PURE__ */ jsx("a-toast", { ...common, content });
+  if (isText)
+    return /* @__PURE__ */ jsx("a-toast", { ...common, children: /* @__PURE__ */ jsx(
+      Banner,
+      {
+        round: true,
+        message: content,
+        dismissed: false,
+        onDismiss: () => store.dismiss(entry.id)
+      }
+    ) });
+  return /* @__PURE__ */ jsx("a-toast", { ...common, children: content });
+};
+const ToasterImpl = ({
+  toaster,
+  label = "Notifications",
+  className,
+  style,
+  // The region's children come from the store, not from JSX.
+  children: _children,
+  ...rest
+}) => {
+  const store = toaster ?? getDefaultStore();
+  const entries = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getServerSnapshot);
+  return /* @__PURE__ */ jsx("a-toaster", { role: "region", "aria-label": label, class: className, style, ...rest, children: entries.map((entry) => /* @__PURE__ */ jsx(ToastItem, { entry, store }, entry.id)) });
+};
+let defaultStore;
+const getDefaultStore = () => defaultStore ??= createToaster();
+const Toaster = ToasterImpl;
+Object.defineProperty(Toaster, "manager", { get: getDefaultStore, enumerable: true });
+import { createToaster as createToaster2 } from "../toaster";
+export {
+  Toaster,
+  createToaster2 as createToaster
+};

package/dist/components/Tooltip.d.ts

@@ -5,7 +5,7 @@ export interface TooltipProps extends BaseProps {
     children?: React.ReactNode;
     /** Show delay in milliseconds after hover / focus. Never use `0` — use
      *  ~`50` for a near-instant tooltip (0 has caused issues in practice).
-     *  @defaultValue 250 */
+     *  @defaultValue 300 */
     delay?: number;
     /** Which side of the anchor the bubble prefers. Auto-flips to the other
      *  side when there isn't room.