themelia-ui 2.0.0 → 3.0.0

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

@@ -20,7 +20,7 @@ import "themelia-ui/features/data-view.css"
 
 ## Optional peers
 
-Install these only when importing this family:
+Install these only when importing this module:
 
 ```bash
 npm install @tanstack/react-table
@@ -28,7 +28,7 @@ npm install @tanstack/react-table
 
 ## Composition
 
-This family composes `base/choice-inputs`, `base/feedback`, `base/navigation`, `base/structure`, `base/typography`, `features/filters`, `features/table`.
+This module composes `base/choice-inputs`, `base/feedback`, `base/navigation`, `base/structure`, `base/typography`, `features/filters`, `features/table`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -49,6 +49,9 @@ Filters are ANDed; the values within one filter are ORed.
 
 Kind: callable.
 
+The filter bar and the table as one surface: filter state, row filtering, the bar inside the
+table's topbar, and pagination, all against one row set.
+
 **Use when:** A resource browser combining a table, search, filters and saved views.
 
 **Avoid when:** Only needing a table or replacing one small visual region with a new state machine.
@@ -72,12 +75,12 @@ Kind: interface.
 | `filters` | yes | `FilterConfig[]` |  |
 | `activeFilters` | yes | `ActiveFilter[]` |  |
 | `onFilterChange` | yes | `(filters: ActiveFilter[]) => void` |  |
-| `filterRows` | no | `DataViewFilterRows<TData>` |  |
-| `getFilterValue` | no | `DataViewFilterValueGetter<TData>` |  |
+| `filterRows` | no | `DataViewFilterRows<TData>` | Replaces the built-in matching entirely. What a server-filtered index passes: the rows are<br>already right, so nothing local runs. |
+| `getFilterValue` | no | `DataViewFilterValueGetter<TData>` | Reads the value a filter compares against, for a nested or computed field. Without it the<br>filter's key is read as a path. |
 | `tabs` | no | `FilterTab[]` |  |
-| `tabsDisplay` | no | `"tabs" \| "select"` | A tab row, or a select — the same saved views, at two widths. |
+| `tabsDisplay` | no | `"tabs" \| "select"` | A tab row, or a select — the same saved views, at two widths. A tab row is better when it<br>fits and useless when it does not, and a bar carrying five pills often does not. |
 | `tabsLabel` | no | `string` |  |
-| `mobilePresentation` | no | `"sheet" \| "inline"` | Narrow viewports use the filters sheet by default. |
+| `mobilePresentation` | no | `"sheet" \| "inline"` | Below 768px, `sheet` keeps search inline and opens filter editors in an inset sheet.<br>Choose `inline` for a caller-owned mobile layout. @default "sheet" |
 | `isFiltering` | no | `boolean` | A change is in flight; the bar dims. |
 | `strings` | no | `Partial<FilterStrings>` |  |
 | `onError` | no | `FilterErrorHandler` |  |
@@ -116,6 +119,9 @@ Reads the value a filter compares against, for a nested or computed field.
 
 Kind: callable.
 
+Keeps the result summary visible, including zero results. Page controls appear only above
+one page; `disabled` makes every control unavailable to pointer and keyboard users.
+
 ```text
 ({ page, pageCount, total, onPageChange, disabled, className, strings, }: DataViewPaginationProps) => import("react").JSX.Element | null
 ```
@@ -151,18 +157,20 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `data` | yes | `readonly TData[]` |  |
-| `columns` | yes | `DataTableProps<TData, TValue>["columns"]` |  |
-| `filtering` | no | `DataViewFilteringConfig<TData>` |  |
-| `strings` | no | `Partial<DataViewStrings>` |  |
-| `table` | no | `DataViewTableOptions<TData, TValue>` |  |
-| `slots` | no | `DataViewSlots` |  |
+| `data` | yes | `readonly TData[]` | The rows, passed straight through to DataTable after the filters have run. |
+| `columns` | yes | `DataTableProps<TData, TValue>["columns"]` | Passed straight through to DataTable. |
+| `filtering` | no | `DataViewFilteringConfig<TData>` | `filters`, `activeFilters` and `onFilterChange` are meaningless apart — two of the three<br>describe a state nobody can read — so they travel as one object the whole feature can be<br>optional on. Without it a DataView is a table in a frame. |
+| `strings` | no | `Partial<DataViewStrings>` | Customizes the filter failure warning, `filterError`. Filter-control copy belongs to<br>`filtering.strings`; pager copy belongs to `DataViewPagination`'s `strings`. |
+| `table` | no | `DataViewTableOptions<TData, TValue>` | Everything DataTable takes except `columns`, `data`, `surface`, `headerTransparent`, and<br>the two topbar slots — the view owns those. |
+| `slots` | no | `DataViewSlots` | `topbarContent` above the bar, `toolbarStart` and `toolbarAfterFilters` around the<br>saved-view select, `topbarEnd` beside the table's controls, `footer` below the table. |
 | `className` | no | `string` |  |
 
 ### `DataViewShell`
 
 Kind: callable.
 
+The plain shell, for composing the same rhythm around something that is not a DataTable.
+
 ```text
 ({ children, header, toolbar, footer, emptySlot, empty, className, contentClassName, }: DataViewShellProps) => import("react").JSX.Element
 ```
@@ -190,7 +198,7 @@ Kind: interface.
 | --- | :-: | --- | --- |
 | `topbarContent` | no | `ReactNode` | Above the filter bar, inside the table's topbar. |
 | `toolbarStart` | no | `ReactNode` | Leading content in the auxiliary row, beside the saved-view select. |
-| `toolbarAfterFilters` | no | `ReactNode` |  |
+| `toolbarAfterFilters` | no | `ReactNode` | Content in the auxiliary row, after the saved-view select. |
 | `topbarEnd` | no | `ReactNode` | Trailing content in the table's topbar, beside its own controls. |
 | `footer` | no | `ReactNode` | Below the table, inside the frame. |
 
@@ -206,6 +214,10 @@ Kind: interface.
 
 Kind: callable.
 
+The table frame the filter bar sits in, with the bar in the table's topbar so filtering and
+the data it filters scroll as one. It works bare too, around something that is not a
+DataTable.
+
 ```text
 ({ toolbar, children, footer, className, toolbarClassName, contentClassName, footerClassName, }: DataViewTableFrameProps) => import("react").JSX.Element
 ```
@@ -238,6 +250,10 @@ Omit<DataTableProps<TData, TValue>, "columns" | "data" | "surface" | "headerTran
 
 Kind: callable.
 
+The filter bar. In a DataView it lives inside the table's topbar rather than above it, so
+filtering and the data it filters are one surface and scroll as one. It works bare too,
+around something that is not a DataTable.
+
 ```text
 ({ leading, search, filters, views, actions, className, }: DataViewToolbarProps) => import("react").JSX.Element
 ```
@@ -294,7 +310,10 @@ Kind: interface.
 
 Kind: callable.
 
-A saved-view row that is NOT filter-driven — for a consumer holding views themselves.
+A compact select of saved views that is NOT filter-driven — for a consumer holding views
+themselves. The caller controls the selected view and applies its state through
+`onValueChange`. For filter-driven tabs, or a select with exact preset matching, use
+DataView's `filtering.tabs` or FilterTabs.
 
 ```text
 ({ views, value, onValueChange, className }: SavedViewTabsProps) => import("react").JSX.Element
@@ -315,6 +334,11 @@ Kind: interface.
 
 Kind: callable.
 
+The rows after filtering, plus `failed` and the `error` for a custom surface. If a matcher
+throws, the unfiltered rows come back with `failed` set and `onError` called, rather than a
+misleading empty list; DataView shows a warning for this fallback, which `strings.filterError`
+customizes.
+
 ```text
 ({ data, filtering, }: UseDataViewOptions<TData>) => UseDataViewResult<TData>
 ```
@@ -345,42 +369,127 @@ Preview route: Data view & data table — `/data-view`
 ### An index
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-// Filter and sort the complete collection before slicing a page.
-// A server-backed view can pass the returned page and total instead.
-const { rows } = useDataView({ data: bookings, filtering })
-const sorted = useLegacyTable({
-  data: rows, columns, state: { sorting },
-  getCoreRowModel: getCoreRowModel(),
-  getSortedRowModel: getSortedRowModel(),
-})
-const sortedRows = sorted.getRowModel().rows.map((row) => row.original)
-const pageRows = sortedRows.slice((page - 1) * pageSize, page * pageSize)
-
-<DataView
-  data={pageRows}
-  columns={columns}
-  filtering={{
-    ...filtering,
-    filterRows: ({ data }) => data, // Already filtered before paging.
-    tabs: savedViews,
-  }}
-  table={{ enableSorting: true, manualSorting: true, sorting, onSortingChange }}
-  slots={{ footer: <DataViewPagination
-    page={page}
-    pageCount={Math.ceil(rows.length / pageSize)}
-    total={resultSummary}
-    onPageChange={setPage}
-  /> }}
-/>
+import { useState } from "react"
+import type { SortingState } from "@tanstack/react-table"
+import { getCoreRowModel, getSortedRowModel, useLegacyTable } from "@tanstack/react-table/legacy"
+
+import { Button } from "themelia-ui/base/buttons"
+import { DataView, DataViewPagination, useDataView } from "themelia-ui/features/data-view"
+import { useFilters, type ActiveFilter } from "themelia-ui/features/filters"
+
+import { FILTERS, indexColumns } from "./_shared"
+import { BOOKINGS, TABS, type Booking } from "./data"
+
+const PAGE_SIZE = 3
+// Filtering has already run before sorting and paging. DataView still owns the controls.
+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}
+		onClick={() => { clearFilters(); onReset() }}>Reset view</Button>
+}
+
+export default function DataViewExample() {
+	const [active, setActive] = useState<ActiveFilter[]>([])
+	const [page, setPage] = useState(1)
+	const [sorting, setSorting] = useState<SortingState>([])
+	const updateFilters = (next: ActiveFilter[]) => {
+		setActive(next)
+		setPage(1)
+	}
+	const { rows } = useDataView({ data: BOOKINGS, filtering: {
+		filters: FILTERS, activeFilters: active, onFilterChange: updateFilters,
+	} })
+
+	const sorted = useLegacyTable({
+		data: rows as Booking[], columns: indexColumns, state: { sorting },
+		getCoreRowModel: getCoreRowModel(), getSortedRowModel: getSortedRowModel(),
+	})
+	const pageCount = Math.ceil(rows.length / PAGE_SIZE)
+	const currentPage = Math.min(page, Math.max(1, pageCount))
+	const start = (currentPage - 1) * PAGE_SIZE
+	const pageRows = sorted.getRowModel().rows.slice(start, start + PAGE_SIZE).map((row) => row.original)
+	const summary = pageCount > 1
+		? `${start + 1}–${start + pageRows.length} of ${rows.length} bookings`
+		: `${rows.length} ${rows.length === 1 ? "booking" : "bookings"}`
+
+	return (
+		<DataView<Booking>
+			data={pageRows}
+			columns={indexColumns}
+			filtering={{
+				filters: FILTERS,
+				activeFilters: active,
+				onFilterChange: updateFilters,
+				filterRows: keepPage,
+				tabs: TABS,
+			}}
+			table={{
+				enableSorting: true,
+				manualSorting: true,
+				sorting,
+				onSortingChange: (next) => { setSorting(next); setPage(1) },
+				enableColumnVisibility: true,
+				getRowId: (row) => row.id,
+				emptyStateMessage: "No bookings match your filters",
+				emptyStateAction: <Button tone="neutral" buttonStyle="outline" onClick={() => updateFilters([])}>Clear filters</Button>,
+			}}
+			slots={{
+				topbarEnd: <ResetViewButton
+					disabled={active.length === 0 && sorting.length === 0 && currentPage === 1}
+					onReset={() => { setSorting([]); setPage(1) }} />,
+				footer: (
+					<DataViewPagination
+						page={currentPage}
+						pageCount={pageCount}
+						total={summary}
+						onPageChange={setPage}
+					/>
+				),
+			}}
+		/>
+	)
+}
 ```
 
 ### Pending results and recovery
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<DataView data={bookings} columns={columns} filtering={{
-  filters, activeFilters, onFilterChange,
-  isFiltering: pending,
-  filterRows: matchRows,
-  onError: reportError,
-}} />
+import { useState } from "react"
+
+import { Button } from "themelia-ui/base/buttons"
+import { Select } from "themelia-ui/base/choice-inputs"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { DataView } from "themelia-ui/features/data-view"
+import type { ActiveFilter } from "themelia-ui/features/filters"
+
+import { FILTERS, indexColumns } from "./_shared"
+import { BOOKINGS, TABS, type Booking } from "./data"
+import styles from "./data-view-states.module.css"
+
+export default function DataViewStates() {
+	const [requestState, setRequestState] = useState("ready")
+	const [recoveryFilters, setRecoveryFilters] = useState<ActiveFilter[]>([])
+
+	return (
+		<>
+			<Stack direction="horizontal" align="center" gap="sm" wrap>
+				<Text size="sm" type="secondary">Result state</Text>
+				<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>}
+			</Stack>
+			<DataView<Booking> data={BOOKINGS.slice(0, 3)} columns={indexColumns}
+				filtering={{ filters: FILTERS, activeFilters: recoveryFilters, onFilterChange: setRecoveryFilters,
+					tabs: TABS, isFiltering: requestState === "pending",
+					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> }} />
+		</>
+	)
+}
 ```

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

@@ -20,7 +20,7 @@ import "themelia-ui/features/event-calendar.css"
 
 ## Composition
 
-This family composes `base/action-menu`, `base/buttons`, `base/choice-inputs`, `base/date-pickers`, `base/display`, `base/feedback`, `base/popover`, `base/typography`.
+This module composes `base/action-menu`, `base/buttons`, `base/choice-inputs`, `base/date-pickers`, `base/display`, `base/feedback`, `base/popover`, `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.
@@ -105,6 +105,9 @@ EventCalendarStrings
 
 Kind: callable.
 
+A month grid, a week strip, or an agenda over one list of events. Views change only the day
+range and layout; placing events onto days is shared.
+
 ```text
 ({ events, categories, viewMode, defaultViewMode, onViewModeChange, date, defaultDate, onDateChange, onEventClick, onDayClick, maxEventsPerDay, showLegend, showHeader, showWeekends, weekStartsOn: weekStartsOnProp, locale, enableCategoryFilter, visibleCategories: controlledVisibleCategories, onVisibleCategoriesChange, loading, emptyStateMessage, className, compact, actions, strings, dayHeadingVariant, dayHeadingClassName, renderDayHeading, rangeMode, minDate, maxDate, disabledDates, filterEvent, renderEvent, renderDayCell, }: EventCalendarProps) => import("react").JSX.Element
 ```
@@ -113,6 +116,10 @@ Kind: callable.
 
 Kind: callable.
 
+One day in the grid. Deliberately not a button: a cell holds events that are themselves
+pressable, and nesting controls makes both unreachable by keyboard. The day number is the
+keyboard affordance; the cell's click only widens the pointer target.
+
 ```text
 ({ data, categories, maxEvents, onClick, onEventClick, compact, strings, renderEvent, }: EventCalendarDayCellProps) => import("react").JSX.Element
 ```
@@ -144,6 +151,9 @@ Kind: type.
 
 Kind: callable.
 
+One event as a chip in a day cell: a category dot, the title and the start time. At the
+narrowest widths only the dot remains.
+
 ```text
 ({ event, category, compact, onClick, strings, }: EventCalendarEventBadgeProps) => import("react").JSX.Element
 ```
@@ -164,6 +174,10 @@ Kind: interface.
 
 Kind: callable.
 
+One event in full, for an agenda row or a popover. The card reads its metadata by name —
+`customerName`, `guestCount`, `serviceName` — so a consumer's own fields appear without a
+mapping step.
+
 ```text
 ({ event, category, onClick, strings, className, }: EventCalendarEventCardPropsWithStrings) => import("react").JSX.Element
 ```
@@ -203,6 +217,9 @@ Kind: interface.
 
 Kind: callable.
 
+The period and the controls that move it. The month jump is icon-only because the label
+beside it already names the month — spelling it on the button too is the same word twice.
+
 ```text
 ({ currentDate, viewMode, displayLabel, onPrevious, onNext, onToday, onViewModeChange, onDateChange, actions, strings, rangeMode, minDate, maxDate, prevDisabled, nextDisabled, className, }: EventCalendarHeaderProps) => import("react").JSX.Element
 ```
@@ -235,6 +252,9 @@ Kind: interface.
 
 Kind: callable.
 
+The category key, and the filter when one is wired. The WHOLE chip toggles rather than a
+checkbox beside a swatch — the swatch is the target a reader aims at anyway.
+
 ```text
 ({ categories, visibleCategories, onToggleCategory, enableFiltering, strings, className, }: EventCalendarLegendProps) => import("react").JSX.Element | null
 ```
@@ -258,24 +278,24 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `events` | yes | `CalendarEvent[]` | The calendar does no fetching of its own. |
-| `categories` | yes | `EventCategory[]` |  |
-| `viewMode` | no | `CalendarViewMode` |  |
-| `defaultViewMode` | no | `CalendarViewMode` |  |
+| `events` | yes | `CalendarEvent[]` | The calendar does no fetching of its own. An event with an `endDate` appears on every day<br>it spans, not only its first. |
+| `categories` | yes | `EventCategory[]` | The categories events name. Each owns its colour, so colour is defined once. |
+| `viewMode` | no | `CalendarViewMode` | Controlled. The switcher works either way. Week steps by weeks; month and agenda step by<br>months. |
+| `defaultViewMode` | no | `CalendarViewMode` | Uncontrolled: the view to start in. |
 | `onViewModeChange` | no | `(mode: CalendarViewMode) => void` |  |
-| `date` | no | `Date` |  |
-| `defaultDate` | no | `Date` |  |
+| `date` | no | `Date` | Where the calendar is looking. Controlled, like the view. |
+| `defaultDate` | no | `Date` | Uncontrolled: where the calendar starts looking. |
 | `onDateChange` | no | `(date: Date) => void` |  |
-| `onEventClick` | no | `(event: CalendarEvent) => void` |  |
-| `onDayClick` | no | `(date: Date, events: CalendarEvent[]) => void` | Fires with the day and everything on it. |
-| `maxEventsPerDay` | no | `number` | Chips drawn per day before the rest collapse into an overflow line. |
+| `onEventClick` | no | `(event: CalendarEvent) => void` | A chip press calls this and stops there. |
+| `onDayClick` | no | `(date: Date, events: CalendarEvent[]) => void` | A press anywhere else in a day's cell calls this, with the day and everything on it. |
+| `maxEventsPerDay` | no | `number` | Chips drawn per day before the rest collapse into an overflow line. The overflow dots are<br>the categories of the HIDDEN events, not the first three in the list. |
 | `showLegend` | no | `boolean` |  |
 | `showHeader` | no | `boolean` |  |
 | `showWeekends` | no | `boolean` |  |
-| `weekStartsOn` | no | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | 0 is Sunday. Falls back to the provider's dates config, then Monday. |
+| `weekStartsOn` | no | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | 0 is Sunday. Falls back to the provider's dates config, then Monday — the same source the<br>kit's own pickers read. |
 | `locale` | no | `Locale` |  |
 | `enableCategoryFilter` | no | `boolean` | Makes the legend chips toggle their category. |
-| `visibleCategories` | no | `string[]` | Ids currently shown. Empty means all. |
+| `visibleCategories` | no | `string[]` | Ids currently shown. An EMPTY list means all are shown — a filter nobody has touched hides<br>nothing. |
 | `onVisibleCategoriesChange` | no | `(categories: string[]) => void` |  |
 | `loading` | no | `boolean` |  |
 | `emptyStateMessage` | no | `string` |  |
@@ -288,11 +308,11 @@ Kind: interface.
 | `renderDayHeading` | no | `(day: string, index: number) => ReactNode` |  |
 | `rangeMode` | no | `EventCalendarRangeMode` |  |
 | `minDate` | no | `Date` | Navigation stops here, and days beyond it are drawn but not clickable. |
-| `maxDate` | no | `Date` |  |
-| `disabledDates` | no | `DateRule` |  |
-| `filterEvent` | no | `EventFilter` | Hides events at render time without touching `events`. |
-| `renderEvent` | no | `RenderEventFn` |  |
-| `renderDayCell` | no | `RenderDayCellFn` |  |
+| `maxDate` | no | `Date` | Navigation stops here, and days beyond it are drawn but not clickable. |
+| `disabledDates` | no | `DateRule` | Days drawn but not clickable. A `DateRule` takes dates, a predicate, or both, combined<br>with OR. |
+| `filterEvent` | no | `EventFilter` | Hides events at render time without touching `events`. Counts and the overflow line<br>follow it, so what is drawn and what is counted agree. |
+| `renderEvent` | no | `RenderEventFn` | Replaces how an event draws: its chip in a day cell, its card in the agenda. |
+| `renderDayCell` | no | `RenderDayCellFn` | Replaces a day's cell. It receives `defaultRender`, so decorating is as easy as replacing. |
 
 ### `EventCalendarRangeMode`
 
@@ -393,6 +413,10 @@ The only fallback: a category that is missing entirely.
 
 Kind: callable.
 
+The date, the view, and the days — for a calendar whose surface is entirely yours. Each is
+independently controllable: the prop wins when given, and setters always call the consumer's
+handler.
+
 ```text
 ({ events, date, defaultDate, viewMode, defaultViewMode, onDateChange, onViewModeChange, dataOptions, }: UseEventCalendarOptions) => UseEventCalendarResult
 ```
@@ -455,28 +479,103 @@ Preview route: Event calendar — `/event-calendar`
 ### The grid
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<EventCalendar
-  events={events}
-  categories={categories}
-  enableCategoryFilter
-  onEventClick={(event) => open(event.id)}
-  onDayClick={(date, events) => setDay({ date, events })}
-/>
+import { useState } from "react"
+import { PlusIcon } from "lucide-react"
+
+import { Text } from "themelia-ui/base/typography"
+import { EventCalendar, type CalendarViewMode } from "themelia-ui/features/event-calendar"
+
+import { CATEGORIES } from "./_shared"
+import { EVENTS, MONTH } from "./data"
+
+export default function Month() {
+	const [view, setView] = useState<CalendarViewMode>("month")
+	const [picked, setPicked] = useState<string | null>(null)
+	const [visible, setVisible] = useState<string[]>([])
+
+	return (
+		<>
+			<EventCalendar
+				events={EVENTS}
+				categories={CATEGORIES}
+				defaultDate={MONTH}
+				viewMode={view}
+				onViewModeChange={setView}
+				enableCategoryFilter
+				visibleCategories={visible}
+				onVisibleCategoriesChange={setVisible}
+				maxEventsPerDay={2}
+				actions={[{ id: "new", label: "New booking", icon: PlusIcon, onClick: () => setPicked("new booking") }]}
+				onEventClick={(event) => setPicked(event.title)}
+				onDayClick={(date, events) =>
+					setPicked(`${date.toDateString()} — ${events.length} event${events.length === 1 ? "" : "s"}`)
+				}
+			/>
+			{!!picked && <Text size="sm" type="secondary">picked: {picked}</Text>}
+		</>
+	)
+}
 ```
 
 ### The agenda
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<EventCalendar viewMode="agenda" events={events} categories={categories} />
+import { useState } from "react"
+
+import { Text } from "themelia-ui/base/typography"
+import { EventCalendar } from "themelia-ui/features/event-calendar"
+
+import { CATEGORIES } from "./_shared"
+import { EVENTS, MONTH } from "./data"
+
+export default function Agenda() {
+	const [picked, setPicked] = useState<string | null>(null)
+
+	return (
+		<>
+			<EventCalendar
+				events={EVENTS}
+				categories={CATEGORIES}
+				defaultDate={MONTH}
+				viewMode="agenda"
+				showLegend={false}
+				onEventClick={(event) => setPicked(event.title)}
+			/>
+			{!!picked && <Text size="sm" type="secondary">picked: {picked}</Text>}
+		</>
+	)
+}
 ```
 
 ### A week, and a range
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<EventCalendar
-  viewMode="week"
-  minDate={new Date(2026, 8, 1)}
-  maxDate={new Date(2026, 8, 30)}
-  disabledDates={(date) => date.getDay() === 0}
-/>
+import { useState } from "react"
+
+import { Text } from "themelia-ui/base/typography"
+import { EventCalendar } from "themelia-ui/features/event-calendar"
+
+import { CATEGORIES } from "./_shared"
+import { EVENTS } from "./data"
+
+export default function Week() {
+	const [picked, setPicked] = useState<string | null>(null)
+
+	return (
+		<>
+			<EventCalendar
+				events={EVENTS}
+				categories={CATEGORIES}
+				defaultDate={new Date(2026, 8, 14)}
+				viewMode="week"
+				showLegend={false}
+				minDate={new Date(2026, 8, 1)}
+				maxDate={new Date(2026, 8, 30)}
+				disabledDates={(date) => date.getDay() === 0}
+				onEventClick={(event) => setPicked(event.title)}
+			/>
+			{!!picked && <Text size="sm" type="secondary">picked: {picked}</Text>}
+		</>
+	)
+}
 ```