@prairielearn/browser-utils 1.0.3 → 1.1.1

package/.turbo/turbo-build.log

@@ -4,7 +4,7 @@
 CLI Target: es2021
 CJS Build start
 ESM Build start
-CJS dist/index.js 2.68 KB
-CJS ⚡️ Build success in 139ms
-ESM dist/index.mjs 1.47 KB
-ESM ⚡️ Build success in 140ms
+CJS dist/index.js 4.22 KB
+CJS ⚡️ Build success in 146ms
+ESM dist/index.mjs 2.95 KB
+ESM ⚡️ Build success in 138ms

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @prairielearn/browser-utils
 
+## 1.1.1
+
+### Patch Changes
+
+- Updated dependencies [098f581da]
+  - @prairielearn/html@3.0.4
+
+## 1.1.0
+
+### Minor Changes
+
+- 0548e8401: Add `templateFromAttributes` function
+
 ## 1.0.3
 
 ### Patch Changes

package/README.md

@@ -59,6 +59,38 @@ onDocumentReady(() => {
 });
 ```
 
+### `templateFromAttributes`
+
+This function simplifies the common pattern of taking attributes from one HTML element and using them as the content of other HTML elements. This is often done with modals that need to display information about a specific entity.
+
+Consider the following simplified markup:
+
+```html
+<button class="js-delete-course" data-course-name="CS 123">Delete course</button>
+
+<div class="modal" id="deleteCourseModal">
+  <p>Are you sure you want to delete course <strong class="js-course-name"></strong>?</p>
+  <button type="button">Cancel</button>
+  <button type="button">Delete <span class="js-course-name"></span></button>
+</div>
+```
+
+The following JavaScript will "template" the value from `data-course-name` on the button into the elements with the `.js-course-name` in the modal.
+
+```ts
+import { templateFromAttributes } from '@prairielearn/browser-utils';
+
+const modal = document.querySelector('#deleteCourseModal');
+document.querySelectorAll('.js-delete-course').forEach((el) => {
+  el.addEventListener('click', (e) => {
+    const button = e.target;
+    templateFromAttributes(e.currentTarget, modal, {
+      'data-course-name': '.js-course-name',
+    });
+  });
+});
+```
+
 ## Development
 
 Unlike most other `@prairielearn` packages, this one is built with [`tsup`](https://tsup.egoist.dev/), which is used to generate both CJS and ESM output. The latter is important for ensuring that tree-shaking works correctly when building client bundles, which is important for minimizing bundle sizes.

package/dist/index.d.ts

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

package/dist/index.js

@@ -24,7 +24,8 @@ __export(src_exports, {
   decodeData: () => decodeData,
   onDocumentReady: () => onDocumentReady,
   parseHTML: () => parseHTML,
-  parseHTMLElement: () => parseHTMLElement
+  parseHTMLElement: () => parseHTMLElement,
+  templateFromAttributes: () => templateFromAttributes
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -73,11 +74,49 @@ function decodeData(elementId) {
   const data = JSON.parse(jsonData);
   return data;
 }
+
+// src/template-from-attributes.ts
+function templateFromAttributes(source, target, attributes) {
+  Object.entries(attributes).forEach(([sourceAttribute, targetSelector]) => {
+    const attributeValue = source.getAttribute(sourceAttribute);
+    if (attributeValue == null) {
+      console.error(`Attribute "${sourceAttribute}" not found on source element`);
+      return;
+    }
+    const targets = target.querySelectorAll(targetSelector);
+    if (targets.length === 0) {
+      console.error(`No elements found matching selector "${targetSelector}"`);
+      return;
+    }
+    targets.forEach((targetElement) => {
+      if (targetElement instanceof HTMLInputElement) {
+        if (targetElement.type === "checkbox") {
+          const attributeParsed = JSON.parse(attributeValue);
+          targetElement.checked = !!attributeParsed;
+          targetElement.dispatchEvent(new Event("change", { bubbles: true }));
+        } else {
+          targetElement.value = attributeValue;
+        }
+      } else if (targetElement instanceof HTMLSelectElement) {
+        const i = Array.from(targetElement.options).findIndex((o) => o.value === attributeValue);
+        if (i >= 0) {
+          targetElement.selectedIndex = i;
+          targetElement.dispatchEvent(new Event("change", { bubbles: true }));
+        } else {
+          console.error(`Could not find option with value "${attributeValue}"`);
+        }
+      } else {
+        targetElement.textContent = attributeValue;
+      }
+    });
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   EncodedData,
   decodeData,
   onDocumentReady,
   parseHTML,
-  parseHTMLElement
+  parseHTMLElement,
+  templateFromAttributes
 });

package/dist/index.mjs

@@ -43,10 +43,48 @@ function decodeData(elementId) {
   const data = JSON.parse(jsonData);
   return data;
 }
+
+// src/template-from-attributes.ts
+function templateFromAttributes(source, target, attributes) {
+  Object.entries(attributes).forEach(([sourceAttribute, targetSelector]) => {
+    const attributeValue = source.getAttribute(sourceAttribute);
+    if (attributeValue == null) {
+      console.error(`Attribute "${sourceAttribute}" not found on source element`);
+      return;
+    }
+    const targets = target.querySelectorAll(targetSelector);
+    if (targets.length === 0) {
+      console.error(`No elements found matching selector "${targetSelector}"`);
+      return;
+    }
+    targets.forEach((targetElement) => {
+      if (targetElement instanceof HTMLInputElement) {
+        if (targetElement.type === "checkbox") {
+          const attributeParsed = JSON.parse(attributeValue);
+          targetElement.checked = !!attributeParsed;
+          targetElement.dispatchEvent(new Event("change", { bubbles: true }));
+        } else {
+          targetElement.value = attributeValue;
+        }
+      } else if (targetElement instanceof HTMLSelectElement) {
+        const i = Array.from(targetElement.options).findIndex((o) => o.value === attributeValue);
+        if (i >= 0) {
+          targetElement.selectedIndex = i;
+          targetElement.dispatchEvent(new Event("change", { bubbles: true }));
+        } else {
+          console.error(`Could not find option with value "${attributeValue}"`);
+        }
+      } else {
+        targetElement.textContent = attributeValue;
+      }
+    });
+  });
+}
 export {
   EncodedData,
   decodeData,
   onDocumentReady,
   parseHTML,
-  parseHTMLElement
+  parseHTMLElement,
+  templateFromAttributes
 };

package/dist/template-from-attributes.d.ts

@@ -0,0 +1,18 @@
+type AttributeMap = Record<string, string>;
+/**
+ * For each key in `attributes`, copies that attribute's value from `source`
+ * into all elements within `target` that match the corresponding value in
+ * `attributes`.
+ *
+ * For `<input type="checkbox">` elements it interprets the attribute as JSON
+ * and uses the truthiness of it to set `checked`. For other `<input>` elements,
+ * it sets the `value` attribute. For all others, it sets the `textContent`
+ * attribute.
+ *
+ * @param source The element to copy attributes from
+ * @param target The element to copy attributes into
+ * @param attributes A map of attributes to copy from `source` to `target`
+ * @param param.debug If true, logs debug information to the console
+ */
+export declare function templateFromAttributes(source: HTMLElement, target: HTMLElement, attributes: AttributeMap): void;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prairielearn/browser-utils",
-  "version": "1.0.3",
+  "version": "1.1.1",
   "main": "dist/index.js",
   "sideEffects": false,
   "repository": {
@@ -21,7 +21,7 @@
     "dev": "tsup --watch src/index.ts"
   },
   "dependencies": {
-    "@prairielearn/html": "^3.0.3",
+    "@prairielearn/html": "^3.0.4",
     "js-base64": "^3.7.5"
   },
   "devDependencies": {

package/src/index.ts

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

package/src/template-from-attributes.ts

@@ -0,0 +1,62 @@
+type AttributeMap = Record<string, string>;
+
+/**
+ * For each key in `attributes`, copies that attribute's value from `source`
+ * into all elements within `target` that match the corresponding value in
+ * `attributes`.
+ *
+ * For `<input type="checkbox">` elements it interprets the attribute as JSON
+ * and uses the truthiness of it to set `checked`. For other `<input>` elements,
+ * it sets the `value` attribute. For all others, it sets the `textContent`
+ * attribute.
+ *
+ * @param source The element to copy attributes from
+ * @param target The element to copy attributes into
+ * @param attributes A map of attributes to copy from `source` to `target`
+ * @param param.debug If true, logs debug information to the console
+ */
+export function templateFromAttributes(
+  source: HTMLElement,
+  target: HTMLElement,
+  attributes: AttributeMap,
+) {
+  Object.entries(attributes).forEach(([sourceAttribute, targetSelector]) => {
+    const attributeValue = source.getAttribute(sourceAttribute);
+    if (attributeValue == null) {
+      console.error(`Attribute "${sourceAttribute}" not found on source element`);
+      return;
+    }
+
+    const targets = target.querySelectorAll(targetSelector);
+    if (targets.length === 0) {
+      console.error(`No elements found matching selector "${targetSelector}"`);
+      return;
+    }
+
+    targets.forEach((targetElement) => {
+      if (targetElement instanceof HTMLInputElement) {
+        if (targetElement.type === 'checkbox') {
+          const attributeParsed = JSON.parse(attributeValue);
+          targetElement.checked = !!attributeParsed;
+          // Manually trigger a 'change' event. This does not trigger
+          // automatically when we change properties like 'checked'.
+          targetElement.dispatchEvent(new Event('change', { bubbles: true }));
+        } else {
+          targetElement.value = attributeValue;
+        }
+      } else if (targetElement instanceof HTMLSelectElement) {
+        const i = Array.from(targetElement.options).findIndex((o) => o.value === attributeValue);
+        if (i >= 0) {
+          targetElement.selectedIndex = i;
+          // Manually trigger a 'change' event. This does not trigger
+          // automatically when we change properties like 'checked'.
+          targetElement.dispatchEvent(new Event('change', { bubbles: true }));
+        } else {
+          console.error(`Could not find option with value "${attributeValue}"`);
+        }
+      } else {
+        targetElement.textContent = attributeValue;
+      }
+    });
+  });
+}

package/tsconfig.json

@@ -4,7 +4,7 @@
     "outDir": "./dist",
     "rootDir": "./src",
     // Unlike other PrairieLearn packages, we use another tool to actually
-    // emit transpiled JavaScript. See note in `README.md`. 
-    "emitDeclarationOnly": true,
-  },
+    // emit transpiled JavaScript. See note in `README.md`.
+    "emitDeclarationOnly": true
+  }
 }