@sableui/react 0.0.0-stage → 0.1.1

package/llms/components/marquee.md

@@ -0,0 +1,66 @@
+# Marquee
+
+**Status:** stable
+
+Seamless, constant-speed infinite loop (logos, tags, testimonials). Zero-dependency: duplicates children to fill the track and advances exactly one group + gap per iteration so it never seams. Pauses on hover/focus; freezes to a scroll region when motion is off/reduced.
+
+**Keywords:** marquee, ticker, scrolling, ambient
+
+## Usage
+
+Use Marquee for decorative or ambient continuous content where motion supports the surface.
+
+### Best practices
+
+- Do: Use it for low-priority repeated content such as logos, tags, or lightweight highlights.
+- Do: Respect reduced motion and keep the content understandable without relying on animation.
+- Don't: Do not put critical messages, controls, or required reading inside Marquee.
+- Don't: Do not put content that must be read in a Marquee. It moves continuously, so anything longer than a logo or a short label cannot be read reliably — and it must stop for prefers-reduced-motion.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| direction | "left" \| "right" \| "up" \| "down" | "left" | Scroll direction; up/down switch to a vertical loop, which needs a bounded height (e.g. className="h-56"). |
+| speed | number | 40 | Constant speed in px/s — independent of content length. |
+| gap | string | "calc(var(--spacing) * 8)" | Gap between items (any CSS length). Use a spacing-scale value (calc(var(--spacing) * n)) so it moves with density. |
+| pauseOnHover | boolean | true | Pause while hovered or keyboard-focused (WCAG 2.2.2). |
+| controls | boolean | false | Render a visible pause/play control — recommended for WCAG 2.2.2 when content auto-scrolls. |
+| fade | boolean | false | Fade the leading/trailing edges with a mask. |
+| label | string | — | Accessible label for the scrolling region. |
+
+## Accessibility
+
+- Duplicate groups are aria-hidden, so screen readers read the content once.
+- Pauses on hover and focus-within; under prefers-reduced-motion / MotionProvider off it stops and becomes a normal scroll region.
+- Decorative by default — pass a label only when the row conveys meaning.
+
+## Related
+
+- Components: Scroller, Carousel, Badge
+
+## Examples
+
+### Logo row
+
+```tsx
+import { Marquee } from "@sableui/react"
+
+<Marquee>{logos.map((l) => <img key={l.id} src={l.src} alt={l.name} className="h-8" />)}</Marquee>
+```
+
+### Reverse, faster
+
+```tsx
+import { Badge, Marquee } from "@sableui/react"
+
+<Marquee direction="right" speed={70}>{tags.map((t) => <Badge key={t} appearance="outline">{t}</Badge>)}</Marquee>
+```
+
+### Vertical
+
+```tsx
+import { Marquee } from "@sableui/react"
+
+<Marquee direction="up" className="h-64">{items}</Marquee>
+```

package/llms/components/menu.md

@@ -0,0 +1,122 @@
+# Menu
+
+**Status:** stable
+
+Dropdown menu over Base UI Menu — roving focus, typeahead, ARIA menu/menuitem wiring, collision-aware positioning, Esc/outside dismissal. Trigger + portal-rendered popup with items, groups, and separators.
+
+**Keywords:** menu, dropdown, actions, commands
+
+## Usage
+
+Use Menu for a compact list of actions opened from a visible trigger.
+
+### Best practices
+
+- Do: Use it for secondary or grouped commands that do not need to be visible all the time.
+- Do: Keep item labels action-oriented and easy to scan.
+- Do: Inside a <Workspace> a Menu adapts automatically — its popup re-applies the compact density across the portal, so items render on the chrome type tier and the control ladder resolves to workspace sizes. Do NOT override the size per call site; that was necessary before v0.41 and is now drift.
+- Don't: Do not use Menu for complex forms, persistent navigation, or arbitrary rich content.
+- Don't: Do not build a Select out of it. A menu fires actions and has no value; a Select holds one and reports changes. Swapping them loses form semantics and keyboard type-ahead.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| MenuTrigger | yes | The control that opens the menu. |
+| MenuContent | yes | The floating command surface. |
+| MenuItem | yes | One selectable command. |
+| MenuSeparator | no | A divider between groups. |
+| MenuGroup | no | A grouped set of menu items. |
+| MenuGroupLabel | no | A label for a group of items. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| MenuTrigger | Base UI Menu.Trigger props + render | The button that opens the menu. Compose with render={<Button … />}. |
+| MenuContent | Base UI Popup props + side: 'top' \| 'right' \| 'bottom' \| 'left' + align: 'start' \| 'center' \| 'end' + sideOffset: number + className | Portal + Positioner + Popup. side picks which side of the trigger the popup renders against (auto-flips on collision; defaults to 'bottom'); align sets alignment along that side (defaults to 'start'); sideOffset is the gap in px between trigger and popup (defaults to 6). |
+| MenuItem | Base UI Menu.Item props + className (disabled, closeOnClick, onClick) + variant?: "default" \| "destructive" | An interactive row. Highlights via data-[highlighted]; dims via data-[disabled]. variant="destructive" for a delete or irreversible action: it keeps the destructive ink when highlighted (never className="text-destructive", which the highlight repaints). |
+| MenuSeparator | Base UI Separator props + className | Hairline rule between item runs. |
+| MenuSubmenu | Base UI Menu.SubmenuRoot props | A nested menu. Wraps a MenuSubmenuTrigger and its own MenuContent — pass side="inline-end" to that content so the submenu opens away from its parent in RTL as well as LTR. |
+| MenuSubmenuTrigger | Base UI Menu.SubmenuTrigger props + value: ReactNode + className | The row that opens a submenu: item styling, a trailing chevron, and an optional `value` showing the current choice so the row reads "Effort  High ›" rather than making the reader open it to find out. |
+| MenuRadioGroup | Base UI Menu.RadioGroup props (value, defaultValue, onValueChange) | A single-choice group inside a menu. Controlled via value/onValueChange, uncontrolled via defaultValue. |
+| MenuRadioItem | Base UI Menu.RadioItem props + className (value, disabled) | One option in a MenuRadioGroup, rendered as menuitemradio with a real checked state. The check sits in a reserved leading column so labels never shift sideways as the highlight moves. |
+| MenuCheckboxItem | Base UI Menu.CheckboxItem props + className + { checked?: boolean; defaultChecked?: boolean; onCheckedChange?: (checked: boolean) => void; disabled?: boolean } | A toggling row, with the same reserved leading column as MenuRadioItem so a menu mixing the two keeps one text margin. |
+| MenuGroup | Base UI Menu.Group props + className | Groups related items; pair with MenuGroupLabel for an accessible group name. |
+| MenuGroupLabel | Base UI Menu.GroupLabel props + className | The label for a MenuGroup — auto-associated with the group for screen readers. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| Menu (Root) | Base UI Menu.Root props (open, defaultOpen, onOpenChange, modal, orientation, loopFocus) | — | Groups all parts and controls open state. Uncontrolled by default. |
+
+## Tokens used
+
+`popover`, `popover-foreground`, `border`, `accent`, `accent-foreground`, `muted-foreground`
+
+## Accessibility
+
+- Base UI provides role=menu/menuitem, roving tabindex, arrow-key navigation, and typeahead.
+- Esc and outside-press dismiss; focus returns to the trigger on close.
+- Animate open/close via data-[starting-style]/data-[ending-style] attributes.
+- MenuGroupLabel is auto-associated with its MenuGroup for screen readers.
+- A disabled MenuItem stays in the arrow-key order — Base UI keeps it focusable with aria-disabled so screen-reader users learn the command exists — but it cannot be activated, and it ignores the pointer.
+
+## Related
+
+- Components: ContextMenu, DotsMenu
+
+## Examples
+
+### Basic
+
+```tsx
+import { Button, Menu, MenuContent, MenuItem, MenuSeparator, MenuTrigger } from "@sableui/react"
+
+<Menu><MenuTrigger render={<Button variant="secondary">Options</Button>} /><MenuContent><MenuItem>Edit</MenuItem><MenuItem>Duplicate</MenuItem><MenuSeparator /><MenuItem variant="destructive">Delete</MenuItem></MenuContent></Menu>
+```
+
+### Grouped
+
+```tsx
+import { Button, Menu, MenuContent, MenuGroup, MenuGroupLabel, MenuItem, MenuSeparator, MenuTrigger } from "@sableui/react"
+
+<Menu><MenuTrigger render={<Button variant="secondary">Account</Button>} /><MenuContent><MenuGroup><MenuGroupLabel>Signed in</MenuGroupLabel><MenuItem>Profile</MenuItem><MenuItem>Settings</MenuItem></MenuGroup><MenuSeparator /><MenuItem>Sign out</MenuItem></MenuContent></Menu>
+```
+
+### Nested, with a single-choice submenu
+
+```tsx
+import { Button, Menu, MenuContent, MenuItem, MenuRadioGroup, MenuRadioItem, MenuSubmenu, MenuSubmenuTrigger, MenuTrigger } from "@sableui/react"
+
+<Menu>
+	<MenuTrigger render={<Button variant="secondary">View</Button>} />
+	<MenuContent>
+		<MenuItem>Reload</MenuItem>
+		<MenuSubmenu>
+			<MenuSubmenuTrigger value={density}>Density</MenuSubmenuTrigger>
+			<MenuContent side="inline-end" align="start" sideOffset={4}>
+				<MenuRadioGroup value={density} onValueChange={setDensity}>
+					<MenuRadioItem value="Comfortable">Comfortable</MenuRadioItem>
+					<MenuRadioItem value="Compact">Compact</MenuRadioItem>
+				</MenuRadioGroup>
+			</MenuContent>
+		</MenuSubmenu>
+	</MenuContent>
+</Menu>
+```
+
+### Toggling rows
+
+```tsx
+import { Button, Menu, MenuCheckboxItem, MenuContent, MenuTrigger } from "@sableui/react"
+
+<Menu>
+	<MenuTrigger render={<Button variant="secondary">Columns</Button>} />
+	<MenuContent>
+		<MenuCheckboxItem checked={cols.status} onCheckedChange={(v) => setCol("status", v)}>Status</MenuCheckboxItem>
+		<MenuCheckboxItem checked={cols.updated} onCheckedChange={(v) => setCol("updated", v)}>Updated</MenuCheckboxItem>
+	</MenuContent>
+</Menu>
+```

package/llms/components/message-scroller.md

@@ -0,0 +1,110 @@
+# MessageScroller
+
+**Status:** stable
+
+Scroll container for a conversation. Auto-follows new messages until the reader scrolls away, holds position when older history is prepended, and exposes scroll commands and visibility tracking through its ref.
+
+**Keywords:** chat, conversation, messages, thread, transcript, stick to bottom, auto scroll, streaming, infinite scroll, inbox, ai chat, support chat
+
+## Usage
+
+The scroll region a conversation lives in. It owns the scrolling and nothing else — not your messages, not your AI state, not your transport or persistence — so you bring the content renderer and it handles the behaviors that make streaming chat feel right: pinning to the newest message, releasing when the reader scrolls up, keeping the view still when older history loads above, jumping to a specific message, restoring a saved read position, and reporting what is actually on screen.
+
+### Best practices
+
+- Do: Bound it the way you would bound any scroll box — `flex-1 min-h-0` inside a flex column, or `max-h-96`. `className` lands on the element that actually scrolls, so the obvious bound is the correct one (same contract as Scroller).
+- Do: Give every Message a `messageId`. It is the handle for `scrollToMessage`, `initialScroll`, and `onVisibleMessagesChange` — a message without one is invisible to all three.
+- Do: Prepend older history directly into `children` when the reader reaches the top. The scroller anchors on the first rendered message and re-adds the height that appeared above it, so the view does not jump.
+- Do: Set the rhythm between messages with the `gap` prop, not with a flex class on `className` — the messages are laid out in a column inside the scroll region, not directly on it.
+- Do: Restore a reopened thread with `initialScroll={{ messageId: lastRead }}` instead of dropping the reader at the bottom of a conversation they have not finished.
+- Do: Wrap a docked agent panel in `<Density value="compact">`. The scroller tightens its rhythm and every message inside it drops to the workspace type tier — one attribute for the whole conversation, no per-component sizing.
+- Don't: Do not call `scrollToBottom` on every incoming token. Auto-follow already does it, and doing it yourself fights the reader who scrolled up to read something.
+- Don't: Do not expect `ref` to be the DOM node — it is a command handle (`scrollToBottom`, `scrollToMessage`, `isFollowing`). Reach for `ref.current.element` when you genuinely need the element.
+- Don't: Do not wrap it in a positioned div to place a jump-to-latest button. It ships one, stuck to the bottom edge from inside the scroll region, which is why `className` gets to stay on the scrolling element.
+- Don't: Do not use it for an ordinary long list. That is `Scroller` — this one's follow-the-bottom behavior is wrong for content the reader is browsing rather than receiving.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Scroll region | yes | The element that scrolls. Carries `className`: sizing, padding, and background. |
+| Message column | yes | The flex column holding the children, spaced by `gap`. Publishes `--message-gap` so `<Message grouped>` can close it. |
+| Jump to latest | no | A control stuck to the bottom edge, shown only while the reader is scrolled away from the newest message. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| ref | Ref<MessageScrollerHandle> | — | Imperative commands, not the DOM node: `scrollToBottom(opts)`, `scrollToTop(opts)`, `scrollToMessage(id, opts)` (returns false when the message is not rendered), `isFollowing()`, and `element` for the scrolling node itself. |
+| autoFollow | boolean | true | Keep the newest message in view as content arrives, until the reader scrolls away from the bottom. Set false for a transcript that must never move under the reader. |
+| followThreshold | number | 64 | Distance from the bottom, in px, that still counts as following. A band rather than a pixel, so a token arriving mid-frame does not flicker the state. |
+| onFollowChange | (following: boolean) => void | — | Notified when the viewport pins to, or releases from, the newest message. |
+| initialScroll | "bottom" \| "top" \| { messageId: string } | "bottom" | Where a freshly mounted thread lands. Pass a messageId to restore a saved read position. Applied once, on mount — changing it later will not yank a reader mid-conversation. |
+| jumpToLatest | boolean | true | Show the jump-to-latest control while the reader is scrolled away from the newest message. |
+| jumpToLatestLabel | string | "Jump to latest" | Accessible label and tooltip for that control. |
+| gap | "sm" \| "md" \| "lg" | "md" | Vertical rhythm between messages. Also published as `--message-gap`, which `<Message grouped>` reads to collapse the gap within a run. |
+| onVisibleMessagesChange | (ids: string[]) => void | — | Ids of the messages currently intersecting the viewport, in DOM order. The hook for read receipts, mark-as-seen, and unread counters. |
+| ...div props | Omit<ComponentPropsWithRef<"div">, "ref"> | — | Spread onto the scrolling element. `className` bounds and pads the scroll region; `onScroll` composes with the component's own. |
+
+## Variants
+
+- **gap**: sm, md, lg
+
+## Tokens used
+
+`border`, `secondary`, `secondary-foreground`, `ring`
+
+## Accessibility
+
+- Native overflow, so keyboard scrolling (arrows, Page Up/Down, Home/End) and the OS scrollbar work unchanged; the scrollbar is styled thin, not replaced.
+- Overscroll is contained, so a wheel gesture that runs out of conversation does not start scrolling the page behind it.
+- The jump-to-latest control is a real button with an accessible label, reachable by keyboard, and only present when there is somewhere to jump to.
+- Smooth scrolling is used only when motion is enabled — `prefers-reduced-motion` and <MotionProvider> off both collapse every scroll command to an instant jump.
+
+## Related
+
+- Components: Message, Bubble, Marker, Attachment, Scroller
+
+## Examples
+
+### Streaming conversation
+
+```tsx
+import { Bubble, Marker, Message, MessageScroller } from "@sableui/react"
+
+<MessageScroller className="flex-1 min-h-0 px-4 py-6">{messages.map((m) => (<Message key={m.id} messageId={m.id} align={m.mine ? "end" : "start"}><Bubble variant={m.mine ? "primary" : "muted"} align={m.mine ? "end" : "start"}>{m.body}</Bubble></Message>))}{pending ? <Marker icon="spinner" spin shimmer>Thinking…</Marker> : null}</MessageScroller>
+```
+
+### Scroll to a message on demand
+
+```tsx
+import { Bubble, Button, Message, MessageScroller } from "@sableui/react"
+
+function Thread({ messages, replyTo }) {
+	const thread = useRef(null)
+	return (
+		<>
+			<Button onClick={() => thread.current?.scrollToMessage(replyTo)}>Show original</Button>
+			<MessageScroller ref={thread} className="max-h-96">
+				{messages.map((m) => (<Message key={m.id} messageId={m.id}><Bubble>{m.body}</Bubble></Message>))}
+			</MessageScroller>
+		</>
+	)
+}
+```
+
+### Restore a saved read position and track receipts
+
+```tsx
+import { Bubble, Message, MessageScroller } from "@sableui/react"
+
+<MessageScroller className="h-96" initialScroll={{ messageId: lastRead }} onVisibleMessagesChange={(ids) => markSeen(ids)}>{messages.map((m) => (<Message key={m.id} messageId={m.id}><Bubble>{m.body}</Bubble></Message>))}</MessageScroller>
+```
+
+### Prepend older history without moving the view
+
+```tsx
+import { Bubble, Button, Message, MessageScroller } from "@sableui/react"
+
+<MessageScroller className="h-96" gap="sm">{hasMore ? <Button variant="secondary" loadingLabel="Loading…" onClick={loadOlder}>Load earlier messages</Button> : null}{messages.map((m) => (<Message key={m.id} messageId={m.id}><Bubble>{m.body}</Bubble></Message>))}</MessageScroller>
+```

package/llms/components/message.md

@@ -0,0 +1,114 @@
+# Message
+
+**Status:** stable
+
+One row in a conversation: avatar gutter, side, and stacked header / content / footer. Layout only — the surface is Bubble, passed as children.
+
+**Keywords:** chat, message, conversation row, turn, thread, messaging, grouped messages, ai chat
+
+## Usage
+
+The row a single turn occupies. It owns the geometry — which side, the avatar gutter, where the name and timestamp go, where reactions and receipts go — and nothing about how the content looks. That separation is the point: an assistant's markdown answer, a one-line reply, an attachment, and a tool-call card are all the same row with different children.
+
+### Best practices
+
+- Do: Set `messageId`. It is what MessageScroller reads for `scrollToMessage`, `initialScroll`, and visibility tracking — a message without one cannot be jumped to or marked as read.
+- Do: Pass the same `align` to Message and to the Bubble inside it, so the flattened tail corner lands on the speaker's side.
+- Do: Use `grouped` for consecutive messages from one author. It tightens the spacing and hides the avatar while keeping its column reserved, so the run reads as one block instead of stepping left. Pass `tail={false}` to the Bubble in each continuation too, so only the first message in the run carries a tail.
+- Do: Match `avatarSize` to the `size` of the Avatar you pass (sm/md/lg line up 1:1). The gutter is declared, not measured, because it has to hold its width when `grouped` hides the avatar.
+- Don't: Do not justify the content to move a message to the right. `align="end"` already mirrors the whole row, gutter included; adding your own justification fights it.
+- Don't: Do not put the timestamp inside the Bubble. It belongs in `header` or `footer`, which stay outside the surface so `variant="plain"` content still has one.
+- Don't: Do not reach for Message to lay out a system note or a date break. That is `Marker`, which is deliberately quieter than the message tier.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Avatar gutter | no | Fixed-width column for the author's Avatar. Kept (but emptied) when `grouped`, which is what keeps a run aligned. |
+| Header | no | Author name and timestamp, above the content. |
+| Content | yes | The children — usually a Bubble, but equally an Attachment, a tool card, or plain rendered markdown. |
+| Footer | no | Reactions, delivery receipts, retry actions. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| messageId | string | — | Stable id, published as `data-message-id`. The handle MessageScroller uses for scroll commands and visibility tracking. |
+| align | "start" \| "end" | "start" | Which side of the conversation. "start" is the other party or the assistant; "end" is the person reading. Mirrors the whole row, gutter included. |
+| avatar | ReactNode | — | Avatar node for the gutter. Omit for a message with no author identity. |
+| avatarSize | "sm" \| "md" \| "lg" | "sm" | Gutter width, matching Avatar's own size scale 1:1 (32 / 40 / 48px). Declared rather than measured so it survives `grouped`. |
+| header | ReactNode | — | Author name, timestamp — anything above the content. |
+| footer | ReactNode | — | Reactions, receipts, retry actions — anything below the content. |
+| grouped | boolean | false | This message continues a run from the same author: tightens the spacing (via `--message-gap`) and drops the avatar while reserving its column. |
+| ...div props | Omit<ComponentPropsWithRef<"div">, "id"> | — | Spread onto the row. Use `messageId` rather than `id` — the scroller matches on `data-message-id`. |
+
+## Variants
+
+- **align**: start, end
+- **avatarSize**: sm, md, lg
+
+## Tokens used
+
+`foreground`, `muted-foreground`
+
+## Accessibility
+
+- A plain container with no imposed role — the conversation's semantics belong to the list or log element you wrap it in, not to each row.
+- `align` reverses the visual row without reordering the DOM, so reading order in assistive tech stays chronological regardless of which side a message is on.
+- The header and footer render at the secondary type step in muted ink, keeping both below the message tier in the visual hierarchy without dropping either below the AA contrast floor.
+
+## Related
+
+- Components: Bubble, MessageScroller, Marker, Attachment, Avatar
+
+## Examples
+
+### Incoming and outgoing
+
+```tsx
+import { Avatar, Bubble, Message, RelativeTime } from "@sableui/react"
+
+<>
+	<Message messageId="m1" avatar={<Avatar size="sm" fallback="CA" />} header={<><strong className="text-foreground">Carla</strong><RelativeTime date={sentAt} /></>}>
+		<Bubble>Did the deploy finish?</Bubble>
+	</Message>
+	<Message messageId="m2" align="end">
+		<Bubble variant="primary" align="end">Green across the board.</Bubble>
+	</Message>
+</>
+```
+
+### A grouped run
+
+```tsx
+import { Avatar, Bubble, Message } from "@sableui/react"
+
+<>
+	<Message messageId="m1" avatar={<Avatar size="sm" fallback="CA" />} header={<strong className="text-foreground">Carla</strong>}>
+		<Bubble>One more thing.</Bubble>
+	</Message>
+	<Message messageId="m2" grouped>
+		<Bubble tail={false}>The staging cert expires Friday.</Bubble>
+	</Message>
+</>
+```
+
+### With reactions in the footer
+
+```tsx
+import { Avatar, Bubble, BubbleReaction, BubbleReactions, Message } from "@sableui/react"
+
+<Message messageId="m3" avatar={<Avatar size="sm" fallback="JR" />} footer={<BubbleReactions><BubbleReaction emoji="🎉" count={3} active /><BubbleReaction emoji="👀" /></BubbleReactions>}>
+	<Bubble>Shipped 0.45.0.</Bubble>
+</Message>
+```
+
+### An attachment as the content
+
+```tsx
+import { Attachment, Message } from "@sableui/react"
+
+<Message messageId="m4" align="end">
+	<Attachment name="proposal.pdf" meta="2.4 MB · PDF" />
+</Message>
+```

package/llms/components/meter.md

@@ -0,0 +1,124 @@
+# Meter
+
+**Status:** stable
+
+A role=meter reading over Base UI Meter, drawn as a bar or a ring — how full something is within a known range (storage, quota, strength), with a tone for good/caution/bad. Not task progress.
+
+**Keywords:** meter, usage bar, storage, quota, capacity, limit, password strength, level
+
+## Usage
+
+Use Meter to show a static measurement against a known maximum — storage used, seats taken, API quota, password strength. It is announced as a meter, not a progress bar, so a screen-reader user hears a level rather than a task underway.
+
+### Best practices
+
+- Do: Label it and show the reading in units people use ("7.2 of 10 GB"), with MeterLabel and MeterValue. The bar shows proportion; the number is what gets acted on.
+- Do: Pick `tone` from thresholds you own and apply them consistently across the page — warning near the limit, destructive at or over it. The component does not guess where good becomes bad.
+- Do: Use shape="ring" when the reading is a score that belongs in a small, glanceable spot on a card. It is the same measurement drawn as a circular gauge, not a different component.
+- Don't: Do not use Meter for a task in flight — an upload, an install, a step count. That is Progress; Meter tells assistive tech nothing is happening.
+- Don't: Do not use it for a value without a meaningful maximum (followers, total spend). A bar implies a full scale; an unbounded count is a stat.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| MeterTrack | yes | The rail that represents the full range. |
+| MeterIndicator | yes | The fill, sized from value and coloured by tone. |
+| MeterLabel | no | The visible name; also names the meter for assistive tech. |
+| MeterValue | no | The formatted reading. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| MeterTrack | Base UI Track props + className + size | The rail. Rendered automatically when Meter has no children; renders a MeterIndicator by default. |
+| MeterIndicator | Base UI Indicator props + className + tone | The fill. Inherits the Meter's tone unless given its own. |
+| MeterLabel | Base UI Label props + className | Visible label; wires aria-labelledby on the root. |
+| MeterValue | Base UI Value props + className | Formatted reading. Accepts a `(formatted, value) => ReactNode` child. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| value | number | — | The current reading, between min and max. Required. |
+| min | number | 0 | The bottom of the range. |
+| max | number | 100 | The top of the range. |
+| tone | "primary" \| "standard" \| "success" \| "warning" \| "destructive" | "primary" | Fill colour, mapped to a semantic token. Choose it from your own thresholds. |
+| shape | "bar" \| "ring" | "bar" | bar is a horizontal track; ring is a circular gauge for a small, glanceable reading — the same value, min, max and tones. |
+| size | "sm" \| "md" \| "lg" | "md" | Ring diameter (40 / 64 / 96px at the default spacing; the centre value steps with it), or bar thickness on the same sm / md / lg rails as Progress. |
+| showValue | boolean | — | Print the value in the ring's centre (formatted like MeterValue). |
+| strokeWidth | number | 6 | Ring stroke width, in viewBox units of 100. |
+| format | Intl.NumberFormatOptions | — | Formatting for MeterValue and aria-valuetext (percent, unit, currency). |
+| getAriaValueText | (formatted: string, value: number) => string | — | Human-readable reading for assistive tech ("7.2 of 10 gigabytes used"). |
+| locale | Intl.LocalesArgument | — | Locale for formatting. Defaults to the runtime locale. |
+
+## Variants
+
+- **tone**: primary, standard, success, warning, destructive
+- **shape**: bar, ring
+- **size**: sm, md, lg
+
+## Tokens used
+
+`secondary`, `primary`, `success`, `tone-warning`, `destructive`, `foreground`, `muted-foreground`
+
+## Motion
+
+- **arrival** · Meter · _no motion_ — A meter is a reading, present with the page that reports it. Animating the fill up from zero on load would act out a change that did not happen.
+- **response** · Meter · _no motion_ — It reports and accepts no input. A bar that reacted to the pointer would read as a Slider the user could drag.
+- **transition** · MeterIndicator · _custom (outside the recipe layer)_ — Width and colour ease on the motion tokens (no recipe animates width) when the reading changes — freeing space after a delete visibly shrinks the bar, so the user sees the cause and effect rather than a different bar.
+- **activity** · Meter · _no motion_ — A meter has no indeterminate state; a reading is either known or not shown. Unknown-but-working is Progress with no value.
+
+## Accessibility
+
+- Base UI renders role=meter with aria-valuenow, aria-valuemin, aria-valuemax and aria-valuetext — distinct from Progress's role=progressbar.
+- Name it with MeterLabel or aria-label; an unnamed meter is announced as a bare number.
+- Tone is colour only. Say the state in text too ("Almost full") when it matters, and use getAriaValueText to give units.
+
+## Related
+
+- Components: Progress, Badge
+
+## Examples
+
+### Ring
+
+```tsx
+import { Meter } from "@sableui/react"
+
+<Meter shape="ring" value={72} showValue aria-label="Storage used" />
+```
+
+### Bare
+
+```tsx
+import { Meter } from "@sableui/react"
+
+<Meter value={64} aria-label="Storage used" />
+```
+
+### Storage with label and reading
+
+```tsx
+import { Meter, MeterLabel, MeterTrack, MeterValue } from "@sableui/react"
+
+<Meter value={7.2} max={10} tone="warning" getAriaValueText={(_, v) => `${v} of 10 gigabytes used`}>
+	<div className="mb-2 flex flex-wrap items-center justify-between gap-x-3 gap-y-1">
+		<MeterLabel>Storage</MeterLabel>
+		<MeterValue>{(_, value) => `${value} of 10 GB`}</MeterValue>
+	</div>
+	<MeterTrack />
+</Meter>
+```
+
+### Tones
+
+```tsx
+import { Meter } from "@sableui/react"
+
+<div className="flex flex-col gap-3">
+	<Meter value={30} tone="success" aria-label="Seats used" />
+	<Meter value={82} tone="warning" aria-label="API quota used" />
+	<Meter value={100} tone="destructive" aria-label="Storage used" />
+</div>
+```

package/llms/components/middle-truncate.md

@@ -0,0 +1,62 @@
+# MiddleTruncate
+
+**Status:** stable
+
+Middle-truncates a long string (hash, address, signature) to `5J7s…8xQp`, keeping the start and end legible while preserving the full value on hover.
+
+**Keywords:** truncate, middle truncate, hash, identifier
+
+## Usage
+
+Use MiddleTruncate when both the beginning and end of a long identifier must remain visible.
+
+### Best practices
+
+- Do: Use it for hashes, addresses, long filenames, URLs, or generated IDs.
+- Do: Provide the full value through title text, copy action, or surrounding detail when needed.
+- Don't: Do not use MiddleTruncate for human prose where the middle words carry meaning.
+- Don't: Do not middle-truncate a value with no way to obtain it in full. Truncation removes characters from the page, so the value needs a copy affordance beside it: an icon Button with useCopy, as in the Copyable value example.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| text | string | — | The full string to render. When it is truncated, the full value is also set as the title attribute (a pointer tooltip). |
+| startChars | number | 6 | How many leading characters to keep before the ellipsis. |
+| endChars | number | 6 | How many trailing characters to keep after the ellipsis. |
+
+## Accessibility
+
+- When truncated, the visible abbreviation is aria-hidden and a visually hidden copy carries the full value, so screen readers announce the whole string. The title attribute holds it too, for a pointer tooltip only.
+- Renders the string verbatim when it is too short to benefit from truncation, so no value is hidden needlessly.
+
+## Related
+
+- Components: Code, Button
+
+## Examples
+
+### Solana address
+
+```tsx
+import { MiddleTruncate } from "@sableui/react"
+
+<MiddleTruncate text="5J7sX2QpHt9vK4mNbR8wYcZ3dF6gH1jL0pA8xQpVnTu" />
+```
+
+### Custom start/end counts
+
+```tsx
+import { MiddleTruncate } from "@sableui/react"
+
+<MiddleTruncate text="0xAbC1234567890dEf1234567890aBcDeF12345678" startChars={4} endChars={4} />
+```
+
+### Copyable value
+
+```tsx
+import { Button, Icon, MiddleTruncate, Row, useCopy } from "@sableui/react"
+
+const { copy, copied } = useCopy(address)
+<Row gap={1}><MiddleTruncate text={address} /><Button variant="ghost" size="icon-xs" aria-label="Copy address" onClick={copy}><Icon name={copied ? "check" : "copy"} /></Button></Row>
+```