@parallelworks/ui 0.57.0 → 0.59.0

package/README.md

@@ -41,6 +41,12 @@ package navigates and never re-renders anything. Define slot components and
 string functions outside a component: one made each render is a new value, and
 a new slot component remounts what it renders.
 
+Under `UIProvider` the components render no inline `<style>`, so they run
+under a Content Security Policy whose `style-src` is `'self'` alone; the one
+rule a select or scroll area would inject ships in `theme.css`. A host that
+renders on the server passes its policy's `nonce`, which the few components
+that emit a script to place themselves before hydration put on it.
+
 ## Which component?
 
 Each need has one component. Reach for it before styling markup by hand.
@@ -60,7 +66,7 @@ Each need has one component. Reach for it before styling markup by hand.
 | A record's details, such as in a drawer or a card: names and values on their own | `DescriptionList` of `DescriptionListItem`s; `copy` on an ID, `mono` on a path, `variant="card"` to frame them; titled lists in a `DescriptionListGroup` to share one label column |
 | An error beside a control outside a `Field` | `ErrorText` |
 | A dense field in a toolbar or a table cell | any field control with `size="sm"`; a width in `className` wins, and `cx` merges classes the same way |
-| On or off | `Switch`; `Checkbox` in a list of things to tick, several of which may be on |
+| On or off | `Switch`; `Checkbox` in a list of things to tick, several of which may be on; either in a `Field` with `controlFirst` to read control, label, then its help and description |
 | 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 |
@@ -72,6 +78,7 @@ Each need has one component. Reach for it before styling markup by hand.
 | A titled part of a page or form | `Section` |
 | More detail under a line | `Disclosure` |
 | Views of one thing | `Tabs` |
+| Chrome that stays in view as the page scrolls | `sticky` on `ActionToolbar` or `Tabs`; `StickyBar` around controls of your own. They stack under the page header by themselves (see [Host chrome](#host-chrome)) |
 | A list of actions | `ActionMenu`; `useContextMenu` for a right-click or a row's menu |
 | A panel of controls anchored to a trigger | `Popover` |
 | 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 |
@@ -84,7 +91,7 @@ Each need has one component. Reach for it before styling markup by hand.
 | How full something is, how far a task has come | `Meter`, `ProgressBar` |
 | Pages of a long list | `Pagination` |
 | A grouped page of settings | `SettingsCard` with `SettingRow`s |
-| A person | `Avatar` |
+| A person | `Avatar`, colored by name without a picture |
 | A status in words | `StatusBadge`, or `StatusDot` beside text that says it |
 | A run's, job's or step's status beside its name | `RunStatusIcon`; `StatusBadge` with `runStatusTone` to say it in words |
 | A copy action | `CopyButton`; `CopyCodeBlock` for a command or snippet; `useCopy` for a menu row or a control of your own |
@@ -312,6 +319,16 @@ icon beside an error message may keep the message's text shade through
 from the accent's hue when they come within 30° of it, so a keyword never looks
 like a link.
 
+Eight category colors tell things apart without ranking them:
+`--theme-category-1` to `--theme-category-8` are soft fills at hues 45° apart,
+all at one lightness and chroma so none reads louder, and each
+`--theme-category-N-text` is solved to secondary text's targets on its fill. An
+`Avatar` without a picture takes one, picked by an FNV-1a hash of its name (or
+its `colorKey`), so the same name has the same color on every page; a nameless
+one keeps the accent. `categoryOf(key)` gives the same pick, 1–8, and
+`categoryClasses(key)` its fill and text classes, for anything else drawn
+beside a name, such as a group's icon.
+
 Every color is mapped into sRGB with the CSS Color 4 method, which lowers
 chroma at fixed lightness and hue. It is mapped into display-p3 too: where the
 wider color differs from sRGB by more than one just-noticeable difference
@@ -343,9 +360,20 @@ leaves unset follows the `color-scheme` it sets:
 ```css
 /* In a Tailwind v4 build: */
 @import '@parallelworks/ui/theme.css';
-@source '../node_modules/@parallelworks/ui/src/**/*.{ts,tsx}';
+@source '../node_modules/@parallelworks/ui/dist/components';
+@source '../node_modules/@parallelworks/ui/dist/list';
 ```
 
+The package publishes only `dist`, built one JavaScript module per source
+module under the same folders as its subpaths (`dist/components`, `dist/list`,
+`dist/form`, `dist/ai` and so on), so `@source` points at those modules. List
+the folders of the subpaths the host imports: each one adds the utilities of
+every component in it. Scanning all of `dist` works too, but also reads the
+editor's bundled workers in `dist/assets`. A host that wants only a few
+components can name their modules one by one, such as
+`dist/components/Avatar.js`, as long as it also names the modules they style
+through, such as `dist/components/floating.js` for a popup's panel.
+
 Consumers without a Tailwind build can import the compiled standalone
 stylesheet instead:
 
@@ -566,13 +594,41 @@ root:
 | ------------------- | ----------------------------------------------------------------------- |
 | `--app-inset-top`   | The height of a fixed top bar. Drawers and toasts start below it.       |
 | `--app-inset-start` | The width of a fixed sidebar on the start side. Toasts center over the page beside it, and a drawer at its widest leaves that strip, and never less than 2.5rem. Update it when the sidebar collapses. |
-| `--table-header-top` | How far below the top of its scrolling box a table's sticky header row stops (`Table stickyHeader`, which list tables use). Set it on the scrolling box, or an ancestor, when something else sticks at that box's top, such as a page header in a page that scrolls as a whole. Inside `ListPage` the rows scroll in their own box below the header and toolbar, so it stays 0. |
 
 ```ts
 document.documentElement.style.setProperty('--app-inset-top', '56px')
 document.documentElement.style.setProperty('--app-inset-start', '220px')
 ```
 
+Sticky chrome stacks by itself, with no offsets to set. A page's pinned pieces,
+`ActionToolbar sticky`, `Tabs sticky`, a `StickyBar` around controls of the
+page's own, and a table's header row (`Table stickyHeader`, which list tables
+use), each stop just below whatever their scrolling box already pins at the top.
+Each finds the elements there with `position: sticky` and a `top` whose parent
+also holds it, so they stay pinned while it passes, and follows them as they
+wrap to a new height or come and go, before the page paints. In a box that
+scrolls on its own, such as a fixed-height panel or `ListPage`'s rows, they pin
+at the box's top.
+
+The stack starts from the host's page header. Put it inside the page's
+scroller, ahead of the page, with `position: sticky` and a `top`, such as
+`sticky top-0`: as a child of the scroller or of a wrapper the page also sits
+in. A header above the scroller, outside it, needs nothing: the page's chrome
+pins at the scroller's top, just under it.
+
+```tsx
+<div className="overflow-auto">
+  <header className="sticky top-0 z-(--layer-header)">…</header>
+  <main>
+    <StickyBar className="px-4 py-1.5">
+      <ActionToolbar groups={actions} />
+    </StickyBar>
+    <Tabs label="Cluster" sticky items={tabs} />
+    <Table stickyHeader>…</Table>
+  </main>
+</div>
+```
+
 Everything the package lays over the page stacks on one scale, set on the
 document root by `base.css`. Give the host's own fixed elements a place on it,
 such as `z-index: 100` for a top bar, rather than a z-index chosen to win:

package/dist/access/PrincipalPicker.js

@@ -1,6 +1,7 @@
 import { cx } from "../cx.js";
 import { OrganizationIcon, RefreshIcon, UsersIcon } from "../icons.js";
 import { useQueryMatch } from "../components/search.js";
+import { categoryClasses } from "../components/category.js";
 import { Avatar } from "../components/Avatar.js";
 import { Callout } from "../components/Callout.js";
 import { Combobox } from "../components/Combobox.js";
@@ -35,7 +36,7 @@ function PrincipalTile({ principal, compact = false, className }) {
 	const Icon = everyone ? OrganizationIcon : UsersIcon;
 	return /* @__PURE__ */ jsx("span", {
 		"aria-hidden": "true",
-		className: cx("flex size-8 shrink-0 items-center justify-center rounded-md [&_svg]:size-4", compact && "size-6 [&_svg]:size-3.5", everyone ? "bg-(--theme-info-muted) text-(--theme-info-text)" : "bg-(--theme-muted-panel-bg) text-(--theme-muted-text-color)", className),
+		className: cx("flex size-8 shrink-0 items-center justify-center rounded-md [&_svg]:size-4", compact && "size-6 [&_svg]:size-3.5", everyone ? "bg-(--theme-info-muted) text-(--theme-info-text)" : categoryClasses(principal.name), className),
 		children: /* @__PURE__ */ jsx(Icon, {})
 	});
 }

package/dist/ai/agent/diff.d.ts

@@ -10,6 +10,7 @@ export interface EditToolArgs {
 }
 export declare function isEditDiffTool(name: string): boolean;
 export declare function parseEditArgs(argsJSON: string): EditToolArgs | null;
+export declare const MAX_DIFF_CELLS = 1000000;
 export declare function wordEmphasisRanges(oldLine: string, newLine: string): Array<[number, number]> | null;
 export declare function lineDelta(oldLines: string[], newLines: string[]): [number, number];
 export interface DiffRow {

package/dist/ai/agent/diff.js

@@ -19,7 +19,51 @@ function splitLines(s) {
 	const trimmed = s.endsWith("\n") ? s.slice(0, -1) : s;
 	return trimmed === "" ? [] : trimmed.split("\n");
 }
+var MAX_DIFF_CELLS = 1e6;
 function getOpCodes(a, b) {
+	if (a.length * b.length <= 1e6) return lcsOpCodes(a, b);
+	let start = 0;
+	while (start < a.length && start < b.length && a[start] === b[start]) start++;
+	let endA = a.length;
+	let endB = b.length;
+	while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+		endA--;
+		endB--;
+	}
+	const midA = a.slice(start, endA);
+	const midB = b.slice(start, endB);
+	const middle = midA.length * midB.length <= 1e6 ? lcsOpCodes(midA, midB) : [{
+		tag: "r",
+		i1: 0,
+		i2: midA.length,
+		j1: 0,
+		j2: midB.length
+	}];
+	const ops = [];
+	if (start > 0) ops.push({
+		tag: "e",
+		i1: 0,
+		i2: start,
+		j1: 0,
+		j2: start
+	});
+	for (const op of middle) ops.push({
+		tag: op.tag,
+		i1: op.i1 + start,
+		i2: op.i2 + start,
+		j1: op.j1 + start,
+		j2: op.j2 + start
+	});
+	if (endA < a.length) ops.push({
+		tag: "e",
+		i1: endA,
+		i2: a.length,
+		j1: endB,
+		j2: b.length
+	});
+	return ops;
+}
+function lcsOpCodes(a, b) {
 	const n = a.length;
 	const m = b.length;
 	const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
@@ -106,9 +150,12 @@ function wordEmphasisRanges(oldLine, newLine) {
 	return ranges.length > 0 ? ranges : null;
 }
 function lineDelta(oldLines, newLines) {
+	return countLines(getOpCodes(oldLines, newLines));
+}
+function countLines(ops) {
 	let added = 0;
 	let removed = 0;
-	for (const op of getOpCodes(oldLines, newLines)) {
+	for (const op of ops) {
 		if (op.tag === "d" || op.tag === "r") removed += op.i2 - op.i1;
 		if (op.tag === "i" || op.tag === "r") added += op.j2 - op.j1;
 	}
@@ -117,8 +164,8 @@ function lineDelta(oldLines, newLines) {
 function computeEditDiff(oldString, newString, startLine = 0) {
 	const oldLines = splitLines(oldString);
 	const newLines = splitLines(newString);
-	const [added, removed] = lineDelta(oldLines, newLines);
 	const ops = getOpCodes(oldLines, newLines);
+	const [added, removed] = countLines(ops);
 	const numbered = startLine > 0;
 	const rows = [];
 	let truncated = false;
@@ -213,4 +260,4 @@ function editSummary(toolName, argsJSON, t = defaultToolStrings) {
 	return "";
 }
 //#endregion
-export { MAX_EDIT_DIFF_LINES, MAX_WRITE_DIFF_LINES, computeEditDiff, computeWriteRows, editSummary, isEditDiffTool, lineDelta, parseEditArgs, wordEmphasisRanges };
+export { MAX_DIFF_CELLS, MAX_EDIT_DIFF_LINES, MAX_WRITE_DIFF_LINES, computeEditDiff, computeWriteRows, editSummary, isEditDiffTool, lineDelta, parseEditArgs, wordEmphasisRanges };

package/dist/ai/ai.css

@@ -182,6 +182,44 @@
 .markdown [data-streamdown="table"] tbody tr:last-child {
   border-bottom: 0;
 }
+/* Markdown set inside other UI, such as a step's summary, reads at the page's
+ * text size, its headings a step above it rather than at a document's sizes. */
+.markdown-compact {
+  font-size: 0.875rem;
+  line-height: 1.5;
+}
+.markdown-compact :is(h1, h2, h3, h4, h5, h6) {
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  font-weight: 600;
+}
+.markdown-compact :is(h1, h2) {
+  font-size: 1rem;
+  line-height: 1.5rem;
+}
+.markdown-compact [data-streamdown="table-wrapper"] table,
+.markdown-compact [data-streamdown="table"] :is(th, td) {
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+}
+/* A summary's tables are mostly a few short columns of counts: they hug their
+ * content so each number sits by its label, and a phone fits them unscrolled. */
+.markdown-compact table[data-streamdown="table"] {
+  width: auto;
+  min-width: min(100%, 20rem);
+}
+.markdown-compact [data-streamdown="table"] :is(th, td) {
+  min-width: 0;
+  padding-inline-end: 2rem;
+  font-variant-numeric: tabular-nums;
+}
+.markdown-compact [data-streamdown="table"] th {
+  font-weight: 500;
+  color: var(--theme-muted-text-color);
+}
+.markdown-compact :not(pre) > code {
+  font-size: 0.8125rem;
+}
 @media (prefers-reduced-motion: reduce) {
   .markdown [data-streamdown="table-wrapper"] > div:first-child {
     transition: none;

package/dist/ai/components/AttachmentUpload.d.ts

@@ -16,6 +16,9 @@ export interface Attachment {
 interface AttachmentUploadProps {
     conversationId?: string | undefined;
     attachments: Attachment[];
+    /** The list with a change. Keep its entries as given: an upload's result
+     *  replaces its pending entry by identity, on the list as it is when the
+     *  upload finishes. */
     onAttachmentsChange: (attachments: Attachment[]) => void;
     disabled?: boolean;
     maxFiles?: number;

package/dist/ai/components/AttachmentUpload.js

@@ -7,7 +7,7 @@ import { useChatConfig } from "../core/config.js";
 import { useChat } from "../core/ChatProvider.js";
 import { ATTACHMENTS_INFINITE_KEY } from "./attachmentKeys.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { useCallback, useImperativeHandle, useRef, useState } from "react";
+import { useCallback, useImperativeHandle, useLayoutEffect, useRef, useState } from "react";
 import { mutate } from "swr";
 //#region src/ai/components/AttachmentUpload.tsx
 var DEFAULT_MAX_FILE_SIZE = 26214400;
@@ -24,18 +24,23 @@ function AttachmentUpload({ conversationId, attachments, onAttachmentsChange, di
 	const { common } = useStrings();
 	const [isDragging, setIsDragging] = useState(false);
 	const fileInputRef = useRef(null);
-	const validateFile = useCallback((file) => {
-		if (file.size > maxFileSize) return t.fileTooLarge(formatBytes(maxFileSize));
-		if (attachments.length >= maxFiles) return t.maxFilesAllowed(maxFiles);
-		return null;
-	}, [
-		attachments.length,
-		maxFileSize,
-		maxFiles,
-		t
-	]);
+	const latest = useRef(attachments);
+	useLayoutEffect(() => {
+		latest.current = attachments;
+	}, [attachments]);
+	const commit = useCallback((next) => {
+		latest.current = next;
+		onAttachmentsChange(next);
+	}, [onAttachmentsChange]);
 	const uploadFile = useCallback(async (file) => {
-		if (!adapter.attachments) return null;
+		const failed = (error) => ({
+			file,
+			filename: file.name,
+			mimeType: file.type,
+			size: file.size,
+			error
+		});
+		if (!adapter.attachments) return failed(t.uploadUnavailable);
 		try {
 			const uploaded = await adapter.attachments.upload(file, conversationId);
 			await mutate(ATTACHMENTS_INFINITE_KEY);
@@ -47,44 +52,47 @@ function AttachmentUpload({ conversationId, attachments, onAttachmentsChange, di
 				uploaded: true
 			};
 		} catch (error) {
-			return {
-				file,
-				filename: file.name,
-				mimeType: file.type,
-				size: file.size,
-				error: error instanceof Error ? error.message : String(error)
-			};
+			return failed(error instanceof Error ? error.message : String(error));
 		}
-	}, [adapter, conversationId]);
+	}, [
+		adapter,
+		conversationId,
+		t
+	]);
 	const handleFiles = useCallback(async (files) => {
-		const fileArray = Array.from(files);
-		const newAttachments = [];
-		for (const file of fileArray) {
-			const error = validateFile(file);
-			if (error) {
-				toast.error(error);
+		const pending = [];
+		let room = maxFiles - latest.current.length;
+		let overLimit = false;
+		for (const file of Array.from(files)) {
+			if (file.size > maxFileSize) {
+				toast.error(t.fileTooLarge(formatBytes(maxFileSize)));
 				continue;
 			}
-			const pendingAttachment = {
+			if (room <= 0) {
+				overLimit = true;
+				continue;
+			}
+			room--;
+			pending.push({
 				file,
 				filename: file.name,
 				mimeType: file.type,
 				size: file.size,
 				uploading: true
-			};
-			newAttachments.push(pendingAttachment);
+			});
 		}
-		onAttachmentsChange([...attachments, ...newAttachments]);
-		const uploaded = await Promise.all(newAttachments.map(async (a) => {
-			if (a.file) return uploadFile(a.file);
-			return a;
-		}));
-		onAttachmentsChange(attachments.concat(uploaded.filter((a) => a !== null)));
+		if (overLimit) toast.error(t.maxFilesAllowed(maxFiles));
+		if (pending.length === 0) return;
+		commit([...latest.current, ...pending]);
+		const results = await Promise.all(pending.map((a) => uploadFile(a.file)));
+		const resultOf = new Map(pending.map((a, i) => [a, results[i]]));
+		commit(latest.current.map((a) => resultOf.get(a) ?? a));
 	}, [
-		attachments,
-		onAttachmentsChange,
-		uploadFile,
-		validateFile
+		commit,
+		maxFileSize,
+		maxFiles,
+		t,
+		uploadFile
 	]);
 	const handleDragOver = useCallback((e) => {
 		e.preventDefault();
@@ -103,9 +111,9 @@ function AttachmentUpload({ conversationId, attachments, onAttachmentsChange, di
 		if (e.target.files && e.target.files.length > 0) handleFiles(e.target.files);
 		e.target.value = "";
 	}, [handleFiles]);
-	const handleRemove = useCallback((index) => {
-		onAttachmentsChange(attachments.filter((_, i) => i !== index));
-	}, [attachments, onAttachmentsChange]);
+	const handleRemove = useCallback((attachment) => {
+		commit(latest.current.filter((a) => a !== attachment));
+	}, [commit]);
 	useImperativeHandle(ref, () => ({ addFiles: handleFiles }), [handleFiles]);
 	const handleClick = () => {
 		fileInputRef.current?.click();
@@ -148,7 +156,7 @@ function AttachmentUpload({ conversationId, attachments, onAttachmentsChange, di
 						}),
 						/* @__PURE__ */ jsx("button", {
 							type: "button",
-							onClick: () => handleRemove(index),
+							onClick: () => handleRemove(attachment),
 							className: "p-0.5 rounded hover:bg-(--theme-error-muted)",
 							title: common.remove,
 							disabled,

package/dist/ai/components/agent/AgentMessageParts.js

@@ -92,10 +92,30 @@ function DiffRows({ rows, lang }) {
 function EditDiffBlock({ part }) {
 	const { strings } = useChatConfig();
 	const t = strings.agentTranscript;
-	const a = parseEditArgs(part.args);
-	if (!a) return null;
-	const outcome = editSummary(part.name, part.args, strings.tools);
-	const model = part.name === "EditFile" ? computeEditDiff(a.old_string ?? "", a.new_string ?? "", part.startLine) : computeWriteRows(a.content ?? "");
+	const diff = useMemo(() => {
+		const a = parseEditArgs(part.args);
+		if (!a) return null;
+		if (part.name === "EditFile") {
+			const model = computeEditDiff(a.old_string ?? "", a.new_string ?? "", part.startLine);
+			return {
+				a,
+				model,
+				outcome: strings.tools.edited(model.added, model.removed)
+			};
+		}
+		return {
+			a,
+			model: computeWriteRows(a.content ?? ""),
+			outcome: editSummary(part.name, part.args, strings.tools)
+		};
+	}, [
+		part.name,
+		part.args,
+		part.startLine,
+		strings.tools
+	]);
+	if (!diff) return null;
+	const { a, model, outcome } = diff;
 	return /* @__PURE__ */ jsxs("div", {
 		className: "mt-1.5 space-y-1",
 		children: [
@@ -210,10 +230,17 @@ function ToolCallBlock({ part }) {
 	const header = toolHeaderFor(part.name);
 	const argSummary = summarizeToolArgs(header.arg, part.args);
 	const isDiff = isEditDiffTool(part.name);
-	const summary = part.status === "running" ? t.running : toolSummary(part.name, part.args, part.result ?? "", part.status === "error", {
+	const summary = useMemo(() => part.status === "running" ? t.running : toolSummary(part.name, part.args, part.result ?? "", part.status === "error", {
 		editSummary,
 		strings: strings.tools
-	});
+	}), [
+		part.status,
+		part.name,
+		part.args,
+		part.result,
+		t.running,
+		strings.tools
+	]);
 	return /* @__PURE__ */ jsxs("div", {
 		className: "py-1.5 text-sm",
 		"data-testid": "tool-call-part",

package/dist/ai/strings.d.ts

@@ -139,6 +139,8 @@ export interface ChatStrings {
         addFiles: string;
         maxSizePerFile: (size: string) => string;
         uploading: string;
+        /** On a file added where the chat has nowhere to upload it. */
+        uploadUnavailable: string;
     };
     attachmentManager: {
         title: string;

package/dist/ai/strings.js

@@ -174,7 +174,8 @@ var defaultChatStrings = {
 		releaseToUpload: "Release to upload",
 		addFiles: "Add files (drag or click)",
 		maxSizePerFile: (size) => `Max ${size} per file`,
-		uploading: "Uploading…"
+		uploading: "Uploading…",
+		uploadUnavailable: "Attachments can’t be uploaded here"
 	},
 	attachmentManager: {
 		title: "Attachments",

package/dist/components/AppLink.js

@@ -3,9 +3,14 @@ import { useLink, useStrings } from "./Provider.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/AppLink.tsx
 function leavesApp(url) {
-	if (!/^([a-z][a-z\d+.-]*:|\/\/)/i.test(url)) return false;
-	if (typeof window === "undefined") return true;
-	return new URL(url, window.location.href).origin !== window.location.origin;
+	if (typeof window === "undefined") return /^([a-z][a-z\d+.-]*:|[/\\]{2})/i.test(url.replace(/[\t\n\r]/g, "").trimStart());
+	const { origin, protocol } = window.location;
+	try {
+		const resolved = new URL(url, window.location.href);
+		return resolved.origin !== origin || resolved.protocol !== protocol;
+	} catch {
+		return true;
+	}
 }
 /** True for a click the browser would open in place: the primary button with
 *  no modifier. A link's own onClick work, such as closing a drawer or clearing

package/dist/components/Avatar.d.ts

@@ -4,6 +4,10 @@ export interface AvatarProps {
     /** Image URL. Until it loads, or when it fails, the initials of `name` show. */
     src?: string | null | undefined;
     name?: string | undefined;
+    /** Picks the fallback's color from the theme's categorical palette, so the same key gets the
+     *  same color everywhere. Defaults to `name`; pass a stable id when names can repeat or
+     *  change, or `null` for the accent fill whatever the name. Without either, the accent fills it. */
+    colorKey?: string | null | undefined;
     size?: AvatarSize | undefined;
     status?: AvatarStatus | undefined;
     className?: string | undefined;
@@ -13,4 +17,4 @@ export declare function avatarInitials(name: string | undefined): string;
 /** A person's picture, or their initials while it loads or when it fails. It is
  *  one image to assistive technology, named for the person, whichever shows,
  *  and their presence when it has a status dot. */
-export declare function Avatar({ src, name, size, status, className }: AvatarProps): import("react").JSX.Element;
+export declare function Avatar({ src, name, colorKey, size, status, className }: AvatarProps): import("react").JSX.Element;

package/dist/components/Avatar.js

@@ -1,5 +1,6 @@
 import { cx } from "../cx.js";
 import { useStrings } from "./Provider.js";
+import { categoryClasses } from "./category.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Avatar } from "@base-ui/react/avatar";
 //#region src/components/Avatar.tsx
@@ -17,20 +18,27 @@ var STATUS_CLASSES = {
 	busy: "bg-(--theme-error)",
 	away: "bg-(--theme-warning)"
 };
+var graphemes = typeof Intl !== "undefined" && "Segmenter" in Intl ? new Intl.Segmenter(void 0, { granularity: "grapheme" }) : void 0;
+function firstCharacter(text) {
+	if (!text) return;
+	if (graphemes) return graphemes.segment(text)[Symbol.iterator]().next().value?.segment;
+	return Array.from(text)[0];
+}
 /** Up to two initials: the first and last word of a name split on spaces and dots. */
 function avatarInitials(name) {
 	const parts = (name ?? "").split(/[\s.]+/).filter(Boolean);
-	const first = parts[0]?.charAt(0);
-	const last = parts.at(-1)?.charAt(0);
+	const first = firstCharacter(parts[0]);
+	const last = firstCharacter(parts.at(-1));
 	if (parts.length >= 2 && first && last) return (first + last).toUpperCase();
 	return first?.toUpperCase() || "?";
 }
 /** A person's picture, or their initials while it loads or when it fails. It is
 *  one image to assistive technology, named for the person, whichever shows,
 *  and their presence when it has a status dot. */
-function Avatar$1({ src, name, size = "md", status, className }) {
+function Avatar$1({ src, name, colorKey, size = "md", status, className }) {
 	const { common } = useStrings();
 	const who = name || common.userAvatar;
+	const colorBy = colorKey === void 0 ? name?.trim() : colorKey;
 	return /* @__PURE__ */ jsxs("span", {
 		role: "img",
 		"aria-label": status ? common.withPresence(who, common.presence[status]) : who,
@@ -45,8 +53,8 @@ function Avatar$1({ src, name, size = "md", status, className }) {
 				className: "absolute inset-0 size-full object-cover data-error:hidden data-loading:invisible"
 			}, src), /* @__PURE__ */ jsx(Avatar.Fallback, {
 				"aria-hidden": "true",
-				className: "flex size-full items-center justify-center bg-gradient-to-br from-[var(--gradient-start,var(--theme-accent))] to-[var(--gradient-mid,var(--theme-link))] text-(--theme-accent-text)",
-				children: size === "xs" ? avatarInitials(name).charAt(0) : avatarInitials(name)
+				className: cx("flex size-full items-center justify-center", colorBy ? categoryClasses(colorBy) : "bg-gradient-to-br from-[var(--gradient-start,var(--theme-accent))] to-[var(--gradient-mid,var(--theme-link))] text-(--theme-accent-text)"),
+				children: size === "xs" ? firstCharacter(avatarInitials(name)) : avatarInitials(name)
 			})]
 		}), status && /* @__PURE__ */ jsx("span", {
 			"data-testid": "online-indicator",

package/dist/components/ExternalLink.d.ts

@@ -4,5 +4,6 @@ export type ExternalLinkProps = Omit<ComponentPropsWithRef<'a'>, 'target' | 'rel
     icon?: boolean;
 };
 /** A link that opens in a new tab, says so to screen readers, and gives the
- *  page it opens no hold on this one. */
-export declare function ExternalLink({ children, icon, className, ...props }: ExternalLinkProps): import("react").JSX.Element;
+ *  page it opens no hold on this one. Its href passes `safeUrl`, as every
+ *  component's does, and one that doesn't is dropped. */
+export declare function ExternalLink({ href, children, icon, className, ...props }: ExternalLinkProps): import("react").JSX.Element;

package/dist/components/ExternalLink.js

@@ -1,14 +1,17 @@
 import { cx } from "../cx.js";
 import { ExternalLinkIcon } from "../icons.js";
+import { safeUrl } from "../safeUrl.js";
 import { useStrings } from "./Provider.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/ExternalLink.tsx
 /** A link that opens in a new tab, says so to screen readers, and gives the
-*  page it opens no hold on this one. */
-function ExternalLink({ children, icon = false, className, ...props }) {
+*  page it opens no hold on this one. Its href passes `safeUrl`, as every
+*  component's does, and one that doesn't is dropped. */
+function ExternalLink({ href, children, icon = false, className, ...props }) {
 	const { common } = useStrings();
 	return /* @__PURE__ */ jsxs("a", {
 		...props,
+		href: safeUrl(href),
 		target: "_blank",
 		rel: "noopener noreferrer",
 		className: cx(icon && "inline-flex items-center gap-1", className),

package/dist/components/Field.d.ts

@@ -59,6 +59,12 @@ export interface FieldProps {
     size?: FieldBoxSize | undefined;
     /** A set of controls, such as radios or checkboxes, that a legend names instead of a label. */
     group?: boolean | undefined;
+    /** Puts a checkbox, a switch or a lone radio before its label, as such a control reads: the
+     *  control, then its label and ?, with the description and error under the label. A click on
+     *  the label sets the control. Inline, or in a row of fields, it sits in the control column,
+     *  its first line on the line of the labels beside it. Not for a `group`, whose options are
+     *  each a `FieldOption`. */
+    controlFirst?: boolean | undefined;
     /** The control's id; one is made up when left out. */
     id?: string | undefined;
     className?: string | undefined;
@@ -77,7 +83,7 @@ export declare function ErrorText({ id, children }: {
 }): import("react").JSX.Element | null;
 /** A control with its label, help and error, tied to it for assistive technology. One frame
  *  for every field, in a form or standing alone. */
-export declare function Field({ label, hint, help, actions, description, error, invalid, required, disabled, layout, compact, size, group, id: ownId, className, children, }: FieldProps): import("react").JSX.Element;
+export declare function Field({ label, hint, help, actions, description, error, invalid, required, disabled, layout, compact, size, group, controlFirst, id: ownId, className, children, }: FieldProps): import("react").JSX.Element;
 /** One checkbox or radio and its label inside a Field, such as an option of a group. A bare
  *  `<label>` there would take the Field's label as its own, so every option read as the field. */
 export declare function FieldOption({ disabled, className, children, }: {