@astrojs/starlight 0.41.3 → 0.41.5

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @astrojs/starlight
 
+## 0.41.5
+
+### Patch Changes
+
+- [#4095](https://github.com/withastro/starlight/pull/4095) [`bb06434`](https://github.com/withastro/starlight/commit/bb06434a1bc199b59f9d7953d0e41c6c287b1aa2) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Fixes a regression when using a union to [extend](https://starlight.astro.build/reference/frontmatter/#extend) Starlight’s `docsSchema()`.
+
+## 0.41.4
+
+### Patch Changes
+
+- [#3936](https://github.com/withastro/starlight/pull/3936) [`712eedd`](https://github.com/withastro/starlight/commit/712eedd8e0d28329feb361edc392438f37ba2095) Thanks [@miichom](https://github.com/miichom)! - Fixes support for modifying Zod enums when passing an [`extend` option](https://starlight.astro.build/reference/frontmatter/#extend) to Starlight’s `docsSchema()`
+
+- [#4092](https://github.com/withastro/starlight/pull/4092) [`0896b91`](https://github.com/withastro/starlight/commit/0896b91607325b9d8494eb665cd1716a40025a5a) Thanks [@delucis](https://github.com/delucis)! - Fixes support for links containing a protocol like `mailto:` in the sidebar
+
+- [#4088](https://github.com/withastro/starlight/pull/4088) [`4486ba4`](https://github.com/withastro/starlight/commit/4486ba432afe9e206f0b05651de24a9c25bdf6dd) Thanks [@delucis](https://github.com/delucis)! - Simplifies Starlight’s client-side sidebar state persistence script slightly
+
 ## 0.41.3
 
 ### Patch Changes

package/components-internals/SidebarPersistState.ts

@@ -69,4 +69,3 @@ target?.addEventListener('click', (event) => {
 addEventListener('visibilitychange', () => {
 	if (document.visibilityState === 'hidden') updateState();
 });
-addEventListener('pageHide', updateState);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.41.3",
+  "version": "0.41.5",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",

package/schema.ts

@@ -6,6 +6,7 @@ import { FrontmatterTableOfContentsSchema } from './schemas/tableOfContents';
 import { BadgeConfigSchema } from './schemas/badge';
 import { HeroSchema } from './schemas/hero';
 import { SidebarLinkItemHTMLAttributesSchema } from './schemas/sidebar';
+import { deepMergeSchemas, type DeepMergedSchema } from './utils/zodDeepMerge';
 export { i18nSchema } from './schemas/i18n';
 
 /** Default content collection schema for Starlight’s `docs` collection. */
@@ -114,14 +115,13 @@ const StarlightFrontmatterSchema = (context: SchemaContext) =>
 type DefaultSchema = ReturnType<typeof StarlightFrontmatterSchema>;
 
 /** Base subset of Zod types that we support passing to the `extend` option. */
-type BaseSchema = z.core.$ZodType;
+type BaseObjectSchema = z.ZodObject<z.ZodRawShape, z.core.$ZodObjectConfig>;
+type BaseSchema = BaseObjectSchema | z.ZodUnion<readonly BaseObjectSchema[]>;
 
 /** Type that extends Starlight’s default schema with an optional, user-defined schema. */
 type ExtendedSchema<T extends BaseSchema = never> = [T] extends [never]
 	? DefaultSchema
-	: T extends BaseSchema
-		? z.ZodIntersection<DefaultSchema, T>
-		: DefaultSchema;
+	: DeepMergedSchema<DefaultSchema, T>;
 
 interface DocsSchemaOpts<T extends BaseSchema> {
 	/**
@@ -160,7 +160,7 @@ export function docsSchema<T extends BaseSchema = never>(
 
 		return (
 			UserSchema
-				? StarlightFrontmatterSchema(context).and(UserSchema)
+				? deepMergeSchemas(StarlightFrontmatterSchema(context), UserSchema)
 				: StarlightFrontmatterSchema(context)
 		) as ExtendedSchema<T>;
 	};

package/utils/navigation.ts

@@ -33,7 +33,7 @@ import type {
 	SidebarAutogenerateRouteData,
 } from './routing/types';
 import { localeToLang, localizedFilePath, slugToPathname } from './slugs';
-import { isAbsoluteUrl } from './url';
+import { hasProtocol } from './url';
 import type { StarlightConfig } from './user-config';
 
 const DirKey = Symbol('DirKey');
@@ -120,7 +120,7 @@ function entriesFromAutogenerateConfig(
 /** Create a link entry from a manual link item in user config. */
 function linkFromSidebarLinkItem(item: SidebarLinkItem, locale: string | undefined) {
 	let href = item.link;
-	if (!isAbsoluteUrl(href)) {
+	if (!hasProtocol(href)) {
 		href = ensureLeadingSlash(href);
 		// Inject current locale into link.
 		if (locale) href = '/' + locale + href;
@@ -188,7 +188,7 @@ function makeSidebarLink(
 	opts: MakeLinkOptions & { autogenerate: SidebarAutogenerateRouteData }
 ): SidebarAutoLink;
 function makeSidebarLink({ attrs, badge, href, label, autogenerate }: MakeLinkOptions) {
-	if (!isAbsoluteUrl(href)) {
+	if (!hasProtocol(href)) {
 		href = formatPath(href);
 	}
 	return makeLink({ label, href, badge, attrs, autogenerate });

package/utils/url.ts

@@ -1,4 +1,8 @@
 const HTTPProtocolRegEx = /^https?:\/\//;
+const ProtocolRegEx = /^[a-z][a-z\d+.-]*:/i;
 
 /** Check if a string starts with one of `http://` or `https://`. */
 export const isAbsoluteUrl = (link: string) => HTTPProtocolRegEx.test(link);
+
+/** Check if a string contains a protocol (e.g., `http:`, `https:`, `mailto:`). */
+export const hasProtocol = (link: string) => ProtocolRegEx.test(link);

package/utils/zodDeepMerge.ts

@@ -0,0 +1,144 @@
+import type { z } from 'astro/zod';
+
+/** Type-level equivalent of {@link mergeWithDefaultSchema}. */
+export type DeepMergedSchema<Default extends z.core.$ZodType, User extends z.core.$ZodType> =
+	User extends z.ZodOptional<infer WrappedSchema extends z.core.$ZodType>
+		? z.ZodOptional<DeepMergedSchema<UnwrappedSchema<Default>, WrappedSchema>>
+		: User extends z.ZodNullable<infer WrappedSchema extends z.core.$ZodType>
+			? z.ZodNullable<DeepMergedSchema<UnwrappedSchema<Default>, WrappedSchema>>
+			: User extends z.ZodDefault<infer WrappedSchema extends z.core.$ZodType>
+				? z.ZodDefault<DeepMergedSchema<UnwrappedSchema<Default>, WrappedSchema>>
+				: User extends z.ZodPrefault<infer WrappedSchema extends z.core.$ZodType>
+					? z.ZodPrefault<DeepMergedSchema<UnwrappedSchema<Default>, WrappedSchema>>
+					: User extends z.ZodUnion<infer Users extends readonly z.core.$ZodType[]>
+						? z.ZodUnion<DeepMergedUnionMembers<UnwrappedSchema<Default>, Users>>
+						: UnwrappedSchema<Default> extends z.ZodObject<infer DefaultShape>
+							? User extends z.ZodObject<infer UserShape, infer UserConfig>
+								? z.ZodObject<DeepMergedShape<DefaultShape, UserShape>, UserConfig>
+								: User
+							: UnwrappedSchema<Default> extends z.ZodArray<
+										infer DefaultItemSchema extends z.core.$ZodType
+								  >
+								? User extends z.ZodArray<infer UserItemSchema extends z.core.$ZodType>
+									? z.ZodArray<DeepMergedSchema<DefaultItemSchema, UserItemSchema>>
+									: User
+								: User;
+
+/** Type-level equivalent of {@link unwrapSchema}. */
+type UnwrappedSchema<T extends z.core.$ZodType> =
+	T extends z.ZodOptional<infer Wrapped extends z.core.$ZodType>
+		? UnwrappedSchema<Wrapped>
+		: T extends z.ZodNullable<infer Wrapped extends z.core.$ZodType>
+			? UnwrappedSchema<Wrapped>
+			: T extends z.ZodDefault<infer Wrapped extends z.core.$ZodType>
+				? UnwrappedSchema<Wrapped>
+				: T extends z.ZodPrefault<infer Wrapped extends z.core.$ZodType>
+					? UnwrappedSchema<Wrapped>
+					: T;
+
+/**
+ * Merged Zod object shapes, preserving default properties, adding user-only properties, and
+ * recursively merging shared properties.
+ */
+type DeepMergedShape<Default extends z.ZodRawShape, User extends z.ZodRawShape> = {
+	[Key in keyof Default | keyof User]: Key extends keyof User
+		? Key extends keyof Default
+			? DeepMergedSchema<Default[Key], User[Key]>
+			: User[Key]
+		: Key extends keyof Default
+			? Default[Key]
+			: never;
+};
+
+/** Merged union schemas where each union member is deep-merged with the default schema. */
+type DeepMergedUnionMembers<
+	Default extends z.core.$ZodType,
+	Users extends readonly z.core.$ZodType[],
+> = {
+	[Key in keyof Users]: Users[Key] extends z.core.$ZodType
+		? DeepMergedSchema<Default, Users[Key]>
+		: Users[Key];
+};
+
+export function deepMergeSchemas(defaultSchema: z.ZodType, userSchema: z.ZodType): z.ZodType {
+	const unwrappedDefaultSchema = unwrapSchema(defaultSchema);
+
+	if (isWrappedSchema(userSchema)) {
+		return userSchema.clone({
+			...userSchema._zod.def,
+			innerType: deepMergeSchemas(unwrappedDefaultSchema, userSchema._zod.def.innerType),
+		} as Parameters<typeof userSchema.clone>[0]);
+	}
+
+	if (isZodUnion(userSchema)) {
+		return userSchema.clone({
+			...userSchema._zod.def,
+			options: userSchema.options.map((schema) => deepMergeSchemas(unwrappedDefaultSchema, schema)),
+		});
+	}
+
+	if (isZodObject(unwrappedDefaultSchema) && isZodObject(userSchema)) {
+		const shape: z.core.$ZodLooseShape = { ...unwrappedDefaultSchema.shape };
+
+		for (const key of Object.keys(userSchema.shape)) {
+			const userFieldSchema = userSchema.shape[key] as z.ZodType;
+			const defaultFieldSchema = shape[key] as z.ZodType | undefined;
+
+			shape[key] = defaultFieldSchema
+				? deepMergeSchemas(defaultFieldSchema, userFieldSchema)
+				: userFieldSchema;
+		}
+
+		return userSchema.safeExtend(shape);
+	}
+
+	if (isZodArray(unwrappedDefaultSchema) && isZodArray(userSchema)) {
+		return userSchema.clone({
+			...userSchema._zod.def,
+			element: deepMergeSchemas(unwrappedDefaultSchema.element, userSchema.element),
+		});
+	}
+
+	return userSchema;
+}
+
+/**
+ * Unwrap any Zod schema that wraps other schemas, such as `z.optional()`, `z.nullable()`,
+ * `z.default()`, etc. until we reach the innermost schema.
+ */
+function unwrapSchema(schema: z.ZodType): z.ZodType {
+	let current = schema;
+
+	while (isWrappedSchema(current)) {
+		current = current._zod.def.innerType;
+	}
+
+	return current;
+}
+
+/**
+ * Check if a schema wraps another schema which can happen when using modifiers like
+ * `z.optional()`, `z.nullable()`, `z.default()`, etc.
+ */
+function isWrappedSchema(schema: z.ZodType): schema is z.ZodType & {
+	_zod: { def: z.ZodType['_zod']['def'] & { innerType: z.ZodType } };
+} {
+	return (
+		schema._zod.def.type === 'optional' ||
+		schema._zod.def.type === 'nullable' ||
+		schema._zod.def.type === 'default' ||
+		schema._zod.def.type === 'prefault'
+	);
+}
+
+function isZodObject(schema: z.ZodType): schema is z.ZodObject<z.ZodRawShape> {
+	return schema._zod.def.type === 'object';
+}
+
+function isZodArray(schema: z.ZodType): schema is z.ZodArray<z.ZodType> {
+	return schema._zod.def.type === 'array';
+}
+
+function isZodUnion(schema: z.ZodType): schema is z.ZodUnion<readonly z.ZodType[]> {
+	return schema._zod.def.type === 'union';
+}