themelia-ui 2.0.0 → 3.0.0

package/.agents/skills/themelia-ui/references/components/base--cards.md

@@ -1,296 +0,0 @@
-<!-- GENERATED by scripts/gen-consumer-docs.mjs — do not edit. -->
-
-# `base/cards`
-
-A surface needs visible chrome — border, padding, header and footer regions.
-
-## Selection
-
-- **Use when:** A surface needs visible chrome — border, padding, header and footer regions.
-- **Avoid when:** You are framing reusable content that the call site should frame instead, or the rows are a list.
-- **Consider instead:** `base/item`, `base/structure`
-- **Stability:** stable.
-
-## Import
-
-```tsx fragment — import-only example
-import { Card } from "themelia-ui/base/cards"
-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`.
-
-Application policy—routing, fetching, persistence, permissions, and translation—stays
-outside the package and arrives through the public props, callbacks, slots, or accessors below.
-
-## Public declarations
-
-### `Card`
-
-Kind: callable.
-
-**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.
-
-**Compose:** Use CardHeader and CardContent rather than local title, description and inset styles.
-
-**Capabilities:** surface title description spacing; header body footer; card actions.
-
-**Alternatives:** ContentBlock, Overlay.
-
-```text
-({ icon, title, titleSuffix, tooltip, description, surface, titleLevel, media, headerStart, headerEnd, headerAction, actions, alert, alertTone, contentTop, contentBottom, footerText, footerSlot, headerDivider, footerDivider, expandable, expanded, defaultExpanded, onExpandedChange, strings, className, children, ...props }: CardProps) => React.JSX.Element
-```
-
-### `CardAction`
-
-Kind: type.
-
-```text
-ActionDefinition
-```
-
-### `CardActionStrip`
-
-Kind: callable.
-
-```text
-({ actions, separator, align, fullWidthPrimary, renderLink, className, ...props }: CardActionStripProps) => import("react").JSX.Element | null
-```
-
-### `CardActionStripProps`
-
-Kind: interface.
-
-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. |
-
-### `CardAlertTone`
-
-Kind: type.
-
-```text
-AlertTone
-```
-
-### `CardContent`
-
-Kind: callable.
-
-Content region. Owns the inset, and drops its top padding when a header precedes it.
-
-```text
-({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element
-```
-
-### `CardFooter`
-
-Kind: callable.
-
-```text
-({ divider, text, className, children, ...props }: React.ComponentProps<"div"> & { divider?: boolean; text?: React.ReactNode; }) => React.JSX.Element
-```
-
-### `CardHeader`
-
-Kind: callable.
-
-The header region: a title row with trailing controls, plus an optional full-width row
-above. The title truncates rather than pushing the controls off the row.
-
-```text
-({ icon, title, titleSuffix, tooltip, tooltipLabel, description, headerStart, headerEnd, headerAction, divider, titleLevel, className, ...props }: Omit<React.ComponentProps<"div">, "title"> & { icon?: React.ReactNode; title?: React.ReactNode; titleSuffix?: React.ReactNode; tooltip?: React.ReactNode; tooltipLabel?: string; description?: React.ReactNode; headerStart?: React.ReactNode; headerEnd?: React.ReactNode; headerAction?: React.ReactNode; divider?: boolean; titleLevel?: 1 | 2 | 3 | 4 | 5 | 6; }) => React.JSX.Element
-```
-
-### `CardPrimaryAction`
-
-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.
-
-```text
-({ label, className, ...props }: CardPrimaryActionProps) => import("react").JSX.Element
-```
-
-### `CardPrimaryActionProps`
-
-Kind: interface.
-
-Extends: `ComponentProps<"a">`.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `label` | yes | `string` | Names the target. The card's own title is not enough — many cards share one. |
-
-### `CardProps`
-
-Kind: interface.
-
-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` |  |
-| `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. |
-| `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` |  |
-| `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` |  |
-| `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. |
-
-### `CardSkeleton`
-
-Kind: callable.
-
-```text
-({ surface, showHeader, lines, label, className, ...props }: CardSkeletonProps) => import("react").JSX.Element
-```
-
-### `CardSkeletonProps`
-
-Kind: interface.
-
-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). |
-| `showHeader` | no | `boolean` | Reserves the header's height. |
-| `lines` | no | `number` |  |
-| `label` | no | `string` |  |
-
-### `CardStrings`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `tooltip` | yes | `string` | Accessible name for the info glyph beside the title. |
-| `actions` | yes | `string` | Accessible name for the overflow trigger in the header. |
-| `expand` | yes | `string` | The disclosure control's name in each state, when the card is expandable. |
-| `collapse` | yes | `string` |  |
-
-### `CardSurface`
-
-Kind: type.
-
-Outer chrome. `flat` is a card in structure only, for a region that must not look like a panel.
-
-```text
-"card" | "framed" | "flat" | "bordered"
-```
-
-### `defaultCardStrings`
-
-Kind: const.
-
-```text
-CardStrings
-```
-
-## Preview recipes
-
-Preview route: Card — `/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" />
-```
-
-### 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>}
-/>
-```
-
-### Expandable
-
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Card expandable title="Terms">…</Card>
-```
-
-### One card primitive
-
-```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."
-/>
-```
-
-### 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" />
-```
-
-### 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>
-```
-
-### CardSkeleton
-
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<CardSkeleton surface="bordered" showHeader lines={3} />
-```

package/.agents/skills/themelia-ui/references/components/base--carousel.md

@@ -1,187 +0,0 @@
-<!-- GENERATED by scripts/gen-consumer-docs.mjs — do not edit. -->
-
-# `base/carousel`
-
-Peer items exceed the width and horizontal paging is the intended reading order.
-
-## Selection
-
-- **Use when:** Peer items exceed the width and horizontal paging is the intended reading order.
-- **Avoid when:** All items should be visible at once, or the overflow is a tab strip.
-- **Consider instead:** `base/structure`, `base/navigation`
-- **Stability:** stable.
-
-## Import
-
-```tsx fragment — import-only example
-import { Carousel } from "themelia-ui/base/carousel"
-import "themelia-ui/base/carousel.css"
-```
-
-## Composition
-
-This family 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.
-
-## Public declarations
-
-### `Carousel`
-
-Kind: callable.
-
-```text
-({ children, orientation, controls, showDots, dotStyle, strings, label, className, viewportClassName, ...props }: CarouselProps) => import("react").JSX.Element
-```
-
-### `CarouselControl`
-
-Kind: callable.
-
-A previous/next control placed by the caller rather than by the root.
-
-```text
-({ direction, className, children, ...props }: CarouselControlProps) => import("react").JSX.Element
-```
-
-### `CarouselControlPlacement`
-
-Kind: type.
-
-Where the previous/next controls sit. `overlay` floats them over the track's edges.
-
-```text
-"outside" | "overlay" | "none"
-```
-
-### `CarouselControlProps`
-
-Kind: interface.
-
-Extends: `ComponentProps<"button">`.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `direction` | yes | `"previous" \| "next"` |  |
-
-### `CarouselDots`
-
-Kind: callable.
-
-The position indicators, placed by the caller.
-
-```text
-({ dotStyle, className, ...props }: CarouselDotsProps) => import("react").JSX.Element
-```
-
-### `CarouselDotsProps`
-
-Kind: interface.
-
-Extends: `ComponentProps<"div">`.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `dotStyle` | no | `"dot" \| "pill"` |  |
-
-### `CarouselOrientation`
-
-Kind: type.
-
-```text
-"horizontal" | "vertical"
-```
-
-### `CarouselProps`
-
-Kind: interface.
-
-Extends: `Omit<ComponentProps<"div">, "children">`.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `children` | yes | `ReactNode` |  |
-| `orientation` | no | `CarouselOrientation` |  |
-| `controls` | no | `CarouselControlPlacement` |  |
-| `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` |  |
-
-### `CarouselSlide`
-
-Kind: callable.
-
-```text
-({ size, className, style, ...props }: CarouselSlideProps) => import("react").JSX.Element
-```
-
-### `CarouselSlideProps`
-
-Kind: interface.
-
-Extends: `ComponentProps<"div">`.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `size` | no | `string` | Track width this slide occupies — "100%", "50%", "18rem". |
-
-### `CarouselStrings`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `label` | yes | `string` | Names the region. A page with two carousels needs two names. |
-| `previous` | yes | `string` | The controls are icon-only, so these are the only names they have. |
-| `next` | yes | `string` |  |
-| `goToSlide` | yes | `(index: number) => string` | Accessible name for a pagination dot, by the slide it jumps to. |
-| `roleDescription` | yes | `string` | What the region and each slide are (`aria-roledescription`), announced before their name. |
-| `slideRoleDescription` | yes | `string` |  |
-
-### `defaultCarouselStrings`
-
-Kind: const.
-
-```text
-CarouselStrings
-```
-
-### `useCarousel`
-
-Kind: callable.
-
-```text
-() => { index: number; count: number; atStart: boolean; atEnd: boolean; scrollToSlide: (index: number) => void; strings: CarouselStrings; }
-```
-
-## Preview recipes
-
-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>
-```
-
-### Control placement
-
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Carousel controls="overlay" label="Gallery">…</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>
-```

package/.agents/skills/themelia-ui/references/components/base--chart.md

@@ -1,204 +0,0 @@
-<!-- GENERATED by scripts/gen-consumer-docs.mjs — do not edit. -->
-
-# `base/chart`
-
-Rendering a Recharts chart that must inherit the kit's tokens, legend and tooltip chrome.
-
-## Selection
-
-- **Use when:** Rendering a Recharts chart that must inherit the kit's tokens, legend and tooltip chrome.
-- **Avoid when:** The number is a single figure with a trend, or the chart needs a titled card frame.
-- **Consider instead:** `patterns/analytics`
-- **Stability:** stable.
-
-## Import
-
-```tsx fragment — import-only example
-import { ChartContainer } from "themelia-ui/base/chart"
-import "themelia-ui/base/chart.css"
-```
-
-## Optional peers
-
-Install these only when importing this family:
-
-```bash
-npm install recharts
-```
-
-## Composition
-
-This family has no component-family dependencies.
-
-Application policy—routing, fetching, persistence, permissions, and translation—stays
-outside the package and arrives through the public props, callbacks, slots, or accessors below.
-
-## Public declarations
-
-### `ChartConfig`
-
-Kind: type.
-
-Maps each data key to its label, colour, and icon.
-
-```text
-Record<string, ChartSeriesConfig>
-```
-
-### `ChartContainer`
-
-Kind: callable.
-
-```text
-({ config, label, description, className, children, style, ...props }: ChartContainerProps) => React.JSX.Element
-```
-
-### `ChartContainerProps`
-
-Kind: interface.
-
-Extends: `Omit<React.ComponentProps<"div">, "children">`.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `config` | yes | `ChartConfig` |  |
-| `children` | yes | `React.ComponentProps<typeof Recharts.ResponsiveContainer>["children"]` |  |
-| `label` | no | `string` | What the chart shows, as a sentence a screen reader can speak ("Monthly revenue against<br>expenses, January to June"). Without it the focusable plot is announced by its tick text. |
-| `description` | no | `string` | A longer summary of the data or its takeaway, read after the label. |
-
-### `ChartLegend`
-
-Kind: callable.
-
-```text
-({ itemSorter, ...props }: React.ComponentProps<typeof Recharts.Legend>) => React.JSX.Element
-```
-
-### `ChartLegendContent`
-
-Kind: callable.
-
-```text
-({ payload, hideIcon, nameKey, className, ...props }: ChartLegendContentProps) => React.JSX.Element | null
-```
-
-### `ChartLegendContentProps`
-
-Kind: interface.
-
-Extends: `React.ComponentProps<"div">`.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `payload` | no | `ChartPayloadItem[]` | Supplied by Recharts. |
-| `hideIcon` | no | `boolean` |  |
-| `nameKey` | no | `string` |  |
-
-### `ChartPayloadItem`
-
-Kind: interface.
-
-One entry of what is under the cursor. Shaped by Recharts, narrowed here.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `dataKey` | no | `string \| number` |  |
-| `name` | no | `string \| number` |  |
-| `value` | no | `string \| number \| (string \| number)[]` |  |
-| `color` | no | `string` |  |
-| `fill` | no | `string` |  |
-| `payload` | no | `Record<string, unknown>` |  |
-
-### `ChartSeriesConfig`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `label` | no | `React.ReactNode` | Shown in the tooltip and the legend in place of the raw data key. |
-| `icon` | no | `React.ComponentType` |  |
-| `color` | no | `string` | Any CSS colour. Prefer a theme token so the chart follows light and dark. |
-
-### `ChartTooltip`
-
-Kind: const.
-
-```text
-typeof Recharts.Tooltip
-```
-
-### `ChartTooltipContent`
-
-Kind: callable.
-
-```text
-({ active, payload, label, hideLabel, hideIndicator, indicator, nameKey, labelKey, labelFormatter, formatter, className, ...props }: ChartTooltipContentProps) => React.JSX.Element | null
-```
-
-### `ChartTooltipContentProps`
-
-Kind: interface.
-
-Extends: `Omit<React.ComponentProps<"div">, "color">`.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `active` | no | `boolean` | Supplied by Recharts. |
-| `payload` | no | `ChartPayloadItem[]` |  |
-| `label` | no | `React.ReactNode` |  |
-| `hideLabel` | no | `boolean` |  |
-| `hideIndicator` | no | `boolean` |  |
-| `indicator` | no | `"dot" \| "line" \| "dashed"` |  |
-| `nameKey` | no | `string` | Key in the payload holding each series name. |
-| `labelKey` | no | `string` | Key in the payload holding the tooltip label. |
-| `labelFormatter` | no | `(label: React.ReactNode, payload: ChartPayloadItem[]) => React.ReactNode` |  |
-| `formatter` | no | `(value: NonNullable<ChartPayloadItem["value"]>, name: NonNullable<ChartPayloadItem["name"]>, item: ChartPayloadItem, index: number) => React.ReactNode` |  |
-
-### `Sparkline`
-
-Kind: callable.
-
-```text
-({ data, tone, animated, label, className, ...props }: SparklineProps) => import("react").JSX.Element
-```
-
-### `SparklineProps`
-
-Kind: interface.
-
-Extends: `Omit<React.ComponentProps<"div">, "children">`.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `data` | yes | `readonly number[]` | The series, in chronological order. |
-| `tone` | no | `SemanticTone` | Colours the stroke and its fade. |
-| `animated` | no | `boolean` | Off by default: many sparklines animating at once reads as a malfunction. |
-| `label` | no | `string` | What the shape says. Without it the chart is decorative and hidden from readers. |
-
-## Preview recipes
-
-Preview route: Chart — `/chart`
-
-### Chart
-
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-const config = {
-  revenue: { label: "Revenue", color: "var(--chart-1)" },
-  expenses: { label: "Expenses", color: "var(--chart-2)" },
-} satisfies ChartConfig
-
-<ChartContainer config={config} label="Monthly revenue and expenses">
-  <BarChart data={data}>
-    <CartesianGrid vertical={false} />
-    <XAxis dataKey="month" tickLine={false} axisLine={false} />
-    <ChartTooltip content={<ChartTooltipContent />} />
-    <Bar dataKey="revenue" fill="var(--color-revenue)" radius={4} />
-  </BarChart>
-</ChartContainer>
-```
-
-### Sparkline
-
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Sparkline data={[4, 9, 6, 12, 10, 17, 15, 22]} tone="success" label="Revenue, last eight weeks" />
-```