@casomoltd/tooling 0.34.1 → 0.35.0

package/README.md

@@ -15,7 +15,7 @@ Shared linting, formatting, commit config, and CLI tools for Casomo Ltd's repos.
 | `@casomoltd/tooling/knip` | Knip config for unused exports/dependencies |
 | `@casomoltd/tooling/jscpd` | Copy-paste detection config |
 | `@casomoltd/tooling/readability` | `scoreText()` — readability scoring for page content |
-| `@casomoltd/tooling/buttondown` | For a repo using the `buttondown` command: the shared email blocks and skins (`createEmailBlocks`, `emailBaseCss`, `composeWebSkin`), `tokenReader()`, `loadSettings()` and `buildPayload()`, and `EMAIL_CHROME_HIDES` ([docs/buttondown.md](docs/buttondown.md)) |
+| `@casomoltd/tooling/buttondown` | For a repo using the `buttondown` command: the shared email blocks and skins (`createEmailBlocks`, `emailBaseCss`, `composeWebSkin`), `tokenReader()`, `loadSettings()` and `buildPayload()`, and `EMAIL_CHROME_HIDES` and `WEB_CHROME_HIDES` ([docs/buttondown.md](docs/buttondown.md)) |
 
 ### Bin commands
 

package/buttondown/engine.mjs

@@ -6,7 +6,8 @@
  *
  * A repo configures it under `buttondown` in its `casomo.config.mjs`:
  *
- *   import {EMAIL_CHROME_HIDES} from "@casomoltd/tooling/buttondown";
+ *   import {EMAIL_CHROME_HIDES, WEB_CHROME_HIDES}
+ *     from "@casomoltd/tooling/buttondown";
  *
  *   export default {
  *     buttondown: {
@@ -16,7 +17,9 @@
  *       tokens: [["--color-accent", "--color-brand-accent"]], // target, source
  *       extra: [["--radius", "0"]],           // uncommented lines after them
  *       asserts: {"--radius-lg": "0"},        // tokens the skins depend on
- *       allowedHides: {...EMAIL_CHROME_HIDES, ".selector": "why"},
+ *       allowedHides: {...EMAIL_CHROME_HIDES, ...WEB_CHROME_HIDES, // the
+ *         second for a repo that composes its web skin
+ *         ".selector": "why"},
  *       linkClasses: {onDark: "on-dark"},     // each needs an `a.<class>` rule
  *       ownLinks: ["/rss"],                   // hrefs that are not socials
  *       paletteFiles: ["buttondown/assets/icon.svg"],
@@ -24,7 +27,8 @@
  *     },
  *   };
  *
- * `newsletter.json` holds the newsletter's short fields, `tags.json` its
+ * `newsletter.json` holds the newsletter's short fields (its `image` is
+ * also every draft's default share image), `tags.json` its
  * tags, and each file in `fields/` is the field it is named after: a
  * stylesheet is read verbatim, and an `.mjs` file's default export is the
  * field's value.
@@ -56,6 +60,25 @@ export const EMAIL_CHROME_HIDES = {
   ".powered-by-icon": "the logo tile above the kept attribution line",
 };
 
+/**
+ * Buttondown's controls on the hosted pages that send a reader somewhere
+ * worse than the site does. `composeWebSkin` hides them, so a repo that
+ * composes its web skin spreads this into `allowedHides`, as it does
+ * EMAIL_CHROME_HIDES. The manage-link hide assumes the archive is on a
+ * custom domain, where that link's buttondown.com address asks a signed-in
+ * reader to sign in again; on buttondown.com it is their only manage link.
+ */
+export const WEB_CHROME_HIDES = {
+  "a.sniper-link-button":
+    "a button to the reader's mail provider, in the form's place and in the"
+    + " sign-up dialog; their inbox is theirs to go to",
+  [".subscribe:has(span.confirmation-email-message)"
+    + " #subscribe-form a.archive__button"]:
+    "a signed-in reader's manage link, which goes to buttondown.com and asks"
+    + " them to sign in again; the header's Account link opens the same"
+    + " settings on the site's domain",
+};
+
 const API = "https://api.buttondown.com/v1";
 
 /** The API's own path prefix, which every request path sits under. */
@@ -158,15 +181,7 @@ export async function tokenReader(file) {
 
 /** Every field the newsletter is set to: newsletter.json, then fields/. */
 export async function buildPayload(settings) {
-  const payload = JSON.parse(
-    await readFile(path.join(settings.dir, "newsletter.json"), "utf8"),
-  );
-  for (const field of IMAGE_FIELDS) {
-    if (payload[field] && !URL.canParse(payload[field])) {
-      throw new Error(`${field} must be an absolute URL, got `
-        + JSON.stringify(payload[field]));
-    }
-  }
+  const payload = await readNewsletter(settings);
   const identity = IDENTITY.filter((key) => key in payload);
   if (identity.length) {
     throw new Error(
@@ -548,7 +563,8 @@ export async function apply(settings, api, log = console.log) {
  * A draft from a markdown file whose first line, after any front matter,
  * is `# Subject`. Front matter carries the email's id once it exists, so a
  * re-run replaces that draft rather than creating a second; `slug` and
- * `description` are passed through. An email already sent is refused:
+ * `description` are passed through, and `image` (the share image) defaults
+ * to the newsletter's own. An email already sent is refused:
  * replacing it would rewrite the published archive.
  */
 export async function draft(settings, api, file, log = console.log) {
@@ -569,6 +585,10 @@ export async function draft(settings, api, file, log = console.log) {
     throw new Error("front matter has an empty `id:`; delete the line to "
       + "create a draft");
   }
+  if ("image" in fm && !fm.image) {
+    throw new Error("front matter has an empty `image:`; delete the line "
+      + "to use the newsletter's share image");
+  }
   // The marker says the body is markdown (Buttondown's `plaintext` mode).
   // Without it Buttondown guesses, and a draft once stored as rich text
   // takes the next PATCH as rich text too.
@@ -579,6 +599,15 @@ export async function draft(settings, api, file, log = console.log) {
     ...Object.fromEntries(["slug", "description"]
       .filter((k) => k in fm).map((k) => [k, fm[k]])),
   };
+  // Left unset, Buttondown takes the post's first picture as its share
+  // image, so every post would preview differently; the newsletter's own
+  // share image is the default, and `image:` in the front matter wins.
+  const image = "image" in fm
+    ? fm.image : (await readNewsletter(settings)).image;
+  if (image) {
+    assertAbsoluteUrl("image", image);
+    body.image = image;
+  }
   if (fm.id) {
     const current = await api.call("GET", `/emails/${fm.id}`);
     if (!current.ok) throw new Error(`GET email: ${detail(current)}`);
@@ -664,6 +693,30 @@ export function stripComments(text) {
   }
 }
 
+/** Throws unless an image field holds an absolute URL, since Buttondown
+ *  stores a relative one as given and the image then never loads. */
+function assertAbsoluteUrl(field, value) {
+  if (!URL.canParse(value)) {
+    throw new Error(`${field} must be an absolute URL, got `
+      + JSON.stringify(value));
+  }
+}
+
+/** newsletter.json, parsed and with its image fields checked. */
+async function readNewsletter(settings) {
+  const file = path.join(settings.dir, "newsletter.json");
+  let payload;
+  try {
+    payload = JSON.parse(await readFile(file, "utf8"));
+  } catch (error) {
+    throw new Error(`${file}: ${error.message}`, {cause: error});
+  }
+  for (const field of IMAGE_FIELDS) {
+    if (payload[field]) assertAbsoluteUrl(field, payload[field]);
+  }
+  return payload;
+}
+
 /** Why a call failed: Buttondown's `detail`, else its whole body, which
  *  names the fields it refused, else the status. */
 function detail(res) {

package/buttondown/index.d.mts

@@ -59,6 +59,10 @@ export type Check = (context: CheckContext) => Promise<string[]>;
  *  bands: spread into `allowedHides` to allow hiding it. */
 export const EMAIL_CHROME_HIDES: Readonly<Record<string, string>>;
 
+/** Hosted-page controls the composed web skin hides; spread into
+ *  `allowedHides` by a repo that uses `composeWebSkin`. */
+export const WEB_CHROME_HIDES: Readonly<Record<string, string>>;
+
 export function loadSettings(root?: string): Promise<Settings>;
 
 export function buildPayload(settings: Settings): Promise<Payload>;

package/buttondown/index.mjs

@@ -4,6 +4,7 @@
  */
 export {
   buildPayload, EMAIL_CHROME_HIDES, loadSettings, tokenReader,
+  WEB_CHROME_HIDES,
 } from "./engine.mjs";
 export {colophonLinks} from "./colophon.mjs";
 export {createEmailBlocks, TABLE} from "./email-blocks.mjs";

package/buttondown/skins.mjs

@@ -6,7 +6,7 @@ import {readFileSync} from "node:fs";
 import {
   BODY_SIZE, PARAGRAPH_MARGIN, requireTheme,
 } from "./email-blocks.mjs";
-import {EMAIL_CHROME_HIDES, preludeEnd} from "./engine.mjs";
+import {EMAIL_CHROME_HIDES, preludeEnd, WEB_CHROME_HIDES} from "./engine.mjs";
 
 /** The shared web rules: base-web.css, which reads every value from the
  *  variables the site's TOKENS block defines. */
@@ -14,6 +14,12 @@ const WEB_BASE = readFileSync(
   new URL("./base-web.css", import.meta.url), "utf8",
 );
 
+/** WEB_CHROME_HIDES as rules. Important, so a site's own rules for the
+ *  same elements can't show them unless those are important too. */
+const WEB_HIDES = Object.keys(WEB_CHROME_HIDES)
+  .map((selector) => `${selector} { display: none !important; }`)
+  .join("\n");
+
 /**
  * The web skin: the site's stylesheet with the shared rules inserted after
  * its opening comments and `@import`s, which must come before any rule,
@@ -22,7 +28,8 @@ const WEB_BASE = readFileSync(
 export function composeWebSkin(site) {
   const at = preludeEnd(site);
   const head = site.slice(0, at);
-  return `${head}${head ? "\n\n" : ""}${WEB_BASE}\n${site.slice(at)}`;
+  return `${head}${head ? "\n\n" : ""}${WEB_BASE}\n${WEB_HIDES}\n`
+    + site.slice(at);
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@casomoltd/tooling",
-  "version": "0.34.1",
+  "version": "0.35.0",
   "description": "Casomo's shared dev config: ESLint, Prettier, commitlint, knip & jscpd presets and dev CLIs (git hooks, readability, screenshots, design specs)",
   "license": "MIT",
   "repository": {