shelving 1.236.0 → 1.236.2

package/ui/block/Video.d.ts

@@ -2,11 +2,26 @@ import { type MouseEvent, type ReactElement } from "react";
 import { type SpaceVariants } from "../style/Space.js";
 import { type WidthVariants } from "../style/Width.js";
 import type { ChildProps, OptionalChildProps } from "../util/props.js";
+/**
+ * Props for `Video` — space and width variants plus optional `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Video/VideoProps
+ */
 export interface VideoProps extends SpaceVariants, WidthVariants, OptionalChildProps {
 }
+/**
+ * Props for `VideoButtons` — `children` plus an optional `left` alignment flag.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Video/VideoButtonsProps
+ */
 export interface VideoButtonsProps extends ChildProps {
     left?: boolean;
 }
+/**
+ * Props for `VideoButton` — `children` plus optional `title`, `onClick`, `danger`, and `disabled`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Video/VideoButtonProps
+ */
 export interface VideoButtonProps extends ChildProps {
     title?: string | undefined;
     onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
@@ -17,16 +32,48 @@ export interface VideoButtonProps extends ChildProps {
  * Video container element.
  * - Has a black background and a 16:9 aspect ratio.
  * - Shows its contents (i.e. a `<video>` element or a `<TwilioRoom>`.
+ *
+ * @param props Space and width variants plus `children` (e.g. a `<video>` element).
+ * @returns Rendered `<figure>` video container.
+ * @example <Video><video src="/clip.mp4" /></Video>
+ * @see https://dhoulb.github.io/shelving/ui/block/Video/Video
  */
 export declare function Video({ children, ...variants }: VideoProps): ReactElement;
-/** Set of video buttons floating over a video. */
+/**
+ * Set of video buttons floating over a video.
+ *
+ * @param props `children` (the buttons) plus an optional `left` alignment flag.
+ * @returns Rendered overlay container for video buttons.
+ * @example <VideoButtons><FullscreenVideoButton /></VideoButtons>
+ * @see https://dhoulb.github.io/shelving/ui/block/Video/VideoButtons
+ */
 export declare function VideoButtons({ children, ...variants }: VideoButtonsProps): import("react").JSX.Element;
-/** Individual video button over a video. */
+/**
+ * Individual video button over a video — renders a `<button>`.
+ *
+ * @param props `children` (the button content) plus optional `title`, `onClick`, `danger`, and `disabled`.
+ * @returns Rendered `<button>` element overlaid on the video.
+ * @example <VideoButton title="Play" onClick={play}><PlayIcon /></VideoButton>
+ * @see https://dhoulb.github.io/shelving/ui/block/Video/VideoButton
+ */
 export declare function VideoButton({ children, title, onClick, disabled, ...variants }: VideoButtonProps): ReactElement;
 declare const _fullscreenVideoButtonProps: unique symbol;
+/**
+ * Props for `FullscreenVideoButton` — an empty marker interface (the component takes no props).
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Video/FullscreenVideoButtonProps
+ */
 export interface FullscreenVideoButtonProps {
     readonly [_fullscreenVideoButtonProps]?: never;
 }
-/** Button to make a video element go fullscreen. */
+/**
+ * Button to toggle the surrounding video element in and out of fullscreen.
+ * - Renders `null` when the browser does not support the Fullscreen API.
+ * - Tracks fullscreen state so the icon and title flip between enter/exit.
+ *
+ * @returns Rendered fullscreen toggle button, or `null` when fullscreen is unavailable.
+ * @example <Video><video src="/clip.mp4" /><VideoButtons><FullscreenVideoButton /></VideoButtons></Video>
+ * @see https://dhoulb.github.io/shelving/ui/block/Video/FullscreenVideoButton
+ */
 export declare function FullscreenVideoButton(): ReactElement | null;
 export {};

package/ui/block/Video.js

@@ -9,20 +9,47 @@ import styles from "./Video.module.css";
  * Video container element.
  * - Has a black background and a 16:9 aspect ratio.
  * - Shows its contents (i.e. a `<video>` element or a `<TwilioRoom>`.
+ *
+ * @param props Space and width variants plus `children` (e.g. a `<video>` element).
+ * @returns Rendered `<figure>` video container.
+ * @example <Video><video src="/clip.mp4" /></Video>
+ * @see https://dhoulb.github.io/shelving/ui/block/Video/Video
  */
 export function Video({ children, ...variants }) {
     const ref = useRef(null);
     return (_jsx("figure", { ref: ref, className: getClass(getModuleClass(styles, "video"), getSpaceClass(variants), getWidthClass(variants)), children: children }));
 }
-/** Set of video buttons floating over a video. */
+/**
+ * Set of video buttons floating over a video.
+ *
+ * @param props `children` (the buttons) plus an optional `left` alignment flag.
+ * @returns Rendered overlay container for video buttons.
+ * @example <VideoButtons><FullscreenVideoButton /></VideoButtons>
+ * @see https://dhoulb.github.io/shelving/ui/block/Video/VideoButtons
+ */
 export function VideoButtons({ children, ...variants }) {
     return _jsx("div", { className: getModuleClass(styles, "buttons", variants), children: children });
 }
-/** Individual video button over a video. */
+/**
+ * Individual video button over a video — renders a `<button>`.
+ *
+ * @param props `children` (the button content) plus optional `title`, `onClick`, `danger`, and `disabled`.
+ * @returns Rendered `<button>` element overlaid on the video.
+ * @example <VideoButton title="Play" onClick={play}><PlayIcon /></VideoButton>
+ * @see https://dhoulb.github.io/shelving/ui/block/Video/VideoButton
+ */
 export function VideoButton({ children, title, onClick, disabled, ...variants }) {
     return (_jsx("button", { type: "button", onClick: onClick, className: getModuleClass(styles, "button", variants), title: title, disabled: disabled, children: children }));
 }
-/** Button to make a video element go fullscreen. */
+/**
+ * Button to toggle the surrounding video element in and out of fullscreen.
+ * - Renders `null` when the browser does not support the Fullscreen API.
+ * - Tracks fullscreen state so the icon and title flip between enter/exit.
+ *
+ * @returns Rendered fullscreen toggle button, or `null` when fullscreen is unavailable.
+ * @example <Video><video src="/clip.mp4" /><VideoButtons><FullscreenVideoButton /></VideoButtons></Video>
+ * @see https://dhoulb.github.io/shelving/ui/block/Video/FullscreenVideoButton
+ */
 export function FullscreenVideoButton() {
     const [isFull, setFull] = useState(() => typeof document !== "undefined" && !!document.fullscreenElement);
     useEffect(() => {

package/ui/block/Video.tsx

@@ -6,12 +6,27 @@ import { getClass, getModuleClass } from "../util/css.js";
 import type { ChildProps, OptionalChildProps } from "../util/props.js";
 import styles from "./Video.module.css";
 
+/**
+ * Props for `Video` — space and width variants plus optional `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Video/VideoProps
+ */
 export interface VideoProps extends SpaceVariants, WidthVariants, OptionalChildProps {}
 
+/**
+ * Props for `VideoButtons` — `children` plus an optional `left` alignment flag.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Video/VideoButtonsProps
+ */
 export interface VideoButtonsProps extends ChildProps {
 	left?: boolean;
 }
 
+/**
+ * Props for `VideoButton` — `children` plus optional `title`, `onClick`, `danger`, and `disabled`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Video/VideoButtonProps
+ */
 export interface VideoButtonProps extends ChildProps {
 	title?: string | undefined;
 	onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
@@ -23,6 +38,11 @@ export interface VideoButtonProps extends ChildProps {
  * Video container element.
  * - Has a black background and a 16:9 aspect ratio.
  * - Shows its contents (i.e. a `<video>` element or a `<TwilioRoom>`.
+ *
+ * @param props Space and width variants plus `children` (e.g. a `<video>` element).
+ * @returns Rendered `<figure>` video container.
+ * @example <Video><video src="/clip.mp4" /></Video>
+ * @see https://dhoulb.github.io/shelving/ui/block/Video/Video
  */
 export function Video({ children, ...variants }: VideoProps): ReactElement {
 	const ref = useRef<HTMLElement | null>(null);
@@ -34,12 +54,26 @@ export function Video({ children, ...variants }: VideoProps): ReactElement {
 	);
 }
 
-/** Set of video buttons floating over a video. */
+/**
+ * Set of video buttons floating over a video.
+ *
+ * @param props `children` (the buttons) plus an optional `left` alignment flag.
+ * @returns Rendered overlay container for video buttons.
+ * @example <VideoButtons><FullscreenVideoButton /></VideoButtons>
+ * @see https://dhoulb.github.io/shelving/ui/block/Video/VideoButtons
+ */
 export function VideoButtons({ children, ...variants }: VideoButtonsProps) {
 	return <div className={getModuleClass(styles, "buttons", variants)}>{children}</div>;
 }
 
-/** Individual video button over a video. */
+/**
+ * Individual video button over a video — renders a `<button>`.
+ *
+ * @param props `children` (the button content) plus optional `title`, `onClick`, `danger`, and `disabled`.
+ * @returns Rendered `<button>` element overlaid on the video.
+ * @example <VideoButton title="Play" onClick={play}><PlayIcon /></VideoButton>
+ * @see https://dhoulb.github.io/shelving/ui/block/Video/VideoButton
+ */
 export function VideoButton({ children, title, onClick, disabled, ...variants }: VideoButtonProps): ReactElement {
 	return (
 		<button type="button" onClick={onClick} className={getModuleClass(styles, "button", variants)} title={title} disabled={disabled}>
@@ -50,11 +84,24 @@ export function VideoButton({ children, title, onClick, disabled, ...variants }:
 
 declare const _fullscreenVideoButtonProps: unique symbol;
 
+/**
+ * Props for `FullscreenVideoButton` — an empty marker interface (the component takes no props).
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Video/FullscreenVideoButtonProps
+ */
 export interface FullscreenVideoButtonProps {
 	readonly [_fullscreenVideoButtonProps]?: never;
 }
 
-/** Button to make a video element go fullscreen. */
+/**
+ * Button to toggle the surrounding video element in and out of fullscreen.
+ * - Renders `null` when the browser does not support the Fullscreen API.
+ * - Tracks fullscreen state so the icon and title flip between enter/exit.
+ *
+ * @returns Rendered fullscreen toggle button, or `null` when fullscreen is unavailable.
+ * @example <Video><video src="/clip.mp4" /><VideoButtons><FullscreenVideoButton /></VideoButtons></Video>
+ * @see https://dhoulb.github.io/shelving/ui/block/Video/FullscreenVideoButton
+ */
 export function FullscreenVideoButton(): ReactElement | null {
 	const [isFull, setFull] = useState(() => typeof document !== "undefined" && !!document.fullscreenElement);
 

package/ui/dialog/Dialog.d.ts

@@ -2,11 +2,38 @@ import { type ReactElement } from "react";
 import type { Callback } from "../../util/function.js";
 import type { ButtonVariants } from "../form/Button.js";
 import type { OptionalChildProps } from "../util/props.js";
+/**
+ * Props for `<Dialog>` — optional `children` content and an `onClose` callback.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialog/DialogProps
+ */
 export interface DialogProps extends OptionalChildProps {
     onClose?: Callback;
 }
+/**
+ * Modal `<dialog>` element that opens on mount and includes a close button.
+ *
+ * - Opens via `showModal()` when mounted and closes on backdrop clicks, link/nav-button clicks, or the close button.
+ * - Wraps content in `<Suspense>` so lazy children can stream in.
+ *
+ * @example dialogs.show(<Dialog><p>Are you sure?</p></Dialog>);
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialog/Dialog
+ */
 export declare const Dialog: import("react").MemoExoticComponent<({ children, onClose, ...props }: DialogProps) => import("react").JSX.Element>;
+/**
+ * Props for `<DialogCloseButton>` — button styling variants and optional `children` to override the X icon.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialog/DialogCloseButtonProps
+ */
 export interface DialogCloseButtonProps extends ButtonVariants, OptionalChildProps {
 }
-/** Button that closes its wrapping dialog with an X icon. */
+/**
+ * Button that closes its wrapping `<dialog>`, showing an X icon by default.
+ *
+ * @param children Optional button content (defaults to an X icon).
+ * @param variants Button styling variants.
+ * @returns The close button element.
+ * @example <DialogCloseButton plain />
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialog/DialogCloseButton
+ */
 export declare function DialogCloseButton({ children, ...variants }: DialogCloseButtonProps): ReactElement;

package/ui/dialog/Dialog.js

@@ -3,6 +3,15 @@ import { XMarkIcon } from "@heroicons/react/24/solid";
 import { memo, Suspense, useEffect, useRef } from "react";
 import { getModuleClass } from "../util/css.js";
 import styles from "./Dialog.module.css";
+/**
+ * Modal `<dialog>` element that opens on mount and includes a close button.
+ *
+ * - Opens via `showModal()` when mounted and closes on backdrop clicks, link/nav-button clicks, or the close button.
+ * - Wraps content in `<Suspense>` so lazy children can stream in.
+ *
+ * @example dialogs.show(<Dialog><p>Are you sure?</p></Dialog>);
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialog/Dialog
+ */
 export const Dialog = memo(({ children, onClose, ...props }) => {
     const ref = useRef(null);
     useEffect(() => {
@@ -19,7 +28,15 @@ function _closeOnBackdropClick({ currentTarget, target }) {
     if (target instanceof Element && target.closest("a:any-link, nav button:enabled"))
         currentTarget.close();
 }
-/** Button that closes its wrapping dialog with an X icon. */
+/**
+ * Button that closes its wrapping `<dialog>`, showing an X icon by default.
+ *
+ * @param children Optional button content (defaults to an X icon).
+ * @param variants Button styling variants.
+ * @returns The close button element.
+ * @example <DialogCloseButton plain />
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialog/DialogCloseButton
+ */
 export function DialogCloseButton({ children = _jsx(XMarkIcon, {}), ...variants }) {
     return (_jsx("button", { type: "button", title: "Close", className: getModuleClass(styles, "button", variants), onClick: _closeOnButtonClick, children: children }));
 }

package/ui/dialog/Dialog.tsx

@@ -6,10 +6,24 @@ import { getModuleClass } from "../util/css.js";
 import type { OptionalChildProps } from "../util/props.js";
 import styles from "./Dialog.module.css";
 
+/**
+ * Props for `<Dialog>` — optional `children` content and an `onClose` callback.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialog/DialogProps
+ */
 export interface DialogProps extends OptionalChildProps {
 	onClose?: Callback;
 }
 
+/**
+ * Modal `<dialog>` element that opens on mount and includes a close button.
+ *
+ * - Opens via `showModal()` when mounted and closes on backdrop clicks, link/nav-button clicks, or the close button.
+ * - Wraps content in `<Suspense>` so lazy children can stream in.
+ *
+ * @example dialogs.show(<Dialog><p>Are you sure?</p></Dialog>);
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialog/Dialog
+ */
 export const Dialog = memo(({ children, onClose, ...props }: DialogProps) => {
 	const ref = useRef<HTMLDialogElement>(null);
 
@@ -39,9 +53,22 @@ function _closeOnBackdropClick({ currentTarget, target }: MouseEvent<HTMLDialogE
 	if (target instanceof Element && target.closest("a:any-link, nav button:enabled")) currentTarget.close();
 }
 
+/**
+ * Props for `<DialogCloseButton>` — button styling variants and optional `children` to override the X icon.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialog/DialogCloseButtonProps
+ */
 export interface DialogCloseButtonProps extends ButtonVariants, OptionalChildProps {}
 
-/** Button that closes its wrapping dialog with an X icon. */
+/**
+ * Button that closes its wrapping `<dialog>`, showing an X icon by default.
+ *
+ * @param children Optional button content (defaults to an X icon).
+ * @param variants Button styling variants.
+ * @returns The close button element.
+ * @example <DialogCloseButton plain />
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialog/DialogCloseButton
+ */
 export function DialogCloseButton({ children = <XMarkIcon />, ...variants }: DialogCloseButtonProps): ReactElement {
 	return (
 		<button type="button" title="Close" className={getModuleClass(styles, "button", variants)} onClick={_closeOnButtonClick}>

package/ui/dialog/Dialogs.d.ts

@@ -1,23 +1,70 @@
 import { type ReactElement, type ReactNode } from "react";
 import { ArrayStore } from "../../store/ArrayStore.js";
 import type { ChildProps } from "../util/props.js";
-/** Store a list of dialogs. */
+/**
+ * Store holding the live list of open `<Dialog>` elements.
+ *
+ * - `show()` opens a new dialog; closed dialogs are removed after an animation delay.
+ *
+ * @example const dialogs = new DialogsStore(); dialogs.show(<p>Hello</p>);
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/DialogsStore
+ */
 export declare class DialogsStore extends ArrayStore<ReactElement> {
-    /** Show a new dialog. */
+    /**
+     * Open a new dialog wrapping the given content.
+     *
+     * @param children The content to show inside the dialog.
+     * @example dialogs.show(<ConfirmForm />);
+     * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/DialogsStore/show
+     */
     show(children: ReactNode): void;
-    /** Hide all currently visible dialogs. */
+    /**
+     * Hide all currently visible dialogs.
+     *
+     * @example dialogs.hideAll();
+     * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/DialogsStore/hideAll
+     */
     hideAll(): void;
 }
-/** Return the current dialogs context. */
+/**
+ * Read the current `DialogsStore` from the nearest `<DialogsContext>`.
+ *
+ * @returns The current `DialogsStore`.
+ * @example requireDialogs().show(<ConfirmForm />);
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/requireDialogs
+ */
 export declare function requireDialogs(): DialogsStore;
 declare const _componentProps: unique symbol;
+/**
+ * Props for `<DialogsContext>` — the `children` subtree the dialogs store is provided to.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/DialogsContextProps
+ */
 export interface DialogsContextProps extends ChildProps {
 }
+/**
+ * Props for `<Dialogs>` — takes no props (branded empty interface).
+ *
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/DialogsProps
+ */
 export interface DialogsProps {
     readonly [_componentProps]?: never;
 }
-/** Create a new `<DialogsStore>` for a set of elements. */
+/**
+ * Provider that creates a fresh `DialogsStore` and shares it with its subtree.
+ *
+ * @param children The subtree that can open dialogs via `requireDialogs()`.
+ * @returns The dialogs context provider wrapping `children`.
+ * @example <DialogsContext><App /></DialogsContext>
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/DialogsContext
+ */
 export declare function DialogsContext({ children }: DialogsContextProps): ReactElement;
-/** Output the list of dialogs from a `DialogsStore` in the current `DialogsContext`. */
+/**
+ * Render the open dialogs from the current `DialogsContext`.
+ *
+ * @returns The list of open dialog elements, or `null` when there are none.
+ * @example <DialogsContext><App /><Dialogs /></DialogsContext>
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/Dialogs
+ */
 export declare function Dialogs(): ReactNode | null;
 export {};

package/ui/dialog/Dialogs.js

@@ -7,9 +7,22 @@ import { getRandomKey } from "../../util/random.js";
 import { Dialog } from "./Dialog.js";
 /** How long before a hidden dialogs are removed from the DOM (allow time for animates to complete). */
 const REMOVE_DELAY = 500;
-/** Store a list of dialogs. */
+/**
+ * Store holding the live list of open `<Dialog>` elements.
+ *
+ * - `show()` opens a new dialog; closed dialogs are removed after an animation delay.
+ *
+ * @example const dialogs = new DialogsStore(); dialogs.show(<p>Hello</p>);
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/DialogsStore
+ */
 export class DialogsStore extends ArrayStore {
-    /** Show a new dialog. */
+    /**
+     * Open a new dialog wrapping the given content.
+     *
+     * @param children The content to show inside the dialog.
+     * @example dialogs.show(<ConfirmForm />);
+     * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/DialogsStore/show
+     */
     show(children) {
         const dialog = (_jsx(Dialog
         // Add a `key=""` so dialogs can be rendered directly and added/removed in any order.
@@ -20,7 +33,12 @@ export class DialogsStore extends ArrayStore {
             }, children: children }, getRandomKey()));
         this.add(dialog);
     }
-    /** Hide all currently visible dialogs. */
+    /**
+     * Hide all currently visible dialogs.
+     *
+     * @example dialogs.hideAll();
+     * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/DialogsStore/hideAll
+     */
     hideAll() {
         this.delete(...this.value);
     }
@@ -28,15 +46,34 @@ export class DialogsStore extends ArrayStore {
 /** Context to get the current `DialogsStore` created by a `<DialogsWrapper>`. */
 const _DialogsContext = createContext(new DialogsStore());
 _DialogsContext.displayName = "DialogsContext";
-/** Return the current dialogs context. */
+/**
+ * Read the current `DialogsStore` from the nearest `<DialogsContext>`.
+ *
+ * @returns The current `DialogsStore`.
+ * @example requireDialogs().show(<ConfirmForm />);
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/requireDialogs
+ */
 export function requireDialogs() {
     return use(_DialogsContext);
 }
-/** Create a new `<DialogsStore>` for a set of elements. */
+/**
+ * Provider that creates a fresh `DialogsStore` and shares it with its subtree.
+ *
+ * @param children The subtree that can open dialogs via `requireDialogs()`.
+ * @returns The dialogs context provider wrapping `children`.
+ * @example <DialogsContext><App /></DialogsContext>
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/DialogsContext
+ */
 export function DialogsContext({ children }) {
     return _jsx(_DialogsContext, { value: useInstance(DialogsStore), children: children });
 }
-/** Output the list of dialogs from a `DialogsStore` in the current `DialogsContext`. */
+/**
+ * Render the open dialogs from the current `DialogsContext`.
+ *
+ * @returns The list of open dialog elements, or `null` when there are none.
+ * @example <DialogsContext><App /><Dialogs /></DialogsContext>
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/Dialogs
+ */
 export function Dialogs() {
     const dialogs = useStore(requireDialogs());
     return dialogs ? dialogs.value : null;

package/ui/dialog/Dialogs.tsx

@@ -9,9 +9,22 @@ import { Dialog } from "./Dialog.js";
 /** How long before a hidden dialogs are removed from the DOM (allow time for animates to complete). */
 const REMOVE_DELAY = 500;
 
-/** Store a list of dialogs. */
+/**
+ * Store holding the live list of open `<Dialog>` elements.
+ *
+ * - `show()` opens a new dialog; closed dialogs are removed after an animation delay.
+ *
+ * @example const dialogs = new DialogsStore(); dialogs.show(<p>Hello</p>);
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/DialogsStore
+ */
 export class DialogsStore extends ArrayStore<ReactElement> {
-	/** Show a new dialog. */
+	/**
+	 * Open a new dialog wrapping the given content.
+	 *
+	 * @param children The content to show inside the dialog.
+	 * @example dialogs.show(<ConfirmForm />);
+	 * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/DialogsStore/show
+	 */
 	show(children: ReactNode) {
 		const dialog = (
 			<Dialog
@@ -28,7 +41,12 @@ export class DialogsStore extends ArrayStore<ReactElement> {
 		this.add(dialog);
 	}
 
-	/** Hide all currently visible dialogs. */
+	/**
+	 * Hide all currently visible dialogs.
+	 *
+	 * @example dialogs.hideAll();
+	 * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/DialogsStore/hideAll
+	 */
 	hideAll() {
 		this.delete(...this.value);
 	}
@@ -38,25 +56,54 @@ export class DialogsStore extends ArrayStore<ReactElement> {
 const _DialogsContext = createContext<DialogsStore>(new DialogsStore());
 _DialogsContext.displayName = "DialogsContext";
 
-/** Return the current dialogs context. */
+/**
+ * Read the current `DialogsStore` from the nearest `<DialogsContext>`.
+ *
+ * @returns The current `DialogsStore`.
+ * @example requireDialogs().show(<ConfirmForm />);
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/requireDialogs
+ */
 export function requireDialogs(): DialogsStore {
 	return use(_DialogsContext);
 }
 
 declare const _componentProps: unique symbol;
 
+/**
+ * Props for `<DialogsContext>` — the `children` subtree the dialogs store is provided to.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/DialogsContextProps
+ */
 export interface DialogsContextProps extends ChildProps {}
 
+/**
+ * Props for `<Dialogs>` — takes no props (branded empty interface).
+ *
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/DialogsProps
+ */
 export interface DialogsProps {
 	readonly [_componentProps]?: never;
 }
 
-/** Create a new `<DialogsStore>` for a set of elements. */
+/**
+ * Provider that creates a fresh `DialogsStore` and shares it with its subtree.
+ *
+ * @param children The subtree that can open dialogs via `requireDialogs()`.
+ * @returns The dialogs context provider wrapping `children`.
+ * @example <DialogsContext><App /></DialogsContext>
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/DialogsContext
+ */
 export function DialogsContext({ children }: DialogsContextProps): ReactElement {
 	return <_DialogsContext value={useInstance(DialogsStore)}>{children}</_DialogsContext>;
 }
 
-/** Output the list of dialogs from a `DialogsStore` in the current `DialogsContext`. */
+/**
+ * Render the open dialogs from the current `DialogsContext`.
+ *
+ * @returns The list of open dialog elements, or `null` when there are none.
+ * @example <DialogsContext><App /><Dialogs /></DialogsContext>
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Dialogs/Dialogs
+ */
 export function Dialogs(): ReactNode | null {
 	const dialogs = useStore(requireDialogs());
 	return dialogs ? dialogs.value : null;

package/ui/dialog/Modal.d.ts

@@ -1,5 +1,18 @@
 import type { ReactElement } from "react";
 import type { OptionalChildProps } from "../util/props.js";
+/**
+ * Props for `<Modal>` — optional `children` content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Modal/ModalProps
+ */
 export interface ModalProps extends OptionalChildProps {
 }
+/**
+ * Styled `<aside>` overlay container for modal content.
+ *
+ * @param children The modal content.
+ * @returns The modal container element.
+ * @example <Modal><p>Modal content</p></Modal>
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Modal/Modal
+ */
 export declare function Modal({ children }: ModalProps): ReactElement;

package/ui/dialog/Modal.js

@@ -1,5 +1,13 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import styles from "./Modal.module.css";
+/**
+ * Styled `<aside>` overlay container for modal content.
+ *
+ * @param children The modal content.
+ * @returns The modal container element.
+ * @example <Modal><p>Modal content</p></Modal>
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Modal/Modal
+ */
 export function Modal({ children }) {
     return _jsx("aside", { className: styles.modal, children: children });
 }

package/ui/dialog/Modal.tsx

@@ -2,8 +2,21 @@ import type { ReactElement } from "react";
 import type { OptionalChildProps } from "../util/props.js";
 import styles from "./Modal.module.css";
 
+/**
+ * Props for `<Modal>` — optional `children` content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Modal/ModalProps
+ */
 export interface ModalProps extends OptionalChildProps {}
 
+/**
+ * Styled `<aside>` overlay container for modal content.
+ *
+ * @param children The modal content.
+ * @returns The modal container element.
+ * @example <Modal><p>Modal content</p></Modal>
+ * @see https://dhoulb.github.io/shelving/ui/dialog/Modal/Modal
+ */
 export function Modal({ children }: ModalProps): ReactElement {
 	return <aside className={styles.modal}>{children}</aside>;
 }