@windmorph/react 0.0.0-stage → 0.1.1

package/dist/components/dialog/Dialog.d.ts

@@ -0,0 +1,267 @@
+import { ClosedBy } from "../../utils/closed-by.js";
+import { CSSProperties, ComponentPropsWithRef, ReactNode } from "react";
+import { AriaDialogProps } from "react-aria";
+//#region src/components/dialog/Dialog.d.ts
+/**
+ * When a dialog fills the window (the M3 full-screen dialog): `never`, `always`, or
+ * `compact` for windows narrower than 600px only, the M3 recommendation.
+ */
+export type DialogFullScreen = 'never' | 'always' | 'compact';
+/**
+ * How a basic dialog enters and leaves: `reveal`, the M3 dialog motion, or `scale`, the
+ * original pop (a fade with a scale from 90%).
+ */
+export type DialogTransition = 'reveal' | 'scale';
+/** Where a basic dialog sits in the window, keeping the spec's 56px margin on wider windows. */
+export type DialogPlacement = 'center' | 'top' | 'bottom' | 'start' | 'end';
+/**
+ * What a full-screen dialog grows out of (a container transform): `"trigger"` for the
+ * `DialogTrigger`'s button, an element such as a FAB, or a box in window coordinates.
+ */
+export type DialogOrigin = 'trigger' | Element | DOMRectReadOnly;
+export interface DialogTriggerProps {
+  /** The trigger (a Button, IconButton, …) followed by the `Dialog`. */
+  children: ReactNode;
+  /** Controlled open state. */
+  open?: boolean;
+  /** Initial open state when uncontrolled. @default false */
+  defaultOpen?: boolean;
+  /** Called when the dialog opens or closes. */
+  onOpenChange?: (open: boolean) => void;
+}
+/**
+ * Opens a `Dialog` from a button. The first child is the trigger (any button-like
+ * component); the rest is the dialog.
+ *
+ * @example
+ * <DialogTrigger>
+ *   <Button>Delete</Button>
+ *   <Dialog>…</Dialog>
+ * </DialogTrigger>
+ */
+export declare function DialogTrigger({ children, open, defaultOpen, onOpenChange }: DialogTriggerProps): import("react").JSX.Element;
+export interface DialogClassNames {
+  /** The dimmed layer behind the dialog. */
+  scrim?: string;
+  /**
+   * The fixed, full-window flex box that places the dialog. It pads 24px on compact windows
+   * and 56px from the medium breakpoint, and `placement` sets its alignment, so alignment
+   * classes here (`items-*`, `justify-*`) position the dialog anywhere within the spec's
+   * margin, and padding classes change that margin.
+   */
+  positioner?: string;
+  /** The dialog's surface: its colour, corners, padding, size and shadow. */
+  panel?: string;
+  /** The icon above the title. */
+  icon?: string;
+}
+export interface DialogRenderProps {
+  /** Closes the dialog. */
+  close: () => void;
+}
+export interface DialogProps extends Omit<ComponentPropsWithRef<'div'>, 'children' | 'role'>, Omit<AriaDialogProps, 'role'> {
+  /** Controlled open state, when not inside a `DialogTrigger`. */
+  open?: boolean;
+  /** Initial open state when uncontrolled, when not inside a `DialogTrigger`. @default false */
+  defaultOpen?: boolean;
+  /** Called when the dialog opens or closes. */
+  onOpenChange?: (open: boolean) => void;
+  /**
+   * Basic dialogs are alert dialogs on the web (the spec): they need a decision, are
+   * described by their `DialogContent`, and aren't dismissed by pressing outside. A dialog
+   * that can be full screen is a `dialog`.
+   * @default "alertdialog", or "dialog" when fullScreen isn't "never"
+   */
+  role?: 'dialog' | 'alertdialog';
+  /**
+   * How the user can close the dialog, as HTML's `<dialog closedby>`: `any` (Escape or a
+   * press outside), `closerequest` (Escape only) or `none` (only its own buttons or the app).
+   * @default "closerequest" for an alertdialog, "any" otherwise
+   */
+  closedBy?: ClosedBy;
+  /** Icon above the title (which is then centred). Decorative. Not shown in full screen. */
+  icon?: ReactNode;
+  /**
+   * Fills the window, with a `DialogHeader` holding the close button, title and confirming
+   * action instead of `DialogActions` (or with them as a bottom bar when the header has no
+   * action). `compact`, the spec's recommendation, does so only below 600px; `always` fills
+   * every window. @default "never"
+   */
+  fullScreen?: DialogFullScreen;
+  /**
+   * Grows the full-screen dialog out of this origin and shrinks it back into it on close,
+   * the spec's container transform from a FAB: `"trigger"` (the `DialogTrigger`'s button),
+   * an element, or a box in window coordinates. The clip, corners and container colour
+   * move from the origin to the window on the slow spatial spring and the content fades
+   * in; reduced motion keeps only the fades. Used only while the dialog is full screen.
+   */
+  origin?: DialogOrigin;
+  /**
+   * Where a basic dialog sits: centred (the spec's default) or against one side of the
+   * window, keeping 24px from its edges on compact windows and 56px on wider ones. For any
+   * other position, align it with `classNames.positioner` (for example
+   * `"items-start justify-end"` for the top end corner). It also sets the motion's
+   * direction: centred or at the top the dialog slides down and grows downward as it
+   * enters, at the bottom up, and at the start or end along the x axis (mirrored in
+   * right-to-left layouts).
+   * @default "center"
+   */
+  placement?: DialogPlacement;
+  children?: ReactNode | ((props: DialogRenderProps) => ReactNode);
+  /**
+   * Classes for the dialog's parts, merged over the library's: `scrim`, `positioner` (the
+   * full-window box that places the dialog; align it anywhere with `items-*` and
+   * `justify-*`), `panel` (the surface) and `icon`.
+   */
+  classNames?: DialogClassNames;
+  /** Goes on the outermost element, with `className`. */
+  style?: CSSProperties;
+  /**
+   * How a basic dialog enters and leaves. `reveal` is the M3 dialog motion: it slides 50px
+   * away from the edge it sits against while its container grows from that edge, and its
+   * headline and content, then its actions, fade in. `scale` is the library's original pop,
+   * an extension beyond the M3 motion: the dialog fades in while it scales up from 90%, and
+   * fades out while it scales to 95%, from the centre (`placement="center"`) or from the edge
+   * it sits against. Either way reduced motion keeps only the fades and `instant` turns the
+   * motion off. A full-screen dialog keeps its own motion and ignores it.
+   * @default "reveal"
+   */
+  transition?: DialogTransition;
+  /**
+   * Skips the enter and exit motion: the dialog, its parts and the scrim appear and leave at
+   * once, and the dialog leaves the document as soon as it closes. Reduced motion already
+   * keeps only the fades. @default false
+   */
+  instant?: boolean;
+  /**
+   * Called when the dialog has finished opening: once its enter motion (the slide, the
+   * container's growth and every part's fade) has ended, or right after it opens with
+   * `instant`. Not called when it closes before then.
+   */
+  onOpened?: () => void;
+  /**
+   * Called when the dialog has finished closing: once its exit motion has ended and it has
+   * left the document, or right after it closes with `instant`.
+   */
+  onClosed?: () => void;
+}
+/**
+ * M3 basic dialog: a modal panel over a scrim, rendered in a portal that keeps the
+ * surrounding theme. It's an alert dialog (described by its `DialogContent`). Focus moves
+ * to its first interactive element (or one marked `autoFocus`), is contained, and is
+ * restored on close; Escape closes it; the page behind does not scroll and is hidden from
+ * assistive tech. Name it with a `DialogTitle` (or `aria-label`).
+ *
+ * It enters with the M3 dialog motion: it slides 50px away from the window edge it sits
+ * against while its container grows from that edge, then its headline and content fade in,
+ * then its actions; it leaves by fading its parts, sliding back and shrinking, then fading.
+ * Any children take part: the actions phase is for `DialogActions` (or any child with
+ * `data-slot="actions"`), and every other child fades in with the content. `onOpened` and
+ * `onClosed` report the end of each motion; `instant` turns it off.
+ *
+ * `className` and `style` go on the outermost element, a full-window layer around the
+ * positioner whose inline placement they can't move, so a layout class (`static`,
+ * `overflow-hidden`, a transform) never hides, clips or stretches the dialog; style the
+ * surface with `classNames.panel`. `ref` and other attributes go on the dialog panel.
+ *
+ * @example
+ * <Dialog icon={<DeleteIcon />}>
+ *   {({ close }) => (
+ *     <>
+ *       <DialogTitle>Delete 3 files?</DialogTitle>
+ *       <DialogContent>They will be removed from all devices.</DialogContent>
+ *       <DialogActions>
+ *         <Button variant="text" onPress={close}>Cancel</Button>
+ *         <Button variant="text" onPress={remove}>Delete</Button>
+ *       </DialogActions>
+ *     </>
+ *   )}
+ * </Dialog>
+ */
+export declare function Dialog({ open, defaultOpen, onOpenChange, origin, onClosed, ...props }: DialogProps): import("react").JSX.Element | null;
+export type DialogTitleProps = ComponentPropsWithRef<'h2'>;
+/**
+ * The dialog's headline; it also names the dialog for assistive tech. In a dialog that can
+ * be full screen, use `DialogHeader` instead.
+ */
+export declare function DialogTitle({ className, ...props }: DialogTitleProps): import("react").JSX.Element;
+export interface DialogHeaderClassNames {
+  /** The header row; `className` is merged here too. */
+  root?: string;
+  /** The close button. */
+  close?: string;
+  /** The headline. */
+  title?: string;
+}
+/** Words a {@link DialogHeader} announces. */
+export interface DialogHeaderLabels {
+  /** The full-screen close button's name. @default "Close" */
+  close: string;
+}
+export interface DialogHeaderProps extends Omit<ComponentPropsWithRef<'div'>, 'title'> {
+  /** The headline; it names the dialog. */
+  children: ReactNode;
+  /** Words the header announces, with English defaults. */
+  labels?: Partial<DialogHeaderLabels>;
+  /**
+   * The confirming action, usually a text `Button` ("Save"). Shown in full screen only;
+   * without it, a full-screen dialog shows its `DialogActions` as a bottom bar.
+   */
+  action?: ReactNode;
+  /** A 1px `outline-variant` divider under the full-screen header. @default false */
+  divider?: boolean;
+  /**
+   * Disables the full-screen close button, e.g. while the confirming action is saving, so the
+   * dialog can't be left halfway. Pair it with the `Dialog`'s `closedBy="none"` to keep Escape
+   * from closing it too. @default false
+   */
+  closeDisabled?: boolean;
+  /** Classes for each part, by slot. */
+  classNames?: DialogHeaderClassNames;
+}
+/**
+ * The headline of a dialog that can be full screen. In full screen it is the M3 full-screen
+ * dialog's header: a close icon button, the headline and the confirming action. Otherwise
+ * it is a plain `DialogTitle`, and the dialog's `DialogActions` carry the actions.
+ *
+ * @example
+ * <Dialog fullScreen="compact">
+ *   <DialogHeader action={<Button variant="text" onPress={save}>Save</Button>}>
+ *     Edit name
+ *   </DialogHeader>
+ *   <DialogContent>…</DialogContent>
+ *   <DialogActions>…</DialogActions>
+ * </Dialog>
+ */
+export declare function DialogHeader({ children, labels, action, divider, closeDisabled, className, classNames, ...props }: DialogHeaderProps): import("react").JSX.Element;
+export interface DialogContentProps extends ComponentPropsWithRef<'div'> {
+  /**
+   * The basic dialog's optional dividers: 1px `outline-variant` lines across the panel
+   * above and below the content, e.g. around a scrolling list. Not drawn in full screen.
+   * @default false
+   */
+  dividers?: boolean;
+}
+/**
+ * The dialog's supporting text or content; scrolls when the dialog is too tall. It describes
+ * an alert dialog. While it scrolls it is focusable (with a focus ring), so the keyboard can
+ * scroll it (`data-scrollable`); the dialog's initial focus still goes to its first control.
+ */
+export declare function DialogContent({ className, dividers, ref, ...props }: DialogContentProps): import("react").JSX.Element;
+export type DialogActionsProps = ComponentPropsWithRef<'div'>;
+/**
+ * Row of actions at the end of the dialog, 8px apart. Put the confirming action last:
+ * when the actions do not fit on one line they stack with it on top (M3: "Confirming
+ * actions appear above dismissive actions"). Stacked, the buttons are rendered in that
+ * visual order, so Tab and screen readers reach the confirming action first, top to bottom,
+ * as they reach the dismissive one first in a row. When the actions are the dialog's first
+ * controls, its initial focus goes to the dismissive action, stacked (the bottom one) or
+ * not: the least destructive choice, as the WAI-ARIA alert dialog pattern asks; a stack
+ * that forms or unforms later keeps focus where it is. While the dialog is full screen they're
+ * hidden when `DialogHeader` carries the confirming action, and otherwise form the spec's
+ * 56px bottom action bar. Use at most two actions (the spec); in development it warns once
+ * when it holds more.
+ */
+export declare function DialogActions({ className, children, ref, ...props }: DialogActionsProps): import("react").JSX.Element;
+//#endregion
+//# sourceMappingURL=Dialog.d.ts.map