@botiverse/raft-ui 0.10.5 → 0.10.6

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [0.10.6](https://github.com/botiverse/raft-design/compare/v0.10.5...v0.10.6) (2026-10-21)
+
+### Added
+
+- Comments beside a document, as in Google Docs, through `@botiverse/raft-ui/wip`: `CommentMargin`, `CommentCard` (with `CommentCardTrigger`, `CommentCardMeta`, `CommentCardQuote`), `CommentEntry` and `CommentMarker`. Cards sit level with their passages and keep the document's order; on a narrow viewer a `CommentMarker` beside each passage opens the discussion in a bottom sheet instead. `useCommentMarginFits(viewer, { minWidth })` picks between the two, `setCommentHighlights` with `COMMENT_HIGHLIGHT` / `COMMENT_HIGHLIGHT_ACTIVE` highlights the passages, and `resolveCommentMarginLayout` is the layout for callers that place cards themselves. New pattern: Comments. ([#614](https://github.com/botiverse/raft-design/pull/614))
+- `AvatarGroup` reads `--avatar-group-surface` (default `layer-canvas`) for the ring between overlapping avatars, so a stack on another surface can match it. ([#614](https://github.com/botiverse/raft-design/pull/614))
+
 ## [0.10.5](https://github.com/botiverse/raft-design/compare/v0.10.4...v0.10.5) (2026-10-20)
 
 ### Added

package/dist/index.mjs

@@ -5701,8 +5701,8 @@ const avatar = tv({
 		group: [
 			"group/avatar-group flex items-center",
 			"stack-x-[-5px]",
-			"*:data-[slot=avatar]:shadow-[0_0_0_1.5px_var(--sticker-edge),0_0_0_3px_var(--layer-canvas)]",
-			"*:data-[slot=avatar-group-count]:shadow-[0_0_0_1.5px_var(--sticker-edge),0_0_0_3px_var(--layer-canvas)]"
+			"*:data-[slot=avatar]:shadow-[0_0_0_1.5px_var(--sticker-edge),0_0_0_3px_var(--avatar-group-surface,var(--layer-canvas))]",
+			"*:data-[slot=avatar-group-count]:shadow-[0_0_0_1.5px_var(--sticker-edge),0_0_0_3px_var(--avatar-group-surface,var(--layer-canvas))]"
 		]
 	},
 	variants: {

package/dist/styles.css

@@ -442,6 +442,26 @@ body {
   position: relative;
 }
 
+/* The passages comments are on, painted with the CSS Custom Highlight API so
+   the document's DOM is never changed (setCommentHighlights registers the
+   ranges; design/patterns/comments.md). Every commented passage gets the soft
+   yellow of a highlight and a 2px yellow underline; the passage of the open
+   discussion gets the full yellow with ink type, like a search hit, in both
+   modes. `--brand-400` is the `brand` role (what `bg-brand` paints):
+   `--color-brand` is an inline theme value and emits no variable. */
+::highlight(raft-comment) {
+  background-color: var(--brand-soft);
+  text-decoration-line: underline;
+  text-decoration-color: var(--brand-400);
+  text-decoration-thickness: 2px;
+}
+
+::highlight(raft-comment-active) {
+  background-color: var(--brand-400);
+  color: var(--sticker-ink);
+  text-decoration-line: none;
+}
+
 @utility image-transparency-bg {
   --checker-cell: light-dark(oklch(0.1813 0.00497 17.62 / 0.12), oklch(1 0 0 / 0.1));
   background-color: light-dark(oklch(1 0 0), oklch(0.23 0 0));

package/dist/wip.d.mts

@@ -1,5 +1,7 @@
-import { O as ButtonProps, T as DialogTrigger, i as DialogClose, s as DialogContentProps, t as Dialog, w as DialogTitleProps } from "./index-CDHLWJtB.mjs";
+import { M as StyledProps, O as ButtonProps, T as DialogTrigger, i as DialogClose, j as DataAttributes, s as DialogContentProps, t as Dialog, w as DialogTitleProps } from "./index-CDHLWJtB.mjs";
 import { CSSProperties, ComponentPropsWithRef, ReactNode } from "react";
+import { Button } from "@base-ui/react/button";
+import { useRender } from "@base-ui/react/use-render";
 import { Combobox } from "@base-ui/react/combobox";
 //#region src/components/combobox-select/combobox-select.types.d.ts
 type ComboboxSelectValue = string | number;
@@ -110,4 +112,170 @@ export declare function AnnouncementDialogFooter({ className, ...props }: Compon
 export declare function AnnouncementDialogAction({ className, ...props }: Omit<ButtonProps, "variant">): import("react").JSX.Element;
 export declare function AnnouncementDialogSecondaryAction({ className, ...props }: Omit<ButtonProps, "variant">): import("react").JSX.Element;
 //#endregion
-export { Dialog as AnnouncementDialog, DialogClose as AnnouncementDialogClose, DialogTrigger as AnnouncementDialogTrigger, type ComboboxSelectGroup, type ComboboxSelectMessages, type ComboboxSelectOption, type ComboboxSelectProps, type ComboboxSelectSelection, type ComboboxSelectValue };
+//#region src/components/comment/comment-card.d.ts
+type CommentCardProps = useRender.ComponentProps<"div"> & {
+  /** The discussion people are reading or replying to: an ink border, lifted. */
+  active?: boolean;
+};
+/**
+ * The card of one discussion: its comments, a line such as "2 replies", and
+ * the reply box when it is open. A `div`; which parts it holds (collapsed or
+ * open) is the caller's choice. To open it with a click, add
+ * `CommentCardTrigger`.
+ */
+export declare function CommentCard({ className, render, active, ...props }: CommentCardProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+type CommentCardTriggerProps = useRender.ComponentProps<"button">;
+/**
+ * A button laid over the whole card, for a collapsed card that opens when it
+ * is clicked or chosen with the keyboard. It has no text of its own: give it
+ * an `aria-label` ("Comment from Martin").
+ */
+export declare function CommentCardTrigger({ className, render, ...props }: CommentCardTriggerProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+type CommentCardMetaProps = useRender.ComponentProps<"div">;
+/**
+ * A short line about the discussion, in the caller's words: how many replies
+ * it has, that it is about the whole document, or that the passage it was on
+ * can no longer be found.
+ */
+export declare function CommentCardMeta({ className, render, ...props }: CommentCardMetaProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+type CommentCardQuoteProps = useRender.ComponentProps<"span">;
+/**
+ * The passage the discussion is about, in the caller's words (usually the
+ * quoted text). Hidden on screen, where the card's place beside the
+ * highlighted passage says it; give it an `id` and point the
+ * `aria-describedby` of `CommentCardTrigger` or `CommentMarker` at it, so a
+ * screen reader says which passage a card is about.
+ */
+export declare function CommentCardQuote({ className, render, ...props }: CommentCardQuoteProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+//#endregion
+//#region src/components/comment/comment-entry.d.ts
+type CommentEntryProps = useRender.ComponentProps<"div">;
+/** One comment in a discussion: its header, then its text. */
+export declare function CommentEntry({ className, render, ...props }: CommentEntryProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+type CommentEntryHeaderProps = useRender.ComponentProps<"div">;
+/** One line: the author's `Avatar` (`size="xs"`), `CommentEntryAuthor`, then `CommentEntryTime`. */
+export declare function CommentEntryHeader({ className, render, ...props }: CommentEntryHeaderProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+type CommentEntryAuthorProps = useRender.ComponentProps<"span">;
+/** Who wrote the comment, in bold. It truncates; the time after it doesn't. */
+export declare function CommentEntryAuthor({ className, render, ...props }: CommentEntryAuthorProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+type CommentEntryTimeProps = useRender.ComponentProps<"time">;
+/**
+ * When the comment was written, right after the author. A `<time>`: pass the
+ * moment in `dateTime` (ISO 8601).
+ */
+export declare function CommentEntryTime({ className, render, ...props }: CommentEntryTimeProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+type CommentEntryBodyProps = useRender.ComponentProps<"div"> & {
+  /** Cuts the text to 2 lines, for a collapsed card. */
+  clamp?: boolean;
+};
+/** What the comment says. */
+export declare function CommentEntryBody({ className, render, clamp, ...props }: CommentEntryBodyProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+//#endregion
+//#region src/components/comment/comment-highlight.d.ts
+/** The highlight of every passage that has comments (`::highlight(raft-comment)` in styles.css). */
+export declare const COMMENT_HIGHLIGHT = "raft-comment";
+/** The highlight of the passage of the open discussion (`::highlight(raft-comment-active)`). */
+export declare const COMMENT_HIGHLIGHT_ACTIVE = "raft-comment-active";
+/**
+ * Highlights the passages comments are on with the CSS Custom Highlight API,
+ * so the document's DOM is never changed: no `<mark>` is wrapped around its
+ * text. Register the ranges of every anchored comment under
+ * `COMMENT_HIGHLIGHT`, and the open discussion's under
+ * `COMMENT_HIGHLIGHT_ACTIVE`, which paints over it. Passing no ranges clears
+ * the name. Returns a function that clears it.
+ *
+ * Where the browser has no `CSS.highlights`, it does nothing: the passages are
+ * not highlighted, and the cards still say where they belong.
+ */
+export declare function setCommentHighlights(name: string, ranges: Iterable<Range>): () => void;
+//#endregion
+//#region src/components/comment/comment-margin.d.ts
+type CommentMarginProps = useRender.ComponentProps<"div"> & {
+  /** Space between two cards that would otherwise touch, in px. Default 8. */
+  gap?: number;
+};
+/**
+ * The column beside a document that holds its comment cards, each level with
+ * the passage it is about. It measures its `CommentMarginItem`s with one
+ * `ResizeObserver`, resolves their collisions with
+ * `resolveCommentMarginLayout`, and takes the height the lowest card needs.
+ * Place it beside the document so that its top is the top the items' `top`
+ * is measured from.
+ */
+export declare function CommentMargin({ className, render, style, gap, ...props }: CommentMarginProps): import("react").JSX.Element;
+type CommentMarginItemProps = useRender.ComponentProps<"div"> & {
+  /** Where the card's anchor is: its y, in px, from the top of the margin. */
+  top: number;
+  /** Pins this card to its anchor and moves the others around it. */
+  active?: boolean;
+};
+/**
+ * One card's place in a `CommentMargin`. It sits at `top`, or lower when the
+ * card above it is in the way; the active one stays at `top` and the others
+ * make room. Items with the same `top` keep the order they were first
+ * rendered in. The resolved top is `data-top`, applied as a `translateY`.
+ */
+export declare function CommentMarginItem({ className, render, style, top, active, ...props }: CommentMarginItemProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+//#endregion
+//#region src/components/comment/comment-margin-layout.d.ts
+/** One card in the margin: where its anchor is and how tall the card is, in px. */
+type CommentMarginLayoutItem = {
+  id: string;
+  /** The y of the card's anchor, measured from the top of the margin. */
+  top: number;
+  /** The card's rendered height. */
+  height: number;
+};
+type CommentMarginLayoutOptions = {
+  /** Space between two cards that would otherwise touch, in px. Default 8. */
+  gap?: number;
+  /** The card pinned to its anchor; the others make room around it. */
+  activeId?: string | null;
+};
+type CommentMarginLayout = {
+  /** The resolved top of each card, by id. */
+  tops: Record<string, number>;
+  /** The bottom of the lowest card: the height the margin needs. */
+  height: number;
+};
+/**
+ * Places the cards of a comment margin the way Google Docs does. Cards keep
+ * document order (by their anchor's top; equal tops keep the order given) and
+ * never overlap: each sits at its anchor, or `gap` below the card before it.
+ * The active card is pinned to its anchor instead, the cards above it are
+ * pushed up to make room and the cards below it pushed down. Nothing goes
+ * above 0: when the cards above the active one don't fit between 0 and its
+ * anchor, they stack from 0 and the active card follows them.
+ */
+export declare function resolveCommentMarginLayout(items: readonly CommentMarginLayoutItem[], { gap, activeId }?: CommentMarginLayoutOptions): CommentMarginLayout;
+//#endregion
+//#region src/components/comment/comment-marker.d.ts
+type CommentMarkerProps = StyledProps<Button.Props> & DataAttributes & {
+  /** The marker of the discussion that is open. */
+  active?: boolean;
+};
+/**
+ * Where there is no room for a margin: a small button beside a passage that
+ * has comments, with the authors' avatars (an `AvatarGroup` of up to 3
+ * `size="2xs"` avatars) and the count. It opens the discussion, in a bottom
+ * sheet. Give it an `aria-label` that starts with the count ("2 comments").
+ */
+export declare function CommentMarker({ className, render, nativeButton, active, ...props }: CommentMarkerProps): import("react").JSX.Element;
+//#endregion
+//#region src/components/comment/use-comment-margin-fits.d.ts
+type UseCommentMarginFitsOptions = {
+  /** The narrowest the viewer may be for the margin to show, in px. Default 784. */
+  minWidth?: number;
+};
+/**
+ * Whether a viewer has room for a comment margin beside its document: true
+ * only on a desktop (from 768px with a mouse or a trackpad, the query the
+ * desktop metrics use) and while `element`, the viewer that holds the
+ * document and the margin, is at least `minWidth` wide. Otherwise show
+ * `CommentMarker`s and open discussions in a bottom sheet. Cards and markers
+ * are different trees, so this is measured in JavaScript (a
+ * `ResizeObserver` on the element), not decided by a container query.
+ */
+export declare function useCommentMarginFits(element: Element | null, { minWidth }?: UseCommentMarginFitsOptions): boolean;
+//#endregion
+export { Dialog as AnnouncementDialog, DialogClose as AnnouncementDialogClose, DialogTrigger as AnnouncementDialogTrigger, type ComboboxSelectGroup, type ComboboxSelectMessages, type ComboboxSelectOption, type ComboboxSelectProps, type ComboboxSelectSelection, type ComboboxSelectValue, type CommentCardMetaProps, type CommentCardProps, type CommentCardQuoteProps, type CommentCardTriggerProps, type CommentEntryAuthorProps, type CommentEntryBodyProps, type CommentEntryHeaderProps, type CommentEntryProps, type CommentEntryTimeProps, type CommentMarginItemProps, type CommentMarginLayout, type CommentMarginLayoutItem, type CommentMarginLayoutOptions, type CommentMarginProps, type CommentMarkerProps, type UseCommentMarginFitsOptions };

package/dist/wip.mjs

@@ -1,7 +1,10 @@
-import { D as DialogTitle, I as useThemeScopeProps, L as useTheme, O as DialogTrigger, a as DrawerContent, c as DrawerHeader, d as DrawerTitle, f as DrawerTrigger, g as Dialog, i as DrawerClose, k as Button, n as DrawerActions, r as DrawerBody, s as DrawerFooter, t as Drawer, v as DialogClose, y as DialogContent, z as tv } from "./drawer-yZD16Ybl.mjs";
+import { D as DialogTitle, I as useThemeScopeProps, L as useTheme, M as defaultNativeButton, O as DialogTrigger, a as DrawerContent, c as DrawerHeader, d as DrawerTitle, f as DrawerTrigger, g as Dialog, i as DrawerClose, k as Button$1, n as DrawerActions, r as DrawerBody, s as DrawerFooter, t as Drawer, v as DialogClose, y as DialogContent, z as tv } from "./drawer-yZD16Ybl.mjs";
 import { Check, ChevronDown, LoaderCircle, Plus, Search, X } from "lucide-react";
-import { useCallback, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { createContext, use, useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { Button } from "@base-ui/react/button";
+import { mergeProps } from "@base-ui/react/merge-props";
+import { useRender } from "@base-ui/react/use-render";
 import { Combobox } from "@base-ui/react/combobox";
 import { Select } from "@base-ui/react/select";
 //#region src/lib/phone-media.ts
@@ -741,7 +744,7 @@ function ComboboxSelect({ options, multiple, value, defaultValue, onValueChange,
 								})]
 							}),
 							multiple ? /* @__PURE__ */ jsx(DrawerFooter, { children: /* @__PURE__ */ jsx(DrawerActions, { children: /* @__PURE__ */ jsx(DrawerClose, {
-								render: /* @__PURE__ */ jsx(Button, { size: "lg" }),
+								render: /* @__PURE__ */ jsx(Button$1, { size: "lg" }),
 								children: strings.done
 							}) }) }) : null
 						]
@@ -900,7 +903,7 @@ function AnnouncementDialogFooter({ className, ...props }) {
 }
 function AnnouncementDialogAction({ className, ...props }) {
 	const { action } = announcement();
-	return /* @__PURE__ */ jsx(Button, {
+	return /* @__PURE__ */ jsx(Button$1, {
 		variant: "accent",
 		"data-announcement-action": true,
 		className: action({ className }),
@@ -909,11 +912,502 @@ function AnnouncementDialogAction({ className, ...props }) {
 }
 function AnnouncementDialogSecondaryAction({ className, ...props }) {
 	const { secondary } = announcement();
-	return /* @__PURE__ */ jsx(Button, {
+	return /* @__PURE__ */ jsx(Button$1, {
 		variant: "ghost",
 		className: secondary({ className }),
 		...props
 	});
 }
 //#endregion
-export { Dialog as AnnouncementDialog, AnnouncementDialogAction, AnnouncementDialogBody, DialogClose as AnnouncementDialogClose, AnnouncementDialogContent, AnnouncementDialogFooter, AnnouncementDialogHeader, AnnouncementDialogLabel, AnnouncementDialogPicture, AnnouncementDialogSecondaryAction, AnnouncementDialogText, AnnouncementDialogTitle, DialogTrigger as AnnouncementDialogTrigger, ComboboxSelect };
+//#region src/components/comment/comment.recipe.ts
+const comment = tv({
+	slots: {
+		margin: ["relative min-w-0"],
+		marginItem: [
+			"absolute inset-x-0 top-0",
+			"data-animate:transition-transform data-animate:duration-150 data-animate:ease-out",
+			"motion-reduce:transition-none",
+			"data-active:z-10"
+		],
+		card: [
+			"relative flex min-w-0 flex-col gap-2",
+			"rounded-container border border-line-hairline p-3",
+			"bg-layer-card text-foreground shadow-none outline-none",
+			"data-active:border-[1.5px] data-active:border-line-strong data-active:p-[11.5px] data-active:shadow-float"
+		],
+		cardTrigger: [
+			"absolute -inset-px z-10 cursor-pointer",
+			"rounded-container border-0 bg-transparent p-0",
+			"hover:bg-fill-pressed active:bg-fill-pressed",
+			"outline-none focus-visible:shadow-focus"
+		],
+		cardQuote: ["sr-only"],
+		cardMeta: [
+			"flex min-w-0 items-center gap-1",
+			"font-sans text-caption text-foreground-hint",
+			"[&_svg]:size-3.5 [&_svg]:shrink-0"
+		],
+		entry: ["flex min-w-0 flex-col gap-1", "[[data-slot=comment-entry]+&]:mt-1"],
+		entryHeader: ["flex min-w-0 items-center gap-1.5", "*:data-[slot=avatar]:me-0.5"],
+		entryAuthor: ["min-w-0 truncate", "text-subhead font-bold text-foreground"],
+		entryTime: ["shrink-0 whitespace-nowrap", "font-mono text-mono-meta tabular-nums text-foreground-hint"],
+		entryBody: [
+			"wrap-break-word select-text",
+			"text-callout text-foreground",
+			"selection:bg-brand-soft"
+		],
+		marker: [
+			"relative inline-flex h-6 shrink-0 items-center gap-1 align-top whitespace-nowrap",
+			"rounded-chip border border-line-hairline py-0 ps-[3px] pe-1.5",
+			"font-mono text-mono-meta font-bold tabular-nums text-foreground",
+			"bg-layer-card [--avatar-group-surface:var(--layer-card)]",
+			"cursor-pointer hover:press-overlay active:press-overlay",
+			"data-active:border-[1.5px] data-active:border-line-strong data-active:bg-brand-soft data-active:ps-[2.5px] data-active:pe-[5.5px]",
+			"data-popup-open:border-[1.5px] data-popup-open:border-line-strong data-popup-open:bg-brand-soft data-popup-open:ps-[2.5px] data-popup-open:pe-[5.5px]",
+			"data-active:[--avatar-group-surface:var(--brand-soft)] data-popup-open:[--avatar-group-surface:var(--brand-soft)]",
+			"outline-none focus-visible:shadow-focus",
+			"after:absolute after:-inset-x-1 after:-inset-y-2.5"
+		]
+	},
+	variants: { clamp: { true: { entryBody: ["line-clamp-2"] } } }
+});
+//#endregion
+//#region src/components/comment/comment-card.tsx
+/**
+* The card of one discussion: its comments, a line such as "2 replies", and
+* the reply box when it is open. A `div`; which parts it holds (collapsed or
+* open) is the caller's choice. To open it with a click, add
+* `CommentCardTrigger`.
+*/
+function CommentCard({ className, render, active = false, ...props }) {
+	const { card } = comment();
+	const defaultProps = {
+		"data-slot": "comment-card",
+		"data-active": active ? "" : void 0,
+		"aria-current": active ? "true" : void 0,
+		className: card({ className })
+	};
+	return useRender({
+		defaultTagName: "div",
+		render,
+		props: mergeProps(defaultProps, props)
+	});
+}
+/**
+* A button laid over the whole card, for a collapsed card that opens when it
+* is clicked or chosen with the keyboard. It has no text of its own: give it
+* an `aria-label` ("Comment from Martin").
+*/
+function CommentCardTrigger({ className, render, ...props }) {
+	const { cardTrigger } = comment();
+	const defaultProps = {
+		"data-slot": "comment-card-trigger",
+		type: "button",
+		className: cardTrigger({ className })
+	};
+	return useRender({
+		defaultTagName: "button",
+		render,
+		props: mergeProps(defaultProps, props)
+	});
+}
+/**
+* A short line about the discussion, in the caller's words: how many replies
+* it has, that it is about the whole document, or that the passage it was on
+* can no longer be found.
+*/
+function CommentCardMeta({ className, render, ...props }) {
+	const { cardMeta } = comment();
+	const defaultProps = {
+		"data-slot": "comment-card-meta",
+		className: cardMeta({ className })
+	};
+	return useRender({
+		defaultTagName: "div",
+		render,
+		props: mergeProps(defaultProps, props)
+	});
+}
+/**
+* The passage the discussion is about, in the caller's words (usually the
+* quoted text). Hidden on screen, where the card's place beside the
+* highlighted passage says it; give it an `id` and point the
+* `aria-describedby` of `CommentCardTrigger` or `CommentMarker` at it, so a
+* screen reader says which passage a card is about.
+*/
+function CommentCardQuote({ className, render, ...props }) {
+	const { cardQuote } = comment();
+	const defaultProps = {
+		"data-slot": "comment-card-quote",
+		className: cardQuote({ className })
+	};
+	return useRender({
+		defaultTagName: "span",
+		render,
+		props: mergeProps(defaultProps, props)
+	});
+}
+//#endregion
+//#region src/components/comment/comment-entry.tsx
+/** One comment in a discussion: its header, then its text. */
+function CommentEntry({ className, render, ...props }) {
+	const { entry } = comment();
+	const defaultProps = {
+		"data-slot": "comment-entry",
+		className: entry({ className })
+	};
+	return useRender({
+		defaultTagName: "div",
+		render,
+		props: mergeProps(defaultProps, props)
+	});
+}
+/** One line: the author's `Avatar` (`size="xs"`), `CommentEntryAuthor`, then `CommentEntryTime`. */
+function CommentEntryHeader({ className, render, ...props }) {
+	const { entryHeader } = comment();
+	const defaultProps = {
+		"data-slot": "comment-entry-header",
+		className: entryHeader({ className })
+	};
+	return useRender({
+		defaultTagName: "div",
+		render,
+		props: mergeProps(defaultProps, props)
+	});
+}
+/** Who wrote the comment, in bold. It truncates; the time after it doesn't. */
+function CommentEntryAuthor({ className, render, ...props }) {
+	const { entryAuthor } = comment();
+	const defaultProps = {
+		"data-slot": "comment-entry-author",
+		className: entryAuthor({ className })
+	};
+	return useRender({
+		defaultTagName: "span",
+		render,
+		props: mergeProps(defaultProps, props)
+	});
+}
+/**
+* When the comment was written, right after the author. A `<time>`: pass the
+* moment in `dateTime` (ISO 8601).
+*/
+function CommentEntryTime({ className, render, ...props }) {
+	const { entryTime } = comment();
+	const defaultProps = {
+		"data-slot": "comment-entry-time",
+		className: entryTime({ className })
+	};
+	return useRender({
+		defaultTagName: "time",
+		render,
+		props: mergeProps(defaultProps, props)
+	});
+}
+/** What the comment says. */
+function CommentEntryBody({ className, render, clamp = false, ...props }) {
+	const { entryBody } = comment({ clamp });
+	const defaultProps = {
+		"data-slot": "comment-entry-body",
+		"data-clamp": clamp ? "" : void 0,
+		className: entryBody({ className })
+	};
+	return useRender({
+		defaultTagName: "div",
+		render,
+		props: mergeProps(defaultProps, props)
+	});
+}
+//#endregion
+//#region src/components/comment/comment-highlight.ts
+/** The highlight of every passage that has comments (`::highlight(raft-comment)` in styles.css). */
+const COMMENT_HIGHLIGHT = "raft-comment";
+/** The highlight of the passage of the open discussion (`::highlight(raft-comment-active)`). */
+const COMMENT_HIGHLIGHT_ACTIVE = "raft-comment-active";
+/**
+* Highlights the passages comments are on with the CSS Custom Highlight API,
+* so the document's DOM is never changed: no `<mark>` is wrapped around its
+* text. Register the ranges of every anchored comment under
+* `COMMENT_HIGHLIGHT`, and the open discussion's under
+* `COMMENT_HIGHLIGHT_ACTIVE`, which paints over it. Passing no ranges clears
+* the name. Returns a function that clears it.
+*
+* Where the browser has no `CSS.highlights`, it does nothing: the passages are
+* not highlighted, and the cards still say where they belong.
+*/
+function setCommentHighlights(name, ranges) {
+	const registry = typeof CSS === "undefined" ? void 0 : CSS.highlights;
+	if (!registry || typeof Highlight === "undefined") return () => {};
+	const list = [...ranges];
+	if (list.length === 0) {
+		registry.delete(name);
+		return () => {};
+	}
+	const highlight = new Highlight(...list);
+	if (name === "raft-comment-active") highlight.priority = 1;
+	registry.set(name, highlight);
+	return () => {
+		if (registry.get(name) === highlight) registry.delete(name);
+	};
+}
+//#endregion
+//#region src/components/comment/comment-margin-layout.ts
+/**
+* Places the cards of a comment margin the way Google Docs does. Cards keep
+* document order (by their anchor's top; equal tops keep the order given) and
+* never overlap: each sits at its anchor, or `gap` below the card before it.
+* The active card is pinned to its anchor instead, the cards above it are
+* pushed up to make room and the cards below it pushed down. Nothing goes
+* above 0: when the cards above the active one don't fit between 0 and its
+* anchor, they stack from 0 and the active card follows them.
+*/
+function resolveCommentMarginLayout(items, { gap = 8, activeId = null } = {}) {
+	const order = items.map((item, index) => ({
+		item,
+		index
+	})).sort((a, b) => a.item.top - b.item.top || a.index - b.index).map(({ item }) => item);
+	const tops = order.map((item) => item.top);
+	const stackDown = (from, floor) => {
+		let next = floor;
+		for (let i = from; i < order.length; i += 1) {
+			tops[i] = Math.max(order[i].top, next);
+			next = tops[i] + order[i].height + gap;
+		}
+	};
+	const pinned = activeId == null ? -1 : order.findIndex((item) => item.id === activeId);
+	if (pinned < 0) stackDown(0, 0);
+	else {
+		tops[pinned] = Math.max(order[pinned].top, 0);
+		for (let i = pinned - 1; i >= 0; i -= 1) tops[i] = Math.min(order[i].top, tops[i + 1] - gap - order[i].height);
+		if (pinned > 0 && tops[0] < 0) stackDown(0, 0);
+		else stackDown(pinned + 1, tops[pinned] + order[pinned].height + gap);
+	}
+	const result = {};
+	let height = 0;
+	order.forEach((item, i) => {
+		result[item.id] = tops[i];
+		height = Math.max(height, tops[i] + item.height);
+	});
+	return {
+		tops: result,
+		height
+	};
+}
+//#endregion
+//#region src/components/comment/comment-margin.tsx
+const CommentMarginContext = createContext(null);
+function useCommentMargin() {
+	const context = use(CommentMarginContext);
+	if (!context) throw new Error("CommentMarginItem must be used within CommentMargin.");
+	return context;
+}
+const heightOf = (element) => element.getBoundingClientRect().height;
+/**
+* The column beside a document that holds its comment cards, each level with
+* the passage it is about. It measures its `CommentMarginItem`s with one
+* `ResizeObserver`, resolves their collisions with
+* `resolveCommentMarginLayout`, and takes the height the lowest card needs.
+* Place it beside the document so that its top is the top the items' `top`
+* is measured from.
+*/
+function CommentMargin({ className, render, style, gap = 8, ...props }) {
+	const { margin } = comment();
+	const [entries, setEntries] = useState(() => /* @__PURE__ */ new Map());
+	const [animate, setAnimate] = useState(false);
+	const observer = useRef(null);
+	const observed = useRef(/* @__PURE__ */ new Map());
+	const patch = useCallback((id, next) => {
+		setEntries((current) => {
+			const previous = current.get(id);
+			if (next === null) {
+				if (!previous) return current;
+				const without = new Map(current);
+				without.delete(id);
+				return without;
+			}
+			if (!previous && next.top === void 0) return current;
+			const merged = {
+				top: 0,
+				height: 0,
+				active: false,
+				...previous,
+				...next
+			};
+			if (previous && previous.top === merged.top && previous.height === merged.height && previous.active === merged.active) return current;
+			const updated = new Map(current);
+			updated.set(id, merged);
+			return updated;
+		});
+	}, []);
+	const place = useCallback((id, placement) => patch(id, placement), [patch]);
+	const observe = useCallback((id, element) => {
+		observer.current ??= new ResizeObserver((records) => {
+			for (const record of records) {
+				const target = observed.current.get(record.target);
+				if (target) patch(target, { height: heightOf(record.target) });
+			}
+		});
+		observed.current.set(element, id);
+		patch(id, { height: heightOf(element) });
+		observer.current.observe(element);
+		return () => {
+			observer.current?.unobserve(element);
+			observed.current.delete(element);
+		};
+	}, [patch]);
+	useEffect(() => () => observer.current?.disconnect(), []);
+	const layout = useMemo(() => {
+		const items = [...entries].map(([id, { top, height }]) => ({
+			id,
+			top,
+			height
+		}));
+		const activeId = [...entries].find(([, entry]) => entry.active)?.[0];
+		return resolveCommentMarginLayout(items, {
+			gap,
+			activeId
+		});
+	}, [entries, gap]);
+	const measured = entries.size > 0;
+	useEffect(() => {
+		if (!measured) return;
+		const frame = requestAnimationFrame(() => setAnimate(true));
+		return () => cancelAnimationFrame(frame);
+	}, [measured]);
+	const context = useMemo(() => ({
+		tops: layout.tops,
+		animate,
+		place,
+		observe
+	}), [
+		layout.tops,
+		animate,
+		place,
+		observe
+	]);
+	const defaultProps = {
+		"data-slot": "comment-margin",
+		className: margin({ className }),
+		style: {
+			minHeight: layout.height,
+			...style
+		}
+	};
+	const element = useRender({
+		defaultTagName: "div",
+		render,
+		props: mergeProps(defaultProps, props)
+	});
+	return /* @__PURE__ */ jsx(CommentMarginContext, {
+		value: context,
+		children: element
+	});
+}
+/**
+* One card's place in a `CommentMargin`. It sits at `top`, or lower when the
+* card above it is in the way; the active one stays at `top` and the others
+* make room. Items with the same `top` keep the order they were first
+* rendered in. The resolved top is `data-top`, applied as a `translateY`.
+*/
+function CommentMarginItem({ className, render, style, top, active = false, ...props }) {
+	const { marginItem } = comment();
+	const { tops, animate, place, observe } = useCommentMargin();
+	const id = useId();
+	const [element, setElement] = useState(null);
+	useLayoutEffect(() => {
+		place(id, {
+			top,
+			active
+		});
+	}, [
+		place,
+		id,
+		top,
+		active
+	]);
+	useLayoutEffect(() => element ? observe(id, element) : void 0, [
+		observe,
+		id,
+		element
+	]);
+	useLayoutEffect(() => () => place(id, null), [place, id]);
+	const resolved = tops[id] ?? Math.max(top, 0);
+	const defaultProps = {
+		"data-slot": "comment-margin-item",
+		"data-top": String(resolved),
+		"data-active": active ? "" : void 0,
+		"data-animate": animate ? "" : void 0,
+		className: marginItem({ className }),
+		style: {
+			...style,
+			transform: `translateY(${resolved}px)`
+		}
+	};
+	return useRender({
+		defaultTagName: "div",
+		render,
+		ref: setElement,
+		props: mergeProps(defaultProps, props)
+	});
+}
+//#endregion
+//#region src/components/comment/comment-marker.tsx
+/**
+* Where there is no room for a margin: a small button beside a passage that
+* has comments, with the authors' avatars (an `AvatarGroup` of up to 3
+* `size="2xs"` avatars) and the count. It opens the discussion, in a bottom
+* sheet. Give it an `aria-label` that starts with the count ("2 comments").
+*/
+function CommentMarker({ className, render, nativeButton, active = false, ...props }) {
+	const { marker } = comment();
+	return /* @__PURE__ */ jsx(Button, {
+		...props,
+		render,
+		nativeButton: nativeButton ?? defaultNativeButton(render),
+		"data-slot": "comment-marker",
+		"data-active": active ? "" : void 0,
+		className: marker({ className })
+	});
+}
+//#endregion
+//#region src/lib/desktop-media.ts
+/**
+* Where the desktop layout and its metrics begin: from 768px, with a mouse or
+* a trackpad (design/foundations/spacing.md#hit-targets). The same query as
+* the desktop blocks in styles.css and foundation.css, for code that has to
+* decide in JavaScript what CSS decides with `md:pointer-fine:`.
+*/
+const DESKTOP_MEDIA_QUERY = "(width >= 48rem) and (pointer: fine)";
+//#endregion
+//#region src/components/comment/use-comment-margin-fits.ts
+function subscribeDesktop(onChange) {
+	if (typeof window === "undefined") return () => void 0;
+	const media = window.matchMedia(DESKTOP_MEDIA_QUERY);
+	media.addEventListener("change", onChange);
+	return () => media.removeEventListener("change", onChange);
+}
+const getDesktop = () => typeof window !== "undefined" && window.matchMedia("(width >= 48rem) and (pointer: fine)").matches;
+/**
+* Whether a viewer has room for a comment margin beside its document: true
+* only on a desktop (from 768px with a mouse or a trackpad, the query the
+* desktop metrics use) and while `element`, the viewer that holds the
+* document and the margin, is at least `minWidth` wide. Otherwise show
+* `CommentMarker`s and open discussions in a bottom sheet. Cards and markers
+* are different trees, so this is measured in JavaScript (a
+* `ResizeObserver` on the element), not decided by a container query.
+*/
+function useCommentMarginFits(element, { minWidth = 784 } = {}) {
+	const desktop = useSyncExternalStore(subscribeDesktop, getDesktop, () => false);
+	const [width, setWidth] = useState(0);
+	useLayoutEffect(() => {
+		if (!element) return;
+		const measure = () => setWidth(element.getBoundingClientRect().width);
+		measure();
+		const observer = new ResizeObserver(measure);
+		observer.observe(element);
+		return () => observer.disconnect();
+	}, [element]);
+	return desktop && element !== null && width >= minWidth;
+}
+//#endregion
+export { Dialog as AnnouncementDialog, AnnouncementDialogAction, AnnouncementDialogBody, DialogClose as AnnouncementDialogClose, AnnouncementDialogContent, AnnouncementDialogFooter, AnnouncementDialogHeader, AnnouncementDialogLabel, AnnouncementDialogPicture, AnnouncementDialogSecondaryAction, AnnouncementDialogText, AnnouncementDialogTitle, DialogTrigger as AnnouncementDialogTrigger, COMMENT_HIGHLIGHT, COMMENT_HIGHLIGHT_ACTIVE, ComboboxSelect, CommentCard, CommentCardMeta, CommentCardQuote, CommentCardTrigger, CommentEntry, CommentEntryAuthor, CommentEntryBody, CommentEntryHeader, CommentEntryTime, CommentMargin, CommentMarginItem, CommentMarker, resolveCommentMarginLayout, setCommentHighlights, useCommentMarginFits };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botiverse/raft-ui",
-  "version": "0.10.5",
+  "version": "0.10.6",
   "description": "React components and CSS foundations for the Raft Design System.",
   "keywords": [
     "agent-skills",