@bspk/ui 1.1.21 → 1.1.22

package/src/InlineAlert.tsx

@@ -30,6 +30,13 @@ export type InlineAlertProps = {
  * Inline alerts provide contextual feedback messages for typical user actions with a handful of available and flexible
  * alert messages.
  *
+ * @example
+ *     import { InlineAlert } from '@bspk/ui/InlineAlert';
+ *
+ *     export function Example() {
+ *         return <InlineAlert variant="informational">Example informational inline alert</InlineAlert>;
+ *     }
+ *
  * @name InlineAlert
  */
 function InlineAlert({ children, variant = 'informational', id }: InlineAlertProps) {

package/src/Layout.tsx

@@ -41,6 +41,13 @@ export type LayoutProps<As extends ElementType = 'div'> = {
 /**
  * Utility component used within other components for layout purposes.
  *
+ * @example
+ *     import { Layout } from '@bspk/ui/Layout';
+ *
+ *     export function Example() {
+ *         return <Layout>Low effort example</Layout>;
+ *     }
+ *
  * @name Layout
  */
 function Layout<As extends ElementType = 'div'>({

package/src/Link.tsx

@@ -36,6 +36,13 @@ export type LinkProps = Pick<AnchorHTMLAttributes<unknown>, 'target'> &
 /**
  * This is the standalone link component. Inline links can use the native `a` element.
  *
+ * @example
+ *     import { Link } from '@bspk/ui/Link';
+ *
+ *     export function Example() {
+ *         return <Link href="https://bspk.dev" label="Example label" trailingIcon="external" />;
+ *     }
+ *
  * @name Link
  */
 function Link({ label, trailingIcon, size, variant, ...props }: LinkProps) {

package/src/ListItem.tsx

@@ -67,6 +67,21 @@ export type ListItemProps<As extends ElementType = 'div'> = CommonProps<'active'
  *
  * The ListItemButton is a more limited Button with context specific options.
  *
+ * @example
+ *     import { SvgSquare } from '@bspk/icons/square';
+ *     import { ListItem } from '@bspk/ui/ListItem';
+ *
+ *     export function Example() {
+ *         return (
+ *             <ListItem
+ *                 label="Example label"
+ *                 leading={<SvgSquare />}
+ *                 subText="Example subtest"
+ *                 trailing={<ListItem.Button label="Click me" onClick={() => console.log('Hello world')} />}
+ *             />
+ *         );
+ *     }
+ *
  * @subComponents ListItemButton
  *
  * @name ListItem

package/src/Menu.tsx

@@ -114,6 +114,34 @@ export type MenuProps<T extends MenuItem = MenuItem> = CommonProps<'disabled' |
 /**
  * A container housing a simple list of options presented to the user to select one option at a time.
  *
+ * @example
+ *     import React from 'react';
+ *
+ *     import { Menu } from '@bspk/ui/Menu';
+ *
+ *     export function Example() {
+ *         const [selected, setSelected] = React.useState<string[]>([]);
+ *
+ *         return (
+ *             <Menu
+ *                 items={[
+ *                     { 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' },
+ *                 ]}
+ *                 onChange={(selectedValues: string[]) => setSelected(selectedValues)}
+ *                 selectedValues={selected}
+ *             />
+ *         );
+ *     }
+ *
  * @name Menu
  */
 function Menu({
@@ -185,6 +213,7 @@ function Menu({
                         <Checkbox
                             aria-label={selectAll}
                             checked={!!allSelected}
+                            indeterminate={!allSelected && selectedValues.length > 0}
                             name=""
                             onChange={(checked) => {
                                 onChange?.(checked ? items.map((item) => item.value) : []);

package/src/MenuButton.tsx

@@ -10,6 +10,13 @@ export type MenuButtonProps = Pick<ButtonProps, 'as' | 'onClick'>;
 /**
  * Utility component used within top navigation.
  *
+ * @example
+ *     import { MenuButton } from '@bspk/ui/MenuButton';
+ *
+ *     export function Example() {
+ *         return <MenuButton />;
+ *     }
+ *
  * @name MenuButton
  */
 function MenuButton(props: ElementProps<MenuButtonProps, 'button'>) {

package/src/Modal.tsx

@@ -28,7 +28,29 @@ export type ModalProps = DialogProps & {
  * interactions until an action is selected. Modal is a wrapper around the Dialog component that provides a header and
  * footer for the dialog.
  *
- * TODO: Add support for custom header and footer
+ * @example
+ *     import React from 'react';
+ *
+ *     import { Button } from '@bspk/ui/Button';
+ *     import { Modal } from '@bspk/ui/Modal';
+ *
+ *     export function Example() {
+ *         const [open, setOpen] = React.useState(false);
+ *
+ *         return (
+ *             <>
+ *                 <Button label="Open Dialog" onClick={() => setOpen(true)} />
+ *                 <Modal
+ *                     description="Example description"
+ *                     header="Example header"
+ *                     onClose={() => setOpen(false)}
+ *                     open={open}
+ *                 >
+ *                     Example Modal
+ *                 </Modal>
+ *             </>
+ *         );
+ *     }
  *
  * @name Modal
  */

package/src/NumberField.tsx

@@ -13,6 +13,25 @@ export type NumberFieldProps = InvalidPropsLibrary &
  *
  * This component takes properties from the FormField and NumberInput components.
  *
+ * @example
+ *     import React from 'react';
+ *
+ *     import { NumberField } from '@bspk/ui/NumberField';
+ *
+ *     export function Example() {
+ *         const [state, setState] = React.useState<number>();
+ *
+ *         return (
+ *             <NumberField
+ *                 controlId="Example controlId"
+ *                 label="Example label"
+ *                 name="Example name"
+ *                 onChange={(nextValue) => setState(nextValue)}
+ *                 value={state}
+ *             />
+ *         );
+ *     }
+ *
  * @name NumberField
  */
 function NumberField({

package/src/NumberInput.tsx

@@ -61,6 +61,22 @@ export type NumberInputProps = CommonProps<'aria-label' | 'disabled' | 'id' | 'n
  *
  * The value of the input is a number. The value is clamped to the min and max values if they are provided.
  *
+ * @example
+ *     import { NumberInput } from '@bspk/ui/NumberInput';
+ *
+ *     export function Example() {
+ *         const [state, setState] = React.useState<number>();
+ *
+ *         return (
+ *             <NumberInput
+ *                 aria-label="Example aria-label"
+ *                 name="Example name"
+ *                 onChange={(nextValue) => setState(nextValue)}
+ *                 value={state}
+ *             />
+ *         );
+ *     }
+ *
  * @name NumberInput
  */
 function NumberInput({

package/src/Popover.tsx

@@ -1,6 +1,13 @@
 import { SvgClose } from '@bspk/icons/Close';
 import './popover.scss';
-import { ReactElement, cloneElement, useId, useMemo, useRef, useState } from 'react';
+import {
+    ReactElement,
+    cloneElement,
+    useId,
+    useMemo,
+    useRef,
+    useState,
+} from 'react';
 
 import { Button } from './Button';
 import { Portal } from './Portal';
@@ -41,11 +48,45 @@ export type PopoverProps = CommonProps<'disabled'> & {
 };
 
 /**
- * Brief message that provide additional guidance and helps users perform an action if needed.
+ * Brief message that provide additional guidance and helps users perform an
+ * action if needed.
+ *
+ * @example
+ *     import { useState } from 'react';
+ *     import { Popover } from '@bspk/ui/Popover';
+ *     import { Button } from '@bspk/ui/Button';
+ *
+ *     export function Example() {
+ *         const [showPopover, setShowPopover] = useState<boolean>(false);
+ *
+ *         const togglePopover = () => setShowPopover(!showPopover);
+ *         const onPopoverCallToActionClick = () => alert('Action clicked');
+ *
+ *         return (
+ *             <Popover
+ *                 placement="bottom"
+ *                 content="This is a popover content"
+ *                 header="Popover Header"
+ *                 callToAction={{
+ *                     label: 'Action',
+ *                     onClick: onPopoverCallToActionClick,
+ *                 }}
+ *             >
+ *                 <Button label="Toggle popover" onClick={togglePopover} />
+ *             </Popover>
+ *         );
+ *     }
  *
  * @name Popover
  */
-function Popover({ placement = 'top', header, content, callToAction, children, disabled = false }: PopoverProps) {
+function Popover({
+    placement = 'top',
+    header,
+    content,
+    callToAction,
+    children,
+    disabled = false,
+}: PopoverProps) {
     const id = useId();
     const [show, setShow] = useState(false);
     const arrowRef = useRef<HTMLElement | null>(null);
@@ -83,13 +124,20 @@ function Popover({ placement = 'top', header, content, callToAction, children, d
                     id={id}
                     ref={(node) => {
                         elements.setFloating(node);
-                        elements.setTrigger(document.querySelector<HTMLElement>(`[aria-describedby="${id}"]`));
+                        elements.setTrigger(
+                            document.querySelector<HTMLElement>(
+                                `[aria-describedby="${id}"]`,
+                            ),
+                        );
                     }}
                     style={floatingStyles}
                 >
                     <header>
                         <Txt variant="heading-h6">{header}</Txt>
-                        <button aria-label="Close" onClick={() => setShow(false)}>
+                        <button
+                            aria-label="Close"
+                            onClick={() => setShow(false)}
+                        >
                             <SvgClose />
                         </button>
                     </header>

package/src/ProgressBar.tsx

@@ -36,6 +36,14 @@ export type ProgressBarProps = {
  * occurring in the background.
  *
  * @name ProgressBar
+ * @example
+ *      import { ProgressBar } from '@bspk/ui/ProgressBar';
+ *
+ *      export function Example() {
+ *          return (
+ *              <ProgressBar label="Example label" completion={50} />
+ *          );
+ *      }
  */
 function ProgressBar({ size = 'large', completion = 0, align = 'center', label }: ProgressBarProps) {
     const id = useId();

package/src/ProgressCircle.tsx

@@ -27,6 +27,14 @@ export type ProgressCircleProps = {
  * Rotating circle or pill that indicates the status or state of completion for a process that’s part of a user flow.
  *
  * @name ProgressCircle
+ * @example
+ *      import { ProgressCircle } from '@bspk/ui/ProgressCircle';
+ *
+ *      export function Example() {
+ *          return (
+ *              <ProgressCircle label="Example label"/>
+ *          );
+ *      }
  */
 function ProgressCircle({ label, labelPosition, size = 'medium' }: ProgressCircleProps) {
     let variant: TxtVariant = 'labels-base';

package/src/ProgressionStepper.tsx

@@ -66,6 +66,18 @@ export type ProgressionStepperProps = {
  * A progress stepper is a horizontal visual indicator that let’s the user know the progression of the current process.
  *
  * @name ProgressionStepper
+ * @example
+ *     import { ProgressionStepper } from '@bspk/ui/ProgressionStepper';
+ *
+ *     export function Example() {
+ *         return (
+ *             <ProgressionStepper steps={[
+ *                 { name: 'Step 1' },
+ *                 { name: 'Step 2' },
+ *                 { name: 'Step 3' },
+ *             ]} />
+ *         );
+ *     }
  */
 function ProgressionStepper({
     steps = [],

package/src/RadioGroup.tsx

@@ -1,8 +1,12 @@
+import { useId } from 'react';
+
 import { Radio } from './Radio';
 import { ToggleOptionProps, ToggleOption } from './ToggleOption';
 
 import { ElementProps, CommonProps } from './';
 
+import './radio-group.scss';
+
 export type RadioGroupOption = Pick<ToggleOptionProps, 'description' | 'label'> & Required<CommonProps<'value'>>;
 
 export type RadioGroupProps = CommonProps<'name'> & {
@@ -29,8 +33,8 @@ export type RadioGroupProps = CommonProps<'name'> & {
      *
      * @example
      *     [
-     *         { value: '1', label: 'Option 1', description: 'Description here' },
-     *         { value: '2', label: 'Option 2' },
+     *         { value: '1', label: 'Option 1' },
+     *         { value: '2', label: 'Option 2', description: 'Description here' },
      *         { value: '3', label: 'Option 3' },
      *     ];
      *
@@ -39,16 +43,47 @@ export type RadioGroupProps = CommonProps<'name'> & {
      */
     options: RadioGroupOption[];
     /**
-     * The size of the radio group labels.
+     * The label of the radio group.
+     *
+     * @required
+     */
+    label: string;
+    /**
+     * Shows the RadioGroup label. When label isn't showing it is used as the aria-label prop.
      *
-     * @default base
+     * @default true
      */
-    size?: 'base' | 'large' | 'small';
+    showLabel?: boolean;
 };
 
 /**
  * A group of radios that allows users to choose one or more items from a list or turn an feature on or off.
  *
+ * @example
+ *     import { useState } from 'react';
+ *     import { RadioGroup } from '@bspk/ui/RadioGroup';
+ *
+ *     export function Example() {
+ *         const [selectedOption, setSelectedOption] = useState<string>('1');
+ *
+ *         return (
+ *             <RadioGroup
+ *                 name="Example name"
+ *                 onChange={(nextValue) => setSelectedOption(nextValue)}
+ *                 options={[
+ *                     {
+ *                         value: '1',
+ *                         label: 'Option 1',
+ *                         description: 'Description here',
+ *                     },
+ *                     { value: '2', label: 'Option 2' },
+ *                     { value: '3', label: 'Option 3' },
+ *                 ]}
+ *                 value={selectedOption}
+ *             />
+ *         );
+ *     }
+ *
  * @name RadioGroup
  */
 function RadioGroup({
@@ -56,29 +91,37 @@ function RadioGroup({
     options = [],
     name,
     value: groupValue,
-    size = 'base',
+    label: groupLabel,
+    showLabel = true,
     ...props
 }: ElementProps<RadioGroupProps, 'div'>) {
+    const id = `radio-group-${useId()}`;
+
     return (
-        <div {...props} data-bspk="radio-group" role="radiogroup" style={{ display: 'contents' }}>
-            {options.map(({ label, description, value }, index) => {
-                return (
-                    <ToggleOption
-                        description={description}
-                        key={`toggle-option-${value || index}`}
-                        label={label}
-                        size={size}
-                    >
-                        <Radio
-                            aria-label={label}
-                            checked={groupValue === value}
-                            name={name}
-                            onChange={(checked) => checked && onChange(value)}
-                            value={value}
-                        />
-                    </ToggleOption>
-                );
-            })}
+        <div
+            {...props}
+            aria-label={!showLabel ? groupLabel : undefined}
+            aria-labelledby={showLabel ? `${id}-label` : undefined}
+            data-bspk="radio-group"
+            id={id}
+            role="group"
+        >
+            {showLabel && <label id={`${id}-label`}>{groupLabel}</label>}
+            <div role="radiogroup">
+                {options.map(({ label, description, value }, index) => {
+                    return (
+                        <ToggleOption description={description} key={`toggle-option-${value || index}`} label={label}>
+                            <Radio
+                                aria-label={label}
+                                checked={groupValue === value}
+                                name={name}
+                                onChange={(checked) => checked && onChange(value)}
+                                value={value}
+                            />
+                        </ToggleOption>
+                    );
+                })}
+            </div>
         </div>
     );
 }

package/src/RadioOption.tsx

@@ -19,13 +19,18 @@ export type RadioOptionProps = InvalidPropsLibrary &
 /**
  * A control that allows users to choose one or more items from a list or turn an feature on or off.
  *
+ * If only a radio button is needed, consider using the `Radio` component directly.
+ *
  * @name RadioOption
  */
-function RadioOption({ label, description, ...checkboxProps }: RadioOptionProps) {
+function RadioOption({ label: labelProp, description, ...checkboxProps }: RadioOptionProps) {
+    const label = labelProp || description;
     return (
-        <ToggleOption data-bspk="radio-option" description={description} label={label}>
-            <Radio {...checkboxProps} aria-label={label} />
-        </ToggleOption>
+        label && (
+            <ToggleOption data-bspk="radio-option" description={description} label={label}>
+                <Radio {...checkboxProps} aria-label={label} />
+            </ToggleOption>
+        )
     );
 }
 

package/src/SearchBar.tsx

@@ -10,7 +10,10 @@ import { useFloatingMenu } from './hooks/useFloatingMenu';
 import { useId } from './hooks/useId';
 //import { useFloatingMenu } from './hooks/useFloatingMenu';
 
-export type SearchBarProps<T extends MenuItem = MenuItem> = Pick<MenuProps<T>, 'itemCount' | 'noResultsMessage'> &
+export type SearchBarProps<T extends MenuItem = MenuItem> = Pick<
+    MenuProps<T>,
+    'itemCount' | 'noResultsMessage'
+> &
     Pick<TextInputProps, 'aria-label' | 'id' | 'inputRef' | 'name' | 'size'> & {
         /** The current value of the search bar. */
         value?: string;
@@ -73,6 +76,40 @@ export type SearchBarProps<T extends MenuItem = MenuItem> = Pick<MenuProps<T>, '
 /**
  * Component description coming soon.
  *
+ * @example
+ *     import { useState } from 'react';
+ *     import { SearchBar } from '@bspk/ui/SearchBar';
+ *
+ *     export function Example() {
+ *         const [searchText, setSearchText] = useState<string>('');
+ *
+ *         const handleItemSelect = (item) =>
+ *             console.log('Selected item:', item);
+ *
+ *         return (
+ *             <SearchBar
+ *                 aria-label="Example aria-label"
+ *                 items={[
+ *                     { value: '1', label: 'Apple Pie' },
+ *                     { value: '2', label: 'Banana Split' },
+ *                     { value: '3', label: 'Cherry Tart' },
+ *                     { value: '4', label: 'Dragonfruit Sorbet' },
+ *                     { value: '5', label: 'Elderberry Jam' },
+ *                     { value: '6', label: 'Fig Newton' },
+ *                     { value: '7', label: 'Grape Soda' },
+ *                     { value: '8', label: 'Honeydew Smoothie' },
+ *                     { value: '9', label: 'Ice Cream Sandwich' },
+ *                     { value: '10', label: 'Jackfruit Pudding' },
+ *                 ]}
+ *                 name="Example name"
+ *                 placeholder="Search"
+ *                 value={searchText}
+ *                 onChange={setSearchText}
+ *                 onSelect={handleItemSelect}
+ *             />
+ *         );
+ *     }
+ *
  * @name SearchBar
  */
 function SearchBar({
@@ -92,7 +129,12 @@ function SearchBar({
 }: SearchBarProps) {
     const id = useId(idProp);
     const {
-        triggerProps: { ref: triggerRef, onClick, onKeyDownCapture, ...triggerProps },
+        triggerProps: {
+            ref: triggerRef,
+            onClick,
+            onKeyDownCapture,
+            ...triggerProps
+        },
         menuProps,
         closeMenu,
     } = useFloatingMenu({
@@ -154,7 +196,9 @@ function SearchBar({
                         }
                         onChange={(selectedValues, event) => {
                             event?.preventDefault();
-                            const item = items?.find((i) => i.value === selectedValues[0]);
+                            const item = items?.find(
+                                (i) => i.value === selectedValues[0],
+                            );
                             onSelect?.(item);
                             onChange(item?.label || '');
                             closeMenu();