Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(citation): accept ReactNode icon on CitationSource (+ src for image URLs) (#4418)

freddymetaaae117cf3ab5
diff --git a/.changeset/citation-icon-reactnode.md b/.changeset/citation-icon-reactnode.md
new file mode 100644
index 0000000000..a3758f1951
--- /dev/null
+++ b/.changeset/citation-icon-reactnode.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Citation: `CitationSource.icon` now accepts a `ReactNode` (e.g. an Astryx `<Icon>`, an SVG, or a custom element) in addition to an image URL string, and a new `CitationSource.src` field holds a favicon/logo image URL (mirroring `Avatar`/`Thumbnail`). Additive and non-breaking: a string `icon` still renders as the favicon `<img>`, so existing callers are unaffected. When both a node `icon` and `src` are set, the node wins. The icon stays decorative — the accessible name still comes solely from the citation's `aria-label`.
+
+@freddymeta
diff --git a/apps/storybook/stories/Citation.stories.tsx b/apps/storybook/stories/Citation.stories.tsx
index 6f02242c4b..aed9b71556 100644
--- a/apps/storybook/stories/Citation.stories.tsx
+++ b/apps/storybook/stories/Citation.stories.tsx
@@ -2,6 +2,7 @@
import type {Meta, StoryObj} from '@storybook/react';
import {Citation} from '@astryxdesign/core/Citation';
+import {Icon} from '@astryxdesign/core/Icon';
const meta: Meta<typeof Citation> = {
title: 'Core/Citation',
@@ -51,6 +52,34 @@ export const WithIcon: Story = {
},
};
+// An image URL can also be passed via the idiomatic `src` field (mirrors
+// Avatar/Thumbnail). Behaves identically to a string `icon`.
+export const WithImageSrc: Story = {
+ args: {
+ source: {
+ title: 'GitHub',
+ url: 'https://github.com',
+ src: 'https://github.githubassets.com/favicons/favicon.svg',
+ },
+ number: 3,
+ variant: 'label',
+ },
+};
+
+// A real icon: pass an Astryx <Icon> (or any React node) to `icon` instead of
+// an image URL. Rendered as-is inside the icon circle.
+export const WithNodeIcon: Story = {
+ args: {
+ source: {
+ title: 'Documentation',
+ url: 'https://example.com',
+ icon: <Icon icon="externalLink" size="sm" />,
+ },
+ number: 3,
+ variant: 'label',
+ },
+};
+
export const NoLink: Story = {
args: {
source: {title: 'Internal reference'},
@@ -61,7 +90,13 @@ export const NoLink: Story = {
export const Variants: Story = {
render: () => (
- <div style={{display: 'flex', gap: '12px', alignItems: 'center', flexWrap: 'wrap'}}>
+ <div
+ style={{
+ display: 'flex',
+ gap: '12px',
+ alignItems: 'center',
+ flexWrap: 'wrap',
+ }}>
<Citation
source={{title: 'React Docs', url: 'https://react.dev'}}
number={1}
@@ -82,7 +117,10 @@ export const Variants: Story = {
variant="label"
/>
<Citation
- source={{title: 'A very long source title that should be truncated with ellipsis'}}
+ source={{
+ title:
+ 'A very long source title that should be truncated with ellipsis',
+ }}
number={4}
variant="label"
/>
diff --git a/packages/core/src/Citation/Citation.doc.mjs b/packages/core/src/Citation/Citation.doc.mjs
index f74bf041fd..9dad0175fa 100644
--- a/packages/core/src/Citation/Citation.doc.mjs
+++ b/packages/core/src/Citation/Citation.doc.mjs
@@ -39,7 +39,7 @@ export const docs = {
name: 'Icon',
required: false,
description:
- 'An optional favicon or source icon displayed before the label text. Only available in the label variant.',
+ 'An optional source icon shown before the label text. Accepts a favicon/logo image URL (via source.src) or a React node such as an Astryx <Icon>. Only available in the label variant.',
},
{
name: 'Label text',
@@ -71,7 +71,7 @@ export const docs = {
name: 'source',
type: 'CitationSource',
description:
- 'The citation source object containing title, url, and optional icon.',
+ 'The citation source object containing title, url, an optional image src, and an optional icon node.',
required: true,
},
{
@@ -121,7 +121,8 @@ export const docsDense = {
],
},
propDescriptions: {
- source: 'citation source object with title, url, optional icon.',
+ source:
+ 'citation source object with title, url, optional image src, and optional icon node.',
number: 'display index for this citation.',
variant: 'display style: label chip with source title or compact numbered badge.',
},
diff --git a/packages/core/src/Citation/Citation.test.tsx b/packages/core/src/Citation/Citation.test.tsx
index efc3ae653f..8bf97876c3 100644
--- a/packages/core/src/Citation/Citation.test.tsx
+++ b/packages/core/src/Citation/Citation.test.tsx
@@ -169,4 +169,101 @@ describe('Citation', () => {
expect(el.classList.contains(cls)).toBe(true);
}
});
+
+ // --- Source icon: image URL (back-compat) vs ReactNode ---------------------
+
+ it('renders a legacy string icon as a decorative image (back-compat)', () => {
+ // Existing callers pass a favicon URL to `source.icon`. A bare string must
+ // still render as <img src>, unchanged from the original behavior.
+ const {container} = render(
+ <Citation
+ source={{
+ title: 'GitHub',
+ url: 'https://github.com',
+ icon: 'https://example.com/favicon.png',
+ }}
+ number={1}
+ data-testid="citation"
+ />,
+ );
+ const img = container.querySelector('img');
+ expect(img).not.toBeNull();
+ expect(img).toHaveAttribute('src', 'https://example.com/favicon.png');
+ // Decorative: empty alt, and the wrapper is aria-hidden.
+ expect(img).toHaveAttribute('alt', '');
+ expect(container.querySelector('[aria-hidden="true"] img')).toBe(img);
+ });
+
+ it('renders source.src as a decorative image', () => {
+ const {container} = render(
+ <Citation
+ source={{
+ title: 'GitHub',
+ url: 'https://github.com',
+ src: 'https://example.com/logo.png',
+ }}
+ number={1}
+ data-testid="citation"
+ />,
+ );
+ const img = container.querySelector('img');
+ expect(img).toHaveAttribute('src', 'https://example.com/logo.png');
+ expect(img).toHaveAttribute('alt', '');
+ });
+
+ it('renders a ReactNode icon as-is (not an <img>)', () => {
+ const {container} = render(
+ <Citation
+ source={{
+ title: 'GitHub',
+ url: 'https://github.com',
+ icon: <svg data-testid="custom-icon" />,
+ }}
+ number={1}
+ data-testid="citation"
+ />,
+ );
+ // The node renders directly; no <img> is produced for a node icon.
+ expect(container.querySelector('img')).toBeNull();
+ expect(screen.getByTestId('custom-icon')).toBeInTheDocument();
+ // Still decorative — wrapped in an aria-hidden container.
+ expect(
+ container.querySelector(
+ '[aria-hidden="true"] [data-testid="custom-icon"]',
+ ),
+ ).not.toBeNull();
+ });
+
+ it('prefers a node icon over src when both are provided', () => {
+ const {container} = render(
+ <Citation
+ source={{
+ title: 'GitHub',
+ url: 'https://github.com',
+ src: 'https://example.com/logo.png',
+ icon: <svg data-testid="custom-icon" />,
+ }}
+ number={1}
+ data-testid="citation"
+ />,
+ );
+ expect(screen.getByTestId('custom-icon')).toBeInTheDocument();
+ expect(container.querySelector('img')).toBeNull();
+ });
+
+ it('keeps aria-label as the sole accessible name when an icon is present', () => {
+ render(
+ <Citation
+ source={{
+ title: 'GitHub',
+ url: 'https://github.com',
+ icon: 'https://example.com/favicon.png',
+ }}
+ number={2}
+ data-testid="citation"
+ />,
+ );
+ const el = screen.getByTestId('citation');
+ expect(el).toHaveAttribute('aria-label', 'Citation 2: GitHub');
+ });
});
diff --git a/packages/core/src/Citation/Citation.tsx b/packages/core/src/Citation/Citation.tsx
index b880ed677f..f08adc75f1 100644
--- a/packages/core/src/Citation/Citation.tsx
+++ b/packages/core/src/Citation/Citation.tsx
@@ -10,10 +10,14 @@
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Citation/index.ts (exports if types change)
+ * - /packages/core/src/Citation/Citation.doc.mjs (props table, features)
+ * - /packages/core/src/Citation/Citation.test.tsx (tests for new/changed behavior)
+ * - /apps/storybook/stories/Citation.stories.tsx (storybook stories)
* - /packages/cli/templates/blocks/components/Citation/ (showcase blocks)
*/
import type React from 'react';
+import type {ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
colorVars,
@@ -29,11 +33,29 @@ import {mergeProps} from '../utils';
import type {BaseProps} from '../BaseProps';
import {themeProps} from '../utils/themeProps';
import {useTranslator} from '../i18n';
+import {renderIconSlot} from '../Icon';
export interface CitationSource {
title?: string;
url?: string;
- icon?: string;
+ /**
+ * Image URL for a favicon or source logo, rendered as `<img src>` inside the
+ * icon circle. This is the idiomatic field for image sources (mirrors
+ * `Avatar`/`Thumbnail` `src`). When both `src` and a non-string `icon` are
+ * provided, `icon` wins.
+ */
+ src?: string;
+ /**
+ * Source icon shown before the label text (label variant only). Accepts:
+ * - a React node / Astryx `<Icon>` / SVG element — rendered as-is, or
+ * - a string image URL — rendered as `<img src>` for backward compatibility
+ * with callers that passed a favicon URL here.
+ *
+ * Note: unlike icon slots elsewhere in the system, a bare string is treated
+ * as an image URL (not a semantic icon name) to preserve the original
+ * favicon behavior. Pass an Astryx `<Icon>` (or other node) for a real icon.
+ */
+ icon?: ReactNode;
}
export interface CitationProps extends BaseProps<HTMLElement> {
@@ -162,7 +184,18 @@ export function Citation({
const t = useTranslator();
const title = source.title ?? String(number);
const href = source.url;
- const icon = source.icon;
+
+ // Resolve the source icon. A non-string `icon` node renders as-is (an Astryx
+ // <Icon>, SVG, avatar, etc.). Otherwise fall back to an image URL: `src`, or
+ // a legacy string passed to `icon` (back-compat — favicon URLs still render
+ // as <img>). The icon is decorative; the accessible name comes solely from
+ // the element's aria-label, so nothing is double-announced.
+ const iconNode =
+ source.icon != null && typeof source.icon !== 'string' ? source.icon : null;
+ const imageSrc =
+ source.src ?? (typeof source.icon === 'string' ? source.icon : undefined);
+ const hasIcon = iconNode != null || imageSrc != null;
+
const Tag = href ? 'a' : 'span';
// `doc-noteref` is a reference role — only appropriate on the interactive
// link form. On a plain (unlinked) span it is not a permitted role
@@ -218,7 +251,7 @@ export function Citation({
themeProps('citation', {variant}),
stylex.props(
styles.label,
- icon != null && styles.labelWithIcon,
+ hasIcon && styles.labelWithIcon,
href != null && styles.labelHover,
href != null && styles.labelInteractive,
xstyle,
@@ -226,14 +259,13 @@ export function Citation({
className,
style,
)}>
- {icon && (
- <span {...stylex.props(styles.iconWrap)}>
- <img
- src={icon}
- alt=""
- aria-hidden="true"
- {...stylex.props(styles.icon)}
- />
+ {hasIcon && (
+ <span aria-hidden="true" {...stylex.props(styles.iconWrap)}>
+ {iconNode != null ? (
+ renderIconSlot(iconNode, {size: 'sm'})
+ ) : (
+ <img src={imageSrc} alt="" {...stylex.props(styles.icon)} />
+ )}
</span>
)}
<span {...stylex.props(styles.labelText)}>{title}</span>