themelia-ui 2.0.1 → 3.0.0

package/docs/generated/components/layout--sidebar.md

@@ -20,7 +20,7 @@ import "themelia-ui/layout/sidebar.css"
 
 ## Composition
 
-This family composes `base/action-menu`, `base/avatar`, `base/display`, `base/dropdown-menu`, `base/sidebar`, `base/typography`.
+This module composes `base/action-menu`, `base/avatar`, `base/display`, `base/dropdown-menu`, `base/sidebar`, `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.
@@ -43,11 +43,11 @@ Extends: `LayoutNavigationAdapter`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `navigationGroups` | no | `Record<string, SidebarNavItem[]>` | Navigation grouped by section heading. An empty key renders an untitled group. |
+| `navigationGroups` | no | `Record<string, SidebarNavItem[]>` | Navigation as data, grouped by section heading. An empty key renders an untitled group,<br>and an item with children renders as a disclosure. |
 | `footerNavItems` | no | `SidebarFlatNavItem[]` | Entries pinned to the footer — support, settings, sign out. |
-| `currentUrl` | no | `string` | The current route. Everything active follows from this. |
+| `currentUrl` | no | `string` | The current route. Active rows, and which parent is expanded, follow from this alone. |
 | `iconMap` | no | `Record<string, ComponentType<{ className?: string; }>>` | Resolves an icon name to a component, so navigation data can stay serialisable. |
-| `liveBadges` | no | `Record<string, string \| number>` | Counts keyed by `handle`, for values that change after the nav was defined. |
+| `liveBadges` | no | `Record<string, string \| number>` | Counts keyed by `handle`, overriding an item's declared badge — for a number that<br>changes after the nav was defined. |
 | `loading` | no | `boolean` |  |
 | `loadingRows` | no | `number` | Rows shown while loading. |
 | `logo` | no | `ReactNode` | The product mark, and the compact one for the collapsed rail. With `workspaceLinks`<br>the header becomes a switcher, in the same row height. |
@@ -96,6 +96,45 @@ Matches every ancestor, so use `resolveActiveHref` to pick the current row.
 (currentUrl: string, path: string) => boolean
 ```
 
+### `LinkRenderer`
+
+Kind: type.
+
+How a component renders a link: through the application's router. Every component that
+navigates takes one as `renderLink`, and without one renders a plain anchor. Return one
+element: the component may merge its own props into it, such as a menu item's role or a
+button's styling.
+
+```tsx fragment — declaration JSDoc excerpt
+const renderLink: LinkRenderer = ({ href, children, active, disabled, external, ...rest }) =>
+  disabled || !href ? <span {...rest}>{children}</span> : <Link to={href} {...rest}>{children}</Link>
+```
+
+```text
+(props: LinkRenderProps) => ReactElement
+```
+
+### `LinkRenderProps`
+
+Kind: interface.
+
+What a component hands its link renderer. Spread everything but `active`, `disabled` and `external` onto the element.
+
+| member | required | type | description / documented default |
+| --- | :-: | --- | --- |
+| `href` | no | `string` | Destination. When absent, render non-interactive content. |
+| `children` | yes | `ReactNode` |  |
+| `className` | no | `string` |  |
+| `target` | no | `string` |  |
+| `rel` | no | `string` |  |
+| `onClick` | no | `(event: MouseEvent<HTMLAnchorElement>) => void` |  |
+| `"aria-label"` | no | `string` |  |
+| `"aria-current"` | no | `AriaAttributes["aria-current"]` |  |
+| `"aria-disabled"` | no | `AriaAttributes["aria-disabled"]` |  |
+| `active` | no | `boolean` | Hint for active styling. A renderer may ignore it — the component styles the row itself. |
+| `disabled` | no | `boolean` | The entry goes nowhere: render non-interactive content. |
+| `external` | no | `boolean` | Opens elsewhere: the default renderer adds `target="_blank"` and `rel="noopener noreferrer"`. |
+
 ### `resolveActiveHref`
 
 Kind: callable.
@@ -120,7 +159,9 @@ Omit<SidebarNavItem, "children">
 Kind: callable.
 
 Resolves an icon that may be a name (looked up in `iconMap`), a component or a node.
-Exported for `renderItem` callers.
+Exported because a caller supplying `renderItem` still wants the same resolution — a row
+rendered by hand should not need its own copy of “string means look it up, component
+means render it, node means use it”.
 
 ```text
 ({ icon, iconMap, }: { icon?: LayoutIconSource; iconMap?: Record<string, ComponentType<{ className?: string; }>>; }) => import("react").JSX.Element | null
@@ -136,13 +177,17 @@ Kind: interface.
 | `active` | yes | `boolean` |  |
 | `expanded` | yes | `boolean` | Whether the row's children are shown: the reader's toggle if they used it, else derived from the current URL. |
 | `badge` | no | `string \| number` |  |
-| `renderLink` | yes | `LayoutLinkRenderer` |  |
+| `renderLink` | yes | `LinkRenderer` |  |
 | `toggle` | no | `() => void` | Flips `expanded` for a row with children; wire it to a custom parent row's click.<br>AppSidebar always supplies it; optional for hand-built contexts. |
 
 ### `SidebarLogo`
 
 Kind: callable.
 
+The product mark in the rail’s header. It swaps to the compact mark when the rail
+collapses to icons rather than scaling the full one down, because a squeezed wordmark is
+unreadable at rail width.
+
 ```text
 ({ logo, collapsedLogo, className }: SidebarLogoProps) => import("react").JSX.Element | null
 ```
@@ -176,6 +221,10 @@ Kind: interface.
 
 Kind: callable.
 
+The account row at the foot of the rail. Its menu opens to the RIGHT when the rail is
+collapsed and ABOVE when it is not, because a menu that always drops down is off-screen at
+the bottom of a full-height panel.
+
 ```text
 ({ user, customContent, onProfile, onSettings, onLogout, strings, renderTrigger, }: SidebarUserProps) => import("react").JSX.Element
 ```
@@ -209,6 +258,9 @@ Kind: interface.
 
 Kind: callable.
 
+The rail’s header as a workspace switcher. The whole header row is the trigger, not a
+chevron beside a decorative name — the name is what a reader aims at.
+
 ```text
 ({ logo, collapsedLogo, workspaceLinks, renderLink, strings, contentClassName, }: SidebarWorkspaceProps) => import("react").JSX.Element
 ```
@@ -261,13 +313,149 @@ Kind: interface.
 
 Preview route: App shell — `/app-shell`
 
+### The shell
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { useState } from "react"
+
+import { Badge } from "themelia-ui/base/badge"
+import { PillRadioGroup } from "themelia-ui/base/choice-inputs"
+import type { SidebarCollapsible, SidebarVariant } from "themelia-ui/base/sidebar"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { SidebarInsetLayout } from "themelia-ui/layout/app-shell"
+import { AppSidebar } from "themelia-ui/layout/sidebar"
+
+import { demoLink } from "./_demo-link"
+import { AdminContent, Brand, BrandMark } from "./_shared"
+import { FRAME, NAVIGATION, PROVIDER } from "./data"
+
+function ShellDemo({ variant, collapsible }: { variant: SidebarVariant; collapsible: SidebarCollapsible }) {
+	const [currentUrl, setCurrentUrl] = useState("/app/settings/members")
+	return <div style={FRAME}>
+		<SidebarInsetLayout contentRender={<div />} contained sidebarProviderProps={PROVIDER}
+			showTrigger={collapsible !== "none"} ruledToolbar={variant !== "inset"}
+			toolbar={<Text weight="medium">Workspace</Text>} toolbarEnd={<Badge tone="neutral">{variant}</Badge>}
+			sidebar={<AppSidebar variant={variant} collapsible={collapsible} currentUrl={currentUrl} navigationGroups={NAVIGATION}
+				liveBadges={{ invoices: 2 }} logo={<Brand />} collapsedLogo={<BrandMark />} renderLink={demoLink(setCurrentUrl)} />}
+		><AdminContent currentUrl={currentUrl} /></SidebarInsetLayout>
+	</div>
+}
+
+export default function SidebarShell() {
+	const [variant, setVariant] = useState<string | null>("sidebar")
+	const [collapsible, setCollapsible] = useState<string | null>("icon")
+
+	return (
+		<Stack gap="lg" style={{ width: "100%" }}>
+			<Stack direction="horizontal" gap="xl" wrap>
+				<Stack gap="2xs">
+					<Text size="xs" type="secondary">
+						variant
+					</Text>
+					<PillRadioGroup
+						aria-label="Sidebar surface"
+						name="sidebar-variant"
+						value={variant}
+						onValueChange={setVariant}
+						options={[
+							{ value: "sidebar", label: "sidebar" },
+							{ value: "floating", label: "floating" },
+							{ value: "inset", label: "inset" },
+						]}
+					/>
+				</Stack>
+				<Stack gap="2xs">
+					<Text size="xs" type="secondary">
+						collapsible
+					</Text>
+					<PillRadioGroup
+						aria-label="Sidebar collapse behavior"
+						name="sidebar-collapsible"
+						value={collapsible}
+						onValueChange={setCollapsible}
+						options={[
+							{ value: "icon", label: "icon" },
+							{ value: "offcanvas", label: "offcanvas" },
+							{ value: "none", label: "none" },
+						]}
+					/>
+				</Stack>
+			</Stack>
+			<ShellDemo
+				key={`${variant}-${collapsible}`}
+				variant={(variant ?? "sidebar") as SidebarVariant}
+				collapsible={(collapsible ?? "icon") as SidebarCollapsible}
+			/>
+		</Stack>
+	)
+}
+```
+
 ### TopbarSidebarLayout
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<TopbarSidebarLayout
-  logo={<Brand />}
-  sidebar={<AppSidebar collapsible="icon" navigationGroups={NAVIGATION} currentUrl={url} renderLink={renderLink} />}
->
-  <InvoicePage />
-</TopbarSidebarLayout>
+import { useState } from "react"
+
+import { Badge } from "themelia-ui/base/badge"
+import { PillRadioGroup } from "themelia-ui/base/choice-inputs"
+import { Stack } from "themelia-ui/base/structure"
+import { Input } from "themelia-ui/base/text-inputs"
+import { TopbarSidebarLayout } from "themelia-ui/layout/app-shell"
+import { AppSidebar } from "themelia-ui/layout/sidebar"
+
+import { demoLink } from "./_demo-link"
+import { AdminContent, Brand } from "./_shared"
+import { FRAME, NAVIGATION, PROVIDER } from "./data"
+
+function TopbarDemo() {
+	const [currentUrl, setCurrentUrl] = useState("/app/invoices")
+	const [side, setSide] = useState<string | null>("left")
+	const [query, setQuery] = useState("")
+	const sidebarSide = side === "right" ? "right" : "left"
+
+	return (
+		<Stack gap="lg" style={{ width: "100%", minWidth: 0 }}>
+			<PillRadioGroup
+				aria-label="Navigation side"
+				name="topbar-sidebar-side"
+				value={side}
+				onValueChange={setSide}
+				options={[{ value: "left", label: "Left navigation" }, { value: "right", label: "Right navigation" }]}
+			/>
+			<div style={FRAME}>
+				<TopbarSidebarLayout
+					contained
+					contentRender={<div />}
+					sidebarProviderProps={PROVIDER}
+					sidebarSide={sidebarSide}
+					logo={<Brand />}
+					headerActions={<Badge tone="neutral">Workspace</Badge>}
+					sidebar={
+						<AppSidebar
+							side={sidebarSide}
+							collapsible="icon"
+							currentUrl={currentUrl}
+							navigationGroups={NAVIGATION}
+							renderLink={demoLink(setCurrentUrl)}
+						/>
+					}
+				>
+					<Stack gap="lg">
+						{currentUrl === "/app/invoices" && (
+							<Input type="search" aria-label="Search invoices" placeholder="Search invoices…" value={query} onChange={event => setQuery(event.target.value)} />
+						)}
+						<AdminContent currentUrl={currentUrl} query={currentUrl === "/app/invoices" ? query : undefined} />
+					</Stack>
+				</TopbarSidebarLayout>
+			</div>
+		</Stack>
+	)
+}
+
+export default function TopbarSidebarLayoutExample() {
+	return (
+		<TopbarDemo />
+	)
+}
 ```

package/docs/generated/components/layout--workspace.md

@@ -20,7 +20,7 @@ import "themelia-ui/layout/workspace.css"
 
 ## Composition
 
-This family composes `base/badge`, `base/display`, `base/feedback`, `base/item`, `base/navigation`, `base/typography`.
+This module composes `base/badge`, `base/display`, `base/feedback`, `base/item`, `base/navigation`, `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.
@@ -51,6 +51,45 @@ Kind: const.
 WorkspaceRecordHeaderStrings
 ```
 
+### `LinkRenderer`
+
+Kind: type.
+
+How a component renders a link: through the application's router. Every component that
+navigates takes one as `renderLink`, and without one renders a plain anchor. Return one
+element: the component may merge its own props into it, such as a menu item's role or a
+button's styling.
+
+```tsx fragment — declaration JSDoc excerpt
+const renderLink: LinkRenderer = ({ href, children, active, disabled, external, ...rest }) =>
+  disabled || !href ? <span {...rest}>{children}</span> : <Link to={href} {...rest}>{children}</Link>
+```
+
+```text
+(props: LinkRenderProps) => ReactElement
+```
+
+### `LinkRenderProps`
+
+Kind: interface.
+
+What a component hands its link renderer. Spread everything but `active`, `disabled` and `external` onto the element.
+
+| member | required | type | description / documented default |
+| --- | :-: | --- | --- |
+| `href` | no | `string` | Destination. When absent, render non-interactive content. |
+| `children` | yes | `ReactNode` |  |
+| `className` | no | `string` |  |
+| `target` | no | `string` |  |
+| `rel` | no | `string` |  |
+| `onClick` | no | `(event: MouseEvent<HTMLAnchorElement>) => void` |  |
+| `"aria-label"` | no | `string` |  |
+| `"aria-current"` | no | `AriaAttributes["aria-current"]` |  |
+| `"aria-disabled"` | no | `AriaAttributes["aria-disabled"]` |  |
+| `active` | no | `boolean` | Hint for active styling. A renderer may ignore it — the component styles the row itself. |
+| `disabled` | no | `boolean` | The entry goes nowhere: render non-interactive content. |
+| `external` | no | `boolean` | Opens elsewhere: the default renderer adds `target="_blank"` and `rel="noopener noreferrer"`. |
+
 ### `WorkspaceContentWidth`
 
 Kind: type.
@@ -65,6 +104,10 @@ How wide the content column is allowed to get.
 
 Kind: callable.
 
+The frame a single RECORD is edited in. Not an app shell — it sits inside one: a record
+with many sections needs its own navigation, and nesting a second shell is how a page ends
+up with two sidebars.
+
 ```text
 ({ header, sidebar, rail, children, contentWidth, label, sidebarWidth, railWidth, className, headerClassName, bodyClassName, sidebarClassName, contentClassName, contentRender, railClassName, style, ...props }: WorkspaceLayoutProps) => import("react").JSX.Element
 ```
@@ -109,6 +152,10 @@ Kind: interface.
 
 Kind: callable.
 
+The languages a record exists in, and how complete each is. A strip rather than a
+select, because the completeness is the reason to switch and a select hides it behind a
+press.
+
 ```text
 ({ locales, activeLocale, onLocaleChange, actions, strings, className, ...props }: WorkspaceLocaleStripProps) => import("react").JSX.Element
 ```
@@ -141,6 +188,10 @@ Kind: interface.
 
 Kind: callable.
 
+Navigation for a record filled in over time. The difference from every other nav in the
+kit is COMPLETION: each section reports how much of it is done, because that is what
+decides where the reader goes next.
+
 ```text
 ({ groups, activeId, onSelect, renderItem, renderLink, footerSlot, strings, className, ...props }: WorkspaceNavProps) => import("react").JSX.Element
 ```
@@ -231,16 +282,16 @@ Extends: `Omit<React.ComponentProps<"div">, "title">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `title` | yes | `React.ReactNode` |  |
-| `description` | no | `React.ReactNode` |  |
+| `title` | yes | `React.ReactNode` | What the record IS. Gives way before the badges do. |
+| `description` | no | `React.ReactNode` | One line under the title. |
 | `media` | no | `React.ReactNode` | An avatar, an icon medallion, a thumbnail. |
 | `badges` | no | `React.ReactNode` | Status marks beside the title. Short — the title is what gives way, not these. |
 | `status` | no | `React.ReactNode` | A single prominent status, rendered after the badges. |
-| `metadata` | no | `WorkspaceRecordMetadataItem[]` | Key/value pairs, drawn inline: each label and its value are one item, read as one fact. |
+| `metadata` | no | `WorkspaceRecordMetadataItem[]` | Key/value pairs, drawn as an inline MetadataList: each label and its value are one item,<br>read as one fact, with a middle dot between items. |
 | `strings` | no | `Partial<WorkspaceRecordHeaderStrings>` | Overrides this header's own copy — the names of its two unlabelled regions. |
 | `actions` | no | `React.ReactNode` | Primary actions, pinned to the end of the title row. |
 | `secondaryActions` | no | `React.ReactNode` | A second, quieter row beneath — filters, tabs, bulk controls. |
-| `headingLevel` | no | `1 \| 2 \| 3` |  |
+| `headingLevel` | no | `1 \| 2 \| 3` | The heading element, for the document outline. |
 
 ### `WorkspaceRecordHeaderStrings`
 
@@ -268,21 +319,84 @@ Preview route: Workspace record header — `/workspace-header`
 ### WorkspaceRecordHeader
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<WorkspaceRecordHeader
-  title="Invoice #4417"
-  media={<Avatar />}
-  badges={<Badge tone="success" dot>Paid</Badge>}
-  metadata={[{ label: "Owner", value: "Jane McDonald" }]}
-  actions={<Button>Edit</Button>}
-/>
+import { Avatar, AvatarFallback } from "themelia-ui/base/avatar"
+import { Badge } from "themelia-ui/base/badge"
+import { Button } from "themelia-ui/base/buttons"
+import { Card } from "themelia-ui/base/cards"
+import { WorkspaceRecordHeader } from "themelia-ui/layout/workspace"
+import { Money } from "themelia-ui/primitives"
+
+export default function RecordHeader() {
+	return (
+		<Card surface="bordered" style={{ width: "100%" }}>
+			<WorkspaceRecordHeader
+				title="Invoice #4417"
+				description="Northwind Traders — issued 1 September 2026."
+				media={
+					<Avatar size="lg">
+						<AvatarFallback>NT</AvatarFallback>
+					</Avatar>
+				}
+				badges={<Badge tone="success" dot>Paid</Badge>}
+				metadata={[
+					{ label: "Owner", value: "Jane McDonald" },
+					{ label: "Amount", value: <Money amount={1299.5} currency="EUR" /> },
+					{ label: "Terms", value: "Net 30" },
+				]}
+				actions={
+					<>
+						<Button tone="neutral" buttonStyle="outline">Duplicate</Button>
+						<Button>Edit</Button>
+					</>
+				}
+			/>
+		</Card>
+	)
+}
 ```
 
 ### Two tiers of action
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<WorkspaceRecordHeader
-  title="Deployment 41a9c2"
-  actions={<Button>Redeploy</Button>}
-  secondaryActions={<PillRadioGroup options={views} />}
-/>
+import { useState } from "react"
+
+import { Badge } from "themelia-ui/base/badge"
+import { Button } from "themelia-ui/base/buttons"
+import { Card } from "themelia-ui/base/cards"
+import { PillRadioGroup } from "themelia-ui/base/choice-inputs"
+import { WorkspaceRecordHeader } from "themelia-ui/layout/workspace"
+
+function ViewSwitch() {
+	const [view, setView] = useState<string | null>("logs")
+	return (
+		<PillRadioGroup
+			value={view}
+			onValueChange={setView}
+			options={[
+				{ value: "logs", label: "Logs" },
+				{ value: "assets", label: "Assets" },
+				{ value: "timing", label: "Timing" },
+			]}
+		/>
+	)
+}
+
+export default function RecordHeaderSecondary() {
+	return (
+		<Card surface="bordered" style={{ width: "100%" }}>
+			<WorkspaceRecordHeader
+				title="Deployment 41a9c2"
+				headingLevel={2}
+				description="main → production, 4 minutes ago."
+				badges={<Badge tone="warning" dot pulse>Building</Badge>}
+				metadata={[
+					{ label: "Branch", value: "main" },
+					{ label: "Author", value: "Raj Patel" },
+				]}
+				actions={<Button tone="neutral" buttonStyle="outline">Cancel</Button>}
+				secondaryActions={<ViewSwitch />}
+			/>
+		</Card>
+	)
+}
 ```