@coderminer/vue-markdown 0.0.0-stage → 1.0.1

package/dist/composables/useMarkdownDocument.d.ts

@@ -0,0 +1,25 @@
+import { ComputedRef, MaybeRefOrGetter, ShallowRef } from 'vue';
+import { MarkdownDiagnostic, MarkdownDocument, MarkdownDocumentOptions, MarkdownLabels, MarkdownNodeComponents, MarkdownRegionComponents, MarkdownTagComponents, TocItem } from '../core/types';
+export type MarkdownStatus = 'idle' | 'pending' | 'ready' | 'error';
+export interface UseMarkdownDocumentReturn {
+    document: ShallowRef<MarkdownDocument | undefined>;
+    toc: ComputedRef<TocItem[]>;
+    status: ShallowRef<MarkdownStatus>;
+    diagnostics: ShallowRef<MarkdownDiagnostic[]>;
+    pipeline: ComputedRef<string>;
+    plugins: ComputedRef<string[]>;
+    /** Tag components contributed by plugins; local props are merged by the host. */
+    resolvedComponents: ComputedRef<MarkdownTagComponents>;
+    /** Semantic node components contributed by plugins. */
+    resolvedNodeComponents: ComputedRef<MarkdownNodeComponents>;
+    /** Structural regions contributed by plugins. */
+    resolvedRegions: ComputedRef<MarkdownRegionComponents>;
+    /** Labels contributed by plugins. */
+    resolvedLabels: ComputedRef<Partial<MarkdownLabels>>;
+    /** Design tokens contributed by plugins. */
+    resolvedTokens: ComputedRef<Record<string, string>>;
+    refresh: () => Promise<void>;
+    /** Clear the published diagnostics without changing the document. */
+    clearDiagnostics: () => void;
+}
+export declare function useMarkdownDocument(source: MaybeRefOrGetter<string>, options?: MaybeRefOrGetter<MarkdownDocumentOptions>): UseMarkdownDocumentReturn;

package/dist/core/adapters.d.ts

@@ -0,0 +1,7 @@
+import { DiagnosticFormatter, MarkdownHighlighter, MarkdownSlugger, MarkdownUrlTransform, MathEngine, MermaidRenderer } from './types';
+export declare function isValidHighlighter(value: unknown): value is MarkdownHighlighter;
+export declare function isValidMathEngine(value: unknown): value is MathEngine;
+export declare function isValidMermaidRenderer(value: unknown): value is MermaidRenderer;
+export declare function isValidDiagnosticFormatter(value: unknown): value is DiagnosticFormatter;
+export declare function isValidSlugger(value: unknown): value is MarkdownSlugger;
+export declare function isValidUrlTransform(value: unknown): value is MarkdownUrlTransform;

package/dist/core/config.d.ts

@@ -0,0 +1,5 @@
+import { MarkdownConfig, MarkdownPreset } from './types';
+/** Merge configuration maps with `next` taking precedence. */
+export declare function mergeMarkdownConfig(base: MarkdownConfig | undefined, next: MarkdownConfig | undefined): MarkdownConfig;
+/** Merge presets; later presets win and plugins are appended in order. */
+export declare function mergeMarkdownPreset(base: MarkdownPreset | undefined, next: MarkdownPreset): MarkdownPreset;

package/dist/core/diagnostics.d.ts

@@ -0,0 +1,9 @@
+import { MarkdownDiagnostic, DiagnosticPhase, SourceRange } from './types';
+export declare function createDiagnostic(code: string, message: string, options?: {
+    severity?: MarkdownDiagnostic['severity'];
+    phase?: DiagnosticPhase;
+    plugin?: string;
+    source?: SourceRange;
+    details?: string;
+}): MarkdownDiagnostic;
+export declare function errorMessage(error: unknown): string;

package/dist/core/finalize.d.ts

@@ -0,0 +1,18 @@
+import { MarkdownDiagnostic, MarkdownDocument, MarkdownDocumentOptions, MarkdownSlugger, PipelineResult } from './types';
+import { ResolvedPlugins } from '../plugins/registry';
+export interface FinalizeDocumentOptions {
+    source: string;
+    result: PipelineResult;
+    options: MarkdownDocumentOptions;
+    plugins: ResolvedPlugins;
+    pipelineName: string;
+    slugger: MarkdownSlugger;
+    idPrefix: string;
+    diagnostics: MarkdownDiagnostic[];
+}
+/**
+ * Turn a pipeline result into the public document model. Both the reactive
+ * composable and static export use this path so filtering, URL policy, heading
+ * IDs, and plugin document transforms cannot diverge.
+ */
+export declare function finalizeMarkdownDocument(input: FinalizeDocumentOptions): MarkdownDocument;

package/dist/core/hast-nodes.d.ts

@@ -0,0 +1,3 @@
+import { MarkdownNode } from './types';
+/** Convert trusted engine HTML into normalized nodes. */
+export declare function htmlToMarkdownNodes(html: string): MarkdownNode[];

package/dist/core/hast-to-nodes.d.ts

@@ -0,0 +1,9 @@
+import { RootContent } from 'hast';
+import { MarkdownNode } from './types';
+/**
+ * Convert an already-parsed trusted hast subtree into normalized nodes.
+ *
+ * This module deliberately has no HTML parser import so adapters that already
+ * produce hast (Shiki) do not pull one into their entry.
+ */
+export declare function hastToMarkdownNodes(nodes: readonly RootContent[]): MarkdownNode[];

package/dist/core/highlight-lines.d.ts

@@ -0,0 +1,8 @@
+import { HighlightLine } from './types';
+/**
+ * Expand numeric lines and `start-end` ranges into a lookup set.
+ *
+ * Invalid, zero, negative, and reversed entries are ignored. Plain numeric
+ * strings are treated as a single line.
+ */
+export declare function resolveHighlightedLines(values: readonly HighlightLine[] | undefined): Set<number>;

package/dist/core/identity.d.ts

@@ -0,0 +1,4 @@
+/** Stable process-local identity for objects and functions. */
+export declare function identityOf(value: unknown): string;
+export declare function listIdentity(list: readonly unknown[] | undefined): string;
+export declare function stringListIdentity(list: readonly string[] | undefined): string;

package/dist/core/labels.d.ts

@@ -0,0 +1,4 @@
+import { MarkdownLabelContext, MarkdownLabelValue, MarkdownLabels } from '../core/types';
+/** Resolve a static or context-aware label value. */
+export declare function resolveLabel(value: MarkdownLabelValue, context?: MarkdownLabelContext): string;
+export declare const DEFAULT_LABELS: MarkdownLabels;

package/dist/core/manifest.d.ts

@@ -0,0 +1,38 @@
+import { MarkdownPart } from './parts';
+/**
+ * Machine-readable customization manifest for one public component.
+ *
+ * Manifests are Vue-free so documentation, the demo inspector, and validation
+ * tests can consume them without importing component code.
+ */
+export interface MarkdownComponentManifest {
+    name: string;
+    parts: readonly MarkdownPart[];
+    tokens: readonly string[];
+    slots: readonly string[];
+    labels: readonly string[];
+    overrideKeys: readonly string[];
+    tags?: readonly string[];
+    behaviors?: readonly string[];
+}
+export type ManifestIssueCode = 'duplicate-manifest' | 'undeclared-part' | 'missing-part' | 'undeclared-label' | 'missing-slot';
+export interface ManifestValidationIssue {
+    code: ManifestIssueCode;
+    component: string;
+    message: string;
+}
+export interface ManifestRenderSnapshot {
+    parts?: readonly string[];
+    labels?: readonly string[];
+    slots?: readonly string[];
+    /** `strict` also requires every declared part to be rendered. */
+    mode?: 'strict' | 'observed';
+}
+export declare const COMPONENT_MANIFESTS: Record<string, MarkdownComponentManifest>;
+export declare function getComponentManifest(name: string): MarkdownComponentManifest | undefined;
+/**
+ * Compare a manifest with rendered output. Missing snapshot fields are skipped
+ * so a test can validate only the parts, labels, or slots it can observe.
+ */
+export declare function validateManifest(entry: MarkdownComponentManifest, snapshot: ManifestRenderSnapshot): ManifestValidationIssue[];
+export declare function validateManifestRegistry(manifests?: Record<string, MarkdownComponentManifest>): ManifestValidationIssue[];

package/dist/core/memo.d.ts

@@ -0,0 +1,5 @@
+import { MarkdownDocument } from './types';
+export declare function memoGet(key: string): MarkdownDocument | undefined;
+export declare function memoSet(key: string, document: MarkdownDocument): void;
+export declare function memoClear(): void;
+export declare function memoSize(): number;

package/dist/core/model-hast.d.ts

@@ -0,0 +1,8 @@
+import { Root } from 'hast';
+import { MarkdownDocument } from './types';
+/**
+ * Serialize the normalized document model back to hast for static export.
+ * The model has already passed sanitization, filtering, URL policy, and plugin
+ * document transforms, so this function performs no new trust decisions.
+ */
+export declare function modelToHast(document: MarkdownDocument): Root;

package/dist/core/model.d.ts

@@ -0,0 +1,10 @@
+import { MarkdownDocument, MarkdownNode } from './types';
+export interface BuildDocumentOptions {
+    nodes: MarkdownNode[];
+    plugins: string[];
+    pipeline: string;
+    frontmatter?: Record<string, unknown>;
+}
+export declare function buildDocument(options: BuildDocumentOptions): MarkdownDocument;
+/** Recompute derived collections after a document transform. */
+export declare function withDerivedDocument(document: MarkdownDocument): MarkdownDocument;

package/dist/core/normalize.d.ts

@@ -0,0 +1,37 @@
+import { Root } from 'hast';
+import { AllowElement, MarkdownDiagnostic, MarkdownDocument, MarkdownNode, MarkdownSlugger, MarkdownUrlTransform, TocItem } from './types';
+export interface NormalizeOptions {
+    slugger: MarkdownSlugger;
+    idPrefix?: string;
+    urlTransform?: MarkdownUrlTransform;
+    baseUrl?: string;
+    allowedElements?: string[];
+    disallowedElements?: string[];
+    unwrapDisallowed?: boolean;
+    allowElement?: AllowElement;
+    diagnostics?: MarkdownDiagnostic[];
+}
+/**
+ * Convert custom-tag attributes into the camelCase props hosts receive.
+ *
+ * HTML parsing lowercases raw attribute names, so a camelCase attribute written
+ * in raw HTML (`startLine`) cannot be recovered. Authors should use kebab-case
+ * (`start-line`), which normalizes to `startLine`. `data-*` and `aria-*` keep
+ * their hyphenated form because they are DOM attributes rather than component
+ * props.
+ */
+export declare function normalizeCustomTagProps(attrs: Record<string, string>): Record<string, string>;
+export interface NormalizeResult {
+    nodes: MarkdownNode[];
+    toc: TocItem[];
+    customTags: MarkdownDocument['customTags'];
+}
+export declare function normalizeHast(root: Root, options: NormalizeOptions): NormalizeResult;
+/**
+ * Keep headings up to `depth`. A missing, zero, negative, or non-finite depth
+ * means all available levels. Values above six are also effectively unlimited.
+ */
+export declare function filterTocByDepth(toc: readonly TocItem[], depth: number | undefined): TocItem[];
+export declare function extractToc(nodes: readonly MarkdownNode[]): TocItem[];
+export declare function collectCustomTags(nodes: readonly MarkdownNode[]): MarkdownDocument['customTags'];
+export declare function walkNodes(nodes: readonly MarkdownNode[], visit: (node: MarkdownNode, parent: MarkdownNode | undefined) => void, parent?: MarkdownNode): void;

package/dist/core/parts.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Stable part names and token names.
+ *
+ * Parts are rendered as `class="vmd-<part>"` plus `data-vmd-part="<part>"`.
+ * They are stable within a major version and are never generated or hashed.
+ */
+export declare const VMD_CLASS_PREFIX = "vmd-";
+export declare const PARTS: {
+    readonly root: "root";
+    readonly body: "body";
+    readonly tocColumn: "toc-column";
+    readonly content: "content";
+    readonly toc: "toc";
+    readonly tocNav: "toc-nav";
+    readonly tocItem: "toc-item";
+    readonly paragraph: "paragraph";
+    readonly heading: "heading";
+    readonly headingAnchor: "heading-anchor";
+    readonly emphasis: "emphasis";
+    readonly strong: "strong";
+    readonly strikethrough: "strikethrough";
+    readonly link: "link";
+    readonly image: "image";
+    readonly list: "list";
+    readonly listItem: "list-item";
+    readonly blockquote: "blockquote";
+    readonly hr: "hr";
+    readonly break: "break";
+    readonly table: "table";
+    readonly tableSection: "table-section";
+    readonly tableRow: "table-row";
+    readonly tableCell: "table-cell";
+    readonly inlineCode: "inline-code";
+    readonly code: "code";
+    readonly codeHeader: "code-header";
+    readonly codeTitle: "code-title";
+    readonly codeFileName: "code-file-name";
+    readonly codeHeading: "code-heading";
+    readonly codeLang: "code-lang";
+    readonly codeToolbar: "code-toolbar";
+    readonly codeActions: "code-actions";
+    readonly codeAction: "code-action";
+    readonly codeBody: "code-body";
+    readonly codeFeedback: "code-feedback";
+    readonly highlighter: "highlighter";
+    readonly highlighterHeader: "highlighter-header";
+    readonly highlighterActions: "highlighter-actions";
+    readonly highlighterFooter: "highlighter-footer";
+    readonly highlighterBody: "highlighter-body";
+    readonly highlighterGutter: "highlighter-gutter";
+    readonly highlighterLine: "highlighter-line";
+    readonly highlighterHidden: "highlighter-hidden";
+    readonly highlighterEmpty: "highlighter-empty";
+    readonly highlighterToggle: "highlighter-toggle";
+    readonly math: "math";
+    readonly mathError: "math-error";
+    readonly mermaid: "mermaid";
+    readonly mermaidHeader: "mermaid-header";
+    readonly mermaidTabs: "mermaid-tabs";
+    readonly mermaidActions: "mermaid-actions";
+    readonly mermaidAction: "mermaid-action";
+    readonly mermaidPreview: "mermaid-preview";
+    readonly mermaidSource: "mermaid-source";
+    readonly mermaidPending: "mermaid-pending";
+    readonly mermaidError: "mermaid-error";
+    readonly mermaidFallback: "mermaid-fallback";
+    readonly mermaidRetry: "mermaid-retry";
+    readonly mermaidFullscreen: "mermaid-fullscreen";
+    readonly editor: "editor";
+    readonly editorPane: "editor-pane";
+    readonly editorDivider: "editor-divider";
+    readonly editorPreview: "editor-preview";
+    readonly editorDiagnostics: "editor-diagnostics";
+    readonly editorEmpty: "editor-empty";
+    readonly editorToolbar: "editor-toolbar";
+    readonly editorFullscreen: "editor-fullscreen";
+    readonly html: "html";
+    readonly customTag: "custom-tag";
+    readonly taskItem: "task-item";
+    readonly taskCheckbox: "task-checkbox";
+    readonly footnoteReference: "footnote-reference";
+    readonly footnotes: "footnotes";
+    readonly searchMatch: "search-match";
+    readonly error: "error";
+    readonly empty: "empty";
+    readonly loading: "loading";
+};
+export type MarkdownPart = (typeof PARTS)[keyof typeof PARTS];
+export declare const TOKENS: {
+    readonly fontFamily: "--vmd-font-family";
+    readonly fontMono: "--vmd-font-mono";
+    readonly fontSize: "--vmd-font-size";
+    readonly lineHeight: "--vmd-line-height";
+    readonly colorText: "--vmd-color-text";
+    readonly colorMuted: "--vmd-color-muted";
+    readonly colorBg: "--vmd-color-bg";
+    readonly colorSurface: "--vmd-color-surface";
+    readonly colorBorder: "--vmd-color-border";
+    readonly colorAccent: "--vmd-color-accent";
+    readonly colorAccentContrast: "--vmd-color-accent-contrast";
+    readonly colorDanger: "--vmd-color-danger";
+    readonly colorSuccess: "--vmd-color-success";
+    readonly space1: "--vmd-space-1";
+    readonly space2: "--vmd-space-2";
+    readonly space3: "--vmd-space-3";
+    readonly space4: "--vmd-space-4";
+    readonly space5: "--vmd-space-5";
+    readonly space6: "--vmd-space-6";
+    readonly radiusSm: "--vmd-radius-sm";
+    readonly radiusMd: "--vmd-radius-md";
+    readonly radiusLg: "--vmd-radius-lg";
+    readonly shadowSm: "--vmd-shadow-sm";
+    readonly shadowMd: "--vmd-shadow-md";
+    readonly motionDuration: "--vmd-motion-duration";
+    readonly motionEasing: "--vmd-motion-easing";
+    readonly codeBg: "--vmd-code-bg";
+    readonly codeText: "--vmd-code-text";
+    readonly codeBorder: "--vmd-code-border";
+    readonly codeToolbarBg: "--vmd-code-toolbar-bg";
+    readonly mathColor: "--vmd-math-color";
+    readonly mathBg: "--vmd-math-bg";
+    readonly mermaidBg: "--vmd-mermaid-bg";
+    readonly mermaidBorder: "--vmd-mermaid-border";
+    readonly zFullscreen: "--vmd-z-fullscreen";
+};
+export type MarkdownToken = (typeof TOKENS)[keyof typeof TOKENS];
+export interface PartAttributes {
+    class: string;
+    'data-vmd-part': string;
+}
+/** Build the class and `data-vmd-part` attributes for a documented part. */
+export declare function partAttrs(part: MarkdownPart): PartAttributes;
+/** Merge part attributes with host-provided class names. */
+export declare function partClass(part: MarkdownPart, extra?: string): string;
+export declare const PART_NAMES: readonly MarkdownPart[];
+export declare const TOKEN_NAMES: readonly MarkdownToken[];

package/dist/core/preset.d.ts

@@ -0,0 +1,10 @@
+import { MarkdownPreset } from './types';
+/**
+ * Define a shareable preset. Presets contain components, plugin instances, and
+ * functions, so they are declarative and inspectable but not JSON-serializable.
+ */
+export declare function defineMarkdownPreset(preset: MarkdownPreset): MarkdownPreset;
+/** Compose presets in order; later presets override earlier values. */
+export declare function composePresets(...presets: Array<MarkdownPreset | false | null | undefined>): MarkdownPreset;
+/** Resolve a single preset, a preset list, or nothing. */
+export declare function resolvePreset(input: MarkdownPreset | readonly MarkdownPreset[] | undefined): MarkdownPreset | undefined;

package/dist/core/run.d.ts

@@ -0,0 +1,16 @@
+import { MarkdownDiagnostic, MarkdownDocumentOptions, MarkdownPipeline, MarkdownSlugger, PipelineContext } from './types';
+import { ResolvedPlugins } from '../plugins/registry';
+export interface MarkdownRun {
+    pipeline: MarkdownPipeline;
+    plugins: ResolvedPlugins;
+    source: string;
+    context: PipelineContext;
+    slugger: MarkdownSlugger;
+    diagnostics: MarkdownDiagnostic[];
+}
+/**
+ * Resolve and prepare one non-reactive pipeline run. Export uses this helper so
+ * source transforms, plugin resolution, and slugger setup match the
+ * composable's run.
+ */
+export declare function prepareMarkdownRun(source: string, options?: MarkdownDocumentOptions, diagnostics?: MarkdownDiagnostic[]): MarkdownRun;

package/dist/core/search.d.ts

@@ -0,0 +1,5 @@
+import { MarkdownDocument, MarkdownNode, SearchOptions } from './types';
+/** Split text nodes into match/non-match segments without changing structure. */
+export declare function segmentSearch(nodes: readonly MarkdownNode[], options: SearchOptions): void;
+export declare function searchDocument(document: MarkdownDocument, options: SearchOptions): MarkdownDocument;
+export declare function countSearchMatches(nodes: readonly MarkdownNode[]): number;

package/dist/core/security.d.ts

@@ -0,0 +1,21 @@
+import { Properties } from 'hast';
+/** Tags that may appear in the normalized model. */
+export declare const ALLOWED_TAGS: Set<string>;
+/** Tags whose content must never reach the model. */
+export declare const DANGEROUS_TAGS: Set<string>;
+declare const URL_ATTRIBUTES: Set<string>;
+export { URL_ATTRIBUTES };
+export declare function toAttributeName(key: string): string;
+export declare function isAllowedAttribute(tag: string, name: string): boolean;
+/**
+ * Validate one URL-bearing attribute value. `srcset` holds a comma-separated
+ * candidate list, so each candidate is checked individually.
+ */
+export declare function sanitizeUrlValue(value: string, key: string): string | undefined;
+export declare function sanitizeStyleValue(value: string): string | undefined;
+export interface PropertiesToAttrsOptions {
+    /** Allow a constrained inline-style subset for trusted engine output. */
+    allowStyle?: boolean;
+}
+/** Convert hast properties into safe, normalized attributes. */
+export declare function propertiesToAttrs(tag: string, properties: Properties | undefined, options?: PropertiesToAttrsOptions): Record<string, string>;

package/dist/core/slugger.d.ts

@@ -0,0 +1,13 @@
+import { MarkdownSlugger } from './types';
+/**
+ * Create the default heading slugger. `github-slugger` maps every space to a
+ * hyphen, so `My   Heading` would become `my---heading`. Collapsing whitespace
+ * before slugging (and hyphen runs after) keeps IDs readable while preserving
+ * GitHub-compatible punctuation handling.
+ */
+export declare function createDefaultSlugger(): MarkdownSlugger;
+/**
+ * Ensure a host slugger still produces unique heading IDs. The wrapper keeps
+ * the host's formatting and appends a numeric suffix for duplicates.
+ */
+export declare function withUniqueSlugs(slugger: MarkdownSlugger): MarkdownSlugger;