Unify handling of component title

Author: essential-randomness

.changeset/sharp-titles-codespans.md

@@ -0,0 +1,13 @@
+---
+"@fujocoded/remark-capitalize-titles": patch
+---
+
+Export `capitalizeTitle` for title-casing a standalone string outside a Markdown
+tree: pass the title, an optional `{ special }` override, and have your Markdown
+string capitalized while preserving inline code, emphasis, and escapes.
+
+Component `title` props now run through this same Markdown path, so inline
+code spans inside a title keep their exact casing instead of being lowercased.
+
+Also extends the default capitalization list with `JavaScript`, `HTML`, and
+`CSS`.

remark-capitalize-titles/LICENSE

@@ -19,3 +19,31 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+---
+
+This software includes portions derived from the following MIT-licensed
+projects. Their copyright notices are reproduced here as required by the MIT
+License:
+
+vercel/title (https://github.com/vercel/title)
+
+  Copyright (c) 2022 Vercel, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

remark-capitalize-titles/README.md

@@ -47,13 +47,9 @@ capitalizeTitle("merging with github via npm");
 // => "Merging with GitHub via NPM"
 
 // Override the capitalization exceptions:
-capitalizeTitle("my title", { special: ["MyBrand"] });
+capitalizeTitle("my title", { special: ["MyPersonalNitpick"] });
 ```
 
-The default exception list is exported as `DEFAULT_CAPITALIZATIONS`.
-
-### TODOs:
-
-- [ ] Fix issue where a title in a heading that has a previous sibling will be capitalized as if the first
-      word was the beginning of the sentence
-- [ ] Something like "`head`ing" in titles where the word is compounded with a code thing will capitalize "ing".
+The default exception list is exported as `DEFAULT_CAPITALIZATIONS`, and
+overridden if special is passed as a parameter. If the change is meant to be
+additive, then import `DEFAULT_CAPITALIZATIONS` and extend it instead.

remark-capitalize-titles/index.ts

@@ -1,35 +1,46 @@
 import { visit } from "unist-util-visit";
+import { fromMarkdown } from "mdast-util-from-markdown";
 import type { Plugin } from "unified";
 
 import type mdast from "mdast";
 import type { MdxJsxFlowElement } from "mdast-util-mdx-jsx";
 
 import { DEFAULT_CAPITALIZATIONS } from "./capitalizations.ts";
-import { titleCase } from "./title-case.ts";
+import { collectTitleItemsFromChildren, titleCase } from "./title-case.ts";
 
-// Matches a Markdown inline code span (backtick-wrapped) so titles can be
-// split around code spans and left untouched.
-const CODE_REGEX = /(`[a-z0-9_\-\s]+`)/gi;
-
-// Title-case a standalone string (treated as a whole title), leaving inline
-// code spans untouched. The plugin uses this for frontmatter and component
-// title props; it's exported for callers who want title-casing outside a
-// Markdown tree.
+// Title-case a standalone string (treated as a whole markdown title), handling
+// inline code spans, emphasis, escapes, etc. The plugin uses this for
+// frontmatter and component title props; it's exported for callers who want
+// title-casing outside a remark plugin.
 export const capitalizeTitle = (
   title: string,
   { special = DEFAULT_CAPITALIZATIONS }: { special?: string[] } = {},
 ): string => {
-  const parts = title.split(new RegExp(CODE_REGEX));
-  return parts
-    .map((part, idx) => {
-      if (part.startsWith("`") && part.endsWith("`")) return part;
-      return titleCase(part, {
-        special,
-        isFirstTextNode: idx === 0,
-        isLastTextNode: idx === parts.length - 1,
-      });
-    })
-    .join("");
+  const tree = fromMarkdown(title);
+  const items = collectTitleItemsFromChildren(tree.children);
+
+  // Re-case the original source bytes (via each text node's position offsets),
+  // NOT node.value: value is unescaped (`a \* b` => `a * b`) while its position
+  // spans the *escaped* source, so splicing value back would drop escapes and
+  // shift later offsets. Since titleCase only flips letters and copies all other
+  // characters through, escapes, `_`/`*` delimiters, and exact spacing survives.
+  let result = "";
+  let cursor = 0;
+  items.forEach((item, i) => {
+    if (item.type !== "text") return;
+    const start = item.node.position!.start.offset!;
+    const end = item.node.position!.end.offset!;
+    result += title.slice(cursor, start);
+    result += titleCase(title.slice(start, end), {
+      special,
+      isFirstTextNode: i === 0,
+      isLastTextNode: i === items.length - 1,
+      firstWordIsContinuation: item.firstWordIsContinuation,
+    });
+    cursor = end;
+  });
+  result += title.slice(cursor);
+  return result;
 };
 
 type AstroFrontmatterData = {
@@ -49,7 +60,7 @@ const plugin: Plugin<[PluginOptions?], mdast.Root> =
     special = DEFAULT_CAPITALIZATIONS,
     componentNames = [],
     frontmatterTitle = true,
-  }: PluginOptions = {}) =>
+  } = {}) =>
   (tree, file) => {
     // If frontmatterTitle is true, it will also format the title in the
     // frontmatter, but only if Astro is exposing it.
@@ -61,29 +72,30 @@ const plugin: Plugin<[PluginOptions?], mdast.Root> =
       }
     }
 
-    // Pass 1: every heading. A heading's text can be split across multiple text
-    // nodes (e.g. emphasis, links, inline code), so we collect them first to
-    // find out which is the first/last text node.
+    // Pass 1: every heading. A heading's text can be split across multiple
+    // phrasing nodes (emphasis, links, inline code), so we flatten them into
+    // ordered title items first — that tells us which text node is first/last
+    // and which ones continue a preceding code span ("`head`ing"). Headings
+    // mutate text nodes in place; the serializer re-emits them (and normalizes
+    // the body, e.g. `_em_` → `*em*`, which is the expected heading behavior).
     visit(tree, "heading", (node) => {
-      // Get every text node for this heading
-      const textNodes: { value?: string }[] = [];
-      visit(node, "text", (textNode) => {
-        textNodes.push(textNode);
-      });
-      // Lowercase each node, but be mindful of which one is first/last
-      textNodes.forEach((textNode, i) => {
-        textNode.value = titleCase(textNode.value ?? "", {
+      const items = collectTitleItemsFromChildren(node.children);
+      items.forEach((item, i) => {
+        if (item.type !== "text") return;
+        item.node.value = titleCase(item.node.value, {
           special,
           isFirstTextNode: i === 0,
-          isLastTextNode: i === textNodes.length - 1,
+          isLastTextNode: i === items.length - 1,
+          firstWordIsContinuation: item.firstWordIsContinuation,
         });
       });
     });
     if (componentNames.length === 0) {
       return;
     }
     // Pass 2: title props of the named MDX components. Their value is one raw
-    // string, so capitalizeTitle handles code-span splitting itself.
+    // string, so capitalizeTitle parses and re-cases it (code spans, emphasis,
+    // escapes and all) on its own.
     visit(
       tree,
       (node): node is MdxJsxFlowElement => {

remark-capitalize-titles/package.json

@@ -42,12 +42,14 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "mdast-util-from-markdown": "^2.0.2",
     "unist-util-visit": "^5.0.0"
   },
   "devDependencies": {
     "mdast": "^3.0.0",
     "mdast-util-mdx-jsx": "^3.1.2",
     "remark": "^15.0.1",
+    "remark-mdx": "^3.1.1",
     "tsup": "^8.1.0",
     "typescript": "^5.5.2",
     "unified": "^11.0.4",

remark-capitalize-titles/tests/capitalize-title.test.ts

@@ -31,4 +31,34 @@ describe("capitalizeTitle as standalone function export", () => {
       "The Flavors of `git reset`: Soft or Hard",
     );
   });
+
+  test("treats a suffix attached to a code span as a continuation", () => {
+    expect(capitalizeTitle("the `head`ing story")).toBe(
+      "The `head`ing Story",
+    );
+  });
+
+  test("does not treat text after a leading code span as the title start", () => {
+    expect(capitalizeTitle("`foo` and bar")).toBe("`foo` and Bar");
+  });
+
+  // The string path re-cases the original source bytes, so emphasis delimiters
+  // and backslash escapes are preserved verbatim (no `_em_` → `*em*`).
+  test("preserves emphasis delimiters and escapes without normalizing", () => {
+    expect(capitalizeTitle("a _really_ big \\* moment")).toBe(
+      "A _Really_ Big \\* Moment",
+    );
+  });
+
+  // A title can start with block-markdown punctuation; fromMarkdown parses it
+  // as a heading/list/blockquote, but the enclosing block is transparent, so
+  // the leading marker is preserved and the inline text (including code spans)
+  // is cased exactly as in a plain title.
+  test("preserves a leading heading marker and respects code spans", () => {
+    expect(capitalizeTitle("# the `git` thing")).toBe("# The `git` Thing");
+  });
+
+  test("preserves a leading blockquote marker", () => {
+    expect(capitalizeTitle("> push and pull")).toBe("> Push and Pull");
+  });
 });

remark-capitalize-titles/tests/component-title.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from "vitest";
+import { remark } from "remark";
+import remarkMdx from "remark-mdx";
+import remarkCapitalizeTitles from "../index.ts";
+
+const processComponent = async (
+  value: string,
+  componentNames: string[] = ["Callout"],
+) => {
+  const file = await remark()
+    .use(remarkMdx)
+    .use(remarkCapitalizeTitles, { componentNames })
+    .process(value);
+  return file.toString().slice(0, -1);
+};
+
+describe("Capitalizes named component titles", () => {
+  test("title-cases a plain component title", async () => {
+    expect(
+      await processComponent('<Callout title="merging with github via npm" />'),
+    ).toBe('<Callout title="Merging with GitHub via NPM" />');
+  });
+
+  test("preserves an inline code span inside a component title", async () => {
+    expect(
+      await processComponent(
+        '<Callout title="the flavors of `git reset`: soft, hard, or mixed" />',
+      ),
+    ).toBe(
+      '<Callout title="The Flavors of `git reset`: Soft, Hard, or Mixed" />',
+    );
+  });
+
+  test("ignores components not in the list", async () => {
+    expect(await processComponent('<Other title="leave this alone" />')).toBe(
+      '<Other title="leave this alone" />',
+    );
+  });
+});

remark-capitalize-titles/tests/index.test.ts

@@ -197,6 +197,26 @@ describe("Handles inline code spans", () => {
       "#### The Jokes Write Themselves: `ours`, `theirs`, and Three-way Merges",
     );
   });
+
+  test("treats a parenthetical suffix attached to a trailing code span as a continuation", async () => {
+    expect(
+      await processMarkdown(
+        "#### easier than real life: finding your `remote`(s)",
+      ),
+    ).toBe("#### Easier than Real Life: Finding Your `remote`(s)");
+  });
+
+  test("does not treat text after a leading code span as the title start", async () => {
+    expect(await processMarkdown("## `push` and pull")).toBe(
+      "## `push` and Pull",
+    );
+  });
+
+  test("treats a suffix attached directly to a code span as a continuation", async () => {
+    expect(await processMarkdown("## the `head`ing story")).toBe(
+      "## The `head`ing Story",
+    );
+  });
 });
 
 describe("Handles hyphenated compound words", () => {