[Feature] Calendar: match shadcn (Base UI + vega)
Restyles Calendar after shadcn's Base UI + vega Calendar and adds the keyboard support the APG date picker grid describes. Calendar is also added to the shadcn audit (map and fixtures), so later changes get checked.
What changes
- Look: the root is
w-fitwithbg-background(transparent inside card and popover content), so it no longer stretches to the container width. The header ish-8, prev/next are 32px ghost buttons with lucide chevrons, day buttons are transparent withhover:bg-muted, today is abg-mutedcell, and focus uses the vega ring (border-ring ring-3 ring-ring/50). - ARIA: the table is
role=gridlabelled with the month, eachtdis agridcell(witharia-selectedon the selected day), and day buttons are named with the full date, e.g. "Monday, March 16th, 2026", "Today, Friday, March 20th, 2026" or "…, selected". Before, the button itself hadrole=gridcelland screen readers heard just "16". The title isrole=status, and prev/next sit innav aria-label="Navigation bar". - Keyboard: without a selected date no day could be reached with Tab, so a keyboard user could not pick a date. Now one day is always in the Tab order (the selected day, else today, else the first enabled day). Arrows move by day or week and skip disabled days, Home/End go to the start or end of the week, PageUp/PageDown move a month (a year with Shift), and focus follows the day across months. When Home/End/PageUp/PageDown would land on a disabled day, focus stops at the nearest enabled one. With nothing selected and today before
min_date, the calendar opens on themin_datemonth. Focus also stays on the chosen day after selecting; before, the re-render dropped it to<body>. - New
week_starts_on:kwarg (:sundaythrough:saturday, or 0-6). The default is now Sunday, as in shadcn. It used to be hardcoded to Monday, so apps that want Monday needweek_starts_on: :monday.
shadcn's own Base UI calendar.tsx gets the arrow keys wrong: CalendarDayButton creates a ref and never attaches it, so react-day-picker moves its internal focus while DOM focus stays put. RubyUI follows the APG here, not shadcn.
Four differences are registered in audit/divergences.yml: the wrapper divs (Phlex parts plus <template>s; landmarks, grid and labels match), a second click on the selected day keeps it selected (it would empty the linked input_id), no native <input type="date"> (it has no inline month grid), and the React-only props (formatters, components, classNames). showOutsideDays, captionLayout, buttonVariant, locale, range mode and a max date are still missing; they are tracked in #611.
Screenshots
Fixture: March 2026, the 12th selected, days before the 5th disabled. The main column is cropped; there the calendar spans the whole 1232px viewport, so the title and the next button fall outside the crop.





Audit checklist, main
shadcn audit ruby-ui/ruby_ui
base 774e823a head 774e823a shadcn c0d63c33
⚠️ Environment font: "Inter Variable", "system-ui", -apple-system, "system-ui", "Segoe UI", Roboto, "Helvetica Neue", Arial, "sans-serif" vs "Inter Variable", sans-serif (light)
⚠️ Environment font: "Inter Variable", "system-ui", -apple-system, "system-ui", "Segoe UI", Roboto, "Helvetica Neue", Arial, "sans-serif" vs "Inter Variable", sans-serif (dark)
✅ Theme neutral tokens match shadcn
Calendar (ref: bases/base/ui/calendar.tsx + style-vega.css @ c0d63c33)
❌ Look background-color: rgba(0, 0, 0, 0)
vega: background-color: oklch(0.145 0 0); background-color: oklch(1 0 0)
Calendar — closed/light, focus/light, closed/dark, focus/dark | Root: RubyUI `p-3 space-y-4` sets no background; shadcn root `bg-background` (transparent only inside card/popover content). | Requested: add bg-background to the root, transparent inside card/popover content.
↳ computed styles (shadcn-audit collect); bases/base/ui/calendar.tsx:34
⏸ Look properties: font-family, height, width
Calendar — explained by environment diff: font | Kept as is: environment font stack difference, not a component finding.
⚠️ ARIA snapshot: only here: - text: March 2026 | - button "Go to previous month": | - img | - button "Go to next month": | - img | - table: | - row "Monday Tuesday Wednesday Thursday Friday Saturday Sunday": |…
shadcn: snapshot: only here: - navigation "Navigation bar": | - button "Go to the Previous Month" | - button "Go to the Next Month" | - status: March 2026 | - grid "March 2026": | - row "Sunday, March 1st, 2026…
Calendar — closed/light, focus/light, closed/dark, focus/dark | Detailed in the ARIA lines below (grid, day names, caption). | Requested: grid role + label, gridcell/aria-selected on td, day button aria-label with the full date (see ARIA lines).
↳ accessibility tree (shadcn-audit collect)
❌ Look root display:block, width 1232px (fills the container); nav buttons pinned to both edges
vega: root w-fit, width 248px
Calendar root has no w-fit; in a wide container the header stretches and prev/next sit far from the grid (screens/calendar-closed-*). | Requested: add w-fit to the root.
↳ bases/base/ui/calendar.tsx:47
❌ Look prev/next: h-7 w-7 (28px), border border-input, opacity-50 hover:opacity-100, hover:bg-accent, 15px Radix chevrons
vega: prev/next: Button ghost size-(--cell-size) (32px), border-transparent, opacity 1, hover:bg-muted, lucide chevron size-4
Outline + dimmed buttons vs ghost buttons at full opacity. | Requested: ghost 32px nav buttons, opacity 1, hover:bg-muted, lucide chevron size-4.
↳ bases/base/ui/calendar.tsx:57-66
❌ Look header `flex justify-center pt-1 relative items-center` + root space-y-4: weekday row at y=76
vega: month_caption h-(--cell-size) (32px) + month gap-4, nav absolute top-0: weekday row at y=84
Header is 8px shorter; title 2px higher (40 vs 42). | Requested: header h-8 (cell size), drop pt-1, nav absolute at top.
↳ bases/base/ui/calendar.tsx:53-56,67-69
❌ Look day button bg-background (light oklch(1 0 0), dark oklch(0.145 0 0)), cursor-not-allowed on disabled
vega: day button Button ghost: background transparent, cursor default
Opaque day squares show as blocks when the calendar sits on a card/popover/muted surface. Hover tokens (RubyUI hover:bg-accent vs shadcn hover:bg-muted) compute the same in the neutral theme. | Requested: transparent day buttons, hover:bg-muted hover:text-foreground, drop cursor-not-allowed.
↳ bases/base/ui/calendar.tsx:222-236
❌ Look today: button bg-accent text-accent-foreground (text oklch(0.205 0 0))
vega: today: cell bg-muted text-foreground (text oklch(0.145 0 0))
Background matches (accent = muted in neutral); text color differs slightly. Verified with the clock fixed to 2026-03-20 (screens/calendar-today-*). | Requested: today template bg-muted text-foreground.
↳ bases/base/ui/calendar.tsx:121-123
❌ Look selected cell td: [&:has([aria-selected])]:bg-accent rounded-md (oklch(0.97 0 0) under the button)
vega: day td: no background in single mode
Hidden behind the primary button; shows only at the anti-aliased corners. | Requested: drop [&:has([aria-selected])]:bg-accent/rounded-md from the day td.
↳ bases/base/ui/calendar.tsx:105-111
❌ Look focus: focus-visible:ring-2 ring-ring ring-offset-2 (2px background gap + 2px ring oklch(0.708 0 0)) on nav and day buttons
vega: vega Button: focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 (seen on the prev button)
Correction: shadcn's focused day does show the 3px ring-ring/50 ring once its transition-all settles (re-measured after 400ms); the first reading caught it mid-transition. | Requested: vega ring (focus-visible:border-ring ring-3 ring-ring/50) on nav and day buttons, keeping the ring on days.
↳ sandbox DOM (Button classes); screens/calendar-focus-*
✅ Look title 14px/500; weekdays 12.8px muted-foreground w-8; selected bg-primary text-primary-foreground radius 8px 32px; disabled muted-foreground opacity .5; outside muted-foreground
Matched by getComputedStyle, light and dark.
↳ bases/base/ui/calendar.tsx:83-96,129-132
❌ HTML div > div(header: title div, prev, next) + table > thead + tbody (rows rendered by JS from 5 <template>s + Mustache)
shadcn: div > div.rdp-months > nav[aria-label] (prev, next) + div.rdp-month > div.month_caption > span + table[role=grid] > thead[aria-hidden] + tbody
No <nav> for the month buttons; title is a div, not inside the grid's labelled structure. | Requested: wrap prev/next in <nav aria-label>; grid labelling handled on the ARIA line.
↳ sandbox DOM; bases/base/ui/calendar.tsx:31-203
❌ HTML week starts on Monday (hardcoded DAYS Monday..Sunday): 6 rows for March 2026
shadcn: week starts on Sunday (en-US locale default): 5 rows
No way to change it in RubyUI (shadcn: weekStartsOn / locale). | Requested: week_starts_on: kwarg, default :sunday (changes the current default).
↳ sandbox DOM; gem/lib/ruby_ui/calendar/calendar_weekdays.rb:5
❌ Props no showOutsideDays, captionLayout, buttonVariant, locale, formatters, components, classNames; disabled → min_date only (before a date)
shadcn: Calendar declares showOutsideDays, captionLayout (label/dropdown), buttonVariant, locale, formatters, components, classNames; disabled takes any matcher
DayPicker props passed through (mode single/multiple/range, defaultMonth, numberOfMonths, weekStartsOn, showWeekNumber, required) have no RubyUI equivalent either. RubyUI-only: input_id, date_format (Calendar), default (CalendarTitle). | Recorded only: week_starts_on lands with this work; range mode, caption dropdown, max_date go to a separate issue; formatters/components/classNames suggested as a divergence (React-only).
↳ bases/base/ui/calendar.tsx:15-27
⚠️ ARIA day: <button role=gridcell> (button role overridden) inside td role=presentation; name is the bare number ("16"); table has no role=grid nor label
shadcn: day: td role=gridcell holding a <button> named "Monday, March 16th, 2026" (", selected", "Today, " appended); table role=grid aria-label="March 2026"
Screen readers hear "16, gridcell" with no weekday/month/year and no button role. | Requested: table role=grid aria-label month/year, td role=gridcell + aria-selected, day button aria-label with the full date.
↳ accessibility tree (sandbox + preview)
⚠️ ARIA title: div role=presentation aria-live=polite; prev/next loose in the header
shadcn: caption: span role=status aria-live=polite; prev/next inside nav aria-label="Navigation bar"
Requested: role=status on CalendarTitle.
↳ accessibility tree (sandbox + preview)
⚠️ Behavior no selected date → no day is in the Tab order (docs page: 0 of 42 day buttons with tabindex ≥ 0); keyboard users can't pick a date
shadcn: one day button is tabbable (tabindex=0; selected day in the fixture)
Today and current-month templates are tabindex=-1; only the selected template has 0. | Requested: roving tabindex (selected > today > first enabled day gets tabindex=0).
↳ Playwright run on /docs/calendar and both fixtures
⚠️ Behavior Arrow keys, Home/End, PageUp/PageDown do nothing
shadcn: react-day-picker moves its focus state (td data-focused moves 12 → 13) but DOM focus stays put: CalendarDayButton creates a ref and never attaches it; PageDown changes month and drops focus to <body>
shadcn's keyboard grid is broken in the Base UI file as shipped; neither side meets APG (see Spec). | Requested: full APG grid keyboard (arrows, Home/End, PageUp/PageDown) with DOM focus following the day.
↳ bases/base/ui/calendar.tsx:216-222
⚠️ Behavior after selecting a day (click or Enter) focus falls to <body> (grid re-rendered via innerHTML)
shadcn: focus stays on the chosen day button
Requested: return focus to the chosen day after re-rendering.
↳ Playwright run on both fixtures
⚠️ Behavior clicking the selected day again keeps it selected
shadcn: clicking the selected day again clears it (mode single, not required)
Suggested divergence: keep the selected day selected on a second click (a linked input would be emptied).
↳ Playwright run on both fixtures
✅ Behavior prev/next change the month title and keep focus on the button; days before min_date are disabled and ignore clicks
↳ Playwright run on both fixtures
✅ Animation no animation (transition-colors on buttons only)
Nothing animates on month change on either side.
↳ bases/base/ui/calendar.tsx:222
❌ Native hand-rolled JS calendar (Stimulus + Mustache templates)
shadcn: react-day-picker
Candidate for <input type="date">, but native only gives a browser popup picker: it drops the inline month grid, styling, outside days and custom disabled rendering that shadcn shows. Likely a divergence rather than a swap. | Suggested divergence: no native inline month grid; keep the Stimulus calendar.
↳ https://developer.mozilla.org/pt-BR/docs/Web/HTML/Reference/Elements/input/date
⚠️ Spec no grid keyboard support (arrows, Home/End, PageUp/PageDown)
shadcn: grid keyboard focus doesn't move (ref not attached)
APG datepicker Date Grid keyboard: arrows move focus by day/week, Home/End to week start/end, Page Up/Down by month. Neither side moves DOM focus (recommendation). | Requested: implement APG grid keyboard (see Behavior).
↳ https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/#kbd_label_5
⚠️ Spec zero day buttons in the Tab sequence when no date is selected
shadcn: one day button in the Tab sequence
APG: "only one button in the calendar grid is in the Tab sequence" (tabindex=0 on the focused date). RubyUI has none without a selection (recommendation). | Requested: roving tabindex (see Behavior).
↳ https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/#rps_label_5
Audit checklist, this PR
shadcn audit ruby-ui/ruby_ui
base af07643d head 21f64446 shadcn c0d63c33
⚠️ Environment font: "Inter Variable", "system-ui", -apple-system, "system-ui", "Segoe UI", Roboto, "Helvetica Neue", Arial, "sans-serif" vs "Inter Variable", sans-serif (light)
⚠️ Environment font: "Inter Variable", "system-ui", -apple-system, "system-ui", "Segoe UI", Roboto, "Helvetica Neue", Arial, "sans-serif" vs "Inter Variable", sans-serif (dark)
✅ Theme neutral tokens match shadcn
Calendar (ref: bases/base/ui/calendar.tsx + style-vega.css @ c0d63c33)
⏸ Look properties: font-family
Calendar — explained by environment diff: font
✅ ARIA Calendar: accessibility tree matches
↳ accessibility tree (shadcn-audit collect)
✅ Look root w-fit bg-background p-3 (248px); header h-8 mb-4; ghost 32px prev/next; transparent day buttons, hover:bg-muted; today cell bg-muted text-foreground; rounded-md cells; leading-none days; vega focus ring (border-ring ring-3 ring-ring/50)
Re-measured with getComputedStyle on every part (root, title, prev/next, weekday, default/outside/disabled/selected/today day and cell, prev hover), light and dark: no differences. Focus ring measured after the transition settles.
↳ bases/base/ui/calendar.tsx:34-123,222-236
✅ HTML div > div(header: nav[aria-label] (prev, next) + title div) + table[role=grid] > thead[aria-hidden] + tbody, rows rendered from <template>s — intentional
Server-rendered Phlex parts plus client-side templates; the landmarks, grid, cells and labels match react-day-picker, only the wrapper divs differ.
↳ audit/divergences.yml
✅ HTML week starts on Sunday by default (week_starts_on: :sunday..:saturday or 0-6)
Fixture renders the same 5 rows.
↳ sandbox DOM
❌ Props no showOutsideDays, captionLayout, buttonVariant, locale; disabled → min_date only (before a date)
shadcn: Calendar declares showOutsideDays, captionLayout (label/dropdown), buttonVariant, locale, formatters, components, classNames; disabled takes any matcher
formatters, components, classNames: registered divergence (React-only). Still missing: showOutsideDays, captionLayout, buttonVariant, locale, and DayPicker's mode/defaultMonth/numberOfMonths/required; disabled → min_date only. Follow-up issue. RubyUI-only: input_id, date_format, week_starts_on (Calendar), default (CalendarTitle).
↳ bases/base/ui/calendar.tsx:15-27
✅ ARIA table role=grid aria-label="March 2026"; td role=gridcell (+ aria-selected); day button named "Monday, March 16th, 2026" ("Today, " / ", selected"); title role=status aria-live=polite; prev/next in nav aria-label="Navigation bar", labels "Go to the Previous/Next Month"
collect: accessibility tree matches in every state.
↳ accessibility tree (shadcn-audit collect)
✅ Behavior one day button is always in the Tab order (selected > today > first enabled day); docs page without a selection: 1 tabbable day
↳ Playwright run on /docs/calendar and both fixtures
✅ Behavior Arrow keys by day/week (skipping disabled days), Home/End to week start/end, PageUp/PageDown by month (Shift: year), DOM focus follows across months — follows spec
Diverges from shadcn, follows the spec: APG datepicker Date Grid keyboard.
↳ https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/#kbd_label_5
✅ Behavior after selecting a day (click or Enter) focus stays on the chosen day
↳ Playwright run on both fixtures
✅ Behavior clicking the selected day again keeps it selected — intentional
The calendar fills a linked input (input_id); clearing on a second click would empty it by accident.
↳ audit/divergences.yml
✅ Behavior prev/next change the month title and keep focus on the button; days before min_date are disabled and ignore clicks
↳ Playwright run on both fixtures
✅ Animation no animation (transition-all on buttons, as Button)
↳ bases/base/ui/calendar.tsx:222
✅ Native hand-rolled JS calendar (Stimulus + Mustache templates) — intentional
<input type="date"> only offers a browser popup picker; there is no native inline month grid, styling or custom disabled days.
↳ audit/divergences.yml
✅ Spec grid keyboard per APG (arrows, Home/End, PageUp/PageDown) with DOM focus moving — follows spec
Diverges from shadcn, follows the spec.
↳ https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/#kbd_label_5
✅ Spec exactly one day button in the Tab sequence, with or without a selection
APG: only one button in the calendar grid is in the Tab sequence.
↳ https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/#rps_label_5
How to test
cd gem && bundle exec rake(tests and standardrb).- In the docs app, open
/docs/calendar: Tab past the next-month button lands on a day; try the arrows, Home/End and PageUp/PageDown; Enter selects and fills the input. - The "Week start" example starts on Monday; the others start on Sunday.
/docs/date_picker: open the popover, pick a day, and check the input value.- Optional:
/shadcn-audit calendaragainst this branch.
🤖 Generated with Claude Code
Summary by cubic
Restyles Calendar to match shadcn's Base UI + vega and adds the APG date grid keyboard support, so the component now passes the shadcn audit.
- Weeks start on Sunday by default; apps that want Monday need
week_starts_on: :monday. - Day buttons are now accessible (full-date names,
grid/gridcellroles), and one day is always in the Tab order, with a fallback to themin_datemonth when today falls before it. - Arrows, Home/End, and PageUp/PageDown move focus per the APG grid pattern; focus stays on the chosen day after selecting.
- Clicking the selected day again refocuses it instead of clearing it.
- Calendar is added to the shadcn audit map and fixtures; four intentional divergences are registered.