Year calendar
A grid of years for choosing one, a decade at a time. It renders no input or popover of its own: show it inline, or in a popover, and listen for the year the user commits.
Usage
<%= render(Impulse::YearCalendarComponent.new(value: 2026)) %>The calendar shows the decade of its value, 2020 to 2029, with the year before and after it, and previous and next decade buttons. Clicking a year, or pressing Enter or Space on it, commits it: the year becomes the value and the calendar emits awc-year-calendar:commit. Committing the year already selected emits nothing.
Arguments
Keyword arguments
| Name | Default | Description |
|---|---|---|
| value | nil | The selected year: an Integer (2026), a string ("2026"), or a Date, Time or ActiveSupport::TimeWithZone, read as its year in the time zone. |
| min | nil | The earliest year the user can commit, given as value is. |
| max | nil | The latest year the user can commit, given as value is. |
| time_zone | see below | The time zone that decides which year today falls in, and which year a time falls in. |
| disabled | false | Whether the calendar is disabled: nothing in it can be focused or pressed. It still shows its value. |
Any other keyword arguments, such as class or data, are passed to the <awc-year-calendar> element as HTML attributes. Render the calendar with the component: the element relies on the decade and the settings it renders.
The time zone is time_zone: when given, else the zone of an ActiveSupport::TimeWithZone value, else Time.zone.
Examples
Limiting the years
Years before min or after max can be reached by keyboard but not committed. The calendar doesn't page past the decades holding min and max.
<%= render(Impulse::YearCalendarComponent.new(value: @year, min: 2000, max: Date.current)) %>In a popover
Focus the selected year when the popover opens, close the popover when the user commits a year, and take the calendar back to the selected year's decade when the popover closes.
<%= render(Impulse::PopoverComponent.new(title: "Choose a year", data: { action: "awc-year-calendar:commit->awc-popover#requestHide" })) do |c| %>
<% c.with_trigger(class: "btn btn-outline-secondary") { @year.to_s } %>
<% c.with_header(visually_hide_title: true, hide_close_button: true) %>
<% c.with_body do %>
<%= render(Impulse::YearCalendarComponent.new(value: @year)) %>
<% end %>
<% end %>const calendar = popover.querySelector('awc-year-calendar');
popover.addEventListener('awc-popover:shown', () => calendar.focus());
popover.addEventListener('awc-popover:hidden', () => calendar.resetView());Translations
The calendar names its decade and its buttons with these keys, under impulse.calendar.*, which the calendars share:
en:
impulse:
calendar:
previous_decade: Previous decade
next_decade: Next decade
formats:
decade: "%{start} – %{end}" # Names the displayed decade, above the grid.Accessibility
The calendar follows the grid of the APG date picker dialog example, as the date calendar does. The grid is one tab stop, named by its decade, and each year is a button named by its text. Turning the page announces the new decade.
| Key | Moves to |
|---|---|
| Left Arrow, Right Arrow | The year before or after |
| Up Arrow, Down Arrow | The year three before or after |
| Home, End | The start or end of the row |
| Page Up, Page Down, with or without Shift | The same year of the decade before or after |
| Enter, Space | Commits the year |
Moving past the edge of the decade, or onto the year before or after it, turns the page. The calendar is as wide as the date calendar.
Imports
import '@ambiki/impulse-view-components/year-calendar';@import '@ambiki/impulse-view-components/year-calendar';The styles need Bootstrap's Sass and the base styles loaded first. See Import the styles.