sfdx-hardis 8.4.1 → 8.4.2

package/defaults/mkdocs-project-doc/docs/javascripts/gtag.js

@@ -9,19 +9,24 @@ location$.subscribe(function(url) {
     gtag("config", "G-3DM50255LC");
 });
 */
+// Replace the placeholder with your own Google Analytics measurement id to enable tracking.
+// While it is left as it is, no request is sent: a project documentation used to call
+// googletagmanager.com on every page load with an id that does not exist.
 var gtag_id = "G-XXXXXXXXXX";
 
-var script = document.createElement("script");
-script.src = "https://www.googletagmanager.com/gtag/js?id=" + gtag_id;
-document.head.appendChild(script);
+if (gtag_id !== "G-XXXXXXXXXX") {
+  var script = document.createElement("script");
+  script.src = "https://www.googletagmanager.com/gtag/js?id=" + gtag_id;
+  document.head.appendChild(script);
 
-location$.subscribe(function (url) {
-  window.dataLayer = window.dataLayer || [];
+  location$.subscribe(function (url) {
+    window.dataLayer = window.dataLayer || [];
 
-  function gtag() {
-    dataLayer.push(arguments);
-  }
+    function gtag() {
+      dataLayer.push(arguments);
+    }
 
-  gtag("js", new Date());
-  gtag("config", gtag_id);
-});
+    gtag("js", new Date());
+    gtag("config", gtag_id);
+  });
+}

package/defaults/mkdocs-project-doc/docs/javascripts/sfdx-hardis-doc.js

@@ -0,0 +1,103 @@
+/*
+ * Behavior owned by sfdx-hardis. Unlike javascripts/tables.js, which is copied once and then
+ * belongs to the project, this file is rewritten on every documentation generation, so fixes
+ * reach projects that were documented with an older version.
+ */
+
+// A generated table regularly holds hundreds of rows: the Account object of a large org lists
+// close to 500 fields, on a page 40 000 pixels tall. Above this many rows a table gets a filter
+// box, so a reader looks a row up instead of scrolling for it.
+var SFDX_HARDIS_FILTER_FROM_ROWS = 15;
+
+// Labels are written by sfdx-hardis in javascripts/sfdx-hardis-doc-labels.js, in the language the
+// documentation was generated with, and the English wording passed below is the fallback. They are
+// read when a label is drawn rather than when this file is parsed, so the two scripts can be
+// declared in either order in mkdocs.yml.
+function sfdxHardisLabel(key, fallback, values) {
+  var labels = window.SFDX_HARDIS_DOC_LABELS || {};
+  var text = labels[key] || fallback;
+  return text.replace(/\{\{(\w+)\}\}/g, function (match, name) {
+    return Object.prototype.hasOwnProperty.call(values || {}, name) ? values[name] : match;
+  });
+}
+
+function sfdxHardisAddTableFilter(table) {
+  var body = table.tBodies[0];
+  if (!body || body.rows.length < SFDX_HARDIS_FILTER_FROM_ROWS) {
+    return;
+  }
+  // Material wraps a table in a scrolling container: the filter goes above the whole thing
+  var anchor = table.closest(".md-typeset__table") || table;
+  if (anchor.previousElementSibling && anchor.previousElementSibling.classList.contains("sfdx-hardis-filter")) {
+    return;
+  }
+
+  var wrapper = document.createElement("div");
+  wrapper.className = "sfdx-hardis-filter";
+
+  var input = document.createElement("input");
+  input.type = "search";
+  input.className = "sfdx-hardis-filter__input";
+  input.setAttribute("aria-label", sfdxHardisLabel("filterTableRows", "Filter table rows"));
+  input.placeholder = sfdxHardisLabel("filterRowsPlaceholder", "Filter {{count}} rows...", { count: body.rows.length });
+
+  var count = document.createElement("span");
+  count.className = "sfdx-hardis-filter__count";
+
+  wrapper.appendChild(input);
+  wrapper.appendChild(count);
+  anchor.parentNode.insertBefore(wrapper, anchor);
+
+  var rows = Array.prototype.slice.call(body.rows);
+  var haystacks = rows.map(function (row) {
+    return row.textContent.toLowerCase();
+  });
+
+  function apply() {
+    var needle = input.value.trim().toLowerCase();
+    var shown = 0;
+    for (var i = 0; i < rows.length; i++) {
+      var matches = needle === "" || haystacks[i].indexOf(needle) > -1;
+      rows[i].hidden = !matches;
+      if (matches) {
+        shown++;
+      }
+    }
+    count.textContent = needle === ""
+      ? ""
+      : sfdxHardisLabel("filterMatchCount", "{{shown}} of {{total}}", { shown: shown, total: rows.length });
+  }
+
+  input.addEventListener("input", apply);
+  // Escape clears the filter, the way a search field is expected to behave
+  input.addEventListener("keydown", function (event) {
+    if (event.key === "Escape") {
+      input.value = "";
+      apply();
+    }
+  });
+}
+
+// Attribute tables (object, profile, permission set, flow node) are written with an empty header
+// row, because their two columns need no title. The theme still paints it, leaving a colored
+// band above the table, so a header row whose cells are all empty is dropped.
+function sfdxHardisHideEmptyTableHeader(table) {
+  var head = table.tHead;
+  if (!head || head.rows.length !== 1) {
+    return;
+  }
+  var cells = Array.prototype.slice.call(head.rows[0].cells);
+  var hasText = cells.some(function (cell) {
+    return cell.textContent.trim() !== "";
+  });
+  if (!hasText) {
+    head.hidden = true;
+  }
+}
+
+document$.subscribe(function () {
+  document.querySelectorAll("article table").forEach(function (table) {
+    sfdxHardisHideEmptyTableHeader(table);
+    sfdxHardisAddTableFilter(table);
+  });
+});

package/defaults/mkdocs-project-doc/docs/stylesheets/sfdx-hardis-doc.css

@@ -0,0 +1,204 @@
+/* stylelint-disable SelectorFormat */
+
+/*
+ * Styling owned by sfdx-hardis. Unlike stylesheets/extra.css, which is copied once and then
+ * belongs to the project, this file is rewritten on every documentation generation, so fixes
+ * reach projects that were documented with an older version. Put project customizations in
+ * stylesheets/extra.css instead: it is loaded first, and this file only overrides what it names.
+ */
+
+/*
+ * The header and the footer are painted navy, but the theme styles them as light strips and
+ * leaves their text on the default near-black foreground. The site title, the repository link,
+ * the version and star counters, the previous/next navigation and the copyright line all came
+ * out at a contrast ratio of 1.12:1, where readable text needs 4.5:1. Background and foreground
+ * are set together here so the two can no longer drift apart.
+ */
+.md-header,
+.md-footer {
+  --md-default-fg-color: rgb(255 255 255 / 90%);
+  --md-default-fg-color--light: rgb(255 255 255 / 70%);
+  --md-default-fg-color--lighter: rgb(255 255 255 / 50%);
+  --md-default-fg-color--lightest: rgb(255 255 255 / 10%);
+  --md-primary-bg-color: #ffffff;
+  --md-primary-bg-color--light: rgb(255 255 255 / 70%);
+  --md-footer-fg-color: #ffffff;
+  --md-footer-fg-color--light: rgb(255 255 255 / 70%);
+  --md-footer-fg-color--lighter: rgb(255 255 255 / 50%);
+  --md-typeset-a-color: #ffffff;
+
+  color: rgb(255 255 255 / 90%);
+  background-color: #001135;
+}
+
+.md-header a,
+.md-header button,
+.md-footer a,
+.md-footer button {
+  color: inherit;
+}
+
+/*
+ * An object page carries a relationship diagram that mermaid lays out as wide as it needs to.
+ * Left alone it either overflows the page or is squeezed to an unreadable size, so it scrolls
+ * inside its own box.
+ */
+.md-typeset .mermaid {
+  overflow-x: auto;
+}
+
+/*
+ * The permission tree of a profile or a permission set gets a search field, created without any
+ * styling: on a white page it was an invisible box with only its placeholder showing. It is given
+ * the same treatment as the table filter below.
+ */
+#jstree-search,
+.sfdx-hardis-filter__input {
+  max-width: 22rem;
+  padding: 0.35rem 0.6rem;
+  font-size: 0.7rem;
+  color: var(--md-default-fg-color);
+  background-color: var(--md-default-bg-color);
+  border: 0.05rem solid var(--md-default-fg-color--lighter);
+  border-radius: 0.2rem;
+}
+
+#jstree-search {
+  width: 100%;
+}
+
+#jstree-search:focus,
+.sfdx-hardis-filter__input:focus {
+  border-color: var(--md-accent-fg-color);
+  outline: none;
+}
+
+/* Filter box that javascripts/sfdx-hardis-doc.js puts above every long table */
+.sfdx-hardis-filter {
+  display: flex;
+  gap: 0.6rem;
+  align-items: center;
+  margin: 0.8em 0 0.4em;
+}
+
+.sfdx-hardis-filter__input {
+  flex: 1 1 auto;
+}
+
+.sfdx-hardis-filter__count {
+  font-size: 0.65rem;
+  color: var(--md-default-fg-color--light);
+}
+
+/*
+ * Home page. The list of sections used to be a bullet list of bare links under a full-width
+ * banner; it is now a grid of cards, each naming what its section holds and how many pages are
+ * behind it. The grid reflows down to one column on a phone.
+ */
+.sfdx-hardis-home-cards {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(15rem, 1fr));
+  gap: 0.7rem;
+  /* Each card is only as tall as what it holds, instead of stretching to the tallest of its row */
+  align-items: start;
+  margin: 1.2em 0;
+}
+
+.sfdx-hardis-home-card {
+  display: flex;
+  flex-direction: column;
+  padding: 0.8rem 0.9rem;
+  border: 0.05rem solid var(--md-default-fg-color--lightest);
+  border-radius: 0.3rem;
+  transition: border-color 125ms, box-shadow 125ms;
+}
+
+.sfdx-hardis-home-card:hover {
+  border-color: var(--md-accent-fg-color);
+  box-shadow: 0 0.1rem 0.4rem rgb(0 0 0 / 8%);
+}
+
+.md-typeset .sfdx-hardis-home-card p {
+  margin: 0 0 0.5em;
+  font-size: 0.7rem;
+  color: var(--md-default-fg-color--light);
+}
+
+.md-typeset .sfdx-hardis-home-card p:last-child {
+  margin-bottom: 0;
+}
+
+.md-typeset .sfdx-hardis-home-card__title {
+  font-size: 0.8rem;
+  font-weight: 700;
+  color: var(--md-default-fg-color);
+  text-decoration: none;
+}
+
+.md-typeset .sfdx-hardis-home-card__title:hover {
+  color: var(--md-accent-fg-color);
+}
+
+.sfdx-hardis-home-card__count {
+  padding: 0.05rem 0.35rem;
+  margin-left: 0.3rem;
+  font-size: 0.62rem;
+  font-weight: 700;
+  color: var(--md-default-fg-color--light);
+  vertical-align: 0.1rem;
+  background-color: var(--md-default-fg-color--lightest);
+  border-radius: 0.6rem;
+}
+
+/* Sections that group several pages list them as chips at the bottom of their card */
+.sfdx-hardis-home-card__links {
+  margin-top: auto;
+}
+
+.md-typeset .sfdx-hardis-home-card__links p {
+  margin: 0;
+  line-height: 1.9;
+}
+
+.md-typeset .sfdx-hardis-home-card__links a {
+  padding: 0.1rem 0.4rem;
+  text-decoration: none;
+  font-size: 0.65rem;
+  color: var(--md-default-fg-color);
+  white-space: nowrap;
+  background-color: var(--md-default-fg-color--lightest);
+  border-radius: 0.2rem;
+}
+
+.md-typeset .sfdx-hardis-home-card__links a:hover {
+  color: var(--md-primary-bg-color);
+  background-color: var(--md-accent-fg-color);
+}
+
+/*
+ * Generated tables are full of long unbreakable names: an API name, a rule name, a class name.
+ * Kept whole they pushed the table past the width of the page, and the last column of the
+ * validation rules of Account was cut off with only a hidden scrollbar to reach it. Cells may
+ * now break a name anywhere, which is what lets the table fit.
+ */
+.md-typeset table td,
+.md-typeset table th {
+  overflow-wrap: anywhere;
+}
+
+/* The first column names the thing the row is about, so it keeps enough room to stay readable */
+.md-typeset table td:first-child,
+.md-typeset table th:first-child {
+  min-width: 8rem;
+}
+
+/*
+ * A validation rule formula is shown as code, and is the exception: allowed to break anywhere its
+ * column collapsed to a few characters and every rule became a tower of two-word lines. It wraps
+ * at the spaces the formula already holds, and only splits a call that is too long to fit.
+ */
+.md-typeset table code {
+  white-space: normal;
+  overflow-wrap: break-word;
+  word-break: normal;
+}

package/defaults/mkdocs-project-doc/mkdocs.yml

@@ -1,6 +1,6 @@
 site_name: Salesforce Project Documentation
 site_url: https://sfdx-hardis.cloudity.com
-repo_url: https://github.com/hardisgroupco/sfdx-hardis
+repo_url: https://github.com/hardisgroupcom/sfdx-hardis
 edit_uri: tree/master/docs
 site_author: Nicolas Vuillamy
 site_description: Salesforce project documentation generated by sfdx-hardis
@@ -15,6 +15,16 @@ theme:
   features:
     - navigation.instant
     - navigation.footer
+    # A project documentation holds thousands of pages, and every one of them used to embed the
+    # whole menu: 900 KB of navigation markup around 30 KB of content. Pruning it to the branch
+    # being read is what keeps the site usable.
+    - navigation.prune
+    - navigation.path
+    - navigation.top
+    - navigation.tracking
+    - toc.follow
+    - search.highlight
+    - content.code.copy
   palette:
     - scheme: default
       primary: custom
@@ -58,6 +68,8 @@ markdown_extensions:
       restrict_base_path: false
   - mdx_truly_sane_lists
   - attr_list
+  # The home page section cards are markdown written inside div elements
+  - md_in_html
   - pymdownx.superfences:
       custom_fences:
         - name: mermaid
@@ -72,9 +84,16 @@ extra_javascript:
   - javascripts/tables.js
   - javascripts/gtag.js
   - javascripts/jstree-handler.js
+  # Rewritten by sfdx-hardis on every run: put project behavior in javascripts/tables.js
+  - javascripts/sfdx-hardis-doc-labels.js
+  - javascripts/sfdx-hardis-doc.js
 extra_css:
   - stylesheets/extra.css
   - https://cdnjs.cloudflare.com/ajax/libs/jstree/3.3.12/themes/default/style.min.css
+  - https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/css/all.min.css
+  - stylesheets/jstree-custom.css
+  # Loaded last so it overrides the project stylesheet: sfdx-hardis rewrites it on every run
+  - stylesheets/sfdx-hardis-doc.css
 extra:
   social:
     - icon: fontawesome/regular/circle-question

package/lib/commands/hardis/doc/project2markdown.d.ts

@@ -12,7 +12,6 @@ export default class Project2Markdown extends SfCommand<any> {
     protected packageXmlCandidates: any[];
     protected outputMarkdownRoot: string;
     protected outputMarkdownIndexFile: string;
-    protected mdLines: string[];
     protected sfdxHardisConfig: any;
     protected outputPackageXmlMarkdownFiles: any[];
     protected mkDocsNavNodes: any[];
@@ -77,6 +76,26 @@ export default class Project2Markdown extends SfCommand<any> {
     private generateLinksInfo;
     private generateFlowsDocumentation;
     private humanDisplay;
+    /**
+     * The home page is the first thing a reader lands on, and for most of them it is the only map of
+     * the org they will ever get. It used to be a bare bullet list under a full-width banner, naming
+     * sections without saying what any of them held. It is now a grid of cards: one per section, with
+     * a sentence of plain language and the number of pages behind it, so someone who does not know
+     * Salesforce can still tell where to click.
+     *
+     * A section is only drawn when the project has one: a project without Lightning Pages, escalation
+     * rules or installed packages used to get links to pages that were never written.
+     */
+    /**
+     * DO_NOT_OVERWRITE_INDEX_MD exists so a project can write its own home page. Setting it used to
+     * freeze the page for good: a project that set the variable and never touched index.md kept the
+     * home page of the sfdx-hardis version that generated it, and no later improvement ever reached
+     * it. A page that is still, to the character, what a previous run wrote is therefore refreshed.
+     * The first edit to it, however small, hands the page over to the project for good.
+     */
+    private canWriteHomePage;
+    private buildHomeLines;
+    private isDocumentedSection;
     private buildSfdxHardisParams;
     private buildMajorBranchesAndOrgs;
     private manageLocalPackages;