general updates

modules/utils/deferredPromise.d.ts

@@ -1,4 +0,0 @@
-interface DeferredPromise<T> extends Promise<T>{
-  resolve: (value: T) => void
-  reject: (reason?: any) => void
-}

modules/utils/deferredPromise.mjs

@@ -1,5 +1,12 @@
 //@ts-check
-/// <reference path="./deferredPromise.d.ts"/>
+
+/**
+ * @template {any} T
+ * @typedef {{
+ *	resolve: (value: T) => void
+ *	reject: (reason?: any) => void
+ * } & Promise<T>} DeferredPromise<T> A promise that can be resolved externally
+ */
 
 /**
  * Returns a promise that can be resolved externally.

modules/utils/index.mjs

@@ -39,6 +39,8 @@ import { makeEventEmitter } from "./makeEventEmitter.mjs";
 import { makeFileLoader, makeFileLoadersTracker } from "./makeFileLoader.mjs";
 import { makeFileSizeFetcher } from "./makeFileSizeFetcher.mjs";
 import { makeSignal } from "./makeSignal.mjs";
+import { makeStyleSheet, css } from "./makeStyleSheet.mjs";
+import { makeTemplate, tmpl } from "./makeTemplate.mjs";
 import { markdownToMarkup } from "./markdownToMarkup.mjs";
 import { markupToDom } from "./markupToDom.mjs";
 import { memoize } from "./memoize.mjs";
@@ -58,7 +60,7 @@ import {
   metadata,
 } from "./path.mjs";
 import { percentFromProgress } from "./percentFromProgress.mjs";
-import { print, makeTemplate } from "./print.mjs";
+import { print, makeMiniStringTemplate } from "./print.mjs";
 import {
   querySelectorDoc,
   querySelectorParent,
@@ -68,6 +70,7 @@ import { retryPromise } from "./retryPromise.mjs";
 import { rewriteLocalUrls } from "./rewriteLocalUrls.mjs";
 import { throttle } from "./throttle.mjs";
 import { today } from "./today.mjs";
+import { trackProgressWithCSS } from "./trackProgressWithCSS.mjs";
 import { UnreachableCaseError } from "./UnreachableCaseError.mjs";
 import { wait } from "./wait.mjs";
 import { waitIfLocalHost } from "./waitIfLocalHost.mjs";
@@ -111,6 +114,10 @@ export {
   makeFileLoadersTracker,
   makeFileSizeFetcher,
   makeSignal,
+  makeStyleSheet, 
+  css,
+  makeTemplate, 
+  tmpl,
   markdownToMarkup,
   markupToDom,
   memoize,
@@ -127,7 +134,7 @@ export {
   metadata,
   percentFromProgress,
   print,
-  makeTemplate,
+  makeMiniStringTemplate,
   querySelectorDoc,
   querySelectorParent,
   querySelectorAll,
@@ -135,6 +142,7 @@ export {
   rewriteLocalUrls,
   throttle,
   today,
+  trackProgressWithCSS,
   UnreachableCaseError,
   wait,
   waitIfLocalHost,

modules/utils/makeStyleSheet.mjs

@@ -0,0 +1,24 @@
+//@ts-check
+
+
+/**
+ * Returns a stylesheet
+ * @param {string} css_string 
+ * @returns 
+ */
+export const makeStyleSheet = (css_string) => {
+  const stylesheet = new CSSStyleSheet();
+  stylesheet.replaceSync(css_string);
+  return stylesheet
+}
+
+/**
+ * Convenience literal to create DOM CSSStyleSheet instances
+ * @param {TemplateStringsArray} strings 
+ * @param  {...any} substitutions 
+ */
+export const css = (strings, ...substitutions) => {
+  const formattedString = strings.reduce((acc, curr, index) => acc + curr + (substitutions[index]||''), '');
+  console.log(formattedString)
+  return makeStyleSheet(formattedString);
+}

modules/utils/makeTemplate.mjs

@@ -0,0 +1,23 @@
+//@ts-check
+
+
+/**
+ * Returns a template
+ * @param {string} template_string 
+ * @returns 
+ */
+export const makeTemplate = (template_string) => {
+  const template = document.createElement("template")
+  template.innerHTML = template_string
+  return template
+}
+
+/**
+ * Convenience literal to create DOM template elements
+ * @param {TemplateStringsArray} strings 
+ * @param  {...any} substitutions 
+ */
+export const tmpl = (strings, ...substitutions) => {
+  const formattedString = strings.reduce((acc, curr, index) => acc + curr + (substitutions[index]||''), '');
+  return makeTemplate(formattedString);
+}

modules/utils/percentFromProgress.mjs

@@ -3,8 +3,9 @@
 /**
  * Returns a formatted percent from a given fraction.
  * @param {number} fraction any fractional number, e.g, 5/10
+ * @param {boolean} [pad]
  */
-export const percentFromProgress = (fraction) =>
+export const percentFromProgress = (fraction, pad = false) =>
-  /** @type {`${string}%`} */ (Math.round(fraction * 100) + "%");
+  /** @type {`${string}%`} */ (Math.round(fraction * 100) + "%").padStart(pad? 3 : 0, "0");
 
 export default percentFromProgress

modules/utils/print.mjs

@@ -12,8 +12,8 @@ export const print = (str, replacements) =>
  * @param {string} str 
  * @returns {(replacements: Record<string, any>) => string}
  */
-export const makeTemplate = (str) => print.bind(null, str)
+export const makeMiniStringTemplate = (str) => print.bind(null, str)
 
-print.makeTemplate = makeTemplate
+print.makeTemplate = makeMiniStringTemplate
 
 export default print

modules/utils/trackProgressWithCSS.mjs

@@ -0,0 +1,35 @@
+//@ts-check
+
+import { percentFromProgress } from "./percentFromProgress.mjs";
+
+/**
+ * Returns a function that can update an HTML Element.
+ * The function, when called with `received` and `total`, set 3 custom css vars
+ * on the element, which can be used in CSS to reflect the state of the object
+ * @param {HTMLElement} element
+ */
+export const trackProgressWithCSS = (element, prefix = "load-") => {
+  const keyFract = `--${prefix}fraction`;
+  const keyProgress = `--${prefix}progress`;
+  const keyProgressStr = `--${prefix}progress-str`;
+  const classComplete = `${prefix}complete`;
+  /**
+   * @param {{received: number, total: number}} progress
+   */
+  const setProgress = ({ received, total }) => {
+    const final = received == total;
+    const fraction = final ? 1 : received / total;
+    const percent = final ? "100%" : percentFromProgress(fraction, true);
+    console.log(keyProgress, percent);
+    element.style.setProperty(keyFract, `${fraction}`);
+    element.style.setProperty(keyProgress, percent);
+    element.style.setProperty(keyProgressStr, `"${percent}"`);
+    if (final) {
+      console.log("all done!", element, classComplete)
+      requestAnimationFrame(() => element.classList.add(classComplete));
+    }
+  };
+  return setProgress;
+};
+
+export default trackProgressWithCSS;