From f2161e95c6bcd8a9bedd50cfa31e78f8e24453ea Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sun, 4 Oct 2026 12:16:28 +0000 Subject: [PATCH 1/2] feat(topics): a Topics page, a recording's topics, and topics on the graph canvas The Topics page shows a namespace's vocabulary as a tree with search and a drawer to edit, merge and delete topics. A recording's Entities tab lists its topics; Term entities can become topics from their drawer; topics show on the graph canvas as tags with About, Narrower and Related edges. TERM entities are labelled Terms. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_012Jo1JNziunMs8MgWJSGyyM --- CHANGELOG.md | 5 + DEVLOG.md | 2 +- docs/topics.md | 18 +- fastapi_backend/app/domain/entities.py | 2 +- fastapi_backend/app/domain/entity_setup.py | 2 +- .../__tests__/topics-model.test.ts | 61 +++ .../app/(app)/topics/[id]/page.tsx | 8 + nextjs-frontend/app/(app)/topics/page.tsx | 15 + .../components/app-shell/nav-config.ts | 4 +- .../components/entities/entity-drawer.tsx | 33 +- nextjs-frontend/components/graph/filters.tsx | 3 +- nextjs-frontend/components/graph/model.ts | 30 +- nextjs-frontend/components/graph/shape.tsx | 9 + .../components/recording/entities-tab.tsx | 18 +- .../components/settings/bodies.tsx | 2 +- nextjs-frontend/components/topics/model.ts | 88 +++ .../components/topics/recording-topics.tsx | 139 +++++ .../components/topics/topic-drawer.tsx | 511 ++++++++++++++++++ .../components/topics/topic-picker.tsx | 66 +++ .../components/topics/topics-page.tsx | 289 ++++++++++ 20 files changed, 1283 insertions(+), 22 deletions(-) create mode 100644 nextjs-frontend/__tests__/topics-model.test.ts create mode 100644 nextjs-frontend/app/(app)/topics/[id]/page.tsx create mode 100644 nextjs-frontend/app/(app)/topics/page.tsx create mode 100644 nextjs-frontend/components/topics/model.ts create mode 100644 nextjs-frontend/components/topics/recording-topics.tsx create mode 100644 nextjs-frontend/components/topics/topic-drawer.tsx create mode 100644 nextjs-frontend/components/topics/topic-picker.tsx create mode 100644 nextjs-frontend/components/topics/topics-page.tsx diff --git a/CHANGELOG.md b/CHANGELOG.md index 102f197a6..a5e6e672a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,11 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version ## Unreleased +- **A Topics page.** Topics in the navigation shows a namespace's vocabulary as a tree of broader and narrower topics, + with search, and a drawer to edit, merge or delete a topic and see the recordings about it. A recording's Entities + tab lists its topics for editors to add, remove or accept; a Term entity can be made a topic from its drawer; topics + show on the graph canvas as green tags. Entities of type TERM are now shown as Terms. + - **Topics, apart from entities.** Each namespace has a controlled vocabulary of topics (SKOS): a label, other labels, a definition, and broader, narrower and related topics. Recordings are about topics, said by a person or brought over when a topic-like entity (type TERM) becomes a topic; the entity is hidden until the topic is deleted. diff --git a/DEVLOG.md b/DEVLOG.md index b6bc0b03c..23f679a40 100644 --- a/DEVLOG.md +++ b/DEVLOG.md @@ -15,7 +15,7 @@ Todo: - [x] Vocabulary in the backend: topics with labels, definition, broader/narrower/related; recordings about topics; create, edit, merge, delete; turn a TERM entity into a topic (and back, by deleting the topic); API with viewer reads and editor changes; topics in the property graph (Topic, ABOUT, NARROWER, RELATED) and in RDF as SKOS -- [ ] Topics page: the tree of broader and narrower topics, a topic's recordings, edit and merge; a recording's topics +- [x] Topics page: the tree of broader and narrower topics, a topic's recordings, edit and merge; a recording's topics - [ ] Analysis suggests topics (summary topics and keywords matched to the vocabulary; new ones as suggestions to accept); a namespace can keep its vocabulary fixed or open, as entities do - [ ] # links in notes point at topics; assistant and MCP tools for topics diff --git a/docs/topics.md b/docs/topics.md index 879301cbc..97dbb02d8 100644 --- a/docs/topics.md +++ b/docs/topics.md @@ -5,8 +5,22 @@ entities. Entities are the named things a transcript mentions (people, organisat subject someone chose for the vocabulary, like "Gene therapy" or "Funding". Status: **built**: the vocabulary (labels, definitions, broader, narrower and related topics), recordings about -topics, topics made from topic-like entities, the API, topics in the graph and in RDF. **Planned**: a Topics page, -topic suggestions from analysis, `#` links in notes pointing at topics, and assistant and MCP tools for topics. +topics, topics made from topic-like entities, the API, the Topics page, a recording's topics, topics in the graph +(and on its canvas) and in RDF. **Planned**: topic suggestions from analysis, `#` links in notes pointing at topics, +and assistant and MCP tools for topics. + +## In the web app + +**Topics** in the navigation shows a namespace's vocabulary as a tree: top topics first, each opening onto its +narrower ones (a topic under two broader topics shows under both). Search finds topics by any of their labels. Pick +a topic to edit it in a drawer: its labels, definition, broader and related topics, its narrower topics, and the +recordings about it, where suggested ones can be accepted or removed. The drawer also merges topics and deletes one. +Editors add topics at the top or under another with **+**. + +A recording's **Entities** tab starts with its topics: editors add one from the vocabulary, take one off, or accept +or dismiss a suggestion. An entity of type Term has **Make a topic** in its drawer. On the graph canvas topics are +green tags, with About, Narrower and Related edges; ask the graph (for example `MATCH (t:Topic) RETURN t`) or open a +recording's children to bring them in. ## A topic diff --git a/fastapi_backend/app/domain/entities.py b/fastapi_backend/app/domain/entities.py index 7695714a7..a1ab08737 100644 --- a/fastapi_backend/app/domain/entities.py +++ b/fastapi_backend/app/domain/entities.py @@ -23,7 +23,7 @@ "PLACE": "Place", "EVENT": "Event", "WORK": "Work", - "TERM": "Topic", + "TERM": "Term", "DATE": "Date", "NUMBER": "Number", } diff --git a/fastapi_backend/app/domain/entity_setup.py b/fastapi_backend/app/domain/entity_setup.py index 99f0ff22a..dd7b8e27e 100644 --- a/fastapi_backend/app/domain/entity_setup.py +++ b/fastapi_backend/app/domain/entity_setup.py @@ -33,7 +33,7 @@ "PLACE": "A country, city, building or other place.", "EVENT": "A named event: a conference, a launch, a war.", "WORK": "A book, paper, film, law or other named work.", - "TERM": "A topic or term that isn't one of the other types.", + "TERM": "A term or theme that isn't one of the other types (the vocabulary of topics is kept apart, under Topics).", "DATE": "A date or time.", "NUMBER": "An amount, percentage or other number.", } diff --git a/nextjs-frontend/__tests__/topics-model.test.ts b/nextjs-frontend/__tests__/topics-model.test.ts new file mode 100644 index 000000000..964cdd55f --- /dev/null +++ b/nextjs-frontend/__tests__/topics-model.test.ts @@ -0,0 +1,61 @@ +import { broaderChoices, findTopics, splitLabels, topicTree, type TopicItem } from "@/components/topics/model"; + +const t = (id: number, label: string, broader: number[] = [], alt: string[] = []): TopicItem => ({ + id, + label, + alt, + broader, + related: [], + recordings: 0, + narrower: 0, +}); + +// Biology > Gene therapy > Viral vectors; Medicine > Gene therapy (two broader topics); Funding at the top +const items = [ + t(1, "Biology"), + t(2, "Gene therapy", [1, 4], ["GT"]), + t(3, "Viral vectors", [2]), + t(4, "Medicine"), + t(5, "funding"), +]; + +describe("topic tree", () => { + it("shows top topics by label, closed", () => { + expect(topicTree(items, new Set()).map((r) => r.topic.label)).toEqual(["Biology", "funding", "Medicine"]); + }); + + it("opens one path at a time, a topic under each of its broader topics", () => { + const rows = topicTree(items, new Set(["1", "1/2"])); + expect(rows.map((r) => [r.topic.label, r.depth, r.path])).toEqual([ + ["Biology", 0, "1"], + ["Gene therapy", 1, "1/2"], + ["Viral vectors", 2, "1/2/3"], + ["funding", 0, "5"], + ["Medicine", 0, "4"], + ]); + expect(topicTree(items, new Set(["4"])).map((r) => r.path)).toEqual(["1", "5", "4", "4/2"]); + }); + + it("cuts cycles and treats unknown broader topics as top", () => { + const loop = [t(1, "A", [2]), t(2, "B", [1]), t(3, "C", [99])]; + expect(topicTree(loop, new Set(["1"])).map((r) => r.topic.label)).toEqual(["C"]); + }); +}); + +describe("topic helpers", () => { + it("finds by label and other labels, prefix first", () => { + expect(findTopics(items, "gt").map((x) => x.label)).toEqual(["Gene therapy"]); + expect(findTopics(items, "me").map((x) => x.label)).toEqual(["Medicine"]); + expect(findTopics(items, "v").map((x) => x.label)).toEqual(["Viral vectors"]); + expect(findTopics(items, "i").map((x) => x.label)).toEqual(["Biology", "funding", "Medicine", "Viral vectors"]); + }); + + it("offers as broader only topics that aren't below it", () => { + expect(broaderChoices(items, 1).map((x) => x.id)).toEqual([5, 4]); + expect(broaderChoices(items, 3).map((x) => x.id)).toEqual([1, 5, 2, 4]); + }); + + it("splits other labels", () => { + expect(splitLabels(" GT, gene therapies ,gt,, ")).toEqual(["GT", "gene therapies"]); + }); +}); diff --git a/nextjs-frontend/app/(app)/topics/[id]/page.tsx b/nextjs-frontend/app/(app)/topics/[id]/page.tsx new file mode 100644 index 000000000..6b7cc428a --- /dev/null +++ b/nextjs-frontend/app/(app)/topics/[id]/page.tsx @@ -0,0 +1,8 @@ +import { notFound, redirect } from "next/navigation"; + +/** A topic opens in the Topics page, in its own namespace (the address RDF sends browsers to). */ +export default async function TopicPage({ params }: { params: Promise<{ id: string }> }) { + const { id } = await params; + if (!/^\d+$/.test(id)) notFound(); + redirect(`/topics?topic=${id}`); +} diff --git a/nextjs-frontend/app/(app)/topics/page.tsx b/nextjs-frontend/app/(app)/topics/page.tsx new file mode 100644 index 000000000..fab1f25a5 --- /dev/null +++ b/nextjs-frontend/app/(app)/topics/page.tsx @@ -0,0 +1,15 @@ +import type { Metadata } from "next"; +import { Suspense } from "react"; + +import { TopicsPage } from "@/components/topics/topics-page"; + +export const metadata: Metadata = { title: "Topics" }; + +/** A namespace's vocabulary of topics: what its recordings are about. */ +export default function Page() { + return ( + + + + ); +} diff --git a/nextjs-frontend/components/app-shell/nav-config.ts b/nextjs-frontend/components/app-shell/nav-config.ts index 925e72c79..95a50bc0e 100644 --- a/nextjs-frontend/components/app-shell/nav-config.ts +++ b/nextjs-frontend/components/app-shell/nav-config.ts @@ -5,7 +5,6 @@ import { HardDriveDownload, House, LibraryBig, - type LucideIcon, MessagesSquare, NotebookPen, RadioTower, @@ -13,6 +12,8 @@ import { Settings, Shapes, Shield, + Tags, + type LucideIcon, Waypoints, Workflow, } from "lucide-react"; @@ -44,6 +45,7 @@ export const NAV: NavItem[] = [ { label: "Chat", href: "/chat", icon: MessagesSquare }, { label: "Notes", href: "/notes", icon: NotebookPen }, { label: "Entities", href: "/entities", icon: Shapes }, + { label: "Topics", href: "/topics", icon: Tags }, { label: "Graph", href: "/graph", icon: Waypoints }, { label: "Reports", diff --git a/nextjs-frontend/components/entities/entity-drawer.tsx b/nextjs-frontend/components/entities/entity-drawer.tsx index 2a57fff92..f28712355 100644 --- a/nextjs-frontend/components/entities/entity-drawer.tsx +++ b/nextjs-frontend/components/entities/entity-drawer.tsx @@ -1,11 +1,12 @@ "use client"; import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"; -import { Eye, EyeOff, NotebookPen, Waypoints } from "lucide-react"; +import { Eye, EyeOff, NotebookPen, Tags, Waypoints } from "lucide-react"; import Link from "next/link"; +import { useRouter } from "next/navigation"; import { useEffect, useState } from "react"; -import { Entities } from "@/app/openapi-client"; +import { Entities, Topics } from "@/app/openapi-client"; import type { EntityType } from "@/app/openapi-client/types.gen"; import { recordingHref } from "@/components/search/links"; import { Banner } from "@/components/ui/banner"; @@ -107,6 +108,21 @@ export function EntityDrawer({ }, onError: fail("Couldn’t delete it"), }); + const router = useRouter(); + const toTopic = useMutation({ + mutationFn: () => data(Topics.entityToTopic({ client, path: { eid: id } })), + onSuccess: (t) => { + refresh(); + qc.invalidateQueries({ queryKey: ["topics"] }); + toast({ + title: `${t.label} is a topic now`, + body: "The entity is hidden while the topic exists.", + tone: "green", + }); + router.push(`/topics/${t.id}`); + }, + onError: fail("Couldn’t make it a topic"), + }); const hide = useMutation({ mutationFn: (hidden: boolean) => data(Entities.hideEntity({ client, path: { eid: id }, body: { hidden } })), onSuccess: (_, hidden) => { @@ -249,6 +265,19 @@ export function EntityDrawer({ > {d.hidden ? "Show again" : "Hide"} + {d.type === "TERM" && !builtin && !d.hidden && ( + + )} {d.defined && !d.mentions && ( + ) : ( + + )} + + ))} + {suggested.map((t) => ( +
  • + {t.label} + + +
  • + ))} + + )} + {canEdit && left.length > 0 && ( + setLabel(ev.target.value)} + /> + )} + + + {(ids) => ( + setAlt(ev.target.value)} + /> + )} + + + {(ids) => ( +