Umami is a privacy-first web and product analytics platform. Traffic, campaigns, behavior, conversions, and revenue in one place. No cookies, no surveillance, self-hosted or in the cloud.
TypeScript analyticsaudience-segmentationchartscohort-analysisgoogle-analyticsproduct-analyticsstatisticsuser-journeyweb-analytics
Add website annotations with chart markers and CRUD management
Mike Cao64e4cc1c3b4f
diff --git a/prisma/migrations/25_add_annotation/migration.sql b/prisma/migrations/25_add_annotation/migration.sqlnew file mode 100644index 000000000..abfa045b6--- /dev/null+++ b/prisma/migrations/25_add_annotation/migration.sql@@ -0,0 +1,19 @@+-- CreateTable+CREATE TABLE "annotation" (+ "annotation_id" UUID NOT NULL,+ "website_id" UUID NOT NULL,+ "user_id" UUID,+ "date" TIMESTAMPTZ(6) NOT NULL,+ "all_day" BOOLEAN NOT NULL DEFAULT true,+ "note" VARCHAR(500) NOT NULL,+ "created_at" TIMESTAMPTZ(6) DEFAULT CURRENT_TIMESTAMP,+ "updated_at" TIMESTAMPTZ(6),++ CONSTRAINT "annotation_pkey" PRIMARY KEY ("annotation_id")+);++-- CreateIndex+CREATE UNIQUE INDEX "annotation_annotation_id_key" ON "annotation"("annotation_id");++-- CreateIndex+CREATE INDEX "annotation_website_id_date_idx" ON "annotation"("website_id", "date");diff --git a/prisma/schema.prisma b/prisma/schema.prismaindex 97436ca16..113c67e99 100644--- a/prisma/schema.prisma+++ b/prisma/schema.prisma@@ -97,6 +97,7 @@ model Website {user User? @relation("user", fields: [userId], references: [id])createUser User? @relation("createUser", fields: [createdBy], references: [id])team Team? @relation(fields: [teamId], references: [id])+ annotations Annotation[]eventData EventData[]reports Report[]revenue Revenue[]@@ -269,6 +270,22 @@ model Report {@@map("report")}+model Annotation {+ id String @id() @map("annotation_id") @db.Uuid+ websiteId String @map("website_id") @db.Uuid+ userId String? @map("user_id") @db.Uuid+ date DateTime @db.Timestamptz(6)+ allDay Boolean @default(true) @map("all_day")+ note String @db.VarChar(500)+ createdAt DateTime? @default(now()) @map("created_at") @db.Timestamptz(6)+ updatedAt DateTime? @updatedAt @map("updated_at") @db.Timestamptz(6)++ website Website @relation(fields: [websiteId], references: [id])++ @@index([websiteId, date])+ @@map("annotation")+}+model Segment {id String @id() @map("segment_id") @db.UuidwebsiteId String @map("website_id") @db.Uuiddiff --git a/public/intl/messages/en-US.json b/public/intl/messages/en-US.jsonindex 0ed5102da..023f53b8c 100644--- a/public/intl/messages/en-US.json+++ b/public/intl/messages/en-US.json@@ -133,6 +133,7 @@"filters-enabled": "Filters enabled","property-filter": "Property Filter","activity-by-property": "Activity by property",+ "add-note": "Add note","first-click": "First click","first-seen": "First seen","funnel": "Funnel",@@ -361,6 +362,8 @@"arpu": "ARPU","uniqueCustomers": "Unique Customers","customers": "Customers",+ "note": "Note",+ "notes": "Notes","orders": "Orders","saved": "Saved","unknown": "Unknown",diff --git a/src/app/(main)/websites/[websiteId]/WebsiteChart.tsx b/src/app/(main)/websites/[websiteId]/WebsiteChart.tsxindex 896c733a8..10564f45a 100644--- a/src/app/(main)/websites/[websiteId]/WebsiteChart.tsx+++ b/src/app/(main)/websites/[websiteId]/WebsiteChart.tsx@@ -1,8 +1,16 @@-import { useMemo } from 'react';+import { useCallback, useMemo } from 'react';+import type { ChartAnnotation } from '@/components/charts/ChartAnnotationMarkers';import { LoadingPanel } from '@/components/common/LoadingPanel';-import { useDateRange, useTimezone } from '@/components/hooks';+import {+ useDateParameters,+ useDateRange,+ useNavigation,+ useTimezone,+ useWebsiteAnnotationsQuery,+} from '@/components/hooks';import { useWebsitePageviewsQuery } from '@/components/hooks/queries/useWebsitePageviewsQuery';import { PageviewsChart } from '@/components/metrics/PageviewsChart';+import { getAnnotationDateRangeValue } from '@/lib/annotations';export function WebsiteChart({websiteId,@@ -11,9 +19,16 @@ export function WebsiteChart({websiteId: string;compareMode?: boolean;}) {- const { timezone } = useTimezone();+ const { timezone, localFromUtc } = useTimezone();const { dateRange, dateCompare } = useDateRange({ timezone: timezone });const { startDate, endDate, unit, value } = dateRange;+ const { startAt, endAt } = useDateParameters();+ const { router, updateParams } = useNavigation();+ const { data: annotationData } = useWebsiteAnnotationsQuery(websiteId, {+ startAt,+ endAt,+ pageSize: 1000,+ });const { data, isLoading, isFetching, error } = useWebsitePageviewsQuery({websiteId,compare: compareMode ? dateCompare?.compare : undefined,@@ -45,6 +60,27 @@ export function WebsiteChart({};}, [data, startDate, endDate, unit]);+ const annotations = useMemo<ChartAnnotation[]>(() => {+ return (annotationData?.data || []).map(({ id, date, note, allDay }) => ({+ id,+ date: localFromUtc(new Date(date)),+ label: note,+ allDay,+ }));+ }, [annotationData, timezone]);++ const handleAnnotationClick = useCallback(+ (annotation: ChartAnnotation) => {+ router.push(+ updateParams({+ date: getAnnotationDateRangeValue(annotation.date, annotation.allDay !== false),+ offset: undefined,+ }),+ );+ },+ [router, updateParams],+ );+return (<LoadingPanel data={data} isFetching={isFetching} isLoading={isLoading} error={error}><PageviewsChart@@ -53,6 +89,8 @@ export function WebsiteChart({minDate={startDate}maxDate={endDate}unit={unit}+ annotations={annotations}+ onAnnotationClick={handleAnnotationClick}/></LoadingPanel>);diff --git a/src/app/(main)/websites/[websiteId]/WebsitePage.tsx b/src/app/(main)/websites/[websiteId]/WebsitePage.tsxindex 5412421e5..74a09acc3 100644--- a/src/app/(main)/websites/[websiteId]/WebsitePage.tsx+++ b/src/app/(main)/websites/[websiteId]/WebsitePage.tsx@@ -3,6 +3,7 @@ import { Column, Row } from '@umami/react-zen';import { ExpandedViewModal } from '@/app/(main)/websites/[websiteId]/ExpandedViewModal';import { Panel } from '@/components/common/Panel';import { UnitFilter } from '@/components/input/UnitFilter';+import { AnnotationsButton } from './annotations/AnnotationsButton';import { WebsiteChart } from './WebsiteChart';import { WebsiteControls } from './WebsiteControls';import { WebsiteMetricsBar } from './WebsiteMetricsBar';@@ -18,6 +19,9 @@ export function WebsitePage({ websiteId }: { websiteId: string }) {<UnitFilter /></Row><WebsiteChart websiteId={websiteId} />+ <Row justifyContent="end">+ <AnnotationsButton websiteId={websiteId} />+ </Row></Panel><WebsitePanels websiteId={websiteId} /><ExpandedViewModal websiteId={websiteId} />diff --git a/src/app/(main)/websites/[websiteId]/annotations/AnnotationDeleteButton.tsx b/src/app/(main)/websites/[websiteId]/annotations/AnnotationDeleteButton.tsxnew file mode 100644index 000000000..02aacb6c1--- /dev/null+++ b/src/app/(main)/websites/[websiteId]/annotations/AnnotationDeleteButton.tsx@@ -0,0 +1,50 @@+import { ConfirmationForm } from '@/components/common/ConfirmationForm';+import { useDeleteQuery, useMessages } from '@/components/hooks';+import { Trash } from '@/components/icons';+import { DialogButton } from '@/components/input/DialogButton';++export function AnnotationDeleteButton({+ annotationId,+ websiteId,+ name,+ onSave,+}: {+ annotationId: string;+ websiteId: string;+ name: string;+ onSave?: () => void;+}) {+ const { t, labels, messages } = useMessages();+ const { mutateAsync, isPending, error, touch } = useDeleteQuery(+ `/websites/${websiteId}/annotations/${annotationId}`,+ );++ const handleConfirm = async (close: () => void) => {+ await mutateAsync(null, {+ onSuccess: () => {+ touch('annotations');+ onSave?.();+ close();+ },+ });+ };++ return (+ <DialogButton icon={<Trash />} variant="quiet" title={t(labels.confirm)} width="400px">+ {({ close }) => (+ <ConfirmationForm+ message={t.rich(messages.confirmRemove, {+ target: name,+ b: chunks => <b>{chunks}</b>,+ })}+ isLoading={isPending}+ error={error}+ onConfirm={handleConfirm.bind(null, close)}+ onClose={close}+ buttonLabel={t(labels.delete)}+ buttonVariant="danger"+ />+ )}+ </DialogButton>+ );+}diff --git a/src/app/(main)/websites/[websiteId]/annotations/AnnotationEditForm.tsx b/src/app/(main)/websites/[websiteId]/annotations/AnnotationEditForm.tsxnew file mode 100644index 000000000..7df122748--- /dev/null+++ b/src/app/(main)/websites/[websiteId]/annotations/AnnotationEditForm.tsx@@ -0,0 +1,98 @@+import {+ Button,+ Column,+ DatePicker,+ Form,+ FormButtons,+ FormField,+ FormSubmitButton,+ Label,+ TextField,+} from '@umami/react-zen';+import { startOfDay } from 'date-fns';+import { useMemo, useState } from 'react';+import { useLocale, useMessages, useTimezone, useUpdateQuery } from '@/components/hooks';++export interface Annotation {+ id: string;+ websiteId: string;+ date: string;+ allDay: boolean;+ note: string;+}++export function AnnotationEditForm({+ annotation,+ websiteId,+ onSave,+ onClose,+}: {+ annotation?: Annotation;+ websiteId: string;+ onSave?: () => void;+ onClose?: () => void;+}) {+ const { t, labels, messages, getErrorMessage } = useMessages();+ const { locale } = useLocale();+ const { localToUtc, localFromUtc } = useTimezone();++ const initialDate = useMemo(+ () => (annotation ? localFromUtc(new Date(annotation.date)) : new Date()),+ [annotation],+ );+ const [date, setDate] = useState<Date>(startOfDay(initialDate));++ const { mutateAsync, error, isPending, touch, toast } = useUpdateQuery(+ `/websites/${websiteId}/annotations${annotation ? `/${annotation.id}` : ''}`,+ );++ const handleSubmit = async ({ note }: { note: string }) => {+ await mutateAsync(+ {+ date: localToUtc(startOfDay(date)).toISOString(),+ allDay: true,+ note,+ },+ {+ onSuccess: async () => {+ toast(t(messages.saved));+ touch('annotations');+ onSave?.();+ onClose?.();+ },+ },+ );+ };++ return (+ <Form+ error={getErrorMessage(error)}+ onSubmit={handleSubmit}+ defaultValues={{ note: annotation?.note || '' }}+ >+ <Column gap>+ <Column>+ <Label>{t(labels.date)}</Label>+ <DatePicker value={date} locale={locale} onChange={value => value && setDate(value)} />+ </Column>++ <FormField+ name="note"+ label={t(labels.note)}+ rules={{ required: t(labels.required), maxLength: 500 }}+ >+ <TextField asTextArea autoFocus />+ </FormField>++ <FormButtons>+ <Button isDisabled={isPending} onPress={onClose}>+ {t(labels.cancel)}+ </Button>+ <FormSubmitButton variant="primary" isDisabled={isPending}>+ {t(labels.save)}+ </FormSubmitButton>+ </FormButtons>+ </Column>+ </Form>+ );+}diff --git a/src/app/(main)/websites/[websiteId]/annotations/AnnotationsButton.tsx b/src/app/(main)/websites/[websiteId]/annotations/AnnotationsButton.tsxnew file mode 100644index 000000000..3236b6d88--- /dev/null+++ b/src/app/(main)/websites/[websiteId]/annotations/AnnotationsButton.tsx@@ -0,0 +1,24 @@+import { useMessages, useShare } from '@/components/hooks';+import { MessageSquareText } from '@/components/icons';+import { DialogButton } from '@/components/input/DialogButton';+import { AnnotationsModal } from './AnnotationsModal';++export function AnnotationsButton({ websiteId }: { websiteId: string }) {+ const { t, labels } = useMessages();+ const share = useShare();++ if (share) {+ return null;+ }++ return (+ <DialogButton+ icon={<MessageSquareText />}+ label={t(labels.notes)}+ variant="quiet"+ width="800px"+ >+ {({ close }) => <AnnotationsModal websiteId={websiteId} onClose={close} />}+ </DialogButton>+ );+}diff --git a/src/app/(main)/websites/[websiteId]/annotations/AnnotationsModal.tsx b/src/app/(main)/websites/[websiteId]/annotations/AnnotationsModal.tsxnew file mode 100644index 000000000..5ea5179d6--- /dev/null+++ b/src/app/(main)/websites/[websiteId]/annotations/AnnotationsModal.tsx@@ -0,0 +1,118 @@+import { Button, Column, DataColumn, DataTable, Loading, Row, Text } from '@umami/react-zen';+import { useState } from 'react';+import { formatAnnotationDate } from '@/components/charts/ChartAnnotationMarkers';+import { Empty } from '@/components/common/Empty';+import { IconLabel } from '@/components/common/IconLabel';+import { Pager } from '@/components/common/Pager';+import {+ useLocale,+ useMessages,+ useNavigation,+ useTimezone,+ useWebsiteAnnotationsQuery,+} from '@/components/hooks';+import { Edit, Plus } from '@/components/icons';+import { getAnnotationDateRangeValue } from '@/lib/annotations';+import { AnnotationDeleteButton } from './AnnotationDeleteButton';+import { type Annotation, AnnotationEditForm } from './AnnotationEditForm';++const PAGE_SIZE = 20;++type View = { mode: 'list' } | { mode: 'add' } | { mode: 'edit'; annotation: Annotation };++export function AnnotationsModal({+ websiteId,+ onClose,+}: {+ websiteId: string;+ onClose?: () => void;+}) {+ const { t, labels } = useMessages();+ const { locale } = useLocale();+ const { localFromUtc } = useTimezone();+ const { router, updateParams } = useNavigation();+ const [view, setView] = useState<View>({ mode: 'list' });+ const [page, setPage] = useState(1);+ const { data, isLoading } = useWebsiteAnnotationsQuery(websiteId, {+ page,+ pageSize: PAGE_SIZE,+ });++ const showList = () => setView({ mode: 'list' });++ const toLocalDate = (annotation: Annotation) => localFromUtc(new Date(annotation.date));++ const handleSelect = (annotation: Annotation) => {+ router.push(+ updateParams({+ date: getAnnotationDateRangeValue(toLocalDate(annotation), annotation.allDay),+ offset: undefined,+ }),+ );+ onClose?.();+ };++ if (view.mode !== 'list') {+ return (+ <AnnotationEditForm+ websiteId={websiteId}+ annotation={view.mode === 'edit' ? view.annotation : undefined}+ onSave={showList}+ onClose={showList}+ />+ );+ }++ if (isLoading && !data) {+ return <Loading placement="absolute" />;+ }++ const rows: Annotation[] = data?.data || [];++ return (+ <Column gap>+ <Row justifyContent="end">+ <Button variant="primary" onPress={() => setView({ mode: 'add' })}>+ <Plus />+ {t(labels.addNote)}+ </Button>+ </Row>+ {rows.length === 0 ? (+ <Empty />+ ) : (+ <DataTable data={rows}>+ <DataColumn id="date" label={t(labels.date)} width="200px">+ {(row: Annotation) => (+ <Button variant="quiet" onPress={() => handleSelect(row)}>+ {formatAnnotationDate(+ { id: row.id, date: toLocalDate(row), label: row.note, allDay: row.allDay },+ locale,+ )}+ </Button>+ )}+ </DataColumn>+ <DataColumn id="note" label={t(labels.note)}>+ {(row: Annotation) => <Text style={{ whiteSpace: 'pre-wrap' }}>{row.note}</Text>}+ </DataColumn>+ <DataColumn id="action" align="end" width="100px">+ {(row: Annotation) => (+ <Row>+ <Button variant="quiet" onPress={() => setView({ mode: 'edit', annotation: row })}>+ <IconLabel icon={<Edit />} />+ </Button>+ <AnnotationDeleteButton+ annotationId={row.id}+ websiteId={websiteId}+ name={row.note}+ />+ </Row>+ )}+ </DataColumn>+ </DataTable>+ )}+ {data?.count > PAGE_SIZE && (+ <Pager page={page} pageSize={PAGE_SIZE} count={data.count} onPageChange={setPage} />+ )}+ </Column>+ );+}diff --git a/src/app/api/websites/[websiteId]/annotations/[annotationId]/route.ts b/src/app/api/websites/[websiteId]/annotations/[annotationId]/route.tsnew file mode 100644index 000000000..fd2773357--- /dev/null+++ b/src/app/api/websites/[websiteId]/annotations/[annotationId]/route.ts@@ -0,0 +1,85 @@+import { parseRequest } from '@/lib/request';+import { json, notFound, ok, unauthorized } from '@/lib/response';+import { annotationSchema } from '@/lib/schema';+import { canUpdateWebsite, canViewSharedWebsiteFilters } from '@/permissions';+import { deleteAnnotation, getWebsiteAnnotation, updateAnnotation } from '@/queries/prisma';++export async function GET(+ request: Request,+ { params }: { params: Promise<{ websiteId: string; annotationId: string }> },+) {+ const { auth, error } = await parseRequest(request);++ if (error) {+ return error();+ }++ const { websiteId, annotationId } = await params;++ if (!(await canViewSharedWebsiteFilters(auth, websiteId))) {+ return unauthorized();+ }++ const annotation = await getWebsiteAnnotation(websiteId, annotationId);++ if (!annotation) {+ return notFound();+ }++ return json(annotation);+}++export async function POST(+ request: Request,+ { params }: { params: Promise<{ websiteId: string; annotationId: string }> },+) {+ const { auth, body, error } = await parseRequest(request, annotationSchema);++ if (error) {+ return error();+ }++ const { websiteId, annotationId } = await params;+ const { date, allDay, note } = body;++ if (!(await canUpdateWebsite(auth, websiteId))) {+ return unauthorized();+ }++ const annotation = await getWebsiteAnnotation(websiteId, annotationId);++ if (!annotation) {+ return notFound();+ }++ const result = await updateAnnotation(annotationId, { date, allDay, note });++ return json(result);+}++export async function DELETE(+ request: Request,+ { params }: { params: Promise<{ websiteId: string; annotationId: string }> },+) {+ const { auth, error } = await parseRequest(request);++ if (error) {+ return error();+ }++ const { websiteId, annotationId } = await params;++ if (!(await canUpdateWebsite(auth, websiteId))) {+ return unauthorized();+ }++ const annotation = await getWebsiteAnnotation(websiteId, annotationId);++ if (!annotation) {+ return notFound();+ }++ await deleteAnnotation(annotationId);++ return ok();+}diff --git a/src/app/api/websites/[websiteId]/annotations/route.test.ts b/src/app/api/websites/[websiteId]/annotations/route.test.tsnew file mode 100644index 000000000..27e331953--- /dev/null+++ b/src/app/api/websites/[websiteId]/annotations/route.test.ts@@ -0,0 +1,124 @@+import { beforeEach, expect, test, vi } from 'vitest';+import { parseRequest } from '@/lib/request';+import { canUpdateWebsite, canViewSharedWebsiteFilters } from '@/permissions';+import { createAnnotation, getWebsiteAnnotations } from '@/queries/prisma';+import { GET, POST } from './route';++vi.mock('@/lib/request', () => ({+ parseRequest: vi.fn(),+}));++vi.mock('@/permissions', () => ({+ canUpdateWebsite: vi.fn(),+ canViewSharedWebsiteFilters: vi.fn(),+}));++vi.mock('@/queries/prisma', () => ({+ createAnnotation: vi.fn(),+ getWebsiteAnnotations: vi.fn(),+}));++const parseRequestMock = vi.mocked(parseRequest);+const canUpdateWebsiteMock = vi.mocked(canUpdateWebsite);+const canViewSharedWebsiteFiltersMock = vi.mocked(canViewSharedWebsiteFilters);+const createAnnotationMock = vi.mocked(createAnnotation);+const getWebsiteAnnotationsMock = vi.mocked(getWebsiteAnnotations);++const params = Promise.resolve({ websiteId: 'website-1' });++beforeEach(() => {+ parseRequestMock.mockReset();+ canUpdateWebsiteMock.mockReset();+ canViewSharedWebsiteFiltersMock.mockReset();+ createAnnotationMock.mockReset();+ getWebsiteAnnotationsMock.mockReset();+});++test('POST validates the note and stores the annotation with the creating user', async () => {+ const date = new Date('2026-08-01T00:00:00.000Z');++ parseRequestMock.mockResolvedValue({+ auth: { user: { id: 'user-1' } },+ body: { date, allDay: false, note: 'Deployed v2' },+ error: undefined,+ } as any);+ canUpdateWebsiteMock.mockResolvedValue(true);+ createAnnotationMock.mockResolvedValue({ id: 'annotation-1' } as any);++ const response = await POST(+ new Request('http://localhost/api/websites/website-1/annotations', { method: 'POST' }),+ { params },+ );+ const schema = parseRequestMock.mock.calls[0][1] as {+ safeParse: (value: unknown) => { success: boolean; data?: any };+ };++ expect(schema.safeParse({ date: '2026-08-01', note: '' }).success).toBe(false);+ expect(schema.safeParse({ date: '2026-08-01', note: 'x'.repeat(501) }).success).toBe(false);+ expect(schema.safeParse({ date: 'not-a-date', note: 'ok' }).success).toBe(false);++ const parsed = schema.safeParse({ date: '2026-08-01', note: 'ok' });+ expect(parsed.success).toBe(true);+ expect(parsed.data.allDay).toBe(true);++ expect(createAnnotationMock).toHaveBeenCalledWith({+ id: expect.any(String),+ websiteId: 'website-1',+ userId: 'user-1',+ date,+ allDay: false,+ note: 'Deployed v2',+ });+ expect(response.status).toBe(200);+});++test('POST rejects users without update permission', async () => {+ parseRequestMock.mockResolvedValue({+ auth: { user: { id: 'user-1' } },+ body: { date: new Date(), allDay: true, note: 'nope' },+ error: undefined,+ } as any);+ canUpdateWebsiteMock.mockResolvedValue(false);++ const response = await POST(+ new Request('http://localhost/api/websites/website-1/annotations', { method: 'POST' }),+ { params },+ );++ expect(createAnnotationMock).not.toHaveBeenCalled();+ expect(response.status).toBe(401);+});++test('GET passes the date window through to the query only when both bounds are present', async () => {+ parseRequestMock.mockResolvedValue({+ auth: { user: { id: 'user-1' } },+ query: { startAt: 1000, endAt: 2000, search: 'deploy', page: 2, pageSize: 20 },+ error: undefined,+ } as any);+ canViewSharedWebsiteFiltersMock.mockResolvedValue(true);+ getWebsiteAnnotationsMock.mockResolvedValue({ data: [], count: 0 } as any);++ await GET(new Request('http://localhost/api/websites/website-1/annotations'), { params });++ expect(getWebsiteAnnotationsMock).toHaveBeenCalledWith('website-1', {+ search: 'deploy',+ page: 2,+ pageSize: 20,+ startDate: new Date(1000),+ endDate: new Date(2000),+ });++ parseRequestMock.mockResolvedValue({+ auth: { user: { id: 'user-1' } },+ query: { page: 1 },+ error: undefined,+ } as any);++ await GET(new Request('http://localhost/api/websites/website-1/annotations'), { params });++ expect(getWebsiteAnnotationsMock).toHaveBeenLastCalledWith('website-1', {+ search: undefined,+ page: 1,+ pageSize: undefined,+ });+});diff --git a/src/app/api/websites/[websiteId]/annotations/route.ts b/src/app/api/websites/[websiteId]/annotations/route.tsnew file mode 100644index 000000000..6393d41df--- /dev/null+++ b/src/app/api/websites/[websiteId]/annotations/route.ts@@ -0,0 +1,70 @@+import { z } from 'zod';+import { uuid } from '@/lib/crypto';+import { parseRequest } from '@/lib/request';+import { json, unauthorized } from '@/lib/response';+import { annotationSchema, pagingParams, searchParams } from '@/lib/schema';+import { canUpdateWebsite, canViewSharedWebsiteFilters } from '@/permissions';+import { createAnnotation, getWebsiteAnnotations } from '@/queries/prisma';++export async function GET(+ request: Request,+ { params }: { params: Promise<{ websiteId: string }> },+) {+ const schema = z.object({+ startAt: z.coerce.number().optional(),+ endAt: z.coerce.number().optional(),+ ...searchParams,+ ...pagingParams,+ });++ const { auth, query, error } = await parseRequest(request, schema);++ if (error) {+ return error();+ }++ const { websiteId } = await params;+ const { startAt, endAt, search, page, pageSize } = query;++ if (!(await canViewSharedWebsiteFilters(auth, websiteId))) {+ return unauthorized();+ }++ const annotations = await getWebsiteAnnotations(websiteId, {+ search,+ page,+ pageSize,+ ...(startAt && endAt && { startDate: new Date(startAt), endDate: new Date(endAt) }),+ });++ return json(annotations);+}++export async function POST(+ request: Request,+ { params }: { params: Promise<{ websiteId: string }> },+) {+ const { auth, body, error } = await parseRequest(request, annotationSchema);++ if (error) {+ return error();+ }++ const { websiteId } = await params;+ const { date, allDay, note } = body;++ if (!(await canUpdateWebsite(auth, websiteId))) {+ return unauthorized();+ }++ const result = await createAnnotation({+ id: uuid(),+ websiteId,+ userId: auth.user.id,+ date,+ allDay,+ note,+ });++ return json(result);+}diff --git a/src/components/charts/Chart.tsx b/src/components/charts/Chart.tsxindex d3775bf40..bf86cfe71 100644--- a/src/components/charts/Chart.tsx+++ b/src/components/charts/Chart.tsx@@ -6,6 +6,11 @@ import ChartJS, {type UpdateMode,} from 'chart.js/auto';import { useEffect, useMemo, useRef, useState } from 'react';+import {+ type AnnotationMarker,+ type ChartAnnotation,+ ChartAnnotationMarkers,+} from '@/components/charts/ChartAnnotationMarkers';import { Legend } from '@/components/metrics/Legend';import { DEFAULT_ANIMATION_DURATION } from '@/lib/constants';@@ -20,6 +25,21 @@ export interface ChartProps extends BoxProps {onTooltip?: (model: any) => void;hiddenLabels?: Set<string>;onLegendClick?: (label: string, willBeHidden: boolean) => void;+ annotations?: ChartAnnotation[];+ onAnnotationClick?: (annotation: ChartAnnotation) => void;+}++function isSameMarkers(a: AnnotationMarker[], b: AnnotationMarker[]) {+ return (+ a.length === b.length &&+ a.every(+ (m, i) =>+ m.x === b[i].x &&+ m.y === b[i].y &&+ m.annotations.length === b[i].annotations.length &&+ m.annotations.every((annotation, j) => annotation === b[i].annotations[j]),+ )+ );}export function Chart({@@ -31,11 +51,56 @@ export function Chart({chartOptions,hiddenLabels,onLegendClick,+ annotations,+ onAnnotationClick,...props}: ChartProps) {const canvas = useRef(null);const chart = useRef(null);const [legendItems, setLegendItems] = useState([]);+ const [markers, setMarkers] = useState<AnnotationMarker[]>([]);+ const annotationsRef = useRef<ChartAnnotation[]>(annotations);+ annotationsRef.current = annotations;++ // Computes pixel positions for annotation markers whenever the chart lays out (update / resize)+ const annotationPlugin = useMemo(+ () => ({+ id: 'annotationMarkers',+ afterLayout: (instance: any) => {+ const list = annotationsRef.current;+ const { chartArea, scales } = instance;++ if (!list?.length || !chartArea || !scales?.x) {+ setMarkers(prev => (prev.length ? [] : prev));+ return;+ }++ // Group annotations that land on the same pixel column into a single marker+ const groups = new Map<number, AnnotationMarker>();++ for (const annotation of list) {+ const x = Math.round(scales.x.getPixelForValue(annotation.date.getTime()));++ if (!Number.isFinite(x) || x < chartArea.left || x > chartArea.right) {+ continue;+ }++ const group = groups.get(x);++ if (group) {+ group.annotations.push(annotation);+ } else {+ groups.set(x, { annotations: [annotation], x, y: chartArea.bottom });+ }+ }++ const next = [...groups.values()];++ setMarkers(prev => (isSameMarkers(prev, next) ? prev : next));+ },+ }),+ [],+ );const options = useMemo(() => {return {@@ -99,6 +164,7 @@ export function Chart({type,data: chartData,options,+ plugins: [annotationPlugin],});setLegendItems(chart.current.legend.legendItems);@@ -140,11 +206,19 @@ export function Chart({}}, [chartData, options, updateMode, hiddenLabels]);+ // Re-run layout when annotations change so marker positions are recalculated+ useEffect(() => {+ chart.current?.update('none');+ }, [annotations]);+return (<Column gap="6"><Box {...props}><div style={{ position: 'relative', width: '100%', height: '100%', overflow: 'hidden' }}><canvas ref={canvas} style={{ position: 'absolute', top: 0, left: 0 }} />+ {markers.length > 0 && (+ <ChartAnnotationMarkers markers={markers} onClick={onAnnotationClick} />+ )}</div></Box><Legend items={legendItems} onClick={handleLegendClick} />diff --git a/src/components/charts/ChartAnnotationMarkers.module.css b/src/components/charts/ChartAnnotationMarkers.module.cssnew file mode 100644index 000000000..62ea86cc1--- /dev/null+++ b/src/components/charts/ChartAnnotationMarkers.module.css@@ -0,0 +1,42 @@+.marker {+ position: absolute;+ width: 14px;+ height: 14px;+ border-radius: 50%;+ border: 2px solid var(--base-color-1, #fff);+ padding: 0;+ cursor: pointer;+ transform: translate(-50%, -50%);+ z-index: 1;+ box-shadow: 0 1px 3px rgba(0, 0, 0, 0.3);+ transition: transform 0.1s ease-in-out;+}++.marker:hover,+.marker:focus-visible {+ transform: translate(-50%, -50%) scale(1.3);+ outline: none;+}++.count {+ position: absolute;+ top: -8px;+ right: -8px;+ min-width: 14px;+ height: 14px;+ padding: 0 3px;+ border-radius: 7px;+ font-size: 9px;+ font-weight: 600;+ line-height: 14px;+ color: #fff;+ background: inherit;+ border: 1px solid var(--base-color-1, #fff);+ pointer-events: none;+}++.note {+ max-width: 300px;+ white-space: pre-wrap;+ word-break: break-word;+}diff --git a/src/components/charts/ChartAnnotationMarkers.tsx b/src/components/charts/ChartAnnotationMarkers.tsxnew file mode 100644index 000000000..4c02435da--- /dev/null+++ b/src/components/charts/ChartAnnotationMarkers.tsx@@ -0,0 +1,69 @@+import { Column, Text, Tooltip, TooltipTrigger, useTheme } from '@umami/react-zen';+import { useMemo } from 'react';+import { useLocale } from '@/components/hooks';+import { getThemeColors } from '@/lib/colors';+import { formatDate } from '@/lib/date';+import styles from './ChartAnnotationMarkers.module.css';++export interface ChartAnnotation {+ id: string;+ date: Date;+ label: string;+ allDay?: boolean;+}++export interface AnnotationMarker {+ annotations: ChartAnnotation[];+ x: number;+ y: number;+}++export function formatAnnotationDate(annotation: ChartAnnotation, locale: string) {+ return formatDate(annotation.date, annotation.allDay === false ? 'PP p' : 'PP', locale);+}++export function ChartAnnotationMarkers({+ markers,+ onClick,+}: {+ markers: AnnotationMarker[];+ onClick?: (annotation: ChartAnnotation) => void;+}) {+ const { theme } = useTheme();+ const { locale } = useLocale();+ const { colors } = useMemo(() => getThemeColors(theme), [theme]);++ return (+ <>+ {markers.map(({ annotations, x, y }) => {+ const [first] = annotations;++ return (+ <TooltipTrigger key={first.id} delay={0}>+ <button+ type="button"+ className={styles.marker}+ style={{ left: x, top: y, backgroundColor: colors.chart.views.hoverBorderColor }}+ aria-label={annotations.map(({ label }) => label).join(', ')}+ onClick={() => onClick?.(first)}+ >+ {annotations.length > 1 && <span className={styles.count}>{annotations.length}</span>}+ </button>+ <Tooltip placement="top">+ <Column gap="3" className={styles.note}>+ {annotations.map(annotation => (+ <Column key={annotation.id} gap="1">+ <Text size="sm" weight="bold">+ {formatAnnotationDate(annotation, locale)}+ </Text>+ <Text size="sm">{annotation.label}</Text>+ </Column>+ ))}+ </Column>+ </Tooltip>+ </TooltipTrigger>+ );+ })}+ </>+ );+}diff --git a/src/components/hooks/index.ts b/src/components/hooks/index.tsindex bff1d0f95..b4a4db3c5 100644--- a/src/components/hooks/index.ts+++ b/src/components/hooks/index.ts@@ -75,6 +75,7 @@ export * from './queries/useWebsiteMetricsQuery';export * from './queries/useWebsitePageviewsQuery';export * from './queries/useWebsiteListChartsQuery';export * from './queries/useWebsiteQuery';+export * from './queries/useWebsiteAnnotationsQuery';export * from './queries/useWebsiteSegmentQuery';export * from './queries/useWebsiteSegmentsQuery';export * from './queries/useWebsiteSessionQuery';diff --git a/src/components/hooks/queries/useWebsiteAnnotationsQuery.ts b/src/components/hooks/queries/useWebsiteAnnotationsQuery.tsnew file mode 100644index 000000000..bd517d3eb--- /dev/null+++ b/src/components/hooks/queries/useWebsiteAnnotationsQuery.ts@@ -0,0 +1,21 @@+import { keepPreviousData } from '@tanstack/react-query';+import type { ReactQueryOptions } from '@/lib/types';+import { useApi } from '../useApi';+import { useModified } from '../useModified';++export function useWebsiteAnnotationsQuery(+ websiteId: string,+ params?: Record<string, string | number>,+ options?: ReactQueryOptions,+) {+ const { get, useQuery } = useApi();+ const { modified } = useModified(`annotations`);++ return useQuery({+ queryKey: ['website:annotations', { websiteId, modified, ...params }],+ queryFn: () => get(`/websites/${websiteId}/annotations`, params),+ enabled: !!websiteId,+ placeholderData: keepPreviousData,+ ...options,+ });+}diff --git a/src/components/messages.ts b/src/components/messages.tsindex b717200d4..35e2f7bcb 100644--- a/src/components/messages.ts+++ b/src/components/messages.ts@@ -336,6 +336,9 @@ export const labels: Record<string, string> = {addBoard: 'label.add-board',selectComponent: 'label.select-component',addLink: 'label.add-link',+ addNote: 'label.add-note',+ notes: 'label.notes',+ note: 'label.note',addPixel: 'label.add-pixel',maximize: 'label.maximize',remaining: 'label.remaining',diff --git a/src/lib/annotations.ts b/src/lib/annotations.tsnew file mode 100644index 000000000..e22a22387--- /dev/null+++ b/src/lib/annotations.ts@@ -0,0 +1,13 @@+import { endOfDay, endOfHour, startOfDay, startOfHour } from 'date-fns';++/**+ * Returns the `date` URL parameter value that filters the website view+ * to the day (all-day annotation) or hour (timed annotation) of an annotation.+ */+export function getAnnotationDateRangeValue(date: Date, allDay: boolean) {+ const [startDate, endDate] = allDay+ ? [startOfDay(date), endOfDay(date)]+ : [startOfHour(date), endOfHour(date)];++ return `range:${startDate.getTime()}:${endDate.getTime()}`;+}diff --git a/src/lib/schema.ts b/src/lib/schema.tsindex a58623850..3a4e98de6 100644--- a/src/lib/schema.ts+++ b/src/lib/schema.ts@@ -78,6 +78,12 @@ export const replayParams = {minDuration: z.coerce.number().int().nonnegative().optional(),};+export const annotationSchema = z.object({+ date: z.coerce.date(),+ allDay: z.boolean().optional().default(true),+ note: z.string().min(1).max(500),+});+export const pagingParams = {page: z.coerce.number().int().positive().optional(),pageSize: z.coerce.number().int().positive().optional(),diff --git a/src/queries/prisma/annotation.ts b/src/queries/prisma/annotation.tsnew file mode 100644index 000000000..6d23f4cbb--- /dev/null+++ b/src/queries/prisma/annotation.ts@@ -0,0 +1,64 @@+import type { Prisma } from '@/generated/prisma/client';+import prisma from '@/lib/prisma';+import type { QueryFilters } from '@/lib/types';++export async function getAnnotation(annotationId: string) {+ return prisma.client.annotation.findUnique({+ where: {+ id: annotationId,+ },+ });+}++export async function getWebsiteAnnotation(websiteId: string, annotationId: string) {+ return prisma.client.annotation.findFirst({+ where: { id: annotationId, websiteId },+ });+}++export async function getWebsiteAnnotations(+ websiteId: string,+ filters: QueryFilters & { startDate?: Date; endDate?: Date } = {},+) {+ const { search, startDate, endDate } = filters;+ const { getSearchParameters, pagedQuery } = prisma;++ const where: Prisma.AnnotationWhereInput = {+ websiteId,+ ...(startDate &&+ endDate && {+ date: {+ gte: startDate,+ lte: endDate,+ },+ }),+ ...getSearchParameters(search, [+ {+ note: 'contains',+ },+ ]),+ };++ return pagedQuery(+ 'annotation',+ {+ where,+ orderBy: {+ date: 'desc',+ },+ },+ filters,+ );+}++export async function createAnnotation(data: Prisma.AnnotationUncheckedCreateInput) {+ return prisma.client.annotation.create({ data });+}++export async function updateAnnotation(annotationId: string, data: Prisma.AnnotationUpdateInput) {+ return prisma.client.annotation.update({ where: { id: annotationId }, data });+}++export async function deleteAnnotation(annotationId: string) {+ return prisma.client.annotation.delete({ where: { id: annotationId } });+}diff --git a/src/queries/prisma/index.ts b/src/queries/prisma/index.tsindex ad6c50ea6..1db320166 100644--- a/src/queries/prisma/index.ts+++ b/src/queries/prisma/index.ts@@ -1,3 +1,4 @@+export * from './annotation';export * from './board';export * from './link';export * from './pixel';diff --git a/src/queries/prisma/website.test.ts b/src/queries/prisma/website.test.tsindex a1a993174..345b82bea 100644--- a/src/queries/prisma/website.test.ts+++ b/src/queries/prisma/website.test.ts@@ -83,6 +83,11 @@ function createDeleteTx(calls: string[]) {calls.push('segment');}),},+ annotation: {+ deleteMany: vi.fn(async () => {+ calls.push('annotation');+ }),+ },share: {deleteMany: vi.fn(async () => {calls.push('share');@@ -149,6 +154,7 @@ describe('website delete dependencies', () => {'session','report','segment',+ 'annotation','share','websiteDelete',]);diff --git a/src/queries/prisma/website.ts b/src/queries/prisma/website.tsindex 612aca09a..60a342138 100644--- a/src/queries/prisma/website.ts+++ b/src/queries/prisma/website.ts@@ -237,6 +237,10 @@ export async function deleteWebsite(websiteId: string) {where: { websiteId },});+ await tx.annotation.deleteMany({+ where: { websiteId },+ });+await tx.share.deleteMany({where: { entityId: websiteId },});