@prairielearn/browser-utils 2.2.14 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @prairielearn/browser-utils
 
+## 2.4.0
+
+### Minor Changes
+
+- 5b46852: Add `downloadTextFile`, `downloadAsJSON` and `downloadAsCSV` utilities
+
+## 2.3.0
+
+### Minor Changes
+
+- 65c63e0: Change the default return type of `decodeData` to unknown
+
 ## 2.2.14
 
 ### Patch 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/encode-data.d.ts

@@ -13,4 +13,4 @@ export declare function EncodedData<T = unknown>(data: T, elementId: string): Ht
  * @param elementId The element ID that stores the encoded data, from from EncodedData().
  * @returns The decoded data.
  */
-export declare function decodeData<T = any>(elementId: string): T;
+export declare function decodeData<T = unknown>(elementId: string): T;

package/dist/encode-data.js.map

@@ -1 +1 @@
-{"version":3,"file":"encode-data.js","sourceRoot":"","sources":["../src/encode-data.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,EAAuB,IAAI,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAc,IAAO,EAAE,SAAiB;IACjE,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7D,OAAO,IAAI,CAAA,eAAe,SAAS;MAC/B,WAAW;YACL,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAU,SAAiB;IACnD,MAAM,UAAU,GAAG,QAAQ,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC;IACnE,IAAI,UAAU,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,qCAAqC,SAAS,GAAG,CAAC,CAAC;IACrE,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClC,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["import { decode, encode } from 'js-base64';\n\nimport { type HtmlSafeString, html, unsafeHtml } from '@prairielearn/html';\n\n/**\n * Use this function as an HTML component encode data that will be passed to the client.\n *\n * @param data The data to encode.\n * @param elementId The element ID to use for the encoded data.\n *\n */\nexport function EncodedData<T = unknown>(data: T, elementId: string): HtmlSafeString {\n  const encodedData = unsafeHtml(encode(JSON.stringify(data)));\n  return html`<script id=\"${elementId}\" type=\"application/base64\">\n    ${encodedData}\n  </script>`;\n}\n\n/**\n * Decode data that was passed to the client from in HTML component using EncodeData().\n *\n * @param elementId The element ID that stores the encoded data, from from EncodedData().\n * @returns The decoded data.\n */\nexport function decodeData<T = any>(elementId: string): T {\n  const base64Data = document.getElementById(elementId)?.textContent;\n  if (base64Data == null) {\n    throw new Error(`No data found in element with ID \"${elementId}\"`);\n  }\n  const jsonData = decode(base64Data);\n  const data = JSON.parse(jsonData);\n  return data;\n}\n"]}
+{"version":3,"file":"encode-data.js","sourceRoot":"","sources":["../src/encode-data.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,EAAuB,IAAI,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAc,IAAO,EAAE,SAAiB;IACjE,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7D,OAAO,IAAI,CAAA,eAAe,SAAS;MAC/B,WAAW;YACL,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAc,SAAiB;IACvD,MAAM,UAAU,GAAG,QAAQ,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC;IACnE,IAAI,UAAU,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,qCAAqC,SAAS,GAAG,CAAC,CAAC;IACrE,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClC,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["import { decode, encode } from 'js-base64';\n\nimport { type HtmlSafeString, html, unsafeHtml } from '@prairielearn/html';\n\n/**\n * Use this function as an HTML component encode data that will be passed to the client.\n *\n * @param data The data to encode.\n * @param elementId The element ID to use for the encoded data.\n *\n */\nexport function EncodedData<T = unknown>(data: T, elementId: string): HtmlSafeString {\n  const encodedData = unsafeHtml(encode(JSON.stringify(data)));\n  return html`<script id=\"${elementId}\" type=\"application/base64\">\n    ${encodedData}\n  </script>`;\n}\n\n/**\n * Decode data that was passed to the client from in HTML component using EncodeData().\n *\n * @param elementId The element ID that stores the encoded data, from from EncodedData().\n * @returns The decoded data.\n */\nexport function decodeData<T = unknown>(elementId: string): T {\n  const base64Data = document.getElementById(elementId)?.textContent;\n  if (base64Data == null) {\n    throw new Error(`No data found in element with ID \"${elementId}\"`);\n  }\n  const jsonData = decode(base64Data);\n  const data = JSON.parse(jsonData);\n  return data;\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.2.14",
+  "version": "2.4.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/encode-data.ts

@@ -22,7 +22,7 @@ export function EncodedData<T = unknown>(data: T, elementId: string): HtmlSafeSt
  * @param elementId The element ID that stores the encoded data, from from EncodedData().
  * @returns The decoded data.
  */
-export function decodeData<T = any>(elementId: string): T {
+export function decodeData<T = unknown>(elementId: string): T {
   const base64Data = document.getElementById(elementId)?.textContent;
   if (base64Data == null) {
     throw new Error(`No data found in element with ID "${elementId}"`);

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';