Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(core): align TreeList guides to chevrons (#8774)

rubyycheung1c1d0ea248a4
diff --git a/.changeset/tree-list-guide-alignment.md b/.changeset/tree-list-guide-alignment.md
new file mode 100644
index 0000000000..d367eb4053
--- /dev/null
+++ b/.changeset/tree-list-guide-alignment.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] TreeList chevrons and hierarchy guides sit 4px closer to the row's inline start, and the chevron-to-label gap widens from 4px to 8px; labels keep their position.
+
+@rubyycheung
diff --git a/packages/core/src/TreeList/TreeList.spec.md b/packages/core/src/TreeList/TreeList.spec.md
index 29b9429642..40eb45ed01 100644
--- a/packages/core/src/TreeList/TreeList.spec.md
+++ b/packages/core/src/TreeList/TreeList.spec.md
@@ -13,6 +13,7 @@ review_triggers: [public-api, behavior, theming, accessibility]
verified_by:
[
packages/core/src/TreeList/TreeList.test.tsx,
+ packages/core/src/TreeList/__tests__/TreeListGuideAlignment.interaction.browser.spec.ts,
packages/core/src/theme/themingTargets.test.ts,
scripts/check-knowledge.mjs,
]
@@ -205,6 +206,7 @@ caller-owned even though TreeList positions their slot wrappers.
| 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. |
+| DD4 | A Chevron stays in its natural column; a Guide aligns its center to that Chevron rather than moving the control. | Guide visibility is decoration, so switching between `lineGuides` and `noGuides` must not reposition an interactive control. | Chevron and Guide at every depth, in LTR and RTL, across both guide variants | Themes may restyle or hide either part through its target; a theme that moves the Chevron or changes Item padding also owns the corresponding Guide alignment. |
### Theming anatomy
@@ -278,6 +280,7 @@ authorize or prohibit a future target.
| 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` |
| FR8 | Real-browser frame evidence under a finger and a mouse | expand and collapse; a toggle mid-motion; reduced motion; rows after the group, with and without an `animatedLayout` handle | Rows inside the group that jump, travel under a fine pointer without a handle or under reduced motion, an animated property under a fine pointer with reduced motion, a fade under a mouse without a handle, collapsing rows still in the accessibility tree during the slide, layout or paint per frame, or rows after the group moving without a handle fails | `audit:TreeList/behavior` |
| FR9 | `animatedLayoutAdopters.test.tsx` (with and without a handle; `isExpanded` changed in `items` glides; the collapsing group kept inert and out of the keyboard order until its exit ends) and `animatedLayoutAdopters.interaction.browser.spec.ts` (the `Core/Animated layout` story through a ScrollableArea ref, expanding and collapsing) | No handle; a handle; click, keyboard, and `items`-driven changes; expanding and collapsing | The rows after a row jump with a handle, an `items` change lands at once, a collapsing group vanishes before its exit or its rows stay focusable during it, or anything changes without a handle | `audit:TreeList/behavior` |
+| DD4 | `TreeListGuideAlignment.interaction.browser.spec.ts` measures Chevron logical-start placement and Guide/Chevron center alignment in the built Fully Expanded story. | `lineGuides` and `noGuides`; LTR and RTL | Reintroducing Chevron edge margins, moving a Chevron when guides are hidden, or placing a Guide off the Chevron center fails the browser geometry assertions. | `audit:TreeList/anatomy` |
| 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
diff --git a/packages/core/src/TreeList/TreeListBranches.tsx b/packages/core/src/TreeList/TreeListBranches.tsx
index f505dc59c7..bcb80b0568 100644
--- a/packages/core/src/TreeList/TreeListBranches.tsx
+++ b/packages/core/src/TreeList/TreeListBranches.tsx
@@ -19,12 +19,14 @@ import {mergeProps} from '../utils';
import {themeProps} from '../utils/themeProps';
const LINE_WIDTH = 1;
+const GUIDE_COLUMN_WIDTH = spacingVars['--spacing-5'];
/**
- * Branch margin from the left edge. No exact spacing token for 10px,
- * so we use calc(--spacing-2 + --spacing-0-5) = 8 + 2 = 10.
+ * The guide owns its alignment to the chevron column. Its 20px container starts
+ * where centering it on the natural 16px chevron leaves it after the row's 8px
+ * inline padding: 8px + 16px / 2 - 20px / 2 = 6px.
*/
-const BRANCH_MARGIN = `calc(${spacingVars['--spacing-2']} + ${spacingVars['--spacing-0-5']})`;
+const GUIDE_COLUMN_START = `calc(${spacingVars['--spacing-2']} + ${spacingVars['--spacing-4']} / 2 - ${GUIDE_COLUMN_WIDTH} / 2)`;
/** 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
@@ -39,7 +41,7 @@ const styles = stylex.create({
container: {
height: '100%',
position: 'absolute',
- width: spacingVars['--spacing-5'],
+ width: GUIDE_COLUMN_WIDTH,
zIndex: 1,
pointerEvents: 'none',
},
@@ -103,7 +105,7 @@ export function TreeListBranches({
return (
<>
{ancestorsIsLast.map((ancestorIsLast, level) => {
- const branchOffset = `calc(${BRANCH_MARGIN} + ${level} * ${LEVEL_INDENT})`;
+ const branchOffset = `calc(${GUIDE_COLUMN_START} + ${level} * ${LEVEL_INDENT})`;
return (
// Skip the level that the current-item connector occupies
// (nestedLevel - 1), since that position is rendered below
@@ -132,7 +134,7 @@ export function TreeListBranches({
<div
{...mergeProps(stylex.props(styles.container), {
style: {
- insetInlineStart: `calc(${BRANCH_MARGIN} + ${nestedLevel - 1} * ${LEVEL_INDENT})`,
+ insetInlineStart: `calc(${GUIDE_COLUMN_START} + ${nestedLevel - 1} * ${LEVEL_INDENT})`,
},
})}>
<div
diff --git a/packages/core/src/TreeList/TreeListItem.tsx b/packages/core/src/TreeList/TreeListItem.tsx
index be868415d6..7b152badd2 100644
--- a/packages/core/src/TreeList/TreeListItem.tsx
+++ b/packages/core/src/TreeList/TreeListItem.tsx
@@ -227,8 +227,6 @@ const styles = stylex.create({
padding: 0,
color: colorVars['--color-icon-secondary'],
borderRadius: radiusVars['--radius-inner'],
- marginInlineStart: spacingVars['--spacing-1'],
- marginInlineEnd: `calc(${spacingVars['--spacing-1']} * -1)`,
},
chevronButton: {
display: 'flex',
@@ -243,8 +241,6 @@ const styles = stylex.create({
},
color: colorVars['--color-icon-secondary'],
borderRadius: radiusVars['--radius-inner'],
- marginInlineStart: spacingVars['--spacing-1'],
- marginInlineEnd: `calc(${spacingVars['--spacing-1']} * -1)`,
},
chevronSvg: {
display: 'flex',
diff --git a/packages/core/src/TreeList/__tests__/TreeListGuideAlignment.interaction.browser.spec.ts b/packages/core/src/TreeList/__tests__/TreeListGuideAlignment.interaction.browser.spec.ts
new file mode 100644
index 0000000000..c5cb216a11
--- /dev/null
+++ b/packages/core/src/TreeList/__tests__/TreeListGuideAlignment.interaction.browser.spec.ts
@@ -0,0 +1,127 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TreeListGuideAlignment.interaction.browser.spec.ts
+ * @input The built Fully Expanded TreeList story in a real browser
+ * @output Proof that guides align to naturally placed chevrons without moving
+ * those controls between lineGuides and noGuides
+ * @position Layout evidence for TreeList chevron and guide geometry
+ */
+
+import {expect, test, type Page} from '@playwright/test';
+import {
+ DEFAULT_STORYBOOK_DIR,
+ serveStorybook,
+ type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+ storybook = await serveStorybook(
+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+ );
+});
+
+test.afterAll(async () => {
+ await storybook?.close();
+});
+
+type Direction = 'ltr' | 'rtl';
+type Variant = 'lineGuides' | 'noGuides';
+
+interface Geometry {
+ chevronCenters: number[];
+ guideCenters: number[];
+ chevronStartOffsets: number[];
+}
+
+async function openStory(
+ page: Page,
+ direction: Direction,
+ variant: Variant,
+): Promise<void> {
+ const params = new URLSearchParams({
+ id: 'core-treelist--fully-expanded',
+ viewMode: 'story',
+ args: `variant:${variant}`,
+ });
+ await page.goto(`${storybook.origin}/iframe.html?${params}`);
+ await page.locator('.astryx-tree-list').waitFor();
+ await page.evaluate(dir => {
+ const tree = document.querySelector('.astryx-tree-list');
+ if (tree == null) {
+ throw new Error('TreeList root not found');
+ }
+ tree.setAttribute('dir', dir);
+ }, direction);
+ await page.evaluate(
+ async () =>
+ new Promise<void>(resolve => {
+ requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+ }),
+ );
+}
+
+async function measureGeometry(page: Page): Promise<Geometry> {
+ return page.evaluate(() => {
+ const chevrons = Array.from(
+ document.querySelectorAll<HTMLElement>('.astryx-tree-list-chevron'),
+ );
+ const guides = Array.from(
+ document.querySelectorAll<HTMLElement>('.astryx-tree-list-guide'),
+ );
+ const centerOf = (element: HTMLElement): number => {
+ const rect = element.getBoundingClientRect();
+ return rect.left + rect.width / 2;
+ };
+ const unique = (values: number[]): number[] =>
+ Array.from(new Set(values.map(value => Math.round(value * 2) / 2))).sort(
+ (a, b) => a - b,
+ );
+
+ return {
+ chevronCenters: unique(chevrons.map(centerOf)),
+ guideCenters: unique(guides.map(centerOf)),
+ chevronStartOffsets: chevrons.map(chevron => {
+ const content = chevron.parentElement;
+ if (content == null) {
+ throw new Error('Chevron has no content container');
+ }
+ const chevronRect = chevron.getBoundingClientRect();
+ const contentStyle = getComputedStyle(content);
+ const contentRect = content.getBoundingClientRect();
+ const paddingStart = Number.parseFloat(contentStyle.paddingInlineStart);
+ return contentStyle.direction === 'rtl'
+ ? contentRect.right - paddingStart - chevronRect.right
+ : chevronRect.left - contentRect.left - paddingStart;
+ }),
+ };
+ });
+}
+
+for (const direction of ['ltr', 'rtl'] as const) {
+ test(`guides align to unshifted chevrons in ${direction.toUpperCase()}`, async ({
+ page,
+ }) => {
+ await openStory(page, direction, 'lineGuides');
+ const geometry = await measureGeometry(page);
+
+ expect(geometry.chevronStartOffsets.length).toBeGreaterThan(0);
+ for (const offset of geometry.chevronStartOffsets) {
+ expect(offset).toBeCloseTo(0, 1);
+ }
+ expect(geometry.guideCenters).toEqual(geometry.chevronCenters);
+ });
+}
+
+test('guide visibility does not move chevrons', async ({page}) => {
+ await openStory(page, 'ltr', 'lineGuides');
+ const withGuides = await measureGeometry(page);
+
+ await openStory(page, 'ltr', 'noGuides');
+ const withoutGuides = await measureGeometry(page);
+
+ expect(withGuides.chevronCenters).toEqual(withoutGuides.chevronCenters);
+ expect(withoutGuides.guideCenters).toEqual([]);
+});