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.mdnew file mode 100644index 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`.++@freddymetadiff --git a/apps/storybook/stories/Citation.stories.tsx b/apps/storybook/stories/Citation.stories.tsxindex 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',+ }}><Citationsource={{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.mjsindex 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.tsxindex 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.tsxindex 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>