Skip to content

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

TypeScript

feat(TreeList): add variant prop (lineGuides | noGuides) (#4334)

Cindy Zhangad5a438dacef
diff --git a/.changeset/treelist-variant.md b/.changeset/treelist-variant.md
new file mode 100644
index 0000000000..3578098d27
--- /dev/null
+++ b/.changeset/treelist-variant.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] TreeList: add a `variant` prop (`'lineGuides' | 'noGuides'`, default `'lineGuides'`) to select the base hierarchy guide-line look. `noGuides` hides the connector lines while keeping indentation intact. Orthogonal to `density` (spacing); the guides stay themeable via the `astryx-tree-list-guide` target. Non-breaking — omitting the prop renders exactly as before.
+
+@cixzhang
diff --git a/apps/storybook/stories/TreeList.stories.tsx b/apps/storybook/stories/TreeList.stories.tsx
index 957cc3532e..9d542ec7a5 100644
--- a/apps/storybook/stories/TreeList.stories.tsx
+++ b/apps/storybook/stories/TreeList.stories.tsx
@@ -25,6 +25,11 @@ const meta: Meta<typeof TreeList> = {
options: ['compact', 'balanced', 'spacious'],
description: 'Spacing density for tree list items',
},
+ variant: {
+ control: 'select',
+ options: ['lineGuides', 'noGuides'],
+ description: 'Hierarchy guide-line treatment',
+ },
},
};
@@ -499,3 +504,34 @@ export const ThemedGuides: Story = {
</Theme>
),
};
+
+/**
+ * The `variant` prop selects the base guide-line look, orthogonal to `density`
+ * (which owns spacing). `lineGuides` (default) draws the connector lines;
+ * `noGuides` hides them while keeping the indentation intact, so nesting is
+ * conveyed by indent alone. The guides remain themeable via the
+ * `astryx-tree-list-guide` target regardless of variant.
+ */
+export const Variants: Story = {
+ render: () => (
+ <div style={{display: 'flex', gap: 48, alignItems: 'flex-start'}}>
+ <div>
+ <div style={{marginBottom: 8, fontWeight: 600}}>
+ lineGuides (default)
+ </div>
+ <TreeList items={guideItems} variant="lineGuides" />
+ </div>
+ <div>
+ <div style={{marginBottom: 8, fontWeight: 600}}>noGuides</div>
+ <TreeList items={guideItems} variant="noGuides" />
+ </div>
+ </div>
+ ),
+};
+
+export const NoGuides: Story = {
+ args: {
+ items: guideItems,
+ variant: 'noGuides',
+ },
+};
diff --git a/packages/cli/templates/blocks/components/TreeList/TreeListVariants.doc.mjs b/packages/cli/templates/blocks/components/TreeList/TreeListVariants.doc.mjs
new file mode 100644
index 0000000000..d03c549b73
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TreeList/TreeListVariants.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'TreeList',
+ name: 'Tree List — Variants',
+ displayName: 'Tree List — Variants',
+ description:
+ 'The `variant` prop controls whether hierarchy guide lines are shown: `lineGuides` (default) draws connector lines between parent and child rows, while `noGuides` relies on indentation alone. It is orthogonal to `density`, which controls spacing.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['TreeList', 'Stack', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/TreeList/TreeListVariants.tsx b/packages/cli/templates/blocks/components/TreeList/TreeListVariants.tsx
new file mode 100644
index 0000000000..b1fc12882e
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TreeList/TreeListVariants.tsx
@@ -0,0 +1,55 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import type {TreeListItemData} from '@astryxdesign/core/TreeList';
+import {TreeList} from '@astryxdesign/core/TreeList';
+import {Stack} from '@astryxdesign/core/Stack';
+import {Text} from '@astryxdesign/core/Text';
+
+const noop = () => {};
+
+const items: TreeListItemData[] = [
+ {
+ id: 'src',
+ label: 'src',
+ isExpanded: true,
+ children: [
+ {
+ id: 'components',
+ label: 'components',
+ isExpanded: true,
+ children: [
+ {id: 'button', label: 'Button.tsx', onClick: noop},
+ {id: 'card', label: 'Card.tsx', onClick: noop},
+ ],
+ },
+ {id: 'app', label: 'App.tsx', onClick: noop},
+ ],
+ },
+ {id: 'readme', label: 'README.md', onClick: noop},
+];
+
+export default function TreeListVariants() {
+ return (
+ <Stack
+ direction="horizontal"
+ gap={6}
+ hAlign="start"
+ vAlign="start"
+ wrap="wrap">
+ <Stack direction="vertical" gap={2}>
+ <Text type="supporting" color="secondary" weight="bold">
+ lineGuides (default)
+ </Text>
+ <TreeList items={items} variant="lineGuides" />
+ </Stack>
+ <Stack direction="vertical" gap={2}>
+ <Text type="supporting" color="secondary" weight="bold">
+ noGuides
+ </Text>
+ <TreeList items={items} variant="noGuides" />
+ </Stack>
+ </Stack>
+ );
+}
diff --git a/packages/core/src/TreeList/TreeList.doc.mjs b/packages/core/src/TreeList/TreeList.doc.mjs
index c9b47f1a28..05b1e6cea3 100644
--- a/packages/core/src/TreeList/TreeList.doc.mjs
+++ b/packages/core/src/TreeList/TreeList.doc.mjs
@@ -50,6 +50,13 @@ export const docs = {
description: 'Spacing density for items.',
default: "'balanced'",
},
+ {
+ name: 'variant',
+ type: "'lineGuides' | 'noGuides'",
+ description:
+ 'Visual treatment of the hierarchy guide lines. lineGuides shows connector lines; noGuides hides them, keeping indentation. Orthogonal to density.',
+ default: "'lineGuides'",
+ },
{
name: 'header',
type: 'ReactNode',
@@ -118,6 +125,13 @@ export const docsZh = {
description: '项目的间距密度。',
default: "'balanced'",
},
+ {
+ name: 'variant',
+ type: "'lineGuides' | 'noGuides'",
+ description:
+ '层级引导线的视觉呈现。lineGuides 显示连接线;noGuides 隐藏连接线并保留缩进。与 density 正交。',
+ default: "'lineGuides'",
+ },
{
name: 'header',
type: 'ReactNode',
@@ -162,6 +176,7 @@ export const docsDense = {
propDescriptions: {
items: 'Recursive tree item data w/ id, label, optional children + isExpanded.',
density: 'Spacing density for items.',
+ variant: 'Guide-line treatment: lineGuides shows connectors, noGuides hides them (indent kept). Orthogonal to density.',
header: 'Header content, linked to tree via aria-labelledby.',
xstyle: 'StyleX styles for layout. Must be stylex.create() value.',
},
@@ -173,6 +188,7 @@ export const docsDense = {
propDescriptions: {
items: 'Recursive tree item data w/ id, label, optional children + isExpanded.',
density: 'Spacing density for items.',
+ variant: 'Guide-line treatment: lineGuides shows connectors, noGuides hides them (indent kept). Orthogonal to density.',
header: 'Header content, linked to tree via aria-labelledby.',
xstyle: 'StyleX styles for layout. Must be stylex.create() value.',
},
diff --git a/packages/core/src/TreeList/TreeList.test.tsx b/packages/core/src/TreeList/TreeList.test.tsx
index cb7cbfee4b..b9917c9201 100644
--- a/packages/core/src/TreeList/TreeList.test.tsx
+++ b/packages/core/src/TreeList/TreeList.test.tsx
@@ -395,6 +395,69 @@ describe('TreeList', () => {
expect(screen.getByRole('tree')).toBeInTheDocument();
});
+ // ===========================================================================
+ // Variant (guide lines)
+ // ===========================================================================
+
+ describe('variant', () => {
+ it('renders guide lines by default', () => {
+ const {container} = render(<TreeList items={nestedItemsExpanded} />);
+ expect(container.querySelector('.astryx-tree-list-guide')).not.toBeNull();
+ });
+
+ it("variant='lineGuides' renders guide lines (explicit == default)", () => {
+ const {container} = render(
+ <TreeList items={nestedItemsExpanded} variant="lineGuides" />,
+ );
+ expect(container.querySelector('.astryx-tree-list-guide')).not.toBeNull();
+ });
+
+ it("variant='noGuides' renders NO guide lines", () => {
+ const {container} = render(
+ <TreeList items={nestedItemsExpanded} variant="noGuides" />,
+ );
+ expect(container.querySelector('.astryx-tree-list-guide')).toBeNull();
+ });
+
+ it("variant='noGuides' preserves the tree structure and items", () => {
+ render(<TreeList items={nestedItemsExpanded} variant="noGuides" />);
+ // Rows, roles, and nesting are all intact — only the connectors are gone.
+ expect(screen.getByRole('tree')).toBeInTheDocument();
+ expect(screen.getAllByRole('treeitem')).toHaveLength(4);
+ expect(screen.getByText('Parent')).toBeInTheDocument();
+ expect(screen.getByText('Child 1')).toBeInTheDocument();
+ expect(screen.getByText('Child 2')).toBeInTheDocument();
+ expect(screen.getByText('Sibling')).toBeInTheDocument();
+ });
+
+ it("variant='noGuides' preserves per-level indentation on the rows", () => {
+ // Indentation lives on the row's marginLeft (not the guide element), so
+ // it must survive when the connectors are suppressed. A deeper row is
+ // indented more than a shallower one.
+ const {container} = render(
+ <TreeList items={deepItems} variant="noGuides" />,
+ );
+ const marginOf = (text: string): string => {
+ const li = screen.getByText(text).closest('li')!;
+ const styled = li.querySelector('[style*="margin-left"]');
+ return styled?.getAttribute('style') ?? '';
+ };
+ // Guides are gone…
+ expect(container.querySelector('.astryx-tree-list-guide')).toBeNull();
+ // …but each level still carries an inline margin-left, and the level
+ // multiplier grows with depth (0, 1, 2).
+ expect(marginOf('Root')).toContain('margin-left');
+ expect(marginOf('Mid')).toContain('margin-left');
+ expect(marginOf('Leaf')).toContain('margin-left');
+ const level = (text: string): number => {
+ const m = /calc\((\d+)/.exec(marginOf(text));
+ return m ? Number(m[1]) : NaN;
+ };
+ expect(level('Mid')).toBeGreaterThan(level('Root'));
+ expect(level('Leaf')).toBeGreaterThan(level('Mid'));
+ });
+ });
+
// ===========================================================================
// Guide theme target
// ===========================================================================
diff --git a/packages/core/src/TreeList/TreeList.tsx b/packages/core/src/TreeList/TreeList.tsx
index 7a004a7d72..8e9f0ad138 100644
--- a/packages/core/src/TreeList/TreeList.tsx
+++ b/packages/core/src/TreeList/TreeList.tsx
@@ -21,7 +21,11 @@ import {spacingVars} from '../theme/tokens.stylex';
import {mergeProps} from '../utils';
import type {BaseProps} from '../BaseProps';
import {TreeListItem} from './TreeListItem';
-import type {TreeListItemData, TreeListDensity} from './TreeListTypes';
+import type {
+ TreeListItemData,
+ TreeListDensity,
+ TreeListVariant,
+} from './TreeListTypes';
import {themeProps} from '../utils/themeProps';
import {useTreeFocus} from '../hooks/useTreeFocus';
@@ -29,7 +33,7 @@ import {useTreeFocus} from '../hooks/useTreeFocus';
// Types
// =============================================================================
-export {type TreeListDensity} from './TreeListTypes';
+export {type TreeListDensity, type TreeListVariant} from './TreeListTypes';
export interface TreeListProps extends BaseProps<HTMLDivElement> {
/** Ref forwarded to the root element */
@@ -50,6 +54,16 @@ export interface TreeListProps extends BaseProps<HTMLDivElement> {
*/
density?: TreeListDensity;
+ /**
+ * Visual treatment of the hierarchy guide (connector) lines.
+ * - `lineGuides`: connector lines between parent and child rows
+ * - `noGuides`: no connector lines; indentation alone conveys nesting
+ *
+ * Orthogonal to `density` (which controls spacing) — the two compose.
+ * @default 'lineGuides'
+ */
+ variant?: TreeListVariant;
+
/**
* Header content rendered above the tree list.
* Semantically associated via aria-labelledby.
@@ -156,6 +170,7 @@ function findInitialTabbableId(items: TreeListItemData[]): string | undefined {
export function TreeList({
items,
density = 'balanced',
+ variant = 'lineGuides',
header,
xstyle,
className,
@@ -275,6 +290,7 @@ export function TreeList({
isExpanded={isExpanded}
onToggle={handleToggle}
density={density}
+ variant={variant}
renderedChildren={renderedChildren}
posInSet={index + 1}
setSize={items.length}
diff --git a/packages/core/src/TreeList/TreeListItem.tsx b/packages/core/src/TreeList/TreeListItem.tsx
index 0ce83450c5..8a6945ebd7 100644
--- a/packages/core/src/TreeList/TreeListItem.tsx
+++ b/packages/core/src/TreeList/TreeListItem.tsx
@@ -28,7 +28,7 @@ import {getIcon} from '../Icon/globalIconRegistry';
import {mergeProps} from '../utils';
import {useLinkComponent} from '../Link/useLinkComponent';
import {TreeListBranches} from './TreeListBranches';
-import type {TreeListDensity} from './TreeListTypes';
+import type {TreeListDensity, TreeListVariant} from './TreeListTypes';
import {themeProps} from '../utils/themeProps';
import {useTranslator} from '../i18n';
@@ -268,6 +268,12 @@ export interface TreeListItemInternalProps {
isExpanded: boolean;
onToggle?: (id: string) => void;
density: TreeListDensity;
+ /**
+ * Guide-line visual treatment. `noGuides` suppresses the connector lines;
+ * indentation is unaffected (it lives on the row's `marginLeft`, not the
+ * guide element).
+ */
+ variant: TreeListVariant;
/** Pre-rendered children subtree (rendered by the parent recursion) */
renderedChildren?: ReactNode;
/** 1-based position of this item among its siblings (aria-posinset). */
@@ -304,6 +310,7 @@ export function TreeListItem({
isExpanded,
onToggle,
density,
+ variant,
renderedChildren,
posInSet,
setSize,
@@ -492,13 +499,15 @@ export function TreeListItem({
data-tree-level={nestedLevel + 1}
data-tree-disabled={isDisabled || undefined}
{...stylex.props(styles.wrapper)}>
- <div {...stylex.props(styles.treeBranches)}>
- <TreeListBranches
- ancestorsIsLast={ancestorsIsLast}
- isLast={isLast}
- nestedLevel={nestedLevel}
- />
- </div>
+ {variant !== 'noGuides' && (
+ <div {...stylex.props(styles.treeBranches)}>
+ <TreeListBranches
+ ancestorsIsLast={ancestorsIsLast}
+ isLast={isLast}
+ nestedLevel={nestedLevel}
+ />
+ </div>
+ )}
<div {...stylex.props(styles.rowWrapper)}>
<div
{...mergeProps(
diff --git a/packages/core/src/TreeList/TreeListTypes.ts b/packages/core/src/TreeList/TreeListTypes.ts
index 2dc5ace2c2..780065546d 100644
--- a/packages/core/src/TreeList/TreeListTypes.ts
+++ b/packages/core/src/TreeList/TreeListTypes.ts
@@ -3,7 +3,7 @@
/**
* @file TreeListTypes.ts
* @input Uses React types
- * @output Exports TreeListItemData, TreeListDensity types
+ * @output Exports TreeListItemData, TreeListDensity, TreeListVariant types
* @position Type definitions; consumed by TreeList.tsx, TreeListItem.tsx, index.ts
*
* SYNC: When modified, update these files to stay in sync:
@@ -16,6 +16,32 @@ import type {ReactNode} from 'react';
/** Spacing density for tree list items. */
export type TreeListDensity = 'compact' | 'balanced' | 'spacious';
+/**
+ * Extensible variant map for TreeList.
+ *
+ * Theme packages can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/TreeList' {
+ * interface TreeListVariantMap {
+ * 'dotted': true;
+ * }
+ * }
+ * ```
+ */
+export interface TreeListVariantMap {
+ lineGuides: true;
+ noGuides: true;
+}
+
+/**
+ * Visual treatment of the hierarchy guide (connector) lines. Extensible via
+ * module augmentation of TreeListVariantMap.
+ * - `lineGuides`: connector lines between parent and child rows (default)
+ * - `noGuides`: no connector lines; indentation alone conveys nesting
+ */
+export type TreeListVariant = keyof TreeListVariantMap;
+
/** Recursive item configuration for TreeList. */
export interface TreeListItemData {
/** Unique identifier for the item. Used as React key and for expansion tracking. */
diff --git a/packages/core/src/TreeList/index.ts b/packages/core/src/TreeList/index.ts
index 6db8ed0754..aea1e8cb0f 100644
--- a/packages/core/src/TreeList/index.ts
+++ b/packages/core/src/TreeList/index.ts
@@ -12,5 +12,5 @@
*/
export {TreeList} from './TreeList';
-export type {TreeListProps, TreeListDensity} from './TreeList';
-export type {TreeListItemData} from './TreeListTypes';
+export type {TreeListProps, TreeListDensity, TreeListVariant} from './TreeList';
+export type {TreeListItemData, TreeListVariantMap} from './TreeListTypes';