@sableui/react 0.6.2 → 0.7.1

package/dist/themes/registry.js

@@ -0,0 +1,59 @@
+// src/themes/registry.ts
+import { atelierTheme } from "./atelier/index.js";
+import { meridianTheme } from "./meridian/index.js";
+import { prismTheme } from "./prism/index.js";
+import { verdantTheme } from "./verdant/index.js";
+import { emberTheme } from "./ember/index.js";
+import { sableTheme } from "./sable/index.js";
+import { poppyTheme } from "./poppy/index.js";
+var SABLE_THEME_ATTRIBUTE = "data-sable-theme";
+var DEFAULT_THEME_ID = sableTheme.id;
+var defaultThemeId = DEFAULT_THEME_ID;
+var themeManifests = [
+  sableTheme,
+  meridianTheme,
+  prismTheme,
+  verdantTheme,
+  emberTheme,
+  poppyTheme,
+  atelierTheme
+];
+var featuredThemeManifests = themeManifests.filter((theme) => !theme.deprecated);
+var themeIds = themeManifests.map((theme) => theme.id);
+var themeManifestById = Object.fromEntries(
+  themeManifests.map((theme) => [theme.id, theme])
+);
+function isThemeId(value) {
+  return Object.hasOwn(themeManifestById, value);
+}
+function getThemeManifest(themeId) {
+  return themeManifestById[themeId];
+}
+function buildThemeManifestById(customThemes = []) {
+  const merged = { ...themeManifestById };
+  for (const theme of customThemes) merged[theme.id] = theme;
+  return merged;
+}
+function isKnownThemeId(value, manifestById) {
+  return Object.hasOwn(manifestById, value);
+}
+export {
+  DEFAULT_THEME_ID,
+  SABLE_THEME_ATTRIBUTE,
+  atelierTheme,
+  buildThemeManifestById,
+  defaultThemeId,
+  emberTheme,
+  featuredThemeManifests,
+  getThemeManifest,
+  isKnownThemeId,
+  isThemeId,
+  meridianTheme,
+  poppyTheme,
+  prismTheme,
+  sableTheme,
+  themeIds,
+  themeManifestById,
+  themeManifests,
+  verdantTheme
+};

package/dist/themes/sable/index.js

@@ -1 +1,16 @@
-export { sable_default as default, sableTheme } from '../../chunk-EHH4MHO6.js';
+// src/themes/sable/index.ts
+var sableTheme = {
+  id: "sable",
+  label: "Sable",
+  modes: ["dark", "light"],
+  defaultMode: "dark",
+  fonts: {
+    sans: '"Figtree", system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
+    mono: '"DM Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Courier New", monospace'
+  }
+};
+var sable_default = sableTheme;
+export {
+  sable_default as default,
+  sableTheme
+};

package/dist/{chunk-EFLC4NA3.js → themes/theme-provider.js}

@@ -1,45 +1,23 @@
-import { prismTheme } from './chunk-7MG4SHYX.js';
-import { verdantTheme } from './chunk-KO3NAEBF.js';
-import { emberTheme } from './chunk-L4IEIQQA.js';
-import { sableTheme } from './chunk-EHH4MHO6.js';
-import { poppyTheme } from './chunk-ADLLDWLW.js';
-import { meridianTheme } from './chunk-K7RUHUGC.js';
-import { atelierTheme } from './chunk-C4Z3CF54.js';
-import { createContext, useMemo, useState, useEffect, useCallback, useContext } from 'react';
-import { jsx } from 'react/jsx-runtime';
+"use client";
 
-// src/themes/registry.ts
-var SABLE_THEME_ATTRIBUTE = "data-sable-theme";
-var DEFAULT_THEME_ID = sableTheme.id;
-var defaultThemeId = DEFAULT_THEME_ID;
-var themeManifests = [
-  sableTheme,
-  meridianTheme,
-  prismTheme,
-  verdantTheme,
-  emberTheme,
-  poppyTheme,
-  atelierTheme
-];
-var featuredThemeManifests = themeManifests.filter((theme) => !theme.deprecated);
-var themeIds = themeManifests.map((theme) => theme.id);
-var themeManifestById = Object.fromEntries(
-  themeManifests.map((theme) => [theme.id, theme])
-);
-function isThemeId(value) {
-  return Object.hasOwn(themeManifestById, value);
-}
-function getThemeManifest(themeId) {
-  return themeManifestById[themeId];
-}
-function buildThemeManifestById(customThemes = []) {
-  const merged = { ...themeManifestById };
-  for (const theme of customThemes) merged[theme.id] = theme;
-  return merged;
-}
-function isKnownThemeId(value, manifestById) {
-  return Object.hasOwn(manifestById, value);
-}
+// src/themes/theme-provider.tsx
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState
+} from "react";
+import {
+  SABLE_THEME_ATTRIBUTE,
+  buildThemeManifestById,
+  defaultThemeId as sableDefaultThemeId,
+  isKnownThemeId,
+  isThemeId,
+  featuredThemeManifests
+} from "./registry.js";
+import { jsx } from "react/jsx-runtime";
 var SABLE_COLOR_STORAGE_KEY = "sable-color-preference";
 var SABLE_THEME_STORAGE_KEY = "sable-theme-id";
 var SableThemeContext = createContext(null);
@@ -117,7 +95,7 @@ function applySableColorMode(mode, target = rootElement()) {
 function applySableTheme(themeId, target = rootElement()) {
   if (!target) return;
   withSuppressedTransitions(() => {
-    if (themeId === defaultThemeId) {
+    if (themeId === sableDefaultThemeId) {
       target.removeAttribute(SABLE_THEME_ATTRIBUTE);
       return;
     }
@@ -126,10 +104,10 @@ function applySableTheme(themeId, target = rootElement()) {
 }
 function SableThemeProvider({
   children,
-  defaultPreference = "dark",
+  defaultPreference = "system",
   preference: controlledPreference,
   onPreferenceChange,
-  defaultThemeId: defaultThemeId2 = defaultThemeId,
+  defaultThemeId = sableDefaultThemeId,
   themeId: controlledThemeId,
   onThemeIdChange,
   colorStorageKey = SABLE_COLOR_STORAGE_KEY,
@@ -137,7 +115,7 @@ function SableThemeProvider({
   target = "root",
   customThemes
 }) {
-  const themeManifestById2 = useMemo(
+  const themeManifestById = useMemo(
     () => buildThemeManifestById(customThemes),
     [customThemes]
   );
@@ -145,7 +123,7 @@ function SableThemeProvider({
     () => coercePreference(readStorage(colorStorageKey), defaultPreference)
   );
   const [uncontrolledThemeId, setUncontrolledThemeId] = useState(
-    () => coerceThemeId(readStorage(themeStorageKey), defaultThemeId2, themeManifestById2)
+    () => coerceThemeId(readStorage(themeStorageKey), defaultThemeId, themeManifestById)
   );
   const [resolvedSystem, setResolvedSystem] = useState(systemColorMode);
   const preference = controlledPreference ?? uncontrolledPreference;
@@ -176,15 +154,15 @@ function SableThemeProvider({
       if (controlledThemeId === void 0) {
         if (event.key === themeStorageKey) {
           setUncontrolledThemeId(
-            coerceThemeId(event.newValue, defaultThemeId2, themeManifestById2)
+            coerceThemeId(event.newValue, defaultThemeId, themeManifestById)
           );
         }
         if (event.key === null) {
           setUncontrolledThemeId(
             coerceThemeId(
               readStorage(themeStorageKey),
-              defaultThemeId2,
-              themeManifestById2
+              defaultThemeId,
+              themeManifestById
             )
           );
         }
@@ -197,8 +175,8 @@ function SableThemeProvider({
     controlledPreference,
     controlledThemeId,
     defaultPreference,
-    defaultThemeId2,
-    themeManifestById2,
+    defaultThemeId,
+    themeManifestById,
     themeStorageKey
   ]);
   useEffect(() => {
@@ -252,7 +230,7 @@ function useSableTheme() {
     colorMode: "dark",
     preference: "dark",
     colorPreference: "dark",
-    themeId: defaultThemeId,
+    themeId: sableDefaultThemeId,
     themes: featuredThemeManifests,
     setPreference: () => {
     },
@@ -266,5 +244,11 @@ function useSableTheme() {
     }
   };
 }
-
-export { DEFAULT_THEME_ID, SABLE_COLOR_STORAGE_KEY, SABLE_THEME_ATTRIBUTE, SABLE_THEME_STORAGE_KEY, SableThemeProvider, applySableColorMode, applySableTheme, buildThemeManifestById, defaultThemeId, featuredThemeManifests, getThemeManifest, isKnownThemeId, isThemeId, themeIds, themeManifestById, themeManifests, useSableTheme };
+export {
+  SABLE_COLOR_STORAGE_KEY,
+  SABLE_THEME_STORAGE_KEY,
+  SableThemeProvider,
+  applySableColorMode,
+  applySableTheme,
+  useSableTheme
+};

package/dist/themes/verdant/index.js

@@ -1 +1,17 @@
-export { verdant_default as default, verdantTheme } from '../../chunk-KO3NAEBF.js';
+// src/themes/verdant/index.ts
+var verdantTheme = {
+  id: "verdant",
+  label: "Verdant",
+  modes: ["light", "dark"],
+  defaultMode: "light",
+  fonts: {
+    sans: '"Inter", system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
+    mono: '"IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Courier New", monospace',
+    display: '"Instrument Serif", Georgia, "Times New Roman", serif'
+  }
+};
+var verdant_default = verdantTheme;
+export {
+  verdant_default as default,
+  verdantTheme
+};

package/llms/blocks/media-player-block.md

@@ -21,9 +21,15 @@ A now-playing card: cover, title and artist as an Entity with a Like action, a p
 
 ```tsx
 import { useState } from "react"
-import { Button, Card, CardContent, cn, Entity, GradientArt, Icon, Slider } from "@sableui/react"
+import { Button, Card, CardContent, cn, Entity, Icon, MediaImage, Slider } from "@sableui/react"
 
-const track = { title: "Low tide, high noon", artist: "Juno Avery", position: 38, elapsed: "1:24", remaining: "-2:16" }
+// `cover` is the artwork URL; left empty, the cover paints art seeded by the title.
+const track = { title: "Low tide, high noon", artist: "Juno Avery", cover: "", duration: 220, position: 84 }
+
+/** Seconds → m:ss, the way the readout and the screen reader both say it. */
+function formatTime(seconds: number) {
+	return `${Math.floor(seconds / 60)}:${String(Math.floor(seconds % 60)).padStart(2, "0")}`
+}
 
 
 export interface MediaPlayerBlockProps {
@@ -38,6 +44,7 @@ export interface MediaPlayerBlockProps {
 
 export function MediaPlayerBlock({ className, framed = true, onPlayingChange, onPrevious, onNext }: MediaPlayerBlockProps) {
 	const [playing, setPlaying] = useState(true)
+	const [position, setPosition] = useState(track.position)
 	return (
 		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-xs", className)}>
 			<CardContent className="flex flex-col gap-4">
@@ -45,8 +52,7 @@ export function MediaPlayerBlock({ className, framed = true, onPlayingChange, on
 				    card already pads it. */}
 				<Entity
 					className="p-0"
-					// Placeholder cover painted from the theme. Replace with the cover image.
-					leading={<GradientArt aria-hidden seed={track.title} className="size-14 rounded-md" />}
+					leading={<MediaImage src={track.cover} seed={track.title} className="size-14 shrink-0 rounded-md" />}
 					title={track.title}
 					subtitle={track.artist}
 					action={
@@ -56,10 +62,17 @@ export function MediaPlayerBlock({ className, framed = true, onPlayingChange, on
 					}
 				/>
 				<div className="flex flex-col gap-1.5">
-					<Slider defaultValue={track.position} aria-label="Position" />
+					<Slider
+						value={position}
+						max={track.duration}
+						onValueChange={setPosition}
+						aria-label="Position"
+						// Spoken as a time, not "38": the number alone means nothing.
+						getAriaValueText={(_, value) => `${formatTime(value)} of ${formatTime(track.duration)}`}
+					/>
 					<div className="flex justify-between text-mono-caption text-muted-foreground">
-						<span>{track.elapsed}</span>
-						<span>{track.remaining}</span>
+						<span>{formatTime(position)}</span>
+						<span>-{formatTime(track.duration - position)}</span>
 					</div>
 				</div>
 				<div className="flex items-center justify-center gap-3">

package/llms/blocks/product-card-block.md

@@ -20,9 +20,10 @@ A product card: edge-to-edge artwork, title and maker, an edition Badge, and the
 ## Source
 
 ```tsx
-import { Badge, Button, Card, CardAction, CardDescription, CardFooter, CardHeader, CardTitle, cn, GradientArt } from "@sableui/react"
+import { AspectBox, Badge, Button, Card, CardAction, CardDescription, CardFooter, CardHeader, CardTitle, cn, MediaImage } from "@sableui/react"
 
-const product = { title: "Untitled (gold rush)", maker: "Mara Okafor", edition: "12 of 50", price: "0.42 SOL" }
+// `image` is the product shot URL; left empty, it paints art seeded by the title.
+const product = { title: "Untitled (gold rush)", maker: "Mara Okafor", image: "", edition: "12 of 50", price: "0.42 SOL" }
 
 
 export interface ProductCardBlockProps {
@@ -36,8 +37,9 @@ export interface ProductCardBlockProps {
 export function ProductCardBlock({ className, framed = true, onCollect }: ProductCardBlockProps) {
 	return (
 		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-xs overflow-hidden", className)}>
-			{/* Placeholder art painted from the theme, so it follows every look. Replace with the product image. */}
-			<GradientArt aria-hidden seed={product.title} className="aspect-[4/3]" />
+			<AspectBox ratio={4 / 3}>
+				<MediaImage src={product.image} seed={product.title} />
+			</AspectBox>
 			<CardHeader>
 				<CardTitle>{product.title}</CardTitle>
 				<CardDescription>{product.maker}</CardDescription>

package/llms/blocks/task-list-block.md

@@ -71,7 +71,7 @@ export function TaskListBlock({ className, framed = true, onAddTask }: TaskListB
 				</ul>
 			</CardContent>
 			<CardFooter>
-				<Button variant="ghost" size="sm" iconStart={<Icon name="plus" />} onClick={onAddTask}>
+				<Button variant="ghost" size="sm" bleed="start" iconStart={<Icon name="plus" />} onClick={onAddTask}>
 					Add task
 				</Button>
 			</CardFooter>

package/llms/blocks/traffic-sources-block.md

@@ -51,7 +51,7 @@ export function TrafficSourcesBlock({ className, framed = true }: TrafficSources
 					index="source"
 					valueKey="visitors"
 					donut
-					centerLabel={{ value: total.toLocaleString("en-US"), label: "Visitors" }}
+					centerLabel={{ value: total, label: "Visitors" }}
 				/>
 			</CardContent>
 			<CardFooter className="text-body-sm text-muted-foreground">

package/llms/blocks/traffic-trend-block.md

@@ -56,11 +56,13 @@ export function TrafficTrendBlock({ className, framed = true }: TrafficTrendBloc
 	const [range, setRange] = useState("90d")
 	const shown = days.slice(-(ranges.find((r) => r.id === range)?.days ?? 90))
 	return (
-		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-3xl", className)}>
-			<CardHeader>
+		<Card variant={framed ? "default" : "flat"} className={cn("@container/trend w-full max-w-3xl", className)}>
+			<CardHeader className="@max-sm/trend:has-data-[slot=card-action]:grid-cols-1">
 				<CardTitle render={<h2 />}>Visitors</CardTitle>
 				<CardDescription>Desktop and mobile, by day.</CardDescription>
-				<CardAction>
+				{/* Beside the title on a wide card; under it on a narrow one, where three
+				    ranges would squeeze the title and description into a sliver. */}
+				<CardAction className="@max-sm/trend:col-start-1 @max-sm/trend:row-span-1 @max-sm/trend:row-start-auto @max-sm/trend:mt-2 @max-sm/trend:justify-self-start">
 					<ToggleGroup value={[range]} onValueChange={(v: unknown[]) => v[0] && setRange(String(v[0]))} aria-label="Time range">
 						{ranges.map((r) => (
 							<Toggle key={r.id} value={r.id}>

package/llms/blocks/verify-code-block.md

@@ -49,7 +49,7 @@ export function VerifyCodeBlock({ className, framed = true, onVerify, onResend }
 			</CardContent>
 			<CardFooter className="justify-between gap-3">
 				<span className="text-caption text-muted-foreground">Didn’t get it?</span>
-				<Button variant="ghost" size="sm" onClick={onResend}>
+				<Button variant="ghost" size="sm" bleed="end" onClick={onResend}>
 					Resend code
 				</Button>
 			</CardFooter>

package/llms/components/app-shell.md

@@ -2,9 +2,9 @@
 
 **Status:** stable
 
-The application frame: slots for status banners, a mobile header, a desktop sidebar, main content, a mobile bottom nav, and floating overlays — plus a built-in skip link and #main-content target.
+The application frame: slots for status banners, a mobile header, a desktop sidebar, main content, a mobile bottom nav, a persistent dock (a now-playing or call bar), and floating overlays — plus a built-in skip link and #main-content target.
 
-**Keywords:** app shell, layout, frame, sidebar, header, bottom nav, mobile, banners, main
+**Keywords:** app shell, layout, frame, sidebar, header, bottom nav, mobile, banners, main, dock, player bar, now playing, persistent
 
 ## Usage
 
@@ -28,6 +28,7 @@ Use AppShell as the outer product frame for authenticated or app-like experience
 | Sidebar | no | Desktop navigation chrome, usually Sidebar. |
 | Main | yes | The route content landmark with id main-content. |
 | Bottom nav | no | Mobile fixed navigation with reserved bottom space. |
+| Dock | no | Persistent bottom chrome that outlives routes — a now-playing bar, a call bar. Sticky above the bottom nav; the desktop Sidebar shortens to clear it. |
 
 ## Props
 
@@ -37,6 +38,7 @@ Use AppShell as the outer product frame for authenticated or app-like experience
 | header | ReactNode | — | Mobile top header (e.g. AppHeader); expected to hide itself at lg. |
 | sidebar | ReactNode | — | Desktop side navigation (e.g. Sidebar); expected to hide itself below lg. Leading column of the body row. |
 | bottomNav | ReactNode | — | Mobile bottom navigation (e.g. BottomNav); fixed to the bottom edge. main reserves space for it. |
+| dock | ReactNode | — | Persistent chrome kept on screen across routes (a now-playing bar, an active-call bar, an upload tray). Full width, sticky to the bottom edge and above bottomNav on mobile; its height is published as --dock-height and the app Sidebar subtracts it. In flow, so main needs no reserved space. The contents paint their own surface and top border, and name themselves (e.g. <section aria-label="Player">). Mount AppShell in a layout that survives navigation, or the playback restarts. |
 | overlays | ReactNode | — | Floating overlays — a message launcher, FAB, or modal mount points. |
 
 ## Tokens used
@@ -48,6 +50,7 @@ Use AppShell as the outer product frame for authenticated or app-like experience
 - Renders a skip link to #main-content as the first focusable element.
 - Wraps content in a <main id="main-content"> landmark.
 - Slot components own their own ARIA (nav landmarks, labels).
+- The dock follows <main> in DOM order, so keyboard and screen-reader users reach the player after the page content, not before it.
 
 ## Related
 

package/llms/components/avatar.md

@@ -15,11 +15,12 @@ Use Avatar to represent a person, team, or account with a compact visual identit
 - Do: Use `variant="art"` where people without photos sit side by side — a member list, an activity feed, a chat. Seeded by the person, each gets their own colour, so faces stay tellable apart at a glance; the neutral fallback makes everyone the same grey circle.
 - Do: Provide meaningful alt text for profile images, or an empty alt when the adjacent text already names the person.
 - Do: Use initials or a simple glyph fallback so missing images still communicate identity.
-- Do: Use consistent sizes within a group; reserve lg for profile headers or major identity moments.
+- Do: Pick the size by the job: sm in dense rows and tables, md (the default) beside one line of text, lg in a row with a title and subtitle, xl (96px) for a profile header beside the person's name, 2xl (160px) for an artist or profile hero and roster portraits. Keep one size within a list or group.
 - Do: Use AvatarGroup for a stack of people, and give it an aria-label with the real count ("12 collaborators"). Set `surface` (or `--avatar-group-ring`) to whatever the group sits on, so the separating ring matches a card or popover, not the page. When it shares a row with actions, set `fit` so it gives up avatars to the "+N" count before the row has to wrap.
 - Don't: Hand-build a stack with negative margins and per-avatar ring classes, or fake the overflow as an Avatar with "+4" initials — screen readers hear "plus 4" with no context. Use AvatarGroup's `max`/`total`, or AvatarGroupCount.
 - Don't: Use avatars as decoration without nearby identity context. They should help users recognize a person or account.
 - Don't: Overload a dense table with large avatars; use sm or omit images when scanning data is more important.
+- Don't: Build a portrait by stretching an Avatar with size classes (`className="size-40"`) — the initials, the status indicator and the image fade stay at row scale. Use size="xl" or "2xl", which scale all three. Past 160px, or for a non-circular cover, it is media: an AspectBox, not an avatar.
 
 ### Anatomy
 
@@ -50,19 +51,26 @@ Use Avatar to represent a person, team, or account with a compact visual identit
 | fallback | ReactNode | — | Initials or a glyph rendered when no image is displayed. |
 | fallbackDelay | number | — | Delay before showing the fallback, in ms — avoids a flash on fast loads. |
 | status | ReactNode | — | A presence indicator pinned to the bottom-end edge, usually <StatusDot tone="success" />. It sits outside the clipped circle and wears a ring in the surface colour (--avatar-group-ring, else the page background). Use this instead of absolutely positioning a dot over an Avatar. |
-| size | "sm" \| "md" \| "lg" | "md" | Square footprint: 32px / 40px / 48px. |
+| size | "sm" \| "md" \| "lg" \| "xl" \| "2xl" | "md" | Square footprint: 32px / 40px / 48px for rows; 96px / 160px for portraits (a profile header, an artist hero, a roster tile). The initials, a status indicator and its cut-out ring scale with it, and at the portrait sizes the photo fades in over the resting surface. |
 | variant | "neutral" \| "art" | "neutral" | What the fallback looks like. neutral: initials on the muted surface. art: initials over GradientArt seeded by the person, so each person without a photo gets their own stable colour from the theme. |
 | seed | string \| number | — | The art variant's seed. Defaults to the fallback text, then `alt`, so a person keeps one colour wherever they appear; pass a user id to tell apart two people who share initials. |
 
 ## Variants
 
-- **size**: sm, md, lg
+- **size**: sm, md, lg, xl, 2xl
 - **variant**: neutral, art
 
 ## Tokens used
 
 `muted`, `muted-foreground`, `background`, `card`, `popover`, `overlay`, `overlay-foreground`
 
+## Motion
+
+- **arrival** · Image · `motion-fade` — At the portrait sizes (xl, 2xl) the photo replacing the initials is a visible pop across one of the page's largest elements; fading it in reads as the picture arriving, not the layout glitching. Row sizes swap instantly — too small to register, and a list of fading faces would shimmer.
+- **response** · Root · _no motion_ — An avatar is not interactive itself; a link or button wrapping it owns the response.
+- **transition** · Root · _no motion_ — It has no states of its own to move between beyond the image arriving.
+- **activity** · Root · _no motion_ — Loading shows the fallback, which is already a finished resting state rather than a spinner.
+
 ## Accessibility
 
 - Base UI tracks the image loading status and swaps to the fallback on missing/loading/error — no manual onError wiring.
@@ -112,6 +120,20 @@ import { Avatar } from "@sableui/react"
 <Avatar src="/pfp.png" alt="Alex Morgan" fallback="AM" size="lg" />
 ```
 
+### Profile portrait
+
+```tsx
+import { Avatar, StatusDot } from "@sableui/react"
+
+<div className="flex flex-col items-center gap-3 text-center">
+	<Avatar variant="art" size="2xl" fallback="LV" alt="Lena Vale" status={<StatusDot tone="success" />} />
+	<div className="flex flex-col gap-1">
+		<h1 className="text-heading-1">Lena Vale</h1>
+		<p className="text-body-sm text-muted-foreground">1.2M monthly listeners</p>
+	</div>
+</div>
+```
+
 ### Low-level parts
 
 ```tsx

package/llms/components/button.md

@@ -4,7 +4,7 @@
 
 Pill-shaped action primitive (theme-driven radius via --button-radius, defaults to full). Neutral tiers (primary/secondary/ghost/outline), plus destructive and link, and three on-color tiers (on-color/on-color-outline/on-color-ghost) that paint with the surrounding ink so a button reads on any tone or brand fill. Optional loading state shows a spinner and disables the button.
 
-**Keywords:** button, action, cta, submit, save, cancel, destructive, loading, link, icon button, on color, inverse, band, brand fill, tone fill
+**Keywords:** button, action, cta, submit, save, cancel, destructive, loading, link, icon button, on color, inverse, band, brand fill, tone fill, bleed, optical alignment, align label to edge, negative margin, view all
 
 ## Usage
 
@@ -16,7 +16,9 @@ Use Button when the user commits an action, submits a form, opens UI, or confirm
 - Do: Write labels as actions, such as "Save changes" or "Delete draft", instead of vague labels like "OK".
 - Do: Use loading with loadingLabel for async work so the action cannot double-fire and the state is announced.
 - Do: Put icons in iconStart / iconEnd rather than as children, so the button applies its optical padding. Start icons say what the action is (plus, share); end icons say where it goes (chevron-right, external).
+- Do: Set bleed on a ghost or link button that sits at the start or end of a row, so its LABEL lines up with the content edge the row shares ("View all" over a grid, "Add task" under a list, "Resend code" at a card footer's end). The box moves out by exactly its own padding; the hit area and hover fill stay full size and run past the edge. SectionHeader, PageHeader (back and actions) and CardAction already do this for their outermost ghost/link child — don't add it there, and use bleed="none" to opt one out.
 - Do: On a coloured fill — a solid Banner, a bg-tone-* or bg-primary band, an inverse (bg-foreground) section, a brand panel — use variant="on-color" for the main action and on-color-outline / on-color-ghost for the rest. They paint with the band's inherited ink (currentColor), so the surface must set its paired ink (text-tone-info-foreground, text-primary-foreground, text-background…), which it already should. Name the fill once on the surface, e.g. [--on-color-fill:var(--tone-info)], and the solid button's label takes the fill colour; unnamed, it falls back to black or white against the ink. Both clear 4.5:1 in every shipped theme and mode.
+- Don't: Pull a ghost button onto an edge with -ms-3 / -me-3 classNames. That number is one size's padding: it is wrong at xs, md and cta, wrong on a side carrying an icon, and wrong once a preset retunes the spacing. bleed reads the button's own padding var. And don't bleed a filled or outlined button — its visible edge is what aligns, so bleed is a no-op there.
 - Don't: Use destructive for reversible or low-risk actions; reserve it for operations with real loss or danger.
 - Don't: Use a button for plain navigation. Compose with render={<a />} when the element should behave like a link.
 - Don't: Use secondary on a tinted surface — inside a Note, a soft Banner, or any tone fill. `secondary` is a near-background surface token (in some themes within 2% of the page), so on a tint it reads as a hole punched in the fill rather than as a control sitting on it. On a soft tint use outline or ghost; on a full-strength fill use the on-color tiers.
@@ -43,6 +45,7 @@ Use Button when the user commits an action, submits a form, opens UI, or confirm
 | loadingLabel | ReactNode | — | Optional text shown in place of children while loading. |
 | iconStart | ReactNode | — | Icon before the label. The button takes one 2px step off its start padding so icon + label read as centred. Replaced by the spinner while loading. |
 | iconEnd | ReactNode | — | Icon after the label (disclosure, external link, next). Same optical correction on the end side. |
+| bleed | "start" \| "end" \| "both" \| "none" | — | Optical alignment for a borderless button (ghost, link, on-color-ghost): a negative inline margin of exactly its own padding on that side — --button-px, or the icon side's optical padding when an icon sits there; an icon-only size bleeds by its inset to the glyph — so the label (or glyph) lands on the content edge. Hit area and hover/focus fill keep their full size. Logical sides, so it mirrors in RTL. A no-op on variants with a visible edge (primary, secondary, outline, destructive, floating, field, on-color, on-color-outline): a filled button aligns its edge, not its label. Unset, a borderless button renders data-bleed="auto" and SectionHeader, PageHeader and CardAction bleed it when it is their outermost child; none opts out. |
 
 ## Variants
 
@@ -68,6 +71,7 @@ Use Button when the user commits an action, submits a form, opens UI, or confirm
 - Use render={<a/>} for link semantics rather than onClick navigation.
 - On-color tiers replace the --ring focus ring with one drawn in the band's ink past a transparent 2px gap, so focus stays visible on any fill (ink-on-fill is the theme's own tested pair).
 - On-color contrast is measured in button.test.tsx for every shipped theme and mode on each tone, primary, destructive, success, highlight and inverse fill: solid label at rest and hover, and outline/ghost label on the hover wash, all at least 4.5:1.
+- bleed moves only the box, never the hit target: the full padded area stays clickable and the focus ring still draws around the whole button, past the content edge.
 - loading sets aria-busy and disables activation (disabled on a native button, aria-disabled on a render element) so the action can't double-fire.
 
 ## Related
@@ -174,6 +178,21 @@ import { Button, Icon } from "@sableui/react"
 <Button size="icon" variant="ghost" aria-label="Share"><Icon name="share" /></Button>
 ```
 
+### Optically aligned to the row's edges
+
+```tsx
+import { Button, Icon, Row, Stack } from "@sableui/react"
+
+<Stack gap={1.5}>
+  <Row justify="between">
+    <span className="text-title-md">Tasks</span>
+    <Button variant="ghost" size="sm" bleed="end">View all</Button>
+  </Row>
+  <span className="text-body-sm text-muted-foreground">Ship the release notes</span>
+  <Button variant="ghost" size="sm" bleed="start" iconStart={<Icon name="plus" />} className="self-start">Add task</Button>
+</Stack>
+```
+
 ### Icon button with an unread badge
 
 ```tsx

package/llms/components/card.md

@@ -36,7 +36,7 @@ Use Card for a discrete thing with its own boundary, such as one product, one no
 | CardHeader | ComponentPropsWithRef<"div"> | Top section holding CardTitle/CardDescription (and optionally CardAction). Padding follows the density knob. |
 | CardTitle | ComponentPropsWithRef<"div"> & { render?: useRender.RenderProp } | The card's name (text-title-lg). A div by default; pass `render={<h2 />}` (or h3…) to make it a heading in the page outline, at the level the card's position calls for. |
 | CardDescription | ComponentPropsWithRef<"div"> | Muted supporting line under the title. |
-| CardAction | ComponentPropsWithRef<"div"> | Header-aligned top-right action slot (e.g. an overflow menu, switch, or close button). Place inside CardHeader, which becomes a 2-column grid when present and collapses to a single column otherwise. |
+| CardAction | ComponentPropsWithRef<"div"> | Header-aligned top-right action slot (e.g. an overflow menu, switch, or close button). Place inside CardHeader, which becomes a 2-column grid when present and collapses to a single column otherwise. A ghost or link Button that ends the slot bleeds by its own padding at the end, so a "View all" label or a "⋯" glyph sits on the card's content edge; filled buttons keep their edge there. |
 | CardContent | ComponentPropsWithRef<"div"> & { flush?: boolean } | The body region. Padding follows the density knob on all sides — does not assume a preceding CardHeader, so it is safe to use standalone (e.g. no CardHeader in the card). When paired with CardHeader, the seam stays tight because CardHeader zeroes its own bottom padding. `flush` runs it edge to edge for a table: the Table insets its first and last columns by exactly the card padding, so it lines up with the header — never hand-set pl-6/pr-6 on columns. |
 | CardList | ComponentPropsWithRef<"div"> | Rows that run edge to edge in the card (Entity rows, most often), divided by hairlines. Insets each row to the card's own padding, so a list card lines up with every other card at any density — no hand-tuned px-* on the rows. Under a CardHeader it opens with a hairline and a gap; alone it fills the card. |
 | CardFooter | ComponentPropsWithRef<"div"> & { actions?: boolean } | Bottom row for actions/meta. Padding follows the density knob. `actions` marks it as the card's action row (buttons only): in a sheet (IosSheet, a bottom SheetContent) it becomes a full-width stack pinned to the bottom, primary on top; on a page nothing changes. |