feat(table): the type cell can provide a disclosure on extra-long types

- scrollable container for overflow tables
- styling of certain columns
- a11y screenreader enhancements

Author: marissahuysentruyt

blocks/table/table.css

@@ -4,7 +4,10 @@
   --table-border-width: 1px;
   --table-head-row-padding-block: 7px;
   --table-body-row-padding-block: 11px;
+  --table-scroll-hint-width: var(--s2-spacing-700);
+  --table-scroll-hint-color: var(--se-body-background-color);
 
+  position: relative;
   container-type: inline-size;
   container-name: table-wrapper;
   margin-block: var(--s2-spacing-500) var(--s2-spacing-800);
@@ -71,6 +74,25 @@
 
   .table-cell-value {
     grid-column: 2;
+    min-inline-size: 0;
+  }
+
+  .table-type-cell {
+    se-disclosure {
+      /* Bound intrinsic sizing without fixing the other table columns. */
+      inline-size: 100%;
+      max-inline-size: 28rem;
+    }
+
+    > .table-cell-value:not(:has(se-disclosure)) {
+      background-color: rgb(from var(--s2-gray-1000) r g b / 8%);
+      font-family: monospace;
+      padding: 2px;
+      border-radius: 3px;
+      font-size: var(--s2-component-s-medium-font-size);
+      color: var(--s2-gray-800);
+      inline-size: fit-content;
+    }
   }
 
   tbody td svg {
@@ -94,9 +116,40 @@
     position: relative;
   }
 
-  @container table-wrapper (width >= 650px) {
+  .table-scroll {
     overflow-x: auto;
 
+    /* Leave room for focus rings on links at the first and last rows. */
+    padding-block: var(--s2-spacing-100);
+    margin-block: calc(var(--s2-spacing-100) * -1);
+  }
+
+  /* Keep the hint outside the scroller so it stays at the visible edge. */
+  &::after {
+    content: '';
+    position: absolute;
+    inset-block: 0;
+    inset-inline-end: 0;
+    inline-size: var(--table-scroll-hint-width);
+    background: linear-gradient(to right, transparent, var(--table-scroll-hint-color));
+    opacity: 0;
+    pointer-events: none;
+    transition: opacity 0.2s ease;
+  }
+
+  &:dir(rtl)::after {
+    background: linear-gradient(to left, transparent, var(--table-scroll-hint-color));
+  }
+
+  &[data-scroll-hint]::after {
+    opacity: 1;
+  }
+
+  @container table-wrapper (width >= 650px) {
+    .table-type-cell:has(se-disclosure) {
+      min-inline-size: 16rem;
+    }
+
     table {
       border-collapse: separate;
       border-spacing: 0;
@@ -212,3 +265,9 @@
     background-color: transparent;
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .table::after {
+    transition: none;
+  }
+}

blocks/table/table.js

@@ -1,5 +1,6 @@
 import { getConfig } from '../../scripts/ak.js';
 import { getComponentProps } from '../../scripts/utils/extraction-status.js';
+import '../../deps/se/se.js';
 
 const config = getConfig();
 
@@ -40,6 +41,7 @@ const EXCLUDED_SOURCES = new Set([
 // `kind`/`values`/`optional` back the playground's controls; this table shows the
 // human-readable `type` instead.
 const EXCLUDED_COLUMNS = new Set(['status', 'since', 'kind', 'values', 'optional']);
+const TYPE_DISCLOSURE_THRESHOLD = 500;
 
 /**
  * The column-header text repeated inside a body cell. Only the narrow stacked layout
@@ -62,6 +64,30 @@ const buildCellValue = () => {
   return value;
 };
 
+const buildDescription = (text) => {
+  const content = document.createDocumentFragment();
+  const tokens = /(?<!`)(`+)(?!`)([\s\S]*?)(?<!`)\1(?!`)|(?<!!)\[([^\]]+)\]\((https?:\/\/(?:[^()\s]|\([^()\s]*\))+)\)/gi;
+  let offset = 0;
+  for (const match of text.matchAll(tokens)) {
+    const [markdown, backticks, codeText, label, href] = match;
+    let node;
+    if (backticks) {
+      node = document.createElement('code');
+      node.textContent = codeText;
+    } else if (label.trim() && URL.canParse(href)) {
+      node = document.createElement('a');
+      node.href = href;
+      node.append(buildDescription(label));
+    }
+    if (node) {
+      content.append(text.slice(offset, match.index), node);
+      offset = match.index + markdown.length;
+    }
+  }
+  content.append(text.slice(offset));
+  return content;
+};
+
 const buildTableElement = (headerCells, dataCells) => {
   const tableHead = document.createElement('thead');
   tableHead.classList.add('header-row');
@@ -152,14 +178,68 @@ const buildDataTable = async (href) => {
   const dataCells = rows.map((props) => properties.map((key) => {
     const tableCell = document.createElement('td');
     const value = buildCellValue();
-    value.textContent = props[key] || '-';
+    const resolvedValue = props[key] || '-';
+    if (key === 'property'
+      || key === 'attribute'
+      || key === 'type'
+      || (key === 'default' && resolvedValue !== '-')) {
+      tableCell.classList.add('table-type-cell');
+    }
+    if (key === 'type' && typeof props[key] === 'string' && props[key].length > TYPE_DISCLOSURE_THRESHOLD) {
+      const disclosure = document.createElement('se-disclosure');
+      disclosure.setAttribute('preview', '');
+      disclosure.setAttribute('label', `Expand to view more about ${props.attribute || props.property || 'this property'}`);
+      disclosure.textContent = resolvedValue;
+      value.append(disclosure);
+    } else if (key === 'description' && typeof resolvedValue === 'string') {
+      value.append(buildDescription(resolvedValue));
+    } else {
+      value.textContent = resolvedValue;
+    }
     tableCell.append(value);
     return tableCell;
   }));
 
   return buildTableElement(headerCells, dataCells);
 };
 
+const buildScroller = (table, labelIds) => {
+  const scroller = document.createElement('div');
+  scroller.className = 'table-scroll';
+  scroller.tabIndex = 0;
+  if (labelIds.length) {
+    scroller.role = 'region';
+    scroller.setAttribute('aria-labelledby', labelIds.join(' '));
+  }
+  scroller.append(table);
+  return scroller;
+};
+
+const watchScrollHint = (el, scroller, instructions) => {
+  const update = () => {
+    const overflow = scroller.scrollWidth - scroller.clientWidth;
+    const remaining = overflow - Math.abs(scroller.scrollLeft);
+    el.toggleAttribute('data-scroll-hint', remaining > 1);
+    const descriptionId = overflow > 1 ? instructions.id : null;
+    if (scroller.getAttribute('aria-describedby') !== descriptionId) {
+      instructions.hidden = !descriptionId;
+      if (descriptionId) {
+        scroller.setAttribute('aria-describedby', descriptionId);
+      } else {
+        scroller.removeAttribute('aria-describedby');
+      }
+    }
+  };
+  update();
+  // Measure again when styles, content, or the surrounding layout change.
+  const observer = new ResizeObserver(update);
+  observer.observe(scroller);
+  observer.observe(scroller.querySelector('table'));
+  scroller.addEventListener('scroll', update, { passive: true });
+  window.addEventListener('resize', update, { passive: true });
+  document.fonts?.ready.then(update);
+};
+
 export default async function init(el) {
   const dataHref = el.querySelector('a[href$=".json"]')?.href;
 
@@ -187,5 +267,14 @@ export default async function init(el) {
     return heading.id;
   });
   if (table && labelIds.length) { table.setAttribute('aria-labelledby', labelIds.join(' ')); }
-  el.tabIndex = 0;
+  if (table) {
+    const scroller = buildScroller(table, labelIds);
+    const instructions = document.createElement('span');
+    instructions.id = `table-scroll-instructions-${Math.random().toString(36).slice(2)}`;
+    instructions.className = 'visually-hidden';
+    instructions.textContent = 'Scrollable table. Use the left and right arrow keys to view more.';
+    instructions.hidden = true;
+    el.replaceChildren(scroller, instructions);
+    watchScrollHint(el, scroller, instructions);
+  }
 }

test/a11y/accessibility.homepage.spec.js

@@ -3,7 +3,7 @@ import { test, expect } from './axe-test.js';
 
 // TODO: these are current skipped right now because aem.page (the proxy) is gated
 test.describe('homepage', () => {
-  test.skip('should not have any automatically detectable accessibility issues', async ({ page }) => {
+  test('should not have any automatically detectable accessibility issues', async ({ page }) => {
     await page.goto('/');
     await page.waitForLoadState('networkidle');
 
@@ -12,7 +12,7 @@ test.describe('homepage', () => {
     expect(accessibilityScanResults.violations).toEqual([]);
   });
 
-  test.skip('should not have any automatically detectable WCAG 2.2 A or AA violations', async ({ page, makeAxeBuilder }) => {
+  test('should not have any automatically detectable WCAG 2.2 A or AA violations', async ({ page, makeAxeBuilder }) => {
     await page.goto('/');
     await page.waitForLoadState('networkidle');