feat(calendar): month grid and date picker on plain Elixir Date

[mplatts]

Closes #610

Summary

Two components, shipped together as the issue asks: <.calendar>, a server-rendered month grid on Elixir's own Date, and <.date_picker>, that grid in a panel under a text input.

No new dependencies. Month maths is Date.beginning_of_month/1, Date.end_of_month/1, Date.add/2 and Date.day_of_week/1 plus modular arithmetic for the week rotation. Display formatting is Calendar.strftime/2. Nothing converts a timezone, because a %Date{} does not have one.

<.calendar>

• single, range (including the half-open {from, nil} mid-selection state) and multiple
• min/max inclusive windows, disabled_dates as a list or a 1-arity function. Disabled days render and stay focusable per the APG, they just lose their click wiring
• starts_on for all seven ISO week starts, show_outside_days, fixed_weeks, and a today marker (a dot under the number) that still reads when the day is also selected
• two wirings: on_select/on_month_change push phx-click with ISO phx-value-date/phx-value-month; with them nil the nav renders <.link patch> on month_param, which is a plain query-string anchor in a dead view
• the range band lives on the <td> so it runs edge to edge between days; the day button keeps its own rounding

<.date_picker>

• display input is strftime and unnamed, so it never posts; a hidden input carries ISO 8601 whatever format says. Range posts name[from] / name[to]
• parse on blur or Enter: ISO first, then a lenient parse of the configured format (padding-insensitive, case-insensitive, accepts %B/%b month names and discards %A/%a), and reverts to the last valid value on failure rather than silently clearing
• two_months, clearable, disabled, and the <.field> surface for label, errors, help text and the required marker, including Phoenix.HTML.FormField integration

Scope

Everything in the issue's "Variants & states to build", the playground spec and the test checklist is in this PR. Deliberately not in it, per the issue's own Non-goals:

• time selection, natural-language parsing, a presets rail, cldr
• the birthday year-select header. The issue says to note it rather than half-ship it, so: the birthday scenario is on the playground page and it works, but it gets there via parse-on-blur (type 12 Jun 1987, the grid follows) plus Shift+PageUp/PageDown for year jumps, not a decade dropdown. A year/month select header is a good follow-up and wants its own API decision (a caption slot, probably, so callers can put anything in the header).

One more follow-up worth naming: in two_months mode both arrows sit on the left pane and the right pane gets none, so paging always moves the pair by one month. Splitting them (prev on the left header, next on the right) needs the right pane's arrow to target base+1 rather than its own next month, which is a second nav-target attr I did not think earned its place yet.

Deviations from the issue's API sketch

All additive; nothing in the sketch was dropped or renamed.

• today attr on both. Defaults to Date.utc_today/0. The issue is right that a Date has no timezone, which is exactly why the component must not pick one for you: a user in Melbourne gets "today" wrong for ten hours a day if UTC is hardcoded. Passing a date is the honest fix, and it makes every test deterministic.
• day_names_long attr. day_names is 7 short labels, which is what a column header shows. The screen-reader name for the column needs the full word, and deriving "Monday" from "Mo" is not possible once the attr is localised. English defaults, same as the others.
• name attr on <.calendar>. The sketch says days "render as submit-capable buttons inside whatever form wraps the calendar" but a submit button needs a name to post anything. With name set (and no on_select) days render type="submit" name=... value={iso}, so the no-JS story is real rather than notional. on_select wins when both are set, and a disabled day never carries the name.
• nav attr on <.calendar> (both / prev / next / none). Two side-by-side panes rendering two independent sets of arrows was confusing in the playground. A suppressed arrow leaves a spacer so the caption stays optically centred.
• target, on_clear, range_separator, prev_label/next_label/open_label/clear_label, panel_class, month/on_month_change on the picker. target is for LiveComponents; the labels exist because otherwise the only localisable strings in the component would be hardcoded English; range_separator has to be an attr because the hook parses the display value back apart with it.
• <.date_picker> does not literally wrap <.popover>. The popover's :trigger slot renders inside a <button>, and a date picker's trigger is an <input> plus a toggle button. It reuses the popover's mechanics instead (JS.show/JS.hide with the same transitions, phx-click-away, phx-keydown Escape plus JS.focus back to the input) and its own pc-date-picker__panel surface.

Hook decisions

Two hooks, both justified by the bar the issue sets.

PetalCalendar does roving tabindex and the arrow map. CSS cannot move focus and a server round trip per arrow key is not navigation, it is latency. Keyboard map: arrows by day and week, Home/End to the week bounds (respecting starts_on), PageUp/PageDown by month, Shift+PageUp/PageDown by year, Enter/Space to select (swallowed on a disabled day). Arrowing or paging out of the displayed month clicks the nav element and restores focus in updated(), so it works identically in event mode and link mode.

One thing worth flagging in review: clicking the arrow as rendered only ever moves one month, so a year jump landed eleven months short. I caught this driving the real playground, not in a unit test. The hook now retargets the arrow (phx-value-month in event mode, the month param in the href in link mode) before clicking it, which keeps phx-target and the patch URL as LiveView's own rather than forging an event. There are three JS specs pinning that.

PetalDatePicker does open-focus (move into the grid on open, back to the input on Escape), parse-on-blur, and client-side selection when no on_select is wired so the picker works in a dead view. When the server owns selection the hook stays out of the value entirely.

Both degrade: every day is a real <button>, so Tab plus Enter works with the hooks deleted. Only roving focus and the arrow map are lost.

Verification

check	result
mix format --check-formatted	pass
mix compile --force --warnings-as-errors	pass
mix credo	45 issues, same 45 as origin/main. Zero new
mix test	913 → 972, 0 failures, 1 skipped (+59)
npm test	157 → 195 (+38)

Date edge cases have real tests: December to January in both directions, February 2024 vs 2026, fixed_weeks always six rows, the first and last week of the grid carrying the adjacent months, min/max inclusivity at both boundaries, all seven starts_on values, a backwards range pair getting ordered, and clamping 31 January to 28 February on a month page.

Verified by hand in the playground, keyboard only: ArrowRight then ArrowDown moved 12 Aug to 20 Aug, Home snapped to 17 Aug and End to 23 Aug, PageDown moved to September 2026 keeping the 23rd focused, and Shift+PageUp landed on September 2025 with focus intact. Light and dark both checked, and the two-month range panel was opened and screenshotted.

[codecov]

Codecov Report

❌ Patch coverage is 94.50867% with 19 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.53%. Comparing base (871b2cf) to head (3bf70e5).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/petal_components/calendar.ex	94.44%	10 Missing ⚠️
lib/petal_components/date_picker.ex	93.61%	9 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #642      +/-   ##
==========================================
+ Coverage   92.40%   92.53%   +0.13%     
==========================================
  Files         119      123       +4     
  Lines        5066     5412     +346     
==========================================
+ Hits         4681     5008     +327     
- Misses        385      404      +19     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[mplatts]

Screenshots

Date picker open — two-month range panel, 12-16 Aug selected

Keyboard — focus ring on Sept 2025 after a Shift+PageUp year jump

Calendar, light / dark

Date picker, light / dark

Verified independently

Check	Result
mix test	972 tests, 0 failures, 1 skipped (+59)
npm test	195 passing (+38)
mix format / compile -Werror	clean
mix credo	zero new entries vs main
new dependencies	none — stdlib Date/Calendar only
slugs : clauses	62 : 62, two components, two pages

The largest issue in the set and it came in clean. Both components carry moduledocs, both are registered, and the 1:1 playground mapping holds at 62.

The bug worth reading

Clicking the nav arrow as rendered only ever moves one month, so year jumps landed eleven months short. The hook now retargets the arrow (phx-value-month, or the month param in the href) before clicking, keeping phx-target and the patch URL as LiveView's own. Three JS specs pin it.

The author's own note: "I'd have shipped that broken on unit tests alone." That's the second time this run that driving the real browser caught something no unit test could — the other was File Upload's :accept string-vs-list. Both argue for the CONTRIBUTING rule that the playground page is part of the deliverable.

Deferred deliberately, not silently

• The birthday year-select header. The issue says note it rather than half-ship it, and that's what happened — the birthday scenario works via parse-on-blur and Shift+PageUp/Down instead of a decade dropdown. A caption slot is the suggested follow-up API.
• Split arrows in two_months. Both arrows sit on the left pane and paging moves the pair by one month; splitting them needs a second nav-target attr the author judged hadn't earned its place. Your call.

The deviations are all additive and each has a concrete reason — today for timezone honesty (UTC is wrong for 10 hours a day in Melbourne), day_names_long because you can't derive "Monday" from a localised "Lu", name because a submit button needs one to post anything.

Worth noting the picker does not literally wrap <.popover>: popover's :trigger renders inside a <button> and a picker's trigger is an <input>, so it reuses the mechanics rather than the component. Reasonable, and stated rather than glossed.

_{Images live on the pr-assets branch, which exists only to host PR screenshots - it never merges to main and ships in no Hex release.}