@asteroidcms/core-utils 0.1.3 → 0.1.5

package/dist/client.d.cts

@@ -1,6 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import * as react from 'react';
-import { PropsWithChildren } from 'react';
+import { PropsWithChildren, ReactNode, RefObject } from 'react';
 import * as _apollo_client from '@apollo/client';
 import { InMemoryCacheConfig, ApolloClientOptions, ApolloClient } from '@apollo/client';
 import { useMutation } from '@apollo/client/react';
@@ -205,7 +204,7 @@ declare function useCmsImage(): (id?: string) => string;
  *
  * 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>;
@@ -217,13 +216,119 @@ 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>;
+    /**
+     * Per-variant icon override for callouts that opt into icons via
+     * `data-icon`. Provide a React element for any variant key — these
+     * elements are rendered into the chip via a portal, so they live in
+     * React land (refs, event handlers, theme context all work). Variants
+     * you don't provide fall back to the built-in SVG glyph.
+     *
+     * Common variants: `"info" | "warning" | "success" | "danger" | "default"`.
+     * Custom variant names work too — anything you set via
+     * `data-variant` on an `<aside data-callout>`.
+     *
+     * Example:
+     * ```tsx
+     * import { Info, AlertTriangle } from "lucide-react";
+     *
+     * <RichTextContent
+     *   html={article.doc}
+     *   calloutIcons={{
+     *     info: <Info size={14} strokeWidth={2.4} />,
+     *     warning: <AlertTriangle size={14} strokeWidth={2.4} />,
+     *   }}
+     * />
+     * ```
+     */
+    calloutIcons?: Partial<Record<string, ReactNode>>;
 }
-declare function RichTextContent({ html, classMap, as, className, }: RichTextContentProps): react.DOMElement<{
-    ref: react.MutableRefObject<HTMLElement | null>;
-    className: string | undefined;
-    dangerouslySetInnerHTML: {
-        __html: string;
-    };
-}, HTMLElement>;
+declare function RichTextContent({ html, classMap, as, className, onReady, contentRef, calloutIcons, }: RichTextContentProps): react_jsx_runtime.JSX.Element;
 
-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,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import * as react from 'react';
-import { PropsWithChildren } from 'react';
+import { PropsWithChildren, ReactNode, RefObject } from 'react';
 import * as _apollo_client from '@apollo/client';
 import { InMemoryCacheConfig, ApolloClientOptions, ApolloClient } from '@apollo/client';
 import { useMutation } from '@apollo/client/react';
@@ -205,7 +204,7 @@ declare function useCmsImage(): (id?: string) => string;
  *
  * 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>;
@@ -217,13 +216,119 @@ 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>;
+    /**
+     * Per-variant icon override for callouts that opt into icons via
+     * `data-icon`. Provide a React element for any variant key — these
+     * elements are rendered into the chip via a portal, so they live in
+     * React land (refs, event handlers, theme context all work). Variants
+     * you don't provide fall back to the built-in SVG glyph.
+     *
+     * Common variants: `"info" | "warning" | "success" | "danger" | "default"`.
+     * Custom variant names work too — anything you set via
+     * `data-variant` on an `<aside data-callout>`.
+     *
+     * Example:
+     * ```tsx
+     * import { Info, AlertTriangle } from "lucide-react";
+     *
+     * <RichTextContent
+     *   html={article.doc}
+     *   calloutIcons={{
+     *     info: <Info size={14} strokeWidth={2.4} />,
+     *     warning: <AlertTriangle size={14} strokeWidth={2.4} />,
+     *   }}
+     * />
+     * ```
+     */
+    calloutIcons?: Partial<Record<string, ReactNode>>;
 }
-declare function RichTextContent({ html, classMap, as, className, }: RichTextContentProps): react.DOMElement<{
-    ref: react.MutableRefObject<HTMLElement | null>;
-    className: string | undefined;
-    dangerouslySetInnerHTML: {
-        __html: string;
-    };
-}, HTMLElement>;
+declare function RichTextContent({ html, classMap, as, className, onReady, contentRef, calloutIcons, }: RichTextContentProps): react_jsx_runtime.JSX.Element;
 
-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 };