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.mdnew file mode 100644index 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.++@rubyycheungdiff --git a/packages/core/src/TreeList/TreeList.spec.md b/packages/core/src/TreeList/TreeList.spec.mdindex 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 supportdiff --git a/packages/core/src/TreeList/TreeListBranches.tsx b/packages/core/src/TreeList/TreeListBranches.tsxindex 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})`,},})}><divdiff --git a/packages/core/src/TreeList/TreeListItem.tsx b/packages/core/src/TreeList/TreeListItem.tsxindex 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.tsnew file mode 100644index 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([]);+});