feat: make it possible to navigate cells using the keyboard

closes #116

Author: simonwep

eslint.config.mjs

@@ -42,6 +42,7 @@ export default defineConfig([
     },
     rules: {
       'no-console': 'error',
+      'vue/no-template-shadow': 'error',
       'vue/attribute-hyphenation': ['error', 'never'],
       'vue/multi-word-component-names': 'off',
       'vue/require-default-prop': 'off',

src/app/components/base/currency-cell/CurrencyCell.vue

@@ -94,6 +94,8 @@ watch(focused, (value) => {
     invalid.value = true;
   }
 });
+
+defineExpose({ input });
 </script>
 
 <style lang="scss" module>

src/app/components/feature/BudgetGroup.vue

@@ -76,6 +76,7 @@
         @action="performAction($event, budget.id, month, budget.values[month])"
       >
         <CurrencyCell
+          :ref="onRefCallback"
           :testId="`${testId}-budget-${index}-${month}`"
           :modelValue="budget.values[month]"
           @update:model-value="setBudget(budget.id, month, $event)"
@@ -105,6 +106,7 @@ import { ReorderEvent } from '@components/base/draggable/Draggable.types';
 import Draggable from '@components/base/draggable/Draggable.vue';
 import { DraggableStore } from '@components/base/draggable/store';
 import TextCell from '@components/base/text-cell/TextCell.vue';
+import { useOrderedTemplateRefs } from '@composables/useOrderedTemplateRefs.ts';
 import { useStateUtils } from '@composables/useStateUtils.ts';
 import { RiAddCircleLine, RiCloseCircleLine } from '@remixicon/vue';
 import { useDataStore } from '@store/state';
@@ -134,6 +136,7 @@ const {
 
 const { isCurrentMonth } = useStateUtils();
 const { t } = useI18n();
+const { onRefCallback, value: currencyCells } = useOrderedTemplateRefs<InstanceType<typeof CurrencyCell>>();
 const focused = ref<string>();
 
 const totals = computed(() => {
@@ -187,6 +190,10 @@ const performAction = (action: CellMenuActionId, budgetId: string, month: number
       return fillBudget(budgetId, value, month);
   }
 };
+
+defineExpose({
+  currencyCells: computed(() => currencyCells.map((v) => v.input).filter((v) => !!v) as HTMLInputElement[])
+});
 </script>
 
 <style lang="scss" module>

src/app/components/feature/BudgetGroups.vue

@@ -34,10 +34,10 @@
     />
     <span :class="[$style.sum, $style.totals]">{{ t('shared.totals') }}</span>
     <Currency
-      v-for="(sum, index) of totals"
+      v-for="(value, index) of totals"
       :key="index"
       :testId="`month-${index}-total`"
-      :value="sum"
+      :value="value"
       :class="$style.sum"
     />
     <span />
@@ -52,7 +52,7 @@
         name="budget-groups"
         @drop="reorder"
       />
-      <BudgetGroup :allowDelete="allowDelete" :group="group" :testId="`group-${index}`" />
+      <BudgetGroup :ref="onRefCallback" :allowDelete="allowDelete" :group="group" :testId="`group-${index}`" />
     </template>
 
     <!-- Footer -->
@@ -74,11 +74,14 @@ import Currency from '@components/base/currency/Currency.vue';
 import { ReorderEvent } from '@components/base/draggable/Draggable.types';
 import Draggable from '@components/base/draggable/Draggable.vue';
 import { DraggableStore } from '@components/base/draggable/store';
+import { useKeyboardNavigation } from '@composables/useKeyboardNavigation.ts';
 import { useMonthNames } from '@composables/useMonthNames.ts';
+import { useOrderedTemplateRefs } from '@composables/useOrderedTemplateRefs.ts';
 import { useStateUtils } from '@composables/useStateUtils.ts';
 import { RiAddCircleLine, RiLockLine, RiLockUnlockLine, RiSkipDownLine } from '@remixicon/vue';
 import { useSettingsStore } from '@store/settings';
 import { useDataStore } from '@store/state';
+import { sum } from '@utils/array/array.ts';
 import { computed, ref } from 'vue';
 import { useI18n } from 'vue-i18n';
 import type { Component } from 'vue';
@@ -88,15 +91,21 @@ const props = defineProps<{
 }>();
 
 const months = useMonthNames('long', () => settings.general.monthOffset);
+const { onRefCallback, value: budgetGroups } = useOrderedTemplateRefs<InstanceType<typeof BudgetGroup>>();
 const { isCurrentMonth } = useStateUtils();
 const { state, moveBudgetGroup, moveBudgetIntoGroup, addBudgetGroup, getBudgetGroup } = useDataStore();
 const { state: settings } = useSettingsStore();
 const { t } = useI18n();
 
 const allowDelete = ref(false);
-
 const groups = computed(() => state[props.type]);
 
+useKeyboardNavigation(() => ({
+  inputs: budgetGroups.flatMap((v) => v.currencyCells),
+  rows: sum(groups.value.map((v) => v.budgets.length)),
+  cols: 12
+}));
+
 const totals = computed(() => {
   const totals = new Array(12).fill(0);
 

src/composables/useKeyboardNavigation.ts

@@ -0,0 +1,84 @@
+import { MaybeRefOrGetter, onScopeDispose, toRef, watch } from 'vue';
+
+type UseKeyboardNavigationOptions = {
+  inputs: HTMLInputElement[];
+  rows: number;
+  cols: number;
+};
+
+const arrowEvents = ['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'];
+
+export const useKeyboardNavigation = (options: MaybeRefOrGetter<UseKeyboardNavigationOptions>) => {
+  const rOptions = toRef(options);
+  const controllers = new Set<AbortController>();
+
+  const unbindEvents = () => {
+    controllers.forEach((controller) => controller.abort());
+    controllers.clear();
+  };
+
+  const resolveNextIndex = (currentIndex: number, key: string, cols: number, rows: number) => {
+    const currentRow = Math.floor(currentIndex / cols);
+    const currentCol = currentIndex % cols;
+
+    switch (key) {
+      case 'ArrowUp':
+        return currentRow > 0 ? (currentRow - 1) * cols + currentCol : (rows - 1) * cols + currentCol;
+      case 'ArrowDown':
+        return currentRow < rows - 1 ? (currentRow + 1) * cols + currentCol : currentCol;
+      case 'ArrowLeft':
+        return currentCol > 0 ? currentRow * cols + (currentCol - 1) : currentRow * cols + (cols - 1);
+      case 'ArrowRight':
+        return currentCol < cols - 1 ? currentRow * cols + (currentCol + 1) : currentRow * cols;
+      default:
+        return currentIndex; // Ignore other keys
+    }
+  };
+
+  const onKeyDown = (event: KeyboardEvent, index: number, options: UseKeyboardNavigationOptions) => {
+    const newIndex = resolveNextIndex(index, event.key, options.cols, options.rows);
+
+    if (newIndex !== index) {
+      event.preventDefault();
+      options.inputs[index].blur();
+      options.inputs[newIndex].focus();
+    }
+  };
+
+  watch(rOptions, (options) => {
+    unbindEvents();
+
+    options.inputs.forEach((input) => {
+      const controller = new AbortController();
+      controllers.add(controller);
+
+      input.addEventListener(
+        'keydown',
+        (event) => {
+          if (!arrowEvents.includes(event.key)) return;
+
+          const sortedInputs = options.inputs.toSorted((a, b) => {
+            const position = a.compareDocumentPosition(b);
+
+            if (position & Node.DOCUMENT_POSITION_FOLLOWING) {
+              return -1;
+            } else if (position & Node.DOCUMENT_POSITION_PRECEDING) {
+              return 1;
+            }
+
+            return 0;
+          });
+
+          const index = sortedInputs.indexOf(input);
+
+          if (index !== -1) {
+            onKeyDown(event, index, { ...options, inputs: sortedInputs });
+          }
+        },
+        { signal: controller.signal }
+      );
+    });
+  });
+
+  onScopeDispose(unbindEvents);
+};

src/composables/useOrderedTemplateRefs.ts

@@ -0,0 +1,22 @@
+import { readonly, shallowReactive } from 'vue';
+
+export const useOrderedTemplateRefs = <T>() => {
+  const refs = shallowReactive<T[]>([]);
+
+  const onRefCallback = (el: T | null) => {
+    if (el && !refs.includes(el)) {
+      refs.push(el);
+    } else if (!el) {
+      const index = refs.findIndex((r) => r === el);
+
+      if (index !== -1) {
+        refs.splice(index, 1);
+      }
+    }
+  };
+
+  return {
+    onRefCallback,
+    value: readonly(refs)
+  };
+};