@botiverse/raft-ui 0.30.0 → 0.31.0

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+## [0.31.0](https://github.com/botiverse/raft-design/compare/v0.30.0...v0.31.0) (2026-10-23)
+
+### Design System
+
+- **A row swipe on a phone**: a swipe starts once the finger has gone 10px on the web (twice as far across as up or down), and swipes that start within 24px of the screen edge stay with the browser. A release applies the action past 40% of the row's width, or past 20% with a quick flick. The uncovered layer is soft until a release would apply, then solid `success` with ink, and ticks once on Android as it turns solid. It says "Done"; the menu keeps "Mark as Done". The row leaves at once, with an 8-second Undo. On a phone, Activity's Mark as Done stays in the row as a button only screen readers see. ([#775](https://github.com/botiverse/raft-design/pull/775), [#776](https://github.com/botiverse/raft-design/pull/776))
+  - Why: Activity on a phone moved Mark as Done to the swipe (stdrc); the swipe must be predictable, reversible, and reachable without swiping.
+  - Affects: a rule for products.
+  - Docs: https://raft-design.botiverse.build/patterns/responsive/#touch-screens
+
+### Added
+
+- **ChoiceList** (wip): ([#774](https://github.com/botiverse/raft-design/pull/774))
+  - `groups` with headings. Each group is named by its heading, and the arrow keys cross groups.
+  - `searchValue` / `onSearchValueChange`, so the app can read and set the search text. It hears `""` when the box hides.
+  - `footer`, which stays in view while the rows scroll.
+  - `fill`, which fills its container's height.
+  - The frame now wraps a `choice-list-scroller`.
+  - Docs: https://raft-design.botiverse.build/components/choice-list/
+
 ## [0.30.0](https://github.com/botiverse/raft-design/compare/v0.29.0...v0.30.0) (2026-10-23)
 
 ### Design System

package/dist/wip.d.mts

@@ -727,6 +727,13 @@ type ChoiceListItem = {
    */
   action?: ReactNode;
   disabled?: boolean;
+  /** The `value` of the group in `groups` this item is listed under. */
+  group?: string;
+};
+type ChoiceListGroup = {
+  value: string;
+  /** The small heading over the group's rows, such as "Agents". */
+  label: ReactNode;
 };
 type ChoiceListCommonProps = {
   items: readonly ChoiceListItem[];
@@ -748,12 +755,37 @@ type ChoiceListCommonProps = {
   searchPlaceholder?: string;
   /** The search box's text when the list first draws, such as a search carried over. */
   defaultSearchValue?: string;
+  /**
+   * The search box's text, for a caller that uses it: a "Create “…”" row
+   * named after it, or a no-match line that quotes it. With it, the caller
+   * owns the text, and `onSearchValueChange` reports each change.
+   */
+  searchValue?: string;
+  onSearchValueChange?: (value: string) => void;
   /** The clear button's accessible name. */
   clearSearchLabel: string;
   /** The line under the chosen rows when nothing else matches. */
   noMatchLabel?: ReactNode;
   /** The line drawn when there are no items at all. */
   empty?: ReactNode;
+  /**
+   * Headings that split the rows by kind, in this order, such as Agents then
+   * People. Each item names its group; a group with no rows to show, or a
+   * search that leaves it empty, draws no heading.
+   */
+  groups?: readonly ChoiceListGroup[];
+  /**
+   * A row of the caller's under the list, inside its frame, that stays in
+   * view while the rows scroll: the way out when the item isn't there, such
+   * as "Create an agent".
+   */
+  footer?: ReactNode;
+  /**
+   * The list takes the height it is given and its rows scroll inside it, for
+   * a sheet or panel whose main content is the list. Otherwise a list with a
+   * search scrolls past 18rem.
+   */
+  fill?: boolean;
   className?: string;
 };
 type ChoiceListSingleProps = ChoiceListCommonProps & {
@@ -769,4 +801,4 @@ type ChoiceListMultipleProps = ChoiceListCommonProps & {
 type ChoiceListProps = ChoiceListSingleProps | ChoiceListMultipleProps;
 export declare function ChoiceList(props: ChoiceListProps): import("react").JSX.Element;
 //#endregion
-export { Dialog as AnnouncementDialog, DialogClose as AnnouncementDialogClose, DialogTrigger as AnnouncementDialogTrigger, type ChoiceListItem, type ChoiceListMultipleProps, type ChoiceListProps, type ChoiceListSingleProps, 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, DialogCommit, type DialogCommitProps, DialogFooterNote, type DialogFooterNoteProps, DialogSheetBack, type DialogSheetBackProps, DialogSheetContent, type DialogSheetContentProps, DropdownMenuLinkItem, type DropdownMenuLinkItemProps, type EllipsisProps, type EllipsisState, type EllipsisToggleProps, type HoldThenMoveOptions, type InboxItemLeadingBadgeProps, type InboxItemSkeletonListProps, type InboxItemSkeletonProps, type ListRowSkeletonProps, MessageItemDelegatedAvatar, type MessageItemDelegatedAvatarProps, MessageItemDelegatedBy, MessageItemDelegatedByButton, type MessageItemDelegatedByButtonProps, MessageItemDelegatedByName, type MessageItemDelegatedByNameProps, type MessageItemDelegatedByProps, MessageListJumpControls, type MessageListJumpControlsProps, MessageListJumpPill, MessageListJumpPillDismiss, type MessageListJumpPillDismissProps, MessageListJumpPillGroup, type MessageListJumpPillGroupProps, type MessageListJumpPillProps, MessageQuotedPreviewAuthorDelegatedBy, type MessageQuotedPreviewAuthorDelegatedByProps, MessageReferenceIcon, type MessageReferenceIconProps, MessageReferenceReadMark, type MessageReferenceReadMarkProps, type MeterHeaderProps, type MeterIndicatorProps, type MeterLabelProps, type MeterProps, type MeterTrackProps, type MeterValueProps, MobileNavServerItem, type MobileNavServerItemProps, MobileNavServerPopover, MobileNavServerPopoverContent, type MobileNavServerPopoverContentProps, MobileNavServerPopoverDestination, type MobileNavServerPopoverDestinationProps, MobileNavServerPopoverDestinations, type MobileNavServerPopoverDestinationsProps, MobileNavServerPopoverGroup, type MobileNavServerPopoverGroupProps, MobileNavServerPopoverList, type MobileNavServerPopoverListProps, type MobileNavServerPopoverProps, MobileNavServerPopoverRow, MobileNavServerPopoverRowBody, type MobileNavServerPopoverRowBodyProps, MobileNavServerPopoverRowDescription, type MobileNavServerPopoverRowDescriptionProps, MobileNavServerPopoverRowLabel, type MobileNavServerPopoverRowLabelProps, type MobileNavServerPopoverRowProps, type OverlayLayerKind, type OverlayLayerProviderProps, PopoverActions, type PopoverActionsProps, PopoverBody, type PopoverBodyProps, PreviewCardActions, type PreviewCardActionsProps, PreviewCardBody, type PreviewCardBodyProps, PreviewCardEyebrow, type PreviewCardEyebrowProps, PreviewCardFooter, type PreviewCardFooterProps, PreviewCardMeta, type PreviewCardMetaProps, type PullToRefresh, type PullToRefreshIndicatorProps, type PullToRefreshPlatform, type PullToRefreshState, type UseCommentMarginFitsOptions, type UsePullToRefreshOptions };
+export { Dialog as AnnouncementDialog, DialogClose as AnnouncementDialogClose, DialogTrigger as AnnouncementDialogTrigger, type ChoiceListGroup, type ChoiceListItem, type ChoiceListMultipleProps, type ChoiceListProps, type ChoiceListSingleProps, 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, DialogCommit, type DialogCommitProps, DialogFooterNote, type DialogFooterNoteProps, DialogSheetBack, type DialogSheetBackProps, DialogSheetContent, type DialogSheetContentProps, DropdownMenuLinkItem, type DropdownMenuLinkItemProps, type EllipsisProps, type EllipsisState, type EllipsisToggleProps, type HoldThenMoveOptions, type InboxItemLeadingBadgeProps, type InboxItemSkeletonListProps, type InboxItemSkeletonProps, type ListRowSkeletonProps, MessageItemDelegatedAvatar, type MessageItemDelegatedAvatarProps, MessageItemDelegatedBy, MessageItemDelegatedByButton, type MessageItemDelegatedByButtonProps, MessageItemDelegatedByName, type MessageItemDelegatedByNameProps, type MessageItemDelegatedByProps, MessageListJumpControls, type MessageListJumpControlsProps, MessageListJumpPill, MessageListJumpPillDismiss, type MessageListJumpPillDismissProps, MessageListJumpPillGroup, type MessageListJumpPillGroupProps, type MessageListJumpPillProps, MessageQuotedPreviewAuthorDelegatedBy, type MessageQuotedPreviewAuthorDelegatedByProps, MessageReferenceIcon, type MessageReferenceIconProps, MessageReferenceReadMark, type MessageReferenceReadMarkProps, type MeterHeaderProps, type MeterIndicatorProps, type MeterLabelProps, type MeterProps, type MeterTrackProps, type MeterValueProps, MobileNavServerItem, type MobileNavServerItemProps, MobileNavServerPopover, MobileNavServerPopoverContent, type MobileNavServerPopoverContentProps, MobileNavServerPopoverDestination, type MobileNavServerPopoverDestinationProps, MobileNavServerPopoverDestinations, type MobileNavServerPopoverDestinationsProps, MobileNavServerPopoverGroup, type MobileNavServerPopoverGroupProps, MobileNavServerPopoverList, type MobileNavServerPopoverListProps, type MobileNavServerPopoverProps, MobileNavServerPopoverRow, MobileNavServerPopoverRowBody, type MobileNavServerPopoverRowBodyProps, MobileNavServerPopoverRowDescription, type MobileNavServerPopoverRowDescriptionProps, MobileNavServerPopoverRowLabel, type MobileNavServerPopoverRowLabelProps, type MobileNavServerPopoverRowProps, type OverlayLayerKind, type OverlayLayerProviderProps, PopoverActions, type PopoverActionsProps, PopoverBody, type PopoverBodyProps, PreviewCardActions, type PreviewCardActionsProps, PreviewCardBody, type PreviewCardBodyProps, PreviewCardEyebrow, type PreviewCardEyebrowProps, PreviewCardFooter, type PreviewCardFooterProps, PreviewCardMeta, type PreviewCardMetaProps, type PullToRefresh, type PullToRefreshIndicatorProps, type PullToRefreshPlatform, type PullToRefreshState, type UseCommentMarginFitsOptions, type UsePullToRefreshOptions };

package/dist/wip.mjs

@@ -2333,9 +2333,12 @@ const choiceList = tv({
 	slots: {
 		root: ["grid min-w-0 gap-2"],
 		searchInput: ["[&::-webkit-search-cancel-button]:appearance-none"],
-		frame: ["min-w-0 rounded-container border border-line-hairline bg-layer-card p-1"],
+		frame: ["flex min-w-0 flex-col overflow-hidden", "rounded-container border border-line-hairline bg-layer-card"],
+		scroller: ["min-h-0 min-w-0 p-1"],
 		rows: ["grid grid-cols-[minmax(0,1fr)_auto] gap-x-0 gap-y-0.5"],
 		group: ["col-span-2 col-start-1 grid grid-cols-subgrid grid-rows-subgrid gap-x-0 gap-y-0.5"],
+		section: ["col-span-2 col-start-1 grid grid-cols-subgrid grid-rows-subgrid"],
+		heading: ["col-span-2 px-2.5 pt-2 pb-1", "font-sans text-caption font-bold text-foreground-hint"],
 		item: [
 			"col-span-2 flex min-w-0 items-start gap-2.5 rounded-chip px-2.5",
 			"min-h-option py-option-inset",
@@ -2353,10 +2356,16 @@ const choiceList = tv({
 			"mt-option-inset pointer-coarse:mt-[calc((--spacing(11)-1lh)/2)]",
 			"font-sans text-subhead"
 		],
-		note: ["px-2.5 py-2 font-sans text-callout text-foreground-hint"]
+		note: ["px-2.5 py-2 font-sans text-callout text-foreground-hint"],
+		footer: ["shrink-0 border-t border-line-seam p-1"]
 	},
 	variants: {
-		scroll: { true: { frame: ["max-h-72 overflow-y-auto overscroll-contain"] } },
+		scroll: { true: { scroller: ["max-h-72 overflow-y-auto overscroll-contain"] } },
+		fill: { true: {
+			root: ["flex min-h-0 flex-1 flex-col"],
+			frame: ["min-h-0 flex-1"],
+			scroller: ["flex-1 overflow-y-auto overscroll-contain"]
+		} },
 		hasAction: { true: { item: ["pr-11"] } }
 	}
 });
@@ -2405,11 +2414,42 @@ function visibleItems(items, needle, pinned, chosen) {
 		noMatch: !items.some(matches)
 	};
 }
+function layoutSections(rows, groups) {
+	const known = new Set(groups?.map((group) => group.value));
+	const sections = groups ? groups.map((group) => ({
+		group,
+		rows: rows.filter((item) => item.group === group.value)
+	})) : [];
+	sections.push({
+		group: null,
+		rows: rows.filter((item) => !groups || item.group === void 0 || !known.has(item.group))
+	});
+	const drawn = sections.filter((section) => section.rows.length > 0);
+	const gridRowOf = /* @__PURE__ */ new Map();
+	let gridRows = 0;
+	for (const section of drawn) {
+		if (section.group) gridRows += 1;
+		for (const item of section.rows) {
+			gridRows += 1;
+			gridRowOf.set(item.value, gridRows);
+		}
+	}
+	return {
+		sections: drawn,
+		gridRowOf,
+		gridRows
+	};
+}
 function ChoiceList(props) {
-	const { items, search = "auto", "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disabled = false, searchLabel, searchPlaceholder, defaultSearchValue = "", clearSearchLabel, noMatchLabel, empty, className } = props;
+	const { items, search = "auto", "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disabled = false, searchLabel, searchPlaceholder, defaultSearchValue = "", searchValue, onSearchValueChange, clearSearchLabel, noMatchLabel, empty, groups, footer, fill = false, className } = props;
 	const value = props.value;
 	const chosen = useMemo(() => value === null ? [] : typeof value === "string" ? [value] : value, [value]);
-	const [query, setQuery] = useState(defaultSearchValue);
+	const [ownQuery, setOwnQuery] = useState(defaultSearchValue);
+	const query = searchValue ?? ownQuery;
+	const setQuery = useCallback((next) => {
+		if (searchValue === void 0) setOwnQuery(next);
+		onSearchValueChange?.(next);
+	}, [searchValue, onSearchValueChange]);
 	const [pinned, setPinned] = useState(chosen);
 	const inputRef = useRef(null);
 	const baseId = useId();
@@ -2417,11 +2457,26 @@ function ChoiceList(props) {
 	const [wasSearchable, setWasSearchable] = useState(searchable);
 	if (wasSearchable !== searchable) {
 		setWasSearchable(searchable);
-		if (!searchable) setQuery("");
+		if (!searchable) setOwnQuery("");
+	}
+	useEffect(() => {
+		if (!searchable && searchValue) onSearchValueChange?.("");
+	}, [
+		searchable,
+		searchValue,
+		onSearchValueChange
+	]);
+	const [pinnedFor, setPinnedFor] = useState(query);
+	if (pinnedFor !== query) {
+		setPinnedFor(query);
+		setPinned(chosen);
 	}
 	const { rows, noMatch } = visibleItems(items, searchable ? query.trim().toLowerCase() : "", pinned, chosen);
 	const hasAction = rows.some((item) => item.action !== void 0 && item.action !== null);
-	const slots = choiceList({ scroll: searchable });
+	const slots = choiceList({
+		scroll: searchable && !fill,
+		fill
+	});
 	useEffect(() => {
 		if (process.env.NODE_ENV === "production") return;
 		if (!ariaLabel && !ariaLabelledBy) console.warn("raft-ui: a ChoiceList has neither aria-label nor aria-labelledby.");
@@ -2444,21 +2499,20 @@ function ChoiceList(props) {
 	}, [focusSearch]);
 	const changeQuery = useCallback((event) => {
 		setQuery(event.currentTarget.value);
-		setPinned(chosen);
-	}, [chosen]);
+	}, [setQuery]);
 	const clearQuery = useCallback(() => {
 		setQuery("");
-		setPinned(chosen);
 		inputRef.current?.focus();
-	}, [chosen]);
+	}, [setQuery]);
+	const { sections, gridRowOf, gridRows } = layoutSections(rows, groups);
 	const groupProps = {
 		"aria-label": ariaLabel,
 		"aria-labelledby": ariaLabelledBy,
 		disabled,
 		className: slots.group(),
-		style: { gridRow: `1 / span ${rows.length}` }
+		style: { gridRow: `1 / span ${gridRows}` }
 	};
-	const rowElements = rows.map((item) => {
+	const rowElement = (item) => {
 		const id = `${baseId}-${items.indexOf(item)}`;
 		const lines = descriptionLines(item.description).slice(0, MAX_DESCRIPTION_LINES);
 		const rowDisabled = disabled || item.disabled === true;
@@ -2499,6 +2553,24 @@ function ChoiceList(props) {
 				})
 			]
 		}, item.value);
+	};
+	const rowElements = sections.map((section, index) => {
+		if (!section.group) return section.rows.map(rowElement);
+		const headingId = `${baseId}-group-${index}`;
+		const start = (gridRowOf.get(section.rows[0].value) ?? 1) - 1;
+		return /* @__PURE__ */ jsxs("div", {
+			role: "group",
+			"aria-labelledby": headingId,
+			"data-slot": "choice-list-section",
+			className: slots.section(),
+			style: { gridRow: `${start} / span ${section.rows.length + 1}` },
+			children: [/* @__PURE__ */ jsx("div", {
+				id: headingId,
+				"data-slot": "choice-list-heading",
+				className: slots.heading(),
+				children: section.group.label
+			}), section.rows.map(rowElement)]
+		}, section.group.value);
 	});
 	return /* @__PURE__ */ jsxs("div", {
 		"data-slot": "choice-list",
@@ -2529,40 +2601,48 @@ function ChoiceList(props) {
 					})
 				}) : null
 			]
-		}) : null, /* @__PURE__ */ jsx("div", {
+		}) : null, /* @__PURE__ */ jsxs("div", {
 			"data-slot": "choice-list-frame",
 			className: slots.frame(),
-			children: items.length === 0 ? /* @__PURE__ */ jsx("p", {
-				"data-slot": "choice-list-note",
-				className: slots.note(),
-				children: empty
-			}) : /* @__PURE__ */ jsxs(Fragment$1, { children: [rows.length > 0 ? /* @__PURE__ */ jsxs("div", {
-				"data-slot": "choice-list-rows",
-				className: slots.rows(),
-				children: [props.multiple ? /* @__PURE__ */ jsx(CheckboxGroup, {
-					"data-slot": "choice-list-group",
-					value: props.value,
-					onValueChange: props.onValueChange,
-					...groupProps,
-					children: rowElements
-				}) : /* @__PURE__ */ jsx(RadioGroup, {
-					"data-slot": "choice-list-group",
-					value: props.value,
-					onValueChange: props.onValueChange,
-					...groupProps,
-					children: rowElements
-				}), rows.map((item, index) => item.action !== void 0 && item.action !== null ? /* @__PURE__ */ jsx("div", {
-					"data-slot": "choice-list-action",
-					className: slots.action(),
-					style: { gridRow: index + 1 },
-					children: item.action
-				}, item.value) : null)]
-			}) : null, searchable ? /* @__PURE__ */ jsx("p", {
-				role: "status",
-				"data-slot": "choice-list-status",
-				className: noMatch ? slots.note() : "sr-only",
-				children: noMatch ? noMatchLabel : null
-			}) : null] })
+			children: [/* @__PURE__ */ jsx("div", {
+				"data-slot": "choice-list-scroller",
+				className: slots.scroller(),
+				children: items.length === 0 ? /* @__PURE__ */ jsx("p", {
+					"data-slot": "choice-list-note",
+					className: slots.note(),
+					children: empty
+				}) : /* @__PURE__ */ jsxs(Fragment$1, { children: [rows.length > 0 ? /* @__PURE__ */ jsxs("div", {
+					"data-slot": "choice-list-rows",
+					className: slots.rows(),
+					children: [props.multiple ? /* @__PURE__ */ jsx(CheckboxGroup, {
+						"data-slot": "choice-list-group",
+						value: props.value,
+						onValueChange: props.onValueChange,
+						...groupProps,
+						children: rowElements
+					}) : /* @__PURE__ */ jsx(RadioGroup, {
+						"data-slot": "choice-list-group",
+						value: props.value,
+						onValueChange: props.onValueChange,
+						...groupProps,
+						children: rowElements
+					}), sections.flatMap((section) => section.rows.map((item) => item.action !== void 0 && item.action !== null ? /* @__PURE__ */ jsx("div", {
+						"data-slot": "choice-list-action",
+						className: slots.action(),
+						style: { gridRow: gridRowOf.get(item.value) },
+						children: item.action
+					}, item.value) : null))]
+				}) : null, searchable ? /* @__PURE__ */ jsx("p", {
+					role: "status",
+					"data-slot": "choice-list-status",
+					className: noMatch ? slots.note() : "sr-only",
+					children: noMatch ? noMatchLabel : null
+				}) : null] })
+			}), footer !== void 0 && footer !== null ? /* @__PURE__ */ jsx("div", {
+				"data-slot": "choice-list-footer",
+				className: slots.footer(),
+				children: footer
+			}) : null]
 		})]
 	});
 }

package/package.json

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