From c86fa81e477cb03a7ddc4beb22578b78f6a507db Mon Sep 17 00:00:00 2001 From: Spencer Fasulo <92827970+spfncer@users.noreply.github.com> Date: Thu, 26 Sep 2024 21:41:22 -0400 Subject: [PATCH] docs(web): JSDoc comments for svelte actions (#12963) * Web: JSDoc comments for Actions * Remove comment --- web/src/lib/actions/click-outside.ts | 6 ++++++ web/src/lib/actions/focus-outside.ts | 5 +++++ web/src/lib/actions/focus.ts | 1 + web/src/lib/actions/intersection-observer.ts | 8 ++++++++ web/src/lib/actions/list-navigation.ts | 5 +++++ web/src/lib/actions/shortcut.ts | 7 +++++++ web/src/lib/actions/thumbhash.ts | 5 +++++ 7 files changed, 37 insertions(+) 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 = (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 = { 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 = ( node: T, option: ShortcutOptions, @@ -47,6 +53,7 @@ export const shortcut = ( }; }; +/** Binds multiple keyboard shortcuts to node */ export const shortcuts = ( node: T, options: ShortcutOptions[], 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) {