@botiverse/raft-ui 0.59.2 → 0.60.1

package/CHANGELOG.md

@@ -1,3 +1,50 @@
+## [0.60.1](https://github.com/botiverse/raft-design/compare/v0.60.0...v0.60.1) (2026-11-04)
+
+### Fixed
+
+- **DropdownMenuShortcut** and **ContextMenuShortcut**: a menu shortcut draws no cap line. ([#976](https://github.com/botiverse/raft-design/pull/976))
+  - Why: Kbd draws its border with an inset ring, and the menu shortcuts reset `ring`, which left a 1px inset box around every menu shortcut, light and dark.
+  - Affects: only the two menu shortcut parts; Kbd, KbdShortcut, tooltips and the search trigger keep their caps.
+  - Docs: https://raft-design.botiverse.build/components/kbd/
+
+## [0.60.0](https://github.com/botiverse/raft-design/compare/v0.59.2...v0.60.0) (2026-11-03)
+
+### Breaking Changes
+
+- **ScrollArea**: rebuilt on native scrolling. ScrollArea is now one element, the container that scrolls, with thin overlay scrollbars drawn over it the same way on every platform; wheel, trackpad, touch and keyboard scrolling stay the browser's own, the thumb can be dragged, and a press on the rail pages. ([#952](https://github.com/botiverse/raft-design/pull/952), [#971](https://github.com/botiverse/raft-design/pull/971))
+  - Why: the Base UI parts split one scroller across a root, a viewport and scrollbar elements, so a list that owned its own scroller (a virtual list, a textarea) could not have the same scrollbar; the scrollbars are now a layer any scroller can bind.
+  - Affects: `ref`, `className`, `style`, `onScroll`, `render` and the native props go on the element that scrolls. Options: `orientation`, `trigger` (`hover` / `scroll` / `none`), `size`, `fade`, `overscroll`, `railInset`, `hideDelay`, `onEdgeChange`, `actionsRef` (`scrollToElement`, `measure`), `contentRef`, `contentClassName` / `contentStyle`. Thumb thickness, colour, minimum length and the gap to the edge are `--r-scroll-area-*` variables. The styles ship in `styles.css`.
+  - Migrate: remove `ScrollAreaViewport`, `ScrollAreaScrollbar`, `ScrollAreaThumb`, `ScrollAreaCorner` and their props types; put what you passed to the viewport on `ScrollArea` itself. A container laid out as a grid, a flex row or a flex column with `gap` puts that layout on a wrapper (`contentClassName`), or binds the container with `useScrollAreaContainer({ guttersPosition: "absolute" })`.
+  - Docs: https://raft-design.botiverse.build/components/scroll-area/
+- **ComposerInput**: the textarea gets ScrollArea's overlay scrollbar and is wrapped in a frame that holds it; it no longer takes `render`. ([#952](https://github.com/botiverse/raft-design/pull/952))
+  - Why: past its maximum height the composer showed the platform's own scrollbar, unlike every other scroller.
+  - Affects: `ref`, `className` and the native props still go to the `textarea`; `wrapperClassName` styles the frame; `trigger`, `size`, `hideDelay` and `overscroll` work as on ScrollArea.
+  - Migrate: drop `render`; a style meant for the box around the textarea moves to `wrapperClassName`.
+  - Docs: https://raft-design.botiverse.build/components/composer/
+
+### Added
+
+- **useScrollAreaContainer** and **ScrollAreaGutters** (+ types `ScrollAreaContainer`, `ScrollAreaContainerOptions`, `ScrollAreaGuttersProps` and the option types): ScrollArea's scrollbars for an element you render yourself, such as a list's own scroller. The hook returns `containerProps` to spread on your element, `guttersProps` for `<ScrollAreaGutters>`, `frameProps` with absolute gutters, and `measure` / `scrollToElement` / `scrollable`. **ScrollAreaTextarea**: a `textarea` with the same scrollbar. ([#952](https://github.com/botiverse/raft-design/pull/952))
+  - Why: a virtual list or a textarea scrolls an element it renders itself, which a wrapping component can't replace.
+  - Affects: sticky gutters (the default) are a zero-height first child of the container; absolute gutters lie over a frame you render around it.
+  - Docs: https://raft-design.botiverse.build/components/scroll-area/
+- **Kbd**: a `size` prop, `sm` (the default, unchanged) or `md`, a 24px cap on a muted fill for a key that is the content, as in a list of shortcuts (+ type `KbdSize`). ([#969](https://github.com/botiverse/raft-design/pull/969))
+  - Why: a shortcuts list drew its keys at the hint size, too small to read as the content of the row.
+  - Affects: `md` is 24px high, at least 24px wide, `rounded-sticker`, `bg-fill-muted`, `text-mono-code`. Menu and search-trigger shortcuts keep `sm` (their props omit `size`).
+  - Docs: https://raft-design.botiverse.build/components/kbd/
+
+### Changed
+
+- **MessageList**, **SidebarContent**, **MarkdownTableScroll** and the composer's attachment row: built on the new ScrollArea, so they show the same thin overlay scrollbar. `MarkdownTableScroll` takes ScrollArea's props except `orientation`. ([#952](https://github.com/botiverse/raft-design/pull/952))
+  - Why: each had its own scroller and scrollbar, so the same list looked different from one place to the next.
+  - Docs: https://raft-design.botiverse.build/components/scroll-area/
+
+### Fixed
+
+- **Tooltip**: a shortcut written as a `KbdGroup` sits 6px after the text like a single `Kbd`, and its caps are no longer taken for the tooltip's leading icon. ([#969](https://github.com/botiverse/raft-design/pull/969))
+  - Why: a multi-key shortcut in a tooltip was spaced differently from a single key.
+  - Docs: https://raft-design.botiverse.build/components/tooltip/
+
 ## [0.59.2](https://github.com/botiverse/raft-design/compare/v0.59.1...v0.59.2) (2026-11-03)
 
 ### Fixed

package/dist/components/composer/composer-attachment.recipe.mjs

@@ -14,9 +14,8 @@ const composerAttachment = tv({
 			"has-[[data-slot=sortable-composer-attachments-list]]:pt-0"
 		],
 		attachmentsScrollArea: ["relative w-full min-w-0"],
-		attachmentsViewport: [
-			"flex flex-nowrap gap-2 overflow-x-auto overflow-y-hidden overscroll-x-contain py-1.5",
-			"scrollbar-none [&::-webkit-scrollbar]:hidden",
+		attachmentsRow: [
+			"flex flex-nowrap gap-2 py-1.5",
 			"**:data-[slot=composer-attachment]:shrink-0",
 			"pe-1.5"
 		],

package/dist/components/composer/composer-attachments-scroll-area.d.mts

@@ -1,5 +1,11 @@
 import { ComponentPropsWithoutRef } from "react";
 //#region src/components/composer/composer-attachments-scroll-area.d.ts
 export type ComposerAttachmentsScrollAreaProps = ComponentPropsWithoutRef<"div">;
+/**
+ * One scrolling row of attachments: a horizontal ScrollArea (its thin
+ * scrollbar shows only while the row scrolls), with an arrow on each side
+ * that has more attachments past it. The ScrollArea reports the edges, so
+ * the arrows follow scrolling, resizing and attachments coming and going.
+ */
 export declare function ComposerAttachmentsScrollArea({ children, className, onMouseEnter, onMouseLeave, ...props }: ComposerAttachmentsScrollAreaProps): import("react").JSX.Element;
 //#endregion

package/dist/components/composer/composer-attachments-scroll-area.mjs

@@ -1,7 +1,8 @@
 import { Button } from "../button/button.mjs";
+import { ScrollArea } from "../scroll-area/scroll-area.mjs";
 import { composerAttachment } from "./composer-attachment.recipe.mjs";
 import { ChevronLeft, ChevronRight } from "lucide-react";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/composer/composer-attachments-scroll-area.tsx
 function scrollByPage(viewport, direction) {
@@ -15,40 +16,22 @@ function scrollByPage(viewport, direction) {
 		behavior: prefersReducedMotion ? "auto" : "smooth"
 	});
 }
+/**
+* One scrolling row of attachments: a horizontal ScrollArea (its thin
+* scrollbar shows only while the row scrolls), with an arrow on each side
+* that has more attachments past it. The ScrollArea reports the edges, so
+* the arrows follow scrolling, resizing and attachments coming and going.
+*/
 function ComposerAttachmentsScrollArea({ children, className, onMouseEnter, onMouseLeave, ...props }) {
-	const { attachmentsScrollArea, attachmentsViewport } = composerAttachment();
+	const { attachmentsScrollArea, attachmentsRow } = composerAttachment();
 	const prevNavClassName = composerAttachment({ side: "prev" }).attachmentsNav();
 	const nextNavClassName = composerAttachment({ side: "next" }).attachmentsNav();
 	const viewportRef = useRef(null);
 	const [canPrev, setCanPrev] = useState(false);
 	const [canNext, setCanNext] = useState(false);
-	const updateScrollState = () => {
-		const viewport = viewportRef.current;
-		if (!viewport) return;
-		const maxScrollLeft = viewport.scrollWidth - viewport.clientWidth;
-		setCanPrev(viewport.scrollLeft > 1);
-		setCanNext(maxScrollLeft - viewport.scrollLeft > 1);
-	};
-	useEffect(() => {
-		const viewport = viewportRef.current;
-		if (!viewport) return;
-		updateScrollState();
-		const resizeObserver = new ResizeObserver(updateScrollState);
-		resizeObserver.observe(viewport);
-		for (const child of viewport.children) resizeObserver.observe(child);
-		const mutationObserver = new MutationObserver(() => {
-			for (const child of viewport.children) resizeObserver.observe(child);
-			updateScrollState();
-		});
-		mutationObserver.observe(viewport, { childList: true });
-		viewport.addEventListener("scroll", updateScrollState, { passive: true });
-		window.addEventListener("resize", updateScrollState);
-		return () => {
-			resizeObserver.disconnect();
-			mutationObserver.disconnect();
-			viewport.removeEventListener("scroll", updateScrollState);
-			window.removeEventListener("resize", updateScrollState);
-		};
+	const handleEdgeChange = useCallback((edges) => {
+		setCanPrev(!edges.left);
+		setCanNext(!edges.right);
 	}, []);
 	const handleScrollPrev = useCallback(() => scrollByPage(viewportRef.current, -1), []);
 	const handleScrollNext = useCallback(() => scrollByPage(viewportRef.current, 1), []);
@@ -71,10 +54,16 @@ function ComposerAttachmentsScrollArea({ children, className, onMouseEnter, onMo
 				onClick: handleScrollPrev,
 				children: /* @__PURE__ */ jsx(ChevronLeft, {})
 			}) : null,
-			/* @__PURE__ */ jsx("div", {
+			/* @__PURE__ */ jsx(ScrollArea, {
 				ref: viewportRef,
 				"data-slot": "composer-attachments-viewport",
-				className: attachmentsViewport(),
+				orientation: "horizontal",
+				trigger: "scroll",
+				size: "small",
+				overscroll: "contain",
+				tabIndex: -1,
+				contentClassName: attachmentsRow(),
+				onEdgeChange: handleEdgeChange,
 				children
 			}),
 			showNext ? /* @__PURE__ */ jsx(Button, {

package/dist/components/composer/composer.d.mts

@@ -1,10 +1,16 @@
 import { ButtonProps } from "../button/button.mjs";
+import { ScrollAreaTextareaProps } from "../scroll-area/types.mjs";
 import { useRender } from "@base-ui/react/use-render";
 //#region src/components/composer/composer.d.ts
 export type ComposerProps = useRender.ComponentProps<"div">;
 export declare function Composer({ className, render, ...props }: ComposerProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
-export type ComposerInputProps = useRender.ComponentProps<"textarea">;
-export declare function ComposerInput({ className, render, ...props }: ComposerInputProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+/**
+ * A native `<textarea>` with ScrollArea's overlay scrollbar (`ScrollAreaTextarea`): `ref`,
+ * `className` and the native props go to the textarea; `wrapperClassName` to the element that holds
+ * it and the scrollbar; `trigger`, `size`, `hideDelay` and `overscroll` as on ScrollArea.
+ */
+export type ComposerInputProps = ScrollAreaTextareaProps;
+export declare function ComposerInput({ className, wrapperClassName, ...props }: ComposerInputProps): import("react").JSX.Element;
 export type ComposerToolbarProps = useRender.ComponentProps<"div">;
 export declare function ComposerToolbar({ className, render, ...props }: ComposerToolbarProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
 export type ComposerActionsProps = useRender.ComponentProps<"div">;

package/dist/components/composer/composer.mjs

@@ -1,4 +1,5 @@
 import { Button } from "../button/button.mjs";
+import { ScrollAreaTextarea } from "../scroll-area/scroll-area-textarea.mjs";
 import { composer } from "./composer.recipe.mjs";
 import { jsx } from "react/jsx-runtime";
 import { mergeProps } from "@base-ui/react/merge-props";
@@ -16,17 +17,14 @@ function Composer({ className, render, ...props }) {
 		props: mergeProps(defaultProps, props)
 	});
 }
-function ComposerInput({ className, render, ...props }) {
-	const { input } = composer();
-	const defaultProps = {
+function ComposerInput({ className, wrapperClassName, ...props }) {
+	const { input, inputFrame } = composer();
+	return /* @__PURE__ */ jsx(ScrollAreaTextarea, {
 		rows: 1,
 		"data-slot": "composer-input",
-		className: input({ className })
-	};
-	return useRender({
-		defaultTagName: "textarea",
-		render,
-		props: mergeProps(defaultProps, props)
+		...props,
+		className: input({ className }),
+		wrapperClassName: inputFrame({ className: wrapperClassName })
 	});
 }
 function ComposerToolbar({ className, render, ...props }) {

package/dist/components/composer/composer.recipe.mjs

@@ -7,6 +7,7 @@ const composer = tv({ slots: {
 		"border-line-field bg-layer-card text-foreground shadow-none",
 		"has-focus-visible:shadow-focus"
 	],
+	inputFrame: ["w-full min-w-0", "[--r-scroll-area-resize-grip-size:0px]"],
 	input: [
 		"max-h-32 w-full resize-none bg-transparent outline-none",
 		"field-sizing-content overflow-y-auto",

package/dist/components/context-menu/context-menu.d.mts

@@ -35,7 +35,7 @@ export type ContextMenuSubmenuTriggerProps = StyledProps<ContextMenu.SubmenuTrig
 export declare function ContextMenuSubmenuTrigger({ children, className, ...props }: ContextMenuSubmenuTriggerProps): import("react").JSX.Element;
 export type ContextMenuLabelProps = StyledProps<ComponentPropsWithRef<"div">>;
 export declare function ContextMenuLabel({ className, ...props }: ContextMenuLabelProps): import("react").JSX.Element;
-export type ContextMenuShortcutProps = KbdProps;
+export type ContextMenuShortcutProps = Omit<KbdProps, "size">;
 export declare function ContextMenuShortcut({ className, ...props }: ContextMenuShortcutProps): import("react").JSX.Element;
 export type ContextMenuSeparatorProps = StyledProps<ContextMenu.Separator.Props>;
 export declare function ContextMenuSeparator({ className, ...props }: ContextMenuSeparatorProps): import("react").JSX.Element;

package/dist/components/context-menu/context-menu.mjs

@@ -51,7 +51,7 @@ const contextMenu = tv({ slots: {
 	label: ["px-2.5 pt-2 pb-1", "font-sans text-caption font-bold text-foreground-hint"],
 	shortcut: [
 		"ml-auto",
-		"h-auto min-w-0 rounded-none bg-transparent p-0 shadow-none ring-0",
+		"h-auto min-w-0 rounded-none bg-transparent p-0 shadow-none inset-ring-0",
 		"font-mono text-mono-meta font-normal text-foreground-hint"
 	],
 	separator: ["-mx-1 my-1 h-px border-0 bg-line-hairline"],

package/dist/components/dropdown-menu/dropdown-menu.d.mts

@@ -30,7 +30,7 @@ export type DropdownMenuSubmenuTriggerProps = StyledProps<Menu.SubmenuTrigger.Pr
 export declare function DropdownMenuSubmenuTrigger({ children, className, ...props }: DropdownMenuSubmenuTriggerProps): import("react").JSX.Element;
 export type DropdownMenuLabelProps = StyledProps<ComponentPropsWithRef<"div">>;
 export declare function DropdownMenuLabel({ className, ...props }: DropdownMenuLabelProps): import("react").JSX.Element;
-export type DropdownMenuShortcutProps = KbdProps;
+export type DropdownMenuShortcutProps = Omit<KbdProps, "size">;
 export declare function DropdownMenuShortcut({ className, ...props }: DropdownMenuShortcutProps): import("react").JSX.Element;
 export type DropdownMenuItemCountProps = BadgeProps;
 export declare function DropdownMenuItemCount({ className, ...props }: DropdownMenuItemCountProps): import("react").JSX.Element;

package/dist/components/dropdown-menu/dropdown-menu.mjs

@@ -22,7 +22,7 @@ const dropdownMenu = tv({ slots: {
 		"min-h-option gap-2.5 rounded-chip px-2.5 py-option-inset",
 		"font-sans text-callout font-medium text-foreground",
 		"hover:bg-brand-soft data-highlighted:bg-brand-soft",
-		"data-checked:font-bold data-[selected]:font-bold data-[emphasis=strong]:font-bold",
+		"data-checked:font-bold data-selected:font-bold data-[emphasis=strong]:font-bold",
 		"data-disabled:pointer-events-none data-disabled:text-foreground-disabled",
 		"[&_svg]:pointer-events-none [&_svg]:shrink-0 [&>svg:not([class*='size-'])]:size-4",
 		"[&>svg]:text-foreground-muted data-disabled:[&>svg]:text-foreground-disabled"
@@ -53,7 +53,7 @@ const dropdownMenu = tv({ slots: {
 	label: ["px-2.5 pt-2 pb-1", "font-sans text-caption font-bold text-foreground-hint"],
 	shortcut: [
 		"ml-auto",
-		"h-auto min-w-0 rounded-none bg-transparent p-0 shadow-none ring-0",
+		"h-auto min-w-0 rounded-none bg-transparent p-0 shadow-none inset-ring-0",
 		"font-mono text-mono-meta font-normal text-foreground-hint"
 	],
 	itemCount: ["ml-auto inline-flex min-w-5 justify-center gap-0 px-1 tabular-nums"],

package/dist/components/kbd/index.d.mts

@@ -1,2 +1,5 @@
-import { Kbd, KbdGroup, KbdGroupProps, KbdProps } from "./kbd.mjs";
-export { Kbd, KbdGroup, type KbdGroupProps, type KbdProps };
+import { Kbd, KbdGroup, KbdGroupProps, KbdProps, KbdSize } from "./kbd.mjs";
+import { KeyboardPlatform, useKeyboardPlatform } from "../../lib/use-platform.mjs";
+import { KbdKeyName } from "./kbd-keys.mjs";
+import { KbdShortcut, KbdShortcutProps } from "./kbd-shortcut.mjs";
+export { Kbd, KbdGroup, type KbdGroupProps, type KbdKeyName, type KbdProps, KbdShortcut, type KbdShortcutProps, type KbdSize, type KeyboardPlatform, useKeyboardPlatform };

package/dist/components/kbd/kbd-keys.d.mts

@@ -0,0 +1,12 @@
+//#region src/components/kbd/kbd-keys.d.ts
+/**
+ * A key, by name, case-insensitive. `mod` is Command on a Mac and Ctrl
+ * elsewhere: write it for the platform's command key. `meta` (also `cmd`,
+ * `command`) is the literal Command key on a Mac and the Windows key
+ * elsewhere; `ctrl` (also `control`) is always the Control key. `KeyboardEvent.key`
+ * values work too: `ArrowUp`, `Control`, `Meta`, `Escape`, `" "`. Any other
+ * string is a key written as it reads: an ASCII letter is drawn uppercase,
+ * `f1`…`f24` as F1…F24, anything else as written.
+ */
+export type KbdKeyName = "mod" | "meta" | "ctrl" | "alt" | "option" | "shift" | "enter" | "backspace" | "delete" | "escape" | "tab" | "space" | "up" | "down" | "left" | "right" | (string & {});
+//#endregion

package/dist/components/kbd/kbd-keys.mjs

@@ -0,0 +1,297 @@
+//#region src/components/kbd/kbd-keys.ts
+/** Every name a key goes by, lowercase, including `KeyboardEvent.key` values. */
+const ALIASES = {
+	mod: "mod",
+	meta: "meta",
+	cmd: "meta",
+	command: "meta",
+	ctrl: "ctrl",
+	control: "ctrl",
+	alt: "alt",
+	opt: "alt",
+	option: "alt",
+	shift: "shift",
+	enter: "enter",
+	return: "enter",
+	backspace: "backspace",
+	delete: "delete",
+	del: "delete",
+	escape: "escape",
+	esc: "escape",
+	tab: "tab",
+	space: "space",
+	spacebar: "space",
+	" ": "space",
+	up: "up",
+	arrowup: "up",
+	down: "down",
+	arrowdown: "down",
+	left: "left",
+	arrowleft: "left",
+	right: "right",
+	arrowright: "right"
+};
+/** The modifier a key presses on a platform, or none. */
+function modifierOf(key, platform) {
+	switch (key) {
+		case "mod": return platform === "mac" ? "command" : "control";
+		case "meta": return platform === "mac" ? "command" : "meta";
+		case "ctrl": return "control";
+		case "alt": return "option";
+		case "shift": return "shift";
+		default: return;
+	}
+}
+const MODIFIER_ORDER = {
+	mac: [
+		"control",
+		"option",
+		"shift",
+		"command"
+	],
+	other: [
+		"control",
+		"option",
+		"shift",
+		"meta"
+	]
+};
+const MODIFIERS = {
+	mac: {
+		control: {
+			icon: "chevron-up",
+			label: "Control"
+		},
+		option: {
+			icon: "option",
+			label: "Option"
+		},
+		shift: {
+			icon: "arrow-big-up",
+			label: "Shift"
+		},
+		command: {
+			icon: "command",
+			label: "Command"
+		},
+		meta: {
+			icon: "command",
+			label: "Command"
+		}
+	},
+	other: {
+		control: {
+			text: "Ctrl",
+			label: "Control"
+		},
+		option: {
+			text: "Alt",
+			label: "Alt"
+		},
+		shift: {
+			text: "Shift",
+			label: "Shift"
+		},
+		command: {
+			text: "Ctrl",
+			label: "Control"
+		},
+		meta: {
+			text: "Win",
+			label: "Windows"
+		}
+	}
+};
+const ARROWS = {
+	up: {
+		icon: "arrow-up",
+		label: "Up Arrow"
+	},
+	down: {
+		icon: "arrow-down",
+		label: "Down Arrow"
+	},
+	left: {
+		icon: "arrow-left",
+		label: "Left Arrow"
+	},
+	right: {
+		icon: "arrow-right",
+		label: "Right Arrow"
+	}
+};
+const NAMED = {
+	mac: {
+		...ARROWS,
+		enter: {
+			icon: "corner-down-left",
+			label: "Return"
+		},
+		backspace: {
+			icon: "delete",
+			label: "Delete"
+		},
+		delete: {
+			text: "Del",
+			label: "Forward Delete"
+		},
+		escape: {
+			text: "Esc",
+			label: "Escape"
+		},
+		tab: {
+			text: "Tab",
+			label: "Tab"
+		},
+		space: {
+			text: "Space",
+			label: "Space"
+		}
+	},
+	other: {
+		...ARROWS,
+		enter: {
+			text: "Enter",
+			label: "Enter"
+		},
+		backspace: {
+			text: "Backspace",
+			label: "Backspace"
+		},
+		delete: {
+			text: "Del",
+			label: "Delete"
+		},
+		escape: {
+			text: "Esc",
+			label: "Escape"
+		},
+		tab: {
+			text: "Tab",
+			label: "Tab"
+		},
+		space: {
+			text: "Space",
+			label: "Space"
+		}
+	}
+};
+/** What a screen reader is told for a punctuation key, which it may skip. */
+const CHARACTER_LABELS = {
+	"/": "Slash",
+	"\\": "Backslash",
+	".": "Period",
+	",": "Comma",
+	";": "Semicolon",
+	":": "Colon",
+	"'": "Quote",
+	"\"": "Double Quote",
+	"`": "Backtick",
+	"-": "Minus",
+	_: "Underscore",
+	"=": "Equals",
+	"+": "Plus",
+	"[": "Left Bracket",
+	"]": "Right Bracket",
+	"{": "Left Brace",
+	"}": "Right Brace",
+	"(": "Left Parenthesis",
+	")": "Right Parenthesis",
+	"?": "Question Mark",
+	"!": "Exclamation Mark",
+	"@": "At",
+	"#": "Number Sign",
+	$: "Dollar",
+	"%": "Percent",
+	"^": "Caret",
+	"&": "Ampersand",
+	"*": "Asterisk",
+	"<": "Less Than",
+	">": "Greater Than",
+	"~": "Tilde",
+	"|": "Vertical Bar"
+};
+/** One written key as a named key, or as a literal key drawn as it reads. */
+function parse(name) {
+	if (name === "") return void 0;
+	const alias = ALIASES[name.toLowerCase()];
+	if (alias) return {
+		kind: "canonical",
+		key: alias,
+		name
+	};
+	if (/^.$/u.test(name)) {
+		const text = /^[a-z]$/.test(name) ? name.toUpperCase() : name;
+		return {
+			kind: "literal",
+			text,
+			label: CHARACTER_LABELS[name] ?? text,
+			name
+		};
+	}
+	if (/^f\d{1,2}$/i.test(name)) {
+		const text = name.toUpperCase();
+		return {
+			kind: "literal",
+			text,
+			label: text,
+			name
+		};
+	}
+	return {
+		kind: "literal",
+		text: name,
+		label: name,
+		name
+	};
+}
+const warned = /* @__PURE__ */ new Set();
+function warnOnce(message) {
+	if (process.env.NODE_ENV === "production" || warned.has(message)) return;
+	warned.add(message);
+	console.warn(message);
+}
+/**
+* The keys of a shortcut as a platform draws them: the modifiers first, in
+* the platform's order whatever order they were written in (each once), then
+* the other keys in the order written. An empty name is skipped. In
+* development, an empty name and two names that press the same key on this
+* platform (`mod` and `ctrl` on Windows and Linux) log a warning.
+*/
+function resolveKbdKeys(keys, platform) {
+	const order = MODIFIER_ORDER[platform];
+	const modifiers = /* @__PURE__ */ new Map();
+	const rest = [];
+	for (const written of keys) {
+		const parsed = parse(written);
+		if (!parsed) {
+			warnOnce(`KbdShortcut: an empty key name in ${JSON.stringify(keys)} is skipped.`);
+			continue;
+		}
+		if (parsed.kind === "literal") {
+			rest.push({
+				name: parsed.name,
+				text: parsed.text,
+				label: parsed.label
+			});
+			continue;
+		}
+		const modifier = modifierOf(parsed.key, platform);
+		if (!modifier) {
+			rest.push({
+				name: parsed.name,
+				...NAMED[platform][parsed.key]
+			});
+			continue;
+		}
+		const earlier = modifiers.get(modifier);
+		if (earlier === void 0) modifiers.set(modifier, written);
+		else warnOnce(`KbdShortcut: "${earlier}" and "${written}" are the same key on ${platform === "mac" ? "a Mac" : "Windows and Linux"}, so ${JSON.stringify(keys)} draws it once.`);
+	}
+	return [...[...modifiers.entries()].sort(([a], [b]) => order.indexOf(a) - order.indexOf(b)).map(([modifier, name]) => ({
+		name,
+		...MODIFIERS[platform][modifier]
+	})), ...rest];
+}
+//#endregion
+export { resolveKbdKeys };

package/dist/components/kbd/kbd-shortcut.d.mts

@@ -0,0 +1,34 @@
+import { KbdSize } from "./kbd.mjs";
+import { KeyboardPlatform } from "../../lib/use-platform.mjs";
+import { KbdKeyName } from "./kbd-keys.mjs";
+import { ComponentPropsWithRef } from "react";
+//#region src/components/kbd/kbd-shortcut.d.ts
+export type KbdShortcutProps = Omit<ComponentPropsWithRef<"span">, "children"> & {
+  /**
+   * The keys, by name, case-insensitive, in any order: `["mod", "shift",
+   * "enter"]`. `KeyboardEvent.key` values work too (`ArrowUp`, `Meta`).
+   * Modifiers are drawn first, in the platform's order; the other keys
+   * follow in the order written.
+   */
+  keys: readonly KbdKeyName[];
+  /** The size of every cap, as `Kbd`'s. */
+  size?: KbdSize;
+  /**
+   * The keyboard to draw for. Without it, the platform the page runs on,
+   * detected once on the client (`other` on the server and while hydrating).
+   */
+  platform?: KeyboardPlatform;
+  /**
+   * What a screen reader says instead of the key names, which are English:
+   * pass the product's own words for another language ("Shift Command 回车").
+   */
+  label?: string;
+};
+/**
+ * One shortcut from key names: a cap per key, with the platform's drawings
+ * (icons on a Mac, words elsewhere), and the shortcut in words for a screen
+ * reader. Alternatives ("⌘↑ / ⌘↓") are two KbdShortcut with a separator
+ * between them, written by the caller.
+ */
+export declare function KbdShortcut({ keys, size, platform: platformProp, label, className, ...props }: KbdShortcutProps): import("react").JSX.Element;
+//#endregion