@bspk/ui 1.1.34 → 1.2.0

package/src/components/TabList/TabList.tsx

@@ -0,0 +1,239 @@
+import { Fragment, ReactNode, useMemo } from 'react';
+
+import { Badge, BadgeProps } from '-/components/Badge';
+import { Tooltip } from '-/components/Tooltip';
+import { Truncated } from '-/components/Truncated';
+import { useId } from '-/hooks/useId';
+import { useKeyNavigation } from '-/hooks/useKeyNavigation';
+import { ElementProps } from '-/types/common';
+
+import './tab-list.scss';
+
+const TAB_BADGE_SIZES: Record<TabSize, BadgeProps['size']> = {
+    large: 'small',
+    medium: 'x-small',
+    small: 'x-small',
+};
+
+export type TabSize = 'large' | 'medium' | 'small';
+
+export type TabOption = {
+    /**
+     * The label of the tab. This is the text that will be displayed on the tab.
+     *
+     * @required
+     */
+    label: string;
+    /**
+     * Determines if the element is [disabled](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled).
+     *
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * The value of the tab sent to onChange when selected.
+     *
+     * If not provided, the label will be used as the value.
+     */
+    value: string;
+    /**
+     * The icon to display on the left side of the tab.
+     *
+     * @type BspkIcon
+     */
+    icon?: ReactNode;
+    /**
+     * The icon to display on the left side of the tab when the tab is currently selected.
+     *
+     * @type BspkIcon
+     */
+    iconSelected?: ReactNode;
+    /** The badge count to display on the tab */
+    badge?: number;
+};
+
+const optionId = (id: string, index: number) => `${id}-item-${index + 1}`;
+
+export type TabListProps<O extends TabOption = TabOption> = {
+    /**
+     * The tabs to display.
+     *
+     * If **less than 2** items are provided, the component will not render.
+     *
+     * @example
+     *     [
+     *         { value: '1', label: 'Option 1' },
+     *         { value: '2', label: 'Disabled 2 ', disabled: true },
+     *         { value: '3', label: 'Option 3' },
+     *     ];
+     *
+     * @type Array<TabOption>
+     * @required
+     */
+    options: O[];
+    /**
+     * The value of the selected tab.
+     *
+     * @example
+     *     1;
+     *
+     * @required
+     */
+    value: TabOption['value'];
+    /**
+     * The function to call when the tab is clicked.
+     *
+     * @required
+     */
+    onChange: (tabValue: string) => void;
+    /**
+     * The size of the tabs.
+     *
+     * @default medium
+     */
+    size?: TabSize;
+    /**
+     * When 'fill' the options will fill the width of the container. When 'hug', the options will be as wide as their
+     * content.
+     *
+     * @default hug
+     */
+    width?: 'fill' | 'hug';
+    /**
+     * The label for the tab utility, used for accessibility.
+     *
+     * @required
+     */
+    label: string;
+    /** The id of the tab utility, used for accessibility. */
+    id?: string;
+    /**
+     * Determines if the labels of the options should be displayed. If icons are not provided for every option this is
+     * ignored and labels are shown.
+     *
+     * @default false
+     */
+    iconsOnly?: boolean;
+};
+
+/**
+ * Navigation tool that organizes content across different screens and views.
+ *
+ * See TabGroup or SegmentedControl for examples.
+ *
+ * @example
+ *     import { useState } from 'react';
+ *     import { TabList } from '@bspk/ui/TabList';
+ *
+ *     export function Example() {
+ *         const [selectedTab, setSelectedTab] = useState<string>();
+ *
+ *         return (
+ *             <TabList
+ *                 onChange={setSelectedTab}
+ *                 options={[
+ *                     { value: '1', label: 'Option 1' },
+ *                     { value: '2', label: 'Option 2' },
+ *                     { value: '3', label: 'Option 3' },
+ *                 ]}
+ *                 value={selectedTab}
+ *             />
+ *         );
+ *     }
+ *
+ * @name TabList
+ * @phase Utility
+ */
+export function TabList({
+    //
+    onChange,
+    value: valueProp,
+    size = 'medium',
+    options: optionsProp,
+    width = 'hug',
+    label,
+    id: idProp,
+    iconsOnly: iconsOnlyProp = false,
+    ...containerProps
+}: ElementProps<TabListProps, 'ul'>) {
+    const id = useId(idProp);
+    const options = useMemo(() => {
+        if (!Array.isArray(optionsProp)) return [];
+        return optionsProp.map((opt, index) => ({ ...opt, id: optionId(id, index) }));
+    }, [id, optionsProp]);
+
+    const value = useMemo(() => {
+        const option = options.find((opt) => opt.value === valueProp);
+        return option ? option.value : options[0]?.value;
+    }, [options, valueProp]);
+
+    const { handleKeyDown, activeElementId, setElements, setActiveElementId } = useKeyNavigation({
+        onSelect: (nextActiveId) => {
+            onChange(options.find((opt) => opt.id === nextActiveId)?.value || '');
+        },
+    });
+
+    // If all options have icons, we can hide the labels
+    const iconsOnly = iconsOnlyProp === true && options.every((item) => item.icon && item.label);
+
+    const handleClick = (item: (typeof options)[number]) => (e: React.MouseEvent<HTMLLIElement>) => {
+        setTimeout(() => (e.target as HTMLElement).focus(), 100);
+        setActiveElementId(item.id);
+        if (!item.disabled) onChange(item.value);
+    };
+
+    return (
+        <ul
+            {...containerProps}
+            aria-label={label}
+            data-bspk-utility="tab-list"
+            data-hug={width === 'hug' || undefined}
+            data-size={size}
+            data-width={width}
+            id={id}
+            ref={(node) => {
+                if (node) {
+                    const newElements = (Array.from(node.children) as HTMLElement[]).filter(
+                        (el) => !el.hasAttribute('aria-disabled'),
+                    );
+                    setElements(newElements);
+                }
+            }}
+            role="tablist"
+        >
+            {options.map((item) => {
+                const isSelected = item.value === value;
+                const icon = isSelected ? item.iconSelected : item.icon;
+                return (
+                    <Fragment key={item.id}>
+                        <Tooltip disabled={!iconsOnly} label={item.label} placement="top">
+                            {(triggerProps) => (
+                                <li
+                                    aria-controls={id}
+                                    aria-disabled={item.disabled || undefined}
+                                    aria-selected={isSelected || undefined}
+                                    data-active={activeElementId === item.id || undefined}
+                                    data-value={item.value}
+                                    id={item.id}
+                                    onClick={handleClick(item)}
+                                    onKeyDown={handleKeyDown}
+                                    role="tab"
+                                    tabIndex={isSelected ? 0 : -1}
+                                    {...triggerProps}
+                                >
+                                    {icon && <span aria-hidden="true">{icon}</span>}
+                                    {!iconsOnly && <Truncated data-label>{item.label}</Truncated>}
+                                    {item.badge && !item.disabled && (
+                                        <Badge count={item.badge} size={TAB_BADGE_SIZES[size]} />
+                                    )}
+                                </li>
+                            )}
+                        </Tooltip>
+                    </Fragment>
+                );
+            })}
+        </ul>
+    );
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/TabList/TabListExample.tsx

@@ -0,0 +1,7 @@
+import { TabListProps } from './TabList';
+import { ComponentExample } from '-/utils/demo';
+
+export const TabListExample: ComponentExample<TabListProps> = {
+    containerStyle: { width: '100%' },
+    render: ({ props, Component }) => <Component {...props} />,
+};

package/src/components/TabList/index.tsx

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

package/src/components/TabList/tab-list.scss

@@ -0,0 +1,76 @@
+ul[data-bspk-utility='tab-list'] {
+    --item-flex-grow: 0;
+
+    display: flex;
+    flex-direction: row;
+    list-style: none;
+    width: fit-content;
+    height: var(--height);
+    font: var(--font);
+
+    &[data-width='fill'] {
+        align-items: stretch;
+        width: 100%;
+
+        --item-flex-grow: 1;
+    }
+
+    --icon-size: var(--spacing-sizing-05);
+    --font: var(--labels-base);
+    --height: var(--spacing-sizing-10);
+
+    &[data-size='small'] {
+        --font: var(--labels-small);
+        --height: var(--spacing-sizing-08);
+        --icon-size: var(--spacing-sizing-04);
+    }
+
+    &[data-size='large'] {
+        --font: var(--labels-large);
+        --height: var(--spacing-sizing-12);
+        --icon-size: var(--spacing-sizing-06);
+    }
+
+    &:has(:focus-visible) {
+        outline: 2px solid var(--stroke-neutral-focus);
+        outline-offset: 2px;
+    }
+
+    li {
+        list-style: none;
+        cursor: pointer;
+        flex-grow: var(--item-flex-grow);
+        font: var(--font);
+        white-space: nowrap;
+        outline: none;
+        user-select: none;
+        display: flex;
+        flex-direction: row;
+        align-items: center;
+        justify-content: center;
+        gap: var(--spacing-sizing-02);
+
+        &[aria-disabled] {
+            cursor: not-allowed;
+        }
+
+        span {
+            display: flex;
+            flex-direction: row;
+            align-items: center;
+            justify-content: center;
+            pointer-events: none;
+        }
+
+        [data-label][style] {
+            justify-content: left;
+            max-width: 200px !important;
+        }
+
+        svg {
+            width: var(--icon-size);
+        }
+    }
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Table/Footer.tsx

@@ -0,0 +1,40 @@
+import { Pagination } from '-/components/Pagination';
+
+export function TableFooter({
+    pageIndex,
+    pageSize,
+    setPageIndex,
+    totalRows,
+    id,
+    totalPages,
+}: {
+    pageIndex: number;
+    pageSize: number;
+    setPageIndex: (newVal: number) => void;
+    totalRows: number;
+    id: string;
+    totalPages: number;
+}) {
+    const startRow = totalRows === 0 ? 0 : pageIndex * pageSize + 1;
+    const endRow = Math.min(startRow + pageSize - 1, totalRows);
+    return (
+        <div data-pagination role="group">
+            <div data-pagination-label>
+                Showing {startRow}-{endRow} of {totalRows} results
+            </div>
+            <div data-sr-only id={`${id}-pagination-description`}>
+                <p>
+                    The buttons inside this control allow you to paginate through the data in the table above,
+                    {pageSize}
+                    rows at a time.
+                </p>
+            </div>
+            <Pagination
+                aria-labelledby={`${id}-pagination-description`}
+                numPages={totalPages}
+                onChange={(newVal) => setPageIndex(newVal - 1)}
+                value={pageIndex + 1}
+            />
+        </div>
+    );
+}

package/src/components/Table/Table.tsx

@@ -1,81 +1,209 @@
-import { ReactNode } from 'react';
-
-import { ElementProps } from '-';
-
 import './table.scss';
+import { SvgAZAscend } from '@bspk/icons/AZAscend';
+import { SvgAZDescend } from '@bspk/icons/AZDescend';
+import { AriaAttributes, useEffect, useState } from 'react';
+import { TableFooter } from './Footer';
+import { formatCell, SortOrder, TableColumn, TableRow, TableSize, useTable } from './utils';
+import { useId } from '-/hooks/useId';
+import { ElementProps } from '-/types/common';
+import { cssWithVars } from '-/utils/cwv';
 
-export type TableRow = Record<string, ReactNode>;
+const SORT_META: Record<
+    SortOrder | 'none',
+    {
+        icon: JSX.Element | null;
+        label: string;
+        aria: AriaAttributes['aria-sort'];
+    }
+> = {
+    asc: {
+        icon: <SvgAZAscend />,
+        label: 'sorted ascending',
+        aria: 'ascending',
+    },
+    desc: {
+        icon: <SvgAZDescend />,
+        label: 'sorted descending',
+        aria: 'descending',
+    },
+    none: {
+        icon: null,
+        label: 'not sorted',
+        aria: 'none',
+    },
+} as const;
 
-export type TableColumn<R extends TableRow = Record<string, ReactNode>> = {
+export type TableProps<R extends TableRow> = {
+    /**
+     * The data of the table.
+     *
+     * Array<TableRow>
+     */
+    data: R[];
     /**
-     * The key of the column. This is used to access the data in the row.
+     * The column definitions of the table.
      *
-     * @type string
+     * @type Array<TableColumn>
      */
-    key: keyof R;
+    columns: (TableColumn<R> | boolean)[];
+    /** The title of the table. */
+    title?: string;
     /**
-     * The label of the column. This is used to display the column header.
+     * The size of the table.
      *
-     * @type string
+     * @default medium
      */
-    label: string;
+    size?: TableSize;
     /**
-     * The width of the column. This is used to set the width of the column.
+     * The number of rows per page.
      *
-     * Used to set the value of
-     * [grid-template-columns](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-columns)
+     * If the number of rows exceeds the page size, pagination controls will be displayed.
      *
-     * @default 1fr
-     * @type string
+     * @default 10
      */
-    width?: string;
-};
-
-export type TableProps<R extends TableRow> = {
-    /** The data of the table. */
-    rows: R[];
-    /** The columns of the table. */
-    columns: TableColumn<R>[];
+    pageSize?: number;
 };
 
 /**
- * Component description coming soon.
+ * A container for displaying tabular data.
+ *
+ * The table supports sorting and custom column definitions.
+ *
+ * @example
+ *     import { Table } from '@bspk/ui/Table';
+ *
+ *     function Example() {
+ *         return (
+ *             <Table
+ *                 columns={[
+ *                     { key: 'state', label: 'State', width: '100px' },
+ *                     { key: 'capital', label: 'Capital', width: '1fr' },
+ *                 ]}
+ *                 data={[
+ *                     { state: 'New Jersey', capital: 'Trenton' },
+ *                     { state: 'New York', capital: 'Albany' },
+ *                     { state: 'California', capital: 'Sacramento' },
+ *                 ]}
+ *                 title="State Capitals"
+ *             />
+ *         );
+ *     }
  *
  * @name Table
- * @phase Backlog
+ * @phase UXReview
  */
-function Table<R extends TableRow>({ rows, columns, ...props }: ElementProps<TableProps<R>, 'div'>) {
+export function Table<R extends TableRow>({
+    data = [],
+    columns: columnsProp,
+    title,
+    size = 'medium',
+    pageSize = 10,
+    ...props
+}: ElementProps<TableProps<R>, 'div'>) {
+    const tableId = useId();
+    const [pageIndex, setPageIndex] = useState(0);
+    // when the length of data changes we should reset the
+    useEffect(() => setPageIndex(0), [data.length]);
+
+    const columns = columnsProp.filter((column): column is TableColumn<R> => {
+        return typeof column === 'object' && column !== null;
+    });
+    const hasPagination = data?.length > pageSize;
+
+    const { rows, sorting, toggleSorting, totalColumns, totalPages } = useTable<R>({
+        data,
+        pageIndex,
+        pageSize,
+        columns,
+    });
+
     return (
         <div
             {...props}
             data-bspk="table"
-            style={{
-                ...props.style,
-                gridTemplateColumns: columns.map((c) => `minmax(0, ${c.width || '1fr'})`).join(' '),
-            }}
+            data-has-pagination={hasPagination || undefined}
+            data-size={size || 'medium'}
+            id={tableId}
+            style={props.style}
         >
-            {columns.map((column, index, arr) => (
-                <div
-                    data-head={[index === 0 && 'first', index === arr.length - 1 && 'last'].filter(Boolean).join(' ')}
-                    key={column.key as string}
+            <div data-scroll-container>
+                <table
+                    {...props}
+                    aria-colcount={totalColumns}
+                    aria-rowcount={data.length}
+                    style={cssWithVars({
+                        '--template-columns': columns
+                            // Create a template column for each column definition
+                            ?.map((column) => `minmax(min-content, ${column.width || '1fr'})`)
+                            .join(' '),
+                    })}
                 >
-                    {column.label}
-                </div>
-            ))}
-            {rows.map((row, index, arr) => {
-                const lastRow = index === arr.length - 1 || undefined;
-                return columns.map((column) => (
-                    <div data-cell={column.key} data-row-last={lastRow} key={index + (column.key as string)}>
-                        {row[column.key]}
-                    </div>
-                ));
-            })}
+                    {title && <caption>{title}</caption>}
+                    <thead>
+                        <tr>
+                            {columns?.map((column) => {
+                                const sortMeta =
+                                    column.sort &&
+                                    SORT_META[sorting.find((s) => s.key === column.key)?.order || 'none'];
+
+                                return (
+                                    <th
+                                        aria-sort={sortMeta?.aria}
+                                        data-align={column.align}
+                                        data-sortable={!!sortMeta || undefined}
+                                        key={column.key}
+                                        scope="col"
+                                    >
+                                        {sortMeta ? (
+                                            <button onClick={() => toggleSorting(column.key)} type="button">
+                                                {column.label}
+                                                {sortMeta?.icon && (
+                                                    <span aria-hidden data-sort-icon>
+                                                        {sortMeta?.icon}
+                                                    </span>
+                                                )}
+                                                <span data-sr-only>
+                                                    <span aria-live="polite" role="status">
+                                                        {sortMeta.label}
+                                                    </span>
+                                                </span>
+                                            </button>
+                                        ) : (
+                                            column.label
+                                        )}
+                                    </th>
+                                );
+                            })}
+                        </tr>
+                    </thead>
+                    <tbody>
+                        {rows.map((row) => (
+                            <tr key={row.id}>
+                                {columns?.map((column) => (
+                                    <td
+                                        data-align={column.align || 'left'}
+                                        data-cell={column.key}
+                                        data-valign={column.valign || 'center'}
+                                        key={`${row.id}-${column.key}`}
+                                    >
+                                        {formatCell(column.formatter?.(row, size) || row[column.key])}
+                                    </td>
+                                ))}
+                            </tr>
+                        ))}
+                    </tbody>
+                </table>
+                {hasPagination && (
+                    <TableFooter
+                        id={tableId}
+                        pageIndex={pageIndex}
+                        pageSize={pageSize}
+                        setPageIndex={setPageIndex}
+                        totalPages={totalPages}
+                        totalRows={data.length}
+                    />
+                )}
+            </div>
         </div>
     );
 }
-
-Table.bspkName = 'Table';
-
-export { Table };
-
-/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */