تلميح (Tooltip)

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

التثبيت

bash

npx @smicolon/fasla-ui@latest add tooltip

قبل إضافة أي مكوّن، شغّل الأمر init مرة واحدة في مشروعك. التفاصيل في صفحة التثبيت.

مكوّن تلميح مبني على مكتبة Base UI، لذلك يحتاج إلى الحزمة @base-ui/react، ويستخدم مكوّن صورة رمزية في موضع الصورة. يثبّت الأمر add كليهما مع المكوّن، وكذلك أداة shadcn.

معاينة

مرّر مؤشر الفأرة فوق الزر، أو انتقل إليه بمفتاح Tab.

الأنماط (variant)

يأتي التلميح بستة أنماط تختار منها بالخاصية variant. النمط primary هو الافتراضي، وهو مناسب للتسميات اليومية. والنمط secondary لون محايد أهدأ. أما الأنماط info، success، warning، destructive فتحمل ألوان الحالات، فاختر منها ما يوافق معنى الرسالة، واجعل كلماتها واضحة وحدها. وتختار الخاصية radius بين زوايا مستديرة بنصف قطر 8px في القيمة standard، ونصف قطر 16px في القيمة rounded، فيبدو التلميح ذو السطر الواحد على شكل كبسولة.

primary

secondary

info

success

warning

destructive

primary · rounded

secondary · rounded

info · rounded

success · rounded

warning · rounded

destructive · rounded

الموضع

تحدد الخاصية side الجهة التي يظهر فيها التلميح من العنصر المُشغِّل، ويشير السهم إليه. القيم top، bottom، left، right جهات ثابتة على الشاشة، فتبقى القيمة left في مكانها حتى في الصفحات من اليمين إلى اليسار. أما القيمة inline-start فتعني بداية السطر، والقيمة inline-end تعني نهايته، فتتبادلان الجهتين في الصفحات العربية. وإذا لم يجد التلميح مساحة كافية، انتقل إلى الجهة المقابلة. ولإخفاء السهم، اجعل قيمة الخاصية arrow هي false.

top

bottom

left

right

inline-start

inline-end

arrow={false}

المحتوى

النص الذي تضعه داخل المكوّن هو العنوان. تضيف الخاصية description سطرًا ثانيًا أقل بروزًا. وتضع الخاصية icon أيقونة بحجم 16px قبل النص وبلونه، وتضع الخاصية avatar في الموضع نفسه مكوّن صورة رمزية دائريًا بحجم 12px، لتُظهر الشخص الذي يخصّه التلميح. يلتف النص عند 296px، فلا يزيد عرض التلميح على 320px، أو 340px مع أيقونة.

description

icon

avatar

296px

إتاحة الوصول (accessibility)

التلميح إشارة مرئية فقط، فلا تضيف إليه مكتبة Base UI السمة role، ولا تربطه بالعنصر المُشغِّل. امنح العنصر المُشغِّل اسمًا خاصًا به، نصًا ظاهرًا أو السمة aria-label، واترك المعلومات الضرورية خارج التلميح.
يظهر التلميح فور استقرار مؤشر الفأرة على العنصر المُشغِّل أو وصول التركيز إليه، ويختفي حين يغادره أحدهما أو حين تضغط مفتاح Escape.
أبقِ الروابط والأزرار خارج التلميح، فهو يختفي حين ينتقل التركيز، ولن يصل إليها أحد.
تضيف أنماط الحالات لونًا، لكنها لا تضيف معنى. اذكر نوع الرسالة في كلماتها، أو أضف أيقونة تدل عليه.
يأخذ التلميح اتجاه الصفحة ولغتها وخطها من العنصر المُشغِّل، مع أنه يُعرض في نهاية العنصر body. ولا يحتاج الاتجاه إلى خاصية.

الخصائص (props)

`Tooltip`

الخاصية	النوع	الافتراضي	الوصف
`open`	`boolean`	لا يوجد	يُظهر التلميح أو يخفيه عند التحكّم بالقيمة.
`defaultOpen`	`boolean`	`false`	يُظهر التلميح في البداية.
`onOpenChange`	`(open, eventDetails) => void`	لا يوجد	تُستدعى عند ظهور التلميح أو اختفائه.
`disabled`	`boolean`	`false`	يمنع ظهور التلميح.

`TooltipTrigger`

الخاصية	النوع	الافتراضي	الوصف
`render`	`ReactElement`	لا يوجد	يعرض عنصرك مكان الزر الافتراضي، مثل رابط أو مكوّن زر.
`delay`	`number`	`0`	مدة الانتظار قبل ظهور التلميح، بالمللي ثانية.

`TooltipContent`

الخاصية	النوع	الافتراضي	الوصف
`variant`	`"primary" \| "secondary" \| "info" \| "success" \| "warning" \| "destructive"`	`"primary"`	لون التلميح.
`radius`	`"standard" \| "rounded"`	`"standard"`	زوايا بنصف قطر 8px، أو 16px فيبدو التلميح ذو السطر الواحد كبسولة.
`side`	`"top" \| "bottom" \| "left" \| "right" \| "inline-start" \| "inline-end"`	`"top"`	الجهة التي يظهر فيها من العنصر المُشغِّل. تتبع قيم `inline-*` اتجاه القراءة.
`align`	`"start" \| "center" \| "end"`	`"center"`	موضع التلميح على طول تلك الجهة.
`sideOffset`	`number`	`8`	المسافة من العنصر المُشغِّل إلى التلميح، بالبكسل.
`arrow`	`boolean`	`true`	يُظهر السهم.
`description`	`ReactNode`	لا يوجد	سطر ثانٍ تحت العنوان.
`icon`	`ReactNode`	لا يوجد	أيقونة بحجم 16px قبل النص.
`avatar`	`Omit<AvatarProps, "size">`	لا يوجد	خصائص مكوّن صورة رمزية يظهر قبل النص، بحجم 12px دائمًا.
`container`	`HTMLElement`	لا يوجد	العنصر الذي يُعرض فيه التلميح، والقيمة الافتراضية هي `body`.
`className`	`string`	لا يوجد	أصناف CSS إضافية للتلميح.

الاستخدام

تلميح بسيط

tsx

import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

export function ShareTooltip() {
  return (
    <Tooltip>
      <TooltipTrigger>مشاركة</TooltipTrigger>
      <TooltipContent>نسخ الرابط</TooltipContent>
    </Tooltip>
  )
}

تسمية زر أيقونة

tsx

import { Link } from "lucide-react"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

export function CopyLinkButton() {
  return (
    <Tooltip>
      <TooltipTrigger aria-label="نسخ الرابط">
        <Link aria-hidden="true" />
      </TooltipTrigger>
      <TooltipContent>نسخ الرابط</TooltipContent>
    </Tooltip>
  )
}

النمط والوصف والأيقونة

tsx

import { Info } from "lucide-react"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

export function ShareInfoTooltip() {
  return (
    <Tooltip>
      <TooltipTrigger>مشاركة</TooltipTrigger>
      <TooltipContent
        variant="info"
        side="bottom"
        icon={<Info />}
        description="يستطيع أي شخص لديه الرابط عرض هذا الملف."
      >
        نسخ الرابط
      </TooltipContent>
    </Tooltip>
  )
}

مع صورة رمزية

tsx

import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

export function LastEditedTooltip() {
  return (
    <Tooltip>
      <TooltipTrigger>مشاركة</TooltipTrigger>
      <TooltipContent
        variant="secondary"
        avatar={{ src: "/avatars/layla.png", name: "" }}
        description="عُدِّل قبل 5 دقائق"
      >
        ليلى حداد
      </TooltipContent>
    </Tooltip>
  )
}

في نهاية السطر

tsx

import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

export function EndSideTooltip() {
  return (
    <Tooltip>
      <TooltipTrigger>مشاركة</TooltipTrigger>
      <TooltipContent side="inline-end">نسخ الرابط</TooltipContent>
    </Tooltip>
  )
}