@primer/react 38.37.0-rc.0b6dd7e38 → 38.37.0-rc.1789e76c6

package/CHANGELOG.md

@@ -4,8 +4,12 @@
 
 ### Minor Changes
 
+- [#8306](https://github.com/primer/react/pull/8306) [`a3afd7b`](https://github.com/primer/react/commit/a3afd7baf05ea6c4a272a40ccb636f20a48f87dc) Thanks [@llastflowers](https://github.com/llastflowers)! - Deprecate the `Flash` component and move to `@primer/react/deprecated`
+
 - [#8295](https://github.com/primer/react/pull/8295) [`bfebb8a`](https://github.com/primer/react/commit/bfebb8a538e6f068a457722b154799876bda3ab4) Thanks [@copilot-swe-agent](https://github.com/apps/copilot-swe-agent)! - Textarea: Add an `autoSize` option that allows the field to grow with its content
 
+- [#8233](https://github.com/primer/react/pull/8233) [`80a68cf`](https://github.com/primer/react/commit/80a68cf05226323ad8cbc0531f244d60ea6747e3) Thanks [@rickyzhangca](https://github.com/rickyzhangca)! - UnderlinePanels: add controlled `value`/`defaultValue`/`onChange` and `activationMode` props, keyed to a per-`Tab`/`Panel` `value`, for data-driven tabs. Behind the `primer_react_underline_panels_controlled` feature flag; the existing `aria-selected`/`onSelect` API is unchanged.
+
 ### Patch Changes
 
 - [#8304](https://github.com/primer/react/pull/8304) [`88feb65`](https://github.com/primer/react/commit/88feb658c13fec154da1a8aa199250514f4fdba3) Thanks [@iansan5653](https://github.com/iansan5653)! - Animate `SegmentedControl` when switching between items

package/dist/FeatureFlags/DefaultFeatureFlags.js

@@ -8,7 +8,8 @@ const DefaultFeatureFlags = FeatureFlagScope.create({
 	primer_react_action_list_group_heading_trailing_action: false,
 	primer_react_action_list_item_gap: false,
 	primer_react_timeline_list_semantics: false,
-	primer_react_merged_forwarded_refs: false
+	primer_react_merged_forwarded_refs: false,
+	primer_react_underline_panels_controlled: false
 });
 //#endregion
 export { DefaultFeatureFlags };

package/dist/Flash/Flash.d.ts

@@ -2,11 +2,17 @@ import { ForwardRefComponent } from "../utils/polymorphic.js";
 import React from "react";
 
 //#region src/Flash/Flash.d.ts
+/**
+ * @deprecated Use `Banner` instead. If migration is not yet possible, import `Flash` from `@primer/react/deprecated`.
+ */
 type FlashProps = React.ComponentPropsWithoutRef<'div'> & {
   className?: string;
   variant?: 'default' | 'warning' | 'success' | 'danger';
   full?: boolean;
 };
+/**
+ * @deprecated Use `Banner` instead. If migration is not yet possible, import `Flash` from `@primer/react/deprecated`.
+ */
 declare const Flash: ForwardRefComponent<"div", FlashProps>;
 //#endregion
 export { FlashProps, Flash as default };

package/dist/Flash/Flash.js

@@ -4,6 +4,12 @@ import { clsx } from "clsx";
 import { jsx } from "react/jsx-runtime";
 import React from "react";
 //#region src/Flash/Flash.tsx
+/**
+* @deprecated Use `Banner` instead. If migration is not yet possible, import `Flash` from `@primer/react/deprecated`.
+*/
+/**
+* @deprecated Use `Banner` instead. If migration is not yet possible, import `Flash` from `@primer/react/deprecated`.
+*/
 const Flash = /*#__PURE__*/ React.forwardRef(function Flash(t0, ref) {
 	const $ = c(15);
 	let className;

package/dist/deprecated/index.d.ts

@@ -3,6 +3,7 @@ import { ItemProps } from "./ActionList/Item.js";
 import { GroupedListProps, ItemInput, ListProps } from "./ActionList/List.js";
 import { ActionList } from "./ActionList/index.js";
 import Octicon, { OcticonProps } from "../Octicon/Octicon.js";
+import Flash, { FlashProps } from "../Flash/Flash.js";
 import { ActionMenu, ActionMenuProps } from "./ActionMenu.js";
 import FilteredSearch, { FilteredSearchProps } from "./FilteredSearch/FilteredSearch.js";
 import _default$2, { UnderlineNavLinkProps, UnderlineNavProps } from "./UnderlineNav/UnderlineNav.js";
@@ -10,4 +11,4 @@ import _default, { DialogHeaderProps, DialogProps } from "./DialogV1/Dialog.js";
 import Pagehead, { PageheadProps } from "../Pagehead/Pagehead.js";
 import _default$1, { TabNavLinkProps, TabNavProps } from "../TabNav/TabNav.js";
 import Tooltip, { TooltipProps } from "../Tooltip/Tooltip.js";
-export { ActionList, type GroupProps as ActionListGroupProps, type GroupedListProps as ActionListGroupedListProps, type ItemInput as ActionListItemInput, type ItemProps as ActionListItemProps, type ListProps as ActionListProps, ActionMenu, type ActionMenuProps, _default as Dialog, type DialogHeaderProps, type DialogProps, FilteredSearch, type FilteredSearchProps, Octicon, type OcticonProps, Pagehead, type PageheadProps, _default$1 as TabNav, type TabNavLinkProps, type TabNavProps, Tooltip, type TooltipProps, _default$2 as UnderlineNav, type UnderlineNavLinkProps, type UnderlineNavProps };
+export { ActionList, type GroupProps as ActionListGroupProps, type GroupedListProps as ActionListGroupedListProps, type ItemInput as ActionListItemInput, type ItemProps as ActionListItemProps, type ListProps as ActionListProps, ActionMenu, type ActionMenuProps, _default as Dialog, type DialogHeaderProps, type DialogProps, FilteredSearch, type FilteredSearchProps, Flash, type FlashProps, Octicon, type OcticonProps, Pagehead, type PageheadProps, _default$1 as TabNav, type TabNavLinkProps, type TabNavProps, Tooltip, type TooltipProps, _default$2 as UnderlineNav, type UnderlineNavLinkProps, type UnderlineNavProps };

package/dist/deprecated/index.js

@@ -1,5 +1,6 @@
 "use client";
 import Octicon from "../Octicon/Octicon.js";
+import Flash from "../Flash/Flash.js";
 import { ActionList } from "./ActionList/index.js";
 import { ActionMenu } from "./ActionMenu.js";
 import FilteredSearch from "./FilteredSearch/FilteredSearch.js";
@@ -17,4 +18,4 @@ import Tooltip from "../Tooltip/Tooltip.js";
 *  example: import {FormGroup} from '@primer/react/deprecated
 */
 //#endregion
-export { ActionList, ActionMenu, Dialog_default as Dialog, FilteredSearch, Octicon, Pagehead, TabNav_default as TabNav, Tooltip, UnderlineNav_default as UnderlineNav };
+export { ActionList, ActionMenu, Dialog_default as Dialog, FilteredSearch, Flash, Octicon, Pagehead, TabNav_default as TabNav, Tooltip, UnderlineNav_default as UnderlineNav };

package/dist/experimental/Tabs/Tabs.js

@@ -1,4 +1,5 @@
 import useIsomorphicLayoutEffect from "../../utils/useIsomorphicLayoutEffect.js";
+import { useFeatureFlag } from "../../FeatureFlags/useFeatureFlag.js";
 import { useControllableState } from "../../hooks/useControllableState.js";
 import { TabsContext } from "./TabsContext.js";
 import { c } from "react-compiler-runtime";
@@ -13,11 +14,13 @@ import React, { useId } from "react";
 * The `Tab`, `TabList`, and `TabPanel` components are provided for convenience to showcase the API & implementation.
 */
 function Tabs(props) {
-	var _props$id, _props$defaultValue;
-	const $ = c(13);
+	var _props$id, _props$activationMode, _props$defaultValue;
+	const $ = c(16);
 	const { children, onValueChange } = props;
 	const generatedId = useId();
 	const groupId = (_props$id = props.id) !== null && _props$id !== void 0 ? _props$id : generatedId;
+	const controlledApiEnabled = useFeatureFlag("primer_react_underline_panels_controlled");
+	const activationMode = controlledApiEnabled ? (_props$activationMode = props.activationMode) !== null && _props$activationMode !== void 0 ? _props$activationMode : "automatic" : "automatic";
 	const t0 = (_props$defaultValue = props.defaultValue) !== null && _props$defaultValue !== void 0 ? _props$defaultValue : props.value;
 	let t1;
 	if ($[0] !== props.value || $[1] !== t0) {
@@ -31,49 +34,60 @@ function Tabs(props) {
 		$[2] = t1;
 	} else t1 = $[2];
 	const [selectedValue, setSelectedValue] = useControllableState(t1);
+	const [focusedValue, setFocusedValue] = React.useState();
 	const savedOnValueChange = React.useRef(onValueChange);
 	let t2;
-	if ($[3] !== groupId || $[4] !== selectedValue || $[5] !== setSelectedValue) {
+	if ($[3] !== activationMode || $[4] !== controlledApiEnabled || $[5] !== focusedValue || $[6] !== groupId || $[7] !== selectedValue || $[8] !== setSelectedValue) {
 		t2 = {
 			groupId,
 			selectedValue,
+			activationMode,
+			focusedValue,
 			selectTab(value) {
 				var _savedOnValueChange$c;
+				setFocusedValue(void 0);
+				if (controlledApiEnabled && value === selectedValue) return;
 				setSelectedValue(value);
 				(_savedOnValueChange$c = savedOnValueChange.current) === null || _savedOnValueChange$c === void 0 || _savedOnValueChange$c.call(savedOnValueChange, { value });
+			},
+			focusTab(value_0) {
+				setFocusedValue(value_0);
 			}
 		};
-		$[3] = groupId;
-		$[4] = selectedValue;
-		$[5] = setSelectedValue;
-		$[6] = t2;
-	} else t2 = $[6];
+		$[3] = activationMode;
+		$[4] = controlledApiEnabled;
+		$[5] = focusedValue;
+		$[6] = groupId;
+		$[7] = selectedValue;
+		$[8] = setSelectedValue;
+		$[9] = t2;
+	} else t2 = $[9];
 	const contextValue = t2;
 	let t3;
 	let t4;
-	if ($[7] !== onValueChange) {
+	if ($[10] !== onValueChange) {
 		t3 = () => {
 			savedOnValueChange.current = onValueChange;
 		};
 		t4 = [onValueChange];
-		$[7] = onValueChange;
-		$[8] = t3;
-		$[9] = t4;
+		$[10] = onValueChange;
+		$[11] = t3;
+		$[12] = t4;
 	} else {
-		t3 = $[8];
-		t4 = $[9];
+		t3 = $[11];
+		t4 = $[12];
 	}
 	useIsomorphicLayoutEffect(t3, t4);
 	let t5;
-	if ($[10] !== children || $[11] !== contextValue) {
+	if ($[13] !== children || $[14] !== contextValue) {
 		t5 = /*#__PURE__*/ jsx(TabsContext.Provider, {
 			value: contextValue,
 			children
 		});
-		$[10] = children;
-		$[11] = contextValue;
-		$[12] = t5;
-	} else t5 = $[12];
+		$[13] = children;
+		$[14] = contextValue;
+		$[15] = t5;
+	} else t5 = $[15];
 	return t5;
 }
 //#endregion

package/dist/experimental/Tabs/types.d.ts

@@ -51,6 +51,12 @@ type CommonTabsProps = {
    * unique id is generated automatically.
    */
   id?: string;
+  /**
+   * `'automatic'` (default) selects on focus, so Arrow/Home/End keys select immediately. `'manual'`
+   * only moves focus; selection commits on Enter/Space/click. Prefer `'manual'` when displaying a
+   * panel is not instant (e.g. it triggers a network request).
+   */
+  activationMode?: 'automatic' | 'manual';
 };
 type TabsProps = PropsWithChildren<(ControlledTabsProps | UncontrolledTabsProps) & CommonTabsProps>;
 type Label = {

package/dist/experimental/Tabs/useTab.js

@@ -12,6 +12,7 @@ function useTab(props) {
 	const selected = tabs.selectedValue === value;
 	const id = `${tabs.groupId}-tab-${value}`;
 	const panelId = `${tabs.groupId}-panel-${value}`;
+	const isTabStop = tabs.activationMode === "manual" && tabs.focusedValue !== void 0 ? tabs.focusedValue === value : selected;
 	let t0;
 	if ($[0] !== tabs || $[1] !== value) {
 		t0 = function onKeyDown(event) {
@@ -37,6 +38,10 @@ function useTab(props) {
 	let t2;
 	if ($[7] !== disabled || $[8] !== selected || $[9] !== tabs || $[10] !== value) {
 		t2 = function onFocus() {
+			if (tabs.activationMode === "manual") {
+				if (!disabled) tabs.focusTab(value);
+				return;
+			}
 			if (!selected && !disabled) tabs.selectTab(value);
 		};
 		$[7] = disabled;
@@ -47,7 +52,7 @@ function useTab(props) {
 	} else t2 = $[11];
 	const onFocus = t2;
 	const t3 = disabled ? true : void 0;
-	const t4 = selected ? 0 : -1;
+	const t4 = isTabStop ? 0 : -1;
 	let t5;
 	if ($[12] !== id || $[13] !== onFocus || $[14] !== onKeyDown || $[15] !== onMouseDown || $[16] !== panelId || $[17] !== selected || $[18] !== t3 || $[19] !== t4) {
 		t5 = { tabProps: {

package/dist/experimental/Tabs/useTabList.js

@@ -5,20 +5,29 @@ import { c } from "react-compiler-runtime";
 import { useRef } from "react";
 //#region src/experimental/Tabs/useTabList.ts
 function useTabList(props) {
-	const $ = c(9);
+	const $ = c(10);
 	const { "aria-label": ariaLabel, "aria-labelledby": ariaLabelledby, "aria-orientation": ariaOrientation } = props;
 	const mergedRefEnabled = useFeatureFlag("primer_react_merged_forwarded_refs");
+	const controlledApiEnabled = useFeatureFlag("primer_react_underline_panels_controlled");
 	const tabListRef = useRef(null);
 	const mergedRef = useMergedRefs(tabListRef, props.ref);
 	const providedOrCreatedRef = useProvidedRefOrCreate(props.ref);
 	const readRef = mergedRefEnabled ? tabListRef : providedOrCreatedRef;
 	const appliedRef = mergedRefEnabled ? mergedRef : providedOrCreatedRef;
 	let t0;
-	if ($[0] !== ariaOrientation || $[1] !== readRef) {
+	if ($[0] !== ariaOrientation || $[1] !== controlledApiEnabled || $[2] !== readRef) {
 		t0 = (event) => {
 			const { current: tablist } = readRef;
 			if (tablist === null) return;
 			const tabs = getFocusableTabs(tablist);
+			const getCurrentIndex = () => {
+				if (controlledApiEnabled) {
+					const activeElement = tablist.ownerDocument.activeElement;
+					const focusedIndex = activeElement instanceof HTMLElement ? tabs.indexOf(activeElement) : -1;
+					if (focusedIndex !== -1) return focusedIndex;
+				}
+				return tabs.findIndex(_temp);
+			};
 			const isVertical = ariaOrientation === "vertical";
 			const nextKey = isVertical ? "ArrowDown" : "ArrowRight";
 			const prevKey = isVertical ? "ArrowUp" : "ArrowLeft";
@@ -27,13 +36,13 @@ function useTabList(props) {
 				event.stopPropagation();
 			}
 			if (event.key === nextKey) {
-				const selectedTabIndex = tabs.findIndex(_temp);
-				if (selectedTabIndex === -1) return;
-				tabs[(selectedTabIndex + 1) % tabs.length].focus();
+				const currentTabIndex = getCurrentIndex();
+				if (currentTabIndex === -1) return;
+				tabs[(currentTabIndex + 1) % tabs.length].focus();
 			} else if (event.key === prevKey) {
-				const selectedTabIndex_0 = tabs.findIndex(_temp2);
-				if (selectedTabIndex_0 === -1) return;
-				tabs[(tabs.length + selectedTabIndex_0 - 1) % tabs.length].focus();
+				const currentTabIndex_0 = getCurrentIndex();
+				if (currentTabIndex_0 === -1) return;
+				tabs[(tabs.length + currentTabIndex_0 - 1) % tabs.length].focus();
 			} else if (event.key === "Home") {
 				if (tabs[0]) tabs[0].focus();
 			} else if (event.key === "End") {
@@ -41,13 +50,14 @@ function useTabList(props) {
 			}
 		};
 		$[0] = ariaOrientation;
-		$[1] = readRef;
-		$[2] = t0;
-	} else t0 = $[2];
+		$[1] = controlledApiEnabled;
+		$[2] = readRef;
+		$[3] = t0;
+	} else t0 = $[3];
 	const onKeyDown = t0;
 	const t1 = ariaOrientation !== null && ariaOrientation !== void 0 ? ariaOrientation : "horizontal";
 	let t2;
-	if ($[3] !== appliedRef || $[4] !== ariaLabel || $[5] !== ariaLabelledby || $[6] !== onKeyDown || $[7] !== t1) {
+	if ($[4] !== appliedRef || $[5] !== ariaLabel || $[6] !== ariaLabelledby || $[7] !== onKeyDown || $[8] !== t1) {
 		t2 = { tabListProps: {
 			ref: appliedRef,
 			"aria-label": ariaLabel,
@@ -56,18 +66,15 @@ function useTabList(props) {
 			role: "tablist",
 			onKeyDown
 		} };
-		$[3] = appliedRef;
-		$[4] = ariaLabel;
-		$[5] = ariaLabelledby;
-		$[6] = onKeyDown;
-		$[7] = t1;
-		$[8] = t2;
-	} else t2 = $[8];
+		$[4] = appliedRef;
+		$[5] = ariaLabel;
+		$[6] = ariaLabelledby;
+		$[7] = onKeyDown;
+		$[8] = t1;
+		$[9] = t2;
+	} else t2 = $[9];
 	return t2;
 }
-function _temp2(tab_0) {
-	return tab_0.getAttribute("aria-selected") === "true";
-}
 function _temp(tab) {
 	return tab.getAttribute("aria-selected") === "true";
 }

package/dist/experimental/UnderlinePanels/UnderlinePanels.d.ts

@@ -16,6 +16,31 @@ type UnderlinePanelsProps = {
    * ID of the element containing the name for the tab list
    */
   'aria-labelledby'?: React.AriaAttributes['aria-labelledby'];
+  /**
+   * The value of the selected tab, keyed to each `UnderlinePanels.Tab`/`UnderlinePanels.Panel`
+   * `value`. Provide this (with `onChange`) for a controlled component where the selected tab is
+   * the single source of truth.
+   */
+  value?: string;
+  /**
+   * The value of the tab that should be selected by default, keyed to each tab's `value`. Use this
+   * for an uncontrolled component. Cannot be combined with `value`.
+   */
+  defaultValue?: string;
+  /**
+   * Fires whenever the selected tab changes, for every selection method including arrow keys.
+   * Unlike `UnderlinePanels.Tab`'s `onSelect`, which only fires on click and Enter/Space.
+   */
+  onChange?: ({
+    value
+  }: {
+    value: string;
+  }) => void;
+  /**
+   * `'automatic'` (default) selects on focus/arrow keys; `'manual'` only moves focus until
+   * Enter/Space/click. Prefer `'manual'` when displaying a panel is not instant.
+   */
+  activationMode?: 'automatic' | 'manual';
   /**
    * Custom string to use when generating the IDs of tabs and `aria-labelledby` for the panels
    */
@@ -34,6 +59,12 @@ type UnderlinePanelsProps = {
   as?: React.ElementType;
 };
 type TabProps = PropsWithChildren<{
+  /**
+   * A value that uniquely identifies this tab, paired with the `UnderlinePanels.Panel` of the same
+   * `value`. Provide this to use domain values (e.g. `'branch'`) with the container's controlled
+   * `value`/`onChange` API. When omitted, tabs and panels are paired by their DOM order.
+   */
+  value?: string;
   /**
    * Whether this is the selected tab
    */
@@ -51,7 +82,13 @@ type TabProps = PropsWithChildren<{
    */
   icon?: FC<IconProps>;
 }>;
-type PanelProps = React.HTMLAttributes<HTMLDivElement>;
+type PanelProps = React.HTMLAttributes<HTMLDivElement> & {
+  /**
+   * A value that uniquely identifies this panel, paired with the `UnderlinePanels.Tab` of the same
+   * `value`. When omitted, tabs and panels are paired by their DOM order.
+   */
+  value?: string;
+};
 declare const _default: React.FC<UnderlinePanelsProps> & SlotMarker & {
   Panel: FCWithSlotMarker<PanelProps>;
   Tab: FCWithSlotMarker<TabProps>;

package/dist/experimental/UnderlinePanels/UnderlinePanels.js

@@ -1,7 +1,9 @@
 import useIsomorphicLayoutEffect from "../../utils/useIsomorphicLayoutEffect.js";
 import { useResizeObserver } from "../../hooks/useResizeObserver.js";
 import { useId as useId$1 } from "../../hooks/useId.js";
+import { warning } from "../../utils/warning.js";
 import { isSlot } from "../../utils/is-slot.js";
+import { useFeatureFlag } from "../../FeatureFlags/useFeatureFlag.js";
 import { invariant } from "../../utils/invariant.js";
 import { UnderlineItem, UnderlineItemList, UnderlineWrapper } from "../../internal/components/UnderlineTabbedInterface.js";
 import UnderlinePanels_module_css_default from "./UnderlinePanels.module.css.js";
@@ -17,43 +19,78 @@ const UnderlinePanelsContext = /*#__PURE__*/ createContext({
 	iconsVisible: true,
 	loadingCounters: void 0
 });
-const UnderlinePanels = ({ "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, children, loadingCounters, className, ...props }) => {
+const UnderlinePanels = ({ "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, children, loadingCounters, className, value: valueProp, defaultValue: defaultValueProp, onChange: onChangeProp, activationMode = "automatic", ...props }) => {
+	var _tabValues$;
+	const controlledApiEnabled = useFeatureFlag("primer_react_underline_panels_controlled");
+	const controlledValue = controlledApiEnabled ? valueProp : void 0;
+	const defaultValue = controlledApiEnabled ? defaultValueProp : void 0;
+	const onChange = controlledApiEnabled ? onChangeProp : void 0;
 	const [iconsVisible, setIconsVisible] = useState(true);
 	const wrapperRef = useRef(null);
 	const listRef = useRef(null);
 	const parentId = useId$1(props.id);
-	const [tabs, tabPanels, tabsHaveIcons, selectedFromProps] = useMemo(() => {
+	const [tabs, tabPanels, tabsHaveIcons, selectedFromProps, tabValues, panelValues] = useMemo(() => {
 		let tabIndex = 0;
 		let panelIndex = 0;
 		const childrenWithProps = Children.map(children, (child) => {
-			if (/*#__PURE__*/ isValidElement(child) && (child.type === Tab || isSlot(child, Tab))) return /*#__PURE__*/ cloneElement(child, { value: `${tabIndex++}` });
-			if (/*#__PURE__*/ isValidElement(child) && (child.type === Panel || isSlot(child, Panel))) return /*#__PURE__*/ cloneElement(child, { value: `${panelIndex++}` });
+			if (/*#__PURE__*/ isValidElement(child) && (child.type === Tab || isSlot(child, Tab))) {
+				var _ref;
+				const value = (_ref = controlledApiEnabled ? child.props.value : void 0) !== null && _ref !== void 0 ? _ref : `${tabIndex}`;
+				tabIndex++;
+				return /*#__PURE__*/ cloneElement(child, { value });
+			}
+			if (/*#__PURE__*/ isValidElement(child) && (child.type === Panel || isSlot(child, Panel))) {
+				var _ref2;
+				const value = (_ref2 = controlledApiEnabled ? child.props.value : void 0) !== null && _ref2 !== void 0 ? _ref2 : `${panelIndex}`;
+				panelIndex++;
+				return /*#__PURE__*/ cloneElement(child, { value });
+			}
 			return child;
 		});
 		const tabs = [];
 		const tabPanels = [];
+		const tabValues = [];
+		const panelValues = [];
 		let selectedFromProps;
 		for (const child of Children.toArray(childrenWithProps)) {
 			if (!/*#__PURE__*/ isValidElement(child)) continue;
 			if (child.type === Tab || isSlot(child, Tab)) {
+				const value = child.props.value;
+				if (value !== void 0) tabValues.push(value);
 				const ariaSelected = child.props["aria-selected"];
-				if (ariaSelected === true || ariaSelected === "true") selectedFromProps = `${tabs.length}`;
+				if (ariaSelected === true || ariaSelected === "true") selectedFromProps = value;
 				tabs.push(child);
-			} else if (child.type === Panel || isSlot(child, Panel)) tabPanels.push(child);
+			} else if (child.type === Panel || isSlot(child, Panel)) {
+				const value = child.props.value;
+				if (value !== void 0) panelValues.push(value);
+				tabPanels.push(child);
+			}
 		}
 		return [
 			tabs,
 			tabPanels,
 			tabs.some((tab) => /*#__PURE__*/ React.isValidElement(tab) && tab.props.icon),
-			selectedFromProps
+			selectedFromProps,
+			tabValues,
+			panelValues
 		];
-	}, [children]);
-	const [selectedValue, setSelectedValue] = useState(() => selectedFromProps !== null && selectedFromProps !== void 0 ? selectedFromProps : "0");
+	}, [children, controlledApiEnabled]);
+	const isControlled = controlledValue !== void 0;
+	const [uncontrolledValue, setUncontrolledValue] = useState(() => {
+		var _ref3;
+		return (_ref3 = defaultValue !== null && defaultValue !== void 0 ? defaultValue : selectedFromProps) !== null && _ref3 !== void 0 ? _ref3 : "0";
+	});
 	const [prevSelectedFromProps, setPrevSelectedFromProps] = useState(selectedFromProps);
-	if (selectedFromProps !== prevSelectedFromProps) {
+	if (!isControlled && selectedFromProps !== prevSelectedFromProps) {
 		setPrevSelectedFromProps(selectedFromProps);
-		if (selectedFromProps !== void 0 && selectedFromProps !== selectedValue) setSelectedValue(selectedFromProps);
+		if (selectedFromProps !== void 0 && selectedFromProps !== uncontrolledValue) setUncontrolledValue(selectedFromProps);
 	}
+	const selectedValue = isControlled ? controlledValue : uncontrolledValue;
+	const effectiveValue = tabValues.includes(selectedValue) ? selectedValue : (_tabValues$ = tabValues[0]) !== null && _tabValues$ !== void 0 ? _tabValues$ : selectedValue;
+	const handleValueChange = (value) => {
+		if (!isControlled) setUncontrolledValue(value);
+		onChange === null || onChange === void 0 || onChange({ value });
+	};
 	const { tabListProps } = useTabList({
 		"aria-label": ariaLabel,
 		"aria-labelledby": ariaLabelledBy,
@@ -78,17 +115,31 @@ const UnderlinePanels = ({ "aria-label": ariaLabel, "aria-labelledby": ariaLabel
 		const wrapperWidth = resizeObserverEntries[0].contentRect.width;
 		setIconsVisible(wrapperWidth > listWidthRef.current);
 	}, wrapperRef, []);
-	!(tabs.filter((tab) => {
-		const ariaSelected = /*#__PURE__*/ React.isValidElement(tab) && tab.props["aria-selected"];
-		return ariaSelected === true || ariaSelected === "true";
-	}).length <= 1) && invariant(false, "Only one tab can be selected at a time.");
-	!(tabs.length === tabPanels.length) && invariant(false, `The number of tabs and panels must be equal. Counted ${tabs.length} tabs and ${tabPanels.length} panels.`);
+	{
+		const selectedTabs = tabs.filter((tab) => {
+			const ariaSelected = /*#__PURE__*/ React.isValidElement(tab) && tab.props["aria-selected"];
+			return ariaSelected === true || ariaSelected === "true";
+		});
+		!(selectedTabs.length <= 1) && invariant(false, "Only one tab can be selected at a time.");
+		!(tabs.length === tabPanels.length) && invariant(false, `The number of tabs and panels must be equal. Counted ${tabs.length} tabs and ${tabPanels.length} panels.`);
+		const duplicateTabValue = tabValues.find((value, index) => tabValues.indexOf(value) !== index);
+		!(duplicateTabValue === void 0) && invariant(false, `Every tab must have a unique \`value\`. Found duplicate "${duplicateTabValue}".`);
+		const duplicatePanelValue = panelValues.find((value, index) => panelValues.indexOf(value) !== index);
+		!(duplicatePanelValue === void 0) && invariant(false, `Every panel must have a unique \`value\`. Found duplicate "${duplicatePanelValue}".`);
+		const unmatchedTabValue = tabValues.find((value) => !panelValues.includes(value));
+		!(unmatchedTabValue === void 0) && invariant(false, `Tab with \`value\` "${unmatchedTabValue}" has no matching panel. Give a \`UnderlinePanels.Panel\` the same \`value\`.`);
+		warning(isControlled && selectedTabs.length > 0, "UnderlinePanels: do not combine the controlled `value` prop with `aria-selected` on a tab. `value` takes precedence; use `value`/`onChange` (or `defaultValue`) to drive selection.");
+		warning(controlledValue !== void 0 && defaultValue !== void 0, "UnderlinePanels: do not combine the controlled `value` prop with `defaultValue`. `value` takes precedence; use one or the other.");
+		const providedValue = controlledValue !== null && controlledValue !== void 0 ? controlledValue : defaultValue;
+		warning(providedValue !== void 0 && tabValues.length > 0 && !tabValues.includes(providedValue), `UnderlinePanels: the selected value "${providedValue}" does not match any tab, so the first tab is selected instead. Provide a \`value\`/\`defaultValue\` that matches a \`UnderlinePanels.Tab\` \`value\`.`);
+	}
 	return /*#__PURE__*/ jsx(UnderlinePanelsContext.Provider, {
 		value: contextValue,
 		children: /*#__PURE__*/ jsxs(Tabs, {
 			id: parentId,
-			value: selectedValue,
-			onValueChange: ({ value }) => setSelectedValue(value),
+			value: effectiveValue,
+			activationMode,
+			onValueChange: ({ value }) => handleValueChange(value),
 			children: [/*#__PURE__*/ jsx(UnderlineWrapper, {
 				ref: wrapperRef,
 				"data-icons-visible": iconsVisible,

package/generated/components.json

@@ -3394,39 +3394,39 @@
       "source": "https://github.com/primer/react/tree/main/packages/react/src/Flash",
       "id": "flash",
       "name": "Flash",
-      "status": "alpha",
+      "status": "deprecated",
       "a11yReviewed": "2025-01-08",
       "stories": [
         {
-          "id": "components-flash--default",
+          "id": "deprecated-components-flash--default",
           "code": "() => <Flash>Default</Flash>"
         },
         {
-          "id": "components-flash-features--success",
+          "id": "deprecated-components-flash-features--success",
           "code": "() => (\n  <Flash\n    variant=\"success\"\n    style={{\n      display: 'grid',\n      gridTemplateColumns: 'min-content 1fr minmax(0, auto)',\n      gridTemplateAreas: `'visual message actions'`,\n    }}\n  >\n    <div className={classes.Visual}>\n      <CheckCircleIcon aria-label=\"Success\" />\n    </div>\n    <div className={classes.Message}>Success</div>\n  </Flash>\n)"
         },
         {
-          "id": "components-flash-features--danger",
+          "id": "deprecated-components-flash-features--danger",
           "code": "() => (\n  <Flash\n    variant=\"danger\"\n    style={{\n      display: 'grid',\n      gridTemplateColumns: 'min-content 1fr minmax(0, auto)',\n      gridTemplateAreas: `'visual message actions'`,\n    }}\n  >\n    <div className={classes.Visual}>\n      <InfoIcon aria-label=\"Danger\" />\n    </div>\n    <div className={classes.Message}>Danger</div>\n  </Flash>\n)"
         },
         {
-          "id": "components-flash-features--warning",
+          "id": "deprecated-components-flash-features--warning",
           "code": "() => (\n  <Flash\n    variant=\"warning\"\n    style={{\n      display: 'grid',\n      gridTemplateColumns: 'min-content 1fr minmax(0, auto)',\n      gridTemplateAreas: `'visual message actions'`,\n    }}\n  >\n    <div className={classes.Visual}>\n      <AlertIcon aria-label=\"Warning\" />\n    </div>\n    <div className={classes.Message}>Warning</div>\n  </Flash>\n)"
         },
         {
-          "id": "components-flash-features--full",
+          "id": "deprecated-components-flash-features--full",
           "code": "() => (\n  <Flash\n    full\n    style={{\n      display: 'grid',\n      gridTemplateColumns: 'min-content 1fr minmax(0, auto)',\n      gridTemplateAreas: `'visual message actions'`,\n    }}\n  >\n    <div className={classes.Visual}>\n      <InfoIcon aria-label=\"Info\" />\n    </div>\n    <div className={classes.Message}>Full</div>\n  </Flash>\n)"
         },
         {
-          "id": "components-flash-features--with-icon-and-action",
+          "id": "deprecated-components-flash-features--with-icon-and-action",
           "code": "() => (\n  <Flash className={classes.WithIconAndAction}>\n    <div className={classes.Visual}>\n      <InfoIcon aria-label=\"Info\" />\n    </div>\n    <div className={classes.Message}>\n      This is a flash message with an icon and an action.\n      <Link href=\"/\"> Learn more.</Link>\n    </div>\n    <div className={classes.ActionsResponsive}>\n      <Button>Join waitlist</Button>\n    </div>\n  </Flash>\n)"
         },
         {
-          "id": "components-flash-features--with-icon-action-dismiss",
+          "id": "deprecated-components-flash-features--with-icon-action-dismiss",
           "code": "() => (\n  <Flash className={classes.WithIconActionDismiss}>\n    <div className={classes.Visual}>\n      <InfoIcon aria-label=\"Info\" />\n    </div>\n    <div className={classes.Message}>\n      This is a flash message with an icon and an action.\n      <Link href=\"/\"> Learn more.</Link>\n    </div>\n    <div className={classes.ActionsResponsive}>\n      <Button>Join waitlist</Button>\n    </div>\n    <div className={classes.Close}>\n      <IconButton variant=\"invisible\" icon={XIcon} aria-label=\"Dismiss\" />\n    </div>\n  </Flash>\n)"
         }
       ],
-      "importPath": "@primer/react",
+      "importPath": "@primer/react/deprecated",
       "props": [
         {
           "name": "full",
@@ -9605,6 +9605,22 @@
         {
           "id": "experimental-components-underlinepanels-features--with-icons-hidden-on-narrow-screen",
           "code": "() => (\n  <UnderlinePanels aria-label=\"Tabs with icons\">\n    <UnderlinePanels.Tab icon={CodeIcon}>Tab 1</UnderlinePanels.Tab>\n    <UnderlinePanels.Tab icon={EyeIcon}>Tab 2</UnderlinePanels.Tab>\n    <UnderlinePanels.Tab icon={GitPullRequestIcon}>Tab 3</UnderlinePanels.Tab>\n    <UnderlinePanels.Tab icon={CommentDiscussionIcon}>\n      Tab 4\n    </UnderlinePanels.Tab>\n    <UnderlinePanels.Tab icon={PlayIcon}>Tab 5</UnderlinePanels.Tab>\n    <UnderlinePanels.Tab icon={ProjectIcon}>Tab 6</UnderlinePanels.Tab>\n    <UnderlinePanels.Tab icon={GraphIcon}>Tab 7</UnderlinePanels.Tab>\n    <UnderlinePanels.Tab icon={GearIcon}>Tab 8</UnderlinePanels.Tab>\n    <UnderlinePanels.Tab icon={ShieldLockIcon}>Tab 9</UnderlinePanels.Tab>\n    <UnderlinePanels.Panel>Panel 1</UnderlinePanels.Panel>\n    <UnderlinePanels.Panel>Panel 2</UnderlinePanels.Panel>\n    <UnderlinePanels.Panel>Panel 3</UnderlinePanels.Panel>\n    <UnderlinePanels.Panel>Panel 4</UnderlinePanels.Panel>\n    <UnderlinePanels.Panel>Panel 5</UnderlinePanels.Panel>\n    <UnderlinePanels.Panel>Panel 6</UnderlinePanels.Panel>\n    <UnderlinePanels.Panel>Panel 7</UnderlinePanels.Panel>\n    <UnderlinePanels.Panel>Panel 8</UnderlinePanels.Panel>\n    <UnderlinePanels.Panel>Panel 9</UnderlinePanels.Panel>\n  </UnderlinePanels>\n)"
+        },
+        {
+          "id": "experimental-components-underlinepanels-features--controlled",
+          "code": "() => {\n  const [refType, setRefType] = useState('branch')\n  return (\n    <>\n      <FlagState />\n      <UnderlinePanels\n        aria-label=\"Ref type\"\n        value={refType}\n        onChange={({ value }) => {\n          action('onChange')({\n            value,\n          })\n          setRefType(value)\n        }}\n      >\n        <UnderlinePanels.Tab value=\"branch\" icon={GitBranchIcon}>\n          Branches\n        </UnderlinePanels.Tab>\n        <UnderlinePanels.Tab value=\"tag\" icon={TagIcon}>\n          Tags\n        </UnderlinePanels.Tab>\n        <UnderlinePanels.Panel value=\"branch\">\n          Find or create a branch…\n        </UnderlinePanels.Panel>\n        <UnderlinePanels.Panel value=\"tag\">\n          Search or create a new tag…\n        </UnderlinePanels.Panel>\n      </UnderlinePanels>\n      <p>\n        Selected ref type: <strong>{refType}</strong>\n      </p>\n    </>\n  )\n}"
+        },
+        {
+          "id": "experimental-components-underlinepanels-features--uncontrolled",
+          "code": "() => (\n  <>\n    <FlagState />\n    <UnderlinePanels\n      aria-label=\"Ref type\"\n      defaultValue=\"tag\"\n      onChange={({ value }) => {\n        action('onChange')({\n          value,\n        })\n      }}\n    >\n      <UnderlinePanels.Tab value=\"branch\">Branches</UnderlinePanels.Tab>\n      <UnderlinePanels.Tab value=\"tag\">Tags</UnderlinePanels.Tab>\n      <UnderlinePanels.Panel value=\"branch\">\n        Find or create a branch…\n      </UnderlinePanels.Panel>\n      <UnderlinePanels.Panel value=\"tag\">\n        Search or create a new tag…\n      </UnderlinePanels.Panel>\n    </UnderlinePanels>\n  </>\n)"
+        },
+        {
+          "id": "experimental-components-underlinepanels-features--manual-activation",
+          "code": "() => {\n  const [refType, setRefType] = useState('branch')\n  return (\n    <>\n      <FlagState />\n      <p>\n        With <code>activationMode=&quot;manual&quot;</code>, arrow keys only\n        move focus; press Enter or Space (or click) to commit selection. Prefer\n        this when switching tabs triggers async work like a fetch.\n      </p>\n      <UnderlinePanels\n        aria-label=\"Ref type\"\n        value={refType}\n        activationMode=\"manual\"\n        onChange={({ value }) => {\n          action('onChange')({\n            value,\n          })\n          setRefType(value)\n        }}\n      >\n        <UnderlinePanels.Tab value=\"branch\">Branches</UnderlinePanels.Tab>\n        <UnderlinePanels.Tab value=\"tag\">Tags</UnderlinePanels.Tab>\n        <UnderlinePanels.Panel value=\"branch\">\n          Find or create a branch…\n        </UnderlinePanels.Panel>\n        <UnderlinePanels.Panel value=\"tag\">\n          Search or create a new tag…\n        </UnderlinePanels.Panel>\n      </UnderlinePanels>\n    </>\n  )\n}"
+        },
+        {
+          "id": "experimental-components-underlinepanels-features--in-overlay",
+          "code": "() => {\n  const [open, setOpen] = useState(false)\n  const [refType, setRefType] = useState('branch')\n  return (\n    <>\n      <FlagState />\n      <AnchoredOverlay\n        open={open}\n        onOpen={() => setOpen(true)}\n        onClose={() => setOpen(false)}\n        renderAnchor={(props) => <Button {...props}>Select ref type</Button>}\n        overlayProps={{\n          role: 'dialog',\n          'aria-modal': true,\n          'aria-label': 'Select a ref type',\n          style: {\n            width: '320px',\n          },\n        }}\n        focusZoneSettings={{\n          disabled: true,\n        }}\n      >\n        <UnderlinePanels\n          aria-label=\"Ref type\"\n          value={refType}\n          onChange={({ value }) => {\n            action('onChange')({\n              value,\n            })\n            setRefType(value)\n          }}\n        >\n          <UnderlinePanels.Tab value=\"branch\">Branches</UnderlinePanels.Tab>\n          <UnderlinePanels.Tab value=\"tag\">Tags</UnderlinePanels.Tab>\n          <UnderlinePanels.Panel value=\"branch\">\n            Find or create a branch…\n          </UnderlinePanels.Panel>\n          <UnderlinePanels.Panel value=\"tag\">\n            Search or create a new tag…\n          </UnderlinePanels.Panel>\n        </UnderlinePanels>\n      </AnchoredOverlay>\n    </>\n  )\n}"
         }
       ],
       "importPath": "@primer/react/experimental",
@@ -9621,6 +9637,30 @@
           "defaultValue": "",
           "description": "ID of the element containing the name for the tab list"
         },
+        {
+          "name": "value",
+          "type": "string",
+          "defaultValue": "",
+          "description": "The value of the selected tab, keyed to each `UnderlinePanels.Tab`/`UnderlinePanels.Panel` `value`. Provide this (with `onChange`) for a controlled component where the selected tab is the single source of truth. Requires the `primer_react_underline_panels_controlled` feature flag."
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "defaultValue": "",
+          "description": "The value of the tab selected by default, for an uncontrolled component. Cannot be combined with `value`."
+        },
+        {
+          "name": "onChange",
+          "type": "({value}: {value: string}) => void",
+          "defaultValue": "",
+          "description": "Callback fired whenever the selected tab changes, for every selection method — pointer, Enter/Space, and Arrow/Home/End keys. Unlike `UnderlinePanels.Tab`'s `onSelect` (which only fires on click and Enter/Space), this makes the selected value usable as a single source of truth for data-driven tabs."
+        },
+        {
+          "name": "activationMode",
+          "type": "'automatic' | 'manual'",
+          "defaultValue": "'automatic'",
+          "description": "Controls how tabs are activated with the keyboard. `'automatic'` selects on focus (Arrow/Home/End select immediately); `'manual'` moves focus only and commits selection on Enter, Space, or click. Prefer `'manual'` when displaying a panel is not instant (e.g. it triggers a network request). Requires the `primer_react_underline_panels_controlled` feature flag."
+        },
         {
           "name": "children",
           "type": "Array<UnderlinePanels.Tab | UnderlinePanels.Panel>",
@@ -9651,6 +9691,12 @@
         {
           "name": "UnderlinePanels.Tab",
           "props": [
+            {
+              "name": "value",
+              "type": "string",
+              "defaultValue": "",
+              "description": "A value that uniquely identifies this tab, paired with the `UnderlinePanels.Panel` of the same `value`. Provide this to use domain values (e.g. `'branch'`) with the container's controlled `value`/`onChange` API. When omitted, tabs and panels are paired by DOM order."
+            },
             {
               "name": "aria-selected",
               "type": "| boolean | 'true' | 'false'",
@@ -9661,7 +9707,7 @@
               "name": "onSelect",
               "type": "(event) => void",
               "defaultValue": "",
-              "description": "The handler that gets called when the tab is selected"
+              "description": "The handler that gets called when the tab is selected. Note: this fires only on click and Enter/Space — not on arrow-key navigation. For a callback that fires for every selection method, use the container's `onChange` prop instead."
             },
             {
               "name": "counter",
@@ -9679,7 +9725,14 @@
         },
         {
           "name": "UnderlinePanels.Panel",
-          "props": [],
+          "props": [
+            {
+              "name": "value",
+              "type": "string",
+              "defaultValue": "",
+              "description": "A value that uniquely identifies this panel, paired with the `UnderlinePanels.Tab` of the same `value`. When omitted, tabs and panels are paired by DOM order."
+            }
+          ],
           "passthrough": {
             "element": "div",
             "url": "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#Attributes"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@primer/react",
   "type": "module",
-  "version": "38.37.0-rc.0b6dd7e38",
+  "version": "38.37.0-rc.1789e76c6",
   "description": "An implementation of GitHub's Primer Design System using React",
   "main": "./dist/index.js",
   "module": "./dist/index.js",