themelia-ui 3.0.0 → 3.2.0

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

@@ -15,7 +15,6 @@ A trigger fetches its content when it opens, and needs loading, empty and error
 
 ```tsx fragment — import-only example
 import { AsyncPreview } from "themelia-ui/features/async-preview"
-import "themelia-ui/features/async-preview.css"
 ```
 
 ## Composition
@@ -473,8 +472,8 @@ export default function AsyncPreviewBasic() {
 	}
 
 	return (
-		<Stack direction="horizontal" gap="lg" wrap align="center">
-			<Stack direction="horizontal" gap="xl" wrap>
+		<Stack direction="horizontal" wrap align="center">
+			<Stack direction="horizontal" wrap>
 				{Object.values(CUSTOMERS).map((customer) => (
 					<AsyncPreview.Root<Customer, { id: string }, "customer">
 						key={customer.id}
@@ -500,7 +499,7 @@ export default function AsyncPreviewBasic() {
 				<Stack direction="horizontal" gap="sm" align="center">
 					<Button
 						tone="neutral"
-						buttonStyle="outline"
+						appearance="outline"
 						onClick={() => {
 							clearAsyncPreviewCache()
 							setLog([])
@@ -545,7 +544,7 @@ export default function AsyncPreviewStates() {
 	const failedOnce = useRef(false)
 
 	return (
-		<Stack direction="horizontal" gap="xl" wrap>
+		<Stack direction="horizontal" wrap>
 			<AsyncPreview.Root<Customer, null, "slow">
 				type="slow"
 				context={null}
@@ -602,7 +601,7 @@ export default function AsyncPreviewStates() {
 								<Text size="xs" type="secondary">
 									{(state.error as Error).message}
 								</Text>
-								<Button tone="neutral" buttonStyle="outline" onClick={state.refresh}>
+								<Button tone="neutral" appearance="outline" onClick={state.refresh}>
 									Try again
 								</Button>
 							</>

package/docs/generated/components/features--combobox.md

@@ -15,7 +15,6 @@ Options arrive from a fetch, the field selects application resources, or it prop
 
 ```tsx fragment — import-only example
 import { AsyncCombobox } from "themelia-ui/features/combobox"
-import "themelia-ui/features/combobox.css"
 ```
 
 ## Composition
@@ -111,7 +110,7 @@ Kind: interface.
 | `cancel` | yes | `string` |  |
 | `errorTitle` | yes | `string` | Announced when a fetch fails, above the retry control. |
 | `retry` | yes | `string` |  |
-| `removeChip` | no | `(label: string) => string` | Accessible name for a multi-select chip's remove control. Takes the chip's label. Optional for compatibility; the default supplies it. |
+| `removeChip` | yes | `(label: string) => string` | Accessible name for a multi-select chip's remove control. Takes the chip's label. |
 
 ### `AsyncMultiCombobox`
 
@@ -229,6 +228,16 @@ Browsable from the first keystroke, and preloaded on mount so the list is there
 failed fetch replaces the list content, as `AsyncCombobox`'s `showListContent` does when
 off, but keeps the selection and the query, for retry.
 
+**Use when:** Resource selection with self-owned debounce, abort and scoped requests.
+
+**Avoid when:** An existing application query/cache already owns lookup results.
+
+**Compose:** Change scopeKey when workspace/tenant/parent changes; preserve query/open state and explicitly clear an invalid controlled selection.
+
+**Capabilities:** resource selection; scoped resource lookup; pending empty error retry.
+
+**Alternatives:** AsyncCombobox, SuggestionsCombobox.
+
 ```text
 ({ fetcher, onAfterFetch, onError, getKey, getLabel, limit, debounceMs, preload, minSearchLength, defaultValue, errorMessage, ...props }: ResourceComboboxProps<T>) => import("react").JSX.Element
 ```
@@ -281,6 +290,7 @@ Extends: `Omit<AsyncComboboxProps<T>, "items" | "selectedValue" | "onSelectedVal
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `fetcher` | yes | `ResourceComboboxFetcher<T>` | Fetches the options for a query. Debounce, abort, and the race guard are owned for you,<br>and the query arrives trimmed. Honour `signal`, so an abort does not surface as a failure. |
+| `scopeKey` | no | `string \| number` | Resource scope identity. A change aborts stale lookups and refetches the current<br>eligible query. The application owns clearing a selection invalid in the new scope. |
 | `value` | no | `T \| null` | Controlled. Omit entirely to let the component own the selection. |
 | `defaultValue` | no | `T \| null` | The starting selection when uncontrolled. Ignored once `value` is passed. |
 | `onValueChange` | no | `(value: T \| null) => void` |  |
@@ -439,6 +449,7 @@ Kind: interface.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `fetchData` | yes | `(query: string, context?: SuggestionsFetchContext) => MaybePromise<T[]>` | Fetches the suggestions for a query, as an array or a promise of one. Pass<br>`context.signal` to the request: it aborts when a newer query starts. |
+| `scopeKey` | no | `string \| number` | Identity of the resource scope (workspace, tenant or parent record). Changing it<br>aborts previous work, hides its results/errors and immediately refetches an eligible<br>query. Compared with Object.is; callback identity alone never refetches. Selection,<br>query and open state survive: the application clears selections invalid in the new scope. |
 | `minQueryLength` | no | `number` | Characters required before a request is issued, not counting surrounding whitespace.<br>Defaults to 1. |
 | `debounceMs` | no | `number` | The quiet period that collapses a burst of typing into one request. Defaults to 300. |
 | `requestDelay` | no | `number` | A further wait before the fetcher runs, after the loading state is showing (unlike<br>`debounceMs`, which delays deciding to fetch). For rate-limited endpoints. @default 0 |
@@ -476,6 +487,61 @@ Kind: interface.
 
 Preview route: Combobox — `/combobox`
 
+### Scoped resource selection
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { useState } from "react"
+import { Button } from "themelia-ui/base/buttons"
+import { FormField } from "themelia-ui/base/forms"
+import { Overlay, OverlayTrigger, OverlayContent, OverlayHeader, OverlayTitle, OverlayDescription, OverlayBody } from "themelia-ui/base/overlay"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { ResourceCombobox } from "themelia-ui/features/combobox"
+
+type Resource = { id: string; label: string }
+type Mode = "results" | "pending" | "empty" | "error"
+
+export default function ScopedResourceReference() {
+	const [scope, setScope] = useState("A")
+	const [mode, setMode] = useState<Mode>("results")
+	const [query, setQuery] = useState("")
+	const [value, setValue] = useState<Resource | null>({ id: "A-1", label: "A project" })
+	const [selections, setSelections] = useState(0)
+	const [submissions, setSubmissions] = useState(0)
+	const [completions, setCompletions] = useState(0)
+	return <Overlay>
+		<OverlayTrigger render={<Button />}>Choose scoped resource</OverlayTrigger>
+		<OverlayContent>
+			<OverlayHeader><OverlayTitle>Assign resource</OverlayTitle><OverlayDescription>Lookup validity belongs to a workspace. The application decides whether a selected resource remains valid.</OverlayDescription></OverlayHeader>
+			<OverlayBody>
+				<form onSubmit={event => { event.preventDefault(); setSubmissions(count => count + 1) }}>
+					<Stack>
+						<Stack direction="horizontal" gap="sm" wrap>
+							{["A", "B"].map(key => <Button key={key} tone="neutral" appearance="outline" onClick={() => { setScope(key); setValue(null) }}>Workspace {key}</Button>)}
+						</Stack>
+						<Stack direction="horizontal" gap="sm" wrap>
+							{(["results", "pending", "empty", "error"] as const).map(key => <Button key={key} tone="neutral" appearance="ghost" onClick={() => setMode(key)}>{key}</Button>)}
+						</Stack>
+						<FormField label="Resource" hint={`Searching workspace ${scope}`}>
+							<ResourceCombobox<Resource> scopeKey={`${scope}:${mode}`} value={value} onValueChange={next => { setValue(next); setSelections(count => count + 1) }} searchValue={query} onSearchValueChange={setQuery} debounceMs={100} getKey={item => item.id} getLabel={item => item.label}
+								fetcher={async ({ query: search, signal }) => {
+									// The mock deliberately ignores abort; the picker must suppress its late answer.
+									void signal
+									await new Promise(resolve => setTimeout(resolve, mode === "pending" ? 2400 : scope === "A" ? 600 : 80))
+									if (mode === "error") throw new Error("Lookup unavailable")
+									return mode === "empty" || (search && !"project".includes(search.toLowerCase())) ? [] : [{ id: `${scope}-1`, label: `${scope} project` }]
+								}} onAfterFetch={() => setCompletions(count => count + 1)} />
+						</FormField>
+						<Button type="submit">Assign</Button>
+						<Text role="status">Selections {selections}; submissions {submissions}; completions {completions}</Text>
+					</Stack>
+				</form>
+			</OverlayBody>
+		</OverlayContent>
+	</Overlay>
+}
+```
+
 ### A picker that fetches
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
@@ -487,7 +553,7 @@ import { searchCountries, type Country } from "./data"
 
 export default function ComboboxPicker() {
 	return (
-		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
+		<Stack gap="sm" style={{ maxWidth: "26rem", width: "100%" }}>
 			<FormField label="Destination" helperText="Open it to browse, or type to search.">
 				<ResourceCombobox<Country>
 					fetcher={searchCountries}
@@ -514,7 +580,7 @@ import { matching, wait, type Country } from "./data"
 
 export default function Suggestions() {
 	return (
-		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
+		<Stack gap="sm" style={{ maxWidth: "26rem", width: "100%" }}>
 			<FormField label="Search">
 				<SuggestionsCombobox<Country>
 					fetchData={async (needle, context) => {
@@ -547,7 +613,7 @@ export default function ResourceComboboxExample() {
 	const [failing, setFailing] = useState(true)
 
 	return (
-		<Stack gap="lg" style={{ maxWidth: "26rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
 			<FormField label="Country (self-fetching)">
 				<ResourceCombobox<Country>
 					// No preload, so the error does not appear on mount.

package/docs/generated/components/features--comments.md

@@ -15,7 +15,6 @@ People discuss a record in a thread, with a composer and attachments.
 
 ```tsx fragment — import-only example
 import { CommentAttachmentChip } from "themelia-ui/features/comments"
-import "themelia-ui/features/comments.css"
 ```
 
 ## Optional peers

package/docs/generated/components/features--data-view.md

@@ -2,12 +2,12 @@
 
 # `features/data-view`
 
-One dataset is presented through switchable views with saved tabs, a toolbar and pagination.
+A resource collection needs search, filters, saved views, table controls and paging.
 
 ## Selection
 
-- **Use when:** One dataset is presented through switchable views with saved tabs, a toolbar and pagination.
-- **Avoid when:** There is one table and no view switching, or you need the table body alone.
+- **Use when:** A resource collection needs search, filters, saved views, table controls and paging.
+- **Avoid when:** Only tabular behavior is needed inside an existing application-owned browser shell.
 - **Consider instead:** `features/table`, `base/table`
 - **Stability:** stable.
 
@@ -15,7 +15,6 @@ One dataset is presented through switchable views with saved tabs, a toolbar and
 
 ```tsx fragment — import-only example
 import { DataView } from "themelia-ui/features/data-view"
-import "themelia-ui/features/data-view.css"
 ```
 
 ## Optional peers
@@ -366,6 +365,62 @@ Kind: interface.
 
 Preview route: Data view & data table — `/data-view`
 
+### Server resource index reference
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { useEffect, useRef, useState } from "react"
+import { Button } from "themelia-ui/base/buttons"
+import { Stack } from "themelia-ui/base/structure"
+import { Heading, Text } from "themelia-ui/base/typography"
+import { DataView, type DataViewProps } from "themelia-ui/features/data-view"
+import { FilterType, type ActiveFilter, type FilterConfig } from "themelia-ui/features/filters"
+
+type RecordRow = { id: string; name: string; status: string; searchTerms: string }
+const RECORDS: RecordRow[] = Array.from({ length: 6 }, (_, index) => ({ id: `r${index + 1}`, name: `Resource ${index + 1}`, status: index % 2 ? "Closed" : "Open", searchTerms: "hidden reference term" }))
+const COLUMNS: DataViewProps<RecordRow>["columns"] = [{ accessorKey: "name", header: "Resource" }, { accessorKey: "status", header: "Status" }]
+const FILTERS: FilterConfig[] = [{ key: "search", label: "Search hidden metadata and resource names", type: FilterType.SEARCH }, { key: "status", label: "Publication and review status with a long translated label", type: FilterType.SELECT, options: [{ value: "Open", label: "Open" }, { value: "Closed", label: "Closed" }] }]
+
+export default function ResourceIndexReference() {
+	const [filters, setFilters] = useState<ActiveFilter[]>([])
+	const [page, setPage] = useState(0)
+	const [rows, setRows] = useState<RecordRow[]>([])
+	const [hasNext, setHasNext] = useState(false)
+	const [pending, setPending] = useState(true)
+	const [error, setError] = useState<string>()
+	const [refresh, setRefresh] = useState(0)
+	const [selection, setSelection] = useState<Record<string, true>>({})
+	const [answeredQuery, setAnsweredQuery] = useState("")
+	const [commands, setCommands] = useState("")
+	const failNext = useRef(false)
+	useEffect(() => {
+		let active = true
+		async function load() {
+			setPending(true); setError(undefined)
+			await new Promise(resolve => setTimeout(resolve, 250))
+			if (!active) return
+			if (failNext.current) { failNext.current = false; setError("Refresh failed. Previous rows remain available."); setPending(false); return }
+			const search = filters.find(filter => filter.key === "search")?.value[0]?.toLowerCase() ?? ""
+			const status = filters.find(filter => filter.key === "status")?.value[0]
+			const matches = RECORDS.filter(row => `${row.name} ${row.searchTerms}`.toLowerCase().includes(search) && (!status || row.status === status))
+			setAnsweredQuery(search); setRows(matches.slice(page * 2, page * 2 + 2)); setHasNext(matches.length > page * 2 + 2); setPending(false)
+		}
+		void load()
+		return () => { active = false }
+	}, [filters, page, refresh])
+	return <div style={{ width: "100%", minWidth: 0, maxWidth: "48rem" }}>
+		<Stack>
+			<Heading level={3}>Resource index</Heading>
+			<Text type="secondary">Server matching includes fields absent from the visible columns. Totals are unknown; selection applies to the current page.</Text>
+			{error && <Text role="alert" type="error">{error}</Text>}
+			<DataView data={rows} columns={COLUMNS} filtering={{ filters: FILTERS, activeFilters: filters, onFilterChange: next => { setFilters(next); setPage(0); setSelection({}) }, filterRows: ({ data }) => [...data], isFiltering: pending }}
+				table={{ enableColumnVisibility: true, enableRowSelection: true, getRowId: row => row.id, rowSelection: selection, onRowSelectionChange: setSelection, bulkActions: ({ selectedRows }) => <Button onClick={() => setCommands(`Selected-page command: ${selectedRows.map(row => row.id).join(", ")}`)}>Archive selected page rows</Button> }}
+				slots={{ topbarEnd: <Stack direction="horizontal" gap="sm" wrap><Button tone="neutral" appearance="outline" disabled={pending} onClick={() => setRefresh(count => count + 1)}>Refresh</Button><Button tone="neutral" appearance="outline" onClick={() => { failNext.current = true; setRefresh(count => count + 1) }}>Fail next refresh</Button><Button tone="neutral" appearance="outline" onClick={() => setCommands(`Export current page: ${rows.map(row => row.id).join(", ")}`)}>Export page</Button></Stack>, footer: <Stack direction="horizontal" wrap align="center"><Text>Total unknown; page {page + 1}</Text><Button disabled={pending || page === 0} onClick={() => { setPage(value => value - 1); setSelection({}) }}>Previous page</Button><Button disabled={pending || !hasNext} onClick={() => { setPage(value => value + 1); setSelection({}) }}>Next page</Button></Stack> }} />
+			<Text role="status">{pending ? "Loading page" : `${rows.length} rows supplied by server; matched ${answeredQuery || "all"}`}{commands && `; ${commands}`}</Text>
+		</Stack>
+	</div>
+}
+```
+
 ### An index
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
@@ -386,7 +441,7 @@ const keepPage = ({ data }: { data: readonly Booking[] }) => data as Booking[]
 
 function ResetViewButton({ disabled, onReset }: { disabled: boolean; onReset: () => void }) {
 	const { clearFilters } = useFilters()
-	return <Button tone="neutral" buttonStyle="outline" disabled={disabled}
+	return <Button tone="neutral" appearance="outline" disabled={disabled}
 		onClick={() => { clearFilters(); onReset() }}>Reset view</Button>
 }
 
@@ -433,7 +488,7 @@ export default function DataViewExample() {
 				enableColumnVisibility: true,
 				getRowId: (row) => row.id,
 				emptyStateMessage: "No bookings match your filters",
-				emptyStateAction: <Button tone="neutral" buttonStyle="outline" onClick={() => updateFilters([])}>Clear filters</Button>,
+				emptyStateAction: <Button tone="neutral" appearance="outline" onClick={() => updateFilters([])}>Clear filters</Button>,
 			}}
 			slots={{
 				topbarEnd: <ResetViewButton
@@ -480,7 +535,7 @@ export default function DataViewStates() {
 				<Select aria-label="Result state" value={requestState} className={styles.stateSelect}
 					options={[{ value: "ready", label: "Ready" }, { value: "pending", label: "Updating" }, { value: "error", label: "Failed" }]}
 					onValueChange={(value) => value && setRequestState(value)} />
-				{requestState === "error" && <Button tone="neutral" buttonStyle="outline" onClick={() => setRequestState("ready")}>Restore results</Button>}
+				{requestState === "error" && <Button tone="neutral" appearance="outline" onClick={() => setRequestState("ready")}>Restore results</Button>}
 			</Stack>
 			<DataView<Booking> data={BOOKINGS.slice(0, 3)} columns={indexColumns}
 				filtering={{ filters: FILTERS, activeFilters: recoveryFilters, onFilterChange: setRecoveryFilters,
@@ -488,7 +543,7 @@ export default function DataViewStates() {
 					filterRows: requestState === "error" ? () => { throw new Error("Preview matcher failure") } : undefined,
 				}}
 				table={{ getRowId: (row) => row.id, emptyStateMessage: "No bookings match your filters",
-					emptyStateAction: <Button tone="neutral" buttonStyle="outline" onClick={() => setRecoveryFilters([])}>Clear filters</Button> }} />
+					emptyStateAction: <Button tone="neutral" appearance="outline" onClick={() => setRecoveryFilters([])}>Clear filters</Button> }} />
 		</>
 	)
 }

package/docs/generated/components/features--event-calendar.md

@@ -8,14 +8,13 @@ Events are placed on a calendar the user navigates by period.
 
 - **Use when:** Events are placed on a calendar the user navigates by period.
 - **Avoid when:** The user is picking a date, or the sequence is chronological rather than spatial.
-- **Consider instead:** `base/date-pickers`, `patterns/timelines`
+- **Consider instead:** `base/date-pickers`, `blocks/timelines`
 - **Stability:** stable.
 
 ## Import
 
 ```tsx fragment — import-only example
 import { EventCalendar } from "themelia-ui/features/event-calendar"
-import "themelia-ui/features/event-calendar.css"
 ```
 
 ## Composition

package/docs/generated/components/features--filters.md

@@ -15,7 +15,6 @@ Users build predicates over fields, with operators, editors and pills.
 
 ```tsx fragment — import-only example
 import { AsyncFilterEditor } from "themelia-ui/features/filters"
-import "themelia-ui/features/filters.css"
 ```
 
 ## Composition
@@ -293,6 +292,16 @@ Kind: callable.
 The default bar: saved tabs, search boxes, active pills, always-shown pills, the add button,
 then Clear. For a custom bar, place the exported parts using `useFilterGroups()`.
 
+**Use when:** Responsive filter controls shared between a desktop region and mobile sheet.
+
+**Avoid when:** A complete resource browser already provides its filter layout, or the controls are page commands.
+
+**Compose:** Share controlled filter state across presentations. Place create and export in action slots outside filter controls.
+
+**Capabilities:** responsive filters; mobile sheet desktop filter region.
+
+**Alternatives:** —.
+
 ```text
 ({ className, dynamicFilterOptions, loadingFilters, variant, showClearFilters, tabs, mobilePresentation, }: FilterLayoutProps) => import("react").JSX.Element
 ```
@@ -1103,7 +1112,7 @@ export default function Filters() {
 	return (
 		<>
 			<Stack direction="horizontal" gap="sm">
-				<Button tone="neutral" buttonStyle="outline" onClick={() => setNavigating((current) => !current)}>
+				<Button tone="neutral" appearance="outline" onClick={() => setNavigating((current) => !current)}>
 					{navigating ? "Resume filtering" : "Show pending state"}
 				</Button>
 			</Stack>

package/docs/generated/components/features--global-search.md

@@ -15,7 +15,6 @@ One search surface spans record types, with tabs, idle and empty states.
 
 ```tsx fragment — import-only example
 import { GlobalSearch } from "themelia-ui/features/global-search"
-import "themelia-ui/features/global-search.css"
 ```
 
 ## Composition
@@ -477,7 +476,7 @@ export default function Dialog() {
 
 	return (
 		<>
-			<Stack direction="horizontal" gap="md" align="center">
+			<Stack direction="horizontal" gap="sm" align="center">
 				<Button type="button" onClick={() => setOpen(true)}>Open the palette</Button>
 				<Text size="sm" type="secondary">Then press Escape, or click outside it.</Text>
 			</Stack>

package/docs/generated/components/features--kanban.md

@@ -15,7 +15,6 @@ Records move between columns by dragging, and the board owns that state.
 
 ```tsx fragment — import-only example
 import { Kanban } from "themelia-ui/features/kanban"
-import "themelia-ui/features/kanban.css"
 ```
 
 ## Optional peers
@@ -442,7 +441,7 @@ export default function KanbanExample() {
 								{(board[column.id] ?? []).map((card) => (
 									<KanbanItem key={card.id} value={card.id}>
 										<Card className={styles.card}>
-											<Stack direction="horizontal" align="start" gap="xs">
+											<Stack direction="horizontal" align="start" gap="sm">
 												<KanbanItemHandle />
 												<Text size="sm" weight="medium" className={styles.cardTitle}>
 													{card.title}

package/docs/generated/components/features--map.md

@@ -15,7 +15,6 @@ Geographic data is displayed or drawn, including markers, shapes and draw contro
 
 ```tsx fragment — import-only example
 import { Map } from "themelia-ui/features/map"
-import "themelia-ui/features/map.css"
 ```
 
 ## Optional peers
@@ -838,7 +837,7 @@ export default function PlaceAutocompleteExample() {
 
 	return (
 		<>
-			<Stack maxWidth="24rem">
+			<Stack gap="sm" maxWidth="24rem">
 				<PlaceAutocomplete limit={5} onPlaceSelect={setPlace} />
 			</Stack>
 			{!!place && (