حقل التحرير والسرد

نظرة عامة

link

Web

tanrei-combobox-field

schedule

SwiftUI

TanreiComboboxField

radio_button_unchecked

Jetpack Compose

TanreiComboboxField

radio_button_unchecked

Flutter

TanreiComboboxField

radio_button_unchecked

React Native

ComboboxField

radio_button_unchecked

أشكال غير متوفرة في

tanrei: filled, outlined

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

حقل تحرير وسرد يقبل أحد خياراته، وآخر يقبل كذلك قيمة من عند الشخص

كيوتولشبونةنيروبيطوكيوتورنتوInterNoto Sans JPRoboto MonoSource Serif 4

استخدم حقل التحرير والسرد (combobox field) حيثما يطلب النموذج قيمة واحدة يفضّل الناس أن يكتبوها على أن يمرّروا إليها: مدينة من بين مئات، أو شخص، أو رمز تصميم. ويصلح كذلك لحقل يقترح قيمًا ويقبل قيمة من عند الشخص، كعائلة الخط. وهو الحالة المعتادة، جاهزًا للاستخدام: تسمية، وصندوق معه قائمته، وسطر مساعدة، والكلمات التي تقول إن القيمة خاطئة. يُرسم الصندوق ويُقاس كما يُرسم ويُقاس صندوق حقل النص الذي له الطراز نفسه والحجم نفسه، وتُرسم القائمة كما تُرسم قائمة عنصر الاختيار.

يُبنى من حقل و مربع تحرير وسرد. الحقل هو الإطار: التسمية، وعلامة المطلوب أو الاختياري، والمساعدة، والخطأ. ومربع التحرير والسرد هو عنصر التحكم: الصندوق، والنص المكتوب فيه، والقائمة وخياراتها. وحقل التحرير والسرد لا يرسم شيئًا من عنده وليس له أي رمز تصميم (token): فكل خاصية له هي خاصية لأحد الاثنين، تُعطى له كما هي، والخيارات التي تعطيه إياها هي خيارات مربع التحرير والسرد فيه.

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

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

الاستخدام

link

يحمل حقل التحرير والسرد ما يحمله مربع التحرير والسرد فيه، وهو شيئان. الخاصية value هي الاختيار المعتمَد: قيمة الخيار المختار، أو نص من عند الشخص. والخاصية inputValue هي النص الذي في حقل الإدخال. لا تتغيّر القيمة إلا حين يختار الشخص خيارًا، أو يعتمد النص (بالمفتاح Enter ولا خيار نشط، أو بمغادرة الحقل)، أو يضغط زر المسح. أما الكتابة والتنقل في القائمة فلا يغيّرانها أبدًا.

<form>
  <tanrei-combobox-field name="city" label="المدينة" value="tokyo" required required-text="مطلوب"
    clearable clear-label="مسح المدينة" empty-text="لا توجد نتائج مطابقة">
    <tanrei-option value="kyoto">كيوتو</tanrei-option>
    <tanrei-option value="tokyo">طوكيو</tanrei-option>
  </tanrei-combobox-field>
</form>

<!-- الصندوق وحده، حيث تقف التسمية في مكان آخر: مربع تحرير وسرد، وتسمّيه label الخاصة به. واستيراد حقل التحرير والسرد يعرّفه. -->
<tanrei-combobox label="الرمز" placeholder="ابحث عن رمز" no-chevron style="inline-size: 16rem">
  <tanrei-option value="primary">primary</tanrei-option>
</tanrei-combobox>

<!-- الخيارات اقتراحات: النص الذي لا يسمّي أيًّا منها يصير هو القيمة. -->
<tanrei-combobox-field label="عائلة الخط" value="Recursive" allow-custom-value>
  <tanrei-option value="Inter">Inter</tanrei-option>
</tanrei-combobox-field>

<!-- التصفية عليك: عند الحدث input، من خادم. أما صف الحالة فيقول ما يفعله مصدرك. -->
<tanrei-combobox-field id="assignee" label="المكلَّف" filter="none" no-chevron placeholder="ابحث عن شخص">
  <span slot="leading-icon">person_search</span>
</tanrei-combobox-field>

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

  const assignee = document.querySelector('#assignee');
  // غيّر الشخص النص. مربع التحرير والسرد لا يؤخّر هذا الحدث ولا يُسقطه: أخِّره بنفسك (debounce).
  assignee.addEventListener('input', async () => {
    assignee.status = 'loading';
    assignee.statusText = 'جارٍ تحميل الأشخاص';
    const people = await find(assignee.inputValue);
    assignee.replaceChildren(...people.map(option));
    assignee.status = 'idle';
    assignee.statusText = `الأشخاص المعروضون: ${people.length} من أصل ${total}`;
  });
  // تغيّرت القيمة المعتمَدة. والقيمة صارت الجديدة سلفًا.
  assignee.addEventListener('change', (e) => save(e.detail.value));
  // فتحها الشخص أو أغلقها؛ والإغلاق يقول السبب. والحدث لا يتصاعد: استمع إليه على الحقل نفسه.
  assignee.addEventListener('toggle', (e) => console.log(e.detail.open, e.detail.reason));
</script>

import { ComboboxField, Option } from '@tanrei/react';

<ComboboxField label="المدينة" value={city} clearable clearLabel="مسح المدينة" emptyText="لا توجد نتائج مطابقة" onChange={(event) => setCity(event.detail.value)}>
  <Option value="kyoto">كيوتو</Option>
  <Option value="tokyo">طوكيو</Option>
</ComboboxField>

مستوى واحد إلى الأسفل

link

حقل التحرير والسرد هو حقل بداخله مربع تحرير وسرد. اكتب الاثنين بنفسك حيث تحتاج إلى شيء لا يقدّمه الحقل، كشيء من عندك بين التسمية والصندوق، أو تحت المساعدة. والصورة والاسم والوصف والحالات هي نفسها.

<!-- حقل التحرير والسرد -->
<tanrei-combobox-field name="city" label="المدينة" required required-text="مطلوب"
  supporting-text="المدينة التي يُرسل إليها الطلب." value="tokyo">
  <tanrei-option value="kyoto">كيوتو</tanrei-option>
  <tanrei-option value="tokyo">طوكيو</tanrei-option>
</tanrei-combobox-field>

<!-- هو نفسه، باليد: خصائص الإطار على الحقل، وكل ما عداها، ومعه الخيارات، على مربع التحرير والسرد -->
<tanrei-field label="المدينة" required required-text="مطلوب" supporting-text="المدينة التي يُرسل إليها الطلب.">
  <tanrei-combobox name="city" value="tokyo">
    <tanrei-option value="kyoto">كيوتو</tanrei-option>
    <tanrei-option value="tokyo">طوكيو</tanrei-option>
  </tanrei-combobox>
</tanrei-field>

حقل فيه مربع تحرير وسرد: الصورة نفسها التي لحقل التحرير والسرد

كيوتوطوكيو

ما يختلف هو موضع عنصر التحكم الذي يلقاه النموذج: باليد هو مربع التحرير والسرد، وهو الذي يأخذ name؛ وفي حقل التحرير والسرد هو الحقل.

المواصفات

link

مجموعات، ونص مساعد مع خيار معطَّل، وخطأ، وحقل تحرير وسرد للقراءة فقط وآخر معطَّل

طوكيوسوللشبونةبرلينالمجانيةالفرقالمؤسساتنيروبيطوكيونيروبيطوكيونيروبيطوكيو

الحقل

link

الجزء	ما هو
التسمية	صف الحقل فوق الحاوية (في الطراز stacked)، أو تسمية مربع التحرير والسرد نفسه عائمة داخلها (في الطرازين filled و outlined). وهي الاسم المتاح للتقنيات المساعدة، مرسومةً كانت أو مخفيّة بالخاصية labelHidden
علامة المطلوب أو الاختياري	بعد التسمية: وسم المطلوب أو نجمة أو لا شيء مع required، ووسم الاختياري مع القيمة optional. والتسمية العائمة تأخذ النجمة
حقل الإدخال	النص: ما يكتبه الشخص ليعثر على خيار، وما دام لا يكتب فهو تسمية الخيار المختار أو القيمة التي من عنده. سطر واحد، يُمرَّر
النص النائب	تلميح يظهر ما دام حقل الإدخال فارغًا. وليس تسمية أبدًا، وليس قيمة أبدًا
أيقونة البداية	رسم الأيقونة (glyph) الذي في المنفذ leading-icon، وإلا فرسم الخيار المختار نفسه
زر المسح	مع clearable، ما دام النص غير فارغ: يفرغ النص والقيمة
السهم الصغير (chevron)	يقول إن للحقل قائمة يُنظر فيها، ويفتحها ويغلقها. ولا يدور. احذفه (بجعل chevron بالقيمة false) حيث لا توجد اقتراحات إلا لما كُتب
النص المساعد	صف الحقل: سطر من المساعدة. وما دامت error بالقيمة true يأخذ errorText مكانه (أو يُرسم تحته، حيث يُبقي نظام التصميم الاثنين). وكلاهما يبدأ حيث يبدأ نص حقل الإدخال

صف التسمية والعلامة وصف النص المساعد هي للحقل، مرسومة من رموز تصميم الحقل؛ وكل ما عداها لمربع التحرير والسرد. والطُرُز الثلاثة والأحجام الثلاثة small (32) و medium (40) و large (56) هي ما لحقل النص. والنظام الافتراضي يتضمن الطراز stacked وحده.

ما دامت القائمة مفتوحة تُرسم التسمية والمساعدة في حالة التركيز مع الصندوق، سواء أكان التركيز على حقل الإدخال أم لا.

القائمة

link

تُفتح القائمة تحت الحاوية على مسافة comp.combobox.list.offset، بعرضها تمامًا، وفوقها حيث لا متّسع تحتها. وارتفاعها ارتفاع صفوفها إلى حدّ list.max-height (320)، وما زاد على ذلك يُمرَّر.

الجزء	ما هو
الخيار	صف فيه تسمية، وسطر مساعد ورسم أيقونة إن شئت. وللخيار المختار تعبئة هادئة وعلامة صح
المطابقة	مع filter="contains" يُرسم بوزن أثقل الجزء الذي طابق النص من كل تسمية
المجموعة	سلسلة من الخيارات تحت عنوان اختياري. والمجموعة التي لا تُبقي التصفية فيها شيئًا لا تُرسم
صف الحالة	بعد الخيارات: statusText، ومؤشر تحميل ما دامت status بالقيمة loading، والإخفاق ما دامت بالقيمة error، أو emptyText حيث لم يطابق شيء

مع filter="contains" تظهر الخيارات التي تحوي تسميتها النص، أيًّا كانت حالة الأحرف أو عرض المحرف أو العلامات التي على الحرف. ومع filter="none" يعرض مربع التحرير والسرد كل خيار تعطيه إياه، والتصفية عليك عند الحدث input. ومربع التحرير والسرد لا يجلب ولا ينتظر ولا يفرز ولا يفاضل بين الخيارات أبدًا.

الكتابة والتنقل والاختيار

link

الإدخال	ما يحدث
الكتابة	تعدّل النص وتفتح القائمة مصفّاةً. وأول مطابقة هي الخيار النشط، ويُقرأ حين تتوقف الكتابة؛ ومع allowCustomValue لا خيار نشطًا
مفتاح السهم للأسفل أو السهم للأعلى والقائمة مغلقة؛ أو السهم الصغير	تُفتح القائمة بكل الخيارات. والخيار النشط هو الخيار المختار، وإلا فأول خيار مفعَّل
مفتاح السهم للأسفل أو السهم للأعلى والقائمة مفتوحة	الخيار التالي أو السابق، عبر المجموعات، مع الدوران عند الطرفين (مرورًا بالنص مع allowCustomValue)، ما لم تكن wrap بالقيمة false
المفتاحان Page Down و Page Up	عشرة خيارات نزولًا أو صعودًا
المفتاحان Home و End، ومفتاحا السهم لليسار والسهم لليمين	تحرّك مؤشر الكتابة (caret) في النص
المفتاح Enter وخيارٌ نشط؛ أو ضغط على خيار	يُختار الخيار وتُغلق القائمة. ولا يُرسل النموذج
المفتاح Enter ولا خيار نشطًا	يُعتمد النص، ويُصدَر الحدث action، ويُرسل النموذج ما لم يُلغَ action
المفتاح Escape	يغلق القائمة المفتوحة ويُبقي النص. وإن ضُغط مرة أخرى أعاد نص القيمة المعتمَدة. ولا يمسح قيمة أبدًا
المفتاح Tab؛ أو ضغط في الخارج	يُغادَر الحقل: يُحسم النص وتُغلق القائمة. ولا يُختار الخيار النشط
ضغط على التسمية	ينقل التركيز إلى حقل الإدخال ولا يفتح شيئًا. وما دامت القائمة مفتوحة فهو ضغط خارج مربع التحرير والسرد: تُغلق القائمة، ويبقى التركيز في حقل الإدخال

مغادرة الحقل تحسم النص: يقرّر مربع التحرير والسرد أيَّ قيمة يمثّلها النص. النص الفارغ يفرغ القيمة. والنص الذي هو تسمية خيار بتمامها يختار ذلك الخيار. وأي نص آخر يصير هو القيمة مع allowCustomValue، ويُتخلّى عنه من دونها.

لا تُفتح القائمة عند التركيز. عيِّن open بنفسك إن أردت ذلك.

ما دام أسلوب الإدخال يركّب نصًّا (input-method composition)، فكل مفتاح له. والمفتاح Enter الذي يؤكّد تحويلًا لا يختار شيئًا ولا يرسل شيئًا.

يحمل الحدث toggle سبب الإغلاق: select أو commit أو escape أو outside أو press أو tab أو focus-out أو anchor-hidden أو empty.

البنية

البنية

مرسوم فوق نموذج الاختبار stacked-empty كما ترسمه حزمة الويب.

الجزء	الوصف
1 field	The Field: the label row with its glyph and its requirement mark, and the supporting row with the help and the error text. In a look whose combobox floats the label it draws no label row.
2 combobox	The combobox, as the Field's one control: the box and the text typed in it, the leading glyph, the clear button and the chevron, the list with its options, groups and status row, and the label that floats in the box in the looks that float one.

الخصائص

الخاصية	النوع	القيمة الافتراضية	الوصف
variant	stacked | filled | outlined	"stacked"	The text input's three looks, so that a combobox is drawn as the text inputs beside it: stacked is a filled box that shows focus and error with a line inside its edge and draws no label of its own; filled and outlined float the label inside the box. Use one style per form. A design system may leave some out (the Tanrei system ships stacked only) or add values. — Combobox
size	small | medium | large	"medium"	Minimum height of the container: stacked 32 / 40 / 56, as tall as a Button of the same size, so that the box and a Button side by side in one row stand as tall as each other; filled and outlined 40 / 48 / 56, which hold the label that floats inside them. These are the text input's three sizes, small for a bar, a toolbar or a dense row of controls. The hit area always meets the minimum target. A design system may add values. — Combobox
value	string	""	The committed choice: the chosen option's value, or, with allowCustomValue, a text the person typed that names no option. Empty while nothing is chosen. It is one string, for ever: several values are another component. — Combobox Held by the combobox, which changes it by a choice, a commit or the clear button; the combobox field's is the same at every moment (CBF-3).
inputValue	string	""	The text in the input. The combobox writes it as the person types and when a value is chosen or restored; the product may set it, and reads it from input to load options. — Combobox Held by the combobox, which writes it as the person types and when a value is chosen or restored; the combobox field's is the same at every moment (CBF-3).
label	string	""	Names the control, visibly and to assistive technology. Required, unless the control names itself (a checkbox or a switch with its own label): then leave it empty and the field adds only help and an error. — Field Names the combobox. In a filled or outlined look the combobox draws it, floating in its box, and the Field draws no label row (FLD-25, CMB-8).
labelHidden	boolean	false	Does not draw the label, which stays the accessible name. For a control whose visible label is elsewhere (a table column, a toolbar). — Field Hides the label wherever it would be drawn: the Field's row, or the combobox's floating label (FLD-25).
placeholder	string	""	A hint shown while the input is empty and no label is in the input line. Never a replacement for a name. — Combobox
supportingText	string	""	Help shown below the control and given to assistive technology as the control's description. While the field is in error it gives way to errorText, unless the design system keeps both (comp.field.error-text.placement append). — Field
errorText	string	""	Shown while error is true, in supportingText's place — or below it, which then stays, where the design system's comp.field.error-text.placement is append: what is wrong and how to put it right, in words. — Field
error	boolean	false	Puts the field in the error condition: the error text is drawn, the control is exposed as invalid and, where it has an error condition of its own, drawn in it. What a value means is the product's to validate; the field never sets this itself. — Field Puts the Field in its error condition, which puts the combobox in its own (FLD-8, CMB-10).
disabled	boolean	false	Disables the control and draws the frame as disabled. Disable a framed control here, not on the control, so that its label follows. — Field Disables the Field, which disables the combobox (FLD-14, CMB-46).
readOnly	boolean	false	The value is shown, can be focused, selected and copied, and is submitted, but cannot be changed: the list does not open and neither the chevron nor the clear button is drawn. — Combobox
required	boolean	false	What the form asks of the control: true exposes it as required and draws the required mark beside the label. It never validates: a missing answer is the product's to report with error. — Field
optional	boolean	false	Draws the optional tag after the label and adds optionalText to the control's description, because assistive technology has no state for it. Ignored while required is true: a control is never both. — Field
requiredMark	auto | tag | asterisk | none	"auto"	How this control shows that it is required: tag is a small filled Tag with requiredText, asterisk is "*" after the label, none draws nothing and keeps the semantics. Auto takes comp.field.requirement.mark, which follows sys.behavior.requirement-mark, the system's one answer. Ignored unless required is true. — Field
requiredText	string	""	The text of the required tag, in the product's language ("Required", "必須"). The product's: Tanrei has no word for it. Empty reads the product's words; with neither, FLD-24 says what is drawn. — Field
optionalText	string	""	The text of the optional tag, in the product's language ("Optional", "任意"); also read to assistive technology as part of the description. The product's: Tanrei has no word for it. Empty reads the product's words. — Field
open	boolean	false	Whether the list is shown. The combobox opens and closes itself and emits toggle; the product may also set it (to open on focus, for one). Ignored while the combobox is disabled or read-only or has nothing to show. — Combobox Held by the combobox, which opens and closes its list itself; the combobox field's is the same at every moment (CBF-3).
allowCustomValue	boolean	false	False: the value is always one of the options, and a text that names none is given up when the person leaves. True: the options are suggestions, and a text that names none becomes the value as typed (a font family, a tag, an address). — Combobox
filter	contains | none	"contains"	Who decides which options answer the text. contains: the combobox shows the options whose label contains what was typed, ignoring case, and marks the match. none: the combobox shows every option it is given and the product filters — on input, from its own data or a server — and says what it is doing with status. — Combobox
wrap	boolean	true	Whether the arrow keys go round at the ends of the list: Down Arrow on the last option to the first, Up Arrow on the first to the last — with allowCustomValue true, through the text itself, where no option is active (CMB-26). False stops them at the ends. — Combobox
chevron	boolean	true	Draws the chevron that opens the whole list without typing. False for a field whose suggestions exist only for what was typed (a remote search): there is no list to look through. — Combobox
clearable	boolean	false	Draws a clear button while the text is not empty, for a combobox whose value may be none. Without it, emptying the text and leaving the field clears the value. — Combobox
clearLabel	string	""	The clear button's accessible name, in the product's language ("Clear"). Required while clearable is true. — Combobox
status	idle | loading | error	"idle"	What the product's source of options is doing, which the product sets: idle (the options given are final), loading (options are on their way: the status row shows a loading indicator), error (the source failed: the status row shows statusText in the error color). — Combobox
statusText	string	""	The status row's text, in the product's language, announced to assistive technology when it changes: a count ("12 of 340 shown"), that loading failed, or, while status is loading, the loading indicator's name ("Loading options"). — Combobox
emptyText	string	""	Shown in the list while the text names nothing the combobox can show, allowCustomValue is false and no status is set, in the product's language ("No matches"). The product's: Tanrei has no words for it. Empty reads the product's words; with neither, no such row is drawn and it is reported (CMB-32). — Combobox
separation	auto | divider | gap	"auto"	How a group of options is told from what is next to it. divider: a line between them. gap: empty space and no line. Auto takes comp.combobox.separation, which follows the design system's choice. — Combobox
iconSpace	auto | always | never	"auto"	Whether a shown option keeps the room of the leading icon column where it has no icon, so that the labels of a section start on one line — a section being the shown options of a group, or a run of adjacent shown options outside any group. auto: an option keeps the column while another shown option of its section has a leading icon; an option the filter hides does not count. always: every option keeps it. never: only an option that has an icon has the column. The menu's and the select's iconSpace, with the same values and default (CMB-67). — Combobox
density	regular | compact	"regular"	How much room an option of the list takes: its least height, its paddings, the gap between its columns and the size of its glyphs (the leading icon, the check), and never its text style. regular (a 48 row in the default system) is for a product used by touch as well as by pointer; compact (a 32 row with 20 glyphs, the menu's compact row) is for a tool used with a pointer, whose lists are long. For touch an option is never lower than the touch target in either (CMB-34). The field's own box is not changed: its height is size's. A design system may add values. — Combobox

المنافذ

المنفذ	الوصف
leading-icon	A glyph at the start of the container that stands for the combobox whatever is chosen (a magnifier before a field that searches people). It takes the place of the chosen option's own glyph. — Combobox
label-icon	A glyph before the label. — Field

الأحداث

الحدث	الوصف
input	The person changed the text (typing, deleting, pasting, dictating, the clear button, Escape restoring it); carries the new text. Not emitted when the product sets inputValue or value, or when a choice writes its label. It is the product's cue to load options; the combobox does not delay or drop it. — Combobox
change	The committed value changed by the person: an option was chosen, a custom text was committed, or the value was cleared; carries the new value and the text now shown. Not emitted when the product sets value, when the chosen option is chosen again, or while the person only types or moves through the list. — Combobox
toggle	The list was opened or closed by the person or by having nothing left to show; carries the new open and, for a close, the reason: select, commit, escape, back, outside, press, tab, focus-out, anchor-hidden or empty (in the platform's casing). After a choice it follows change. — Combobox
action	The person pressed Enter with no option active and the text was committed; emitted after any change it caused. On the web it is followed by the form's submission unless cancelled. — Combobox

العناصر

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

option

One choice of the combobox: a label, the value it stands for, and optionally a supporting line and a glyph. The same kind a select holds.

الخاصية	النوع	القيمة الافتراضية	الوصف
label	string	""	The option's text and its accessible name: what the filter searches and what the input shows once the option is chosen. Required.
value	string	""	Identifies the choice: the option is the chosen one while the combobox's value equals it. Unique within the combobox and not empty: the empty value means that nothing is chosen.
supportingText	string	""	A line below the label that says more about the choice. Shown in the list, not in the input; not searched.
leadingIcon	string	""	The name of an icon (a glyph of the system's icon set) before the label; the container shows it too while the option is chosen and the combobox has no leading icon of its own.
disabled	boolean	false	Prevents the option from being chosen. It stays reachable with the arrow keys.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
العنصر	tanrei-option	TanreiComboboxOption	TanreiComboboxOption	TanreiComboboxOption	ComboboxOption
label · الخاصية	label	title	text	label	label
value · الخاصية	value	tag	value	value	value
supportingText · الخاصية	supportingText	supportingText	supportingText	supportingText	supportingText
leadingIcon · الخاصية	leadingIcon	leadingIcon	leadingIcon	leadingIcon	leadingIcon
disabled · الخاصية	disabled	disabled	enabled	enabled	disabled
ملاحظات	<tanrei-option value="tokyo">Tokyo</tanrei-option>: the element a select holds, and the same data: the label is the label attribute or, without one, the element's text. Attributes supporting-text, leading-icon, disabled. It draws nothing itself. tanrei-option and tanrei-option-group are one pair of elements for the select and the combobox, defined once; an option with the empty value is refused by the combobox (CMB-17, CMB-57), not by the element, because a select allows it.	TanreiComboboxOption(_ title:, supportingText:, leadingIcon:).tag(value); disabled follows .disabled(_:).	TanreiComboboxOption(text, value, supportingText, leadingIcon, enabled), called in the combobox's content lambda.	TanreiComboboxOption<String>(value:, label:, supportingText:, leadingIcon:, enabled:), in the combobox's options list, as DropdownMenuEntry.	{ label, value, supportingText?, leadingIcon?, disabled? }: an element of the options array.

option-group · مجموعة — تحتوي عناصر

A run of related options, optionally titled. The combobox separates a group from what is next to it by a divider or a gap, and draws neither a group nor its title while the filter leaves it empty.

الخاصية	النوع	القيمة الافتراضية	الوصف
title	string	""	A short heading drawn above the group's options, which also names the group; empty draws none and leaves the group unnamed.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
العنصر	tanrei-option-group	TanreiComboboxSection	TanreiComboboxGroup	TanreiComboboxGroup	ComboboxOptionGroup
title · الخاصية	label	title	title	title	title
ملاحظات	The title is the label attribute, as <optgroup label>: a title attribute would also draw the browser's tooltip.	TanreiComboboxSection(_ title:) { … }, as Section.	TanreiComboboxGroup(title) { … }.	TanreiComboboxGroup(title:, options: […]), in the same list.	{ kind: 'group', title?, options: ComboboxOption[] } in the same array.

الحالات

السلوك

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

المعرّف	المتطلب
CBF-1	THE combobox field SHALL be a Field that frames one combobox, and nothing else. It SHALL give label, labelHidden, supportingText, errorText, error, disabled, required, optional, requiredMark, requiredText and optionalText to its Field and every other prop to its combobox, each unchanged; SHALL hold the label-icon slot for its Field and the leading-icon slot for its combobox; SHALL give its options to its combobox (CBF-2); and SHALL emit its combobox's events as its own, each once. THE combobox field SHALL be as wide as the place it stands in, and its combobox SHALL fill it: it is a block with no width of its own, as its Field is (FLD-1), around a control that fills the width it is given (CMB-49). It SHALL draw no part of its own and have no token of its own: what it shows, how it behaves and what it exposes to assistive technology SHALL be exactly what that Field and that combobox do when a product places the one in the other (FLD-1 to FLD-28; CMB-1 to CMB-62) — the label row and its requirement mark (FLD-2 to FLD-6), or the label that floats in the box with the Field's row left out (FLD-25, CMB-7, CMB-8); the supporting row and the error (FLD-7 to FLD-9, FLD-26, CMB-10); the name, the description and the states (FLD-10, FLD-11, FLD-14, CMB-12, CMB-46); and the list, which is the combobox's alone and as wide as its container (CMB-22).
CBF-2	THE combobox field SHALL take the options and the option groups a product gives it — in the platform's form for a combobox's own (its child elements on the web) — and give them to its combobox as that combobox's options, in the order given, each with its label, its value, its supporting text, its leading icon and its disabled, and each group with its title: the option a product wrote SHALL be the option its combobox reads, never a copy of it. THE combobox field SHALL NOT read, filter, order, count or keep an option, and SHALL make no option active or chosen: which options are shown, which is active and which is the chosen one are its combobox's (CMB-25, CMB-26, CMB-36). WHEN the product adds, removes, reorders or changes an option or a group THE combobox field's combobox SHALL meet the change at once and as CMB-31 says, as though the product had changed that combobox's own options.
CBF-3	THE combobox field SHALL hold no value, no text and no open state of its own: its value, its inputValue and its open SHALL at every moment be its combobox's. WHEN its combobox changes one of them — a choice, a commit or the clear button (CMB-17, CMB-20, CMB-27 to CMB-29); typing, or a text the combobox writes itself for a choice, for a commit that was given up or for Escape (CMB-16, CMB-27, CMB-29, CMB-30); the list opening or closing, or open taken back because there is nothing to show (CMB-21, CMB-30, CMB-57) — THE combobox field's SHALL be the new one before any event that reports the change is emitted, and equally WHERE no event reports it. WHEN the product sets one on the combobox field THE combobox field SHALL set it on its combobox and nothing else, so that no event follows (CMB-31).
CBF-4	WHERE the platform has forms (the web) THE combobox field SHALL be the one control the form sees: it SHALL take name, submit its combobox's value — never the text of an edit that was not committed — reset to the value it was first given, restore it on navigation, report to the form's constraint validation exactly what its combobox would report there (CMB-59), and be left out WHILE disabled is true or a disabled group of the form holds it; its combobox and its Field SHALL take no part in the form themselves. WHEN Enter asks for the form's submission (CMB-28) the form asked SHALL be the combobox field's own, through that form's default button (BTN-30), and not WHEN action was cancelled.
CBF-5	WHEN the combobox field is given focus — by the product, by a press on any part of it that FLD-12 or CMB-14 gives to the input, or by a form that reports its validity — THE combobox field SHALL pass the focus to its combobox's input and SHALL add no stop to the focus order: the stops inside it are its combobox's, in that combobox's order (the input, then the clear button while it is shown). WHILE focus is anywhere inside it, or its combobox's list is open, its Field's rows SHALL be drawn focused, because its combobox says so to its Field (FLD-13, CMB-61): the combobox field arranges nothing for it. A press on its Field's label row WHILE the list is open is a press outside the combobox: the list SHALL close with the reason outside, choosing nothing (CMB-30), and focus SHALL go to the input (FLD-12).
CBF-6	IF the combobox field is placed in a Field THE combobox field SHALL in debug builds report that it is a field already and that the bare control is the combobox, and both SHALL still render (FLD-15). WHILE it stands in a field group THE combobox field SHALL follow that group's disabled, through its own Field, and take nothing else from the group (FGR-20).
CBF-7	THE combobox field SHALL have no words of its own and SHALL read none: requiredText and optionalText are read by its Field (FLD-24), emptyText and clearLabel by its combobox (CMB-60), each from the instance's prop and then from the product's words.
CBF-8	WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE combobox field SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on the element that carries its role — an id reference by the elements it names in the host's tree or a tree around it, an error message as part of the description while the combobox field is invalid — except those the combobox field owns (aria-label, aria-labelledby, aria-disabled, aria-haspopup, aria-expanded, aria-controls), which it SHALL move and not expose: its name is label (CBF-1). WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE combobox field SHALL take it off that element. WHEN the product sets an aria- attribute the combobox field owns THE combobox field SHALL report it in debug builds.

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

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

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
المكوّن	tanrei-combobox-field	TanreiComboboxField	TanreiComboboxField	TanreiComboboxField	ComboboxField
variant · الخاصية	variant	variant	variant	variant	variant
size · الخاصية	size	size	size	size	size
value · الخاصية	value	selection	value	value	value
inputValue · الخاصية	inputValue	text	inputValue	controller	inputValue
label · الخاصية	label	label	label	labelText	label
labelHidden · الخاصية	labelHidden	labelsHidden	labelHidden	labelHidden	labelHidden
placeholder · الخاصية	placeholder	prompt	placeholder	hintText	placeholder
supportingText · الخاصية	supportingText	supportingText	supportingText	helperText	supportingText
errorText · الخاصية	errorText	errorText	errorText	errorText	errorText
error · الخاصية	error	error	isError	isError	error
disabled · الخاصية	disabled	disabled	enabled	enabled	disabled
readOnly · الخاصية	readOnly	readOnly	readOnly	readOnly	readOnly
required · الخاصية	required	isRequired	required	required	required
optional · الخاصية	optional	isOptional	optional	optional	optional
requiredMark · الخاصية	requiredMark	requiredMark	requiredMark	requiredMark	requiredMark
requiredText · الخاصية	requiredText	requiredText	requiredText	requiredText	requiredText
optionalText · الخاصية	optionalText	optionalText	optionalText	optionalText	optionalText
open · الخاصية	open	isPresented	expanded	menuController	open
allowCustomValue · الخاصية	allowCustomValue	allowCustomValue	allowCustomValue	allowCustomValue	allowCustomValue
filter · الخاصية	filter	filter	filter	filter	filter
wrap · الخاصية	wrap	wrap	wrap	wrap	wrap
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
iconSpace · الخاصية	iconSpace	iconSpace	iconSpace	iconSpace	iconSpace
density · الخاصية	density	density	density	density	density
input · الحدث	input	text	onInputValueChange	onInputChanged	onInputValueChange
change · الحدث	change	selection	onValueChange	onChanged	onValueChange
toggle · الحدث	toggle	isPresented	onExpandedChange	onOpenChanged	onOpenChange
action · الحدث	action	onSubmit	keyboardActions	onSubmitted	onSubmitEditing
ملاحظات	The tag tanrei-combobox-field, the class TanreiComboboxField, the React name ComboboxField. It takes the combobox's attributes, children and listeners and the Field's, name for name. The element is composed as every composed element on the web is (the web package's README, Composed elements); what follows is what is particular to it, and the three places where this element needs more than every composed element has. Members: <tanrei-field> holding one <tanrei-combobox> in its default slot; the product places no member. The host is display: block. Value member: tanrei-combobox. The host is the form's element — name, the value and its state, validity anchored on the combobox's input, reset to the value attribute, restore, form, a disabled fieldset — and the combobox inside has no name. Props, set as properties on the member each is from. On the Field: label, labelHidden, supportingText, errorText, error, disabled, required, optional, requiredMark, requiredText, optionalText. On the combobox: variant, size, value, inputValue, placeholder, readOnly, open, allowCustomValue, filter, noChevron (the inverse of chevron, attribute no-chevron), clearable, clearLabel, status, statusText, emptyText, separation. Attributes are the members' own: kebab-case, except readonly. Props of one name on both members — label, labelHidden, error, disabled — are the Field's; the combobox's are never set by the element and reach the combobox through the connection. **1. Three props the member writes** (a composed element sets each prop on its member, with one exception, the value, which it reads back on the member's event): the combobox writes value, inputValue and open itself, and writes the text with no event when a commit is given up (CMB-29). The host therefore keeps no copy of the three: each is an accessor over the member's property — a get reads the member's, a set writes the member's, and a value set before the member exists is kept and given at its first render — so that event.target.value, .inputValue and .open are the new ones in every listener and between events (CBF-3). open reflects on the host as it does on the member: the host writes its own attribute when the member tells it of an update, by the primitive through which the member already tells the host its form value. **2. The options are passed by the default slot** (other passed-on children use named slots): the shadow root is <tanrei-field><slot name="label-icon" slot="label-icon"></slot><tanrei-combobox><slot></slot><slot name="leading-icon" slot="leading-icon"></slot></tanrei-combobox></tanrei-field>. The product's <tanrei-option> and <tanrei-option-group> children stay the host's light-DOM children and are assigned to the unnamed <slot>, which is a child of the combobox; the combobox reads a <slot> among its children as the elements assigned to it and reads again on slotchange and on a change of an assigned element (primitives/option-list.ts, the combobox's web note; the select reads its options the same way, with the same reader). Unlike a passing named slot, the unnamed one is always rendered: the combobox draws no room for options, so an empty slot is no option. The host never reads its option children. Slots: label-icon is passed to the Field and leading-icon to the combobox, each by a slot element of the same name rendered only while the host has a child for it. **3. A forwarded attribute that is no prop**: inline, the combobox's web-only attribute that draws an open list in place for the fixtures, is forwarded as a property, and select() is passed on as focus() and blur() are. Events: input is the native, composed event of the text element, and change and action are the combobox's own composed, bubbling events; the three leave by themselves, with the host as their target, and action stays cancelable. toggle is composed and does not bubble: it is heard on the host, as on any shadow host, and by no ancestor — which needs the combobox's toggle to be composed, as it is not today (the combobox's web note). None is stopped and none is copied. Parts: the member hosts are field and combobox. Exported from the Field: label, label-icon, requirement-label, supporting-text. Exported from the combobox: container, outline, active-indicator, label, requirement-label, input, leading-icon, clear-button, chevron, list, option, option-label, option-supporting-text, option-leading-icon, mark, group, group-title, divider, status. Two names collide, label and requirement-label. Each is exported with its member's name before it, always (field-label, combobox-label, field-requirement-label, combobox-requirement-label), and under the bare name from both members as well, because the two are one thing to a person and are never drawn at once: FLD-25 is the sentence that holds it. Focus: the shadow root does not delegate. focus(), blur() and select() call the combobox's; a press on the label row focuses the input by FLD-12, a press on the box by CMB-14, and a press on the help does nothing. The combobox's list is a popover of the combobox's own shadow root, in the top layer; the combobox is its opener, so a press on the Field's rows while it is open is a press outside (CBF-5). The connection is the Field's with its control, with one value more upward, that the control is drawn focused (FLD-13, FLD-25, FLD-26, CMB-61); the element takes no part in it. Parts and tokens of its own: none. The element writes no custom property: --tanrei-comp-field-*, --tanrei-comp-input-box-* and --tanrei-comp-combobox-* reach the members by inheritance, and one combobox field is set apart by setting any of them on the element. What its twin cannot do that it does: nothing. The twin: <tanrei-field label="City" supporting-text="Where the order is sent." required><tanrei-combobox name="city" value="tokyo"><tanrei-option value="kyoto">Kyoto</tanrei-option><tanrei-option value="tokyo">Tokyo</tanrei-option></tanrei-combobox></tanrei-field>. Before the element is defined its options are running text: a page hides them with tanrei-combobox-field:not(:defined) > * { display: none } and gives the tag a block size. Words: none of its own; required-text and optional-text are read by the Field, empty-text and clear-label by the combobox.	TanreiComboboxField("City", selection: $city, text: $query) { TanreiComboboxOption("Tokyo").tag("tokyo") … }: a view built from TanreiField and TanreiCombobox, with the combobox's two bindings and its content builder passed through and the Field's arguments beside them. It takes TanreiCombobox's arguments, name for name. One instance is set apart by .tanreiTheme(_:) on the view. The options are TanreiComboboxOption and TanreiComboboxSection, the combobox's own. Planned, after the Field and the combobox.	TanreiComboboxField(value, onValueChange, label = "City") { TanreiComboboxOption("Tokyo", "tokyo") … }: a composable that calls TanreiField with TanreiCombobox as its content and passes the content lambda through. enabled is the inverse flag and isError keeps Compose's name. One instance is set apart by TanreiTheme(…) { } around it. Planned, after the Field and the combobox.	TanreiComboboxField(value:, onChanged:, labelText:, helperText:, errorText:, options: […]): a widget that builds TanreiField around TanreiCombobox and passes options through; labelText, hintText, helperText, errorText and enabled keep InputDecoration's names, enabled the inverse flag. TanreiComboboxFormField wraps the combobox field as a FormField<String>. One instance is set apart by a TanreiTheme around it. Planned, after the Field and the combobox.	<ComboboxField label="City" supportingText="Where the order is sent." value={city} onValueChange={setCity} options={[…]} />: a component that renders Field around Combobox and passes options through as given. inputValue / onInputValueChange and open / onOpenChange are the combobox's optional pairs. One instance is set apart by a provider around it. Planned, after the Field and the combobox.

الرموز

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

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

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

variant: stacked (46)

stacked-empty

variant: stacked label: City items: 5

stacked-value

variant: stacked value: tokyo label: City items: 5

stacked-open

variant: stacked value: tokyo label: City open: true items: 5 مرسوم وحده في نافذة بحجم 312 × 472

stacked-large

variant: stacked size: large value: tokyo label: City items: 5

stacked-error

variant: stacked label: City errorText: Choose the city you are sending to. error: true items: 5

stacked-disabled

variant: stacked value: tokyo label: City disabled: true items: 5

stacked-placeholder

label: City placeholder: Type to find a city items: 5

stacked-label-hidden

value: tokyo label: City labelHidden: true items: 5

stacked-supporting

value: tokyo label: City supportingText: Where the order is sent. items: 5

stacked-error-value

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

stacked-read-only

value: tokyo label: City readOnly: true items: 5

stacked-clearable

value: tokyo label: City clearable: true clearLabel: Clear city items: 5

stacked-no-chevron

label: Address placeholder: Start typing an address filter: none chevron: false items: 1

stacked-custom-value

value: Recursive label: Font family allowCustomValue: true items: 4

stacked-required

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

stacked-optional

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

stacked-required-asterisk

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

stacked-required-error

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

stacked-required-disabled

value: tokyo label: City disabled: true required: true requiredText: Required items: 5

stacked-label-icon

value: tokyo label: City items: 5 slots: label-icon

stacked-leading-icon

label: Assignee placeholder: Find a person items: 2 slots: leading-icon

stacked-option-icon

value: train label: Transport items: 3

open-none-chosen

label: City open: true items: 5 مرسوم وحده في نافذة بحجم 312 × 473

open-filtered

value: tokyo inputValue: to label: City open: true items: 5 مرسوم وحده في نافذة بحجم 312 × 473

open-filtered-none

inputValue: zz label: City open: true emptyText: No matches items: 5 مرسوم وحده في نافذة بحجم 312 × 473

open-icons

value: train label: Transport open: true items: 3 مرسوم وحده في نافذة بحجم 312 × 473

open-supporting-text

value: sys.color.on-primary inputValue: primary label: Token open: true items: 4 مرسوم وحده في نافذة بحجم 312 × 473

open-disabled-chosen

value: sys.color.secondary label: Token open: true items: 4 مرسوم وحده في نافذة بحجم 312 × 473

open-groups

value: Europe/Lisbon label: Time zone open: true items: 3 مرسوم وحده في نافذة بحجم 312 × 473

open-groups-divider

value: Europe/Lisbon label: Time zone open: true separation: divider items: 3 مرسوم وحده في نافذة بحجم 312 × 473

open-groups-gap

value: Europe/Lisbon label: Time zone open: true separation: gap items: 3 مرسوم وحده في نافذة بحجم 312 × 473

open-groups-filtered

inputValue: in label: Time zone open: true items: 3 مرسوم وحده في نافذة بحجم 312 × 473

open-many

value: lisbon label: City open: true items: 24 مرسوم وحده في نافذة بحجم 312 × 473

open-long-options

label: Licence open: true items: 2 مرسوم وحده في نافذة بحجم 312 × 473

open-custom-suggestions

inputValue: no label: Font family open: true allowCustomValue: true items: 4 مرسوم وحده في نافذة بحجم 312 × 473

open-loading

inputValue: ai label: Assignee open: true filter: none chevron: false status: loading statusText: Loading people items: 1 مرسوم وحده في نافذة بحجم 312 × 473

open-status

inputValue: a label: Assignee open: true filter: none chevron: false statusText: 2 of 48 people shown. Keep typing to nar… items: 2 مرسوم وحده في نافذة بحجم 312 × 473

open-status-error

inputValue: ai label: Assignee open: true filter: none chevron: false status: error statusText: People could not be loaded. Check your c… items: 1 مرسوم وحده في نافذة بحجم 312 × 473

long-value

value: cc-by-nc-sa label: Licence items: 2

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: 5

stacked-required-ja

value: kyoto label: 都市 required: true requiredText: 必須 items: 3

open-filtered-ja

inputValue: 京 label: 都市 optional: true optionalText: 任意 open: true emptyText: 一致する項目がありません items: 3 مرسوم وحده في نافذة بحجم 312 × 473

stacked-required-rtl

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

open-rtl

value: Asia/Riyadh inputValue: ال label: المنطقة الزمنية open: true direction: rtl items: 2 مرسوم وحده في نافذة بحجم 312 × 473

long-value-rtl

value: cc-by-nc-sa label: רישיון direction: rtl items: 2

stacked-error-rtl

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

variant: filled (6)

filled-empty

variant: filled label: City items: 5

filled-value

variant: filled value: tokyo label: City items: 5

filled-open

variant: filled value: tokyo label: City open: true items: 5 مرسوم وحده في نافذة بحجم 312 × 473

filled-large

variant: filled size: large value: tokyo label: City items: 5

filled-error

variant: filled label: City errorText: Choose the city you are sending to. error: true items: 5

filled-disabled

variant: filled value: tokyo label: City disabled: true items: 5

variant: outlined (8)

outlined-empty

variant: outlined label: City items: 5

outlined-value

variant: outlined value: tokyo label: City items: 5

outlined-open

variant: outlined value: tokyo label: City open: true items: 5 مرسوم وحده في نافذة بحجم 312 × 473

outlined-large

variant: outlined size: large value: tokyo label: City items: 5

outlined-error

variant: outlined label: City errorText: Choose the city you are sending to. error: true items: 5

outlined-disabled

variant: outlined value: tokyo label: City disabled: true items: 5

outlined-required

variant: outlined label: City required: true requiredText: Required items: 5

outlined-rtl

variant: outlined value: cairo label: المدينة direction: rtl items: 2

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

ما يرسمه الويب بطريقة مختلفة

link

• العنصران <tanrei-option> و <tanrei-option-group> بيانات: لا يرسمان شيئًا. وهما العنصران اللذان يحملهما عنصر الاختيار. والخيار الذي قيمته السلسلة الفارغة يُرسم ولا يمكن اختياره، لأن القيمة الفارغة تعني أن لا شيء مختار.
• جذر الظل (shadow root) في العنصر فيه عنصر <tanrei-field> حول عنصر <tanrei-combobox>. وفروعك من عناصر <tanrei-option> تبقى فروعه هو وتبلغ مربع التحرير والسرد عبر منفذ؛ فلا يُنقل شيء ولا يُنسخ.
• حقل التحرير والسرد عنصر مرتبط بالنماذج (form-associated): هو عنصر التحكم الوحيد الذي يراه النموذج. يأخذ name، ويرسل value ولا يرسل أبدًا نص تعديل لم يُعتمد، ويعود عند إعادة الضبط إلى قيمة خاصية HTML value، ويبلّغ النموذج بأن القيمة ناقصة ما دامت required و value فارغة. والمفتاح Enter ولا خيار نشط يرسل نموذجه.
• الخصائص value و inputValue و open هي خصائص مربع التحرير والسرد في كل لحظة: فكل منها صارت الجديدة سلفًا في كل مستمع.
• الخاصيتان chevron و wrap هما خاصيتا HTML المعكوستان no-chevron و no-wrap، والخاصية readOnly هي readonly.
• الحدث input هو الحدث الأصلي لعنصر النص. والحدثان change و action يحملان detail.value و detail.inputValue. والأحداث الأربعة هي أحداث مربع التحرير والسرد نفسه، وهدفها حقل التحرير والسرد؛ والحدث toggle لا يتصاعد.
• الدالة focus() تذهب إلى حقل الإدخال. والعنصر نفسه غير قابل للتركيز وليس له دور: سمِّه بالخاصية label، ولا تسمِّه أبدًا بالخاصية aria-label.
• الأجزاء: field و combobox هما العضوان؛ وأجزاء كل عضو مصدَّرة بأسمائها، والجزءان label و requirement-label مصدَّران كذلك بالأسماء field-label و combobox-label و field-requirement-label و combobox-requirement-label.
• يُخصَّص حقل واحد دون غيره بخاصية مخصصة (custom property) عليه: --tanrei-comp-field-* للصفوف، و --tanrei-comp-input-box-* للصندوق، و --tanrei-comp-combobox-* للقائمة.
• القائمة عنصر له popover="manual" في الطبقة العليا (top layer). والضغط في الخارج يغلقها ويصل أيضًا إلى العنصر الذي تحته.
• صف الحالة يقف تحت الخيارات ولا يُمرَّر معها، فيبقى العدد أو الإخفاق في مجال الرؤية.
• قبل أن يُعرَّف العنصر، تكون خياراته نصًّا جاريًا في الصفحة. أخفِ tanrei-combobox-field:not(:defined) > * واحجز الارتفاع.
• ليس للويب إيماءة رجوع خاصة به، فلا يحمل الحدث toggle السبب back أبدًا.

الإرشادات

link

حقل تحرير وسرد أم عنصر اختيار أم بحث أم حقل نص

link

الجانب	حقل التحرير والسرد	عنصر الاختيار	البحث	حقل النص
ما يحمله	قيمة واحدة يُعثر عليها بالكتابة	قيمة واحدة من قائمة مغلقة	استعلام	أي نص
متى يعرض الخيارات	في أثناء كتابة الشخص	بعد ضغط	اقتراحات ونتائج	لا يعرضها
هل يقبل قيمة ليست في القائمة	مع allowCustomValue	لا	نعم	نعم
هل هو جزء من نموذج	نعم	نعم	لا	نعم

1. حين لا تزيد الخيارات على خمسة تقريبًا وهي قصيرة، اعرضها كلها: أزرار اختيار.
2. إن كانت القائمة قصيرة بحيث تُمسح بالنظر، ومغلقة، فذاك عنصر اختيار.
3. إن كان الناس يفضّلون الكتابة على التمرير، أو كان الحقل يقبل قيمة ليست في القائمة، فذاك حقل تحرير وسرد.
4. إن كانت الكتابة تقود إلى أماكن يُذهب إليها لا إلى قيمة، فذاك بحث.
5. القيم المتعددة مكوّن آخر: مربع التحرير والسرد يحمل قيمة واحدة.
6. إن كانت التسمية تقف في مكان آخر، كعامل تصفية في شريط أدوات أو خلية في جدول، فذاك مربع التحرير والسرد مجرَّدًا، وتسمّيه label الخاصة به.

افعل

link

• اكتب تسمية تسمّي ما يُختار، وأبقِها مرئية في النموذج.
• استخدم allowCustomValue فقط حيث تكون القيمة التي ليست في القائمة جوابًا حقيقيًّا.
• أعطِ clearable لحقل تحرير وسرد يجوز أن تكون قيمته لا شيء، وسمِّ الزر بالخاصية clearLabel.
• حين تحمّل الخيارات، عيِّن status و statusText لتقول القائمة إنها تنتظر، أو كم خيارًا تعرض، أو إنها أخفقت.
• أعطِ emptyText، على حقل التحرير والسرد أو مرة واحدة للمنتج كله بالاستدعاء setWords({ emptyText }). لا يتضمن Tanrei أي كلمة: من دونها لا يرسم النص الذي لا يطابق شيئًا أي صف، ولا يكون في القائمة ما تعرضه.

لا تفعل

link

• لا تستخدم النص النائب تسميةً. فهو يختفي ما إن يكتب الشخص.
• لا تحفظ ولا تنقل إلى صفحة أخرى ولا ترسل عند الحدث input. فهو يصدر عند كل ضغطة مفتاح؛ والحدث change هو القيمة المعتمَدة.
• لا تعامل النص الذي لا يسمّي خيارًا على أنه خطأ في الحقل. فهو يُتخلّى عنه حين يغادر الشخص. وإن أردت أن تقول «اختر واحدًا من القائمة»، فعيِّن error و errorText بنفسك.
• لا تضع حقل تحرير وسرد داخل حقل. فهو حقل أصلًا؛ وعنصر التحكم الذي يؤطّره الحقل هو مربع التحرير والسرد.
• لا تفتح القائمة عند التركيز في نموذج كثير الحقول: فهي تغطي الحقول التي تحتها عند كل موضع توقف.

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

link

الدور

combobox

التسمية

The combobox field adds nothing to what its members expose and coordinates nothing: the Field gives the combobox its name, its description and its required, invalid and disabled states (FLD-8, FLD-10, FLD-11, FLD-14), and the combobox carries them on its own input, with its expanded state, its list and its active option (CMB-12, CMB-48). Assistive technology meets one editable combobox named by label, with a list of the same name, exactly as it meets a Field around a combobox written by hand.

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

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

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

المفاتيح	الإجراء
Every key	The combobox's (its accessibility block; CMB-16, CMB-20, CMB-21, CMB-26 to CMB-30). The combobox field handles no key and adds no focus stop (CBF-5).

ملاحظات

• One level down is the same thing: a Field with a combobox in it, holding the same options. Every fixture has that pair as its twin, and the accessibility tree of the two is the same (CBF-1).
• The options are the product's, and they are the combobox's: the combobox field passes them on and does nothing with them (CBF-2). Value, text and open are the combobox's too, and the combobox field keeps no second copy that could disagree with it (CBF-3).
• On the web the two members stand in the combobox field's own shadow root, so the form meets the combobox field and not the combobox (CBF-4); focus passes through to the input (CBF-5); and the product's option elements stay its own children, read by the combobox through a slot.
• A list is not a second thing the component reports: choosing an option is setting its one value, so the combobox field is composed, not a feature.

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

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

link

• حقل الإدخال مربع تحرير وسرد قابل للتحرير له مربع قائمة (listbox). اسمه قيمة label، مرسومةً كانت أو مخفيّة، وليس النص النائب أبدًا. يعطيه الحقل لمربع التحرير والسرد، وهذا يحمله على حقل الإدخال الخاص به.
• النص المساعد أو نص الخطأ المعروض هو وصفه، ويُضاف إليه optionalText ما دام الحقل اختياريًّا.
• الخطأ الذي يظهر والتركيز داخل الحقل يُعلَن مرة واحدة، بتهذيب.
• يُعرَض للتقنيات المساعدة على أنه غير صالح ما دامت error بالقيمة true، وعلى أنه مطلوب ما دامت required معيَّنة، وعلى أنه للقراءة فقط، وعلى أنه موسَّع ما دامت قائمته مفتوحة.
• يبقى التركيز في حقل الإدخال ما دامت القائمة مفتوحة. والخيار النشط هو فرعه النشط (active descendant)، فلا تقطع الكتابة تحرير النص أبدًا. والخيار الذي جعلته الكتابة نشطًا يُسمّى حين تتوقف الكتابة نصف ثانية، فيقرأ قارئ الشاشة الحرف المكتوب أولًا ثم الخيار الذي سيختاره Enter؛ أما الخيار الذي تنتقل إليه مفاتيح الأسهم فيُسمّى في الحال.
• القائمة مربع قائمة تسمّيه التسمية. ولكل خيار اسمه ووصفه، وهل هو المختار، وهل هو معطَّل، وموضعه بين الخيارات المعروضة. والمجموعة يسمّيها عنوانها.
• المطابقة تُعلَّم بالوزن، لا باللون وحده أبدًا. والتسمية تُقرأ نصًّا واحدًا.
• صف الحالة منطقة حيّة (live region): يُقرأ نصه بتهذيب حين يتغيّر، وفورًا حين يخفق المصدر. وفي أثناء التحميل تُعلَّم القائمة مشغولة ولا يُعلَن شيء.
• ما دام أسلوب الإدخال يركّب نصًّا، لا يعالج مربع التحرير والسرد أي مفتاح.
• السهم الصغير زر لمؤشر الإدخال (pointer) وللاستكشاف باللمس، خارج ترتيب التركيز. ولوحة المفاتيح تفتح القائمة بمفتاح السهم للأسفل.
• زر المسح زر تسمّيه clearLabel، وهو موضع توقف التركيز التالي بعد حقل الإدخال.
• المفتاح Escape يغلق القائمة ولا يذهب أبعد من ذلك، فيبقى مربع الحوار المحيط بمربع التحرير والسرد مفتوحًا.
• مساحة لمس الحقل تستوفي الحد الأدنى للهدف، وارتفاع الخيارات لا يقل عن الحد الأدنى للهدف.
• عند تكبير النص إلى 200% تلتفّ التسمية والمساعدة والخيارات والعناوين، وكذلك صف الحالة. والنص الذي في حقل الإدخال وحده يبقى في سطر واحد، ويُمرَّر.
• في الألوان المفروضة (forced colors) يكتسب الحقل والقائمة حدًّا، ويأخذ الخيار النشط ألوان التمييز، ويُعرف الخيار المختار بعلامة الصح.
• في تخطيط من اليمين إلى اليسار ينعكس الحقل وكل صف، ويحتفظ كل نص باتجاهه. والسهم الصغير ورسم زر المسح وعلامة الصح لا تنعكس.

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

• الفاصل بين مجموعتين لا يُعرض فاصلًا (separator): فمربع القائمة لا يحمل إلا خيارات ومجموعات.
• التصفية تسوّي حالة الأحرف والعرض والعلامات في كل الكتابات على السواء. ولا تطابق كتابة Hangul بالحرف الساكن الأول ولا حروف kana بقراءتها.
• قبل أن يُعرَّف العنصر، تكون الخيارات نصًّا في الصفحة بلا عنصر تحكم.

ما عليك فعله

link

• أعطِ كل حقل تحرير وسرد label، وكل خيار تسمية وقيمة غير فارغة.
• أعطِ حقل التحرير والسرد القابل للمسح clearLabel.
• اكتب statusText على حقل التحرير والسرد. وأعطِ emptyText و requiredText و optionalText و clearLabel على حقل التحرير والسرد، أو مرة واحدة للمنتج كله بالدالة setWords(). لا يتضمن Tanrei أي كلمة، والكلمة الناقصة يُبلَّغ عنها أثناء التطوير. انظر كلمات المنتج.
• تحقق من القيمة بنفسك، وعيِّن error، واكتب errorText بحيث يقول كيف تُصحَّح الإجابة.
• أبقِ قيم الخيارات فريدة داخل حقل التحرير والسرد الواحد.