@bspk/ui 1.3.7 → 1.3.9

package/src/components/Radio/RadioExample.tsx

@@ -1,7 +1,8 @@
 import { ComponentExample, createUid } from '-/utils/demo';
 
 export const RadioExample: ComponentExample = {
-    render: ({ props, Component }) => (
-        <Component {...props} aria-label={props['aria-label'] || 'radio aria-label'} name={createUid('radio')} />
-    ),
+    defaultState: {
+        'aria-label': 'radio aria-label',
+    },
+    render: ({ props, Component }) => <Component {...props} name={createUid('radio')} />,
 };

package/src/components/RadioGroup/RadioGroup.tsx

@@ -40,7 +40,7 @@ export type RadioGroupProps = Omit<FieldControlProps, 'readOnly'> & {
  *     import { useState } from 'react';
  *     import { RadioGroup } from '@bspk/ui/RadioGroup';
  *
- *     function Example() {
+ *     () => {
  *         const [selectedOption, setSelectedOption] = useState<string>('1');
  *
  *         return (
@@ -59,7 +59,7 @@ export type RadioGroupProps = Omit<FieldControlProps, 'readOnly'> & {
  *                 value={selectedOption}
  *             />
  *         );
- *     }
+ *     };
  *
  * @name RadioGroup
  * @phase UXReview

package/src/components/Rating/Rating.tsx

@@ -1,6 +1,5 @@
 import './rating.scss';
 import { SvgStarFill } from '@bspk/icons/StarFill';
-import { ElementType } from 'react';
 
 export type RatingSize = 'large' | 'medium' | 'small';
 export type RatingProps = {
@@ -12,7 +11,7 @@ export type RatingProps = {
      */
     value?: number;
     /**
-     * If included the component is in interactive mode and this callback is fired when a star is selected.
+     * If included the component is interactive and this callback is fired when the user selects a new rating value.
      *
      * @param value - The new value of the rating.
      */
@@ -39,37 +38,58 @@ const iconWidths: Record<RatingSize, number> = {
  * @example
  *     import { Rating } from '@bspk/ui/Rating';
  *
- *     function Example() {
- *         return <Rating value={4.5} />;
- *     }
+ *     <Rating value={4.5} size="large" />;
  *
  * @name Rating
  * @phase UXReview
  */
 export function Rating({ size = 'medium', value, onChange }: RatingProps) {
-    const As: ElementType = onChange ? 'button' : 'div';
+    if (!onChange)
+        return (
+            <div
+                aria-label={value ? `${value} out of ${MAX_STARS} stars` : 'Rating'}
+                data-bspk="rating"
+                data-size={size}
+                role="img"
+            >
+                {Array.from({ length: MAX_STARS }, (_, index) => {
+                    const fill = getFill(index + 1, value);
+                    return (
+                        <div data-fill={fill} data-star key={index} role="presentation" tabIndex={-1}>
+                            <SvgStarFill width={iconWidths[size]} />
+                            {fill === 'half' && (
+                                <div data-fill-half>
+                                    <div data-star>
+                                        <SvgStarFill width={iconWidths[size]} />
+                                    </div>
+                                </div>
+                            )}
+                        </div>
+                    );
+                })}
+            </div>
+        );
 
     return (
         <div
-            aria-label={onChange ? 'Select a star rating' : value ? `${value} out of ${MAX_STARS} stars` : 'Rating'}
+            aria-label={value ? `${value} out of ${MAX_STARS} stars` : 'Select a star rating'}
             data-bspk="rating"
             data-size={size}
-            role={onChange ? 'radiogroup' : 'img'}
+            role="radiogroup"
         >
             {Array.from({ length: MAX_STARS }, (_, index) => {
                 const fill = getFill(index + 1, value);
                 const selected = value !== undefined && Math.floor(value) === index;
                 return (
-                    <As
+                    <button
                         aria-checked={selected}
-                        aria-hidden={!onChange}
-                        aria-label={onChange ? `Rate ${index + 1}` : undefined}
+                        aria-label={`Rate ${index + 1}`}
                         data-fill={fill}
                         data-star
                         key={index}
                         onClick={() => onChange?.(index + 1)}
-                        role={onChange ? 'radio' : 'presentation'}
-                        tabIndex={onChange ? (selected ? 0 : -1) : -1}
+                        role="radio"
+                        tabIndex={selected ? 0 : -1}
                         type="button"
                     >
                         <SvgStarFill width={iconWidths[size]} />
@@ -80,7 +100,7 @@ export function Rating({ size = 'medium', value, onChange }: RatingProps) {
                                 </div>
                             </div>
                         )}
-                    </As>
+                    </button>
                 );
             })}
         </div>

package/src/components/Rating/RatingExample.tsx

@@ -3,11 +3,28 @@ import { ComponentExampleFn, Preset } from '-/utils/demo';
 
 export const presets: Preset<RatingProps>[] = [
     {
-        label: 'Non interactive',
+        label: 'Read Only, No Value',
         propState: {
             onChange: undefined,
+            value: undefined,
         },
     },
+    {
+        label: 'Read Only',
+        propState: {
+            onChange: undefined,
+            value: 4.5,
+        },
+        designPattern: 'A read only representation of ratings, a scale of 1 to 5.',
+    },
+    {
+        label: 'Interactive',
+        propState: {
+            onChange: () => {},
+        },
+        designPattern:
+            'Interactive control that allow customers to indicate their feelings about an experience or product on a scale of 1 to 5.',
+    },
 ];
 
 export const RatingExample: ComponentExampleFn<RatingProps> = () => {

package/src/components/SearchBar/SearchBar.tsx

@@ -72,7 +72,7 @@ export type SearchBarProps<O extends SearchBarOption = SearchBarOption> = Omit<
  *     import { useState } from 'react';
  *     import { SearchBar } from '@bspk/ui/SearchBar';
  *
- *     function Example() {
+ *     () => {
  *         const [searchText, setSearchText] = useState('');
  *
  *         return (
@@ -96,7 +96,7 @@ export type SearchBarProps<O extends SearchBarOption = SearchBarOption> = Omit<
  *                 onChange={setSearchText}
  *             />
  *         );
- *     }
+ *     };
  *
  * @name SearchBar
  * @phase UXReview

package/src/components/SearchBar/SearchBarExample.tsx

@@ -3,6 +3,9 @@ import { ComponentExample } from '-/utils/demo';
 import { randomString } from '-/utils/random';
 
 export const SearchBarExample: ComponentExample<SearchBarProps> = {
+    defaultState: {
+        'aria-label': 'search bar aria-label',
+    },
     render: ({ props, Component }) => {
         return <Component {...props} id={`search-bar-${randomString(8)}`} />;
     },

package/src/components/SegmentedControl/SegmentedControl.tsx

@@ -12,8 +12,8 @@ export type SegmentedControlProps = TabListProps<SegmentedControlOption>;
  *     import { useState } from 'react';
  *     import { SegmentedControl } from '@bspk/ui/SegmentedControl';
  *
- *     function Example() {
- *         const [selectedOption, setSelectedOption] = useState<string>();
+ *     () => {
+ *         const [selectedOption, setSelectedOption] = useState<string>('');
  *
  *         return (
  *             <SegmentedControl
@@ -26,7 +26,7 @@ export type SegmentedControlProps = TabListProps<SegmentedControlOption>;
  *                 value={selectedOption}
  *             />
  *         );
- *     }
+ *     };
  *
  * @name SegmentedControl
  * @phase UXReview

package/src/components/SegmentedControl/SegmentedControlExample.tsx

@@ -1,9 +1,3 @@
-import { SvgCircle } from '@bspk/icons/Circle';
-import { SvgDiamond } from '@bspk/icons/Diamond';
-import { SvgDiamondFill } from '@bspk/icons/DiamondFill';
-import { SvgSquare } from '@bspk/icons/Square';
-import { SvgSquareFill } from '@bspk/icons/SquareFill';
-
 import { SegmentedControlOption, SegmentedControlProps } from '.';
 import { ComponentExample, Preset } from '-/utils/demo';
 
@@ -11,20 +5,20 @@ const PRESET_OPTIONS: SegmentedControlOption[] = [
     {
         value: '1',
         label: 'Option 1',
-        icon: <SvgDiamond />,
-        iconSelected: <SvgDiamondFill />,
+        icon: 'Diamond',
+        iconSelected: 'DiamondFill',
     },
     {
         value: '2',
         label: 'Disabled 2',
         disabled: true,
-        icon: <SvgCircle />,
+        icon: 'Circle',
     },
     {
         value: '3',
         label: 'Option 3',
-        icon: <SvgSquare />,
-        iconSelected: <SvgSquareFill />,
+        icon: 'Square',
+        iconSelected: 'SquareFill',
     },
 ];
 
@@ -64,7 +58,11 @@ export const presets: Preset<SegmentedControlProps>[] = [
 export const SegmentedControlExample: ComponentExample<SegmentedControlProps> = {
     containerStyle: { width: '100%', overflow: 'auto', alignItems: 'start' },
     defaultState: {
-        options: PRESET_OPTIONS,
+        options: PRESET_OPTIONS.map((option) => ({
+            ...option,
+            icon: undefined,
+            iconSelected: undefined,
+        })),
     },
     presets,
     variants: false,

package/src/components/Select/Select.tsx

@@ -77,29 +77,14 @@ export type SelectProps = CommonProps<'size'> &
  *         { id: '6', label: 'Option 6' },
  *     ];
  *
- *     function ExampleStandalone() {
- *         const [selected, setSelected] = React.useState<string[]>([]);
+ *     () => {
+ *         const [selected, setSelected] = useState<string[]>([]);
  *
  *         return (
- *             <Select
- *                 aria-label="Select an option"
- *                 itemCount={5}
- *                 name="example-select"
- *                 onChange={setSelected}
- *                 options={OPTIONS}
- *                 placeholder="Select an option"
- *                 size="medium"
- *                 value={selected}
- *             />
- *         );
- *     }
- *
- *     function ExampleWithField() {
- *         const [selected, setSelected] = React.useState<string[]>([]);
- *         return (
- *             <Field>
- *                 <FieldLabel>Select an option</FieldLabel>
+ *             <>
+ *                 // standalone select example
  *                 <Select
+ *                     aria-label="Select an option"
  *                     itemCount={5}
  *                     name="example-select"
  *                     onChange={setSelected}
@@ -108,12 +93,26 @@ export type SelectProps = CommonProps<'size'> &
  *                     size="medium"
  *                     value={selected}
  *                 />
- *                 <FieldDescription>
- *                     The select allows you to choose one option from a list of options.
- *                 </FieldDescription>
- *             </Field>
+ *                 <br />
+ *                 // select used within a field
+ *                 <Field>
+ *                     <FieldLabel>Select an option</FieldLabel>
+ *                     <Select
+ *                         itemCount={5}
+ *                         name="example-select"
+ *                         onChange={setSelected}
+ *                         options={OPTIONS}
+ *                         placeholder="Select an option"
+ *                         size="medium"
+ *                         value={selected}
+ *                     />
+ *                     <FieldDescription>
+ *                         The select allows you to choose one option from a list of options.
+ *                     </FieldDescription>
+ *                 </Field>
+ *             </>
  *         );
- *     }
+ *     };
  *
  * @name Select
  * @phase UXReview

package/src/components/Select/SelectExample.tsx

@@ -156,6 +156,7 @@ export const SelectExample: ComponentExample<SelectProps> = {
         options: DEFAULT_OPTIONS,
         scrollLimit: 5,
         value: '',
+        'aria-label': 'select aria-label',
     },
     render: ({ props, Component, preset }) => <Component key={preset?.label} {...props} />,
     presets,

package/src/components/Skeleton/Skeleton.tsx

@@ -49,20 +49,16 @@ export type SkeletonProps = {
  * @example
  *     import { Skeleton } from '@bspk/ui/skeleton';
  *
- *     function Example(item: { title: string; src: string } | null) {
- *         return (
- *             <Skeleton variant="photo" width={210} height={118}>
- *                 <img
- *                     style={{
- *                         width: 210,
- *                         height: 118,
- *                     }}
- *                     alt={item.title}
- *                     src={item.src}
- *                 />
- *             </Skeleton>
- *         );
- *     }
+ *     <Skeleton variant="photo" width={210} height={118}>
+ *         <img
+ *             style={{
+ *                 width: 210,
+ *                 height: 118,
+ *             }}
+ *             alt={'A cool photo'}
+ *             src={'https://example.com/cool-photo.jpg'}
+ *         />
+ *     </Skeleton>;
  *
  * @exampleDescription This example shows a skeleton loading state for an image but can be used for any element.
  *

package/src/components/Skeleton/SkeletonExample.tsx

@@ -1,8 +1,7 @@
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import { SkeletonProps, SkeletonVariant } from '.';
 import { Avatar } from '-/components/Avatar';
 import { ExamplePlaceholder } from '-/components/ExamplePlaceholder';
-import { useTimeout } from '-/hooks/useTimeout';
 import { ComponentExample, ComponentExampleRenderProps, Preset } from '-/utils/demo';
 
 export const presets: Preset<SkeletonProps>[] = [
@@ -29,7 +28,10 @@ function SkeletonTransition({
     props,
 }: Pick<ComponentExampleRenderProps<SkeletonProps>, 'Component' | 'props'>) {
     const [loaded, setLoaded] = useState(false);
-    useTimeout(() => setLoaded(true), 3000);
+
+    useEffect(() => {
+        setTimeout(() => setLoaded(true), 3000);
+    }, []);
 
     return <Component {...props}>{loaded && PROP_VARIANT_CHILDREN[props!.variant as SkeletonVariant]}</Component>;
 }

package/src/components/SkeletonText/SkeletonText.tsx

@@ -33,15 +33,11 @@ export type SkeletonTextProps = {
  * @example
  *     import { SkeletonText } from '@bspk/ui/SkeletonText';
  *
- *     function Example(item: { content: string } | null) {
- *         return (
- *             <SkeletonText textLines={1} textVariant="body-base">
- *                 <Txt as="p" variant="body-base">
- *                     {item?.content}
- *                 </Txt>
- *             </SkeletonText>
- *         );
- *     }
+ *     <SkeletonText textLines={1} textVariant="body-base">
+ *         <Txt as="p" variant="body-base">
+ *             {'This is the loaded text content that was previously loading.'}
+ *         </Txt>
+ *     </SkeletonText>;
  *
  * @exampleDescription This example shows a skeleton loading state for some text but can be used for any element.
  *

package/src/components/Slider/Slider.tsx

@@ -74,11 +74,11 @@ export type SliderProps<Value> = Pick<CommonPropsLibrary, 'disabled' | 'readOnly
  *     import { Slider } from '@bspk/ui/Slider';
  *     import { useState } from 'react';
  *
- *     function Example() {
+ *     () => {
  *         const [value, setValue] = useState(50);
  *
  *         return <Slider value={value} min={0} max={100} label="Slider Example" onChange={setValue} />;
- *     }
+ *     };
  *
  * @name Slider
  * @phase UXReview

package/src/components/Slider/SliderExample.tsx

@@ -22,19 +22,21 @@ export const SliderExample: ComponentExample<SliderProps<number | [number, numbe
     },
     presets: [
         {
-            label: 'Basic Slider',
+            label: 'Formatted Number',
             propState: {
-                label: 'Basic option',
-                min: 20,
-                max: 80,
-                step: 1,
-                value: 30,
+                label: 'Price option',
+                min: 0,
+                max: 100,
+                step: 5,
+                value: 50,
                 formatNumber: (num) => `$${num}`,
-                name: 'basic-slider',
+                name: 'formatted-number-slider',
             },
         },
         {
             label: 'Range Slider',
+            designPattern:
+                'A control element that allows customers to select a value or adjust a setting by moving the handle along a horizontal track.',
             propState: {
                 label: 'Range option',
                 min: 0,
@@ -48,19 +50,42 @@ export const SliderExample: ComponentExample<SliderProps<number | [number, numbe
             },
         },
         {
-            label: 'Undefined Value',
+            label: 'Continuous Slider',
+            designPattern: 'Continuous sliders allow users to select a value along a subjective range.',
             propState: {
-                label: 'undefined',
-                min: 50,
-                max: 150,
+                label: 'What is the purpose of life?',
+                min: 0,
+                max: 100,
+                value: 42,
                 step: 1,
-                value: null as unknown as [number, number],
-                formatNumber: (num, context) => {
-                    if (context === 'max') return `${num}% Passing`;
-                    return `${num}%`;
-                },
-                name: 'undefined-slider',
+                formatNumber: (num) => num.toFixed(0),
+                name: 'continuous-slider',
+                marks: false,
+            },
+        },
+        {
+            label: 'Discrete Slider',
+            designPattern:
+                'Discrete sliders can be adjusted to a specific value by referencing its value indicator. You can generate a mark for each step with marks={true}.',
+            propState: {
+                label: 'Discrete option',
+                min: 0,
+                max: 100,
+                step: 10,
+                value: 40,
+                formatNumber: (num) => num.toString(),
+                name: 'discrete-slider',
+                marks: true,
             },
         },
     ],
+    defaultState: {
+        label: 'Basic option',
+        min: 20,
+        max: 80,
+        step: 1,
+        value: 30,
+        formatNumber: (num) => `$${num}`,
+        name: 'basic-slider',
+    },
 };

package/src/components/Snackbar/Manager.tsx

@@ -0,0 +1,64 @@
+import { IconName } from '@bspk/icons';
+import { SvgIcon } from '@bspk/icons/SvgIcon';
+import { useState } from 'react';
+import { SnackbarProps, Snackbar } from './Snackbar';
+import { BspkIcon } from '-/types/common';
+import { createCustomEvent } from '-/utils/createCustomEvent';
+
+const CLEAR_EVENT = 'bspk-snackbar-clear' as const;
+
+// make onClose optional
+export type SendSnackbarProps = Omit<SnackbarProps, 'icon' | 'innerRef' | 'onClose'> & {
+    onClose?: SnackbarProps['onClose'];
+    icon?: BspkIcon;
+};
+
+export type SnackbarManagerProps = {
+    /**
+     * Default timeout for snackbars sent via the manager (in milliseconds).
+     *
+     * @default 5000
+     */
+    defaultTimeout?: number;
+};
+
+const SnackbarEvent = createCustomEvent<SendSnackbarProps | string | typeof CLEAR_EVENT>('bspk-snackbar-event');
+
+/**
+ * SnackbarManager is a single use component that listens for snackbar events and displays them to the user.
+ *
+ * We use a custom event to communicate between components and this manager.
+ *
+ * We don't store the snackbar props in React.Context to avoid unnecessary re-renders of all components that consume the
+ * context. :)
+ *
+ * @name SnackbarManager
+ *
+ * @phase UXReview
+ */
+export function SnackbarManager({ defaultTimeout = 5000 }: SnackbarManagerProps) {
+    const [snackbarProps, setSnackbarProps] = useState<SendSnackbarProps | undefined>();
+    const { useEventListener } = SnackbarEvent;
+
+    useEventListener((detail) => {
+        if (detail === CLEAR_EVENT || !detail) return setSnackbarProps(undefined);
+
+        setSnackbarProps(typeof detail === 'string' ? { text: detail, timeout: defaultTimeout } : detail);
+    });
+
+    return snackbarProps ? (
+        <Snackbar
+            {...snackbarProps}
+            icon={snackbarProps.icon ? <SvgIcon name={snackbarProps.icon as IconName} /> : undefined}
+            onClose={() => {
+                setSnackbarProps(undefined);
+                snackbarProps?.onClose?.();
+            }}
+            open={true}
+        />
+    ) : null;
+}
+
+export const sendSnackbar = (props: SendSnackbarProps | string) => SnackbarEvent.send(props);
+
+export const clearSnackbar = () => SnackbarEvent.send(CLEAR_EVENT);

package/src/components/Snackbar/Snackbar.tsx

@@ -41,8 +41,6 @@ export type SnackbarProps = CommonProps<'id'> & {
      * @required
      */
     onClose: () => void;
-    /** Content to be rendered inside the snack bar provider, the snackbar trigger element. */
-    // children: ReactNode;
     /**
      * Time in milliseconds after which the snackbar will auto dismiss.
      *
@@ -67,24 +65,43 @@ export type SnackbarProps = CommonProps<'id'> & {
 };
 
 /**
- * Snackbars are intended to provide feedback about an action. Because of focus trap these will interrupt the customer
- * experience.
+ * Snackbars provide brief feedback about user actions. Because they use a focus trap, they interrupt the user's
+ * workflow and should be used sparingly.
+ *
+ * #### Inline
+ *
+ * Render the Snackbar inside the component that triggers it and control visibility with local state/props. This is
+ * simple and useful for small or isolated components, but can lead to duplicate snackbars or inadvertent render loops
+ * if state is not managed carefully.
+ *
+ * #### Managed
+ *
+ * Use the SnackbarManager together with `sendSnackbar` and `clearSnackbar` to control snackbars globally. This lets any
+ * part of the app trigger snackbars without prop drilling and helps avoid duplicates. and prevents duplicate snackbars
+ * from being shown.
  *
  * @example
  *     import { Snackbar } from '@bspk/ui/Snackbar';
  *     import { Button } from '@bspk/ui/Button';
  *     import { useState } from 'react';
+ *     import { sendSnackbar } from '@bspk/ui/Snackbar/Manager';
  *
- *     function ExampleComponent(props) {
+ *     () => {
  *         const [snackbarOpen, setSnackbarOpen] = useState(false);
  *
  *         return (
  *             <>
+ *                 // -- inline snackbar
  *                 <Button label="Show snackbar" onClick={() => setSnackbarOpen(true)} size="medium" title="Snackbar" />
  *                 <Snackbar text="I am an example." open={snackbarOpen} onClose={() => setSnackbarOpen(false)} />
+ *                 // -- managed snackbar
+ *                 <Button
+ *                     label="Show managed snackbar"
+ *                     onClick={() => sendSnackbar({ text: 'I am a managed snackbar!' })}
+ *                 />
  *             </>
  *         );
- *     }
+ *     };
  *
  * @name Snackbar
  *