# `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.