@minimalstuff/ui 3.0.1 → 3.2.0

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import { Callable } from 'react-call';
 import { ComponentPropsWithRef } from 'react';
+import type { HTMLAttributeAnchorTarget } from 'react';
 import { JSX } from 'react';
 import { JSXElementConstructor } from 'react';
-import { MouseEvent as MouseEvent_2 } from 'react';
+import type { MouseEvent as MouseEvent_2 } from 'react';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
 import { ReactPortal } from 'react';
@@ -10,6 +11,34 @@ import { Ref } from 'react';
 import { StoreApi } from 'zustand';
 import { UseBoundStore } from 'zustand';
 
+/**
+ * The picture of a person, or the initial of `name` when there is none.
+ * Labelled with the full `name` so screen readers announce the person rather
+ * than a stray letter; the `<img>` itself stays out of the accessibility
+ * tree to avoid announcing it twice.
+ *
+ * A `src` that fails to load falls back to the initial — remote avatars go
+ * missing (deleted accounts, rate limits), and a broken-image glyph in a
+ * circle looks like a bug. Pointing `src` at a different URL retries.
+ *
+ * A missing name is the caller's call to make: this renders whatever `name`
+ * starts with, and an empty circle for a blank string, rather than inventing
+ * a placeholder identity.
+ */
+export declare function Avatar({ name, src, size, color, radius, unstyled, className, }: Readonly<AvatarProps>): JSX.Element;
+
+export declare interface AvatarProps {
+    name: string;
+    src?: string;
+    size?: AvatarSize;
+    color?: ButtonColor;
+    radius?: Radius;
+    unstyled?: boolean;
+    className?: string;
+}
+
+export declare type AvatarSize = ControlSize;
+
 export declare const Badge: ({ children, color, variant, size, radius, className, ...props }: Readonly<BadgeProps>) => JSX.Element;
 
 export declare interface BadgeProps extends ComponentPropsWithRef<'span'> {
@@ -35,6 +64,7 @@ declare type ButtonColor =
 	| 'danger'
 	| 'success'
 	| 'warning';
+export { ButtonColor as AvatarColor }
 export { ButtonColor as BadgeColor }
 export { ButtonColor }
 
@@ -59,6 +89,39 @@ declare type ButtonStyle = {
 
 export declare type ButtonVariant = 'solid' | 'outline' | 'ghost' | 'subtle';
 
+/**
+ * A section container: surface, border, radius, padding. Pass `title` (plus
+ * optionally `description` and `actions`, which sit opposite the title) to
+ * get the standard header, or omit all three and lay the section out inside
+ * `children` yourself.
+ *
+ * A titled card is also a labelled `region`, so screen reader users can jump
+ * between sections by name — worth it on a settings page stacking seven of
+ * them. Untitled cards stay plain `div`s rather than adding nameless
+ * landmarks. Set `headingLevel` when the card sits under an existing heading:
+ * the default `h2` is right at the top level of a page and wrong nested.
+ *
+ * `unstyled` strips the surface, border, radius and padding; the header
+ * markup stays, since that is structure rather than skin.
+ */
+export declare function Card({ children, title, description, actions, headingLevel, padding, radius, unstyled, className, }: Readonly<CardProps>): JSX.Element;
+
+export declare type CardHeadingLevel = 2 | 3 | 4;
+
+export declare type CardPadding = 'none' | 'sm' | 'md' | 'lg';
+
+export declare interface CardProps {
+    children: ReactNode;
+    title?: ReactNode;
+    description?: ReactNode;
+    actions?: ReactNode;
+    headingLevel?: CardHeadingLevel;
+    padding?: CardPadding;
+    radius?: Radius;
+    unstyled?: boolean;
+    className?: string;
+}
+
 export declare function CharacterCount({ current, min, max, showMin, showMax, unstyled, className, }: Readonly<CharacterCountProps>): JSX.Element;
 
 export declare interface CharacterCountProps {
@@ -83,7 +146,7 @@ export declare interface CheckboxProps extends Omit<ComponentPropsWithRef<'input
     wrapperClassName?: string;
 }
 
-export declare function ClientOnly({ children, fallback }: Readonly<ClientOnlyProps>): string | number | bigint | boolean | Iterable< ReactNode> | Promise<string | number | bigint | boolean | ReactPortal | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable< ReactNode> | null | undefined> | JSX.Element | null;
+export declare function ClientOnly({ children, fallback }: Readonly<ClientOnlyProps>): string | number | bigint | boolean | JSX.Element | Iterable< ReactNode> | Promise<string | number | bigint | boolean | ReactPortal | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable< ReactNode> | null | undefined> | null;
 
 export declare interface ClientOnlyProps extends React.PropsWithChildren {
     fallback?: React.ReactNode;
@@ -134,10 +197,10 @@ export declare interface ConfirmModalProps {
 export declare type ConfirmModalResponse = boolean;
 
 /**
- * Wraps `children` (the right-click target area) and opens `items`, a list
- * of `MenuItem` elements as direct children (see `MenuItem`'s own doc
- * comment), at the cursor position. Right-click again elsewhere on the
- * wrapped area to reposition it.
+ * Wraps `children` (the right-click target area) and opens `items` — made
+ * of `MenuItem`s, optionally wrapped in `MenuGroup`s and split by
+ * `MenuSeparator`s — at the cursor position. Right-click again elsewhere on
+ * the wrapped area to reposition it.
  *
  * For a menu anchored to a specific button (e.g. a kebab icon) instead of a
  * right-click, use `Menu`.
@@ -232,39 +295,112 @@ export declare type KbdSize = ControlSize;
 
 /**
  * A dropdown anchored to `trigger` (e.g. a kebab `IconButton`): click to
- * open, click again/click outside/Escape to close. `children` must be
- * `MenuItem` elements as direct children (see `MenuItem`'s own doc comment)
- * for keyboard nav and close-on-select to work.
+ * open, click again/click outside/Escape to close. `children` is made of
+ * `MenuItem`s, optionally wrapped in `MenuGroup`s and split by
+ * `MenuSeparator`s.
  *
  * For "right-click anywhere on this area" instead of a specific trigger
  * button, use `ContextMenu`.
+ *
+ * Opening a `Modal` from a `MenuItem`'s `onClick` is safe: the menu returns
+ * focus to `trigger` synchronously during the click, then the modal mounts a
+ * render later and takes focus from there. That ordering is what makes the
+ * modal record `trigger` as its restore target, so focus lands back on the
+ * trigger when the modal closes. The menu panel outlives the click by one
+ * exit animation, but the modal sits above it and owns Escape (a document
+ * listener), so the fading panel is inert. See `menu_with_modal.test.tsx`.
  */
 export declare function Menu({ trigger, children, side, align, radius, className, ref, }: Readonly<MenuProps>): JSX.Element;
 
 export declare type MenuAlign = 'start' | 'center' | 'end';
 
 /**
- * A row inside a `Menu` or `ContextMenu`. Must be a direct child of one of
- * those (or of a `<>` fragment passed as their `children`/`items`): arrow
- * key navigation and close-on-select both rely on `role="menuitem"` being a
- * direct descendant. Wrapping items in another element (e.g. a `<div>` for
- * a labeled section) will render fine but breaks both.
+ * A named group of `MenuItem`s inside a `Menu` or `ContextMenu`. Where
+ * `MenuSeparator` cuts, this one names — and unlike a bare title sitting
+ * next to the items, `role="group"` plus `aria-labelledby` actually tells
+ * assistive tech which items the name covers.
  *
- * Works standalone outside a `Menu`/`ContextMenu` too (e.g. in isolation in
- * Storybook): `onClick` still fires, it just won't auto-close anything.
+ * Wrapping items is safe: the enclosing menu collects `[role="menuitem"]`
+ * across all its descendants, so keyboard navigation still walks into the
+ * group, and close-on-select travels through React context rather than the
+ * DOM tree.
+ *
+ * `className` styles the label — the only part of the group that carries any
+ * skin. `wrapperClassName` styles the `role="group"` element around both the
+ * label and the items.
  */
-export declare function MenuItem({ icon, onClick, danger, disabled, children, className, ref, }: Readonly<MenuItemProps>): JSX.Element;
+export declare function MenuGroup({ label, children, unstyled, className, wrapperClassName, }: Readonly<MenuGroupProps>): JSX.Element;
 
-export declare interface MenuItemProps {
-    icon?: string;
-    onClick: (event: MouseEvent_2<HTMLButtonElement>) => void;
-    danger?: boolean;
-    disabled?: boolean;
+export declare interface MenuGroupProps {
+    label: ReactNode;
     children: ReactNode;
+    unstyled?: boolean;
     className?: string;
-    ref?: Ref<HTMLButtonElement>;
+    wrapperClassName?: string;
 }
 
+/**
+ * A row inside a `Menu` or `ContextMenu`, at any depth: the menu collects
+ * `[role="menuitem"]`/`[role="menuitemradio"]` across all its descendants
+ * for keyboard navigation, and close-on-select travels through React
+ * context rather than the DOM tree. `MenuGroup` relies on that to wrap the
+ * items it names.
+ *
+ * Renders either a `<button>` (pass `onClick`) or a native `<a>` (pass
+ * `href`, plus optional `target`/`rel`); the two are mutually exclusive.
+ * A disabled link drops its `href` and is marked `aria-disabled`, which
+ * keeps it out of the menu's keyboard navigation just like a disabled
+ * button.
+ *
+ * Works standalone outside a `Menu`/`ContextMenu` too (e.g. in isolation in
+ * Storybook): `onClick` still fires, it just won't auto-close anything.
+ */
+export declare function MenuItem(menuItemProps: Readonly<MenuItemProps>): JSX.Element;
+
+declare type MenuItemBaseProps = {
+    	icon?: string;
+    	/**
+     	 * Content pinned to the end of the row, dimmed by default — a `Kbd`, the
+     	 * current value of a setting. Keep it inert: the whole row is already the
+     	 * control, so anything focusable or separately clickable in here breaks
+     	 * both the menu's keyboard navigation and its `menuitem` semantics.
+     	 *
+     	 * It sits inside the row, so it is part of what the row announces:
+     	 * "Theme, Dark" for a value, "Shortcuts, Command K" for a shortcut. That
+     	 * is usually what you want; pass already-hidden content if it is not.
+     	 */
+    	trailing?: ReactNode;
+    	danger?: boolean;
+    	disabled?: boolean;
+    	children: ReactNode;
+    	className?: string;
+};
+
+export declare type MenuItemButtonProps = MenuItemBaseProps & {
+    	onClick: (event: MouseEvent_2<HTMLButtonElement>) => void;
+    	/**
+     	 * Turns the item into one option of a choice: it reports as
+     	 * `menuitemradio`, carries `aria-checked`, and shows a check mark when
+     	 * true. Leave it out for plain actions — an unset `selected` is not the
+     	 * same as `false`, which reads as "an option, currently not the one".
+     	 */
+    	selected?: boolean;
+    	href?: never;
+    	target?: never;
+    	rel?: never;
+    	ref?: Ref<HTMLButtonElement>;
+};
+
+export declare type MenuItemLinkProps = MenuItemBaseProps & {
+    	href: string;
+    	target?: HTMLAttributeAnchorTarget;
+    	rel?: string;
+    	onClick?: never;
+    	ref?: Ref<HTMLAnchorElement>;
+};
+
+export declare type MenuItemProps = MenuItemButtonProps | MenuItemLinkProps;
+
 export declare interface MenuProps {
     trigger: ReactElement;
     children: ReactNode;
@@ -276,6 +412,18 @@ export declare interface MenuProps {
     ref?: Ref<HTMLSpanElement>;
 }
 
+/**
+ * A divider between groups of `MenuItem`s inside a `Menu` or `ContextMenu`.
+ * Carries `role="separator"` (never `menuitem`), so the surrounding menu's
+ * arrow key navigation skips it: only focusable items take part.
+ */
+export declare const MenuSeparator: ({ unstyled, className, }: Readonly<MenuSeparatorProps>) => JSX.Element;
+
+export declare interface MenuSeparatorProps {
+    unstyled?: boolean;
+    className?: string;
+}
+
 export declare type MenuSide = 'top' | 'bottom' | 'left' | 'right';
 
 export declare const Modal: Callable<ModalProps, void, {}>;