Expose `StarlightIcon` type (#2805)

Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com>

16 files changed, 46 insertions, 26 deletions

diff --git a/.changeset/unlucky-items-notice.md b/.changeset/unlucky-items-notice.md
new file mode 100644
index 00000000..c4aeb031
--- /dev/null
+++ b/.changeset/unlucky-items-notice.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': minor
+---
+
+Exposes the [`StarlightIcon`](https://starlight.astro.build/reference/icons/#starlighticon-type) TypeScript type referencing the names of Starlight’s built-in icons.
diff --git a/docs/src/components/icons-list.astro b/docs/src/components/icons-list.astro
index 9c83c7b1..e0e37a98 100644
--- a/docs/src/components/icons-list.astro
+++ b/docs/src/components/icons-list.astro
@@ -1,6 +1,6 @@
 ---
 import { Icon } from '@astrojs/starlight/components';
-import { Icons } from '../../../packages/starlight/components/Icons';
+import { Icons, type StarlightIcon } from '../../../packages/starlight/components/Icons';
 
 interface Props {
 	labels?: {
@@ -10,7 +10,7 @@ interface Props {
 
 const { copied = 'Copied!' } = Astro.props.labels ?? {};
 
-const icons = Object.keys(Icons) as (keyof typeof Icons)[];
+const icons = Object.keys(Icons) as StarlightIcon[];
 ---
 
 <div class="icons-grid" data-label-copied={copied}>
diff --git a/docs/src/content/docs/components/icons.mdx b/docs/src/content/docs/components/icons.mdx
index 042b1527..745f4f7e 100644
--- a/docs/src/content/docs/components/icons.mdx
+++ b/docs/src/content/docs/components/icons.mdx
@@ -95,7 +95,7 @@ The `<Icon>` component accepts the following props:
 ### `name`
 
 **required**  
-**type:** `string`
+**type:** [`StarlightIcon`](/reference/icons/#starlighticon-type)
 
 The name of the icon to display set to [one of Starlight’s built-in icons](/reference/icons/#all-icons).
 
diff --git a/docs/src/content/docs/components/using-components.mdx b/docs/src/content/docs/components/using-components.mdx
index 9448e781..a497e398 100644
--- a/docs/src/content/docs/components/using-components.mdx
+++ b/docs/src/content/docs/components/using-components.mdx
@@ -81,14 +81,14 @@ If these styles conflict with your component’s appearance, set the `not-conten
 Use the [`ComponentProps`](https://docs.astro.build/en/guides/typescript/#componentprops-type) type from `astro/types` to reference the `Props` accepted by a component even if they are not exported by the component itself.
 This can be helpful when wrapping or extending an existing component.
 
-The following example uses `ComponentProps` to get the type of the props accepted by Starlight’s built-in `Icon` component:
+The following example uses `ComponentProps` to get the type of the props accepted by Starlight’s built-in `Badge` component:
 
 ```astro
 ---
 // src/components/Example.astro
 import type { ComponentProps } from 'astro/types';
-import { Icon } from '@astrojs/starlight/components';
+import { Badge } from '@astrojs/starlight/components';
 
-type IconProps = ComponentProps<typeof Icon>;
+type BadgeProps = ComponentProps<typeof Badge>;
 ---
 ```
diff --git a/docs/src/content/docs/reference/icons.mdx b/docs/src/content/docs/reference/icons.mdx
index c1feadd2..3f024642 100644
--- a/docs/src/content/docs/reference/icons.mdx
+++ b/docs/src/content/docs/reference/icons.mdx
@@ -10,6 +10,19 @@ Starlight provides a set of built-in icons that you can display in your content
 Icons can be displayed using the [`<Icon>`](/components/icons/) component.
 They are also often used in other components, such as [cards](/components/cards/) or settings like [hero actions](/reference/frontmatter/#hero).
 
+## `StarlightIcon` type
+
+Use the `StarlightIcon` TypeScript type to reference the names of [Starlight’s built-in icons](#all-icons).
+
+```ts {2} /icon: (StarlightIcon)/
+// src/icon.ts
+import type { StarlightIcon } from '@astrojs/starlight/types';
+
+function getIconLabel(icon: StarlightIcon) {
+	// …
+}
+```
+
 ## All icons
 
 A list of all available icons is shown below with their associated names. Click an icon to copy its name to your clipboard.
diff --git a/packages/starlight/__tests__/remark-rehype/rehype-file-tree.test.ts b/packages/starlight/__tests__/remark-rehype/rehype-file-tree.test.ts
index 36e8cb41..5c94c7e5 100644
--- a/packages/starlight/__tests__/remark-rehype/rehype-file-tree.test.ts
+++ b/packages/starlight/__tests__/remark-rehype/rehype-file-tree.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'vitest';
 import { processFileTree } from '../../user-components/rehype-file-tree';
-import { Icons } from '../../components/Icons';
+import { Icons, type StarlightIcon } from '../../components/Icons';
 
 describe('validation', () => {
 	test('throws an error with no content', () => {
@@ -176,6 +176,6 @@ function extractFileTree(html: string, stripIcons = true) {
 	return tree;
 }
 
-function expectHtmlToIncludeIcon(html: string, icon: (typeof Icons)[keyof typeof Icons]) {
+function expectHtmlToIncludeIcon(html: string, icon: (typeof Icons)[StarlightIcon]) {
 	return expect(extractFileTree(html, false)).toContain(icon.replace('/>', '>'));
 }
diff --git a/packages/starlight/components/ContentNotice.astro b/packages/starlight/components/ContentNotice.astro
index 9c354f93..fcf4ac3d 100644
--- a/packages/starlight/components/ContentNotice.astro
+++ b/packages/starlight/components/ContentNotice.astro
@@ -1,9 +1,9 @@
 ---
-import { Icons } from '../components/Icons';
+import type { StarlightIcon } from '../components/Icons';
 import Icon from '../user-components/Icon.astro';
 
 interface Props {
-	icon: keyof typeof Icons;
+	icon: StarlightIcon;
 	label: string;
 }
 
diff --git a/packages/starlight/components/Icons.ts b/packages/starlight/components/Icons.ts
index a6a9b742..2d4a55af 100644
--- a/packages/starlight/components/Icons.ts
+++ b/packages/starlight/components/Icons.ts
@@ -185,3 +185,5 @@ export const Icons = {
 	...BuiltInIcons,
 	...FileIcons,
 };
+
+export type StarlightIcon = keyof typeof Icons;
diff --git a/packages/starlight/schemas/hero.ts b/packages/starlight/schemas/hero.ts
index 6ecc50df..86105523 100644
--- a/packages/starlight/schemas/hero.ts
+++ b/packages/starlight/schemas/hero.ts
@@ -1,9 +1,8 @@
 import { z } from 'astro/zod';
 import type { SchemaContext } from 'astro:content';
-import { Icons } from '../components/Icons';
+import { Icons, type StarlightIcon } from '../components/Icons';
 
-type IconName = keyof typeof Icons;
-const iconNames = Object.keys(Icons) as [IconName, ...IconName[]];
+const iconNames = Object.keys(Icons) as [StarlightIcon, ...StarlightIcon[]];
 
 export const HeroSchema = ({ image }: SchemaContext) =>
 	z.object({
diff --git a/packages/starlight/types.ts b/packages/starlight/types.ts
index d5a2fcbb..5a48998b 100644
--- a/packages/starlight/types.ts
+++ b/packages/starlight/types.ts
@@ -3,3 +3,4 @@ export type {
 	StarlightPlugin,
 	StarlightUserConfigWithPlugins as StarlightUserConfig,
 } from './utils/plugins';
+export type { StarlightIcon } from './components/Icons';
diff --git a/packages/starlight/user-components/Card.astro b/packages/starlight/user-components/Card.astro
index 6b95e5bf..d7ead9c9 100644
--- a/packages/starlight/user-components/Card.astro
+++ b/packages/starlight/user-components/Card.astro
@@ -1,9 +1,9 @@
 ---
 import Icon from './Icon.astro';
-import type { Icons } from '../components/Icons';
+import type { StarlightIcon } from '../components/Icons';
 
 interface Props {
-	icon?: keyof typeof Icons;
+	icon?: StarlightIcon;
 	title: string;
 }
 
diff --git a/packages/starlight/user-components/Icon.astro b/packages/starlight/user-components/Icon.astro
index 7575cc78..ee7c443d 100644
--- a/packages/starlight/user-components/Icon.astro
+++ b/packages/starlight/user-components/Icon.astro
@@ -1,8 +1,8 @@
 ---
-import { Icons } from '../components/Icons';
+import { Icons, type StarlightIcon } from '../components/Icons';
 
 interface Props {
-	name: keyof typeof Icons;
+	name: StarlightIcon;
 	label?: string;
 	color?: string;
 	size?: string;
diff --git a/packages/starlight/user-components/LinkButton.astro b/packages/starlight/user-components/LinkButton.astro
index 3bf68f07..3afa2bb6 100644
--- a/packages/starlight/user-components/LinkButton.astro
+++ b/packages/starlight/user-components/LinkButton.astro
@@ -1,11 +1,11 @@
 ---
 import type { HTMLAttributes } from 'astro/types';
-import { Icons } from '../components/Icons';
+import type { StarlightIcon } from '../components/Icons';
 import Icon from './Icon.astro';
 
 interface Props extends Omit<HTMLAttributes<'a'>, 'href'> {
 	href: string | URL;
-	icon?: keyof typeof Icons | undefined;
+	icon?: StarlightIcon | undefined;
 	iconPlacement?: 'start' | 'end' | undefined;
 	variant?: 'primary' | 'secondary' | 'minimal';
 }
diff --git a/packages/starlight/user-components/TabItem.astro b/packages/starlight/user-components/TabItem.astro
index a7dfe634..0bd9fa6d 100644
--- a/packages/starlight/user-components/TabItem.astro
+++ b/packages/starlight/user-components/TabItem.astro
@@ -1,9 +1,9 @@
 ---
 import { TabItemTagname } from './rehype-tabs';
-import type { Icons } from '../components/Icons';
+import type { StarlightIcon } from '../components/Icons';
 
 interface Props {
-	icon?: keyof typeof Icons;
+	icon?: StarlightIcon;
 	label: string;
 }
 
diff --git a/packages/starlight/user-components/rehype-file-tree.ts b/packages/starlight/user-components/rehype-file-tree.ts
index 1bdb1907..72f658a0 100644
--- a/packages/starlight/user-components/rehype-file-tree.ts
+++ b/packages/starlight/user-components/rehype-file-tree.ts
@@ -6,7 +6,7 @@ import { fromHtml } from 'hast-util-from-html';
 import { toString } from 'hast-util-to-string';
 import { rehype } from 'rehype';
 import { CONTINUE, SKIP, visit } from 'unist-util-visit';
-import { Icons } from '../components/Icons';
+import { Icons, type StarlightIcon } from '../components/Icons';
 import { definitions } from './file-tree-icons';
 
 declare module 'vfile' {
@@ -160,7 +160,7 @@ function getFileIcon(fileName: string) {
 	const name = getFileIconName(fileName);
 	if (!name) return defaultFileIcon;
 	if (name in Icons) {
-		const path = Icons[name as keyof typeof Icons];
+		const path = Icons[name as StarlightIcon];
 		return makeSVGIcon(path);
 	}
 	return defaultFileIcon;
diff --git a/packages/starlight/user-components/rehype-tabs.ts b/packages/starlight/user-components/rehype-tabs.ts
index e7e40ebf..b989a81f 100644
--- a/packages/starlight/user-components/rehype-tabs.ts
+++ b/packages/starlight/user-components/rehype-tabs.ts
@@ -2,13 +2,13 @@ import type { Element } from 'hast';
 import { select } from 'hast-util-select';
 import { rehype } from 'rehype';
 import { CONTINUE, SKIP, visit } from 'unist-util-visit';
-import { Icons } from '../components/Icons';
+import type { StarlightIcon } from '../components/Icons';
 
 interface Panel {
 	panelId: string;
 	tabId: string;
 	label: string;
-	icon?: keyof typeof Icons;
+	icon?: StarlightIcon;
 }
 
 declare module 'vfile' {
@@ -67,7 +67,7 @@ const tabsProcessor = rehype()
 					...ids,
 					label: String(dataLabel),
 				};
-				if (dataIcon) panel.icon = String(dataIcon) as keyof typeof Icons;
+				if (dataIcon) panel.icon = String(dataIcon) as StarlightIcon;
 				file.data.panels?.push(panel);
 
 				// Remove `<TabItem>` props