Campo de código de un solo uso

Categoría: Entradas de texto
Tokens: comp.field
Nivel: Compuesto
Se compone de: Field, One-time-code input

Descripción general

Web: tanrei-one-time-code-field; schedule
SwiftUI: TanreiOneTimeCodeField; radio_button_unchecked
Jetpack Compose: TanreiOneTimeCodeField; radio_button_unchecked
Flutter: TanreiOneTimeCodeField; radio_button_unchecked
React Native: OneTimeCodeField; radio_button_unchecked

Generado a partir de docs/status/status.json, specs/one-time-code-field.spec.json

Un campo de código de un solo uso, y otro cuyo código rechazó el producto

Usa un campo de código de un solo uso allí donde un producto pide de vuelta un código corto que envió: para iniciar sesión, para confirmar una dirección o un número de teléfono, para aprobar un pago. Es el caso corriente, listo para usarse: una etiqueta, las celdas, una línea que dice adónde se envió el código y las palabras para un código incorrecto.

Se compone de un campo y una entrada de código de un solo uso. El campo es el marco: la etiqueta, la marca de obligatorio o de opcional, la ayuda y el error. La entrada de código de un solo uso es el control: las celdas y todo lo que una persona hace en ellas. El campo de código de un solo uso no dibuja nada propio y no tiene ningún token: cada propiedad que tiene es una propiedad de uno de los dos, que se le da sin cambios.

Es tan ancho como el lugar en el que se pone, y las celdas empiezan en su borde de inicio.

En la web es <tanrei-one-time-code-field>. Las demás plataformas todavía no lo han implementado.

Uso

value es el código introducido hasta el momento, sin separador, sean cuales sean los grupos dibujados. Los cuatro eventos son los de la propia entrada de código de un solo uso, y cuando se oye cualquiera de ellos el value del campo ya es el nuevo.

<form>
  <tanrei-one-time-code-field name="code" label="Código de verificación"
    supporting-text="Introduce el código de 6 dígitos que enviamos a tu teléfono."
    error-text="El código no es correcto. Revisa el mensaje e inténtalo de nuevo."
    required required-text="Obligatorio"
    group-size="3"></tanrei-one-time-code-field>
</form>

<script type="module">
  import '@tanrei/web/components/one-time-code-field';

  const code = document.querySelector('tanrei-one-time-code-field');
  // La persona cambió el valor. Ya es el nuevo.
  code.addEventListener('input', () => (code.error = false));
  // Se rellenó la última celda, o se pegó o se rellenó un código entero. Nada más ocurre por sí solo.
  code.addEventListener('complete', async (e) => {
    code.readOnly = true;
    const right = await verify(e.detail.value);
    code.readOnly = false;
    code.error = !right;
  });
</script>

import { OneTimeCodeField } from '@tanrei/react';

<OneTimeCodeField name="code" label="Código de verificación" error={wrong}
  supportingText="Introduce el código de 6 dígitos que enviamos a tu teléfono."
  errorText="El código no es correcto. Revisa el mensaje e inténtalo de nuevo."
  groupSize={3} value={code}
  onInput={(event) => setCode(event.currentTarget.value)}
  onComplete={(event) => verify(event.detail.value)} />

Un nivel más abajo

El mismo campo, escrito a mano a partir de sus dos miembros, da la misma imagen y es el mismo cuadro de texto para la tecnología de apoyo:

<tanrei-field label="Código de verificación"
  supporting-text="Introduce el código de 6 dígitos que enviamos a tu teléfono."
  error-text="El código no es correcto. Revisa el mensaje e inténtalo de nuevo.">
  <tanrei-one-time-code-input name="code" group-size="3"></tanrei-one-time-code-input>
</tanrei-field>

El mismo campo escrito a mano: un campo con una entrada de código de un solo uso dentro

Baja a ese nivel cuando necesites una organización que el campo de código de un solo uso no ofrece:

Necesitas	Usa
Una etiqueta, las celdas, una ayuda y un error	El campo de código de un solo uso
Algo tuyo dentro del marco, junto a las celdas: un control para volver a enviar el código, una cuenta atrás	Un campo con una entrada de código de un solo uso y tu propio elemento dentro
Las celdas solas, bajo una etiqueta que se dibuja en otro lugar: el título de un diálogo, el título de un paso	La entrada de código de un solo uso sola, que recibe su nombre de su propio `label`
Una sola caja sin celdas, para un código cuya longitud no se conoce	Un campo de texto con `autocomplete="one-time-code"`

Lo que cambia un nivel más abajo es dónde se dice cada cosa. name y value están en la entrada de código de un solo uso, que es entonces el control con el que trata el formulario, y sus eventos se oyen en ella. label, error y disabled se quedan en el campo, que se los pasa al control: no definas los de la propia entrada.

Especificaciones

Obligatorio con la palabra del producto, opcional, deshabilitado y un código oculto de cuatro

Qué aporta cada miembro

Aspecto	Del campo	De la entrada de código de un solo uso
Propiedades	`label`, `labelHidden`, `supportingText`, `errorText`, `error`, `disabled`, `required`, `optional`, `requiredMark`, `requiredText`, `optionalText`	`value`, `length`, `type`, `groupSize`, `mask`, `readOnly`
Eventos	—	`input`, `change`, `complete`, `action`
Slots	`label-icon`	—
Tokens	`comp.field.*`	`comp.one-time-code-input.*`

La entrada de código de un solo uso tiene un label, un error y un disabled propios. No son propiedades del campo de código de un solo uso: el label del campo da nombre al control, su error pone las celdas en su estado de error y su disabled las deshabilita. Así, defines cada uno una sola vez, en el campo de código de un solo uso, y su etiqueta cambia con el control.

Lo que hacen las celdas —escribir, pegar, las teclas de flecha, los grupos— está en la página de la entrada de código de un solo uso. Lo que hace el marco —la marca de obligatorio, la ayuda, el error y cómo se anuncia— está en la página del campo.

Diferenciar un solo campo

El campo de código de un solo uso no tiene ningún token propio. Su marco lee los tokens del campo, y sus celdas los de la entrada de código de un solo uso, allí donde estén definidos. Para cambiar una sola instancia, define en ella el token del miembro:

<tanrei-one-time-code-field label="Código de verificación"
  style="--tanrei-comp-field-label-gap: 12px"></tanrei-one-time-code-field>

Anatomía

Dibujado sobre el fixture supporting, tal como lo dibuja el paquete web.

Parte	Descripción
1 `field`	The frame: a Field, whole — its label row with the label glyph and the requirement mark, and its supporting row, where the error text stands in the help's place or below it (FLD-7). Drawn by the Field from the Field's tokens (FLD-1 to FLD-9).
2 `one-time-code-input`	The frame's one control: a One-time-code input, whole — its cells, its characters, its caret and its group marks. Drawn by the One-time-code input from its own tokens (OTC-1 to OTC-3, OTC-15).

Propiedades

Propiedad	Tipo	Valor predeterminado	Descripción
`label`	`string`	`""`	Names the control, visibly and to assistive technology. Required, unless the control names itself (a checkbox or a switch with its own label): then leave it empty and the field adds only help and an error. — Field Always given: the control of a one-time-code field never names itself, so the case of an empty label does not arise.
`labelHidden`	`boolean`	`false`	Does not draw the label, which stays the accessible name. For a control whose visible label is elsewhere (a table column, a toolbar). — Field
`supportingText`	`string`	`""`	Help shown below the control and given to assistive technology as the control's description. While the field is in error it gives way to errorText, unless the design system keeps both (comp.field.error-text.placement append). — Field
`errorText`	`string`	`""`	Shown while error is true, in supportingText's place — or below it, which then stays, where the design system's comp.field.error-text.placement is append: what is wrong and how to put it right, in words. — Field
`error`	`boolean`	`false`	Puts the field in the error condition: the error text is drawn, the control is exposed as invalid and, where it has an error condition of its own, drawn in it. What a value means is the product's to validate; the field never sets this itself. — Field The one error of the one-time-code field: the Field passes it to the control (FLD-8, OTC-17), whose own error is not a prop here.
`disabled`	`boolean`	`false`	Disables the control and draws the frame as disabled. Disable a framed control here, not on the control, so that its label follows. — Field The one disabled of the one-time-code field: the Field passes it to the control (FLD-14, OTC-20), whose own disabled is not a prop here.
`required`	`boolean`	`false`	What the form asks of the control: true exposes it as required and draws the required mark beside the label. It never validates: a missing answer is the product's to report with error. — Field
`optional`	`boolean`	`false`	Draws the optional tag after the label and adds optionalText to the control's description, because assistive technology has no state for it. Ignored while required is true: a control is never both. — Field
`requiredMark`	`auto` \| `tag` \| `asterisk` \| `none`	`"auto"`	How this control shows that it is required: tag is a small filled Tag with requiredText, asterisk is "*" after the label, none draws nothing and keeps the semantics. Auto takes comp.field.requirement.mark, which follows sys.behavior.requirement-mark, the system's one answer. Ignored unless required is true. — Field
`requiredText`	`string`	`""`	The text of the required tag, in the product's language ("Required", "必須"). The product's: Tanrei has no word for it. Empty reads the product's words; with neither, FLD-24 says what is drawn. — Field
`optionalText`	`string`	`""`	The text of the optional tag, in the product's language ("Optional", "任意"); also read to assistive technology as part of the description. The product's: Tanrei has no word for it. Empty reads the product's words. — Field
`value`	`string`	`""`	The code entered so far: at most length characters, digits or, for alphanumeric, digits and upper-case letters, with no separator. One string, whatever the cells and groups drawn. — One-time-code input
`length`	`number`	`6`	How many characters the code has, and so how many cells are drawn. A whole number of 1 or more. — One-time-code input
`type`	`numeric` \| `alphanumeric`	`"numeric"`	What a cell takes: numeric is the digits 0 to 9, with a numeric keypad; alphanumeric is digits and the letters A to Z, held in upper case, with a general keyboard. — One-time-code input
`groupSize`	`number`	`0`	Draws the cells in groups of this many, counted from the first, with a mark between two groups (3 for a six-character code written "123 456"). 0 draws one group. It changes the drawing only: the value has no separator. — One-time-code input
`mask`	`boolean`	`false`	Draws the platform's obscuring mark in each filled cell in place of its character, and exposes the field as protected. For a screen other people can see; a code that is used once and expires rarely needs it. — One-time-code input
`readOnly`	`boolean`	`false`	Keeps the field focusable and its value readable, and lets nothing change it: for the moment a complete code is being checked, when taking focus away would lose the place of a person who must then correct it. — One-time-code input

Slots

Slot	Descripción
`label-icon`	A glyph before the label. — Field

Eventos

Evento	Descripción
`input`	The person changed the value; carries the new value. Emitted for every change, not when the product sets value. — One-time-code input
`change`	The person committed a changed value (focus left the field, or the action key was pressed); carries the value. — One-time-code input
`complete`	A change by the person left the value length characters long; carries the value. Emitted after input, once for that change. The field does nothing else: checking the code is the product's. — One-time-code input
`action`	The person pressed the keyboard's action key (Enter, Return, Done). — One-time-code input

Estados

Comportamiento

Requisitos en formato EARS. Cada implementación de plataforma se prueba contra estos identificadores. El texto de los requisitos se muestra tal como está en la especificación, en inglés.

ID	Requisito
`OTF-1`	THE one-time-code field SHALL be a Field whose one control is a One-time-code input, and SHALL draw nothing of its own: every row, text, mark, cell and line it shows is drawn by one of the two, from that component's own tokens, as FLD-1 to FLD-8 and OTC-1 to OTC-3, OTC-7 and OTC-15 to OTC-17 say. THE one-time-code field SHALL have no token, no size and no gap of its own: the Field places the control and gives it its width (FLD-1), and the One-time-code input lays its row out in that width (OTC-1, OTC-23). What it shows SHALL be the picture a product gets by placing that One-time-code input in that Field by hand with the same values, and what assistive technology is told SHALL be the same name, description and states (FLD-10, FLD-11, OTC-22).
`OTF-2`	THE one-time-code field SHALL give each of its props, unchanged, to the member it is from and SHALL hold no state between the two: label, labelHidden, supportingText, errorText, error, disabled, required, optional, requiredMark, requiredText and optionalText are the Field's; value, length, type, groupSize, mask and readOnly are the One-time-code input's. A value a member does not know SHALL be passed on as given and answered by that member (FLD-22, OTC-19). THE one-time-code field SHALL never set the One-time-code input's own label, error or disabled: the Field's label names the control (FLD-10, OTC-22), the Field's error puts it in its error condition (FLD-8, OTC-17) and the Field's disabled disables it (FLD-14, OTC-20), so that each is said once, in the place where the label follows.
`OTF-3`	THE one-time-code field SHALL hold one value, the One-time-code input's. WHEN the person changes it THE one-time-code field's value SHALL be the new one before any event is reported, and THE one-time-code field SHALL report input, change, complete and action as the One-time-code input emits them — the same events, carrying the same value, in the same order and as often (OTC-13, OTC-14) — as its own, adding none and holding none back. WHEN the product sets value THE one-time-code field SHALL show it as OTC-18 says and SHALL report no event.
`OTF-4`	WHERE the platform has forms (the web) THE one-time-code field SHALL be the one control the form meets, and what OTC-29 says of a One-time-code input SHALL hold of the one-time-code field as a whole: it takes name; it submits the code alone, an empty string WHILE it holds none, and nothing WHILE disabled (OTC-20); it is restored on navigation and resets to the value it was first given; and it reports a missing value WHILE required is true and the value is empty, and nothing for a code shorter than length. Its members SHALL add no entry of their own to the form, and the action key SHALL submit the form the one-time-code field belongs to as OTC-13 says, unless action was cancelled.
`OTF-5`	THE one-time-code field SHALL be one stop in the focus order, its control's (FLD-12, OTC-2). WHEN the product moves focus to the one-time-code field THE one-time-code field SHALL pass it to the control, whose active cell is then the one OTC-5 names. A press on the label row SHALL move focus to the control and a press on the supporting row SHALL do nothing (FLD-12); THE one-time-code field SHALL take focus for no other press, SHALL add no key, and SHALL draw no focus indicator of its own: the frame's focused tokens and the active cell's focused line are the members' (FLD-13, OTC-7).
`OTF-6`	THE one-time-code field SHALL hold exactly one control and SHALL take no other from the product: it has no place for a child but the Field's label glyph (FLD-3, FLD-20), so that the cases of FLD-15 — no control, several controls — and of FLD-23 — a control replaced by another — never arise in it. IF the one-time-code field is placed in a Field THEN THE one-time-code field SHALL be drawn as it is and reported in debug builds as a field placed in a Field (FLD-15); WHERE it is placed in a field group THE one-time-code field SHALL follow the group's disabled as a Field does (FGR-14) and SHALL take nothing else from the group.
`OTF-7`	THE one-time-code field SHALL have no words of its own: every word it shows or says is a prop of the Field's, read as FLD-24 says — the instance's, else the product's words of the same name — and the One-time-code input has none (OTC-30). THE one-time-code field SHALL read no key of the product's words itself.
`OTF-8`	THE one-time-code field SHALL add nothing to how its members answer the place they are used in: the layout direction (FLD-18 to FLD-21; OTC-27 and OTC-28, by which the cells stay a left-to-right run and stand at the start edge, under the label), enlarged text (FLD-16, OTC-23, OTC-24), a person's own forced colors (FLD-17, OTC-26) and the caret's reduced motion are each member's own answer. THE one-time-code field SHALL have no direction, size, color or motion setting of its own, and SHALL never be wider than its layout gives it.
`OTF-9`	WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE one-time-code field SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on the element that carries its role — an id reference by the elements it names in the host's tree or a tree around it, an error message as part of the description while the one-time-code field is invalid — except those the one-time-code field owns (aria-label, aria-labelledby, aria-disabled), which it SHALL move and not expose: its name is label (OTF-1). WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE one-time-code field SHALL take it off that element. WHEN the product sets an aria- attribute the one-time-code field owns THE one-time-code field SHALL report it in debug builds.

Correspondencia de nombres por plataforma

Paridad no significa API idénticas. Cada plataforma expresa el mismo contrato con su propio estilo.

Especificación	Web	SwiftUI	Jetpack Compose	Flutter	React Native
Componente	`tanrei-one-time-code-field`	`TanreiOneTimeCodeField`	`TanreiOneTimeCodeField`	`TanreiOneTimeCodeField`	`OneTimeCodeField`
`label` · Propiedad	`label`	`label`	`label`	`labelText`	`label`
`labelHidden` · Propiedad	`labelHidden`	`labelsHidden`	`labelHidden`	`labelHidden`	`labelHidden`
`supportingText` · Propiedad	`supportingText`	`supportingText`	`supportingText`	`helperText`	`supportingText`
`errorText` · Propiedad	`errorText`	`errorText`	`errorText`	`errorText`	`errorText`
`error` · Propiedad	`error`	`error`	`isError`	`isError`	`error`
`disabled` · Propiedad	`disabled`	`disabled`	`enabled`	`enabled`	`disabled`
`required` · Propiedad	`required`	`isRequired`	`required`	`required`	`required`
`optional` · Propiedad	`optional`	`isOptional`	`optional`	`optional`	`optional`
`requiredMark` · Propiedad	`requiredMark`	`requiredMark`	`requiredMark`	`requiredMark`	`requiredMark`
`requiredText` · Propiedad	`requiredText`	`requiredText`	`requiredText`	`requiredText`	`requiredText`
`optionalText` · Propiedad	`optionalText`	`optionalText`	`optionalText`	`optionalText`	`optionalText`
`value` · Propiedad	`value`	`code`	`value`	`controller`	`value`
`length` · Propiedad	`length`	`length`	`length`	`length`	`length`
`type` · Propiedad	`type`	`type`	`type`	`type`	`type`
`groupSize` · Propiedad	`groupSize`	`groupSize`	`groupSize`	`groupSize`	`groupSize`
`mask` · Propiedad	`mask`	`isMasked`	`masked`	`obscureText`	`secureTextEntry`
`readOnly` · Propiedad	`readOnly`	`readOnly`	`readOnly`	`readOnly`	`readOnly`
`input` · Evento	`input`	`code`	`onValueChange`	`onChanged`	`onChangeText`
`change` · Evento	`change`	`onCommit`	`onCommit`	`onCommit`	`onEndEditing`
`complete` · Evento	`complete`	`onComplete`	`onComplete`	`onCompleted`	`onComplete`
`action` · Evento	`action`	`onSubmit`	`keyboardActions`	`onSubmitted`	`onSubmitEditing`
Notas	`<tanrei-one-time-code-field name="code" label="Verification code" supporting-text="Enter the 6-digit code we sent to your phone." group-size="3"></tanrei-one-time-code-field>`. Composed: a custom element with a shadow root that holds its members' own elements — `<tanrei-field part="field" exportparts="label, label-icon, requirement-label, supporting-text"><tanrei-one-time-code-input part="one-time-code-input" exportparts="input, cell, character, caret, separator"></tanrei-one-time-code-input></tanrei-field>` — and nothing else but the passage of the `label-icon` slot; its module imports both members' modules, so where it is defined they are. Each prop is a property and an attribute of the element under its member's own attribute name (`label-hidden`, `supporting-text`, `error-text`, `required-mark`, `required-text`, `optional-text`, `group-size`, `readonly`) and is set on that member as a property; the element writes no custom property and reads no token, so every `--tanrei-comp-field-` and `--tanrei-comp-one-time-code-input-` value reaches the members by inheritance, and one instance is set apart by setting such a property on this element. One level down, the same by hand: `<tanrei-field label="Verification code" supporting-text="…"><tanrei-one-time-code-input name="code" group-size="3"></tanrei-one-time-code-input></tanrei-field>`. Form-associated itself (`static formAssociated = true`): its members stand in its shadow root, outside any form, so it takes `name` and `form`, repeats on its own ElementInternals the value, the state and the validity its One-time-code input tells its own — the same flags, the same message and the same anchor, the native input, so the browser's message points where it points one level down — resets to its `value` attribute, and passes a disabled `<fieldset>` on to its Field (OTF-4); Enter in the cells presses the default button of this element's form. The shadow root does not delegate focus — a press on the supporting row must do nothing (FLD-12) — so `focus()` and `blur()` are passed to the control, a click that arrives on the element itself (a page's own `<label for>`) moves focus there, and `autofocus` is copied to the control (OTF-5). The four events are the One-time-code input's own composed, bubbling CustomEvents: they leave the shadow root by themselves with the element as their target, and the element's `value` is at every moment its One-time-code input's — what was last set on the element until the input has taken it, and from then on what the input holds — so `event.target.value` is the code in every listener, capturing or bubbling (OTF-3); it dispatches nothing itself. The name, the description and the states reach the native input as values, by the `tanrei-field-connect` exchange between the two members inside the one shadow root, exactly as in a product's markup; the element's own host has no role, and an `aria-` attribute the product writes on it moves to `data-aria-` and reaches the cells' input, as its accessibility notes say — but for the name: name it with `label` (and `label-hidden`), never with `aria-label`, which a debug build reports. Inside a `tanrei-field-group` it follows the group's `disabled` through its Field (OTF-6). `custom-elements.json` shows it whole — sixteen attributes with their members' descriptions, four events with `TanreiOneTimeCodeInputDetail`, the `label-icon` slot, the two member parts and the nine exported ones, and the `form` attribute — and the React wrapper `OneTimeCodeField` is generated from that, with `onInput`, `onChange`, `onComplete` and `onAction`. Before the element is defined it has no size and shows nothing but a `label-icon` child, which a page hides with `tanrei-one-time-code-field:not(:defined) > *`; a page that must not jump gives the tag a block size of its own, and a page that must work without script writes a `<label>` around a plain `<input autocomplete="one-time-code" inputmode="numeric">` with its help beside it. The host is `display: block`. Words: the element has none; `required-text` and `optional-text` left empty are read by its Field from the product's words.	`TanreiOneTimeCodeField("Verification code", code: $code, supportingText: "…", groupSize: 3, onComplete: verify)`: a view whose body is `TanreiField(…) { TanreiOneTimeCodeInput(…) }` with each argument passed to the member it is from, and nothing else. `code` is the input's `Binding<String>`; `labelHidden` follows `.labelsHidden()` and `disabled` follows `.disabled(_:)`, as the Field's do; the glyph is the Field's `labelIcon:`. One field is set apart by `.tanreiTheme(_:)` on this view. Planned: owed after the One-time-code input itself.	`TanreiOneTimeCodeField(label = "Verification code", value = code, onValueChange = { code = it }, supportingText = …, groupSize = 3, onComplete = ::verify)`: a composable that calls `TanreiField(…) { TanreiOneTimeCodeInput(…) }` with each argument passed to the member it is from, and nothing else. `enabled` is the Field's inverse flag; the glyph is the Field's `labelIcon`. One field is set apart by a `TanreiTheme(…) { }` around this call. Planned: owed after the One-time-code input itself.	`TanreiOneTimeCodeField(labelText: 'Verification code', controller: code, helperText: …, groupSize: 3, onCompleted: verify)`: a widget whose build returns `TanreiField(…, child: TanreiOneTimeCodeInput(…))` with each argument passed to the member it is from, and nothing else. The names follow the members'; `enabled` is the Field's inverse flag; the glyph is the Field's `labelIcon`. One field is set apart by a `TanreiTheme` widget around it. Planned: owed after the One-time-code input itself.	`<OneTimeCodeField label="Verification code" value={code} onChangeText={setCode} supportingText="…" groupSize={3} onComplete={verify} />`: a component that returns `<Field …><OneTimeCodeInput … /></Field>` with each prop passed to the member it is from, and nothing else. The glyph is the Field's `labelIcon` prop. One field is set apart by a provider around it. Planned: owed after the One-time-code input itself.

Tokens

Token	Alias de	Valor resuelto (claro)
`--tanrei-comp-field-counter-gap`	`sys.space.space200`	16px
`--tanrei-comp-field-error-text-gap`	`sys.space.space50`	4px
`--tanrei-comp-field-error-text-placement`	—	0
`--tanrei-comp-field-label-icon-gap`	`sys.space.space100`	8px
`--tanrei-comp-field-label-icon-size`	`sys.icon.small`	20px
`--tanrei-comp-field-label-gap`	`sys.space.space100`	8px
`--tanrei-comp-field-motion-state-duration`	`sys.motion.role.state.default`	250ms
`--tanrei-comp-field-motion-state-easing`	`sys.motion.easing.state`	cubic-bezier(0.2, 0, 0, 1)
`--tanrei-comp-field-requirement-asterisk-gap`	`sys.space.space25`	2px
`--tanrei-comp-field-requirement-gap`	`sys.space.space100`	8px
`--tanrei-comp-field-requirement-mark`	`sys.behavior.requirement-mark`	0
`--tanrei-comp-field-standard-counter-color`	`sys.color.on-surface-variant`	#4b4b4b
`--tanrei-comp-field-standard-disabled-counter-color`	—	#1b1b1b · 38%
`--tanrei-comp-field-standard-disabled-error-text-color`	—	#1b1b1b · 38%
`--tanrei-comp-field-standard-disabled-error-counter-color`	—	#1b1b1b · 38%
`--tanrei-comp-field-standard-disabled-error-label-icon-color`	—	#1b1b1b · 38%
`--tanrei-comp-field-standard-disabled-error-label-color`	—	#1b1b1b · 38%
`--tanrei-comp-field-standard-disabled-error-required-asterisk-color`	—	#1b1b1b · 38%
`--tanrei-comp-field-standard-disabled-error-supporting-text-color`	—	#1b1b1b · 38%
`--tanrei-comp-field-standard-disabled-error-value-text-color`	—	#1b1b1b · 38%
`--tanrei-comp-field-standard-disabled-label-icon-color`	—	#1b1b1b · 38%
`--tanrei-comp-field-standard-disabled-label-color`	—	#1b1b1b · 38%
`--tanrei-comp-field-standard-disabled-required-asterisk-color`	—	#1b1b1b · 38%
`--tanrei-comp-field-standard-disabled-supporting-text-color`	—	#1b1b1b · 38%
`--tanrei-comp-field-standard-disabled-value-text-color`	—	#1b1b1b · 38%
`--tanrei-comp-field-standard-error-text-color`	`sys.color.error`	#cd262f
`--tanrei-comp-field-standard-error-counter-color`	`sys.color.on-surface-variant`	#4b4b4b
`--tanrei-comp-field-standard-error-label-icon-color`	`sys.color.on-surface-variant`	#4b4b4b
`--tanrei-comp-field-standard-error-label-color`	`sys.color.on-surface`	#1b1b1b
`--tanrei-comp-field-standard-error-required-asterisk-color`	`sys.color.primary`	#1b1b1b
`--tanrei-comp-field-standard-error-supporting-text-color`	`sys.color.on-surface-variant`	#4b4b4b
`--tanrei-comp-field-standard-error-value-text-color`	`sys.color.on-surface-variant`	#4b4b4b
`--tanrei-comp-field-standard-focused-counter-color`	—	#4b4b4b
`--tanrei-comp-field-standard-focused-error-text-color`	—	#cd262f
`--tanrei-comp-field-standard-focused-error-counter-color`	—	#4b4b4b
`--tanrei-comp-field-standard-focused-error-label-icon-color`	—	#4b4b4b
`--tanrei-comp-field-standard-focused-error-label-color`	—	#1b1b1b
`--tanrei-comp-field-standard-focused-error-required-asterisk-color`	—	#1b1b1b
`--tanrei-comp-field-standard-focused-error-supporting-text-color`	—	#4b4b4b
`--tanrei-comp-field-standard-focused-error-value-text-color`	—	#4b4b4b
`--tanrei-comp-field-standard-focused-label-icon-color`	—	#4b4b4b
`--tanrei-comp-field-standard-focused-label-color`	—	#1b1b1b
`--tanrei-comp-field-standard-focused-required-asterisk-color`	—	#1b1b1b
`--tanrei-comp-field-standard-focused-supporting-text-color`	—	#4b4b4b
`--tanrei-comp-field-standard-focused-value-text-color`	—	#4b4b4b
`--tanrei-comp-field-standard-label-icon-color`	`sys.color.on-surface-variant`	#4b4b4b
`--tanrei-comp-field-standard-label-color`	`sys.color.on-surface`	#1b1b1b
`--tanrei-comp-field-standard-required-asterisk-color`	`sys.color.primary`	#1b1b1b
`--tanrei-comp-field-standard-supporting-text-color`	`sys.color.on-surface-variant`	#4b4b4b
`--tanrei-comp-field-standard-value-text-color`	`sys.color.on-surface-variant`	#4b4b4b
`--tanrei-comp-field-supporting-text-gap`	`sys.space.space50`	4px
`--tanrei-comp-field-value-text-gap`	`sys.space.space200`	16px
`--tanrei-comp-field-label-typescale`	`sys.typescale.label`	500 14px/1.4286
`--tanrei-comp-field-supporting-text-typescale`	`sys.typescale.label-small`	500 12px/1.3333
`--tanrei-comp-field-value-text-typescale`	`sys.typescale.label`	500 14px/1.4286

Fixtures

Representaciones canónicas. Todas las plataformas capturan cada fixture con el mismo identificador para poder comparar los resultados.

supporting

label: Verification code supportingText: Enter the 6-digit code we sent to your p… value: 123 groupSize: 3

error

label: Verification code supportingText: Enter the 6-digit code we sent to your p… errorText: That code is not right. Check the messag… error: true value: 123456 groupSize: 3

disabled

label: Verification code supportingText: Enter the 6-digit code we sent to your p… disabled: true value: 123456 groupSize: 3

required-rtl

label: رمز التحقق supportingText: أدخل الرمز المكوّن من 6 أرقام الذي أرسلن… required: true requiredText: مطلوب value: 123 groupSize: 3 direction: rtl

Generado a partir de specs/one-time-code-field.spec.json, tokens/comp/field.tokens.json, design/tokens/

Qué dibuja la web de otra manera

El shadow root del elemento contiene un <tanrei-field> con un <tanrei-one-time-code-input> dentro, y nada más. Importar el elemento define ambos.
El elemento está asociado a formularios. Recibe name y form, envía solo el código —nada mientras está deshabilitado—, se restablece al valor del atributo value, sigue a un <fieldset> deshabilitado y notifica que falta un valor mientras required está activado y está vacío. Sus dos miembros no añaden ninguna entrada al formulario. Enter en las celdas pulsa el botón predeterminado del formulario del elemento; cancela action para impedirlo.
input, change, complete y action son los CustomEvents de la entrada de código de un solo uso, con detail.value. Su destino es el elemento, y event.target.value es el código en todos los listeners.
Partes: field y one-time-code-input son los dos miembros. Sus propias partes tienen aquí los mismos nombres que un nivel más abajo: label, label-icon, requirement-label, supporting-text; input, cell, character, caret, separator.
El elemento no puede recibir el foco por sí mismo: focus() va a las celdas, y un <label for> propio de la página lleva el foco allí. autofocus en el elemento da el foco a las celdas cuando se dibuja por primera vez, salvo que otra cosa tenga el foco.
El elemento no tiene rol. Dale nombre con label —con label-hidden donde la etiqueta se dibuja en otro lugar— y nunca con aria-label, que aquí no nombra nada.
Los atributos son los de los propios miembros: label-hidden, supporting-text, error-text, required-mark, required-text, optional-text, group-size, readonly.
Tiene un solo slot, label-icon. Un segundo control colocado dentro no se dibuja.
Antes de que el elemento esté definido no tiene tamaño y solo muestra un hijo label-icon. Ocúltalo con tanrei-one-time-code-field:not(:defined) > * y reserva la altura. Una página que deba funcionar sin script usa un <label> alrededor de un <input autocomplete="one-time-code" inputmode="numeric"> sencillo, con su ayuda al lado.

Pautas

Evita

No pongas un campo de código de un solo uso dentro de un campo. Ya es un campo; una compilación de depuración lo notifica.
No le des nombre con aria-label. Donde no deba dibujarse ninguna etiqueta, da label y labelHidden.
No impidas pegar, esté el código oculto o no, y no muevas el foco a otro lugar ni envíes el formulario sin avisar antes a la persona.
No uses mask por costumbre. Un código que se usa una vez y caduca rara vez necesita ocultarse, y ocultarlo hace que un error sea más difícil de ver.
No cambies el estilo de las celdas solo para este campo copiándolas. Define en el campo el token del miembro.

Accesibilidad

Rol: textbox
Etiquetado: One text box, the One-time-code input's (OTC-2); the frame has no role. Its accessible name is label, drawn or not (labelHidden), and its description is the supporting text with, in error, the error text after it, with optionalText while optional is true (FLD-10, FLD-11, OTC-22). It is exposed as invalid while error is true, required while required is true, disabled while disabled is true, read-only while readOnly is true, and as a protected text entry while mask is true. The label's drawn text, the requirement mark, the cells, the caret and the group marks are not exposed a second time (FLD-11, OTC-2).
Objetivo mínimo: El área de pulsación cumple el tamaño mínimo de objetivo aunque el tamaño visual sea menor. minimum 32px · pointer 44px · spacing 8px · touch 48px

Teclado

Teclas	Acción
`Tab / Shift+Tab`	Moves focus to the control and on from it: the one-time-code field is one stop, its control's, and adds none (OTF-5).
`Every other key`	The One-time-code input's own, as its spec's keyboard table says (OTC-6, OTC-8 to OTC-11, OTC-13). The one-time-code field handles no key.

Notas

What the one-time-code field adds to its members is their being one thing: one tag or one call, one set of props, one value and one entry in a form (OTF-2 to OTF-4). The tie between the two — the name, the description, required, invalid, disabled — is not the one-time-code field's: it is what a Field gives any control it frames, and it runs here exactly as it runs in a product's own Field.
One level down: a Field with a One-time-code input in it, written by the product, is the same picture and the same text box, and the Field's fixtures code-supporting, code-error, code-disabled and code-required-rtl are this component's twins. A product drops to it for an arrangement the one-time-code field does not offer: something of its own inside the frame beside the cells (a resend control, a countdown), or the One-time-code input alone under a dialog's headline, named by its own label.
The members' notes hold as written and are not repeated: errors are words (the Field's); nothing happens by itself when the code is complete, and paste and the platform's autofill are never blocked (the One-time-code input's).
The hit area is the control's (OTC-25); the label widens where a press can land without widening what a press does (FLD-12).
Not pressable: a press focuses the control and is not an action (OTC-25), so BTN-8, BTN-9 and BTN-10 are not copied.
How a state looks is a value decision of the active design system; components read the state's tokens and never compute the effect themselves.

Generado a partir de specs/one-time-code-field.spec.json, tokens/sys/measure.tokens.json

De qué se encarga el componente

Es un solo cuadro de texto, el de la entrada de código de un solo uso. Su nombre es label, se dibuje o no; su descripción es el texto de apoyo o de error que se muestra, junto con el texto de opcional mientras el campo es opcional.
Se expone como no válido mientras error es true, como obligatorio mientras required está activado, como deshabilitado mientras disabled es true, como de solo lectura mientras readOnly es true y como un campo de contraseña mientras mask es true.
El nombre, la descripción y los estados se vinculan exactamente como un campo los vincula a cualquier control que enmarca. El campo escrito a mano, un nivel más abajo, es el mismo cuadro de texto.
La etiqueta dibujada, la marca de obligatoriedad, las celdas, el cursor de texto y las marcas de grupo no se exponen una segunda vez.
Es una sola parada para la tecla Tab. Una pulsación en la etiqueta lleva el foco a las celdas y no acciona nada; una pulsación en la ayuda no hace nada.
Un error que aparece mientras el foco está en el campo de código de un solo uso lo anuncia una vez, de forma cortés, su miembro campo.
La dirección, el texto ampliado y los colores forzados son la respuesta propia de cada miembro: en un diseño de derecha a izquierda, el marco se refleja y las celdas siguen siendo una serie de izquierda a derecha en el borde de inicio; con el texto al 200%, nada se corta y nada se desplaza hacia los lados.
No incluye textos propios. Si requiredText y optionalText se dejan vacíos, el campo los lee de los textos del producto.

Las carencias conocidas en la web son las de sus miembros: lo que dicen los lectores de pantalla mientras se escribe un código se ha leído en los árboles de accesibilidad de los navegadores, no se ha oído con un lector de pantalla, y antes de que el elemento esté definido no se dibuja nada.

Qué debes hacer tú

Da label, siempre, con las palabras que una persona usaría para el código.
Di con palabras qué se espera: cuántos caracteres, y adónde se envió el código. Las celdas muestran la longitud solo a quienes las ven.
Di que un código es incorrecto, que ha caducado o que es obligatorio con errorText, supportingText y required. El color nunca es la única señal.
Donde el tiempo para introducir un código sea limitado, dilo, y deja que la persona pida más tiempo o un código nuevo.

Código fuente e incidencias en GitHub