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-1775234017199.md

@@ -0,0 +1,6 @@
+---
+gamut-styles: minor
+gamut: minor
+---
+
+Updates the Pagination component to have its Previous/Next buttons' icon reflect the correct dir

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

@@ -0,0 +1,6 @@
+---
+gamut-styles: minor
+gamut: minor
+---
+
+feat: add useLogicalProperties + useElementDir hooks. fix: RTL left-center + right-center ToolTip and Pagination issues.

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,80 @@
+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.
+ *
+ * @param el - DOM node whose effective direction is resolved.
+ * @returns `rtl` or `ltr`.
+ */
+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`).
+ *
+ * @template T - DOM element type for `current`; defaults to {@link 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}.
+ *
+ * @template T - DOM element type for the optional ref; defaults to {@link Element}.
+ * @param elementRef - Optional ref; when missing or `current` is not an `Element`, uses `document.documentElement`.
+ * @returns Effective direction for the resolved element, or `ltr` when `document` is undefined (SSR).
+ */
+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 map to 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/Pagination/index.tsx

@@ -2,10 +2,11 @@ import {
   MiniChevronLeftIcon,
   MiniChevronRightIcon,
 } from '@codecademy/gamut-icons';
-import { useMemo, useState } from 'react';
+import { useElementDir } from '@codecademy/gamut-styles';
+import { useMemo, useRef, useState } from 'react';
 import * as React from 'react';
 
-import { HiddenText } from '..';
+import { Text } from '..';
 import { FlexBox } from '../Box';
 import {
   AnimatedFadeButton,
@@ -72,6 +73,8 @@ export const Pagination: React.FC<PaginationProps> = ({
   );
   const [liveText, setLiveText] = useState('');
   const [shownPageArray, setShownPageArray] = useState([0]);
+  const rootRef = useRef<HTMLDivElement>(null);
+  const isRtl = useElementDir(rootRef) === 'rtl';
 
   const showSkipToButtons = !!(
     (type === undefined && totalPages >= 10) ||
@@ -145,13 +148,16 @@ export const Pagination: React.FC<PaginationProps> = ({
         _: 'initial',
         sm: `${showSkipToButtons ? getMinWidth({ chapterSize }) : 'initial'}`,
       }}
+      ref={rootRef}
     >
-      <HiddenText aria-live="polite">{liveText}</HiddenText>
+      <Text aria-live="polite" screenreader>
+        {liveText}
+      </Text>
       <AnimatedFadeButton
         aria-label={`Navigate back to page ${currentPage - 1}`}
         buttonType={variant}
         href={navigation}
-        icon={MiniChevronLeftIcon}
+        icon={isRtl ? MiniChevronRightIcon : MiniChevronLeftIcon}
         showButton={currentPage === 1 ? 'hidden' : 'shown'}
         onClick={() => changeHandler(currentPage - 1)}
       />
@@ -230,7 +236,7 @@ export const Pagination: React.FC<PaginationProps> = ({
         aria-label={`Navigate forward to page ${currentPage + 1}`}
         buttonType={variant}
         href={navigation}
-        icon={MiniChevronRightIcon}
+        icon={isRtl ? MiniChevronLeftIcon : MiniChevronRightIcon}
         showButton={currentPage === totalPages ? 'hidden' : 'shown'}
         onClick={() => changeHandler(currentPage + 1)}
       />