@asteroidcms/core-utils 0.1.5 → 0.1.7

package/README.md

@@ -11,6 +11,7 @@
 - **Provider-driven** - configure `cmsUrl`, `apiKey`, and Apollo behavior in one place
 - **API-key auth only** - sends `x-api-key` on every request, nothing else
 - **Typed hooks** - `useCmsContent` / `useCmsMutate` build GraphQL on the fly from a declarative selection
+- **Server helpers** - `fetchCmsContent` / `cmsMutate` for Next.js Server Components, Route Handlers, and scripts
 - **Tree-shakeable** - ESM + CJS + types, `@apollo/client`/`react` as peer deps
 
 ---
@@ -34,7 +35,7 @@ npm install @apollo/client-integration-nextjs # for nextjs (optional)
 Wrap your app once:
 
 ```tsx
-import { AsteroidCMSProvider } from "@asteroidcms/core-utils";
+import { AsteroidCMSProvider } from "@asteroidcms/core-utils/client";
 
 export function Root() {
   return (
@@ -51,7 +52,7 @@ export function Root() {
 Then use the hooks anywhere:
 
 ```tsx
-import { useCmsContent, useCmsImage } from "@asteroidcms/core-utils";
+import { useCmsContent, useCmsImage } from "@asteroidcms/core-utils/client";
 
 function NewsList() {
   const cmsImage = useCmsImage();
@@ -197,9 +198,7 @@ const { data: topStories } = useCmsContent({
 
 ## `fetchCmsContent` (Next.js / RSC)
 
-Server-side counterpart to `useCmsContent`. Use it in Next.js Server Components, route handlers, or any other server context. Accepts a server-side Apollo client plus the same options object as `useCmsContent`, and returns the resolved data directly.
-
-Pass a `getClient` function that returns a server-side Apollo client. The shape matches what `registerApolloClient` from `@apollo/client-integration-nextjs` already returns, so you can hand it through directly.
+Server-side counterpart to `useCmsContent`. Use it in Next.js Server Components, Route Handlers, or any other server context. Accepts a `getClient` function plus the same options object as `useCmsContent`, and returns the resolved data directly.
 
 ```ts
 // app/lib/cms-server.ts
@@ -242,28 +241,6 @@ const articles = await fetchCmsContent<Article[]>(getClient, {
 
 Outside Next.js you can pass any `() => ApolloClient` - e.g. `() => createApolloClient({ cmsUrl, apiKey })`.
 
-Add `import "server-only"` in the file that calls it if you want Next.js to fail the build when it leaks into a client component.
-
----
-
-## `buildCmsQuery`
-
-Lower-level helper that turns a declarative selection into a GraphQL `DocumentNode` plus variables. Used internally by `useCmsContent` and `fetchCmsContent`; exported so you can drive your own Apollo calls (cache reads, prefetching, batching, etc.).
-
-```ts
-import { buildCmsQuery } from "@asteroidcms/core-utils";
-
-const { query, variables, isSingle } = buildCmsQuery({
-  schema_slug: "news",
-  limit: 10,
-  status: "PUBLISHED",
-  select: ["title", "slug"],
-});
-
-const { data } = await apolloClient.query({ query, variables });
-const entries = isSingle ? data.entry : data.entries;
-```
-
 ---
 
 ## `useCmsMutate`
@@ -310,6 +287,69 @@ removeComment();
 
 ---
 
+## `cmsMutate` (Next.js / RSC)
+
+Server-side counterpart to `useCmsMutate`. Use it in Route Handlers, webhooks, cron jobs, or build scripts.
+
+```ts
+import { cmsMutate } from "@asteroidcms/core-utils";
+import { getClient } from "@/app/lib/cms-server";
+
+// Create
+const entry = await cmsMutate<{ id: string }>(getClient, {
+  schema_slug: "newsletter_subscribers",
+  mutationType: "create",
+  variables: { data: { email: "user@example.com", name: "Alice" } },
+});
+
+// Update
+await cmsMutate(getClient, {
+  schema_slug: "news",
+  mutationType: "update",
+  entryId: "abc123",
+  variables: { data: { title: "Updated title" } },
+});
+
+// Delete
+await cmsMutate(getClient, {
+  schema_slug: "comments",
+  mutationType: "delete",
+  entryId: "xyz789",
+});
+```
+
+---
+
+## `buildCmsQuery` / `buildCmsMutation`
+
+Lower-level helpers that turn a declarative selection into GraphQL `DocumentNode` plus variables. Used internally by the hooks and server helpers; exported so you can drive your own Apollo calls.
+
+```ts
+import { buildCmsQuery, buildCmsMutation } from "@asteroidcms/core-utils";
+
+// Query
+const { query, variables, isSingle } = buildCmsQuery({
+  schema_slug: "news",
+  limit: 10,
+  status: "PUBLISHED",
+  select: ["title", "slug"],
+});
+
+const { data } = await apolloClient.query({ query, variables });
+const entries = isSingle ? data.entry : data.entries;
+
+// Mutation
+const { mutation, variables: mutVars } = buildCmsMutation({
+  schema_slug: "news",
+  mutationType: "create",
+  variables: { data: { title: "Hello" } },
+});
+
+const { data: mutData } = await apolloClient.mutate({ mutation, variables: mutVars });
+```
+
+---
+
 ## `cmsImage` / `useCmsImage`
 
 Build a canonical media URL for an asset id.
@@ -372,7 +412,7 @@ import { Info } from "lucide-react";
 />;
 ```
 
-Additional props: `contentRef` (forwards the wrapper element, useful for `useTableOfContents`), `onReady` (fires once enhancements have run), and `calloutIcons` (per-variant icon override for `<aside data-callout data-icon>` blocks).
+Additional props: `contentRef` (forwards the wrapper element, useful for scroll observers or ToC hooks), `onReady` (fires once enhancements have run), and `calloutIcons` (per-variant icon override for `<aside data-callout data-icon>` blocks).
 
 Or use the parser directly (server-safe, no `highlight.js`):
 
@@ -388,56 +428,24 @@ 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:
+Build a static ToC from HTML with `extractHeadingsFromHtml`, or extract headings from live DOM with `extractHeadingsFromElement`:
 
-```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
-  });
+```ts
+import { extractHeadingsFromHtml } from "@asteroidcms/core-utils";
 
-  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>
-  );
-}
+const toc = extractHeadingsFromHtml(article.body, { levels: [2, 3] });
+// → [{ id: "intro", text: "Intro", level: 2 }, ...]
 ```
 
-For a static, server-side outline (RSC layouts, sitemaps, RSS), use `extractHeadingsFromHtml`:
-
 ```ts
-import { extractHeadingsFromHtml } from "@asteroidcms/core-utils";
+import { extractHeadingsFromElement } from "@asteroidcms/core-utils/client";
 
-const toc = extractHeadingsFromHtml(article.body, { levels: [2, 3] });
+const toc = extractHeadingsFromElement(contentRef.current, { 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.
+Pair with `RichTextContent`'s `contentRef` prop and a scroll listener to build live active-heading tracking.
+
+See the [full rich-text docs](./docs/web-sdk-react/10-rich-text.md) for `classMap` variants, parser options, and code block features.
 
 ---
 

package/dist/client.cjs

@@ -1050,37 +1050,38 @@ function isIconEnabled(el) {
   if (v === null) return false;
   return v !== "false" && v !== "0";
 }
-function enhanceCallouts(root) {
+function enhanceCallouts(root, calloutIcons) {
   const callouts = root.querySelectorAll("aside[data-callout]");
   callouts.forEach((el) => {
-    if (el.dataset.rtCalloutEnhanced === "1") return;
-    el.dataset.rtCalloutEnhanced = "1";
-    if (!isIconEnabled(el)) return;
     if (el.querySelector(":scope > .rt-callout-icon")) return;
+    if (!isIconEnabled(el)) return;
     const variant = calloutVariantOf(el);
     const icon = document.createElement("span");
     icon.className = "rt-callout-icon";
     icon.dataset.variant = variant;
     icon.setAttribute("aria-hidden", "true");
+    if (!calloutIcons || !(variant in calloutIcons)) {
+      icon.innerHTML = CALLOUT_ICON_SVG[variant] ?? CALLOUT_ICON_SVG.default;
+    }
     el.prepend(icon);
   });
+  if (!calloutIcons) return [];
   const chips = [];
   root.querySelectorAll(
     "aside[data-callout] > .rt-callout-icon"
   ).forEach((chip) => {
-    chips.push({
-      el: chip,
-      variant: chip.dataset.variant || (chip.parentElement?.getAttribute("data-variant") ?? "default")
-    });
+    const variant = chip.dataset.variant || (chip.parentElement?.getAttribute("data-variant") ?? "default");
+    if (variant in calloutIcons) {
+      chips.push({ el: chip, variant });
+    }
   });
   return chips;
 }
 function enhanceBlockquotes(root) {
   const quotes = root.querySelectorAll("blockquote");
   quotes.forEach((bq) => {
-    if (bq.dataset.rtQuoted === "1") return;
+    if (bq.querySelector(":scope > .rt-quote-open")) return;
     if (bq.closest('figure[data-variant="pullquote"]')) return;
-    bq.dataset.rtQuoted = "1";
     const { first, last } = findQuoteBody(bq);
     if (!first || !last) return;
     const open = document.createElement("span");
@@ -1119,11 +1120,10 @@ function highlightCodeBlock(pre) {
   if (!lang) return;
   const code = pre.querySelector("code");
   if (!code) return;
-  if (code.dataset.rtHighlighted === "1") return;
+  if (code.classList.contains("hljs")) return;
   const source = code.textContent ?? "";
   code.innerHTML = highlightSource(source, lang);
   code.classList.add("hljs");
-  code.dataset.rtHighlighted = "1";
 }
 var DIFF_SEPARATOR_RE = /\n?@@---@@\n?/;
 function diffLines(a, b) {
@@ -1246,8 +1246,7 @@ function buildCodeBlockLabel(pre) {
 function enhanceCodeBlocks(root) {
   const blocks = root.querySelectorAll("pre");
   blocks.forEach((pre) => {
-    if (pre.dataset.rtEnhanced === "1") return;
-    pre.dataset.rtEnhanced = "1";
+    if (pre.classList.contains("rt-codeblock")) return;
     pre.classList.add("rt-codeblock");
     const variant = pre.dataset.variant;
     if (variant === "diff") {
@@ -1591,7 +1590,7 @@ function BuiltinCalloutIcon({ variant }) {
   const html = CALLOUT_ICON_SVG[variant] ?? CALLOUT_ICON_SVG.default;
   return /* @__PURE__ */ jsxRuntime.jsx("span", { dangerouslySetInnerHTML: { __html: html } });
 }
-function RichTextContent({
+var RichTextContent = react.memo(function RichTextContent2({
   html,
   classMap,
   as = "div",
@@ -1609,49 +1608,58 @@ function RichTextContent({
     [html, merged]
   );
   const ref = react.useRef(null);
-  const [chips, setChips] = react.useState([]);
-  react.useEffect(() => {
+  const prevSafe = react.useRef("");
+  const chipsRef = react.useRef([]);
+  const onReadyRef = react.useRef(onReady);
+  onReadyRef.current = onReady;
+  const contentRefStable = react.useRef(contentRef);
+  contentRefStable.current = contentRef;
+  const calloutIconsRef = react.useRef(calloutIcons);
+  calloutIconsRef.current = calloutIcons;
+  const [renderKey, setRenderKey] = react.useState(0);
+  react.useLayoutEffect(() => {
     ensureCodeBlockStyles();
     const root = ref.current;
     if (!root) return;
-    if (contentRef) contentRef.current = root;
-    const apply = () => {
-      mo.disconnect();
-      enhanceCodeBlocks(root);
-      enhanceBlockquotes(root);
-      const nextChips = enhanceCallouts(root);
-      setChips((prev) => calloutChipsEqual(prev, nextChips) ? prev : nextChips);
-      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]);
+    if (contentRefStable.current) contentRefStable.current.current = root;
+    if (prevSafe.current === safe) return;
+    prevSafe.current = safe;
+    root.innerHTML = safe;
+    enhanceCodeBlocks(root);
+    enhanceBlockquotes(root);
+    const nextChips = enhanceCallouts(root, calloutIconsRef.current);
+    if (!calloutChipsEqual(chipsRef.current, nextChips)) {
+      chipsRef.current = nextChips;
+      if (nextChips.length > 0) setRenderKey((n) => n + 1);
+    }
+    onReadyRef.current?.(root);
+  }, [safe]);
   return /* @__PURE__ */ jsxRuntime.jsxs(react.Fragment, { children: [
     react.createElement(as, {
       ref,
-      className,
-      dangerouslySetInnerHTML: { __html: safe }
+      className
     }),
-    chips.map(
+    chipsRef.current.map(
       (chip, i) => reactDom.createPortal(
-        calloutIcons && chip.variant in calloutIcons ? calloutIcons[chip.variant] : /* @__PURE__ */ jsxRuntime.jsx(BuiltinCalloutIcon, { variant: chip.variant }),
+        calloutIconsRef.current && chip.variant in calloutIconsRef.current ? calloutIconsRef.current[chip.variant] : /* @__PURE__ */ jsxRuntime.jsx(BuiltinCalloutIcon, { variant: chip.variant }),
         chip.el,
         `${chip.variant}:${i}`
       )
     )
   ] });
+}, richTextPropsEqual);
+function richTextPropsEqual(prev, next) {
+  if (prev.html !== next.html) return false;
+  if (prev.classMap !== next.classMap) return false;
+  if (prev.as !== next.as) return false;
+  if (prev.className !== next.className) return false;
+  const prevKeys = prev.calloutIcons ? Object.keys(prev.calloutIcons) : [];
+  const nextKeys = next.calloutIcons ? Object.keys(next.calloutIcons) : [];
+  if (prevKeys.length !== nextKeys.length) return false;
+  for (const k of nextKeys) {
+    if (!prevKeys.includes(k)) return false;
+  }
+  return true;
 }
 
 // src/utils/extractHeadings.ts
@@ -1727,97 +1735,6 @@ function extractHeadingsFromElement(root, options = {}) {
   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;
@@ -1827,6 +1744,5 @@ exports.useAsteroidCMSConfig = useAsteroidCMSConfig;
 exports.useCmsContent = useCmsContent;
 exports.useCmsImage = useCmsImage;
 exports.useCmsMutate = useCmsMutate;
-exports.useTableOfContents = useTableOfContents;
 //# sourceMappingURL=client.cjs.map
 //# sourceMappingURL=client.cjs.map