Accessibility

Introduction

Wisej.NET 4.1 adds a concrete accessibility layer to the client-side widget stack instead of relying only on generic DOM output. The implementation now assigns semantic ARIA roles, updates ARIA state attributes as widget state changes, and propagates accessible names and descriptions from server-side controls down to the actual interactive element in the browser.

This improves three areas at the same time:

• Assistive technology support, because screen readers and other tools can inspect a more accurate accessibility tree.

• Browser automation, because tools can target controls by role, label, and state instead of brittle CSS or DOM structure.

• AI-based inspection, including Playwright MCP workflows, because the accessibility tree exposes the intent of the UI instead of only its rendered HTML.

What Changed

The current 4.1 implementation introduces these accessibility behaviors:

• AccessibleName is rendered as aria-label.

• AccessibleDescription is rendered as aria-description.

• Roles are assigned directly in the widget layer using setRole(...).

• Dynamic ARIA states are updated using setAriaAttribute(...).

• Several composite Wisej controls redirect accessibility metadata to the inner editable or clickable subcontrol instead of the outer container.

• Child controls are named in the DOM, and automation IDs are also applied to accessibility targets when present.

The AccessibleRole enumeration and the AccessibleRole property were removed in 4.1.

Changing the semantic role of a control is no longer supported, because the role is defined by the control itself.

Accessible Name and Description

All Wisej components support:

Server-side property	Browser output	Notes
AccessibleName	aria-label	Used as the accessible name exposed in the accessibility tree.
AccessibleDescription	aria-description	Used as the accessible description exposed in the accessibility tree.

On the client side this is implemented in wisej.Mixins.js, which applies the attributes to the control's accessibility element, not always to the outermost widget container.

If AccessibleName is not set, aria-label falls back to the control's Name property.

Accessibility Target Redirection

Several controls expose accessibility metadata on the element users actually interact with:

Control	Accessibility target
wisej.web.TextBoxBase	Inner text field
wisej.web.TextBox	Inner text field
wisej.web.ComboBox	Inner text field when visible, otherwise the combo box itself
wisej.web.DateTimePicker	Inner text field
wisej.web.LabelWrapper	Wrapped editor's accessibility target
wisej.web.TabControl.TabPage	Tab button
wisej.web.datagrid.ColumnHeader	Header widget

This matters because AccessibleName, AccessibleDescription, and automation IDs are applied to the target returned by getAccessibilityTarget() when a control implements it.

Supported Roles and ARIA States

The table below shows the current roles and attributes supported in Wisej.NET 4.1.

Area / widget	Role	ARIA attributes updated	Notes
Window	dialog	-	Applied to qx.ui.window.Window.
Tree, VirtualTree	tree	-	Applied to tree containers.
Tree item	treeitem	-	Applied to tree nodes.
ToolBar	toolbar	-	Applied to toolbar containers.
ToolBar radio button	radio	aria-checked	Qooxdoo toolbar radio buttons update checked state.
TabView	tablist	-	Applied to the tab strip container.
Tab page	tabpanel	aria-expanded	Applied to the page container.
Tab button	tab	aria-selected	Applied to the page's button.
Table / DataGrid base table widget	grid	-	Applied to qx.ui.table.Table.
Table header cell	columnheader	-	Applied to header cells.
Menu container	menu	-	Applied to popup menus.
Menu item	menuitem	-	Applied when menu children are added.
Menu check box	checkbox	aria-checked	Qooxdoo menu checkbox support.
Menu radio button	radio	aria-checked	Applied to popup menu radio items.
Scroll bar	scrollbar	aria-orientation, aria-valuemax, aria-valuenow	Horizontal and vertical orientation are updated explicitly.
Toggle button	button	aria-checked	Updates checked, including mixed for tri-state.
Text field	textbox	-	Applied to single-line text input.
Text area	textbox	aria-multiline	Marks multi-line editing support.
Split button	button	-	Applied to split button root widget.
Standard button	button	-	Includes generic push buttons.
Menu button	button	-	Used for buttons that open menus.
Abstract select box	button	aria-haspopup="listbox", aria-expanded	Base behavior inherited by select-box style controls.
Combo box	combobox	inherited popup state from select-box patterns	Explicit role is applied by the combo box widget.
Slider	slider	-	Applied to slider widgets.
Radio group	radiogroup	-	Applied to grouped radio button containers.
Radio button	radio	aria-checked	Applied to standard radio buttons.
Check box	checkbox	aria-checked	Applied to standard check boxes.
Menubar	menubar	-	Applied to menu bars.
List and selection-backed items	-	aria-selected	Applied to selectable items through selection infrastructure.
Wisej menu items	inherited menu item semantics	aria-checked	Wisej popup menu items update checked state when used as checked or radio-style menu items.
Wisej toolbar buttons and split buttons	inherited button semantics	aria-checked	Wisej toolbar items update checked state for toggle-like behavior.

Selection, Checked, Expanded, and Other Dynamic States

The current implementation updates the following ARIA states dynamically:

ARIA attribute	Where it is used
aria-checked	Check boxes, radio buttons, toolbar toggle items, checked menu items, radio-style menu items, tri-state toggle buttons
aria-selected	Tab buttons and selection-managed list items
aria-expanded	Tab pages and select-box style controls
aria-haspopup	Select-box style controls with popup lists
aria-multiline	Text areas
aria-orientation	Scroll bars
aria-pressed	Toggle button initialization
aria-description	Any Wisej control with AccessibleDescription
aria-label	Any Wisej control with AccessibleName

Why This Helps AI and Playwright MCP

The accessibility layer is not only for screen readers. It also makes application inspection much more reliable for automation and AI tools.

When Playwright or an MCP tool inspects the application through the accessibility tree, it can see:

• The role of the control, such as button, textbox, tab, grid, or dialog.

• The accessible name from AccessibleName or from the control's visible label.

• The accessible description from AccessibleDescription.

• State information such as checked, selected, expanded, multiline, or orientation.

That enables more stable interaction patterns such as:

• getByRole("button", { name: "Save" })

• getByRole("textbox", { name: "Customer Name" })

• getByRole("tab", { name: "Orders" })

• Accessibility-tree based inspection instead of DOM-class based guessing

For AI agents this is especially important because the accessibility tree is a semantic representation of the UI. A model can infer that something is a tab, dialog, or checked menu item much more reliably than from nested <div> elements. In practice this means:

• Better control identification

• Less dependence on fragile DOM structure

• Better reasoning about current widget state

• More reliable automation in Playwright MCP and similar tooling

Wisej also applies automation IDs to accessibility targets when a control exposes one. This helps bridge semantic inspection and deterministic element targeting in automated scenarios.

Implementation Notes

• The accessibility support in 4.1 is implemented primarily in the client-side widget layer.

• Composite controls do not always expose accessibility metadata on the outer widget. In many cases the metadata is intentionally routed to the real focus or input target.

• Menu and toolbar overflow items clone the original command surface into popup menus. Those clones also benefit from the underlying menu semantics and checked-state updates.

Summary

Wisej.NET 4.1 now provides a real accessibility implementation rather than only passive markup. Roles, accessible names, descriptions, and state attributes are assigned in the widget layer and forwarded to the correct interactive element. This benefits assistive technologies, improves test automation, and makes AI and Playwright MCP inspection significantly more reliable when working from the accessibility tree.