Skip to content

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

TypeScript

feat(DialogHeader): accept ReactNode title and subtitle (#6746)

ksying95336a1c7833
diff --git a/.changeset/dialog-header-node-title-subtitle.md b/.changeset/dialog-header-node-title-subtitle.md
new file mode 100644
index 0000000000..38ffc9e459
--- /dev/null
+++ b/.changeset/dialog-header-node-title-subtitle.md
@@ -0,0 +1,13 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] `DialogHeader` `title` and `subtitle` now accept any `ReactNode`, not only strings.
+
+A title can carry inline markup and still renders inside the focusable `h2` that
+receives focus on open and names the Dialog; the accessible name is the title's
+text content. A subtitle can carry inline content such as a `Link`. String
+callers are unchanged. An empty-string, boolean, or nullish subtitle renders
+nothing, and a numeric `0` subtitle now renders inside the subtitle text.
+
+@ksying
diff --git a/packages/core/src/Dialog/Dialog.test.tsx b/packages/core/src/Dialog/Dialog.test.tsx
index a7fc4ec22a..b531f4373a 100644
--- a/packages/core/src/Dialog/Dialog.test.tsx
+++ b/packages/core/src/Dialog/Dialog.test.tsx
@@ -805,6 +805,24 @@ describe('Dialog', () => {
expect(dialog).toHaveAccessibleName('Dialog title');
});
+ it('is labelled by the text content of a node title', () => {
+ render(
+ <Dialog isOpen={true} onOpenChange={() => {}}>
+ <DialogHeader
+ title={
+ <span>
+ Rich <strong>dialog</strong> title
+ </span>
+ }
+ />
+ </Dialog>,
+ );
+ const dialog = screen.getByRole('dialog');
+ const heading = screen.getByRole('heading', {level: 2});
+ expect(dialog).toHaveAttribute('aria-labelledby', heading.id);
+ expect(dialog).toHaveAccessibleName('Rich dialog title');
+ });
+
it('prefers a consumer-provided aria-label over the header title', () => {
render(
<Dialog isOpen={true} onOpenChange={() => {}} aria-label="Custom name">
diff --git a/packages/core/src/Dialog/DialogHeader.doc.mjs b/packages/core/src/Dialog/DialogHeader.doc.mjs
index e10d32555a..2a189283f9 100644
--- a/packages/core/src/Dialog/DialogHeader.doc.mjs
+++ b/packages/core/src/Dialog/DialogHeader.doc.mjs
@@ -21,13 +21,13 @@ export const docs = {
props: [
{
name: 'title',
- type: 'string',
- description: 'Dialog title (receives focus on open and labels the dialog via aria-labelledby).',
+ type: 'ReactNode',
+ description: 'Dialog title, rendered inside the focusable h2 (receives focus on open; its text content labels the dialog via aria-labelledby unless the Dialog has an explicit aria-label/aria-labelledby). Keep it inline, non-interactive, and non-empty.',
},
{
name: 'subtitle',
- type: 'string',
- description: 'Subtitle below the title.',
+ type: 'ReactNode',
+ description: 'Subtitle below the title. Accepts inline content such as a Link; avoid block elements.',
},
{
name: 'onOpenChange',
@@ -117,6 +117,23 @@ function Header() {
// Passing onOpenChange renders a close button that calls it with false.
return <DialogHeader title="Settings" onOpenChange={setIsOpen} />;
}
+`,
+ },
+ {
+ label: 'With a link in the subtitle',
+ code: `
+import {DialogHeader} from '@astryxdesign/core/Dialog';
+import {Link} from '@astryxdesign/core/Link';
+
+<DialogHeader
+ title="Share conversation"
+ subtitle={
+ <>
+ Anyone with the link can view it. Review the{' '}
+ <Link href="#sharing-policy">sharing policy</Link> first.
+ </>
+ }
+/>;
`,
},
{
@@ -154,13 +171,13 @@ export const docsZh = {
props: [
{
name: 'title',
- type: 'string',
- description: '对话框标题(打开时获得焦点)。',
+ type: 'ReactNode',
+ description: '对话框标题,渲染在可聚焦的 h2 中(打开时获得焦点,其文本内容通过 aria-labelledby 为对话框命名)。请使用非空、非交互的行内内容。',
},
{
name: 'subtitle',
- type: 'string',
- description: '标题下方的副标题。',
+ type: 'ReactNode',
+ description: '标题下方的副标题,可包含链接等行内内容;避免使用块级元素。',
},
{
name: 'onOpenChange',
@@ -216,8 +233,8 @@ export const docsDense = {
],
},
propDescriptions: {
- title: 'dialog title (focused on open; labels dialog via aria-labelledby)',
- subtitle: 'subtitle below title',
+ title: 'dialog title node inside focusable h2 (focused on open; text content labels dialog via aria-labelledby); inline, non-interactive, non-empty',
+ subtitle: 'subtitle node below title; inline content ok (e.g. Link), no block elements',
onOpenChange: 'close button callback (omit=no button)',
startContent: 'content before title (e.g. back button)',
endContent: 'content after title, before close button',
diff --git a/packages/core/src/Dialog/DialogHeader.test.tsx b/packages/core/src/Dialog/DialogHeader.test.tsx
index 595efff8bc..ebdf4d619c 100644
--- a/packages/core/src/Dialog/DialogHeader.test.tsx
+++ b/packages/core/src/Dialog/DialogHeader.test.tsx
@@ -13,6 +13,7 @@ import {describe, it, expect, vi} from 'vitest';
import {render, screen} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {DialogHeader} from './DialogHeader';
+import {Link} from '../Link';
import {LayoutDividerContext} from '../Layout/LayoutDividerContext';
import {defineTheme} from '../theme/defineTheme';
import {generateThemeCSS} from '../theme/generateThemeRules';
@@ -69,6 +70,67 @@ describe('DialogHeader', () => {
expect(screen.queryByText('This is a subtitle')).not.toBeInTheDocument();
});
+ it('renders a node title inside the focusable h2', () => {
+ render(
+ <DialogHeader
+ title={
+ <span data-testid="rich-title">
+ Send <em>feedback</em>
+ </span>
+ }
+ />,
+ );
+ const heading = screen.getByRole('heading', {
+ level: 2,
+ name: 'Send feedback',
+ });
+ expect(heading).toContainElement(screen.getByTestId('rich-title'));
+ expect(heading).toHaveAttribute('tabindex', '-1');
+ expect(document.activeElement).toBe(heading);
+ });
+
+ it('renders a node subtitle and keeps its link', () => {
+ render(
+ <DialogHeader
+ title="Share"
+ subtitle={
+ <>
+ Review the <Link href="#policy">sharing policy</Link> first.
+ </>
+ }
+ />,
+ );
+ const link = screen.getByRole('link', {name: 'sharing policy'});
+ expect(link).toHaveAttribute('href', '#policy');
+ expect(link.closest('.astryx-dialog-header-title-block')).not.toBeNull();
+ expect(screen.getByRole('heading', {level: 2})).not.toContainElement(link);
+ });
+
+ it('renders a numeric zero subtitle inside the title block', () => {
+ const {container} = render(<DialogHeader title="Title" subtitle={0} />);
+ const titleBlock = container.querySelector(
+ '.astryx-dialog-header-title-block',
+ );
+ expect(titleBlock?.children).toHaveLength(2);
+ expect(titleBlock?.children[1]).toHaveTextContent(/^0$/);
+ });
+
+ it.each([
+ ['empty string', ''],
+ ['false', false],
+ ['true', true],
+ ['null', null],
+ ['undefined', undefined],
+ ])('renders no subtitle for %s', (_, subtitle) => {
+ const {container} = render(
+ <DialogHeader title="Title" subtitle={subtitle} />,
+ );
+ const titleBlock = container.querySelector(
+ '.astryx-dialog-header-title-block',
+ );
+ expect(titleBlock?.children).toHaveLength(1);
+ });
+
it('renders close button when onOpenChange is provided', () => {
render(<DialogHeader title="Title" onOpenChange={() => {}} />);
const closeButton = screen.getByRole('button', {name: /close/i});
diff --git a/packages/core/src/Dialog/DialogHeader.tsx b/packages/core/src/Dialog/DialogHeader.tsx
index c0266aaf4d..2c86294d87 100644
--- a/packages/core/src/Dialog/DialogHeader.tsx
+++ b/packages/core/src/Dialog/DialogHeader.tsx
@@ -72,16 +72,23 @@ export interface DialogHeaderProps extends BaseProps<HTMLDivElement> {
ref?: React.Ref<HTMLDivElement>;
/**
* The title of the dialog.
+ * Rendered inside the dialog's focusable h2, so rich inline content (for
+ * example a styled span) keeps the heading semantics. Keep it inline,
+ * non-interactive, and non-empty: its text becomes the dialog's name.
* This title receives focus when the dialog opens for screen reader
* accessibility, and names the parent Dialog via aria-labelledby unless the
- * consumer passes an explicit aria-label/aria-labelledby to the Dialog.
+ * consumer passes an explicit aria-label/aria-labelledby to the Dialog. The
+ * accessible name is the rendered title's text content.
*/
- title: string;
+ title: ReactNode;
/**
* Optional subtitle displayed below the title in smaller, secondary text.
+ * Accepts inline content such as a Link; it renders inside a span, so
+ * avoid block elements. Nothing renders for `null`, `undefined`, booleans,
+ * or an empty string.
*/
- subtitle?: string;
+ subtitle?: ReactNode;
/**
* Callback fired when the dialog visibility changes.
@@ -157,6 +164,10 @@ export function DialogHeader({
const dialogContext = useDialogContext();
const shouldAutoFocus = dialogContext?.isInline !== true;
const titleId = dialogContext?.titleId;
+ // A node subtitle may be `0`: render it inside Text instead of letting a
+ // truthiness check leak a bare text node, and skip only empty values.
+ const hasSubtitle =
+ subtitle != null && typeof subtitle !== 'boolean' && subtitle !== '';
const shouldCompensateEndBlock =
endContentEdgeCompensation == null
? onOpenChange != null
@@ -214,7 +225,7 @@ export function DialogHeader({
xstyle={styles.titleFocusable}>
{title}
</Heading>
- {subtitle && (
+ {hasSubtitle && (
<Text type="body" size="sm" color="secondary">
{subtitle}
</Text>