Skip to content

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

TypeScript

feat(calendar): add calendar-nav theme target for month-nav controls (#4287)

freddymeta2b006182683e
diff --git a/.changeset/calendar-nav-theme-target.md b/.changeset/calendar-nav-theme-target.md
new file mode 100644
index 0000000000..00c9558c23
--- /dev/null
+++ b/.changeset/calendar-nav-theme-target.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Calendar: add a dedicated `astryx-calendar-nav` theme target for the prev/next month-nav buttons, so consumers can theme the nav controls (color, radius, per-direction, disabled edge) without reaching every Button via the global `astryx-button` handle. Reflects `nav` (prev/next) and the `disabled` state as data attributes.
+
+@freddymeta
diff --git a/apps/storybook/stories/Calendar.stories.tsx b/apps/storybook/stories/Calendar.stories.tsx
index ec3e4d1159..4410a655ef 100644
--- a/apps/storybook/stories/Calendar.stories.tsx
+++ b/apps/storybook/stories/Calendar.stories.tsx
@@ -318,3 +318,52 @@ export const ThemedSelectedAndTodayRing: Story = {
);
},
};
+
+/**
+ * Theme the month-nav controls and the selected-date ring independently of the
+ * rest of the app, using `defineTheme`.
+ *
+ * - `components['calendar-nav']` scopes overrides to the prev/next month
+ * buttons only (via the `astryx-calendar-nav` target), instead of the global
+ * `astryx-button` handle that would hit every Button in the app. The
+ * `nav` visual prop and `disabled` state are reflected as data
+ * attributes, so a theme can target one arrow or the disabled edge alone.
+ * - `components['calendar-day'].selected` restyles the selected-date treatment
+ * (the `astryx-calendar-day` target with its `selected` state).
+ */
+const navRingTheme = defineTheme({
+ name: 'calendar-nav-ring',
+ components: {
+ 'calendar-nav': {
+ base: {
+ color: 'var(--color-accent)',
+ borderRadius: 'var(--radius-inner)',
+ },
+ 'nav:next': {
+ backgroundColor: 'var(--color-accent-muted)',
+ },
+ },
+ 'calendar-day': {
+ selected: {
+ backgroundColor: 'var(--color-success)',
+ boxShadow: 'inset 0 0 0 2px var(--color-on-accent)',
+ },
+ },
+ },
+});
+
+export const ThemedNavAndSelectedRing: Story = {
+ render: () => {
+ const [value, setValue] = useState<ISODateString>('2026-01-15');
+ return (
+ <Theme theme={navRingTheme} mode="light">
+ <Calendar
+ mode="single"
+ value={value}
+ onChange={val => setValue(val)}
+ focusDate="2026-01-01"
+ />
+ </Theme>
+ );
+ },
+};
diff --git a/packages/core/src/Calendar/Calendar.doc.mjs b/packages/core/src/Calendar/Calendar.doc.mjs
index e3fc57f3c5..b943da1fb0 100644
--- a/packages/core/src/Calendar/Calendar.doc.mjs
+++ b/packages/core/src/Calendar/Calendar.doc.mjs
@@ -111,6 +111,7 @@ export const docs = {
theming: {
targets: [
{className: 'astryx-calendar', visualProps: ['mode']},
+ {className: 'astryx-calendar-nav', visualProps: ['nav'], states: ['disabled']},
{className: 'astryx-calendar-day', states: ['selected', 'today', 'disabled', 'in-range', 'marker']},
],
},
@@ -157,6 +158,15 @@ export const docsZh = {
'mode',
],
},
+ {
+ className: 'astryx-calendar-nav',
+ visualProps: [
+ 'nav',
+ ],
+ states: [
+ 'disabled',
+ ],
+ },
{
className: 'astryx-calendar-day',
states: [
diff --git a/packages/core/src/Calendar/Calendar.test.tsx b/packages/core/src/Calendar/Calendar.test.tsx
index e2c9204103..df13b9e62a 100644
--- a/packages/core/src/Calendar/Calendar.test.tsx
+++ b/packages/core/src/Calendar/Calendar.test.tsx
@@ -885,6 +885,7 @@ describe('Calendar', () => {
});
});
+
// ─── Day-cell marker theming (#4286) ─────────────────────────
describe('day-cell marker theme state', () => {
// Tests use the real "today" (as the existing aria-current tests do) since
@@ -994,4 +995,83 @@ describe('Calendar', () => {
);
});
});
+
+ // ─── Theming targets ─────────────────────────────────────────
+ describe('theming targets', () => {
+ it('renders the astryx-calendar-nav target on both month-nav buttons', () => {
+ render(<Calendar focusDate="2026-01-01" />);
+
+ const prev = getButton('Previous month');
+ const next = getButton('Next month');
+
+ // Dedicated, stable theme target — scoped to the nav controls, not the
+ // global astryx-button handle that hits every Button in the app.
+ expect(prev).toHaveClass('astryx-calendar-nav');
+ expect(next).toHaveClass('astryx-calendar-nav');
+
+ // Direction is reflected so a theme can target one arrow alone.
+ expect(prev).toHaveAttribute('data-nav', 'prev');
+ expect(next).toHaveAttribute('data-nav', 'next');
+ });
+
+ it('reflects the disabled nav state as a data attribute at the range edges', () => {
+ // Clamp navigation so "Previous month" is disabled and "Next" is not.
+ render(
+ <Calendar focusDate="2026-01-15" min="2026-01-01" max="2026-03-31" />,
+ );
+
+ const prev = getButton('Previous month');
+ const next = getButton('Next month');
+
+ expect(prev).toHaveAttribute('data-disabled', 'disabled');
+ expect(next).not.toHaveAttribute('data-disabled');
+ });
+
+ it('keeps the default nav rendering unchanged (still a ghost icon button)', () => {
+ render(<Calendar focusDate="2026-01-01" />);
+
+ // The new target is additive — the nav still carries the stock Button
+ // classes, so default appearance is preserved.
+ const prev = getButton('Previous month');
+ expect(prev).toHaveClass('astryx-button');
+ expect(prev).toHaveClass('ghost');
+ expect(prev.tagName).toBe('BUTTON');
+ });
+
+ it('renders the astryx-calendar-day target with its reflected states', () => {
+ render(
+ <Calendar mode="single" value="2026-01-15" focusDate="2026-01-01" />,
+ );
+
+ const selected = getDayButton(15);
+ expect(selected).toHaveClass('astryx-calendar-day');
+ expect(selected).toHaveAttribute('data-selected', 'selected');
+
+ // A non-selected weekday cell still carries the base target and no
+ // selected/today reflection.
+ const plain = getDayButton(20);
+ expect(plain).toHaveClass('astryx-calendar-day');
+ expect(plain).not.toHaveAttribute('data-selected');
+ });
+
+ it('exposes calendar-nav 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: 'calendar-nav-test',
+ components: {
+ 'calendar-nav': {
+ base: {color: 'var(--color-accent)'},
+ 'nav:next': {backgroundColor: 'var(--color-accent-muted)'},
+ },
+ },
+ });
+ const css = generateThemeCSSFlat(theme);
+ expect(css).toContain('.astryx-calendar-nav {');
+ expect(css).toContain('color: var(--color-accent)');
+ expect(css).toContain('.astryx-calendar-nav.next');
+ expect(css).toContain('background-color: var(--color-accent-muted)');
+ });
+ });
});
diff --git a/packages/core/src/Calendar/Calendar.tsx b/packages/core/src/Calendar/Calendar.tsx
index 6cad5ac1b7..197b5e5dc4 100644
--- a/packages/core/src/Calendar/Calendar.tsx
+++ b/packages/core/src/Calendar/Calendar.tsx
@@ -452,6 +452,10 @@ export function Calendar({ref, ...props}: CalendarProps) {
{/* Header with navigation */}
<div {...stylex.props(calendarStyles.header)}>
<Button
+ {...themeProps('calendar-nav', {
+ nav: 'prev',
+ disabled: !canNavigatePrevious ? 'disabled' : null,
+ })}
label={t('@astryx.calendar.previousMonth')}
variant="ghost"
icon={
@@ -472,6 +476,10 @@ export function Calendar({ref, ...props}: CalendarProps) {
</span>
<Button
+ {...themeProps('calendar-nav', {
+ nav: 'next',
+ disabled: !canNavigateNext ? 'disabled' : null,
+ })}
label={t('@astryx.calendar.nextMonth')}
variant="ghost"
icon={