@ai-react-markdown/core 1.0.0 → 1.0.1

package/dist/index.d.cts

@@ -2,64 +2,218 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ComponentType, PropsWithChildren } from 'react';
 import { Components } from 'react-markdown';
 
+/**
+ * Core type definitions, enums, and default configuration for ai-react-markdown.
+ *
+ * This module defines the public API surface for configuring the renderer,
+ * including extra markdown syntax extensions, display optimization abilities,
+ * typography theming, and the shared render state shape.
+ *
+ * @module defs
+ */
+
+/**
+ * Extra markdown syntax extensions beyond standard GFM.
+ * Enable or disable these via {@link AIMarkdownRenderConfig.extraSyntaxSupported}.
+ */
 declare enum AIMarkdownRenderExtraSyntax {
-    HIGHLIGHT = "HIGHLIGHT",// support ==Highlight==
-    DEFINITION_LIST = "DEFINITION_LIST",// support Definition List https://michelf.ca/projects/php-markdown/extra/#def-list
+    /** `==Highlight==` syntax support. */
+    HIGHLIGHT = "HIGHLIGHT",
+    /** Definition list syntax. @see https://michelf.ca/projects/php-markdown/extra/#def-list */
+    DEFINITION_LIST = "DEFINITION_LIST",
+    /** Superscript (`^text^`) and subscript (`~text~`) syntax. */
     SUBSCRIPT = "SUBSCRIPT"
 }
+/**
+ * Display optimization abilities applied during markdown processing.
+ * Enable or disable these via {@link AIMarkdownRenderConfig.displayOptimizeAbilities}.
+ */
 declare enum AIMarkdownRenderDisplayOptimizeAbility {
-    REMOVE_COMMENTS = "REMOVE_COMMENTS",// remove comments
-    SMARTYPANTS = "SMARTYPANTS",// make conent more typographic by SmartyPants https://www.npmjs.com/package/smartypants
+    /** Strip HTML comments from the content. */
+    REMOVE_COMMENTS = "REMOVE_COMMENTS",
+    /** Typographic enhancements via SmartyPants (curly quotes, em-dashes, etc.). @see https://www.npmjs.com/package/smartypants */
+    SMARTYPANTS = "SMARTYPANTS",
+    /** Automatically insert spaces between CJK and half-width characters. */
     PANGU = "PANGU"
 }
+/**
+ * Configuration object controlling which markdown extensions and
+ * display optimizations are active during rendering.
+ */
 interface AIMarkdownRenderConfig {
+    /** Extra syntax extensions to enable. */
     extraSyntaxSupported: AIMarkdownRenderExtraSyntax[];
+    /** Display optimization abilities to enable. */
     displayOptimizeAbilities: AIMarkdownRenderDisplayOptimizeAbility[];
 }
+/**
+ * Arbitrary metadata that consumers can pass through the render context.
+ * Custom renderers can access this via {@link AIMarkdownRenderState.metadata}.
+ */
 interface AIMarkdownMetadata extends Record<string, any> {
 }
+/**
+ * Typography variant identifier. Built-in variant is `'default'`;
+ * consumers may define additional variants via custom typography components.
+ */
 type AIMarkdownVariant = 'default' | (string & {});
+/**
+ * Color scheme identifier. Built-in schemes are `'light'` and `'dark'`;
+ * consumers may define additional schemes via custom typography CSS.
+ */
 type AIMarkdownColorScheme = 'light' | 'dark' | (string & {});
+/** Props accepted by a typography wrapper component. */
 interface AIMarkdownTypographyProps extends PropsWithChildren {
+    /** Resolved CSS font-size value (e.g. `'14px'`, `'0.875rem'`). */
     fontSize: string;
+    /** Active typography variant. */
     variant?: AIMarkdownVariant;
+    /** Active color scheme. */
     colorScheme?: AIMarkdownColorScheme;
 }
+/** React component type for the typography wrapper. */
 type AIMarkdownTypographyComponent = ComponentType<AIMarkdownTypographyProps>;
+/** Props accepted by an optional extra style wrapper component. */
 interface AIMarkdownExtraStyleProps extends PropsWithChildren {
 }
+/** React component type for an optional extra style wrapper. */
 type AIMarkdownExtraStyleComponent = ComponentType<AIMarkdownExtraStyleProps>;
+/**
+ * Immutable render state exposed to all descendant components via React context.
+ * Access this with the {@link useAIMarkdownRenderState} hook.
+ *
+ * @typeParam TConfig - Render configuration type (defaults to {@link AIMarkdownRenderConfig}).
+ * @typeParam TMetadata - Metadata type (defaults to {@link AIMarkdownMetadata}).
+ */
 interface AIMarkdownRenderState<TConfig extends AIMarkdownRenderConfig = AIMarkdownRenderConfig, TMetadata extends AIMarkdownMetadata = AIMarkdownMetadata> {
+    /** Whether the content is currently being streamed (e.g. from an LLM). */
     streaming: boolean;
+    /** Resolved CSS font-size value. */
     fontSize: string;
+    /** Active render configuration. */
     config: TConfig;
+    /** Optional consumer-provided metadata. */
     metadata?: TMetadata;
 }
 
+/**
+ * Shared TypeScript utility types.
+ *
+ * @module ts-util
+ */
+/**
+ * Recursively makes all properties of `T` optional.
+ * Unlike the built-in `Partial<T>`, this traverses nested objects.
+ *
+ * @typeParam T - The type to make deeply partial.
+ *
+ * @example
+ * ```ts
+ * type Config = { a: { b: number } };
+ * type PartialConfig = DeepPartial<Config>;
+ * // { a?: { b?: number } }
+ * ```
+ */
 type DeepPartial<T> = {
     [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
 };
 
+/**
+ * Access the current {@link AIMarkdownRenderState} from within the `<AIMarkdown>` tree.
+ *
+ * Must be called inside a component rendered as a descendant of `<AIMarkdown>`.
+ * Throws if called outside the provider boundary.
+ *
+ * @typeParam TConfig - Expected configuration shape (defaults to {@link AIMarkdownRenderConfig}).
+ * @typeParam TMetadata - Expected metadata shape (defaults to {@link AIMarkdownMetadata}).
+ * @returns The current render state.
+ *
+ * @example
+ * ```tsx
+ * function CustomCodeBlock({ children }: PropsWithChildren) {
+ *   const { streaming, config } = useAIMarkdownRenderState();
+ *   // ...
+ * }
+ * ```
+ */
 declare function useAIMarkdownRenderState<TConfig extends AIMarkdownRenderConfig = AIMarkdownRenderConfig, TMetadata extends AIMarkdownMetadata = AIMarkdownMetadata>(): AIMarkdownRenderState<TConfig, TMetadata>;
+/** Props for {@link AIMarkdownRenderStateProvider}. */
 interface AIMarkdownRenderStateProviderProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRenderConfig, TMetadata extends AIMarkdownMetadata = AIMarkdownMetadata> extends PropsWithChildren {
     streaming: boolean;
     fontSize: string;
+    /** Partial config that will be deep-merged with {@link defaultAIMarkdownRenderConfig}. */
     config?: DeepPartial<TConfig>;
     metadata?: TMetadata;
 }
 
+/**
+ * Type definitions for the content preprocessor pipeline.
+ *
+ * @module preprocessors/defs
+ */
+/**
+ * A synchronous function that transforms raw markdown content before it is
+ * passed to the remark/rehype rendering pipeline.
+ *
+ * Preprocessors run in sequence -- each receives the output of the previous one.
+ *
+ * @param content - The raw (or partially processed) markdown string.
+ * @returns The transformed markdown string.
+ *
+ * @example
+ * ```ts
+ * const stripFrontmatter: AIMDContentPreprocessor = (content) =>
+ *   content.replace(/^---[\s\S]*?---\n/, '');
+ * ```
+ */
 type AIMDContentPreprocessor = (content: string) => string;
 
+/**
+ * Props for the `<AIMarkdown>` component.
+ *
+ * @typeParam TConfig - Custom render configuration type (extends {@link AIMarkdownRenderConfig}).
+ * @typeParam TRenderData - Custom metadata type (extends {@link AIMarkdownMetadata}).
+ */
 interface AIMarkdownProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRenderConfig, TRenderData extends AIMarkdownMetadata = AIMarkdownMetadata> extends Omit<AIMarkdownRenderStateProviderProps<TConfig, TRenderData>, 'fontSize'> {
+    /**
+     * Base font size for the rendered output.
+     * Accepts a CSS length string (e.g. `'14px'`, `'0.875rem'`) or a number
+     * which is treated as pixels. Defaults to `'0.875rem'`.
+     */
     fontSize?: number | string;
+    /** Raw markdown content to render. */
     content: string;
+    /**
+     * Additional preprocessors to run on the raw markdown before rendering.
+     * These run *after* the built-in LaTeX preprocessor.
+     */
     contentPreprocessors?: AIMDContentPreprocessor[];
+    /**
+     * Custom `react-markdown` component overrides.
+     * Use this to replace the default renderers for specific HTML elements
+     * (e.g. code blocks, links, images).
+     */
     customComponents?: Components;
+    /**
+     * Typography wrapper component. Receives `fontSize`, `variant`, and `colorScheme`.
+     * Defaults to the built-in {@link DefaultTypography}.
+     */
     typography?: AIMarkdownTypographyComponent;
+    /**
+     * Optional extra style wrapper component rendered between the typography
+     * wrapper and the markdown content. Useful for injecting additional
+     * CSS scope or theme providers.
+     */
     extraStyle?: AIMarkdownExtraStyleComponent;
+    /** Typography variant name. Defaults to `'default'`. */
     variant?: AIMarkdownVariant;
+    /** Color scheme name. Defaults to `'light'`. */
     colorScheme?: AIMarkdownColorScheme;
 }
+/**
+ * Root component that preprocesses markdown content and renders it through
+ * a configurable remark/rehype pipeline wrapped in typography and style layers.
+ */
 declare const AIMarkdownComponent: <TConfig extends AIMarkdownRenderConfig = AIMarkdownRenderConfig, TRenderData extends AIMarkdownMetadata = AIMarkdownMetadata>({ streaming, content, fontSize, contentPreprocessors, customComponents, config, metadata, typography: Typography, extraStyle: ExtraStyle, variant, colorScheme, }: AIMarkdownProps<TConfig, TRenderData>) => react_jsx_runtime.JSX.Element;
 declare const _default: typeof AIMarkdownComponent;
 

package/dist/index.d.ts

@@ -2,64 +2,218 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ComponentType, PropsWithChildren } from 'react';
 import { Components } from 'react-markdown';
 
+/**
+ * Core type definitions, enums, and default configuration for ai-react-markdown.
+ *
+ * This module defines the public API surface for configuring the renderer,
+ * including extra markdown syntax extensions, display optimization abilities,
+ * typography theming, and the shared render state shape.
+ *
+ * @module defs
+ */
+
+/**
+ * Extra markdown syntax extensions beyond standard GFM.
+ * Enable or disable these via {@link AIMarkdownRenderConfig.extraSyntaxSupported}.
+ */
 declare enum AIMarkdownRenderExtraSyntax {
-    HIGHLIGHT = "HIGHLIGHT",// support ==Highlight==
-    DEFINITION_LIST = "DEFINITION_LIST",// support Definition List https://michelf.ca/projects/php-markdown/extra/#def-list
+    /** `==Highlight==` syntax support. */
+    HIGHLIGHT = "HIGHLIGHT",
+    /** Definition list syntax. @see https://michelf.ca/projects/php-markdown/extra/#def-list */
+    DEFINITION_LIST = "DEFINITION_LIST",
+    /** Superscript (`^text^`) and subscript (`~text~`) syntax. */
     SUBSCRIPT = "SUBSCRIPT"
 }
+/**
+ * Display optimization abilities applied during markdown processing.
+ * Enable or disable these via {@link AIMarkdownRenderConfig.displayOptimizeAbilities}.
+ */
 declare enum AIMarkdownRenderDisplayOptimizeAbility {
-    REMOVE_COMMENTS = "REMOVE_COMMENTS",// remove comments
-    SMARTYPANTS = "SMARTYPANTS",// make conent more typographic by SmartyPants https://www.npmjs.com/package/smartypants
+    /** Strip HTML comments from the content. */
+    REMOVE_COMMENTS = "REMOVE_COMMENTS",
+    /** Typographic enhancements via SmartyPants (curly quotes, em-dashes, etc.). @see https://www.npmjs.com/package/smartypants */
+    SMARTYPANTS = "SMARTYPANTS",
+    /** Automatically insert spaces between CJK and half-width characters. */
     PANGU = "PANGU"
 }
+/**
+ * Configuration object controlling which markdown extensions and
+ * display optimizations are active during rendering.
+ */
 interface AIMarkdownRenderConfig {
+    /** Extra syntax extensions to enable. */
     extraSyntaxSupported: AIMarkdownRenderExtraSyntax[];
+    /** Display optimization abilities to enable. */
     displayOptimizeAbilities: AIMarkdownRenderDisplayOptimizeAbility[];
 }
+/**
+ * Arbitrary metadata that consumers can pass through the render context.
+ * Custom renderers can access this via {@link AIMarkdownRenderState.metadata}.
+ */
 interface AIMarkdownMetadata extends Record<string, any> {
 }
+/**
+ * Typography variant identifier. Built-in variant is `'default'`;
+ * consumers may define additional variants via custom typography components.
+ */
 type AIMarkdownVariant = 'default' | (string & {});
+/**
+ * Color scheme identifier. Built-in schemes are `'light'` and `'dark'`;
+ * consumers may define additional schemes via custom typography CSS.
+ */
 type AIMarkdownColorScheme = 'light' | 'dark' | (string & {});
+/** Props accepted by a typography wrapper component. */
 interface AIMarkdownTypographyProps extends PropsWithChildren {
+    /** Resolved CSS font-size value (e.g. `'14px'`, `'0.875rem'`). */
     fontSize: string;
+    /** Active typography variant. */
     variant?: AIMarkdownVariant;
+    /** Active color scheme. */
     colorScheme?: AIMarkdownColorScheme;
 }
+/** React component type for the typography wrapper. */
 type AIMarkdownTypographyComponent = ComponentType<AIMarkdownTypographyProps>;
+/** Props accepted by an optional extra style wrapper component. */
 interface AIMarkdownExtraStyleProps extends PropsWithChildren {
 }
+/** React component type for an optional extra style wrapper. */
 type AIMarkdownExtraStyleComponent = ComponentType<AIMarkdownExtraStyleProps>;
+/**
+ * Immutable render state exposed to all descendant components via React context.
+ * Access this with the {@link useAIMarkdownRenderState} hook.
+ *
+ * @typeParam TConfig - Render configuration type (defaults to {@link AIMarkdownRenderConfig}).
+ * @typeParam TMetadata - Metadata type (defaults to {@link AIMarkdownMetadata}).
+ */
 interface AIMarkdownRenderState<TConfig extends AIMarkdownRenderConfig = AIMarkdownRenderConfig, TMetadata extends AIMarkdownMetadata = AIMarkdownMetadata> {
+    /** Whether the content is currently being streamed (e.g. from an LLM). */
     streaming: boolean;
+    /** Resolved CSS font-size value. */
     fontSize: string;
+    /** Active render configuration. */
     config: TConfig;
+    /** Optional consumer-provided metadata. */
     metadata?: TMetadata;
 }
 
+/**
+ * Shared TypeScript utility types.
+ *
+ * @module ts-util
+ */
+/**
+ * Recursively makes all properties of `T` optional.
+ * Unlike the built-in `Partial<T>`, this traverses nested objects.
+ *
+ * @typeParam T - The type to make deeply partial.
+ *
+ * @example
+ * ```ts
+ * type Config = { a: { b: number } };
+ * type PartialConfig = DeepPartial<Config>;
+ * // { a?: { b?: number } }
+ * ```
+ */
 type DeepPartial<T> = {
     [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
 };
 
+/**
+ * Access the current {@link AIMarkdownRenderState} from within the `<AIMarkdown>` tree.
+ *
+ * Must be called inside a component rendered as a descendant of `<AIMarkdown>`.
+ * Throws if called outside the provider boundary.
+ *
+ * @typeParam TConfig - Expected configuration shape (defaults to {@link AIMarkdownRenderConfig}).
+ * @typeParam TMetadata - Expected metadata shape (defaults to {@link AIMarkdownMetadata}).
+ * @returns The current render state.
+ *
+ * @example
+ * ```tsx
+ * function CustomCodeBlock({ children }: PropsWithChildren) {
+ *   const { streaming, config } = useAIMarkdownRenderState();
+ *   // ...
+ * }
+ * ```
+ */
 declare function useAIMarkdownRenderState<TConfig extends AIMarkdownRenderConfig = AIMarkdownRenderConfig, TMetadata extends AIMarkdownMetadata = AIMarkdownMetadata>(): AIMarkdownRenderState<TConfig, TMetadata>;
+/** Props for {@link AIMarkdownRenderStateProvider}. */
 interface AIMarkdownRenderStateProviderProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRenderConfig, TMetadata extends AIMarkdownMetadata = AIMarkdownMetadata> extends PropsWithChildren {
     streaming: boolean;
     fontSize: string;
+    /** Partial config that will be deep-merged with {@link defaultAIMarkdownRenderConfig}. */
     config?: DeepPartial<TConfig>;
     metadata?: TMetadata;
 }
 
+/**
+ * Type definitions for the content preprocessor pipeline.
+ *
+ * @module preprocessors/defs
+ */
+/**
+ * A synchronous function that transforms raw markdown content before it is
+ * passed to the remark/rehype rendering pipeline.
+ *
+ * Preprocessors run in sequence -- each receives the output of the previous one.
+ *
+ * @param content - The raw (or partially processed) markdown string.
+ * @returns The transformed markdown string.
+ *
+ * @example
+ * ```ts
+ * const stripFrontmatter: AIMDContentPreprocessor = (content) =>
+ *   content.replace(/^---[\s\S]*?---\n/, '');
+ * ```
+ */
 type AIMDContentPreprocessor = (content: string) => string;
 
+/**
+ * Props for the `<AIMarkdown>` component.
+ *
+ * @typeParam TConfig - Custom render configuration type (extends {@link AIMarkdownRenderConfig}).
+ * @typeParam TRenderData - Custom metadata type (extends {@link AIMarkdownMetadata}).
+ */
 interface AIMarkdownProps<TConfig extends AIMarkdownRenderConfig = AIMarkdownRenderConfig, TRenderData extends AIMarkdownMetadata = AIMarkdownMetadata> extends Omit<AIMarkdownRenderStateProviderProps<TConfig, TRenderData>, 'fontSize'> {
+    /**
+     * Base font size for the rendered output.
+     * Accepts a CSS length string (e.g. `'14px'`, `'0.875rem'`) or a number
+     * which is treated as pixels. Defaults to `'0.875rem'`.
+     */
     fontSize?: number | string;
+    /** Raw markdown content to render. */
     content: string;
+    /**
+     * Additional preprocessors to run on the raw markdown before rendering.
+     * These run *after* the built-in LaTeX preprocessor.
+     */
     contentPreprocessors?: AIMDContentPreprocessor[];
+    /**
+     * Custom `react-markdown` component overrides.
+     * Use this to replace the default renderers for specific HTML elements
+     * (e.g. code blocks, links, images).
+     */
     customComponents?: Components;
+    /**
+     * Typography wrapper component. Receives `fontSize`, `variant`, and `colorScheme`.
+     * Defaults to the built-in {@link DefaultTypography}.
+     */
     typography?: AIMarkdownTypographyComponent;
+    /**
+     * Optional extra style wrapper component rendered between the typography
+     * wrapper and the markdown content. Useful for injecting additional
+     * CSS scope or theme providers.
+     */
     extraStyle?: AIMarkdownExtraStyleComponent;
+    /** Typography variant name. Defaults to `'default'`. */
     variant?: AIMarkdownVariant;
+    /** Color scheme name. Defaults to `'light'`. */
     colorScheme?: AIMarkdownColorScheme;
 }
+/**
+ * Root component that preprocesses markdown content and renders it through
+ * a configurable remark/rehype pipeline wrapped in typography and style layers.
+ */
 declare const AIMarkdownComponent: <TConfig extends AIMarkdownRenderConfig = AIMarkdownRenderConfig, TRenderData extends AIMarkdownMetadata = AIMarkdownMetadata>({ streaming, content, fontSize, contentPreprocessors, customComponents, config, metadata, typography: Typography, extraStyle: ExtraStyle, variant, colorScheme, }: AIMarkdownProps<TConfig, TRenderData>) => react_jsx_runtime.JSX.Element;
 declare const _default: typeof AIMarkdownComponent;