@astryxdesign/core 0.6.0 → 0.6.1

package/src/Popover/Popover.spec.md

@@ -46,36 +46,33 @@ and rendering contract for custom compositions.
 This contract records the behavior present after
 [PR #5373](https://github.com/facebook/astryx/pull/5373), the Popover target
 direction settled by Cindy Zhang on 2026-08-31, and the focus/opening correction
-approved by Cindy Zhang on 2026-09-07. Public API signatures, emitted classes,
-and release status remain unchanged. Consumer syntax and complete signatures
-remain owned by `Popover.doc.mjs` and `usePopover.doc.mjs`; automatic canonical-
-target emission and compatibility removal require separately reviewed runtime
-work.
+approved by Cindy Zhang on 2026-09-07. Public API signatures and release status
+remain unchanged. Consumer syntax and complete signatures remain owned by
+`Popover.doc.mjs` and `usePopover.doc.mjs`. The canonical `popover` target and
+the deprecated `popover-surface` compatibility alias remain supported together.
 
 ## Compatibility and migration
 
 - Released default preserved: `yes`
-- Compatibility class: documentation-only target ownership clarification;
-  runtime, DOM, styling, emitted classes, and public API are unchanged
+- Compatibility class: the canonical and deprecated targets are emitted together;
+  runtime behavior, DOM shape, styling, and public API otherwise remain unchanged
 - Canonical target: `popover` owns the broad painted-surface contract for
-  `<Popover>` and public `usePopover` compositions
-- Deprecated alias: `popover-surface` remains emitted so existing themes keep
-  working during a documented migration window; it is not a second anatomy part
-  or equal durable owner
+  `<Popover>` and public `usePopover` compositions and is preferred in new themes
+- Deprecated alias: `popover-surface` remains emitted, documented as deprecated,
+  and discoverable with `popover` as its exact replacement so existing themes keep
+  working; it is not a second anatomy part or equal durable owner
 - Composed components: component-specific surface targets such as
   `selector-popup` and `multi-selector-popup` remain authoritative refinements;
-  compatibility output may remain underneath until migration
+  the broad canonical and compatibility targets remain underneath
 - New hook consumers: a direct `usePopover` composition that needs its own theme
-  reachability provides and documents an owned `surfaceTarget`; it does not
-  create a new dependency on `popover-surface`
-- Migration decision: target ownership is settled; automatic `popover` emission
-  for every painted hook surface and eventual alias removal ship only through
-  separately reviewed runtime changes
+  reachability provides and documents an owned `surfaceTarget`; it does not create
+  a new dependency on `popover-surface`
+- Migration decision: maintained themes and copyable new examples use `popover`;
+  compatibility discovery and runtime support for `popover-surface` continue
 
-The implementation migration must preserve `popover-surface` themes until its
-announced removal window. Implementation and removal each update consumer
-migration guidance, target inventory, focused tests, and changelog or release
-documentation; this documentation-only PR does none of those runtime steps.
+Deprecation does not implement or require alias removal. CLI and theme-build
+surfaces label `popover-surface` as deprecated and warn with the exact `popover`
+replacement when it is authored, while existing themes continue to work.
 
 ## Ownership boundary
 
@@ -117,16 +114,16 @@ surface, not the Layer entry point. There is no installable
 
 ## Public concepts
 
-| Concept                  | Closed values or states                                      | Meaning                                                                                                               | Availability              | Default                                                                      | Owner                                                                               | Stability                                    | Invalid or unsupported behavior                                                                                                                            |
-| ------------------------ | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Trigger composition      | Wrapped trigger, render-prop trigger, or referenced anchor   | Supplies the anchor and the control that opens or closes the standard component                                       | Popover                   | Wrapped trigger when children are supplied                                   | `component:Popover`                                                                 | Current public behavior                      | A referenced or wrapped anchor without a button or button role warns in development and receives no trigger handler; it does not throw.                    |
-| Visibility ownership     | Uncontrolled or externally controlled                        | Chooses whether Popover stores visibility or synchronizes to caller state                                             | Popover                   | Uncontrolled                                                                 | `component:Popover`                                                                 | Current public behavior                      | Controlled changes are synchronized through show/hide; dismissal requests are reported to the caller rather than redefining the external source of truth.  |
-| Popup semantics          | Dialog or neutral wrapper                                    | Exposes dialog semantics or lets child menu/listbox semantics own the popup                                           | Popover and hook          | Dialog                                                                       | `component:Popover`                                                                 | Current public behavior                      | A dialog without a label warns in development. Neutral mode omits dialog role and modal semantics.                                                         |
-| Focus entry              | Automatic or caller-preserved                                | Focuses genuine caller content, falls back to the labeled dialog surface when none exists, or preserves current focus | Popover and hook          | Automatic                                                                    | `component:Popover`                                                                 | Current public behavior                      | The injected fallback close control is excluded from initial-focus candidates and reveals only when reached sequentially.                                  |
-| Dismissal                | Outside/Escape enabled or disabled within native constraints | Controls light dismiss and explicit Escape participation                                                              | Popover and hook          | Both enabled                                                                 | `component:Popover`; `family:overlay-dismissal` owns Escape/platform-close ordering | Current public behavior                      | Disabling Escape alone cannot override the native Escape behavior of an auto popover; explicit-dismiss behavior requires light dismiss to be disabled too. |
-| Surface treatment        | Default surface or caller-owned treatment                    | Applies the shared painted surface and optional consumer styling                                                      | Popover and hook          | Default surface                                                              | `component:Popover`                                                                 | Current public behavior                      | Custom styling does not change lifecycle, focus, or dismissal semantics.                                                                                   |
-| Surface target ownership | Shared baseline or component-specific refinement             | Assigns `popover` as the broad surface owner and lets a composed component add its own target on that same element    | Popover and hook          | `popover` baseline; no component-specific refinement                         | `component:Popover`; the composed component owns its refinement target              | Accepted contract; runtime alignment pending | `popover-surface` is compatibility output, not a new target for consumers or a second anatomy owner.                                                       |
-| Placement and fit        | Logical placement/alignment plus preferred width             | Positions the anchor surface and constrains it to available space                                                     | Popover and hook renderer | Below/start; Popover matches trigger minimum width when no width is supplied | `component:Popover` above `architecture:layer-runtime`                              | Current public behavior                      | Preferred width and trigger matching remain capped by viewport and safe-area availability.                                                                 |
+| Concept                  | Closed values or states                                      | Meaning                                                                                                               | Availability              | Default                                                                      | Owner                                                                               | Stability                      | Invalid or unsupported behavior                                                                                                                            |
+| ------------------------ | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Trigger composition      | Wrapped trigger, render-prop trigger, or referenced anchor   | Supplies the anchor and the control that opens or closes the standard component                                       | Popover                   | Wrapped trigger when children are supplied                                   | `component:Popover`                                                                 | Current public behavior        | A referenced or wrapped anchor without a button or button role warns in development and receives no trigger handler; it does not throw.                    |
+| Visibility ownership     | Uncontrolled or externally controlled                        | Chooses whether Popover stores visibility or synchronizes to caller state                                             | Popover                   | Uncontrolled                                                                 | `component:Popover`                                                                 | Current public behavior        | Controlled changes are synchronized through show/hide; dismissal requests are reported to the caller rather than redefining the external source of truth.  |
+| Popup semantics          | Dialog or neutral wrapper                                    | Exposes dialog semantics or lets child menu/listbox semantics own the popup                                           | Popover and hook          | Dialog                                                                       | `component:Popover`                                                                 | Current public behavior        | A dialog without a label warns in development. Neutral mode omits dialog role and modal semantics.                                                         |
+| Focus entry              | Automatic or caller-preserved                                | Focuses genuine caller content, falls back to the labeled dialog surface when none exists, or preserves current focus | Popover and hook          | Automatic                                                                    | `component:Popover`                                                                 | Current public behavior        | The injected fallback close control is excluded from initial-focus candidates and reveals only when reached sequentially.                                  |
+| Dismissal                | Outside/Escape enabled or disabled within native constraints | Controls light dismiss and explicit Escape participation                                                              | Popover and hook          | Both enabled                                                                 | `component:Popover`; `family:overlay-dismissal` owns Escape/platform-close ordering | Current public behavior        | Disabling Escape alone cannot override the native Escape behavior of an auto popover; explicit-dismiss behavior requires light dismiss to be disabled too. |
+| Surface treatment        | Default surface or caller-owned treatment                    | Applies the shared painted surface and optional consumer styling                                                      | Popover and hook          | Default surface                                                              | `component:Popover`                                                                 | Current public behavior        | Custom styling does not change lifecycle, focus, or dismissal semantics.                                                                                   |
+| Surface target ownership | Shared baseline or component-specific refinement             | Assigns `popover` as the broad surface owner and lets a composed component add its own target on that same element    | Popover and hook          | `popover` baseline; no component-specific refinement                         | `component:Popover`; the composed component owns its refinement target              | Current compatibility contract | `popover-surface` is compatibility output, not a new target for consumers or a second anatomy owner.                                                       |
+| Placement and fit        | Logical placement/alignment plus preferred width             | Positions the anchor surface and constrains it to available space                                                     | Popover and hook renderer | Below/start; Popover matches trigger minimum width when no width is supplied | `component:Popover` above `architecture:layer-runtime`                              | Current public behavior        | Preferred width and trigger matching remain capped by viewport and safe-area availability.                                                                 |
 
 ### Public `usePopover` semantic inputs
 
@@ -173,15 +170,15 @@ table owns their semantic effect.
 
 ## Behavioral and layout contract
 
-| ID  | Invariant                                                                                                                                                                                                                                                          | Basis                                                                                               | Acceptance and implementation state                                                                                        |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| FR1 | Popover and public `usePopover` expose one visibility lifecycle with canonical show, hide, and toggle operations. Every opening path inherits same-gesture reopen protection without changing public signatures.                                                   | Current public package surface, `architecture:layer-runtime/INV7`, and owner approval on 2026-09-07 | Accepted; implemented and covered by focused Popover-family tests                                                          |
-| FR2 | Popover derives semantic focus entry identically across activation modalities: first genuine caller content, then labeled dialog-surface fallback. The injected close control is excluded. Shared interaction modality controls focus indication, not destination. | PR #5373, `architecture:interaction-modality`, and owner approval on 2026-09-07                     | Accepted; implemented and covered by Popover focus tests                                                                   |
-| FR3 | The preferred surface size is capped to logical viewport and safe-area availability before overflow is enabled.                                                                                                                                                    | PR #5373, current source, tests, and Storybook fixtures                                             | Verified in unit/style evidence; real rendered viewport evidence remains a gap                                             |
-| FR4 | Popover enables internal scrolling only after measured overflow exceeds the current tolerance. Fitting content does not become a scroll container.                                                                                                                 | PR #5373 and current tests                                                                          | Verified current behavior                                                                                                  |
-| FR5 | Overflow signals while open coalesce into at most one measurement per animation frame, and Popover owns no measurement observers while closed.                                                                                                                     | PR #5373 and current tests                                                                          | Verified current resource behavior                                                                                         |
-| FR6 | Component anatomy contains the caller trigger and content, one painted Popover surface, and the optional fallback close control. Popover owns no Header, Body, or separate shared-hook surface part.                                                               | Current source, docs target inventory, and tests                                                    | Accepted anatomy; stale consumer anatomy corrected by this contract                                                        |
-| FR7 | The painted surface has one broad canonical target, `popover`. `popover-surface` is a deprecated compatibility alias on that same part; composed components may add one authoritative component-specific refinement target.                                        | Owner direction on 2026-08-31 plus current target inventory                                         | Accepted semantic contract; automatic hook-wide emission and compatibility removal remain separately reviewed runtime work |
+| ID  | Invariant                                                                                                                                                                                                                                                          | Basis                                                                                               | Acceptance and implementation state                                                               |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| FR1 | Popover and public `usePopover` expose one visibility lifecycle with canonical show, hide, and toggle operations. Every opening path inherits same-gesture reopen protection without changing public signatures.                                                   | Current public package surface, `architecture:layer-runtime/INV7`, and owner approval on 2026-09-07 | Accepted; implemented and covered by focused Popover-family tests                                 |
+| FR2 | Popover derives semantic focus entry identically across activation modalities: first genuine caller content, then labeled dialog-surface fallback. The injected close control is excluded. Shared interaction modality controls focus indication, not destination. | PR #5373, `architecture:interaction-modality`, and owner approval on 2026-09-07                     | Accepted; implemented and covered by Popover focus tests                                          |
+| FR3 | The preferred surface size is capped to logical viewport and safe-area availability before overflow is enabled.                                                                                                                                                    | PR #5373, current source, tests, and Storybook fixtures                                             | Verified in unit/style evidence; real rendered viewport evidence remains a gap                    |
+| FR4 | Popover enables internal scrolling only after measured overflow exceeds the current tolerance. Fitting content does not become a scroll container.                                                                                                                 | PR #5373 and current tests                                                                          | Verified current behavior                                                                         |
+| FR5 | Overflow signals while open coalesce into at most one measurement per animation frame, and Popover owns no measurement observers while closed.                                                                                                                     | PR #5373 and current tests                                                                          | Verified current resource behavior                                                                |
+| FR6 | Component anatomy contains the caller trigger and content, one painted Popover surface, and the optional fallback close control. Popover owns no Header, Body, or separate shared-hook surface part.                                                               | Current source, docs target inventory, and tests                                                    | Accepted anatomy; stale consumer anatomy corrected by this contract                               |
+| FR7 | The painted surface has one broad canonical target, `popover`. `popover-surface` remains a deprecated compatibility alias on that same part; composed components may add one authoritative component-specific refinement target.                                   | Owner direction on 2026-08-31 plus current target inventory                                         | Accepted compatibility contract; both canonical and deprecated paths remain supported and covered |
 
 ### Allowed variation
 
@@ -297,21 +294,20 @@ table owns their semantic effect.
 
 `popover-surface` is a deprecated alias for `popover` on the same painted
 surface. It is not anatomy and has no independent conceptual ownership. The
-component doc marks it with `deprecatedFor: 'popover'`, so the anatomy validator
-excludes it from the active target inventory while the runtime keeps emitting
-it for existing themes.
-
-Every public `usePopover` painted surface belongs to the broad `popover` target.
-A composed component may add its own authoritative refinement target, such as
-`selector-popup` or `multi-selector-popup`, on that same element. New direct
-hook consumers that need distinct theme reachability provide and document an
-owned `surfaceTarget`; they do not use `popover-surface`.
-
-Automatic hook-wide `popover` emission and eventual removal of the compatibility
-alias are runtime migration work outside this contract. Existing
-`popover-surface` themes remain supported until that separately reviewed
-migration includes target-inventory and regression-test updates plus changelog
-or release guidance.
+component doc keeps `deprecatedFor: 'popover'`, discovery labels the alias with
+that exact replacement, and runtime keeps emitting both names for existing
+themes.
+
+Every public `usePopover` painted surface belongs to the broad `popover` target
+and retains the `popover-surface` compatibility alias. A composed component may
+add its own authoritative refinement target, such as `selector-popup` or
+`multi-selector-popup`, on that same element. New direct hook consumers that
+need distinct theme reachability provide and document an owned `surfaceTarget`;
+they use `popover` in new theme source rather than authoring the deprecated key.
+
+Maintained themes, templates, and copyable new examples use `popover`. Existing
+`popover-surface` themes remain supported; deprecation does not imply or require
+removal.
 
 ## Family and system relationships
 
@@ -368,9 +364,9 @@ focus indication, while Popover owns semantic focus placement.
 
 `popover` is the broad canonical theming baseline automatically owned by every
 painted surface created by `<Popover>` or public `usePopover`.
-`popover-surface` is deprecated compatibility output on that same element, not a
-second anatomy part or equal owner. Existing themes using it remain supported
-through a documented migration window.
+`popover-surface` remains deprecated compatibility output on that same element,
+not a second anatomy part or equal owner. Existing themes using it remain
+supported, while maintained and newly authored themes use `popover`.
 
 Composed components keep authoritative refinement targets such as
 `selector-popup` and `multi-selector-popup`. Optional `surfaceTarget` adds that
@@ -415,18 +411,12 @@ not block acceptance of the semantic contract above.
 - **VG2 — AT announcement.** The current story provides manual instructions, but
   named NVDA + Chrome and VoiceOver + Safari results are absent. No announcement
   outcome is claimed.
-- **VG3 — Target migration.** Current runtime still emits `popover-surface` as
-  the automatic shared class and reaches `popover` through Popover's explicit
-  `surfaceTarget`. A separate implementation must make `popover` automatic for
-  every public hook surface while preserving the alias, then verify direct-hook
-  and composed-component target inventories before any later removal.
 
 ## Open questions
 
 None. DEC-1 settles the visibility model, DEC-2 settles canonical target
 ownership, and DEC-3 settles semantic focus versus modality-aware indication.
-The remaining items are verification or separately reviewed implementation work,
-not human API questions.
+The remaining items are verification work, not human API questions.
 
 ## Content boundary
 

package/src/Popover/Popover.test.tsx

@@ -17,6 +17,7 @@ import * as stylex from '@stylexjs/stylex';
 import {readFileSync} from 'node:fs';
 import React, {useRef} from 'react';
 import {Popover} from './Popover';
+import {usePopover} from './usePopover';
 import type {UsePopoverReturn} from './usePopover';
 import {Dialog} from '../Dialog';
 import {SegmentedControl, SegmentedControlItem} from '../SegmentedControl';
@@ -83,6 +84,34 @@ describe('usePopover public return type', () => {
     expect(publicToggleTakesNoOptions).toBe(true);
     expect(hasInternalFocusTarget).toBe(false);
   });
+
+  it('emits canonical and deprecated surface targets for direct hook consumers', () => {
+    function HeadlessPopover() {
+      const popover = usePopover({dialogLabel: 'Headless popover'});
+      return (
+        <>
+          <button
+            type="button"
+            ref={popover.triggerRef}
+            onClick={() => popover.show()}
+            {...popover.triggerProps}>
+            Open headless
+          </button>
+          {popover.render(<span>Headless content</span>)}
+        </>
+      );
+    }
+
+    render(<HeadlessPopover />);
+    fireEvent.click(screen.getByRole('button', {name: 'Open headless'}));
+
+    const surface = screen.getByRole('dialog', {
+      name: 'Headless popover',
+      hidden: true,
+    });
+    expect(surface).toHaveClass('astryx-popover');
+    expect(surface).toHaveClass('astryx-popover-surface');
+  });
 });
 
 describe('Popover', () => {

package/src/Popover/usePopover.doc.mjs

@@ -159,7 +159,7 @@ export const docs = {
   ],
   usage: {
     description:
-      'Headless hook for click-triggered popovers with focus trapping. Combines useLayer with useFocusTrap, auto-focus, light dismiss, Escape handling, and an optional hidden close button for accessible dialog-like popover behavior. Use for custom interactive floating content that needs keyboard navigation. The canonical broad surface target is popover; automatic hook-wide emission is separate migration work, so current direct compositions needing a distinct stable seam should pass and document their own surfaceTarget instead of depending on deprecated popover-surface.',
+      'Headless hook for click-triggered popovers with focus trapping. Combines useLayer with useFocusTrap, auto-focus, light dismiss, Escape handling, and an optional hidden close button for accessible dialog-like popover behavior. Every painted surface emits the canonical popover target and deprecated popover-surface compatibility alias. A custom composition needing a distinct stable seam should pass and document its own surfaceTarget.',
     bestPractices: [
       {
         guidance: true,
@@ -174,7 +174,7 @@ export const docs = {
       {
         guidance: true,
         description:
-          'Use popover as the broad surface target. During migration, popover-surface remains compatibility output only; do not create new theme dependencies on it.',
+          'Use popover as the broad surface target. Popover-surface remains supported compatibility output, but new theme source uses the canonical key.',
       },
       {
         guidance: true,
@@ -197,7 +197,7 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
-    'Headless click-triggered popovers w/ focus trap, auto-focus, light dismiss, Escape, optional hidden close button. Canonical broad target is popover; automatic hook-wide emission is separate migration work. Current direct compositions needing a distinct seam pass/document an owned surfaceTarget; do not depend on deprecated popover-surface.',
+    'Headless click-triggered popovers w/ focus trap, auto-focus, light dismiss, Escape, optional hidden close button. Every surface emits canonical popover plus deprecated popover-surface compatibility output. Custom compositions needing a distinct seam pass/document an owned surfaceTarget.',
   paramDescriptions: {
     onShow: 'fires when popover becomes visible.',
     onHide: 'fires when popover hides; use to return focus when needed.',
@@ -230,7 +230,7 @@ export const docsDense = {
   },
   usage: {
     description:
-      'Headless click-triggered popovers w/ focus trap, auto-focus, light dismiss, Escape, optional hidden close button. Canonical broad target is popover; automatic hook-wide emission is separate migration work. Current direct compositions needing a distinct seam pass/document an owned surfaceTarget; do not depend on deprecated popover-surface.',
+      'Headless click-triggered popovers w/ focus trap, auto-focus, light dismiss, Escape, optional hidden close button. Every surface emits canonical popover plus deprecated popover-surface compatibility output. Custom compositions needing a distinct seam pass/document an owned surfaceTarget.',
     bestPractices: [
       {
         guidance: true,

package/src/Popover/usePopover.tsx

@@ -240,8 +240,9 @@ export interface UsePopoverOptions {
    * or radius rule paints the wrong box. Name the surface through this option
    * and document the class in the component's `theming.targets`.
    *
-   * The shared `astryx-popover-surface` class is always present alongside it,
-   * so a theme can style every popup surface at once.
+   * The canonical `astryx-popover` target and deprecated
+   * `astryx-popover-surface` compatibility alias are always present alongside
+   * any component-owned refinement target.
    */
   surfaceTarget?: string;
 }
@@ -485,9 +486,11 @@ function usePopoverImplementation(
       // `mergeProps` is positional — a third OBJECT argument is read as
       // `style`, not as more props — so the surface's classes are composed
       // into one props object before merging with the StyleX result.
-      const surfaceProps = themeProps('popover-surface');
+      const surfaceProps = themeProps('popover', undefined, {
+        legacyNames: ['popover-surface'],
+      });
       const surfaceClassName =
-        surfaceTarget != null
+        surfaceTarget != null && surfaceTarget !== 'popover'
           ? `${surfaceProps.className} ${stableClassName(surfaceTarget)}`
           : surfaceProps.className;
 

package/src/ProgressBar/ProgressBar.doc.mjs

@@ -132,8 +132,8 @@ export const docs = {
         className: 'astryx-progress-bar-mark',
         visualProps: ['variant', 'placement'],
       },
-      // Still emitted beside the names above, so themes written against
-      // them keep working. Drop in the next major.
+      // Retained beside the canonical names for backwards compatibility.
+      // New themes use the canonical targets above.
       {
         className: 'astryx-progressbar',
         visualProps: ['variant'],
@@ -297,8 +297,8 @@ export const docsZh = {
         className: 'astryx-progress-bar-mark',
         visualProps: ['variant', 'placement'],
       },
-      // Still emitted beside the names above, so themes written against
-      // them keep working. Drop in the next major.
+      // Retained beside the canonical names for backwards compatibility.
+      // New themes use the canonical targets above.
       {
         className: 'astryx-progressbar',
         visualProps: ['variant'],

package/src/ProgressBar/ProgressBar.test.tsx

@@ -14,23 +14,6 @@ beforeAll(async () => {
 });
 
 describe('ProgressBar', () => {
-  it('renders with default props', () => {
-    render(<ProgressBar value={50} label="Progress" />);
-    const progressbar = screen.getByRole('progressbar');
-    expect(progressbar).toBeInTheDocument();
-    expect(progressbar).toHaveAttribute('aria-valuenow', '50');
-    expect(progressbar).toHaveAttribute('aria-valuemin', '0');
-    expect(progressbar).toHaveAttribute('aria-valuemax', '100');
-  });
-
-  it('uses role="progressbar" (not "meter") for determinate progress', () => {
-    // A determinate ProgressBar conveys task completion, so it must be a
-    // progressbar (announced on update), not a meter (a static gauge).
-    render(<ProgressBar value={50} label="Progress" />);
-    expect(screen.getByRole('progressbar')).toBeInTheDocument();
-    expect(screen.queryByRole('meter')).not.toBeInTheDocument();
-  });
-
   it('renders visible label by default', () => {
     render(<ProgressBar value={50} label="Storage used" />);
     expect(screen.getByText('Storage used')).toBeInTheDocument();
@@ -70,13 +53,6 @@ describe('ProgressBar', () => {
     expect(progressbar).toHaveAttribute('aria-valuetext', '50%');
   });
 
-  it('respects custom max', () => {
-    render(<ProgressBar value={3} max={10} label="Steps" />);
-    const progressbar = screen.getByRole('progressbar');
-    expect(progressbar).toHaveAttribute('aria-valuenow', '3');
-    expect(progressbar).toHaveAttribute('aria-valuemax', '10');
-  });
-
   it('clamps value to [0, max]', () => {
     const {rerender} = render(
       <ProgressBar value={150} max={100} label="Over" />,
@@ -197,13 +173,7 @@ describe('ProgressBar', () => {
 
   // Indeterminate mode tests
   describe('indeterminate mode', () => {
-    it('renders with role="progressbar" when isIndeterminate', () => {
-      render(<ProgressBar isIndeterminate label="Loading" />);
-      const progressbar = screen.getByRole('progressbar');
-      expect(progressbar).toBeInTheDocument();
-    });
-
-    it('does not set aria-valuenow/min/max when indeterminate', () => {
+    it('omits authored value attributes while the value is indeterminate', () => {
       render(<ProgressBar isIndeterminate label="Loading" />);
       const progressbar = screen.getByRole('progressbar');
       expect(progressbar).not.toHaveAttribute('aria-valuenow');

package/src/ProgressBar/ProgressBar.tsx

@@ -482,8 +482,8 @@ export function ProgressBar({
         themeProps(
           'progress-bar',
           {variant},
-          // `progressbar` ran the compound name together; themes styling it
-          // keep working until the next major.
+          // `progressbar` ran the compound name together; keep it emitted so
+          // existing themes continue to work.
           {legacyNames: ['progressbar']},
         ),
         stylex.props(styles.container, xstyle),

package/src/RadioList/RadioList.test.tsx

@@ -3,8 +3,11 @@
 /**
  * @file RadioList.test.tsx
  * @input Uses vitest, @testing-library/react, RadioList, RadioListItem
- * @output Unit tests for RadioList and RadioListItem behavior
- * @position Testing; validates RadioList.tsx and RadioListItem.tsx implementation
+ * @output Component-specific callback, form, composition, layout, and styling
+ *   tests. Shared radio-group role, name, state, focus, and interaction outcomes
+ *   live in __tests__/RadioGroup.a11y.test.tsx and its Chromium twin.
+ * @position Component-owned regression tests that do not duplicate the reusable
+ *   radio-group contract.
  *
  * SYNC: When RadioList.tsx or RadioListItem.tsx changes, update tests to match new behavior
  */
@@ -64,29 +67,6 @@ describe('RadioList', () => {
     expect(screen.getAllByRole('radio')).toHaveLength(3);
   });
 
-  it('renders radiogroup role', () => {
-    render(
-      <RadioList label="Preference" value="" onChange={() => {}}>
-        <RadioListItem label="Option A" value="a" />
-      </RadioList>,
-    );
-    expect(screen.getByRole('radiogroup')).toBeInTheDocument();
-  });
-
-  it('selects the correct radio based on value prop', () => {
-    render(
-      <RadioList label="Preference" value="b" onChange={() => {}}>
-        <RadioListItem label="Option A" value="a" />
-        <RadioListItem label="Option B" value="b" />
-        <RadioListItem label="Option C" value="c" />
-      </RadioList>,
-    );
-    const radios = screen.getAllByRole('radio');
-    expect(radios[0]).not.toBeChecked();
-    expect(radios[1]).toBeChecked();
-    expect(radios[2]).not.toBeChecked();
-  });
-
   it('calls onChange with value string when clicking a radio', async () => {
     const user = userEvent.setup();
     const handleChange = vi.fn();
@@ -132,18 +112,6 @@ describe('RadioList', () => {
     expect(handleChange).toHaveBeenCalledWith('b');
   });
 
-  it('disables all radios when group isDisabled is true', () => {
-    render(
-      <RadioList label="Preference" value="" onChange={() => {}} isDisabled>
-        <RadioListItem label="Option A" value="a" />
-        <RadioListItem label="Option B" value="b" />
-      </RadioList>,
-    );
-    const radios = screen.getAllByRole('radio');
-    expect(radios[0]).toBeDisabled();
-    expect(radios[1]).toBeDisabled();
-  });
-
   it('does not call onChange when group is disabled', async () => {
     const user = userEvent.setup();
     const handleChange = vi.fn();
@@ -163,18 +131,6 @@ describe('RadioList', () => {
     expect(handleChange).not.toHaveBeenCalled();
   });
 
-  it('disables individual item when item isDisabled is true', () => {
-    render(
-      <RadioList label="Preference" value="" onChange={() => {}}>
-        <RadioListItem label="Option A" value="a" />
-        <RadioListItem label="Option B" value="b" isDisabled />
-      </RadioList>,
-    );
-    const radios = screen.getAllByRole('radio');
-    expect(radios[0]).not.toBeDisabled();
-    expect(radios[1]).toBeDisabled();
-  });
-
   it('does not call onChange when individual item is disabled', async () => {
     const user = userEvent.setup();
     const handleChange = vi.fn();
@@ -251,22 +207,6 @@ describe('RadioList', () => {
     expect(screen.getByText('Great choice!')).toBeInTheDocument();
   });
 
-  it('sets aria-invalid on radiogroup when status is error', () => {
-    render(
-      <RadioList
-        label="Preference"
-        value=""
-        onChange={() => {}}
-        status={{type: 'error', message: 'Required'}}>
-        <RadioListItem label="Option A" value="a" />
-      </RadioList>,
-    );
-    expect(screen.getByRole('radiogroup')).toHaveAttribute(
-      'aria-invalid',
-      'true',
-    );
-  });
-
   it('renders startContent', () => {
     render(
       <RadioList label="Preference" value="" onChange={() => {}}>
@@ -398,59 +338,7 @@ describe('RadioList', () => {
     expect(screen.getAllByRole('radio')).toHaveLength(2);
   });
 
-  it('sets aria-required on radiogroup when isRequired is true', () => {
-    render(
-      <RadioList label="Preference" value="" onChange={() => {}} isRequired>
-        <RadioListItem label="Option A" value="a" />
-      </RadioList>,
-    );
-    expect(screen.getByRole('radiogroup')).toHaveAttribute(
-      'aria-required',
-      'true',
-    );
-  });
-
   describe('focus management (no-selection tab stop)', () => {
-    it('keeps focus on the selected radio when a value is selected', () => {
-      render(
-        <RadioList label="Preference" value="b" onChange={() => {}}>
-          <RadioListItem label="Option A" value="a" />
-          <RadioListItem label="Option B" value="b" />
-          <RadioListItem label="Option C" value="c" />
-        </RadioList>,
-      );
-      const selected = screen.getByLabelText('Option B');
-      // A selected value provides a deterministic native tab stop; focusing it
-      // must not be redirected elsewhere.
-      selected.focus();
-      expect(selected).toHaveFocus();
-    });
-
-    it('redirects to the first radio when focus enters an unselected group forward', () => {
-      render(
-        <>
-          <button type="button">before</button>
-          <RadioList label="Preference" value="" onChange={() => {}}>
-            <RadioListItem label="Option A" value="a" />
-            <RadioListItem label="Option B" value="b" />
-            <RadioListItem label="Option C" value="c" />
-          </RadioList>
-        </>,
-      );
-      const radios = screen.getAllByRole('radio');
-      const outside = screen.getByText('before');
-      outside.focus();
-      // Forward entry: the browser lands on a leading radio; the group keeps the
-      // first radio as the deterministic tab stop.
-      radios[0].focus();
-      expect(radios[0]).toHaveFocus();
-
-      // Landing on a middle radio from outside is normalized to the first.
-      outside.focus();
-      radios[1].focus();
-      expect(radios[0]).toHaveFocus();
-    });
-
     it('redirects to the last radio when focus enters an unselected group backward', () => {
       render(
         <>
@@ -570,21 +458,6 @@ describe('RadioList', () => {
       expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
     });
 
-    it('keeps radios focusable via aria-disabled when a reason is provided', () => {
-      renderGroup();
-      for (const radio of screen.getAllByRole('radio', h)) {
-        expect(radio).not.toBeDisabled();
-        expect(radio).toHaveAttribute('aria-disabled', 'true');
-      }
-    });
-
-    it('links the reason tooltip from the group via aria-describedby', () => {
-      renderGroup();
-      const group = screen.getByRole('radiogroup');
-      const tooltip = screen.getByRole('tooltip', h);
-      expect(group.getAttribute('aria-describedby')).toContain(tooltip.id);
-    });
-
     it('blocks selection while focusable-disabled', () => {
       const onChange = vi.fn();
       renderGroup({onChange});
@@ -592,18 +465,6 @@ describe('RadioList', () => {
       fireEvent.click(pro);
       expect(onChange).not.toHaveBeenCalled();
     });
-
-    it('keeps radios natively disabled when disabled without a reason', () => {
-      render(
-        <RadioList label="Plan" value="free" onChange={() => {}} isDisabled>
-          <RadioListItem label="Free" value="free" />
-          <RadioListItem label="Pro" value="pro" />
-        </RadioList>,
-      );
-      for (const radio of screen.getAllByRole('radio', h)) {
-        expect(radio).toBeDisabled();
-      }
-    });
   });
   describe('form participation', () => {
     it('submits the selected value under htmlName', () => {