الحقل

نظرة عامة

link

Web

tanrei-field

schedule

SwiftUI

TanreiField

radio_button_unchecked

Jetpack Compose

TanreiField

radio_button_unchecked

Flutter

TanreiField

radio_button_unchecked

React Native

Field

radio_button_unchecked

مولَّد من docs/status/status.json, specs/field.spec.json

شريط تمرير ومفتاح تبديل، يسمّي الحقل كلًّا منهما ويعطيه المساعدة والعلامة

حقل النص يستطيع أن يقول ما هو، وهل تجب الإجابة عنه، وكيف يُجاب عنه، ولماذا رُفضت إجابة. والحقل يعطي هذه الأربعة نفسها لعنصر تحكم لا يستطيعها: شريط تمرير، أو مفتاح تبديل، أو حقل إدخال النص، أو حقل إدخال اللون، أو حقل إدخال الرمز لمرة واحدة، أو عنصر تحكم بناه منتجك. وحقل النص نفسه حقل حول حقل إدخال النص. تقف التسمية فوق عنصر التحكم، والمساعدة تحته. وما دام الحقل في حالة خطأ يأخذ نص الخطأ مكان المساعدة، فلا يزيد ارتفاع النموذج في حالة الخطأ عنه في الراحة؛ ويستطيع نظام التصميم بدلًا من ذلك أن يُبقي المساعدة ويضيف نص الخطأ تحتها.

الحقل يرسم الإطار ولا شيء غيره. ليس له حاوية ولا قيمة ولا حدث، وعنصر التحكم يحتفظ بمظهره ومفاتيحه وأحداثه ومكانه في النموذج.

على الويب هو <tanrei-field>. والمنصات الأخرى لم تنفّذه بعد.

الاستخدام

link

<tanrei-field label="مستوى الصوت" supporting-text="ينطبق على التنبيهات والوسائط." optional optional-text="اختياري">
  <tanrei-slider name="volume" value="40"></tanrei-slider>
</tanrei-field>

<!-- المنتج هو الذي يتحقق؛ والحقل يعرض السبب ويعلّم عنصر التحكم بأنه غير صالح. -->
<tanrei-field label="مستوى الصوت" required required-text="مطلوب" error error-text="اختر مستوى أعلى من 0.">
  <tanrei-slider name="volume" value="0"></tanrei-slider>
</tanrei-field>

<!-- حقل إدخال النص: الحقل يسمّيه، ومساعدته تبدأ حيث يبدأ النص، ويرسم الحقل العدد الذي يُعطى له. -->
<tanrei-field label="اسم العرض" supporting-text="يظهر بجانب تعليقاتك." count-text="12/40">
  <tanrei-text-input name="display-name" value="Ada Lovelace" maxlength="40" counter></tanrei-text-input>
</tanrei-field>

<!-- عنصر تحكم يسمّي نفسه: اترك تسمية الحقل فارغة. -->
<tanrei-field supporting-text="يمكنك التراجع في أي وقت.">
  <tanrei-checkbox label="أوافق على شروط الاستخدام"></tanrei-checkbox>
</tanrei-field>

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

import { Field, Slider } from '@tanrei/react';

<Field label="مستوى الصوت" supportingText="ينطبق على التنبيهات والوسائط." error={tooQuiet} errorText="اختر مستوى أعلى من 0.">
  <Slider value={volume} onChange={(event) => setVolume(event.detail.value)} />
</Field>

المواصفات

link

علامات المطلوب والاختياري الثلاث، وخطأ، وحقل معطَّل، ورسم أيقونة للتسمية

volume_up

حقل إدخال النص داخل حقل: مع مساعدة وعدد، وفي حالة خطأ

مساعدة، وخطأ: يأخذ نص الخطأ مكان المساعدة

حول حقل إدخال النص

link

الحقل حول حقل إدخال النص هو حقل النص مكتوبًا باليد: الصورة نفسها والاسم والوصف والحالات. يقول حقل الإدخال لحقله ما لا يعرفه سواه، والحقل يتبعه:

ما يقوله حقل الإدخال	الحقل
كم يبعد نصه عن حافتيه: حشوه، وأيقونة في البداية	يبدأ صف النص المساعد وينهيه هناك، فتبدأ المساعدة حيث يبدأ النص
أنه يرسم التسمية بنفسه، عائمة في صندوق من الطراز filled أو outlined	لا يرسم صف التسمية ولا وسم المطلوب أو الاختياري، ويظل يسمّي حقل الإدخال. وحقل الإدخال المطلوب يأخذ نجمة بعد تسميته العائمة، والاختياري يأخذ كلمة optionalText
أنه رفض تاريخًا أو وقتًا: نصف مملوء، أو غير متاح	يكون في حالة خطأ كما لو كانت error بالقيمة true، ويعرض كلمات حقل الإدخال عن ذلك

الخاصية countText عدد يخص قيمة عنصر التحكم، كما يُراد رسمه («12/40»). يرسمه الحقل في نهاية صف النص المساعد ولا يفعل به شيئًا آخر: فهو لا يعدّ، ويحجب العدد المرسوم عن التقنيات المساعدة، لأن عنصر التحكم يقول عدده بنفسه. اكتبه من countText في حقل الإدخال عند كل حدث input. وحقل النص يفعل ذلك بنفسه.

الخاصية valueText هي القيمة الحالية لعنصر التحكم بالكلمات («40 %»، «$100 – $300»)، لعنصر تحكم لا تُقرأ قيمته منه هو: شريط التمرير. يرسمها الحقل في نهاية صف التسمية، على السطر الأول من التسمية، ولا يفعل بها شيئًا آخر: فهو لا يقرأ قيمة ولا ينسّقها أبدًا، ويحجب النص المرسوم عن التقنيات المساعدة، لأن عنصر التحكم يقول قيمته بنفسه. وحيث كانت ستترك للتسمية أقل من نصف الصف، تأخذ سطرًا لها بعد التسمية. ولا تُرسم ما دامت التسمية غير مرسومة. اكتبها من shownValueText في شريط التمرير عند كل حدث input. وحقل شريط التمرير يفعل ذلك من تلقاء نفسه، وهو الحقل الجاهز لشريط التمرير.

حقل فيه شريط تمرير، والقيمة بالكلمات في نهاية صف التسمية

حول عنصر الاختيار

link

الحقل حول عنصر الاختيار هو حقل الاختيار مكتوبًا باليد: الصورة نفسها والاسم والوصف والحالات. وخيارات عنصر الاختيار عناصره الفرعية هو. يقول لحقله ما لا يعرفه سواه، والحقل يتبعه:

ما يقوله عنصر الاختيار	الحقل
كم تبعد قيمته عن حافتيه: حشوه، وأيقونة في البداية	يبدأ صف النص المساعد وينهيه هناك، فتبدأ المساعدة حيث تبدأ القيمة
أنه يرسم التسمية بنفسه، عائمة في صندوق من الطراز filled أو outlined	لا يرسم صف التسمية ولا وسم المطلوب أو الاختياري، ويظل يسمّي عنصر الاختيار. وعنصر الاختيار المطلوب يأخذ نجمة بعد تسميته العائمة
أنه مرسوم في حالة التركيز، ما دامت قائمته مفتوحة	يرسم تسميته ومساعدته بألوان حالة التركيز طوال تلك المدة، سواء أكان التركيز داخل الحقل أم لا

البنية

الجزء	الوصف
1 label	Names the control: above it, from the start edge, still, and never cut. The requirement mark follows it. Left out where the control draws the label itself, floating in its own box (FLD-25).
2 label-icon · اختياري	A glyph of the icon set before the label, decorative to assistive technology.
3 requirement-label · اختياري	After the label: the Tag component at its small size, drawn as every small tag is and never a control, saying the control is required or optional; or, for required, an asterisk after the label.
4 value-text · اختياري	The control's present value in words, at the end of the label row: for a control whose value cannot be read from the control itself (a slider). Words the field is given; it never reads or formats a value.
5 control	The one control the field frames: a control that has no label, help and error of its own (a slider, a switch, a control the product built). It keeps its own tokens, states, keyboard, events and value; the field gives it a name, a description, and its required, invalid and disabled states.
6 supporting-text · اختياري	A line of help below the control, from where the control's content starts (FLD-26), It stays while the field is in error, with the error text below it. No row is drawn, and no room kept, while there is neither a help, an error text nor a count.
7 error-text · اختياري	The reason the value was refused, in words, in the supporting row: in the help's place, directly below the control, or below the help, which stays, where comp.field.error-text.placement is append (FLD-7, FLD-31). Drawn only while the field is in error; no room is kept for it before.
8 counter · اختياري	A count about the control's value, in the words the field is given (countText) — a text input's characters typed and, after a slash, the most allowed — at the end of the supporting row's first line (FLD-27). The field draws it and does not count.

الخصائص

الخاصية	النوع	القيمة الافتراضية	الوصف
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.
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).
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).
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.
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.
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.
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.
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.
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.
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.
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.
countText	string	""	A count about the control's value, as it is to be drawn ("12/40"), at the end of the supporting row. For a control that keeps a count (a text input whose counter is true). The product's, or the composed component's that holds the field; kept from assistive technology, because the control says its own count.
valueText	string	""	The control's present value in words ("40 %", "$100 – $300"), drawn at the end of the label row. For a control whose value cannot be read from the control itself (a slider). The product's, or the composed component's that holds the field; kept from assistive technology, because the control says its own value.

المنافذ

المنفذ	الوصف
label-icon	A glyph before the label.

العناصر

أنواع العناصر التي يكررها المكوّن. يسرد كل نموذج اختبار عناصره بالترتيب، وتسمّي كل منصة كل نوع بأسلوبها.

slider

A Slider as the field's control: the slider component, named, described and disabled by the field, otherwise drawn and behaving as it does anywhere.

الخاصية	النوع	القيمة الافتراضية	الوصف
value	number	0	Its value, as the Slider's value.
startValue	number	0	As the Slider's startValue.
range	boolean	false	As the Slider's range.
min	number	0	As the Slider's min.
max	number	100	As the Slider's max.
step	number	0	As the Slider's step.
valueIndicator	none | active | always	"none"	As the Slider's valueIndicator.
valueText	string	""	As the Slider's valueText.
startValueText	string	""	As the Slider's startValueText.
startLabel	string	""	As the Slider's startLabel.
label	string	""	As the Slider's label.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
العنصر	tanrei-slider	TanreiSlider	TanreiSlider	TanreiSlider	Slider
value · الخاصية	value	value	value	value	value
startValue · الخاصية	startValue	value	value	start	startValue
range · الخاصية	range	value	value	range	range
min · الخاصية	min	bounds	valueRange	min	minimumValue
max · الخاصية	max	bounds	valueRange	max	maximumValue
step · الخاصية	step	step	step	step	step
valueIndicator · الخاصية	valueIndicator	valueIndicator	valueIndicator	valueIndicator	valueIndicator
valueText · الخاصية	valueText	valueText	stateDescription	semanticValue	valueText
startValueText · الخاصية	startValueText	startValueText	startStateDescription	startSemanticValue	startValueText
startLabel · الخاصية	startLabel	startLabel	startContentDescription	startSemanticLabel	startAccessibilityLabel
label · الخاصية	label	label	contentDescription	semanticLabel	accessibilityLabel
ملاحظات	A tanrei-slider child in the default slot, as anywhere, without a label of its own: the field names it.

switch

A Switch as the field's control, with no label of its own: the field's label names it.

الخاصية	النوع	القيمة الافتراضية	الوصف
checked	boolean	false	Whether it is on, as the Switch's checked.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
العنصر	tanrei-switch	TanreiSwitch	TanreiSwitch	TanreiSwitch	Switch
checked · الخاصية	checked	isOn	checked	value	value

checkbox

A Checkbox as the field's control. It names itself with its own label, so the field's label is left empty and the field adds help and an error.

الخاصية	النوع	القيمة الافتراضية	الوصف
checked	boolean	false	Whether it is on, as the Checkbox's checked.
label	string	""	Its own label, drawn beside the box, as the Checkbox's label.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
العنصر	tanrei-checkbox	TanreiCheckbox	TanreiCheckbox	TanreiCheckbox	Checkbox
checked · الخاصية	checked	isOn	checked	value	value
label · الخاصية	label	title	label	label	label

one-time-code-input

A One-time-code input as the field's control, with no label of its own: the field names it, describes it and puts it in its error condition.

الخاصية	النوع	القيمة الافتراضية	الوصف
value	string	""	The code entered so far, as the One-time-code input's value.
groupSize	number	0	How many cells a group has, as the One-time-code input's groupSize.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
العنصر	tanrei-one-time-code-input	TanreiOneTimeCodeInput	TanreiOneTimeCodeInput	TanreiOneTimeCodeInput	OneTimeCodeInput
value · الخاصية	value	code	value	controller	value
groupSize · الخاصية	groupSize	groupSize	groupSize	groupSize	groupSize

file-upload

A File upload as the field's control, in its button layout and with no label of its own: the field's label names its group, and the field's help, error and requirement join the description of its trigger (FUP-32). The item's content is the label of the trigger, the product's own Button.

الخاصية	النوع	القيمة الافتراضية	الوصف
constraintsText	string	""	The limits in words, as the File upload's constraintsText: drawn below the trigger, and still read while the field shows its error.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
العنصر	tanrei-file-upload	TanreiFileUpload	TanreiFileUpload	TanreiFileUpload	FileUpload
constraintsText · الخاصية	constraintsText	constraintsText	constraintsText	constraintsText	constraintsText
ملاحظات	A tanrei-file-upload child in the default slot, without a label of its own, holding the product's own tanrei-button in its trigger slot.

file-picker

A File picker as the field's control, in its button layout and with no label of its own: the field's label names its group, and the field's help, error and requirement join the description of its trigger (FPK-21). The item's content is the label of the trigger, the product's own Button.

الخاصية	النوع	القيمة الافتراضية	الوصف
constraintsText	string	""	The limits in words, as the File picker's constraintsText: drawn below the trigger, and still read while the field shows its error.
selectionText	string	""	What is chosen now, in the product's words, as the File picker's selectionText: beside the trigger.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
العنصر	tanrei-file-picker	TanreiFilePicker	TanreiFilePicker	TanreiFilePicker	FilePicker
constraintsText · الخاصية	constraintsText	constraintsText	constraintsText	constraintsText	constraintsText
selectionText · الخاصية	selectionText	selectionText	selectionText	selectionText	selectionText
ملاحظات	A tanrei-file-picker child in the default slot, without a label of its own, holding the product's own tanrei-button in its trigger slot.

text-input

A Text input as the field's control: the pair a text field is. The field names it, describes it and puts it in its error condition; the input says back what only it knows — that it draws the label itself, where its text starts and ends, an entry error (FLD-25, FLD-26, FLD-28).

الخاصية	النوع	القيمة الافتراضية	الوصف
variant	stacked | filled | outlined	"stacked"	As the Text input's variant.
size	small | medium | large	"medium"	As the Text input's size.
type	text | email | password | number | search | tel | url | code | date | time | date-time	"text"	As the Text input's type.
value	string	""	As the Text input's value.
placeholder	string	""	As the Text input's placeholder.
readOnly	boolean	false	As the Text input's readOnly.
multiline	boolean	false	As the Text input's multiline.
minRows	number	2	As the Text input's minRows.
maxRows	number	0	As the Text input's maxRows.
resize	auto | manual | fixed	"auto"	As the Text input's resize.
resizeAxis	vertical | both	"vertical"	As the Text input's resizeAxis.
resizeLabel	string	""	As the Text input's resizeLabel.
wrap	boolean	true	As the Text input's wrap.
maxLength	number	0	As the Text input's maxLength.
counter	boolean	false	As the Text input's counter.
prefixText	string	""	As the Text input's prefixText.
suffixText	string	""	As the Text input's suffixText.
locale	string	""	As the Text input's locale.
segmentEmptyText	string	""	As the Text input's segmentEmptyText.
picker	boolean	false	As the Text input's picker.
pickerLabel	string	""	As the Text input's pickerLabel.
entries	strings		What was entered already: each string is drawn as one small input Chip in the Text input's entries slot (TXI-64), in order — disabled while the field is, and without its remove action while the input is read-only. A product writes these chips by hand; a chip field makes them from its value.
entryRemoveLabel	string	""	The accessible name of each entry's remove action, with {entry} standing for the entry's text ("Remove {entry}"): what a product writes on each chip by hand as the Chip's removeLabel.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
العنصر	tanrei-text-input	TanreiTextInput	TanreiTextInput	TanreiTextInput	TextInput
variant · الخاصية	variant	variant	variant	variant	variant
size · الخاصية	size	size	size	size	size
type · الخاصية	type	type	type	type	type
value · الخاصية	value	text	value	controller	value
placeholder · الخاصية	placeholder	prompt	placeholder	hintText	placeholder
readOnly · الخاصية	readOnly	readOnly	readOnly	readOnly	readOnly
multiline · الخاصية	multiline	axis	singleLine	multiline	multiline
minRows · الخاصية	minRows	lineLimit	minLines	minLines	minRows
maxRows · الخاصية	maxRows	lineLimit	maxLines	maxLines	maxRows
resize · الخاصية	resize	resize	resize	resize	resize
resizeAxis · الخاصية	resizeAxis	resizeAxis	resizeAxis	resizeAxis	resizeAxis
resizeLabel · الخاصية	resizeLabel	resizeLabel	resizeContentDescription	resizeSemanticLabel	resizeAccessibilityLabel
wrap · الخاصية	noWrap	wrap	softWrap	softWrap	wrap
maxLength · الخاصية	maxLength	maxLength	maxLength	maxLength	maxLength
counter · الخاصية	counter	counter	counter	showCounter	counter
prefixText · الخاصية	prefixText	prefix	prefix	prefixText	prefix
suffixText · الخاصية	suffixText	suffix	suffix	suffixText	suffix
locale · الخاصية	locale	locale	locale	locale	locale
segmentEmptyText · الخاصية	segmentEmptyText	segmentEmptyText	segmentEmptyText	segmentEmptyText	segmentEmptyText
picker · الخاصية	picker	onPickerRequest	onPickerRequest	onPickerRequest	onPickerRequest
pickerLabel · الخاصية	pickerLabel	pickerLabel	pickerContentDescription	pickerSemanticLabel	pickerAccessibilityLabel
entries · الخاصية	entries	entries	entries	entries	entries
entryRemoveLabel · الخاصية	entryRemoveLabel	entryRemoveLabel	entryRemoveLabel	entryRemoveLabel	entryRemoveLabel
ملاحظات	A tanrei-text-input child in the default slot, without a label of its own: the field names it, and floats nothing itself. The two elements by hand are the twin of tanrei-text-field.

number-input

A Number input as the field's control: the pair a number field is. The field names it, describes it and puts it in its error condition; the input says back what only it knows — that it draws the label itself, where its number's line starts and ends, a text that is not a number (FLD-25, FLD-26, FLD-28).

الخاصية	النوع	القيمة الافتراضية	الوصف
variant	stacked | filled | outlined	"stacked"	As the Number input's variant.
size	small | medium | large	"medium"	As the Number input's size.
value	number	null	As the Number input's value.
placeholder	string	""	As the Number input's placeholder.
readOnly	boolean	false	As the Number input's readOnly.
min	number	null	As the Number input's min.
max	number	null	As the Number input's max.
step	number	1	As the Number input's step.
steppers	boolean	true	As the Number input's steppers.
incrementLabel	string	""	As the Number input's incrementLabel.
decrementLabel	string	""	As the Number input's decrementLabel.
prefixText	string	""	As the Number input's prefixText.
suffixText	string	""	As the Number input's suffixText.
valueText	string	""	As the Number input's valueText.
align	start | end	"start"	As the Number input's align.
minFractionDigits	number	0	As the Number input's minFractionDigits.
maxFractionDigits	number	3	As the Number input's maxFractionDigits.
locale	string	""	As the Number input's locale.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
العنصر	tanrei-number-input	TanreiNumberInput	TanreiNumberInput	TanreiNumberInput	NumberInput
variant · الخاصية	variant	variant	variant	variant	variant
size · الخاصية	size	size	size	size	size
value · الخاصية	value	value	value	value	value
placeholder · الخاصية	placeholder	prompt	placeholder	hintText	placeholder
readOnly · الخاصية	readOnly	readOnly	readOnly	readOnly	readOnly
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
ملاحظات	A tanrei-number-input child in the default slot, without a label of its own: the field names it, and floats nothing itself. The two elements by hand are the twin of tanrei-number-field. The input says drawsLabel, inset and refusal through the connection and no count.

color-input

A Color input as the field's control: the pair a color field is. The field names it, describes it and puts it in its error condition; the input says back what only it knows — that it draws the label itself, where the value's text starts, after its swatch, and an entry error (FLD-25, FLD-26, FLD-28).

الخاصية	النوع	القيمة الافتراضية	الوصف
variant	stacked | filled | outlined	"stacked"	As the Color input's variant.
size	small | medium | large	"medium"	As the Color input's size.
value	string	""	As the Color input's value.
picker	boolean	false	As the Color input's picker.
pickerLabel	string	""	As the Color input's pickerLabel.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
العنصر	tanrei-color-input	TanreiColorInput	TanreiColorInput	TanreiColorInput	ColorInput
variant · الخاصية	variant	variant	variant	variant	variant
size · الخاصية	size	size	size	size	size
value · الخاصية	value	hex	value	controller	value
picker · الخاصية	picker	showsPicker	onPickerRequest	onPickerRequest	onPickerRequest
pickerLabel · الخاصية	pickerLabel	pickerLabel	pickerContentDescription	pickerSemanticLabel	pickerAccessibilityLabel
ملاحظات	A tanrei-color-input child in the default slot, without a label of its own: the field names it, and floats nothing itself. The two elements by hand are the twin of tanrei-color-field.

select

A Select as the field's control: the pair a select field is. The field names it, describes it and puts it in its error condition; the select says back what only it knows — that it draws the label itself in a look that floats one, where its value starts and ends, and that its list is open (FLD-13, FLD-25, FLD-26). In a fixture, an item of this kind holds the select's own options as its items and fills the select's own slots.

الخاصية	النوع	القيمة الافتراضية	الوصف
variant	stacked | filled | outlined	"stacked"	As the Select's variant.
size	small | medium | large	"medium"	As the Select's size.
value	string	""	As the Select's value.
placeholder	string	""	As the Select's placeholder.
readOnly	boolean	false	As the Select's readOnly.
open	boolean	false	As the Select's open.
separation	auto | divider | gap	"auto"	As the Select's separation.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
العنصر	tanrei-select	TanreiSelect	TanreiSelect	TanreiSelect	Select
variant · الخاصية	variant	variant	variant	variant	variant
size · الخاصية	size	size	size	size	size
value · الخاصية	value	selection	value	value	value
placeholder · الخاصية	placeholder	prompt	placeholder	hintText	placeholder
readOnly · الخاصية	readOnly	readOnly	readOnly	readOnly	readOnly
open · الخاصية	open	isPresented	expanded	controller	open
separation · الخاصية	separation	separation	separation	separation	separation
ملاحظات	A tanrei-select child in the default slot, without a label of its own, holding its tanrei-option children: the field names it, describes it and marks it through the connection, and the select says back that it draws the label, where its value starts and that its list is open (SEL-63).	The select as the content of the Field, with its options as its own content.	The select as the content of the Field, with its options as its own content.	The select as the content of the Field, with its options as its own content.	The select as the content of the Field, with its options as its own content.

combobox

A Combobox as the field's control: the pair a combobox field is. The field names it, describes it and puts it in its error condition; the combobox says back what only it knows — that it draws the label itself in a look that floats one, where its input text starts and ends, and that its list is open (FLD-13, FLD-25, FLD-26). In a fixture, an item of this kind holds the combobox's own options as its items and fills the combobox's own slots.

الخاصية	النوع	القيمة الافتراضية	الوصف
variant	stacked | filled | outlined	"stacked"	As the Combobox's variant.
size	small | medium | large	"medium"	As the Combobox's size.
value	string	""	As the Combobox's value.
inputValue	string	""	As the Combobox's inputValue.
placeholder	string	""	As the Combobox's placeholder.
readOnly	boolean	false	As the Combobox's readOnly.
open	boolean	false	As the Combobox's open.
allowCustomValue	boolean	false	As the Combobox's allowCustomValue.
filter	contains | none	"contains"	As the Combobox's filter.
chevron	boolean	true	As the Combobox's chevron.
clearable	boolean	false	As the Combobox's clearable.
clearLabel	string	""	As the Combobox's clearLabel.
status	idle | loading | error	"idle"	As the Combobox's status.
statusText	string	""	As the Combobox's statusText.
emptyText	string	""	As the Combobox's emptyText.
separation	auto | divider | gap	"auto"	As the Combobox's separation.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
العنصر	tanrei-combobox	TanreiCombobox	TanreiCombobox	TanreiCombobox	Combobox
variant · الخاصية	variant	variant	variant	variant	variant
size · الخاصية	size	size	size	size	size
value · الخاصية	value	selection	value	value	value
inputValue · الخاصية	inputValue	text	inputValue	controller	inputValue
placeholder · الخاصية	placeholder	prompt	placeholder	hintText	placeholder
readOnly · الخاصية	readOnly	readOnly	readOnly	readOnly	readOnly
open · الخاصية	open	isPresented	expanded	menuController	open
allowCustomValue · الخاصية	allowCustomValue	allowCustomValue	allowCustomValue	allowCustomValue	allowCustomValue
filter · الخاصية	filter	filter	filter	filter	filter
chevron · الخاصية	noChevron	chevron	chevron	chevron	chevron
clearable · الخاصية	clearable	clearable	clearable	clearable	clearable
clearLabel · الخاصية	clearLabel	clearLabel	clearContentDescription	clearSemanticLabel	clearAccessibilityLabel
status · الخاصية	status	status	status	status	status
statusText · الخاصية	statusText	statusText	statusText	statusText	statusText
emptyText · الخاصية	emptyText	emptyText	emptyText	emptyText	emptyText
separation · الخاصية	separation	separation	separation	separation	separation
ملاحظات	A tanrei-combobox child in the default slot, without a label of its own: the field names it, and floats nothing itself. Its <tanrei-option> and <tanrei-option-group> children are its own. The two elements by hand are the twin of tanrei-combobox-field.	TanreiCombobox as the field's content, with its own options. Planned.	TanreiCombobox as the field's content, with its own options. Planned.	TanreiCombobox as the field's content, with its own options. Planned.	Combobox as the field's content, with its own options. Planned.

chat-composer

A Chat composer as the field's control, with no label of its own: the field's label names it and its typing area, the field's help and, in error, its error text are the last part of the typing area's description, and the field's error and disabled are the composer's (CCM-28). The composer draws its own capsule and none of the field's rows.

الخاصية	النوع	القيمة الافتراضية	الوصف
placeholder	string	""	As the Chat composer's placeholder.
sendLabel	string	""	As the Chat composer's sendLabel: the name of its send button, which the field does not give (CCM-31).

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
العنصر	tanrei-chat-composer	TanreiChatComposer	TanreiChatComposer	TanreiChatComposer	ChatComposer
placeholder · الخاصية	placeholder	prompt	placeholder	hintText	placeholder
sendLabel · الخاصية	sendLabel	sendLabel	sendContentDescription	sendSemanticLabel	sendAccessibilityLabel
ملاحظات	A tanrei-chat-composer child in the default slot, without a label of its own: the field names it, and its texts join the typing area's description (CCM-28).

الحالات

السلوك

متطلبات بصيغة EARS. يُختبر تنفيذ كل منصة مقابل هذه المعرّفات. يُعرض نص المتطلبات كما ورد في ملف المواصفة، بالإنجليزية.

المعرّف	المتطلب
FLD-1	THE field SHALL lay out, from top to bottom and from its start edge: its label row (FLD-2), its control comp.field.label.gap below the last line of that row, and its supporting row (FLD-7) comp.field.supporting-text.gap below the control. It SHALL be as wide as its layout gives it and give the control that whole width to lay itself out in — a control that fills the width it is given fills it, and a control with a size of its own keeps it, at the start edge — and SHALL be as tall as its rows and its control together. THE field SHALL draw no container, edge, fill or elevation of its own, SHALL add no padding around its rows, and SHALL NOT change the size, the look or the behaviour of its control.
FLD-2	WHILE label is not empty, labelHidden is false and its control does not draw the label itself (FLD-25) THE field SHALL draw label above its control, from the field's start edge, in comp.field.label.typescale and comp.field.standard.label.color (comp.field.standard.error.label.color WHILE error is true). The label SHALL keep its place, size and style whatever the control holds, SHALL wrap onto as many lines as it needs, and SHALL never be cut with an ellipsis or drawn over the control, because text enlarged to 200% must lose no content. WHILE labelHidden is true or label is empty THE field SHALL draw neither the label row nor the gap below it, and SHALL draw no label glyph and no requirement mark (FLD-3, FLD-6).
FLD-3	WHILE the label is drawn and the label-icon slot holds a glyph THE field SHALL draw it before the label, comp.field.label-icon.gap from it, at comp.field.label-icon.size, centred on the label's first line, with sys.icon.family.unselected and sys.icon.fill.unselected, sys.icon.weight and an optical size clamped between sys.icon.optical-size.min and sys.icon.optical-size.max, in comp.field.standard.label-icon.color (comp.field.standard.error.label-icon.color WHILE error is true), and SHALL keep it from assistive technology, because the label names the control; WHILE the label is not drawn THE field SHALL NOT draw the label glyph and SHALL report it in debug builds.
FLD-4	THE field SHALL take from required and optional what the form asks of its control: WHILE required is true it exposes the control as required (FLD-10) and draws the required mark (FLD-5, FLD-6); WHILE optional is true it draws the optional tag (FLD-5) and adds optionalText to the control's description (FLD-11), because assistive technology has no state for it; WHILE both are false it says nothing and draws nothing. THE field SHALL NOT validate because of required: it SHALL NOT set the error condition for a missing value or show an error text of its own; what a missing value means is the product's to say with error and errorText. WHILE disabled is true THE field SHALL keep its mark: an asterisk drawn from the field's disabled tokens (FLD-14), a requirement tag drawn as a tag inside something disabled (FLD-5, TAG-21).
FLD-5	WHILE the label is drawn and optional is true, or required is true and the required mark is tag (FLD-6), THE field SHALL draw after the label's text, comp.field.requirement.gap from it and centred on the label's last line, a requirement tag: the Tag component, drawn as every tag is — size small, variant filled for required and tonal for optional, status default, no glyph and no dot, its label requiredText or optionalText on one line (TAG-1, TAG-2, TAG-5) — from the Tag's own tokens (comp.tag.container.height.small, comp.tag.label.typescale.small, comp.tag.filled.container.color, comp.tag.tonal.container.color and the others those sentences name). THE field SHALL have no token for the requirement tag's fill, lettering, text style, paddings or corners and SHALL set none of the Tag's for it, so that a design system or a product that restyles its small tags restyles the requirement tag with them and nothing restyles the requirement tag alone. THE field SHALL draw the requirement tag the same at rest, WHILE focus is inside the field and WHILE error is true, because a tag has no states (TAG-9) and what the form asks has not changed; WHILE disabled is true THE field SHALL have it drawn as a tag inside something disabled (TAG-21), from the Tag's own disabled tokens, so that the tag fades with the label it follows and no part of a disabled field reads as live. The requirement tag is text, never a control: it SHALL take no focus and no hover, focus or press answer of its own (a press on it does what a press on the label does, FLD-12). It SHALL NOT make the label's row taller: where it is taller than the label's line it SHALL reach equally above and below that line. WHEN the label and the requirement tag do not fit on one line THE field SHALL wrap the label (FLD-2) and move the tag whole to a line of its own after the label's last line, never cutting or splitting it. WHILE requiredText or optionalText is empty THE field SHALL NOT draw the tag of that kind and in debug builds SHALL report it. THE field SHALL keep the required tag from assistive technology, because the required state already says it, and SHALL give the optional tag's text as part of the description (FLD-4).
FLD-6	WHILE required is true and the label is drawn THE field SHALL draw the required mark that requiredMark names — tag (FLD-5), asterisk or none — and WHILE requiredMark is auto, the one comp.field.requirement.mark names: that token follows sys.behavior.requirement-mark, the design system's one answer for every field and every set of controls, unless a layer gives comp.field.requirement.mark a value of its own. As asterisk it SHALL draw the character "*" after the label's text, comp.field.requirement.asterisk-gap from it, in the label's text style, in comp.field.standard.required-asterisk.color (comp.field.standard.error.required-asterisk.color WHILE error is true), and SHALL keep it from assistive technology, because the required state already says it; as none it SHALL draw no mark and still expose the required state. WHILE the label is not drawn THE field SHALL draw no mark, and SHALL still expose the required state and the optional description.
FLD-7	THE field SHALL draw its supporting row below the control, from the start edge of the control's content (FLD-26). It holds supportingText, the help, WHILE it is not empty, in comp.field.supporting-text.typescale and comp.field.standard.supporting-text.color (comp.field.standard.error.supporting-text.color WHILE the field is in error), and the error text WHILE the field is in error and has words for it (FLD-31). How the two share the row is the one comp.field.error-text.placement names. WHERE it is replace, its first value, THE field SHALL NOT draw the help WHILE it draws the error text, which stands in the help's place, because what the person must read then is what is wrong with the answer, and a field in error is no taller for it than at rest; WHEN the error text goes THE field SHALL draw the help again where it was. WHERE it is append THE field SHALL keep the help in its place and its words WHILE it draws the error text, and draw the error text below it, because the help says how to answer, which is what the person needs then. Each text SHALL wrap onto as many lines as it needs and never be cut. WHILE countText is not empty THE field SHALL draw it at the end of the row's first line (FLD-27). WHILE there is neither a help, an error text nor a count THE field SHALL draw neither the row nor its gap, and SHALL keep no room for it.
FLD-8	WHILE error is true THE field SHALL draw its label, its label glyph, its asterisk and its help from the error parts of its tokens (FLD-2, FLD-3, FLD-5 to FLD-7), SHALL draw its error text (FLD-31), SHALL expose its control as invalid to assistive technology, and SHALL put its control in the control's own error condition where the control has one (a checkbox's error), so that the control itself is marked and not only its text; a control with no error condition SHALL stay as it is drawn. THE field SHALL never set error itself: what a value means is the product's to validate. The one error it shows without it is its control's own refusal of an entry (FLD-28).
FLD-9	WHEN error becomes true, or errorText changes while error is true, and focus is inside the field THE field SHALL have assistive technology announce the shown error text once, politely; an error set while focus is elsewhere SHALL be read as part of the control's description when the control is next focused. THE field SHALL NOT move focus because of an error, and SHALL announce no other change of its texts: the help is not said again when the error appears, because it has not changed and is still read with the control (FLD-11).
FLD-10	THE field SHALL make label the accessible name of its control, whether or not the label is drawn (labelHidden), WHERE the control has no accessible name of its own; a control that names itself (a checkbox or a switch with its own label, a control the product named) SHALL keep that name, and WHERE such a control stands under a drawn label THE field SHALL in debug builds report that the control has two labels. WHILE label is empty and the control has no name of its own THE field SHALL still render and in debug builds report that the control has no accessible name. WHILE required is true THE field SHALL expose the control as required, whichever mark is drawn and where none is.
FLD-11	THE field SHALL make these the description of its control, in this order, after any description the control has of its own and whether or not the label is drawn: supportingText, WHILE the row draws it (FLD-7); the error text WHILE the field is in error (FLD-31); optionalText WHILE optional is true — the order in which a field group describes its set (FGR-11). The description SHALL say what the row draws: WHERE comp.field.error-text.placement is replace, the error text in the help's place WHILE the field is in error; WHERE it is append, the help and then the error text. WHEN one of these texts comes, goes or changes THE field SHALL expose the new description at once. The label glyph, the required tag and the asterisk SHALL NOT be exposed.
FLD-12	WHEN the user presses the label, the label glyph or the requirement mark THE field SHALL move focus to its control and do nothing else: it SHALL NOT activate, switch or change the control, and SHALL draw no press answer, because a press on a label is not an action. A press on the supporting row SHALL do nothing. THE field SHALL add no stop to the focus order and handle no key: its control is the only thing in it that takes focus, and the control's own keys are the control's.
FLD-13	WHILE focus is inside the field — on its control or on any part of it, however the focus was gained — or its control says that it is drawn focused (for one, a select or a combobox for as long as its list is open) THE field SHALL draw its label, its label glyph, its asterisk, its value text and its supporting row from its focused tokens (their error parts WHILE error is true), as a text input's box does (TXI-6), so that a form shows which field has focus in one way for every field; the control draws its own focus indicator, and THE field SHALL draw none. WHEN focus enters or leaves, or error or disabled changes, THE field SHALL change its colors over comp.field.motion.state-duration with comp.field.motion.state-easing, and at once WHERE motion is reduced.
FLD-14	WHILE disabled is true THE field SHALL draw every part of its own from its disabled tokens (of its error parts WHILE error is true) and its requirement tag as a tag inside something disabled (FLD-5, TAG-21), SHALL make its control disabled as that control's own disabled does — not focusable, not operable, exposed as disabled — and SHALL NOT answer a press on its label (FLD-12); WHILE disabled is false THE field SHALL NOT enable a control the product disabled itself. A disabled field SHALL keep its texts readable by assistive technology.
FLD-15	THE field SHALL frame exactly one control. IF it is given none THE field SHALL draw its rows without one and in debug builds report it; IF it is given more than one THE field SHALL lay them out in the order given, name, describe and mark only the first (FLD-8, FLD-10, FLD-11), and in debug builds report that a set of controls is a field group. IF its control is a component that has this frame already — a composed field, which is a Field and its one control (a text field, a select field) — THE field SHALL in debug builds report that the control is already a field and that the bare control is the one that field frames (for a text field, the text input), and SHALL hide neither frame.
FLD-16	WHILE the text size is enlarged THE field SHALL grow with its texts: the label and the supporting row wrap and never clip, the requirement tag grows with its text and keeps its paddings, the label glyph keeps comp.field.label-icon.size, the value text grows with its text and keeps the line FLD-29 gives it, and the rows keep their order and their gaps; at 200% no text SHALL be lost, lie over another part or need scrolling in two directions.
FLD-17	WHERE the platform draws with a person's own forced colors (the web's forced-colors mode, and a platform's equivalent where it has one) THE field SHALL draw its label, its asterisk, its value text, its supporting text and its error text in the platform's text color and its requirement tag as a tag is drawn there (an edge and a label in the text color, TAG-14), and SHALL rely on no color of its own to tell an error from help: the error is carried by the words of errorText, by the invalid state (FLD-8) and by the control's own error condition; the two texts, drawn in one color there, are told apart by their words and their order, the help first.
FLD-18	WHERE the layout direction is right-to-left THE field SHALL mirror its layout: the label row, the control and the supporting row start at the right edge, the label glyph stands at the right of the label and the requirement mark at its left, and the value text stands at the left end of the label row.
FLD-19	THE field SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the field is shown THE field SHALL draw itself for the new direction at once, without a motion of its own, keeping its control, with that control's value and focus.
FLD-20	WHERE the layout direction is right-to-left THE field SHALL draw the glyph of its label-icon slot mirrored left to right exactly when the system's icon set marks that glyph's name as mirrored or the product forces mirroring for that use, and unmirrored when the product forbids it: the icon helper mirrors the glyph inside its own box, about the box's vertical centre line, changing neither its place, size, color and fill nor the order FLD-18 gives. THE field SHALL NOT mirror a glyph itself, and SHALL NOT mirror content the product gives as an image or a view of its own rather than by a glyph's name.
FLD-21	THE field SHALL lay out its label, its value text, its supporting text and error text and the text of its requirement tag as text of its own direction, isolated from the text around it: each takes the base direction of its first strong character, or the layout direction where it has none, so that a left-to-right word, a number with its sign or unit, a telephone number and an address keep their own order in a right-to-left layout and reorder nothing beside them; THE field SHALL still place each and align its lines by the layout direction, not by the text's own.
FLD-22	WHEN requiredMark names a value the field does not know THE field SHALL behave as auto, and in debug builds THE field SHALL report the unknown value.
FLD-23	THE field SHALL leave its control what it is: the control keeps its own tokens, states, keyboard, events, value and place in a form, and THE field SHALL emit no event, hold no value and take no part in form submission. WHEN the control is replaced by another while the field is shown THE field SHALL name, describe and mark the new one (FLD-8, FLD-10, FLD-11, FLD-14) at once, and SHALL take back from the old one everything it gave it.
FLD-24	THE field SHALL have no words of its own: it SHALL take requiredText and optionalText from the instance's prop and, WHILE that is empty, from the product's words of the same name — the words a product sets once for all its components — and from nowhere else. IF neither gives requiredText WHILE required is true and the required mark is tag THE field SHALL draw the asterisk of FLD-6 in the tag's place, so that the requirement is still shown without a word, SHALL keep the required state on its control (FLD-10), and in debug builds SHALL report the missing words once. IF neither gives optionalText WHILE optional is true THE field SHALL draw no tag, SHALL add nothing to the description for it, and in debug builds SHALL report the missing words once.
FLD-25	WHILE its control draws the label itself — a control whose look floats its name inside its own box (for one, a text input of the filled or the outlined look, TXI-13) — THE field SHALL draw no label row, no gap below it, no label glyph and no requirement tag, as WHILE labelHidden is true (FLD-2), and SHALL still give the control label as its accessible name (FLD-10). With the name it SHALL give the control three things to draw the label by: whether labelHidden is true, so that the control draws none either; and the required mark, as an asterisk WHILE required is true and the mark FLD-6 names is tag or asterisk, and as none otherwise; and optionalText WHILE optional is true, because a person who sees the asterisk on the required fields of a form must also see which ones may be left out, and the optional tag of the label row has no room in a label that floats. The control draws both after the label's text, from its own tokens (for a text input, TXI-50). THE field SHALL keep its supporting row, its error condition, and the description and the states it gives (FLD-7 to FLD-11, FLD-14) unchanged. A press on a label the control draws is a press on the control, and the control's to answer (for a text input, TXI-8): FLD-12 speaks of the row the field draws. WHILE optional is true THE field SHALL keep optionalText in the description as well (FLD-11); WHILE the label-icon slot holds a glyph it SHALL report it as FLD-3 says. WHEN the control starts or stops drawing the label THE field SHALL leave out or draw its label row at once, without motion.
FLD-26	WHERE its control's content is inset from the control's own edges and the control says by how much — for one, a text input: from its start edge to where its text starts, past its inline padding and a leading icon, and the padding it keeps at its end edge (TXI-62) — THE field SHALL start its supporting row that far from its own start edge and end it that far before its end edge, so that the help and the error start where the text starts (FLD-7). The label row SHALL stay at the field's edges (FLD-2). A control that says nothing SHALL have the row at the field's edges, as a slider has. WHEN what the control says changes — its size, an icon that comes or goes, the layout direction — the row SHALL follow at once, without motion.
FLD-27	WHILE countText is not empty THE field SHALL draw it at the end of the supporting row's first line — beside the first line of the help, or of the error text WHILE there is no help — on one line that does not wrap, at least comp.field.counter.gap from every line of the help and of the error text, which both wrap in the room the count leaves beside it, and SHALL keep it in that place WHEN the error text comes or goes below a help, in comp.field.supporting-text.typescale with figures of equal width and in comp.field.standard.counter.color (comp.field.standard.error.counter.color WHILE the field is in error; their focused and disabled tokens as FLD-13 and FLD-14 say), and SHALL draw the row for the count alone WHILE there is no text to show. THE field SHALL draw the count as it is given and SHALL NOT count, format, describe or announce it, and SHALL keep the drawn count from assistive technology: countText is words the field is given — by the composed component that holds it (a text field gives its text input's count, TXF-67) or by the product that writes the pair by hand — about a control that makes the same count part of its own description and announces it (TXI-19). It SHALL lay the count out as text of its own direction (FLD-21), at the left end of the row in a right-to-left layout (FLD-18), in the platform's text color under forced colors (FLD-17), and WHILE the text size is enlarged SHALL keep it whole on its line while the text beside it wraps (FLD-16). A press on the count SHALL do nothing, as on the rest of the row (FLD-12). WHEN countText changes THE field SHALL draw the new text at once, without a motion.
FLD-28	WHILE its control reports that it refused what was entered — an entry error of the control's own (for one, a text input of type date, time or date-time committed half-filled, or with a date or a time that is not available, TXI-30) — THE field SHALL be in the error condition exactly as WHILE error is true (FLD-8): it SHALL draw its error parts, expose the control as invalid, and show as its error text (FLD-31) the words the control gives for the refusal — errorText WHILE the control gives none — in its supporting row, where any error text stands (FLD-7, FLD-31); WHILE the control gives no words and errorText is empty THE field SHALL draw no error text, SHALL still mark itself and in debug builds SHALL report a refusal that has no words. WHEN the report begins, or its words change, while focus is inside the field THE field SHALL announce the error text as FLD-9 says. WHEN the control withdraws the report THE field SHALL return at once to what error and errorText say. THE field SHALL NOT validate for the control, and SHALL forget the report WHEN the control is replaced (FLD-23).
FLD-29	WHILE valueText is not empty and the label is drawn THE field SHALL draw valueText at the end edge of the label row, on the baseline of the label's first line, on one line, in comp.field.value-text.typescale and comp.field.standard.value-text.color (comp.field.standard.error.value-text.color WHILE error is true), and SHALL keep at least comp.field.value-text.gap between it and the label with its requirement mark: the label wraps in the room that is left (FLD-2) and the requirement tag moves to a line of its own as FLD-5 says. WHERE that leaves the label less than half of the row's width THE field SHALL instead draw the value text whole on a line of its own after the label row's last line, from the start edge, wrapping there where it must, and never cut. WHEN valueText changes THE field SHALL draw the new text at once, without a motion, and SHALL move no other part: the text is aligned to the end edge, so that only its own start moves. WHILE the label is not drawn THE field SHALL draw no value text, and it SHALL never draw one in the supporting row.
FLD-30	THE field SHALL keep the drawn value text from assistive technology and SHALL announce no change of it, because the control says its own value and a second reading would say it twice; a control that exposes no value is the product's to mend, not the frame's to speak for. A press on the value text SHALL do what a press on the label does (FLD-12). THE field SHALL NOT read, compute or format a value: valueText is words it is given.
FLD-31	WHILE the field is in error — error is true, or its control reports that it refused an entry (FLD-28) — and has words for it — errorText, or the control's own words for a refusal — THE field SHALL draw those words as its error text, in its supporting row: as the row's first line, comp.field.supporting-text.gap below the control — in the help's place WHERE comp.field.error-text.placement is replace (FLD-7), and WHILE supportingText is empty under either value — and WHERE it is append and supportingText is not empty, comp.field.error-text.gap below the last line of the help. It SHALL start where the help starts (FLD-26), be drawn in comp.field.supporting-text.typescale and comp.field.standard.error-text.color (its focused and disabled tokens as FLD-13 and FLD-14 say), wrap onto as many lines as it needs, never be cut, and never share a line with the help. WHILE the field is not in error, or is in error without words, THE field SHALL draw no error text and no gap for it and SHALL keep no room for one: under replace a field with a help is as tall in error as at rest while its error text takes as many lines as its help, under append it is taller by comp.field.error-text.gap and the lines of its error text, and a form at rest is no taller for errors it does not have. WHEN the error text appears, goes or changes its words THE field SHALL draw the row as it then is at once, with no motion of its own — what stands below the field moves with the layout, and only the colors of FLD-13 ease — so there is nothing here that reduced motion changes. THE field SHALL lay the error text out as text of its own direction (FLD-21), mirror it with its row (FLD-18), draw it in the platform's text color under forced colors (FLD-17), let it wrap and grow with enlarged text (FLD-16), and do nothing WHEN it is pressed (FLD-12).
FLD-32	IF required and optional are both true THEN THE field SHALL behave as WHILE required alone is true — it draws the required mark and no optional tag, and says no optionalText — and in debug builds SHALL report that optional is ignored, because a control is never both required and optional.
FLD-33	WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the field's host, by the attribute or by the ARIA property that reflects it, THE field SHALL move it to the data-aria- attribute of the same name, so that the host — which has no role — is no node of its own with a name, a description or a state, SHALL expose it on no element, and SHALL report it in debug builds, saying to write it on the control: the control is the product's own element, which keeps its own name, states and ARIA (FLD-10, FLD-23), and what the field gives it is its label, its texts and its marks (FLD-8, FLD-10, FLD-11, FLD-14). WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it to null, THE field SHALL take the moved value away.

مطابقة الأسماء بين المنصات

التكافؤ لا يعني واجهات برمجية متطابقة. تعبّر كل منصة عن العقد نفسه بأسلوبها.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
المكوّن	tanrei-field	TanreiField	TanreiField	TanreiField	Field
label · الخاصية	label	label	label	labelText	label
labelHidden · الخاصية	labelHidden	labelsHidden	labelHidden	labelHidden	labelHidden
supportingText · الخاصية	supportingText	supportingText	supportingText	helperText	supportingText
errorText · الخاصية	errorText	errorText	errorText	errorText	errorText
error · الخاصية	error	error	isError	isError	error
disabled · الخاصية	disabled	disabled	enabled	enabled	disabled
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
countText · الخاصية	countText	countText	countText	countText	countText
valueText · الخاصية	valueText	valueText	valueText	valueText	valueText
ملاحظات	<tanrei-field label="Volume"><tanrei-slider></tanrei-slider></tanrei-field>: the control is the one element in the default slot. It stays in the product's light DOM, so it keeps its place in a <form>, its name and value, its events and its styles; the field is not form-associated and holds no value. The label, the asterisk, the supporting row and the requirement tag (a <tanrei-tag size="small">, filled or tonal, disabled while the field is, with nothing else set on it: it reads the Tag's tokens as every tag where the field stands does) are in the shadow root; the label glyph is the label-icon slot. An id cannot be referenced across a shadow boundary, so the field does not point aria-labelledby or aria-describedby at its own texts: it gives them as strings. A Tanrei control asks for them (it dispatches a composed tanrei-field-connect event when it is connected, the nearest field answers with { label, description, invalid, required, disabled } and tells it of every change), writes them on its inner native element or role holder, and lets its own label win. Any other element receives aria-label (only where it has neither aria-label nor aria-labelledby), aria-description, aria-invalid, aria-required and, where it has the property, disabled; the field removes exactly what it set when the element leaves the slot (slotchange, FLD-23). The announcement of FLD-9 is a visually hidden aria-live="polite" element in the shadow root, written only while :focus-within holds. A press on the label calls focus() on the control; focusin and focusout on the host select the focused tokens. Attributes are kebab-case: label-hidden, supporting-text, error-text, required-mark, required-text, optional-text. The host is display: block. Under forced-colors: active the texts are CanvasText. Words: the element has no words of its own. required-text and optional-text left empty read the product's words, set once with setWords() from @tanrei/web; the element draws again when they change. The exchange with a control runs both ways. Beside the name, the description and the three states, the field gives labelHidden and requiredMark (asterisk or none) to a control that draws the label itself; and a control may say drawsLabel, inset: { start, end } and refusal: { text } of itself through the same connection (FLD-25, FLD-26, FLD-28). A control that says none of them is framed as any other, and a field ignores what it does not know. The supporting row is a flex row whose padding-inline is the inset. The count is not in the exchange: count-text is an attribute of the field, drawn in a part="counter" element at the end of the supporting row, aria-hidden, white-space: nowrap, font-variant-numeric: tabular-nums (FLD-27). The supporting row holds two texts. part="supporting-text" is the help alone, not rendered while the error text stands in its place; part="error-text" is the error text — the row's first line under replace, a block below the help, --tanrei-comp-field-error-text-gap away, under append — in --tanrei-comp-field-standard-error-text-color, rendered only while the field is in error with words (FLD-31). The two are one column that takes the room beside the counter part, which is aligned to the first line. --tanrei-comp-field-error-text-placement is read by name (replace, the first, or append) from the cascade at each render, and the field draws again when the design system is switched. The aria-description the field gives its control is what the row draws (the help, the error text, or the two in that order) and the optional text, joined (FLD-11); the live region of FLD-9 is given the error text alone. shownText() of the frame does not choose between the two. The tag's element carries no custom property and is centred on the label's line without its height being read; required-mark takes tag; and --tanrei-comp-field-requirement-mark is var(--tanrei-sys-behavior-requirement-mark) until a layer sets it.	TanreiField("Volume", supportingText:, errorText:, error:, required:, optional:) { TanreiSlider(value: $volume) }, the glyph given by name through labelIcon:. labelHidden follows the .labelsHidden() environment and disabled follows .disabled(_:), which also disables the content. The content is one view; the field sets .accessibilityLabel, .accessibilityHint (the description) and the invalid and required values on it, and offers the same values in the environment (\.tanreiField) for a control the product built. The product's words are read from the \.tanreiWords environment value. Not built on this platform yet: the supporting row is a VStack of the help and, in error, the error text — in the help's place, or comp.field.error-text.gap below it, as comp.field.error-text.placement names (FLD-7); the hint is what the row draws, then the optional text (FLD-11, FLD-31). Not built on this platform yet: the requirement tag as this platform's Tag at its small size with nothing of the field's set on it (FLD-5); generated tokens with none of the field's values for it and with the system's choice of mark, which the field's own token follows (FLD-6); the first mark named tag.	TanreiField(label = "Volume", supportingText = …, isError = …, required = …, optional = …) { TanreiSlider(…) }, the glyph given by name through labelIcon. enabled is the inverse flag and is offered to the content through LocalTanreiFieldState, with the name, the description and isError; Tanrei controls read it, and a control the product built reads the same composition local. The field adds contentDescription, stateDescription and error(…) to the merged semantics of its content. The product's words are read from LocalTanreiWords. Not built on this platform yet: the supporting row is a Column of the help and, in error, the error text — in the help's place, or comp.field.error-text.gap below it, as comp.field.error-text.placement names (FLD-7); the description offered through LocalTanreiFieldState is what the row draws, then the optional text (FLD-11, FLD-31). Not built on this platform yet: the requirement tag as this platform's Tag at its small size with nothing of the field's set on it (FLD-5); generated tokens with none of the field's values for it and with the system's choice of mark, which the field's own token follows (FLD-6); the first mark named tag.	TanreiField(labelText: 'Volume', helperText: …, errorText: …, isError: …, required: …, optional: …, child: TanreiSlider(…)), the glyph given by name through labelIcon. enabled is the inverse flag. The names follow InputDecoration, as the text field's do. The field wraps its child in a Semantics(label:, hint:, enabled:) node and an inherited TanreiFieldScope that Tanrei controls and the product's own read. 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: errorText takes the helper's place, as InputDecoration's does, under comp.field.error-text.placement replace, and is drawn below helperText, which stays, comp.field.error-text.gap away, under append (FLD-7); the Semantics hint is what the row draws, then the optional text (FLD-11, FLD-31). Not built on this platform yet: the requirement tag as this platform's Tag at its small size with nothing of the field's set on it (FLD-5); generated tokens with none of the field's values for it and with the system's choice of mark, which the field's own token follows (FLD-6); the first mark named tag.	<Field label="Volume" supportingText="…"><Slider … /></Field>; the glyph is the labelIcon prop (a glyph name). The one child receives the name, the description and the states through FieldContext (Tanrei controls read it; a control the product built calls useField()), and on Android the label is also tied with accessibilityLabelledBy. Follows the app's direction where an ancestor's is not known. The product's words are read from the TanreiWordsProvider context. Not built on this platform yet: the supporting row is a column of the help and, in error, the error text — in the help's place, or comp.field.error-text.gap below it, as comp.field.error-text.placement names (FLD-7); the description given through FieldContext is what the row draws, then the optional text (FLD-11, FLD-31). Not built on this platform yet: the requirement tag as this platform's Tag at its small size with nothing of the field's set on it (FLD-5); generated tokens with none of the field's values for it and with the system's choice of mark, which the field's own token follows (FLD-6); the first mark named tag.

الرموز

الرمز	يشير إلى	القيمة المحلولة (فاتح)
--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

نماذج الاختبار

عروض مرجعية. تلتقط كل المنصات لقطة لكل نموذج بالمعرّف نفسه حتى يمكن مقارنة النتائج.

slider

label: Volume items: 1

slider-supporting

label: Volume supportingText: Applies to alerts and media. valueText: 40 items: 1

slider-required

label: Volume required: true requiredText: Required valueText: 40 items: 1

slider-optional

label: Volume optional: true optionalText: Optional valueText: 40 items: 1

slider-required-asterisk

label: Volume required: true requiredMark: asterisk valueText: 40 items: 1

slider-error

label: Volume supportingText: Applies to alerts and media. errorText: Choose a level above 0. error: true valueText: 0 items: 1

slider-required-error

label: Volume errorText: Choose a level above 0. error: true required: true requiredText: Required valueText: 0 items: 1

slider-error-without-text

label: Volume supportingText: Applies to alerts and media. error: true valueText: 0 items: 1

slider-disabled

label: Volume supportingText: Applies to alerts and media. disabled: true valueText: 40 items: 1

slider-required-disabled

label: Volume disabled: true required: true requiredText: Required items: 1

slider-label-hidden

label: Volume labelHidden: true supportingText: Applies to alerts and media. items: 1

slider-label-icon

label: Volume valueText: 40 items: 1 slots: label-icon

slider-required-label-icon

label: Volume required: true requiredText: Required items: 1 slots: label-icon

switch

label: Notifications supportingText: Sent when a review is waiting for you. items: 1

switch-optional

label: Notifications optional: true optionalText: Optional items: 1

checkbox-own-label

supportingText: You can withdraw at any time. items: 1

checkbox-own-label-error

supportingText: You can withdraw at any time. errorText: Accept the terms to continue. error: true items: 1

long-label

label: How loud alerts, calls and media are pla… supportingText: A level the connected device cannot play… required: true requiredText: Required valueText: 40 items: 1

slider-required-ja

label: 音量 supportingText: 通知とメディアに適用されます。 required: true requiredText: 必須 valueText: 40 items: 1

slider-optional-ja

label: 音量 optional: true optionalText: 任意 items: 1

slider-error-ja

label: 音量 errorText: 0 より大きい値を選んでください。 error: true required: true requiredText: 必須 valueText: 0 items: 1

slider-rtl

label: مستوى الصوت supportingText: ينطبق على التنبيهات والوسائط. required: true requiredText: مطلوب valueText: 40 direction: rtl items: 1 slots: label-icon

slider-error-rtl

label: עוצמת קול errorText: יש לבחור רמה מעל 0. error: true optional: true optionalText: רשות valueText: 0 direction: rtl items: 1

ltr-label-rtl

label: Bluetooth 5.3 supportingText: LE Audio, 2 Mbps direction: rtl items: 1

code-supporting

label: Verification code supportingText: Enter the 6-digit code we sent to your p… items: 1

code-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 items: 1

code-disabled

label: Verification code supportingText: Enter the 6-digit code we sent to your p… disabled: true items: 1

code-required-rtl

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

file-upload-required-error

label: Attachment errorText: Choose a PDF of 10 MB or less. error: true required: true requiredText: Required items: 1

file-picker-required-error

label: Attachment errorText: Choose a PDF of 10 MB or less. error: true required: true requiredText: Required items: 1

text-outlined-empty

label: Email items: 1

text-outlined-filled

label: Email items: 1

text-filled-empty

label: Email items: 1

text-filled-filled

label: Email items: 1

text-outlined-large

label: Email items: 1

text-filled-large

label: Email items: 1

text-outlined-label-hidden

label: Search labelHidden: true items: 1

text-outlined-supporting

label: Email supportingText: We only use it to sign you in. items: 1

text-outlined-error

label: Email errorText: Enter a complete email address. error: true items: 1

text-outlined-supporting-error

label: Email supportingText: We never share your address. errorText: Enter a complete email address. error: true items: 1

text-filled-error

label: Email errorText: Enter a complete email address. error: true items: 1

text-outlined-disabled

label: Email disabled: true items: 1

text-filled-disabled

label: Email disabled: true items: 1

text-outlined-read-only

label: Email items: 1

text-outlined-icons

label: Search items: 1

text-outlined-affixes

label: Amount items: 1

text-outlined-counter

label: Display name countText: 12/40 items: 1

text-outlined-multiline

label: Message items: 1

text-filled-multiline

label: Message items: 1

text-outlined-password

label: Password items: 1

text-stacked-empty

label: Email items: 1

text-stacked-filled

label: Email items: 1

text-stacked-placeholder

label: Email items: 1

text-stacked-large

label: Email items: 1

text-stacked-small

label: Search items: 1

text-stacked-label-hidden

label: Search labelHidden: true items: 1

text-stacked-supporting

label: Email supportingText: We never share your address. items: 1

text-stacked-error

label: Email errorText: Enter a complete address. error: true items: 1

text-stacked-supporting-error

label: Password supportingText: At least 8 characters, with one number. errorText: This password is too short. error: true items: 1

text-stacked-supporting-error-long

label: Billing address supportingText: Use the address your bank has on file, w… errorText: We could not find this address. Check th… error: true items: 1

text-stacked-supporting-error-rtl

label: סיסמה supportingText: לפחות 8 תווים, כולל ספרה אחת. errorText: הסיסמה קצרה מדי. error: true direction: rtl items: 1

text-stacked-disabled

label: Email disabled: true items: 1

text-stacked-read-only

label: Email items: 1

text-stacked-icons

label: Search items: 1

text-stacked-label-icon

label: Display name items: 1 slots: label-icon

text-stacked-affixes

label: Amount items: 1

text-stacked-counter

label: Display name countText: 12/40 items: 1

text-stacked-supporting-error-counter

label: Display name supportingText: Shown beside your posts. errorText: This name is taken. Choose another. error: true countText: 3/40 items: 1

text-stacked-multiline

label: Message items: 1

text-stacked-password

label: Password items: 1

text-stacked-date

label: Start date items: 1

text-stacked-date-empty

label: Start date items: 1

text-stacked-date-picker

label: Start date items: 1

text-stacked-date-picker-large

label: Start date items: 1

text-stacked-date-ja

label: 開始日 items: 1

text-stacked-time-picker

label: Start time items: 1

text-stacked-date-time-picker

label: Starts items: 1

text-stacked-date-error

label: Start date errorText: Choose a date after today. error: true items: 1

text-stacked-date-disabled

label: Start date disabled: true items: 1

text-outlined-date-picker

label: Start date items: 1

text-stacked-multiline-auto-grown

label: Message items: 1

text-stacked-multiline-auto-grown-icons

label: Message items: 1

text-stacked-multiline-auto-max

label: Message items: 1

text-stacked-multiline-manual

label: Message items: 1

text-stacked-multiline-manual-both

label: Message items: 1

text-stacked-multiline-manual-rtl

label: הודעה direction: rtl items: 1

text-stacked-multiline-fixed

label: Message items: 1

text-outlined-multiline-manual

label: Message items: 1

text-stacked-time-empty

label: Start time items: 1

text-stacked-time-24h

label: 開始時刻 items: 1

text-stacked-date-rtl

label: תאריך התחלה direction: rtl items: 1

text-stacked-required

label: Email required: true requiredText: Required items: 1

text-stacked-optional

label: Company optional: true optionalText: Optional items: 1

text-stacked-required-asterisk

label: Email required: true requiredMark: asterisk items: 1

text-stacked-required-ja

label: 氏名 required: true requiredText: 必須 items: 1

text-stacked-optional-ja

label: 会社名 optional: true optionalText: 任意 items: 1

text-stacked-required-label-icon

label: Display name required: true requiredText: Required items: 1 slots: label-icon

text-stacked-required-error

label: Email errorText: Enter your email address. error: true required: true requiredText: Required items: 1

text-stacked-required-disabled

label: Email disabled: true required: true requiredText: Required items: 1

text-stacked-required-rtl

label: אימייל required: true requiredText: חובה direction: rtl items: 1

text-outlined-required

label: Email required: true requiredText: Required items: 1

text-outlined-optional

label: Company optional: true optionalText: Optional items: 1

text-stacked-code

label: Pattern items: 1

text-stacked-code-empty

label: Pattern items: 1

text-stacked-code-large

label: Pattern items: 1

text-stacked-code-affixes

label: Pattern supportingText: A regular expression, matched against a… items: 1

text-stacked-code-multiline

label: Layer items: 1

text-stacked-code-multiline-empty

label: Layer items: 1

text-stacked-code-multiline-wrap

label: Rule items: 1

text-stacked-code-multiline-nowrap

label: Rule items: 1

text-stacked-code-multiline-tabs

label: Recipe items: 1

text-stacked-code-multiline-error

label: Layer errorText: Line 3: a name was expected before }. error: true items: 1

text-stacked-code-multiline-counter

label: Layer countText: 41/200 items: 1

text-stacked-code-multiline-manual

label: Rule items: 1

text-stacked-code-multiline-read-only

label: Rule items: 1

text-stacked-code-multiline-disabled

label: Layer disabled: true items: 1

text-outlined-code-multiline

label: Layer items: 1

text-filled-code-multiline

label: Layer items: 1

text-stacked-code-rtl

label: النمط supportingText: معرّف رمز، مع * لأي جزء. direction: rtl items: 1

text-stacked-code-empty-rtl

label: النمط direction: rtl items: 1

text-stacked-code-affixes-rtl

label: النمط direction: rtl items: 1

text-stacked-code-multiline-rtl

label: الطبقة supportingText: الصق ملف الطبقة هنا. required: true requiredText: مطلوب countText: 41/200 direction: rtl items: 1

text-stacked-code-multiline-empty-rtl

label: الطبقة direction: rtl items: 1

text-stacked-code-multiline-brace-rtl

label: الطبقة direction: rtl items: 1

text-stacked-code-multiline-arabic-first-rtl

label: المصادر direction: rtl items: 1

text-stacked-code-multiline-nowrap-rtl

label: القاعدة errorText: السطر 2: القاعدة ينقصها سبب. error: true direction: rtl items: 1

text-stacked-code-multiline-manual-rtl

label: الطبقة direction: rtl items: 1

slider-value-text

label: Volume valueText: 40 items: 1

slider-value-words

label: Text size valueText: 120 % items: 1

slider-value-indicator

label: Volume valueText: 40 items: 1

slider-range

label: Price valueText: 20 – 60 items: 1

slider-range-words

label: Price supportingText: Per night, before taxes. valueText: $100 – $300 items: 1

slider-long-value-text

label: Yearly income before tax valueText: 3,400,000 – 12,500,000 items: 1

slider-range-rtl

label: السعر valueText: $100 – $300 direction: rtl items: 1

number-stacked-empty

label: Quantity items: 1

number-stacked-value

label: Quantity items: 1

number-stacked-placeholder

label: Quantity items: 1

number-stacked-large

label: Quantity items: 1

number-stacked-label-hidden

label: Quantity labelHidden: true items: 1

number-stacked-supporting

label: Quantity supportingText: Up to 99 per order. items: 1

number-stacked-error

label: Quantity supportingText: Up to 99 per order. errorText: Order at least 1. error: true items: 1

number-stacked-disabled

label: Quantity disabled: true items: 1

number-stacked-read-only

label: Quantity items: 1

number-stacked-at-min

label: Quantity items: 1

number-stacked-at-max

label: Quantity items: 1

number-stacked-no-steppers

label: Quantity items: 1

number-stacked-unit

label: Corner radius items: 1

number-stacked-percent

label: Opacity items: 1

number-stacked-prefix

label: Amount items: 1

number-stacked-negative-decimal

label: Letter spacing items: 1

number-stacked-align-end

label: Tone items: 1

number-stacked-long-number

label: Population items: 1

number-stacked-label-icon

label: Duration items: 1 slots: label-icon

number-stacked-required

label: Quantity required: true requiredText: Required items: 1

number-stacked-optional

label: Quantity optional: true optionalText: Optional items: 1

number-stacked-required-asterisk

label: Quantity required: true requiredMark: asterisk items: 1

number-stacked-required-error

label: Quantity errorText: Enter how many you need. error: true required: true requiredText: Required items: 1

number-stacked-required-disabled

label: Quantity disabled: true required: true requiredText: Required items: 1

number-stacked-required-label-icon

label: Duration required: true requiredText: Required items: 1 slots: label-icon

number-stacked-required-ja

label: 数量 required: true requiredText: 必須 items: 1

number-stacked-optional-ja

label: 数量 supportingText: 1 回の注文で 99 個まで。 optional: true optionalText: 任意 items: 1

number-stacked-locale-de

label: Gewicht items: 1

number-stacked-locale-ar

label: الكمية direction: rtl items: 1

number-stacked-required-rtl

label: الكمية supportingText: حتى 99 لكل طلب. required: true requiredText: مطلوب direction: rtl items: 1 slots: label-icon

number-stacked-unit-rtl

label: רוחב direction: rtl items: 1

number-stacked-error-rtl

label: כמות errorText: יש להזמין לפחות 1. error: true optional: true optionalText: רשות direction: rtl items: 1

number-long-label

label: How many copies of the printed annual re… supportingText: Each copy is 180 pages; orders of more t… required: true requiredText: Required items: 1

number-beside-slider

label: Scale labelHidden: true items: 1

number-filled-empty

label: Quantity items: 1

number-filled-value

label: Quantity items: 1

number-filled-large

label: Quantity items: 1

number-filled-error

label: Quantity errorText: Order at least 1. error: true items: 1

number-filled-disabled

label: Quantity disabled: true items: 1

number-filled-unit

label: Corner radius items: 1

number-outlined-empty

label: Quantity items: 1

number-outlined-value

label: Quantity items: 1

number-outlined-large

label: Quantity items: 1

number-outlined-error

label: Quantity errorText: Order at least 1. error: true items: 1

number-outlined-disabled

label: Quantity disabled: true items: 1

number-outlined-required

label: Quantity required: true requiredText: Required items: 1

color-stacked-empty

label: Brand color items: 1

color-stacked-filled

label: Brand color items: 1

color-stacked-large

label: Brand color items: 1

color-stacked-label-hidden

label: Brand color labelHidden: true items: 1

color-stacked-supporting

label: Brand color supportingText: Six hexadecimal digits, like #0f766e. items: 1

color-stacked-white

label: Page background items: 1

color-stacked-black

label: Text items: 1

color-stacked-picker

label: Brand color items: 1

color-stacked-picker-empty

label: Brand color items: 1

color-stacked-picker-large

label: Brand color items: 1

color-stacked-error

label: Brand color errorText: Too light for white text. Choose a darke… error: true items: 1

color-stacked-error-picker

label: Brand color errorText: Too light for white text. Choose a darke… error: true items: 1

color-stacked-disabled

label: Brand color disabled: true items: 1

color-stacked-picker-disabled

label: Brand color disabled: true items: 1

color-stacked-label-icon

label: Brand color items: 1 slots: label-icon

color-stacked-required

label: Brand color required: true requiredText: Required items: 1

color-stacked-optional

label: Accent color optional: true optionalText: Optional items: 1

color-stacked-required-asterisk

label: Brand color required: true requiredMark: asterisk items: 1

color-stacked-required-label-icon

label: Brand color required: true requiredText: Required items: 1 slots: label-icon

color-stacked-required-error

label: Brand color errorText: Choose a brand color. error: true required: true requiredText: Required items: 1

color-stacked-required-disabled

label: Brand color disabled: true required: true requiredText: Required items: 1

color-stacked-required-ja

label: ブランドカラー required: true requiredText: 必須 items: 1

color-stacked-optional-ja

label: アクセントカラー supportingText: # と 6 桁の 16 進数で入力します。 optional: true optionalText: 任意 items: 1

color-stacked-required-rtl

label: لون العلامة required: true requiredText: مطلوب direction: rtl items: 1

color-stacked-error-rtl

label: צבע המותג errorText: בהיר מדי לטקסט לבן. בחרו צבע כהה יותר. error: true direction: rtl items: 1 slots: label-icon

color-ltr-label-rtl

label: Brand color (HEX) supportingText: sRGB, 6 digits direction: rtl items: 1

color-long-label

label: The color of the primary buttons, the li… supportingText: Six hexadecimal digits after a number si… required: true requiredText: Required items: 1

color-filled-empty

label: Brand color items: 1

color-filled-filled

label: Brand color items: 1

color-filled-picker

label: Brand color items: 1

color-filled-error

label: Brand color errorText: Too light for white text. Choose a darke… error: true items: 1

color-filled-disabled

label: Brand color disabled: true items: 1

color-outlined-empty

label: Brand color items: 1

color-outlined-filled

label: Brand color items: 1

color-outlined-large

label: Brand color items: 1

color-outlined-picker

label: Brand color items: 1

color-outlined-error

label: Brand color errorText: Too light for white text. Choose a darke… error: true items: 1

color-outlined-disabled

label: Brand color disabled: true items: 1

color-outlined-required

label: Brand color required: true requiredText: Required items: 1

select-stacked-empty

label: Country items: 1

select-stacked-value

label: Country items: 1

select-stacked-open

label: Country items: 1

select-stacked-large

label: Country items: 1

select-stacked-small

label: Country items: 1

select-stacked-error

label: Country errorText: Choose a country. error: true items: 1

select-stacked-disabled

label: Country disabled: true items: 1

select-filled-empty

label: Country items: 1

select-filled-value

label: Country items: 1

select-filled-open

label: Country items: 1

select-filled-large

label: Country items: 1

select-filled-small

label: Country items: 1

select-filled-error

label: Country errorText: Choose a country. error: true items: 1

select-filled-disabled

label: Country disabled: true items: 1

select-outlined-empty

label: Country items: 1

select-outlined-value

label: Country items: 1

select-outlined-open

label: Country items: 1

select-outlined-large

label: Country items: 1

select-outlined-small

label: Country items: 1

select-outlined-error

label: Country errorText: Choose a country. error: true items: 1

select-outlined-disabled

label: Country disabled: true items: 1

select-stacked-placeholder

label: Country items: 1

select-stacked-open-none-chosen

label: Country items: 1

select-stacked-label-hidden

label: Country labelHidden: true items: 1

select-stacked-supporting

label: Country supportingText: Where your invoices are addressed. items: 1

select-stacked-error-value

label: Country errorText: We cannot ship there yet. error: true items: 1

select-stacked-read-only

label: Country items: 1

select-stacked-required

label: Country required: true requiredText: Required items: 1

select-stacked-optional

label: Country optional: true optionalText: Optional items: 1

select-stacked-required-asterisk

label: Country required: true requiredMark: asterisk items: 1

select-stacked-required-disabled

label: Country disabled: true required: true requiredText: Required items: 1

select-stacked-required-error

label: Country errorText: Choose a country. error: true required: true requiredText: Required items: 1

select-stacked-required-ja

label: 国 required: true requiredText: 必須 items: 1

select-stacked-optional-ja

label: 国 optional: true optionalText: 任意 items: 1

select-outlined-required

label: Country required: true requiredText: Required items: 1

select-stacked-label-icon

label: Time zone items: 1 slots: label-icon

select-stacked-option-icon

label: Theme items: 1

select-stacked-leading-icon

label: Language items: 1

select-open-icons

label: Theme items: 1

select-open-supporting-text

label: Plan items: 1

select-open-disabled-chosen

label: Plan items: 1

select-open-groups

label: Time zone items: 1

select-open-groups-divider

label: Time zone items: 1

select-open-groups-gap

label: Time zone items: 1

select-open-many

label: Token items: 1

select-open-long-options

label: Email me items: 1

select-long-value

label: Email me items: 1

select-empty-value-option

label: Contrast items: 1

select-small-label-hidden

label: Contrast labelHidden: true items: 1

select-small-label-hidden-icons

label: Theme labelHidden: true items: 1

select-small-label-hidden-leading-icon

label: Language labelHidden: true items: 1

select-small-label-hidden-open

label: Theme labelHidden: true items: 1

select-small-open

label: Country items: 1

select-stacked-required-rtl

label: المنطقة الزمنية supportingText: تُعرض المواعيد بهذا التوقيت. required: true requiredText: مطلوب direction: rtl items: 1 slots: label-icon

select-open-rtl

label: المنطقة الزمنية direction: rtl items: 1

select-long-value-rtl

label: Email me direction: rtl items: 1

select-outlined-rtl

label: المنطقة الزمنية direction: rtl items: 1

combobox-stacked-empty

label: City items: 1

combobox-stacked-value

label: City items: 1

combobox-stacked-open

label: City items: 1

combobox-stacked-large

label: City items: 1

combobox-stacked-error

label: City errorText: Choose the city you are sending to. error: true items: 1

combobox-stacked-disabled

label: City disabled: true items: 1

combobox-stacked-placeholder

label: City items: 1

combobox-stacked-label-hidden

label: City labelHidden: true items: 1

combobox-stacked-supporting

label: City supportingText: Where the order is sent. items: 1

combobox-stacked-error-value

label: City supportingText: Where the order is sent. errorText: We do not deliver to Nairobi yet. error: true items: 1

combobox-stacked-read-only

label: City items: 1

combobox-stacked-clearable

label: City items: 1

combobox-stacked-no-chevron

label: Address items: 1

combobox-stacked-custom-value

label: Font family items: 1

combobox-stacked-required

label: City required: true requiredText: Required items: 1

combobox-stacked-optional

label: City optional: true optionalText: Optional items: 1

combobox-stacked-required-asterisk

label: City required: true requiredMark: asterisk items: 1

combobox-stacked-required-error

label: City errorText: Choose the city you are sending to. error: true required: true requiredText: Required items: 1

combobox-stacked-required-disabled

label: City disabled: true required: true requiredText: Required items: 1

combobox-stacked-label-icon

label: City items: 1 slots: label-icon

combobox-stacked-leading-icon

label: Assignee items: 1

combobox-stacked-option-icon

label: Transport items: 1

combobox-open-none-chosen

label: City items: 1

combobox-open-filtered

label: City items: 1

combobox-open-filtered-none

label: City items: 1

combobox-open-icons

label: Transport items: 1

combobox-open-supporting-text

label: Token items: 1

combobox-open-disabled-chosen

label: Token items: 1

combobox-open-groups

label: Time zone items: 1

combobox-open-groups-divider

label: Time zone items: 1

combobox-open-groups-gap

label: Time zone items: 1

combobox-open-groups-filtered

label: Time zone items: 1

combobox-open-many

label: City items: 1

combobox-open-long-options

label: Licence items: 1

combobox-open-custom-suggestions

label: Font family items: 1

combobox-open-loading

label: Assignee items: 1

combobox-open-status

label: Assignee items: 1

combobox-open-status-error

label: Assignee items: 1

combobox-long-value

label: Licence items: 1

combobox-long-label

label: Which of the cities we deliver to is nea… supportingText: If none of them is near enough, leave th… required: true requiredText: Required items: 1

combobox-stacked-required-ja

label: 都市 required: true requiredText: 必須 items: 1

combobox-open-filtered-ja

label: 都市 optional: true optionalText: 任意 items: 1

combobox-stacked-required-rtl

label: المدينة supportingText: إلى أين نرسل الطلب. required: true requiredText: مطلوب direction: rtl items: 1 slots: label-icon

combobox-open-rtl

label: المنطقة الزمنية direction: rtl items: 1

combobox-long-value-rtl

label: רישיון direction: rtl items: 1

combobox-stacked-error-rtl

label: עיר errorText: יש לבחור עיר מהרשימה. error: true optional: true optionalText: רשות direction: rtl items: 1

combobox-filled-empty

label: City items: 1

combobox-filled-value

label: City items: 1

combobox-filled-open

label: City items: 1

combobox-filled-large

label: City items: 1

combobox-filled-error

label: City errorText: Choose the city you are sending to. error: true items: 1

combobox-filled-disabled

label: City disabled: true items: 1

combobox-outlined-empty

label: City items: 1

combobox-outlined-value

label: City items: 1

combobox-outlined-open

label: City items: 1

combobox-outlined-large

label: City items: 1

combobox-outlined-error

label: City errorText: Choose the city you are sending to. error: true items: 1

combobox-outlined-disabled

label: City disabled: true items: 1

combobox-outlined-required

label: City required: true requiredText: Required items: 1

combobox-outlined-rtl

label: المدينة direction: rtl items: 1

entries-email-empty

label: Recipients supportingText: Separate addresses with a comma. items: 1

entries-email-entries

label: Recipients items: 1

entries-email-typing

label: Recipients supportingText: Separate addresses with a comma. items: 1

entries-email-refused

label: Recipients supportingText: Separate addresses with a comma. errorText: Enter a full address, such as name@examp… error: true items: 1

entries-email-error

label: Recipients errorText: [email protected] could not be re… error: true items: 1

entries-email-required

label: Recipients required: true requiredText: Required items: 1

entries-email-required-empty-error

label: Recipients errorText: Add at least one address. error: true required: true requiredText: Required items: 1

entries-email-optional

label: Cc optional: true optionalText: Optional items: 1

entries-email-limit

label: Recipients supportingText: Up to 3 addresses. items: 1

entries-email-many

label: Recipients items: 1

entries-email-many-typing

label: Recipients items: 1

entries-email-long-entry

label: Recipients items: 1

entries-email-large

label: Recipients items: 1

entries-email-filled

label: Recipients items: 1

entries-email-filled-empty

label: Recipients items: 1

entries-email-outlined

label: Recipients items: 1

entries-email-disabled

label: Recipients supportingText: Separate addresses with a comma. disabled: true items: 1

entries-email-disabled-empty

label: Recipients disabled: true items: 1

entries-email-read-only

label: Recipients items: 1

entries-email-label-hidden

label: Recipients labelHidden: true items: 1

entries-email-label-icon

label: Recipients items: 1 slots: label-icon

entries-keywords

label: Keywords supportingText: Press Enter or type a comma after each k… items: 1

entries-keywords-enter-only

label: Authors supportingText: Press Enter after each name. items: 1

entries-telephone

label: Numbers to notify items: 1

entries-keywords-ja

label: キーワード supportingText: キーワードごとに Enter を押してください。 required: true requiredText: 必須 items: 1

entries-keywords-rtl

label: الكلمات المفتاحية supportingText: اضغط Enter بعد كل كلمة. direction: rtl items: 1

entries-email-rtl

label: נמענים errorText: יש להזין כתובת מלאה, למשל [email protected]… error: true direction: rtl items: 1

chat-composer-supporting

label: Message supportingText: Everyone in this channel can read it. items: 1

number-stacked-unit-own-script-rtl

label: الوزن direction: rtl items: 1

number-stacked-prefix-rtl

label: المبلغ direction: rtl items: 1

number-stacked-percent-rtl

label: العتامة direction: rtl items: 1

number-stacked-align-end-unit-rtl

label: גודל direction: rtl items: 1

مولَّد من specs/field.spec.json, tokens/comp/field.tokens.json, design/tokens/

الإرشادات

link

حقل، أم عنصر تحكم هو نفسه حقل

link

عنصر التحكم	استخدم
ليس له تسمية ولا مساعدة ولا خطأ من عنده: شريط تمرير، أو مفتاح تبديل، أو عنصر تحكم بنيته أنت	حقلًا حوله. أو، لشريط التمرير، الحقل الذي يجمع الاثنين في مكوّن واحد: حقل شريط التمرير.
عنصر تحكم للكتابة مجرَّدًا: حقل إدخال النص، أو حقل إدخال اللون، أو حقل إدخال الرمز لمرة واحدة	حقلًا حوله. أو الحقل الذي يجمع الاثنين في مكوّن واحد: حقل النص، أو حقل اللون، أو حقل الرمز لمرة واحدة.
عنصر الاختيار مجرَّدًا	حقلًا حوله. أو الاثنين في مكوّن واحد: حقل الاختيار.
حقل أصلًا: حقل النص، وحقل الرمز لمرة واحدة، وحقل شريط التمرير، وحقل الاختيار، وأي عنصر تحكم له خاصية supportingText من عنده	عنصر التحكم وحده. لا تضعه في حقل أبدًا.
يسمّي نفسه بتسمية بجانبه: خانة اختيار، أو مفتاح تبديل له تسميته	حقلًا خاصيته label فارغة، حين يحتاج إلى مساعدة أو خطأ.
مجموعة من عناصر التحكم تجيب عن سؤال واحد	مجموعة حقول.

القاعدة العملية: إن كانت لعنصر التحكم خاصية supportingText فلا يحتاج إلى حقل.

مطلوب واختياري

link

الخاصيتان required و optional تقولان ما يطلبه النموذج من عنصر التحكم. فالخاصية required، وهي الاسم الذي تعطيه HTML لها، تعرض عنصر التحكم على أنه مطلوب وترسم علامة المطلوب: <tanrei-field label="البريد" required>. والخاصية optional ترسم وسم الاختياري. وعنصر التحكم لا يكون الاثنين معًا أبدًا: فإن عُيِّنتا كلتاهما كان مطلوبًا، وتبلّغ بنية التطوير بأن optional مُهمَلة. وفي React هما خاصيتان (prop) كما تكون required على <input>.

• القيمة required تعرض عنصر التحكم على أنه مطلوب وترسم علامة المطلوب بجانب التسمية.
• القيمة optional ترسم وسمًا هادئًا وتضيف نصه إلى وصف عنصر التحكم.
• لا تتحقق أي منهما من شيء. الإجابة الناقصة أنت من يبلّغ عنها، بالخاصيتين error و errorText.

كيف يُعلَّم عنصر التحكم المطلوب اختيار واحد يختاره نظام التصميم، لكل حقل ولكل مجموعة من عناصر التحكم: رمز التصميم sys.behavior.requirement-mark، وقيمه tag (وسم صغير من الطراز filled يقول «مطلوب») و asterisk و none. والنظام الافتراضي يعلِّم بالوسم. ونظام التصميم يعيّن هذا الرمز الواحد ليغيّر كل النماذج دفعة واحدة. والحقل يقرؤه عبر رمز خاص به، comp.field.requirement.mark، وهو يتبعه؛ ولا يعيّن نظام التصميم ذلك الرمز إلا ليعلِّم الحقول المفردة بغير ما يعلِّم به مجموعات عناصر التحكم. والخاصية requiredMark تتجاوز الاثنين لحقل واحد (tag أو asterisk أو none).

وسم المطلوب أو الاختياري وسم صغير، من الطراز filled للمطلوب ومن الطراز tonal للاختياري، ولا شيء غير ذلك: فليست للحقل رموز تصميم له. ونظام التصميم الذي يعيد تنسيق وسومه الصغيرة يعيد تنسيق وسم المطلوب أو الاختياري معها، ومظهره واحد والحقل في حالة التركيز أو في حالة الخطأ؛ وما دام الحقل معطَّلًا يُرسم وسمًا داخل شيء معطَّل، فيبهت مع التسمية التي يتبعها. وكلمات الوسم كلماتك: requiredText و optionalText على الحقل، أو مرة واحدة للمنتج كله بالدالة setWords(). لا يتضمن Tanrei أي كلمة: من دون requiredText تقف نجمة في مكان الوسم، ومن دون optionalText لا يُرسم وسم.

علِّم المجموعة الأصغر. في نموذج تجب الإجابة عن كل ما فيه تقريبًا علِّم الاختياري؛ وحيث لا يجب إلا القليل علِّم المطلوب.

المساعدة والأخطاء

link

• الخاصية supportingText تقول كيف يُجاب: صيغة، أو مدى، أو ما تُستخدم القيمة له.
• الخاصية errorText تقول ما الخطأ في هذه الإجابة وكيف يُصحَّح، بالكلمات. وما دامت error بالقيمة true تأخذ مكان المساعدة، فأعِد فيها ما قالته المساعدة حيث يظل مهمًّا: «أدخل تاريخًا بعد اليوم»، لا «تاريخ غير صالح».
• موضع نص الخطأ اختيار واحد يختاره نظام التصميم، comp.field.error-text.placement. القيمة replace، وهي الافتراضية، تضعه في مكان المساعدة: سطر واحد يُقرأ، ولا يزيد ارتفاع الحقل في حالة الخطأ عنه في الراحة. والقيمة append تُبقي المساعدة وتضيف نص الخطأ تحتها، على بعد فجوة صغيرة (comp.field.error-text.gap): فيزيد ارتفاع الحقل ما دام في حالة الخطأ، ولا يتحرك شيء مما فوق نص الخطأ. كل نظام مشحون مع Tanrei يستخدم replace، كما يفعل Material و Carbon؛ والقيمة append لنظام تصميم يُبقي المساعدة ظاهرة، كنظام GOV.UK.
• لا يُحجز مكان لخطأ قبل وجوده. والحقل الذي ليست له مساعدة يعرض نص الخطأ حيث كانت المساعدة ستكون.
• العدد يبقى في نهاية السطر الأول حين يظهر نص الخطأ أو يزول.
• عيِّن error حين تكون قد تحققت، لا والشخص ما زال يجيب. الحقل لا يعيّنها أبدًا.

عنصر تحكم واحد

link

الحقل يؤطّر عنصر تحكم واحدًا بالضبط، هو العنصر الوحيد في منفذه الافتراضي. وإن كانت فيه عدة عناصر سمّى الأول وحده ووصفه وقال ذلك في بنيات التنقيح (debug): فمجموعة عناصر التحكم مجموعة حقول.

عطِّل عنصر التحكم المؤطَّر من الحقل، لا من عنصر التحكم نفسه، لتتبعه التسمية والمساعدة.

افعل

link

• اكتب تسمية تسمّي المطلوب إدخاله، في بضع كلمات، وأبقِها مرئية. لا تستخدم labelHidden إلا حيث تقف تسمية مرئية لعنصر التحكم نفسه في مكان آخر، كترويسة عمود في جدول.
• اجعل الحقول التي في عمود واحد بعرض واحد، لتصطفّ تسمياتها وعناصر التحكم فيها.

لا تفعل

link

• لا تضع حقل نص، ولا أي عنصر تحكم يرسم تسميته ومساعدته بنفسه، داخل حقل. ستحصل على تسميتين، وبنية التنقيح تقول ذلك. وعنصر التحكم الذي يؤطّره الحقل هو المجرَّد: حقل إدخال النص.
• لا تستخدم التسمية للتعليمات. فذلك ما وُجد له النص المساعد.
• لا تعتمد على لون الخطأ. اكتب الخطأ.

إمكانية الوصول

link

الدور

none

التسمية

The field has no role of its own: it is a frame, and assistive technology meets the control. label is the control's accessible name, drawn or not (labelHidden), unless the control names itself. The control's description is what the supporting row draws — the help (supportingText) and, while the field is in error, the error text in its place or after it (FLD-11) — then optionalText while optional is true. The control is exposed as invalid while error is true, as required while required is true — whichever mark is drawn, and the mark itself is hidden — and as disabled while disabled is true. The label glyph is decorative.

الحد الأدنى للهدف

تستوفي مساحة اللمس الحد الأدنى لحجم الهدف حتى لو كان الحجم المرئي أصغر. minimum 32px · pointer 44px · spacing 8px · touch 48px

لوحة المفاتيح

المفاتيح	الإجراء

ملاحظات

• Not interactive by itself: the field takes no focus and adds no key (FLD-12), so it has no target of its own to size and minimumTarget holds through its control, whose own spec sizes its hit area. A press on the label moves focus to the control and never operates it; the label therefore widens where a pointer can land without widening what a press does.
• There is one frame: a composed field — a text field — is this Field around its one control and draws no rows of its own. No component draws these rows itself; a composed field placed inside a field is reported (FLD-15).
• Each platform carries the name, the description and the three states to the control in its own way, and a control the product built receives them the same way a Tanrei control does: on the web as ARIA attributes on the slotted element; in SwiftUI through the environment and the accessibility modifiers of the framed view; in Compose through a composition local and merged semantics; in Flutter through an inherited widget and a Semantics node around the control; in React Native through a context and the accessibility props of the wrapper.
• Errors are words (WCAG 3.3.1, 1.4.1): errorText says what is wrong and how to put it right, the control is exposed as invalid, and the error color is one more sign, never the only one. The error text is announced when it appears under the person's focus and is otherwise read with the control (FLD-9); it never takes focus away.
• After a failed submission a product should also say, above the form, how many answers were refused and link to each: that summary is a live Callout in its error status, not a part of any field. The field does not build it, because only the form knows all of its errors.
• While the field is in error the error text takes the help's place under the default system (comp.field.error-text.placement replace): the one line below the control then says what is wrong, and a form in error is no taller than at rest; errorText should then also say how to put the answer right, because the help is not drawn. A design system that keeps the help in view while the person corrects the answer chooses append: the help stays and the error text is added below it, and a field with a help is taller in error by the error text and its gap. Under both, nothing above the error text moves, and no room is held open before an error exists. A field group keeps its description and gives its error a row of its own (FGR-7, FGR-8).
• An asterisk alone does not explain itself: a product that marks required controls with an asterisk says what it means once, near the top of the form. The tag says it in words.
• Heights are the texts': at 200% text size the label and the supporting row wrap and the field grows; nothing is cut (WCAG 1.4.4, 1.4.10).
• Forced colors (FLD-17): the error and the help then look alike, which is why the error must be in words and in the invalid state.
• 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.
• A control can say three things back to its field, each by the same channel the field names it by: that it draws the label itself (FLD-25), where its content starts and ends (FLD-26) and a refusal of an entry (FLD-28). They are what makes a Field around a text input by hand the same picture as a text field; a control that says none of them is framed as before.
• A place for words about the control's value is a prop of the field, named for what it holds: the field draws the words it is given, never reads, counts or formats a value, and keeps the drawn text from assistive technology, because the control says the same itself. countText is the first such place (FLD-27). A composed field fills it from its control (a text field, TXF-67); a product that writes the pair by hand writes it, at each change.
• valueText is a place for words about the control's value (FLD-29, FLD-30): the field draws the words it is given at the end of the label row, never reads or formats a value, and keeps the drawn text from assistive technology, because the control says its own value. A slider field fills it from its slider (SLF-3); a product that writes the pair by hand writes it, at each change.

مولَّد من specs/field.spec.json, tokens/sys/measure.tokens.json

ما يتكفل به المكوّن

link

• التسمية هي الاسم المتاح للتقنيات المساعدة لعنصر التحكم، سواء رُسمت أم أُخفيت بالخاصية labelHidden. وعنصر التحكم الذي له اسم من عنده يحتفظ به.
• وصف عنصر التحكم هو ما يعرضه صف النص المساعد — المساعدة، أو ما دام الحقل في حالة الخطأ نص الخطأ في مكانها (ومع append، المساعدة ثم نص الخطأ) — ثم optionalText ما دام عنصر التحكم اختياريًّا. وهي تأتي بعد أي وصف لعنصر التحكم من قبل.
• يُعرض عنصر التحكم على أنه غير صالح ما دامت error بالقيمة true، وعلى أنه مطلوب ما دامت required معيَّنة، وعلى أنه معطَّل ما دامت disabled بالقيمة true. وعنصر التحكم الذي ليس لدوره حالة المطلوب، كشريط التمرير، يقول requiredText في وصفه بدلًا منها.
• عنصر التحكم الذي له حالة خطأ خاصة به، كخانة الاختيار أو زر الاختيار، يُرسم فيها.
• الخطأ الذي يظهر، أو تتغيّر كلماته، والتركيز داخل الحقل يُعلَن مرة واحدة، بتهذيب: نص الخطأ وحده، من دون إعادة المساعدة. ولا ينتقل التركيز أبدًا بسبب خطأ.
• الضغط على التسمية ينقل التركيز إلى عنصر التحكم ولا يشغّله.
• لا يضيف الحقل أي موضع توقف إلى ترتيب التركيز ولا يعالج أي مفتاح.
• وسم المطلوب أو الاختياري والنجمة ورسم أيقونة التسمية مخفيّة عن التقنيات المساعدة: فالحالة والوصف يقولان سلفًا ما تُظهره. وكذلك العدد المرسوم: فعنصر التحكم يصف عدده ويعلنه بنفسه.
• عند تكبير النص إلى 200% تلتفّ التسمية والنص المساعد ولا يُقصّ شيء.
• في الألوان المفروضة (forced colors) يأخذ كل نص لون نص النظام ويكتسب وسم المطلوب أو الاختياري حدًّا. فيتشابه عندئذ نص الخطأ والمساعدة، ولا يفرّق بينهما إلا كلماتهما وترتيبهما، والمساعدة أولًا. ولهذا يجب أن يكون الخطأ بالكلمات.
• في تخطيط من اليمين إلى اليسار تبدأ الصفوف من اليمين، وينتقل رسم الأيقونة إلى يمين التسمية والعلامة إلى يسارها، ويحتفظ كل نص باتجاهه.

على الويب تُكتب خصائص HTML بصيغة kebab-case: label-hidden، supporting-text، error-text، required-mark، required-text، optional-text، count-text. والأجزاء هي label و label-icon و requirement-label و value-text و supporting-text (المساعدة) و error-text و counter.

كيف يربط الويب عنصر التحكم: لا يمكن الإشارة إلى معرّف id عبر جذر ظل (shadow root)، ولذلك يعطي الحقل نصوصه قيمًا. عنصر التحكم من Tanrei يطلبها من حقله ويكتبها على عنصره الداخلي. وأي عنصر آخر يتلقى aria-label (فقط حيث لا اسم له من عنده) و aria-description و aria-invalid و aria-required و disabled، ويستعيد ما كان له بالضبط حين يغادر الحقل.

فجوات معروفة على الويب:

• يُعطى الوصف بالخاصية aria-description، وهي لم تُختبر مع كل قارئ شاشة، والعنصر الذي له سلفًا aria-describedby من عنده لا يصله نص الحقل.
• قبل أن يُعرَّف العنصر، يكون عنصر التحكم في الصفحة بلا تسميته ولا مساعدته.

ما عليك فعله

link

• أعطِ كل حقل label، إلا إذا كان عنصر التحكم يسمّي نفسه.
• تحقق من القيمة بنفسك، وعيِّن error، واكتب errorText بحيث يقول كيف تُصحَّح الإجابة.
• بعد إرسال أخفق، قل كذلك فوق النموذج كم إجابة رُفضت واربط بكل واحدة منها: تنويه حيّ في حالة الخطأ. الحقل لا يستطيع بناءه، لأن النموذج وحده يعرف كل أخطائه.
• أعطِ كلمات المطلوب والاختياري: required-text و optional-text على الحقل، أو مرة واحدة للمنتج كله بالاستدعاء setWords({ requiredText, optionalText }). لا يتضمن Tanrei أي كلمة، والكلمة الناقصة يُبلَّغ عنها أثناء التطوير. انظر كلمات المنتج.
• إن علّمت عناصر التحكم المطلوبة بنجمة، فقل مرة واحدة، قرب أعلى النموذج، ما معنى النجمة.
• لعنصر تحكم بنيته أنت، تأكد من أنه يأخذ الاسم والحالات حيث تكون دلالاته: فإما أن يحمل دوره على عنصره هو، فتنطبق الخصائص التي يكتبها الحقل، وإما أن يستمع إليها (انظر القسم «Field» في ملف README الخاص بحزمة الويب).