@botiverse/raft-ui 0.20.0 → 0.21.1

package/CHANGELOG.md

@@ -1,3 +1,160 @@
+## [0.21.1](https://github.com/botiverse/raft-design/compare/v0.21.0...v0.21.1) (2026-10-22)
+
+### Design System
+
+- **Chips**: the ink at a chip's two ends sits the same distance from its fill's edges. A chip keeps its total padding and its width, and splits the padding between its ends so each end makes up for the empty space its own content brings. A smaller note after a chip's label centers on the label's letters, and the label stays on the sentence's baseline. It applies to MessageReferenceChip, MessageReferencePending, MessageReferenceUnavailable, MessageReactionChip, MessageItemSavedIndicator, MessageForwardedBundleAttachment, TaskChip and TaskCardStatus, and to the new MessageReferenceSuffix. ([#700](https://github.com/botiverse/raft-design/pull/700))
+  - Why: the chips split their padding as if every end were the same, so an icon or a status pixel sat closer to its edge than the last letter did to the other (3.6px against 7px in a reference chip), and the end after the text looked empty; each chip's padding is now set from where its ink is drawn.
+  - Affects: the padding at each end, left / right, totals unchanged; see Fixed below.
+  - Docs: https://raft-design.botiverse.build/foundations/alignment/#chips
+- **A control and its label**: a settings row is the exception to the first-line rule. The leading icon, avatar or tile and the trailing switch, checkbox, radio, value or chevron of a `ListRow variant="plain"` center on the whole row, with or without a description, as they did in 0.20. A checkbox or radio beside wrapping text in a `<label>` row still sits on that text's first line. It applies to ListRow. ([#703](https://github.com/botiverse/raft-design/pull/703))
+  - Why: a setting reads as one unit, and with its controls on the title's first line they belonged to the title instead of the row; settings rows center them on the row again.
+  - Docs: https://raft-design.botiverse.build/foundations/alignment/#a-control-and-its-label
+- **Timeline rhythm: the edge that messages scroll under fades**: the bottom edge of a message list, over the composer, fades from the panel's color to transparent over the section step, at all times, instead of cutting the message under it. The line of who is about to post sits on the same fade and has none of its own. It applies to the new MessageListEndFade. ([#699](https://github.com/botiverse/raft-design/pull/699))
+  - Why: a message scrolled under the composer was cut off by a hard edge; the edge now fades, as a tab bar fades on the side that hides tabs.
+  - Affects: fade height `timeline-section` 24px, `layer-canvas` to transparent.
+  - Docs: https://raft-design.botiverse.build/foundations/spacing/#timeline-rhythm
+
+### Added
+
+- **MessageReferenceSuffix**: a short note after a reference chip's label, in muted Space Mono, such as `msg` on a link to a message. Put it inside `MessageReferenceChip`, after `MessageReferenceLabel`. ([#700](https://github.com/botiverse/raft-design/pull/700))
+  - Why: a note in a span of the caller's own sat on the label's baseline, 0.3px low beside a 12.25px label and 0.75px low beside a 14px one, and its descenders made it look lower still; the part keeps the label's baseline in the layout and draws the note a quarter of the size difference higher, so the middles of the two x-heights meet.
+  - Affects: `text-label` (11px) in `foreground-hint`, line height 1; drawn `(label size - 1em) / 4` higher.
+  - Docs: https://raft-design.botiverse.build/components/message-item/
+- **MessageListEndFade**: the fade over a message list's bottom edge. Put it beside `MessageList`, in the same positioned parent (`ConversationPanelBody` is one), like the jump controls; it lies under them, is hidden from assistive technology and takes no pointer events. ([#699](https://github.com/botiverse/raft-design/pull/699))
+  - Why: see Timeline rhythm: the edge that messages scroll under fades, above.
+  - Affects: 24px tall (`h-timeline-section`), `layer-canvas` to transparent upward, `z-index` 5.
+  - Docs: https://raft-design.botiverse.build/components/message-list/
+- **SegmentedControl** `variant="on-frame"`, for a control in the frame (a top bar). `variant="default"` is unchanged and stays the default. ([#693](https://github.com/botiverse/raft-design/pull/693))
+  - Why: a yellow sticker on the yellow frame did not read as selected, and a white segment beside it looked chosen instead; in the frame the selected segment takes the frame's active colors, as a selected rail item does.
+  - Affects: track `fill-frame-medium`; other segments `foreground-on-frame-muted`, with `foreground-on-frame` on hover and `overlay-frame-medium` on hover and press; the selected segment `layer-frame-active` with a `line-frame-active` edge and `foreground-on-frame-active` text (white on the yellow frame, yellow on the dark one).
+  - Docs: https://raft-design.botiverse.build/components/segmented-control/
+
+### Changed
+
+- **ListRow** `variant="plain"` with a description: the leading icon, avatar or tile and the trailing switch, checkbox, radio, value or chevron center on the whole row again, as in 0.20, instead of on the title's first line. With a title alone, nothing changes. This reverts the 0.21.0 change to ListRow. ([#703](https://github.com/botiverse/raft-design/pull/703))
+  - Why: see A control and its label above.
+  - Affects: the ends move without changing size, so row heights are unchanged (54px on a phone for a one-line row with a switch).
+  - Docs: https://raft-design.botiverse.build/components/list-row/
+
+### Fixed
+
+- **MessageReferenceChip**, **MessageReferencePending**, **MessageReferenceUnavailable**, **MessageReactionChip**, **MessageItemSavedIndicator**, **MessageForwardedBundleAttachment**, **TaskChip** and **TaskCardStatus**: the ink at both ends sits the same distance from the edges; each chip keeps its total padding and its width. ([#700](https://github.com/botiverse/raft-design/pull/700))
+  - Why: see Chips above.
+  - Affects: padding left / right: MessageReferenceChip, MessageReferencePending and MessageReferenceUnavailable with an icon 3px / 6px → 4.5px / 4.5px (without an icon unchanged, 6px / 6px); MessageReactionChip 6px / 8px → 7px / 7px; MessageItemSavedIndicator and MessageForwardedBundleAttachment 6px / 6px → 5.5px / 6.5px (their bookmark and file icons are drawn inside their boxes); TaskChip 6px / 8px → 7px / 7px, `size="sm"` 4px / 6px → 5px / 5px and `variant="inline"` 3px / 6px → 4.5px / 4.5px; TaskCardStatus 6px / 8px → 7px / 7px.
+  - Docs: https://raft-design.botiverse.build/foundations/alignment/#chips
+- **MessageReferencePending**, and any reference chip, holding a `Spinner`: the spinner centers on the middle of the label's line, as an icon does. ([#700](https://github.com/botiverse/raft-design/pull/700))
+  - Why: the chip centered only `svg` icons on the label's line, and a spinner is not one, so it sat on the baseline, 5–6px below the middle of the label's line.
+  - Docs: https://raft-design.botiverse.build/components/message-item/
+- **MessageQuotedPreviewChannel** and **MessageQuotedPreviewThread**: the icon sits on the first line of the name when a long name wraps, instead of in the middle of both lines. ([#700](https://github.com/botiverse/raft-design/pull/700))
+  - Why: the icon was centered on the whole name, so it slid between the lines of a wrapped name; it now follows A mark that leads text, like the other components.
+  - Affects: the icon (14px) is placed `(1lh - 14px) / 2` from the top of the name's first line.
+  - Docs: https://raft-design.botiverse.build/foundations/alignment/#a-mark-that-leads-text
+
+## [0.21.0](https://github.com/botiverse/raft-design/compare/v0.20.1...v0.21.0) (2026-10-22)
+
+0.20.1 was not published to npm. This release includes its changes, listed under [0.20.1](https://github.com/botiverse/raft-design/blob/v0.21.0/packages/ui/CHANGELOG.md#0201-2026-10-22) in the changelog.
+
+### Design System
+
+- **Timeline rhythm**: a conversation uses three distances between its lines, measured from text to text: 8px between the rows of one turn, the message step (16px) between turns, and the section step (24px) at a boundary: either side of a date line, from the top of the list to its first line, and from the last line to the composer's frame. It applies to MessageItem, SystemMessage, SystemMessageGroupHeader, MessageListDateDivider, MessageListNotice, ThreadPanelOriginalMessage, ThreadPanelReplySummary, ThreadPanelReplyCount, ConversationPanelFooter and ThreadPanelFooter. ([#694](https://github.com/botiverse/raft-design/pull/694))
+  - Why: each part kept its own spacing, so a date line sat closer to the message above it than to the one below and looked attached to it, an event line had more space under it than over it, and the composer's frame read as touching the last message; the parts now read one rhythm from tokens, one step wider for each kind of break.
+  - Affects: new tokens `timeline-gap-message` 16px, `timeline-gap-section` 24px and `timeline-row-inset` 4px (the reach of a row's highlight above and below its text).
+  - Docs: https://raft-design.botiverse.build/foundations/spacing/#timeline-rhythm
+- **A control and its label**: a checkbox, radio or switch sits 8px before its label, centered on the label's first line, and keeps its size wherever it sits. In a settings row with a description, both ends center on the title's first line. A tap between two options lands on the nearer one. It applies to Checkbox, RadioGroupItem and ListRow; FieldItem already followed it. ([#686](https://github.com/botiverse/raft-design/pull/686))
+  - Why: a box in a `<label>` row followed the row instead of the text's line, so callers nudged it with a margin, and a settings row's ends centered on the title and description together, level with neither; the components now place the control themselves.
+  - Affects: switch 50 × 30px and checkbox and radio 20px, unchanged; 8px from control to label.
+  - Docs: https://raft-design.botiverse.build/foundations/alignment/#a-control-and-its-label
+
+### Breaking Changes
+
+- **ConversationPanelFooter** and **ThreadPanelFooter**: no space of their own above the composer; the end of the list sets it. ([#694](https://github.com/botiverse/raft-design/pull/694))
+  - Why: the footer's 12px stacked on whatever space the list left under its last message, so the gap to the composer differed from list to list; now the list ends with one token and the composer's frame sits a section step, 24px, under the last line.
+  - Affects: footer top padding 12px → 0; `pb-timeline-end` is 20px (the 24px section step less the last row's 4px inset).
+  - Migrate: end your message list with `pb-timeline-end` under its last row, in place of any spacer you had there; without it the composer moves 12px closer to the last message. You can also start the list with `pt-timeline-start` over its first row, so its top follows the same step.
+  - Docs: https://raft-design.botiverse.build/components/conversation-panel/
+
+### Added
+
+- **Timeline spacing utilities**: `pt-timeline-start` and `pb-timeline-end` for the top and end of a message list you build, and `timeline-message`, `timeline-section`, `timeline-row`, `timeline-turn` and `timeline-lead`, which the components use. All are registered with the `cn` helper, so they merge with other padding and margin classes. ([#694](https://github.com/botiverse/raft-design/pull/694))
+  - Why: a list's top and end were written by hand in each product, which is how the gaps drifted; two utilities now give the section step with the rows' own insets taken out.
+  - Affects: `timeline-start` 12px, `timeline-end` 20px, `timeline-turn` 8px, `timeline-lead` 12px, `timeline-message` 16px, `timeline-section` 24px, `timeline-row` 4px. Use only `timeline-start` and `timeline-end` in a product.
+  - Docs: https://raft-design.botiverse.build/foundations/spacing/#timeline-rhythm
+- **`ButtonSize`** and **`DeprecatedButtonSize`** types, and the **`button-sizes` codemod**, which renames deprecated Button sizes to the size they render as. ([#686](https://github.com/botiverse/raft-design/pull/686))
+  - Why: the deprecated names could only be found by hand, and `sm` and `xs` are also sizes of other components; the codemod parses TSX and renames `size` only on Buttons, the raft-ui parts that pass `size` to a Button and wrappers you name, plus `icon-sm` / `icon-xs` on any element and `size` in `buttonVariants()` calls.
+  - Affects: run `node node_modules/@botiverse/raft-ui/codemods/button-sizes.mjs <src> [--dry] [--components=MyButton]`; it renames `xs`, `sm` → `md` and `icon-xs`, `icon-sm` → `icon-md`, then lists every `sm`, `xs`, `icon-sm` and `icon-xs` it left for review. It needs `@babel/parser`, a new optional peer dependency (`pnpm add -D @babel/parser`); nothing else uses it.
+  - Docs: https://raft-design.botiverse.build/components/button/#sizes
+
+### Changed
+
+- **Button** `size`: `xs` and `sm` are deprecated aliases of `md`, and `icon-xs` and `icon-sm` of `icon-md`, kept until raft-ui 1.0. They already rendered as those sizes, so nothing on screen changes. ([#686](https://github.com/botiverse/raft-design/pull/686))
+  - Why: nine names for five sizes made a smaller button look available where there is none; a new Size by place table says which size each place takes.
+  - Affects: sizes `md` (32px), `lg`, `xl`, `icon-md` and `icon-lg`; `size` is typed `ButtonSize | DeprecatedButtonSize`, so every existing size name still type-checks. No runtime warning.
+  - Docs: https://raft-design.botiverse.build/components/button/#size-by-place
+- **Checkbox** and **RadioGroupItem** directly in a `<label>`: the box takes one line of the label's height and centers on it, so it sits on the first line in an `items-start` row and on the one line in an `items-center` row, at any min-height. ([#686](https://github.com/botiverse/raft-design/pull/686))
+  - Why: the box followed the row rather than the text's line, so it sat above the center of a line taller than 20px and callers added a `margin-top`; see A control and its label above.
+  - Affects: vertical margin `max(0, (1lh - 20px) / 2)` from the `<label>`'s type (2px on a 24px line); the box stays 20px and a `text-xs` row stays 20px tall. A `margin-top` you added to line it up is no longer needed. Set the label's type on the `<label>`, use `items-start` when the text can wrap, and give a wrapping `text-xs` label `leading-5`.
+  - Docs: https://raft-design.botiverse.build/foundations/alignment/#a-control-and-its-label
+- **DescriptionList** `direction="inline"`: every fact is at most 24rem wide, or the row's width if that is narrower, and keeps the same 24px between facts and 8px between lines as the others. ([#697](https://github.com/botiverse/raft-design/pull/697))
+  - Why: a long value, such as a message, made its fact as wide as the row on a line of its own, so one line of facts no longer read as one flow; every fact now wraps the same way, and a long value wraps at the cap, or is cut there when the caller truncates it.
+  - Affects: fact `max-width` none → `min(100%, 24rem)` (384px); plain text longer than that wraps inside the 24rem. To cut a long value on one line instead, truncate it with an ellipsis and make the whole value available elsewhere, such as a tooltip.
+  - Docs: https://raft-design.botiverse.build/components/description-list/
+- **ListRow** `variant="plain"` with a description: the leading icon, avatar or tile and the trailing switch, checkbox, radio, value or chevron center on the title's first line instead of the middle of the title and description. With a title alone, nothing changes. ([#686](https://github.com/botiverse/raft-design/pull/686))
+  - Why: with a description the ends sat between the title and the description, level with neither and with no line of text.
+  - Affects: the ends move without changing size, so row heights are unchanged (54px on a phone for a one-line row with a switch).
+  - Docs: https://raft-design.botiverse.build/components/list-row/
+- **MessageListDateDivider**, **SystemMessage**, **SystemMessageGroupHeader**, **MessageListNotice**, **ThreadPanelOriginalMessage**, **ThreadPanelReplySummary** and **ThreadPanelReplyCount**: spaced on the timeline rhythm. ([#694](https://github.com/botiverse/raft-design/pull/694))
+  - Why: see Timeline rhythm above.
+  - Affects: a date line's rule sits 24px from the text above and below it (was 24px / 32px on a phone, 25px / 33px on a desktop); SystemMessage padding 12px / 12px → 12px / 4px, 16px from the text on both sides; a closed SystemMessageGroupHeader keeps the same 12px / 4px around its disclosure's text (padding 6px / 6px → 6px top and −2px bottom on a phone, 7px and −1px on a desktop), and an open one keeps its 6px under the header; MessageListNotice padding 0 / 8px → 12px / 4px; ThreadPanelOriginalMessage bottom padding 8px → 20px and ThreadPanelReplySummary top padding 8px → 12px, so the thread's rule sits 24px from the text on both sides; ThreadPanelReplyCount gains 4px above it (margin 0 / 4px → 4px / 4px). MessageItem keeps its 4px / 8px, now read from the tokens.
+  - Docs: https://raft-design.botiverse.build/foundations/spacing/#timeline-rhythm
+
+### Fixed
+
+- **Select**, **Combobox**, **ComboboxSelect** and **InputGroup**: a value cut with an ellipsis gets its full text as a `title` whenever it is cut. ([#695](https://github.com/botiverse/raft-design/pull/695))
+  - Why: the check compared whole pixels with 1px to spare, so it missed cuts of about 0.6–1.3px that still showed an ellipsis, and it did not measure again when a web font finished loading; it now compares fractional sizes and measures again after fonts load.
+  - Affects: tolerance 1px (whole pixels) → 0.5px (fractional).
+  - Docs: https://raft-design.botiverse.build/components/select/
+- **Checkbox** and **RadioGroupItem** hit areas: in a `<label>` row the box or circle reaches 4px past its line, half the 8px gap to the next option, so a tap between two options lands on the nearer one; the label is the target for the rest. On its own, its hit area is 44px tall on a touch screen. ([#686](https://github.com/botiverse/raft-design/pull/686))
+  - Why: each option's hit area reached across the gap and the next option's covered it, so a tap just under one option could select the next one.
+  - Affects: standalone touch hit area 44px tall (was 36px for a checkbox, 33px for a radio); standalone mouse hit area unchanged; in a `<label>` row the hit area is the line plus 4px above and below, for every pointer.
+  - Docs: https://raft-design.botiverse.build/foundations/alignment/#a-control-and-its-label
+
+## [0.20.1](https://github.com/botiverse/raft-design/compare/v0.20.0...v0.20.1) (2026-10-22)
+
+### Design System
+
+- **A mark that leads text**: an icon or status light that starts a line of text is centered on the first line of that text and stays there when the text wraps or a description follows. Only the place is shared; each component keeps its own icon size and gap. A status light beside text is always 9px. It applies to Banner, PanelNotice, ToastIcon, MessageActionCardNotice, Badge and PanelActivity. ([#670](https://github.com/botiverse/raft-design/pull/670), [#687](https://github.com/botiverse/raft-design/pull/687))
+  - Why: each component placed its mark with its own fixed offset, which held for one type size and drifted at the next; one rule, the line box center (the cap-height center in Space Grotesk), now places every mark.
+  - Affects: offset `(1lh - size) / 2` on the row's own type; status light 9px with a 1.5px ink edge.
+  - Docs: https://raft-design.botiverse.build/foundations/alignment/#a-mark-that-leads-text
+- **Popups stay on their trigger**: when the window or a pane scrolls under an open popup, the popup moves with the element that opened it. A context menu stays with the point where it was opened. It applies to SelectContent, ComboboxContent, PopoverContent, PreviewCardContent and NotificationCenterPopup. ([#669](https://github.com/botiverse/raft-design/pull/669))
+  - Why: popups stayed where they opened while the page scrolled, pointing at whatever had scrolled into place; the wrappers no longer turn Base UI's anchor tracking off.
+  - Docs: https://raft-design.botiverse.build/foundations/elevation/#popups
+
+### Added
+
+- **`lead-icon`** and **`lead-dot`** utilities: center an icon (`lead-icon`) or a `Status` light (`lead-dot`) you place yourself on the first line of the text beside it. ([#670](https://github.com/botiverse/raft-design/pull/670), [#687](https://github.com/botiverse/raft-design/pull/687))
+  - Why: a mark placed outside the components above had no way to follow the same rule except a hand-tuned margin.
+  - Affects: `lead-dot` sizes the light 9px with a 1.5px edge, so don't pass the `Status` a `size`. Both read `1lh`, so put the text's type on the row that holds the mark and the text.
+  - Docs: https://raft-design.botiverse.build/foundations/alignment/#a-mark-that-leads-text
+
+### Changed
+
+- **Status** in Banner, PanelNotice, ToastIcon, Badge and PanelActivity: held at 9px and centered on the first line, whatever `size` or vertical margin it was given. ([#670](https://github.com/botiverse/raft-design/pull/670), [#687](https://github.com/botiverse/raft-design/pull/687))
+  - Why: the same light showed at different sizes in a toast, a banner and a chip; a light beside text has one size, 9px, the least color that tells green from yellow from orange, plus its ink edges.
+  - Affects: a `Status` passed `xs` (6px), `sm` (8px) or `lg` (11px) in these components renders 9px; the `xs` edge 1px → 1.5px (its 1px corner stays). The default `md` is unchanged, as are icon sizes and gaps.
+  - Docs: https://raft-design.botiverse.build/components/status/#sizes
+
+### Fixed
+
+- **PanelNotice**: a leading status light or icon is centered on the first line of the notice's text. ([#670](https://github.com/botiverse/raft-design/pull/670), [#687](https://github.com/botiverse/raft-design/pull/687))
+  - Why: the mark sat at the top of the first line, a light 6.5px above the line's center on a desktop (5.5px on a phone) and a 16px icon 3px (2px); the notice now follows A mark that leads text.
+  - Affects: icon size and gap are unchanged (your icon's size, 10px before the text).
+  - Docs: https://raft-design.botiverse.build/components/panel/
+- **Popups**: SelectContent, ComboboxContent, PopoverContent, PreviewCardContent and NotificationCenterPopup follow their trigger while the window or a scrolling pane moves. ([#669](https://github.com/botiverse/raft-design/pull/669))
+  - Why: these wrappers turned anchor tracking off by default, so an open popup kept its opening position and drifted off its trigger as soon as anything scrolled; they now leave it to Base UI's default.
+  - Affects: `disableAnchorTracking` default `true` → unset (Base UI's default, tracking on). ContextMenuContent drops its `true` default too; it is anchored to a point, so it looks the same. Pass `disableAnchorTracking` to turn it off for one popup. Select still turns tracking off with `alignItemWithTrigger`.
+  - Docs: https://raft-design.botiverse.build/foundations/elevation/#popups
+
 ## [0.20.0](https://github.com/botiverse/raft-design/compare/v0.19.0...v0.20.0) (2026-10-22)
 
 ### Design System

package/codemods/button-sizes.mjs

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+// Renames Button's duplicate sizes to the one they always rendered as.
+//
+//   node node_modules/@botiverse/raft-ui/codemods/button-sizes.mjs <dir-or-file>... [--dry] [--components=MyButton,…]
+//
+// `xs` and `sm` render exactly as `md`, and `icon-xs` and `icon-sm` exactly as
+// `icon-md`, so nothing on screen changes: xs, sm -> md; icon-xs, icon-sm ->
+// icon-md. The old names keep working as deprecated aliases until raft-ui 1.0,
+// so the rewrite can land at any time after upgrading.
+//
+// Needs @babel/parser, an optional peer dependency of raft-ui: install it
+// in the project you migrate (`pnpm add -D @babel/parser`).
+//
+// Each file is parsed as TypeScript and JSX (@babel/parser), so comments,
+// strings and JSX text never confuse it, and a Button anywhere is found: as a
+// child, in another component's prop (`actions={<Button …/>}`,
+// `render={<Button …/>}`), in a callback. It rewrites:
+// - the `size` of `<Button>`, of the raft-ui parts that pass `size` to a
+//   Button (BUTTON_COMPONENTS), and of the components named with
+//   `--components`, for your own wrappers: a string (`size="sm"`,
+//   `size={"sm"}`) or the strings in an expression (`size={inHead ? "sm" :
+//   "lg"}`);
+// - `icon-sm` and `icon-xs` in the `size` of any JSX element: only Button has
+//   those names;
+// - `size: "sm"` in a `buttonVariants({…})` call.
+// `sm` and `xs` are names other components use too (Dialog, Banner, Avatar,
+// Spinner …), so nothing else is touched. It then lists every `sm`, `xs`,
+// `icon-sm` and `icon-xs` string it left, with the element it belongs to, for
+// review by hand: a size kept in a variable, a wrapper you didn't name, a test.
+import { readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+let babelParse;
+
+/**
+ * @babel/parser is an optional peer dependency of raft-ui: only this codemod
+ * uses it. Look in the project being migrated first, then beside raft-ui.
+ */
+function loadParser() {
+  if (babelParse) return babelParse;
+  for (const from of [path.join(process.cwd(), "package.json"), import.meta.url]) {
+    try {
+      babelParse = createRequire(from)("@babel/parser").parse;
+      return babelParse;
+    } catch {
+      // Try the next place.
+    }
+  }
+  throw new Error(
+    "install @babel/parser to run this codemod (it parses your TSX): pnpm add -D @babel/parser",
+  );
+}
+
+/** Deprecated Button size -> the size it renders as. */
+export const BUTTON_SIZE_RENAMES = {
+  xs: "md",
+  sm: "md",
+  "icon-xs": "icon-md",
+  "icon-sm": "icon-md",
+};
+
+/** raft-ui components whose `size` is a Button size. */
+export const BUTTON_COMPONENTS = [
+  "Button",
+  "AlertDialogAction",
+  "AlertDialogCancel",
+  "AlertDialogClose",
+  "AnnouncementDialogAction",
+  "AnnouncementDialogSecondaryAction",
+  "ComposerSubmit",
+  "CopyableCodeAction",
+  "DialogClose",
+  "DrawerClose",
+  "FileAction",
+  "SidebarSectionControl",
+];
+
+const ICON_ONLY = new Set(["icon-xs", "icon-sm"]);
+const OLD = new Set(Object.keys(BUTTON_SIZE_RENAMES));
+
+function parseSource(source, file) {
+  const ext = path.extname(file);
+  const plugins =
+    ext === ".ts" || ext === ".mts" || ext === ".cts" ? ["typescript"] : ["typescript", "jsx"];
+  return loadParser()(source, {
+    sourceType: "unambiguous",
+    plugins,
+    errorRecovery: true,
+    allowReturnOutsideFunction: true,
+  });
+}
+
+/** Depth-first walk over a Babel AST, with each node's parent chain. */
+function walk(node, visit, parents = []) {
+  if (!node || typeof node.type !== "string") return;
+  visit(node, parents);
+  const next = [...parents, node];
+  for (const key of Object.keys(node)) {
+    if (key === "loc" || key === "start" || key === "end" || key === "extra") continue;
+    const value = node[key];
+    if (Array.isArray(value)) for (const child of value) walk(child, visit, next);
+    else if (value && typeof value.type === "string") walk(value, visit, next);
+  }
+}
+
+function elementName(name) {
+  if (!name) return "";
+  if (name.type === "JSXIdentifier") return name.name;
+  if (name.type === "JSXMemberExpression")
+    return `${elementName(name.object)}.${name.property.name}`;
+  if (name.type === "JSXNamespacedName") return `${name.namespace.name}:${name.name.name}`;
+  return "";
+}
+
+/** The string literals a `size` value can resolve to, without entering nested functions or JSX. */
+function sizeStrings(node, out = []) {
+  if (!node) return out;
+  switch (node.type) {
+    case "StringLiteral":
+      out.push(node);
+      break;
+    case "TemplateLiteral":
+      if (node.expressions.length === 0 && node.quasis.length === 1) out.push(node);
+      break;
+    case "JSXExpressionContainer":
+    case "ParenthesizedExpression":
+    case "TSAsExpression":
+    case "TSSatisfiesExpression":
+    case "TSNonNullExpression":
+      sizeStrings(node.expression, out);
+      break;
+    case "ConditionalExpression":
+      sizeStrings(node.consequent, out);
+      sizeStrings(node.alternate, out);
+      break;
+    case "LogicalExpression":
+      sizeStrings(node.left, out);
+      sizeStrings(node.right, out);
+      break;
+    default:
+      break;
+  }
+  return out;
+}
+
+const literalValue = (node) =>
+  node.type === "StringLiteral" ? node.value : node.quasis[0].value.cooked;
+
+function lineOf(source, index) {
+  let line = 1;
+  for (let i = 0; i < index; i += 1) if (source.charCodeAt(i) === 10) line += 1;
+  return line;
+}
+
+/**
+ * Renames the deprecated sizes in one file. Returns the new source and the
+ * strings it left, as `{ line, value, where }`.
+ */
+export function migrateButtonSizes(
+  source,
+  { file = "file.tsx", components = BUTTON_COMPONENTS } = {},
+) {
+  const buttons = new Set(components);
+  const ast = parseSource(source, file);
+  const edits = new Map();
+  const rename = (literal) => {
+    const value = literalValue(literal);
+    const quote = source[literal.start];
+    edits.set(literal.start, {
+      end: literal.end,
+      text: `${quote}${BUTTON_SIZE_RENAMES[value]}${quote}`,
+    });
+  };
+  const handled = new Set();
+
+  walk(ast.program, (node) => {
+    if (node.type === "JSXOpeningElement") {
+      const name = elementName(node.name);
+      const isButton = buttons.has(name);
+      for (const attribute of node.attributes) {
+        if (attribute.type !== "JSXAttribute" || attribute.name.name !== "size") continue;
+        for (const literal of sizeStrings(attribute.value)) {
+          const value = literalValue(literal);
+          if (!OLD.has(value)) continue;
+          handled.add(literal.start);
+          if (isButton || ICON_ONLY.has(value)) rename(literal);
+        }
+      }
+    }
+    if (
+      node.type === "CallExpression" &&
+      node.callee.type === "Identifier" &&
+      node.callee.name === "buttonVariants"
+    ) {
+      for (const argument of node.arguments) {
+        if (argument.type !== "ObjectExpression") continue;
+        for (const property of argument.properties) {
+          if (property.type !== "ObjectProperty") continue;
+          const key = property.key.type === "Identifier" ? property.key.name : property.key.value;
+          if (key !== "size") continue;
+          for (const literal of sizeStrings(property.value)) {
+            if (!OLD.has(literalValue(literal))) continue;
+            handled.add(literal.start);
+            rename(literal);
+          }
+        }
+      }
+    }
+  });
+
+  // Every deprecated name still standing, and what it belongs to.
+  const left = [];
+  walk(ast.program, (node, parents) => {
+    // A test that matches the source (`/size="sm"/`) has to change with it.
+    if (node.type === "RegExpLiteral") {
+      const name = /["'](icon-)?(sm|xs)["']/.exec(node.pattern);
+      if (name) {
+        left.push({
+          line: lineOf(source, node.start),
+          value: name[0].slice(1, -1),
+          where: "a regular expression",
+        });
+      }
+      return;
+    }
+    const isString =
+      node.type === "StringLiteral" ||
+      (node.type === "TemplateLiteral" &&
+        node.expressions.length === 0 &&
+        node.quasis.length === 1);
+    if (!isString || !OLD.has(literalValue(node)) || edits.has(node.start)) return;
+    let where = "a string";
+    let prop = "";
+    for (let i = parents.length - 1; i >= 0; i -= 1) {
+      const parent = parents[i];
+      if (parent.type === "JSXAttribute" && !prop) prop = ` ${parent.name.name}`;
+      if (parent.type === "JSXOpeningElement") {
+        where = `<${elementName(parent.name)}${prop}>`;
+        break;
+      }
+      if (parent.type === "JSXElement" || parent.type === "JSXFragment") break;
+    }
+    left.push({ line: lineOf(source, node.start), value: literalValue(node), where });
+  });
+
+  let out = source;
+  for (const start of [...edits.keys()].sort((a, b) => b - a)) {
+    const { end, text } = edits.get(start);
+    out = out.slice(0, start) + text + out.slice(end);
+  }
+  return { source: out, left };
+}
+
+/** The source with the deprecated sizes renamed (see migrateButtonSizes). */
+export function renameButtonSizes(source, components = BUTTON_COMPONENTS, file = "file.tsx") {
+  return migrateButtonSizes(source, { file, components }).source;
+}
+
+const EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts"]);
+const SKIP = new Set(["node_modules", "dist", "build", ".git"]);
+
+function* walkFiles(target) {
+  const stat = statSync(target);
+  if (stat.isFile()) {
+    if (EXTENSIONS.has(path.extname(target))) yield target;
+    return;
+  }
+  for (const name of readdirSync(target)) {
+    if (SKIP.has(name) || name.startsWith(".")) continue;
+    yield* walkFiles(path.join(target, name));
+  }
+}
+
+function main(argv) {
+  const dry = argv.includes("--dry");
+  const option = argv.find((arg) => arg.startsWith("--components="));
+  const components = option
+    ? [...BUTTON_COMPONENTS, ...option.slice("--components=".length).split(",").filter(Boolean)]
+    : BUTTON_COMPONENTS;
+  const targets = argv.filter((arg) => !arg.startsWith("--"));
+  if (targets.length === 0) {
+    console.error("usage: button-sizes.mjs <dir-or-file>... [--dry] [--components=MyButton,…]");
+    process.exit(1);
+  }
+  let changed = 0;
+  const review = [];
+  try {
+    loadParser();
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+  const groups = new Map();
+  for (const target of targets) {
+    for (const file of walkFiles(target)) {
+      const before = readFileSync(file, "utf8");
+      if (!/["'`](?:icon-)?(?:sm|xs)["'`]/.test(before)) continue;
+      let result;
+      try {
+        result = migrateButtonSizes(before, { file, components });
+      } catch (error) {
+        review.push(`${file}: could not parse (${error.message}); not changed`);
+        continue;
+      }
+      for (const { line, value, where } of result.left) {
+        review.push(`${file}:${line}  "${value}" in ${where}`);
+        groups.set(where, (groups.get(where) ?? 0) + 1);
+      }
+      if (result.source === before) continue;
+      changed += 1;
+      console.log(`${dry ? "would update" : "updated"} ${file}`);
+      if (!dry) writeFileSync(file, result.source);
+    }
+  }
+  console.log(`${changed} file${changed === 1 ? "" : "s"} ${dry ? "to update" : "updated"}`);
+  if (review.length > 0) {
+    console.log(
+      "\nLeft as they are; check each by hand (another component's size, a variable, your own wrapper).",
+    );
+    console.log("\nBy element and prop:");
+    for (const [where, count] of [...groups].sort((a, b) => b[1] - a[1])) {
+      console.log(`  ${String(count).padStart(4)}  ${where}`);
+    }
+    console.log("\nEach one:");
+    for (const where of review) console.log(`  ${where}`);
+  }
+}
+
+// Run only when invoked directly (see token-names.mjs: pnpm installs through
+// symlinks, so compare real paths).
+function isInvokedDirectly() {
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+if (isInvokedDirectly()) main(process.argv.slice(2));

package/dist/cn.mjs

@@ -11,7 +11,14 @@ const twMerge = extendTailwindMerge({ extend: {
 		"embedded-inset",
 		"option",
 		"option-inset",
-		"icon-inset"
+		"icon-inset",
+		"timeline-message",
+		"timeline-section",
+		"timeline-row",
+		"timeline-turn",
+		"timeline-lead",
+		"timeline-end",
+		"timeline-start"
 	] },
 	classGroups: {
 		shadow: [{ shadow: [

package/dist/foundation.css

@@ -310,6 +310,19 @@
   /* A chip or a button embedded in a field: the control height less the embedded
      inset above and below, so the field keeps its height. */
   --control-embedded-size: 32px;
+  /* The message step of a timeline: from the last line of one turn to the first
+     line of the next (a sender line, an event line). Every row keeps the row
+     inset above and below its text; the first row of a turn adds the rest above
+     it. */
+  --timeline-gap-message: 16px;
+  /* The section step of a timeline, one step wider than the message step: either
+     side of a date line, from the top of the list to the first line, and from
+     the last line to the composer, so a boundary reads as one and the last
+     message never sits on the composer. */
+  --timeline-gap-section: 24px;
+  /* How far a timeline row's hover and selected highlight reaches above and
+     below its text. Two rows of one turn sit two insets apart. */
+  --timeline-row-inset: 4px;
   --sticker-ink: oklch(0.1813 0.005 17.62);
   --sticker-paper: oklch(1 0 0);
   --sticker-edge: oklch(0.1813 0.005 17.62 / 0);