@casomoltd/tooling 0.33.2 → 0.34.1

package/buttondown/colophon.mjs

@@ -0,0 +1,80 @@
+/**
+ * A site's colophon as Buttondown `socials` links, for a footer that
+ * says what the site's footer says. Buttondown draws `socials` only as
+ * links, and caps each label (docs/buttondown-platform.md, The API), so
+ * a colophon line arrives as several links that a skin sets as one line
+ * of text.
+ */
+
+/** Buttondown's limit on a `socials` label, and the only `socials` type
+ *  that carries a label of our own. */
+export const SOCIALS_LABEL_MAX = 32;
+const GENERIC = "generic";
+
+/** The query a skin keys on, and its parts: `<line>-<part>`. */
+const MARK = "colophon";
+const START = "start";
+const RUN = "run";
+const NUMBER = "num";
+
+/**
+ * The links for each colophon line: its text in runs that fit a label,
+ * then, for a line with a register, the register's number with the full
+ * stop (one label, so the stop can't wrap away from it); a line with a
+ * source gets the full stop on its text instead. A line is `{text,
+ * register: {number, url}}` or `{text, source}`, its text written
+ * without the closing full stop; every run links to the register, or to
+ * the source where a line without one is explained or published.
+ *
+ * Each URL carries a `colophon` query, `<line>-<part>`: `start` begins a
+ * line, `num` is the number, and `run<n>` the rest of the line's text. A
+ * query rather than a fragment, so a link to a section keeps its anchor.
+ */
+export function colophonLinks(colophon) {
+  return colophon.flatMap((entry, line) => {
+    const {text, register, source} = entry;
+    if (text.endsWith(".")) {
+      throw new Error(`colophon line "${text}": leave off the full stop`);
+    }
+    if (register && !(register.url && register.number)) {
+      throw new Error(`colophon line "${text}": register needs url and number`);
+    }
+    const url = register ? register.url : source;
+    if (!url) throw new Error(`colophon line "${text}" links nowhere`);
+    const at = (part) => {
+      const marked = new URL(url);
+      if (!["http:", "https:"].includes(marked.protocol)) {
+        throw new Error(`colophon line "${text}": ${url} isn't http(s)`);
+      }
+      marked.searchParams.set(MARK, `${line}-${part}`);
+      return marked.href;
+    };
+    const runs = labelRuns(register ? text : `${text}.`);
+    return [
+      ...runs.map((label, i) => ({
+        type: GENERIC, url: at(i === 0 ? START : `${RUN}${i}`), label,
+      })),
+      ...(register
+        ? [{type: GENERIC, url: at(NUMBER), label: `${register.number}.`}]
+        : []),
+    ];
+  });
+}
+
+/** `text` split at spaces into runs of at most SOCIALS_LABEL_MAX
+ *  characters; throws on a word longer than that, which no run holds. */
+export function labelRuns(text) {
+  const out = [];
+  for (const word of text.split(" ")) {
+    const last = out.at(-1);
+    if (last && `${last} ${word}`.length <= SOCIALS_LABEL_MAX) {
+      out[out.length - 1] = `${last} ${word}`;
+    } else {
+      if (word.length > SOCIALS_LABEL_MAX) {
+        throw new Error(`no socials label fits "${word}"`);
+      }
+      out.push(word);
+    }
+  }
+  return out;
+}

package/buttondown/engine.mjs

@@ -47,6 +47,8 @@ export const END = "/* END TOKENS */";
 export const EMAIL_CHROME_HIDES = {
   ".social-links": "the web footer's links, duplicated in an email",
   ".newsletter-masthead": "replaced by the repo's own header band",
+  ".transactional-email-header":
+    "the icon, subject and name above a transactional email's own bands",
   ".newsletter-icon": "the icon slot above the repo's own mark",
   ".email-preamble": "the forwarding prompt between title and prose",
   ".colophon": "the sender-and-date line under the hidden masthead",

package/buttondown/index.d.mts

@@ -123,3 +123,29 @@ export function composeWebSkin(site: string): string;
 
 /** The shared email rules, in the site's theme, with literal values. */
 export function emailBaseCss(theme: EmailTheme): string;
+
+/** The register that proves a colophon line, by its number. */
+export interface Register {
+  readonly number: string;
+  readonly url: string;
+}
+
+/** One colophon line, its text without the closing full stop: then the
+ *  register that proves it, or the http(s) source where a line without
+ *  one is explained or published. */
+export type ColophonLine =
+  | {readonly text: string; readonly register: Register; readonly source?: never}
+  | {readonly text: string; readonly source: string; readonly register?: never};
+
+/** A labelled Buttondown `socials` entry. */
+export interface ColophonLink {
+  type: "generic";
+  url: string;
+  label: string;
+}
+
+/** A colophon as `socials` links, each URL marked with a `colophon`
+ *  query (`<line>-start|run<n>|num`) for a skin to key on. */
+export function colophonLinks(
+  colophon: readonly ColophonLine[],
+): ColophonLink[];

package/buttondown/index.mjs

@@ -5,5 +5,6 @@
 export {
   buildPayload, EMAIL_CHROME_HIDES, loadSettings, tokenReader,
 } from "./engine.mjs";
+export {colophonLinks} from "./colophon.mjs";
 export {createEmailBlocks, TABLE} from "./email-blocks.mjs";
 export {composeWebSkin, emailBaseCss} from "./skins.mjs";

package/package.json

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