Skip to content

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 ​

HookOnRole
data-av-calendarThe wrapperMarks the calendar. One per page
data-av-calendar-eventsA <script type="application/json">The event array
data-av-calendar-gridAn empty <table role="grid">Receives the generated month
data-av-calendar-titleAny elementWritten with the month and year
data-av-calendar-prev / -nextButtonsStep by what the view shows: a month, a week, a day or a year
data-av-calendar-viewButtonsSwitch to month, week, day or year; carries aria-pressed
data-av-calendar-boardAn empty <div hidden>Receives the week, day and year views
data-av-calendar-dateThe wrapperYYYY-MM-DD, the date the calendar opens on. Defaults to today
data-av-calendar-todayA buttonReturn to today and select it
data-av-calendar-filterButtonsFilter by calendar; carries aria-pressed
data-av-agendaA <ul>Receives the selected day's events
data-av-agenda-titleAny elementWritten 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:

KeyRequiredMeaning
dateyesYYYY-MM-DD, compared as the local calendar day rather than a UTC instant
titleyesShown in the agenda
timenoHH: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
endnoHH:MM. Without it a timed event is drawn an hour long
wherenoFree text
rolenoprimary | success | warning | danger | info — the dot and bar colour. Defaults to primary
calendarnoThe 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"> with role="row", role="columnheader" and role="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 tabindex keeps 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-selected sits on the gridcell, not on the button inside it. A button is not a selectable element, so the attribute is not allowed there — moving it removes one aria-allowed-attr violation 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 builtConsequence
List and timeline viewsMonth, week, day and year only
Resource / scheduler rowsNo per-person or per-room lanes
Drag-and-drop and resizeEvents are read-only; editing is your own form
Recurrence (RRULE)Expand recurring events server-side into dated entries
Timezone conversiondate is a local calendar day; convert before rendering
Overlap layoutA 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:00An event that starts outside them is listed with the all-day events
More than one calendar per pageThe 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:

  1. Vendor it as Asset Vendoring describes — manifest entry, npm run vendor, commit the checksum.
  2. Add a key to the loader's VENDORS in src/js/adminvora.js. check:integrations holds the documentation to that registry, so the key and its documented row have to arrive together.
  3. 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.
  4. 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 from src/vendor/ rather than hand-picked, and npm run lint prints 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 date is 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.

Documentation for @creativeigniter/adminvora