@canofold/markdown 0.2.0

package/dist/compiler/types.d.ts

@@ -0,0 +1,177 @@
+import type { MarkdownAssets } from './assets';
+import type { Root } from 'hast';
+import type { LanguageInput } from '@shikijs/types';
+import type { PluggableList } from 'unified';
+export type MarkdownHtmlPolicy = 'trusted' | 'sanitize' | 'strip';
+export type MarkdownUnknownLanguagePolicy = 'warn' | 'error' | 'plain-text';
+export type MarkdownPluginCacheValue = string | number | boolean | null | MarkdownPluginCacheValue[] | {
+    [key: string]: MarkdownPluginCacheValue;
+};
+export interface MarkdownPluginBrowserCompiler {
+    /** Browser-safe package export that contains the plugin factory. */
+    module: string;
+    /** Named factory export, for example `mermaid` or `plantUml`. */
+    exportName: string;
+    /** JSON-serializable factory options used by browser-side Markdown compilers. */
+    options?: MarkdownPluginCacheValue;
+}
+export interface MarkdownCodeOptions {
+    themes?: {
+        light?: string;
+        dark?: string;
+    };
+    fallbackLanguage?: string;
+    /**
+     * Additional fence-language loaders keyed by the label authors use after
+     * the opening fence. Built-in technical-document languages remain enabled.
+     */
+    languages?: Readonly<Record<string, LanguageInput>>;
+    /** Behavior when neither a built-in nor custom language matches a fence. */
+    unknownLanguage?: MarkdownUnknownLanguagePolicy;
+}
+export interface MarkdownFeatureOptions {
+    callouts?: boolean;
+    tabs?: boolean;
+    codeGroups?: boolean;
+    steps?: boolean;
+    terminals?: boolean;
+    documentBlocks?: boolean;
+    /** Enhance GFM tables independently from other rich document blocks. */
+    tables?: boolean;
+    codeBlocks?: boolean;
+}
+export interface MarkdownLabels {
+    copyCode: string;
+    copyFailed: string;
+    copySnippet: string;
+    copyTerminal: string;
+    terminalTitle: string;
+    tabsTitle: string;
+    tabItem: string;
+    codeGroupTitle: string;
+    codeGroupItem: string;
+    taskCompleted: string;
+    taskIncomplete: string;
+    copySectionLink: string;
+    tableTitle: string;
+    copyTableCsv: string;
+    downloadTableCsv: string;
+    zoomTable: string;
+    closeTablePreview: string;
+    sortTableColumn: string;
+    zoomImage: string;
+    closeImagePreview: string;
+    imageGallery: string;
+    closeImageGallery: string;
+    previousGalleryImage: string;
+    nextGalleryImage: string;
+    galleryThumbnails: string;
+    galleryImage: string;
+}
+/**
+ * A build-time trusted compiler plugin. Plugins extend the shared Markdown and
+ * MDX pipeline with additional remark (mdast) and rehype (hast) transforms.
+ *
+ * Plugin functions cannot participate in cache fingerprints, so `name`,
+ * `version` and `cacheKey` carry the cache identity instead: bump `version`
+ * whenever the transform behavior changes and derive `cacheKey` from the
+ * plugin's resolved options.
+ */
+export interface MarkdownPlugin {
+    /** Unique lowercase kebab-case slug, e.g. "external-links". */
+    name: string;
+    /** Implementation revision; part of the cache identity. */
+    version?: string;
+    /** JSON-serializable configuration identity, typically resolved options. */
+    cacheKey?: MarkdownPluginCacheValue;
+    /**
+     * Optional browser compiler entry. Static sites use this only for explicit
+     * authoring surfaces such as the Playground; ordinary pages do not load it.
+     */
+    browserCompiler?: MarkdownPluginBrowserCompiler;
+    /** Applied before the core rich-block conversion, before remark-rehype. */
+    remarkPlugins?: PluggableList;
+    /** Appended after the built-in rehype plugins, at the end of the pipeline. */
+    rehypePlugins?: PluggableList;
+    /**
+     * Fenced-code language labels consumed by this plugin's remark transforms.
+     * Declaring them prevents the core Shiki loader from treating plugin-owned
+     * fences as ordinary code or reporting them as unsupported languages.
+     */
+    fenceLanguages?: readonly string[];
+    /**
+     * Directive names owned by this plugin. Undeclared directive names are
+     * rejected so author typos cannot silently degrade to generic HTML.
+     */
+    directiveNames?: readonly string[];
+    /**
+     * Optional source-level activation gate. Use this for expensive opt-in
+     * syntax so ordinary documents do not load or run the plugin.
+     */
+    appliesTo?: (context: MarkdownPluginContext) => boolean;
+    /** Static assets required whenever this plugin is active for a document. */
+    assets?: {
+        math?: boolean;
+        /** Browser entry points loaded only for pages that activate this plugin. */
+        clients?: readonly MarkdownPluginClientAsset[];
+        /** Published CSS entry points appended only for pages that activate this plugin. */
+        styles?: readonly MarkdownPluginStyleAsset[];
+    };
+}
+export interface MarkdownPluginClientAsset {
+    /** Stable identifier used for output naming and de-duplication. */
+    id: string;
+    /** Public package export, for example `@scope/plugin/client`. */
+    module: string;
+    /** Extra package files copied beside this client under a directory named after `id`. */
+    resources?: readonly MarkdownPluginClientResource[];
+}
+export interface MarkdownPluginClientResourceDirectory {
+    /** Directory relative to the resource entry point. Parent traversal is rejected. */
+    source: string;
+    /** Output directory relative to this client's resource directory. */
+    output: string;
+    /** Optional file suffix allowlist, for example `[".mjs"]`. */
+    extensions?: readonly string[];
+}
+export interface MarkdownPluginClientResource {
+    /** Package export resolved from the client asset's owning package. */
+    module: string;
+    /** Output file relative to this client's resource directory. */
+    output: string;
+    /** Chunk directories located beside the resolved resource entry. */
+    directories?: readonly MarkdownPluginClientResourceDirectory[];
+}
+export interface MarkdownPluginStyleAsset {
+    /** Stable identifier used for output naming and de-duplication. */
+    id: string;
+    /** Public package export, for example `@canofold/plugins/diagram.css`. */
+    module: string;
+}
+export interface MarkdownPluginContext {
+    source: string;
+    mode: 'markdown' | 'mdx';
+}
+export interface RenderMarkdownOptions {
+    /**
+     * Raw HTML policy for markdown input.
+     *
+     * `trusted` preserves inline HTML and is intended for build-time docs content.
+     * `sanitize` parses HTML and removes unsafe elements, attributes and URLs.
+     * `strip` disables raw HTML parsing entirely.
+     * MDX remains executable trusted code and does not support safe HTML modes.
+     */
+    html?: MarkdownHtmlPolicy;
+    code?: MarkdownCodeOptions;
+    features?: MarkdownFeatureOptions;
+    labels?: Partial<MarkdownLabels>;
+    /** BCP 47 locale exposed to compiler plugins for locale-aware output. */
+    locale?: string;
+    /** Compiler plugins applied to both the Markdown and MDX pipelines. */
+    plugins?: readonly MarkdownPlugin[];
+}
+/** Serializable HAST output before HTML stringification. */
+export interface PreparedMarkdown {
+    document: Root;
+    assets: MarkdownAssets;
+}

package/dist/components/blocks/MarkdownCodeBlock.d.ts

@@ -0,0 +1,10 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+export interface MarkdownCodeBlockProps extends Omit<HTMLAttributes<HTMLElement>, 'children'> {
+    children?: ReactNode;
+    language?: string;
+    filename?: string;
+    source?: string;
+    copyLabel?: string;
+    copyFailureLabel?: string;
+}
+export declare function MarkdownCodeBlock({ children, source: directSource, language: directLanguage, filename: directFilename, copyLabel: directCopyLabel, copyFailureLabel: directCopyFailureLabel, ...inputProps }: MarkdownCodeBlockProps): import("react").JSX.Element;

package/dist/components/blocks/MarkdownCopySnippet.d.ts

@@ -0,0 +1,10 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+export interface MarkdownCopySnippetProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'children'> {
+    children?: ReactNode;
+    value?: string;
+    copyLabel?: string;
+    copyFailureLabel?: string;
+    className?: string;
+}
+/** Inline copy interaction shared by React applications and static islands. */
+export declare function MarkdownCopySnippet(props: MarkdownCopySnippetProps): ReactNode;

package/dist/components/blocks/MarkdownHeading.d.ts

@@ -0,0 +1,13 @@
+import { type ElementType, type HTMLAttributes, type ReactNode } from 'react';
+interface MarkdownHeadingProps extends Omit<HTMLAttributes<HTMLHeadingElement>, 'children' | 'id'> {
+    level: 1 | 2 | 3 | 4 | 5 | 6;
+    as?: ElementType;
+    id?: string;
+    anchor?: string;
+    anchorLabel?: string;
+    copyFailureLabel?: string;
+    'data-cf-element'?: string;
+    children?: ReactNode;
+}
+export declare function MarkdownHeading({ level, as, id, anchor, anchorLabel, copyFailureLabel, children, className, ...props }: MarkdownHeadingProps): import("react").JSX.Element;
+export {};

package/dist/components/blocks/MarkdownImage.d.ts

@@ -0,0 +1,16 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+export interface MarkdownImageProps extends Omit<HTMLAttributes<HTMLElement>, 'children' | 'title'> {
+    children?: ReactNode;
+    src?: string;
+    alt?: string;
+    caption?: string;
+    title?: string;
+    width?: number | string;
+    height?: number | string;
+    loading?: 'eager' | 'lazy';
+    srcSet?: string;
+    sizes?: string;
+    zoomLabel?: string;
+    closeLabel?: string;
+}
+export declare function MarkdownImage(props: MarkdownImageProps): ReactNode;

package/dist/components/blocks/MarkdownTable.d.ts

@@ -0,0 +1,12 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+export interface MarkdownTableProps extends Omit<HTMLAttributes<HTMLElement>, 'children'> {
+    children?: ReactNode;
+    tableTitle?: string;
+    copyLabel?: string;
+    copyFailureLabel?: string;
+    downloadLabel?: string;
+    zoomLabel?: string;
+    closeLabel?: string;
+    sortLabel?: string;
+}
+export declare function MarkdownTable(props: MarkdownTableProps): ReactNode;

package/dist/components/blocks/MarkdownTerminal.d.ts

@@ -0,0 +1,9 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+export interface MarkdownTerminalProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'title'> {
+    children?: ReactNode;
+    title?: string;
+    source?: string;
+    copyLabel?: string;
+    copyFailureLabel?: string;
+}
+export declare function MarkdownTerminal(props: MarkdownTerminalProps): ReactNode;

package/dist/components/composite/MarkdownComposite.d.ts

@@ -0,0 +1,37 @@
+import { type DetailsHTMLAttributes, type HTMLAttributes, type ReactNode } from 'react';
+import { MarkdownCodeBlock } from '../blocks/MarkdownCodeBlock';
+import { MarkdownCopySnippet } from '../blocks/MarkdownCopySnippet';
+import { MarkdownImage } from '../blocks/MarkdownImage';
+import { MarkdownTable } from '../blocks/MarkdownTable';
+import { MarkdownTerminal } from '../blocks/MarkdownTerminal';
+type MarkdownCompositeKind = 'callout' | 'tabs' | 'code-group' | 'steps' | 'code-block' | 'copy-snippet' | 'table' | 'image' | 'terminal' | 'details' | 'file-tree' | 'gallery' | 'card-grid' | 'api' | 'aside' | 'badge';
+export interface MarkdownCompositeProps extends Omit<HTMLAttributes<HTMLElement>, 'children'> {
+    children?: ReactNode;
+}
+export interface MarkdownDetailsProps extends Omit<DetailsHTMLAttributes<HTMLDetailsElement>, 'children'> {
+    children?: ReactNode;
+}
+export declare function MarkdownCallout({ children, ...props }: MarkdownCompositeProps): import("react").DetailedReactHTMLElement<{
+    'data-cf-component': MarkdownCompositeKind;
+    'data-cf-slot': string;
+    className?: string | undefined;
+}, HTMLElement>;
+export declare function MarkdownSteps({ children, ...props }: MarkdownCompositeProps): import("react").DetailedReactHTMLElement<{
+    'data-cf-component': MarkdownCompositeKind;
+    'data-cf-slot': string;
+    className?: string | undefined;
+}, HTMLElement>;
+/**
+ * Keeps native <details> semantics for static output, then upgrades its content
+ * area to a deterministic React disclosure transition after hydration.
+ */
+export declare function MarkdownDetails(props: MarkdownDetailsProps): ReactNode;
+/** Structural React wrappers for trusted/document extension blocks. */
+export { ImageGallery as MarkdownGallery } from '../gallery/ImageGallery';
+export { MarkdownTabs } from './MarkdownTabs';
+export { MarkdownFileTree } from './MarkdownFileTree';
+export declare function MarkdownCardGrid({ children, ...props }: MarkdownCompositeProps): import("react").JSX.Element;
+export declare function MarkdownApiBlock({ children, ...props }: MarkdownCompositeProps): import("react").JSX.Element;
+export declare function MarkdownAside({ children, ...props }: MarkdownCompositeProps): import("react").JSX.Element;
+export declare function MarkdownBadge({ children, ...props }: MarkdownCompositeProps): import("react").JSX.Element;
+export { MarkdownCodeBlock, MarkdownCopySnippet, MarkdownImage, MarkdownTable, MarkdownTerminal };

package/dist/components/composite/MarkdownFileTree.d.ts

@@ -0,0 +1,5 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+export interface MarkdownFileTreeProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    children?: ReactNode;
+}
+export declare function MarkdownFileTree(props: MarkdownFileTreeProps): ReactNode;

package/dist/components/composite/MarkdownTabs.d.ts

@@ -0,0 +1,6 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+export interface MarkdownTabsProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    children?: ReactNode;
+    kind?: 'tabs' | 'code-group';
+}
+export declare function MarkdownTabs(props: MarkdownTabsProps): ReactNode;

package/dist/components/gallery/ImageGallery.d.ts

@@ -0,0 +1,25 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+export interface MarkdownGalleryItem {
+    src: string;
+    alt: string;
+    caption?: string;
+    title?: string;
+    srcSet?: string;
+    sizes?: string;
+    width?: number | string;
+    height?: number | string;
+}
+export interface ImageGalleryProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'role'> {
+    children?: ReactNode;
+    items?: MarkdownGalleryItem[];
+    role?: 'group' | 'region';
+    labels?: Partial<{
+        gallery: string;
+        close: string;
+        previous: string;
+        next: string;
+        thumbnails: string;
+        image: string;
+    }>;
+}
+export declare function ImageGallery(props: ImageGalleryProps): ReactNode;

package/dist/components/shared/MarkdownActions.d.ts

@@ -0,0 +1,18 @@
+import { type MarkdownIconName } from './MarkdownIcon';
+export { copyMarkdownText } from '../../shared/copyText';
+export declare function MarkdownCopyButton({ value, label, action, className, icon, failureLabel }: {
+    value: string;
+    label: string;
+    action: string;
+    className?: string;
+    icon?: MarkdownIconName;
+    failureLabel?: string;
+}): import("react").JSX.Element;
+export declare function MarkdownDownloadButton({ value, filename, label, action, className, contentType }: {
+    value: string;
+    filename: string;
+    label: string;
+    action: string;
+    className?: string;
+    contentType?: string;
+}): import("react").JSX.Element;

package/dist/components/shared/MarkdownDialog.d.ts

@@ -0,0 +1,11 @@
+import { type KeyboardEvent, type ReactNode, type RefObject } from 'react';
+export declare function MarkdownDialogPortal({ children }: {
+    children: ReactNode;
+}): import("react").ReactPortal | null;
+export declare function useMarkdownDialog({ open, close, dialogRef, initialFocusRef, triggerRef }: {
+    open: boolean;
+    close: () => void;
+    dialogRef: RefObject<HTMLElement | null>;
+    initialFocusRef: RefObject<HTMLElement | null>;
+    triggerRef: RefObject<HTMLElement | null>;
+}): (event: KeyboardEvent<HTMLElement>) => void;

package/dist/components/shared/MarkdownFileIcon.d.ts

@@ -0,0 +1,4 @@
+export declare function MarkdownFileIcon({ filename, language }: {
+    filename: string;
+    language?: string;
+}): import("react").JSX.Element;

package/dist/components/shared/MarkdownIcon.d.ts

@@ -0,0 +1,8 @@
+import { type MarkdownIconName } from '../../react/slots';
+export type { MarkdownIconName } from '../../react/slots';
+export declare function MarkdownIcon({ name, size, className }: {
+    name: MarkdownIconName;
+    size?: number;
+    className?: string;
+    direction?: 'asc' | 'desc';
+}): import("react").JSX.Element;

package/dist/components/shared/interactionConstants.d.ts

@@ -0,0 +1 @@
+export declare const ACTION_FEEDBACK_DURATION_MS = 1500;

package/dist/components/shared/reactText.d.ts

@@ -0,0 +1,14 @@
+import { type ReactElement, type ReactNode } from 'react';
+export declare function reactText(value: unknown): string;
+export type MarkdownReactElement = ReactElement<Record<string, unknown> & {
+    children?: ReactNode;
+}>;
+export declare function elementChildren(value: ReactNode): MarkdownReactElement[];
+/** Resolve names from raw elements and the mapped Markdown element functions. */
+export declare function elementTag(element: MarkdownReactElement): string;
+export declare function readProp(props: object, ...names: string[]): {} | undefined;
+export declare function stringProp(props: object, ...names: string[]): string;
+export declare function markdownDomProps(props: object, omitted?: readonly string[]): {
+    [k: string]: any;
+};
+export declare function mergeMarkdownClasses(base: string, value: unknown): string;