@4djs/assistant 0.0.0

package/src/react/components/chat/SystemPromptField.tsx

@@ -0,0 +1,107 @@
+import { Eye, Pencil, RotateCcw } from "lucide-react";
+import { useState } from "react";
+import { MarkdownContent } from "../MarkdownContent.tsx";
+import { MarkdownEditor } from "../MarkdownEditor.tsx";
+
+type SystemPromptMode = "edit" | "preview";
+
+interface SystemPromptFieldProps {
+	value: string;
+	defaultPrompt: string;
+	onChange: (value: string) => void;
+	onReset?: () => void;
+	disabled?: boolean;
+}
+
+export function SystemPromptField({
+	value,
+	defaultPrompt,
+	onChange,
+	onReset,
+	disabled = false,
+}: SystemPromptFieldProps) {
+	const [mode, setMode] = useState<SystemPromptMode>("preview");
+	const usingDefault = !value.trim() || value.trim() === defaultPrompt.trim();
+	const previewContent = usingDefault ? defaultPrompt : value;
+
+	return (
+		<div className="assistant-system-prompt">
+			<div className="assistant-system-prompt__shell">
+				<div className="assistant-system-prompt__bar">
+					<div className="assistant-system-prompt__bar-start">
+						<span className="assistant-system-prompt__label">
+							System prompt
+						</span>
+						{usingDefault ? (
+							<span className="assistant-system-prompt__tag">Default</span>
+						) : null}
+					</div>
+					<div
+						className="assistant-system-prompt__modes"
+						role="tablist"
+						aria-label="System prompt view"
+					>
+						{!usingDefault && onReset ? (
+							<button
+								type="button"
+								className="assistant-system-prompt__mode"
+								onClick={onReset}
+								disabled={disabled}
+								aria-label="Reset system prompt"
+								title="Reset to default"
+							>
+								<RotateCcw size={12} aria-hidden />
+							</button>
+						) : null}
+						<button
+							type="button"
+							className={`assistant-system-prompt__mode ${mode === "edit" ? "assistant-system-prompt__mode--active" : ""}`.trim()}
+							role="tab"
+							aria-selected={mode === "edit"}
+							aria-label="Edit"
+							title="Edit"
+							onClick={() => setMode("edit")}
+						>
+							<Pencil size={12} aria-hidden />
+						</button>
+						<button
+							type="button"
+							className={`assistant-system-prompt__mode ${mode === "preview" ? "assistant-system-prompt__mode--active" : ""}`.trim()}
+							role="tab"
+							aria-selected={mode === "preview"}
+							aria-label="Preview"
+							title="Preview"
+							onClick={() => setMode("preview")}
+						>
+							<Eye size={12} aria-hidden />
+						</button>
+					</div>
+				</div>
+
+				{mode === "edit" ? (
+					<div role="tabpanel">
+						<MarkdownEditor
+							className="assistant-system-prompt__editor"
+							value={value}
+							onChange={onChange}
+							placeholder="Optional — replaces app default"
+							disabled={disabled}
+							aria-label="System prompt editor"
+						/>
+					</div>
+				) : (
+					<div
+						className="assistant-system-prompt__doc"
+						role="tabpanel"
+						aria-label="System prompt preview"
+					>
+						<MarkdownContent
+							content={previewContent}
+							className="assistant-system-prompt__md"
+						/>
+					</div>
+				)}
+			</div>
+		</div>
+	);
+}

package/src/react/components/highlighted-code.tsx

@@ -0,0 +1,107 @@
+import {
+	type ComponentPropsWithoutRef,
+	createElement,
+	type ReactNode,
+	useMemo,
+} from "react";
+import { highlightCode } from "../../core/code-highlight.ts";
+import { cn } from "../utils/cn.ts";
+
+const HIGHLIGHT_HTML_PATTERN = /<span class="(hljs-[^"]+)">|<\/span>|([^<]+)/g;
+
+type HighlightPart =
+	| { type: "open"; className: string }
+	| { type: "close" }
+	| { type: "text"; value: string };
+
+function decodeHighlightEntities(text: string): string {
+	return text
+		.replace(/&quot;/g, '"')
+		.replace(/&amp;/g, "&")
+		.replace(/&lt;/g, "<")
+		.replace(/&gt;/g, ">");
+}
+
+function tokenizeHighlightHtml(html: string): HighlightPart[] {
+	const parts: HighlightPart[] = [];
+
+	for (const match of html.matchAll(HIGHLIGHT_HTML_PATTERN)) {
+		if (match[1]) {
+			parts.push({ type: "open", className: match[1] });
+			continue;
+		}
+
+		if (match[0] === "</span>") {
+			parts.push({ type: "close" });
+			continue;
+		}
+
+		if (match[2]) {
+			parts.push({ type: "text", value: decodeHighlightEntities(match[2]) });
+		}
+	}
+
+	return parts;
+}
+
+export function highlightNodes(
+	code: string,
+	language: string | null,
+): ReactNode[] {
+	const html = highlightCode(code, language);
+	const parts = tokenizeHighlightHtml(html);
+	const nodes: ReactNode[] = [];
+	const stack: { className: string; children: ReactNode[] }[] = [];
+	let key = 0;
+
+	for (const part of parts) {
+		if (part.type === "text") {
+			const target = stack.at(-1)?.children ?? nodes;
+			target.push(part.value);
+			continue;
+		}
+
+		if (part.type === "open") {
+			stack.push({ className: part.className, children: [] });
+			continue;
+		}
+
+		const span = stack.pop();
+		if (!span) continue;
+
+		const element = createElement(
+			"span",
+			{ key: key++, className: span.className },
+			...span.children,
+		);
+		const target = stack.at(-1)?.children ?? nodes;
+		target.push(element);
+	}
+
+	return nodes;
+}
+
+export function HighlightedCodeBlock({
+	className,
+	code,
+	language = "json",
+	...props
+}: {
+	className?: string;
+	code: string;
+	language?: string | null;
+} & ComponentPropsWithoutRef<"code">) {
+	const children = useMemo(
+		() => highlightNodes(code, language),
+		[code, language],
+	);
+
+	return (
+		<code
+			className={cn("hljs font-mono text-[11px] leading-snug", className)}
+			{...props}
+		>
+			{children}
+		</code>
+	);
+}

package/src/react/context.tsx

@@ -0,0 +1,72 @@
+import {
+	createContext,
+	type ReactNode,
+	useContext,
+	useEffect,
+	useMemo,
+	useRef,
+} from "react";
+import { createAssistantStore } from "../core/create-assistant-store.ts";
+import type { AssistantContextValue, AssistantProviderProps } from "./types.ts";
+
+const AssistantContext = createContext<AssistantContextValue | null>(null);
+
+export function AssistantProvider({
+	config,
+	children,
+}: AssistantProviderProps) {
+	const storeRef = useRef<ReturnType<typeof createAssistantStore> | null>(null);
+	if (!storeRef.current) {
+		storeRef.current = createAssistantStore(config);
+	}
+
+	const value = useMemo(
+		(): AssistantContextValue => ({
+			store: storeRef.current as ReturnType<typeof createAssistantStore>,
+			config,
+		}),
+		[config],
+	);
+
+	return (
+		<AssistantContext.Provider value={value}>
+			{children}
+		</AssistantContext.Provider>
+	);
+}
+
+export function useAssistantContext(): AssistantContextValue {
+	const context = useContext(AssistantContext);
+	if (!context) {
+		throw new Error(
+			"useAssistantContext must be used within AssistantProvider",
+		);
+	}
+	return context;
+}
+
+export function useAssistant<T>(
+	selector: (
+		state: ReturnType<ReturnType<typeof createAssistantStore>["getState"]>,
+	) => T,
+): T {
+	const { store } = useAssistantContext();
+	return store(selector);
+}
+
+export function useAssistantActions() {
+	const { store } = useAssistantContext();
+	return store.getState();
+}
+
+export function AssistantBootstrap({ children }: { children: ReactNode }) {
+	const { store, config } = useAssistantContext();
+	const autoLoad = config.autoLoadLlmStatus !== false;
+
+	useEffect(() => {
+		if (!autoLoad) return;
+		void store.getState().loadLlmStatus();
+	}, [autoLoad, store]);
+
+	return children;
+}

package/src/react/hooks/use-composer-commands.ts

@@ -0,0 +1,129 @@
+import { type KeyboardEvent, useEffect, useMemo, useState } from "react";
+import {
+	type ChatCommandSuggestion,
+	type ChatCommandSurface,
+	completionForChatCommand,
+	filterChatCommands,
+	parseChatCommand,
+	shouldShowChatCommandMenu,
+} from "../../core/chat-commands.ts";
+
+type UseComposerCommandsOptions = {
+	value: string;
+	onChange: (value: string) => void;
+	surface: ChatCommandSurface;
+	onExecute: (commandText: string) => void | Promise<void>;
+	disabled?: boolean;
+};
+
+export function useComposerCommands({
+	value,
+	onChange,
+	surface,
+	onExecute,
+	disabled = false,
+}: UseComposerCommandsOptions) {
+	const suggestions = useMemo(
+		() => filterChatCommands(value, surface),
+		[value, surface],
+	);
+	const menuOpen = !disabled && shouldShowChatCommandMenu(value, surface);
+	const [selectedIndex, setSelectedIndex] = useState(0);
+
+	const handleInputChange = (next: string) => {
+		setSelectedIndex(0);
+		onChange(next);
+	};
+
+	useEffect(() => {
+		if (selectedIndex >= suggestions.length) {
+			setSelectedIndex(0);
+		}
+	}, [selectedIndex, suggestions.length]);
+
+	function completeCommand(command: ChatCommandSuggestion) {
+		onChange(completionForChatCommand(command));
+	}
+
+	async function tryExecuteCommand(): Promise<boolean> {
+		const parsed = parseChatCommand(value);
+		if (!parsed) {
+			return false;
+		}
+
+		const command = suggestions.find((entry) => entry.name === parsed.name);
+		if (!command) {
+			return false;
+		}
+
+		onChange("");
+		await onExecute(command.usage);
+		return true;
+	}
+
+	function handleKeyDown(event: KeyboardEvent<HTMLTextAreaElement>): boolean {
+		if (menuOpen && suggestions.length > 0) {
+			if (event.key === "ArrowDown") {
+				event.preventDefault();
+				setSelectedIndex((current) => (current + 1) % suggestions.length);
+				return true;
+			}
+
+			if (event.key === "ArrowUp") {
+				event.preventDefault();
+				setSelectedIndex(
+					(current) => (current - 1 + suggestions.length) % suggestions.length,
+				);
+				return true;
+			}
+
+			if (event.key === "Tab") {
+				event.preventDefault();
+				const command = suggestions[selectedIndex] ?? suggestions[0];
+				if (command) {
+					completeCommand(command);
+				}
+				return true;
+			}
+
+			if (event.key === "Enter" && !event.shiftKey) {
+				event.preventDefault();
+				const command = suggestions[selectedIndex] ?? suggestions[0];
+				if (!command) {
+					return true;
+				}
+
+				const parsed = parseChatCommand(value);
+				if (parsed && suggestions.some((entry) => entry.name === parsed.name)) {
+					void tryExecuteCommand();
+				} else {
+					onChange("");
+					void onExecute(command.usage);
+				}
+				return true;
+			}
+		}
+
+		if (event.key === "Enter" && !event.shiftKey) {
+			const parsed = parseChatCommand(value);
+			if (parsed) {
+				event.preventDefault();
+				void tryExecuteCommand();
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+	return {
+		suggestions,
+		menuOpen,
+		selectedIndex,
+		setSelectedIndex,
+		handleInputChange,
+		completeCommand,
+		tryExecuteCommand,
+		handleKeyDown,
+	};
+}

package/src/react/hooks/use-suggested-prompts.ts

@@ -0,0 +1,128 @@
+import { useCallback, useEffect, useState } from "react";
+import type { AssistantToolDefinition } from "../../core/types.ts";
+import { resolvePromptIcon } from "../lib/prompt-icons.ts";
+import type { AssistantSuggestedPromptWithIcon } from "../types.ts";
+
+function withIcons(
+	prompts: Array<{
+		id: string;
+		label: string;
+		description?: string;
+		prompt: string;
+		icon?: string;
+	}>,
+): AssistantSuggestedPromptWithIcon[] {
+	return prompts.map((entry) => ({
+		id: entry.id,
+		label: entry.label,
+		hint: entry.description,
+		prompt: entry.prompt,
+		icon: resolvePromptIcon(entry.icon),
+	}));
+}
+
+export function useSuggestedPrompts(input: {
+	staticPrompts?: AssistantSuggestedPromptWithIcon[];
+	llmEnabled: boolean;
+	model: string | null;
+	enabled: boolean;
+	dynamicSuggestedPrompts?: boolean;
+	listTools: () => Promise<AssistantToolDefinition[]>;
+	fetchSuggestedPrompts?: (ctx: {
+		llmEnabled: boolean;
+		model: string | null;
+		tools: AssistantToolDefinition[];
+	}) => Promise<
+		Array<{
+			id: string;
+			label: string;
+			description?: string;
+			prompt: string;
+			icon?: string;
+		}>
+	>;
+}) {
+	const {
+		staticPrompts,
+		llmEnabled,
+		model,
+		enabled,
+		dynamicSuggestedPrompts,
+		listTools,
+		fetchSuggestedPrompts,
+	} = input;
+
+	const useDynamic =
+		dynamicSuggestedPrompts !== false &&
+		llmEnabled &&
+		enabled &&
+		Boolean(fetchSuggestedPrompts);
+
+	const [prompts, setPrompts] = useState<AssistantSuggestedPromptWithIcon[]>(
+		useDynamic ? [] : (staticPrompts ?? []),
+	);
+	const [loading, setLoading] = useState(false);
+	const [error, setError] = useState<string | null>(null);
+	const [hasFetched, setHasFetched] = useState(false);
+
+	useEffect(() => {
+		if (useDynamic) {
+			setPrompts([]);
+			setHasFetched(false);
+			setError(null);
+			setLoading(false);
+			return;
+		}
+
+		setPrompts(staticPrompts ?? []);
+		setHasFetched(false);
+		setError(null);
+		setLoading(false);
+	}, [useDynamic, staticPrompts]);
+
+	const refresh = useCallback(async () => {
+		if (!useDynamic || !fetchSuggestedPrompts) {
+			return;
+		}
+
+		setLoading(true);
+		setError(null);
+
+		try {
+			const tools = await listTools();
+			const fetched = await fetchSuggestedPrompts({
+				llmEnabled,
+				model,
+				tools,
+			});
+
+			if (fetched.length > 0) {
+				setPrompts(withIcons(fetched));
+			} else if (staticPrompts?.length) {
+				setPrompts(staticPrompts);
+			} else {
+				setPrompts([]);
+			}
+			setHasFetched(true);
+		} catch (loadError) {
+			setError(
+				loadError instanceof Error
+					? loadError.message
+					: "Failed to load suggestions",
+			);
+			setPrompts(staticPrompts ?? []);
+			setHasFetched(true);
+		} finally {
+			setLoading(false);
+		}
+	}, [
+		useDynamic,
+		fetchSuggestedPrompts,
+		listTools,
+		llmEnabled,
+		model,
+		staticPrompts,
+	]);
+
+	return { prompts, loading, error, useDynamic, refresh, hasFetched };
+}

package/src/react/index.ts

@@ -0,0 +1,39 @@
+export type {
+	AssistantMessage,
+	AssistantStoreDependencies,
+	AssistantToolDefinition,
+	AssistantToolResult,
+} from "../core/types.ts";
+export {
+	Assistant,
+	AssistantRoot,
+} from "./Assistant.tsx";
+export { ChatActivity } from "./components/chat/ChatActivity.tsx";
+export { ChatComposer } from "./components/chat/ChatComposer.tsx";
+export { ChatEmptyState } from "./components/chat/ChatEmptyState.tsx";
+export { ChatInteractivePrompt } from "./components/chat/ChatInteractivePrompt/index.tsx";
+export { ChatMessageView } from "./components/chat/ChatMessage.tsx";
+export { ChatMessageScroll } from "./components/chat/ChatMessageScroll.tsx";
+export { ChatReplySuggestions } from "./components/chat/ChatReplySuggestions.tsx";
+export { LlmSettingsStrip } from "./components/chat/LlmSettingsStrip.tsx";
+export { MarkdownContent } from "./components/MarkdownContent.tsx";
+export { MermaidDiagram } from "./components/MermaidDiagram.tsx";
+export { ModelSelector } from "./components/ModelSelector.tsx";
+export {
+	AssistantBootstrap,
+	AssistantProvider,
+	useAssistant,
+	useAssistantActions,
+	useAssistantContext,
+} from "./context.tsx";
+export { useComposerCommands } from "./hooks/use-composer-commands.ts";
+export type {
+	AssistantConfig,
+	AssistantContextValue,
+	AssistantEmptyStateConfig,
+	AssistantHeaderConfig,
+	AssistantProps,
+	AssistantProviderProps,
+	AssistantSuggestedPromptWithIcon,
+	AssistantUiConfig,
+} from "./types.ts";

package/src/react/lib/parse-assistant-error.ts

@@ -0,0 +1,96 @@
+export type AssistantErrorKind =
+	| "network"
+	| "auth"
+	| "timeout"
+	| "rate-limit"
+	| "unknown";
+
+export type ParsedAssistantError = {
+	title: string;
+	detail: string;
+	hint?: string;
+	kind: AssistantErrorKind;
+};
+
+function stripKnownPrefix(message: string): string {
+	const chatPrefix = "Chat failed: ";
+	if (message.startsWith(chatPrefix)) {
+		return message.slice(chatPrefix.length).trim();
+	}
+	return message.trim();
+}
+
+export function parseAssistantError(
+	raw: string,
+	context: "chat" | "suggestions" = "chat",
+): ParsedAssistantError {
+	const detail = stripKnownPrefix(raw);
+	const lower = detail.toLowerCase();
+
+	if (
+		lower.includes("failed to fetch") ||
+		lower.includes("networkerror") ||
+		lower.includes("network error") ||
+		lower.includes("load failed") ||
+		lower.includes("connection refused") ||
+		lower.includes("econnrefused")
+	) {
+		return {
+			title: "Connection lost",
+			detail,
+			hint:
+				context === "chat"
+					? "Check your network or LLM endpoint, then try again."
+					: "Check your connection and LLM settings.",
+			kind: "network",
+		};
+	}
+
+	if (
+		lower.includes("unauthorized") ||
+		lower.includes("401") ||
+		lower.includes("invalid api key") ||
+		lower.includes("authentication") ||
+		lower.includes("permission denied")
+	) {
+		return {
+			title: "Authentication failed",
+			detail,
+			hint: "Verify your API key or credentials in LLM settings.",
+			kind: "auth",
+		};
+	}
+
+	if (lower.includes("timeout") || lower.includes("timed out")) {
+		return {
+			title: "Request timed out",
+			detail,
+			hint: "The model took too long to respond. Try again in a moment.",
+			kind: "timeout",
+		};
+	}
+
+	if (
+		lower.includes("rate limit") ||
+		lower.includes("429") ||
+		lower.includes("too many requests")
+	) {
+		return {
+			title: "Rate limit reached",
+			detail,
+			hint: "Wait a few seconds before sending another request.",
+			kind: "rate-limit",
+		};
+	}
+
+	return {
+		title:
+			context === "chat" ? "Something went wrong" : "Couldn't load suggestions",
+		detail,
+		hint:
+			context === "chat"
+				? "Try again, or review your LLM settings."
+				: "Try regenerating, or check your LLM configuration.",
+		kind: "unknown",
+	};
+}