From 830aab511fface6c670031f00178f02a9b995930 Mon Sep 17 00:00:00 2001 From: nmahesh Date: Mon, 3 Nov 2025 18:03:26 +0530 Subject: [PATCH] docs(AC-28): elaborate ListBox.js comments and add AC-28.md (pre-assigned issue) --- AC-28.md | 35 +++++++++++++++++++++++++++++++++ test-app/src/widgets/ListBox.js | 35 ++++++++++++++++++++++++++------- 2 files changed, 63 insertions(+), 7 deletions(-) create mode 100644 AC-28.md diff --git a/AC-28.md b/AC-28.md new file mode 100644 index 0000000..02e771c --- /dev/null +++ b/AC-28.md @@ -0,0 +1,35 @@ +## Pre-assigned issue: Elaborate comments in `test-app/src/widgets/ListBox.js` (AC-28) + +This file represents the GitHub-tracked, pre-assigned issue for the documentation-only change made on branch `feature/AC-28-assigning-tasks-to-gh-copilot`. + +Title: Elaborate comments in ListBox.js + +Assignee: @nmahesh-cainc + +Summary +------- +Before making changes, the team requested a small documentation update to clarify why certain UI/accessibility behaviors are implemented in `ListBox.js`. + +This pre-assigned issue corresponds exactly to the comment-only edits present in `test-app/src/widgets/ListBox.js` on branch `feature/AC-28-assigning-tasks-to-gh-copilot`. + +Changes included (documentation-only): +- Clarified why the list container is moved to the front when opening the dropdown (to avoid clipping by siblings). +- Documented the focus transfer from the collapsed control to the drop-down list for keyboard and assistive tech. +- Explained the visual arrow/chevron drawing code and that it is purely visual. +- Clarified the drop-down blur behavior that collapses the list and returns logical focus. + +Acceptance criteria +------------------- +- All edits are comment-only; no executable code is modified. +- The repo builds and lints with the same behavior as prior to the change. +- The branch `feature/AC-28-assigning-tasks-to-gh-copilot` contains the edited `ListBox.js` and this `AC-28.md` file. + +References +---------- +- Branch: `feature/AC-28-assigning-tasks-to-gh-copilot` +- File: `test-app/src/widgets/ListBox.js` +- Jira: https://curriculumassociates.atlassian.net/browse/AC-28 + +Notes for reviewers +------------------- +This is a documentation-only change intended to improve code readability and ease future maintenance. Please verify the diff is comment-only before merging. diff --git a/test-app/src/widgets/ListBox.js b/test-app/src/widgets/ListBox.js index 605e462..f0b28b8 100644 --- a/test-app/src/widgets/ListBox.js +++ b/test-app/src/widgets/ListBox.js @@ -55,11 +55,15 @@ export default class ListBox extends createjs.Container { this._dropDownView.visible = !this._dropDownView.visible; this._collapsedView.accessible.expanded = this._dropDownView.visible; if (this._dropDownView.visible) { - // make sure the listbox is on top of its sibling DisplayObjects to try - // to ensure that the dropdown is completely visible + // When the dropdown becomes visible we want it to render above any + // sibling display objects so it is not clipped or hidden. Reparenting + // this container to the end of the parent's children list achieves + // that by drawing it on top. this.parent.addChild(this); - // move focus from the expand button to the drop down list element + // Transfer keyboard focus from the collapsed "expand" button into + // the drop-down list so assistive tech (and keyboard users) can + // immediately interact with the options. this._dropDownView.accessible.requestFocus(); } @@ -69,13 +73,21 @@ export default class ListBox extends createjs.Container { _onCollapedViewKeyDown(evt) { if (evt.keyCode === KeyCodes.down || evt.keyCode === KeyCodes.up) { - // make sure the listbox is on top of its sibling DisplayObjects to try to ensure - // that the dropdown is completely visible + // When navigating with up/down keys from the collapsed control we + // open the drop-down and bring this container to the front so the + // list is fully visible to sighted users. This mirrors the click + // behavior above and keeps keyboard interaction consistent. this.parent.addChild(this); + // Show the drop-down and mark the collapsed control as expanded for + // accessibility APIs. Then move logical focus into the drop-down + // so subsequent key events act on the list items. this._dropDownView.visible = true; this._collapsedView.accessible.expanded = this._dropDownView.visible; this._dropDownView.accessible.requestFocus(); + + // Update which option is considered selected based on arrow key + // direction (down -> next, up -> previous). this._updateSelectedOption( this._getAdjacentOption(evt.keyCode === KeyCodes.down) ); @@ -160,16 +172,22 @@ export default class ListBox extends createjs.Container { const bg = new createjs.Shape(); bg.graphics.beginFill('#ffffff').drawRect(0, 0, width, height); // main background const dropBoxLeft = width - height; + // Draw the arrow background area on the right-hand side of the + // collapsed control that visually indicates there is a drop-down. bg.graphics .endStroke() .beginFill('#aaaaaa') - .drawRect(dropBoxLeft, 0, height, height); // arrow background to indicate drop down + .drawRect(dropBoxLeft, 0, height, height); + // Draw the chevron/arrow symbol centered inside the arrow area. This is + // purely visual and does not affect accessibility behavior; the + // accessible.hasPopUp flag and focus handling provide the programmatic + // affordances. bg.graphics .endFill() .beginStroke('#000000') .moveTo(dropBoxLeft + height * 0.25, height * 0.25) .lineTo(dropBoxLeft + height * 0.5, height * 0.75) - .lineTo(dropBoxLeft + height * 0.75, height * 0.25); // arrow + .lineTo(dropBoxLeft + height * 0.75, height * 0.25); bg.graphics .beginStroke('#000000') .setStrokeStyle(1) @@ -196,6 +214,9 @@ export default class ListBox extends createjs.Container { parent: this, }); this._dropDownView.accessible.tabIndex = -1; + // When the drop-down loses focus we close it. This handler mirrors the + // click/keyboard interactions so that focus-out from the list collapses + // the drop-down and returns logical focus to the collapsed control. this._dropDownView.addEventListener('blur', (evt) => { if (this._dropDownView.visible) { this._onCollapedViewClick(evt);