@bspk/ui 1.1.33 → 1.2.0

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

@@ -1,17 +1,15 @@
 [data-bspk='toggle-option'] {
-    display: flex;
+    display: grid;
     width: 100%;
-    flex-direction: row;
-    padding: var(--spacing-sizing-03) var(--spacing-sizing-01) 0 0;
-    gap: var(--spacing-sizing-02);
+    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);
-    align-items: flex-start;
-    justify-content: flex-start;
     max-width: 100%;
+    padding: var(--spacing-sizing-01);
 
     &:has([data-description]) {
         align-items: unset;
@@ -22,10 +20,13 @@
         min-height: var(--spacing-sizing-12);
     }
 
-    [data-content] {
+    [data-control],
+    [data-label],
+    [data-description] {
         display: flex;
-        flex-direction: column;
-        padding: 2px 0;
+        flex-direction: row;
+        align-items: center;
+        justify-content: start;
     }
 
     [data-label] {
@@ -34,11 +35,12 @@
     }
 
     [data-description] {
+        grid-column-start: 2;
         font: var(--body-small);
         color: var(--foreground-neutral-on-surface-variant-01);
     }
 
-    &:not(:has(:disabled)) {
+    &:not([aria-disabled]) {
         [data-pseudo='focus'] &,
         &:focus-visible,
         &:has(*:focus-visible) {
@@ -46,7 +48,9 @@
         }
     }
 
-    &:has(:disabled) {
+    &[aria-disabled] {
+        cursor: not-allowed;
+
         [data-label] {
             color: var(--foreground-neutral-disabled-on-surface);
         }

package/src/components/Tooltip/Tooltip.tsx

@@ -1,7 +1,9 @@
-import { ReactElement, cloneElement, useId, useMemo, useRef, useState } from 'react';
+import { ReactElement, useRef, useState } from 'react';
 
 import { Portal } from '-/components/Portal';
 import { Placement, useFloating } from '-/hooks/useFloating';
+import { useId } from '-/hooks/useId';
+
 import './tooltip.scss';
 
 const DEFAULT = {
@@ -10,6 +12,13 @@ const DEFAULT = {
     disabled: false,
 } as const;
 
+export type TooltipTriggerProps = {
+    onMouseOver?: () => void;
+    onMouseLeave?: () => void;
+    onFocus?: () => void;
+    'aria-describedby'?: string;
+};
+
 export type TooltipProps = {
     /**
      * The placement of the tooltip.
@@ -20,12 +29,11 @@ export type TooltipProps = {
     /** The tooltip content. */
     label: string;
     /**
-     * A single element that will trigger the tooltip when hovered over.
+     * A callback to render the trigger element.
      *
-     * @type ReactElement
      * @required
      */
-    children: ReactElement;
+    children: (triggerProps: TooltipTriggerProps) => ReactElement;
     /** Determines if the tooltip is disabled. */
     disabled?: boolean;
     /**
@@ -46,15 +54,15 @@ export type TooltipProps = {
  *     export function Example() {
  *         return (
  *             <Tooltip label="I explain what this button does" placement="top">
- *                 <Button>Click me</Button>
+ *                 {(triggerProps) => <Button {...triggerProps}>Click me</Button>}
  *             </Tooltip>
  *         );
  *     }
  *
  * @name Tooltip
- * @phase DesignReview
+ * @phase UXReview
  */
-function Tooltip({
+export function Tooltip({
     placement = DEFAULT.placement,
     label,
     children,
@@ -64,18 +72,6 @@ function Tooltip({
     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({
@@ -86,9 +82,20 @@ function Tooltip({
         hide: !show,
     });
 
-    return disabled ? (
-        children
-    ) : (
+    const child = children(
+        disabled
+            ? {}
+            : {
+                  onMouseOver: () => setShow(true),
+                  onMouseLeave: () => setShow(false),
+                  onFocus: () => setShow(true),
+                  'aria-describedby': id,
+              },
+    );
+
+    if (disabled) return child;
+
+    return (
         <>
             {child}
             {label && (
@@ -112,7 +119,7 @@ function Tooltip({
                                 arrowRef.current = node;
                             }}
                             style={{
-                                zIndex: 1000,
+                                zIndex: 'var(--z-index-tooltip-popover)',
                                 opacity: showTail ? 1 : 0,
                                 left: middlewareData.arrow?.x != null ? `${middlewareData.arrow?.x}px` : '',
                                 top: middlewareData.arrow?.y != null ? `${middlewareData.arrow?.y}px` : '',
@@ -125,8 +132,4 @@ function Tooltip({
     );
 }
 
-Tooltip.bspkName = 'Tooltip';
-
-export { Tooltip };
-
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Tooltip/TooltipExample.tsx

@@ -1,15 +1,19 @@
+import { TooltipProps } from './Tooltip';
 import { Button } from '-/components/Button';
 import { ComponentExample } from '-/utils/demo';
 
-export const TooltipExample: ComponentExample = {
+export const TooltipExample: ComponentExample<TooltipProps> = {
     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 {...state} placement={[state.placement].flat()[0] || 'top'}>
+                    {(triggerProps) => (
+                        <Button
+                            label={`Hover over me ${'data-variant-value' in state ? `(${state['data-variant-value']})` : ''}`}
+                            variant="secondary"
+                            {...triggerProps}
+                        />
+                    )}
                 </Component>
             </>
         );

package/src/components/Tooltip/tooltip.scss

@@ -9,7 +9,7 @@
         z-index: 2;
         position: relative;
         background-color: var(--surface-neutral-inverse);
-        border-radius: var(--radius-small);
+        border-radius: var(--radius-sm);
         color: var(--foreground-neutral-on-inverse-surface);
         box-shadow: var(--drop-shadow-float);
         font: var(--labels-small);

package/src/components/TopNavigation/TopNavigation.tsx

@@ -11,12 +11,8 @@ export type TopNavigationProps = {
  * @name TopNavigation
  * @phase Backlog
  */
-function TopNavigation({ children }: TopNavigationProps) {
+export 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/Truncated/Truncated.tsx

@@ -1,10 +1,10 @@
 import { ElementType } from 'react';
 
-import { ElementConstructorProps } from '-';
-import { Tooltip } from '-/components/Tooltip';
+import { Tooltip, TooltipTriggerProps } from '-/components/Tooltip';
 import { useTruncatedText } from '-/hooks/useTruncatedText';
+import { ElementConstructorProps } from '-/types/common';
 
-export type TruncatedProps<As extends ElementType = 'span'> = ElementConstructorProps<'span', 'children'> & {
+export type TruncatedProps<As extends ElementType = 'span'> = {
     /**
      * The element type to render as.
      *
@@ -14,6 +14,9 @@ export type TruncatedProps<As extends ElementType = 'span'> = ElementConstructor
     /**
      * The content to render.
      *
+     * @example
+     *     Some really long text that might be truncated when displayed in a small container.
+     *
      * @type string
      * @required
      */
@@ -30,25 +33,33 @@ export type TruncatedProps<As extends ElementType = 'span'> = ElementConstructor
  * A utility component that displays a tooltip with the full text when hovered when text is truncated.
  *
  * @name Truncated
- * @phase WorkInProgress
+ * @phase Utility
  */
-function Truncated({ children, label, ...props }: TruncatedProps) {
+export function Truncated<As extends ElementType = 'span'>({
+    children,
+    label,
+    ...props
+}: ElementConstructorProps<As, 'children'> & TruncatedProps<As>) {
     const { setElement, isTruncated } = useTruncatedText();
 
-    const span = (
+    const span = (triggerProps: TooltipTriggerProps) => (
         <span
             {...props}
-            data-bspk="truncated"
+            data-bspk-utility="truncated"
             ref={(node) => setElement(node)}
-            style={{ overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}
+            style={{
+                maxWidth: '100%',
+                ...props.style,
+                display: 'inline-block',
+                overflow: 'hidden',
+                textOverflow: 'ellipsis',
+                whiteSpace: 'nowrap',
+            }}
+            {...triggerProps}
         >
             {children}
         </span>
     );
 
-    return isTruncated ? <Tooltip label={label || children}>{span}</Tooltip> : span;
+    return isTruncated ? <Tooltip label={label || children}>{span}</Tooltip> : span({});
 }
-
-Truncated.bspkName = 'Truncated';
-
-export { Truncated };

package/src/components/Txt/Txt.tsx

@@ -1,7 +1,7 @@
 import { ElementType } from 'react';
 
-import { ElementProps } from '-';
 import { SkeletonText } from '-/components/SkeletonText';
+import { ElementProps } from '-/types/common';
 import { TxtVariant } from '-/utils/txtVariants';
 
 export type TxtProps<As extends ElementType = 'span'> = {
@@ -54,9 +54,9 @@ export type TxtProps<As extends ElementType = 'span'> = {
  *     }
  *
  * @name Txt
- * @phase DesignReview
+ * @phase UXReview
  */
-function Txt<As extends ElementType = 'span'>({
+export function Txt<As extends ElementType = 'span'>({
     children,
     as,
     variant = 'body-base',
@@ -85,8 +85,4 @@ function Txt<As extends ElementType = 'span'>({
     );
 }
 
-Txt.bspkName = 'Txt';
-
-export { Txt };
-
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/UIProvider/UIProvider.tsx

@@ -14,7 +14,7 @@ export type UIProviderProps = {
  *
  * @name UIProvider
  */
-function UIProvider({ children }: UIProviderProps) {
+export function UIProvider({ children }: UIProviderProps) {
     const [theme, setTheme] = useState<ColorTheme>('light');
 
     const [deviceWidth, setDeviceWidth] = useDebounceState(() => {
@@ -33,6 +33,7 @@ function UIProvider({ children }: UIProviderProps) {
 
     return (
         <UIContext.Provider
+            data-bspk-utility="ui-provider"
             value={{
                 theme,
                 setTheme,
@@ -45,7 +46,3 @@ function UIProvider({ children }: UIProviderProps) {
         </UIContext.Provider>
     );
 }
-
-UIProvider.bspkName = 'UIProvider';
-
-export { UIProvider };

package/src/constants/brands.ts

@@ -0,0 +1,45 @@
+import { Brand } from '-/types/common';
+
+export const BRANDS: {
+    /** The title of the brand. */
+    title: string;
+    /** The slug of the brand, used in URLs and identifiers. */
+    slug: Brand;
+}[] = [
+    {
+        title: 'Anywhere',
+        slug: 'anywhere',
+    },
+    {
+        title: 'Better Homes & Gardens',
+        slug: 'better-homes-gardens',
+    },
+    {
+        title: 'Cartus',
+        slug: 'cartus',
+    },
+    {
+        title: 'Century 21',
+        slug: 'century-21',
+    },
+    {
+        title: 'Coldwell Banker',
+        slug: 'coldwell-banker',
+    },
+    {
+        title: 'Corcoran',
+        slug: 'corcoran',
+    },
+    {
+        title: 'Denali Boss',
+        slug: 'denali-boss',
+    },
+    {
+        title: 'ERA',
+        slug: 'era',
+    },
+    {
+        title: "Sotheby's",
+        slug: 'sothebys',
+    },
+] as const;

package/src/constants/phases.ts

@@ -0,0 +1,11 @@
+import { ComponentPhase } from '-/types/meta';
+import { ColorVariant } from '-/utils/colorVariants';
+
+export const COMPONENT_PHASE_COLORS: Record<ComponentPhase, ColorVariant> = {
+    Backlog: 'grey',
+    Dev: 'blue',
+    QA: 'yellow',
+    UXReview: 'purple',
+    Stable: 'green',
+    Utility: 'magenta',
+};

package/src/global.d.ts

@@ -0,0 +1,3 @@
+declare module '*.css';
+
+declare module '*.scss';

package/src/hooks/useCombobox.ts

@@ -1,14 +1,12 @@
-import { AriaAttributes, useId, useState } from 'react';
+import { AriaAttributes, useState } from 'react';
 
+import { useFloating, UseFloatingElements, UseFloatingProps } from './useFloating';
+import { useId } from './useId';
+import { CommonProps } from '-/types/common';
 import { EVENT_KEY } from '-/utils/keyboard';
 import { scrollElementIntoView } from '-/utils/scrollElementIntoView';
 
-import { CommonProps, InvalidPropsLibrary } from '..';
-
-import { useFloating, UseFloatingElements, UseFloatingProps } from './useFloating';
-
 export type UseComboboxProps = CommonProps<'disabled' | 'readOnly'> &
-    InvalidPropsLibrary &
     Pick<UseFloatingProps, 'offsetOptions' | 'placement' | 'refWidth'> & {
         /**
          * The element to use for outside click detection.
@@ -53,7 +51,8 @@ function useKeyDownNavigation(containerElement: HTMLElement, setShow: (show: boo
             return true;
         }
 
-        if (event.key !== EVENT_KEY.Enter && !event.key.startsWith('Arrow')) return false;
+        if (event.key !== EVENT_KEY.Enter && event.key !== EVENT_KEY[' '] && !event.key.startsWith('Arrow'))
+            return false;
 
         if (event.key.startsWith('Arrow') && !containerElement) {
             event.preventDefault();
@@ -66,7 +65,7 @@ function useKeyDownNavigation(containerElement: HTMLElement, setShow: (show: boo
 
         event.preventDefault();
 
-        if (event.key === EVENT_KEY.Enter && activeIndex !== -1) {
+        if ((event.key === EVENT_KEY[' '] || event.key === EVENT_KEY.Enter) && activeIndex !== -1) {
             itemElements[activeIndex].click();
             return true;
         }
@@ -103,8 +102,6 @@ export function useCombobox({
     placement = 'bottom',
     refWidth = true,
     disabled,
-    errorMessage,
-    invalid,
     readOnly,
     offsetOptions,
 }: UseComboboxProps): {
@@ -121,6 +118,7 @@ export function useCombobox({
     closeMenu: () => void;
     isOpen: boolean;
     elements: UseFloatingElements;
+    openMenu: () => void;
 } {
     const menuId = useId();
 
@@ -151,13 +149,11 @@ export function useCombobox({
             onOutsideClick: () => setShow(false),
         },
         toggleProps: {
-            'aria-errormessage': errorMessage || undefined,
             'aria-activedescendant': selectedId || undefined,
             'aria-controls': menuId,
             'aria-disabled': disabled || undefined,
             'aria-expanded': show,
             'aria-haspopup': 'listbox' as AriaAttributes['aria-haspopup'],
-            'aria-invalid': invalid || undefined,
             'aria-owns': menuId,
             'aria-readonly': readOnly || undefined,
             role: 'combobox',
@@ -168,6 +164,7 @@ export function useCombobox({
             onKeyDownCapture,
         },
         closeMenu: () => setShow(false),
+        openMenu: () => setShow(true),
         isOpen: show,
         elements,
     };

package/src/hooks/useFloating.ts

@@ -65,11 +65,9 @@ export type UseFloatingProps = {
     /**
      * When set to true, the width of the floating element will match the width of the reference element.
      *
-     * When set to an HTMLElement, the width of the floating element will match the width of that HTMLElement.
-     *
      * @default true
      */
-    refWidth?: HTMLElement | boolean;
+    refWidth?: boolean;
     /** Whether to hide the floating element. */
     hide?: boolean;
 };
@@ -162,10 +160,10 @@ export function useFloating<ReferenceElementType extends HTMLElement = HTMLEleme
                     refWidth &&
                         size({
                             apply({ rects, elements }: MiddlewareState) {
-                                Object.assign(elements.floating.style, {
-                                    width:
-                                        refWidth === true ? `${rects.reference.width}px` : `${refWidth.offsetWidth}px`,
-                                });
+                                if (refWidth)
+                                    Object.assign(elements.floating.style, {
+                                        width: `${rects.reference.width}px`,
+                                    });
                             },
                         }),
                 ],

package/src/hooks/useId.ts

@@ -1,4 +1,5 @@
-import { useId as useIdReact } from 'react';
+import { useMemo } from 'react';
+import { randomString } from '-/utils/random';
 
 /**
  * A utility hook that generates a unique id for an element. If a default id is provided, it will use that instead.
@@ -7,8 +8,9 @@ import { useId as useIdReact } from 'react';
  * @returns {string}
  */
 export function useId(defaultId?: string | null): string {
-    const generatedId = useIdReact();
-    return defaultId || generatedId;
+    return useMemo(() => {
+        return defaultId || randomString(8);
+    }, [defaultId]);
 }
 
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/hooks/useKeyNavigation.ts

@@ -0,0 +1,66 @@
+import { Dispatch, DOMAttributes, SetStateAction, useRef, useState } from 'react';
+import { useOutsideClick } from './useOutsideClick';
+import { handleKeyDown } from '-/utils/handleKeyDown';
+
+export type UseKeyNavigationProps = {
+    /** The callback function to call when a tab is selected (Enter or Space keys). */
+    onSelect: (activeId?: string) => void;
+};
+
+/**
+ * Custom hook to handle keyboard navigation for a list of elements.
+ *
+ * This hook provides functionality to navigate through elements using arrow keys and select an element with the Enter
+ * or Space key, or onClick.
+ */
+export function useKeyNavigation<T extends HTMLElement>({
+    onSelect,
+}: UseKeyNavigationProps): {
+    handleKeyDown: DOMAttributes<T>['onKeyDown'];
+    activeElementId: string | null;
+    setElements: (newElements: HTMLElement[]) => void;
+    setActiveElementId: Dispatch<SetStateAction<string | null>>;
+} {
+    const elements = useRef<HTMLElement[]>([]);
+    const setElements = (newElements: HTMLElement[]) => {
+        elements.current = newElements;
+    };
+
+    const [activeElementId, setActiveElementId] = useState<string | null>(null);
+
+    useOutsideClick({
+        elements: elements.current,
+        callback: () => setActiveElementId(null),
+    });
+
+    const handleIncrement = (increment: -1 | 1) => (): void => {
+        let currentElement = elements.current[0];
+        if (activeElementId)
+            currentElement = elements.current.find((el) => el.id === activeElementId) || elements.current[0];
+
+        const activeIndex = elements.current.indexOf(currentElement);
+        const nextindex = (activeIndex + increment + elements.current.length) % elements.current.length;
+        setActiveElementId(elements.current[nextindex].id);
+    };
+
+    const handleSelect = () => () => {
+        if (activeElementId) onSelect(activeElementId);
+    };
+
+    return {
+        setElements,
+        handleKeyDown: handleKeyDown(
+            {
+                ArrowRight: handleIncrement(1),
+                ArrowDown: handleIncrement(1),
+                ArrowUp: handleIncrement(-1),
+                ArrowLeft: handleIncrement(-1),
+                Enter: handleSelect(),
+                Space: handleSelect(),
+            },
+            { preventDefault: true, stopPropagation: true },
+        ),
+        activeElementId,
+        setActiveElementId,
+    };
+}

package/src/hooks/useLongPress.ts

@@ -1,4 +1,4 @@
-import { useRef, useState } from 'react';
+import { useRef, useState, MouseEvent } from 'react';
 
 import { useTimeout } from './useTimeout';
 
@@ -38,7 +38,8 @@ export function useLongPress(callback: () => void, disabled: boolean) {
     };
 
     return {
-        onMouseDown: () => {
+        onMouseDown: (event: MouseEvent) => {
+            event.preventDefault();
             intervalRef.current = INITIAL_INTERVAL;
             callback();
             timeout.set(run, intervalRef.current);

package/src/hooks/useOutsideClick.ts

@@ -29,11 +29,15 @@ import { useEffect } from 'react';
  * @param callback - The callback to call when a click occurs outside of the ref.
  * @param disabled - Whether the hook should be disabled. Defaults to false.
  */
-export function useOutsideClick(
-    elements: (HTMLElement | null)[] | null,
-    callback: (event?: MouseEvent) => void,
-    disabled?: boolean,
-) {
+export function useOutsideClick({
+    elements,
+    callback,
+    disabled,
+}: {
+    elements: (HTMLElement | null)[] | null;
+    callback: (event?: MouseEvent) => void;
+    disabled?: boolean;
+}) {
     useEffect(() => {
         if (!elements?.length || disabled) return;
 

package/src/hooks/usePaginationState.tsx

@@ -0,0 +1,24 @@
+import { useState } from 'react';
+
+/*
+    * A hook to manage the state of pagination.
+
+    * @param numPages - The total number of pages.
+    * @param initialPage - The initial page to start on (default is 1).
+    * @returns An object containing the current page and a function to set the current page.
+    */
+export const usePaginationState = (numPages: number, initialPage?: number) => {
+    const [currentPage, setCurrentPage] = useState(initialPage || 1);
+
+    const setPage = (page: number) => {
+        if (page < 1 || page > numPages) {
+            return;
+        }
+        setCurrentPage(page);
+    };
+
+    return {
+        currentPage,
+        setCurrentPage: setPage,
+    };
+};