التلميح — مكوّن واجهة مستخدم يراعي إمكانية الوصول

الفئة: التواصل
الرموز: comp.tooltip
المستوى: أساسي

نظرة عامة

Web: tanrei-tooltip; schedule
SwiftUI: tanreiTooltip; schedule
Jetpack Compose: TanreiTooltip; schedule
Flutter: TanreiTooltip; schedule
React Native: Tooltip; schedule

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

أشِر إلى زر أو ركّز عليه: تلميح من الطراز وآخر من الطراز rich

delete

info

الاستخدام

عنصر الارتكاز عنصر من عندك: زر أيقونة، أو تسمية مقتطعة، أو علامة في مخطط بياني. يضيف التلميح إليه وصفًا ولا يغيّر فيه شيئًا آخر. يحيط التلميح بعنصر الارتكاز على الويب و Compose و Flutter و React Native، وهو مُعدِّل على عنصر الارتكاز في SwiftUI.

يفتح التلميح نفسه ويغلقها، عند التحويم وتركيز لوحة المفاتيح والضغط المطوَّل، ويبلّغ عن ذلك بالحدث toggle. ولا تضبط open إلا لتعرضه بنفسك، كتلميح أول تشغيل. ضبطها لا يُصدر شيئًا، ويبقى التلميح يفتح نفسه ويغلقها بعد ذلك.

الخاصية describes (وقيمتها الافتراضية true) تجعل النص وصفًا لعنصر الارتكاز متاحًا للتقنيات المساعدة. اضبطها على false حين يكرّر النص اسم عنصر الارتكاز نفسه، كما في زر الأيقونة الذي يعرض تلميحه تسميته، حتى لا تقرأ قارئات الشاشة الكلمات مرتين.

تعرض عيّنتا Web و React المواصفة الحالية. أما SwiftUI و Compose و Flutter و React Native فمتأخرة: ما زالت تقدّم المراجعة السابقة من التلميح، وفيها أربعة مواضع موسَّطة وليس فيها مهل ولا إزاحات خاصة بتلميح واحد، ولا سهم، ولا مظهر ثانٍ، ولا اختصار، وتظهر تدريجيًّا من دون أن تكبر. وتعرض عيّناتها تلك المراجعة إلى أن تلحق بالبقية.

<!-- التلميح يحيط بعنصر ارتكازه. no-describe هي describes مضبوطة على false: النص يكرّر التسمية. -->
<tanrei-tooltip text="نقل إلى المهملات" no-describe>
  <tanrei-button variant="text" label="نقل إلى المهملات"><span slot="icon">delete</span></tanrei-button>
</tanrei-tooltip>

<!-- شريط أدوات كثيف يريد أسماءه أبكر. المهل بالميلي ثانية. -->
<tanrei-tooltip text="غامق" show-delay="150" no-describe>
  <tanrei-button variant="text" label="غامق"><span slot="icon">format_bold</span></tanrei-button>
</tanrei-tooltip>

<!-- مفاتيح الأمر بعد اسمه. عنصر الارتكاز يحملها للتقنيات المساعدة. -->
<tanrei-tooltip text="غامق" shortcut="mod+b" no-describe>
  <tanrei-button variant="text" label="غامق"><span slot="icon">format_bold</span></tanrei-button>
</tanrei-tooltip>

<!-- تحت عنصر التحكم، محاذيًا لحافة بدايته، مع سهم، على سطح بدل المظهر المعكوس. -->
<tanrei-tooltip text="التصفية حسب التاريخ أو المالك" placement="bottom-start" arrow inverse="false">
  <tanrei-button variant="text" label="تصفية"><span slot="icon">filter_list</span></tanrei-button>
</tanrei-tooltip>

<tanrei-tooltip id="storage" variant="rich" headline="التخزين" placement="bottom"
                text="الملفات في المهملات تبقى محسوبة من مساحة تخزينك إلى أن تُحذف.">
  <tanrei-button variant="text" label="عن التخزين"><span slot="icon">info</span></tanrei-button>
</tanrei-tooltip>

<script type="module">
  import '@tanrei/web/components/tooltip';
  const storage = document.querySelector('#storage');
  // تلميح أول تشغيل. ضبط open لا يُصدر شيئًا.
  storage.open = true;
  // toggle يبلّغ عمّا فعله التلميح من تلقاء نفسه: التحويم، التركيز، الضغط المطوَّل، Escape، انتهاء المهلة، تلميح آخر.
  storage.addEventListener('toggle', (e) => console.log(e.detail.open));
</script>

import { Button, Tooltip } from '@tanrei/react';

<Tooltip text="نقل إلى المهملات" describes={false}>
  <Button variant="text" label="نقل إلى المهملات" onClick={trash}><span slot="icon">delete</span></Button>
</Tooltip>
{/* مفاتيح الأمر بعد اسمه: تآلف واحد في كل سلسلة نصية. */}
<Tooltip text="غامق" shortcut={['mod+b']} describes={false}>
  <Button variant="text" label="غامق" onClick={bold}><span slot="icon">format_bold</span></Button>
</Tooltip>
{/* تحت عنصر التحكم، محاذيًا لحافة بدايته، مع سهم، على سطح بدل المظهر المعكوس. */}
<Tooltip text="التصفية حسب التاريخ أو المالك" placement="bottom-start" arrow inverse={false}>
  <Button variant="text" label="تصفية" onClick={filter}><span slot="icon">filter_list</span></Button>
</Tooltip>
<Tooltip
  variant="rich"
  headline="التخزين"
  text="الملفات في المهملات تبقى محسوبة من مساحة تخزينك إلى أن تُحذف."
  placement="bottom"
  touchTimeout={4000} // بضع جمل تحتاج إلى وقت أطول لتُقرأ بعد ضغط مطوَّل
  onToggle={(e) => log(e.detail.open)}
>
  <Button variant="text" label="عن التخزين"><span slot="icon">info</span></Button>
</Tooltip>

import Tanrei

// مُعدِّل على عنصر الارتكاز. والمُعدِّل .tanreiTheme(_:) فوقه يستضيف الطبقة التي يُرسم فيها التلميح.
// الوصف يصير accessibilityHint لعنصر الارتكاز.
TanreiIconButton("نقل إلى المهملات", action: trash) { Image(systemName: "trash") }
    .tanreiTooltip("نقل إلى المهملات", describes: false)

// isPresented هي open؛ يكتبها التلميح حين يفتح أو يغلق من تلقاء نفسه.
TanreiIconButton("عن التخزين", action: {}) { Image(systemName: "info.circle") }
    .tanreiTooltip("الملفات في المهملات تبقى محسوبة من مساحة تخزينك إلى أن تُحذف.",
                   title: "التخزين", variant: .rich, placement: .bottom, isPresented: $showHint)

import io.github.chnotchy.tanrei.components.TanreiIconButton
import io.github.chnotchy.tanrei.components.TanreiTooltip
import io.github.chnotchy.tanrei.components.TanreiTooltipPlacement
import io.github.chnotchy.tanrei.components.TanreiTooltipVariant
import io.github.chnotchy.tanrei.components.rememberTanreiTooltipState
import io.github.chnotchy.tanrei.primitives.TanreiText

// مثل TooltipBox في Material: التلميح يحيط بعنصر ارتكازه.
TanreiTooltip(text = "نقل إلى المهملات", describes = false) {
    TanreiIconButton(onClick = ::trash, contentDescription = "نقل إلى المهملات") { TanreiText("delete") }
}

// الحالة (state) هي open. يسمع onToggle ما يفعله التلميح من تلقاء نفسه؛ أما show() و dismiss() فلا يُصدران شيئًا.
val hint = rememberTanreiTooltipState(onToggle = { open -> log(open) })
TanreiTooltip(
    text = "الملفات في المهملات تبقى محسوبة من مساحة تخزينك إلى أن تُحذف.",
    variant = TanreiTooltipVariant.Rich,
    title = "التخزين",
    placement = TanreiTooltipPlacement.Bottom,
    state = hint,
) {
    TanreiIconButton(onClick = {}, contentDescription = "عن التخزين") { TanreiText("info") }
}
LaunchedEffect(Unit) { hint.show() } // تلميح أول تشغيل

import 'package:tanrei/tanrei.dart';

// show() و hide() يضبطان open، ولا يُشعران أحدًا. المستمعون يسمعون ما يفعله التلميح من تلقاء نفسه.
final TanreiTooltipController hint = TanreiTooltipController();
hint.addListener(() => log(hint.isOpen));

// مثل Tooltip في Flutter: message هو النص، و excludeFromSemantics هو describes معكوسًا.
TanreiTooltip(
  message: 'نقل إلى المهملات',
  excludeFromSemantics: true, // النص يكرّر اسم الزر نفسه
  child: TanreiIconButton(onPressed: trash, icon: const Icon(AppSymbols.delete), semanticLabel: 'نقل إلى المهملات'),
);
TanreiTooltip(
  variant: TanreiTooltipVariant.rich,
  title: 'التخزين',
  message: 'الملفات في المهملات تبقى محسوبة من مساحة تخزينك إلى أن تُحذف.',
  placement: TanreiTooltipPlacement.bottom,
  controller: hint, // hint.show() لتلميح أول تشغيل
  child: TanreiIconButton(onPressed: info, icon: const Icon(AppSymbols.info), semanticLabel: 'عن التخزين'),
);

import { IconButton, Tooltip } from '@tanrei/react-native';

// عنصر الارتكاز عنصر فرعي واحد يقبل خصائص Pressable. يضيف التلميح معالجاته، ويستدعي معالجات عنصر الارتكاز أولًا.
<Tooltip text="نقل إلى المهملات" describes={false}>
  <IconButton accessibilityLabel="نقل إلى المهملات" onPress={trash}>delete</IconButton>
</Tooltip>

// open تعرضه من شيفرتك ولا تُصدر شيئًا؛ و onOpenChange يسمع ما يفعله من تلقاء نفسه.
<Tooltip
  variant="rich"
  headline="التخزين"
  text="الملفات في المهملات تبقى محسوبة من مساحة تخزينك إلى أن تُحذف."
  placement="bottom"
  open={showHint}
  onOpenChange={setShowHint}
>
  <IconButton accessibilityLabel="عن التخزين">info</IconButton>
</Tooltip>

المواصفات

تلميح من الطراز تحت عنصر ارتكازه، وتلميح من الطراز rich بلا عنوان

delete

info

البنية

الجزء	الوصف
1 `anchor`	The element the tooltip describes: the product's own (an icon-only Button, a truncated label, a chart mark). The tooltip adds a description to it and changes nothing else about it.
2 `container`	The surface that holds the text, placed on one side of the anchor and aligned along it.
3 `arrow` · اختياري	A triangle on the container's edge that faces the anchor, pointing at it; one shape with the container.
4 `title` · اختياري	A short heading above the supporting text. Rich tooltips only.
5 `supporting-text`	The description. A plain tooltip holds nothing else.
6 `shortcut` · اختياري	The keys that perform the anchor's command, after the text. Plain tooltips only.

الخصائص

الخاصية	النوع	القيمة الافتراضية	الوصف
`variant`	`plain` \| `rich`	`"plain"`	Plain is one short phrase, by default on the inverse surface, for naming what an icon does. Rich is an optional title and a few sentences, by default on a raised surface, for explaining a term or a setting. A structural choice drawn by code, not a token axis: a design system cannot add a form by values.
`text`	`string`	`""`	The description. Required.
`title`	`string`	`""`	A heading for a rich tooltip. Ignored by a plain one.
`shortcut`	`strings`		The keyboard shortcut of the anchor's command, in the keyboard shortcut component's key names: one chord per string, pressed in order (["mod+b"]). A plain tooltip draws it after the text for the keyboard the person uses and exposes it as the anchor's keyboard shortcut (TIP-27); a rich one ignores it. It does not make the keys work; the product binds them.
`placement`	`top` \| `top-start` \| `top-end` \| `bottom` \| `bottom-start` \| `bottom-end` \| `start` \| `start-top` \| `start-bottom` \| `end` \| `end-top` \| `end-bottom` \| `auto`	`"top"`	Where the tooltip prefers to stand: a side of the anchor, and how it lines up along that side (TIP-22). top and bottom centre it above or below the anchor; with -start or -end its start or end edge meets the anchor's. start and end centre it beside the anchor; with -top or -bottom its top or bottom edge meets the anchor's. auto takes the first side with room (TIP-23). Start and end follow the layout direction. The tooltip flips to the opposite side when the preferred one has no room, keeping the alignment (TIP-9).
`offset`	`number`	`null`	The distance between the anchor's edge and the tooltip, in the platform's layout units; 0 lets them touch. Null takes comp.tooltip.offset, the system's answer for every tooltip. Set it only where one anchor's box is not what the eye takes for its edge (a control with a large invisible hit area, a mark of a chart).
`crossOffset`	`number`	`0`	How far the tooltip moves along the side it stands on, in the platform's layout units, from where placement puts it: positive towards the end for a tooltip above or below, towards the bottom for one beside. For lining an aligned tooltip up with what is drawn inside the anchor rather than with the anchor's box. It never moves the tooltip off the anchor's side (TIP-24).
`arrow`	`boolean`	`null`	Whether the tooltip draws an arrow that points at the anchor. Null, the default, takes comp.tooltip.arrow.visible, the system's choice, which is off in the default system (TIP-25).
`inverse`	`boolean`	`null`	Whether this tooltip is drawn inverse: in the opposite scheme's colors, so that it stands apart from whatever it lands on. False draws it on a surface of the scheme. Null, the default, takes its form's choice: comp.tooltip.plain.container.inverse (on in the default system) or comp.tooltip.rich.container.inverse (off). It changes colors and elevation only (TIP-26).
`describes`	`boolean`	`true`	Whether assistive technology reads the text as the anchor's description. Set it to false when the text repeats the anchor's own accessible name (an icon-only Button whose tooltip shows its label), so that it is not read twice.
`open`	`boolean`	`false`	Whether the tooltip is showing. The tooltip opens and closes itself on hover, focus and long-press and reports it (toggle). A product sets it to show a tooltip on its own (a first-run hint); a snapshot harness sets it to draw a fixture.
`showDelay`	`number`	`null`	How long, in milliseconds, a fine pointer rests on the anchor before this tooltip opens; 0 opens it at once. Null takes comp.tooltip.motion.show-delay, the system's answer for every tooltip. Set it only where one tooltip needs another pace than the rest (a dense toolbar that wants its names sooner, a chart whose marks the pointer sweeps across and should not flash). It applies to hover alone: keyboard focus still opens at once.
`hideDelay`	`number`	`null`	How long, in milliseconds, this tooltip waits after the pointer has left the anchor, the gap and the tooltip before it closes; 0 closes it at once. Null takes comp.tooltip.motion.hide-delay. The tooltip stays hoverable at any value, 0 included, because the gap between the anchor and the tooltip counts as hover (TIP-1).
`touchTimeout`	`number`	`null`	How long, in milliseconds, a tooltip opened by a long-press stays after the finger lifts; 0 closes it as the finger lifts, so it shows for as long as the press lasts. Null takes comp.tooltip.timeout.touch. Set it only where one tooltip needs more or less reading time on touch than the rest (a rich tooltip of a few sentences, a one-word name).

المنافذ

المنفذ	الوصف
`default`	The anchor.

الأحداث

الحدث	الوصف
`toggle`	The tooltip opened or closed by itself (hover, focus, long-press, Escape, the touch timeout, another tooltip opening); carries the new open value.

الحالات

السلوك

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

المعرّف	المتطلب
`TIP-1`	WHEN a fine pointer enters the anchor and stays on it for the show delay (TIP-17) THE tooltip SHALL open; WHEN the pointer leaves the anchor THE tooltip SHALL stay open while the pointer crosses the gap to the tooltip or moves onto the tooltip itself, and SHALL close once the pointer has been off the anchor, the gap and the tooltip for the hide delay (TIP-17). The gap is the strip between the anchor's edge and the container — the offset deep (TIP-24), and comp.tooltip.arrow.height deeper while an arrow is drawn (TIP-25) — as wide as the container along that side; it counts for hover alone, is not drawn and takes no press.
`TIP-2`	WHEN the anchor receives keyboard focus THE tooltip SHALL open without delay, and WHEN the anchor loses focus THE tooltip SHALL close; focus gained by pointer or touch SHALL NOT open it.
`TIP-3`	WHEN the user long-presses the anchor by touch THE tooltip SHALL open without activating the anchor, and WHEN the finger lifts SHALL stay open for the touch timeout (TIP-17) and then close; a touch anywhere else SHALL close it sooner.
`TIP-4`	WHILE the tooltip is open, WHEN the user presses Escape THE tooltip SHALL close without moving focus and SHALL consume the key, so that it does not also close an enclosing dialog; it SHALL stay closed until the anchor is entered by the pointer or focused again.
`TIP-5`	WHILE the pointer is over the anchor or the tooltip, or the anchor has keyboard focus, THE tooltip SHALL stay open with no time limit, until Escape (TIP-4), an activation of the anchor (TIP-6) or another tooltip opening (TIP-8) closes it.
`TIP-6`	WHEN the anchor is activated (a click, a tap, Enter or Space) THE tooltip SHALL close, and SHALL NOT open again from the same hover until the pointer has left the anchor and entered it again.
`TIP-7`	WHEN the tooltip opens or closes by itself (TIP-1 to TIP-6, TIP-8) THE tooltip SHALL emit toggle with the new value; WHEN the product sets open THE tooltip SHALL show or hide accordingly without emitting toggle, and SHALL then keep following TIP-1 to TIP-6.
`TIP-8`	WHEN a tooltip opens while another tooltip is open THE other tooltip SHALL close at once, and the new one SHALL open without waiting for its show delay (TIP-17), because the person is already reading tooltips; at most one tooltip SHALL be open in a window.
`TIP-9`	THE tooltip SHALL place its container on the side of the anchor and with the alignment that placement names (TIP-22, TIP-23), the offset away from the anchor's edge and moved along the side by crossOffset (TIP-24), and SHALL keep it at least comp.tooltip.window-margin inside the window's safe area by these steps, in this order: WHEN the preferred side has no room for the container and the opposite side has, it SHALL flip to the opposite side, keeping the alignment; WHEN neither has room it SHALL use the one of the two with more room; it SHALL then shift along the side as far as the margin asks and no farther; and WHERE the container is still larger than the room on its side (a window smaller than the tooltip) it SHALL move the container back into the margin over the anchor, its top and start edges first, rather than leave the window. It SHALL follow the anchor when the anchor moves (scrolling, resizing, layout), taking these steps again from the side it is on, which it SHALL keep for as long as that side has room, so that a page that scrolls does not throw the tooltip from side to side; and it SHALL close WHEN the anchor is removed, hidden, scrolled out of the window, or scrolled out of sight inside a scrolling ancestor so that no part of it can be seen.
`TIP-10`	WHILE variant is plain THE tooltip SHALL draw text in comp.tooltip.plain.supporting-text.typescale and comp.tooltip.plain.supporting-text.color on a container of comp.tooltip.plain.container.color with comp.tooltip.plain.container.shape corners and comp.tooltip.plain.container.elevation — or, WHILE it is drawn on a surface, in the colors and the elevation TIP-26 names in their place — padded by comp.tooltip.plain.container.padding-inline and comp.tooltip.plain.container.padding-block, at least comp.tooltip.plain.container.min-height tall and at most comp.tooltip.plain.container.max-width wide, wrapping longer text onto further lines; it SHALL draw its shortcut as TIP-27 says and SHALL ignore title.
`TIP-11`	WHILE variant is rich THE tooltip SHALL draw title in comp.tooltip.rich.title.typescale and comp.tooltip.rich.title.color above text in comp.tooltip.rich.supporting-text.typescale and comp.tooltip.rich.supporting-text.color, comp.tooltip.rich.container.gap apart, on a container of comp.tooltip.rich.container.color with comp.tooltip.rich.container.shape corners and comp.tooltip.rich.container.elevation — or, WHILE it is drawn inverse, in the colors and the elevation TIP-26 names in their place — padded by comp.tooltip.rich.container.padding-inline and comp.tooltip.rich.container.padding-block and at most comp.tooltip.rich.container.max-width wide; WHILE title is empty it SHALL draw the supporting text alone. THE tooltip SHALL set the title's letter-spacing by the script of its text, as every title is set (PRS-20): no negative letter-spacing WHERE its language is Chinese, Japanese or Korean, and none WHERE its script joins its letters or stacks marks on them.
`TIP-12`	THE tooltip SHALL ease its container corners by sys.shape.corner-smoothing (0 is a quarter circle, 0.6 the iOS continuous corner; a platform with only the OS curve draws it for any amount above 0), SHALL grow with enlarged text without clipping it, and SHALL start-align its text by the layout direction.
`TIP-13`	THE tooltip SHALL NOT take focus, SHALL hold nothing focusable or pressable, SHALL NOT make anything inert or dimmed, and SHALL be drawn above every other layer of its window, including an open dialog and its scrim; a press on the tooltip SHALL close it and SHALL NOT reach what lies under it.
`TIP-14`	WHILE describes is true THE tooltip SHALL expose text — preceded by title for a rich tooltip — as the anchor's accessible description, whether or not the tooltip is open, and SHALL keep the drawn tooltip from being read a second time; WHILE describes is false it SHALL add nothing to the anchor's semantics. In both cases it SHALL NOT change the anchor's accessible name or role.
`TIP-15`	WHEN the tooltip opens THE tooltip SHALL appear as every surface appears: from sys.motion.appear.opacity, sys.motion.appear.scale, sys.motion.appear.distance toward its anchor and sys.motion.appear.blur to whole, grown from the middle of its edge that faces the anchor — from its own centre WHERE sys.motion.appear.origin is center, and WHILE it covers its anchor (TIP-9) — over comp.tooltip.motion.enter-duration with comp.tooltip.motion.enter-easing, so that it comes out of the anchor's side whichever side it is on; WHEN it closes THE tooltip SHALL take it back the same way to where it started, over comp.tooltip.motion.exit-duration with comp.tooltip.motion.exit-easing. WHERE sys.behavior.appearance is unfold the scale SHALL apply along the axis that leaves the anchor only. The motion SHALL be drawn only: the place TIP-9 gives, the gap of TIP-1 and the room the tooltip is measured for are those of the tooltip at rest. WHERE motion is reduced THE tooltip SHALL only fade in and out, over sys.motion.role.reduced, with no scale, distance or blur, or appear and disappear at once on a platform whose reduced-motion setting removes every animation (Android's). WHEN it is mounted with open true THE tooltip SHALL appear without its motion while the document has not yet been first painted, and with it when it is mounted after that. A tooltip that takes over from another SHALL NOT move at all (TIP-28).
`TIP-16`	WHILE text is empty THE tooltip SHALL NOT open and SHALL add nothing to the anchor's semantics, and in debug builds SHALL report the empty text; WHILE variant is plain and title is set it SHALL report the ignored title in debug builds.
`TIP-17`	THE tooltip SHALL take its show delay from showDelay, its hide delay from hideDelay and its touch timeout from touchTimeout, each a number of milliseconds used as given (the motion dial does not scale it), so that 0 opens or closes at once: a show delay of 0 opens as the pointer enters, a hide delay of 0 closes as the pointer leaves the anchor, the gap and the tooltip, and a touch timeout of 0 closes as the finger lifts, after the tooltip has shown for the whole long-press. WHILE one of them is null THE tooltip SHALL use comp.tooltip.motion.show-delay, comp.tooltip.motion.hide-delay or comp.tooltip.timeout.touch in its place, and IF one is negative or not a finite number THE tooltip SHALL use that token likewise and in debug builds report the value it ignored.
`TIP-18`	THE tooltip SHALL treat its show delay, hide delay and touch timeout as waiting times, not motion: WHERE motion is reduced it SHALL keep them, on every platform, including one whose reduced-motion setting removes every animation. The show and hide delays SHALL govern hover alone (TIP-1), and the touch timeout the time after a long-press alone (TIP-3): keyboard focus (TIP-2), another tooltip being open (TIP-8) and the product setting open (TIP-7) SHALL NOT wait for any of them, and the long-press itself SHALL take the platform's own duration. WHEN showDelay, hideDelay or touchTimeout changes while that wait is running THE tooltip SHALL finish the running wait and use the new value from the next time that wait starts.
`TIP-19`	THE tooltip 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 tooltip is shown THE tooltip SHALL draw itself for the new direction at once, without a motion of its own, keeping its open state, the container placed again by the new direction (TIP-20).
`TIP-20`	WHEN the layout direction is right-to-left THE tooltip SHALL take the side start as the anchor's right side and the side end as its left, SHALL take the alignments -start and -end of a tooltip above or below as the right and the left edges, and a positive crossOffset of such a tooltip as a move towards the left, flipping and shifting from there as TIP-9 says; it SHALL leave the sides top and bottom, the alignments -top and -bottom, a crossOffset beside the anchor and the centring on the anchor as they are, SHALL keep auto's order of sides by their names (TIP-23), SHALL start-align a rich tooltip's title and text at the right (TIP-12) and SHALL draw a plain tooltip's shortcut at the left of its text (TIP-27).
`TIP-21`	THE tooltip SHALL lay out its title and its text 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 tooltip SHALL still place each and align its lines by the layout direction, not by the text's own.
`TIP-22`	THE tooltip SHALL read placement as a side and an alignment along that side: top and bottom SHALL put the container above or below the anchor with its centre on the anchor's, top-start and bottom-start with its start edge on the anchor's start edge, and top-end and bottom-end with its end edge on the anchor's end edge; start and end SHALL put it beside the anchor, on the side the layout direction gives that name, with its centre on the anchor's, start-top and end-top with its top edge on the anchor's top edge, and start-bottom and end-bottom with its bottom edge on the anchor's bottom edge. WHEN placement names a value the tooltip does not define THE tooltip SHALL place itself as the default value says and in debug builds report the unknown value; WHEN placement changes while the tooltip is shown THE tooltip SHALL take its new place at once, without a motion.
`TIP-23`	WHILE placement is auto THE tooltip SHALL try the sides in the order top, bottom, end, start and SHALL take the first that has room for the container within comp.tooltip.window-margin, or the one with the most room WHEN none has, with its centre on the anchor's, and SHALL then shift, hold and follow as TIP-9 says, keeping the side it took for as long as that side has room.
`TIP-24`	THE tooltip SHALL take the distance between the anchor's edge and the nearest part of itself — the container's edge, or the arrow's tip while an arrow is drawn — from offset, a number of the platform's layout units used as given, so that 0 lets the two touch, and from comp.tooltip.offset WHILE offset is null; it SHALL then move the container along its side by crossOffset, before the shift of TIP-9, and by no more than leaves comp.tooltip.arrow.width of the container beside the anchor, so that the tooltip still stands on the anchor's side and an arrow can still reach the anchor. IF offset is negative or not a finite number THE tooltip SHALL use comp.tooltip.offset in its place, IF crossOffset is not a finite number THE tooltip SHALL use 0, and in debug builds it SHALL report the value it ignored.
`TIP-25`	THE tooltip SHALL draw an arrow WHILE arrow is true, and WHILE arrow is null and comp.tooltip.arrow.visible is on, and none otherwise. WHILE it draws one THE tooltip SHALL draw a triangle comp.tooltip.arrow.width wide at its base and comp.tooltip.arrow.height tall on the container's edge that faces the anchor, as one shape with the container — the container's color and elevation, with no seam and no shadow between the two — its tip pointing at the middle of the part of the anchor's edge that the container stands beside, and SHALL keep its base at least comp.tooltip.arrow.inset, and at least the corner's radius, from each end of that edge, standing at the edge's middle where the edge is too short for both; the container SHALL stand comp.tooltip.arrow.height farther from the anchor, so that the tip keeps the offset (TIP-24). WHEN the container flips, shifts or follows the anchor (TIP-9) the arrow SHALL move with it to the edge that now faces the anchor and point at the anchor again, and WHILE the container covers the anchor (TIP-9) THE tooltip SHALL draw no arrow.
`TIP-26`	THE tooltip SHALL draw itself inverse — in the opposite scheme's colors — WHILE inverse is true, on a surface of the scheme WHILE inverse is false, and WHILE inverse is null as its form's choice says: comp.tooltip.plain.container.inverse for a plain tooltip and comp.tooltip.rich.container.inverse for a rich one. The tokens TIP-10 and TIP-27 name are a plain tooltip's inverse look: WHILE drawn on a surface a plain tooltip SHALL take comp.tooltip.plain.surface.container.color, comp.tooltip.plain.surface.container.elevation, comp.tooltip.plain.surface.supporting-text.color and comp.tooltip.plain.surface.shortcut.color in their place. The tokens TIP-11 names are a rich tooltip's surface look: WHILE drawn inverse a rich one SHALL take comp.tooltip.rich.inverse.container.color, comp.tooltip.rich.inverse.container.elevation, comp.tooltip.rich.inverse.title.color and comp.tooltip.rich.inverse.supporting-text.color in place of those TIP-11 names; its shape, padding, sizes, typescales, arrow, placement, motion and timing SHALL be the same either way, and WHEN inverse changes while the tooltip is shown THE tooltip SHALL draw the other look at once, keeping its open state.
`TIP-27`	WHILE variant is plain and shortcut is not empty THE tooltip SHALL draw the shortcut after the text, comp.tooltip.plain.container.gap from it and on the text's first line, with the keyboard shortcut component hosted as KBS-13 says: in its plain form, at size small, with convention auto, its legends and separators in comp.tooltip.plain.supporting-text.typescale and comp.tooltip.plain.shortcut.color; the shortcut SHALL stay whole on one line while the text wraps beside it, and the two with the gap SHALL fit within comp.tooltip.plain.container.max-width. THE tooltip SHALL expose the shortcut as the anchor's keyboard shortcut in the form KBS-12 gives (aria-keyshortcuts on the web) where the platform has that property and the anchor does not state one itself, and otherwise, WHILE describes is true, SHALL add the text KBS-10 gives to the end of the anchor's description; it SHALL NOT make the keys work. WHILE variant is rich THE tooltip SHALL ignore shortcut and in debug builds report it.
`TIP-28`	WHEN a tooltip opens while another tooltip of its window is open or still fading out, or within comp.tooltip.motion.warm-duration after one closed because the pointer or the keyboard focus left its anchor THE tooltip SHALL appear whole in its place at once, without the motion of TIP-15, and the other SHALL disappear at once, without its own; WHEN it is a pointer that opens it within that time THE tooltip SHALL NOT wait for its show delay either, as TIP-8 says of a tooltip that opens while another is open. A tooltip closed by Escape (TIP-4), by an activation of its anchor (TIP-6) or by a press on it (TIP-13) SHALL start no such time, so that the next tooltip waits and moves as a first one does. The time is a waiting time: WHERE motion is reduced it SHALL still apply (TIP-18).
`TIP-29`	WHEN the tooltip is told to close while it is still entering, or to open while it is still leaving THE tooltip SHALL turn round from the opacity, the size and the position it has reached, without first jumping to the start or the end of either motion, and SHALL take no longer over the rest than the whole duration of the motion it turns to. WHILE the tooltip is closed or leaving THE tooltip SHALL take no pointer input — a press reaches what lies under it, and the pointer on it is not hover (TIP-1) — and WHILE it is closed it SHALL take no room in the layout and draw nothing, so that a tooltip nobody can see never stands in the way of what is under it.

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

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

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
المكوّن	`tanrei-tooltip`	`tanreiTooltip`	`TanreiTooltip`	`TanreiTooltip`	`Tooltip`
`variant` · الخاصية	`variant`	`variant`	`variant`	`variant`	`variant`
`text` · الخاصية	`text`	`text`	`text`	`message`	`text`
`title` · الخاصية	`headline`	`title`	`title`	`title`	`title`
`shortcut` · الخاصية	`shortcut`	`shortcut`	`shortcut`	`shortcut`	`shortcut`
`placement` · الخاصية	`placement`	`placement`	`placement`	`placement`	`placement`
`offset` · الخاصية	`offset`	`offset`	`offset`	`offset`	`offset`
`crossOffset` · الخاصية	`crossOffset`	`crossOffset`	`crossOffset`	`crossOffset`	`crossOffset`
`arrow` · الخاصية	`arrow`	`arrow`	`arrow`	`arrow`	`arrow`
`inverse` · الخاصية	`inverse`	`inverse`	`inverse`	`inverse`	`inverse`
`describes` · الخاصية	`describes`	`describes`	`describes`	`excludeFromSemantics`	`describes`
`open` · الخاصية	`open`	`isPresented`	`state`	`controller`	`open`
`showDelay` · الخاصية	`showDelay`	`showDelay`	`showDelayMillis`	`waitDuration`	`showDelay`
`hideDelay` · الخاصية	`hideDelay`	`hideDelay`	`hideDelayMillis`	`exitDuration`	`hideDelay`
`touchTimeout` · الخاصية	`touchTimeout`	`touchTimeout`	`touchTimeoutMillis`	`showDuration`	`touchTimeout`
`toggle` · الحدث	`toggle`	`isPresented`	`state`	`controller`	`onOpenChange`
ملاحظات	Wraps its anchor (the default slot). `showDelay`, `hideDelay` and `touchTimeout` are number properties in milliseconds, null by default, set by the `show-delay`, `hide-delay` and `touch-timeout` attributes; an attribute that is empty or does not parse as a finite number is not a number (TIP-17), so `show-delay=""` takes the token and does not open at once. The gap of TIP-1 is measured, not drawn: the document's pointer-move listener counts a point inside it as over the tooltip, so nothing in the top layer covers what lies under the gap. The drawn tooltip is a `popover="manual"` element in the shadow root, so it is in the top layer (above an open modal `<dialog>`); it is placed with CSS anchor positioning and `position-try` flips where supported, and by measuring otherwise. `describes` is a boolean property that defaults to true; its attribute is the inverse `no-describe`, because an HTML boolean attribute cannot default to true. `toggle` is a CustomEvent whose `detail.open` is the new value. Snapshot harness: each fixture is a stage of 320 × 200 with a medium icon-only text `tanrei-button` labelled after the fixture's glyph at its centre, and the tooltip open beside it. `placement` takes the thirteen values as written (`top-start`, `end-bottom`, `auto`); `offset` and `crossOffset` are number properties in CSS pixels (attributes `offset`, `cross-offset`), parsed as the delays are, so an empty attribute is not a number. `arrow` and `inverse` are properties that are true, false or null: the attribute is absent for null, present for true and `="false"` for false, as the snackbar's `inverse` is; null reads the choice from the cascade. `shortcut` is an array property; its attribute holds the chords separated by spaces, as the keyboard shortcut's `keys` does, and the shortcut reaches the anchor's focusable element as `aria-keyshortcuts` unless that element already has one. The container and the arrow are one painted shape, so the elevation's ring and shadows run round both. The enter and exit motion runs on a wrapper inside the popover whose transform origin is set from the placement that was taken; the popover element itself keeps its placed box, so the measured gap and the following do not see the motion. The time tooltips stay warm is kept per window, beside the one showing tooltip. Snapshot harness: the stage sets `data-tanrei-keyboard-convention="standard"`, so `plain-shortcut` reads the same on every machine.	Lagging: has no delay or timeout parameters and no hover gap; owes TIP-1 (the gap), TIP-3 and TIP-8's wording, TIP-17 and TIP-18. The target: a view modifier `.tanreiTooltip(_ text:, title:, variant:, placement:, describes:, showDelay: Duration? = nil, hideDelay: Duration? = nil, touchTimeout: Duration? = nil, isPresented: Binding<Bool>?)`; a `Duration` carries its own unit (`.milliseconds(300)`), nil takes the token, and a negative one takes the token and is reported in debug builds. The description is the anchor's `accessibilityHint`. The tooltip is drawn in an overlay above the window's content (anchored with anchor preferences), not with `.popover`, which is modal at compact widths and moves VoiceOver focus: a non-modal overlay must do neither. Hover is `onContinuousHover` (iPadOS and macOS pointers), keyboard focus is `focused` with full keyboard access, long-press is a `LongPressGesture` that does not fire the anchor's action. Snapshot harness: renders the anchor and the open tooltip in a fixed 320 × 200 frame. Also owed: the thirteen placement values, offset, crossOffset, arrow, inverse and shortcut; TIP-9 and TIP-15 as they read now and TIP-22 to TIP-29. `offset` and `crossOffset` are `CGFloat?` and `CGFloat` in points; `arrow` and `inverse` are `Bool?`, nil taking the system's choice; `shortcut` is `[String]`, exposed with the anchor's `keyboardShortcut` semantics where it has one and in the hint otherwise. The container and the arrow are one `Shape`. Snapshot harness: the stage sets the standard keyboard convention for `plain-shortcut`. Not yet: the title's letter-spacing by the script of its text (TIP-11, PRS-20).	Lagging: has no delay or timeout parameters and no hover gap; owes TIP-1 (the gap), TIP-3 and TIP-8's wording, TIP-17 and TIP-18. The target: `TanreiTooltip(text, modifier, variant, title, placement, describes, showDelayMillis: Long? = null, hideDelayMillis: Long? = null, touchTimeoutMillis: Long? = null, state = rememberTanreiTooltipState()) { anchor }`, shaped like Material's `TooltipBox`, the times named in milliseconds as `ViewConfiguration.longPressTimeoutMillis` is; null takes the token, a negative value takes the token and is reported in debug builds. The waits are coroutine delays, not animations, so the animator duration scale of 0 (Android's reduced motion) does not remove them (TIP-18); `state.isVisible` is open, and `state.show()` / `state.dismiss()` set it. The tooltip is a `Popup` with `PopupProperties(focusable = false)`. Compose has no separate description semantics: the text is appended to the anchor's merged semantics after its own name, as Android reads a View's tooltip text, and a test asserts the order. Snapshot harness: renders the anchor and the open tooltip in a fixed 320 × 200 frame. Also owed: the thirteen placement values, offset, crossOffset, arrow, inverse and shortcut; TIP-9 and TIP-15 as they read now and TIP-22 to TIP-29. `offset` and `crossOffset` are `Dp?` and `Dp`; `arrow` and `inverse` are `Boolean?`, null taking the system's choice; `shortcut` is `List<String>`. The container and the arrow are one `Shape`, so the shadow follows both. The warm time is a coroutine delay, kept at an animator duration scale of 0 (TIP-28). Snapshot harness: the stage sets the standard keyboard convention for `plain-shortcut`. Not yet: the title's letter-spacing by the script of its text (TIP-11, PRS-20).	Lagging: has no delay or timeout parameters and no hover gap; owes TIP-1 (the gap), TIP-3 and TIP-8's wording, TIP-17 and TIP-18. Named as Flutter's `Tooltip`: `message` is the text, `excludeFromSemantics` is the inverse of describes, the delays are `waitDuration` and `exitDuration`, and the touch timeout is `showDuration`, which Flutter's `Tooltip` uses for the time after a long-press is released (each a `Duration?`: null takes the token, a negative one takes the token and is reported in debug builds). The description is the anchor's `Semantics(tooltip:)`. The tooltip is drawn through an `OverlayPortal` (the overlay of the nearest `Overlay`, so above a dialog route opened earlier). `controller` is a `TanreiTooltipController` (a `ChangeNotifier` with `show()`, `hide()` and `isOpen`). Snapshot harness: a golden of the anchor and the open tooltip in a 320 × 200 surface. Also owed: the thirteen placement values, offset, crossOffset, arrow, inverse and shortcut; TIP-9 and TIP-15 as they read now and TIP-22 to TIP-29. `offset` and `crossOffset` are `double?` and `double` in logical pixels (Flutter's own `Tooltip` calls the first `verticalOffset`; this one is not vertical only); `arrow` and `inverse` are `bool?`, null taking the system's choice; `shortcut` is `List<String>`. The container and the arrow are one `ShapeBorder`. Snapshot harness: the stage sets the standard keyboard convention for `plain-shortcut`. Not yet: the title's letter-spacing by the script of its text (TIP-11, PRS-20).	Lagging: has no delay or timeout props and no hover gap; owes TIP-1 (the gap), TIP-3 and TIP-8's wording, TIP-17 and TIP-18. The target: `showDelay`, `hideDelay` and `touchTimeout` are numbers of milliseconds, as `Pressable`'s `delayLongPress` is; undefined or null takes the token, and a negative or non-finite number takes the token and is reported in development builds. Wraps its anchor (`children`). The description is the anchor's `accessibilityHint`. The tooltip is drawn in the overlay layer that `TanreiProvider` renders at the root of the app, not in a `Modal`: a `Modal` is modal (it takes every touch and moves accessibility focus), which a non-modal overlay must not be. Hover comes from `onHoverIn`/`onHoverOut` on platforms with a pointer. Snapshot harness: renders the anchor and the open tooltip in a fixed 320 × 200 view. Also owed: the thirteen placement values, offset, crossOffset, arrow, inverse and shortcut; TIP-9 and TIP-15 as they read now and TIP-22 to TIP-29. `offset` and `crossOffset` are numbers of density-independent pixels; `arrow` and `inverse` are booleans, undefined or null taking the system's choice; `shortcut` is a string array. The container and the arrow are one drawn shape. Snapshot harness: the stage sets the standard keyboard convention for `plain-shortcut`. Not yet: the title's letter-spacing by the script of its text (TIP-11, PRS-20).

الرموز

الرمز	يشير إلى	القيمة المحلولة (فاتح)
`--tanrei-comp-tooltip-arrow-height`	`sys.space.space75`	6px
`--tanrei-comp-tooltip-arrow-inset`	`sys.space.space100`	8px
`--tanrei-comp-tooltip-arrow-visible`	—	0
`--tanrei-comp-tooltip-arrow-width`	`sys.space.space150`	12px
`--tanrei-comp-tooltip-motion-enter-duration`	`sys.motion.role.appear.hint.enter`	250ms
`--tanrei-comp-tooltip-motion-enter-easing`	`sys.motion.easing.enter`	cubic-bezier(0.2, 0, 0, 1)
`--tanrei-comp-tooltip-motion-exit-duration`	`sys.motion.role.appear.hint.exit`	200ms
`--tanrei-comp-tooltip-motion-exit-easing`	`sys.motion.easing.exit`	cubic-bezier(0.3, 0, 1, 1)
`--tanrei-comp-tooltip-motion-hide-delay`	`sys.motion.duration.short2`	100ms
`--tanrei-comp-tooltip-motion-show-delay`	`sys.motion.duration.long2`	500ms
`--tanrei-comp-tooltip-motion-warm-duration`	`sys.motion.duration.medium2`	300ms
`--tanrei-comp-tooltip-offset`	`sys.space.space50`	4px
`--tanrei-comp-tooltip-plain-container-color`	`sys.color.inverse-surface`	#1f1f1f
`--tanrei-comp-tooltip-plain-container-elevation`	`sys.elevation.level0`
`--tanrei-comp-tooltip-plain-container-gap`	`sys.space.space100`	8px
`--tanrei-comp-tooltip-plain-container-inverse`	—	1
`--tanrei-comp-tooltip-plain-container-max-width`	—	200px
`--tanrei-comp-tooltip-plain-container-min-height`	—	24px
`--tanrei-comp-tooltip-plain-container-padding-block`	`sys.space.space50`	4px
`--tanrei-comp-tooltip-plain-container-padding-inline`	`sys.space.space100`	8px
`--tanrei-comp-tooltip-plain-container-shape`	`sys.shape.corner.small`	6px
`--tanrei-comp-tooltip-plain-shortcut-color`	`sys.color.inverse-on-surface`	#f1f1f1
`--tanrei-comp-tooltip-plain-supporting-text-color`	`sys.color.inverse-on-surface`	#f1f1f1
`--tanrei-comp-tooltip-plain-surface-container-color`	`sys.color.surface-bright`	#ffffff
`--tanrei-comp-tooltip-plain-surface-container-elevation`	`sys.elevation.level2`	0px 0px 0px 1px rgb(0 0 0 / 0.08), 0px 1px 2px 0px rgb(0 0 0 / 0.04)
`--tanrei-comp-tooltip-plain-surface-shortcut-color`	`sys.color.on-surface-variant`	#4b4b4b
`--tanrei-comp-tooltip-plain-surface-supporting-text-color`	`sys.color.on-surface`	#1b1b1b
`--tanrei-comp-tooltip-rich-container-color`	`sys.color.surface-bright`	#ffffff
`--tanrei-comp-tooltip-rich-container-elevation`	`sys.elevation.level2`	0px 0px 0px 1px rgb(0 0 0 / 0.08), 0px 1px 2px 0px rgb(0 0 0 / 0.04)
`--tanrei-comp-tooltip-rich-container-gap`	`sys.space.space50`	4px
`--tanrei-comp-tooltip-rich-container-inverse`	—	0
`--tanrei-comp-tooltip-rich-container-max-width`	—	320px
`--tanrei-comp-tooltip-rich-container-padding-block`	`sys.space.space150`	12px
`--tanrei-comp-tooltip-rich-container-padding-inline`	`sys.space.space200`	16px
`--tanrei-comp-tooltip-rich-container-shape`	`sys.shape.corner.medium`	8px
`--tanrei-comp-tooltip-rich-inverse-container-color`	`sys.color.inverse-surface`	#1f1f1f
`--tanrei-comp-tooltip-rich-inverse-container-elevation`	`sys.elevation.level0`
`--tanrei-comp-tooltip-rich-inverse-supporting-text-color`	`sys.color.inverse-on-surface`	#f1f1f1
`--tanrei-comp-tooltip-rich-inverse-title-color`	`sys.color.inverse-on-surface`	#f1f1f1
`--tanrei-comp-tooltip-rich-supporting-text-color`	`sys.color.on-surface-variant`	#4b4b4b
`--tanrei-comp-tooltip-rich-title-color`	`sys.color.on-surface`	#1b1b1b
`--tanrei-comp-tooltip-timeout-touch`	—	1500ms
`--tanrei-comp-tooltip-window-margin`	`sys.space.space100`	8px
`--tanrei-comp-tooltip-plain-supporting-text-typescale`	`sys.typescale.body-small`	400 13px/1.5385
`--tanrei-comp-tooltip-rich-supporting-text-typescale`	`sys.typescale.body`	400 14px/1.5714
`--tanrei-comp-tooltip-rich-title-typescale`	`sys.typescale.heading-6`	500 14px/1.4286

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

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

plain

text: Move to trash open: true مرسوم وحده في نافذة بحجم 320 × 200

plain-wrapped

text: Move the selected files to the trash. Th… open: true مرسوم وحده في نافذة بحجم 320 × 200

plain-bottom

text: Move to trash placement: bottom open: true مرسوم وحده في نافذة بحجم 320 × 200

rich

variant: rich text: Trash still counts toward storage. title: Storage open: true مرسوم وحده في نافذة بحجم 320 × 200

rich-untitled

variant: rich text: Files in the trash still count toward yo… open: true مرسوم وحده في نافذة بحجم 320 × 200

plain-top-start

text: Move to trash placement: top-start open: true مرسوم وحده في نافذة بحجم 320 × 200

plain-top-start-rtl

text: Move to trash placement: top-start open: true direction: rtl مرسوم وحده في نافذة بحجم 320 × 200

plain-bottom-end

text: Move to trash placement: bottom-end open: true مرسوم وحده في نافذة بحجم 320 × 200

plain-end-top

text: Move the selected files to the trash. placement: end-top open: true مرسوم وحده في نافذة بحجم 320 × 200

plain-start-bottom

text: Move the selected files to the trash. placement: start-bottom open: true مرسوم وحده في نافذة بحجم 320 × 200

plain-arrow

text: Move to trash arrow: true open: true مرسوم وحده في نافذة بحجم 320 × 200

plain-arrow-top-start

text: Move to trash placement: top-start arrow: true open: true مرسوم وحده في نافذة بحجم 320 × 200

rich-arrow-bottom

variant: rich text: Trash still counts toward storage. title: Storage placement: bottom arrow: true open: true مرسوم وحده في نافذة بحجم 320 × 200

plain-surface

text: Move to trash inverse: false open: true مرسوم وحده في نافذة بحجم 320 × 200

rich-inverse

variant: rich text: Trash still counts toward storage. title: Storage inverse: true open: true مرسوم وحده في نافذة بحجم 320 × 200

plain-shortcut

text: Move to trash shortcut: ["mod+backspace"] open: true مرسوم وحده في نافذة بحجم 320 × 200

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

الإرشادات

متى يُستخدم

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

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

اختيار الطراز

الطراز (variant)	ما هو	يُستخدم لـ
Plain	عبارة قصيرة واحدة، على السطح المعكوس (inverse) افتراضيًّا. يتجاهل `headline`، ويستطيع أن يعرض اختصار لوحة مفاتيح بعد نصه.	تسمية ما تفعله أيقونة: «نقل إلى المهملات»، «مشاركة».
Rich	عنوان اختياري فوق بضع جمل، على سطح مرتفع افتراضيًّا. يتجاهل `shortcut`.	شرح مصطلح أو إعداد: «التخزين» وما يُحسب منه.

الطراز اختيار بنيوي، لا محور رموز (tokens). يعيد نظام التصميم تنسيق الهيئتين، لكنه لا يستطيع أن يضيف ثالثة بالقيم.

الموضع

الخاصية placement تسمّي جهة عنصر الارتكاز التي يفضّلها التلميح وكيف يُحاذى على امتداد تلك الجهة. القيمة الافتراضية top.

أشِر إلى زر أو ركّز عليه: المواضع الثلاثة عشر

top

top-start

top-end

bottom

bottom-start

bottom-end

start

start-top

start-bottom

end

end-top

end-bottom

auto

الجهة	موسَّط على عنصر الارتكاز	تطابق الحافتين الأوليين	تطابق الحافتين الثانيتين
فوق	`top`	`top-start`	`top-end`
تحت	`bottom`	`bottom-start`	`bottom-end`
قبل عنصر الارتكاز	`start`	`start-top`	`start-bottom`
بعد عنصر الارتكاز	`end`	`end-top`	`end-bottom`

المحاذاة تعني حافة على حافة. القيمة top-start تضع حافة بداية التلميح على حافة بداية عنصر الارتكاز، والقيمة end-bottom تضع حافته السفلية على الحافة السفلية لعنصر الارتكاز. استخدم موضعًا محاذيًا لتلميح عريض على عنصر ارتكاز صغير قرب حافة لوحة، أو لمحاذاة تلميح مع سطر من النص.
البداية والنهاية تتبعان اتجاه التخطيط. في التخطيط من اليمين إلى اليسار (RTL) تكون start هي الجهة اليمنى، وتحاذي top-start الحافتين اليمنيين. أما الأعلى والأسفل فلا ينعكسان.
القيمة auto تجرّب الأعلى ثم الأسفل ثم النهاية ثم البداية بهذا الترتيب وتأخذ أول جهة فيها متّسع، موسَّطةً. استخدمها لعنصر ارتكاز لا تستطيع أن تعرف ما يحيط به، كعنصر تحكم في لوحة قد تُرسى عند أي حافة.
حين لا يوجد متّسع. ينقلب التلميح إلى الجهة المقابلة ويحتفظ بمحاذاته، ثم ينزاح على امتداد الجهة ليبقى داخل المنطقة الآمنة للنافذة. في نافذة أصغر من التلميح يبقى داخل النافذة، ولو فوق عنصر الارتكاز إن لزم. وبعد أن ينقلب يحتفظ بتلك الجهة ما دام فيها متّسع، فلا ترميه الصفحة التي تُمرَّر من جهة إلى أخرى.
الخاصيتان offset و crossOffset. الخاصية offset هي المسافة من حافة عنصر الارتكاز، والقيمة 0 تجعل الاثنين يتلامسان؛ وإن تُركت بلا ضبط كانت مسافة النظام. والخاصية crossOffset تحرّك التلميح على امتداد جهته، نحو النهاية حين يكون فوق عنصر الارتكاز أو تحته ونحو الأسفل حين يكون بجانبه، ولا تُخرجه أبدًا عن جهة عنصر الارتكاز. وكلتاهما بوحدات التخطيط في المنصة. اضبطهما فقط حيث لا يكون صندوق عنصر الارتكاز هو ما تعدّه العين حافته، كعنصر تحكم له مساحة لمس كبيرة غير مرئية أو علامة في مخطط بياني.
تغيير أثناء العرض. قيمة placement الجديدة أو الإزاحة الجديدة تحرّك التلميح فورًا، بلا حركة انتقالية.

السهم

أشِر إلى زر أو ركّز عليه: مع سهم

delete

filter_list

info

الخاصية arrow ترسم مثلثًا صغيرًا على حافة التلميح يشير إلى عنصر الارتكاز. وهو موقوف في النظام الافتراضي. إن تُركت بلا ضبط أخذت اختيار نظام التصميم؛ والقيمتان true و false تقررانه لتلميح واحد. على الويب تُكتب خاصية HTML (attribute) في الصورة arrow للقيمة true و arrow="false" للقيمة false.

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

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

مظهران

أشِر إلى زر أو ركّز عليه: كل هيئة معكوسةً وعلى سطح

Plain, inverse

Plain, surface

Rich, surface

Rich, inverse

يمكن أن تُرسم كل من الهيئتين معكوسةً، بألوان المخطط اللوني المقابل، أو على سطح مرتفع من المخطط اللوني.

`inverse`	Plain	Rich
غير مضبوطة (الافتراضي)	كما يختار نظام التصميم للتلميحات من الطراز plain: معكوس في النظام الافتراضي.	كما يختار نظام التصميم للتلميحات من الطراز rich: سطح في النظام الافتراضي.
`true`	معكوس.	معكوس.
`false`	على سطح.	على سطح.

على الويب تُكتب خاصية HTML في الصورة inverse للقيمة true و inverse="false" للقيمة false، كما في شريط الإشعار.

لا يتغيّر إلا الألوان والارتفاع. الشكل الهندسي والأحجام وأنماط النص والسهم والموضع والحركة واحدة في المظهرين، ولا يقول أي منهما إن التلميح مهم. اضبطه لتلميح واحد لن يتميّز من دونه عمّا حوله: تسمية داكنة فوق عارض صور داكن أو على شريط معكوس، أو ملاحظة أطول فوق سطح مرتفع مزدحم.

اختصار لوحة المفاتيح

أشِر إلى زر أو ركّز عليه: مفاتيح الأمر بعد اسمه

format_bold

format_italic

الخاصية shortcut تعرض مفاتيح أمر عنصر الارتكاز بعد نص التلميح من الطراز plain، مكتوبةً للوحة المفاتيح التي يستخدمها الشخص. وتأخذ أسماء المفاتيح التي يستخدمها مكوّن اختصار لوحة المفاتيح، تآلفًا (chord) واحدًا في كل سلسلة نصية؛ وعلى الويب تحمل خاصية HTML التآلفات مفصولة بمسافات.

التلميح يعرض المفاتيح فقط. لا يجعلها تعمل: منتجك هو الذي يربطها. تبقى المفاتيح كاملة على سطر واحد والنص الطويل يلتف بجانبها. والتلميح من الطراز rich يتجاهل shortcut ويبلّغ عنها في بنيات التنقيح (debug).

الفتح والتركيز والإغلاق

التلميح تراكب قراءة. يأخذ الأشخاص منه معلومة ولا يعملون داخله أبدًا، ولذلك لا يأخذ التركيز أبدًا.

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

لا حدّ زمنيًّا أثناء الاستخدام. ما دام المؤشر فوق عنصر الارتكاز أو التلميح أو الفجوة بينهما، أو ما دام لعنصر الارتكاز تركيز لوحة المفاتيح، يبقى مفتوحًا. الفجوة لا تُرسم ولا تأخذ ضغطًا: تُحسب تحويمًا فقط.
المفتاح Escape. يغلقه المفتاح Escape من دون أن ينقل التركيز، ولا يذهب أبعد من ذلك، فيبقى مربع الحوار المحيط مفتوحًا. ويبقى مغلقًا إلى أن يدخل المؤشر عنصر الارتكاز أو يأخذ العنصر التركيز من جديد.
التفعيل. تفعيل عنصر الارتكاز (بنقرة أو لمسة أو Enter أو Space) يغلقه، والتحويم نفسه لا يفتحه مرة أخرى.
واحد في كل مرة. حين يُفتح تلميح يُغلق أي تلميح آخر في النافذة، ويُفتح الجديد بلا مهلة، لأن الشخص يقرأ التلميحات أصلًا.
التنقل بين التلميحات. التلميح الذي يخلف تلميحًا آخر، أو يُفتح بعد وقت قصير من إغلاق تلميح لأن المؤشر أو التركيز غادر عنصر ارتكازه، يظهر كاملًا فورًا: بلا مهلة وبلا حركة. فالمؤشر الذي يمر على امتداد شريط أدوات يقرأ اسمًا بعد اسم. أما التلميح الذي أُغلق بالمفتاح Escape، أو بتفعيل عنصر ارتكازه، أو بضغط عليه، فلا يبدأ ذلك الوقت.
لا يأخذ التركيز ولا يحجب شيئًا. لا يحمل شيئًا يقبل التركيز أو الضغط، ولا يجعل شيئًا خاملًا (inert)، ولا يرسم حجابًا (scrim). الضغط على التلميح يغلقه ولا يصل إلى ما تحته.
فوق كل شيء. يُرسم فوق كل طبقة أخرى في نافذته، ومنها مربع الحوار المفتوح وحجابه، فالتلميح داخل مربع حوار مرئي.
الموضع. يقف حيث تقول الخاصية placement؛ انظر الموضع. يتبع عنصر الارتكاز وهو يتحرك، ويُغلق حين يُزال عنصر الارتكاز، أو يُخفى، أو يُمرَّر إلى خارج النافذة، أو يُمرَّر إلى خارج النظر داخل منطقة تمرير.
الحركة. يخرج من جهة عنصر الارتكاز كما يظهر كل سطح في نظام التصميم: افتراضيًّا يظهر تدريجيًّا وهو يكبر قليلًا من منتصف الحافة المواجهة لعنصر الارتكاز، ويعود بالطريقة نفسها. الحركة التي تُقاطَع تنعكس من حيث هي. وأثناء إغلاقه لا يأخذ التلميح المؤشر، فلا يقف أبدًا في طريق ما تحته. وحيث الحركة مقلَّلة يظهر ويختفي تدريجيًّا فقط.
الإعلان. لا يُعلَن شيء حين يظهر التلميح. ما دامت describes بالقيمة true، فنصه، بعد العنوان في التلميح من الطراز rich، هو وصف عنصر الارتكاز سواء أكان التلميح مفتوحًا أم لا، ويُمنع التلميح المرسوم من أن يُقرأ مرة ثانية.

مهل خاصة بتلميح واحد

يضبط نظام التصميم مهلة الإظهار ومهلة الإخفاء ومهلة اللمس لكل التلميحات دفعة واحدة. ويستطيع التلميح الواحد أن يضبط مهله بالخصائص showDelay و hideDelay و touchTimeout، بالميلي ثانية. وإن تُركت إحداها بلا ضبط أخذت قيمة النظام.

متى تضبطها. اضبط مهلة إظهار أقصر في شريط أدوات كثيف يريد أسماءه أبكر، ومهلة أطول فوق مخطط بياني يمر المؤشر على علاماته، حتى لا يومض أي تلميح. اضبط مهلة لمس أطول على تلميح من الطراز rich فيه بضع جمل، ومهلة أقصر على اسم من كلمة واحدة.
القيمة 0 تعني فورًا. مهلة الإظهار 0 تفتح التلميح لحظة دخول المؤشر عنصر الارتكاز، ومهلة الإخفاء 0 تغلقه لحظة خروج المؤشر من عنصر الارتكاز والفجوة والتلميح. ويبقى التحويم على التلميح ممكنًا حتى عندئذ، لأن الفجوة تُحسب تحويمًا. ومهلة اللمس 0 تغلقه لحظة ارتفاع الإصبع، بعد أن يكون قد ظهر طوال الضغط المطوَّل.
تُستخدم كما كُتبت. القيمة التي تضبطها لا يغيّر مقاسها قرص ضبط الحركة (dial)، وتقليل الحركة يُبقيها: المهلة انتظار، لا حركة. القيمة السالبة أو غير الرقمية تأخذ قيمة النظام ويُبلَّغ عنها في بنيات التنقيح. وعلى الويب، خاصية HTML الفارغة ليست رقمًا هي الأخرى.
للتحويم واللمس فقط. تركيز لوحة المفاتيح يبقى يفتح التلميح فورًا، والتلميح الذي يُفتح وتلميح آخر معروض يبقى يتخطى مهلة إظهاره، وضبط open يبقى يعرضه أو يخفيه فورًا. والضغط المطوَّل نفسه يأخذ المدة الخاصة بالمنصة.
تغيير أثناء الانتظار. الانتظار الذي بدأ فعلًا ينتهي كما بدأ. وتسري القيمة الجديدة في المرة التالية.

اليوم لا يقبل هذه الخصائص إلا الويب و React. وحين تلحق المنصات الأخرى، تسمّيها المواصفة بأسلوب كل منصة: showDelayMillis و hideDelayMillis و touchTimeoutMillis على Compose، والخصائص waitDuration و exitDuration و showDuration التي للمكوّن Tooltip في Flutter، وأسماء المواصفة نفسها على SwiftUI و React Native.

تستخدم كل منصة عرضًا غير نمطي (non-modal): عنصر popover="manual" في الطبقة العليا (top layer) على الويب، وتراكب فوق النافذة على SwiftUI (لا .popover، فهو نمطي في العروض من الفئة المضغوطة (Compact))، وعنصر Popup لا يستطيع أخذ التركيز على Compose، وعنصر OverlayPortal على Flutter، وطبقة التراكب التابعة للمكوّن TanreiProvider على React Native (لا Modal، فهو يأخذ كل لمسة).

افعل

اجعل التلميحات من الطراز plain بضع كلمات، والتلميحات من الطراز rich بضع جمل.
أعطِ النوع نفسه من عناصر الارتكاز الموضع نفسه في الشاشة كلها، كأن يكون تحت كل أيقونة في شريط أدوات.
اترك inverse و arrow لنظام التصميم في معظم التلميحات، واضبطهما للتلميح الذي يحتاج إليهما.
اعرض مفاتيح الأمر بالخاصية shortcut، لا بكتابتها في النص.
أعطِ تلميحات المجموعة الواحدة من عناصر الارتكاز المهل نفسها، لتبقى على إيقاع واحد.
اضبط describes على false حين يعرض التلميح تسمية عنصر الارتكاز نفسها.

لا تفعل

لا تستخدم التلميح اسمًا لزر أيقونة. قيمة label في الزر هي اسمه.
لا تضع تلميحًا على عنصر ارتكاز معطَّل لتشرح لماذا هو معطَّل. عنصر التحكم المعطَّل لا يقبل التركيز وقد لا يستقبل أحداث المؤشر. ضع السبب في نص مرئي.
لا تضع روابط أو أزرارًا أو أي شيء تفاعلي آخر في تلميح.
لا تكرّر في التلميح ما يقوله عنصر الارتكاز أصلًا في نص مرئي.
لا تستخدم المظهر المعكوس أو السهم لتجعل التلميح يبدو أهم.

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

الدور: tooltip
التسمية: The tooltip names nothing. The anchor keeps its own accessible name and role; while describes is true the text (after the title, for a rich tooltip) is the anchor's description, available whether or not the tooltip is showing. An icon-only Button's label is its name (BTN-16) and is never replaced by a tooltip: a tooltip that shows the same words sets describes to false. A shortcut is the anchor's keyboard shortcut where the platform has that property, and the end of its description otherwise (TIP-27); the drawn keys and the arrow are hidden.
الحد الأدنى للهدف: تستوفي مساحة اللمس الحد الأدنى لحجم الهدف حتى لو كان الحجم المرئي أصغر. minimum 32px · pointer 44px · spacing 8px · touch 48px

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

المفاتيح	الإجراء
`Tab`	Moving focus to the anchor opens its tooltip at once; moving focus away closes it. The tooltip itself is never a tab stop.
`Escape`	Closes an open tooltip without moving focus, and goes no further (an enclosing dialog stays open).

ملاحظات

The tooltip takes no input, so it has no target of its own: minimumTarget applies to the anchor, which keeps its own hit area.
WCAG 1.4.13 (content on hover or focus): the tooltip can be dismissed without moving the pointer or focus (Escape, TIP-4), can be hovered (TIP-1: the gap between the anchor and the tooltip counts as hover — at any offset, with or without an arrow — so this holds at any hideDelay, 0 included), and stays until hover or focus ends or it is dismissed (TIP-5). Placement, the arrow and the motion change none of the three: a tooltip that flips, shifts or follows its anchor is the same open tooltip, and the gap is measured to wherever it stands.
A tooltip is invisible to touch users until they long-press, and to screen-reader users it is only a description. Nothing a person needs to finish a task may live only in a tooltip. A note that needs a link or a button is not a tooltip; that form belongs to a separate non-modal popover component.
Do not put a tooltip on a disabled anchor to explain why it is disabled: a disabled control cannot be focused, and on the web it may receive no pointer events. Put the reason in visible text.
Web: the description reaches the anchor's focusable element as aria-description, because aria-describedby cannot point across shadow roots. The anchor is the first focusable element slotted into the tooltip; a Tanrei component forwards aria-description from its host to the native element in its shadow root. The drawn tooltip has role tooltip and aria-hidden while describes carries the text.
The motion is short, small and never the only sign of anything; where motion is reduced nothing grows or travels (TIP-15). A tooltip that is leaving is already closed for input (TIP-29), so nothing invisible is ever in the pointer's way.
The inverse look and the surface look are two looks of one thing, not two meanings: neither says that a tooltip matters more. Choose by what the tooltip lands on.
A shortcut in a tooltip is a reminder for people who see it. It must also work for those who do not: the product binds the keys, and the anchor carries the shortcut for assistive technology (TIP-27).

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

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

ما دامت describes بالقيمة true، فالنص، بعد العنوان في التلميح من الطراز rich، هو وصف عنصر الارتكاز المتاح للتقنيات المساعدة، سواء أكان التلميح معروضًا أم لا. ويحتفظ عنصر الارتكاز باسمه ودوره. وما دامت describes بالقيمة false، لا يضيف التلميح شيئًا إلى عنصر الارتكاز.
يُمنع التلميح المرسوم من أن يُقرأ مرتين. ولا يأخذ التركيز أبدًا ولا يحمل شيئًا يقبل التركيز.
تركيز لوحة المفاتيح على عنصر الارتكاز يفتحه فورًا، وإبعاد التركيز يغلقه. والتلميح نفسه ليس موضع توقف للمفتاح Tab أبدًا.
المفتاح Escape يغلقه من دون أن ينقل التركيز، ولا يغلق معه مربع الحوار المحيط.
يستوفي معيار WCAG 1.4.13 (المحتوى عند التحويم أو التركيز): يمكن إغلاقه من دون تحريك المؤشر أو التركيز، ويمكن التحويم عليه مع أي مهلة إخفاء، ومنها 0، لأن الفجوة بين عنصر الارتكاز والتلميح تُحسب تحويمًا، ويبقى إلى أن ينتهي التحويم أو التركيز أو يُغلق.
يكبر مع النص الأكبر من دون أن يقصّه، ونصه محاذى إلى بداية اتجاه التخطيط.
الاختصار يُعرَض على أنه اختصار لوحة المفاتيح لعنصر الارتكاز (aria-keyshortcuts على الويب، على العنصر الذي يأخذ التركيز)، والمفاتيح المرسومة مخفيّة عن التقنيات المساعدة. وحيث يذكر عنصر الارتكاز اختصارًا خاصًّا به أصلًا، تُكتب مفاتيح التلميح بأسمائها في آخر الوصف بدلًا من ذلك، ما دامت describes بالقيمة true.
السهم زخرفة ومخفي عن التقنيات المساعدة. ويستخدم المظهران أزواجًا من ألوان النص والحاوية يفحص البناء تباينها في كل مخطط لوني.
حركته صغيرة: افتراضيًّا ظهور تدريجي وتكبّر طفيف. وحيث الحركة مقلَّلة يظهر ويختفي تدريجيًّا من دون أن يكبر أو ينتقل، إلا على Android، فإعداده يزيل كل حركة. أما المهل، ومهلة اللمس، والوقت الذي يُفتح فيه التلميح التالي فورًا، فانتظار لا حركة، وتبقى في كل مكان.
التلميح الذي نصه فارغ لا يُفتح أبدًا ولا يضيف شيئًا. تبلّغ عنه بنيات التنقيح (debug)، وعن العنوان المتجاهَل في التلميح من الطراز plain.

فجوات معروفة في المنصات:

لا تقبل SwiftUI و Compose و Flutter و React Native بعد showDelay ولا hideDelay ولا touchTimeout، ولا تحسب الفجوة تحويمًا: كل تلميح فيها يأخذ مهل النظام، ويعبر المؤشر الفجوة في حدود مهلة الإخفاء. وليس فيها كذلك إلا المواضع الأربعة الموسَّطة (top، bottom، start، end)، ولا offset ولا crossOffset ولا arrow ولا inverse ولا shortcut؛ وتلميحاتها تظهر وتختفي تدريجيًّا من دون أن تكبر أو تنتقل.
الويب: الضغط المطوَّل باللمس لا يفتح التلميح إلا حيث يبلّغ عنه المتصفح على أنه قائمة سياق (context menu). و iOS Safari لا يفعل، فلا يُفتح التلميح هناك باللمس.
الويب: عنوان التلميح الغني هو السمة headline. أما السمة title على <tanrei-tooltip> فهي للمتصفح، ويرسم لها تلميحه الأصلي: فلا تضعها.
ليس في SwiftUI دور تلميح. الوصف هو تلميح إمكانية الوصول (accessibility hint) لعنصر الارتكاز.
في SwiftUI على iOS: المفتاح Return أو Space على عنصر ارتكاز عليه التركيز لا يغلق التلميح، والمفتاح Escape لا يغلقه إلا ما دام التركيز على عنصر الارتكاز. وعنصر الارتكاز الذي يأخذ التركيز من لمسة، كحقل نص، يفتح تلميحه. وعنصر الارتكاز الذي جُعل شفافًا أو غُطّي لا يُكتشف أنه مخفي.
يرسم SwiftUI التلميحات في طبقة يوفّرها المُعدِّل .tanreiTheme(_:) ومربع حوار Tanrei. والمحتوى الذي يعرضه SwiftUI منفصلًا، كالمُعدِّل .sheet أو .popover من عندك، يحتاج إلى .tanreiTooltipLayer() لتظهر تلميحاته.
ليس في Compose خاصية وصف. يصير النص وصف الحالة (state description) لعنصر الارتكاز، ويُقرأ بعد اسمه ودوره. عنصر التحكم من Tanrei يضعه على عقدته هو؛ وأي عنصر ارتكاز آخر لا يوصَف إلا حين يلتقطه سلف يدمج فروعه. وعلى عنصر ارتكاز من نوع التبديل، كزر أيقونة تبديل، يحل محل On أو Off.
في Compose: التلميح الذي تعرضه من الشيفرة على عنصر ارتكاز خلف مربع حوار مفتوح يُرسم تحت نافذة مربع الحوار.
في Compose: ما دام التركيز في مكان آخر من النافذة وعنصر الارتكاز عليه التحويم فقط، لا يصل المفتاح Escape إلى التلميح إلا على Android 9 (API 28) وما بعده.
في Compose: التحويم بفأرة حقيقية، واللمس في الخارج، ومستمع Escape، وقراءة TalkBack وصف الحالة لعنصر الارتكاز مختبَرة على Robolectric فقط، لا على جهاز بعد.
في Flutter: التلميح المرسوم مستبعَد من الدلالات (semantics) دائمًا، لأن دور التلميح في Flutter لا يمكن استخدامه بعد. والوصف على عنصر الارتكاز لا يتأثر.
في Flutter: لا يُستهلَك المفتاح Escape إلا ما دام التركيز في عنصر الارتكاز، أو من مربع حوار Tanrei. والسلف الآخر الذي يعالج Escape، كمسار مربع حوار Material، يبقى يستقبله ما دام التركيز في مكان آخر.
في React Native: الوصف هو accessibilityHint لعنصر الارتكاز، بعد التلميح (hint) الخاص بعنصر الارتكاز نفسه.
في React Native: اللمسة في مكان آخر لا تغلق أبكر تلميحًا فُتح بضغط مطوَّل. ومهلة اللمس تبقى تغلقه.
في React Native: لا يتبع التلميح عنصر ارتكاز يُمرَّر، ولا يُغلق حين يُمرَّر عنصر الارتكاز إلى خارج النظر. ولا يبقى داخل المنطقة الآمنة إلا حين تمرّر هوامش النافذة (insets) إلى TanreiProvider.
في React Native: التحويم، وتحريك المؤشر إلى التلميح، والضغط المطوَّل، و Escape لم تُفحص بعد على جهاز.

ما عليك فعله

أعطِ عنصر الارتكاز اسمه الخاص المتاح للتقنيات المساعدة. التلميح لا يحل محله أبدًا.
اضبط describes على false حين يكرّر النص ذلك الاسم.
اربط بنفسك المفاتيح التي تعرضها بالخاصية shortcut، واعرض المفاتيح نفسها حيثما ظهر الأمر في مكان آخر، كما في قائمة خيارات.
اجعل عنصر الارتكاز قابلًا للتركيز، ليستطيع مستخدمو لوحة المفاتيح فتح التلميح.
إن قصّرت مهلة اللمس فتأكد أن النص ما زال يمكن قراءته في الوقت الباقي. المهلة 0 تعرض التلميح فقط ما دام الإصبع على الشاشة.
أبقِ كل ما يحتاج إليه الشخص خارج التلميح. مستخدمو اللمس وقارئات الشاشة قد لا يرونه أبدًا.
على React Native، ضع TanreiProvider في جذر تطبيقك، مع قيمة insets للنافذة: طبقة التراكب فيه ترسم التلميح داخل المنطقة الآمنة. على SwiftUI، طبّق .tanreiTheme(_:) فوق عنصر الارتكاز، وطبّق .tanreiTooltipLayer() على محتوى ما تعرضه أنت بالمُعدِّل .sheet أو .popover. على Flutter، يحتاج التلميح إلى Overlay فوقه، وهو موجود في كل WidgetsApp له Navigator.

الشيفرة المصدرية والمشكلات على GitHub