@astryxdesign/core 0.6.1 → 0.6.2-canary.176dfa6

package/src/DateRangeInput/DateRangeInput.spec.md

@@ -0,0 +1,203 @@
+---
+schema_version: 3
+template_version: 4
+kind: component
+id: component:DateRangeInput
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-09-14
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+  [
+    packages/core/src/DateRangeInput/DateRangeInput.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: [family:input-fields, family:overlay-dismissal]
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# DateRangeInput component contract
+
+## Intent
+
+DateRangeInput presents one controlled date range through a labeled field surface.
+Its trigger opens a Calendar-backed Popover and may include a list of quick-select
+presets beside that calendar.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive theme targets plus corrected preset constraint
+  enforcement; default appearance, DOM semantics, and public props remain unchanged
+- Controlled/uncontrolled behavior: unchanged; DateRangeInput remains controlled
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The composite date-range field surface and its range-display trigger.
+- The optional preset list, each preset action, and reflection of a preset's current
+  and disabled states.
+- Converting a selected Calendar range or preset into `onChange` and
+  `changeAction` output.
+
+**Does not own / non-goals**
+
+- Label, description, and status presentation — owned by `component:Field` and
+  `component:FieldStatus`.
+- Calendar-grid rendering and date-cell interaction — owned by
+  `component:Calendar`.
+- Layer hosting and dismissal — owned by `component:Popover` and
+  `family:overlay-dismissal`.
+- Shared clear-button presentation — owned by `component:Field`.
+
+## Public concepts
+
+No public prop or value domain is added. This contract records the existing
+preset-list anatomy and its additive theming surface.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                                                                                                                                             | Basis                                                     | Review state               |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | -------------------------- |
+| FR1 | DateRangeInput MUST present the controlled `value` and emit range changes without maintaining a competing selected range.                                                                                                                                                                       | Current source, docs, and focused tests                   | Verified current behavior  |
+| FR2 | When presets are present, each preset remains an independent button in one labeled group; the applied preset reflects current state and a preset whose endpoint violates `min`, `max`, or `dateConstraints`, or whose range violates `minRangeSpan` or `maxRangeSpan`, reflects disabled state. | Current source, accessibility comments, and focused tests | Verified current behavior  |
+| FR3 | The preset group and each preset button expose stable theme targets; selected and disabled are states of the preset-button target rather than separate targets.                                                                                                                                 | `architecture:component-theming-surface`; #5417 demand    | Approved additive contract |
+| FR4 | Adding theme targets MUST NOT change the Popover, Calendar, button, focus, or selection semantics those elements already own.                                                                                                                                                                   | Composition boundary and compatibility goal               | Approved additive contract |
+
+### Allowed variation
+
+- **AV1 — Preset content.** A caller may omit presets or provide any number of
+  labeled ranges.
+- **AV2 — Calendar layout.** Calendar month count, date constraints, and range
+  bounds may vary without changing preset target identity.
+- **AV3 — Theme output.** Themes may restyle the preset group and buttons while
+  the component's button semantics and state remain unchanged.
+
+### Representative states
+
+| State             | Required invariant                                                                                                                          | Allowed variation       |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| No presets        | No preset group or preset-button target renders.                                                                                            | Calendar configuration  |
+| Presets, no match | Every button carries the preset target with no selected state.                                                                              | Preset count and labels |
+| Applied preset    | The matching button carries `aria-current="true"` and the target's selected state.                                                          | Selected range          |
+| Disabled preset   | A preset that violates an endpoint date constraint or a range-span constraint is natively disabled and carries the target's disabled state. | Constraint source       |
+
+### Transformation and precedence order
+
+- **ORD1 — Preset state.** Resolve each preset's range once, compare it with the
+  controlled value, evaluate `min`, `max`, and `dateConstraints` against both
+  endpoints, evaluate `minRangeSpan` and `maxRangeSpan` against the full range,
+  then reflect selected and disabled state on the same preset-button target.
+- **ORD2 — Preset activation.** An enabled preset emits the already-resolved range;
+  activation does not resolve the preset again.
+
+Endpoint constraints match Calendar selection: they apply to the preset's start
+and end, not every date between them.
+
+### Performance and resources
+
+No new performance or resource constraint is introduced.
+
+## Accessibility contract
+
+- **AR1 — Preset semantics.** Presets remain native buttons in one labeled group,
+  navigated independently by Tab.
+- **AR2 — Current state.** The applied preset remains exposed with
+  `aria-current="true"`; theme state reflection is additive.
+- **AR3 — Disabled state.** A preset that violates an endpoint date constraint or
+  a range-span constraint remains natively disabled; theme state reflection does
+  not replace that behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                              | Representation authority              | Hierarchy role | Component contract |
+| ---------------- | --------------------------------------------------------------- | ------------------------------------- | -------------- | ------------------ |
+| Field surface    | Presents one coherent input boundary.                           | Current source and input-field family | Prominent      | FR1                |
+| Calendar popover | Provides range selection without changing field ownership.      | Popover and Calendar components       | Prominent      | FR1, FR4           |
+| Preset sidebar   | Groups optional shortcuts beside the calendar.                  | Current source and public docs        | Supporting     | FR2, FR3           |
+| Preset button    | Presents one quick-select range and its current/disabled state. | Current source and public docs        | Supporting     | FR2–FR4, AR1–AR3   |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Label": {
+    "delegatesTo": {"owner": "component:Field", "target": "field-label"}
+  },
+  "Field surface": {"target": "date-range-input"},
+  "Trigger button": {
+    "none": {
+      "reason": "unsettled: The composite field surface has a target, but the inner range-display button has no separate current target."
+    }
+  },
+  "Calendar icon": {"target": "date-range-input-toggle-icon"},
+  "Calendar popover": {
+    "delegatesTo": {"owner": "component:Popover", "target": "popover"}
+  },
+  "Preset sidebar": {"target": "date-range-input-presets"},
+  "Preset button": {"target": "date-range-input-preset"},
+  "Clear button": {
+    "delegatesTo": {"owner": "component:Field", "target": "input-clear-button"}
+  },
+  "Status message": {
+    "delegatesTo": {"owner": "component:FieldStatus", "target": "field-status"}
+  }
+}
+```
+
+The deprecated `date-range-input-clear-icon` alias remains compatibility metadata;
+the shared `input-clear-icon` target owns the current glyph contract.
+
+## Family and system relationships
+
+- `family:input-fields` owns field sizing, status placement, loading, disabled
+  reasons, and end-control geometry.
+- `family:overlay-dismissal` owns the Popover dismissal stack.
+- `architecture:component-theming-surface` owns target admission, state
+  reflection, and anatomy mapping.
+
+## Verification map
+
+| Contract            | Verification                                                               | Representative states                                                  | Mutation or failure expectation                                             | Audit section                  |
+| ------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------ |
+| FR1, FR2, AR1–AR3   | `DateRangeInput.test.tsx`                                                  | no match, applied preset, endpoint-invalid preset, span-invalid preset | Semantics or state attributes disappear                                     | `audit:DateRangeInput/presets` |
+| FR3, FR4            | `DateRangeInput.test.tsx`, `themingTargets.test.ts`, generated probe theme | group target, selected button, disabled button                         | Target class/state is missing, undocumented, or placed on the wrong element | `audit:DateRangeInput/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                              | all documented anatomy                                                 | Target ownership or anatomy names drift                                     | `audit:DateRangeInput/theming` |
+
+## Decision log
+
+### DEC-1 — Preset group and buttons are public theme anatomy
+
+**Reference:** `component:DateRangeInput/DEC-1`
+**Decider:** cixzhang, 2026-09-14
+
+The optional preset sidebar and each quick-select button are stable,
+consumer-recognizable parts. `date-range-input-presets` belongs on the group
+that owns sidebar presentation; `date-range-input-preset` belongs on each
+button, with selected and disabled reflected as states rather than separate
+targets. The target additions preserve default visuals and button semantics;
+preset constraint enforcement follows FR2 and ORD1–ORD2.
+
+## Open questions
+
+- **OQ1 — Should the inner range-display trigger receive its own target, or remain
+  represented only by the composite field surface?** (`human-api`)
+
+## Content boundary
+
+This file does not duplicate the consumer prop table, usage examples, Calendar or
+Popover contracts, current audit results, or downstream theme implementation.

package/src/DateRangeInput/DateRangeInput.test.tsx

@@ -370,10 +370,15 @@ describe('DateRangeInput', () => {
       expect(
         screen.queryByRole('listbox', {hidden: true}),
       ).not.toBeInTheDocument();
-      expect(
-        screen.getByRole('group', {name: 'Preset date ranges', hidden: true}),
-      ).toBeInTheDocument();
-      expect(getButton('Last 7 days')).toBeInTheDocument();
+      const group = screen.getByRole('group', {
+        name: 'Preset date ranges',
+        hidden: true,
+      });
+      expect(group).toBeInTheDocument();
+      expect(group).toHaveClass('astryx-date-range-input-presets');
+      expect(getButton('Last 7 days')).toHaveClass(
+        'astryx-date-range-input-preset',
+      );
     });
 
     it('marks the applied preset with aria-current, not aria-selected', () => {
@@ -386,11 +391,99 @@ describe('DateRangeInput', () => {
         />,
       );
       const active = getButton('Last 7 days');
+      expect(active).toHaveClass('astryx-date-range-input-preset');
+      expect(active).toHaveAttribute('data-selected', 'selected');
       expect(active).toHaveAttribute('aria-current', 'true');
       expect(active).not.toHaveAttribute('aria-selected');
       const inactive = getButton('This month');
+      expect(inactive).toHaveClass('astryx-date-range-input-preset');
+      expect(inactive).not.toHaveAttribute('data-selected');
+      expect(inactive).not.toHaveAttribute('data-disabled');
       expect(inactive).not.toHaveAttribute('aria-current');
     });
+
+    it('disables a preset when its start is before min', () => {
+      const handleChange = vi.fn();
+      render(
+        <DateRangeInput
+          label="Range"
+          value={null}
+          onChange={handleChange}
+          min="2026-03-02"
+          presets={[presets[0]]}
+        />,
+      );
+
+      const preset = getButton('Last 7 days');
+      expect(preset).toBeDisabled();
+      fireEvent.click(preset);
+      expect(handleChange).not.toHaveBeenCalled();
+    });
+
+    it('disables a preset when its end is after max', () => {
+      const handleChange = vi.fn();
+      render(
+        <DateRangeInput
+          label="Range"
+          value={null}
+          onChange={handleChange}
+          max="2026-03-06"
+          presets={[presets[0]]}
+        />,
+      );
+
+      const preset = getButton('Last 7 days');
+      expect(preset).toBeDisabled();
+      fireEvent.click(preset);
+      expect(handleChange).not.toHaveBeenCalled();
+    });
+
+    it('disables a preset when either endpoint fails dateConstraints', () => {
+      const handleChange = vi.fn();
+      render(
+        <DateRangeInput
+          label="Range"
+          value={null}
+          onChange={handleChange}
+          dateConstraints={[date => date.getDate() !== 7]}
+          presets={[presets[0]]}
+        />,
+      );
+
+      const preset = getButton('Last 7 days');
+      expect(preset).toBeDisabled();
+      fireEvent.click(preset);
+      expect(handleChange).not.toHaveBeenCalled();
+    });
+
+    it('commits an enabled preset using its already-resolved range', () => {
+      const range = {start: '2026-03-01', end: '2026-03-07'} as const;
+      const getRange = vi.fn(() => range);
+      let getRangeCallsAtChange = 0;
+      const handleChange = vi.fn(() => {
+        getRangeCallsAtChange = getRange.mock.calls.length;
+      });
+      render(
+        <DateRangeInput
+          label="Range"
+          value={null}
+          onChange={handleChange}
+          min="2026-03-01"
+          max="2026-03-31"
+          dateConstraints={[date => date.getDate() !== 13]}
+          minRangeSpan={2}
+          maxRangeSpan={7}
+          presets={[{label: 'Allowed range', getRange}]}
+        />,
+      );
+
+      const getRangeCallsBeforeClick = getRange.mock.calls.length;
+      const preset = getButton('Allowed range');
+      expect(preset).not.toBeDisabled();
+      fireEvent.click(preset);
+      expect(handleChange).toHaveBeenCalledWith(range);
+      expect(getRangeCallsAtChange).toBe(getRangeCallsBeforeClick);
+    });
   });
   describe('disabledMessage', () => {
     // jsdom does not implement the Popover API used by the tooltip, so mock
@@ -831,7 +924,10 @@ describe('DateRangeInput range-span forwarding', () => {
     const withinCap = getButton('Last 3 days');
     const overCap = getButton('Last 30 days');
     expect(withinCap).not.toBeDisabled();
+    expect(withinCap).not.toHaveAttribute('data-disabled');
     expect(overCap).toBeDisabled();
+    expect(overCap).toHaveClass('astryx-date-range-input-preset');
+    expect(overCap).toHaveAttribute('data-disabled', 'disabled');
 
     fireEvent.click(overCap);
     expect(handleChange).not.toHaveBeenCalled();

package/src/DateRangeInput/DateRangeInput.tsx

@@ -54,6 +54,7 @@ import {
   type DayOfWeek,
   type DayOfWeekName,
 } from '../Calendar';
+import {useCalendarConstraints} from '../Calendar/hooks';
 import {usePopover} from '../Popover';
 import {useTooltip} from '../Tooltip';
 import {mergeProps} from '../utils';
@@ -376,6 +377,9 @@ export interface DateRangeInputProps extends Omit<
 
   /**
    * Preset date ranges shown as quick-select options beside the calendar.
+   * A preset is disabled when either endpoint violates `min`, `max`, or
+   * `dateConstraints`, or when its span violates `minRangeSpan` or
+   * `maxRangeSpan`.
    */
   presets?: ReadonlyArray<DateRangePreset>;
 
@@ -542,6 +546,11 @@ export function DateRangeInput({
     dialogLabel: t('@astryx.dateRangeInput.dialogLabel'),
     closeButtonLabel: t('@astryx.dateInput.closeCalendar'),
   });
+  const {isDateDisabled} = useCalendarConstraints({
+    min,
+    max,
+    dateConstraints,
+  });
 
   const fireChange = useCallback(
     (newValue: DateRange | null) => {
@@ -577,14 +586,6 @@ export function DateRangeInput({
     [fireChange, popover],
   );
 
-  const handlePresetClick = useCallback(
-    (preset: DateRangePreset) => {
-      fireChange(preset.getRange());
-      popover.hide();
-    },
-    [fireChange, popover],
-  );
-
   const handleClear = useCallback(
     (e: React.MouseEvent) => {
       e.stopPropagation();
@@ -713,15 +714,17 @@ export function DateRangeInput({
             <div
               role="group"
               aria-label={t('@astryx.dateRangeInput.presetDateRanges')}
-              {...stylex.props(styles.presetSidebar)}>
+              {...mergeProps(
+                themeProps('date-range-input-presets'),
+                stylex.props(styles.presetSidebar),
+              )}>
               {presets.map(preset => {
                 const presetRange = preset.getRange();
                 const isActive = isRangeEqual(value, presetRange);
-                const isPresetDisabled = !isRangeWithinSpan(
-                  presetRange,
-                  maxRangeSpan,
-                  minRangeSpan,
-                );
+                const isPresetDisabled =
+                  !isRangeWithinSpan(presetRange, maxRangeSpan, minRangeSpan) ||
+                  isDateDisabled(plainDateFromISO(presetRange.start)) ||
+                  isDateDisabled(plainDateFromISO(presetRange.end));
                 return (
                   <button
                     key={preset.label}
@@ -733,12 +736,18 @@ export function DateRangeInput({
                     // concept that contradicted the Tab interaction) (forms-5).
                     aria-current={isActive ? 'true' : undefined}
                     disabled={isPresetDisabled}
-                    onClick={() => handlePresetClick(preset)}
-                    {...stylex.props(
-                      focusOutlineStyles.focusVisible,
-                      styles.presetButton,
-                      isActive && styles.presetButtonActive,
-                      isPresetDisabled && styles.presetButtonDisabled,
+                    onClick={() => handleRangeSelect(presetRange)}
+                    {...mergeProps(
+                      themeProps('date-range-input-preset', {
+                        selected: isActive ? 'selected' : null,
+                        disabled: isPresetDisabled ? 'disabled' : null,
+                      }),
+                      stylex.props(
+                        focusOutlineStyles.focusVisible,
+                        styles.presetButton,
+                        isActive && styles.presetButtonActive,
+                        isPresetDisabled && styles.presetButtonDisabled,
+                      ),
                     )}>
                     {preset.label}
                   </button>

package/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},

package/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:

package/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',

package/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(

package/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),
+          )}>
           <Heading
             ref={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);
                 }}