@astrojs/starlight 0.19.1 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @astrojs/starlight
 
+## 0.20.0
+
+### Minor Changes
+
+- [#1541](https://github.com/withastro/starlight/pull/1541) [`1043052f`](https://github.com/withastro/starlight/commit/1043052f3890a577a73276472f3773924909406b) Thanks [@hippotastic](https://github.com/hippotastic)! - Updates `astro-expressive-code` dependency to the latest minor release (0.33).
+
+  This unlocks support for [word wrap](https://expressive-code.com/key-features/word-wrap/) and [line numbers](https://expressive-code.com/plugins/line-numbers/), as well as updating the syntax highlighter to the latest Shiki release, which includes new and updated language grammars.
+
+  See the [Expressive Code release notes](https://expressive-code.com/releases/) for more information including details of potentially breaking changes.
+
+### Patch Changes
+
+- [#1542](https://github.com/withastro/starlight/pull/1542) [`b3b7a606`](https://github.com/withastro/starlight/commit/b3b7a6069952d5f27a49b2fd097aa4db065e1718) Thanks [@delucis](https://github.com/delucis)! - Improves error messages shown by Starlight for configuration errors.
+
+- [#1544](https://github.com/withastro/starlight/pull/1544) [`65dc6586`](https://github.com/withastro/starlight/commit/65dc6586ef7c1754875db1d48c49e709051a0b13) Thanks [@torn4dom4n](https://github.com/torn4dom4n)! - Update Vietnamese UI translations
+
 ## 0.19.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",
@@ -172,9 +172,9 @@
   "devDependencies": {
     "@astrojs/markdown-remark": "^4.2.1",
     "@types/node": "^18.16.19",
-    "@vitest/coverage-v8": "^1.2.2",
+    "@vitest/coverage-v8": "^1.3.1",
     "astro": "^4.3.5",
-    "vitest": "^1.2.2"
+    "vitest": "^1.3.1"
   },
   "dependencies": {
     "@astrojs/mdx": "^2.1.1",
@@ -182,7 +182,7 @@
     "@pagefind/default-ui": "^1.0.3",
     "@types/hast": "^3.0.3",
     "@types/mdast": "^4.0.3",
-    "astro-expressive-code": "^0.32.4",
+    "astro-expressive-code": "^0.33.2",
     "bcp-47": "^2.1.0",
     "hast-util-select": "^6.0.2",
     "hastscript": "^8.0.0",

package/translations/vi.json

@@ -19,8 +19,8 @@
   "page.previousLink": "Tiếp",
   "page.nextLink": "Trước",
   "404.text": "Không tìm thấy trang. Kiểm tra URL hoặc thử sử dụng thanh tìm kiếm.",
-  "aside.note": "Note",
-  "aside.tip": "Tip",
-  "aside.caution": "Caution",
-  "aside.danger": "Danger"
+  "aside.note": "Ghi chú",
+  "aside.tip": "Mẹo",
+  "aside.caution": "Thận trọng",
+  "aside.danger": "Nguy hiểm"
 }

package/utils/error-map.ts

@@ -3,6 +3,7 @@
  * source: https://github.com/withastro/astro/blob/main/packages/astro/src/content/error-map.ts
  */
 
+import { AstroError } from 'astro/errors';
 import type { z } from 'astro:content';
 
 type TypeOrLiteralErrByPathEntry = {
@@ -11,11 +12,27 @@ type TypeOrLiteralErrByPathEntry = {
 	expected: unknown[];
 };
 
-export function throwValidationError(error: z.ZodError, message: string): never {
-	throw new Error(`${message}\n${error.issues.map((i) => i.message).join('\n')}`);
+/**
+ * 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.
+ */
+export function parseWithFriendlyErrors<T extends z.Schema>(
+	schema: T,
+	input: z.input<T>,
+	message: string
+): z.output<T> {
+	const parsedConfig = schema.safeParse(input, { errorMap });
+	if (!parsedConfig.success) {
+		throw new AstroError(message, parsedConfig.error.issues.map((i) => i.message).join('\n'));
+	}
+	return parsedConfig.data;
 }
 
-export const errorMap: z.ZodErrorMap = (baseError, ctx) => {
+const errorMap: z.ZodErrorMap = (baseError, ctx) => {
 	const baseErrorPath = flattenErrorPath(baseError.path);
 	if (baseError.code === 'invalid_union') {
 		// Optimization: Combine type and literal errors for keys that are common across ALL union types
@@ -38,30 +55,51 @@ export const errorMap: z.ZodErrorMap = (baseError, ctx) => {
 				}
 			}
 		}
-		let messages: string[] = [
-			prefix(
-				baseErrorPath,
-				typeOrLiteralErrByPath.size ? 'Did not match union:' : 'Did not match union.'
-			),
-		];
+		const messages: string[] = [prefix(baseErrorPath, 'Did not match union.')];
+		const details: string[] = [...typeOrLiteralErrByPath.entries()]
+			// If type or literal error isn't common to ALL union types,
+			// filter it out. Can lead to confusing noise.
+			.filter(([, error]) => error.expected.length === baseError.unionErrors.length)
+			.map(([key, error]) =>
+				key === baseErrorPath
+					? // Avoid printing the key again if it's a base error
+					  `> ${getTypeOrLiteralMsg(error)}`
+					: `> ${prefix(key, getTypeOrLiteralMsg(error))}`
+			);
+
+		if (details.length === 0) {
+			const expectedShapes: string[] = [];
+			for (const unionError of baseError.unionErrors) {
+				const expectedShape: string[] = [];
+				for (const issue of unionError.issues) {
+					// If the issue is a nested union error, show the associated error message instead of the
+					// base error message.
+					if (issue.code === 'invalid_union') {
+						return errorMap(issue, ctx);
+					}
+					const relativePath = flattenErrorPath(issue.path)
+						.replace(baseErrorPath, '')
+						.replace(leadingPeriod, '');
+					if ('expected' in issue && typeof issue.expected === 'string') {
+						expectedShape.push(
+							relativePath ? `${relativePath}: ${issue.expected}` : issue.expected
+						);
+					} else {
+						expectedShape.push(relativePath);
+					}
+				}
+				expectedShapes.push(`{ ${expectedShape.join('; ')} }`);
+			}
+			if (expectedShapes.length) {
+				details.push('> Expected type `' + expectedShapes.join(' | ') + '`');
+				details.push('> Received `' + stringify(ctx.data) + '`');
+			}
+		}
+
 		return {
-			message: messages
-				.concat(
-					[...typeOrLiteralErrByPath.entries()]
-						// If type or literal error isn't common to ALL union types,
-						// filter it out. Can lead to confusing noise.
-						.filter(([, error]) => error.expected.length === baseError.unionErrors.length)
-						.map(([key, error]) =>
-							key === baseErrorPath
-								? // Avoid printing the key again if it's a base error
-								  `> ${getTypeOrLiteralMsg(error)}`
-								: `> ${prefix(key, getTypeOrLiteralMsg(error))}`
-						)
-				)
-				.join('\n'),
+			message: messages.concat(details).join('\n'),
 		};
-	}
-	if (baseError.code === 'invalid_literal' || baseError.code === 'invalid_type') {
+	} else if (baseError.code === 'invalid_literal' || baseError.code === 'invalid_type') {
 		return {
 			message: prefix(
 				baseErrorPath,
@@ -84,25 +122,25 @@ const getTypeOrLiteralMsg = (error: TypeOrLiteralErrByPathEntry): string => {
 	const expectedDeduped = new Set(error.expected);
 	switch (error.code) {
 		case 'invalid_type':
-			return `Expected type \`${unionExpectedVals(expectedDeduped)}\`, received ${JSON.stringify(
+			return `Expected type \`${unionExpectedVals(expectedDeduped)}\`, received \`${stringify(
 				error.received
-			)}`;
+			)}\``;
 		case 'invalid_literal':
-			return `Expected \`${unionExpectedVals(expectedDeduped)}\`, received ${JSON.stringify(
+			return `Expected \`${unionExpectedVals(expectedDeduped)}\`, received \`${stringify(
 				error.received
-			)}`;
+			)}\``;
 	}
 };
 
 const prefix = (key: string, msg: string) => (key.length ? `**${key}**: ${msg}` : msg);
 
 const unionExpectedVals = (expectedVals: Set<unknown>) =>
-	[...expectedVals]
-		.map((expectedVal, idx) => {
-			if (idx === 0) return JSON.stringify(expectedVal);
-			const sep = ' | ';
-			return `${sep}${JSON.stringify(expectedVal)}`;
-		})
-		.join('');
+	[...expectedVals].map((expectedVal) => stringify(expectedVal)).join(' | ');
 
 const flattenErrorPath = (errorPath: (string | number)[]) => errorPath.join('.');
+
+/** `JSON.stringify()` a value with spaces around object/array entries. */
+const stringify = (val: unknown) =>
+	JSON.stringify(val, null, 1).split(newlinePlusWhitespace).join(' ');
+const newlinePlusWhitespace = /\n\s*/;
+const leadingPeriod = /^\./;

package/utils/plugins.ts

@@ -1,7 +1,7 @@
 import type { AstroIntegration } from 'astro';
 import { z } from 'astro/zod';
 import { StarlightConfigSchema, type StarlightUserConfig } from '../utils/user-config';
-import { errorMap, throwValidationError } from '../utils/error-map';
+import { parseWithFriendlyErrors } from '../utils/error-map';
 
 /**
  * Runs Starlight plugins in the order that they are configured after validating the user-provided
@@ -15,23 +15,19 @@ export async function runPlugins(
 ) {
 	// Validate the user-provided configuration.
 	let userConfig = starlightUserConfig;
-	let starlightConfig = StarlightConfigSchema.safeParse(userConfig, { errorMap });
 
-	if (!starlightConfig.success) {
-		throwValidationError(starlightConfig.error, 'Invalid config passed to starlight integration');
-	}
+	let starlightConfig = parseWithFriendlyErrors(
+		StarlightConfigSchema,
+		userConfig,
+		'Invalid config passed to starlight integration'
+	);
 
 	// Validate the user-provided plugins configuration.
-	const pluginsConfig = starlightPluginsConfigSchema.safeParse(pluginsUserConfig, {
-		errorMap,
-	});
-
-	if (!pluginsConfig.success) {
-		throwValidationError(
-			pluginsConfig.error,
-			'Invalid plugins config passed to starlight integration'
-		);
-	}
+	const pluginsConfig = parseWithFriendlyErrors(
+		starlightPluginsConfigSchema,
+		pluginsUserConfig,
+		'Invalid plugins config passed to starlight integration'
+	);
 
 	// A list of Astro integrations added by the various plugins.
 	const integrations: AstroIntegration[] = [];
@@ -39,7 +35,7 @@ export async function runPlugins(
 	for (const {
 		name,
 		hooks: { setup },
-	} of pluginsConfig.data) {
+	} of pluginsConfig) {
 		await setup({
 			config: pluginsUserConfig ? { ...userConfig, plugins: pluginsUserConfig } : userConfig,
 			updateConfig(newConfig) {
@@ -52,14 +48,11 @@ export async function runPlugins(
 
 				// If the plugin is updating the user config, re-validate it.
 				const mergedUserConfig = { ...userConfig, ...newConfig };
-				const mergedConfig = StarlightConfigSchema.safeParse(mergedUserConfig, { errorMap });
-
-				if (!mergedConfig.success) {
-					throwValidationError(
-						mergedConfig.error,
-						`Invalid config update provided by the '${name}' plugin`
-					);
-				}
+				const mergedConfig = parseWithFriendlyErrors(
+					StarlightConfigSchema,
+					mergedUserConfig,
+					`Invalid config update provided by the '${name}' plugin`
+				);
 
 				// If the updated config is valid, keep track of both the user config and parsed config.
 				userConfig = mergedUserConfig;
@@ -79,7 +72,7 @@ export async function runPlugins(
 		});
 	}
 
-	return { integrations, starlightConfig: starlightConfig.data };
+	return { integrations, starlightConfig };
 }
 
 // https://github.com/withastro/astro/blob/910eb00fe0b70ca80bd09520ae100e8c78b675b5/packages/astro/src/core/config/schema.ts#L113

package/utils/starlight-page.ts

@@ -1,7 +1,7 @@
 import { z } from 'astro/zod';
 import { type ContentConfig, type SchemaContext } from 'astro:content';
 import config from 'virtual:starlight/user-config';
-import { errorMap, throwValidationError } from './error-map';
+import { parseWithFriendlyErrors } from './error-map';
 import { stripLeadingAndTrailingSlashes } from './path';
 import { getToC, type PageProps, type StarlightRouteData } from './route-data';
 import type { StarlightDocsEntry } from './routing';
@@ -138,14 +138,11 @@ type StarlightPageSidebarUserConfig = z.input<typeof StarlightPageSidebarSchema>
 const normalizeSidebarProp = (
 	sidebarProp: StarlightPageSidebarUserConfig
 ): StarlightRouteData['sidebar'] => {
-	const sidebar = StarlightPageSidebarSchema.safeParse(sidebarProp, { errorMap });
-	if (!sidebar.success) {
-		throwValidationError(
-			sidebar.error,
-			'Invalid sidebar prop passed to the `<StarlightPage/>` component.'
-		);
-	}
-	return sidebar.data;
+	return parseWithFriendlyErrors(
+		StarlightPageSidebarSchema,
+		sidebarProp,
+		'Invalid sidebar prop passed to the `<StarlightPage/>` component.'
+	);
 };
 
 /**
@@ -267,16 +264,11 @@ async function getStarlightPageFrontmatter(frontmatter: StarlightPageFrontmatter
 			}),
 	});
 
-	const pageFrontmatter = schema.safeParse(frontmatter, { errorMap });
-
-	if (!pageFrontmatter.success) {
-		throwValidationError(
-			pageFrontmatter.error,
-			'Invalid frontmatter props passed to the `<StarlightPage/>` component.'
-		);
-	}
-
-	return pageFrontmatter.data;
+	return parseWithFriendlyErrors(
+		schema,
+		frontmatter,
+		'Invalid frontmatter props passed to the `<StarlightPage/>` component.'
+	);
 }
 
 /** Returns the user docs schema and falls back to the default schema if needed. */