first commit

docs/localization/i18n/i18n-detector/src/direction/direction.md

@@ -0,0 +1,78 @@
+# `direction.ts` — text-direction helpers
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`getTextDirection(locale)` and `isRtl(locale)` resolve a locale's
+display direction without instantiating a full locale resolver or
+booting the slim core. They are pure functions over `RTL_LOCALES`
+from `@suaveplan/i18n-shared` and complete in O(1) — perfect for use
+in render hot paths (e.g. `<html dir={getTextDirection(locale)}>`)
+where every microsecond saved compounds across SSR fan-out.
+
+The helpers ship in `@suaveplan/i18n-detector` rather than the slim
+core because direction lookup is logically part of the locale-
+resolution surface — every consumer that detects a locale needs to
+know which direction to render — and pulling them here keeps the
+slim core lighter.
+
+## Features
+
+- `getTextDirection(locale)` returns `"ltr"` or `"rtl"` for any
+  BCP-47 locale tag.
+- `isRtl(locale)` is sugar for `getTextDirection(locale) === "rtl"`.
+- Region subtags are tolerated: `"ar-SA"`, `"he-IL"`, `"fa-IR"` all
+  resolve to `"rtl"`.
+- Lookup is case-insensitive — the language subtag is lower-cased
+  before the `RTL_LOCALES` set probe.
+- Unknown locales default to `"ltr"`, matching browser behaviour.
+
+## Usage: Basic Example
+
+```ts
+import { getTextDirection, isRtl } from "@suaveplan/i18n-detector/direction";
+
+getTextDirection("ar"); // "rtl"
+getTextDirection("ar-SA"); // "rtl"
+getTextDirection("en-GB"); // "ltr"
+isRtl("he-IL"); // true
+```
+
+## Usage: Advanced Example
+
+```tsx
+import { getTextDirection } from "@suaveplan/i18n-detector/direction";
+
+export function HtmlShell({
+    locale,
+    children,
+}: {
+    locale: string;
+    children: React.ReactNode;
+}) {
+    return (
+        <html lang={locale} dir={getTextDirection(locale)}>
+            {children}
+        </html>
+    );
+}
+```
+
+## API Reference
+
+- `getTextDirection(locale: string): "ltr" | "rtl"` — pure.
+- `isRtl(locale: string): boolean` — pure.
+- `type TextDirection = "ltr" | "rtl"` — re-exported for consumer
+  type-safety.
+
+## Implementation Notes
+
+- The language subtag is everything before the first `-`. Multi-tag
+  locales (`zh-Hant-TW`) resolve via the first segment only — script
+  subtags are ignored because every script-bearing RTL locale is
+  already covered by its language subtag.
+- Adding a new RTL language is a one-line change in
+  `@suaveplan/i18n-shared/constants/rtl-locales.ts` — no detector
+  code needs to be touched.