@bspk/ui 1.1.34 → 1.3.0

package/src/components/ListItem/ListItem.tsx

@@ -1,77 +1,95 @@
-import { AnchorHTMLAttributes, ElementType, ReactNode, AriaRole } from 'react';
-
-import { CommonProps, ElementProps, SetRef } from '-';
-import { ButtonProps, Button } from '-/components/Button';
-import { Truncated } from '-/components/Truncated';
-import { ChildElement, getChildrenElements } from '-/utils/children';
-import { useErrorLogger } from '-/utils/errors';
 import './list-item.scss';
-
-export const LEADING_COMPONENTS = Object.freeze(['Icon', 'Img', 'Avatar']);
-
-export const TRAILING_COMPONENTS = Object.freeze([
-    'ListItemButton',
-    'Checkbox',
-    'Icon',
-    'Radio',
-    'Switch',
-    'Tag',
-    'Txt',
-    'string',
-]);
-
-export type ListItemProps<As extends ElementType = 'div', T = HTMLElement> = CommonProps<
-    'active' | 'disabled' | '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>;
-    /**
-     * Whether the ListItem is selected.
-     *
-     * @default false
-     */
-    selected?: boolean;
-};
+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';
+
+export type ListItemProps<As extends ElementType = ElementType> = CommonProps<
+    'active' | 'disabled' | 'owner' | 'readOnly'
+> &
+    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
@@ -81,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.
  *
@@ -102,132 +120,92 @@ export type ListItemProps<As extends ElementType = 'div', T = HTMLElement> = Com
  *         );
  *     }
  *
- * @subComponents ListItemButton
- *
  * @name ListItem
- * @phase DesignReview
+ * @phase UXReview
  */
-function ListItem<As extends ElementType = 'div', T = HTMLElement>({
+function ListItem<As extends ElementType = ElementType>({
+    active,
     as,
     disabled,
-    leading: leadingProp,
-    trailing: trailingProp,
+    innerRef,
     label,
-    subText,
-    active,
+    leading,
     readOnly,
-    innerRef,
-    selected = false,
+    owner,
     role: roleProp,
+    subText,
+    trailing,
+    id: idProp,
+    'aria-label': ariaLabel,
+    'aria-selected': ariaSelected,
+    hideAriaLabel,
     ...props
-}: ElementProps<ListItemProps<As, T>, As>) {
-    let As: ElementType = as || 'div';
-    const role: AriaRole[] = ['option', roleProp || 'listitem'];
-    const AsInner: ElementType = 'span';
-
-    const { leading, trailing } = useChildren(leadingProp, trailingProp);
-
-    if (!label) return;
-
-    if (props.href) As = 'a';
-
-    if (trailing?.name) {
-        // if trailing is a ListItemButton and As is a button, change As to div
-        if (trailing?.name === 'ListItemButton') As = 'div';
+}: ElementProps<ListItemProps<As>, As>) {
+    const id = useId(idProp);
 
-        if (['Checkbox', 'Radio', 'Switch'].includes(trailing.name)) {
-            As = 'div';
-            role.push('button');
-        }
-    }
+    if (!label) return null;
 
-    if (!As && 'onClick' in props) As = 'button';
-
-    const actionable = ('onClick' in props || 'href' in props) && !disabled && !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' ? undefined : label}
-            aria-selected={selected || undefined}
+            aria-label={ariaLabel || undefined}
+            aria-selected={ariaSelected}
             data-action={actionable || undefined}
             data-active={active || undefined}
             data-bspk="list-item"
-            data-component={leading?.name || undefined}
+            data-bspk-owner={owner || undefined}
             data-readonly={readOnly || undefined}
+            id={id}
             ref={innerRef}
-            role="option"
-            tabIndex={0}
+            role={role}
+            tabIndex={props.tabIndex || (actionable ? 0 : undefined)}
         >
-            <AsInner data-inner>
-                {leading && (
-                    <span data-component={leading.name} data-leading>
-                        {leading.child}
-                    </span>
-                )}
-                <span data-item-label>
-                    <Truncated data-text>{label}</Truncated>
-                    {subText && <span data-sub-text>{subText}</span>}
+            {leading && (
+                <span aria-hidden data-leading>
+                    {leading}
                 </span>
-                {trailing && (
-                    <span data-component={trailing.name} data-trailing>
-                        {trailing.child}
-                    </span>
-                )}
-            </AsInner>
+            )}
+            <span aria-hidden={hideAriaLabel ? true : undefined} data-item-label>
+                <Truncated data-text>{label}</Truncated>
+                {subText && <span data-sub-text>{subText}</span>}
+            </span>
+            {trailing && <span data-trailing>{trailing}</span>}
         </As>
     );
 }
-ListItem.bspkName = 'ListItem';
 
-/** A button that can be used as a trailing element in a ListItem. */
-// eslint-disable-next-line react/no-multi-comp
-function ListItemButton({ label, icon, ...buttonProps }: Pick<ButtonProps, 'icon' | 'label' | 'onClick'>) {
-    return <Button icon={icon} label={label} showLabel={false} {...buttonProps} size="large" variant="tertiary" />;
-}
-ListItemButton.bspkName = 'ListItemButton';
 ListItem.Button = ListItemButton;
 
 export { ListItem };
 
-function useChildren(
-    leadingProp: ReactNode,
-    trailingProp: ReactNode,
-): {
-    leading?: { child: ReactNode; name: string } | null;
-    trailing?: { child: ReactNode; name: string } | null;
-} {
-    const { logError } = useErrorLogger();
-
-    let leading: ChildElement | null = getChildrenElements(leadingProp)[0] || null;
-
-    const trailingElements = getChildrenElements(trailingProp);
+function asLogic<As extends ElementType>(as: As | undefined, props: Partial<ListItemProps>): ElementType {
+    if (as) return as;
+    if (props.href) return 'a';
+    return 'div';
+}
 
-    let trailing: ChildElement | null = trailingElements[0] || null;
+function roleLogic(
+    existingRole: AriaRole | undefined,
+    {
+        as: As,
+        props,
+    }: {
+        as: ElementType;
+        props: Partial<ListItemProps>;
+    },
+): HTMLAttributes<HTMLElement>['role'] | undefined {
+    if (existingRole) return existingRole;
 
-    if (leading) {
-        const valid = LEADING_COMPONENTS.includes(leading.name);
-        if (!valid) leading = null;
-        logError(
-            !valid,
-            `ListItem - Leading child is invalid. Must be one of:${LEADING_COMPONENTS} Elements: ${leading?.name || 'None'}`,
-        );
-    }
+    if (props.href) return As !== 'a' ? 'link' : undefined;
 
-    if (trailing) {
-        const valid = TRAILING_COMPONENTS.includes(trailing.name);
-        if (!valid) trailing = null;
-        logError(
-            !valid,
-            `ListItem - Trailing child is invalid. Must be one of:${TRAILING_COMPONENTS} Elements: ${trailing?.name || 'None'}`,
-        );
-    }
+    if (props.onClick && As !== 'button' && As !== 'label') return 'button';
 
-    return {
-        leading,
-        trailing,
-    };
+    return undefined;
 }
 
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/ListItem/ListItemButton.tsx

@@ -0,0 +1,6 @@
+import { ButtonProps, Button } from '-/components/Button';
+
+// A button that can be used as a trailing element in a ListItem.
+export function ListItemButton({ label, icon, ...buttonProps }: Pick<ButtonProps, 'icon' | 'label' | 'onClick'>) {
+    return <Button icon={icon} iconOnly label={label} {...buttonProps} size="large" variant="tertiary" />;
+}

package/src/components/ListItem/ListItemExample.tsx

@@ -1,92 +1,42 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */ import { SvgContentCopy } from '@bspk/icons/ContentCopy';
-import { SvgDiamond } from '@bspk/icons/Diamond';
-
-import { Avatar } from '-/components/Avatar';
-import { Checkbox } from '-/components/Checkbox';
-import { Img } from '-/components/Img';
-import { Radio } from '-/components/Radio';
-import { Switch } from '-/components/Switch';
-import { Tag } from '-/components/Tag';
-import { Txt } from '-/components/Txt';
-import { ComponentExampleFn, DemoAction, DemoSetState } from '-/utils/demo';
-
-import { ListItem, ListItemProps } from '.';
+import { ElementType } from 'react';
+import { ListItem, ListItemProps } from './ListItem';
+import { createExampleChildElement } from '-/utils/createExampleChildElement';
+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, Component, id }) => {
-        return (
-            <Component
-                {...props}
-                leading={createChildrenElement(props, 'leading', setState, action, id)}
-                trailing={createChildrenElement(props, 'trailing', setState, action, id)}
-            />
-        );
+    render: ({ props, id }) => {
+        const leading = createExampleChildElement({
+            exampleState: props,
+            name: 'leading',
+            setState,
+            action,
+            id,
+        });
+        const trailing = createExampleChildElement({
+            exampleState: props,
+            name: 'trailing',
+            setState,
+            action,
+            id,
+        });
+
+        let as: ElementType = props.as || 'div';
+
+        if (trailing.componentName && ['Checkbox', 'Radio', 'Switch'].includes(trailing.componentName)) as = 'label';
+
+        return <ListItem {...props} as={as} leading={leading.element} trailing={trailing.element} />;
     },
-    presets: [
-        // really long label
-        {
-            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',
-                trailing: 'Checkbox',
-                leading: 'Avatar',
-            },
-        },
-    ],
+    presets,
 });
-
-export const createChildrenElement = (
-    state: Record<string, any>,
-    name: string,
-    setState: DemoSetState,
-    action: DemoAction,
-    id?: string,
-) => {
-    const componentName = state[name];
-
-    if (componentName === 'Checkbox' || componentName === 'Radio' || componentName === 'Switch') {
-        let As: typeof Checkbox | typeof Radio | typeof Switch = Checkbox;
-        if (componentName === 'Radio') As = Radio;
-        else if (componentName === 'Switch') As = Switch;
-
-        const toggleName = `data-${name}-toggle-${id}`;
-        return (
-            <As
-                aria-label={`${componentName} demo`}
-                checked={state[toggleName]}
-                disabled={state.disabled}
-                name={`${name}-toggle`}
-                onChange={(checked: boolean) => {
-                    setState({ [toggleName]: checked });
-                }}
-                onClick={() => action(`${name} ${componentName} clicked`)}
-                readOnly={state.readOnly}
-                value={`${name}-${componentName}`}
-            />
-        );
-    }
-
-    if (componentName === 'ListItemButton')
-        return (
-            <ListItem.Button
-                icon={<SvgContentCopy />}
-                label="LI Button"
-                onClick={() => action('ListItem button clicked')}
-            />
-        );
-
-    if (componentName === 'Img') return <Img alt="placeholder" src="/placeholder.svg" />;
-
-    if (componentName === 'Avatar') return <Avatar name="List Item" showTooltip={false} />;
-
-    if (componentName === 'Tag') {
-        return <Tag>Tag</Tag>;
-    }
-
-    if (componentName === 'Txt') return <Txt>Text</Txt>;
-
-    if (componentName === 'Icon') return <SvgDiamond />;
-
-    return null;
-};

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

@@ -1,26 +1,19 @@
-body[data-bspk] a[data-bspk='list-item'] {
-    color: unset !important;
-    text-decoration: !important;
-    font: !important;
-}
-
 [data-bspk='list-item'] {
-    display: block;
+    display: flex;
     width: 100%;
-    padding: 0 var(--spacing-sizing-02);
-    background: unset;
+    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);
+    flex-direction: row;
+    gap: var(--spacing-sizing-03);
+    padding: var(--spacing-sizing-02);
+    justify-items: stretch;
     border: unset;
     margin: unset;
     text-decoration: unset;
-    user-select: none;
-    color: var(--foreground-neutral-on-surface);
-
-    &:is(a),
-    &:is(button),
-    &[onclick],
-    &[role='button'] {
-        cursor: pointer;
-    }
 
     [data-pseudo='focus'] &,
     &:focus-visible,
@@ -32,38 +25,21 @@ body[data-bspk] a[data-bspk='list-item'] {
         }
     }
 
-    &[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-inner] {
-        height: 100%;
-        width: 100%;
-        overflow: hidden;
-        min-height: var(--list-item-height);
-        display: flex;
-        flex-direction: row;
-        gap: var(--spacing-sizing-03);
-        padding: var(--spacing-sizing-02) 0;
-        justify-items: stretch;
-    }
-
     [data-leading],
     [data-item-label],
     [data-trailing] {
@@ -102,11 +78,18 @@ body[data-bspk] a[data-bspk='list-item'] {
         }
     }
 
+    &[aria-disabled] {
+        [data-text],
+        [data-sub-text] {
+            color: var(--foreground-neutral-disabled-on-surface);
+        }
+    }
+
     [data-trailing]:has(input) {
         pointer-events: none;
     }
 
-    [data-component='Img'] > img {
+    img {
         height: 36px;
         width: 36px;
         max-width: unset;
@@ -118,6 +101,10 @@ body[data-bspk] a[data-bspk='list-item'] {
             gap: var(--spacing-sizing-02);
         }
     }
+
+    &[aria-selected='true'] {
+        background-color: var(--surface-brand-primary-highlight);
+    }
 }
 
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */