npm - @waveso/docs - Versions diffs - 0.2.0 → 0.3.0 - Mend

@waveso/docs 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (59) hide show

package/CHANGELOG.md +110 -0
package/README.md +490 -75
package/dist/code-frame.d.ts +29 -0
package/dist/code-frame.js +41 -0
package/dist/code-meta.d.ts +48 -0
package/dist/code-meta.js +72 -0
package/dist/docs-content-id.d.ts +19 -0
package/dist/docs-content-id.js +19 -0
package/dist/docs-error.d.ts +2 -57
package/dist/docs-error.js +3 -15
package/dist/errors.d.ts +94 -0
package/dist/errors.js +45 -0
package/dist/next.d.ts +153 -28
package/dist/next.js +65 -33
package/dist/plugins/rehype-capture-toc.js +26 -5
package/dist/plugins/rehype-code-frame.d.ts +10 -0
package/dist/plugins/rehype-code-frame.js +88 -0
package/dist/plugins/rehype-code-language.js +7 -1
package/dist/react/code-runtime.d.ts +14 -0
package/dist/react/code-runtime.js +161 -0
package/dist/react/doc-content.d.ts +39 -2
package/dist/react/doc-content.js +42 -10
package/dist/react/layout.d.ts +44 -0
package/dist/react/layout.js +65 -0
package/dist/react/nav.d.ts +28 -0
package/dist/react/nav.js +70 -0
package/dist/react/nearest-scroll-top.d.ts +45 -0
package/dist/react/nearest-scroll-top.js +44 -0
package/dist/react/next-link.d.ts +34 -0
package/dist/react/next-link.js +30 -0
package/dist/react/next-nav.d.ts +11 -0
package/dist/react/next-nav.js +32 -0
package/dist/react/next-search.d.ts +22 -0
package/dist/react/next-search.js +52 -0
package/dist/react/search-dialog.d.ts +20 -8
package/dist/react/search-dialog.js +15 -10
package/dist/react/shell-labels.d.ts +43 -0
package/dist/react/shell-labels.js +27 -0
package/dist/react/sidebar.d.ts +38 -3
package/dist/react/sidebar.js +104 -12
package/dist/react/skip-link.d.ts +1 -9
package/dist/react/skip-link.js +6 -5
package/dist/react/toc.d.ts +12 -4
package/dist/react/toc.js +18 -7
package/dist/react/youtube.d.ts +31 -5
package/dist/react/youtube.js +76 -54
package/dist/render.d.ts +35 -1
package/dist/render.js +35 -14
package/dist/route-path.d.ts +46 -0
package/dist/route-path.js +51 -0
package/dist/search-index.d.ts +6 -23
package/dist/search-index.js +6 -51
package/dist/sitemap-limit.d.ts +34 -0
package/dist/sitemap-limit.js +37 -0
package/dist/source.d.ts +1 -23
package/dist/source.js +40 -43
package/dist/styles.css +939 -93
package/dist/types.d.ts +11 -2
package/package.json +58 -23

package/dist/code-frame.d.ts ADDED Viewed

@@ -0,0 +1,29 @@
+import { Root } from "hast";
+//#region src/code-frame.d.ts
+/** Marks the `<figure>` a code block is wrapped in. */
+declare const CODE_FRAME_ATTRIBUTE = "data-wave-docs-code";
+/** The copy button inside that figure. */
+declare const CODE_COPY_ATTRIBUTE = "data-wave-docs-copy";
+/**
+ * Set on `<html>` by the runtime once its listener is attached.
+ *
+ * ⚠️ THIS IS WHAT CLOSES THE INERT-MARKUP TRAP, AND IT IS STRUCTURAL RATHER
+ * THAN DOCUMENTED. The button is in the HTML whether or not any JavaScript
+ * runs — a `renderToStaticMarkup` consumer, a reader with scripts off, anyone
+ * rendering the hast by hand. The stylesheet keeps it `visibility: hidden`
+ * until this attribute appears, which also takes it out of the tab order, so
+ * none of those readers meets a button that silently does nothing or a dead
+ * tab stop where a control should be.
+ */
+declare const CODE_READY_ATTRIBUTE = "data-wave-docs-code-ready";
+/**
+ * Whether a tree contains a code frame.
+ *
+ * `DocContent` asks before rendering the runtime, so a page with no fences
+ * ships zero extra bytes rather than a client component that finds nothing to
+ * do. The server has the tree in hand and this is one pass over it, so the
+ * check costs nothing the render was not already paying.
+ */
+declare function hasCodeFrame(tree: Root): boolean;
+//#endregion
+export { CODE_COPY_ATTRIBUTE, CODE_FRAME_ATTRIBUTE, CODE_READY_ATTRIBUTE, hasCodeFrame };

package/dist/code-frame.js ADDED Viewed

@@ -0,0 +1,41 @@
+//#region src/code-frame.ts
+/** Marks the `<figure>` a code block is wrapped in. */
+const CODE_FRAME_ATTRIBUTE = "data-wave-docs-code";
+/** The copy button inside that figure. */
+const CODE_COPY_ATTRIBUTE = "data-wave-docs-copy";
+/**
+* Set on `<html>` by the runtime once its listener is attached.
+*
+* ⚠️ THIS IS WHAT CLOSES THE INERT-MARKUP TRAP, AND IT IS STRUCTURAL RATHER
+* THAN DOCUMENTED. The button is in the HTML whether or not any JavaScript
+* runs — a `renderToStaticMarkup` consumer, a reader with scripts off, anyone
+* rendering the hast by hand. The stylesheet keeps it `visibility: hidden`
+* until this attribute appears, which also takes it out of the tab order, so
+* none of those readers meets a button that silently does nothing or a dead
+* tab stop where a control should be.
+*/
+const CODE_READY_ATTRIBUTE = "data-wave-docs-code-ready";
+/**
+* Whether a tree contains a code frame.
+*
+* `DocContent` asks before rendering the runtime, so a page with no fences
+* ships zero extra bytes rather than a client component that finds nothing to
+* do. The server has the tree in hand and this is one pass over it, so the
+* check costs nothing the render was not already paying.
+*/
+function hasCodeFrame(tree) {
+	return containsFrame(tree.children);
+}
+function containsFrame(nodes) {
+	for (const node of nodes) {
+		if (node.type !== "element") continue;
+		if (isCodeFrame(node)) return true;
+		if (containsFrame(node.children)) return true;
+	}
+	return false;
+}
+function isCodeFrame(node) {
+	return node.properties[CODE_FRAME_ATTRIBUTE] !== void 0;
+}
+//#endregion
+export { CODE_COPY_ATTRIBUTE, CODE_FRAME_ATTRIBUTE, CODE_READY_ATTRIBUTE, hasCodeFrame };

package/dist/code-meta.d.ts ADDED Viewed

@@ -0,0 +1,48 @@
+//#region src/code-meta.d.ts
+/**
+ * The bit after the language on a fence: ```` ```ts title="app/page.tsx" ````.
+ *
+ * Private — deliberately not an entry point. What a consumer sees is the
+ * `<figcaption>` it produces; the grammar is ours to extend.
+ *
+ * ## Read, never mutate
+ *
+ * `parseCodeMeta` takes a string and returns a value. It does not rewrite
+ * `code.data.meta`, and that restraint is the whole design: Shiki forwards the
+ * raw meta string to its transformers as `meta.__raw`, which is how
+ * `{1,3-5}` line highlighting and `showLineNumbers` will work when those land.
+ * A parser that consumed what it recognised would silently disable every
+ * feature it had not been taught about yet.
+ *
+ * ## Why `title=`
+ *
+ * Not a design question — a survey. Fumadocs, Starlight (via Expressive Code)
+ * and Docusaurus all spell it `title="…"`. Nextra's `filename=` and VitePress's
+ * `[filename]` are the minority, and `[…]` has nowhere to grow, so adopting it
+ * would mean two grammars in one meta string. `title` collides with frontmatter
+ * `title` as a word, which one comment fixes; making three of the five nearest
+ * comparators' users learn a second spelling does not have a fix.
+ *
+ * ## Unknown keys are ignored, malformed ones are not
+ *
+ * Shiki's meta string is an open namespace shared with its own transformers, so
+ * an author pasting `twoslash` or `{1,3}` from another site's documentation must
+ * not fail the build. But `title=app/page.tsx` — unquoted — is a *malformed*
+ * `title`, and ignoring it silently ships a caption reading `app/page.tsx` only
+ * up to the first space, or no caption at all. That throws, naming the file.
+ */
+/** What a fence's meta string asked for. */
+interface CodeMeta {
+  /** The `<figcaption>` text, and part of the copy button's accessible name. */
+  title?: string | undefined;
+}
+/**
+ * Read {@link CodeMeta} out of a fence's meta string.
+ *
+ * `path` is only ever used to name the offending document in an error. The
+ * alternative — an error saying `title=` was malformed, on a site with four
+ * hundred pages — is a grep.
+ */
+declare function parseCodeMeta(meta: string | undefined, path: string): CodeMeta;
+//#endregion
+export { CodeMeta, parseCodeMeta };

package/dist/code-meta.js ADDED Viewed

@@ -0,0 +1,72 @@
+import { docsError } from "./docs-error.js";
+//#region src/code-meta.ts
+/**
+* The bit after the language on a fence: ```` ```ts title="app/page.tsx" ````.
+*
+* Private — deliberately not an entry point. What a consumer sees is the
+* `<figcaption>` it produces; the grammar is ours to extend.
+*
+* ## Read, never mutate
+*
+* `parseCodeMeta` takes a string and returns a value. It does not rewrite
+* `code.data.meta`, and that restraint is the whole design: Shiki forwards the
+* raw meta string to its transformers as `meta.__raw`, which is how
+* `{1,3-5}` line highlighting and `showLineNumbers` will work when those land.
+* A parser that consumed what it recognised would silently disable every
+* feature it had not been taught about yet.
+*
+* ## Why `title=`
+*
+* Not a design question — a survey. Fumadocs, Starlight (via Expressive Code)
+* and Docusaurus all spell it `title="…"`. Nextra's `filename=` and VitePress's
+* `[filename]` are the minority, and `[…]` has nowhere to grow, so adopting it
+* would mean two grammars in one meta string. `title` collides with frontmatter
+* `title` as a word, which one comment fixes; making three of the five nearest
+* comparators' users learn a second spelling does not have a fix.
+*
+* ## Unknown keys are ignored, malformed ones are not
+*
+* Shiki's meta string is an open namespace shared with its own transformers, so
+* an author pasting `twoslash` or `{1,3}` from another site's documentation must
+* not fail the build. But `title=app/page.tsx` — unquoted — is a *malformed*
+* `title`, and ignoring it silently ships a caption reading `app/page.tsx` only
+* up to the first space, or no caption at all. That throws, naming the file.
+*/
+/**
+* `title="…"`, anywhere in the string, with the value in double quotes.
+*
+* A filename containing a double quote is inexpressible, and gets no escape
+* mechanism: no real path has one, and an escape grammar is a permanent tax on
+* every reader of this regex to serve a case that does not occur.
+*/
+const TITLE = /(^|\s)title="([^"]*)"/;
+/**
+* A `title=` at a word boundary, however it is spelled.
+*
+* Only consulted once {@link TITLE} has already failed, so reaching this means
+* the author wrote a title the one grammar cannot read — unquoted,
+* single-quoted, or opened and never closed. An earlier version excluded
+* anything followed by a quote, which let `title="a.ts` (no closing quote)
+* fall through and produce no caption at all, silently. That is the failure
+* this function exists to make loud.
+*/
+const MALFORMED_TITLE = /(^|\s)title=/;
+/**
+* Read {@link CodeMeta} out of a fence's meta string.
+*
+* `path` is only ever used to name the offending document in an error. The
+* alternative — an error saying `title=` was malformed, on a site with four
+* hundred pages — is a grep.
+*/
+function parseCodeMeta(meta, path) {
+	if (meta === void 0 || meta.trim() === "") return {};
+	const matched = TITLE.exec(meta);
+	if (matched === null) {
+		if (MALFORMED_TITLE.test(meta)) throw docsError("invalid-code-meta", `${path}: a code fence has a malformed \`title\`. Write it as \`title="app/page.tsx"\`, with double quotes — an unquoted title stops at the first space, and a title containing a double quote cannot be expressed. Got: \`${meta.trim()}\``);
+		return {};
+	}
+	const title = matched[2];
+	return title === void 0 || title === "" ? {} : { title };
+}
+//#endregion
+export { parseCodeMeta };

package/dist/docs-content-id.d.ts ADDED Viewed

@@ -0,0 +1,19 @@
+//#region src/docs-content-id.d.ts
+/**
+ * The id of the rendered `<article>`, and the target of the skip link.
+ *
+ * Private — deliberately not an entry point in `package.json`. The documented
+ * import is `@waveso/docs/react/skip-link`, which re-exports it; this module
+ * exists so `src/next.ts` can have the constant without importing a
+ * `'use client'` module for a string.
+ *
+ * One constant for both halves, and no way to change it. The two files spelled
+ * it independently once, and a skip link pointing at an id nothing carries
+ * scrolls nowhere and focuses nothing — a failure with no symptom until a
+ * keyboard user hits it. `createDocsRoute` used to accept a `contentId` option
+ * that broke exactly that pairing, silently, because `SkipLink` had no matching
+ * option to follow it with.
+ */
+declare const DOCS_CONTENT_ID = "docs-content";
+//#endregion
+export { DOCS_CONTENT_ID };

package/dist/docs-content-id.js ADDED Viewed

@@ -0,0 +1,19 @@
+//#region src/docs-content-id.ts
+/**
+* The id of the rendered `<article>`, and the target of the skip link.
+*
+* Private — deliberately not an entry point in `package.json`. The documented
+* import is `@waveso/docs/react/skip-link`, which re-exports it; this module
+* exists so `src/next.ts` can have the constant without importing a
+* `'use client'` module for a string.
+*
+* One constant for both halves, and no way to change it. The two files spelled
+* it independently once, and a skip link pointing at an id nothing carries
+* scrolls nowhere and focuses nothing — a failure with no symptom until a
+* keyboard user hits it. `createDocsRoute` used to accept a `contentId` option
+* that broke exactly that pairing, silently, because `SkipLink` had no matching
+* option to follow it with.
+*/
+const DOCS_CONTENT_ID = "docs-content";
+//#endregion
+export { DOCS_CONTENT_ID };

package/dist/docs-error.d.ts CHANGED Viewed

@@ -1,58 +1,5 @@
+import { DocsError, DocsErrorCode } from "./errors.js";
 //#region src/docs-error.d.ts
-/**
- * One error shape for the whole package.
- *
- * Private — deliberately not an entry point in `package.json`. Consumers get
- * the `code` off the error they already catch; they do not import a class and
- * they cannot `instanceof` against a copy of this module resolved twice.
- */
-/**
- * What went wrong, as something a consumer can branch on.
- *
- * Before this existed, every failure was a bare `Error` and roughly half the
- * messages omitted the package prefix, so a host wanting to downgrade (say)
- * broken-link failures in dev had nothing to test but the message text — and
- * `message.startsWith('@waveso/docs:')` was not even a reliable filter.
- */
-type DocsErrorCode =
-/** A link resolves to a route no published page owns. */
-'broken-link' |
-/** A link resolves to a page that exists but is `draft: true`. */
-'draft-link' |
-/** A link resolves to an alias, which is a redirect and not a page. */
-'alias-link' |
-/** An `aliases` entry is empty, escapes the root, or is not URL-safe. */
-'invalid-alias' |
-/** Two pages claim one alias, or an alias shadows a real route. */
-'alias-collision' |
-/** Two files resolve to the same route. */
-'route-collision' |
-/** A page's frontmatter is missing, malformed, or rejected by the schema. */
-'invalid-frontmatter' |
-/** A `meta.json` is malformed, or names something that is not there. */
-'invalid-meta' |
-/** An option passed to this package cannot be used as given. */
-'invalid-config' |
-/** `contentDir` does not point at a readable directory. */
-'missing-content-dir' |
-/** A markdown page is reachable only through a broken symbolic link. */
-'broken-symlink' |
-/** An `imageResolver` returned an unusable shape, threw, or was needed. */
-'invalid-image' |
-/** A theme name outside the supported set. */
-'unknown-theme' |
-/** A fence language outside the loaded set. */
-'unknown-language' |
-/** An optional peer (`next`) is absent or not the expected shape. */
-'missing-peer' |
-/** The search index could not be fetched or parsed. */
-'search-index-unavailable' |
-/** A plugin ran without the context this package always supplies. */
-'internal';
-/** An {@link Error} carrying a {@link DocsErrorCode}. */
-interface DocsError extends Error {
-  readonly code: DocsErrorCode;
-}
 /**
  * Build an error that names this package and says what class of thing failed.
  *
@@ -68,7 +15,5 @@ interface DocsError extends Error {
  * consumer does not care about, and also the ones a maintainer needs.
  */
 declare function docsError(code: DocsErrorCode, message: string, options?: ErrorOptions): DocsError;
-/** Narrow an unknown caught value to one of this package's errors. */
-declare function isDocsError(value: unknown): value is DocsError;
 //#endregion
-export { DocsError, DocsErrorCode, docsError, isDocsError };
+export { docsError };

package/dist/docs-error.js CHANGED Viewed

@@ -1,14 +1,6 @@
+import { DOCS_ERROR_PREFIX } from "./errors.js";
 //#region src/docs-error.ts
 /**
-* One error shape for the whole package.
-*
-* Private — deliberately not an entry point in `package.json`. Consumers get
-* the `code` off the error they already catch; they do not import a class and
-* they cannot `instanceof` against a copy of this module resolved twice.
-*/
-/** Prefix every message carries, so a stack trace names the culprit package. */
-const PREFIX = "@waveso/docs: ";
-/**
 * Build an error that names this package and says what class of thing failed.
 *
 * The message is passed through untouched apart from the prefix, which is added
@@ -23,7 +15,7 @@ const PREFIX = "@waveso/docs: ";
 * consumer does not care about, and also the ones a maintainer needs.
 */
 function docsError(code, message, options) {
-	const error = new Error(message.startsWith(PREFIX) ? message : `${PREFIX}${message}`, options);
+	const error = new Error(message.startsWith("@waveso/docs: ") ? message : `${DOCS_ERROR_PREFIX}${message}`, options);
 	Object.defineProperty(error, "code", {
 		value: code,
 		enumerable: false,
@@ -32,9 +24,5 @@ function docsError(code, message, options) {
 	});
 	return error;
 }
-/** Narrow an unknown caught value to one of this package's errors. */
-function isDocsError(value) {
-	return value instanceof Error && typeof value.code === "string" && value.message.startsWith(PREFIX);
-}
 //#endregion
-export { docsError, isDocsError };
+export { docsError };

package/dist/errors.d.ts ADDED Viewed

@@ -0,0 +1,94 @@
+//#region src/errors.d.ts
+/**
+ * The error taxonomy, as public API.
+ *
+ * Every failure this package raises is an `Error` whose message names the
+ * package and which carries a `code` off this union. That exists so a host can
+ * branch — downgrade broken-link failures in a preview build, say, or report
+ * `invalid-frontmatter` differently from `missing-peer` — and until this
+ * module was an entry point there was no supported way to do it. The taxonomy
+ * said "branch on this" while the module said "you cannot import me", and the
+ * two paragraphs contradicted each other for nineteen codes and forty-five
+ * call sites.
+ *
+ * ```ts
+ * import { isDocsError } from '@waveso/docs/errors';
+ *
+ * try {
+ *   await docs.renderAll();
+ * } catch (error) {
+ *   if (isDocsError(error) && error.code === 'draft-link') {
+ *     console.warn(error.message);
+ *   } else {
+ *     throw error;
+ *   }
+ * }
+ * ```
+ *
+ * No class is exported, and that is deliberate: `instanceof` against a copy of
+ * this module resolved twice — a monorepo with two versions installed, a
+ * bundler that duplicates it — silently answers `false`. A string `code` and a
+ * structural guard have no such failure mode.
+ */
+/** Prefix every message carries, so a stack trace names the culprit package. */
+declare const DOCS_ERROR_PREFIX = "@waveso/docs: ";
+/**
+ * What went wrong, as something a consumer can branch on.
+ *
+ * Before this existed, every failure was a bare `Error` and roughly half the
+ * messages omitted the package prefix, so a host wanting to downgrade (say)
+ * broken-link failures in dev had nothing to test but the message text — and
+ * `message.startsWith('@waveso/docs:')` was not even a reliable filter.
+ */
+type DocsErrorCode =
+/** A link resolves to a route no published page owns. */
+'broken-link' |
+/** A link resolves to a page that exists but is `draft: true`. */
+'draft-link' |
+/** A link resolves to an alias, which is a redirect and not a page. */
+'alias-link' |
+/** An `aliases` entry is empty, escapes the root, or is not URL-safe. */
+'invalid-alias' |
+/** Two pages claim one alias, or an alias shadows a real route. */
+'alias-collision' |
+/** Two files resolve to the same route. */
+'route-collision' |
+/** A page's frontmatter is missing, malformed, or rejected by the schema. */
+'invalid-frontmatter' |
+/** A `meta.json` is malformed, or names something that is not there. */
+'invalid-meta' |
+/** An option passed to this package cannot be used as given. */
+'invalid-config' |
+/** `contentDir` does not point at a readable directory. */
+'missing-content-dir' |
+/** A markdown page is reachable only through a broken symbolic link. */
+'broken-symlink' |
+/** An `imageResolver` returned an unusable shape, threw, or was needed. */
+'invalid-image' |
+/** A theme name outside the supported set. */
+'unknown-theme' |
+/** A fence language outside the loaded set. */
+'unknown-language' |
+/** An optional peer (`next`) is absent or not the expected shape. */
+'missing-peer' |
+/** The search index could not be fetched or parsed. */
+'search-index-unavailable' |
+/** The search-index route ran at request time instead of being prerendered. */
+'search-index-dynamic' |
+/** A code fence's meta string has a `title` that cannot be read. */
+'invalid-code-meta' |
+/** A plugin ran without the context this package always supplies. */
+'internal';
+/** An {@link Error} carrying a {@link DocsErrorCode}. */
+interface DocsError extends Error {
+  readonly code: DocsErrorCode;
+}
+/**
+ * Narrow an unknown caught value to one of this package's errors.
+ *
+ * Checks the prefix as well as the shape, so an unrelated `Error` that happens
+ * to carry a `code` — Node's own `ENOENT`, for one — is not mistaken for ours.
+ */
+declare function isDocsError(value: unknown): value is DocsError;
+//#endregion
+export { DOCS_ERROR_PREFIX, DocsError, DocsErrorCode, isDocsError };

package/dist/errors.js ADDED Viewed

@@ -0,0 +1,45 @@
+//#region src/errors.ts
+/**
+* The error taxonomy, as public API.
+*
+* Every failure this package raises is an `Error` whose message names the
+* package and which carries a `code` off this union. That exists so a host can
+* branch — downgrade broken-link failures in a preview build, say, or report
+* `invalid-frontmatter` differently from `missing-peer` — and until this
+* module was an entry point there was no supported way to do it. The taxonomy
+* said "branch on this" while the module said "you cannot import me", and the
+* two paragraphs contradicted each other for nineteen codes and forty-five
+* call sites.
+*
+* ```ts
+* import { isDocsError } from '@waveso/docs/errors';
+*
+* try {
+*   await docs.renderAll();
+* } catch (error) {
+*   if (isDocsError(error) && error.code === 'draft-link') {
+*     console.warn(error.message);
+*   } else {
+*     throw error;
+*   }
+* }
+* ```
+*
+* No class is exported, and that is deliberate: `instanceof` against a copy of
+* this module resolved twice — a monorepo with two versions installed, a
+* bundler that duplicates it — silently answers `false`. A string `code` and a
+* structural guard have no such failure mode.
+*/
+/** Prefix every message carries, so a stack trace names the culprit package. */
+const DOCS_ERROR_PREFIX = "@waveso/docs: ";
+/**
+* Narrow an unknown caught value to one of this package's errors.
+*
+* Checks the prefix as well as the shape, so an unrelated `Error` that happens
+* to carry a `code` — Node's own `ENOENT`, for one — is not mistaken for ours.
+*/
+function isDocsError(value) {
+	return value instanceof Error && typeof value.code === "string" && value.message.startsWith("@waveso/docs: ");
+}
+//#endregion
+export { DOCS_ERROR_PREFIX, isDocsError };