From cdfa69088d275c7bd08ab0eef5f9e349a073fae8 Mon Sep 17 00:00:00 2001
From: Eli Luberoff <eli@desmos.com>
Date: Sun, 2 Feb 2025 21:10:36 -0500
Subject: [PATCH] improve API for tabbability

* update value through the config method
* change from "tabbable" to "tabindex", to match all of html's capabilities
---
 docs/Api_Methods.md         |  4 ----
 docs/Config.md              |  7 ++++---
 src/mathquill.d.ts          |  3 +--
 src/publicapi.ts            |  9 ++++-----
 src/services/textarea.ts    | 33 ++++++++++++++-------------------
 test/basic.html             |  3 ++-
 test/demo.html              |  8 ++++----
 test/unit/aria.test.js      |  6 +++---
 test/unit/focusBlur.test.js | 20 ++++++++++----------
 9 files changed, 42 insertions(+), 51 deletions(-)

diff --git a/docs/Api_Methods.md b/docs/Api_Methods.md
index 8b2a99e9e..084afc4d3 100644
--- a/docs/Api_Methods.md
+++ b/docs/Api_Methods.md
@@ -252,10 +252,6 @@ mathField.typedText('x=-b\\pm \\sqrt b^2 -4ac');
 
 Specify an [ARIA label][`aria-label`] for this field, for screen readers. The actual [`aria-label`] includes this label followed by the math content of the field as speech. Default: `'Math Input'`
 
-## .setTabbable(tabbable)
-
-Specify whether this field should be in the tab order. 
-
 ## .getAriaLabel()
 
 Returns the [ARIA label][`aria-label`] for this field, for screen readers. If no ARIA label has been specified, `'Math Input'` is returned.
diff --git a/docs/Config.md b/docs/Config.md
index ecbb5b4e5..cac50a9d6 100644
--- a/docs/Config.md
+++ b/docs/Config.md
@@ -124,11 +124,12 @@ You can also specify a speech-friendly representation of the operator name by su
 `substituteTextarea` is a function that creates a focusable DOM element that is called when setting up a math field. Overwriting this may be useful for hacks like suppressing built-in virtual keyboards. It defaults to `<textarea autocorrect=off .../>`.
 For example, [Desmos](https://www.desmos.com/calculator) substitutes `<textarea inputmode=none />` to suppress the native virtual keyboard in favor of a custom math keypad that calls the MathQuill API. On old iOS versions that don't support `inputmode=none`, it uses `<span tabindex=0></span>` to suppress the native virtual keyboard, at the cost of bluetooth keyboards not working.
 
-## tabbable
+## tabindex
 
-For static and editable math fields, when `tabbable` is false, the math field is not part of the page's tab order. Despite that, the math field can still be focused when selected by a mouse.
+Sets a tabindex on the field, following the standard spec. When tabindex is -1,
+the math field is not part of the page's tab order. Despite that, the math field can still be focused when selected by a mouse.
 
-Static math fields default to `tabbable: false`, Editable math fields default to `tabbable:true`.
+Static math fields default to `tabindex: -1`, Editable math fields default to `tabindex: 1`.
 
 ## disableAutoSubstitutionInSubscripts
 
diff --git a/src/mathquill.d.ts b/src/mathquill.d.ts
index 4972bf6b2..ebb6119a6 100644
--- a/src/mathquill.d.ts
+++ b/src/mathquill.d.ts
@@ -40,7 +40,6 @@ declare namespace MathQuill {
       latex(latex: string): this;
       latex(): string;
       setAriaLabel(str: string): this;
-      setTabbable(tabbable: boolean): this;
       blur(): this;
       focus(): this;
       select(): this;
@@ -109,7 +108,7 @@ declare namespace MathQuill {
       typingSlashWritesDivisionSymbol?: boolean;
       typingPercentWritesPercentOf?: boolean;
       resetCursorOnBlur?: boolean | undefined;
-      tabbable?: boolean;
+      tabindex?: number;
       leftRightIntoCmdGoes?: 'up' | 'down';
       enableDigitGrouping?: boolean;
       tripleDotsAreEllipsis?: boolean;
diff --git a/src/publicapi.ts b/src/publicapi.ts
index 97db263bb..382e01faf 100644
--- a/src/publicapi.ts
+++ b/src/publicapi.ts
@@ -107,7 +107,7 @@ class Options {
   leftRightIntoCmdGoes?: 'up' | 'down';
   enableDigitGrouping?: boolean;
   tripleDotsAreEllipsis?: boolean;
-  tabbable?: boolean;
+  tabindex?: number;
   mouseEvents?: boolean;
   maxDepth?: number;
   disableCopyPaste?: boolean;
@@ -310,12 +310,11 @@ function getInterface(v: number): MathQuill.v3.API | MathQuill.v1.API {
     getAriaLabel() {
       return this.__controller.getAriaLabel();
     }
-    setTabbable(tabbable: boolean) {
-      this.__controller.setTabbable(tabbable);
-      return this;
-    }
     config(opts: ConfigOptions) {
       config(this.__options, opts);
+      if (opts.tabindex !== undefined) {
+        this.__controller.setTabindex(opts.tabindex);
+      }
       return this;
     }
     el() {
diff --git a/src/services/textarea.ts b/src/services/textarea.ts
index 8d870f6e1..b1a62330e 100644
--- a/src/services/textarea.ts
+++ b/src/services/textarea.ts
@@ -29,7 +29,7 @@ Options.prototype.substituteKeyboardEvents = defaultSubstituteKeyboardEvents;
 class Controller extends Controller_scrollHoriz {
   selectFn: (text: string) => void = noop;
 
-  wasTabbable: boolean | undefined;
+  previousTabindex: number | undefined;
 
   createTextarea() {
     this.textareaSpan = h('span', { class: 'mq-textarea' });
@@ -60,34 +60,29 @@ class Controller extends Controller_scrollHoriz {
       ctrlr.selectionChanged();
     };
 
-    const tabbable =
-      this.options.tabbable !== undefined
-        ? this.options.tabbable
-        : this.KIND_OF_MQ !== 'StaticMath';
+    const tabindex =
+      this.options.tabindex !== undefined
+        ? this.options.tabindex
+        : this.KIND_OF_MQ === 'StaticMath'
+          ? -1
+          : 0;
 
-    if (!this.options.tabbable && this.KIND_OF_MQ === 'StaticMath') {
-      // aria-hide noninteractive textarea element for static math
-      textarea.setAttribute('aria-hidden', 'true');
-    }
-    if (tabbable && this.mathspeakSpan) {
-      this.mathspeakSpan.setAttribute('aria-hidden', 'true');
-    }
-    this.setTabbable(tabbable);
+    this.setTabindex(tabindex);
   }
 
-  setTabbable(tabbable: boolean) {
-    if (tabbable === this.wasTabbable) return;
-    this.wasTabbable = tabbable;
+  setTabindex(tabindex: number) {
+    if (tabindex === this.previousTabindex || !this.textarea) return;
+    this.previousTabindex = tabindex;
 
-    this.textarea?.setAttribute('tabindex', tabbable ? '0' : '-1');
+    this.textarea?.setAttribute('tabindex', '' + tabindex);
 
-    if (!tabbable && this.KIND_OF_MQ === 'StaticMath') {
+    if (tabindex < 0 && this.KIND_OF_MQ === 'StaticMath') {
       this.textarea?.setAttribute('aria-hidden', 'true');
     } else {
       this.textarea?.removeAttribute('aria-hidden');
     }
 
-    if (tabbable) {
+    if (tabindex >= 0) {
       this.mathspeakSpan?.setAttribute('aria-hidden', 'true');
     } else {
       this.mathspeakSpan?.removeAttribute('aria-hidden');
diff --git a/test/basic.html b/test/basic.html
index 846743bba..1af889199 100644
--- a/test/basic.html
+++ b/test/basic.html
@@ -46,7 +46,7 @@ <h1>
         });
       });
       var mq = MQ.MathField($('#basic')[0], {
-        tabbable: false,
+        tabindex: -1,
         autoSubscriptNumerals: true,
         autoCommands:
           'alpha beta sqrt theta phi pi tau nthroot cbrt prod int ans percent mid square',
@@ -58,6 +58,7 @@ <h1>
         }
       });
       latex.val(mq.latex());
+      mq.config({ tabindex: 0 });
     </script>
   </body>
 </html>
diff --git a/test/demo.html b/test/demo.html
index ab8b15ed5..95d9378a2 100644
--- a/test/demo.html
+++ b/test/demo.html
@@ -110,9 +110,9 @@ <h1>
       </p>
 
       <p>
-        On the other hand, you can make static math tabbable to appear in the
-        tab order despite being non-editable. The entire range is selected when
-        tabbed into:
+        On the other hand, you can make static math appear in the tab order
+        despite being non-editable by providing a tabindex. The entire range is
+        selected when tabbed into:
         <span class="static-math-tabbable">1.234\times 10^{8}</span>.
       </p>
 
@@ -169,7 +169,7 @@ <h1>
           MQ.StaticMath(this, { mouseEvents: false });
         });
         $('.static-math-tabbable').each(function () {
-          MQ.StaticMath(this, { tabbable: true });
+          MQ.StaticMath(this, { tabindex: 0 });
         });
         $('.mathquill-math-field').each(function () {
           MQ.MathField(this);
diff --git a/test/unit/aria.test.js b/test/unit/aria.test.js
index a9ab45dc8..012eb2ae2 100644
--- a/test/unit/aria.test.js
+++ b/test/unit/aria.test.js
@@ -38,7 +38,7 @@ suite('aria', function () {
       'aria-hidden is set on mq-root-block'
     );
 
-    staticMath.setTabbable(true);
+    staticMath.config({ tabindex: 0 });
     var ariaHiddenChildren = $(container).find('[aria-hidden]="true"');
     assert.equal(ariaHiddenChildren.length, 2, '2 aria-hidden elements');
     assert.equal(
@@ -47,7 +47,7 @@ suite('aria', function () {
       'aria-hidden is set on mathspeak span when tabbable'
     );
 
-    staticMath.setTabbable(false);
+    staticMath.config({ tabindex: -1 });
     var ariaHiddenChildren = $(container).find('[aria-hidden]="true"');
     assert.equal(
       ariaHiddenChildren[0].nodeName,
@@ -57,7 +57,7 @@ suite('aria', function () {
   });
 
   test('Tabbable static math aria-hidden', function () {
-    var staticMath = MQ.StaticMath(container, { tabbable: true });
+    var staticMath = MQ.StaticMath(container, { tabindex: 0 });
     staticMath.latex('1+\\frac{1}{x}');
     var ariaHiddenChildren = $(container).find('[aria-hidden]="true"');
     // There will be two hidden children: the raw text of the field, and its mathspeak representation.
diff --git a/test/unit/focusBlur.test.js b/test/unit/focusBlur.test.js
index 0575810e8..4b2642187 100644
--- a/test/unit/focusBlur.test.js
+++ b/test/unit/focusBlur.test.js
@@ -106,7 +106,7 @@ suite('focusBlur', function () {
   test('full range selected on focusing tabbable static math', function () {
     var mq = MQ.StaticMath(
       $('<span>1234\\times 10^{23}</span>').appendTo('#mock')[0],
-      { tabbable: true }
+      { tabindex: 0 }
     );
 
     mq.focus();
@@ -119,18 +119,18 @@ suite('focusBlur', function () {
     );
 
     assert.equal($(document.activeElement).attr('tabindex'), '0');
-    mq.setTabbable(false);
+    mq.config({ tabindex: -1 });
     assert.equal(
       $(document.activeElement).attr('tabindex'),
       '-1',
-      'tab index updated when setTabbable:false called'
+      'tab index updated when tabindex is set to -1'
     );
 
-    mq.setTabbable(true);
+    mq.config({ tabindex: 0 });
     assert.equal(
       $(document.activeElement).attr('tabindex'),
       '0',
-      'tab index restored when setTabbable:true called'
+      'tab index restored when tabindex is set to 0'
     );
 
     mq.blur();
@@ -139,7 +139,7 @@ suite('focusBlur', function () {
 
   test('tabindex for editable math', function () {
     var mq = MQ.MathField($('<span></span>').appendTo('#mock')[0], {
-      tabbable: false
+      tabindex: -1
     });
 
     mq.focus();
@@ -149,18 +149,18 @@ suite('focusBlur', function () {
     assert.equal(mq.latex(), '1+1', 'latex populated');
 
     assert.equal($(document.activeElement).attr('tabindex'), '-1');
-    mq.setTabbable(true);
+    mq.config({ tabindex: 0 });
     assert.equal(
       $(document.activeElement).attr('tabindex'),
       '0',
-      'tab index updated when setTabbable:true called'
+      'tab index updated tabindex is set to 0'
     );
 
-    mq.setTabbable(false);
+    mq.config({ tabindex: -1 });
     assert.equal(
       $(document.activeElement).attr('tabindex'),
       '-1',
-      'tab index restored when setTabbable:false called'
+      'tab index restored when tabindex is set to -1'
     );
 
     mq.blur();