On this page

Text & numbers

Datetime released

A day and a time of it, typed into two texts under one label or picked in one panel holding a calendar and columns of hours and minutes.

Source

Import@pacit/components/datetime
Selectorpct-datetime

Implements the W3C ARIA APG Date Picker Dialog pattern ↗

Starts

Type it, or pick the day and then the time

import { Component, signal } from '@angular/core';
import { PctDatetime, PctDateTime } from '@pacit/components/datetime';

/** Type the two halves or pick them in one panel — a day first, then the hours. */
@Component({
  selector: 'demo-datetime',
  imports: [PctDatetime],
  styles: ':host { display: block; max-inline-size: 24rem; }',
  template: `
    <pct-datetime
      label="Starts"
      hint="Type it, or pick the day and then the time"
      [(value)]="startsAt"
    />
  `,
})
export class DatetimeDemo {
  readonly startsAt = signal<PctDateTime | null>(null);
}

datetime.demo.ts — the same file runs here and is highlighted under Code

Start here

Usage

One import per component, and the shortest possible use — the package itself is installed once, on the start page.

Import this component

import { PctDatetime } from '@pacit/components/datetime';

Exported	What it is
`PctDateTime`typeunreleased`string`	A day and a time of it, written the way the platform already writes one: `YYYY-MM-DDTHH:mm`, or `YYYY-MM-DDTHH:mm:ss` where the field's step has seconds in it — a `PctDay`, a `T` and a `PctTimeOfDay`.
`PctDateTimeParts`interfaceunreleased	The two halves of a datetime — what the field's two texts hold.
`isPctDateTime`functionunreleased	Whether a string is a datetime this library will work with: a `PctDay`, one capital `T`, and a `PctTimeOfDay` — each half held to its own guard, so the domain is theirs: the day runs from `0000-01-01` to `275760-09-13` and the time refuses `24:00`, a leap second and a fraction.
`pctDateTime`functionunreleased	Joins a day and a time into one value, in the time's shape: `13:05` makes `…T13:05`, and `13:05:00` makes `…T13:05:00`.
`pctDateTimeParts`functionunreleased	The two halves of a datetime, each in the shape it was written in. The caller has already established that it is one.
`pctDateTimeAsUtc`functionunreleased	The pair as the one `Date` anything outside this file is allowed to see: those fields in UTC — which is what `Intl.DateTimeFormat` with `timeZone: 'UTC'` reads back as the same day and time, exactly, in all three engines (0090, B9). It is the day's `pctDayAsUtc` with an hour on it, and it is not an instant anybody meant: no zone the event happens in is asked.
`pctCompareDateTimes`functionunreleased	`-1`, `0` or `1` — the days first, then the times. `…T13:05` and `…T13:05:00`, one value in two shapes, compare equal; and the day's compare reads a year of five digits as later than one of four, where a string compare would not.
`pctClampDateTime`functionunreleased	Held inside the bounds, either of which may be absent — `undefined`, as the `FormUiControl` contract spells an absent bound. A clamp invents no value: it hands back the one it was given or a bound, as written, and a value equal to a bound in the other shape is inside.
`pctAddDateTimeMinutes`functionunreleased	`n` minutes on (or back), and the day carries: `…01T23:30` plus 45 minutes is `…02T00:15`. That is `PlainDateTime`'s answer and the platform's own — a datetime input's `stepUp()` at `23:59` is the next day's `00:00` in all three engines, where the same call on a time input stops or comes round (0090, A10 and B7). The time's shape is kept: a whole minute never moves the seconds.
`pctNowDateTime`functionunreleased	The day and the time on the LOCAL clock — the one read of local time in this file, and the only one that belongs: "what day and what time is it" is a question about where the user is standing, and every other question here is arithmetic on a value that already has an answer.
`PctDateTimePredicate`typeunreleased`(value: PctDateTime) => boolean`	A predicate on a datetime: `true` refuses it — a slot already taken on a day.
`PctDatetimePanelAlign`typeunreleased`'start' \| 'end'`	Which edge of the field the panel lines its own up with.
`PctDatetime`componentunreleased`pct-datetime`	Datetime field — two texts under one label, the day's and the time's, each formatted and parsed per locale, with ONE button and ONE panel holding a calendar and columns of hours and minutes. It is the ARIA APG's Date Picker Dialog whole, through `PctCalendar` as `PctDate` holds it, with the time's columns beside the grid — a `role="listbox"` per field, claimed on their own card.
`PctDateTimeBound`typeunreleased`PctDateTime \| undefined \| LogicFn<TValue, PctDateTime \| undefined, TPathKind>`	A bound `pctDateTimeBounds` takes: a datetime, or a function of the field's context that returns one — the two shapes Angular's own `min()` takes. One that is not a datetime, `undefined` among them, is no bound, as it is on the field's input.
`PctDateTimeBoundError`typeunreleased`\| { readonly kind: 'minDateTime'`	What `pctDateTimeBounds` reports: `minDateTime` for a datetime before `min`, `maxDateTime` for one after `max` — and both at once for one between the two of a reversed pair, the native element's reading on a datetime (0090, A8). Each carries the bound it broke, as the bound was written.
`PctDateTimeBoundsConfig`interfaceunreleased	The bounds of `pctDateTimeBounds`, and the sentence its errors carry — one for both, or one written from the error, which holds the bound.
`pctDateTimeBounds`functionunreleased	Bounds a datetime field in a signal form: what Angular's `min()` / `max()` do for a number and `minDate()` / `maxDate()` for a `Date`, for a `PctDateTime` — which none of them takes (their paths are a number's and a `Date`'s, and the latter read 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 and the columns walk inside them, and the form grades the value: a datetime outside is `minDateTime` or `maxDateTime`.

<pct-datetime label="Starts" [(value)]="startsAt" />

Examples

Every state, running

Each example is the component itself, not a screenshot. Open the code under any of them.

In other languages

Which half stands first, the day's order and the clock all come from Intl for the field's locale — the time first in Vietnamese. One value, written three ways.

American English

Polish

Vietnamese

Within bounds, around taken slots

min and max are a day and a time: the calendar gets the day of each, the columns the time of a bound only on the bound's own day. dateDisabled refuses a day whole; datetimeDisabled is asked of every time of the chosen day, and an hour every slot of which is taken is refused.

Office hours, weekdays

Meeting room

API

What it reads, and what it writes back

Read from the source at build time — the types, the defaults and the lines of documentation are the library's own.

unreleased marks 41 of them: on main, and not in @pacit/components@0.2.0 — the next release names the version.

Datetime field — two texts under one label, the day's and the time's, each formatted and parsed per locale, with ONE button and ONE panel holding a calendar and columns of hours and minutes. It is the ARIA APG's Date Picker Dialog whole, through PctCalendar as PctDate holds it, with the time's columns beside the grid — a role="listbox" per field, claimed on their own card.

Inputs

Name	Type	What it does
`value`two-wayunreleaseddefault `null`	`PctDateTime \| null`	The chosen day and time, or `null` — which it is until both halves hold one.
`disabled`unreleaseddefault `false`	`boolean`	Blocks the control and greys it — the native `disabled` on both texts, so they leave the tab order as well. With `[formField]` the directive writes it, as it writes every input of the `FormUiControl` contract.
`readonly`unreleaseddefault `false`	`boolean`	Keeps the value: both texts take the native `readonly` and the button is disabled with them, while the field stays focusable.
`invalid`unreleaseddefault `false`	`boolean`	The form's verdict; shown only once `touched`, so an empty form does not open red.
`touched`unreleaseddefault `false`	`boolean`	Whether the user has left the field once; with `invalid` it gates the error face.
`required`unreleaseddefault `false`	`boolean`	Marks the label with the required sign; with `[formField]` it follows the schema's `required()`.
`errors`unreleaseddefault `[]`	`readonly ValidationError.WithOptionalFieldTree[]`	The form's validation errors; the first one's `message` takes the hint's place once the field is touched.
`warnings`unreleaseddefault `undefined`	`readonly ValidationError.WithOptionalFieldTree[] \| undefined`	A verdict without a veto (0087): shown after the error and before the hint once the field is touched, in the warning tone, with `aria-invalid` untouched. Left unbound, the control reads what `pctWarn()` wrote for its own `[formField]`; bound — `[]` included — the list given stands.
`name`unreleaseddefault `''`	`string`	The native `name` — what a form submission calls the value. It names a hidden input that carries the value as the platform writes one, `YYYY-MM-DDTHH:mm`, and not either text, which are written in the user's language.
`min`unreleaseddefault `undefined`	`unknown`	The earliest day and time. It belongs to the `FormUiControl` contract, which spells an absent bound `undefined`, and a signal form gives it through `pctDateTimeBounds` — the compiler refuses the attribute beside `[formField]`.
`max`unreleaseddefault `undefined`	`unknown`	The latest day and time — as `min`, a bound on the panel's walk and not a rewrite of what was typed.
`step`unreleaseddefault `60`	`number`	The step in seconds — the time's, 60 by default. It decides the columns' rows, whether a seconds column exists and whether the value carries `:ss`, and nothing about typed text. It counts from midnight on every day, not from `min`: a bound off the step is moved inward onto it before the columns see it (0090 §5). A step the columns cannot list is refused with a dev-mode warning and read as 60.
`dateDisabled`unreleaseddefault `null`	`PctDayPredicate \| null`	Days inside the bounds that cannot be picked — handed to the calendar as it is, so a day it refuses is refused whole, hours included.
`datetimeDisabled`unreleaseddefault `null`	`PctDateTimePredicate \| null`	Slots inside the bounds that cannot be taken — a meeting room's bookings. The field closes it over the chosen day and asks it of every time on the step, in the columns' rows: an hour is refused when every time in it is. It never reaches the calendar; a day whose every slot it refuses is still a day the grid offers, and a consumer who wants that day greyed says so through `dateDisabled`. A typed value it refuses is kept, and the form's to refuse.
`label`unreleaseddefault `''`	`string`	The visible label, rendered by the control itself when it stands outside a `pct-field`; inside one, the field's label is the name. Each text is named by it and a word of its own.
`hint`unreleaseddefault `''`	`string`	A line of help under the control, outside a `pct-field`; the first error message takes its place while the field is invalid and touched.
`ariaLabel`unreleaseddefault `''`	`string`	The accessible name of a field with no visible `label` — an INPUT rather than an `aria-label` on the tag, because the texts sit inside this template and an ARIA name on the roleless host is ignored. Each text is named by it and a word of its own.
`ariaLabelledby`unreleaseddefault `''`	`string`	As `ariaLabel`, for a name that already stands somewhere on the page.
`locale`unreleaseddefault `''`	`string`	Overrides the application's `LOCALE_ID` for this field — the order of the two texts, the day's order and the clock all follow it.
`firstDayOfWeek`unreleaseddefault `0`	`number`	Which day the calendar's week starts on, `1` (Monday) … `7` (Sunday). Absent, the locale decides.
`showFormat`unreleaseddefault `true`	`boolean`	Whether the two format hints stand in the texts while they are empty (`dd.mm.yyyy` and `hh:mm`).
`size`unreleaseddefault `config.defaultSize`	`PctSize`	Height 28 / 36 / 44 px — the axis every field shares; from `providePctConfig` by default (req-api-config).
`panelAlign`unreleaseddefault `'start'`	`PctDatetimePanelAlign`	Which edge of the field the panel lines up with.

Outputs

Name	Payload	When it fires
`touch`unreleased	`void`	Emitted when focus leaves the whole field — both texts, the button and the panel — and not when it moves between them; lets the form mark the field as touched.

What it writes on the element

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-datetime`
`data-pct-size`	`size()`
`data-pct-open`	`open() ? "" : null`
`data-pct-invalid`	`showInvalid() ? "" : null`
`data-pct-warning`	`showWarning() ? "" : null`
`data-pct-disabled`	`disabled() ? "" : null`
`data-pct-malformed`	`malformed() ? "" : null`	What the control knows and the form cannot: there is text in a half and it is not one.
`data-pct-in-field`	`inField ? "" : null`

Styling

Parts to select, tokens to override

Two ways in, both stable. No class names to depend on.

Parts

In a test, PctDatetimeHarness 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
`date-control`	`[data-pct-part="date-control"]`	the day's text
`error`	`[data-pct-part="error"]`	the message when the value is invalid, or a half is not one, or one is missing
`hint`	`[data-pct-part="hint"]`	the hint under the field
`label`	`[data-pct-part="label"]`	the label of the field, pointing at the text that stands first
`panel`	`[data-pct-part="panel"]`	the dialog the calendar and the columns stand in
`time-control`	`[data-pct-part="time-control"]`	the time's text
`toggle`	`[data-pct-part="toggle"]`	the button that opens the panel
`warning`	`[data-pct-part="warning"]`	the message when the value is allowed and suspect — after the error, before the hint (0087)

Tokens

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-datetime-bg{pct.surface}`#ffffff · #0f172a	Background of the datetime field.
`--pct-datetime-bg-disabled{pct.surface-disabled}`#f1f5f9 · #1e293b	Background of the datetime field while disabled.
`--pct-datetime-border{pct.border-strong}`#64748b	Edge colour of the datetime field.
`--pct-datetime-border-disabled{pct.border}`#e2e8f0 · #334155	Edge colour of the datetime field while disabled.
`--pct-datetime-border-focus{pct.primary}`#2563eb · #60a5fa	Edge colour of the datetime field when focused.
`--pct-datetime-border-hover{pct.text-muted}`#334155 · #e2e8f0	Edge colour of the datetime field on hover.
`--pct-datetime-border-invalid{pct.danger}`#b91c1c · #f87171	Edge colour of the datetime field when invalid.
`--pct-datetime-border-warning{pct.warning}`#b45309 · #fbbf24	Edge colour of the datetime field under a warning (0087).
`--pct-datetime-fg{pct.text}`#0f172a · #ffffff	Text colour of the datetime field.
`--pct-datetime-fg-disabled{pct.text-disabled}`#64748b	Text colour of the datetime field while disabled.
`--pct-datetime-fg-invalid{pct.danger}`#b91c1c · #f87171	Text colour of the datetime field when invalid.
`--pct-datetime-fg-warning{pct.warning}`#b45309 · #fbbf24	Text colour of the warning line (0087).
`--pct-datetime-font-size{pct.font.size.md}`14px	Font size of the datetime field.
`--pct-datetime-font-size-lg{pct.font.size.lg}`16px	Font size of the datetime field at size lg.
`--pct-datetime-font-size-sm{pct.font.size.sm}`13px	Font size of the datetime field at size sm.
`--pct-datetime-hint-fg{pct.text-muted}`#334155 · #e2e8f0	Text colour of the hint.
`--pct-datetime-icon-size`16px	Size of the icon.
`--pct-datetime-label-fg{pct.text}`#0f172a · #ffffff	Text colour of the label.
`--pct-datetime-padding-x{pct.space.4}`12px	Horizontal padding of the datetime field.
`--pct-datetime-padding-x-lg{pct.space.4}`12px	Horizontal padding of the datetime field at size lg.
`--pct-datetime-padding-x-sm{pct.space.3}`8px	Horizontal padding of the datetime field at size sm.
`--pct-datetime-padding-y{pct.space.3}`8px	Vertical padding of the datetime field.
`--pct-datetime-padding-y-lg{pct.space.4}`12px	Vertical padding of the datetime field at size lg.
`--pct-datetime-padding-y-sm{pct.space.2}`4px	Vertical padding of the datetime field at size sm.
`--pct-datetime-panel-bg{pct.surface}`#ffffff · #0f172a	Background of the panel.
`--pct-datetime-panel-border{pct.border-strong}`#64748b	Edge colour of the panel.
`--pct-datetime-panel-gap{pct.space.2}`4px	Gap between the calendar and the columns in the panel.
`--pct-datetime-panel-padding-x{pct.space.3}`8px	Horizontal padding of the panel.
`--pct-datetime-panel-padding-y{pct.space.3}`8px	Vertical padding of the panel.
`--pct-datetime-panel-radius{pct.radius.md}`8px	Corner radius of the panel.
`--pct-datetime-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-datetime-placeholder-fg{pct.text-muted}`#334155 · #e2e8f0	Text colour of the placeholder.
`--pct-datetime-radius{pct.radius.md}`8px	Corner radius of the datetime field.
`--pct-datetime-target-min{pct.target.min}`24px	Touch-target floor of the datetime field.
`--pct-datetime-toggle-bg-hover{pct.surface-100}`#f1f5f9 · #1e293b	Background of the button that opens the panel on hover.
`--pct-datetime-toggle-fg{pct.text-muted}`#334155 · #e2e8f0	Text colour of the button that opens the panel.
`--pct-datetime-toggle-radius{pct.radius.md}`8px	Corner radius of the button that opens the panel.
`--pct-datetime-toggle-size`20px	Size of the button that opens the panel.

Theming

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-datetime-border-focus: #0f766e;
  --pct-date-day-bg-selected: #0f766e;
  --pct-time-option-bg-selected: #0f766e;
}

Starts

Type it, or pick the day and then the time

Accessibility

Measured, not assumed

Pattern: Date Picker Dialog — held whole, through PctCalendar as the date field holds it: a button beside the field opens a role="dialog" holding a role="grid", and beside the grid one named role="listbox" per field of the time, claimed on their own card (0090 §7). The two texts stand in a role="group" named by the label, and each is a plain textbox named by the label and a word of its own — deliberately not a combobox, for the date's reason (0035 read backwards)

Keyboard

key	effect	test
any text	typed into a half, parsed when that half is left	`apps/sandbox-e2e/src/datetime.spec.ts › junk in one half keeps the other`
`Tab`	the first text → the second → the button → out; leaving the whole is `touch`	`apps/sandbox-e2e/src/datetime.spec.ts › a day with no time is no value`
`Enter` on the button	opens the panel, focus on the grid's cell — the held day, or today	`apps/sandbox-e2e/src/datetime.spec.ts › opens on the day and the time the field holds`
arrows in the grid	walk the days, as on `PctCalendar`	`apps/sandbox-e2e/src/datetime.spec.ts › a day picked moves on to the hours`
`Enter` in the grid	writes the day's text, leaves the time's as typed, and hands focus to the hour column	`apps/sandbox-e2e/src/datetime.spec.ts › a day picked moves on to the hours`, `libs/components/datetime/src/datetime-field.spec.ts`
`Tab` in the panel	the month buttons, the grid's cell, then the columns one stop each — the grid first	`apps/sandbox-e2e/src/datetime.spec.ts › Tab walks the grid, then the columns`
`Shift+Tab` from the hours	back to the grid's cell — the way to a day picked wrong	`apps/sandbox-e2e/src/datetime.spec.ts › Tab walks the grid, then the columns`
arrows in a column	write the time as they walk, as on `PctTimeColumns`	`apps/sandbox-e2e/src/datetime.spec.ts › a day picked moves on to the hours`
`Enter` in a column	takes the time and closes the panel, focus back on the first text	`apps/sandbox-e2e/src/datetime.spec.ts › a day picked moves on to the hours`
`Escape` in the panel	closes it with the value as the halves left it, focus back on the first text	`apps/sandbox-e2e/src/datetime.spec.ts › Escape closes it`, `libs/components/datetime/src/datetime-field.spec.ts`
`Tab` out of the panel	closes it, focus spliced back onto the first text	`apps/sandbox-e2e/src/datetime.spec.ts › Tab walks the grid, then the columns`

The grid's and the columns' own maps are on their cards. The field adds no key of its own: what a user types is text, and the arrows do not step the segment under the caret, because the engines step the native element's segments three ways (0090, A10) and a reader is never told a textbox has a value to step.

Evidence

What the repository holds for this component

Read at build time from the tracked snapshots, not typed here.

85.64%mutation score692 of 808 mutants killed

15 × 3e2e cases × enginesplus the shared audits: axe, forced colors, preferences, size, hydration

18colour pairs measuredlight and dark, at every token build

3visual baselinesChromium, the sandbox's own pictures

13elements in the preview8 listeners · 1 render to settle · 6335 µs in jsdom, held exactly but for the clock

Decisions behind it

0090A day with a time is a wall clock with a date, and the field that takes one is two texts under one label
0093A bound of the field's own type reaches it through the platform's limit key, and the module ships the rule
0086A time of day is a wall clock, and the field that takes one is text the application formats
0089One value, more than one control, and the consumer chooses which
0043A day is not an instant, and the field that takes one is text the application formats
0070What the control knows and the form cannot is a second channel
0035A filter is a question, not a value
0031A panel's tab order belongs to its trigger
0025A panel says whether it takes focus, and the rest of the focus layer waits for a consumer
0024The overlay layer carries what an overlay severs, and borrows the closing stack
0022One message line, and it is the error that takes it
0005Signal forms without ControlValueAccessor
0003Wrapper and control
lesson-26FormField supplies an NgControl itself

Known limitations

No zone, so neither the gap nor the overlap is refused. 02:30 on 29 March 2026 is a value of this field and does not exist on a wall in Warsaw; 02:30 on 25 October happens there twice. The control cannot know where the event is — in Lisbon both minutes are ordinary — so turning the pair into an instant, and choosing what the skipped and the repeated minute mean, is the application's: Temporal.PlainDateTime.from(value).toZonedDateTime(zone, { disambiguation }) where the engine has it.
A null from outside does not clear a half-filled field. A day typed with no time is null already, so a model or a form writing null over it changes nothing the field can see, and the day stays on the screen with its sentence; reset() — which a signal form's reset calls — takes the half back and writes both texts again from the value, empty here.
One day and time, not a range. A meeting's two ends are two fields with min / max bound to each other (0034) — in a signal form, pctDateTimeBounds with a bound read off the other field. A reversed pair is no window: the night shift is two datetimes on two days, and a time field's 22:00–06:00 ported here gets a warning and no bounds.
Rules that meet in no datetime leave the panel open. A start typed past the close hands the end's field no bounds: the panel offers every day and the form refuses every datetime, each rule with the bound it broke — no pair says "nothing" to a field that reads a reversed one as none. The field's warning is for its own attributes: a pair written reversed by hand in one rule warns of nothing either, and every datetime then carries the errors (0093).
No day without a time. A half-filled field says so, always, and there is no knob to let "required" win over it; a form that wants a day with an optional time is a date field and a time field.
Gregorian only. The calendar and both parsers read the Gregorian calendar, as the date field does; a -u-ca- extension changes nothing the field writes.
datetimeDisabled is asked per row, per day. 1 440 questions on the default step every time the chosen day changes — cheap for a Set, and the consumer's problem for a predicate that fetches.
The clock is the engine's. In chromium a Burmese, Nepali, Georgian, Armenian, Icelandic or Albanian field is written in the browser's default locale — the same engine's own Intl on the same page (0090, C4).
list columns only. The wheel shape the time panel will offer (0089, plan 1.7) reaches this field when it lands.

pacit