pgn-postmortem 0.1.0__py3-none-any.whl

pgn_postmortem/static/history.js

@@ -0,0 +1,363 @@
+// pgn-postmortem: the reading history (ROADMAP.md, F-8).
+//
+// The site builder writes this file, unchanged, into every page. It keeps, in
+// this browser only (localStorage), which games were opened and which answers
+// were revealed, and shows it on the index: a "Recently viewed" list and a
+// mark on each viewed game; and on the quiz page (ROADMAP.md, F-9), a mark on
+// each question whose answer was revealed. It loads nothing and sends nothing
+// anywhere.
+// Without it (scripts off, or no storage) the pages read as they would
+// without it: what it shows is hidden in the HTML until it shows it.
+//
+// What it reads from the page, and nothing else:
+//   html[data-site]           the site key KEY, set at build time
+//   article[data-game]        an article, and its game's id ID
+//   details[data-move]        an answer, by its move: "31b" for Black's 31st
+//   li[data-game][data-moves] on the index, a game and its current questions ("3b 17w")
+//   section#history           on the index, the history, hidden until shown here, with
+//                             the list ol#history-recent and the button #history-clear
+//   ol#quiz li[data-game][data-move]
+//                             on the quiz page, a question: its game and its move
+//
+// What it stores, every key starting with "pgn-postmortem:KEY:":
+//   pgn-postmortem:KEY:viewed:ID               when the game was last opened, in ms
+//   pgn-postmortem:KEY:revealed:ID:MOVE        "1", once that answer was opened
+// A value of any other shape is ignored. "Clear history", on the index only,
+// removes these keys and no other. The quiz page only reads them.
+//
+// The file has no asterisk in it: no page may show a bare asterisk outside its
+// PGN section (tests/test_presumed_results.py).
+
+(function () {
+  "use strict";
+
+  var PREFIX = "pgn-postmortem:";
+  var RECENT = 10;
+  var SITE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+  var GAME = /^[A-Za-z0-9_-]{1,64}$/;
+  var MOVE = /^[1-9][0-9]{0,3}[wb]$/;
+  var TIME = /^[1-9][0-9]{0,15}$/;
+  var CONFIRM = "Clear the reading history of this site in this browser? " +
+    "The games you opened and the answers you revealed will be forgotten.";
+  var STYLE =
+    ".seen { display: inline-block; margin-left: .5rem; padding: 0 .45rem; border-radius: .7rem;\n" +
+    "  background: var(--answer); color: var(--fg); font-size: .8rem; line-height: 1.5; }\n" +
+    "#history-clear { font: inherit; font-size: .9rem; min-height: 2.75rem; padding: .3rem .9rem;\n" +
+    "  color: var(--link); background: var(--box); border: 1px solid var(--rule); border-radius: .4rem;\n" +
+    "  cursor: pointer; }\n";
+
+  function openStorage(win) {
+    try {
+      var storage = win.localStorage;
+      if (!storage) {
+        return null;
+      }
+      var probe = PREFIX + "probe";
+      storage.setItem(probe, "1");
+      storage.removeItem(probe);
+      return storage;
+    } catch (error) {
+      return null;
+    }
+  }
+
+  function read(storage, key) {
+    try {
+      var value = storage.getItem(key);
+      return typeof value === "string" ? value : null;
+    } catch (error) {
+      return null;
+    }
+  }
+
+  function write(storage, key, value) {
+    try {
+      storage.setItem(key, value);
+    } catch (error) {
+      // full, or refused: the history is a convenience, the page goes on
+    }
+  }
+
+  function viewedAt(storage, prefix, id) {
+    var value = read(storage, prefix + "viewed:" + id);
+    return value !== null && TIME.test(value) ? Number(value) : 0;
+  }
+
+  function isRevealed(storage, prefix, id, move) {
+    return read(storage, prefix + "revealed:" + id + ":" + move) === "1";
+  }
+
+  // --- an article ---
+
+  function watchAnswer(storage, prefix, id, details) {
+    var move = details.getAttribute("data-move");
+    if (!move || !MOVE.test(move)) {
+      return;
+    }
+    var key = prefix + "revealed:" + id + ":" + move;
+    function record() {
+      if (details.open && read(storage, key) !== "1") {
+        write(storage, key, "1");
+      }
+    }
+    details.addEventListener("toggle", record);
+    record();
+  }
+
+  // Returns what to do when the page is shown again (see start).
+  function startArticle(doc, storage, prefix, article) {
+    var id = article.getAttribute("data-game");
+    if (!id || !GAME.test(id)) {
+      return null;
+    }
+    function view() {
+      write(storage, prefix + "viewed:" + id, String(Date.now()));
+    }
+    view();
+    var answers = doc.getElementsByTagName("details");
+    for (var i = 0; i < answers.length; i++) {
+      watchAnswer(storage, prefix, id, answers[i]);
+    }
+    return view;
+  }
+
+  // --- the index ---
+
+  function markText(storage, prefix, game) {
+    var m = game.moves.length;
+    if (m === 0) {
+      return "viewed";
+    }
+    var k = 0;
+    for (var i = 0; i < m; i++) {
+      if (isRevealed(storage, prefix, game.id, game.moves[i])) {
+        k += 1;
+      }
+    }
+    return "viewed · " + k + "/" + m + (m === 1 ? " answer" : " answers");
+  }
+
+  function makeMark(doc, text) {
+    var mark = doc.createElement("span");
+    mark.className = "seen";
+    mark.textContent = text;
+    return mark;
+  }
+
+  function indexGames(doc) {
+    var games = [];
+    var items = doc.getElementsByTagName("li");
+    for (var i = 0; i < items.length; i++) {
+      var id = items[i].getAttribute("data-game");
+      if (!id || !GAME.test(id)) {
+        continue;
+      }
+      var moves = (items[i].getAttribute("data-moves") || "").split(" ").filter(function (move) {
+        return MOVE.test(move);
+      });
+      var link = items[i].getElementsByTagName("a")[0];
+      var spans = items[i].getElementsByTagName("span");
+      var meta = null;
+      for (var j = 0; j < spans.length; j++) {
+        if (spans[j].className === "meta" && spans[j].parentNode === items[i]) {
+          meta = spans[j];
+        }
+      }
+      games.push({ id: id, item: items[i], moves: moves, link: link, meta: meta, order: games.length, mark: null });
+    }
+    return games;
+  }
+
+  function addStyle(doc) {
+    if (doc.getElementById("history-style") || !doc.head) {
+      return;
+    }
+    var style = doc.createElement("style");
+    style.setAttribute("id", "history-style");
+    style.textContent = STYLE;
+    doc.head.appendChild(style);
+  }
+
+  function render(doc, storage, prefix, games, section) {
+    var list = doc.getElementById("history-recent");
+    var viewed = [];
+    for (var i = 0; i < games.length; i++) {
+      var game = games[i];
+      if (game.mark) {
+        game.mark.parentNode.removeChild(game.mark);
+        game.mark = null;
+      }
+      var time = viewedAt(storage, prefix, game.id);
+      if (time) {
+        game.text = markText(storage, prefix, game);
+        // on the game's first line, before its date and event
+        game.mark = game.item.insertBefore(makeMark(doc, game.text), game.meta);
+        viewed.push({ game: game, time: time });
+      }
+    }
+    viewed.sort(function (a, b) {
+      return b.time - a.time || a.game.order - b.game.order;
+    });
+    viewed = viewed.slice(0, RECENT);
+    if (list) {
+      list.textContent = "";
+      for (var j = 0; j < viewed.length; j++) {
+        var entry = viewed[j].game;
+        var item = doc.createElement("li");
+        if (entry.link) {
+          var link = doc.createElement("a");
+          link.setAttribute("href", entry.link.getAttribute("href"));
+          link.textContent = entry.link.textContent;
+          item.appendChild(link);
+        }
+        item.appendChild(makeMark(doc, entry.text));
+        list.appendChild(item);
+      }
+    }
+    if (viewed.length) {
+      addStyle(doc);
+    }
+    section.hidden = viewed.length === 0 || !list;
+  }
+
+  function clearSite(storage, prefix) {
+    var keys = [];
+    try {
+      for (var i = 0; i < storage.length; i++) {
+        var key = storage.key(i);
+        if (typeof key === "string" && key.indexOf(prefix) === 0) {
+          keys.push(key);
+        }
+      }
+      for (var j = 0; j < keys.length; j++) {
+        storage.removeItem(keys[j]);
+      }
+    } catch (error) {
+      // what could be removed was
+    }
+  }
+
+  // Returns what to do when the page is shown again (see start).
+  function startIndex(win, doc, storage, prefix, section) {
+    var games = indexGames(doc);
+    function show() {
+      render(doc, storage, prefix, games, section);
+    }
+    show();
+    var button = doc.getElementById("history-clear");
+    if (button) {
+      button.addEventListener("click", function () {
+        if (typeof win.confirm !== "function" || !win.confirm(CONFIRM)) {
+          return;
+        }
+        clearSite(storage, prefix);
+        show();
+      });
+    }
+    return show;
+  }
+
+  // --- the quiz ---
+
+  function quizEntries(list) {
+    var entries = [];
+    var items = list.getElementsByTagName("li");
+    for (var i = 0; i < items.length; i++) {
+      var id = items[i].getAttribute("data-game");
+      var move = items[i].getAttribute("data-move");
+      if (!id || !GAME.test(id) || !move || !MOVE.test(move)) {
+        continue;
+      }
+      var spans = items[i].getElementsByTagName("span");
+      var meta = null;
+      for (var j = 0; j < spans.length; j++) {
+        if (spans[j].className === "meta" && spans[j].parentNode === items[i]) {
+          meta = spans[j];
+        }
+      }
+      entries.push({ id: id, move: move, item: items[i], meta: meta, mark: null });
+    }
+    return entries;
+  }
+
+  // Marks each question whose answer was revealed; the lines stay where they are.
+  function renderQuiz(doc, storage, prefix, entries) {
+    var marked = 0;
+    for (var i = 0; i < entries.length; i++) {
+      var entry = entries[i];
+      if (entry.mark) {
+        entry.mark.parentNode.removeChild(entry.mark);
+        entry.mark = null;
+      }
+      if (isRevealed(storage, prefix, entry.id, entry.move)) {
+        // on the question's first line, before its date and opponent
+        entry.mark = entry.item.insertBefore(makeMark(doc, "answered"), entry.meta);
+        marked += 1;
+      }
+    }
+    if (marked) {
+      addStyle(doc);
+    }
+  }
+
+  // Returns what to do when the page is shown again (see start).
+  function startQuiz(doc, storage, prefix, list) {
+    var entries = quizEntries(list);
+    function show() {
+      renderQuiz(doc, storage, prefix, entries);
+    }
+    show();
+    return show;
+  }
+
+  function start(win, doc) {
+    var site = doc.documentElement ? doc.documentElement.getAttribute("data-site") : null;
+    if (!site || !SITE.test(site)) {
+      return;
+    }
+    var storage = openStorage(win);
+    if (!storage) {
+      return;
+    }
+    var prefix = PREFIX + site + ":";
+    var again = [];
+    var articles = doc.getElementsByTagName("article");
+    if (articles.length && articles[0].getAttribute("data-game")) {
+      again.push(startArticle(doc, storage, prefix, articles[0]));
+    }
+    var section = doc.getElementById("history");
+    if (section) {
+      again.push(startIndex(win, doc, storage, prefix, section));
+    }
+    var quiz = doc.getElementById("quiz");
+    if (quiz) {
+      again.push(startQuiz(doc, storage, prefix, quiz));
+    }
+    // "Back" to a served page (http, e.g. GitHub Pages) can show it again from the browser's
+    // back/forward cache, as it was left: the script does not run again, and only a "pageshow"
+    // event with "persisted" set says so. Then the article counts as viewed again, and the index
+    // and the quiz show the history as it is stored now.
+    if (typeof win.addEventListener === "function") {
+      win.addEventListener("pageshow", function (event) {
+        if (!event || !event.persisted) {
+          return;
+        }
+        for (var i = 0; i < again.length; i++) {
+          try {
+            if (again[i]) {
+              again[i]();
+            }
+          } catch (error) {
+            // the page as it was left is still complete
+          }
+        }
+      });
+    }
+  }
+
+  try {
+    start(window, document);
+  } catch (error) {
+    // the pages are complete without the history
+  }
+})();