mosaic-headless 1.24.0 → 1.25.0

package/tools/audit_mobile.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Find the RWD defects a sideways-scroll check cannot see.
+
+    python tools/audit_mobile.py --base https://site/ --paths a/,b/         --widths 390,768 --csv data/mobile-audit.csv
+
+"Does the document scroll horizontally" is the floor, not the bar. A page can pass
+it and still be unusable on a phone: type below the legible floor, a grid that
+never collapsed, a control too small to hit, a line of 60 Han characters, two
+things sitting on top of each other.
+"""
+import json
+import sys
+from playwright.sync_api import sync_playwright
+
+AUDIT = r"""() => {
+  const out = [];
+  const vw = document.documentElement.clientWidth;
+  const vis = el => {
+    const r = el.getBoundingClientRect();
+    const s = getComputedStyle(el);
+    return r.width > 0 && r.height > 0 && s.visibility !== 'hidden' &&
+           s.display !== 'none' && parseFloat(s.opacity) > 0.05;
+  };
+  const txt = el => (el.textContent || '').trim();
+  // A slider lays its slides out side by side and clips them on purpose; so does
+  // anything else with overflow hidden. Measuring children against the VIEWPORT
+  // inside such a box reports the mechanism as a defect, 58 times on one page.
+  const clipped = el => {
+    for (let n = el.parentElement; n && n !== document.body; n = n.parentElement) {
+      const s = getComputedStyle(n);
+      if (/hidden|clip|auto|scroll/.test(s.overflow + s.overflowX)) return true;
+    }
+    return false;
+  };
+
+  for (const el of document.querySelectorAll('body *')) {
+    if (!vis(el)) continue;
+    const r = el.getBoundingClientRect();
+    const s = getComputedStyle(el);
+    const id = el.id || (el.className && String(el.className).split(' ')[0]) || el.tagName;
+    const leaf = !el.children.length || [...el.children].every(c => c.nodeType !== 1);
+    const t = txt(el);
+
+    const inClip = clipped(el);
+
+    // 1. anything wider than the viewport
+    if (r.width > vw + 1 && !inClip)
+      out.push(['WIDE', id, Math.round(r.width) + 'px vs viewport ' + vw]);
+
+    // 2. sticking out past either edge
+    if ((r.left < -1 || r.right > vw + 1) && !inClip)
+      out.push(['OUTSIDE', id, 'left=' + Math.round(r.left) + ' right=' + Math.round(r.right)]);
+
+    // 3. type too small to read on a phone
+    const fs = parseFloat(s.fontSize);
+    if (t && leaf && fs && fs < 11)
+      out.push(['TINY_TYPE', id, fs + 'px: ' + t.slice(0, 32)]);
+
+    // 4. a control too small to hit
+    if (/^(A|BUTTON)$/.test(el.tagName) || el.getAttribute('role') === 'button') {
+      if (r.height < 30 || r.width < 30)
+        out.push(['SMALL_TARGET', id,
+                  Math.round(r.width) + 'x' + Math.round(r.height) + ': ' + t.slice(0, 24)]);
+    }
+
+    // 5. content clipped by its own box
+    const ownOverflow = s.overflow + ' ' + s.overflowX;
+    if (el.scrollWidth > el.clientWidth + 2 && !inClip &&
+        !/auto|scroll|hidden|clip/.test(ownOverflow))
+      out.push(['CLIPPED', id, el.scrollWidth + ' > ' + el.clientWidth]);
+
+    // 6. a grid that never collapsed
+    if (s.display === 'grid') {
+      const cols = s.gridTemplateColumns.split(' ').filter(x => x && x !== 'none');
+      if (cols.length > 1 && vw <= 430)
+        out.push(['GRID_NOT_COLLAPSED', id, cols.length + ' columns at ' + vw + 'px']);
+    }
+
+    // 7. a very long measure - Han text past ~40 chars per line reads badly
+    if (t && leaf && fs) {
+      const perLine = r.width / fs;
+      if (perLine > 42 && t.length > 40)
+        out.push(['LONG_MEASURE', id, Math.round(perLine) + ' chars/line']);
+    }
+  }
+  return out;
+}"""
+
+
+def main():
+    import argparse, csv as _csv
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--base", required=True)
+    ap.add_argument("--paths", required=True,
+                    help="comma-separated, relative to --base")
+    ap.add_argument("--widths", default="390,768")
+    ap.add_argument("--csv")
+    ap.add_argument("--ignore", default="",
+                    help="comma-separated KIND or KIND:id to accept as intended")
+    a = ap.parse_args()
+    url_base = a.base
+    slugs = a.paths.split(",")
+    ignore = {x.strip() for x in a.ignore.split(",") if x.strip()}
+    rows = []
+    found = {}
+    widths = [int(x) for x in a.widths.split(",")]
+    with sync_playwright() as pw:
+        b = pw.chromium.launch()
+        for width in widths:
+          for slug in slugs:
+              c = b.new_context(viewport={"width": width, "height": 780},
+                                device_scale_factor=2, is_mobile=True,
+                                has_touch=True)
+              p = c.new_page()
+              p.goto(url_base + slug, wait_until="load")
+              p.wait_for_timeout(2200)
+              p.evaluate("()=>document.querySelectorAll('dialog').forEach(d=>d.open&&d.close())")
+              p.wait_for_timeout(300)
+              agg = {}
+              for kind, who, detail in p.evaluate(AUDIT):
+                  if kind in ignore or ("%s:%s" % (kind, who)) in ignore:
+                      continue
+                  agg.setdefault(kind, []).append((who, detail))
+                  rows.append([slug, str(width), kind, who, detail])
+              found[slug] = agg
+              print("== %s  (%dpx)" % (slug or "/", width))
+              if not agg:
+                  print("   clean")
+              for kind in sorted(agg):
+                  items = agg[kind]
+                  print("   %-20s %d" % (kind, len(items)))
+                  for who, detail in items[:4]:
+                      print("       %-26s %s" % (who[:26], detail[:70]))
+              c.close()
+        b.close()
+    if a.csv:
+        with open(a.csv, "w", newline="", encoding="utf-8") as fh:
+            w = _csv.writer(fh)
+            w.writerow(["path", "width", "finding", "element", "detail"])
+            w.writerows(rows)
+        print("\nwrote %s (%d findings)" % (a.csv, len(rows)))
+    return 1 if rows else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/extract_default_children.py

@@ -20,6 +20,20 @@ server side complains. This table is where that requirement is written down.
 
 The source of truth is the `get<Something>DefaultData()` static on each type factory,
 which is what the editor calls when you insert one of these from the UI.
+
+## The other half: children a type HEALS into itself
+
+A composite can also acquire its parts after the fact. `ModalElementMResource::onHeal()`
+inserts a `modal-overlay` when the author left one out - "a required structural part,
+non-deletable, one per Modal" - and `LoopElementMResource::onHeal()` does the same with
+`loop-items` and `loop-no-result`. Those children never appear in a `getDefaultData()`
+body, so a table built only from the statics above says a `loop` has no default
+children at all, and anything consulting it (the placement guard in `build_page.py`,
+for one) then refuses a correctly-built loop.
+
+So the MResource classes are read too, and a child found inside an `onHeal()` body is
+recorded with `source` = `heal`. The distinction is worth keeping: a declared default
+is what you GET when you insert the type, a healed one is what you CANNOT avoid.
 """
 import csv
 import os
@@ -32,6 +46,13 @@ RE_DEFAULT = re.compile(
 RE_TYPE = re.compile(r'"type"\s*=>\s*"([^"]+)"')
 RE_CHILD_CALL = re.compile(r"(\w+)ElementTypeFactory::get(\w+)DefaultData|(\w+)NodeTypeFactory::get(\w+)DefaultData")
 
+# `protected function onHeal(...) { ... }` - the body is taken to the next
+# method at the same indent, which is how every one of these files is laid out.
+RE_HEAL = re.compile(r"function\s+onHeal\s*\([^)]*\)\s*:\s*void\s*\{(.*?)\n    \}", re.S)
+# the MResource knows its own slug through the factory it names in use statements,
+# so the owning TYPE is taken from the class name instead
+RE_MRESOURCE_CLASS = re.compile(r"class\s+(\w+)ElementMResource\b")
+
 
 def read(path):
     with open(path, encoding="utf-8", errors="replace") as fh:
@@ -76,16 +97,57 @@ def extract(plugin_root, out_dir):
                 "declared_in": os.path.relpath(path, plugin_root).replace(os.sep, "/"),
             })
 
-    rows.sort(key=lambda r: r["type"])
+    # ---- and the ones a type heals into itself
+    stem_by_class = {}
+    for path, src in files:
+        m = re.search(r"class\s+(\w+)ElementTypeFactory", src)
+        if m:
+            stem_by_class[m.group(1)] = stem_to_slug.get(m.group(1), "")
+
+    for dirpath, _dirs, names in os.walk(node_root):
+        for fn in sorted(names):
+            if not fn.endswith("ElementMResource.php"):
+                continue
+            path = os.path.join(dirpath, fn)
+            src = read(path)
+            owner_stem = RE_MRESOURCE_CLASS.search(src)
+            if not owner_stem:
+                continue
+            owner = stem_to_slug.get(owner_stem.group(1))
+            if not owner:
+                continue
+            healed = []
+            for body in RE_HEAL.findall(src):
+                for m in RE_CHILD_CALL.finditer(body):
+                    stem = m.group(1) or m.group(3)
+                    slug = stem_to_slug.get(stem, stem.lower())
+                    if slug != owner and slug not in healed:
+                        healed.append(slug)
+            if healed:
+                rows.append({
+                    "type": owner,
+                    "default_children": "|".join(healed),
+                    "child_count": len(healed),
+                    "source": "heal",
+                    "declared_in": os.path.relpath(path, plugin_root).replace(os.sep, "/"),
+                })
+
+    for r in rows:
+        r.setdefault("source", "default")
+
+    rows.sort(key=lambda r: (r["type"], r["source"]))
     os.makedirs(out_dir, exist_ok=True)
     out = os.path.join(out_dir, "default-children.csv")
     with open(out, "w", newline="", encoding="utf-8") as fh:
-        w = csv.DictWriter(fh, fieldnames=["type", "default_children", "child_count", "declared_in"])
+        w = csv.DictWriter(fh, fieldnames=["type", "default_children", "child_count",
+                                           "source", "declared_in"])
         w.writeheader()
         w.writerows(rows)
-    print("composite types with a declared default structure: %d" % len(rows))
+    print("composite types with a required internal structure: %d (%d declared, "
+          "%d healed in)" % (len(rows), sum(1 for r in rows if r["source"] == "default"),
+                             sum(1 for r in rows if r["source"] == "heal")))
     for r in rows:
-        print("  %-26s -> %s" % (r["type"], r["default_children"]))
+        print("  %-26s %-8s -> %s" % (r["type"], r["source"], r["default_children"]))
 
 
 if __name__ == "__main__":

package/tools/verify_tokens.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""Hold a page's design tokens against what the browser actually computed.
+
+    python tools/verify_tokens.py --url https://site/tokens/ \\
+        --prefix --mk- --csv data/token-verification.csv
+
+A collection variable is the one part of the styling system with a visible failure
+mode that looks like success: a wrong `skinsData` shape still creates the variable,
+still emits the `:root` declaration, and simply serves the sub-factory's default -
+`#FFF` for a colour. The page renders, nothing errors, and the token is white. So
+"the declaration exists" is not the check; "the declaration exists AND something on
+the page resolved to it AND it is not the default" is.
+
+Three things are asserted, each of which has gone wrong at least once:
+
+- every `--` custom property on `:root` is declared exactly ONCE. Changing a
+  variable's value does not retire the old declaration, so duplicates are the
+  signature of an orphan left behind by an earlier build.
+- every property's value is non-empty and is not the bare white default.
+- every element that was authored to reference a token computes to that token's
+  value. This is what separates "the token exists" from "the token is in use" -
+  a page can carry a perfect `:root` and point at none of it.
+"""
+import argparse
+import csv
+import re
+import sys
+
+from playwright.sync_api import sync_playwright
+
+ROOT_VARS = """() => {
+  // Every :root rule in every stylesheet the document actually loaded, in order,
+  // so a property declared twice is visible as two entries rather than collapsing.
+  const out = [];
+  for (const sheet of document.styleSheets) {
+    let rules;
+    try { rules = sheet.cssRules; } catch (e) { continue; }
+    for (const r of rules || []) {
+      if (!r.selectorText || !/(^|,)\\s*:root\\s*($|,)/.test(r.selectorText)) continue;
+      for (const name of r.style) {
+        if (name.startsWith('--')) out.push([name, r.style.getPropertyValue(name).trim()]);
+      }
+    }
+  }
+  return out;
+}"""
+
+USES = """(prefix) => {
+  // Which elements resolve to a token, and to what. getComputedStyle gives the
+  // RESOLVED value, so this is the end of the pipeline, not the authored intent.
+  const cs = getComputedStyle(document.documentElement);
+  const want = {};
+  for (const name of cs) if (name.startsWith(prefix)) want[name] = cs.getPropertyValue(name).trim();
+  const seen = {};
+  for (const el of document.querySelectorAll('[id]')) {
+    const s = getComputedStyle(el);
+    for (const prop of ['color', 'background-color', 'border-top-color']) {
+      const v = s.getPropertyValue(prop).trim();
+      for (const [name, val] of Object.entries(want)) {
+        if (!val) continue;
+        if (norm(v) && norm(v) === norm(val)) (seen[name] = seen[name] || []).push(el.id);
+      }
+    }
+  }
+  function norm(c) {
+    if (!c) return '';
+    const m = c.match(/rgba?\\(([^)]+)\\)/);
+    if (!m) return c.replace(/\\s+/g, '');
+    const p = m[1].split(',').map(x => parseFloat(x));
+    if (p.length === 4 && p[3] === 0) return '';     // transparent matches nothing
+    return p.slice(0, 3).map(Math.round).join(',');
+  }
+  return {declared: want, used: seen};
+}"""
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--url", required=True)
+    ap.add_argument("--prefix", default="--",
+                    help="only tokens whose custom property starts with this are "
+                         "judged; a theme shares :root with WordPress and the "
+                         "block editor, whose variables are not yours")
+    ap.add_argument("--csv")
+    a = ap.parse_args()
+
+    rows, fails = [], []
+
+    def check(name, ok, detail=""):
+        rows.append([name, "PASS" if ok else "FAIL", detail])
+        print("  %-26s %-5s %s" % (name, "PASS" if ok else "FAIL", detail))
+        if not ok:
+            fails.append(name)
+
+    with sync_playwright() as pw:
+        b = pw.chromium.launch()
+        pg = b.new_context(viewport={"width": 1280, "height": 900}).new_page()
+        pg.goto(a.url, wait_until="load")
+        pg.wait_for_timeout(1500)
+
+        declared = [(n, v) for n, v in pg.evaluate(ROOT_VARS)
+                    if n.startswith(a.prefix)]
+        info = pg.evaluate(USES, a.prefix)
+        b.close()
+
+    check("ROOT_PRESENT", bool(declared),
+          "%d custom properties on :root matching %r" % (len(declared), a.prefix))
+
+    counts = {}
+    for n, _v in declared:
+        counts[n] = counts.get(n, 0) + 1
+    dupes = {n: c for n, c in counts.items() if c > 1}
+    check("NO_DUPLICATES", not dupes,
+          "every property declared once" if not dupes
+          else "declared more than once (an earlier value was never retired): %s"
+               % ", ".join("%s x%d" % kv for kv in sorted(dupes.items())))
+
+    blank = [n for n, v in declared if not v]
+    check("NO_EMPTY", not blank,
+          "every token has a value" if not blank else "empty: %s" % ", ".join(blank))
+
+    # #FFF is what a colour variable serves when its skinsData never arrived. It is
+    # a legitimate value too, so this reports rather than fails on its own.
+    whites = [n for n, v in declared
+              if re.sub(r"\s+", "", v).lower() in ("#fff", "#ffffff",
+                                                   "rgb(255,255,255)")]
+    check("NOT_DEFAULT_WHITE", True,
+          "none" if not whites else
+          "white, which is also the value a colour serves when skinsData never "
+          "arrived - confirm these are intended: %s" % ", ".join(whites))
+
+    # Only a COLOUR token can be found by comparing computed colours. A theme's
+    # `:root` also carries numbers that drive animations and lengths - this page's
+    # clock keeps its state in --mk-m/-s/-n - and judging those by colour would
+    # report a permanent, meaningless failure. Split them and say which is which.
+    used = info["used"]
+    is_colour = re.compile(r"^(#[0-9a-fA-F]{3,8}|rgba?\(|hsla?\()")
+    colours = {n: v for n, v in info["declared"].items() if is_colour.match(v)}
+    others = {n: v for n, v in info["declared"].items() if n not in colours}
+
+    unused = [n for n in colours if n not in used]
+    check("ALL_COLOUR_TOKENS_USED", not unused,
+          "all %d colour tokens are resolved by at least one element" % len(colours)
+          if not unused else
+          "declared but nothing on this page resolves to them: %s" % ", ".join(unused))
+    check("NON_COLOUR_TOKENS", True,
+          "none" if not others else
+          "%d not judged by colour (they are numbers or lengths): %s"
+          % (len(others), ", ".join("%s=%s" % (n, v or "''") for n, v
+                                    in sorted(others.items()))))
+
+    for name in sorted(colours):
+        ids = used.get(name, [])
+        check("USED/%s" % name, bool(ids),
+              "%d element(s), e.g. %s" % (len(ids), ", ".join(ids[:3]))
+              if ids else "no element on the page computes to %s" % colours[name])
+
+    print("\n%d of %d checks passed" % (len(rows) - len(fails), len(rows)))
+    if a.csv:
+        with open(a.csv, "w", newline="", encoding="utf-8") as fh:
+            w = csv.writer(fh)
+            w.writerow(["check", "result", "detail"])
+            w.writerows(rows)
+        print("wrote %s" % a.csv)
+    sys.exit(1 if fails else 0)
+
+
+if __name__ == "__main__":
+    main()