Appearance
Calendar & Scheduling
Four views of the same events, in this repository's own code: a month grid on role="grid", a week and a day on a time grid, and a year of twelve small months. No calendar library is vendored, and the module is part of the runtime, so it works with the bundle alone.
What a scheduling library adds beyond that (timeline views, resource rows, drag-and-drop, recurrence and timezone arithmetic) is real work this does not do, and What it does not do says so plainly.
Markup
One [data-av-calendar] per page. The month is generated into the empty <table> and the other views into [data-av-calendar-board]; everything else is yours. Leave the board and the view buttons out and you have a month calendar.
html
<div class="av-calendar" data-av-calendar>
<script type="application/json" data-av-calendar-events>
[
{ "date": "2026-08-13", "title": "Design review", "time": "10:00",
"where": "Room 2", "role": "info", "calendar": "work" },
{ "date": "2026-08-14", "title": "Q3 board pack due", "time": "09:00",
"role": "danger", "calendar": "work" }
]
</script>
<div class="av-calendar__toolbar">
<h1 class="av-calendar__title" data-av-calendar-title>—</h1>
<div class="av-calendar__nav">
<button class="av-btn av-btn--ghost av-btn--icon av-btn--sm" type="button"
data-av-calendar-prev aria-label="Previous month">…</button>
<button class="av-btn av-btn--ghost av-btn--icon av-btn--sm" type="button"
data-av-calendar-next aria-label="Next month">…</button>
</div>
<button class="av-btn av-btn--outline av-btn--sm" type="button"
data-av-calendar-today>Today</button>
</div>
<table class="av-calendar__grid" role="grid" data-av-calendar-grid>
<caption class="av-visually-hidden">
Month view. Use the arrow keys to move between days.
</caption>
</table>
</div>The title and the day names are written by the module through Intl.DateTimeFormat, so they follow the visitor's locale without a translation file. The — is a placeholder the module overwrites on first render.
Hooks
| Hook | On | Role |
|---|---|---|
data-av-calendar | The wrapper | Marks the calendar. One per page |
data-av-calendar-events | A <script type="application/json"> | The event array |
data-av-calendar-grid | An empty <table role="grid"> | Receives the generated month |
data-av-calendar-title | Any element | Written with the month and year |
data-av-calendar-prev / -next | Buttons | Step by what the view shows: a month, a week, a day or a year |
data-av-calendar-view | Buttons | Switch to month, week, day or year; carries aria-pressed |
data-av-calendar-board | An empty <div hidden> | Receives the week, day and year views |
data-av-calendar-date | The wrapper | YYYY-MM-DD, the date the calendar opens on. Defaults to today |
data-av-calendar-today | A button | Return to today and select it |
data-av-calendar-filter | Buttons | Filter by calendar; carries aria-pressed |
data-av-agenda | A <ul> | Receives the selected day's events |
data-av-agenda-title | Any element | Written with the selected date |
The two agenda hooks are looked up on document rather than inside the calendar, so the grid and the agenda can sit in separate panes of a split view.
Events
The array is read once, from the page. Each entry:
| Key | Required | Meaning |
|---|---|---|
date | yes | YYYY-MM-DD, compared as the local calendar day rather than a UTC instant |
title | yes | Shown in the agenda |
time | no | HH:MM places the event on the time grid. Any other text, or none, makes it an all-day event. Shown in the agenda either way |
end | no | HH:MM. Without it a timed event is drawn an hour long |
where | no | Free text |
role | no | primary | success | warning | danger | info — the dot and bar colour. Defaults to primary |
calendar | no | The value data-av-calendar-filter matches on |
The events live in the markup, not in a fetch. The server renders the month it is already rendering the page for, so the calendar is readable before any JavaScript runs. Malformed JSON is caught and treated as an empty list — the month still renders, so a bad feed degrades to an empty calendar rather than a blank page.
Keyboard and semantics
This is the part worth reading, because keyboard behaviour is what a calendar library is usually bought for.
- The month is a real
<table role="grid">withrole="row",role="columnheader"androle="gridcell". ARIA state needs a real role to attach to; a<div>mesh looks identical and announces nothing. - One tab stop for the whole grid. A roving
tabindexkeeps it on the selected day, so tabbing through the page does not walk forty-two cells. - Arrow keys move a day or a week; Home and End go to the ends of the week; Page Up and Page Down change month. Moving past the edge of the month turns the page and keeps focus on the day you moved to.
- Today carries
aria-current="date". It was marked in paint alone until that was added, which is a difference nobody sees by looking. aria-selectedsits on thegridcell, not on the button inside it. A button is not a selectable element, so the attribute is not allowed there — moving it removes onearia-allowed-attrviolation per rendering.- Each day's accessible name carries its event count, so arrowing through the grid announces "14 August, 3 events" rather than "14".
- Selecting a day announces it in a live region — the date and the number of events, worded as a sentence, with "no events" rather than "0 events". Moving focus is not the same as telling somebody what changed: the agenda pane beside the grid updates silently otherwise.
What it does not do
Stated as limits rather than discovered as bugs:
| Not built | Consequence |
|---|---|
| List and timeline views | Month, week, day and year only |
| Resource / scheduler rows | No per-person or per-room lanes |
| Drag-and-drop and resize | Events are read-only; editing is your own form |
Recurrence (RRULE) | Expand recurring events server-side into dated entries |
| Timezone conversion | date is a local calendar day; convert before rendering |
| Overlap layout | A month cell shows dots and a count. On the time grid two events at the same time are drawn on top of each other |
| Hours outside 07:00 to 21:00 | An event that starts outside them is listed with the all-day events |
| More than one calendar per page | The agenda and the filters are looked up in the document, so two calendars would share them |
The calendar is scanned by AdminVora.init(root) like every other module, so a router that inserts one after boot calls AdminVora.init() and it starts.
Adding a scheduling library
No scheduling library is vendored. If you need the views in the table above, adding one is an ordinary integration:
- Vendor it as Asset Vendoring describes — manifest entry,
npm run vendor, commit the checksum. - Add a key to the loader's
VENDORSinsrc/js/adminvora.js.check:integrationsholds the documentation to that registry, so the key and its documented row have to arrive together. - Mount it against a hook of your own. Do not reuse
data-av-calendar: two readers for one attribute is a defect this codebase has shipped more than once. - Theme it from a
plugins/partial, re-pointing the vendor's own selectors at tokens rather than overriding them. The specificity ceiling that partial is held to is derived fromsrc/vendor/rather than hand-picked, andnpm run lintprints it.
Keep a server-rendered month as the fallback if you do. That is the property the built-in grid exists to protect, and it is the easiest thing to lose on the way to a richer view.
Checklist
- [ ]
<caption>on the grid saying the arrow keys work - [ ] Every
dateis the local calendar day, converted server-side if your store is UTC - [ ] Recurring events expanded before rendering
- [ ] The agenda's empty state written, and worded as a sentence
- [ ] Filter buttons carry
aria-pressed - [ ] Walked with the keyboard alone: tab reaches the grid once, arrows move, the month turns at the edge
Read next: Editors.