Skip to content

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

TypeScript

feat(calendar): make the today/selected day-cell ring precisely themeable (#4289)

freddymetad6d955c334a0
diff --git a/.changeset/calendar-day-ring-states.md b/.changeset/calendar-day-ring-states.md
new file mode 100644
index 0000000000..e03f728db3
--- /dev/null
+++ b/.changeset/calendar-day-ring-states.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Calendar: make the today/selected day-cell ring precisely themeable. The day cell now reflects a compound `marker` state (`today-only` / `today-in-range`) that maps 1:1 to the treatment actually drawn, so `defineTheme({components: {'calendar-day': {'marker:today-only': {...}}}})` targets exactly those states without over-matching or needing a `:not()` exclusion. Default rendering is unchanged.
+
+@freddymeta
diff --git a/apps/storybook/stories/Calendar.stories.tsx b/apps/storybook/stories/Calendar.stories.tsx
index 81886c26ae..ec3e4d1159 100644
--- a/apps/storybook/stories/Calendar.stories.tsx
+++ b/apps/storybook/stories/Calendar.stories.tsx
@@ -7,6 +7,7 @@ import {
type ISODateString,
type DateRange,
} from '@astryxdesign/core/Calendar';
+import {Theme, defineTheme} from '@astryxdesign/core/theme';
const meta: Meta<typeof Calendar> = {
title: 'Core/Calendar',
@@ -273,3 +274,47 @@ export const AllVariations: Story = {
);
},
};
+
+/**
+ * Theme the selected-date and today rings precisely via `defineTheme`.
+ *
+ * The day cell reflects a compound `marker` state that maps 1:1 to the
+ * treatment actually drawn — `marker:today-only` for a plain today cell and
+ * `marker:today-in-range` for today inside a range — plus the existing
+ * `selected` state for the selection fill. A theme can restyle each without
+ * needing a `:not()` exclusion or over-matching the states where no ring is
+ * shown.
+ *
+ * Defaults are unchanged; this story only demonstrates the override channel.
+ */
+const markerTheme = defineTheme({
+ name: 'calendar-marker-demo',
+ components: {
+ 'calendar-day': {
+ selected: {
+ backgroundColor: 'var(--color-success)',
+ },
+ 'marker:today-only': {
+ boxShadow: 'inset 0 0 0 2px var(--color-accent)',
+ },
+ 'marker:today-in-range': {
+ boxShadow: 'inset 0 0 0 2px var(--color-warning)',
+ },
+ },
+ },
+});
+
+export const ThemedSelectedAndTodayRing: Story = {
+ render: () => {
+ const [value, setValue] = useState<DateRange | undefined>(undefined);
+ return (
+ <Theme theme={markerTheme} mode="light">
+ <Calendar
+ mode="range"
+ value={value}
+ onChange={range => setValue(range)}
+ />
+ </Theme>
+ );
+ },
+};
diff --git a/packages/core/src/Calendar/Calendar.doc.mjs b/packages/core/src/Calendar/Calendar.doc.mjs
index c9941d36f6..e3fc57f3c5 100644
--- a/packages/core/src/Calendar/Calendar.doc.mjs
+++ b/packages/core/src/Calendar/Calendar.doc.mjs
@@ -111,7 +111,7 @@ export const docs = {
theming: {
targets: [
{className: 'astryx-calendar', visualProps: ['mode']},
- {className: 'astryx-calendar-day', states: ['selected', 'today', 'disabled', 'in-range']},
+ {className: 'astryx-calendar-day', states: ['selected', 'today', 'disabled', 'in-range', 'marker']},
],
},
};
@@ -164,6 +164,7 @@ export const docsZh = {
'today',
'disabled',
'in-range',
+ 'marker',
],
},
],
diff --git a/packages/core/src/Calendar/Calendar.test.tsx b/packages/core/src/Calendar/Calendar.test.tsx
index 8e149bbdda..e2c9204103 100644
--- a/packages/core/src/Calendar/Calendar.test.tsx
+++ b/packages/core/src/Calendar/Calendar.test.tsx
@@ -16,7 +16,10 @@ import {getButton} from '../__tests__/fastRoleQueries';
import * as stylex from '@stylexjs/stylex';
import {Calendar} from './Calendar';
import type {CalendarHandle} from './Calendar';
+import type {ISODateString} from './Calendar';
import {calendarStyles} from './styles';
+import {defineTheme} from '../theme/defineTheme';
+import {generateThemeCSSFlat} from '../theme/generateThemeRules';
import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
afterEach(() => {
@@ -881,4 +884,114 @@ describe('Calendar', () => {
expect(screen.getByText('February 2026')).toBeInTheDocument();
});
});
+
+ // ─── Day-cell marker theming (#4286) ─────────────────────────
+ describe('day-cell marker theme state', () => {
+ // Tests use the real "today" (as the existing aria-current tests do) since
+ // Calendar derives it internally. Helpers pin the exact ISO strings.
+ function todayISO(): ISODateString {
+ const n = new Date();
+ return `${n.getFullYear()}-${String(n.getMonth() + 1).padStart(2, '0')}-${String(n.getDate()).padStart(2, '0')}` as ISODateString;
+ }
+ function isoOffsetFromToday(deltaDays: number): ISODateString {
+ const n = new Date();
+ n.setDate(n.getDate() + deltaDays);
+ return `${n.getFullYear()}-${String(n.getMonth() + 1).padStart(2, '0')}-${String(n.getDate()).padStart(2, '0')}` as ISODateString;
+ }
+ function todayCell(): HTMLElement {
+ const el = document.querySelector<HTMLElement>(
+ `button[data-date="${todayISO()}"]`,
+ );
+ expect(el).not.toBeNull();
+ return el as HTMLElement;
+ }
+
+ it('reflects marker="today-only" for a plain today cell (no selection)', () => {
+ render(<Calendar />);
+ const cell = todayCell();
+ expect(cell).toHaveAttribute('data-marker', 'today-only');
+ expect(cell).toHaveAttribute('data-today', 'today');
+ expect(cell).not.toHaveAttribute('data-selected');
+ expect(cell).not.toHaveAttribute('data-in-range');
+ });
+
+ it('reflects marker="today-in-range" when today is strictly inside a range', () => {
+ render(
+ <Calendar
+ mode="range"
+ value={{start: isoOffsetFromToday(-2), end: isoOffsetFromToday(2)}}
+ />,
+ );
+ const cell = todayCell();
+ // Today is inside the range but not an endpoint: the today-in-range ring
+ // is shown, so `marker` reflects that compound state precisely.
+ expect(cell).toHaveAttribute('data-marker', 'today-in-range');
+ expect(cell).toHaveAttribute('data-in-range', 'in-range');
+ expect(cell).not.toHaveAttribute('data-selected');
+ });
+
+ it('shows no marker state when today is the single-selected date', () => {
+ render(<Calendar mode="single" value={todayISO()} />);
+ const cell = todayCell();
+ // A single-mode selected cell shows no ring by default — `marker` is
+ // absent, while `selected` (which owns the selected treatment) is present.
+ expect(cell).not.toHaveAttribute('data-marker');
+ expect(cell).toHaveAttribute('data-selected', 'selected');
+ expect(cell).toHaveAttribute('data-today', 'today');
+ });
+
+ it('preserves the today-in-range ring on a today range endpoint', () => {
+ render(
+ <Calendar
+ mode="range"
+ value={{start: todayISO(), end: isoOffsetFromToday(3)}}
+ />,
+ );
+ const cell = todayCell();
+ // A range endpoint is NOT `isSelected` (that flag is single-mode only),
+ // so by default the today-in-range ring IS drawn on a today endpoint
+ // alongside the endpoint styling. `marker` mirrors that exactly — this
+ // asserts the default rendering is preserved, byte-for-byte.
+ expect(cell).toHaveAttribute('data-marker', 'today-in-range');
+ expect(cell).toHaveAttribute('data-in-range', 'in-range');
+ });
+
+ it('omits the marker state for non-today cells', () => {
+ render(<Calendar />);
+ const other = document.querySelector(
+ `button[data-date="${isoOffsetFromToday(1)}"]`,
+ );
+ // Guard against the +1 day landing in an adjacent month with outside days
+ // hidden; if present it must carry no marker.
+ if (other) {
+ expect(other).not.toHaveAttribute('data-marker');
+ }
+ });
+
+ it('exposes the marker states as themeable defineTheme targets', () => {
+ // jsdom can't resolve the @layer cascade, so the DOM-reflection tests
+ // above cover that the right state renders; this asserts the state is
+ // reachable by a theme via the sanctioned defineTheme channel.
+ const theme = defineTheme({
+ name: 'calendar-marker-test',
+ components: {
+ 'calendar-day': {
+ 'marker:today-only': {
+ boxShadow: 'inset 0 0 0 2px var(--color-accent)',
+ },
+ 'marker:today-in-range': {
+ boxShadow: 'inset 0 0 0 2px var(--color-text-primary)',
+ },
+ },
+ },
+ });
+ const css = generateThemeCSSFlat(theme);
+ expect(css).toContain('.astryx-calendar-day.today-only');
+ expect(css).toContain('.astryx-calendar-day.today-in-range');
+ expect(css).toContain('box-shadow: inset 0 0 0 2px var(--color-accent)');
+ expect(css).toContain(
+ 'box-shadow: inset 0 0 0 2px var(--color-text-primary)',
+ );
+ });
+ });
});
diff --git a/packages/core/src/Calendar/Calendar.tsx b/packages/core/src/Calendar/Calendar.tsx
index f503802984..6cad5ac1b7 100644
--- a/packages/core/src/Calendar/Calendar.tsx
+++ b/packages/core/src/Calendar/Calendar.tsx
@@ -941,6 +941,21 @@ function DayCell({
});
const endpoint = isEndpoint(state);
+
+ // The day's focus-ring treatment, derived once so the reflected `marker`
+ // theme state and the StyleX ring styles below share a single source of
+ // truth. `state.isSelected` is single-select only, so a range endpoint that
+ // is today still qualifies for the today-in-range ring (unchanged prior
+ // behavior).
+ const showsTodayRing = state.isToday && !state.isSelected && !state.isInRange;
+ const showsTodayInRangeRing =
+ state.isToday && !state.isSelected && state.isInRange;
+ const markerState: 'today-only' | 'today-in-range' | null = showsTodayRing
+ ? 'today-only'
+ : showsTodayInRangeRing
+ ? 'today-in-range'
+ : null;
+
const rangeRounding = computeRangeRounding(state, {
prevInRange: neighbors.prevInRange,
nextInRange: neighbors.nextInRange,
@@ -1010,28 +1025,27 @@ function DayCell({
today: state.isToday ? 'today' : null,
disabled: state.effectivelyDisabled ? 'disabled' : null,
'in-range': state.isInRange ? 'in-range' : null,
+ // `marker` reflects the day's *actual* focus-ring treatment as a
+ // single compound state, so a theme can target exactly the states
+ // the ring is drawn under without needing `:not()` in the theme
+ // key. It is null unless a ring is shown:
+ // 'today-only' → today, not single-selected, not in a range
+ // 'today-in-range' → today, not single-selected, inside a range
+ // `isSelected` here is single-select only (see computeDayCellState),
+ // so a today range endpoint still shows the today-in-range ring —
+ // `marker` mirrors the StyleX conditions below exactly, preserving
+ // the default rendering.
+ marker: markerState,
}),
stylex.props(
dayCellStyles.day,
dayCellTheme.day,
isOutside && dayCellStyles.dayOutside,
isOutside && dayCellTheme.dayOutside,
- state.isToday &&
- !state.isSelected &&
- !state.isInRange &&
- dayCellStyles.dayToday,
- state.isToday &&
- !state.isSelected &&
- !state.isInRange &&
- dayCellTheme.dayToday,
- state.isToday &&
- !state.isSelected &&
- state.isInRange &&
- dayCellStyles.dayTodayInRange,
- state.isToday &&
- !state.isSelected &&
- state.isInRange &&
- dayCellTheme.dayTodayInRange,
+ showsTodayRing && dayCellStyles.dayToday,
+ showsTodayRing && dayCellTheme.dayToday,
+ showsTodayInRangeRing && dayCellStyles.dayTodayInRange,
+ showsTodayInRangeRing && dayCellTheme.dayTodayInRange,
endpoint && dayCellStyles.daySelected,
endpoint && dayCellTheme.daySelected,
state.effectivelyDisabled && dayCellStyles.dayDisabled,