@astrojs/starlight 0.41.10 → 0.42.0

package/dist/user-components/file-tree-processor.d.ts

@@ -0,0 +1,16 @@
+//#region src/user-components/file-tree-processor.d.ts
+/**
+ * Process the HTML for a file tree to create the necessary markup for each file and directory
+ * including icons.
+ * @param html Inner HTML passed to the `<FileTree>` component.
+ * @param directoryLabel The localized label for a directory.
+ * @returns The processed HTML for the file tree.
+ */
+declare function processFileTree(html: string, directoryLabel: string): string;
+interface Definitions {
+  files: Record<string, string>;
+  extensions: Record<string, string>;
+  partials: Record<string, string>;
+}
+//#endregion
+export { Definitions, processFileTree };

package/dist/user-components/file-tree-processor.js

@@ -0,0 +1,132 @@
+import { definitions } from "./file-tree-icons.js";
+import { Icons } from "../components-internals/Icons.js";
+import { AstroError } from "astro/errors";
+import { htmlToHast } from "satteri";
+import { CONTINUE, SKIP, visit } from "unist-util-visit";
+import { toString } from "hast-util-to-string";
+import { h, s } from "hastscript";
+import { select } from "hast-util-select";
+import { toHtml } from "hast-util-to-html";
+//#region src/user-components/file-tree-processor.ts
+const folderIcon = makeSVGIcon(Icons["seti:folder"]);
+const defaultFileIcon = makeSVGIcon(Icons["seti:default"]);
+/**
+* Process the HTML for a file tree to create the necessary markup for each file and directory
+* including icons.
+* @param html Inner HTML passed to the `<FileTree>` component.
+* @param directoryLabel The localized label for a directory.
+* @returns The processed HTML for the file tree.
+*/
+function processFileTree(html, directoryLabel) {
+	const tree = htmlToHast(html, { fragment: true });
+	validateFileTree(tree);
+	visit(tree, "element", (node) => {
+		node.children = node.children.filter((child) => child.type === "comment" || child.type !== "text" || !/^\n+$/.test(child.value));
+		if (node.tagName !== "li") return CONTINUE;
+		const [firstChild, ...otherChildren] = node.children;
+		const comment = [];
+		if (firstChild?.type === "text") {
+			const [filename, ...fragments] = firstChild.value.split(" ");
+			firstChild.value = filename || "";
+			if (fragments.join(" ").trim().length > 0) comment.push(fragments.join(" "));
+		}
+		const subTreeIndex = otherChildren.findIndex((child) => child.type === "element" && child.tagName === "ul");
+		const commentNodes = subTreeIndex > -1 ? otherChildren.slice(0, subTreeIndex) : [...otherChildren];
+		otherChildren.splice(0, subTreeIndex > -1 ? subTreeIndex : otherChildren.length);
+		comment.push(...commentNodes);
+		const firstChildTextContent = firstChild ? toString(firstChild) : "";
+		const isDirectory = /\/\s*$/.test(firstChildTextContent) || otherChildren.some((child) => child.type === "element" && child.tagName === "ul");
+		const isPlaceholder = /^\s*(\.{3}|…)\s*$/.test(firstChildTextContent);
+		const isHighlighted = firstChild?.type === "element" && firstChild.tagName === "strong";
+		const icon = h("span", isDirectory ? folderIcon : getFileIcon(firstChildTextContent));
+		if (isDirectory) icon.children.unshift(h("span", { class: "sr-only" }, directoryLabel));
+		node.properties.class = isDirectory ? "directory" : "file";
+		if (isPlaceholder) node.properties.class += " empty";
+		const treeEntryChildren = [h("span", { class: isHighlighted ? "highlight" : "" }, [isPlaceholder ? null : icon, firstChild])];
+		if (comment.length > 0) treeEntryChildren.push(makeText(" "), h("span", { class: "comment" }, ...comment));
+		const treeEntry = h("span", { class: "tree-entry" }, ...treeEntryChildren);
+		if (isDirectory) {
+			const hasContents = otherChildren.length > 0;
+			node.children = [h("details", { open: hasContents }, [h("summary", treeEntry), ...hasContents ? otherChildren : [h("ul", h("li", "…"))]])];
+			return CONTINUE;
+		}
+		node.children = [treeEntry, ...otherChildren];
+		return SKIP;
+	});
+	return toHtml(tree);
+}
+/** Make a text node with the pass string as its contents. */
+function makeText(value = "") {
+	return {
+		type: "text",
+		value
+	};
+}
+/** Make a node containing an SVG icon from the passed HTML string. */
+function makeSVGIcon(svgString) {
+	return s("svg", {
+		width: 16,
+		height: 16,
+		class: "tree-icon",
+		"aria-hidden": "true",
+		viewBox: "0 0 24 24"
+	}, htmlToHast(svgString, {
+		fragment: true,
+		space: "svg"
+	}).children);
+}
+/** Return the icon for a file based on its file name. */
+function getFileIcon(fileName) {
+	const name = getFileIconName(fileName);
+	if (!name) return defaultFileIcon;
+	if (name in Icons) {
+		const path = Icons[name];
+		return makeSVGIcon(path);
+	}
+	return defaultFileIcon;
+}
+/** Return the icon name for a file based on its file name. */
+function getFileIconName(fileName) {
+	let icon = definitions.files[fileName];
+	if (icon) return icon;
+	icon = getFileIconTypeFromExtension(fileName);
+	if (icon) return icon;
+	for (const [partial, partialIcon] of Object.entries(definitions.partials)) if (fileName.includes(partial)) return partialIcon;
+	return icon;
+}
+/**
+* Get an icon from a file name based on its extension.
+* Note that an extension in Seti is everything after a dot, so `README.md` would be `.md` and
+* `name.with.dots` will try to look for an icon for `.with.dots` and then `.dots` if the first one
+* is not found.
+*/
+function getFileIconTypeFromExtension(fileName) {
+	const firstDotIndex = fileName.indexOf(".");
+	if (firstDotIndex === -1) return;
+	let extension = fileName.slice(firstDotIndex);
+	while (extension !== "") {
+		const icon = definitions.extensions[extension];
+		if (icon) return icon;
+		const nextDotIndex = extension.indexOf(".", 1);
+		if (nextDotIndex === -1) return;
+		extension = extension.slice(nextDotIndex);
+	}
+}
+/** Validate that the user provided HTML for a file tree is valid. */
+function validateFileTree(tree) {
+	const rootElements = tree.children.filter(isElementNode);
+	const [rootElement] = rootElements;
+	if (rootElements.length === 0) throwFileTreeValidationError("The `<FileTree>` component expects its content to be a single unordered list but found no child elements.");
+	if (rootElements.length !== 1) throwFileTreeValidationError(`The \`<FileTree>\` component expects its content to be a single unordered list but found multiple child elements: ${rootElements.map((element) => `\`<${element.tagName}>\``).join(" - ")}.`);
+	if (!rootElement || rootElement.tagName !== "ul") throwFileTreeValidationError(`The \`<FileTree>\` component expects its content to be an unordered list but found the following element: \`<${rootElement?.tagName}>\`.`);
+	if (!select("li", rootElement)) throwFileTreeValidationError("The `<FileTree>` component expects its content to be an unordered list with at least one list item.");
+}
+function isElementNode(node) {
+	return node.type === "element";
+}
+/** Throw a validation error for a file tree linking to the documentation. */
+function throwFileTreeValidationError(message) {
+	throw new AstroError(message, "To learn more about the `<FileTree>` component, see https://starlight.astro.build/components/file-tree/");
+}
+//#endregion
+export { processFileTree };

package/dist/user-components/steps-processor.d.ts

@@ -0,0 +1,10 @@
+//#region src/user-components/steps-processor.d.ts
+/**
+ * Process steps children: validates the HTML and adds `role="list"` to the ordered list.
+ * @param html Inner HTML passed to the `<Steps>` component.
+ */
+declare const processSteps: (html: string | undefined) => {
+  html: string;
+};
+//#endregion
+export { processSteps };

package/dist/user-components/steps-processor.js

@@ -0,0 +1,39 @@
+import { AstroError } from "astro/errors";
+import { htmlToHast } from "satteri";
+import { toHtml } from "hast-util-to-html";
+import { format } from "hast-util-format";
+//#region src/user-components/steps-processor.ts
+const prettyPrintHtml = (tree) => {
+	format(tree);
+	return toHtml(tree);
+};
+/**
+* Process steps children: validates the HTML and adds `role="list"` to the ordered list.
+* @param html Inner HTML passed to the `<Steps>` component.
+*/
+const processSteps = (html) => {
+	const tree = htmlToHast(html ?? "", { fragment: true });
+	const rootElements = tree.children.filter((item) => item.type === "element" && item.tagName !== "script");
+	const [rootElement] = rootElements;
+	if (!rootElement) throw new StepsError("The `<Steps>` component expects its content to be a single ordered list (`<ol>`) but found no child elements.");
+	else if (rootElements.length > 1) throw new StepsError("The `<Steps>` component expects its content to be a single ordered list (`<ol>`) but found multiple child elements: " + rootElements.map((element) => `\`<${element.tagName}>\``).join(", ") + ".", tree);
+	else if (rootElement.tagName !== "ol") throw new StepsError(`The \`<Steps>\` component expects its content to be a single ordered list (\`<ol>\`) but found the following element: \`<${rootElement.tagName}>\`.`, tree);
+	rootElement.properties.role = "list";
+	if (!Array.isArray(rootElement.properties.className)) rootElement.properties.className = ["sl-steps"];
+	else rootElement.properties.className.push("sl-steps");
+	if (typeof rootElement.properties.start === "number") {
+		const styles = [`--sl-steps-start: ${rootElement.properties.start - 1}`];
+		if (rootElement.properties.style) styles.push(String(rootElement.properties.style));
+		rootElement.properties.style = styles.join(";");
+	}
+	return { html: toHtml(tree) };
+};
+var StepsError = class extends AstroError {
+	constructor(message, tree) {
+		let hint = "To learn more about the `<Steps>` component, see https://starlight.astro.build/components/steps/";
+		if (tree) hint += "\n\nFull HTML passed to `<Steps>`:\n" + prettyPrintHtml(tree);
+		super(message, hint);
+	}
+};
+//#endregion
+export { processSteps };

package/dist/user-components/tabs-processor.d.ts

@@ -0,0 +1,23 @@
+import { StarlightIcon } from "../components-internals/Icons.js";
+//#region src/user-components/tabs-processor.d.ts
+interface Panel {
+  panelId: string;
+  tabId: string;
+  label: string;
+  icon?: StarlightIcon;
+}
+declare const TabItemTagname = "starlight-tab-item";
+/**
+ * Process tab panel items to extract data for the tab links and format
+ * each tab panel correctly.
+ * @param html Inner HTML passed to the `<Tabs>` component.
+ * @param index The index of the `<Tabs>` component on the page.
+ */
+declare const processPanels: (html: string, index: number) => {
+  /** Data for each tab panel. */
+  panels: Panel[];
+  /** Processed HTML for the tab panels. */
+  html: string;
+};
+//#endregion
+export { TabItemTagname, processPanels };

package/dist/user-components/tabs-processor.js

@@ -0,0 +1,70 @@
+import { htmlToHast } from "satteri";
+import { CONTINUE, SKIP, visit } from "unist-util-visit";
+import { select } from "hast-util-select";
+import { toHtml } from "hast-util-to-html";
+//#region src/user-components/tabs-processor.ts
+const TabItemTagname = "starlight-tab-item";
+const focusableElementSelectors = [
+	"input:not([disabled]):not([type=hidden])",
+	"select:not([disabled])",
+	"textarea:not([disabled])",
+	"button:not([disabled])",
+	"a[href]",
+	"area[href]",
+	"summary",
+	"iframe",
+	"object",
+	"embed",
+	"audio[controls]",
+	"video[controls]",
+	"[contenteditable]",
+	"[tabindex]:not([disabled])"
+].map((selector) => `${selector}:not([hidden]):not([tabindex="-1"])`).join(",");
+/**
+* Process tab panel items to extract data for the tab links and format
+* each tab panel correctly.
+* @param html Inner HTML passed to the `<Tabs>` component.
+* @param index The index of the `<Tabs>` component on the page.
+*/
+const processPanels = (html, index) => {
+	const tree = htmlToHast(html, { fragment: true });
+	const panels = [];
+	let isFirst = true;
+	let count = 0;
+	const getIDs = () => {
+		const id = count++;
+		return {
+			panelId: `tab-panel-${index}-${id}`,
+			tabId: `tab-${index}-${id}`
+		};
+	};
+	visit(tree, "element", (node) => {
+		if (node.tagName !== "starlight-tab-item" || !node.properties) return CONTINUE;
+		const { dataLabel, dataIcon } = node.properties;
+		const ids = getIDs();
+		const panel = {
+			...ids,
+			label: String(dataLabel)
+		};
+		if (dataIcon) panel.icon = String(dataIcon);
+		panels.push(panel);
+		delete node.properties.dataLabel;
+		delete node.properties.dataIcon;
+		node.tagName = "div";
+		node.properties.id = ids.panelId;
+		node.properties["aria-labelledby"] = ids.tabId;
+		node.properties.role = "tabpanel";
+		if (!select(focusableElementSelectors, node)) node.properties.tabindex = 0;
+		if (isFirst) isFirst = false;
+		else node.properties.hidden = true;
+		return SKIP;
+	});
+	return {
+		/** Data for each tab panel. */
+		panels,
+		/** Processed HTML for the tab panels. */
+		html: toHtml(tree)
+	};
+};
+//#endregion
+export { TabItemTagname, processPanels };

package/dist/utils/base.d.ts

@@ -0,0 +1,7 @@
+//#region src/utils/base.d.ts
+/** Get the a root-relative URL path with the site’s `base` prefixed. */
+declare function pathWithBase(path: string): string;
+/** Get the a root-relative file URL path with the site’s `base` prefixed. */
+declare function fileWithBase(path: string): string;
+//#endregion
+export { fileWithBase, pathWithBase };

package/dist/utils/base.js

@@ -0,0 +1,15 @@
+import { stripLeadingSlash, stripTrailingSlash } from "./path.js";
+//#region src/utils/base.ts
+const base = stripTrailingSlash(import.meta.env.BASE_URL);
+/** Get the a root-relative URL path with the site’s `base` prefixed. */
+function pathWithBase(path) {
+	path = stripLeadingSlash(path);
+	return path ? base + "/" + path : base + "/";
+}
+/** Get the a root-relative file URL path with the site’s `base` prefixed. */
+function fileWithBase(path) {
+	path = stripLeadingSlash(path);
+	return path ? base + "/" + path : base;
+}
+//#endregion
+export { fileWithBase, pathWithBase };

package/dist/utils/canonical.d.ts

@@ -0,0 +1,10 @@
+import { AstroConfig } from "astro";
+//#region src/utils/canonical.d.ts
+interface FormatCanonicalOptions {
+  format: AstroConfig['build']['format'];
+  trailingSlash: AstroConfig['trailingSlash'];
+}
+/** Format a canonical link based on the project config. */
+declare function formatCanonical(href: string, opts: FormatCanonicalOptions): string;
+//#endregion
+export { FormatCanonicalOptions, formatCanonical };

package/dist/utils/canonical.js

@@ -0,0 +1,14 @@
+import { ensureTrailingSlash, stripTrailingSlash } from "./path.js";
+//#region src/utils/canonical.ts
+const canonicalTrailingSlashStrategies = {
+	always: ensureTrailingSlash,
+	never: stripTrailingSlash,
+	ignore: ensureTrailingSlash
+};
+/** Format a canonical link based on the project config. */
+function formatCanonical(href, opts) {
+	if (opts.format === "file") return href;
+	return canonicalTrailingSlashStrategies[opts.trailingSlash](href);
+}
+//#endregion
+export { formatCanonical };

package/dist/utils/collection-fs.d.ts

@@ -0,0 +1,13 @@
+import { StarlightCollection } from "./collection.js";
+//#region src/utils/collection-fs.d.ts
+/**
+ * @see {@link file://./collection.ts} for more context about this file.
+ *
+ * Below are various functions to easily get paths to collections used in Starlight that rely on
+ * Node.js builtins. They exist in a separate file from {@link file://./collection.ts} to avoid
+ * potentially importing Node.js builtins in the final bundle.
+ */
+declare function resolveCollectionPath(collection: StarlightCollection, srcDir: URL): string;
+declare function getCollectionPosixPath(collection: StarlightCollection, srcDir: URL): string;
+//#endregion
+export { getCollectionPosixPath, resolveCollectionPath };

package/dist/utils/collection-fs.js

@@ -0,0 +1,19 @@
+import { getCollectionUrl } from "./collection.js";
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+//#region src/utils/collection-fs.ts
+/**
+* @see {@link file://./collection.ts} for more context about this file.
+*
+* Below are various functions to easily get paths to collections used in Starlight that rely on
+* Node.js builtins. They exist in a separate file from {@link file://./collection.ts} to avoid
+* potentially importing Node.js builtins in the final bundle.
+*/
+function resolveCollectionPath(collection, srcDir) {
+	return resolve(fileURLToPath(srcDir), `content/${collection}`);
+}
+function getCollectionPosixPath(collection, srcDir) {
+	return fileURLToPath(getCollectionUrl(collection, srcDir), { windows: false });
+}
+//#endregion
+export { getCollectionPosixPath, resolveCollectionPath };

package/{utils/collection.ts → dist/utils/collection.d.ts}

@@ -1,5 +1,5 @@
-export type StarlightCollection = 'docs' | 'i18n';
-
+//#region src/utils/collection.d.ts
+type StarlightCollection = 'docs' | 'i18n';
 /**
  * We still rely on the content collection folder structure to be fixed for now:
  *
@@ -17,21 +17,10 @@ export type StarlightCollection = 'docs' | 'i18n';
  * hardcode them throughout the codebase. When user-defined content folder locations are supported,
  * these helper functions should be updated to reflect that in one place.
  */
-
-export function getCollectionUrl(collection: StarlightCollection, srcDir: URL) {
-	return new URL(`content/${collection}/`, srcDir);
-}
-
-export function getCollectionPathFromRoot(
-	collection: StarlightCollection,
-	{ root, srcDir }: { root: URL | string; srcDir: URL | string }
-) {
-	return (
-		(typeof srcDir === 'string' ? srcDir : srcDir.pathname).replace(
-			typeof root === 'string' ? root : root.pathname,
-			''
-		) +
-		'content/' +
-		collection
-	);
-}
+declare function getCollectionUrl(collection: StarlightCollection, srcDir: URL): URL;
+declare function getCollectionPathFromRoot(collection: StarlightCollection, { root, srcDir }: {
+  root: URL | string;
+  srcDir: URL | string;
+}): string;
+//#endregion
+export { StarlightCollection, getCollectionPathFromRoot, getCollectionUrl };

package/dist/utils/collection.js

@@ -0,0 +1,26 @@
+//#region src/utils/collection.ts
+/**
+* We still rely on the content collection folder structure to be fixed for now:
+*
+* - At build time, if the feature is enabled, we get all the last commit dates for each file in
+*   the docs folder ahead of time. In the current approach, we cannot know at this time the
+*   user-defined content folder path in the integration context as this would only be available
+*   from the loader. A potential solution could be to do that from a custom loader re-implementing
+*   the glob loader or built on top of it. Although, we don't have access to the Starlight
+*   configuration from the loader to even know we should do that.
+* - Remark plugins get passed down an absolute path to a content file and we need to figure out
+*   the language from that path. Without knowing the content folder path, we cannot reliably do
+*   so.
+*
+* Below are various functions to easily get paths to these collections and avoid having to
+* hardcode them throughout the codebase. When user-defined content folder locations are supported,
+* these helper functions should be updated to reflect that in one place.
+*/
+function getCollectionUrl(collection, srcDir) {
+	return new URL(`content/${collection}/`, srcDir);
+}
+function getCollectionPathFromRoot(collection, { root, srcDir }) {
+	return (typeof srcDir === "string" ? srcDir : srcDir.pathname).replace(typeof root === "string" ? root : root.pathname, "") + "content/" + collection;
+}
+//#endregion
+export { getCollectionPathFromRoot, getCollectionUrl };

package/dist/utils/createPathFormatter.d.ts

@@ -0,0 +1,9 @@
+import { AstroConfig } from "astro";
+//#region src/utils/createPathFormatter.d.ts
+interface FormatPathOptions {
+  format?: AstroConfig['build']['format'];
+  trailingSlash?: AstroConfig['trailingSlash'];
+}
+declare function createPathFormatter(opts: FormatPathOptions): (href: string) => string;
+//#endregion
+export { createPathFormatter };

package/dist/utils/createPathFormatter.js

@@ -0,0 +1,35 @@
+import { ensureHtmlExtension, ensureTrailingSlash, stripHtmlExtension, stripTrailingSlash } from "./path.js";
+import { fileWithBase, pathWithBase } from "./base.js";
+//#region src/utils/createPathFormatter.ts
+const defaultFormatStrategy = {
+	addBase: pathWithBase,
+	handleExtension: (href) => stripHtmlExtension(href)
+};
+const formatStrategies = {
+	file: {
+		addBase: fileWithBase,
+		handleExtension: (href) => ensureHtmlExtension(href)
+	},
+	directory: defaultFormatStrategy,
+	preserve: defaultFormatStrategy
+};
+const trailingSlashStrategies = {
+	always: ensureTrailingSlash,
+	never: stripTrailingSlash,
+	ignore: (href) => href
+};
+/** Format a path based on the project config. */
+function formatPath(href, { format = "directory", trailingSlash = "ignore" }) {
+	const formatStrategy = formatStrategies[format];
+	const trailingSlashStrategy = trailingSlashStrategies[trailingSlash];
+	href = formatStrategy.handleExtension(href);
+	href = formatStrategy.addBase(href);
+	if (format === "file") return href;
+	href = href === "/" ? href : trailingSlashStrategy(href);
+	return href;
+}
+function createPathFormatter(opts) {
+	return (href) => formatPath(href, opts);
+}
+//#endregion
+export { createPathFormatter };

package/dist/utils/createTranslationSystem.d.ts

@@ -0,0 +1,23 @@
+import { StarlightConfig } from "./user-config.js";
+import { i18nSchemaOutput } from "../schemas/i18n.js";
+import _default from "../translations/index.js";
+import { UserI18nKeys, UserI18nSchema } from "./translations.js";
+import { ExistsFunction, TFunction } from "i18next";
+//#region src/utils/createTranslationSystem.d.ts
+/**
+ * The namespace for i18next resources used by Starlight.
+ * All translations handled by Starlight are stored in the same namespace and Starlight always use
+ * a new instance of i18next configured for this namespace.
+ */
+declare const i18nextNamespace: "starlight";
+type I18nextNamespace = typeof i18nextNamespace;
+declare function createTranslationSystem<T extends i18nSchemaOutput>(config: Pick<StarlightConfig, 'defaultLocale' | 'locales'>, userTranslations: Record<string, T>, pluginTranslations?: Record<string, T>): Promise<(lang: string | undefined) => I18nT>;
+type BuiltInStrings = (typeof _default)['en'];
+type I18nKeys = keyof BuiltInStrings | UserI18nKeys | keyof StarlightApp.I18n;
+type I18nT = TFunction<'starlight', undefined> & {
+  all: () => UserI18nSchema;
+  exists: ExistsFunction;
+  dir: (lang?: string) => 'ltr' | 'rtl';
+};
+//#endregion
+export { I18nKeys, I18nT, I18nextNamespace, createTranslationSystem };

package/dist/utils/createTranslationSystem.js

@@ -0,0 +1,84 @@
+import { BuiltInDefaultLocale } from "./i18n.js";
+import translations_default from "../translations/index.js";
+import i18next from "i18next";
+//#region src/utils/createTranslationSystem.ts
+/**
+* The namespace for i18next resources used by Starlight.
+* All translations handled by Starlight are stored in the same namespace and Starlight always use
+* a new instance of i18next configured for this namespace.
+*/
+const i18nextNamespace = "starlight";
+async function createTranslationSystem(config, userTranslations, pluginTranslations = {}) {
+	const defaultLocale = config.defaultLocale.lang || config.defaultLocale?.locale || BuiltInDefaultLocale.lang;
+	const translations = { [defaultLocale]: buildResources(translations_default[defaultLocale] || translations_default[stripLangRegion(defaultLocale)], pluginTranslations[defaultLocale], userTranslations[defaultLocale]) };
+	if (config.locales) for (const locale in config.locales) {
+		const lang = localeToLang(locale, config.locales, config.defaultLocale);
+		translations[lang] = buildResources(translations_default[lang] || translations_default[stripLangRegion(lang)], pluginTranslations[lang], userTranslations[lang]);
+	}
+	const i18n = i18next.createInstance();
+	await i18n.init({
+		resources: translations,
+		fallbackLng: config.defaultLocale.lang || config.defaultLocale?.locale || BuiltInDefaultLocale.lang
+	});
+	/**
+	* Generate a utility function that returns UI strings for the given language.
+	*
+	* Also includes a few utility methods:
+	* - `all()` method for getting the entire dictionary.
+	* - `exists()` method for checking if a key exists in the dictionary.
+	* - `dir()` method for getting the text direction of the locale.
+	*
+	* @param {string | undefined} [lang]
+	* @example
+	* const t = useTranslations('en');
+	* const label = t('search.label');
+	* // => 'Search'
+	* const dictionary = t.all();
+	* // => { 'skipLink.label': 'Skip to content', 'search.label': 'Search', ... }
+	* const exists = t.exists('search.label');
+	* // => true
+	* const dir = t.dir();
+	* // => 'ltr'
+	*/
+	return (lang) => {
+		lang ??= config.defaultLocale?.lang || BuiltInDefaultLocale.lang;
+		const t = i18n.getFixedT(lang, i18nextNamespace);
+		t.all = () => i18n.getResourceBundle(lang, i18nextNamespace);
+		t.exists = ((key, options) => i18n.exists(key, {
+			lng: lang,
+			ns: i18nextNamespace,
+			...options
+		}));
+		t.dir = (dirLang = lang) => i18n.dir(dirLang);
+		return t;
+	};
+}
+/**
+* Strips the region subtag from a BCP-47 lang string.
+* @param {string} [lang]
+* @example
+* const lang = stripLangRegion('en-GB'); // => 'en'
+*/
+function stripLangRegion(lang) {
+	return lang.replace(/-[a-zA-Z]{2}/, "");
+}
+/**
+* Get the BCP-47 language tag for the given locale.
+* @param locale Locale string or `undefined` for the root locale.
+*/
+function localeToLang(locale, locales, defaultLocale) {
+	const lang = locale ? locales?.[locale]?.lang : locales?.root?.lang;
+	const defaultLang = defaultLocale?.lang || defaultLocale?.locale;
+	return lang || defaultLang || BuiltInDefaultLocale.lang;
+}
+/** Build an i18next resources dictionary by layering preferred translation sources. */
+function buildResources(...dictionaries) {
+	const dictionary = {};
+	for (const dict of dictionaries) for (const key in dict) {
+		const value = dict[key];
+		if (value) dictionary[key] = value;
+	}
+	return { [i18nextNamespace]: dictionary };
+}
+//#endregion
+export { createTranslationSystem };

package/dist/utils/error-map.d.ts

@@ -0,0 +1,23 @@
+import { z } from "astro/zod";
+//#region src/utils/error-map.d.ts
+/**
+ * Parse data with a Zod schema and throw a nicely formatted error if it is invalid.
+ *
+ * @param schema The Zod schema to use to parse the input.
+ * @param input Input data that should match the schema.
+ * @param message Error message preamble to use if the input fails to parse.
+ * @returns Validated data parsed by Zod.
+ */
+declare function parseWithFriendlyErrors<T extends z.ZodType>(schema: T, input: z.input<T>, message: string): z.output<T>;
+/**
+ * Asynchronously parse data with a Zod schema that contains asynchronous refinements or transforms
+ * and throw a nicely formatted error if it is invalid.
+ *
+ * @param schema The Zod schema to use to parse the input.
+ * @param input Input data that should match the schema.
+ * @param message Error message preamble to use if the input fails to parse.
+ * @returns Validated data parsed by Zod.
+ */
+declare function parseAsyncWithFriendlyErrors<T extends z.ZodType>(schema: T, input: z.input<T>, message: string): Promise<z.output<T>>;
+//#endregion
+export { parseAsyncWithFriendlyErrors, parseWithFriendlyErrors };