@bspk/ui 1.1.31 → 1.1.33

package/src/components/Divider/Divider.tsx

@@ -0,0 +1,90 @@
+import { ElementProps } from '-';
+import { cssWithVars } from '-/utils/cwv';
+import './divider.scss';
+
+export type DividerProps = {
+    /**
+     * The orientation of the divider.
+     *
+     * @default horizontal
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * The thickness of the divider.
+     *
+     * @default light
+     */
+    thickness?: 'heavy' | 'light';
+    /**
+     * If the divider padding is shown.
+     *
+     * @default true
+     */
+    padding?: boolean;
+    /**
+     * The inset (margin) of the divider. The value is a number between 0 and 12, which corresponds to the spacing
+     * sizing variables defined in the theme. The inset is applied to the left and right sides of the divider when the
+     * orientation is horizontal, and to the top and bottom when the orientation is vertical.
+     *
+     * @default 0
+     */
+    inset?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+};
+
+const insetToVariable = (insetProp: number | string) => {
+    const inset = Number(insetProp);
+    if (inset === undefined || inset === null || inset < 1 || inset > 12) return '0px';
+    return `var(--spacing-sizing-${inset.toString().padStart(2, '0')})`;
+};
+
+/**
+ * Horizontal thin lines that separates grouped content in a list or other containers with an optional section/group
+ * label.
+ *
+ * Vertical thin lines that separates grouped content or other visual elements within a container.
+ *
+ * @example
+ *     import { Divider } from '@bspk/ui/Divider';
+ *
+ *     function Example() {
+ *         return (
+ *             <div>
+ *                 <p>Content above the divider</p>
+ *                 <Divider orientation="horizontal" />
+ *                 <p>Content below the divider</p>
+ *             </div>
+ *         );
+ *     }
+ *
+ * @name Divider
+ * @phase DesignReview
+ */
+function Divider({
+    padding = true,
+    orientation = 'horizontal',
+    thickness = 'light',
+    inset = 0,
+    ...props
+}: ElementProps<DividerProps, 'div'>) {
+    return (
+        <div
+            {...props}
+            aria-orientation={orientation}
+            data-bspk="divider"
+            data-hide-padding={!padding || undefined}
+            data-orientation={orientation}
+            data-thickness={thickness}
+            role="separator"
+            style={cssWithVars({
+                ...props.style,
+                '--inset': insetToVariable(inset),
+            })}
+        />
+    );
+}
+
+Divider.bspkName = 'Divider';
+
+export { Divider };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Divider/DividerExample.tsx

@@ -0,0 +1,26 @@
+import { CSSProperties } from 'react';
+
+import { ExamplePlaceholder } from '-/components/ExamplePlaceholder';
+import { ComponentExample } from '-/utils/demo';
+
+export const DividerExample: ComponentExample = {
+    render: ({ props, Component }) => {
+        const style: CSSProperties =
+            props.orientation === 'vertical' ? { height: 300, width: 100 } : { height: 100, width: '300px' };
+        return (
+            <div
+                style={{
+                    display: 'flex',
+                    flexDirection: props.orientation === 'vertical' ? 'row' : 'column',
+                    alignItems: props.orientation === 'vertical' ? 'center' : 'stretch',
+                    justifyContent: props.orientation === 'vertical' ? 'center' : 'stretch',
+                    maxWidth: props.orientation !== 'vertical' ? '300px' : 'auto',
+                }}
+            >
+                <ExamplePlaceholder direction={props.orientation !== 'vertical' ? 'row' : 'column'} style={style} />
+                <Component {...props} />
+                <ExamplePlaceholder direction={props.orientation !== 'vertical' ? 'row' : 'column'} style={style} />
+            </div>
+        );
+    },
+};

package/src/components/Divider/index.tsx

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

package/src/components/EmptyState/EmptyState.tsx

@@ -0,0 +1,91 @@
+import { ReactNode } from 'react';
+
+import { CallToActionButton } from '-';
+import { Button } from '-/components/Button';
+import { Layout } from '-/components/Layout';
+import { Txt } from '-/components/Txt';
+
+export type EmptyStateProps = {
+    /** The image or icon to display in the empty state. */
+    children?: ReactNode;
+    /**
+     * The header of the empty state.
+     *
+     * @required
+     */
+    header: string;
+    /**
+     * The body of the empty state.
+     *
+     * @type multiline
+     * @required
+     */
+    body: string;
+    /**
+     * The text alignment of the body.
+     *
+     * @default center
+     */
+    bodyAlign?: 'center' | 'left';
+    /**
+     * Optional CallToActionButton properties.
+     *
+     * @type CallToActionButton
+     */
+    callToAction?: CallToActionButton;
+};
+
+/**
+ * A design pattern component that indicates to users that system has no content to display.
+ *
+ * @example
+ *     import { EmptyState } from '@bspk/ui/EmptyState';
+ *
+ *     export function Example() {
+ *         return (
+ *             <EmptyState body="Example body" header="Example header">
+ *                 Example EmptyState
+ *             </EmptyState>
+ *         );
+ *     }
+ *
+ * @name EmptyState
+ * @phase DesignReview
+ */
+function EmptyState({ children, header, body, callToAction, bodyAlign = 'center' }: EmptyStateProps) {
+    return (
+        <Layout
+            align="center"
+            column
+            data-bspk="empty-state"
+            style={{
+                margin: 'var(--spacing-sizing-04)',
+                maxWidth: '500px',
+            }}
+        >
+            {children}
+            <Layout align="center" column gap="4">
+                <Txt as="header" variant="heading-h5">
+                    {header}
+                </Txt>
+                <Txt as="p" style={{ textAlign: bodyAlign }} variant="body-base">
+                    {body}
+                </Txt>
+            </Layout>
+            {callToAction && (
+                <Button
+                    label={callToAction.label}
+                    onClick={callToAction.onClick}
+                    size={callToAction.size || 'medium'}
+                    variant="primary"
+                />
+            )}
+        </Layout>
+    );
+}
+
+EmptyState.bspkName = 'EmptyState';
+
+export { EmptyState };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/EmptyState/EmptyStateExample.tsx

@@ -0,0 +1,37 @@
+import { ExamplePlaceholder } from '-/components/ExamplePlaceholder';
+import { ComponentExampleFn } from '-/utils/demo';
+
+import { EmptyStateProps } from '.';
+
+export const EmptyStateExample: ComponentExampleFn<EmptyStateProps> = ({ action }) => ({
+    containerStyle: { width: '100%' },
+    render: ({ props: { children, ...props }, context, Component }) => (
+        <Component {...props}>
+            {context?.preset?.label === 'With Image' ? (
+                <ExamplePlaceholder
+                    style={{
+                        height: '200px',
+                        width: '60%',
+                        minWidth: '250px',
+                    }}
+                />
+            ) : (
+                children
+            )}
+        </Component>
+    ),
+    presets: [
+        {
+            label: 'With CallToAction',
+            propState: {
+                callToAction: {
+                    label: 'Add payment method',
+                    onClick: () => action('Add payment method clicked!'),
+                },
+            },
+        },
+        {
+            label: 'With Image',
+        },
+    ],
+});

package/src/components/EmptyState/index.tsx

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

package/src/components/ExamplePlaceholder/ExamplePlaceholder.tsx

@@ -0,0 +1,56 @@
+import { useRef } from 'react';
+
+import { ElementProps } from '-';
+import { Txt } from '-/components/Txt';
+
+const dimension = (value: number | string) => (typeof value === 'number' ? `${value}px` : `${value}`);
+
+/**
+ * A utility component that serves as a placeholder for examples.
+ *
+ * @name ExamplePlaceholder
+ * @phase Utility
+ */
+function ExamplePlaceholder({
+    hideSize = false,
+    height = 100,
+    width = '100%',
+    direction = 'row',
+    ...props
+}: ElementProps<
+    {
+        hideSize?: boolean;
+        height?: number | string;
+        width?: number | string;
+        direction?: 'column' | 'row';
+    },
+    'div'
+>) {
+    const ref = useRef<HTMLDivElement | null>(null);
+
+    return (
+        <div
+            {...props}
+            data-example-placeholder
+            ref={ref}
+            style={{
+                ...props.style,
+                width: dimension(width),
+                height: dimension(height),
+                flexDirection: direction,
+            }}
+        >
+            {!hideSize && (
+                <>
+                    <Txt variant="labels-large">{dimension(width)}</Txt>
+                    <Txt>&times;</Txt>
+                    <Txt variant="labels-large">{dimension(height)}</Txt>
+                </>
+            )}
+        </div>
+    );
+}
+
+ExamplePlaceholder.bspkName = 'ExamplePlaceholder';
+
+export { ExamplePlaceholder };

package/src/components/ExamplePlaceholder/index.tsx

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

package/src/components/Fab/Fab.tsx

@@ -0,0 +1,107 @@
+import { ElementType } from 'react';
+
+import { ElementProps } from '-';
+import { ButtonProps } from '-/components/Button';
+import { Tooltip } from '-/components/Tooltip';
+import { isValidIcon } from '-/utils/children';
+import { useErrorLogger } from '-/utils/errors';
+import './fab.scss';
+
+export type FabVariant = 'neutral' | 'primary' | 'secondary';
+
+export type FabProps<As extends ElementType = 'button'> = Pick<
+    ButtonProps<As>,
+    'as' | 'icon' | 'onClick' | 'showLabel' | 'toolTip'
+> &
+    Required<Pick<ButtonProps<As>, 'label'>> & {
+        /**
+         * The size of the button.
+         *
+         * @default small
+         */
+        size?: 'medium' | 'small';
+        /**
+         * The style variant of the button.
+         *
+         * @default primary
+         */
+        variant?: FabVariant;
+        /**
+         * The placement of the button on the container.
+         *
+         * @default bottom-right
+         */
+        placement?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
+        /**
+         * The container to render the button in.
+         *
+         * @default local
+         */
+        container?: 'local' | 'page';
+    };
+
+/**
+ * A button that highlights a primary action that is elevated above the body content of a page; normally fixed to the
+ * bottom right of a screen.
+ *
+ * @example
+ *     import { SvgBolt } from '@bspk/icons/Bolt';
+ *     import { Fab } from '@bspk/ui/Fab';
+ *
+ *     export function Example() {
+ *         return <Fab icon={<SvgBolt />} label="Example label" placement="bottom-right" variant="neutral" />;
+ *     }
+ *
+ * @name Fab
+ * @phase DesignReview
+ */
+function Fab<As extends ElementType = 'button'>({
+    size = 'small',
+    variant = 'primary',
+    showLabel: showLabelProp = true,
+    as,
+    placement = 'bottom-right',
+    container = 'local',
+    label,
+    icon,
+    toolTip,
+    ...otherProps
+}: ElementProps<FabProps<As>, As>) {
+    // ignore showLabel=false if there is no icon
+    const hideLabel = showLabelProp === false && icon;
+
+    const { logError } = useErrorLogger();
+    logError(!!icon && !isValidIcon(icon), 'Button - The icon prop must be a valid icon element.');
+
+    const As: ElementType = as || 'button';
+
+    const button = (
+        <As
+            {...otherProps}
+            aria-label={label}
+            data-bspk="fab"
+            data-container={container}
+            data-placement={placement}
+            data-round={hideLabel || undefined}
+            data-size={size}
+            data-variant={variant}
+        >
+            {!!icon && <span data-fab-icon>{icon}</span>}
+            {!hideLabel && <span data-fab-label>{label}</span>}
+        </As>
+    );
+
+    return toolTip || hideLabel ? (
+        <Tooltip label={toolTip || label} placement="top">
+            {button}
+        </Tooltip>
+    ) : (
+        button
+    );
+}
+
+Fab.bspkName = 'Fab';
+
+export { Fab };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Fab/FabExample.tsx

@@ -0,0 +1,7 @@
+import { ButtonExample } from '-/components/Button/ButtonExample';
+import { ComponentExample } from '-/utils/demo';
+
+export const FabExample: ComponentExample = {
+    containerStyle: { width: '100%' },
+    presets: ButtonExample.presets,
+};

package/src/components/Fab/fab.scss

@@ -0,0 +1,122 @@
+[data-bspk='fab'] {
+    --placement-offset: var(--spacing-sizing-04);
+
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    justify-content: center;
+    gap: var(--spacing-sizing-02);
+    border: none;
+    cursor: pointer;
+    text-decoration: none;
+    z-index: var(--z-index-fab);
+    box-shadow: var(--drop-shadow-float);
+    border-radius: var(--radius-small);
+
+    &[data-container='page'] {
+        position: fixed;
+    }
+
+    &[data-container='local'] {
+        position: absolute;
+    }
+
+    &[data-placement='top-right'] {
+        top: var(--placement-offset);
+        right: var(--placement-offset);
+    }
+
+    &[data-placement='bottom-right'] {
+        bottom: var(--placement-offset);
+        right: var(--placement-offset);
+    }
+
+    &[data-placement='top-left'] {
+        top: var(--placement-offset);
+        left: var(--placement-offset);
+    }
+
+    &[data-placement='bottom-left'] {
+        bottom: var(--placement-offset);
+        left: var(--placement-offset);
+    }
+
+    > [data-fab-icon] {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+    }
+
+    > [data-fab-label] {
+        display: flex;
+        flex-direction: row;
+        align-items: center;
+    }
+
+    &[data-size='small'] {
+        font: var(--labels-base);
+        height: var(--spacing-sizing-10);
+        padding: 0 var(--spacing-sizing-04);
+
+        > [data-fab-icon] {
+            width: var(--spacing-sizing-05);
+        }
+    }
+
+    &[data-size='medium'] {
+        font: var(--labels-large);
+        height: var(--spacing-sizing-14);
+        padding: 0 var(--spacing-sizing-07);
+
+        > [data-fab-icon] {
+            width: var(--spacing-sizing-06);
+        }
+    }
+
+    &[data-variant='primary'] {
+        --variant-background: var(--surface-brand-primary);
+        --variant-foreground: var(--foreground-brand-on-primary);
+    }
+
+    &[data-variant='secondary'] {
+        --variant-background: var(--surface-brand-secondary);
+        --variant-foreground: var(--foreground-brand-on-secondary);
+    }
+
+    &[data-variant='neutral'] {
+        --variant-background: var(--surface-neutral-t1-base);
+        --variant-foreground: var(--foreground-neutral-on-surface-variant-01);
+    }
+
+    background: var(--variant-background);
+    color: var(--variant-foreground);
+
+    --variant-gradient: linear-gradient(var(--variant-background), var(--variant-background));
+
+    [data-pseudo='hover'] > &,
+    &:hover {
+        background:
+            linear-gradient(var(--interactions-brand-hover-opacity), var(--interactions-brand-hover-opacity)),
+            var(--variant-gradient);
+    }
+
+    [data-pseudo='active'] > &,
+    &:active {
+        background:
+            linear-gradient(var(--interactions-brand-press-opacity), var(--interactions-brand-press-opacity)),
+            var(--variant-gradient);
+    }
+
+    [data-pseudo='focus'] > &,
+    &:focus-visible {
+        outline: solid 2px var(--stroke-neutral-focus);
+    }
+
+    &[data-round] {
+        border-radius: var(--radius-circular);
+        aspect-ratio: 1/1;
+        padding: 0;
+    }
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Fab/index.tsx

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

package/src/components/FormField/FormField.tsx

@@ -0,0 +1,131 @@
+import { CommonProps, ElementProps, InvalidPropsLibrary } from '-';
+import { InlineAlert } from '-/components/InlineAlert';
+import { Txt } from '-/components/Txt';
+import './form-field.scss';
+
+export type FieldControlProps = {
+    /**
+     * Marks the element as invalid and displays error message.
+     *
+     * @default false
+     */
+    invalid?: boolean;
+    /** The id of the control description. */
+    'aria-describedby'?: string;
+    /** The id of the error message */
+    'aria-errormessage'?: string;
+};
+
+export type FormFieldProps = CommonProps<'required'> &
+    InvalidPropsLibrary & {
+        /**
+         * The label of the field.
+         *
+         * @required
+         */
+        label: string;
+        /** The id of the control. */
+        controlId: string;
+        /**
+         * The children of the form field. This should be a control such as TextInput, Select, DatePicker, or
+         * TimePicker.
+         *
+         * @type (childProps: FieldControlProps) => JSX.Element
+         * @required
+         */
+        children: (childProps: FieldControlProps) => JSX.Element;
+        /** The helperText of the field. */
+        helperText?: string;
+        /** The trailing element of the label. */
+        labelTrailing?: React.ReactNode;
+    };
+
+/**
+ * Wrapper component for form controls.
+ *
+ * Children may be one of the following: TextInput, Select, DatePicker, or TimePicker.
+ *
+ * @example
+ *     import { TextInput } from '@bspk/ui/TextInput';
+ *     import { FormField } from '@bspk/ui/FormField';
+ *
+ *     export function Example() {
+ *         const [state, setState] = React.useState<string | undefined>(undefined);
+ *         return (
+ *             <FormField controlId="Example controlId" label="Example label">
+ *                 {(fieldProps) => {
+ *                     return (
+ *                         <TextInput
+ *                             aria-label="example aria-label"
+ *                             name="example-text"
+ *                             onChange={(next) => {
+ *                                 setState(next);
+ *                             }}
+ *                             value={state}
+ *                             {...fieldProps}
+ *                         />
+ *                     );
+ *                 }}
+ *             </FormField>
+ *         );
+ *     }
+ *
+ * @name FormField
+ * @phase Backlog
+ */
+function FormField({
+    label,
+    invalid,
+    errorMessage: errorMessageProp,
+    helperText: helperTextProp,
+    children,
+    labelTrailing,
+    controlId,
+    required,
+}: ElementProps<FormFieldProps, 'div'>) {
+    const errorMessage = invalid && errorMessageProp ? errorMessageProp : undefined;
+    const errorMessageId = errorMessage ? `${controlId}-error-message` : undefined;
+    const helperText = !invalid && helperTextProp ? helperTextProp : undefined;
+    const helperTextId = !errorMessage && helperText ? `${controlId}-helper-text` : undefined;
+
+    if (typeof children !== 'function') return null;
+
+    return (
+        <div data-bspk="form-field" data-invalid={invalid || undefined}>
+            <header>
+                <label htmlFor={controlId}>
+                    <Txt as="span" variant="labels-small">
+                        {label}
+                    </Txt>
+                    {required && (
+                        <Txt as="span" variant="body-small">
+                            {' (Required)'}
+                        </Txt>
+                    )}
+                </label>
+                {labelTrailing}
+            </header>
+            {children({
+                invalid,
+                'aria-describedby': helperTextId,
+                'aria-errormessage': errorMessageId,
+            })}
+            {errorMessage && (
+                <InlineAlert id={errorMessageId} variant="error">
+                    {errorMessage}
+                </InlineAlert>
+            )}
+            {helperText && (
+                <Txt id={helperTextId} variant="body-small">
+                    {helperText}
+                </Txt>
+            )}
+        </div>
+    );
+}
+
+FormField.bspkName = 'FormField';
+
+export { FormField };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */