@wingleeio/mugen-markdown 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { CSSProperties, JSX, ReactElement, ReactNode } from "react";
 import { ParserOptions } from "@incremark/core";
-import { Blockquote, Blockquote as Blockquote$1, Code, Code as Code$1, Heading, Heading as Heading$1, Html, Html as Html$1, Image, Image as Image$1, Link, List, List as List$1, ListItem, Paragraph, Paragraph as Paragraph$1, PhrasingContent, PhrasingContent as PhrasingContent$1, Root, Root as Root$1, RootContent, RootContent as RootContent$1, Table, Table as Table$1, TableCell, TableRow, ThematicBreak, ThematicBreak as ThematicBreak$1 } from "mdast";
+import { Blockquote, Blockquote as Blockquote$1, Code, Code as Code$1, Delete, Emphasis, Heading, Heading as Heading$1, Html, Html as Html$1, Image, Image as Image$1, InlineCode, Link, Link as Link$1, List, List as List$1, ListItem, Paragraph, Paragraph as Paragraph$1, PhrasingContent, PhrasingContent as PhrasingContent$1, Root, Root as Root$1, RootContent, RootContent as RootContent$1, Strong, Table, Table as Table$1, TableCell, TableRow, Text as Text$1, ThematicBreak, ThematicBreak as ThematicBreak$1 } from "mdast";
 import { BoxProps, Font, Font as Font$1, HStack, HStackProps, MeasurableStyle, PrimitiveComponent, SafeClassName, Text, TextProps, VStack, VStackProps, definePrimitive } from "@wingleeio/mugen";
 
 //#region src/parse.d.ts
@@ -175,8 +175,19 @@ declare function resolveTheme(theme?: DeepPartial<MarkdownTheme>): MarkdownTheme
  * rich-inline layout) and the painted spans use the identical fonts.
  */
 interface RichTextRun {
-  /** The run's text. Ignored when `break` is set. */
-  text: string;
+  /** The run's text. Ignored when `break` or `advance` is set. */
+  text?: string;
+  /**
+   * Render this run as an **inline box** — the inline analogue of mugen's
+   * `Escape`: it reserves exactly `advance` px in the flow (via pretext's
+   * `extraWidth`) and paints {@link content}, whatever it is, without measuring
+   * its insides. The flow wraps it as one non-breaking atom. The caller owns the
+   * contract: `content` must render exactly `advance` px wide and no taller than
+   * the line (use the exported `measureInline` to size text-based boxes).
+   */
+  advance?: number;
+  /** The painted content of an inline box (see {@link advance}). */
+  content?: ReactNode;
   /** Measurable font for this run; falls back to the `<RichText font>` prop. */
   font?: Font$1;
   color?: string;
@@ -217,6 +228,12 @@ interface RichTextProps<C extends string = string> {
  * performs over the rendered spans, so the analytic height matches the paint.
  */
 declare const RichText: <C extends string = string>(props: RichTextProps<C>) => ReactElement;
+/**
+ * Measure a string's rendered advance in px for a given measurable font — the
+ * same ruler `RichText` measures with. Use it to size an inline box: a text
+ * "pill" reserves `measureInline(label, font) + horizontalPadding`.
+ */
+declare function measureInline(text: string, font: Font$1): number;
 /** Drop the rich-inline prepare cache (tests / memory pressure). */
 declare function clearRichTextCache(): void;
 //#endregion
@@ -252,9 +269,11 @@ declare function composeFont(fmt: InlineFormat): Font$1;
 /**
  * Flatten phrasing content into styled runs. Recursive over the inline marks;
  * the result feeds a single `<RichText>` so the whole paragraph wraps as one
- * flow and measures exactly.
+ * flow and measures exactly. An `inline` override map can replace how any node
+ * type flattens — returning its own runs (e.g. a measured inline box) or `null`
+ * to fall through to the default.
  */
-declare function flattenInline(nodes: readonly PhrasingContent$1[], fmt: InlineFormat, theme: MarkdownTheme, out: RichTextRun[]): void;
+declare function flattenInline(nodes: readonly PhrasingContent$1[], fmt: InlineFormat, theme: MarkdownTheme, out: RichTextRun[], inline?: InlineComponents): void;
 //#endregion
 //#region src/types.d.ts
 /** Options for building a body/heading inline-text (`RichText`) element. */
@@ -315,10 +334,49 @@ interface MarkdownComponentProps<N> {
  */
 type MarkdownComponent<N> = (props: MarkdownComponentProps<N>) => ReactNode;
 /**
- * The overridable block-level components, keyed by mdast node type and typed to
- * the matching node. Inline marks (bold, italic, code, links) are styled through
- * the {@link MarkdownTheme} rather than as components, because inline content
- * must collapse into a single wrapping flow to be measured exactly.
+ * The context passed to an inline override. It carries the active inline format
+ * (so an override can match the surrounding type) and the helpers to build runs
+ * that stay exactly measurable.
+ */
+interface InlineRenderContext {
+  readonly theme: MarkdownTheme;
+  /** The composed inline format at this node (family, size, weight, colour…). */
+  readonly fmt: InlineFormat;
+  /** Compose a measurable `Font` from the current format plus overrides. */
+  font(overrides?: Partial<InlineFormat>): Font$1;
+  /**
+   * Measure a string's rendered advance in px for a font — to size an inline
+   * box. A text pill reserves `measure(label, font) + horizontalPadding`.
+   */
+  measure(text: string, font: Font$1): number;
+  /** Default-flatten phrasing children into runs, to compose with your own. */
+  runs(nodes: readonly PhrasingContent$1[], fmtOverrides?: Partial<InlineFormat>): RichTextRun[];
+}
+/**
+ * An inline-node override: given the mdast node and the inline context, return
+ * the runs it should flatten to — styled text, an inline box (`{ advance,
+ * content }`), or a mix — or `null` to fall back to the default styling.
+ */
+type InlineComponent<N> = (node: N, ctx: InlineRenderContext) => RichTextRun[] | null;
+/**
+ * Inline-node overrides, keyed by mdast inline type. The index signature admits
+ * custom inline tokens (from a remark plugin) beyond the named ones.
+ */
+interface InlineComponents {
+  text?: InlineComponent<Text$1>;
+  strong?: InlineComponent<Strong>;
+  emphasis?: InlineComponent<Emphasis>;
+  delete?: InlineComponent<Delete>;
+  inlineCode?: InlineComponent<InlineCode>;
+  link?: InlineComponent<Link$1>;
+  [type: string]: InlineComponent<any> | undefined;
+}
+/**
+ * The overridable components. Block-level marks are keyed by mdast node type and
+ * typed to the matching node. Inline marks (bold, italic, code, links) are
+ * styled through the {@link MarkdownTheme} by default, but `inline` lets you
+ * override how an inline node flattens into runs — including a measured inline
+ * box (`{ advance, content }`), the inline twin of mugen's `Escape`.
  */
 interface MarkdownComponents {
   paragraph?: MarkdownComponent<Paragraph$1>;
@@ -330,8 +388,13 @@ interface MarkdownComponents {
   table?: MarkdownComponent<Table$1>;
   image?: MarkdownComponent<Image$1>;
   html?: MarkdownComponent<Html$1>;
+  /** Inline-node overrides (see {@link InlineComponents}). */
+  inline?: InlineComponents;
 }
-type ResolvedMarkdownComponents = Required<MarkdownComponents>;
+/** Block components resolve to defaults; `inline` stays optional. */
+type ResolvedMarkdownComponents = Required<Omit<MarkdownComponents, 'inline'>> & {
+  inline?: InlineComponents;
+};
 /**
  * Identity helper for authoring a typed component set with full inference and
  * `node` narrowing per key:
@@ -369,6 +432,13 @@ declare function renderMarkdown(source: string, options?: RenderMarkdownOptions)
 interface MarkdownProps extends RenderMarkdownOptions {
   /** The markdown source to render. */
   source: string;
+  /**
+   * Fade just-arrived text in as the source streams. The DOM still commits and
+   * lays out instantly (heights stay exact); a veil over new characters
+   * dissolves, which reads as a fade-in. Leaving it on for a settled block is
+   * free. Honours `prefers-reduced-motion`.
+   */
+  fade?: boolean;
 }
 /**
  * Render markdown as a tree of mugen primitives.
@@ -496,6 +566,18 @@ interface TableBlockProps<C extends string = string> {
 /** A measurable GFM-table primitive with aligned, content-proportional columns. */
 declare const TableBlock: <C extends string = string>(props: TableBlockProps<C>) => ReactElement;
 //#endregion
+//#region src/primitives/fade.d.ts
+interface FadeMarkdownProps {
+  /** The rendered markdown subtree to veil. */
+  children?: ReactNode;
+}
+/**
+ * Wraps a measured markdown subtree with a streaming fade-in canvas. Its height
+ * is exactly the subtree's height — the canvas overlay is out of flow and never
+ * measured.
+ */
+declare const FadeMarkdown: (props: FadeMarkdownProps) => ReactElement;
+//#endregion
 //#region src/highlight/languages.d.ts
 /**
  * Language profiles for the built-in tokenizer. A profile is a small data
@@ -537,4 +619,4 @@ declare function registerLanguage(names: string | readonly string[], p: Language
 /** The profile for a fence language, or `null` when the language is unknown. */
 declare function profileFor(lang: string | undefined): LanguageProfile | null;
 //#endregion
-export { type Blockquote, type BoxProps, type Code, CodeBlock, type CodeBlockHeader, type CodeBlockProps, type CodeTokenColors, type DeepPartial, type Font, HStack, type HStackProps, type Heading, type Html, type Image, type InlineFormat, type InlineTextOptions, type LanguageProfile, type Link, type List, type ListItem, Markdown, type MarkdownComponent, type MarkdownComponentProps, type MarkdownComponents, type MarkdownParseOptions, type MarkdownProps, type MarkdownRenderContext, type MarkdownTheme, type Paragraph, type PhrasingContent, type PrimitiveComponent, type RenderMarkdownOptions, type ResolvedMarkdownComponents, RichText, type RichTextProps, type RichTextRun, type Root, type RootContent, type Table, TableBlock, type TableBlockProps, type TableCell, type TableRow, Text, type TextProps, type ThematicBreak, type TokenType, VStack, type VStackProps, baseFormat, clearParseCache, clearRichTextCache, composeFont, defaultComponents, defaultTheme, defaultTokenColors, defineMarkdownComponents, definePrimitive, flattenInline, parseMarkdown, profileFor, registerLanguage, renderMarkdown, resolveTheme };
+export { type Blockquote, type BoxProps, type Code, CodeBlock, type CodeBlockHeader, type CodeBlockProps, type CodeTokenColors, type DeepPartial, FadeMarkdown, type Font, HStack, type HStackProps, type Heading, type Html, type Image, type InlineComponent, type InlineComponents, type InlineFormat, type InlineRenderContext, type InlineTextOptions, type LanguageProfile, type Link, type List, type ListItem, Markdown, type MarkdownComponent, type MarkdownComponentProps, type MarkdownComponents, type MarkdownParseOptions, type MarkdownProps, type MarkdownRenderContext, type MarkdownTheme, type Paragraph, type PhrasingContent, type PrimitiveComponent, type RenderMarkdownOptions, type ResolvedMarkdownComponents, RichText, type RichTextProps, type RichTextRun, type Root, type RootContent, type Table, TableBlock, type TableBlockProps, type TableCell, type TableRow, Text, type TextProps, type ThematicBreak, type TokenType, VStack, type VStackProps, baseFormat, clearParseCache, clearRichTextCache, composeFont, defaultComponents, defaultTheme, defaultTokenColors, defineMarkdownComponents, definePrimitive, flattenInline, measureInline, parseMarkdown, profileFor, registerLanguage, renderMarkdown, resolveTheme };

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { CSSProperties, JSX, ReactElement, ReactNode } from "react";
 import { BoxProps, Font, Font as Font$1, HStack, HStackProps, MeasurableStyle, PrimitiveComponent, SafeClassName, Text, TextProps, VStack, VStackProps, definePrimitive } from "@wingleeio/mugen";
 import { ParserOptions } from "@incremark/core";
-import { Blockquote, Blockquote as Blockquote$1, Code, Code as Code$1, Heading, Heading as Heading$1, Html, Html as Html$1, Image, Image as Image$1, Link, List, List as List$1, ListItem, Paragraph, Paragraph as Paragraph$1, PhrasingContent, PhrasingContent as PhrasingContent$1, Root, Root as Root$1, RootContent, RootContent as RootContent$1, Table, Table as Table$1, TableCell, TableRow, ThematicBreak, ThematicBreak as ThematicBreak$1 } from "mdast";
+import { Blockquote, Blockquote as Blockquote$1, Code, Code as Code$1, Delete, Emphasis, Heading, Heading as Heading$1, Html, Html as Html$1, Image, Image as Image$1, InlineCode, Link, Link as Link$1, List, List as List$1, ListItem, Paragraph, Paragraph as Paragraph$1, PhrasingContent, PhrasingContent as PhrasingContent$1, Root, Root as Root$1, RootContent, RootContent as RootContent$1, Strong, Table, Table as Table$1, TableCell, TableRow, Text as Text$1, ThematicBreak, ThematicBreak as ThematicBreak$1 } from "mdast";
 
 //#region src/parse.d.ts
 /**
@@ -175,8 +175,19 @@ declare function resolveTheme(theme?: DeepPartial<MarkdownTheme>): MarkdownTheme
  * rich-inline layout) and the painted spans use the identical fonts.
  */
 interface RichTextRun {
-  /** The run's text. Ignored when `break` is set. */
-  text: string;
+  /** The run's text. Ignored when `break` or `advance` is set. */
+  text?: string;
+  /**
+   * Render this run as an **inline box** — the inline analogue of mugen's
+   * `Escape`: it reserves exactly `advance` px in the flow (via pretext's
+   * `extraWidth`) and paints {@link content}, whatever it is, without measuring
+   * its insides. The flow wraps it as one non-breaking atom. The caller owns the
+   * contract: `content` must render exactly `advance` px wide and no taller than
+   * the line (use the exported `measureInline` to size text-based boxes).
+   */
+  advance?: number;
+  /** The painted content of an inline box (see {@link advance}). */
+  content?: ReactNode;
   /** Measurable font for this run; falls back to the `<RichText font>` prop. */
   font?: Font$1;
   color?: string;
@@ -217,6 +228,12 @@ interface RichTextProps<C extends string = string> {
  * performs over the rendered spans, so the analytic height matches the paint.
  */
 declare const RichText: <C extends string = string>(props: RichTextProps<C>) => ReactElement;
+/**
+ * Measure a string's rendered advance in px for a given measurable font — the
+ * same ruler `RichText` measures with. Use it to size an inline box: a text
+ * "pill" reserves `measureInline(label, font) + horizontalPadding`.
+ */
+declare function measureInline(text: string, font: Font$1): number;
 /** Drop the rich-inline prepare cache (tests / memory pressure). */
 declare function clearRichTextCache(): void;
 //#endregion
@@ -252,9 +269,11 @@ declare function composeFont(fmt: InlineFormat): Font$1;
 /**
  * Flatten phrasing content into styled runs. Recursive over the inline marks;
  * the result feeds a single `<RichText>` so the whole paragraph wraps as one
- * flow and measures exactly.
+ * flow and measures exactly. An `inline` override map can replace how any node
+ * type flattens — returning its own runs (e.g. a measured inline box) or `null`
+ * to fall through to the default.
  */
-declare function flattenInline(nodes: readonly PhrasingContent$1[], fmt: InlineFormat, theme: MarkdownTheme, out: RichTextRun[]): void;
+declare function flattenInline(nodes: readonly PhrasingContent$1[], fmt: InlineFormat, theme: MarkdownTheme, out: RichTextRun[], inline?: InlineComponents): void;
 //#endregion
 //#region src/types.d.ts
 /** Options for building a body/heading inline-text (`RichText`) element. */
@@ -315,10 +334,49 @@ interface MarkdownComponentProps<N> {
  */
 type MarkdownComponent<N> = (props: MarkdownComponentProps<N>) => ReactNode;
 /**
- * The overridable block-level components, keyed by mdast node type and typed to
- * the matching node. Inline marks (bold, italic, code, links) are styled through
- * the {@link MarkdownTheme} rather than as components, because inline content
- * must collapse into a single wrapping flow to be measured exactly.
+ * The context passed to an inline override. It carries the active inline format
+ * (so an override can match the surrounding type) and the helpers to build runs
+ * that stay exactly measurable.
+ */
+interface InlineRenderContext {
+  readonly theme: MarkdownTheme;
+  /** The composed inline format at this node (family, size, weight, colour…). */
+  readonly fmt: InlineFormat;
+  /** Compose a measurable `Font` from the current format plus overrides. */
+  font(overrides?: Partial<InlineFormat>): Font$1;
+  /**
+   * Measure a string's rendered advance in px for a font — to size an inline
+   * box. A text pill reserves `measure(label, font) + horizontalPadding`.
+   */
+  measure(text: string, font: Font$1): number;
+  /** Default-flatten phrasing children into runs, to compose with your own. */
+  runs(nodes: readonly PhrasingContent$1[], fmtOverrides?: Partial<InlineFormat>): RichTextRun[];
+}
+/**
+ * An inline-node override: given the mdast node and the inline context, return
+ * the runs it should flatten to — styled text, an inline box (`{ advance,
+ * content }`), or a mix — or `null` to fall back to the default styling.
+ */
+type InlineComponent<N> = (node: N, ctx: InlineRenderContext) => RichTextRun[] | null;
+/**
+ * Inline-node overrides, keyed by mdast inline type. The index signature admits
+ * custom inline tokens (from a remark plugin) beyond the named ones.
+ */
+interface InlineComponents {
+  text?: InlineComponent<Text$1>;
+  strong?: InlineComponent<Strong>;
+  emphasis?: InlineComponent<Emphasis>;
+  delete?: InlineComponent<Delete>;
+  inlineCode?: InlineComponent<InlineCode>;
+  link?: InlineComponent<Link$1>;
+  [type: string]: InlineComponent<any> | undefined;
+}
+/**
+ * The overridable components. Block-level marks are keyed by mdast node type and
+ * typed to the matching node. Inline marks (bold, italic, code, links) are
+ * styled through the {@link MarkdownTheme} by default, but `inline` lets you
+ * override how an inline node flattens into runs — including a measured inline
+ * box (`{ advance, content }`), the inline twin of mugen's `Escape`.
  */
 interface MarkdownComponents {
   paragraph?: MarkdownComponent<Paragraph$1>;
@@ -330,8 +388,13 @@ interface MarkdownComponents {
   table?: MarkdownComponent<Table$1>;
   image?: MarkdownComponent<Image$1>;
   html?: MarkdownComponent<Html$1>;
+  /** Inline-node overrides (see {@link InlineComponents}). */
+  inline?: InlineComponents;
 }
-type ResolvedMarkdownComponents = Required<MarkdownComponents>;
+/** Block components resolve to defaults; `inline` stays optional. */
+type ResolvedMarkdownComponents = Required<Omit<MarkdownComponents, 'inline'>> & {
+  inline?: InlineComponents;
+};
 /**
  * Identity helper for authoring a typed component set with full inference and
  * `node` narrowing per key:
@@ -369,6 +432,13 @@ declare function renderMarkdown(source: string, options?: RenderMarkdownOptions)
 interface MarkdownProps extends RenderMarkdownOptions {
   /** The markdown source to render. */
   source: string;
+  /**
+   * Fade just-arrived text in as the source streams. The DOM still commits and
+   * lays out instantly (heights stay exact); a veil over new characters
+   * dissolves, which reads as a fade-in. Leaving it on for a settled block is
+   * free. Honours `prefers-reduced-motion`.
+   */
+  fade?: boolean;
 }
 /**
  * Render markdown as a tree of mugen primitives.
@@ -496,6 +566,18 @@ interface TableBlockProps<C extends string = string> {
 /** A measurable GFM-table primitive with aligned, content-proportional columns. */
 declare const TableBlock: <C extends string = string>(props: TableBlockProps<C>) => ReactElement;
 //#endregion
+//#region src/primitives/fade.d.ts
+interface FadeMarkdownProps {
+  /** The rendered markdown subtree to veil. */
+  children?: ReactNode;
+}
+/**
+ * Wraps a measured markdown subtree with a streaming fade-in canvas. Its height
+ * is exactly the subtree's height — the canvas overlay is out of flow and never
+ * measured.
+ */
+declare const FadeMarkdown: (props: FadeMarkdownProps) => ReactElement;
+//#endregion
 //#region src/highlight/languages.d.ts
 /**
  * Language profiles for the built-in tokenizer. A profile is a small data
@@ -537,4 +619,4 @@ declare function registerLanguage(names: string | readonly string[], p: Language
 /** The profile for a fence language, or `null` when the language is unknown. */
 declare function profileFor(lang: string | undefined): LanguageProfile | null;
 //#endregion
-export { type Blockquote, type BoxProps, type Code, CodeBlock, type CodeBlockHeader, type CodeBlockProps, type CodeTokenColors, type DeepPartial, type Font, HStack, type HStackProps, type Heading, type Html, type Image, type InlineFormat, type InlineTextOptions, type LanguageProfile, type Link, type List, type ListItem, Markdown, type MarkdownComponent, type MarkdownComponentProps, type MarkdownComponents, type MarkdownParseOptions, type MarkdownProps, type MarkdownRenderContext, type MarkdownTheme, type Paragraph, type PhrasingContent, type PrimitiveComponent, type RenderMarkdownOptions, type ResolvedMarkdownComponents, RichText, type RichTextProps, type RichTextRun, type Root, type RootContent, type Table, TableBlock, type TableBlockProps, type TableCell, type TableRow, Text, type TextProps, type ThematicBreak, type TokenType, VStack, type VStackProps, baseFormat, clearParseCache, clearRichTextCache, composeFont, defaultComponents, defaultTheme, defaultTokenColors, defineMarkdownComponents, definePrimitive, flattenInline, parseMarkdown, profileFor, registerLanguage, renderMarkdown, resolveTheme };
+export { type Blockquote, type BoxProps, type Code, CodeBlock, type CodeBlockHeader, type CodeBlockProps, type CodeTokenColors, type DeepPartial, FadeMarkdown, type Font, HStack, type HStackProps, type Heading, type Html, type Image, type InlineComponent, type InlineComponents, type InlineFormat, type InlineRenderContext, type InlineTextOptions, type LanguageProfile, type Link, type List, type ListItem, Markdown, type MarkdownComponent, type MarkdownComponentProps, type MarkdownComponents, type MarkdownParseOptions, type MarkdownProps, type MarkdownRenderContext, type MarkdownTheme, type Paragraph, type PhrasingContent, type PrimitiveComponent, type RenderMarkdownOptions, type ResolvedMarkdownComponents, RichText, type RichTextProps, type RichTextRun, type Root, type RootContent, type Table, TableBlock, type TableBlockProps, type TableCell, type TableRow, Text, type TextProps, type ThematicBreak, type TokenType, VStack, type VStackProps, baseFormat, clearParseCache, clearRichTextCache, composeFont, defaultComponents, defaultTheme, defaultTokenColors, defineMarkdownComponents, definePrimitive, flattenInline, measureInline, parseMarkdown, profileFor, registerLanguage, renderMarkdown, resolveTheme };