Skip to content

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

TypeScript

feat(tree-list): add astryx-tree-list-item-label theme target (#4306)

freddymeta33a6cdc21d5b
diff --git a/.changeset/tree-list-item-label-theme-target.md b/.changeset/tree-list-item-label-theme-target.md
new file mode 100644
index 0000000000..4271646470
--- /dev/null
+++ b/.changeset/tree-list-item-label-theme-target.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] TreeList: add a dedicated `astryx-tree-list-item-label` theme target on the item's label text, so consumers can theme just the label (e.g. bold the selected item's label) via `defineTheme` instead of a fragile `button:not([data-tree-toggle]) > span` structural selector. Reflects the row's `selected` state as a `data-selected` attribute on the label.
+
+@freddymeta
diff --git a/apps/storybook/stories/TreeList.stories.tsx b/apps/storybook/stories/TreeList.stories.tsx
index c67da19706..bad0b0747f 100644
--- a/apps/storybook/stories/TreeList.stories.tsx
+++ b/apps/storybook/stories/TreeList.stories.tsx
@@ -355,6 +355,29 @@ const chevronTheme = defineTheme({
},
});
+/**
+ * Theme the item label text precisely via `defineTheme`.
+ *
+ * - `components['tree-list-item-label'].base` scopes overrides to the label
+ * text only (via the `astryx-tree-list-item-label` target), instead of a
+ * fragile `button:not([data-tree-toggle]) > span` structural selector.
+ * - `selected` restyles just the selected item's label (bold here), which the
+ * label reflects as a `data-selected` attribute.
+ *
+ * Defaults are unchanged; this story only demonstrates the override channel.
+ */
+const labelTheme = defineTheme({
+ name: 'tree-list-item-label-demo',
+ components: {
+ 'tree-list-item-label': {
+ selected: {
+ fontWeight: 'var(--font-weight-bold)',
+ color: 'var(--color-accent)',
+ },
+ },
+ },
+});
+
export const ThemedChevron: Story = {
render: () => (
<Theme theme={chevronTheme} mode="light">
@@ -378,3 +401,29 @@ export const ThemedChevron: Story = {
</Theme>
),
};
+
+export const ThemedItemLabel: Story = {
+ render: () => (
+ <Theme theme={labelTheme} mode="light">
+ <TreeList
+ items={[
+ {
+ id: 'nav',
+ label: 'Navigation',
+ isExpanded: true,
+ children: [
+ {id: 'home', label: 'Home', onClick: noop},
+ {
+ id: 'about',
+ label: 'About (selected — bold accent label)',
+ onClick: noop,
+ isSelected: true,
+ },
+ {id: 'contact', label: 'Contact', onClick: noop},
+ ],
+ },
+ ]}
+ />
+ </Theme>
+ ),
+};
diff --git a/packages/core/src/TreeList/TreeList.doc.mjs b/packages/core/src/TreeList/TreeList.doc.mjs
index 5a4180e882..247b7a5937 100644
--- a/packages/core/src/TreeList/TreeList.doc.mjs
+++ b/packages/core/src/TreeList/TreeList.doc.mjs
@@ -27,6 +27,7 @@ export const docs = {
{className: 'astryx-tree-list', visualProps: ['density']},
{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']},
],
},
components: [
@@ -92,6 +93,7 @@ export const docsZh = {
{className: 'astryx-tree-list', visualProps: ['density']},
{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']},
],
},
components: [
diff --git a/packages/core/src/TreeList/TreeList.test.tsx b/packages/core/src/TreeList/TreeList.test.tsx
index ab059772be..7dec44d6ca 100644
--- a/packages/core/src/TreeList/TreeList.test.tsx
+++ b/packages/core/src/TreeList/TreeList.test.tsx
@@ -468,6 +468,64 @@ describe('TreeList', () => {
});
});
+ // ===========================================================================
+ // Item label theme target
+ // ===========================================================================
+
+ describe('item label theme target', () => {
+ it('renders the astryx-tree-list-item-label target on the label span', () => {
+ render(<TreeList items={simpleItems} />);
+ const label = screen.getByText('Item A');
+
+ // Dedicated, stable theme target on the label text, so a theme can style
+ // just the label without a fragile `button:not([data-tree-toggle]) > span`
+ // structural selector.
+ expect(label).toHaveClass('astryx-tree-list-item-label');
+ // A non-selected item's label carries no selected reflection.
+ expect(label).not.toHaveAttribute('data-selected');
+ });
+
+ it('reflects the selected state on the selected item label', () => {
+ render(
+ <TreeList items={[{id: 'a', label: 'Item A', isSelected: true}]} />,
+ );
+ const label = screen.getByText('Item A');
+ expect(label).toHaveClass('astryx-tree-list-item-label');
+ expect(label).toHaveAttribute('data-selected', 'selected');
+ });
+
+ it('keeps the label linked to its row via aria-labelledby', () => {
+ // The theme target is additive — the label still owns the id the
+ // interactive row references for its accessible name.
+ render(
+ <TreeList items={[{id: 'a', label: 'Item A', onClick: () => {}}]} />,
+ );
+ const label = screen.getByText('Item A');
+ const action = screen.getByRole('button');
+ expect(action).toHaveAttribute('aria-labelledby', label.id);
+ });
+
+ it('exposes tree-list-item-label as a themeable defineTheme target', () => {
+ // The generated CSS is what proves the target is reachable by a theme:
+ // jsdom cannot resolve the @layer cascade, so the DOM-class assertions
+ // above and this generation assertion together cover the seam.
+ const theme = defineTheme({
+ name: 'tree-list-item-label-test',
+ components: {
+ 'tree-list-item-label': {
+ base: {color: 'var(--color-text-primary)'},
+ selected: {fontWeight: 'var(--font-weight-bold)'},
+ },
+ },
+ });
+ const css = generateThemeCSSFlat(theme);
+ expect(css).toContain('.astryx-tree-list-item-label {');
+ expect(css).toContain('color: var(--color-text-primary)');
+ expect(css).toContain('.astryx-tree-list-item-label.selected');
+ expect(css).toContain('font-weight: var(--font-weight-bold)');
+ });
+ });
+
// ===========================================================================
// APG structural ARIA (aria-level / aria-posinset / aria-setsize)
// ===========================================================================
diff --git a/packages/core/src/TreeList/TreeListItem.tsx b/packages/core/src/TreeList/TreeListItem.tsx
index 8aeb3d6b9d..0ce83450c5 100644
--- a/packages/core/src/TreeList/TreeListItem.tsx
+++ b/packages/core/src/TreeList/TreeListItem.tsx
@@ -352,7 +352,20 @@ export function TreeListItem({
const labelAndDescription = (
<>
- <span id={labelId} {...stylex.props(styles.label)}>
+ <span
+ id={labelId}
+ {...mergeProps(
+ // Stable theme target for the item's label text. The label carries no
+ // themeable handle today, so a theme can only reach it through a
+ // fragile structural selector (a content button's first span). This
+ // adds an `astryx-tree-list-item-label` class and reflects the row's
+ // `selected` state so a theme can, e.g., bold just the selected
+ // item's label via `defineTheme`.
+ themeProps('tree-list-item-label', {
+ selected: isSelected ? 'selected' : null,
+ }),
+ stylex.props(styles.label),
+ )}>
{label}
</span>
{description != null && (