Aside: Support custom icons (withastro#2261)

Co-authored-by: HiDeoo <[email protected]>
Co-authored-by: Chris Swithinbank <[email protected]>

Author: 3 people

__tests__/remark-rehype/asides.test.ts

@@ -1,7 +1,7 @@
 import { createMarkdownProcessor, type MarkdownProcessor } from '@astrojs/markdown-remark';
 import type { Root } from 'mdast';
 import { visit } from 'unist-util-visit';
-import { describe, expect, test } from 'vitest';
+import { describe, expect, test, vi } from 'vitest';
 import { starlightAsides, remarkDirectivesRestoration } from '../../integrations/asides';
 import { createTranslationSystemFromFs } from '../../utils/translations-fs';
 import { StarlightConfigSchema, type StarlightUserConfig } from '../../utils/user-config';
@@ -126,6 +126,80 @@ Some text
 	);
 });
 
+describe('custom icons', () => {
+	test.each(['note', 'tip', 'caution', 'danger'])('%s with custom icon', async (type) => {
+		const res = await renderMarkdown(`
+:::${type}{icon="heart"}
+Some text
+:::
+  `);
+		await expect(res.code).toMatchFileSnapshot(
+			`./snapshots/generates-aside-${type}-custom-icon.html`
+		);
+	});
+
+	test.each(['note', 'tip', 'caution', 'danger'])('%s with invalid custom icon', async (type) => {
+		// Temporarily mock console.error to avoid cluttering test output when the Astro Markdown
+		// processor logs an error before rethrowing it.
+		// https://github.com/withastro/astro/blob/98853ce7e31a8002fd7be83d7932a53cfec84d27/packages/markdown/remark/src/index.ts#L161
+		const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+		await expect(async () =>
+			renderMarkdown(
+				`
+:::${type}{icon="invalid-icon-name"}
+Some text
+:::
+		`
+			)
+		).rejects.toThrowError(
+			// We are not relying on `toThrowErrorMatchingInlineSnapshot()` and our custom snapshot
+			// serializer in this specific test as error thrown in a remark plugin includes a dynamic file
+			// path.
+			expect.objectContaining({
+				type: 'AstroUserError',
+				hint: expect.stringMatching(
+					/An aside custom icon must be set to the name of one of Starlight’s built-in icons, but received `invalid-icon-name`/
+				),
+			})
+		);
+
+		// Restore the original console.error implementation.
+		consoleError.mockRestore();
+	});
+
+	test('test custom icon with multiple paths inside the svg', async () => {
+		const res = await renderMarkdown(`
+:::note{icon="external"}
+Some text
+:::
+  `);
+		await expect(res.code).toMatchFileSnapshot(
+			`./snapshots/generates-aside-note-multiple-path-custom-icon.html`
+		);
+		const pathCount = (res.code.match(/path/g) || []).length;
+		// If we have two pairs of opening and closing tags of path,
+		// we will have 4 occurences of that word.
+		expect(pathCount).eq(4);
+	});
+});
+
+describe('custom labels with custom icons', () => {
+	test.each(['note', 'tip', 'caution', 'danger'])('%s with custom label', async (type) => {
+		const label = 'Custom Label';
+		const res = await renderMarkdown(`
+:::${type}[${label}]{icon="heart"}
+Some text
+:::
+  `);
+		expect(res.code).includes(`aria-label="${label}"`);
+		expect(res.code).includes(`</svg>${label}</p>`);
+		await expect(res.code).toMatchFileSnapshot(
+			`./snapshots/generates-aside-${type}-custom-label-and-icon.html`
+		);
+	});
+});
+
 test('ignores unknown directive variants', async () => {
 	const res = await renderMarkdown(`
 :::unknown

__tests__/remark-rehype/snapshots/generates-aside-caution-custom-icon.html

@@ -0,0 +1 @@
+<aside aria-label="Caution" class="starlight-aside starlight-aside--caution"><p class="starlight-aside__title" aria-hidden="true"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor" class="starlight-aside__icon"><path d="M20.16 5A6.29 6.29 0 0 0 12 4.36a6.27 6.27 0 0 0-8.16 9.48l6.21 6.22a2.78 2.78 0 0 0 3.9 0l6.21-6.22a6.27 6.27 0 0 0 0-8.84m-1.41 7.46-6.21 6.21a.76.76 0 0 1-1.08 0l-6.21-6.24a4.29 4.29 0 0 1 0-6 4.27 4.27 0 0 1 6 0 1 1 0 0 0 1.42 0 4.27 4.27 0 0 1 6 0 4.29 4.29 0 0 1 .08 6Z"></path></svg>Caution</p><div class="starlight-aside__content"><p>Some text</p></div></aside>

__tests__/remark-rehype/snapshots/generates-aside-caution-custom-label-and-icon.html

@@ -0,0 +1 @@
+<aside aria-label="Custom Label" class="starlight-aside starlight-aside--caution"><p class="starlight-aside__title" aria-hidden="true"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor" class="starlight-aside__icon"><path d="M20.16 5A6.29 6.29 0 0 0 12 4.36a6.27 6.27 0 0 0-8.16 9.48l6.21 6.22a2.78 2.78 0 0 0 3.9 0l6.21-6.22a6.27 6.27 0 0 0 0-8.84m-1.41 7.46-6.21 6.21a.76.76 0 0 1-1.08 0l-6.21-6.24a4.29 4.29 0 0 1 0-6 4.27 4.27 0 0 1 6 0 1 1 0 0 0 1.42 0 4.27 4.27 0 0 1 6 0 4.29 4.29 0 0 1 .08 6Z"></path></svg>Custom Label</p><div class="starlight-aside__content"><p>Some text</p></div></aside>

__tests__/remark-rehype/snapshots/generates-aside-danger-custom-icon.html

@@ -0,0 +1 @@
+<aside aria-label="Danger" class="starlight-aside starlight-aside--danger"><p class="starlight-aside__title" aria-hidden="true"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor" class="starlight-aside__icon"><path d="M20.16 5A6.29 6.29 0 0 0 12 4.36a6.27 6.27 0 0 0-8.16 9.48l6.21 6.22a2.78 2.78 0 0 0 3.9 0l6.21-6.22a6.27 6.27 0 0 0 0-8.84m-1.41 7.46-6.21 6.21a.76.76 0 0 1-1.08 0l-6.21-6.24a4.29 4.29 0 0 1 0-6 4.27 4.27 0 0 1 6 0 1 1 0 0 0 1.42 0 4.27 4.27 0 0 1 6 0 4.29 4.29 0 0 1 .08 6Z"></path></svg>Danger</p><div class="starlight-aside__content"><p>Some text</p></div></aside>

__tests__/remark-rehype/snapshots/generates-aside-danger-custom-label-and-icon.html

@@ -0,0 +1 @@
+<aside aria-label="Custom Label" class="starlight-aside starlight-aside--danger"><p class="starlight-aside__title" aria-hidden="true"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor" class="starlight-aside__icon"><path d="M20.16 5A6.29 6.29 0 0 0 12 4.36a6.27 6.27 0 0 0-8.16 9.48l6.21 6.22a2.78 2.78 0 0 0 3.9 0l6.21-6.22a6.27 6.27 0 0 0 0-8.84m-1.41 7.46-6.21 6.21a.76.76 0 0 1-1.08 0l-6.21-6.24a4.29 4.29 0 0 1 0-6 4.27 4.27 0 0 1 6 0 1 1 0 0 0 1.42 0 4.27 4.27 0 0 1 6 0 4.29 4.29 0 0 1 .08 6Z"></path></svg>Custom Label</p><div class="starlight-aside__content"><p>Some text</p></div></aside>

__tests__/remark-rehype/snapshots/generates-aside-note-custom-icon.html

@@ -0,0 +1 @@
+<aside aria-label="Note" class="starlight-aside starlight-aside--note"><p class="starlight-aside__title" aria-hidden="true"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor" class="starlight-aside__icon"><path d="M20.16 5A6.29 6.29 0 0 0 12 4.36a6.27 6.27 0 0 0-8.16 9.48l6.21 6.22a2.78 2.78 0 0 0 3.9 0l6.21-6.22a6.27 6.27 0 0 0 0-8.84m-1.41 7.46-6.21 6.21a.76.76 0 0 1-1.08 0l-6.21-6.24a4.29 4.29 0 0 1 0-6 4.27 4.27 0 0 1 6 0 1 1 0 0 0 1.42 0 4.27 4.27 0 0 1 6 0 4.29 4.29 0 0 1 .08 6Z"></path></svg>Note</p><div class="starlight-aside__content"><p>Some text</p></div></aside>

__tests__/remark-rehype/snapshots/generates-aside-note-custom-label-and-icon.html

@@ -0,0 +1 @@
+<aside aria-label="Custom Label" class="starlight-aside starlight-aside--note"><p class="starlight-aside__title" aria-hidden="true"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor" class="starlight-aside__icon"><path d="M20.16 5A6.29 6.29 0 0 0 12 4.36a6.27 6.27 0 0 0-8.16 9.48l6.21 6.22a2.78 2.78 0 0 0 3.9 0l6.21-6.22a6.27 6.27 0 0 0 0-8.84m-1.41 7.46-6.21 6.21a.76.76 0 0 1-1.08 0l-6.21-6.24a4.29 4.29 0 0 1 0-6 4.27 4.27 0 0 1 6 0 1 1 0 0 0 1.42 0 4.27 4.27 0 0 1 6 0 4.29 4.29 0 0 1 .08 6Z"></path></svg>Custom Label</p><div class="starlight-aside__content"><p>Some text</p></div></aside>

__tests__/remark-rehype/snapshots/generates-aside-note-multiple-path-custom-icon.html

@@ -0,0 +1 @@
+<aside aria-label="Note" class="starlight-aside starlight-aside--note"><p class="starlight-aside__title" aria-hidden="true"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor" class="starlight-aside__icon"><path d="M19.33 10.18a1 1 0 0 1-.77 0 1 1 0 0 1-.62-.93l.01-1.83-8.2 8.2a1 1 0 0 1-1.41-1.42l8.2-8.2H14.7a1 1 0 0 1 0-2h4.25a1 1 0 0 1 1 1v4.25a1 1 0 0 1-.62.93Z"></path><path d="M11 4a1 1 0 1 1 0 2H7a1 1 0 0 0-1 1v10a1 1 0 0 0 1 1h10a1 1 0 0 0 1-1v-4a1 1 0 1 1 2 0v4a3 3 0 0 1-3 3H7a3 3 0 0 1-3-3V7a3 3 0 0 1 3-3h4Z"></path></svg>Note</p><div class="starlight-aside__content"><p>Some text</p></div></aside>

__tests__/remark-rehype/snapshots/generates-aside-tip-custom-icon.html

@@ -0,0 +1 @@
+<aside aria-label="Tip" class="starlight-aside starlight-aside--tip"><p class="starlight-aside__title" aria-hidden="true"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor" class="starlight-aside__icon"><path d="M20.16 5A6.29 6.29 0 0 0 12 4.36a6.27 6.27 0 0 0-8.16 9.48l6.21 6.22a2.78 2.78 0 0 0 3.9 0l6.21-6.22a6.27 6.27 0 0 0 0-8.84m-1.41 7.46-6.21 6.21a.76.76 0 0 1-1.08 0l-6.21-6.24a4.29 4.29 0 0 1 0-6 4.27 4.27 0 0 1 6 0 1 1 0 0 0 1.42 0 4.27 4.27 0 0 1 6 0 4.29 4.29 0 0 1 .08 6Z"></path></svg>Tip</p><div class="starlight-aside__content"><p>Some text</p></div></aside>

__tests__/remark-rehype/snapshots/generates-aside-tip-custom-label-and-icon.html

@@ -0,0 +1 @@
+<aside aria-label="Custom Label" class="starlight-aside starlight-aside--tip"><p class="starlight-aside__title" aria-hidden="true"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor" class="starlight-aside__icon"><path d="M20.16 5A6.29 6.29 0 0 0 12 4.36a6.27 6.27 0 0 0-8.16 9.48l6.21 6.22a2.78 2.78 0 0 0 3.9 0l6.21-6.22a6.27 6.27 0 0 0 0-8.84m-1.41 7.46-6.21 6.21a.76.76 0 0 1-1.08 0l-6.21-6.24a4.29 4.29 0 0 1 0-6 4.27 4.27 0 0 1 6 0 1 1 0 0 0 1.42 0 4.27 4.27 0 0 1 6 0 4.29 4.29 0 0 1 .08 6Z"></path></svg>Custom Label</p><div class="starlight-aside__content"><p>Some text</p></div></aside>