@wingleeio/mugen-markdown 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,498 @@
+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";
+
+//#region src/parse.d.ts
+/**
+ * Markdown parsing options — a curated subset of incremark's `ParserOptions`.
+ * `gfm` (tables, task lists, strikethrough, autolinks) is on by default because
+ * it's what people mean by "markdown" today.
+ */
+interface MarkdownParseOptions {
+  /** GitHub-Flavored Markdown: tables, task lists, strikethrough, autolinks. Default `true`. */
+  gfm?: boolean;
+  /** `$…$` / `$$…$$` math. Off by default (needs a math-capable component override to render). */
+  math?: ParserOptions['math'];
+  /** `:::` directive containers. Off by default. */
+  containers?: ParserOptions['containers'];
+}
+/**
+ * Parse markdown into an mdast `Root` with incremark, memoized by
+ * `(source, options)` and parsed **incrementally** when the source grows.
+ *
+ * Pure and synchronous — safe to call inside mugen's measure walk. Growing the
+ * same source (a streaming row) appends only the new text to a retained parser;
+ * an unchanged source is served from the AST cache; a non-extending change parses
+ * fresh.
+ */
+declare function parseMarkdown(source: string, options?: MarkdownParseOptions): Root$1;
+/** Drop the parse caches and retained parsers (tests / memory pressure). */
+declare function clearParseCache(): void;
+//#endregion
+//#region src/highlight/types.d.ts
+/**
+ * Token vocabulary for the built-in code-block highlighter. The set is small on
+ * purpose: highlighting is purely cosmetic paint layered over already-laid-out
+ * text, so a coarse classification that is cheap to compute incrementally beats
+ * a grammar-exact one that would need a real parser.
+ */
+type TokenType = 'keyword' | 'string' | 'comment' | 'number' | 'constant' | 'function' | 'type' | 'property' | 'operator' | 'punctuation';
+/**
+ * One colour per token type. A value of `'currentColor'` paints that token in
+ * the block's own text colour (whatever `color` computes to on the `<code>`),
+ * which is how a token type opts out of special colouring.
+ */
+type CodeTokenColors = Record<TokenType, string>;
+/**
+ * Default palette: mid-tone colours chosen to stay legible on both light and
+ * dark page backgrounds, since the default theme inherits the page colours.
+ */
+declare const defaultTokenColors: CodeTokenColors;
+//#endregion
+//#region src/theme.d.ts
+/**
+ * The markdown theme. Every value that affects a box's height — fonts, line
+ * heights, paddings, gaps — lives here as a concrete number/family, because the
+ * dispatcher bakes them into primitive props (the measure walk only sees props,
+ * never React context). Colours and other purely-cosmetic values live here too,
+ * for one-stop styling.
+ *
+ * Fonts are given as a **family** plus sizes/weights, not as full `Font`
+ * shorthands, so the dispatcher can compose inline variants (bold inside a
+ * heading, code inside a paragraph) without you spelling out every combination.
+ * Families must be measurable — a named web font (`"Inter"`) or a canvas-safe
+ * generic (`"sans-serif"`, `"monospace"`); `"system-ui"` is rejected at measure
+ * time because its canvas metrics drift from what CSS paints.
+ */
+interface MarkdownTheme {
+  /** Body text family, e.g. `"Inter"` or `"sans-serif"`. */
+  fontFamily: string;
+  /** Monospace family for code, e.g. `"JetBrains Mono"` or `"monospace"`. */
+  monoFamily: string;
+  /** Body font size in px. */
+  fontSize: number;
+  /** Body line height in px. */
+  lineHeight: number;
+  /** Default text colour (any CSS colour; `"inherit"` follows the surrounding CSS). */
+  color: string;
+  /** Vertical gap between adjacent blocks, in px. */
+  blockGap: number;
+  heading: {
+    weight: number;
+    color: string; /** Font size per heading depth, in px. */
+    sizes: Record<1 | 2 | 3 | 4 | 5 | 6, number>; /** Line height per heading depth, in px. */
+    lineHeights: Record<1 | 2 | 3 | 4 | 5 | 6, number>;
+  };
+  /** Weight applied to `**strong**` text. */
+  strongWeight: number;
+  /** Whether `*emphasis*` renders italic (needs an italic face of the family). */
+  emphasisItalic: boolean;
+  link: {
+    color: string;
+    underline: boolean;
+  };
+  inlineCode: {
+    color: string;
+    background: string; /** Inline-code size as a fraction of the surrounding text size. */
+    sizeScale: number;
+  };
+  code: {
+    fontSize: number;
+    lineHeight: number;
+    padding: number;
+    background: string;
+    color: string;
+    radius: number;
+    /**
+     * Token palette for the built-in non-blocking canvas highlighter, or
+     * `false` to disable highlighting. Colours are paint-only — they can never
+     * change a block's measured height.
+     */
+    highlight: CodeTokenColors | false;
+  };
+  blockquote: {
+    padding: number;
+    gap: number;
+    borderWidth: number;
+    borderColor: string;
+    color: string;
+  };
+  list: {
+    /** Gap between list items, in px. */gap: number; /** Width of the marker column (bullet / number), in px. */
+    indent: number;
+    markerColor: string;
+  };
+  table: {
+    /** Uniform cell padding in px (uniform so the analytic height stays exact). */cellPadding: number; /** Hairline between rows (and the outer ring) in px; 0 disables both. */
+    gap: number;
+    headerWeight: number; /** Background behind the header row. */
+    headerBackground: string; /** Hairline / outer-ring colour. */
+    borderColor: string; /** Corner radius in px (clip only — no height impact). */
+    radius: number;
+  };
+  rule: {
+    thickness: number;
+    color: string;
+    gap: number;
+  };
+  /**
+   * Images have no intrinsic measurable height, so the default `image` component
+   * renders a fixed-height box. Override the `image` component for real layout.
+   */
+  image: {
+    placeholderHeight: number;
+    color: string;
+  };
+}
+type DeepPartial<T> = T extends (infer U)[] ? DeepPartial<U>[] : T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T;
+declare const defaultTheme: MarkdownTheme;
+/** Merge a partial theme over the defaults into a fully-resolved theme. */
+declare function resolveTheme(theme?: DeepPartial<MarkdownTheme>): MarkdownTheme;
+//#endregion
+//#region src/primitives/rich-text.d.ts
+/**
+ * One styled span of inline text. A `RichText` is a sequence of runs that wrap
+ * together as a single flowing paragraph — the thing markdown inline content
+ * (bold, italic, code, links inside a sentence) needs and that a single-font
+ * `<Text>` can't express. Each run carries its own measurable `font`, so the
+ * mixed fonts on a line are measured exactly (via `@chenglou/pretext`'s
+ * rich-inline layout) and the painted spans use the identical fonts.
+ */
+interface RichTextRun {
+  /** The run's text. Ignored when `break` is set. */
+  text: string;
+  /** Measurable font for this run; falls back to the `<RichText font>` prop. */
+  font?: Font$1;
+  color?: string;
+  /** Background (e.g. inline-code chip). Cosmetic — does not affect height. */
+  background?: string;
+  /** CSS `text-decoration` (e.g. `"underline"`, `"line-through"`). Cosmetic. */
+  decoration?: string;
+  /** Render as a link with this `href` (sets the tag to `<a>` unless `as` is given). */
+  href?: string;
+  title?: string;
+  onClick?: (e: unknown) => void;
+  /** The element tag for this run. Defaults to `a` when `href` is set, else `span`. */
+  as?: keyof JSX.IntrinsicElements;
+  /** Forbid line breaks inside this run. */
+  noBreak?: boolean;
+  letterSpacing?: number;
+  className?: string;
+  /** A hard line break (renders `<br>`, forces a new line in the measure). */
+  break?: boolean;
+}
+interface RichTextProps<C extends string = string> {
+  /** The inline runs to flow together. */
+  runs: RichTextRun[];
+  /** Line height in px — the height of every wrapped line. Required. */
+  lineHeight: number;
+  /** Fallback font for runs that don't set their own. */
+  font?: Font$1;
+  color?: string;
+  align?: CSSProperties['textAlign'];
+  /** Inline styles, minus spacing/sizing (owned by the layout). */
+  style?: MeasurableStyle;
+  className?: SafeClassName<C>;
+}
+/**
+ * A measurable rich inline-text primitive: a paragraph of mixed-font runs that
+ * wrap as one flow. Its height is `lines × lineHeight`, where `lines` comes from
+ * pretext's rich-inline layout at the row's width — the same layout the browser
+ * performs over the rendered spans, so the analytic height matches the paint.
+ */
+declare const RichText: <C extends string = string>(props: RichTextProps<C>) => ReactElement;
+/** Drop the rich-inline prepare cache (tests / memory pressure). */
+declare function clearRichTextCache(): void;
+//#endregion
+//#region src/inline.d.ts
+/**
+ * The mutable styling state threaded through the inline walk. Markdown inline
+ * marks (`**`, `*`, `` ` ``, `[]()`) nest, so we carry the composed format down
+ * and emit a styled run at each text leaf. Fonts are composed here — a `<strong>`
+ * inside a heading produces one bold run at the heading's size — which is what
+ * lets the rich-inline measurement see every mixed font exactly.
+ */
+interface InlineFormat {
+  family: string;
+  monoFamily: string;
+  size: number;
+  weight: number;
+  italic: boolean;
+  mono: boolean;
+  underline: boolean;
+  strike: boolean;
+  color?: string;
+  background?: string;
+  href?: string;
+}
+/** A base format for body text at a given size/weight/colour. */
+declare function baseFormat(theme: MarkdownTheme, opts?: {
+  size?: number;
+  weight?: number;
+  color?: string;
+}): InlineFormat;
+/** Compose a measurable `Font` shorthand from a format. */
+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.
+ */
+declare function flattenInline(nodes: readonly PhrasingContent$1[], fmt: InlineFormat, theme: MarkdownTheme, out: RichTextRun[]): void;
+//#endregion
+//#region src/types.d.ts
+/** Options for building a body/heading inline-text (`RichText`) element. */
+interface InlineTextOptions {
+  /** Font size in px (defaults to the theme body size). */
+  size?: number;
+  /** Font weight (defaults to 400). */
+  weight?: number;
+  /** Line height in px (defaults to the theme body line height). */
+  lineHeight?: number;
+  color?: string;
+  align?: CSSProperties['textAlign'];
+}
+/**
+ * The context threaded to every markdown component. It carries the resolved
+ * theme and the helpers a component needs to recurse — all of which return
+ * **mugen primitives**, so whatever a component builds with them stays
+ * measurable by mugen's tree walker.
+ */
+interface MarkdownRenderContext {
+  /** The fully-resolved theme. */
+  readonly theme: MarkdownTheme;
+  /** The resolved component set (defaults merged with user overrides). */
+  readonly components: ResolvedMarkdownComponents;
+  /** Render a list of block nodes as a vertically-stacked subtree (gap defaults to `theme.blockGap`). */
+  renderBlocks(nodes: readonly RootContent$1[], gap?: number): ReactNode;
+  /** Render a single block node, dispatching to its component. */
+  renderBlock(node: RootContent$1, key?: string | number): ReactNode;
+  /** The default inner rendering for a node (inline `RichText`, or rendered child blocks). */
+  renderChildren(node: RootContent$1): ReactNode;
+  /** Flatten phrasing content into styled `RichText` runs at an optional base format. */
+  inlineRuns(nodes: readonly PhrasingContent$1[], base?: Partial<InlineFormat>): RichTextRun[];
+  /** Build a `RichText` element from phrasing content (the inline pipeline). */
+  inlineText(nodes: readonly PhrasingContent$1[], opts?: InlineTextOptions): ReactNode;
+  /**
+   * Memoize a rendered element by its `node`'s content, so streaming re-renders
+   * reuse it (React then bails out). `variant` distinguishes renderings of the
+   * same node that differ by sibling context — e.g. a list item's index/marker
+   * or a table cell's column. Use it in custom `list`/`table` components so their
+   * already-finished items/cells don't re-render while a later one streams in.
+   */
+  memo(node: object, variant: string, build: () => ReactNode): ReactNode;
+}
+/**
+ * Props every markdown component receives. `node` is the typed mdast node,
+ * `children` is what the default component would render inside (so an override
+ * can wrap it), and `ctx` exposes the recursion + theme helpers.
+ */
+interface MarkdownComponentProps<N> {
+  node: N;
+  children: ReactNode;
+  ctx: MarkdownRenderContext;
+}
+/**
+ * A markdown component. It must return mugen primitives (or hook-free
+ * compositions of them) so mugen's walker can measure the row — use the
+ * primitives re-exported from this package and the `ctx` helpers.
+ */
+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.
+ */
+interface MarkdownComponents {
+  paragraph?: MarkdownComponent<Paragraph$1>;
+  heading?: MarkdownComponent<Heading$1>;
+  thematicBreak?: MarkdownComponent<ThematicBreak$1>;
+  blockquote?: MarkdownComponent<Blockquote$1>;
+  list?: MarkdownComponent<List$1>;
+  code?: MarkdownComponent<Code$1>;
+  table?: MarkdownComponent<Table$1>;
+  image?: MarkdownComponent<Image$1>;
+  html?: MarkdownComponent<Html$1>;
+}
+type ResolvedMarkdownComponents = Required<MarkdownComponents>;
+/**
+ * Identity helper for authoring a typed component set with full inference and
+ * `node` narrowing per key:
+ *
+ * ```tsx
+ * const components = defineMarkdownComponents({
+ *   heading: ({ node, children }) => // node is Heading, node.depth is 1..6
+ *     <VStack>{children}</VStack>,
+ * });
+ * ```
+ */
+declare function defineMarkdownComponents(components: MarkdownComponents): MarkdownComponents;
+//#endregion
+//#region src/components.d.ts
+declare const defaultComponents: ResolvedMarkdownComponents;
+//#endregion
+//#region src/render.d.ts
+interface RenderMarkdownOptions {
+  /** Theme overrides (deep-merged over the defaults). */
+  theme?: DeepPartial<MarkdownTheme>;
+  /** Block-component overrides. */
+  components?: MarkdownComponents;
+  /** Parser options (gfm, math, containers). */
+  parserOptions?: MarkdownParseOptions;
+}
+/**
+ * Parse `source` and render it into a tree of mugen primitives. The result is
+ * pure and hook-free, so it can be returned straight from a `<MugenVList>`
+ * `render` and measured by the walker. Memoization of parsing/theme/components
+ * keeps the measure and render passes cheap.
+ */
+declare function renderMarkdown(source: string, options?: RenderMarkdownOptions): ReactNode;
+//#endregion
+//#region src/markdown.d.ts
+interface MarkdownProps extends RenderMarkdownOptions {
+  /** The markdown source to render. */
+  source: string;
+}
+/**
+ * Render markdown as a tree of mugen primitives.
+ *
+ * `<Markdown>` is a **pure, hook-free** component: it parses `source` with
+ * incremark and maps the AST to mugen primitives, producing the identical tree
+ * in mugen's measure walk and in React's render. Drop it straight into a
+ * `<MugenVList>` `render` and every row — on- or off-screen — gets an exact,
+ * analytic height.
+ *
+ * ```tsx
+ * <MugenVList
+ *   instance={list}
+ *   getKey={(m) => m.id}
+ *   render={(m) => <Markdown source={m.body} />}
+ * />
+ * ```
+ *
+ * Extend it with typed, per-node `components` (built from the same primitives)
+ * and a deep-partial `theme`.
+ */
+declare function Markdown(props: MarkdownProps): ReactNode;
+declare namespace Markdown {
+  var displayName: string;
+}
+//#endregion
+//#region src/primitives/code-block.d.ts
+/**
+ * A fenced code block. Code does not wrap — long lines scroll horizontally — so
+ * its height is simply `lineCount × lineHeight + 2 × padding`, independent of the
+ * row width. That makes it trivially and exactly measurable.
+ *
+ * Syntax highlighting is layered on as pure paint, never layout: the `<code>`
+ * text renders immediately (plain, selectable, accessible), the language is
+ * tokenized off the critical path in time-sliced chunks, and token colours are
+ * painted onto canvas tiles overlaying the text — at which point the DOM text
+ * turns `color: transparent` in the same frame. Highlighting therefore can't
+ * block first paint and can't ever change the measured height.
+ */
+interface CodeBlockProps<C extends string = string> {
+  /** Raw code text. Newlines determine the line count. */
+  value: string;
+  /** Info-string language, if any (drives the built-in highlighter / labels). */
+  lang?: string;
+  /** Monospace font. Required. */
+  font: Font$1;
+  /** Line height in px. Required. */
+  lineHeight: number;
+  /** Uniform padding in px (chrome counted in the height). */
+  padding?: number;
+  background?: string;
+  color?: string;
+  radius?: number;
+  /**
+   * Token-colour overrides for the built-in canvas highlighter, or `false` to
+   * disable it. Defaults to {@link defaultTokenColors}; only languages with a
+   * registered profile are highlighted either way.
+   */
+  highlight?: Partial<CodeTokenColors> | false;
+  style?: MeasurableStyle;
+  className?: SafeClassName<C>;
+}
+/** A measurable fenced-code primitive (no wrapping; height from line count). */
+declare const CodeBlock: <C extends string = string>(props: CodeBlockProps<C>) => ReactElement;
+//#endregion
+//#region src/primitives/table-block.d.ts
+/**
+ * A GFM table that *looks* like a table and is still exactly measurable.
+ *
+ * Every row shares one set of column widths, proportional to each column's
+ * max-content width across all rows (floored so a tiny column stays
+ * readable). Cells paint as `flex: ratio ratio 0` — with basis 0, flexbox
+ * resolves each column to `width × ratio / Σratios`, which is the same
+ * arithmetic the measure runs, so the heights agree at any width and the
+ * columns align across rows.
+ *
+ * Chrome is height-neutral by construction: row hairlines are real
+ * `divider`-px elements (counted in the height), while the outer ring is an
+ * inset box-shadow and the corner radius is pure overflow clipping — neither
+ * consumes width or height the walker can't see.
+ */
+interface TableBlockProps<C extends string = string> {
+  /** Cell content per row, header row first. Rows may be ragged. */
+  rows: ReactNode[][];
+  /** Uniform cell padding in px (counted in the height). */
+  cellPadding: number;
+  /** Hairline between rows and the outer ring, in px. 0 disables both. */
+  divider: number;
+  /** Hairline / ring colour. */
+  borderColor: string;
+  /** Background behind the header row. */
+  headerBackground: string;
+  /** Corner radius in px (clip only — no height impact). */
+  radius: number;
+  style?: MeasurableStyle;
+  className?: SafeClassName<C>;
+}
+/** A measurable GFM-table primitive with aligned, content-proportional columns. */
+declare const TableBlock: <C extends string = string>(props: TableBlockProps<C>) => ReactElement;
+//#endregion
+//#region src/highlight/languages.d.ts
+/**
+ * Language profiles for the built-in tokenizer. A profile is a small data
+ * description — comment markers, string delimiters, keyword sets, and a few
+ * classification heuristics — interpreted by one shared scanner, so adding a
+ * language is a handful of lines rather than a grammar.
+ */
+interface LanguageProfile {
+  /** Markers that comment to end-of-line (`//`, `#`, `--`). */
+  lineComments: readonly string[];
+  /** Open/close pairs that may span lines (C-style block comments, `<!-- … -->`). */
+  blockComments: readonly (readonly [string, string])[];
+  /** Single-char string delimiters; an unclosed one ends at end-of-line. */
+  quotes: readonly string[];
+  /** String delimiters that carry across lines (`` ` ``, `'''`, `"""`). */
+  multilineQuotes: readonly string[];
+  keywords: ReadonlySet<string>;
+  constants: ReadonlySet<string>;
+  /** Colour Capitalised identifiers as types. */
+  capitalTypes: boolean;
+  /** Extra identifier characters beyond `[A-Za-z0-9_$]` (e.g. `-` for CSS). */
+  identExtra: string;
+  /** Lower-case words before keyword/constant lookup (SQL, Dockerfile). */
+  caseInsensitive?: boolean;
+  /** A string immediately followed by `:` is a property key (JSON). */
+  stringKeys?: boolean;
+  /** An identifier immediately followed by `:` is a property key. */
+  colonProps?: boolean;
+  /** An identifier followed by `=` (not `==`) is a property/attribute name. */
+  eqProps?: boolean;
+  /** An identifier right after `<` or `</` is a tag name (HTML/XML). */
+  tags?: boolean;
+}
+/**
+ * Register a profile under one or more fence info-string names (lower-cased).
+ * Use this to add or override languages for the built-in highlighter.
+ */
+declare function registerLanguage(names: string | readonly string[], p: LanguageProfile): void;
+/** 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 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 };