@bspk/ui 1.1.16 → 1.1.18

package/src/Dialog.tsx

@@ -1,18 +1,18 @@
 import './dialog.scss';
 import { FocusTrap } from 'focus-trap-react';
-import { ReactNode, Ref, useCallback, useEffect, useRef, useState } from 'react';
+import { ReactNode, useCallback, useEffect, useRef, useState } from 'react';
 
 import { Portal } from './Portal';
 import { useId } from './hooks/useId';
 import { useOutsideClick } from './hooks/useOutsideClick';
 
-import { CommonProps, ElementProps } from './';
+import { CommonProps, ElementProps, SetRef } from './';
 
 export type DialogProps = CommonProps<'id'> & {
     /** The content of the dialog. */
     children?: ReactNode;
     /** A ref to the dialog element. */
-    innerRef?: Ref<HTMLDivElement>;
+    innerRef?: SetRef<HTMLDivElement>;
     /**
      * If the dialog should appear.
      *

package/src/Dropdown.tsx

@@ -10,27 +10,41 @@ import { useId } from './hooks/useId';
 
 import { CommonProps, InvalidPropsLibrary } from './';
 
-export type DropdownOption = {
+export type DropdownOption = Record<string, unknown> & {
     /** The value of the option. */
     value: string;
     /** The label of the option. This is the text that will be displayed on the option. */
     label: string;
 };
 
-export type DropdownProps<O extends DropdownOption = DropdownOption> = CommonProps<
+export type DropdownProps<T extends DropdownOption = DropdownOption> = CommonProps<
     'aria-label' | 'disabled' | 'id' | 'name' | 'readOnly' | 'size'
 > &
     InvalidPropsLibrary &
-    Pick<MenuProps<O>, 'isMulti' | 'itemCount' | 'onChange' | 'renderListItem'> & {
+    Pick<MenuProps<T>, 'isMulti' | 'itemCount' | 'renderListItem'> & {
         /**
          * Array of options to display in the dropdown
          *
-         * @type DropdownOption[]
+         * @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 Array<DropdownOption>
          * @required
          */
-        options: O[];
+        options: T[];
         /**
-         * Array of selected values!
+         * Array of selected values
          *
          * @type Array<string>
          */
@@ -49,6 +63,12 @@ export type DropdownProps<O extends DropdownOption = DropdownOption> = CommonPro
         placement?: Extract<Placement, 'bottom' | 'top'>;
         /** The style of the dropdown. */
         style?: React.CSSProperties;
+        /**
+         * The function to call when the selected values change.
+         *
+         * @required
+         */
+        onChange?: (value: string[], event?: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void;
     };
 
 /**
@@ -56,7 +76,7 @@ export type DropdownProps<O extends DropdownOption = DropdownOption> = CommonPro
  *
  * @name Dropdown
  */
-function Dropdown<O extends DropdownOption = DropdownOption>({
+function Dropdown({
     options = [],
     value: selected,
     onChange,
@@ -74,7 +94,7 @@ function Dropdown<O extends DropdownOption = DropdownOption>({
     isMulti,
     renderListItem,
     style: styleProp,
-}: DropdownProps<O>) {
+}: DropdownProps) {
     const id = useId(propId);
 
     const { triggerProps, menuProps, closeMenu } = useFloatingMenu({
@@ -116,10 +136,10 @@ function Dropdown<O extends DropdownOption = DropdownOption>({
                     isMulti={isMulti}
                     itemCount={itemCount}
                     items={options}
-                    onChange={(selectedValues, event) => {
+                    onChange={(next, event) => {
                         event?.preventDefault();
                         if (!isMulti) closeMenu();
-                        onChange?.(selectedValues);
+                        onChange?.(next);
                     }}
                     renderListItem={renderListItem}
                     selectedValues={selected}

package/src/Menu.tsx

@@ -1,12 +1,12 @@
 import './menu.scss';
-import { ComponentProps, CSSProperties, MouseEvent as ReactMouseEvent, useMemo } from 'react';
+import { ComponentProps, CSSProperties, 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 './';
 
 export const MIN_ITEM_COUNT = 3;
 export const MAX_ITEM_COUNT = 10;
@@ -16,12 +16,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 +37,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,11 +49,25 @@ export type MenuProps<Item extends MenuItem = MenuItem> = CommonProps<'disabled'
     /**
      * Content to display in the menu.
      *
-     * @type MenuItems
+     * @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 Array<MenuItem>
      */
-    items?: Item[];
+    items?: T[];
     /** A ref to the inner div element. */
-    innerRef?: (node: HTMLElement | null) => void;
+    innerRef?: SetRef<HTMLDivElement>;
     /**
      * Message to display when no results are found
      *
@@ -71,7 +85,7 @@ 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.
      *
@@ -81,12 +95,10 @@ export type MenuProps<Item extends MenuItem = MenuItem> = CommonProps<'disabled'
     /**
      * 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 +106,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,
@@ -107,7 +119,7 @@ function Menu<Item extends MenuItem = MenuItem>({
     renderListItem,
     isMulti,
     ...props
-}: ElementProps<MenuProps<Item>, 'div'>) {
+}: ElementProps<MenuProps, 'div'>) {
     const menuId = useId(idProp);
     const items = Array.isArray(itemsProp) ? itemsProp : [];
     const itemCount = useMemo(
@@ -164,7 +176,7 @@ function Menu<Item extends MenuItem = MenuItem>({
                             id={itemId}
                             key={itemId}
                             label={renderProps?.label?.toString() || item.label?.toString()}
-                            onClick={(event: ReactMouseEvent<HTMLButtonElement, MouseEvent>) => {
+                            onClick={(event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => {
                                 if (renderProps) renderProps?.onClick?.(event);
 
                                 if (onChange) {

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.

package/src/SegmentedControl.tsx

@@ -21,8 +21,17 @@ export type SegmentedControlOption = {
     disabled?: boolean;
     /** The value of the option. If not provided, the label will be used as the value. */
     value?: string;
-    /** The the icon to display before the label. */
+    /**
+     * The the icon to display before the label.
+     *
+     * @type BspkIcon
+     */
     icon?: React.ReactNode;
+    /**
+     * The icon to display before the label when the option is active.
+     *
+     * @type BspkIcon
+     */
     iconActive?: React.ReactNode;
 };
 
@@ -30,13 +39,23 @@ export type SegmentedControlProps = {
     /**
      * The options to display. Each option has a label and an optional leading icon.
      *
-     * @type SegmentedControlOption[]
+     * @example
+     *     [
+     *         { value: '1', label: 'Option 1' },
+     *         { value: '2', label: 'Option 2' },
+     *         { value: '3', label: 'Option 3' },
+     *     ];
+     *
+     * @type Array<SegmentedControlOption>
      * @required
      */
     options: SegmentedControlOption[];
     /**
      * The id of the selected option.
      *
+     * @example
+     *     1;
+     *
      * @required
      */
     value: SegmentedControlOption['value'];

package/src/Switch.tsx

@@ -3,7 +3,7 @@ import { ChangeEvent } from 'react';
 
 import { CommonProps } from './';
 
-export type SwitchProps = CommonProps<'aria-label' | 'disabled' | 'name' | 'onClick' | 'value'> & {
+export type SwitchProps = CommonProps<'aria-label' | 'disabled' | 'name' | 'value'> & {
     /**
      * Marks the control as checked.
      *

package/src/SwitchGroup.tsx

@@ -1,10 +1,9 @@
 import { Switch } from './Switch';
 import { ToggleOptionProps, ToggleOption } from './ToggleOption';
 
-import { ToggleControlProps, ElementProps, CommonProps } from './';
+import { ElementProps, CommonProps } from './';
 
-export type SwitchGroupOption = Pick<ToggleControlProps<HTMLInputElement>, 'value'> &
-    Pick<ToggleOptionProps, 'description' | 'label'>;
+export type SwitchGroupOption = Pick<ToggleOptionProps, 'description' | 'label'> & Required<CommonProps<'value'>>;
 
 export type SwitchGroupProps = CommonProps<'aria-label' | 'name'> & {
     /**
@@ -16,16 +15,23 @@ export type SwitchGroupProps = CommonProps<'aria-label' | 'name'> & {
     /**
      * The options for the switches.
      *
-     * @type SwitchGroupOption[]
+     * @example
+     *     [
+     *         { value: '1', label: 'Option 1' },
+     *         { value: '2', label: 'Option 2' },
+     *         { value: '3', label: 'Option 3' },
+     *     ];
+     *
+     * @type Array<SwitchGroupOption>
      * @required
      */
     options: SwitchGroupOption[];
     /**
      * The values of the switches in the on state.
      *
-     * @type string[]
+     * @type Array<string>
      */
-    values?: SwitchGroupProps['options'][number]['value'][];
+    value?: SwitchGroupProps['options'][number]['value'][];
 };
 
 /**
@@ -33,7 +39,13 @@ export type SwitchGroupProps = CommonProps<'aria-label' | 'name'> & {
  *
  * @name SwitchGroup
  */
-function SwitchGroup({ onChange, options = [], name, values = [], ...props }: ElementProps<SwitchGroupProps, 'div'>) {
+function SwitchGroup({
+    onChange,
+    options = [],
+    name,
+    value: values = [],
+    ...props
+}: ElementProps<SwitchGroupProps, 'div'>) {
     return (
         <div {...props} data-bspk="switch-group" role="group">
             {options.map(({ label, description, value }) => (

package/src/TabGroup.tsx

@@ -33,11 +33,19 @@ export type TabGroupOption = {
      * If not provided, the label will be used as the value.
      */
     value?: string;
-    /** The icon to display on the left side of the tab. */
+    /**
+     * The icon to display on the left side of the tab.
+     *
+     * @type BspkIcon
+     */
     icon?: ReactNode;
-    /** The icon to display on the left side of the tab when the tab is active. */
+    /**
+     * The icon to display on the left side of the tab when the tab is active.
+     *
+     * @type BspkIcon
+     */
     iconActive?: ReactNode;
-    /** The badge count to display on the tab. */
+    /** The badge count to display on the tab */
     badge?: number;
 };
 
@@ -45,12 +53,22 @@ export type TabGroupProps = {
     /**
      * The tabs to display. Each tab has a label and an optional leading icon.
      *
-     * @type TabGroupOption[]
+     * @example
+     *     [
+     *         { value: '1', label: 'Option 1' },
+     *         { value: '2', label: 'Option 2' },
+     *         { value: '3', label: 'Option 3' },
+     *     ];
+     *
+     * @type Array<TabGroupOption>
      * @required
      */
     options: TabGroupOption[];
     /**
-     * The id of the selected tab.
+     * The value of the selected tab.
+     *
+     * @example
+     *     1;
      *
      * @required
      */