@ng-doc/utils 22.0.0-beta.1 → 22.0.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,68 @@
+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
+ * 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 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. 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.
+ */
+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'];
+    /** What `options` stands 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;
+}
+/**
+ * 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>;

package/html/process-html.d.ts

@@ -1,9 +1,18 @@
 import { NgDocHeading, NgDocPageAnchor } from '@ng-doc/core';
+import { NgDocHighlightCache } from './plugins/cached-shiki.plugin';
+export type { NgDocHighlightBlock, NgDocHighlightCache } from './plugins/cached-shiki.plugin';
 export interface NgDocHtmlProcessorConfig {
     lightTheme?: string;
     darkTheme?: string;
     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;