themelia-ui 2.0.1 → 3.0.0

package/docs/generated/components/features--async-preview.md

@@ -20,7 +20,7 @@ import "themelia-ui/features/async-preview.css"
 
 ## Composition
 
-This family composes `base/badge`, `base/feedback`, `base/popover`, `base/spinner`, `base/tooltip`.
+This module composes `base/badge`, `base/feedback`, `base/popover`, `base/spinner`, `base/tooltip`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -51,7 +51,7 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `children` | yes | `(data: TData, state: AsyncPreviewState<TData, TContext, TType>) => ReactNode` | Rendered only in the `success` state, with the data non-null. |
+| `children` | yes | `(data: TData, state: AsyncPreviewState<TData, TContext, TType>) => ReactNode` | Runs only in the `success` state, with the data non-null — so `data.name` needs no guard. |
 
 ### `AsyncPreviewCachePolicy`
 
@@ -68,6 +68,8 @@ open — for a value that changes while the reader is on the page.
 
 Kind: callable.
 
+The popover the states render in, labelled by its trigger.
+
 ```text
 ({ className, children, width, side, align, }: AsyncPreviewContentProps) => import("react").JSX.Element
 ```
@@ -94,13 +96,16 @@ Extends: `AsyncPreviewRootBaseProps<TData, TContext, TType>`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `onShow` | yes | `(args: AsyncPreviewShowArgs<TContext, TType>) => Promise<TData \| null \| undefined>` |  |
+| `onShow` | yes | `(args: AsyncPreviewShowArgs<TContext, TType>) => Promise<TData \| null \| undefined>` | The fetcher, run when the preview opens or the trigger prefetches it. Supply this or<br>`data`, not both. |
 | `data` | no | `never` |  |
 
 ### `AsyncPreviewEmpty`
 
 Kind: callable.
 
+The case where the fetch resolved to nothing. One part per state, so each is styled where it
+is written.
+
 ```text
 ({ className, children }: AsyncPreviewSlotProps) => import("react").JSX.Element | null
 ```
@@ -117,6 +122,9 @@ AsyncPreviewSlotProps<TData, TContext, TType>
 
 Kind: callable.
 
+The error case: a message with a retry, unless replaced. One part per state, so each is
+styled where it is written.
+
 ```text
 ({ className, children }: AsyncPreviewSlotProps) => import("react").JSX.Element | null
 ```
@@ -133,6 +141,9 @@ AsyncPreviewSlotProps<TData, TContext, TType>
 
 Kind: callable.
 
+The loading case: a spinner with the fetcher's slow-step label, unless replaced. One part per
+state, so each is styled where it is written.
+
 ```text
 ({ className, children }: AsyncPreviewSlotProps) => import("react").JSX.Element | null
 ```
@@ -169,6 +180,11 @@ Why a fetch ran. `prefetch` fires on pointer-enter and is not repeated by the op
 
 Kind: callable.
 
+The root of the compound over `useAsyncPreview`: it runs the fetch, the cache and the open
+state for the parts inside it. Compound rather than one `renderPreview` prop because the four
+states want four different shapes, and a single render prop makes the caller branch on all
+of them every time.
+
 ```text
 ({ children, strings, ...options }: AsyncPreviewRootProps<TData, TContext, TType>) => import("react").JSX.Element
 ```
@@ -181,11 +197,11 @@ Extends: `AsyncPreviewCallbacks<TData, TContext, TType>`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `type` | yes | `TType` | Names the kind of record, passed to the fetcher. Caching requires cacheKey. |
-| `context` | yes | `TContext` | Whatever the fetcher needs — usually an id. |
-| `cacheKey` | no | `string` | The record identity and cache key. Change it when switching records; without one nothing is cached. |
-| `cachePolicy` | no | `AsyncPreviewCachePolicy` |  |
-| `staleTime` | no | `number` | How long a cache entry counts as fresh. Defaults to five minutes. |
+| `type` | yes | `TType` | Names the kind of record. Passed back to `onShow`, so one fetcher can serve several types.<br>Caching requires `cacheKey`. |
+| `context` | yes | `TContext` | Whatever the fetcher needs — usually an id. Handed to `onShow` unchanged. |
+| `cacheKey` | no | `string` | The record identity and cache key: it enables the cache. Change it when the record<br>changes; absent, nothing is cached, and each open fetches or consumes its hover prefetch. |
+| `cachePolicy` | no | `AsyncPreviewCachePolicy` | `cache-first` serves a fresh cache entry without a request. `always` refetches on every<br>open — for a value that changes while the reader is on the page. @default "cache-first" |
+| `staleTime` | no | `number` | How long a cache entry counts as fresh, in ms: five minutes. Entries are evicted on read;<br>nothing wakes up on a timer. @default 300_000 |
 | `open` | no | `boolean` |  |
 | `defaultOpen` | no | `boolean` |  |
 | `strings` | no | `Partial<AsyncPreviewStrings>` |  |
@@ -203,6 +219,8 @@ AsyncPreviewDynamicRootProps<TData, TContext, TType> | AsyncPreviewStaticRootPro
 
 Kind: interface.
 
+What `onShow` is given.
+
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `type` | yes | `TType` |  |
@@ -211,7 +229,7 @@ Kind: interface.
 | `reason` | yes | `AsyncPreviewReason` |  |
 | `cached` | yes | `boolean` | Whether a cache entry existed. A revalidating fetch can render through it. |
 | `setLoading` | yes | `(loading: AsyncPreviewLoadingState) => void` | Reports a slow step — "Decrypting…" — without resolving. |
-| `setMeta` | yes | `(meta: Record<string, unknown>) => void` |  |
+| `setMeta` | yes | `(meta: Record<string, unknown>) => void` | Carries a count or a permission alongside the record. |
 
 ### `AsyncPreviewSlotProps`
 
@@ -222,13 +240,14 @@ The three placeholder slots. `children` may be a function of the state, e.g. to
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `className` | no | `string` |  |
-| `children` | no | `ReactNode \| ((state: AsyncPreviewState<TData, TContext, TType>) => ReactNode)` |  |
+| `children` | no | `ReactNode \| ((state: AsyncPreviewState<TData, TContext, TType>) => ReactNode)` | Replaces the default. The function form is what an error slot wants — it is the only way<br>to show the error. |
 
 ### `AsyncPreviewState`
 
 Kind: callable.
 
-The whole state, for a preview that renders its own four cases.
+The whole state, for a preview that renders its own four cases: the escape hatch for a caller
+who genuinely wants to branch themselves.
 
 ```text
 ({ children, }: AsyncPreviewStateProps<TData, TContext, TType>) => import("react").JSX.Element
@@ -271,7 +290,7 @@ Extends: `AsyncPreviewRootBaseProps<TData, TContext, TType>`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `data` | yes | `TData \| null` |  |
+| `data` | yes | `TData \| null` | The static form, in place of `onShow`: same component, same states, no request, for a row<br>that already loaded what the preview shows. |
 | `onShow` | no | `never` |  |
 
 ### `AsyncPreviewStatus`
@@ -301,6 +320,8 @@ Kind: interface.
 
 Kind: callable.
 
+The element the preview hangs off: it opens the popover, and hovering it prefetches.
+
 ```text
 ({ children, prefetchOnHover, className, }: AsyncPreviewTriggerProps<TData, TContext, TType>) => import("react").JSX.Element
 ```
@@ -312,7 +333,7 @@ Kind: interface.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `children` | no | `ReactNode \| ((props: AsyncPreviewTriggerRenderProps<TData, TContext, TType>) => ReactElement)` | The element the preview hangs off. |
-| `prefetchOnHover` | no | `boolean` | Starts the fetch on pointer-enter, before the popover opens. |
+| `prefetchOnHover` | no | `boolean` | Starts the fetch on pointer-enter, before the popover opens — once per record. Not on<br>focus: prefetching for every trigger a keyboard user tabs past would fire a request per row. |
 | `className` | no | `string` |  |
 
 ### `AsyncPreviewTriggerRenderProps`
@@ -337,7 +358,8 @@ Clears one key, or everything. Call it after a mutation invalidates a record.
 
 Kind: callable.
 
-Binds the generics once, for a record shape used in more than one place.
+Binds the generics once, for a record shape used in more than one place, instead of restating
+them at every part.
 
 ```text
 () => { Root: ({ children, strings, ...options }: AsyncPreviewRootProps<TData, TContext, TType>) => import("react").JSX.Element; Trigger: ({ children, prefetchOnHover, className, }: AsyncPreviewTriggerProps<TData, TContext, TType>) => import("react").JSX.Element; Content: typeof AsyncPreviewContent; Body: ({ children, }: AsyncPreviewBodyProps<TData, TContext, TType>) => import("react").JSX.Element | null; State: ({ children, }: AsyncPreviewStateProps<TData, TContext, TType>) => import("react").JSX.Element; Loading: typeof AsyncPreviewLoading; Error: typeof AsyncPreviewError; Empty: typeof AsyncPreviewEmpty; }
@@ -355,6 +377,9 @@ AsyncPreviewStrings
 
 Kind: callable.
 
+The trigger, shaped for a table cell. It is a button only when there is something to open;
+otherwise the same text renders inert.
+
 ```text
 ({ value, secondary, leading, trailing, badge, icon: Icon, emptyLabel, hasPreview, disabledReason, asName, disabled, className, ...props }: PreviewTriggerCellProps) => import("react").JSX.Element
 ```
@@ -374,7 +399,7 @@ Extends: `Omit<ComponentProps<"button">, "children" | "value" | "name">`.
 | `badge` | no | `BadgeSpec` |  |
 | `icon` | no | `ComponentType<{ className?: string; }>` |  |
 | `emptyLabel` | no | `ReactNode` | Shown when `value` is absent — the em dash, unless a column wants its own word. |
-| `hasPreview` | no | `boolean` | Whether this row has a preview at all. Off renders plain text. |
+| `hasPreview` | no | `boolean` | Whether this row has a preview at all. Off renders an inert span with the same text and<br>rhythm, and no caret, pointer or popup ARIA. |
 | `disabledReason` | no | `ReactNode` | Why it is unavailable. Shown as a tooltip on the inert cell. |
 | `asName` | no | `boolean` | Runs the value through `Name` to normalise casing. |
 | `className` | no | `string` |  |
@@ -383,6 +408,9 @@ Extends: `Omit<ComponentProps<"button">, "children" | "value" | "name">`.
 
 Kind: callable.
 
+Fetching tied to a popover's open state. Closing aborts the request, only the newest request
+may write state, and a module cache keyed by `cacheKey` spares a repeat within `staleTime`.
+
 ```text
 (options: UseAsyncPreviewOptions<TData, TContext, TType>) => UseAsyncPreviewReturn<TData, TContext, TType>
 ```
@@ -391,6 +419,9 @@ Kind: callable.
 
 Kind: callable.
 
+The current state and data, for a part rendered outside the provided ones — a footer that
+counts results, a header that names what is loading.
+
 ```text
 () => AsyncPreviewState<TData, TContext, TType>
 ```
@@ -418,19 +449,277 @@ Preview route: Async preview — `/async-preview`
 ### Fetching on open
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<AsyncPreview.Root
-  type="customer"
-  context={{ id }}
-  cacheKey={`customer:${id}\
+import { useRef, useState } from "react"
+
+import { Button } from "themelia-ui/base/buttons"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { AsyncPreview, clearAsyncPreviewCache } from "themelia-ui/features/async-preview"
+
+import { CustomerCard } from "./_shared"
+import { CUSTOMERS, wait, type Customer } from "./data"
+
+export default function AsyncPreviewBasic() {
+	const [log, setLog] = useState<string[]>([])
+	const callsRef = useRef(0)
+
+	const record = (line: string) => setLog((lines) => [line, ...lines].slice(0, 6))
+
+	const fetchCustomer = async (id: string, signal: AbortSignal, delay = 700) => {
+		callsRef.current += 1
+		record(`request #${callsRef.current} → ${id}`)
+		await wait(delay, signal)
+		return CUSTOMERS[id] ?? null
+	}
+
+	return (
+		<Stack direction="horizontal" gap="lg" wrap align="center">
+			<Stack direction="horizontal" gap="xl" wrap>
+				{Object.values(CUSTOMERS).map((customer) => (
+					<AsyncPreview.Root<Customer, { id: string }, "customer">
+						key={customer.id}
+						type="customer"
+						context={{ id: customer.id }}
+						cacheKey={`customer:${customer.id}`}
+						onShow={({ context, signal }) => fetchCustomer(context.id, signal)}
+					>
+						<AsyncPreview.Trigger>{customer.name}</AsyncPreview.Trigger>
+						<AsyncPreview.Content>
+							<AsyncPreview.Loading />
+							<AsyncPreview.Error />
+							<AsyncPreview.Empty />
+							<AsyncPreview.Body>
+								{(data) => <CustomerCard customer={data as Customer} />}
+							</AsyncPreview.Body>
+						</AsyncPreview.Content>
+					</AsyncPreview.Root>
+				))}
+			</Stack>
+
+			<Stack gap="sm">
+				<Stack direction="horizontal" gap="sm" align="center">
+					<Button
+						tone="neutral"
+						buttonStyle="outline"
+						onClick={() => {
+							clearAsyncPreviewCache()
+							setLog([])
+							callsRef.current = 0
+						}}
+					>
+						Clear the cache
+					</Button>
+					<Text size="xs" type="secondary">
+						Hover one twice — the second open makes no request.
+					</Text>
+				</Stack>
+				{log.length > 0 && (
+					<Stack gap="none">
+						{log.map((line, index) => (
+							<Text key={`${line}-${index}`} size="xs" type="secondary" numeric>
+								{line}
+							</Text>
+						))}
+					</Stack>
+				)}
+			</Stack>
+		</Stack>
+	)
+}
+```
+
+### The four states
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { useRef } from "react"
+
+import { Button } from "themelia-ui/base/buttons"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { AsyncPreview } from "themelia-ui/features/async-preview"
+
+import { CustomerCard } from "./_shared"
+import { CUSTOMERS, wait, type Customer } from "./data"
+
+export default function AsyncPreviewStates() {
+	const failedOnce = useRef(false)
+
+	return (
+		<Stack direction="horizontal" gap="xl" wrap>
+			<AsyncPreview.Root<Customer, null, "slow">
+				type="slow"
+				context={null}
+				onShow={async ({ signal, setLoading }) => {
+					setLoading({ label: "Reaching the billing service…" })
+					await wait(2500, signal)
+					return CUSTOMERS["c-1"]!
+				}}
+			>
+				<AsyncPreview.Trigger>Slow, with its own label</AsyncPreview.Trigger>
+				<AsyncPreview.Content>
+					<AsyncPreview.Loading />
+					<AsyncPreview.Body>
+						{(data) => <CustomerCard customer={data as Customer} />}
+					</AsyncPreview.Body>
+				</AsyncPreview.Content>
+			</AsyncPreview.Root>
+
+			<AsyncPreview.Root<Customer, null, "failing">
+				type="failing"
+				context={null}
+				onShow={async ({ signal }) => {
+					await wait(600, signal)
+					if (!failedOnce.current) {
+						failedOnce.current = true
+						throw new Error("502 from the billing service")
+					}
+					return CUSTOMERS["c-1"]!
+				}}
+			>
+				<AsyncPreview.Trigger>Fails once, then recovers</AsyncPreview.Trigger>
+				<AsyncPreview.Content>
+					<AsyncPreview.Loading />
+					<AsyncPreview.Error />
+					<AsyncPreview.Body>{(data) => <CustomerCard customer={data as Customer} />}</AsyncPreview.Body>
+				</AsyncPreview.Content>
+			</AsyncPreview.Root>
+
+			<AsyncPreview.Root<Customer, null, "failing-custom">
+				type="failing-custom"
+				context={null}
+				onShow={async ({ signal }) => {
+					await wait(600, signal)
+					throw new Error("502 from the billing service")
+				}}
+			>
+				<AsyncPreview.Trigger>Fails, with its own copy</AsyncPreview.Trigger>
+				<AsyncPreview.Content>
+					<AsyncPreview.Loading />
+					<AsyncPreview.Error>
+						{(state) => (
+							<>
+								<Text weight="medium">Billing is unreachable</Text>
+								<Text size="xs" type="secondary">
+									{(state.error as Error).message}
+								</Text>
+								<Button tone="neutral" buttonStyle="outline" onClick={state.refresh}>
+									Try again
+								</Button>
+							</>
+						)}
+					</AsyncPreview.Error>
+					<AsyncPreview.Body>{() => null}</AsyncPreview.Body>
+				</AsyncPreview.Content>
+			</AsyncPreview.Root>
+
+			<AsyncPreview.Root<Customer, null, "missing">
+				type="missing"
+				context={null}
+				onShow={async ({ signal }) => {
+					await wait(500, signal)
+					return null
+				}}
+			>
+				<AsyncPreview.Trigger>Resolves to nothing</AsyncPreview.Trigger>
+				<AsyncPreview.Content>
+					<AsyncPreview.Loading />
+					<AsyncPreview.Empty />
+					<AsyncPreview.Body>{() => null}</AsyncPreview.Body>
+				</AsyncPreview.Content>
+			</AsyncPreview.Root>
+
+			<AsyncPreview.Root<Customer, null, "static">
+				type="static"
+				context={null}
+				data={CUSTOMERS["c-2"]!}
+			>
+				<AsyncPreview.Trigger>Already in hand</AsyncPreview.Trigger>
+				<AsyncPreview.Content>
+					<AsyncPreview.Body>
+						{(data) => <CustomerCard customer={data as Customer} />}
+					</AsyncPreview.Body>
+				</AsyncPreview.Content>
+			</AsyncPreview.Root>
+		</Stack>
+	)
+}
 ```
 
 ### PreviewTriggerCell
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<PreviewTriggerCell
-  value={row.customerName}
-  secondary={row.reference}
-  hasPreview={row.customerId !== null}
-  disabledReason="Imported without a customer record"
-/>
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "themelia-ui/base/table"
+import { AsyncPreview, PreviewTriggerCell } from "themelia-ui/features/async-preview"
+
+import { CustomerCard } from "./_shared"
+import { CUSTOMERS, wait, type Customer } from "./data"
+
+const ROWS = [
+	{ id: "c-1", reference: "INV-4417", note: "" },
+	{ id: "c-2", reference: "INV-4418", note: "" },
+	{ id: "c-3", reference: "INV-4419", note: "" },
+	{ id: null, reference: "INV-4420", note: "Imported without a customer record" },
+]
+
+const fetchCustomer = async (id: string, signal: AbortSignal, delay = 700) => {
+	await wait(delay, signal)
+	return CUSTOMERS[id] ?? null
+}
+
+export default function PreviewTriggerCellExample() {
+	return (
+		<Table>
+			<TableHeader>
+				<TableRow>
+					<TableHead>Customer</TableHead>
+					<TableHead>Reference</TableHead>
+				</TableRow>
+			</TableHeader>
+			<TableBody>
+				{ROWS.map((row) => {
+					const customer = row.id ? CUSTOMERS[row.id] : undefined
+					return (
+						<TableRow key={row.reference}>
+							<TableCell>
+								{customer ? (
+									<AsyncPreview.Root<Customer, { id: string }, "customer">
+										type="customer"
+										context={{ id: customer.id }}
+										cacheKey={`cell:${customer.id}`}
+										onShow={({ context, signal }) => fetchCustomer(context.id, signal, 450)}
+									>
+										<AsyncPreview.Trigger>
+											{() => (
+												<PreviewTriggerCell
+													value={customer.name}
+													secondary={customer.email}
+													badge={{ label: customer.plan }}
+												/>
+											)}
+										</AsyncPreview.Trigger>
+										<AsyncPreview.Content>
+											<AsyncPreview.Loading />
+											<AsyncPreview.Error />
+											<AsyncPreview.Empty />
+											<AsyncPreview.Body>
+												{(data) => <CustomerCard customer={data as Customer} />}
+											</AsyncPreview.Body>
+										</AsyncPreview.Content>
+									</AsyncPreview.Root>
+								) : (
+									<PreviewTriggerCell
+										value={null}
+										hasPreview={false}
+										disabledReason={row.note}
+									/>
+								)}
+							</TableCell>
+							<TableCell>{row.reference}</TableCell>
+						</TableRow>
+					)
+				})}
+			</TableBody>
+		</Table>
+	)
+}
 ```