feat: Anchor integration and Anchor Note widget (#5040)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Meier Lukas <meierschlumpf@gmail.com>
This commit is contained in:
authored and GitHub committed 2026-04-10 20:43:43 +02:00
1 parent 57ea82f088
commit 7879b31630
20 files changed
+949 -2

No files matched your search

+2
View File
@@ -1,4 +1,5 @@
import type { WidgetOptionType } from "../options";
import { WidgetAnchorNoteInput } from "./widget-anchor-note-input";
import { WidgetAppInput } from "./widget-app-input";
import { WidgetDynamicSelectInput } from "./widget-dynamic-select-input";
import { WidgetLocationInput } from "./widget-location-input";
@@ -13,6 +14,7 @@ import { WidgetSwitchInput } from "./widget-switch-input";
import { WidgetTextInput } from "./widget-text-input";
const mapping = {
anchorNote: WidgetAnchorNoteInput,
text: WidgetTextInput,
location: WidgetLocationInput,
multiSelect: WidgetMultiSelectInput,
@@ -0,0 +1,63 @@
"use client";
import { useMemo, useState } from "react";
import { Loader, Select } from "@mantine/core";
import { useDebouncedValue } from "@mantine/hooks";
import { clientApi } from "@homarr/api/client";
import { useI18n, useScopedI18n } from "@homarr/translation/client";
import type { CommonWidgetInputProps } from "./common";
import { useWidgetInputTranslation } from "./common";
import { useFormContext } from "./form";
export const WidgetAnchorNoteInput = ({ property, kind, options }: CommonWidgetInputProps<"anchorNote">) => {
const t = useI18n();
const tWidget = useWidgetInputTranslation(kind, property);
const tAnchor = useScopedI18n("widget.anchorNote");
const form = useFormContext();
const integrationId = form.values.integrationIds[0];
const [search, setSearch] = useState("");
const [debouncedSearch] = useDebouncedValue(search, 250);
const { data: notes, isPending } = clientApi.widget.anchorNotes.listNotes.useQuery(
{
integrationId: integrationId ?? "",
search: debouncedSearch.trim() ? debouncedSearch : undefined,
limit: 200,
},
{
enabled: Boolean(integrationId),
refetchOnMount: false,
refetchOnWindowFocus: false,
refetchOnReconnect: false,
retry: false,
},
);
const noteOptions = useMemo(
() =>
notes?.map((note) => ({
value: note.id,
label: note.title || tAnchor("untitled"),
})) ?? [],
[notes, tAnchor],
);
return (
<Select
label={tWidget("label")}
description={options.withDescription ? tWidget("description") : undefined}
placeholder={integrationId ? t("common.select.placeholder") : tAnchor("integrationRequired")}
nothingFoundMessage={integrationId ? tAnchor("noNotes") : tAnchor("integrationRequired")}
searchable
searchValue={search}
onSearchChange={setSearch}
data={noteOptions}
leftSection={isPending && integrationId ? <Loader size={16} /> : undefined}
disabled={!integrationId}
{...form.getInputProps(`options.${property}`)}
/>
);
};
@@ -0,0 +1,115 @@
.homarr-anchor-quill {
display: flex;
flex-direction: column;
height: 100%;
}
.homarr-anchor-quill .ql-toolbar.ql-snow,
.homarr-anchor-quill .ql-container.ql-snow {
border: 0;
}
.homarr-anchor-quill .ql-toolbar.ql-snow {
background: transparent;
border-radius: 0;
}
.homarr-anchor-quill .ql-container.ql-snow {
background: transparent;
border-radius: 0;
flex: 1;
display: flex;
flex-direction: column;
}
.homarr-anchor-quill .ql-editor {
min-height: 160px;
flex: 1;
padding: 0;
color: var(--mantine-color-text);
font-size: var(--mantine-font-size-sm, 0.95rem);
line-height: 1.6;
}
.homarr-anchor-quill .ql-editor.ql-blank::before {
color: var(--mantine-color-dimmed);
}
.homarr-anchor-quill .ql-editor ol,
.homarr-anchor-quill .ql-editor ul {
padding-left: 1.5rem;
}
.homarr-anchor-quill .ql-editor li {
margin: 0.25rem 0;
}
.homarr-anchor-quill .ql-editor li[data-list="unchecked"],
.homarr-anchor-quill .ql-editor li[data-list="checked"] {
padding-left: 28px !important;
list-style: none;
position: relative;
}
.homarr-anchor-quill .ql-editor li[data-list="checked"] > .ql-ui,
.homarr-anchor-quill .ql-editor li[data-list="unchecked"] > .ql-ui {
position: absolute;
left: 0;
top: 0.35em;
width: 18px !important;
height: 18px !important;
border-radius: 5px;
box-sizing: border-box;
transition: all 150ms ease;
background: transparent;
padding: 0 !important;
margin: 0 !important;
}
.homarr-anchor-quill .ql-editor li[data-list="checked"] > .ql-ui::before,
.homarr-anchor-quill .ql-editor li[data-list="unchecked"] > .ql-ui::before {
content: "" !important;
display: none !important;
}
.homarr-anchor-quill .ql-editor li[data-list="unchecked"] > .ql-ui {
border: 2px solid var(--mantine-color-dimmed);
opacity: 0.7;
}
.homarr-anchor-quill .ql-editor li[data-list="unchecked"]:hover > .ql-ui {
border-color: var(--mantine-primary-color-filled);
opacity: 1;
}
.homarr-anchor-quill .ql-editor li[data-list="checked"] > .ql-ui {
border: 2px solid var(--mantine-primary-color-filled);
background: var(--mantine-primary-color-filled);
}
.homarr-anchor-quill .ql-editor li[data-list="checked"] > .ql-ui::after {
content: "";
display: block;
position: absolute;
left: 50%;
top: 45%;
width: 5px;
height: 9px;
border: solid var(--mantine-color-white, #fff);
border-width: 0 2px 2px 0;
transform: translate(-50%, -50%) rotate(45deg);
}
.homarr-anchor-quill .ql-editor li[data-list="checked"] {
color: var(--mantine-color-dimmed);
text-decoration: line-through;
text-decoration-color: var(--mantine-color-dimmed);
}
.homarr-anchor-quill--readonly .ql-toolbar.ql-snow {
display: none;
}
.homarr-anchor-quill--readonly .ql-container.ql-snow {
border-radius: 0;
}
@@ -0,0 +1,320 @@
"use client";
import { startTransition, useCallback, useEffect, useMemo, useState } from "react";
import type { ComponentProps } from "react";
import dynamic from "next/dynamic";
import { Button, Center, Group, Stack, Text, TextInput } from "@mantine/core";
import { Quill } from "react-quill-new";
import type { DeltaStatic } from "react-quill-new";
import type ReactQuillComponent from "react-quill-new";
import { z } from "zod/v4";
import { clientApi } from "@homarr/api/client";
import { useTimeAgo } from "@homarr/common";
import type { AnchorNotePermission } from "@homarr/integrations";
import { useScopedI18n } from "@homarr/translation/client";
import type { WidgetComponentProps } from "../definition";
import "react-quill-new/dist/quill.snow.css";
import "./anchor-note.css";
type ReactQuillProps = ComponentProps<typeof ReactQuillComponent>;
type ReactQuillOnChange = NonNullable<ReactQuillProps["onChange"]>;
const ReactQuill = dynamic(() => import("react-quill-new"), { ssr: false });
const quillDeltaOperationSchema = z.object({
insert: z.unknown().optional(),
attributes: z.record(z.string(), z.unknown()).optional(),
});
const quillDeltaSchema = z.object({
ops: z.array(quillDeltaOperationSchema),
});
type QuillDelta = z.infer<typeof quillDeltaSchema>;
const DeltaConstructor = Quill.import("delta") as new (
ops?: QuillDelta["ops"] | { ops: QuillDelta["ops"] },
) => DeltaStatic;
const quillModules = {
toolbar: [
["bold", "italic", "underline", "strike"],
[{ header: [1, 2, 3, 4, false] }],
[{ align: [] }],
[{ list: "ordered" }, { list: "bullet" }, { list: "check" }],
[{ indent: "-1" }, { indent: "+1" }],
["blockquote", "code-block"],
["link"],
["clean"],
],
history: {
delay: 1000,
maxStack: 200,
userOnly: true,
},
};
const readOnlyModules = {
toolbar: false,
};
const quillFormats = [
"bold",
"italic",
"underline",
"strike",
"header",
"align",
"list",
"indent",
"blockquote",
"code-block",
"link",
];
const emptyDelta = (): DeltaStatic => new DeltaConstructor([{ insert: "\n" }]);
const toPlainTextDelta = (value: string): DeltaStatic => {
const normalized = value.endsWith("\n") ? value : `${value}\n`;
return new DeltaConstructor([{ insert: normalized }]);
};
const parseStoredContent = (content?: string | null): DeltaStatic => {
if (!content) return emptyDelta();
try {
const parsedDelta = quillDeltaSchema.safeParse(JSON.parse(content));
if (parsedDelta.success) {
return new DeltaConstructor(parsedDelta.data.ops);
}
} catch {
return toPlainTextDelta(content);
}
return toPlainTextDelta(content);
};
const stringifyDelta = (delta: unknown): string => {
const parsedDelta = quillDeltaSchema.safeParse(delta);
if (parsedDelta.success) {
return JSON.stringify(parsedDelta.data);
}
return JSON.stringify(emptyDelta());
};
const canEditPermission = (permission: AnchorNotePermission) => {
return permission === "owner" || permission === "editor";
};
const isForbiddenError = (error: unknown): boolean => {
if (typeof error !== "object" || error === null) return false;
const data = (error as { data?: unknown }).data;
if (typeof data !== "object" || data === null) return false;
return (data as { code?: unknown }).code === "FORBIDDEN";
};
export default function AnchorNoteWidget({ options, integrationIds }: WidgetComponentProps<"anchorNote">) {
const t = useScopedI18n("widget.anchorNote");
const noteId = options.noteId.trim();
if (!noteId) {
return (
<Center h="100%">
<Text c="dimmed">{t("empty")}</Text>
</Center>
);
}
// It will always have at least one integration as otherwise the NoIntegrationSelectedError would be thrown in item-content.tsx
// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
const integrationId = integrationIds[0]!;
return <AnchorNoteWidgetContent options={options} integrationId={integrationId} noteId={noteId} />;
}
interface AnchorNoteWidgetContentProps {
options: WidgetComponentProps<"anchorNote">["options"];
integrationId: string;
noteId: string;
}
const AnchorNoteWidgetContent = ({ options, integrationId, noteId }: AnchorNoteWidgetContentProps) => {
const t = useScopedI18n("widget.anchorNote");
const [note, { refetch }] = clientApi.widget.anchorNotes.getNote.useSuspenseQuery(
{
integrationId,
noteId,
},
{
refetchOnMount: false,
refetchOnWindowFocus: false,
refetchOnReconnect: false,
retry: false,
},
);
const { mutateAsync: updateNoteAsync, isPending: isUpdating } = clientApi.widget.anchorNotes.updateNote.useMutation();
const [isEditing, setIsEditing] = useState(false);
const [draftTitle, setDraftTitle] = useState(note.title);
const [draftContent, setDraftContent] = useState(note.content ?? "");
const [saveError, setSaveError] = useState<string | null>(null);
useEffect(() => {
if (isEditing) return;
startTransition(() => {
setDraftTitle(note.title);
setDraftContent(note.content ?? "");
});
}, [isEditing, note.content, note.title]);
const canEdit = canEditPermission(note.permission);
const isViewer = note.permission === "viewer";
const updatedAt = useMemo(() => new Date(note.updatedAt), [note.updatedAt]);
const updatedAtRelative = useTimeAgo(updatedAt, 30000);
const hasChanges = useMemo(() => {
const normalizedTitle = draftTitle.trim() || note.title;
return normalizedTitle !== note.title || draftContent !== (note.content ?? "");
}, [draftContent, draftTitle, note.content, note.title]);
const editorValue = useMemo(() => parseStoredContent(draftContent), [draftContent]);
const readOnlyValue = useMemo(() => parseStoredContent(note.content), [note.content]);
const handleEditorChange = useCallback<ReactQuillOnChange>(
(_html, _delta, source, editor) => {
if (!isEditing || source !== "user") return;
const next = stringifyDelta(editor.getContents());
setDraftContent(next);
},
[isEditing],
);
const handleEdit = useCallback(() => {
if (!canEdit) return;
startTransition(() => {
setDraftTitle(note.title);
setDraftContent(note.content ?? "");
setSaveError(null);
setIsEditing(true);
});
}, [canEdit, note.content, note.title]);
const handleCancel = useCallback(() => {
startTransition(() => {
setDraftTitle(note.title);
setDraftContent(note.content ?? "");
setSaveError(null);
setIsEditing(false);
});
}, [note.content, note.title]);
const handleSave = useCallback(async () => {
if (!canEdit) return;
const normalizedTitle = draftTitle.trim() || note.title || t("untitled");
if (!hasChanges) {
startTransition(() => {
setSaveError(null);
setIsEditing(false);
});
return;
}
await updateNoteAsync(
{
integrationId,
noteId,
title: normalizedTitle,
content: draftContent,
},
{
onSuccess() {
void (async () => {
await refetch();
startTransition(() => {
setSaveError(null);
setIsEditing(false);
});
})();
},
onError(error) {
if (isForbiddenError(error)) {
void (async () => {
await refetch();
startTransition(() => {
setSaveError(t("saveForbidden"));
setIsEditing(false);
});
})();
return;
}
startTransition(() => {
setSaveError(t("saveFailed"));
});
},
},
);
}, [canEdit, draftContent, draftTitle, hasChanges, integrationId, note.title, noteId, refetch, t, updateNoteAsync]);
return (
<Stack h="100%" gap="xs" p="sm">
<Group justify="space-between" align="flex-start">
<Stack gap={2} style={{ flex: 1 }}>
{isEditing ? (
<TextInput value={draftTitle} onChange={(event) => setDraftTitle(event.currentTarget.value)} size="sm" />
) : (
options.showTitle && <Text fw={600}>{note.title || t("untitled")}</Text>
)}
{!isEditing && options.showUpdatedAt && (
<Text size="xs" c="dimmed">
{t("updatedAt", { date: updatedAtRelative })}
</Text>
)}
{!isEditing && isViewer && (
<Text size="xs" c="dimmed">
{t("readOnlyViewer")}
</Text>
)}
{saveError && (
<Text size="xs" c="red">
{saveError}
</Text>
)}
</Stack>
<Group gap="xs">
{isEditing ? (
<>
<Button size="xs" onClick={handleSave} loading={isUpdating} disabled={!hasChanges || !canEdit}>
{t("save")}
</Button>
<Button size="xs" variant="subtle" onClick={handleCancel} disabled={isUpdating}>
{t("cancel")}
</Button>
</>
) : (
<Button size="xs" variant="light" onClick={handleEdit} disabled={!canEdit || isUpdating}>
{t("edit")}
</Button>
)}
</Group>
</Group>
<div className={`homarr-anchor-quill${isEditing ? "" : " homarr-anchor-quill--readonly"}`} style={{ flex: 1 }}>
<ReactQuill
theme="snow"
readOnly={!isEditing}
value={isEditing ? editorValue : readOnlyValue}
onChange={handleEditorChange}
modules={isEditing ? quillModules : readOnlyModules}
formats={quillFormats}
placeholder={t("emptyContent")}
/>
</div>
</Stack>
);
};
+20
View File
@@ -0,0 +1,20 @@
import { IconNotes } from "@tabler/icons-react";
import { createWidgetDefinition } from "../definition";
import { optionsBuilder } from "../options";
export const { definition, componentLoader } = createWidgetDefinition("anchorNote", {
icon: IconNotes,
supportedIntegrations: ["anchor"],
createOptions() {
return optionsBuilder.from((factory) => ({
noteId: factory.anchorNote(),
showTitle: factory.switch({
defaultValue: true,
}),
showUpdatedAt: factory.switch({
defaultValue: true,
}),
}));
},
}).withDynamicImport(() => import("./component"));
+2
View File
@@ -7,6 +7,7 @@ import { objectEntries } from "@homarr/common";
import type { IntegrationKind, WidgetKind } from "@homarr/definitions";
import type { SettingsContextProps } from "@homarr/settings/creator";
import * as anchorNote from "./anchor-note";
import * as app from "./app";
import * as bookmarks from "./bookmarks";
import * as calendar from "./calendar";
@@ -55,6 +56,7 @@ export const widgetImports = {
clock,
weather,
app,
anchorNote,
notebook,
iframe,
video,
+7
View File
@@ -19,6 +19,8 @@ interface TextInput extends CommonInput<string> {
validate?: z.ZodType<string>;
}
type AnchorNoteInput = CommonInput<string>;
interface MultiSelectInput<TOptions extends SelectOption[]> extends CommonInput<
inferSelectOptionValue<TOptions[number]>[]
> {
@@ -86,6 +88,11 @@ const optionsFactory = {
withDescription: input?.withDescription ?? false,
validate: input?.validate,
}),
anchorNote: (input?: AnchorNoteInput) => ({
type: "anchorNote" as const,
defaultValue: input?.defaultValue ?? "",
withDescription: input?.withDescription ?? false,
}),
multiSelect: <const TOptions extends SelectOption[]>(input: MultiSelectInput<TOptions>) => ({
type: "multiSelect" as const,
defaultValue: input.defaultValue ?? [],