@stonecrop/utilities 0.13.12 → 0.14.0

package/dist/composables/keyboard.js

@@ -1,473 +0,0 @@
-import { onBeforeUnmount, onMounted, ref, watch } from 'vue';
-import { useFocusWithin } from '@vueuse/core';
-import { useElementVisibility } from './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',
-};
-/**
- * Default keypress handlers for keyboard navigation
- * @public
- */
-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();
-        }
-    },
-};
-/**
- * Keyboard navigation composable
- * @param options - Keyboard navigation options
- * @public
- */
-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 (option.selectors?.value) {
-            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

@@ -1,47 +0,0 @@
-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 - Element to track visibility for
- * @param options - Configuration options (window, scrollTarget)
- */
-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

@@ -1,8 +0,0 @@
-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/naming-conventions.js

@@ -1,135 +0,0 @@
-/**
- * Naming Convention Utilities
- * Converts between SQL snake_case and JavaScript camelCase naming conventions
- * @packageDocumentation
- */
-/**
- * Converts snake_case to camelCase
- * @param snakeCase - Snake case string
- * @returns Camel case string
- * @public
- * @example
- * ```typescript
- * snakeToCamel('user_email') // 'userEmail'
- * snakeToCamel('created_at') // 'createdAt'
- * snakeToCamel('user_id') // 'userId'
- * ```
- */
-export function snakeToCamel(snakeCase) {
-    return snakeCase.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
-}
-/**
- * Converts camelCase to snake_case
- * @param camelCase - Camel case string
- * @returns Snake case string
- * @public
- * @example
- * ```typescript
- * camelToSnake('userEmail') // 'user_email'
- * camelToSnake('createdAt') // 'created_at'
- * camelToSnake('userId') // 'user_id'
- * ```
- */
-export function camelToSnake(camelCase) {
-    return camelCase.replace(/[A-Z]/g, letter => `_${letter.toLowerCase()}`);
-}
-/**
- * Converts snake_case to Title Case label
- * @param snakeCase - Snake case string
- * @returns Title case label
- * @public
- * @example
- * ```typescript
- * snakeToLabel('user_email') // 'User Email'
- * snakeToLabel('first_name') // 'First Name'
- * snakeToLabel('created_at') // 'Created At'
- * ```
- */
-export function snakeToLabel(snakeCase) {
-    return snakeCase
-        .split('_')
-        .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
-        .join(' ');
-}
-/**
- * Converts camelCase to Title Case label
- * @param camelCase - Camel case string
- * @returns Title case label
- * @public
- * @example
- * ```typescript
- * camelToLabel('userEmail') // 'User Email'
- * camelToLabel('firstName') // 'First Name'
- * camelToLabel('createdAt') // 'Created At'
- * ```
- */
-export function camelToLabel(camelCase) {
-    // Insert space before capital letters and capitalize first letter
-    const withSpaces = camelCase.replace(/([A-Z])/g, ' $1').trim();
-    return withSpaces.charAt(0).toUpperCase() + withSpaces.slice(1);
-}
-/**
- * Converts SQL column name to Stonecrop field naming convention
- * Handles special cases like ID suffixes
- * @param sqlName - SQL column name (snake_case)
- * @returns Field name and label
- * @public
- * @example
- * ```typescript
- * convertSQLName('user_email')
- * // { fieldname: 'userEmail', label: 'User Email', originalName: 'user_email' }
- *
- * convertSQLName('user_id')
- * // { fieldname: 'userId', label: 'User', originalName: 'user_id' }
- *
- * convertSQLName('created_at')
- * // { fieldname: 'createdAt', label: 'Created At', originalName: 'created_at' }
- * ```
- */
-export function convertSQLName(sqlName) {
-    const fieldname = snakeToCamel(sqlName);
-    // Generate label - special handling for _id suffix
-    let label;
-    if (sqlName.endsWith('_id')) {
-        // Remove _id suffix for label: user_id -> User
-        const withoutId = sqlName.slice(0, -3);
-        label = snakeToLabel(withoutId);
-    }
-    else {
-        label = snakeToLabel(sqlName);
-    }
-    return {
-        fieldname,
-        label,
-        originalName: sqlName,
-    };
-}
-/**
- * Batch converts multiple SQL column names
- * @param sqlNames - Array of SQL column names
- * @returns Array of name conversions
- * @public
- */
-export function convertSQLNames(sqlNames) {
-    return sqlNames.map(convertSQLName);
-}
-/**
- * Creates a bidirectional mapping between SQL and Stonecrop names
- * @param sqlNames - Array of SQL column names
- * @returns Mapping object with both directions
- * @public
- */
-export function createNameMapping(sqlNames) {
-    const conversions = convertSQLNames(sqlNames);
-    const sqlToFieldname = new Map();
-    const fieldnameToSQL = new Map();
-    for (const conversion of conversions) {
-        sqlToFieldname.set(conversion.originalName, conversion.fieldname);
-        fieldnameToSQL.set(conversion.fieldname, conversion.originalName);
-    }
-    return {
-        sqlToFieldname,
-        fieldnameToSQL,
-        conversions,
-    };
-}