# منتقي الألوان

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

الصفحة: https://ritla.app/ar/ui/color-picker

## التثبيت

يُفتح التثبيت من السجل قريبًا، وهذه هي الأوامر التي ستشغّلها حينها.

```bash
npx ritla add color-picker
```

أو بأداة shadcn:

```bash
npx shadcn@latest add @ritla/color-picker
```

الاعتماديات: `@base-ui/react`، `@phosphor-icons/react`

## الاستخدام

```tsx
import { ColorPicker } from "@/components/ui/color-picker";

const [color, setColor] = useState("#4F46E5");

<ColorPicker aria-label="Brand color" value={color} onValueChange={setColor} />
```

## أمثلة

### في نافذة منبثقة، مع فحص التباين

الحقل يعرض اللون ورمزه ويفتح المنتقي في `Popover`. `contrastWith` يقيس تباين النص الأبيض على اللون المختار، فيحذّر تحت 4.5:1 (`contrastTarget={3}` للأيقونات والحدود) ويقترح أقرب درجة تنجح، دون أن يمنع الاختيار. `showAlpha={false}` لألوان معتمة دائمًا.

معاينة حيّة: https://ritla.app/_kanz/preview/arabic/color-picker-popover

## مرجع الخصائص

### `ColorPicker`

| الخاصية | النوع | الافتراضي | الوصف |
| --- | --- | --- | --- |
| `value / onValueChange` | `string / (value: string) => void` | لا يوجد | اللون: `#RRGGBB`، أو `#RRGGBBAA` حين لا يكون معتمًا تمامًا. |
| `swatches` | `{ value, name? }[]` | لا يوجد | الألوان المحفوظة: صف قصير، الأحدث أولًا. `name` يُقرأ مع الرمز («نيلي العلامة، #4F46E5»). دونها لا يظهر الصف. |
| `onAddSwatch` | `(value: string) => void` | لا يوجد | رابط «إضافة»: يحفظ اللون الحالي. |
| `showAlpha` | `boolean` | `true` | شريط التعتيم وحقله. |
| `contrastWith / contrastTarget` | `string / number` | `contrastTarget: 4.5` | اللون الذي سيجاور المختار (النص عليه). تحت الهدف يظهر تحذير مع أقرب درجة تنجح. |
| `aria-label` | `string` | لا يوجد | اسم المنتقي («لون العلامة»). |

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

لوحة المفاتيح (المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين، ويتبادل السهمان في الاتجاه من اليمين إلى اليسار):

- `Tab`: مساحة الألوان، ثم درجة اللون، ثم التعتيم، ثم الحقول، ثم العيّنات.
- `ArrowLeft` + `ArrowRight`: في مساحة الألوان: التشبّع؛ في الشريطين: القيمة. اليمين يزيد في اللغتين لأن الشريطين من اليسار إلى اليمين.
- `ArrowUp` + `ArrowDown`: في مساحة الألوان: السطوع؛ مع Shift بخطوات 10%.
- `PageUp` + `PageDown` + `Home` + `End`: في الشريطين: عُشر المدى، والطرفان.
- `Enter`: في حقل HEX يطبّق القيمة.

ARIA:

- مساحة الألوان والشريطان `role="slider"` بقيمها بالكلمات («التشبّع 70%، السطوع 90%»).
- العيّنات مجموعة أزرار اختيار، كل عيّنة باسمها ورمزها، والمختارة بحلقة ظاهرة لا باللون وحده.
- حقل HEX الطريق الدقيق بلوحة المفاتيح: يقبل الرمز مع # أو دونها، بأحرف كبيرة أو صغيرة، والصيغة القصيرة.

## ملاحظات العربية والاتجاه

ينعكس:

- صف الحقول (تنسيق HEX، ثم الرمز، ثم التعتيم) وصف «الألوان المحفوظة» و«إضافة» والعيّنات.

لا ينعكس:

- مساحة الألوان وشريطا درجة اللون والتعتيم: مقياس ألوان ثابت، يبدأ الأحمر من اليسار في اللغتين.
- رمز HEX يبقى من اليسار إلى اليمين بأحرف لاتينية وأرقام غربية.

الأرقام: النسب (التعتيم، التشبّع، السطوع، التباين) تتبع `numerals`؛ رمز HEX لا يتبعها أبدًا.

الخط العربي: الحقول `label-14` بوزن Medium وعنوان العيّنات `label-12`؛ لا ارتفاعات ثابتة على النص العربي.