@kanso-labs/react-native-kanso-ui 0.4.0 → 0.5.0

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

@@ -0,0 +1,216 @@
+import { ReactElement, ReactNode, Ref } from "react";
+import { FlatList, HostInstance, PressableProps, ScrollViewProps, StyleProp, ViewStyle } from "react-native";
+import { Key, Selection, SelectionMode } from "react-stately";
+//#region src/components/list/index.d.ts
+type ListLoadMoreProps = {
+  /**
+   * Draws the ring in a row of its own while more items are being fetched.
+   * @default false
+   */
+  readonly isLoading?: boolean;
+  /**
+   * What a screen reader calls the ring, and hears as it appears. Left out,
+   * it is the word for it in the device's language, "Loading more" in
+   * English.
+   */
+  readonly label?: string;
+  /**
+   * Called when the end of the list comes within `scrollOffset` of its
+   * visible end, while nothing is loading. Called once for each length the
+   * list reaches, so a load that adds nothing does not start another.
+   */
+  readonly onLoadMore?: () => void;
+  /**
+   * How far past the visible end of the list the next items are asked for,
+   * as a share of the list's visible height.
+   * @default 1
+   */
+  readonly scrollOffset?: number;
+  readonly style?: StyleProp<ViewStyle>;
+  readonly testID?: string;
+};
+type ListProps<T extends object = object> = Omit<ScrollViewProps, 'children' | 'role' | 'stickyHeaderIndices' | 'style'> & {
+  /**
+   * The rows, each a `List.Item`, `List.Section` or `List.LoadMore`. With
+   * `items`, a function from an item to its part, called for each item in
+   * turn.
+   */
+  readonly children?: ((item: T) => ReactElement) | ReactNode;
+  /** The keys selected at first, when the list keeps its own selection. */
+  readonly defaultSelectedKeys?: 'all' | Iterable<Key>;
+  /** The keys of the rows drawn disabled, which take no presses. */
+  readonly disabledKeys?: Iterable<Key>;
+  /**
+   * Keeps the last selected row selected, so a press on it changes nothing.
+   * @default false
+   */
+  readonly disallowEmptySelection?: boolean;
+  /** The entries `children` draws a part for, when it is a function. */
+  readonly items?: Iterable<T>;
+  /**
+   * Called with a row's key when a press runs its action. A row's own
+   * `onAction` takes its place for that row.
+   */
+  readonly onAction?: (key: Key) => void;
+  /** Called with the selected keys whenever a press changes them. */
+  readonly onSelectionChange?: (keys: Selection) => void;
+  readonly ref?: Ref<FlatList>;
+  /**
+   * What the list shows when it has no rows and nothing is loading. Left
+   * out, it is a muted row saying "No results" in the device's language, so
+   * the list keeps a row's height.
+   */
+  readonly renderEmptyState?: () => ReactNode;
+  /**
+   * The selected keys, for a call site holding the selection itself with
+   * `onSelectionChange`.
+   */
+  readonly selectedKeys?: 'all' | Iterable<Key>;
+  /**
+   * Whether rows can be selected: one at a time, several, or none. A list
+   * that selects draws a checkbox on every row.
+   * @default 'none'
+   */
+  readonly selectionMode?: SelectionMode;
+  /**
+   * What selecting a row is called, for a screen reader: the accessibility
+   * action each selectable row offers, which is what its checkbox does. The
+   * row's own text is what names the row. Left out, it is the word for it in
+   * the device's language, "Select" in English.
+   */
+  readonly selectLabel?: string;
+  readonly style?: StyleProp<ViewStyle>;
+};
+type ListRowProps = Omit<PressableProps, 'children' | 'disabled' | 'id' | 'role' | 'style'> & {
+  /** The row's headline, the one thing it is mostly about. */
+  readonly children?: ReactNode;
+  /** The key the row is selected and reported by. Give one to every row. */
+  readonly id?: Key;
+  /**
+   * Draws the row disabled, and takes no presses on it, as a key in the
+   * list's `disabledKeys` does.
+   * @default false
+   */
+  readonly isDisabled?: boolean;
+  /** Content before the headline: an avatar, an icon. */
+  readonly leading?: ReactNode;
+  /**
+   * Called when a press runs the row's action, in place of the list's
+   * `onAction` for this row.
+   */
+  readonly onAction?: () => void;
+  /**
+   * A line above the headline, in label small and the muted role. Given
+   * beside `supporting`, it makes the row the three-line item.
+   */
+  readonly overline?: ReactNode;
+  readonly ref?: Ref<HostInstance>;
+  readonly style?: StyleProp<ViewStyle>;
+  /** A second line under the headline, in body medium and the muted role. */
+  readonly supporting?: ReactNode;
+  /**
+   * The row's text, read off `children` when they are a plain string, so a
+   * row whose headline is an element passes it.
+   */
+  readonly textValue?: string;
+  /** Content after the headline, such as an amount or a control. */
+  readonly trailing?: ReactNode;
+};
+type ListSectionProps = {
+  /** The rows in the section. */
+  readonly children?: ReactNode;
+  /**
+   * The section's heading, which stays at the top of the list while the
+   * section's rows scroll under it. A section without one is its rows alone.
+   */
+  readonly header?: ReactNode;
+  readonly id?: Key;
+};
+/**
+ * A list of rows, one or more of which can be selected. Selection is React
+ * Stately's, as web's is React Aria's: set `selectionMode` to `single` or
+ * `multiple`, and pass `selectedKeys` with `onSelectionChange` to control
+ * it or `defaultSelectedKeys` to let it keep its own. A list whose rows do
+ * something takes `onAction`, or an `onAction` on each row.
+ *
+ * ```tsx
+ * <List aria-label="Label" selectionMode="multiple">
+ *   <List.Item id="first" supporting="Supporting line">First item</List.Item>
+ * </List>
+ * ```
+ *
+ * ListItem is the row on its own; this is the collection that draws the
+ * same row and adds selection, sections and a row that loads more. Composed
+ * from parts, `List.Item`, `List.Section` and `List.LoadMore`, which the
+ * list draws from their props, so none of them renders anything on its
+ * own. Name the list with `aria-label`. It scrolls by itself, so it wants a
+ * height to fill: a short list on a page that scrolls takes
+ * `scrollEnabled={false}` and is laid out at its full length. `style` and
+ * `ref` land on the `FlatList`.
+ *
+ * Inside an `Autocomplete`, the list shows the rows the search keeps and
+ * says how many there are to a screen reader, and a tap on a row reaches it
+ * while the keyboard is up.
+ */
+declare function List<T extends object = object>({ children, contentContainerStyle, defaultSelectedKeys, disabledKeys, disallowEmptySelection, items, keyboardShouldPersistTaps, onAction, onSelectionChange, ref, renderEmptyState, selectedKeys, selectionMode, selectLabel, style, ...props }: ListProps<T>): import("react").JSX.Element;
+declare namespace List {
+  var Item: typeof ListRow;
+  var LoadMore: typeof ListLoadMore;
+  var Section: typeof ListSection;
+}
+/**
+ * The row shown while more items are being fetched. `onLoadMore` is called
+ * as the reader nears the end of the list, and the ring is drawn only while
+ * `isLoading`, in a live region, so a screen reader hears it arrive. It
+ * goes last, after the rows it loads more of.
+ */
+declare function ListLoadMore(_props: ListLoadMoreProps): null;
+declare namespace ListLoadMore {
+  var getCollectionNode: (props: ListLoadMoreProps) => Generator<{
+    hasChildNodes: boolean;
+    props: ListLoadMoreProps;
+    rendered: null;
+    type: string;
+  }, void, unknown>;
+}
+/**
+ * One row. Its slots are ListItem's: `leading`, the headline as children,
+ * `overline` above it, `supporting` under it, and `trailing`. Give every
+ * row an `id`, which is the key selection is reported by. A list that
+ * selects draws a checkbox before whatever `leading` holds.
+ *
+ * The list draws it from its entry in the collection, so it renders nothing
+ * on its own. `style`, `ref` and `testID` land on the row.
+ */
+declare function ListRow(_props: ListRowProps): null;
+declare namespace ListRow {
+  var getCollectionNode: (props: ListRowProps) => Generator<{
+    'aria-label': string | undefined;
+    hasChildNodes: boolean;
+    key: Key | undefined;
+    props: ListRowProps;
+    rendered: ReactNode;
+    textValue: string;
+    type: string;
+  }, void, unknown>;
+}
+/**
+ * A group of rows under a heading, which stays at the top of the list while
+ * the group's rows scroll under it.
+ */
+declare function ListSection(_props: ListSectionProps): null;
+declare namespace ListSection {
+  var getCollectionNode: (props: ListSectionProps) => Generator<{
+    childNodes(): Generator<{
+      element: ReactNode;
+    }, void, unknown>;
+    hasChildNodes: boolean;
+    key: Key | undefined;
+    props: ListSectionProps;
+    rendered: ReactNode;
+    type: string;
+  }, void, unknown>;
+}
+//#endregion
+export { List, ListLoadMore, type ListLoadMoreProps, type ListProps, ListRow, type ListRowProps, ListSection, type ListSectionProps };
+//# sourceMappingURL=index.d.ts.map