📝 Add docstrings to main

Docstrings generation was requested by @Rajdave69.

* https://github.com/nicotsx/zerobyte/pull/142#issuecomment-3655717762

The following files were modified:

* `app/client/modules/backups/components/sortable-backup-card.tsx`
* `app/client/modules/backups/routes/backups.tsx`

app/client/modules/backups/components/sortable-backup-card.tsx

@@ -0,0 +1,89 @@
+import { useSortable } from "@dnd-kit/sortable";
+import { CSS } from "@dnd-kit/utilities";
+import { CalendarClock, Database, GripVertical, HardDrive } from "lucide-react";
+import { Link } from "react-router";
+import { BackupStatusDot } from "./backup-status-dot";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "~/client/components/ui/card";
+import type { ListBackupSchedulesResponse } from "~/client/api-client";
+
+type Schedule = ListBackupSchedulesResponse[number];
+
+interface SortableBackupCardProps {
+	schedule: Schedule;
+	isDragging?: boolean;
+}
+
+/**
+ * Render a draggable backup schedule card that displays name, status, volume/repository and schedule metadata.
+ *
+ * @param schedule - The backup schedule object to display (name, id, cronExpression, timestamps, volume and repository info, enabled/status fields).
+ * @param isDragging - Optional flag indicating the card is currently being dragged; used to adjust visual appearance.
+ * @returns The JSX element for the sortable backup schedule card.
+ */
+export function SortableBackupCard({ schedule, isDragging }: SortableBackupCardProps) {
+	const { attributes, listeners, setNodeRef, transform, transition } = useSortable({
+		id: schedule.id,
+	});
+
+	const style = {
+		transform: CSS.Transform.toString(transform),
+		transition,
+		opacity: isDragging ? 0.5 : 1,
+	};
+
+	return (
+		<div ref={setNodeRef} style={style} className="relative group">
+			<div
+				{...attributes}
+				{...listeners}
+				className="absolute left-1/2 -translate-x-1/2 top-1 z-10 cursor-grab active:cursor-grabbing opacity-0 group-hover:opacity-100 transition-opacity p-1 rounded hover:bg-muted/50 bg-background/80 backdrop-blur-sm"
+			>
+				<GripVertical className="h-4 w-4 text-muted-foreground rotate-90" />
+			</div>
+			<Link to={`/backups/${schedule.id}`} className="block">
+				<Card className="flex flex-col h-full hover:bg-muted/30 transition-colors">
+					<CardHeader className="pb-3 overflow-hidden">
+						<div className="flex items-center justify-between gap-2 w-full">
+							<div className="flex items-center gap-2 flex-1 min-w-0 w-0">
+								<CalendarClock className="h-5 w-5 text-muted-foreground shrink-0" />
+								<CardTitle className="text-lg truncate">{schedule.name}</CardTitle>
+							</div>
+							<BackupStatusDot
+								enabled={schedule.enabled}
+								hasError={!!schedule.lastBackupError}
+								isInProgress={schedule.lastBackupStatus === "in_progress"}
+							/>
+						</div>
+						<CardDescription className="ml-0.5 flex items-center gap-2 text-xs">
+							<HardDrive className="h-3.5 w-3.5" />
+							<span className="truncate">{schedule.volume.name}</span>
+							<span className="text-muted-foreground">→</span>
+							<Database className="h-3.5 w-3.5 text-strong-accent" />
+							<span className="truncate text-strong-accent">{schedule.repository.name}</span>
+						</CardDescription>
+					</CardHeader>
+					<CardContent className="flex-1 space-y-4">
+						<div className="space-y-2">
+							<div className="flex items-center justify-between text-sm">
+								<span className="text-muted-foreground">Schedule</span>
+								<code className="text-xs bg-muted px-2 py-1 rounded">{schedule.cronExpression}</code>
+							</div>
+							<div className="flex items-center justify-between text-sm">
+								<span className="text-muted-foreground">Last backup</span>
+								<span className="font-medium">
+									{schedule.lastBackupAt ? new Date(schedule.lastBackupAt).toLocaleDateString() : "Never"}
+								</span>
+							</div>
+							<div className="flex items-center justify-between text-sm">
+								<span className="text-muted-foreground">Next backup</span>
+								<span className="font-medium">
+									{schedule.nextBackupAt ? new Date(schedule.nextBackupAt).toLocaleDateString() : "N/A"}
+								</span>
+							</div>
+						</div>
+					</CardContent>
+				</Card>
+			</Link>
+		</div>
+	);
+}

app/client/modules/backups/routes/backups.tsx

@@ -1,13 +1,46 @@
-import { useQuery } from "@tanstack/react-query";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import {
+	DndContext,
+	closestCenter,
+	KeyboardSensor,
+	PointerSensor,
+	useSensor,
+	useSensors,
+	type DragEndEvent,
+} from "@dnd-kit/core";
+import { arrayMove, SortableContext, sortableKeyboardCoordinates, rectSortingStrategy } from "@dnd-kit/sortable";
 import { CalendarClock, Database, HardDrive, Plus } from "lucide-react";
 import { Link } from "react-router";
+import { useState, useEffect } from "react";
+import { SortableBackupCard } from "../components/sortable-backup-card";
 import { BackupStatusDot } from "../components/backup-status-dot";
 import { EmptyState } from "~/client/components/empty-state";
 import { Button } from "~/client/components/ui/button";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "~/client/components/ui/card";
 import type { Route } from "./+types/backups";
 import { listBackupSchedules } from "~/client/api-client";
-import { listBackupSchedulesOptions } from "~/client/api-client/@tanstack/react-query.gen";
+import { listBackupSchedulesOptions, listBackupSchedulesQueryKey } from "~/client/api-client/@tanstack/react-query.gen";
+
+/**
+ * Send a new ordering of backup schedule IDs to the server.
+ *
+ * @param scheduleIds - Array of schedule IDs in the desired order (first element becomes first).
+ * @returns The parsed JSON response from the server.
+ * @throws Error if the server responds with a non-OK status.
+ */
+async function reorderBackupSchedules(scheduleIds: number[]) {
+	const response = await fetch("/api/v1/backups/reorder", {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+		},
+		body: JSON.stringify({ scheduleIds }),
+	});
+	if (!response.ok) {
+		throw new Error("Failed to reorder backup schedules");
+	}
+	return response.json();
+}
 
 export const handle = {
 	breadcrumb: () => [{ label: "Backups" }],
@@ -29,12 +62,71 @@ export const clientLoader = async () => {
 	return [];
 };
 
+/**
+ * Renders the Backups page with a draggable, re-orderable grid of backup schedule cards and a tile to create a new backup job.
+ *
+ * The component fetches backup schedules (using `loaderData` as initial data), keeps a local order state synchronized with fetched schedules, and persists reorder operations to the server. While loading it shows a loading message, and when there are no schedules it shows an empty state with a create button.
+ *
+ * @param loaderData - Initial list of backup schedules provided by the route loader; used as the query's initial data and to initialize the local item order
+ * @returns The page UI for listing and reordering backup schedules
+ */
 export default function Backups({ loaderData }: Route.ComponentProps) {
+	const queryClient = useQueryClient();
 	const { data: schedules, isLoading } = useQuery({
 		...listBackupSchedulesOptions(),
 		initialData: loaderData,
 	});
 
+	const [items, setItems] = useState(schedules?.map((s) => s.id) ?? []);
+
+	// Keep items in sync with schedules
+	useEffect(() => {
+		if (schedules) {
+			setItems(schedules.map((s) => s.id));
+		}
+	}, [schedules]);
+
+	const sensors = useSensors(
+		useSensor(PointerSensor, {
+			activationConstraint: {
+				distance: 8,
+			},
+		}),
+		useSensor(KeyboardSensor, {
+			coordinateGetter: sortableKeyboardCoordinates,
+		}),
+	);
+
+	const reorderMutation = useMutation({
+		mutationFn: async (scheduleIds: number[]) => {
+			await reorderBackupSchedules(scheduleIds);
+		},
+		onSuccess: () => {
+			queryClient.invalidateQueries({ queryKey: listBackupSchedulesQueryKey() });
+		},
+		onError: () => {
+			// Revert the order or display error to user
+			queryClient.invalidateQueries({ queryKey: listBackupSchedulesQueryKey() });
+		},
+	});
+
+	const handleDragEnd = (event: DragEndEvent) => {
+		const { active, over } = event;
+
+		if (over && active.id !== over.id) {
+			setItems((items) => {
+				const oldIndex = items.indexOf(active.id as number);
+				const newIndex = items.indexOf(over.id as number);
+				const newItems = arrayMove(items, oldIndex, newIndex);
+
+				// Save the new order
+				reorderMutation.mutate(newItems);
+
+				return newItems;
+			});
+		}
+	};
+
 	if (isLoading) {
 		return (
 			<div className="flex items-center justify-center h-full">
@@ -61,64 +153,30 @@ export default function Backups({ loaderData }: Route.ComponentProps) {
 		);
 	}
 
+	// Create a map for quick lookup
+	const scheduleMap = new Map(schedules.map((s) => [s.id, s]));
+
 	return (
 		<div className="container mx-auto space-y-6">
-			<div className="grid gap-4 md:grid-cols-2 lg:grid-cols-3 auto-rows-fr">
+			<DndContext sensors={sensors} collisionDetection={closestCenter} onDragEnd={handleDragEnd}>
-				{schedules.map((schedule) => (
+				<SortableContext items={items} strategy={rectSortingStrategy}>
-					<Link key={schedule.id} to={`/backups/${schedule.id}`}>
+					<div className="grid gap-4 md:grid-cols-2 lg:grid-cols-3 auto-rows-fr">
-						<Card key={schedule.id} className="flex flex-col h-full">
+						{items.map((id) => {
-							<CardHeader className="pb-3 overflow-hidden">
+							const schedule = scheduleMap.get(id);
-								<div className="flex items-center justify-between gap-2 w-full">
+							if (!schedule) return null;
-									<div className="flex items-center gap-2 flex-1 min-w-0 w-0">
+							return <SortableBackupCard key={schedule.id} schedule={schedule} />;
-										<CalendarClock className="h-5 w-5 text-muted-foreground shrink-0" />
+						})}
-										<CardTitle className="text-lg truncate">{schedule.name}</CardTitle>
+						<Link to="/backups/create">
-									</div>
+							<Card className="flex flex-col items-center justify-center h-full hover:bg-muted/50 transition-colors cursor-pointer">
-									<BackupStatusDot
+								<CardContent className="flex flex-col items-center justify-center gap-2">
-										enabled={schedule.enabled}
+									<Plus className="h-8 w-8 text-muted-foreground" />
-										hasError={!!schedule.lastBackupError}
+									<span className="text-sm font-medium text-muted-foreground">Create a backup job</span>
-										isInProgress={schedule.lastBackupStatus === "in_progress"}
+								</CardContent>
-									/>
+							</Card>
-								</div>
+						</Link>
-								<CardDescription className="ml-0.5 flex items-center gap-2 text-xs">
+					</div>
-									<HardDrive className="h-3.5 w-3.5" />
+				</SortableContext>
-									<span className="truncate">{schedule.volume.name}</span>
+			</DndContext>
-									<span className="text-muted-foreground">→</span>
-									<Database className="h-3.5 w-3.5 text-strong-accent" />
-									<span className="truncate text-strong-accent">{schedule.repository.name}</span>
-								</CardDescription>
-							</CardHeader>
-							<CardContent className="flex-1 space-y-4">
-								<div className="space-y-2">
-									<div className="flex items-center justify-between text-sm">
-										<span className="text-muted-foreground">Schedule</span>
-										<code className="text-xs bg-muted px-2 py-1 rounded">{schedule.cronExpression}</code>
-									</div>
-									<div className="flex items-center justify-between text-sm">
-										<span className="text-muted-foreground">Last backup</span>
-										<span className="font-medium">
-											{schedule.lastBackupAt ? new Date(schedule.lastBackupAt).toLocaleDateString() : "Never"}
-										</span>
-									</div>
-									<div className="flex items-center justify-between text-sm">
-										<span className="text-muted-foreground">Next backup</span>
-										<span className="font-medium">
-											{schedule.nextBackupAt ? new Date(schedule.nextBackupAt).toLocaleDateString() : "N/A"}
-										</span>
-									</div>
-								</div>
-							</CardContent>
-						</Card>
-					</Link>
-				))}
-				<Link to="/backups/create">
-					<Card className="flex flex-col items-center justify-center h-full hover:bg-muted/50 transition-colors cursor-pointer">
-						<CardContent className="flex flex-col items-center justify-center gap-2">
-							<Plus className="h-8 w-8 text-muted-foreground" />
-							<span className="text-sm font-medium text-muted-foreground">Create a backup job</span>
-						</CardContent>
-					</Card>
-				</Link>
-			</div>
 		</div>
 	);
-}
+}