From 7bd563e8d46292fdc98dcfcefcde6ae1fdec2903 Mon Sep 17 00:00:00 2001
From: Jacques Erasmus <jerasmus@gitlab.com>
Date: Thu, 2 Oct 2025 09:22:19 +0200
Subject: [PATCH 1/4] Implement ARIA tree view pattern for the FTB

This commit implements the ARIA tree view pattern as specified in the W3C
ARIA Authoring Practices Guide for the file tree browser components.
---
 .../diffs/components/tree_list.vue            |  4 +-
 .../components/tree_list.vue                  |  5 +-
 .../vue_shared/components/file_row.vue        |  3 +
 .../diffs/components/tree_list_spec.js        | 16 ++++-
 .../components/tree_list_spec.js              | 12 ++++
 .../vue_shared/components/file_row_spec.js    | 58 +++++++++++++++++++
 6 files changed, 95 insertions(+), 3 deletions(-)

diff --git a/app/assets/javascripts/diffs/components/tree_list.vue b/app/assets/javascripts/diffs/components/tree_list.vue
index aaa7697632560f..f2becb6a7e5481 100644
--- a/app/assets/javascripts/diffs/components/tree_list.vue
+++ b/app/assets/javascripts/diffs/components/tree_list.vue
@@ -292,7 +292,7 @@ export default {
         key-field="key"
         data-testid="tree-list-scroll"
       >
-        <template #default="{ item }">
+        <template #default="{ item, index }">
           <diff-file-row
             :file="item"
             :level="item.level"
@@ -302,6 +302,8 @@ export default {
             :style="{ '--level': item.level }"
             :class="{ 'tree-list-parent': item.level > 0 }"
             :tabindex="item.loading ? -1 : 0"
+            :aria-setsize="treeList.length"
+            :aria-posinset="index + 1"
             class="gl-relative"
             :data-file-row="item.fileHash"
             @toggleTreeOpen="$emit('toggleFolder', $event)"
diff --git a/app/assets/javascripts/repository/file_tree_browser/components/tree_list.vue b/app/assets/javascripts/repository/file_tree_browser/components/tree_list.vue
index 39e9d61f01dafc..ed8c2f056b7b0b 100644
--- a/app/assets/javascripts/repository/file_tree_browser/components/tree_list.vue
+++ b/app/assets/javascripts/repository/file_tree_browser/components/tree_list.vue
@@ -391,14 +391,17 @@ export default {
         key-field="id"
         class="gl-h-full gl-min-h-0 gl-flex-grow"
       >
-        <template #default="{ item }">
+        <template #default="{ item, index }">
           <file-row
             :file="item"
             :file-url="item.routerPath"
             :level="item.level"
             :opened="item.opened"
             :loading="item.loading"
+            :tabindex="item.loading ? -1 : 0"
             :aria-current="isCurrentPath(item.path)"
+            :aria-setsize="filteredFlatFilesList.length"
+            :aria-posinset="index + 1"
             :style="{ '--level': item.level }"
             :class="{
               'tree-list-parent': item.level > 0,
diff --git a/app/assets/javascripts/vue_shared/components/file_row.vue b/app/assets/javascripts/vue_shared/components/file_row.vue
index 4e7ce05f34ef85..5019b0c406b68e 100644
--- a/app/assets/javascripts/vue_shared/components/file_row.vue
+++ b/app/assets/javascripts/vue_shared/components/file_row.vue
@@ -146,7 +146,10 @@ export default {
     :title="textForTitle"
     :data-level="level"
     class="file-row"
+    role="treeitem"
+    :aria-level="level + 1"
     :aria-expanded="file.type === 'tree' ? file.opened.toString() : undefined"
+    :aria-label="file.name"
     @click="clickFile"
   >
     <span
diff --git a/spec/frontend/diffs/components/tree_list_spec.js b/spec/frontend/diffs/components/tree_list_spec.js
index a4ee48353b2191..3f2ee8251cd3ed 100644
--- a/spec/frontend/diffs/components/tree_list_spec.js
+++ b/spec/frontend/diffs/components/tree_list_spec.js
@@ -39,7 +39,7 @@ describe('Diffs tree list component', () => {
           },
           {
             template:
-              '<div><template v-for="item in items"><slot :item="item"></slot></template></div>',
+              '<div><template v-for="(item, index) in items"><slot :item="item" :index="index"></slot></template></div>',
           },
         ),
       },
@@ -415,6 +415,20 @@ describe('Diffs tree list component', () => {
     });
   });
 
+  describe('ARIA tree view pattern', () => {
+    beforeEach(() => {
+      setupFilesInState();
+      createComponent();
+    });
+
+    it('applies ARIA attributes directly to file rows', () => {
+      const fileRow = getFileRow();
+
+      expect(fileRow.attributes('aria-setsize')).toBe('7');
+      expect(fileRow.attributes('aria-posinset')).toBe('1');
+    });
+  });
+
   describe('tree view buttons', () => {
     it.each`
       toggle                | renderTreeList
diff --git a/spec/frontend/repository/file_tree_browser/components/tree_list_spec.js b/spec/frontend/repository/file_tree_browser/components/tree_list_spec.js
index 60ff772bef2b9d..e5c95e62c70e90 100644
--- a/spec/frontend/repository/file_tree_browser/components/tree_list_spec.js
+++ b/spec/frontend/repository/file_tree_browser/components/tree_list_spec.js
@@ -417,4 +417,16 @@ describe('Tree List', () => {
       expect(getQueryHandlerSuccess).toHaveBeenCalledTimes(2); // root + dir_0
     });
   });
+
+  describe('ARIA tree view pattern', () => {
+    it('applies ARIA attributes directly to file rows', () => {
+      const fileRows = findFileRows();
+
+      expect(fileRows.at(0).attributes('aria-setsize')).toBe('2');
+      expect(fileRows.at(0).attributes('aria-posinset')).toBe('1');
+
+      expect(fileRows.at(1).attributes('aria-setsize')).toBe('2');
+      expect(fileRows.at(1).attributes('aria-posinset')).toBe('2');
+    });
+  });
 });
diff --git a/spec/frontend/vue_shared/components/file_row_spec.js b/spec/frontend/vue_shared/components/file_row_spec.js
index 17454bec6f7642..fa246ea8b7f210 100644
--- a/spec/frontend/vue_shared/components/file_row_spec.js
+++ b/spec/frontend/vue_shared/components/file_row_spec.js
@@ -224,6 +224,64 @@ describe('File row component', () => {
     expect(wrapper.findComponent(GlIcon).props('name')).toBe('link');
   });
 
+  describe('ARIA tree view pattern', () => {
+    const createTreeItem = (fileProps = {}, level = 0) => {
+      createComponent({
+        file: { ...file('test.js'), ...fileProps },
+        level,
+      });
+      return wrapper.find('button');
+    };
+
+    it('renders treeitem role for files and folders', () => {
+      const button = createTreeItem();
+      expect(button.attributes('role')).toBe('treeitem');
+    });
+
+    it.each`
+      level | expectedAriaLevel
+      ${0}  | ${'1'}
+      ${2}  | ${'3'}
+    `('sets aria-level=$expectedAriaLevel when level=$level', ({ level, expectedAriaLevel }) => {
+      const button = createTreeItem({}, level);
+      expect(button.attributes('aria-level')).toBe(expectedAriaLevel);
+    });
+
+    it('does not render aria-setsize and aria-posinset (handled by parent components)', () => {
+      const button = createTreeItem({ ariaSetSize: 5, ariaPosInSet: 3 });
+      expect(button.attributes('aria-setsize')).toBeUndefined();
+      expect(button.attributes('aria-posinset')).toBeUndefined();
+    });
+
+    describe('folder-specific attributes', () => {
+      it.each`
+        opened   | expectedExpanded
+        ${true}  | ${'true'}
+        ${false} | ${'false'}
+      `(
+        'sets aria-expanded=$expectedExpanded when folder is opened=$opened',
+        ({ opened, expectedExpanded }) => {
+          const button = createTreeItem({ type: 'tree', opened });
+          expect(button.attributes('aria-expanded')).toBe(expectedExpanded);
+        },
+      );
+
+      it('does not set aria-expanded for files', () => {
+        const button = createTreeItem({ type: 'blob' });
+        expect(button.attributes('aria-expanded')).toBeUndefined();
+      });
+    });
+
+    it.each`
+      type      | name         | expectedLabel
+      ${'tree'} | ${'src'}     | ${'src'}
+      ${'blob'} | ${'test.js'} | ${'test.js'}
+    `('sets aria-label="$expectedLabel" for $type', ({ type, name, expectedLabel }) => {
+      const button = createTreeItem({ type, name });
+      expect(button.attributes('aria-label')).toBe(expectedLabel);
+    });
+  });
+
   describe('Show more button', () => {
     const findShowMoreButton = () => wrapper.findComponent(GlButton);
 
-- 
GitLab


From 123214e554f736f9e1a72ba1281b396003a6a219 Mon Sep 17 00:00:00 2001
From: jerasmus <jerasmus@gitlab.com>
Date: Mon, 6 Oct 2025 10:57:20 +0200
Subject: [PATCH 2/4] Fix failing tests

Fixed the failing ruby tests
---
 app/assets/javascripts/diffs/components/tree_list.vue  |  1 +
 .../file_tree_browser/components/tree_list.vue         |  1 +
 .../projects/repository/file_tree_browser_spec.rb      | 10 +++++-----
 3 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/app/assets/javascripts/diffs/components/tree_list.vue b/app/assets/javascripts/diffs/components/tree_list.vue
index f2becb6a7e5481..25ed8b87ad5850 100644
--- a/app/assets/javascripts/diffs/components/tree_list.vue
+++ b/app/assets/javascripts/diffs/components/tree_list.vue
@@ -290,6 +290,7 @@ export default {
         :item-size="rowHeight"
         :buffer="100"
         key-field="key"
+        role="tree"
         data-testid="tree-list-scroll"
       >
         <template #default="{ item, index }">
diff --git a/app/assets/javascripts/repository/file_tree_browser/components/tree_list.vue b/app/assets/javascripts/repository/file_tree_browser/components/tree_list.vue
index ed8c2f056b7b0b..ba5432cfc221d9 100644
--- a/app/assets/javascripts/repository/file_tree_browser/components/tree_list.vue
+++ b/app/assets/javascripts/repository/file_tree_browser/components/tree_list.vue
@@ -389,6 +389,7 @@ export default {
         :item-size="$options.ROW_HEIGHT"
         :buffer="100"
         key-field="id"
+        role="tree"
         class="gl-h-full gl-min-h-0 gl-flex-grow"
       >
         <template #default="{ item, index }">
diff --git a/spec/features/projects/repository/file_tree_browser_spec.rb b/spec/features/projects/repository/file_tree_browser_spec.rb
index 1281536fcea6f4..233d257806bedf 100644
--- a/spec/features/projects/repository/file_tree_browser_spec.rb
+++ b/spec/features/projects/repository/file_tree_browser_spec.rb
@@ -59,14 +59,14 @@
 
       within('.file-tree-browser') do
         # Should auto-expand parent directories
-        files_folder = find('[aria-label="files"]').ancestor('.file-row')
+        files_folder = find_button('files')
         expect(files_folder[:class]).to include('is-open')
 
-        ruby_folder = find('[aria-label="ruby"]').ancestor('.file-row')
+        ruby_folder = find_button('ruby')
         expect(ruby_folder[:class]).to include('is-open')
 
         # Should highlight the current file
-        popen_row = find('[aria-label="popen.rb"]').ancestor('.file-row')
+        popen_row = find_button('popen.rb')
         expect(popen_row['aria-current']).to eq('true')
       end
     end
@@ -121,11 +121,11 @@
   private
 
   def click_file(name)
-    find("[aria-label=\"#{name}\"]").click
+    find(".file-row[aria-label=\"#{name}\"]").click
     wait_for_requests
   end
 
   def have_file(name)
-    have_css("[aria-label=\"#{name}\"]")
+    have_css(".file-row[aria-label=\"#{name}\"]")
   end
 end
-- 
GitLab


From 50e07a5e8e09f22c310a14e2f6b76609bc4fdadd Mon Sep 17 00:00:00 2001
From: jerasmus <jerasmus@gitlab.com>
Date: Mon, 6 Oct 2025 12:51:19 +0200
Subject: [PATCH 3/4] Move aria attributes to the RecycleScroller

Moves the attributes to teh recycle scroller to fix the axe violations
---
 .../diffs/components/tree_list.vue            |  5 +-
 .../components/tree_list.vue                  |  5 +-
 .../vue_shared/components/file_row.vue        |  2 -
 .../diffs/components/tree_list_spec.js        | 16 +----
 .../components/tree_list_spec.js              | 12 ----
 .../vue_shared/components/file_row_spec.js    | 58 -------------------
 .../src/components/RecycleScroller.vue        |  4 ++
 7 files changed, 7 insertions(+), 95 deletions(-)

diff --git a/app/assets/javascripts/diffs/components/tree_list.vue b/app/assets/javascripts/diffs/components/tree_list.vue
index 25ed8b87ad5850..aaa7697632560f 100644
--- a/app/assets/javascripts/diffs/components/tree_list.vue
+++ b/app/assets/javascripts/diffs/components/tree_list.vue
@@ -290,10 +290,9 @@ export default {
         :item-size="rowHeight"
         :buffer="100"
         key-field="key"
-        role="tree"
         data-testid="tree-list-scroll"
       >
-        <template #default="{ item, index }">
+        <template #default="{ item }">
           <diff-file-row
             :file="item"
             :level="item.level"
@@ -303,8 +302,6 @@ export default {
             :style="{ '--level': item.level }"
             :class="{ 'tree-list-parent': item.level > 0 }"
             :tabindex="item.loading ? -1 : 0"
-            :aria-setsize="treeList.length"
-            :aria-posinset="index + 1"
             class="gl-relative"
             :data-file-row="item.fileHash"
             @toggleTreeOpen="$emit('toggleFolder', $event)"
diff --git a/app/assets/javascripts/repository/file_tree_browser/components/tree_list.vue b/app/assets/javascripts/repository/file_tree_browser/components/tree_list.vue
index ba5432cfc221d9..0bf536f0e33251 100644
--- a/app/assets/javascripts/repository/file_tree_browser/components/tree_list.vue
+++ b/app/assets/javascripts/repository/file_tree_browser/components/tree_list.vue
@@ -389,10 +389,9 @@ export default {
         :item-size="$options.ROW_HEIGHT"
         :buffer="100"
         key-field="id"
-        role="tree"
         class="gl-h-full gl-min-h-0 gl-flex-grow"
       >
-        <template #default="{ item, index }">
+        <template #default="{ item }">
           <file-row
             :file="item"
             :file-url="item.routerPath"
@@ -401,8 +400,6 @@ export default {
             :loading="item.loading"
             :tabindex="item.loading ? -1 : 0"
             :aria-current="isCurrentPath(item.path)"
-            :aria-setsize="filteredFlatFilesList.length"
-            :aria-posinset="index + 1"
             :style="{ '--level': item.level }"
             :class="{
               'tree-list-parent': item.level > 0,
diff --git a/app/assets/javascripts/vue_shared/components/file_row.vue b/app/assets/javascripts/vue_shared/components/file_row.vue
index 5019b0c406b68e..e0681558402941 100644
--- a/app/assets/javascripts/vue_shared/components/file_row.vue
+++ b/app/assets/javascripts/vue_shared/components/file_row.vue
@@ -146,8 +146,6 @@ export default {
     :title="textForTitle"
     :data-level="level"
     class="file-row"
-    role="treeitem"
-    :aria-level="level + 1"
     :aria-expanded="file.type === 'tree' ? file.opened.toString() : undefined"
     :aria-label="file.name"
     @click="clickFile"
diff --git a/spec/frontend/diffs/components/tree_list_spec.js b/spec/frontend/diffs/components/tree_list_spec.js
index 3f2ee8251cd3ed..a4ee48353b2191 100644
--- a/spec/frontend/diffs/components/tree_list_spec.js
+++ b/spec/frontend/diffs/components/tree_list_spec.js
@@ -39,7 +39,7 @@ describe('Diffs tree list component', () => {
           },
           {
             template:
-              '<div><template v-for="(item, index) in items"><slot :item="item" :index="index"></slot></template></div>',
+              '<div><template v-for="item in items"><slot :item="item"></slot></template></div>',
           },
         ),
       },
@@ -415,20 +415,6 @@ describe('Diffs tree list component', () => {
     });
   });
 
-  describe('ARIA tree view pattern', () => {
-    beforeEach(() => {
-      setupFilesInState();
-      createComponent();
-    });
-
-    it('applies ARIA attributes directly to file rows', () => {
-      const fileRow = getFileRow();
-
-      expect(fileRow.attributes('aria-setsize')).toBe('7');
-      expect(fileRow.attributes('aria-posinset')).toBe('1');
-    });
-  });
-
   describe('tree view buttons', () => {
     it.each`
       toggle                | renderTreeList
diff --git a/spec/frontend/repository/file_tree_browser/components/tree_list_spec.js b/spec/frontend/repository/file_tree_browser/components/tree_list_spec.js
index e5c95e62c70e90..60ff772bef2b9d 100644
--- a/spec/frontend/repository/file_tree_browser/components/tree_list_spec.js
+++ b/spec/frontend/repository/file_tree_browser/components/tree_list_spec.js
@@ -417,16 +417,4 @@ describe('Tree List', () => {
       expect(getQueryHandlerSuccess).toHaveBeenCalledTimes(2); // root + dir_0
     });
   });
-
-  describe('ARIA tree view pattern', () => {
-    it('applies ARIA attributes directly to file rows', () => {
-      const fileRows = findFileRows();
-
-      expect(fileRows.at(0).attributes('aria-setsize')).toBe('2');
-      expect(fileRows.at(0).attributes('aria-posinset')).toBe('1');
-
-      expect(fileRows.at(1).attributes('aria-setsize')).toBe('2');
-      expect(fileRows.at(1).attributes('aria-posinset')).toBe('2');
-    });
-  });
 });
diff --git a/spec/frontend/vue_shared/components/file_row_spec.js b/spec/frontend/vue_shared/components/file_row_spec.js
index fa246ea8b7f210..17454bec6f7642 100644
--- a/spec/frontend/vue_shared/components/file_row_spec.js
+++ b/spec/frontend/vue_shared/components/file_row_spec.js
@@ -224,64 +224,6 @@ describe('File row component', () => {
     expect(wrapper.findComponent(GlIcon).props('name')).toBe('link');
   });
 
-  describe('ARIA tree view pattern', () => {
-    const createTreeItem = (fileProps = {}, level = 0) => {
-      createComponent({
-        file: { ...file('test.js'), ...fileProps },
-        level,
-      });
-      return wrapper.find('button');
-    };
-
-    it('renders treeitem role for files and folders', () => {
-      const button = createTreeItem();
-      expect(button.attributes('role')).toBe('treeitem');
-    });
-
-    it.each`
-      level | expectedAriaLevel
-      ${0}  | ${'1'}
-      ${2}  | ${'3'}
-    `('sets aria-level=$expectedAriaLevel when level=$level', ({ level, expectedAriaLevel }) => {
-      const button = createTreeItem({}, level);
-      expect(button.attributes('aria-level')).toBe(expectedAriaLevel);
-    });
-
-    it('does not render aria-setsize and aria-posinset (handled by parent components)', () => {
-      const button = createTreeItem({ ariaSetSize: 5, ariaPosInSet: 3 });
-      expect(button.attributes('aria-setsize')).toBeUndefined();
-      expect(button.attributes('aria-posinset')).toBeUndefined();
-    });
-
-    describe('folder-specific attributes', () => {
-      it.each`
-        opened   | expectedExpanded
-        ${true}  | ${'true'}
-        ${false} | ${'false'}
-      `(
-        'sets aria-expanded=$expectedExpanded when folder is opened=$opened',
-        ({ opened, expectedExpanded }) => {
-          const button = createTreeItem({ type: 'tree', opened });
-          expect(button.attributes('aria-expanded')).toBe(expectedExpanded);
-        },
-      );
-
-      it('does not set aria-expanded for files', () => {
-        const button = createTreeItem({ type: 'blob' });
-        expect(button.attributes('aria-expanded')).toBeUndefined();
-      });
-    });
-
-    it.each`
-      type      | name         | expectedLabel
-      ${'tree'} | ${'src'}     | ${'src'}
-      ${'blob'} | ${'test.js'} | ${'test.js'}
-    `('sets aria-label="$expectedLabel" for $type', ({ type, name, expectedLabel }) => {
-      const button = createTreeItem({ type, name });
-      expect(button.attributes('aria-label')).toBe(expectedLabel);
-    });
-  });
-
   describe('Show more button', () => {
     const findShowMoreButton = () => wrapper.findComponent(GlButton);
 
diff --git a/vendor/assets/javascripts/vue-virtual-scroller/src/components/RecycleScroller.vue b/vendor/assets/javascripts/vue-virtual-scroller/src/components/RecycleScroller.vue
index ea3c5aa12c1a3b..b11eee8385665e 100644
--- a/vendor/assets/javascripts/vue-virtual-scroller/src/components/RecycleScroller.vue
+++ b/vendor/assets/javascripts/vue-virtual-scroller/src/components/RecycleScroller.vue
@@ -22,6 +22,7 @@
       ref="wrapper"
       :style="{ [direction === 'vertical' ? 'minHeight' : 'minWidth']: totalSize + 'px' }"
       class="vue-recycle-scroller__item-wrapper"
+      role="tree"
     >
       <div
         v-for="view of pool"
@@ -32,6 +33,9 @@
           left: !useTransform && direction !== 'vertical' ? `${view.position}px` : null,
         } : null"
         class="vue-recycle-scroller__item-view"
+        role="treeitem"
+        :aria-setsize="items.length"
+        :aria-posinset="view.nr.index + 1"
         :class="{ hover: hoverKey === view.nr.key, 'will-change-transform': useTransform }"
         @mouseenter="hoverKey = view.nr.key"
         @mouseleave="hoverKey = null"
-- 
GitLab


From 67de834bb3bd10cd13e1b35d3b53914e20e6f78e Mon Sep 17 00:00:00 2001
From: jerasmus <jerasmus@gitlab.com>
Date: Mon, 6 Oct 2025 15:24:31 +0200
Subject: [PATCH 4/4] Add automated accessibility testing

Added accessibility testing for the FTB
---
 spec/features/projects/repository/file_tree_browser_spec.rb | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/spec/features/projects/repository/file_tree_browser_spec.rb b/spec/features/projects/repository/file_tree_browser_spec.rb
index 233d257806bedf..7374ba0af2220b 100644
--- a/spec/features/projects/repository/file_tree_browser_spec.rb
+++ b/spec/features/projects/repository/file_tree_browser_spec.rb
@@ -35,6 +35,10 @@
       end
     end
 
+    it 'passes axe automated accessibility testing' do
+      expect(page).to be_axe_clean.within('.file-tree-browser')
+    end
+
     it 'navigates to a file' do
       within('.file-tree-browser') do
         click_file('README.md')
-- 
GitLab