@stack-spot/portal-layout 0.0.10 → 0.0.12

package/dist/utils.js

@@ -5,4 +5,84 @@ export function valueOfLayoutVar(varname) {
         return '';
     return valueOf(varname, layout);
 }
+/**
+ * Important for accessibility.
+ *
+ * Makes it so we focus the next focusable element in the DOM hierarchy, disregarding the element passed as parameter and its children.
+ *
+ * If there's no next focusable element, the first focusable of the page will be focused. If the page doesn't contain any focusable
+ * element, nothing happens.
+ *
+ * @param current the reference element to focus the next. If not provided, will be the currently active element.
+ */
+export function focusNextIgnoringChildren(current) {
+    current = current ?? document.activeElement;
+    while (current && !current.nextElementSibling) {
+        current = current?.parentElement;
+    }
+    current = current?.nextElementSibling;
+    while (current && current.tabIndex < 0) {
+        current = (current.children.length ? current.firstChild : current.nextElementSibling);
+    }
+    if (current)
+        current?.focus?.();
+    else
+        focusFirstChild(document);
+}
+const selectors = {
+    a: 'a[href]:not(:disabled)',
+    button: 'button:not(:disabled)',
+    input: 'input:not(:disabled):not([type="hidden"])',
+    select: 'textarea:not(:disabled)',
+    textarea: 'select:not(:disabled)',
+    other: '[tabindex]:not([tabindex="-1"])',
+};
+/**
+ * Focus the first focusable child of the element provided. If the element has no focusable child, nothing happens.
+ *
+ * A priority list can be passed in the second parameter, as an option. If it's provided, it will focus the first element according to the
+ * list.
+ *
+ * An ignore query selector can also be passed in the options parameter. If the first focusable element matches the query selector, the
+ * next element is focused instead.
+ *
+ * @example
+ * Suppose the children of element are: h1, button, p, input, select.
+ * 1. We don't pass a priority list. The focused element will be the button.
+ * 2. Our priority list is ['button']. The focused element will be the button.
+ * 3. Our priority list is ['input', 'button']. The focused element will be the input.
+ * 4. Our priority list is ['select', 'input']. The focused element will be the select.
+ * 5. Our priority list is [['select', 'input'], 'button']. The focused element will be the input.
+ *
+ * @param element the element to search a child to focus.
+ * @param options optional.
+ */
+export function focusFirstChild(element, { priority = [], ignore } = {}) {
+    let focusable;
+    let missing = ['a', 'button', 'input', 'other', 'select', 'textarea'];
+    for (const p of priority) {
+        const tags = Array.isArray(p) ? p : [p];
+        const querySelectors = tags.map(t => {
+            missing = missing.filter(tag => tag != t);
+            return selectors[t];
+        });
+        focusable = element?.querySelectorAll(querySelectors.join(', '));
+        if (focusable)
+            break;
+    }
+    if (!focusable) {
+        element?.querySelectorAll(missing.map(t => selectors[t]).join(', '));
+    }
+    let elementToFocus;
+    for (const f of focusable ?? []) {
+        if (!ignore || !f.matches(ignore)) {
+            const styles = window.getComputedStyle(f);
+            if (styles.display != 'none' && styles.visibility != 'hidden') {
+                elementToFocus = f;
+                break;
+            }
+        }
+    }
+    elementToFocus?.focus?.();
+}
 //# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAElD,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,MAAM,MAAM,GAAG,QAAQ,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAA;IAChD,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAA;IACtB,OAAO,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;AACjC,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@stack-spot/portal-layout",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "peerDependencies": {
-    "@citric/core": ">=5.3.1",
-    "@citric/icons": ">=5.3.1",
-    "@citric/ui": ">=5.3.1",
+    "@citric/core": ">=5.4.0",
+    "@citric/icons": ">=5.4.0",
+    "@citric/ui": ">=5.4.0",
     "@stack-spot/portal-theme": ">=0.0.4",
     "@stack-spot/portal-translate": ">=0.0.5",
     "react": ">=18.2.0",

package/src/Layout.tsx

@@ -1,8 +1,8 @@
 import { CSSToCitricAdapter, listToClass, WithStyle } from '@stack-spot/portal-theme'
 import '@stack-spot/portal-theme/dist/theme.css'
-import { ReactElement, ReactNode } from 'react'
+import { ReactElement, ReactNode, useEffect } from 'react'
 import { ErrorBoundary } from './components/error/ErrorBoundary'
-import { DescriptionFn, ErrorDescriptor } from './components/error/ErrorDescriptor'
+import { DescriptionFn, ErrorHandler, ErrorManager } from './components/error/ErrorManager'
 import { SilentErrorBoundary } from './components/error/SilentErrorBoundary'
 import { Header, HeaderProps } from './components/Header'
 import { MenuContent } from './components/menu/MenuContent'
@@ -18,6 +18,7 @@ interface Props extends WithStyle {
   children: ReactNode,
   extra?: ReactNode,
   errorDescriptor?: DescriptionFn,
+  onError?: ErrorHandler,
 }
 
 interface RawProps extends WithStyle {
@@ -28,10 +29,11 @@ interface RawProps extends WithStyle {
   compactMenu?: boolean,
   extra?: ReactNode,
   errorDescriptor?: DescriptionFn,
+  onError?: ErrorHandler,
 }
 
 export const RawLayout = (
-  { menuSections, menuContent, header, compactMenu = true, children, extra, errorDescriptor, className, style }: RawProps,
+  { menuSections, menuContent, header, compactMenu = true, children, extra, errorDescriptor, onError, className, style }: RawProps,
 ) => {
   // @ts-ignore
   const { bottomDialog, modal, rightPanel } = overlay.useOverlays()
@@ -41,7 +43,11 @@ export const RawLayout = (
     menuSections ? undefined : 'no-menu-sections',
     className,
   ]
-  if (errorDescriptor) ErrorDescriptor.setDescriptionFunction(errorDescriptor)
+
+  useEffect(() => {
+    if (errorDescriptor) ErrorManager.setDescriptionFunction(errorDescriptor)
+    if (onError) ErrorManager.setErrorHandler(onError)
+  }, [])
 
   return (
     <CSSToCitricAdapter>
@@ -55,10 +61,10 @@ export const RawLayout = (
           <nav id="menuContent"><SilentErrorBoundary>{menuContent}</SilentErrorBoundary></nav>
           {menuSections && <nav id="menuSections"><SilentErrorBoundary>{menuSections}</SilentErrorBoundary></nav>}
         </aside>
-        <div id="rightPanel"><ErrorBoundary>{rightPanel}</ErrorBoundary></div>
-        <div id="bottomDialog"><ErrorBoundary>{bottomDialog}</ErrorBoundary></div>
+        <div id="bottomDialog" role="dialog"><ErrorBoundary>{bottomDialog}</ErrorBoundary></div>
         <div id="backdrop">
-          <div id="modal"><ErrorBoundary>{modal}</ErrorBoundary></div>
+          <div id="rightPanel" aria-modal role="dialog"><ErrorBoundary>{rightPanel}</ErrorBoundary></div>
+          <div id="modal" aria-modal role="dialog"><ErrorBoundary>{modal}</ErrorBoundary></div>
         </div>
         <Toaster />
       </div>
@@ -71,7 +77,7 @@ const MenuContentRenderer = ({ content }: Required<Pick<Props['menu'], 'content'
   return <MenuContent {...menuContent} />
 }
 
-export const Layout = ({ menu, header, children, extra, errorDescriptor, className, style }: Props) => (
+export const Layout = ({ menu, header, children, extra, errorDescriptor, onError, className, style }: Props) => (
   <RawLayout
     header={<Header {...header} />}
     menuSections={menu.sections ? <MenuSections {...menu} /> : undefined}
@@ -81,6 +87,7 @@ export const Layout = ({ menu, header, children, extra, errorDescriptor, classNa
     }
     compactMenu={menu.compact}
     errorDescriptor={errorDescriptor}
+    onError={onError}
     extra={extra}
     className={className}
     style={style}

package/src/LayoutOverlayManager.tsx

@@ -3,11 +3,12 @@
 import { Button } from '@citric/core'
 import { ReactElement, useLayoutEffect, useState } from 'react'
 import { Dialog, DialogOptions } from './components/Dialog'
-import { OverlayContent, OverlayContentProps } from './components/OverlayContent'
+import { CLOSE_OVERLAY_ID, OverlayContent, OverlayContentProps } from './components/OverlayContent'
 import { getDictionary } from './dictionary'
+import { LayoutElements, elementIds, getLayoutElements } from './elements'
 import { ElementNotFound, LayoutError } from './errors'
 import { showToaster as showReactToaster } from './toaster'
-import { valueOfLayoutVar } from './utils'
+import { focusFirstChild, valueOfLayoutVar } from './utils'
 
 interface AlertOptions extends Omit<DialogOptions, 'cancel'> {
   showButton?: boolean,
@@ -16,14 +17,6 @@ interface AlertOptions extends Omit<DialogOptions, 'cancel'> {
 type BottomDialogOptions = Omit<DialogOptions, 'title'>
 type OverlaySize = 'small' | 'medium' | 'large'
 type ModalSize = 'fit-content' | OverlaySize
-
-interface LayoutElements {
-  backdrop: HTMLElement | null,
-  modal: HTMLElement | null,
-  rightPanel: HTMLElement | null,
-  bottomDialog: HTMLElement | null,
-}
-
 type SetContentFn = ((content: ReactElement | undefined) => void) | undefined
 
 interface OverlayContentSetter {
@@ -42,11 +35,6 @@ interface CustomRightPanelOptions {
   onClose?: () => void,
 }
 
-const BACKDROP_ID = 'backdrop'
-const MODAL_ID = 'modal'
-const BOTTOM_DIALOG_ID = 'bottomDialog'
-const RIGHT_PANEL_ID = 'rightPanel'
-
 class LayoutOverlayManager {
   static readonly instance?: LayoutOverlayManager
   private setContent: OverlayContentSetter = {}
@@ -54,17 +42,20 @@ class LayoutOverlayManager {
   private onModalClose?: () => void
 
   private setupElements() {
-    this.elements = {
-      modal: document.getElementById(MODAL_ID),
-      backdrop: document.getElementById(BACKDROP_ID),
-      bottomDialog: document.getElementById(BOTTOM_DIALOG_ID),
-      rightPanel: document.getElementById(RIGHT_PANEL_ID),
-    }
+    this.elements = getLayoutElements()
     this.elements.backdrop?.addEventListener('click', (event) => {
-      if (this.elements?.modal && !this.elements.modal.contains(event.target as Node)) {
-        this.closeModal()
-      }
+      if (this.isModalOpen() && !this.elements?.modal?.contains?.(event.target as Node)) this.closeModal()
+      if (this.isRightPanelOpen() && !this.elements?.rightPanel?.contains?.(event.target as Node)) this.closeRightPanel()
     })
+    this.elements.backdrop?.addEventListener('keydown', (event) => {
+      if (event.key !== 'Escape') return
+      if (this.isModalOpen()) this.closeModal()
+      if (this.isRightPanelOpen()) this.closeRightPanel()
+      event.preventDefault()
+    })
+    this.setInteractivity(this.elements?.modal, false)
+    this.setInteractivity(this.elements?.rightPanel, false)
+    this.setInteractivity(this.elements?.bottomDialog, false)
   }
 
   // this should actually be like Kotlin's "internal", i.e. private to any user of the lib, but public to the lib itself.
@@ -82,13 +73,57 @@ class LayoutOverlayManager {
     return { modal, rightPanel, bottomDialog }
   }
 
+  private setInteractivity(element: HTMLElement | null | undefined, interactive: boolean) {
+    if (interactive) {
+      element?.removeAttribute('inert')
+      element?.removeAttribute('aria-hidden')
+    } else {
+      element?.setAttribute('aria-hidden', '')
+      element?.setAttribute('inert', '')
+    }
+  }
+
+  private setMainContentInteractivity(interactive: boolean) {
+    this.setInteractivity(this.elements?.page, interactive)
+    this.setInteractivity(this.elements?.header, interactive)
+    this.setInteractivity(this.elements?.menu, interactive)
+  }
+
+  private showOverlay(element: HTMLElement | null | undefined, extraClasses: string[] = []) {
+    element?.classList.add('visible', ...extraClasses)
+    this.setInteractivity(element, true)
+    this.setMainContentInteractivity(false)
+    setTimeout(() => focusFirstChild(
+      element,
+      { priority: [['input', 'textarea', 'select', 'other', 'button']], ignore: `#${CLOSE_OVERLAY_ID}` },
+    ), 50)
+  }
+
+  private hideOverlay(element: HTMLElement | null | undefined) {
+    element?.setAttribute('class', '')
+    this.setInteractivity(element, false)
+    this.setMainContentInteractivity(true)
+  }
+
+  isModalOpen() {
+    return this.elements?.modal?.classList.contains('visible') ?? false
+  }
+
+  isRightPanelOpen() {
+    return this.elements?.rightPanel?.classList.contains('visible') ?? false
+  }
+
+  isBottomDialogOpen() {
+    return this.elements?.bottomDialog?.classList.contains('visible') ?? false
+  }
+
   showCustomModal(content: React.ReactElement, { size = 'medium', onClose }: CustomModalOptions = {}) {
-    if (!this.elements?.modal) throw new ElementNotFound('modal', MODAL_ID)
+    if (!this.elements?.modal) throw new ElementNotFound('modal', elementIds.modal)
     if (!this.setContent.modal) throw new LayoutError('unable to show modal, because it has not been setup yet.')
     this.onModalClose = onClose
     this.setContent.modal(content)
     this.elements.backdrop?.setAttribute('class', 'visible')
-    this.elements.modal.setAttribute('class', `visible ${size}`)
+    this.showOverlay(this.elements.modal, [size])
   }
 
   showModal({ size, ...props }: OverlayContentProps & { size?: ModalSize }) {
@@ -127,7 +162,7 @@ class LayoutOverlayManager {
   }
 
   showBottomDialog({ message, cancel, confirm }: BottomDialogOptions): Promise<boolean> {
-    if (!this.elements?.bottomDialog) throw new ElementNotFound('bottom dialog', BOTTOM_DIALOG_ID)
+    if (!this.elements?.bottomDialog) throw new ElementNotFound('bottom dialog', elementIds.bottomDialog)
     if (!this.setContent.bottomDialog) throw new LayoutError('unable to show bottom dialog, because it has not been setup yet.')
     return new Promise((resolve) => {
       this.setContent.bottomDialog?.(
@@ -139,17 +174,20 @@ class LayoutOverlayManager {
           </div>
         </>,
       )
-      this.elements?.bottomDialog?.setAttribute('class', 'visible')
+      this.showOverlay(this.elements?.bottomDialog)
     })
   }
 
   showCustomRightPanel(content: ReactElement, { size = 'medium', onClose }: CustomRightPanelOptions = {}) {
-    if (!this.elements?.rightPanel) throw new ElementNotFound('right panel overlay', RIGHT_PANEL_ID)
+    if (!this.elements?.rightPanel) throw new ElementNotFound('right panel overlay', elementIds.rightPanel)
     if (!this.setContent.rightPanel) throw new LayoutError('unable to show right panel overlay, because it has not been setup yet.')
     this.onModalClose = onClose
     this.setContent.rightPanel(content)
     this.elements?.rightPanel.classList.add(size)
-    setTimeout(() => this.elements?.rightPanel?.classList?.add('visible'))
+    setTimeout(() => {
+      this.elements?.backdrop?.setAttribute('class', 'visible')
+      this.showOverlay(this.elements?.rightPanel)
+    })
   }
 
   showRightPanel({ size, ...props }: OverlayContentProps & { size?: OverlaySize }) {
@@ -169,7 +207,7 @@ class LayoutOverlayManager {
     setTimeout(
       () => {
         if (this.setContent.modal) this.setContent.modal(undefined)
-        this.elements?.modal?.setAttribute('class', '')
+        this.hideOverlay(this.elements?.modal)
       },
       parseFloat(valueOfLayoutVar('--modal-animation-duration')) * 1000,
     )
@@ -177,6 +215,7 @@ class LayoutOverlayManager {
 
   closeRightPanel(runCloseListener = true) {
     this.elements?.rightPanel?.classList.remove('visible')
+    this.elements?.backdrop?.setAttribute('class', '')
     if (runCloseListener && this.onModalClose) {
       this.onModalClose()
       this.onModalClose = undefined
@@ -184,14 +223,14 @@ class LayoutOverlayManager {
     setTimeout(
       () => {
         if (this.setContent.rightPanel) this.setContent.rightPanel(undefined)
-        this.elements?.rightPanel?.removeAttribute('class')
+        this.hideOverlay(this.elements?.rightPanel)
       },
       parseFloat(valueOfLayoutVar('--right-panel-animation-duration')) * 1000,
     )
   }
 
   closeBottomDialog() {
-    this.elements?.bottomDialog?.setAttribute('class', '')
+    this.hideOverlay(this.elements?.bottomDialog)
   }
 
   isInsideModal(element: HTMLElement) {

package/src/components/OverlayContent.tsx

@@ -6,6 +6,8 @@ import { ReactNode } from 'react'
 import { styled } from 'styled-components'
 import { useDictionary } from '../dictionary'
 
+export const CLOSE_OVERLAY_ID = 'close-overlay'
+
 export interface OverlayContentProps extends WithStyle {
   title: string,
   subtitle?: string,
@@ -48,7 +50,7 @@ export const OverlayContent = ({ children, title, subtitle, className, style, on
           <Text appearance={type === 'modal' ? 'h3' : 'h4'}>{title}</Text>
           {subtitle && <Text appearance="body2" colorScheme="light.700">{subtitle}</Text>}
         </Flex>
-        <IconButton onClick={onClose} title={t.close} aria-label={t.close}><TimesMini /></IconButton>
+        <IconButton onClick={onClose} title={t.close} aria-label={t.close} id={CLOSE_OVERLAY_ID}><TimesMini /></IconButton>
       </header>
       {children}
     </ContentBox>

package/src/components/SelectionList.tsx

@@ -2,6 +2,7 @@ import { Flex, IconBox, Text } from '@citric/core'
 import { ArrowLeft, Check, ChevronRight } from '@citric/icons'
 import { IconButton } from '@citric/ui'
 import { WithStyle, listToClass, theme } from '@stack-spot/portal-theme'
+import { Dictionary, useTranslate } from '@stack-spot/portal-translate'
 import { ReactElement, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { styled } from 'styled-components'
 import { Action } from './types'
@@ -39,8 +40,10 @@ interface CurrentItemList {
 }
 
 const ANIMATION_DURATION_MS = 300
+const MAX_HEIGHT_TRANSITION = `max-height ease-in ${ANIMATION_DURATION_MS / 1000}s`
 
 export interface SelectionListProps extends WithStyle {
+  id?: string,
   visible?: boolean,
   items: ListItem[],
   onHide?: () => void,
@@ -50,14 +53,21 @@ export interface SelectionListProps extends WithStyle {
   scroll?: boolean,
 }
 
+interface RenderOptions {
+  setCurrent: (current: CurrentItemList) => void,
+  controllerId?: string,
+  onClose?: () => void,
+}
+
 const SelectionBox = styled.div<{ $maxHeight: string, $scroll?: boolean }>`
   max-height: 0;
   overflow-y: ${({ $scroll }) => $scroll ? 'auto' : 'hidden'};
   overflow-x: hidden;
-  transition: max-height ease-in ${ANIMATION_DURATION_MS / 1000}s;
+  transition: ${MAX_HEIGHT_TRANSITION}, visibility 0s ${ANIMATION_DURATION_MS / 1000}s;
   z-index: 1;
   box-shadow: 4px 4px 48px #000;
   border-radius: 0.5rem;
+  visibility: hidden;
 
   .selection-list-content {
     display: flex;
@@ -80,7 +90,7 @@ const SelectionBox = styled.div<{ $maxHeight: string, $scroll?: boolean }>`
   li > a {
     gap: 4px;
     transition: background-color 0.2s;
-    &:hover {
+    &:hover, &:focus {
       background: ${theme.color.light['400']};
     }
     .label {
@@ -100,13 +110,20 @@ const SelectionBox = styled.div<{ $maxHeight: string, $scroll?: boolean }>`
 
   &.visible {
     max-height: ${({ $maxHeight }) => $maxHeight};
+    visibility: visible;
+    transition: ${MAX_HEIGHT_TRANSITION};
   }
 `
 
-function renderAction({ label, href, onClick, icon, iconRight, active }: ListAction) {
+function renderAction({ label, href, onClick, icon, iconRight, active }: ListAction, { onClose }: RenderOptions) {
+  function handleClick() {
+    onClick?.()
+    onClose?.()
+  }
+
   return (
     <li key={label} className="action">
-      <a href={href} onClick={onClick}>
+      <a href={href} onClick={handleClick} tabIndex={0}>
         {icon && <IconBox>{icon}</IconBox>}
         <Text appearance="body2" className="label">{label}</Text>
         {iconRight && <IconBox>{iconRight}</IconBox>}
@@ -116,10 +133,15 @@ function renderAction({ label, href, onClick, icon, iconRight, active }: ListAct
   )
 }
 
-function renderCollapsible({ label, icon, iconRight, children }: ListCollapsible, setCurrent: (current: CurrentItemList) => void) {
+function renderCollapsible({ label, icon, iconRight, children }: ListCollapsible, { setCurrent, controllerId }: RenderOptions) {
+  function handleClick(ev: React.MouseEvent) {
+    // accessibility: this will tell the screen reader the section was expanded before this link is removed from the DOM.
+    (ev.target as HTMLElement)?.setAttribute?.('aria-expanded', 'true')
+    setCurrent({ items: children, label })
+  }
   return (
     <li key={label} className="collapsible">
-      <a onClick={() => setCurrent({ items: children, label })}>
+      <a onClick={handleClick} tabIndex={0} aria-expanded={false} aria-controls={controllerId}>
         {icon && <IconBox>{icon}</IconBox>}
         <Text appearance="body2" className="label">{label}</Text>
         {iconRight && <IconBox>{iconRight}</IconBox>}
@@ -129,68 +151,120 @@ function renderCollapsible({ label, icon, iconRight, children }: ListCollapsible
   )
 }
 
-function renderSection({ label, children }: ListSection, setCurrent: (current: CurrentItemList) => void) {
+function renderSection({ label, children }: ListSection, options: RenderOptions) {
   return (
     <li key={label ?? children.map(c => c.label).join('-')} className="section">
       {label && <Text appearance="overheader2" colorScheme="primary" className="section-title">{label}</Text>}
-      <ul>{children.map(i => renderItem(i, setCurrent))}</ul>
+      <ul>{children.map(i => renderItem(i, options))}</ul>
     </li>
   )
 }
 
-function renderItem(item: ListItem, setCurrent: (current: CurrentItemList) => void) {
+function renderItem(item: ListItem, options: RenderOptions) {
   if ('children' in item) {
-    return item.type === 'section' ? renderSection(item, setCurrent) : renderCollapsible(item, setCurrent)
+    return item.type === 'section' ? renderSection(item, options) : renderCollapsible(item, options)
   }
-  return renderAction(item)
+  return renderAction(item, options)
 }
 
 export const SelectionList = ({
-  items, className, style, visible = true, maxHeight = '300px', onHide, before, after, scroll,
+  id, items, className, style, visible = true, maxHeight = '300px', onHide, before, after, scroll,
 }: SelectionListProps) => {
+  const t = useTranslate(dictionary)
   const wrapper = useRef<HTMLDivElement>(null)
-  const itemsRef = useRef(items)
   const [current, setCurrent] = useState<CurrentItemList>({ items })
+
   const listItems = useMemo(
-    () => current.items.map(i => renderItem(i, (next: CurrentItemList) => setCurrent({ ...next, parent: current }))),
+    () => current.items.map(i => renderItem(
+      i,
+      {
+        setCurrent: (next: CurrentItemList) => setCurrent({ ...next, parent: current }),
+        onClose: onHide,
+        controllerId: id,
+      },
+    )),
     [current],
   )
-  const hide = useCallback((event: MouseEvent) => {
+
+  const keyboardControls = useCallback((event: KeyboardEvent) => {
+    const target = event?.target as HTMLElement | null
+
+    function getSelectableAnchors() {
+      return wrapper.current?.querySelectorAll('li.action a, li.collapsible a, button') ?? []
+    }
+
+    function handleArrows() {
+      const anchors = getSelectableAnchors()
+      let i = 0
+      while (i < anchors.length && document.activeElement !== anchors[i]) i++
+      const next: any = event.key === 'ArrowDown' ? (anchors[i + 1] ?? anchors[0]) : (anchors[i - 1] ?? anchors[anchors.length - 1])
+      next?.focus?.()
+    }
+
+    const handlers: Record<string, (() => void) | undefined> = {
+      Escape: () => {
+        onHide?.()
+        event.stopPropagation()
+        event.preventDefault()
+      },
+      Enter: () => target?.click(),
+      Tab: () => {
+        const anchors = getSelectableAnchors()
+        if (document.activeElement === anchors[anchors.length - 1]) onHide?.()
+      },
+      ArrowUp: handleArrows,
+      ArrowDown: handleArrows,
+    }
+
+    handlers[event.key]?.()
+  }, [])
+
+  const hide = useCallback((event: Event) => {
     const target = (event.target as HTMLElement | null)
     // if the element is not in the DOM anymore, we'll consider the click was inside the selection list
     const isClickInsideSelectionList = !target?.isConnected || wrapper.current?.contains(target)
     const isAction = target?.classList?.contains('action') || !!target?.closest('.action')
-    if (!isClickInsideSelectionList || isAction) {
-      if (onHide) onHide()
-      setTimeout(() => setCurrent({ items: itemsRef.current }), ANIMATION_DURATION_MS)
-      document.removeEventListener('click', hide)
-    }
+    if (!isClickInsideSelectionList || isAction) onHide?.()
   }, [])
 
   useEffect(() => {
-    if (!onHide) return
-    if (visible) setTimeout(() => document.addEventListener('click', hide), 50)
+    if (visible) {
+      setCurrent({ items })
+      document.addEventListener('keydown', keyboardControls)
+      if (onHide) setTimeout(() => document.addEventListener('click', hide), 50)
+    }
+    else {
+      document.removeEventListener('keydown', keyboardControls)
+      document.removeEventListener('click', hide)
+    }
   }, [visible])
 
-  useEffect(() => {
-    itemsRef.current = items
-    if (!wrapper.current?.classList.contains('visible')) setCurrent({ items })
-  }, [items])
-
   return (
     <SelectionBox
+      id={id}
       ref={wrapper}
       $maxHeight={maxHeight}
       style={style}
       className={listToClass(['selection-list', visible ? 'visible' : undefined, className])}
       $scroll={scroll}
+      aria-hidden={!visible}
     >
       <div className="selection-list-content">
         {before}
         {current.parent
           ? (
             <Flex mt={5} mb={1} alignItems="center">
-              <IconButton onClick={() => setCurrent(current.parent ?? { items })} sx={{ mr: 3 }}>
+              <IconButton
+                onClick={(ev) => {
+                  // accessibility: this will tell the screen reader the section was collapsed before this button is removed from the DOM.
+                  (ev.target as HTMLElement)?.setAttribute?.('aria-expanded', 'false')
+                  setCurrent(current.parent ?? { items })
+                }}
+                sx={{ mr: 3 }}
+                title={t.back}
+                aria-controls={id}
+                aria-expanded={true}
+              >
                 <ArrowLeft />
               </IconButton>
               <Text appearance="microtext1">{current.label}</Text>
@@ -204,3 +278,12 @@ export const SelectionList = ({
     </SelectionBox>
   )
 }
+
+const dictionary = {
+  en: {
+    back: 'Go back',
+  },
+  pt: {
+    back: 'Voltar',
+  },
+} satisfies Dictionary