@bspk/ui 1.1.17 → 1.1.19

package/src/Menu.tsx

@@ -1,12 +1,15 @@
 import './menu.scss';
-import { ComponentProps, CSSProperties, MouseEvent as ReactMouseEvent, useMemo } from 'react';
+import { ComponentProps, CSSProperties, ReactNode, useMemo } from 'react';
 
 import { Checkbox } from './Checkbox';
 import { ListItem } from './ListItem';
-import { Txt } from './Txt';
 import { useId } from './hooks/useId';
 
-import { CommonProps, ElementProps } from './';
+import { CommonProps, ElementProps, SetRef } from './';
+
+const DEFAULT = {
+    selectAll: 'Select All',
+};
 
 export const MIN_ITEM_COUNT = 3;
 export const MAX_ITEM_COUNT = 10;
@@ -16,12 +19,12 @@ export function menuItemId(menuId: string, index: number) {
 }
 
 /** The props for the renderListItem function. Useful for customizing menu list items. */
-export type RenderListItemParams<M extends MenuItem> = Pick<
-    MenuProps<M>,
+export type RenderListItemParams<T extends MenuItem = MenuItem> = Pick<
+    MenuProps<T>,
     'activeIndex' | 'isMulti' | 'selectedValues'
 > & {
     index: number;
-    item: M;
+    item: T;
     menuId: string;
     selected: boolean;
     itemId?: string;
@@ -37,7 +40,7 @@ export type MenuItem = CommonProps<'disabled'> & {
     id?: string;
 };
 
-export type MenuProps<Item extends MenuItem = MenuItem> = CommonProps<'disabled' | 'id'> & {
+export type MenuProps<T extends MenuItem = MenuItem> = CommonProps<'disabled' | 'id'> & {
     /**
      * The number of items to display in the menu
      *
@@ -49,17 +52,27 @@ export type MenuProps<Item extends MenuItem = MenuItem> = CommonProps<'disabled'
     /**
      * Content to display in the menu.
      *
-     * @type MenuItems
-     */
-    items?: Item[];
-    /** A ref to the inner div element. */
-    innerRef?: (node: HTMLElement | null) => void;
-    /**
-     * Message to display when no results are found
+     * @example
+     *     [
+     *         { value: '1', label: 'Option 1' },
+     *         { value: '2', label: 'Option 2' },
+     *         { value: '3', label: 'Option 3' },
+     *         { value: '4', label: 'Option 4' },
+     *         { value: '5', label: 'Option 5' },
+     *         { value: '6', label: 'Option 6' },
+     *         { value: '7', label: 'Option 7' },
+     *         { value: '8', label: 'Option 8' },
+     *         { value: '9', label: 'Option 9' },
+     *         { value: '10', label: 'Option 10' },
+     *     ];
      *
-     * @type multiline
+     * @type Array<MenuItem>
      */
-    noResultsMessage?: string;
+    items?: T[];
+    /** A ref to the inner div element. */
+    innerRef?: SetRef<HTMLDivElement>;
+    /** Message to display when no results are found */
+    noResultsMessage?: ReactNode;
     /** The index of the currently highlighted item. */
     activeIndex?: number;
     /** The values of the selected items */
@@ -71,22 +84,31 @@ export type MenuProps<Item extends MenuItem = MenuItem> = CommonProps<'disabled'
      * @param {RenderListItemParams} props
      * @returns {ComponentProps<typeof ListItem>}
      */
-    renderListItem?: (props: RenderListItemParams<Item>) => Partial<ComponentProps<typeof ListItem>>;
+    renderListItem?: (props: RenderListItemParams<T>) => Partial<ComponentProps<typeof ListItem>>;
     /**
      * Whether the menu allows multiple selections.
      *
      * @default false
      */
     isMulti?: boolean;
+    /**
+     * The label for the "Select All" option.
+     *
+     * Ignored if `isMulti` is false.
+     *
+     * If `isMulti` is `true`, defaults to "Select All". If a string, it will be used as the label. If false the select
+     * all option will not be rendered.
+     *
+     * @default false
+     */
+    selectAll?: boolean | string;
     /**
      * The function to call when the selected values change.
      *
-     * @type (selectedValues: String[], event: ChangeEvent) => void
-     * @param {string[]} selectedValues
-     * @param {ChangeEvent} event
-     * @returns {void}
+     * @example
+     *     (selectedValues, event) => setState({ selectedValues });
      */
-    onChange?: (selectedValues: string[], event?: ReactMouseEvent<HTMLButtonElement, MouseEvent>) => void;
+    onChange?: (selectedValues: string[], event?: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void;
 };
 
 /**
@@ -94,7 +116,7 @@ export type MenuProps<Item extends MenuItem = MenuItem> = CommonProps<'disabled'
  *
  * @name Menu
  */
-function Menu<Item extends MenuItem = MenuItem>({
+function Menu({
     itemCount: itemCountProp = 5,
     items: itemsProp = [],
     noResultsMessage,
@@ -106,24 +128,39 @@ function Menu<Item extends MenuItem = MenuItem>({
     id: idProp,
     renderListItem,
     isMulti,
+    selectAll: selectAllProp,
     ...props
-}: ElementProps<MenuProps<Item>, 'div'>) {
+}: ElementProps<MenuProps, 'div'>) {
     const menuId = useId(idProp);
-    const items = Array.isArray(itemsProp) ? itemsProp : [];
-    const itemCount = useMemo(
-        () =>
+
+    const selectAll = useMemo(() => {
+        if (!isMulti) return false;
+        if (selectAllProp && typeof selectAllProp === 'string') return selectAllProp;
+        return selectAllProp === true ? DEFAULT.selectAll : false;
+    }, [isMulti, selectAllProp]);
+
+    const { items, itemCount } = useMemo(() => {
+        const itemsNext = Array.isArray(itemsProp) ? itemsProp : [];
+        return {
+            items: itemsNext,
             // Ensure itemCount is within the range of items.length
-            Math.min(
-                items.length,
+            itemCount: Math.min(
+                itemsNext.length,
                 // pin itemCountProp to a range of 3 to 10
                 Math.max(MIN_ITEM_COUNT, Math.min(itemCountProp, MAX_ITEM_COUNT)),
             ),
-        [itemCountProp, items.length],
+        };
+    }, [itemCountProp, itemsProp]);
+
+    const allSelected = useMemo(
+        () => !!(items.length && items.every((item) => selectedValues.includes(item.value))),
+        [items, selectedValues],
     );
 
     return (
         <div
             {...props}
+            aria-multiselectable={isMulti || undefined}
             data-bspk="menu"
             data-disabled={disabled || undefined}
             data-item-count={itemCount || undefined}
@@ -133,87 +170,101 @@ function Menu<Item extends MenuItem = MenuItem>({
             role="listbox"
             style={{ ...props.style, '--item-count': itemCount } as CSSProperties}
         >
-            {items.length ? (
-                items.map((item, index) => {
-                    const itemId = item.id || menuItemId(menuId, index);
-
-                    const selected = Array.isArray(selectedValues) && selectedValues.includes(item.value);
-
-                    const renderProps = renderListItem?.({
-                        activeIndex,
-                        index,
-                        item,
-                        selectedValues,
-                        isMulti,
-                        menuId: menuId || '',
-                        selected,
-                        itemId,
-                    });
-
-                    return (
-                        <ListItem
-                            {...renderProps}
-                            active={activeIndex === index || undefined}
-                            aria-disabled={item.disabled || undefined}
-                            aria-posinset={index + 1}
-                            aria-selected={selected || undefined}
-                            as="button"
-                            data-menu-item
-                            data-selected={selected || undefined}
-                            disabled={item.disabled || undefined}
-                            id={itemId}
-                            key={itemId}
-                            label={renderProps?.label?.toString() || item.label?.toString()}
-                            onClick={(event: ReactMouseEvent<HTMLButtonElement, MouseEvent>) => {
-                                if (renderProps) renderProps?.onClick?.(event);
-
-                                if (onChange) {
-                                    if (!isMulti) {
-                                        onChange?.([item.value], event);
-                                        return;
-                                    }
-                                    onChange(
-                                        selected
-                                            ? selectedValues.filter((value) => value !== item.value)
-                                            : [...selectedValues, item.value],
-                                        event,
-                                    );
-                                }
+            {isMulti && selectAll && (
+                <ListItem
+                    as="button"
+                    data-selected={allSelected || undefined}
+                    key="select-all"
+                    label={selectAll}
+                    onClick={(event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => {
+                        onChange?.(allSelected ? [] : items.map((item) => item.value), event);
+                    }}
+                    role="option"
+                    tabIndex={-1}
+                    trailing={
+                        <Checkbox
+                            aria-label={selectAll}
+                            checked={!!allSelected}
+                            name=""
+                            onChange={(checked) => {
+                                onChange?.(checked ? items.map((item) => item.value) : []);
                             }}
-                            role="option"
-                            tabIndex={-1}
-                            trailing={
-                                isMulti ? (
-                                    <Checkbox
-                                        aria-label={item.label}
-                                        checked={selected}
-                                        name={item.value}
-                                        onChange={(checked) => {
-                                            onChange?.(
-                                                checked
-                                                    ? selectedValues.filter((value) => value !== item.value)
-                                                    : [...selectedValues, item.value],
-                                            );
-                                        }}
-                                        value={item.value}
-                                    />
-                                ) : (
-                                    renderProps?.trailing
-                                )
-                            }
+                            value=""
                         />
-                    );
-                })
-            ) : (
-                <>
-                    <Txt as="div" variant="heading-h5">
-                        No results found
-                    </Txt>
-                    <Txt as="div" variant="body-base">
-                        {noResultsMessage}
-                    </Txt>
-                </>
+                    }
+                />
             )}
+            {items.length
+                ? items.map((item, index) => {
+                      const itemId = item.id || menuItemId(menuId, index);
+
+                      const selected = Boolean(Array.isArray(selectedValues) && selectedValues.includes(item.value));
+
+                      const renderProps = renderListItem?.({
+                          activeIndex,
+                          index,
+                          item,
+                          selectedValues,
+                          isMulti,
+                          menuId: menuId || '',
+                          selected,
+                          itemId,
+                      });
+
+                      return (
+                          <ListItem
+                              {...renderProps}
+                              active={activeIndex === index || undefined}
+                              aria-disabled={item.disabled || undefined}
+                              aria-posinset={index + 1}
+                              aria-selected={selected || undefined}
+                              as="button"
+                              //data-selected={selected || undefined}
+                              disabled={item.disabled || undefined}
+                              id={itemId}
+                              key={itemId}
+                              label={renderProps?.label?.toString() || item.label?.toString()}
+                              onClick={(event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => {
+                                  if (renderProps) renderProps?.onClick?.(event);
+
+                                  if (onChange) {
+                                      if (!isMulti) {
+                                          onChange?.([item.value], event);
+                                          return;
+                                      }
+                                      onChange(
+                                          selected
+                                              ? selectedValues.filter((value) => value !== item.value)
+                                              : [...selectedValues, item.value],
+                                          event,
+                                      );
+                                  }
+                              }}
+                              role="option"
+                              tabIndex={-1}
+                              trailing={
+                                  isMulti ? (
+                                      <Checkbox
+                                          aria-label={item.label}
+                                          checked={selected}
+                                          name={item.value}
+                                          onChange={(checked) => {
+                                              onChange?.(
+                                                  checked
+                                                      ? selectedValues.filter((value) => value !== item.value)
+                                                      : [...selectedValues, item.value],
+                                              );
+                                          }}
+                                          value={item.value}
+                                      />
+                                  ) : (
+                                      renderProps?.trailing
+                                  )
+                              }
+                          />
+                      );
+                  })
+                : noResultsMessage}
         </div>
     );
 }

package/src/NumberInput.tsx

@@ -25,7 +25,11 @@ export type NumberInputProps = CommonProps<'aria-label' | 'disabled' | 'id' | 'n
     InvalidPropsLibrary & {
         /** The value of the control. */
         value?: number;
-        /** Callback when the value changes. */
+        /**
+         * Callback when the value changes.
+         *
+         * @required
+         */
         onChange: (value: number | undefined) => void;
         /**
          * The alignment of the input box. Centered between the plus and minus buttons or to the left of the buttons.
@@ -78,8 +82,10 @@ function NumberInput({
     const max = isNumber(maxProp);
     const min = isNumber(minProp);
 
-    const fix = (next: number | undefined = value) => {
-        if (typeof next !== 'number') {
+    const fix = (nextValue: number | string | undefined) => {
+        const next = isNumber(nextValue);
+
+        if (typeof next !== 'number' || isNaN(next)) {
             onChange(undefined);
             return;
         }
@@ -116,12 +122,15 @@ function NumberInput({
                 aria-label={ariaLabel}
                 disabled={disabled}
                 id={inputId}
+                max={max}
+                min={min}
                 name={name}
-                onBlur={() => {
-                    fix();
+                onBlur={(event) => {
+                    // Fix the value on blur to ensure it is a valid number
+                    fix(event.target.value);
                 }}
                 onChange={(event) => {
-                    onChange(event.target.value as unknown as number);
+                    onChange(isNumber(event.target.value));
                 }}
                 readOnly={readOnly}
                 type="number"

package/src/Portal.tsx

@@ -8,7 +8,11 @@ export type PortalProps = {
      * @required
      */
     children: ReactNode;
-    /** The container to render the portal in. */
+    /**
+     * The container to render the portal in.
+     *
+     * @optional
+     */
     container?: HTMLElement;
 };
 

package/src/ProgressBar.tsx

@@ -11,9 +11,13 @@ export type ProgressBarProps = {
     /**
      * The current progress of the progressbar.
      *
+     * @example
+     *     42;
+     *
      * @default 0
      * @minimum 0
      * @maximum 100
+     *
      * @required
      */
     completion: number;

package/src/ProgressionStepper.tsx

@@ -30,7 +30,14 @@ export type ProgressionStepperProps = {
     /**
      * The steps to display in the progress bar.
      *
-     * @type ProgressionStepperItem[]
+     * @example
+     *     [
+     *         { name: '[Name of step to proceed forward 1]' },
+     *         { name: '[Name of step to proceed forward 2]' },
+     *         { name: '[Name of step to proceed forward 3]' },
+     *     ];
+     *
+     * @type Array<ProgressionStepperItem>
      * @required
      */
     steps: ProgressionStepperItem[];
@@ -67,7 +74,7 @@ function ProgressionStepper({
     ...containerProps
 }: ElementProps<ProgressionStepperProps, 'div'>) {
     const currentStep = Math.max(0, Math.min(currentStepProp, steps.length + 1));
-    return (
+    return !steps?.length ? null : (
         <div {...containerProps} data-bspk="progression-stepper" data-variant={variant}>
             {variant === 'widget' && (
                 <label>

package/src/ProgressionStepperBar.tsx

@@ -5,6 +5,9 @@ export type ProgressionStepperBarProps = {
     /**
      * The number of steps in the progress bar.
      *
+     * @example
+     *     5;
+     *
      * @minimum 2
      * @maximum 10
      * @required
@@ -13,6 +16,9 @@ export type ProgressionStepperBarProps = {
     /**
      * The last step completed.
      *
+     * @example
+     *     2;
+     *
      * @default 0
      * @minimum 0
      */

package/src/Radio.tsx

@@ -1,8 +1,24 @@
 import './radio.scss';
-import { ToggleControlProps, ElementProps, InvalidPropsLibrary } from './';
+import { ChangeEvent } from 'react';
 
-export type RadioProps = InvalidPropsLibrary &
-    Pick<ToggleControlProps<HTMLInputElement>, 'aria-label' | 'checked' | 'disabled' | 'name' | 'onChange' | 'value'>;
+import { ElementProps, InvalidPropsLibrary, CommonProps } from './';
+
+export type RadioProps = CommonProps<'aria-label' | 'disabled' | 'name'> &
+    InvalidPropsLibrary &
+    Required<CommonProps<'value'>> & {
+        /**
+         * Marks the radio as checked.
+         *
+         * @default false
+         */
+        checked?: boolean;
+        /**
+         * The function to call when the radio is checked.
+         *
+         * @required
+         */
+        onChange: (checked: boolean, event: ChangeEvent<HTMLInputElement>) => void;
+    };
 
 /**
  * A round control that allows user to choose one option from a set. This is the base element and if used directly you
@@ -13,13 +29,14 @@ export type RadioProps = InvalidPropsLibrary &
  * @name Radio
  */
 function Radio(props: ElementProps<RadioProps, 'input'>) {
-    const { checked = false, invalid, disabled, onChange, ...otherProps } = props;
+    const { checked = false, invalid, disabled, onChange, errorMessage, ...otherProps } = props;
 
     return (
         <span data-bspk="radio">
             <input
                 {...otherProps}
                 checked={!!checked}
+                data-errormessage={errorMessage || undefined}
                 data-invalid={invalid || undefined}
                 disabled={disabled || undefined}
                 onChange={(event) => onChange(!!event.target.checked, event)}

package/src/RadioGroup.tsx

@@ -5,21 +5,44 @@ import { ElementProps, CommonProps } from './';
 
 export type RadioGroupOption = Pick<ToggleOptionProps, 'description' | 'label'> & Required<CommonProps<'value'>>;
 
-export type RadioGroupProps = CommonProps<'name' | 'value'> & {
+export type RadioGroupProps = CommonProps<'name'> & {
+    /**
+     * The value of the control.
+     *
+     * @example
+     *     1;
+     *
+     * @required
+     */
+    value: string;
     /**
      * The function to call when the radios are changed.
      *
+     * @example
+     *     (value) => setState({ value }),
+     *
      * @required
      */
     onChange: (value: string) => void;
     /**
      * The options for the radios.
      *
-     * @type RadioGroupOption[]
+     * @example
+     *     [
+     *         { value: '1', label: 'Option 1', description: 'Description here' },
+     *         { value: '2', label: 'Option 2' },
+     *         { value: '3', label: 'Option 3' },
+     *     ];
+     *
+     * @type Array<RadioGroupOption>
      * @required
      */
     options: RadioGroupOption[];
-    /** The size of the radio group labels. */
+    /**
+     * The size of the radio group labels.
+     *
+     * @default base
+     */
     size?: 'base' | 'large' | 'small';
 };
 
@@ -33,14 +56,19 @@ function RadioGroup({
     options = [],
     name,
     value: groupValue,
-    size,
+    size = 'base',
     ...props
 }: ElementProps<RadioGroupProps, 'div'>) {
     return (
         <div {...props} data-bspk="radio-group" role="radiogroup" style={{ display: 'contents' }}>
-            {options.map(({ label, description, value }) => {
+            {options.map(({ label, description, value }, index) => {
                 return (
-                    <ToggleOption description={description} key={value} label={label} size={size}>
+                    <ToggleOption
+                        description={description}
+                        key={`toggle-option-${value || index}`}
+                        label={label}
+                        size={size}
+                    >
                         <Radio
                             aria-label={label}
                             checked={groupValue === value}

package/src/RadioOption.tsx

@@ -1,11 +1,20 @@
+import { ChangeEvent } from 'react';
+
 import { RadioProps, Radio } from './Radio';
 import { ToggleOptionProps, ToggleOption } from './ToggleOption';
 
 import { InvalidPropsLibrary } from '.';
 
 export type RadioOptionProps = InvalidPropsLibrary &
-    Pick<RadioProps, 'checked' | 'disabled' | 'name' | 'onChange' | 'value'> &
-    Pick<ToggleOptionProps, 'description' | 'label'>;
+    Pick<RadioProps, 'checked' | 'disabled' | 'name' | 'value'> &
+    Pick<ToggleOptionProps, 'description' | 'label'> & {
+        /**
+         * The function to call when the radio is checked.
+         *
+         * @required
+         */
+        onChange: (checked: boolean, event: ChangeEvent<HTMLInputElement>) => void;
+    };
 
 /**
  * A control that allows users to choose one or more items from a list or turn an feature on or off.