themelia-ui 2.0.0 → 3.0.0

package/docs/generated/components/base--input-group.md

@@ -20,7 +20,7 @@ import "themelia-ui/base/input-group.css"
 
 ## Composition
 
-This family composes `base/buttons`, `base/text-inputs`, `base/typography`.
+This module composes `base/buttons`, `base/text-inputs`, `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,9 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: callable.
 
+The shell, with `role="group"`. It owns the border and the focus ring for whatever is
+inside, so the control strips its own.
+
 ```text
 ({ className, id, "aria-labelledby": labelledBy, "aria-describedby": describedBy, "aria-invalid": invalid, "aria-required": required, ...props }: React.ComponentProps<"div">) => React.JSX.Element
 ```
@@ -39,38 +42,51 @@ Kind: callable.
 
 Kind: callable.
 
+Something attached to the field — a unit, a prefix, a submit. Clicking it focuses the
+control, as a label does, unless the click lands on a button.
+
 ```text
-({ className, align, ...props }: React.ComponentProps<"div"> & VariantProps<typeof inputGroupAddonVariants>) => React.JSX.Element
+({ className, align, ...props }: InputGroupAddonProps) => React.JSX.Element
 ```
 
 ### `InputGroupAddonProps`
 
-Kind: type.
+Kind: interface.
 
-```text
-React.ComponentProps<"div">
-```
+Extends: `React.ComponentProps<"div">`.
+
+| member | required | type | description / documented default |
+| --- | :-: | --- | --- |
+| `align` | no | `"inline-start" \| "inline-end" \| "block-start" \| "block-end"` | Where the addon attaches. The inline edges sit on the control's line; the block edges<br>take a row of their own, for a toolbar above a textarea or a hint below one. |
 
 ### `InputGroupButton`
 
 Kind: callable.
 
+A quiet Button sized to sit inside the field rather than beside it.
+
 ```text
-({ className, type, tone, buttonStyle, size, ...props }: Omit<React.ComponentProps<typeof Button>, "size" | "type"> & VariantProps<typeof inputGroupButtonVariants> & { type?: "button" | "submit" | "reset"; }) => React.JSX.Element
+({ className, type, tone, buttonStyle, size, ...props }: InputGroupButtonProps) => React.JSX.Element
 ```
 
 ### `InputGroupButtonProps`
 
-Kind: type.
+Kind: interface.
 
-```text
-React.ComponentProps<typeof Button>
-```
+Extends: `Omit<React.ComponentProps<typeof Button>, "size" | "type">`.
+
+| member | required | type | description / documented default |
+| --- | :-: | --- | --- |
+| `size` | no | `"xs" \| "sm" \| "icon-xs" \| "icon-sm"` | The sizes that fit inside a field: two text sizes and their icon-only twins. A<br>full-height Button would set the field's height rather than fit in it, which is why<br>this is the one place the kit keeps a size prop on a control. |
+| `type` | no | `"button" \| "submit" \| "reset"` | The native button type: `button` unless set, so pressing it never submits the form around the field. |
 
 ### `InputGroupInput`
 
 Kind: callable.
 
+The kit's Input with its chrome removed, because the group is drawing it. Every other
+prop passes through.
+
 ```text
 ({ className, ...props }: React.ComponentProps<"input">) => React.JSX.Element
 ```
@@ -95,6 +111,9 @@ React.ComponentProps<"div">
 
 Kind: callable.
 
+Secondary text at the group's own size — a unit, a domain suffix, a counter. It inherits
+the size, so it cannot drift from the input beside it.
+
 ```text
 ({ className, ...props }: React.ComponentProps<"span">) => React.JSX.Element
 ```
@@ -103,6 +122,9 @@ Kind: callable.
 
 Kind: callable.
 
+The kit's Textarea with its chrome removed, because the group is drawing it. Every other
+prop passes through.
+
 ```text
 ({ className, ...props }: TextareaProps) => React.JSX.Element
 ```
@@ -130,25 +152,108 @@ Preview route: Input group — `/input-group`
 ### Attached along the line
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<InputGroup>
-  <InputGroupAddon><SearchIcon /></InputGroupAddon>
-  <InputGroupInput placeholder="Search orders" />
-</InputGroup>
+import { ArrowRightIcon, MailIcon, SearchIcon } from "lucide-react"
+
+import {
+	InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText,
+} from "themelia-ui/base/input-group"
+import { Stack } from "themelia-ui/base/structure"
+
+export default function InputGroupInline() {
+	return (
+		<Stack gap="lg" style={{ maxWidth: "26rem" }}>
+			<InputGroup>
+				<InputGroupAddon>
+					<SearchIcon aria-hidden="true" />
+				</InputGroupAddon>
+				<InputGroupInput placeholder="Search orders" aria-label="Search orders" />
+			</InputGroup>
+
+			<InputGroup>
+				<InputGroupAddon>
+					<MailIcon aria-hidden="true" />
+				</InputGroupAddon>
+				<InputGroupInput placeholder="name@example.com" aria-label="Email" />
+				<InputGroupAddon align="inline-end">
+					<InputGroupText>@acme.test</InputGroupText>
+				</InputGroupAddon>
+			</InputGroup>
+
+			<InputGroup>
+				<InputGroupInput placeholder="Add a label" aria-label="Label" />
+				<InputGroupAddon align="inline-end">
+					<InputGroupButton size="icon-xs" aria-label="Add">
+						<ArrowRightIcon aria-hidden="true" />
+					</InputGroupButton>
+				</InputGroupAddon>
+			</InputGroup>
+		</Stack>
+	)
+}
 ```
 
 ### Attached above or below
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<InputGroup>
-  <InputGroupTextarea placeholder="Write a note" />
-  <InputGroupAddon align="block-end">
-    <InputGroupText>Markdown supported</InputGroupText>
-  </InputGroupAddon>
-</InputGroup>
+import { StarIcon } from "lucide-react"
+
+import {
+	InputGroup, InputGroupAddon, InputGroupButton, InputGroupText, InputGroupTextarea,
+} from "themelia-ui/base/input-group"
+import { Stack } from "themelia-ui/base/structure"
+
+export default function InputGroupBlock() {
+	return (
+		<Stack gap="lg" style={{ maxWidth: "26rem" }}>
+			<InputGroup>
+				<InputGroupAddon align="block-start">
+					<InputGroupButton size="icon-xs" aria-label="Favourite">
+						<StarIcon aria-hidden="true" />
+					</InputGroupButton>
+					<InputGroupText>Internal note</InputGroupText>
+				</InputGroupAddon>
+				<InputGroupTextarea placeholder="Write a note" aria-label="Note" rows={3} />
+				<InputGroupAddon align="block-end">
+					<InputGroupText>Markdown supported</InputGroupText>
+				</InputGroupAddon>
+			</InputGroup>
+		</Stack>
+	)
+}
 ```
 
 ### Button sizes inside the shell
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<InputGroupButton size="icon-xs" aria-label="Go"><ArrowRightIcon /></InputGroupButton>
+import { ArrowRightIcon } from "lucide-react"
+
+import {
+	InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput,
+} from "themelia-ui/base/input-group"
+import { Stack } from "themelia-ui/base/structure"
+
+export default function InputGroupButtons() {
+	return (
+		<Stack gap="lg" style={{ maxWidth: "26rem" }}>
+			{(["xs", "sm"] as const).map((size) => (
+				<InputGroup key={size}>
+					<InputGroupInput placeholder={`size="${size}"`} aria-label={size} />
+					<InputGroupAddon align="inline-end">
+						<InputGroupButton size={size}>Apply</InputGroupButton>
+					</InputGroupAddon>
+				</InputGroup>
+			))}
+			{(["icon-xs", "icon-sm"] as const).map((size) => (
+				<InputGroup key={size}>
+					<InputGroupInput placeholder={`size="${size}"`} aria-label={size} />
+					<InputGroupAddon align="inline-end">
+						<InputGroupButton size={size} aria-label="Go">
+							<ArrowRightIcon aria-hidden="true" />
+						</InputGroupButton>
+					</InputGroupAddon>
+				</InputGroup>
+			))}
+		</Stack>
+	)
+}
 ```

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

@@ -20,7 +20,7 @@ import "themelia-ui/base/item.css"
 
 ## Composition
 
-This family composes `base/display`, `base/typography`.
+This module composes `base/display`, `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,8 +31,8 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: callable.
 
-Item — a row. No size prop: row height follows `--density-scale`, so use a denser
-scope for a denser list.
+A row — a list row, a menu row, a table row. No size prop: row height follows
+`--density-scale`, so use a denser scope for a denser list.
 
 **Use when:** An identity row with a title, description, media and actions.
 
@@ -45,13 +45,15 @@ scope for a denser list.
 **Alternatives:** MetadataList, FormField.
 
 ```text
-({ className, surface, render, ...props }: useRender.ComponentProps<"div"> & VariantProps<typeof itemVariants>) => React.JSX.Element
+({ className, surface, render, ...props }: ItemProps) => React.JSX.Element
 ```
 
 ### `ItemActions`
 
 Kind: callable.
 
+Trailing controls. Kept out of the content flow, so a long title cannot displace them.
+
 ```text
 ({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element
 ```
@@ -60,6 +62,9 @@ Kind: callable.
 
 Kind: callable.
 
+The title and description. Takes the remaining width and truncates rather than pushing
+the actions off the row.
+
 ```text
 ({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element
 ```
@@ -76,6 +81,9 @@ Kind: callable.
 
 Kind: callable.
 
+A full-width row below the row's own content, for an item that carries a footnote
+without it competing with the title line.
+
 ```text
 ({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element
 ```
@@ -84,6 +92,8 @@ Kind: callable.
 
 Kind: callable.
 
+Stacks rows and owns the dividers, so a row never draws its own.
+
 ```text
 ({ className, ruled, ...props }: ItemGroupProps) => React.JSX.Element
 ```
@@ -96,12 +106,15 @@ Extends: `React.ComponentProps<"div">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `ruled` | no | `boolean` | Draws rules between rows instead of gaps, and neutral rows drop their inline padding.<br>Use for a run of rows inside one card. |
+| `ruled` | no | `boolean` | Draws hairlines between rows instead of gaps, and neutral rows drop their inline<br>padding and go flush. For a run of rows inside one card, where a rem of air between<br>each reads as unrelated blocks. Bordered and muted rows keep their inset, because they<br>do draw a surface. |
 
 ### `ItemHeader`
 
 Kind: callable.
 
+A full-width row above the row's own content, for an item that carries an eyebrow
+without it competing with the title line.
+
 ```text
 ({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element
 ```
@@ -110,14 +123,19 @@ Kind: callable.
 
 Kind: callable.
 
+The leading slot: a glyph, an avatar or a thumbnail, aligned to the first line.
+
 ```text
-({ className, variant, ...props }: React.ComponentProps<"div"> & VariantProps<typeof itemMediaVariants>) => React.JSX.Element
+({ className, variant, ...props }: ItemMediaProps) => React.JSX.Element
 ```
 
 ### `ItemSeparator`
 
 Kind: callable.
 
+A rule between items, for a group that wants one only in places. `ItemGroup ruled` is the
+answer when every row needs one.
+
 ```text
 ({ className, ...props }: React.ComponentProps<typeof Separator>) => React.JSX.Element
 ```
@@ -137,31 +155,112 @@ Preview route: Item — `/item`
 ### Item
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<ItemGroup>
-  <Item>
-    <ItemMedia variant="image"><Avatar /></ItemMedia>
-    <ItemContent>
-      <ItemTitle>Jane McDonald</ItemTitle>
-      <ItemDescription>jane@example.com</ItemDescription>
-    </ItemContent>
-    <ItemActions><Badge>Active</Badge></ItemActions>
-  </Item>
-</ItemGroup>
+import { CreditCardIcon } from "lucide-react"
+
+import { Badge } from "themelia-ui/base/badge"
+import {
+	Item, ItemActions, ItemContent, ItemDescription, ItemGroup, ItemMedia, ItemSeparator,
+	ItemTitle,
+} from "themelia-ui/base/item"
+import { Money, RelativeTime } from "themelia-ui/primitives"
+
+export default function ItemExample() {
+	return (
+		<ItemGroup style={{ width: "100%" }}>
+			{[
+				{ name: "Northwind Traders", detail: "Invoice #4417", amount: 1299.5 },
+				{ name: "Acme Corporation", detail: "Invoice #4418", amount: 84 },
+			].map((row, index) => (
+				<Item key={row.name} surface={index === 0 ? "bordered" : "neutral"}>
+					<ItemMedia variant="icon">
+						<CreditCardIcon />
+					</ItemMedia>
+					<ItemContent>
+						<ItemTitle>{row.name}</ItemTitle>
+						<ItemDescription>
+							{row.detail} · <RelativeTime value="2026-08-20T00:00:00Z" />
+						</ItemDescription>
+					</ItemContent>
+					<ItemActions>
+						<Money amount={row.amount} />
+						<Badge tone="neutral">Paid</Badge>
+					</ItemActions>
+				</Item>
+			))}
+			<ItemSeparator />
+			<Item surface="muted">
+				<ItemContent>
+					<ItemTitle>Muted surface</ItemTitle>
+					<ItemDescription>For a de-emphasised row.</ItemDescription>
+				</ItemContent>
+			</Item>
+		</ItemGroup>
+	)
+}
 ```
 
 ### Density
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Scope vars={{ "--density-scale": 0.85 }}>
-  <ItemGroup>…</ItemGroup>
-</Scope>
+import { Card } from "themelia-ui/base/cards"
+import { Item, ItemContent, ItemDescription, ItemGroup, ItemTitle } from "themelia-ui/base/item"
+import { Stack } from "themelia-ui/base/structure"
+import { Scope } from "themelia-ui/ui-provider"
+
+export default function CardsScale() {
+	return (
+		<Stack gap="lg" style={{ width: "100%" }}>
+			{[1, 0.85].map((scale) => (
+				<Scope key={scale} vars={{ "--density-scale": scale }}>
+					<Card surface="bordered" title={`--density-scale ${scale}`}>
+						<ItemGroup>
+							<Item surface="bordered">
+								<ItemContent>
+									<ItemTitle>First row</ItemTitle>
+									<ItemDescription>Supporting detail.</ItemDescription>
+								</ItemContent>
+							</Item>
+							<Item surface="bordered">
+								<ItemContent>
+									<ItemTitle>Second row</ItemTitle>
+									<ItemDescription>Supporting detail.</ItemDescription>
+								</ItemContent>
+							</Item>
+						</ItemGroup>
+					</Card>
+				</Scope>
+			))}
+		</Stack>
+	)
+}
 ```
 
 ### A ruled group
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<ItemGroup ruled>
-  <Item>…</Item>
-  <Item>…</Item>
-</ItemGroup>
+import { CreditCardIcon } from "lucide-react"
+
+import { Item, ItemContent, ItemDescription, ItemGroup, ItemMedia, ItemTitle } from "themelia-ui/base/item"
+
+export default function ItemRuled() {
+	return (
+		<ItemGroup ruled style={{ width: "100%" }}>
+			{[
+				{ name: "Production", detail: "sk_live_••••0b3d" },
+				{ name: "Staging", detail: "sk_test_••••a771" },
+				{ name: "CI", detail: "sk_ci_••••e145" },
+			].map((row) => (
+				<Item key={row.name}>
+					<ItemMedia variant="icon">
+						<CreditCardIcon />
+					</ItemMedia>
+					<ItemContent>
+						<ItemTitle>{row.name}</ItemTitle>
+						<ItemDescription>{row.detail}</ItemDescription>
+					</ItemContent>
+				</Item>
+			))}
+		</ItemGroup>
+	)
+}
 ```

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

@@ -20,7 +20,7 @@ import "themelia-ui/base/label.css"
 
 ## Composition
 
-This family composes `base/typography`.
+This module composes `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,8 +31,11 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: callable.
 
+A form label: a real `<label>`, so clicking it focuses the control it names. Takes
+everything a native label takes.
+
 ```text
-({ className, ...props }: React.ComponentProps<"label">) => React.JSX.Element
+({ className, ...props }: LabelProps) => React.JSX.Element
 ```
 
 ## Preview recipes
@@ -42,6 +45,24 @@ Preview route: Label — `/label`
 ### Label
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Label htmlFor="email">Email</Label>
-<Input id="email" />
+import { Checkbox } from "themelia-ui/base/choice-inputs"
+import { Label } from "themelia-ui/base/label"
+import { Stack } from "themelia-ui/base/structure"
+import { Input } from "themelia-ui/base/text-inputs"
+
+
+export default function LabelExample() {
+	return (
+		<Stack gap="lg" style={{ maxWidth: "26rem", width: "100%" }}>
+			<Stack gap="xs">
+				<Label htmlFor="demo-email">Email</Label>
+				<Input id="demo-email" placeholder="name@example.com" />
+			</Stack>
+			<Stack direction="horizontal" gap="sm" align="center">
+				<Checkbox id="demo-terms" />
+				<Label htmlFor="demo-terms">I accept the terms</Label>
+			</Stack>
+		</Stack>
+	)
+}
 ```

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

@@ -22,9 +22,9 @@ import "themelia-ui/base/dropdown-menu.css"
 
 ## Composition
 
-This family has no component-family dependencies.
+This module depends on no other module.
 
-It is used together with `base/dropdown-menu`: import that family and its stylesheet too.
+It is used together with `base/dropdown-menu`: import that module and its stylesheet too.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -35,6 +35,13 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: callable.
 
+The bar. Its menus are `DropdownMenu` roots, each holding a `MenubarTrigger` and a
+`DropdownMenuContent` with every row the dropdown menu offers.
+
+The menu itself is the dropdown menu module's, not a copy under a second name — so
+groups, labels, checkbox and radio items, submenus and the portal are the dropdown
+menu's parts too, and a reader who has learned one has learned the other.
+
 ```text
 ({ className, ...props }: MenubarProps) => import("react").JSX.Element
 ```
@@ -51,7 +58,9 @@ No own members are present in the normalized public snapshot.
 
 Kind: callable.
 
-One menu's word in the bar. Place it inside a `DropdownMenu`, beside its content.
+One menu's word in the bar, placed inside a `DropdownMenu` beside its
+`DropdownMenuContent`. Once a menu is open, moving along the bar opens the next without
+a second click — which is what makes a menubar a menubar rather than a row of dropdowns.
 
 ```text
 ({ className, ...props }: MenuPrimitive.Trigger.Props) => import("react").JSX.Element
@@ -64,12 +73,42 @@ Preview route: Menubar — `/menubar`
 ### Menubar
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Menubar>
-  <DropdownMenu>
-    <MenubarTrigger>File</MenubarTrigger>
-    <DropdownMenuContent>
-      <DropdownMenuItem>New <DropdownMenuShortcut>⌘N</DropdownMenuShortcut></DropdownMenuItem>
-    </DropdownMenuContent>
-  </DropdownMenu>
-</Menubar>
+import {
+	DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuShortcut,
+} from "themelia-ui/base/dropdown-menu"
+import { Menubar, MenubarTrigger } from "themelia-ui/base/menubar"
+
+export default function MenubarExample() {
+	return (
+		<Menubar>
+			<DropdownMenu>
+				<MenubarTrigger>File</MenubarTrigger>
+				<DropdownMenuContent>
+					<DropdownMenuItem>
+						New <DropdownMenuShortcut>⌘N</DropdownMenuShortcut>
+					</DropdownMenuItem>
+					<DropdownMenuItem>Open…</DropdownMenuItem>
+					<DropdownMenuSeparator />
+					<DropdownMenuItem>
+						Save <DropdownMenuShortcut>⌘S</DropdownMenuShortcut>
+					</DropdownMenuItem>
+				</DropdownMenuContent>
+			</DropdownMenu>
+			<DropdownMenu>
+				<MenubarTrigger>Edit</MenubarTrigger>
+				<DropdownMenuContent>
+					<DropdownMenuItem>Undo</DropdownMenuItem>
+					<DropdownMenuItem>Redo</DropdownMenuItem>
+				</DropdownMenuContent>
+			</DropdownMenu>
+			<DropdownMenu>
+				<MenubarTrigger>View</MenubarTrigger>
+				<DropdownMenuContent>
+					<DropdownMenuItem>Zoom in</DropdownMenuItem>
+					<DropdownMenuItem>Zoom out</DropdownMenuItem>
+				</DropdownMenuContent>
+			</DropdownMenu>
+		</Menubar>
+	)
+}
 ```