Skip to content

High performance self-hosted photo and video management solution.

docs(web): JSDoc comments for svelte actions (#12963)

Spencer Fasuloc86fa81e477c
diff --git a/web/src/lib/actions/click-outside.ts b/web/src/lib/actions/click-outside.ts
index bbcb0c405b..1a421f1f56 100644
--- a/web/src/lib/actions/click-outside.ts
+++ b/web/src/lib/actions/click-outside.ts
@@ -6,6 +6,12 @@ interface Options {
onEscape?: () => void;
}
+/**
+ * Calls a function when a click occurs outside of the element, or when the escape key is pressed.
+ * @param node
+ * @param options Object containing onOutclick and onEscape functions
+ * @returns
+ */
export function clickOutside(node: HTMLElement, options: Options = {}): ActionReturn {
const { onOutclick, onEscape } = options;
diff --git a/web/src/lib/actions/focus-outside.ts b/web/src/lib/actions/focus-outside.ts
index 2266ea8f0f..c302e33d4c 100644
--- a/web/src/lib/actions/focus-outside.ts
+++ b/web/src/lib/actions/focus-outside.ts
@@ -2,6 +2,11 @@ interface Options {
onFocusOut?: (event: FocusEvent) => void;
}
+/**
+ * Calls a function when focus leaves the element.
+ * @param node
+ * @param options Object containing onFocusOut function
+ */
export function focusOutside(node: HTMLElement, options: Options = {}) {
const { onFocusOut } = options;
diff --git a/web/src/lib/actions/focus.ts b/web/src/lib/actions/focus.ts
index 81185625f7..3b6049f247 100644
--- a/web/src/lib/actions/focus.ts
+++ b/web/src/lib/actions/focus.ts
@@ -1,3 +1,4 @@
+/** Focus the given element when it is mounted. */
export const initInput = (element: HTMLInputElement) => {
element.focus();
};
diff --git a/web/src/lib/actions/intersection-observer.ts b/web/src/lib/actions/intersection-observer.ts
index 700ae0c373..edbc07e5c1 100644
--- a/web/src/lib/actions/intersection-observer.ts
+++ b/web/src/lib/actions/intersection-observer.ts
@@ -13,7 +13,9 @@ type OnIntersectCallback = (entryOrElement: IntersectionObserverEntry | HTMLElem
type OnSeparateCallback = (element: HTMLElement) => unknown;
type IntersectionObserverActionProperties = {
key?: string;
+ /** Function to execute when the element leaves the viewport */
onSeparate?: OnSeparateCallback;
+ /** Function to execute when the element enters the viewport */
onIntersect?: OnIntersectCallback;
root?: Element | Document | null;
@@ -112,6 +114,12 @@ function _intersectionObserver(
};
}
+/**
+ * Monitors an element's visibility in the viewport and calls functions when it enters or leaves (based on a threshold).
+ * @param element
+ * @param properties One or multiple configurations for the IntersectionObserver(s)
+ * @returns
+ */
export function intersectionObserver(
element: HTMLElement,
properties: IntersectionObserverActionProperties | IntersectionObserverActionProperties[],
diff --git a/web/src/lib/actions/list-navigation.ts b/web/src/lib/actions/list-navigation.ts
index b981f67521..8f8ed62ed0 100644
--- a/web/src/lib/actions/list-navigation.ts
+++ b/web/src/lib/actions/list-navigation.ts
@@ -1,6 +1,11 @@
import { shortcuts } from '$lib/actions/shortcut';
import type { Action } from 'svelte/action';
+/**
+ * Enables keyboard navigation (up and down arrows) for a list of elements.
+ * @param node Element which listens for keyboard events
+ * @param container Element containing the list of elements
+ */
export const listNavigation: Action<HTMLElement, HTMLElement> = (node, container: HTMLElement) => {
const moveFocus = (direction: 'up' | 'down') => {
const children = Array.from(container?.children);
diff --git a/web/src/lib/actions/shortcut.ts b/web/src/lib/actions/shortcut.ts
index df155ea821..6348257c40 100644
--- a/web/src/lib/actions/shortcut.ts
+++ b/web/src/lib/actions/shortcut.ts
@@ -10,11 +10,16 @@ export type Shortcut = {
export type ShortcutOptions<T = HTMLElement> = {
shortcut: Shortcut;
+ /** If true, the event handler will not execute if the event comes from an input field */
ignoreInputFields?: boolean;
onShortcut: (event: KeyboardEvent & { currentTarget: T }) => unknown;
preventDefault?: boolean;
};
+/** Determines whether an event should be ignored. The event will be ignored if:
+ * - The element dispatching the event is not the same as the element which the event listener is attached to
+ * - The element dispatching the event is an input field
+ */
export const shouldIgnoreEvent = (event: KeyboardEvent | ClipboardEvent): boolean => {
if (event.target === event.currentTarget) {
return false;
@@ -33,6 +38,7 @@ export const matchesShortcut = (event: KeyboardEvent, shortcut: Shortcut) => {
);
};
+/** Bind a single keyboard shortcut to node. */
export const shortcut = <T extends HTMLElement>(
node: T,
option: ShortcutOptions<T>,
@@ -47,6 +53,7 @@ export const shortcut = <T extends HTMLElement>(
};
};
+/** Binds multiple keyboard shortcuts to node */
export const shortcuts = <T extends HTMLElement>(
node: T,
options: ShortcutOptions<T>[],
diff --git a/web/src/lib/actions/thumbhash.ts b/web/src/lib/actions/thumbhash.ts
index ab9d28ffc9..e49f04dbee 100644
--- a/web/src/lib/actions/thumbhash.ts
+++ b/web/src/lib/actions/thumbhash.ts
@@ -1,6 +1,11 @@
import { decodeBase64 } from '$lib/utils';
import { thumbHashToRGBA } from 'thumbhash';
+/**
+ * Renders a thumbnail onto a canvas from a base64 encoded hash.
+ * @param canvas
+ * @param param1 object containing the base64 encoded hash (base64Thumbhash: yourString)
+ */
export function thumbhash(canvas: HTMLCanvasElement, { base64ThumbHash }: { base64ThumbHash: string }) {
const ctx = canvas.getContext('2d');
if (ctx) {