themelia-ui 1.0.3 → 2.0.0

package/.agents/skills/themelia-ui/references/components/INDEX.md

@@ -84,7 +84,6 @@ snapshot, the architecture manifest, selection guidance, and the live preview re
 | `features/rich-text-editor` | features | general | [API](./features--rich-text-editor.md) |
 | `features/rich-text-editor/tiptap` | features | general | [API](./features--rich-text-editor--tiptap.md) |
 | `features/schema-form` | features | general | [API](./features--schema-form.md) |
-| `features/suggestions` | features | general | [API](./features--suggestions.md) |
 | `features/sync` | features | general | [API](./features--sync.md) |
 | `features/table` | features | general | [API](./features--table.md) |
 | `features/theme-tweaker` | features | general | [API](./features--theme-tweaker.md) |

package/.agents/skills/themelia-ui/references/components/admin--patterns--access.md

@@ -70,11 +70,7 @@ Extends: `Omit<ComponentProps<"div">, "children" | "title" | "onCopy">`.
 
 Kind: interface.
 
-Copy owned by the admin blocks.
-
-The count formatter is a function rather than a template because pluralisation is not a
-suffix in most languages — "1 member" / "2 members" is an English rule, and a consumer
-replacing only the string cannot fix the rule from inside it.
+Copy owned by the admin blocks. Counts are functions, so a translation controls pluralisation.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
@@ -150,7 +146,7 @@ Kind: interface.
 | --- | :-: | --- | --- |
 | `editLabel` | yes | `string` |  |
 | `formatMemberCount` | yes | `(count: number) => string` |  |
-| `granted` | yes | `string` | Names each permission dot, which otherwise states its condition by colour alone. |
+| `granted` | yes | `string` | Announces a granted permission; the glyph beside it is decorative. |
 | `notGranted` | yes | `string` |  |
 
 ### `SensitiveAction`

package/.agents/skills/themelia-ui/references/components/admin--patterns--commerce.md

@@ -101,7 +101,7 @@ Extends: `Omit<ComponentProps<"div">, "children">`.
 | `label` | yes | `ReactNode` |  |
 | `amount` | yes | `string` | Already formatted, including its currency. |
 | `total` | no | `boolean` | Marks the row the eye should land on — a total, an amount due. |
-| `deduction` | no | `boolean` | Money coming off the total. Rewrites the sign rather than trusting the caller's, and<br>tints the figure, because a discount that reads like a charge is worse than no<br>discount line at all. |
+| `deduction` | no | `boolean` | Money coming off the total. Rewrites the sign rather than trusting the caller's, and tints the figure. |
 | `note` | no | `ReactNode` | A rate, a qualifier — sits quietly beside the label. |
 
 ### `Booking`
@@ -175,12 +175,8 @@ Kind: interface.
 
 Kind: interface.
 
-Copy owned by the commerce blocks.
-
-One file per domain rather than one per component: these surfaces sit on the same page
-as each other, and "Subtotal" appearing twice with two spellings is exactly what a
-shared dictionary prevents. Counts are functions — pluralisation is not a suffix outside
-English, and a consumer replacing only the noun cannot fix the rule around it.
+Copy owned by the commerce blocks: one dictionary for the domain, so shared words match.
+Counts are functions, so a translation controls pluralisation.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
@@ -518,10 +514,7 @@ Kind: interface.
 
 Kind: callable.
 
-Writes an amount as a deduction.
-
-An empty or blank value is returned untouched, so the caller's own empty handling still
-runs rather than being handed a bare minus sign.
+Writes an amount as a deduction. A blank value is returned untouched.
 
 ```text
 (value: string) => string
@@ -554,10 +547,10 @@ Extends: `Omit<ComponentProps<"div">, "children">`.
 | `status` | yes | `FulfillmentStatus` |  |
 | `location` | no | `ReactNode` | Where it ships from. |
 | `notice` | no | `ReactNode` | A standing fact about the group — "Shipping not required". |
-| `noticeIcon` | no | `LucideIcon` | The glyph beside the notice.<br><br>A prop rather than a node, because an icon passed as a child arrives with no size:<br>lucide's own default is 24px, which put a crossed circle in the header at the height<br>of three lines of the text it was annotating. |
+| `noticeIcon` | no | `LucideIcon` | The glyph beside the notice. A component, so the group sizes it. |
 | `items` | no | `OrderLine[]` |  |
 | `children` | no | `ReactNode` | Overrides `items` entirely, for a caller who needs the rows themselves. |
-| `actions` | no | `ActionDefinition[]` | The first renders as a button and the rest collapse into an overflow, built from one<br>array — which is what stops the menu offering what the button already does. |
+| `actions` | no | `ActionDefinition[]` | The first renders as a button; the rest collapse into an overflow menu. |
 | `strings` | no | `Partial<FulfillmentGroupStrings>` |  |
 | `vocabulary` | no | `Partial<OrderStatusVocabulary>` |  |
 
@@ -1016,7 +1009,7 @@ Kind: interface.
 | `imageAlt` | no | `string` |  |
 | `unitPrice` | yes | `string` | Already formatted, including its currency. |
 | `quantity` | yes | `number` |  |
-| `total` | yes | `string` | Already formatted. Passed, never multiplied — see the note above. |
+| `total` | yes | `string` | Already formatted. Passed, never multiplied. |
 | `properties` | no | `OrderLineProperty[]` | Rendered as label/value rows under the title, so every consumer's extras match. |
 | `children` | no | `ReactNode` | Whatever `properties` cannot express. |
 
@@ -1079,7 +1072,7 @@ Extends: `Omit<ComponentProps<typeof ContentBlock>, "children">`.
 | `status` | yes | `OrderStatus` |  |
 | `events` | yes | `OrderEvent[]` | Oldest first, so "latest complete" and "next" are found by position. |
 | `eta` | no | `string` | Already formatted. |
-| `defaultHistoryOpen` | no | `boolean` | Opens the full event list on first render.<br><br>Closed by default, because the panel above it already answers what just happened,<br>what is next and when it lands — which is what a reader opening an order wants. The<br>list underneath is the audit trail: five rows repeating two facts they have just read<br>and adding three they did not ask for. |
+| `defaultHistoryOpen` | no | `boolean` | Opens the full event list on first render. Closed by default: the panel above<br>already summarises it. |
 | `strings` | no | `Partial<OrderStatusStrings>` |  |
 
 ### `OrderStatusStrings`
@@ -1213,13 +1206,8 @@ Record<PaymentStatus, BadgeTone>
 
 Kind: type.
 
-Card networks and wallets.
-
-The brand is NAMED, never painted. Depicting one properly means its real trademark
-colours, which must not follow a consumer's theme — and this kit has no escape for that:
-`verify:composition` forbids a colour literal in any module, deliberately. So the card
-shows its brand as a word beside the last four digits, which is what identifies a card
-on an admin screen anyway. A consumer who wants the logo passes it as `icon`.
+Card networks and wallets. The brand is named, never painted: trademark colours would
+need literals `verify composition` forbids. Pass a logo as `icon`.
 
 ```text
 "visa" | "mastercard" | "amex" | "paypal" | "applePay" | "googlePay" | "unknown"
@@ -1369,7 +1357,7 @@ Kind: interface.
 | `status` | yes | `SeoCheckStatus` |  |
 | `score` | yes | `number` |  |
 | `maxScore` | yes | `number` |  |
-| `ratio` | no | `number` | The UNROUNDED fraction of this check that was earned, for anything showing a<br>percentage.<br><br>`score` is whole points, because a point total made of halves is not a point total —<br>and rounding it was erasing the very penalty it had just applied. A 61-character title<br>against a 60 cap scores 0.983, which is 29.5 of 30 points, which rounds to 30: the card<br>then drew "61 / 60" beside "100%", saying in one row both that the title is over the<br>limit and that nothing is wrong with it.<br><br>OPTIONAL, and that is not a detail. `calculateSeoScore` always sets it, so the kit's<br>own path is exact — but a consumer assembling a SeoCheck by hand is building a value<br>of this type, and a required field added to a type people CONSTRUCT is a breaking<br>change however additive it looks from inside. Absent, a reader falls back to the<br>rounded score, which is what it had before. |
+| `ratio` | no | `number` | The unrounded fraction earned, for percentages: `score` is rounded to whole points and<br>can hide a small penalty. Always set by `calculateSeoScore`; optional so hand-built<br>checks stay valid, and readers fall back to `score / maxScore`. |
 | `actual` | yes | `number` | The measured length, so a card can show "62 / 60". |
 | `min` | no | `number` |  |
 | `max` | no | `number` |  |
@@ -1378,15 +1366,9 @@ Kind: interface.
 
 Kind: type.
 
-How a listing's search presentation is scored.
-
-Pure functions with no React in them, exported so a consumer can score a draft while the
-user is still typing rather than only when the card renders it.
-
-The weights say what matters: title and description carry 30 points each because they
-are what a search result actually shows, the permalink 15, the slug and origin 10, and a
-target keyword 5 — and the keyword check only exists when a keyword was supplied, so an
-absent one does not drag the total down.
+Scores a listing's search presentation. Pure functions, so a draft can be scored while
+typing. Weights: title 30, description 30, permalink 15, slug 10, origin 10, and keyword
+5 only when a keyword is supplied.
 
 ```text
 "title" | "description" | "permalink" | "slug" | "url" | "keyword"
@@ -1431,7 +1413,7 @@ Extends: `Omit<ComponentProps<typeof ContentBlock>, "children" | "title">`.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `listing` | yes | `SeoScoreInput` | What the result will read as. |
-| `score` | no | `SeoScore` | A score computed elsewhere — by an editor scoring on every keystroke, say. Without<br>it this scores the listing itself. |
+| `score` | no | `SeoScore` | A score computed elsewhere (e.g. per keystroke by an editor). Without it, the listing is scored here. |
 | `onEdit` | no | `() => void` |  |
 | `strings` | no | `Partial<SeoStrings>` |  |
 

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

@@ -63,8 +63,7 @@ Kind: callable.
 
 Kind: interface.
 
-One section, for the bounded `items` API. For richer rows — multi-line metadata,
-custom layouts — drop to the compound parts and compose freely.
+One section for the bounded `items` API; use the compound parts for richer rows.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
@@ -88,8 +87,8 @@ AccordionPrimitive.Item.Props
 
 Kind: type.
 
-How leading media is framed. When no row supplies media the column is removed rather
-than left as an empty gutter; a mixed group keeps a placeholder so titles stay aligned.
+How leading media is framed. With no media in any row the column is dropped; a mixed
+group reserves it on every row so titles align.
 
 ```text
 "inline" | "medallion" | "none"
@@ -104,18 +103,15 @@ Extends: `AccordionPrimitive.Root.Props<string>`.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `surface` | no | `AccordionSurface` | Outer chrome. Resolves through the provider when omitted. |
-| `items` | no | `AccordionItemData[]` | Bounded sections. Renders the canonical icon/title/badge/description row, so the<br>common accordion is one prop rather than four nested elements per section. Ignored<br>when `children` are supplied. |
+| `items` | no | `AccordionItemData[]` | Bounded sections, each rendered as the canonical icon/title/badge/description row.<br>Ignored when `children` are supplied. |
 | `media` | no | `AccordionMedia` | How leading media is framed. Only meaningful alongside `items`. |
 
 ### `AccordionSurface`
 
 Kind: type.
 
-Outer chrome for the group.
-
-`bordered` — one cohesive shell with quiet row dividers. The settings-page default.
-`card`     — each section is its own panel. For genuinely independent sections.
-`flat`     — no chrome; the consumer supplies it.
+Outer chrome for the group: `bordered` — one shell with quiet dividers (the settings
+default); `card` — a panel per section; `flat` — none, the consumer supplies it.
 
 ```text
 "bordered" | "card" | "flat"

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

@@ -44,7 +44,7 @@ Kind: interface.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `actions` | yes | `readonly ActionDefinition[]` | The same definitions, side by side rather than collapsed into a menu. |
-| `max` | no | `number` | How many render as buttons before the remainder collapses into an overflow menu.<br><br>The menu is built from the SAME array, which is the point: a toolbar that hard-codes<br>its own overflow is how the menu ends up offering something the buttons already do.<br>Left unset, every definition is a button. |
+| `max` | no | `number` | How many render as buttons before the rest collapse into an overflow menu built from<br>the same array. Unset, every definition is a button. |
 | `strings` | no | `Partial<ActionMenuStrings>` | Overrides this toolbar's own copy — the overflow trigger's name. |
 | `className` | no | `string` |  |
 | `renderLink` | no | `ActionLinkRenderer` |  |
@@ -69,7 +69,7 @@ Kind: interface.
 | `trailing` | no | `ReactNode` | Trailing content beside the shortcut — a badge, a count. |
 | `checked` | no | `boolean` |  |
 | `onCheckedChange` | no | `(checked: boolean) => void` |  |
-| `group` | no | `string \| true` | Starts a new group, ruling off above this entry. A string also captions the group;<br>`true` rules off without a heading — the common case of holding one entry apart<br>(a sign-out, a delete) with nothing worth titling. |
+| `group` | no | `string \| true` | Starts a new group, ruling off above this entry. A string also captions it; `true`<br>rules off without a heading (e.g. to set apart a sign-out or delete). |
 | `tone` | no | `ButtonTone` | Semantic intent. `destructive` also moves the entry last and separates it. |
 | `buttonStyle` | no | `ButtonStyle \| "link"` | Treatment when the action renders as a button. `link` is a ghost that underlines. |
 | `visible` | no | `boolean` | `false` omits the action entirely. |
@@ -113,11 +113,8 @@ Kind: interface.
 
 Kind: callable.
 
-Overflow commands for a page, a card, a table, or a row.
-
-There is deliberately one of these rather than a menu per surface: grouping, the
-destructive ordering, the checkbox rows, and the link handling are the parts everyone
-gets subtly different when they assemble a menu by hand.
+Overflow commands for a page, a card, a table or a row — one component so grouping,
+destructive ordering, checkbox rows and links behave the same everywhere.
 
 ```text
 ({ actions, label, icon, strings, buttonProps, align, side, contentClassName, width, minWidth, maxWidth, closeOnSelect, labelVisibility, preserveOrder, renderLink, renderTrigger, }: ActionMenuProps) => import("react").JSX.Element | null
@@ -147,12 +144,12 @@ Kind: interface.
 | `contentClassName` | no | `string` |  |
 | `width` | no | `string \| number \| "trigger"` | Fixed surface width, any CSS length, or `"trigger"` to match the trigger. Left<br>unset the menu sizes to its widest row. |
 | `minWidth` | no | `string \| number` |  |
-| `maxWidth` | no | `string \| number` | Ceiling for the content-sized default. Defaults to a reading measure rather than<br>the viewport, so one long label cannot drag every row out with it. |
+| `maxWidth` | no | `string \| number` | Ceiling for the content-sized default: a reading measure, so one long label doesn't widen every row. |
 | `closeOnSelect` | no | `boolean` |  |
 | `labelVisibility` | no | `ActionMenuLabelVisibility` |  |
 | `preserveOrder` | no | `boolean` | Keeps the incoming order instead of moving destructive entries last. |
 | `renderLink` | no | `ActionLinkRenderer` | Routes `href` actions through the app's router, keeping this framework-agnostic. |
-| `renderTrigger` | no | `ComponentProps<typeof DropdownMenuTrigger>["render"]` | Replaces the trigger entirely, so a menu can hang off something that is not a<br>button — an account block, a sidebar row, a tab matching its siblings. For a plain<br>button that just needs different words, `label` and `icon` are the smaller tools. |
+| `renderTrigger` | no | `ComponentProps<typeof DropdownMenuTrigger>["render"]` | Replaces the trigger entirely — an account block, a sidebar row, a tab. For different<br>words on a plain button, use `label` and `icon`. |
 
 ### `ActionMenuStrings`
 
@@ -163,6 +160,53 @@ Kind: interface.
 | `trigger` | yes | `string` | Accessible name for an icon-only trigger, which has no visible text of its own. |
 | `overflow` | yes | `string` | Accessible name for the trigger holding the actions that did not fit as buttons. |
 
+### `ActionPlacement`
+
+Kind: type.
+
+Where an action renders when a set is split between buttons and a menu.
+
+```text
+"auto" | "inline" | "menu"
+```
+
+### `ActionPredicate`
+
+Kind: type.
+
+A flag, or a question asked of the subject the action is bound to.
+
+```text
+boolean | ((context: TContext) => boolean)
+```
+
+### `ContextAction`
+
+Kind: interface.
+
+An action bound to a subject — a table row, a board card, an activity, a record. An
+`ActionDefinition` whose handler and predicates take the subject; table, board and
+activity actions extend it, and `resolveContextActions` resolves them.
+
+Extends: `Omit<ActionDefinition, "onClick" | "visible" | "disabled">`.
+
+| member | required | type | description / documented default |
+| --- | :-: | --- | --- |
+| `onClick` | no | `(context: TContext) => void` |  |
+| `visible` | no | `ActionPredicate<TContext>` | `false`, or a predicate returning false, omits the action for that subject. |
+| `disabled` | no | `ActionPredicate<TContext>` |  |
+| `placement` | no | `ActionPlacement` | Forces this entry to one side when the set is split between buttons and a menu: `menu`<br>keeps it out of the button row, `inline` pins it there, `auto` lets the renderer decide. |
+
+### `ContextActionSource`
+
+Kind: type.
+
+A fixed list, or one computed per subject.
+
+```text
+readonly ContextAction<TContext>[] | ((context: TContext) => readonly ContextAction<TContext>[])
+```
+
 ### `defaultActionMenuStrings`
 
 Kind: const.
@@ -171,22 +215,50 @@ Kind: const.
 ActionMenuStrings
 ```
 
-## Preview recipes
+### `resolveContextActions`
 
-Preview route: Action buttons — `/action-buttons`
+Kind: callable.
 
-### ActionButtons
+Runs the predicates against `context` and binds each handler to it.
 
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<ActionButtons actions={actions.slice(0, 2)} />
+```text
+(source: ContextActionSource<TContext> | undefined, context: TContext, options?: ResolveContextActionsOptions) => ResolvedAction[]
 ```
 
-### Overflow
+### `ResolveContextActionsOptions`
 
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<ActionButtons actions={toolbar} max={2} />
+Kind: interface.
+
+| member | required | type | description / documented default |
+| --- | :-: | --- | --- |
+| `onAction` | no | `(id: string) => void` | Called after an action's own handler, with its id, for surfaces reporting all actions through one callback. |
+| `stripHref` | no | `boolean` | Drops `href` instead of rendering a link — for tables, where `href` is data the handler routes with. |
+
+### `ResolvedAction`
+
+Kind: type.
+
+A resolved entry: a plain `ActionDefinition` that still knows where it wants to go.
+
+```text
+ActionDefinition & { placement?: ActionPlacement; }
 ```
 
+### `splitActions`
+
+Kind: callable.
+
+Splits a set into buttons and overflow: `inline` entries are always buttons, `menu`
+entries always overflow, the rest fill up to `max` in order. No `max`: all are buttons.
+
+```text
+(actions: readonly TAction[], max?: number) => { inline: TAction[]; overflow: TAction[]; }
+```
+
+## Preview recipes
+
+Preview route: Action menu & buttons — `/action-menu`
+
 ### ActionMenu
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
@@ -223,3 +295,21 @@ const declared = [
 { label: "Duplicate", icon: CopyIcon, shortcut: "⌘D" }
 { label: "Export", description: "CSV, one row per invoice" }
 ```
+
+### In a card header
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<ActionButtons actions={toolbar} max={2} />
+```
+
+### Actions that depend on a record
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+const actions: ContextAction<Invoice>[] = [
+  { id: "send", label: "Send reminder", visible: (i) => !i.paid, placement: "inline" },
+  { id: "edit", label: "Edit", disabled: (i) => i.locked },
+  { id: "delete", label: "Delete", tone: "destructive", placement: "menu" },
+]
+
+<ActionButtons actions={resolveContextActions(actions, invoice)} max={2} />
+```

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

@@ -14,7 +14,7 @@ Documenting or extending the alert-dialog anatomy itself inside base.
 ## Import
 
 ```tsx fragment — import-only example
-import { AlertDialog } from "themelia-ui/base/alert-dialog"
+import { AlertDialogAction } from "themelia-ui/base/alert-dialog"
 import "themelia-ui/base/alert-dialog.css"
 ```
 
@@ -27,14 +27,6 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 ## Public declarations
 
-### `AlertDialog`
-
-Kind: const.
-
-```text
-typeof Overlay
-```
-
 ### `AlertDialogAction`
 
 Kind: callable.
@@ -45,14 +37,6 @@ The affirmative answer. Closes on click unless the handler prevents it.
 ({ className, ...props }: AnswerProps) => React.JSX.Element
 ```
 
-### `AlertDialogBody`
-
-Kind: const.
-
-```text
-React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>
-```
-
 ### `AlertDialogCancel`
 
 Kind: callable.
@@ -69,30 +53,6 @@ Kind: callable.
 ({ className, ...props }: Omit<OverlayContentProps, "placement" | "dismissal">) => React.JSX.Element
 ```
 
-### `AlertDialogDescription`
-
-Kind: const.
-
-```text
-React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>, "ref"> & React.RefAttributes<HTMLParagraphElement>>
-```
-
-### `AlertDialogFooter`
-
-Kind: callable.
-
-```text
-({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element
-```
-
-### `AlertDialogHeader`
-
-Kind: callable.
-
-```text
-({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element
-```
-
 ### `AlertDialogMedia`
 
 Kind: callable.
@@ -103,28 +63,28 @@ Media slot above the title — an illustration or icon carrying the alert's weig
 ({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element
 ```
 
-### `AlertDialogTitle`
-
-Kind: const.
-
-```text
-React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>, "ref"> & React.RefAttributes<HTMLHeadingElement>>
-```
-
-### `AlertDialogTrigger`
-
-Kind: const.
-
-```text
-typeof OverlayTrigger
-```
-
 ## Preview recipes
 
-Preview route: Alert dialog — `/alert-dialog`
+Preview route: Overlay, dialog & sheet — `/overlay`
 
 ### Alert dialog
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<AlertDialogContent>  {/* dismissal={{ backdrop: false, escape: false }} */}
+<Overlay>
+  <OverlayTrigger render={<Button tone="destructive">Delete account</Button>} />
+  <AlertDialogContent>
+    <OverlayHeader><OverlayTitle>Delete this account?</OverlayTitle></OverlayHeader>
+    <OverlayFooter>
+      <AlertDialogCancel render={<Button tone="neutral" buttonStyle="outline" />}>Cancel</AlertDialogCancel>
+      <AlertDialogAction render={<Button tone="destructive" />}>Delete</AlertDialogAction>
+    </OverlayFooter>
+  </AlertDialogContent>
+</Overlay>
+
+{/* AlertDialogContent is exactly */}
+<OverlayContent
+  role="alertdialog"
+  dismissal={{ backdrop: false, escape: false }}
+  showCloseButton={false}
+/>
 ```

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

@@ -43,12 +43,12 @@ Extends: `ComponentProps<"div">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `ratio` | no | `ResponsiveValue<number>` | Width divided by height — `16 / 9`, `1`, `4 / 3`.<br><br>Written as a division rather than a string so the arithmetic is the caller's and the<br>component never parses anything: `16 / 9` is a number by the time it arrives. |
-| `fit` | no | `"cover" \| "contain"` | How a media child fills the box. `cover` crops to fill, `contain` fits inside it.<br><br>`cover` is the default because it is what a frame is usually for. `contain` is the<br>right answer for artwork with edges that matter — a logo, a diagram, a screenshot. |
+| `ratio` | no | `ResponsiveValue<number>` | Width divided by height — `16 / 9`, `1`, `4 / 3` — as a number, never parsed. |
+| `fit` | no | `"cover" \| "contain"` | How a media child fills the box: `cover` crops to fill (the usual frame); `contain` fits<br>inside, for artwork whose edges matter (a logo, a diagram, a screenshot). |
 
 ## Preview recipes
 
-Preview route: Menubar & hover card — `/menubar`
+Preview route: Aspect ratio — `/aspect-ratio`
 
 ### AspectRatio
 

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

@@ -87,7 +87,7 @@ AvatarPrimitive.Root.Props & { size?: AvatarSize; }
 
 Kind: type.
 
-One of the four places a size prop survives — an avatar has no content to scale with.
+An avatar keeps a size prop: it has no content to scale with.
 
 ```text
 "default" | "sm" | "lg"
@@ -121,23 +121,19 @@ Extends: `Omit<ComponentProps<"div">, "children">`.
 | `strings` | no | `Partial<StackedAvatarsStrings>` | Overrides this group's own copy — its accessible name, and the overflow chip. |
 | `max` | no | `number` | How many faces to show before collapsing the rest into a count. |
 | `showOverflow` | no | `boolean` | Hides the "+N" tile, for a group where the total does not matter. |
-| `overflowFormatter` | no | `(overflow: number) => ReactNode` | Formats the overflow tile — "+12", "+12 more". |
+| `overflowFormatter` | no | `(overflow: number) => ReactNode` | Formats the overflow tile — "+12", "+12 more". Defaults to `strings.overflow`. |
 
 ### `StackedAvatarsStrings`
 
 Kind: interface.
 
-What a stack of avatars announces.
-
-It was `${users.length} ${users.length === 1 ? "person" : "people"}` — an English plural
-rule written into a component. Most languages have more than two forms, and several
-choose the form by more than the count, so the branch cannot be made correct here at
-all: it has to be one function a consumer replaces whole.
+What a stack of avatars announces. Plurals are functions a consumer replaces whole:
+most languages have more than two forms.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `people` | yes | `(count: number) => string` | Names the group, by how many people are in it. |
-| `overflow` | yes | `(count: number) => string` | The `+3` chip at the end of the stack. |
+| `overflow` | yes | `(count: number) => string` | The overflow chip at the end of the stack ("+3"). `overflowFormatter` replaces it. |
 
 ### `StackedAvatarUser`
 

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

@@ -43,9 +43,9 @@ Extends: `React.ComponentProps<"span">`, `VariantProps<typeof badgeVariants>`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `render` | no | `React.ReactElement` | The element this becomes — an anchor, a router link, a label. The canonical<br>polymorphic contract (docs/adr/0005): the element is a VALUE, and `children` keeps<br>meaning the content. |
+| `render` | no | `React.ReactElement` | The element this becomes — an anchor, a router link, a label (docs/adr/0005).<br>`children` stays the content. |
 | `dot` | no | `boolean` | A leading status dot in the badge's own tone. |
-| `pending` | no | `boolean` | Draws the dot hollow, for a state that has not happened yet.<br><br>"Queued" is not "failed" — the difference is worth a shape, not only a word. |
+| `pending` | no | `boolean` | Draws the dot hollow, for a state that hasn't happened yet ("queued", not "failed"). |
 | `pulse` | no | `boolean` | Animates the dot, for a state that is actively changing. |
 
 ### `BadgeTone`

package/.agents/skills/themelia-ui/references/components/base--batch-action-bar.md

@@ -63,7 +63,7 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `summary` | yes | `(selected: number, total?: number) => string` | The selection summary. Takes both counts so a consumer can write "3 of 250 selected"<br>or just "3 selected" — the shape of that sentence differs per language, which is<br>exactly why it is a function rather than a template the component assembles. |
+| `summary` | yes | `(selected: number, total?: number) => string` | The selection summary ("3 of 250 selected"), a function because sentence shape varies by language. |
 | `clear` | yes | `string` | The control that drops the selection. |
 | `label` | yes | `string` | Names the bar for assistive technology. |
 
@@ -83,8 +83,8 @@ Preview route: Batch action bar — `/batch-action-bar`
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
 <BatchActionBar selectedCount={selected} totalCount={250} onClear={() => setSelected(0)}>
-	<Button tone="neutral" buttonStyle="outline">Export</Button>
-	<Button tone="destructive" buttonStyle="outline">Delete</Button>
+	<Button tone="neutral" buttonStyle="ghost">Export</Button>
+	<Button tone="destructive" buttonStyle="ghost">Delete</Button>
 </BatchActionBar>
 ```
 
@@ -92,6 +92,6 @@ Preview route: Batch action bar — `/batch-action-bar`
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
 <BatchActionBar placement="inline" selectedCount={12} onClear={clear}>
-	<Button tone="neutral" buttonStyle="outline">Assign</Button>
+	<Button tone="neutral" buttonStyle="ghost">Assign</Button>
 </BatchActionBar>
 ```

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

@@ -31,8 +31,11 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: callable.
 
+No `size` prop by design: geometry follows the scale factors, so a denser region is a
+scope (styles/FACTORS.md).
+
 ```text
-({ tone, buttonStyle, iconOnly, fullWidth, loading, render, className, disabled, children, ...props }: ButtonProps) => React.JSX.Element
+({ tone, buttonStyle, iconOnly, fullWidth, loading, render, className, disabled, children, onClick, ...props }: ButtonProps) => React.JSX.Element
 ```
 
 ### `ButtonGroup`
@@ -77,10 +80,7 @@ Extends: `React.ComponentProps<"div">`.
 
 Kind: callable.
 
-A non-interactive segment inside a group — a unit, a prefix, a count.
-
-A `<span>`, deliberately: it is not activatable, so making it a disabled button would
-put a phantom stop in the tab order and announce a control that does nothing.
+A non-interactive segment — a unit, a prefix, a count. A span, so it adds no tab stop.
 
 ```text
 ({ className, ...props }: ButtonGroupTextProps) => React.JSX.Element
@@ -115,7 +115,7 @@ Extends: `Omit<React.ComponentProps<"button">, "children">`.
 | `iconOnly` | no | `boolean` | Square button sized to its height. The label becomes the accessible name. |
 | `fullWidth` | no | `boolean` |  |
 | `loading` | no | `boolean` | Shows a spinner and blocks interaction. The label keeps its space so the button does<br>not resize mid-action. |
-| `render` | no | `React.ReactElement` | Renders the child element instead of a `button`.<br>The element this button becomes — an anchor, a router link, a label.<br><br>The canonical polymorphic contract (docs/adr/0005). The element is a VALUE, so it can<br>be built conditionally or defaulted, and `children` keeps meaning the content: the<br>button's own label wrapper still applies, which was the difference from the retired<br>`asChild`.<br><br>  <Button render={<a href="/settings" />}>Settings</Button> |
+| `render` | no | `React.ReactElement` | The element this button becomes — an anchor, a router link, a label (docs/adr/0005).<br>`children` stay the content and keep the button's label wrapper.<br><br>  <Button render={<a href="/settings" />}>Settings</Button> |
 | `children` | no | `React.ReactNode` |  |
 
 ### `ButtonStyle`
@@ -161,8 +161,8 @@ Extends: `Omit<ButtonProps, "onClick">`.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `loading` | no | `boolean` | Controlled pending state. Omit to let the button manage it from `onClick`. |
-| `handlesLoading` | no | `boolean` | Accepted for source-kit compatibility; inert here.<br><br>Upstream a single `Button` upgrades itself into the loading-capable implementation,<br>and `handlesLoading` is how a caller asks for that upgrade up front — swapping<br>implementations at the moment of the first press would change the element's<br>component identity, so React would unmount one and mount the other and the button<br>would lose focus mid-action.<br><br>This kit splits the two into `Button` and `LoaderButton`, so reaching for<br>`LoaderButton` IS that decision and there is nothing left for the flag to do. It is<br>still accepted, and still swallowed rather than spread, so a call site ported from<br>the source kit keeps working and does not leak an unknown attribute to the DOM. |
-| `onClick` | no | `(event: React.MouseEvent<HTMLButtonElement>) => void \| Promise<unknown>` | May return a promise. When it does, the button holds its pending state until the<br>promise settles, so the caller does not have to mirror it in their own state. |
+| `handlesLoading` | no | `boolean` | Accepted for source-kit compatibility; inert. Choosing `LoaderButton` is already that<br>decision. Swallowed rather than spread, so ported call sites don't leak it to the DOM. |
+| `onClick` | no | `(event: React.MouseEvent<HTMLButtonElement>) => void \| Promise<unknown>` | May return a promise; the button then stays pending until it settles. |
 | `strings` | no | `StringsProp<ButtonLoadingStrings>` |  |
 
 ### `TextButton`
@@ -197,7 +197,7 @@ Extends: `ButtonProps`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `tooltip` | yes | `string` | Shown on hover and focus, and used as the accessible name. |
+| `tooltip` | yes | `string` | Shown on hover and focus. It is the accessible name only when the button has no text of<br>its own; beside a visible label it is the description. |
 | `side` | no | `React.ComponentProps<typeof TooltipContent>["side"]` | Where the tooltip opens. |
 
 ## Preview recipes