@sesamehr/react-design-system 2.0.0-beta.3 → 2.0.0-beta.5

package/dist/Data/Table/TableBody/TableBody.d.ts

@@ -16,5 +16,8 @@ export interface TableBodyProps extends React.ComponentPropsWithoutRef<'tbody'>
 /**
  * Styled `<tbody>`. When `draggable`, wraps rows in a dnd-kit sortable
  * context. Sortable item ids are derived from the index of each `items` entry.
+ *
+ * Virtualised, it also renders the two rows that stand in for the ones not
+ * rendered — see `Spacer` below — and refuses to be draggable at the same time.
  */
 export declare const TableBody: import('react').ForwardRefExoticComponent<TableBodyProps & import('react').RefAttributes<HTMLTableSectionElement>>;

package/dist/Data/Table/TableHead/TableHead.d.ts

@@ -1,3 +1,27 @@
 export type TableHeadProps = React.ComponentPropsWithoutRef<'thead'>;
-/** Styled `<thead>` wrapping its children in a header row. */
+/**
+ * Styled `<thead>`. Virtualised, it renders its row twice and keeps the copy on
+ * screen.
+ *
+ * A virtualised table is the one case where the table is certain to be taller
+ * than what you can see — that is what virtualising is for — and a header that
+ * scrolls away takes the column names and the select-all checkbox with it. At
+ * ten thousand rows, getting back to them means scrolling back through all of
+ * them.
+ *
+ * Neither obvious way works. `position: sticky` answers to the nearest
+ * scrolling ancestor and nothing above it, and with pinned columns that
+ * ancestor is the section that owns the horizontal scroll — a box that never
+ * moves vertically, so the header rides away with the rows. Moving the header
+ * from a scroll handler works but is always one frame behind what the
+ * compositor has already painted, which reads as the header dropping away and
+ * snapping back on every frame of a scroll.
+ *
+ * So the row is rendered twice. The one in the table stays and is hidden, still
+ * doing the two jobs only it can do: reserving the header's height and settling
+ * the column widths. The copy is positioned against an ancestor that does not
+ * scroll, so vertical scrolling does not move it and there is nothing to
+ * correct. It is the same elements rendered again rather than a cloned node, so
+ * sorting and select-all still work in the one you can see.
+ */
 export declare const TableHead: import('react').ForwardRefExoticComponent<Omit<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLTableSectionElement>, HTMLTableSectionElement>, "ref"> & import('react').RefAttributes<HTMLTableSectionElement>>;

package/dist/Data/Table/TableScrollbar/TableScrollbar.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The scrollbar a virtualised table draws for itself.
+ *
+ * Every other table in the system hides its bar: they scroll sideways, the
+ * shadows at the edges say there is more, and a bar would be chrome. A list of
+ * ten thousand rows is the opposite case — without one there is nothing to read
+ * your position from, and no way to cross the list in one gesture.
+ *
+ * The browser's own bar cannot be that thing here. It runs the full height of
+ * the scrollport, and the scrollport has to contain the header, so it always
+ * cuts across the column names. This one starts below them.
+ *
+ * It behaves the way an overlay bar does: out of the way until you scroll or
+ * reach for the edge, and gone again shortly after.
+ */
+export declare function TableScrollbar(): import("react/jsx-runtime").JSX.Element | null;
+export declare namespace TableScrollbar {
+    var displayName: string;
+}

package/dist/Data/Table/TableSelectCell/TableSelectCell.d.ts

@@ -4,6 +4,14 @@ export interface TableSelectCellProps extends Omit<React.ComponentPropsWithoutRe
     /** Usually fixed to left */
     fixed?: boolean;
     fixedOffset?: string;
+    /**
+     * Whether this row can be selected at all.
+     *
+     * On the header cell it disables select-all, which is the right thing when
+     * nothing in the table can be selected — a checkbox that ticks and then
+     * selects nothing is worse than one that says so.
+     */
+    disabled?: boolean;
     onChange?: (checked: boolean) => void;
 }
 export declare const TableSelectCell: import('react').ForwardRefExoticComponent<TableSelectCellProps & import('react').RefAttributes<HTMLTableCellElement>>;

package/dist/Data/Table/TableVirtualized/TableVirtualized.d.ts

@@ -0,0 +1,45 @@
+import { TableComponentProps } from '../Table.tsx';
+import { UseTableVirtualReturn } from '../hooks/useTableVirtual/useTableVirtual.types.ts';
+export type TableVirtualizedProps<TData = unknown> = TableComponentProps<TData> & {
+    /**
+     * What `useTableVirtual()` returned.
+     *
+     * Not the rows — those you map yourself, the same as in any other table.
+     * This is the thing that works out which rows those are, and the table
+     * hands it the element they scroll inside.
+     */
+    virtualizer: UseTableVirtualReturn<never>;
+};
+/**
+ * A `Table` that renders only the rows on screen.
+ *
+ * Everything but `virtualizer` is a `Table` prop and is passed straight through.
+ * What goes inside is what goes inside a `Table`: this is the same component,
+ * told where its virtualiser is.
+ *
+ * ```tsx
+ * const virtual = useTableVirtual(employees, { height: '480px' });
+ *
+ * <TableVirtualized virtualizer={virtual}>
+ *   <TableBody>
+ *     {virtual.rows.map(row => <TableRow key={row.id}>…</TableRow>)}
+ *   </TableBody>
+ * </TableVirtualized>
+ * ```
+ *
+ * It is the one piece the Vue side does not have, and it exists because of how
+ * the two frameworks differ rather than because the tables do. There
+ * `useTableVirtual` runs in the caller's `setup`, which is already above the
+ * table, so it provides itself and `<Table>` is written exactly as it always
+ * was. A hook has nothing to provide to until something renders — so this
+ * renders.
+ *
+ * The alternative was a prop on `Table`, and it would not have stopped there:
+ * the spacers belong inside `TableBody`'s `<tbody>` and the pinned header is
+ * `TableHead`'s, so it would have had to be threaded to both of those by hand
+ * as well. A wrapper reaches all three and leaves `Table`'s own API alone.
+ */
+export declare function TableVirtualized<TData = unknown>({ virtualizer, ...props }: TableVirtualizedProps<TData>): import("react/jsx-runtime").JSX.Element;
+export declare namespace TableVirtualized {
+    var displayName: string;
+}

package/dist/Data/Table/TableVirtualized/index.d.ts

@@ -0,0 +1,2 @@
+export { TableVirtualized } from './TableVirtualized.tsx';
+export type { TableVirtualizedProps } from './TableVirtualized.tsx';

package/dist/Data/Table/hooks/index.d.ts

@@ -18,3 +18,6 @@ export { useDragToScroll } from './useDragToScroll/useDragToScroll.ts';
 export type { UseDragToScrollOptions, UseDragToScrollReturn, } from './useDragToScroll/useDragToScroll.ts';
 export { useFixedColumns } from './useFixedColumns.ts';
 export type { UseFixedColumnsOptions } from './useFixedColumns.ts';
+export { useTableVirtual } from './useTableVirtual/useTableVirtual.ts';
+export { TableVirtualContext, useTableVirtualContext, } from './useTableVirtual/context.ts';
+export type { UseTableVirtualOptions, UseTableVirtualReturn, } from './useTableVirtual/useTableVirtual.types.ts';

package/dist/Data/Table/hooks/useTableVirtual/context.d.ts

@@ -0,0 +1,16 @@
+import { UseTableVirtualReturn } from './useTableVirtual.types.ts';
+/**
+ * How the virtualiser reaches the parts of the table that need it.
+ *
+ * The Vue side has no equivalent: `useTableVirtual` runs in the caller's
+ * `setup`, which is above the table, so it provides itself and nothing has to
+ * be passed anywhere. A hook cannot do that — nothing is above anything until
+ * something renders — which is what `TableVirtualized` is for.
+ *
+ * They do need reaching. The spacers standing in for the unrendered rows have
+ * to sit inside the `<tbody>`, which `TableBody` renders from the caller's own
+ * markup, and the floating header belongs to `TableHead`. Handing each of them
+ * a prop is the boilerplate this removes.
+ */
+export declare const TableVirtualContext: import('react').Context<UseTableVirtualReturn<unknown> | null>;
+export declare function useTableVirtualContext(): UseTableVirtualReturn<unknown> | null;

package/dist/Data/Table/hooks/useTableVirtual/index.d.ts

@@ -0,0 +1,3 @@
+export { TableVirtualContext, useTableVirtualContext } from './context.ts';
+export { useTableVirtual } from './useTableVirtual.ts';
+export type { UseTableVirtualOptions, UseTableVirtualReturn, } from './useTableVirtual.types.ts';

package/dist/Data/Table/hooks/useTableVirtual/useTableVirtual.d.ts

@@ -0,0 +1,36 @@
+import { UseTableVirtualOptions, UseTableVirtualReturn } from './useTableVirtual.types.ts';
+/**
+ * Renders only the rows that are on screen, however many the table is given.
+ *
+ * Hand it the whole list and map `rows` instead: at ten thousand rows that is
+ * about twenty in the DOM, and the browser stops doing the work of laying out
+ * the other nine thousand nine hundred and eighty.
+ *
+ * ```tsx
+ * const virtual = useTableVirtual(employees, { maxHeight: '480px' });
+ *
+ * <TableVirtualized virtualizer={virtual}>
+ *   <TableBody>
+ *     {virtual.rows.map(row => <TableRow key={row.id}>…</TableRow>)}
+ *   </TableBody>
+ * </TableVirtualized>
+ * ```
+ *
+ * `TableVirtualized` is the one piece the Vue side does not have. There the
+ * composable provides itself from the caller's `setup`; a hook has nothing to
+ * provide to until something renders, so the wrapper does it instead — and
+ * `Table` itself gains no prop on either side.
+ *
+ * **Not with row reordering.** `TableBody` throws if both are on. Where a row
+ * sits in the DOM is not where it sits in the list once only part of it is
+ * rendered, and dragging across ten thousand rows is not a gesture anyone can
+ * make. A reorderable table is a paged one.
+ *
+ * **Why spacers.** Rendering twenty rows would leave a table twenty rows tall,
+ * with no scrollbar and so nothing to scroll — the window could never move.
+ * Something has to stand in for the height of everything that is not rendered,
+ * and in a `<table>` that something is a pair of empty rows, one above the
+ * window and one below. They belong inside the `<tbody>`, so `TableBody` is
+ * what renders them. A caller never writes a spacer, and never should have to.
+ */
+export declare function useTableVirtual<TData>(items: TData[], options?: UseTableVirtualOptions): UseTableVirtualReturn<TData>;

package/dist/Data/Table/hooks/useTableVirtual/useTableVirtual.types.d.ts

@@ -0,0 +1,73 @@
+import { RefObject } from 'react';
+export interface UseTableVirtualOptions {
+    /**
+     * How tall the table's scrollport is allowed to get, as a CSS length.
+     *
+     * A ceiling rather than a measurement: given fewer rows than it has room
+     * for, the table shrinks to them instead of leaving empty space under the
+     * last one.
+     *
+     * Any length the browser understands: `'480px'`, `'30vh'`,
+     * `'calc(100vh - 12rem)'`. It is written straight onto the element and the
+     * window is worked out from what that element ends up measuring, so nothing
+     * here cares which unit you used. `'100%'` works too, as long as whatever
+     * contains the table has a height of its own — a percentage of `auto` is
+     * `auto`, and a table that grows to fit its rows is the one case this cannot
+     * work with.
+     *
+     * Virtualising needs one. A table that grows to fit its rows has no scrollbar
+     * of its own — the page scrolls instead — and with nothing scrolling there is
+     * no position to work a window out from.
+     */
+    maxHeight?: string;
+    /**
+     * How tall one row is, in pixels.
+     *
+     * This is what turns a scroll position into a row index, so it is worth
+     * getting right: the error is paid on every row crossed, which is nothing at
+     * one click of the wheel and hundreds of rows after a flick. The default,
+     * 48px, is the height `TableRow` gives itself with plain text in it. Rows
+     * with an avatar or two lines of text are taller, and those tables should say
+     * so here.
+     *
+     * It is deliberately a number you give rather than one measured from the
+     * page. Measuring as you scroll means the total height changes as you scroll,
+     * and a table whose content grows and shrinks underneath the scrollbar throws
+     * you somewhere else every time it does.
+     */
+    estimateSize?: number;
+    /** How many rows to keep either side of the window, so scrolling stays smooth. */
+    overscan?: number;
+}
+export interface UseTableVirtualReturn<TData> {
+    /**
+     * The rows that belong on screen right now, as data rather than indices — a
+     * caller maps these exactly the way it would map the whole list.
+     */
+    rows: TData[];
+    /** How many rows there are in total, window or no window. */
+    total: number;
+    /** Where a windowed row sits in the full list, for callers that need to know. */
+    indexOf: (windowIndex: number) => number;
+    /**
+     * Everything below is how `Table` drives this, and no caller should have to
+     * touch it. The scrollport is the table's, the spacers are `TableBody`'s, and
+     * both reach it through `TableVirtualized` rather than by hand.
+     */
+    containerRef: RefObject<HTMLElement | null>;
+    /**
+     * How `Table` registers itself as the scrollport, and how a second one is
+     * stopped from taking it over.
+     */
+    claim: (element: HTMLElement | null) => void;
+    maxHeight: string | undefined;
+    /** The height of everything above the window, and of everything below it. */
+    padStart: number;
+    padEnd: number;
+    /**
+     * Measures a row that turned out taller than the estimate. Without it the
+     * scrollbar drifts: every row that wraps makes the list a little longer than
+     * the virtualiser thinks it is, and by the bottom the two disagree.
+     */
+    measure: (element: Element | null) => void;
+}

package/dist/Data/Table/index.d.ts

@@ -1,4 +1,5 @@
 export { Table, type TableComponentProps } from './Table.tsx';
+export { TableVirtualized, type TableVirtualizedProps, } from './TableVirtualized/TableVirtualized.tsx';
 export { TableHead, type TableHeadProps } from './TableHead/TableHead.tsx';
 export { TableBody, type TableBodyProps } from './TableBody/TableBody.tsx';
 export { TableRow, type TableRowProps } from './TableRow/TableRow.tsx';
@@ -13,5 +14,5 @@ export { TableAvatar, type TableAvatarProps, } from './TableAvatar/TableAvatar.t
 export { TableRowExpanded, type TableRowExpandedProps, } from './TableRowExpanded/TableRowExpanded.tsx';
 export { TableExpandCell, type TableExpandCellProps, } from './TableExpandCell/TableExpandCell.tsx';
 export { TableColumnVisibility, type TableColumnVisibilityProps, } from './TableColumnVisibility/TableColumnVisibility.tsx';
-export { useTable, type UseTableOptions, type UseTableReturn, useTableSelection, type SelectionInstance as UseTableSelectionReturn, useTableSorting, type SortingInstance as UseTableSortingReturn, useTablePagination, type UseTablePaginationOptions, type UseTablePaginationReturn, useTableDetailRow, type DetailRowInstance, type DetailRowOptions, type DetailRowPluginDef, useTablePinning, type PinningOptions as UseTablePinningOptions, type PinningInstance as UseTablePinningReturn, type CellInfo, type HeaderInfo, useTableColumns, type ColumnsOptions as UseTableColumnsOptions, type ColumnsInstance as UseTableColumnsReturn, useScrollShadow, type UseScrollShadowOptions, type UseScrollShadowReturn, useDragToScroll, type UseDragToScrollOptions, type UseDragToScrollReturn, useFixedColumns, type UseFixedColumnsOptions, } from './hooks/index.ts';
+export { useTable, type UseTableOptions, type UseTableReturn, useTableSelection, type SelectionInstance as UseTableSelectionReturn, useTableSorting, type SortingInstance as UseTableSortingReturn, useTablePagination, type UseTablePaginationOptions, type UseTablePaginationReturn, useTableDetailRow, type DetailRowInstance, type DetailRowOptions, type DetailRowPluginDef, useTablePinning, type PinningOptions as UseTablePinningOptions, type PinningInstance as UseTablePinningReturn, type CellInfo, type HeaderInfo, useTableColumns, type ColumnsOptions as UseTableColumnsOptions, type ColumnsInstance as UseTableColumnsReturn, useScrollShadow, type UseScrollShadowOptions, type UseScrollShadowReturn, useDragToScroll, type UseDragToScrollOptions, type UseDragToScrollReturn, useFixedColumns, type UseFixedColumnsOptions, useTableVirtual, type UseTableVirtualOptions, type UseTableVirtualReturn, } from './hooks/index.ts';
 export type { TableProps, TableMode, ColumnDef, ColumnAlign, CellContext, SortingState, PaginationState, PaginationChangePayload, SortingChangePayload, SelectionChangePayload, FilterChangePayload, ColumnResizeMode, ColumnVisibilityState, ColumnOrderState, ExpandedState, ColumnVisibilityChangePayload, ColumnOrderChangePayload, RowExpandChangePayload, ColumnResizePayload, ColumnPinningState, } from './types';

package/dist/main.d.ts

@@ -36,5 +36,5 @@ export { Breadcrumb as OxBreadcrumb, BreadcrumbList as OxBreadcrumbList, Breadcr
 export { Counter as OxCounter, counterVariants, type CounterVariants, } from './Forms/Field/Counter/index.ts';
 export { FieldGroup as OxFieldGroup, FieldLabel as OxFieldLabel, FieldMessage as OxFieldMessage, type FieldGroupProps, } from './Forms/Field/index.ts';
 export { InputGroup as OxInputGroup, InputText as OxInputText, InputNumber as OxInputNumber, InputNumberContent as OxInputNumberContent, InputNumberDecrement as OxInputNumberDecrement, InputNumberIncrement as OxInputNumberIncrement, InputNumberInput as OxInputNumberInput, InputPassword as OxInputPassword, InputPasswordInput as OxInputPasswordInput, InputPasswordToggle as OxInputPasswordToggle, useInputPassword, InputOtp as OxInputOtp, InputOtpGroup as OxInputOtpGroup, InputOtpSlot as OxInputOtpSlot, InputOtpSeparator as OxInputOtpSeparator, useInputOtp, Combobox as OxCombobox, ComboboxInput as OxComboboxInput, ComboboxChipsInput as OxComboboxChipsInput, ComboboxContent as OxComboboxContent, ComboboxItem as OxComboboxItem, ComboboxEmpty as OxComboboxEmpty, ComboboxGroup as OxComboboxGroup, ComboboxSeparator as OxComboboxSeparator, Select as OxSelect, SelectTrigger as OxSelectTrigger, SelectContent as OxSelectContent, SelectItem as OxSelectItem, SelectGroup as OxSelectGroup, SelectSeparator as OxSelectSeparator, Switch as OxSwitch, Checkbox as OxCheckbox, RadioButton as OxRadioButton, RadioGroup as OxRadioGroup, ToggleGroup as OxToggleGroup, ToggleLabel as OxToggleLabel, ToggleDescription as OxToggleDescription, SWITCH_SIZES, type InputNumberProps, type InputPasswordProps, type InputPasswordContext, type InputOtpProps, type InputOtpSlotProps, type InputOtpContext, type ComboboxProps, type SelectProps, type RadioGroupProps, type ToggleGroupProps, type ToggleLabelProps, type ToggleDescriptionProps, } from './Forms/Inputs/index.ts';
-export { Table as OxTable, TableHead as OxTableHead, TableBody as OxTableBody, TableRow as OxTableRow, TableCell as OxTableCell, TableHeaderCell as OxTableHeaderCell, TableSelectCell as OxTableSelectCell, TableDragCell as OxTableDragCell, TableBulkHeader as OxTableBulkHeader, TablePagination as OxTablePagination, TableEmpty as OxTableEmpty, TableAvatar as OxTableAvatar, TableRowExpanded as OxTableRowExpanded, TableExpandCell as OxTableExpandCell, TableColumnVisibility as OxTableColumnVisibility, useTable, useTableSelection, useTableSorting, useTablePagination, useTableDetailRow, useTablePinning, useTableColumns, useScrollShadow, useDragToScroll, useFixedColumns, } from './Data/Table/index.ts';
-export type { UseTableOptions, UseTableReturn, UseTableSelectionReturn, UseTableSortingReturn, UseTablePaginationOptions, UseTablePaginationReturn, DetailRowInstance, DetailRowOptions, DetailRowPluginDef, UseTablePinningOptions, UseTablePinningReturn, CellInfo, HeaderInfo, UseTableColumnsOptions, UseTableColumnsReturn, UseScrollShadowOptions, UseScrollShadowReturn, UseDragToScrollOptions, UseDragToScrollReturn, UseFixedColumnsOptions, TableProps, TableMode, ColumnDef, ColumnAlign, CellContext, SortingState, PaginationState, PaginationChangePayload, SortingChangePayload, SelectionChangePayload, FilterChangePayload, ColumnResizeMode, ColumnVisibilityState, ColumnOrderState, ExpandedState, ColumnVisibilityChangePayload, ColumnOrderChangePayload, RowExpandChangePayload, ColumnResizePayload, ColumnPinningState, } from './Data/Table/index.ts';
+export { Table as OxTable, TableVirtualized as OxTableVirtualized, TableHead as OxTableHead, TableBody as OxTableBody, TableRow as OxTableRow, TableCell as OxTableCell, TableHeaderCell as OxTableHeaderCell, TableSelectCell as OxTableSelectCell, TableDragCell as OxTableDragCell, TableBulkHeader as OxTableBulkHeader, TablePagination as OxTablePagination, TableEmpty as OxTableEmpty, TableAvatar as OxTableAvatar, TableRowExpanded as OxTableRowExpanded, TableExpandCell as OxTableExpandCell, TableColumnVisibility as OxTableColumnVisibility, useTable, useTableSelection, useTableSorting, useTablePagination, useTableDetailRow, useTablePinning, useTableColumns, useScrollShadow, useDragToScroll, useFixedColumns, useTableVirtual, } from './Data/Table/index.ts';
+export type { UseTableOptions, UseTableReturn, UseTableSelectionReturn, UseTableSortingReturn, UseTablePaginationOptions, UseTablePaginationReturn, DetailRowInstance, DetailRowOptions, DetailRowPluginDef, UseTablePinningOptions, UseTablePinningReturn, CellInfo, HeaderInfo, UseTableVirtualOptions, UseTableVirtualReturn, UseTableColumnsOptions, UseTableColumnsReturn, UseScrollShadowOptions, UseScrollShadowReturn, UseDragToScrollOptions, UseDragToScrollReturn, UseFixedColumnsOptions, TableProps, TableMode, ColumnDef, ColumnAlign, CellContext, SortingState, PaginationState, PaginationChangePayload, SortingChangePayload, SelectionChangePayload, FilterChangePayload, ColumnResizeMode, ColumnVisibilityState, ColumnOrderState, ExpandedState, ColumnVisibilityChangePayload, ColumnOrderChangePayload, RowExpandChangePayload, ColumnResizePayload, ColumnPinningState, } from './Data/Table/index.ts';