@primer/react 0.0.0-20260715193046 → 0.0.0-20260716164750

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. package/CHANGELOG.md +15 -3
  2. package/dist/ActionBar/ActionBar.js +1 -1
  3. package/dist/ActionList/Group.js +1 -1
  4. package/dist/ActionList/List.js +14 -20
  5. package/dist/AnchoredOverlay/AnchoredOverlay.js +3 -9
  6. package/dist/Autocomplete/AutocompleteInput.js +7 -10
  7. package/dist/ButtonGroup/ButtonGroup.js +8 -15
  8. package/dist/Checkbox/Checkbox.js +9 -16
  9. package/dist/Dialog/Dialog.js +5 -12
  10. package/dist/FeatureFlags/DefaultFeatureFlags.js +1 -2
  11. package/dist/FilteredActionList/FilteredActionList.js +20 -31
  12. package/dist/FilteredActionList/FilteredActionListInput.d.ts +1 -1
  13. package/dist/Overlay/Overlay.js +1 -1
  14. package/dist/PageHeader/PageHeader.js +21 -30
  15. package/dist/PageLayout/DragHandle.d.ts +45 -0
  16. package/dist/PageLayout/DragHandle.js +224 -0
  17. package/dist/PageLayout/PageLayout.js +53 -247
  18. package/dist/PageLayout/index.d.ts +3 -1
  19. package/dist/PageLayout/usePaneWidth.d.ts +63 -1
  20. package/dist/PageLayout/usePaneWidth.js +52 -36
  21. package/dist/SelectPanel/SelectPanel.js +1 -1
  22. package/dist/TextInput/TextInput.js +6 -13
  23. package/dist/TooltipV2/Tooltip.js +11 -18
  24. package/dist/experimental/Tabs/types.d.ts +2 -2
  25. package/dist/experimental/Tabs/useTabList.js +10 -18
  26. package/dist/experimental/index.js +3 -3
  27. package/dist/hooks/useAnchoredPosition.js +14 -1
  28. package/dist/hooks/useMergedRefs.d.ts +4 -4
  29. package/dist/hooks/useMergedRefs.js +5 -8
  30. package/dist/hooks/useProvidedRefOrCreate.d.ts +10 -7
  31. package/dist/hooks/useProvidedRefOrCreate.js +10 -7
  32. package/dist/index.d.ts +3 -1
  33. package/dist/index.js +3 -1
  34. package/package.json +1 -1
@@ -1,7 +1,5 @@
1
- import { useMergedRefs } from "../hooks/useMergedRefs.js";
2
1
  import { useProvidedRefOrCreate } from "../hooks/useProvidedRefOrCreate.js";
3
2
  import { AriaStatus } from "../live-region/AriaStatus.js";
4
- import { useFeatureFlag } from "../FeatureFlags/useFeatureFlag.js";
5
3
  import Text_default from "../Text/Text.js";
6
4
  import _VisuallyHidden_module_css_default from "../_VisuallyHidden.module.css.js";
7
5
  import VisuallyHidden from "../_VisuallyHidden.js";
@@ -13,19 +11,14 @@ import UnstyledTextInput from "../internal/components/UnstyledTextInput.js";
13
11
  import { getCharacterCountState } from "../utils/character-counter.js";
14
12
  import { clsx } from "clsx";
15
13
  import { Fragment, jsx, jsxs } from "react/jsx-runtime";
16
- import React, { useCallback, useId, useRef, useState } from "react";
14
+ import React, { useCallback, useId, useState } from "react";
17
15
  import { isValidElementType } from "react-is";
18
16
  import { AlertFillIcon } from "@primer/octicons-react";
19
17
  //#region src/TextInput/TextInput.tsx
20
18
  const TextInput = /*#__PURE__*/ React.forwardRef(({ icon: IconComponent, leadingVisual: LeadingVisual, trailingVisual: TrailingVisual, trailingAction, block, className, contrast, disabled, loading, loaderPosition = "auto", loaderText = "Loading", monospace, validationStatus, size: sizeProp, onFocus, onBlur, variant: variantProp, width: widthProp, minWidth: minWidthProp, maxWidth: maxWidthProp, type = "text", required, characterLimit, onChange, value, defaultValue, "data-component": dataComponent, ...inputProps }, ref) => {
21
19
  var _counter$isOverLimit;
22
20
  const [isInputFocused, setIsInputFocused] = useState(false);
23
- const mergedRefEnabled = useFeatureFlag("primer_react_merged_forwarded_refs");
24
- const inputRef = useRef(null);
25
- const mergedRef = useMergedRefs(inputRef, ref);
26
- const providedOrCreatedRef = useProvidedRefOrCreate(ref);
27
- const readRef = mergedRefEnabled ? inputRef : providedOrCreatedRef;
28
- const appliedRef = mergedRefEnabled ? mergedRef : providedOrCreatedRef;
21
+ const inputRef = useProvidedRefOrCreate(ref);
29
22
  const isControlled = value !== void 0;
30
23
  const [uncontrolledLength, setUncontrolledLength] = useState(() => defaultValue !== void 0 ? String(defaultValue).length : 0);
31
24
  const currentLength = isControlled ? String(value).length : uncontrolledLength;
@@ -36,9 +29,9 @@ const TextInput = /*#__PURE__*/ React.forwardRef(({ icon: IconComponent, leading
36
29
  const showTrailingLoadingIndicator = loading && (loaderPosition === "trailing" || Boolean(loaderPosition === "auto" && !LeadingVisual));
37
30
  const isSegmentedInputType = type === "date" || type === "time" || type === "datetime-local";
38
31
  const focusInput = (e) => {
39
- if (e.target !== readRef.current || !isSegmentedInputType) {
40
- var _readRef$current;
41
- (_readRef$current = readRef.current) === null || _readRef$current === void 0 || _readRef$current.focus();
32
+ if (e.target !== inputRef.current || !isSegmentedInputType) {
33
+ var _inputRef$current;
34
+ (_inputRef$current = inputRef.current) === null || _inputRef$current === void 0 || _inputRef$current.focus();
42
35
  }
43
36
  };
44
37
  const leadingVisualId = useId();
@@ -95,7 +88,7 @@ const TextInput = /*#__PURE__*/ React.forwardRef(({ icon: IconComponent, leading
95
88
  children: typeof LeadingVisual !== "string" && isValidElementType(LeadingVisual) ? /*#__PURE__*/ jsx(LeadingVisual, {}) : LeadingVisual
96
89
  }),
97
90
  /*#__PURE__*/ jsx(UnstyledTextInput, {
98
- ref: appliedRef,
91
+ ref: inputRef,
99
92
  disabled,
100
93
  onFocus: handleInputFocus,
101
94
  onBlur: handleInputBlur,
@@ -1,9 +1,7 @@
1
- import { useMergedRefs } from "../hooks/useMergedRefs.js";
2
1
  import { useProvidedRefOrCreate } from "../hooks/useProvidedRefOrCreate.js";
3
2
  import { useOnEscapePress } from "../hooks/useOnEscapePress.js";
4
3
  import { useId as useId$1 } from "../hooks/useId.js";
5
4
  import { warning } from "../utils/warning.js";
6
- import { useFeatureFlag } from "../FeatureFlags/useFeatureFlag.js";
7
5
  import { invariant } from "../utils/invariant.js";
8
6
  import Tooltip_module_css_default from "./Tooltip.module.css.js";
9
7
  import VisuallyHidden from "../_VisuallyHidden.js";
@@ -82,12 +80,7 @@ const emptyKeybindingHints = [];
82
80
  const Tooltip = /*#__PURE__*/ React.forwardRef(({ direction = "s", text, type = "description", children, id, className, keybindingHint = emptyKeybindingHints, delay = "short", _privateDisableTooltip = false, ...rest }, forwardedRef) => {
83
81
  const tooltipId = useId$1(id);
84
82
  const child = Children.only(children);
85
- const mergedRefEnabled = useFeatureFlag("primer_react_merged_forwarded_refs");
86
- const triggerRef = useRef(null);
87
- const mergedTriggerRef = useMergedRefs(triggerRef, forwardedRef);
88
- const providedOrCreatedRef = useProvidedRefOrCreate(forwardedRef);
89
- const readTriggerRef = mergedRefEnabled ? triggerRef : providedOrCreatedRef;
90
- const appliedTriggerRef = mergedRefEnabled ? mergedTriggerRef : providedOrCreatedRef;
83
+ const triggerRef = useProvidedRefOrCreate(forwardedRef);
91
84
  const tooltipElRef = useRef(null);
92
85
  const [calculatedDirection, setCalculatedDirection] = useState(direction);
93
86
  const [isPopoverOpen, setIsPopoverOpen] = useState(false);
@@ -95,9 +88,9 @@ const Tooltip = /*#__PURE__*/ React.forwardRef(({ direction = "s", text, type =
95
88
  const { safeSetTimeout, safeClearTimeout } = useSafeTimeout();
96
89
  const openTooltip = () => {
97
90
  try {
98
- if (tooltipElRef.current && readTriggerRef.current && tooltipElRef.current.hasAttribute("popover") && !tooltipElRef.current.matches(":popover-open") && !_privateDisableTooltip) {
91
+ if (tooltipElRef.current && triggerRef.current && tooltipElRef.current.hasAttribute("popover") && !tooltipElRef.current.matches(":popover-open") && !_privateDisableTooltip) {
99
92
  const tooltip = tooltipElRef.current;
100
- const trigger = readTriggerRef.current;
93
+ const trigger = triggerRef.current;
101
94
  tooltip.showPopover();
102
95
  setIsPopoverOpen(true);
103
96
  const { top, left, anchorAlign, anchorSide } = getAnchoredPosition(tooltip, trigger, {
@@ -119,7 +112,7 @@ const Tooltip = /*#__PURE__*/ React.forwardRef(({ direction = "s", text, type =
119
112
  openTimeoutRef.current = null;
120
113
  }
121
114
  try {
122
- if (tooltipElRef.current && readTriggerRef.current && tooltipElRef.current.hasAttribute("popover") && tooltipElRef.current.matches(":popover-open")) {
115
+ if (tooltipElRef.current && triggerRef.current && tooltipElRef.current.hasAttribute("popover") && tooltipElRef.current.matches(":popover-open")) {
123
116
  tooltipElRef.current.hidePopover();
124
117
  setIsPopoverOpen(false);
125
118
  } else setIsPopoverOpen(false);
@@ -129,16 +122,16 @@ const Tooltip = /*#__PURE__*/ React.forwardRef(({ direction = "s", text, type =
129
122
  };
130
123
  const value = useMemo(() => ({ tooltipId }), [tooltipId]);
131
124
  useEffect(() => {
132
- if (!tooltipElRef.current || !readTriggerRef.current) return;
133
- const isTriggerInteractive = isInteractive(readTriggerRef.current);
134
- const triggerChildren = readTriggerRef.current.childNodes;
125
+ if (!tooltipElRef.current || !triggerRef.current) return;
126
+ const isTriggerInteractive = isInteractive(triggerRef.current);
127
+ const triggerChildren = triggerRef.current.childNodes;
135
128
  const hasInteractiveDescendant = Array.from(triggerChildren).some((child) => {
136
129
  return child instanceof HTMLElement && isInteractive(child) || Array.from(child.childNodes).some((grandChild) => grandChild instanceof HTMLElement && isInteractive(grandChild));
137
130
  });
138
131
  !(isTriggerInteractive || hasInteractiveDescendant) && invariant(false, "The `Tooltip` component expects a single React element that contains interactive content. Consider using a `<button>` or equivalent interactive element instead.");
139
132
  if (type === "label") {
140
- const hasAriaLabel = readTriggerRef.current.hasAttribute("aria-label");
141
- const hasAriaLabelInChildren = Array.from(readTriggerRef.current.childNodes).some((child) => child instanceof HTMLElement && child.hasAttribute("aria-label"));
133
+ const hasAriaLabel = triggerRef.current.hasAttribute("aria-label");
134
+ const hasAriaLabelInChildren = Array.from(triggerRef.current.childNodes).some((child) => child instanceof HTMLElement && child.hasAttribute("aria-label"));
142
135
  warning(hasAriaLabel || hasAriaLabelInChildren, "The label type `Tooltip` is going to be used here to label the trigger element. Please remove the aria-label from the trigger element.");
143
136
  }
144
137
  if (typeof window !== "undefined") {
@@ -147,7 +140,7 @@ const Tooltip = /*#__PURE__*/ React.forwardRef(({ direction = "s", text, type =
147
140
  tooltipElRef.current.setAttribute("popover", "auto");
148
141
  }, [
149
142
  tooltipElRef,
150
- readTriggerRef,
143
+ triggerRef,
151
144
  direction,
152
145
  type
153
146
  ]);
@@ -164,7 +157,7 @@ const Tooltip = /*#__PURE__*/ React.forwardRef(({ direction = "s", text, type =
164
157
  return /*#__PURE__*/ jsx(TooltipContext.Provider, {
165
158
  value,
166
159
  children: /*#__PURE__*/ jsxs(Fragment, { children: [/*#__PURE__*/ React.isValidElement(child) && /*#__PURE__*/ React.cloneElement(child, {
167
- ref: appliedTriggerRef,
160
+ ref: triggerRef,
168
161
  "aria-describedby": (() => {
169
162
  if (type !== "description") return child.props["aria-describedby"];
170
163
  const existingDescribedBy = child.props["aria-describedby"];
@@ -73,7 +73,7 @@ type TabPanelProps = {
73
73
  value: string;
74
74
  };
75
75
  type TabListHookProps<T extends HTMLElement> = TabListProps & {
76
- /** Optional ref to use for the tablist. If none is provided, one will be generated automatically */ref?: React.Ref<T | null>;
76
+ /** Optional ref to use for the tablist. If none is provided, one will be generated automatically */ref?: React.RefObject<T>;
77
77
  };
78
78
  type TabListHookResult<T extends HTMLElement> = {
79
79
  /** Props to be spread onto the tablist element */tabListProps: {
@@ -81,7 +81,7 @@ type TabListHookResult<T extends HTMLElement> = {
81
81
  'aria-orientation': AriaAttributes['aria-orientation'];
82
82
  'aria-label': AriaAttributes['aria-label'];
83
83
  'aria-labelledby': AriaAttributes['aria-labelledby'];
84
- ref: React.Ref<T | null>;
84
+ ref: React.RefObject<T | null>;
85
85
  role: 'tablist';
86
86
  };
87
87
  };
@@ -1,22 +1,14 @@
1
- import { useMergedRefs } from "../../hooks/useMergedRefs.js";
2
1
  import { useProvidedRefOrCreate } from "../../hooks/useProvidedRefOrCreate.js";
3
- import { useFeatureFlag } from "../../FeatureFlags/useFeatureFlag.js";
4
2
  import { c } from "react-compiler-runtime";
5
- import { useRef } from "react";
6
3
  //#region src/experimental/Tabs/useTabList.ts
7
4
  function useTabList(props) {
8
5
  const $ = c(9);
9
6
  const { "aria-label": ariaLabel, "aria-labelledby": ariaLabelledby, "aria-orientation": ariaOrientation } = props;
10
- const mergedRefEnabled = useFeatureFlag("primer_react_merged_forwarded_refs");
11
- const tabListRef = useRef(null);
12
- const mergedRef = useMergedRefs(tabListRef, props.ref);
13
- const providedOrCreatedRef = useProvidedRefOrCreate(props.ref);
14
- const readRef = mergedRefEnabled ? tabListRef : providedOrCreatedRef;
15
- const appliedRef = mergedRefEnabled ? mergedRef : providedOrCreatedRef;
7
+ const ref = useProvidedRefOrCreate(props.ref);
16
8
  let t0;
17
- if ($[0] !== ariaOrientation || $[1] !== readRef) {
9
+ if ($[0] !== ariaOrientation || $[1] !== ref) {
18
10
  t0 = (event) => {
19
- const { current: tablist } = readRef;
11
+ const { current: tablist } = ref;
20
12
  if (tablist === null) return;
21
13
  const tabs = getFocusableTabs(tablist);
22
14
  const isVertical = ariaOrientation === "vertical";
@@ -41,25 +33,25 @@ function useTabList(props) {
41
33
  }
42
34
  };
43
35
  $[0] = ariaOrientation;
44
- $[1] = readRef;
36
+ $[1] = ref;
45
37
  $[2] = t0;
46
38
  } else t0 = $[2];
47
39
  const onKeyDown = t0;
48
40
  const t1 = ariaOrientation !== null && ariaOrientation !== void 0 ? ariaOrientation : "horizontal";
49
41
  let t2;
50
- if ($[3] !== appliedRef || $[4] !== ariaLabel || $[5] !== ariaLabelledby || $[6] !== onKeyDown || $[7] !== t1) {
42
+ if ($[3] !== ariaLabel || $[4] !== ariaLabelledby || $[5] !== onKeyDown || $[6] !== ref || $[7] !== t1) {
51
43
  t2 = { tabListProps: {
52
- ref: appliedRef,
44
+ ref,
53
45
  "aria-label": ariaLabel,
54
46
  "aria-labelledby": ariaLabelledby,
55
47
  "aria-orientation": t1,
56
48
  role: "tablist",
57
49
  onKeyDown
58
50
  } };
59
- $[3] = appliedRef;
60
- $[4] = ariaLabel;
61
- $[5] = ariaLabelledby;
62
- $[6] = onKeyDown;
51
+ $[3] = ariaLabel;
52
+ $[4] = ariaLabelledby;
53
+ $[5] = onKeyDown;
54
+ $[6] = ref;
63
55
  $[7] = t1;
64
56
  $[8] = t2;
65
57
  } else t2 = $[8];
@@ -3,9 +3,6 @@ import { Announce } from "../live-region/Announce.js";
3
3
  import { AriaAlert } from "../live-region/AriaAlert.js";
4
4
  import { AriaStatus } from "../live-region/AriaStatus.js";
5
5
  import { ButtonBase } from "../Button/ButtonBase.js";
6
- import { DefaultFeatureFlags } from "../FeatureFlags/DefaultFeatureFlags.js";
7
- import { FeatureFlags } from "../FeatureFlags/FeatureFlags.js";
8
- import { useFeatureFlag } from "../FeatureFlags/useFeatureFlag.js";
9
6
  import { KeybindingHint } from "../KeybindingHint/KeybindingHint.js";
10
7
  import { getAccessibleKeybindingHintString } from "../KeybindingHint/utils.js";
11
8
  import { Tooltip } from "../TooltipV2/Tooltip.js";
@@ -13,6 +10,9 @@ import { useSlots } from "../hooks/useSlots.js";
13
10
  import { useOverflow } from "../hooks/useOverflow.js";
14
11
  import { ScrollableRegion } from "../ScrollableRegion/ScrollableRegion.js";
15
12
  import { Dialog } from "../Dialog/Dialog.js";
13
+ import { DefaultFeatureFlags } from "../FeatureFlags/DefaultFeatureFlags.js";
14
+ import { FeatureFlags } from "../FeatureFlags/FeatureFlags.js";
15
+ import { useFeatureFlag } from "../FeatureFlags/useFeatureFlag.js";
16
16
  import { Stack } from "../Stack/index.js";
17
17
  import { SkeletonBox } from "../Skeleton/SkeletonBox.js";
18
18
  import { FilteredActionListLoadingTypes } from "../FilteredActionList/constants.js";
@@ -106,6 +106,10 @@ function useAnchoredPosition(settings, dependencies = []) {
106
106
  }, [updatePosition]);
107
107
  useResizeObserver(updatePosition, void 0, [], enabled);
108
108
  useResizeObserver(updatePosition, floatingElementRef, [], enabled);
109
+ const scrollAncestorsCacheRef = React.useRef({
110
+ anchor: null,
111
+ scrollables: []
112
+ });
109
113
  React.useEffect(() => {
110
114
  if (!enabled) return;
111
115
  const anchorEl = anchorElementRef.current;
@@ -118,7 +122,16 @@ function useAnchoredPosition(settings, dependencies = []) {
118
122
  updatePosition();
119
123
  });
120
124
  };
121
- const scrollables = getScrollableAncestors(anchorEl);
125
+ const cache = scrollAncestorsCacheRef.current;
126
+ let scrollables;
127
+ if (cache.anchor === anchorEl) scrollables = cache.scrollables;
128
+ else {
129
+ scrollables = getScrollableAncestors(anchorEl);
130
+ scrollAncestorsCacheRef.current = {
131
+ anchor: anchorEl,
132
+ scrollables
133
+ };
134
+ }
122
135
  for (const scrollable of scrollables) scrollable.addEventListener("scroll", handleScroll);
123
136
  return () => {
124
137
  for (const scrollable of scrollables) scrollable.removeEventListener("scroll", handleScroll);
@@ -17,18 +17,18 @@ import { ForwardedRef, Ref } from "react";
17
17
  * // React 18
18
18
  * const Example = forwardRef<HTMLButtonElement, {}>((props, forwardedRef) => {
19
19
  * const ref = useRef<HTMLButtonElement>(null)
20
- * const mergedRef = useMergedRefs(forwardedRef, ref)
20
+ * const combinedRef = useMergedRefs(forwardedRef, ref)
21
21
  *
22
- * return <button ref={mergedRef} />
22
+ * return <button ref={combinedRef} />
23
23
  * })
24
24
  *
25
25
  * @example
26
26
  * // React 19
27
27
  * const Example = ({ref: externalRef}: {ref?: Ref<HTMLButtonElement>}) => {
28
28
  * const ref = useRef<HTMLButtonElement>(null)
29
- * const mergedRef = useMergedRefs(externalRef, ref)
29
+ * const combinedRef = useMergedRefs(externalRef, ref)
30
30
  *
31
- * return <button ref={mergedRef} />
31
+ * return <button ref={combinedRef} />
32
32
  * }
33
33
  */
34
34
  declare function useMergedRefs<T>(refA: Ref$1<T | null>, refB: Ref$1<T | null>): (value: T | null) => (() => void) | undefined;
@@ -1,9 +1,7 @@
1
1
  import { isExperimentalReactVersion, reactMajorVersion } from "../utils/environment.js";
2
2
  import { c } from "react-compiler-runtime";
3
- import { version } from "react";
3
+ import "react";
4
4
  //#region src/hooks/useMergedRefs.ts
5
- var _version$split$;
6
- const majorReactVersion = parseInt((_version$split$ = version.split(".")[0]) !== null && _version$split$ !== void 0 ? _version$split$ : "18", 10);
7
5
  /**
8
6
  * Cleanup functions for refs were introduced in React 19. For feature detection,
9
7
  * we look to see if current version of React is >= 19 or if it is an
@@ -28,18 +26,18 @@ const supportsRefCleanup = reactMajorVersion >= 19 || isExperimentalReactVersion
28
26
  * // React 18
29
27
  * const Example = forwardRef<HTMLButtonElement, {}>((props, forwardedRef) => {
30
28
  * const ref = useRef<HTMLButtonElement>(null)
31
- * const mergedRef = useMergedRefs(forwardedRef, ref)
29
+ * const combinedRef = useMergedRefs(forwardedRef, ref)
32
30
  *
33
- * return <button ref={mergedRef} />
31
+ * return <button ref={combinedRef} />
34
32
  * })
35
33
  *
36
34
  * @example
37
35
  * // React 19
38
36
  * const Example = ({ref: externalRef}: {ref?: Ref<HTMLButtonElement>}) => {
39
37
  * const ref = useRef<HTMLButtonElement>(null)
40
- * const mergedRef = useMergedRefs(externalRef, ref)
38
+ * const combinedRef = useMergedRefs(externalRef, ref)
41
39
  *
42
- * return <button ref={mergedRef} />
40
+ * return <button ref={combinedRef} />
43
41
  * }
44
42
  */
45
43
  function useMergedRefs(refA, refB) {
@@ -50,7 +48,6 @@ function useMergedRefs(refA, refB) {
50
48
  const cleanupA = setRef(refA, value);
51
49
  const cleanupB = setRef(refB, value);
52
50
  if (!supportsRefCleanup) return;
53
- if (majorReactVersion <= 18) return;
54
51
  return () => {
55
52
  if (cleanupA) cleanupA();
56
53
  else setRef(refA, null);
@@ -9,14 +9,17 @@ import React from "react";
9
9
  * @param providedRef The ref to use - if undefined, will use the ref from a call to React.useRef
10
10
  * @type TRef The type of the RefObject which should be created.
11
11
  *
12
- * @note This hook is overly restrictive in that it forces the provided ref to be a ref object rather than a callback.
13
- * In particular, it should **not** be used to merge internal refs with forwarded refs. For this, use
14
- * {@linkcode useMergedRefs} instead.
12
+ * @deprecated This hook is incompatible with forwarded callback refs. Prefer `useMergedRefs` with an internally
13
+ * created ref instead.
15
14
  *
16
- * The primary valid use case for this hook is for when the consumer is using the provided ref to point to an external
17
- * element, like an externally rendered anchor. This is 'backwards' from forwarded refs with respect to data flow; the
18
- * consumer is passing a reference to an external element, rather than passing a handle to obtain a reference to an
19
- * internal element.
15
+ * ```diff
16
+ * - const ref = useProvidedRefOrCreate(forwardedRef as RefObject<...>)
17
+ * + const ref = useRef(null)
18
+ * + const mergedRef = useMergedRefs(forwardedRef, ref)
19
+ *
20
+ * - return <div ref={ref} />
21
+ * + return <div ref={mergedRef} />
22
+ * ```
20
23
  */
21
24
  declare function useProvidedRefOrCreate<TRef>(providedRef?: React.RefObject<TRef | null>): React.RefObject<TRef | null>;
22
25
  //#endregion
@@ -8,14 +8,17 @@ import React from "react";
8
8
  * @param providedRef The ref to use - if undefined, will use the ref from a call to React.useRef
9
9
  * @type TRef The type of the RefObject which should be created.
10
10
  *
11
- * @note This hook is overly restrictive in that it forces the provided ref to be a ref object rather than a callback.
12
- * In particular, it should **not** be used to merge internal refs with forwarded refs. For this, use
13
- * {@linkcode useMergedRefs} instead.
11
+ * @deprecated This hook is incompatible with forwarded callback refs. Prefer `useMergedRefs` with an internally
12
+ * created ref instead.
14
13
  *
15
- * The primary valid use case for this hook is for when the consumer is using the provided ref to point to an external
16
- * element, like an externally rendered anchor. This is 'backwards' from forwarded refs with respect to data flow; the
17
- * consumer is passing a reference to an external element, rather than passing a handle to obtain a reference to an
18
- * internal element.
14
+ * ```diff
15
+ * - const ref = useProvidedRefOrCreate(forwardedRef as RefObject<...>)
16
+ * + const ref = useRef(null)
17
+ * + const mergedRef = useMergedRefs(forwardedRef, ref)
18
+ *
19
+ * - return <div ref={ref} />
20
+ * + return <div ref={mergedRef} />
21
+ * ```
19
22
  */
20
23
  function useProvidedRefOrCreate(providedRef) {
21
24
  const createdRef = React.useRef(null);
package/dist/index.d.ts CHANGED
@@ -16,7 +16,9 @@ import { LinkButton, LinkButtonProps } from "./Button/LinkButton.js";
16
16
  import { ButtonComponent } from "./Button/Button.js";
17
17
  import { ButtonBase } from "./Button/ButtonBase.js";
18
18
  import { ResponsiveValue, useResponsiveValue } from "./hooks/useResponsiveValue.js";
19
+ import { CustomWidthOptions, PaneWidth, PaneWidthValue, UsePaneWidthOptions, UsePaneWidthResult, defaultPaneWidth, usePaneWidth } from "./PageLayout/usePaneWidth.js";
19
20
  import { PageLayout, PageLayoutContentProps, PageLayoutFooterProps, PageLayoutHeaderProps, PageLayoutPaneProps, PageLayoutProps } from "./PageLayout/PageLayout.js";
21
+ import { DragHandle, DragHandleProps } from "./PageLayout/DragHandle.js";
20
22
  import { SplitPageLayout, SplitPageLayoutContentProps, SplitPageLayoutFooterProps, SplitPageLayoutHeaderProps, SplitPageLayoutPaneProps, SplitPageLayoutProps } from "./SplitPageLayout/SplitPageLayout.js";
21
23
  import useDetails from "./hooks/useDetails.js";
22
24
  import useSafeTimeout from "./hooks/useSafeTimeout.js";
@@ -117,4 +119,4 @@ import { ActionsProps, ChildrenPropTypes, PageHeader, PageHeaderProps, TitleArea
117
119
  import { SkeletonBox, SkeletonBoxProps } from "./Skeleton/SkeletonBox.js";
118
120
  import { ActionMenu, ActionMenuAnchorProps, ActionMenuButtonProps, ActionMenuProps } from "./ActionMenu/ActionMenu.js";
119
121
  import Overlay, { OverlayProps } from "./Overlay/Overlay.js";
120
- export { ActionBar, type ActionBarProps, ActionList, type ActionListDescriptionProps, type ActionListDividerProps, type ActionListGroupHeadingProps, type ActionListGroupHeadingTrailingActionProps, type ActionListGroupProps, type ActionListItemProps, type ActionListLeadingVisualProps, type ActionListLinkItemProps, type ActionListProps, type ActionListTrailingActionProps, type ActionListTrailingVisualProps, ActionMenu, type ActionMenuAnchorProps, type ActionMenuButtonProps, type ActionMenuProps, AnchoredOverlay, type AnchoredOverlayProps, type AnchoredPositionHookSettings, _default as Autocomplete, type AutocompleteInputProps, type AutocompleteMenuProps, type AutocompleteOverlayProps, Avatar, type AvatarProps, AvatarStack, type AvatarStackProps, Banner, type BannerProps, BaseStyles, type BaseStylesProps, _default$1 as BranchName, type BranchNameProps, Breadcrumb, type BreadcrumbItemProps, type BreadcrumbProps, _default$2 as Breadcrumbs, type BreadcrumbsItemProps, type BreadcrumbsProps, ButtonComponent as Button, ButtonBase, type ButtonBaseProps, ButtonGroup, type ButtonGroupProps, type ButtonProps, _default$3 as Checkbox, _default$4 as CheckboxGroup, type CheckboxGroupProps, type CheckboxProps, _default$5 as CircleBadge, type CircleBadgeIconProps, type CircleBadgeProps, ConfirmationDialog, type ConfirmationDialogProps, CounterLabel, type CounterLabelProps, Details, type DetailsProps, Dialog, type DialogButtonProps, type DialogHeaderProps, type DialogHeight, type DialogProps, type DialogWidth, type FCWithSlotMarker, Flash, type FlashProps, FocusKeys, type FocusTrapHookSettings, type FocusZoneHookSettings, _default$6 as FormControl, type FormControlCaptionProps, type Props as FormControlLabelProps, type FormControlProps, type FormControlValidationProps, _default$7 as Header, type HeaderItemProps, type HeaderLinkProps, type HeaderProps, Heading, type HeadingProps, IconButton, type IconButtonProps, IssueLabelToken, type IssueLabelTokenProps, Label, type LabelColorOptions, LabelGroup, type LabelGroupProps, type LabelProps, Link, LinkButton, type LinkButtonProps, type LinkProps, NavList, type NavListDividerProps, type NavListGroupHeadingProps, type NavListGroupProps, type NavListItemProps, type NavListLeadingVisualProps, type NavListProps, type NavListSubNavProps, type NavListTrailingVisualProps, Overlay, type OverlayProps, PageHeader, type ActionsProps as PageHeaderActionsProps, type ChildrenPropTypes as PageHeaderChildrenPropTypes, type PageHeaderProps, type TitleAreaProps as PageHeaderTitleAreaProps, type TitleProps as PageHeaderTitleProps, PageLayout, type PageLayoutContentProps, type PageLayoutFooterProps, type PageLayoutHeaderProps, type PageLayoutPaneProps, type PageLayoutProps, Pagination, type PaginationProps, _default$8 as Popover, type PopoverContentProps, type PopoverProps, Portal, PortalContext, type PortalProps, ProgressBar, type ProgressBarItemProps, type ProgressBarProps, _default$9 as Radio, _default$10 as RadioGroup, type RadioGroupProps, type RadioProps, RelativeTime, type RelativeTimeProps, type ResponsiveValue, SegmentedControl, type SegmentedControlButtonProps, type SegmentedControlIconButtonProps, type SegmentedControlProps, _default$11 as Select, SelectPanel, type GroupedListProps as SelectPanelGroupedListProps, type ItemInput as SelectPanelItemInput, type FilteredActionListItemProps as SelectPanelItemProps, type SelectPanelProps, type SelectProps, _default$12 as SideNav, type SideNavLinkProps, type SideNavProps, SkeletonBox, type SkeletonBoxProps, type SlotMarker, Spinner, type SpinnerProps, SplitPageLayout, type SplitPageLayoutContentProps, type SplitPageLayoutFooterProps, type SplitPageLayoutHeaderProps, type SplitPageLayoutPaneProps, type SplitPageLayoutProps, Stack, type StackItemProps, type StackProps, StateLabel, type StateLabelProps, _default$13 as SubNav, type SubNavLinkProps, type SubNavLinksProps, type SubNavProps, _default$14 as Text, _default$15 as TextInput, type TextInputActionProps, type TextInputProps, _default$16 as TextInputWithTokens, type TextInputWithTokensProps, type TextProps, _default$17 as Textarea, type TextareaProps, type ThemeColorPaths, ThemeProvider, type ThemeProviderProps, type ThemeShadowPaths, _default$18 as Timeline, type TimelineActionsProps, type TimelineAvatarProps, type TimelineBadgeProps, type TimelineBadgeVariant, type TimelineBodyProps, type TimelineBreakProps, type TimelineItemProps, type TimelineItemsProps, type TimelineProps, ToggleSwitch, type ToggleSwitchProps, Token, type TokenProps, Tooltip, type TooltipProps, type TouchOrMouseEvent, TreeView, type TreeViewErrorDialogProps, type TreeViewItemProps, type TreeViewProps, type TreeViewSubTreeProps, type TreeViewVisualProps, Truncate, type TruncateProps, UnderlineNav, type UnderlineNavItemProps, type UnderlineNavProps, VisuallyHidden, type VisuallyHiddenProps, type WithSlotMarker, asSlot, createComponent, isSlot, registerPortalRoot, theme, useAnchoredPosition, useColorSchemeVar, useConfirm, useDetails, useFocusTrap, useFocusZone, useFormControlForwardedProps, useId, useIsomorphicLayoutEffect, useMergedRefs, useOnEscapePress, useOnOutsideClick, useOpenAndCloseFocus, useOverlay, useProvidedRefOrCreate, useRefObjectAsForwardedRef, useResizeObserver, useResponsiveValue, useRovingTabIndex, useSafeTimeout, useSlots, useSyncedState, useTheme };
122
+ export { ActionBar, type ActionBarProps, ActionList, type ActionListDescriptionProps, type ActionListDividerProps, type ActionListGroupHeadingProps, type ActionListGroupHeadingTrailingActionProps, type ActionListGroupProps, type ActionListItemProps, type ActionListLeadingVisualProps, type ActionListLinkItemProps, type ActionListProps, type ActionListTrailingActionProps, type ActionListTrailingVisualProps, ActionMenu, type ActionMenuAnchorProps, type ActionMenuButtonProps, type ActionMenuProps, AnchoredOverlay, type AnchoredOverlayProps, type AnchoredPositionHookSettings, _default as Autocomplete, type AutocompleteInputProps, type AutocompleteMenuProps, type AutocompleteOverlayProps, Avatar, type AvatarProps, AvatarStack, type AvatarStackProps, Banner, type BannerProps, BaseStyles, type BaseStylesProps, _default$1 as BranchName, type BranchNameProps, Breadcrumb, type BreadcrumbItemProps, type BreadcrumbProps, _default$2 as Breadcrumbs, type BreadcrumbsItemProps, type BreadcrumbsProps, ButtonComponent as Button, ButtonBase, type ButtonBaseProps, ButtonGroup, type ButtonGroupProps, type ButtonProps, _default$3 as Checkbox, _default$4 as CheckboxGroup, type CheckboxGroupProps, type CheckboxProps, _default$5 as CircleBadge, type CircleBadgeIconProps, type CircleBadgeProps, ConfirmationDialog, type ConfirmationDialogProps, CounterLabel, type CounterLabelProps, type CustomWidthOptions, Details, type DetailsProps, Dialog, type DialogButtonProps, type DialogHeaderProps, type DialogHeight, type DialogProps, type DialogWidth, DragHandle, type DragHandleProps, type FCWithSlotMarker, Flash, type FlashProps, FocusKeys, type FocusTrapHookSettings, type FocusZoneHookSettings, _default$6 as FormControl, type FormControlCaptionProps, type Props as FormControlLabelProps, type FormControlProps, type FormControlValidationProps, _default$7 as Header, type HeaderItemProps, type HeaderLinkProps, type HeaderProps, Heading, type HeadingProps, IconButton, type IconButtonProps, IssueLabelToken, type IssueLabelTokenProps, Label, type LabelColorOptions, LabelGroup, type LabelGroupProps, type LabelProps, Link, LinkButton, type LinkButtonProps, type LinkProps, NavList, type NavListDividerProps, type NavListGroupHeadingProps, type NavListGroupProps, type NavListItemProps, type NavListLeadingVisualProps, type NavListProps, type NavListSubNavProps, type NavListTrailingVisualProps, Overlay, type OverlayProps, PageHeader, type ActionsProps as PageHeaderActionsProps, type ChildrenPropTypes as PageHeaderChildrenPropTypes, type PageHeaderProps, type TitleAreaProps as PageHeaderTitleAreaProps, type TitleProps as PageHeaderTitleProps, PageLayout, type PageLayoutContentProps, type PageLayoutFooterProps, type PageLayoutHeaderProps, type PageLayoutPaneProps, type PageLayoutProps, Pagination, type PaginationProps, type PaneWidth, type PaneWidthValue, _default$8 as Popover, type PopoverContentProps, type PopoverProps, Portal, PortalContext, type PortalProps, ProgressBar, type ProgressBarItemProps, type ProgressBarProps, _default$9 as Radio, _default$10 as RadioGroup, type RadioGroupProps, type RadioProps, RelativeTime, type RelativeTimeProps, type ResponsiveValue, SegmentedControl, type SegmentedControlButtonProps, type SegmentedControlIconButtonProps, type SegmentedControlProps, _default$11 as Select, SelectPanel, type GroupedListProps as SelectPanelGroupedListProps, type ItemInput as SelectPanelItemInput, type FilteredActionListItemProps as SelectPanelItemProps, type SelectPanelProps, type SelectProps, _default$12 as SideNav, type SideNavLinkProps, type SideNavProps, SkeletonBox, type SkeletonBoxProps, type SlotMarker, Spinner, type SpinnerProps, SplitPageLayout, type SplitPageLayoutContentProps, type SplitPageLayoutFooterProps, type SplitPageLayoutHeaderProps, type SplitPageLayoutPaneProps, type SplitPageLayoutProps, Stack, type StackItemProps, type StackProps, StateLabel, type StateLabelProps, _default$13 as SubNav, type SubNavLinkProps, type SubNavLinksProps, type SubNavProps, _default$14 as Text, _default$15 as TextInput, type TextInputActionProps, type TextInputProps, _default$16 as TextInputWithTokens, type TextInputWithTokensProps, type TextProps, _default$17 as Textarea, type TextareaProps, type ThemeColorPaths, ThemeProvider, type ThemeProviderProps, type ThemeShadowPaths, _default$18 as Timeline, type TimelineActionsProps, type TimelineAvatarProps, type TimelineBadgeProps, type TimelineBadgeVariant, type TimelineBodyProps, type TimelineBreakProps, type TimelineItemProps, type TimelineItemsProps, type TimelineProps, ToggleSwitch, type ToggleSwitchProps, Token, type TokenProps, Tooltip, type TooltipProps, type TouchOrMouseEvent, TreeView, type TreeViewErrorDialogProps, type TreeViewItemProps, type TreeViewProps, type TreeViewSubTreeProps, type TreeViewVisualProps, Truncate, type TruncateProps, UnderlineNav, type UnderlineNavItemProps, type UnderlineNavProps, type UsePaneWidthOptions, type UsePaneWidthResult, VisuallyHidden, type VisuallyHiddenProps, type WithSlotMarker, asSlot, createComponent, defaultPaneWidth, isSlot, registerPortalRoot, theme, useAnchoredPosition, useColorSchemeVar, useConfirm, useDetails, useFocusTrap, useFocusZone, useFormControlForwardedProps, useId, useIsomorphicLayoutEffect, useMergedRefs, useOnEscapePress, useOnOutsideClick, useOpenAndCloseFocus, useOverlay, usePaneWidth, useProvidedRefOrCreate, useRefObjectAsForwardedRef, useResizeObserver, useResponsiveValue, useRovingTabIndex, useSafeTimeout, useSlots, useSyncedState, useTheme };
package/dist/index.js CHANGED
@@ -27,6 +27,8 @@ import { ButtonComponent } from "./Button/Button.js";
27
27
  import { useResponsiveValue } from "./hooks/useResponsiveValue.js";
28
28
  import { isSlot } from "./utils/is-slot.js";
29
29
  import { useSlots } from "./hooks/useSlots.js";
30
+ import { defaultPaneWidth, usePaneWidth } from "./PageLayout/usePaneWidth.js";
31
+ import { DragHandle } from "./PageLayout/DragHandle.js";
30
32
  import { PageLayout } from "./PageLayout/PageLayout.js";
31
33
  import { SplitPageLayout } from "./SplitPageLayout/SplitPageLayout.js";
32
34
  import useDetails from "./hooks/useDetails.js";
@@ -92,4 +94,4 @@ import { TreeView } from "./TreeView/TreeView.js";
92
94
  import { UnderlineNav } from "./UnderlineNav/index.js";
93
95
  import { ActionBar } from "./ActionBar/index.js";
94
96
  import { PageHeader } from "./PageHeader/PageHeader.js";
95
- export { ActionBar, ActionList, ActionMenu, AnchoredOverlay, Autocomplete_default as Autocomplete, Avatar, AvatarStack, Banner, BaseStyles, BranchName_default as BranchName, Breadcrumb, Breadcrumbs_default as Breadcrumbs, ButtonComponent as Button, ButtonBase, ButtonGroup, Checkbox, CheckboxGroup_default as CheckboxGroup, CircleBadge_default as CircleBadge, ConfirmationDialog, CounterLabel, Details, Dialog, Flash, FocusKeys, FormControl_default as FormControl, Header_default as Header, Heading, IconButton, IssueLabelToken, Label_default as Label, LabelGroup, Link, LinkButton, NavList, Overlay, PageHeader, PageLayout, Pagination_default as Pagination, Popover_default as Popover, Portal_default as Portal, PortalContext, ProgressBar, Radio, RadioGroup_default as RadioGroup, RelativeTime, SegmentedControl, Select_default as Select, SelectPanel, SideNav_default as SideNav, SkeletonBox, Spinner, SplitPageLayout, Stack, StateLabel, SubNav_default as SubNav, Text_default as Text, TextInput_default as TextInput, TextInputWithTokens, Textarea, ThemeProvider, Timeline_default as Timeline, ToggleSwitch, Token, Tooltip, TreeView, Truncate, UnderlineNav, VisuallyHidden, asSlot, createComponent, isSlot, registerPortalRoot, theme, useAnchoredPosition, useColorSchemeVar, useConfirm, useDetails, useFocusTrap, useFocusZone, useFormControlForwardedProps, useId, useIsomorphicLayoutEffect, useMergedRefs, useOnEscapePress, useOnOutsideClick, useOpenAndCloseFocus, useOverlay, useProvidedRefOrCreate, useRefObjectAsForwardedRef, useResizeObserver, useResponsiveValue, useRovingTabIndex, useSafeTimeout, useSlots, useSyncedState, useTheme };
97
+ export { ActionBar, ActionList, ActionMenu, AnchoredOverlay, Autocomplete_default as Autocomplete, Avatar, AvatarStack, Banner, BaseStyles, BranchName_default as BranchName, Breadcrumb, Breadcrumbs_default as Breadcrumbs, ButtonComponent as Button, ButtonBase, ButtonGroup, Checkbox, CheckboxGroup_default as CheckboxGroup, CircleBadge_default as CircleBadge, ConfirmationDialog, CounterLabel, Details, Dialog, DragHandle, Flash, FocusKeys, FormControl_default as FormControl, Header_default as Header, Heading, IconButton, IssueLabelToken, Label_default as Label, LabelGroup, Link, LinkButton, NavList, Overlay, PageHeader, PageLayout, Pagination_default as Pagination, Popover_default as Popover, Portal_default as Portal, PortalContext, ProgressBar, Radio, RadioGroup_default as RadioGroup, RelativeTime, SegmentedControl, Select_default as Select, SelectPanel, SideNav_default as SideNav, SkeletonBox, Spinner, SplitPageLayout, Stack, StateLabel, SubNav_default as SubNav, Text_default as Text, TextInput_default as TextInput, TextInputWithTokens, Textarea, ThemeProvider, Timeline_default as Timeline, ToggleSwitch, Token, Tooltip, TreeView, Truncate, UnderlineNav, VisuallyHidden, asSlot, createComponent, defaultPaneWidth, isSlot, registerPortalRoot, theme, useAnchoredPosition, useColorSchemeVar, useConfirm, useDetails, useFocusTrap, useFocusZone, useFormControlForwardedProps, useId, useIsomorphicLayoutEffect, useMergedRefs, useOnEscapePress, useOnOutsideClick, useOpenAndCloseFocus, useOverlay, usePaneWidth, useProvidedRefOrCreate, useRefObjectAsForwardedRef, useResizeObserver, useResponsiveValue, useRovingTabIndex, useSafeTimeout, useSlots, useSyncedState, useTheme };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@primer/react",
3
3
  "type": "module",
4
- "version": "0.0.0-20260715193046",
4
+ "version": "0.0.0-20260716164750",
5
5
  "description": "An implementation of GitHub's Primer Design System using React",
6
6
  "main": "./dist/index.js",
7
7
  "module": "./dist/index.js",