An open source design system that's fully customizable and agent ready
TypeScript
feat(Dialog): expose DialogHeader theme targets (#6240)
ksying224b530656ea
diff --git a/.changeset/dialog-header-theme-targets.md b/.changeset/dialog-header-theme-targets.mdnew file mode 100644index 0000000000..db96bffbaa--- /dev/null+++ b/.changeset/dialog-header-theme-targets.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[feature] DialogHeader exposes theme targets for its header gap, title/subtitle gap, and close-icon size.++@ksyingdiff --git a/packages/cli/foundation/discovery/theming-targets.test.mjs b/packages/cli/foundation/discovery/theming-targets.test.mjsindex 0377a1dae4..34623084e1 100644--- a/packages/cli/foundation/discovery/theming-targets.test.mjs+++ b/packages/cli/foundation/discovery/theming-targets.test.mjs@@ -258,6 +258,35 @@ describe('collectThemingTargets', () => {},);+ it('keeps DialogHeader theming metadata available in its direct doc', async () => {+ const doc = await loadComponentDoc(+ path.join(coreSrc, 'Dialog', 'DialogHeader.doc.mjs'),+ );+ expect(doc.subComponentOf).toBe('Dialog');+ expect(doc.theming.targets).toEqual([+ {className: 'astryx-dialog-header'},+ {className: 'astryx-dialog-header-title-block'},+ {className: 'astryx-dialog-header-close-icon'},+ ]);+ });++ it.each([+ 'dialog-header',+ 'dialog-header-title-block',+ 'dialog-header-close-icon',+ ])('enumerates %s once under its canonical Dialog owner', async key => {+ const matches = (await enumerated).filter(target => target.key === key);+ expect(matches).toEqual([+ {+ key,+ className: `astryx-${key}`,+ component: 'Dialog',+ props: [],+ states: [],+ },+ ]);+ });+it.each(['table-header', 'table-body', 'table-footer'])('enumerates %s once under its canonical Table owner',async key => {diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjsindex 78f3fc230e..15ca9414a4 100644--- a/packages/core/src/Dialog/Dialog.doc.mjs+++ b/packages/core/src/Dialog/Dialog.doc.mjs@@ -30,6 +30,9 @@ export const docs = {container: true,targets: [{className: 'astryx-dialog', visualProps: ['variant']},+ {className: 'astryx-dialog-header'},+ {className: 'astryx-dialog-header-title-block'},+ {className: 'astryx-dialog-header-close-icon'},],vars: [{name: '--_dialog-radius', description: 'Border radius of the dialog', default: 'var(--radius-container)', private: true},diff --git a/packages/core/src/Dialog/Dialog.spec.md b/packages/core/src/Dialog/Dialog.spec.mdindex ca21369ab7..486e3f9812 100644--- a/packages/core/src/Dialog/Dialog.spec.md+++ b/packages/core/src/Dialog/Dialog.spec.md@@ -17,7 +17,7 @@ verified_by:packages/core/src/Dialog/__tests__/Dialog.a11y.test.tsx,packages/core/src/Dialog/__tests__/Dialog.a11y.chromium.spec.ts,]-modules: []+modules: [module:Dialog/DialogHeader]families: [family:overlay-dismissal]design_specs: []architecture:diff --git a/packages/core/src/Dialog/DialogHeader.doc.mjs b/packages/core/src/Dialog/DialogHeader.doc.mjsindex 876cde22a6..609191a793 100644--- a/packages/core/src/Dialog/DialogHeader.doc.mjs+++ b/packages/core/src/Dialog/DialogHeader.doc.mjs@@ -8,6 +8,14 @@ export const docs = {displayName: 'Dialog Header',isHiddenFromOverview: true,description: 'Header for dialogs with a title, optional subtitle, close button, and start/end content slots.',+ usage: {+ description: 'Use DialogHeader to give a dialog a labelled title area and optional close control.',+ anatomy: [+ {name: 'Header row', required: true, description: 'Arranges the title block, optional start/end content, and close control.'},+ {name: 'Title block', required: true, description: 'Groups the title and optional subtitle.'},+ {name: 'Close icon', required: false, description: 'Visual close glyph inside the close button.'},+ ],+ },props: [{name: 'title',@@ -72,6 +80,13 @@ export const docs = {hasDivider: true,},},+ theming: {+ targets: [+ {className: 'astryx-dialog-header'},+ {className: 'astryx-dialog-header-title-block'},+ {className: 'astryx-dialog-header-close-icon'},+ ],+ },examples: [{label: 'Basic',@@ -117,6 +132,14 @@ export const docsZh = {isHiddenFromOverview: true,displayName: 'Dialog Header',description: '对话框头部,包含标题、可选副标题、关闭按钮以及首尾内容插槽。',+ usage: {+ description: '使用 DialogHeader 为对话框提供带标签的标题区和可选的关闭控件。',+ anatomy: [+ {name: 'Header row', required: true, description: '排列标题区、可选的首尾内容和关闭控件。'},+ {name: 'Title block', required: true, description: '组合标题和可选副标题。'},+ {name: 'Close icon', required: false, description: '关闭按钮内的关闭图标。'},+ ],+ },props: [{name: 'title',@@ -150,6 +173,13 @@ export const docsZh = {default: 'true',},],+ theming: {+ targets: [+ {className: 'astryx-dialog-header'},+ {className: 'astryx-dialog-header-title-block'},+ {className: 'astryx-dialog-header-close-icon'},+ ],+ },};export const docsDense = {@@ -157,6 +187,14 @@ export const docsDense = {isHiddenFromOverview: true,displayName: 'Dialog Header',description: 'dialog header w/ title, optional subtitle, close button, start/end content slots',+ usage: {+ description: 'labelled dialog title area + optional close control',+ anatomy: [+ {name: 'Header row', required: true, description: 'arranges title block, optional start/end content, close control'},+ {name: 'Title block', required: true, description: 'groups title + optional subtitle'},+ {name: 'Close icon', required: false, description: 'close glyph inside close button'},+ ],+ },propDescriptions: {title: 'dialog title (focused on open; labels dialog via aria-labelledby)',subtitle: 'subtitle below title',diff --git a/packages/core/src/Dialog/DialogHeader.test.tsx b/packages/core/src/Dialog/DialogHeader.test.tsxindex f012b58f51..168c39a0b5 100644--- a/packages/core/src/Dialog/DialogHeader.test.tsx+++ b/packages/core/src/Dialog/DialogHeader.test.tsx@@ -14,6 +14,13 @@ import {render, screen} from '@testing-library/react';import userEvent from '@testing-library/user-event';import {DialogHeader} from './DialogHeader';import {LayoutDividerContext} from '../Layout/LayoutDividerContext';+import {defineTheme} from '../theme/defineTheme';+import {generateThemeCSS} from '../theme/generateThemeRules';++function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {+ const {prose, component} = generateThemeCSS(theme);+ return [prose, component].filter(Boolean).join('\n\n');+}describe('DialogHeader', () => {it('renders the title', () => {@@ -56,6 +63,48 @@ describe('DialogHeader', () => {expect(screen.getByRole('button', {name: /close/i})).toBeInTheDocument();});+ it('exposes theme targets for the header row, title block, and close icon', () => {+ const {container} = render(+ <DialogHeader+ title="Title"+ subtitle="Subtitle"+ onOpenChange={() => {}}+ />,+ );++ expect(container.querySelector('.astryx-dialog-header')).not.toBeNull();+ expect(screen.getByRole('heading', {level: 2}).parentElement).toHaveClass(+ 'astryx-dialog-header-title-block',+ );++ const closeIcon = screen+ .getByRole('button', {name: /close/i})+ .querySelector('.astryx-dialog-header-close-icon');+ expect(closeIcon).toHaveClass('astryx-icon');+ });++ it('lets themes set the two internal gaps and close-icon size', () => {+ const theme = defineTheme({+ name: 'dialog-header-targets-test',+ components: {+ 'dialog-header': {base: {gap: '8px'}},+ 'dialog-header-title-block': {base: {gap: '4px'}},+ 'dialog-header-close-icon': {+ base: {width: '16px', height: '16px', fontSize: '16px'},+ },+ },+ });+ const css = generateThemeTestCSS(theme);++ expect(css).toContain('.astryx-dialog-header {');+ expect(css).toContain('gap: 8px');+ expect(css).toContain('.astryx-dialog-header-title-block {');+ expect(css).toContain('gap: 4px');+ expect(css).toContain('.astryx-dialog-header-close-icon {');+ expect(css).toContain('width: 16px');+ expect(css).toContain('height: 16px');+ });+it('does not render close button when onOpenChange is not provided', () => {render(<DialogHeader title="Title" />);expect(diff --git a/packages/core/src/Dialog/DialogHeader.tsx b/packages/core/src/Dialog/DialogHeader.tsxindex d32c2e88cd..5f37e4c238 100644--- a/packages/core/src/Dialog/DialogHeader.tsx+++ b/packages/core/src/Dialog/DialogHeader.tsx@@ -4,7 +4,7 @@/*** @file DialogHeader.tsx- * @input Uses React, useEffect, useRef, LayoutHeader, Button, Icon, Heading, Text, DialogContext+ * @input Uses React, StyleX, LayoutHeader, Button, Icon, Heading, Text, DialogContext, mergeProps, themeProps* @output Exports DialogHeader component and DialogHeaderProps* @position Dialog header component; used with Dialog and Layout*@@ -25,6 +25,8 @@ import {Icon} from '../Icon';import {Heading} from '../Heading/Heading';import {Text} from '../Text/Text';import type {BaseProps} from '../BaseProps';+import {mergeProps} from '../utils';+import {themeProps} from '../utils/themeProps';import {useDialogContext} from './DialogContext';import {useTranslator} from '../i18n';@@ -41,6 +43,9 @@ const styles = stylex.create({marginInlineEnd: `calc(-1 * ${spacingVars['--spacing-2']})`,},titleWrapper: {+ display: 'flex',+ flexDirection: 'column',+ gap: spacingVars['--spacing-0'],flex: 1,minWidth: 0,// Visual centering: align title center with close button center@@ -161,11 +166,19 @@ export function DialogHeader({className={className}style={style}{...rest}>- <div {...stylex.props(styles.container)}>+ <div+ {...mergeProps(+ themeProps('dialog-header'),+ stylex.props(styles.container),+ )}>{startContent && (<div {...stylex.props(styles.actions)}>{startContent}</div>)}- <div {...stylex.props(styles.titleWrapper)}>+ <div+ {...mergeProps(+ themeProps('dialog-header-title-block'),+ stylex.props(styles.titleWrapper),+ )}><Headingref={titleRef}id={titleId}@@ -192,7 +205,13 @@ export function DialogHeader({variant="ghost"label={t('@astryx.dialog.close')}tooltip={t('@astryx.dialog.close')}- icon={<Icon icon="close" color="inherit" />}+ icon={+ <Icon+ icon="close"+ color="inherit"+ {...themeProps('dialog-header-close-icon')}+ />+ }onClick={() => {onOpenChange?.(false);}}diff --git a/packages/core/src/Dialog/modules/DialogHeader.spec.md b/packages/core/src/Dialog/modules/DialogHeader.spec.mdnew file mode 100644index 0000000000..14d3ed51d2--- /dev/null+++ b/packages/core/src/Dialog/modules/DialogHeader.spec.md@@ -0,0 +1,152 @@+---+schema_version: 3+template_version: 1+kind: module+id: module:Dialog/DialogHeader+authority: current+archive_reason: null+superseded_by: null+approved_by: cixzhang+approved_at: 2026-09-14+owners: [cixzhang, imdreamrunner]+review_triggers: [theming, layout]+verified_by:+ [+ packages/core/src/Dialog/DialogHeader.test.tsx,+ packages/core/src/theme/themingTargets.test.ts,+ scripts/check-knowledge.mjs,+ ]+parent_component: component:Dialog+references: [architecture:component-theming-surface]+---++# DialogHeader module contract++## Intent++`DialogHeader` presents the title region of a Dialog and its optional close+control. This record owns the stable header-row, title-block, and close-icon+anatomy and their public theming targets.++## Compatibility and migration++- Released default preserved: `yes`+- Compatibility class: additive theme targets only; default layout, paint,+ interaction, accessibility, and public props remain unchanged+- Migration decision: none++Consumer migration instructions belong in consumer docs and release notes.++## Ownership boundary++**Owns**++- The header row that arranges title content and trailing controls.+- The title block that groups the title and optional subtitle.+- The close icon rendered for the optional close action.+- The `dialog-header`, `dialog-header-title-block`, and+ `dialog-header-close-icon` targets.++**Does not own / non-goals**++- Dialog modality, dismissal policy, or focus lifecycle — owned by+ `component:Dialog` and its linked system records.+- Generic Button or Icon presentation outside this module — owned by those+ components.+- New public props or default visual changes.++## Public API and concepts++No component prop changes. This contract adds three public theming surfaces for+existing anatomy.++| Concept | Closed values or states | Meaning | Default | Owner | Stability |+| --- | --- | --- | --- | --- | --- |+| Header row target | present | Styles the row that arranges title content and controls | Existing row visuals | `module:Dialog/DialogHeader` | stable |+| Title block target | present | Styles the title/subtitle grouping element | Existing title stack visuals | `module:Dialog/DialogHeader` | stable |+| Close icon target | present when close action renders | Styles the close glyph itself | Existing medium Icon visuals | `module:Dialog/DialogHeader` | stable |++## Behavioral contract++| ID | Invariant | Basis | Review state |+| --- | --- | --- | --- |+| FR1 | The header row MUST carry `dialog-header` on the element that applies its row layout and gap. | Current implementation and owner decision | settled |+| FR2 | The title block MUST carry `dialog-header-title-block` on the element that applies its title/subtitle layout and gap. | Current implementation and owner decision | settled |+| FR3 | The rendered close Icon MUST carry `dialog-header-close-icon` on the glyph element that applies icon presentation. | Current implementation and owner decision | settled |+| FR4 | Omitting `onOpenChange` MUST continue to omit the close action and its optional close-icon anatomy. | Released behavior | settled |++### Transformation and precedence order++- The module applies each target to its owning element before normal theme CSS+ resolves through the shared theming pipeline.++### Performance and resources++- The additive class names and metadata introduce no listener, observer, timer,+ measurement, or asynchronous resource.++## Accessibility contract++- Theme targets MUST NOT change the title's role, focus behavior, dialog naming,+ or the close button's accessible name and operation.++## Design relationships++| Anatomy or state | Design requirement | Representation authority | Module contract |+| --- | --- | --- | --- |+| Header row | Owns arrangement and spacing among title content and controls. | This module | FR1 |+| Title block | Owns title/subtitle grouping and spacing. | This module | FR2 |+| Close icon | Owns the close glyph's visual box inside the Button-owned action. | This module with Icon rendering | FR3, FR4 |++### Theming anatomy++<!-- anatomy-theming:v1 -->++```json+{+ "Header row": {"target": "dialog-header"},+ "Title block": {"target": "dialog-header-title-block"},+ "Close icon": {"target": "dialog-header-close-icon"}+}+```++## Parent and system relationships++- `component:Dialog` owns modal behavior and the aggregate Dialog contract.+- `component:Layout` owns the composed LayoutHeader region outside the three+ module-owned inner parts.+- `component:Button` owns the close action's control behavior and outer button+ presentation.+- `component:Icon` renders the glyph; this module guarantees a distinct target+ for the close icon's DialogHeader-specific visual contract.+- `architecture:component-theming-surface` owns target qualification, anatomy+ mapping, and the requirement that each target sits on its painter.++## Verification map++| Contract | Verification | Representative states | Mutation or failure expectation |+| --- | --- | --- | --- |+| FR1–FR3 | `DialogHeader.test.tsx`, target inventory, generated probe theme, and source inspection | title only, title/subtitle, close action | A target is missing, undocumented, or moved away from its owning painter. |+| FR4 | Existing close-button presence tests | with and without `onOpenChange` | The optional target renders without the optional close action. |+| Theming anatomy map | `scripts/check-knowledge.mjs` | all three module anatomy entries and targets | Anatomy, docs, runtime targets, and the module map drift. |++## Decision log++### DEC-1 — Header targets follow stable anatomy and visual ownership++**Reference:** `module:Dialog/DialogHeader/DEC-1`+**Decider:** cixzhang, 2026-09-14++Each public target represents documented anatomy and is applied to the element+that owns the corresponding visuals. The header row, title block, and close icon+meet that admission rule and are approved as additive targets.++## Open questions++None.++## Content boundary++This record does not duplicate consumer signatures/examples, parent Dialog+behavior, implementation steps, or shared theming rules. It links to their+canonical owners.diff --git a/packages/themes/probe/src/probeTheme.ts b/packages/themes/probe/src/probeTheme.tsindex e67c09d5fa..8f88b9d7d2 100644--- a/packages/themes/probe/src/probeTheme.ts+++ b/packages/themes/probe/src/probeTheme.ts@@ -6,7 +6,7 @@// test fixture. Regenerate with: pnpm visual:probe-theme//// defineTheme takes six things and this covers all six:-// components 278 targets, 906 selectors (generated from the docs)+// components 282 targets, 913 selectors (generated from the docs)// tokens custom properties, read back off the themed element// icons every registry entry swapped for a marked glyph// indicators check / radio / checkbox swapped — the swap that reaches furthest@@ -2052,6 +2052,30 @@ export const probeTheme = defineTheme({outlineColor: 'hsl(240.3 74% 25%)',},},+ 'dialog-header': {+ base: {+ backgroundColor: 'hsl(312.1 73% 56%)',+ color: 'hsl(253.8 72% 12%)',+ borderColor: 'hsl(79.0 70% 25%)',+ outlineColor: 'hsl(252.5 77% 25%)',+ },+ },+ 'dialog-header-close-icon': {+ base: {+ backgroundColor: 'hsl(90.9 85% 52%)',+ color: 'hsl(55.2 71% 12%)',+ borderColor: 'hsl(180.8 84% 25%)',+ outlineColor: 'hsl(215.4 89% 25%)',+ },+ },+ 'dialog-header-title-block': {+ base: {+ backgroundColor: 'hsl(279.3 88% 58%)',+ color: 'hsl(210.9 80% 12%)',+ borderColor: 'hsl(219.8 84% 25%)',+ outlineColor: 'hsl(358.8 73% 25%)',+ },+ },divider: {base: {backgroundColor: 'hsl(26.4 77% 53%)',@@ -3973,6 +3997,32 @@ export const probeTheme = defineTheme({outlineColor: 'hsl(58.8 73% 25%)',},},+ 'scrollable-area': {+ base: {+ backgroundColor: 'hsl(170.2 82% 57%)',+ color: 'hsl(26.0 76% 12%)',+ borderColor: 'hsl(40.8 70% 25%)',+ outlineColor: 'hsl(17.3 90% 25%)',+ },+ 'axis:inline': {+ backgroundColor: 'hsl(118.1 92% 62%)',+ color: 'hsl(340.0 75% 12%)',+ borderColor: 'hsl(98.6 94% 25%)',+ outlineColor: 'hsl(163.6 70% 25%)',+ },+ 'axis:block': {+ backgroundColor: 'hsl(310.5 79% 45%)',+ color: 'hsl(156.4 74% 12%)',+ borderColor: 'hsl(34.4 81% 25%)',+ outlineColor: 'hsl(180.6 89% 25%)',+ },+ 'axis:both': {+ backgroundColor: 'hsl(170.0 84% 52%)',+ color: 'hsl(112.4 74% 12%)',+ borderColor: 'hsl(281.8 89% 25%)',+ outlineColor: 'hsl(288.5 81% 25%)',+ },+ },section: {base: {backgroundColor: 'hsl(337.5 74% 48%)',