chore(GamutProvider): useLogicalProperties hook

.lintstagedrc.mjs

@@ -1,5 +1,8 @@
 import micromatch from 'micromatch';
 
+/** Shell-safe argument for paths that may contain spaces (lint-staged runs commands via a shell). */
+const shellArg = (file) => JSON.stringify(file);
+
 export default {
   // Use custom function to avoid overlaps that could cause race conditions
   [`*`]: (allChanges) => {
@@ -22,14 +25,16 @@ export default {
 
     if (eslintFiles.length) {
       commands.push(
-        `node_modules/@codecademy/eslint-config/bin/eslint-fix.js ${eslintFiles.join(
-          ' '
-        )}`
+        `node_modules/@codecademy/eslint-config/bin/eslint-fix.js ${eslintFiles
+          .map(shellArg)
+          .join(' ')}`
       );
     }
 
     // Run nx format, which will run prettier
-    commands.push(`nx format:write --files ${allChanges}`);
+    commands.push(
+      `nx format:write --files ${allChanges.map(shellArg).join(' ')}`
+    );
 
     return commands;
   },

.nx/version-plans/version-plan-1775134595003.md

@@ -0,0 +1,5 @@
+---
+gamut-styles: minor
+---
+
+feat(gamut-styles): add useLogicalProperties hook

packages/gamut-styles/src/AssetProvider.tsx

@@ -3,7 +3,7 @@ import * as React from 'react';
 
 import { webFonts } from './remoteAssets/fonts';
 import { coreTheme } from './themes';
-import { FontConfig, getFonts } from './utils/fontUtils';
+import { FontConfig, getFonts } from './utilities/fontUtils';
 
 /*
  * Only preload woff2 fonts, since woff1 are only included as fallbacks.

packages/gamut-styles/src/__tests__/AssetProvider.test.tsx

@@ -8,7 +8,7 @@ import { setupRtl } from './testUtils';
 
 const renderView = setupRtl(AssetProvider, {});
 
-jest.mock('../utils/fontUtils', () => ({
+jest.mock('../utilities/fontUtils', () => ({
   getFonts: jest.fn(),
 }));
 
@@ -43,7 +43,7 @@ jest.mock('../remoteAssets/fonts', () => ({
   },
 }));
 
-const mockGetFonts = require('../utils/fontUtils').getFonts;
+const mockGetFonts = require('../utilities/fontUtils').getFonts;
 
 describe('AssetProvider', () => {
   beforeEach(() => {

packages/gamut-styles/src/__tests__/fontLoading.test.tsx

@@ -6,7 +6,7 @@ import { coreTheme, percipioTheme } from '../themes';
 // Type assertion to satisfy Theme interface in GamutProvider from theme.d.ts - this lib is typed to the CoreTheme interface
 const typedPercipioTheme = percipioTheme as any;
 
-jest.mock('../utils/fontUtils', () => ({
+jest.mock('../utilities/fontUtils', () => ({
   getFonts: jest.fn(),
 }));
 
@@ -29,7 +29,7 @@ jest.mock('../remoteAssets/fonts', () => ({
   },
 }));
 
-const mockGetFonts = require('../utils/fontUtils').getFonts;
+const mockGetFonts = require('../utilities/fontUtils').getFonts;
 
 const mockDocumentFonts = {
   load: jest.fn(),

packages/gamut-styles/src/globals/Typography.tsx

@@ -2,7 +2,7 @@ import { css, Global } from '@emotion/react';
 import * as React from 'react';
 
 import { coreTheme } from '../themes';
-import { FontConfig, getFonts } from '../utils/fontUtils';
+import { FontConfig, getFonts } from '../utilities/fontUtils';
 
 /**
  * Typography component that applies global typography styles to the application.

packages/gamut-styles/src/remoteAssets/fonts.ts

@@ -1,4 +1,4 @@
-import { FontConfig } from '../utils/fontUtils';
+import { FontConfig } from '../utilities/fontUtils';
 
 export const FONT_ASSET_PATH = `https://www.codecademy.com/gamut`;
 

packages/gamut-styles/src/utilities/__tests__/elementDir.test.ts

@@ -0,0 +1,25 @@
+import { elementDir } from '../elementDir';
+
+describe('elementDir', () => {
+  afterEach(() => {
+    document.documentElement.removeAttribute('dir');
+  });
+
+  it('returns rtl when the element has dir="rtl"', () => {
+    const el = document.createElement('div');
+    el.setAttribute('dir', 'rtl');
+    expect(elementDir(el)).toBe('rtl');
+  });
+
+  it('returns ltr when the element has dir="ltr"', () => {
+    const el = document.createElement('div');
+    el.setAttribute('dir', 'ltr');
+    expect(elementDir(el)).toBe('ltr');
+  });
+
+  it('falls back to documentElement dir when computed style is empty (JSDOM)', () => {
+    const el = document.createElement('div');
+    document.documentElement.setAttribute('dir', 'rtl');
+    expect(elementDir(el)).toBe('rtl');
+  });
+});

packages/gamut-styles/src/utilities/__tests__/useElementDir.test.tsx

@@ -0,0 +1,66 @@
+import * as React from 'react';
+
+import { setupRtl } from '../../__tests__/testUtils';
+import { useElementDir } from '../elementDir';
+
+const DirProbe: React.FC = () => (
+  <span data-testid="dir">{useElementDir()}</span>
+);
+
+const WithRef: React.FC = () => {
+  const ref = React.useRef<HTMLDivElement>(null);
+  return (
+    <>
+      <div data-testid="dir">{useElementDir(ref)}</div>
+      <div dir="rtl" ref={ref}>
+        x
+      </div>
+    </>
+  );
+};
+
+const WithSpanRef: React.FC = () => {
+  const ref = React.useRef<HTMLSpanElement>(null);
+  return (
+    <>
+      <span data-testid="dir">{useElementDir(ref)}</span>
+      <span dir="rtl" ref={ref}>
+        x
+      </span>
+    </>
+  );
+};
+
+const renderDirProbe = setupRtl(DirProbe, {});
+const renderWithRef = setupRtl(WithRef, {});
+const renderWithSpanRef = setupRtl(WithSpanRef, {});
+
+describe('useElementDir', () => {
+  afterEach(() => {
+    document.documentElement.removeAttribute('dir');
+  });
+
+  it('returns rtl when documentElement has dir=rtl and no ref', () => {
+    document.documentElement.setAttribute('dir', 'rtl');
+
+    const { view } = renderDirProbe();
+    expect(view.getByTestId('dir')).toHaveTextContent('rtl');
+  });
+
+  it('returns ltr when documentElement has dir=ltr and no ref', () => {
+    document.documentElement.setAttribute('dir', 'ltr');
+
+    const { view } = renderDirProbe();
+    expect(view.getByTestId('dir')).toHaveTextContent('ltr');
+  });
+
+  it('uses ref target when it is an Element', () => {
+    const { view } = renderWithRef();
+    expect(view.getByTestId('dir')).toHaveTextContent('rtl');
+  });
+
+  it('accepts non-div element refs (e.g. span)', () => {
+    const { view } = renderWithSpanRef();
+    expect(view.getByTestId('dir')).toHaveTextContent('rtl');
+  });
+});

packages/gamut-styles/src/utilities/__tests__/useLogicalProperties.test.tsx

@@ -0,0 +1,36 @@
+import { Theme, ThemeProvider } from '@emotion/react';
+import * as React from 'react';
+
+import { setupRtl } from '../../__tests__/testUtils';
+import { coreTheme as theme } from '../../themes';
+import { useLogicalProperties } from '../useLogicalProperties';
+
+const ValueReadout: React.FC = () => <span>{`${useLogicalProperties()}`}</span>;
+
+const HookProbe: React.FC<{ themeForHook?: Theme }> = ({
+  themeForHook = theme,
+}) => (
+  <ThemeProvider theme={themeForHook}>
+    <ValueReadout />
+  </ThemeProvider>
+);
+
+const renderView = setupRtl(HookProbe, {});
+
+describe('useLogicalProperties', () => {
+  it('returns false when theme sets useLogicalProperties: false', () => {
+    const { view } = renderView({
+      themeForHook: { ...theme, useLogicalProperties: false },
+    });
+
+    view.getByText('false');
+  });
+
+  it('returns true when theme sets useLogicalProperties: true', () => {
+    const { view } = renderView({
+      themeForHook: { ...theme, useLogicalProperties: true },
+    });
+
+    view.getByText('true');
+  });
+});

packages/gamut-styles/src/utilities/elementDir.ts

@@ -0,0 +1,70 @@
+import type { RefObject } from 'react';
+import { useEffect, useLayoutEffect, useReducer } from 'react';
+
+/** Resolved HTML `dir` keyword: effective writing direction after `dir`, then CSS `direction`, then document root. */
+export type DirValue = 'rtl' | 'ltr';
+
+/**
+ * Resolves the effective `dir` for an element (`rtl` or `ltr`), including JSDOM where
+ * `getComputedStyle(el).direction` is often empty while `dir` is set on the root.
+ */
+export function elementDir(el: Element): DirValue {
+  const ownDir = el.getAttribute('dir');
+  if (ownDir === 'rtl') return 'rtl';
+  if (ownDir === 'ltr') return 'ltr';
+  const { direction } = getComputedStyle(el);
+  if (direction === 'rtl' || direction === 'ltr') {
+    return direction;
+  }
+  return document.documentElement.getAttribute('dir') === 'rtl' ? 'rtl' : 'ltr';
+}
+
+/**
+ * Ref whose `current` may be any DOM {@link Element} subclass (`HTMLElement`, `SVGElement`,
+ * `HTMLButtonElement`, etc.). For structural/minimal types (e.g. tests), intersect with
+ * `Element` so `current` is still typed as an `Element` (e.g. `Pick<HTMLAnchorElement, 'id'> & Element`).
+ */
+export type ElementDirRef<T extends Element = Element> = RefObject<T | null>;
+
+function resolveElement<T extends Element>(
+  elementRef: ElementDirRef<T> | undefined
+): Element {
+  return elementRef?.current instanceof Element
+    ? elementRef.current
+    : document.documentElement;
+}
+
+/**
+ * Returns the effective `dir` for the resolved element (`rtl` or `ltr`), and updates when `dir`
+ * changes on the document subtree or after layout (so `ref.current` is current).
+ * Resolution uses {@link elementDir}.
+ *
+ * @param elementRef - Optional ref; when missing or `current` is not an `Element`, uses `document.documentElement`.
+ */
+export function useElementDir<T extends Element = Element>(
+  elementRef?: ElementDirRef<T>
+): DirValue {
+  const [, bump] = useReducer((n: number) => n + 1, 0);
+
+  useLayoutEffect(() => {
+    bump();
+  }, [elementRef]);
+
+  useEffect(() => {
+    const observer = new MutationObserver(() => {
+      bump();
+    });
+    observer.observe(document.documentElement, {
+      attributeFilter: ['dir'],
+      attributes: true,
+      subtree: true,
+    });
+    return () => observer.disconnect();
+  }, []);
+
+  if (typeof document === 'undefined') {
+    return 'ltr';
+  }
+
+  return elementDir(resolveElement(elementRef));
+}

packages/gamut-styles/src/utilities/index.ts

@@ -1 +1,3 @@
+export * from './elementDir';
 export * from './themed';
+export * from './useLogicalProperties';

packages/gamut-styles/src/utilities/useLogicalProperties.ts

@@ -0,0 +1,12 @@
+import { useTheme } from '@emotion/react';
+
+/**
+ * Whether Gamut system props emit logical CSS properties (`marginInlineStart`, etc.)
+ * vs physical (`marginLeft`, etc.).
+ *
+ * `GamutProvider` always merges an explicit boolean (default `false`).
+ */
+export function useLogicalProperties() {
+  const theme = useTheme();
+  return theme?.useLogicalProperties;
+}

packages/gamut/src/DataList/Controls/FilterControl.tsx

@@ -66,7 +66,7 @@ export const FilterControl: React.FC<FilterProps> = ({
           alignment={justify === 'left' ? 'bottom-right' : 'bottom-left'}
           isOpen
           offset={0}
-          targetRef={target as any}
+          targetRef={target}
           onRequestClose={() => setMenuOpen(false)}
         >
           <Menu

packages/gamut/src/PopoverContainer/PopoverContainer.tsx

@@ -1,4 +1,8 @@
-import { system } from '@codecademy/gamut-styles';
+import {
+  system,
+  useElementDir,
+  useLogicalProperties,
+} from '@codecademy/gamut-styles';
 import { variance } from '@codecademy/variance';
 import styled from '@emotion/styled';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
@@ -50,35 +54,14 @@
   const parent = containers?.parent;
 
   // Memoize scrolling parents to avoid expensive DOM traversals
-  const scrollingParents = useScrollingParents(
-    targetRef as React.RefObject<HTMLElement | null>
-  );
+  const scrollingParents = useScrollingParents(targetRef);
 
   // Keep onRequestClose ref up to date
   useEffect(() => {
     onRequestCloseRef.current = onRequestClose;
   }, [onRequestClose]);
 
-  // Detect RTL direction from the target element and watch for attribute changes so the
-  // position recalculates when changes occur
-  const [isRtl, setIsRtl] = useState(false);
-  useEffect(() => {
-    const checkDirection = () => {
-      const target = targetRef?.current;
-      const el = target instanceof Element ? target : document.documentElement;
-      setIsRtl(getComputedStyle(el).direction === 'rtl');
-    };
-
-    checkDirection();
-
-    const observer = new MutationObserver(checkDirection);
-    observer.observe(document.documentElement, {
-      attributes: true,
-      attributeFilter: ['dir'],
-      subtree: true,
-    });
-    return () => observer.disconnect();
-  }, [targetRef]);
+  const isRtl = useElementDir(targetRef) === 'rtl';
 
   const popoverPosition = useMemo(() => {
     if (parent !== undefined) {
@@ -95,6 +78,10 @@
     return { styles: {}, physicalStyles: undefined };
   }, [parent, x, y, offset, alignment, invertAxis, isRtl]);
 
+  // Log logical properties to the console TEST CODE
+  const logicalProperties = useLogicalProperties();
+  console.log('dir', isRtl, 'logicalProperties', logicalProperties);
+
   useEffect(() => {
     const target = targetRef?.current;
     if (!target) return;