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.mdnew file mode 100644index 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.++@cixzhangdiff --git a/apps/storybook/stories/TreeList.stories.tsx b/apps/storybook/stories/TreeList.stories.tsxindex 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsindex 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.tsindex 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';