@bspk/ui 1.1.34 → 1.3.0

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 */

package/src/components/Table/TableExample.tsx

@@ -0,0 +1,138 @@
+import { TableProps } from './Table';
+import { TableRow, TableSize } from './utils';
+import { Tag, TagProps } from '-/components/Tag';
+import { Truncated } from '-/components/Truncated';
+import { COMPONENT_PHASE_COLORS } from '-/constants/phases';
+import { ComponentPhase } from '-/types/meta';
+import { ComponentExample, ComponentExampleFn, Preset } from '-/utils/demo';
+
+const tableSizeToTagSize: Record<TableSize, TagProps['size']> = {
+    large: 'small',
+    medium: 'x-small',
+    small: 'x-small',
+    'x-large': 'small',
+};
+
+export const TableExample: ComponentExampleFn<TableProps<TableRow>> = ({
+    componentsMeta,
+}): ComponentExample<TableProps<TableRow>> => {
+    return {
+        containerStyle: { width: '100%' },
+        defaultState: {
+            data: [
+                {
+                    id: '1',
+                    firstName: 'James',
+                    lastName: 'Kirk',
+                    email: 'james.kirk@starfleet.gov',
+                    serviceYears: 5,
+                },
+                {
+                    id: '2',
+                    firstName: 'Jean-Luc',
+                    lastName: 'Picard',
+                    email: 'jean-luc.picard@starfleet.gov',
+                    serviceYears: 9,
+                },
+                {
+                    id: '3',
+                    firstName: 'Benjamin',
+                    lastName: 'Sisko',
+                    email: 'benjamin.sisko@starfleet.gov',
+                    serviceYears: 6,
+                },
+                {
+                    id: '4',
+                    firstName: 'Kathryn',
+                    lastName: 'Janeway',
+                    email: 'kathryn.janeway@starfleet.gov',
+                    serviceYears: 7,
+                },
+            ],
+            columns: [
+                {
+                    key: 'firstName',
+                    label: 'First Name',
+                    width: '1fr',
+                    sort: 'string',
+                },
+                {
+                    key: 'lastName',
+                    label: 'Last Name',
+                    width: '1fr',
+                    sort: 'string',
+                },
+                {
+                    key: 'email',
+                    label: 'Email',
+                    width: '1fr',
+                },
+                {
+                    key: 'serviceYears',
+                    label: 'Service Years',
+                    align: 'right',
+                    width: '1fr',
+                    sort: 'number',
+                },
+            ],
+        },
+        presets: [
+            {
+                label: 'Large data set',
+                propState: {
+                    title: 'Components',
+                    columns: [
+                        {
+                            key: 'name',
+                            label: 'Name',
+                            width: '1fr',
+                            sort: 'string',
+                        },
+                        {
+                            key: 'phase',
+                            label: 'Phase',
+                            width: '1fr',
+                            align: 'center',
+                            sort: 'string',
+                            formatter: ({ phase }, size) => (
+                                <Tag
+                                    color={COMPONENT_PHASE_COLORS[phase]}
+                                    label={phase}
+                                    size={tableSizeToTagSize[size]}
+                                />
+                            ),
+                        },
+                        {
+                            key: 'cssLines',
+                            label: 'CSS Lines',
+                            width: '1fr',
+                            sort: 'number',
+                            align: 'right',
+                        },
+                        {
+                            key: 'dependencies',
+                            label: 'Dependencies',
+                            width: '1fr',
+                        },
+                        {
+                            key: 'description',
+                            label: 'Description',
+                            width: 'auto',
+                            formatter: (row) => <Truncated style={{ maxWidth: '200px' }}>{row.description}</Truncated>,
+                        },
+                    ],
+                    data: componentsMeta
+                        .filter((c) => c.phase !== 'Utility')
+                        .map((c) => ({
+                            id: c.slug,
+                            name: c.name,
+                            phase: c.phase,
+                            dependencies: c.dependencies,
+                            description: c.description || '',
+                            cssLines: c.css.split('\n').length - 1,
+                        })),
+                },
+            } as Preset<TableProps<TableRow & { phase: ComponentPhase; description: string }>>,
+        ],
+    };
+};

package/src/components/Table/table.scss

@@ -1,46 +1,248 @@
 [data-bspk='table'] {
-    width: 100%;
+    /*! --template-columns: is set via inline style */
+
+    --white-background: var(--surface-neutral-t1-base);
+    --grey-background: var(--surface-neutral-t2-lowest);
+    --icon-size: var(--spacing-sizing-05);
+
+    min-width: 100%;
+    overflow: auto hidden;
     border-collapse: separate;
     text-align: left;
     border-spacing: 2rem 0.125rem;
-    display: grid;
     color: var(--foreground-neutral-on-surface);
     font: var(--labels-base);
     border-radius: var(--radius-md);
     border: 1px solid var(--stroke-neutral-low);
+    background: var(--white-background);
 
-    [data-cell] {
-        display: flex;
-        flex-direction: column;
-        gap: var(--spacing-sizing-02);
-        padding: var(--spacing-sizing-04);
-        background-color: var(--surface-neutral-t1-base);
-        border-bottom: var(--stroke-neutral-low) solid 1px;
-        font: var(--labels-small);
-
-        p {
-            margin: 0;
-            padding: 0;
+    /* [data-size='medium'] */
+    --min-height: var(--spacing-sizing-10);
+    --padding-y: var(--spacing-sizing-02);
+
+    &[data-size='x-large'] {
+        --min-height: var(--spacing-sizing-14);
+        --padding-y: var(--spacing-sizing-04);
+    }
+
+    &[data-size='large'] {
+        --min-height: var(--spacing-sizing-12);
+        --padding-y: var(--spacing-sizing-03);
+    }
+
+    &[data-size='small'] {
+        --min-height: var(--spacing-sizing-08);
+        --padding-y: var(--spacing-sizing-01);
+    }
+
+    [data-scroll-container] {
+        width: fit-content;
+        min-width: 100%;
+        border-radius: var(--radius-md);
+    }
+
+    table {
+        display: grid;
+        grid-template-columns: var(--template-columns);
+        border-collapse: collapse;
+        min-width: 100%;
+        user-select: none;
+
+        tr,
+        tbody,
+        thead {
+            display: contents;
+        }
+
+        caption {
+            grid-column: 1 / -1;
+            background: var(--grey-background);
+            border-bottom: 1px solid var(--stroke-neutral-low);
+            display: flex;
+            flex-direction: row;
+            justify-content: start;
+            align-items: center;
+            font: var(--labels-small);
+            min-height: var(--min-height);
+            padding: calc(var(--padding-y) + 2px) var(--spacing-sizing-04);
+            overflow: hidden;
+        }
+
+        th {
+            display: flex;
+            min-height: var(--min-height);
+            overflow: hidden;
+            flex-direction: row;
+            background: var(--grey-background);
+            font: var(--labels-small);
+            border-bottom: 1px solid var(--stroke-neutral-base);
+            white-space: nowrap;
+            z-index: 1;
+            position: relative;
+
+            &:not([data-sortable]) {
+                padding: calc(var(--padding-y) + 2px) var(--spacing-sizing-04);
+                pointer-events: none;
+            }
+
+            &[data-sortable] {
+                button {
+                    display: flex;
+                    min-height: var(--min-height);
+                    border: none;
+                    overflow: hidden;
+                    flex-direction: row;
+                    padding: calc(var(--padding-y) + 2px) var(--spacing-sizing-04);
+                    background: var(--grey-background);
+                    align-items: center;
+                    justify-content: space-between;
+                    gap: var(--spacing-sizing-02);
+                    width: 100%;
+                    cursor: pointer;
+                    font: inherit;
+                    outline: none;
+                    position: relative;
+
+                    &:hover {
+                        background:
+                            linear-gradient(
+                                var(--interactions-neutral-hover-opacity),
+                                var(--interactions-neutral-hover-opacity)
+                            ),
+                            linear-gradient(var(--grey-background), var(--grey-background));
+                    }
+
+                    &:active {
+                        background:
+                            linear-gradient(
+                                var(--interactions-neutral-press-opacity),
+                                var(--interactions-neutral-press-opacity)
+                            ),
+                            linear-gradient(var(--grey-background), var(--grey-background));
+                    }
+
+                    [data-sort-icon] {
+                        display: flex;
+                        flex-direction: row;
+                        align-items: center;
+
+                        svg {
+                            width: var(--icon-size);
+                        }
+                    }
+
+                    &:focus-visible {
+                        position: absolute;
+                        z-index: var(--z-index-focus);
+                        inset: 0;
+                        outline: solid 2px var(--stroke-neutral-focus);
+                        outline-offset: -2px;
+                    }
+                }
+            }
+
+            &[data-align='right'] {
+                align-items: flex-end;
+
+                button {
+                    justify-content: flex-end;
+                }
+            }
+
+            &[data-align='center'] {
+                align-items: center;
+
+                button {
+                    justify-content: center;
+                }
+            }
+
+            &[data-align='left'] {
+                align-items: flex-start;
+
+                button {
+                    justify-content: space-between;
+                }
+            }
+        }
+
+        td {
+            display: flex;
+            min-height: var(--min-height);
+            overflow: hidden;
+            padding: calc(var(--padding-y) + 2px) var(--spacing-sizing-04);
+            flex-direction: column;
             font: var(--body-small);
+
+            &[data-align='right'] {
+                align-items: flex-end;
+            }
+
+            &[data-align='center'] {
+                align-items: center;
+            }
+
+            &[data-align='left'] {
+                align-items: flex-start;
+            }
+
+            &[data-valign='top'] {
+                justify-content: flex-start;
+            }
+
+            &[data-valign='bottom'] {
+                justify-content: flex-end;
+            }
+
+            &[data-valign='center'] {
+                justify-content: center;
+            }
+
+            p {
+                margin: 0;
+                padding: 0;
+                font: var(--body-small);
+            }
+
+            &[data-action]:hover {
+                background:
+                    linear-gradient(
+                        var(--interactions-neutral-hover-opacity),
+                        var(--interactions-neutral-hover-opacity)
+                    ),
+                    linear-gradient(var(--white-background), var(--white-background));
+            }
+        }
+
+        tr:nth-child(even) td {
+            background: var(--grey-background);
+
+            &[data-action]:hover {
+                background:
+                    linear-gradient(
+                        var(--interactions-neutral-hover-opacity),
+                        var(--interactions-neutral-hover-opacity)
+                    ),
+                    linear-gradient(var(--grey-background), var(--grey-background));
+            }
         }
     }
 
-    [data-head] {
+    [data-pagination] {
         display: flex;
-        align-items: center;
         flex-direction: row;
-        border-bottom: 1px solid var(--stroke-neutral-base);
-        background: var(--surface-neutral-t2-lowest);
-        height: var(--spacing-sizing-10);
-        padding: 0 var(--spacing-sizing-03);
-        font: var(--labels-base);
-
-        &[data-head='first'] {
-            border-top-left-radius: var(--radius-md);
+        justify-content: space-between;
+        align-items: center;
+        padding: var(--spacing-sizing-03) var(--spacing-sizing-04);
+        width: 100%;
+
+        [data-pagination-label] {
+            font: var(--body-small);
+            min-width: fit-content;
         }
 
-        &[data-head='last'] {
-            border-top-right-radius: var(--radius-md);
+        [data-bspk='pagination'] {
+            flex-grow: 0;
         }
     }
 }