themelia-ui 1.0.1 → 2.0.0

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

@@ -43,6 +43,14 @@ Kind: callable.
 ({ className, children, ...props }: AccordionContentProps) => import("react").JSX.Element
 ```
 
+### `AccordionContentProps`
+
+Kind: type.
+
+```text
+AccordionPrimitive.Panel.Props
+```
+
 ### `AccordionItem`
 
 Kind: callable.
@@ -51,6 +59,64 @@ Kind: callable.
 ({ className, ...props }: AccordionItemProps) => import("react").JSX.Element
 ```
 
+### `AccordionItemData`
+
+Kind: interface.
+
+One section for the bounded `items` API; use the compound parts for richer rows.
+
+| member | required | type | description / documented default |
+| --- | :-: | --- | --- |
+| `value` | yes | `string` | Stable identifier. Used as the item's `value`. |
+| `title` | yes | `ReactNode` |  |
+| `description` | no | `ReactNode` | Supporting line below the title, inside the trigger. |
+| `icon` | no | `ReactNode` | Leading media. Framed per the root's `media` prop. |
+| `badge` | no | `ReactNode` | Trailing node after the title — usually a `<Badge>`. |
+| `content` | yes | `ReactNode` |  |
+| `disabled` | no | `boolean` |  |
+
+### `AccordionItemProps`
+
+Kind: type.
+
+```text
+AccordionPrimitive.Item.Props
+```
+
+### `AccordionMedia`
+
+Kind: type.
+
+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"
+```
+
+### `AccordionProps`
+
+Kind: interface.
+
+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, 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 shell with quiet dividers (the settings
+default); `card` — a panel per section; `flat` — none, the consumer supplies it.
+
+```text
+"bordered" | "card" | "flat"
+```
+
 ### `AccordionTrigger`
 
 Kind: callable.
@@ -59,6 +125,14 @@ Kind: callable.
 ({ className, children, ...props }: AccordionTriggerProps) => import("react").JSX.Element
 ```
 
+### `AccordionTriggerProps`
+
+Kind: type.
+
+```text
+AccordionPrimitive.Trigger.Props
+```
+
 ## Preview recipes
 
 Preview route: Accordion — `/accordion`

package/docs/generated/components/base--action-menu.md

@@ -31,26 +31,181 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: callable.
 
+The same definitions rendered as visible buttons — a toolbar rather than an overflow.
+
 ```text
 ({ actions, max, strings, className, renderLink, }: ActionButtonsProps) => import("react").JSX.Element | null
 ```
 
+### `ActionButtonsProps`
+
+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 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` |  |
+
+### `ActionDefinition`
+
+Kind: interface.
+
+| member | required | type | description / documented default |
+| --- | :-: | --- | --- |
+| `id` | no | `string` | Stable key. Falls back to a string `label`, then the index. |
+| `label` | yes | `ReactNode` |  |
+| `icon` | no | `ActionIcon` |  |
+| `type` | no | `"item" \| "checkbox"` | `checkbox` renders a toggle driven by `checked` / `onCheckedChange`. |
+| `href` | no | `string` | Renders the entry as a link. A native `<a href>` by default, which is a full page<br>navigation — pass `renderLink` to route it through the app's router instead. |
+| `target` | no | `string` |  |
+| `rel` | no | `string` |  |
+| `external` | no | `boolean` |  |
+| `onClick` | no | `() => void` |  |
+| `description` | no | `ReactNode` | Second line under the label. |
+| `shortcut` | no | `ReactNode` | Trailing content — a keyboard shortcut, rendered in the shortcut treatment. |
+| `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 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. |
+| `disabled` | no | `boolean` |  |
+| `closeOnSelect` | no | `boolean` | Overrides the menu's `closeOnSelect` for this entry. |
+| `className` | no | `string` |  |
+| `render` | no | `ReactNode` | Replaces the rendered entry — a framework `<Link>`, for instance. |
+
+### `ActionIcon`
+
+Kind: type.
+
+A Lucide icon, any component taking a className, or an already-rendered node.
+
+```text
+ComponentType<{ className?: string; }> | ReactNode
+```
+
+### `ActionLinkRenderer`
+
+Kind: type.
+
+```text
+(props: ActionLinkRenderProps) => ReactElement
+```
+
+### `ActionLinkRenderProps`
+
+Kind: interface.
+
+| member | required | type | description / documented default |
+| --- | :-: | --- | --- |
+| `href` | yes | `string` |  |
+| `children` | no | `ReactNode` |  |
+| `target` | no | `string` |  |
+| `rel` | no | `string` |  |
+| `external` | no | `boolean` |  |
+| `disabled` | no | `boolean` |  |
+
 ### `ActionMenu`
 
 Kind: callable.
 
+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
 ```
 
+### `ActionMenuLabelVisibility`
+
+Kind: type.
+
+```text
+"visible" | "responsive" | "hidden"
+```
+
+### `ActionMenuProps`
+
+Kind: interface.
+
+| member | required | type | description / documented default |
+| --- | :-: | --- | --- |
+| `actions` | yes | `readonly ActionDefinition[]` | Commands to offer. Destructive entries move last unless `preserveOrder` is set. |
+| `label` | no | `string` | Trigger text. Omit for an icon-only trigger — `strings.trigger` names it then. |
+| `icon` | no | `ActionIcon` | Trigger glyph. Defaults to the vertical ellipsis. |
+| `strings` | no | `Partial<ActionMenuStrings>` | Overrides this menu's own copy. |
+| `buttonProps` | no | `Omit<ComponentProps<typeof Button>, "children">` |  |
+| `align` | no | `"start" \| "center" \| "end"` |  |
+| `side` | no | `"top" \| "right" \| "bottom" \| "left"` |  |
+| `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: 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 — an account block, a sidebar row, a tab. For different<br>words on a plain button, use `label` and `icon`. |
+
 ### `ActionMenuStrings`
 
 Kind: interface.
 
-| member | required | type |
-| --- | :-: | --- |
-| `trigger` | yes | `string` |
-| `overflow` | yes | `string` |
+| member | required | type | description / documented default |
+| --- | :-: | --- | --- |
+| `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`
 
@@ -60,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
@@ -112,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/docs/generated/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,28 +27,14 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 ## Public declarations
 
-### `AlertDialog`
-
-Kind: const.
-
-```text
-typeof Overlay
-```
-
 ### `AlertDialogAction`
 
 Kind: callable.
 
-```text
-({ className, ...props }: AnswerProps) => React.JSX.Element
-```
-
-### `AlertDialogBody`
-
-Kind: const.
+The affirmative answer. Closes on click unless the handler prevents it.
 
 ```text
-React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>
+({ className, ...props }: AnswerProps) => React.JSX.Element
 ```
 
 ### `AlertDialogCancel`
@@ -67,60 +53,38 @@ 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.
 
-```text
-({ 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.
+Media slot above the title — an illustration or icon carrying the alert's weight.
 
 ```text
-typeof OverlayTrigger
+({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element
 ```
 
 ## 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/docs/generated/components/base--aspect-ratio.md

@@ -41,52 +41,14 @@ Kind: interface.
 
 Extends: `ComponentProps<"div">`.
 
-| member | required | type |
-| --- | :-: | --- |
-| `ratio` | no | `ResponsiveValue<number>` |
-| `fit` | no | `"cover" \| "contain"` |
+| member | required | type | description / documented default |
+| --- | :-: | --- | --- |
+| `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`
-
-### Menubar
-
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Menubar>
-  <MenubarMenu>
-    <MenubarTrigger>File</MenubarTrigger>
-    <MenubarContent>
-      <MenubarItem>New <MenubarShortcut>⌘N</MenubarShortcut></MenubarItem>
-    </MenubarContent>
-  </MenubarMenu>
-</Menubar>
-```
-
-### HoverCard
-
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<HoverCard>
-  <HoverCardTrigger render={<TextLink />}>@jane</HoverCardTrigger>
-  <HoverCardContent>…</HoverCardContent>
-</HoverCard>
-```
-
-### Resizable
-
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<ResizablePanelGroup orientation="horizontal" autoSaveId="inspector">
-  <ResizablePanel defaultSize={65}>…</ResizablePanel>
-  <ResizableHandle withHandle />
-  <ResizablePanel defaultSize={35}>…</ResizablePanel>
-</ResizablePanelGroup>
-```
-
-### OtpInput
-
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<OtpInput length={6} groupSize={3} value={code} onValueChange={setCode} />
-```
+Preview route: Aspect ratio — `/aspect-ratio`
 
 ### AspectRatio
 
@@ -95,9 +57,3 @@ Preview route: Menubar & hover card — `/menubar`
   <img src={cover} alt="" />
 </AspectRatio>
 ```
-
-### Kbd
-
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Kbd>⌘K</Kbd>
-```

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

@@ -87,6 +87,8 @@ AvatarPrimitive.Root.Props & { size?: AvatarSize; }
 
 Kind: type.
 
+An avatar keeps a size prop: it has no content to scale with.
+
 ```text
 "default" | "sm" | "lg"
 ```
@@ -113,33 +115,36 @@ Kind: interface.
 
 Extends: `Omit<ComponentProps<"div">, "children">`.
 
-| member | required | type |
-| --- | :-: | --- |
-| `users` | yes | `StackedAvatarUser[]` |
-| `strings` | no | `Partial<StackedAvatarsStrings>` |
-| `max` | no | `number` |
-| `showOverflow` | no | `boolean` |
-| `overflowFormatter` | no | `(overflow: number) => ReactNode` |
+| member | required | type | description / documented default |
+| --- | :-: | --- | --- |
+| `users` | yes | `StackedAvatarUser[]` |  |
+| `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". Defaults to `strings.overflow`. |
 
 ### `StackedAvatarsStrings`
 
 Kind: interface.
 
-| member | required | type |
-| --- | :-: | --- |
-| `people` | yes | `(count: number) => string` |
-| `overflow` | yes | `(count: number) => string` |
+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 overflow chip at the end of the stack ("+3"). `overflowFormatter` replaces it. |
 
 ### `StackedAvatarUser`
 
 Kind: interface.
 
-| member | required | type |
-| --- | :-: | --- |
-| `id` | no | `string` |
-| `name` | yes | `string` |
-| `src` | no | `string` |
-| `initials` | no | `string` |
+| member | required | type | description / documented default |
+| --- | :-: | --- | --- |
+| `id` | no | `string` | Stable identity. Falls back to the name when absent. |
+| `name` | yes | `string` |  |
+| `src` | no | `string` |  |
+| `initials` | no | `string` | Overrides the derived initials. |
 
 ## Preview recipes
 

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

@@ -41,12 +41,12 @@ Kind: interface.
 
 Extends: `React.ComponentProps<"span">`, `VariantProps<typeof badgeVariants>`.
 
-| member | required | type |
-| --- | :-: | --- |
-| `render` | no | `React.ReactElement` |
-| `dot` | no | `boolean` |
-| `pending` | no | `boolean` |
-| `pulse` | no | `boolean` |
+| member | required | type | description / documented default |
+| --- | :-: | --- | --- |
+| `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 hasn't happened yet ("queued", not "failed"). |
+| `pulse` | no | `boolean` | Animates the dot, for a state that is actively changing. |
 
 ### `BadgeTone`
 
@@ -60,6 +60,8 @@ Kind: type.
 
 Kind: type.
 
+Structural presentation. The tone supplies the hue; this decides how it is applied.
+
 ```text
 "soft" | "solid" | "outline"
 ```