themelia-ui 2.0.0 → 3.0.0

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

@@ -20,7 +20,7 @@ import "themelia-ui/features/global-search.css"
 
 ## Composition
 
-This family composes `base/avatar`, `base/badge`, `base/buttons`, `base/display`, `base/feedback`, `base/item`, `base/navigation`, `base/text-inputs`, `base/typography`, `features/overlays`.
+This module composes `base/avatar`, `base/badge`, `base/buttons`, `base/display`, `base/feedback`, `base/item`, `base/navigation`, `base/text-inputs`, `base/typography`, `features/overlays`.
 
 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 +39,10 @@ GlobalSearchStrings
 
 Kind: callable.
 
+The command palette's panel. It does not search: `query` is controlled and `results` are
+given; debounce, endpoint and ranking belong to the app. It owns the regions, grouping, and
+an arrow-key highlight.
+
 ```text
 ({ results, query, onQueryChange, onResultSelect, onClose, loading, idleSections, groupLabels, autoFocus, strings, slots, tabs, className, }: GlobalSearchProps<TGroup>) => import("react").JSX.Element
 ```
@@ -56,6 +60,9 @@ Kind: interface.
 
 Kind: callable.
 
+The palette presentation over ActionDialog: focus trap, portal, scroll lock, and a dialog
+role — none of which a hand-rolled fixed backdrop has.
+
 ```text
 ({ open, onOpenChange, contentClassName, className, strings, autoFocus, ...search }: GlobalSearchDialogProps<TGroup>) => import("react").JSX.Element
 ```
@@ -76,6 +83,8 @@ Extends: `Omit<GlobalSearchProps<TGroup>, "onClose">`.
 
 Kind: callable.
 
+What the palette shows after a search that found nothing.
+
 ```text
 ({ title, hint, className }: GlobalSearchEmptyStateProps) => import("react").JSX.Element
 ```
@@ -94,6 +103,9 @@ Kind: interface.
 
 Kind: callable.
 
+The keyboard-hint strip under the list. It is the only place a reader is told which three
+keys the palette answers to.
+
 ```text
 ({ navigateLabel, openLabel, closeLabel, escKey, trailing, className, }: GlobalSearchFooterProps) => import("react").JSX.Element
 ```
@@ -128,6 +140,9 @@ A static section shown while the query is too short to search on.
 
 Kind: callable.
 
+What the palette shows before there is anything to search: recent queries and curated
+suggestions, both supplied by the consumer — the palette does not remember anything itself.
+
 ```text
 ({ sections, fallbackIcons, className, }: GlobalSearchIdleStateProps) => import("react").JSX.Element
 ```
@@ -183,18 +198,18 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `results` | no | `readonly GlobalSearchResult<TGroup>[]` |  |
-| `query` | yes | `string` | Controlled. The palette never searches; it renders what it is given. |
-| `onQueryChange` | yes | `(query: string) => void` |  |
-| `onResultSelect` | no | `(result: GlobalSearchResult<TGroup>) => void` |  |
-| `onClose` | no | `() => void` | Fires on Escape. The dialog presentation wires this to closing itself. |
-| `loading` | no | `boolean` | Swaps the input's clear button for a spinner and shows the loading region. |
-| `idleSections` | no | `readonly GlobalSearchIdleSection[]` |  |
-| `groupLabels` | no | `Partial<Record<TGroup, ReactNode>>` | Names a group in the tab strip and above its results. Otherwise the key shows. |
+| `results` | no | `readonly GlobalSearchResult<TGroup>[]` | One shape for every kind, with optional parts: avatar OR thumbnail, a badge, meta, tags, a<br>timestamp, a trailing figure. A union per kind would be honest about the data and useless<br>for a list that renders them all the same way. |
+| `query` | yes | `string` | Controlled, always. The palette never searches; it renders what it is given. |
+| `onQueryChange` | yes | `(query: string) => void` | Receives every edit to `query`. |
+| `onResultSelect` | no | `(result: GlobalSearchResult<TGroup>) => void` | Fires on click and on Enter, with the whole result including its free-form `data`. |
+| `onClose` | no | `() => void` | Fires on Escape. The dialog presentation wires this to closing itself; a panel embedded in<br>a page usually wants it too. |
+| `loading` | no | `boolean` | Swaps the input's clear control for a spinner and shows the loading region. Hidden results<br>cannot be selected while the loading region is visible. |
+| `idleSections` | no | `readonly GlobalSearchIdleSection[]` | Recent queries and curated suggestions. The palette has no memory of its own — whose<br>recents these are is a question only the app can answer. |
+| `groupLabels` | no | `Partial<Record<TGroup, ReactNode>>` | Names a group in the tab strip and above its results. Without it the raw key shows, which<br>is a useful default only while you are wiring it up. |
 | `autoFocus` | no | `boolean` |  |
 | `strings` | no | `Partial<GlobalSearchStrings>` |  |
-| `slots` | no | `GlobalSearchSlots<TGroup>` |  |
-| `tabs` | no | `readonly GlobalSearchTab<TGroup>[]` | Replaces the auto-generated "All + one per group" strip. |
+| `slots` | no | `GlobalSearchSlots<TGroup>` | `input`, `tabs`, `idle`, `empty`, `loading`, `footer`, and `renderResult` — every region,<br>replaceable one at a time. |
+| `tabs` | no | `readonly GlobalSearchTab<TGroup>[]` | Replaces the auto-generated "All + one per group" strip, for a fixed set of tabs that<br>should not appear and disappear with the results. |
 | `className` | no | `string` |  |
 
 ### `GlobalSearchRenderResultContext`
@@ -216,7 +231,7 @@ Kind: interface.
 | `id` | yes | `string` |  |
 | `title` | yes | `string` | The only line guaranteed to render. |
 | `subtitle` | no | `string` |  |
-| `group` | yes | `TGroup` | The bucket this lands in. Also a tab, unless `tabs` says otherwise. |
+| `group` | yes | `TGroup` | The bucket this lands in. Tabs and group headings are both generated from the groups that<br>actually returned something, unless `tabs` says otherwise. |
 | `avatar` | no | `{ src?: string; initials: string; tone?: GlobalSearchTone; }` |  |
 | `thumbnail` | no | `{ src?: string; icon?: ReactNode; tone?: GlobalSearchTone; }` |  |
 | `meta` | no | `GlobalSearchMeta[]` |  |
@@ -231,6 +246,9 @@ Kind: interface.
 
 Kind: callable.
 
+One rich result — its media, title, context and trailing figure. Exported so a consumer
+rendering their own groups keeps the row's highlight and keyboard behaviour.
+
 ```text
 ({ result, active, query, onSelect, onMouseEnter, onFocus, className, }: GlobalSearchResultRowProps<TGroup>) => import("react").JSX.Element
 ```
@@ -298,6 +316,9 @@ Kind: interface.
 
 Kind: callable.
 
+The group filter strip, built on OverflowTabBar rather than Tabs: these narrow one list
+rather than switching between panels, and the distinction decides what the arrow keys do.
+
 ```text
 ({ value, onValueChange, tabs, counts, className, }: GlobalSearchTabsProps<TGroup>) => import("react").JSX.Element
 ```
@@ -328,6 +349,10 @@ IconBadgeTone
 
 Kind: callable.
 
+The palette's active row, active tab and key handling — `grouped`, `tabCounts`, `activeTab`,
+`flat`, `activeIndex` and `onKeyDown` — for a palette whose markup is entirely yours. `flat`
+is both what the rows render and what the keys walk, so the highlight and Enter always agree.
+
 ```text
 ({ results, query, onResultSelect, onClose, }: UseGlobalSearchOptions<TGroup>) => UseGlobalSearchResult<TGroup>
 ```
@@ -368,26 +393,108 @@ Preview route: Global search — `/global-search`
 ### The panel
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<GlobalSearch<Group>
-  query={query}
-  onQueryChange={setQuery}
-  results={results}
-  loading={isFetching}
-  groupLabels={{ people: "People", bookings: "Bookings" }}
-  idleSections={recentAndSuggested}
-  onResultSelect={(result) => navigate(result.data.href)}
-/>
+import { useMemo, useState } from "react"
+
+import { Switch } from "themelia-ui/base/choice-inputs"
+import { Text } from "themelia-ui/base/typography"
+import { GlobalSearch, type GlobalSearchIdleSection } from "themelia-ui/features/global-search"
+
+import { match } from "./_shared"
+import { GROUP_LABELS, IDLE, type Group } from "./data"
+
+export default function Panel() {
+	const [query, setQuery] = useState("marlow")
+	const [loading, setLoading] = useState(false)
+	const [chosen, setChosen] = useState<string | null>(null)
+
+	const results = useMemo(() => match(query), [query])
+
+	/* Choosing a recent query or a suggestion searches for it. */
+	const idle = useMemo<GlobalSearchIdleSection[]>(
+		() =>
+			IDLE.map((section) => ({
+				...section,
+				items: section.items.map((item) => ({
+					...item,
+					onSelect: () => setQuery(String(item.label)),
+				})),
+			})),
+		[],
+	)
+
+	return (
+		<>
+			<Switch label="Simulate loading" checked={loading} onChange={event => setLoading(event.target.checked)} />
+			<GlobalSearch<Group>
+				loading={loading}
+				query={query}
+				onQueryChange={setQuery}
+				results={results}
+				groupLabels={GROUP_LABELS}
+				idleSections={idle}
+				onResultSelect={(result) => setChosen(result.title)}
+			/>
+			{!!chosen && (
+				<Text size="sm" type="secondary">opened: {chosen}</Text>
+			)}
+		</>
+	)
+}
 ```
 
 ### The palette
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<GlobalSearchDialog
-  open={open}
-  onOpenChange={setOpen}
-  query={query}
-  onQueryChange={setQuery}
-  results={results}
-  onResultSelect={(result) => navigate(result.id)}
-/>
+import { useMemo, 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 { GlobalSearchDialog, type GlobalSearchIdleSection } from "themelia-ui/features/global-search"
+
+import { match } from "./_shared"
+import { GROUP_LABELS, IDLE, type Group } from "./data"
+
+export default function Dialog() {
+	const [open, setOpen] = useState(false)
+	const [query, setQuery] = useState("")
+	const [chosen, setChosen] = useState<string | null>(null)
+
+	const results = useMemo(() => match(query), [query])
+
+	/* Choosing a recent query or a suggestion searches for it. */
+	const idle = useMemo<GlobalSearchIdleSection[]>(
+		() =>
+			IDLE.map((section) => ({
+				...section,
+				items: section.items.map((item) => ({
+					...item,
+					onSelect: () => setQuery(String(item.label)),
+				})),
+			})),
+		[],
+	)
+
+	return (
+		<>
+			<Stack direction="horizontal" gap="md" 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>
+			<GlobalSearchDialog<Group>
+				open={open}
+				onOpenChange={setOpen}
+				query={query}
+				onQueryChange={setQuery}
+				results={results}
+				groupLabels={GROUP_LABELS}
+				idleSections={idle}
+				onResultSelect={(result) => setChosen(result.title)}
+			/>
+			{!!chosen && (
+				<Text size="sm" type="secondary">opened: {chosen}</Text>
+			)}
+		</>
+	)
+}
 ```

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

@@ -20,7 +20,7 @@ import "themelia-ui/features/kanban.css"
 
 ## Optional peers
 
-Install these only when importing this family:
+Install these only when importing this module:
 
 ```bash
 npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
@@ -28,7 +28,7 @@ npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
 
 ## Composition
 
-This family composes `base/action-menu`, `base/buttons`, `base/typography`.
+This module composes `base/action-menu`, `base/buttons`, `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.
@@ -47,6 +47,9 @@ KanbanStrings
 
 Kind: callable.
 
+A drag-and-drop board. It never persists: `onValueChange` is the truth, and `onItemMove` the
+seam for saving it.
+
 ```text
 ({ value, onValueChange, getItemValue, onItemMove, itemActions, onItemClick, strings, className, children, }: KanbanProps<T>) => import("react").JSX.Element
 ```
@@ -81,6 +84,9 @@ Kind: callable.
 
 Kind: callable.
 
+A column's droppable region, for a board that wants its own column chrome but the same drag
+behaviour.
+
 ```text
 ({ value, className, children }: KanbanColumnContentProps) => import("react").JSX.Element
 ```
@@ -125,6 +131,9 @@ Kind: interface.
 
 Kind: callable.
 
+One draggable card, for a board that wants its own column chrome but the same drag
+behaviour.
+
 ```text
 ({ value, className, disabled, onClick, children, }: KanbanItemProps) => import("react").JSX.Element
 ```
@@ -147,6 +156,8 @@ Extends: `ContextAction<T>`.
 
 Kind: callable.
 
+The card's verbs: its `itemActions`, in a menu.
+
 ```text
 ({ className, icon, label, }: KanbanItemActionsProps) => import("react").JSX.Element | null
 ```
@@ -191,6 +202,10 @@ itself, and the card then attaches drag listeners to the handle instead of its s
 
 Kind: callable.
 
+The grip. Optional: present, it becomes the only grip; absent, the whole card is. A handle
+rather than a draggable card body, because a card carrying a menu and a link has no way to
+tell a drag from a press otherwise — and text inside the card stays selectable.
+
 ```text
 ({ className, children, ref, }: KanbanItemHandleProps & { ref?: Ref<HTMLButtonElement>; }) => import("react").JSX.Element
 ```
@@ -231,6 +246,9 @@ Kind: interface.
 
 Kind: callable.
 
+What follows the pointer during a drag — rendered outside the column so it is not clipped by
+the scroll container it started in.
+
 ```text
 ({ className, render }: KanbanOverlayProps<T>) => import("react").JSX.Element
 ```
@@ -242,7 +260,7 @@ Kind: interface.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `className` | no | `string` |  |
-| `render` | no | `(context: { item: T \| null; columnId: string \| null; }) => ReactNode` | Replaces the default outline with the consumer's own card. |
+| `render` | no | `(context: { item: T \| null; columnId: string \| null; }) => ReactNode` | Replaces the default outline with the consumer's own card. The default is a placeholder<br>rather than a copy of the card, because the card's markup lives at the call site. |
 
 ### `KanbanProps`
 
@@ -250,12 +268,12 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `value` | yes | `KanbanValue<T>` |  |
-| `onValueChange` | yes | `(next: KanbanValue<T>) => void` |  |
+| `value` | yes | `KanbanValue<T>` | The board, as `Record<columnId, T[]>`: a plain object because that is what a board is,<br>and it serialises without a thought. Column titles and limits are the consumer's — only<br>the ORDER lives here. |
+| `onValueChange` | yes | `(next: KanbanValue<T>) => void` | Receives the whole next board after every move. |
 | `getItemValue` | yes | `(item: T) => string` | A stable id per item. Everything else is keyed off this. |
-| `onItemMove` | no | `(event: KanbanItemMoveEvent<T>) => void` | Fires after a move lands, with both ends of it, for persistence or analytics. |
-| `itemActions` | no | `KanbanItemActions<T>` |  |
-| `onItemClick` | no | `(item: T) => void` | Fires on a card click that was not the handle or the menu. |
+| `onItemMove` | no | `(event: KanbanItemMoveEvent<T>) => void` | Fires after a move lands, with both ends of it — from column and index, to column and<br>index. The seam for persistence or analytics. Idempotent: a move that changes nothing<br>fires nothing. |
+| `itemActions` | no | `KanbanItemActions<T>` | Each card's actions, or a function of the card. The factory form is what a real board<br>needs: “Reopen” belongs on a card in Done and nowhere else, and a fixed list would render<br>it everywhere and disable it. |
+| `onItemClick` | no | `(item: T) => void` | Fires on a card click that was not the handle or the menu — both mark themselves, so a<br>click on an icon inside either is caught too. |
 | `strings` | no | `Partial<KanbanStrings>` |  |
 | `className` | no | `string` |  |
 | `children` | no | `ReactNode` |  |
@@ -286,6 +304,10 @@ Record<string, T[]>
 
 Kind: callable.
 
+The move without the drag: `findItem` and `move` over the same `value`, `onValueChange` and
+`getItemValue` the board takes — for a keyboard board, a "move to column" menu, or a test
+that moves items without simulating a pointer.
+
 ```text
 ({ value, onValueChange, getItemValue, onItemMove, }: UseKanbanOptions<T>) => UseKanbanResult<T>
 ```
@@ -294,6 +316,8 @@ Kind: callable.
 
 Kind: callable.
 
+The board's state, for a custom card or column rendered inside it.
+
 ```text
 () => KanbanContextValue<T>
 ```
@@ -302,6 +326,8 @@ Kind: callable.
 
 Kind: callable.
 
+One card's drag state, for a custom card that still needs to know it is being dragged.
+
 ```text
 () => KanbanItemContextValue<T>
 ```
@@ -333,25 +359,118 @@ Preview route: Kanban & sync — `/kanban`
 ### The board
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Kanban
-  value={board}
-  onValueChange={setBoard}
-  getItemValue={(card) => card.id}
-  onItemMove={(event) => api.persist(event)}
-  itemActions={(card) => card.done ? [reopen] : [archive]}
->
-  <KanbanBoard>
-    {columns.map((column) => (
-      <KanbanColumn key={column.id} value={column.id}>
-        <header>{column.title}</header>
-        <KanbanColumnContent value={column.id}>
-          {board[column.id].map((card) => (
-            <KanbanItem key={card.id} value={card.id}>…</KanbanItem>
-          ))}
-        </KanbanColumnContent>
-      </KanbanColumn>
-    ))}
-  </KanbanBoard>
-  <KanbanOverlay />
-</Kanban>
+import { useState } from "react"
+import { ArchiveIcon, ExternalLinkIcon, RotateCwIcon } from "lucide-react"
+
+import { Badge } from "themelia-ui/base/badge"
+import { Card } from "themelia-ui/base/cards"
+import { Stack } from "themelia-ui/base/structure"
+import { DisplayLabel, Text } from "themelia-ui/base/typography"
+import {
+	Kanban, KanbanBoard, KanbanColumn, KanbanColumnContent, KanbanItem,
+	KanbanItemActions, KanbanItemHandle, KanbanOverlay,
+	type KanbanValue,
+} from "themelia-ui/features/kanban"
+
+import styles from "./kanban.module.css"
+
+interface Card_ {
+	id: string
+	title: string
+	owner: string
+	value: string
+}
+
+const COLUMNS = [
+	{ id: "backlog", title: "Backlog" },
+	{ id: "progress", title: "In progress" },
+	{ id: "done", title: "Done" },
+]
+
+const INITIAL: KanbanValue<Card_> = {
+	backlog: [
+		{ id: "c1", title: "Reconcile August payouts", owner: "Maria", value: "€12,400" },
+		{ id: "c2", title: "Chase the Marlow deposit", owner: "Marcus", value: "€300" },
+	],
+	progress: [{ id: "c3", title: "Migrate the invoice numbering", owner: "Alice", value: "—" }],
+	done: [{ id: "c4", title: "Close the Q2 books", owner: "Maria", value: "€48,200" }],
+}
+
+export default function KanbanExample() {
+	const [board, setBoard] = useState(INITIAL)
+	const [log, setLog] = useState<string[]>([])
+
+	const note = (line: string) => setLog((lines) => [line, ...lines].slice(0, 4))
+
+	return (
+		<>
+			<Kanban<Card_>
+				value={board}
+				onValueChange={setBoard}
+				getItemValue={(card) => card.id}
+				onItemMove={(event) =>
+					note(`${event.item.title}: ${event.from.columnId} → ${event.to.columnId} @ ${event.to.index}`)
+				}
+				onItemClick={(card) => note(`opened ${card.title}`)}
+				itemActions={(card) => [
+					{ id: "open", label: "Open", icon: <ExternalLinkIcon />, onClick: () => note(`open ${card.id}`) },
+					{
+						id: "reopen",
+						label: "Reopen",
+						icon: <RotateCwIcon />,
+						// Only on a finished card — the whole reason the factory form exists.
+						visible: () => (board.done ?? []).some((done) => done.id === card.id),
+						onClick: () => note(`reopen ${card.id}`),
+					},
+					{
+						id: "archive",
+						label: "Archive",
+						icon: <ArchiveIcon />,
+						tone: "destructive",
+						onClick: () => note(`archive ${card.id}`),
+					},
+				]}
+			>
+				<KanbanBoard className={styles.board}>
+					{COLUMNS.map((column) => (
+						<KanbanColumn key={column.id} value={column.id} className={styles.column}>
+							<Stack direction="horizontal" align="center" justify="between" gap="sm">
+								<DisplayLabel>{column.title}</DisplayLabel>
+								<Badge tone="neutral">{board[column.id]?.length ?? 0}</Badge>
+							</Stack>
+							<KanbanColumnContent value={column.id}>
+								{(board[column.id] ?? []).map((card) => (
+									<KanbanItem key={card.id} value={card.id}>
+										<Card className={styles.card}>
+											<Stack direction="horizontal" align="start" gap="xs">
+												<KanbanItemHandle />
+												<Text size="sm" weight="medium" className={styles.cardTitle}>
+													{card.title}
+												</Text>
+												<KanbanItemActions<Card_> />
+											</Stack>
+											<Stack direction="horizontal" align="baseline" justify="between" gap="sm" className={styles.cardMeta}>
+												<Text size="xs" type="secondary">{card.owner}</Text>
+												<Text size="xs" type="secondary" numeric>{card.value}</Text>
+											</Stack>
+										</Card>
+									</KanbanItem>
+								))}
+							</KanbanColumnContent>
+						</KanbanColumn>
+					))}
+				</KanbanBoard>
+				<KanbanOverlay<Card_> />
+			</Kanban>
+
+			{log.length > 0 && (
+				<Stack gap="none">
+					{log.map((line, index) => (
+						<Text key={`${line}-${index}`} size="xs" type="secondary">{line}</Text>
+					))}
+				</Stack>
+			)}
+		</>
+	)
+}
 ```