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

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

@@ -0,0 +1,140 @@
+import { OverlayAlign, OverlaySide } from "../../overlay/placement.js";
+import "../../overlay/index.js";
+import { HostInstance, StyleProp, TextProps, ViewProps, ViewStyle } from "react-native";
+import { ReactNode, Ref, RefObject } from "react";
+//#region src/components/popover/index.d.ts
+/** Where the panel sits along the side it opens on. */
+type PopoverAlign = OverlayAlign;
+type PopoverContentProps = Omit<ViewProps, 'children' | 'role' | 'style'> & {
+  /**
+   * Where the panel sits along the side it opens on. On `top` and `bottom`,
+   * `start` and `end` follow a right-to-left layout.
+   * @default 'center'
+   */
+  readonly align?: PopoverAlign;
+  /** Moves the panel along that side, in dp: right or down when positive. */
+  readonly alignOffset?: number;
+  readonly children?: ReactNode;
+  readonly ref?: Ref<HostInstance>;
+  /**
+   * Which side of the trigger the panel opens on. It flips to the opposite
+   * side when there is no room.
+   * @default 'bottom'
+   */
+  readonly side?: PopoverSide;
+  /**
+   * The gap between the trigger and the panel, in dp.
+   * @default spacing.sm
+   */
+  readonly sideOffset?: number;
+  readonly style?: StyleProp<ViewStyle>;
+  /** A view to place the panel beside other than the trigger. */
+  readonly triggerRef?: RefObject<HostInstance | null>;
+};
+type PopoverDescriptionProps = TextProps & {
+  readonly ref?: Ref<HostInstance>;
+};
+type PopoverProps = {
+  /** The button that opens the popover, and `Popover.Content`. */
+  readonly children?: ReactNode;
+  /**
+   * How long the pointer has to be gone from a hovered popover's trigger
+   * and panel before it closes, in milliseconds. Ignored by a pressed one.
+   * @default 200
+   */
+  readonly closeDelay?: number;
+  /** Whether the popover starts open, when it keeps its own state. */
+  readonly defaultOpen?: boolean;
+  /**
+   * How long a pointer rests on a hover trigger, or a press is held on it,
+   * before the popover opens, in milliseconds. Ignored by a pressed one.
+   * @default 600
+   */
+  readonly delay?: number;
+  /** Whether the popover is open, when the call site holds the state. */
+  readonly isOpen?: boolean;
+  /**
+   * Keeps a screen reader inside the panel while it is open, as a dialog
+   * does. Off by default: a popover leaves the screen in reach, which is the
+   * difference from `Sheet`. A hovered popover is never modal.
+   * @default false
+   */
+  readonly modal?: boolean;
+  /** Called with the new state as the popover opens or closes. */
+  readonly onOpenChange?: (isOpen: boolean) => void;
+  /**
+   * The panel's width: `sm` caps it at 240dp, `md` at 320dp. Either way it is
+   * only as wide as its content.
+   * @default 'md'
+   */
+  readonly size?: PopoverSize;
+  /**
+   * What opens the panel: a press on the trigger, or a pointer resting on
+   * it. `hover` is the tooltips page's rich tooltip, and on touch it opens
+   * on a press held for `delay`.
+   * @default 'press'
+   */
+  readonly trigger?: PopoverTrigger;
+};
+/** Which side of the trigger the panel opens on. */
+type PopoverSide = OverlaySide;
+type PopoverSize = 'md' | 'sm';
+type PopoverTitle = {
+  readonly id: string;
+  readonly setTitle: (node: HostInstance | null) => void;
+};
+type PopoverTitleProps = Omit<TextProps, 'role'> & {
+  readonly ref?: Ref<HostInstance>;
+};
+type PopoverTrigger = 'hover' | 'press';
+/**
+ * A panel anchored to the control that opened it, as the tooltips spec
+ * page's rich tooltip draws one. Pass `isOpen` with `onOpenChange` to hold
+ * the open state, or `defaultOpen` to let it keep its own.
+ *
+ * ```tsx
+ * <Popover>
+ *   <Button variant="outlined">Open</Button>
+ *   <Popover.Content>
+ *     <Popover.Title>Headline</Popover.Title>
+ *     <Popover.Description>Supporting text</Popover.Description>
+ *   </Popover.Content>
+ * </Popover>
+ * ```
+ *
+ * Non-modal by default, which leaves the screen in reach of a screen reader,
+ * and `modal` keeps one inside it. A press outside the panel and a button
+ * given `slot="close"` inside it close it, and a press on its trigger
+ * toggles it. Composed rather than configured by props, as web's is: a
+ * `Button` or `IconButton` placed directly inside `Popover` is its trigger,
+ * and the panel is placed beside it.
+ */
+declare function Popover({ children, closeDelay, defaultOpen, delay, isOpen, modal, onOpenChange, size, trigger }: PopoverProps): import("react").JSX.Element;
+declare namespace Popover {
+  var Content: typeof PopoverContent;
+  var Description: typeof PopoverDescription;
+  var Title: typeof PopoverTitle;
+}
+/**
+ * The panel itself. Everything the popover shows goes in here; the trigger
+ * stays outside it. Its content scrolls when it runs past the room the
+ * window leaves on the side it opened on.
+ *
+ * `style`, `ref` and `testID` land on the panel.
+ */
+declare function PopoverContent({ triggerRef, ...props }: PopoverContentProps): import("react").JSX.Element | null;
+/**
+ * Supporting text under the title, in body medium on on-surface variant.
+ * `style`, `ref` and `testID` land on React Native's own Text.
+ */
+declare function PopoverDescription({ style, ...props }: PopoverDescriptionProps): import("react").JSX.Element;
+/**
+ * Names the popover: the panel is labelled by it, and a screen reader is
+ * sent to it once a pressed popover shows. In title small on on-surface
+ * variant, the rich tooltip's subhead. `style`, `ref` and `testID` land on
+ * React Native's own Text.
+ */
+declare function PopoverTitle({ ref, style, ...props }: PopoverTitleProps): import("react").JSX.Element;
+//#endregion
+export { Popover, type PopoverAlign, PopoverContent, type PopoverContentProps, PopoverDescription, type PopoverDescriptionProps, type PopoverProps, type PopoverSide, type PopoverSize, PopoverTitle, type PopoverTitleProps, type PopoverTrigger };
+//# sourceMappingURL=index.d.ts.map