Auro Layover Component - HTML5 Popover Implementation

[jason-capsule42]

Introduction

The Layover component is intended to be a single point of entry for all implementations of the native HTML5 popover spec. It should contain multiple behaviors such as dialog, tooltip, dropdown, and more that allow a consumer to quickly and easier create elements that use the HTML5 native popover spec and behave in those ways.

It serves to:

• Implement native HTML5 popover spec that was intended to be used with FloatingUI but that was missing from our current solution
• Refactor code that has grown organically into a structure that better meets our needs
• Improve our ability to support WCAG 2.2 a11y criteria with components like dialog, drawer, and popover, as well as elements that use full-screen dialogs and dropdowns such as Formkit's select, combobox, and more

It should:

• Implement the HTML5 native popover spec
• Allow for any number of behaviors (dialog, dropdown, etc.)
  • Each behavior should be clearly defined
  • The behavior of a layover component should be able to be changed at any time
• Ensure full a11y of all behaviors
• Tightly control the desired UX for each behavior

HTML5 Popover Spec

https://developer.mozilla.org/en-US/docs/Web/API/Popover_API/Using

Utilities and Components To Support This Solution

• auro-layover

  • Core component for this work

• Supporting Code from auro-library

  • FocusTrap - utility class
  • PopoverPositioner - utility class (our Floating UI implementation)
  • StringBoolean - custom lit property converter

Technical Details

auro-library

Focus Trapping

Enables trapping the focus within a specified element when the user shifts focus using the tab key

Popover Positioner (controller)

Exposes controls and methods for implementing Floating UI.

StringBoolean

Allows for string boolean values to be attached to attributes, e.g.:

<auro-elem myState=”true”></auro-elem>

auro-layover

Triggers

• Trigger slot projects desired trigger content
  • Can be any type of element(s)
  • Content is projected into an HTML5 button element internally

Popover

• Type is set automatically by specifying the behavior, but can be overwritten for custom functionality via type attribute.
• Types
  • auto - browser default behaviors (events associated with the below) (CAVEAT only works with button triggers - HTML5 element with type="button")
    • space/enter on trigger to toggle
    • esc to close
    • click outside to close
    • click to toggle
  • manual - have to write your own event handlers for open/close
  • hint - e.g. tooltip that shows on hover/focus

Arrow

• FloatingUI/PopoverPositioner expose the ability to have a positioned arrow
  • Layover provides a slot: arrow
  • Layover exposes a related property: arrowPosition
  • Example usage: auro-popover would create a CSS caret that points to the target element and project it into this slot

Render

• Popover spec provides a pseudo-element :backdrop for popovers when they are projected to the top of the document.
  • Variables provide access to key styles for the background to allow consumers to customize it:
    • Background:
      • Variable: --auro-layover-backdrop-background
      • Default: transparent
    • Backdrop Filter:
      • Variable: --auro-layover-backdrop-filter
      • Default: none
    • Opacity
      • Variable: --auro-layover-backdrop-opacity
      • Default: 1
    • Transition:
      • Variable: --auro-layover-backdrop-transition
      • Default: none

Behaviors

Each behavior has a default configuration.

• Dialog

  • Handles any unpositioned popovers such as:
    • Dialog
    • Drawer
  • Has “fullscreen” version*

• Dropdown

  • Handles all positioned popovers such as
    • Combobox
    • Select
    • Datepicker

• Input

  • Ties an input to a popover
  • Input-specific properties:
    • showOnFocus
      • Shows the popover when the input receives focus
      • Default: true
    • showOnChange
      • Shows the popover when the input value changes
      • Default: true
    • hideOnNoValue
      • Hides the popover when the input has no value
      • Default: true
    • minInputLength
      • The minimum length the input value must be before the popover shows
      • Also hides the popover if the input value drops below defined threshold
      • Default: undefined
  • Has “fullscreen” version*

• Tooltip

  • Handles hover-based positioned tooltips such as:
    • auro-popover

Configuration can be customized per behavior.

• useHide - auto-hide when trigger not in viewport
• useFlip - currently our noFlip attribute but reversed
• useShift - nudge the popover to fit in viewport
• inline - only enable this on auro components that might use inline elements in the trigger slot
• useAutoPlacement
• placement - default placement
• offset - distance between trigger and popover
• allowBodyScroll - false by default
• disabled - only controlled by the component directly implementing the layover (dropdown, dialog, drawer, popover)

* Full Screen Handling

• Available for dialog and input behavior
• Ensures width, height, and position styles are applied to make popover fullscreen
• Modifies some behaviors
  • Input:
    • Does not bind to blur for fullscreen

Events

• Exposes public events for consumption
  • auro-layover-shown
    • Fires when the layover shows the popover element
    • Payload:
      • target: the popover that emitted the event
      • newState: the new state of the popover (“shown”)
  • auro-layover-hidden
    • Fires when the layover hides the popover element
    • Payload:
      • target: the popover that emitted the event
      • newState: the new state of the popover (“hidden”)
  • auro-layover-change
    • Fires when the popover visibility changes
    • Payload:
      • target: the popover that emitted the event
      • newState: the new state of the popover (“shown” or “hidden”)
  • auro-layover-beforechange
    • Fires when the popover visibility is going to change, but hasn’t yet
    • Payload:
      • target: the popover that emitted the event
      • newState: what the new state will be once the lifecycle is complete (“shown” or “hidden”)

A11Y

• Handled largely by the popover spec:
  • Creates an implicit aria connection between trigger and popover
  • Browser handles aria-expanded, aria-controls, etc.
  • Aria attributes are not injected by the browser
  • Button text content determines label for popover

What Problems Were Discovered and Addressed During Development

Current Patch Caveat

• Current functionality relies on a side effect of using bibtemplate, which wraps content in a single Shadow DOM.
• This containment preserves tab order, avoiding known issues with native popover tabbing in several browsers.
• The behavior is not intentional or robust; it’s a fragile workaround rather than a reliable implementation. Reusing popovers outside of bibtemplate would require custom shimming to replicate this behavior.
• This adds unnecessary complexity and long-term maintenance overhead.

Non-Dialog Usage with Popover

• When the user can interact with the page when a popover is visible, such as with a dropdown, if there are multiple such elements on the page, clicking on a second one causes a poor UX:

  • New element opens
  • Old element closes
  • Old element’s trigger gets focus
  • Browser scrolls to old element’s trigger

• Our solution resolves this issue

Visible Encapsulation of Dropdowns in Dialogs

• When a dropdown exists in a dialog, and the dialog contains a scrollable area, the dropdown’s trigger element may move outside of the viewable area.
• For this use case, our solution hides the dropdown when the trigger element moves outside of the viewable area, and shows it again when it returns to the viewable area

“Passive Focus” Solution

• The current implementation automatically shifts focus to the first element in the popover, which can lead to unexpected UI states and suboptimal user experience.

• The proposed solution introduces a "Passive Focus" mechanism that mimics the browser’s native popover focus behavior while enhancing it with a focus trap to maintain accessibility and control.

• Example Use Case w/ Current Implementation:

  • User opens a full screen select
  • The close button is focused
  • User selects an element with the keyboard controls
  • The close button is still showing visible focus
  • Will hitting enter select the menu element, or close the dialog, or both?

• Example Use Case w/ New Implementation

  • User opens a full screen select
  • The layover component does not shift focus, but adds a listener for the next “Tab” or “Shift + Tab”
  • If the user performs a tab interaction, focus shifts to the appropriate element in the popover, and focus becomes trapped
  • If the user does not perform a tab interaction, no element is focused
  • UX is clearer since there is no visible focus on the close button

Refactoring for Maintainability and Clarity

• The current implementation has grown organically and combines several concerns in a single component (AuroFloatingUI), making it harder to extend or maintain.

  • AuroFloatingUI is responsible for rendering, positioning (via FloatingUI), event handling, behavior management (e.g., Dropdown), and more, which stretches its scope beyond a single responsibility.

• The updated approach aims to improve modularity and maintainability by applying SOLID principles more explicitly.

  • While some pragmatic shortcuts were necessary to meet deadlines, the refactor moves toward a clearer separation of concerns.
  • Proposed Final Structure:
    • Layover
      • Focused solely on rendering and positioning (via FloatingUI).
      • Exposes clean, minimal interfaces for external control.
    • Behavior Manager
      • Accepts a behavior definition and manages the Layover instance accordingly.
      • Encapsulates logic for implementing behaviors in a reusable, testable way.
    • Behavior Definitions
      • Self-contained configurations or classes (e.g., Dialog, Dropdown) defining specific UI behaviors.
      • Passed to the Behavior Manager to enable pluggable, consistent interaction patterns.
  • This structure improves code readability, testability, and scalability, while maintaining flexibility for future use cases.

Open Questions

• How does the screen reader handle nested popovers and what is inert and what is not?

• Does it still need to be in auro-dialog?

• Does it still need to be in auro-drawer?

• A11y

  • Knowledge/Functionality Gaps:
    • What should the screen reader read when a popover is opened?
      • Is this the behavior we see when we open our layover?
    • Do we need to support a label for the actual popover to be read to the user when the layover opens/closes?
  • Known Issues
    • Button expanded/collapsed state is not read on initial button focus
  • Other a11y Work
    • Needs full ally audit

• Future Work

  • Abstracting Input Functionality
    • Code currently exists to bind an input to a popover, but it resides in layover when it should probably be abstracted into its own file to maintain single-responsibility.
    • Questions:

• Is there any good reason to keep this in layover rather than abstract it?

  • Negative impacts on behavior management?
  • Does code complexity stay reasonable when abstracting?

• What type of code best suits our current and future needs?

  • Option 1: Component
    • Could reside in its own repo
    • Could be a part of Formkit
      • Could be a new type of input and extended/implemented by combobox
      • Could be optional functionality tied to input and used by combobox
  • Option 2: Service
    • Would probably reside in auro-library