@soroush.tech/design-system 2.0.0-rc.3 → 2.0.0-rc.5

package/dist/Autocomplete.d.cts

@@ -0,0 +1,93 @@
+import { nt as Theme } from "./index-Lsm4v8fB.cjs";
+import { ChangeEvent, KeyboardEvent, ReactNode, SyntheticEvent } from "react";
+import { LayoutProps, SpaceProps } from "@soroush.tech/styled-system";
+/** One value for a single field, a list for `multiple`. */
+type AutocompleteValue<T, Multiple extends boolean | undefined> = Multiple extends true ? T[] : T | null;
+/** Why the value changes. */
+type AutocompleteChangeReason = 'selectOption' | 'removeOption' | 'createOption' | 'clear';
+/** Why the text changes: it was typed, set to match a choice, or emptied. */
+type AutocompleteInputReason = 'input' | 'reset' | 'clear';
+type AutocompleteVariant = 'default' | 'outlined' | 'text' | 'underline';
+interface AutocompleteProps<T = string, Multiple extends boolean | undefined = false> extends SpaceProps<Theme>, Pick<LayoutProps<Theme>, 'width' | 'minWidth' | 'maxWidth'> {
+  /** What can be chosen - strings, or anything `getOptionLabel` can say. */
+  options: readonly T[];
+  /** The chosen option - `null` for none - or, with `multiple`, the chosen list. Controlled with `onChange`. */
+  value?: AutocompleteValue<T, Multiple>;
+  /** The choice at first, when uncontrolled. */
+  defaultValue?: AutocompleteValue<T, Multiple>;
+  /** Fired as the choice changes, with why. */
+  onChange?: (event: React.SyntheticEvent, value: AutocompleteValue<T, Multiple>, reason: AutocompleteChangeReason) => void;
+  /** The text in the field. Controlled with `onInputChange`. */
+  inputValue?: string;
+  /** Fired as the text changes, with why. */
+  onInputChange?: (event: React.SyntheticEvent, value: string, reason: AutocompleteInputReason) => void;
+  /** Chooses several: each shows as a `Chip`. */
+  multiple?: Multiple;
+  /** Takes a typed text that is no option as the value - a string - on Enter, or on leaving the field. Default: `false`. */
+  shouldAllowFreeText?: boolean;
+  /** What an option says, and what is typed to find it. Default: a string as it is, else its `label`. */
+  getOptionLabel?: (option: T) => string;
+  /** Whether an option is the value. Default: `===`. */
+  isOptionEqualToValue?: (option: T, value: T) => boolean;
+  /** The options that match what is typed. Default: those whose label holds it, in any case. */
+  filterOptions?: (options: readonly T[], state: {
+    inputValue: string;
+  }) => readonly T[];
+  /** The group an option sits in - options of one group are next to one another. */
+  groupBy?: (option: T) => string;
+  /** What an option shows in its row, in place of its label. */
+  renderOption?: (option: T, state: {
+    isSelected: boolean;
+    isHighlighted: boolean;
+  }) => ReactNode;
+  /** Shows `loadingText` while there is nothing to list. Default: `false`. */
+  isLoading?: boolean;
+  /** What the list says while it is loading - no built-in English. */
+  loadingText?: string;
+  /** What the list says when nothing matches. Without it, the list stays closed. */
+  noOptionsText?: string;
+  /** Names the clear control - without it, there is none. */
+  clearLabel?: string;
+  /** Names the control that opens the list. */
+  openLabel?: string;
+  /** Names the control that closes the list. */
+  closeLabel?: string;
+  /** Names the control that removes a chip of `multiple`, by its label. Without it, a chip has none. */
+  getRemoveLabel?: (label: string) => string;
+  placeholder?: string;
+  /** Frame of the field. Default: its `FormControl`'s, else `'default'`. */
+  variant?: AutocompleteVariant;
+  /** Resolves against `theme.sizes`. Default: its `FormControl`'s, else `'md'`. */
+  size?: keyof Theme['sizes'];
+  /** Focus color - resolves to `theme.palette`. Default: its `FormControl`'s, else `'primary'`. */
+  color?: keyof Theme['palette'];
+  /** Text color, resolves against `theme.text`. Default: the focus color. */
+  textColor?: keyof Theme['text'];
+  /** Corner radius of the field - only the `default` and `outlined` frames - and of the list. Resolves against `theme.radii`. The field is square by default; the list takes `theme.defaults.surfaceRadius`. */
+  borderRadius?: keyof Theme['radii'];
+  /** Background of the list, resolves against `theme.background`. Default: `'modal'`. */
+  bg?: keyof Theme['background'];
+  disabled?: boolean;
+  error?: boolean;
+  required?: boolean;
+  fullWidth?: boolean;
+  name?: string;
+  id?: string;
+  /** Stacking layer of the list, from `theme.zOrder`. Default: `'modal'`. */
+  layer?: keyof Theme['zOrder'];
+  className?: string;
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
+  'aria-describedby'?: string;
+  'data-testid'?: string;
+}
+/**
+ * @description A field whose text finds an option in a list: a `role="combobox"` input with a
+ * listbox below it, `aria-activedescendant` on the highlighted option. ArrowDown and ArrowUp open
+ * it and step through the options, Home and End go to the first and the last while it is being
+ * walked, Enter chooses, Escape closes. `multiple` shows the choice as `Chip`s, and Backspace in
+ * the empty field takes the last off; `shouldAllowFreeText` takes what is typed as a value. In a
+ * `FormControl` its `FormLabel` names it, and its size, color, error and disabled state apply.
+ */
+declare function Autocomplete<T = string, Multiple extends boolean | undefined = false>({ options, value, defaultValue, onChange, inputValue: inputValueProp, onInputChange, multiple, shouldAllowFreeText: shouldAllowFreeTextProp, getOptionLabel, isOptionEqualToValue, filterOptions, groupBy, renderOption, isLoading, loadingText: loadingTextProp, noOptionsText: noOptionsTextProp, clearLabel: clearLabelProp, openLabel: openLabelProp, closeLabel: closeLabelProp, getRemoveLabel, placeholder, variant: variantProp, size: sizeProp, color: colorProp, textColor: textColorProp, borderRadius: borderRadiusProp, bg: bgProp, disabled: disabledProp, error: errorProp, required: requiredProp, fullWidth: fullWidthProp, name, id: idProp, layer: layerProp, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, 'aria-describedby': ariaDescribedby, 'data-testid': dataTestid, ...spaceProps }: Readonly<AutocompleteProps<T, Multiple>>): import("react").JSX.Element;
+export { Autocomplete, type AutocompleteChangeReason, type AutocompleteInputReason, AutocompleteProps, type AutocompleteValue, AutocompleteVariant };

package/dist/Autocomplete.d.mts

@@ -0,0 +1,93 @@
+import { nt as Theme } from "./index-CR8qkP8U.mjs";
+import { LayoutProps, SpaceProps } from "@soroush.tech/styled-system";
+import { ChangeEvent, KeyboardEvent, ReactNode, SyntheticEvent } from "react";
+/** One value for a single field, a list for `multiple`. */
+type AutocompleteValue<T, Multiple extends boolean | undefined> = Multiple extends true ? T[] : T | null;
+/** Why the value changes. */
+type AutocompleteChangeReason = 'selectOption' | 'removeOption' | 'createOption' | 'clear';
+/** Why the text changes: it was typed, set to match a choice, or emptied. */
+type AutocompleteInputReason = 'input' | 'reset' | 'clear';
+type AutocompleteVariant = 'default' | 'outlined' | 'text' | 'underline';
+interface AutocompleteProps<T = string, Multiple extends boolean | undefined = false> extends SpaceProps<Theme>, Pick<LayoutProps<Theme>, 'width' | 'minWidth' | 'maxWidth'> {
+  /** What can be chosen - strings, or anything `getOptionLabel` can say. */
+  options: readonly T[];
+  /** The chosen option - `null` for none - or, with `multiple`, the chosen list. Controlled with `onChange`. */
+  value?: AutocompleteValue<T, Multiple>;
+  /** The choice at first, when uncontrolled. */
+  defaultValue?: AutocompleteValue<T, Multiple>;
+  /** Fired as the choice changes, with why. */
+  onChange?: (event: React.SyntheticEvent, value: AutocompleteValue<T, Multiple>, reason: AutocompleteChangeReason) => void;
+  /** The text in the field. Controlled with `onInputChange`. */
+  inputValue?: string;
+  /** Fired as the text changes, with why. */
+  onInputChange?: (event: React.SyntheticEvent, value: string, reason: AutocompleteInputReason) => void;
+  /** Chooses several: each shows as a `Chip`. */
+  multiple?: Multiple;
+  /** Takes a typed text that is no option as the value - a string - on Enter, or on leaving the field. Default: `false`. */
+  shouldAllowFreeText?: boolean;
+  /** What an option says, and what is typed to find it. Default: a string as it is, else its `label`. */
+  getOptionLabel?: (option: T) => string;
+  /** Whether an option is the value. Default: `===`. */
+  isOptionEqualToValue?: (option: T, value: T) => boolean;
+  /** The options that match what is typed. Default: those whose label holds it, in any case. */
+  filterOptions?: (options: readonly T[], state: {
+    inputValue: string;
+  }) => readonly T[];
+  /** The group an option sits in - options of one group are next to one another. */
+  groupBy?: (option: T) => string;
+  /** What an option shows in its row, in place of its label. */
+  renderOption?: (option: T, state: {
+    isSelected: boolean;
+    isHighlighted: boolean;
+  }) => ReactNode;
+  /** Shows `loadingText` while there is nothing to list. Default: `false`. */
+  isLoading?: boolean;
+  /** What the list says while it is loading - no built-in English. */
+  loadingText?: string;
+  /** What the list says when nothing matches. Without it, the list stays closed. */
+  noOptionsText?: string;
+  /** Names the clear control - without it, there is none. */
+  clearLabel?: string;
+  /** Names the control that opens the list. */
+  openLabel?: string;
+  /** Names the control that closes the list. */
+  closeLabel?: string;
+  /** Names the control that removes a chip of `multiple`, by its label. Without it, a chip has none. */
+  getRemoveLabel?: (label: string) => string;
+  placeholder?: string;
+  /** Frame of the field. Default: its `FormControl`'s, else `'default'`. */
+  variant?: AutocompleteVariant;
+  /** Resolves against `theme.sizes`. Default: its `FormControl`'s, else `'md'`. */
+  size?: keyof Theme['sizes'];
+  /** Focus color - resolves to `theme.palette`. Default: its `FormControl`'s, else `'primary'`. */
+  color?: keyof Theme['palette'];
+  /** Text color, resolves against `theme.text`. Default: the focus color. */
+  textColor?: keyof Theme['text'];
+  /** Corner radius of the field - only the `default` and `outlined` frames - and of the list. Resolves against `theme.radii`. The field is square by default; the list takes `theme.defaults.surfaceRadius`. */
+  borderRadius?: keyof Theme['radii'];
+  /** Background of the list, resolves against `theme.background`. Default: `'modal'`. */
+  bg?: keyof Theme['background'];
+  disabled?: boolean;
+  error?: boolean;
+  required?: boolean;
+  fullWidth?: boolean;
+  name?: string;
+  id?: string;
+  /** Stacking layer of the list, from `theme.zOrder`. Default: `'modal'`. */
+  layer?: keyof Theme['zOrder'];
+  className?: string;
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
+  'aria-describedby'?: string;
+  'data-testid'?: string;
+}
+/**
+ * @description A field whose text finds an option in a list: a `role="combobox"` input with a
+ * listbox below it, `aria-activedescendant` on the highlighted option. ArrowDown and ArrowUp open
+ * it and step through the options, Home and End go to the first and the last while it is being
+ * walked, Enter chooses, Escape closes. `multiple` shows the choice as `Chip`s, and Backspace in
+ * the empty field takes the last off; `shouldAllowFreeText` takes what is typed as a value. In a
+ * `FormControl` its `FormLabel` names it, and its size, color, error and disabled state apply.
+ */
+declare function Autocomplete<T = string, Multiple extends boolean | undefined = false>({ options, value, defaultValue, onChange, inputValue: inputValueProp, onInputChange, multiple, shouldAllowFreeText: shouldAllowFreeTextProp, getOptionLabel, isOptionEqualToValue, filterOptions, groupBy, renderOption, isLoading, loadingText: loadingTextProp, noOptionsText: noOptionsTextProp, clearLabel: clearLabelProp, openLabel: openLabelProp, closeLabel: closeLabelProp, getRemoveLabel, placeholder, variant: variantProp, size: sizeProp, color: colorProp, textColor: textColorProp, borderRadius: borderRadiusProp, bg: bgProp, disabled: disabledProp, error: errorProp, required: requiredProp, fullWidth: fullWidthProp, name, id: idProp, layer: layerProp, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, 'aria-describedby': ariaDescribedby, 'data-testid': dataTestid, ...spaceProps }: Readonly<AutocompleteProps<T, Multiple>>): import("react").JSX.Element;
+export { Autocomplete, type AutocompleteChangeReason, type AutocompleteInputReason, AutocompleteProps, type AutocompleteValue, AutocompleteVariant };