Expose `<Icon>` component (#254)

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

17 files changed, 85 insertions, 14 deletions

diff --git a/.changeset/eight-pens-sell.md b/.changeset/eight-pens-sell.md
new file mode 100644
index 00000000..befbfeea
--- /dev/null
+++ b/.changeset/eight-pens-sell.md
@@ -0,0 +1,5 @@
+---
+"@astrojs/starlight": minor
+---
+
+Expose `<Icon>` component
diff --git a/docs/src/components/icons-list.astro b/docs/src/components/icons-list.astro
new file mode 100644
index 00000000..f3c9c106
--- /dev/null
+++ b/docs/src/components/icons-list.astro
@@ -0,0 +1,40 @@
+---
+import { Icon } from '@astrojs/starlight/components';
+import { Icons } from '../../../packages/starlight/components/Icons';
+
+const icons = Object.keys(Icons) as (keyof typeof Icons)[];
+---
+
+<div class="icons-grid">
+  {
+    icons.map((icon) => {
+      return (
+        <div class="icon-preview">
+          <Icon name={icon} size="1.5rem" />
+          <span>{icon}</span>
+        </div>
+      );
+    })
+  }
+</div>
+
+<style>
+  .icons-grid {
+    display: grid;
+    gap: 1rem;
+    grid-template-columns: repeat(auto-fit, minmax(8rem, 1fr));
+  }
+
+  .icons-grid .icon-preview {
+    align-items: center;
+    justify-content: center;
+    text-align: center;
+    border: 1px solid var(--sl-color-gray-5);
+    display: flex;
+    flex-direction: column;
+    font-size: var(--sl-text-sm);
+    gap: 0.25rem;
+    margin: 0;
+    padding: 0.75rem;
+  }
+</style>
diff --git a/docs/src/content/docs/guides/components.mdx b/docs/src/content/docs/guides/components.mdx
index 54978517..0ed73557 100644
--- a/docs/src/content/docs/guides/components.mdx
+++ b/docs/src/content/docs/guides/components.mdx
@@ -68,7 +68,7 @@ import { Card, CardGrid } from '@astrojs/starlight/components';
 You can display content in a box matching Starlight’s styles using the `<Card>` component.
 Wrap multiple cards in the `<CardGrid>` component to display cards side-by-side when there’s enough space.
 
-A `<Card>` requires a `title` and can optionally include an `icon` attribute set to the name of [one of Starlight’s built-in icons](https://github.com/withastro/starlight/blob/main/packages/starlight/components/Icons.ts).
+A `<Card>` requires a `title` and can optionally include an `icon` attribute set to the name of [one of Starlight’s built-in icons](#all-icons).
 
 ```mdx
 import { Card, CardGrid } from '@astrojs/starlight/components';
@@ -109,3 +109,28 @@ Add the `stagger` attribute to shift the second column of cards vertically and a
 ```
 
 :::
+
+### Icon
+
+import { Icon } from '@astrojs/starlight/components';
+import IconsList from '../../../components/icons-list.astro';
+
+Starlight provides a set of common icons that you can display in your content using the `<Icon>` component.
+
+Each `<Icon>` requires a [`name`](#all-icons) and can optionally include a `label`, `size`, and `color` attribute.
+
+```mdx
+import { Icon } from '@astrojs/starlight/components';
+
+<Icon name="star" color="goldenrod" size="2rem" />
+```
+
+The code above generates the following on the page:
+
+<Icon name="star" color="goldenrod" size="2rem" />
+
+#### All icons
+
+A list of all available icons is shown below with their associated names.
+
+<IconsList />
diff --git a/packages/starlight/components.ts b/packages/starlight/components.ts
index 610e5086..6fd711e8 100644
--- a/packages/starlight/components.ts
+++ b/packages/starlight/components.ts
@@ -1,4 +1,5 @@
 export { default as Card } from './user-components/Card.astro';
 export { default as CardGrid } from './user-components/CardGrid.astro';
+export { default as Icon } from './user-components/Icon.astro';
 export { default as Tabs } from './user-components/Tabs.astro';
 export { default as TabItem } from './user-components/TabItem.astro';
diff --git a/packages/starlight/components/CallToAction.astro b/packages/starlight/components/CallToAction.astro
index a297e989..68e6bb90 100644
--- a/packages/starlight/components/CallToAction.astro
+++ b/packages/starlight/components/CallToAction.astro
@@ -1,5 +1,5 @@
 ---
-import Icon from './Icon.astro';
+import Icon from '../user-components/Icon.astro';
 import type { Icons } from './Icons';
 
 interface Props {
diff --git a/packages/starlight/components/EditLink.astro b/packages/starlight/components/EditLink.astro
index f4fcbef2..459c2103 100644
--- a/packages/starlight/components/EditLink.astro
+++ b/packages/starlight/components/EditLink.astro
@@ -2,7 +2,7 @@
 import type { CollectionEntry } from 'astro:content';
 import config from 'virtual:starlight/user-config';
 import { useTranslations } from '../utils/translations';
-import Icon from './Icon.astro';
+import Icon from '../user-components/Icon.astro';
 
 interface Props {
   data: CollectionEntry<'docs'>['data'];
diff --git a/packages/starlight/components/FallbackContentNotice.astro b/packages/starlight/components/FallbackContentNotice.astro
index ba54e212..f1a604f0 100644
--- a/packages/starlight/components/FallbackContentNotice.astro
+++ b/packages/starlight/components/FallbackContentNotice.astro
@@ -1,6 +1,6 @@
 ---
 import { useTranslations } from '../utils/translations';
-import Icon from './Icon.astro';
+import Icon from '../user-components/Icon.astro';
 
 interface Props {
   locale: string | undefined;
diff --git a/packages/starlight/components/MobileMenuToggle.astro b/packages/starlight/components/MobileMenuToggle.astro
index b531d751..d199f4f6 100644
--- a/packages/starlight/components/MobileMenuToggle.astro
+++ b/packages/starlight/components/MobileMenuToggle.astro
@@ -1,5 +1,5 @@
 ---
-import Icon from './Icon.astro';
+import Icon from '../user-components/Icon.astro';
 import { useTranslations } from '../utils/translations';
 
 interface Props {
diff --git a/packages/starlight/components/PrevNextLinks.astro b/packages/starlight/components/PrevNextLinks.astro
index fe6329a3..4fd92ddd 100644
--- a/packages/starlight/components/PrevNextLinks.astro
+++ b/packages/starlight/components/PrevNextLinks.astro
@@ -1,7 +1,7 @@
 ---
 import type { Link } from '../utils/navigation';
 import { useTranslations } from '../utils/translations';
-import Icon from './Icon.astro';
+import Icon from '../user-components/Icon.astro';
 
 interface Props {
   prev: Link | undefined;
diff --git a/packages/starlight/components/Search.astro b/packages/starlight/components/Search.astro
index 93b5e72d..fbea5dd2 100644
--- a/packages/starlight/components/Search.astro
+++ b/packages/starlight/components/Search.astro
@@ -1,7 +1,7 @@
 ---
 import '@pagefind/default-ui/css/ui.css';
 import { useTranslations } from '../utils/translations';
-import Icon from './Icon.astro';
+import Icon from '../user-components/Icon.astro';
 
 interface Props {
   locale: string | undefined;
diff --git a/packages/starlight/components/Select.astro b/packages/starlight/components/Select.astro
index 86771470..d242ec67 100644
--- a/packages/starlight/components/Select.astro
+++ b/packages/starlight/components/Select.astro
@@ -1,5 +1,5 @@
 ---
-import Icon from './Icon.astro';
+import Icon from '../user-components/Icon.astro';
 
 interface Props {
   label: string;
diff --git a/packages/starlight/components/SidebarSublist.astro b/packages/starlight/components/SidebarSublist.astro
index 27a13b82..c2d6aa54 100644
--- a/packages/starlight/components/SidebarSublist.astro
+++ b/packages/starlight/components/SidebarSublist.astro
@@ -1,6 +1,6 @@
 ---
 import type { SidebarEntry } from '../utils/navigation';
-import Icon from './Icon.astro';
+import Icon from '../user-components/Icon.astro';
 
 interface Props {
   sublist: SidebarEntry[];
diff --git a/packages/starlight/components/SocialIcons.astro b/packages/starlight/components/SocialIcons.astro
index 906232d0..fae3ba0e 100644
--- a/packages/starlight/components/SocialIcons.astro
+++ b/packages/starlight/components/SocialIcons.astro
@@ -1,6 +1,6 @@
 ---
 import config from 'virtual:starlight/user-config';
-import Icon from './Icon.astro';
+import Icon from '../user-components/Icon.astro';
 
 type Platform = keyof NonNullable<typeof config.social>;
 
diff --git a/packages/starlight/components/TableOfContents/MobileTableOfContents.astro b/packages/starlight/components/TableOfContents/MobileTableOfContents.astro
index a638658e..142f15c7 100644
--- a/packages/starlight/components/TableOfContents/MobileTableOfContents.astro
+++ b/packages/starlight/components/TableOfContents/MobileTableOfContents.astro
@@ -1,6 +1,6 @@
 ---
 import { useTranslations } from '../../utils/translations';
-import Icon from '../Icon.astro';
+import Icon from '../../user-components/Icon.astro';
 import TableOfContentsList from './TableOfContentsList.astro';
 import type { TocItem } from './generateToC';
 
diff --git a/packages/starlight/components/ThemeProvider.astro b/packages/starlight/components/ThemeProvider.astro
index 64ac10e1..cd6aeade 100644
--- a/packages/starlight/components/ThemeProvider.astro
+++ b/packages/starlight/components/ThemeProvider.astro
@@ -1,5 +1,5 @@
 ---
-import Icon from './Icon.astro';
+import Icon from '../user-components/Icon.astro';
 ---
 
 {/* This is intentionally inlined to avoid FOUC. */}
diff --git a/packages/starlight/user-components/Card.astro b/packages/starlight/user-components/Card.astro
index 98f611c2..1bbe44d3 100644
--- a/packages/starlight/user-components/Card.astro
+++ b/packages/starlight/user-components/Card.astro
@@ -1,5 +1,5 @@
 ---
-import Icon from '../components/Icon.astro';
+import Icon from './Icon.astro';
 import type { Icons } from '../components/Icons';
 
 interface Props {
diff --git a/packages/starlight/components/Icon.astro b/packages/starlight/user-components/Icon.astro
index 6fed52e4..31d3dfc9 100644
--- a/packages/starlight/components/Icon.astro
+++ b/packages/starlight/user-components/Icon.astro
@@ -1,5 +1,5 @@
 ---
-import { Icons } from './Icons';
+import { Icons } from '../components/Icons';
 
 interface Props {
   name: keyof typeof Icons;