Merge pull request #21035 from itisAliRH/add-history-list-keyboard-navigation

[25.1] Add Keyboard Navigation to History Lists

Author: bgruening

client/src/components/Common/GCard.vue

@@ -176,6 +176,11 @@ interface Props {
      * @default "Last updated"
      */
     updateTimeTitle?: string;
+
+    /** Whether this card is highlighted (for example, as a range selection anchor)
+     * @default false
+     */
+    highlighted?: boolean;
 }
 
 const props = withDefaults(defineProps<Props>(), {
@@ -207,6 +212,7 @@ const props = withDefaults(defineProps<Props>(), {
     updateTime: "",
     updateTimeIcon: () => faEdit,
     updateTimeTitle: "Last updated",
+    highlighted: false,
 });
 
 /**
@@ -283,8 +289,10 @@ const allowedTitleLines = computed(() => props.titleNLines);
 
 function onKeyDown(event: KeyboardEvent) {
     if ((props.clickable && event.key === "Enter") || event.key === " ") {
+        event.stopPropagation();
         emit("click", event);
     } else if (props.clickable) {
+        event.stopPropagation();
         emit("keydown", event);
     }
 }
@@ -310,7 +318,7 @@ function onKeyDown(event: KeyboardEvent) {
         <div
             :id="`g-card-content-${props.id}`"
             class="g-card-content d-flex flex-column justify-content-between h-100 p-2"
-            :class="contentClass">
+            :class="[{ 'g-card-highlighted': props.highlighted }, contentClass]">
             <slot>
                 <div class="d-flex flex-column flex-gapy-1">
                     <div
@@ -708,6 +716,10 @@ function onKeyDown(event: KeyboardEvent) {
         border-left: 0.25rem solid $brand-primary;
     }
 
+    &.g-card-highlighted .g-card-content {
+        box-shadow: 0 0 0 0.2rem transparentize($brand-primary, 0.75);
+    }
+
     &.g-card-clickable {
         cursor: pointer;
 

client/src/components/History/HistoryCard.vue

@@ -93,6 +93,20 @@ interface Props {
      * @default false
      */
     sharedView?: boolean;
+
+    /**
+     * Whether the card is clickable for keyboard navigation
+     * @type {boolean}
+     * @default false
+     */
+    clickable?: boolean;
+
+    /**
+     * Whether this card is highlighted (for example, as a range selection anchor)
+     * @type {boolean}
+     * @default false
+     */
+    highlighted?: boolean;
 }
 
 const props = withDefaults(defineProps<Props>(), {
@@ -102,6 +116,8 @@ const props = withDefaults(defineProps<Props>(), {
     selectable: false,
     selected: false,
     sharedView: false,
+    clickable: false,
+    highlighted: false,
 });
 
 const router = useRouter();
@@ -144,6 +160,18 @@ const emit = defineEmits<{
      * @event updateFilter
      */
     (e: "updateFilter", key: string, value: any): void;
+
+    /**
+     * Emitted when a keyboard event occurs on the history card
+     * @event on-key-down
+     */
+    (e: "on-key-down", history: AnyHistoryEntry, event: KeyboardEvent): void;
+
+    /**
+     * Emitted when the history card is clicked
+     * @event on-history-card-click
+     */
+    (e: "on-history-card-click", history: AnyHistoryEntry, event: Event): void;
 }>();
 
 /**
@@ -203,12 +231,25 @@ async function onTagsUpdate(historyId: string, tags: string[]) {
     await historyStore.updateHistory(historyId, { tags: tags });
     emit("refreshList", true, true);
 }
+
+function onClick(event: Event) {
+    if (props.clickable) {
+        emit("on-history-card-click", props.history, event);
+    }
+}
+
+function onKeyDown(event: KeyboardEvent) {
+    if (props.clickable) {
+        emit("on-key-down", props.history, event);
+    }
+}
 </script>
 
 <template>
     <GCard
         :id="`history-${history.id}`"
         :key="history.id"
+        class="history-card"
         :title="historyCardTitle"
         :title-badges="historyCardTitleBadges"
         :title-n-lines="2"
@@ -226,11 +267,15 @@ async function onTagsUpdate(historyId: string, tags: string[]) {
         :tags-editable="userOwnsHistory(currentUser, history)"
         :max-visible-tags="props.gridView ? 2 : 8"
         :update-time="history.update_time"
+        :clickable="props.clickable"
+        :highlighted="props.highlighted"
         @titleClick="onTitleClick"
         @rename="() => router.push(`/histories/rename?id=${history.id}`)"
         @select="isMyHistory(history) && emit('select', history)"
         @tagsUpdate="(tags) => onTagsUpdate(history.id, tags)"
-        @tagClick="(tag) => emit('tagClick', tag)">
+        @tagClick="(tag) => emit('tagClick', tag)"
+        @click="onClick"
+        @keydown="onKeyDown">
         <template v-if="props.archivedView && isArchivedHistory(history)" v-slot:titleActions>
             <ExportRecordDOILink :export-record-uri="history.export_record_data?.target_uri" />
         </template>

client/src/components/History/HistoryCardList.vue

@@ -23,6 +23,8 @@
  *   @tagClick="onTagClick" />
  */
 
+import type { Ref } from "vue";
+
 import type { AnyHistoryEntry, MyHistory } from "@/api/histories";
 import { isMyHistory } from "@/api/histories";
 
@@ -76,13 +78,36 @@ interface Props {
      * @default []
      */
     selectedHistoryIds?: { id: string }[];
+
+    /**
+     * Whether cards are clickable for navigation
+     * @type {boolean}
+     * @default false
+     */
+    clickable?: boolean;
+
+    /**
+     * Item refs for keyboard navigation
+     * @type {Record<string, Ref<InstanceType<typeof HistoryCard> | null>>}
+     * @default {}
+     */
+    itemRefs?: Record<string, Ref<InstanceType<typeof HistoryCard> | null>>;
+
+    /**
+     * Range select anchor for keyboard navigation
+     * @type {AnyHistoryEntry | undefined}
+     */
+    rangeSelectAnchor?: AnyHistoryEntry;
 }
 
 const props = withDefaults(defineProps<Props>(), {
     gridView: false,
     publishedView: false,
     selectable: false,
     selectedHistoryIds: () => [],
+    clickable: false,
+    itemRefs: () => ({}),
+    rangeSelectAnchor: undefined,
 });
 
 /**
@@ -112,29 +137,50 @@ const emit = defineEmits<{
      * @event updateFilter
      */
     (e: "updateFilter", key: string, value: any): void;
+
+    /**
+     * Emitted when a keyboard event occurs on a history card
+     * @event on-key-down
+     */
+    (e: "on-key-down", history: AnyHistoryEntry, event: KeyboardEvent): void;
+
+    /**
+     * Emitted when a history card is clicked
+     * @event on-history-card-click
+     */
+    (e: "on-history-card-click", history: AnyHistoryEntry, event: Event): void;
 }>();
 </script>
 
 <template>
-    <div class="history-card-list d-flex flex-wrap overflow-auto">
+    <div class="history-card-list d-flex flex-wrap overflow-auto pt-1">
         <HistoryCard
             v-for="history in props.histories"
+            :ref="props.itemRefs[history.id]"
             :key="history.id"
+            tabindex="0"
             :history="history"
             :grid-view="props.gridView"
             :shared-view="props.sharedView"
             :published-view="props.publishedView"
             :archived-view="props.archivedView"
             :selectable="props.selectable"
             :selected="props.selectedHistoryIds.some((selected) => selected.id === history.id)"
+            :clickable="props.clickable"
+            :highlighted="props.rangeSelectAnchor?.id === history.id"
+            class="history-card-in-list"
             @select="isMyHistory(history) && emit('select', history)"
             @tagClick="(...args) => emit('tagClick', ...args)"
             @refreshList="(...args) => emit('refreshList', ...args)"
-            @updateFilter="(...args) => emit('updateFilter', ...args)" />
+            @updateFilter="(...args) => emit('updateFilter', ...args)"
+            @on-key-down="(...args) => emit('on-key-down', ...args)"
+            @on-history-card-click="(...args) => emit('on-history-card-click', ...args)" />
     </div>
 </template>
 
 <style lang="scss" scoped>
+@import "theme/blue.scss";
+
 .history-card-list {
     container: cards-list / inline-size;
 }