snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/ar/developers/contribute/capabilities/frontend-development/best-practices-front.mdx

@@ -0,0 +1,329 @@
+---
+title: أفضل الممارسات
+icon: star
+---
+
+تحدد هذه الوثيقة أفضل الممارسات التي يجب اتباعها عند العمل في الواجهة الأمامية.
+
+## إدارة الحالة
+
+تقوم React و Jotai بإدارة الحالة في قاعدة الشيفرة.
+
+### استخدم ذرات Jotai لتخزين الحالة
+
+من الجيد إنشاء أكبر عدد ممكن من الذرات لتخزين الحالة الخاصة بك.
+
+<Warning>
+
+من الأفضل استخدام ذرات إضافية بدلاً من محاولة أن تكون مقتضبًا باستخدام تمرير الخصائص.
+
+</Warning>
+
+```tsx
+import { createAtomState } from '@/ui/utilities/state/jotai/utils/createAtomState';
+import { useAtomState } from '@/ui/utilities/state/jotai/hooks/useAtomState';
+
+export const myAtomState = createAtomState<string>({
+  key: 'myAtomState',
+  defaultValue: 'default value',
+});
+
+export const MyComponent = () => {
+  const [myAtom, setMyAtom] = useAtomState(myAtomState);
+
+  return (
+    <div>
+      <input
+        value={myAtom}
+        onChange={(e) => setMyAtom(e.target.value)}
+      />
+    </div>
+  );
+}
+```
+
+### لا تستخدم `useRef` لتخزين الحالة
+
+تجنب استخدام `useRef` لتخزين الحالة.
+
+إذا كنت ترغب في تخزين الحالة، يجب أن تستخدم `useState` أو ذرات Jotai مع `useAtomState`.
+
+انظر [كيفية إدارة إعادة العرض](#managing-re-renders) إذا شعرت أنك بحاجة إلى `useRef` لمنع بعض إعادة العرض من الحدوث.
+
+## إدارة إعادة العرض
+
+يمكن أن تكون إعادة العرض صعبة الإدارة في React.
+
+إليك بعض القواعد التي يجب اتباعها لتجنب إعادة العرض غير الضرورية.
+
+تذكر أنه يمكنك **دائمًا** تجنب إعادة العرض من خلال فهم سببها.
+
+### العمل على المستوى الجذري
+
+تجنب إعادة العرض في الميزات الجديدة أصبح سهلاً الآن عن طريق إزالتها على المستوى الجذري.
+
+يحتوي المكون الجانبي "PageChangeEffect" على "useEffect" واحد فقط يحمل كل المنطق لتنفيذه على تغيير الصفحة.
+
+بهذه الطريقة، تعرف أن هناك مكان واحد فقط يمكنه تحفيز إعادة العرض.
+
+### تفكير دائماً مرتين قبل إضافة `useEffect` في الرمز الخاص بك
+
+وكثيرا ما تكون عمليات إعادة التسليم ناجمة عن `فعالية الاستخدام` غير الضرورية.
+
+يجب أن تفكر فيما إذا كنت بحاجة إلى \`useEffect'، أو إذا كنت تستطيع نقل المنطق في وظيفة معالج الأحداث.
+
+ستجد أنه من السهل عموما نقل المنطق في دالة "handleClick" أو "handleChange".
+
+يمكنك أيضًا العثور عليها في المكتبات مثل Apollo: `onCompleted`، `onError`، إلخ.
+
+### استخدم مكون أخت لاستخراج \`تأثير الاستخدام' أو منطق جلب البيانات
+
+إذا كنت تشعر أنك بحاجة إلى إضافة 'useEffect' في مكون الجذر الخاص بك، فيجب عليك النظر في استخراجه في مكون جانبي.
+
+يمكنك تطبيق نفس الشيء على منطق جلب البيانات، مع الخُطافات Apollo.
+
+```tsx
+// ❌ Bad, will cause re-renders even if data is not changing,
+//    because useEffect needs to be re-evaluated
+export const PageComponent = () => {
+  const [data, setData] = useAtomState(dataState);
+  const [someDependency] = useAtomState(someDependencyState);
+
+  useEffect(() => {
+    if(someDependency !== data) {
+      setData(someDependency);
+    }
+  }, [someDependency]);
+
+  return <div>{data}</div>;
+};
+
+export const App = () => (
+  <PageComponent />
+);
+```
+
+```tsx
+// ✅ Good, will not cause re-renders if data is not changing,
+//   because useEffect is re-evaluated in another sibling component
+export const PageComponent = () => {
+  const [data, setData] = useAtomState(dataState);
+
+  return <div>{data}</div>;
+};
+
+export const PageData = () => {
+  const [data, setData] = useAtomState(dataState);
+  const [someDependency] = useAtomState(someDependencyState);
+
+  useEffect(() => {
+    if(someDependency !== data) {
+      setData(someDependency);
+    }
+  }, [someDependency]);
+
+  return <></>;
+};
+
+export const App = () => (
+  <>
+    <PageData />
+    <PageComponent />
+  </>
+);
+```
+
+### استخدم حالات عائلة الذرات والمحددات
+
+تُعد حالات عائلة الذرات والمحددات طريقة رائعة لتجنّب عمليات إعادة التصيير.
+
+إنها مفيدة عندما تحتاج إلى تخزين قائمة من العناصر.
+
+### يجب ألا تستخدم `React.memo(MyComponent)`
+
+تجنب استخدام `React.memo()` لأنه لا يحل سبب إعادة العرض، بل يكسر سلسلة إعادة العرض، مما قد يؤدي إلى سلوك غير متوقع ويجعل التعليمات البرمجية صعبة التعديل.
+
+### حدد استخدام `useCallback` أو `useMemo`
+
+غالبًا ما لا تكون ضرورية وستجعل التعليمات البرمجية أصعب في القراءة والصيانة لأداء غير ملحوظ.
+
+## Console.logs
+
+تصريحات `console.log` ذات قيمة أثناء التطوير، حيث تقدم رؤى في الوقت الفعلي عن قيمة المتغيرات وتدفق التعليمات البرمجية. ولكن، تركها في التعليمات البرمجية في الإنتاج قد يؤدي إلى عدة مشكلات:
+
+1. **الأداء**: تسجيل كثير قد يؤثر على أداء وقت التشغيل، خاصة في التطبيقات على الجانب العميل.
+
+2. **الأمان**: تسجيل البيانات الحساسة قد يكشف المعلومات الحرجة لأي شخص يقوم بتفتيش وحدة التحكم في المتصفح.
+
+3. **النظافة**: ملء وحدة التحكم بالسجلات قد يحجب التحذيرات أو الأخطاء الهامة التي يحتاج المطورون أو الأدوات إلى رؤيتها.
+
+4. **الاحترافية**: المستخدمون النهائيون أو العملاء الذين يفحصون وحدة التحكم ويجدون الكثير من تصريحات السجلات قد يشككون في جودة وتأنق التعليمات البرمجية.
+
+تأكد من إزالة جميع تصريحات `console.log` قبل دفع التعليمات البرمجية إلى الإنتاج.
+
+## التسمية
+
+### تسمية المتغيرات
+
+يجب أن تعبر أسماء المتغيرات بدقة عن الغرض أو وظيفة المتغير.
+
+#### المشكلة مع الأسماء العامة
+
+الأسماء العامة في البرمجة ليست مثالية لأنها تفتقر إلى التحديد، مما يؤدي إلى الغموض وتقليل قابلية قراءة التعليمات البرمجية. مثل هذه الأسماء تفشل في التعبير عن الغرض من المتغير أو الوظيفة، مما يجعل من الصعب على المطورين فهم نية التعليمات البرمجية دون تحقيق أعمق. يمكن أن يؤدي ذلك إلى زيادة وقت إزالة الأخطاء، وزيادة قابلية التعرض للأخطاء، وصعوبات في الصيانة والتعاون. في الوقت نفسه، تجعل التسمية الوصفية التعليمات البرمجية تفسيرية بذاتها وأسهل في التنقل، مما يعزز جودة التعليمات البرمجية وإنتاجية المطور.
+
+```tsx
+// ❌ Bad, uses a generic name that doesn't communicate its
+//    purpose or content clearly
+const [value, setValue] = useState('');
+```
+
+```tsx
+// ✅ Good, uses a descriptive name
+const [email, setEmail] = useState('');
+```
+
+#### بعض الكلمات يجب تجنبها في أسماء المتغيرات
+
+* dummy
+
+### معالجات الأحداث
+
+يجب أن تبدأ أسماء معالجات الأحداث بكلمة `handle`، بينما يعتبر `on` بادئة تستخدم لتسمية الأحداث في خصائص المكونات.
+
+```tsx
+// ❌ Bad
+const onEmailChange = (val: string) => {
+  // ...
+};
+```
+
+```tsx
+// ✅ Good
+const handleEmailChange = (val: string) => {
+  // ...
+};
+```
+
+## الخصائص الاختيارية
+
+تجنب تمرير القيمة الافتراضية لخاصية اختيارية.
+
+**مثال**
+
+خذ مكون`EmailField` المحدد أدناه:
+
+```tsx
+type EmailFieldProps = {
+  value: string;
+  disabled?: boolean;
+};
+
+const EmailField = ({ value, disabled = false }: EmailFieldProps) => (
+  <TextInput value={value} disabled={disabled} fullWidth />
+);
+```
+
+**الاستخدام**
+
+```tsx
+// ❌ Bad, passing in the same value as the default value adds no value
+const Form = () => <EmailField value="username@email.com" disabled={false} />;
+```
+
+```tsx
+// ✅ Good, assumes the default value
+const Form = () => <EmailField value="username@email.com" />;
+```
+
+## المكون كخصائص
+
+حاول قدر الإمكان تمرير المكونات غير المنشأة كمكونات، بحيث يمكن للأطفال تحديد ما يحتاجون لتمريره.
+
+المثال الأكثر شيوعا لذلك هو مكونات الأيقونات:
+
+```tsx
+const SomeParentComponent = () => <MyComponent Icon={MyIcon} />;
+
+// In MyComponent
+const MyComponent = ({ MyIcon }: { MyIcon: IconComponent }) => {
+  const theme = useTheme();
+
+  return (
+    <div>
+      <MyIcon size={theme.icon.size.md}>
+    </div>
+  )
+};
+```
+
+لفهم React أن المكون هو مكون، يجب عليك استخدام PascalCase، للتمكن من معاملته لاحقًا كـ `<MyIcon>`
+
+## تمرير الخصائص: اجعلها محدودة
+
+يشير تمرير الخصائص في سياق React إلى ممارسة تمرير متغيرات الحالة وأدوات تحكمها عبر العديد من طبقات المكونات، حتى لو لم تستخدمها المكونات الوسيطة. رغم أنها تكون ضرورية في بعض الأحيان، إلا أن تمرير الخصائص الزائد يمكن أن يؤدي إلى:
+
+1. **انخفاض القابلية للقراءة**: يمكن أن يصبح تتبع مصدر الخاصية أو مكان استخدامها معقدا في هيكل مكون معقد.
+
+2. **تحديات الصيانة**: قد تتطلب التغييرات في هيكل خاصية أحد المكونات تعديلات في عدة مكونات، حتى لو لم تستخدم الخاصية مباشرة.
+
+3. **تقليل إعادة استخدام المكونات**: يصبح المكون الذي يتلقى الكثير من الخصائص لتمريرها فقط أقل شمولية وأصعب في إعادة استخدامه في سياقات مختلفة.
+
+إذا شعرت أنك تستخدم تمرير الخصائص بشكل مفرط، راجع [أفضل ممارسات إدارة الحالة](#state-management).
+
+## استيرادات
+
+عند الاستيراد، اختر الأسماء المستعارة المتعينة بدلا من تحديد المسارات كاملة أو نسبية.
+
+**الأسماء المستعارة**
+
+```js
+{
+  alias: {
+    "~": path.resolve(__dirname, "src"),
+    "@": path.resolve(__dirname, "src/modules"),
+    "@testing": path.resolve(__dirname, "src/testing"),
+  },
+}
+```
+
+**الاستخدام**
+
+```tsx
+// ❌ Bad, specifies the entire relative path
+import {
+  CatalogDecorator
+} from '../../../../../testing/decorators/CatalogDecorator';
+import {
+  ComponentDecorator
+} from '../../../../../testing/decorators/ComponentDecorator';
+```
+
+```tsx
+// ✅ Good, utilises the designated aliases
+import { CatalogDecorator } from '~/testing/decorators/CatalogDecorator';
+import { ComponentDecorator } from 'twenty-ui/testing';
+```
+
+## التحقق من المخططات
+
+[Zod](https://github.com/colinhacks/zod) هو مدقق المخططات للكائنات غير المTyped:
+
+```js
+const validationSchema = z
+  .object({
+    exist: z.boolean(),
+    email: z
+      .string()
+      .email('Email must be a valid email'),
+    password: z
+      .string()
+      .regex(PASSWORD_REGEX, 'Password must contain at least 8 characters'),
+  })
+  .required();
+
+type Form = z.infer<typeof validationSchema>;
+```
+
+## التغييرات الجذرية
+
+قم دائمًا بإجراء اختبارات يدوية شاملة قبل المتابعة لضمان أن التعديلات لم تسبب تعطيلًا في أماكن أخرى، نظرًا لأن الاختبارات لم تدمج حتى الآن بشكل كبير.

packages/twenty-docs/l/ar/developers/contribute/capabilities/frontend-development/folder-architecture-front.mdx

@@ -0,0 +1,110 @@
+---
+title: هيكلية المجلدات
+icon: folder-tree
+info: نظرة مفصلة على هيكل المجلدات الخاصة بنا
+---
+
+في هذا الدليل، ستستكشف تفاصيل هيكل دليل المشروع وكيف يساهم في تنظيم Twenty وسهولة صيانتها.
+
+باتباع اصطلاح هيكل المجلدات هذا، يسهل العثور على الملفات المتعلقة بميزات محددة وضمان أن يكون التطبيق قابلاً للتوسّع والصيانة.
+
+```
+front
+└───modules
+│   └───module1
+│   │   └───submodule1
+│   └───module2
+│   └───ui
+│   │   └───display
+│   │   └───inputs
+│   │   │   └───buttons
+│   │   └───...
+└───pages
+└───...
+```
+
+## الصفحات
+
+تشمل المكونات عالية المستوى المحددة من قبل مسارات التطبيق. وتستورد مكوّنات منخفضة المستوى من مجلد الوحدات (تفاصيل إضافية أدناه).
+
+## الوحدات
+
+تمثّل كل وحدة ميزة أو مجموعة من الميزات، وتضم مكوّناتها الخاصة وحالاتها ومنطقها التشغيلي.
+يجب أن تتبع جميعها البنية المذكورة أدناه. يمكنك تعشيق الوحدات داخل الوحدات (تُعرف بالوحدات الفرعية) وستطبق نفس القواعد.
+
+```
+module1
+  └───components
+  │   └───component1
+  │   └───component2
+  └───constants
+  └───contexts
+  └───graphql
+  │   └───fragments
+  │   └───queries
+  │   └───mutations
+  └───hooks
+  │   └───internal
+  └───states
+  │   └───selectors
+  └───types
+  └───utils
+```
+
+### السياقات
+
+السياق هو وسيلة لتمرير البيانات عبر شجرة المكوّنات دون الحاجة إلى تمرير الخصائص يدويًا في كل مستوى.
+
+انظر [React Context](https://react.dev/reference/react#context-hooks) لمزيد من التفاصيل.
+
+### جراف كيو إل
+
+تشمل الأجزاء، الاستعلامات والتحويرات.
+
+انظر [GraphQL](https://graphql.org/learn/) لمزيد من التفاصيل.
+
+* الأجزاء
+
+الجزء هو جزء قابل لإعادة الاستخدام من استعلام، والذي يمكنك استخدامه في أماكن مختلفة. باستخدام الأجزاء، يصبح من الأسهل تجنب تكرار التعليمات البرمجية.
+
+انظر [GraphQL Fragments](https://graphql.org/learn/queries/#fragments) لمزيد من التفاصيل.
+
+* الاستعلامات
+
+انظر [GraphQL Queries](https://graphql.org/learn/queries/) لمزيد من التفاصيل.
+
+* التحويرات
+
+انظر [GraphQL Mutations](https://graphql.org/learn/queries/#mutations) لمزيد من التفاصيل.
+
+### الخطافات
+
+انظر [Hooks](https://react.dev/learn/reusing-logic-with-custom-hooks) لمزيد من التفاصيل.
+
+### الحالات
+
+تشمل منطق إدارة الحالة. [Jotai](https://jotai.org) يتولّى ذلك.
+
+* المحددات: الذرات المشتقة (باستخدام `createAtomSelector`) تحسب قيماً من ذرات أخرى وتخزن نتائجها في الذاكرة مؤقتاً تلقائياً.
+
+لا تزال إدارة الحالة المدمجة في React تتولّى الحالة داخل المكوّن.
+
+### الأدوات
+
+يجب أن تحتوي فقط على دوال نقية قابلة لإعادة الاستخدام. بخلاف ذلك، أنشئ خطافات مخصصة في مجلد `hooks`.
+
+## واجهة المستخدم
+
+تحتوي على جميع مكونات واجهة المستخدم القابلة لإعادة الاستخدام المستخدمة في التطبيق.
+
+يمكن أن يحتوي هذا المجلد على مجلّدات فرعية، مثل `data`، `display`، `feedback`، و `input` لأنواع معينة من المكوّنات. يجب أن يكون كل مكون مستقلًا وقابلًا لإعادة الاستخدام، حتى تتمكن من استخدامه في أجزاء مختلفة من التطبيق.
+
+من خلال فصل مكونات واجهة المستخدم عن المكونات الأخرى في مجلد `modules`، يسهل الحفاظ على تصميم متسق وإجراء تغييرات على واجهة المستخدم دون التأثير على الأجزاء الأخرى (منطق الأعمال) من قاعدة الشيفرة.
+
+## الواجهة والتبعيات
+
+يمكنك استيراد شيفرة وحدة أخرى من أي وحدة باستثناء مجلد `ui`. سيجعل هذا شيفرته سهلة الاختبار.
+
+### داخلي
+
+كل جزء (خطافات، حالات، ...) من الممكن أن يحتوي جزء من الوحدة على مجلد `internal`، والذي يحتوي على الأجزاء التي تُستخدم فقط داخل الوحدة.

packages/twenty-docs/l/ar/developers/contribute/capabilities/frontend-development/frontend-commands.mdx

@@ -0,0 +1,91 @@
+---
+title: أوامر الواجهة الأمامية
+icon: terminal
+---
+
+## الأوامر المفيدة
+
+### "بدء التطبيق"
+
+```bash
+npx nx start twenty-front
+```
+
+### "إعادة توليد مخطط graphql بناءً على مخطط API graphql"
+
+```bash
+npx nx run twenty-front:graphql:generate --configuration=metadata
+```
+
+"أو"
+
+```bash
+npx nx run twenty-front:graphql:generate
+```
+
+### Lint
+
+```bash
+npx nx run twenty-front:lint # pass --fix to fix lint errors
+```
+
+## "الترجمات"
+
+```bash
+npx nx run twenty-front:lingui:extract
+npx nx run twenty-front:lingui:compile
+```
+
+### تجربة
+
+```bash
+npx nx run twenty-front:test # run jest tests
+npx nx run twenty-front:storybook:serve:dev # run storybook
+npx nx run twenty-front:storybook:test # run tests # (needs yarn storybook:serve:dev to be running)
+npx nx run twenty-front:storybook:coverage # (needs yarn storybook:serve:dev to be running)
+```
+
+## "التقنية المستخدمة"
+
+"المشروع يحتوي على تقنية بسيطة ونظيفة، مع الحد الأدنى من كود البويلر بليت."
+
+"**التطبيق**"
+
+* "[React](https://react.dev/)"
+* "[Apollo](https://www.apollographql.com/docs/)"
+* "[GraphQL Codegen](https://the-guild.dev/graphql/codegen)"
+* [Jotai](https://jotai.org/)
+* "[TypeScript](https://www.typescriptlang.org/)"
+
+**الاختبار**
+
+* [Jest](https://jestjs.io/)
+* "[Storybook](https://storybook.js.org/)"
+
+**الأدوات**
+
+* [Yarn](https://yarnpkg.com/)
+* "[Craco](https://craco.js.org/docs/)"
+* [Oxlint](https://oxc.rs/docs/guide/usage/linter.html)
+
+## "الهيكلية"
+
+### "التوجيه"
+
+"[React Router](https://reactrouter.com/) يتعامل مع التوجيه."
+
+لتجنب غير ضروري [re-renders](/l/ar/developers/contribute/capabilities/frontend-development/best-practices-front#managing-re-renders) كل منطق المسارات في 'useEffect' في 'PageChangeEffect'.
+
+### "إدارة الحالة"
+
+[Jotai](https://jotai.org/) يتعامل مع إدارة الحالة.
+
+"راجع [أفضل الممارسات](/l/ar/developers/contribute/capabilities/frontend-development/best-practices-front#state-management) لمزيد من المعلومات حول إدارة الحالة."
+
+## "الاختبار"
+
+"[Jest](https://jestjs.io/) يعمل كأداة لاختبار الوحدات بينما يعمل [Storybook](https://storybook.js.org/) لاختبار المكونات."
+
+"يستخدم Jest بشكل رئيسي لاختبار دوال الأدوات وليس المكونات نفسها."
+
+"Storybook لاختبار سلوك المكونات المعزولة، وكذلك عرض نظام التصميم."

packages/twenty-docs/l/ar/developers/contribute/capabilities/frontend-development/hotkeys.mdx

@@ -0,0 +1,178 @@
+---
+title: مفاتيح الاختصار
+---
+
+## مقدمة
+
+عندما تحتاج إلى الاستماع إلى مفتاح اختصار، فإنه عادةً ما تستخدم مستمع الحدث `onKeyDown`.
+
+في `twenty-front`، قد تواجه تعارضات بين نفس مفاتيح الاختصار المستخدمة في مكونات مختلفة، مركبة في الوقت نفسه.
+
+على سبيل المثال، إذا كان لديك صفحة تستمع لمفتاح Enter ومودال يستمع لمفتاح Enter، ولكن به مكون Select يستمع لمفتاح Enter، فقد تواجه تعارضًا عند تركيب الجميع في الوقت نفسه.
+
+## الخطاف `useScopedHotkeys`
+
+لمعالجة هذه المشكلة، لدينا خطاف مخصص يمكن من الاستماع لمفاتيح الاختصار دون أي تعارض.
+
+تضعه داخل مكوّن، ولن يستمع إلى مفاتيح الاختصار إلا عندما يكون المكوّن مُركّبًا وعندما يكون **نطاق مفاتيح الاختصار** المحدّد نشطًا.
+
+## كيف تستمع إلى مفاتيح الاختصار عمليًا؟
+
+هناك خطوتان متضمنتان في إعداد الاستماع لمفاتيح الاختصار:
+
+1. تعيين [نطاق المفتاح](#what-is-a-hotkey-scope-) الذي سيستمع لمفاتيح الاختصار
+2. استخدام الخطاف `useScopedHotkeys` للاستماع لمفاتيح الاختصار
+
+إعداد نطاقات مفاتيح الاختصار ضروري حتى في الصفحات البسيطة، لأن عناصر أخرى في واجهة المستخدم مثل القائمة اليسرى أو قائمة الأوامر قد تستمع أيضًا لمفاتيح الاختصار.
+
+## حالات الاستخدام لمفاتيح الاختصار
+
+بشكل عام، سيكون لديك حالتا استخدام تتطلبان مفاتيح الاختصار:
+
+1. في صفحة أو مكون مركب في صفحة
+2. في مكون من نوع مودال يتخذ التركيز بسبب إجراء من المستخدم
+
+يمكن حدوث الحالة الثانية بشكل متكرر: على سبيل المثال، في قائمة منسدلة في مودال.
+
+### الاستماع لمفاتيح الاختصار في صفحة
+
+مثال:
+
+```tsx
+const PageListeningEnter = () => {
+  const {
+    setHotkeyScopeAndMemorizePreviousScope,
+    goBackToPreviousHotkeyScope,
+  } = usePreviousHotkeyScope();
+
+  // 1. Set the hotkey scope in a useEffect
+  useEffect(() => {
+    setHotkeyScopeAndMemorizePreviousScope(
+      ExampleHotkeyScopes.ExampleEnterPage,
+    );
+
+    // Revert to the previous hotkey scope when the component is unmounted
+    return () => {
+      goBackToPreviousHotkeyScope();
+    };
+  }, [goBackToPreviousHotkeyScope, setHotkeyScopeAndMemorizePreviousScope]);
+
+  // 2. Use the useScopedHotkeys hook
+  useScopedHotkeys(
+    Key.Enter,
+    () => {
+      // Some logic executed on this page when the user presses Enter
+      // ...
+    },
+    ExampleHotkeyScopes.ExampleEnterPage,
+  );
+
+  return <div>My page that listens for Enter</div>;
+};
+```
+
+### الاستماع لمفاتيح الاختصار في مكون من نوع مودال
+
+في هذا المثال سنستخدم مكوّن نافذة منبثقة يستمع لمفتاح Escape ليطلب من المكوّن الأب إغلاقه.
+
+هنا يتمثّل تفاعل المستخدم في تغيير النطاق.
+
+```tsx
+const ExamplePageWithModal = () => {
+  const [showModal, setShowModal] = useState(false);
+
+  const {
+    setHotkeyScopeAndMemorizePreviousScope,
+    goBackToPreviousHotkeyScope,
+  } = usePreviousHotkeyScope();
+
+  const handleOpenModalClick = () => {
+    // 1. Set the hotkey scope when user opens the modal
+    setShowModal(true);
+    setHotkeyScopeAndMemorizePreviousScope(
+      ExampleHotkeyScopes.ExampleModal,
+    );
+  };
+
+  const handleModalClose = () => {
+    // 1. Revert to the previous hotkey scope when the modal is closed
+    setShowModal(false);
+    goBackToPreviousHotkeyScope();
+  };
+
+  return <div>
+    <h1>My page with a modal</h1>
+    <button onClick={handleOpenModalClick}>Open modal</button>
+    {showModal && <MyModalComponent onClose={handleModalClose} />}
+  </div>;
+};
+```
+
+ثم في مكون المودال:
+
+```tsx
+const MyDropdownComponent = ({ onClose }: { onClose: () => void }) => {
+  // 2. Use the useScopedHotkeys hook to listen for Escape.
+  // Note that escape is a common hotkey that could be used by many other components
+  // So it's important to use a hotkey scope to avoid conflicts
+  useScopedHotkeys(
+    Key.Escape,
+    () => {
+      onClose()
+    },
+    ExampleHotkeyScopes.ExampleModal,
+  );
+
+  return <div>My modal component</div>;
+};
+```
+
+من المهم استخدام هذا النمط عندما لست متأكدا من أن استخدام تأثير الاستخدام مع التركيب/إلغاء التثبيت سيكون كافيا لتجنب الصراعات.
+
+ويمكن أن يكون من الصعب تصحيح تلك الصراعات، وقد يحدث ذلك في كثير من الأحيان بآثار استعمالية.
+
+## ما هو نطاق المفتاح؟
+
+نطاق المفتاح هو سلسلة تمثل السياق الذي تكون فيه مفاتيح الاختصار نشطة. عادة ما تكون مشفرة كنوع مفصل.
+
+عندما تقوم بتغيير نطاق المفتاح، سيتم تمكين مفاتيح الاختصار المستمعة لهذا النطاق وتعطيل المفاتيح المستمعة لنطاقات أخرى.
+
+يمكنك تعيين نطاق واحد فقط في كل مرة.
+
+على سبيل المثال، يتم تعريف نطاقات مفاتيح الاختصار لكل صفحة في نوع "PageHotkeyScope" المفصل:
+
+```tsx
+export enum PageHotkeyScope {
+  Settings = 'settings',
+  CreateWorkspace = 'create-workspace',
+  SignInUp = 'sign-in-up',
+  CreateProfile = 'create-profile',
+  PlanRequired = 'plan-required',
+  ShowPage = 'show-page',
+  PersonShowPage = 'person-show-page',
+  CompanyShowPage = 'company-show-page',
+  CompaniesPage = 'companies-page',
+  PeoplePage = 'people-page',
+  OpportunitiesPage = 'opportunities-page',
+  ProfilePage = 'profile-page',
+  WorkspaceMemberPage = 'workspace-member-page',
+  TaskPage = 'task-page',
+}
+```
+
+داخليًا، يتم تخزين النطاق المحدد حاليًا في ذرة Jotai مشتركة عبر التطبيق:
+
+```tsx
+export const currentHotkeyScopeState = createState<HotkeyScope>({
+  key: 'currentHotkeyScopeState',
+  defaultValue: INITIAL_HOTKEYS_SCOPE,
+});
+```
+
+لكن لا يجب التعامل مع هذه الذرة يدويًا! سنرى كيف يمكن استخدامها في القسم التالي.
+
+## كيف يعمل داخليًا؟
+
+قمنا بإنشاء غلاف رقيق فوق [react-hotkeys-hook](https://react-hotkeys-hook.vercel.app/docs/intro) والذي يجعله أكثر كفاءة ويتجنب عمليات إعادة التقديم غير الضرورية.
+
+ونقوم أيضًا بإنشاء ذرة Jotai للتعامل مع حالة نطاق مفاتيح الاختصار وجعلها متاحة في جميع أنحاء التطبيق.

packages/twenty-docs/l/ar/developers/contribute/capabilities/frontend-development/storybook.mdx

@@ -0,0 +1,8 @@
+---
+title: Storybook
+description: تصفح مكتبة مكونات واجهة المستخدم الخاصة بـ Twenty
+---
+
+اطلع على مكتبة المكونات الكاملة لدينا والتوثيق في Storybook.
+
+[افتح Storybook →](https://storybook.twenty.com)

packages/twenty-docs/l/ar/developers/contribute/capabilities/frontend-development/style-guide.mdx

@@ -0,0 +1,291 @@
+---
+title: دليل الأسلوب
+icon: paintbrush
+---
+
+تشمل هذه الوثيقة القواعد التي يجب اتباعها عند كتابة التعليمات البرمجية.
+
+الهدف هنا هو وجود قاعدة شيفرة متسقة يسهل قراءتها وصيانتها.
+
+لهذا، من الأفضل أن تكون تفصيلًا أكثر قليلاً بدلاً من أن تكون موجزًا للغاية.
+
+دائمًا ضع في اعتبارك أن الناس يقرؤون التعليمات البرمجية أكثر مما يكتبونها، وخاصة في مشروع مفتوح المصدر، حيث يمكن لأي شخص المساهمة.
+
+هناك العديد من القواعد التي لم يتم تعريفها هنا، ولكن يتم التحقق منها تلقائيًا بواسطة أدوات الفحص.
+
+## React
+
+### استخدام المكونات الوظيفية
+
+استخدم دائمًا مكونات TSX الوظيفية.
+
+لا تستخدم `import` الافتراضي مع `const`، لأنه أصعب من حيث القراءة والدمج باستخدام إكمال التعليمات البرمجية.
+
+```tsx
+// ❌ Bad, harder to read, harder to import with code completion
+const MyComponent = () => {
+  return <div>Hello World</div>;
+};
+
+export default MyComponent;
+
+// ✅ Good, easy to read, easy to import with code completion
+export function MyComponent() {
+  return <div>Hello World</div>;
+};
+```
+
+### الإزاحة
+
+قم بإنشاء نوع الخصائص واطلق عليه `(ComponentName)Props` إذا لم يكن هناك حاجة لتصديره.
+
+استخدام تفكيك الخصائص.
+
+```tsx
+// ❌ Bad, no type
+export const MyComponent = (props) => <div>Hello {props.name}</div>;
+
+// ✅ Good, type
+type MyComponentProps = {
+  name: string;
+};
+
+export const MyComponent = ({ name }: MyComponentProps) => <div>Hello {name}</div>;
+```
+
+#### امتنع عن استخدام `React.FC` أو `React.FunctionComponent` لتحديد أنواع الخصائص
+
+```tsx
+/* ❌ - Bad, defines the component type annotations with `FC`
+ *    - With `React.FC`, the component implicitly accepts a `children` prop
+ *      even if it's not defined in the prop type. This might not always be
+ *      desirable, especially if the component doesn't intend to render
+ *      children.
+ */
+const EmailField: React.FC<{
+  value: string;
+}> = ({ value }) => <TextInput value={value} disabled fullWidth />;
+```
+
+```tsx
+/* ✅ - Good, a separate type (OwnProps) is explicitly defined for the
+ *      component's props
+ *    - This method doesn't automatically include the children prop. If
+ *      you want to include it, you have to specify it in OwnProps.
+ */
+type EmailFieldProps = {
+  value: string;
+};
+
+const EmailField = ({ value }: EmailFieldProps) => (
+  <TextInput value={value} disabled fullWidth />
+);
+```
+
+#### لا تستخدم انتشار متغير فردي للخصائص في عناصر JSX
+
+تجنب استخدام انتشار متغير فردي للخصائص في عناصر JSX، مثل `{...props}`. غالبًا ما تؤدي هذه الممارسة إلى شكل تعليمي أقل قابلية للقراءة وأصعب في الصيانة لأنه من غير الواضح أي الخصائص يتلقاها المكون.
+
+```tsx
+/* ❌ - Bad, spreads a single variable prop into the underlying component
+ */
+const MyComponent = (props: OwnProps) => {
+  return <OtherComponent {...props} />;
+}
+```
+
+```tsx
+/* ✅ - Good, Explicitly lists all props
+ *    - Enhances readability and maintainability
+ */
+const MyComponent = ({ prop1, prop2, prop3 }: MyComponentProps) => {
+  return <OtherComponent {...{ prop1, prop2, prop3 }} />;
+};
+```
+
+المبرر:
+
+* نظرة سريعة تسهل معرفة الخصائص التي تمررها التعليمات البرمجية، مما يسهل من الفهم والصيانة.
+* يساعد على منع نشوء تعقيدات كبيرة بين المكونات من خلال خصائصها.
+* أدوات الفحص تجعل من السهل تحديد الخصائص التي بها أخطاء إملائية أو غير مستخدمة عندما تسرد الخصائص بشكل صريح.
+
+## JavaScript
+
+### استخدم معامل دمج القيم الفارغة `??`
+
+```tsx
+// ❌ Bad, can return 'default' even if value is 0 or ''
+const value = process.env.MY_VALUE || 'default';
+
+// ✅ Good, will return 'default' only if value is null or undefined
+const value = process.env.MY_VALUE ?? 'default';
+```
+
+### استخدم معامل الربط الاختياري `?.`
+
+```tsx
+// ❌ Bad
+onClick && onClick();
+
+// ✅ Good
+onClick?.();
+```
+
+## TypeScript
+
+### استخدام `type` بدلاً من `interface`
+
+استخدم دائمًا `type` بدلاً من `interface`، لأنهما تقريبًا دائمًا متداخلين، و `type` أكثر مرونة.
+
+```tsx
+// ❌ Bad
+interface MyInterface {
+  name: string;
+}
+
+// ✅ Good
+type MyType = {
+  name: string;
+};
+```
+
+### استخدم السلاسل النصية بدلاً من التعدادات
+
+[الحروف المشفوعة](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types) هي الطريقة المفضلة للتعامل مع القيم الشبيهة بالأعداد المخصصة في TypeScript. من السهل توسيعها باستخدام Pick و Omit، وتقدم تجربة مطور أفضل، خاصة مع إكمال التعليمات البرمجية.
+
+يمكنك معرفة السبب في أن TypeScript توصي بتجنب الأعداد [هنا](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#enums).
+
+```tsx
+// ❌ Bad, utilizes an enum
+enum Color {
+  Red = "red",
+  Green = "green",
+  Blue = "blue",
+}
+
+let color = Color.Red;
+```
+
+```tsx
+// ✅ Good, utilizes a string literal
+
+let color: "red" | "green" | "blue" = "red";
+```
+
+#### GraphQL والمكتبات الداخلية
+
+يجب عليك استخدام الأعداد التي يقوم بإنشائها GraphQL codegen.
+
+من الأفضل أيضًا استخدام عدد مخصص عند استخدام مكتبة داخلية، بحيث لا تضطر المكتبة الداخلية إلى تعريض نوع حرف مشفوع غير متعلق بـ API الداخلي.
+
+مثال:
+
+```TSX
+const {
+  setHotkeyScopeAndMemorizePreviousScope,
+  goBackToPreviousHotkeyScope,
+} = usePreviousHotkeyScope();
+
+setHotkeyScopeAndMemorizePreviousScope(
+  RelationPickerHotkeyScope.RelationPicker,
+);
+```
+
+## التنسيق
+
+### استخدام مكونات منسقة
+
+قم بتنسيق المكونات باستخدام [Linaria styled](https://github.com/callstack/linaria).
+
+```tsx
+// ❌ Bad
+<div className="my-class">Hello World</div>
+```
+
+```tsx
+// ✅ Good
+const StyledTitle = styled.div`
+  color: red;
+`;
+```
+
+قم بإضافة بادئة للمكونات المنسقة بـ "Styled" لتمييزها عن المكونات "الحقيقية".
+
+```tsx
+// ❌ Bad
+const Title = styled.div`
+  color: red;
+`;
+```
+
+```tsx
+// ✅ Good
+const StyledTitle = styled.div`
+  color: red;
+`;
+```
+
+### السمات
+
+استخدام السمة لتنسيق معظم المكونات هو النهج المفضل.
+
+#### وحدات القياس
+
+تجنب استخدام قيم `px` أو `rem` مباشرة داخل المكونات المنسقة. بشكل عام، عادة ما تكون القيم المحددة مسبقًا موجودة بالفعل في السمة، لذا يفضل استخدام السمة لتحقيق هذا الغرض.
+
+#### ألوان
+
+امتنع عن تقديم ألوان جديدة، بدلاً من ذلك، استخدم اللوحة الموجودة في السمة. إذا كانت هناك حالة لا تتطابق فيها اللوحة، يرجى ترك تعليق لكي تتمكن الفريق من تصحيحها.
+
+```tsx
+// ❌ Bad, directly specifies style values without utilizing the theme
+const StyledButton = styled.button`
+  color: #333333;
+  font-size: 1rem;
+  font-weight: 400;
+  margin-left: 4px;
+  border-radius: 50px;
+`;
+```
+
+```tsx
+// ✅ Good, utilizes the theme
+const StyledButton = styled.button`
+  color: ${({ theme }) => theme.font.color.primary};
+  font-size: ${({ theme }) => theme.font.size.md};
+  font-weight: ${({ theme }) => theme.font.weight.regular};
+  margin-left: ${({ theme }) => theme.spacing(1)};
+  border-radius:  ${({ theme }) => theme.border.rounded};
+`;
+```
+
+## تطبيق قاعدة "عدم استيراد الأنواع"
+
+تجنب استيراد الأنواع. لفرض هذا المعيار، تتحقق قاعدة Oxlint وتبلغ عن أي استيرادات للأنواع. يساعد هذا على الحفاظ على الاتساق وقابلية القراءة في كود TypeScript.
+
+```tsx
+// ❌ Bad
+import { type Meta, type StoryObj } from '@storybook/react';
+
+// ❌ Bad
+import type { Meta, StoryObj } from '@storybook/react';
+
+// ✅ Good
+import { Meta, StoryObj } from '@storybook/react';
+```
+
+### لماذا لا نوع استيرادات
+
+* **الاتساق**: من خلال تجنب استيراد الأنواع واستخدام أسلوب استيراد واحد لكل من الأنواع والقيم، يبقى الكود موحدًا في أسلوب استيراد الوحدة.
+
+* **القراءة**: استيرادات بلا نوع تحسن من قابلية القراءة للرمز من خلال توضيح عندما تقوم باستيراد القيم أو الأنواع. يقلل هذا من الغموض ويجعل من الأسهل فهم الهدف من الرموز المستوردة.
+
+* **الصيانة**: يعزز الصيانة داخل قاعدة الكود لأن المطوّرين يمكنهم تحديد مواقع استيرادات الأنواع فقط عند استعراض أو تعديل الكود.
+
+### قاعدة Oxlint
+
+تفرض قاعدة Oxlint، `typescript/consistent-type-imports`, معيار عدم استيراد الأنواع. ستولد هذه القاعدة تحذيرات أو أخطاء عن أي انتهاكات لاستيراد الأنواع.
+
+يرجى ملاحظة أن هذه القاعدة تتناول بشكل خاص حالات الحافة النادرة حيث تحدث استيرادات الأنواع دون قصد. يمنع TypeScript نفسه هذه الممارسة، كما هو موضح في [ملاحظات إصدار TypeScript 3.8](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html). في معظم الحالات، لا ينبغي لك أن تستخدم استيرادات الأنواع وحدها.
+
+لضمان امتثال الكود الخاص بك لهذه القاعدة، تأكد من تشغيل Oxlint كجزء من سير العمل الخاص بالتطوير لديك.

packages/twenty-docs/l/ar/developers/contribute/capabilities/frontend-development/work-with-figma.mdx

@@ -0,0 +1,60 @@
+---
+title: العمل مع فيجما
+info: تعرّف على كيفية التعاون باستخدام Figma الخاص بـ Twenty
+---
+
+فيجما هي أداة تصميم واجهات تعاونية تساعد في سد فجوة التواصل بين المصممين والمطورين.
+يشرح هذا الدليل كيف يمكنك التعاون مع فيجما.
+
+## الوصول
+
+1. **الوصول إلى الرابط المشترك:** يمكنك الوصول إلى ملف فيجما الخاص بالمشروع [هنا](https://www.figma.com/file/xt8O9mFeLl46C5InWwoMrN/Twenty).
+2. **تسجيل الدخول:** إذا لم تكن قد سجلت دخولك بالفعل، سيطلب منك فيجما القيام بذلك.
+   تتوفر المميزات الرئيسية فقط للمستخدمين الذين قاموا بتسجيل الدخول، مثل وضع المطور والقدرة على اختيار إطار مخصص.
+
+<Warning>
+
+لن تتمكن من التعاون بفعالية بدون حساب.
+
+</Warning>
+
+## هيكل فيجما
+
+من الشريط الجانبي الأيسر، يمكنك الوصول إلى الصفحات المختلفة في Figma الخاص بـ Twenty. هكذا هم مُنظمون:
+
+* **صفحة المكونات:** هذه هي الصفحة الأولى. يستخدمها المصمم لإنشاء وتنظيم العناصر التصميمية القابلة لإعادة الاستخدام في ملف التصميم. على سبيل المثال، الأزرار، الأيقونات، الرموز أو أي مكونات أخرى قابلة لإعادة الاستخدام. تعمل على الحفاظ على التناسق عبر التصميم.
+* **الصفحة الرئيسية:** الصفحة الثانية هي الصفحة الرئيسية التي تظهر واجهة المستخدم الكاملة للمشروع. يمكنك الضغط على ***تشغيل*** لاستخدام النموذج الأولي الكامل للتطبيق.
+* **صفحات الميزات:** الصفحات الأخرى تكون مخصصة عادة للميزات قيد التقدم. تحتوي على تصميم الميزات أو الوحدات المحددة للتطبيق أو الموقع الإلكتروني. عادة ما تكون لا تزال قيد التقدم.
+
+## نصائح مفيدة
+
+مع الوصول لعرض فقط، لا يمكنك تحرير التصميم، ولكن يمكنك الوصول إلى جميع الميزات التي ستكون مفيدة لتحويل التصميمات إلى كود.
+
+### استخدم وضع المطور
+
+يعزز وضع المطور في فيجما إنتاجية المطورين من خلال توفير التنقل السهل في التصميم، إدارة فعالة للموارد، أدوات اتصال فعالة، تكاملات طقم الأدوات، مقتطفات كود سريعة، ومعلومات رئيسية عن الطبقات، مما يسد الفجوة بين التصميم والتطوير. يمكنك معرفة المزيد عن وضع المطور [هنا](https://www.figma.com/dev-mode/).
+
+قم بالتبديل إلى وضع "المطور" في الجزء الأيمن من شريط الأدوات لتشاهد مواصفات التصميم، نسخ CSS، والوصول إلى الموارد.
+
+### استخدم النموذج الأولي
+
+انقر على أي عنصر على اللوحة واضغط على زر “تشغيل” في نهاية الحافة العلوية لواجهة المستخدم للوصول إلى عرض النموذج الأولي. يسمح لك وضع النموذج الأولي بالتفاعل مع التصميم كما لو كان المنتج النهائي. يوضح التدفق بين الشاشات وكيف تتصرف عناصر الواجهة مثل الأزرار، الروابط، أو القوائم عند التفاعل معها.
+
+1. **فهم الانتقالات والرسوم المتحركة:** في وضع النموذج الأولي، يمكنك مشاهدة أي انتقالات أو رسوم متحركة أضافها المصمم بين الشاشات أو عناصر واجهة المستخدم، مما يوفر تعليمات بصرية واضحة للمطورين حول السلوك والنمط المقصود.
+2. **توضيح التنفيذ:** يمكن أن يساعد النموذج الأولي أيضًا في تقليل الغموض. يمكن للمطورين التفاعل معه لاكتساب فهم أفضل لوظيفة أو مظهر عناصر معينة.
+
+للحصول على تفاصيل شاملة وإرشادات لتعلم منصة فيجما، يمكنك زيارة [وثائق فيجما الرسمية](https://help.figma.com/hc/en-us).
+
+### قياس المسافات
+
+حدد عنصرًا، اضغط مع الاستمرار على مفتاح `Option` (لماك) أو مفتاح `Alt` (لويندوز)، ثم مرر فوق عنصر آخر لرؤية المسافة بينهما.
+
+### إضافة فيجما لـ VSCode (موصى به)
+
+[فيجما لـ VS Code](https://marketplace.visualstudio.com/items?itemName=figma.figma-vscode-extension) يتيح لك التنقل ومعاينة ملفات التصميم، التعاون مع المصممين، تتبع التغييرات، وتسريع التنفيذ - دون مغادرة محرر النصوص الخاص بك.
+إنها جزء من الإضافات الموصى بها لدينا.
+
+## التعاون
+
+1. **استخدام التعليقات:** يمكنك استخدام ميزة التعليق بالنقر على أيقونة الفقاعة في الجزء الأيسر من شريط الأدوات.
+2. **دردشة المؤشر:** ميزة لطيفة في فيجما هي دردشة المؤشر. فقط اضغط على `;` على ماك و`/` على ويندوز لإرسال رسالة إذا رأيت شخصًا آخر يستخدم فيجما في نفس الوقت الذي تستخدمه فيه.