@asteroidcms/core-utils 0.1.3 → 0.1.4

package/dist/client.d.cts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
-import { PropsWithChildren } from 'react';
+import { PropsWithChildren, RefObject } from 'react';
 import * as _apollo_client from '@apollo/client';
 import { InMemoryCacheConfig, ApolloClientOptions, ApolloClient } from '@apollo/client';
 import { useMutation } from '@apollo/client/react';
@@ -217,8 +217,20 @@ interface RichTextContentProps {
     /** Wrapper element. Defaults to `div`. Use `article` for blog content. */
     as?: keyof React.JSX.IntrinsicElements;
     className?: string;
+    /**
+     * Fires after the parsed HTML is in the DOM and post-render enhancements
+     * (syntax highlighting, copy buttons, blockquote decorations) have run.
+     * The wrapper element is passed back so callers can read headings, attach
+     * a ToC observer, or do other DOM work without re-querying.
+     */
+    onReady?: (root: HTMLElement) => void;
+    /**
+     * Optional ref to the wrapper element. Useful for hooks like
+     * `useTableOfContents` that need a stable reference to the rendered tree.
+     */
+    contentRef?: React.MutableRefObject<HTMLElement | null>;
 }
-declare function RichTextContent({ html, classMap, as, className, }: RichTextContentProps): react.DOMElement<{
+declare function RichTextContent({ html, classMap, as, className, onReady, contentRef, }: RichTextContentProps): react.DOMElement<{
     ref: react.MutableRefObject<HTMLElement | null>;
     className: string | undefined;
     dangerouslySetInnerHTML: {
@@ -226,4 +238,79 @@ declare function RichTextContent({ html, classMap, as, className, }: RichTextCon
     };
 }, HTMLElement>;
 
-export { AsteroidCMSProvider, type AsteroidCMSProviderProps, RichTextContent, type UseCmsContentOptions, type UseCmsMutateOptions, useAsteroidCMSConfig, useCmsContent, useCmsImage, useCmsMutate };
+/**
+ * Heading extraction helpers used to build tables of contents (ToC) from
+ * rich-text HTML. Server-safe — no React, no DOM dependency in the HTML
+ * variant. The DOM variant assigns missing `id`s in-place so anchor links
+ * resolve immediately.
+ */
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+interface ExtractedHeading {
+    id: string;
+    text: string;
+    level: HeadingLevel;
+}
+interface ExtractHeadingsOptions {
+    /** Levels to include. Defaults to `[2, 3]` — typical doc page outline. */
+    levels?: ReadonlyArray<HeadingLevel>;
+    /** Custom slug function. Defaults to a lowercase/kebab/diacritic-safe slug. */
+    slugify?: (text: string, index: number) => string;
+}
+declare function slugify(text: string): string;
+/**
+ * Parse headings out of a raw HTML string. Returns headings in document
+ * order with stable, de-duplicated IDs.
+ *
+ * If a heading already has an `id` attribute, it's preserved verbatim
+ * (and reserved so later slugs don't collide with it).
+ */
+declare function extractHeadingsFromHtml(html: string, options?: ExtractHeadingsOptions): ExtractedHeading[];
+/**
+ * Walk a rendered DOM subtree, collect headings, and assign missing `id`s
+ * in-place so anchor links resolve immediately. Also sets `scrollMarginTop`
+ * on each heading when `scrollMarginTop` is provided so navigation lands
+ * cleanly below a sticky header.
+ */
+declare function extractHeadingsFromElement(root: HTMLElement, options?: ExtractHeadingsOptions & {
+    scrollMarginTop?: number;
+}): ExtractedHeading[];
+
+interface UseTableOfContentsOptions {
+    /** Heading levels to include. Defaults to `[2, 3]`. */
+    levels?: ReadonlyArray<HeadingLevel>;
+    /**
+     * Re-collect headings whenever this value changes. Pass the article slug
+     * (or any stable identifier) so swapping content rebuilds the ToC.
+     */
+    contentKey?: string | number | null;
+    /** Pixels to subtract from heading scroll-into-view target. Default 24. */
+    scrollMarginTop?: number;
+    /**
+     * Distance from the top of the viewport (in px) at which a heading becomes
+     * "active". A heading is considered active once its top edge has scrolled
+     * past this line. Default `96` — works well with a sticky header that
+     * stands ~60–80px tall.
+     */
+    activationOffset?: number;
+}
+interface UseTableOfContentsResult {
+    items: ExtractedHeading[];
+    activeId: string;
+}
+/**
+ * Build a table of contents from a rendered element and track which
+ * heading is currently in view via IntersectionObserver. Resilient to
+ * content swaps when `contentKey` is provided.
+ *
+ * Usage:
+ * ```tsx
+ * const ref = useRef<HTMLDivElement>(null);
+ * const { items, activeId } = useTableOfContents(ref, {
+ *   contentKey: article.slug,
+ *   levels: [2, 3],
+ * });
+ * ```
+ */
+declare function useTableOfContents(ref: RefObject<HTMLElement | null>, options?: UseTableOfContentsOptions): UseTableOfContentsResult;
+
+export { AsteroidCMSProvider, type AsteroidCMSProviderProps, type ExtractHeadingsOptions, type ExtractedHeading, type HeadingLevel, RichTextContent, type UseCmsContentOptions, type UseCmsMutateOptions, type UseTableOfContentsOptions, type UseTableOfContentsResult, extractHeadingsFromElement, extractHeadingsFromHtml, slugify, useAsteroidCMSConfig, useCmsContent, useCmsImage, useCmsMutate, useTableOfContents };

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
-import { PropsWithChildren } from 'react';
+import { PropsWithChildren, RefObject } from 'react';
 import * as _apollo_client from '@apollo/client';
 import { InMemoryCacheConfig, ApolloClientOptions, ApolloClient } from '@apollo/client';
 import { useMutation } from '@apollo/client/react';
@@ -217,8 +217,20 @@ interface RichTextContentProps {
     /** Wrapper element. Defaults to `div`. Use `article` for blog content. */
     as?: keyof React.JSX.IntrinsicElements;
     className?: string;
+    /**
+     * Fires after the parsed HTML is in the DOM and post-render enhancements
+     * (syntax highlighting, copy buttons, blockquote decorations) have run.
+     * The wrapper element is passed back so callers can read headings, attach
+     * a ToC observer, or do other DOM work without re-querying.
+     */
+    onReady?: (root: HTMLElement) => void;
+    /**
+     * Optional ref to the wrapper element. Useful for hooks like
+     * `useTableOfContents` that need a stable reference to the rendered tree.
+     */
+    contentRef?: React.MutableRefObject<HTMLElement | null>;
 }
-declare function RichTextContent({ html, classMap, as, className, }: RichTextContentProps): react.DOMElement<{
+declare function RichTextContent({ html, classMap, as, className, onReady, contentRef, }: RichTextContentProps): react.DOMElement<{
     ref: react.MutableRefObject<HTMLElement | null>;
     className: string | undefined;
     dangerouslySetInnerHTML: {
@@ -226,4 +238,79 @@ declare function RichTextContent({ html, classMap, as, className, }: RichTextCon
     };
 }, HTMLElement>;
 
-export { AsteroidCMSProvider, type AsteroidCMSProviderProps, RichTextContent, type UseCmsContentOptions, type UseCmsMutateOptions, useAsteroidCMSConfig, useCmsContent, useCmsImage, useCmsMutate };
+/**
+ * Heading extraction helpers used to build tables of contents (ToC) from
+ * rich-text HTML. Server-safe — no React, no DOM dependency in the HTML
+ * variant. The DOM variant assigns missing `id`s in-place so anchor links
+ * resolve immediately.
+ */
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+interface ExtractedHeading {
+    id: string;
+    text: string;
+    level: HeadingLevel;
+}
+interface ExtractHeadingsOptions {
+    /** Levels to include. Defaults to `[2, 3]` — typical doc page outline. */
+    levels?: ReadonlyArray<HeadingLevel>;
+    /** Custom slug function. Defaults to a lowercase/kebab/diacritic-safe slug. */
+    slugify?: (text: string, index: number) => string;
+}
+declare function slugify(text: string): string;
+/**
+ * Parse headings out of a raw HTML string. Returns headings in document
+ * order with stable, de-duplicated IDs.
+ *
+ * If a heading already has an `id` attribute, it's preserved verbatim
+ * (and reserved so later slugs don't collide with it).
+ */
+declare function extractHeadingsFromHtml(html: string, options?: ExtractHeadingsOptions): ExtractedHeading[];
+/**
+ * Walk a rendered DOM subtree, collect headings, and assign missing `id`s
+ * in-place so anchor links resolve immediately. Also sets `scrollMarginTop`
+ * on each heading when `scrollMarginTop` is provided so navigation lands
+ * cleanly below a sticky header.
+ */
+declare function extractHeadingsFromElement(root: HTMLElement, options?: ExtractHeadingsOptions & {
+    scrollMarginTop?: number;
+}): ExtractedHeading[];
+
+interface UseTableOfContentsOptions {
+    /** Heading levels to include. Defaults to `[2, 3]`. */
+    levels?: ReadonlyArray<HeadingLevel>;
+    /**
+     * Re-collect headings whenever this value changes. Pass the article slug
+     * (or any stable identifier) so swapping content rebuilds the ToC.
+     */
+    contentKey?: string | number | null;
+    /** Pixels to subtract from heading scroll-into-view target. Default 24. */
+    scrollMarginTop?: number;
+    /**
+     * Distance from the top of the viewport (in px) at which a heading becomes
+     * "active". A heading is considered active once its top edge has scrolled
+     * past this line. Default `96` — works well with a sticky header that
+     * stands ~60–80px tall.
+     */
+    activationOffset?: number;
+}
+interface UseTableOfContentsResult {
+    items: ExtractedHeading[];
+    activeId: string;
+}
+/**
+ * Build a table of contents from a rendered element and track which
+ * heading is currently in view via IntersectionObserver. Resilient to
+ * content swaps when `contentKey` is provided.
+ *
+ * Usage:
+ * ```tsx
+ * const ref = useRef<HTMLDivElement>(null);
+ * const { items, activeId } = useTableOfContents(ref, {
+ *   contentKey: article.slug,
+ *   levels: [2, 3],
+ * });
+ * ```
+ */
+declare function useTableOfContents(ref: RefObject<HTMLElement | null>, options?: UseTableOfContentsOptions): UseTableOfContentsResult;
+
+export { AsteroidCMSProvider, type AsteroidCMSProviderProps, type ExtractHeadingsOptions, type ExtractedHeading, type HeadingLevel, RichTextContent, type UseCmsContentOptions, type UseCmsMutateOptions, type UseTableOfContentsOptions, type UseTableOfContentsResult, extractHeadingsFromElement, extractHeadingsFromHtml, slugify, useAsteroidCMSConfig, useCmsContent, useCmsImage, useCmsMutate, useTableOfContents };

package/dist/client.js

@@ -1,5 +1,5 @@
 "use client";
-import { createContext, useContext, useMemo, useRef, useEffect, createElement } from 'react';
+import { createContext, useContext, useMemo, useRef, useEffect, createElement, useState } from 'react';
 import { ApolloProvider, useQuery, useMutation } from '@apollo/client/react';
 import { gql, HttpLink, ApolloClient, InMemoryCache, ApolloLink, CombinedGraphQLErrors, CombinedProtocolErrors } from '@apollo/client';
 import { SetContextLink } from '@apollo/client/link/context';
@@ -419,7 +419,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(
@@ -1425,7 +1454,9 @@ function RichTextContent({
   html,
   classMap,
   as = "div",
-  className
+  className,
+  onReady,
+  contentRef
 }) {
   const merged = useMemo(
     () => mergeClassMap(DEFAULT_CLASS_MAP, classMap),
@@ -1438,11 +1469,30 @@ function RichTextContent({
   const ref = useRef(null);
   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 createElement(as, {
     ref,
     className,
@@ -1450,6 +1500,170 @@ function RichTextContent({
   });
 }
 
-export { AsteroidCMSProvider, RichTextContent, useAsteroidCMSConfig, useCmsContent, useCmsImage, useCmsMutate };
+// 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] = useState([]);
+  const [activeId, setActiveId] = useState("");
+  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]);
+  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 };
+}
+
+export { AsteroidCMSProvider, RichTextContent, extractHeadingsFromElement, extractHeadingsFromHtml, slugify, useAsteroidCMSConfig, useCmsContent, useCmsImage, useCmsMutate, useTableOfContents };
 //# sourceMappingURL=client.js.map
 //# sourceMappingURL=client.js.map