@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/TreeList/TreeList.tsx

@@ -15,7 +15,15 @@
  * - /packages/cli/assets/templates/blocks/components/TreeList/ (showcase blocks)
  */
 
-import {useId, useState, useMemo, useCallback, type ReactNode} from 'react';
+import {
+  useId,
+  useState,
+  useMemo,
+  useCallback,
+  useLayoutEffect,
+  useRef,
+  type ReactNode,
+} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
@@ -28,6 +36,16 @@ import type {
 } from './TreeListTypes';
 import {themeProps} from '../utils/themeProps';
 import {useTreeFocusInternal} from '../hooks/useTreeFocus';
+import {LayoutChangeSnapshot} from '../motion/LayoutChangeSnapshot';
+import {
+  applyLayoutChangeTransition,
+  holdLayoutExit,
+  playLayoutChange,
+  releaseLayoutExit,
+  reportLayoutChange,
+  type AnimatedLayout,
+  type LayoutChange,
+} from '../motion/animatedLayout';
 
 // =============================================================================
 // Types
@@ -39,6 +57,13 @@ export interface TreeListProps extends BaseProps<HTMLDivElement> {
   /** Ref forwarded to the root element */
   ref?: React.Ref<HTMLDivElement>;
 
+  /**
+   * The handle from `useAnimatedLayout({containerRef})`. With it, expanding
+   * or collapsing a row glides the rows and content after it, up to that
+   * container, instead of jumping, and the chevron turns on the same timing.
+   */
+  animatedLayout?: AnimatedLayout;
+
   /**
    * Tree items as a recursive data structure.
    * Each item can have nested `children` arrays.
@@ -183,6 +208,22 @@ function findInitialTabbableId(items: TreeListItemData[]): string | undefined {
  * />
  * ```
  */
+/** Whether two sets of row ids hold the same rows. */
+function sameIds(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
+  if (a === b) {
+    return true;
+  }
+  if (a.size !== b.size) {
+    return false;
+  }
+  for (const id of a) {
+    if (!b.has(id)) {
+      return false;
+    }
+  }
+  return true;
+}
+
 export function TreeList({
   items,
   density = 'balanced',
@@ -196,6 +237,7 @@ export function TreeList({
   'aria-labelledby': ariaLabelledby,
   ref,
   onKeyDown: onKeyDownProp,
+  animatedLayout,
   ...restProps
 }: TreeListProps) {
   const headerId = useId();
@@ -211,6 +253,145 @@ export function TreeList({
     Map<string, boolean>
   >(() => new Map());
 
+  // With an `animatedLayout` handle, a row's size change (its children shown
+  // or hidden) animates up to the handle's container: the rows and content after it glide, and
+  // the shown group plays its own entrance on the same timing
+  // (`architecture:react-component-runtime` INV12). Read through a ref
+  // because the tree element comes from the focus hook below.
+  const treeElementRef = useRef<HTMLUListElement | null>(null);
+  // The rows expanded now, whatever expanded them (a click, the keyboard, or
+  // `isExpanded` changed in `items`).
+  const expandedIds = useMemo(() => {
+    const out = new Set<string>();
+    const walk = (list: ReadonlyArray<TreeListItemData>) => {
+      for (const item of list) {
+        if (item.children == null || item.children.length === 0) {
+          continue;
+        }
+        const isExpanded = expandedKeysOverride.has(item.id)
+          ? (expandedKeysOverride.get(item.id) ?? false)
+          : expandedKeysFromProps.has(item.id);
+        if (isExpanded) {
+          out.add(item.id);
+          walk(item.children);
+        }
+      }
+    };
+    walk(items);
+    return out;
+  }, [items, expandedKeysOverride, expandedKeysFromProps]);
+  // Rows whose collapse is still playing its exit: their child group stays
+  // rendered (the exit makes it inert and gives up its space) until it ends
+  // (`spec:AST-105` FR4). Derived from the expanded rows as they change,
+  // during render, so the collapsing commit already keeps the group.
+  const [exitingIds, setExitingIds] = useState<ReadonlySet<string>>(
+    () => new Set(),
+  );
+  const [renderedExpandedIds, setRenderedExpandedIds] = useState(expandedIds);
+  if (!sameIds(renderedExpandedIds, expandedIds)) {
+    setRenderedExpandedIds(expandedIds);
+    if (animatedLayout != null) {
+      const next = new Set(exitingIds);
+      for (const id of renderedExpandedIds) {
+        if (!expandedIds.has(id)) {
+          next.add(id);
+        }
+      }
+      for (const id of expandedIds) {
+        next.delete(id);
+      }
+      setExitingIds(next);
+    }
+  }
+  const endExit = useCallback((id: string) => {
+    // Called from the exit effect: holdLayoutExit decides from layout read
+    // in the collapsing commit (the group's place in the area's visible part,
+    // Reduce Motion and the pointer, and whether an end margin frees its
+    // space); a group it does not hold goes before the frame paints.
+    setExitingIds(prev => {
+      if (!prev.has(id)) {
+        return prev;
+      }
+      const next = new Set(prev);
+      next.delete(id);
+      return next;
+    });
+  }, []);
+  // Every expansion change is measured before it lands (`spec:AST-105` FR1):
+  // LayoutChangeSnapshot calls this in the commit, before the DOM changes,
+  // for each row whose expansion changed. The row's own chevron (the Icon in
+  // its toggle, the first one in the row) turns on the glide's motion.
+  const pendingLayoutRef = useRef<
+    {
+      change: LayoutChange;
+      id: string;
+      isExpanding: boolean;
+      /** Changed rows inside this one: they move and exit with it. */
+      nested: string[];
+    }[]
+  >([]);
+  const measureChanges = useCallback(
+    (previous: ReadonlySet<string>) => {
+      const changed = [
+        ...[...previous].filter(id => !expandedIds.has(id)),
+        ...[...expandedIds].filter(id => !previous.has(id)),
+      ];
+      const rows = new Map<string, HTMLElement>();
+      for (const id of changed) {
+        const row = treeElementRef.current?.querySelector<HTMLElement>(
+          `[data-tree-id="${CSS.escape(id)}"]`,
+        );
+        if (row != null) {
+          rows.set(id, row);
+        }
+      }
+      // A changed row inside another changed row (a child left expanded when
+      // its parent collapses) is not a change of its own: its group goes with
+      // the outer one, so the content after them moves once (`spec:AST-105`
+      // FR3).
+      const outerOf = (row: HTMLElement): string | undefined =>
+        [...rows].find(
+          ([, other]) => other !== row && other.contains(row),
+        )?.[0];
+      const nested = new Map<string, string[]>();
+      for (const [id, row] of rows) {
+        const outer = outerOf(row);
+        if (outer != null) {
+          nested.set(outer, [...(nested.get(outer) ?? []), id]);
+        }
+      }
+      for (const [id, row] of rows) {
+        if (outerOf(row) != null) {
+          continue;
+        }
+        applyLayoutChangeTransition(
+          animatedLayout,
+          row.querySelector<HTMLElement>('[data-tree-toggle] > .astryx-icon'),
+        );
+        const change = reportLayoutChange(animatedLayout, () => row);
+        change.measureBefore();
+        pendingLayoutRef.current.push({
+          change,
+          id,
+          isExpanding: expandedIds.has(id),
+          nested: nested.get(id) ?? [],
+        });
+      }
+    },
+    [animatedLayout, expandedIds],
+  );
+  // Without a handle the chevrons keep the theme's own turn: a spring a
+  // handle set stays only while it is passed (`spec:AST-105` FR2).
+  useLayoutEffect(() => {
+    if (animatedLayout != null) {
+      return;
+    }
+    for (const chevron of treeElementRef.current?.querySelectorAll<HTMLElement>(
+      '[data-tree-toggle] > .astryx-icon',
+    ) ?? []) {
+      applyLayoutChangeTransition(null, chevron);
+    }
+  }, [animatedLayout]);
   const handleToggle = useCallback(
     (id: string) => {
       setExpandedKeysOverride(prev => {
@@ -259,6 +440,44 @@ export function TreeList({
     return false;
   }, []);
 
+  useLayoutEffect(() => {
+    const pendings = pendingLayoutRef.current;
+    pendingLayoutRef.current = [];
+    for (const pending of pendings) {
+      const isMeasured = pending.change.animate();
+      const group = treeElementRef.current?.querySelector<HTMLElement>(
+        `[data-tree-id="${CSS.escape(pending.id)}"] > [role="group"]`,
+      );
+      if (pending.isExpanding) {
+        if (group != null) {
+          // Expanded again mid-exit: the group takes its place in flow.
+          releaseLayoutExit(group);
+          if (isMeasured) {
+            playLayoutChange(animatedLayout, group);
+          }
+        }
+        continue;
+      }
+      // The rows nested in it leave with it, once its exit ends.
+      const endAll = () => {
+        endExit(pending.id);
+        for (const id of pending.nested) {
+          endExit(id);
+        }
+      };
+      const isHeld =
+        isMeasured &&
+        group != null &&
+        holdLayoutExit(animatedLayout, group, endAll);
+      if (!isHeld) {
+        // An exit holdLayoutExit did not hold (out of view, Reduce Motion
+        // with a fine pointer, or no margin frees its space): the group goes
+        // before this frame paints.
+        endAll();
+      }
+    }
+  }, [expandedIds, animatedLayout, endExit]);
+
   const {treeRef, handleKeyDown, handleFocus} =
     useTreeFocusInternal<HTMLUListElement>({
       onToggleExpand: handleToggle,
@@ -267,7 +486,12 @@ export function TreeList({
       // Rows are named by their label (AR1); typeahead matches that label, not
       // the chevron toggle, start content or description.
       matchLabelledBy: true,
+      // Rows of a group still playing its collapse are gone already.
+      itemSelector: '[role="treeitem"]:not([data-tree-exiting] *)',
     });
+  useLayoutEffect(() => {
+    treeElementRef.current = treeRef.current;
+  });
 
   const handleRootKeyDown = useCallback(
     (e: React.KeyboardEvent<HTMLDivElement>) => {
@@ -316,8 +540,9 @@ export function TreeList({
         ? [...ancestorsIsLast, isLast]
         : ancestorsIsLast;
 
+      const isExiting = exitingIds.has(item.id);
       const renderedChildren =
-        isExpanded && hasChildren
+        (isExpanded || isExiting) && hasChildren
           ? renderItems(
               item.children ?? [],
               nestedLevel + 1,
@@ -347,6 +572,7 @@ export function TreeList({
           isLast={isLast}
           ancestorsIsLast={ancestorsIsLast}
           isExpanded={isExpanded}
+          isExiting={isExiting && !isExpanded}
           onToggle={handleToggle}
           density={density}
           variant={variant}
@@ -376,6 +602,12 @@ export function TreeList({
           {header}
         </div>
       )}
+      {animatedLayout != null && (
+        <LayoutChangeSnapshot
+          value={expandedIds}
+          onBeforeChange={measureChanges}
+        />
+      )}
       <ul
         ref={treeRef}
         role="tree"

package/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

package/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',
@@ -351,6 +347,12 @@ export interface TreeListItemInternalProps {
   isLast: boolean;
   ancestorsIsLast: ReadonlyArray<boolean>;
   isExpanded: boolean;
+  /**
+   * The row collapsed and its child group is playing its exit: the group
+   * stays rendered (the exit makes it inert) until it ends, and its rows
+   * leave the tree's keyboard order at once.
+   */
+  isExiting?: boolean;
   onToggle?: (id: string) => void;
   density: TreeListDensity;
   /**
@@ -397,6 +399,7 @@ export function TreeListItem({
   isLast,
   ancestorsIsLast,
   isExpanded,
+  isExiting = false,
   onToggle,
   density,
   variant,
@@ -703,8 +706,11 @@ export function TreeListItem({
           <div {...stylex.props(styles.indentedContent)}>{innerContent}</div>
         </div>
       </div>
-      {isExpanded && renderedChildren != null && (
-        <ul role="group" {...stylex.props(styles.childGroup)}>
+      {(isExpanded || isExiting) && renderedChildren != null && (
+        <ul
+          role="group"
+          data-tree-exiting={isExiting ? '' : undefined}
+          {...stylex.props(styles.childGroup)}>
           {renderedChildren}
         </ul>
       )}

package/src/TreeList/__tests__/TreeList.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y scope ^(internal/a11y-spec/src/patterns/tree-view|internal/a11y-spec/src/harness|packages/core/src/TreeList/|packages/core/src/hooks/useTreeFocus|apps/storybook/stories/TreeListTreeViewA11y)
 
 /**
  * @file TreeList.a11y.chromium.spec.ts
@@ -97,15 +98,27 @@ async function runState(
   });
 }
 
-test('every tree-view expectation is exercised by a TreeList state', async ({
-  page,
-}) => {
-  const cdp = await page.context().newCDPSession(page);
+// Checking coverage runs every state again, which on a loaded runner nears
+// the per-test timeout as one test. It runs as one serial part per state,
+// sharing their results, then one check over all of them.
+test.describe('every tree-view expectation is exercised by a TreeList state', () => {
+  test.describe.configure({mode: 'serial'});
   const results: BindingResult[] = [];
+
   for (const state of TREE_LIST_BINDING_STATES) {
-    results.push(await runState(page, cdp, state));
+    test(`runs ${state.id}`, async ({page}) => {
+      const cdp = await page.context().newCDPSession(page);
+      results.push(await runState(page, cdp, state));
+    });
   }
-  expect(neverExercised(results)).toEqual([]);
+
+  test('no expectation is left unexercised', () => {
+    // Every part ran in this worker; this test alone proves nothing.
+    expect(results.map(result => result.state).sort()).toEqual(
+      TREE_LIST_BINDING_STATES.map(state => state.id).sort(),
+    );
+    expect(neverExercised(results)).toEqual([]);
+  });
 });
 
 for (const state of TREE_LIST_BINDING_STATES) {

package/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([]);
+});

package/src/TreeList/__tests__/TreeListRowNames.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y scope ^(packages/core/src/TreeList/|packages/core/src/hooks/useTreeFocus|apps/storybook/stories/TreeListA11y)
 
 /**
  * @file TreeListRowNames.a11y.chromium.spec.ts