@stonecrop/utilities 0.2.24 → 0.2.25

package/dist/composables/keyboard.js

@@ -0,0 +1,464 @@
+import { onBeforeUnmount, onMounted, ref, watch } from 'vue';
+import { useFocusWithin } from '@vueuse/core';
+import { useElementVisibility } from '@/composables/visibility';
+// helper functions
+const isVisible = (element) => {
+    let isVisible = useElementVisibility(element).value;
+    isVisible = isVisible && element.offsetHeight > 0;
+    return isVisible;
+};
+const isFocusable = (element) => {
+    return element.tabIndex >= 0;
+};
+// navigation functions
+const getUpCell = (event) => {
+    const $target = event.target;
+    return _getUpCell($target);
+};
+const _getUpCell = (element) => {
+    let $upCell;
+    if (element instanceof HTMLTableCellElement) {
+        const $prevRow = element.parentElement?.previousElementSibling;
+        if ($prevRow) {
+            const $prevRowCells = Array.from($prevRow.children);
+            const $prevCell = $prevRowCells[element.cellIndex];
+            if ($prevCell) {
+                $upCell = $prevCell;
+            }
+        }
+    }
+    else if (element instanceof HTMLTableRowElement) {
+        const $prevRow = element.previousElementSibling;
+        if ($prevRow) {
+            $upCell = $prevRow;
+        }
+    }
+    else {
+        // handle other contexts
+    }
+    if ($upCell && (!isFocusable($upCell) || !isVisible($upCell))) {
+        return _getUpCell($upCell);
+    }
+    return $upCell;
+};
+const getTopCell = (event) => {
+    const $target = event.target;
+    let $topCell;
+    if ($target instanceof HTMLTableCellElement) {
+        const $table = $target.parentElement?.parentElement;
+        if ($table) {
+            const $firstRow = $table.firstElementChild;
+            const $navCell = $firstRow.children[$target.cellIndex];
+            if ($navCell) {
+                $topCell = $navCell;
+            }
+        }
+    }
+    else if ($target instanceof HTMLTableRowElement) {
+        const $table = $target.parentElement;
+        if ($table) {
+            const $firstRow = $table.firstElementChild;
+            if ($firstRow) {
+                $topCell = $firstRow;
+            }
+        }
+    }
+    else {
+        // handle other contexts
+    }
+    if ($topCell && (!isFocusable($topCell) || !isVisible($topCell))) {
+        return _getDownCell($topCell);
+    }
+    return $topCell;
+};
+const getDownCell = (event) => {
+    const $target = event.target;
+    return _getDownCell($target);
+};
+const _getDownCell = (element) => {
+    let $downCell;
+    if (element instanceof HTMLTableCellElement) {
+        const $nextRow = element.parentElement?.nextElementSibling;
+        if ($nextRow) {
+            const $nextRowCells = Array.from($nextRow.children);
+            const $nextCell = $nextRowCells[element.cellIndex];
+            if ($nextCell) {
+                $downCell = $nextCell;
+            }
+        }
+    }
+    else if (element instanceof HTMLTableRowElement) {
+        const $nextRow = element.nextElementSibling;
+        if ($nextRow) {
+            $downCell = $nextRow;
+        }
+    }
+    else {
+        // handle other contexts
+    }
+    if ($downCell && (!isFocusable($downCell) || !isVisible($downCell))) {
+        return _getDownCell($downCell);
+    }
+    return $downCell;
+};
+const getBottomCell = (event) => {
+    const $target = event.target;
+    let $bottomCell;
+    if ($target instanceof HTMLTableCellElement) {
+        const $table = $target.parentElement?.parentElement;
+        if ($table) {
+            const $lastRow = $table.lastElementChild;
+            const $navCell = $lastRow.children[$target.cellIndex];
+            if ($navCell) {
+                $bottomCell = $navCell;
+            }
+        }
+    }
+    else if ($target instanceof HTMLTableRowElement) {
+        const $table = $target.parentElement;
+        if ($table) {
+            const $lastRow = $table.lastElementChild;
+            if ($lastRow) {
+                $bottomCell = $lastRow;
+            }
+        }
+    }
+    else {
+        // handle other contexts
+    }
+    if ($bottomCell && (!isFocusable($bottomCell) || !isVisible($bottomCell))) {
+        return _getUpCell($bottomCell);
+    }
+    return $bottomCell;
+};
+const getPrevCell = (event) => {
+    const $target = event.target;
+    return _getPrevCell($target);
+};
+const _getPrevCell = (element) => {
+    let $prevCell;
+    if (element.previousElementSibling) {
+        $prevCell = element.previousElementSibling;
+    }
+    else {
+        const $prevRow = element.parentElement?.previousElementSibling;
+        $prevCell = $prevRow?.lastElementChild;
+    }
+    if ($prevCell && (!isFocusable($prevCell) || !isVisible($prevCell))) {
+        return _getPrevCell($prevCell);
+    }
+    return $prevCell;
+};
+const getNextCell = (event) => {
+    const $target = event.target;
+    return _getNextCell($target);
+};
+const _getNextCell = (element) => {
+    let $nextCell;
+    if (element.nextElementSibling) {
+        $nextCell = element.nextElementSibling;
+    }
+    else {
+        const $nextRow = element.parentElement?.nextElementSibling;
+        $nextCell = $nextRow?.firstElementChild;
+    }
+    if ($nextCell && (!isFocusable($nextCell) || !isVisible($nextCell))) {
+        return _getNextCell($nextCell);
+    }
+    return $nextCell;
+};
+const getFirstCell = (event) => {
+    const $target = event.target;
+    const $parent = $target.parentElement;
+    const $firstCell = $parent.firstElementChild;
+    if ($firstCell && (!isFocusable($firstCell) || !isVisible($firstCell))) {
+        return _getNextCell($firstCell);
+    }
+    return $firstCell;
+};
+const getLastCell = (event) => {
+    const $target = event.target;
+    const $parent = $target.parentElement;
+    const $lastCell = $parent.lastElementChild;
+    if ($lastCell && (!isFocusable($lastCell) || !isVisible($lastCell))) {
+        return _getPrevCell($lastCell);
+    }
+    return $lastCell;
+};
+const modifierKeys = ['alt', 'control', 'shift', 'meta'];
+const eventKeyMap = {
+    ArrowUp: 'up',
+    ArrowDown: 'down',
+    ArrowLeft: 'left',
+    ArrowRight: 'right',
+};
+export const defaultKeypressHandlers = {
+    'keydown.up': (event) => {
+        const $upCell = getUpCell(event);
+        if ($upCell) {
+            event.preventDefault();
+            event.stopPropagation();
+            $upCell.focus();
+        }
+    },
+    'keydown.down': (event) => {
+        const $downCell = getDownCell(event);
+        if ($downCell) {
+            event.preventDefault();
+            event.stopPropagation();
+            $downCell.focus();
+        }
+    },
+    'keydown.left': (event) => {
+        const $prevCell = getPrevCell(event);
+        // prevent default edit-cell behaviour on first cell
+        event.preventDefault();
+        event.stopPropagation();
+        if ($prevCell) {
+            $prevCell.focus();
+        }
+    },
+    'keydown.right': (event) => {
+        const $nextCell = getNextCell(event);
+        // prevent default edit-cell behaviour on last cell
+        event.preventDefault();
+        event.stopPropagation();
+        if ($nextCell) {
+            $nextCell.focus();
+        }
+    },
+    'keydown.control.up': (event) => {
+        const $topCell = getTopCell(event);
+        if ($topCell) {
+            event.preventDefault();
+            event.stopPropagation();
+            $topCell.focus();
+        }
+    },
+    'keydown.control.down': (event) => {
+        const $bottomCell = getBottomCell(event);
+        if ($bottomCell) {
+            event.preventDefault();
+            event.stopPropagation();
+            $bottomCell.focus();
+        }
+    },
+    'keydown.control.left': (event) => {
+        const $firstCell = getFirstCell(event);
+        if ($firstCell) {
+            event.preventDefault();
+            event.stopPropagation();
+            $firstCell.focus();
+        }
+    },
+    'keydown.control.right': (event) => {
+        const $lastCell = getLastCell(event);
+        if ($lastCell) {
+            event.preventDefault();
+            event.stopPropagation();
+            $lastCell.focus();
+        }
+    },
+    'keydown.end': (event) => {
+        const $lastCell = getLastCell(event);
+        if ($lastCell) {
+            event.preventDefault();
+            event.stopPropagation();
+            $lastCell.focus();
+        }
+    },
+    'keydown.enter': (event) => {
+        const $target = event.target;
+        if ($target instanceof HTMLTableCellElement) {
+            event.preventDefault();
+            event.stopPropagation();
+            const $downCell = getDownCell(event);
+            if ($downCell) {
+                $downCell.focus();
+            }
+        }
+        else {
+            // handle other contexts
+        }
+    },
+    'keydown.shift.enter': (event) => {
+        const $target = event.target;
+        if ($target instanceof HTMLTableCellElement) {
+            event.preventDefault();
+            event.stopPropagation();
+            const $upCell = getUpCell(event);
+            if ($upCell) {
+                $upCell.focus();
+            }
+        }
+        else {
+            // handle other contexts
+        }
+    },
+    'keydown.home': (event) => {
+        const $firstCell = getFirstCell(event);
+        if ($firstCell) {
+            event.preventDefault();
+            event.stopPropagation();
+            $firstCell.focus();
+        }
+    },
+    'keydown.tab': (event) => {
+        const $nextCell = getNextCell(event);
+        if ($nextCell) {
+            event.preventDefault();
+            event.stopPropagation();
+            $nextCell.focus();
+        }
+    },
+    'keydown.shift.tab': (event) => {
+        const $prevCell = getPrevCell(event);
+        if ($prevCell) {
+            event.preventDefault();
+            event.stopPropagation();
+            $prevCell.focus();
+        }
+    },
+};
+export function useKeyboardNav(options) {
+    const getParentElement = (option) => {
+        let $parent = null;
+        if (option.parent) {
+            if (typeof option.parent === 'string') {
+                $parent = document.querySelector(option.parent);
+            }
+            else if (option.parent instanceof HTMLElement) {
+                $parent = option.parent;
+            }
+            else {
+                $parent = option.parent.value;
+            }
+        }
+        return $parent;
+    };
+    const getSelectorsFromOption = (option) => {
+        // assumes that option.selectors is provided
+        const $parent = getParentElement(option);
+        let selectors = [];
+        if (typeof option.selectors === 'string') {
+            selectors = $parent
+                ? Array.from($parent.querySelectorAll(option.selectors))
+                : Array.from(document.querySelectorAll(option.selectors));
+        }
+        else if (Array.isArray(option.selectors)) {
+            for (const element of option.selectors) {
+                if (element instanceof HTMLElement) {
+                    selectors.push(element);
+                }
+                else {
+                    selectors.push(element.$el);
+                }
+            }
+        }
+        else if (option.selectors instanceof HTMLElement) {
+            selectors.push(option.selectors);
+        }
+        else {
+            if (Array.isArray(option.selectors.value)) {
+                for (const element of option.selectors.value) {
+                    if (element instanceof HTMLElement) {
+                        selectors.push(element);
+                    }
+                    else {
+                        selectors.push(element.$el);
+                    }
+                }
+            }
+            else {
+                selectors.push(option.selectors.value);
+            }
+        }
+        return selectors;
+    };
+    const getSelectors = (option) => {
+        const $parent = getParentElement(option);
+        let selectors = [];
+        if (option.selectors) {
+            selectors = getSelectorsFromOption(option);
+        }
+        else if ($parent) {
+            // TODO: what should happen if no parent or selectors are provided?
+            const $children = Array.from($parent.children);
+            selectors = $children.filter(selector => {
+                // ignore elements not in the tab order or are not visible
+                return isFocusable(selector) && isVisible(selector);
+            });
+        }
+        return selectors;
+    };
+    const getEventListener = (option) => {
+        return (event) => {
+            const activeKey = eventKeyMap[event.key] || event.key.toLowerCase();
+            if (modifierKeys.includes(activeKey))
+                return; // ignore modifier key presses
+            const handlers = option.handlers || defaultKeypressHandlers;
+            for (const key of Object.keys(handlers)) {
+                const [eventType, ...keys] = key.split('.');
+                if (eventType !== 'keydown') {
+                    continue;
+                }
+                if (keys.includes(activeKey)) {
+                    const listener = handlers[key];
+                    // check if the handler has modifiers, and if the modifier is active;
+                    // this is to ensure exact key-press matches
+                    const hasModifier = keys.filter(key => modifierKeys.includes(key));
+                    const isModifierActive = modifierKeys.some(key => {
+                        const modifierKey = key.charAt(0).toUpperCase() + key.slice(1);
+                        return event.getModifierState(modifierKey);
+                    });
+                    if (hasModifier.length > 0) {
+                        if (isModifierActive) {
+                            for (const modifier of modifierKeys) {
+                                if (keys.includes(modifier)) {
+                                    // docs: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/getModifierState
+                                    const modifierKey = modifier.charAt(0).toUpperCase() + modifier.slice(1);
+                                    if (event.getModifierState(modifierKey)) {
+                                        listener(event);
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    else {
+                        if (!isModifierActive) {
+                            listener(event);
+                        }
+                    }
+                }
+            }
+        };
+    };
+    const watchStopHandlers = [];
+    onMounted(() => {
+        for (const option of options) {
+            const $parent = getParentElement(option);
+            const selectors = getSelectors(option);
+            const listener = getEventListener(option);
+            const listenerElements = $parent
+                ? [$parent] // watch for focus recursively within the parent element
+                : selectors; // watch for focus on each selector element TODO: too much JS?
+            for (const element of listenerElements) {
+                const { focused } = useFocusWithin(ref(element));
+                const stopHandler = watch(focused, value => {
+                    if (value) {
+                        element.addEventListener('keydown', listener);
+                    }
+                    else {
+                        element.removeEventListener('keydown', listener);
+                    }
+                });
+                watchStopHandlers.push(stopHandler);
+            }
+        }
+    });
+    onBeforeUnmount(() => {
+        for (const stopHandler of watchStopHandlers) {
+            stopHandler();
+        }
+    });
+}

package/dist/composables/visibility/index.js

@@ -0,0 +1,47 @@
+import { defaultWindow, unrefElement, useEventListener, } from '@vueuse/core';
+import { ref, watch } from 'vue';
+/**
+ * Tracks the visibility of an element within the viewport.
+ *
+ * Compatibility version to get Stonecrop keyboard navigation to work. This function is a copy of the
+ * `useElementVisibility` function from VueUse v9.13.0, with the `IntersectionObserver` API removed.
+ *
+ * This version uses the `getBoundingClientRect` method to determine if an element is visible
+ * in the viewport. This is less performant than the `IntersectionObserver` API, but it is
+ * more compatible.
+ *
+ * Note: the newer versions of the VueUse dependencies imported here are sufficient for this composable.
+ * (Last verified: v10.9.0 on May 2, 2024)
+ *
+ * @see https://v9-13-0.vueuse.org/core/useElementVisibility
+ * @param element
+ * @param options
+ */
+export function useElementVisibility(element, { window = defaultWindow, scrollTarget } = {}) {
+    const elementIsVisible = ref(false);
+    const testBounding = () => {
+        if (!window)
+            return;
+        const document = window.document;
+        const el = unrefElement(element);
+        if (!el) {
+            elementIsVisible.value = false;
+        }
+        else {
+            const rect = el.getBoundingClientRect();
+            elementIsVisible.value =
+                rect.top <= (window.innerHeight || document.documentElement.clientHeight) &&
+                    rect.left <= (window.innerWidth || document.documentElement.clientWidth) &&
+                    rect.bottom >= 0 &&
+                    rect.right >= 0;
+        }
+    };
+    watch(() => unrefElement(element), () => testBounding(), { immediate: true, flush: 'post' });
+    if (window) {
+        useEventListener(scrollTarget || window, 'scroll', testBounding, {
+            capture: false,
+            passive: true,
+        });
+    }
+    return elementIsVisible;
+}

package/dist/index.js

@@ -0,0 +1,8 @@
+import { defaultKeypressHandlers, useKeyboardNav } from '@/composables/keyboard';
+/**
+ * Install all utility components
+ * @param app - Vue app instance
+ * @public
+ */
+function install(app /* options */) { }
+export { defaultKeypressHandlers, install, useKeyboardNav };

package/dist/src/composables/keyboard.d.ts

@@ -0,0 +1,4 @@
+import type { KeyboardNavigationOptions, KeypressHandlers } from '@/types';
+export declare const defaultKeypressHandlers: KeypressHandlers;
+export declare function useKeyboardNav(options: KeyboardNavigationOptions[]): void;
+//# sourceMappingURL=keyboard.d.ts.map

package/dist/src/composables/keyboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyboard.d.ts","sourceRoot":"","sources":["../../../src/composables/keyboard.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAuM1E,eAAO,MAAM,uBAAuB,EAAE,gBA6HrC,CAAA;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,yBAAyB,EAAE,QA2IlE"}

package/dist/src/composables/visibility/index.d.ts

@@ -0,0 +1,23 @@
+import { type ConfigurableWindow, type MaybeComputedElementRef, type MaybeRefOrGetter } from '@vueuse/core';
+export interface UseElementVisibilityOptions extends ConfigurableWindow {
+    scrollTarget?: MaybeRefOrGetter<HTMLElement | undefined | null>;
+}
+/**
+ * Tracks the visibility of an element within the viewport.
+ *
+ * Compatibility version to get Stonecrop keyboard navigation to work. This function is a copy of the
+ * `useElementVisibility` function from VueUse v9.13.0, with the `IntersectionObserver` API removed.
+ *
+ * This version uses the `getBoundingClientRect` method to determine if an element is visible
+ * in the viewport. This is less performant than the `IntersectionObserver` API, but it is
+ * more compatible.
+ *
+ * Note: the newer versions of the VueUse dependencies imported here are sufficient for this composable.
+ * (Last verified: v10.9.0 on May 2, 2024)
+ *
+ * @see https://v9-13-0.vueuse.org/core/useElementVisibility
+ * @param element
+ * @param options
+ */
+export declare function useElementVisibility(element: MaybeComputedElementRef, { window, scrollTarget }?: UseElementVisibilityOptions): import("vue").Ref<boolean>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/composables/visibility/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/composables/visibility/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EAIrB,MAAM,cAAc,CAAA;AAGrB,MAAM,WAAW,2BAA4B,SAAQ,kBAAkB;IACtE,YAAY,CAAC,EAAE,gBAAgB,CAAC,WAAW,GAAG,SAAS,GAAG,IAAI,CAAC,CAAA;CAC/D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,uBAAuB,EAChC,EAAE,MAAsB,EAAE,YAAY,EAAE,GAAE,2BAAgC,8BAmC1E"}

package/dist/src/index.d.ts

@@ -0,0 +1,11 @@
+import { App } from 'vue';
+import { defaultKeypressHandlers, useKeyboardNav } from '@/composables/keyboard';
+export type { KeypressHandlers, KeyboardNavigationOptions } from '@/types';
+/**
+ * Install all utility components
+ * @param app - Vue app instance
+ * @public
+ */
+declare function install(app: App): void;
+export { defaultKeypressHandlers, install, useKeyboardNav };
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAA;AAEzB,OAAO,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAChF,YAAY,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAA;AAE1E;;;;GAIG;AACH,iBAAS,OAAO,CAAC,GAAG,EAAE,GAAG,QAAkB;AAE3C,OAAO,EAAE,uBAAuB,EAAE,OAAO,EAAE,cAAc,EAAE,CAAA"}

package/dist/src/types/index.d.ts

@@ -0,0 +1,10 @@
+import { ComponentPublicInstance, Ref } from 'vue';
+export type KeypressHandlers = {
+    [key: string]: (ev: KeyboardEvent) => any;
+};
+export type KeyboardNavigationOptions = {
+    parent?: string | HTMLElement | Ref<HTMLElement>;
+    selectors?: string | HTMLElement | HTMLElement[] | ComponentPublicInstance[] | Ref<HTMLElement> | Ref<HTMLElement[]> | Ref<ComponentPublicInstance[]>;
+    handlers?: KeypressHandlers;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/src/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,GAAG,EAAE,MAAM,KAAK,CAAA;AAElD,MAAM,MAAM,gBAAgB,GAAG;IAC9B,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,aAAa,KAAK,GAAG,CAAA;CACzC,CAAA;AAED,MAAM,MAAM,yBAAyB,GAAG;IACvC,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,GAAG,CAAC,WAAW,CAAC,CAAA;IAChD,SAAS,CAAC,EACP,MAAM,GACN,WAAW,GACX,WAAW,EAAE,GACb,uBAAuB,EAAE,GACzB,GAAG,CAAC,WAAW,CAAC,GAChB,GAAG,CAAC,WAAW,EAAE,CAAC,GAClB,GAAG,CAAC,uBAAuB,EAAE,CAAC,CAAA;IACjC,QAAQ,CAAC,EAAE,gBAAgB,CAAA;CAC3B,CAAA"}

package/dist/utilities/src/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.47.0"
+    }
+  ]
+}

package/dist/utilities.d.ts

@@ -0,0 +1,22 @@
+import { App } from 'vue';
+import { defaultKeypressHandlers } from '@/composables/keyboard';
+import { KeyboardNavigationOptions } from '@/types';
+import { KeypressHandlers } from '@/types';
+import { useKeyboardNav } from '@/composables/keyboard';
+
+export { defaultKeypressHandlers }
+
+/**
+ * Install all utility components
+ * @param app - Vue app instance
+ * @public
+ */
+export declare function install(app: App): void;
+
+export { KeyboardNavigationOptions }
+
+export { KeypressHandlers }
+
+export { useKeyboardNav }
+
+export { }