(home) make doc list easier to navigate with screen readers / kb

- using one big `<a>` tag wrapping the whole row is not that great for SR users as it gets pretty difficult to understand each part of the row. now the link is actually only on the doc name, but the whole row is still clickable thanks to a "stretchableLink" helper (taken from bootstrap) - adding some hidden "workspace" text before each workspace to help SR users understand context - hiding the doc icon from SR users as its purely decorative - make the document dots button targettable through keyboard + understandable for SR users
gristlabs · georgegevoian · Aug 12, 2025 · Jul 17, 2025 · Jul 23, 2025 · Jul 17, 2025
commit c1b9959baa5626977ca586fe1170b1512a379e69
diff --git a/app/client/ui/DocList.ts b/app/client/ui/DocList.ts
@@ -20,7 +20,8 @@ import {
 } from "app/client/ui2018/cssVars";
 import { IconName } from "app/client/ui2018/IconList";
 import { icon as cssIcon } from "app/client/ui2018/icons";
-import { unstyledH2, unstyledUl } from "app/client/ui2018/unstyled";
+import { unstyledButton, unstyledH2, unstyledUl } from "app/client/ui2018/unstyled";
+import { stretchedLink } from "app/client/ui2018/stretchedLink";
 import { visuallyHidden } from "app/client/ui2018/visuallyHidden";
 import { menu, menuItem, select } from "app/client/ui2018/menus";
 import { confirmModal, saveModal } from "app/client/ui2018/modals";
@@ -159,7 +160,6 @@ export class DocList extends Disposable {
               dom.forEach(docs, (doc) => {
                 return cssDocRow(
                   cssDoc(
-                    urlState().setLinkUrl(docUrl(doc)),
                     cssDoc.cls("-no-access", !roles.canView(doc.access)),
                     cssDocIconAndName(
                       buildDocIcon(
@@ -168,10 +168,12 @@ export class DocList extends Disposable {
                           docName: doc.name,
                           icon: doc.options?.appearance?.icon,
                         },
-                        testId("doc-icon")
+                        testId("doc-icon"),
+                        {'aria-hidden': 'true'},
                       ),
                       cssDocNameAndBadges(
                         cssDocName(
+                          urlState().setLinkUrl(docUrl(doc)),
                           stripIconFromName(doc.name, Boolean(doc.options?.appearance?.icon?.emoji)),
                           testId("doc-name")
                         ),
@@ -187,7 +189,10 @@ export class DocList extends Disposable {
                     ),
                     cssDocWorkspace(
                       dom.show(this._showWorkspace),
-                      workspaceName(this._home.app, doc.workspace),
+                      dom('span',
+                        visuallyHidden(t("Workspace")),
+                        workspaceName(this._home.app, doc.workspace)
+                      ),
                       testId("doc-workspace")
                     ),
                     cssDocEditedAt(
@@ -218,6 +223,7 @@ export class DocList extends Disposable {
                         parentSelectorToMark: "." + cssDocRow.className,
                       }),
                       dom.on("click", (ev) => stopEvent(ev)),
+                      {'aria-label': t("Document options - {{- documentName }}", {documentName: `"${doc.name}"`})},
                       testId("doc-options")
                     ),
                     contextMenu(() => makeDocOptionsMenu(this._home, doc), {
@@ -508,19 +514,14 @@ const cssDocRow = styled("li", `
   }
 `);
 
-const cssDoc = styled("a", `
+const cssDoc = styled("div", `
   display: flex;
+  position: relative;
   align-items: center;
   border-radius: 3px;
   outline: none;
   padding: 8px;
 
-  &, &:hover, &:focus {
-    text-decoration: none;
-    outline: none;
-    color: inherit;
-  }
-
   &-no-access, &-no-access:hover, &-no-access:focus {
     color: ${theme.disabledText};
     cursor: not-allowed;
@@ -587,7 +588,7 @@ const noAccessStyles = `
   }
 `;
 
-const cssDocName = styled("div", `
+const cssDocName = styled(stretchedLink, `
   font-size: 14px;
   flex: 0 1 auto;
   white-space: nowrap;
@@ -596,6 +597,17 @@ const cssDocName = styled("div", `
   color: ${theme.text};
   font-weight: 600;
 
+  &, &:hover, &:focus {
+    text-decoration: none;
+    outline: none;
+    color: inherit;
+  }
+
+  &:focus-visible {
+    outline-offset: -3px;
+    padding: 5px;
+  }
+
   ${noAccessStyles}
 
   @media ${mediaMedium} {
@@ -660,7 +672,9 @@ const cssDocEditedAt = styled(cssEditedAtColumn, `
   }
 `);
 
-const cssDocOptions = styled("div", `
+const cssDocOptions = styled(unstyledButton, `
+  position: relative;
+  z-index: 2; /* make sure this is above the stretched link row */
   flex: none;
   display: flex;
   justify-content: center;

diff --git a/app/client/ui2018/stretchedLink.ts b/app/client/ui2018/stretchedLink.ts
@@ -0,0 +1,17 @@
+/**
+ * A link that has a clickable area that spans the entire containing block.
+ *
+ * Don't forget to apply the `position: relative` CSS property to the parent block you want the link to cover.
+ *
+ * @see https://getbootstrap.com/docs/5.3/helpers/stretched-link
+ */
+import {styled} from 'grainjs';
+
+export const stretchedLink = styled('a', `
+  &::after {
+    position: absolute;
+    inset: 0;
+    content: '';
+    z-index: 1;
+  }
+`);
diff --git a/static/locales/en.client.json b/static/locales/en.client.json
@@ -2040,6 +2040,7 @@
         "Sort by name": "Sort by name",
         "Unpin": "Unpin",
         "Workspace": "Workspace",
+        "Document options - {{- documentName }}": "Document options - {{- documentName }}",
         "Documents list": "Documents list"
     },
     "RenameDocModal": {