@wazir-dev/cli 1.0.0

package/expertise/i18n/rtl/rtl-layout-mirroring.md

@@ -0,0 +1,252 @@
+# RTL Layout Mirroring — i18n/RTL Expertise Module
+
+> The mechanics of layout mirroring: CSS logical properties, Flexbox/Grid behavior, transforms, and platform-specific APIs. Physical vs logical is the central concept—every layout decision must use the correct model.
+
+> **Category:** RTL
+> **Applies to:** Mobile, Web
+> **Key standards:** CSS Logical Properties (MDN), W3C BiDi
+> **RTL impact:** Critical — layout mirroring is the bulk of RTL implementation work
+
+## 1. The Rules
+
+### Physical vs Logical Mapping
+
+| Physical (avoid for layout) | Logical (use) | LTR resolves to | RTL resolves to |
+|-----------------------------|---------------|-----------------|-----------------|
+| `left` | `inset-inline-start` | `left` | `right` |
+| `right` | `inset-inline-end` | `right` | `left` |
+| `margin-left` | `margin-inline-start` | `margin-left` | `margin-right` |
+| `margin-right` | `margin-inline-end` | `margin-right` | `margin-left` |
+| `padding-left` | `padding-inline-start` | `padding-left` | `padding-right` |
+| `padding-right` | `padding-inline-end` | `padding-right` | `padding-left` |
+| `border-left` | `border-inline-start` | `border-left` | `border-right` |
+| `border-right` | `border-inline-end` | `border-right` | `border-left` |
+| `text-align: left` | `text-align: start` | left | right |
+| `text-align: right` | `text-align: end` | right | left |
+
+### Block vs Inline
+
+- **Inline axis** — Direction of text flow (horizontal in LTR/RTL; can be vertical in CJK)
+- **Block axis** — Perpendicular to inline (vertical in horizontal writing modes)
+
+**Logical properties:**
+- `inline-start`, `inline-end` — start/end of inline axis
+- `block-start`, `block-end` — start/end of block axis
+
+### What Does NOT Auto-Mirror
+
+- **`transform: translateX(10px)`** — Physical; does not flip. Use direction multiplier: `translateX(calc(10px * var(--dir, 1)))` with `--dir: -1` for RTL.
+- **`box-shadow`** — Horizontal offset is physical. Use `inset-inline-start` for inset shadows or duplicate rules for RTL.
+- **`background-position`** — `left`, `right` are physical. Use `right` in RTL override or `inline-start`/`inline-end` where supported.
+- **`float`** — `float: left` is physical. Prefer Flexbox/Grid; if using float, override for RTL.
+
+---
+
+## 2. Platform Implementation
+
+### Web: CSS Logical Properties
+
+```css
+/* Margins and padding */
+.container {
+  margin-inline-start: 16px;
+  margin-inline-end: 8px;
+  padding-inline-start: 24px;
+  padding-inline-end: 12px;
+}
+
+/* Borders */
+.card {
+  border-inline-start: 2px solid var(--accent);
+  border-inline-end: none;
+}
+
+/* Position */
+.overlay {
+  position: absolute;
+  inset-inline-start: 0;
+  inset-block-start: 0;
+  width: 100%;
+}
+
+/* Text alignment */
+.text {
+  text-align: start;
+}
+```
+
+### Web: Transform (Manual RTL)
+
+```css
+:root {
+  --slide-offset: -100%;
+}
+
+[dir="rtl"] {
+  --slide-offset: 100%;
+}
+
+.sidebar {
+  transform: translateX(var(--slide-offset));
+}
+```
+
+Or with a direction variable:
+```css
+[dir="rtl"] {
+  --dir: -1;
+}
+
+.element {
+  transform: translateX(calc(20px * var(--dir, 1)));
+}
+```
+
+### Web: Flexbox
+
+Flexbox is **logical by default** when `dir` is set on a parent:
+- `flex-direction: row` — Main axis follows writing direction (LTR: left→right; RTL: right→left)
+- `justify-content: flex-start` — Start of main axis
+- `align-items: flex-start` — Start of cross axis
+
+**Do NOT use `row-reverse` for RTL.** The `dir` attribute handles it. Use `flex-start`/`flex-end`, not `left`/`right`.
+
+### Web: CSS Grid
+
+```css
+.grid {
+  display: grid;
+  grid-template-columns: 1fr 2fr 1fr;
+  /* Columns flow inline; RTL flips column order automatically when dir="rtl" */
+}
+
+/* Use logical values for placement */
+.item {
+  grid-column: 1 / 2; /* Still numeric; column order flips with dir */
+}
+```
+
+For `grid-column-start`/`end`, use `inline-start`/`inline-end` where supported, or rely on `dir` to flip the grid.
+
+### Flutter: Directional Classes
+
+```dart
+// Padding
+Padding(
+  padding: EdgeInsetsDirectional.only(start: 16, end: 8, top: 12, bottom: 12),
+  child: child,
+)
+
+// Alignment
+Align(
+  alignment: AlignmentDirectional.centerStart,
+  child: child,
+)
+
+// EdgeInsets for symmetric
+EdgeInsetsDirectional.symmetric(horizontal: 16)
+
+// Positioned (in Stack)
+Positioned.directional(
+  textDirection: Directionality.of(context),
+  start: 0,
+  end: 0,
+  top: 0,
+  child: child,
+)
+```
+
+**Avoid:** `EdgeInsets.only(left: 16)`, `Alignment.centerLeft` — use directional equivalents.
+
+### Flutter: Row and ListView
+
+`Row` and `ListView` (horizontal) automatically reverse child order when `Directionality` is RTL. No extra code if you use `MainAxisAlignment.start` and directional padding.
+
+### iOS: Auto Layout
+
+- Use **leading** and **trailing** constraints, never left/right for layout
+- `NSLayoutConstraint` with `leadingAnchor`/`trailingAnchor`
+- `UIView.semanticContentAttribute = .forceRightToLeft` for RTL
+
+### Android: Layout XML
+
+```xml
+<LinearLayout
+  android:layoutDirection="locale"
+  ...>
+  <TextView
+    android:layout_marginStart="16dp"
+    android:layout_marginEnd="8dp"
+    ... />
+</LinearLayout>
+```
+
+Use `layout_marginStart`/`End`, `paddingStart`/`End`, `layout_gravity="start"`/`"end"`.
+
+---
+
+## 3. Visual Examples (Described in Detail)
+
+### Sidebar Drawer
+
+- **LTR:** Drawer slides in from the left. `transform: translateX(-100%)` when closed.
+- **RTL:** Drawer slides in from the right. `transform: translateX(100%)` when closed. The drawer is on the "start" side; in RTL, start is right.
+
+### Card with Leading Icon
+
+- **LTR:** `[Icon] Title` — icon at inline-start.
+- **RTL:** `Title [Icon]` — icon still at inline-start (now right). Use `margin-inline-start` on the title so spacing is correct.
+
+### List Item with Trailing Chevron
+
+- **LTR:** `Item text                    [>]` — chevron at end.
+- **RTL:** `[<]                    Item text` — chevron at end (now left). Chevron may need to mirror (point left in RTL = "more" in reading direction).
+
+### Progress Bar
+
+- **LTR:** Fills from left. `width: 60%` or `transform: scaleX(0.6)` with `transform-origin: left`.
+- **RTL:** Fills from right. `transform-origin: right` in RTL, or use logical: `inset-inline-start: 0` and `width` from start.
+
+---
+
+## 4. Common RTL Layout Bugs
+
+1. **Transform not mirroring** — `translateX` is physical. Use direction multiplier or separate RTL rule.
+2. **Shadow offset** — `box-shadow: 4px 0 8px` — 4px is to the right in LTR; in RTL it should be to the left. Override or use logical equivalent.
+3. **Gradient direction** — `linear-gradient(to right, ...)` — "right" is physical. Use `to inline-end` or `to left` in RTL override.
+4. **Absolute positioning** — `left: 0`; use `inset-inline-start: 0`.
+5. **Border radius** — `border-top-left-radius`; use `border-start-start-radius` for asymmetric corners.
+6. **Flexbox with `margin-left: auto`** — Physical. Use `margin-inline-start: auto`.
+7. **Float** — `float: left`; use `float: inline-start` or Flexbox.
+8. **Scrollbar position** — Horizontal scroll in RTL: scrollbar may be on the right; ensure overflow and scroll behavior are correct.
+9. **Fixed/sticky elements** — `position: fixed; left: 0`; use `inset-inline-start: 0`.
+
+---
+
+## 5. QA Checklist
+
+- [ ] All margins/padding use logical properties
+- [ ] Transforms use direction multiplier or RTL override
+- [ ] Flexbox uses flex-start/flex-end, not left/right
+- [ ] Absolute/fixed positioning uses inset-inline-*
+- [ ] Borders and border-radius use logical where asymmetric
+- [ ] Shadows and gradients checked in RTL
+- [ ] Sidebar/drawer slides from correct edge
+- [ ] Progress bar fills from start
+- [ ] List items and cards lay out correctly
+
+---
+
+## Quick Reference Checklist
+
+- [ ] Replace `left`/`right` with `inline-start`/`inline-end`
+- [ ] Replace `margin-left`/`margin-right` with `margin-inline-*`
+- [ ] Replace `padding-left`/`padding-right` with `padding-inline-*`
+- [ ] Use `EdgeInsetsDirectional` in Flutter
+- [ ] Use leading/trailing in iOS Auto Layout
+- [ ] Use start/end in Android XML
+- [ ] Handle `translateX` manually for RTL
+- [ ] Verify shadows, gradients, and transforms in RTL
+
+---
+*Researched: 2026-03-08 | Sources: MDN logical properties, CSS-Tricks multi-directional layouts, Flutter Directionality docs, Firefox RTL guidelines*

package/expertise/i18n/rtl/rtl-navigation-and-gestures.md

@@ -0,0 +1,107 @@
+# RTL Navigation and Gestures — i18n/RTL Expertise Module
+
+> Navigation and gestures must follow reading direction: swipe-back from the right edge in RTL, tab order from right to left, carousels and steppers reversed. Wrong gesture direction is disorienting.
+
+> **Category:** RTL
+> **Applies to:** Mobile, Web
+> **Key standards:** Material Design, Apple HIG
+> **RTL impact:** Critical — navigation is core to UX
+
+## 1. The Rules
+
+### Swipe-Back Gesture
+
+| Context | LTR | RTL |
+|---------|-----|-----|
+| **Back navigation** | Swipe from left edge → right | Swipe from right edge → left |
+| **Rationale** | "Back" = toward start (left) | "Back" = toward start (right) |
+
+In RTL, the user "came from" the right. Swiping right-to-left dismisses the current screen and returns to the previous one.
+
+### Carousel / Horizontal Scroll
+
+| Context | LTR | RTL |
+|---------|-----|-----|
+| **Scroll direction** | Swipe left to see "next" | Swipe right to see "next" |
+| **Initial position** | Content starts at left | Content starts at right |
+| **"More" content** | To the right | To the left |
+
+### Tab Bar / Bottom Navigation
+
+- **LTR:** First tab on left
+- **RTL:** First tab on right
+- Tab order follows visual order (start → end)
+
+### Focus Order
+
+- **LTR:** Tab order left → right, top → bottom
+- **RTL:** Tab order right → left, top → bottom
+- Ensure focus follows visual layout
+
+---
+
+## 2. Platform Implementation
+
+### iOS
+
+- **Swipe-back:** iOS automatically inverts when `userInterfaceLayoutDirection` is RTL
+- **Edge swipe:** From the leading edge (right in RTL)
+- **UINavigationController:** Handles RTL by default with base internationalization
+
+### Android
+
+- **Back gesture:** From the start edge (right in RTL)
+- **Navigation component:** Uses `layoutDirection`; gestures follow
+- **ViewPager:** Set `layoutDirection` or use `ViewPager2` with RTL support
+
+### Flutter
+
+- **CupertinoPageRoute:** Swipe-back direction follows `Directionality`
+- **PageView:** Horizontal scroll direction flips with `TextDirection.rtl`
+- **TabBar:** Tab order reverses automatically
+
+### React Navigation
+
+- RTL swipe-back fixed in later versions; ensure `gestureDirection` is not overridden incorrectly
+- Use `gestureDirection: 'inverted'` only when framework doesn't auto-detect RTL
+
+### Web (Carousel / Swiper)
+
+- Set `dir="rtl"` on container; many libraries (Swiper, etc.) respect it
+- If not: `rtl: true` or equivalent option
+- Verify "next" swipe goes the correct direction
+
+---
+
+## 3. Common RTL Navigation Bugs
+
+1. **Swipe-back from wrong edge** — User swipes left (LTR habit) but nothing happens; back is from right in RTL
+2. **Carousel "next" goes wrong way** — Swiping "forward" feels backward
+3. **Tab order wrong** — Focus jumps left when it should go right
+4. **Horizontal scroll starts wrong** — Content appears to start from wrong side
+5. **Stepper/wizard arrows wrong** — Progress direction doesn't match layout
+6. **Drawer opens from wrong side** — Should open from start (right in RTL)
+
+---
+
+## 4. QA Checklist
+
+- [ ] Swipe-back from correct edge (right in RTL)
+- [ ] Carousel/horizontal scroll direction correct
+- [ ] Tab bar order follows visual order
+- [ ] Focus order follows visual order
+- [ ] Drawer/sidebar opens from start edge
+- [ ] "Next" and "Previous" buttons in correct positions
+
+---
+
+## Quick Reference Checklist
+
+- [ ] Back gesture from start edge (right in RTL)
+- [ ] Carousel next/previous follow reading direction
+- [ ] Tab order = visual order
+- [ ] Focus order = visual order
+- [ ] Test swipe gestures in RTL
+
+---
+*Researched: 2026-03-08 | Sources: React Navigation RTL, iOS/Flutter RTL, Material Design*

package/expertise/i18n/rtl/rtl-testing-and-qa.md

@@ -0,0 +1,147 @@
+# RTL Testing and QA — i18n/RTL Expertise Module
+
+> How to verify RTL correctness: pseudo-localization, manual checklists, automated checks, and real-locale testing. Catch layout, icon, gesture, and BiDi bugs before release.
+
+> **Category:** RTL
+> **Applies to:** Mobile, Web
+> **Key standards:** W3C, Material Design
+> **RTL impact:** Critical — RTL bugs ship without dedicated QA
+
+## 1. Pseudo-Localization for RTL
+
+### Purpose
+
+- Simulate RTL without translators
+- Expose layout, truncation, and hardcoded-string issues early
+
+### Android Pseudolocales
+
+- **en-XA** — Accented Latin, text expansion
+- **ar-XB** — Reversed text direction (RTL simulation)
+
+### Web / General
+
+- Use `dir="rtl"` with pseudo-translated content
+- Wrap strings with Unicode RLI/PDI or use `dir="rtl"` on test locale
+- Tools: pseudo-l10n npm package, custom scripts
+
+### What to Look For
+
+- Layout mirroring (or lack of it)
+- Truncated text
+- Overlapping elements
+- Icons that should mirror but don't
+- Hardcoded strings (remain in source language)
+
+---
+
+## 2. Manual QA Checklist (20–30 Items)
+
+### Layout
+
+- [ ] Navigation/tabs ordered start→end (right→left in RTL)
+- [ ] Sidebar/drawer on start side (right in RTL)
+- [ ] Content flows from start
+- [ ] No horizontal overflow or clipping
+- [ ] Margins/padding correct (logical properties)
+
+### Text
+
+- [ ] Text aligns to start
+- [ ] Mixed content (Arabic + English) displays correctly
+- [ ] Numbers, URLs, email in correct direction
+- [ ] Truncation/ellipsis at inline-end
+- [ ] Line breaks and wrapping correct
+
+### Icons and Images
+
+- [ ] Back/forward arrows mirror
+- [ ] Chevrons mirror where directional
+- [ ] Checkmark, play, settings do NOT mirror
+- [ ] Logos and photos do NOT mirror
+- [ ] Icon position uses start/end
+
+### Navigation and Gestures
+
+- [ ] Swipe-back from correct edge (right in RTL)
+- [ ] Carousel/horizontal scroll direction correct
+- [ ] Tab order follows visual order
+- [ ] Focus order correct
+
+### Forms
+
+- [ ] Labels at start of input
+- [ ] Input text aligns to start
+- [ ] Leading/trailing icons in correct positions
+- [ ] Validation messages positioned correctly
+
+### Animations
+
+- [ ] Drawer slides from start edge
+- [ ] Page transitions follow direction
+- [ ] No "wrong way" slide animations
+
+### Edge Cases
+
+- [ ] Empty states
+- [ ] Long text (e.g., German)
+- [ ] Mixed LTR/RTL in same view
+- [ ] Dynamic content (user names, search results)
+
+---
+
+## 3. Real Locale Testing
+
+### Arabic (ar-SA, ar-EG)
+
+- Real text: مرحباً، كيف حالك؟
+- Eastern Arabic numerals (٠١٢٣) where applicable
+- Hijri calendar if used
+
+### Hebrew (he-IL)
+
+- Real text: שלום, עברית
+- Western numerals
+- Hebrew calendar if used
+
+### Why Real Text
+
+- BiDi algorithm behaves differently with real script
+- Font rendering, line breaks, and shaping differ from pseudo
+
+---
+
+## 4. Automated Checks
+
+- **Lint:** Flag `margin-left`, `padding-right`, `text-align: left` in styles
+- **CI:** Run with `dir="rtl"` or RTL locale; snapshot or visual regression
+- **Accessibility:** Screen reader with RTL; focus order
+- **Unit tests:** Direction-dependent logic (e.g., transform, layout direction)
+
+---
+
+## 5. Common RTL Bugs to Catch
+
+1. Physical properties instead of logical
+2. Icons that should mirror but don't (or vice versa)
+3. Swipe-back from wrong edge
+4. Drawer from wrong side
+5. Transform/translate not inverted
+6. Form labels on wrong side
+7. Mixed content BiDi spillover
+8. Truncation at wrong edge
+9. Shadow/gradient not mirrored where needed
+10. Tab/focus order wrong
+
+---
+
+## Quick Reference Checklist
+
+- [ ] Pseudo-localization (ar-XB or dir=rtl) in CI
+- [ ] Manual checklist for layout, text, icons, navigation, forms
+- [ ] Test with real Arabic and Hebrew
+- [ ] Automated lint for physical properties
+- [ ] Verify swipe gestures and animations
+
+---
+*Researched: 2026-03-08 | Sources: Android pseudolocales, L10n pseudo-localization, Ubertesters RTL testing*

package/expertise/i18n/rtl/rtl-typography.md

@@ -0,0 +1,160 @@
+# RTL Typography — i18n/RTL Expertise Module
+
+> Typography for RTL scripts: font selection, line height, letter spacing, and script-specific considerations. Arabic and Hebrew have different requirements—connected cursive vs discrete letters, diacritics, and rendering complexity.
+
+> **Category:** RTL
+> **Applies to:** Mobile, Web
+> **Key standards:** OpenType, W3C typography
+> **RTL impact:** Critical — poor typography makes RTL content unreadable
+
+## 1. The Rules
+
+### Arabic vs Hebrew: Key Differences
+
+| Aspect | Arabic | Hebrew |
+|--------|--------|--------|
+| **Script type** | Cursive (connected) | Mostly discrete (some connections) |
+| **Letter forms** | Initial, medial, final, isolated | Positional variants, final forms |
+| **Ligatures** | Many; words can act as single units | Fewer |
+| **Diacritics** | Harakat (short vowels), dots | Niqqud, cantillation |
+| **Font requirements** | OpenType shaping, contextual alternates | OpenType shaping |
+| **Baseline** | Varies with letter height | More uniform |
+
+### Font Size and Line Height
+
+- **Arabic body text:** 14–18px minimum; many sites use 12–16px (below ideal)
+- **Line height:** 1.5–1.75 for body; Arabic's ascenders/descenders need room
+- **Hebrew:** Similar range; ensure diacritics (niqqud) don't collide with adjacent lines
+
+### Logical Properties for Typography
+
+- `text-align: start` — Not `left`
+- `text-indent` — Use `text-indent: 2em` (block direction) or logical equivalent
+- `letter-spacing` — Use sparingly; Arabic/Hebrew have different norms than Latin
+
+---
+
+## 2. Arabic-Specific Typography
+
+### Connected Script
+
+Arabic letters connect within words. Each letter has up to 4 forms: isolated, initial, medial, final. The font must support **OpenType contextual alternates** and **shaping** (e.g., HarfBuzz, Uniscribe).
+
+### Diacritical Marks (Harakat)
+
+- Short vowels (fatḥa, kasra, ḍamma) and other marks sit above/below letters
+- Require sufficient line height to avoid clipping
+- Some fonts render them better than others
+
+### Font Recommendations
+
+- **Body:** Tahoma, Arial (system), Noto Sans Arabic, IBM Plex Sans Arabic
+- **Headlines:** Amiri, Lateef, Noto Kufi Arabic, Droid Arabic Kufi
+- **Display:** Avoid overly decorative fonts for UI; reserve for marketing
+
+### Common Pitfalls
+
+1. **Font without Arabic support** — Fallback to system font; ensure `font-family` includes Arabic-capable fonts
+2. **Insufficient line height** — Diacritics get clipped
+3. **Letter-spacing** — Arabic typically uses minimal or no letter-spacing; adding it can break connections
+4. **Small font size** — Below 14px, connected letters blur; diacritics become illegible
+
+---
+
+## 3. Hebrew-Specific Typography
+
+### Script Characteristics
+
+- 22 consonants; optional vowel points (niqqud)
+- Final forms for 5 letters (kaf, mem, nun, pe, tsadi)
+- Rashi script for religious commentary (different glyph set)
+
+### Font Recommendations
+
+- **Body:** Heebo, Noto Sans Hebrew, Arial (system)
+- **Religious/formal:** Noto Rashi Hebrew, Frank Ruhl Libre
+- **Display:** Heebo, Rubik
+
+### Niqqud (Vowel Points)
+
+- Placed above/below letters; need line height headroom
+- Optional in modern Hebrew; often omitted in UI
+
+---
+
+## 4. Platform Implementation
+
+### Web: Font Stack
+
+```css
+:root {
+  --font-arabic: 'Noto Sans Arabic', 'Tahoma', 'Arial', sans-serif;
+  --font-hebrew: 'Heebo', 'Noto Sans Hebrew', 'Arial', sans-serif;
+}
+
+[lang="ar"] {
+  font-family: var(--font-arabic);
+  line-height: 1.6;
+  font-size: 1rem; /* 16px minimum for body */
+}
+```
+
+### Web: Font Loading
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link href="https://fonts.googleapis.com/css2?family=Noto+Sans+Arabic:wght@400;600;700&display=swap" rel="stylesheet">
+```
+
+### Flutter
+
+```dart
+// In theme or TextStyle
+TextStyle(
+  fontFamily: 'NotoSansArabic',
+  fontSize: 16,
+  height: 1.6,
+)
+```
+
+### iOS / Android
+
+- Use system fonts that support Arabic/Hebrew (San Francisco, Roboto)
+- Or bundle Noto Sans Arabic / Heebo
+
+---
+
+## 5. Mixed Script Typography
+
+When mixing Arabic/Hebrew with Latin (e.g., brand names, technical terms):
+
+- Ensure both scripts have compatible x-height and weight
+- Noto family provides matching Latin + Arabic + Hebrew
+- Avoid font switching mid-sentence when possible
+
+---
+
+## 6. Anti-Patterns
+
+1. **Letter-spacing on Arabic** — Breaks cursive connections
+2. **Font size below 14px for body** — Illegible diacritics
+3. **Line height < 1.5** — Diacritics collide
+4. **Font without OpenType shaping** — Wrong letter forms
+5. **Using Latin font for Arabic** — Missing glyphs, replacement characters
+6. **text-transform: uppercase** — Arabic has no case; can break
+7. **word-spacing** — Arabic uses different word-boundary rules
+
+---
+
+## Quick Reference Checklist
+
+- [ ] Font supports Arabic/Hebrew (OpenType shaping)
+- [ ] Body font size ≥ 14px (16px preferred)
+- [ ] Line height 1.5–1.75 for body
+- [ ] No letter-spacing on Arabic
+- [ ] text-align: start
+- [ ] Test with real text: العربية، עברית
+- [ ] Diacritics not clipped
+
+---
+*Researched: 2026-03-08 | Sources: Code Guru Arabic fonts, HackerNoon Arabic design, Noto fonts, OpenType shaping*