feat(theming): add arrow/menu position and floating placement utilities

packages/theming/package.json

@@ -21,6 +21,7 @@
   "sideEffects": false,
   "types": "dist/typings/index.d.ts",
   "dependencies": {
+    "@floating-ui/react-dom": "^2.0.0",
     "@zendeskgarden/container-focusvisible": "^2.0.0",
     "@zendeskgarden/container-utilities": "^2.0.0",
     "lodash.memoize": "^4.1.2",

packages/theming/src/index.ts

@@ -13,9 +13,12 @@ export {
   /** `retrieveTheme` is a deprecated usage for v7 compatability */
   default as retrieveTheme
 } from './utils/retrieveComponentStyles';
+export { getArrowPosition } from './utils/getArrowPosition';
 export { getColor } from './utils/getColor';
+export { getFloatingPlacements } from './utils/getFloatingPlacements';
 export { getFocusBoxShadow } from './utils/getFocusBoxShadow';
 export { default as getLineHeight } from './utils/getLineHeight';
+export { getMenuPosition } from './utils/getMenuPosition';
 export { default as mediaQuery } from './utils/mediaQuery';
 export { default as arrowStyles } from './utils/arrowStyles';
 export { useDocument } from './utils/useDocument';
@@ -27,8 +30,10 @@ export { focusStyles, SELECTOR_FOCUS_VISIBLE } from './utils/focusStyles';
 export {
   ARROW_POSITION as ARRAY_ARROW_POSITION,
   MENU_POSITION as ARRAY_MENU_POSITION,
+  PLACEMENT,
   type IGardenTheme,
   type IThemeProviderProps,
   type ArrowPosition as ARROW_POSITION,
-  type MenuPosition as MENU_POSITION
+  type MenuPosition as MENU_POSITION,
+  type Placement
 } from './types';

packages/theming/src/types/index.ts

@@ -28,6 +28,23 @@ export const MENU_POSITION = ['top', 'right', 'bottom', 'left'] as const;
 
 export type MenuPosition = (typeof MENU_POSITION)[number];
 
+export const PLACEMENT = [
+  'top',
+  'top-start',
+  'top-end',
+  'bottom',
+  'bottom-start',
+  'bottom-end',
+  'end',
+  'end-top',
+  'end-bottom',
+  'start',
+  'start-top',
+  'start-bottom'
+] as const;
+
+export type Placement = (typeof PLACEMENT)[number];
+
 type Hue = Record<number | string, string> | string;
 
 export interface IGardenTheme {

packages/theming/src/utils/getArrowPosition.spec.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright Zendesk, Inc.
+ *
+ * Use of this source code is governed under the Apache License, Version 2.0
+ * found at http://www.apache.org/licenses/LICENSE-2.0.
+ */
+
+import { Placement } from '@floating-ui/react-dom';
+import { POSITION_MAP, getArrowPosition } from './getArrowPosition';
+import { ArrowPosition } from '../types';
+
+describe('getArrowPosition', () => {
+  it.each<[Placement, ArrowPosition]>(Object.entries(POSITION_MAP) as [Placement, ArrowPosition][])(
+    'converts "%s" to "%s"',
+    (placement, expected) => {
+      const position = getArrowPosition(placement);
+
+      expect(position).toBe(expected);
+    }
+  );
+});

packages/theming/src/utils/getArrowPosition.ts

@@ -0,0 +1,35 @@
+/**
+ * Copyright Zendesk, Inc.
+ *
+ * Use of this source code is governed under the Apache License, Version 2.0
+ * found at http://www.apache.org/licenses/LICENSE-2.0.
+ */
+
+import { Placement } from '@floating-ui/react-dom';
+import { ArrowPosition } from '../types';
+
+export const POSITION_MAP: Record<Placement, ArrowPosition> = {
+  top: 'bottom',
+  'top-start': 'bottom-left',
+  'top-end': 'bottom-right',
+  right: 'left',
+  'right-start': 'left-top',
+  'right-end': 'left-bottom',
+  bottom: 'top',
+  'bottom-start': 'top-left',
+  'bottom-end': 'top-right',
+  left: 'right',
+  'left-start': 'right-top',
+  'left-end': 'right-bottom'
+};
+
+/**
+ * Convert Floating-UI placement to a valid `arrowStyles` position.
+ *
+ * @param {string} placement A Floating-UI placement.
+ *
+ * @returns An `arrowStyles` position.
+ */
+export const getArrowPosition = (placement: Placement): ArrowPosition => {
+  return POSITION_MAP[placement];
+};

packages/theming/src/utils/getFloatingPlacements.spec.ts

@@ -0,0 +1,44 @@
+/**
+ * Copyright Zendesk, Inc.
+ *
+ * Use of this source code is governed under the Apache License, Version 2.0
+ * found at http://www.apache.org/licenses/LICENSE-2.0.
+ */
+
+import { Placement as FloatingPlacement } from '@floating-ui/react-dom';
+import { PLACEMENT, Placement } from '../types';
+import { PLACEMENT_MAP, RTL_PLACEMENT_MAP, getFloatingPlacements } from './getFloatingPlacements';
+import DEFAULT_THEME from '../elements/theme';
+
+describe('getFloatingPlacements', () => {
+  it.each<[Placement, FloatingPlacement]>(
+    PLACEMENT.map(placement => [placement, PLACEMENT_MAP[placement] || placement])
+  )('converts Garden "%s" to Floating-UI "%s"', (placement, expected) => {
+    const [floatingPlacement, fallbackPlacements] = getFloatingPlacements(DEFAULT_THEME, placement);
+
+    expect(floatingPlacement).toBe(expected);
+    expect(fallbackPlacements).not.toContain(floatingPlacement);
+  });
+
+  it.each<[Placement, FloatingPlacement]>(
+    PLACEMENT.map(placement => [
+      placement,
+      RTL_PLACEMENT_MAP[PLACEMENT_MAP[placement] || placement] ||
+        PLACEMENT_MAP[placement] ||
+        placement
+    ])
+  )('converts RTL Garden "%s" to Floating-UI "%s"', (placement, expected) => {
+    const theme = { ...DEFAULT_THEME, rtl: true };
+    const [floatingPlacement, fallbackPlacements] = getFloatingPlacements(theme, placement);
+
+    expect(floatingPlacement).toBe(expected);
+    expect(fallbackPlacements).not.toContain(floatingPlacement);
+  });
+
+  it('handles fallbacks as expected', () => {
+    const fallbacks = ['top-start', 'top', 'top-end'] as Placement[];
+    const placements = getFloatingPlacements(DEFAULT_THEME, 'bottom', fallbacks);
+
+    expect(placements[1]).toStrictEqual(fallbacks);
+  });
+});

packages/theming/src/utils/getFloatingPlacements.ts

@@ -0,0 +1,105 @@
+/**
+ * Copyright Zendesk, Inc.
+ *
+ * Use of this source code is governed under the Apache License, Version 2.0
+ * found at http://www.apache.org/licenses/LICENSE-2.0.
+ */
+
+import { Placement as FloatingPlacement } from '@floating-ui/react-dom';
+import { IGardenTheme, MenuPosition, Placement } from '../types';
+
+/* Map Garden to Floating-UI placements */
+export const PLACEMENT_MAP: Record<string, FloatingPlacement> = {
+  end: 'right',
+  'end-top': 'right-start',
+  'end-bottom': 'right-end',
+  start: 'left',
+  'start-top': 'left-start',
+  'start-bottom': 'left-end'
+};
+
+/* Map Floating-UI to RTL placements */
+export const RTL_PLACEMENT_MAP: Record<string, FloatingPlacement> = {
+  left: 'right',
+  'left-start': 'right-start',
+  'left-end': 'right-end',
+  'top-start': 'top-end',
+  'top-end': 'top-start',
+  right: 'left',
+  'right-start': 'left-start',
+  'right-end': 'left-end',
+  'bottom-start': 'bottom-end',
+  'bottom-end': 'bottom-start'
+};
+
+const toFloatingPlacement = (placement: Placement, theme: IGardenTheme): FloatingPlacement => {
+  let retVal = PLACEMENT_MAP[placement] || placement;
+
+  if (theme.rtl) {
+    retVal = RTL_PLACEMENT_MAP[retVal] || retVal;
+  }
+
+  return retVal;
+};
+
+/* Map Floating-UI side placement to fallbacks */
+const SIDE_FALLBACKS_MAP: Record<string, FloatingPlacement[]> = {
+  top: ['top-start', 'top', 'top-end'],
+  right: ['right-start', 'right', 'right-end'],
+  bottom: ['bottom-start', 'bottom', 'bottom-end'],
+  left: ['left-start', 'left', 'left-end']
+};
+
+/* Map Floating-UI side placement to opposite side */
+const SIDE_OPPOSITE_MAP: Record<string, MenuPosition> = {
+  top: 'bottom',
+  right: 'left',
+  bottom: 'top',
+  left: 'right'
+};
+
+const toFallbackPlacements = (
+  primaryPlacement: FloatingPlacement,
+  theme: IGardenTheme,
+  fallbackPlacements?: Placement[]
+): FloatingPlacement[] => {
+  if (Array.isArray(fallbackPlacements) && fallbackPlacements.length > 0) {
+    return fallbackPlacements.map(fallbackPlacement =>
+      toFloatingPlacement(fallbackPlacement, theme)
+    );
+  }
+
+  const side = primaryPlacement.split('-')[0];
+  const sameSideFallbackPlacements = [...SIDE_FALLBACKS_MAP[side]];
+  const oppositeSideFallbackPlacements = SIDE_FALLBACKS_MAP[SIDE_OPPOSITE_MAP[side]];
+
+  // Remove the primary placement from the list of same-side fallbacks to
+  // prevent extra work for Floating-UI
+  sameSideFallbackPlacements.splice(sameSideFallbackPlacements.indexOf(primaryPlacement), 1);
+
+  return [...sameSideFallbackPlacements, ...oppositeSideFallbackPlacements];
+};
+
+/**
+ * Convert Garden placements to valid placements for Floating-UI.
+ *
+ * @param {Object} theme Context `theme` object used to determine if layout is right-to-left.
+ * @param {string} placement A Garden placement.
+ * @param {Array} fallbackPlacements Optional list of Garden fallback placements.
+ *
+ * @returns A Floating-UI (placement, fallbackPlacements) tuple.
+ */
+export const getFloatingPlacements = (
+  theme: IGardenTheme,
+  placement: Placement,
+  fallbackPlacements?: Placement[]
+): [FloatingPlacement, FloatingPlacement[]] => {
+  const floatingPlacement = toFloatingPlacement(placement, theme);
+  const floatingFallbackPlacements = toFallbackPlacements(
+    floatingPlacement,
+    theme,
+    fallbackPlacements
+  );
+
+  return [floatingPlacement, floatingFallbackPlacements];
+};

packages/theming/src/utils/getMenuPosition.spec.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright Zendesk, Inc.
+ *
+ * Use of this source code is governed under the Apache License, Version 2.0
+ * found at http://www.apache.org/licenses/LICENSE-2.0.
+ */
+
+import DEFAULT_THEME from '../elements/theme';
+import { PLACEMENT } from '../types';
+import { getFloatingPlacements } from './getFloatingPlacements';
+import { getMenuPosition } from './getMenuPosition';
+
+describe('getMenuPosition', () => {
+  it.each(PLACEMENT)('converts "%s" as expected', placement => {
+    const placements = getFloatingPlacements(DEFAULT_THEME, placement);
+    const position = getMenuPosition(placements[0]);
+    const expected = placements[0].split('-')[0];
+
+    expect(position).toBe(expected);
+  });
+});

packages/theming/src/utils/getMenuPosition.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright Zendesk, Inc.
+ *
+ * Use of this source code is governed under the Apache License, Version 2.0
+ * found at http://www.apache.org/licenses/LICENSE-2.0.
+ */
+
+import { Placement } from '@floating-ui/react-dom';
+import { MenuPosition } from '../types';
+
+/**
+ * Convert Floating-UI placement to a valid `menuStyles` position.
+ *
+ * @param {string} placement A Floating-UI placement.
+ *
+ * @returns A `menuStyles` position.
+ */
+export const getMenuPosition = (placement: Placement): MenuPosition => {
+  return placement.split('-')[0] as MenuPosition;
+};