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

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

@@ -0,0 +1,309 @@
+import { OverlayAlign, OverlaySide } from "../../overlay/placement.js";
+import "../../overlay/index.js";
+import { ReactElement, ReactNode, Ref } from "react";
+import { HostInstance, PressableProps, StyleProp, ViewProps, ViewStyle } from "react-native";
+import { Key, Selection, SelectionMode } from "react-stately";
+//#region src/components/menu/index.d.ts
+type ItemNodeProps = MenuItemProps & {
+  readonly submenu?: ReactElement<MenuContentProps>;
+};
+type MenuAlign = OverlayAlign;
+type MenuContentProps<T extends object = object> = Omit<ViewProps, 'children' | 'role' | 'style'> & {
+  /**
+   * Where the menu lines up along the side it opens on. On `top` and
+   * `bottom`, `start` and `end` follow a right-to-left layout.
+   * @default 'start'
+   */
+  readonly align?: MenuAlign;
+  /**
+   * Moves the menu along that side, in dp: right or down when positive.
+   * Left out, a submenu moves up by the surface's own padding, which puts
+   * its first item level with the one that opened it.
+   */
+  readonly alignOffset?: number;
+  /**
+   * The items, each a `Menu.Item`, `Menu.Section`, `Menu.Separator`,
+   * `Menu.Submenu` or `Menu.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 menu keeps its own selection. */
+  readonly defaultSelectedKeys?: 'all' | Iterable<Key>;
+  /** The keys of the items drawn disabled, which take no presses. */
+  readonly disabledKeys?: Iterable<Key>;
+  /**
+   * Keeps the last selected item 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 an item's key when a press on it runs its action. */
+  readonly onAction?: (key: Key) => void;
+  /** Called when a press on an item closes the menu. */
+  readonly onClose?: () => void;
+  /** Called with the selected keys whenever a press changes them. */
+  readonly onSelectionChange?: (keys: Selection) => void;
+  readonly ref?: Ref<HostInstance>;
+  /**
+   * What the menu shows when nothing is in it. Left out, it is a muted row
+   * saying "No results" in the device's language, so the menu 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 a press selects an item: one at a time, several, or none, in
+   * which case a press runs the item's action alone.
+   * @default 'none'
+   */
+  readonly selectionMode?: SelectionMode;
+  /**
+   * Whether a press on an item closes the menu. Left out, it does unless the
+   * menu selects several items at once, or the item has an `href`.
+   */
+  readonly shouldCloseOnSelect?: boolean;
+  /**
+   * Which side of the trigger the menu opens on. It flips to the opposite
+   * side when there is no room. Left out, a menu opens below its trigger and
+   * a submenu at the inline end of the item that opens it.
+   */
+  readonly side?: MenuSide;
+  /**
+   * The gap between the trigger and the menu, in dp. Left out, a menu sits
+   * `spacing.sm` from its trigger and a submenu against its item.
+   */
+  readonly sideOffset?: number;
+  readonly style?: StyleProp<ViewStyle>;
+};
+type MenuItemProps = Omit<PressableProps, 'children' | 'disabled' | 'id' | 'role' | 'style'> & {
+  /** The item's label: what it does. */
+  readonly children?: ReactNode;
+  /**
+   * Where a press on the item leads, through the app's router as Button's
+   * `href` does. An item with one closes the menu whatever the selection.
+   */
+  readonly href?: string;
+  /**
+   * The key the item is selected and reported by. Give one to every item
+   * the call site needs to tell apart.
+   */
+  readonly id?: Key;
+  /**
+   * Draws the item disabled, and takes no presses on it, as a key in the
+   * menu's `disabledKeys` does.
+   * @default false
+   */
+  readonly isDisabled?: boolean;
+  /**
+   * Content before the label, usually an icon, which takes the label's
+   * colour at 24dp. A selected item draws the check here in its place.
+   */
+  readonly leading?: ReactNode;
+  /**
+   * Called when a press runs the item's action, in place of the menu's
+   * `onAction` for this item.
+   */
+  readonly onAction?: () => void;
+  readonly ref?: Ref<HostInstance>;
+  readonly style?: StyleProp<ViewStyle>;
+  /**
+   * The item's text, read off `children` when they are a plain string, so
+   * an item whose label is an element passes it.
+   */
+  readonly textValue?: string;
+  /** Content after the label. */
+  readonly trailing?: ReactNode;
+};
+type MenuLoadMoreProps = {
+  /**
+   * 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 while it shows. Left out, it is the
+   * word for it in the device's language, "Loading more" in English.
+   */
+  readonly label?: string;
+  /**
+   * Called when the row comes within `scrollOffset` of the menu's visible
+   * end, while nothing is loading.
+   */
+  readonly onLoadMore?: () => void;
+  /**
+   * How far past the visible end of the menu the row starts loading, as a
+   * share of the menu's visible height.
+   * @default 1
+   */
+  readonly scrollOffset?: number;
+  readonly style?: StyleProp<ViewStyle>;
+  readonly testID?: string;
+};
+type MenuProps = {
+  /** The trigger, then the `Menu.Content` it opens. */
+  readonly children?: ReactNode;
+  /** Whether the menu starts open, when it keeps its own state. */
+  readonly defaultOpen?: boolean;
+  /** Whether the menu is open, when the call site holds the state. */
+  readonly isOpen?: boolean;
+  /** Called with the new state as the menu opens or closes. */
+  readonly onOpenChange?: (isOpen: boolean) => void;
+  /**
+   * What opens the menu: a press on the trigger, or a press held on it, in
+   * which case a plain press runs the trigger's own `onPress`.
+   * @default 'press'
+   */
+  readonly trigger?: MenuTrigger;
+};
+type MenuSectionProps = {
+  readonly 'aria-label'?: string;
+  /** The items in the section. */
+  readonly children?: ReactNode;
+  /**
+   * The section's heading, which names the group. A section without one is
+   * a group with no name, and takes `aria-label` for one instead.
+   */
+  readonly header?: ReactNode;
+  readonly id?: Key;
+};
+type MenuSeparatorProps = {
+  readonly style?: StyleProp<ViewStyle>;
+  readonly testID?: string;
+};
+type MenuSide = OverlaySide;
+type MenuSubmenuProps = {
+  /**
+   * The item that opens the submenu, then the `Menu.Content` it opens.
+   * Exactly those two, in that order.
+   */
+  readonly children: readonly [trigger: ReactElement<MenuItemProps>, content: ReactElement<MenuContentProps>];
+};
+type MenuTrigger = 'longPress' | 'press';
+/**
+ * A list of actions or choices opened from a control. Pass `isOpen` with
+ * `onOpenChange` to hold the open state, or `defaultOpen` to let it keep its
+ * own.
+ *
+ * ```tsx
+ * <Menu>
+ *   <Button variant="outlined">Open</Button>
+ *   <Menu.Content>
+ *     <Menu.Item id="first">First item</Menu.Item>
+ *   </Menu.Content>
+ * </Menu>
+ * ```
+ *
+ * A `Button` or `IconButton` placed directly inside `Menu` is its trigger,
+ * and a press on it toggles the menu. Everything the menu shows goes in
+ * `Menu.Content`, since the trigger lives in the screen while the menu is
+ * drawn above it.
+ */
+declare function Menu({ children, defaultOpen, isOpen, onOpenChange, trigger }: MenuProps): import("react").JSX.Element;
+declare namespace Menu {
+  var Content: typeof MenuContent;
+  var Item: typeof MenuItem;
+  var LoadMore: typeof MenuLoadMore;
+  var Section: typeof MenuSection;
+  var Separator: typeof MenuSeparator;
+  var Submenu: typeof MenuSubmenu;
+}
+/**
+ * The menu itself, and the surface it is drawn on. Its items scroll when they
+ * run past the room the window leaves on the side it opened on.
+ *
+ * A menu with nothing in it shows a muted "No results" row in place of its
+ * items; pass `renderEmptyState` to draw something else.
+ *
+ * `style`, `ref` and `testID` land on the surface.
+ */
+declare function MenuContent<T extends object = object>(props: MenuContentProps<T>): import("react").JSX.Element | null;
+/**
+ * One action or choice. Its slots are the row's: `leading` before the label,
+ * the label as children, and `trailing` after it. A selected item draws the
+ * check, in place of `leading` where it has one and at the end of the row
+ * where it has none, so choosing an item moves nothing in the menu. An item
+ * that opens a submenu draws the chevron itself.
+ *
+ * The menu 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 MenuItem(_props: MenuItemProps): null;
+declare namespace MenuItem {
+  var getCollectionNode: (props: ItemNodeProps) => Generator<{
+    'aria-label': string | undefined;
+    hasChildNodes: boolean;
+    key: Key | undefined;
+    props: ItemNodeProps;
+    rendered: ReactNode;
+    textValue: string;
+    type: string;
+  }, void, unknown>;
+}
+/**
+ * The row shown while more items are being fetched. `onLoadMore` is called
+ * when it comes near the visible end of the menu, and the ring is drawn only
+ * while `isLoading`. It goes last, after the items it loads more of.
+ */
+declare function MenuLoadMore(_props: MenuLoadMoreProps): null;
+declare namespace MenuLoadMore {
+  var getCollectionNode: (props: MenuLoadMoreProps) => Generator<{
+    hasChildNodes: boolean;
+    props: MenuLoadMoreProps;
+    rendered: null;
+    type: string;
+  }, void, unknown>;
+}
+/**
+ * A named group of items. `header` names it, and is what a screen reader
+ * reads before the items inside.
+ */
+declare function MenuSection(_props: MenuSectionProps): null;
+declare namespace MenuSection {
+  var getCollectionNode: (props: MenuSectionProps) => Generator<{
+    'aria-label': string | undefined;
+    childNodes(): Generator<{
+      element: ReactNode;
+    }, void, unknown>;
+    hasChildNodes: boolean;
+    key: Key | undefined;
+    props: MenuSectionProps;
+    rendered: ReactNode;
+    type: string;
+  }, void, unknown>;
+}
+/** A rule between groups of items, with the menus page's 8dp either side. */
+declare function MenuSeparator(_props: MenuSeparatorProps): null;
+declare namespace MenuSeparator {
+  var getCollectionNode: (props: MenuSeparatorProps) => Generator<{
+    hasChildNodes: boolean;
+    props: MenuSeparatorProps;
+    rendered: null;
+    type: string;
+  }, void, unknown>;
+}
+/**
+ * An item that opens a menu of its own. Takes exactly two children: the
+ * `Menu.Item` that opens it, then the `Menu.Content` it opens. A press on
+ * the item opens it, and a second press closes it.
+ */
+declare function MenuSubmenu(_props: MenuSubmenuProps): null;
+declare namespace MenuSubmenu {
+  var getCollectionNode: (props: MenuSubmenuProps) => Generator<{
+    'aria-label': string | undefined;
+    hasChildNodes: boolean;
+    key: Key | undefined;
+    props: ItemNodeProps;
+    rendered: ReactNode;
+    textValue: string;
+    type: string;
+  }, void, unknown>;
+}
+//#endregion
+export { Menu, type MenuAlign, MenuContent, type MenuContentProps, MenuItem, type MenuItemProps, MenuLoadMore, type MenuLoadMoreProps, type MenuProps, MenuSection, type MenuSectionProps, MenuSeparator, type MenuSeparatorProps, type MenuSide, MenuSubmenu, type MenuSubmenuProps, type MenuTrigger };
+//# sourceMappingURL=index.d.ts.map