@vernikr/size-report 2.4.0 → 2.6.0

package/src/page/state.js

@@ -1,70 +1,83 @@
-/* Программа страницы отчёта: панель выбора с легендой и таблица.
+import { appDecode } from './payload.js';
+
+/* The page's choice state: what is switched on, how it survives a closing and how it travels as a link.
  *
- * Это обычный исходник, а не строка в движке: его видит линтер, и он же
- * вклеивается в собранную страницу (`pageScript` снимает модульный синтаксис —
- * импорт ниже и объявления с `export` из соседнего файла). Расчёт берётся из
- * производных величин, поэтому включение метрики, категории или файла зовёт тот
- * же расчёт, что считает статическую таблицу, и не может дать других чисел.
+ * An ordinary source file rather than a string inside the engine: a linter sees it, and it is pasted into the assembled
+ * page (`pageScript` strips module syntax — the `import` lines and the `export` keywords of the chapters). The numbers
+ * come from the derived quantities, so switching a metric, a category or a file calls the same calculation the report's
+ * numbers come from and cannot yield different ones.
  *
- * Страница — один файл без внешних ссылок, поэтому здесь нет ни динамического
- * импорта, ни загрузки чего-либо по сети: оформление приходит тем же файлом,
- * а разметка клеток повторяет статическую таблицу (`clip` и подпись коммита —
- * правила общей части оформления).
+ * The page is one file without external references, so there is no dynamic import here and nothing is loaded over the
+ * network: the styling arrives in the same file, and the cell markup follows the rules of the shared part of the styling
+ * (`clip`, a commit's caption).
  *
- * Панель помнит выбор читателя между открытиями и умеет передать его ссылкой
- * («Память выбора» ниже): запись привязана к паспорту отчёта и хранит только
- * выключенное по именам, поэтому чужая запись не применяется, а исчезнувшее имя
- * просто ничего не значит. Та же запись ложится в адрес — его и отправляют коллеге.
+ * The panel remembers the reader's choice between visits and can hand it over as a link ("the choice's memory" below):
+ * the record is tied to the report's passport and keeps only what is switched off, by name, so someone else's record is
+ * not applied while a vanished name simply means nothing. The same record goes into the address — which is what one
+ * sends to a colleague.
  *
- * Точность числа страница не выводит сама: пометки приближённых клеток приходят в
- * данных, от того же правила, по которому названа точность метрики. Из путей и
- * форматов страница такого вывода не делает — второго правила точности не будет. */
-
-/* Импорт — одной строкой: модульный синтаксис снимается при вклейке построчно,
- * и оставшаяся строка `import` попала бы в страницу (её ловит проверка). */
+ * The page draws no conclusion about how a number was obtained: the method of each metric arrives in the data, and the
+ * page prints it. There is no second rule of counting here, and no vocabulary of precision either. */
 
-export const appData = JSON.parse(document.getElementById('data').textContent);
 export const appUi = JSON.parse(document.getElementById('ui').textContent);
-export const appView = { metrics: {}, files: [], folded: {} };
-appData.metrics.forEach((m) => { appView.metrics[m.key] = true; });
-appData.files.forEach(() => { appView.files.push(true); });
 
-/* Описание метрики по ключу: подсказка приближённой клетки называет способ её
- * числа — тот же, что стоит в подписи метрики, поэтому двух ответов про «чем
- * посчитано» у страницы нет. */
-export const appMetric = {};
-appData.metrics.forEach((m) => { appMetric[m.key] = m; });
+/* The model is not a constant any longer: the block in the file is **packed** (gzipped and base64 encoded,
+ * `appUnpack` of the payload chapter), so unpacking is asynchronous and the model is set once, by `appBoot`,
+ * before anything is drawn and before any chapter below reads it. The names, their shapes and their order are what
+ * they were; only their appearance moved — from the parse to that one call. */
+export let appData = null;
+export let appView = null;
+export let appMetric = null;
+export let appMeasured = null;
+let appKey = null;
+let appFoldKey = null;
 
-/* Колонка по пути файла: дерево страницы — дерево проекта (все пути каталога), а
- * числа есть только у колонок, поэтому лист дерева по этому указателю и решает,
- * галочка он или подпись. Имя берётся тем же правилом, что у записи выбора
- * (`appFileAt`), — дерево и память читателя разойтись не могут. */
-export const appMeasured = {};
-appData.files.forEach((_f, i) => { appMeasured[appFileAt(i)] = i; });
+/* One place that turns the unpacked block into what the chapters speak: the sparse form is unrolled by the payload
+ * chapter into the dense contract every number comes from — snapshots per commit, the texts themselves, "now" as
+ * the state at HEAD — and the view starts switched on whole.
+ *
+ * A metric's description by key stands here too: the way the number was obtained is text under the switches, so the
+ * page holds no second answer about "counted with what".
+ *
+ * A column by a file's path is the pointer that decides whether a leaf of the tree is a checkbox or a caption (the
+ * page's tree is the project's tree while the numbers belong to columns only); the name follows the same rule as the
+ * choice's record (`appFileAt`), so the tree and the reader's memory cannot drift apart.
+ *
+ * The key the reader's memory lives under is counted here as well, because it is the report's passport: it depends
+ * on the data, and until the block is unpacked there is nothing to count it from. */
+export function appBoot(text) {
+  appData = appDecode(JSON.parse(text));
+  appView = { metrics: {}, files: [], folded: {} };
+  appMetric = {};
+  appMeasured = {};
+  appData.metrics.forEach((m) => { appView.metrics[m.key] = true; appMetric[m.key] = m; });
+  appData.files.forEach((_f, i) => { appView.files.push(true); appMeasured[appFileAt(i)] = i; });
+  appKey = 'size-report:' + appPassport();
+  appFoldKey = appKey + ':tree';
+}
 
-/* Ссылка — это тот же выбор в адресе, под своим именем: чужой якорь страницы
- * ссылкой не считается, и спорить с ним нечем. */
+/* A link is that same choice in the address, under a name of its own: someone else's anchor on the page does not count
+ * as a link, and there is nothing to argue with it about. */
 const APP_LINK = '#size-report=';
 
-/* Три обстоятельства первой отрисовки, которые действуют только на ней:
- * адрес в ней не переписывается (его прислали читателю, а не наоборот), память
- * не трогается (присланная ссылка — не выбор читателя), а сообщение о ссылке
- * ещё не гаснет. */
+/* Three circumstances of the first drawing, which act on it alone: the address is not rewritten during it (it was sent to
+ * the reader rather than the other way), the memory is not touched (a link that came in is not the reader's choice), and
+ * the message about the link has not faded yet. */
 let appStartup = true;
 let appForeign = false;
 let appTransient = false;
 
-/* -------- память выбора читателя -------- */
+/* -------- the reader's memory of his choice -------- */
 
-/* Имя файла для записи — путь на HEAD, а если файла там уже нет, последний из
- * настроек: по нему файл и опознаётся в отчёте. */
+/* The name of a file for the record is its path at HEAD, or the last of the settings when the file is already gone from
+ * there: that is the name it is recognised by in the report. */
 export function appFileAt(i) {
   const f = appData.files[i];
   return f.path === null ? f.paths[0] : f.path;
 }
 
-/* Отпечаток паспорта: опознавательный знак записи, а не защита от подделки,
- * поэтому 32 бит достаточно (FNV-1a). */
+/* The passport's fingerprint: an identifying mark of a record rather than protection against forgery, so 32 bits are
+ * enough (FNV-1a). */
 function appHash(text) {
   let h = 2166136261;
   for (let i = 0; i < text.length; i++) {
@@ -74,22 +87,27 @@ function appHash(text) {
   return (h >>> 0).toString(16);
 }
 
-/* Паспорт отчёта: имя инструмента, схема данных, путь артефакта, заголовок и метки
- * колонок в порядке отчёта. Он и отделяет один отчёт от другого — по нему выбирается
- * ключ записи, поэтому выбор с чужого отчёта не подхватывается. Версии пакета и
- * верхушки истории в паспорте нет намеренно: это тот же отчёт — обновление
- * инструмента не меняет того, что значит колонка, а подросшая история это та же
- * история, к которой читатель и возвращается. */
+/* The report's passport: the tool's name, the data schema, the artifact's path, the title and the column labels in the
+ * report's order. It is what tells one report from another — the record's key is chosen by it, so a choice made in
+ * someone else's report is not picked up. The package version and the top of the history are absent on purpose: this is
+ * the same report — updating the tool does not change what a column means, while a grown history is the very history the
+ * reader comes back to.
+ *
+ * Counted once per document: it is a constant of the report, which depends on nothing the reader can change, and every
+ * click asks for it (the key of the memory and the passport of the record). A second count would be a second answer
+ * waiting to happen, and the labels it reads do not change while the page is open. */
+let appPassportValue = null;
 function appPassport() {
-  return appHash([appData.tool.name, appData.schema, appData.report.artifact,
-    appData.report.title, appData.files.map((f) => f.label).join('|')].join('\n'));
+  if (appPassportValue === null) {
+    appPassportValue = appHash([appData.tool.name, appData.schema, appData.report.artifact,
+      appData.report.title, appData.files.map((f) => f.label).join('|')].join('\n'));
+  }
+  return appPassportValue;
 }
-const appKey = 'size-report:' + appPassport();
 
-/* Запись выбора — одна на всё: её кладут и в память, и в адрес, поэтому двух
- * форматов одного состояния не бывает. Хранится только выключенное, по именам:
- * «включено» и «записи нет» — одно и то же состояние, поэтому возврат всех галочек
- * убирает запись, а не оставляет след, неотличимый от выбора. */
+/* One record of the choice for everything: it goes both into the memory and into the address, so there are no two formats
+ * of one state. Only what is switched off is kept, by name: "switched on" and "no record" are the same state, which is
+ * why turning every checkbox back on removes the record instead of leaving a trace indistinguishable from a choice. */
 function appRecord() {
   const metrics = {};
   const files = {};
@@ -98,47 +116,73 @@ function appRecord() {
   return { v: 1, passport: appPassport(), metrics: metrics, files: files };
 }
 
-// Своя ли запись и того ли формата — одно правило и для памяти, и для адреса.
+// Whether a record is ours and of the right format — one rule for the memory and the address alike.
 function appRecordOk(rec) {
   return rec !== null && typeof rec === 'object' && rec.v === 1 && rec.passport === appPassport();
 }
 
+/* The address is the link for a colleague, while the memory is the reader's own: the memory is written on the click
+ * itself — that is what survives a closing — and the address 200 ms after the last of a burst of switches, because a
+ * burst is one link rather than five history entries and five URL parses. The delay is short enough for a person and
+ * long enough to swallow a run of clicks; a timer that fires after the page is gone writes nothing useful, which is the
+ * price of not writing the address five times. */
+const APP_ADDRESS_DELAY = 200;
+let appAddressTimer = null;
+
+/* An address that came in from outside wins over a write this page has not made yet: a click arms a write, a link
+ * arrives within the delay, and the choice left behind must not land on the address the reader was sent — a refused link
+ * arms nothing to replace it, so without this the page would rewrite someone else's address a fifth of a second later. */
+export function appAddressDrop() {
+  if (appAddressTimer === null) return;
+  clearTimeout(appAddressTimer);
+  appAddressTimer = null;
+}
+
+function appAddressLater(text) {
+  appAddressDrop();
+  appAddressTimer = setTimeout(() => {
+    appAddressTimer = null;
+    try {
+      window.history.replaceState(null, '', APP_LINK + encodeURIComponent(text));
+    } catch (_e) {
+      /* The browser grants no change of the address: the link is then taken from the browser's memory. */
+    }
+  }, APP_ADDRESS_DELAY);
+}
+
+/* One record for a click and two destinations: the same text goes into the memory and — a moment later — into the
+ * address, so the two cannot describe different choices. */
 export function appWrite() {
   const rec = appRecord();
+  const text = JSON.stringify(rec);
   const empty = Object.keys(rec.metrics).length === 0 && Object.keys(rec.files).length === 0;
   if (!appTransient) {
     try {
       if (empty) window.localStorage.removeItem(appKey);
-      else window.localStorage.setItem(appKey, JSON.stringify(rec));
+      else window.localStorage.setItem(appKey, text);
     } catch (_e) {
-      /* Памяти нет (браузер её не даёт этой странице): выбор не переживёт закрытия,
-       * а числа и разметка от этого не зависят. */
+      /* There is no memory (the browser grants this page none): the choice will not survive a closing, while the numbers
+       * and the markup do not depend on it. */
     }
   }
-  /* Адрес и есть ссылка для коллеги, поэтому он повторяет выбор. Но не на первой
-   * отрисовке и не тогда, когда ссылка оказалась чужой: присланный адрес — не наш,
-   * его читателю ещё читать. */
+  /* But not during the first drawing and not when the link turned out to be someone else's: an address that came in is
+   * not ours, and the reader has yet to read it. */
   if (appStartup || appForeign) return;
-  try {
-    window.history.replaceState(null, '', APP_LINK + encodeURIComponent(JSON.stringify(rec)));
-  } catch (_e) {
-    /* Браузер не даёт менять адрес: ссылку тогда берут из памяти браузера. */
-  }
+  appAddressLater(text);
 }
 
-/* Сброс к «включено всё»: граница между «в отчёте этого больше нет» и
- * «выключено» — это запись, а не отсутствие значения. Ссылка несёт весь выбор
- * отправителя, поэтому применяется на чистом виде, а не поверх чужого. */
+/* A reset to "everything on": the border between "this is no longer in the report" and "switched off" is the record
+ * rather than a missing value. A link carries the sender's whole choice, which is why it is applied to a clean view rather
+ * than on top of someone else's. */
 function appAll() {
   appData.metrics.forEach((m) => { appView.metrics[m.key] = true; });
   appData.files.forEach((_f, i) => { appView.files[i] = true; });
 }
 
-/* Что говорит адрес. Отвечает либо своей записью, либо отказом (`linkForeign` —
- * ссылка другого отчёта, `linkBroken` — прочитать нечего): чужой или испорченный
- * выбор не применяется, но и не молчит — иначе читатель не поймёт, почему он видит
- * не то, что ему прислали. Адрес без имени ссылки не ссылка вовсе: молчание, чтобы
- * не спорить с обычными якорями страницы. */
+/* What the address says. It answers either with a record of ours or with a refusal (`linkForeign` — a link of another
+ * report, `linkBroken` — nothing to read): someone else's or a broken choice is not applied, but it does not stay silent
+ * either — otherwise the reader would not understand why he sees something other than what was sent to him. An address
+ * without the link's name is no link at all: silence, so as not to argue with the page's ordinary anchors. */
 function appLinkRead() {
   const hash = window.location.hash || '';
   if (hash.indexOf(APP_LINK) !== 0) return { rec: null, refused: null };
@@ -160,8 +204,8 @@ function appLinkRead() {
   return { rec: rec, refused: null, extra: appUnknown(rec) };
 }
 
-/* Сколько имён в ссылке этому отчёту неизвестны: о них читателю надо сказать —
- * иначе он будет искать в таблице то, чего в ней и не было. */
+/* How many names in the link are unknown to this report: the reader has to be told about them — otherwise he would look
+ * in the table for something that was never there. */
 function appUnknown(rec) {
   const known = {};
   const metricKeys = {};
@@ -173,19 +217,18 @@ function appUnknown(rec) {
   return n;
 }
 
-/* Сообщение о ссылке гаснет после первого же действия читателя: он его прочитал, а
- * постоянное предупреждение — это шум поверх чисел. */
+/* The message about the link fades after the reader's very first action: he has read it, and a permanent warning is noise
+ * on top of the numbers. */
 export function appNotice(text) {
   const el = document.getElementById('notice');
   el.textContent = text;
   el.hidden = text === '';
 }
 
-/* Что делает с адресом его событие — открытие страницы и перемена якоря на уже
- * открытой (браузер в этом случае документ не перезагружает, а лишь переставляет
- * якорь, поэтому без этого разбора ссылка работала бы только в новой вкладке).
- * Своя ссылка заменяет вид целиком: в ней весь выбор отправителя, а не разница с
- * чужим. Отказ объясняется словами — и не трогает ни вид, ни адрес. */
+/* What its event does with the address — opening the page and an anchor change on an already open one (the browser does
+ * not reload the document then, it only moves the anchor, so without this reading a link would work in a new tab alone).
+ * A link of ours replaces the view whole: it holds the sender's entire choice rather than a difference from someone
+ * else's. A refusal is explained in words — and touches neither the view nor the address. */
 export function appLinkUse() {
   const link = appLinkRead();
   if (link.rec !== null) {
@@ -201,9 +244,8 @@ export function appLinkUse() {
   return 'none';
 }
 
-/* Чтение: только своя запись — своей версии формата и своего паспорта. Запись
- * чужого отчёта лежит под другим ключом, а чужая, устаревшая или испорченная
- * равносильна её отсутствию. */
+/* Reading: only a record of ours — of our format version and our passport. Another report's record lies under another key,
+ * while a foreign, outdated or broken one amounts to its absence. */
 export function appRead() {
   let text = null;
   try {
@@ -221,10 +263,9 @@ export function appRead() {
   return appRecordOk(rec) ? rec : null;
 }
 
-/* Применение — по именам: файл опознаётся путём, метрика ключом. Имени, которого в
- * отчёте нет, ничего не соответствует (колонку перенаправили на другой путь,
- * метрику убрали из настроек), а появившиеся файлы и метрики остаются включёнными —
- * как их видит тот, кто открыл страницу впервые. */
+/* Applying goes by name: a file is recognised by its path, a metric by its key. A name the report does not hold matches
+ * nothing (a column was pointed at another path, a metric was dropped from the settings), while files and metrics that
+ * appeared stay switched on — the way someone opening the page for the first time sees them. */
 export function appApply(rec) {
   const metrics = rec.metrics || {};
   const files = rec.files || {};
@@ -232,15 +273,14 @@ export function appApply(rec) {
   appData.files.forEach((_f, i) => { if (files[appFileAt(i)] === false) appView.files[i] = false; });
 }
 
-/* -------- сложенное дерево -------- */
+/* -------- the folded tree -------- */
 
-/* Сложенные папки — память того же рода, что выбор, но своей записи: она про то,
- * сколько дерева видно, а не про то, какие числа читают. Поэтому в адрес она не
- * идёт: ссылку отправляют ради чисел, а разложенное дерево — дело смотрящего. Как и
- * у выбора, здесь помнится только сложенное (`true`), а имя папки — это путь
- * («src/page»), поэтому исчезнувшее имя просто ничего не значит. */
-const appFoldKey = appKey + ':tree';
 
+/* Folded folders are a memory of the same kind as the choice, but of a record of their own: it is about how much of the
+ * tree is visible rather than about which numbers are read. Hence it does not go into the address: a link is sent for the
+ * sake of the numbers, while an unfolded tree is the onlooker's business. As with the choice, only what is folded is kept
+ * (`true`), and a folder's name is its path ("src/page"), so a vanished name simply means nothing. `appFoldKey` is
+ * set with the rest of the model (`appBoot`), for the reason the key itself is. */
 export function appFoldRead() {
   let text = null;
   try {
@@ -268,7 +308,7 @@ export function appFoldSet(path, folded) {
     if (Object.keys(rec.folded).length === 0) window.localStorage.removeItem(appFoldKey);
     else window.localStorage.setItem(appFoldKey, JSON.stringify(rec));
   } catch (_e) {
-    /* Памяти нет: сложенное не переживёт закрытия страницы, а вид от этого не
-     * зависит — дерево сложено ровно так, как его сложил читатель сейчас. */
+    /* There is no memory: what is folded will not survive a closing, while the view does not depend on it — the tree is
+     * folded exactly the way the reader folded it just now. */
   }
 }