@ctrl-ui/react 0.8.0

package/README.md

@@ -0,0 +1,70 @@
+# @ctrl-ui/react
+
+Every Control UI component, block, and primitive with the Refined skin, as a versioned package. Same source as the registry, built from the `all-refined` install set. Prefer the [registry](https://control-ui.dev/get-started) when you want to own and edit the source or run another skin.
+
+## Install
+
+```bash
+bun add @ctrl-ui/react
+```
+
+Requires React 19 and Tailwind CSS v4. Wire the styles once in `app/globals.css`:
+
+```css
+@import "tailwindcss";
+@import "@ctrl-ui/react/styles/index.css";
+@source "../node_modules/@ctrl-ui/react/dist";
+```
+
+Stamp the skin on the root element:
+
+```tsx
+<html lang="en" data-skin="refined">
+```
+
+## Use
+
+Import paths mirror the registry tree, so any docs example works after replacing `@/components/control-ui/` with `@ctrl-ui/react/`.
+
+```tsx
+import { ChatMessage } from "@ctrl-ui/react/chat-message";
+import { Button } from "@ctrl-ui/react/ui/button";
+```
+
+`styles/index.css` imports every recipe. To ship less CSS, import the four base sheets and only the recipes you use:
+
+```css
+@import "@ctrl-ui/react/styles/theme.css";
+@import "@ctrl-ui/react/styles/effects.css";
+@import "@ctrl-ui/react/styles/skin-theme.css";
+@import "@ctrl-ui/react/styles/skin.css";
+@import "@ctrl-ui/react/styles/recipes/button.css";
+```
+
+## Customize
+
+Override tokens after the imports, and tune a component through its typed knobs:
+
+```css
+[data-skin="refined"] {
+  --cui-accent: oklch(0.6 0.2 260);
+}
+```
+
+```tsx
+<Button style={{ "--cui-button-radius": "4px" }}>Save</Button>
+```
+
+## Optional peers
+
+Install a peer only when you import the component that needs it.
+
+| Component | Peer |
+| --- | --- |
+| `ui/calendar` | `react-day-picker` |
+| `ui/code`, `ui/code-diff` | `@tanstack/react-virtual`, `diff`, `shiki` |
+| `ui/command` | `cmdk` |
+| `ui/markdown` | `streamdown` |
+| `ui/phone-input` | `react-phone-number-input`, `libphonenumber-js`, `zod` |
+| `ui/resizable` | `react-resizable-panels` |
+| `chat-composer` | `prosemirror-*` |

package/dist/action-bar.d.ts

@@ -0,0 +1,44 @@
+import { ActionBarKnobStyle } from "./knob-contracts/action-bar-knobs.js";
+import { Button } from "./ui/button.js";
+import { CSSProperties, ComponentProps, ReactNode } from "react";
+//#region src/action-bar.d.ts
+type ActionBarCopyValue = string | (() => string | Promise<string>);
+type ActionBarContextValue = {
+  copyValue?: ActionBarCopyValue;
+  editValue?: ActionBarCopyValue;
+  onCopy?: (value: string) => void;
+  onCopyError?: (error: unknown) => void;
+  onEdit?: (value: string) => void;
+  onEditError?: (error: unknown) => void;
+};
+type ActionBarProps = Omit<ComponentProps<"div">, "style"> & {
+  label?: string;
+  align?: "start" | "end";
+  context?: ActionBarContextValue;
+  copyValue?: ActionBarCopyValue;
+  editValue?: ActionBarCopyValue;
+  onCopy?: (value: string) => void;
+  onCopyError?: (error: unknown) => void;
+  onEdit?: (value: string) => void;
+  onEditError?: (error: unknown) => void;
+  style?: CSSProperties & ActionBarKnobStyle;
+};
+declare function ActionBar({ label, align, className, children, context, copyValue, editValue, onCopy, onCopyError, onEdit, onEditError, ...props }: ActionBarProps): import("react").JSX.Element;
+type ActionBarItemProps = ComponentProps<typeof Button> & {
+  icon?: ReactNode;
+};
+declare function ActionBarItem({ icon, children, className, ...props }: ActionBarItemProps): import("react").JSX.Element;
+type ActionBarCopyProps = Omit<ActionBarItemProps, "children"> & {
+  value?: ActionBarCopyValue;
+  children?: ReactNode;
+  copiedChildren?: ReactNode;
+  resetDelay?: number;
+};
+declare function ActionBarCopy({ value, children, copiedChildren, resetDelay, disabled, onClick, ...props }: ActionBarCopyProps): import("react").JSX.Element;
+type ActionBarEditProps = Omit<ActionBarItemProps, "children"> & {
+  value?: ActionBarCopyValue;
+  children?: ReactNode;
+};
+declare function ActionBarEdit({ value, children, disabled, onClick, ...props }: ActionBarEditProps): import("react").JSX.Element;
+//#endregion
+export { ActionBar, ActionBarContextValue, ActionBarCopy, ActionBarCopyProps, ActionBarCopyValue, ActionBarEdit, ActionBarEditProps, ActionBarItem, ActionBarItemProps, ActionBarProps };

package/dist/action-bar.js

@@ -0,0 +1,89 @@
+"use client";
+import { useCopyToClipboard } from "./hooks/use-copy-to-clipboard.js";
+import { cn } from "./lib/cn.js";
+import { Button } from "./ui/button.js";
+import { createContext, useContext } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/action-bar.tsx
+const ActionBarContext = createContext({});
+async function resolveCopyValue(value) {
+	return typeof value === "function" ? await value() : value;
+}
+function ActionBar({ label = "Message actions", align = "start", className, children, context, copyValue, editValue, onCopy, onCopyError, onEdit, onEditError, ...props }) {
+	const actionContext = {
+		...context,
+		copyValue: copyValue ?? context?.copyValue,
+		editValue: editValue ?? context?.editValue,
+		onCopy: onCopy ?? context?.onCopy,
+		onCopyError: onCopyError ?? context?.onCopyError,
+		onEdit: onEdit ?? context?.onEdit,
+		onEditError: onEditError ?? context?.onEditError
+	};
+	return /* @__PURE__ */ jsx(ActionBarContext.Provider, {
+		value: actionContext,
+		children: /* @__PURE__ */ jsx("div", {
+			"data-control-ui": "action-bar",
+			"data-control-family": "action-bar",
+			"data-slot": "root",
+			role: "toolbar",
+			"aria-label": label,
+			className: cn("flex items-center", align === "end" ? "justify-end" : "justify-start", className),
+			...props,
+			children
+		})
+	});
+}
+function ActionBarItem({ icon, children, className, ...props }) {
+	return /* @__PURE__ */ jsxs(Button, {
+		size: "xs",
+		className,
+		...props,
+		children: [icon, children]
+	});
+}
+function ActionBarCopy({ value, children = "Copy", copiedChildren = "Copied", resetDelay = 1200, disabled, onClick, ...props }) {
+	const { copyValue: contextCopyValue, onCopy, onCopyError } = useContext(ActionBarContext);
+	const copyValue = value ?? contextCopyValue;
+	const { isCopied, copyToClipboard } = useCopyToClipboard({
+		copiedDuration: resetDelay,
+		onCopy,
+		onCopyError
+	});
+	async function handleClick(event) {
+		onClick?.(event);
+		if (event.defaultPrevented) return;
+		const nextValue = await resolveCopyValue(copyValue);
+		if (!nextValue) return;
+		await copyToClipboard(nextValue);
+	}
+	return /* @__PURE__ */ jsx(ActionBarItem, {
+		"aria-live": "polite",
+		disabled: disabled ?? !copyValue,
+		onClick: handleClick,
+		...props,
+		children: isCopied ? copiedChildren : children
+	});
+}
+function ActionBarEdit({ value, children = "Edit", disabled, onClick, ...props }) {
+	const { copyValue, editValue: contextEditValue, onEdit, onEditError } = useContext(ActionBarContext);
+	const editValue = value ?? contextEditValue ?? copyValue;
+	async function handleClick(event) {
+		onClick?.(event);
+		if (event.defaultPrevented || !onEdit) return;
+		try {
+			const nextValue = await resolveCopyValue(editValue);
+			if (!nextValue) return;
+			onEdit(nextValue);
+		} catch (error) {
+			onEditError?.(error);
+		}
+	}
+	return /* @__PURE__ */ jsx(ActionBarItem, {
+		disabled: disabled ?? (!editValue || !onEdit),
+		onClick: handleClick,
+		...props,
+		children
+	});
+}
+//#endregion
+export { ActionBar, ActionBarCopy, ActionBarEdit, ActionBarItem };

package/dist/activity.d.ts

@@ -0,0 +1,53 @@
+import { ActivityKnobStyle } from "./knob-contracts/activity-knobs.js";
+import { CollapsibleContent, CollapsibleProps, CollapsibleTrigger } from "./ui/collapsible.js";
+import { ScrollAreaProps } from "./ui/scroll-area.js";
+import { CSSProperties, ComponentProps, ReactNode } from "react";
+import { ChevronRight } from "lucide-react";
+//#region src/activity.d.ts
+type ActivityState = "pending" | "running" | "success" | "error";
+type ActivityKind = "default" | "tool" | "reasoning" | "signal";
+type ActivityDetailFormat = "text" | "code";
+type ActivityProps = Omit<CollapsibleProps, "children" | "style"> & {
+  children?: ReactNode;
+  kind?: ActivityKind;
+  name?: string;
+  state?: ActivityState;
+  statusLabel?: ReactNode;
+  style?: CSSProperties & ActivityKnobStyle;
+};
+type ActivityStyleProps<Props, Style> = Omit<Props, "style"> & {
+  style?: CSSProperties & Style;
+};
+declare function Activity({ kind, name, state, statusLabel, className, children, ...props }: ActivityProps): import("react").JSX.Element;
+type ActivityRowProps = ActivityStyleProps<ComponentProps<"div">, ActivityKnobStyle>;
+declare function ActivityRow({ className, ...props }: ActivityRowProps): import("react").JSX.Element;
+type ActivityTriggerProps = ActivityStyleProps<ComponentProps<typeof CollapsibleTrigger>, ActivityKnobStyle> & {
+  chevronProps?: ActivityStyleProps<ComponentProps<typeof ChevronRight>, ActivityKnobStyle> & {
+    "data-slot"?: string;
+  };
+};
+declare function ActivityTrigger({ className, children, chevronProps, ...props }: ActivityTriggerProps): import("react").JSX.Element;
+type ActivityIconProps = ActivityStyleProps<ComponentProps<"span">, ActivityKnobStyle>;
+declare function ActivityIcon({ className, children, ...props }: ActivityIconProps): import("react").JSX.Element;
+type ActivityTitleProps = ActivityStyleProps<ComponentProps<"span">, ActivityKnobStyle>;
+declare function ActivityTitle({ className, children, ...props }: ActivityTitleProps): import("react").JSX.Element;
+type ActivityStatusProps = ActivityStyleProps<ComponentProps<"span">, ActivityKnobStyle>;
+declare function ActivityStatus({ className, children, ...props }: ActivityStatusProps): import("react").JSX.Element;
+type ActivityContentProps = Omit<ComponentProps<typeof CollapsibleContent>, "children"> & {
+  children?: ReactNode;
+  maxHeight?: string | false;
+  scrollAreaProps?: Omit<ScrollAreaProps, "children" | "maxHeight">;
+};
+declare function ActivityContent({ className, children, maxHeight, scrollAreaProps, ...props }: ActivityContentProps): import("react").JSX.Element;
+type ActivityDetailProps = ComponentProps<"div"> & {
+  style?: CSSProperties & ActivityKnobStyle;
+};
+declare function ActivityDetail({ className, ...props }: ActivityDetailProps): import("react").JSX.Element;
+type ActivityDetailLabelProps = ActivityStyleProps<ComponentProps<"div">, ActivityKnobStyle>;
+declare function ActivityDetailLabel({ className, ...props }: ActivityDetailLabelProps): import("react").JSX.Element;
+type ActivityDetailContentProps = ActivityStyleProps<ComponentProps<"div">, ActivityKnobStyle> & {
+  format?: ActivityDetailFormat;
+};
+declare function ActivityDetailContent({ format, className, ...props }: ActivityDetailContentProps): import("react").JSX.Element;
+//#endregion
+export { Activity, ActivityContent, ActivityContentProps, ActivityDetail, ActivityDetailContent, ActivityDetailContentProps, ActivityDetailFormat, ActivityDetailLabel, ActivityDetailLabelProps, ActivityDetailProps, ActivityIcon, ActivityIconProps, ActivityKind, ActivityProps, ActivityRow, ActivityRowProps, ActivityState, ActivityStatus, ActivityStatusProps, ActivityTitle, ActivityTitleProps, ActivityTrigger, ActivityTriggerProps };

package/dist/activity.js

@@ -0,0 +1,188 @@
+"use client";
+import { cn } from "./lib/cn.js";
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "./ui/collapsible.js";
+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";
+//#region src/activity.tsx
+const activityStatusLabels = {
+	pending: "Pending",
+	running: "Running",
+	success: "Complete",
+	error: "Failed"
+};
+const activityStatusIcons = {
+	pending: CircleDashed,
+	running: LoaderCircle,
+	success: Check,
+	error: CircleAlert
+};
+const ActivityContext = createContext(null);
+function useActivityContext() {
+	const context = useContext(ActivityContext);
+	if (!context) throw new Error("Activity compound components must be rendered inside <Activity>.");
+	return context;
+}
+function formatActivityTitle(value) {
+	const words = value.replace(/([a-z\d])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").trim();
+	return words ? `${words.charAt(0).toUpperCase()}${words.slice(1)}` : value;
+}
+function Activity({ kind = "default", name, state = "pending", statusLabel, className, children, ...props }) {
+	const context = {
+		isError: state === "error",
+		isRunning: state === "running",
+		kind,
+		name,
+		state,
+		statusLabel: statusLabel ?? activityStatusLabels[state]
+	};
+	return /* @__PURE__ */ jsx(ActivityContext.Provider, {
+		value: context,
+		children: /* @__PURE__ */ jsxs(Collapsible, {
+			"data-control-ui": "activity",
+			"data-control-family": "activity",
+			"data-slot": "root",
+			"data-activity-state": state,
+			"data-activity-kind": kind,
+			"data-activity-name": name,
+			"aria-busy": context.isRunning || void 0,
+			className: cn("group/activity min-w-0", className),
+			...props,
+			children: [/* @__PURE__ */ jsx("span", {
+				role: context.isError ? "alert" : "status",
+				"aria-live": context.isError ? "assertive" : "polite",
+				"aria-atomic": "true",
+				"data-control-ui": "activity",
+				"data-control-family": "activity",
+				"data-slot": "announcement",
+				"data-status": state,
+				className: "sr-only",
+				children: context.statusLabel
+			}), children]
+		})
+	});
+}
+const activityRowClassName = "flex w-fit max-w-full items-center";
+function ActivityRow({ className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-control-ui": "activity",
+		"data-control-family": "activity",
+		"data-slot": "row",
+		...props,
+		className: cn(activityRowClassName, className)
+	});
+}
+function ActivityTrigger({ className, children, chevronProps, ...props }) {
+	return /* @__PURE__ */ jsxs(CollapsibleTrigger, {
+		"data-control-ui": "activity",
+		"data-control-family": "activity",
+		"data-slot": "trigger",
+		...props,
+		className: cn(activityRowClassName, className),
+		children: [children, /* @__PURE__ */ jsx(ChevronRight, {
+			"aria-hidden": "true",
+			"data-control-ui": "activity",
+			"data-control-family": "activity",
+			"data-slot": "chevron",
+			...chevronProps,
+			className: cn("shrink-0", chevronProps?.className)
+		})]
+	});
+}
+function ActivityIcon({ className, children, ...props }) {
+	const activity = useActivityContext();
+	const Icon = activityStatusIcons[activity.state];
+	return /* @__PURE__ */ jsx("span", {
+		"aria-hidden": "true",
+		"data-control-ui": "activity",
+		"data-control-family": "activity",
+		"data-status-icon": children === void 0 ? "" : void 0,
+		"data-slot": "icon",
+		...props,
+		className: cn("flex shrink-0 items-center justify-center [&_svg]:size-4", className),
+		children: children ?? /* @__PURE__ */ jsx(Icon, {})
+	});
+}
+function ActivityTitle({ className, children, ...props }) {
+	const activity = useActivityContext();
+	return /* @__PURE__ */ jsx("span", {
+		"data-control-ui": "activity",
+		"data-control-family": "activity",
+		"data-slot": "title",
+		...props,
+		className: cn("min-w-0 flex-1 truncate", className),
+		children: children ?? (activity.name ? formatActivityTitle(activity.name) : void 0)
+	});
+}
+function ActivityStatus({ className, children, ...props }) {
+	const activity = useActivityContext();
+	return /* @__PURE__ */ jsx("span", {
+		"data-control-ui": "activity",
+		"data-control-family": "activity",
+		"data-slot": "status",
+		"data-kind": activity.kind,
+		...props,
+		"data-status": activity.state,
+		className: cn("shrink-0", className),
+		children: children ?? activity.statusLabel
+	});
+}
+function ActivityContent({ className, children, maxHeight = "var(--activity-content-max-height, min(24rem, 50dvh))", scrollAreaProps, ...props }) {
+	const { className: scrollAreaClassName, viewportProps, lockAxis = "x", ...resolvedScrollAreaProps } = scrollAreaProps ?? {};
+	const resolvedViewportProps = {
+		...viewportProps,
+		"data-control-ui": viewportProps?.["data-control-ui"] ?? "activity",
+		"data-slot": viewportProps?.["data-slot"] ?? "content-viewport"
+	};
+	return /* @__PURE__ */ jsx(CollapsibleContent, {
+		"data-control-ui": "activity",
+		"data-slot": "content",
+		className,
+		...props,
+		children: /* @__PURE__ */ jsx(ScrollArea, {
+			maxHeight: maxHeight || void 0,
+			lockAxis,
+			viewportProps: resolvedViewportProps,
+			className: cn("min-w-0", scrollAreaClassName),
+			...resolvedScrollAreaProps,
+			children: /* @__PURE__ */ jsx("div", {
+				"data-control-ui": "activity",
+				"data-control-family": "activity",
+				"data-slot": "content-grid",
+				className: "grid min-w-0",
+				children
+			})
+		})
+	});
+}
+function ActivityDetail({ className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-control-ui": "activity",
+		"data-control-family": "activity",
+		"data-slot": "detail",
+		...props,
+		className: cn("grid min-w-0", className)
+	});
+}
+function ActivityDetailLabel({ className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-control-ui": "activity",
+		"data-control-family": "activity",
+		"data-slot": "detail-label",
+		...props,
+		className: cn("uppercase", className)
+	});
+}
+function ActivityDetailContent({ format = "text", className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-control-ui": "activity",
+		"data-control-family": "activity",
+		"data-slot": "detail-content",
+		"data-format": format,
+		...props,
+		className: cn("min-w-0 whitespace-pre-wrap wrap-anywhere", format === "code" && "w-fit max-w-full", className)
+	});
+}
+//#endregion
+export { Activity, ActivityContent, ActivityDetail, ActivityDetailContent, ActivityDetailLabel, ActivityIcon, ActivityRow, ActivityStatus, ActivityTitle, ActivityTrigger };

package/dist/audio-recorder.d.ts

@@ -0,0 +1,32 @@
+import { ButtonKnobStyle } from "./knob-contracts/button-knobs.js";
+import { Button } from "./ui/button.js";
+import { AudioRecording, UseAudioRecorderOptions, UseAudioRecorderResult } from "./hooks/use-audio-recorder.js";
+import { AudioRecorderKnobStyle } from "./knob-contracts/audio-recorder-knobs.js";
+import { AudioVisualizerKnobStyle } from "./knob-contracts/audio-visualizer-knobs.js";
+import { CSSProperties, ComponentProps } from "react";
+//#region src/audio-recorder.d.ts
+type AudioRecorderStyleProps<Props, Style> = Omit<Props, "style"> & {
+  style?: CSSProperties & Style;
+};
+declare function useAudioRecorderContext(): UseAudioRecorderResult;
+type AudioRecorderProps = Omit<ComponentProps<"div">, "style"> & UseAudioRecorderOptions & {
+  label?: string;
+  style?: CSSProperties & AudioRecorderKnobStyle;
+};
+declare function AudioRecorder({ onRecordingComplete, onCancel, maxDurationMs, disabled, barCount, barDurationMs, deviceId, label, className, children, ...props }: AudioRecorderProps): import("react").JSX.Element;
+type AudioRecorderTriggerProps = AudioRecorderStyleProps<ComponentProps<typeof Button>, ButtonKnobStyle & AudioRecorderKnobStyle>;
+declare function AudioRecorderTrigger({ className, children, disabled, onClick, ...props }: AudioRecorderTriggerProps): import("react").JSX.Element;
+type AudioRecorderVisualizerProps = AudioRecorderStyleProps<Omit<ComponentProps<"div">, "children">, AudioVisualizerKnobStyle & AudioRecorderKnobStyle> & {
+  points?: number;
+};
+declare function AudioRecorderVisualizer({ points, className, ...props }: AudioRecorderVisualizerProps): import("react").JSX.Element;
+type AudioRecorderStatusProps = AudioRecorderStyleProps<ComponentProps<"span">, AudioRecorderKnobStyle>;
+declare function AudioRecorderStatus({ className, children, ...props }: AudioRecorderStatusProps): import("react").JSX.Element;
+type AudioRecorderDurationProps = AudioRecorderStyleProps<ComponentProps<"span">, AudioRecorderKnobStyle>;
+declare function AudioRecorderDuration({ className, children, ...props }: AudioRecorderDurationProps): import("react").JSX.Element;
+type AudioRecorderCancelProps = AudioRecorderStyleProps<ComponentProps<typeof Button>, ButtonKnobStyle & AudioRecorderKnobStyle>;
+declare function AudioRecorderCancel({ className, children, disabled, onClick, tabIndex, ...props }: AudioRecorderCancelProps): import("react").JSX.Element;
+type AudioRecorderSubmitProps = AudioRecorderStyleProps<ComponentProps<typeof Button>, ButtonKnobStyle & AudioRecorderKnobStyle>;
+declare function AudioRecorderSubmit({ className, children, disabled, onClick, tabIndex, ...props }: AudioRecorderSubmitProps): import("react").JSX.Element;
+//#endregion
+export { AudioRecorder, AudioRecorderCancel, AudioRecorderCancelProps, AudioRecorderDuration, AudioRecorderDurationProps, AudioRecorderProps, AudioRecorderStatus, AudioRecorderStatusProps, AudioRecorderSubmit, AudioRecorderSubmitProps, AudioRecorderTrigger, AudioRecorderTriggerProps, AudioRecorderVisualizer, AudioRecorderVisualizerProps, type AudioRecording, useAudioRecorderContext };