Skip to content

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

TypeScript

feat(core): make TreeList per-level indent a themeable CSS variable (#4530)

Cindy Zhange6c6c2318e54
diff --git a/.changeset/tree-list-indent-var.md b/.changeset/tree-list-indent-var.md
new file mode 100644
index 0000000000..020dd8b8b1
--- /dev/null
+++ b/.changeset/tree-list-indent-var.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] TreeList: the per-level indentation step is now the themeable `--tree-list-indent` variable (default `var(--spacing-4)`), so a theme can retune the indent metric via `defineTheme` on the `tree-list` target instead of the previously hardcoded, unreachable step (#4308).
+@cixzhang
diff --git a/packages/core/src/TreeList/TreeList.doc.mjs b/packages/core/src/TreeList/TreeList.doc.mjs
index 05b1e6cea3..9d60ac5021 100644
--- a/packages/core/src/TreeList/TreeList.doc.mjs
+++ b/packages/core/src/TreeList/TreeList.doc.mjs
@@ -30,6 +30,9 @@ export const docs = {
{className: 'astryx-tree-list-item-label', states: ['selected']},
{className: 'astryx-tree-list-guide'},
],
+ vars: [
+ {name: '--tree-list-indent', description: 'Per-level indentation step. Each nesting level indents its rows by this distance, and the guide lines follow it so they stay aligned. Set it on the `tree-list` target to retune the metric (e.g. `var(--spacing-5)` for a wider indent).', default: 'var(--spacing-4)'},
+ ],
},
components: [
{
@@ -104,6 +107,9 @@ export const docsZh = {
{className: 'astryx-tree-list-item-label', states: ['selected']},
{className: 'astryx-tree-list-guide'},
],
+ vars: [
+ {name: '--tree-list-indent', description: '每级缩进步长。每个嵌套层级的行按此距离缩进,引导线随之对齐。在 `tree-list` 目标上设置以调整该度量(例如用 `var(--spacing-5)` 获得更宽的缩进)。', default: 'var(--spacing-4)'},
+ ],
},
components: [
{
diff --git a/packages/core/src/TreeList/TreeList.test.tsx b/packages/core/src/TreeList/TreeList.test.tsx
index 8de0cfe837..991e903c86 100644
--- a/packages/core/src/TreeList/TreeList.test.tsx
+++ b/packages/core/src/TreeList/TreeList.test.tsx
@@ -432,25 +432,28 @@ describe('TreeList', () => {
it("variant='noGuides' preserves per-level indentation on the rows", () => {
// Indentation lives on the row's margin-inline-start (not the guide
- // element), so it must survive when the connectors are suppressed. A
- // deeper row is indented more than a shallower one.
+ // element), so it must survive when the connectors are suppressed. The
+ // per-row distance is published as the `--_tree-indent` custom property
+ // (not an inline longhand — see #4308), so the theme layer can override
+ // the `margin-inline-start` declaration. A deeper row is indented more
+ // than a shallower one.
const {container} = render(
<TreeList items={deepItems} variant="noGuides" />,
);
- const marginOf = (text: string): string => {
+ const indentOf = (text: string): string => {
const li = screen.getByText(text).closest('li')!;
- const styled = li.querySelector('[style*="margin-inline-start"]');
+ const styled = li.querySelector('[style*="--_tree-indent"]');
return styled?.getAttribute('style') ?? '';
};
// Guides are gone…
expect(container.querySelector('.astryx-tree-list-guide')).toBeNull();
- // …but each level still carries an inline margin-inline-start, and the
- // level multiplier grows with depth (0, 1, 2).
- expect(marginOf('Root')).toContain('margin-inline-start');
- expect(marginOf('Mid')).toContain('margin-inline-start');
- expect(marginOf('Leaf')).toContain('margin-inline-start');
+ // …but each level still publishes an indent distance, and the level
+ // multiplier grows with depth (0, 1, 2).
+ expect(indentOf('Root')).toContain('--_tree-indent');
+ expect(indentOf('Mid')).toContain('--_tree-indent');
+ expect(indentOf('Leaf')).toContain('--_tree-indent');
const level = (text: string): number => {
- const m = /calc\((\d+)/.exec(marginOf(text));
+ const m = /calc\((\d+)/.exec(indentOf(text));
return m ? Number(m[1]) : NaN;
};
expect(level('Mid')).toBeGreaterThan(level('Root'));
@@ -504,6 +507,43 @@ describe('TreeList', () => {
});
});
+ // ===========================================================================
+ // Indent lever (--tree-list-indent)
+ // ===========================================================================
+
+ describe('indent lever', () => {
+ it('lets a theme retune the indent step via the tree-list target', () => {
+ // The per-level step is a public, themeable var (default --spacing-4) set
+ // on the tree-list root, so a theme can retune the indent metric (e.g. to
+ // --spacing-5) via defineTheme. jsdom cannot resolve the @layer cascade,
+ // so the generated CSS is what proves the override reaches the lever.
+ const theme = defineTheme({
+ name: 'tree-list-indent-test',
+ components: {
+ 'tree-list': {
+ base: {'--tree-list-indent': 'var(--spacing-5)'},
+ },
+ },
+ });
+ const css = generateThemeCSSFlat(theme);
+ expect(css).toContain('.astryx-tree-list {');
+ expect(css).toContain('--tree-list-indent: var(--spacing-5)');
+ });
+
+ it('rows consume the indent step in their published indent distance', () => {
+ // Each row's --_tree-indent is calc(level * var(--tree-list-indent)),
+ // so retuning the step scales every level uniformly.
+ render(<TreeList items={deepItems} variant="noGuides" />);
+ const indentOf = (text: string): string => {
+ const li = screen.getByText(text).closest('li')!;
+ const styled = li.querySelector('[style*="--_tree-indent"]');
+ return styled?.getAttribute('style') ?? '';
+ };
+ expect(indentOf('Mid')).toContain('var(--tree-list-indent)');
+ expect(indentOf('Leaf')).toContain('var(--tree-list-indent)');
+ });
+ });
+
// ===========================================================================
// xds class name
// ===========================================================================
diff --git a/packages/core/src/TreeList/TreeList.tsx b/packages/core/src/TreeList/TreeList.tsx
index 8e9f0ad138..02bc14d2cb 100644
--- a/packages/core/src/TreeList/TreeList.tsx
+++ b/packages/core/src/TreeList/TreeList.tsx
@@ -83,6 +83,11 @@ export interface TreeListProps extends BaseProps<HTMLDivElement> {
const styles = stylex.create({
root: {
position: 'relative',
+ // Per-level indentation step. Public, themeable lever: a theme can retune
+ // the tree's indent metric (e.g. to `var(--spacing-5)`) via `defineTheme`
+ // on the `tree-list` target, and both the row margins (TreeListItem) and
+ // the guide-line offsets (TreeListBranches) read it so they stay aligned.
+ '--tree-list-indent': spacingVars['--spacing-4'],
},
list: {
margin: 0,
diff --git a/packages/core/src/TreeList/TreeListBranches.tsx b/packages/core/src/TreeList/TreeListBranches.tsx
index 12eb8fdb4c..5affefca55 100644
--- a/packages/core/src/TreeList/TreeListBranches.tsx
+++ b/packages/core/src/TreeList/TreeListBranches.tsx
@@ -26,8 +26,10 @@ const LINE_WIDTH = 1;
*/
const BRANCH_MARGIN = `calc(${spacingVars['--spacing-2']} + ${spacingVars['--spacing-0-5']})`;
-/** Per-level indent width, matching --spacing-4 (16px). */
-const LEVEL_INDENT = spacingVars['--spacing-4'];
+/** 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
+ * lines stay aligned with the row indent when a theme retunes the step. */
+const LEVEL_INDENT = 'var(--tree-list-indent)';
const styles = stylex.create({
container: {
diff --git a/packages/core/src/TreeList/TreeListItem.tsx b/packages/core/src/TreeList/TreeListItem.tsx
index c22273dabc..d3a4968f94 100644
--- a/packages/core/src/TreeList/TreeListItem.tsx
+++ b/packages/core/src/TreeList/TreeListItem.tsx
@@ -82,6 +82,12 @@ const styles = stylex.create({
position: 'relative',
boxSizing: 'border-box',
textAlign: 'start',
+ // Per-level indent. Declared here (not inline) so it lives in
+ // `@layer astryx-base` and the theme layer can override it in normal
+ // cascade order — an inline longhand would outrank every layer. The row
+ // publishes only the computed distance as `--_tree-indent`; the per-level
+ // step is the public `--tree-list-indent` lever (see TreeList `root`).
+ marginInlineStart: 'var(--_tree-indent, 0px)',
},
interactive: {
cursor: 'pointer',
@@ -246,6 +252,11 @@ const descriptionSizeStyles = stylex.create({
},
});
+// `CSSProperties` has no index signature for custom properties, so the row's
+// inline style — which publishes the computed indent distance as the private
+// `--_tree-indent` — needs this augmentation to typecheck.
+type IndentStyle = React.CSSProperties & Record<'--_tree-indent', string>;
+
// =============================================================================
// Types
// =============================================================================
@@ -353,9 +364,18 @@ export function TreeListItem({
return undefined;
}, [onClick, hasChildren, onToggle, id, isDisabled]);
- const computedMarginLeft = hasChildren
- ? `calc(${nestedLevel} * ${spacingVars['--spacing-4']})`
- : `calc(${nestedLevel} * ${spacingVars['--spacing-4']} + ${spacingVars['--spacing-4']} + ${spacingVars['--spacing-2']})`;
+ // Per-level indent distance. The per-level step is the public, themeable
+ // `--tree-list-indent` lever (default `--spacing-4`, set on the tree-list
+ // root). Leaves add a fixed chevron-column offset (chevron width + gap) so
+ // their labels line up with sibling parents' labels; that offset is tied to
+ // the chevron's own dimensions, not the indent step, so it does not scale
+ // with the lever. Published as the private `--_tree-indent` and consumed by
+ // `contentWrapper`'s stylesheet `margin-inline-start` (kept out of the inline
+ // style so the theme layer can override it — see #4308).
+ const indentDistance = hasChildren
+ ? `calc(${nestedLevel} * var(--tree-list-indent))`
+ : `calc(${nestedLevel} * var(--tree-list-indent) + ${spacingVars['--spacing-4']} + ${spacingVars['--spacing-2']})`;
+ const indentStyle: IndentStyle = {'--_tree-indent': indentDistance};
const labelAndDescription = (
<>
@@ -529,7 +549,7 @@ export function TreeListItem({
isSelected && styles.selected,
),
)}
- style={{marginInlineStart: computedMarginLeft}}
+ style={indentStyle}
onClick={handleClick}>
{innerContent}
</div>