@kanso-labs/react-native-kanso-ui 0.10.0 → 0.11.0

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

@@ -0,0 +1,391 @@
+import { CollectionLoadMoreProps } from "../../collection/index.js";
+import { FlatList, HostInstance, PressableProps, ScrollViewProps, StyleProp, ViewStyle } from "react-native";
+import { ReactElement, ReactNode, Ref } from "react";
+import { DisabledBehavior, Key, Node, Selection, SelectionMode, SortDescriptor } from "react-stately";
+import { ColumnSize, ColumnStaticSize } from "react-stately/useTableState";
+//#region src/components/table/index.d.ts
+/**
+ * What a part's entry is built with: the columns the header has given so
+ * far, which a row reads its cells against.
+ */
+type BuilderContext = {
+  columns: Node<unknown>[];
+};
+type TableBodyProps<T extends object = object> = {
+  /**
+   * The rows, each a `Table.Row`, with a `Table.LoadMore` after them. With
+   * `items`, a function from an item to its row, called for each in turn.
+   */
+  readonly children?: ((item: T) => ReactElement) | ReactNode;
+  /** The entries `children` draws a row for, when it is a function. */
+  readonly items?: Iterable<T>;
+  /**
+   * What the table shows in place of rows when it has none and nothing is
+   * loading, in a muted, padded box across its width. A string is set in
+   * body medium.
+   */
+  readonly renderEmptyState?: () => ReactNode;
+};
+type TableCellProps = {
+  /** What the cell holds. A string is set in body medium. */
+  readonly children?: ReactNode;
+  /**
+   * How many columns the cell spans, from where it sits.
+   * @default 1
+   */
+  readonly colSpan?: number;
+  /**
+   * Draws this row's selection checkbox instead of `children`. The row's own
+   * text is what names the row.
+   */
+  readonly selection?: boolean;
+  readonly style?: StyleProp<ViewStyle>;
+  readonly testID?: string;
+  /** The cell's text, read off `children` when they are a plain string. */
+  readonly textValue?: string;
+};
+type TableColumnProps = {
+  /**
+   * Makes the header itself the control that sorts by the column, as
+   * React Aria's prop does. The arrow appears on the column the table's
+   * `sortDescriptor` names.
+   * @default false
+   */
+  readonly allowsSorting?: boolean;
+  /** The column's name. */
+  readonly children?: ReactNode;
+  /** The width the column starts at, when the table keeps its widths. */
+  readonly defaultWidth?: ColumnSize | null;
+  /**
+   * The key the column is sorted and sized by. It shares a namespace with
+   * the rows' ids, so give the two sets values that cannot meet.
+   */
+  readonly id?: Key;
+  /**
+   * Marks the column a screen reader reads a row by on web. Kept for a call
+   * site written for both libraries; native reads every cell of a row.
+   * @default false
+   */
+  readonly isRowHeader?: boolean;
+  /** The widest the column is drawn. */
+  readonly maxWidth?: ColumnStaticSize | null;
+  /**
+   * The narrowest the column is drawn.
+   * @default 75
+   */
+  readonly minWidth?: ColumnStaticSize | null;
+  /**
+   * Draws a handle at the column's trailing edge that drags its width. Needs
+   * the table's own `resizable` as well.
+   * @default false
+   */
+  readonly resizable?: boolean;
+  /**
+   * Draws the select-all checkbox instead of `children`, for the column the
+   * rows put their own checkboxes in.
+   * @default false
+   */
+  readonly selection?: boolean;
+  readonly style?: StyleProp<ViewStyle>;
+  readonly testID?: string;
+  /** The column's name as text, read off `children` when it is a string. */
+  readonly textValue?: string;
+  /** The column's width, for a call site holding the widths itself. */
+  readonly width?: ColumnSize | null;
+};
+type TableFooterProps = {
+  /** The rows under the body, each a `Table.Row` of `Table.Cell`s. */
+  readonly children?: ReactNode;
+  readonly style?: StyleProp<ViewStyle>;
+  readonly testID?: string;
+};
+type TableHeaderProps<T extends object = object> = {
+  /**
+   * The columns, each a `Table.Column`. With `columns`, a function from an
+   * entry to its column, called for each in turn.
+   */
+  readonly children?: ((column: T) => ReactElement) | ReactNode;
+  /** The entries `children` draws a column for, when it is a function. */
+  readonly columns?: Iterable<T>;
+  readonly style?: StyleProp<ViewStyle>;
+  readonly testID?: string;
+};
+type TableLoadMoreProps = CollectionLoadMoreProps;
+type TableProps = Omit<ScrollViewProps, 'children' | 'horizontal' | 'role' | 'stickyHeaderIndices' | 'style'> & {
+  /**
+   * The parts: a `Table.Header`, a `Table.Body` and, under them, a
+   * `Table.Footer`.
+   */
+  readonly children?: ReactNode;
+  /** The keys selected at first, when the table keeps its own selection. */
+  readonly defaultSelectedKeys?: 'all' | Iterable<Key>;
+  /**
+   * Whether `disabledKeys` takes every press off a row, or only its
+   * selection, as React Aria's prop says.
+   * @default 'all'
+   */
+  readonly disabledBehavior?: DisabledBehavior;
+  /** The keys of the rows drawn disabled. */
+  readonly disabledKeys?: Iterable<Key>;
+  /**
+   * Keeps the last selected row selected, so a press on it changes nothing.
+   * @default false
+   */
+  readonly disallowEmptySelection?: boolean;
+  /** Called as a column is dragged, with every column's width. */
+  readonly onResize?: (widths: Map<Key, ColumnSize>) => void;
+  /** Called once a drag ends, with every column's width. */
+  readonly onResizeEnd?: (widths: Map<Key, ColumnSize>) => void;
+  /**
+   * Called with a row's key when a press runs its action. A row's own
+   * `onAction` takes its place for that row.
+   */
+  readonly onRowAction?: (key: Key) => void;
+  /** Called with the selected keys whenever a press changes them. */
+  readonly onSelectionChange?: (keys: Selection) => void;
+  /** Called with the column and direction a press on a header asks for. */
+  readonly onSortChange?: (descriptor: SortDescriptor) => void;
+  readonly ref?: Ref<FlatList>;
+  /**
+   * Lets the columns marked `resizable` be dragged.
+   * @default false
+   */
+  readonly resizable?: boolean;
+  /**
+   * What a resize handle is called, for a screen reader, before its column's
+   * name. Left out, it is the word for it in the `I18nProvider`'s language,
+   * or the device's outside one, "Resizer" in English.
+   */
+  readonly resizeLabel?: string;
+  /**
+   * What the select-all checkbox is called, for a screen reader. Left out,
+   * it is the word for it in the `I18nProvider`'s language, or the device's
+   * outside one, "Select All" in English, or "Select" while one row at a
+   * time selects.
+   */
+  readonly selectAllLabel?: string;
+  /** The selected keys, for a call site holding the selection itself. */
+  readonly selectedKeys?: 'all' | Iterable<Key>;
+  /**
+   * Whether rows can be selected: one at a time, several, or none.
+   * @default 'none'
+   */
+  readonly selectionMode?: SelectionMode;
+  /**
+   * What selecting a row is called, for a screen reader: the accessibility
+   * action that selects a row. Left out, it is the word for it in the
+   * `I18nProvider`'s language, or the device's outside one, "Select" in
+   * English.
+   */
+  readonly selectLabel?: string;
+  /** The column the rows are sorted by, and in which direction. */
+  readonly sortDescriptor?: SortDescriptor;
+  /**
+   * Holds the header row in place while the rows scroll under it. Needs the
+   * table to have a height to scroll in.
+   * @default false
+   */
+  readonly stickyHeader?: boolean;
+  readonly style?: StyleProp<ViewStyle>;
+};
+type TableRowProps<T extends object = object> = Omit<PressableProps, 'children' | 'disabled' | 'id' | 'role' | 'style'> & {
+  /**
+   * The row's cells, one `Table.Cell` for each column it spans, or a
+   * function from a column's key to its cell.
+   */
+  readonly children?: ((columnKey: Key) => ReactElement) | ReactNode;
+  /** Goes to this route when a press runs the row's action. */
+  readonly href?: string;
+  /**
+   * The key the row is selected and reported by. Give one to every row, and
+   * keep it apart from every column's.
+   */
+  readonly id?: Key;
+  /**
+   * Draws the row disabled, as a key in the table's `disabledKeys` does.
+   * @default false
+   */
+  readonly isDisabled?: boolean;
+  /**
+   * Called when a press runs the row's action, in place of the table's
+   * `onRowAction` for this row.
+   */
+  readonly onAction?: () => void;
+  readonly ref?: Ref<HostInstance>;
+  readonly style?: StyleProp<ViewStyle>;
+  /** The row's text, for a row whose cells hold elements. */
+  readonly textValue?: string;
+  /** The entry `children` was drawn for, kept on the row's node. */
+  readonly value?: T;
+};
+declare function bodyNode(props: TableBodyProps): Generator<{
+  childNodes(): Generator<{
+    renderer: (item: object) => ReactElement;
+    type: string;
+    value: object;
+    element?: undefined;
+  } | {
+    element: ReactNode;
+    type: string;
+    renderer?: undefined;
+    value?: undefined;
+  }, void, unknown>;
+  hasChildNodes: boolean;
+  props: TableBodyProps<object>;
+  type: string;
+}, void, unknown>;
+declare function cellNode(props: TableCellProps): Generator<{
+  hasChildNodes: boolean;
+  props: TableCellProps;
+  rendered: ReactNode;
+  textValue: string;
+  type: string;
+}, void, unknown>;
+declare function columnNode(props: TableColumnProps, context: BuilderContext): Generator<object, void, readonly Node<unknown>[]>;
+declare function headerNodes(props: TableHeaderProps, context: BuilderContext): Generator<{
+  renderer: (column: object) => ReactElement;
+  type: string;
+  value: object;
+  element?: undefined;
+} | {
+  element: ReactNode;
+  type: string;
+  renderer?: undefined;
+  value?: undefined;
+}, void, unknown>;
+declare function rowNode(props: TableRowProps, context: BuilderContext): Generator<{
+  'aria-label': string | undefined;
+  childNodes(): Generator<{
+    element: ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+    key: Key;
+    type: string;
+  } | {
+    element: ReactNode;
+    type: string;
+    key?: undefined;
+  }, void, unknown>;
+  hasChildNodes: boolean;
+  key: Key | undefined;
+  props: TableRowProps<object>;
+  shouldInvalidate(next: BuilderContext): boolean;
+  textValue: string | undefined;
+  type: string;
+}, void, unknown>;
+/**
+ * A grid of rows and columns. Sorting and selection are React Stately's, as
+ * web's are React Aria's: pass `sortDescriptor` with `onSortChange` and mark
+ * the sortable columns `allowsSorting`, and set `selectionMode` to `single`
+ * or `multiple` with `selectedKeys` and `onSelectionChange`, or
+ * `defaultSelectedKeys`.
+ *
+ * ```tsx
+ * <Table aria-label="Label" selectionMode="multiple">
+ *   <Table.Header>
+ *     <Table.Column id="colSelect" selection />
+ *     <Table.Column id="colName" isRowHeader>Label</Table.Column>
+ *   </Table.Header>
+ *   <Table.Body>
+ *     <Table.Row id="first">
+ *       <Table.Cell selection />
+ *       <Table.Cell>First item</Table.Cell>
+ *     </Table.Row>
+ *   </Table.Body>
+ * </Table>
+ * ```
+ *
+ * Composed from parts, since a cell takes any content: `Table.Header`,
+ * `Table.Column`, `Table.Body`, `Table.Row`, `Table.Cell`, `Table.LoadMore`
+ * and `Table.Footer`, which the table draws from their props, so none of them
+ * renders anything on its own. A column's `id` and a row's share one
+ * namespace, so keep the two sets apart, as `col`-prefixed column ids do.
+ * Name the table with `aria-label`.
+ *
+ * The columns fill the table's width, `1fr` each unless `defaultWidth` or
+ * `width` says otherwise, and the table scrolls sideways once they are wider
+ * than it is. The rows scroll by themselves, so a table on a page that
+ * scrolls takes `scrollEnabled={false}` and is laid out at its full length,
+ * and one with `stickyHeader` wants a height to fill. `style` lands on the
+ * box the table is drawn in, and `ref`, `aria-label`, `testID` and the
+ * scroll props on the `FlatList` that holds the rows.
+ *
+ * The rows take focus while they run past the table's height, as web's grid
+ * is a tab stop, so a keyboard can scroll them whatever they hold, and the
+ * sideways scroll does while the columns are wider than the table; a call
+ * site's own `focusable` still wins for the rows.
+ */
+declare function Table({ children, defaultSelectedKeys, disabledBehavior, disabledKeys, disallowEmptySelection, onSelectionChange, onSortChange, selectedKeys, selectionMode, sortDescriptor, ...props }: TableProps): import("react").JSX.Element;
+declare namespace Table {
+  var Body: typeof TableBody;
+  var Cell: typeof TableCell;
+  var Column: typeof TableColumn;
+  var Footer: typeof TableFooter;
+  var Header: typeof TableHeader;
+  var LoadMore: typeof TableLoadMore;
+  var Row: typeof TableRow;
+}
+/**
+ * The rows. `renderEmptyState` is what the table shows when there are none,
+ * and a `Table.LoadMore` after them is the row it shows while fetching
+ * more. The table draws it from its props, so it renders nothing on its
+ * own.
+ */
+declare function TableBody<T extends object = object>(_props: TableBodyProps<T>): null;
+declare namespace TableBody {
+  var getCollectionNode: typeof bodyNode;
+}
+/**
+ * One cell. `selection` draws this row's checkbox in place of whatever else
+ * the cell would hold. `style` and `testID` land on the cell.
+ */
+declare function TableCell(_props: TableCellProps): null;
+declare namespace TableCell {
+  var getCollectionNode: typeof cellNode;
+}
+/**
+ * One column. `allowsSorting` makes the header itself the control that
+ * sorts; the arrow appears on the column the `sortDescriptor` names.
+ * `selection` draws the select-all checkbox in place of a name. `style` and
+ * `testID` land on the column's header.
+ *
+ * Its `id` shares a namespace with the rows', so give the two sets values
+ * that cannot meet: a column and a row with one id between them leaves the
+ * table with no columns at all.
+ */
+declare function TableColumn(_props: TableColumnProps): null;
+declare namespace TableColumn {
+  var getCollectionNode: typeof columnNode;
+}
+/**
+ * Rows under the body, for totals and the like, ruled off from it. They are
+ * not part of the selection and take no press, as React Aria keeps a footer
+ * out of both. `style` and `testID` land on the footer.
+ */
+declare function TableFooter(_props: TableFooterProps): null;
+/**
+ * The header row, holding the columns, and the rule drawn under it. `style`
+ * and `testID` land on the row.
+ */
+declare function TableHeader<T extends object = object>(_props: TableHeaderProps<T>): null;
+declare namespace TableHeader {
+  var getCollectionNode: typeof headerNodes;
+}
+/**
+ * The row shown while more rows are being fetched. `onLoadMore` is called
+ * as the reader nears the end of the table, and the ring is drawn only while
+ * `isLoading`, in a live region, so a screen reader hears it arrive. It goes
+ * inside `Table.Body`, after the rows.
+ */
+declare function TableLoadMore(_props: TableLoadMoreProps): null;
+/**
+ * One row. Give every row an `id`, which is the key selection is reported
+ * by, and keep it apart from every column's. `onAction` runs when a press
+ * runs the row's action, and `href` goes to that route. `style`, `ref` and
+ * `testID` land on the row.
+ */
+declare function TableRow<T extends object = object>(_props: TableRowProps<T>): null;
+declare namespace TableRow {
+  var getCollectionNode: typeof rowNode;
+}
+//#endregion
+export { Table, TableBody, type TableBodyProps, TableCell, type TableCellProps, TableColumn, type TableColumnProps, TableFooter, type TableFooterProps, TableHeader, type TableHeaderProps, TableLoadMore, type TableLoadMoreProps, type TableProps, TableRow, type TableRowProps };
+//# sourceMappingURL=index.d.ts.map