@igne-agency/react-web-ui 0.5.0 → 0.6.0

package/dist/components/combobox-field/combobox.d.ts

@@ -1,6 +1,7 @@
 import { Combobox as BaseCombobox } from "@base-ui/react/combobox";
 import { type ComponentProps, type ReactNode, type Ref } from "react";
-import { Field, type FieldState, type OptionsLoad, type OptionsLoadLabels } from "../field/index.ts";
+import { type ButtonProps as AriaButtonProps, type TagProps } from "react-aria-components";
+import { type FieldPendingProps, type FieldState, type OptionsLoad, type OptionsLoadLabels } from "../field/index.ts";
 import { type PagedQuery } from "./combobox-items.ts";
 export type ComboboxRootProps<TItem, TMultiple extends boolean | undefined = false> = Omit<BaseCombobox.Root.Props<TItem, TMultiple>, "autoHighlight"> & Readonly<{
     /** `"always"` highlights the first item whenever the list changes. @default "always" */
@@ -13,41 +14,124 @@ export type ComboboxControlProps = BaseCombobox.InputGroup.Props & Readonly<{
     ref?: Ref<HTMLDivElement>;
     /** The states projected onto the control as `data-*` attributes. */
     state?: FieldState;
-    /**
-     * The tags, beside the trigger. They show the selection, so the
-     * trigger's own value is read but not shown.
-     */
-    tags?: ReactNode;
-    /** The chevron at the end of the control, such as an expand icon. */
-    icon?: ReactNode;
 }>;
-/** The chevron at the end of the control. Its children are the icon; without them it renders nothing. */
+/**
+ * The chevron at the end of the trigger. Its children are the icon; without
+ * them it renders nothing.
+ *
+ * @example
+ * <Combobox.Icon><ExpandMoreIcon /></Combobox.Icon>
+ */
 declare const ComboboxIcon: ({ className, children, ...props }: BaseCombobox.Icon.Props) => ReactNode;
-/** The control that opens the popup: the value or the tags, the pending mark and `icon`. */
-declare const ComboboxControl: ({ className, children, tags, icon, state, ...props }: ComboboxControlProps) => ReactNode;
-export type ComboboxTagsProps<TItem> = Readonly<{
-    /** Names the group of tags, such as "Selected statuses". */
+/**
+ * The control's box, projecting `state` onto itself and holding the `Chips`
+ * and the `Trigger`. The positioner takes it as its `anchor`.
+ *
+ * @example
+ * <Combobox.Control ref={anchorRef} state={state}>
+ * 	<Combobox.Trigger>…</Combobox.Trigger>
+ * </Combobox.Control>
+ */
+declare const ComboboxControl: ({ className, children, state, ...props }: ComboboxControlProps) => ReactNode;
+export type ComboboxTriggerProps = BaseCombobox.Trigger.Props;
+/**
+ * The button that opens the popup, holding the value, `Pending` and `Icon`.
+ * The arrow keys move between it and the `Chips` beside it.
+ *
+ * @example
+ * <Combobox.Trigger>
+ * 	<Combobox.TriggerValue>{label}</Combobox.TriggerValue>
+ * 	<Combobox.Icon><ExpandMoreIcon /></Combobox.Icon>
+ * </Combobox.Trigger>
+ */
+declare const ComboboxTrigger: ({ className, onKeyDown, ...props }: ComboboxTriggerProps) => ReactNode;
+/**
+ * The value the trigger shows, such as the chosen item or the placeholder.
+ *
+ * @example
+ * <Combobox.TriggerValue>{label ?? placeholder}</Combobox.TriggerValue>
+ */
+declare const ComboboxTriggerValue: ({ className, ...props }: ComponentProps<"span">) => ReactNode;
+/**
+ * The value the trigger is read as while `Chips` show the selection, such as
+ * every chosen item joined. Only assistive tech reads it.
+ *
+ * @example
+ * <Combobox.SpokenValue>{names.join(", ")}</Combobox.SpokenValue>
+ */
+declare const ComboboxSpokenValue: ({ className, ...props }: ComponentProps<"span">) => ReactNode;
+/**
+ * What the trigger shows while the control's `state` is pending, such as a
+ * spinner. Renders nothing otherwise.
+ *
+ * @example
+ * <Combobox.Pending><Spinner size={1} /></Combobox.Pending>
+ */
+declare const ComboboxPending: (props: FieldPendingProps) => ReactNode;
+/**
+ * The area beside the trigger that shows the selection of a multiple
+ * combobox: a `ChipList`, or a placeholder while nothing is chosen. The arrow
+ * keys move from its first and last chip back to the trigger.
+ *
+ * @example
+ * <Combobox.Chips>
+ * 	<Combobox.ChipList …>…</Combobox.ChipList>
+ * </Combobox.Chips>
+ */
+declare const ComboboxChips: ({ className, onKeyDownCapture, ...props }: ComponentProps<"div">) => ReactNode;
+export type ComboboxChipListProps<TItem> = Readonly<{
+    /** Names the group of chips, such as "Selected statuses". */
     label: string;
     items: readonly TItem[];
-    /** A stable identity per item. */
+    /** A stable identity per item, which its `Chip` takes as its `id`. */
     itemKey: (item: TItem) => string;
-    /** An item as plain text, which its tag is read as. */
-    itemLabel: (item: TItem) => string;
-    /** The remove control's own name, which the tag's name completes, such as "Remove". */
-    removeLabel: string;
-    /** The remove control's tooltip for an item, such as "Remove Jan Jansen". */
-    removeHint: (item: TItem) => string;
-    /** The remove control's icon, such as a cross. */
-    removeIcon: ReactNode;
-    /** Renders one tag's content. */
+    /** Renders one item's `Chip`. */
     children: (item: TItem) => ReactNode;
     /** Called with the items left after a removal. */
     onRemove: (remaining: readonly TItem[]) => void;
     disabled?: boolean;
     readOnly?: boolean;
+    className?: string;
+}>;
+/**
+ * The chosen values of a multiple combobox as a grid of removable chips, over
+ * react-aria's `TagGroup`. Removing the last one returns focus to the trigger.
+ *
+ * @example
+ * <Combobox.ChipList label="Selected statuses" items={chosen} itemKey={status => status} onRemove={setChosen}>
+ * 	{status => <Combobox.Chip key={status} id={status} textValue={status}>{status}</Combobox.Chip>}
+ * </Combobox.ChipList>
+ */
+declare const ComboboxChipList: <TItem>({ label, items, itemKey, children, onRemove, disabled, readOnly, className, }: ComboboxChipListProps<TItem>) => ReactNode;
+export type ComboboxChipProps = Omit<TagProps, "className" | "id" | "textValue"> & Readonly<{
+    /** The item's key, as `ChipList`'s `itemKey` gives it. */
+    id: string;
+    /** The item as plain text, which the chip is read as. */
+    textValue: string;
+    className?: string;
+}>;
+/**
+ * One chosen value as a chip, holding its content and a `ChipRemove`.
+ *
+ * @example
+ * <Combobox.Chip id={status} textValue={status}>{status}</Combobox.Chip>
+ */
+declare const ComboboxChip: ({ className, ...props }: ComboboxChipProps) => ReactNode;
+export type ComboboxChipRemoveProps = Omit<AriaButtonProps, "className" | "slot" | "aria-label"> & Readonly<{
+    /** The button's own name, which the chip's name completes, such as "Remove". */
+    "aria-label": string;
+    className?: string;
 }>;
-/** The chosen values of a multiple combobox as removable tags, for `Control`'s `tags`. */
-declare const ComboboxTags: <TItem>({ label, items, itemKey, itemLabel, removeLabel, removeHint, removeIcon, children, onRemove, disabled, readOnly, }: ComboboxTagsProps<TItem>) => ReactNode;
+/**
+ * The pointer-only button that removes its chip; the keyboard removes with
+ * Delete. Its children are the icon, such as a cross.
+ *
+ * @example
+ * <Tooltip content="Remove Open">
+ * 	<Combobox.ChipRemove aria-label="Remove"><CloseIcon /></Combobox.ChipRemove>
+ * </Tooltip>
+ */
+declare const ComboboxChipRemove: ({ className, ...props }: ComboboxChipRemoveProps) => ReactNode;
 /** Places the popup against the control, given as its `anchor`. */
 declare const ComboboxPositioner: ({ className, sideOffset, ...props }: BaseCombobox.Positioner.Props) => ReactNode;
 /** The shared popup surface. */
@@ -71,12 +155,24 @@ declare const ComboboxList: ({ className, query, ...props }: ComboboxListProps)
 export type ComboboxOptionProps = BaseCombobox.Item.Props;
 /** One option's row, holding its `OptionIndicator` and `OptionText`. */
 declare const ComboboxOption: ({ className, ...props }: ComboboxOptionProps) => ReactNode;
-export type ComboboxOptionIndicatorProps = BaseCombobox.ItemIndicator.Props & Readonly<{
-    /** Draws the mark inside a checkbox, for a multi-value list. */
-    multiple?: boolean;
-}>;
-/** The mark beside a chosen option. Its children are the mark, such as a tick. */
-declare const ComboboxOptionIndicator: ({ className, multiple, ...props }: ComboboxOptionIndicatorProps) => ReactNode;
+export type ComboboxOptionIndicatorProps = BaseCombobox.ItemIndicator.Props;
+/**
+ * The mark beside a chosen option. Its children are the mark, such as a tick.
+ * Inside an `OptionCheckbox` it is the checkbox's tick, kept mounted.
+ *
+ * @example
+ * <Combobox.OptionIndicator><CheckIcon /></Combobox.OptionIndicator>
+ */
+declare const ComboboxOptionIndicator: ({ className, ...props }: ComboboxOptionIndicatorProps) => ReactNode;
+/**
+ * The box an option's `OptionIndicator` sits in, for a multi-value list.
+ *
+ * @example
+ * <Combobox.OptionCheckbox>
+ * 	<Combobox.OptionIndicator><CheckIcon /></Combobox.OptionIndicator>
+ * </Combobox.OptionCheckbox>
+ */
+declare const ComboboxOptionCheckbox: ({ className, children, ...props }: ComponentProps<"span">) => ReactNode;
 /** An option's content, beside its indicator. */
 declare const ComboboxOptionText: ({ className, ...props }: ComponentProps<"span">) => ReactNode;
 /** What the popup says when no option is listed. */
@@ -116,7 +212,7 @@ export type ComboboxBodyProps<TItem> = ComboboxPopupLabels & Readonly<{
     query?: PagedQuery<TItem>;
     /** There are no items at all, rather than none matching the search. */
     noOptions: boolean;
-    /** Draws each option's mark inside a checkbox. */
+    /** Draws each option's mark inside an `OptionCheckbox`. */
     multiple?: boolean;
     /** A stable identity per item. */
     itemKey: (item: TItem) => string;
@@ -132,36 +228,49 @@ export type ComboboxBodyProps<TItem> = ComboboxPopupLabels & Readonly<{
  */
 declare const ComboboxBody: <TItem>({ load, query, noOptions, multiple, itemKey, checkIcon, children, ...labels }: ComboboxBodyProps<TItem>) => ReactNode;
 /** The parts of a combobox. */
-export type ComboboxParts = Omit<typeof BaseCombobox, "Root" | "Icon" | "Positioner" | "Popup" | "Input" | "List" | "Empty" | "Status"> & Readonly<{
+export type ComboboxParts = Omit<typeof BaseCombobox, "Root" | "Icon" | "Trigger" | "Chips" | "Chip" | "ChipRemove" | "Positioner" | "Popup" | "Input" | "List" | "Empty" | "Status"> & Readonly<{
     Root: typeof ComboboxRoot;
     Control: typeof ComboboxControl;
+    Trigger: typeof ComboboxTrigger;
+    TriggerValue: typeof ComboboxTriggerValue;
+    SpokenValue: typeof ComboboxSpokenValue;
     Icon: typeof ComboboxIcon;
-    Tags: typeof ComboboxTags;
+    Chips: typeof ComboboxChips;
+    ChipList: typeof ComboboxChipList;
+    Chip: typeof ComboboxChip;
+    ChipRemove: typeof ComboboxChipRemove;
     Positioner: typeof ComboboxPositioner;
     Popup: typeof ComboboxPopup;
     Search: typeof ComboboxSearch;
     List: typeof ComboboxList;
     Option: typeof ComboboxOption;
     OptionIndicator: typeof ComboboxOptionIndicator;
+    OptionCheckbox: typeof ComboboxOptionCheckbox;
     OptionText: typeof ComboboxOptionText;
     Empty: typeof ComboboxEmpty;
     Status: typeof ComboboxStatus;
     StatusArea: typeof ComboboxStatusArea;
     LoadStatus: typeof ComboboxLoadStatus;
     Body: typeof ComboboxBody;
-    Pending: typeof Field.Pending;
+    Pending: typeof ComboboxPending;
 }>;
 /**
  * The styled parts of a base-ui Combobox: a filterable select whose control
  * matches `Select`'s trigger and whose popup is the shared popup surface. Every
- * unstyled base-ui part stays reachable. `Body` holds what the popup usually
- * does. For the ordinary case, use `ComboboxField`. The positioner takes the
+ * unstyled base-ui part stays reachable. A multiple combobox shows its
+ * selection as `Chips` beside the `Trigger`. `Body` holds what the popup
+ * usually does. For the ordinary case, use `ComboboxField`. The positioner takes the
  * control as its `anchor`.
  *
  * @example
  * <Combobox.Root items={statuses}>
- * 	<Combobox.Control ref={anchorRef} icon={<ExpandMoreIcon />}>
- * 		<Combobox.Value>{(status: string | null) => status}</Combobox.Value>
+ * 	<Combobox.Control ref={anchorRef}>
+ * 		<Combobox.Trigger>
+ * 			<Combobox.TriggerValue>
+ * 				<Combobox.Value>{(status: string | null) => status}</Combobox.Value>
+ * 			</Combobox.TriggerValue>
+ * 			<Combobox.Icon><ExpandMoreIcon /></Combobox.Icon>
+ * 		</Combobox.Trigger>
  * 	</Combobox.Control>
  * 	<Combobox.Portal>
  * 		<Combobox.Positioner anchor={anchorRef}>