@astryxdesign/core 0.2.0-canary.8d64648 → 0.2.0-canary.8dfd7cf

package/src/DropdownMenu/DropdownMenuCheckboxItem.tsx

@@ -4,39 +4,39 @@
 
 /**
  * @file DropdownMenuCheckboxItem.tsx
- * @input React, stylex, Item + Icon + DropdownMenu context + tokens from core
+ * @input React, stylex, Item + CheckboxInput + DropdownMenu context + tokens from core
  * @output DropdownMenuCheckboxItem — a standalone checkable menu item.
  * @position Sub-component; used inside DropdownMenu.
  *
  * A menu item that toggles an independent boolean (role="menuitemcheckbox").
- * Unlike CheckboxInput, there is no nested native <input>: the row itself owns
- * the role and aria-checked, per the WAI-ARIA menuitemcheckbox pattern.
- * Keyboard navigation (arrows/typeahead) and Enter/Space activation come from
- * the parent DropdownMenu's useListFocus + activation path, which matches
- * menuitemcheckbox alongside plain menuitem rows.
+ * Unlike CheckboxInput, there is no nested native <input> that participates in
+ * accessibility: the row itself owns the role and aria-checked, per the
+ * WAI-ARIA menuitemcheckbox pattern. Keyboard navigation (arrows/typeahead) and
+ * Enter/Space activation come from the parent DropdownMenu's useListFocus +
+ * activation path, which matches menuitemcheckbox alongside plain menuitem rows.
  *
- * The square checkbox visual is decorative (aria-hidden) — the row owns the
- * checked state. Its size is derived from the menu's item size (a `sm` menu
- * gets the compact control; `md`/`lg` get the standard one) and it swaps to the
- * inline-end of the row on coarse-pointer (touch) devices via CSS `order`, so
- * it lands where selection toggles are conventionally placed on mobile. The
- * checkmark uses the `check` icon from the active theme's icon registry.
+ * The checkbox visual composes the real CheckboxInput primitive so its checkmark
+ * matches CheckboxListItem and picks up the standard `checkbox` theming slots.
+ * It is purely decorative: the composed control is wrapped in an element that is
+ * both `aria-hidden` and `inert`, so it contributes nothing to the row's
+ * accessible name, and its native <input> and sr-only label stay out of the tab
+ * order and the accessibility tree while pointer clicks fall through to the row
+ * — the same shim MultiSelector uses. The row owns the checked state and
+ * accessible name. The control size is derived from the menu's item size (a
+ * `sm` menu gets the compact control; `md`/`lg` get the standard one) and it
+ * swaps to the inline-end of the row on coarse-pointer (touch) devices via CSS
+ * `order`, so it lands where selection toggles are conventionally placed on
+ * mobile.
  */
 
 import {useCallback, type PointerEvent, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {Icon, renderIconSlot, type IconType} from '../Icon';
+import {renderIconSlot, type IconType} from '../Icon';
+import {CheckboxInput} from '../CheckboxInput/CheckboxInput';
 import {Item} from '../Item';
 import {useDropdownMenuContext} from './DropdownMenuContext';
 import {focusMenuItemOnHover} from './menuItemHover';
-import {
-  colorVars,
-  spacingVars,
-  radiusVars,
-  durationVars,
-  easeVars,
-  borderVars,
-} from '../theme/tokens.stylex';
+import {colorVars, spacingVars} from '../theme/tokens.stylex';
 import {mergeProps, themeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 
@@ -58,22 +58,13 @@ const styles = stylex.create({
   },
   // Rendered in Item's `marker` slot as a raw flex child, so `order` moves it
   // relative to the label within the row. On touch it moves to the inline-end.
-  box: {
+  // `aria-hidden` + `inert` + pointer-events:none keep the composed CheckboxInput
+  // decorative: it adds no accessible name, and clicks fall through to the row,
+  // which owns the role and activation.
+  markerBox: {
     display: 'flex',
-    alignItems: 'center',
-    justifyContent: 'center',
     flexShrink: 0,
-    boxSizing: 'border-box',
-    borderWidth: borderVars['--border-width'],
-    borderStyle: 'solid',
-    borderRadius: radiusVars['--radius-inner'],
-    color: colorVars['--color-on-accent'],
-    transitionProperty: 'background-color, border-color',
-    transitionDuration: {
-      default: durationVars['--duration-fast'],
-      '@media (prefers-reduced-motion: reduce)': '0s',
-    },
-    transitionTimingFunction: easeVars['--ease-standard'],
+    pointerEvents: 'none',
     order: {
       default: 0,
       '@media (pointer: coarse)': 1,
@@ -83,19 +74,6 @@ const styles = stylex.create({
       '@media (pointer: coarse)': 'auto',
     },
   },
-  unchecked: {
-    borderColor: colorVars['--color-border-emphasized'],
-    backgroundColor: colorVars['--color-background-surface'],
-  },
-  checked: {
-    borderColor: colorVars['--color-accent'],
-    backgroundColor: colorVars['--color-accent'],
-  },
-});
-
-const boxSizeStyles = stylex.create({
-  sm: {width: 18, height: 18},
-  md: {width: 22, height: 22},
 });
 
 export interface DropdownMenuCheckboxItemProps extends Omit<
@@ -180,6 +158,12 @@ export function DropdownMenuCheckboxItem({
   const menuSize = ctx?.menuSize ?? 'md';
   const controlSize = menuSize === 'sm' ? 'sm' : 'md';
 
+  // The composed checkbox is decorative and inert, so its label never reaches
+  // the accessibility tree — the row's `label` prop provides the announced
+  // name. CheckboxInput still requires a string label, so pass one through when
+  // the row label is a plain string.
+  const checkboxLabel = typeof label === 'string' ? label : '';
+
   const handleClick = useCallback(() => {
     if (isDisabled) {
       return;
@@ -203,22 +187,15 @@ export function DropdownMenuCheckboxItem({
       tabIndex={isDisabled ? undefined : -1}
       onPointerMove={handlePointerMove}
       marker={
-        <span
-          aria-hidden="true"
-          {...mergeProps(
-            themeProps('dropdown-menu-checkbox', {
-              size: controlSize,
-              checked: value ? 'checked' : null,
-              disabled: isDisabled ? 'disabled' : null,
-            }),
-            stylex.props(
-              styles.box,
-              boxSizeStyles[controlSize],
-              value ? styles.checked : styles.unchecked,
-            ),
-          )}>
-          {value && <Icon icon="check" size="sm" color="inherit" />}
-        </span>
+        <div aria-hidden="true" inert {...stylex.props(styles.markerBox)}>
+          <CheckboxInput
+            label={checkboxLabel}
+            isLabelHidden
+            value={value}
+            isDisabled={isDisabled}
+            size={controlSize}
+          />
+        </div>
       }
       startContent={
         icon

package/src/DropdownMenu/DropdownMenuItem.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'DropdownMenuItem',

package/src/DropdownMenu/DropdownMenuItem.tsx

@@ -20,7 +20,7 @@
  * - /packages/core/src/DropdownMenu/DropdownMenu.test.tsx
  * - /packages/core/src/DropdownMenu/index.ts
  * - /apps/storybook/stories/DropdownMenu.stories.tsx
- * - /packages/cli/templates/blocks/components/DropdownMenu/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/DropdownMenu/ (showcase blocks)
  */
 
 import {useCallback, type PointerEvent, type ReactNode} from 'react';

package/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'DropdownMenuRadioGroup',

package/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'DropdownMenuRadioItem',

package/src/DropdownMenu/DropdownMenuRadioItem.tsx

@@ -212,7 +212,16 @@ export function DropdownMenuRadioItem({
             ),
           )}>
           {isChecked && (
-            <span {...stylex.props(styles.dot, dotSizeStyles[controlSize])} />
+            <span
+              {...mergeProps(
+                themeProps('dropdown-menu-radio-dot', {
+                  size: controlSize,
+                  checked: 'checked',
+                  disabled: isDisabled ? 'disabled' : null,
+                }),
+                stylex.props(styles.dot, dotSizeStyles[controlSize]),
+              )}
+            />
           )}
         </span>
       }

package/src/DropdownMenu/DropdownMenuSelectable.test.tsx

@@ -78,6 +78,37 @@ describe('DropdownMenuCheckboxItem', () => {
     expect(onChangeSpy).toHaveBeenCalledWith(true);
   });
 
+  it('keeps the composed checkbox decorative (row is the only announced control)', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'View'}}>
+        <DropdownMenuCheckboxItem label="Show archived" value={true} />
+      </DropdownMenu>,
+    );
+    await user.click(screen.getByRole('button', {name: /View/}));
+
+    // The row owns role="menuitemcheckbox" — it is the single such control.
+    expect(
+      screen.getAllByRole('menuitemcheckbox', {hidden: true}),
+    ).toHaveLength(1);
+
+    // The composed CheckboxInput is present in the DOM but sits inside an
+    // `aria-hidden` + `inert` subtree: it contributes nothing to the row's
+    // accessible name and its native <input> is out of the tab order and the
+    // accessibility tree, so it is not a second announced/focusable control.
+    // (Browsers enforce inert; jsdom does not model its a11y removal, so this
+    // asserts the aria-hidden/inert boundary directly rather than via role.)
+    const row = screen.getByRole('menuitemcheckbox', {
+      name: /Show archived/,
+      hidden: true,
+    });
+    const input = row.querySelector('input[type="checkbox"]');
+    expect(input).not.toBeNull();
+    const marker = input?.closest('[inert]');
+    expect(marker).not.toBeNull();
+    expect(marker).toHaveAttribute('aria-hidden', 'true');
+  });
+
   it('does not toggle when disabled', async () => {
     const user = userEvent.setup();
     const onChangeSpy = vi.fn();
@@ -128,6 +159,39 @@ describe('DropdownMenuRadioGroup / RadioItem', () => {
     ).toBeInTheDocument();
   });
 
+  it('exposes a themeable slot on the checked radio dot', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Sort'}}>
+        <DropdownMenuRadioGroup
+          value="newest"
+          onChange={() => {}}
+          label="Sort by">
+          <DropdownMenuRadioItem value="newest" label="Newest" />
+          <DropdownMenuRadioItem value="oldest" label="Oldest" />
+        </DropdownMenuRadioGroup>
+      </DropdownMenu>,
+    );
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+    const checked = screen.getByRole('menuitemradio', {
+      name: 'Newest',
+      hidden: true,
+    });
+    const dot = checked.querySelector('.astryx-dropdown-menu-radio-dot');
+    expect(dot).toBeInTheDocument();
+    // Mirrors the radio container's visual props/states for consistent theming.
+    expect(dot).toHaveAttribute('data-size', 'md');
+    expect(dot).toHaveAttribute('data-checked', 'checked');
+    // The unchecked radio has no dot, so no dot slot either.
+    const unchecked = screen.getByRole('menuitemradio', {
+      name: 'Oldest',
+      hidden: true,
+    });
+    expect(
+      unchecked.querySelector('.astryx-dropdown-menu-radio-dot'),
+    ).not.toBeInTheDocument();
+  });
+
   it('calls onChange with the selected value', async () => {
     const user = userEvent.setup();
     const onChange = vi.fn();

package/src/DropdownMenu/DropdownMenuSubMenu.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'DropdownMenuSubMenu',

package/src/DropdownMenu/DropdownMenuSubMenu.test.tsx

@@ -661,3 +661,20 @@ describe('DropdownMenuSubMenu accessibility (WCAG 2.2 / APG)', () => {
     });
   });
 });
+
+describe('DropdownMenuSubMenu theming slots', () => {
+  it('exposes a themeable slot on the submenu indicator icon', async () => {
+    const user = userEvent.setup();
+    render(<MoveMenu />);
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+    const trigger = screen.getByRole('menuitem', {
+      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();
+  });
+});

package/src/DropdownMenu/DropdownMenuSubMenu.tsx

@@ -35,7 +35,7 @@
  * - /packages/core/src/DropdownMenu/DropdownMenuSubMenu.test.tsx
  * - /packages/core/src/DropdownMenu/index.ts
  * - /apps/storybook/stories/DropdownMenu.stories.tsx
- * - /packages/cli/templates/blocks/components/DropdownMenu/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/DropdownMenu/ (showcase blocks)
  */
 
 import React, {
@@ -474,11 +474,19 @@ export function DropdownMenuSubMenu(
   );
 
   const endAffordance = hasSpinner ? (
-    <span {...stylex.props(triggerStyles.caret)}>
+    <span
+      {...mergeProps(
+        themeProps('dropdown-menu-indicator-icon'),
+        stylex.props(triggerStyles.caret),
+      )}>
       <Spinner size="sm" />
     </span>
   ) : (
-    <span {...stylex.props(triggerStyles.caret)}>
+    <span
+      {...mergeProps(
+        themeProps('dropdown-menu-indicator-icon'),
+        stylex.props(triggerStyles.caret),
+      )}>
       <Icon icon="chevronRight" size="sm" color="secondary" />
     </span>
   );

package/src/DropdownMenu/renderDropdownItems.tsx

@@ -17,6 +17,7 @@ import {
   typeScaleVars,
   colorVars,
 } from '../theme/tokens.stylex';
+import {mergeProps, themeProps} from '../utils';
 import type {
   DropdownMenuItemData,
   DropdownMenuOption,
@@ -57,7 +58,13 @@ export function renderDropdownItems(items: DropdownMenuOption[]): ReactNode {
     const option = items[i];
 
     if ('type' in option && option.type === 'divider') {
-      elements.push(<Divider key={`divider-${i}`} xstyle={styles.divider} />);
+      elements.push(
+        <Divider
+          key={`divider-${i}`}
+          xstyle={styles.divider}
+          {...themeProps('dropdown-menu-divider')}
+        />,
+      );
     } else if ('type' in option && option.type === 'section') {
       elements.push(
         <div
@@ -65,7 +72,12 @@ export function renderDropdownItems(items: DropdownMenuOption[]): ReactNode {
           role="group"
           aria-label={option.title}>
           {option.title && (
-            <div {...stylex.props(styles.sectionHeading)} aria-hidden="true">
+            <div
+              aria-hidden="true"
+              {...mergeProps(
+                themeProps('dropdown-menu-section-heading'),
+                stylex.props(styles.sectionHeading),
+              )}>
               {option.title}
             </div>
           )}

package/src/EmptyState/EmptyState.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'EmptyState',
@@ -87,7 +87,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'EmptyState',
   displayName: 'Empty State',
@@ -156,7 +156,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'placeholder when a content area has no data: icon, title, description, action buttons',

package/src/EmptyState/EmptyState.tsx

@@ -11,7 +11,7 @@
  * - /packages/core/src/EmptyState/EmptyState.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/EmptyState/index.ts (exports if types change)
  * - /apps/storybook/stories/EmptyState.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/EmptyState/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/EmptyState/ (showcase blocks)
  */
 
 import {type ReactNode, createElement} from 'react';

package/src/Field/Field.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Field',
@@ -196,7 +196,7 @@ function CustomSliderField() {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description: 'Field is a low-level wrapper for custom, native, or third-party controls that do not already provide field label, description, and status UI. Use it when you need the Field shell around a control you own; use styled Astryx inputs like TextInput, Typeahead, and Select directly when they already expose label, description, and validation props.',
@@ -212,7 +212,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Low-level field shell for custom controls needing label/description/status.',

package/src/Field/Field.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/Field/Field.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Field/index.ts (exports if types change)
  * - /apps/storybook/stories/Field.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Field/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Field/ (showcase blocks)
  */
 
 import {type ReactNode, use} from 'react';

package/src/Field/FieldLabel.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'FieldLabel',

package/src/Field/FieldLabel.test.tsx

@@ -11,6 +11,7 @@
 
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import {TestIcon} from '../__tests__/TestIcon';
 import {InternationalizationProvider} from '../i18n';
 import {FieldLabel} from './FieldLabel';
@@ -119,4 +120,81 @@ describe('FieldLabel', () => {
     // Info icon should be present
     expect(document.querySelector('svg')).toBeInTheDocument();
   });
+
+  describe('description click forwarding', () => {
+    // Renders a real control with the target id so click-forwarding has
+    // something to hit, alongside the label whose description forwards clicks.
+    function renderWithControl(props: {
+      isGroupLabel?: boolean;
+      controlType?: string;
+      description?: React.ReactNode;
+    }) {
+      const {isGroupLabel, controlType = 'checkbox', description} = props;
+      const onClick = vi.fn();
+      render(
+        <>
+          <input id="ctrl" type={controlType} onClick={onClick} />
+          <FieldLabel
+            label="Notify"
+            inputID="ctrl"
+            description={description ?? "We'll email you"}
+            descriptionID="ctrl-desc"
+            isGroupLabel={isGroupLabel}
+          />
+        </>,
+      );
+      return onClick;
+    }
+
+    it('forwards a description click to a click-activatable control (checkbox)', async () => {
+      const user = userEvent.setup();
+      const onClick = renderWithControl({controlType: 'checkbox'});
+      await user.click(screen.getByText("We'll email you"));
+      expect(onClick).toHaveBeenCalledTimes(1);
+    });
+
+    it('focuses (does not click) a text input on description click', async () => {
+      const user = userEvent.setup();
+      const onClick = renderWithControl({controlType: 'text'});
+      await user.click(screen.getByText("We'll email you"));
+      // Text inputs focus rather than click — matching native label behavior,
+      // so no synthetic click fires but the control receives focus.
+      expect(onClick).not.toHaveBeenCalled();
+      expect(document.getElementById('ctrl')).toHaveFocus();
+    });
+
+    it('does NOT forward description clicks for a group label', async () => {
+      const user = userEvent.setup();
+      const onClick = renderWithControl({isGroupLabel: true});
+      await user.click(screen.getByText("We'll email you"));
+      expect(onClick).not.toHaveBeenCalled();
+    });
+
+    it('does NOT hijack clicks on interactive content inside the description', async () => {
+      const user = userEvent.setup();
+      const linkClick = vi.fn();
+      const onClick = renderWithControl({
+        description: (
+          <>
+            See our{' '}
+            <a href="#terms" onClick={linkClick}>
+              terms
+            </a>
+          </>
+        ),
+      });
+      await user.click(screen.getByRole('link', {name: 'terms'}));
+      // The nested link handles its own click; the control is not toggled.
+      expect(linkClick).toHaveBeenCalledTimes(1);
+      expect(onClick).not.toHaveBeenCalled();
+    });
+
+    it('keeps the description a sibling of the label (not nested inside it)', () => {
+      renderWithControl({});
+      const description = screen.getByText("We'll email you");
+      // The description must not live inside the <label> — nesting it there
+      // would fold it into the control's accessible name.
+      expect(description.closest('label')).toBeNull();
+    });
+  });
 });

package/src/Field/FieldLabel.tsx

@@ -11,11 +11,11 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Field/Field.doc.mjs (props table, features, implementation notes)
  * - /packages/core/src/Field/index.ts (exports if types change)
- * - /packages/cli/templates/blocks/components/Field/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Field/ (showcase blocks)
  * - /packages/core/locales/en.json (@astryx.field.required / @astryx.field.optional)
  */
 
-import type {ReactNode} from 'react';
+import {useMemo, useRef, type ReactNode, type RefObject} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
 import {mergeProps} from '../utils';
@@ -31,6 +31,7 @@ import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {Tooltip} from '../Tooltip';
 import {useTranslator} from '../i18n';
 import {themeProps} from '../utils/themeProps';
+import {useInputContainer} from '../hooks';
 
 const styles = stylex.create({
   label: {
@@ -76,6 +77,11 @@ const styles = stylex.create({
     fontWeight: fontWeightVars['--font-weight-normal'],
     color: colorVars['--color-text-secondary'],
   },
+  // When the description forwards clicks to a click-activatable control
+  // (checkbox/switch), it reads as part of the same hit target as the label.
+  descriptionClickable: {
+    cursor: 'pointer',
+  },
 });
 
 export interface FieldLabelProps extends BaseProps<HTMLLabelElement> {
@@ -194,6 +200,41 @@ export function FieldLabel({
   // label styling and slots. The group references it via `aria-labelledby`.
   const LabelElement = isGroupLabel ? 'span' : 'label';
 
+  // Clicking the description forwards to the associated control, so the whole
+  // label area (label text + description) is one hit target — mirroring native
+  // `<label>` click behavior, which the description can't get from `htmlFor`
+  // because it stays a sibling `<span>` (nesting it in the `<label>` would fold
+  // it into the control's accessible name and double-announce it alongside
+  // `aria-describedby`). A group label names a group, not one control, so it
+  // has nothing to forward to.
+  const forwardsDescriptionClick = !isGroupLabel && inputID != null;
+
+  // Reuse `useInputContainer` — the same hook input wrappers use to forward
+  // clicks on non-interactive chrome to their control. It skips nested
+  // interactive content (a link/button inside a ReactNode description) and
+  // guards against forwarding during text selection, so the description needs
+  // no bespoke click logic. The "input" is resolved from `inputID` lazily via
+  // a ref-shaped object, since FieldLabel points at the control by id rather
+  // than holding a ref to it.
+  const descriptionRef = useRef<HTMLSpanElement>(null);
+  const controlRef = useMemo<RefObject<HTMLElement | null>>(
+    () => ({
+      get current() {
+        return inputID == null
+          ? null
+          : (descriptionRef.current?.ownerDocument.getElementById(inputID) ??
+              null);
+      },
+      set current(_value) {},
+    }),
+    [inputID],
+  );
+  const descriptionClickProps = useInputContainer({
+    containerRef: descriptionRef,
+    inputRef: controlRef,
+    disabled: !forwardsDescriptionClick,
+  });
+
   const labelContent = (
     <>
       {labelIcon && renderIconSlot(labelIcon, {size: 'sm', color: 'inherit'})}
@@ -236,8 +277,14 @@ export function FieldLabel({
       </LabelElement>
       {description && (
         <span
+          ref={forwardsDescriptionClick ? descriptionRef : undefined}
           id={descriptionID}
-          {...stylex.props(styles.description, isLabelHidden && styles.srOnly)}>
+          {...(forwardsDescriptionClick ? descriptionClickProps : undefined)}
+          {...stylex.props(
+            styles.description,
+            forwardsDescriptionClick && styles.descriptionClickable,
+            isLabelHidden && styles.srOnly,
+          )}>
           {description}
         </span>
       )}