@bspk/ui 1.1.31 → 1.1.33

package/src/components/TextareaField/TextareaFieldExample.tsx

@@ -0,0 +1,19 @@
+import { ComponentExample } from '-/utils/demo';
+
+import { TextareaFieldProps } from '.';
+
+export const TextareaFieldExample: ComponentExample<TextareaFieldProps> = {
+    render: ({ Component, props }) => {
+        const tooManyCharacters = Boolean(props.value && props.maxLength && props.value?.length > props.maxLength);
+
+        const invalid = props.invalid || tooManyCharacters;
+
+        return (
+            <Component
+                {...props}
+                errorMessage={invalid ? props.errorMessage || 'Too Many characters' : ''}
+                invalid={invalid}
+            />
+        );
+    },
+};

package/src/components/TextareaField/index.tsx

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

package/src/components/ToggleOption/ToggleOption.tsx

@@ -0,0 +1,44 @@
+import { ReactElement } from 'react';
+import './toggle-option.scss';
+
+export type ToggleOptionProps = {
+    /**
+     * The label of the option. Also used as the aria-label of the checkbox.
+     *
+     * @required
+     */
+    label: string;
+    /**
+     * The description of the option.
+     *
+     * @type multiline
+     * @type multiline
+     */
+    description?: string;
+    /** The control element to use. */
+    children?: ReactElement;
+};
+
+/**
+ * A utility component that wraps a checkbox, radio, and switch.
+ *
+ * @name ToggleOption
+ * @phase Utility
+ */
+function ToggleOption({ label, description, children }: ToggleOptionProps) {
+    return (
+        <label data-bspk="toggle-option">
+            <span data-control>{children}</span>
+            <span data-content>
+                <span data-label>{label}</span>
+                {description && <span data-description>{description}</span>}
+            </span>
+        </label>
+    );
+}
+
+ToggleOption.bspkName = 'ToggleOption';
+
+export { ToggleOption };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/ToggleOption/index.tsx

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

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

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

package/src/components/Tooltip/Tooltip.tsx

@@ -0,0 +1,132 @@
+import { ReactElement, cloneElement, useId, useMemo, useRef, useState } from 'react';
+
+import { Portal } from '-/components/Portal';
+import { Placement, useFloating } from '-/hooks/useFloating';
+import './tooltip.scss';
+
+const DEFAULT = {
+    placement: 'top',
+    showTail: true,
+    disabled: false,
+} as const;
+
+export type TooltipProps = {
+    /**
+     * The placement of the tooltip.
+     *
+     * @default top
+     */
+    placement?: Extract<Placement, 'bottom' | 'left' | 'right' | 'top'>;
+    /** The tooltip content. */
+    label: string;
+    /**
+     * A single element that will trigger the tooltip when hovered over.
+     *
+     * @type ReactElement
+     * @required
+     */
+    children: ReactElement;
+    /** Determines if the tooltip is disabled. */
+    disabled?: boolean;
+    /**
+     * Determines if the tooltip should hide the tail.
+     *
+     * @default true
+     */
+    showTail?: boolean;
+};
+
+/**
+ * Brief message that provide additional guidance and helps users perform an action if needed.
+ *
+ * @example
+ *     import { Tooltip } from '@bspk/ui/Tooltip';
+ *     import { Button } from '@bspk/ui/Button';
+ *
+ *     export function Example() {
+ *         return (
+ *             <Tooltip label="I explain what this button does" placement="top">
+ *                 <Button>Click me</Button>
+ *             </Tooltip>
+ *         );
+ *     }
+ *
+ * @name Tooltip
+ * @phase DesignReview
+ */
+function Tooltip({
+    placement = DEFAULT.placement,
+    label,
+    children,
+    disabled = DEFAULT.disabled,
+    showTail = DEFAULT.showTail,
+}: TooltipProps) {
+    const id = useId();
+    const [show, setShow] = useState(false);
+
+    const child = useMemo(
+        () =>
+            !disabled &&
+            children &&
+            cloneElement(children, {
+                onMouseOver: () => setShow(true),
+                onMouseLeave: () => setShow(false),
+                'aria-describedby': id,
+            }),
+        [children, disabled, id],
+    );
+
+    const arrowRef = useRef<HTMLElement | null>(null);
+
+    const { floatingStyles, middlewareData, elements } = useFloating({
+        placement,
+        strategy: 'fixed',
+        offsetOptions: showTail ? 8 : 4,
+        arrowRef,
+        hide: !show,
+    });
+
+    return disabled ? (
+        children
+    ) : (
+        <>
+            {child}
+            {label && (
+                <Portal>
+                    <div
+                        data-bspk="tooltip"
+                        data-placement={middlewareData?.offset?.placement}
+                        id={id}
+                        ref={(node) => {
+                            elements.setFloating(node);
+                            elements.setReference(document.querySelector<HTMLElement>(`[aria-describedby="${id}"]`));
+                        }}
+                        role="tooltip"
+                        style={floatingStyles}
+                    >
+                        <span data-text>{label}</span>
+                        <span
+                            aria-hidden
+                            data-arrow
+                            ref={(node) => {
+                                arrowRef.current = node;
+                            }}
+                            style={{
+                                zIndex: 1000,
+                                opacity: showTail ? 1 : 0,
+                                left: middlewareData.arrow?.x != null ? `${middlewareData.arrow?.x}px` : '',
+                                top: middlewareData.arrow?.y != null ? `${middlewareData.arrow?.y}px` : '',
+                            }}
+                        />
+                    </div>
+                </Portal>
+            )}
+        </>
+    );
+}
+
+Tooltip.bspkName = 'Tooltip';
+
+export { Tooltip };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Tooltip/TooltipExample.tsx

@@ -0,0 +1,17 @@
+import { Button } from '-/components/Button';
+import { ComponentExample } from '-/utils/demo';
+
+export const TooltipExample: ComponentExample = {
+    render: ({ props: state, Component }) => {
+        return (
+            <>
+                <Component label="Tooltip text" {...state} placement={[state.placement].flat()[0] || 'top'}>
+                    <Button
+                        label={`Hover over me ${'data-variant-value' in state ? `(${state['data-variant-value']})` : ''}`}
+                        variant="secondary"
+                    />
+                </Component>
+            </>
+        );
+    },
+};

package/src/components/Tooltip/index.tsx

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

package/src/components/Tooltip/tooltip.scss

@@ -0,0 +1,65 @@
+[data-bspk='tooltip'] {
+    position: fixed;
+    pointer-events: none;
+    z-index: var(--z-index-tooltip-popover);
+    width: max-content !important;
+
+    [data-text] {
+        display: block;
+        z-index: 2;
+        position: relative;
+        background-color: var(--surface-neutral-inverse);
+        border-radius: var(--radius-small);
+        color: var(--foreground-neutral-on-inverse-surface);
+        box-shadow: var(--drop-shadow-float);
+        font: var(--labels-small);
+        padding: var(--spacing-sizing-01) var(--spacing-sizing-02);
+        border: none;
+        transition: opacity 0.2s ease-in-out;
+        width: max-content;
+    }
+
+    --arrow-size: var(--spacing-sizing-01);
+    --arrow-offset: calc(var(--arrow-size) * -2);
+    --arrow-color: var(--surface-neutral-inverse);
+
+    [data-arrow] {
+        display: block;
+        z-index: 1;
+        position: absolute;
+        width: 0;
+        height: 0;
+        border-style: solid;
+        border-width: var(--arrow-size) var(--arrow-size) var(--arrow-size) var(--arrow-size);
+        border-color: transparent;
+    }
+
+    &[data-placement='bottom'] {
+        [data-arrow] {
+            top: var(--arrow-offset);
+            border-bottom-color: var(--arrow-color);
+        }
+    }
+
+    &[data-placement='top'] {
+        [data-arrow] {
+            border-top-color: var(--arrow-color);
+        }
+    }
+
+    &[data-placement='right'] {
+        [data-arrow] {
+            margin-left: var(--arrow-offset);
+            border-right-color: var(--arrow-color);
+        }
+    }
+
+    &[data-placement='left'] {
+        [data-arrow] {
+            right: var(--arrow-offset);
+            border-left-color: var(--arrow-color);
+        }
+    }
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/TopNavigation/TopNavigation.tsx

@@ -0,0 +1,22 @@
+import './top-navigation.scss';
+
+export type TopNavigationProps = {
+    /** The content of the top navigation. */
+    children: string;
+};
+
+/**
+ * Component description coming soon.
+ *
+ * @name TopNavigation
+ * @phase Backlog
+ */
+function TopNavigation({ children }: TopNavigationProps) {
+    return <div data-bspk="top-navigation">{children}</div>;
+}
+
+TopNavigation.bspkName = 'TopNavigation';
+
+export { TopNavigation };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/TopNavigation/index.tsx

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

package/src/components/Truncated/Truncated.tsx

@@ -0,0 +1,54 @@
+import { ElementType } from 'react';
+
+import { ElementConstructorProps } from '-';
+import { Tooltip } from '-/components/Tooltip';
+import { useTruncatedText } from '-/hooks/useTruncatedText';
+
+export type TruncatedProps<As extends ElementType = 'span'> = ElementConstructorProps<'span', 'children'> & {
+    /**
+     * The element type to render as.
+     *
+     * @default span
+     */
+    as?: As;
+    /**
+     * The content to render.
+     *
+     * @type string
+     * @required
+     */
+    children: string;
+    /**
+     * The label to display in the tooltip when the text is truncated.
+     *
+     * If not provided, the children will be used as the label.
+     */
+    label?: string;
+};
+
+/**
+ * A utility component that displays a tooltip with the full text when hovered when text is truncated.
+ *
+ * @name Truncated
+ * @phase WorkInProgress
+ */
+function Truncated({ children, label, ...props }: TruncatedProps) {
+    const { setElement, isTruncated } = useTruncatedText();
+
+    const span = (
+        <span
+            {...props}
+            data-bspk="truncated"
+            ref={(node) => setElement(node)}
+            style={{ overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}
+        >
+            {children}
+        </span>
+    );
+
+    return isTruncated ? <Tooltip label={label || children}>{span}</Tooltip> : span;
+}
+
+Truncated.bspkName = 'Truncated';
+
+export { Truncated };

package/src/components/Truncated/index.tsx

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

package/src/components/Txt/Txt.tsx

@@ -0,0 +1,92 @@
+import { ElementType } from 'react';
+
+import { ElementProps } from '-';
+import { SkeletonText } from '-/components/SkeletonText';
+import { TxtVariant } from '-/utils/txtVariants';
+
+export type TxtProps<As extends ElementType = 'span'> = {
+    /**
+     * The element type to render as.
+     *
+     * @default span
+     * @type ElementType
+     */
+    as?: As;
+    /**
+     * The content to render.
+     *
+     * @type string
+     * @required
+     */
+    children: unknown;
+    /**
+     * The variant to use.
+     *
+     * @default body-base
+     */
+    variant?: TxtVariant;
+    /** The id of the element. */
+    id?: string;
+    /**
+     * The number of lines to display for skeleton text.
+     *
+     * If not provided, it defaults to 0, meaning no skeleton lines will be shown.
+     *
+     * @default 0
+     */
+    skeletonLines?: number;
+    /**
+     * Inherit style and not set font style.
+     *
+     * @default false
+     */
+    inherit?: boolean;
+};
+
+/**
+ * A text component that applies the correct font styles based on the variant and size. variant
+ *
+ * @example
+ *     import { Txt } from '@bspk/ui/Txt';
+ *
+ *     export function Example() {
+ *         return <Txt>Example Txt</Txt>;
+ *     }
+ *
+ * @name Txt
+ * @phase DesignReview
+ */
+function Txt<As extends ElementType = 'span'>({
+    children,
+    as,
+    variant = 'body-base',
+    style: styleProp,
+    skeletonLines = 0,
+    inherit,
+    ...containerProps
+}: ElementProps<TxtProps<As>, As>) {
+    const content = children?.toString();
+
+    if (!content) return skeletonLines ? <SkeletonText lines={skeletonLines} variant={variant} /> : null;
+
+    const As: ElementType = as || 'span';
+
+    return (
+        <As
+            {...containerProps}
+            data-bspk="txt"
+            style={{
+                ...styleProp,
+                font: inherit ? undefined : `var(--${variant})`,
+            }}
+        >
+            {content}
+        </As>
+    );
+}
+
+Txt.bspkName = 'Txt';
+
+export { Txt };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Txt/index.tsx

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

package/src/components/UIProvider/UIProvider.tsx

@@ -0,0 +1,51 @@
+import { useState, ReactNode } from 'react';
+
+import { useEventListener } from '-/hooks/useAddEventListener';
+import { useDebounceState } from '-/hooks/useDebounceState';
+import { useIsomorphicEffect } from '-/hooks/useIsomorphicEffect';
+import { UIContext, ColorTheme } from '-/utils/uiContext';
+
+export type UIProviderProps = {
+    children: ReactNode;
+};
+
+/**
+ * UIProvider is a React context provider that manages the UI state, including theme and responsive state.
+ *
+ * @name UIProvider
+ */
+function UIProvider({ children }: UIProviderProps) {
+    const [theme, setTheme] = useState<ColorTheme>('light');
+
+    const [deviceWidth, setDeviceWidth] = useDebounceState(() => {
+        return typeof window !== 'undefined' ? window.innerWidth : 0;
+    }, 250);
+
+    useIsomorphicEffect(() => {
+        document.documentElement.dataset.theme = theme;
+        document.documentElement.style.setProperty(
+            '--scrollbar-width',
+            `${window.innerWidth - document.documentElement.clientWidth}px`,
+        );
+    }, [theme]);
+
+    useEventListener('resize', () => setDeviceWidth(window.innerWidth));
+
+    return (
+        <UIContext.Provider
+            value={{
+                theme,
+                setTheme,
+                isMobile: deviceWidth < 640,
+                isTablet: deviceWidth > 640 && deviceWidth < 1024,
+                isDesktop: deviceWidth >= 1024,
+            }}
+        >
+            {children}
+        </UIContext.Provider>
+    );
+}
+
+UIProvider.bspkName = 'UIProvider';
+
+export { UIProvider };

package/src/components/UIProvider/index.tsx

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

package/src/hooks/useAddEventListener.ts

@@ -0,0 +1,51 @@
+import { useRef } from 'react';
+
+import { useIsomorphicEffect } from './useIsomorphicEffect';
+
+export function useEventListener<
+    KW extends keyof WindowEventMap,
+    KH extends keyof HTMLElementEventMap & keyof SVGElementEventMap,
+    KM extends keyof MediaQueryListEventMap,
+    T extends Document | HTMLElement | MediaQueryList | SVGAElement | Window = HTMLElement,
+>(
+    eventName: KH | KM | KW,
+    handler: (
+        event:
+            | Event
+            | HTMLElementEventMap[KH]
+            | MediaQueryListEventMap[KM]
+            | SVGElementEventMap[KH]
+            | WindowEventMap[KW],
+    ) => void,
+    element?: T,
+    disabled?: boolean,
+    options?: AddEventListenerOptions | boolean,
+) {
+    // Create a ref that stores handler
+    const savedHandler = useRef(handler);
+
+    useIsomorphicEffect(() => {
+        savedHandler.current = handler;
+    }, [handler]);
+
+    useIsomorphicEffect(() => {
+        if (disabled) return;
+
+        // Define the listening target
+        const targetElement: T | Window = element ?? window;
+
+        if (!(targetElement && targetElement.addEventListener)) return;
+
+        // Create event listener that calls handler function stored in ref
+        const listener: typeof handler = (event) => {
+            savedHandler.current(event);
+        };
+
+        targetElement.addEventListener(eventName, listener, options);
+
+        // Remove event listener on cleanup
+        return () => {
+            targetElement.removeEventListener(eventName, listener, options);
+        };
+    }, [eventName, element, options]);
+}

package/src/hooks/useCheckboxGroupState.ts

@@ -1,6 +1,6 @@
 import { useCallback, useMemo, useState } from 'react';
 
-import { CheckboxProps } from '../Checkbox';
+import { CheckboxProps } from '-/components/Checkbox';
 
 /**
  * A hook to manage the state of a group of checkboxes. Used alongside the CheckboxGroup component.

package/src/hooks/useCheckboxState.ts

@@ -1,6 +1,6 @@
 import { useState } from 'react';
 
-import { CheckboxProps } from '../Checkbox';
+import { CheckboxProps } from '-/components/Checkbox';
 
 /**
  * A hook to manage the state of a single checkbox. Used alongside the Checkbox component.