@ctrl-ui/react 0.9.5 → 0.9.8

package/README.md

@@ -47,10 +47,46 @@ const twMerge = extendTailwindMerge({ extend: { classGroups: { "font-size": [{ t
 
 Controls size their own text: pick the control's `size`, or set its `--cui-*-font-size` knob in your theme, rather than wrapping the label in a `text-*` span.
 
-With Biome, the shipped GritQL plugin warns on type rungs in `className`:
+## Lint rules
+
+Two rules keep call sites honest, shipped for Biome, ESLint, and oxlint from one policy (`lint/class-policy.mjs`):
+
+- `no-component-style-classes` errors when `className` on a component imported from `@ctrl-ui/react` (or a `components/control-ui` directory) sets what the component owns: colors, type, padding, borders, radius, shadows, state styles such as `hover:` and `data-[…]:`, or `!important`. Layout classes (`flex`, `gap-*`, widths, heights, margins, placement) stay allowed. Restyle through the component's props or its `--cui-*` knobs instead.
+- `no-raw-type-classes` errors on text sizes in any `className`: the type rungs, Tailwind's `text-xs`…`text-9xl`, and arbitrary `text-[13px]`. It reaches beyond Control UI, so adopt it folder by folder while you migrate.
+
+Biome, extending the shipped preset so rules added later arrive with the package update:
+
+```json
+{
+  "extends": ["@ctrl-ui/react/biome"],
+  "overrides": [{ "includes": ["src/features/**"], "plugins": ["./node_modules/@ctrl-ui/react/lint/no-raw-type-classes.grit"] }]
+}
+```
+
+ESLint flat config:
+
+```js
+import controlUi from "@ctrl-ui/react/eslint-plugin";
+
+export default [{ plugins: { "control-ui": controlUi }, rules: { "control-ui/no-component-style-classes": "error" } }];
+```
+
+oxlint, through its JS plugin support:
+
+```json
+{ "jsPlugins": ["@ctrl-ui/react/eslint-plugin"], "rules": { "control-ui/no-component-style-classes": "error" } }
+```
+
+When your app imports components through its own wrapper package or folder, declare that path so the rule follows those imports too:
+
+```js
+rules: { "control-ui/no-component-style-classes": ["error", { importSources: ["@acme/ui/components/"] }] }
+```
+
+Biome's Grit plugins take no options, so the package ships `control-ui-grit` to write the rules with your paths. Run it on install so a package update regenerates them, gitignore `.control-ui`, and list `./.control-ui/no-component-style-classes.grit` under `plugins` in place of the preset:
 
 ```json
-{ "plugins": ["./node_modules/@ctrl-ui/react/lint/no-raw-type-classes.grit"] }
+{ "scripts": { "postinstall": "control-ui-grit --import-source=@acme/ui/components/ --out=.control-ui" } }
 ```
 
 ## Customize

package/dist/action-bar.js

@@ -3,6 +3,7 @@ import { useCopyToClipboard } from "./hooks/use-copy-to-clipboard.js";
 import { cn } from "./lib/cn.js";
 import { Button } from "./ui/button.js";
 import { LiveStatus } from "./ui/live-status.js";
+import { Swap, SwapItem } from "./ui/swap.js";
 import { Toolbar } from "@base-ui/react/toolbar";
 import { createContext, useContext } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
@@ -66,21 +67,28 @@ function ActionBarCopy({ value, children = "Copy", copiedChildren = "Copied", co
 			onCopyError?.(error);
 		}
 	}
+	const copied = status === "copied";
 	let copyStatus = "";
-	if (status === "copied") copyStatus = copiedAriaLabel;
+	if (copied) copyStatus = copiedAriaLabel;
 	else if (status === "failed") copyStatus = copyFailedLabel;
-	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(ActionBarItem, {
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsxs(ActionBarItem, {
 		disabled: disabled ?? !copyValue,
 		onClick: handleClick,
 		...props,
-		children: status === "copied" ? /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("span", {
-			"aria-hidden": "true",
-			className: "contents",
-			children: copiedChildren
-		}), /* @__PURE__ */ jsx("span", {
+		children: [/* @__PURE__ */ jsxs(Swap, {
+			value: copied ? "copied" : "idle",
+			children: [/* @__PURE__ */ jsx(SwapItem, {
+				value: "idle",
+				children
+			}), /* @__PURE__ */ jsx(SwapItem, {
+				value: "copied",
+				"aria-hidden": "true",
+				children: copiedChildren
+			})]
+		}), copied ? /* @__PURE__ */ jsx("span", {
 			className: "sr-only",
 			children
-		})] }) : children
+		}) : null]
 	}), /* @__PURE__ */ jsx(LiveStatus, { message: copyStatus })] });
 }
 function ActionBarEdit({ value, children = "Edit", disabled, onClick, ...props }) {

package/dist/activity.d.ts

@@ -4,7 +4,7 @@ import { ScrollAreaProps } from "./ui/scroll-area.js";
 import { CSSProperties, ComponentProps, ReactNode } from "react";
 import { ChevronRight } from "lucide-react";
 //#region src/activity.d.ts
-export type ActivityState = "pending" | "running" | "success" | "error";
+export type ActivityState = "pending" | "running" | "waiting" | "success" | "error";
 export type ActivityKind = "default" | "tool" | "reasoning" | "signal";
 export type ActivityDetailFormat = "text" | "code";
 export type ActivityProps = Omit<CollapsibleProps, "children" | "style"> & {
@@ -45,8 +45,10 @@ export type ActivityDetailProps = ComponentProps<"div"> & {
 export declare function ActivityDetail({ className, ...props }: ActivityDetailProps): import("react").JSX.Element;
 export type ActivityDetailLabelProps = ActivityStyleProps<ComponentProps<"div">, ActivityKnobStyle>;
 export declare function ActivityDetailLabel({ className, ...props }: ActivityDetailLabelProps): import("react").JSX.Element;
+export type ActivityDetailTone = "default" | "destructive";
 export type ActivityDetailContentProps = ActivityStyleProps<ComponentProps<"div">, ActivityKnobStyle> & {
   format?: ActivityDetailFormat;
+  tone?: ActivityDetailTone;
 };
-export declare function ActivityDetailContent({ format, className, ...props }: ActivityDetailContentProps): import("react").JSX.Element;
+export declare function ActivityDetailContent({ format, tone, className, ...props }: ActivityDetailContentProps): import("react").JSX.Element;
 //#endregion

package/dist/activity.js

@@ -5,17 +5,19 @@ import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "./ui/collap
 import { ScrollArea } from "./ui/scroll-area.js";
 import { createContext, useContext } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { Check, ChevronRight, CircleAlert, CircleDashed, LoaderCircle } from "lucide-react";
+import { Check, ChevronRight, CircleAlert, CircleDashed, CirclePause, LoaderCircle } from "lucide-react";
 //#region src/activity.tsx
 const activityStatusLabels = {
 	pending: "Pending",
 	running: "Running",
+	waiting: "Waiting",
 	success: "Complete",
 	error: "Failed"
 };
 const activityStatusIcons = {
 	pending: CircleDashed,
 	running: LoaderCircle,
+	waiting: CirclePause,
 	success: Check,
 	error: CircleAlert
 };
@@ -166,12 +168,13 @@ function ActivityDetailLabel({ className, ...props }) {
 		className: cn("uppercase", className)
 	});
 }
-function ActivityDetailContent({ format = "text", className, ...props }) {
+function ActivityDetailContent({ format = "text", tone = "default", className, ...props }) {
 	return /* @__PURE__ */ jsx("div", {
 		"data-control-ui": "activity",
 		"data-control-family": "activity",
 		"data-slot": "detail-content",
 		"data-format": format,
+		"data-tone": tone,
 		...props,
 		className: cn("min-w-0 whitespace-pre-wrap wrap-anywhere", format === "code" && "w-fit max-w-full", className)
 	});

package/dist/audio-visualizer.js

@@ -61,7 +61,7 @@ function AudioVisualizer({ levels, points, active = true, className, style, ...p
 				const visibleLevel = MIN_VISIBLE_LEVEL + perceptualLevel * .96;
 				const levelStyle = {
 					"--_audio-visualizer-level-opacity": `${.48 + perceptualLevel * .52}`,
-					clipPath: `inset(${(1 - visibleLevel) * 50}% 0 round var(--cui-audio-visualizer-bar-radius))`
+					clipPath: `inset(${((1 - visibleLevel) * 50).toFixed(3)}% 0 round var(--cui-audio-visualizer-bar-radius))`
 				};
 				return /* @__PURE__ */ jsx("span", {
 					ref: key === "bar-0" ? firstBarRef : void 0,

package/dist/blocks/agent-run-clock.d.ts

@@ -0,0 +1,5 @@
+//#region src/blocks/agent-run-clock.d.ts
+export declare function useRunClock(active: boolean): number | null;
+export declare function formatElapsed(ms: number): string;
+export declare function elapsedIsoDuration(ms: number): string;
+//#endregion

package/dist/blocks/agent-run-clock.js

@@ -0,0 +1,52 @@
+import { useSyncExternalStore } from "react";
+//#region src/blocks/agent-run-clock.ts
+const TICK_MS = 1e3;
+let now = null;
+const listeners = /* @__PURE__ */ new Set();
+let interval;
+function tick() {
+	if (document.hidden) return;
+	now = Date.now();
+	for (const listener of listeners) listener();
+}
+function onVisibilityChange() {
+	if (!document.hidden) tick();
+}
+function subscribeToRunClock(listener) {
+	listeners.add(listener);
+	if (listeners.size === 1) {
+		now = Date.now();
+		interval = setInterval(tick, TICK_MS);
+		document.addEventListener("visibilitychange", onVisibilityChange);
+	}
+	return () => {
+		listeners.delete(listener);
+		if (listeners.size > 0) return;
+		clearInterval(interval);
+		interval = void 0;
+		document.removeEventListener("visibilitychange", onVisibilityChange);
+	};
+}
+const subscribeToNothing = () => () => {};
+function useRunClock(active) {
+	return useSyncExternalStore(active ? subscribeToRunClock : subscribeToNothing, () => now, () => null);
+}
+function splitElapsed(ms) {
+	const totalSeconds = Math.floor(Math.max(0, ms) / 1e3);
+	return {
+		hours: Math.floor(totalSeconds / 3600),
+		minutes: Math.floor(totalSeconds % 3600 / 60),
+		seconds: totalSeconds % 60
+	};
+}
+const pad2 = (value) => String(value).padStart(2, "0");
+function formatElapsed(ms) {
+	const { hours, minutes, seconds } = splitElapsed(ms);
+	return hours > 0 ? `${hours}:${pad2(minutes)}:${pad2(seconds)}` : `${minutes}:${pad2(seconds)}`;
+}
+function elapsedIsoDuration(ms) {
+	const { hours, minutes, seconds } = splitElapsed(ms);
+	return `PT${hours ? `${hours}H` : ""}${minutes ? `${minutes}M` : ""}${seconds}S`;
+}
+//#endregion
+export { elapsedIsoDuration, formatElapsed, useRunClock };

package/dist/blocks/agent-run-sidebar.d.ts

@@ -0,0 +1,13 @@
+import { AgentRunSummary } from "./agent-run-status.js";
+import { ReactNode } from "react";
+//#region src/blocks/agent-run-sidebar.d.ts
+export declare function AgentRunSidebar({ appName, brand, runs, activeRunId, sidebarFooter, onRunSelect, onNewRun }: {
+  appName: string;
+  brand?: ReactNode;
+  runs: readonly AgentRunSummary[];
+  activeRunId?: string;
+  sidebarFooter?: ReactNode;
+  onRunSelect?: (run: AgentRunSummary) => void;
+  onNewRun?: () => void;
+}): import("react").JSX.Element;
+//#endregion

package/dist/blocks/agent-run-sidebar.js

@@ -0,0 +1,101 @@
+"use client";
+import { Text } from "../ui/typography.js";
+import { useSidebar } from "../ui/sidebar-provider.js";
+import { SidebarGroup, SidebarGroupLabel, SidebarMenu, SidebarMenuButton, SidebarMenuItem } from "../ui/sidebar-menu.js";
+import { Sidebar, SidebarContent, SidebarFooter, SidebarHeader, SidebarRail } from "../ui/sidebar.js";
+import { agentRunStatusLabels } from "./agent-run-status.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { BotIcon, CheckIcon, CircleAlertIcon, CircleDashedIcon, CirclePauseIcon, CircleSlashIcon, LoaderCircleIcon, PlusIcon } from "lucide-react";
+//#region src/blocks/agent-run-sidebar.tsx
+const runStatusIcons = {
+	running: /* @__PURE__ */ jsx(LoaderCircleIcon, {
+		className: "size-3.5 shrink-0 motion-safe:animate-spin",
+		"aria-hidden": "true"
+	}),
+	waiting: /* @__PURE__ */ jsx(CirclePauseIcon, {
+		className: "size-3.5 shrink-0 text-warning-text",
+		"aria-hidden": "true"
+	}),
+	success: /* @__PURE__ */ jsx(CheckIcon, {
+		className: "size-3.5 shrink-0 text-success-text",
+		"aria-hidden": "true"
+	}),
+	error: /* @__PURE__ */ jsx(CircleAlertIcon, {
+		className: "size-3.5 shrink-0 text-destructive-text",
+		"aria-hidden": "true"
+	}),
+	cancelled: /* @__PURE__ */ jsx(CircleSlashIcon, {
+		className: "size-3.5 shrink-0 text-muted-foreground",
+		"aria-hidden": "true"
+	}),
+	pending: /* @__PURE__ */ jsx(CircleDashedIcon, {
+		className: "size-3.5 shrink-0 text-muted-foreground",
+		"aria-hidden": "true"
+	})
+};
+function AgentRunSidebar({ appName, brand, runs, activeRunId, sidebarFooter, onRunSelect, onNewRun }) {
+	const { setOpenMobile } = useSidebar();
+	return /* @__PURE__ */ jsxs(Sidebar, {
+		collapsible: "offcanvas",
+		children: [
+			/* @__PURE__ */ jsxs(SidebarHeader, {
+				divider: true,
+				className: "gap-1.5",
+				children: [/* @__PURE__ */ jsxs("div", {
+					className: "flex min-w-0 items-center gap-2 px-1 py-1",
+					children: [brand ?? /* @__PURE__ */ jsx("span", {
+						className: "flex size-6 shrink-0 items-center justify-center rounded-md bg-foreground text-background",
+						children: /* @__PURE__ */ jsx(BotIcon, {
+							className: "size-3.5",
+							"aria-hidden": "true"
+						})
+					}), /* @__PURE__ */ jsx(Text, {
+						size: "label",
+						weight: "semibold",
+						className: "truncate",
+						title: appName,
+						children: appName
+					})]
+				}), onNewRun ? /* @__PURE__ */ jsx(SidebarMenu, { children: /* @__PURE__ */ jsx(SidebarMenuItem, { children: /* @__PURE__ */ jsxs(SidebarMenuButton, {
+					size: "sm",
+					onClick: () => {
+						onNewRun();
+						setOpenMobile(false);
+					},
+					children: [/* @__PURE__ */ jsx(PlusIcon, {}), /* @__PURE__ */ jsx("span", { children: "New run" })]
+				}) }) }) : null]
+			}),
+			/* @__PURE__ */ jsx(SidebarContent, { children: /* @__PURE__ */ jsxs(SidebarGroup, {
+				className: "gap-1",
+				children: [/* @__PURE__ */ jsx(SidebarGroupLabel, { children: "Runs" }), runs.length === 0 ? /* @__PURE__ */ jsx(Text, {
+					size: "caption",
+					tone: "muted",
+					className: "mx-2",
+					children: "No runs yet"
+				}) : /* @__PURE__ */ jsx(SidebarMenu, { children: runs.map((run) => /* @__PURE__ */ jsx(SidebarMenuItem, { children: /* @__PURE__ */ jsxs(SidebarMenuButton, {
+					size: "sm",
+					isActive: run.id === activeRunId,
+					onClick: () => {
+						onRunSelect?.(run);
+						setOpenMobile(false);
+					},
+					children: [
+						runStatusIcons[run.status],
+						/* @__PURE__ */ jsx("span", {
+							className: "truncate",
+							children: run.title
+						}),
+						/* @__PURE__ */ jsxs("span", {
+							className: "sr-only",
+							children: [", ", agentRunStatusLabels[run.status]]
+						})
+					]
+				}) }, run.id)) })]
+			}) }),
+			sidebarFooter ? /* @__PURE__ */ jsx(SidebarFooter, { children: sidebarFooter }) : null,
+			/* @__PURE__ */ jsx(SidebarRail, {})
+		]
+	});
+}
+//#endregion
+export { AgentRunSidebar };

package/dist/blocks/agent-run-status.d.ts

@@ -0,0 +1,32 @@
+//#region src/blocks/agent-run-status.d.ts
+export type AgentRunStatus = "pending" | "running" | "waiting" | "success" | "error" | "cancelled";
+export type AgentRunSummary = {
+  id: string;
+  title: string;
+  status: AgentRunStatus;
+};
+export declare const agentRunStatusLabels: {
+  pending: string;
+  running: string;
+  waiting: string;
+  success: string;
+  error: string;
+  cancelled: string;
+};
+export declare const agentRunStatusColors: {
+  pending: "neutral";
+  running: "blue";
+  waiting: "yellow";
+  success: "green";
+  error: "red";
+  cancelled: "neutral";
+};
+export declare const agentRunStepLabels: {
+  neutral: string;
+  pending: string;
+  running: string;
+  waiting: string;
+  success: string;
+  error: string;
+};
+//#endregion

package/dist/blocks/agent-run-status.js

@@ -0,0 +1,27 @@
+//#region src/blocks/agent-run-status.ts
+const agentRunStatusLabels = {
+	pending: "Queued",
+	running: "Running",
+	waiting: "Needs approval",
+	success: "Done",
+	error: "Failed",
+	cancelled: "Cancelled"
+};
+const agentRunStatusColors = {
+	pending: "neutral",
+	running: "blue",
+	waiting: "yellow",
+	success: "green",
+	error: "red",
+	cancelled: "neutral"
+};
+const agentRunStepLabels = {
+	neutral: "Step",
+	pending: "Pending",
+	running: "Running",
+	waiting: "Waiting for approval",
+	success: "Done",
+	error: "Failed"
+};
+//#endregion
+export { agentRunStatusColors, agentRunStatusLabels, agentRunStepLabels };

package/dist/blocks/agent-run.d.ts

@@ -0,0 +1,82 @@
+import { ActivityProps } from "../activity.js";
+import { AgentRunStatus, AgentRunSummary } from "./agent-run-status.js";
+import { Card } from "../ui/card.js";
+import { SidebarProviderProps } from "../ui/sidebar-provider.js";
+import "../ui/sidebar.js";
+import { TimelineItemProps } from "../ui/timeline.js";
+import { TypeSize } from "../ui/typography.js";
+import { ComponentProps, ReactNode } from "react";
+//#region src/blocks/agent-run.d.ts
+type AgentRunLayout = "viewport" | "contained";
+export type AgentRunBlockProps = Omit<ComponentProps<"div">, "children"> & Pick<SidebarProviderProps, "persistOpen" | "keyboardShortcut"> & {
+  appName?: string;
+  brand?: ReactNode;
+  runs: readonly AgentRunSummary[];
+  activeRunId?: string;
+  onRunSelect?: (run: AgentRunSummary) => void;
+  onNewRun?: () => void;
+  sidebarFooter?: ReactNode;
+  children: ReactNode;
+  layout?: AgentRunLayout;
+};
+export declare function AgentRunBlock({ appName, brand, runs, activeRunId, onRunSelect, onNewRun, sidebarFooter, children, layout, className, style, ...props }: AgentRunBlockProps): import("react").JSX.Element;
+export type AgentRunElapsedProps = Omit<ComponentProps<"time">, "dateTime" | "children"> & {
+  startedAt: number;
+  endedAt?: number;
+  size?: TypeSize;
+};
+export declare function AgentRunElapsed({ startedAt, endedAt, size, className, ...props }: AgentRunElapsedProps): import("react").JSX.Element;
+export type AgentRunHeaderProps = Omit<ComponentProps<"header">, "title"> & {
+  title: string;
+  status: AgentRunStatus;
+  startedAt?: number;
+  endedAt?: number;
+  actions?: ReactNode;
+};
+export declare function AgentRunHeader({ title, status, startedAt, endedAt, actions, className, ...props }: AgentRunHeaderProps): import("react").JSX.Element;
+export type AgentRunBodyProps = ComponentProps<"div"> & {
+  aside?: ReactNode;
+};
+export declare function AgentRunBody({ aside, className, children, ...props }: AgentRunBodyProps): import("react").JSX.Element;
+export type AgentRunPlanProps = Omit<ComponentProps<"section">, "title"> & {
+  title?: ReactNode;
+  description?: ReactNode;
+};
+export declare function AgentRunPlan({ title, description, className, children, ...props }: AgentRunPlanProps): import("react").JSX.Element;
+export type AgentRunStepProps = Omit<TimelineItemProps, "title"> & {
+  title: ReactNode;
+  detail?: ReactNode;
+  startedAt?: number;
+  endedAt?: number;
+  actions?: ReactNode;
+};
+export declare function AgentRunStep({ title, detail, startedAt, endedAt, actions, state, children, ...props }: AgentRunStepProps): import("react").JSX.Element;
+export type AgentRunToolCallProps = Omit<ActivityProps, "kind" | "name" | "children"> & {
+  name: string;
+  summary?: ReactNode;
+  icon?: ReactNode;
+  input?: unknown;
+  output?: unknown;
+  errorText?: string;
+  startedAt?: number;
+  endedAt?: number;
+};
+export declare function AgentRunToolCall({ name, summary, icon, input, output, errorText, startedAt, endedAt, ...props }: AgentRunToolCallProps): import("react").JSX.Element;
+export type AgentRunAsideProps = ComponentProps<"aside">;
+export declare function AgentRunAside({ className, ...props }: AgentRunAsideProps): import("react").JSX.Element;
+export type AgentRunSectionProps = Omit<ComponentProps<typeof Card>, "title"> & {
+  title: ReactNode;
+  actions?: ReactNode;
+};
+export declare function AgentRunSection({ title, actions, children, ...props }: AgentRunSectionProps): import("react").JSX.Element;
+export type AgentRunDetail = {
+  label: string;
+  value: ReactNode;
+};
+export type AgentRunDetailsProps = Omit<AgentRunSectionProps, "title" | "children"> & {
+  title?: ReactNode;
+  items: readonly AgentRunDetail[];
+};
+export declare function AgentRunDetails({ title, items, ...props }: AgentRunDetailsProps): import("react").JSX.Element | null;
+//#endregion
+export type { AgentRunStatus, AgentRunSummary };