@antadesign/anta 0.3.18 → 0.3.20

package/dist/components/InputDate.js

@@ -1,5 +1,4 @@
 import { Fragment, jsx, jsxs } from "@antadesign/anta/jsx-runtime";
-import cn from "clsx";
 import { useMemo, useState } from "../jsx-runtime";
 import { Temporal } from "temporal-polyfill";
 import {
@@ -18,7 +17,7 @@ import { Calendar } from "./Calendar";
 import { Button } from "./Button";
 import { Icon } from "./Icon";
 import { InputTime } from "./InputTime";
-import styles from "./InputDate.module.css";
+import "./InputDate.css";
 const InputDate = ({
   value,
   defaultValue,
@@ -147,7 +146,8 @@ const InputDate = ({
             if (resolve(e.currentTarget.value)) setOpen(false);
           }
         },
-        className: cn(styles.dateField, className),
+        truncate: true,
+        className,
         style,
         ...rest
       }
@@ -159,7 +159,7 @@ const InputDate = ({
         placement: placement ?? "bottom-start",
         offset,
         autoWidth: true,
-        className: styles.calendarMenu,
+        inset: 8,
         onStateChange: (_e, { next }) => setOpen(next),
         children: /* @__PURE__ */ jsxs("div", { "data-menu-open": "", children: [
           /* @__PURE__ */ jsx(
@@ -180,7 +180,7 @@ const InputDate = ({
               }
             }
           ),
-          time && /* @__PURE__ */ jsxs("div", { className: styles.timeRow, children: [
+          time && /* @__PURE__ */ jsxs("a-input-date-time-container", { children: [
             /* @__PURE__ */ jsx(
               InputTime,
               {

package/dist/components/InputTime.d.ts

@@ -16,7 +16,7 @@ export interface InputTimeChangeAttrs {
 }
 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). */
+     *  a `<Tooltip>` takes no space and anchors to the field). */
     children?: React.ReactNode;
     /** Field label, shown above the control and used as the segment group's
      *  accessible name. */
@@ -29,7 +29,7 @@ export interface InputTimeProps extends BaseProps, DOMEventHandlers {
     /** 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
+    /** Custom accent color — any literal CSS color 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.
@@ -87,7 +87,7 @@ export interface InputTimeProps extends BaseProps, DOMEventHandlers {
  * behave as one control: each is a native text input — ↑/↓ steps with wrap,
  * ←/→ crosses segments at caret boundaries, typing digits auto-advances, and
  * AM/PM accepts its locale text or `a`/`p`. Renders an `<a-input-time>` web
- * component that owns the segments, navigation, and form value (via
+ * component that manages the segments, navigation, and form value (via
  * `ElementInternals`).
  *
  * The clock and layout follow the locale (`en-US` → 12-hour, most others 24),

package/dist/components/InputTime.js

@@ -79,7 +79,7 @@ const InputTime = ({
       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
+        clearable && // Real <a-button> in the element's `clear` slot; the element controls 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

package/dist/components/Menu.d.ts

@@ -28,6 +28,10 @@ export interface MenuProps extends BaseProps {
      *  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;
+    /** Inner inset for the scroll body and named header/footer content. A number is
+     * pixels; a CSS length string is used as written.
+     * @defaultValue 4 */
+    inset?: number | string;
     /** 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,7 +57,7 @@ export interface MenuProps extends BaseProps {
     /** Combobox-mode cursor report (raw element event). Fires when the active
      *  option changes as arrow keys move the cursor while focus stays in a
      *  `[data-menu-search]` filter field; `detail.id` is the active option's `id`
-     *  (`null` when none). The reactive layer that owns the field reflects this
+     *  (`null` when none). The reactive layer that renders the field reflects this
      *  onto its `aria-activedescendant` — the element can't write that light-DOM
      *  attribute itself. Passed straight through to the element. */
     onactivedescendant?: (e: CustomEvent<{
@@ -74,7 +78,7 @@ export interface MenuProps extends BaseProps {
  *
  * Open state is uncontrolled by default — listen for `onStateChange`
  * (`detail: { next, prev }`) to observe it, or pass `open` to control it. You
- * can also grab a `ref` and call `.open()` / `.close()` / `.toggle()`.
+ * can also keep a `ref` and call `.open()` / `.close()` / `.toggle()`.
  * Selecting a `MenuItem` closes the menu;
  * arbitrary injected content does not. Add `data-menu-open` to any item /
  * container to keep it open, or `data-menu-close` to a custom element to let it
@@ -92,4 +96,4 @@ export interface MenuProps extends BaseProps {
  * </Menu>
  * ```
  */
-export declare const Menu: ({ placement, context, coord, nohover, offset, autoWidth, open, onStateChange, round, role, className, style, children, ...rest }: MenuProps) => any;
+export declare const Menu: ({ placement, context, coord, nohover, offset, autoWidth, inset, open, onStateChange, round, role, className, style, children, ...rest }: MenuProps) => any;

package/dist/components/Menu.js

@@ -1,5 +1,5 @@
 import { jsx } from "@antadesign/anta/jsx-runtime";
-import { nativeStateChange, roundStyle, roundAttr } from "../anta_helpers";
+import { nativeStateChange, lengthStyle, roundStyle, roundAttr } from "../anta_helpers";
 const Menu = ({
   placement,
   context,
@@ -7,6 +7,7 @@ const Menu = ({
   nohover,
   offset,
   autoWidth,
+  inset,
   open,
   onStateChange,
   round,
@@ -38,7 +39,7 @@ const Menu = ({
       role,
       "aria-orientation": "vertical",
       class: className,
-      style: roundStyle(round, "--menu-round", style),
+      style: lengthStyle(inset, "--menu-padding", roundStyle(round, "--menu-round", style)),
       ...rest,
       children
     }

package/dist/components/MenuItem.d.ts

@@ -111,7 +111,7 @@ export type MenuItemActionMode = {
      *  `selectionIndicator` to keep the semantics — the row stays the control and
      *  carries `role` + `aria-checked`; only the drawn mark changes. Suppresses the
      *  built-in checkbox / radio and the trailing `check` glyph. The node is made
-     *  passive (aria-hidden, no pointer events) so the row owns the click. */
+     *  passive (aria-hidden, no pointer events) so the row receives the click. */
     indicator?: React.ReactNode;
 };
 export type MenuItemProps = MenuItemCommonProps & (MenuItemLinkMode | MenuItemActionMode);

package/dist/components/MenuItem.js

@@ -81,7 +81,7 @@ const MenuItem = ({
       ...rest,
       children: [
         indicator != null ? (
-          // `min-height: 1lh` makes the wrapper one text line tall and centres the node
+          // `min-height: 1lh` makes the wrapper one text line tall and centers the node
           // in it, so a small indicator aligns with the label's first line in a hinted
           // (top-aligned) row instead of riding at the top.
           /* @__PURE__ */ jsx(

package/dist/components/Progress.d.ts

@@ -6,7 +6,7 @@ export interface ProgressProps extends BaseProps {
     /** Upper bound of the range.
      *  @defaultValue 100 */
     max?: number;
-    /** Colour variant, or any literal CSS colour for a one-off custom tone (the
+    /** Color variant, or any literal CSS color for a one-off custom tone (the
      *  surface / indicator / text are derived from it in oklch). Named tones track
      *  light/dark automatically.
      *  @defaultValue 'neutral' */

package/dist/components/RadioGroup.d.ts

@@ -37,12 +37,11 @@ export interface RadioGroupProps extends Omit<BaseProps, "children" | "onChange"
     /** The options. The wrapper renders one `<a-radio>` per entry and computes its
      *  `selected` / roving `tabindex` / `role` declaratively. */
     options: RadioOption[];
-    /** Controlled selected value. When provided, the consumer owns selection: the
-     *  group follows this prop and a pick only *requests* a change via
-     *  `onStateChange` (reject by not updating). Leave undefined for uncontrolled. */
+    /** Controlled selected value. The group follows this prop and reports a
+     *  requested change through `onStateChange`. Leave it undefined for
+     *  uncontrolled use. */
     value?: string;
-    /** Initial selected value for the uncontrolled case (the wrapper then owns the
-     *  selection in local state). */
+    /** Initial selected value for uncontrolled use. */
     defaultValue?: string;
     /** Fired whenever selection changes — event-first. `detail` is
      *  `{ next, prev, reason }`: `next`/`prev` are values (`null` = nothing selected);
@@ -56,8 +55,8 @@ export interface RadioGroupProps extends Omit<BaseProps, "children" | "onChange"
      *  counterpart to `onStateChange`). Not cancelable; for a controlled group it
      *  fires once you've updated `value`. */
     onChange?: (event: Event) => void;
-    /** Like `onChange`, but with a `{ value, name }` snapshot as the 2nd argument —
-     *  the ergonomic "just give me the new value" callback (mirrors `Input`). */
+    /** Like `onChange`, but with a `{ value, name }` snapshot as the second argument,
+     *  matching `Input`. */
     onValueChange?: (event: Event, attrs: RadioChangeAttrs) => void;
     /** Fired when focus enters the group (any option) — wired to `focusin`, since
      *  focus lands on an individual option, not the group element itself. */
@@ -73,19 +72,19 @@ export interface RadioGroupProps extends Omit<BaseProps, "children" | "onChange"
      *  the options) — typically instructional copy. Per-option helper text goes on
      *  the option's own `hint` instead. */
     hint?: string;
-    /** Validation/feedback tone for the group `hint` — recolours it (same tone set
+    /** Validation/feedback tone for the group `hint` — recolors it (same tone set
      *  as `Input`'s `status`). Use `critical` for an error message, etc.; omit for
      *  the neutral default.
      *  @defaultValue 'neutral' */
     status?: "neutral" | "brand" | "info" | "success" | "warning" | "critical";
     /** Mark tone applied to every option (an option's own `tone` wins), or any literal
-     *  CSS color for a one-off custom tone. Colours the selected-ring fill + dot *and*
+     *  CSS color for a one-off custom tone. Colors the selected-ring fill + dot *and*
      *  the unselected ring border. Named tones track light/dark mode. Use `toneSelected`
      *  instead to tone only the selected option and leave the rest neutral. The option
-     *  text stays neutral — recolour it in plain CSS via the `--text-N-{tone}` tokens.
+     *  text stays neutral — recolor it in plain CSS via the `--text-N-{tone}` tokens.
      *  @defaultValue 'neutral' */
     tone?: "brand" | "neutral" | "info" | "success" | "warning" | "critical" | (string & {});
-    /** Like `tone`, but coloured onto the **selected option only** — every unselected
+    /** Like `tone`, but colored onto the **selected option only** — every unselected
      *  ring stays neutral grey. Applied to every option (an option's own `toneSelected`
      *  wins). Prefer this over `tone` when a resting tinted border would read as a
      *  validation state.
@@ -104,8 +103,8 @@ export interface RadioGroupProps extends Omit<BaseProps, "children" | "onChange"
  * `<RadioGroup>` — a single-select radio control, rendered from `options`.
  *
  * This wrapper is convenience over the web components: it renders an `<a-radio>`
- * per option and, crucially, owns the two **declarative** DOM concerns the
- * elements deliberately don't touch — the roving **`tabindex`** (so keyboard Tab
+ * per option and manages the two **declarative** DOM concerns the elements
+ * deliberately do not touch: the roving **`tabindex`** (so keyboard Tab
  * lands on the right option) and each radio's **`role`**. Selection itself lives
  * in `<a-radio-group>` off-DOM (it sets each radio's `selected` property), so the
  * elements never mutate the DOM; this wrapper just reflects the current value into

package/dist/components/Select.d.ts

@@ -1,6 +1,7 @@
 import type { BaseProps } from '../general_types';
 import type { IconShape } from '../elements/a-icon.shapes';
 import { type MenuProps } from './Menu';
+import './select-parts.css';
 /** 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
@@ -34,7 +35,7 @@ export interface SelectOption<V extends OptionValue = string> {
      *  hint for the Alt/Option-click "select only this" accelerator; set `tooltip`
      *  to override that, or `''` to suppress it. */
     tooltip?: React.ReactNode;
-    /** Your own data — attach anything and read it in `renderOption`. */
+    /** Additional application data. Read it in `renderOption`. */
     [key: string]: unknown;
 }
 /** A titled group of options rendered **inline** under a heading (like `MenuGroup`).
@@ -163,10 +164,9 @@ export interface SelectCommonProps<V extends OptionValue = string> extends Omit<
      *  `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`. */
+    /** Content for the default trigger's `leading` slot, such as a key prefix
+     *  before the value. It replaces the icon derived from `icon`. Include an
+     *  `<Icon>` in this content when both are needed. Ignored by `renderTrigger`. */
     leading?: React.ReactNode;
     /** Field label, above the trigger (Input's `label`). */
     label?: string;
@@ -196,11 +196,10 @@ export interface SelectCommonProps<V extends OptionValue = string> extends Omit<
      *  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<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
-     *  `multiple` mode — set `false` to drop the row (and with it the Alt/⌥-click
-     *  isolate accelerator it gates).
+    /** `multiple` only: shows a "Select all" row that toggles every enabled option,
+     *  or only the visible options when a filter query is active. Its checkbox is
+     *  mixed when some options are selected. It is on by default. Set it to `false`
+     *  to remove the row and the Alt/Option-click shortcut that selects only one row.
      *  @defaultValue true */
     selectAll?: boolean;
     /** Label for the `selectAll` row.
@@ -213,13 +212,12 @@ export interface SelectCommonProps<V extends OptionValue = string> extends Omit<
     /** 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
-     *  fields off the option (see `SelectOption`'s index signature) plus an
-     *  `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. */
+    /** Replaces the built-in `label`, `hint`, and `icon` layout for each option row.
+     *  Select still supplies the row container, click handling, ARIA attributes, and
+     *  selection indicator. Read extra option fields through `SelectOption`'s index
+     *  signature. `state` contains `value`, `selected`, and `disabled`. Filtering
+     *  still matches the option's `value`, `label`, and `hint`, but Select cannot
+     *  highlight matches within the returned content. */
     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
@@ -245,16 +243,15 @@ export interface SelectCommonProps<V extends OptionValue = string> extends Omit<
      *  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) —
-     *  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 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. */
+    /** Replaces the default field with a trigger returned from this function.
+     *  Receives `open`, `value`, `selected`, `disabled`, and `icon`. Return exactly
+     *  one focusable element, such as an Anta `Button`. The menu is positioned
+     *  relative to that element and opens when it is clicked. Do not return a
+     *  fragment, multiple siblings, or a non-focusable wrapper. Add
+     *  `aria-haspopup="menu"` and `aria-expanded={state.open}` to the element.
+     *  Field props (`label`, `hint`, `size`, `status`, `placeholder`, and `round`) and
+     *  `className` / `style` apply only to the default field. Add styling and
+     *  attributes to the returned element instead. */
     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
@@ -275,13 +272,10 @@ export type SelectProps<V extends OptionValue = string> = SelectCommonProps<V> &
      *  array value.
      *  @defaultValue single */
     selection?: 'single';
-    /** 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. */
+    /** Controlled value: the selected option's `value`. Update it through
+     *  `onValueChange`. Leave it undefined for uncontrolled use. */
     value?: V;
-    /** Initial value (an option's `value`) for the uncontrolled case — the
-     *  wrapper then owns it. */
+    /** Initial selected option value for uncontrolled use. */
     defaultValue?: V;
     /** Fires after the selection changes, with the new value and a
      *  `{ value, option }` snapshot. Select has no discrete element state, so
@@ -351,17 +345,17 @@ export type SelectedItem<V extends OptionValue = string> = SelectedOption<V> | S
  */
 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:
+ * `<Select>` lets people choose one or more options from a dropdown. It uses an
+ * `<Input>` as its read-only trigger and a `<Menu>` for its options. `selection` sets behavior:
  * `'single'` (default; `value` is a string, menu closes on pick) or `'multiple'`
  * (checkboxes, `value` is a string array, menu stays open while toggling, the
  * field shows an "N selected" count). For single-select, `indicator` picks the
  * per-row mark: `'none'` (tint only, default), `'check'` (trailing checkmark), or
  * `'radio'` (leading radio).
  *
- * Controlled (`value` + `onValueChange`) or uncontrolled (`defaultValue`). There
- * is no `a-select` element — this wrapper is the coordinator; for a non-React
- * equivalent, hand-compose the same pieces (see the docs).
+ * Use `value` with `onValueChange` to control the selection, or use
+ * `defaultValue` for uncontrolled use. There is no `a-select` element. See the
+ * docs for the equivalent markup without React or Preact.
  *
  * Requires `@antadesign/anta/elements` (client-side only).
  *

package/dist/components/Select.js

@@ -9,7 +9,7 @@ import { MenuItem } from "./MenuItem";
 import { MenuGroup } from "./MenuGroup";
 import { MenuSeparator } from "./MenuSeparator";
 import { Tooltip } from "./Tooltip";
-import styles from "./Select.module.css";
+import "./select-parts.css";
 function optionsWithSelection(options, values) {
   const set = new Set(values == null ? [] : Array.isArray(values) ? values : [values]);
   const state = (on, total) => on === 0 ? "none" : on === total ? "all" : "some";
@@ -269,16 +269,9 @@ const Select = (props) => {
         "aria-haspopup": "menu",
         "aria-expanded": open ? "true" : "false",
         trailing: (
-          // Chevron rotates down → up when open (spacing + rotation in the CSS
-          // module, matching the Input "Select dropdown" example).
-          /* @__PURE__ */ jsx(
-            Icon,
-            {
-              shape: "chevron-down",
-              className: open ? `${styles.chevron} ${styles.open}` : styles.chevron,
-              style: statusColor ? { color: statusColor } : void 0
-            }
-          )
+          // The named tag applies the Select-specific rotation while the icon remains
+          // a normal currentColor glyph.
+          /* @__PURE__ */ jsx("a-select-chevron", { open: open ? "" : void 0, style: statusColor ? { color: statusColor } : void 0, children: /* @__PURE__ */ jsx(Icon, { shape: "chevron-down" }) })
         ),
         className,
         style,
@@ -302,7 +295,7 @@ const Select = (props) => {
           filtering && // `slot="header"` pins the field in the Menu's fixed header region (above
           // the scrolling options); `data-menu-search` puts the menu in combobox
           // mode — it focuses this field on open and drives an active-option cursor.
-          /* @__PURE__ */ jsx("div", { className: styles.filter, slot: "header", "data-menu-open": "", children: /* @__PURE__ */ jsx(
+          /* @__PURE__ */ jsx("a-select-header", { slot: "header", "data-menu-open": "", children: /* @__PURE__ */ jsx(
             Input,
             {
               "data-menu-search": "",
@@ -332,7 +325,10 @@ const Select = (props) => {
           ] }),
           visibleLeaves.length === 0 ? renderEmpty?.({ query: q }) : flattening ? renderFlat() : renderTree(options, false),
           clearable && selectedValues.length > 0 && // Pinned in the footer so it never scrolls away in a long / filtered list.
-          /* @__PURE__ */ jsx("div", { slot: "footer", className: styles.footer, children: /* @__PURE__ */ jsx(MenuItem, { icon: "x", label: clearLabel, "data-menu-open": "", onSelect: clear }) })
+          /* @__PURE__ */ jsxs(Fragment, { children: [
+            /* @__PURE__ */ jsx(MenuSeparator, { slot: "footer" }),
+            /* @__PURE__ */ jsx("a-select-footer", { slot: "footer", children: /* @__PURE__ */ jsx(MenuItem, { icon: "x", label: clearLabel, "data-menu-open": "", onSelect: clear }) })
+          ] })
         ]
       }
     )

package/dist/components/SelectFaceted.d.ts

@@ -2,10 +2,10 @@ import type { BaseProps } from '../general_types';
 import type { IconShape } from '../elements/a-icon.shapes';
 import type { OptionValue, SelectItem, SelectOption } from './Select';
 import { type MenuProps } from './Menu';
+import './select-parts.css';
 interface FacetBase {
-    /** The facet's namespace — the key its value is stored under in the value
-     *  record, and what `onValueChange`'s `attrs.facet` reports. Unique across
-     *  `facets`. */
+    /** The key for this facet's value in the record. `onValueChange` reports it as
+     *  `attrs.facet`. It must be unique across `facets`. */
     key: string;
     /** The facet's row label in the menu. */
     label: string;
@@ -62,9 +62,8 @@ export interface SelectFacetCustomContext<V> {
     /** Close the whole filter menu (e.g. after applying from a custom editor). */
     close: () => void;
 }
-/** Bring your own editor and value type — the escape hatch for anything the
- *  built-in kinds don't cover, including object-shaped values (a date range, a
- *  numeric comparator, …). */
+/** A custom editor and value type for values the built-in kinds do not cover,
+ *  including objects such as date ranges and numeric comparisons. */
 export interface SelectFacetCustom<V = unknown> extends FacetBase {
     kind: 'custom';
     /** Render the facet's editor inside its flyout. The returned node stays
@@ -74,11 +73,11 @@ export interface SelectFacetCustom<V = unknown> extends FacetBase {
      *  string or any node). Called only when the value is set. */
     summary: (value: V) => React.ReactNode;
 }
-/** One facet (dimension) of the filter, discriminated by `kind`. */
+/** One filter category, discriminated by `kind`. */
 export type SelectFacet = SelectFacetSingle | SelectFacetMultiple | SelectFacetText | SelectFacetCustom;
 /** 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.
+ *  `multiple`, or a `V` value 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>;
@@ -110,7 +109,7 @@ export interface SelectFacetedTriggerState {
     disabled: boolean;
 }
 export interface SelectFacetedProps extends Omit<BaseProps, 'children'> {
-    /** The facets (dimensions) to filter across, each with its own editor kind. */
+    /** Categories to filter by. Each facet has a `kind` that determines its editor. */
     facets: SelectFacet[];
     /** Preferred placement of the root filter menu relative to its trigger. The
      *  menu auto-flips vertically and clamps horizontally when needed.
@@ -119,11 +118,10 @@ export interface SelectFacetedProps extends Omit<BaseProps, 'children'> {
     /** Gap in pixels between the trigger and the filter menu.
      *  @defaultValue 4 */
     offset?: number;
-    /** Controlled value — the facet-keyed record. When provided, the consumer
-     *  owns state: a pick only *requests* a change via `onValueChange` (reject by
-     *  not updating). Leave undefined for uncontrolled. */
+    /** Controlled value record, keyed by facet. When provided, update it through
+     *  `onValueChange`. Leave it undefined for uncontrolled use. */
     value?: SelectFacetedValue;
-    /** Initial value for the uncontrolled case (the wrapper then owns it). */
+    /** Initial value for uncontrolled use. */
     defaultValue?: SelectFacetedValue;
     /** 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:
@@ -146,14 +144,13 @@ export interface SelectFacetedProps extends Omit<BaseProps, 'children'> {
     disabled?: boolean;
     /** Tone applied to a selected option row in the facet flyouts (label, selected
      *  tint, and the check / checkbox indicator). A named tone or a custom CSS
-     *  colour, matching `Select`'s `toneSelected`. Defaults to a neutral selection. */
+     *  color, matching `Select`'s `toneSelected`. Defaults to a neutral selection. */
     toneSelected?: 'neutral' | 'brand' | 'info' | 'success' | 'warning' | 'critical' | (string & {});
-    /** Add a single search field to the top of the root menu that flattens every
-     *  `single` / `multiple` facet's options into one list and searches across them
-     *  — typing "alice" surfaces it under both an Assignee and an Owner facet, each
-     *  selectable in place. `text` / `custom` facets are reachable when the search is
-     *  empty. Matching uses each facet's `filter` function if it has one, else the
-     *  built-in substring match. */
+    /** Adds a search field at the top of the root menu. It searches the options of
+     *  every `single` and `multiple` facet in one list. For example, "alice" can
+     *  appear under application-defined Assignee and Owner facets. `text` and
+     *  `custom` facets remain available when the search is empty. Each facet uses
+     *  its `filter` function when supplied, or the built-in substring match. */
     searchable?: boolean;
     /** Placeholder for the global search field.
      *  @defaultValue Filter… */
@@ -164,22 +161,20 @@ export interface SelectFacetedProps extends Omit<BaseProps, 'children'> {
     /** Label for the "Clear all" row.
      *  @defaultValue Clear all */
     clearAllLabel?: string;
-    /** Render your own trigger in place of the default `Button`. Receives a
-     *  `SelectFacetedTriggerState`; **return exactly one focusable element** (the
-     *  menu anchors to it as its previous sibling and opens it on click). Give it
-     *  `aria-haspopup="menu"` plus `aria-expanded={state.open}`. The custom trigger
-     *  owns its own styling — `className` / `style` / other props apply to the
-     *  *default* trigger only, so put your own on the element you return. */
+    /** Replaces the default `Button` with a trigger returned from this function.
+     *  Receives a `SelectFacetedTriggerState`. Return exactly one focusable element:
+     *  the menu is positioned relative to that element and opens when it is clicked.
+     *  Add `aria-haspopup="menu"` and `aria-expanded={state.open}` to the returned
+     *  element. `className`, `style`, and other trigger props apply only to the
+     *  default Button, so add styling and attributes to the returned element. */
     renderTrigger?: (state: SelectFacetedTriggerState) => React.ReactNode;
 }
 /**
- * `<SelectFaceted>` — a faceted filter: one trigger opens a menu of facets
- * (dimensions), each a submenu flyout with its own editor. Facet kinds:
- * `'single'` (pick one), `'multiple'` (pick many), `'text'` (free-form
- * substring, applied on Enter / blur), and `'custom'` (bring your own editor +
- * value, including object-shaped values). The value is a
- * `Record<facetKey, value>`, so the same option value under two facets stays
- * distinct.
+ * `<SelectFaceted>` filters a result set by categories called facets. Its
+ * trigger opens a facet menu, and each facet opens a control for its value.
+ * The available kinds are `'single'`, `'multiple'`, `'text'`, and `'custom'`.
+ * The value is a `Record<facetKey, value>`, so values under different facet
+ * keys stay distinct.
  *
  * Controlled (`value` + `onValueChange`) or uncontrolled (`defaultValue`).
  * There is no `a-select-faceted` element — this wrapper is the coordinator.