@bspk/ui 1.2.0 → 1.3.0

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

@@ -0,0 +1,30 @@
+import { FormField } from './FormField';
+import { TextInput } from '-/components/TextInput';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const TestBed = () => (
+    <FormField controlId="Example controlId" label="Example label">
+        {(fieldProps) => {
+            return (
+                <TextInput
+                    aria-label="example aria-label"
+                    name="example-text"
+                    onChange={() => {}}
+                    value="Input text"
+                    {...fieldProps}
+                />
+            );
+        }}
+    </FormField>
+);
+
+describe('FormField (RTL)', () => {
+    it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
+
+    it('renders', () => {
+        const { getByLabelText } = render(<TestBed />);
+
+        expect(getByLabelText('example aria-label')).toBeInTheDocument();
+    });
+});

package/src/components/FormField/FormField.tsx

@@ -1,9 +1,8 @@
+import './form-field.scss';
 import { InlineAlert } from '-/components/InlineAlert';
 import { Txt } from '-/components/Txt';
 import { CommonProps, ElementProps, FormFieldControlProps } from '-/types/common';
 
-import './form-field.scss';
-
 // omits are usually a code smell, but in this case, we need to ensure we get all the props from child components
 export type FormFieldWrapProps<T extends Record<string, unknown>> = Omit<FormFieldProps, keyof T | 'children'> &
     Omit<T, 'aria-describedby' | 'aria-errormessage'>;
@@ -20,7 +19,7 @@ export type FormFieldProps = CommonProps<'invalid' | 'required'> & {
     /** 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.
+     * The children of the form field. This should be a control such as TextInput, Select, DateInput, or TimeInput.
      *
      * @type (childProps: FormFieldControlProps) => JSX.Element
      * @required
@@ -35,7 +34,7 @@ export type FormFieldProps = CommonProps<'invalid' | 'required'> & {
 /**
  * Wrapper component for form controls.
  *
- * Children may be one of the following: TextInput, Select, DatePicker, or TimePicker.
+ * Children should be one of the following: TextInput, Select, DateInput or TimeInput.
  *
  * @example
  *     import { TextInput } from '@bspk/ui/TextInput';

package/src/components/FormField/form-field.scss

@@ -1,4 +1,4 @@
-[data-bspk='form-field'] {
+[data-bspk-utility='form-field'] {
     width: 100%;
     display: flex;
     flex-direction: column;

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

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

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

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

package/src/components/InlineAlert/InlineAlert.tsx

@@ -1,3 +1,4 @@
+import './inline-alert.scss';
 import { SvgCheckCircleFill } from '@bspk/icons/CheckCircleFill';
 import { SvgErrorFill } from '@bspk/icons/ErrorFill';
 import { SvgInfoFill } from '@bspk/icons/InfoFill';
@@ -6,8 +7,6 @@ import { SvgWarningTwoTone } from './SvgWarningTwoTone';
 import { Txt } from '-/components/Txt';
 import { AlertVariant } from '-/types/common';
 
-import './inline-alert.scss';
-
 export type InlineAlertProps = {
     /**
      * The content of the inline alert.

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

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

package/src/components/Layout/LayoutExample.tsx

@@ -1,5 +1,7 @@
 import { LayoutProps } from './Layout';
-import { ComponentExample } from '-/utils/demo';
+import { ComponentExample, Preset } from '-/utils/demo';
+
+export const presets: Preset<LayoutProps>[] = [];
 
 export const LayoutExample: ComponentExample<LayoutProps> = {
     render: ({ props, Component }) => {
@@ -11,4 +13,5 @@ export const LayoutExample: ComponentExample<LayoutProps> = {
             </Component>
         );
     },
+    presets,
 };

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

@@ -0,0 +1,14 @@
+import { Link } from './Link';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const TestBed = () => <Link href="https://bspk.dev" label="Example link" trailingIcon="external" />;
+
+describe('Link (RTL)', () => {
+    it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
+
+    it('renders', async () => {
+        const { findByText } = render(<TestBed />);
+        expect(await findByText('Example link')).toBeInTheDocument();
+    });
+});

package/src/components/Link/Link.tsx

@@ -1,9 +1,7 @@
+import './link.scss';
 import { AnchorHTMLAttributes, ComponentType, lazy, LazyExoticComponent, Suspense } from 'react';
-
 import { CommonPropsLibrary, ElementProps } from '-/types/common';
 
-import './link.scss';
-
 export type LinkProps = Pick<CommonPropsLibrary, 'disabled'> & {
     /**
      * The label of the link.

package/src/components/Link/LinkExample.tsx

@@ -3,7 +3,9 @@ import { Fragment } from 'react';
 import { LinkProps, Link } from '.';
 import { Txt } from '-/components/Txt';
 import { useId } from '-/hooks/useId';
-import { ComponentExample } from '-/utils/demo';
+import { ComponentExample, Preset } from '-/utils/demo';
+
+export const presets: Preset<LinkProps>[] = [];
 
 export const LinkExample: ComponentExample<LinkProps> = {
     containerStyle: {
@@ -30,6 +32,7 @@ export const LinkExample: ComponentExample<LinkProps> = {
             content: ({ props }) => <LinkDemo props={props} />,
         },
     ],
+    presets,
 };
 
 /**

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

@@ -0,0 +1,18 @@
+import { ListItem } from './ListItem';
+import { presets } from './ListItemExample';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+describe('ListItem (RTL)', () => {
+    presets.forEach((preset) => {
+        it(`has no basic a11y issues - ${preset.label}`, hasNoBasicA11yIssues(<ListItem {...preset.propState} />));
+    });
+
+    it('renders', () => {
+        const { getByText } = render(<ListItem {...presets[0].propState} />);
+
+        expect(
+            getByText('This is a really long label that should be truncated if it exceeds the width of the ListItem'),
+        ).toBeInTheDocument();
+    });
+});

package/src/components/ListItem/ListItem.tsx

@@ -1,60 +1,95 @@
-import { AnchorHTMLAttributes, ElementType, ReactNode } from 'react';
+import './list-item.scss';
+import {
+    AnchorHTMLAttributes,
+    ElementType,
+    ReactNode,
+    MouseEvent,
+    AriaAttributes,
+    HTMLAttributes,
+    AriaRole,
+} from 'react';
 import { ListItemButton } from './ListItemButton';
 import { Truncated } from '-/components/Truncated';
+import { useId } from '-/hooks/useId';
 import { CommonProps, ElementProps, SetRef } from '-/types/common';
 
-import './list-item.scss';
-
-export type ListItemProps<As extends ElementType = 'div', T = HTMLElement> = CommonProps<
+export type ListItemProps<As extends ElementType = ElementType> = CommonProps<
     'active' | 'disabled' | 'owner' | 'readOnly'
-> & {
-    /**
-     * The element type to render as.
-     *
-     * @default div
-     * @type ElementType
-     */
-    as?: As;
-    /**
-     * The leading element to display in the ListItem.
-     *
-     * Leading elements may only be one of the following [Icon](/icons), Img, Avatar.
-     *
-     * @exampleType select
-     * @options Icon, Img, Avatar
-     */
-    leading?: ReactNode;
-    /**
-     * The label to display in the ListItem.
-     *
-     * @required
-     */
-    label: string;
-    /** The subtext to display in the ListItem. */
-    subText?: string;
-    /**
-     * The trailing element to display in the ListItem.
-     *
-     * Trailing elements may only be one of the following [Icon](/icons), Checkbox, ListItemButton, Radio, Switch, Tag,
-     * Txt.
-     *
-     * @exampleType select
-     * @options Checkbox, Icon, ListItemButton, Radio, Switch, Tag, Txt
-     */
-    trailing?: ReactNode;
-    /**
-     * The [href](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a#href) of the list item.
-     *
-     * If the href is provided, the ListItem will render as an anchor element (`<a>`).
-     */
-    href?: AnchorHTMLAttributes<unknown>['href'];
-    /** A ref to the list item div element. */
-    innerRef?: SetRef<T>;
-    /** The ARIA role of the list item. */
-    role?: string;
-    /** Whether the aria-label should be included on the list item. */
-    includeAriaLabel?: boolean;
-};
+> &
+    Pick<AriaAttributes, 'aria-label'> & {
+        /**
+         * The element type to render as.
+         *
+         * @default div
+         * @type ElementType
+         */
+        as?: As;
+        /**
+         * The leading element to display in the ListItem.
+         *
+         * Leading elements should only be one of the following [Icon](/icons), Img, Avatar.
+         *
+         * @exampleType select
+         * @options Icon, Img, Avatar
+         */
+        leading?: ReactNode;
+        /**
+         * The label to display in the ListItem.
+         *
+         * @required
+         */
+        label: string;
+        /** The subtext to display in the ListItem. */
+        subText?: string;
+        /**
+         * The trailing element to display in the ListItem.
+         *
+         * Trailing elements should only be one of the following [Icon](/icons), Checkbox, ListItemButton, Radio,
+         * Switch, Tag, Txt.
+         *
+         * @exampleType select
+         * @options Checkbox, Icon, ListItemButton, Radio, Switch, Tag, Txt
+         */
+        trailing?: ReactNode;
+        /**
+         * The [href](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a#href) of the list item.
+         *
+         * If the href is provided, the ListItem will render as an anchor element (`<a>`).
+         */
+        href?: AnchorHTMLAttributes<unknown>['href'];
+        /** A ref to the list item div element. */
+        innerRef?: SetRef<HTMLElement>;
+        /**
+         * The ARIA role of the list item.
+         *
+         * The role will be set to 'button' automatically if the ListItem has an onClick prop and is not a button,
+         * label, or anchor element.
+         *
+         * If including other focusable elements (e.g. buttons, links) in the leading or trailing slots, the role should
+         * be set explicitly to something other than 'button'.
+         */
+        role?: AriaRole;
+        /** Callback function that is called when the ListItem is clicked. */
+        onClick?: (event: MouseEvent<HTMLElement>) => void;
+        /**
+         * The unique ID of the list item.
+         *
+         * If not provided, a unique ID will be generated. This is useful for accessibility and testing purposes.
+         */
+        id?: string;
+        /**
+         * Whether to hide the label from screen readers. Use this when the label is redundant with other context, such
+         * as within a ListItemMenu or Label.
+         *
+         * @default false
+         */
+        hideAriaLabel?: boolean;
+        /**
+         * Indicates the current "selected" state of the list item when used in a selectable context, such as within a
+         * ListItemMenu.
+         */
+        'aria-selected'?: boolean;
+    };
 
 /**
  * A hybrid interactive component that is used frequently to organize content and offers a wide range of control and
@@ -64,9 +99,9 @@ export type ListItemProps<As extends ElementType = 'div', T = HTMLElement> = Com
  *
  * The ListItem has three main elements: leading element, label, and trailing element.
  *
- * Leading elements may be one of the following [Icon](/icons), Img, Avatar.
+ * Leading elements should be one of the following [Icon](/icons), Img, Avatar.
  *
- * Trailing elements may be one of the following [Icon](/icons), Checkbox, ListItemButton, Radio, Switch, Tag, Txt.
+ * Trailing elements should be one of the following [Icon](/icons), Checkbox, ListItemButton, Radio, Switch, Tag, Txt.
  *
  * The ListItemButton is a more limited Button with context specific options.
  *
@@ -88,8 +123,7 @@ export type ListItemProps<As extends ElementType = 'div', T = HTMLElement> = Com
  * @name ListItem
  * @phase UXReview
  */
-function ListItem<As extends ElementType = 'div', T = HTMLElement>({
-    includeAriaLabel = true,
+function ListItem<As extends ElementType = ElementType>({
     active,
     as,
     disabled,
@@ -98,45 +132,45 @@ function ListItem<As extends ElementType = 'div', T = HTMLElement>({
     leading,
     readOnly,
     owner,
-    role,
+    role: roleProp,
     subText,
     trailing,
+    id: idProp,
+    'aria-label': ariaLabel,
+    'aria-selected': ariaSelected,
+    hideAriaLabel,
     ...props
-}: ElementProps<ListItemProps<As, T>, As>) {
-    if (!label) return null;
+}: ElementProps<ListItemProps<As>, As>) {
+    const id = useId(idProp);
 
-    let As = as || 'div';
-
-    if (!as) {
-        if (props.href) As = 'a';
-        else if (props.onClick) As = 'button';
-    }
+    if (!label) return null;
 
-    const actionable = (As === 'a' || As === 'button') && !props.disabled && !props.readOnly;
+    const As = asLogic(as, props);
+    const role = roleLogic(roleProp, { as: As, props });
+    const actionable = (props.href || props.onClick) && !props.disabled && !props.readOnly;
 
     return (
         <As
             {...props}
             aria-disabled={disabled || undefined}
-            aria-label={
-                As === 'label' || As === 'span' || As === 'div' || includeAriaLabel === false ? undefined : label
-            }
-            as={As}
+            aria-label={ariaLabel || undefined}
+            aria-selected={ariaSelected}
             data-action={actionable || undefined}
             data-active={active || undefined}
             data-bspk="list-item"
             data-bspk-owner={owner || undefined}
             data-readonly={readOnly || undefined}
+            id={id}
             ref={innerRef}
-            role={role || (As === 'button' ? 'option' : undefined)}
-            tabIndex={actionable ? 0 : undefined}
+            role={role}
+            tabIndex={props.tabIndex || (actionable ? 0 : undefined)}
         >
             {leading && (
                 <span aria-hidden data-leading>
                     {leading}
                 </span>
             )}
-            <span data-item-label>
+            <span aria-hidden={hideAriaLabel ? true : undefined} data-item-label>
                 <Truncated data-text>{label}</Truncated>
                 {subText && <span data-sub-text>{subText}</span>}
             </span>
@@ -149,4 +183,29 @@ ListItem.Button = ListItemButton;
 
 export { ListItem };
 
+function asLogic<As extends ElementType>(as: As | undefined, props: Partial<ListItemProps>): ElementType {
+    if (as) return as;
+    if (props.href) return 'a';
+    return 'div';
+}
+
+function roleLogic(
+    existingRole: AriaRole | undefined,
+    {
+        as: As,
+        props,
+    }: {
+        as: ElementType;
+        props: Partial<ListItemProps>;
+    },
+): HTMLAttributes<HTMLElement>['role'] | undefined {
+    if (existingRole) return existingRole;
+
+    if (props.href) return As !== 'a' ? 'link' : undefined;
+
+    if (props.onClick && As !== 'button' && As !== 'label') return 'button';
+
+    return undefined;
+}
+
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/ListItem/ListItemExample.tsx

@@ -1,7 +1,19 @@
 import { ElementType } from 'react';
 import { ListItem, ListItemProps } from './ListItem';
 import { createExampleChildElement } from '-/utils/createExampleChildElement';
-import { ComponentExampleFn } from '-/utils/demo';
+import { ComponentExampleFn, Preset } from '-/utils/demo';
+
+export const presets: Preset<ListItemProps>[] = [
+    {
+        label: 'Long Label',
+        propState: {
+            label: 'This is a really long label that should be truncated if it exceeds the width of the ListItem',
+            subText: 'See below for other leading and trailing examples',
+            trailing: 'Checkbox',
+            leading: 'Avatar',
+        },
+    },
+];
 
 export const ListItemExample: ComponentExampleFn<ListItemProps> = ({ action, setState }) => ({
     render: ({ props, id }) => {
@@ -26,16 +38,5 @@ export const ListItemExample: ComponentExampleFn<ListItemProps> = ({ action, set
 
         return <ListItem {...props} as={as} leading={leading.element} trailing={trailing.element} />;
     },
-    presets: [
-        {
-            value: 'long-label',
-            label: 'Long Label',
-            propState: {
-                label: 'This is a really long label that should be truncated if it exceeds the width of the ListItem',
-                subText: 'See below for other leading and trailing examples',
-                trailing: 'Checkbox',
-                leading: 'Avatar',
-            },
-        },
-    ],
+    presets,
 });

package/src/components/ListItem/list-item.scss

@@ -3,6 +3,7 @@
     width: 100%;
     user-select: none;
     color: var(--foreground-neutral-on-surface);
+    background-color: var(--surface-neutral-t1-base);
     height: 100%;
     overflow: hidden;
     min-height: var(--list-item-height);
@@ -10,7 +11,6 @@
     gap: var(--spacing-sizing-03);
     padding: var(--spacing-sizing-02);
     justify-items: stretch;
-    background: unset;
     border: unset;
     margin: unset;
     text-decoration: unset;
@@ -25,26 +25,21 @@
         }
     }
 
-    &[data-action] {
+    &[data-action],
+    &:is(label) {
+        &[data-active],
         [data-pseudo='hover'] &,
         &:hover {
             background-color: var(--interactions-neutral-hover-opacity);
         }
 
         [data-pseudo='active'] &,
-        &[data-active],
+        // pressed state
         &:active {
             background-color: var(--interactions-neutral-press-opacity);
         }
     }
 
-    &[aria-disabled] {
-        [data-text],
-        [data-sub-text] {
-            color: var(--foreground-neutral-disabled-on-surface);
-        }
-    }
-
     [data-leading],
     [data-item-label],
     [data-trailing] {
@@ -83,6 +78,13 @@
         }
     }
 
+    &[aria-disabled] {
+        [data-text],
+        [data-sub-text] {
+            color: var(--foreground-neutral-disabled-on-surface);
+        }
+    }
+
     [data-trailing]:has(input) {
         pointer-events: none;
     }
@@ -99,6 +101,10 @@
             gap: var(--spacing-sizing-02);
         }
     }
+
+    &[aria-selected='true'] {
+        background-color: var(--surface-brand-primary-highlight);
+    }
 }
 
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */