@kanso-labs/kanso-ui 0.44.1 → 0.45.0

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

@@ -1,9 +1,6 @@
 import { HTMLAttributes, ReactNode, RefAttributes } from "react";
-import { ClassNameOrFunction, DialogProps, DialogTriggerProps, HeadingProps, ModalOverlayProps, ModalRenderProps, StyleOrFunction } from "react-aria-components";
+import { ClassNameOrFunction, DialogProps, DialogTriggerProps, HeadingProps, ModalOverlayProps, SheetRenderProps, StyleOrFunction } from "react-aria-components";
 //#region src/components/sheet/index.d.ts
-type SheetProps = Omit<DialogTriggerProps, 'children'> & {
-  children?: ReactNode;
-};
 /**
  * A modal panel that arrives from the edge of the screen — a side sheet on a
  * wide viewport, a bottom sheet on a narrow one. Open state is React Aria's:
@@ -17,16 +14,42 @@ type SheetProps = Omit<DialogTriggerProps, 'children'> & {
  * given `slot="close"` anywhere inside the content closes it; neither needs
  * a part of its own.
  *
+ * ```tsx
+ * <Sheet>
+ *   <Button>Open</Button>
+ *   <Sheet.Content>
+ *     <Sheet.Handle />
+ *     <Sheet.Header>
+ *       <Sheet.Title>Headline</Sheet.Title>
+ *     </Sheet.Header>
+ *     <Sheet.Body>Supporting line</Sheet.Body>
+ *     <Sheet.Footer>
+ *       <Button slot="close">Close</Button>
+ *     </Sheet.Footer>
+ *   </Sheet.Content>
+ * </Sheet>
+ * ```
+ *
  * `Sheet` is the trigger's half, so a sheet nothing on the page opens — one
  * a route shows, or a menu item raises — leaves it out and passes `isOpen`
  * and `onOpenChange` to `Sheet.Content` instead. Wrapped in `Sheet` with no
  * button inside it, React Aria warns that its press responder found nothing
  * to press.
+ *
+ * ```tsx
+ * <Sheet.Content isOpen={isOpen} onOpenChange={setOpen}>
+ *   …
+ * </Sheet.Content>
+ * ```
+ *
+ * Tab stays inside an open sheet, so a `Snackbar` shown meanwhile is reached
+ * with F6, which React Aria uses to move between landmarks. Tabbing on past
+ * the snackbar's last control leads back into the sheet.
  */
-declare function Sheet({ children, ...props }: SheetProps): import("react").JSX.Element;
-declare namespace Sheet {
+declare function Sheet$1({ children, ...props }: SheetProps): import("react").JSX.Element;
+declare namespace Sheet$1 {
   var Body: typeof SheetBody;
-  var Content: typeof SheetContent;
+  var Content: typeof SheetContent$1;
   var Footer: typeof SheetFooter;
   var Handle: typeof SheetHandle;
   var Header: typeof SheetHeader;
@@ -38,43 +61,56 @@ declare function SheetBody({ ref: callerRef, ...props }: HTMLAttributes<HTMLDivE
  * in here; the trigger stays outside it, since the trigger lives in the page
  * while this is portalled out to the end of the body.
  *
- * A press on the scrim closes the sheet unless `isDismissable` says
- * otherwise — React Aria's own default is the reverse, and a sheet that
- * ignores a tap outside it reads as stuck.
+ * A swipe toward the edge the panel rests on closes it — down on a bottom
+ * sheet, toward the screen's edge on a side sheet — as do a press on the
+ * scrim, Escape and a `slot="close"` button. `isDismissable` holds the first
+ * two, and `isKeyboardDismissDisabled` holds Escape. React Aria's default for
+ * the scrim is the reverse of this one: a sheet that ignores a tap outside it
+ * reads as stuck.
  *
  * Inside `Sheet`, the open state is the trigger's. On its own, with no
  * trigger, it is this part's: `isOpen` with `onOpenChange` controls it, and
- * a `slot="close"` button, Escape and the scrim all report through
+ * a swipe, a `slot="close"` button, Escape and the scrim all report through
  * `onOpenChange`, as they would to `Sheet`.
  *
- * The scrim draws at `z-index: 900`, over any page content layered below
- * that, such as a sticky header, and the panel draws inside it. A
+ * The sheet draws at `z-index: 900`, the scrim and the panel over it, over
+ * any page content layered below that, such as a sticky header. A
  * `Snackbar` draws at 1000, so a toast raised from inside the sheet is read
  * over it, and React Aria's popovers and menus draw above both.
+ *
+ * React Aria lays the sheet over the page from the page's own top-left
+ * corner rather than fixing it to the window, so a `container` inside a
+ * positioned element holds the sheet to that element instead.
  */
-declare function SheetContent({ children, className, container, defaultOpen, isDismissable, isKeyboardDismissDisabled, isOpen, onOpenChange, ref, style, ...props }: RefAttributes<HTMLDivElement> & SheetContentProps): import("react").JSX.Element;
+declare function SheetContent$1({ children, className, container, defaultOpen, isDismissable, isKeyboardDismissDisabled, isOpen, onOpenChange, ref, snapPoints, style, ...props }: RefAttributes<HTMLDivElement> & SheetContentProps): import("react").JSX.Element;
 /**
- * The sheet's actions. The panel is pinned to the window's bottom edge in
- * both presentations, so they sit on that edge, and a toast rises clear of
- * them while the sheet is open rather than lying over its buttons. A side
- * sheet's are included: the toast is centred in the window, and on any
- * window narrower than about 1376px its 576 reach into the sheet's 400.
+ * The sheet's actions. The panel rests on the window's bottom edge in both
+ * presentations, so they sit on that edge, and a toast rises clear of them
+ * while the sheet is open rather than lying over its buttons. A side sheet's
+ * are included: the toast is centred in the window, and on any window
+ * narrower than about 1376px its 576 reach into the sheet's 400.
  */
 declare function SheetFooter({ ref: callerRef, ...props }: HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>): import("react").JSX.Element;
 /**
  * The bottom sheets page's drag handle: a short bar above the sheet's
- * content, saying the panel is a bottom sheet. Place it first inside
- * `Sheet.Content`; above the medium breakpoint the panel is a side sheet and
- * this draws nothing.
+ * content, saying the panel is a bottom sheet that a swipe moves. Place it
+ * first inside `Sheet.Content`; above the medium breakpoint the panel is a
+ * side sheet and this draws nothing.
+ *
+ * On a sheet given `snapPoints` it is a button, as the bottom sheets page
+ * asks of a handle that moves the sheet between heights: a press, from a
+ * pointer, a keyboard or assistive technology, moves the sheet to its next
+ * snap point, from the last back to the first, and `aria-expanded` says
+ * whether it rests at the last. It is called "Drag handle" in the locale's
+ * own words, and a call site's `aria-label` names it instead. Its 48 square
+ * is the page's target, centred over the bar.
  *
- * It is decoration rather than a control, and hidden from assistive
- * technology. Material's own handle drags a sheet between a collapsed and an
- * expanded height and dismisses it from the collapsed one; this panel has
- * one height and cannot be dragged, so a control that only looked draggable
- * would promise what it cannot do. Closing is already the scrim, Escape, and
- * any button given `slot="close"`.
+ * On a sheet without them it is decoration, hidden from assistive
+ * technology: the panel has one height, and the swipe the bar points at
+ * takes it from anywhere on the panel, so a control here would offer
+ * nothing a swipe, the scrim, Escape or a `slot="close"` button does not.
  */
-declare function SheetHandle(props: HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>): import("react").JSX.Element;
+declare function SheetHandle({ 'aria-label': label, ...props }: HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>): import("react").JSX.Element;
 declare function SheetHeader(props: HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>): import("react").JSX.Element;
 /**
  * Names the sheet. Rendered through React Aria's title slot, which is what
@@ -82,9 +118,9 @@ declare function SheetHeader(props: HTMLAttributes<HTMLDivElement> & RefAttribut
  * itself as an unnamed dialog.
  */
 declare function SheetTitle(props: RefAttributes<HTMLHeadingElement> & SheetTitleProps): import("react").JSX.Element;
-type SheetContentProps = Omit<DialogProps, 'className' | 'style'> & Pick<ModalOverlayProps, 'defaultOpen' | 'isKeyboardDismissDisabled' | 'isOpen' | 'onOpenChange'> & {
+type SheetContentProps = Omit<DialogProps, 'className' | 'style'> & Pick<ModalOverlayProps, 'defaultOpen' | 'isOpen' | 'onOpenChange'> & {
   /** A function may compute the class from the panel's render state. */
-  className?: ClassNameOrFunction<ModalRenderProps>;
+  className?: ClassNameOrFunction<SheetRenderProps>;
   /**
    * Where to portal the panel and scrim. Defaults to the container of the
    * `ThemeScope` around it, which keeps the sheet on that scope's tokens, or
@@ -94,17 +130,40 @@ type SheetContentProps = Omit<DialogProps, 'className' | 'style'> & Pick<ModalOv
    */
   container?: Element;
   /**
-   * Whether a press on the scrim, outside the panel, closes the sheet.
-   * `true` here where React Aria's own default is `false`, since a sheet
-   * that ignores a tap outside it reads as stuck. Escape is
-   * `isKeyboardDismissDisabled`'s, and this says nothing about it.
+   * Whether a press on the scrim, outside the panel, or a swipe toward the
+   * edge it rests on closes the sheet. `true` here where React Aria's own
+   * default for the scrim is `false`, since a sheet that ignores a tap
+   * outside it reads as stuck. Escape is `isKeyboardDismissDisabled`'s, and
+   * this says nothing about it.
    * @default true
    */
   isDismissable?: boolean;
+  /**
+   * Whether Escape is kept from closing the sheet. The scrim and the swipe
+   * are `isDismissable`'s, and this says nothing about them.
+   * @default false
+   */
+  isKeyboardDismissDisabled?: boolean;
+  /**
+   * The heights a bottom sheet rests at, each the amount of the panel
+   * showing: a number of pixels, or a percentage of the panel's own
+   * height. The sheet opens at the first, a swipe moves it between them,
+   * and a press on `Sheet.Handle` moves it to the next, from the last
+   * back to the first. React Aria's own prop, under its own name.
+   *
+   * End on `'100%'` for a sheet that can show all of itself: its body
+   * scrolls only while the whole panel is showing, and short of that a
+   * swipe on the body moves the sheet instead. The side sheet has one
+   * width and ignores them.
+   */
+  snapPoints?: Array<number | string>;
   /** A function may compute the style from the panel's render state. */
-  style?: StyleOrFunction<ModalRenderProps>;
+  style?: StyleOrFunction<SheetRenderProps>;
+};
+type SheetProps = Omit<DialogTriggerProps, 'children'> & {
+  children?: ReactNode;
 };
 type SheetTitleProps = HeadingProps;
 //#endregion
-export { SheetBody, SheetContent, type SheetContentProps, SheetFooter, SheetHandle, SheetHeader, type SheetProps, SheetTitle, type SheetTitleProps, Sheet as default };
+export { SheetBody, SheetContent$1 as SheetContent, type SheetContentProps, SheetFooter, SheetHandle, SheetHeader, type SheetProps, SheetTitle, type SheetTitleProps, Sheet$1 as default };
 //# sourceMappingURL=index.d.ts.map