examples/web_ui/frontend/src/components/knowledge/KnowledgeDocumentsPanel.tsx

import { AlertCircle, CheckCircle2, FileText, Loader2, Plus, Trash2, X } from 'lucide-react';
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import { useTranslation } from 'react-i18next';
import { toast } from 'sonner';

import { knowledgeBaseApi } from '@/api';
import type { KnowledgeDocumentStatus, KnowledgeDocumentView } from '@/api';
import { DeleteDialog } from '@/components/dialog/DeleteDialog.tsx';
import { Button } from '@/components/ui/button.tsx';
import {
	Empty,
	EmptyContent,
	EmptyDescription,
	EmptyHeader,
	EmptyMedia,
	EmptyTitle,
} from '@/components/ui/empty.tsx';
import { useUploadContext } from '@/context/UploadContext';
import { isInFlight } from '@/context/uploadTypes';
import type { UploadPhase, UploadTask } from '@/context/uploadTypes';
import { useDocumentStatusPolling } from '@/hooks/useDocumentStatusPolling';
import { useKnowledgeDocuments } from '@/hooks/useKnowledgeDocuments';
import { useKnowledgeSupportedContentTypes } from '@/hooks/useKnowledgeSupportedContentTypes';
import { cn } from '@/lib/utils';

interface KnowledgeDocumentsPanelProps {
	knowledgeBaseId: string;
}

/**
 * A row that the panel renders. Either a server-side document (the
 * canonical record after upload returns) or a still-uploading local
 * task. Uploads that have already produced a `documentId` are routed
 * through the server row so the panel never double-renders one.
 */
type Row =
	| { kind: 'server'; doc: KnowledgeDocumentView; localTask: UploadTask | null }
	| { kind: 'local'; task: UploadTask };

const TERMINAL_SERVER_STATUSES: KnowledgeDocumentStatus[] = ['ready', 'error'];

function formatSize(bytes: number): string {
	if (!bytes) return '—';
	const units = ['B', 'KB', 'MB', 'GB'];
	let value = bytes;
	let i = 0;
	while (value >= 1024 && i < units.length - 1) {
		value /= 1024;
		i++;
	}
	return `${value.toFixed(value >= 100 || i === 0 ? 0 : 1)} ${units[i]}`;
}

function StatusBadge({ phase }: { phase: UploadPhase }) {
	const { t } = useTranslation();
	const label = t(`knowledge.document.status.${phase}`);
	const tone = (() => {
		switch (phase) {
			case 'ready':
				return 'bg-emerald-500/10 text-emerald-700 dark:text-emerald-400';
			case 'error':
				return 'bg-destructive/10 text-destructive';
			case 'cancelled':
				return 'bg-muted text-muted-foreground';
			case 'queued':
			case 'uploading':
			case 'pending':
			case 'parsing':
			case 'chunking':
			case 'indexing':
			default:
				return 'bg-primary/10 text-primary';
		}
	})();
	return (
		<span
			className={cn(
				'inline-flex items-center gap-x-1 rounded-md px-1.5 py-0.5 text-[10px] font-medium',
				tone,
			)}
		>
			{phase === 'ready' ? (
				<CheckCircle2 className="size-3" />
			) : phase === 'error' ? (
				<AlertCircle className="size-3" />
			) : phase === 'cancelled' ? null : (
				<Loader2 className="size-3 animate-spin" />
			)}
			{label}
		</span>
	);
}

interface RowViewProps {
	row: Row;
	onCancel: (taskId: string) => void;
	onDismiss: (taskId: string) => void;
	onDelete: (doc: KnowledgeDocumentView) => void;
}

function RowView({ row, onCancel, onDismiss, onDelete }: RowViewProps) {
	const { t } = useTranslation();

	const filename = row.kind === 'server' ? row.doc.filename : row.task.filename;
	const size = row.kind === 'server' ? row.doc.size : row.task.size;

	// Phase resolution — the local task wins while the server hasn't
	// caught up; once the server says `ready` / `error`, that's the
	// truth.
	const phase: UploadPhase = (() => {
		if (row.kind === 'local') return row.task.phase;
		const localPhase = row.localTask?.phase;
		if (
			localPhase &&
			!TERMINAL_SERVER_STATUSES.includes(row.doc.status as KnowledgeDocumentStatus)
		) {
			return localPhase;
		}
		return row.doc.status;
	})();

	// Progress bar logic: byte-level during `uploading`; otherwise a
	// coarse phase-derived value so the user gets visible movement.
	const { progressValue, indeterminate } = (() => {
		if (phase === 'uploading' && row.kind === 'local') {
			if (!row.task.size) return { progressValue: 0, indeterminate: true };
			return {
				progressValue: Math.min(100, Math.round((row.task.loaded / row.task.size) * 100)),
				indeterminate: false,
			};
		}
		switch (phase) {
			case 'queued':
				return { progressValue: 5, indeterminate: false };
			case 'pending':
				return { progressValue: 35, indeterminate: true };
			case 'parsing':
				return { progressValue: 55, indeterminate: true };
			case 'chunking':
				return { progressValue: 75, indeterminate: true };
			case 'indexing':
				return { progressValue: 90, indeterminate: true };
			case 'ready':
				return { progressValue: 100, indeterminate: false };
			default:
				return { progressValue: 0, indeterminate: false };
		}
	})();

	const error = row.kind === 'local' ? row.task.error : row.doc.error;
	const chunkCount = row.kind === 'server' ? row.doc.chunk_count : row.task.documentId ? 0 : 0;

	const taskIdForCancel =
		row.kind === 'local' ? row.task.taskId : (row.localTask?.taskId ?? null);

	const showProgress = phase !== 'ready' && phase !== 'cancelled';

	return (
		<div className="border-border bg-card flex flex-col gap-y-2 rounded-lg border p-3">
			<div className="flex items-start gap-x-3">
				<FileText className="text-muted-foreground mt-0.5 size-4 shrink-0" />
				<div className="flex min-w-0 flex-1 flex-col gap-y-0.5">
					<div className="flex items-center gap-x-2">
						<span className="truncate text-sm font-medium">{filename}</span>
						<StatusBadge phase={phase} />
					</div>
					<div className="text-muted-foreground flex items-center gap-x-2 text-xs">
						<span>{formatSize(size)}</span>
						{chunkCount > 0 && (
							<>
								<span>·</span>
								<span>
									{t('knowledge.document.chunkCount', {
										count: chunkCount,
									})}
								</span>
							</>
						)}
					</div>
				</div>
				<div className="flex shrink-0 items-center gap-x-1">
					{phase === 'queued' || phase === 'uploading' ? (
						<Button
							variant="ghost"
							size="icon-xs"
							onClick={() => taskIdForCancel && onCancel(taskIdForCancel)}
							aria-label={t('knowledge.document.actions.cancel')}
						>
							<X className="size-3.5" />
						</Button>
					) : phase === 'cancelled' || phase === 'error' ? (
						row.kind === 'local' ? (
							<Button
								variant="ghost"
								size="icon-xs"
								onClick={() => onDismiss(row.task.taskId)}
								aria-label={t('knowledge.document.actions.dismiss')}
							>
								<X className="size-3.5" />
							</Button>
						) : (
							<Button
								variant="ghost"
								size="icon-xs"
								onClick={() => onDelete(row.doc)}
								aria-label={t('knowledge.document.actions.remove')}
							>
								<Trash2 className="size-3.5" />
							</Button>
						)
					) : row.kind === 'server' ? (
						<Button
							variant="ghost"
							size="icon-xs"
							onClick={() => onDelete(row.doc)}
							aria-label={t('knowledge.document.actions.remove')}
						>
							<Trash2 className="size-3.5" />
						</Button>
					) : null}
				</div>
			</div>
			{showProgress && (
				<div className="bg-muted relative h-1 w-full overflow-hidden rounded-full">
					<div
						className={cn(
							'h-full rounded-full transition-all',
							phase === 'error' ? 'bg-destructive' : 'bg-primary',
							indeterminate && 'animate-pulse',
						)}
						style={{ width: `${progressValue}%` }}
					/>
				</div>
			)}
			{phase === 'error' && error && <p className="text-destructive text-xs">{error}</p>}
		</div>
	);
}

export function KnowledgeDocumentsPanel({ knowledgeBaseId }: KnowledgeDocumentsPanelProps) {
	const { t } = useTranslation();
	const fileInputRef = useRef<HTMLInputElement>(null);
	const [dragOver, setDragOver] = useState(false);
	const [deleteTarget, setDeleteTarget] = useState<KnowledgeDocumentView | null>(null);

	const { enqueue, cancel, dismiss, tasksForKb, clearFinishedForKb } = useUploadContext();
	const { documents, refetch } = useKnowledgeDocuments(knowledgeBaseId);
	const tasks = tasksForKb(knowledgeBaseId);
	const { statuses } = useDocumentStatusPolling({
		knowledgeBaseId,
		documents,
	});
	const { mediaTypes, extensions } = useKnowledgeSupportedContentTypes();

	// Lowercased extension set used to gate `handleFiles`. Built once
	// per render — the underlying list is shared across the app via a
	// module-level cache so this stays cheap.
	const extensionSet = useMemo(
		() => new Set(extensions.map((ext) => ext.toLowerCase())),
		[extensions],
	);
	// `<input accept>` takes a comma-separated string of MIME types and
	// `.ext` tokens. We hand it both because browsers diverge on which
	// they honour for any given filename — extensions filter the picker
	// dialog, MIME types catch programmatic drops.
	const acceptAttr = useMemo(
		() => [...extensions, ...mediaTypes].join(','),
		[extensions, mediaTypes],
	);

	// Refetch the canonical list whenever a polled doc reaches a
	// terminal state — this is the single hook that pulls in the worker's
	// final `chunk_count` and any updates to `error`.
	const terminalIdsKey = useMemo(() => {
		const ids: string[] = [];
		for (const id of Object.keys(statuses)) {
			const s = statuses[id];
			if (s.status === 'ready' || s.status === 'error') ids.push(id);
		}
		return ids.join(',');
	}, [statuses]);
	const lastRefetchedKey = useRef('');
	useEffect(() => {
		if (!terminalIdsKey) return;
		if (terminalIdsKey === lastRefetchedKey.current) return;
		lastRefetchedKey.current = terminalIdsKey;
		void refetch();
	}, [terminalIdsKey, refetch]);

	// Merge tasks + documents into a single ordered row list.
	const rows: Row[] = useMemo(() => {
		const tasksByDocId = new Map<string, UploadTask>();
		const tasksWithoutDoc: UploadTask[] = [];
		for (const task of tasks) {
			if (task.documentId) tasksByDocId.set(task.documentId, task);
			else tasksWithoutDoc.push(task);
		}
		const docRows: Row[] = documents.map((doc) => ({
			kind: 'server',
			doc,
			localTask: tasksByDocId.get(doc.id) ?? null,
		}));
		const localRows: Row[] = tasksWithoutDoc.map((task) => ({
			kind: 'local',
			task,
		}));
		// Local-only rows go first (they're either uploading or queued
		// — both are user-visible "I just hit upload" states).
		return [...localRows, ...docRows];
	}, [documents, tasks]);

	const onUploadClick = useCallback(() => {
		fileInputRef.current?.click();
	}, []);

	const handleFiles = useCallback(
		(files: FileList | File[]) => {
			const arr = Array.from(files);
			if (arr.length === 0) return;
			// When the capability list hasn't loaded yet, allow everything
			// through — the backend still rejects unsupported uploads.
			// Once we have the list, filter client-side by extension
			// (`file.type` is unreliable across browsers/OSes).
			const accepted: File[] = [];
			for (const f of arr) {
				if (extensionSet.size === 0) {
					accepted.push(f);
					continue;
				}
				const dot = f.name.lastIndexOf('.');
				const ext = dot >= 0 ? f.name.slice(dot).toLowerCase() : '';
				if (ext && extensionSet.has(ext)) {
					accepted.push(f);
				} else {
					toast.error(
						t('knowledge.document.unsupportedExtension', {
							name: f.name,
						}),
					);
				}
			}
			if (accepted.length === 0) return;
			enqueue(knowledgeBaseId, accepted);
		},
		[enqueue, knowledgeBaseId, extensionSet, t],
	);

	const onFileInputChange = useCallback(
		(e: React.ChangeEvent<HTMLInputElement>) => {
			if (e.target.files) handleFiles(e.target.files);
			// Reset so picking the same file twice re-fires the change.
			e.target.value = '';
		},
		[handleFiles],
	);

	const onDrop = useCallback(
		(e: React.DragEvent<HTMLDivElement>) => {
			e.preventDefault();
			setDragOver(false);
			if (e.dataTransfer.files) handleFiles(e.dataTransfer.files);
		},
		[handleFiles],
	);

	const onDragOver = useCallback((e: React.DragEvent<HTMLDivElement>) => {
		e.preventDefault();
		setDragOver(true);
	}, []);

	const onDragLeave = useCallback(() => setDragOver(false), []);

	const handleDelete = useCallback(async () => {
		if (!deleteTarget) return;
		try {
			await knowledgeBaseApi.deleteDocument(knowledgeBaseId, deleteTarget.id);
			await refetch();
		} catch {
			toast.error(t('knowledge.document.deleteError'));
		}
	}, [deleteTarget, knowledgeBaseId, refetch, t]);

	const hasFinishedLocalTasks = tasks.some((t) => !isInFlight(t.phase));

	const totalCount = rows.length;

	return (
		<div className="flex flex-col gap-y-4">
			<div className="flex items-center justify-between">
				<h3 className="text-sm font-semibold">
					{t('knowledge.document.countLabel', { count: totalCount })}
				</h3>
				<div className="flex items-center gap-x-2">
					{hasFinishedLocalTasks && (
						<Button
							variant="ghost"
							size="sm"
							onClick={() => clearFinishedForKb(knowledgeBaseId)}
						>
							{t('knowledge.document.actions.clearFinished')}
						</Button>
					)}
					<Button variant="outline" size="sm" onClick={onUploadClick}>
						<Plus className="size-3.5" />
						{t('knowledge.document.uploadButtonShort')}
					</Button>
				</div>
			</div>

			<input
				ref={fileInputRef}
				type="file"
				multiple
				accept={acceptAttr || undefined}
				className="hidden"
				onChange={onFileInputChange}
			/>

			<div
				onDrop={onDrop}
				onDragOver={onDragOver}
				onDragLeave={onDragLeave}
				className={cn(
					'rounded-lg border border-dashed transition-colors',
					dragOver ? 'border-primary bg-primary/5' : 'border-border bg-transparent',
				)}
			>
				{rows.length === 0 ? (
					<Empty className="border-none py-6">
						<EmptyHeader>
							<EmptyMedia variant="icon">
								<FileText />
							</EmptyMedia>
							<EmptyTitle>{t('knowledge.document.emptyTitle')}</EmptyTitle>
							<EmptyDescription>
								{t('knowledge.document.emptyDescription')}
							</EmptyDescription>
						</EmptyHeader>
						<EmptyContent>
							<Button variant="outline" size="sm" onClick={onUploadClick}>
								<Plus className="size-3.5" />
								{t('knowledge.document.uploadButton')}
							</Button>
							<p className="text-muted-foreground mt-2 text-xs">
								{t('knowledge.document.dropHintIdle')}
							</p>
						</EmptyContent>
					</Empty>
				) : (
					<div className="flex flex-col gap-y-2 p-2">
						{rows.map((row) => (
							<RowView
								key={
									row.kind === 'server'
										? `srv-${row.doc.id}`
										: `tsk-${row.task.taskId}`
								}
								row={row}
								onCancel={cancel}
								onDismiss={dismiss}
								onDelete={setDeleteTarget}
							/>
						))}
					</div>
				)}
			</div>

			<DeleteDialog
				open={deleteTarget !== null}
				onOpenChange={(open) => {
					if (!open) setDeleteTarget(null);
				}}
				title={t('knowledge.document.deleteConfirmTitle')}
				description={t('knowledge.document.deleteConfirmDescription', {
					name: deleteTarget?.filename ?? '',
				})}
				onConfirm={handleDelete}
			/>
		</div>
	);
}