feat(react-overflow): split and expose hooks for headless reuse (#36304)

Author: mainframev

change/@fluentui-react-overflow-7caf7721-7aaf-4793-9640-e9844c06d0d8.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Expose Overflow use/render/styles hooks, provider and context types for headless consumers",
+  "packageName": "@fluentui/react-overflow",
+  "email": "vgenaev@gmail.com",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-overflow/library/etc/react-overflow.api.md

@@ -4,11 +4,13 @@
 
 ```ts
 
-import type { OnUpdateOverflow } from '@fluentui/priority-overflow';
+import { OnUpdateItemVisibility } from '@fluentui/priority-overflow';
+import { OnUpdateOverflow } from '@fluentui/priority-overflow';
 import type { OverflowDividerEntry } from '@fluentui/priority-overflow';
+import { OverflowEventPayload } from '@fluentui/priority-overflow';
 import type { OverflowGroupState } from '@fluentui/priority-overflow';
 import type { OverflowItemEntry } from '@fluentui/priority-overflow';
-import type { OverflowOptions } from '@fluentui/priority-overflow';
+import { OverflowOptions } from '@fluentui/priority-overflow';
 import type { OverflowSnapshot } from '@fluentui/priority-overflow';
 import * as React_2 from 'react';
 
@@ -28,15 +30,65 @@ export const DATA_OVERFLOWING = "data-overflowing";
 export interface OnOverflowChangeData extends OverflowState {
 }
 
+export { OnUpdateItemVisibility }
+
+export { OnUpdateOverflow }
+
 // @public
-export const Overflow: React_2.ForwardRefExoticComponent<Partial<Pick<OverflowOptions, "padding" | "overflowDirection" | "overflowAxis" | "minimumVisible" | "hasHiddenItems">> & {
+export const Overflow: React_2.ForwardRefExoticComponent<Partial<Pick<OverflowOptions, "overflowAxis" | "overflowDirection" | "padding" | "minimumVisible" | "hasHiddenItems">> & {
     children: React_2.ReactElement;
     onOverflowChange?: (ev: null, data: OverflowState) => void;
 } & React_2.RefAttributes<unknown>>;
 
+// @public
+export type OverflowComponentState = UseOverflowContainerReturn<HTMLElement> & {
+    ref: React_2.Ref<HTMLElement>;
+    className?: string;
+    children: React_2.ReactElement;
+};
+
+// @public (undocumented)
+export interface OverflowContextValue {
+    // (undocumented)
+    containerRef?: React_2.RefObject<HTMLElement | null>;
+    // (undocumented)
+    forceUpdateOverflow: () => void;
+    // (undocumented)
+    getSnapshot: () => OverflowSnapshot;
+    // @deprecated (undocumented)
+    groupVisibility: Record<string, OverflowGroupState>;
+    // @deprecated (undocumented)
+    hasOverflow: boolean;
+    // @deprecated (undocumented)
+    itemVisibility: Record<string, boolean>;
+    // (undocumented)
+    registerDivider: (divider: OverflowDividerEntry) => () => void;
+    // (undocumented)
+    registerItem: (item: OverflowItemEntry) => () => void;
+    // (undocumented)
+    registerOverflowMenu: (el: HTMLElement) => () => void;
+    // (undocumented)
+    subscribe: (listener: () => void) => () => void;
+    // (undocumented)
+    updateOverflow: (padding?: number) => void;
+}
+
+// @public
+export type OverflowContextValues = {
+    overflow: OverflowContextValue;
+};
+
 // @public
 export const OverflowDivider: React_2.ForwardRefExoticComponent<OverflowDividerProps & React_2.RefAttributes<unknown>>;
 
+// @public
+export type OverflowDividerProps = {
+    groupId: string;
+    children: React_2.ReactElement;
+};
+
+export { OverflowEventPayload }
+
 // @public
 export const OverflowItem: React_2.ForwardRefExoticComponent<OverflowItemProps & React_2.RefAttributes<unknown>>;
 
@@ -53,25 +105,44 @@ export type OverflowItemProps = {
     priority?: number;
 });
 
-// @public
+// @public (undocumented)
 export type OverflowProps = Partial<Pick<OverflowOptions, 'overflowAxis' | 'overflowDirection' | 'padding' | 'minimumVisible' | 'hasHiddenItems'>> & {
     children: React_2.ReactElement;
     onOverflowChange?: (ev: null, data: OverflowState) => void;
 };
 
+// @public
+export const OverflowProvider: React_2.Provider<OverflowContextValue>;
+
 // @public
 export const OverflowReorderObserver: React_2.FC;
 
+// @public (undocumented)
+export interface OverflowState {
+    // (undocumented)
+    groupVisibility: Record<string, OverflowGroupState>;
+    // (undocumented)
+    hasOverflow: boolean;
+    // (undocumented)
+    itemVisibility: Record<string, boolean>;
+}
+
+// @public
+export const renderOverflow_unstable: (state: OverflowComponentState, contextValues: OverflowContextValues) => React_2.ReactElement;
+
 // @public (undocumented)
 export function useIsOverflowGroupVisible(id: string): OverflowGroupState;
 
 // @public (undocumented)
 export function useIsOverflowItemVisible(id: string): boolean;
 
+// @public
+export const useOverflow_unstable: (props: OverflowProps, ref: React_2.Ref<HTMLElement>) => OverflowComponentState;
+
 // @internal (undocumented)
 export const useOverflowContainer: <TElement extends HTMLElement>(update: OnUpdateOverflow, options: Omit<OverflowOptions, "onUpdateOverflow">) => UseOverflowContainerReturn<TElement>;
 
-// @internal (undocumented)
+// @public (undocumented)
 export interface UseOverflowContainerReturn<TElement extends HTMLElement> extends Pick<OverflowContextValue, 'registerItem' | 'updateOverflow' | 'forceUpdateOverflow' | 'registerOverflowMenu' | 'registerDivider' | 'getSnapshot' | 'subscribe'> {
     containerRef: React_2.RefObject<TElement | null>;
 }
@@ -82,6 +153,9 @@ export function useOverflowContext(): OverflowContextValue;
 // @internal (undocumented)
 export function useOverflowContext<SelectedValue>(selector: (context: OverflowContextValue) => SelectedValue): SelectedValue;
 
+// @internal
+export const useOverflowContextValues_unstable: (state: OverflowComponentState) => OverflowContextValues;
+
 // @public (undocumented)
 export const useOverflowCount: () => number;
 
@@ -98,6 +172,9 @@ export function useOverflowMenu<TElement extends HTMLElement>(id?: string): {
     isOverflowing: boolean;
 };
 
+// @public (undocumented)
+export const useOverflowStyles_unstable: (state: OverflowComponentState) => OverflowComponentState;
+
 // @public
 export function useOverflowVisibility(): {
     itemVisibility: Record<string, boolean>;

packages/react-components/react-overflow/library/src/components/Overflow.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { render } from '@testing-library/react';
 import { Overflow } from './Overflow';
-import { OverflowItem } from './OverflowItem';
+import { OverflowItem } from '../OverflowItem';
 
 describe('Overflow', () => {
   beforeAll(() => {

…library/src/components/Overflow.test.tsx …rc/components/Overflow/Overflow.test.tsxpackages/react-components/react-overflow/library/src/components/Overflow.test.tsx renamed to packages/react-components/react-overflow/library/src/components/Overflow/Overflow.test.tsx packages/react-components/react-overflow/library/src/components/Overflow.test.tsx renamed to packages/react-components/react-overflow/library/src/components/Overflow/Overflow.test.tsx

@@ -0,0 +1,20 @@
+'use client';
+
+import * as React from 'react';
+import type { OverflowProps } from './Overflow.types';
+import { useOverflow_unstable } from './useOverflow';
+import { useOverflowContextValues_unstable } from '../../useOverflowContextValues';
+import { useOverflowStyles_unstable } from './useOverflowStyles.styles';
+import { renderOverflow_unstable } from './renderOverflow';
+
+/**
+ * Provides an OverflowContext for OverflowItem descendants.
+ */
+export const Overflow = React.forwardRef((props: OverflowProps, ref) => {
+  const state = useOverflow_unstable(props, ref as React.Ref<HTMLElement>);
+  const contextValues = useOverflowContextValues_unstable(state);
+
+  useOverflowStyles_unstable(state);
+
+  return renderOverflow_unstable(state, contextValues);
+});

packages/react-components/react-overflow/library/src/components/Overflow/Overflow.tsx

@@ -0,0 +1,49 @@
+import type * as React from 'react';
+import type { OverflowOptions, OverflowGroupState } from '@fluentui/priority-overflow';
+import type { OverflowContextValue } from '../../overflowContext';
+import type { UseOverflowContainerReturn } from '../../types';
+
+export interface OverflowState {
+  hasOverflow: boolean;
+  itemVisibility: Record<string, boolean>;
+  groupVisibility: Record<string, OverflowGroupState>;
+}
+
+export interface OnOverflowChangeData extends OverflowState {}
+
+export type OverflowProps = Partial<
+  Pick<OverflowOptions, 'overflowAxis' | 'overflowDirection' | 'padding' | 'minimumVisible' | 'hasHiddenItems'>
+> & {
+  children: React.ReactElement;
+
+  // overflow is not caused by DOM event
+  // eslint-disable-next-line @nx/workspace-consistent-callback-type
+  onOverflowChange?: (ev: null, data: OverflowState) => void;
+};
+
+/**
+ * State used in rendering Overflow. Carries the overflow container's registration api so
+ * `useOverflowContextValues_unstable` can assemble the context values.
+ */
+export type OverflowComponentState = UseOverflowContainerReturn<HTMLElement> & {
+  /**
+   * Merged ref applied to the cloned child's root element.
+   */
+  ref: React.Ref<HTMLElement>;
+  /**
+   * Class name applied to the cloned child. Set by `useOverflowStyles_unstable`; left `undefined`
+   * by headless consumers that apply no styling.
+   */
+  className?: string;
+  /**
+   * The single child that overflow behavior is attached to.
+   */
+  children: React.ReactElement;
+};
+
+/**
+ * Context values provided to overflow descendants.
+ */
+export type OverflowContextValues = {
+  overflow: OverflowContextValue;
+};

packages/react-components/react-overflow/library/src/components/Overflow/Overflow.types.ts

@@ -0,0 +1,11 @@
+export { Overflow } from './Overflow';
+export { useOverflow_unstable } from './useOverflow';
+export { renderOverflow_unstable } from './renderOverflow';
+export { useOverflowStyles_unstable } from './useOverflowStyles.styles';
+export type {
+  OverflowProps,
+  OnOverflowChangeData,
+  OverflowState,
+  OverflowComponentState,
+  OverflowContextValues,
+} from './Overflow.types';

packages/react-components/react-overflow/library/src/components/Overflow/index.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import { applyTriggerPropsToChildren, getTriggerChild } from '@fluentui/react-utilities';
+import { OverflowContext } from '../../overflowContext';
+import type { OverflowComponentState, OverflowContextValues } from './Overflow.types';
+
+/**
+ * Render the final JSX of Overflow.
+ *
+ * Griffel-free so it can be reused by headless consumers; all class merging happens in
+ * `useOverflowStyles_unstable`.
+ */
+export const renderOverflow_unstable = (
+  state: OverflowComponentState,
+  contextValues: OverflowContextValues,
+): React.ReactElement => {
+  const child = getTriggerChild<HTMLElement>(state.children);
+
+  const clonedChild = applyTriggerPropsToChildren(state.children, {
+    ref: state.ref,
+    className: state.className ?? child?.props.className,
+  });
+
+  return <OverflowContext.Provider value={contextValues.overflow}>{clonedChild}</OverflowContext.Provider>;
+};