# `lr-phone-input` - **Import** `import '@aceshooting/lyra-ui/components/lr-phone-input.js';` (stable tag alias; registers the tag) - **Class** `LyraPhoneInput`, also available unregistered from `@aceshooting/lyra-ui/components/forms/phone-input/phone-input.class.js` - **Family** `components/forms/` — see `llms/index.md` for its siblings - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md` - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt) - **Deprecations** none - **Optional peers** none - **Themeable via** 14 parts, 17 custom properties — see this component's own `@csspart`/`@cssprop` list below - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md` --- ## `lr-phone-input` A form-associated, country-aware telephone field. The submitted `value` is either canonical E.164 (for example `+352621123456`) or `''` while the editable input is empty, incomplete, or invalid. Numbering-plan metadata and national formatting stay outside Lyra's base bundle: supply a synchronous `LyraPhoneNumberAdapter`, or lazily create one from a `libphonenumber-js`-compatible module with `loadLibphonenumberAdapter()`. Without an adapter, already-international E.164 input still normalizes and validates; national input remains editable with `incomplete` validity. The loader returns its discovered country catalog as a frozen array of frozen records. For `default-country`, removing the attribute safely uses the existing country fallback while leaving property readback at native `null`; an existing selected country remains selected. Explicit empty strings remain empty, and later valid default-country values work normally. Host `aria-describedby` references resolve onto the telephone input before its local hint/error guidance. References track missing IDs, target replacement, removal/reinsertion, reconnect, and adoption. The country selector keeps its separate existing accessible-name contract. The country selector keeps the real native ``. - `readonly: boolean = false` (reflected) — forwards to the native telephone input, locks the country selector and all user edit handlers, and bars validation while retaining focus, selection/copying, canonical form value, and submission. - `autofocus: boolean = false` (reflected) — forwarded to the actual native telephone input; it is never stranded on the non-focusable host. - readonly `input: HTMLInputElement | undefined` — the internal native telephone input. - readonly `inputValue: string` — editable formatted/partial text, which remains available even when canonical `value` is `''`. - `selectionStart`, `selectionEnd`, and `selectionDirection` — native selection getters/setters forwarded to the telephone input - readonly `phoneStatus: LyraPhoneNumberStatus` — current parse state. The host also reflects it through `data-phone-status`. - readonly `form`, `labels`, `validity`, `validationMessage`, `willValidate`, and `effectiveDisabled` — the shared form-associated native-like getters. **Events:** each text edit emits native `InputEvent` `input` then `lr-input`; telephone-input commit emits native `Event` `change` then `lr-change`; and a country pick emits both pairs in order: `input`, `lr-input`, `change`, `lr-change`. Native events carry no custom detail; the aliases carry `{ value, inputValue, country, valid, status }`. Internal `focus`/`blur` are relayed once as realm-correct native `FocusEvent`s preserving `relatedTarget`. `lr-invalid` has no detail and is the one bubbling/composed alias when native validity fails. Programmatic value writes remain silent. **Validity:** empty + `required` sets `valueMissing`; incomplete dial-like input sets `badInput`; completed-invalid input sets `typeMismatch`; valid E.164 input clears all three. Partial or invalid text remains in `inputValue`/the native input so validation never makes a number impossible to edit, but its canonical submitted `value` is blank. Native validation feedback is anchored to the telephone input, not the adjacent country selector. **Methods:** `focus(options?)`, `blur()`, `select()`, `setSelectionRange()`, and `setRangeText()` forward to the native telephone input. Range-text edits reparse the number and synchronize the canonical value, form value, and validity. `getForm()`, `setFormValue(value)`, `checkValidity()`, and `reportValidity()` come from `FormAssociated`. `setCustomValidity(message)` sets or clears `customError` without discarding the control's intrinsic phone-number validity. `resetValidity()` clears only that consumer error and recomputes the current phone-number constraints; it does not change the editable/canonical value, the reset default, or prior interaction state. `form.reset()` restores the original declarative `value` and the default country. **Slots:** `label`, `hint`, `error`, `country-prefix` (optional visual before the country selector, such as a consumer-owned ``; no flag package is imported automatically). **CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `country-prefix`, `country` (the selector region: invisible native select layered over the visual trigger), `country-select`, `country-trigger` (visible, `aria-hidden` closed-state box), `flag` (the ``, only with `flags`), `country-code` (selected alpha-2 code, `data-placeholder` when no country exists), `expand-icon`, `calling-code`, `input`, `hint`, `error`. `error` is ordinary visible validation text referenced by the native telephone input through `aria-describedby`, not a shadow `role="alert"`. Native invalid/focus feedback therefore has one description path instead of being duplicated by a second live-region announcement. **The required marker.** `required` with a non-empty `label` paints the library's shared marker on `[part="form-control-label"]` — the one `::after` rule described above, not a copy of it, so `--lr-form-control-required-content`, `--lr-form-control-required-color` and `--lr-form-control-required-offset` retune or suppress it here exactly as they do on `lr-input`. With no label text the part is hidden and no glyph is painted. **Themeable custom properties:** `--lr-phone-input-padding-block` (scaled through the shared form-control padding ladder), `--lr-phone-input-font-size`, and `--lr-phone-input-control-min-height` (each scaled by `size`), plus `--lr-phone-input-control-height` to pin an exact input-wrapper height (both floors and caps it — use it for pixel-matching an `` or `` in the same toolbar row; undeclared by default, leaving the min height as a floor only). The phone-number input and calling code are deliberately `dir="ltr"`/isolated because telephone numbers are algorithmic content; surrounding form chrome and the country selector inherit LTR/RTL and use logical spacing/borders. The native country selector's hover and press backgrounds are supplemented in forced-colors mode with dashed/solid `Highlight` outlines, so those states do not collapse when the UA flattens the background tint to `Canvas`. **Optional peer deps:** `libphonenumber-js` is declared optional but never imported by Lyra itself. For full national parsing/formatting, install it in the consuming app and pass it through the consumer-supplied lazy loader below. Because the import expression lives in consumer code, no numbering metadata enters a bundle that does not opt in. ```ts import "@aceshooting/lyra-ui/components/forms/phone-input/phone-input.js"; import { loadLibphonenumberAdapter } from "@aceshooting/lyra-ui/components/forms/phone-input/phone-input.class.js"; const phone = document.querySelector("lr-phone-input"); phone.adapter = await loadLibphonenumberAdapter( () => import("libphonenumber-js/min") ); ``` ```html ``` ```ts // Country flags in the trigger (optional): same peer contract as a standalone . import "@aceshooting/lyra-ui/components/media/flag/flag-peer.js"; ``` ```html ``` **Known gotchas:** - An adapter's `parse()` method is synchronous because it runs on every keystroke. Load any optional module first, then assign the resolved adapter. Once an adapter is assigned, exceptions and malformed results fail closed to `invalid`; only the no-adapter mode uses the E.164-only fallback. - A valid adapter result must include an E.164-shaped `e164`; the discriminated result type makes that requirement statically visible and runtime normalization prevents malformed success from entering form submission. - Country names use `Intl.DisplayNames` and fall back to the ISO code; set `LyraPhoneCountry.label` for a product-specific name. Calling codes are data, not derived by the component. - The component never imports `@aceshooting/lyra-flags` itself, with `flags` or without. `flags` lazily registers only the `` element; the artwork resolver comes from the consumer's own `flag-peer.js` import (plus the installed peer package), so forgetting either shows a flagless trigger rather than erroring. `country-prefix` remains available for a fully consumer-owned adornment instead. - The visible trigger (`country-trigger` and everything inside it) is `aria-hidden` by design; the layered native select is the accessible control. Don't move interactive content into those parts via `::part` styling tricks, and don't expect the flag inside the open popup list — a native `