@ssa-ui-kit/core 3.23.1 → 3.24.0

package/dist/components/Calendar/utils.d.ts

@@ -0,0 +1,116 @@
+import { ReactNode } from 'react';
+import { DateTime } from 'luxon';
+import { CalendarDateInput, CalendarEvent } from './types';
+/** Length given to a timed event that has no `end`. */
+export declare const DEFAULT_EVENT_MINUTES = 30;
+/**
+ * Most days an entry is repeated on. A mistyped `end` years away would
+ * otherwise fill every cell up to it.
+ */
+export declare const MAX_SPAN_DAYS = 366;
+/** `Date` or ISO string → luxon, in local time. */
+export declare const toDateTime: (value: CalendarDateInput) => DateTime;
+/** `yyyy-MM-dd` of a date — the key events are grouped by. */
+export declare const toDayKey: (value: DateTime) => string;
+/**
+ * An event with its dates parsed once, so rendering never re-parses them.
+ */
+export type NormalizedEvent<TData = unknown> = {
+    event: CalendarEvent<TData>;
+    start: DateTime;
+    /** For untimed events, the start of the last day (inclusive). */
+    end: DateTime;
+    allDay: boolean;
+    /** Days the entry is repeated on: 1 unless it spans several. */
+    spanDays: number;
+    /** Which of those days this copy is on, from 1. */
+    dayOfSpan: number;
+};
+export declare const normalizeEvent: <TData>(event: CalendarEvent<TData>) => NormalizedEvent<TData> | undefined;
+/**
+ * Whether an entry fills a day: untimed, or timed and running from before
+ * the day starts to after it ends. Such entries are listed above the day
+ * view's timeline rather than placed on it.
+ */
+export declare const isWholeDay: (item: NormalizedEvent, day: DateTime) => boolean;
+/**
+ * Groups events by day (`yyyy-MM-dd`), each day sorted for display. An event
+ * spanning several days (see `NormalizedEvent.spanDays`) is repeated on
+ * each, with its `dayOfSpan`. Events with an unparsable `start` are dropped.
+ */
+export declare const groupEventsByDay: <TData>(events: CalendarEvent<TData>[]) => Map<string, NormalizedEvent<TData>[]>;
+/** A cell of the month grid. */
+export type MonthDay = {
+    date: DateTime;
+    key: string;
+    isCurrentMonth: boolean;
+    isToday: boolean;
+    isWeekend: boolean;
+};
+/** A row of the month grid. */
+export type MonthWeek = {
+    key: string;
+    days: MonthDay[];
+};
+/**
+ * The Monday-first week rows covering `month`, padded out with the
+ * neighbouring months' days. With five weekdays a row that holds only the
+ * neighbours' days is dropped — a month that ends on a Saturday would
+ * otherwise get a row of nothing but padding.
+ */
+export declare const buildMonthWeeks: (month: DateTime, weekdays: 5 | 7, today?: DateTime) => MonthWeek[];
+/** Monday-first weekday names, `long` (`Monday`) or `short` (`Mon`). */
+export declare const getWeekdayNames: (format: "long" | "short", locale?: string) => string[];
+/** `09:30` or `09:30 AM`. */
+export declare const formatTime: (value: DateTime, timeFormat: "24h" | "12h") => string;
+/**
+ * Hour label of the day view: `09:00` or `9 AM`. Formatted on a fixed date
+ * with no DST change, so every hour exists — on today's date an hour skipped
+ * by DST would be moved on, and labelled like the next one.
+ */
+export declare const formatHourLabel: (hour: number, timeFormat: "24h" | "12h") => string;
+/**
+ * Minutes from midnight as the clock shows them. The timeline draws 24
+ * labelled hours on every day, so positions follow the clock rather than
+ * elapsed time — on a DST day, elapsed time would put entries after the
+ * change an hour off their labels.
+ */
+export declare const clockMinutes: (value: DateTime) => number;
+/** A timed event placed on the day view's timeline. */
+export type PositionedEvent<TData = unknown> = {
+    item: NormalizedEvent<TData>;
+    /** Minutes from midnight to the start. */
+    startMinutes: number;
+    /** Minutes the event lasts, clipped to the day. */
+    durationMinutes: number;
+    /** Column within its overlap group, from 0. */
+    column: number;
+    /** Columns in its overlap group. */
+    columns: number;
+};
+/**
+ * Places a day's timed events on the timeline. Events that overlap share the
+ * width side by side; each overlap group gets just as many columns as it
+ * needs at its busiest moment.
+ *
+ * Expects events sorted by start: the day's own (as `groupEventsByDay`
+ * returns them), after any carried over from earlier days. Events running
+ * past either midnight are clipped to the day; events not on it are skipped.
+ */
+export declare const layoutDayEvents: <TData>(items: NormalizedEvent<TData>[], day: DateTime) => PositionedEvent<TData>[];
+/** Applies `locale` when given; otherwise keeps luxon's default. */
+export declare const withLocale: (value: DateTime, locale?: string) => DateTime<boolean>;
+/**
+ * First and last day a view shows: the whole grid of the month view,
+ * neighbouring months' days included, or the single day.
+ */
+export declare const getVisibleRange: (view: "month" | "day", date: DateTime, weekdays: 5 | 7) => {
+    start: DateTime;
+    end: DateTime;
+};
+/**
+ * Whether a slot has something to draw. Like React itself, keeps `0` and
+ * `''` but skips `false` — so `slot={cond && <Button />}` adds no empty
+ * wrapper when `cond` is false.
+ */
+export declare const hasContent: (node: ReactNode) => node is string | number | bigint | true | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | import("react").ReactPortal | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined>;

package/dist/components/NestedTable/NestedTableContext.d.ts

@@ -1,3 +1,3 @@
-import { NestedTableContextType } from './types';
-export declare const NestedTableContext: import("react").Context<NestedTableContextType>;
-export declare const NestedTableProvider: ({ children, collapsedIconName, expandedIconName, defaultCollapsed, }: React.PropsWithChildren<NestedTableContextType>) => import("@emotion/react/jsx-runtime").JSX.Element;
+import { NestedTableContextValue } from './types';
+export declare const NestedTableContext: import("react").Context<NestedTableContextValue>;
+export declare const NestedTableProvider: ({ children, collapsedIconName, expandedIconName, defaultCollapsed, opaqueCells, isResizable, }: React.PropsWithChildren<NestedTableContextValue>) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/NestedTable/components/NestedTable.d.ts

@@ -1,6 +1,4 @@
-import { PropsWithChildren, TableHTMLAttributes } from 'react';
-import { CommonProps } from '../../../types/emotion';
-import { NestedTableContextType } from '../types';
+import { TableProps } from '../../Table/types';
 /**
  * NestedTable - Table whose rows collapse into expandable groups.
  *
@@ -26,6 +24,21 @@ import { NestedTableContextType } from '../types';
  * is what makes the transition animate. They remain findable by queries and by
  * `Ctrl+F`, so do not rely on collapse to hide sensitive content.
  *
+ * ### Resizing and freezing columns
+ * Takes every `Table` option — `resizableColumns`, `frozenColumns`,
+ * `freezeControls`, `stickyHeader` — and works inside `TableContainer`. Build
+ * the header from `NestedTableCellHeader` so the columns get their drag handles
+ * and freeze menus.
+ *
+ * Column positions skip the toggle column: `0` is your first column in
+ * `frozenColumns`, and width arrays hold one entry per column of yours. The
+ * toggle column freezes by itself only when your first column is frozen to the
+ * left; otherwise it scrolls like any other column.
+ *
+ * Frozen cells and a sticky header paint the row's background, so give rows an
+ * opaque one — a translucent row would let scrolled content show through.
+ * With resizing on, the table renders its own `colgroup`; drop any you had.
+ *
  * @category Components
  * @subcategory Data Display
  *
@@ -57,5 +70,25 @@ import { NestedTableContextType } from '../types';
  *   {groups}
  * </NestedTable>
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Resizable, with the first column frozen and a sticky header
+ * <TableContainer maxHeight={400}>
+ *   <NestedTable
+ *     resizableColumns
+ *     freezeControls
+ *     stickyHeader
+ *     defaultFrozenColumns={{ start: ['team'] }}>
+ *     <TableHead>
+ *       <NestedTableRow isHeader>
+ *         <NestedTableCellHeader columnId="team">Team</NestedTableCellHeader>
+ *         <NestedTableCellHeader columnId="size">Headcount</NestedTableCellHeader>
+ *       </NestedTableRow>
+ *     </TableHead>
+ *     <TableBody>{groups}</TableBody>
+ *   </NestedTable>
+ * </TableContainer>
+ * ```
  */
-export declare const NestedTable: ({ children, collapsedIconName, expandedIconName, defaultCollapsed, ...rest }: PropsWithChildren & NestedTableContextType & CommonProps & TableHTMLAttributes<HTMLTableElement>) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const NestedTable: import("react").ForwardRefExoticComponent<TableProps & import("../types").NestedTableContextType & import("react").RefAttributes<HTMLTableElement>>;

package/dist/components/NestedTable/components/NestedTableCell.d.ts

@@ -1,5 +1,4 @@
-import { HTMLAttributes } from 'react';
-import { CommonProps } from '../../../types/emotion';
+import { NestedTableCellBaseProps } from './NestedTableCellBase';
 /**
  * NestedTableCell - Cell for a `NestedTableRow`.
  *
@@ -33,4 +32,4 @@ import { CommonProps } from '../../../types/emotion';
  * <NestedTableCell as="th">Headcount</NestedTableCell>
  * ```
  */
-export declare const NestedTableCell: ({ children, ...props }: React.PropsWithChildren<HTMLAttributes<HTMLTableCellElement>> & CommonProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const NestedTableCell: (props: Omit<NestedTableCellBaseProps, "adornment" | "trailing">) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/NestedTable/components/NestedTableCellBase.d.ts

@@ -0,0 +1,16 @@
+import { ReactNode } from 'react';
+import { TableCellProps } from '../../TableCell/types';
+export type NestedTableCellBaseProps = React.PropsWithChildren<TableCellProps> & {
+    /** Rendered inside the content wrapper, after the content. */
+    adornment?: ReactNode;
+    /**
+     * Rendered after the content wrapper, straight inside the cell — where
+     * the table's stylesheet expects a column's resize handle.
+     */
+    trailing?: ReactNode;
+};
+/**
+ * The cell shared by `NestedTableCell` and `NestedTableCellHeader`. Not
+ * exported from the package.
+ */
+export declare const NestedTableCellBase: ({ children, adornment, trailing, ...props }: NestedTableCellBaseProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/NestedTable/components/NestedTableCellHeader.d.ts

@@ -0,0 +1,36 @@
+import { NestedTableCellHeaderProps } from '../types';
+/**
+ * NestedTableCellHeader - Column header cell for a `NestedTable`.
+ *
+ * The nested counterpart of `TableCellHeader`: renders a `th` styled like a
+ * `NestedTableCell`, and carries the column's drag handle when the table has
+ * `resizableColumns` and its freeze menu when the table has `freezeControls`.
+ * Outside those modes it is just a header cell, so it is safe to use in every
+ * nested table.
+ *
+ * Use it in the header `NestedTableRow` (the one with `isHeader`). The
+ * toggle column the row adds in front gets no handle or menu, and does not
+ * count as a column — `0` is the first header cell you render.
+ *
+ * @category Components
+ * @subcategory Data Display
+ *
+ * @example
+ * ```tsx
+ * <TableHead>
+ *   <NestedTableRow isHeader>
+ *     <NestedTableCellHeader columnId="team">Team</NestedTableCellHeader>
+ *     <NestedTableCellHeader columnId="size">Headcount</NestedTableCellHeader>
+ *     <NestedTableCellHeader columnId="actions" resizable={false} freezable={false} />
+ *   </NestedTableRow>
+ * </TableHead>
+ * ```
+ *
+ * @see {@link NestedTable} - `resizableColumns`, `frozenColumns`, `freezeControls`
+ * @see {@link TableCellHeader} - the same cell for a plain `Table`
+ *
+ * @accessibility
+ * - Renders a semantic `th`
+ * - The resize handle and freeze menu are keyboard operable
+ */
+export declare const NestedTableCellHeader: ({ children, resizable, freezable, columnId, ...props }: React.PropsWithChildren<NestedTableCellHeaderProps>) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/NestedTable/components/index.d.ts

@@ -2,3 +2,4 @@ export * from './NestedTable';
 export * from './NestedTableCell';
 export * from './NestedTableCellSubHeader';
 export * from './NestedTableRow';
+export * from './NestedTableCellHeader';

package/dist/components/NestedTable/consts.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Width of the toggle column `NestedTableRow` puts in front of every row: the
+ * cell's 16px left padding plus the 20px icon box.
+ */
+export declare const NESTED_EXPANDER_WIDTH = 36;

package/dist/components/NestedTable/hooks/useNestedTableContext.d.ts

@@ -1 +1 @@
-export declare const useNestedTableContext: () => import("..").NestedTableContextType;
+export declare const useNestedTableContext: () => import("..").NestedTableContextValue;

package/dist/components/NestedTable/types.d.ts

@@ -1,5 +1,7 @@
 import { Dispatch, SetStateAction } from 'react';
 import { IconProps } from '../Icon/types';
+import { TableProps } from '../Table/types';
+import { TableCellHeaderProps } from '../TableCellHeader/types';
 export type NestedTableContextType = {
     /** Toggle icon shown while a group is collapsed. @default 'carrot-up' */
     collapsedIconName?: IconProps['name'];
@@ -14,6 +16,35 @@ export type NestedTableContextType = {
      */
     defaultCollapsed?: boolean;
 };
+/** What `NestedTable` hands its rows and cells, beyond its own props. */
+export type NestedTableContextValue = NestedTableContextType & {
+    /**
+     * Set while columns can freeze or the header sticks. Cells then paint the
+     * row's background themselves, and the row paints it opaque, so content
+     * scrolled under a stuck cell does not show through.
+     */
+    opaqueCells?: boolean;
+    /**
+     * Mirrors the table's `resizableColumns`. Cells read it here rather than
+     * from the resize context, whose value changes on every frame of a drag and
+     * would re-render every cell in the table with it.
+     */
+    isResizable?: boolean;
+};
+/**
+ * Props for {@link NestedTable}: everything `Table` accepts, plus the group
+ * toggle options.
+ *
+ * Column positions in `columnWidths`, `defaultColumnWidths`,
+ * `onColumnWidthsChange` and `frozenColumns` count only your own columns — the
+ * toggle column `NestedTableRow` adds in front is left out of all of them.
+ */
+export type NestedTableProps = TableProps & NestedTableContextType;
+/**
+ * Props for {@link NestedTableCellHeader}: the same column options as
+ * `TableCellHeader` — `columnId`, `resizable`, `freezable`.
+ */
+export type NestedTableCellHeaderProps = TableCellHeaderProps;
 export type NestedTableRowContextType = {
     isCollapsed: boolean;
     isSubHeader: boolean;

package/dist/components/Table/ColumnFreezeContext.d.ts

@@ -0,0 +1,27 @@
+import { ColumnFreezeApi } from './types';
+/**
+ * Null outside a `Table` that freezes columns or offers freeze controls, so
+ * header cells in an ordinary table stay exactly as they were.
+ */
+export declare const ColumnFreezeContext: import("react").Context<ColumnFreezeApi | null>;
+/**
+ * The enclosing table's column-freezing state, or `null` when it has none.
+ *
+ * Lets a custom header cell render {@link ColumnFreezeMenu} only when the
+ * table asked for freeze controls.
+ *
+ * @example
+ * ```tsx
+ * const MyHeaderCell = ({ children }) => {
+ *   const columnFreeze = useColumnFreezeContext();
+ *
+ *   return (
+ *     <TableCell as="th">
+ *       {children}
+ *       {columnFreeze?.freezeControls && <ColumnFreezeMenu />}
+ *     </TableCell>
+ *   );
+ * };
+ * ```
+ */
+export declare const useColumnFreezeContext: () => ColumnFreezeApi | null;

package/dist/components/Table/ColumnFreezeMenu.d.ts

@@ -0,0 +1,33 @@
+import { ColumnFreezeMenuProps } from './types';
+/**
+ * ColumnFreezeMenu - The freeze/unfreeze menu in a table header cell
+ *
+ * `TableCellHeader` renders it for you when its `Table` has `freezeControls`.
+ * Render it yourself only in a custom header cell, passing the column's id;
+ * without one it falls back to the `columnId` or position of the `th` it
+ * sits in.
+ *
+ * Any column can be frozen to either edge. It stays where it is until
+ * scrolling would take it out of view, then sticks to that edge while the
+ * columns between slide underneath.
+ *
+ * @category Components
+ * @subcategory Data Display
+ *
+ * @example
+ * ```tsx
+ * <TableCell as="th" data-column-id="email">
+ *   Email
+ *   <ColumnFreezeMenu columnId="email" />
+ * </TableCell>
+ * ```
+ *
+ * @see {@link Table} - `freezeControls` and `frozenColumns`
+ * @see {@link useColumnFreezeContext} - whether the table wants the menu
+ *
+ * @accessibility
+ * - The trigger is a labelled button, reachable by keyboard even while hidden
+ * - Clicks inside the menu do not reach the header cell, so they never sort
+ */
+export declare const ColumnFreezeMenu: ({ columnId }: ColumnFreezeMenuProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export default ColumnFreezeMenu;

package/dist/components/Table/TableBase.d.ts

@@ -1,5 +1,5 @@
 import { CommonProps } from '../../types/emotion';
-import { ColumnResizeMode } from './types';
+import { ColumnResizeMode, FrozenColumnIndices } from './types';
 export interface TableBaseProps extends CommonProps {
     /** Applies the truncation rules resizing depends on. */
     isResizable?: boolean;
@@ -11,6 +11,13 @@ export interface TableBaseProps extends CommonProps {
     hasColumnWidths?: boolean;
     /** How a resize distributes width. See TableProps.columnResizeMode. */
     columnResizeMode?: ColumnResizeMode;
+    /**
+     * Positions of the frozen columns on each edge, resolved by `Table` from
+     * the ids in TableProps.frozenColumns.
+     */
+    frozenIndices?: FrozenColumnIndices;
+    /** Keeps the header row in view. See TableProps.stickyHeader. */
+    stickyHeader?: boolean;
 }
 /**
  * The styled element behind `Table`.

package/dist/components/Table/hooks/useColumnFreeze.d.ts

@@ -0,0 +1,44 @@
+import { RefObject } from 'react';
+import { ColumnFreezeApi, FrozenColumnIndices, FrozenColumns } from '../types';
+/** Custom property holding the sticky offset of the column at `index`. */
+export declare const frozenOffsetVar: (index: number) => string;
+/** Attributes naming the frozen column that currently casts each shadow. */
+export declare const SHADOW_START_ATTR = "data-frozen-shadow-start";
+export declare const SHADOW_END_ATTR = "data-frozen-shadow-end";
+interface UseColumnFreezeOptions {
+    tableRef: RefObject<HTMLTableElement | null>;
+    frozenColumns?: FrozenColumns;
+    defaultFrozenColumns?: FrozenColumns;
+    onFrozenColumnsChange?: (frozenColumns: Required<FrozenColumns>) => void;
+    freezeControls: boolean;
+    controlled: boolean;
+}
+/**
+ * Frozen-column state for `Table`, plus the DOM work that keeps frozen cells
+ * in place.
+ *
+ * ## Ids are resolved against the header
+ *
+ * The caller speaks in column ids; the stylesheet needs positions. After every
+ * render the header cells are read back, ids matched to positions, and the
+ * positions handed to `TableBase`. Only the set of frozen positions ever
+ * reaches emotion, so a column changing width mints no new rules.
+ *
+ * ## Offsets live in custom properties
+ *
+ * Each frozen cell is `position: sticky` with a `left`/`right` equal to the
+ * width of the frozen columns between it and its edge. Those widths change
+ * with every frame of a column resize, so they are written to custom
+ * properties on the table element directly.
+ *
+ * ## Shadows follow the scroll position
+ *
+ * `data-frozen-shadow-start` / `-end` on the table name the frozen column on
+ * each side that has content scrolled underneath it, so the divider only
+ * shows when there is something to divide.
+ */
+export declare const useColumnFreeze: ({ tableRef, frozenColumns, defaultFrozenColumns, onFrozenColumnsChange, freezeControls, controlled, }: UseColumnFreezeOptions) => {
+    api: ColumnFreezeApi;
+    indices: FrozenColumnIndices;
+};
+export {};

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

@@ -2,5 +2,7 @@ export { default } from './Table';
 export { default as ColumnResizeHandle } from './ColumnResizeHandle';
 export { useColumnResize } from './hooks/useColumnResize';
 export { useColumnResizeContext } from './ColumnResizeContext';
+export { default as ColumnFreezeMenu } from './ColumnFreezeMenu';
+export { useColumnFreezeContext } from './ColumnFreezeContext';
 export * from './types';
 export * from './ColumnResizeHandle.types';

package/dist/components/Table/types.d.ts

@@ -97,6 +97,12 @@ export interface UseColumnResizeOptions extends ColumnResizeOptions {
 export interface ColumnResizeApi {
     /** Current width of each column, in pixels. Empty until measured. */
     columnWidths: number[];
+    /**
+     * Positions of the columns the table added on its own, such as the toggle
+     * column of a `NestedTable`. In `fit` mode they keep their width exactly,
+     * and only the other columns share out any space the table has to spare.
+     */
+    fixedColumns: number[];
     /** Attach to the `table` element so the hook can measure its columns. */
     tableRef: RefObject<HTMLTableElement | null>;
     /** Whether a drag is in progress. */
@@ -119,11 +125,100 @@ export interface ColumnResizeApi {
     /** Builds the props for the drag handle of a given column. */
     getResizeHandleProps: (index: number) => ResizeHandleProps;
 }
+/**
+ * Identifies a table column: the `columnId` of its `TableCellHeader`, or its
+ * zero-based position when the header has none. Ids are compared as strings,
+ * so `3` and `'3'` are the same column.
+ */
+export type ColumnId = string | number;
+/**
+ * Which columns of a {@link Table} are frozen, and to which edge.
+ *
+ * A frozen column stays where it is until scrolling would take it out of view;
+ * from then on it sticks to its edge and the columns between it and the edge
+ * slide underneath. Several frozen columns on one edge stack up in column
+ * order.
+ *
+ * Give the header cells a `columnId` so the frozen state follows the column
+ * when the app hides or reorders columns; without one, a column is
+ * identified by its position.
+ *
+ * @example
+ * ```tsx
+ * const frozen: FrozenColumns = { start: ['name', 'status'], end: ['actions'] };
+ * ```
+ */
+export interface FrozenColumns {
+    /**
+     * Columns that stick to the left edge.
+     * @default []
+     */
+    start?: ColumnId[];
+    /**
+     * Columns that stick to the right edge.
+     * @default []
+     */
+    end?: ColumnId[];
+}
+/** Which columns, by position, are frozen to each edge, in column order. */
+export interface FrozenColumnIndices {
+    start: number[];
+    end: number[];
+}
+/** Options for freezing columns and the header row of a `Table`. */
+export interface ColumnFreezeOptions {
+    /**
+     * Columns frozen to each edge. Passing this prop puts freezing into
+     * controlled mode — hold the value in state and update it from
+     * `onFrozenColumnsChange`, or the header controls will have no effect.
+     */
+    frozenColumns?: FrozenColumns;
+    /** Columns frozen to each edge to begin with, for the uncontrolled case. */
+    defaultFrozenColumns?: FrozenColumns;
+    /**
+     * Called whenever the user freezes or unfreezes columns from the header
+     * controls. Always receives both lists.
+     */
+    onFrozenColumnsChange?: (frozenColumns: Required<FrozenColumns>) => void;
+    /**
+     * Gives every `TableCellHeader` a menu to freeze its column to either edge,
+     * or unfreeze it. Independent of `frozenColumns` — a table can have frozen
+     * columns without letting the user change them.
+     *
+     * @default false
+     */
+    freezeControls?: boolean;
+    /**
+     * Keeps the header row in view while the table scrolls vertically. Needs a
+     * scroll container with a height limit, such as `TableContainer` with
+     * `maxHeight`.
+     *
+     * @default false
+     */
+    stickyHeader?: boolean;
+}
+/** Props for {@link ColumnFreezeMenu}. */
+export interface ColumnFreezeMenuProps {
+    /**
+     * The column the menu freezes. Defaults to the `data-column-id` of the
+     * header cell it sits in, or that cell's position.
+     */
+    columnId?: ColumnId;
+}
+/** What the freezing context hands to header cells. */
+export interface ColumnFreezeApi {
+    /** Current frozen columns, both lists always present. */
+    frozenColumns: Required<FrozenColumns>;
+    /** Replaces the frozen columns and notifies `onFrozenColumnsChange`. */
+    setFrozenColumns: (frozenColumns: Required<FrozenColumns>) => void;
+    /** Whether header cells should render the freeze menu. */
+    freezeControls: boolean;
+}
 /**
  * Props for the {@link Table} component.
  *
  * Every attribute of a `table` element, plus the column-resizing options that
- * `resizableColumns` turns on.
+ * `resizableColumns` turns on and the column-freezing options.
  *
  * @example
  * ```tsx
@@ -132,7 +227,7 @@ export interface ColumnResizeApi {
  * </Table>
  * ```
  */
-export interface TableProps extends CommonProps, ColumnResizeOptions, TableHTMLAttributes<HTMLTableElement> {
+export interface TableProps extends CommonProps, ColumnResizeOptions, ColumnFreezeOptions, TableHTMLAttributes<HTMLTableElement> {
     /**
      * Lets columns be resized by dragging the right edge of each header cell.
      *

package/dist/components/Table/utils.d.ts

@@ -0,0 +1,21 @@
+import { ColumnId } from './types';
+/** The cells that define the column grid — the first header row, or row one. */
+export declare const getHeaderCells: (table: HTMLTableElement | null) => HTMLTableCellElement[];
+/**
+ * Marks a structural column the table adds on its own, such as the toggle
+ * column `NestedTableRow` puts in front of every row. It has no id of its own,
+ * is skipped when columns are numbered, and freezes to the start only when the
+ * column right after it does.
+ */
+export declare const EXPANDER_ATTR = "data-column-expander";
+export declare const isExpanderCell: (cell: HTMLTableCellElement) => boolean;
+/**
+ * The id each cell answers to: its `columnId`, else its position counting only
+ * the columns the app itself rendered. `null` for expander cells.
+ */
+export declare const getColumnKeys: (cells: HTMLTableCellElement[]) => (string | null)[];
+/**
+ * The id of the column a header cell belongs to: its `columnId`, else its
+ * position as a number. `null` for an expander. See getColumnKeys.
+ */
+export declare const getColumnIdOf: (cell: HTMLTableCellElement) => ColumnId | null;

package/dist/components/TableCellHeader/TableCellHeader.d.ts

@@ -54,6 +54,7 @@ import { TableCellHeaderProps } from './types';
  * @see {@link TableCell} - Data cell component (use in TableBody)
  * @see {@link TableBody} - Body section component
  * @see {@link ColumnResizeHandle} - the handle rendered inside resizable headers
+ * @see {@link ColumnFreezeMenu} - the menu rendered when the table has `freezeControls`
  *
  * @accessibility
  * - Semantic HTML th element (renders as th)
@@ -61,5 +62,5 @@ import { TableCellHeaderProps } from './types';
  * - Supports ARIA attributes via TableCellProps
  * - Better accessibility than using TableCell in headers
  */
-declare const TableCellHeader: ({ children, resizable, ...props }: React.PropsWithChildren<TableCellHeaderProps>) => import("@emotion/react/jsx-runtime").JSX.Element;
+declare const TableCellHeader: ({ children, resizable, freezable, columnId, ...props }: React.PropsWithChildren<TableCellHeaderProps>) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default TableCellHeader;

package/dist/components/TableCellHeader/types.d.ts

@@ -1,4 +1,5 @@
 import { TableCellProps } from '../TableCell/types';
+import { ColumnId } from '../Table/types';
 /**
  * Props for the TableCellHeader component
  *
@@ -42,4 +43,20 @@ export interface TableCellHeaderProps extends TableCellProps {
      * @default true
      */
     resizable?: boolean;
+    /**
+     * Whether this header cell offers the freeze menu inside a `Table` with
+     * `freezeControls`. Set it to `false` for columns the user should not
+     * freeze, such as a checkbox column. The app can still freeze it through
+     * `frozenColumns`.
+     *
+     * @default true
+     */
+    freezable?: boolean;
+    /**
+     * Stable id for this column, used by `frozenColumns` on the `Table`. Give
+     * every header one when the app can hide or reorder columns, so frozen
+     * state follows the column rather than its position. Without it the column
+     * is identified by its zero-based position.
+     */
+    columnId?: ColumnId;
 }