@astryxdesign/core 0.4.7 → 0.5.0-canary.009bcb3

package/src/Dialog/Dialog.tsx

@@ -8,6 +8,13 @@
  * @output Exports Dialog component, DialogProps, DialogVariant, DialogPurpose types
  * @position Core implementation; consumed by index.ts, tested by Dialog.test.tsx
  *
+ * The standard variant treats `width` as the preferred surface width, then
+ * clamps it to the dynamic viewport with spacing-token gutters so narrow
+ * viewports keep content and controls on screen without changing the public API.
+ * Fullscreen dialogs add safe-area protection to the default padding fallback
+ * while preserving explicit prop/theme padding overrides, and fade in without
+ * the centered-dialog translate/scale motion.
+ *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Dialog/Dialog.doc.mjs (props table, features, implementation notes)
  * - /packages/core/src/Dialog/Dialog.test.tsx (tests for new/changed behavior)
@@ -27,14 +34,15 @@ import {
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {useScrollLock} from '../hooks/useScrollLock';
-import {hasActiveFocusTrapEscape} from '../hooks/useFocusTrap';
-import {isImeKeyEvent} from '../utils/ime';
+import {LayerDepthProvider} from '../Layer/LayerDepthContext';
+import {useLayerDismissal} from '../Layer/useLayerDismissal';
 import {
   colorVars,
   radiusVars,
   durationVars,
   easeVars,
   shadowVars,
+  spacingVars,
 } from '../theme/tokens.stylex';
 import {container} from '../Layout/container.stylex';
 import type {SpacingToken} from '../Layout/container.stylex';
@@ -47,13 +55,14 @@ import {
   overlayPaddingReset,
 } from '../Layout/padding.stylex';
 import type {SpacingStep} from '../utils/types';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {devWarn} from '../utils/devWarning';
 import {DialogContext} from './DialogContext';
 import {themeProps} from '../utils/themeProps';
 import type {DialogVariantMap} from './index';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 /**
  * Calculate a directional translate offset for dialog entry animation.
  * Returns a normalized vector from the trigger element toward the viewport
@@ -118,6 +127,32 @@ const enterDirectional = stylex.keyframes({
   to: {opacity: 1, transform: 'translate(0, 0) scale(1)'},
 });
 
+const enterFullscreen = stylex.keyframes({
+  from: {opacity: 0},
+  to: {opacity: 1},
+});
+
+const dialogFullscreenSafeAreaBlockStartPadding = `var(--astryx-dialog-padding-block-start, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-top, 0px))))`;
+const dialogFullscreenSafeAreaBlockEndPadding = `var(--astryx-dialog-padding-block-end, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-bottom, 0px))))`;
+const dialogFullscreenSafeAreaInlineStartPaddingLtr = `var(--astryx-dialog-padding-inline-start, var(--astryx-dialog-padding-inline, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-left, 0px)))))`;
+const dialogFullscreenSafeAreaInlineStartPaddingRtl = `var(--astryx-dialog-padding-inline-start, var(--astryx-dialog-padding-inline, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-right, 0px)))))`;
+const dialogFullscreenSafeAreaInlineEndPaddingLtr = `var(--astryx-dialog-padding-inline-end, var(--astryx-dialog-padding-inline, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-right, 0px)))))`;
+const dialogFullscreenSafeAreaInlineEndPaddingRtl = `var(--astryx-dialog-padding-inline-end, var(--astryx-dialog-padding-inline, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-left, 0px)))))`;
+
+/** @internal Verified by Dialog.test.tsx; not re-exported from the package entry point. */
+export const dialogFullscreenSafeAreaPaddingContract = {
+  blockStart: dialogFullscreenSafeAreaBlockStartPadding,
+  blockEnd: dialogFullscreenSafeAreaBlockEndPadding,
+  inlineStart: {
+    ltr: dialogFullscreenSafeAreaInlineStartPaddingLtr,
+    rtl: dialogFullscreenSafeAreaInlineStartPaddingRtl,
+  },
+  inlineEnd: {
+    ltr: dialogFullscreenSafeAreaInlineEndPaddingLtr,
+    rtl: dialogFullscreenSafeAreaInlineEndPaddingRtl,
+  },
+} as const;
+
 /**
  * Dialog styles using native <dialog> element
  * Uses ::backdrop pseudo-element for overlay
@@ -171,6 +206,24 @@ const styles = stylex.create({
     margin: 0,
     inset: 0,
   },
+  fullscreenOpen: {
+    animationName: {
+      default: enterFullscreen,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
+  },
+  fullscreenSafeArea: {
+    paddingBlockStart: dialogFullscreenSafeAreaBlockStartPadding,
+    paddingBlockEnd: dialogFullscreenSafeAreaBlockEndPadding,
+    paddingInlineStart: {
+      default: dialogFullscreenSafeAreaInlineStartPaddingLtr,
+      ':is([dir="rtl"] *)': dialogFullscreenSafeAreaInlineStartPaddingRtl,
+    },
+    paddingInlineEnd: {
+      default: dialogFullscreenSafeAreaInlineEndPaddingLtr,
+      ':is([dir="rtl"] *)': dialogFullscreenSafeAreaInlineEndPaddingRtl,
+    },
+  },
   inner: {
     display: 'flex',
     flexDirection: 'column',
@@ -194,12 +247,30 @@ const styles = stylex.create({
   },
 });
 
-// Dynamic styles for width, maxHeight, and position
+const STANDARD_DIALOG_VIEWPORT_GUTTER = spacingVars['--spacing-4'];
+const STANDARD_DIALOG_VIEWPORT_MAX_WIDTH = `calc(100dvw - ${STANDARD_DIALOG_VIEWPORT_GUTTER} - ${STANDARD_DIALOG_VIEWPORT_GUTTER})`;
+const STANDARD_DIALOG_MAX_WIDTH = `min(100%, ${STANDARD_DIALOG_VIEWPORT_MAX_WIDTH})`;
+
+function formatSizeValue(value: number | string): string {
+  return typeof value === 'number' ? `${value}px` : value;
+}
+
+function resolveDialogSizing(
+  width: number | string,
+  maxHeight: number | string,
+) {
+  return {
+    width: formatSizeValue(width),
+    maxWidth: STANDARD_DIALOG_MAX_WIDTH,
+    maxHeight: formatSizeValue(maxHeight),
+  };
+}
+
 const dynamicStyles = stylex.create({
-  sizing: (width: number | string, maxHeight: number | string) => ({
-    width: typeof width === 'number' ? `${width}px` : width,
-    maxWidth: '90vw',
-    maxHeight: typeof maxHeight === 'number' ? `${maxHeight}px` : maxHeight,
+  sizing: (width: string, maxWidth: string, maxHeight: string) => ({
+    width,
+    maxWidth,
+    maxHeight,
   }),
   position: (
     top: string,
@@ -288,7 +359,7 @@ export interface DialogProps extends BaseProps<HTMLDialogElement> {
    * The actual height will be the height of its content.
    * Numbers are treated as pixels, strings are used as-is.
    * Ignored when variant is 'fullscreen'.
-   * @default '75vh'
+   * @default '75dvh'
    */
   maxHeight?: number | string;
 
@@ -356,7 +427,7 @@ export function Dialog({
   isInline = false,
   onOpenChange,
   width = 400,
-  maxHeight = '75vh',
+  maxHeight = '75dvh',
   position,
   variant = 'standard',
   purpose = 'info',
@@ -374,6 +445,9 @@ export function Dialog({
   const paddingToken = spacingStepToToken[effectivePadding] as SpacingToken;
 
   const isFullscreen = variant === 'fullscreen';
+  const standardSizing = isFullscreen
+    ? null
+    : resolveDialogSizing(width, maxHeight);
 
   // Default accessible name: publish a title id through DialogContext so a
   // DialogHeader applies it to its heading (mirrors AlertDialog's explicit
@@ -415,6 +489,8 @@ export function Dialog({
     [titleId, hasConsumerName],
   );
 
+  const mergedDialogRef = useMergedRefs(ref, attachDialog);
+
   // Capture the element that was focused when the dialog opened,
   // for directional animation origin and focus restoration on close.
   const triggerElementRef = useRef<HTMLElement | null>(null);
@@ -474,34 +550,24 @@ export function Dialog({
   // Skip for inline rendering — no modal overlay to compensate for.
   useScrollLock(isOpen && !isInline);
 
-  // Handle Escape key — skip for inline rendering
-  useEffect(() => {
-    if (isInline) {
-      return;
-    }
-    const dialog = dialogRef.current;
-    if (!dialog || !isOpen) {
-      return;
-    }
-
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') {
-        // Ignore IME composition-cancel, and defer to any popover/menu layered
-        // on top of this dialog so a single Escape closes only the top-most
-        // layer (the popover's own focus trap handles it and stops propagation).
-        if (isImeKeyEvent(event) || hasActiveFocusTrapEscape()) {
-          return;
-        }
-        event.preventDefault();
-        if (allowEscape) {
-          onOpenChange(false);
-        }
-      }
-    };
-
-    dialog.addEventListener('keydown', handleKeyDown);
-    return () => dialog.removeEventListener('keydown', handleKeyDown);
-  }, [isOpen, isInline, allowEscape, onOpenChange]);
+  // Join the shared layer dismissal stack. The stack owns the Escape listener
+  // and routes each press to the top-most layer, so this dialog does not listen
+  // itself — that is what stops a modal opened from inside another modal (or a
+  // popover opened inside this one) from closing two layers on one press.
+  //
+  // A `required` dialog registers as `block`: it must not be dismissed, and the
+  // press must not fall through and dismiss a layer behind it either.
+  //
+  // Inline mode opts out — it renders dialog content in normal flow, with
+  // nothing layered over anything.
+  const {shouldDismissOnCloseRequest} = useLayerDismissal({
+    isActive: isOpen,
+    isEnabled: !isInline,
+    escapeBehavior: allowEscape ? 'close' : 'block',
+    onDismiss: () => {
+      onOpenChange(false);
+    },
+  });
 
   // Dev-time guardrail: an open modal should always have an accessible name.
   // The header-title check reads the DOM, so this stays in an effect; the ref
@@ -537,12 +603,18 @@ export function Dialog({
     }
   };
 
-  // Handle native cancel event (browser Escape handling)
+  // The native `cancel` event is the browser's own close-watcher firing: an
+  // Android back gesture, or a close request the stack never saw a press for.
+  // Escape presses the stack owns never arrive here — it preventDefault()s
+  // those, which suppresses the close watcher.
+  //
+  // Always preventDefault so the browser cannot close a controlled <dialog>
+  // behind React's back, then answer the request with the stack's own rules:
+  // only the top-most layer dismisses, a `required` dialog swallows it, and
+  // nothing dismisses while an IME composition is in progress.
   const handleCancel = (event: React.SyntheticEvent<HTMLDialogElement>) => {
     event.preventDefault();
-    // Defer to a popover/menu layered on top of this dialog; it will dismiss
-    // itself on the same Escape press.
-    if (hasActiveFocusTrapEscape()) {
+    if (!shouldDismissOnCloseRequest()) {
       return;
     }
     if (allowEscape) {
@@ -550,7 +622,6 @@ export function Dialog({
     }
   };
 
-  // Shared inner content wrapper
   const innerContent = (
     <div
       {...stylex.props(
@@ -559,22 +630,14 @@ export function Dialog({
           useThemeDefault
             ? {
                 useThemeDefault: 'dialog',
-                maxHeight: isFullscreen
-                  ? undefined
-                  : typeof maxHeight === 'number'
-                    ? `${maxHeight}px`
-                    : maxHeight,
+                maxHeight: standardSizing?.maxHeight,
               }
             : {
                 paddingInnerX: paddingToken,
                 paddingInnerY: paddingToken,
                 paddingOuterX: paddingToken,
                 paddingOuterY: paddingToken,
-                maxHeight: isFullscreen
-                  ? undefined
-                  : typeof maxHeight === 'number'
-                    ? `${maxHeight}px`
-                    : maxHeight,
+                maxHeight: standardSizing?.maxHeight,
               },
         ),
         !useThemeDefault &&
@@ -589,6 +652,7 @@ export function Dialog({
         !useThemeDefault &&
           effectivePadding !== 4 &&
           containerPaddingBlockEndVarStyles[effectivePadding],
+        isFullscreen && useThemeDefault && styles.fullscreenSafeArea,
       )}>
       <DialogContext value={dialogContextValue}>{children}</DialogContext>
     </div>
@@ -612,7 +676,12 @@ export function Dialog({
           stylex.props(
             styles.inlineWrapper,
             overlayPaddingReset.reset,
-            !isFullscreen && dynamicStyles.sizing(width, maxHeight),
+            standardSizing &&
+              dynamicStyles.sizing(
+                standardSizing.width,
+                standardSizing.maxWidth,
+                standardSizing.maxHeight,
+              ),
             isFullscreen && styles.fullscreen,
             xstyle,
           ),
@@ -623,7 +692,7 @@ export function Dialog({
           (props as Record<string, unknown>)['data-testid'] as
             string | undefined
         }>
-        {innerContent}
+        <LayerDepthProvider>{innerContent}</LayerDepthProvider>
       </div>
     );
   }
@@ -632,7 +701,7 @@ export function Dialog({
 
   return (
     <dialog
-      ref={mergeRefs(ref, attachDialog)}
+      ref={mergedDialogRef}
       {...safeProps}
       {...mergeProps(
         themeProps('dialog', {variant}),
@@ -641,7 +710,12 @@ export function Dialog({
           overlayPaddingReset.reset,
           isOpen && styles.open,
           styles.backdrop,
-          !isFullscreen && dynamicStyles.sizing(width, maxHeight),
+          standardSizing &&
+            dynamicStyles.sizing(
+              standardSizing.width,
+              standardSizing.maxWidth,
+              standardSizing.maxHeight,
+            ),
           hasPosition &&
             (() => {
               const o = resolveDialogPositionOffsets(position);
@@ -653,6 +727,7 @@ export function Dialog({
               );
             })(),
           isFullscreen && styles.fullscreen,
+          isFullscreen && isOpen && styles.fullscreenOpen,
           xstyle,
         ),
         className,
@@ -665,7 +740,7 @@ export function Dialog({
       // imperatively in `attachDialog`; a consumer-provided aria-labelledby
       // flows through {...safeProps} above and wins.
       {...(purpose === 'required' ? {role: 'alertdialog'} : undefined)}>
-      {innerContent}
+      <LayerDepthProvider>{innerContent}</LayerDepthProvider>
     </dialog>
   );
 }

package/src/DropdownMenu/DropdownMenu.doc.mjs

@@ -89,6 +89,12 @@ export const docs = {
       type: '() => void',
       description: 'Callback fired when the trigger button is clicked.',
     },
+    {
+      name: 'placement',
+      type: "'above' | 'below' | 'start' | 'end'",
+      description: 'Position placement for the menu popover relative to the trigger button.',
+      default: "'below'",
+    },
     {
       name: 'hasChevron',
       type: 'boolean',

package/src/DropdownMenu/DropdownMenu.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen, fireEvent, waitFor} from '@testing-library/react';
+import {render, screen, fireEvent, waitFor, act} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {useState} from 'react';
 import {DropdownMenu} from './DropdownMenu';
@@ -315,10 +315,7 @@ describe('DropdownMenu', () => {
 });
 
 describe('DropdownMenu light-dismiss race', () => {
-  it('does not re-open the menu when a click follows a hide within the guard window', () => {
-    // Reproduces the iOS Safari race: pointerdown fires light-dismiss before
-    // the subsequent click on the trigger; without the guard, the click would
-    // immediately re-open the menu in the same tap.
+  function openMenu() {
     render(
       <DropdownMenu
         button={{label: 'Actions'}}
@@ -326,13 +323,50 @@ describe('DropdownMenu light-dismiss race', () => {
         data-testid="astryx-dropdown-menu"
       />,
     );
-
     const trigger = screen.getByTestId('astryx-dropdown-menu');
-    fireEvent.click(trigger); // open
-    fireEvent.click(trigger); // close (stamps guard)
-    fireEvent.click(trigger); // would re-open without guard
+    fireEvent.pointerDown(trigger);
+    fireEvent.click(trigger);
     expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1);
-    expect(HTMLElement.prototype.hidePopover).toHaveBeenCalledTimes(1);
+    return trigger;
+  }
+
+  /**
+   * The browser dismisses the menu on pointerup and queues the `toggle` event;
+   * on the engines that lose the race it reaches React before the trigger's
+   * own click, which then reads a closed menu.
+   */
+  function lightDismiss() {
+    const popover = document.querySelector('[popover]') as HTMLElement;
+    act(() => {
+      popover.dispatchEvent(
+        Object.assign(new Event('toggle'), {
+          oldState: 'open',
+          newState: 'closed',
+        }),
+      );
+    });
+  }
+
+  it('does not re-open when the trigger click follows its own light dismiss', () => {
+    const trigger = openMenu();
+
+    fireEvent.pointerDown(trigger);
+    lightDismiss();
+    fireEvent.click(trigger);
+
+    expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1);
+  });
+
+  it('re-opens on a press of its own after a light dismiss', () => {
+    const trigger = openMenu();
+
+    fireEvent.pointerDown(trigger);
+    lightDismiss();
+    fireEvent.click(trigger);
+    fireEvent.pointerDown(trigger);
+    fireEvent.click(trigger);
+
+    expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(2);
   });
 });
 

package/src/DropdownMenu/DropdownMenu.tsx

@@ -37,7 +37,7 @@ import React, {
   type ReactNode,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {usePopover} from '../Popover/usePopover';
+import {usePopoverInternal} from '../Popover/usePopover';
 import {Button, type ButtonProps} from '../Button';
 import {Icon} from '../Icon';
 
@@ -261,14 +261,8 @@ export function DropdownMenu({
   const isControlled = controlledIsOpen !== undefined;
   const isOpen = isControlled ? controlledIsOpen : internalIsOpen;
 
-  // Track when the menu was last hidden so a near-simultaneous trigger
-  // click — e.g. on iOS Safari where pointerdown fires light-dismiss
-  // before the trigger's click event — can't immediately re-open it.
-  const lastHideTimeRef = useRef(0);
-
   // Close menu + return focus to trigger
   const handleLayerHide = useCallback(() => {
-    lastHideTimeRef.current = Date.now();
     onOpenChange?.(false);
     if (!isControlled) {
       setInternalIsOpen(false);
@@ -294,7 +288,7 @@ export function DropdownMenu({
     }
   }, [isControlled, onOpenChange]);
 
-  const popover = usePopover({
+  const popover = usePopoverInternal({
     onHide: handleLayerHide,
     onShow: handleLayerShow,
     hasLightDismiss: true,
@@ -422,11 +416,8 @@ export function DropdownMenu({
 
   const handleButtonClick = useCallback(
     (e: React.MouseEvent<HTMLButtonElement>) => {
-      // If the menu was just closed by light dismiss (e.g. iOS Safari fires
-      // pointerdown → hide before the trigger's click), the click would
-      // otherwise immediately re-open it. Short-circuit within the guard
-      // window.
-      if (Date.now() - lastHideTimeRef.current < 50) {
+      // The click that light-dismissed the menu is not a request to reopen it.
+      if (popover.wasJustDismissed()) {
         return;
       }
       onClick?.();

package/src/DropdownMenu/DropdownMenuSubMenu.test.tsx

@@ -701,11 +701,14 @@ describe('DropdownMenuSubMenu theming slots', () => {
       name: /Move to/,
       hidden: true,
     });
-    // The indicator-icon slot wraps the chevron affordance inside the trigger
-    // row.
-    expect(
-      trigger.querySelector('.astryx-dropdown-menu-indicator-icon'),
-    ).toBeInTheDocument();
+    // The indicator-icon slot sits on the chevron glyph itself (the element
+    // that carries the icon size), so a theme can restyle its size/color
+    // directly.
+    const indicator = trigger.querySelector(
+      '.astryx-dropdown-menu-indicator-icon',
+    );
+    expect(indicator).toBeInTheDocument();
+    expect(indicator).toHaveClass('astryx-icon');
   });
 });
 

package/src/DropdownMenu/DropdownMenuSubMenu.tsx

@@ -476,20 +476,17 @@ export function DropdownMenuSubMenu(
   );
 
   const endAffordance = hasSpinner ? (
-    <span
-      {...mergeProps(
-        themeProps('dropdown-menu-indicator-icon'),
-        stylex.props(triggerStyles.caret),
-      )}>
+    <span {...stylex.props(triggerStyles.caret)}>
       <Spinner size="sm" />
     </span>
   ) : (
-    <span
-      {...mergeProps(
-        themeProps('dropdown-menu-indicator-icon'),
-        stylex.props(triggerStyles.caret),
-      )}>
-      <Icon icon="chevronRight" size="sm" color="secondary" />
+    <span {...stylex.props(triggerStyles.caret)}>
+      <Icon
+        icon="chevronRight"
+        size="sm"
+        color="secondary"
+        {...themeProps('dropdown-menu-indicator-icon')}
+      />
     </span>
   );
 

package/src/Field/Field.doc.mjs

@@ -39,8 +39,8 @@ export const docs = {
     ],
     vars: [
       {name: '--_field-radius', description: 'Border radius of input fields', default: 'var(--radius-element)', private: true},
-      {name: '--_input-clear-hit-inset', description: 'Outset of the clear (\u2715) button\u2019s invisible hit area, applied to a ::after overlay. 0 on a fine pointer; negative on a coarse one, which grows the 20px button to the 24px touch target without changing what is drawn.', default: '0px', private: true},
-      {name: '--_input-clear-hit-content', description: 'Whether the clear (\u2715) button\u2019s invisible hit overlay exists. `none` on a fine pointer, so no ::after is generated and hover still reaches the glyph; `""` on a coarse one, where the overlay provides the 24px touch target.', default: 'none', private: true},
+      {name: '--_input-clear-hit-inset', description: 'Outset of the clear (\u2715) button\'s invisible hit area, applied to a ::after overlay. 0 on a fine pointer; negative on a coarse one, which grows the 20px button to the 24px touch target without changing what is drawn.', default: '0px', private: true},
+      {name: '--_input-clear-hit-content', description: 'Whether the clear (\u2715) button\'s invisible hit overlay exists. `none` on a fine pointer, so no ::after is generated and hover still reaches the glyph; `""` on a coarse one, where the overlay provides the 24px touch target.', default: 'none', private: true},
     ],
     derived: [
       {property: 'borderRadius', vars: ['--_field-radius']},
@@ -60,6 +60,17 @@ export const docs = {
       description: 'ID for the input element (used for the label htmlFor attribute).',
       required: true,
     },
+    {
+      name: 'labelID',
+      type: 'string',
+      description: 'ID applied to the label element itself for group accessibility.',
+    },
+    {
+      name: 'isGroupLabel',
+      type: 'boolean',
+      description: 'Renders the label as a span for control groups (radiogroup, checkbox list).',
+      default: 'false',
+    },
     {
       name: 'children',
       type: 'ReactNode',

package/src/Field/FieldLabel.test.tsx

@@ -15,6 +15,7 @@ import userEvent from '@testing-library/user-event';
 import {TestIcon} from '../__tests__/TestIcon';
 import {InternationalizationProvider} from '../i18n';
 import {FieldLabel} from './FieldLabel';
+import {themeProps} from '../utils/themeProps';
 
 describe('FieldLabel', () => {
   it('renders label text', () => {
@@ -197,4 +198,32 @@ describe('FieldLabel', () => {
       expect(description.closest('label')).toBeNull();
     });
   });
+
+  describe('a control can name its own label target', () => {
+    it('composes a passed target onto the field-label one', () => {
+      // How CheckboxInput and Switch reach their label: the control spreads
+      // its own themeProps in, and both classes end up on the same element,
+      // so a theme can style every label or just this kind.
+      render(
+        <FieldLabel
+          {...themeProps('checkbox-label')}
+          label="Notify me"
+          inputID="notify-input"
+        />,
+      );
+      const label = screen.getByText('Notify me').closest('label');
+      expect(label).toHaveClass('astryx-field-label');
+      expect(label).toHaveClass('astryx-checkbox-label');
+    });
+
+    it('describes no placement of its own', () => {
+      // The label cannot know how its caller arranged it, so it says nothing:
+      // a `data-layout` here would be a claim that is wrong for at least one
+      // caller (Field's horizontal-labels puts a label beside its control),
+      // and a consumer could set it untruthfully.
+      render(<FieldLabel label="Email" inputID="email-input" />);
+      const label = screen.getByText('Email').closest('label');
+      expect(label).not.toHaveAttribute('data-layout');
+    });
+  });
 });

package/src/Field/FieldLabel.tsx

@@ -285,6 +285,13 @@ export function FieldLabel({
         htmlFor={isGroupLabel ? undefined : inputID}
         {...rest}
         {...mergeProps(
+          // A control that knows what kind of label this is passes its own
+          // target down (CheckboxInput's `checkbox-label`, Switch's
+          // `switch-label`); it arrives as `className` and composes onto this
+          // one. The label itself does not describe its own placement — it
+          // cannot know it, and any encoding it guessed would be wrong for a
+          // caller that arranges labels differently (Field's
+          // `horizontal-labels`).
           themeProps('field-label'),
           stylex.props(
             styles.label,

package/src/Field/InputClearButton.test.tsx

@@ -15,7 +15,7 @@ import {readFileSync} from 'node:fs';
 import path from 'node:path';
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
-import {InputClearButton} from './InputClearButton';
+import {InputClearButton, type InputClearButtonProps} from './InputClearButton';
 import {Icon} from '../Icon';
 import {defineTheme} from '../theme/defineTheme';
 import {generateThemeCSS} from '../theme/generateThemeRules';
@@ -67,6 +67,20 @@ const getGlyph = (): HTMLElement => {
   return icon as HTMLElement;
 };
 
+describe('InputClearButton public props', () => {
+  it('keep popup invoker handlers internal', () => {
+    const hasPointerDown: 'onPointerDown' extends keyof InputClearButtonProps
+      ? true
+      : false = false;
+    const hasClickCapture: 'onClickCapture' extends keyof InputClearButtonProps
+      ? true
+      : false = false;
+
+    expect(hasPointerDown).toBe(false);
+    expect(hasClickCapture).toBe(false);
+  });
+});
+
 describe('InputClearButton', () => {
   it('renders a real button with the given accessible label', () => {
     render(<InputClearButton label="Clear" onClick={() => {}} />);