Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
import "./SiblingNavigator.css";
import type { RefObject } from "preact";
import { useEffect, useRef, useState } from "preact/hooks";
import type NoteContext from "../../components/note_context";
import type FNote from "../../entities/fnote";
import froca from "../../services/froca";
import { t } from "../../services/i18n";
import type { ViewScope } from "../../services/link";
import type LoadResults from "../../services/load_results";
import { useTriliumEvent } from "./hooks";
import OverlayControlGroup, { OverlayControlButton } from "./OverlayControlGroup";
import { codeToSiblingDirection, getParentFromNotePath, getSiblingNavigation, isInteractiveTarget, isTextEntryTarget, sameRoleAttachments } from "./sibling_navigation";
const NO_KEYS: readonly string[] = [];
interface SiblingNavigatorProps {
note?: FNote;
noteContext?: NoteContext;
/** When it carries an `attachmentId`, navigation operates over the note's attachments instead of its siblings. */
viewScope?: ViewScope;
/** For note siblings, match this type; defaults to the current note's type. (Ignored for attachments.) */
siblingType?: string;
/** i18n translation key (resolved via `t()`) for the previous-button tooltip; receives the target's title as `{{title}}`. E.g. `"image_navigation.previous"`. */
previousTooltipI18nKey: string;
/** i18n translation key (resolved via `t()`) for the next-button tooltip; receives the target's title as `{{title}}`. E.g. `"image_navigation.next"`. */
nextTooltipI18nKey: string;
/**
* Optional element to scope keyboard navigation to: keys act only while focus is inside it. When
* omitted, navigation is scoped to the active tab/pane instead, so it works without any wiring.
*/
keyboardTarget?: RefObject<HTMLElement | null>;
/** Extra `KeyboardEvent.code`s that trigger previous/next, on top of PageUp/PageDown. */
extraPreviousKeys?: readonly string[];
extraNextKeys?: readonly string[];
}
export interface SiblingNavigationState {
index: number;
total: number;
previousId: string;
nextId: string;
previousTitle: string;
nextTitle: string;
navigatePrevious: () => void;
navigateNext: () => void;
navigateFirst: () => void;
navigateLast: () => void;
}
/**
* The iterator behind sibling navigation: where the ordered siblings come from, which one is current,
* how to move to one, and which entity changes should refresh the list. Swapping it switches navigation
* between notes and attachments — see {@link noteSiblingProvider} / {@link attachmentSiblingProvider}.
*/
export interface SiblingNavigationProvider {
/** Id of the item currently shown (a noteId or attachmentId); undefined when there is nothing to navigate. */
currentId: string | undefined;
/** Changes whenever the loaded collection or current item changes; used as the load effect's key. */
depsKey: string;
/** Loads the ordered siblings (including the current item) as `{ id, title }`. */
loadSiblings(): Promise<{ id: string; title: string }[]>;
/** Navigates the current tab to the sibling with the given id. */
navigateTo(id: string): void;
/** Whether an `entitiesReloaded` event touches this collection (given the currently-loaded ids). */
shouldRefresh(loadResults: LoadResults, currentSiblingIds: string[]): boolean;
}
/**
* Floating previous/next navigation between a note's same-type siblings — or, when shown over a single
* attachment, the note's same-role attachments — with a "<index>/<total>" indicator and tooltips naming
* the target. The iterator is chosen automatically from the view (no caller wiring). Tooltip text comes
* from the caller-provided i18n keys. Renders nothing when there is no sibling to move between.
*/
export default function SiblingNavigator({ note, noteContext, viewScope, siblingType, previousTooltipI18nKey, nextTooltipI18nKey, keyboardTarget, extraPreviousKeys = NO_KEYS, extraNextKeys = NO_KEYS }: SiblingNavigatorProps) {
// Viewing a single attachment → cycle the note's attachments; otherwise its note siblings.
const provider = viewScope?.attachmentId
? attachmentSiblingProvider(note, noteContext, viewScope)
: noteSiblingProvider(note, noteContext, { type: siblingType });
const navigation = useSiblingNavigation(provider);
useSiblingKeyboard(navigation, noteContext, keyboardTarget, extraPreviousKeys, extraNextKeys);
if (!navigation) return null;
return (
<OverlayControlGroup className="sibling-navigator" placement="bottom-start">
<OverlayControlButton
title={t(previousTooltipI18nKey, { title: navigation.previousTitle })}
icon="bx-chevron-left"
onClick={() => navigation.navigatePrevious()}
/>
<OverlayControlButton
text={`${navigation.index}/${navigation.total}`}
className="sibling-navigator-index"
disabled
/>
<OverlayControlButton
title={t(nextTooltipI18nKey, { title: navigation.nextTitle })}
icon="bx-chevron-right"
onClick={() => navigation.navigateNext()}
/>
</OverlayControlGroup>
);
}
/**
* Generic sibling-navigation engine over a {@link SiblingNavigationProvider}: loads the siblings, keeps
* them fresh across entity/froca reloads, and exposes the current index/total plus prev/next/first/last
* navigation. Returns null when there is nothing to navigate.
*/
export function useSiblingNavigation(provider: SiblingNavigationProvider): SiblingNavigationState | null {
const [ siblings, setSiblings ] = useState<{ id: string; title: string }[]>([]);
const [ refreshCounter, setRefreshCounter ] = useState(0);
const providerRef = useRef(provider);
providerRef.current = provider;
const { currentId, depsKey } = provider;
useEffect(() => {
let active = true;
providerRef.current.loadSiblings()
.then((loaded) => { if (active) setSiblings(loaded); })
.catch(() => { if (active) setSiblings([]); });
return () => { active = false; };
}, [ depsKey, refreshCounter ]);
useTriliumEvent("entitiesReloaded", ({ loadResults }) => {
if (providerRef.current.shouldRefresh(loadResults, siblings.map((sibling) => sibling.id))) {
setRefreshCounter((counter) => counter + 1);
}
});
// froca replaces every cached entity on a full reload (e.g. a protected-session unlock), refreshing titles.
useTriliumEvent("frocaReloaded", () => setRefreshCounter((counter) => counter + 1));
if (!currentId) return null;
const navigation = getSiblingNavigation(siblings.map((sibling) => sibling.id), currentId);
if (!navigation) return null;
const titleOf = (id: string) => siblings.find((sibling) => sibling.id === id)?.title ?? "";
const navigateTo = (id: string) => providerRef.current.navigateTo(id);
return {
index: navigation.index,
total: navigation.total,
previousId: navigation.previous,
nextId: navigation.next,
previousTitle: titleOf(navigation.previous),
nextTitle: titleOf(navigation.next),
navigatePrevious: () => navigateTo(navigation.previous),
navigateNext: () => navigateTo(navigation.next),
navigateFirst: () => navigateTo(navigation.first),
navigateLast: () => navigateTo(navigation.last)
};
}
/** Filter for note siblings: a note type (defaults to the current note's), optionally narrowed by a mime prefix. */
export interface NoteSiblingFilter {
type?: string;
mimePrefix?: string;
}
/** Iterator over the current note's matching siblings within the parent of the current tab (clone-aware). */
export function noteSiblingProvider(note: FNote | undefined, noteContext: NoteContext | undefined, filter: NoteSiblingFilter = {}): SiblingNavigationProvider {
const notePath = noteContext?.notePath;
const type = filter.type ?? note?.type;
const { mimePrefix } = filter;
const parent = getParentFromNotePath(notePath);
const matches = (sibling: FNote) => sibling.type === type && (!mimePrefix || !!sibling.mime?.startsWith(mimePrefix));
return {
currentId: note?.noteId,
depsKey: `note:${parent?.parentPath ?? ""}:${type ?? ""}:${mimePrefix ?? ""}`,
loadSiblings: async () => {
if (!parent || !type) return [];
const parentNote = await froca.getNote(parent.parentNoteId);
const children = (await parentNote?.getChildNotes()) ?? [];
return children.filter(matches).map((child) => ({ id: child.noteId, title: child.title }));
},
navigateTo: (id) => { if (parent) void noteContext?.setNote(`${parent.parentPath}/${id}`); },
shouldRefresh: (loadResults, currentSiblingIds) => {
if (!parent) return false;
const branchesChanged = loadResults.getBranchRows().some((branch) => branch.parentNoteId === parent.parentNoteId);
const siblingChanged = loadResults.getNoteIds().some((noteId) => currentSiblingIds.includes(noteId));
return branchesChanged || siblingChanged;
}
};
}
/**
* Iterator over the note's same-role attachments, with the role taken from the currently-shown attachment.
* `mimePrefix` narrows it further, for a host that can only show one kind — a media player cycles the
* owner's `audio/` attachments rather than every `file`-role one.
*/
export function attachmentSiblingProvider(note: FNote | undefined, noteContext: NoteContext | undefined, viewScope: ViewScope, filter: { mimePrefix?: string } = {}): SiblingNavigationProvider {
const notePath = noteContext?.notePath;
const attachmentId = viewScope.attachmentId;
const { mimePrefix } = filter;
// Key on the role rather than the id, so cycling same-role attachments doesn't re-fetch the list.
const role = note?.attachments?.find((attachment) => attachment.attachmentId === attachmentId)?.role;
return {
currentId: attachmentId,
depsKey: `attachment:${note?.noteId ?? ""}:${role ?? attachmentId ?? ""}:${mimePrefix ?? ""}`,
loadSiblings: async () => {
if (!note) return [];
return sameRoleAttachments(Array.from(await note.getAttachments()), attachmentId, mimePrefix);
},
navigateTo: (id) => { if (notePath) void noteContext?.setNote(notePath, { viewScope: { ...viewScope, attachmentId: id } }); },
shouldRefresh: (loadResults) => !!note && loadResults.getAttachmentRows().some((row) => row.ownerId === note.noteId)
};
}
/**
* Drives sibling navigation from the keyboard. A single document-level listener (stable across the
* viewer remounting on each navigation) maps PageUp/PageDown — Home/End too unless `edgeKeys` is false
* (media players reserve those for seeking) — plus any caller-provided extra keys, to previous/next. It
* acts only when a `keyboardTarget` (if given) holds focus, otherwise when the note context is the
* active tab/pane, and never while the user is typing in a text field.
*/
export function useSiblingKeyboard(
navigation: SiblingNavigationState | null,
noteContext: NoteContext | undefined,
keyboardTarget: RefObject<HTMLElement | null> | undefined,
extraPreviousKeys: readonly string[],
extraNextKeys: readonly string[],
options: { edgeKeys?: boolean } = {}
) {
const { edgeKeys = true } = options;
// Read the freshest values from inside the listener without re-attaching it on every change.
const stateRef = useRef({ navigation, noteContext, keyboardTarget, extraPreviousKeys, extraNextKeys, edgeKeys });
stateRef.current = { navigation, noteContext, keyboardTarget, extraPreviousKeys, extraNextKeys, edgeKeys };
useEffect(() => {
const onKeyDown = (e: KeyboardEvent) => {
if (e.defaultPrevented || e.ctrlKey || e.metaKey || e.altKey || e.shiftKey) return;
const { navigation, noteContext, keyboardTarget, extraPreviousKeys, extraNextKeys, edgeKeys } = stateRef.current;
const target = e.target as Element | null;
if (!navigation || isTextEntryTarget(target)) return;
// Don't hijack Space from a focused button or other interactive control — it activates them.
if (e.code === "Space" && isInteractiveTarget(target)) return;
if (keyboardTarget) {
if (!keyboardTarget.current?.contains(document.activeElement)) return;
} else if (noteContext && !noteContext.isActive()) {
return;
}
const direction = codeToSiblingDirection(e.code, extraPreviousKeys, extraNextKeys, edgeKeys);
if (!direction) return;
e.preventDefault();
if (direction === "previous") navigation.navigatePrevious();
else if (direction === "next") navigation.navigateNext();
else if (direction === "first") navigation.navigateFirst();
else navigation.navigateLast();
};
document.addEventListener("keydown", onKeyDown);
return () => document.removeEventListener("keydown", onKeyDown);
}, []);
}