docs: refine contents

Author: amir78729

.vitepress/config/fa.mts

@@ -47,7 +47,7 @@ export const fa = defineConfig({
       quote:
         "اما اگر جهت خود را تغییر ندهید و اگر ادامه دهید به دنبال چیزی که دنبال می‌کنید، ممکن است در نهایت به جایی که در حال رفتن به سمتش هستید، برسید.",
     },
-    siteTitle: "قابلیت دسترسی (accessibility)",
+    siteTitle: "Accessibility",
   },
 });
 
@@ -82,6 +82,10 @@ function sidebar(): DefaultTheme.SidebarItem[] {
           text: "Personaهای مرتبط با accessibility",
           link: "/persona",
         },
+        {
+          text: "تمرین",
+          link: "/excercise-1",
+        },
       ],
     },
     {
@@ -108,6 +112,10 @@ function sidebar(): DefaultTheme.SidebarItem[] {
           text: "چگونه یک کامپوننت UI را از نظر accessibility تست کنیم",
           link: "/how-to-test-components",
         },
+        // {
+        //   text: "تمرین: بهبود یک کامپوننت!",
+        //   link: "/excersice-2",
+        // },
       ],
     },
     {

.vitepress/config/shared.mts

@@ -1,16 +1,17 @@
-import { defineConfig } from 'vitepress'
+import { defineConfig } from "vitepress";
 export const shared = defineConfig({
   rewrites: {
-    'en/:rest*': ':rest*'
+    "en/:rest*": ":rest*",
   },
   lastUpdated: true,
   cleanUrls: true,
   metaChunk: true,
-  base: '/a11y',
+  base: "/a11y",
 
   themeConfig: {
-    socialLinks: [
-        { icon: 'github', link: 'https://github.com/amir78729' }
-      ],
+    editLink: {
+      pattern: "https://github.com/code-with-amirhossein/a11y/edit/main/:path",
+    },
+    socialLinks: [{ icon: "github", link: "https://github.com/amir78729" }],
   },
-})
+});

.vitepress/theme/index.ts

@@ -1,5 +1,6 @@
 import DefaultTheme from 'vitepress/theme'
 import './fonts.css'
 import './custom.css'
+import '../../components/stackBlitzEmbed'
 
 export default DefaultTheme

api-examples.md

@@ -0,0 +1,64 @@
+class StackBlitzEmbed extends HTMLElement {
+	constructor() {
+		super();
+		this.attachShadow({ mode: 'open' });
+	}
+
+	static get observedAttributes() {
+		return ['name', 'height', 'view', 'open-file', 'hide-explorer', 'show-devtools'];
+	}
+
+	connectedCallback() {
+		this.render();
+	}
+
+	attributeChangedCallback() {
+		this.render();
+	}
+
+	get name() {
+		return this.getAttribute('name') || '';
+	}
+
+	get height() {
+		return this.getAttribute('height') || '600';
+	}
+
+	get view() {
+		return this.getAttribute('view') || 'preview';
+	}
+
+	get openFile() {
+		return this.getAttribute('open-file') || '';
+	}
+
+	get hideExplorer() {
+		return this.hasAttribute('hide-explorer');
+	}
+
+	get showDevtools() {
+		return this.hasAttribute('show-devtools');
+	}
+
+	render() {
+		const iframe = document.createElement('iframe');
+		const params = new URLSearchParams({
+			embed: '1',
+			hideExplorer: this.hideExplorer ? '1' : '0',
+			file: this.openFile,
+			view: this.view,
+			devToolsHeight: this.showDevtools ? '50' : '0',
+		});
+
+		iframe.src = `https://stackblitz.com/edit/${this.name}?${params.toString()}`;
+		iframe.height = this.height;
+		iframe.style.width = '100%';
+		iframe.style.border = 'none';
+
+		// Clear previous content
+		this.shadowRoot.innerHTML = '';
+		this.shadowRoot.appendChild(iframe);
+	}
+}
+
+customElements.define('stackblitz-embed', StackBlitzEmbed);

components/stackBlitzEmbed.js

@@ -0,0 +1,15 @@
+# تمرین بحث گروهی
+
+در اولین تمرین، یک مشخصه برای قابلیت جدید بررسی می‌شود — با در نظر گرفتن accessibility. چه سؤالاتی باید از ابتدا مطرح کنیم تا مطمئن شویم این قابلیت در زمان انتشار، accessible خواهد بود؟
+
+## قابلیت: کامپوننت Typeahead برای جستجو
+
+<figure className="my-6">
+    <img src="/typeahead.png" alt="A screenshot of the Amazon search box, with toddler results" className="max-w-[560px]" />
+</figure>
+
+## مواردی برای بحث
+
+- الزامات accessibility برای این قابلیت چیستند؟
+- برای رعایت Deadlineها، چه چیزهایی را می‌توان حذف کرد، بدون اینکه به accessibility آسیب برسد؟
+- چگونه می‌توان این قابلیت را به‌صورت مرحله‌ای توسعه داد؟

markdown-examples.md

@@ -4,7 +4,7 @@
     <img src="/SDLC.png" alt="The Software Development Lifecycle" style="border-radius: 50%; padding: 64px 10%;" />
 </figure>
 
-زمانی که در مراحل برنامه‌ریزی، طراحی یا مهندسی به accessibility توجه نمی‌شود، اعمال تغییرات و اصلاحات بعدی می‌تواند دشوار و پرهزینه باشد — به‌ویژه اگر تصمیمات گرفته‌شده به بخش اساسی هویت محصول تبدیل شده باشند، مانند رنگ برند یا پیاده‌سازی کامل برنامه با HTML5 Canvas.
+زمانی که در مراحل برنامه‌ریزی، طراحی یا مهندسی به accessibility توجه نمی‌شود، اعمال تغییرات و اصلاحات بعدی می‌تواند دشوار و پرهزینه باشد — به‌ویژه اگر تصمیمات گرفته‌شده به بخش اساسی هویت محصول تبدیل شده باشند، مانند رنگ برند یا پیاده‌سازی کامل برنامه با HTML5 Canvas (مثل Figma).
 
 بیشترین موفقیت زمانی حاصل می‌شود که accessibility در چرخه عمر توسعه نرم‌افزار (SDLC) به مراحل ابتدایی‌تر منتقل شود؛ از مرحله پیاده‌سازی (مهندسی) به طراحی و از طراحی به برنامه‌ریزی.
 

public/typeahead.png

@@ -7,47 +7,44 @@
 <figure className="grid grid-cols-2 gap-6 py-2 item-start">
 
 ```tsx
-
 const Submit = () => {
-    const handleKeyDown = (event) => {
-        if (event.code === 'Space' || event.code === 'Enter') {
-            // do click stuff
-        }
-    };
-
-    return (
-        <div
-            onClick={handleClick}
-            onKeyDown={handleKeyDown}
-            role="button"
-            tabIndex="0"
-        >
-            Submit
-        </div>
-    )
-}
-
+  const handleKeyDown = (event) => {
+    if (event.code === "Space" || event.code === "Enter") {
+      // do click stuff
+    }
+  };
+
+  return (
+    <div
+      onClick={handleClick}
+      onKeyDown={handleKeyDown} // Add functionality for keyboard users // [!code highlight]
+      role="button" // Tell the screen readers that it's a button (it's NOT!) // [!code highlight]
+      tabIndex="0" // Make it focusable! // [!code highlight]
+    >
+      Submit
+    </div>
+  );
+};
 ```
 
-
 </figure>
 
 در key handler باید به‌طور شرطی منطق مورد نظر را هنگام فشردن کلید Space یا Enter اجرا کنید. و اگر دکمه‌ شما آیکونی است یا محتوای متنی ندارد، فراموش نکنید که یک نام قابل دسترس (احتمالاً با `aria-label`) به آن اختصاص دهید.
 
-استفاده از عنصر `button` بسیار ساده‌تر است. برای رسیدن به همان عملکرد و سطح دسترسی، تنها کافی است:
+استفاده از عنصر `button` بسیار ساده‌تر است. برای رسیدن به همان عملکرد و سطح دسترسی، تنها کافی است بگوییم:
 
 ```javascript
 <button onClick={handleClick}>Submit</button>
 ```
 
-همین. نیازی به تعیین role صریح، `tabIndex`، یا key handler ندارید (چون دکمه‌ها به‌صورت پیش‌فرض از طریق کیبورد فعال می‌شوند، بر خلاف DIVها).
+همین! نیازی به تعیین role صریح، `tabIndex`، یا key handler نداریم (چون دکمه‌ها به‌صورت پیش‌فرض از طریق کیبورد فعال می‌شوند، بر خلاف DIVها).
 
 ## مراقب دکمه‌های DIV باشید
 
 این یکی از ساده‌ترین مشکلاتی است که می‌توان در بازبینی کدها شناسایی کرد: رویداد کلیک روی یک DIV (یا listitem یا سایر عناصر غیرتعاملی). معمولاً اعضای تیم تلاش خود را می‌کنند و role و tabIndex را اضافه می‌کنند، اما اغلب key handler را فراموش می‌کنند، چون تست با کیبورد بخشی از فرآیند کاری روزمره‌ آن‌ها نیست.
 
 تست با کیبورد را به بخشی از جریان کاری منظم خود تبدیل کنید و از دکمه‌های HTML استفاده کنید! مشکل به‌سادگی حل خواهد شد.
 
-## نکته‌ای درباره هوش مصنوعی
+<!-- ## نکته‌ای درباره هوش مصنوعی
 
-ما باید این مسئله (و سایر بخش‌های مرتبط با accessibility) را در مرحله توسعه، یعنی همان authoring، به‌طور جدی مدنظر قرار دهیم. نباید انتظار داشته باشیم Assistive Tech یا هوش مصنوعی این مشکلات را به‌جای ما حل کنند. چنین دیدگاهی بسیار خاص و وابسته به امکانات لوکس است، در حالی که بسیاری از افراد در سراسر جهان توانایی استفاده از فناوری‌های پیشرفته را ندارند. در عوض، می‌توانیم همین حالا UIهایی بسازیم که از نظر پایه‌ای accessible باشند — هم برای امروز و هم برای آینده.
+ما باید این مسئله (و سایر بخش‌های مرتبط با accessibility) را در مرحله توسعه، یعنی همان authoring، به‌طور جدی مدنظر قرار دهیم. نباید انتظار داشته باشیم Assistive Tech یا هوش مصنوعی این مشکلات را به‌جای ما حل کنند. چنین دیدگاهی بسیار خاص و وابسته به امکانات لوکس است، در حالی که بسیاری از افراد در سراسر جهان توانایی استفاده از فناوری‌های پیشرفته را ندارند. در عوض، می‌توانیم همین حالا UIهایی بسازیم که از نظر پایه‌ای accessible باشند — هم برای امروز و هم برای آینده. -->