# 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. {% hint style="danger" %} 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. {% endhint %} ### 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. {% hint style="info" %} If `AccessibleName` is not set, `aria-label` falls back to the control's `Name` property. {% endhint %} ### 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 `
` 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.wisej.com/docs/whats-new-in-4.1/accessibility.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.