@bspk/ui 1.3.8 → 1.3.10

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/Scrim/Scrim.tsx

@@ -23,7 +23,6 @@ export type ScrimProps = CommonProps<'owner'> & {
  * attention to a modal or sheet.
  *
  * @name Scrim
- *
  * @phase Utility
  */
 export function Scrim({ visible = true, owner, ...props }: ScrimProps) {

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/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

@@ -68,39 +68,24 @@ export type SelectProps = CommonProps<'size'> &
  * @example
  *     import { Select } from '@bspk/ui/Select';
  *
- *     const OPTIONS = [
- *         { id: '1', label: 'Option 1' },
- *         { id: '2', label: 'Option 2' },
- *         { id: '3', label: 'Option 3' },
- *         { id: '4', label: 'Option 4' },
- *         { id: '5', label: 'Option 5' },
- *         { id: '6', label: 'Option 6' },
- *     ];
+ *     () => {
+ *         const OPTIONS = [
+ *             { id: '1', label: 'Option 1' },
+ *             { id: '2', label: 'Option 2' },
+ *             { id: '3', label: 'Option 3' },
+ *             { id: '4', label: 'Option 4' },
+ *             { id: '5', label: 'Option 5' },
+ *             { 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
- *                     itemCount={5}
+ *                     aria-label="Select an option"
+ *                     scrollLimit={5}
  *                     name="example-select"
  *                     onChange={setSelected}
  *                     options={OPTIONS}
@@ -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
+ *                         scrollLimit={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/Skeleton/Circular.tsx

@@ -1,5 +1,11 @@
 import { Skeleton, SkeletonProps } from './Skeleton';
 
+/**
+ * SkeletonCircular component displays a circular skeleton loader.
+ *
+ * @name SkeletonCircular
+ * @parent Skeleton
+ */
 export function SkeletonCircular(props: Pick<SkeletonProps, 'height' | 'width'>) {
     return <Skeleton {...props} variant="circular" />;
 }

package/src/components/Skeleton/Photo.tsx

@@ -1,5 +1,11 @@
 import { Skeleton, SkeletonProps } from './Skeleton';
 
+/**
+ * SkeletonPhoto component displays a photo skeleton loader.
+ *
+ * @name SkeletonPhoto
+ * @parent Skeleton
+ */
 export function SkeletonPhoto(props: Pick<SkeletonProps, 'height' | 'width'>) {
     return <Skeleton {...props} variant="photo" />;
 }

package/src/components/Skeleton/Profile.tsx

@@ -1,5 +1,11 @@
 import { Skeleton, SkeletonProps } from './Skeleton';
 
+/**
+ * SkeletonProfile component displays a profile skeleton loader.
+ *
+ * @name SkeletonProfile
+ * @parent Skeleton
+ */
 export function SkeletonProfile(props: Pick<SkeletonProps, 'height' | 'width'>) {
     return <Skeleton {...props} variant="profile" />;
 }

package/src/components/Skeleton/Rectangular.tsx

@@ -1,5 +1,11 @@
 import { Skeleton, SkeletonProps } from './Skeleton';
 
+/**
+ * SkeletonRectangular component displays a rectangular skeleton loader.
+ *
+ * @name SkeletonRectangular
+ * @parent Skeleton
+ */
 export function SkeletonRectangular(props: Pick<SkeletonProps, 'height' | 'width'>) {
     return <Skeleton {...props} variant="rectangular" />;
 }

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/Skeleton/Thumbnail.tsx

@@ -1,5 +1,11 @@
 import { Skeleton, SkeletonProps } from './Skeleton';
 
+/**
+ * SkeletonThumbnail component displays a thumbnail skeleton loader.
+ *
+ * @name SkeletonThumbnail
+ * @parent Skeleton
+ */
 export function SkeletonThumbnail(props: Pick<SkeletonProps, 'height' | 'width'>) {
     return <Skeleton {...props} variant="thumbnail" />;
 }

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/Slider/SliderIntervalDots.tsx

@@ -4,6 +4,12 @@ export type IntervalDotProps = Pick<SliderProps<SliderValue>, 'max' | 'min' | 'v
     step: number;
 };
 
+/**
+ * SliderIntervalDots component displays interval dots along a slider track.
+ *
+ * @name SliderIntervalDots
+ * @parent Slider
+ */
 export function SliderIntervalDots({ step, max, min, value }: IntervalDotProps) {
     if (step <= 0) return null;
 

package/src/components/Snackbar/Manager.tsx

@@ -0,0 +1,63 @@
+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,27 +65,45 @@ 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
- *
  * @phase UXReview
  */
 export function Snackbar({

package/src/components/Snackbar/SnackbarExample.tsx

@@ -1,3 +1,5 @@
+import { IconName } from '@bspk/icons';
+import { clearSnackbar, sendSnackbar } from './Manager';
 import { Snackbar, SnackbarProps } from './Snackbar';
 import { Button } from '-/components/Button';
 import { ComponentExample } from '-/utils/demo';
@@ -7,12 +9,32 @@ export const SnackbarExample: ComponentExample<SnackbarProps> = {
     defaultState: {},
     disableProps: [],
     presets: [],
-    render: ({ props, setState }) => (
-        <>
-            <Snackbar {...props} onClose={() => setState({ open: false })} />
-            <Button label="open snackbar" onClick={() => setState({ open: true })} size="medium" title="Snackbar" />
-        </>
-    ),
+    render: ({ props, setState }) => {
+        return (
+            <>
+                <Snackbar {...props} onClose={() => setState({ open: false })} />
+                <Button
+                    label="Launch Inline Snackbar"
+                    onClick={() => setState({ open: true })}
+                    size="medium"
+                    title="Snackbar"
+                />
+                <br />
+                <Button
+                    label="Launch Managed Snackbar"
+                    onClick={() =>
+                        sendSnackbar({
+                            ...props,
+                            text: `Managed: ${props.text}`,
+                            icon: 'icon:icon-name' in props ? (props['icon:icon-name'] as IconName) : undefined,
+                        })
+                    }
+                />
+                <br />
+                <Button label="Clear Managed Snackbar" onClick={() => clearSnackbar()} />
+            </>
+        );
+    },
     sections: [],
     variants: false,
 };

package/src/components/Snackbar/index.tsx

@@ -1 +1,2 @@
 export * from './Snackbar';
+export * from './Manager';

package/src/components/StylesProviderDemo/StylesProviderDemo.tsx

@@ -21,9 +21,7 @@ export type StylesProviderDemoProps = {
  * @example
  *     import { StylesProviderDemo } from '@bspk/ui/StylesProviderDemo';
  *
- *     function Example() {
- *         return <StylesProviderDemo brand="anywhere" />;
- *     }
+ *     <StylesProviderDemo brand="anywhere" />;
  *
  * @name StylesProviderDemo
  * @phase Utility