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

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

@@ -1,10 +1,12 @@
 import { Combobox as BaseCombobox } from "@base-ui/react/combobox";
 import { type ComponentProps, type ReactNode, type Ref } from "react";
-import { Field, type FieldState } from "../field/index.ts";
+import { Field, 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" */
     autoHighlight?: boolean | "always";
 }>;
+/** The combobox's state, holding its items and its value. */
 declare const ComboboxRoot: <TItem, TMultiple extends boolean | undefined = false>({ autoHighlight, ...props }: ComboboxRootProps<TItem, TMultiple>) => ReactNode;
 export type ComboboxControlProps = BaseCombobox.InputGroup.Props & Readonly<{
     /** The control element, which the positioner takes as its `anchor`. */
@@ -16,8 +18,13 @@ export type ComboboxControlProps = BaseCombobox.InputGroup.Props & Readonly<{
      * 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;
 }>;
-declare const ComboboxControl: ({ className, children, tags, state, ...props }: ComboboxControlProps) => ReactNode;
+/** The chevron at the end of the control. Its children are the icon; without them it renders nothing. */
+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". */
     label: string;
@@ -30,6 +37,8 @@ export type ComboboxTagsProps<TItem> = Readonly<{
     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. */
     children: (item: TItem) => ReactNode;
     /** Called with the items left after a removal. */
@@ -37,8 +46,11 @@ export type ComboboxTagsProps<TItem> = Readonly<{
     disabled?: boolean;
     readOnly?: boolean;
 }>;
-declare const ComboboxTags: <TItem>({ label, items, itemKey, itemLabel, removeLabel, removeHint, children, onRemove, disabled, readOnly, }: ComboboxTagsProps<TItem>) => ReactNode;
+/** 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;
+/** Places the popup against the control, given as its `anchor`. */
 declare const ComboboxPositioner: ({ className, sideOffset, ...props }: BaseCombobox.Positioner.Props) => ReactNode;
+/** The shared popup surface. */
 declare const ComboboxPopup: ({ className, ...props }: BaseCombobox.Popup.Props) => ReactNode;
 export type ComboboxSearchProps = Omit<BaseCombobox.Input.Props, "aria-label" | "aria-labelledby"> & Readonly<{
     /** The search box's accessible name. */
@@ -50,43 +62,105 @@ export type ComboboxSearchProps = Omit<BaseCombobox.Input.Props, "aria-label" |
  * field's own control.
  */
 declare const ComboboxSearch: ({ className, ...props }: ComboboxSearchProps) => ReactNode;
-export type ComboboxListProps = BaseCombobox.List.Props & Readonly<{
-    /** The scroll container, which `useInfiniteScroll` watches. */
-    ref?: Ref<HTMLDivElement>;
+export type ComboboxListProps = Omit<BaseCombobox.List.Props, "ref"> & Readonly<{
+    /** A paged query, whose next page loads as the list nears its end. */
+    query?: Pick<PagedQuery<unknown>, "hasNextPage" | "isFetchingNextPage" | "fetchNextPage">;
 }>;
-declare const ComboboxList: ({ className, ...props }: ComboboxListProps) => ReactNode;
-export type ComboboxOptionProps = BaseCombobox.Item.Props & Readonly<{
-    /** Draws a checkbox rather than a tick, for a multi-value list. */
+/** The scrolling list of options, which loads a paged `query`'s next page as it nears its end. */
+declare const ComboboxList: ({ className, query, ...props }: ComboboxListProps) => ReactNode;
+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;
 }>;
-declare const ComboboxOption: ({ className, children, multiple, ...props }: ComboboxOptionProps) => ReactNode;
+/** The mark beside a chosen option. Its children are the mark, such as a tick. */
+declare const ComboboxOptionIndicator: ({ className, multiple, ...props }: ComboboxOptionIndicatorProps) => 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. */
 declare const ComboboxEmpty: ({ className, ...props }: BaseCombobox.Empty.Props) => ReactNode;
+/** The popup's polite status line. */
 declare const ComboboxStatus: ({ className, ...props }: BaseCombobox.Status.Props) => ReactNode;
+/** The row that holds the status and a retry button. */
 declare const ComboboxStatusArea: ({ className, ...props }: ComponentProps<"div">) => ReactNode;
+/** The copy a combobox's popup shows about its options. */
+export type ComboboxPopupLabels = OptionsLoadLabels & Readonly<{
+    /** Shown when the search matches nothing. */
+    noResultsLabel: string;
+    /** The search box's accessible name, such as "Search". */
+    searchLabel: string;
+    /** Read while a paged query fetches its next page. */
+    loadingMoreLabel: string;
+    /** The match count of a paged query, such as "40 results". */
+    resultsLabel: (count: number) => string;
+}>;
+/** The copy `LoadStatus` shows. */
+export type ComboboxLoadStatusLabels = Pick<ComboboxPopupLabels, "loadingLabel" | "loadFailedLabel" | "loadBrokenLabel" | "retryLabel" | "loadingMoreLabel" | "resultsLabel">;
+export type ComboboxLoadStatusProps = ComboboxLoadStatusLabels & Readonly<{
+    /** How far the items have loaded. */
+    load: OptionsLoad;
+    /** A paged query, whose match count and next page it reports. */
+    query?: Pick<PagedQuery<unknown>, "data" | "isFetchingNextPage">;
+    /** Runs a retry, such as to move focus back afterwards. @default retry() */
+    onRetry?: (retry: () => void) => void;
+    className?: string;
+}>;
+/** The load status of the items, with a retry button where trying again can help. */
+declare const ComboboxLoadStatus: ({ load, query, onRetry, className, ...labels }: ComboboxLoadStatusProps) => ReactNode;
+export type ComboboxBodyProps<TItem> = ComboboxPopupLabels & Readonly<{
+    /** How far the items have loaded. */
+    load: OptionsLoad;
+    /** A paged query, searched on the server and loaded page by page. */
+    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. */
+    multiple?: boolean;
+    /** A stable identity per item. */
+    itemKey: (item: TItem) => string;
+    /** The mark beside a chosen option, such as a tick. */
+    checkIcon: ReactNode;
+    /** Renders one item's row. */
+    children: (item: TItem) => ReactNode;
+}>;
+/**
+ * What a combobox's popup holds: the search box, the load status with a retry
+ * where one can help, the empty state and the list, which loads the next page
+ * of a paged query as it nears its end.
+ */
+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" | "Positioner" | "Popup" | "Input" | "List" | "Empty" | "Status"> & Readonly<{
+export type ComboboxParts = Omit<typeof BaseCombobox, "Root" | "Icon" | "Positioner" | "Popup" | "Input" | "List" | "Empty" | "Status"> & Readonly<{
     Root: typeof ComboboxRoot;
     Control: typeof ComboboxControl;
+    Icon: typeof ComboboxIcon;
     Tags: typeof ComboboxTags;
     Positioner: typeof ComboboxPositioner;
     Popup: typeof ComboboxPopup;
     Search: typeof ComboboxSearch;
     List: typeof ComboboxList;
     Option: typeof ComboboxOption;
+    OptionIndicator: typeof ComboboxOptionIndicator;
+    OptionText: typeof ComboboxOptionText;
     Empty: typeof ComboboxEmpty;
     Status: typeof ComboboxStatus;
     StatusArea: typeof ComboboxStatusArea;
+    LoadStatus: typeof ComboboxLoadStatus;
+    Body: typeof ComboboxBody;
     Pending: typeof Field.Pending;
 }>;
 /**
  * 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. For the ordinary case, use
- * `ComboboxField`. The positioner takes the control as its `anchor`.
+ * unstyled base-ui part stays reachable. `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}>
+ * 	<Combobox.Control ref={anchorRef} icon={<ExpandMoreIcon />}>
  * 		<Combobox.Value>{(status: string | null) => status}</Combobox.Value>
  * 	</Combobox.Control>
  * 	<Combobox.Portal>
@@ -94,7 +168,12 @@ export type ComboboxParts = Omit<typeof BaseCombobox, "Root" | "Positioner" | "P
  * 			<Combobox.Popup>
  * 				<Combobox.Search aria-label="Search" />
  * 				<Combobox.List>
- * 					{(status: string) => <Combobox.Option key={status} value={status}>{status}</Combobox.Option>}
+ * 					{(status: string) => (
+ * 						<Combobox.Option key={status} value={status}>
+ * 							<Combobox.OptionIndicator><CheckIcon /></Combobox.OptionIndicator>
+ * 							<Combobox.OptionText>{status}</Combobox.OptionText>
+ * 						</Combobox.Option>
+ * 					)}
  * 				</Combobox.List>
  * 			</Combobox.Popup>
  * 		</Combobox.Positioner>