@ng-doc/utils 22.0.0 → 22.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Aleksandr Skoropad
+
+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 NON INFRINGEMENT. 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/html/plugins/cached-shiki.plugin.d.ts

@@ -1,4 +1,3 @@
-import { type RehypeShikiOptions } from '@shikijs/rehype';
 import type { Root } from 'hast';
 /**
  * Everything a highlighted code block depends on, apart from the installed Shiki release. A cache
@@ -12,6 +11,8 @@ export interface NgDocHighlightBlock {
         readonly light: string;
         readonly dark: string;
     };
+    /** The identity of the extra languages (`processHtml`'s `langs`); absent without any. */
+    readonly languages?: string;
     /** The language of the block's class, or the default language: before the fallback. */
     readonly lang: string;
     /** The raw meta string, before it is parsed. */
@@ -21,8 +22,10 @@ export interface NgDocHighlightBlock {
 }
 /**
  * A cache of highlighted code blocks for `processHtml`. Values are the JSON of the HAST nodes that
- * replace a block's `pre` element. A value that is not a JSON array of HAST elements is a miss.
- * The cache only ever receives values of blocks that were highlighted without an error.
+ * replace a block's `pre` element: `@shikijs/rehype` replaces it with the root of the highlighted
+ * fragment, which holds the new `pre` element. A value that is not a JSON array of HAST elements or
+ * such roots is a miss. The cache only ever receives values of blocks that were highlighted without
+ * an error.
  */
 export interface NgDocHighlightCache {
     /** The key of a block. It must change whenever anything in the block or the Shiki release does. */
@@ -44,13 +47,24 @@ export interface NgDocHighlightCache {
 export interface CachedShikiOptions {
     cache: NgDocHighlightCache;
     themes: NgDocHighlightBlock['themes'];
-    /** What `options` stands for in a key: change it whenever the options or this plugin change. */
+    /** The identity of the extra languages the transformer highlights with; absent without any. */
+    languages?: string;
+    /**
+     * `used` when the transformer loads only the grammars blocks use. It gives the same result, so
+     * it is not part of a key; it only selects the transformer.
+     */
+    grammars?: 'used';
+    /** What the options stand for in a key: change it whenever the options or this plugin change. */
     identity: NgDocHighlightBlock['options'];
     /** The language of a block without a `language-*` class (the options' `defaultLanguage`). */
     defaultLanguage: string;
-    /** The options `@shikijs/rehype` highlights with, created when the highlighter is. */
-    options: () => RehypeShikiOptions;
+    /**
+     * Creates the `@shikijs/rehype` transformer that highlights a miss, with the plugin's options;
+     * called once per thread, theme pair and languages.
+     */
+    transformer: () => Highlighter;
 }
+type Highlighter = (tree: Root) => Promise<void> | void;
 /**
  * The plain `@shikijs/rehype` plugin, with a cache of its results per block.
  *
@@ -66,3 +80,4 @@ export interface CachedShikiOptions {
  * loads Shiki once the cache shows that its themes load.
  */
 export default function cachedShikiPlugin(settings: CachedShikiOptions): (tree: Root) => Promise<void>;
+export {};

package/html/plugins/keyword-positions.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Where a keyword may link inside code.
+ *
+ * The keywords plugin splits code into words and looks each one up. A word that happens to be a
+ * keyword is not always a reference to it: an object key (`group: 'Colors'`), a property after a
+ * dot, a string, an HTML attribute value or a file name in inline code (`vite.config.mjs`) only
+ * share its name. Highlighted code carries no token scopes (Shiki emits colours only, and adjacent
+ * tokens of one colour are merged), so this module reads the position of a word from the code text
+ * itself with a small lexer: strings and comments, the characters around the word, and the names
+ * the code declares. The result only depends on the code, never on the keyword set, so the words a
+ * page records as used keywords are exactly the ones that may link.
+ */
+/** How the code around a word is read. */
+export type CodeMode = 'typescript' | 'html';
+/** What the plugin does with one word. */
+export type WordPosition = 
+/** Not a reference: the word stays plain text and is not recorded as used. */
+{
+    readonly link: false;
+}
+/**
+ * A reference. `keyword`, when present, is the key to look up instead of the word's own key: a
+ * member after a dot is looked up as `Owner.member`.
+ */
+ | {
+    readonly link: true;
+    readonly keyword?: string;
+};
+/** The positions of the words of one code element. */
+export interface CodeScan {
+    /** Whether the whole element is a single keyword reference (inline code only). */
+    readonly whole: boolean;
+    /**
+     * The position of the word at `[start, end)` of the element's text.
+     * @param start - The offset of the word's first character.
+     * @param end - The offset after the word's last character.
+     * @param key - The word's key: the word without its `.member`/`#anchor` and query.
+     */
+    position(start: number, end: number, key: string): WordPosition;
+}
+/**
+ * The positions of the words of inline code, or `undefined` when no word of it may link.
+ *
+ * Inline code links when it is one keyword reference as a whole (`NgDocPage`, `*GuidePage#anchor`,
+ * `NgDocPage.title`, with an optional `?query`), or when it reads as TypeScript: it contains code
+ * punctuation (a call, generics, a union, an array type, a decorator, a type annotation) or starts
+ * with a declaration. Then its words link where they would in a TypeScript code block. Anything
+ * else (a file name like `vite.ng-doc.config.mjs`, a path, a command, prose, an HTML tag) stays
+ * plain text.
+ * @param text - The text of the inline code element.
+ */
+export declare function scanInlineCode(text: string): CodeScan | undefined;
+/**
+ * The positions of the words of a code block.
+ * @param text - The text of the block's `code` element.
+ * @param mode - How the block's language is read.
+ */
+export declare function scanCodeBlock(text: string, mode: CodeMode): CodeScan;

package/html/process-html.d.ts

@@ -1,9 +1,27 @@
 import { NgDocHeading, NgDocPageAnchor } from '@ng-doc/core';
 import { NgDocHighlightCache } from './plugins/cached-shiki.plugin';
 export type { NgDocHighlightBlock, NgDocHighlightCache } from './plugins/cached-shiki.plugin';
+/** A Shiki language registration: a TextMate grammar as plain JSON, with its name. */
+export interface NgDocHighlightLanguage {
+    readonly name: string;
+    readonly scopeName: string;
+}
 export interface NgDocHtmlProcessorConfig {
     lightTheme?: string;
     darkTheme?: string;
+    /**
+     * Languages that code blocks can use besides those bundled with Shiki. A registration named like
+     * a bundled language replaces it. With languages, code is highlighted by a highlighter of its
+     * own, created once per thread for these languages and themes.
+     */
+    langs?: readonly NgDocHighlightLanguage[];
+    /**
+     * Which bundled Shiki grammars the highlighter loads: `all` (the default) sets it up with every
+     * bundled grammar, as `@shikijs/rehype` does; `used` loads only the grammars the document's code
+     * blocks can reach, into a highlighter kept per thread and theme pair, which takes a fraction of
+     * the time and gives the same HTML. With `langs`, every grammar is loaded.
+     */
+    grammars?: 'all' | 'used';
     headings?: NgDocHeading[];
     route?: string;
     /**

package/html/shiki-grammars.d.ts

@@ -0,0 +1,58 @@
+import type { Root } from 'hast';
+import { type HighlighterGeneric, type LanguageRegistration, createHighlighter } from 'shiki';
+/**
+ * Loading only the Shiki grammars that code blocks use, with the same result as loading every
+ * bundled grammar.
+ *
+ * `@shikijs/rehype` sets its highlighter up with every bundled grammar, which takes seconds. A
+ * grammar's highlighting depends only on the grammars it can reach: the languages it embeds
+ * (`embeddedLangs`, and `embeddedLangsLazy`, which it uses once they are loaded), the scopes its
+ * rules include, and the grammars that inject into its scopes (`injectTo`, matched by scope
+ * prefix, in registration order). {@link ShikiGrammars.closure} is that set, closed under the
+ * same rules, plus every grammar that shares an injection target with an injector in it, so the
+ * injections of a scope are always registered together. Loaded in the order in which loading every
+ * bundled grammar registers them (the first mention of each name), a closure gives the
+ * highlighter the same grammars, injections and injection order for its languages as loading
+ * everything, whatever else was loaded before: a highlighter only grows by whole closures, and
+ * each scope's grammars are complete when the scope is first loaded.
+ */
+export declare class ShikiGrammars {
+    private readonly byName;
+    private readonly byScope;
+    private readonly injectors;
+    private readonly order;
+    private readonly closures;
+    private readonly loaded;
+    private constructor();
+    /**
+     * The bundled grammars, in the order `@shikijs/rehype` registers them: every bundled language
+     * name, each with the registrations of its module.
+     */
+    static create(): Promise<ShikiGrammars>;
+    /**
+     * The grammars that a block of `language` can reach, in registration order; empty for a
+     * language that no bundled grammar names (it falls back to plain text, as before).
+     * @param language
+     */
+    closure(language: string): readonly LanguageRegistration[];
+    /**
+     * Loads the closures of `languages` that `highlighter` does not hold yet.
+     * @param highlighter
+     * @param languages
+     */
+    load(highlighter: HighlighterGeneric<string, string>, languages: Iterable<string>): void;
+}
+/** The bundled grammars of this thread, read once. */
+export declare function shikiGrammars(): Promise<ShikiGrammars>;
+/**
+ * A highlighter with the given themes and no language: {@link ShikiGrammars.load} adds them.
+ * @param themes
+ */
+export declare function createGrammarlessHighlighter(themes: Parameters<typeof createHighlighter>[0]['themes']): Promise<HighlighterGeneric<string, string>>;
+/**
+ * The language of every block `@shikijs/rehype` highlights in `tree` (a `pre` whose first child is
+ * a `code` element with properties): its `language-*` class, or `defaultLanguage`.
+ * @param tree
+ * @param defaultLanguage
+ */
+export declare function blockLanguages(tree: Root, defaultLanguage: string): Set<string>;