مرجع الـ API

كل option و theme key و method و export في الـ package، مع الـ type والقيمة الـ default بتاعة كل واحد.

في الصفحة دي

الـ Options

بتتمرّر لـ init(options)، أو كـ props لـ AccessibilityWidget، أو بعدين لـ widget.setOptions(options).

الـ Options
الاسم	الـ type	الـ default	الوصف
`position`	`"left" \| "right"`	`"left"`	ناحية الشاشة اللي فيها زرار الفتح واللوحة.
`offset`	`{ x?: number; y?: number }`	`{ x: 24, y: 24 }`	المسافة من أطراف الشاشة، بالـ px (0–1000).
`theme`	`AccessibilityTheme`		الألوان والـ radius والخط: شوف «الـ Theme» تحت.
`colorScheme`	`"auto" \| "light" \| "dark"`	`"auto"`	لوحة فاتحة أو غامقة. ‎"auto"‎ بتمشي ورا الصفحة: بتبقى غامقة طول ما خلفية الموقع نفسه غامقة، مهما كانت طريقة الموقع في تبديل الـ theme. ألوان اللوحة اللي بتحددها في theme بتقفل ‎"auto"‎.
`icon`	`string \| Element`	`built-in icon`	لوجو زرار الفتح: URL لصورة أو DOM element. ماتمرّرش غير elements موثوقة: لأنها بتتنسخ زي ما هي.
`logo`	`string \| Element \| null`	`hidden`	لوجو جنب عنوان اللوحة.
`buttonSize`	`number`	`56`	قطر زرار الفتح، بالـ px (24–160).
`features`	`Partial<Record<FeatureKey, boolean>>`	`all on`	خلّي أي control بـ `false` عشان تشيله. الإعداد اللي اتشال بيفضل مقفول.
`initialSettings`	`Partial<AccessibilitySettings>`		إعدادات للزوار اللي مش حافظين أي حاجة.
`languages`	`AccessibilityLanguage[] \| false`	`English + Arabic`	عناصر قائمة اللغات، أو `false` عشان تخفي القائمة.
`language`	`string`	`saved → <html lang> → first`	كود لغة البداية.
`labels`	`Partial<AccessibilityLabels>`		غيّر نصوص معينة فوق اللغة الشغالة.
`dir`	`"ltr" \| "rtl"`	`language's direction`	اجبر اتجاه النص بتاع الـ widget.
`shortcut`	`string \| false`	`"Alt+A"`	shortcut بيفتح اللوحة ويقفلها، وبيرجّع الـ widget بعد «إخفاء الأداة». مع `false`، زرار الإخفاء بيتشال.
`statementUrl`	`string`		لينك الـ accessibility statement بتاعك في الـ footer بتاع اللوحة (http أو https أو relative).
`feedbackUrl`	`string`		المكان اللي الزوار يبلّغوا فيه عن مشكلة accessibility (صفحة أو form أو `mailto:`)، وبيظهر في الـ footer بتاع اللوحة.
`showSkipLink`	`boolean`	`true`	لينك «تخطَّ إلى المحتوى الرئيسي». مش بيتضاف لو الصفحة مفيهاش `main` أو `h1`، أو لو بتبدأ أصلًا بـ skip link خاص بيها.
`zIndex`	`number`	`2147483000`	ترتيب طبقة الـ widget (stacking order).
`persist`	`boolean`	`true`	احفظ الإعدادات في الـ localStorage، وخلّيها متزامنة بين الـ tabs.
`storageKey`	`string`	`"a11yw-settings"`	الـ key بتاع الـ localStorage.
`nonce`	`string`		الـ CSP nonce للـ `style` tags اللي بتتضاف.
`onChange`	`(settings) => void`		بيتنادى لما الزائر يغيّر أي حاجة.

الـ Theme

الـ keys بتاعة الـ option theme. الألوان بتقبل أي لون CSS، بس فحص التباين بيشمل الألوان الـ hex بس.

الـ Theme
الاسم	الـ type	الوصف
`primary`	`string`	لون البراند: زرار الفتح والـ header والـ active states.
`onPrimary`	`string`	لون النص والأيقونات فوق الـ primary.
`background`	`string`	خلفية اللوحة.
`surface`	`string`	الـ footer والـ segmented controls والـ hover states.
`text, mutedText`	`string`	النص والنص الثانوي.
`border`	`string`	الـ borders.
`radius`	`number \| string`	انحناء الزوايا: رقم بالـ px أو أي CSS length.
`fontFamily`	`string`	الـ font stack بتاع اللوحة.

الـ instance methods

init() بترجّع الـ widget. ونسخة الـ script tag بتعرض نفس الـ exports على window.A11yWidget.

TypeScript

import { init } from "open-accessibility-widget";

const widget = init();

widget.open(); widget.close(); widget.toggle();
widget.getSettings();                                  // a frozen snapshot
widget.setSettings({ fontSize: 120 });                 // validated: bad values are dropped
widget.setSettings((s) => ({ fontSize: s.fontSize + 10 }));
widget.toggleProfile("visionImpaired");
widget.reset();
widget.setOptions({ theme: { primary: "#000000" }, language: "ar" });
const unsubscribe = widget.subscribe(({ settings, isOpen }) => {});
widget.destroy();                                      // removes the widget and undoes every change

الـ instance methods
الاسم	الـ type	الوصف
`open(), close(), toggle()`	`void`	افتح اللوحة أو اقفلها أو اعملها toggle.
`getSettings()`	`AccessibilitySettings`	الإعدادات الحالية، كـ snapshot متجمّدة (frozen).
`getState()`	`AccessibilityState`	الإعدادات، واللوحة مفتوحة ولا لأ.
`setSettings(update)`	`void`	دمج التغييرات: object، أو function بتاخد الإعدادات اللي قبلها. المدخلات بتتعملها validation والقيم الغلط بتتشال. لو حطيت `profiles` هتتطبق التعديلات بتاعتها كمان.
`toggleProfile(id)`	`void`	شغّل profile أو اقفله.
`reset()`	`void`	رجّع كل تعديل والصفحة ترجع زي ما إنت عاملها.
`setOptions(options)`	`void`	غيّر الـ options بتاعة الشكل والسلوك وهو شغال (at runtime).
`subscribe(listener)`	`() => void`	اسمع لتغييرات الإعدادات وحالة الفتح. بترجّع function بتوقف الاستماع.
`destroy()`	`void`	شيل الـ widget وارجع في كل تغيير عمله في الصفحة.

React

من open-accessibility-widget/react، اللي بيعمل re-export لكل الباقي كمان. الـ entry دي متعلّم عليها "use client".

React
الاسم	الـ type	الوصف
`<AccessibilityWidget {...options} />`	`null`	بيركّب الـ widget بالـ options دي. تغيير الـ props بينادي `setOptions()`، والـ unmount بيشيل الـ widget. هو نفسه مش بيعمل render لأي حاجة.
`useAccessibility()`	`{ settings, isOpen, widget }`	اقرا الـ widget واتحكم فيه من أي component. `widget` بتبقى `null` لحد ما يتركّب.

الـ Exports

الـ named exports بتاعة الـ package.

الـ Exports
الاسم	الـ type	الوصف
`init(options), createAccessibilityWidget(options)`	`AccessibilityWidgetInstance`	بيركّب الـ widget على `body` ويرجّعه. لو ناديته تاني بيبدّل الـ widget الموجود.
`getAccessibilityWidget()`	`AccessibilityWidgetInstance \| null`	الـ widget اللي شغال دلوقتي، لو فيه.
`onActiveWidgetChange(listener)`	`() => void`	اسمع لما widget يتعمل أو يتشال. بترجّع function بتوقف الاستماع.
`DEFAULT_SETTINGS`	`Readonly<AccessibilitySettings>`	كل الإعدادات بالقيم الـ default بتاعتها.
`RANGES`	`Record<RangeKey, { min, max, step }>`	الـ minimum والـ maximum والـ step لكل إعداد بالنسبة المئوية.
`PROFILE_IDS, PROFILE_PRESETS`	`ProfileId[], Record<ProfileId, ProfilePreset>`	الـ ids بتاعة الـ profiles، والتعديلات اللي كل profile بيشغّلها.
`sanitizeSettings(input)`	`AccessibilitySettings`	اعمل validation لمدخلات مش موثوقة وحوّلها لإعدادات كاملة.
`builtInLanguages`	`AccessibilityLanguage[]`	الإنجليزي والعربي، عشان تزوّد عليهم لغاتك.
`defaultLabels, arabicLabels`	`AccessibilityLabels`	النصوص الإنجليزي والعربي.

الإعدادات

اللي getSettings() بترجّعه، واللي setSettings() وinitialSettings بيقبلوه. في النسب المئوية، 100 معناها «من غير تغيير»؛ والقيم اللي برّه الـ range بتتقصّ عند الحد، والقيم المش معروفة بتتشال.

الإعدادات
الاسم	الـ type	الـ default	الوصف
`profiles`	`ProfileId[]`	`[]`	الـ profiles الشغالة، بالترتيب اللي اتشغلت بيه.
`contentScale`	`number (50–200)`	`100`	تكبير الصفحة (zoom)، بالنسبة المئوية.
`fontSize`	`number (50–200)`	`100`	حجم النص، بالنسبة المئوية.
`lineHeight`	`number (100–200)`	`100`	المسافة بين السطور، بالنسبة المئوية.
`letterSpacing`	`number (100–200)`	`100`	المسافة بين الحروف، بالنسبة المئوية (مش بتتطبق على العربي).
`textAlign`	`"default" \| "left" \| "center" \| "right" \| "justify"`	`"default"`	محاذاة النص.
`readableFont`	`boolean`	`false`	خط بسيط وسهل في القراية.
`boldText`	`boolean`	`false`	كل نص الصفحة يبقى bold.
`highlightTitles, highlightLinks`	`boolean`	`false`	إطار حوالين العناوين / اللينكات.
`textMagnifier`	`boolean`	`false`	بيعرض النص اللي تحت المؤشر أو الـ focus مكبّر (والـ alt text بتاع الصور).
`readAloud`	`boolean`	`false`	الضغط أو اللمس أو الـ focus بالكيبورد بيقرا الجزء ده بصوت عالي بالـ speech بتاع المتصفح نفسه، بلغة الصفحة. Escape بيوقفه.
`colorMode`	`"default" \| "dark-contrast" \| "light-contrast" \| "high-contrast"`	`"default"`	وضع التباين.
`saturationMode`	`"default" \| "monochrome" \| "low-saturation" \| "high-saturation"`	`"default"`	فلتر التشبع.
`invertColors`	`boolean`	`false`	بيعكس ألوان الصفحة؛ والصور والفيديو بيفضلوا بألوانهم.
`textColor, titleColor, backgroundColor`	`"#rrggbb" \| null`	`null`	ألوان مخصصة للنص والعناوين والخلفية.
`muteSounds, hideImages, stopAnimations`	`boolean`	`false`	كتم الميديا، وإخفاء الصور، وإيقاف الـ CSS animations.
`readingGuide, readingMask`	`boolean`	`false`	خط القراءة ونافذة التركيز.
`highlightFocus, highlightHover`	`boolean`	`false`	إطار واضح عند الـ focus بالكيبورد / عند الـ hover.
`cursor`	`"default" \| "black" \| "white"`	`"default"`	مؤشر كبير.

محتوى الـ package

كل entry جاية بـ ESM و CommonJS ومعاها الـ type declarations. من غير runtime dependencies.

محتوى الـ package
الاسم	الـ type	الوصف
`open-accessibility-widget`	`ESM + CJS + .d.ts`	أي framework، أو JavaScript عادي مع bundler.
`open-accessibility-widget/react`	`ESM + CJS + .d.ts`	React component و hook؛ و`react` 18 أو أحدث peer dependency اختيارية.
`open-accessibility-widget/languages`	`ESM + CJS + .d.ts`	لغات إضافية اختيارية (14)، tree-shakable، حوالي 1 KB gzipped لكل لغة.
`dist/open-accessibility-widget.global.js`	`IIFE`	نسخة الـ script tag، حوالي 27 KB gzipped؛ بتعرض `window.A11yWidget`.
`dist/open-accessibility-widget.languages.global.js`	`IIFE`	باكدج اللغات لنسخة الـ script tag، حوالي 17 KB gzipped؛ بتعرض `window.A11yWidgetLanguages`.

عدّل الصفحة دي على GitHub