@bspk/ui 1.1.34 → 1.3.0

package/src/components/ToggleOption/ToggleOption.rtl.test.tsx

@@ -0,0 +1,15 @@
+import { ToggleOption } from './ToggleOption';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const TestBed = () => <ToggleOption label="Example label" />;
+
+describe('ToggleOption (RTL)', () => {
+    it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
+
+    it('renders', () => {
+        const { getByText } = render(<TestBed />);
+
+        expect(getByText('Example label')).toBeInTheDocument();
+    });
+});

package/src/components/ToggleOption/ToggleOption.tsx

@@ -1,9 +1,13 @@
-import { ReactElement } from 'react';
 import './toggle-option.scss';
+import { ReactElement } from 'react';
+import { CommonProps } from '-/types/common';
+
+export type ToggleOptionControlProps<T extends { 'aria-label'?: string }> = Omit<T, 'aria-label'> &
+    Pick<ToggleOptionProps, 'description' | 'label'>;
 
-export type ToggleOptionProps = {
+export type ToggleOptionProps = CommonProps<'disabled'> & {
     /**
-     * The label of the option. Also used as the aria-label of the checkbox.
+     * The label of the option. Also used as the aria-label of the control.
      *
      * @required
      */
@@ -25,20 +29,14 @@ export type ToggleOptionProps = {
  * @name ToggleOption
  * @phase Utility
  */
-function ToggleOption({ label, description, children }: ToggleOptionProps) {
+export function ToggleOption({ label, description, children, disabled }: ToggleOptionProps) {
     return (
-        <label data-bspk="toggle-option">
+        <label aria-disabled={!!disabled || undefined} data-bspk="toggle-option">
             <span data-control>{children}</span>
-            <span data-content>
-                <span data-label>{label}</span>
-                {description && <span data-description>{description}</span>}
-            </span>
+            <span data-label>{label}</span>
+            {description && <span data-description>{description}</span>}
         </label>
     );
 }
 
-ToggleOption.bspkName = 'ToggleOption';
-
-export { ToggleOption };
-
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.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.rtl.test.tsx

@@ -0,0 +1,24 @@
+import { Tooltip } from './Tooltip';
+import { Button } from '-/components/Button';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const TestBed = () => (
+    <Tooltip label="Example label" placement="top">
+        {(triggerProps) => (
+            <Button label="Trigger button" {...triggerProps}>
+                Click me
+            </Button>
+        )}
+    </Tooltip>
+);
+
+describe('Tooltip (RTL)', () => {
+    it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
+
+    it('renders', () => {
+        const { getByText } = render(<TestBed />);
+
+        expect(getByText('Example label')).toBeInTheDocument();
+    });
+});

package/src/components/Tooltip/Tooltip.tsx

@@ -1,14 +1,16 @@
-import { ReactElement, cloneElement, useId, useMemo, useRef, useState } from 'react';
-
+import './tooltip.scss';
+import { ReactElement, useRef, useState } from 'react';
 import { Portal } from '-/components/Portal';
 import { Placement, useFloating } from '-/hooks/useFloating';
-import './tooltip.scss';
+import { useId } from '-/hooks/useId';
 
-const DEFAULT = {
-    placement: 'top',
-    showTail: true,
-    disabled: false,
-} as const;
+export type TooltipTriggerProps = {
+    onMouseOver?: () => void;
+    onMouseLeave?: () => void;
+    onFocus?: () => void;
+    onBlur?: () => void;
+    'aria-labelledby'?: string;
+};
 
 export type TooltipProps = {
     /**
@@ -20,12 +22,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,36 +47,18 @@ 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({
-    placement = DEFAULT.placement,
-    label,
-    children,
-    disabled = DEFAULT.disabled,
-    showTail = DEFAULT.showTail,
-}: TooltipProps) {
+export function Tooltip({ placement = 'top', label, children, disabled = false, showTail = true }: 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({
@@ -84,13 +67,20 @@ function Tooltip({
         offsetOptions: showTail ? 8 : 4,
         arrowRef,
         hide: !show,
+        refWidth: false,
     });
 
-    return disabled ? (
-        children
-    ) : (
+    if (disabled) return children({});
+
+    return (
         <>
-            {child}
+            {children({
+                onMouseOver: () => setShow(true),
+                onMouseLeave: () => setShow(false),
+                onFocus: () => setShow(true),
+                onBlur: () => setShow(false),
+                'aria-labelledby': id,
+            })}
             {label && (
                 <Portal>
                     <div
@@ -99,7 +89,7 @@ function Tooltip({
                         id={id}
                         ref={(node) => {
                             elements.setFloating(node);
-                            elements.setReference(document.querySelector<HTMLElement>(`[aria-describedby="${id}"]`));
+                            elements.setReference(document.querySelector<HTMLElement>(`[aria-labelledby="${id}"]`));
                         }}
                         role="tooltip"
                         style={floatingStyles}
@@ -112,7 +102,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 +115,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,17 @@
+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}
+                    label={`Hover over me ${state.label || ''}`}
+                    placement={[state.placement].flat()[0] || 'top'}
+                >
+                    {(triggerProps) => <Button {...triggerProps} label="Hover over me" variant="secondary" />}
                 </Component>
             </>
         );

package/src/components/Tooltip/tooltip.scss

@@ -2,7 +2,6 @@
     position: fixed;
     pointer-events: none;
     z-index: var(--z-index-tooltip-popover);
-    width: max-content !important;
 
     [data-text] {
         display: block;
@@ -16,7 +15,6 @@
         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);

package/src/components/TopNavigation/TopNavigation.rtl.test.tsx

@@ -0,0 +1,15 @@
+import { TopNavigation } from './TopNavigation';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const TestBed = () => <TopNavigation>Example content</TopNavigation>;
+
+describe('TopNavigation (RTL)', () => {
+    it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
+
+    it('renders', () => {
+        const { getByText } = render(<TestBed />);
+
+        expect(getByText('Example content')).toBeInTheDocument();
+    });
+});

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.rtl.test.tsx

@@ -0,0 +1,15 @@
+import { Truncated } from './Truncated';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const TestBed = () => <Truncated>Example content</Truncated>;
+
+describe('Truncated (RTL)', () => {
+    it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
+
+    it('renders', () => {
+        const { getByText } = render(<TestBed />);
+
+        expect(getByText('Example content')).toBeInTheDocument();
+    });
+});

package/src/components/Truncated/Truncated.tsx

@@ -1,10 +1,10 @@
+import './truncated.scss';
 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,26 @@ 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' }}
+            {...triggerProps}
+            role={isTruncated ? 'note' : props.role}
         >
             {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/Truncated/truncated.scss

@@ -0,0 +1,8 @@
+[data-bspk-utility='truncated'] {
+    max-width: 100%;
+    display: inline-block;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    background-color: transparent;
+}

package/src/components/Txt/Txt.rtl.test.tsx

@@ -0,0 +1,15 @@
+import { Txt } from './Txt';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const TestBed = () => <Txt>Example content</Txt>;
+
+describe('Txt (RTL)', () => {
+    it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
+
+    it('renders', () => {
+        const { getByText } = render(<TestBed />);
+
+        expect(getByText('Example content')).toBeInTheDocument();
+    });
+});

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/AriaLiveMessageHandler.tsx

@@ -0,0 +1,44 @@
+import { useState } from 'react';
+import { useEventListener } from '-/hooks/useAddEventListener';
+import { useTimeout } from '-/hooks/useTimeout';
+import { AriaLiveMessage } from '-/utils/uiContext';
+
+export function sendAriaLiveMessage(message: string, live: 'assertive' | 'polite' = 'polite') {
+    document.dispatchEvent(new CustomEvent('aria-live', { detail: { message, live } }));
+}
+
+/**
+ * AriaLiveMessageHandler is a single use component that listens for aria-live messages and displays them to the user.
+ *
+ * We use a custom event to communicate between components and this handler.
+ *
+ * We don't store the message in context to avoid unnecessary re-renders of all components that consume the context. :)
+ *
+ * We queue messages to ensure that they are read by screen readers.
+ *
+ * After the message is read, we clear it after a short delay to allow for subsequent messages to be read.
+ */
+export function AriaLiveMessageHandler() {
+    const [ariaLiveMessage, setAriaLiveMessage] = useState<AriaLiveMessage | undefined>(undefined);
+
+    const timeout = useTimeout();
+
+    useEventListener(
+        'aria-live',
+        (event: CustomEvent) => {
+            const { message, live } = event.detail;
+            // Clear any existing message to ensure that screen readers read the new message
+            setAriaLiveMessage(undefined);
+            timeout.set(() => setAriaLiveMessage({ message, live: live || 'polite' }), 10);
+        },
+        document,
+    );
+
+    return (
+        ariaLiveMessage && (
+            <div aria-live={ariaLiveMessage?.live || 'polite'} data-sr-only role="alert">
+                {ariaLiveMessage?.message}
+            </div>
+        )
+    );
+}

package/src/components/UIProvider/UIProvider.tsx

@@ -1,21 +1,33 @@
 import { useState, ReactNode } from 'react';
-
+import { AriaLiveMessageHandler, sendAriaLiveMessage } from './AriaLiveMessageHandler';
 import { useEventListener } from '-/hooks/useAddEventListener';
 import { useDebounceState } from '-/hooks/useDebounceState';
 import { useIsomorphicEffect } from '-/hooks/useIsomorphicEffect';
 import { UIContext, ColorTheme } from '-/utils/uiContext';
 
 export type UIProviderProps = {
+    /**
+     * The children elements that will have access to the UI context.
+     *
+     * @required
+     */
     children: ReactNode;
 };
 
 /**
- * UIProvider is a React context provider that manages the UI state, including theme and responsive state.
+ * UIProvider is a React context provider that manages the UI state.
+ *
+ * UI state includes, theme, setTheme, responsive state, aria live messages
+ *
+ * This provider should wrap the root of your application to ensure that all components have access to the UI context.
  *
  * @name UIProvider
+ *
+ * @phase Utility
  */
-function UIProvider({ children }: UIProviderProps) {
+export function UIProvider({ children }: UIProviderProps) {
     const [theme, setTheme] = useState<ColorTheme>('light');
+    // Keep track of device width to determine if we are in mobile, tablet, or desktop mode
 
     const [deviceWidth, setDeviceWidth] = useDebounceState(() => {
         return typeof window !== 'undefined' ? window.innerWidth : 0;
@@ -33,19 +45,18 @@ function UIProvider({ children }: UIProviderProps) {
 
     return (
         <UIContext.Provider
+            data-bspk-utility="ui-provider"
             value={{
                 theme,
                 setTheme,
                 isMobile: deviceWidth < 640,
                 isTablet: deviceWidth > 640 && deviceWidth < 1024,
                 isDesktop: deviceWidth >= 1024,
+                sendAriaLiveMessage,
             }}
         >
             {children}
+            <AriaLiveMessageHandler />
         </UIContext.Provider>
     );
 }
-
-UIProvider.bspkName = 'UIProvider';
-
-export { UIProvider };