@prairielearn/browser-utils 2.3.0 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @prairielearn/browser-utils
 
+## 2.5.0
+
+### Minor Changes
+
+- 19f0bf7: Improved support for focus on radio groups
+
+## 2.4.0
+
+### Minor Changes
+
+- 5b46852: Add `downloadTextFile`, `downloadAsJSON` and `downloadAsCSV` utilities
+
 ## 2.3.0
 
 ### Minor Changes

package/dist/downloads.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Triggers a browser download of a text-based file.
+ *
+ * @param content The content of the file.
+ * @param filename The desired filename.
+ * @param mimeType The MIME type of the file.
+ */
+export declare function downloadTextFile(content: string, filename: string, mimeType: string): void;
+/**
+ * Triggers a browser download of a JSON file.
+ *
+ * @param data The data to be included in the JSON file.
+ * @param filename The desired filename.
+ */
+export declare function downloadAsJSON(data: any, filename: string): void;
+/**
+ * Triggers a browser download of a CSV file.
+ *
+ * @param header The header row of the CSV.
+ * @param data The data rows of the CSV.
+ * @param filename The desired filename.
+ */
+export declare function downloadAsCSV(header: string[], data: unknown[][], filename: string): void;

package/dist/downloads.js

@@ -0,0 +1,43 @@
+import { stringify } from 'csv-stringify/browser/esm/sync';
+/**
+ * Triggers a browser download of a text-based file.
+ *
+ * @param content The content of the file.
+ * @param filename The desired filename.
+ * @param mimeType The MIME type of the file.
+ */
+export function downloadTextFile(content, filename, mimeType) {
+    if (typeof window === 'undefined')
+        return;
+    const blob = new Blob([content], { type: mimeType });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    document.body.append(a);
+    a.click();
+    a.remove();
+    URL.revokeObjectURL(url);
+}
+/**
+ * Triggers a browser download of a JSON file.
+ *
+ * @param data The data to be included in the JSON file.
+ * @param filename The desired filename.
+ */
+export function downloadAsJSON(data, filename) {
+    const jsonContent = JSON.stringify(data, null, 2);
+    downloadTextFile(jsonContent, filename, 'application/json');
+}
+/**
+ * Triggers a browser download of a CSV file.
+ *
+ * @param header The header row of the CSV.
+ * @param data The data rows of the CSV.
+ * @param filename The desired filename.
+ */
+export function downloadAsCSV(header, data, filename) {
+    const csvContent = stringify(data, { header: true, columns: header });
+    downloadTextFile(csvContent, filename, 'text/csv');
+}
+//# sourceMappingURL=downloads.js.map

package/dist/downloads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"downloads.js","sourceRoot":"","sources":["../src/downloads.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,QAAgB,EAAE,QAAgB;IAClF,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,OAAO;IAC1C,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IACrD,MAAM,GAAG,GAAG,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,CAAC,GAAG,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC;IACb,CAAC,CAAC,QAAQ,GAAG,QAAQ,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACxB,CAAC,CAAC,KAAK,EAAE,CAAC;IACV,CAAC,CAAC,MAAM,EAAE,CAAC;IACX,GAAG,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAS,EAAE,QAAgB;IACxD,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAClD,gBAAgB,CAAC,WAAW,EAAE,QAAQ,EAAE,kBAAkB,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,MAAgB,EAAE,IAAiB,EAAE,QAAgB;IACjF,MAAM,UAAU,GAAG,SAAS,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IACtE,gBAAgB,CAAC,UAAU,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;AACrD,CAAC","sourcesContent":["import { stringify } from 'csv-stringify/browser/esm/sync';\n\n/**\n * Triggers a browser download of a text-based file.\n *\n * @param content The content of the file.\n * @param filename The desired filename.\n * @param mimeType The MIME type of the file.\n */\nexport function downloadTextFile(content: string, filename: string, mimeType: string): void {\n  if (typeof window === 'undefined') return;\n  const blob = new Blob([content], { type: mimeType });\n  const url = URL.createObjectURL(blob);\n  const a = document.createElement('a');\n  a.href = url;\n  a.download = filename;\n  document.body.append(a);\n  a.click();\n  a.remove();\n  URL.revokeObjectURL(url);\n}\n\n/**\n * Triggers a browser download of a JSON file.\n *\n * @param data The data to be included in the JSON file.\n * @param filename The desired filename.\n */\nexport function downloadAsJSON(data: any, filename: string): void {\n  const jsonContent = JSON.stringify(data, null, 2);\n  downloadTextFile(jsonContent, filename, 'application/json');\n}\n\n/**\n * Triggers a browser download of a CSV file.\n *\n * @param header The header row of the CSV.\n * @param data The data rows of the CSV.\n * @param filename The desired filename.\n */\nexport function downloadAsCSV(header: string[], data: unknown[][], filename: string): void {\n  const csvContent = stringify(data, { header: true, columns: header });\n  downloadTextFile(csvContent, filename, 'text/csv');\n}\n"]}

package/dist/focus.js

@@ -60,15 +60,15 @@ export function trapFocus(element) {
         const lastFocusable = focusable[focusable.length - 1];
         if (e.shiftKey) {
             // Tabbing backwards
-            if (document.activeElement === firstFocusable) {
-                focusable[focusable.length - 1].focus();
+            if (isSameFocusContext(document.activeElement, firstFocusable)) {
+                focusElementOrCheckedOption(focusable[focusable.length - 1]);
                 e.preventDefault();
             }
         }
         else {
             // Tabbing forwards
-            if (document.activeElement === lastFocusable) {
-                focusable[0].focus();
+            if (isSameFocusContext(document.activeElement, lastFocusable)) {
+                focusElementOrCheckedOption(focusable[0]);
                 e.preventDefault();
             }
         }
@@ -80,7 +80,7 @@ export function trapFocus(element) {
             // Restore focus to the previously active element, but only if focus is
             // currently inside the trap container.
             if (element.contains(document.activeElement)) {
-                previousActiveElement?.focus({ preventScroll: true });
+                focusElementOrCheckedOption(previousActiveElement, { preventScroll: true });
             }
         },
     };
@@ -100,10 +100,56 @@ export function focusFirstFocusableChild(el) {
     }
     const focusablePopoverChildren = focusableChildren(el);
     if (focusablePopoverChildren.length > 0) {
-        focusablePopoverChildren[0].focus();
+        focusElementOrCheckedOption(focusablePopoverChildren[0]);
         return;
     }
     // If we still couldn't find a child element, focus the container itself.
     el.focus();
 }
+/**
+ * Focus on the element, or if it's a radio button, focus on the checked radio button in the same group.
+ */
+function focusElementOrCheckedOption(element, focusOptions) {
+    // If the element receiving focus is a radio button, and there is another
+    // radio button in the same group that is currently checked, focus on that one
+    // instead.
+    // https://www.w3.org/WAI/ARIA/apg/patterns/radio/
+    if (element.tagName === 'INPUT') {
+        const inputElement = element;
+        if (inputElement.type === 'radio' && inputElement.name) {
+            const checkedRadio = (inputElement.form ?? document).querySelector(`input[type="radio"][name="${CSS.escape(inputElement.name)}"]:checked`);
+            if (checkedRadio) {
+                checkedRadio.focus(focusOptions);
+                return;
+            }
+        }
+    }
+    // Otherwise, just focus on the element itself.
+    element.focus(focusOptions);
+}
+/**
+ * Check if two elements are in the same focus context. This is true if they are the
+ * same element, or if they are radio buttons in the same group.
+ */
+function isSameFocusContext(element1, element2) {
+    if (!element1 || !element2)
+        return false;
+    if (element1 === element2)
+        return true;
+    if (element1.tagName === 'INPUT' && element2.tagName === 'INPUT') {
+        const input1 = element1;
+        const input2 = element2;
+        // https://html.spec.whatwg.org/multipage/input.html#radio-button-state-(type=radio)
+        if (input1.type === 'radio' &&
+            input2.type === 'radio' &&
+            // radios without a name are not in the same group, even if they share the same form
+            input1.name &&
+            input1.name === input2.name &&
+            // either both have no form, or both have the same form
+            input1.form === input2.form) {
+            return true;
+        }
+    }
+    return false;
+}
 //# sourceMappingURL=focus.js.map

package/dist/focus.js.map

@@ -1 +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 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 ((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    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      // Restore focus to the previously active element, but only if focus is\n      // currently inside the trap container.\n      if (element.contains(document.activeElement)) {\n        (previousActiveElement as HTMLElement)?.focus({ preventScroll: true });\n      }\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"]}
+{"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 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 ((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    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 (isSameFocusContext(document.activeElement, firstFocusable)) {\n        focusElementOrCheckedOption(focusable[focusable.length - 1]);\n        e.preventDefault();\n      }\n    } else {\n      // Tabbing forwards\n      if (isSameFocusContext(document.activeElement, lastFocusable)) {\n        focusElementOrCheckedOption(focusable[0]);\n        e.preventDefault();\n      }\n    }\n  }\n\n  document.addEventListener('keydown', keyDown);\n\n  return {\n    deactivate() {\n      document.removeEventListener('keydown', keyDown);\n      // Restore focus to the previously active element, but only if focus is\n      // currently inside the trap container.\n      if (element.contains(document.activeElement)) {\n        focusElementOrCheckedOption(previousActiveElement as HTMLElement, { preventScroll: true });\n      }\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    focusElementOrCheckedOption(focusablePopoverChildren[0]);\n    return;\n  }\n\n  // If we still couldn't find a child element, focus the container itself.\n  el.focus();\n}\n\n/**\n * Focus on the element, or if it's a radio button, focus on the checked radio button in the same group.\n */\nfunction focusElementOrCheckedOption(element: HTMLElement, focusOptions?: FocusOptions) {\n  // If the element receiving focus is a radio button, and there is another\n  // radio button in the same group that is currently checked, focus on that one\n  // instead.\n  // https://www.w3.org/WAI/ARIA/apg/patterns/radio/\n  if (element.tagName === 'INPUT') {\n    const inputElement = element as HTMLInputElement;\n    if (inputElement.type === 'radio' && inputElement.name) {\n      const checkedRadio = (inputElement.form ?? document).querySelector<HTMLInputElement>(\n        `input[type=\"radio\"][name=\"${CSS.escape(inputElement.name)}\"]:checked`,\n      );\n      if (checkedRadio) {\n        checkedRadio.focus(focusOptions);\n        return;\n      }\n    }\n  }\n\n  // Otherwise, just focus on the element itself.\n  element.focus(focusOptions);\n}\n\n/**\n * Check if two elements are in the same focus context. This is true if they are the\n * same element, or if they are radio buttons in the same group.\n */\nfunction isSameFocusContext(element1: Element | null, element2: Element | null) {\n  if (!element1 || !element2) return false;\n  if (element1 === element2) return true;\n  if (element1.tagName === 'INPUT' && element2.tagName === 'INPUT') {\n    const input1 = element1 as HTMLInputElement;\n    const input2 = element2 as HTMLInputElement;\n    // https://html.spec.whatwg.org/multipage/input.html#radio-button-state-(type=radio)\n    if (\n      input1.type === 'radio' &&\n      input2.type === 'radio' &&\n      // radios without a name are not in the same group, even if they share the same form\n      input1.name &&\n      input1.name === input2.name &&\n      // either both have no form, or both have the same form\n      input1.form === input2.form\n    ) {\n      return true;\n    }\n  }\n  return false;\n}\n"]}

package/dist/index.d.ts

@@ -3,3 +3,4 @@ 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';
+export { downloadAsCSV, downloadAsJSON } from './downloads.js';

package/dist/index.js

@@ -3,4 +3,5 @@ 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';
+export { downloadAsCSV, downloadAsJSON } from './downloads.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;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"]}
+{"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;AACjE,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,gBAAgB,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';\nexport { downloadAsCSV, downloadAsJSON } from './downloads.js';\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prairielearn/browser-utils",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -14,6 +14,7 @@
   },
   "dependencies": {
     "@prairielearn/html": "^4.0.20",
+    "csv-stringify": "^6.6.0",
     "js-base64": "^3.7.8"
   },
   "devDependencies": {

package/src/downloads.ts

@@ -0,0 +1,44 @@
+import { stringify } from 'csv-stringify/browser/esm/sync';
+
+/**
+ * Triggers a browser download of a text-based file.
+ *
+ * @param content The content of the file.
+ * @param filename The desired filename.
+ * @param mimeType The MIME type of the file.
+ */
+export function downloadTextFile(content: string, filename: string, mimeType: string): void {
+  if (typeof window === 'undefined') return;
+  const blob = new Blob([content], { type: mimeType });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  document.body.append(a);
+  a.click();
+  a.remove();
+  URL.revokeObjectURL(url);
+}
+
+/**
+ * Triggers a browser download of a JSON file.
+ *
+ * @param data The data to be included in the JSON file.
+ * @param filename The desired filename.
+ */
+export function downloadAsJSON(data: any, filename: string): void {
+  const jsonContent = JSON.stringify(data, null, 2);
+  downloadTextFile(jsonContent, filename, 'application/json');
+}
+
+/**
+ * Triggers a browser download of a CSV file.
+ *
+ * @param header The header row of the CSV.
+ * @param data The data rows of the CSV.
+ * @param filename The desired filename.
+ */
+export function downloadAsCSV(header: string[], data: unknown[][], filename: string): void {
+  const csvContent = stringify(data, { header: true, columns: header });
+  downloadTextFile(csvContent, filename, 'text/csv');
+}

package/src/focus.ts

@@ -78,14 +78,14 @@ export function trapFocus(element: Element): FocusTrap {
 
     if (e.shiftKey) {
       // Tabbing backwards
-      if (document.activeElement === firstFocusable) {
-        (focusable[focusable.length - 1] as HTMLElement).focus();
+      if (isSameFocusContext(document.activeElement, firstFocusable)) {
+        focusElementOrCheckedOption(focusable[focusable.length - 1]);
         e.preventDefault();
       }
     } else {
       // Tabbing forwards
-      if (document.activeElement === lastFocusable) {
-        (focusable[0] as HTMLElement).focus();
+      if (isSameFocusContext(document.activeElement, lastFocusable)) {
+        focusElementOrCheckedOption(focusable[0]);
         e.preventDefault();
       }
     }
@@ -99,7 +99,7 @@ export function trapFocus(element: Element): FocusTrap {
       // Restore focus to the previously active element, but only if focus is
       // currently inside the trap container.
       if (element.contains(document.activeElement)) {
-        (previousActiveElement as HTMLElement)?.focus({ preventScroll: true });
+        focusElementOrCheckedOption(previousActiveElement as HTMLElement, { preventScroll: true });
       }
     },
   };
@@ -121,10 +121,61 @@ export function focusFirstFocusableChild(el: HTMLElement) {
 
   const focusablePopoverChildren = focusableChildren(el);
   if (focusablePopoverChildren.length > 0) {
-    focusablePopoverChildren[0].focus();
+    focusElementOrCheckedOption(focusablePopoverChildren[0]);
     return;
   }
 
   // If we still couldn't find a child element, focus the container itself.
   el.focus();
 }
+
+/**
+ * Focus on the element, or if it's a radio button, focus on the checked radio button in the same group.
+ */
+function focusElementOrCheckedOption(element: HTMLElement, focusOptions?: FocusOptions) {
+  // If the element receiving focus is a radio button, and there is another
+  // radio button in the same group that is currently checked, focus on that one
+  // instead.
+  // https://www.w3.org/WAI/ARIA/apg/patterns/radio/
+  if (element.tagName === 'INPUT') {
+    const inputElement = element as HTMLInputElement;
+    if (inputElement.type === 'radio' && inputElement.name) {
+      const checkedRadio = (inputElement.form ?? document).querySelector<HTMLInputElement>(
+        `input[type="radio"][name="${CSS.escape(inputElement.name)}"]:checked`,
+      );
+      if (checkedRadio) {
+        checkedRadio.focus(focusOptions);
+        return;
+      }
+    }
+  }
+
+  // Otherwise, just focus on the element itself.
+  element.focus(focusOptions);
+}
+
+/**
+ * Check if two elements are in the same focus context. This is true if they are the
+ * same element, or if they are radio buttons in the same group.
+ */
+function isSameFocusContext(element1: Element | null, element2: Element | null) {
+  if (!element1 || !element2) return false;
+  if (element1 === element2) return true;
+  if (element1.tagName === 'INPUT' && element2.tagName === 'INPUT') {
+    const input1 = element1 as HTMLInputElement;
+    const input2 = element2 as HTMLInputElement;
+    // https://html.spec.whatwg.org/multipage/input.html#radio-button-state-(type=radio)
+    if (
+      input1.type === 'radio' &&
+      input2.type === 'radio' &&
+      // radios without a name are not in the same group, even if they share the same form
+      input1.name &&
+      input1.name === input2.name &&
+      // either both have no form, or both have the same form
+      input1.form === input2.form
+    ) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/index.ts

@@ -3,3 +3,4 @@ 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';
+export { downloadAsCSV, downloadAsJSON } from './downloads.js';