@bspk/ui 1.1.33 → 1.2.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-medium);
+    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-medium);
+        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-medium);
+        [data-bspk='pagination'] {
+            flex-grow: 0;
         }
     }
 }

package/src/components/Table/utils.ts

@@ -0,0 +1,179 @@
+import { isValidElement, ReactNode, useMemo, useState } from 'react';
+
+const parseDateTime = (val: TableCellValue) => {
+    if (val instanceof Date) return val.getTime();
+    if (typeof val === 'string' || typeof val === 'number') return new Date(val).getTime();
+    return 0;
+};
+
+export type BuiltInColumnSorters = 'boolean' | 'date' | 'number' | 'string';
+
+const BUILT_IN_COLUMN_SORTERS: Record<BuiltInColumnSorters, TableColumnSortingFn> = {
+    string: (a: TableCellValue, b: TableCellValue) => `${a}`.localeCompare(`${b}`),
+    number: (a: TableCellValue, b: TableCellValue) => {
+        const aNum = typeof a === 'number' ? a : Number(a) || 0;
+        const bNum = typeof b === 'number' ? b : Number(b) || 0;
+        return aNum - bNum;
+    },
+    boolean: (a: TableCellValue, b: TableCellValue) => (a === b ? 0 : a ? 1 : -1),
+    date: (a: TableCellValue, b: TableCellValue) => {
+        return parseDateTime(a) - parseDateTime(b);
+    },
+} as const;
+
+export type TableSize = 'large' | 'medium' | 'small' | 'x-large';
+
+export type TableCellValue = ReactNode;
+
+export type TableRow = {
+    [key: string]: TableCellValue | TableCellValue[];
+    id: string;
+};
+
+export type TableColumnSortingFn = (a: TableCellValue, b: TableCellValue) => number;
+
+export type TableColumn<R extends TableRow> = {
+    /**
+     * The key of the column. This is used to access the data in the row.
+     *
+     * @type string
+     */
+    key: string;
+    /**
+     * The label of the column. This is used to display the column header.
+     *
+     * @type string
+     */
+    label: string;
+    /**
+     * The width of the column. This is used to set the width of the column.
+     *
+     * Used to set the value of
+     * [grid-template-columns](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-columns)
+     *
+     * @default 1fr
+     * @type string
+     */
+    width?: string;
+    /**
+     * The horizontal alignment of the column. This is used to set the text alignment of the column.
+     *
+     * @default left
+     */
+    align?: 'center' | 'left' | 'right';
+    /**
+     * The vertical alignment of the column. This is used to set the text alignment of the column.
+     *
+     * @default center
+     */
+    valign?: 'bottom' | 'center' | 'top';
+    /**
+     * The sorting function for the column.
+     *
+     * This can be a custom sorting function or one of the built-in sorting functions:
+     *
+     * `string`, `boolean`, `date`, or `number`.
+     *
+     * If unspecified, the column will not be sortable.
+     */
+    sort?: BuiltInColumnSorters | TableColumnSortingFn;
+    /**
+     * A formatter function for the cell values in the column.
+     *
+     * This function is called for each cell in the column and can be used to customize the display of the cell value.
+     */
+    formatter?: TableCellValueFormatter<R>;
+};
+
+export type TableCellValueFormatter<R extends TableRow> = (row: R, size: TableSize) => ReactNode;
+
+export type SortOrder = 'asc' | 'desc';
+
+export type SortState = { key: string; order: SortOrder }[];
+
+export const SORT_PREV_NEXT_STATE: Record<SortOrder | 'none', SortOrder | undefined> = {
+    asc: 'desc',
+    desc: undefined,
+    none: 'asc',
+};
+
+export function formatCell(value: TableCellValue): ReactNode {
+    if (isValidElement(value)) return value;
+
+    if (Array.isArray(value)) return value.map(formatCell).join(', ');
+
+    if (typeof value === 'object') {
+        // eslint-disable-next-line no-console
+        console.warn('Unexpected object value:', value);
+        return null;
+    }
+
+    return `${value}`;
+}
+
+export function useTable<R extends TableRow>({
+    data,
+    pageIndex,
+    pageSize,
+    columns,
+}: {
+    data: R[];
+    pageIndex: number;
+    pageSize: number;
+    columns?: TableColumn<R>[];
+}) {
+    const [sorting, setSorting] = useState<SortState>([]);
+
+    const filteredData = useMemo(() => {
+        let result = data;
+
+        // Apply sorting
+        if (sorting.length) {
+            result = result.sort((a, b) => {
+                for (const { key, order } of sorting) {
+                    const aValue = a[key];
+                    const bValue = b[key];
+
+                    const colSort = columns?.find((col) => col.key === key)?.sort;
+
+                    if (!colSort) continue;
+
+                    const colSortFn = typeof colSort === 'function' ? colSort : BUILT_IN_COLUMN_SORTERS[colSort];
+                    const next: number = colSortFn(aValue, bValue);
+
+                    if (next !== 0) return next * (order === 'asc' ? 1 : -1);
+                }
+
+                return 0;
+            });
+        }
+
+        // Apply pagination
+        const start = pageIndex * pageSize;
+        const end = start + pageSize;
+        result = result.slice(start, end);
+
+        return result;
+    }, [data, sorting, pageIndex, pageSize, columns]);
+
+    return {
+        rows: filteredData,
+        sorting,
+        toggleSorting: (key: string) => {
+            setSorting((prev) => {
+                const nextArr = [...prev];
+                const prevIndex = nextArr.findIndex((sort) => sort.key === key);
+                if (prevIndex !== -1) {
+                    const order = SORT_PREV_NEXT_STATE[nextArr[prevIndex].order];
+                    if (order === undefined) nextArr.splice(prevIndex, 1);
+                    else nextArr[prevIndex] = { key, order: order };
+                } else {
+                    nextArr.push({ key, order: 'asc' });
+                }
+                return nextArr;
+            });
+        },
+        totalColumns: columns?.length || 0,
+        totalPages: Math.ceil(data.length / pageSize),
+    };
+}

package/src/components/Tag/Tag.tsx

@@ -1,26 +1,16 @@
-import { ElementType, ReactNode } from 'react';
+import { Truncated } from '-/components/Truncated';
 
-import { ElementProps } from '-';
 import { ColorVariant } from '-/utils/colorVariants';
+
 import './tag.scss';
 
-export type TagProps<As extends ElementType = 'span'> = {
-    /**
-     * The element type to render as.
-     *
-     * @default span
-     * @type ElementType
-     */
-    as?: As;
+export type TagProps = {
     /**
-     * The content of the tag.
-     *
-     * @example
-     *     New;
+     * The label of the tag.
      *
      * @required
      */
-    children: ReactNode;
+    label: string;
     /**
      * The size of the tag.
      *
@@ -39,14 +29,6 @@ export type TagProps<As extends ElementType = 'span'> = {
      * @default flat
      */
     variant?: 'corner-wrap' | 'flat' | 'pill';
-    /**
-     * Whether the tag should wrap its content.
-     *
-     * (Not recommended)
-     *
-     * @default false
-     */
-    wrap?: boolean;
 };
 
 /**
@@ -56,44 +38,19 @@ export type TagProps<As extends ElementType = 'span'> = {
  *     import { Tag } from '@bspk/ui/Tag';
  *
  *     export function Example() {
- *         return (
- *             <Tag variant="flat" color="primary">
- *                 Example Tag
- *             </Tag>
- *         );
+ *         return <Tag label="Example Tag" variant="flat" color="primary" />;
  *     }
  *
  * @name Tag
- * @phase AccessibilityReview
+ * @phase UXReview
  */
-function Tag<As extends ElementType = 'span'>({
-    children,
-    as,
-    color = 'white',
-    size = 'small',
-    variant = 'flat',
-    wrap,
-    ...props
-}: ElementProps<TagProps<As>, As>) {
-    const As: ElementType = as || 'span';
-
+export function Tag({ label, color = 'white', size = 'small', variant = 'flat' }: TagProps) {
     return (
-        <As
-            {...props}
-            data-bspk="tag"
-            data-color={color}
-            data-size={size}
-            data-variant={variant}
-            data-wrap={wrap || undefined}
-        >
-            {children}
+        <span data-bspk="tag" data-color={color} data-size={size} data-variant={variant}>
+            {label && <Truncated>{label}</Truncated>}
             {variant === 'corner-wrap' && <div data-triangle />}
-        </As>
+        </span>
     );
 }
 
-Tag.bspkName = 'Tag';
-
-export { Tag };
-
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */