From faa70de584bf596fdd7184c4a8622d67d1410ecf Mon Sep 17 00:00:00 2001
From: HiDeoo
Date: Fri, 30 Jun 2023 17:52:54 +0200
Subject: Expose `<Icon>` component (#254)

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
---
 .changeset/eight-pens-sell.md                      |  5 +++
 docs/src/components/icons-list.astro               | 40 ++++++++++++++++++++++
 docs/src/content/docs/guides/components.mdx        | 27 ++++++++++++++-
 packages/starlight/components.ts                   |  1 +
 packages/starlight/components/CallToAction.astro   |  2 +-
 packages/starlight/components/EditLink.astro       |  2 +-
 .../components/FallbackContentNotice.astro         |  2 +-
 packages/starlight/components/Icon.astro           | 35 -------------------
 .../starlight/components/MobileMenuToggle.astro    |  2 +-
 packages/starlight/components/PrevNextLinks.astro  |  2 +-
 packages/starlight/components/Search.astro         |  2 +-
 packages/starlight/components/Select.astro         |  2 +-
 packages/starlight/components/SidebarSublist.astro |  2 +-
 packages/starlight/components/SocialIcons.astro    |  2 +-
 .../TableOfContents/MobileTableOfContents.astro    |  2 +-
 packages/starlight/components/ThemeProvider.astro  |  2 +-
 packages/starlight/user-components/Card.astro      |  2 +-
 packages/starlight/user-components/Icon.astro      | 35 +++++++++++++++++++
 18 files changed, 119 insertions(+), 48 deletions(-)
 create mode 100644 .changeset/eight-pens-sell.md
 create mode 100644 docs/src/components/icons-list.astro
 delete mode 100644 packages/starlight/components/Icon.astro
 create mode 100644 packages/starlight/user-components/Icon.astro

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/Icon.astro b/packages/starlight/components/Icon.astro
deleted file mode 100644
index 6fed52e4..00000000
--- a/packages/starlight/components/Icon.astro
+++ /dev/null
@@ -1,35 +0,0 @@
----
-import { Icons } from './Icons';
-
-interface Props {
-  name: keyof typeof Icons;
-  label?: string;
-  color?: string;
-  size?: string;
-  class?: string;
-}
-
-const { name, label, size = '1em', color } = Astro.props;
-const a11yAttrs = label
-  ? ({ 'aria-label': label } as const)
-  : ({ 'aria-hidden': 'true' } as const);
----
-
-<svg
-  {...a11yAttrs}
-  class={Astro.props.class}
-  width="16"
-  height="16"
-  viewBox="0 0 24 24"
-  fill="currentColor"
-  set:html={Icons[name]}
-/>
-
-<style define:vars={{ 'sl-icon-color': color, 'sl-icon-size': size }}>
-  svg {
-    color: var(--sl-icon-color);
-    font-size: var(--sl-icon-size, 1em);
-    width: 1em;
-    height: 1em;
-  }
-</style>
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/user-components/Icon.astro b/packages/starlight/user-components/Icon.astro
new file mode 100644
index 00000000..31d3dfc9
--- /dev/null
+++ b/packages/starlight/user-components/Icon.astro
@@ -0,0 +1,35 @@
+---
+import { Icons } from '../components/Icons';
+
+interface Props {
+  name: keyof typeof Icons;
+  label?: string;
+  color?: string;
+  size?: string;
+  class?: string;
+}
+
+const { name, label, size = '1em', color } = Astro.props;
+const a11yAttrs = label
+  ? ({ 'aria-label': label } as const)
+  : ({ 'aria-hidden': 'true' } as const);
+---
+
+<svg
+  {...a11yAttrs}
+  class={Astro.props.class}
+  width="16"
+  height="16"
+  viewBox="0 0 24 24"
+  fill="currentColor"
+  set:html={Icons[name]}
+/>
+
+<style define:vars={{ 'sl-icon-color': color, 'sl-icon-size': size }}>
+  svg {
+    color: var(--sl-icon-color);
+    font-size: var(--sl-icon-size, 1em);
+    width: 1em;
+    height: 1em;
+  }
+</style>
-- 
cgit