@asteroidcms/core-utils 0.1.3 → 0.1.4

package/README.md

@@ -356,18 +356,20 @@ getContentReadTime(article.body, {
 
 ## `<RichTextContent>`
 
-Render Asteroid CMS rich-text JSON/HTML with syntax-highlighted code blocks (via `highlight.js`).
+Render Asteroid CMS rich-text HTML with syntax-highlighted code blocks (via `highlight.js`), self-healing enhancements (copy buttons, blockquote decorations), and slugified heading IDs out of the box.
 
 ```tsx
-import { RichTextContent } from "@asteroidcms/core-utils";
+import { RichTextContent } from "@asteroidcms/core-utils/client";
 
 <RichTextContent
-  content={article.body}
+  html={article.body}
+  as="article"
+  className="prose"
   classMap={{ p: "my-2 leading-relaxed", h2: "text-2xl font-bold" }}
 />;
 ```
 
-Or use the parser directly:
+Or use the parser directly (server-safe, no `highlight.js`):
 
 ```ts
 import { parseRichText } from "@asteroidcms/core-utils";
@@ -379,6 +381,59 @@ const html = parseRichText(article.body, {
 });
 ```
 
+### Table of contents
+
+Build a live, scroll-tracked ToC from rendered content with `useTableOfContents`. Pair it with `RichTextContent`'s `contentRef` prop:
+
+```tsx
+import { useRef } from "react";
+import {
+  RichTextContent,
+  useTableOfContents,
+} from "@asteroidcms/core-utils/client";
+
+function Article({ slug, html }: { slug: string; html: string }) {
+  const contentRef = useRef<HTMLElement | null>(null);
+  const { items, activeId } = useTableOfContents(contentRef, {
+    levels: [2, 3],
+    contentKey: slug,           // re-collect when content swaps
+    activationOffset: 96,       // px from viewport top
+  });
+
+  return (
+    <div className="flex gap-8">
+      <RichTextContent
+        html={html}
+        as="article"
+        className="prose"
+        contentRef={contentRef}
+      />
+      <nav>
+        {items.map((it) => (
+          <a
+            key={it.id}
+            href={`#${it.id}`}
+            className={it.id === activeId ? "font-semibold" : ""}
+          >
+            {it.text}
+          </a>
+        ))}
+      </nav>
+    </div>
+  );
+}
+```
+
+For a static, server-side outline (RSC layouts, sitemaps, RSS), use `extractHeadingsFromHtml`:
+
+```ts
+import { extractHeadingsFromHtml } from "@asteroidcms/core-utils";
+
+const toc = extractHeadingsFromHtml(article.body, { levels: [2, 3] });
+```
+
+See the [full rich-text docs](./docs/web-sdk-react/10-rich-text.md) for `classMap` variants, parser options, and `useTableOfContents` tuning.
+
 ---
 
 ## Advanced - bring your own Apollo client

package/dist/client.cjs

@@ -425,7 +425,36 @@ function parseRichText(html, options = {}) {
   working = upgradeStandaloneImages(working);
   working = upgradeAuthoredBlockquotes(working);
   working = flattenTableCellParagraphs(working);
-  return sanitizeAndStyle(working, options);
+  working = sanitizeAndStyle(working, options);
+  if (options.autoHeadingIds !== false) {
+    working = injectHeadingIds(working);
+  }
+  return working;
+}
+function injectHeadingIds(html) {
+  const used = /* @__PURE__ */ new Map();
+  const existingRe = /<h[1-6]\b[^>]*\bid\s*=\s*("([^"]*)"|'([^']*)'|(\S+))/gi;
+  let em;
+  while ((em = existingRe.exec(html)) !== null) {
+    const id = em[2] ?? em[3] ?? em[4] ?? "";
+    if (id) used.set(id, (used.get(id) ?? 0) + 1);
+  }
+  return html.replace(
+    /<(h[1-6])\b([^>]*)>([\s\S]*?)<\/\1>/gi,
+    (full, tag, attrs, inner) => {
+      if (/\bid\s*=/i.test(attrs)) return full;
+      const text = inner.replace(/<[^>]+>/g, " ").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/\s+/g, " ").trim();
+      if (!text) return full;
+      const base = slugifyHeading(text) || tag;
+      const n = used.get(base) ?? 0;
+      used.set(base, n + 1);
+      const id = n === 0 ? base : `${base}-${n}`;
+      return `<${tag}${attrs} id="${id}">${inner}</${tag}>`;
+    }
+  );
+}
+function slugifyHeading(text) {
+  return text.normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().trim().replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
 }
 function flattenTableCellParagraphs(html) {
   return html.replace(
@@ -1431,7 +1460,9 @@ function RichTextContent({
   html,
   classMap,
   as = "div",
-  className
+  className,
+  onReady,
+  contentRef
 }) {
   const merged = react.useMemo(
     () => mergeClassMap(DEFAULT_CLASS_MAP, classMap),
@@ -1444,11 +1475,30 @@ function RichTextContent({
   const ref = react.useRef(null);
   react.useEffect(() => {
     ensureCodeBlockStyles();
-    if (ref.current) {
-      enhanceCodeBlocks(ref.current);
-      enhanceBlockquotes(ref.current);
-    }
-  }, [safe]);
+    const root = ref.current;
+    if (!root) return;
+    if (contentRef) contentRef.current = root;
+    const apply = () => {
+      mo.disconnect();
+      enhanceCodeBlocks(root);
+      enhanceBlockquotes(root);
+      onReady?.(root);
+      mo.observe(root, { childList: true, subtree: true });
+    };
+    let raf = 0;
+    const mo = new MutationObserver(() => {
+      if (raf) return;
+      raf = requestAnimationFrame(() => {
+        raf = 0;
+        apply();
+      });
+    });
+    apply();
+    return () => {
+      mo.disconnect();
+      if (raf) cancelAnimationFrame(raf);
+    };
+  }, [safe, onReady, contentRef]);
   return react.createElement(as, {
     ref,
     className,
@@ -1456,11 +1506,179 @@ function RichTextContent({
   });
 }
 
+// src/utils/extractHeadings.ts
+var DEFAULT_LEVELS = [2, 3];
+function slugify(text) {
+  return text.normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().trim().replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+function decodeBasicEntities(s) {
+  return s.replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+}
+function stripTags(s) {
+  return decodeBasicEntities(s.replace(/<[^>]+>/g, " ")).replace(/\s+/g, " ").trim();
+}
+function uniqueId(base, used) {
+  const seed = base || "section";
+  const n = used.get(seed) ?? 0;
+  used.set(seed, n + 1);
+  return n === 0 ? seed : `${seed}-${n}`;
+}
+function extractHeadingsFromHtml(html, options = {}) {
+  if (!html) return [];
+  const levels = options.levels ?? DEFAULT_LEVELS;
+  const slug = options.slugify ?? slugify;
+  const used = /* @__PURE__ */ new Map();
+  const out = [];
+  const re = /<h([1-6])\b([^>]*)>([\s\S]*?)<\/h\1>/gi;
+  let m;
+  let i = 0;
+  while ((m = re.exec(html)) !== null) {
+    const level = Number(m[1]);
+    if (!levels.includes(level)) continue;
+    const attrs = m[2] ?? "";
+    const inner = m[3] ?? "";
+    const text = stripTags(inner);
+    if (!text) continue;
+    const explicitIdMatch = attrs.match(/\bid\s*=\s*("([^"]*)"|'([^']*)'|(\S+))/i);
+    let id;
+    if (explicitIdMatch) {
+      id = explicitIdMatch[2] ?? explicitIdMatch[3] ?? explicitIdMatch[4] ?? "";
+      if (id) used.set(id, (used.get(id) ?? 0) + 1);
+    } else {
+      id = uniqueId(slug(text, i), used);
+    }
+    out.push({ id, text, level });
+    i++;
+  }
+  return out;
+}
+function extractHeadingsFromElement(root, options = {}) {
+  const levels = options.levels ?? DEFAULT_LEVELS;
+  const slug = options.slugify ?? slugify;
+  const selector = levels.map((l) => `h${l}`).join(",");
+  const nodes = root.querySelectorAll(selector);
+  const used = /* @__PURE__ */ new Map();
+  nodes.forEach((n) => {
+    if (n.id) used.set(n.id, (used.get(n.id) ?? 0) + 1);
+  });
+  const out = [];
+  let i = 0;
+  nodes.forEach((node) => {
+    const level = Number(node.tagName.slice(1));
+    const text = (node.textContent ?? "").replace(/\s+/g, " ").trim();
+    if (!text) return;
+    if (!node.id) {
+      node.id = uniqueId(slug(text, i), used);
+    }
+    if (options.scrollMarginTop != null) {
+      node.style.scrollMarginTop = `${options.scrollMarginTop}px`;
+    }
+    out.push({ id: node.id, text, level });
+    i++;
+  });
+  return out;
+}
+
+// src/hooks/useTableOfContents.tsx
+function useTableOfContents(ref, options = {}) {
+  const {
+    levels,
+    contentKey = null,
+    scrollMarginTop = 24,
+    activationOffset = 96
+  } = options;
+  const [items, setItems] = react.useState([]);
+  const [activeId, setActiveId] = react.useState("");
+  react.useEffect(() => {
+    const root = ref.current;
+    if (!root) {
+      setItems([]);
+      setActiveId("");
+      return;
+    }
+    let raf = 0;
+    const collect = () => {
+      const next = extractHeadingsFromElement(root, {
+        levels,
+        scrollMarginTop
+      });
+      setItems(next);
+      setActiveId(
+        (prev) => next.some((h) => h.id === prev) ? prev : next[0]?.id ?? ""
+      );
+    };
+    raf = requestAnimationFrame(collect);
+    const mo = new MutationObserver(() => {
+      if (raf) cancelAnimationFrame(raf);
+      raf = requestAnimationFrame(collect);
+    });
+    mo.observe(root, { childList: true, subtree: true, characterData: true });
+    return () => {
+      mo.disconnect();
+      if (raf) cancelAnimationFrame(raf);
+    };
+  }, [ref, contentKey, levels, scrollMarginTop]);
+  react.useEffect(() => {
+    if (items.length === 0) return;
+    const targets = items.map((it) => document.getElementById(it.id)).filter((el) => el !== null);
+    if (targets.length === 0) return;
+    let raf = 0;
+    const compute = () => {
+      raf = 0;
+      let activeIdx = 0;
+      for (let i = 0; i < items.length; i++) {
+        const el = document.getElementById(items[i].id);
+        if (!el) continue;
+        if (el.getBoundingClientRect().top - activationOffset <= 0) {
+          activeIdx = i;
+        } else {
+          break;
+        }
+      }
+      const scroller = document.scrollingElement || document.documentElement;
+      const scrollY = window.scrollY;
+      const viewportH = window.innerHeight;
+      const atBottom = scrollY + viewportH >= scroller.scrollHeight - 2;
+      if (atBottom) {
+        for (let i = items.length - 1; i > activeIdx; i--) {
+          const el = document.getElementById(items[i].id);
+          if (el && el.getBoundingClientRect().top < viewportH) {
+            activeIdx = i;
+            break;
+          }
+        }
+      }
+      setActiveId(items[activeIdx].id);
+    };
+    const schedule = () => {
+      if (raf) return;
+      raf = requestAnimationFrame(compute);
+    };
+    const io = new IntersectionObserver(schedule, {
+      rootMargin: `-${activationOffset}px 0px -${Math.max(0, window.innerHeight - activationOffset - 1)}px 0px`,
+      threshold: 0
+    });
+    targets.forEach((t) => io.observe(t));
+    window.addEventListener("resize", schedule, { passive: true });
+    compute();
+    return () => {
+      io.disconnect();
+      window.removeEventListener("resize", schedule);
+      if (raf) cancelAnimationFrame(raf);
+    };
+  }, [items, activationOffset]);
+  return { items, activeId };
+}
+
 exports.AsteroidCMSProvider = AsteroidCMSProvider;
 exports.RichTextContent = RichTextContent;
+exports.extractHeadingsFromElement = extractHeadingsFromElement;
+exports.extractHeadingsFromHtml = extractHeadingsFromHtml;
+exports.slugify = slugify;
 exports.useAsteroidCMSConfig = useAsteroidCMSConfig;
 exports.useCmsContent = useCmsContent;
 exports.useCmsImage = useCmsImage;
 exports.useCmsMutate = useCmsMutate;
+exports.useTableOfContents = useTableOfContents;
 //# sourceMappingURL=client.cjs.map
 //# sourceMappingURL=client.cjs.map