@parallelworks/ui 0.53.0 → 0.55.0

package/README.md

@@ -14,6 +14,7 @@ so an application ships only what it imports:
 | `./editor` | Monaco editor (`monaco-editor` is an optional peer), loaded on first mount with the languages it needs; YAML validation, completion and hover run in a bundled worker |
 | `./logviewer` | log viewer with ANSI color and search |
 | `./file-explorer` | object storage explorer over a host-supplied provider |
+| `./access` | `AccessDrawer`: who has access to a resource, and granting roles to groups |
 | `./ai`, `./ai/openai`, `./ai/mock` | chat interface and adapters |
 | `./theme.css`, `./base.css`, `./fonts.css`, `./styles.css`, `./logviewer.css`, `./ai.css` | stylesheets |
 
@@ -63,7 +64,7 @@ Each need has one component. Reach for it before styling markup by hand.
 | One of a few choices, all shown | `RadioGroup` in a form; `SegmentedControl` in a toolbar, or as a field's control in a `Field group` |
 | Narrowing a list by values, such as statuses: several at once, or one or none | `ToggleGroup` |
 | Narrowing what is shown by typing | `SearchInput`; `ListSearchControl` on a list page's toolbar |
-| A value from a list | `Select`, or `Combobox` when the list needs filtering |
+| A value from a list | `Select`, or `Combobox` when the list needs filtering; its `details` pane describes the highlighted item, and `onQueryChange` hands the search to the host |
 | Free text with suggestions, or tags | `Autocomplete`; `Combobox` with `multiple creatable` |
 | A range | `Slider` |
 | A page's breadcrumbs, title and commands | `PageHeader`, shown by the shell's `PageHeaderBar` (see [Page header](#page-header)) |
@@ -76,7 +77,8 @@ Each need has one component. Reach for it before styling markup by hand.
 | A hint for a control | `Tooltip`; a `Field`'s `help` for more about a field, which its control reads and which opens as Tab reaches it; `InfoTip` for help about anything else |
 | A preview of what a link leads to | `HoverCard` |
 | A task that blocks the page | `Modal`, laid out with `title`, `description` and `footer` as a `Drawer` is; `ConfirmModal` to confirm one action; `CreateModal` to name and create one thing |
-| A panel beside the page | `Drawer` |
+| A panel beside the page | `Drawer`; `onBack` for a view it opens over its first, such as a form |
+| Who has access to something, and changing it | `AccessDrawer` from `./access` (see [Access](#access)) |
 | A message set into the page: guidance, a warning, an error | `Callout`; `variant="bar"` across a surface under its header |
 | A passing notice, or the progress of work in the background | `toast` |
 | How full something is, how far a task has come | `Meter`, `ProgressBar` |
@@ -313,11 +315,13 @@ In React, `useColorMode(preference)` follows the device while the preference is
 `system`, and `useApplyTheme(theme, mode)` applies the theme to the document
 root (or to an element you pass) and sets `color-scheme`. `applyTheme` sets the
 display-p3 values on a wide-gamut screen. To render a theme on the server,
-`themeStylesheet(selector, scheme)` returns a stylesheet with both blocks.
+`themeStylesheet(selector, scheme)` returns a stylesheet with both blocks; given
+`{ light, dark }` schemes, it pairs each token's two values with `light-dark()`.
 `deriveTheme(scheme)` returns the sRGB tokens alone.
 
-`theme.css` defines the default theme's tokens, so a page renders before any
-script runs:
+`theme.css` defines the default theme's tokens for both modes, each as
+`light-dark()`, so a page renders before any script runs and a token the host
+leaves unset follows the `color-scheme` it sets:
 
 ```css
 /* In a Tailwind v4 build: */
@@ -470,6 +474,52 @@ five seconds, eight for a warning or an error, pausing while the pointer or focu
 is on it; `timeout: false` keeps it. `loading` stays until an update settles it
 into a tone. Pass an `id` to replace a toast rather than stack another.
 
+## Access
+
+`AccessDrawer` shows who holds which role on one resource, and grants and takes
+them away. A role is a named set of permissions; groups are granted roles, never
+permissions one by one. Two roles may overlap: the drawer works the overlap out
+from each role's `permissions` and says so as a hint ("Sudo covers this too"),
+and before a role is taken away it lists exactly what the group loses, the
+permissions no role it keeps still gives, and what it keeps.
+
+```tsx
+import { AccessDrawer, type AccessChange } from '@parallelworks/ui/access'
+
+<AccessDrawer
+  open={open}
+  onClose={close}
+  resourceName={cluster.name}
+  roles={[{ id: 'login', name: 'Login', description: 'Sign in.', permissions: ['cluster:login'] }]}
+  permissions={[{ id: 'cluster:login', label: 'Sign in' }]}
+  groups={[{ id: 'org', name: 'Everyone', kind: 'everyone', memberCount: 214 }, ...granted]}
+  grants={grants} // { groupId, roleId }[]
+  onChange={(change: AccessChange) => api.patch(change)} // { grant, revoke }
+  describeGroup={(id, signal) => api.group(id, { signal })}
+  searchGroups={(query, signal) => api.groups({ query, signal })}
+  readOnly={!canManage}
+  readOnlyReason="Only people with the Admin role can change it."
+/>
+```
+
+- `onChange` gets one change at a time, holding only grants that change
+  something. Return a promise: its rows show they are saving until it settles,
+  and when it rejects the drawer says that nothing changed and offers Retry. A
+  saved change offers Undo in a toast. Pass the new grants back through
+  `grants`; the drawer never keeps its own copy.
+- `groups` holds every group that has a role here, and everyone if the resource
+  can be granted to everyone (`kind: 'everyone'`, at most one). Without
+  `searchGroups` it is also the list to grant to; with it, the picker asks the
+  host as the reader types.
+- `describeGroup` fills the pane beside the group picker for the highlighted
+  group: where it comes from, its first members and when it last changed. It is
+  asked once per group while the drawer is mounted, and aborted when the
+  highlight moves on.
+- `highImpact` roles carry a tag, and granting anything to everyone says how
+  many people it reaches and asks to confirm.
+- A development build warns about duplicate ids and grants that name unknown
+  roles or groups.
+
 ## Host chrome
 
 Popups, dialogs and drawers portal to `<body>` and read the tokens from the
@@ -707,11 +757,20 @@ animations) and streamdown's classes next to the theme contract:
 
 The prebuilt `@parallelworks/ui/styles.css` already includes both.
 
-Math needs nothing from the host: `Markdown` imports KaTeX's stylesheet
-itself, from the `katex` package, so the host's bundler loads it and its fonts
+For math, `Markdown` imports KaTeX's stylesheet itself, from the `katex` package, so the host's bundler loads it and its fonts
 with the markdown renderer's lazy chunk. The bundler must accept CSS imported
-from JavaScript, as the editor's Monaco also requires. Inline math takes `$$`
-within a sentence; a single `$` stays text, so prices are never read as math.
+from JavaScript, as the editor's Monaco also requires. The renderer's math
+plugins still ask for katex 0.16, which has a prototype-pollution advisory;
+override them to the katex this package asks for, so they render with the copy
+the stylesheet comes from, as with pnpm:
+
+```yaml
+overrides:
+  'katex@<0.19.0': '^0.19.0'
+```
+
+Inline math takes `$$` within a sentence; a single `$` stays text, so prices
+are never read as math.
 
 ## Form state
 

package/dist/access/AccessDrawer.d.ts

@@ -0,0 +1,55 @@
+import { type ReactNode } from 'react';
+import { type AccessModel } from './model.js';
+import { type AccessStrings } from './strings.js';
+import type { AccessChange, AccessGrant, AccessGroup, AccessGroupDetails, AccessPermission, AccessRole } from './types.js';
+export type AccessArrangement = 'role' | 'group';
+export interface AccessDrawerProps {
+    open: boolean;
+    onClose: () => void;
+    /** What access is to, as the reader knows it: "gpu-cluster-east". */
+    resourceName: string;
+    /** Every role that can be granted here, in the order to list them. */
+    roles: readonly AccessRole[];
+    /** Every group that holds a role here, and everyone when the resource can be granted to
+     *  everyone. Without `searchGroups`, also every group that can be granted one. */
+    groups: readonly AccessGroup[];
+    /** Who holds which role. The drawer shows these and never changes them itself. */
+    grants: readonly AccessGrant[];
+    /** Names the permissions roles list, for what a group loses when it loses a role. */
+    permissions?: readonly AccessPermission[] | undefined;
+    /** Saves a change. Return a promise that settles once it is saved: until then its rows show
+     *  that they are saving, and when it rejects the drawer says that nothing changed and offers
+     *  to try again. Pass the new grants back through `grants`. */
+    onChange?: ((change: AccessChange) => void | Promise<unknown>) | undefined;
+    /** The grants are still loading: skeletons hold their place. */
+    loading?: boolean | undefined;
+    /** Shows who has access without letting the reader change it. */
+    readOnly?: boolean | undefined;
+    /** Who can change it, said in read-only mode: "Only people with the Admin role can change it." */
+    readOnlyReason?: ReactNode;
+    /** More about a group, asked for when it is highlighted in the group picker and kept while the
+     *  drawer is mounted. A highlight that moves on aborts `signal`. */
+    describeGroup?: ((groupId: string, signal: AbortSignal) => Promise<AccessGroupDetails>) | undefined;
+    /** Finds groups to grant to, for an organization with too many to pass in `groups`. A newer
+     *  query aborts `signal`. Without it, the picker filters `groups`. */
+    searchGroups?: ((query: string, signal: AbortSignal) => Promise<readonly AccessGroup[]>) | undefined;
+    /** How many groups the organization has, for the picker's hint and heading. */
+    groupCount?: number | undefined;
+    /** Groups the reader granted to lately, listed first in the picker. */
+    recentGroupIds?: readonly string[] | undefined;
+    /** How the list starts out: role by role, or group by group. */
+    defaultArrangement?: AccessArrangement | undefined;
+    /** As `Drawer`'s. */
+    width?: number | string | undefined;
+}
+/** Who has access to one resource, and the place to change it: roles granted to groups.
+ *  Overlapping roles are allowed and only redundant, which the drawer points out; taking a
+ *  role away first says exactly what the group loses. Each change is saved as it is made, with
+ *  Undo in a toast. */
+export declare function AccessDrawer({ open, onClose, resourceName, roles, groups, grants, permissions, onChange, loading, readOnly, readOnlyReason, describeGroup, searchGroups, groupCount, recentGroupIds, defaultArrangement, width, }: AccessDrawerProps): import("react").JSX.Element;
+type Match = (query: string, ...texts: (string | undefined)[]) => boolean;
+export declare function filterAccess(model: AccessModel, arrangement: AccessArrangement, query: string, match: Match, t: AccessStrings): {
+    shown: Map<string, readonly string[]>;
+    order: string[];
+};
+export {};

package/dist/access/AccessDrawer.js

@@ -0,0 +1,445 @@
+import { AddIcon, LockIcon, UsersIcon } from "../icons.js";
+import { toast } from "../components/Toast.js";
+import { EmptyState } from "../components/EmptyState.js";
+import { useQueryMatch } from "../components/search.js";
+import { Button } from "../components/Button.js";
+import { Callout } from "../components/Callout.js";
+import { Drawer } from "../components/Drawer.js";
+import { LoadingRegion, Skeleton } from "../components/Skeleton.js";
+import { SearchInput } from "../components/SearchInput.js";
+import { SegmentedControl } from "../components/SegmentedControl.js";
+import { buildModel, invert, key, warnAboutMisuse } from "./model.js";
+import { ByGroup, ByRole, removeKey } from "./AccessList.js";
+import { holdFocus, useFocusAfterRender } from "./focus.js";
+import { useGrantView } from "./GrantView.js";
+import { useAccessStrings } from "./strings.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+//#region src/access/AccessDrawer.tsx
+var EMPTY_SELECTION = {
+	groupIds: [],
+	roleIds: []
+};
+/** Who has access to one resource, and the place to change it: roles granted to groups.
+*  Overlapping roles are allowed and only redundant, which the drawer points out; taking a
+*  role away first says exactly what the group loses. Each change is saved as it is made, with
+*  Undo in a toast. */
+function AccessDrawer({ open, onClose, resourceName, roles, groups, grants, permissions, onChange, loading = false, readOnly = false, readOnlyReason, describeGroup, searchGroups, groupCount, recentGroupIds, defaultArrangement = "role", width = 560 }) {
+	const t = useAccessStrings();
+	const uid = useId();
+	const model = useMemo(() => buildModel(roles, groups, grants, permissions), [
+		roles,
+		groups,
+		grants,
+		permissions
+	]);
+	useEffect(() => {
+		if (!loading) warnAboutMisuse(roles, groups, grants, permissions);
+	}, [
+		roles,
+		groups,
+		grants,
+		permissions,
+		loading
+	]);
+	const [view, setView] = useState("list");
+	const [selection, setSelection] = useState(EMPTY_SELECTION);
+	const [arrangement, setArrangement] = useState(defaultArrangement);
+	const [query, setQuery] = useState("");
+	const [expanded, setExpanded] = useState({
+		role: /* @__PURE__ */ new Set(),
+		group: /* @__PURE__ */ new Set()
+	});
+	const [removal, setRemoval] = useState();
+	const [saving, setSaving] = useState();
+	const [failure, setFailure] = useState();
+	const cache = useRef(/* @__PURE__ */ new Map()).current;
+	const seen = useRef(/* @__PURE__ */ new Map()).current;
+	const body = useRef(null);
+	const [bodyElement, setBodyElement] = useState(null);
+	const bodyRef = useCallback((element) => {
+		body.current = element;
+		setBodyElement(element);
+	}, []);
+	const focusLater = useFocusAfterRender();
+	const change = useRef(onChange);
+	change.current = onChange;
+	const match = useQueryMatch();
+	const filtered = useFiltered(model, arrangement, query.trim(), match, t);
+	const editable = !readOnly && onChange !== void 0;
+	const sectionId = (id) => `${uid}${arrangement}${id}`;
+	const names = (changed) => {
+		const all = [...changed.grant, ...changed.revoke];
+		return {
+			groupNames: [...new Set(all.map((grant) => grant.groupId))].map((id) => {
+				const group = seen.get(id) ?? model.groupById.get(id);
+				return group?.kind === "everyone" ? t.everyone : group?.name ?? id;
+			}),
+			roleNames: [...new Set(all.map((grant) => grant.roleId))].map((id) => model.roleById.get(id)?.name ?? id)
+		};
+	};
+	const undo = (done) => {
+		Promise.resolve(change.current?.(invert(done))).then(() => toast.info(t.undone), (error) => toast.error(t.nothingChanged(messageOf(error)), { title: t.undoFailed }));
+	};
+	/** Saves a change and reports how it went; resolves true once saved. */
+	const save = async (next, where) => {
+		if (!onChange || next.grant.length === 0 && next.revoke.length === 0) return false;
+		const { groupNames, roleNames } = names(next);
+		setSaving(next);
+		setFailure(void 0);
+		try {
+			await onChange(next);
+		} catch (error) {
+			setFailure({
+				change: next,
+				title: next.grant.length > 0 ? t.grantFailed(groupNames, roleNames) : t.removeFailed(groupNames[0] ?? "", roleNames),
+				message: messageOf(error),
+				...where
+			});
+			return false;
+		} finally {
+			setSaving(void 0);
+		}
+		toast.success(next.grant.length > 0 ? t.granted(groupNames, roleNames) : t.removed(groupNames, roleNames), { action: {
+			label: t.common.undo,
+			onClick: () => undo(next)
+		} });
+		return true;
+	};
+	const toList = () => {
+		setView("list");
+		setFailure((current) => current?.inGrant ? void 0 : current);
+		focusLater(() => visible(body.current?.querySelectorAll("[data-grant-access]")));
+	};
+	const toGrant = (groupIds = []) => {
+		setSelection({
+			groupIds,
+			roleIds: []
+		});
+		setRemoval(void 0);
+		setView("grant");
+		focusLater(() => body.current?.querySelector("input[role=\"combobox\"]"));
+	};
+	const grant = async (next) => {
+		if (await save(next, {
+			inGrant: true,
+			groupId: next.grant[0]?.groupId ?? ""
+		})) {
+			setExpanded((current) => ({
+				role: /* @__PURE__ */ new Set([...current.role, ...next.grant.map((g) => g.roleId)]),
+				group: /* @__PURE__ */ new Set([...current.group, ...next.grant.map((g) => g.groupId)])
+			}));
+			toList();
+		}
+	};
+	const remove = async (pending) => {
+		const next = {
+			grant: [],
+			revoke: pending.roleIds.map((roleId) => ({
+				groupId: pending.groupId,
+				roleId
+			}))
+		};
+		const anchor = arrangement === "role" && !pending.all ? pending.roleIds[0] : void 0;
+		await save(next, {
+			inGrant: false,
+			groupId: pending.groupId,
+			roleId: anchor
+		});
+		setRemoval(void 0);
+		focusLater(() => document.getElementById(sectionId(anchor ?? pending.groupId)) ?? body.current?.querySelector("input[type=\"search\"]"));
+	};
+	const retry = (failed) => failed.inGrant ? grant(failed.change) : save(failed.change, {
+		inGrant: false,
+		groupId: failed.groupId,
+		roleId: failed.roleId
+	});
+	const failureNode = failure && /* @__PURE__ */ jsx(Callout, {
+		tone: "error",
+		live: true,
+		title: failure.title,
+		action: /* @__PURE__ */ jsx(Button, {
+			size: "sm",
+			variant: "secondary",
+			onClick: () => retry(failure),
+			children: t.common.retry
+		}),
+		onDismiss: () => setFailure(void 0),
+		children: t.nothingChanged(failure.message)
+	});
+	const close = () => {
+		setView("list");
+		setRemoval(void 0);
+		setQuery("");
+		onClose();
+	};
+	const grantView = useGrantView({
+		model,
+		selection,
+		onSelectionChange: setSelection,
+		resourceName,
+		describeGroup,
+		searchGroups,
+		groupCount,
+		recentGroupIds,
+		cache,
+		seen,
+		saving: saving !== void 0,
+		failure: failure?.inGrant ? failureNode : void 0,
+		onGrant: grant,
+		onCancel: toList,
+		focusLater,
+		boundary: bodyElement,
+		t
+	});
+	const savingKeys = useMemo(() => new Set(saving?.revoke.map(key) ?? []), [saving]);
+	const empty = !loading && model.held.size === 0;
+	const View = arrangement === "role" ? ByRole : ByGroup;
+	const grantButton = (className) => /* @__PURE__ */ jsx(Button, {
+		variant: "primary",
+		icon: /* @__PURE__ */ jsx(AddIcon, {}),
+		"data-grant-access": "",
+		disabled: loading,
+		onClick: () => toGrant(),
+		className,
+		children: t.grantAccess
+	});
+	const list = /* @__PURE__ */ jsxs("div", {
+		className: "@container/access flex min-h-0 flex-1 flex-col",
+		children: [
+			readOnly && /* @__PURE__ */ jsx("div", {
+				className: "px-4 pt-3",
+				children: /* @__PURE__ */ jsxs(Callout, {
+					tone: "info",
+					icon: /* @__PURE__ */ jsx(LockIcon, {}),
+					children: [
+						t.readOnly,
+						" ",
+						readOnlyReason ?? t.readOnlyReason
+					]
+				})
+			}),
+			!empty && /* @__PURE__ */ jsxs("div", {
+				className: "flex flex-wrap items-center gap-2 border-b border-(--theme-border) px-4 py-3",
+				children: [
+					/* @__PURE__ */ jsx("div", {
+						className: "w-full @min-[30rem]/access:w-auto",
+						children: /* @__PURE__ */ jsx(SegmentedControl, {
+							fill: true,
+							label: t.arrange,
+							value: arrangement,
+							onValueChange: setArrangement,
+							options: [{
+								value: "role",
+								label: t.byRole
+							}, {
+								value: "group",
+								label: t.byGroup
+							}]
+						})
+					}),
+					/* @__PURE__ */ jsx(SearchInput, {
+						label: t.filter,
+						value: query,
+						onValueChange: (next) => {
+							setQuery(next);
+							setExpanded(expandedFor(model, next.trim(), match, t));
+						},
+						className: "min-w-0 flex-1 basis-full @min-[30rem]/access:basis-0"
+					}),
+					editable && grantButton("hidden @min-[30rem]/access:inline-flex")
+				]
+			}),
+			failure && !failure.inGrant && !filtered.order.includes(anchorOf(failure, arrangement)) && /* @__PURE__ */ jsx("div", {
+				className: "px-4 pt-3",
+				children: failureNode
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: "min-h-0 flex-1 overflow-y-auto",
+				children: loading ? /* @__PURE__ */ jsx(LoadingRegion, {
+					label: t.loading,
+					children: /* @__PURE__ */ jsx(RowsSkeleton, {})
+				}) : empty ? /* @__PURE__ */ jsx(EmptyState, {
+					variant: "bare",
+					icon: /* @__PURE__ */ jsx(UsersIcon, {}),
+					title: t.emptyTitle,
+					description: t.emptyDescription(resourceName),
+					action: editable && grantButton(""),
+					className: "py-16"
+				}) : filtered.order.length === 0 ? /* @__PURE__ */ jsx(EmptyState, {
+					variant: "bare",
+					title: t.noMatches,
+					action: /* @__PURE__ */ jsx(Button, {
+						variant: "secondary",
+						size: "sm",
+						onClick: () => setQuery(""),
+						children: t.clearFilter
+					})
+				}) : /* @__PURE__ */ jsx(View, {
+					model,
+					shown: filtered.shown,
+					order: filtered.order,
+					expanded: expanded[arrangement],
+					onExpandedChange: (id, isOpen) => setExpanded((current) => {
+						const next = new Set(current[arrangement]);
+						if (isOpen) next.add(id);
+						else next.delete(id);
+						return {
+							...current,
+							[arrangement]: next
+						};
+					}),
+					filtering: query.trim() !== "",
+					sectionId,
+					t,
+					actions: {
+						readOnly: !editable,
+						saving: savingKeys,
+						removal,
+						onAskRemove: (next) => {
+							holdFocus();
+							setFailure(void 0);
+							setRemoval(next);
+						},
+						onCancelRemove: () => {
+							const asked = removal;
+							setRemoval(void 0);
+							if (asked) focusLater(() => body.current?.querySelector(`[data-remove="${CSS.escape(removeKey(asked))}"]`));
+						},
+						onRemove: remove,
+						onGrantMore: (groupId) => toGrant([groupId]),
+						failure: failure && !failure.inGrant ? {
+							node: failureNode,
+							groupId: failure.groupId,
+							roleId: failure.roleId
+						} : void 0
+					}
+				})
+			}),
+			editable && !empty && /* @__PURE__ */ jsx("div", {
+				className: "border-t border-(--theme-border) p-4 @min-[30rem]/access:hidden",
+				children: grantButton("w-full")
+			})
+		]
+	});
+	const granting = view === "grant";
+	return /* @__PURE__ */ jsx(Drawer, {
+		open,
+		onClose: close,
+		width,
+		padded: false,
+		title: granting ? t.grantAccess : t.title,
+		description: granting ? resourceName : loading ? resourceName : t.summary(resourceName, [...model.held.keys()].filter((id) => id !== model.everyone?.id).length, model.everyone !== void 0 && model.held.has(model.everyone.id)),
+		onBack: granting ? toList : void 0,
+		backLabel: t.back,
+		footer: granting ? grantView.footer : void 0,
+		onKeyDown: (e) => {
+			const target = e.target;
+			if (granting && e.key === "Escape" && !e.defaultPrevented && target.getAttribute("aria-expanded") !== "true") {
+				e.stopPropagation();
+				e.preventBaseUIHandler();
+				toList();
+			}
+		},
+		children: /* @__PURE__ */ jsx("div", {
+			ref: bodyRef,
+			className: "flex min-h-0 flex-1 flex-col",
+			children: granting ? grantView.body : list
+		})
+	});
+}
+var messageOf = (error) => error instanceof Error && error.message ? error.message : void 0;
+var anchorOf = (failure, arrangement) => arrangement === "role" ? failure.roleId ?? "" : failure.groupId;
+/** The first of several elements that is laid out, such as the one of two buttons a width shows. */
+/** The one of `elements` that is laid out, or the first where nothing is (as in tests). */
+function visible(elements) {
+	const all = [...elements ?? []];
+	return all.find((element) => element.getClientRects().length > 0) ?? all[0];
+}
+var groupNames = (group, t) => group.kind === "everyone" ? [
+	group.name,
+	t.everyone,
+	t.everyoneInOrganization
+] : [group.name];
+/** The sections in view and the rows under each. A section named by the query shows all its
+*  rows; otherwise only the rows the query names, and no section when none are. */
+function useFiltered(model, arrangement, query, match, t) {
+	return useMemo(() => filterAccess(model, arrangement, query, match, t), [
+		model,
+		arrangement,
+		query,
+		match,
+		t
+	]);
+}
+function filterAccess(model, arrangement, query, match, t) {
+	const shown = /* @__PURE__ */ new Map();
+	const order = [];
+	if (arrangement === "role") for (const role of model.roles) {
+		const holders = model.holders.get(role.id) ?? [];
+		const rows = !query || match(query, role.name, role.description) ? holders : holders.filter((group) => match(query, ...groupNames(group, t)));
+		if (!query || rows.length > 0) {
+			order.push(role.id);
+			shown.set(role.id, rows.map((group) => group.id));
+		}
+	}
+	else {
+		const everyone = model.everyone;
+		const holders = [...model.held.keys()].sort((a, b) => a === everyone?.id ? -1 : b === everyone?.id ? 1 : 0);
+		for (const groupId of holders) {
+			const group = model.groupById.get(groupId);
+			const held = model.held.get(groupId) ?? [];
+			if (!group) continue;
+			const rows = !query || match(query, ...groupNames(group, t)) ? held : held.filter((role) => match(query, role.name, role.description));
+			if (!query || rows.length > 0) {
+				order.push(groupId);
+				shown.set(groupId, rows.map((role) => role.id));
+			}
+		}
+	}
+	return {
+		shown,
+		order
+	};
+}
+/** Opens the sections a query found rows in, so the matches show; each can then be folded. */
+function expandedFor(model, query, match, t) {
+	if (!query) return {
+		role: /* @__PURE__ */ new Set(),
+		group: /* @__PURE__ */ new Set()
+	};
+	const open = (arrangement) => {
+		const { shown } = filterAccess(model, arrangement, query, match, t);
+		return new Set([...shown].filter(([, rows]) => rows.length > 0).map(([id]) => id));
+	};
+	return {
+		role: open("role"),
+		group: open("group")
+	};
+}
+function RowsSkeleton() {
+	return [
+		"a",
+		"b",
+		"c",
+		"d"
+	].map((row) => /* @__PURE__ */ jsxs("div", {
+		className: "flex items-center gap-3 border-b border-(--theme-border) px-4 py-3",
+		children: [
+			/* @__PURE__ */ jsx(Skeleton, {
+				width: 16,
+				height: 16
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex min-w-0 flex-1 flex-col gap-1.5",
+				children: [/* @__PURE__ */ jsx(Skeleton, { width: "30%" }), /* @__PURE__ */ jsx(Skeleton, {
+					width: "60%",
+					className: "text-sm"
+				})]
+			}),
+			/* @__PURE__ */ jsx(Skeleton, { width: 56 })
+		]
+	}, row));
+}
+//#endregion
+export { AccessDrawer, filterAccess };

package/dist/access/AccessList.d.ts

@@ -0,0 +1,58 @@
+import { type ReactNode } from 'react';
+import { type AccessModel } from './model.js';
+import type { AccessStrings } from './strings.js';
+/** A removal waiting on the reader: one role, or every role the group holds. */
+export interface PendingRemoval {
+    groupId: string;
+    roleIds: string[];
+    /** Every role the group holds, from its "Remove all access". */
+    all: boolean;
+}
+export interface ListActions {
+    readOnly: boolean;
+    /** The grants being saved, by `key()`. */
+    saving: ReadonlySet<string>;
+    removal: PendingRemoval | undefined;
+    onAskRemove: (removal: PendingRemoval) => void;
+    onCancelRemove: () => void;
+    onRemove: (removal: PendingRemoval) => void;
+    onGrantMore: (groupId: string) => void;
+    /** The failed save's callout, and where it belongs: under the role or group it was about. */
+    failure: {
+        node: ReactNode;
+        roleId?: string | undefined;
+        groupId: string;
+    } | undefined;
+}
+export declare function HighImpact({ t }: {
+    t: AccessStrings;
+}): import("react").JSX.Element;
+/** Asks before a group loses roles, saying exactly what it loses and what it keeps. */
+export declare function RemoveConfirm({ model, removal, saving, onCancel, onConfirm, t, }: {
+    model: AccessModel;
+    removal: PendingRemoval;
+    saving: boolean;
+    onCancel: () => void;
+    onConfirm: () => void;
+    t: AccessStrings;
+}): import("react").JSX.Element | null;
+/** Marks the button that asked for a removal, so focus can go back to it. */
+export declare const removeKey: (removal: PendingRemoval) => string;
+interface ViewProps {
+    model: AccessModel;
+    /** What the filter left: each role's groups, or each group's roles. */
+    shown: ReadonlyMap<string, readonly string[]>;
+    /** The rows in view, in order. */
+    order: readonly string[];
+    expanded: ReadonlySet<string>;
+    onExpandedChange: (id: string, open: boolean) => void;
+    filtering: boolean;
+    actions: ListActions;
+    t: AccessStrings;
+    sectionId: (id: string) => string;
+}
+/** Who has each role, role by role. */
+export declare function ByRole({ model, shown, order, expanded, onExpandedChange, filtering, actions, t, sectionId, }: ViewProps): (import("react").JSX.Element | null)[];
+/** Which roles each group has, group by group. */
+export declare function ByGroup({ model, shown, order, expanded, onExpandedChange, actions, t, sectionId, }: ViewProps): (import("react").JSX.Element | null)[];
+export {};