@asteroidcms/core-utils 0.1.3 → 0.1.5

package/dist/index.d.cts

@@ -132,7 +132,7 @@ declare function getContentReadTime(content: string, options?: GetContentReadTim
  *
  * Idempotent: parseRichText(parseRichText(x, opts), opts) === parseRichText(x, opts).
  */
-type RichTextClassKey = "p" | "br" | "hr" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "ul" | "ol" | "li" | "blockquote" | "pre" | "code" | "inlineCode" | "a" | "strong" | "em" | "u" | "s" | "kbd" | "table" | "tableWrapper" | "thead" | "tbody" | "tr" | "th" | "td" | "figure" | "figcaption" | "img" | "span" | "callout" | "calloutTitle";
+type RichTextClassKey = "p" | "br" | "hr" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "ul" | "ol" | "li" | "blockquote" | "pre" | "code" | "inlineCode" | "a" | "strong" | "em" | "u" | "s" | "kbd" | "table" | "tableWrapper" | "thead" | "tbody" | "tr" | "th" | "td" | "figure" | "figcaption" | "img" | "span" | "callout" | "calloutTitle" | "collapsible" | "collapsibleTitle";
 type RichTextClassMap = Partial<Record<RichTextClassKey, string>> & {
     /** Variant overrides keyed as `${matchKey}:${variant}`, e.g. "callout:warning". */
     variants?: Record<string, string>;
@@ -141,6 +141,12 @@ interface ParseRichTextOptions {
     classMap?: RichTextClassMap;
     /** Tag allowlist override. Defaults to a safe semantic set. */
     allowlist?: ReadonlyArray<string>;
+    /**
+     * When `true` (default), inject slugified `id` attributes on `<h1>`–`<h6>`
+     * tags that don't already have one. Lets ToC anchors resolve from the
+     * server-rendered markup without a client-side mutation step.
+     */
+    autoHeadingIds?: boolean;
 }
 declare function parseRichText(html: string, options?: ParseRichTextOptions): string;
 /**
@@ -150,4 +156,41 @@ declare function parseRichText(html: string, options?: ParseRichTextOptions): st
  */
 declare function removeEmptyParagraphs(html: string): string;
 
-export { type AsteroidCMSConfig, type CmsSearchCondition, type ContentStatus, type FieldSelector, type ParseRichTextOptions, type ReferenceExpansion, type ResolvedAsteroidCMSConfig, type RichTextClassKey, type RichTextClassMap, type UseCmsContentOptions, buildCmsQuery, cmsImage, createApolloClient, fetchCmsContent, getContentReadTime, parseRichText, removeEmptyParagraphs };
+/**
+ * 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[];
+
+export { type AsteroidCMSConfig, type CmsSearchCondition, type ContentStatus, type ExtractHeadingsOptions, type ExtractedHeading, type FieldSelector, type HeadingLevel, type ParseRichTextOptions, type ReferenceExpansion, type ResolvedAsteroidCMSConfig, type RichTextClassKey, type RichTextClassMap, type UseCmsContentOptions, buildCmsQuery, cmsImage, createApolloClient, extractHeadingsFromElement, extractHeadingsFromHtml, fetchCmsContent, getContentReadTime, parseRichText, removeEmptyParagraphs, slugify };

package/dist/index.d.ts

@@ -132,7 +132,7 @@ declare function getContentReadTime(content: string, options?: GetContentReadTim
  *
  * Idempotent: parseRichText(parseRichText(x, opts), opts) === parseRichText(x, opts).
  */
-type RichTextClassKey = "p" | "br" | "hr" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "ul" | "ol" | "li" | "blockquote" | "pre" | "code" | "inlineCode" | "a" | "strong" | "em" | "u" | "s" | "kbd" | "table" | "tableWrapper" | "thead" | "tbody" | "tr" | "th" | "td" | "figure" | "figcaption" | "img" | "span" | "callout" | "calloutTitle";
+type RichTextClassKey = "p" | "br" | "hr" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "ul" | "ol" | "li" | "blockquote" | "pre" | "code" | "inlineCode" | "a" | "strong" | "em" | "u" | "s" | "kbd" | "table" | "tableWrapper" | "thead" | "tbody" | "tr" | "th" | "td" | "figure" | "figcaption" | "img" | "span" | "callout" | "calloutTitle" | "collapsible" | "collapsibleTitle";
 type RichTextClassMap = Partial<Record<RichTextClassKey, string>> & {
     /** Variant overrides keyed as `${matchKey}:${variant}`, e.g. "callout:warning". */
     variants?: Record<string, string>;
@@ -141,6 +141,12 @@ interface ParseRichTextOptions {
     classMap?: RichTextClassMap;
     /** Tag allowlist override. Defaults to a safe semantic set. */
     allowlist?: ReadonlyArray<string>;
+    /**
+     * When `true` (default), inject slugified `id` attributes on `<h1>`–`<h6>`
+     * tags that don't already have one. Lets ToC anchors resolve from the
+     * server-rendered markup without a client-side mutation step.
+     */
+    autoHeadingIds?: boolean;
 }
 declare function parseRichText(html: string, options?: ParseRichTextOptions): string;
 /**
@@ -150,4 +156,41 @@ declare function parseRichText(html: string, options?: ParseRichTextOptions): st
  */
 declare function removeEmptyParagraphs(html: string): string;
 
-export { type AsteroidCMSConfig, type CmsSearchCondition, type ContentStatus, type FieldSelector, type ParseRichTextOptions, type ReferenceExpansion, type ResolvedAsteroidCMSConfig, type RichTextClassKey, type RichTextClassMap, type UseCmsContentOptions, buildCmsQuery, cmsImage, createApolloClient, fetchCmsContent, getContentReadTime, parseRichText, removeEmptyParagraphs };
+/**
+ * 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[];
+
+export { type AsteroidCMSConfig, type CmsSearchCondition, type ContentStatus, type ExtractHeadingsOptions, type ExtractedHeading, type FieldSelector, type HeadingLevel, type ParseRichTextOptions, type ReferenceExpansion, type ResolvedAsteroidCMSConfig, type RichTextClassKey, type RichTextClassMap, type UseCmsContentOptions, buildCmsQuery, cmsImage, createApolloClient, extractHeadingsFromElement, extractHeadingsFromHtml, fetchCmsContent, getContentReadTime, parseRichText, removeEmptyParagraphs, slugify };

package/dist/index.js

@@ -270,7 +270,9 @@ var DEFAULT_ALLOWLIST = [
   "section",
   "article",
   "div",
-  "span"
+  "span",
+  "details",
+  "summary"
 ];
 var ALLOWED_ATTRS = {
   a: ["href", "title", "target", "rel"],
@@ -280,7 +282,8 @@ var ALLOWED_ATTRS = {
   col: ["span", "width"],
   colgroup: ["span"],
   table: ["border", "cellpadding", "cellspacing"],
-  span: ["style"]
+  span: ["style"],
+  details: ["open"]
 };
 var ALLOWED_STYLE_PROPS = {
   span: ["font-size"]
@@ -314,7 +317,8 @@ var GLOBAL_ALLOWED_ATTRS = [
   "data-title",
   "data-callout-title",
   "data-language",
-  "data-filename"
+  "data-filename",
+  "data-icon"
 ];
 var URL_ATTRS = /* @__PURE__ */ new Set(["href", "src"]);
 function parseRichText(html, options = {}) {
@@ -324,7 +328,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(
@@ -699,6 +732,8 @@ function classKeyForTag(tag, attrs, openStack) {
   if (tag === "p" && "data-callout-title" in attrs) return "calloutTitle";
   if (tag === "code" && openStack[openStack.length - 1] !== "pre")
     return "inlineCode";
+  if (tag === "details") return "collapsible";
+  if (tag === "summary") return "collapsibleTitle";
   const known = [
     "p",
     "br",
@@ -866,6 +901,79 @@ function sanitizeAndStyle(html, options) {
   return out.join("");
 }
 
-export { buildCmsQuery, cmsImage, createApolloClient, fetchCmsContent, getContentReadTime, parseRichText, removeEmptyParagraphs };
+// 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;
+}
+
+export { buildCmsQuery, cmsImage, createApolloClient, extractHeadingsFromElement, extractHeadingsFromHtml, fetchCmsContent, getContentReadTime, parseRichText, removeEmptyParagraphs, slugify };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map