@mond-design-system/react 1.0.0-alpha.3 → 1.0.0-alpha.4

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { CSSProperties, HTMLAttributes, JSX, ReactElement, ReactNode, ButtonHTMLAttributes, ElementType, Ref, AnchorHTMLAttributes, MouseEventHandler, InputHTMLAttributes, TextareaHTMLAttributes, SelectHTMLAttributes, RefObject, KeyboardEvent } from 'react';
+import { CSSProperties, HTMLAttributes, JSX, ReactElement, ReactNode, ButtonHTMLAttributes, ElementType, Ref, ComponentPropsWithoutRef, MouseEventHandler, InputHTMLAttributes, TextareaHTMLAttributes, SelectHTMLAttributes, RefObject, KeyboardEvent } from 'react';
 
 /**
  * Join class names, dropping anything falsy.
@@ -120,7 +120,7 @@ interface IconProps extends HTMLAttributes<HTMLSpanElement> {
 /** A glyph from the app-registered set, sized on the core scale. */
 declare function Icon({ name, size, label, className, ...rest }: IconProps): ReactElement;
 
-type ButtonVariant = "primary" | "secondary" | "ghost" | "danger" | "highlight";
+type ButtonVariant = "primary" | "secondary" | "ghost" | "danger" | "warning" | "highlight";
 type ButtonSize = "sm" | "md" | "lg";
 interface ButtonBaseProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type"> {
     variant?: ButtonVariant;
@@ -160,7 +160,7 @@ declare function Button({ variant, size, iconLeft, iconRight, loading, disabled,
 
 type LinkVariant = "inline" | "standalone" | "plain";
 type LinkSize = "xs" | "sm" | "base" | "lg" | "xl";
-interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+type LinkOwnProps<E extends ElementType> = {
     /** inline = underlined, lives in running text. standalone = nav/action link.
         plain = inherits the surrounding color and weight, underlines on hover —
         for links whose context already marks them (a card title, a list row). */
@@ -169,10 +169,12 @@ interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
     size?: LinkSize;
     /** Opens in a new tab with rel protection. */
     external?: boolean;
-    /** Element override, e.g. a router's Link. */
-    as?: ElementType;
-    ref?: Ref<HTMLAnchorElement>;
-}
+    /** Element override — `'button'` for a link-styled action, or a router's
+        Link component, whose own props (`to`, `href`, …) then type-check. */
+    as?: E;
+    children?: ReactNode;
+};
+type LinkProps<E extends ElementType = "a"> = LinkOwnProps<E> & Omit<ComponentPropsWithoutRef<E>, keyof LinkOwnProps<E>>;
 /**
  * Text link. Inline links keep their underline: color alone fails WCAG 1.4.1
  * for links inside prose.
@@ -180,10 +182,10 @@ interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
  * ```tsx
  * <Text>Read the <Link href="/terms">terms</Link>.</Text>
  * <Link variant="standalone" href="https://example.com" external>Docs</Link>
- * <Link as={NextLink} href="/about">About</Link>
+ * <Link as={RouterLink} to="/about">About</Link>
  * ```
  */
-declare function Link({ variant, size, external, as: Element, className, ...rest }: LinkProps): ReactElement;
+declare function Link<E extends ElementType = "a">({ variant, size, external, as, ...rest }: LinkProps<E>): ReactElement;
 
 type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
 /** One of the five brand identity tints (`--mds-avatar-tone-1..5`). */
@@ -722,12 +724,14 @@ declare function SearchField({ label, value, onChange, className, ...rest }: Sea
 
 interface ListGroupProps extends HTMLAttributes<HTMLUListElement> {
     children: ReactNode;
+    /** Heading over the group. Also names the list to a screen reader. */
+    label?: ReactNode;
 }
 /**
  * Card-styled list container for ListItems.
  *
  * ```tsx
- * <ListGroup>
+ * <ListGroup label="Account">
  *   <ListItem
  *     title="Profile"
  *     description="Name, avatar"
@@ -738,7 +742,7 @@ interface ListGroupProps extends HTMLAttributes<HTMLUListElement> {
  * </ListGroup>
  * ```
  */
-declare function ListGroup({ className, ...rest }: ListGroupProps): ReactElement;
+declare function ListGroup({ label, className, ...rest }: ListGroupProps): ReactElement;
 type ListItemSurface = "card" | "sunken" | "accent" | "plain";
 interface ListItemProps extends Omit<HTMLAttributes<HTMLElement>, "title" | "onClick"> {
     title: ReactNode;
@@ -749,6 +753,10 @@ interface ListItemProps extends Omit<HTMLAttributes<HTMLElement>, "title" | "onC
     trailing?: ReactNode;
     /** Makes the whole row a button. */
     onClick?: () => void;
+    /** Marks an onClick row as a toggle — a picker row that selects rather than
+        navigates. Lands as aria-pressed on the row button itself, where the
+        screen reader's focus is. Leave unset for rows that navigate. */
+    pressed?: boolean;
     /** Makes the whole row a link. Wins over onClick. */
     href?: string;
     /** What the row paints behind itself. Inside a ListGroup the group is the
@@ -763,7 +771,7 @@ interface ListItemProps extends Omit<HTMLAttributes<HTMLElement>, "title" | "onC
  * One row. Static by default; interactive as one whole-row button/link.
  * An `<li>` inside a ListGroup, a standalone `<div>` row anywhere else.
  */
-declare function ListItem({ title, description, leading, trailing, onClick, href, surface, className, ...rest }: ListItemProps): ReactElement;
+declare function ListItem({ title, description, leading, trailing, onClick, pressed, href, surface, className, ...rest }: ListItemProps): ReactElement;
 
 interface EmptyStateProps {
     title: string;
@@ -840,6 +848,12 @@ interface ToastContextValue {
 declare function useToast(): ToastContextValue;
 interface ToastProviderProps {
     children: ReactNode;
+    /** Accessible name of the notification region (localise). Default "Notifications". */
+    regionLabel?: string | undefined;
+    /** Prefix of each dismiss button's accessible name (localise). The toast's
+     *  title follows it, so every dismiss control names its own toast. Default
+     *  "Dismiss" — a button labelled "Dismiss: Saved". */
+    dismissLabel?: string | undefined;
 }
 /**
  * Mount once near the root. Renders the notification region itself.
@@ -855,7 +869,7 @@ interface ToastProviderProps {
  * toast({ title: "Saved", tone: "success" });
  * ```
  */
-declare function ToastProvider({ children }: ToastProviderProps): ReactElement;
+declare function ToastProvider({ children, regionLabel, dismissLabel, }: ToastProviderProps): ReactElement;
 
 type StackGap = "hairline" | "tight" | "base" | "loose" | "section";
 type StackAlign = "start" | "center" | "end" | "stretch";
@@ -926,11 +940,15 @@ interface ContainerProps extends HTMLAttributes<HTMLElement> {
  */
 declare function Container({ width, as, className, ...rest }: ContainerProps): ReactElement;
 
-type CardVariant = "card" | "raised";
+type CardVariant = "card" | "raised" | "sunken";
 interface CardProps extends Omit<HTMLAttributes<HTMLElement>, "onClick"> {
     children: ReactNode;
-    /** card = flat on border, raised = elevated. Default "card". */
+    /** card = flat on border, raised = elevated, sunken = recessed fill for
+        secondary tiles. Default "card". */
     variant?: CardVariant;
+    /** Accent border — marks the card out from its neighbours (a pinned post,
+        the active choice) without changing its surface. */
+    emphasis?: boolean;
     /** Makes the whole card a button. */
     onClick?: () => void;
     /** Makes the whole card a link. Wins over onClick. */
@@ -950,7 +968,7 @@ interface CardProps extends Omit<HTMLAttributes<HTMLElement>, "onClick"> {
  * <Card href="/items/42" variant="flat">…</Card>
  * ```
  */
-declare function Card({ children, variant, onClick, href, className, ...rest }: CardProps): ReactElement;
+declare function Card({ children, variant, emphasis, onClick, href, className, ...rest }: CardProps): ReactElement;
 type CardSectionProps = HTMLAttributes<HTMLDivElement>;
 /** Top slot — title row, media, tabs. */
 declare function CardHeader({ className, ...rest }: CardSectionProps): ReactElement;
@@ -966,6 +984,8 @@ interface ModalProps {
     label: string;
     /** Scrim click dismisses. Default true. */
     closeOnScrimClick?: boolean;
+    /** alertdialog interrupts — ConfirmDialog sets it. Default "dialog". */
+    role?: "dialog" | "alertdialog";
     children: ReactNode;
 }
 /**
@@ -980,7 +1000,7 @@ interface ModalProps {
  * </Modal>
  * ```
  */
-declare function Modal({ open, onClose, label, closeOnScrimClick, children }: ModalProps): react.JSX.Element;
+declare function Modal({ open, onClose, label, closeOnScrimClick, role, children }: ModalProps): react.JSX.Element;
 declare function ModalHeader({ children }: {
     children: ReactNode;
 }): react.JSX.Element;
@@ -1012,9 +1032,18 @@ interface SheetProps {
  * ```
  */
 declare function Sheet({ open, onClose, label, closeOnScrimClick, children }: SheetProps): react.JSX.Element;
-declare function SheetHeader({ children }: {
+type SheetHeaderProps = {
     children: ReactNode;
-}): react.JSX.Element;
+} & ({
+    /** Renders a close button after the title. Wire it to the sheet's own onClose. */
+    onClose: () => void;
+    /** Accessible name of the close button (localise). */
+    closeLabel: string;
+} | {
+    onClose?: undefined;
+    closeLabel?: undefined;
+});
+declare function SheetHeader({ children, onClose, closeLabel }: SheetHeaderProps): react.JSX.Element;
 declare function SheetBody({ children }: {
     children: ReactNode;
 }): react.JSX.Element;
@@ -1022,33 +1051,61 @@ declare function SheetFooter({ children }: {
     children: ReactNode;
 }): react.JSX.Element;
 
-interface ConfirmDialogProps {
-    open: boolean;
-    onClose: () => void;
-    onConfirm: () => void;
+type ConfirmDialogTone = "default" | "danger" | "warning";
+interface ConfirmDialogProps<T = void> {
+    /** The row in question, or null when nothing is being asked. Held by the
+        caller — only it knows which row was tapped — and handed back to
+        `onConfirm`, so the action runs against the row the user actually saw. */
+    target?: T | null;
+    /** Defaults to "there is a row in question"; pass it directly for a
+        one-off prompt that has no row. */
+    open?: boolean;
+    /** Cancel, or the action having landed. Clear the row here. */
+    onClose?: () => void;
+    /** The action, given the row it was asked about. Return the promise the
+        write is riding on — typically `mutateAsync(...)` — and do not catch:
+        a handled rejection resolves, and a resolved action is
+        indistinguishable from a write that landed. Typed as a promise so
+        fire-and-forget is a type error rather than a prompt that closes on
+        the click. */
+    onConfirm?: (target: T) => Promise<unknown>;
+    /** Short question, e.g. "Delete session?" */
     title: string;
-    description?: string | undefined;
+    /** Consequence explained in a sentence or two. */
+    description?: ReactNode;
     confirmLabel: string;
-    cancelLabel?: string | undefined;
-    /** Style the confirm action as destructive. */
-    danger?: boolean | undefined;
+    /** @default "Cancel" */
+    cancelLabel?: string;
+    /** Styles the confirm action: danger for destructive, warning for
+        consequential-but-recoverable. */
+    tone?: ConfirmDialogTone;
+    /** How to phrase a failure, given the error's own message. Defaults to
+        that message — supply this rather than catching inside `onConfirm`,
+        so the copy stays with the caller. */
+    errorMessage?: (message: string) => string;
 }
 /**
- * Pre-composed Modal for the confirm/cancel pattern.
+ * A binary confirm/cancel prompt for consequential actions. role="alertdialog"
+ * so assistive tech announces it and holds focus until the user decides.
+ *
+ * The prompt owns everything downstream of the tap: it stays busy until
+ * `onConfirm` settles, closes only once the write has landed, and keeps
+ * itself up with the reason shown if it fails. Callers supply the question,
+ * not the mechanics.
  *
  * ```tsx
  * <ConfirmDialog
- *   open={open}
- *   onClose={() => setOpen(false)}
- *   onConfirm={deleteItem}
- *   title="Delete item?"
+ *   target={asked}
+ *   onClose={() => setAsked(null)}
+ *   onConfirm={(row) => remove.mutateAsync(row.id)}
+ *   title="Delete session?"
  *   description="This cannot be undone."
  *   confirmLabel="Delete"
- *   danger
+ *   tone="danger"
  * />
  * ```
  */
-declare function ConfirmDialog({ open, onClose, onConfirm, title, description, confirmLabel, cancelLabel, danger, }: ConfirmDialogProps): react.JSX.Element;
+declare function ConfirmDialog<T = void>({ target, open, onClose, onConfirm, title, description, confirmLabel, cancelLabel, tone, errorMessage, }: ConfirmDialogProps<T>): react.JSX.Element;
 
 /**
  * Page scaffold. Compose:
@@ -1060,17 +1117,36 @@ declare function ConfirmDialog({ open, onClose, onConfirm, title, description, c
  *   <TabBar label="Primary">…</TabBar>
  * </Screen>
  * ```
+ *
+ * Fills the height its host gives it — the app root, a device frame, a
+ * `flex: 1; min-height: 0` slot — rather than claiming the viewport itself:
+ * on iOS the software keyboard shrinks the visual viewport without shrinking
+ * 100dvh, so only the host can know the real height. A standalone app gives
+ * the root chain `height: 100%`.
  */
 declare function Screen({ children }: {
     children: ReactNode;
 }): react.JSX.Element;
-/** The scrollable main region of a Screen. */
-declare function ScreenContent({ children }: {
+interface ScreenContentProps extends HTMLAttributes<HTMLElement> {
     children: ReactNode;
-}): react.JSX.Element;
+    /** Drop the page gutter — full-bleed lists whose rows carry their own
+        padding. Default keeps it: forms and prose want the margin. */
+    flush?: boolean;
+    /** The scrolling element. A screen that drives the scroll — restores an
+        offset on back, pins a thread to the bottom — has no other way to reach
+        it. Read it; restyling it is the sheet's job. */
+    ref?: Ref<HTMLElement>;
+}
+/** The scrollable main region of a Screen. */
+declare function ScreenContent({ children, flush, className, ref, ...rest }: ScreenContentProps): react.JSX.Element;
 
 interface AppBarProps {
-    title?: string | undefined;
+    /** Page heading — rendered as the h1. A node is allowed for titles that
+        are themselves a control (e.g. a thread title that opens the event). */
+    title?: ReactNode;
+    /** Second line under the title — a member count, a status. Kept out of
+        the h1 so the accessible page name stays just the title. */
+    subtitle?: ReactNode;
     /** Left slot — typically a back icon-only Button. */
     leading?: ReactNode;
     /** Right slot — actions. */
@@ -1090,7 +1166,7 @@ interface AppBarProps {
  * />
  * ```
  */
-declare function AppBar({ title, leading, trailing }: AppBarProps): react.JSX.Element;
+declare function AppBar({ title, subtitle, leading, trailing }: AppBarProps): react.JSX.Element;
 
 interface TabBarProps {
     /** Accessible name of the navigation landmark. */
@@ -1116,8 +1192,20 @@ interface TabBarItemProps {
     href?: string | undefined;
     onClick?: MouseEventHandler | undefined;
     active?: boolean | undefined;
+    /** Attention dot on the icon — unread, pending. Boolean only: the count
+        lives on the destination screen, the bar just says "something's there". */
+    badge?: boolean | undefined;
+}
+declare function TabBarItem({ label, icon, href, onClick, active, badge }: TabBarItemProps): react.JSX.Element;
+interface TabBarActionProps {
+    /** Names the action — icon-only, so this is all a screen reader gets. */
+    label: string;
+    icon: ReactNode;
+    onClick?: MouseEventHandler | undefined;
 }
-declare function TabBarItem({ label, icon, href, onClick, active }: TabBarItemProps): react.JSX.Element;
+/** Raised center action (a create button). Place it between the item halves:
+    it is a peer child, and the bar's flex layout leaves it its own width. */
+declare function TabBarAction({ label, icon, onClick }: TabBarActionProps): react.JSX.Element;
 
 interface UseOverlayOptions {
     open: boolean;
@@ -1197,4 +1285,4 @@ interface RovingGroupOptions {
  */
 declare function useRovingGroup(ref: RefObject<HTMLElement | null>, { selector, orientation }: RovingGroupOptions): (event: KeyboardEvent<HTMLElement>) => void;
 
-export { AppBar, type AppBarProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, Badge, type BadgeProps, type BadgeTone, Button, type ButtonProps, type ButtonSize, type ButtonVariant, type CSSVars, Card, CardBody, CardFooter, CardHeader, type CardProps, type CardSectionProps, type CardVariant, Checkbox, type CheckboxProps, Chip, ChipBar, type ChipBarGap, type ChipBarProps, ChipGroup, type ChipGroupGap, type ChipGroupProps, type ChipProps, type ChipVariant, ConfirmDialog, type ConfirmDialogProps, Container, type ContainerProps, type ContainerWidth, CountButton, type CountButtonProps, type CountButtonTone, DateTimePicker, type DateTimePickerLabels, type DateTimePickerProps, Divider, type DividerProps, EmptyState, type EmptyStateProps, Field, type FieldContextValue, type FieldProps, Heading, type HeadingLevel, type HeadingProps, type HeadingTone, Icon, type IconProps, IconProvider, type IconProviderProps, type IconRender, type IconRenderProps, type IconSize, Inline, type InlineAlign, type InlineGap, type InlineJustify, type InlineProps, Input, type InputProps, type InputSize, Link, type LinkProps, type LinkVariant, ListGroup, type ListGroupProps, ListItem, type ListItemProps, Modal, ModalBody, ModalFooter, ModalHeader, type ModalProps, type OverlayHistory, OverlayHistoryContext, PasswordInput, type PasswordInputProps, type Presence, ProgressBar, type ProgressBarProps, Radio, type RadioProps, type RovingGroupOptions, Screen, ScreenContent, SearchField, type SearchFieldProps, type SegmentOption, SegmentedControl, type SegmentedControlProps, Select, type SelectProps, type SelectSize, Sheet, SheetBody, SheetFooter, SheetHeader, type SheetProps, Skeleton, type SkeletonProps, type SkeletonVariant, Spinner, type SpinnerProps, Stack, type StackAlign, type StackGap, type StackProps, Switch, type SwitchProps, Tab, TabBar, TabBarItem, type TabBarItemProps, type TabBarProps, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Tabs, type TabsProps, Tag, type TagProps, type TagTone, Text, type TextProps, type TextTone, type TextVariant, Textarea, type TextareaProps, type ToastOptions, ToastProvider, type ToastProviderProps, type ToastTone, type UseOverlayOptions, cx, useFieldContext, useOverlay, usePresence, useRovingGroup, useToast };
+export { AppBar, type AppBarProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, Badge, type BadgeProps, type BadgeTone, Button, type ButtonProps, type ButtonSize, type ButtonVariant, type CSSVars, Card, CardBody, CardFooter, CardHeader, type CardProps, type CardSectionProps, type CardVariant, Checkbox, type CheckboxProps, Chip, ChipBar, type ChipBarGap, type ChipBarProps, ChipGroup, type ChipGroupGap, type ChipGroupProps, type ChipProps, type ChipVariant, ConfirmDialog, type ConfirmDialogProps, type ConfirmDialogTone, Container, type ContainerProps, type ContainerWidth, CountButton, type CountButtonProps, type CountButtonTone, DateTimePicker, type DateTimePickerLabels, type DateTimePickerProps, Divider, type DividerProps, EmptyState, type EmptyStateProps, Field, type FieldContextValue, type FieldProps, Heading, type HeadingLevel, type HeadingProps, type HeadingTone, Icon, type IconProps, IconProvider, type IconProviderProps, type IconRender, type IconRenderProps, type IconSize, Inline, type InlineAlign, type InlineGap, type InlineJustify, type InlineProps, Input, type InputProps, type InputSize, Link, type LinkProps, type LinkVariant, ListGroup, type ListGroupProps, ListItem, type ListItemProps, Modal, ModalBody, ModalFooter, ModalHeader, type ModalProps, type OverlayHistory, OverlayHistoryContext, PasswordInput, type PasswordInputProps, type Presence, ProgressBar, type ProgressBarProps, Radio, type RadioProps, type RovingGroupOptions, Screen, ScreenContent, type ScreenContentProps, SearchField, type SearchFieldProps, type SegmentOption, SegmentedControl, type SegmentedControlProps, Select, type SelectProps, type SelectSize, Sheet, SheetBody, SheetFooter, SheetHeader, type SheetProps, Skeleton, type SkeletonProps, type SkeletonVariant, Spinner, type SpinnerProps, Stack, type StackAlign, type StackGap, type StackProps, Switch, type SwitchProps, Tab, TabBar, TabBarAction, type TabBarActionProps, TabBarItem, type TabBarItemProps, type TabBarProps, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Tabs, type TabsProps, Tag, type TagProps, type TagTone, Text, type TextProps, type TextTone, type TextVariant, Textarea, type TextareaProps, type ToastOptions, ToastProvider, type ToastProviderProps, type ToastTone, type UseOverlayOptions, cx, useFieldContext, useOverlay, usePresence, useRovingGroup, useToast };