@bspk/ui 1.3.10 → 1.3.16

package/src/components/PageHeader/PageHeader.tsx

@@ -0,0 +1,78 @@
+import { Avatar, AvatarProps } from '-/components/Avatar';
+import { Breadcrumb, BreadcrumbProps } from '-/components/Breadcrumb';
+import './page-header.scss';
+
+export type PageHeaderProps = {
+    /**
+     * The actions slot content.
+     *
+     * Appears in the top right of the header next to the title.
+     */
+    actions?: React.ReactNode;
+    /**
+     * Breadcrumb properties.
+     *
+     * If provided, a breadcrumb will be rendered above the title.
+     */
+    breadcrumb?: BreadcrumbProps;
+    /**
+     * The avatar slot content.
+     *
+     * Appears to the left of the title.
+     */
+    avatar?: AvatarProps;
+    /**
+     * The subheader slot content.
+     *
+     * Appears below the header.
+     */
+    subHeader?: React.ReactNode;
+    /**
+     * The page title content.
+     *
+     * Appears as the main title of the page.
+     */
+    title: string;
+};
+
+/**
+ * A standard page header component.
+ *
+ * @example
+ *     import { PageHeader } from '@bspk/ui/PageHeader';
+ *
+ *     <PageHeader
+ *         actions={<Slot height={32} label="Page actions slot" width={372} />}
+ *         subHeader={
+ *             <>
+ *                 <Slot height="var(--spacing-sizing-06)" label="Slot component" width={200} />
+ *                 <Slot height="var(--spacing-sizing-06)" label="Slot component 2" width={200} />
+ *             </>
+ *         }
+ *         title="Page Title"
+ *     />;
+ *
+ * @name PageHeader
+ * @phase Dev
+ */
+export function PageHeader({ actions, breadcrumb, avatar, subHeader, title }: PageHeaderProps) {
+    return (
+        <span data-bspk="page-header">
+            {breadcrumb && (
+                <div data-breadcrumb>
+                    <Breadcrumb {...breadcrumb} />
+                </div>
+            )}
+            <div data-has-avatar={!!avatar} data-header>
+                <div data-title>
+                    {avatar && <Avatar {...avatar} size="xx-large" />}
+                    <h1>{title}</h1>
+                </div>
+                {actions && <div data-page-actions>{actions}</div>}
+            </div>
+            {subHeader && <div data-subheader>{subHeader}</div>}
+        </span>
+    );
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/PageHeader/PageHeaderExample.tsx

@@ -0,0 +1,58 @@
+import { PageHeaderProps } from '.';
+import { ExamplePlaceholder } from '-/components/ExamplePlaceholder';
+import { ComponentExample, Preset } from '-/utils/demo';
+
+export const presets: Preset<PageHeaderProps>[] = [
+    {
+        label: 'Title Only',
+        propState: {
+            title: 'Page Title',
+        },
+        designPattern: true,
+    },
+    {
+        label: 'With Actions',
+        propState: {
+            title: 'Page Title',
+            actions: <ExamplePlaceholder height={32} label="Page actions slot" width={372} />,
+        },
+        designPattern: true,
+    },
+    {
+        label: 'With Breadcrumb',
+        propState: {
+            title: 'Page Title',
+            breadcrumb: {
+                items: [
+                    { label: 'Home', href: '#/home' },
+                    { label: 'Section', href: '#/section' },
+                    { label: 'Page Title', href: '#/page' },
+                ],
+            },
+            actions: <ExamplePlaceholder height={32} label="Page actions slot" width={372} />,
+        },
+        designPattern: true,
+    },
+    {
+        label: 'Profile',
+        propState: {
+            title: 'Charlie Brown',
+            avatar: { image: '/avatar-01.png', name: 'CB' },
+            actions: <ExamplePlaceholder height={32} label="Page actions slot" width={372} />,
+        },
+        designPattern: true,
+    },
+];
+
+export const PageHeaderExample: ComponentExample<PageHeaderProps> = {
+    defaultState: {
+        title: 'Page Title',
+        actions: <ExamplePlaceholder height={32} label="Page actions slot" width={372} />,
+    },
+    disableProps: [],
+    presets,
+    render: ({ props, Component }) => <Component {...props} />,
+    variants: false,
+    fullPage: true,
+    hideDemo: true,
+};

package/src/components/PageHeader/index.tsx

@@ -0,0 +1 @@
+export * from './PageHeader';

package/src/components/PageHeader/page-header.scss

@@ -0,0 +1,41 @@
+[data-bspk='page-header'] {
+    display: flex;
+    flex-direction: column;
+    width: 100%;
+    background-color: var(--background-base);
+
+    [data-breadcrumb] {
+        padding: var(--spacing-sizing-05) var(--spacing-sizing-05) 0;
+    }
+
+    [data-header] {
+        padding: var(--spacing-sizing-05);
+        display: flex;
+        justify-content: space-between;
+        align-items: end;
+
+        [data-title] {
+            display: flex;
+            align-items: center;
+            gap: var(--spacing-sizing-03);
+
+            h1 {
+                margin: 0;
+                font: var(--heading-h3);
+            }
+        }
+
+        &[data-has-avatar] {
+            align-items: center;
+        }
+    }
+
+    [data-subheader] {
+        padding: 0 var(--spacing-sizing-05);
+        display: flex;
+        align-items: end;
+        justify-content: space-between;
+    }
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Pagination/Pagination.tsx

@@ -4,6 +4,7 @@ import { AriaAttributes, useEffect, useState } from 'react';
 import { PageList } from './PageList';
 import { Button } from '-/components/Button';
 import { InputElement } from '-/components/Input';
+import { sendAriaLiveMessage } from '-/utils/sendAriaLiveMessage';
 
 // After this point the manual input renders. With equal or fewer pages the individual page buttons render instead.
 const INPUT_TYPE_THRESHOLD = 7;
@@ -42,9 +43,19 @@ export type PaginationProps = {
  *     }
  *
  * @name Pagination
- * @phase UXReview
+ * @phase Stable
  */
-export function Pagination({ numPages, value, onChange, ...ariaProps }: AriaAttributes & PaginationProps) {
+export function Pagination({
+    numPages,
+    value,
+    onChange: onChangeProp,
+    ...ariaProps
+}: AriaAttributes & PaginationProps) {
+    const onChange = (newPage: number) => {
+        onChangeProp(newPage);
+        sendAriaLiveMessage(`Page ${newPage} of ${numPages}`);
+    };
+
     const nextPage = () => {
         if (value < numPages) onChange(value + 1);
     };
@@ -102,7 +113,7 @@ export function Pagination({ numPages, value, onChange, ...ariaProps }: AriaAttr
                         type="number"
                         value={inputValue}
                     />
-                    of {numPages}
+                    <span>of {numPages}</span>
                 </form>
             ) : (
                 <PageList numPages={numPages} onChange={onChange} value={value} />

package/src/components/Pagination/pagination.scss

@@ -8,13 +8,20 @@
 
     [data-input-form] {
         display: contents;
-    }
 
-    [data-bspk='input'] {
-        max-width: var(--spacing-sizing-12);
+        [data-bspk='input'] {
+            max-width: var(--spacing-sizing-12);
+            margin-right: var(--spacing-sizing-01);
+
+            input {
+                text-align: center;
+            }
+        }
 
-        input {
-            text-align: center;
+        span {
+            display: block;
+            white-space: nowrap;
+            font: var(--body-small);
         }
     }
 

package/src/components/Password/Password.tsx

@@ -14,34 +14,29 @@ export type PasswordProps = FieldControlProps & Pick<InputProps, 'containerRef'
  *
  * @example
  *     import { Password } from '@bspk/ui/Password';
- *     import { useState } from 'react';
+ *     import { Field, FieldLabel, FieldDescription } from '-/components/Field';
  *
  *     () => {
- *         const [value, setValue] = useState('');
+ *         const [value, setValue] = useState<string | undefined>('');
  *
  *         return (
- *             <>
- *                 // standalone password example
- *                 <Password
- *                     aria-label="Enter password"
- *                     value={value}
- *                     onChange={setValue}
- *                     aria-label="password"
- *                     name="password"
- *                 />
- *                 <br />
- *                 // password used within a field
+ *             <div style={{ width: 320 }}>
  *                 <Field>
  *                     <FieldLabel>Password</FieldLabel>
- *                     <Password value={value} onChange={setValue} aria-label="password" name="password" />
+ *                     <Password
+ *                         aria-label="password"
+ *                         name="password"
+ *                         onChange={(next) => setValue(next)}
+ *                         value={value}
+ *                     />
  *                     <FieldDescription>The password field allows you to enter a secure password.</FieldDescription>
  *                 </Field>
- *             </>
+ *             </div>
  *         );
  *     };
  *
  * @name Password
- * @phase UXReview
+ * @phase Stable
  */
 export function Password({
     inputProps,

package/src/components/Password/PasswordExample.tsx

@@ -1,8 +1,25 @@
-import { PasswordProps } from '.';
+import { useState } from 'react';
+import { Password, PasswordProps } from '.';
+import { Field, FieldLabel, FieldDescription } from '-/components/Field';
 import { ComponentExample } from '-/utils/demo';
 
 export const PasswordExample: ComponentExample<PasswordProps> = {
     defaultState: {
         'aria-label': 'password aria-label',
     },
+    containerStyle: { width: 320, padding: 0 },
+};
+
+export const Usage = () => {
+    const [value, setValue] = useState<string | undefined>('');
+
+    return (
+        <div>
+            <Field>
+                <FieldLabel>Password</FieldLabel>
+                <Password aria-label="password" name="password" onChange={(next) => setValue(next)} value={value} />
+                <FieldDescription>The password field allows you to enter a secure password.</FieldDescription>
+            </Field>
+        </div>
+    );
 };

package/src/components/PasswordField/PasswordField.tsx

@@ -9,7 +9,7 @@ export type PasswordFieldProps = FormFieldControlProps<PasswordProps>;
  * This component takes properties from the FormField and Password components.
  *
  * @name PasswordField
- * @phase UXReview
+ * @phase Stable
  *
  * @generated
  */

package/src/components/Popover/Popover.tsx

@@ -73,7 +73,7 @@ export type PopoverProps = CommonProps<'disabled'> &
  *     </Popover>;
  *
  * @name Popover
- * @phase UXReview
+ * @phase Stable
  */
 export function Popover({
     placement = 'top',

package/src/components/Popover/PopoverExample.tsx

@@ -4,7 +4,6 @@ import { Txt } from '-/components/Txt';
 import { ComponentExampleFn } from '-/utils/demo';
 
 export const PopoverExample: ComponentExampleFn<PopoverProps> = ({ action }) => ({
-    containerStyle: { width: '100%' },
     render: ({ props, Component }) => {
         return (
             <>

package/src/components/ProgressBar/ProgressBar.tsx

@@ -56,7 +56,7 @@ export type ProgressBarProps = {
  *     <ProgressBar label="Example label" completion={50} />;
  *
  * @name ProgressBar
- * @phase UXReview
+ * @phase Stable
  */
 export function ProgressBar({
     size = 'large',

package/src/components/ProgressCircle/ProgressCircle.tsx

@@ -30,7 +30,7 @@ export type ProgressCircleProps = {
  *     <ProgressCircle label="Example label" />;
  *
  * @name ProgressCircle
- * @phase UXReview
+ * @phase Stable
  */
 function ProgressCircle({ label, labelPosition, size = 'medium' }: ProgressCircleProps) {
     let variant: TxtVariant = 'labels-base';

package/src/components/ProgressionStepper/ProgressionStepper.tsx

@@ -62,7 +62,7 @@ export type ProgressionStepperProps = {
  *     <ProgressionStepper steps={[{ name: 'Step 1' }, { name: 'Step 2' }, { name: 'Step 3' }]} />;
  *
  * @name ProgressionStepper
- * @phase UXReview
+ * @phase Stable
  */
 export function ProgressionStepper({
     steps = [],

package/src/components/ProgressionStepper/ProgressionStepperExample.tsx

@@ -66,6 +66,5 @@ export const presets: Preset<ProgressionStepperProps>[] = [
 ];
 
 export const ProgressionStepperExample: ComponentExample<ProgressionStepperProps> = {
-    containerStyle: { width: '100%' },
     presets,
 };

package/src/components/ProgressionStepperBar/ProgressionStepperBar.tsx

@@ -35,7 +35,7 @@ export type ProgressionStepperBarProps = {
  * Component description coming soon.
  *
  * @name ProgressionStepperBar
- * @phase UXReview
+ * @phase Stable
  */
 export function ProgressionStepperBar({
     stepCount,

package/src/components/RadioGroup/RadioGroup.tsx

@@ -62,7 +62,7 @@ export type RadioGroupProps = Omit<FieldControlProps, 'readOnly'> & {
  *     };
  *
  * @name RadioGroup
- * @phase UXReview
+ * @phase Stable
  */
 export function RadioGroup({
     onChange,

package/src/components/RadioGroupField/RadioGroupField.tsx

@@ -10,7 +10,7 @@ export type RadioGroupFieldProps = FormFieldControlProps<RadioGroupProps>;
  * This component takes properties from the FormField and RadioGroup components.
  *
  * @name RadioGroupField
- * @phase UXReview
+ * @phase Stable
  *
  * @generated
  */

package/src/components/Rating/Rating.tsx

@@ -1,11 +1,13 @@
 import './rating.scss';
 import { SvgStarFill } from '@bspk/icons/StarFill';
+import { useControlledState } from '-/hooks/useControlledState';
 
 export type RatingSize = 'large' | 'medium' | 'small';
 export type RatingProps = {
     /**
      * The value of the rating between 0 and 5.
      *
+     * @default 0
      * @minimum 0
      * @maximum 5
      */
@@ -41,10 +43,12 @@ const iconWidths: Record<RatingSize, number> = {
  *     <Rating value={4.5} size="large" />;
  *
  * @name Rating
- * @phase UXReview
+ * @phase Stable
  */
-export function Rating({ size = 'medium', value, onChange }: RatingProps) {
-    if (!onChange)
+export function Rating({ size = 'medium', value: valueProp, onChange: onChangeProp }: RatingProps) {
+    const [value, onChange] = useControlledState(valueProp, onChangeProp);
+
+    if (!onChangeProp)
         return (
             <div
                 aria-label={value ? `${value} out of ${MAX_STARS} stars` : 'Rating'}

package/src/components/SearchBar/SearchBar.tsx

@@ -9,11 +9,11 @@ import { useArrowNavigation } from '-/hooks/useArrowNavigation';
 import { useFloating } from '-/hooks/useFloating';
 import { useId } from '-/hooks/useId';
 import { useOutsideClick } from '-/hooks/useOutsideClick';
-import { useUIContext } from '-/hooks/useUIContext';
 import { FieldControlProps } from '-/types/common';
 import { getElementById } from '-/utils/dom';
 import { handleKeyDown } from '-/utils/handleKeyDown';
 import { scrollListItemsStyle, ScrollListItemsStyleProps } from '-/utils/scrollListItemsStyle';
+import { sendAriaLiveMessage } from '-/utils/sendAriaLiveMessage';
 import { useIds } from '-/utils/useIds';
 
 /**
@@ -99,7 +99,7 @@ export type SearchBarProps<O extends SearchBarOption = SearchBarOption> = Omit<
  *     };
  *
  * @name SearchBar
- * @phase UXReview
+ * @phase Stable
  */
 export function SearchBar<O extends SearchBarOption>({
     items: itemsProp,
@@ -129,11 +129,9 @@ export function SearchBar<O extends SearchBarOption>({
         return items.filter((item) => !valueStr || item.label.toLowerCase().includes(valueStr));
     }, [items, value]);
 
-    const { sendAriaLiveMessage } = useUIContext();
-
     useEffect(() => {
         if (!items.length) sendAriaLiveMessage('No results found', 'assertive');
-    }, [items.length, sendAriaLiveMessage, value]);
+    }, [items.length, value]);
 
     const { activeElementId, setActiveElementId, arrowKeyCallbacks } = useArrowNavigation({
         ids: filteredItems.map((i) => i.id),

package/src/components/SegmentedControl/SegmentedControl.tsx

@@ -29,7 +29,7 @@ export type SegmentedControlProps = TabListProps<SegmentedControlOption>;
  *     };
  *
  * @name SegmentedControl
- * @phase UXReview
+ * @phase Stable
  */
 export function SegmentedControl({
     onChange,

package/src/components/Select/Select.tsx

@@ -70,39 +70,26 @@ export type SelectProps = CommonProps<'size'> &
  *
  *     () => {
  *         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' },
+ *             { id: '1', label: 'Option 1', value: '1' },
+ *             { id: '2', label: 'Option 2', value: '2' },
+ *             { id: '3', label: 'Option 3', value: '3' },
+ *             { id: '4', label: 'Option 4', value: '4' },
+ *             { id: '5', label: 'Option 5', value: '5' },
+ *             { id: '6', label: 'Option 6', value: '6' },
  *         ];
  *
- *         const [selected, setSelected] = useState<string[]>([]);
+ *         const [selected, setSelected] = useState<string | undefined>(undefined);
  *
  *         return (
- *             <>
- *                 // standalone select example
- *                 <Select
- *                     aria-label="Select an option"
- *                     scrollLimit={5}
- *                     name="example-select"
- *                     onChange={setSelected}
- *                     options={OPTIONS}
- *                     placeholder="Select an option"
- *                     size="medium"
- *                     value={selected}
- *                 />
- *                 <br />
- *                 // select used within a field
+ *             <div style={{ width: 320 }}>
  *                 <Field>
  *                     <FieldLabel>Select an option</FieldLabel>
  *                     <Select
- *                         scrollLimit={5}
  *                         name="example-select"
  *                         onChange={setSelected}
  *                         options={OPTIONS}
  *                         placeholder="Select an option"
+ *                         scrollLimit={5}
  *                         size="medium"
  *                         value={selected}
  *                     />
@@ -110,12 +97,12 @@ export type SelectProps = CommonProps<'size'> &
  *                         The select allows you to choose one option from a list of options.
  *                     </FieldDescription>
  *                 </Field>
- *             </>
+ *             </div>
  *         );
  *     };
  *
  * @name Select
- * @phase UXReview
+ * @phase Stable
  */
 export function Select({
     options: optionsProp = [],

package/src/components/Select/SelectExample.tsx

@@ -1,5 +1,8 @@
-import { SelectProps } from '.';
+/* eslint-disable react/no-multi-comp */
+import { useState } from 'react';
+import { Select, SelectProps } from '.';
 import { Avatar } from '-/components/Avatar';
+import { Field, FieldDescription, FieldLabel } from '-/components/Field';
 import { Tag } from '-/components/Tag';
 import { Txt } from '-/components/Txt';
 import { ComponentExample, Preset } from '-/utils/demo';
@@ -160,4 +163,36 @@ export const SelectExample: ComponentExample<SelectProps> = {
     },
     render: ({ props, Component, preset }) => <Component key={preset?.label} {...props} />,
     presets,
+    containerStyle: { width: 320, padding: 0 },
+};
+
+export const Usage = () => {
+    const OPTIONS = [
+        { id: '1', label: 'Option 1', value: '1' },
+        { id: '2', label: 'Option 2', value: '2' },
+        { id: '3', label: 'Option 3', value: '3' },
+        { id: '4', label: 'Option 4', value: '4' },
+        { id: '5', label: 'Option 5', value: '5' },
+        { id: '6', label: 'Option 6', value: '6' },
+    ];
+
+    const [selected, setSelected] = useState<string | undefined>(undefined);
+
+    return (
+        <div style={{ width: 320 }}>
+            <Field>
+                <FieldLabel>Select an option</FieldLabel>
+                <Select
+                    name="example-select"
+                    onChange={setSelected}
+                    options={OPTIONS}
+                    placeholder="Select an option"
+                    scrollLimit={5}
+                    size="medium"
+                    value={selected}
+                />
+                <FieldDescription>The select allows you to choose one option from a list of options.</FieldDescription>
+            </Field>
+        </div>
+    );
 };

package/src/components/SelectField/SelectField.tsx

@@ -9,7 +9,7 @@ export type SelectFieldProps = FormFieldControlProps<SelectProps>;
  * This component takes properties from the FormField and Select components.
  *
  * @name SelectField
- * @phase UXReview
+ * @phase Stable
  *
  * @generated
  */

package/src/components/Skeleton/Skeleton.tsx

@@ -63,7 +63,7 @@ export type SkeletonProps = {
  * @exampleDescription This example shows a skeleton loading state for an image but can be used for any element.
  *
  * @name Skeleton
- * @phase UXReview
+ * @phase Stable
  */
 export function Skeleton({ width = 100, height = 100, variant = 'rectangular', children = null }: SkeletonProps) {
     return children !== null && children !== undefined && children !== false ? (

package/src/components/SkeletonText/SkeletonText.tsx

@@ -42,7 +42,7 @@ export type SkeletonTextProps = {
  * @exampleDescription This example shows a skeleton loading state for some text but can be used for any element.
  *
  * @name SkeletonText
- * @phase UXReview
+ * @phase Stable
  */
 export function SkeletonText({ lines = 3, variant = 'body-base', children = null }: SkeletonTextProps) {
     return children !== null && children !== undefined && children !== false ? (