Skip to content

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

TypeScript

feat(command-palette): add command-palette-group-heading theme target (#4422)

freddymetaf5a628613b9f
diff --git a/.changeset/command-palette-group-heading-theme-target.md b/.changeset/command-palette-group-heading-theme-target.md
new file mode 100644
index 0000000000..4577eeeaed
--- /dev/null
+++ b/.changeset/command-palette-group-heading-theme-target.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] CommandPalette: add a dedicated `astryx-command-palette-group-heading` theme target on the group heading, so consumers can theme just the heading (e.g. its padding or typography) via `defineTheme` instead of a fragile structural selector. The group root keeps its own `astryx-command-palette-group` target.
+
+@freddymeta
diff --git a/apps/storybook/stories/CommandPalette.stories.tsx b/apps/storybook/stories/CommandPalette.stories.tsx
index 413a2bd52e..ade86f3f8e 100644
--- a/apps/storybook/stories/CommandPalette.stories.tsx
+++ b/apps/storybook/stories/CommandPalette.stories.tsx
@@ -13,9 +13,11 @@ import {
CommandPalette,
CommandPaletteInput,
CommandPaletteFooter,
+ CommandPaletteGroup,
} from '@astryxdesign/core/CommandPalette';
import {Button} from '@astryxdesign/core/Button';
import {Icon} from '@astryxdesign/core/Icon';
+import {Theme, defineTheme} from '@astryxdesign/core/theme';
import {createStaticSource} from '@astryxdesign/core/Typeahead';
import type {SearchSource, SearchableItem} from '@astryxdesign/core/Typeahead';
import type {IconName} from '@astryxdesign/core/Icon';
@@ -48,10 +50,7 @@ export const Default: Story = {
);
return (
<>
- <Button
- label="Open Command Palette"
- onClick={() => setIsOpen(true)}
- />
+ <Button label="Open Command Palette" onClick={() => setIsOpen(true)} />
<CommandPalette
isOpen={isOpen}
onOpenChange={setIsOpen}
@@ -375,3 +374,40 @@ export const CustomFooter: Story = {
);
},
};
+
+// ─── Themed group heading ─────────────────────────────────────────────────────
+
+/**
+ * Theme the group heading precisely via `defineTheme`.
+ *
+ * `components['command-palette-group-heading'].base` scopes overrides to the
+ * heading text only (via the `astryx-command-palette-group-heading` target),
+ * instead of a fragile structural selector. The group root keeps its own
+ * `astryx-command-palette-group` target.
+ *
+ * Defaults are unchanged; this story only demonstrates the override channel.
+ */
+const groupHeadingTheme = defineTheme({
+ name: 'command-palette-group-heading-demo',
+ components: {
+ 'command-palette-group-heading': {
+ base: {
+ fontWeight: 'var(--font-weight-bold)',
+ color: 'var(--color-accent)',
+ textTransform: 'uppercase',
+ },
+ },
+ },
+});
+
+export const ThemedGroupHeading: Story = {
+ render: () => (
+ <Theme theme={groupHeadingTheme} mode="light">
+ <CommandPaletteGroup heading="Suggestions">
+ <div>Home</div>
+ <div>Settings</div>
+ <div>Profile</div>
+ </CommandPaletteGroup>
+ </Theme>
+ ),
+};
diff --git a/packages/core/src/CommandPalette/CommandPalette.doc.mjs b/packages/core/src/CommandPalette/CommandPalette.doc.mjs
index f6da27b2a2..98f8f4a5d5 100644
--- a/packages/core/src/CommandPalette/CommandPalette.doc.mjs
+++ b/packages/core/src/CommandPalette/CommandPalette.doc.mjs
@@ -145,6 +145,7 @@ export const docs = {
{className: 'astryx-command-palette-empty'},
{className: 'astryx-command-palette-footer'},
{className: 'astryx-command-palette-group'},
+ {className: 'astryx-command-palette-group-heading'},
{className: 'astryx-command-palette-input'},
{className: 'astryx-command-palette-item'},
{className: 'astryx-command-palette-list'},
diff --git a/packages/core/src/CommandPalette/CommandPaletteGroup.test.tsx b/packages/core/src/CommandPalette/CommandPaletteGroup.test.tsx
index 069191eef9..0f0af6cd70 100644
--- a/packages/core/src/CommandPalette/CommandPaletteGroup.test.tsx
+++ b/packages/core/src/CommandPalette/CommandPaletteGroup.test.tsx
@@ -9,6 +9,8 @@
import {describe, it, expect} from 'vitest';
import {render, screen} from '@testing-library/react';
import {CommandPaletteGroup} from './CommandPaletteGroup';
+import {defineTheme} from '../theme/defineTheme';
+import {generateThemeCSSFlat} from '../theme/generateThemeRules';
describe('CommandPaletteGroup', () => {
it('renders heading', () => {
@@ -51,4 +53,73 @@ describe('CommandPaletteGroup', () => {
'true',
);
});
+
+ // ===========================================================================
+ // Heading theme target
+ // ===========================================================================
+
+ describe('heading theme target', () => {
+ it('renders the astryx-command-palette-group-heading target on the heading', () => {
+ render(
+ <CommandPaletteGroup heading="Suggestions">
+ <div>Item</div>
+ </CommandPaletteGroup>,
+ );
+ const heading = screen.getByText('Suggestions');
+
+ // The root carries `astryx-command-palette-group`; this is the stable
+ // handle on the heading itself, so a theme can style just the heading
+ // without a fragile structural selector.
+ expect(heading).toHaveClass('astryx-command-palette-group-heading');
+ });
+
+ it('keeps the heading target distinct from the group root target', () => {
+ render(
+ <CommandPaletteGroup heading="Suggestions">
+ <div>Item</div>
+ </CommandPaletteGroup>,
+ );
+ const root = screen.getByRole('group');
+ const heading = screen.getByText('Suggestions');
+
+ expect(root).toHaveClass('astryx-command-palette-group');
+ expect(root).not.toHaveClass('astryx-command-palette-group-heading');
+ expect(heading).not.toHaveClass('astryx-command-palette-group');
+ });
+
+ it('leaves the heading decorative (additive target only)', () => {
+ // The target adds a class and nothing else — the heading stays
+ // aria-hidden so grouping remains announced via the root's aria-label.
+ render(
+ <CommandPaletteGroup heading="Suggestions">
+ <div>Item</div>
+ </CommandPaletteGroup>,
+ );
+ expect(screen.getByText('Suggestions')).toHaveAttribute(
+ 'aria-hidden',
+ 'true',
+ );
+ });
+
+ it('exposes command-palette-group-heading as a themeable defineTheme target', () => {
+ // The generated CSS 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: 'command-palette-group-heading-test',
+ components: {
+ 'command-palette-group-heading': {
+ base: {
+ paddingBlock: 'var(--spacing-2)',
+ fontWeight: 'var(--font-weight-bold)',
+ },
+ },
+ },
+ });
+ const css = generateThemeCSSFlat(theme);
+ expect(css).toContain('.astryx-command-palette-group-heading {');
+ expect(css).toContain('padding-block: var(--spacing-2)');
+ expect(css).toContain('font-weight: var(--font-weight-bold)');
+ });
+ });
});
diff --git a/packages/core/src/CommandPalette/CommandPaletteGroup.tsx b/packages/core/src/CommandPalette/CommandPaletteGroup.tsx
index 195c786761..c84650c54c 100644
--- a/packages/core/src/CommandPalette/CommandPaletteGroup.tsx
+++ b/packages/core/src/CommandPalette/CommandPaletteGroup.tsx
@@ -90,7 +90,18 @@ export function CommandPaletteGroup({
style,
)}
{...props}>
- <div aria-hidden="true" {...stylex.props(styles.heading)}>
+ <div
+ aria-hidden="true"
+ {...mergeProps(
+ // Stable theme target for the group heading text. The root carries
+ // `astryx-command-palette-group`, but the heading itself had no
+ // handle, so a theme could only reach it through a fragile structural
+ // selector. This adds an `astryx-command-palette-group-heading` class
+ // so `defineTheme` can scope overrides (e.g. heading typography) to
+ // the heading alone.
+ themeProps('command-palette-group-heading'),
+ stylex.props(styles.heading),
+ )}>
{heading}
</div>
{children}