themelia-ui 2.0.1 → 3.1.0

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

@@ -15,12 +15,11 @@ Assembling a form's visible structure — label, control, support text, sections
 
 ```tsx fragment — import-only example
 import { DirtyStateBanner } from "themelia-ui/base/forms"
-import "themelia-ui/base/forms.css"
 ```
 
 ## Composition
 
-This family composes `base/buttons`, `base/cards`, `base/feedback`, `base/typography`.
+This module composes `base/buttons`, `base/cards`, `base/feedback`, `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.
@@ -55,6 +54,8 @@ SubmitStateButtonStrings
 
 Kind: callable.
 
+Tells the reader there are unsaved changes, with the actions that resolve them.
+
 ```text
 ({ title, description, actions, tone, strings, className, }: DirtyStateBannerProps) => import("react").JSX.Element
 ```
@@ -68,7 +69,7 @@ Kind: interface.
 | `title` | no | `ReactNode` |  |
 | `description` | no | `ReactNode` |  |
 | `actions` | no | `ReactNode` | Save and discard, usually. |
-| `tone` | no | `Extract<AlertTone, "neutral" \| "info" \| "warning">` |  |
+| `tone` | no | `Extract<AlertTone, "neutral" \| "info" \| "warning">` | Deliberately narrower than `AlertTone`: unsaved work is neither an error nor a<br>success. |
 | `strings` | no | `StringsProp<DirtyStateBannerStrings>` |  |
 | `className` | no | `string` |  |
 
@@ -98,9 +99,9 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `title` | no | `ReactNode` | Overrides the counted heading. |
-| `description` | no | `ReactNode` |  |
-| `errors` | no | `readonly ReactNode[]` |  |
+| `title` | no | `ReactNode` | Replaces the heading, which otherwise counts the list. |
+| `description` | no | `ReactNode` | Copy under the heading. |
+| `errors` | no | `readonly ReactNode[]` | The problems, one per item. An item may link to its field. |
 | `action` | no | `ReactNode` | A control beside the summary — "Review the first problem". |
 | `autoFocus` | no | `boolean` | Moves focus to the summary when it has problems, and again whenever the count changes —<br>what a failed submit wants. Items may be links to their fields<br>(`<a href="#email">Email is not valid.</a>`). |
 | `strings` | no | `StringsProp<ErrorSummaryStrings>` |  |
@@ -120,16 +121,20 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `label` | no | `React.ReactNode` | Caption above the control, associated through `htmlFor`. |
-| `required` | no | `boolean` | Marks the field required and renders the indicator beside the label. |
+| `label` | no | `React.ReactNode` | Caption above the control, wired to it by a generated id unless the control has one of<br>its own, or `htmlFor` names one. |
+| `required` | no | `boolean` | Marks the label and the control: the indicator beside the label, and `aria-required`<br>on the control. |
 | `hint` | no | `React.ReactNode` | Lowest priority: shown only when neither `error` nor `helperText` is set. |
 | `helperText` | no | `React.ReactNode` | Middle priority: replaces `hint`, and is itself replaced by `error`. |
-| `error` | no | `React.ReactNode` | Highest priority. Announced politely and switches the control to its invalid state. |
+| `error` | no | `React.ReactNode` | Highest priority of the three supporting lines. Announced politely and switches the<br>control to its invalid state. |
 
 ### `FieldGroup`
 
 Kind: callable.
 
+Several fields sharing one label and one supporting line — a date range, a name split in
+two. A real `<fieldset>` and `<legend>`, so the legend is announced when focus enters the
+group.
+
 ```text
 ({ legend, description, className, children, ...props }: FieldGroupProps) => React.JSX.Element
 ```
@@ -142,13 +147,15 @@ Extends: `React.ComponentProps<"fieldset">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `legend` | no | `React.ReactNode` |  |
-| `description` | no | `React.ReactNode` |  |
+| `legend` | no | `React.ReactNode` | The group's one label, announced when focus enters the group. |
+| `description` | no | `React.ReactNode` | The group's one supporting line. |
 
 ### `FormActionsBar`
 
 Kind: callable.
 
+A form's actions in one row, with room for status before them.
+
 ```text
 ({ children, leading, trailing, sticky, className }: FormActionsBarProps) => import("react").JSX.Element
 ```
@@ -161,8 +168,8 @@ Kind: interface.
 | --- | :-: | --- | --- |
 | `children` | no | `ReactNode` | The actions. `trailing` wins when both are given. |
 | `leading` | no | `ReactNode` | Status or context before the actions — "Last saved 2 minutes ago". |
-| `trailing` | no | `ReactNode` |  |
-| `sticky` | no | `boolean` | Pins the bar to the bottom of its nearest scrolling ancestor. |
+| `trailing` | no | `ReactNode` | The actions, in place of `children`. It wins when both are given. |
+| `sticky` | no | `boolean` | Pins the bar to the foot of its nearest scrolling ancestor, for a form longer than the<br>viewport. |
 | `className` | no | `string` |  |
 
 ### `FormField`
@@ -213,14 +220,16 @@ Extends: `FieldChromeProps`, `Omit<React.ComponentProps<"div">, "children">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `children` | yes | `FormFieldControl` | A direct control, or an explicit adapter for a wrapped/custom control. |
+| `children` | yes | `FormFieldControl` | A direct control, or an explicit adapter for a wrapped/custom control. Use the function<br>form when a consumer wrapper hides the actual control, and spread the supplied id and<br>aria props onto it. |
 | `orientation` | no | `"vertical" \| "horizontal"` | Label beside the control instead of above it — for settings rows. |
-| `htmlFor` | no | `string \| false` | The id the caption addresses, or `false` when there is no single labelable element.<br>A string is for a control that can't take the generated id. `false` is for a cluster<br>(repeater, checkbox group, segments): the field becomes a named `group` instead. Opt-in,<br>because a group sharing its control's name makes `getByLabelText` ambiguous. |
+| `htmlFor` | no | `string \| false` | The id the caption addresses, or `false` when there is no single labelable element.<br>A string associates the label with a control that already has an id, instead of the<br>generated one, or one that can't take it. `false` is for a cluster<br>(repeater, checkbox group, segments): the field becomes a named `group` instead. Opt-in,<br>because a group sharing its control's name makes `getByLabelText` ambiguous. |
 
 ### `FormSection`
 
 Kind: callable.
 
+A titled group of fields, on a card's surface.
+
 ```text
 ({ title, description, actions, children, footer, surface, className, }: FormSectionProps) => import("react").JSX.Element
 ```
@@ -231,12 +240,12 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `title` | no | `ReactNode` |  |
-| `description` | no | `ReactNode` |  |
-| `actions` | no | `ReactNode` | Controls in the section header. |
+| `title` | no | `ReactNode` | The header line. |
+| `description` | no | `ReactNode` | The copy under the title. |
+| `actions` | no | `ReactNode` | Controls on the title's own line. |
 | `children` | no | `ReactNode` |  |
-| `footer` | no | `ReactNode` |  |
-| `surface` | no | `CardSurface` | Outer chrome. Use `flat` when the section already sits inside a card. |
+| `footer` | no | `ReactNode` | A footer below the fields. |
+| `surface` | no | `CardSurface` | Outer chrome. Use `flat` when the section already sits inside a card, which is most of<br>them. |
 | `className` | no | `string` |  |
 
 ### `SubmitState`
@@ -267,7 +276,7 @@ Extends: `Omit<ButtonProps, "loading" | "children">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `state` | no | `SubmitState` |  |
+| `state` | no | `SubmitState` | Drives the label and the disabled state. The label is the message, so a spinner never<br>replaces the answer. |
 | `strings` | no | `StringsProp<SubmitStateButtonStrings>` |  |
 
 ### `SubmitStateButtonStrings`
@@ -287,79 +296,252 @@ Preview route: Form field — `/form-field`
 ### FormField
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<FormField
-  label="Email"
-  required
-  hint="We only use this for receipts."
-  error={errors.email}
->
-  <Input type="email" />
-</FormField>
+import { FormField } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+import { Input } from "themelia-ui/base/text-inputs"
+
+
+export default function FormFieldExample() {
+	return (
+		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
+			<FormField label="Email" required hint="We only use this for receipts.">
+				<Input type="email" placeholder="you@example.com" />
+			</FormField>
+			<FormField label="Workspace" helperText="Lowercase letters and dashes only.">
+				<Input defaultValue="acme-corp" />
+			</FormField>
+			<FormField label="Card number" error="That card number is not valid.">
+				<Input defaultValue="4242 4242" />
+			</FormField>
+		</Stack>
+	)
+}
 ```
 
 ### Custom control composition
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<FormField label="Weight" error={errors.weight}>
-  {(fieldProps) => (
-    <FieldShell {...fieldProps} end="kg">
-      {(controlProps) => <WrappedNumberInput controlProps={controlProps} />}
-    </FieldShell>
-  )}
-</FormField>
+import { FormField } from "themelia-ui/base/forms"
+import { FieldShell, Input } from "themelia-ui/base/text-inputs"
+
+
+export default function FormFieldComposition() {
+	return (
+		<div style={{ maxWidth: "26rem", width: "100%" }}>
+			<FormField label="Weight" required hint="Use the packaged weight.">
+				{(fieldProps) => (
+					<FieldShell {...fieldProps} end="kg">
+						{(controlProps) => (
+							<div style={{ display: "contents" }}>
+								<Input type="number" defaultValue="24" {...controlProps} />
+							</div>
+						)}
+					</FieldShell>
+				)}
+			</FormField>
+		</div>
+	)
+}
 ```
 
 ### Horizontal fields
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<FormField orientation="horizontal" label="Display name">
-  <Input />
-</FormField>
+import { FormField } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+import { Input } from "themelia-ui/base/text-inputs"
+
+export default function HorizontalFields() {
+	return (
+		<Stack style={{ width: "100%" }}>
+			<FormField orientation="horizontal" label="Display name" hint="Shown on invoices.">
+				<Input defaultValue="Acme Corporation" />
+			</FormField>
+			<FormField orientation="horizontal" label="Billing email" required>
+				<Input type="email" defaultValue="billing@acme.com" />
+			</FormField>
+		</Stack>
+	)
+}
 ```
 
 ### FieldGroup
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<FieldGroup legend="Reporting period" description="Both ends are inclusive.">
-  <FormField label="From"><Input type="date" /></FormField>
-  <FormField label="To"><Input type="date" /></FormField>
-</FieldGroup>
+import { FieldGroup, FormField } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+import { Input } from "themelia-ui/base/text-inputs"
+
+
+export default function FieldGroupExample() {
+	return (
+		<div style={{ maxWidth: "34rem", width: "100%" }}>
+			<FieldGroup legend="Reporting period" description="Both ends are inclusive.">
+				<Stack direction="horizontal" gap="sm">
+					<FormField label="From">
+						<Input type="date" defaultValue="2026-03-01" />
+					</FormField>
+					<FormField label="To">
+						<Input type="date" defaultValue="2026-03-31" />
+					</FormField>
+				</Stack>
+			</FieldGroup>
+		</div>
+	)
+}
 ```
 
 ### FormSection
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<FormSection title="Billing" description="Where invoices go." actions={<Button>Edit</Button>}>
-  <FormField label="Company">…</FormField>
-</FormSection>
+import { Button } from "themelia-ui/base/buttons"
+import { FormField, FormSection } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+import { Input } from "themelia-ui/base/text-inputs"
+import { Text } from "themelia-ui/base/typography"
+
+export default function FormSectionExample() {
+	return (
+		<Stack style={{ maxWidth: "34rem" }}>
+			<FormSection
+				title="Billing"
+				description="Where invoices go. Changing it does not change the shipping address."
+				actions={
+					<Button tone="neutral" appearance="ghost">
+						Edit
+					</Button>
+				}
+				footer={
+					<Text size="xs" type="secondary">
+						VAT is added at checkout.
+					</Text>
+				}
+			>
+				<FormField label="Company">
+					<Input defaultValue="Northwind Traders" />
+				</FormField>
+			</FormSection>
+		</Stack>
+	)
+}
 ```
 
 ### FormActionsBar
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<FormActionsBar leading={<Text size="xs" type="secondary">Saved 2 minutes ago</Text>}>
-  <Button buttonStyle="outline">Discard</Button>
-  <Button>Save</Button>
-</FormActionsBar>
+import { Button } from "themelia-ui/base/buttons"
+import { Card, CardContent } from "themelia-ui/base/cards"
+import { FormActionsBar } from "themelia-ui/base/forms"
+import { Text } from "themelia-ui/base/typography"
+
+export default function FormActions() {
+	return (
+		<Card style={{ maxWidth: "34rem" }}>
+			<CardContent>
+				<FormActionsBar
+					leading={
+						<Text size="xs" type="secondary">
+							Saved 2 minutes ago
+						</Text>
+					}
+				>
+					<Button tone="neutral" appearance="outline">
+						Discard
+					</Button>
+					<Button>Save</Button>
+				</FormActionsBar>
+			</CardContent>
+		</Card>
+	)
+}
 ```
 
 ### ErrorSummary
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<ErrorSummary
-  errors={["Name is required.", "Email is not valid."]}
-  action={<Button buttonStyle="outline">Review the first problem</Button>}
-/>
+import { Button } from "themelia-ui/base/buttons"
+import { ErrorSummary } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+
+export default function FormErrorSummary() {
+	return (
+		<Stack gap="sm" style={{ maxWidth: "34rem" }}>
+			<ErrorSummary
+				errors={[
+					"Name is required.",
+					"Email is not valid.",
+					"VAT number does not match the selected country.",
+				]}
+				action={
+					<Button tone="neutral" appearance="outline">
+						Review the first problem
+					</Button>
+				}
+			/>
+		</Stack>
+	)
+}
 ```
 
 ### DirtyStateBanner
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<DirtyStateBanner actions={<><Button buttonStyle="outline">Discard</Button><Button>Save</Button></>} />
+import { Button } from "themelia-ui/base/buttons"
+import { DirtyStateBanner } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+
+export default function FormDirty() {
+	return (
+		<Stack style={{ maxWidth: "34rem" }}>
+			{(["neutral", "info", "warning"] as const).map((tone) => (
+				<DirtyStateBanner
+					key={tone}
+					tone={tone}
+					actions={
+						<>
+							<Button tone="neutral" appearance="outline">
+								Discard
+							</Button>
+							<Button>Save</Button>
+						</>
+					}
+				/>
+			))}
+		</Stack>
+	)
+}
 ```
 
 ### SubmitStateButton
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<SubmitStateButton state={state} />
+import { useState } from "react"
+
+import { Button } from "themelia-ui/base/buttons"
+import { SubmitStateButton, type SubmitState } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+
+export default function FormSubmitState() {
+	const [state, setState] = useState<SubmitState>("idle")
+
+	return (
+		<Stack direction="horizontal" wrap align="center">
+			{(["idle", "submitting", "succeeded"] as SubmitState[]).map((s) => (
+				<SubmitStateButton key={s} state={s} />
+			))}
+			<Button
+				tone="neutral"
+				appearance="outline"
+				onClick={() => {
+					setState("submitting")
+					setTimeout(() => setState("succeeded"), 1200)
+					setTimeout(() => setState("idle"), 2600)
+				}}
+			>
+				Run the cycle
+			</Button>
+			<SubmitStateButton state={state} />
+		</Stack>
+	)
+}
 ```

package/docs/generated/components/base--hover-card.md

@@ -15,12 +15,11 @@ Hovering a reference reveals a preview the reader does not have to act on.
 
 ```tsx fragment — import-only example
 import { HoverCard } from "themelia-ui/base/hover-card"
-import "themelia-ui/base/hover-card.css"
 ```
 
 ## Composition
 
-This family has no component-family dependencies.
+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.
@@ -39,6 +38,8 @@ Kind: callable.
 
 Kind: callable.
 
+What the card shows: the preview itself, placed against its trigger.
+
 ```text
 ({ container, align, side, sideOffset, className, ...props }: HoverCardContentProps) => import("react").JSX.Element
 ```
@@ -52,9 +53,9 @@ Extends: `PreviewCard.Popup.Props`.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `container` | no | `UIPortalContainer` | Where the popup renders. Defaults to the nearest `UIPortalHost`, else the primitive's<br>own target. |
-| `align` | no | `PreviewCard.Positioner.Props["align"]` |  |
-| `side` | no | `PreviewCard.Positioner.Props["side"]` |  |
-| `sideOffset` | no | `PreviewCard.Positioner.Props["sideOffset"]` |  |
+| `align` | no | `PreviewCard.Positioner.Props["align"]` | How the card lines up along the side it opens on: `start`, `center` or `end`. |
+| `side` | no | `PreviewCard.Positioner.Props["side"]` | Where the card opens relative to its trigger: `top`, `right`, `bottom` or `left`, or<br>the logical `inline-start` or `inline-end`. |
+| `sideOffset` | no | `PreviewCard.Positioner.Props["sideOffset"]` | The gap between the trigger and the card, in pixels. |
 
 ### `HoverCardProps`
 
@@ -68,8 +69,12 @@ No own members are present in the normalized public snapshot.
 
 Kind: callable.
 
-Trigger with default delays. `closeDelay` keeps the card open while the pointer crosses
-the gap to it.
+What opens the card. Hover and focus both open it, because a card reachable only by
+pointer is unreachable to a keyboard.
+
+The delays live here, on the trigger. `closeDelay` is the load-bearing one: it keeps the
+card open while the pointer crosses the gap to it, and without it the card closes as the
+pointer leaves the trigger.
 
 ```text
 ({ delay, closeDelay, ...props }: HoverCardTriggerProps) => import("react").JSX.Element
@@ -90,8 +95,34 @@ Preview route: Hover card — `/hover-card`
 ### HoverCard
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<HoverCard>
-  <HoverCardTrigger render={<TextLink href="/people/jane" />}>@jane</HoverCardTrigger>
-  <HoverCardContent>…</HoverCardContent>
-</HoverCard>
+import { Avatar, AvatarFallback } from "themelia-ui/base/avatar"
+import { HoverCard, HoverCardContent, HoverCardTrigger } from "themelia-ui/base/hover-card"
+import { Stack } from "themelia-ui/base/structure"
+import { Text, TextLink } from "themelia-ui/base/typography"
+
+export default function HoverCardExample() {
+	return (
+		<Text>
+			Assigned to{" "}
+			<HoverCard>
+				{/* A real link, as the rule below asks: the card previews where it goes. */}
+				<HoverCardTrigger render={<TextLink href="/people/jane" onClick={(event) => event.preventDefault()} />}>
+					@jane
+				</HoverCardTrigger>
+				<HoverCardContent>
+					<Stack direction="horizontal" gap="sm" align="start">
+						<Avatar>
+							<AvatarFallback>JM</AvatarFallback>
+						</Avatar>
+						<Stack gap="sm">
+							<Text weight="medium">Jane McDonald</Text>
+							<Text size="xs" type="secondary">Billing · joined March 2024</Text>
+						</Stack>
+					</Stack>
+				</HoverCardContent>
+			</HoverCard>{" "}
+			on 1 September.
+		</Text>
+	)
+}
 ```