@xiee/utils 1.9.5 → 1.10.0

package/README.md

@@ -163,6 +163,11 @@ KaTeX's auto-render extension.
 Right-align a `<blockquote>` footer if the footer is a `<p>` that starts with
 the em-dash.
 
+## snap.js
+
+Create HTML slides using [the CSS Scroll Snap
+technique](https://yihui.org/en/2023/09/snap-slides/).
+
 ## tabsets.js
 
 Create tabsets from section headings and their content. See [this

package/css/snap.css

@@ -0,0 +1,98 @@
+:root { --slide-width: 100%; }
+html { scroll-snap-type: y mandatory; }
+th, td { padding: .2em .5em; }
+.slide { padding: 0 1em; }
+.slide, .frontmatter .main, .middle .main {
+  display: flex;
+  flex-direction: column;
+}
+.slide > .main { flex-grow: 1; }
+.slide > .header { margin-bottom: 1em; }
+.slide h2, .slide h3 { margin-top: unset; }
+body {
+  max-width: fit-content;
+  padding: 0;
+}
+a { color: #eb4a47; }
+:not(pre) > code { background-color: #fdfded; }
+#TOC { columns: 2; }
+#TOC::before {
+  font-size: 1.3em;
+  font-weight: bold;
+  display: block;
+  border-bottom: 1px solid #666;
+}
+.frontmatter .main, .middle .main {
+  justify-content: center;
+}
+.footer {
+  display: flex;
+  justify-content: space-between;
+  opacity: .5;
+  font: .7em monospace;
+}
+.inverse {
+  background-color: #eee;
+  filter: invert(1);
+}
+.fade {
+  background: repeating-linear-gradient(135deg, white, white 30px, #ddd 32px, #ddd 32px);
+  opacity: 0.6;
+}
+.center { text-align: center; }
+.slide-container h2 .section-number {
+  display: inline-block;
+  background-color: #666;
+  color: white;
+  padding: 0 .1em;
+  margin-right: .3em;
+}
+.overview { font-size: .8em; }
+.overview .slide-container {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: space-evenly;
+}
+.overview .slide-container .slide {
+  width: var(--slide-width);
+  border: 1px dotted #ccc;
+  margin-bottom: 0.5em;
+}
+.mirrored { transform: scale(-1, 1); }
+.timer { visibility: hidden; }
+html:fullscreen::-webkit-scrollbar, .spacer { display: none; }
+html:fullscreen {
+  -ms-overflow-style: none;
+  scrollbar-width: none;
+}
+@media screen and (min-width: 992px) {
+  :root {
+    --slide-width: 49%;
+    --slide-scale: 1;
+    --slide-ratio: 0.75;
+    --slide-top: auto;
+  }
+  .slide-mode {
+    font-size: 2em;
+    background-color: #d7d8d2;
+    scale: var(--slide-scale);
+    margin-top: var(--slide-top);
+  }
+  .slide-mode .slide {
+    min-height: calc(100vh / var(--slide-scale));
+    width: calc(100vh / var(--slide-ratio) / var(--slide-scale));
+    box-shadow: 0 0 2em #888;
+    clip-path: inset(0 -2em 0 -2em);
+    background-color: white;
+    scroll-snap-align: start;
+  }
+  li li { font-size: .9em; }
+  .slide-mode .spacer { display: block; }
+  .slide-mode .timer { visibility: visible; }
+}
+@media (min-width: 1400px) {
+  :root { --slide-width: 33%; }
+}
+@media (min-width: 1800px) {
+  :root { --slide-width: 24.67%; }
+}

package/css/snap.min.css

@@ -0,0 +1 @@
+:root{--slide-width:100%}html{scroll-snap-type:y mandatory}td,th{padding:.2em .5em}.slide{padding:0 1em}.frontmatter .main,.middle .main,.slide{display:flex;flex-direction:column}.slide>.main{flex-grow:1}.slide>.header{margin-bottom:1em}.slide h2,.slide h3{margin-top:unset}body{max-width:fit-content;padding:0}a{color:#eb4a47}:not(pre)>code{background-color:#fdfded}#TOC{columns:2}#TOC::before{font-size:1.3em;font-weight:700;display:block;border-bottom:1px solid #666}.frontmatter .main,.middle .main{justify-content:center}.footer{display:flex;justify-content:space-between;opacity:.5;font:.7em monospace}.inverse{background-color:#eee;filter:invert(1)}.fade{background:repeating-linear-gradient(135deg,#fff,#fff 30px,#ddd 32px,#ddd 32px);opacity:.6}.center{text-align:center}.slide-container h2 .section-number{display:inline-block;background-color:#666;color:#fff;padding:0 .1em;margin-right:.3em}.overview{font-size:.8em}.overview .slide-container{display:flex;flex-wrap:wrap;justify-content:space-evenly}.overview .slide-container .slide{width:var(--slide-width);border:1px dotted #ccc;margin-bottom:.5em}.mirrored{transform:scale(-1,1)}.timer{visibility:hidden}.spacer,html:fullscreen::-webkit-scrollbar{display:none}html:fullscreen{-ms-overflow-style:none;scrollbar-width:none}@media screen and (min-width:992px){:root{--slide-width:49%;--slide-scale:1;--slide-ratio:0.75;--slide-top:auto}.slide-mode{font-size:2em;background-color:#d7d8d2;scale:var(--slide-scale);margin-top:var(--slide-top)}.slide-mode .slide{min-height:calc(100vh / var(--slide-scale));width:calc(100vh / var(--slide-ratio)/ var(--slide-scale));box-shadow:0 0 2em #888;clip-path:inset(0 -2em 0 -2em);background-color:#fff;scroll-snap-align:start}li li{font-size:.9em}.slide-mode .spacer{display:block}.slide-mode .timer{visibility:visible}}@media (min-width:1400px){:root{--slide-width:33%}}@media (min-width:1800px){:root{--slide-width:24.67%}}

package/js/snap.js

@@ -0,0 +1,193 @@
+(function(d) {
+  let p = d.body;  // container of slides; assume <body> for now
+  const s1 = ':scope > hr:not([class])', s2 = ':scope > h2';
+  // find a container that has at least n "slides"
+  function findContainer(s, n = 1) {
+    if (p.querySelectorAll(s).length >= n) return true;
+    // if body doesn't contain headings or <hr>s, look into children
+    for (let i = 0; i < p.children.length; i++) {
+      if (p.children[i].querySelectorAll(s).length >= n) {
+        p = p.children[i]; break;
+      }
+    }
+    return false;
+  }
+  function newEl(tag, cls) {
+    const el = d.createElement(tag);
+    if (cls) el.className = cls;
+    return el;
+  }
+  if (!findContainer(s1, 3)) {
+    // if not enough <hr>s found in children; look for <h2> instead
+    if (p.tagName === 'BODY') {
+      // not enough h2 found, this page is not appropriate for slides
+      if (!findContainer(s2) && p.tagName === 'BODY') return;
+      p.querySelectorAll(s2).forEach(h2 => h2.before(newEl('hr')));
+    }
+  }
+  p.classList.add('slide-container');
+  // add 'slide' class to the frontmatter div and toc
+  ['.frontmatter', '#TOC'].forEach(sel => {
+    const el = d.body.querySelector(sel);
+    if (!el) return;
+    if (sel === '.frontmatter') {
+      el.classList.add('slide');
+    } else {
+      const s = newSlide(); el.before(s); s.append(el);
+    }
+  });
+
+  function newSlide(s) {
+    return (s?.innerText === '') ? s : newEl('div', 'slide');
+  }
+  function isSep(el) {
+    return el.tagName === 'HR' && el.attributes.length === 0;
+  }
+  let el = p.firstElementChild; isSep(el) && el.remove();
+  el = p.firstElementChild; if (!el) return;
+  let s = newSlide(); el.before(s);
+  while (true) {
+    let el = s.nextSibling;
+    if (!el) break;
+    // remove slide separators (<hr>) and create new slide
+    if (isSep(el)) {
+      s = newSlide(s);
+      el.before(s); el.remove();
+    } else if (el.classList?.contains('slide')) {
+      s = newSlide(s);
+      el.after(s);
+    } else {
+      s.append(el);
+    }
+  }
+  function setAttr(el, attr) {
+    const m = newEl('div');
+    m.innerHTML = `<div ${attr}></div>`;
+    const attrs = m.firstElementChild.attributes;
+    for (const a of attrs) {
+      el.setAttribute(a.name, a.value);
+    }
+    m.remove();
+  }
+  function reveal(el) {
+    setTimeout(() => el?.scrollIntoView(), 100);
+  }
+  const dE = d.documentElement, dC = d.body.classList;
+  const slides = d.querySelectorAll('div.slide'), N = slides.length,
+        tm = d.querySelector('span.timer'), fn = d.querySelector('.footnotes');
+  slides.forEach((s, i) => {
+    // slide header, main body, and footer
+    const header = newEl('div', 'header'), main = newEl('div', 'main'), footer = newEl('div', 'footer');
+    main.append(...s.childNodes);
+    s.append(main);
+    s.insertAdjacentElement('afterbegin', header);
+    s.insertAdjacentElement('beforeend', footer);
+    // append footnotes
+    if (fn) s.querySelectorAll('.footnote-ref > a[href^="#fn"]').forEach(a => {
+      const li = fn.querySelector('li' + a.getAttribute('href'));
+      if (!li) return;
+      let f = s.querySelector('section.footnotes');
+      if (!f) {
+        f = newEl('section', 'footnotes'); footer.before(f);
+      }
+      f.append(li);
+      li.firstElementChild?.insertAdjacentHTML('afterbegin', `[${a.innerHTML}] `);
+      li.outerHTML = li.innerHTML;
+    });
+    // add a timer
+    footer.append(tm ? tm.cloneNode() : newEl('span', 'timer'));
+    // add page numbers
+    const n = newEl('span', 'page-number');
+    n.innerText = i + 1 + '/' + N;
+    n.onclick = e => location.hash = i + 1;
+    footer.append(n);
+    // apply slide attributes in <!--# -->
+    for (const node of main.childNodes) {
+      if (node.nodeType !== Node.COMMENT_NODE) continue;
+      let t = node.textContent;
+      if (!/^#/.test(t)) continue;
+      t = t.replace(/^#/, '');
+      const r = /[\s\n]class="([^"]+)"/, m = t.match(r);
+      if (m) {
+        t = t.replace(r, '').trim();
+        s.className += ' ' + m[1];
+      }
+      if (t) setAttr(s, t);
+      break;
+    }
+    s.addEventListener('click', e => {
+      e.altKey && (toggleView(e), reveal(e.target));
+    });
+  });
+  [...d.querySelectorAll('a.footnote-backref'), fn, tm].forEach(el => el?.remove());
+  const tms = d.querySelectorAll('span.timer'), t1 = 1000 * tms[0].dataset.total;
+  let t0;
+  function startTimers() {
+    t0 = new Date();
+    setInterval(setTimers, 1000);
+  }
+  function setTimers() {
+    if (!dC.contains('slide-mode')) return;  // set timer only in slide mode
+    let t = (new Date() - t0);
+    if (t1) t = t1 - t;
+    const t2 = new Date(Math.abs(t)).toISOString().substr(11, 8).replace(/^00:/, '');
+    tms.forEach(el => {
+      el.innerText = t2;
+      if (t < 0) el.style.visibility = el.style.visibility === 'hidden' ? '' : 'hidden';
+    });
+  }
+  function toggleView(e) {
+    (dC.toggle('overview') ? dC.remove('slide-mode') : setScale(e));
+  }
+  // press f for fullscreen mode
+  d.addEventListener('keyup', e => {
+    if (e.target !== d.body) return;
+    e.key === 'f' && dE.requestFullscreen();
+    e.key === 'o' && toggleView(e);
+    e.key === 'm' && dC.toggle('mirrored');
+    sessionStorage.setItem('body-class', d.body.className);
+  });
+  // start timer and set scale on fullscreen
+  d.onfullscreenchange = e => {
+    d.fullscreenElement && (!t0 && startTimers(), setScale(e));
+  }
+  tms.forEach(el => el.addEventListener('click', e => startTimers()));
+  // measure the height of an empty slide
+  let H = -1;
+  function slideHeight() {
+    if (H >= 0) return H;
+    const s = newEl('div', 'slide');
+    p.querySelector('.slide:last-of-type').after(s);
+    H = s.offsetHeight;
+    s.remove()
+    return H;
+  }
+  // scale slides according to window height (baseline: 900px)
+  const sty = newEl('style'); sty.setAttribute('type', 'text/css');
+  d.head.append(sty);
+  // default height/width ratio from screen size
+  sty.innerHTML = `:root{--slide-ratio:${screen.height / screen.width}}`;
+  // read --slide-ratio in case users have set it in their CSS
+  const ratio = +getComputedStyle(dE).getPropertyValue('--slide-ratio');
+  function setScale(e) {
+    // navigate to a slide indicated by the hash if provided
+    e.type === 'load' && reveal(slides[location.hash.replace(/^#/, '') - 1]);
+    if (dC.contains('overview')) return;
+    let h = window.innerHeight, p = h / 900, r2 = h / window.innerWidth, full = d.fullscreenElement;
+    // add slide mode if there's enough window width, and remove it in case of scrollbar
+    dC.toggle('slide-mode', full || r2 <= ratio) &&
+      (!full && (dE.scrollWidth > dE.offsetWidth)) && dC.remove('slide-mode');
+    sty.innerHTML = `:root{--slide-ratio:${ratio};--slide-scale:${p};--slide-top:${(p - 1)/2 * d.body.scrollHeight + 'px'};}`;
+    // add spacers with enough height on load
+    !d.querySelector('.spacer.fade') && dC.contains('slide-mode') && slides.forEach(s => {
+      const sp = newEl('div', 'spacer fade'), h = s.offsetHeight, h2 = slideHeight();
+      s.append(sp);
+      if (h <= h2) return;
+      sp.style.height = (h2 - h % h2) * p + 'px';
+    });
+  }
+  ['load', 'resize'].forEach(evt => window.addEventListener(evt, setScale));
+  // restore previsouly saved body class
+  const bc = sessionStorage.getItem('body-class');
+  if (bc) d.body.className += ' ' + bc;
+})(document);

package/js/snap.min.js

@@ -0,0 +1 @@
+!function(e){let t=e.body;const n=":scope > h2";function o(e,n=1){if(t.querySelectorAll(e).length>=n)return!0;for(let o=0;o<t.children.length;o++)if(t.children[o].querySelectorAll(e).length>=n){t=t.children[o];break}return!1}function r(t,n){const o=e.createElement(t);return n&&(o.className=n),o}if(!o(":scope > hr:not([class])",3)&&"BODY"===t.tagName){if(!o(n)&&"BODY"===t.tagName)return;t.querySelectorAll(n).forEach((e=>e.before(r("hr"))))}function i(e){return""===e?.innerText?e:r("div","slide")}function s(e){return"HR"===e.tagName&&0===e.attributes.length}t.classList.add("slide-container"),[".frontmatter","#TOC"].forEach((t=>{const n=e.body.querySelector(t);if(n)if(".frontmatter"===t)n.classList.add("slide");else{const e=i();n.before(e),e.append(n)}}));let l=t.firstElementChild;if(s(l)&&l.remove(),l=t.firstElementChild,!l)return;let c=i();for(l.before(c);;){let e=c.nextSibling;if(!e)break;s(e)?(c=i(c),e.before(c),e.remove()):e.classList?.contains("slide")?(c=i(c),e.after(c)):c.append(e)}function a(e,t){const n=r("div");n.innerHTML=`<div ${t}></div>`;const o=n.firstElementChild.attributes;for(const t of o)e.setAttribute(t.name,t.value);n.remove()}function d(e){setTimeout((()=>e?.scrollIntoView()),100)}const f=e.documentElement,u=e.body.classList,h=e.querySelectorAll("div.slide"),m=h.length,p=e.querySelector("span.timer"),y=e.querySelector(".footnotes");h.forEach(((e,t)=>{const n=r("div","header"),o=r("div","main"),i=r("div","footer");o.append(...e.childNodes),e.append(o),e.insertAdjacentElement("afterbegin",n),e.insertAdjacentElement("beforeend",i),y&&e.querySelectorAll('.footnote-ref > a[href^="#fn"]').forEach((t=>{const n=y.querySelector("li"+t.getAttribute("href"));if(!n)return;let o=e.querySelector("section.footnotes");o||(o=r("section","footnotes"),i.before(o)),o.append(n),n.firstElementChild?.insertAdjacentHTML("afterbegin",`[${t.innerHTML}] `),n.outerHTML=n.innerHTML})),i.append(p?p.cloneNode():r("span","timer"));const s=r("span","page-number");s.innerText=t+1+"/"+m,s.onclick=e=>location.hash=t+1,i.append(s);for(const t of o.childNodes){if(t.nodeType!==Node.COMMENT_NODE)continue;let n=t.textContent;if(!/^#/.test(n))continue;n=n.replace(/^#/,"");const o=/[\s\n]class="([^"]+)"/,r=n.match(o);r&&(n=n.replace(o,"").trim(),e.className+=" "+r[1]),n&&a(e,n);break}e.addEventListener("click",(e=>{e.altKey&&(q(e),d(e.target))}))})),[...e.querySelectorAll("a.footnote-backref"),y,p].forEach((e=>e?.remove()));const g=e.querySelectorAll("span.timer"),b=1e3*g[0].dataset.total;let v;function E(){v=new Date,setInterval(S,1e3)}function S(){if(!u.contains("slide-mode"))return;let e=new Date-v;b&&(e=b-e);const t=new Date(Math.abs(e)).toISOString().substr(11,8).replace(/^00:/,"");g.forEach((n=>{n.innerText=t,e<0&&(n.style.visibility="hidden"===n.style.visibility?"":"hidden")}))}function q(e){u.toggle("overview")?u.remove("slide-mode"):N(e)}e.addEventListener("keyup",(t=>{t.target===e.body&&("f"===t.key&&f.requestFullscreen(),"o"===t.key&&q(t),"m"===t.key&&u.toggle("mirrored"),sessionStorage.setItem("body-class",e.body.className))})),e.onfullscreenchange=t=>{e.fullscreenElement&&(!v&&E(),N(t))},g.forEach((e=>e.addEventListener("click",(e=>E()))));let L=-1;function T(){if(L>=0)return L;const e=r("div","slide");return t.querySelector(".slide:last-of-type").after(e),L=e.offsetHeight,e.remove(),L}const w=r("style");w.setAttribute("type","text/css"),e.head.append(w),w.innerHTML=`:root{--slide-ratio:${screen.height/screen.width}}`;const A=+getComputedStyle(f).getPropertyValue("--slide-ratio");function N(t){if("load"===t.type&&d(h[location.hash.replace(/^#/,"")-1]),u.contains("overview"))return;let n=window.innerHeight,o=n/900,i=n/window.innerWidth,s=e.fullscreenElement;u.toggle("slide-mode",s||i<=A)&&!s&&f.scrollWidth>f.offsetWidth&&u.remove("slide-mode"),w.innerHTML=`:root{--slide-ratio:${A};--slide-scale:${o};--slide-top:${(o-1)/2*e.body.scrollHeight+"px"};}`,!e.querySelector(".spacer.fade")&&u.contains("slide-mode")&&h.forEach((e=>{const t=r("div","spacer fade"),n=e.offsetHeight,i=T();e.append(t),n<=i||(t.style.height=(i-n%i)*o+"px")}))}["load","resize"].forEach((e=>window.addEventListener(e,N)));const H=sessionStorage.getItem("body-class");H&&(e.body.className+=" "+H)}(document);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiee/utils",
-  "version": "1.9.5",
+  "version": "1.10.0",
   "description": "Miscellaneous tools and utilities to manipulate HTML pages",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"