docs(web): JSDoc comments for svelte actions

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;
 

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;
 

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();
 };

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[],

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);

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>[],

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) {