数値フィールド

カテゴリ: テキスト入力
トークン: comp.field
レベル: 合成
構成要素: Field, Number input

概要

Web: tanrei-number-field; schedule
SwiftUI: TanreiNumberField; radio_button_unchecked
Jetpack Compose: TanreiNumberField; radio_button_unchecked
Flutter: TanreiNumberField; radio_button_unchecked
React Native: NumberField; radio_button_unchecked

提供しないバリアント: tanrei: filled, outlined

生成元 docs/status/status.json, specs/number-field.spec.json

単位と範囲のある数値フィールドと、金額を持つ数値フィールド

数値フィールドは、プロダクトが数値として読む数に使います。数量、サイズ、パーセント、金額などです。ユーザーは自分のロケールの書き方で入力するか、矢印キーやフィールドの末尾側にある 2 つのボタンで増減します。フィールドは、同じバリアントとサイズのテキストフィールドと同じ見た目と寸法です。

構成要素は、フィールドと数値入力欄です。フィールドは枠で、ラベル、必須または任意の印、補足、エラーを受け持ちます。数値入力欄はコントロールで、ボックス、数値、単位、2 つのステッパーを受け持ちます。数値フィールドは自分では何も描かず、自分のトークンも持ちません。数値フィールドのプロパティはどれも 2 つのどちらかのプロパティで、そのまま渡されます。

数値フィールドは、すでにフィールドです。フィールドの中には入れません。スライダーの横やテーブルのセルのように、ラベルがほかの場所にあるところでは、数値入力欄を単独で使います。

置かれた場所の幅いっぱいに広がるブロックで、ボックスもその幅いっぱいになります。自分の幅は持ちません。フィールドを狭くするには、置く場所を狭くします。

Web では <tanrei-number-field> です。ほかのプラットフォームはまだ実装していません。

使い方

value は数値で、フィールドが数値を持たない間は null です。値が変わるのは、ユーザーが確定したときです。フォーカスがフィールドを離れたとき、Enter を押したとき、増減したときで、キーを打つたびには変わりません。入力している間、テキストはユーザーのものです。拒否も、書き直しも、範囲への丸めも、桁の丸めもしません。その間にテキストが表す数は、input が運びます。

<form>
  <tanrei-number-field name="quantity" label="数量" value="1" min="1" max="99"
    required required-text="必須" invalid-text="数値を入力してください。"
    increment-label="増やす" decrement-label="減らす"></tanrei-number-field>
</form>

<!-- 単位があり、0.25 刻みで、上限はありません。 -->
<tanrei-number-field id="radius" label="角の半径" value="8" min="0" step="0.25" suffix-text="px"
  increment-label="増やす" decrement-label="減らす"></tanrei-number-field>

<!-- 金額。前に記号、後ろにコード、小数は常に 2 桁です。 -->
<tanrei-number-field label="金額" value="120" prefix-text="$" suffix-text="USD"
  min-fraction-digits="2" max-fraction-digits="2"
  increment-label="増やす" decrement-label="減らす"></tanrei-number-field>

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

  const radius = document.querySelector('#radius');
  // 確定によって値が変わりました。value はすでに新しい値で、数値か null です。
  radius.addEventListener('change', () => save(radius.value));
  // ユーザーが入力または増減しています。テキストが表す数で、範囲にも桁にも丸めていません。数でなければ null です。
  radius.addEventListener('input', (e) => preview(e.detail.value));
  // 数ではないテキストが確定されました。フィールドはテキストを残し、invalidText を表示します。
  // detail.text はそのテキストで、フィールドに与えられていなければ空です。
  radius.addEventListener('entryerror', (e) => console.log(e.detail.reason, e.detail.text));
</script>

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

<NumberField label="角の半径" value={radius} min={0} step={0.25} suffixText="px"
  incrementLabel="増やす" decrementLabel="減らす"
  onChange={(event) => setRadius(event.currentTarget.value)} />

1 つ下の階層

同じフィールドを 2 つの構成要素から自分で書いても、見た目は同じで、支援技術にとっても、同じ名前、説明、状態を持つ同じスピンボタンになります。

<tanrei-field label="数量" required required-text="必須"
  supporting-text="1 回の注文は 99 個までです。">
  <tanrei-number-input name="quantity" min="1" max="99" invalid-text="数値を入力してください。"
    increment-label="増やす" decrement-label="減らす"></tanrei-number-input>
</tanrei-field>

同じフィールドを自分で書いたもの。フィールドの中に数値入力欄があります

数値フィールドにない並べ方が必要なときに、1 つ下の階層で書きます。

必要なもの	使うもの
ラベル、ボックス、補足、エラー	数値フィールド
枠の中、ボックスの横か下に置く自分の要素	フィールドに、数値入力欄と自分の要素を入れる
ボックスだけ。ラベルは別の場所にある（スライダーの横、テーブルのセル、ツールバー）	数値入力欄を単独で使い、入力欄の `label` で名前を付ける

1 つ下の階層で変わるのは、何をどこに指定するかです。name、value、範囲、単位は数値入力欄に指定し、フォームに加わるコントロールもイベントが届く先も入力欄になります。label、error、disabled、必須の指定はフィールドに指定したままにします。フィールドがコントロールに伝えるので、入力欄の側には指定しません。数値フィールドが行い、フィールドと数値入力欄を自分で書いたものが行わないことはありません。

仕様

上限で無効になったステッパー、末尾側にそろえた数字、ステッパーなし、エラー、読み取り専用、無効の数値フィールド

フィールド

パーツ	内容
ラベル	フィールドのもの。コンテナの上（`stacked`）。`filled` と `outlined` では数値入力欄がボックスの中で浮き上がるラベルとして描き、フィールドはラベルの行を描きません。描いても `labelHidden` で隠しても、アクセシブルネームになります
必須・任意の印	フィールドのもの。ラベルの後ろ。`required` では必須のタグ、アスタリスク、または印なし。`optional` では任意のタグ。浮き上がるラベルにはアスタリスクが付きます
入力欄	数値入力欄のもの。テキストとしての数値。編集中はユーザーが入力したもの、それ以外は確定した数値をロケールの書き方で示します。1 行で、収まらない分はスクロールします
プレフィックス、サフィックス	数値入力欄のもの。数値の前後に置く決まったテキスト。通貨記号や単位です。ボックスの一部で、値には含まれません
ステッパー	数値入力欄のもの。末尾側にある 2 つのボタン。1 つ目が減らし、2 つ目が増やします。`steppers` を false にすると付きません
補足テキスト	フィールドのもの。補足の 1 行。フィールドがエラーの間は、エラーテキストがその位置に代わって出ます（デザインシステムが両方を残す場合は、その下に）。`error` が true の間は `errorText`、テキストが数でない間は `invalidText` です。ステッパーがあってもなくても、ボックスのテキストのパディングの位置で始まり、同じ位置で終わります

3 つのバリアントと、3 つのサイズ small（32）、medium（40）、large（56）は、テキストフィールドのものです。既定のシステムが提供するのは stacked だけです。

数値フィールドに自分のトークンはありません。ボックスは数値入力欄のトークンを、行はフィールドのトークンを、2 つのステッパーはボタンのトークンを、どこで設定されていても読みます。1 つのインスタンスだけを変えるには、構成要素のトークンをその要素に設定します。style="--tanrei-comp-field-label-gap: 0.75rem" のようにします。

2 つのステッパーは、medium サイズのテキストボタンで、横に並びます。既定のシステムでは、フィールドの幅のうち 88 を使い、それぞれがタッチターゲットを満たします。小さく描くことも、縦に重ねることもしません。その幅を取れない行では、ステッパーをなくしてください。キーでは引き続き増減できます。

値とテキスト

いつ	起きること
ユーザーが入力、貼り付け、音声入力をする	何も変えません。`input` が、テキストが表す数か `null` を運びます
フォーカスが離れる、または Enter	テキストを確定します。`min` まで上げ、`max` まで下げ、`maxFractionDigits` の桁に丸めて値にし、ロケールの書き方で書き戻します。値が変わっていれば `change` を発火します
テキストが空	値は `null` になります
テキストが数ではない	テキストは残ります。値は `null` になり、フィールドはエラーになって `invalidText` を表示し（なければ `errorText`）、`entryerror` を発火します
プロダクトが `value` を設定する	入力されていた内容にかかわらず、その数値を表示します。イベントは発火せず、`min` と `max` による修正もしません

確定した数値は、ロケールの数字と小数点で、小数部を minFractionDigits 桁から maxFractionDigits 桁までにして書きます。桁区切りは付けません。表示されているものを、そのまま入力し直せるようにするためです。

同じ値 1.5 を、ドイツ語とエジプトのアラビア語で

テキストは、フィールドの locale に従って、寛容に読みます。locale が空のときは、ページの言語に従います。

数の前後と途中の空白は無視します。
数字の前のハイフンマイナス、マイナス記号、プラス記号は、符号として読みます。
ASCII の数字、ロケールの数字、全角の数字は、どれも数字として読みます。
数字の間にあるロケールの桁区切りは無視します。英語では 1,234.50 を 1234.5 と読みます。
一緒に入力または貼り付けたプレフィックスとサフィックスは無視します。12 px は 12 と読みます。
文字、指数、2 つの小数点、符号だけのテキストは、数ではありません。

フィールドは、2 つのロケールの書き方の間で推測しません。小数点がカンマのドイツ語では、1.500 を 1500、1.5 を 15 と読みます。

右から左のレイアウト：ラテン文字の単位は数値の後ろに左から右へ、ページ自身の文字の単位は数値の左に来ます

数値とその単位は、ひと続きのテキストです。プレフィックスは数値の前に、サフィックスは数値の後ろに、単位自身の文字の向きで書きます。ページの向きには左右されません。そのため「44 px」「$ 120 USD」「40 %」は、アラビア語やヘブライ語のページでも英語のページと同じ並びになり、アラビア文字やヘブライ文字で書いた単位は数値の左に来ます。ステッパーとラベルはページの向きに従います。align="end" は数値を単位の側に寄せます。ラテン文字や記号の単位なら、どちらの向きでも右です。ラテン文字の通貨コードを数値の左に置きたいときは、サフィックスの先頭に右から左への方向マーク（U+200F）を書きます。

増減

入力	起きること
上矢印、下矢印	`step` だけ増減します
Page Up、Page Down	`step` の 10 倍だけ増減します
ステッパーを押す	1 回増減します。押し続けると繰り返します。0.5 秒後から 1 秒に 10 回、その後は 1 秒に 20 回です
Home、End、左矢印、右矢印	テキストの中でキャレットを動かします
ホイール、ドラッグ	何も起きません。ページがスクロールします

増減は、min から（なければ 0 から）数えた step の目盛りの、次の数に進みます。step が 5 なら、12 は上に 15、下に 10 です。計算は 10 進で行うので、0.2 を 0.1 増やすと 0.3 になります。空のフィールドは、範囲が許す中で 0 に最も近い数になります。

step は、1 回の増減でどれだけ進むかです。入力できる数は制限しません。step が 5 でも、入力した 12 は 12 のままです。特定の数だけを受け付けるには、値を検証して error を設定してください。

スライダーと並べる

1 つの行見出しの下でスライダーの横に置く数値は、ボックスだけです。数値入力欄を単独で使い、入力欄の label で名前を付けます。サンプルは数値入力欄のページにあります。

構成要素

Web パッケージが描くフィクスチャ stacked-empty の上に描いています。

パーツ	説明
1 `field`	The Field: the label row with its glyph and its requirement mark, and the supporting row with the help and the error text. In a look whose input floats the label it draws no label row.
2 `number-input`	The number input, as the Field's one control: the box, the number in it, the prefix and the suffix, the two steppers, and the label that floats in the box in the looks that float one.

プロパティ

プロパティ	型	既定値	説明
`variant`	`stacked` \| `filled` \| `outlined`	`"stacked"`	The text input's three looks, so that a number input is drawn as the text inputs beside it: stacked is a filled box that shows focus and error with a line inside its edge and draws no label — the label of the Field that frames it stands above it; filled and outlined float the label inside the box. Use one style per form. A design system may leave some out (the Tanrei system ships stacked only) or add values. — Number input
`size`	`small` \| `medium` \| `large`	`"medium"`	Minimum height of the container: stacked 32 / 40 / 56, as tall as a Button of the same size, so that the box and a Button side by side in one row stand as tall as each other; filled and outlined 40 / 48 / 56, which hold the label that floats inside them. These are the text input's three sizes, small for a bar, a toolbar or a dense row of controls. The hit area always meets the minimum target. A design system may add values. — Number input
`value`	`number`	`null`	The committed number, or null (the platform's absent value) while the field holds none. It changes when the person commits — focus leaves, the action key, a step — not on every keystroke; input carries what is being typed. — Number input
`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 Names the number input. In a filled or outlined look the input draws it, floating in its box, and the Field draws no label row (FLD-25, NMI-8).
`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 Hides the label wherever it would be drawn: the Field's row, or the input's floating label (FLD-25). Where no message is shown either, the bare number input, named by its own label, is that control without a frame.
`placeholder`	`string`	`""`	A hint shown while the input is empty and the label is not in the input line. Never a replacement for a name. — Number input
`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 Field puts its number input in the input's own error condition (FLD-8, NMI-10); the steppers stay as they are.
`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 Field disables its number input, and with it both steppers (FLD-14, NMI-32); the number field is then left out of its form (NUM-48).
`readOnly`	`boolean`	`false`	The number can be focused, selected and copied, but not changed: no key steps it and no stepper is drawn. — Number input
`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 The Field exposes its number input as required (FLD-10, NMI-12).
`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
`min`	`number`	`null`	The lowest number a commit keeps; a lower one is raised to it. Null for no limit. It is also where the steps are counted from. — Number input
`max`	`number`	`null`	The highest number a commit keeps; a higher one is lowered to it. Null for no limit. — Number input
`step`	`number`	`1`	How far Up Arrow, Down Arrow and a stepper move the number; Page Up and Page Down move ten times as far. It does not limit what may be typed. — Number input
`steppers`	`boolean`	`true`	Draws the two stepper buttons at the end of the field. False for a field in a row too narrow for them, or beside a slider that does their work; the keys still step. — Number input
`incrementLabel`	`string`	`""`	The accessible name of the stepper that steps up, in the product's language ("Increase"). The product's: Tanrei has no word for it. Empty reads the product's words. Required while the steppers are shown. — Number input
`decrementLabel`	`string`	`""`	The accessible name of the stepper that steps down, in the product's language ("Decrease"). The product's: Tanrei has no word for it. Empty reads the product's words. Required while the steppers are shown. — Number input
`prefixText`	`string`	`""`	Fixed text before the number, not part of the value: a currency sign ("$", "¥"). — Number input
`suffixText`	`string`	`""`	Fixed text after the number, not part of the value: the unit ("px", "ms", "%", "kg"). Read to assistive technology with the number. — Number input
`valueText`	`string`	`""`	The value as words ("12 pixels", "3 stars"), given to assistive technology in place of the number with its prefix and suffix. The same text a Slider beside the field takes as its valueText. — Number input
`align`	`start` \| `end`	`"start"`	Where the number stands in the input: at the start, as the text of every other field, or at the end, for a number in a column of numbers whose digits should line up. — Number input
`minFractionDigits`	`number`	`0`	The fewest digits shown after the decimal separator; zeros fill them (2 for an amount of money: "12.00"). — Number input
`maxFractionDigits`	`number`	`3`	The most digits kept after the decimal separator: a commit rounds to it. 0 makes the field hold whole numbers and asks for a keyboard without a separator. — Number input
`locale`	`string`	`""`	A BCP 47 language tag ("en-US", "de-DE", "ar-EG") for how the number is shown and read: its digits and its decimal separator. Empty uses the platform's current locale. The value itself is a number in every locale. — Number input
`invalidText`	`string`	`""`	The words for an input committed with a text that is not a number ("Enter a number"): given to the Field that frames it, which shows them as its error text and, while they are empty, shows its own errorText (NMI-21, FLD-28). — Number input Shown by the Field, in its supporting row (FLD-28).

スロット

スロット	説明
`label-icon`	A glyph before the label. — Field

イベント

イベント	説明
`input`	The person changed the text, or a step changed the value; carries the number the text reads as — not clamped, not rounded — or the empty value while it reads as none. Emitted for every change, not when the product sets value. What a Slider beside the field follows. — Number input
`change`	A commit changed the value: focus left the field, the action key was pressed, a key or a stepper stepped it, or a held stepper was released; carries the value. — Number input
`action`	The person pressed the keyboard's action key (Enter, Return, Done). — Number input
`entryError`	The person committed a text that is not a number; carries the reason (invalid) and invalidText, the words the input has for it. The entry error itself is shown by the Field that frames the input (NMI-21). — Number input

状態

振る舞い

EARS 記法による要件です。各プラットフォームの実装は、この ID に対応するテストで検証されます。要件の原文は仕様ファイルのものをそのまま掲載しています。

ID	要件
`NUM-47`	THE number field SHALL be a Field that frames one number input, and nothing else. It SHALL give label, labelHidden, supportingText, errorText, error, disabled, required, optional, requiredMark, requiredText and optionalText to its Field and every other prop to its number input, each unchanged; SHALL hold the label-icon slot for its Field; and SHALL emit its number input's events as its own, each once. THE number field SHALL be as wide as the place it stands in, and its number input SHALL fill it: it is a block with no width of its own, as its Field is (FLD-1), around a control that fills the width it is given (NMI-36). It SHALL draw no part of its own, hold no state of its own and have no token of its own: what it shows, how it behaves and what it exposes to assistive technology SHALL be exactly what that Field and that number input do when a product places the one in the other (FLD-1 to FLD-28; NMI-1 to NMI-46) — the label row and its requirement mark (FLD-2 to FLD-6), or the label that floats in the box with the Field's row left out (FLD-25, NMI-7, NMI-8); the supporting row and the error (FLD-7 to FLD-9, FLD-26); the name, the description and the states (FLD-10, FLD-11, FLD-14, NMI-12, NMI-32); a text that is not a number shown as an error in the Field's row, in the input's words (FLD-28, NMI-21); and the two steppers, which are the number input's Buttons and stand inside its box (NMI-25).
`NUM-48`	WHERE the platform has forms (the web) THE number field SHALL be the one control the form sees: it SHALL take name, submit its number input's value as that input submits it — a decimal number with ASCII digits and a period, or an empty string WHILE it holds none (NMI-35) — reset to the value it was first given, restore it on navigation, report to the form's constraint validation exactly what its number input would report there (a missing value WHILE required is true and it holds none, NMI-12; a bad input WHILE an entry error lasts, NMI-21), and be left out WHILE disabled is true or a disabled group of the form holds it; its number input and its Field SHALL take no part in the form themselves. WHEN the action key asks for the form's submission (NMI-20) the form asked SHALL be the number field's own.
`NUM-49`	WHEN the number field is given focus — by the product, by a press on any part of it that FLD-12 or NMI-14 gives to the input, or by a form that reports its validity — THE number field SHALL pass the focus to its number input and SHALL add no stop to the focus order: it has one stop, its input, and the steppers are none (NMI-25). A press on a stepper SHALL step and move no focus, in the number field as in the bare input (NMI-26). WHILE focus is inside it THE number field SHALL count as focused for its Field (FLD-13).
`NUM-50`	IF the number field is placed in a Field THE number field SHALL in debug builds report that it is a field already and that the bare control is the number input, and both SHALL still render (FLD-15). WHILE it stands in a field group THE number field SHALL follow that group's disabled, through its own Field, and take nothing else from the group (FGR-14).
`NUM-51`	THE number field SHALL have no words of its own and SHALL read none: requiredText and optionalText are read by its Field (FLD-24), incrementLabel and decrementLabel by its number input (NMI-44), each from the instance's prop and then from the product's words.
`NUM-52`	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 number 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 number field is invalid — except those the number field owns (aria-label, aria-labelledby, aria-disabled), which it SHALL move and not expose: its name is label (NUM-47). 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 number field SHALL take it off that element. WHEN the product sets an aria- attribute the number field owns THE number field SHALL report it in debug builds.

プラットフォーム別の名前対応

パリティは API が同一であることを意味しません。同じ契約を、各プラットフォームの流儀で表現します。

仕様	Web	SwiftUI	Jetpack Compose	Flutter	React Native
コンポーネント	`tanrei-number-field`	`TanreiNumberField`	`TanreiNumberField`	`TanreiNumberField`	`NumberField`
`variant` · プロパティ	`variant`	`variant`	`variant`	`variant`	`variant`
`size` · プロパティ	`size`	`size`	`size`	`size`	`size`
`value` · プロパティ	`value`	`value`	`value`	`value`	`value`
`label` · プロパティ	`label`	`label`	`label`	`labelText`	`label`
`labelHidden` · プロパティ	`labelHidden`	`labelsHidden`	`labelHidden`	`labelHidden`	`labelHidden`
`placeholder` · プロパティ	`placeholder`	`prompt`	`placeholder`	`hintText`	`placeholder`
`supportingText` · プロパティ	`supportingText`	`supportingText`	`supportingText`	`helperText`	`supportingText`
`errorText` · プロパティ	`errorText`	`errorText`	`errorText`	`errorText`	`errorText`
`error` · プロパティ	`error`	`error`	`isError`	`isError`	`error`
`disabled` · プロパティ	`disabled`	`disabled`	`enabled`	`enabled`	`disabled`
`readOnly` · プロパティ	`readOnly`	`readOnly`	`readOnly`	`readOnly`	`readOnly`
`required` · プロパティ	`required`	`isRequired`	`required`	`required`	`required`
`optional` · プロパティ	`optional`	`isOptional`	`optional`	`optional`	`optional`
`requiredMark` · プロパティ	`requiredMark`	`requiredMark`	`requiredMark`	`requiredMark`	`requiredMark`
`requiredText` · プロパティ	`requiredText`	`requiredText`	`requiredText`	`requiredText`	`requiredText`
`optionalText` · プロパティ	`optionalText`	`optionalText`	`optionalText`	`optionalText`	`optionalText`
`min` · プロパティ	`min`	`in`	`min`	`min`	`min`
`max` · プロパティ	`max`	`in`	`max`	`max`	`max`
`step` · プロパティ	`step`	`step`	`step`	`step`	`step`
`steppers` · プロパティ	`noSteppers`	`steppers`	`steppers`	`steppers`	`steppers`
`incrementLabel` · プロパティ	`incrementLabel`	`incrementLabel`	`incrementContentDescription`	`incrementSemanticLabel`	`incrementAccessibilityLabel`
`decrementLabel` · プロパティ	`decrementLabel`	`decrementLabel`	`decrementContentDescription`	`decrementSemanticLabel`	`decrementAccessibilityLabel`
`prefixText` · プロパティ	`prefixText`	`prefix`	`prefix`	`prefixText`	`prefix`
`suffixText` · プロパティ	`suffixText`	`suffix`	`suffix`	`suffixText`	`suffix`
`valueText` · プロパティ	`valueText`	`valueText`	`stateDescription`	`semanticValue`	`valueText`
`align` · プロパティ	`align`	`align`	`align`	`align`	`align`
`minFractionDigits` · プロパティ	`minFractionDigits`	`minFractionDigits`	`minFractionDigits`	`minFractionDigits`	`minFractionDigits`
`maxFractionDigits` · プロパティ	`maxFractionDigits`	`maxFractionDigits`	`maxFractionDigits`	`maxFractionDigits`	`maxFractionDigits`
`locale` · プロパティ	`locale`	`locale`	`locale`	`locale`	`locale`
`invalidText` · プロパティ	`invalidText`	`invalidText`	`invalidText`	`invalidText`	`invalidText`
`input` · イベント	`input`	`onInput`	`onInput`	`onInput`	`onInput`
`change` · イベント	`change`	`value`	`onValueChange`	`onChanged`	`onValueChange`
`action` · イベント	`action`	`onSubmit`	`keyboardActions`	`onSubmitted`	`onSubmitEditing`
`entryError` · イベント	`entryerror`	`onEntryError`	`onEntryError`	`onEntryError`	`onEntryError`
備考	The tag is `tanrei-number-field`, the class `TanreiNumberField`, the React name `NumberField`. Members: `<tanrei-field>` holding one `<tanrei-number-input>` in its default slot; the product places none. The host is `display: block`, as the Field is, so a number field is as wide as its place and its input fills it (NUM-47, NMI-36). Value member: `tanrei-number-input`. The host is the form's element — `name`, the value and its state as the input gives them (the decimal string, or nothing while disabled), validity anchored on the input (`valueMissing`, `badInput`), reset to the `value` attribute, restore, `form`, a disabled fieldset — and the input inside has no `name`. The `value` property is `number \| null` and the attribute a decimal string, declared as the member declares them. Props, set as properties on the member each is from. On the Field: `label`, `labelHidden`, `supportingText`, `errorText`, `error`, `disabled`, `required`, `optional`, `requiredMark`, `requiredText`, `optionalText`. On the number input: `variant`, `size`, `value`, `placeholder`, `readOnly`, `min`, `max`, `step`, `noSteppers` (the inverse of `steppers`, attribute `no-steppers`), `incrementLabel`, `decrementLabel`, `prefixText`, `suffixText`, `valueText`, `align`, `minFractionDigits`, `maxFractionDigits`, `locale`, `invalidText`. Attributes are the members' own: kebab-case, except `readonly`, `min`, `max` and `step`. Props of one name on both members — `label`, `labelHidden`, `error`, `disabled` — are the Field's; the input's are never set by the element and reach the input through the connection. Events: `input`, `change`, `action` and `entryerror` are the number input's own composed events and leave by themselves, with the host as their target and `value` already new at `change`; `action` stays cancelable. None is stopped and none is copied; a stepper's own `click` is the Button's and is not an event of the spec. Slots: `label-icon` is passed to the Field by a slot element of the same name, rendered only while the host has a child for it. The element has no other slot: the steppers are the input's own Buttons, not the product's children. Parts: the member hosts are `field` and `number-input`. Exported from the Field: `label`, `label-icon`, `requirement-label`, `supporting-text`. Exported from the number input: `container`, `outline`, `active-indicator`, `label`, `requirement-label`, `input`, `prefix`, `suffix`, `stepper`. Two names collide, `label` and `requirement-label`. Each is exported with its member's name before it, always (`field-label`, `number-input-label`, `field-requirement-label`, `number-input-requirement-label`), and under the bare name from both members as well, because the two are one thing to a person and are never drawn at once: FLD-25 is the sentence that holds it. `stepper` is a part of a member's small part: the number input exports the two Buttons' hosts under that name, and nothing of the Button's inside is exported. Focus: the shadow root does not delegate. `focus()` and `blur()` call the number input's; a press on the label row focuses the input by FLD-12, a press on the box by NMI-14, a press on a stepper steps and moves no focus (NMI-26), and a press on the help does nothing. The connection is the Field's with its control (FLD-25, FLD-26, FLD-28; NMI-45); the element takes no part in it. Parts and tokens of its own: none. The element writes no custom property: `--tanrei-comp-field-`, `--tanrei-comp-input-box-`, `--tanrei-comp-number-input-` and, for the steppers, `--tanrei-comp-button-` reach the members by inheritance, and one number field is set apart by setting any of them on the element. What its twin cannot do that it does: nothing. The twin: `<tanrei-field label="Quantity" supporting-text="Up to 99 per order." required><tanrei-number-input name="quantity" min="1" max="99" increment-label="Increase" decrement-label="Decrease"></tanrei-number-input></tanrei-field>`. Words: none of its own (NUM-51).	Not built on this platform yet: the number input as a view of its own, and this as the Field around it. Its name, its props and its idiom: `TanreiNumberField("Quantity", value: $quantity, in: 1...99, step: 1)`, shaped as the platform's own pair, `TextField(_:value:format:)` and `Stepper(value:in:step:)`: `value` is a `Binding<Double?>` (and an overload for `Binding<Int?>`, which sets `maxFractionDigits` to 0), written on every commit, which is the change event; `min` and `max` are one optional `ClosedRange` or partial range. Built on `TextField` with `.keyboardType(.decimalPad)` (`.numbersAndPunctuation` where a minus sign is needed) and a `FormatStyle` from `locale`. `labelHidden` follows `.labelsHidden()`, `disabled` follows `.disabled(_:)`, `action` is `onSubmit:`. The field carries `.accessibilityAdjustableAction` for increment and decrement and `.accessibilityValue` with the value text; the steppers are `TanreiButton`s with `.focusable(false)`. The drawing is Tanrei's on every Apple platform; `Stepper` itself is not used to draw. The product's words are read from the `\.tanreiWords` environment value.	Not built on this platform yet: the number input as a view of its own, and this as the Field around it. Its name, its props and its idiom: Compose idiom, as `TextField`: `TanreiNumberField(value: Double?, onValueChange: (Double?) -> Unit, label = "Quantity", min = 1.0, max = 99.0)`; the caller keeps `value` (state hoisting) and `onValueChange` is called on a commit, `onInput` while typing. `enabled` is the inverse flag and `isError`, `readOnly`, `prefix` and `suffix` keep Compose's names. Built on `BasicTextField` with `KeyboardOptions(keyboardType = KeyboardType.Decimal)` (`Number` while `maxFractionDigits` is 0) and `java.text.DecimalFormat` for `locale`. Semantics: `Role` has no spin button, so the field sets `stateDescription` (the value text), `ProgressBarRangeInfo` for the limits and `setProgress`, plus custom accessibility actions for increase and decrease; the steppers are `TanreiButton`s with `Modifier.focusProperties { canFocus = false }`. A held stepper repeats from `pointerInput` with the component's own timings. The product's words are read from `LocalTanreiWords`.	Not built on this platform yet: the number input as a view of its own, and this as the Field around it. Its name, its props and its idiom: Flutter idiom, as `TextField` and `InputDecoration`: `TanreiNumberField(value: 12, onChanged: (num? v) {…}, labelText: 'Quantity', min: 1, max: 99)`, with `hintText`, `helperText`, `errorText`, `prefixText`, `suffixText` and `enabled` keeping `InputDecoration`'s names, `enabled` the inverse flag. `TanreiNumberFormField` wraps it as a `FormField<num?>` (`validator`, `onSaved`, `autovalidateMode`). Built on `TextField` with `TextInputType.numberWithOptions(decimal:, signed:)` and no input formatter that refuses characters (NMI-16); formatting and parsing use `NumberFormat` from the `intl` package with `locale`. `Semantics(value:, increasedValue:, decreasedValue:, onIncrease:, onDecrease:)` makes it adjustable; the steppers are `TanreiButton`s with `canRequestFocus: false`. Tabular figures are `FontFeature.tabularFigures()`. The product's words are read from the `TanreiWords` inherited widget, which the app fills from its own localizations.	Not built on this platform yet: the number input as a view of its own, and this as the Field around it. Its name, its props and its idiom: React Native idiom, as `TextInput`: `<NumberField label="Quantity" value={quantity} onValueChange={setQuantity} min={1} max={99} />` with `value: number \| null`. Built on `TextInput` with `inputMode="decimal"` (`"numeric"` while `maxFractionDigits` is 0; `keyboardType="numbers-and-punctuation"` on iOS where a minus sign is needed, because its decimal pad has none). `accessibilityRole="adjustable"`, `accessibilityValue={{ min, max, now, text }}` and `accessibilityActions` increment and decrement with `onAccessibilityAction`; the steppers are `Button`s with `focusable={false}`. Formatting uses `Intl.NumberFormat` where the engine has it (Hermes does) and falls back to ASCII digits with the locale's separator. `fontVariant: ['tabular-nums']`. Follows the app's direction where an ancestor's is not known. The product's words are read from the `TanreiWordsProvider` context.

トークン

トークン	参照先	解決値（ライト）
`--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

フィクスチャ

基準となる描画パターンです。全プラットフォームが同じ ID でスナップショットを撮り、結果を比較できるようにしています。

`variant: stacked` (38)

stacked-empty

variant: stacked label: Quantity incrementLabel: Increase decrementLabel: Decrease

stacked-value

variant: stacked value: 12 label: Quantity incrementLabel: Increase decrementLabel: Decrease

stacked-placeholder

variant: stacked label: Quantity placeholder: 1 to 99 incrementLabel: Increase decrementLabel: Decrease

stacked-large

variant: stacked size: large value: 12 label: Quantity incrementLabel: Increase decrementLabel: Decrease

stacked-label-hidden

variant: stacked value: 12 label: Quantity labelHidden: true incrementLabel: Increase decrementLabel: Decrease

stacked-supporting

variant: stacked value: 12 label: Quantity supportingText: Up to 99 per order. incrementLabel: Increase decrementLabel: Decrease

stacked-error

variant: stacked value: 0 label: Quantity supportingText: Up to 99 per order. errorText: Order at least 1. error: true incrementLabel: Increase decrementLabel: Decrease

stacked-disabled

variant: stacked value: 12 label: Quantity disabled: true incrementLabel: Increase decrementLabel: Decrease

stacked-read-only

variant: stacked value: 12 label: Quantity readOnly: true

stacked-at-min

variant: stacked value: 1 label: Quantity min: 1 max: 99 incrementLabel: Increase decrementLabel: Decrease

stacked-at-max

variant: stacked value: 99 label: Quantity min: 1 max: 99 incrementLabel: Increase decrementLabel: Decrease

stacked-no-steppers

variant: stacked value: 12 label: Quantity steppers: false

stacked-unit

variant: stacked value: 8 label: Corner radius min: 0 step: 0.25 incrementLabel: Increase decrementLabel: Decrease suffixText: px

stacked-percent

variant: stacked value: 40 label: Opacity min: 0 max: 100 incrementLabel: Increase decrementLabel: Decrease suffixText: %

stacked-prefix

variant: stacked value: 120 label: Amount incrementLabel: Increase decrementLabel: Decrease prefixText: $ suffixText: USD minFractionDigits: 2 maxFractionDigits: 2

stacked-negative-decimal

variant: stacked value: -0.25 label: Letter spacing step: 0.01 incrementLabel: Increase decrementLabel: Decrease suffixText: px

stacked-align-end

variant: stacked value: 40 label: Tone min: 0 max: 100 incrementLabel: Increase decrementLabel: Decrease align: end

stacked-long-number

variant: stacked value: 8336817000 label: Population steppers: false

stacked-label-icon

variant: stacked value: 200 label: Duration incrementLabel: Increase decrementLabel: Decrease suffixText: ms slots: label-icon

stacked-required

variant: stacked label: Quantity required: true requiredText: Required incrementLabel: Increase decrementLabel: Decrease

stacked-optional

variant: stacked label: Quantity optional: true optionalText: Optional incrementLabel: Increase decrementLabel: Decrease

stacked-required-asterisk

variant: stacked label: Quantity required: true requiredMark: asterisk incrementLabel: Increase decrementLabel: Decrease

stacked-required-error

variant: stacked label: Quantity errorText: Enter how many you need. error: true required: true requiredText: Required incrementLabel: Increase decrementLabel: Decrease

stacked-required-disabled

variant: stacked value: 12 label: Quantity disabled: true required: true requiredText: Required incrementLabel: Increase decrementLabel: Decrease

stacked-required-label-icon

variant: stacked value: 200 label: Duration required: true requiredText: Required incrementLabel: Increase decrementLabel: Decrease suffixText: ms slots: label-icon

stacked-required-ja

variant: stacked value: 12 label: 数量 required: true requiredText: 必須 incrementLabel: 増やす decrementLabel: 減らす suffixText: 個

stacked-optional-ja

variant: stacked label: 数量 supportingText: 1 回の注文で 99 個まで。 optional: true optionalText: 任意 incrementLabel: 増やす decrementLabel: 減らす

stacked-locale-de

variant: stacked value: 1.5 label: Gewicht step: 0.1 incrementLabel: Erhöhen decrementLabel: Verringern suffixText: kg locale: de-DE

stacked-locale-ar

variant: stacked value: 12 label: الكمية incrementLabel: زيادة decrementLabel: إنقاص locale: ar-EG direction: rtl

stacked-required-rtl

variant: stacked value: 12 label: الكمية supportingText: حتى 99 لكل طلب. required: true requiredText: مطلوب incrementLabel: زيادة decrementLabel: إنقاص direction: rtl slots: label-icon

stacked-unit-rtl

variant: stacked value: -12.5 label: רוחב incrementLabel: הגדלה decrementLabel: הקטנה suffixText: px direction: rtl

stacked-error-rtl

variant: stacked value: 0 label: כמות errorText: יש להזמין לפחות 1. error: true optional: true optionalText: רשות incrementLabel: הגדלה decrementLabel: הקטנה direction: rtl

long-label

variant: stacked value: 2 label: How many copies of the printed annual re… supportingText: Each copy is 180 pages; orders of more t… required: true requiredText: Required incrementLabel: Increase decrementLabel: Decrease

beside-slider

variant: stacked value: 1.5 label: Scale labelHidden: true min: 0.25 max: 4 step: 0.05 steppers: false suffixText: × valueText: 1.5 times align: end

stacked-unit-own-script-rtl

variant: stacked value: 12 label: الوزن min: 0 step: 0.5 incrementLabel: زيادة decrementLabel: إنقاص suffixText: كغم direction: rtl

stacked-prefix-rtl

variant: stacked value: 120 label: المبلغ incrementLabel: زيادة decrementLabel: إنقاص prefixText: $ suffixText: USD minFractionDigits: 2 maxFractionDigits: 2 direction: rtl

stacked-percent-rtl

variant: stacked value: 40 label: العتامة min: 0 max: 100 incrementLabel: زيادة decrementLabel: إنقاص suffixText: % direction: rtl

stacked-align-end-unit-rtl

variant: stacked value: 44 label: גודל steppers: false suffixText: px align: end direction: rtl

`variant: filled` (6)

filled-empty

variant: filled label: Quantity incrementLabel: Increase decrementLabel: Decrease

filled-value

variant: filled value: 12 label: Quantity incrementLabel: Increase decrementLabel: Decrease

filled-large

variant: filled size: large value: 12 label: Quantity incrementLabel: Increase decrementLabel: Decrease

filled-error

variant: filled value: 0 label: Quantity errorText: Order at least 1. error: true incrementLabel: Increase decrementLabel: Decrease

filled-disabled

variant: filled value: 12 label: Quantity disabled: true incrementLabel: Increase decrementLabel: Decrease

filled-unit

variant: filled value: 8 label: Corner radius incrementLabel: Increase decrementLabel: Decrease suffixText: px

`variant: outlined` (6)

outlined-empty

variant: outlined label: Quantity incrementLabel: Increase decrementLabel: Decrease

outlined-value

variant: outlined value: 12 label: Quantity incrementLabel: Increase decrementLabel: Decrease

outlined-large

variant: outlined size: large value: 12 label: Quantity incrementLabel: Increase decrementLabel: Decrease

outlined-error

variant: outlined value: 0 label: Quantity errorText: Order at least 1. error: true incrementLabel: Increase decrementLabel: Decrease

outlined-disabled

variant: outlined value: 12 label: Quantity disabled: true incrementLabel: Increase decrementLabel: Decrease

outlined-required

variant: outlined label: Quantity required: true requiredText: Required incrementLabel: Increase decrementLabel: Decrease

生成元 specs/number-field.spec.json, tokens/comp/field.tokens.json, design/tokens/

Web での描き方の違い

要素のシャドウルートには <tanrei-field> があり、その中に <tanrei-number-input> があります。数値フィールドをインポートすると、どちらも定義されます。
数値フィールドは、フォームに関連付けられる要素で、フォームに加わるコントロールはこの要素だけです。name を受け取り、ロケールの表示にかかわらず、値を素の 10 進数（12.5）として送信します。リセットでは value 属性に戻ります。required で値がない間は値の欠落を、テキストが数でない間は不正な入力を、フォームに報告します。
置かれた場所の幅いっぱいに広がるブロックです。幅を与えない場所では、長いラベルがあるとボックスより広くなります。そこでは幅を与えてください。
パーツは構成要素のもので、名前も同じです。フィールドからは label、label-icon、requirement-label、supporting-text、数値入力欄からは container、outline、active-indicator、input、prefix、suffix、stepper です。label と requirement-label は、2 つのうち描かれているほうに届きます。field-label と number-input-label は、どちらか一方に届きます。2 つの構成要素は、パーツ field と number-input です。
entryerror の detail.text は入力欄の invalidText で、与えられていなければ空です。detail の型は数値入力欄のもので、TanreiNumberInputInputDetail と TanreiNumberInputEntryErrorDetail です。
steppers は逆の属性 no-steppers で、readOnly は readonly です。
input は detail.value を持つ CustomEvent です。change と action はただのイベントなので、value は要素から読みます。action をキャンセルしなければ、続けてフォームに送信を求めます。
locale がなければ、最も近い lang 属性、次にブラウザーの言語を読みます。
ロケールの小数点に加えて、桁区切りにピリオドを使わないロケールでは、ピリオドも小数点として読みます。
ページキーは、スライダーと同じく、step の目盛りのまま 10 個分進みます。step が 2 なら、42 からの Page Up は 62、次は 82 です。
iOS と iPadOS では、負の数を入力できる間、フィールドは通常のキーボードを求めます。小数用のキーパッドにマイナス記号がないためです。
要素が定義されるまでは、大きさがありません。高さを確保してください。

ガイドライン