@astrojs/starlight 0.19.0 → 0.19.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @astrojs/starlight
 
+## 0.19.1
+
+### Patch Changes
+
+- [#1527](https://github.com/withastro/starlight/pull/1527) [`163bc84`](https://github.com/withastro/starlight/commit/163bc848e173eecca92d1cb034045fdb42aa4ff1) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Exports the `StarlightPageProps` TypeScript type representing the props expected by the `<StarlightPage />` component.
+
+- [#1504](https://github.com/withastro/starlight/pull/1504) [`fc83a05`](https://github.com/withastro/starlight/commit/fc83a05235b74be2bfe6ba8e7f95a8a5a618ead3) Thanks [@mingjunlu](https://github.com/mingjunlu)! - Adds Traditional Chinese UI translations
+
+- [#1534](https://github.com/withastro/starlight/pull/1534) [`aada680`](https://github.com/withastro/starlight/commit/aada6805abc0068f07393585b86978ef5200439c) Thanks [@delucis](https://github.com/delucis)! - Improves DX of the `sidebar` prop used by the new `<StarlightPage>` component.
+
 ## 0.19.0
 
 ### Minor Changes

package/package.json

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

package/props.ts

@@ -1 +1,2 @@
 export type { StarlightRouteData as Props } from './utils/route-data';
+export type { StarlightPageProps } from './utils/starlight-page';

package/translations/index.ts

@@ -24,6 +24,7 @@ import ru from './ru.json';
 import vi from './vi.json';
 import uk from './uk.json';
 import hi from './hi.json';
+import zhTW from './zh-TW.json';
 
 const { parse } = builtinI18nSchema();
 
@@ -54,5 +55,6 @@ export default Object.fromEntries(
 		vi,
 		uk,
 		hi,
+		'zh-TW': zhTW,
 	}).map(([key, dict]) => [key, parse(dict)])
 );

package/translations/zh-TW.json

@@ -0,0 +1,26 @@
+{
+  "skipLink.label": "跳到內容",
+  "search.label": "搜尋",
+  "search.shortcutLabel": "（按 / 鍵開始搜尋）",
+  "search.cancelLabel": "取消",
+  "search.devWarning": "正式版本才能使用搜尋功能。\n如要在本地測試，請先建置並預覽網站。",
+  "themeSelect.accessibleLabel": "選擇佈景主題",
+  "themeSelect.dark": "深色",
+  "themeSelect.light": "淺色",
+  "themeSelect.auto": "自動",
+  "languageSelect.accessibleLabel": "選擇語言",
+  "menuButton.accessibleLabel": "選單",
+  "sidebarNav.accessibleLabel": "主要",
+  "tableOfContents.onThisPage": "本頁內容",
+  "tableOfContents.overview": "概述",
+  "i18n.untranslatedContent": "本頁內容尚未翻譯。",
+  "page.editLink": "編輯頁面",
+  "page.lastUpdated": "最後更新於：",
+  "page.previousLink": "前一則",
+  "page.nextLink": "下一則",
+  "404.text": "找不到頁面。請檢查網址或改用搜尋功能。",
+  "aside.note": "注意",
+  "aside.tip": "提示",
+  "aside.caution": "警告",
+  "aside.danger": "危險"
+}

package/utils/starlight-page.ts

@@ -9,6 +9,8 @@ import { slugToLocaleData, urlToSlug } from './slugs';
 import { getPrevNextLinks, getSidebar } from './navigation';
 import { useTranslations } from './translations';
 import { docsSchema } from '../schema';
+import { BadgeConfigSchema } from '../schemas/badge';
+import { SidebarLinkItemHTMLAttributesSchema } from '../schemas/sidebar';
 
 /**
  * The frontmatter schema for Starlight pages derived from the default schema for Starlight’s
@@ -56,6 +58,96 @@ type StarlightPageFrontmatter = Omit<
 	'editUrl' | 'sidebar'
 > & { editUrl?: string | false };
 
+/**
+ * Link configuration schema for `<StarlightPage>`.
+ * Sets default values where possible to be more user friendly than raw `SidebarEntry` type.
+ */
+const LinkSchema = z
+	.object({
+		/** @deprecated Specifying `type` is no longer required. */
+		type: z.literal('link').default('link'),
+		label: z.string(),
+		href: z.string(),
+		isCurrent: z.boolean().default(false),
+		badge: BadgeConfigSchema(),
+		attrs: SidebarLinkItemHTMLAttributesSchema(),
+	})
+	// Make sure badge is in the object even if undefined — Zod doesn’t seem to have a way to set `undefined` as a default.
+	.transform((item) => ({ badge: undefined, ...item }));
+
+/** Base schema for link groups without the recursive `items` array. */
+const LinkGroupBase = z.object({
+	/** @deprecated Specifying `type` is no longer required. */
+	type: z.literal('group').default('group'),
+	label: z.string(),
+	collapsed: z.boolean().default(false),
+	badge: BadgeConfigSchema(),
+});
+
+//  These manual types are needed to correctly type the recursive link group type.
+type ManualLinkGroupInput = Prettify<
+	z.input<typeof LinkGroupBase> &
+		// The original implementation of `<StarlightPage>` in v0.19.0 used `entries`.
+		// We want to use `items` so it matches the sidebar config in `astro.config.mjs`.
+		// Keeping `entries` support for now to not break anyone.
+		// TODO: warn about `entries` usage in a future version
+		// TODO: remove support for `entries` in a future version
+		(| {
+					/** Array of links and subcategories to display in this category. */
+					items: Array<z.input<typeof LinkSchema> | ManualLinkGroupInput>;
+			  }
+			| {
+					/**
+					 * @deprecated Use `items` instead of `entries`.
+					 * Support for `entries` will be removed in a future version of Starlight.
+					 */
+					entries: Array<z.input<typeof LinkSchema> | ManualLinkGroupInput>;
+			  }
+		)
+>;
+type ManualLinkGroupOutput = z.output<typeof LinkGroupBase> & {
+	entries: Array<z.output<typeof LinkSchema> | ManualLinkGroupOutput>;
+	badge: z.output<typeof LinkGroupBase>['badge'];
+};
+type LinkGroupSchemaType = z.ZodType<ManualLinkGroupOutput, z.ZodTypeDef, ManualLinkGroupInput>;
+/**
+ * Link group configuration schema for `<StarlightPage>`.
+ * Sets default values where possible to be more user friendly than raw `SidebarEntry` type.
+ */
+const LinkGroupSchema: LinkGroupSchemaType = z.preprocess(
+	// Map `items` to `entries` as expected by the `SidebarEntry` type.
+	(arg) => {
+		if (arg && typeof arg === 'object' && 'items' in arg) {
+			const { items, ...rest } = arg;
+			return { ...rest, entries: items };
+		}
+		return arg;
+	},
+	LinkGroupBase.extend({
+		entries: z.lazy(() => z.union([LinkSchema, LinkGroupSchema]).array()),
+	})
+		// Make sure badge is in the object even if undefined.
+		.transform((item) => ({ badge: undefined, ...item }))
+) as LinkGroupSchemaType;
+
+/** Sidebar configuration schema for `<StarlightPage>` */
+const StarlightPageSidebarSchema = z.union([LinkSchema, LinkGroupSchema]).array();
+type StarlightPageSidebarUserConfig = z.input<typeof StarlightPageSidebarSchema>;
+
+/** Parse sidebar prop to ensure all required defaults are in place. */
+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;
+};
+
 /**
  * The props accepted by the `<StarlightPage/>` component.
  */
@@ -63,7 +155,8 @@ export type StarlightPageProps = Prettify<
 	// Remove the index signature from `Route`, omit undesired properties and make the rest optional.
 	Partial<Omit<RemoveIndexSignature<PageProps>, 'entry' | 'entryMeta' | 'id' | 'locale' | 'slug'>> &
 		// Add the sidebar definitions for a Starlight page.
-		Partial<Pick<StarlightRouteData, 'hasSidebar' | 'sidebar'>> & {
+		Partial<Pick<StarlightRouteData, 'hasSidebar'>> & {
+			sidebar?: StarlightPageSidebarUserConfig;
 			// And finally add the Starlight page frontmatter properties in a `frontmatter` property.
 			frontmatter: StarlightPageFrontmatter;
 		}
@@ -94,7 +187,9 @@ export async function generateStarlightPageRouteData({
 	const pageFrontmatter = await getStarlightPageFrontmatter(frontmatter);
 	const id = `${stripLeadingAndTrailingSlashes(slug)}.md`;
 	const localeData = slugToLocaleData(slug);
-	const sidebar = props.sidebar ?? getSidebar(url.pathname, localeData.locale);
+	const sidebar = props.sidebar
+		? normalizeSidebarProp(props.sidebar)
+		: getSidebar(url.pathname, localeData.locale);
 	const headings = props.headings ?? [];
 	const pageDocsEntry: StarlightPageDocsEntry = {
 		id,