One month of days as a grid, standing on the page rather than folded into a panel.
@pacit/components/datepct-calendarImplements the grid of the W3C ARIA APG Date Picker Dialog pattern ↗
| Sunday | Monday | Tuesday | Wednesday | Thursday | Friday | Saturday |
|---|---|---|---|---|---|---|
| 27 | 28 | 29 | 30 | 1 | 2 | 3 |
| 4 | 5 | 6 | 7 | 8 | 9 | 10 |
| 11 | 12 | 13 | 14 | 15 | 16 | 17 |
| 18 | 19 | 20 | 21 | 22 | 23 | 24 |
| 25 | 26 | 27 | 28 | 29 | 30 | 31 |
| 1 | 2 | 3 | 4 | 5 | 6 | 7 |
import { Component, signal } from '@angular/core';
import { PctCalendar, PctDay } from '@pacit/components/date';
/** The month grid on its own — a roving grid the arrow keys walk. */
@Component({
selector: 'demo-calendar',
imports: [PctCalendar],
styles: ':host { display: block; max-inline-size: 24rem; }',
template: ` <pct-calendar [(value)]="day" ariaLabel="Pick a day" /> `,
})
export class CalendarDemo {
readonly day = signal<PctDay | null>(null);
}calendar.demo.ts — the same file runs here and is highlighted under Code
One import per component, and the shortest possible use — the package itself is installed once, on the start page.
import { PctCalendar } from '@pacit/components/date';| Exported | What it is |
|---|---|
PctCalendarCellinterface | One cell of the grid, with everything the template and the reader need already decided. |
PctDayPredicatetype(day: PctDay) => boolean | A day the consumer refuses — weekends, holidays, a taken slot. |
PctCalendarcomponentpct-calendar | Calendar — one month of days as a role="grid", walked by a roving tabindex. |
PctDatePanelAligntype'start' | 'end' | Which edge of the field the panel lines its own up with. |
PctDatecomponentpct-date | Date field — a text control the library formats and parses per locale, with a calendar in a panel beside it. |
PctDayBoundtypeunreleasedPctDay | undefined | LogicFn<TValue, PctDay | undefined, TPathKind> | A bound pctDayBounds takes: a day, or a function of the field's context that returns one — the two shapes Angular's own min() takes. One that is not a day, undefined among them, is no bound, as it is on the field's input. |
PctDayBoundErrortypeunreleased| { readonly kind: 'minDay' | What pctDayBounds reports: minDay for a day before min, maxDay for one after max. Each carries the bound it broke, as the bound was written. |
PctDayBoundsConfiginterfaceunreleased | The bounds of pctDayBounds, and the sentence its errors carry — one for both, or one written from the error, which holds the bound. |
pctDayBoundsfunctionunreleased | Bounds a date field in a signal form: what Angular's minDate() and maxDate() do for a Date, for a PctDay — which they cannot take (their path is a Date's, and their validator reads the value with getTime()), and which the compiler refuses as an attribute beside [formField] (NG8022). The bounds reach the field's min / max, so the calendar's walk stops at them, and the form grades the value: a day outside is minDay or maxDay. |
PctDaytypestring | A calendar day, written the way the platform already writes one: YYYY-MM-DD. |
PctDayPartsinterface | The three fields of a day, as numbers. month is 1–12, the way a person says it. |
pctDaysInMonthfunction | How many days February has — the Gregorian rule, written once. |
isPctDayfunction | Whether a string is a day this library will work with: the right shape and a day the calendar has. 2026-02-30 has the shape and is not a day, and the difference matters — a value read from a server, a query string or a localStorage entry is a string somebody else wrote. |
pctDayfunction | Builds a day from its three fields, normalising an overflow the way a person expects — month 13 is January of the next year, day 0 is the last day of the previous month. That is what makes pctAddMonths and pctAddDays one line each instead of three branches. |
pctDayAsUtcfunction | The day as the one Date anything outside this file is allowed to see: midnight UTC, which is what Intl.DateTimeFormat with timeZone: 'UTC' reads back as the same three fields it was built from. Handing out a local-time Date is the defect this whole module exists to refuse. |
pctDayPartsfunction | The three fields of a day. The caller has already established that it is one. |
pctTodayfunction | Today, read from the LOCAL clock — the one read of local time in this file, and the only one that belongs: "what day is it" is a question about where the user is standing, and every other question here is arithmetic on a day that already has an answer. |
pctAddDaysfunction | n days on (or back). |
pctAddMonthsfunction | n months on (or back), clamped to the length of the month it lands in: 31 January plus one month is 28 February and not 3 March. The clamp is what a calendar's "next month" button means — a walk that changed the day of the month would move the cursor twice. |
pctCompareDaysfunction | -1, 0 or 1 — read from the three fields, though the shape invites a string compare and carried one for months. |
pctWeekdayfunction | The ISO weekday: Monday is 1, Sunday is 7 — the numbering Intl.Locale.prototype.getWeekInfo() answers in, so the two never need converting between them. |
pctClampDayfunction | Held inside the bounds, either of which may be absent — and undefined is what absent is, because that is how the FormUiControl contract's min / max spell an absent bound. |
pctMonthGridfunction | The grid of one month: whole weeks, starting on firstDayOfWeek, with the days of the neighbouring months that share those weeks. Six weeks always, and that is a decision rather than an oversight — a month spans four to six weeks depending on where it starts, and a panel that changed height between March and August would move the page under the pointer mid-walk. |
PctDayFieldtype'day' | 'month' | 'year' | Which of the three fields a position in the format holds. |
PctDayLettersinterface | The letters a format hint is written with — one per field, from PCT_TEXTS. |
pctFirstDayOfWeekfunction | Which day the week starts on, 1 (Monday) … 7 (Sunday). |
PctDayFormatinterface | Everything about writing and reading a day in one language, built once per locale. |
pctDayFormatfunction | The day, weekday and month names of a locale, built once and shared. |
PctWeekdayNameinterface | The two names a column header needs: the one the eye reads and the one a reader says. |
pctWeekdayNamesfunction | The seven column headings, rotated so that the first is firstDayOfWeek. |
pctMonthCaptionfunction | The month and year over the grid ("December 2026"), in the value's own calendar. |
<pct-calendar [(value)]="day" ariaLabel="Pick a day" />Each example is the component itself, not a screenshot. Open the code under any of them.
locale names the month and the weekdays through the platform's own Intl; firstDayOfWeek starts the row where that culture starts it — Monday is 1.
| poniedziałek | wtorek | środa | czwartek | piątek | sobota | niedziela |
|---|---|---|---|---|---|---|
| 28 | 29 | 30 | 1 | 2 | 3 | 4 |
| 5 | 6 | 7 | 8 | 9 | 10 | 11 |
| 12 | 13 | 14 | 15 | 16 | 17 | 18 |
| 19 | 20 | 21 | 22 | 23 | 24 | 25 |
| 26 | 27 | 28 | 29 | 30 | 31 | 1 |
| 2 | 3 | 4 | 5 | 6 | 7 | 8 |
Read from the source at build time — the types, the defaults and the lines of documentation are the library's own.
unreleased marks 5 of them: on main, and not in @pacit/components@0.2.0 — the next release names the version.
Calendar — one month of days as a role="grid", walked by a roving tabindex.
| Name | Type | What it does |
|---|---|---|
valuetwo-waydefault null | PctDay | null | The chosen day, or null. |
mindefault undefined | unknown | The earliest and latest day the walk may reach; absent means no bound on that side. |
maxdefault undefined | unknown | The latest day the walk may reach; absent means no bound on that side — the other half of min. |
dateDisableddefault null | PctDayPredicate | null | Days inside the bounds that still cannot be picked. The split is deliberate: min/max are the range and this is the holes in it — the bounds clamp where the keyboard can go, a refused day is reached, announced and simply not takeable. |
startAtunreleaseddefault undefined | unknown | The day the grid opens on while there is no value — absent, today. It is where the walk STARTS and nothing more: no day is marked chosen by it, and the bounds still hold it. The datetime field hands it the month a half that is not a date names, so 31.02.2026 opens on February (0090 §2). |
disableddefault false | boolean | Freezes the grid: no day can be picked, the walk and the month buttons stop, and aria-disabled says so. |
localedefault '' | string | Overrides the application's LOCALE_ID, as on [pctNumber] and <pct-slider>. |
firstDayOfWeekdefault 0 | number | Which day the week starts on, 1 (Monday) … 7 (Sunday). Absent, the locale decides — through the platform where it answers and through a table of regions where it does not (locale.ts — firefox 151 is one engine that does not, and Angular still supports it). |
sizedefault config.defaultSize | PctSize | Scales the grid with the field sizes, so a panel matches the field it opens from; from providePctConfig by default (req-api-config). |
ariaLabeldefault '' | string | The accessible name of the grid; the panel that owns one passes its own. |
ariaLabelledbydefault '' | string | As ariaLabel, for a name that already stands somewhere on the page. |
| Name | Payload | When it fires |
|---|---|---|
dayPicked | PctDay | A day was chosen by the user — which is not the same event as value changing, and the difference is what closes a panel: a value written from outside must not. |
The hooks a stylesheet or a test can hold. Stable by contract — the parts inventory gate fails the build when one disappears.
| Attribute | Bound to | Note |
|---|---|---|
class | pct-calendar | |
data-pct-size | size() | |
data-pct-disabled | disabled() ? "" : null |
Two ways in, both stable. No class names to depend on.
In a test, PctCalendarHarness from @pacit/components/testing reads a part by the name below and a state by its attribute — the harness gate holds the names to the package.
| Part | Selector | What it is |
|---|---|---|
caption | [data-pct-part="caption"] | the month and the year over the grid |
day | [data-pct-part="day"] | one day cell |
grid | [data-pct-part="grid"] | the grid of days |
nav | [data-pct-part="nav"] | the previous-month and next-month buttons |
week | [data-pct-part="week"] | one row of the grid |
weekday | [data-pct-part="weekday"] | a heading over a column of days |
control | [data-pct-part="control"] | the typed input |
error | [data-pct-part="error"] | the message when the value is invalid |
hint | [data-pct-part="hint"] | the hint under the input |
label | [data-pct-part="label"] | the label of the typed input |
panel | [data-pct-part="panel"] | the calendar, floating or inline |
toggle | [data-pct-part="toggle"] | the button that opens the calendar |
warning | [data-pct-part="warning"] | the message when the value is allowed and suspect — after the error, before the hint (0087) |
Every value the component reads, with the light and the dark default. Override a token at any scope and it cascades like any custom property.
| Token | Styles |
|---|---|
--pct-date-bg{pct.surface}#ffffff · #0f172a | Background of the date field. |
--pct-date-bg-disabled{pct.surface-disabled}#f1f5f9 · #1e293b | Background of the date field while disabled. |
--pct-date-border{pct.border-strong}#64748b | Edge colour of the date field. |
--pct-date-border-disabled{pct.border}#e2e8f0 · #334155 | Edge colour of the date field while disabled. |
--pct-date-border-focus{pct.primary}#2563eb · #60a5fa | Edge colour of the date field when focused. |
--pct-date-border-hover{pct.text-muted}#334155 · #e2e8f0 | Edge colour of the date field on hover. |
--pct-date-border-invalid{pct.danger}#b91c1c · #f87171 | Edge colour of the date field when invalid. |
--pct-date-border-warning{pct.warning}#b45309 · #fbbf24 | Edge colour of the date field under a warning (0087). |
--pct-date-caption-font-size{pct.font.size.md}14px | Font size of the month caption. |
--pct-date-caption-font-weight{pct.font.weight.medium}500 | Font weight of the month caption. |
--pct-date-day-bg-hover{pct.surface-100}#f1f5f9 · #1e293b | Background of a day cell on hover. |
--pct-date-day-bg-selected{pct.primary}#2563eb · #60a5fa | Background of a day cell when selected. |
--pct-date-day-border-today{pct.primary}#2563eb · #60a5fa | Edge colour of a day cell for today. |
--pct-date-day-fg-disabled{pct.text-disabled}#64748b | Text colour of a day cell while disabled. |
--pct-date-day-fg-muted{pct.text-muted}#334155 · #e2e8f0 | Text colour of a day outside the month shown. |
--pct-date-day-fg-selected{pct.on-primary}#ffffff · #0f172a | Text colour of a day cell when selected. |
--pct-date-day-font-size{pct.font.size.md}14px | Font size of a day cell. |
--pct-date-day-font-size-lg{pct.font.size.lg}16px | Font size of a day cell at size lg. |
--pct-date-day-font-size-sm{pct.font.size.sm}13px | Font size of a day cell at size sm. |
--pct-date-day-font-weight-selected{pct.font.weight.medium}500 | Font weight of a day cell when selected. |
--pct-date-day-radius{pct.radius.md}8px | Corner radius of a day cell. |
--pct-date-day-size32px | Size of a day cell. |
--pct-date-day-size-lg36px | Size of a day cell at size lg. |
--pct-date-day-size-sm28px | Size of a day cell at size sm. |
--pct-date-fg{pct.text}#0f172a · #ffffff | Text colour of the date field. |
--pct-date-fg-disabled{pct.text-disabled}#64748b | Text colour of the date field while disabled. |
--pct-date-fg-invalid{pct.danger}#b91c1c · #f87171 | Text colour of the date field when invalid. |
--pct-date-fg-warning{pct.warning}#b45309 · #fbbf24 | Text colour of the warning line (0087). |
--pct-date-font-size{pct.font.size.md}14px | Font size of the date field. |
--pct-date-font-size-lg{pct.font.size.lg}16px | Font size of the date field at size lg. |
--pct-date-font-size-sm{pct.font.size.sm}13px | Font size of the date field at size sm. |
--pct-date-gap{pct.space.3}8px | Gap between the label, the input and the hint. |
--pct-date-hint-fg{pct.text-muted}#334155 · #e2e8f0 | Text colour of the hint. |
--pct-date-icon-size16px | Size of the icon. |
--pct-date-label-fg{pct.text}#0f172a · #ffffff | Text colour of the label. |
--pct-date-nav-bg-hover{pct.surface-100}#f1f5f9 · #1e293b | Background of the month navigation on hover. |
--pct-date-nav-radius{pct.radius.md}8px | Corner radius of the month navigation. |
--pct-date-nav-size28px | Size of the month navigation. |
--pct-date-padding-x{pct.space.4}12px | Horizontal padding of the date field. |
--pct-date-padding-x-lg{pct.space.4}12px | Horizontal padding of the date field at size lg. |
--pct-date-padding-x-sm{pct.space.3}8px | Horizontal padding of the date field at size sm. |
--pct-date-padding-y{pct.space.3}8px | Vertical padding of the date field. |
--pct-date-padding-y-lg{pct.space.4}12px | Vertical padding of the date field at size lg. |
--pct-date-padding-y-sm{pct.space.2}4px | Vertical padding of the date field at size sm. |
--pct-date-panel-bg{pct.surface}#ffffff · #0f172a | Background of the panel. |
--pct-date-panel-border{pct.border-strong}#64748b | Edge colour of the panel. |
--pct-date-panel-padding-x{pct.space.3}8px | Horizontal padding of the panel. |
--pct-date-panel-padding-y{pct.space.3}8px | Vertical padding of the panel. |
--pct-date-panel-radius{pct.radius.md}8px | Corner radius of the panel. |
--pct-date-panel-shadow{pct.shadow-panel}0 8px 24px rgba(15, 23, 42, 0.14) · 0 8px 24px rgba(0, 0, 0, 0.55) | Shadow of the panel. |
--pct-date-placeholder-fg{pct.text-muted}#334155 · #e2e8f0 | Text colour of the placeholder. |
--pct-date-radius{pct.radius.md}8px | Corner radius of the date field. |
--pct-date-target-min{pct.target.min}24px | Touch-target floor of the date field. |
--pct-date-toggle-bg-hover{pct.surface-100}#f1f5f9 · #1e293b | Background of the calendar toggle on hover. |
--pct-date-toggle-fg{pct.text-muted}#334155 · #e2e8f0 | Text colour of the calendar toggle. |
--pct-date-toggle-radius{pct.radius.md}8px | Corner radius of the calendar toggle. |
--pct-date-toggle-size20px | Size of the calendar toggle. |
--pct-date-weekday-fg{pct.text-muted}#334155 · #e2e8f0 | Text colour of a weekday heading. |
--pct-date-weekday-font-size{pct.font.size.sm}13px | Font size of a weekday heading. |
--pct-date-weekday-font-weight{pct.font.weight.medium}500 | Font weight of a weekday heading. |
A brand override in a few declarations. Scope it to a theme attribute, a page or one container — the component never notices.
[data-theme='brand'] {
--pct-date-day-bg-selected: #0f766e;
--pct-date-day-fg-selected: #ffffff;
--pct-date-day-border-today: #0f766e;
}| Sunday | Monday | Tuesday | Wednesday | Thursday | Friday | Saturday |
|---|---|---|---|---|---|---|
| 27 | 28 | 29 | 30 | 1 | 2 | 3 |
| 4 | 5 | 6 | 7 | 8 | 9 | 10 |
| 11 | 12 | 13 | 14 | 15 | 16 | 17 |
| 18 | 19 | 20 | 21 | 22 | 23 | 24 |
| 25 | 26 | 27 | 28 | 29 | 30 | 31 |
| 1 | 2 | 3 | 4 | 5 | 6 | 7 |
Pattern: the grid of Date Picker Dialog — a <table role="grid"> walked by a roving tabindex
| key | effect | test |
|---|---|---|
ArrowRight / ArrowLeft | one day along the inline axis | libs/components/date/src/calendar.spec.ts |
ArrowDown / ArrowUp | one week | libs/components/date/src/calendar.spec.ts |
Home / End | the first / last day of the week it stands in | libs/components/date/src/calendar.spec.ts |
PageDown / PageUp | one month | libs/components/date/src/calendar.spec.ts |
Shift+PageDown / Shift+PageUp | one year | apps/sandbox-e2e/src/date.spec.ts |
Enter / Space | takes the day the cursor is on | libs/components/date/src/calendar.spec.ts |
ArrowRight moves to the next day in an LTR grid and to the previous one in an RTL grid, because a grid's arrows are about the cell to the side and which side that is depends on the direction it is written in — req-token-logical read on the keyboard rather than in a stylesheet. Measured as geometry and as behaviour in apps/sandbox-e2e/src/date.spec.ts.
A walk is not a choice. Moving the cursor never writes the value; only Enter, the space bar or a press does.
Every line is a test in three engines or a gate on every commit. The gaps are listed the same way, each with the requirement that will close it.
libs/components/date/src/calendar.tslibs/components/date/src/calendar.spec.ts and apps/sandbox-e2e/src/date.spec.tsapps/sandbox-e2e/src/a11y.spec.ts — the /date view holds an inline calendar, so the grid is audited attached and not only inside a panelapps/sandbox-e2e/src/visual.spec.ts — date-calendar and date-calendar-rtlforced-colors: activeapps/sandbox-e2e/src/forced-colors.spec.ts — the chosen day, today and a refused day stay three different things after the palette swapprefers-reduced-motiontools/check-styles.mjs point 9 — the day cell's transition takes --pct-motion-transition-durationlibs/components/date/src/calendar.scss — the day cell is --pct-date-day-size (32 px at md, 28 at sm), above the threshold at every size--pct-date-day-size-sm / -lg — every box in the grid is derived from the day cell, so one number moves the whole monthapps/sandbox-e2e/src/date.spec.ts — geometry and arrows; the date-calendar-rtl baselineapps/sandbox-e2e/src/hydration.spec.ts — the /date view is in SBX_ROUTES, and the inline calendar renders on the server<pct-date> that implements FormValueControlaria-live="polite", because it is the one thing that changes without the user moving anything they can seelibs/components/date/src/day.property.spec.ts — the grid's own laws among them: six rows of seven, 42 consecutive days, the first column always firstDayOfWeek, and the month's 1st inside the first row. The bound test this panel reads a cell's disabling from went through < on two day strings until that sweep (lesson-185)libs/components/parts.snapshot.md, tools/check-parts.mjscontrast.policy.jsonlibs/tokens/src/contrast.policy.json — the day, its states and the weekday headingsPCT_TEXTStools/check-texts.mjs — two keys; everything else is Intllibs/components/size.snapshot.md — measured together with the field, one entrypointdocs/acr/at/ — three readers, whole sandbox, and the act on /date that opens the month grid — the only way this component enters the logs. Focus lands on the chosen day and what a reader makes of the cell differs: Orca Choisir une date · dialog · août 2026. · table with 7 rows 7 columns · jeudi column header 27 · row 6 column 4 — the caption, the table's shape, the column heading's long weekday and the cell's TEXT, not the whole date the cell carries as its name; NVDA Choisir une date, dialog, the dialog alone in the act's window; VoiceOver silent in the window and 27 on the row after. So the long weekday reaches a reader through the column heading, as designed, and the cell's date name reached none of the three inside the act's two seconds. The moving focus and the month change are arrows the act does not press, and stay unread/components/calendar on the published site — prerendered, the demo's own source is the code tabRead at build time from the tracked snapshots, not typed here.
It ships in the date entrypoint and is a component of its own rather than a private half of PctDate, for one reason: a calendar standing on the page, always visible, is a real control and not a degenerate date field. <pct-date> puts this one in a panel; a booking screen puts it in a column.
Shift+PageUp/PageDown steps a year; a distant date is reached by typing it in the field, which is the whole reason the field is typable. A three-view picker is a feature waiting for the consumer who needs one without a field beside it.PctDate.Intl.Locale.prototype.getWeekInfo() was absent from firefox 151, which Angular still supports, so 80 regions are written down in locale.ts and checked against the platform's own CLDR for every two-letter region code in locale.spec.ts; date.spec.ts deletes the method in every engine and draws the grid from the table (0084). A consumer can override it outright with firstDayOfWeek.