@astryxdesign/core 0.7.1 → 0.7.2-canary.01eab6a

package/src/TreeList/TreeList.spec.md

@@ -96,14 +96,15 @@ Supporting one does not justify omitting another from the durable contract.
 
 ## Behavioral and layout contract
 
-| ID  | Invariant                                                                                                                                                                                                                                                                 | Basis                                                                               | Contract state                                      |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------- |
-| FR1 | The current render contains one Tree list, one Item and Item label per rendered node, optional Header, Chevron, Item description, Start content, End content, and Guide parts, and delegated Chevron glyphs.                                                              | Current source, docs, and tests                                                     | Current behavior                                    |
-| FR2 | Tree list, Item, Chevron, Item label, and Guide carry the five current `tree-list*` targets documented below.                                                                                                                                                             | Current source and target docs                                                      | Current behavior                                    |
-| FR3 | Chevron glyph delegates to Icon's `icon` target. Header, Start content, and End content are consumer-owned and have no TreeList target.                                                                                                                                   | Current source and component docs                                                   | Current ownership                                   |
-| FR4 | Item description is a stable library-rendered part below Item label and currently has no public target. It does not inherit through `tree-list-item-label`; both spans are siblings inside the row content.                                                               | Current source and target docs                                                      | Current reachability gap; no new target is accepted |
-| FR5 | `TreeListItemData` MUST admit `className`, `style`, and `xstyle` as one per-item styling seam. Every supplied value MUST compose on the same Item row box; an implementation MUST NOT treat current support for only one mechanism as authority to exclude the other two. | Owner decision; `architecture:public-component-api` INV5–INV6; `spec:AST-002/DEC-1` | Settled intent; implementation may be staged        |
-| FR6 | The Item row box is the logical element that paints the row, owns its hover state, and contains Start content, Item label and description, and End content. The styling seam MUST NOT move to the semantic `<li>` or another element without a compatibility decision.    | Owner decision and the caller-owned per-row interaction boundary                    | Settled intent                                      |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Basis                                                                               | Contract state                                      |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------- |
+| FR1 | The current render contains one Tree list, one Item and Item label per rendered node, optional Header, Chevron, Item description, Start content, End content, and Guide parts, and delegated Chevron glyphs.                                                                                                                                                                                                                                                              | Current source, docs, and tests                                                     | Current behavior                                    |
+| FR2 | Tree list, Item, Chevron, Item label, and Guide carry the five current `tree-list*` targets documented below.                                                                                                                                                                                                                                                                                                                                                             | Current source and target docs                                                      | Current behavior                                    |
+| FR3 | Chevron glyph delegates to Icon's `icon` target. Header, Start content, and End content are consumer-owned and have no TreeList target.                                                                                                                                                                                                                                                                                                                                   | Current source and component docs                                                   | Current ownership                                   |
+| FR4 | Item description is a stable library-rendered part below Item label and currently has no public target. It does not inherit through `tree-list-item-label`; both spans are siblings inside the row content.                                                                                                                                                                                                                                                               | Current source and target docs                                                      | Current reachability gap; no new target is accepted |
+| FR5 | `TreeListItemData` MUST admit `className`, `style`, and `xstyle` as one per-item styling seam. Every supplied value MUST compose on the same Item row box; an implementation MUST NOT treat current support for only one mechanism as authority to exclude the other two.                                                                                                                                                                                                 | Owner decision; `architecture:public-component-api` INV5–INV6; `spec:AST-002/DEC-1` | Settled intent; implementation may be staged        |
+| FR6 | The Item row box is the logical element that paints the row, owns its hover state, and contains Start content, Item label and description, and End content. The styling seam MUST NOT move to the semantic `<li>` or another element without a compatibility decision.                                                                                                                                                                                                    | Owner decision and the caller-owned per-row interaction boundary                    | Settled intent                                      |
+| FR7 | A click on an Item row outside its Item label performs the row's action: an Item with `onClick` runs it; otherwise an Item with children toggles; otherwise an Item whose only action is its link follows that link as Enter does, with modified and middle clicks following the shared enlarged-surface rule in `family:navigation-destinations`. The Chevron and controls in Start content and End content keep their own activation, and a disabled Item does nothing. | Owner decision; `family:navigation-destinations`                                    | Settled intent; implementation may be staged        |
 
 ### Allowed variation
 
@@ -183,6 +184,16 @@ structure. Its current lack of a target is a reachability gap, not a decision
 that it must remain unthemeable. Header, Start content, and End content remain
 caller-owned even though TreeList positions their slot wrappers.
 
+### Design decisions
+
+<!-- design-decisions:v1 -->
+
+| ID  | Decision                                                                                                                     | Intent or reason                                                                                                                                                                                               | Applies to                                                                             | Allowed variation                                                                                                                                                 |
+| --- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| DD1 | Every Item spans the full width of the tree list at any depth; its nesting indent sits inside the row, ahead of its content. | Hover, pressed, and selected fills line up across depths, so the tree reads as one list of equal rows while labels keep their per-level alignment.                                                             | Item at every depth, at rest and through hover, pressed, selected, disabled, and focus | Themes set the indent step with `--tree-list-indent` and may restyle the row's fill, radius, and padding; row padding adds to the indent instead of replacing it. |
+| DD2 | A nested Item's indent area is part of the row's painted target: it shows the row's hover and press feedback.                | The whole painted row reads as one target, matching where a click acts (FR7), so no part of a row lights up apart from the rest.                                                                               | Nested Items that act on click                                                         | Themes may restyle the feedback through the `tree-list-item` target.                                                                                              |
+| DD3 | Guides paint above row fills, and an Item whose focus ring is showing paints above the guides.                               | Hierarchy lines stay continuous through hover and selection, and the focus indicator is never cut; on a focused row that is also filled, the ring takes precedence and the fill covers the guides at that row. | Guide and Item in `lineGuides` trees                                                   | Themes may recolor or hide guides through the `tree-list-guide` target.                                                                                           |
+
 ### Theming anatomy
 
 <!-- anatomy-theming:v1 -->
@@ -242,15 +253,16 @@ authorize or prohibit a future target.
 
 ## Verification map
 
-| Contract            | Verification                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Representative states                                                                  | Mutation or failure expectation                                                                                                                                                                                                                     | Audit section                  |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
-| FR1                 | `TreeList.test.tsx` rendering, hierarchy, slot, and accessibility suites plus source inspection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Flat, nested, described, headed, and slotted items                                     | Removing asserted Tree list, Header, Item, Chevron, Item label, Item description, Start content, End content, or Guide behavior fails existing role, content, hierarchy, or state assertions; Chevron glyph presence remains source-inspected only. | `audit:TreeList/anatomy`       |
-| FR2                 | `TreeList.test.tsx` and `themingTargets.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Five local targets and their documented states                                         | Removing or moving any current local target fails focused class assertions or the global inventory.                                                                                                                                                 | `audit:TreeList/theming`       |
-| FR3                 | Source inspection plus Icon public target metadata                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Expandable rows and caller-provided slots                                              | Existing focused tests do not assert the composed Icon instance; changing glyph or slot ownership requires this map and the relevant owner metadata to change.                                                                                      | `audit:TreeList/theming`       |
-| FR4                 | `TreeList.test.tsx` description rendering test and source inspection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Item with description                                                                  | Removing description fails content coverage; adding a target requires an explicit map update.                                                                                                                                                       | `audit:TreeList/anatomy`       |
-| AR1                 | Tree View accessibility contract (`internal/a11y-spec`, pending) bound to TreeList, in jsdom and Chromium; `TreeList.test.tsx` row-naming cases ("names a parent row by its label alone, not the chevron toggle", "names a plain row by its label and describes it with its description", "names and describes link and action rows themselves, not only their inner control", "keeps start and end content, including controls, out of the row name", "typeahead matches the label, not the description or start content") and `TreeListRowNames.a11y.chromium.spec.ts` for the browser-computed names; `TreeList.test.tsx` structural ARIA cases ("sets aria-level, aria-posinset, and aria-setsize at the top level", "sets aria-level/posinset/setsize correctly at deeper levels", "sets aria-level across three depths"); `TreeList.test.tsx` and `useTreeFocus.test.tsx` keyboard suites | Flat and nested trees; expanded/collapsed; selected/unselected; LTR and RTL; typeahead | A row loses its role, label name, state or position, two rows hold a Tab stop, an arrow key stops moving or stops mirroring under RTL, Home/End or typeahead stop working, or the tree claims multi-select                                          | `audit:TreeList/accessibility` |
-| FR5, FR6, ORD1      | Focused `TreeList.test.tsx` row-identity and styling-composition coverage, required with implementation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | One input at a time; all three together; sibling rows                                  | Dropping any mechanism, applying mechanisms to different elements, targeting the `<li>`, changing the merge order, or styling a sibling row fails.                                                                                                  | `audit:TreeList/api`           |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Canonical anatomy and five current local targets                                       | Missing, extra, duplicated, prefixed, or stale mappings fail repository validation.                                                                                                                                                                 | `audit:TreeList/theming`       |
+| Contract            | Verification                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Representative states                                                                                                                                                | Mutation or failure expectation                                                                                                                                                                                                                     | Audit section                  |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
+| FR1                 | `TreeList.test.tsx` rendering, hierarchy, slot, and accessibility suites plus source inspection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Flat, nested, described, headed, and slotted items                                                                                                                   | Removing asserted Tree list, Header, Item, Chevron, Item label, Item description, Start content, End content, or Guide behavior fails existing role, content, hierarchy, or state assertions; Chevron glyph presence remains source-inspected only. | `audit:TreeList/anatomy`       |
+| FR2                 | `TreeList.test.tsx` and `themingTargets.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Five local targets and their documented states                                                                                                                       | Removing or moving any current local target fails focused class assertions or the global inventory.                                                                                                                                                 | `audit:TreeList/theming`       |
+| FR3                 | Source inspection plus Icon public target metadata                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Expandable rows and caller-provided slots                                                                                                                            | Existing focused tests do not assert the composed Icon instance; changing glyph or slot ownership requires this map and the relevant owner metadata to change.                                                                                      | `audit:TreeList/theming`       |
+| FR4                 | `TreeList.test.tsx` description rendering test and source inspection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Item with description                                                                                                                                                | Removing description fails content coverage; adding a target requires an explicit map update.                                                                                                                                                       | `audit:TreeList/anatomy`       |
+| AR1                 | Tree View accessibility contract (`internal/a11y-spec`, pending) bound to TreeList, in jsdom and Chromium; `TreeList.test.tsx` row-naming cases ("names a parent row by its label alone, not the chevron toggle", "names a plain row by its label and describes it with its description", "names and describes link and action rows themselves, not only their inner control", "keeps start and end content, including controls, out of the row name", "typeahead matches the label, not the description or start content") and `TreeListRowNames.a11y.chromium.spec.ts` for the browser-computed names; `TreeList.test.tsx` structural ARIA cases ("sets aria-level, aria-posinset, and aria-setsize at the top level", "sets aria-level/posinset/setsize correctly at deeper levels", "sets aria-level across three depths"); `TreeList.test.tsx` and `useTreeFocus.test.tsx` keyboard suites | Flat and nested trees; expanded/collapsed; selected/unselected; LTR and RTL; typeahead                                                                               | A row loses its role, label name, state or position, two rows hold a Tab stop, an arrow key stops moving or stops mirroring under RTL, Home/End or typeahead stop working, or the tree claims multi-select                                          | `audit:TreeList/accessibility` |
+| FR5, FR6, ORD1      | Focused `TreeList.test.tsx` row-identity and styling-composition coverage, required with implementation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | One input at a time; all three together; sibling rows                                                                                                                | Dropping any mechanism, applying mechanisms to different elements, targeting the `<li>`, changing the merge order, or styling a sibling row fails.                                                                                                  | `audit:TreeList/api`           |
+| FR7                 | Focused `TreeList.test.tsx` row-click coverage, required with implementation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Action, parent, link, and disabled rows; clicks in the indent and padding, on the Chevron, and on Start and End content controls; plain, modified, and middle clicks | A click outside the label does nothing or runs the wrong action, a link-row click reaches ancestors twice, the Chevron or a Start or End content control activates the row, or a disabled row acts.                                                 | `audit:TreeList/behavior`      |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Canonical anatomy and five current local targets                                                                                                                     | Missing, extra, duplicated, prefixed, or stale mappings fail repository validation.                                                                                                                                                                 | `audit:TreeList/theming`       |
 
 Focused target-placement assertions cover all five local targets. Runtime support
 and mutation-sensitive coverage for the item styling seam may land separately,

package/src/TreeList/TreeList.test.tsx

@@ -11,6 +11,7 @@
 
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
+import type {ReactNode} from 'react';
 import userEvent from '@testing-library/user-event';
 import * as stylex from '@stylexjs/stylex';
 import {TreeList} from './TreeList';
@@ -609,12 +610,12 @@ describe('TreeList', () => {
     });
 
     it("variant='noGuides' preserves per-level indentation on the rows", () => {
-      // 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.
+      // Indentation lives inside the row's padding-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 `padding-inline-start` declaration. A deeper
+      // row is indented more than a shallower one.
       const {container} = render(
         <TreeList items={deepItems} variant="noGuides" />,
       );
@@ -720,6 +721,326 @@ describe('TreeList', () => {
       expect(indentOf('Mid')).toContain('var(--tree-list-indent)');
       expect(indentOf('Leaf')).toContain('var(--tree-list-indent)');
     });
+
+    it('indents inside the row so nested rows keep the full list width', () => {
+      // The row box keeps its own inline padding and stays full width; the
+      // indent is padding on a child inside it. A nested row's hover and
+      // selected fill therefore spans the list like a root row's, while its
+      // content lands where a margin indent would have put it.
+      render(<TreeList items={deepItems} />);
+      const rules = collectCssText();
+      expect(rules).toMatch(
+        /padding-inline-start:\s*var\(--_tree-indent,\s*0px\)/,
+      );
+      expect(rules).not.toMatch(/margin-inline-start:\s*var\(--_tree-indent/);
+
+      const row = screen
+        .getByText('Leaf')
+        .closest<HTMLElement>('.astryx-tree-list-item')!;
+      const indented = row.firstElementChild as HTMLElement;
+      expect(indented.className).toContain('indentedContent');
+      expect(row.className).not.toContain('indentedContent');
+    });
+
+    it("keeps the indent when a caller sets the row's padding", () => {
+      // Caller padding lands on the row box; the indent is on a separate
+      // element inside it, so the two compose instead of one replacing the
+      // other.
+      const items = [
+        {
+          id: 'root',
+          label: 'Root',
+          isExpanded: true,
+          children: [
+            {id: 'leaf', label: 'Leaf', style: {paddingInlineStart: '20px'}},
+          ],
+        },
+      ];
+      render(<TreeList items={items} />);
+      const row = screen
+        .getByText('Leaf')
+        .closest<HTMLElement>('.astryx-tree-list-item')!;
+      expect(row.style.paddingInlineStart).toBe('20px');
+      expect(row.getAttribute('style')).toContain('--_tree-indent');
+      expect((row.firstElementChild as HTMLElement).className).toContain(
+        'indentedContent',
+      );
+    });
+
+    describe('link rows', () => {
+      const linkItems = (endContent?: ReactNode): TreeListItemData[] => [
+        {
+          id: 'docs',
+          label: 'Docs',
+          isExpanded: true,
+          children: [
+            {id: 'report', label: 'Report', href: '/report', endContent},
+          ],
+        },
+      ];
+      const rowSurfaceOf = (link: HTMLElement) =>
+        link.closest<HTMLElement>('.astryx-tree-list-item')!
+          .firstElementChild as HTMLElement;
+
+      it('follows the link when the row is clicked outside its label', () => {
+        // The indent is part of the row now, so a click there must do what
+        // the row does. The click is delegated to the anchor through the
+        // shared enlarged-surface hook, modifier keys included.
+        render(<TreeList items={linkItems()} />);
+        const link = screen.getByRole('link', {name: 'Report'});
+        const clicks: MouseEvent[] = [];
+        link.addEventListener('click', e => {
+          clicks.push(e);
+          e.preventDefault();
+        });
+
+        fireEvent.click(rowSurfaceOf(link), {metaKey: true});
+        expect(clicks).toHaveLength(1);
+        expect(clicks[0].metaKey).toBe(true);
+
+        // The row box's own padding follows the link too.
+        fireEvent.click(rowSurfaceOf(link).parentElement!);
+        expect(clicks).toHaveLength(2);
+
+        // Clicking the label itself reaches the anchor once, not twice.
+        fireEvent.click(link);
+        expect(clicks).toHaveLength(3);
+      });
+
+      it('reports one click to ancestors per press', () => {
+        // The delegated click bubbles from the anchor; the original stops,
+        // so a listener above the tree sees exactly one click.
+        const onTreeClick = vi.fn();
+        render(<TreeList items={linkItems()} onClick={onTreeClick} />);
+        const link = screen.getByRole('link', {name: 'Report'});
+        link.addEventListener('click', e => e.preventDefault());
+
+        fireEvent.click(rowSurfaceOf(link));
+        expect(onTreeClick).toHaveBeenCalledTimes(1);
+        expect(onTreeClick.mock.calls[0][0].target).toBe(link);
+      });
+
+      it('leaves a role-based control in the row to itself', () => {
+        const onSwitch = vi.fn();
+        render(
+          <TreeList
+            items={linkItems(
+              <span
+                role="switch"
+                aria-checked="false"
+                aria-label="Pin"
+                tabIndex={0}
+                onClick={onSwitch}>
+                Pin
+              </span>,
+            )}
+          />,
+        );
+        const link = screen.getByRole('link', {name: 'Report'});
+        const onLinkClick = vi.fn((e: Event) => e.preventDefault());
+        link.addEventListener('click', onLinkClick);
+
+        fireEvent.click(screen.getByRole('switch', {name: 'Pin'}));
+        expect(onSwitch).toHaveBeenCalledTimes(1);
+        expect(onLinkClick).not.toHaveBeenCalled();
+      });
+
+      it('opens the link in a new tab on a middle-click in the row', () => {
+        const open = vi.spyOn(window, 'open').mockImplementation(() => null);
+        render(<TreeList items={linkItems()} />);
+        const link = screen.getByRole('link', {name: 'Report'});
+
+        fireEvent.mouseUp(rowSurfaceOf(link), {button: 1});
+        expect(open).toHaveBeenCalledWith('/report', '_blank', 'noopener');
+
+        // A middle-click on the label is the browser's own.
+        open.mockClear();
+        fireEvent.mouseUp(link, {button: 1});
+        expect(open).not.toHaveBeenCalled();
+        open.mockRestore();
+      });
+    });
+
+    it('does not follow a disabled link row', () => {
+      const items = [
+        {
+          id: 'docs',
+          label: 'Docs',
+          isExpanded: true,
+          children: [
+            {id: 'report', label: 'Report', href: '/report', isDisabled: true},
+          ],
+        },
+      ];
+      render(<TreeList items={items} />);
+      const link = screen.getByRole('link', {name: 'Report', hidden: true});
+      const onLinkClick = vi.fn((e: Event) => e.preventDefault());
+      link.addEventListener('click', onLinkClick);
+      const row = link.closest<HTMLElement>('.astryx-tree-list-item')!;
+      fireEvent.click(row.firstElementChild!);
+      expect(onLinkClick).not.toHaveBeenCalled();
+    });
+
+    describe('row clicks outside the label (FR7)', () => {
+      // Each row sits under an expanded root, so it has an indent; the click
+      // lands on the row surface (indent, reserved chevron column, padding),
+      // not on the label.
+      const underRoot = (children: TreeListItemData[]): TreeListItemData[] => [
+        {id: 'root', label: 'Root', isExpanded: true, children},
+      ];
+      // The row box itself (its own padding) and the indented content inside
+      // it: FR7 covers clicks on both.
+      const rowOf = (label: string) =>
+        screen.getByText(label).closest<HTMLElement>('.astryx-tree-list-item')!;
+      const rowSurfaceOf = (label: string) =>
+        rowOf(label).firstElementChild as HTMLElement;
+      const folder: TreeListItemData = {
+        id: 'folder',
+        label: 'Folder',
+        children: [{id: 'file', label: 'File'}],
+      };
+
+      it("runs an action row's onClick once", () => {
+        const onClick = vi.fn();
+        render(
+          <TreeList items={underRoot([{id: 'run', label: 'Run', onClick}])} />,
+        );
+        fireEvent.click(rowSurfaceOf('Run'));
+        expect(onClick).toHaveBeenCalledTimes(1);
+        fireEvent.click(rowOf('Run'));
+        expect(onClick).toHaveBeenCalledTimes(2);
+
+        // The label's own button still runs it once per press, not twice.
+        fireEvent.click(screen.getByRole('button', {name: 'Run'}));
+        expect(onClick).toHaveBeenCalledTimes(3);
+      });
+
+      it('toggles a parent row', () => {
+        render(<TreeList items={underRoot([folder])} />);
+        expect(screen.queryByText('File')).not.toBeInTheDocument();
+        fireEvent.click(rowSurfaceOf('Folder'));
+        expect(screen.getByText('File')).toBeInTheDocument();
+        fireEvent.click(rowOf('Folder'));
+        expect(screen.queryByText('File')).not.toBeInTheDocument();
+      });
+
+      it('does nothing on a disabled action or parent row', () => {
+        const onClick = vi.fn();
+        render(
+          <TreeList
+            items={underRoot([
+              {id: 'run', label: 'Run', onClick, isDisabled: true},
+              {...folder, isDisabled: true},
+            ])}
+          />,
+        );
+        fireEvent.click(rowSurfaceOf('Run'));
+        fireEvent.click(rowOf('Run'));
+        expect(onClick).not.toHaveBeenCalled();
+        fireEvent.click(rowSurfaceOf('Folder'));
+        fireEvent.click(rowOf('Folder'));
+        expect(screen.queryByText('File')).not.toBeInTheDocument();
+      });
+
+      it('leaves a role-based control in start or end content to itself', () => {
+        // Native and role-based controls alike keep their own activation,
+        // the same rule link rows get from the shared enlarged-surface hook.
+        const onClick = vi.fn();
+        const onSwitch = vi.fn();
+        const pin = (name: string) => (
+          <span
+            role="switch"
+            aria-checked="false"
+            aria-label={name}
+            tabIndex={0}
+            onClick={onSwitch}>
+            {name}
+          </span>
+        );
+        render(
+          <TreeList
+            items={underRoot([
+              {
+                id: 'run',
+                label: 'Run',
+                onClick,
+                startContent: pin('Pin run start'),
+                endContent: pin('Pin run end'),
+              },
+              {
+                ...folder,
+                startContent: pin('Pin folder start'),
+                endContent: pin('Pin folder end'),
+              },
+            ])}
+          />,
+        );
+        for (const name of [
+          'Pin run start',
+          'Pin run end',
+          'Pin folder start',
+          'Pin folder end',
+        ]) {
+          fireEvent.click(screen.getByRole('switch', {name}));
+        }
+        expect(onSwitch).toHaveBeenCalledTimes(4);
+        expect(onClick).not.toHaveBeenCalled();
+        expect(screen.queryByText('File')).not.toBeInTheDocument();
+      });
+    });
+
+    it('draws guides above full-width rows without taking pointer input', () => {
+      // Guide columns now sit inside deeper rows' boxes. They paint above the
+      // rows so a row fill never breaks the line, and let clicks fall through
+      // to the row underneath.
+      const {container} = render(<TreeList items={deepItems} />);
+      const guide = container.querySelector('.astryx-tree-list-guide');
+      expect(guide).not.toBeNull();
+      const column = guide!.parentElement!;
+      expect(getComputedStyle(column).pointerEvents).toBe('none');
+      expect(getComputedStyle(column).zIndex).toBe('1');
+      // The tree contains that stacking so a guide cannot climb over
+      // positioned content outside the list.
+      const treeRoot = screen.getByRole('tree').parentElement!;
+      expect(treeRoot.className).toContain('astryx-tree-list');
+      expect(getComputedStyle(treeRoot).isolation).toBe('isolate');
+    });
+
+    it('lifts only rows that draw a focus ring above the guides', () => {
+      // A plain row (no onClick, href or children) draws no focus ring, so it
+      // stays under the guides: a focused selected plain row must not hide
+      // them with its fill (DD3). Rows that draw the ring take the lift.
+      render(
+        <TreeList
+          items={[
+            {
+              id: 'root',
+              label: 'Root',
+              isExpanded: true,
+              children: [
+                {id: 'plain', label: 'Plain', isSelected: true},
+                {id: 'run', label: 'Run', onClick: () => {}},
+              ],
+            },
+          ]}
+        />,
+      );
+      const rowOf = (label: string) =>
+        screen.getByText(label).closest<HTMLElement>('.astryx-tree-list-item')!;
+      expect(rowOf('Plain').className).not.toContain('focusLift');
+      expect(rowOf('Run').className).toContain('focusLift');
+      expect(rowOf('Root').className).toContain('focusLift');
+    });
+
+    it('lifts the focused row above the guides so they never cut its ring', () => {
+      // Each treeitem publishes its own focus as `--_tree-focus-z`, and the
+      // row reads it as its z-index, so the focused row paints above the
+      // guide columns (z-index 1). Nested treeitems redeclare the default.
+      render(<TreeList items={deepItems} />);
+      const rules = collectCssText();
+      expect(rules).toMatch(/--_tree-focus-z:\s*2/);
+      expect(rules).toMatch(/z-index:\s*var\(--_tree-focus-z,\s*auto\)/);
+    });
   });
 
   // ===========================================================================

package/src/TreeList/TreeList.tsx

@@ -83,9 +83,13 @@ export interface TreeListProps extends BaseProps<HTMLDivElement> {
 const styles = stylex.create({
   root: {
     position: 'relative',
+    // Contain the guides' and focused rows' `z-index` (TreeListBranches,
+    // TreeListItem) inside the tree, so they never climb over a sticky header
+    // or other positioned content outside the list.
+    isolation: 'isolate',
     // 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
+    // on the `tree-list` target, and both the row indents (TreeListItem) and
     // the guide-line offsets (TreeListBranches) read it so they stay aligned.
     '--tree-list-indent': spacingVars['--spacing-4'],
     // Vertical gap between adjacent rows. Public, themeable lever (default

package/src/TreeList/TreeListBranches.tsx

@@ -32,10 +32,16 @@ const BRANCH_MARGIN = `calc(${spacingVars['--spacing-2']} + ${spacingVars['--spa
 const LEVEL_INDENT = 'var(--tree-list-indent)';
 
 const styles = stylex.create({
+  // Rows span the full width of the list and carry their indent inside, so
+  // the guide columns sit inside the row boxes of deeper rows. Lift the guides
+  // above the rows so a hovered or selected row's fill never breaks the line,
+  // and let pointer input fall through to the row underneath.
   container: {
     height: '100%',
     position: 'absolute',
     width: spacingVars['--spacing-5'],
+    zIndex: 1,
+    pointerEvents: 'none',
   },
   verticalLine: {
     borderRadius: 1,