@astryxdesign/core 0.1.9 → 0.2.0-canary.0f56f82

package/src/Tooltip/Tooltip.test.tsx

@@ -221,4 +221,50 @@ describe('Tooltip', () => {
       expect(onOpenChange).not.toHaveBeenCalledWith(false);
     });
   });
+
+  describe('press-to-dismiss', () => {
+    it('hides the tooltip when the trigger is pressed', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Tooltip content="Copy link" onOpenChange={onOpenChange} delay={0}>
+          <button type="button">Trigger</button>
+        </Tooltip>,
+      );
+
+      const trigger = screen.getByRole('button', {name: 'Trigger'});
+      fireEvent.mouseEnter(trigger);
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+
+      fireEvent.pointerDown(trigger);
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(false);
+      });
+    });
+
+    it('does not press-dismiss a controlled tooltip', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Tooltip
+          content="Controlled"
+          isOpen
+          onOpenChange={onOpenChange}
+          delay={0}>
+          <button type="button">Trigger</button>
+        </Tooltip>,
+      );
+
+      const trigger = screen.getByRole('button', {name: 'Trigger'});
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+      onOpenChange.mockClear();
+
+      fireEvent.pointerDown(trigger);
+      // Give any (incorrect) async hide a chance to run.
+      await new Promise(r => setTimeout(r, 20));
+      expect(onOpenChange).not.toHaveBeenCalledWith(false);
+    });
+  });
 });

package/src/Tooltip/useTooltip.tsx

@@ -366,6 +366,19 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     scheduleHide();
   }, [scheduleHide]);
 
+  // Pressing the trigger hides its own tooltip: once the control is activated
+  // the hint has served its purpose, and a tooltip lingering over a
+  // just-pressed control reads as stale. Fires on pointerdown so it feels
+  // immediate. Uncontrolled tooltips only — a controlled tooltip's visibility
+  // is owned by the consumer. `layer.hide()` self-guards when already closed.
+  const handlePointerDown = useCallback(() => {
+    if (isOpen !== undefined) {
+      return;
+    }
+    clearTimeouts();
+    layer.hide();
+  }, [isOpen, clearTimeouts, layer]);
+
   // Interaction ref that handles event listeners only
   const interactionRef: RefCallback<HTMLElement> = useCallback(
     (el: HTMLElement | null) => {
@@ -375,12 +388,18 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
         triggerRef.current.removeEventListener('mouseleave', handleMouseLeave);
         triggerRef.current.removeEventListener('focusin', handleFocusIn);
         triggerRef.current.removeEventListener('focusout', handleFocusOut);
+        triggerRef.current.removeEventListener(
+          'pointerdown',
+          handlePointerDown,
+        );
       }
 
       if (el) {
         // Attach hover listeners
         el.addEventListener('mouseenter', handleMouseEnter);
         el.addEventListener('mouseleave', handleMouseLeave);
+        // Press-to-dismiss: activating the trigger hides its own tooltip.
+        el.addEventListener('pointerdown', handlePointerDown);
 
         // Attach focus listeners based on focusTrigger option
         const shouldAttachFocus =
@@ -401,6 +420,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       handleMouseLeave,
       handleFocusIn,
       handleFocusOut,
+      handlePointerDown,
     ],
   );
 

package/src/TopNav/TopNav.test.tsx

@@ -420,12 +420,103 @@ describe('TopNavItem', () => {
 
   it('applies aria-disabled when isDisabled', () => {
     render(<TopNavItem label="Home" href="#" isDisabled />);
-    expect(screen.getByRole('link')).toHaveAttribute('aria-disabled', 'true');
+    expect(screen.getByText('Home').closest('a')).toHaveAttribute(
+      'aria-disabled',
+      'true',
+    );
   });
 
   it('sets tabIndex to -1 when disabled', () => {
     render(<TopNavItem label="Home" href="#" isDisabled />);
-    expect(screen.getByRole('link')).toHaveAttribute('tabIndex', '-1');
+    expect(screen.getByText('Home').closest('a')).toHaveAttribute(
+      'tabIndex',
+      '-1',
+    );
+  });
+
+  describe('disabled items do not navigate', () => {
+    it('drops href/target and suppresses clicks when disabled (default mode)', () => {
+      const handleClick = vi.fn();
+      render(
+        <TopNavItem
+          label="Home"
+          href="/home"
+          target="_blank"
+          onClick={handleClick}
+          isDisabled
+        />,
+      );
+      // An href-less anchor exposes no link role, so it is not announced
+      // with a live destination.
+      expect(screen.queryByRole('link')).not.toBeInTheDocument();
+      const item = screen.getByText('Home').closest('a') as HTMLAnchorElement;
+      expect(item).not.toHaveAttribute('href');
+      expect(item).not.toHaveAttribute('target');
+      expect(item).toHaveAttribute('aria-disabled', 'true');
+      expect(item).toHaveAttribute('tabIndex', '-1');
+
+      // fireEvent bypasses pointer-events: none, simulating programmatic/AT
+      // activation. It returns false when preventDefault was called, i.e.
+      // any default navigation behavior is cancelled.
+      const notCancelled = fireEvent.click(item);
+      expect(notCancelled).toBe(false);
+      expect(handleClick).not.toHaveBeenCalled();
+    });
+
+    it('drops href/target and suppresses clicks when disabled (drawer mode)', () => {
+      const handleClick = vi.fn();
+      render(
+        <TopNavRenderContext value="drawer">
+          <TopNavItem
+            label="Home"
+            href="/home"
+            target="_blank"
+            onClick={handleClick}
+            isDisabled
+          />
+        </TopNavRenderContext>,
+      );
+      expect(screen.queryByRole('link')).not.toBeInTheDocument();
+      const item = screen.getByText('Home').closest('a') as HTMLAnchorElement;
+      expect(item).not.toHaveAttribute('href');
+      expect(item).not.toHaveAttribute('target');
+      expect(item).toHaveAttribute('aria-disabled', 'true');
+      expect(item).toHaveAttribute('tabIndex', '-1');
+
+      // fireEvent bypasses pointer-events: none, simulating programmatic/AT
+      // activation. It returns false when preventDefault was called.
+      const notCancelled = fireEvent.click(item);
+      expect(notCancelled).toBe(false);
+      expect(handleClick).not.toHaveBeenCalled();
+    });
+
+    it('keeps href and click behavior for enabled items (default mode)', async () => {
+      const user = userEvent.setup();
+      const handleClick = vi.fn();
+      render(<TopNavItem label="Home" href="#" onClick={handleClick} />);
+      const link = screen.getByRole('link', {name: 'Home'});
+      expect(link).toHaveAttribute('href', '#');
+      expect(link).not.toHaveAttribute('aria-disabled');
+
+      await user.click(link);
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
+
+    it('keeps href and click behavior for enabled items (drawer mode)', async () => {
+      const user = userEvent.setup();
+      const handleClick = vi.fn();
+      render(
+        <TopNavRenderContext value="drawer">
+          <TopNavItem label="Home" href="#" onClick={handleClick} />
+        </TopNavRenderContext>,
+      );
+      const link = screen.getByRole('link', {name: 'Home'});
+      expect(link).toHaveAttribute('href', '#');
+      expect(link).not.toHaveAttribute('aria-disabled');
+
+      await user.click(link);
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
   });
 
   it('renders icon with label', () => {

package/src/TopNav/TopNavItem.doc.mjs

@@ -29,7 +29,7 @@ export const docs = {
     {
       name: 'isDisabled',
       type: 'boolean',
-      description: 'Whether the nav item is disabled. Sets aria-disabled and prevents interaction.',
+      description: 'Whether the nav item is disabled. Sets aria-disabled, drops href/target so the item cannot navigate, and prevents interaction.',
       default: 'false',
     },
     {
@@ -91,7 +91,7 @@ export const docsZh = {
     {
       name: 'isDisabled',
       type: 'boolean',
-      description: '导航项是否被禁用。设置 aria-disabled 并阻止交互。',
+      description: '导航项是否被禁用。设置 aria-disabled，移除 href/target 使其无法导航，并阻止交互。',
       default: 'false',
     },
     {
@@ -121,7 +121,7 @@ export const docsDense = {
     label: 'Visible text or aria-label when isIconOnly is true.',
     href: 'Navigation URL.',
     isSelected: 'Sets aria-current="page"+highlighted styles.',
-    isDisabled: 'Sets aria-disabled, prevents interaction.',
+    isDisabled: 'Sets aria-disabled, drops href/target (no navigation), prevents interaction.',
     icon: 'Icon before label.',
     children: 'Custom content instead of label text.',
     as: 'Custom link component. Overrides LinkProvider default. Must accept href, className, style, children.',

package/src/TopNav/TopNavItem.tsx

@@ -131,6 +131,8 @@ export interface TopNavItemProps extends BaseProps<HTMLAnchorElement> {
   isSelected?: boolean;
   /**
    * Whether the nav item is disabled.
+   * A disabled item renders as a plain anchor without an href (and without
+   * target), so it cannot navigate and is removed from the tab order.
    * @default false
    */
   isDisabled?: boolean;
@@ -157,6 +159,15 @@ export interface TopNavItemProps extends BaseProps<HTMLAnchorElement> {
   size?: NavItemSize;
 }
 
+/**
+ * Click handler for disabled items. The disabled anchor renders without an
+ * href, so there is no navigation to block in practice; preventDefault is a
+ * defensive guard against synthetic/programmatic clicks.
+ */
+function preventDefaultClick(event: React.MouseEvent<HTMLAnchorElement>): void {
+  event.preventDefault();
+}
+
 /**
  * A navigation item for use within TopNav startContent.
  *
@@ -178,6 +189,9 @@ export interface TopNavItemProps extends BaseProps<HTMLAnchorElement> {
  */
 export function TopNavItem({
   as,
+  href,
+  target,
+  onClick,
   label,
   isSelected = false,
   isDisabled = false,
@@ -195,22 +209,34 @@ export function TopNavItem({
   const renderMode = useTopNavRenderMode();
   const {closeMobileNav} = useAppShellMobile();
 
+  // A disabled item renders as a plain <a> with no href: an href-less anchor
+  // is not focusable and exposes no link affordance, so programmatic focus +
+  // Enter, AT activation commands, and middle-click cannot navigate or fire
+  // the consumer onClick. The router LinkComponent is deliberately skipped —
+  // a disabled item performs no navigation, and custom router links may
+  // require a live href. target is omitted with the href. (Mirrors the
+  // disabled paths of Link and SideNavItem.)
+  const Root = isDisabled ? 'a' : LinkComponent;
+
   // =========================================================================
   // Drawer mode — render as a SideNavItem-style vertical list element
   // =========================================================================
   if (renderMode === 'drawer') {
-    const handleDrawerClick = (e: React.MouseEvent) => {
+    const handleDrawerClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
       if (isDisabled) {
+        preventDefaultClick(e);
         return;
       }
       // Forward the original onClick if present
-      (props as {onClick?: (e: React.MouseEvent) => void}).onClick?.(e);
+      onClick?.(e);
       closeMobileNav();
     };
 
     return (
-      <LinkComponent
+      <Root
         ref={ref}
+        href={isDisabled ? undefined : href}
+        target={isDisabled ? undefined : target}
         aria-label={isIconOnly ? label : undefined}
         aria-current={isSelected ? 'page' : undefined}
         aria-disabled={isDisabled || undefined}
@@ -235,7 +261,7 @@ export function TopNavItem({
         onClick={handleDrawerClick}>
         {icon}
         {!isIconOnly && (children ?? label)}
-      </LinkComponent>
+      </Root>
     );
   }
 
@@ -244,8 +270,11 @@ export function TopNavItem({
   // =========================================================================
 
   return (
-    <LinkComponent
+    <Root
       ref={ref}
+      href={isDisabled ? undefined : href}
+      target={isDisabled ? undefined : target}
+      onClick={isDisabled ? preventDefaultClick : onClick}
       aria-label={isIconOnly ? label : undefined}
       aria-current={isSelected ? 'page' : undefined}
       aria-disabled={isDisabled || undefined}
@@ -267,7 +296,7 @@ export function TopNavItem({
       {...props}>
       {icon}
       {!isIconOnly && (children ?? label)}
-    </LinkComponent>
+    </Root>
   );
 }
 

package/src/TopNav/TopNavMegaMenu.tsx

@@ -123,6 +123,18 @@ const styles = stylex.create({
       transform: 'translateY(-4px)',
     },
   },
+  // Clamp the anchored layer to the space available below the nav so a tall
+  // menu never runs off the bottom of the viewport. The layer is positioned
+  // with position-area: self-block-end, so its containing block spans from
+  // the nav's block-end to the viewport edge — 100% is exactly that space.
+  // The layer is a flex column so panelContainer can shrink and scroll its
+  // own content, keeping the surface radius/shadow static at the edges.
+  // Internal scroll is a stopgap until the mobile bottom-sheet lands.
+  panelViewportFit: {
+    display: 'flex',
+    flexDirection: 'column',
+    maxHeight: `calc(100% - ${spacingVars['--spacing-3']})`,
+  },
   // Visual styles for the panel content container.
   panelContainer: {
     backgroundColor: colorVars['--color-background-popover'],
@@ -132,6 +144,11 @@ const styles = stylex.create({
     borderRadius: radiusVars['--radius-container'],
     boxShadow: shadowVars['--shadow-low'],
     overflow: 'hidden',
+    // Allow the container to shrink inside the height-clamped layer so its
+    // content (panelContent) can scroll rather than overflow the viewport.
+    display: 'flex',
+    flexDirection: 'column',
+    minHeight: 0,
   },
   panelContent: {
     display: 'flex',
@@ -139,7 +156,14 @@ const styles = stylex.create({
     gap: spacingVars['--spacing-6'],
     paddingBlock: spacingVars['--spacing-3'],
     paddingInline: spacingVars['--spacing-3'],
-    maxWidth: 960,
+    // Clamp to the viewport (minus a gutter) so the anchored panel never
+    // overflows the screen edge on narrow viewports; caps at 960px otherwise.
+    maxWidth: `min(960px, calc(100dvw - ${spacingVars['--spacing-4']}))`,
+    boxSizing: 'border-box',
+    // Scroll internally when the menu is taller than the available space
+    // below the nav (paired with panelViewportFit on the layer).
+    overflowY: 'auto',
+    overscrollBehavior: 'contain',
   },
   menuWrapper: {
     flexGrow: 2,
@@ -484,7 +508,7 @@ function DefaultMegaMenu({
         {
           placement: 'below',
           alignment: slot,
-          xstyle: styles.panelAnimation,
+          xstyle: [styles.panelAnimation, styles.panelViewportFit],
         },
       )}
     </>

package/src/TopNav/TopNavMegaMenuFeaturedCard.doc.mjs

@@ -27,7 +27,7 @@ export const docs = {
     {
       name: 'imageAlt',
       type: 'string',
-      description: 'Alt text for the image. When omitted, the image is explicitly decorative (alt="", role="presentation", aria-hidden) — usually correct since the card already has a visible title. Provide it only when the image conveys information beyond the title and description.',
+      description: 'Alt text for the image. When omitted, the image is explicitly decorative (alt="", role="presentation", aria-hidden), usually correct since the card already has a visible title. Provide it only when the image conveys information beyond the title and description.',
     },
     {
       name: 'linkLabel',

package/src/TreeList/TreeList.doc.mjs

@@ -30,6 +30,9 @@ export const docs = {
       {className: 'astryx-tree-list-item-label', states: ['selected']},
       {className: 'astryx-tree-list-guide'},
     ],
+    vars: [
+      {name: '--tree-list-indent', description: 'Per-level indentation step. Each nesting level indents its rows by this distance, and the guide lines follow it so they stay aligned. Set it on the `tree-list` target to retune the metric (e.g. `var(--spacing-5)` for a wider indent).', default: 'var(--spacing-4)'},
+    ],
   },
   components: [
     {
@@ -104,6 +107,9 @@ export const docsZh = {
       {className: 'astryx-tree-list-item-label', states: ['selected']},
       {className: 'astryx-tree-list-guide'},
     ],
+    vars: [
+      {name: '--tree-list-indent', description: '每级缩进步长。每个嵌套层级的行按此距离缩进，引导线随之对齐。在 `tree-list` 目标上设置以调整该度量（例如用 `var(--spacing-5)` 获得更宽的缩进）。', default: 'var(--spacing-4)'},
+    ],
   },
   components: [
     {

package/src/TreeList/TreeList.test.tsx

@@ -431,26 +431,29 @@ describe('TreeList', () => {
     });
 
     it("variant='noGuides' preserves per-level indentation on the rows", () => {
-      // Indentation lives on the row's marginLeft (not the guide element), so
-      // it must survive when the connectors are suppressed. A deeper row is
-      // indented more than a shallower one.
+      // Indentation lives on the row's margin-inline-start (not the guide
+      // element), so it must survive when the connectors are suppressed. The
+      // per-row distance is published as the `--_tree-indent` custom property
+      // (not an inline longhand — see #4308), so the theme layer can override
+      // the `margin-inline-start` declaration. A deeper row is indented more
+      // than a shallower one.
       const {container} = render(
         <TreeList items={deepItems} variant="noGuides" />,
       );
-      const marginOf = (text: string): string => {
+      const indentOf = (text: string): string => {
         const li = screen.getByText(text).closest('li')!;
-        const styled = li.querySelector('[style*="margin-left"]');
+        const styled = li.querySelector('[style*="--_tree-indent"]');
         return styled?.getAttribute('style') ?? '';
       };
       // Guides are gone…
       expect(container.querySelector('.astryx-tree-list-guide')).toBeNull();
-      // …but each level still carries an inline margin-left, and the level
+      // …but each level still publishes an indent distance, and the level
       // multiplier grows with depth (0, 1, 2).
-      expect(marginOf('Root')).toContain('margin-left');
-      expect(marginOf('Mid')).toContain('margin-left');
-      expect(marginOf('Leaf')).toContain('margin-left');
+      expect(indentOf('Root')).toContain('--_tree-indent');
+      expect(indentOf('Mid')).toContain('--_tree-indent');
+      expect(indentOf('Leaf')).toContain('--_tree-indent');
       const level = (text: string): number => {
-        const m = /calc\((\d+)/.exec(marginOf(text));
+        const m = /calc\((\d+)/.exec(indentOf(text));
         return m ? Number(m[1]) : NaN;
       };
       expect(level('Mid')).toBeGreaterThan(level('Root'));
@@ -504,6 +507,43 @@ describe('TreeList', () => {
     });
   });
 
+  // ===========================================================================
+  // Indent lever (--tree-list-indent)
+  // ===========================================================================
+
+  describe('indent lever', () => {
+    it('lets a theme retune the indent step via the tree-list target', () => {
+      // The per-level step is a public, themeable var (default --spacing-4) set
+      // on the tree-list root, so a theme can retune the indent metric (e.g. to
+      // --spacing-5) via defineTheme. jsdom cannot resolve the @layer cascade,
+      // so the generated CSS is what proves the override reaches the lever.
+      const theme = defineTheme({
+        name: 'tree-list-indent-test',
+        components: {
+          'tree-list': {
+            base: {'--tree-list-indent': 'var(--spacing-5)'},
+          },
+        },
+      });
+      const css = generateThemeCSSFlat(theme);
+      expect(css).toContain('.astryx-tree-list {');
+      expect(css).toContain('--tree-list-indent: var(--spacing-5)');
+    });
+
+    it('rows consume the indent step in their published indent distance', () => {
+      // Each row's --_tree-indent is calc(level * var(--tree-list-indent)),
+      // so retuning the step scales every level uniformly.
+      render(<TreeList items={deepItems} variant="noGuides" />);
+      const indentOf = (text: string): string => {
+        const li = screen.getByText(text).closest('li')!;
+        const styled = li.querySelector('[style*="--_tree-indent"]');
+        return styled?.getAttribute('style') ?? '';
+      };
+      expect(indentOf('Mid')).toContain('var(--tree-list-indent)');
+      expect(indentOf('Leaf')).toContain('var(--tree-list-indent)');
+    });
+  });
+
   // ===========================================================================
   // xds class name
   // ===========================================================================

package/src/TreeList/TreeList.tsx

@@ -83,6 +83,11 @@ export interface TreeListProps extends BaseProps<HTMLDivElement> {
 const styles = stylex.create({
   root: {
     position: 'relative',
+    // Per-level indentation step. Public, themeable lever: a theme can retune
+    // the tree's indent metric (e.g. to `var(--spacing-5)`) via `defineTheme`
+    // on the `tree-list` target, and both the row margins (TreeListItem) and
+    // the guide-line offsets (TreeListBranches) read it so they stay aligned.
+    '--tree-list-indent': spacingVars['--spacing-4'],
   },
   list: {
     margin: 0,

package/src/TreeList/TreeListBranches.tsx

@@ -26,8 +26,10 @@ const LINE_WIDTH = 1;
  */
 const BRANCH_MARGIN = `calc(${spacingVars['--spacing-2']} + ${spacingVars['--spacing-0-5']})`;
 
-/** Per-level indent width, matching --spacing-4 (16px). */
-const LEVEL_INDENT = spacingVars['--spacing-4'];
+/** Per-level indent width. Reads the public, themeable `--tree-list-indent`
+ * lever set on the tree-list root (default `--spacing-4`, 16px), so the guide
+ * lines stay aligned with the row indent when a theme retunes the step. */
+const LEVEL_INDENT = 'var(--tree-list-indent)';
 
 const styles = stylex.create({
   container: {
@@ -37,10 +39,10 @@ const styles = stylex.create({
   },
   verticalLine: {
     borderRadius: 1,
-    left: 0,
+    insetInlineStart: 0,
     margin: 'auto',
     position: 'absolute',
-    right: 0,
+    insetInlineEnd: 0,
     width: LINE_WIDTH,
     backgroundColor: colorVars['--color-border-emphasized'],
   },
@@ -92,7 +94,7 @@ export function TreeListBranches({
               key={level}
               {...mergeProps(stylex.props(styles.container), {
                 style: {
-                  left: branchOffset,
+                  insetInlineStart: branchOffset,
                 },
               })}>
               <div
@@ -109,7 +111,7 @@ export function TreeListBranches({
         <div
           {...mergeProps(stylex.props(styles.container), {
             style: {
-              left: `calc(${BRANCH_MARGIN} + ${nestedLevel - 1} * ${LEVEL_INDENT})`,
+              insetInlineStart: `calc(${BRANCH_MARGIN} + ${nestedLevel - 1} * ${LEVEL_INDENT})`,
             },
           })}>
           <div

package/src/TreeList/TreeListItem.tsx

@@ -25,7 +25,7 @@ import {
   typeScaleVars,
 } from '../theme/tokens.stylex';
 import {getIcon} from '../Icon/globalIconRegistry';
-import {mergeProps} from '../utils';
+import {mergeProps, rtlStyles} from '../utils';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import {TreeListBranches} from './TreeListBranches';
 import type {TreeListDensity, TreeListVariant} from './TreeListTypes';
@@ -82,6 +82,12 @@ const styles = stylex.create({
     position: 'relative',
     boxSizing: 'border-box',
     textAlign: 'start',
+    // Per-level indent. Declared here (not inline) so it lives in
+    // `@layer astryx-base` and the theme layer can override it in normal
+    // cascade order — an inline longhand would outrank every layer. The row
+    // publishes only the computed distance as `--_tree-indent`; the per-level
+    // step is the public `--tree-list-indent` lever (see TreeList `root`).
+    marginInlineStart: 'var(--_tree-indent, 0px)',
   },
   interactive: {
     cursor: 'pointer',
@@ -246,6 +252,11 @@ const descriptionSizeStyles = stylex.create({
   },
 });
 
+// `CSSProperties` has no index signature for custom properties, so the row's
+// inline style — which publishes the computed indent distance as the private
+// `--_tree-indent` — needs this augmentation to typecheck.
+type IndentStyle = React.CSSProperties & Record<'--_tree-indent', string>;
+
 // =============================================================================
 // Types
 // =============================================================================
@@ -353,9 +364,18 @@ export function TreeListItem({
     return undefined;
   }, [onClick, hasChildren, onToggle, id, isDisabled]);
 
-  const computedMarginLeft = hasChildren
-    ? `calc(${nestedLevel} * ${spacingVars['--spacing-4']})`
-    : `calc(${nestedLevel} * ${spacingVars['--spacing-4']} + ${spacingVars['--spacing-4']} + ${spacingVars['--spacing-2']})`;
+  // Per-level indent distance. The per-level step is the public, themeable
+  // `--tree-list-indent` lever (default `--spacing-4`, set on the tree-list
+  // root). Leaves add a fixed chevron-column offset (chevron width + gap) so
+  // their labels line up with sibling parents' labels; that offset is tied to
+  // the chevron's own dimensions, not the indent step, so it does not scale
+  // with the lever. Published as the private `--_tree-indent` and consumed by
+  // `contentWrapper`'s stylesheet `margin-inline-start` (kept out of the inline
+  // style so the theme layer can override it — see #4308).
+  const indentDistance = hasChildren
+    ? `calc(${nestedLevel} * var(--tree-list-indent))`
+    : `calc(${nestedLevel} * var(--tree-list-indent) + ${spacingVars['--spacing-4']} + ${spacingVars['--spacing-2']})`;
+  const indentStyle: IndentStyle = {'--_tree-indent': indentDistance};
 
   const labelAndDescription = (
     <>
@@ -386,12 +406,14 @@ export function TreeListItem({
   );
 
   const chevronIcon = (
-    <span
-      {...stylex.props(
-        styles.chevronSvg,
-        isExpanded ? styles.chevronExpanded : styles.chevronCollapsed,
-      )}>
-      {getIcon('chevronRight')}
+    <span {...stylex.props(rtlStyles.mirror)}>
+      <span
+        {...stylex.props(
+          styles.chevronSvg,
+          isExpanded ? styles.chevronExpanded : styles.chevronCollapsed,
+        )}>
+        {getIcon('chevronRight')}
+      </span>
     </span>
   );
 
@@ -527,7 +549,7 @@ export function TreeListItem({
               isSelected && styles.selected,
             ),
           )}
-          style={{marginLeft: computedMarginLeft}}
+          style={indentStyle}
           onClick={handleClick}>
           {innerContent}
         </div>