@astryxdesign/core 0.6.2 → 0.6.3-canary.0788c49

package/src/Dialog/modules/DialogHeader.spec.md

@@ -7,17 +7,19 @@ authority: current
 archive_reason: null
 superseded_by: null
 approved_by: cixzhang
-approved_at: 2026-09-14
+approved_at: 2026-09-23
 owners: [cixzhang, imdreamrunner]
-review_triggers: [theming, layout]
+review_triggers: [theming, layout, public-api]
 verified_by:
   [
     packages/core/src/Dialog/DialogHeader.test.tsx,
     packages/core/src/theme/themingTargets.test.ts,
+    packages/cli/foundation/discovery/theming-targets.test.mjs,
     scripts/check-knowledge.mjs,
   ]
 parent_component: component:Dialog
-references: [architecture:component-theming-surface]
+references:
+  [architecture:component-theming-surface, architecture:container-padding]
 ---
 
 # DialogHeader module contract
@@ -25,14 +27,15 @@ references: [architecture:component-theming-surface]
 ## 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.
+control. This record owns the stable header-row, start-content, title-block,
+end-content, and close-icon anatomy, their public theming targets, and the fixed
+compensation applied to the existing end-content slot.
 
 ## Compatibility and migration
 
 - Released default preserved: `yes`
-- Compatibility class: additive theme targets only; default layout, paint,
-  interaction, accessibility, and public props remain unchanged
+- Compatibility class: two additive theme targets and one additive prop; omitted
+  layout, paint, interaction, accessibility, and theming remain unchanged
 - Migration decision: none
 
 Consumer migration instructions belong in consumer docs and release notes.
@@ -41,10 +44,16 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 **Owns**
 
-- The header row that arranges title content and trailing controls.
+- The header row that arranges title content and controls.
+- The start-content wrapper for optional leading content.
 - The title block that groups the title and optional subtitle.
+- The existing end-content wrapper that groups optional trailing content with
+  the close action.
+- The fixed end-slot compensation derived from the medium close action's
+  transparent inset.
 - The close icon rendered for the optional close action.
-- The `dialog-header`, `dialog-header-title-block`, and
+- The `dialog-header`, `dialog-header-start-content`,
+  `dialog-header-title-block`, `dialog-header-end-content`, and
   `dialog-header-close-icon` targets.
 
 **Does not own / non-goals**
@@ -53,50 +62,70 @@ Consumer migration instructions belong in consumer docs and release notes.
   `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.
+- List-style inherited container-padding compensation, caller-supplied margin
+  values, or a general alignment primitive.
 
 ## Public API and concepts
 
-No component prop changes. This contract adds three public theming surfaces for
-existing anatomy.
+This contract preserves the three existing theming surfaces, adds two content-
+slot targets, and adds one slot-targeted compensation override.
 
-| 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 |
+| 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    |
+| Start-content target         | present when start content renders               | Styles the wrapper for optional leading content                                       | Existing start-content layout                         | `module:Dialog/DialogHeader` | stable    |
+| Title block target           | present                                          | Styles the title/subtitle grouping element                                            | Existing title stack visuals                          | `module:Dialog/DialogHeader` | stable    |
+| End-content target           | present when end content or close action renders | Styles the wrapper that groups trailing content with the close action                 | Existing end-content layout                           | `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    |
+| `endContentEdgeCompensation` | `inline`, `block`, `all`                         | Selects which axes of the existing end-content wrapper receive its fixed compensation | omitted; preserve automatic close-action compensation | `module:Dialog/DialogHeader` | stable    |
+
+For this slot-targeted prop, `inline` means the slot's logical inline-end edge,
+`block` means both block edges, and `all` combines them.
 
 ## 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 |
+| 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      |
+| FR5  | The existing end wrapper MUST continue to group optional `endContent` with the optional close action; this change MUST NOT add another wrapper.                                                                                                             | Current implementation                           | settled      |
+| FR6  | When `endContentEdgeCompensation` is omitted, rendering the close action MUST preserve the released fixed negative block and logical inline-end inset, whether or not `endContent` is present. Without the close action, no automatic compensation applies. | Released behavior and owner decision             | settled      |
+| FR7  | Explicit `inline` MUST apply only logical inline-end compensation; `block` MUST apply only both block edges; `all` MUST apply both. The explicit value overrides the automatic close-action selection.                                                      | `module:Dialog/DialogHeader/DEC-2`               | settled      |
+| FR8  | Compensation MUST use logical inline properties, preserve title, slot, and close-action semantics and hit targets, and expose no caller-controlled margin amount.                                                                                           | `architecture:container-padding`; owner decision | settled      |
+| FR9  | The leading content wrapper MUST carry `dialog-header-start-content` whenever optional start content renders.                                                                                                                                               | `module:Dialog/DialogHeader/DEC-3`               | settled      |
+| FR10 | The existing trailing content wrapper MUST carry `dialog-header-end-content` whenever optional end content or the close action renders.                                                                                                                     | `module:Dialog/DialogHeader/DEC-3`               | settled      |
 
 ### Transformation and precedence order
 
-- The module applies each target to its owning element before normal theme CSS
-  resolves through the shared theming pipeline.
+1. If `endContentEdgeCompensation` is present, its closed value selects the
+   compensated axes.
+2. Otherwise, a rendered close action selects `all`; omission of the close
+   action selects no compensation.
+3. The module applies each theme 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.
+- The additive closed-value branch and class selection 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.
+- Compensation and theme targets MUST NOT change the title's role, focus
+  behavior, dialog naming, the close button's accessible name and operation, or
+  any slot child's hit target.
 
 ## 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 |
+| Anatomy or state | Design requirement                                                                                                                       | Representation authority        | Module contract |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | --------------- |
+| Header row       | Owns arrangement and spacing among title content and controls.                                                                           | This module                     | FR1             |
+| Start content    | Owns the leading wrapper for optional start content.                                                                                     | This module                     | FR9             |
+| Title block      | Owns title/subtitle grouping and spacing.                                                                                                | This module                     | FR2             |
+| End content      | Owns the existing trailing wrapper containing optional end content and the close action, including its fixed slot-targeted compensation. | This module                     | FR4–FR8, FR10   |
+| Close icon       | Owns the close glyph's visual box inside the Button-owned action.                                                                        | This module with Icon rendering | FR3, FR4        |
 
 ### Theming anatomy
 
@@ -105,7 +134,9 @@ existing anatomy.
 ```json
 {
   "Header row": {"target": "dialog-header"},
+  "Start content": {"target": "dialog-header-start-content"},
   "Title block": {"target": "dialog-header-title-block"},
+  "End content": {"target": "dialog-header-end-content"},
   "Close icon": {"target": "dialog-header-close-icon"}
 }
 ```
@@ -113,22 +144,27 @@ existing anatomy.
 ## Parent and system relationships
 
 - `component:Dialog` owns modal behavior and the aggregate Dialog contract.
-- `component:Layout` owns the composed LayoutHeader region outside the three
+- `component:Layout` owns the composed LayoutHeader region outside the five
   module-owned inner parts.
-- `component:Button` owns the close action's control behavior and outer button
-  presentation.
+- `component:Button` owns the close action's control behavior, hit target, and
+  outer 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.
+- `architecture:container-padding` defines the retained-inset edge-compensation
+  intent and distinguishes this slot-targeted projection from List-style
+  inherited-inset self-compensation and full bleed.
 
 ## 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. |
+| Contract            | Verification                                                                    | Representative states                                                     | Mutation or failure expectation                                                              |
+| ------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| FR1–FR3, FR9–FR10   | Target tests, target inventory, generated probe theme, and source inspection    | title only, title/subtitle, start content, end content, close action      | A target is missing, undocumented, duplicated, or moved away from its owning painter.        |
+| FR4–FR5             | Existing content and close-button tests                                         | end content only; close only; both                                        | The close action or slot content disappears, reorders, or gains another wrapper.             |
+| FR6–FR7             | Focused end-slot class-selection assertions                                     | close only; end content only; both; explicit `inline`, `block`, and `all` | An omitted prop changes released geometry, or an explicit value selects the wrong axes.      |
+| FR8                 | Source inspection, RTL CI, interaction tests, and focused real-browser geometry | LTR and RTL; custom end control; close action                             | Physical margins, caller-controlled amounts, or hit-target changes enter the implementation. |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                   | all five module anatomy entries and targets                               | Anatomy, docs, runtime targets, and the module map drift.                                    |
 
 ## Decision log
 
@@ -141,6 +177,29 @@ 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.
 
+### DEC-2 — End-content compensation is slot-targeted and explicit
+
+**Reference:** `module:Dialog/DialogHeader/DEC-2`
+**Decider:** cixzhang, 2026-09-22
+
+DialogHeader preserves its released automatic compensation whenever the close
+action renders. `endContentEdgeCompensation` targets the existing end-content
+slot and selects `inline`, `block`, or `all` without exposing a margin amount.
+This is a slot-targeted projection of the retained-inset edge-compensation
+intent; it does not make DialogHeader a List-style inherited-padding consumer.
+
+### DEC-3 — Content-slot wrappers are approved target destinations
+
+**Reference:** `module:Dialog/DialogHeader/DEC-3`
+**Decider:** cixzhang, 2026-09-23
+
+The existing wrappers for `startContent` and `endContent` are approved as stable
+visible anatomy. Their target destinations are
+`dialog-header-start-content` and `dialog-header-end-content`; implementation
+must add no wrapper and must preserve default layout, paint, interaction,
+accessibility, and public props. The end-content name follows the public prop
+even though that slot also contains the optional close action.
+
 ## Open questions
 
 None.

package/src/DropdownMenu/DropdownMenu.test.tsx

@@ -3,7 +3,7 @@
 /**
  * @file DropdownMenu.test.tsx
  * @input Uses vitest, @testing-library/react, DropdownMenu component
- * @output Unit tests for DropdownMenu component behavior
+ * @output Unit tests for DropdownMenu behavior and derived bottom-sheet item padding
  * @position Testing; validates DropdownMenu.tsx implementation
  *
  * SYNC: When DropdownMenu.tsx changes, update tests to match new behavior
@@ -165,7 +165,10 @@ describe('DropdownMenu', () => {
     });
     expect(
       screen.getByRole('button', {name: 'Edit project'}).closest('li'),
-    ).toHaveStyle({paddingInline: 'var(--spacing-3)'});
+    ).toHaveStyle({
+      paddingInline: 'var(--_item-inset-inline)',
+      '--_item-inset-inline': 'var(--spacing-3)',
+    });
   });
 
   it('drills into nested data items in bottom-sheet presentation', async () => {

package/src/Field/InputClearButton.test.tsx

@@ -8,8 +8,8 @@
  * @output Unit tests for the shared clear-button primitive
  * @position Testing; validates InputClearButton.tsx — the single home for the
  *   clearable input family's clear (✕) affordance and its theme target. Covers
- *   the accessible name, the click callback, the decorative registry glyph,
- *   both theme targets, the touch hit area, and xstyle forwarding.
+ *   the accessible name, contextual hover tooltip, click callback, decorative
+ *   registry glyph, both theme targets, touch hit area, and xstyle forwarding.
  *
  * SYNC: When InputClearButton.tsx changes, update tests to match new behavior.
  */
@@ -17,7 +17,7 @@
 import {readFileSync} from 'node:fs';
 import path from 'node:path';
 import {describe, it, expect, vi, afterEach} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import * as stylex from '@stylexjs/stylex';
 import {
   InputClearButton,
@@ -95,6 +95,20 @@ describe('InputClearButton public props', () => {
 });
 
 describe('InputClearButton', () => {
+  it('uses the contextual label for the tooltip and accessible name', async () => {
+    const showPopover = vi.spyOn(HTMLElement.prototype, 'showPopover');
+    render(<InputClearButton label="Clear Search" onClick={() => {}} />);
+
+    const button = screen.getByRole('button', {name: 'Clear Search'});
+    const tooltip = screen.getByRole('tooltip', {hidden: true});
+    expect(tooltip).toHaveTextContent(/^Clear Search$/);
+    expect(button.getAttribute('aria-describedby')).toBe(tooltip.id);
+
+    fireEvent.mouseEnter(button);
+    await waitFor(() => expect(showPopover).toHaveBeenCalled());
+    showPopover.mockRestore();
+  });
+
   it('renders a real button with the given accessible label', () => {
     render(<InputClearButton label="Clear" onClick={() => {}} />);
     const button = screen.getByRole('button', {name: 'Clear'});

package/src/Field/InputClearButton.tsx

@@ -4,8 +4,9 @@
 
 /**
  * @file InputClearButton.tsx
- * @input Uses React, Button, Icon
- * @output Exports the public InputClearButton and an internal popup-aware variant.
+ * @input Uses React, Button, and Icon
+ * @output Exports the public InputClearButton and an internal popup-aware variant,
+ *   both with a contextual tooltip matching their required label.
  * @position Shared primitive. Every input that renders a clear affordance —
  *   TextInput, NumberInput, TimeInput, DateInput, DateTimeInput,
  *   DateRangeInput, Selector, MultiSelector, Typeahead, Tokenizer, FileInput —
@@ -66,6 +67,7 @@ const styles = stylex.create({
 });
 
 export interface InputClearButtonProps {
+  /** Contextual accessible name for the button, such as "Clear Search". */
   label: string;
   onClick: (e: React.MouseEvent<HTMLButtonElement>) => void;
   xstyle?: stylex.StyleXStyles;
@@ -104,6 +106,7 @@ function renderInputClearButton({
       variant="ghost"
       size="sm"
       label={label}
+      tooltip={label}
       className={buttonTargetClassName}
       icon={
         <Icon

package/src/Field/PanelSearchInput.tsx

@@ -119,10 +119,13 @@ const styles = stylex.create({
     color: colorVars['--color-text-primary'],
     fontFamily: typographyVars['--font-family-body'],
     // Matches the option rows below it, so the query reads as the first line of
-    // the list. The coarse-pointer floor keeps iOS from zooming on focus.
+    // the list. The floor keeps iOS from zooming on focus — keyed to iOS
+    // alone, since only iOS WebKit implements -webkit-touch-callout.
     fontSize: {
       default: typeScaleVars['--text-label-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-label-leading'],
     // The field draws the focus ring (see `field`), so the bare input must not

package/src/FieldStatus/__tests__/StatusMessage.a11y.states.ts

@@ -256,7 +256,7 @@ export const CORE_STATUS_MESSAGE_BINDING_STATES = [
       minValue: 0,
       maxValue: 100,
     },
-    focusSelector: '[role="progressbar"] [tabindex="0"]',
+    focusSelector: '[tabindex="0"]',
     storyId: 'a11y-status-message-pattern--progress-mark-focused-update',
   },
 ] as const satisfies ReadonlyArray<CoreStatusMessageBindingDefinition>;

package/src/FileInput/FileInput.tsx

@@ -231,9 +231,14 @@ const styles = stylex.create({
   },
   placeholderText: {
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-secondary'],
@@ -242,9 +247,13 @@ const styles = stylex.create({
   },
   fileNameText: {
     fontFamily: typographyVars['--font-family-body'],
+    // ...and the filename beside it keeps the same floor, so both lines the
+    // control shows stay the same size.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],

package/src/Icon/Icon.doc.mjs

@@ -49,8 +49,9 @@ export const docs = {
     {
       name: 'size',
       type: "'xsm' | 'sm' | 'md' | 'lg'",
-      description: 'Icon size.',
-      default: "'md'",
+      description:
+        'Icon size. An explicit value wins. When omitted, Icon uses the nearest default supplied by an owning Astryx component for its icon slot, then falls back to md when no contextual default exists.',
+      default: "Contextual; otherwise 'md'",
     },
     {
       name: 'label',
@@ -153,8 +154,9 @@ export const docsZh = {
     {
       name: 'size',
       type: "'xsm' | 'sm' | 'md' | 'lg'",
-      description: '图标尺寸。',
-      default: "'md'",
+      description:
+        '图标尺寸。显式值优先。省略时，Icon 使用最近的 Astryx 所属组件为其图标槽提供的默认尺寸；如果没有上下文默认值，则回退为 md。',
+      default: "上下文默认值；否则为 'md'",
     },
     {
       name: 'label',
@@ -294,7 +296,7 @@ export const docsDense = {
   propDescriptions: {
     icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For others, pass an SVG component.',
     color: 'Color variant mapped to Astryx icon color tokens.',
-    size: 'Icon size.',
+    size: "explicit Icon size; otherwise nearest owning-component default, then 'md' when no contextual default exists",
     label:
       'Accessible name for a meaningful, standalone icon. Sets role="img" + aria-label and drops the default aria-hidden. Omit (default) for decorative icons (stays aria-hidden). Empty string = decorative. The accessible-name/alt-text prop for icons.',
     xstyle: