@minidocs/core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan1F
+
+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 NONINFRINGEMENT. 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/README.md

@@ -1,3 +1,12 @@
-# Temporary Holding Version
+# @minidocs/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework-agnostic logic behind [minidocs](https://github.com/Ivan-1F/minidocs): page trees, navigation state, previous and next pages, and tables of contents.
+
+Most sites use it through [`@minidocs/astro`](https://www.npmjs.com/package/@minidocs/astro), which re-exports what pages need from `@minidocs/astro/runtime`.
+
+> [!WARNING]
+> minidocs is experimental. Until 1.0, minor versions may include breaking changes.
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,138 @@
+//#region src/path.d.ts
+interface ParsedPath<L extends string> {
+  locale: L;
+  /**
+   * Locale-free page id, e.g. `concepts/primitives`. Directory index files use the directory path, the root index uses `index`.
+   * Route groups, directories named in parentheses like `(basics)`, are left out.
+   */
+  id: string;
+  /** Directory the page belongs to as it is on disk, route groups included, `''` for the root. An index file belongs to its own directory. */
+  dir: string;
+  isIndex: boolean;
+}
+/**
+ * Derives the locale and page id of a content file from its path.
+ * With `localeDirs: false`, files are not inside locale directories and all belong to the only locale.
+ */
+export declare function parseFilePath<L extends string>(filePath: string, base: string, locales: readonly L[], localeDirs?: boolean): ParsedPath<L>;
+//#endregion
+//#region src/content.d.ts
+interface EntryLike {
+  filePath?: string | undefined;
+}
+interface ContentOptions<L extends string> {
+  /** Collection root that `entry.filePath` starts with, e.g. `src/content/docs`. */
+  base: string;
+  locales: readonly L[];
+  /** Locales to try, in order, when a page is not translated. Locales without an entry never fall back. */
+  fallback?: Partial<Record<L, L | readonly L[]>>;
+  /**
+   * Whether content files sit inside locale directories. Defaults to `true`.
+   * Single-language sites set it to `false` with exactly one locale, which every file then belongs to.
+   */
+  localeDirs?: boolean;
+}
+/** A page as seen from one locale, possibly served with content from a fallback locale. */
+interface ResolvedPage<L extends string, E> {
+  id: string;
+  /** Locale the page is shown in. */
+  locale: L;
+  /** Locale the content actually comes from. Differs from `locale` only for fallback pages. */
+  contentLocale: L;
+  entry: E;
+  isFallback: boolean;
+  path: ParsedPath<L>;
+}
+/** Lists every page that needs a route, in every locale, including untranslated pages served through fallback. */
+export declare function listPages<L extends string, E extends EntryLike>(entries: readonly E[], options: ContentOptions<L>): Omit<ResolvedPage<L, E>, 'path'>[];
+//#endregion
+//#region src/query.d.ts
+/** The part of a node the queries rely on, so callers can pass trimmed-down node shapes. */
+interface AnyNode {
+  page?: {
+    id: string;
+  } | undefined;
+  children: AnyNode[];
+}
+/** Returns the previous and next page of a page in reading order. */
+export declare function neighbors<N extends AnyNode>(nodes: N[], id: string): {
+  prev: N | undefined;
+  next: N | undefined;
+};
+/** Returns the nodes from the root down to the first occurrence of a page, or an empty array if it is not in the tree. */
+export declare function findPath<N extends AnyNode>(nodes: N[], id: string): N[];
+interface NavState<N extends AnyNode> {
+  /** Whether a node is the current page, and whether the current page is the node itself or below it. */
+  of(node: N): {
+    current: boolean;
+    open: boolean;
+  };
+}
+/** Tracks where the current page sits in a tree, for marking and expanding navigation. */
+export declare function navState<N extends AnyNode>(nodes: N[], id: string): NavState<N>;
+//#endregion
+//#region src/toc.d.ts
+/** A heading as returned by Astro's `render(entry)`. */
+interface Heading {
+  depth: number;
+  slug: string;
+  text: string;
+}
+interface TocNode extends Heading {
+  children: TocNode[];
+}
+interface TocOptions {
+  /** Inclusive range of heading levels to keep. Defaults to `[2, 3]`. */
+  depth?: [min: number, max: number];
+}
+/** Nests a flat heading list into a tree. A heading that skips levels goes under the closest shallower heading. */
+export declare function tocTree(headings: readonly Heading[], options?: TocOptions): TocNode[];
+//#endregion
+//#region src/tree.d.ts
+interface PageRef<Id extends string, L extends string, E> {
+  id: Id;
+  /** Locale of the tree this node belongs to. */
+  locale: L;
+  /** Locale `entry` comes from. Differs from `locale` only for fallback pages. */
+  contentLocale: L;
+  entry: E;
+  /** True when `entry` comes from a fallback locale because the page is not translated. */
+  isFallback: boolean;
+}
+interface Node<Id extends string = string, L extends string = string, E = EntryLike> {
+  label: string;
+  page?: PageRef<Id, L, E>;
+  /** External link target, never set together with `page`. */
+  href?: string;
+  children: Node<Id, L, E>[];
+}
+type Tree<Id extends string, L extends string, E> = Record<L, Node<Id, L, E>[]>;
+interface TreeOptions<L extends string, E> extends ContentOptions<L> {
+  label: (entry: E) => string;
+}
+interface DirOptions<Id extends string, L extends string, E> {
+  /** Orders siblings. Without it, siblings are ordered by file or directory name. */
+  compare?: (a: Node<Id, L, E>, b: Node<Id, L, E>) => number;
+}
+interface BuildContext<Id extends string, L extends string, E> {
+  locale: L;
+  page: (id: Id, children?: Node<Id, L, E>[]) => Node<Id, L, E>;
+  group: (label: string, children: Node<Id, L, E>[]) => Node<Id, L, E>;
+  /**
+   * Returns the contents of a directory, excluding the directory's own index page.
+   * Route groups inside it add no level: their pages and directories join their siblings.
+   */
+  dir: (path: string, options?: DirOptions<Id, L, E>) => Node<Id, L, E>[];
+  link: (label: string, href: string) => Node<Id, L, E>;
+}
+type Build<Id extends string, L extends string, E> = (ctx: BuildContext<Id, L, E>) => Node<Id, L, E>[] | Promise<Node<Id, L, E>[]>;
+/** Thrown by `page()` for an id that the given entries do not contain in the locale or its fallbacks. */
+export declare class MissingPageError extends Error {
+  readonly id: string;
+  readonly locale: string;
+  constructor(id: string, locale: string, searched: readonly string[]);
+}
+/** Builds one navigation tree per locale by running `build` once for each locale. */
+export declare function createTree<Id extends string, L extends string, E extends EntryLike>(entries: readonly E[], options: TreeOptions<L, E>, build: Build<Id, L, E>): Promise<Tree<Id, L, E>>;
+//#endregion
+export type { BuildContext, ContentOptions, DirOptions, EntryLike, Heading, NavState, Node, PageRef, ParsedPath, ResolvedPage, TocNode, TocOptions, Tree, TreeOptions };

package/dist/index.mjs

@@ -0,0 +1,275 @@
+//#region src/path.ts
+/** Whether a directory name is a route group, which organizes files without becoming part of page ids. */
+function isRouteGroup(name) {
+	return /^\(.+\)$/.test(name);
+}
+function normalize(path) {
+	return path.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/+$/, "");
+}
+/**
+* Derives the locale and page id of a content file from its path.
+* With `localeDirs: false`, files are not inside locale directories and all belong to the only locale.
+*/
+function parseFilePath(filePath, base, locales, localeDirs = true) {
+	const file = normalize(filePath);
+	const root = normalize(base);
+	if (!file.startsWith(`${root}/`)) throw new Error(`File "${filePath}" is outside the content base "${base}".`);
+	const segments = file.slice(root.length + 1).split("/");
+	const locale = localeDirs ? segments.shift() : locales[0];
+	if (segments.length === 0 || !locales.includes(locale)) throw new Error(`File "${filePath}" must be inside a locale directory (${locales.join(", ")}).`);
+	const name = segments.pop().replace(/\.[^.]+$/, "");
+	const dir = segments.join("/");
+	const route = segments.filter((segment) => !isRouteGroup(segment)).join("/");
+	if (name === "index") return {
+		locale,
+		id: route || "index",
+		dir,
+		isIndex: true
+	};
+	return {
+		locale,
+		id: route ? `${route}/${name}` : name,
+		dir,
+		isIndex: false
+	};
+}
+//#endregion
+//#region src/content.ts
+function indexContent(entries, options) {
+	const { base, locales, fallback = {}, localeDirs = true } = options;
+	if (!localeDirs && locales.length !== 1) throw new Error("Content without locale directories must have exactly one locale.");
+	const chains = /* @__PURE__ */ new Map();
+	for (const locale of locales) chains.set(locale, [locale]);
+	for (const [locale, targets] of Object.entries(fallback)) {
+		if (!locales.includes(locale)) throw new Error(`Fallback is declared for unknown locale "${locale}".`);
+		for (const target of [targets ?? []].flat()) {
+			if (!locales.includes(target)) throw new Error(`Locale "${locale}" falls back to unknown locale "${target}".`);
+			const chain = chains.get(locale);
+			if (!chain.includes(target)) chain.push(target);
+		}
+	}
+	const own = new Map(locales.map((locale) => [locale, /* @__PURE__ */ new Map()]));
+	for (const entry of entries) {
+		if (!entry.filePath) throw new Error("Every entry must have a filePath.");
+		const path = parseFilePath(entry.filePath, base, locales, localeDirs);
+		const pages = own.get(path.locale);
+		const existing = pages.get(path.id);
+		if (existing) throw new Error(`"${existing.entry.filePath}" and "${entry.filePath}" both map to the page id "${path.id}".`);
+		pages.set(path.id, {
+			entry,
+			path
+		});
+	}
+	const cache = /* @__PURE__ */ new Map();
+	return {
+		chain: (locale) => chains.get(locale),
+		visible(locale) {
+			let visible = cache.get(locale);
+			if (visible) return visible;
+			visible = /* @__PURE__ */ new Map();
+			for (const contentLocale of chains.get(locale)) for (const [id, { entry, path }] of own.get(contentLocale)) {
+				if (visible.has(id)) continue;
+				visible.set(id, {
+					id,
+					locale,
+					contentLocale,
+					entry,
+					isFallback: contentLocale !== locale,
+					path
+				});
+			}
+			cache.set(locale, visible);
+			return visible;
+		}
+	};
+}
+/** Lists every page that needs a route, in every locale, including untranslated pages served through fallback. */
+function listPages(entries, options) {
+	const index = indexContent(entries, options);
+	return options.locales.flatMap((locale) => [...index.visible(locale).values()].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0).map(({ path: _, ...page }) => page));
+}
+//#endregion
+//#region src/query.ts
+/** Page nodes in reading order (depth-first, parents before children), keeping only the first occurrence of each page. */
+function pages(nodes, seen = /* @__PURE__ */ new Set(), out = []) {
+	for (const node of nodes) {
+		if (node.page && !seen.has(node.page.id)) {
+			seen.add(node.page.id);
+			out.push(node);
+		}
+		pages(node.children, seen, out);
+	}
+	return out;
+}
+/** Returns the previous and next page of a page in reading order. */
+function neighbors(nodes, id) {
+	const list = pages(nodes);
+	const index = list.findIndex((node) => node.page.id === id);
+	if (index === -1) return {
+		prev: void 0,
+		next: void 0
+	};
+	return {
+		prev: list[index - 1],
+		next: list[index + 1]
+	};
+}
+/** Returns the nodes from the root down to the first occurrence of a page, or an empty array if it is not in the tree. */
+function findPath(nodes, id) {
+	for (const node of nodes) {
+		if (node.page?.id === id) return [node];
+		const rest = findPath(node.children, id);
+		if (rest.length > 0) return [node, ...rest];
+	}
+	return [];
+}
+/** Tracks where the current page sits in a tree, for marking and expanding navigation. */
+function navState(nodes, id) {
+	const path = findPath(nodes, id);
+	const current = path.at(-1);
+	return { of: (node) => ({
+		current: node === current,
+		open: path.includes(node)
+	}) };
+}
+//#endregion
+//#region src/toc.ts
+/** Nests a flat heading list into a tree. A heading that skips levels goes under the closest shallower heading. */
+function tocTree(headings, options = {}) {
+	const [min, max] = options.depth ?? [2, 3];
+	const root = [];
+	const stack = [];
+	for (const { depth, slug, text } of headings) {
+		if (depth < min || depth > max) continue;
+		const node = {
+			depth,
+			slug,
+			text,
+			children: []
+		};
+		while (stack.length > 0 && stack.at(-1).depth >= depth) stack.pop();
+		(stack.at(-1)?.children ?? root).push(node);
+		stack.push(node);
+	}
+	return root;
+}
+//#endregion
+//#region src/tree.ts
+/** Thrown by `page()` for an id that the given entries do not contain in the locale or its fallbacks. */
+var MissingPageError = class extends Error {
+	id;
+	locale;
+	constructor(id, locale, searched) {
+		super(`Page "${id}" does not exist in locale "${locale}" (searched: ${searched.join(", ")}).`);
+		this.id = id;
+		this.locale = locale;
+		this.name = "MissingPageError";
+	}
+};
+/** Builds one navigation tree per locale by running `build` once for each locale. */
+async function createTree(entries, options, build) {
+	const { locales, label } = options;
+	const index = indexContent(entries, options);
+	const tree = {};
+	for (const locale of locales) tree[locale] = prune(await build(createContext(locale)));
+	return tree;
+	function createContext(locale) {
+		const visible = index.visible(locale);
+		function page(id, children = []) {
+			const resolved = visible.get(id);
+			if (!resolved) throw new MissingPageError(id, locale, index.chain(locale));
+			const { contentLocale, entry, isFallback } = resolved;
+			return {
+				label: label(entry),
+				page: {
+					id,
+					locale,
+					contentLocale,
+					entry,
+					isFallback
+				},
+				children
+			};
+		}
+		function group(text, children) {
+			return {
+				label: text,
+				children
+			};
+		}
+		function link(text, href) {
+			return {
+				label: text,
+				href,
+				children: []
+			};
+		}
+		function dir(path, dirOptions = {}) {
+			const root = path.replace(/^\/+|\/+$/g, "");
+			const pages = [...visible.values()].map((resolved) => resolved.path);
+			if (!pages.some((p) => root === "" || p.dir === root || p.dir.startsWith(`${root}/`))) throw new Error(`Directory "${path}" does not contain any page in locale "${locale}".`);
+			return list(root);
+			function list(current) {
+				const items = collect(current);
+				items.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+				const nodes = items.map((item) => item.node);
+				return dirOptions.compare ? nodes.sort(dirOptions.compare) : nodes;
+			}
+			function collect(current) {
+				const items = [];
+				const subdirs = /* @__PURE__ */ new Set();
+				for (const p of pages) if (p.dir === current) {
+					if (!p.isIndex) items.push({
+						name: p.id.slice(p.id.lastIndexOf("/") + 1),
+						node: page(p.id)
+					});
+				} else if (current === "" || p.dir.startsWith(`${current}/`)) {
+					const rest = current === "" ? p.dir : p.dir.slice(current.length + 1);
+					subdirs.add(rest.split("/")[0]);
+				}
+				for (const name of subdirs) {
+					const full = current === "" ? name : `${current}/${name}`;
+					if (isRouteGroup(name)) {
+						items.push(...collect(full));
+						continue;
+					}
+					const children = list(full);
+					const index = pages.find((p) => p.isIndex && indexDirs(full).includes(p.dir));
+					items.push({
+						name,
+						node: index ? page(index.id, children) : group(name, children)
+					});
+				}
+				return items;
+			}
+			function indexDirs(full) {
+				const dirs = [full];
+				for (const p of pages) {
+					if (!p.dir.startsWith(`${full}/`)) continue;
+					if (p.dir.slice(full.length + 1).split("/").every(isRouteGroup)) dirs.push(p.dir);
+				}
+				return dirs;
+			}
+		}
+		return {
+			locale,
+			page,
+			group,
+			dir,
+			link
+		};
+	}
+}
+/** Drops nodes that have no page, no link and no children left. */
+function prune(nodes) {
+	return nodes.flatMap((node) => {
+		const children = prune(node.children);
+		if (!node.page && !node.href && children.length === 0) return [];
+		return [{
+			...node,
+			children
+		}];
+	});
+}
+//#endregion
+export { MissingPageError, createTree, findPath, listPages, navState, neighbors, parseFilePath, tocTree };

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@minidocs/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Framework-agnostic logic for building documentation sites",
+  "keywords": [
+    "documentation",
+    "docs"
+  ],
+  "homepage": "https://github.com/Ivan-1F/minidocs#readme",
+  "bugs": "https://github.com/Ivan-1F/minidocs/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ivan-1F/minidocs.git",
+    "directory": "packages/core"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsdown": "^0.23.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  }
 }