themelia-ui 2.0.0 → 3.0.0

package/docs/generated/components/base--cards.md

@@ -20,7 +20,7 @@ import "themelia-ui/base/cards.css"
 
 ## Composition
 
-This family composes `base/action-menu`, `base/buttons`, `base/feedback`, `base/skeleton`, `base/structure`, `base/tooltip`, `base/typography`.
+This module composes `base/action-menu`, `base/buttons`, `base/feedback`, `base/skeleton`, `base/structure`, `base/tooltip`, `base/typography`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -31,6 +31,10 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: callable.
 
+The single surface primitive. Slot props (`title`, `description`, `actions`, `footerText`,
+…) cover the common shape; `CardHeader`, `CardContent` and `CardFooter` are exported for
+composing.
+
 **Use when:** A bounded surface with a coordinated header, body and footer.
 
 **Avoid when:** Only grouping content within an existing surface or temporarily interrupting a task.
@@ -57,6 +61,9 @@ ActionDefinition
 
 Kind: callable.
 
+A card's commands as buttons. One array decides which action is primary and how the rest
+follow, so a page of cards cannot disagree about it.
+
 ```text
 ({ actions, separator, align, fullWidthPrimary, renderLink, className, ...props }: CardActionStripProps) => import("react").JSX.Element | null
 ```
@@ -69,11 +76,11 @@ Extends: `Omit<ComponentProps<"div">, "children">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `actions` | yes | `ActionDefinition[]` |  |
-| `separator` | no | `boolean` | A rule above the strip, for a card whose content runs right into it. |
-| `align` | no | `"start" \| "end" \| "between"` |  |
-| `fullWidthPrimary` | no | `boolean` | Stretches the first action, for a narrow card where two buttons will not fit. |
-| `renderLink` | no | `ActionLinkRenderer` | Routes `href` actions through the app's router. |
+| `actions` | yes | `ActionDefinition[]` | The commands, as the overflow menu takes them. The first is the primary action; the rest<br>follow in outline unless an entry sets its own `buttonStyle`. |
+| `separator` | no | `boolean` | A rule above the strip, ruling it off from content that runs right into it. |
+| `align` | no | `"start" \| "end" \| "between"` | Where the buttons sit along the strip. |
+| `fullWidthPrimary` | no | `boolean` | Stretches the first action, for a card whose action is the point, or a narrow card where<br>two buttons will not fit. |
+| `renderLink` | no | `LinkRenderer` | Routes `href` actions through the app's router. |
 
 ### `CardAlertTone`
 
@@ -116,8 +123,9 @@ above. The title truncates rather than pushing the controls off the row.
 
 Kind: callable.
 
-Makes a whole card one target with a covering link (wrapping the card would nest its
-controls inside an anchor). Interactive children are lifted above it in CSS.
+Stretches an anchor across the whole card, so the card is one tab stop rather than a grid
+of them (wrapping the card would nest its controls inside an anchor). Interactive children
+are lifted above it in CSS.
 
 ```text
 ({ label, className, ...props }: CardPrimaryActionProps) => import("react").JSX.Element
@@ -127,11 +135,11 @@ controls inside an anchor). Interactive children are lifted above it in CSS.
 
 Kind: interface.
 
-Extends: `ComponentProps<"a">`.
+Extends: `ComponentProps<"a">`, `Pick<ComponentProps<"a">, "href">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `label` | yes | `string` | Names the target. The card's own title is not enough — many cards share one. |
+| `label` | yes | `string` | The link's accessible name. The visible title is not necessarily the destination, and<br>many cards share one. |
 
 ### `CardProps`
 
@@ -142,35 +150,39 @@ Extends: `Omit<React.ComponentProps<"div">, "title">`.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `icon` | no | `React.ReactNode` | Leading glyph on the title line. |
-| `title` | no | `React.ReactNode` |  |
+| `title` | no | `React.ReactNode` | Header copy. The title truncates rather than pushing header controls off the row. |
 | `titleSuffix` | no | `React.ReactNode` | Badges, status, or counts immediately after the title. |
-| `tooltip` | no | `React.ReactNode` | Explanatory copy behind a focusable info button on the title line — for a definition or<br>caveat too long for the description. |
-| `description` | no | `React.ReactNode` |  |
-| `surface` | no | `CardSurface` | Outer chrome. |
+| `tooltip` | no | `React.ReactNode` | Explanatory copy behind an info button on the title line — for a definition or caveat<br>too long for the description. A real focusable button, not a `title` attribute;<br>`strings.tooltip` names it. |
+| `description` | no | `React.ReactNode` | Header copy under the title. |
+| `surface` | no | `CardSurface` | Outer chrome. `framed`, the bezel, is the default; `card` is the plain panel. Change it<br>for a whole product once with `UIProvider` `defaults.card.surface`. @default "framed" |
 | `headerStart` | no | `React.ReactNode` | Full-width row above the title — an eyebrow or breadcrumb. Rare. |
 | `headerEnd` | no | `React.ReactNode` | Metadata or a secondary control before the action and overflow menu. |
 | `headerAction` | no | `React.ReactNode` | A single control at the end of the header. Use `actions` for a list of commands. |
-| `actions` | no | `CardAction[]` | Overflow commands, collapsed into one menu trigger. |
-| `titleLevel` | no | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | Renders the title as a heading of this level. Unset, the title is a span that heading<br>navigation can't find; set it when the card titles a page section. |
-| `media` | no | `React.ReactNode` | A full-bleed strip above the header — a cover image, an illustration, a preview. |
-| `alert` | no | `React.ReactNode` | Banner between header and content. A plain string is wrapped for you. |
-| `alertTone` | no | `CardAlertTone` |  |
-| `contentTop` | no | `React.ReactNode` |  |
-| `contentBottom` | no | `React.ReactNode` |  |
+| `actions` | no | `CardAction[]` | Overflow commands, collapsed into one menu trigger and rendered by the shared<br>`ActionMenu`: a destructive entry moves last and is separated. |
+| `titleLevel` | no | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | Renders the title as a heading of this level, for a card that heads a page or a region.<br>Unset, the title is a span that heading navigation can't find. |
+| `media` | no | `React.ReactNode` | A full-bleed strip above the header — a cover image, a map, a brand band — clipped to<br>the card's top corners. |
+| `alert` | no | `React.ReactNode` | Banner between header and content. A plain string is wrapped in an `Alert`. |
+| `alertTone` | no | `CardAlertTone` | Tone of the alert band. |
+| `contentTop` | no | `React.ReactNode` | Content inside the content inset, above `children`. |
+| `contentBottom` | no | `React.ReactNode` | Content inside the content inset, below `children`. |
 | `footerText` | no | `React.ReactNode` | Muted text in the footer band. |
 | `footerSlot` | no | `React.ReactNode` | Footer band under the content — a single primary action fits well here. |
-| `headerDivider` | no | `boolean` |  |
-| `footerDivider` | no | `boolean` |  |
+| `headerDivider` | no | `boolean` | A rule between the header and the content. `UIProvider` defaults can change it. @default false |
+| `footerDivider` | no | `boolean` | A rule between the content and the footer. @default false |
 | `expandable` | no | `boolean \| { collapsedMaxHeight?: number \| string; }` | Clips content to a collapsed height with a fade, and adds a toggle. `true` uses<br>`--card-collapsed-height`; the object form sets the height for this card only. |
-| `expanded` | no | `boolean` |  |
-| `defaultExpanded` | no | `boolean` |  |
-| `onExpandedChange` | no | `(expanded: boolean) => void` |  |
-| `strings` | no | `Partial<CardStrings>` | Overrides this card's own copy — the info glyph, the overflow trigger, the disclosure. |
+| `expanded` | no | `boolean` | Whether an expandable card's content is expanded, for controlled expansion. |
+| `defaultExpanded` | no | `boolean` | Whether an expandable card starts expanded, for uncontrolled expansion. |
+| `onExpandedChange` | no | `(expanded: boolean) => void` | Called with the new state when the reader expands or collapses the content. |
+| `strings` | no | `Partial<CardStrings>` | Overrides this card's own copy — the info glyph, the overflow trigger, and the<br>disclosure control's name in each state. |
 
 ### `CardSkeleton`
 
 Kind: callable.
 
+A placeholder that reserves the real card's box, so the page doesn't reflow when content
+lands. Matching the surface and the line count is the whole job: a placeholder of the wrong
+shape moves the page twice.
+
 ```text
 ({ surface, showHeader, lines, label, className, ...props }: CardSkeletonProps) => import("react").JSX.Element
 ```
@@ -183,10 +195,10 @@ Extends: `Omit<ComponentProps<"div">, "title">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `surface` | no | `CardSurface` | Match the real card's surface. Unset, it takes the card's default (the provider's<br>`defaults.card.surface`, framed out of the box). |
+| `surface` | no | `CardSurface` | Match the real card's surface. Unset, it takes the card's default (the provider's<br>`defaults.card.surface`, framed out of the box). @default "framed" |
 | `showHeader` | no | `boolean` | Reserves the header's height. |
-| `lines` | no | `number` |  |
-| `label` | no | `string` |  |
+| `lines` | no | `number` | Lines of content to reserve. Match the real card's. |
+| `label` | no | `string` | What the placeholder announces while it waits. Unset, the skeleton's own loading copy. |
 
 ### `CardStrings`
 
@@ -217,80 +229,291 @@ Kind: const.
 CardStrings
 ```
 
+### `LinkRenderer`
+
+Kind: type.
+
+How a component renders a link: through the application's router. Every component that
+navigates takes one as `renderLink`, and without one renders a plain anchor. Return one
+element: the component may merge its own props into it, such as a menu item's role or a
+button's styling.
+
+```tsx fragment — declaration JSDoc excerpt
+const renderLink: LinkRenderer = ({ href, children, active, disabled, external, ...rest }) =>
+  disabled || !href ? <span {...rest}>{children}</span> : <Link to={href} {...rest}>{children}</Link>
+```
+
+```text
+(props: LinkRenderProps) => ReactElement
+```
+
+### `LinkRenderProps`
+
+Kind: interface.
+
+What a component hands its link renderer. Spread everything but `active`, `disabled` and `external` onto the element.
+
+| member | required | type | description / documented default |
+| --- | :-: | --- | --- |
+| `href` | no | `string` | Destination. When absent, render non-interactive content. |
+| `children` | yes | `ReactNode` |  |
+| `className` | no | `string` |  |
+| `target` | no | `string` |  |
+| `rel` | no | `string` |  |
+| `onClick` | no | `(event: MouseEvent<HTMLAnchorElement>) => void` |  |
+| `"aria-label"` | no | `string` |  |
+| `"aria-current"` | no | `AriaAttributes["aria-current"]` |  |
+| `"aria-disabled"` | no | `AriaAttributes["aria-disabled"]` |  |
+| `active` | no | `boolean` | Hint for active styling. A renderer may ignore it — the component styles the row itself. |
+| `disabled` | no | `boolean` | The entry goes nowhere: render non-interactive content. |
+| `external` | no | `boolean` | Opens elsewhere: the default renderer adds `target="_blank"` and `rel="noopener noreferrer"`. |
+
 ## Preview recipes
 
-Preview route: Card — `/card`
+Preview route: Action menu & buttons — `/action-menu`
+
+### In a card header
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { LogOutIcon, PencilIcon, TrashIcon } from "lucide-react"
+
+import { Card } from "themelia-ui/base/cards"
+import { Text } from "themelia-ui/base/typography"
+
+export default function MenusInContext() {
+	return (
+		<Card
+			surface="bordered"
+			title="Northwind Traders"
+			description="Customer since 2019"
+			actions={[
+				{ label: "Edit", icon: PencilIcon, onClick: () => {} },
+				{ label: "Sign out of all sessions", icon: LogOutIcon, onClick: () => {}, group: true },
+				{ label: "Delete customer", icon: TrashIcon, onClick: () => {}, tone: "destructive" },
+			]}
+			style={{ maxWidth: "26rem" }}
+		>
+			<Text size="sm" type="secondary">
+				The header menu is an ActionMenu — the card passes its actions straight through.
+			</Text>
+		</Card>
+	)
+}
+```
 
 ### Surfaces
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Card surface="framed" title="Revenue" description="Last 30 days" />
+import { Card, type CardSurface } from "themelia-ui/base/cards"
+import { Grid } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+const SURFACES: CardSurface[] = ["card", "framed", "flat", "bordered"]
+
+export default function CardSurfaces() {
+	return (
+		/* Two columns for four surfaces, so none sits alone on a row. */
+		<Grid columns={{ base: 1, sm: 2 }} gap="lg" style={{ width: "100%" }}>
+			{SURFACES.map((surface) => (
+				<Card key={surface} surface={surface} title={surface} description="Supporting sentence.">
+					<Text type="secondary" size="sm">
+						Card content.
+					</Text>
+				</Card>
+			))}
+		</Grid>
+	)
+}
 ```
 
 ### Slots
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Card
-  icon={<CreditCardIcon />}
-  title="Primary card"
-  titleSuffix={<Badge>Default</Badge>}
-  description="Visa ending 4242"
-  actions={[
-    { label: "Edit", onClick: … },
-    { label: "Remove", onClick: …, tone: "destructive" },
-  ]}
-  footerText="Updated 3 days ago"
-  footerSlot={<Button>Manage</Button>}
-/>
+import { CreditCardIcon, PencilIcon, StarIcon, TrashIcon } from "lucide-react"
+
+import { Badge } from "themelia-ui/base/badge"
+import { Button } from "themelia-ui/base/buttons"
+import { Card } from "themelia-ui/base/cards"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+
+export default function CardSlots() {
+	return (
+		<Stack gap="lg" style={{ maxWidth: "34rem", width: "100%" }}>
+			<Card
+				icon={<CreditCardIcon />}
+				title="Primary payment method"
+				titleSuffix={<Badge tone="neutral">Default</Badge>}
+				description="Visa ending 4242, expires 09/28"
+				headerDivider
+				actions={[
+					{ label: "Edit", icon: <PencilIcon />, onClick: () => {} },
+					{ label: "Set as default", icon: <StarIcon />, onClick: () => {} },
+					{ label: "Remove", icon: <TrashIcon />, onClick: () => {}, tone: "destructive" },
+				]}
+				footerText="Updated 3 days ago"
+				footerSlot={<Button tone="neutral" buttonStyle="outline">Manage</Button>}
+				footerDivider
+			>
+				<Text type="secondary" size="sm">
+					Charged on the first of each month.
+				</Text>
+			</Card>
+
+			<Card
+				title="With an alert"
+				description="A banner sits between the header and the content."
+				alert="Your card expires next month."
+				alertTone="warning"
+			>
+				<Text type="secondary" size="sm">
+					Content follows the banner.
+				</Text>
+			</Card>
+		</Stack>
+	)
+}
 ```
 
 ### Expandable
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Card expandable title="Terms">…</Card>
+import { Card } from "themelia-ui/base/cards"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+
+export default function CardExpandable() {
+	return (
+		<Card expandable title="Terms of service" style={{ maxWidth: "34rem", width: "100%" }}>
+			<Stack gap="md">
+				{Array.from({ length: 10 }, (_, i) => (
+					<Text key={i} type="secondary" size="sm">
+						Clause {i + 1}. Content that runs past the collapsed height, so the fade has
+						something to fade.
+					</Text>
+				))}
+			</Stack>
+		</Card>
+	)
+}
 ```
 
-### One card primitive
+### Header slots
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Card
-  icon={<CreditCardIcon />}
-  title="Payment method"
-  titleSuffix={<Badge tone="success">Verified</Badge>}
-  tooltip="We store only the last four digits."
-  headerAction={<Button buttonStyle="ghost" tone="neutral">Change</Button>}
-  description="Charged on the first of the month."
-/>
+import { CreditCardIcon } from "lucide-react"
+
+import { Badge } from "themelia-ui/base/badge"
+import { Button } from "themelia-ui/base/buttons"
+import { Card } from "themelia-ui/base/cards"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+
+export default function CardHeaderSlots() {
+	return (
+		<Stack gap="lg" style={{ maxWidth: "34rem", width: "100%" }}>
+			<Card
+				icon={<CreditCardIcon />}
+				title="Payment method"
+				titleSuffix={<Badge tone="success">Verified</Badge>}
+				tooltip="We store only the last four digits. The full number never reaches our servers."
+				headerAction={
+					<Button buttonStyle="ghost" tone="neutral">
+						Change
+					</Button>
+				}
+				description="Charged on the first of the month."
+				headerDivider
+				footerText="Next charge 1 April"
+				footerSlot={<Button buttonStyle="outline" tone="neutral">Invoices</Button>}
+				footerDivider
+			>
+				<Text size="sm" type="secondary">
+					Visa ending 4417.
+				</Text>
+			</Card>
+		</Stack>
+	)
+}
 ```
 
 ### Alert band
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Card title="Domain" alert="Verification expires in 3 days." alertTone="warning" />
+import { Card } from "themelia-ui/base/cards"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+
+export default function CardAlert() {
+	return (
+		<Stack gap="lg" style={{ maxWidth: "34rem", width: "100%" }}>
+			<Card title="Domain" alert="Verification expires in 3 days." alertTone="warning">
+				<Text size="sm" type="secondary">
+					acme.com
+				</Text>
+			</Card>
+			<Card title="Billing" alert="Payment failed." alertTone="destructive">
+				<Text size="sm" type="secondary">
+					We will retry in 24 hours.
+				</Text>
+			</Card>
+		</Stack>
+	)
+}
 ```
 
 ### Actions, and the whole card as one
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Card>
-  <CardContent>…</CardContent>
-  <CardFooter>
-    <CardActionStrip actions={[{ id: "open", label: "Open" }, { id: "archive", label: "Archive" }]} />
-  </CardFooter>
-</Card>
-
-// Or the whole card as one link. The card becomes the anchor's containing
-// block on its own, and a control inside it still takes its own clicks.
-<Card title="Northwind Traders">
-  <CardPrimaryAction href="/invoices/4417" label="Open Northwind Traders" />
-  <CardFooter>
-    <TextLink href="/invoices/4417.pdf">View the invoice instead</TextLink>
-  </CardFooter>
-</Card>
+import { Card, CardActionStrip, CardFooter, CardPrimaryAction } from "themelia-ui/base/cards"
+import { Stack } from "themelia-ui/base/structure"
+import { TextLink } from "themelia-ui/base/typography"
+
+export default function CardActions() {
+	return (
+		<Stack direction="horizontal" gap="lg" wrap align="start">
+			<Card style={{ width: "18rem" }} title="Northwind Traders" description="Invoice #4417">
+				<CardFooter>
+					<CardActionStrip
+						actions={[
+							{ id: "open", label: "Open" },
+							{ id: "archive", label: "Archive" },
+						]}
+					/>
+				</CardFooter>
+			</Card>
+			<Card style={{ width: "18rem" }} title="A card that is one link" description="The whole surface is the target.">
+				<CardPrimaryAction href="#card-actions" label="Open Northwind Traders" />
+				{/* An unpositioned TextLink, not a Button (already `position: relative`), so it exercises the lifting rule. */}
+				<CardFooter>
+					<TextLink href="#card-skeleton">View the invoice instead</TextLink>
+				</CardFooter>
+			</Card>
+		</Stack>
+	)
+}
 ```
 
 ### CardSkeleton
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<CardSkeleton surface="bordered" showHeader lines={3} />
+import { CardSkeleton } from "themelia-ui/base/cards"
+import { Stack } from "themelia-ui/base/structure"
+
+export default function CardSkeletonExample() {
+	return (
+		<Stack direction="horizontal" gap="lg" wrap align="start">
+			<div style={{ width: "18rem" }}>
+				<CardSkeleton showHeader lines={3} label="Loading invoice" />
+			</div>
+			<div style={{ width: "18rem" }}>
+				<CardSkeleton surface="bordered" lines={2} label="Loading summary" />
+			</div>
+		</Stack>
+	)
+}
 ```

package/docs/generated/components/base--carousel.md

@@ -20,7 +20,7 @@ import "themelia-ui/base/carousel.css"
 
 ## Composition
 
-This family composes `base/buttons`.
+This module composes `base/buttons`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -31,6 +31,9 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: callable.
 
+A native scroll-snap track with controls. Script only reports the current slide and
+scrolls to a chosen one.
+
 ```text
 ({ children, orientation, controls, showDots, dotStyle, strings, label, className, viewportClassName, ...props }: CarouselProps) => import("react").JSX.Element
 ```
@@ -39,7 +42,8 @@ Kind: callable.
 
 Kind: callable.
 
-A previous/next control placed by the caller rather than by the root.
+A single previous/next control placed by the caller rather than by the root, for composing
+your own layout with `controls="none"`. Must sit inside a `Carousel`.
 
 ```text
 ({ direction, className, children, ...props }: CarouselControlProps) => import("react").JSX.Element
@@ -63,13 +67,14 @@ Extends: `ComponentProps<"button">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `direction` | yes | `"previous" \| "next"` |  |
+| `direction` | yes | `"previous" \| "next"` | Which way the control moves the track. |
 
 ### `CarouselDots`
 
 Kind: callable.
 
-The position indicators, placed by the caller.
+The position indicators on their own, placed by the caller outside the track. Must sit
+inside a `Carousel`.
 
 ```text
 ({ dotStyle, className, ...props }: CarouselDotsProps) => import("react").JSX.Element
@@ -83,7 +88,7 @@ Extends: `ComponentProps<"div">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `dotStyle` | no | `"dot" \| "pill"` |  |
+| `dotStyle` | no | `"dot" \| "pill"` | `pill` stretches the active indicator instead of only recolouring it. |
 
 ### `CarouselOrientation`
 
@@ -101,19 +106,21 @@ Extends: `Omit<ComponentProps<"div">, "children">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `children` | yes | `ReactNode` |  |
-| `orientation` | no | `CarouselOrientation` |  |
-| `controls` | no | `CarouselControlPlacement` |  |
+| `children` | yes | `ReactNode` | The slides, usually `CarouselSlide`s. |
+| `orientation` | no | `CarouselOrientation` | Which axis snaps. |
+| `controls` | no | `CarouselControlPlacement` | Where the previous/next buttons sit: `outside` the track, `overlay` on its edges, or<br>`none` when you compose your own with `CarouselControl`. |
 | `showDots` | no | `boolean` | Shows the position indicators, and lets them be clicked. |
-| `dotStyle` | no | `"dot" \| "pill"` |  |
-| `strings` | no | `Partial<CarouselStrings>` | Overrides this carousel's own copy — the region name and the two controls. |
-| `label` | no | `string` |  |
-| `viewportClassName` | no | `string` |  |
+| `dotStyle` | no | `"dot" \| "pill"` | `pill` stretches the active indicator instead of only recolouring it. |
+| `strings` | no | `Partial<CarouselStrings>` | Overrides this carousel's own copy — the region name, the two icon-only controls, and<br>each pagination dot. It travels through the context, so a control placed with<br>`CarouselControl` is named by the same override as one the root rendered. |
+| `label` | no | `string` | Names the region for assistive technology; unset, `strings.label` does. A carousel with<br>no name is an unexplained scroll box, and a page with two needs two names. |
+| `viewportClassName` | no | `string` | Styles the scroll container rather than the outer frame — for a carousel that needs its<br>own padding inside the clip. |
 
 ### `CarouselSlide`
 
 Kind: callable.
 
+One slide of the track, announced as a slide.
+
 ```text
 ({ size, className, style, ...props }: CarouselSlideProps) => import("react").JSX.Element
 ```
@@ -153,6 +160,9 @@ CarouselStrings
 
 Kind: callable.
 
+The track's position, its slide count, and the scroll helpers, for a fully custom control
+surface. Must be called inside a `Carousel`.
+
 ```text
 () => { index: number; count: number; atStart: boolean; atEnd: boolean; scrollToSlide: (index: number) => void; strings: CarouselStrings; }
 ```
@@ -164,24 +174,74 @@ Preview route: Carousel — `/carousel`
 ### Carousel
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Carousel showDots dotStyle="pill" label="Recent invoices">
-  {invoices.map((name) => (
-    <CarouselSlide key={name} size="16rem">
-      <Card surface="bordered" title={name} />
-    </CarouselSlide>
-  ))}
-</Carousel>
+import { Card } from "themelia-ui/base/cards"
+import { Carousel, CarouselSlide } from "themelia-ui/base/carousel"
+import { Text } from "themelia-ui/base/typography"
+
+const INVOICES = ["Northwind", "Acme", "Globex", "Initech", "Umbrella"]
+
+export default function CarouselExample() {
+	return (
+		<Carousel showDots dotStyle="pill" label="Recent invoices">
+			{INVOICES.map((name) => (
+				<CarouselSlide key={name} size="16rem">
+					<Card surface="bordered" title={name} description="Invoice due in 14 days.">
+						<Text size="sm" type="secondary">
+							Slide content.
+						</Text>
+					</Card>
+				</CarouselSlide>
+			))}
+		</Carousel>
+	)
+}
 ```
 
 ### Control placement
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Carousel controls="overlay" label="Gallery">…</Carousel>
+import { Carousel, CarouselSlide } from "themelia-ui/base/carousel"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+import styles from "./controls.module.css"
+
+export default function Controls() {
+	return (
+		// Full-bleed slides: overlay controls float over the slide's edges.
+		<Carousel controls="overlay" label="Gallery">
+			{["One", "Two", "Three"].map((name) => (
+				<CarouselSlide key={name}>
+					<Stack align="center" justify="center" className={styles.slide}>
+						<Text size="lg" weight="semibold">{name}</Text>
+					</Stack>
+				</CarouselSlide>
+			))}
+		</Carousel>
+	)
+}
 ```
 
 ### Slide width
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<CarouselSlide size="50%">…</CarouselSlide>
-<CarouselSlide size="18rem">…</CarouselSlide>
+import { Card } from "themelia-ui/base/cards"
+import { Carousel, CarouselSlide } from "themelia-ui/base/carousel"
+import { Text } from "themelia-ui/base/typography"
+
+export default function Sizes() {
+	return (
+		<Carousel label="Two per view">
+			{["Half", "Half", "Half", "Half"].map((name, index) => (
+				<CarouselSlide key={index} size="50%">
+					<Card surface="bordered" title={`${name} ${index + 1}`}>
+						<Text size="sm" type="secondary">
+							Two slides fill the track.
+						</Text>
+					</Card>
+				</CarouselSlide>
+			))}
+		</Carousel>
+	)
+}
 ```