@ng-doc/utils 22.0.0-beta.2 → 22.1.0

package/README.md

@@ -1,37 +1,28 @@
-<!-- PROJECT LOGO -->
-<br />
-<div align="center">
-  <a href="https://github.com/ng-doc/ng-doc">
-    <img src="https://ng-doc.com/assets/images/ng-doc.svg?raw=true" alt="Logo" height="150px">
-  </a>
-
-<h1 align="center" style="margin-bottom: 0; border-bottom: 0">NgDoc</h1>
-  <p align="center">
-    Create user-friendly documentation for your projects with ease!
-    <br />
-    <a href="https://ng-doc.com/">Documentation</a>
-    ·
-    <a href="https://github.com/ng-doc/ng-doc/issues/new/choose">Report Bug</a>
-    ·
-    <a href="https://github.com/ng-doc/ng-doc/issues/new/choose">Request Feature</a>
-
-[![GitHub Workflow Status][build-shield]][build-url]
+# 🧰 @ng-doc/utils
+
+Small utilities shared by the other NgDoc packages.
+
+It's part of [NgDoc](https://ng-doc.com/) 📚, the documentation engine for Angular projects.
+
 [![NPM][npm-shield]][npm-url]
 [![MIT License][license-shield]][license-url]
 
-  </p>
-</div>
+## 🚀 Getting started
+
+You don't need to install this package by hand. Add NgDoc to your project and it sets up
+everything it needs:
 
-<!-- ABOUT THE PROJECT -->
+```bash
+ng add @ng-doc/add
+```
 
-## About The Project
+## 📖 Learn more
 
-This library is a part of NgDoc project, that uses to create documentation
-for Angular projects, please check our [repo](https://github.com/ng-doc/ng-doc) for more details.
+- [Documentation](https://ng-doc.com/)
+- [GitHub repository](https://github.com/ng-doc/ng-doc)
+- [Report a bug or request a feature](https://github.com/ng-doc/ng-doc/issues/new/choose)
 
-[npm-shield]: https://img.shields.io/npm/v/@ng-doc/builder.svg?style=for-the-badge
-[npm-url]: https://www.npmjs.com/package/@ng-doc/builder
+[npm-shield]: https://img.shields.io/npm/v/%40ng-doc%2Futils.svg?style=for-the-badge
+[npm-url]: https://www.npmjs.com/package/@ng-doc/utils
 [license-shield]: https://img.shields.io/github/license/ng-doc/ng-doc.svg?style=for-the-badge
-[license-url]: https://github.com/othneildrew/Best-README-Template/blob/master/LICENSE.txt
-[build-shield]: https://img.shields.io/github/actions/workflow/status/ng-doc/ng-doc/release.yml?style=for-the-badge&branch=release
-[build-url]: https://github.com/ng-doc/ng-doc/actions
+[license-url]: https://github.com/ng-doc/ng-doc/blob/main/LICENSE

package/html/plugins/cached-shiki.plugin.d.ts

@@ -0,0 +1,83 @@
+import type { Root } from 'hast';
+/**
+ * Everything a highlighted code block depends on, apart from the installed Shiki release. A cache
+ * keys a block by it (plus that release) with {@link NgDocHighlightCache.key}.
+ */
+export interface NgDocHighlightBlock {
+    /** The plugin's format and the fixed Shiki options it highlights with. */
+    readonly options: Readonly<Record<string, string | number | boolean>>;
+    /** The theme names. NgDoc's own theme (`css-variables`) is not a Shiki theme. */
+    readonly themes: {
+        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. */
+    readonly meta: string;
+    /** The block's text. */
+    readonly code: string;
+}
+/**
+ * A cache of highlighted code blocks for `processHtml`. Values are the JSON of the HAST nodes that
+ * 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. */
+    key(block: NgDocHighlightBlock): string;
+    get(key: string): string | undefined;
+    set(key: string, value: string): void;
+    /**
+     * Whether these themes are known to load, because the cache holds a block highlighted with them.
+     * Without that, a document is processed only after Shiki has loaded them, as without a cache, so
+     * that a theme that cannot load fails every document, even one without code.
+     */
+    loads?(themes: NgDocHighlightBlock['themes']): boolean;
+    /** Highlights every hit again, uses the fresh value and reports each difference. */
+    readonly verify?: boolean;
+    /** A hit whose fresh value differs (with `verify`). */
+    mismatch?(key: string): void;
+}
+/** The options of {@link cachedShikiPlugin}. */
+export interface CachedShikiOptions {
+    cache: NgDocHighlightCache;
+    themes: NgDocHighlightBlock['themes'];
+    /** 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;
+    /**
+     * 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.
+ *
+ * It selects the blocks exactly as the plugin does (`pre` elements whose first child is a `code`
+ * element with properties, with the language of its `language-*` class or the default language)
+ * and leaves the tree unchanged while it keys them. A miss is highlighted by the plugin's own
+ * transformer, on a tree that holds only that block, so it gets exactly the plugin's options,
+ * language fallback, meta parsing and transformers. A failing block throws the plugin's error at
+ * the same block, since a hit cannot fail (the cache holds only blocks that were highlighted), and
+ * nothing is stored for it. Every value is serialized before the tree is changed, and every block
+ * is replaced with nodes parsed from it, so later plugins, which change the tree, never change a
+ * value or a node another block shares. A document whose blocks all hit (or that has none) never
+ * 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,36 @@
 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;
+    /**
+     * A cache of highlighted code blocks. With it, code is highlighted by a Shiki highlighter that is
+     * set up once per thread and theme pair, and a block is highlighted only when the cache misses;
+     * the result is the same as without it. Without it, every call sets the highlighter up again
+     * and highlights every block.
+     */
+    highlight?: NgDocHighlightCache;
 }
 export interface NgDocHtmlProcessorOutput {
     content: 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>;