@waveso/docs 0.1.0 → 0.3.0

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-import { StandardSchemaV1 } from "@standard-schema/spec";
 import { Root } from "hast";
+import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/types.d.ts
 /**
  * The frontmatter fields the package itself understands.
@@ -7,17 +7,24 @@ import { Root } from "hast";
  * Consumers extend this with their own schema — {@link DocsConfig.frontmatterSchema} —
  * and the extra fields flow through the generic parameter on {@link DocFile}
  * and friends rather than widening this interface.
+ *
+ * The optionals are spelled `?: T | undefined` because a schema written with
+ * `.optional()` instead of `.exactOptional()` infers exactly that shape, and
+ * under `exactOptionalPropertyTypes` the narrow spelling rejects it — as a
+ * nine-line error through Standard Schema's internals at the config, plus a
+ * `Property 'audience' does not exist on type 'DocFrontmatter'` at every read
+ * site, because the inference then collapses to this default.
  */
 interface DocFrontmatter {
   /** Page title. Used for `<h1>` fallbacks, `<title>`, and search. */
   title: string;
   /** One-line summary. Used for `<meta name="description">` and search. */
-  description?: string;
+  description?: string | undefined;
   /**
    * Sidebar label, when it should differ from {@link DocFrontmatter.title}.
    * Sidebars are narrow; page ancestors are not.
    */
-  label?: string;
+  label?: string | undefined;
   /**
    * Excluded from navigation, search and `generateStaticParams`.
    *
@@ -25,18 +32,18 @@ interface DocFrontmatter {
    * production builds, so branching on it would hide drafts in exactly the
    * place reviewers look. Gate on an explicit config flag instead.
    */
-  draft?: boolean;
+  draft?: boolean | undefined;
   /**
    * Previous URLs for this page, relative to the docs base path
    * (e.g. `['old-name', 'legacy/old-name']`). The Next adapter turns these
    * into permanent redirects so a rename never becomes a silent 404.
    */
-  aliases?: string[];
+  aliases?: string[] | undefined;
   /**
    * Sort weight within its directory, for directories without a `meta.json`.
    * Lower sorts first; pages without an order sort last, alphabetically.
    */
-  order?: number;
+  order?: number | undefined;
 }
 /**
  * A single documentation page discovered on disk.
@@ -75,7 +82,7 @@ interface DocNavPage {
 interface DocNavGroup {
   type: 'group';
   title: string;
-  href?: string;
+  href?: string | undefined;
   children: DocNavNode[];
 }
 /** A non-interactive heading between groups, from `"---Label---"` in meta.json. */
@@ -108,12 +115,12 @@ type DocNavNode = DocNavPage | DocNavGroup | DocNavSeparator | DocNavLink;
  */
 interface DocsMeta {
   /** Directory title, shown as the group heading. Defaults to the dirname. */
-  title?: string;
+  title?: string | undefined;
   /** Ordered entries. Omit to sort by frontmatter `order`, then alphabetically. */
   pages?: Array<string | {
     title: string;
     href: string;
-  }>;
+  }> | undefined;
 }
 /**
  * A heading captured from the rendered tree.
@@ -126,7 +133,16 @@ interface DocsMeta {
 interface TocEntry {
   id: string;
   text: string;
-  /** Heading level, 2–6. `h1` is the page title and is never in the TOC. */
+  /**
+   * Heading level. `h1` is the page title and is never in the TOC.
+   *
+   * In practice **2 or 3**: the capture stops at `h3`, measured on a synthetic
+   * API reference where taking `h2`–`h6` gave 104 entries against 32. Deeper
+   * headings keep their ids and permalinks, so they stay deep-linkable and
+   * still open their own sections in search — only the rail entry is dropped.
+   * `number` rather than `2 | 3` because `rehypePlugins` is the escape hatch
+   * for putting them back, and a literal union would make that a type error.
+   */
   depth: number;
   children: TocEntry[];
 }
@@ -244,12 +260,12 @@ href: string, from: DocLinkContext) => string | undefined;
  */
 type ImageResolver = (src: string, from: DocLinkContext) => Promise<{
   src: string;
-  width?: number;
-  height?: number;
+  width?: number | undefined;
+  height?: number | undefined;
 } | undefined> | {
   src: string;
-  width?: number;
-  height?: number;
+  width?: number | undefined;
+  height?: number | undefined;
 } | undefined;
 /**
  * How a documentation tree is read.
@@ -267,18 +283,18 @@ interface DocsConfig<TFrontmatter extends DocFrontmatter = DocFrontmatter> {
    */
   contentDir: string;
   /** URL prefix the docs are mounted at. Defaults to `'/docs'`. */
-  basePath?: string;
+  basePath?: string | undefined;
   /**
    * Include pages marked `draft: true`. Defaults to `false`.
    *
    * Drive this from your own env check — deliberately not `NODE_ENV`.
    */
-  includeDrafts?: boolean;
+  includeDrafts?: boolean | undefined;
   /**
    * Fail the build when an internal link resolves to a page that does not
    * exist. Defaults to `true`; there is no good reason to turn it off.
    */
-  assertLinks?: boolean;
+  assertLinks?: boolean | undefined;
   /**
    * Validates every page's frontmatter. Defaults to `docFrontmatterSchema`
    * from `@waveso/docs/frontmatter`.
@@ -301,21 +317,28 @@ interface DocsConfig<TFrontmatter extends DocFrontmatter = DocFrontmatter> {
    *
    * Three things are worth knowing before you write one:
    *
-   *  - **The output must still satisfy {@link DocFrontmatter}.** `title` drives
-   *    the `<h1>` fallback and `<title>`, `draft` the visibility filter,
-   *    `aliases` the redirects, `order`/`label` the sidebar. A schema that
-   *    drops them is a compile error here, not a mystery at render time.
+   *  - **The package's fields are not yours to drop.** `title` drives the
+   *    `<h1>` fallback and `<title>`, `draft` the visibility filter, `aliases`
+   *    the redirects, `order`/`label` the sidebar — so all six are re-read from
+   *    the YAML by `docFrontmatterSchema` and laid back over your output. A
+   *    bare `z.object({ title, audience })` therefore cannot publish a draft or
+   *    lose a redirect; it only costs you the six in the inferred type. Nothing
+   *    in the type system could have caught that: `TFrontmatter extends
+   *    DocFrontmatter` constrains `title` and nothing else, because the other
+   *    five are optional. The price is that a `.default()`, `.transform()` or
+   *    `.coerce` aimed at one of the six is not honoured — the YAML wins.
    *  - **Unknown keys are stripped, by every validator worth using.** The
-   *    parsed frontmatter is exactly what the schema declares, so declare every
-   *    field you intend to read — extending
-   *    `docFrontmatterSchema` is the shortest way to keep the built-ins.
+   *    parsed frontmatter is exactly what the schema declares plus the six, so
+   *    declare every field you intend to read — extending
+   *    `docFrontmatterSchema` is the shortest way to get the built-ins back in
+   *    the type as well.
    *  - **Identity is load-bearing.** The filesystem scan is memoised per
    *    resolved config, and two schema objects are only "the same schema" when
    *    they are the same object. Export one from a shared module (as above)
    *    rather than building it inline in each route file, or each file pays for
    *    its own scan.
    */
-  frontmatterSchema?: StandardSchemaV1<unknown, TFrontmatter>;
+  frontmatterSchema?: StandardSchemaV1<unknown, TFrontmatter> | undefined;
 }
 /** {@link DocsConfig} with defaults applied. */
 interface ResolvedDocsConfig<TFrontmatter extends DocFrontmatter = DocFrontmatter> {
@@ -324,11 +347,11 @@ interface ResolvedDocsConfig<TFrontmatter extends DocFrontmatter = DocFrontmatte
   includeDrafts: boolean;
   assertLinks: boolean;
   /**
-   * As supplied. Absent — never explicitly `undefined`, per
-   * `exactOptionalPropertyTypes` — when the built-in `docFrontmatterSchema`
-   * applies, so the default lives in one place: `parseFrontmatter`.
+   * As supplied. `resolveDocsConfig` omits the key rather than setting it to
+   * `undefined` when the built-in `docFrontmatterSchema` applies, so the
+   * default lives in exactly one place: `parseFrontmatter`.
    */
-  frontmatterSchema?: StandardSchemaV1<unknown, TFrontmatter>;
+  frontmatterSchema?: StandardSchemaV1<unknown, TFrontmatter> | undefined;
 }
 //#endregion
 export { DocFile, DocFrontmatter, DocLinkContext, DocNavGroup, DocNavLink, DocNavNode, DocNavPage, DocNavSeparator, DocsConfig, DocsMeta, ImageResolver, LinkResolver, RenderedDoc, ResolvedDocsConfig, SearchRecord, TocEntry };

package/package.json

@@ -1,22 +1,19 @@
 {
   "name": "@waveso/docs",
-  "version": "0.1.0",
-  "description": "Markdown documentation for Next.js — parsed to hast in Node at build time, rendered as your own React components, zero parser bytes in the browser",
+  "version": "0.3.0",
+  "description": "Zero parser bytes in the browser: markdown docs for Next.js, built to hast in Node and rendered as your components",
   "type": "module",
   "sideEffects": [
     "*.css"
   ],
   "license": "MIT",
+  "author": "Wave (https://github.com/wavedotso)",
   "keywords": [
+    "nextjs",
     "documentation",
-    "docs",
     "markdown",
-    "remark",
-    "rehype",
-    "shiki",
-    "nextjs",
     "react-server-components",
-    "static-site"
+    "shiki"
   ],
   "repository": {
     "type": "git",
@@ -25,7 +22,7 @@
   "homepage": "https://github.com/wavedotso/wave-docs#readme",
   "bugs": "https://github.com/wavedotso/wave-docs/issues",
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=22.12.0"
   },
   "exports": {
     "./package.json": "./package.json",
@@ -34,6 +31,10 @@
       "types": "./dist/types.d.ts",
       "default": "./dist/types.js"
     },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "default": "./dist/errors.js"
+    },
     "./frontmatter": {
       "types": "./dist/frontmatter.d.ts",
       "default": "./dist/frontmatter.js"
@@ -58,30 +59,59 @@
       "browser": null,
       "default": "./dist/search-index.js"
     },
-    "./search-options": {
-      "types": "./dist/search-options.d.ts",
-      "default": "./dist/search-options.js"
-    },
-    "./markdown-links": {
-      "types": "./dist/plugins/remark-doc-links.d.ts",
-      "default": "./dist/plugins/remark-doc-links.js"
-    },
     "./next": {
       "types": "./dist/next.d.ts",
       "browser": null,
       "default": "./dist/next.js"
     },
-    "./react/*": {
-      "types": "./dist/react/*.d.ts",
-      "default": "./dist/react/*.js"
+    "./react/callout": {
+      "types": "./dist/react/callout.d.ts",
+      "default": "./dist/react/callout.js"
+    },
+    "./react/doc-content": {
+      "types": "./dist/react/doc-content.d.ts",
+      "default": "./dist/react/doc-content.js"
+    },
+    "./react/markdown-components": {
+      "types": "./dist/react/markdown-components.d.ts",
+      "default": "./dist/react/markdown-components.js"
+    },
+    "./react/next-search": {
+      "types": "./dist/react/next-search.d.ts",
+      "default": "./dist/react/next-search.js"
+    },
+    "./react/search-dialog": {
+      "types": "./dist/react/search-dialog.d.ts",
+      "default": "./dist/react/search-dialog.js"
+    },
+    "./react/sidebar": {
+      "types": "./dist/react/sidebar.d.ts",
+      "default": "./dist/react/sidebar.js"
+    },
+    "./react/skip-link": {
+      "types": "./dist/react/skip-link.d.ts",
+      "default": "./dist/react/skip-link.js"
+    },
+    "./react/toc": {
+      "types": "./dist/react/toc.d.ts",
+      "default": "./dist/react/toc.js"
+    },
+    "./react/youtube": {
+      "types": "./dist/react/youtube.d.ts",
+      "default": "./dist/react/youtube.js"
     }
   },
   "files": [
     "dist",
     "package.json",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "dependencies": {
     "@shikijs/langs": "4.4.3",
     "@shikijs/rehype": "4.4.3",
@@ -89,7 +119,6 @@
     "@standard-schema/spec": "^1.1.0",
     "@types/hast": "^3.0.5",
     "@types/mdast": "^4.0.4",
-    "gray-matter": "^4.0.3",
     "hast-util-to-jsx-runtime": "^2.3.6",
     "hast-util-to-string": "^3.0.1",
     "minisearch": "^7.2.0",
@@ -102,21 +131,18 @@
     "shiki": "4.4.3",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
-    "vfile": "^6.0.3"
+    "vfile": "^6.0.3",
+    "vfile-matter": "^5.0.1",
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
     "next": "^16.0.0",
     "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "tailwindcss": "^4.0.0",
-    "zod": "^4.4.3"
+    "react-dom": "^19.0.0"
   },
   "peerDependenciesMeta": {
     "next": {
       "optional": true
-    },
-    "tailwindcss": {
-      "optional": true
     }
   },
   "devDependencies": {
@@ -129,22 +155,25 @@
     "@types/node": "^24.0.0",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.4",
+    "@vitest/browser": "4.1.10",
+    "@vitest/browser-playwright": "^4.1.10",
+    "hast-util-to-html": "^9.0.5",
     "image-size": "^2.0.2",
     "jsdom": "^30.0.1",
     "next": "^16.3.0",
+    "playwright": "^1.62.1",
     "publint": "^0.3.23",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
+    "rolldown": "^1.2.4",
     "tsdown": "^0.22.14",
     "typescript": "^5.9.3",
-    "unrun": "^0.3.1",
-    "vitest": "^4.1.10",
-    "zod": "^4.4.3"
+    "vitest": "^4.1.10"
   },
   "devEngines": {
     "runtime": {
       "name": "node",
-      "version": ">=22.18.0",
+      "version": ">=26.0.0",
       "onFail": "warn"
     }
   },
@@ -155,12 +184,19 @@
     "lint": "biome check",
     "lint:fix": "biome check --write",
     "format": "biome format --write",
-    "test": "vitest run",
+    "test": "vitest run --project node --project dom",
     "test:watch": "vitest",
     "check:package": "publint && attw --pack . --ignore-rules no-resolution cjs-resolves-to-esm",
+    "check:readme": "node scripts/check-readme.ts",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "changeset": "changeset",
     "version": "changeset version",
-    "release": "pnpm run build && changeset publish"
+    "release": "pnpm run build && changeset publish",
+    "test:browser": "vitest run --project browser",
+    "test:smoke": "node smoke/check.ts",
+    "size": "node scripts/size.ts",
+    "build:site": "next build site",
+    "dev:site": "next dev site",
+    "shoot": "node scripts/shoot.ts"
   }
 }