On this page

Text & numbers

Field released

The wrapper around a form control — its label, its hint, its error, and the wiring between the three.

Import@pacit/components/field
Selectorpct-field

No APG pattern applies, and none is invented — the reasoning is under Accessibility ↓

import { Component, signal } from '@angular/core';
import { FormField, email, form, required } from '@angular/forms/signals';
import { PctField, PctText } from '@pacit/components/field';

/** One line under the field: the hint — or, once you leave it broken, the error. */
@Component({
  selector: 'demo-field',
  imports: [FormField, PctField, PctText],
  styles: ':host { display: block; max-inline-size: 24rem; }',
  template: `
    <pct-field label="E-mail" hint="A work address">
      <input pctText type="email" [formField]="userForm.email" />
    </pct-field>
  `,
})
export class FieldDemo {
  readonly model = signal({ email: '' });
  readonly userForm = form(this.model, (path) => {
    required(path.email, { message: 'The e-mail address is required' });
    email(path.email, { message: 'That does not look like an address' });
  });
}

field.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 { PctField, PctText } from '@pacit/components/field';

Exported	What it is
`PctField`component`pct-field`	The chrome of a form field: label, hint, warning, error message, the required marker and the `[pctPrefix]` / `[pctSuffix]` slots inside the field.
`PctFieldSize`type`PctSize`	The size of a field: the library's own scale.
`PctText`component`input[pctText], textarea[pctText]`	Text field: a directive on a native `<input>`. The input is not wrapped in a component of ours, so `type`, browser autofill, mobile keyboard modes and the whole semantics are kept without an abstraction in between (`req-api-platform`).
`PctAutosize`directive`textarea[pctText][pctAutosize]`	A `<textarea>` as tall as what is written in it — the ARIA APG has no pattern for this, because it is not a behaviour but a height.
`PctNumber`component`input[pctNumber]`	Number field: a component on a native `<input type="text">` with the `spinbutton` role, a value of type `number \| null` and locale-aware formatting.
`PctAffixFit`type`'inset' \| 'fill'`	How a decoration sits in its slot:
`PctPrefix`directive`[pctPrefix]`	A decoration before the control, inside the field border (a currency unit, an icon). Decorative content should be hidden from the screen reader (`aria-hidden`), or have an accessible name of its own if it is interactive.
`PctSuffix`directive`[pctSuffix]`	A decoration after the control, inside the field border (a clear button, say).
`PctLabelAux`directive`[pctLabelAux]`	A label add-on — content in the label row, aligned to the end (an "i" icon with a hint about the field, a help link). It lies outside the field border, so it does not interfere with the control's touch area. If it is interactive (a button, a link) it needs an accessible name of its own.
`PctMessageAux`directive`[pctMessageAux]`	A message-line add-on — content in the row below the field, aligned to the end (a character counter, say). It shares the row with the hint or the error: the chrome shows only one of those messages below the field, and this slot stands beside it whichever one is lit.

<pct-field label="E-mail" hint="A work address">
  <input pctText type="email" />
</pct-field>

Examples

Every state, running

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

Around the control

pctPrefix and pctSuffix sit inside the row, beside the control; pctLabelAux and pctMessageAux sit beside the label and the message — a counter, a link, a unit.

€/ month

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.

The chrome of a form field: label, hint, warning, error message, the required marker and the [pctPrefix] / [pctSuffix] slots inside the field.

Inputs

Name	Type	What it does
`label`default `''`	`string`	The visible `<label>` of the row, wired to the control by `for` or by `aria-labelledby` — whichever the control's `labelStrategy` asks for.
`hint`default `''`	`string`	A line of help under the row; an error or a warning takes its place while one shows (one message at a time, req-api-message).
`size`default `config.defaultSize`	`PctFieldSize`	The field size; taken from the global configuration by default (req-api-config). It concerns the field row — the height here equals that of a button of the same size, because both take it from the `--pct-control-height-*` token (req-api-size).
`required`default `false`	`boolean`	Requiredness can be given outright when the control does not report it.

Outputs

None of its own. The native events — (click), (focus), the form's submit — are the platform's, and two-way models above carry the rest.

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-field`
`data-pct-size`	`size()`
`data-pct-appearance`	`appearance()`
`data-pct-cursor`	`cursor()`
`data-pct-invalid`	`showInvalid() ? "" : null`
`data-pct-warning`	`showWarning() ? "" : null`
`data-pct-disabled`	`disabled() ? "" : null`

Styling

Parts to select, tokens to override

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

Parts

In a test, PctFieldHarness, PctPrefixHarness, PctSuffixHarness, PctLabelAuxHarness, PctMessageAuxHarness from @pacit/components/testing read 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
`field-control`	`[data-pct-part="field-control"]`	the wrapped control itself
`field-error`	`[data-pct-part="field-error"]`	the message when the control is invalid
`field-footer`	`[data-pct-part="field-footer"]`	the row under the control: the hint, the warning or the error
`field-header`	`[data-pct-part="field-header"]`	the row above the control: the label and what stands beside it
`field-hint`	`[data-pct-part="field-hint"]`	the hint, read as the description of the control
`field-label`	`[data-pct-part="field-label"]`	the label, tied to the control by id
`field-label-aux`	`[data-pct-part="field-label-aux"]`	the slot beside the label — a counter, a link
`field-message-aux`	`[data-pct-part="field-message-aux"]`	the slot beside the hint, the warning or the error
`field-prefix`	`[data-pct-part="field-prefix"]`	what sits before the control inside the row
`field-row`	`[data-pct-part="field-row"]`	the control's row, with its prefix and suffix
`field-suffix`	`[data-pct-part="field-suffix"]`	what sits after the control inside the row
`field-warning`	`[data-pct-part="field-warning"]`	the message when the value is allowed and suspect — after the error, before the hint, in the warning tone with a glyph and a hidden word (0087)
`field-label-aux-item`	`[data-pct-part="field-label-aux-item"]`	one projected item inside the label slot
`field-message-aux-item`	`[data-pct-part="field-message-aux-item"]`	one projected item inside the message slot
`field-prefix-item`	`[data-pct-part="field-prefix-item"]`	one projected item inside the prefix
`field-suffix-item`	`[data-pct-part="field-suffix-item"]`	one projected item inside the suffix

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-field-affix-fg{pct.text-muted}`#334155 · #e2e8f0	Text colour of an affix.
`--pct-field-bg{pct.surface}`#ffffff · #0f172a	Background of the field.
`--pct-field-bg-disabled{pct.surface-disabled}`#f1f5f9 · #1e293b	Background of the field while disabled.
`--pct-field-border{pct.border-strong}`#64748b	Edge colour of the field.
`--pct-field-border-disabled{pct.border}`#e2e8f0 · #334155	Edge colour of the field while disabled.
`--pct-field-border-focus{pct.primary}`#2563eb · #60a5fa	Edge colour of the field when focused.
`--pct-field-border-hover{pct.text-muted}`#334155 · #e2e8f0	Edge colour of the field on hover.
`--pct-field-border-invalid{pct.danger}`#b91c1c · #f87171	Edge colour of the field when invalid.
`--pct-field-border-warning{pct.warning}`#b45309 · #fbbf24	Edge colour of the field under a warning (0087).
`--pct-field-fg{pct.text}`#0f172a · #ffffff	Text colour of the field.
`--pct-field-fg-disabled{pct.text-disabled}`#64748b	Text colour of the field while disabled.
`--pct-field-fg-invalid{pct.danger}`#b91c1c · #f87171	Text colour of the field when invalid.
`--pct-field-fg-warning{pct.warning}`#b45309 · #fbbf24	Text colour of the warning line (0087).
`--pct-field-font-size{pct.font.size.md}`14px	Font size of the field.
`--pct-field-font-size-lg{pct.font.size.lg}`16px	Font size of the field at size lg.
`--pct-field-font-size-sm{pct.font.size.sm}`13px	Font size of the field at size sm.
`--pct-field-gap{pct.space.3}`8px	Gap between the field's label, control and hint.
`--pct-field-height{pct.control.height.md}`36px	Height of the field.
`--pct-field-height-lg{pct.control.height.lg}`44px	Height of the field at size lg.
`--pct-field-height-sm{pct.control.height.sm}`28px	Height of the field at size sm.
`--pct-field-hint-fg{pct.text-muted}`#334155 · #e2e8f0	Text colour of the hint.
`--pct-field-label-fg{pct.text}`#0f172a · #ffffff	Text colour of the label.
`--pct-field-label-gap{pct.space.2}`4px	Gap inside the label.
`--pct-field-padding-x{pct.space.4}`12px	Horizontal padding of the field.
`--pct-field-padding-x-lg{pct.space.5}`16px	Horizontal padding of the field at size lg.
`--pct-field-padding-x-sm{pct.space.3}`8px	Horizontal padding of the field at size sm.
`--pct-field-placeholder-fg{pct.text-muted}`#334155 · #e2e8f0	Text colour of the placeholder.
`--pct-field-radius{pct.radius.md}`8px	Corner radius of the field.

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-field-border-focus: #0f766e;
  --pct-field-bg: #f0fdfa;
  --pct-field-fg: #134e4a;
}

Accessibility

Measured, not assumed

Pattern: none — the wrapper has no role of its own: it supplies the label and the descriptions, and the control inside carries the role

Evidence

What the repository holds for this component

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

75.83%mutation score91 of 120 mutants killed

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

14colour pairs measuredlight and dark, at every token build

5visual baselinesChromium, the sandbox's own pictures

14elements in the preview4 listeners · 1 render to settle · 5229 µs in jsdom, held exactly but for the clock

Decisions behind it

0003Wrapper and control
0004Height stated outright, not derived from padding
0006The anchor and inheritance in an overlay
lesson-70A media query adds no specificity, and the browser it is written for hides that
lesson-68A warning about a second one needs to be told when the first one left

Known limitations

Two controls in one chrome are reported, not repaired. The last to register wins, as before — the chrome cannot know which of the two the label was written for — but it is no longer quiet about it: a dev-mode message names both control ids (lesson-68). Registration is a pair (attach / detach), so a control merely replaced inside an @if is not mistaken for a second one, and a control that leaves takes its state out of the chrome with it.
An inset button has to be one step smaller than the field. At size sm there is no step below, so the button fills the height there and pushes the row out by the thickness of the frame. That is a corollary of 0004, not a fitting defect.

pacit

Usage

Every state, running

Around the control

What it reads, and what it writes back

Inputs

Outputs

What it writes on the element

Parts to select, tokens to override

Parts

Tokens

Theming

Measured, not assumed

Keyboard

What is measured, and what is not yet

What the repository holds for this component

Decisions behind it

Known limitations