@botiverse/raft-ui 0.81.0 → 0.83.0

package/CHANGELOG.md

@@ -1,3 +1,83 @@
+## [0.83.0](https://github.com/botiverse/raft-design/compare/v0.82.0...v0.83.0) (2026-11-10)
+
+### Added
+
+- **`placement="top"` on DialogContent**, on a desktop and a tablet (and on DialogSheetContent there): the dialog stays centered across, its top edge at `var(--dialog-top, 8vh)`, and it is never taller than the window less that top and 16px, so it never runs past the window's bottom. Its width still comes from `size`. The content carries `data-placement="top"`. To anchor the card to something, the app measures it and sets `--dialog-top` in the content's `style`; raft-ui measures nothing. Below 768px it does nothing.
+  - Why: search opens from the top bar's field, and its panel's top edge belongs on the field, which a centered dialog can't do (slock drew it on DialogSurface with its own positioning, #triage:#278).
+  - Affects: nothing until a dialog passes `placement="top"`: `"center"`, the default, renders the same DOM and classes as before.
+  - Docs: https://raft-design.botiverse.build/components/dialog/#at-the-top
+- **On a phone every centered dialog moves up while the on-screen keyboard is open**, whatever its `placement`: its top edge goes where the phone's top bar ends (`--header-height` below the top of what is visible, under the status bar), it ends at least 16px above the keyboard, and it goes back to the middle when the keyboard closes. While lifted the content carries `data-soft-keyboard`. A phone sheet doesn't move; it keeps its own keyboard box.
+  - Why: a centered dialog covered by the keyboard is always wrong, its field or its buttons out of sight, so this is platform behavior and no app opts in (stdrc, 2026-10-21: centered unless the keyboard is open). slock did it with its own `narrow="top"`; that maps to the default now.
+  - Affects: every centered `DialogContent` below 768px, only while a text field in it has focus and the visible area is over 100px shorter than the window; at rest nothing changes. A DialogSheetContent's keyboard box now reads the keyboard through the same check, once a frame: a focused checkbox, radio or button no longer counts as typing. An app that lifted its dialogs itself (slock's `narrow="top"`) can drop that code.
+  - Docs: https://raft-design.botiverse.build/components/dialog/#the-keyboard
+- **SelectionToolbar** (from `@botiverse/raft-ui/wip`): the floating toolbar for selected items (messages, tasks), in the BatchBar style. `SelectionToolbarDock` floats it 12px above the bottom (plus the safe area) and 20px from the sides; `SelectionToolbarCount` (with the number in `SelectionToolbarCountValue`, Space Mono), `SelectionToolbarHint`, `SelectionToolbarActions` with `SelectionToolbarAction` (`secondary`, `menu`, `moreItem`), `SelectionToolbarMore` with `SelectionToolbarMoreItems` in its menu, `SelectionToolbarItem` for another control such as a select-all checkbox, and `SelectionToolbarClose`. A floating panel's frame (`line-seam` ring, `shadow-float`) as tall as a head: 44px with `md` buttons 4px apart with a mouse, 56px with 44px bar buttons side by side showing their icons alone by touch. It is a Base UI Toolbar (one Tab stop, arrow keys inside) and never wraps: when its row doesn't fit the width it floats in, measured, the hint, the secondary actions, the labels (the first action's last) and then the other actions give way, the last first; the count and × stay.
+  - Why: the toolbar for selected items is one bar shared by message multi-select and task bulk actions, in Noel's BatchBar style: `md` ghost buttons with a 14px icon and a label, no primary (stdrc, 2026-11-10, #wg-task-v2); by touch it aligns with the head, so a phone fits the tasks' Status, Assignee and Nudge at 360px (Noel, 2026-11-10).
+  - Affects: nothing yet. The stable `MessageMultiSelectToolbar` and `MessageMultiSelectToolbarActions` keep their earlier bar until SelectionToolbar leaves wip; move to it from `@botiverse/raft-ui/wip` when you are ready.
+  - Docs: https://raft-design.botiverse.build/components/selection-toolbar/, https://raft-design.botiverse.build/components/#toolbar-for-selected-items
+- **FitToolbar** (from `@botiverse/raft-ui/wip`): a Base UI Toolbar whose items give way in named steps as the region it sits in narrows: `label` (to an icon), `more` (into More), `collapse` (a group to one button) and `wrap` (a group to a line of its own, with `wrap`; groups with the same `wrapLine` share one, and a wrapped group gets back what its items gave before it wrapped). Items declare their steps and order with `useFitItem`, or are a `FitToolbarButton`; a `FitToolbarGroup overflow="scroll"` scrolls sideways instead, its `data-active` items kept in view; groups are `FitToolbarGroup` (`firstLine`, `wrapOrder`, `wrapLine`, `collapsed`, `collapseOrder`); More takes `useFitMore` and lists `FitToolbarMoreItems`. It measures its own region's width, never the window's, again when its content changes on its own, and writes each step as `data-fit-<step>`. A SegmentedControl inside it follows its `label` step; its own `iconsOnlyBelow` is off there.
+  - Why: one measured engine for every toolbar that has to give way (responsive.md "measure the content rather than guess a width"), used by SelectionToolbar now and meant for the list toolbars of #proj-raft-ui:#225, instead of a breakpoint guess or a hook per app. Its step names and API stay in wip until sindresorhus confirms them for those toolbars.
+  - Docs: https://raft-design.botiverse.build/components/fit-toolbar/
+
+### Changed
+
+- **DialogSheetContent, DialogCommit and DialogSheetBack are stable**: import them, and their props types, from `@botiverse/raft-ui`. `@botiverse/raft-ui/wip` no longer exports them.
+  - Why: slock is moving its own dialogs, its phone sheets among them, onto raft-ui (#triage:#278), and a product builds on the stable entry.
+  - Affects: an import from `@botiverse/raft-ui/wip` fails; import from `@botiverse/raft-ui` instead. No app imported them from `/wip` (slock draws its sheets itself today), and the docs' examples have moved.
+  - Docs: https://raft-design.botiverse.build/components/dialog/#making-a-dialog-a-sheet
+
+### Fixed
+
+- **A label/value list puts its labels above when a chip or a long word of a wrapping value can't fit beside its label**: DescriptionList `direction="horizontal"` and MessageActionCard's properties now also stack when one chip of a value that wraps either way (a row of chips wider than the list) is wider than the value column but no wider than the list, and likewise when a long word in such a value (an ID, a commit SHA, a URL) is: beside the label the chip was cut and the word ran past the value column. A word set to `overflow-wrap: anywhere` breaks where it must, and doesn't decide. There is no new prop.
+  - Why: the one-line rule let a row of chips wider than the list stay beside its labels, where one long chip was cut off with no way to read it (mobile #4507, the Computer page's Detected Runtimes chip).
+  - Affects: lists whose value wraps either way and holds a chip or a long word wider than the value column now stack instead of staying beside their labels (slock's Computer page among them). Such a word used to run past the value column in DescriptionList and break mid-word in MessageActionCard properties; it now reads whole on its own line. Every other list lays out as before; the extra measurement runs only for values wider than the list.
+  - Docs: https://raft-design.botiverse.build/components/description-list/#labels-go-above-only-when-a-value-doesnt-fit
+- **The server tab's popover keeps one whole server row and opens on the current server**: `MobileNavServerPopoverList` is never shorter than one two-line row. Where the footer actions and the pages would leave it less inside 60% of the screen, `MobileNavServerPopoverContent` grows past 60% as far as that row needs; where the screen is too short even for that, the whole popover scrolls, the footer and the pages with it, in a ScrollArea. On open the list scrolls, with no animation, to the row with `aria-current="true"`, and focus goes to that row (a touch still focuses the popover itself), so focus no longer scrolls the list back to the top.
+  - Why: with 5 pages in the grid, a 360dp phone squeezed the list until the current server was half hidden, and the list always opened at the top (Lagoon, mobile #4500; Jasper's review of raft-design #1117).
+  - Affects: every `MobileNavServerPopoverContent`. A popover that fit before is unchanged except that it opens scrolled to the current server; one whose list was squeezed below a row is now taller than 60%, or scrolls as a whole. Opening from a mouse or keyboard focuses the current server's row instead of the first row; pass `initialFocus` to choose otherwise. The popover's parts now sit in a ScrollArea (`data-slot="mobile-nav-server-popover-scroll"`) inside the popup, so a selector for a direct child of `mobile-nav-server-popover-content` no longer matches them. Mark the current server's row with `aria-current="true"` for the scroll and the focus to find it.
+  - Docs: https://raft-design.botiverse.build/components/mobile-nav/#the-server-tab
+- **A settings row's switch centers on its text, not on the SaveStatus line under it**: in a `ListRow variant="plain"` whose `ListRowBody` ends with a `SaveStatus`, both ends (the switch, value, chevron, checkbox, radio or button, and a leading icon, avatar or tile) center on the title and description. The row moves the line's reserved space (4px and one footnote line) into its bottom padding, so its height is unchanged and nothing moves when "Saved" or a one-line error appears. There is no new prop.
+  - Why: the ends centered on the whole body, the empty reserved line included, so the switch sat visibly below the text (slock's Administration › Hide #all channel; Jasper and Kirby, 2026-11-09, #proj-raft-ui:#220).
+  - Affects: in such rows the ends move up by half the reserved line (11px). A row without a `SaveStatus` is unchanged. An error that wraps still grows the row, and the ends move down by half of each extra line. Beside a title alone on a phone, the 30px switch keeps 12px above it, so that row is 76px instead of 70px. A local wrapper that put an invisible line under the switch to compensate (slock's) now lifts it too far: remove it.
+  - Docs: https://raft-design.botiverse.build/components/list-row/#anatomy, https://raft-design.botiverse.build/components/save-status/#behavior
+
+## [0.82.0](https://github.com/botiverse/raft-design/compare/v0.81.0...v0.82.0) (2026-11-09)
+
+### Changed
+
+- **OtterIndicator uses Ottie's approved four poses**: relaxed side-lying, quiet typing, a puzzled head tilt with a question mark, and one celebratory hop. The SVG props and ref remain supported. It pauses outside the viewport and in hidden documents; reduced motion shows a still. The HTML art layer sizes from the SVG box so Safari/WebKit scales it correctly at 40px and larger.
+  - Why: the previous unrelated otter drawing and sleeping wait pose did not match Ottie or the recent-activity card (Artea's approved B study).
+  - Affects: consumers of OtterIndicator, including Raft's recent-activity card. Artwork loads as separate transparent WebP files only for a displayed status; there is no frame timer or per-frame React update.
+  - Docs: https://raft-design.botiverse.build/components/steps/#ottie-illustration
+
+### Breaking
+
+- **`ComposerDropOverlayPrompt` takes its text as `children`, which is required**: the icon cluster stays, and the text under it is what you pass. It no longer falls back to the built-in "Drop files to attach", and children no longer replace the icons.
+  - Why: the component library carried product copy in English that no app could translate (Remy's helper-text sweep, #proj-workspace:#250).
+  - Affects: `<ComposerDropOverlayPrompt />` no longer type-checks; pass the text, e.g. `<ComposerDropOverlayPrompt>{t("dropToAttach")}</ComposerDropOverlayPrompt>`. A caller that passed children for a label without icons uses `ComposerDropOverlayLabel` instead.
+  - Docs: https://raft-design.botiverse.build/components/composer/
+
+### Added
+
+- **Data parts beside the explanation parts**: three additive parts, so data no longer has to sit in a slot meant for a sentence that explains. Nothing existing changes: no prop, part or style is renamed or restyled.
+  - `ListRowSubtitle`: data about a row's subject under its title (an agent's description, a channel's topic, an app's byline), in the title's ink at 400 and `text-footnote`. It follows the row's tone and disabled state with the title. `ListRowDescription` stays the place for a setting's consequence.
+  - ChoiceList items take `meta`: lines of data people compare across rows (a quota, free disk, a count, a status), in `text-footnote` in `foreground-muted` as the description is, after the `description` lines. A row still draws at most two lines in all, the description's first; a meta line has a description line's height, so moving a line from one to the other doesn't move the rows. Radios and checkboxes are described by the description lines, then the meta lines.
+  - `MessageActionCardHeaderMeta`: the time on a resolved card, in Space Mono at the hint tier: a line of its own under the title, or the end of the `MessageActionCardHeaderDescription` line it is placed in ("Approved by Martin · 10:51").
+  - Why: grey text is to mean one of two things, a sentence written to explain or a component's own notes on its data (times, counts, IDs), and data people read as the content uses the body ink. Apps had put data in the explanation parts (`ListRowDescription`, a ChoiceList item's `description`, `MessageActionCardHeaderDescription`) because there was nowhere else for it; these parts give it a place before those parts are kept for explanations (Kirby, Remy's helper-text plan).
+  - Affects: nothing until an app uses them. Data moved into `ListRowSubtitle` gets darker and a size smaller than in `ListRowDescription`; data moved into a ChoiceList item's `meta` looks as it did in `description`; a time moved into `MessageActionCardHeaderMeta` is set in Space Mono at the hint tier.
+  - Docs: https://raft-design.botiverse.build/components/list-row/#data-and-explanation, https://raft-design.botiverse.build/components/choice-list/#content, https://raft-design.botiverse.build/components/message-action-card/#anatomy
+
+### Fixed
+
+- **A Resizable seam's handle no longer covers the scrollbar beside it**: the 12px handle (24px under a coarse pointer) lies over the start of the panel after the boundary instead of straddling it; its hover and focus line stays on the seam.
+  - Why: a panel's scrollbar runs along its end edge, the seam's other side, and the centered handle covered its last 6px, where the thumb is, so dragging the thumb resized the panel instead (Raft app's Activity list, #proj-raft-ui:21bae128).
+  - Affects: the handle now takes the pointer over the first 12px of the next panel (24px by touch) instead of 6px on each side. Nothing else moves.
+  - Docs: https://raft-design.botiverse.build/components/resizable/#behavior
+
+- **ScrollArea measures in the frame after mounting, not while React commits**: where a `ResizeObserver` watches the sizes, the first read of the container's `clientHeight` and `scrollHeight` waits for the next animation frame, as every later one already did. Without a `ResizeObserver` it still measures at once.
+  - Why: the read in the commit forced a layout of the whole page each time an area mounted. Entering a server in the Raft app mounts the sidebar, the message list and the panels at once, and those reads took about 120ms of layout (InNOut's measurement, #proj-frontend:#40).
+  - Affects: the frame runs before the paint that first shows the area, so nothing on screen changes. Until it runs, an overflowing area has no thumb length and no overflow classes, and `onEdgeChange` is first called in it: code that reads them in a layout effect right after mounting finds them unset, and can call `actionsRef.measure` for a measure at once.
+  - Docs: https://raft-design.botiverse.build/components/scroll-area/
+
 ## [0.81.0](https://github.com/botiverse/raft-design/compare/v0.80.0...v0.81.0) (2026-11-09)
 
 ### Fixed

package/dist/components/choice-list/choice-list.d.mts

@@ -11,6 +11,14 @@ export type ChoiceListItem = {
    * (null, false or "") is not drawn. Colour inside a line is the caller's.
    */
   description?: ReactNode | readonly ReactNode[];
+  /**
+   * Lines of data under the description: what people compare across rows,
+   * such as a quota, free disk or a count ("120 GB free · 3 agents"), drawn
+   * as the description is (muted), after it. The row still draws at most two
+   * lines under the name, the description's first. An empty line is not
+   * drawn. Colour inside a line is the caller's.
+   */
+  meta?: ReactNode | readonly ReactNode[];
   /** Drawn before the radio's or checkbox's row text: an avatar, an icon. */
   media?: ReactNode;
   /**

package/dist/components/choice-list/choice-list.mjs

@@ -18,6 +18,13 @@ function isDrawn(line) {
 function descriptionLines(description) {
 	return (Array.isArray(description) ? description : [description]).filter(isDrawn);
 }
+function rowLines(item) {
+	const description = descriptionLines(item.description).slice(0, MAX_DESCRIPTION_LINES);
+	return {
+		description,
+		meta: descriptionLines(item.meta).slice(0, MAX_DESCRIPTION_LINES - description.length)
+	};
+}
 function CutLine({ id, slot, className, children }) {
 	const ref = useOverflowTitle();
 	return /* @__PURE__ */ jsx("span", {
@@ -133,6 +140,7 @@ function ChoiceList(props) {
 		if (process.env.NODE_ENV === "production") return;
 		if (!ariaLabel && !ariaLabelledBy) console.warn("raft-ui: a ChoiceList has neither aria-label nor aria-labelledby.");
 		if (items.some((item) => descriptionLines(item.description).length > MAX_DESCRIPTION_LINES)) console.warn(`raft-ui: a ChoiceList item has more than ${MAX_DESCRIPTION_LINES} description lines; only the first ${MAX_DESCRIPTION_LINES} are drawn.`);
+		else if (items.some((item) => descriptionLines(item.description).length + descriptionLines(item.meta).length > MAX_DESCRIPTION_LINES)) console.warn(`raft-ui: a ChoiceList item has more than ${MAX_DESCRIPTION_LINES} description and meta lines together; only the first ${MAX_DESCRIPTION_LINES} are drawn, the description's first.`);
 	}, [
 		ariaLabel,
 		ariaLabelledBy,
@@ -166,13 +174,14 @@ function ChoiceList(props) {
 	};
 	const rowElement = (item) => {
 		const id = `${baseId}-${items.indexOf(item)}`;
-		const lines = descriptionLines(item.description).slice(0, MAX_DESCRIPTION_LINES);
+		const { description: lines, meta } = rowLines(item);
 		const rowDisabled = disabled || item.disabled === true;
+		const describedBy = [lines.length > 0 ? `${id}-description` : null, meta.length > 0 ? `${id}-meta` : null].filter(Boolean);
 		const markProps = {
 			value: item.value,
 			disabled: item.disabled,
 			"aria-labelledby": `${id}-label`,
-			"aria-describedby": lines.length > 0 ? `${id}-description` : void 0
+			"aria-describedby": describedBy.length > 0 ? describedBy.join(" ") : void 0
 		};
 		return /* @__PURE__ */ jsxs("label", {
 			"data-slot": "choice-list-item",
@@ -188,20 +197,32 @@ function ChoiceList(props) {
 				/* @__PURE__ */ jsxs("span", {
 					"data-slot": "choice-list-body",
 					className: slots.body(),
-					children: [/* @__PURE__ */ jsx(CutLine, {
-						id: `${id}-label`,
-						slot: "choice-list-label",
-						className: slots.label(),
-						children: item.label
-					}), lines.length > 0 ? /* @__PURE__ */ jsx("span", {
-						id: `${id}-description`,
-						className: "contents",
-						children: lines.map((line, index) => /* @__PURE__ */ jsx(CutLine, {
-							slot: "choice-list-description",
-							className: slots.description(),
-							children: line
-						}, index))
-					}) : null]
+					children: [
+						/* @__PURE__ */ jsx(CutLine, {
+							id: `${id}-label`,
+							slot: "choice-list-label",
+							className: slots.label(),
+							children: item.label
+						}),
+						lines.length > 0 ? /* @__PURE__ */ jsx("span", {
+							id: `${id}-description`,
+							className: "contents",
+							children: lines.map((line, index) => /* @__PURE__ */ jsx(CutLine, {
+								slot: "choice-list-description",
+								className: slots.description(),
+								children: line
+							}, index))
+						}) : null,
+						meta.length > 0 ? /* @__PURE__ */ jsx("span", {
+							id: `${id}-meta`,
+							className: "contents",
+							children: meta.map((line, index) => /* @__PURE__ */ jsx(CutLine, {
+								slot: "choice-list-meta",
+								className: slots.meta(),
+								children: line
+							}, index))
+						}) : null
+					]
 				})
 			]
 		}, item.value);

package/dist/components/choice-list/choice-list.recipe.mjs

@@ -22,6 +22,7 @@ const choiceList = tv({
 		body: ["grid min-w-0 flex-1 gap-0.5"],
 		label: ["truncate font-semibold text-foreground", "in-data-disabled:text-foreground-disabled"],
 		description: ["block truncate font-sans text-footnote font-normal text-foreground-muted", "in-data-disabled:text-foreground-disabled"],
+		meta: ["block truncate font-sans text-footnote font-normal text-foreground-muted", "in-data-disabled:text-foreground-disabled"],
 		action: [
 			"relative z-10 col-start-2 flex h-lh items-center self-start pr-1",
 			"mt-option-inset pointer-coarse:mt-[calc((--spacing(11)-1lh)/2)]",

package/dist/components/composer/composer-drop-overlay.d.mts

@@ -1,9 +1,14 @@
+import * as React from "react";
 import { useRender } from "@base-ui/react/use-render";
 //#region src/components/composer/composer-drop-overlay.d.ts
 export type ComposerDropOverlayProps = useRender.ComponentProps<"div">;
-export declare function ComposerDropOverlay({ className, render, ...props }: ComposerDropOverlayProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export declare function ComposerDropOverlay({ className, render, ...props }: ComposerDropOverlayProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
 export type ComposerDropOverlayLabelProps = useRender.ComponentProps<"span">;
-export declare function ComposerDropOverlayLabel({ className, render, ...props }: ComposerDropOverlayLabelProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
-export type ComposerDropOverlayPromptProps = ComposerDropOverlayLabelProps;
-export declare function ComposerDropOverlayPrompt({ children, ...props }: ComposerDropOverlayPromptProps): import("react").JSX.Element;
+export declare function ComposerDropOverlayLabel({ className, render, ...props }: ComposerDropOverlayLabelProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
+export type ComposerDropOverlayPromptProps = Omit<ComposerDropOverlayLabelProps, "children"> & {
+  /** What the prompt says, such as "Drop files to attach": the caller's copy, in its locale. */
+  children: React.ReactNode;
+};
+/** The label with the files-and-upload icon cluster above the caller's text. */
+export declare function ComposerDropOverlayPrompt({ children, ...props }: ComposerDropOverlayPromptProps): React.JSX.Element;
 //#endregion

package/dist/components/composer/composer-drop-overlay.mjs

@@ -28,12 +28,9 @@ function ComposerDropOverlayLabel({ className, render, ...props }) {
 		props: mergeProps(defaultProps, props)
 	});
 }
+/** The label with the files-and-upload icon cluster above the caller's text. */
 function ComposerDropOverlayPrompt({ children, ...props }) {
 	const { dropOverlayIcon, dropOverlayIconCluster } = composerDropOverlay();
-	if (children) return /* @__PURE__ */ jsx(ComposerDropOverlayLabel, {
-		...props,
-		children
-	});
 	return /* @__PURE__ */ jsxs(ComposerDropOverlayLabel, {
 		...props,
 		children: [/* @__PURE__ */ jsxs("span", {
@@ -53,7 +50,7 @@ function ComposerDropOverlayPrompt({ children, ...props }) {
 					children: /* @__PURE__ */ jsx(Image, { className: "text-foreground-muted" })
 				})
 			]
-		}), /* @__PURE__ */ jsx("span", { children: "Drop files to attach" })]
+		}), /* @__PURE__ */ jsx("span", { children })]
 	});
 }
 //#endregion

package/dist/components/dialog/dialog-sheet-context.mjs

@@ -12,6 +12,11 @@ const DialogSheetContext = createContext(NO_SHEET);
 function useDialogSheet() {
 	return useContext(DialogSheetContext);
 }
+/**
+* True around the DialogContent a `DialogSheetContent` draws as a phone
+* sheet: the sheet has its own keyboard box, so the content doesn't lift.
+*/
+const DialogSheetSurfaceContext = createContext(false);
 /** Inside the sheet's head: its × is a pushed page's leading action. */
 const DialogSheetHeadContext = createContext(false);
 function useInDialogSheetHead() {
@@ -23,7 +28,7 @@ function useInDialogSheetHead() {
 * button instead of taking the sheet's.
 */
 function DialogSheetReset({ children }) {
-	return createElement(DialogSheetContext.Provider, { value: NO_SHEET }, createElement(DialogSheetHeadContext.Provider, { value: false }, children));
+	return createElement(DialogSheetSurfaceContext.Provider, { value: false }, createElement(DialogSheetContext.Provider, { value: NO_SHEET }, createElement(DialogSheetHeadContext.Provider, { value: false }, children)));
 }
 /**
 * A dialog drawn as a phone sheet (design: dialog.md "On a phone"). The
@@ -55,4 +60,4 @@ const dialogSheet = tv({ slots: {
 	bodyEnd: ["mt-4 empty:hidden", "text-start font-sans text-footnote text-foreground-muted *:data-[slot=text-link]:text-footnote"]
 } });
 //#endregion
-export { DialogSheetContext, DialogSheetHeadContext, DialogSheetReset, NO_SHEET, dialogSheet, useDialogSheet, useInDialogSheetHead };
+export { DialogSheetContext, DialogSheetHeadContext, DialogSheetReset, DialogSheetSurfaceContext, NO_SHEET, dialogSheet, useDialogSheet, useInDialogSheetHead };

package/dist/components/dialog/dialog-sheet.d.mts

@@ -10,9 +10,10 @@ export type DialogSheetContentProps = DialogContentProps;
  * up over its scrim; `DialogHeader` becomes a pushed page's head (× at the
  * start, the title, the `DialogCommit` button at the end), `DialogFooter` is
  * hidden (× is Cancel) and `DialogBody` scrolls on the phone's 16px margin
- * above the home indicator. Base UI keeps Esc, focus and close.
+ * above the home indicator. Base UI keeps Esc, focus and close. `placement`
+ * applies on a desktop and a tablet only: the sheet is docked to the bottom.
  */
-export declare function DialogSheetContent({ className, overlay, style, ref, children, ...props }: DialogSheetContentProps): import("react").JSX.Element;
+export declare function DialogSheetContent({ className, overlay, placement, style, ref, children, ...props }: DialogSheetContentProps): import("react").JSX.Element;
 export type DialogCommitProps = ButtonProps;
 /**
  * The dialog's one commit button: a `Button`, written where it goes on a

package/dist/components/dialog/dialog-sheet.mjs

@@ -1,8 +1,9 @@
 import { cn } from "../../cn.mjs";
 import { Button } from "../button/button.mjs";
-import { DialogSheetContext, dialogSheet, useDialogSheet } from "./dialog-sheet-context.mjs";
-import { DialogContent } from "./dialog.mjs";
+import { DialogSheetContext, DialogSheetSurfaceContext, dialogSheet, useDialogSheet } from "./dialog-sheet-context.mjs";
 import { useMobileViewport } from "../../lib/use-mobile-viewport.mjs";
+import { useSoftKeyboard } from "../../lib/use-soft-keyboard.mjs";
+import { DialogContent } from "./dialog.mjs";
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { createPortal } from "react-dom";
@@ -14,9 +15,10 @@ import { createPortal } from "react-dom";
 * up over its scrim; `DialogHeader` becomes a pushed page's head (× at the
 * start, the title, the `DialogCommit` button at the end), `DialogFooter` is
 * hidden (× is Cancel) and `DialogBody` scrolls on the phone's 16px margin
-* above the home indicator. Base UI keeps Esc, focus and close.
+* above the home indicator. Base UI keeps Esc, focus and close. `placement`
+* applies on a desktop and a tablet only: the sheet is docked to the bottom.
 */
-function DialogSheetContent({ className, overlay, style, ref, children, ...props }) {
+function DialogSheetContent({ className, overlay, placement, style, ref, children, ...props }) {
 	const phone = useMobileViewport();
 	const [commitSlot, setCommitSlot] = useState(null);
 	const [bodyEndSlot, setBodyEndSlot] = useState(null);
@@ -51,16 +53,20 @@ function DialogSheetContent({ className, overlay, style, ref, children, ...props
 		...style,
 		...keyboardBox
 	} : style, [style, keyboardBox]);
-	return /* @__PURE__ */ jsx(DialogContent, {
-		...props,
-		ref: setRef,
-		overlay: phone ? sheetOverlay : overlay,
-		className: phone ? cn(className, sheet.content()) : className,
-		style: phone ? sheetStyle : style,
-		"data-sheet": phone ? "" : void 0,
-		children: /* @__PURE__ */ jsx(DialogSheetContext.Provider, {
-			value: state,
-			children
+	return /* @__PURE__ */ jsx(DialogSheetSurfaceContext.Provider, {
+		value: phone,
+		children: /* @__PURE__ */ jsx(DialogContent, {
+			...props,
+			ref: setRef,
+			placement: phone ? void 0 : placement,
+			overlay: phone ? sheetOverlay : overlay,
+			className: phone ? cn(className, sheet.content()) : className,
+			style: phone ? sheetStyle : style,
+			"data-sheet": phone ? "" : void 0,
+			children: /* @__PURE__ */ jsx(DialogSheetContext.Provider, {
+				value: state,
+				children
+			})
 		})
 	});
 }
@@ -132,36 +138,16 @@ function DialogCommit({ size, form, onClick, ...props }) {
 * keyboard. `undefined` otherwise (the CSS box).
 */
 function useSheetKeyboardBox(active) {
-	const [box, setBox] = useState(void 0);
-	useEffect(() => {
-		const viewport = typeof window === "undefined" ? void 0 : window.visualViewport;
-		if (!active || !viewport) return;
-		const update = () => {
-			const focused = document.activeElement;
-			const keyboardUp = (focused instanceof HTMLInputElement || focused instanceof HTMLTextAreaElement || focused instanceof HTMLElement && focused.isContentEditable) && window.innerHeight - viewport.height > 100;
-			const height = Math.round(Math.min(viewport.height, window.innerHeight * .9));
-			const top = Math.round(Math.max(viewport.offsetTop, 0) + viewport.height - height);
-			setBox((previous) => {
-				if (!keyboardUp) return void 0;
-				return previous?.top === `${top}px` && previous?.height === `${height}px` ? previous : {
-					top: `${top}px`,
-					bottom: "auto",
-					height: `${height}px`
-				};
-			});
-		};
-		viewport.addEventListener("resize", update);
-		viewport.addEventListener("scroll", update, { passive: true });
-		document.addEventListener("focusin", update);
-		document.addEventListener("focusout", update);
-		return () => {
-			viewport.removeEventListener("resize", update);
-			viewport.removeEventListener("scroll", update);
-			document.removeEventListener("focusin", update);
-			document.removeEventListener("focusout", update);
+	const keyboard = useSoftKeyboard(active);
+	return useMemo(() => {
+		if (!keyboard) return void 0;
+		const height = Math.round(Math.min(keyboard.height, keyboard.windowHeight * .9));
+		return {
+			top: `${keyboard.top + keyboard.height - height}px`,
+			bottom: "auto",
+			height: `${height}px`
 		};
-	}, [active]);
-	return active ? box : void 0;
+	}, [keyboard]);
 }
 /**
 * The commit is at the top of a sheet, so an error a failed commit adds near

package/dist/components/dialog/dialog.d.mts

@@ -22,8 +22,19 @@ export type DialogContentProps = StyledProps<Dialog.Popup.Props> & {
   overlay?: false | DialogOverlayProps;
   size?: "sm" | "md" | "lg" | "wide";
   layer?: 0 | 1;
+  /**
+   * Where the card sits in the window. `"center"` (the default): in the
+   * middle. `"top"`: centred across, its top edge at `var(--dialog-top, 8vh)`,
+   * and never taller than the window less that top and 16px, so it never runs
+   * past the window's bottom; its width is still `size`'s. To anchor the card
+   * to something on the page (search under the top bar's field), measure it
+   * and set `--dialog-top` in `style`. Desktop and tablet only: below 768px
+   * every centred dialog sits in the middle and moves up only while the
+   * on-screen keyboard is open (dialog.md, "On a phone").
+   */
+  placement?: "center" | "top";
 };
-export declare function DialogContent({ className, children, portalProps, overlay, size, layer, ...props }: DialogContentProps): import("react").JSX.Element;
+export declare function DialogContent({ className, children, portalProps, overlay, size, layer, placement, ...props }: DialogContentProps): import("react").JSX.Element;
 export type DialogCloseProps = Dialog.Close.Props & Pick<ButtonProps, "variant" | "size"> & {
   className?: string;
   children?: ReactNode;

package/dist/components/dialog/dialog.mjs

@@ -6,13 +6,15 @@ import { tv } from "../../lib/tv.mjs";
 import { useThemeScopeProps } from "../../lib/theme/theme-scope.mjs";
 import { useParentOverlayKind, withOverlayLayer } from "../../lib/overlay-depth.mjs";
 import { Button } from "../button/button.mjs";
-import { DialogSheetHeadContext, DialogSheetReset, dialogSheet, useDialogSheet, useInDialogSheetHead } from "./dialog-sheet-context.mjs";
+import { DialogSheetHeadContext, DialogSheetReset, DialogSheetSurfaceContext, dialogSheet, useDialogSheet, useInDialogSheetHead } from "./dialog-sheet-context.mjs";
 import { ScrollArea } from "../scroll-area/scroll-area.mjs";
+import { useMobileViewport } from "../../lib/use-mobile-viewport.mjs";
+import { useSoftKeyboard } from "../../lib/use-soft-keyboard.mjs";
 import { TextLink } from "../text-link/text-link.mjs";
 import { PanelAction } from "../panel/panel-action.mjs";
 import { Dialog } from "@base-ui/react/dialog";
 import { ArrowLeft, X } from "lucide-react";
-import { Children, createContext, isValidElement, useContext, useEffect } from "react";
+import { Children, createContext, isValidElement, useContext, useEffect, useState } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { mergeProps } from "@base-ui/react/merge-props";
 import { useRender } from "@base-ui/react/use-render";
@@ -59,12 +61,20 @@ const dialog = tv({
 			lg: { content: ["max-w-160"] },
 			wide: { content: ["max-w-4xl h-[min(760px,calc(100dvh-2rem))]"] }
 		},
+		placement: {
+			center: {},
+			top: { content: ["md:top-(--dialog-top,8vh) md:translate-y-0", "md:max-h-[calc(100dvh-var(--dialog-top,8vh)-16px)]"] }
+		},
+		keyboard: {
+			false: {},
+			true: { content: ["data-soft-keyboard:top-[calc(var(--dialog-visible-top)+env(safe-area-inset-top,0px)+var(--header-height))] data-soft-keyboard:translate-y-0", "data-soft-keyboard:max-h-[calc(var(--dialog-visible-height)-env(safe-area-inset-top,0px)-var(--header-height)-16px)]"] }
+		},
 		bar: {
 			false: {},
 			true: {
-				header: ["flex h-(--header-height) shrink-0 items-center gap-2 border-b px-(--surface-inset) py-0", "border-line-seam pt-0 [&>[data-slot=dialog-close]]:my-0"],
-				body: ["flex min-h-0 flex-1 overflow-hidden p-0", "px-0 pt-0 pb-0 first:pt-0 text-foreground"],
-				footer: ["shrink-0 border-t px-(--surface-inset) py-3", "border-line-seam pt-3 pb-3 first:pt-3 [[data-slot=dialog-header]+&]:pt-3"]
+				header: ["flex h-(--header-height) shrink-0 items-center gap-2 border-b px-(--surface-inset) py-0", "border-line-seam pt-0 *:data-[slot=dialog-close]:my-0"],
+				body: ["flex min-h-0 flex-1 overflow-hidden p-0", "p-0   first:pt-0 text-foreground"],
+				footer: ["shrink-0 border-t px-(--surface-inset) py-3", "border-line-seam py-3  first:pt-3 [[data-slot=dialog-header]+&]:pt-3"]
 			}
 		},
 		layer: {
@@ -125,10 +135,16 @@ function DialogOverlay({ className, layer, ...props }) {
 	});
 }
 const DialogSizeContext = createContext(void 0);
-function DialogContent({ className, children, portalProps, overlay, size, layer, ...props }) {
+function DialogContent({ className, children, portalProps, overlay, size, layer, placement, ...props }) {
+	const top = placement === "top";
+	const sheetSurface = useContext(DialogSheetSurfaceContext);
+	const [keyboard, setKeyboard] = useState(null);
+	const raised = !sheetSurface && keyboard != null;
 	const { content } = dialog({
 		size,
-		layer
+		layer,
+		placement,
+		keyboard: raised || void 0
 	});
 	const overlayProps = typeof overlay === "object" ? overlay : {};
 	return /* @__PURE__ */ jsxs(DialogPortal, {
@@ -136,17 +152,41 @@ function DialogContent({ className, children, portalProps, overlay, size, layer,
 		children: [overlay === false ? null : /* @__PURE__ */ jsx(DialogOverlay, {
 			layer,
 			...overlayProps
-		}), /* @__PURE__ */ jsx(Dialog.Popup, {
+		}), /* @__PURE__ */ jsxs(Dialog.Popup, {
 			"data-slot": "dialog-content",
+			"data-placement": top ? "top" : void 0,
+			"data-soft-keyboard": raised ? "" : void 0,
 			className: content({ className }),
 			...props,
-			children: /* @__PURE__ */ jsx(DialogSizeContext.Provider, {
+			...raised ? { style: withVisibleArea(props.style, keyboard) } : null,
+			children: [sheetSurface ? null : /* @__PURE__ */ jsx(SoftKeyboardWatch, { onChange: setKeyboard }), /* @__PURE__ */ jsx(DialogSizeContext.Provider, {
 				value: size ?? (/(^|\s)max-w-/.test(className ?? "") ? void 0 : "md"),
 				children: /* @__PURE__ */ jsx(DialogSheetReset, { children })
-			})
+			})]
 		})]
 	});
 }
+/**
+* Reports the on-screen keyboard on a phone to a centred dialog, which moves
+* up while it is open (dialog.md, "On a phone"). Rendered inside the popup,
+* so it listens only while the dialog is open, and only below 768px.
+*/
+function SoftKeyboardWatch({ onChange }) {
+	const keyboard = useSoftKeyboard(useMobileViewport());
+	useEffect(() => {
+		onChange(keyboard);
+	}, [keyboard, onChange]);
+	useEffect(() => () => onChange(null), [onChange]);
+	return null;
+}
+/** The popup's style with the area the keyboard leaves visible, for its CSS. */
+function withVisibleArea(style, keyboard) {
+	return {
+		...style,
+		"--dialog-visible-top": `${keyboard.top}px`,
+		"--dialog-visible-height": `${keyboard.height}px`
+	};
+}
 function DialogClose({ className, variant, size, children, render, "aria-label": ariaLabel, ...props }) {
 	const inSheetHead = useInDialogSheetHead();
 	if (render) return /* @__PURE__ */ jsx(Dialog.Close, {