@bloomreach/react-banana-ui 1.6.0 → 1.7.0

package/dist/components/inputs/base-input/base-input.d.ts

@@ -1,4 +1,4 @@
-import React, { ChangeEventHandler, FocusEventHandler, InputHTMLAttributes, ReactNode } from 'react';
+import React, { ChangeEventHandler, FocusEventHandler, ForwardedRef, InputHTMLAttributes, ReactNode } from 'react';
 import './base-input.scss';
 export interface BaseInputProps {
     /**
@@ -37,6 +37,10 @@ export interface BaseInputProps {
      * @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea#Attributes
      */
     inputProps?: InputHTMLAttributes<HTMLInputElement | HTMLTextAreaElement>;
+    /**
+     * The ref to the `input` or `textarea` element.
+     */
+    inputRef?: ForwardedRef<HTMLInputElement> | ForwardedRef<HTMLTextAreaElement>;
     /**
      * Icon or any element displayed at the end of the `input` or `textarea`.
      */
@@ -101,5 +105,5 @@ export interface BaseInputProps {
  * The base input component to enter and edit text.
  * Should be used only by other components and not exposed to the end users.
  */
-declare const BaseInput: React.ForwardRefExoticComponent<BaseInputProps & React.RefAttributes<HTMLInputElement | HTMLTextAreaElement>>;
+declare const BaseInput: React.ForwardRefExoticComponent<BaseInputProps & React.RefAttributes<HTMLDivElement>>;
 export default BaseInput;

package/dist/components/inputs/internal.d.ts

@@ -1,4 +1,5 @@
 export * from './base-field';
 export * from './base-input';
 export * from './field-label';
+export * from './select';
 export * from './toggle';

package/dist/components/inputs/select/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Select } from './select';
+export type { SelectProps } from './select.types';

package/dist/components/inputs/select/select.d.ts

@@ -0,0 +1,37 @@
+import { SelectComponentType } from './select.types';
+import './select.scss';
+/**
+ * @internal
+ *
+ * The `Select` component is meant to optimize user interaction and experience.
+ * It is a customizable dropdown list that allows users to choose one or more options from a list.
+ * Its primary function is to enhance and simplify data input, minimizing user effort
+ * in navigation while avoiding incorrect entries.
+ *
+ * ### Usage
+ *
+ * ```tsx
+ * import { Select, SelectOption } from '@bloomreach/react-banana-ui';
+ * import React from 'react';
+ *
+ * export default function MyCustomSingleSelect() {
+ *   return (
+ *     <Select
+ *       label="List of fruits"
+ *       placeholder="Select a fruit"
+ *       onChange={(event, value) => console.log(value)}
+ *     >
+ *       <SelectOption value="apple">Apple</SelectOption>
+ *       <SelectOption value="banana">Banana</SelectOption>
+ *       <SelectOption value="orange">Orange</SelectOption>
+ *       <SelectOption value="grapes">Grapes</SelectOption>
+ *       <SelectOption value="strawberries">Strawberries</SelectOption>
+ *       <SelectOption value="blueberries">Blueberries</SelectOption>
+ *       <SelectOption value="pineapple">Pineapple</SelectOption>
+ *     </Select>
+ *   );
+ * }
+ * ```
+ */
+declare const _default: SelectComponentType;
+export default _default;

package/dist/components/inputs/select/select.types.d.ts

@@ -0,0 +1,66 @@
+import { ForwardedRef, ReactElement, ReactNode } from 'react';
+export type SelectValue<Value, Multiple> = Multiple extends true ? Value[] : Value | null;
+export interface SelectProps<OptionValue extends NonNullable<unknown>, Multiple extends boolean> {
+    /**
+     * The content of the component.
+     */
+    children?: ReactNode;
+    /**
+     * Custom class name for the container of the component.
+     */
+    className?: string;
+    /**
+     * The default selected value. Use when the component is not controlled.
+     * The value must be an array when `multiple` is `true`.
+     */
+    defaultValue?: SelectValue<OptionValue, Multiple>;
+    /**
+     * If true, the select is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Display an icon at the beginning of the select field.
+     */
+    icon?: ReactNode;
+    /**
+     * The `id` of the select element.
+     */
+    id?: string;
+    /**
+     * If `true`, selecting multiple values is allowed.
+     * This affects the type of the `value`, `defaultValue`, and `onChange` props.
+     */
+    multiple?: Multiple;
+    /**
+     * Name of the element. For example used by the server to identify the fields in form submits.
+     */
+    name?: string;
+    /**
+     * Callback fired when an option is selected.
+     */
+    onChange?: (event: React.MouseEvent<Element, MouseEvent> | React.KeyboardEvent<Element> | React.FocusEvent<Element, Element> | null, value: SelectValue<OptionValue, Multiple>) => void;
+    /**
+     * Text to show when there is no selected value.
+     */
+    placeholder?: string;
+    /**
+     * If `true`, the `select` element is readonly.
+     */
+    readOnly?: boolean;
+    /**
+     * If `true`, the `Select` cannot be empty when submitting form.
+     */
+    required?: boolean;
+    /**
+     * The selected value.
+     * Set to `null` in case of single select and `[]` in case of multiple select to clear the selection.
+     * If the value is an object it must have reference equality with the option in order to be selected.
+     */
+    value?: SelectValue<OptionValue, Multiple>;
+}
+export interface SelectComponentType {
+    <OptionValue extends NonNullable<unknown>, Multiple extends boolean = false>(props: SelectProps<OptionValue, Multiple> & {
+        ref?: ForwardedRef<HTMLElement>;
+    }): ReactElement | null;
+    displayName?: string | undefined;
+}

package/dist/components/inputs/select-field/index.d.ts

@@ -0,0 +1 @@
+export { default as SelectField } from './select-field';

package/dist/components/inputs/select-field/select-field.d.ts

@@ -0,0 +1,34 @@
+import { SelectFieldComponentType } from './select-field.types';
+/**
+ * The `SelectField` component is meant to optimize user interaction and experience.
+ * It is a customizable dropdown list that allows users to choose one or more options from a list.
+ * Its primary function is to enhance and simplify data input, minimizing user effort
+ * in navigation while avoiding incorrect entries.
+ *
+ * ### Usage
+ *
+ * ```tsx
+ * import { SelectField, SelectOption } from '@bloomreach/react-banana-ui';
+ * import React from 'react';
+ *
+ * export default function MyCustomSingleSelectField() {
+ *   return (
+ *     <SelectField
+ *       label="List of fruits"
+ *       placeholder="Select a fruit"
+ *       onChange={(event, value) => console.log(value)}
+ *     >
+ *       <SelectOption value="apple">Apple</SelectOption>
+ *       <SelectOption value="banana">Banana</SelectOption>
+ *       <SelectOption value="orange">Orange</SelectOption>
+ *       <SelectOption value="grapes">Grapes</SelectOption>
+ *       <SelectOption value="strawberries">Strawberries</SelectOption>
+ *       <SelectOption value="blueberries">Blueberries</SelectOption>
+ *       <SelectOption value="pineapple">Pineapple</SelectOption>
+ *     </SelectField>
+ *   );
+ * }
+ * ```
+ */
+declare const _default: SelectFieldComponentType;
+export default _default;

package/dist/components/inputs/select-field/select-field.qa.stories.d.ts

@@ -0,0 +1,15 @@
+import { Meta } from '@storybook/react';
+import { type Story } from './select-field.stories';
+import { SelectField } from '.';
+declare const meta: Meta<typeof SelectField>;
+export default meta;
+export declare const Basic: Story;
+export declare const DifferentStates: Story;
+export declare const FullWidth: Story;
+export declare const Single: Story;
+export declare const ControlledSingleSelect: Story;
+export declare const Multiple: Story<string, true>;
+export declare const ControlledMultipleSelect: Story<string, true>;
+export declare const OptionWithLabel: Story;
+export declare const NoneOption: Story;
+export declare const DisabledOptions: Story;

package/dist/components/inputs/select-field/select-field.stories.d.ts

@@ -0,0 +1,20 @@
+import { Meta, StoryObj } from '@storybook/react';
+import SelectField from './select-field';
+declare const meta: Meta<typeof SelectField>;
+export default meta;
+export type Story<ValueType extends NonNullable<unknown> = string, Multiple extends boolean = false> = StoryObj<typeof SelectField<ValueType, Multiple>>;
+export declare const Basic: Story;
+export declare const WithLabel: Story;
+export declare const WithTooltip: Story;
+export declare const WithHelperText: Story;
+export declare const CompleteField: Story;
+export declare const FullWidth: Story;
+export declare const ControlledSingleSelect: Story;
+export declare const Multiple: Story<string, true>;
+export declare const ControlledMultipleSelect: Story<string, true>;
+export declare const WithIconInTheField: Story;
+export declare const FieldsInColumn: Story;
+export declare const FieldsInRow: Story;
+export declare const OptionWithLabel: Story;
+export declare const NoneOption: Story;
+export declare const DisabledOptions: Story;

package/dist/components/inputs/select-field/select-field.types.d.ts

@@ -0,0 +1,38 @@
+import { ForwardedRef, ReactElement, ReactNode } from 'react';
+import { SelectProps } from '../../internal';
+export interface SelectFieldProps<OptionValue extends NonNullable<unknown>, Multiple extends boolean> extends SelectProps<OptionValue, Multiple> {
+    /**
+     * The options of the select. Use the `SelectOption` component to define the options.
+     */
+    children: React.ReactNode;
+    /**
+     * Custom class name for the container of the component.
+     */
+    className?: string;
+    /**
+     * If `true`, the ``field` will indicate an error and set the `aria-invalid` attribute for `input`.
+    */
+    error?: boolean;
+    /**
+     * If `true`, the field will take up the full width of its container.
+     */
+    fullWidth?: boolean;
+    /**
+     * The helper text content.
+     */
+    helperText?: ReactNode;
+    /**
+     * The label content.
+    */
+    label?: ReactNode;
+    /**
+     * Tooltip to display when the field has label.
+     */
+    tooltip?: ReactNode;
+}
+export interface SelectFieldComponentType {
+    <OptionValue extends NonNullable<unknown>, Multiple extends boolean = false>(props: SelectFieldProps<OptionValue, Multiple> & {
+        ref?: ForwardedRef<HTMLElement>;
+    }): ReactElement | null;
+    displayName?: string;
+}

package/dist/components/inputs/select-option/index.d.ts

@@ -0,0 +1,2 @@
+export { default as SelectOption } from './select-option';
+export type { SelectOptionProps } from './select-option.types';

package/dist/components/inputs/select-option/select-option.d.ts

@@ -0,0 +1,4 @@
+import { SelectOptionComponentType } from './select-option.types';
+import './select-option.scss';
+declare const _default: SelectOptionComponentType;
+export default _default;

package/dist/components/inputs/select-option/select-option.types.d.ts

@@ -0,0 +1,30 @@
+import { ForwardedRef, ReactElement, ReactNode } from 'react';
+export interface SelectOptionProps<OptionValue> {
+    /**
+     * Custom class name for the container of the component.
+     */
+    className?: string;
+    /**
+     * The content of the component.
+     */
+    children?: ReactNode;
+    /**
+     * If `true`, the option will be disabled.
+     */
+    disabled?: boolean;
+    /**
+     * The value of the option.
+     * If the value is an object it must have reference equality with the select in order to be selected.
+     */
+    value: OptionValue;
+    /**
+     * A text representation of the option's content. Used for keyboard text navigation matching.
+     */
+    label?: string;
+}
+export interface SelectOptionComponentType {
+    <OptionValue>(props: SelectOptionProps<OptionValue> & {
+        ref?: ForwardedRef<HTMLElement>;
+    }): ReactElement | null;
+    displayName?: string;
+}

package/dist/components/internal.d.ts

@@ -1 +1,2 @@
 export * from './inputs/internal';
+export * from './lists/internal';

package/dist/components/lists/internal.d.ts

@@ -0,0 +1,2 @@
+export * from './listbox-item';
+export * from './listbox';

package/dist/components/lists/listbox/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Listbox } from './listbox';
+export type { ListboxProps } from './listbox.types';

package/dist/components/lists/listbox/listbox.d.ts

@@ -0,0 +1,26 @@
+/// <reference types="react" />
+import { ListboxProps } from './listbox.types';
+import './listbox.scss';
+/**
+ * @internal
+ * The `Listbox` component is used to display a list of items aligned with design system styles.
+ * Use the `ListboxItem` component to define the items of the list.
+ *
+ * ### Usage
+ *
+ * ```tsx
+ * import { Listbox, ListboxItem } from '@bloomreach/react-banana-ui';
+ *
+ * export default function MyMenu() {
+ *   return (
+ *      <Listbox>
+ *        <ListboxItem>Item 1</ListboxItem>
+ *        <ListboxItem>Item 2</ListboxItem>
+ *        <ListboxItem>Item 3</ListboxItem>
+ *      </Listbox>
+ *   );
+ * }
+ * ```
+ */
+declare const Listbox: import("react").ForwardRefExoticComponent<ListboxProps & import("react").RefAttributes<HTMLUListElement>>;
+export default Listbox;

package/dist/components/lists/listbox/listbox.types.d.ts

@@ -0,0 +1,16 @@
+import { HTMLAttributes, ReactNode } from 'react';
+export interface ListboxProps {
+    /**
+     * Custom class name for the container of the component.
+     */
+    className?: string;
+    /**
+     * The content of the component.
+     */
+    children: ReactNode;
+    /**
+     * The role of the list box.
+     * @default 'listbox'
+     */
+    role?: HTMLAttributes<Element>['role'];
+}

package/dist/components/lists/listbox-item/index.d.ts

@@ -0,0 +1,2 @@
+export { default as ListboxItem } from './listbox-item';
+export type { ListboxItemProps } from './listbox-item.types';

package/dist/components/lists/listbox-item/listbox-item.d.ts

@@ -0,0 +1,27 @@
+/// <reference types="react" />
+import { ListboxItemProps } from './listbox-item.types';
+import './listbox-item.scss';
+/**
+ * @internal
+ * The `ListboxItem` component is used to define the items of the `Listbox` component.
+ * It mostly should be used as internal component to bring defined styles to the list items in menu
+ * or select components.
+ *
+ * ### Usage
+ *
+ * ```tsx
+ * import { Listbox, ListboxItem } from '@bloomreach/react-banana-ui';
+ *
+ * export default function MyMenu() {
+ *   return (
+ *      <Listbox>
+ *        <ListboxItem>Item 1</ListboxItem>
+ *        <ListboxItem>Item 2</ListboxItem>
+ *        <ListboxItem>Item 3</ListboxItem>
+ *      </Listbox>
+ *   );
+ * }
+ * ```
+ */
+declare const ListboxItem: import("react").ForwardRefExoticComponent<ListboxItemProps & import("react").RefAttributes<HTMLLIElement>>;
+export default ListboxItem;

package/dist/components/lists/listbox-item/listbox-item.types.d.ts

@@ -0,0 +1,28 @@
+import { HTMLAttributes, ReactNode } from 'react';
+export interface ListboxItemProps {
+    /**
+     * Custom class name for the container of the component.
+     */
+    className?: string;
+    /**
+     * The content of the component.
+     */
+    children?: ReactNode;
+    /**
+     * If `true`, the item will be disabled.
+     */
+    disabled?: boolean;
+    /**
+     * If `true`, the item will be highlighted.
+     */
+    highlighted?: boolean;
+    /**
+     * If `true`, the item will be selected.
+     */
+    selected?: boolean;
+    /**
+     * The role of the list box item.
+     * @default 'option'
+     */
+    role?: HTMLAttributes<Element>['role'];
+}