@shikijs/twoslash 1.0.0-beta.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2021 Pine Wu
+Copyright (c) 2023 Anthony Fu <https://github.com/antfu>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @shikijs/twoslash
+
+A [shiki](https://github.com/shikijs/shiki) transformer for [TypeScript Twoslash](https://www.typescriptlang.org/dev/twoslash/).
+
+[Documentations](https://shiki.style/packages/twoslash)
+
+## License
+
+MIT

package/dist/core.d.mts

@@ -0,0 +1,230 @@
+import { TwoslashReturn, twoslasher, TwoslashOptions, NodeError, NodeTag, NodeQuery, NodeCompletion, NodeHover, NodeHighlight, TwoslashExecuteOptions } from 'twoslash';
+import { CodeToHastOptions, ShikiTransformerContext, ShikiTransformerContextCommon, ShikiTransformer } from '@shikijs/core';
+import { ElementContent, Element, Text } from 'hast';
+
+declare module '@shikijs/core' {
+    interface ShikiTransformerContextMeta {
+        twoslash?: TwoslashReturn;
+    }
+}
+interface TransformerTwoslashOptions {
+    /**
+     * Languages to apply this transformer to
+     */
+    langs?: string[];
+    /**
+     * Requires `twoslash` to be presented in the code block meta to apply this transformer
+     *
+     * @default false
+     */
+    explicitTrigger?: boolean;
+    /**
+     * Mapping from language alias to language name
+     */
+    langAlias?: Record<string, string>;
+    /**
+     * Custom filter function to apply this transformer to
+     * When specified, `langs` and `explicitTrigger` will be ignored
+     */
+    filter?: (lang: string, code: string, options: CodeToHastOptions) => boolean;
+    /**
+     * Custom instance of twoslasher function
+     */
+    twoslasher?: typeof twoslasher;
+    /**
+     * Options to pass to twoslash
+     */
+    twoslashOptions?: TwoslashOptions;
+    /**
+     * Custom renderers to decide how each info should be rendered
+     */
+    renderer?: TwoslashRenderer;
+    /**
+     * Strictly throw when there is an error
+     * @default true
+     */
+    throws?: boolean;
+}
+interface TwoslashRenderer {
+    lineError?(this: ShikiTransformerContext, error: NodeError): ElementContent[];
+    lineCustomTag?(this: ShikiTransformerContext, tag: NodeTag): ElementContent[];
+    lineQuery?(this: ShikiTransformerContext, query: NodeQuery, targetNode?: Element | Text): ElementContent[];
+    lineCompletion?(this: ShikiTransformerContext, query: NodeCompletion): ElementContent[];
+    nodeStaticInfo(this: ShikiTransformerContext, info: NodeHover, node: Element | Text): Partial<ElementContent>;
+    nodeError?(this: ShikiTransformerContext, error: NodeError, node: Element | Text): Partial<ElementContent>;
+    nodeQuery?(this: ShikiTransformerContext, query: NodeQuery, node: Element | Text): Partial<ElementContent>;
+    nodeCompletion?(this: ShikiTransformerContext, query: NodeCompletion, node: Element | Text): Partial<ElementContent>;
+    nodesHighlight?(this: ShikiTransformerContext, highlight: NodeHighlight, nodes: ElementContent[]): ElementContent[];
+}
+
+type CompletionItem = NonNullable<NodeCompletion['completions']>[number];
+declare const defaultCompletionIcons: Record<CompletionItem['kind'], Element | undefined>;
+declare const defaultCustomTagIcons: Record<string, Element | undefined>;
+
+interface RendererRichOptions {
+    /**
+     * Render JSDoc comments in hover popup.
+     *
+     * @default true
+     */
+    jsdoc?: boolean;
+    /**
+     * Custom icons for completion items.
+     * A map from completion item kind to a HAST node.
+     *
+     * If `false`, no icons will be rendered.
+     * @default defaultCompletionIcons
+     */
+    completionIcons?: Partial<Record<CompletionItem['kind'], ElementContent>> | false;
+    /**
+     * Custom icons for custom tags lines.
+     * A map from tag name to a HAST node.
+     *
+     * If `false`, no icons will be rendered.
+     * @default defaultCustomTagIcons
+     */
+    customTagIcons?: Partial<Record<string, ElementContent>> | false;
+    /**
+     * Custom formatter for the type info text.
+     * Note that it might not be valid TypeScript syntax.
+     *
+     * @default defaultHoverInfoProcessor
+     */
+    processHoverInfo?: (info: string) => string;
+    /**
+     * Custom formatter for the docs text (can be markdown).
+     *
+     * @default undefined
+     */
+    processHoverDocs?: (docs: string) => string;
+    /**
+     * Classes added to injected elements
+     */
+    classExtra?: string;
+    /**
+     * Language for syntax highlight.
+     * @default the language of the code block
+     */
+    lang?: string;
+    /**
+     * @deprecated Use `processHoverInfo` instead.
+     */
+    formatInfo?(info: string): string;
+    /**
+     * Custom function to render markdown.
+     *
+     * By default it pass-through the markdown.
+     */
+    renderMarkdown?(this: ShikiTransformerContextCommon, markdown: string): ElementContent[];
+    /**
+     * Custom function to render inline markdown.
+     *
+     * By default it pass-through the markdown.
+     */
+    renderMarkdownInline?(this: ShikiTransformerContextCommon, markdown: string, context: string): ElementContent[];
+    /**
+     * Extensions for the genreated HAST tree.
+     */
+    hast?: {
+        /**
+         * The <code> block for in the hover popup.
+         */
+        popupTypes?: HastExtension;
+        /**
+         * The documentation block in the hover popup. Can be markdown rendered if `renderMarkdown` is provided.
+         */
+        popupDocs?: HastExtension;
+        /**
+         * The container of jsdoc tags in the hover popup.
+         */
+        popupDocsTags?: HastExtension;
+        /**
+         * The token for the hover informaton.
+         */
+        hoverToken?: HastExtension;
+        /**
+         * The container of the hover popup.
+         */
+        hoverPopup?: HastExtension;
+        /**
+         * Custom function to compose the hover token.
+         */
+        hoverCompose?: (parts: {
+            popup: Element;
+            token: Text | Element;
+        }) => ElementContent[];
+        /**
+         * The token for the query informaton.
+         */
+        queryToken?: HastExtension;
+        /**
+         * The container of the query popup.
+         */
+        queryPopup?: HastExtension;
+        /**
+         * Custom function to compose the hover token.
+         */
+        queryCompose?: (parts: {
+            popup: Element;
+            token: Text | Element;
+        }) => ElementContent[];
+        /**
+         * The token for the completion informaton.
+         */
+        completionToken?: HastExtension;
+        /**
+         * The cursor element in the completion popup.
+         */
+        completionCursor?: HastExtension;
+        /**
+         * The container of the completion popup.
+         */
+        completionPopup?: HastExtension;
+        /**
+         * Custom function to compose the completion token.
+         */
+        completionCompose?: (parts: {
+            popup: Element;
+            cursor: Element;
+        }) => ElementContent[];
+        /**
+         * The token for the error informaton.
+         */
+        errorToken?: HastExtension;
+        /**
+         * The wrapper for the highlighted nodes.
+         */
+        nodesHighlight?: HastExtension;
+    };
+}
+interface HastExtension {
+    tagName?: string;
+    properties?: Element['properties'];
+    class?: string;
+    children?: (input: ElementContent[]) => ElementContent[];
+}
+/**
+ * An alternative renderer that providers better prefixed class names,
+ * with syntax highlight for the info text.
+ */
+declare function rendererRich(options?: RendererRichOptions): TwoslashRenderer;
+/**
+ * The default hover info processor, which will do some basic cleanup
+ */
+declare function defaultHoverInfoProcessor(type: string): string;
+
+/**
+ * The default renderer aligning with the original `@shikijs/twoslash` output.
+ */
+declare function rendererClassic(): TwoslashRenderer;
+
+/**
+ * This file is the core of the @shikijs/twoslash package,
+ * Decoupled from twoslash's implementation and allowing to introduce custom implementation or cache system.
+ */
+
+declare function defaultTwoslashOptions(): TwoslashExecuteOptions;
+type TwoslashFunction = (code: string, lang?: string, options?: TwoslashExecuteOptions) => TwoslashReturn;
+declare function createTransformerFactory(defaultTwoslasher: TwoslashFunction, defaultRenderer?: TwoslashRenderer): (options?: TransformerTwoslashOptions) => ShikiTransformer;
+
+export { type CompletionItem, type HastExtension, type RendererRichOptions, type TransformerTwoslashOptions, type TwoslashRenderer, createTransformerFactory, defaultCompletionIcons, defaultCustomTagIcons, defaultHoverInfoProcessor, defaultTwoslashOptions, rendererClassic, rendererRich };

package/dist/core.d.ts

@@ -0,0 +1,230 @@
+import { TwoslashReturn, twoslasher, TwoslashOptions, NodeError, NodeTag, NodeQuery, NodeCompletion, NodeHover, NodeHighlight, TwoslashExecuteOptions } from 'twoslash';
+import { CodeToHastOptions, ShikiTransformerContext, ShikiTransformerContextCommon, ShikiTransformer } from '@shikijs/core';
+import { ElementContent, Element, Text } from 'hast';
+
+declare module '@shikijs/core' {
+    interface ShikiTransformerContextMeta {
+        twoslash?: TwoslashReturn;
+    }
+}
+interface TransformerTwoslashOptions {
+    /**
+     * Languages to apply this transformer to
+     */
+    langs?: string[];
+    /**
+     * Requires `twoslash` to be presented in the code block meta to apply this transformer
+     *
+     * @default false
+     */
+    explicitTrigger?: boolean;
+    /**
+     * Mapping from language alias to language name
+     */
+    langAlias?: Record<string, string>;
+    /**
+     * Custom filter function to apply this transformer to
+     * When specified, `langs` and `explicitTrigger` will be ignored
+     */
+    filter?: (lang: string, code: string, options: CodeToHastOptions) => boolean;
+    /**
+     * Custom instance of twoslasher function
+     */
+    twoslasher?: typeof twoslasher;
+    /**
+     * Options to pass to twoslash
+     */
+    twoslashOptions?: TwoslashOptions;
+    /**
+     * Custom renderers to decide how each info should be rendered
+     */
+    renderer?: TwoslashRenderer;
+    /**
+     * Strictly throw when there is an error
+     * @default true
+     */
+    throws?: boolean;
+}
+interface TwoslashRenderer {
+    lineError?(this: ShikiTransformerContext, error: NodeError): ElementContent[];
+    lineCustomTag?(this: ShikiTransformerContext, tag: NodeTag): ElementContent[];
+    lineQuery?(this: ShikiTransformerContext, query: NodeQuery, targetNode?: Element | Text): ElementContent[];
+    lineCompletion?(this: ShikiTransformerContext, query: NodeCompletion): ElementContent[];
+    nodeStaticInfo(this: ShikiTransformerContext, info: NodeHover, node: Element | Text): Partial<ElementContent>;
+    nodeError?(this: ShikiTransformerContext, error: NodeError, node: Element | Text): Partial<ElementContent>;
+    nodeQuery?(this: ShikiTransformerContext, query: NodeQuery, node: Element | Text): Partial<ElementContent>;
+    nodeCompletion?(this: ShikiTransformerContext, query: NodeCompletion, node: Element | Text): Partial<ElementContent>;
+    nodesHighlight?(this: ShikiTransformerContext, highlight: NodeHighlight, nodes: ElementContent[]): ElementContent[];
+}
+
+type CompletionItem = NonNullable<NodeCompletion['completions']>[number];
+declare const defaultCompletionIcons: Record<CompletionItem['kind'], Element | undefined>;
+declare const defaultCustomTagIcons: Record<string, Element | undefined>;
+
+interface RendererRichOptions {
+    /**
+     * Render JSDoc comments in hover popup.
+     *
+     * @default true
+     */
+    jsdoc?: boolean;
+    /**
+     * Custom icons for completion items.
+     * A map from completion item kind to a HAST node.
+     *
+     * If `false`, no icons will be rendered.
+     * @default defaultCompletionIcons
+     */
+    completionIcons?: Partial<Record<CompletionItem['kind'], ElementContent>> | false;
+    /**
+     * Custom icons for custom tags lines.
+     * A map from tag name to a HAST node.
+     *
+     * If `false`, no icons will be rendered.
+     * @default defaultCustomTagIcons
+     */
+    customTagIcons?: Partial<Record<string, ElementContent>> | false;
+    /**
+     * Custom formatter for the type info text.
+     * Note that it might not be valid TypeScript syntax.
+     *
+     * @default defaultHoverInfoProcessor
+     */
+    processHoverInfo?: (info: string) => string;
+    /**
+     * Custom formatter for the docs text (can be markdown).
+     *
+     * @default undefined
+     */
+    processHoverDocs?: (docs: string) => string;
+    /**
+     * Classes added to injected elements
+     */
+    classExtra?: string;
+    /**
+     * Language for syntax highlight.
+     * @default the language of the code block
+     */
+    lang?: string;
+    /**
+     * @deprecated Use `processHoverInfo` instead.
+     */
+    formatInfo?(info: string): string;
+    /**
+     * Custom function to render markdown.
+     *
+     * By default it pass-through the markdown.
+     */
+    renderMarkdown?(this: ShikiTransformerContextCommon, markdown: string): ElementContent[];
+    /**
+     * Custom function to render inline markdown.
+     *
+     * By default it pass-through the markdown.
+     */
+    renderMarkdownInline?(this: ShikiTransformerContextCommon, markdown: string, context: string): ElementContent[];
+    /**
+     * Extensions for the genreated HAST tree.
+     */
+    hast?: {
+        /**
+         * The <code> block for in the hover popup.
+         */
+        popupTypes?: HastExtension;
+        /**
+         * The documentation block in the hover popup. Can be markdown rendered if `renderMarkdown` is provided.
+         */
+        popupDocs?: HastExtension;
+        /**
+         * The container of jsdoc tags in the hover popup.
+         */
+        popupDocsTags?: HastExtension;
+        /**
+         * The token for the hover informaton.
+         */
+        hoverToken?: HastExtension;
+        /**
+         * The container of the hover popup.
+         */
+        hoverPopup?: HastExtension;
+        /**
+         * Custom function to compose the hover token.
+         */
+        hoverCompose?: (parts: {
+            popup: Element;
+            token: Text | Element;
+        }) => ElementContent[];
+        /**
+         * The token for the query informaton.
+         */
+        queryToken?: HastExtension;
+        /**
+         * The container of the query popup.
+         */
+        queryPopup?: HastExtension;
+        /**
+         * Custom function to compose the hover token.
+         */
+        queryCompose?: (parts: {
+            popup: Element;
+            token: Text | Element;
+        }) => ElementContent[];
+        /**
+         * The token for the completion informaton.
+         */
+        completionToken?: HastExtension;
+        /**
+         * The cursor element in the completion popup.
+         */
+        completionCursor?: HastExtension;
+        /**
+         * The container of the completion popup.
+         */
+        completionPopup?: HastExtension;
+        /**
+         * Custom function to compose the completion token.
+         */
+        completionCompose?: (parts: {
+            popup: Element;
+            cursor: Element;
+        }) => ElementContent[];
+        /**
+         * The token for the error informaton.
+         */
+        errorToken?: HastExtension;
+        /**
+         * The wrapper for the highlighted nodes.
+         */
+        nodesHighlight?: HastExtension;
+    };
+}
+interface HastExtension {
+    tagName?: string;
+    properties?: Element['properties'];
+    class?: string;
+    children?: (input: ElementContent[]) => ElementContent[];
+}
+/**
+ * An alternative renderer that providers better prefixed class names,
+ * with syntax highlight for the info text.
+ */
+declare function rendererRich(options?: RendererRichOptions): TwoslashRenderer;
+/**
+ * The default hover info processor, which will do some basic cleanup
+ */
+declare function defaultHoverInfoProcessor(type: string): string;
+
+/**
+ * The default renderer aligning with the original `@shikijs/twoslash` output.
+ */
+declare function rendererClassic(): TwoslashRenderer;
+
+/**
+ * This file is the core of the @shikijs/twoslash package,
+ * Decoupled from twoslash's implementation and allowing to introduce custom implementation or cache system.
+ */
+
+declare function defaultTwoslashOptions(): TwoslashExecuteOptions;
+type TwoslashFunction = (code: string, lang?: string, options?: TwoslashExecuteOptions) => TwoslashReturn;
+declare function createTransformerFactory(defaultTwoslasher: TwoslashFunction, defaultRenderer?: TwoslashRenderer): (options?: TransformerTwoslashOptions) => ShikiTransformer;
+
+export { type CompletionItem, type HastExtension, type RendererRichOptions, type TransformerTwoslashOptions, type TwoslashRenderer, createTransformerFactory, defaultCompletionIcons, defaultCustomTagIcons, defaultHoverInfoProcessor, defaultTwoslashOptions, rendererClassic, rendererRich };