@prairielearn/browser-utils 2.1.2 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @prairielearn/browser-utils
 
+## 2.2.0
+
+### Minor Changes
+
+- d7f1045: Add `trapFocus` and `focusFirstFocusbaleChild` functions
+
+## 2.1.3
+
+### Patch Changes
+
+- Updated dependencies [852c2e2]
+  - @prairielearn/html@4.0.5
+
 ## 2.1.2
 
 ### Patch Changes

package/README.md

@@ -90,3 +90,28 @@ document.querySelectorAll('.js-delete-course').forEach((el) => {
   });
 });
 ```
+
+### `trapFocus`
+
+This function can be used to trap focus within an element, such as a popover or modal. It will ensure that the user cannot tab out of the element.
+
+```ts
+import { trapFocus } from '@prairielearn/browser-utils';
+
+const popover = document.querySelector('.popover');
+const trap = trapFocus(popover);
+
+// When the container is being closed or removed, deactivate the trap.
+trap.deactivate();
+```
+
+### `focusFirstFocusableChild`
+
+This function will focus the first focusable child of an element. This is useful when opening a modal or popover.
+
+```ts
+import { focusFirstFocusableChild } from '@prairielearn/browser-utils';
+
+const modal = document.querySelector('.modal');
+focusFirstFocusableChild(modal);
+```

package/dist/focus.d.ts

@@ -0,0 +1,5 @@
+export interface FocusTrap {
+    deactivate(): void;
+}
+export declare function trapFocus(element: Element): FocusTrap;
+export declare function focusFirstFocusableChild(el: HTMLElement): void;

package/dist/focus.js

@@ -0,0 +1,106 @@
+// Borrowed from Bootstrap:
+// https://github.com/twbs/bootstrap/blob/5f75413735d8779aeefe0097af9dc5a416208ae5/js/src/dom/selector-engine.js#L67
+const FOCUSABLE_SELECTOR = [
+    'a',
+    'button',
+    'input',
+    'textarea',
+    'select',
+    'details',
+    '[tabindex]',
+    '[contenteditable="true"]',
+]
+    .map((selector) => `${selector}:not([tabindex^="-"]):not(.btn-close)`)
+    .join(',');
+function isElement(object) {
+    return typeof object?.nodeType !== 'undefined';
+}
+function isVisible(element) {
+    if (!isElement(element) || element.getClientRects().length === 0) {
+        return false;
+    }
+    const elementIsVisible = getComputedStyle(element).getPropertyValue('visibility') === 'visible';
+    // Handle `details` element as its content may falsly appear visible when it is closed
+    const closedDetails = element.closest('details:not([open])');
+    if (!closedDetails) {
+        return elementIsVisible;
+    }
+    if (closedDetails !== element) {
+        const summary = element.closest('summary');
+        if (summary && summary.parentNode !== closedDetails) {
+            return false;
+        }
+        if (summary === null) {
+            return false;
+        }
+    }
+    return elementIsVisible;
+}
+function isDisabled(element) {
+    if (!element || element.nodeType !== Node.ELEMENT_NODE) {
+        return true;
+    }
+    if (typeof element.disabled !== 'undefined') {
+        return element.disabled;
+    }
+    return element.hasAttribute('disabled') && element.getAttribute('disabled') !== 'false';
+}
+function focusableChildren(element) {
+    const focusableChildren = element.querySelectorAll(FOCUSABLE_SELECTOR);
+    return Array.from(focusableChildren).filter((child) => !isDisabled(child) && isVisible(child));
+}
+export function trapFocus(element) {
+    // Store the previous active element so we can restore it later.
+    const previousActiveElement = document.activeElement ?? document.body;
+    function keyDown(e) {
+        console.log('handling keydown', e.key);
+        if (e.key !== 'Tab')
+            return;
+        const focusable = focusableChildren(element);
+        const firstFocusable = focusable[0];
+        const lastFocusable = focusable[focusable.length - 1];
+        if (e.shiftKey) {
+            // Tabbing backwards
+            if (document.activeElement === firstFocusable) {
+                focusable[focusable.length - 1].focus();
+                e.preventDefault();
+            }
+        }
+        else {
+            // Tabbing forwards
+            if (document.activeElement === lastFocusable) {
+                focusable[0].focus();
+                e.preventDefault();
+            }
+        }
+    }
+    document.addEventListener('keydown', keyDown);
+    return {
+        deactivate() {
+            document.removeEventListener('keydown', keyDown);
+            previousActiveElement?.focus();
+        },
+    };
+}
+export function focusFirstFocusableChild(el) {
+    // In case the user (or more frequently, Cypress) is too fast and focuses a
+    // specific element inside the container before this script runs, don't transfer
+    // focus to a different element.
+    if (el.contains(document.activeElement))
+        return;
+    // Escape hatch: if the first element isn't the one that should be focused,
+    // add the `autofocus` attribute to the element that should be.
+    const autofocusElement = el.querySelector('[autofocus]');
+    if (autofocusElement) {
+        autofocusElement.focus();
+        return;
+    }
+    const focusablePopoverChildren = focusableChildren(el);
+    if (focusablePopoverChildren.length > 0) {
+        focusablePopoverChildren[0].focus();
+        return;
+    }
+    // If we still couldn't find a child element, focus the container itself.
+    el.focus();
+}
+//# sourceMappingURL=focus.js.map

package/dist/focus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus.js","sourceRoot":"","sources":["../src/focus.ts"],"names":[],"mappings":"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","sourcesContent":["// Borrowed from Bootstrap:\n// https://github.com/twbs/bootstrap/blob/5f75413735d8779aeefe0097af9dc5a416208ae5/js/src/dom/selector-engine.js#L67\nconst FOCUSABLE_SELECTOR = [\n  'a',\n  'button',\n  'input',\n  'textarea',\n  'select',\n  'details',\n  '[tabindex]',\n  '[contenteditable=\"true\"]',\n]\n  .map((selector) => `${selector}:not([tabindex^=\"-\"]):not(.btn-close)`)\n  .join(',');\n\nfunction isElement(object: Element) {\n  return typeof object?.nodeType !== 'undefined';\n}\n\nfunction isVisible(element: Element) {\n  if (!isElement(element) || element.getClientRects().length === 0) {\n    return false;\n  }\n\n  const elementIsVisible = getComputedStyle(element).getPropertyValue('visibility') === 'visible';\n  // Handle `details` element as its content may falsly appear visible when it is closed\n  const closedDetails = element.closest('details:not([open])');\n\n  if (!closedDetails) {\n    return elementIsVisible;\n  }\n\n  if (closedDetails !== element) {\n    const summary = element.closest('summary');\n    if (summary && summary.parentNode !== closedDetails) {\n      return false;\n    }\n\n    if (summary === null) {\n      return false;\n    }\n  }\n\n  return elementIsVisible;\n}\n\nfunction isDisabled(element: Element) {\n  if (!element || element.nodeType !== Node.ELEMENT_NODE) {\n    return true;\n  }\n\n  if (typeof (element as any).disabled !== 'undefined') {\n    return (element as any).disabled;\n  }\n\n  return element.hasAttribute('disabled') && element.getAttribute('disabled') !== 'false';\n}\n\nfunction focusableChildren(element: Element): HTMLElement[] {\n  const focusableChildren = element.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR);\n  return Array.from(focusableChildren).filter((child) => !isDisabled(child) && isVisible(child));\n}\n\nexport interface FocusTrap {\n  deactivate(): void;\n}\n\nexport function trapFocus(element: Element): FocusTrap {\n  // Store the previous active element so we can restore it later.\n  const previousActiveElement = document.activeElement ?? document.body;\n\n  function keyDown(e: KeyboardEvent) {\n    console.log('handling keydown', e.key);\n    if (e.key !== 'Tab') return;\n\n    const focusable = focusableChildren(element);\n    const firstFocusable = focusable[0];\n    const lastFocusable = focusable[focusable.length - 1];\n\n    if (e.shiftKey) {\n      // Tabbing backwards\n      if (document.activeElement === firstFocusable) {\n        (focusable[focusable.length - 1] as HTMLElement).focus();\n        e.preventDefault();\n      }\n    } else {\n      // Tabbing forwards\n      if (document.activeElement === lastFocusable) {\n        (focusable[0] as HTMLElement).focus();\n        e.preventDefault();\n      }\n    }\n  }\n\n  document.addEventListener('keydown', keyDown);\n\n  return {\n    deactivate() {\n      document.removeEventListener('keydown', keyDown);\n      (previousActiveElement as HTMLElement)?.focus();\n    },\n  };\n}\n\nexport function focusFirstFocusableChild(el: HTMLElement) {\n  // In case the user (or more frequently, Cypress) is too fast and focuses a\n  // specific element inside the container before this script runs, don't transfer\n  // focus to a different element.\n  if (el.contains(document.activeElement)) return;\n\n  // Escape hatch: if the first element isn't the one that should be focused,\n  // add the `autofocus` attribute to the element that should be.\n  const autofocusElement = el.querySelector<HTMLElement>('[autofocus]');\n  if (autofocusElement) {\n    autofocusElement.focus();\n    return;\n  }\n\n  const focusablePopoverChildren = focusableChildren(el);\n  if (focusablePopoverChildren.length > 0) {\n    focusablePopoverChildren[0].focus();\n    return;\n  }\n\n  // If we still couldn't find a child element, focus the container itself.\n  el.focus();\n}\n"]}

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export { onDocumentReady } from './on-document-ready.js';
 export { parseHTML, parseHTMLElement } from './parse-html.js';
 export { EncodedData, decodeData } from './encode-data.js';
 export { templateFromAttributes } from './template-from-attributes.js';
+export { trapFocus, focusFirstFocusableChild } from './focus.js';

package/dist/index.js

@@ -2,4 +2,5 @@ export { onDocumentReady } from './on-document-ready.js';
 export { parseHTML, parseHTMLElement } from './parse-html.js';
 export { EncodedData, decodeData } from './encode-data.js';
 export { templateFromAttributes } from './template-from-attributes.js';
+export { trapFocus, focusFirstFocusableChild } from './focus.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC","sourcesContent":["export { onDocumentReady } from './on-document-ready.js';\nexport { parseHTML, parseHTMLElement } from './parse-html.js';\nexport { EncodedData, decodeData } from './encode-data.js';\nexport { templateFromAttributes } from './template-from-attributes.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,SAAS,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC","sourcesContent":["export { onDocumentReady } from './on-document-ready.js';\nexport { parseHTML, parseHTMLElement } from './parse-html.js';\nexport { EncodedData, decodeData } from './encode-data.js';\nexport { templateFromAttributes } from './template-from-attributes.js';\nexport { trapFocus, focusFirstFocusableChild } from './focus.js';\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prairielearn/browser-utils",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "type": "module",
   "main": "dist/index.js",
   "sideEffects": false,
@@ -14,7 +14,7 @@
     "dev": "tsc --watch --preserveWatchOutput"
   },
   "dependencies": {
-    "@prairielearn/html": "^4.0.4",
+    "@prairielearn/html": "^4.0.5",
     "js-base64": "^3.7.7"
   },
   "devDependencies": {

package/src/focus.ts

@@ -0,0 +1,127 @@
+// Borrowed from Bootstrap:
+// https://github.com/twbs/bootstrap/blob/5f75413735d8779aeefe0097af9dc5a416208ae5/js/src/dom/selector-engine.js#L67
+const FOCUSABLE_SELECTOR = [
+  'a',
+  'button',
+  'input',
+  'textarea',
+  'select',
+  'details',
+  '[tabindex]',
+  '[contenteditable="true"]',
+]
+  .map((selector) => `${selector}:not([tabindex^="-"]):not(.btn-close)`)
+  .join(',');
+
+function isElement(object: Element) {
+  return typeof object?.nodeType !== 'undefined';
+}
+
+function isVisible(element: Element) {
+  if (!isElement(element) || element.getClientRects().length === 0) {
+    return false;
+  }
+
+  const elementIsVisible = getComputedStyle(element).getPropertyValue('visibility') === 'visible';
+  // Handle `details` element as its content may falsly appear visible when it is closed
+  const closedDetails = element.closest('details:not([open])');
+
+  if (!closedDetails) {
+    return elementIsVisible;
+  }
+
+  if (closedDetails !== element) {
+    const summary = element.closest('summary');
+    if (summary && summary.parentNode !== closedDetails) {
+      return false;
+    }
+
+    if (summary === null) {
+      return false;
+    }
+  }
+
+  return elementIsVisible;
+}
+
+function isDisabled(element: Element) {
+  if (!element || element.nodeType !== Node.ELEMENT_NODE) {
+    return true;
+  }
+
+  if (typeof (element as any).disabled !== 'undefined') {
+    return (element as any).disabled;
+  }
+
+  return element.hasAttribute('disabled') && element.getAttribute('disabled') !== 'false';
+}
+
+function focusableChildren(element: Element): HTMLElement[] {
+  const focusableChildren = element.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR);
+  return Array.from(focusableChildren).filter((child) => !isDisabled(child) && isVisible(child));
+}
+
+export interface FocusTrap {
+  deactivate(): void;
+}
+
+export function trapFocus(element: Element): FocusTrap {
+  // Store the previous active element so we can restore it later.
+  const previousActiveElement = document.activeElement ?? document.body;
+
+  function keyDown(e: KeyboardEvent) {
+    console.log('handling keydown', e.key);
+    if (e.key !== 'Tab') return;
+
+    const focusable = focusableChildren(element);
+    const firstFocusable = focusable[0];
+    const lastFocusable = focusable[focusable.length - 1];
+
+    if (e.shiftKey) {
+      // Tabbing backwards
+      if (document.activeElement === firstFocusable) {
+        (focusable[focusable.length - 1] as HTMLElement).focus();
+        e.preventDefault();
+      }
+    } else {
+      // Tabbing forwards
+      if (document.activeElement === lastFocusable) {
+        (focusable[0] as HTMLElement).focus();
+        e.preventDefault();
+      }
+    }
+  }
+
+  document.addEventListener('keydown', keyDown);
+
+  return {
+    deactivate() {
+      document.removeEventListener('keydown', keyDown);
+      (previousActiveElement as HTMLElement)?.focus();
+    },
+  };
+}
+
+export function focusFirstFocusableChild(el: HTMLElement) {
+  // In case the user (or more frequently, Cypress) is too fast and focuses a
+  // specific element inside the container before this script runs, don't transfer
+  // focus to a different element.
+  if (el.contains(document.activeElement)) return;
+
+  // Escape hatch: if the first element isn't the one that should be focused,
+  // add the `autofocus` attribute to the element that should be.
+  const autofocusElement = el.querySelector<HTMLElement>('[autofocus]');
+  if (autofocusElement) {
+    autofocusElement.focus();
+    return;
+  }
+
+  const focusablePopoverChildren = focusableChildren(el);
+  if (focusablePopoverChildren.length > 0) {
+    focusablePopoverChildren[0].focus();
+    return;
+  }
+
+  // If we still couldn't find a child element, focus the container itself.
+  el.focus();
+}

package/src/index.ts

@@ -2,3 +2,4 @@ export { onDocumentReady } from './on-document-ready.js';
 export { parseHTML, parseHTMLElement } from './parse-html.js';
 export { EncodedData, decodeData } from './encode-data.js';
 export { templateFromAttributes } from './template-from-attributes.js';
+export { trapFocus, focusFirstFocusableChild } from './focus.js';