From e0e5400340fabd0b92191829b4549f5324215f85 Mon Sep 17 00:00:00 2001
From: Cristian Istrate <techcornersrl@gmail.com>
Date: Wed, 8 Oct 2025 14:18:17 +0300
Subject: [PATCH 1/2] votemonitor-1005 [Hacktoberfest][Web2.0] Implement forms
 CRUD in new UI

---
 .../pages/NgoAdmin/GuidesObservers/Page.tsx   |  14 +++
 .../GuidesObservers/components/Table.tsx      |  49 +++++++++
 .../components/TableColumns.tsx               | 104 ++++++++++++++++++
 .../components/TableFilters.tsx               |  61 ++++++++++
 web2.0/src/queries/guides-observers.ts        |  35 ++++++
 .../$electionRoundId/guides/index.tsx         |  10 +-
 .../services/api/guides-observers/list.api.ts |  13 +++
 web2.0/src/types/guides-observer.ts           |  35 ++++++
 8 files changed, 316 insertions(+), 5 deletions(-)
 create mode 100644 web2.0/src/pages/NgoAdmin/GuidesObservers/Page.tsx
 create mode 100644 web2.0/src/pages/NgoAdmin/GuidesObservers/components/Table.tsx
 create mode 100644 web2.0/src/pages/NgoAdmin/GuidesObservers/components/TableColumns.tsx
 create mode 100644 web2.0/src/pages/NgoAdmin/GuidesObservers/components/TableFilters.tsx
 create mode 100644 web2.0/src/queries/guides-observers.ts
 create mode 100644 web2.0/src/services/api/guides-observers/list.api.ts
 create mode 100644 web2.0/src/types/guides-observer.ts

diff --git a/web2.0/src/pages/NgoAdmin/GuidesObservers/Page.tsx b/web2.0/src/pages/NgoAdmin/GuidesObservers/Page.tsx
new file mode 100644
index 000000000..5cb688650
--- /dev/null
+++ b/web2.0/src/pages/NgoAdmin/GuidesObservers/Page.tsx
@@ -0,0 +1,14 @@
+import {Route} from "@/routes/(app)/elections/$electionRoundId/guides";
+import {useDebounce} from "@/hooks/use-debounce.ts";
+import {useListMonitoringObservers} from "@/queries/monitoring-observers.ts";
+import Table from "@/pages/NgoAdmin/GuidesObservers/components/Table.tsx";
+
+export default function Page() {
+    const { electionRoundId } = Route.useParams();
+    const search = Route.useSearch();
+    const debouncedSearch = useDebounce(search, 200);
+    const { data } = useListMonitoringObservers(electionRoundId, debouncedSearch);
+
+    // @ts-ignore
+    return <Table data={data} />;
+}
\ No newline at end of file
diff --git a/web2.0/src/pages/NgoAdmin/GuidesObservers/components/Table.tsx b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/Table.tsx
new file mode 100644
index 000000000..6b74ecc12
--- /dev/null
+++ b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/Table.tsx
@@ -0,0 +1,49 @@
+import type {PageResponse} from "@/types/common.ts";
+import type {GuidesObserverModel} from "@/types/guides-observer.ts";
+import {DataTable} from "@/components/ui/data-table.tsx";
+import {DataTableToolbar} from "@/components/data-table-toolbar.tsx";
+import TableFilters from "@/pages/NgoAdmin/GuidesObservers/components/TableFilters.tsx";
+import {useDataTable} from "@/hooks/use-data-table.ts";
+import {useMemo, useState} from "react";
+import {getGuidesObserversTableColumns} from "@/pages/NgoAdmin/GuidesObservers/components/TableColumns.tsx";
+import type {DataTableRowAction} from "@/types/data-table.ts";
+import { Route } from '@/routes/(app)/elections/$electionRoundId/guides'
+
+export interface TableProps {
+    data?: PageResponse<GuidesObserverModel>;
+}
+
+export default function Table({ data } : TableProps) {
+    const [rowAction, setRowAction] = useState<DataTableRowAction<GuidesObserverModel> | null>(null);
+
+    const search = Route.useSearch();
+    const navigate = Route.useNavigate();
+
+    const columns = useMemo(
+        () =>
+            getGuidesObserversTableColumns({
+                setRowAction
+            }), [setRowAction]
+    )
+
+    const { table } = useDataTable({
+        tableName: "guides-observer",
+        data: data?.items || [],
+        columns,
+        pageCount: data ? Math.ceil(data.totalCount / data.pageSize) : 0,
+        initialState: {
+            sorting: [{ id: "displayName", desc: false }],
+            columnPinning: { right: ["actions"] },
+        },
+        getRowId: (originalRow) => originalRow.id,
+        search,
+        navigate,
+    });
+    return (
+        <DataTable table={table}>
+            <DataTableToolbar table={table}>
+                <TableFilters table={table} />
+            </DataTableToolbar>
+        </DataTable>
+    )
+}
\ No newline at end of file
diff --git a/web2.0/src/pages/NgoAdmin/GuidesObservers/components/TableColumns.tsx b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/TableColumns.tsx
new file mode 100644
index 000000000..39dec5259
--- /dev/null
+++ b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/TableColumns.tsx
@@ -0,0 +1,104 @@
+"use client";
+
+import type {DataTableRowAction} from "@/types/data-table";
+import type {ColumnDef} from "@tanstack/react-table";
+import {Ellipsis} from "lucide-react";
+import * as React from "react";
+
+import {DataTableColumnHeader} from "@/components/data-table-column-header";
+import {Button} from "@/components/ui/button";
+import {
+    DropdownMenu,
+    DropdownMenuContent,
+    DropdownMenuItem,
+    DropdownMenuSeparator,
+    DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import type {GuidesObserverModel} from "@/types/guides-observer.ts";
+
+interface GetTasksTableColumnsProps {
+    setRowAction: React.Dispatch<
+        React.SetStateAction<DataTableRowAction<GuidesObserverModel> | null>
+    >;
+}
+
+export function getGuidesObserversTableColumns({
+                                                   setRowAction,
+                                               }: GetTasksTableColumnsProps): ColumnDef<GuidesObserverModel>[] {
+    return [
+        {
+            id: "title",
+            accessorKey: "title",
+            header: ({column}) => (
+                <DataTableColumnHeader column={column} title="Title"/>
+            ),
+            cell: ({row}) => (
+                <div className="truncate">{row.original.title}</div>
+            ),
+            meta: {
+                label: "Title",
+            },
+            enableSorting: true,
+            enableHiding: true,
+        },
+        {
+            id: "createdOn",
+            accessorKey: "createdOn",
+            header: ({column}) => (
+                <DataTableColumnHeader column={column} title="Uploaded On"/>
+            ),
+            cell: ({row}) => <div className="truncate">{row.original.createdOn}</div>,
+            meta: {
+                label: "Uploaded On",
+            },
+            enableSorting: true,
+            enableHiding: true,
+        },
+        {
+            id: "createdBy",
+            accessorKey: "createdBy",
+            header: ({ column }) => (
+                <DataTableColumnHeader column={column} title="Created By" />
+            ),
+            cell: ({ row }) => <div className="truncate">{row.original.createdBy}</div>,
+            meta: {
+                label: "Created By",
+            },
+            enableSorting: true,
+            enableHiding: true,
+        },
+        {
+            id: "actions",
+            cell: function Cell({row}) {
+                return (
+                    <DropdownMenu>
+                        <DropdownMenuTrigger asChild>
+                            <Button
+                                aria-label="Open menu"
+                                variant="ghost"
+                                className="flex size-8 p-0 data-[state=open]:bg-muted"
+                            >
+                                <Ellipsis className="size-4" aria-hidden="true"/>
+                            </Button>
+                        </DropdownMenuTrigger>
+                        <DropdownMenuContent align="end" className="w-40">
+                            <DropdownMenuItem
+                                onSelect={() => setRowAction({row, variant: "update"})}
+                            >
+                                Edit
+                            </DropdownMenuItem>
+
+                            <DropdownMenuSeparator/>
+                            <DropdownMenuItem
+                                onSelect={() => setRowAction({row, variant: "delete"})}
+                            >
+                                Delete
+                            </DropdownMenuItem>
+                        </DropdownMenuContent>
+                    </DropdownMenu>
+                );
+            },
+            size: 40,
+        },
+    ];
+}
diff --git a/web2.0/src/pages/NgoAdmin/GuidesObservers/components/TableFilters.tsx b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/TableFilters.tsx
new file mode 100644
index 000000000..b0c4f92ba
--- /dev/null
+++ b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/TableFilters.tsx
@@ -0,0 +1,61 @@
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { getRouteApi } from "@tanstack/react-router";
+import type { Table } from "@tanstack/react-table";
+import { X } from "lucide-react";
+import React from "react";
+import type {GuidesObserverModel} from "@/types/guides-observer.ts";
+
+interface DataTableToolbarProps extends React.ComponentProps<"div"> {
+  table: Table<GuidesObserverModel>;
+}
+
+const route = getRouteApi(
+  "/(app)/elections/$electionRoundId/guides/" as const
+);
+
+function TableFilters({ table }: DataTableToolbarProps) {
+  const search = route.useSearch();
+  const navigate = route.useNavigate();
+
+  const isFiltered = table.getState().columnFilters.length > 0;
+
+  //   const onReset = React.useCallback(() => {
+  //     table.resetColumnFilters();
+  //   }, [table]);
+
+  const onReset = React.useCallback(() => {
+    console.log("reset");
+  }, []);
+
+  return (
+    <div className="flex flex-1 flex-wrap items-center gap-2">
+      <Input
+        placeholder="Search"
+        value={search.searchText ?? ""}
+        onChange={(event) =>
+          navigate({
+            search: (prev) => ({ ...prev, searchText: event.target.value }),
+            replace: true,
+          })
+        }
+        className="h-8 w-40 lg:w-56"
+      />
+
+      {isFiltered && (
+        <Button
+          aria-label="Reset filters"
+          variant="outline"
+          size="sm"
+          className="border-dashed"
+          onClick={onReset}
+        >
+          <X />
+          Reset
+        </Button>
+      )}
+    </div>
+  );
+}
+
+export default TableFilters;
diff --git a/web2.0/src/queries/guides-observers.ts b/web2.0/src/queries/guides-observers.ts
new file mode 100644
index 000000000..7e9e048f1
--- /dev/null
+++ b/web2.0/src/queries/guides-observers.ts
@@ -0,0 +1,35 @@
+import { queryOptions, useQuery } from "@tanstack/react-query";
+import type {GuidesObserversSearch} from "@/types/guides-observer.ts";
+import {listGuidesObservers} from "@/services/api/guides-observers/list.api.ts";
+
+export const guidesObserversKeys = {
+    all: (electionRoundId: string) =>
+        ["guides-observers", electionRoundId] as const,
+    lists: (electionRoundId: string) =>
+        [...guidesObserversKeys.all(electionRoundId), "list"] as const,
+    list: (electionRoundId: string, search: GuidesObserversSearch) =>
+        [...guidesObserversKeys.lists(electionRoundId), { ...search }] as const,
+    details: (electionRoundId: string) =>
+        [...guidesObserversKeys.all(electionRoundId), "detail"] as const,
+    detail: (electionRoundId: string, id: string) =>
+        [...guidesObserversKeys.details(electionRoundId), id] as const,
+};
+
+const STALE_TIME = 1000 * 60 * 15; // 15 minutes
+
+export const listGuidesObserversQueryOptions = (
+    electionRoundId: string,
+    search: GuidesObserversSearch
+) =>
+    queryOptions({
+        queryKey: guidesObserversKeys.list(electionRoundId, search),
+        queryFn: async () => await listGuidesObservers(electionRoundId, search),
+        enabled: !!electionRoundId,
+        staleTime: STALE_TIME,
+        refetchOnWindowFocus: false,
+    });
+
+export const useListGuidesObservers = (
+    electionRoundId: string,
+    search: GuidesObserversSearch
+) => useQuery(listGuidesObserversQueryOptions(electionRoundId, search));
diff --git a/web2.0/src/routes/(app)/elections/$electionRoundId/guides/index.tsx b/web2.0/src/routes/(app)/elections/$electionRoundId/guides/index.tsx
index 16135a024..04ce46ccb 100644
--- a/web2.0/src/routes/(app)/elections/$electionRoundId/guides/index.tsx
+++ b/web2.0/src/routes/(app)/elections/$electionRoundId/guides/index.tsx
@@ -1,11 +1,11 @@
 import { createFileRoute } from "@tanstack/react-router";
+import Page from "@/pages/NgoAdmin/GuidesObservers/Page"
+import {zodValidator} from "@tanstack/zod-adapter";
+import {guidesObserversSearchSchema} from "@/types/guides-observer.ts";
 
 export const Route = createFileRoute(
   "/(app)/elections/$electionRoundId/guides/"
 )({
-  component: RouteComponent,
+  component: Page,
+    validateSearch: zodValidator(guidesObserversSearchSchema)
 });
-
-function RouteComponent() {
-  return <div>Hello "/(app)/elections/$electionRoundId/guides/"!</div>;
-}
diff --git a/web2.0/src/services/api/guides-observers/list.api.ts b/web2.0/src/services/api/guides-observers/list.api.ts
new file mode 100644
index 000000000..e04291c40
--- /dev/null
+++ b/web2.0/src/services/api/guides-observers/list.api.ts
@@ -0,0 +1,13 @@
+import { buildURLSearchParams } from "@/lib/utils";
+import API from "@/services/api";
+import type { PageResponse } from "@/types/common";
+import type {GuidesObserverModel, GuidesObserversSearch} from "@/types/guides-observer.ts";
+
+export const listGuidesObservers = (
+    electionRoundId: string,
+    search: GuidesObserversSearch
+): Promise<PageResponse<GuidesObserverModel>> => {
+    return API.get(`election-rounds/${electionRoundId}/observer-guide`, {
+        params: buildURLSearchParams(search),
+    }).then((res) => res.data);
+};
diff --git a/web2.0/src/types/guides-observer.ts b/web2.0/src/types/guides-observer.ts
new file mode 100644
index 000000000..afe15717d
--- /dev/null
+++ b/web2.0/src/types/guides-observer.ts
@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { SortOrder } from "./common";
+
+export interface GuidesObserverModel {
+    id: string;
+    title: string;
+    fileName: string;
+    mimeType: string;
+    guideType: string;
+    text: string;
+    websiteUrl: string;
+    createdOn: string;
+    createdBy: string;
+    presignedUrl: string;
+    urlValidityInSeconds: string;
+    filePath: string;
+    uploadedFileName: string;
+    isGuideOwner: boolean;
+}
+
+export const guidesObserversSearchSchema = z.object({
+    title: z.string().optional(),
+    fileName: z.string().optional(),
+    mimeType: z.string().optional(),
+    guideType: z.string().optional(),
+    searchText: z.string().optional(),
+    sortColumnName: z.string().optional(),
+    sortOrder: z.enum(SortOrder).optional(),
+    pageNumber: z.number().default(1),
+    pageSize: z.number().default(25),
+});
+
+export type GuidesObserversSearch = z.infer<
+    typeof guidesObserversSearchSchema
+>;

From 50728515125b93ea565b677ebfb04186c9b6b659 Mon Sep 17 00:00:00 2001
From: Cristian Istrate <office@techspot.solutions>
Date: Wed, 12 Aug 2026 08:13:44 +0300
Subject: [PATCH 2/2] votemonitor-1005 [Hacktoberfest][Web2.0] Implement
 observer guides CRUD in new UI

---
 .../mutations/guides-observers-mutations.ts   |  57 +++++
 .../pages/NgoAdmin/GuidesObservers/Page.tsx   |  39 ++-
 .../components/CreateGuideDialog.tsx          | 214 ++++++++++++++++
 .../GuidesObservers/components/Dialogs.tsx    |  58 +++++
 .../components/GuideTypeIcon.tsx              |  23 ++
 .../components/GuidesProvider.tsx             |  60 +++++
 .../GuidesObservers/components/RowActions.tsx |  57 +++++
 .../GuidesObservers/components/Table.tsx      | 177 ++++++++++----
 .../components/TableColumns.tsx               | 175 ++++++-------
 .../components/TableFilters.tsx               | 111 ++++++---
 .../components/UpdateGuideDialog.tsx          | 196 +++++++++++++++
 .../components/UploadGuideMenu.tsx            |  58 +++++
 web2.0/src/queries/guides-observers.ts        |  58 ++---
 .../$electionRoundId/guides/index.tsx         |  31 ++-
 .../api/guides-observers/create.api.ts        |  47 ++++
 .../api/guides-observers/delete.api.ts        |  14 ++
 .../services/api/guides-observers/list.api.ts |  26 +-
 .../api/guides-observers/update.api.ts        |  27 +++
 web2.0/src/types/guides-observer.ts           | 229 +++++++++++++++---
 19 files changed, 1385 insertions(+), 272 deletions(-)
 create mode 100644 web2.0/src/mutations/guides-observers-mutations.ts
 create mode 100644 web2.0/src/pages/NgoAdmin/GuidesObservers/components/CreateGuideDialog.tsx
 create mode 100644 web2.0/src/pages/NgoAdmin/GuidesObservers/components/Dialogs.tsx
 create mode 100644 web2.0/src/pages/NgoAdmin/GuidesObservers/components/GuideTypeIcon.tsx
 create mode 100644 web2.0/src/pages/NgoAdmin/GuidesObservers/components/GuidesProvider.tsx
 create mode 100644 web2.0/src/pages/NgoAdmin/GuidesObservers/components/RowActions.tsx
 create mode 100644 web2.0/src/pages/NgoAdmin/GuidesObservers/components/UpdateGuideDialog.tsx
 create mode 100644 web2.0/src/pages/NgoAdmin/GuidesObservers/components/UploadGuideMenu.tsx
 create mode 100644 web2.0/src/services/api/guides-observers/create.api.ts
 create mode 100644 web2.0/src/services/api/guides-observers/delete.api.ts
 create mode 100644 web2.0/src/services/api/guides-observers/update.api.ts

diff --git a/web2.0/src/mutations/guides-observers-mutations.ts b/web2.0/src/mutations/guides-observers-mutations.ts
new file mode 100644
index 000000000..82912b296
--- /dev/null
+++ b/web2.0/src/mutations/guides-observers-mutations.ts
@@ -0,0 +1,57 @@
+import { useMutation } from '@tanstack/react-query'
+import { queryClient } from '@/main'
+import { guidesObserversKeys } from '@/queries/guides-observers'
+import {
+  createGuide,
+  type CreateGuideRequest,
+} from '@/services/api/guides-observers/create.api'
+import { deleteGuide } from '@/services/api/guides-observers/delete.api'
+import {
+  updateGuide,
+  type UpdateGuideRequest,
+} from '@/services/api/guides-observers/update.api'
+
+/**
+ * Every mutation invalidates the whole guides namespace of the election round.
+ * The list is the single source of truth for the table, and the create endpoint
+ * answers with a partial model while the update one answers with nothing, so
+ * refetching is cheaper than patching the cache by hand.
+ */
+
+export const useCreateGuideMutation = (electionRoundId: string) =>
+  useMutation({
+    mutationFn: async (guide: CreateGuideRequest) =>
+      await createGuide(electionRoundId, guide),
+    onSuccess: async () => {
+      await queryClient.invalidateQueries({
+        queryKey: guidesObserversKeys.all(electionRoundId),
+      })
+    },
+  })
+
+export const useUpdateGuideMutation = (electionRoundId: string) =>
+  useMutation({
+    mutationFn: async ({
+      guideId,
+      guide,
+    }: {
+      guideId: string
+      guide: UpdateGuideRequest
+    }) => await updateGuide(electionRoundId, guideId, guide),
+    onSuccess: async () => {
+      await queryClient.invalidateQueries({
+        queryKey: guidesObserversKeys.all(electionRoundId),
+      })
+    },
+  })
+
+export const useDeleteGuideMutation = (electionRoundId: string) =>
+  useMutation({
+    mutationFn: async (guideId: string) =>
+      await deleteGuide(electionRoundId, guideId),
+    onSuccess: async () => {
+      await queryClient.invalidateQueries({
+        queryKey: guidesObserversKeys.all(electionRoundId),
+      })
+    },
+  })
diff --git a/web2.0/src/pages/NgoAdmin/GuidesObservers/Page.tsx b/web2.0/src/pages/NgoAdmin/GuidesObservers/Page.tsx
index 5cb688650..68c6b997b 100644
--- a/web2.0/src/pages/NgoAdmin/GuidesObservers/Page.tsx
+++ b/web2.0/src/pages/NgoAdmin/GuidesObservers/Page.tsx
@@ -1,14 +1,29 @@
-import {Route} from "@/routes/(app)/elections/$electionRoundId/guides";
-import {useDebounce} from "@/hooks/use-debounce.ts";
-import {useListMonitoringObservers} from "@/queries/monitoring-observers.ts";
-import Table from "@/pages/NgoAdmin/GuidesObservers/components/Table.tsx";
+import { useCurrentElectionRound } from '@/contexts/election-round.context'
+import { ElectionRoundStatus } from '@/types/election'
+import { H1, P } from '@/components/ui/typography'
+import { GuidesDialogs } from './components/Dialogs'
+import { GuidesProvider } from './components/GuidesProvider'
+import GuidesTable from './components/Table'
+import { UploadGuideMenu } from './components/UploadGuideMenu'
 
-export default function Page() {
-    const { electionRoundId } = Route.useParams();
-    const search = Route.useSearch();
-    const debouncedSearch = useDebounce(search, 200);
-    const { data } = useListMonitoringObservers(electionRoundId, debouncedSearch);
+function Page() {
+  const { electionRound } = useCurrentElectionRound()
+  // Archived election rounds are frozen, so nothing new can be uploaded to them.
+  const isArchived = electionRound?.status === ElectionRoundStatus.Archived
 
-    // @ts-ignore
-    return <Table data={data} />;
-}
\ No newline at end of file
+  return (
+    <GuidesProvider>
+      <div className='flex items-center justify-between'>
+        <div>
+          <H1>Observer guides</H1>
+          <P>Here&apos;s all guides your observers have access to</P>
+        </div>
+        <UploadGuideMenu disabled={isArchived} />
+      </div>
+      <GuidesTable />
+      <GuidesDialogs />
+    </GuidesProvider>
+  )
+}
+
+export default Page
diff --git a/web2.0/src/pages/NgoAdmin/GuidesObservers/components/CreateGuideDialog.tsx b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/CreateGuideDialog.tsx
new file mode 100644
index 000000000..a2d6ca005
--- /dev/null
+++ b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/CreateGuideDialog.tsx
@@ -0,0 +1,214 @@
+import { useEffect } from 'react'
+import { useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { useCreateGuideMutation } from '@/mutations/guides-observers-mutations'
+import { Route } from '@/routes/(app)/elections/$electionRoundId/guides'
+import {
+  createGuideSchema,
+  GuideType,
+  type CreateGuideForm,
+} from '@/types/guides-observer'
+import { toast } from 'sonner'
+import { Button } from '@/components/ui/button'
+import {
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog'
+import {
+  Form,
+  FormControl,
+  FormDescription,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from '@/components/ui/form'
+import { Input } from '@/components/ui/input'
+import { Separator } from '@/components/ui/separator'
+import { Spinner } from '@/components/ui/spinner'
+import { Textarea } from '@/components/ui/textarea'
+import { useGuides } from './GuidesProvider'
+
+export function CreateGuideDialog() {
+  const { open, setOpen, newGuideType } = useGuides()
+  const { electionRoundId } = Route.useParams()
+  const createGuideMutation = useCreateGuideMutation(electionRoundId)
+
+  // The type is chosen from the upload menu, so the dialog stays closed until
+  // one has been picked.
+  const isOpen = open === 'create' && newGuideType !== null
+
+  const form = useForm<CreateGuideForm>({
+    resolver: zodResolver(createGuideSchema),
+    mode: 'all',
+    defaultValues: {
+      guideType: newGuideType ?? GuideType.Document,
+      title: '',
+      file: undefined,
+      websiteUrl: '',
+      text: '',
+    },
+  })
+
+  // Start from a blank form on every open, otherwise a cancelled attempt would
+  // come back with its old values, its errors, and the previously picked type.
+  useEffect(() => {
+    if (isOpen && newGuideType) {
+      form.reset({
+        guideType: newGuideType,
+        title: '',
+        file: undefined,
+        websiteUrl: '',
+        text: '',
+      })
+    }
+  }, [form, isOpen, newGuideType])
+
+  const onSubmit = (values: CreateGuideForm) => {
+    createGuideMutation.mutate(
+      {
+        title: values.title,
+        guideType: values.guideType,
+        file: values.file,
+        websiteUrl: values.websiteUrl,
+        text: values.text,
+      },
+      {
+        onSuccess: () => {
+          setOpen(null)
+          toast.success('Upload was successful')
+        },
+        onError: () => {
+          toast.error('Error uploading guide', {
+            description:
+              'Please try again or contact support if the problem persists.',
+          })
+        },
+      }
+    )
+  }
+
+  return (
+    <Dialog
+      open={isOpen}
+      onOpenChange={(nextOpen) => {
+        if (!nextOpen) {
+          setOpen(null)
+        }
+      }}
+    >
+      <DialogContent
+        className='sm:max-w-[650px]'
+        // A misclick outside the dialog should not throw away a half filled
+        // form, which is how the same dialog behaves in the current admin app.
+        onInteractOutside={(event) => event.preventDefault()}
+      >
+        <DialogHeader>
+          <DialogTitle>New guide</DialogTitle>
+        </DialogHeader>
+        <Separator />
+
+        <Form {...form}>
+          <form
+            id='create-guide-form'
+            onSubmit={form.handleSubmit(onSubmit)}
+            className='flex w-full flex-col gap-4'
+          >
+            <FormField
+              control={form.control}
+              name='title'
+              render={({ field }) => (
+                <FormItem>
+                  <FormLabel>Title</FormLabel>
+                  <FormControl>
+                    <Input placeholder='Title' {...field} />
+                  </FormControl>
+                  <FormMessage />
+                </FormItem>
+              )}
+            />
+
+            {newGuideType === GuideType.Document && (
+              <FormField
+                control={form.control}
+                name='file'
+                // `value` is left out on purpose: a file input cannot be given
+                // one, only read from.
+                render={({ field: { name, onBlur, onChange, ref } }) => (
+                  <FormItem>
+                    <FormLabel>Guide</FormLabel>
+                    <FormControl>
+                      <Input
+                        type='file'
+                        name={name}
+                        ref={ref}
+                        onBlur={onBlur}
+                        onChange={(event) => onChange(event.target.files?.[0])}
+                        disabled={createGuideMutation.isPending}
+                      />
+                    </FormControl>
+                    <FormDescription>Up to 50 MB.</FormDescription>
+                    <FormMessage />
+                  </FormItem>
+                )}
+              />
+            )}
+
+            {newGuideType === GuideType.Website && (
+              <FormField
+                control={form.control}
+                name='websiteUrl'
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>Guide url</FormLabel>
+                    <FormControl>
+                      <Input placeholder='https://' {...field} />
+                    </FormControl>
+                    <FormMessage />
+                  </FormItem>
+                )}
+              />
+            )}
+
+            {newGuideType === GuideType.Text && (
+              <FormField
+                control={form.control}
+                name='text'
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>Text</FormLabel>
+                    <FormControl>
+                      <Textarea className='min-h-48' {...field} />
+                    </FormControl>
+                    <FormMessage />
+                  </FormItem>
+                )}
+              />
+            )}
+          </form>
+        </Form>
+
+        <DialogFooter>
+          <Button
+            variant='outline'
+            onClick={() => setOpen(null)}
+            disabled={createGuideMutation.isPending}
+          >
+            Cancel
+          </Button>
+          <Button
+            type='submit'
+            form='create-guide-form'
+            disabled={createGuideMutation.isPending}
+          >
+            {createGuideMutation.isPending && <Spinner className='mr-2' />}
+            Upload guide
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
diff --git a/web2.0/src/pages/NgoAdmin/GuidesObservers/components/Dialogs.tsx b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/Dialogs.tsx
new file mode 100644
index 000000000..d26b5fa70
--- /dev/null
+++ b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/Dialogs.tsx
@@ -0,0 +1,58 @@
+import { useDeleteGuideMutation } from '@/mutations/guides-observers-mutations'
+import { Route } from '@/routes/(app)/elections/$electionRoundId/guides'
+import { toast } from 'sonner'
+import { ConfirmDialog } from '@/components/ConfirmDialog'
+import { CreateGuideDialog } from './CreateGuideDialog'
+import { useGuides } from './GuidesProvider'
+import { UpdateGuideDialog } from './UpdateGuideDialog'
+
+/** Every dialog of the guides page, mounted once next to the table. */
+export function GuidesDialogs() {
+  const { open, setOpen, currentRow } = useGuides()
+  const { electionRoundId } = Route.useParams()
+  const deleteGuideMutation = useDeleteGuideMutation(electionRoundId)
+
+  const handleDelete = () => {
+    if (!currentRow) {
+      return
+    }
+
+    deleteGuideMutation.mutate(currentRow.id, {
+      onSuccess: () => {
+        setOpen(null)
+        toast.success('Delete was successful')
+      },
+      onError: () => {
+        toast.error('Error deleting guide', {
+          description:
+            'Please try again or contact support if the problem persists.',
+        })
+      },
+    })
+  }
+
+  return (
+    <>
+      <CreateGuideDialog />
+      <UpdateGuideDialog />
+
+      {currentRow && (
+        <ConfirmDialog
+          destructive
+          open={open === 'delete'}
+          onOpenChange={(isOpen) => {
+            if (!isOpen) {
+              setOpen(null)
+            }
+          }}
+          handleConfirm={handleDelete}
+          isLoading={deleteGuideMutation.isPending}
+          className='max-w-md'
+          title={`Delete ${currentRow.title} ?`}
+          desc='Are you sure you want to delete this guide? This action cannot be undone.'
+          confirmText='Delete'
+        />
+      )}
+    </>
+  )
+}
diff --git a/web2.0/src/pages/NgoAdmin/GuidesObservers/components/GuideTypeIcon.tsx b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/GuideTypeIcon.tsx
new file mode 100644
index 000000000..2be6165f2
--- /dev/null
+++ b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/GuideTypeIcon.tsx
@@ -0,0 +1,23 @@
+import { GuideType } from '@/types/guides-observer'
+import { FileText, Link2, Paperclip } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+/** One icon per guide type, shared by the table and the upload menu. */
+const guideTypeIcons = {
+  [GuideType.Document]: Paperclip,
+  [GuideType.Website]: Link2,
+  [GuideType.Text]: FileText,
+}
+
+type GuideTypeIconProps = {
+  guideType: GuideType
+  className?: string
+}
+
+export function GuideTypeIcon({ guideType, className }: GuideTypeIconProps) {
+  // Guides created before a new type is added would render nothing, so fall
+  // back to the plain text icon.
+  const Icon = guideTypeIcons[guideType] ?? FileText
+
+  return <Icon className={cn('h-4 w-4 opacity-50', className)} />
+}
diff --git a/web2.0/src/pages/NgoAdmin/GuidesObservers/components/GuidesProvider.tsx b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/GuidesProvider.tsx
new file mode 100644
index 000000000..505c2808d
--- /dev/null
+++ b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/GuidesProvider.tsx
@@ -0,0 +1,60 @@
+import React, { useState } from 'react'
+import type { GuidesObserverModel, GuideType } from '@/types/guides-observer'
+import useDialogState from '@/hooks/use-dialog-state'
+
+type GuidesDialogType = 'create' | 'update' | 'delete'
+
+type GuidesContextType = {
+  open: GuidesDialogType | null
+  setOpen: (str: GuidesDialogType | null) => void
+  /** The guide the update and delete dialogs act upon. */
+  currentRow: GuidesObserverModel | null
+  setCurrentRow: React.Dispatch<
+    React.SetStateAction<GuidesObserverModel | null>
+  >
+  /**
+   * Type of the guide being created. Picked from the upload menu before the
+   * dialog opens, since it decides which fields the form shows and can never
+   * be changed afterwards.
+   */
+  newGuideType: GuideType | null
+  setNewGuideType: React.Dispatch<React.SetStateAction<GuideType | null>>
+}
+
+const GuidesContext = React.createContext<GuidesContextType | null>(null)
+
+/**
+ * Holds which guide dialog is open and what it works on, so the page header,
+ * the table rows and the dialogs all read the same state.
+ */
+export function GuidesProvider({ children }: { children: React.ReactNode }) {
+  const [open, setOpen] = useDialogState<GuidesDialogType>(null)
+  const [currentRow, setCurrentRow] = useState<GuidesObserverModel | null>(null)
+  const [newGuideType, setNewGuideType] = useState<GuideType | null>(null)
+
+  return (
+    <GuidesContext
+      value={{
+        open,
+        setOpen,
+        currentRow,
+        setCurrentRow,
+        newGuideType,
+        setNewGuideType,
+      }}
+    >
+      {children}
+    </GuidesContext>
+  )
+}
+
+// eslint-disable-next-line react-refresh/only-export-components
+export const useGuides = () => {
+  const guidesContext = React.useContext(GuidesContext)
+
+  if (!guidesContext) {
+    throw new Error('useGuides has to be used within <GuidesContext>')
+  }
+
+  return guidesContext
+}
diff --git a/web2.0/src/pages/NgoAdmin/GuidesObservers/components/RowActions.tsx b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/RowActions.tsx
new file mode 100644
index 000000000..55a894c39
--- /dev/null
+++ b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/RowActions.tsx
@@ -0,0 +1,57 @@
+import type { GuidesObserverModel } from '@/types/guides-observer'
+import { Ellipsis } from 'lucide-react'
+import { Button } from '@/components/ui/button'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu'
+import { useGuides } from './GuidesProvider'
+
+type GuideRowActionsProps = {
+  guide: GuidesObserverModel
+}
+
+export function GuideRowActions({ guide }: GuideRowActionsProps) {
+  const { setOpen, setCurrentRow } = useGuides()
+
+  // Guides shared by another NGO of the coalition are read only: the API only
+  // resolves them for their owner and answers 404 to anybody else.
+  const isReadOnly = !guide.isGuideOwner
+
+  return (
+    <DropdownMenu modal={false}>
+      <DropdownMenuTrigger asChild>
+        <Button
+          variant='ghost'
+          className='data-[state=open]:bg-muted flex h-8 w-8 p-0'
+        >
+          <Ellipsis className='h-4 w-4' />
+          <span className='sr-only'>Open menu</span>
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align='end' className='w-[160px]'>
+        <DropdownMenuItem
+          disabled={isReadOnly}
+          onClick={() => {
+            setCurrentRow(guide)
+            setOpen('update')
+          }}
+        >
+          Update
+        </DropdownMenuItem>
+        <DropdownMenuItem
+          variant='destructive'
+          disabled={isReadOnly}
+          onClick={() => {
+            setCurrentRow(guide)
+            setOpen('delete')
+          }}
+        >
+          Delete guide
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
diff --git a/web2.0/src/pages/NgoAdmin/GuidesObservers/components/Table.tsx b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/Table.tsx
index 6b74ecc12..7a1c2d16e 100644
--- a/web2.0/src/pages/NgoAdmin/GuidesObservers/components/Table.tsx
+++ b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/Table.tsx
@@ -1,49 +1,136 @@
-import type {PageResponse} from "@/types/common.ts";
-import type {GuidesObserverModel} from "@/types/guides-observer.ts";
-import {DataTable} from "@/components/ui/data-table.tsx";
-import {DataTableToolbar} from "@/components/data-table-toolbar.tsx";
-import TableFilters from "@/pages/NgoAdmin/GuidesObservers/components/TableFilters.tsx";
-import {useDataTable} from "@/hooks/use-data-table.ts";
-import {useMemo, useState} from "react";
-import {getGuidesObserversTableColumns} from "@/pages/NgoAdmin/GuidesObservers/components/TableColumns.tsx";
-import type {DataTableRowAction} from "@/types/data-table.ts";
+import React from 'react'
+import { useSuspenseListGuidesObservers } from '@/queries/guides-observers'
 import { Route } from '@/routes/(app)/elections/$electionRoundId/guides'
+import { SortOrder } from '@/types/common'
+import type { GuidesObserverModel } from '@/types/guides-observer'
+import { useDataTable } from '@/hooks/use-data-table'
+import { DataTable } from '@/components/ui/data-table'
+import { DataTableToolbar } from '@/components/data-table/data-table-toolbar'
+import { getGuidesObserversTableColumns } from './TableColumns'
+import TableFilters from './TableFilters'
 
-export interface TableProps {
-    data?: PageResponse<GuidesObserverModel>;
+/** Columns the table can be sorted by, mapped to the value used to compare rows. */
+const sortAccessors: Record<
+  string,
+  (guide: GuidesObserverModel) => string | number
+> = {
+  title: (guide) => guide.title?.toLowerCase() ?? '',
+  guideType: (guide) => guide.guideType ?? '',
+  createdOn: (guide) => new Date(guide.createdOn).getTime(),
+  createdBy: (guide) => guide.createdBy?.toLowerCase() ?? '',
 }
 
-export default function Table({ data } : TableProps) {
-    const [rowAction, setRowAction] = useState<DataTableRowAction<GuidesObserverModel> | null>(null);
-
-    const search = Route.useSearch();
-    const navigate = Route.useNavigate();
-
-    const columns = useMemo(
-        () =>
-            getGuidesObserversTableColumns({
-                setRowAction
-            }), [setRowAction]
-    )
-
-    const { table } = useDataTable({
-        tableName: "guides-observer",
-        data: data?.items || [],
-        columns,
-        pageCount: data ? Math.ceil(data.totalCount / data.pageSize) : 0,
-        initialState: {
-            sorting: [{ id: "displayName", desc: false }],
-            columnPinning: { right: ["actions"] },
-        },
-        getRowId: (originalRow) => originalRow.id,
-        search,
-        navigate,
-    });
-    return (
-        <DataTable table={table}>
-            <DataTableToolbar table={table}>
-                <TableFilters table={table} />
-            </DataTableToolbar>
-        </DataTable>
-    )
-}
\ No newline at end of file
+export default function Table() {
+  const { electionRoundId } = Route.useParams()
+  const search = Route.useSearch()
+  const navigate = Route.useNavigate()
+
+  // The endpoint hands over every guide of the election round at once, so the
+  // three steps below (filter, sort, slice) are what a paginated API would
+  // normally do server side.
+  const { data: guides } = useSuspenseListGuidesObservers(electionRoundId)
+
+  const columns = React.useMemo(() => getGuidesObserversTableColumns(), [])
+
+  const filteredGuides = React.useMemo(() => {
+    const searchText = search.searchText?.trim().toLowerCase()
+
+    return guides.filter((guide) => {
+      if (
+        search.guideTypeFilter &&
+        guide.guideType !== search.guideTypeFilter
+      ) {
+        return false
+      }
+
+      if (!searchText) {
+        return true
+      }
+
+      // Same two columns the search box hints at: the guide name and whoever
+      // uploaded it.
+      return (
+        guide.title?.toLowerCase().includes(searchText) ||
+        guide.createdBy?.toLowerCase().includes(searchText)
+      )
+    })
+  }, [guides, search.searchText, search.guideTypeFilter])
+
+  const sortedGuides = React.useMemo(() => {
+    const accessor = search.sortColumnName
+      ? sortAccessors[search.sortColumnName]
+      : undefined
+
+    if (!accessor) {
+      return filteredGuides
+    }
+
+    const direction = search.sortOrder === SortOrder.Desc ? -1 : 1
+
+    // Copied first: sort mutates in place and the array belongs to the query cache.
+    return [...filteredGuides].sort((left, right) => {
+      const leftValue = accessor(left)
+      const rightValue = accessor(right)
+
+      if (leftValue === rightValue) {
+        return 0
+      }
+
+      return (leftValue > rightValue ? 1 : -1) * direction
+    })
+  }, [filteredGuides, search.sortColumnName, search.sortOrder])
+
+  const pageCount = Math.max(
+    1,
+    Math.ceil(sortedGuides.length / search.pageSize)
+  )
+
+  // Filtering, or deleting the last row of the last page, can leave the url
+  // pointing past the end of the list. Clamp the slice so nothing flashes empty
+  // and put the url back in range.
+  const pageIndex = Math.min(Math.max(0, search.pageNumber - 1), pageCount - 1)
+
+  React.useEffect(() => {
+    if (search.pageNumber > pageCount) {
+      navigate({
+        search: (prev) => ({ ...prev, pageNumber: pageCount }),
+        replace: true,
+      })
+    }
+  }, [navigate, pageCount, search.pageNumber])
+
+  const pagedGuides = React.useMemo(
+    () =>
+      sortedGuides.slice(
+        pageIndex * search.pageSize,
+        pageIndex * search.pageSize + search.pageSize
+      ),
+    [sortedGuides, pageIndex, search.pageSize]
+  )
+
+  const { table } = useDataTable({
+    tableName: 'guides-observers',
+    data: pagedGuides,
+    columns,
+    pageCount,
+    initialState: {
+      sorting: [{ id: 'createdOn', desc: true }],
+      columnPinning: { right: ['actions'] },
+    },
+    getRowId: (originalRow) => originalRow.id,
+    // Filtering is driven by the dedicated filters below, not by the table's
+    // own global filter state.
+    globalFilter: { enabled: false },
+    pagination: { pageKey: 'pageNumber', pageSizeKey: 'pageSize' },
+    search,
+    navigate,
+  })
+
+  return (
+    <DataTable table={table}>
+      <DataTableToolbar table={table}>
+        <TableFilters />
+      </DataTableToolbar>
+    </DataTable>
+  )
+}
diff --git a/web2.0/src/pages/NgoAdmin/GuidesObservers/components/TableColumns.tsx b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/TableColumns.tsx
index 39dec5259..234b1b1eb 100644
--- a/web2.0/src/pages/NgoAdmin/GuidesObservers/components/TableColumns.tsx
+++ b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/TableColumns.tsx
@@ -1,104 +1,75 @@
-"use client";
+import { format } from 'date-fns'
+import type { ColumnDef } from '@tanstack/react-table'
+import type { GuidesObserverModel } from '@/types/guides-observer'
+import { DateTimeFormat } from '@/constants/formats'
+import { DataTableColumnHeader } from '@/components/data-table/data-table-column-header'
+import { GuideTypeIcon } from './GuideTypeIcon'
+import { GuideRowActions } from './RowActions'
 
-import type {DataTableRowAction} from "@/types/data-table";
-import type {ColumnDef} from "@tanstack/react-table";
-import {Ellipsis} from "lucide-react";
-import * as React from "react";
-
-import {DataTableColumnHeader} from "@/components/data-table-column-header";
-import {Button} from "@/components/ui/button";
-import {
-    DropdownMenu,
-    DropdownMenuContent,
-    DropdownMenuItem,
-    DropdownMenuSeparator,
-    DropdownMenuTrigger,
-} from "@/components/ui/dropdown-menu";
-import type {GuidesObserverModel} from "@/types/guides-observer.ts";
-
-interface GetTasksTableColumnsProps {
-    setRowAction: React.Dispatch<
-        React.SetStateAction<DataTableRowAction<GuidesObserverModel> | null>
-    >;
-}
-
-export function getGuidesObserversTableColumns({
-                                                   setRowAction,
-                                               }: GetTasksTableColumnsProps): ColumnDef<GuidesObserverModel>[] {
-    return [
-        {
-            id: "title",
-            accessorKey: "title",
-            header: ({column}) => (
-                <DataTableColumnHeader column={column} title="Title"/>
-            ),
-            cell: ({row}) => (
-                <div className="truncate">{row.original.title}</div>
-            ),
-            meta: {
-                label: "Title",
-            },
-            enableSorting: true,
-            enableHiding: true,
-        },
-        {
-            id: "createdOn",
-            accessorKey: "createdOn",
-            header: ({column}) => (
-                <DataTableColumnHeader column={column} title="Uploaded On"/>
-            ),
-            cell: ({row}) => <div className="truncate">{row.original.createdOn}</div>,
-            meta: {
-                label: "Uploaded On",
-            },
-            enableSorting: true,
-            enableHiding: true,
-        },
-        {
-            id: "createdBy",
-            accessorKey: "createdBy",
-            header: ({ column }) => (
-                <DataTableColumnHeader column={column} title="Created By" />
-            ),
-            cell: ({ row }) => <div className="truncate">{row.original.createdBy}</div>,
-            meta: {
-                label: "Created By",
-            },
-            enableSorting: true,
-            enableHiding: true,
-        },
-        {
-            id: "actions",
-            cell: function Cell({row}) {
-                return (
-                    <DropdownMenu>
-                        <DropdownMenuTrigger asChild>
-                            <Button
-                                aria-label="Open menu"
-                                variant="ghost"
-                                className="flex size-8 p-0 data-[state=open]:bg-muted"
-                            >
-                                <Ellipsis className="size-4" aria-hidden="true"/>
-                            </Button>
-                        </DropdownMenuTrigger>
-                        <DropdownMenuContent align="end" className="w-40">
-                            <DropdownMenuItem
-                                onSelect={() => setRowAction({row, variant: "update"})}
-                            >
-                                Edit
-                            </DropdownMenuItem>
-
-                            <DropdownMenuSeparator/>
-                            <DropdownMenuItem
-                                onSelect={() => setRowAction({row, variant: "delete"})}
-                            >
-                                Delete
-                            </DropdownMenuItem>
-                        </DropdownMenuContent>
-                    </DropdownMenu>
-                );
-            },
-            size: 40,
-        },
-    ];
+export function getGuidesObserversTableColumns(): ColumnDef<GuidesObserverModel>[] {
+  return [
+    {
+      header: '',
+      id: 'guideType',
+      enableSorting: false,
+      size: 16,
+      minSize: 25,
+      maxSize: 25,
+      cell: ({ row }) => (
+        <div className='w-[30px]'>
+          <GuideTypeIcon guideType={row.original.guideType} />
+        </div>
+      ),
+    },
+    {
+      header: ({ column }) => (
+        <DataTableColumnHeader title='Title' column={column} />
+      ),
+      accessorFn: (row) => row.title,
+      id: 'title',
+      enableSorting: true,
+      cell: ({ row }) => <div className='truncate'>{row.original.title}</div>,
+      meta: {
+        label: 'Title',
+      },
+    },
+    {
+      header: ({ column }) => (
+        <DataTableColumnHeader title='Uploaded on' column={column} />
+      ),
+      accessorFn: (row) => row.createdOn,
+      id: 'createdOn',
+      enableSorting: true,
+      size: 200,
+      cell: ({ row }) => (
+        <div className='truncate'>
+          {format(row.original.createdOn, DateTimeFormat)}
+        </div>
+      ),
+      meta: {
+        label: 'Uploaded on',
+      },
+    },
+    {
+      header: ({ column }) => (
+        <DataTableColumnHeader title='Created by' column={column} />
+      ),
+      accessorFn: (row) => row.createdBy,
+      id: 'createdBy',
+      enableSorting: true,
+      cell: ({ row }) => (
+        <div className='truncate'>{row.original.createdBy}</div>
+      ),
+      meta: {
+        label: 'Created by',
+      },
+    },
+    {
+      header: '',
+      id: 'actions',
+      enableSorting: false,
+      size: 40,
+      cell: ({ row }) => <GuideRowActions guide={row.original} />,
+    },
+  ]
 }
diff --git a/web2.0/src/pages/NgoAdmin/GuidesObservers/components/TableFilters.tsx b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/TableFilters.tsx
index b0c4f92ba..0aa9ee6f7 100644
--- a/web2.0/src/pages/NgoAdmin/GuidesObservers/components/TableFilters.tsx
+++ b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/TableFilters.tsx
@@ -1,53 +1,92 @@
-import { Button } from "@/components/ui/button";
-import { Input } from "@/components/ui/input";
-import { getRouteApi } from "@tanstack/react-router";
-import type { Table } from "@tanstack/react-table";
-import { X } from "lucide-react";
-import React from "react";
-import type {GuidesObserverModel} from "@/types/guides-observer.ts";
-
-interface DataTableToolbarProps extends React.ComponentProps<"div"> {
-  table: Table<GuidesObserverModel>;
-}
-
-const route = getRouteApi(
-  "/(app)/elections/$electionRoundId/guides/" as const
-);
+import React from 'react'
+import { Route } from '@/routes/(app)/elections/$electionRoundId/guides'
+import type { Option } from '@/types/data-table'
+import {
+  GuideTypeLabels,
+  GuideTypeList,
+  type GuideType,
+} from '@/types/guides-observer'
+import { X } from 'lucide-react'
+import { useDebouncedCallback } from '@/hooks/use-debounced-callback'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { SingleSelectDataTableFacetedFilter } from '@/components/data-table/data-table-faceted-filter'
 
-function TableFilters({ table }: DataTableToolbarProps) {
-  const search = route.useSearch();
-  const navigate = route.useNavigate();
+const guideTypeOptions: Option[] = GuideTypeList.map((guideType) => ({
+  label: GuideTypeLabels[guideType],
+  value: guideType,
+}))
 
-  const isFiltered = table.getState().columnFilters.length > 0;
+function TableFilters() {
+  const search = Route.useSearch()
+  const navigate = Route.useNavigate()
 
-  //   const onReset = React.useCallback(() => {
-  //     table.resetColumnFilters();
-  //   }, [table]);
+  const isFiltered =
+    Boolean(search.searchText) || Boolean(search.guideTypeFilter)
 
   const onReset = React.useCallback(() => {
-    console.log("reset");
-  }, []);
+    navigate({
+      search: {
+        pageNumber: 1,
+        pageSize: search.pageSize,
+      },
+      replace: true,
+    })
+  }, [navigate, search.pageSize])
+
+  // The input is kept in local state so typing stays responsive while the url,
+  // and with it the filtered list, is only rewritten once the user pauses.
+  const [searchInput, setSearchInput] = React.useState(search.searchText ?? '')
+
+  React.useEffect(() => {
+    setSearchInput(search.searchText ?? '')
+  }, [search.searchText])
+
+  const debouncedSearch = useDebouncedCallback((value: string) => {
+    navigate({
+      // Back to the first page: the current one may no longer exist once the
+      // list shrinks.
+      search: (prev) => ({ ...prev, searchText: value, pageNumber: 1 }),
+      replace: true,
+    })
+  }, 500)
+
+  const handleInputChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+    setSearchInput(event.target.value)
+    debouncedSearch(event.target.value)
+  }
 
   return (
-    <div className="flex flex-1 flex-wrap items-center gap-2">
+    <div className='flex flex-1 flex-wrap items-center gap-2'>
       <Input
-        placeholder="Search"
-        value={search.searchText ?? ""}
-        onChange={(event) =>
+        placeholder='Search'
+        value={searchInput}
+        onChange={handleInputChange}
+        className='h-8 w-40 lg:w-56'
+      />
+
+      <SingleSelectDataTableFacetedFilter
+        title='Guide type'
+        options={guideTypeOptions}
+        value={search.guideTypeFilter as string}
+        onValueChange={(value) =>
           navigate({
-            search: (prev) => ({ ...prev, searchText: event.target.value }),
+            search: (prev) => ({
+              ...prev,
+              guideTypeFilter: value as GuideType,
+              pageNumber: 1,
+            }),
             replace: true,
           })
         }
-        className="h-8 w-40 lg:w-56"
       />
 
       {isFiltered && (
         <Button
-          aria-label="Reset filters"
-          variant="outline"
-          size="sm"
-          className="border-dashed"
+          aria-label='Reset filters'
+          variant='outline'
+          size='sm'
+          className='border-dashed'
           onClick={onReset}
         >
           <X />
@@ -55,7 +94,7 @@ function TableFilters({ table }: DataTableToolbarProps) {
         </Button>
       )}
     </div>
-  );
+  )
 }
 
-export default TableFilters;
+export default TableFilters
diff --git a/web2.0/src/pages/NgoAdmin/GuidesObservers/components/UpdateGuideDialog.tsx b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/UpdateGuideDialog.tsx
new file mode 100644
index 000000000..2432a7459
--- /dev/null
+++ b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/UpdateGuideDialog.tsx
@@ -0,0 +1,196 @@
+import { useEffect } from 'react'
+import { useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { useUpdateGuideMutation } from '@/mutations/guides-observers-mutations'
+import { Route } from '@/routes/(app)/elections/$electionRoundId/guides'
+import {
+  GuideType,
+  updateGuideSchema,
+  type UpdateGuideForm,
+} from '@/types/guides-observer'
+import { toast } from 'sonner'
+import { Button } from '@/components/ui/button'
+import {
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog'
+import {
+  Form,
+  FormControl,
+  FormDescription,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from '@/components/ui/form'
+import { Input } from '@/components/ui/input'
+import { Separator } from '@/components/ui/separator'
+import { Spinner } from '@/components/ui/spinner'
+import { Textarea } from '@/components/ui/textarea'
+import { useGuides } from './GuidesProvider'
+
+export function UpdateGuideDialog() {
+  const { open, setOpen, currentRow: guide } = useGuides()
+  const { electionRoundId } = Route.useParams()
+  const updateGuideMutation = useUpdateGuideMutation(electionRoundId)
+
+  const isOpen = open === 'update' && guide !== null
+
+  const form = useForm<UpdateGuideForm>({
+    resolver: zodResolver(updateGuideSchema),
+    mode: 'all',
+    defaultValues: {
+      guideType: guide?.guideType ?? GuideType.Document,
+      title: guide?.title ?? '',
+      websiteUrl: guide?.websiteUrl ?? '',
+      text: guide?.text ?? '',
+    },
+  })
+
+  // The dialog is mounted once and reused for every row, so the form has to be
+  // refilled with the guide it was opened on.
+  useEffect(() => {
+    if (isOpen && guide) {
+      form.reset({
+        guideType: guide.guideType,
+        title: guide.title,
+        websiteUrl: guide.websiteUrl ?? '',
+        text: guide.text ?? '',
+      })
+    }
+  }, [form, guide, isOpen])
+
+  if (!guide) {
+    return null
+  }
+
+  const onSubmit = (values: UpdateGuideForm) => {
+    updateGuideMutation.mutate(
+      {
+        guideId: guide.id,
+        guide: {
+          title: values.title,
+          websiteUrl: values.websiteUrl,
+          text: values.text,
+        },
+      },
+      {
+        onSuccess: () => {
+          setOpen(null)
+          toast.success('Update was successful')
+        },
+        onError: () => {
+          toast.error('Error updating guide', {
+            description:
+              'Please try again or contact support if the problem persists.',
+          })
+        },
+      }
+    )
+  }
+
+  return (
+    <Dialog
+      open={isOpen}
+      onOpenChange={(nextOpen) => {
+        if (!nextOpen) {
+          setOpen(null)
+        }
+      }}
+    >
+      <DialogContent
+        className='sm:max-w-[650px]'
+        onInteractOutside={(event) => event.preventDefault()}
+      >
+        <DialogHeader>
+          <DialogTitle>Update guide</DialogTitle>
+        </DialogHeader>
+        <Separator />
+
+        <Form {...form}>
+          <form
+            id='update-guide-form'
+            onSubmit={form.handleSubmit(onSubmit)}
+            className='flex w-full flex-col gap-4'
+          >
+            <FormField
+              control={form.control}
+              name='title'
+              render={({ field }) => (
+                <FormItem>
+                  <FormLabel>Title</FormLabel>
+                  <FormControl>
+                    <Input {...field} />
+                  </FormControl>
+                  <FormMessage />
+                </FormItem>
+              )}
+            />
+
+            {/* Documents expose nothing but their title: the API keeps the
+                uploaded file as it is and offers no way to replace it. */}
+            {guide.guideType === GuideType.Document && (
+              <FormDescription>
+                Attached file: {guide.fileName}. Upload a new guide to replace
+                it.
+              </FormDescription>
+            )}
+
+            {guide.guideType === GuideType.Website && (
+              <FormField
+                control={form.control}
+                name='websiteUrl'
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>Guide url</FormLabel>
+                    <FormControl>
+                      <Input placeholder='Guide url' {...field} />
+                    </FormControl>
+                    <FormMessage />
+                  </FormItem>
+                )}
+              />
+            )}
+
+            {guide.guideType === GuideType.Text && (
+              <FormField
+                control={form.control}
+                name='text'
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>Text</FormLabel>
+                    <FormControl>
+                      <Textarea className='min-h-48' {...field} />
+                    </FormControl>
+                    <FormMessage />
+                  </FormItem>
+                )}
+              />
+            )}
+          </form>
+        </Form>
+
+        <DialogFooter>
+          <Button
+            variant='outline'
+            onClick={() => setOpen(null)}
+            disabled={updateGuideMutation.isPending}
+          >
+            Cancel
+          </Button>
+          <Button
+            type='submit'
+            form='update-guide-form'
+            disabled={updateGuideMutation.isPending}
+          >
+            {updateGuideMutation.isPending && <Spinner className='mr-2' />}
+            Update guide
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
diff --git a/web2.0/src/pages/NgoAdmin/GuidesObservers/components/UploadGuideMenu.tsx b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/UploadGuideMenu.tsx
new file mode 100644
index 000000000..a0a7b6557
--- /dev/null
+++ b/web2.0/src/pages/NgoAdmin/GuidesObservers/components/UploadGuideMenu.tsx
@@ -0,0 +1,58 @@
+import { GuideType, GuideTypeList } from '@/types/guides-observer'
+import { ChevronDown, Upload } from 'lucide-react'
+import { Button } from '@/components/ui/button'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu'
+import { GuideTypeIcon } from './GuideTypeIcon'
+import { useGuides } from './GuidesProvider'
+
+/** Wording of each entry of the upload menu. */
+const uploadMenuLabels: Record<GuideType, string> = {
+  [GuideType.Document]: 'Document guide',
+  [GuideType.Website]: 'Url guide',
+  [GuideType.Text]: 'Text guide',
+}
+
+type UploadGuideMenuProps = {
+  disabled?: boolean
+}
+
+/**
+ * Entry point for creating a guide. The type is picked here rather than inside
+ * the dialog because it cannot be changed later and it decides which fields the
+ * form has to show.
+ */
+export function UploadGuideMenu({ disabled }: UploadGuideMenuProps) {
+  const { setOpen, setNewGuideType } = useGuides()
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild disabled={disabled}>
+        <Button>
+          <Upload className='mr-1.5 h-4 w-4' />
+          Upload observer guide
+          <ChevronDown className='h-4 w-4 opacity-50' />
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align='end' className='w-56'>
+        {GuideTypeList.map((guideType) => (
+          <DropdownMenuItem
+            key={guideType}
+            className='flex flex-row gap-2'
+            onClick={() => {
+              setNewGuideType(guideType)
+              setOpen('create')
+            }}
+          >
+            <GuideTypeIcon guideType={guideType} />
+            {uploadMenuLabels[guideType]}
+          </DropdownMenuItem>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
diff --git a/web2.0/src/queries/guides-observers.ts b/web2.0/src/queries/guides-observers.ts
index 7e9e048f1..4ba74d1d2 100644
--- a/web2.0/src/queries/guides-observers.ts
+++ b/web2.0/src/queries/guides-observers.ts
@@ -1,35 +1,35 @@
-import { queryOptions, useQuery } from "@tanstack/react-query";
-import type {GuidesObserversSearch} from "@/types/guides-observer.ts";
-import {listGuidesObservers} from "@/services/api/guides-observers/list.api.ts";
+import { queryOptions, useSuspenseQuery } from '@tanstack/react-query'
+import { listGuidesObservers } from '@/services/api/guides-observers/list.api'
+import type { GuidesObserverModel } from '@/types/guides-observer'
 
 export const guidesObserversKeys = {
-    all: (electionRoundId: string) =>
-        ["guides-observers", electionRoundId] as const,
-    lists: (electionRoundId: string) =>
-        [...guidesObserversKeys.all(electionRoundId), "list"] as const,
-    list: (electionRoundId: string, search: GuidesObserversSearch) =>
-        [...guidesObserversKeys.lists(electionRoundId), { ...search }] as const,
-    details: (electionRoundId: string) =>
-        [...guidesObserversKeys.all(electionRoundId), "detail"] as const,
-    detail: (electionRoundId: string, id: string) =>
-        [...guidesObserversKeys.details(electionRoundId), id] as const,
-};
+  all: (electionRoundId: string) =>
+    ['guides-observers', electionRoundId] as const,
+  lists: (electionRoundId: string) =>
+    [...guidesObserversKeys.all(electionRoundId), 'list'] as const,
+}
 
-const STALE_TIME = 1000 * 60 * 15; // 15 minutes
+const STALE_TIME = 1000 * 60 * 15 // 15 minutes
 
-export const listGuidesObserversQueryOptions = (
-    electionRoundId: string,
-    search: GuidesObserversSearch
+/**
+ * The key deliberately holds nothing but the election round id: the endpoint
+ * returns the whole collection and ignores search params, so folding them into
+ * the key would refetch the exact same payload on every keystroke.
+ */
+export const listGuidesObserversQueryOptions = <
+  TResult = GuidesObserverModel[],
+>(
+  electionRoundId: string,
+  select?: (data: GuidesObserverModel[]) => TResult
 ) =>
-    queryOptions({
-        queryKey: guidesObserversKeys.list(electionRoundId, search),
-        queryFn: async () => await listGuidesObservers(electionRoundId, search),
-        enabled: !!electionRoundId,
-        staleTime: STALE_TIME,
-        refetchOnWindowFocus: false,
-    });
+  queryOptions({
+    queryKey: guidesObserversKeys.lists(electionRoundId),
+    queryFn: async () => await listGuidesObservers(electionRoundId),
+    staleTime: STALE_TIME,
+    select,
+  })
 
-export const useListGuidesObservers = (
-    electionRoundId: string,
-    search: GuidesObserversSearch
-) => useQuery(listGuidesObserversQueryOptions(electionRoundId, search));
+export const useSuspenseListGuidesObservers = <TResult = GuidesObserverModel[]>(
+  electionRoundId: string,
+  select?: (data: GuidesObserverModel[]) => TResult
+) => useSuspenseQuery(listGuidesObserversQueryOptions(electionRoundId, select))
diff --git a/web2.0/src/routes/(app)/elections/$electionRoundId/guides/index.tsx b/web2.0/src/routes/(app)/elections/$electionRoundId/guides/index.tsx
index 04ce46ccb..b1ad25166 100644
--- a/web2.0/src/routes/(app)/elections/$electionRoundId/guides/index.tsx
+++ b/web2.0/src/routes/(app)/elections/$electionRoundId/guides/index.tsx
@@ -1,11 +1,28 @@
-import { createFileRoute } from "@tanstack/react-router";
-import Page from "@/pages/NgoAdmin/GuidesObservers/Page"
-import {zodValidator} from "@tanstack/zod-adapter";
-import {guidesObserversSearchSchema} from "@/types/guides-observer.ts";
+import { createFileRoute, stripSearchParams } from '@tanstack/react-router'
+import Page from '@/pages/NgoAdmin/GuidesObservers/Page'
+import { listGuidesObserversQueryOptions } from '@/queries/guides-observers'
+import { guidesObserversSearchSchema } from '@/types/guides-observer'
 
 export const Route = createFileRoute(
-  "/(app)/elections/$electionRoundId/guides/"
+  '/(app)/elections/$electionRoundId/guides/'
 )({
+  validateSearch: guidesObserversSearchSchema,
+  search: {
+    // Keep the url clean while nothing is filtered.
+    middlewares: [
+      stripSearchParams({
+        searchText: undefined,
+        guideTypeFilter: undefined,
+      }),
+    ],
+  },
+  loader: async ({ context, params: { electionRoundId } }) => {
+    // The list is fetched without the search params on purpose: filtering,
+    // sorting and paging all happen on the client, so the same payload serves
+    // every combination of them.
+    await context.queryClient.ensureQueryData(
+      listGuidesObserversQueryOptions(electionRoundId)
+    )
+  },
   component: Page,
-    validateSearch: zodValidator(guidesObserversSearchSchema)
-});
+})
diff --git a/web2.0/src/services/api/guides-observers/create.api.ts b/web2.0/src/services/api/guides-observers/create.api.ts
new file mode 100644
index 000000000..fbc7db99b
--- /dev/null
+++ b/web2.0/src/services/api/guides-observers/create.api.ts
@@ -0,0 +1,47 @@
+import API from '@/services/api'
+import { GuideType, type GuidesObserverModel } from '@/types/guides-observer'
+
+export type CreateGuideRequest = {
+  title: string
+  guideType: GuideType
+  /** Required for `Document` guides, ignored for the other types. */
+  file?: File
+  /** Required for `Website` guides, ignored for the other types. */
+  websiteUrl?: string
+  /** Required for `Text` guides, ignored for the other types. */
+  text?: string
+}
+
+/**
+ * Creates an observer guide.
+ *
+ * The endpoint accepts file uploads, so the payload always goes out as
+ * multipart even for the two types that carry no attachment. Only the field
+ * matching the selected type is appended: sending an empty `websiteUrl` for a
+ * document would fail the `new Uri(...)` conversion on the backend.
+ */
+export const createGuide = (
+  electionRoundId: string,
+  guide: CreateGuideRequest
+): Promise<GuidesObserverModel> => {
+  const formData = new FormData()
+  formData.append('Title', guide.title)
+  formData.append('GuideType', guide.guideType)
+
+  if (guide.guideType === GuideType.Document && guide.file) {
+    formData.append('Attachment', guide.file)
+  }
+
+  if (guide.guideType === GuideType.Website && guide.websiteUrl) {
+    formData.append('WebsiteUrl', guide.websiteUrl)
+  }
+
+  if (guide.guideType === GuideType.Text && guide.text) {
+    formData.append('Text', guide.text)
+  }
+
+  return API.post<GuidesObserverModel>(
+    `election-rounds/${electionRoundId}/observer-guide`,
+    formData
+  ).then((res) => res.data)
+}
diff --git a/web2.0/src/services/api/guides-observers/delete.api.ts b/web2.0/src/services/api/guides-observers/delete.api.ts
new file mode 100644
index 000000000..09f4cf300
--- /dev/null
+++ b/web2.0/src/services/api/guides-observers/delete.api.ts
@@ -0,0 +1,14 @@
+import API from '@/services/api'
+
+/**
+ * Deletes an observer guide. The backend performs a soft delete, so the guide
+ * simply stops showing up in the list.
+ */
+export const deleteGuide = (
+  electionRoundId: string,
+  guideId: string
+): Promise<void> => {
+  return API.delete(
+    `election-rounds/${electionRoundId}/observer-guide/${guideId}`
+  ).then(() => undefined)
+}
diff --git a/web2.0/src/services/api/guides-observers/list.api.ts b/web2.0/src/services/api/guides-observers/list.api.ts
index e04291c40..1c85420dc 100644
--- a/web2.0/src/services/api/guides-observers/list.api.ts
+++ b/web2.0/src/services/api/guides-observers/list.api.ts
@@ -1,13 +1,17 @@
-import { buildURLSearchParams } from "@/lib/utils";
-import API from "@/services/api";
-import type { PageResponse } from "@/types/common";
-import type {GuidesObserverModel, GuidesObserversSearch} from "@/types/guides-observer.ts";
+import API from '@/services/api'
+import type { GuidesObserverModel } from '@/types/guides-observer'
 
+/**
+ * Lists every observer guide of an election round.
+ *
+ * The endpoint takes no filter, sort or paging argument and answers with the
+ * whole collection wrapped in a `guides` property, so the array is unwrapped
+ * here and the table works on it locally.
+ */
 export const listGuidesObservers = (
-    electionRoundId: string,
-    search: GuidesObserversSearch
-): Promise<PageResponse<GuidesObserverModel>> => {
-    return API.get(`election-rounds/${electionRoundId}/observer-guide`, {
-        params: buildURLSearchParams(search),
-    }).then((res) => res.data);
-};
+  electionRoundId: string
+): Promise<GuidesObserverModel[]> => {
+  return API.get<{ guides: GuidesObserverModel[] }>(
+    `election-rounds/${electionRoundId}/observer-guide`
+  ).then((res) => res.data.guides)
+}
diff --git a/web2.0/src/services/api/guides-observers/update.api.ts b/web2.0/src/services/api/guides-observers/update.api.ts
new file mode 100644
index 000000000..56b7c1cad
--- /dev/null
+++ b/web2.0/src/services/api/guides-observers/update.api.ts
@@ -0,0 +1,27 @@
+import API from '@/services/api'
+
+export type UpdateGuideRequest = {
+  title: string
+  /** Only read by the backend for `Website` guides. */
+  websiteUrl?: string
+  /** Only read by the backend for `Text` guides. */
+  text?: string
+}
+
+/**
+ * Updates an observer guide.
+ *
+ * The guide type and the uploaded file are fixed at creation time, so a
+ * `Document` guide can only be renamed through this call. The endpoint answers
+ * with `204 No Content`, which is why nothing is returned here.
+ */
+export const updateGuide = (
+  electionRoundId: string,
+  guideId: string,
+  guide: UpdateGuideRequest
+): Promise<void> => {
+  return API.put(
+    `election-rounds/${electionRoundId}/observer-guide/${guideId}`,
+    guide
+  ).then(() => undefined)
+}
diff --git a/web2.0/src/types/guides-observer.ts b/web2.0/src/types/guides-observer.ts
index afe15717d..b4c665846 100644
--- a/web2.0/src/types/guides-observer.ts
+++ b/web2.0/src/types/guides-observer.ts
@@ -1,35 +1,204 @@
-import { z } from "zod";
-import { SortOrder } from "./common";
+import z from 'zod'
+import { SortOrder } from './common'
+
+/**
+ * Guide flavours supported by the API. A guide holds exactly one kind of
+ * content, decided when it is created and immutable afterwards: an uploaded
+ * file, an external link or a block of text.
+ */
+export enum GuideType {
+  Document = 'Document',
+  Website = 'Website',
+  Text = 'Text',
+}
+
+export const GuideTypeList: GuideType[] = [
+  GuideType.Document,
+  GuideType.Website,
+  GuideType.Text,
+]
+
+/** Labels shown in the table and in the guide type picker. */
+export const GuideTypeLabels: Record<GuideType, string> = {
+  [GuideType.Document]: 'Document',
+  [GuideType.Website]: 'Website',
+  [GuideType.Text]: 'Text',
+}
+
+/** An NGO of the coalition the guide has been shared with. */
+export interface GuideAccessModel {
+  ngoId: string
+  name: string
+}
 
 export interface GuidesObserverModel {
-    id: string;
-    title: string;
-    fileName: string;
-    mimeType: string;
-    guideType: string;
-    text: string;
-    websiteUrl: string;
-    createdOn: string;
-    createdBy: string;
-    presignedUrl: string;
-    urlValidityInSeconds: string;
-    filePath: string;
-    uploadedFileName: string;
-    isGuideOwner: boolean;
+  id: string
+  title: string
+  guideType: GuideType
+  /** Original name of the uploaded file. Only set for `Document` guides. */
+  fileName: string
+  mimeType: string
+  /** HTML sanitized by the backend. Only set for `Text` guides. */
+  text: string
+  /** Only set for `Website` guides. */
+  websiteUrl: string
+  /** Last update, falling back to the creation date when never updated. */
+  createdOn: string
+  /** Display name of the last person who touched the guide. */
+  createdBy: string
+  /** Short lived download link built by the backend for `Document` guides. */
+  presignedUrl: string
+  urlValidityInSeconds: number
+  filePath: string
+  uploadedFileName: string
+  /**
+   * `false` for guides received through a coalition. Those are read only: the
+   * API answers with a 404 when someone who is not the owner tries to update
+   * or delete them.
+   */
+  isGuideOwner: boolean
+  guideAccess: GuideAccessModel[]
 }
 
+/**
+ * Search params kept in the URL.
+ *
+ * The list endpoint only takes the election round id, so none of these reach
+ * the API: they drive the client side filtering, sorting and pagination of the
+ * full list the backend returns in one go.
+ */
 export const guidesObserversSearchSchema = z.object({
-    title: z.string().optional(),
-    fileName: z.string().optional(),
-    mimeType: z.string().optional(),
-    guideType: z.string().optional(),
-    searchText: z.string().optional(),
-    sortColumnName: z.string().optional(),
-    sortOrder: z.enum(SortOrder).optional(),
-    pageNumber: z.number().default(1),
-    pageSize: z.number().default(25),
-});
-
-export type GuidesObserversSearch = z.infer<
-    typeof guidesObserversSearchSchema
->;
+  searchText: z.string().optional(),
+  guideTypeFilter: z.enum(GuideType).optional(),
+  sortColumnName: z.string().optional(),
+  sortOrder: z.enum(SortOrder).optional(),
+  pageNumber: z.number().default(1),
+  pageSize: z.number().default(25),
+})
+
+/** Limits enforced by the API validators, mirrored here for instant feedback. */
+const GUIDE_TITLE_MAX_LENGTH = 256
+const GUIDE_WEBSITE_URL_MAX_LENGTH = 2048
+const GUIDE_FILE_MAX_SIZE = 50 * 1024 * 1024 // 50 MB
+
+/**
+ * Shape of the create form. The three content fields are optional at this level
+ * because only the one matching the selected type is required, which is what
+ * the refinement below enforces.
+ */
+export const createGuideSchema = z
+  .object({
+    guideType: z.enum(GuideType),
+    title: z
+      .string()
+      .trim()
+      .min(1, { message: 'Title is required' })
+      .max(GUIDE_TITLE_MAX_LENGTH, {
+        message: `Title cannot exceed ${GUIDE_TITLE_MAX_LENGTH} characters`,
+      }),
+    file: z.instanceof(File).optional(),
+    websiteUrl: z
+      .string()
+      .trim()
+      .max(GUIDE_WEBSITE_URL_MAX_LENGTH, {
+        message: `Url cannot exceed ${GUIDE_WEBSITE_URL_MAX_LENGTH} characters`,
+      })
+      .optional(),
+    text: z.string().optional(),
+  })
+  .superRefine(({ guideType, file, websiteUrl, text }, ctx) => {
+    if (guideType === GuideType.Document) {
+      if (!file) {
+        ctx.addIssue({
+          code: 'custom',
+          message: 'Select a file to upload',
+          path: ['file'],
+        })
+      } else if (file.size > GUIDE_FILE_MAX_SIZE) {
+        ctx.addIssue({
+          code: 'custom',
+          message: 'File cannot be larger than 50 MB',
+          path: ['file'],
+        })
+      }
+    }
+
+    if (guideType === GuideType.Website) {
+      if (!websiteUrl) {
+        ctx.addIssue({
+          code: 'custom',
+          message: 'Website url is required',
+          path: ['websiteUrl'],
+        })
+      } else if (!URL.canParse(websiteUrl)) {
+        // The backend feeds this straight into `new Uri(...)`, which throws on
+        // anything that is not an absolute url.
+        ctx.addIssue({
+          code: 'custom',
+          message: 'Enter a valid url, including https://',
+          path: ['websiteUrl'],
+        })
+      }
+    }
+
+    if (guideType === GuideType.Text && !text?.trim()) {
+      ctx.addIssue({
+        code: 'custom',
+        message: 'Text is required',
+        path: ['text'],
+      })
+    }
+  })
+
+export type CreateGuideForm = z.infer<typeof createGuideSchema>
+
+/**
+ * Shape of the edit form. Neither the type nor the uploaded file can be changed
+ * after creation, so `Document` guides only expose their title here.
+ */
+export const updateGuideSchema = z
+  .object({
+    guideType: z.enum(GuideType),
+    title: z
+      .string()
+      .trim()
+      .min(1, { message: 'Title is required' })
+      .max(GUIDE_TITLE_MAX_LENGTH, {
+        message: `Title cannot exceed ${GUIDE_TITLE_MAX_LENGTH} characters`,
+      }),
+    websiteUrl: z
+      .string()
+      .trim()
+      .max(GUIDE_WEBSITE_URL_MAX_LENGTH, {
+        message: `Url cannot exceed ${GUIDE_WEBSITE_URL_MAX_LENGTH} characters`,
+      })
+      .optional(),
+    text: z.string().optional(),
+  })
+  .superRefine(({ guideType, websiteUrl, text }, ctx) => {
+    if (guideType === GuideType.Website) {
+      if (!websiteUrl) {
+        ctx.addIssue({
+          code: 'custom',
+          message: 'Website url is required',
+          path: ['websiteUrl'],
+        })
+      } else if (!URL.canParse(websiteUrl)) {
+        ctx.addIssue({
+          code: 'custom',
+          message: 'Enter a valid url, including https://',
+          path: ['websiteUrl'],
+        })
+      }
+    }
+
+    if (guideType === GuideType.Text && !text?.trim()) {
+      ctx.addIssue({
+        code: 'custom',
+        message: 'Text is required',
+        path: ['text'],
+      })
+    }
+  })
+
+export type UpdateGuideForm = z.infer<typeof updateGuideSchema>