@wazir-dev/cli 1.0.0

package/expertise/i18n/rtl/rtl-forms-and-input.md

@@ -0,0 +1,161 @@
+# RTL Forms and Input — i18n/RTL Expertise Module
+
+> Form layout, label placement, input alignment, and validation messages in RTL. Labels at start of input, text alignment follows direction, placeholders and icons positioned correctly.
+
+> **Category:** RTL
+> **Applies to:** Mobile, Web
+> **Key standards:** W3C, Material Design
+> **RTL impact:** Critical — forms are high-frequency touchpoints
+
+## 1. The Rules
+
+### Label Placement
+
+| Layout | LTR | RTL |
+|--------|-----|-----|
+| **Inline (label + input)** | Label left of input | Label right of input |
+| **Top-aligned** | Label above input | Same (no mirror) |
+| **Floating label** | Label at start of input | Label at start (right in RTL) |
+
+**Rule:** Label is always at the **start** of the input (inline axis). In RTL, start = right.
+
+### Input Text Alignment
+
+- **LTR:** `text-align: start` → left
+- **RTL:** `text-align: start` → right
+- **Numbers in input:** May stay LTR (e.g., phone, credit card); use `dir="ltr"` on input if needed
+- **Mixed content:** Use `dir="auto"` for user-generated text
+
+### Input Icons
+
+| Icon position | LTR | RTL |
+|---------------|-----|-----|
+| **Leading (search icon)** | Left of input | Right of input |
+| **Trailing (clear, visibility)** | Right of input | Left of input |
+| **Inside input** | `padding-inline-start` for leading icon space | Same (logical) |
+
+---
+
+## 2. Platform Implementation
+
+### Web (CSS)
+
+```css
+.form-group {
+  display: flex;
+  flex-direction: row;  /* or column for top-aligned */
+  gap: 0.5rem;
+}
+
+label {
+  flex-shrink: 0;
+  /* Inline: label at start; flex order handles it when dir=rtl */
+}
+
+input, textarea {
+  text-align: start;
+  padding-inline-start: 1rem;
+  padding-inline-end: 1rem;
+}
+
+/* Leading icon */
+.input-with-icon {
+  padding-inline-start: 2.5rem;
+}
+.input-with-icon[dir="rtl"] {
+  padding-inline-end: 2.5rem;
+  padding-inline-start: 1rem;
+}
+/* Or use logical: padding-inline-start with icon positioned at start */
+```
+
+### Flutter
+
+```dart
+TextField(
+  textDirection: TextDirection.rtl,  // or from Directionality
+  textAlign: TextAlign.start,
+  decoration: InputDecoration(
+    labelText: '...',
+    // Flutter handles RTL for icon placement when Directionality is set
+    prefixIcon: Icon(Icons.search),  // At start
+    suffixIcon: Icon(Icons.clear),   // At end
+  ),
+)
+```
+
+### Android
+
+```xml
+<EditText
+  android:layoutDirection="locale"
+  android:textAlignment="viewStart"
+  android:gravity="start"
+  ... />
+```
+
+### iOS
+
+- Use leading/trailing constraints for label and input
+- `NSTextAlignment.natural` for text alignment
+- `semanticContentAttribute` for RTL
+
+---
+
+## 3. Special Cases
+
+### Number Inputs
+
+- Phone numbers, credit cards: often LTR
+- Use `dir="ltr"` on the input or `inputmode` + `inputmode="numeric"`
+- Or let `dir="auto"` resolve from first character
+
+### Search Input
+
+- Magnifier icon at start (right in RTL)
+- Clear button at end (left in RTL)
+
+### Validation Messages
+
+- Position at start of input (below or inline)
+- Use logical properties for placement
+
+### Placeholder Text
+
+- `text-align: start` so placeholder aligns with input
+- Placeholder direction follows input `dir`
+
+---
+
+## 4. Anti-Patterns
+
+1. **Label on wrong side** — Using `float: left` or `margin-left`; use logical
+2. **Input text-align: left** — Use `text-align: start`
+3. **Icon padding physical** — `padding-left` for leading icon; use `padding-inline-start`
+4. **Fixed width for label** — Labels vary in length; use flex or min-width
+5. **Validation message position** — Using `left`; use `inline-start`
+
+---
+
+## 5. QA Checklist
+
+- [ ] Labels at start of input
+- [ ] Input text aligns to start
+- [ ] Leading/trailing icons in correct positions
+- [ ] Placeholder aligns with input
+- [ ] Number inputs (phone, etc.) handled (LTR or as needed)
+- [ ] Validation messages at start
+- [ ] Focus ring/outline uses logical inset
+
+---
+
+## Quick Reference Checklist
+
+- [ ] Label at start (right in RTL for inline layout)
+- [ ] `text-align: start` on inputs
+- [ ] Icon padding uses `padding-inline-*`
+- [ ] Test with long labels (e.g., German)
+- [ ] Test number and mixed-content inputs
+
+---
+*Researched: 2026-03-08 | Sources: CSS-Tricks forms, Bootstrap RTL, Stack Overflow RTL forms*

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

@@ -0,0 +1,211 @@
+# RTL Fundamentals — i18n/RTL Expertise Module
+
+> The core rules of right-to-left layout: what mirrors, what doesn't, and why "just flip the layout" is wrong. RTL is a fundamental change in reading direction, interaction patterns, and visual hierarchy—not a CSS transform.
+
+> **Category:** RTL
+> **Applies to:** Mobile, Web
+> **Key standards:** W3C BiDi, Material Design RTL, Apple HIG RTL
+> **RTL impact:** Critical — this is the entry point for all RTL work
+
+## 1. The Rules
+
+### What Mirrors (Layout and Directional Elements)
+
+| Element | LTR | RTL | Why |
+|---------|-----|-----|-----|
+| **Layout flow** | Content starts left, flows right | Content starts right, flows left | Reading direction |
+| **Navigation** | Items ordered left→right | Items ordered right→left | Reading order |
+| **Back arrow** | ← (points left) | → (points right) | "Back" = toward start |
+| **Forward arrow** | → (points right) | ← (points left) | "Forward" = toward end |
+| **Sidebar** | Left side | Right side | Start edge |
+| **Padding/margins** | `padding-left` = start | `padding-inline-start` = start | Logical = auto-mirror |
+| **Text alignment** | `text-align: left` | `text-align: start` | Start = reading start |
+| **Progress bar fill** | Fills left→right | Fills right→left | Direction of progress |
+| **Tabs** | First tab on left | First tab on right | Start edge |
+| **Form labels** | Label left of input | Label right of input | Start-before-end |
+| **Icons with direction** | Back, forward, chevron | Mirrored | Convey direction |
+
+### What Does NOT Mirror
+
+| Element | Reason |
+|---------|--------|
+| **Checkmark (✓)** | No inherent direction; same in all locales |
+| **Play button (▶)** | Represents play action, not reading direction |
+| **Media timeline** | Time flows left→right universally |
+| **Charts and graphs** | X-axis = time/quantity; convention is LTR |
+| **Maps** | Geographic; north is up, east is right |
+| **Clocks** | 12 at top is universal |
+| **Numbers** | 123 stays 123 (Western Arabic numerals) |
+| **Phone numbers** | Always LTR |
+| **URLs, email** | Always LTR |
+| **Brand logos** | Do not mirror |
+| **Music notation** | Universal convention |
+| **Video playhead** | Represents time; moves left→right |
+
+### The #1 Rule: Physical vs Logical
+
+**Physical:** `left`, `right`, `margin-left`, `padding-right` — fixed in space.
+
+**Logical:** `start`, `end`, `inline-start`, `inline-end`, `margin-inline-start` — follow reading direction.
+
+Using logical properties prevents ~60% of RTL bugs. Every layout decision should ask: "Is this physical or logical?"
+
+---
+
+## 2. Visual Examples (Described in Detail)
+
+### Back Arrow
+
+- **LTR:** Back arrow points left (←). User taps to go "back" = toward the start of the navigation stack.
+- **RTL:** Back arrow points right (→). "Back" still means toward the start—but in RTL, start is on the right. The arrow mirrors so it points toward the right edge, where the user "came from."
+
+### Progress Bar
+
+- **LTR:** Bar fills from left to right. Empty on the left, full on the right.
+- **RTL:** Bar fills from right to left. Empty on the right, full on the left. Progress direction follows reading direction.
+
+### Media Playhead
+
+- **LTR and RTL:** Playhead moves left→right. Time is universal; 0:00 is left, end is right. Do NOT mirror.
+
+### List with Leading Icon
+
+- **LTR:** Icon on left, text on right. `[icon] Item text`
+- **RTL:** Icon on right, text on left. `Item text [icon]` — icon stays at the start (which is now right).
+
+### Form: Label + Input
+
+- **LTR:** Label to the left of the input. `Name: [________]`
+- **RTL:** Label to the right of the input. `[________] :Name` — label at start, input at end.
+
+### Mixed Content: "Hello العربية"
+
+- **LTR paragraph:** "Hello" LTR, "العربية" RTL (reversed visually), both in one line.
+- **RTL paragraph:** "العربية" RTL, "Hello" LTR (embedded), order depends on BiDi algorithm.
+
+---
+
+## 3. Platform Implementation
+
+### Web (CSS Logical Properties)
+
+```css
+/* Physical (avoid for layout) */
+margin-left: 16px;
+padding-right: 8px;
+text-align: left;
+
+/* Logical (RTL-safe) */
+margin-inline-start: 16px;
+padding-inline-end: 8px;
+text-align: start;
+```
+
+**Transform that does NOT auto-mirror:**
+```css
+/* BAD: translateX is physical */
+transform: translateX(10px);
+
+/* GOOD: use direction multiplier or logical equivalent */
+transform: translateX(calc(10px * var(--dir, 1))); /* dir = -1 for RTL */
+```
+
+### Flutter
+
+```dart
+// Use Directionality
+Directionality(
+  textDirection: TextDirection.rtl,
+  child: Row(
+    children: [...],
+  ),
+)
+
+// Use EdgeInsetsDirectional, not EdgeInsets
+EdgeInsetsDirectional.only(start: 16, end: 8)
+
+// Icons: Icon with semanticLabel; use RTL-aware icons
+Icon(Icons.arrow_back) // Flutter mirrors automatically when Directionality is RTL
+```
+
+### iOS (Auto Layout)
+
+- Use `leading` and `trailing` constraints, not `left` and `right`
+- `UIView.semanticContentAttribute = .forceRightToLeft` for RTL
+- SF Symbols: many auto-mirror; use `symbolConfiguration` for custom behavior
+
+### Android
+
+- `android:layoutDirection="rtl"` on root or `View`
+- `start`/`end` in XML layouts instead of `left`/`right`
+- `getLayoutDirectionFromLocale()` for system locale
+
+---
+
+## 4. Mixed Content Handling
+
+### LTR Inside RTL
+
+- English brand names, URLs, code: wrap in `dir="ltr"` or equivalent
+- Numbers (Western): often LTR; may need LRM in edge cases
+
+### RTL Inside LTR
+
+- Arabic/Hebrew names in English UI: wrap in `dir="rtl"` or `dir="auto"`
+- Use `<bdi>` when direction is unknown
+
+### Phone Numbers, Email, URLs
+
+- Always LTR; do not mirror
+
+---
+
+## 5. Common RTL Bugs
+
+1. **Shadows and gradients** — `box-shadow` with `left` offset doesn't mirror; use `inset-inline-start` or direction-aware values.
+2. **Swipe gestures** — Swipe-to-go-back: in RTL, "back" swipe should be from the right edge.
+3. **Text alignment** — `text-align: left` on mixed content; use `text-align: start`.
+4. **Padding/margin** — Using `padding-left`; use `padding-inline-start`.
+5. **Icons that should mirror** — Back, forward, chevrons; ensure they flip.
+6. **Icons that shouldn't** — Checkmark, play, share; do not mirror.
+7. **Progress bar** — Filling wrong direction; should fill start→end.
+8. **Transform** — `translateX(10px)` doesn't mirror; use logical or direction multiplier.
+9. **Absolute positioning** — `left: 0`; use `inset-inline-start: 0`.
+10. **Border radius** — `border-top-left-radius`; consider `border-start-start-radius` if asymmetric.
+11. **Flexbox** — `flex-direction: row` is logical; `row-reverse` for RTL is usually wrong—prefer logical props.
+12. **Scroll position** — Horizontal scroll may start from right in RTL.
+13. **Tab order** — Focus order should follow visual order in RTL.
+14. **Truncation** — `text-overflow: ellipsis`; ellipsis should appear at end (inline-end).
+15. **Z-index and overlay** — Overlays from "start" side; in RTL, start is right.
+
+---
+
+## 6. QA Checklist
+
+- [ ] Layout mirrors: navigation, sidebars, tabs
+- [ ] Back/forward arrows mirror
+- [ ] Progress bars fill correct direction
+- [ ] Media timeline and playhead do NOT mirror
+- [ ] Forms: labels at start of input
+- [ ] No physical properties (left/right) for layout
+- [ ] Shadows/gradients correct in RTL
+- [ ] Swipe gestures match direction
+- [ ] Mixed content (Arabic in English, etc.) displays correctly
+- [ ] Phone numbers, URLs, email stay LTR
+- [ ] Focus order follows visual order
+- [ ] Truncation and ellipsis at correct edge
+
+---
+
+## Quick Reference Checklist
+
+- [ ] Use logical properties (start/end, inline-start/end)
+- [ ] Mirror directional icons (back, forward, chevrons)
+- [ ] Do NOT mirror: play, checkmark, media timeline, maps, numbers
+- [ ] Progress bar fills start→end
+- [ ] Test with real Arabic (العربية) and Hebrew (עברית)
+- [ ] Verify shadows, transforms, and absolute positioning
+- [ ] Swipe gestures match RTL expectations
+
+---
+*Researched: 2026-03-08 | Sources: W3C BiDi, Material Design RTL, Apple HIG RTL, MDN logical properties, RTL guidelines (GitHub)*

package/expertise/i18n/rtl/rtl-icons-and-images.md

@@ -0,0 +1,181 @@
+# RTL Icons and Images — i18n/RTL Expertise Module
+
+> Which icons and images mirror in RTL, and which don't. Directional elements (arrows, chevrons, progress) flip; content (photos, logos, checkmarks) stays. Platform APIs and implementation patterns.
+
+> **Category:** RTL
+> **Applies to:** Mobile, Web
+> **Key standards:** Material Design RTL, Apple HIG
+> **RTL impact:** Critical — wrong icon direction confuses users
+
+## 1. The Rules
+
+### Icons That MIRROR (Directional)
+
+| Icon | LTR | RTL | Why |
+|------|-----|-----|-----|
+| Back/previous | ← | → | "Back" = toward start; start is right in RTL |
+| Forward/next | → | ← | "Forward" = toward end |
+| Chevron (expand/collapse) | > | < | Points to content; content moves |
+| Caret (dropdown) | ▼ or > | Same or mirrored | Depends on placement |
+| Text alignment left | ∟ | Mirrored | Aligns with "start" |
+| Text alignment right | ⊣ | Mirrored | Aligns with "end" |
+| Indent/outdent | Directional | Mirrored | Text flow direction |
+| List bullet/arrow | → | ← | Indicates flow |
+| Progress/stepper arrow | → | ← | Direction of progress |
+| Sidebar expand | > | < | Expand toward content |
+
+### Icons That Do NOT Mirror
+
+| Icon | Reason |
+|------|--------|
+| Checkmark (✓) | No inherent direction |
+| Play (▶) | Universal "play" symbol |
+| Pause (⏸) | No direction |
+| Stop (⏹) | No direction |
+| Camera | No direction |
+| Settings (gear) | No direction |
+| Search (magnifier) | No direction |
+| Heart, star, bookmark | No direction |
+| Share | No direction (unless arrow indicates target) |
+| Trash/delete | No direction |
+| Edit (pencil) | No direction |
+| Lock, key | No direction |
+
+### Images: Mirror or Not?
+
+| Type | Mirror? | Examples |
+|------|---------|----------|
+| **Photos** | No | User avatars, product images |
+| **Logos** | No | Brand identity |
+| **Maps** | No | Geographic |
+| **Charts/graphs** | No | Data visualization |
+| **Illustrations with direction** | Yes | Person pointing, arrow in illustration |
+| **UI controls (custom)** | Depends | If directional, mirror |
+
+---
+
+## 2. Platform Implementation
+
+### Web (CSS)
+
+```css
+/* Manual mirror for directional icons */
+[dir="rtl"] .icon-back {
+  transform: scaleX(-1);
+}
+
+/* Or use dir attribute on icon container */
+.icon-back {
+  transform: scaleX(var(--dir, 1));
+}
+[dir="rtl"] {
+  --dir: -1;
+}
+```
+
+### Flutter
+
+```dart
+// Flutter mirrors many directional icons automatically when Directionality is RTL
+Icon(Icons.arrow_back)  // Auto-mirrors
+
+// Manual mirror when needed
+Transform(
+  alignment: Alignment.center,
+  transform: Matrix4.identity()..scale(-1.0, 1.0),
+  child: Icon(Icons.arrow_forward),
+)
+```
+
+### Android (Jetpack Compose)
+
+```kotlin
+// AutoMirrored icons flip automatically
+Icon(Icons.AutoMirrored.Filled.ArrowBack)
+
+// Manual for custom drawables
+Icon(
+  painter = painterResource(R.drawable.arrow_back),
+  contentDescription = "...",
+  modifier = Modifier.graphicsLayer {
+    scaleX = if (LocalLayoutDirection.current == LayoutDirection.Rtl) -1f else 1f
+  }
+)
+```
+
+### Android (XML)
+
+```xml
+<ImageView
+  android:autoMirrored="true"
+  android:src="@drawable/ic_arrow_back" />
+```
+
+### iOS
+
+```swift
+// SF Symbols: many auto-mirror with semanticContentAttribute
+imageView.image = UIImage(systemName: "chevron.left")
+imageView.semanticContentAttribute = .forceRightToLeftLayoutDirection
+
+// Or: imageFlippedForRightToLeftLayoutDirection()
+```
+
+---
+
+## 3. Visual Examples (Described in Detail)
+
+### Back Button
+
+- **LTR:** Arrow points left (←). User taps to go "back" = toward the start of the navigation stack (left).
+- **RTL:** Arrow points right (→). "Back" = toward start, which is now on the right. Icon mirrors.
+
+### Chevron in List Item
+
+- **LTR:** Chevron (>) on the right indicates "more content to the right."
+- **RTL:** Chevron (<) on the left indicates "more content to the left." Icon mirrors.
+
+### Play Button in Media Player
+
+- **LTR and RTL:** Play (▶) does NOT mirror. "Play" is a universal action; the triangle direction is not reading-direction-dependent.
+
+### Progress Stepper
+
+- **LTR:** Steps flow left → right. Arrow between steps points right.
+- **RTL:** Steps flow right → left. Arrow between steps points left. Arrows mirror.
+
+---
+
+## 4. Common RTL Icon Bugs
+
+1. **Back arrow doesn't mirror** — User expects it to point toward "back" (start)
+2. **Chevron doesn't mirror** — Points wrong way for "more" or "expand"
+3. **Checkmark mirrored** — Wrong; checkmark has no direction
+4. **Play button mirrored** — Wrong; play is universal
+5. **Share icon mirrored** — Usually wrong unless it's an arrow indicating direction
+6. **Custom SVG not mirroring** — Add `transform: scaleX(-1)` for directional icons in RTL
+7. **Icon in wrong position** — Use logical properties for placement; icon asset may still need mirror
+
+---
+
+## 5. QA Checklist
+
+- [ ] Back/forward arrows mirror
+- [ ] Chevrons mirror where they indicate direction
+- [ ] Checkmark, play, settings do NOT mirror
+- [ ] Logos and photos do NOT mirror
+- [ ] Custom directional icons have RTL variant or transform
+- [ ] Icon position uses start/end, not left/right
+
+---
+
+## Quick Reference Checklist
+
+- [ ] Mirror: back, forward, chevrons, alignment icons, progress arrows
+- [ ] Do NOT mirror: checkmark, play, pause, camera, settings, logos, photos
+- [ ] Use platform auto-mirror APIs when available (Flutter, Compose AutoMirrored)
+- [ ] Manual `scaleX(-1)` or equivalent for custom directional icons
+- [ ] Test all icon types in RTL
+
+---
+*Researched: 2026-03-08 | Sources: Material Design bidirectionality, Android AutoMirrored, Qt RTL docs*