From e8640a8c8159157ae075504707c3789ec3b3a4e3 Mon Sep 17 00:00:00 2001 From: Nagashri Date: Thu, 6 Nov 2025 14:22:43 +0530 Subject: [PATCH 1/2] Improve inline comments for better readability in SpinButton.js --- test-app/src/widgets/SpinButton.js | 129 +++++++++++++++++++++++++---- 1 file changed, 114 insertions(+), 15 deletions(-) diff --git a/test-app/src/widgets/SpinButton.js b/test-app/src/widgets/SpinButton.js index a659188..68e9597 100644 --- a/test-app/src/widgets/SpinButton.js +++ b/test-app/src/widgets/SpinButton.js @@ -1,28 +1,56 @@ import AccessibilityModule from '@curriculumassociates/createjs-accessibility'; import Button from './Button'; +/** + * SpinButton widget for CreateJS accessibility library. + * + * This class implements a spin button control that allows users to increment or decrement + * a numeric value through button clicks or keyboard input. It provides ARIA-compliant + * accessibility features and integrates with the CreateJS accessibility module. + * + * The spin button consists of increment and decrement buttons, and displays the current + * value in an associated text container. It supports minimum and maximum value constraints + * and provides visual focus indicators. + */ export default class SpinButton extends createjs.Container { + /** + * Constructor for the SpinButton widget. + * + * @param {Object} options - Configuration options for the spin button + * @param {number} options.maxValue - Maximum allowed value + * @param {number} options.minValue - Minimum allowed value + * @param {number} options.width - Width of the spin button in pixels + * @param {number} options.height - Height of the spin button in pixels + * @param {createjs.Text} textContainer - Text object that displays the current value + * @param {Function} callback - Function called when the value changes + */ constructor({ options, textContainer, callback }) { super(); + + // Extract configuration values from options const { maxValue, minValue } = options; this.minValue = minValue; this.maxValue = maxValue; this.targetContainer = textContainer; this.callback = callback; + // Store dimensions for getter methods this._width = options.width; this._height = options.height; + + // Initialize current value from text container and ensure it's numeric this.currentValue = Number(textContainer.text); textContainer.text = this.currentValue; + // Register with accessibility module to provide ARIA spinbutton functionality AccessibilityModule.register({ accessibleOptions: { max: maxValue, min: minValue, - readOnly: false, - required: true, - tabIndex: 0, - value: this.currentValue, + readOnly: false, // Allow user input + required: true, // Value must be provided + tabIndex: 0, // Make focusable via keyboard navigation + value: this.currentValue, // Current numeric value }, displayObject: this, role: AccessibilityModule.ROLES.SPINBUTTON, @@ -50,34 +78,52 @@ export default class SpinButton extends createjs.Container { ], }); + // Set container bounds for proper layout this.setBounds(0, 0, this.width, this.height); + + // Create visual focus indicator this.setupFocusIndicator(this.width, this.height); + + // Create increment and decrement buttons this.createButtons(); } + /** + * Creates the increment and decrement buttons for the spin button. + * + * The buttons are positioned vertically - increment on top, decrement on bottom. + * Both buttons share the same width as the spin button and half the height each. + */ createButtons() { + // Configuration for button creation const options = { type: 'button', - value: '+', - name: 'Increment', + value: '+', // Will be changed for decrement button + name: 'Increment', // Will be changed for decrement button enabled: true, autoFocus: true, width: this.width, - height: this.height * 0.5, + height: this.height * 0.5, // Each button takes half the height }; - // Increment button + + // Create increment button with '+' symbol this.incBtn = new Button(options, 0, this.onIncrement.bind(this)); this.addChild(this.incBtn); - // Decrement button + // Create decrement button with '-' symbol, positioned below increment button options.value = '-'; options.name = 'Decrement'; this.decBtn = new Button(options, 0, this.onDecrement.bind(this)); this.addChild(this.decBtn); - - this.decBtn.y = this.height * 0.5; + this.decBtn.y = this.height * 0.5; // Position below increment button } + /** + * Handles increment event - increases the current value by 1. + * + * Respects the maximum value constraint. If incrementing would exceed max, + * the value is set to the maximum instead. + */ onIncrement() { this.currentValue = this.currentValue + 1 > this.maxValue @@ -86,6 +132,12 @@ export default class SpinButton extends createjs.Container { this.updateTargetValue(); } + /** + * Handles decrement event - decreases the current value by 1. + * + * Respects the minimum value constraint. If decrementing would go below min, + * the value is set to the minimum instead. + */ onDecrement() { this.currentValue = this.currentValue - 1 < this.minValue @@ -94,39 +146,86 @@ export default class SpinButton extends createjs.Container { this.updateTargetValue(); } + /** + * Handles change event from accessibility module. + * + * Updates the current value to the new value provided in the event. + * + * @param {Object} evt - Change event object containing the new value + * @param {number} evt.value - The new numeric value + */ onChange(evt) { this.currentValue = evt.value; this.updateTargetValue(); } + /** + * Updates the target text container and accessibility value. + * + * Sets the text of the associated text container to the current value, + * updates the accessible value for screen readers, and calls the callback + * function to notify listeners of the value change. + */ updateTargetValue() { this.targetContainer.text = this.currentValue; this.accessible.value = this.currentValue; this.callback(); } + /** + * Creates and configures the visual focus indicator. + * + * The focus indicator is a blue rectangle outline that appears when + * the spin button receives focus, providing visual feedback for keyboard navigation. + * + * @param {number} width - Width of the focus indicator + * @param {number} height - Height of the focus indicator + */ setupFocusIndicator(width, height) { this._focusIndicator = new createjs.Shape(); - this._focusIndicator.visible = false; + this._focusIndicator.visible = false; // Initially hidden + + // Draw blue rectangle outline slightly larger than the button this._focusIndicator.graphics - .setStrokeStyle(5) - .beginStroke('#5FC1FA') - .drawRect(-2.5, -2.5, width + 5, height + 5); + .setStrokeStyle(5) // 5px stroke width + .beginStroke('#5FC1FA') // Light blue color + .drawRect(-2.5, -2.5, width + 5, height + 5); // Offset to center the stroke + this.addChild(this._focusIndicator); } + /** + * Handles focus event - shows the focus indicator. + * + * Called when the spin button receives keyboard focus. + */ onFocus() { this._focusIndicator.visible = true; } + /** + * Handles blur event - hides the focus indicator. + * + * Called when the spin button loses keyboard focus. + */ onBlur() { this._focusIndicator.visible = false; } + /** + * Gets the width of the spin button. + * + * @returns {number} The width in pixels + */ get width() { return this._width; } + /** + * Gets the height of the spin button. + * + * @returns {number} The height in pixels + */ get height() { return this._height; } From d90b72d12c44cd00ab25f9357e1fae1ce1ff0a15 Mon Sep 17 00:00:00 2001 From: nmahesh Date: Mon, 10 Nov 2025 12:03:32 +0530 Subject: [PATCH 2/2] feat: enhance SpinButton.js comments for better readability - Added comprehensive JSDoc documentation for SpinButton class - Documented constructor parameters and functionality - Added detailed method descriptions for all event handlers - Included parameter and return type documentation - Improved code maintainability without changing logic Related to Jira subtask AC-45 --- test-app/src/widgets/SpinButton.js | 62 ++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/test-app/src/widgets/SpinButton.js b/test-app/src/widgets/SpinButton.js index a659188..4d17a7a 100644 --- a/test-app/src/widgets/SpinButton.js +++ b/test-app/src/widgets/SpinButton.js @@ -1,7 +1,25 @@ import AccessibilityModule from '@curriculumassociates/createjs-accessibility'; import Button from './Button'; +/** + * SpinButton widget that provides an accessible numeric input control with increment/decrement buttons. + * Extends CreateJS Container to create a composite widget that follows accessibility guidelines. + * @extends createjs.Container + */ export default class SpinButton extends createjs.Container { + /** + * Creates a new SpinButton instance with accessibility features. + * Initializes the widget with specified options, registers it with the accessibility module, + * and sets up the visual components including increment/decrement buttons and focus indicator. + * @param {Object} params - Configuration parameters for the spin button + * @param {Object} params.options - Configuration options including min/max values and dimensions + * @param {number} params.options.maxValue - Maximum allowed value for the spin button + * @param {number} params.options.minValue - Minimum allowed value for the spin button + * @param {number} params.options.width - Width of the spin button widget + * @param {number} params.options.height - Height of the spin button widget + * @param {createjs.Text} params.textContainer - Text container that displays the current value + * @param {Function} params.callback - Callback function called when the value changes + */ constructor({ options, textContainer, callback }) { super(); const { maxValue, minValue } = options; @@ -55,6 +73,12 @@ export default class SpinButton extends createjs.Container { this.createButtons(); } + /** + * Creates and configures the increment and decrement buttons for the spin button widget. + * Sets up two Button instances - one for incrementing and one for decrementing the value. + * Both buttons are positioned vertically and share the same width as the parent widget. + * The increment button is positioned at the top half, decrement button at the bottom half. + */ createButtons() { const options = { type: 'button', @@ -78,6 +102,11 @@ export default class SpinButton extends createjs.Container { this.decBtn.y = this.height * 0.5; } + /** + * Handles the increment event when the up/increment button is pressed. + * Increases the current value by 1, ensuring it doesn't exceed the maximum allowed value. + * After updating the value, triggers the target container update and callback. + */ onIncrement() { this.currentValue = this.currentValue + 1 > this.maxValue @@ -86,6 +115,11 @@ export default class SpinButton extends createjs.Container { this.updateTargetValue(); } + /** + * Handles the decrement event when the down/decrement button is pressed. + * Decreases the current value by 1, ensuring it doesn't go below the minimum allowed value. + * After updating the value, triggers the target container update and callback. + */ onDecrement() { this.currentValue = this.currentValue - 1 < this.minValue @@ -94,17 +128,35 @@ export default class SpinButton extends createjs.Container { this.updateTargetValue(); } + /** + * Handles the change event when the spin button value is modified programmatically or through accessibility APIs. + * Updates the current value to the new value provided in the event and triggers the target update. + * @param {Object} evt - Change event object containing the new value + * @param {number} evt.value - The new value to set for the spin button + */ onChange(evt) { this.currentValue = evt.value; this.updateTargetValue(); } + /** + * Updates the target text container with the current value and synchronizes the accessibility value. + * This method ensures that both the visual display and the accessibility layer reflect the current value. + * Also triggers the callback function to notify listeners of the value change. + */ updateTargetValue() { this.targetContainer.text = this.currentValue; this.accessible.value = this.currentValue; this.callback(); } + /** + * Creates and configures the visual focus indicator for the spin button widget. + * The focus indicator is a blue rectangular border that appears when the widget receives focus. + * It's initially hidden and becomes visible during focus/blur events for accessibility. + * @param {number} width - Width of the focus indicator rectangle + * @param {number} height - Height of the focus indicator rectangle + */ setupFocusIndicator(width, height) { this._focusIndicator = new createjs.Shape(); this._focusIndicator.visible = false; @@ -115,10 +167,20 @@ export default class SpinButton extends createjs.Container { this.addChild(this._focusIndicator); } + /** + * Handles the focus event by making the focus indicator visible. + * This provides visual feedback when the spin button widget receives keyboard focus, + * improving accessibility for users who navigate with the keyboard. + */ onFocus() { this._focusIndicator.visible = true; } + /** + * Handles the blur event by hiding the focus indicator. + * This removes the visual focus feedback when the spin button widget loses keyboard focus, + * maintaining a clean appearance when the widget is not actively focused. + */ onBlur() { this._focusIndicator.visible = false; }