@asteroidcms/core-utils 0.1.2 → 0.1.4

package/dist/client.d.cts

@@ -0,0 +1,316 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react 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';
+
+type AsteroidCMSConfig = {
+    /** Base URL of the Asteroid CMS API (e.g. https://cms-api.example.com). */
+    cmsUrl: string;
+    /** API key sent as the `x-api-key` header on every request. */
+    apiKey: string;
+    /** Optional path appended to `cmsUrl` for the GraphQL endpoint. Defaults to "/graphql". */
+    graphqlPath?: string;
+    /** Optional path appended to `cmsUrl` for canonical media. Defaults to "/media/canonical". */
+    mediaPath?: string;
+    /** Extra headers attached to every GraphQL request. */
+    headers?: Record<string, string>;
+    /** Called for every GraphQL/network error. Use this to wire your own toast/logger. */
+    onError?: (error: unknown) => void;
+    /** Optional cache options forwarded to the InMemoryCache constructor. */
+    cacheConfig?: InMemoryCacheConfig;
+    /** Escape hatch — override any field on the underlying ApolloClient. */
+    apolloOptions?: Partial<ApolloClientOptions>;
+    /** Provide a pre-built ApolloClient and skip the internal factory entirely. */
+    client?: ApolloClient;
+};
+type ResolvedAsteroidCMSConfig = Required<Pick<AsteroidCMSConfig, "cmsUrl" | "apiKey" | "graphqlPath" | "mediaPath">> & {
+    headers: Record<string, string>;
+    onError?: AsteroidCMSConfig["onError"];
+};
+
+type AsteroidCMSProviderProps = PropsWithChildren<AsteroidCMSConfig>;
+/**
+ * Root provider for `@asteroidcms/core-utils`.
+ *
+ * Wrap your app once at the top level:
+ *
+ * ```tsx
+ * <AsteroidCMSProvider cmsUrl="https://cms.example.com" apiKey="...">
+ *   <App />
+ * </AsteroidCMSProvider>
+ * ```
+ *
+ * Everything below — `useCmsContent`, `useCmsMutate`, `useCmsImage`,
+ * `<RichTextContent>` — picks up `cmsUrl` and `apiKey` from this provider.
+ */
+declare function AsteroidCMSProvider({ children, ...config }: AsteroidCMSProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function useAsteroidCMSConfig(): ResolvedAsteroidCMSConfig;
+
+type FieldSelector$1 = string | {
+    field: string;
+    as?: string;
+};
+type ReferenceExpansion$1 = {
+    field: string;
+    as?: string;
+    single?: boolean;
+    select?: readonly (FieldSelector$1 | ReferenceExpansion$1)[];
+};
+type ContentStatus = "DRAFT" | "PUBLISHED" | "ARCHIVED";
+type CmsSearchCondition = {
+    field: string;
+    value: string;
+    mode?: string;
+};
+type UseCmsContentOptions = {
+    schema_slug: string;
+    entrySlug?: string;
+    select?: readonly (FieldSelector$1 | ReferenceExpansion$1)[];
+    fullData?: boolean;
+    limit?: number;
+    offset?: number;
+    status?: ContentStatus;
+    filter?: Record<string, string | number | boolean | null>;
+    search?: CmsSearchCondition[];
+    variables?: Record<string, any>;
+};
+/**
+ * React hook for querying content from Asteroid CMS via a flexible GraphQL API.
+ *
+ * Supports single-entry fetches (`entrySlug`) and paginated/filtered lists,
+ * with arbitrarily nested reference expansion and field aliasing.
+ */
+declare function useCmsContent<T = unknown>({ schema_slug, entrySlug, select, fullData, limit, offset, status, filter, search, variables, }: UseCmsContentOptions): {
+    client: _apollo_client.ApolloClient;
+    observable: _apollo_client.ObservableQuery<unknown, _apollo_client.OperationVariables>;
+    previousData?: unknown;
+    networkStatus: _apollo_client.NetworkStatus;
+    startPolling: (pollInterval: number) => void;
+    stopPolling: () => void;
+    subscribeToMore: _apollo_client.SubscribeToMoreFunction<unknown, _apollo_client.OperationVariables>;
+    updateQuery: (mapFn: _apollo_client.UpdateQueryMapFn<unknown, _apollo_client.OperationVariables>) => void;
+    refetch: (variables?: Partial<_apollo_client.OperationVariables> | undefined) => Promise<{
+        data: unknown;
+        error?: _apollo_client.ErrorLike;
+    }>;
+    variables: _apollo_client.OperationVariables;
+    fetchMore: <TFetchData = unknown, TFetchVars extends _apollo_client.OperationVariables = _apollo_client.OperationVariables>(fetchMoreOptions: _apollo_client.ObservableQuery.FetchMoreOptions<unknown, _apollo_client.OperationVariables, TFetchData, TFetchVars>) => Promise<{
+        data: TFetchData | undefined;
+        error?: _apollo_client.ErrorLike;
+    }>;
+    dataState: "empty";
+    loading: boolean;
+    error: _apollo_client.ErrorLike | undefined;
+    data: T | undefined;
+} | {
+    client: _apollo_client.ApolloClient;
+    observable: _apollo_client.ObservableQuery<unknown, _apollo_client.OperationVariables>;
+    previousData?: unknown;
+    networkStatus: _apollo_client.NetworkStatus;
+    startPolling: (pollInterval: number) => void;
+    stopPolling: () => void;
+    subscribeToMore: _apollo_client.SubscribeToMoreFunction<unknown, _apollo_client.OperationVariables>;
+    updateQuery: (mapFn: _apollo_client.UpdateQueryMapFn<unknown, _apollo_client.OperationVariables>) => void;
+    refetch: (variables?: Partial<_apollo_client.OperationVariables> | undefined) => Promise<{
+        data: unknown;
+        error?: _apollo_client.ErrorLike;
+    }>;
+    variables: _apollo_client.OperationVariables;
+    fetchMore: <TFetchData = unknown, TFetchVars extends _apollo_client.OperationVariables = _apollo_client.OperationVariables>(fetchMoreOptions: _apollo_client.ObservableQuery.FetchMoreOptions<unknown, _apollo_client.OperationVariables, TFetchData, TFetchVars>) => Promise<{
+        data: TFetchData | undefined;
+        error?: _apollo_client.ErrorLike;
+    }>;
+    dataState: "complete";
+    loading: boolean;
+    error: _apollo_client.ErrorLike | undefined;
+    data: T | undefined;
+} | {
+    client: _apollo_client.ApolloClient;
+    observable: _apollo_client.ObservableQuery<unknown, _apollo_client.OperationVariables>;
+    previousData?: unknown;
+    networkStatus: _apollo_client.NetworkStatus;
+    startPolling: (pollInterval: number) => void;
+    stopPolling: () => void;
+    subscribeToMore: _apollo_client.SubscribeToMoreFunction<unknown, _apollo_client.OperationVariables>;
+    updateQuery: (mapFn: _apollo_client.UpdateQueryMapFn<unknown, _apollo_client.OperationVariables>) => void;
+    refetch: (variables?: Partial<_apollo_client.OperationVariables> | undefined) => Promise<{
+        data: unknown;
+        error?: _apollo_client.ErrorLike;
+    }>;
+    variables: _apollo_client.OperationVariables;
+    fetchMore: <TFetchData = unknown, TFetchVars extends _apollo_client.OperationVariables = _apollo_client.OperationVariables>(fetchMoreOptions: _apollo_client.ObservableQuery.FetchMoreOptions<unknown, _apollo_client.OperationVariables, TFetchData, TFetchVars>) => Promise<{
+        data: TFetchData | undefined;
+        error?: _apollo_client.ErrorLike;
+    }>;
+    dataState: "streaming";
+    loading: boolean;
+    error: _apollo_client.ErrorLike | undefined;
+    data: T | undefined;
+};
+
+type FieldSelector = string | {
+    field: string;
+    as?: string;
+    single?: boolean;
+    select?: readonly (FieldSelector | ReferenceExpansion)[];
+};
+type ReferenceExpansion = {
+    field: string;
+    as?: string;
+    single?: boolean;
+    select?: readonly (FieldSelector | ReferenceExpansion)[];
+};
+type MutationType = "create" | "update" | "delete";
+type UseCmsMutateOptions = {
+    schema_slug: string;
+    entrySlug?: string;
+    select?: readonly (FieldSelector | ReferenceExpansion)[];
+    fullData?: boolean;
+    mutationType?: MutationType;
+    entryId?: string;
+    variables?: Record<string, any>;
+};
+/**
+ * React hook for mutating content in Asteroid CMS (`create` / `update` / `delete`).
+ * Uses the same selection syntax as `useCmsContent`.
+ */
+declare function useCmsMutate<TData = unknown>({ schema_slug, select, fullData, mutationType, entryId, variables: inputVariables, }: UseCmsMutateOptions): {
+    readonly data: TData | undefined;
+    readonly loading: boolean;
+    readonly called: boolean;
+    readonly client: _apollo_client.ApolloClient;
+    readonly reset: () => void;
+    readonly error: _apollo_client.ErrorLike | undefined;
+    readonly mutate: useMutation.MutationFunction<unknown, {
+        [x: string]: any;
+    }, _apollo_client.ApolloCache, "none">;
+};
+
+/** Hook variant that pulls `cmsUrl`/`mediaPath` from the provider. */
+declare function useCmsImage(): (id?: string) => string;
+
+/**
+ * Portable rich-text parser for CMS content.
+ *
+ * Zero runtime dependencies. Safe to copy into any consuming frontend.
+ *
+ * Pipeline:
+ *   1. Detect & migrate legacy "markdown-in-divs" content to clean semantic HTML.
+ *   2. Walk the HTML through a tag/attribute allowlist (strips <script>, event
+ *      handlers, javascript: URLs, unknown tags).
+ *   3. Merge per-tag and per-variant classes from `options.classMap`.
+ *
+ * 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 RichTextClassMap = Partial<Record<RichTextClassKey, string>> & {
+    /** Variant overrides keyed as `${matchKey}:${variant}`, e.g. "callout:warning". */
+    variants?: Record<string, string>;
+};
+
+interface RichTextContentProps {
+    html: string;
+    classMap?: RichTextClassMap;
+    /** 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, onReady, contentRef, }: RichTextContentProps): react.DOMElement<{
+    ref: react.MutableRefObject<HTMLElement | null>;
+    className: string | undefined;
+    dangerouslySetInnerHTML: {
+        __html: string;
+    };
+}, HTMLElement>;
+
+/**
+ * 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

@@ -0,0 +1,316 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react 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';
+
+type AsteroidCMSConfig = {
+    /** Base URL of the Asteroid CMS API (e.g. https://cms-api.example.com). */
+    cmsUrl: string;
+    /** API key sent as the `x-api-key` header on every request. */
+    apiKey: string;
+    /** Optional path appended to `cmsUrl` for the GraphQL endpoint. Defaults to "/graphql". */
+    graphqlPath?: string;
+    /** Optional path appended to `cmsUrl` for canonical media. Defaults to "/media/canonical". */
+    mediaPath?: string;
+    /** Extra headers attached to every GraphQL request. */
+    headers?: Record<string, string>;
+    /** Called for every GraphQL/network error. Use this to wire your own toast/logger. */
+    onError?: (error: unknown) => void;
+    /** Optional cache options forwarded to the InMemoryCache constructor. */
+    cacheConfig?: InMemoryCacheConfig;
+    /** Escape hatch — override any field on the underlying ApolloClient. */
+    apolloOptions?: Partial<ApolloClientOptions>;
+    /** Provide a pre-built ApolloClient and skip the internal factory entirely. */
+    client?: ApolloClient;
+};
+type ResolvedAsteroidCMSConfig = Required<Pick<AsteroidCMSConfig, "cmsUrl" | "apiKey" | "graphqlPath" | "mediaPath">> & {
+    headers: Record<string, string>;
+    onError?: AsteroidCMSConfig["onError"];
+};
+
+type AsteroidCMSProviderProps = PropsWithChildren<AsteroidCMSConfig>;
+/**
+ * Root provider for `@asteroidcms/core-utils`.
+ *
+ * Wrap your app once at the top level:
+ *
+ * ```tsx
+ * <AsteroidCMSProvider cmsUrl="https://cms.example.com" apiKey="...">
+ *   <App />
+ * </AsteroidCMSProvider>
+ * ```
+ *
+ * Everything below — `useCmsContent`, `useCmsMutate`, `useCmsImage`,
+ * `<RichTextContent>` — picks up `cmsUrl` and `apiKey` from this provider.
+ */
+declare function AsteroidCMSProvider({ children, ...config }: AsteroidCMSProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function useAsteroidCMSConfig(): ResolvedAsteroidCMSConfig;
+
+type FieldSelector$1 = string | {
+    field: string;
+    as?: string;
+};
+type ReferenceExpansion$1 = {
+    field: string;
+    as?: string;
+    single?: boolean;
+    select?: readonly (FieldSelector$1 | ReferenceExpansion$1)[];
+};
+type ContentStatus = "DRAFT" | "PUBLISHED" | "ARCHIVED";
+type CmsSearchCondition = {
+    field: string;
+    value: string;
+    mode?: string;
+};
+type UseCmsContentOptions = {
+    schema_slug: string;
+    entrySlug?: string;
+    select?: readonly (FieldSelector$1 | ReferenceExpansion$1)[];
+    fullData?: boolean;
+    limit?: number;
+    offset?: number;
+    status?: ContentStatus;
+    filter?: Record<string, string | number | boolean | null>;
+    search?: CmsSearchCondition[];
+    variables?: Record<string, any>;
+};
+/**
+ * React hook for querying content from Asteroid CMS via a flexible GraphQL API.
+ *
+ * Supports single-entry fetches (`entrySlug`) and paginated/filtered lists,
+ * with arbitrarily nested reference expansion and field aliasing.
+ */
+declare function useCmsContent<T = unknown>({ schema_slug, entrySlug, select, fullData, limit, offset, status, filter, search, variables, }: UseCmsContentOptions): {
+    client: _apollo_client.ApolloClient;
+    observable: _apollo_client.ObservableQuery<unknown, _apollo_client.OperationVariables>;
+    previousData?: unknown;
+    networkStatus: _apollo_client.NetworkStatus;
+    startPolling: (pollInterval: number) => void;
+    stopPolling: () => void;
+    subscribeToMore: _apollo_client.SubscribeToMoreFunction<unknown, _apollo_client.OperationVariables>;
+    updateQuery: (mapFn: _apollo_client.UpdateQueryMapFn<unknown, _apollo_client.OperationVariables>) => void;
+    refetch: (variables?: Partial<_apollo_client.OperationVariables> | undefined) => Promise<{
+        data: unknown;
+        error?: _apollo_client.ErrorLike;
+    }>;
+    variables: _apollo_client.OperationVariables;
+    fetchMore: <TFetchData = unknown, TFetchVars extends _apollo_client.OperationVariables = _apollo_client.OperationVariables>(fetchMoreOptions: _apollo_client.ObservableQuery.FetchMoreOptions<unknown, _apollo_client.OperationVariables, TFetchData, TFetchVars>) => Promise<{
+        data: TFetchData | undefined;
+        error?: _apollo_client.ErrorLike;
+    }>;
+    dataState: "empty";
+    loading: boolean;
+    error: _apollo_client.ErrorLike | undefined;
+    data: T | undefined;
+} | {
+    client: _apollo_client.ApolloClient;
+    observable: _apollo_client.ObservableQuery<unknown, _apollo_client.OperationVariables>;
+    previousData?: unknown;
+    networkStatus: _apollo_client.NetworkStatus;
+    startPolling: (pollInterval: number) => void;
+    stopPolling: () => void;
+    subscribeToMore: _apollo_client.SubscribeToMoreFunction<unknown, _apollo_client.OperationVariables>;
+    updateQuery: (mapFn: _apollo_client.UpdateQueryMapFn<unknown, _apollo_client.OperationVariables>) => void;
+    refetch: (variables?: Partial<_apollo_client.OperationVariables> | undefined) => Promise<{
+        data: unknown;
+        error?: _apollo_client.ErrorLike;
+    }>;
+    variables: _apollo_client.OperationVariables;
+    fetchMore: <TFetchData = unknown, TFetchVars extends _apollo_client.OperationVariables = _apollo_client.OperationVariables>(fetchMoreOptions: _apollo_client.ObservableQuery.FetchMoreOptions<unknown, _apollo_client.OperationVariables, TFetchData, TFetchVars>) => Promise<{
+        data: TFetchData | undefined;
+        error?: _apollo_client.ErrorLike;
+    }>;
+    dataState: "complete";
+    loading: boolean;
+    error: _apollo_client.ErrorLike | undefined;
+    data: T | undefined;
+} | {
+    client: _apollo_client.ApolloClient;
+    observable: _apollo_client.ObservableQuery<unknown, _apollo_client.OperationVariables>;
+    previousData?: unknown;
+    networkStatus: _apollo_client.NetworkStatus;
+    startPolling: (pollInterval: number) => void;
+    stopPolling: () => void;
+    subscribeToMore: _apollo_client.SubscribeToMoreFunction<unknown, _apollo_client.OperationVariables>;
+    updateQuery: (mapFn: _apollo_client.UpdateQueryMapFn<unknown, _apollo_client.OperationVariables>) => void;
+    refetch: (variables?: Partial<_apollo_client.OperationVariables> | undefined) => Promise<{
+        data: unknown;
+        error?: _apollo_client.ErrorLike;
+    }>;
+    variables: _apollo_client.OperationVariables;
+    fetchMore: <TFetchData = unknown, TFetchVars extends _apollo_client.OperationVariables = _apollo_client.OperationVariables>(fetchMoreOptions: _apollo_client.ObservableQuery.FetchMoreOptions<unknown, _apollo_client.OperationVariables, TFetchData, TFetchVars>) => Promise<{
+        data: TFetchData | undefined;
+        error?: _apollo_client.ErrorLike;
+    }>;
+    dataState: "streaming";
+    loading: boolean;
+    error: _apollo_client.ErrorLike | undefined;
+    data: T | undefined;
+};
+
+type FieldSelector = string | {
+    field: string;
+    as?: string;
+    single?: boolean;
+    select?: readonly (FieldSelector | ReferenceExpansion)[];
+};
+type ReferenceExpansion = {
+    field: string;
+    as?: string;
+    single?: boolean;
+    select?: readonly (FieldSelector | ReferenceExpansion)[];
+};
+type MutationType = "create" | "update" | "delete";
+type UseCmsMutateOptions = {
+    schema_slug: string;
+    entrySlug?: string;
+    select?: readonly (FieldSelector | ReferenceExpansion)[];
+    fullData?: boolean;
+    mutationType?: MutationType;
+    entryId?: string;
+    variables?: Record<string, any>;
+};
+/**
+ * React hook for mutating content in Asteroid CMS (`create` / `update` / `delete`).
+ * Uses the same selection syntax as `useCmsContent`.
+ */
+declare function useCmsMutate<TData = unknown>({ schema_slug, select, fullData, mutationType, entryId, variables: inputVariables, }: UseCmsMutateOptions): {
+    readonly data: TData | undefined;
+    readonly loading: boolean;
+    readonly called: boolean;
+    readonly client: _apollo_client.ApolloClient;
+    readonly reset: () => void;
+    readonly error: _apollo_client.ErrorLike | undefined;
+    readonly mutate: useMutation.MutationFunction<unknown, {
+        [x: string]: any;
+    }, _apollo_client.ApolloCache, "none">;
+};
+
+/** Hook variant that pulls `cmsUrl`/`mediaPath` from the provider. */
+declare function useCmsImage(): (id?: string) => string;
+
+/**
+ * Portable rich-text parser for CMS content.
+ *
+ * Zero runtime dependencies. Safe to copy into any consuming frontend.
+ *
+ * Pipeline:
+ *   1. Detect & migrate legacy "markdown-in-divs" content to clean semantic HTML.
+ *   2. Walk the HTML through a tag/attribute allowlist (strips <script>, event
+ *      handlers, javascript: URLs, unknown tags).
+ *   3. Merge per-tag and per-variant classes from `options.classMap`.
+ *
+ * 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 RichTextClassMap = Partial<Record<RichTextClassKey, string>> & {
+    /** Variant overrides keyed as `${matchKey}:${variant}`, e.g. "callout:warning". */
+    variants?: Record<string, string>;
+};
+
+interface RichTextContentProps {
+    html: string;
+    classMap?: RichTextClassMap;
+    /** 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, onReady, contentRef, }: RichTextContentProps): react.DOMElement<{
+    ref: react.MutableRefObject<HTMLElement | null>;
+    className: string | undefined;
+    dangerouslySetInnerHTML: {
+        __html: string;
+    };
+}, HTMLElement>;
+
+/**
+ * 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 };