@bspk/ui 1.3.8 → 1.3.9

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
  *

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

package/src/components/Switch/Switch.tsx

@@ -29,7 +29,7 @@ export type SwitchProps = CommonProps<'aria-label' | 'disabled' | 'name'> & {
  *     import { useState } from 'react';
  *     import { Switch } from '@bspk/ui/Switch';
  *
- *     function Example() {
+ *     () => {
  *         const [isChecked, setIsChecked] = useState<boolean>(false);
  *
  *         return (
@@ -40,7 +40,7 @@ export type SwitchProps = CommonProps<'aria-label' | 'disabled' | 'name'> & {
  *                 checked={isChecked}
  *             />
  *         );
- *     }
+ *     };
  *
  * @element
  *

package/src/components/TabGroup/TabGroup.tsx

@@ -21,7 +21,7 @@ export type TabGroupProps = Omit<TabListProps<TabOption>, 'iconsOnly'> & {
  *     import { useState } from 'react';
  *     import { TabGroup } from '@bspk/ui/TabGroup';
  *
- *     function Example() {
+ *     () => {
  *         const [selectedTab, setSelectedTab] = useState<string>();
  *
  *         return (
@@ -35,7 +35,7 @@ export type TabGroupProps = Omit<TabListProps<TabOption>, 'iconsOnly'> & {
  *                 value={selectedTab}
  *             />
  *         );
- *     }
+ *     };
  *
  * @name TabGroup
  * @phase UXReview

package/src/components/TabGroup/TabGroupExample.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 { TabGroupProps } from '.';
 import { ComponentExample, Preset } from '-/utils/demo';
 
@@ -34,17 +28,17 @@ const PRESET_OPTIONS: TabGroupProps['options'] = [
 
 const OPTION_ICONS = [
     {
-        icon: <SvgDiamond />,
-        iconSelected: <SvgDiamondFill />,
+        icon: 'Diamond',
+        iconSelected: 'DiamondFill',
     },
 
     {
-        icon: <SvgCircle />,
+        icon: 'Circle',
         iconSelected: undefined,
     },
     {
-        icon: <SvgSquare />,
-        iconSelected: <SvgSquareFill />,
+        icon: 'Square',
+        iconSelected: 'SquareFill',
     },
 ];
 

package/src/components/TabGroup/tab-group.scss

@@ -1,5 +1,6 @@
 ul[data-bspk='tab-group'] {
     border-bottom: none;
+    max-width: 100%;
 
     li {
         border: 0;

package/src/components/TabList/TabList.tsx

@@ -127,7 +127,7 @@ export type TabListProps<O extends TabOption = TabOption> = {
  *     import { useState } from 'react';
  *     import { TabList } from '@bspk/ui/TabList';
  *
- *     function Example() {
+ *     () => {
  *         const [selectedTab, setSelectedTab] = useState<string>();
  *
  *         return (
@@ -141,7 +141,7 @@ export type TabListProps<O extends TabOption = TabOption> = {
  *                 value={selectedTab}
  *             />
  *         );
- *     }
+ *     };
  *
  * @name TabList
  * @phase Utility

package/src/components/TabList/tab-list.scss

@@ -4,7 +4,6 @@ ul[data-bspk-utility='tab-list'] {
     display: flex;
     flex-direction: row;
     list-style: none;
-    width: 100%;
     height: var(--height);
     font: var(--font);
 

package/src/components/Table/Table.tsx

@@ -72,22 +72,59 @@ export type TableProps<R extends TableRow> = {
  * @example
  *     import { Table } from '@bspk/ui/Table';
  *
- *     function Example() {
- *         return (
- *             <Table
- *                 columns={[
- *                     { key: 'state', label: 'State', width: '100px' },
- *                     { key: 'capital', label: 'Capital', width: '1fr' },
- *                 ]}
- *                 data={[
- *                     { state: 'New Jersey', capital: 'Trenton' },
- *                     { state: 'New York', capital: 'Albany' },
- *                     { state: 'California', capital: 'Sacramento' },
- *                 ]}
- *                 title="State Capitals"
- *             />
- *         );
- *     }
+ *     <Table
+ *         columns={[
+ *             { key: 'state', label: 'State', width: '160px' },
+ *             { key: 'capital', label: 'Capital', width: '140px' },
+ *             { key: 'population', label: 'Population', width: '140px' },
+ *             { key: 'nickname', label: 'Nickname', width: '1fr' },
+ *         ]}
+ *         data={[
+ *             {
+ *                 id: 'ca',
+ *                 state: 'California',
+ *                 capital: 'Sacramento',
+ *                 population: '39,512,223',
+ *                 nickname: 'The Golden State',
+ *             },
+ *             {
+ *                 id: 'ny',
+ *                 state: 'New York',
+ *                 capital: 'Albany',
+ *                 population: '19,299,981',
+ *                 nickname: 'The Empire State',
+ *             },
+ *             {
+ *                 id: 'nj',
+ *                 state: 'New Jersey',
+ *                 capital: 'Trenton',
+ *                 population: '8,882,190',
+ *                 nickname: 'The Garden State',
+ *             },
+ *             {
+ *                 id: 'tx',
+ *                 state: 'Texas',
+ *                 capital: 'Austin',
+ *                 population: '29,183,290',
+ *                 nickname: 'The Lone Star State',
+ *             },
+ *             {
+ *                 id: 'hi',
+ *                 state: 'Hawaii',
+ *                 capital: 'Honolulu',
+ *                 population: '1,415,872',
+ *                 nickname: 'The Aloha State',
+ *             },
+ *             {
+ *                 id: 'ak',
+ *                 state: 'Alaska',
+ *                 capital: 'Juneau',
+ *                 population: '731,545',
+ *                 nickname: 'The Last Frontier',
+ *             },
+ *         ]}
+ *         title="U.S. States — Capitals & Quick Facts"
+ *     />;
  *
  * @name Table
  * @phase UXReview

package/src/components/Table/table.scss

@@ -46,7 +46,6 @@
         grid-template-columns: var(--template-columns);
         border-collapse: collapse;
         min-width: 100%;
-        user-select: none;
 
         tr,
         tbody,

package/src/components/Tag/Tag.tsx

@@ -35,9 +35,7 @@ export type TagProps = {
  * @example
  *     import { Tag } from '@bspk/ui/Tag';
  *
- *     function Example() {
- *         return <Tag label="Example Tag" variant="flat" color="primary" />;
- *     }
+ *     <Tag label="Example Tag" variant="flat" color="primary" />;
  *
  * @name Tag
  * @phase UXReview

package/src/components/Textarea/Textarea.tsx

@@ -49,22 +49,22 @@ export type TextareaProps = CommonProps<'size'> &
  *     import { useState } from 'react';
  *     import { Textarea } from '@bspk/ui/Textarea';
  *
- *     function ExampleWithField() {
+ *     () => {
  *         const [value, setValue] = useState('');
  *         return (
- *             <Field>
- *                 <FieldLabel>Example Textarea</FieldLabel>
- *                 <Textarea name="example-name" onChange={setValue} value={value} />
- *                 <FieldDescription>This is an example textarea field.</FieldDescription>
- *             </Field>
+ *             <>
+ *                 // standalone textarea example
+ *                 <Textarea aria-label="Enter text" name="example-name" onChange={setValue} value={value} />
+ *                 <br />
+ *                 // textarea used within a field
+ *                 <Field>
+ *                     <FieldLabel>Example Textarea</FieldLabel>
+ *                     <Textarea name="example-name" onChange={setValue} value={value} />
+ *                     <FieldDescription>This is an example textarea field.</FieldDescription>
+ *                 </Field>
+ *             </>
  *         );
- *     }
- *
- *     function ExampleStandalone() {
- *         const [value, setValue] = useState('');
- *
- *         return <Textarea aria-label="Enter text" name="example-name" onChange={setValue} value={value} />;
- *     }
+ *     };
  *
  * @element
  *

package/src/components/TimePicker/TimePicker.tsx

@@ -33,23 +33,23 @@ export type TimePickerProps = FieldControlProps & Pick<InputProps, 'size'>;
  * @example
  *     import { TimePicker } from '@bspk/ui/TimePicker';
  *
- *     function ExampleStandalone() {
- *         const [value, onChange] = React.useState('');
- *
- *         return <TimePicker aria-label="Time" name="time" value={value} onChange={onChange} />;
- *     }
- *
- *     function ExampleWithField() {
- *         const [value, onChange] = React.useState('');
+ *     () => {
+ *         const [value, onChange] = useState('');
  *
  *         return (
- *             <Field>
- *                 <FieldLabel>Time</FieldLabel>
- *                 <TimePicker value={value} onChange={onChange} />
- *                 <FieldDescription>The time picker allows you to select a time.</FieldDescription>
- *             </Field>
+ *             <>
+ *                 // standalone time picker example
+ *                 <TimePicker aria-label="Time" name="time" value={value} onChange={onChange} />
+ *                 <br />
+ *                 // time picker used within a field
+ *                 <Field>
+ *                     <FieldLabel>Time</FieldLabel>
+ *                     <TimePicker value={value} onChange={onChange} />
+ *                     <FieldDescription>The time picker allows you to select a time.</FieldDescription>
+ *                 </Field>
+ *             </>
  *         );
- *     }
+ *     };
  *
  * @name TimePicker
  * @phase UXReview

package/src/components/ToggleOption/ToggleOption.tsx

@@ -38,6 +38,7 @@ export function ToggleOption({ label, description, children, disabled, ...props
             as="label"
             label={label}
             leading={children}
+            owner="toggle-option"
             subText={description}
             width="hug"
         />

package/src/components/ToggleOption/toggle-option.scss

@@ -1,64 +1,5 @@
-[data-bspk='toggle-option'] {
-    display: grid;
-    width: 100%;
-    grid-template-columns: auto 1fr;
-    grid-column-gap: var(--spacing-sizing-02);
-    user-select: none;
-    background: unset;
-    border: unset;
-    cursor: pointer;
-    min-height: var(--spacing-sizing-08);
-    max-width: 100%;
-    padding: var(--spacing-sizing-01);
-
-    &:has([data-description]) {
-        align-items: unset;
-    }
-
-    // this media query targets touch devices
-    @media (any-pointer: coarse) {
-        min-height: var(--spacing-sizing-12);
-    }
-
-    [data-control],
-    [data-label],
-    [data-description] {
-        display: flex;
-        flex-direction: row;
-        align-items: center;
-        justify-content: start;
-    }
-
-    [data-label] {
-        color: var(--foreground-neutral-on-surface);
-        font: var(--labels-base);
-    }
-
-    [data-description] {
-        grid-column-start: 2;
-        font: var(--body-small);
-        color: var(--foreground-neutral-on-surface-variant-01);
-    }
-
-    &:not([aria-disabled]) {
-        [data-pseudo='focus'] &,
-        &:focus-visible,
-        &:has(*:focus-visible) {
-            outline: var(--stroke-neutral-focus) 2px solid;
-        }
-    }
-
-    &[aria-disabled] {
-        cursor: not-allowed;
-
-        [data-label] {
-            color: var(--foreground-neutral-disabled-on-surface);
-        }
-
-        [data-description] {
-            color: var(--foreground-neutral-disabled-on-surface);
-        }
-    }
+[data-bspk-owner='toggle-option'] {
+    align-items: start;
 }
 
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */