@parallelworks/ui 0.50.0 → 0.52.0

package/dist/components/Input.js

@@ -1,39 +1,52 @@
 import { cx } from "../cx.js";
-import { Field, RevealToggle } from "./Field.js";
 import { fieldBox } from "./fieldBox.js";
+import { Field, RevealToggle } from "./Field.js";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { forwardRef, useState } from "react";
+import { useState } from "react";
+import { Input } from "@base-ui/react/input";
 //#region src/components/Input.tsx
 /** The Field around a control when it has a label; the control alone when it doesn't. */
-function framed({ label, hint, description, error }, { id, required, disabled }, control) {
+function framed({ label, hint, help, description, error, size }, { id, required, disabled }, control) {
 	if (label === void 0) return control(error ? { "aria-invalid": true } : {});
 	return /* @__PURE__ */ jsx(Field, {
 		label,
 		hint,
+		help,
 		description,
 		error,
 		required,
 		disabled,
+		size,
 		id,
 		children: control
 	});
 }
-/** A single-line text field. `type="password"` adds a button that shows what was typed. */
-var Input = forwardRef(({ label, hint, description, error, className, mono, size, type, ...props }, ref) => {
+/** The control props joined with the element's own: its own `aria-describedby` stays beside the
+*  field's, and its own invalid mark holds when the field sets none. */
+function joined(control, own) {
+	return {
+		...control,
+		"aria-invalid": control["aria-invalid"] ?? own["aria-invalid"],
+		"aria-describedby": [own["aria-describedby"], control["aria-describedby"]].filter(Boolean).join(" ") || void 0
+	};
+}
+/** A single-line text field. `type="password"` adds a button that shows what was typed. Placed in
+*  a Field, it takes the Field's label, description and invalid state. */
+function Input$1({ label, hint, help, description, error, className, mono, size, type, ref, ...props }) {
 	const [revealed, setRevealed] = useState(false);
 	const secret = type === "password";
 	return framed({
 		label,
 		hint,
+		help,
 		description,
-		error
+		error,
+		size
 	}, props, (control) => {
-		const input = /* @__PURE__ */ jsx("input", {
+		const input = /* @__PURE__ */ jsx(Input, {
 			ref,
 			...props,
-			...control,
-			"aria-invalid": control["aria-invalid"] ?? props["aria-invalid"],
-			"aria-describedby": [props["aria-describedby"], control["aria-describedby"]].filter(Boolean).join(" ") || void 0,
+			...joined(control, props),
 			type: secret && revealed ? "text" : type,
 			className: cx(fieldBox({ size }), mono && "font-mono", secret && "pr-9", className)
 		});
@@ -46,25 +59,27 @@ var Input = forwardRef(({ label, hint, description, error, className, mono, size
 			})]
 		}) : input;
 	});
-});
-Input.displayName = "Input";
-/** A multi-line text field that grows by hand. */
-var Textarea = forwardRef(({ label, hint, description, error, className, mono, size, ...props }, ref) => framed({
-	label,
-	hint,
-	description,
-	error
-}, props, (control) => /* @__PURE__ */ jsx("textarea", {
-	ref,
-	...props,
-	...control,
-	"aria-invalid": control["aria-invalid"] ?? props["aria-invalid"],
-	"aria-describedby": [props["aria-describedby"], control["aria-describedby"]].filter(Boolean).join(" ") || void 0,
-	className: cx(fieldBox({
-		size,
-		multiline: true
-	}), size === "sm" ? "min-h-16" : "min-h-24", "resize-y", mono && "font-mono", className)
-})));
-Textarea.displayName = "Textarea";
+}
+/** A multi-line text field that grows by hand. Placed in a Field, it takes the Field's label,
+*  description and invalid state. */
+function Textarea({ label, hint, help, description, error, className, mono, size, ref, ...props }) {
+	return framed({
+		label,
+		hint,
+		help,
+		description,
+		error,
+		size
+	}, props, (control) => /* @__PURE__ */ jsx(Input, {
+		...props,
+		...joined(control, props),
+		ref,
+		render: /* @__PURE__ */ jsx("textarea", {}),
+		className: cx(fieldBox({
+			size,
+			multiline: true
+		}), size === "sm" ? "min-h-16" : "min-h-24", "resize-y", mono && "font-mono", className)
+	}));
+}
 //#endregion
-export { Input, Textarea, framed };
+export { Input$1 as Input, Textarea, framed };

package/dist/components/Loader.js

@@ -31,7 +31,7 @@ function Loader({ size = 48, label, variant = "spinner", inline = false, color,
 		"aria-label": label || loading,
 		className: cx("items-center", inline ? "inline-flex gap-2" : "flex w-full flex-col justify-center gap-y-1"),
 		children: [/* @__PURE__ */ jsx("span", {
-			className: cx("inline-flex", !color && "text-(--theme-accent,#3b82f6)"),
+			className: cx("inline-flex", !color && "text-(--theme-accent)"),
 			style: color ? { color } : void 0,
 			children: variant === "logo" ? /* @__PURE__ */ jsx("svg", {
 				viewBox: "0 0 64.29 64.29",

package/dist/components/MenuEntries.d.ts

@@ -1,27 +1,51 @@
 import { type ReactNode } from 'react';
-/** Something a menu row does: navigates with `href`, or runs `onClick`. */
-export interface MenuAction {
+interface MenuActionBase {
     label: string;
     icon?: ReactNode;
-    /** Navigates instead of calling onClick. */
-    href?: string | undefined;
-    /** Loads the page instead of routing, for paths the host's router doesn't serve. */
-    reloadDocument?: boolean | undefined;
-    onClick?: (() => void) | undefined;
     disabled?: boolean | undefined;
     /** Why the action is disabled, shown on hover and read with its name. */
     disabledReason?: string | undefined;
     destructive?: boolean | undefined;
+    /** More text a menu's search matches, beside the label. */
+    keywords?: string | undefined;
+}
+/** Runs `onClick`. */
+interface MenuClickAction extends MenuActionBase {
+    onClick: () => void;
     /** Makes the row an on/off choice, checked while true. */
     checked?: boolean | undefined;
-    /** Text the row copies to the clipboard, confirmed with a toast naming `label`. */
-    copy?: {
+    href?: never;
+    reloadDocument?: never;
+    target?: never;
+    copy?: never;
+}
+/** Navigates to `href`. */
+interface MenuLinkAction extends MenuActionBase {
+    href: string;
+    /** Loads the page instead of routing, for paths the host's router doesn't serve. */
+    reloadDocument?: boolean | undefined;
+    /** `_blank` opens it in a new tab, such as a page outside the app. */
+    target?: '_blank' | undefined;
+    onClick?: never;
+    checked?: never;
+    copy?: never;
+}
+/** Copies `copy.text` to the clipboard, confirmed with a toast naming `copy.label`. */
+interface MenuCopyAction extends MenuActionBase {
+    copy: {
         text: string;
         label: string;
-    } | undefined;
-    /** More text a menu's search matches, beside the label. */
-    keywords?: string | undefined;
+    };
+    onClick?: never;
+    checked?: never;
+    href?: never;
+    reloadDocument?: never;
+    target?: never;
 }
+/** Something a menu row does: runs `onClick`, navigates to `href`, or copies
+ *  `copy`. Exactly one, so a row that does nothing when chosen doesn't compile.
+ *  A disabled action keeps its behavior; one that has none belongs out of the menu. */
+export type MenuAction = MenuClickAction | MenuLinkAction | MenuCopyAction;
 /** A row that opens a menu of its own. */
 export interface MenuSubmenu {
     label: string;
@@ -54,3 +78,10 @@ export declare function MenuEntries({ entries, search, query, }: {
     /** The search's text, from the MenuFilter around the menu's root. */
     query?: string;
 }): import("react").JSX.Element;
+/** Warns in development when an action has no behavior. The types rule that
+ *  out, but a JavaScript caller or a cast still can, and its row renders fine
+ *  and silently does nothing. */
+export declare function warnIfInert(action: MenuAction, where: string): void;
+/** Runs an action that isn't a link: copies its text or calls its onClick. */
+export declare function useRunAction(): (action: MenuAction) => void;
+export {};

package/dist/components/MenuEntries.js

@@ -1,15 +1,15 @@
 import { cx } from "../cx.js";
 import { MenuCheckboxItem, MenuItem, MenuLinkItem, MenuPopup, MenuSeparator, MenuSubmenuTrigger } from "./Menu.js";
-import { safeUrl } from "../safeUrl.js";
-import { EmptyState } from "./EmptyState.js";
+import { isDev } from "../dev.js";
 import { keyedByContent } from "./keys.js";
 import { Tooltip } from "./Tooltip.js";
-import { useLink } from "./Provider.js";
+import { AppLink } from "./AppLink.js";
+import { EmptyState } from "./EmptyState.js";
 import { useQueryMatch } from "./search.js";
 import { useCopy } from "./useCopy.js";
 import { Menu } from "@base-ui/react/menu";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { useState } from "react";
+import { useCallback, useState } from "react";
 //#region src/components/MenuEntries.tsx
 var menuDivider = { divider: true };
 var isMenuDivider = (entry) => "divider" in entry;
@@ -38,7 +38,7 @@ function MenuEntries({ entries, search, query = "" }) {
 			children: /* @__PURE__ */ jsx(Menu.Input, {
 				"aria-label": search.placeholder,
 				placeholder: search.placeholder,
-				className: "w-full rounded-md border border-(--theme-border) bg-(--theme-muted-panel-bg) px-2 py-1 text-[13px] text-(--theme-app) outline-none placeholder:text-(--theme-placeholder) focus:border-(--theme-accent)"
+				className: "w-full rounded-md border border-(--theme-border) bg-(--theme-muted-panel-bg) px-2 py-1 text-[13px] text-(--theme-app) outline-none placeholder:text-(--theme-placeholder) focus:border-(--theme-focus)"
 			})
 		}),
 		/* @__PURE__ */ jsx(Menu.List, { children: /* @__PURE__ */ jsx(EntryRows, { entries: shown }) }),
@@ -73,25 +73,40 @@ function SubmenuRow({ submenu }) {
 		})] })
 	});
 }
-var destructiveClassName = "text-(--theme-error) data-highlighted:text-(--theme-error)";
-function ActionRow({ action }) {
-	const Link = useLink();
+var destructiveClassName = "text-(--theme-error-text) data-highlighted:text-(--theme-error-text)";
+var warnedInert = /* @__PURE__ */ new Set();
+/** Warns in development when an action has no behavior. The types rule that
+*  out, but a JavaScript caller or a cast still can, and its row renders fine
+*  and silently does nothing. */
+function warnIfInert(action, where) {
+	if (!isDev()) return;
+	if (action.onClick || action.href || action.copy || warnedInert.has(action.label)) return;
+	warnedInert.add(action.label);
+	console.warn(`${where}: the action "${action.label}" has no onClick, href or copy, so choosing it does nothing.`);
+}
+/** Runs an action that isn't a link: copies its text or calls its onClick. */
+function useRunAction() {
 	const { copy } = useCopy();
+	return useCallback((action) => {
+		if (action.copy) copy(action.copy.text, { label: action.copy.label });
+		else action.onClick?.();
+	}, [copy]);
+}
+function ActionRow({ action }) {
+	warnIfInert(action, "MenuEntries");
+	const runAction = useRunAction();
 	const className = cx(action.destructive && destructiveClassName);
 	const content = /* @__PURE__ */ jsxs(Fragment, { children: [action.icon, action.label] });
-	if (action.href && !action.disabled) return action.reloadDocument ? /* @__PURE__ */ jsx(MenuLinkItem, {
-		href: safeUrl(action.href),
-		className,
-		children: content
-	}) : /* @__PURE__ */ jsx(MenuLinkItem, {
-		render: /* @__PURE__ */ jsx(Link, { href: action.href }),
+	if (action.href && !action.disabled) return /* @__PURE__ */ jsx(MenuLinkItem, {
+		render: /* @__PURE__ */ jsx(AppLink, {
+			href: action.href,
+			reloadDocument: action.reloadDocument,
+			target: action.target
+		}),
 		className,
 		children: content
 	});
-	const run = () => {
-		if (action.copy) copy(action.copy.text, { label: action.copy.label });
-		action.onClick?.();
-	};
+	const run = () => runAction(action);
 	const reason = action.disabled ? action.disabledReason : void 0;
 	const label = /* @__PURE__ */ jsxs(Fragment, { children: [content, reason && /* @__PURE__ */ jsxs("span", {
 		className: "sr-only",
@@ -115,4 +130,4 @@ function ActionRow({ action }) {
 	});
 }
 //#endregion
-export { MenuEntries, MenuFilter, isMenuDivider, isMenuSubmenu, menuDivider };
+export { MenuEntries, MenuFilter, isMenuDivider, isMenuSubmenu, menuDivider, useRunAction, warnIfInert };

package/dist/components/Meter.js

@@ -1,4 +1,5 @@
 import { cx } from "../cx.js";
+import { toneFill } from "./tone.js";
 import { Tooltip } from "./Tooltip.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Meter } from "@base-ui/react/meter";
@@ -6,10 +7,10 @@ import { Progress } from "@base-ui/react/progress";
 //#region src/components/Meter.tsx
 var fillClassName = {
 	accent: "bg-(--theme-accent)",
-	success: "bg-green-600",
-	warning: "bg-amber-500",
-	error: "bg-red-600",
-	muted: "bg-(--theme-muted-text-color)"
+	success: toneFill.success,
+	warning: toneFill.warning,
+	error: toneFill.error,
+	muted: toneFill.muted
 };
 var trackClassName = {
 	sm: "h-1",

package/dist/components/Modal.d.ts

@@ -6,9 +6,27 @@ export declare const modalPanelClassName = "rounded-xl border border-(--theme-bo
 export declare const ModalTitle: import("react").ForwardRefExoticComponent<Omit<import("@base-ui/react").DialogTitleProps, "ref"> & import("react").RefAttributes<HTMLHeadingElement>>;
 /** Describes the modal for assistive technology; renders a `<p>`. */
 export declare const ModalDescription: import("react").ForwardRefExoticComponent<Omit<import("@base-ui/react").DialogDescriptionProps, "ref"> & import("react").RefAttributes<HTMLParagraphElement>>;
-export interface ModalProps extends Omit<Dialog.Popup.Props, 'className' | 'children' | 'render'> {
+declare const sizeClasses: {
+    readonly sm: 'w-[400px]';
+    readonly md: 'w-[480px]';
+    readonly lg: 'w-[560px]';
+    readonly xl: 'w-[672px]';
+};
+export type ModalSize = keyof typeof sizeClasses;
+export interface ModalProps extends Omit<Dialog.Popup.Props, 'className' | 'children' | 'render' | 'title'> {
     open: boolean;
     onClose: () => void;
+    /** The header's heading, which names the modal. Without one, name it with
+     *  `aria-label`, or with a `ModalTitle` among the children. */
+    title?: ReactNode;
+    /** A line under the title, which describes the modal. */
+    description?: ReactNode;
+    /** Actions along the bottom edge, such as Cancel and Save, ruled off from the
+     *  body; they stay in view as a tall body scrolls. */
+    footer?: ReactNode;
+    /** Its width, which narrows to fit a small window. Without one, it's as wide
+     *  as its content. */
+    size?: ModalSize | undefined;
     /** A confirmation the person must answer: it takes the alertdialog role and the
      *  backdrop doesn't close it. Escape still cancels while it's dismissible. */
     alert?: boolean | undefined;
@@ -21,9 +39,15 @@ export interface ModalProps extends Omit<Dialog.Popup.Props, 'className' | 'chil
     panel?: boolean;
     /** The backdrop's dimming, for a modal that needs a darker or blurred stage. */
     backdropClassName?: string;
+    /** On the panel. */
     className?: string;
-    children: ReactNode;
+    /** The body. With a title or a footer it sits padded between them and scrolls
+     *  when the window is short; without either, it is the whole panel. */
+    children?: ReactNode;
 }
 /** A modal dialog: focus stays inside, the page behind is inert and doesn't scroll,
- *  and focus returns to where it was on close. Name it with `ModalTitle` or `aria-label`. */
-export declare function Modal({ open, onClose, alert, dismissible, align, panel, backdropClassName, className, children, ...popupProps }: ModalProps): import("react").JSX.Element;
+ *  and focus returns to where it was on close. Give it a `title`, a `description`
+ *  and a `footer` for the standard layout, as a Drawer has, or lay out the whole
+ *  panel with the children. */
+export declare function Modal({ open, onClose, title, description, footer, size, alert, dismissible, align, panel, backdropClassName, className, children, ...popupProps }: ModalProps): import("react").JSX.Element;
+export {};

package/dist/components/Modal.js

@@ -1,6 +1,6 @@
 import { cx } from "../cx.js";
-import { pressedToast } from "./Toast.js";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { closeHandler } from "./dismiss.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { AlertDialog } from "@base-ui/react/alert-dialog";
 import { Dialog } from "@base-ui/react/dialog";
 //#region src/components/Modal.tsx
@@ -10,23 +10,46 @@ var modalPanelClassName = "rounded-xl border border-(--theme-border) bg-(--theme
 var ModalTitle = Dialog.Title;
 /** Describes the modal for assistive technology; renders a `<p>`. */
 var ModalDescription = Dialog.Description;
+var sizeClasses = {
+	sm: "w-[400px]",
+	md: "w-[480px]",
+	lg: "w-[560px]",
+	xl: "w-[672px]"
+};
 /** A modal dialog: focus stays inside, the page behind is inert and doesn't scroll,
-*  and focus returns to where it was on close. Name it with `ModalTitle` or `aria-label`. */
-function Modal({ open, onClose, alert = false, dismissible = true, align = "top", panel = true, backdropClassName = "bg-black/40", className, children, ...popupProps }) {
-	const onOpenChange = (next, details) => {
-		if (next) return;
-		if (!dismissible && details.reason === "escape-key" || details.reason === "outside-press" && pressedToast(details.event)) {
-			details.cancel();
-			return;
-		}
-		onClose();
-	};
+*  and focus returns to where it was on close. Give it a `title`, a `description`
+*  and a `footer` for the standard layout, as a Drawer has, or lay out the whole
+*  panel with the children. */
+function Modal({ open, onClose, title, description, footer, size, alert = false, dismissible = true, align = "top", panel = true, backdropClassName = "bg-black/40", className, children, ...popupProps }) {
+	const onOpenChange = closeHandler(dismissible, onClose);
+	const header = title !== void 0 || description !== void 0;
+	const body = children !== void 0 && children !== null && children !== false;
+	const laidOut = header || footer !== void 0;
 	const content = /* @__PURE__ */ jsxs(Dialog.Portal, { children: [/* @__PURE__ */ jsx(Dialog.Backdrop, { className: cx("fixed inset-0 z-(--layer-modal)", backdropClassName) }), /* @__PURE__ */ jsx(Dialog.Viewport, {
 		className: cx("fixed inset-0 z-(--layer-modal) flex justify-center px-4 pt-20 pb-8", align === "center" ? "items-center" : "items-start sm:pt-[max(14vh,5rem)]"),
 		children: /* @__PURE__ */ jsx(Dialog.Popup, {
 			...popupProps,
-			className: cx(panel && "rounded-xl border border-(--theme-border) bg-(--theme-app-bg) text-(--theme-app) shadow-2xl", "outline-none", className),
-			children
+			className: cx(panel && "rounded-xl border border-(--theme-border) bg-(--theme-app-bg) text-(--theme-app) shadow-2xl", size && [sizeClasses[size], "max-w-full"], laidOut && "flex max-h-full flex-col", "outline-none", className),
+			children: laidOut ? /* @__PURE__ */ jsxs(Fragment, { children: [
+				header && /* @__PURE__ */ jsxs("div", {
+					className: cx("shrink-0 px-5 pt-5", !body && "pb-5"),
+					children: [title !== void 0 && /* @__PURE__ */ jsx(ModalTitle, {
+						className: "m-0 text-lg font-semibold",
+						children: title
+					}), description !== void 0 && /* @__PURE__ */ jsx(ModalDescription, {
+						className: "m-0 mt-1.5 text-sm text-(--theme-muted-text-color)",
+						children: description
+					})]
+				}),
+				body && /* @__PURE__ */ jsx("div", {
+					className: "min-h-0 flex-1 overflow-y-auto overscroll-contain px-5 py-4",
+					children
+				}),
+				footer !== void 0 && /* @__PURE__ */ jsx("div", {
+					className: "flex shrink-0 items-center justify-end gap-2 border-t border-(--theme-border) px-5 py-3",
+					children: footer
+				})
+			] }) : children
 		})
 	})] });
 	return alert ? /* @__PURE__ */ jsx(AlertDialog.Root, {

package/dist/components/Overview.d.ts

@@ -1,12 +1,20 @@
-export declare function Overview({ Icon, name, type, children, right, className, loading, iconSize, }: {
-    Icon: React.ReactNode;
-    name: string | React.ReactNode;
-    type?: string | React.ReactNode;
-    children?: React.ReactNode;
-    /** Right-aligned content on the header row (e.g. a detail-page action bar),
-     * vertically centered against the name block. */
-    right?: React.ReactNode;
-    className?: string;
-    loading?: boolean;
-    iconSize?: number;
-}): import("react").JSX.Element;
+import type { ReactNode } from 'react';
+export interface OverviewProps {
+    /** The thing's mark, such as its type's icon or an avatar. */
+    icon: ReactNode;
+    name: ReactNode;
+    /** Under the name, such as its kind. */
+    type?: ReactNode;
+    /** A row under the type, such as badges. */
+    children?: ReactNode;
+    /** At the row's end, centered against the name block, such as actions. */
+    actions?: ReactNode;
+    /** Sketches the icon and two lines while the thing loads. */
+    loading?: boolean | undefined;
+    /** The loading sketch's icon size, in pixels, to match the icon that replaces it. */
+    iconSize?: number | undefined;
+    className?: string | undefined;
+}
+/** A thing's summary at the top of its page: its mark, its name and kind, and
+ *  what to do with it. */
+export declare function Overview({ icon, name, type, children, actions, className, loading, iconSize, }: OverviewProps): import("react").JSX.Element;

package/dist/components/Overview.js

@@ -2,17 +2,19 @@ import { cx } from "../cx.js";
 import { LoadingRegion, Skeleton } from "./Skeleton.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/Overview.tsx
-function Overview({ Icon, name, type, children, right, className, loading, iconSize = 75 }) {
+/** A thing's summary at the top of its page: its mark, its name and kind, and
+*  what to do with it. */
+function Overview({ icon, name, type, children, actions, className, loading = false, iconSize = 75 }) {
 	return /* @__PURE__ */ jsxs("div", {
-		className: cx("flex items-center w-full", className),
+		className: cx("flex w-full items-center gap-3", className),
 		children: [
 			loading ? /* @__PURE__ */ jsx(Skeleton, {
 				circle: true,
 				height: iconSize,
 				className: "shrink-0"
-			}) : Icon,
+			}) : icon,
 			/* @__PURE__ */ jsx("div", {
-				className: "flex flex-col min-w-0 flex-1",
+				className: "flex min-w-0 flex-1 flex-col",
 				children: loading ? /* @__PURE__ */ jsx(LoadingRegion, {
 					className: "space-y-1",
 					children: /* @__PURE__ */ jsx(Skeleton, {
@@ -21,19 +23,22 @@ function Overview({ Icon, name, type, children, right, className, loading, iconS
 					})
 				}) : /* @__PURE__ */ jsxs(Fragment, { children: [
 					/* @__PURE__ */ jsx("div", {
-						className: "font-semibold text-xl tracking-tight",
+						className: "text-xl font-semibold tracking-tight",
 						children: name
 					}),
-					type && /* @__PURE__ */ jsx("p", { children: type }),
-					/* @__PURE__ */ jsx("div", {
+					type && /* @__PURE__ */ jsx("p", {
+						className: "m-0 text-sm text-(--theme-muted-text-color)",
+						children: type
+					}),
+					children && /* @__PURE__ */ jsx("div", {
 						className: "flex flex-row gap-x-2",
 						children
 					})
 				] })
 			}),
-			right && /* @__PURE__ */ jsx("div", {
+			actions && /* @__PURE__ */ jsx("div", {
 				className: "shrink-0 self-center",
-				children: right
+				children: actions
 			})
 		]
 	});

package/dist/components/PageHeader.d.ts

@@ -1,70 +1,52 @@
-import type { ComponentType, ReactNode } from 'react';
-import type { MenuEntry } from './MenuEntries.js';
-export interface PageHeaderBreadcrumb {
-    label: string;
-    href?: string;
-}
-/** A rendered crumb row entry, as handed to the breadcrumbPin slot. */
-export interface PageHeaderCrumb {
-    label: ReactNode;
-    href?: string;
-}
-/** With menu, the plus opens a chooser; otherwise navigates to or calls the
- * single action. `word` is the visible verb; `label` stays the full action for
- * the tooltip and screen readers. */
-export declare function HeaderAddButton({ href, onClick, label, word, menu, disabled, disabledHint, }: {
-    href?: string;
-    onClick?: () => void;
-    label: string;
-    word?: 'add' | 'create';
-    menu?: MenuEntry[];
-    /** Button mode only. */
-    disabled?: boolean;
-    disabledHint?: string;
-}): import("react").JSX.Element;
-/** The header's "…" menu of actions on the page's subject. */
-export declare function HeaderActionMenu({ items, label }: {
-    items: MenuEntry[];
-    label?: string;
-}): import("react").JSX.Element | null;
-export declare function HeaderEditButton({ href, onClick, label: labelProp, disabled, tooltip, }: {
-    href?: string;
-    onClick?: () => void;
-    label?: string;
-    disabled?: boolean;
-    tooltip?: string | undefined;
-}): import("react").JSX.Element;
-/** Renders nothing when the modern breadcrumb strip isn't mounted (classic chrome or self-headered pages). */
-export declare function BreadcrumbsTitleAction({ children }: {
-    children: ReactNode;
-}): import("react").ReactPortal | null;
-export declare function BreadcrumbsRightAction({ children }: {
+import type { ReactNode } from 'react';
+import { type Breadcrumb } from './pageHeaderStore.js';
+export type { Breadcrumb } from './pageHeaderStore.js';
+/**
+ * Holds the header the current page declares, for the `PageHeaderBar` the
+ * shell renders. Wrap the shell, above both the bar and the routes.
+ */
+export declare function PageHeaderProvider({ children }: {
     children: ReactNode;
-}): import("react").ReactPortal | null;
-export declare function BreadcrumbsActionButton({ icon: Icon, label, ariaLabel, href, onClick, disabled, tooltip, destructive, }: {
-    icon: ComponentType<{
-        className?: string;
-    }>;
-    label: string;
-    ariaLabel?: string;
-    href?: string;
-    onClick?: (() => void) | undefined;
-    disabled?: boolean;
-    tooltip?: string | undefined;
-    /** In the error color, as a destructive menu entry is, for an action that removes or breaks
-     *  something. */
-    destructive?: boolean | undefined;
 }): import("react").JSX.Element;
-interface PageHeaderProps {
-    breadcrumbs?: PageHeaderBreadcrumb[] | undefined;
-    title?: ReactNode;
-    titleAction?: ReactNode;
+export interface PageHeaderProps {
+    /** The trail to this page, ending with the page itself, which becomes its
+     *  `h1`. A crumb with an empty label, such as a name still loading, shows a
+     *  placeholder. */
+    breadcrumbs?: readonly Breadcrumb[] | undefined;
+    /** Beside the title: actions on the page's subject, such as edit, rename or
+     *  favorite, or its `PageHeaderMenu`. */
+    titleActions?: ReactNode;
+    /** At the end of the bar: the page's commands, such as Save or "+ Create". */
     actions?: ReactNode;
+    /** A row under the bar, such as tabs or a time range, that stays put while
+     *  the page scrolls. */
     toolbar?: ReactNode;
-    className?: string;
-    sticky?: boolean;
-    /** Negative offset (e.g. -top-4) prevents rows peeking above the header when the container has top padding. */
-    stickyTopClassName?: string;
+    /** Takes the bar away, for a page that fills the window. */
+    hidden?: boolean | undefined;
+}
+/**
+ * Declares the page's header: its breadcrumbs, title actions, actions and
+ * toolbar. Under a `PageHeaderProvider` it renders nothing in place: the
+ * shell's `PageHeaderBar` shows it, while the actions stay in the page's React
+ * tree, with its context and state. Without a provider it renders the bar
+ * itself, for a page with no shell.
+ *
+ * Any component may render one, such as a form adding its Save button: the bar
+ * shows the actions of all of them, outermost first, and the trail of the last
+ * one rendered that has one, so a page's trail replaces its layout's.
+ */
+export declare function PageHeader(props: PageHeaderProps): import("react").JSX.Element | null;
+export interface PageHeaderBarProps {
+    /** A shorter bar, for a page that gives the window to an embedded app. */
+    compact?: boolean | undefined;
+    /** Keep the bar when the page declares nothing, such as on a narrow screen
+     *  where it holds the navigation toggle. A page's `hidden` still wins. */
+    persistent?: boolean | undefined;
+    className?: string | undefined;
 }
-export declare function PageHeader({ breadcrumbs, title, titleAction, actions, toolbar, className, sticky, stickyTopClassName, }: PageHeaderProps): import("react").JSX.Element;
-export {};
+/**
+ * The bar showing what the current page declares with `PageHeader`. The shell
+ * renders one, inside a `PageHeaderProvider`, wherever its chrome puts it. It
+ * renders nothing while the page declares nothing.
+ */
+export declare function PageHeaderBar({ compact, persistent, className, }: PageHeaderBarProps): import("react").JSX.Element | null;