Skip to content

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

TypeScript

feat(tree-list): add astryx-tree-list-guide theme target (#4309)

freddymetadd421ea4ac32
diff --git a/.changeset/tree-list-guide-style.md b/.changeset/tree-list-guide-style.md
new file mode 100644
index 0000000000..cfc374a4ff
--- /dev/null
+++ b/.changeset/tree-list-guide-style.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] TreeList: add a stable `astryx-tree-list-guide` theme target on the hierarchy guide (connector) line elements, so consumers can recolor or hide the guides through `defineTheme` (e.g. `backgroundColor`, or `display: 'none'` to hide them) instead of hiding the built-in connectors and reimplementing them with unlayered CSS.
+
+@freddymeta
diff --git a/apps/storybook/stories/TreeList.stories.tsx b/apps/storybook/stories/TreeList.stories.tsx
index bad0b0747f..957cc3532e 100644
--- a/apps/storybook/stories/TreeList.stories.tsx
+++ b/apps/storybook/stories/TreeList.stories.tsx
@@ -427,3 +427,75 @@ export const ThemedItemLabel: Story = {
</Theme>
),
};
+
+const guideItems: TreeListItemData[] = [
+ {
+ id: 'root',
+ label: 'Project',
+ isExpanded: true,
+ children: [
+ {
+ id: 'src',
+ label: 'src',
+ isExpanded: true,
+ children: [
+ {id: 'app', label: 'App.tsx'},
+ {id: 'index', label: 'index.tsx'},
+ ],
+ },
+ {id: 'pkg', label: 'package.json'},
+ ],
+ },
+];
+
+/**
+ * Hide the hierarchy guide (connector) lines through the
+ * `astryx-tree-list-guide` theme target — `display: 'none'` — when the
+ * surrounding layout already conveys nesting, or when a theme supplies its own
+ * connectors. No prop is needed: the theme rule lands in `@layer astryx-theme`,
+ * above StyleX's base layer, so it wins.
+ */
+const hiddenGuidesTheme = defineTheme({
+ name: 'tree-list-guide-hidden-demo',
+ components: {
+ 'tree-list-guide': {
+ base: {
+ display: 'none',
+ },
+ },
+ },
+});
+
+export const HiddenGuides: Story = {
+ render: () => (
+ <Theme theme={hiddenGuidesTheme} mode="light">
+ <TreeList items={guideItems} />
+ </Theme>
+ ),
+};
+
+/**
+ * Recolor the guides via the `astryx-tree-list-guide` theme target instead of
+ * hiding the built-in connectors and reimplementing them.
+ *
+ * `components['tree-list-guide'].base` restyles the connector lines only.
+ * Defaults are unchanged; this story only demonstrates the override channel.
+ */
+const guideTheme = defineTheme({
+ name: 'tree-list-guide-demo',
+ components: {
+ 'tree-list-guide': {
+ base: {
+ backgroundColor: 'var(--color-accent)',
+ },
+ },
+ },
+});
+
+export const ThemedGuides: Story = {
+ render: () => (
+ <Theme theme={guideTheme} mode="light">
+ <TreeList items={guideItems} />
+ </Theme>
+ ),
+};
diff --git a/packages/core/src/TreeList/TreeList.doc.mjs b/packages/core/src/TreeList/TreeList.doc.mjs
index 247b7a5937..c9b47f1a28 100644
--- a/packages/core/src/TreeList/TreeList.doc.mjs
+++ b/packages/core/src/TreeList/TreeList.doc.mjs
@@ -28,6 +28,7 @@ export const docs = {
{className: 'astryx-tree-list-item', visualProps: ['density'], states: ['selected', 'disabled']},
{className: 'astryx-tree-list-chevron', states: ['state']},
{className: 'astryx-tree-list-item-label', states: ['selected']},
+ {className: 'astryx-tree-list-guide'},
],
},
components: [
@@ -94,6 +95,7 @@ export const docsZh = {
{className: 'astryx-tree-list-item', visualProps: ['density'], states: ['selected', 'disabled']},
{className: 'astryx-tree-list-chevron', states: ['state']},
{className: 'astryx-tree-list-item-label', states: ['selected']},
+ {className: 'astryx-tree-list-guide'},
],
},
components: [
diff --git a/packages/core/src/TreeList/TreeList.test.tsx b/packages/core/src/TreeList/TreeList.test.tsx
index 7dec44d6ca..cb7cbfee4b 100644
--- a/packages/core/src/TreeList/TreeList.test.tsx
+++ b/packages/core/src/TreeList/TreeList.test.tsx
@@ -395,6 +395,52 @@ describe('TreeList', () => {
expect(screen.getByRole('tree')).toBeInTheDocument();
});
+ // ===========================================================================
+ // Guide theme target
+ // ===========================================================================
+
+ describe('guide theme target', () => {
+ it('renders the astryx-tree-list-guide target on the connector lines', () => {
+ const {container} = render(<TreeList items={nestedItemsExpanded} />);
+ const guide = container.querySelector('.astryx-tree-list-guide');
+ // A dedicated, stable target so a theme can recolor or hide the guides
+ // without hiding the built-in connectors and reimplementing them.
+ expect(guide).not.toBeNull();
+ });
+
+ it('exposes tree-list-guide as a themeable defineTheme target', () => {
+ // jsdom cannot resolve the @layer cascade, so the generated CSS is what
+ // proves a theme override reaches the guide element.
+ const theme = defineTheme({
+ name: 'tree-list-guide-test',
+ components: {
+ 'tree-list-guide': {
+ base: {backgroundColor: 'var(--color-accent)'},
+ },
+ },
+ });
+ const css = generateThemeCSSFlat(theme);
+ expect(css).toContain('.astryx-tree-list-guide {');
+ expect(css).toContain('background-color: var(--color-accent)');
+ });
+
+ it('lets a theme hide the guides via display: none on the target', () => {
+ // Hiding the guides is done through the theme target, not a prop — the
+ // theme rule lands in @layer astryx-theme, above StyleX's base layer.
+ const theme = defineTheme({
+ name: 'tree-list-guide-hidden-test',
+ components: {
+ 'tree-list-guide': {
+ base: {display: 'none'},
+ },
+ },
+ });
+ const css = generateThemeCSSFlat(theme);
+ expect(css).toContain('.astryx-tree-list-guide {');
+ expect(css).toContain('display: none');
+ });
+ });
+
// ===========================================================================
// xds class name
// ===========================================================================
diff --git a/packages/core/src/TreeList/TreeListBranches.tsx b/packages/core/src/TreeList/TreeListBranches.tsx
index 9b3723e245..67640c6f7c 100644
--- a/packages/core/src/TreeList/TreeListBranches.tsx
+++ b/packages/core/src/TreeList/TreeListBranches.tsx
@@ -16,6 +16,7 @@
import * as stylex from '@stylexjs/stylex';
import {colorVars, spacingVars} from '../theme/tokens.stylex';
import {mergeProps} from '../utils';
+import {themeProps} from '../utils/themeProps';
const LINE_WIDTH = 1;
@@ -65,6 +66,11 @@ interface TreeListBranchesProps {
/**
* Renders vertical lines showing parent-child relationships in the tree.
* Positioned in a full-height container to span the entire item including children.
+ *
+ * The line element carries the stable `astryx-tree-list-guide` theme target so a
+ * theme can recolor or hide the connectors via `defineTheme` (e.g.
+ * `backgroundColor` or `display: 'none'`) instead of hiding the built-in guides
+ * and reimplementing them.
*/
export function TreeListBranches({
ancestorsIsLast,
@@ -90,7 +96,10 @@ export function TreeListBranches({
},
})}>
<div
- {...stylex.props(styles.verticalLine, styles.verticalFull)}
+ {...mergeProps(
+ themeProps('tree-list-guide'),
+ stylex.props(styles.verticalLine, styles.verticalFull),
+ )}
/>
</div>
)
@@ -103,7 +112,12 @@ export function TreeListBranches({
left: `calc(${BRANCH_MARGIN} + ${nestedLevel - 1} * ${LEVEL_INDENT})`,
},
})}>
- <div {...stylex.props(styles.verticalLine, styles.verticalFull)} />
+ <div
+ {...mergeProps(
+ themeProps('tree-list-guide'),
+ stylex.props(styles.verticalLine, styles.verticalFull),
+ )}
+ />
</div>
)}
</>