first commit

docs/localization/i18n/i18n-formatter-relative-time/src/helpers/helpers.md

@@ -0,0 +1,73 @@
+# Relative-Time Helper Formatters
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Pre-bound shortcuts over `formatRelativeTime` for the two most common relative-time shapes in product UIs: past-tense ("5 minutes ago") and future-tense ("in 5 minutes"). These are net-new ergonomic helpers introduced by the Wave-3 split — the monolith's `formatting/relative-time/` ships only the class and standalone, while every other Wave-3 formatter carries a sibling helper module.
+
+The helpers route every call through `formatRelativeTime`, so they inherit Zod option validation, the per-`(locale, style, numeric)` cache, and the OTel histogram + cache-hit counter. `selectRelativeUnit` is re-exported from the helpers subpath so callers that import only `@suaveplan/i18n-formatter-relative-time/helpers` for tree-shaking still get the auto-unit-selection function.
+
+## Features
+
+- `formatTimeAgo(ageMs, locale, options?)` — past-tense shortcut that negates internally so callers never have to remember the past = negative convention
+- `formatTimeIn(intervalMs, locale, options?)` — future-tense shortcut that abs-es internally
+- `formatRelativeTimeStyled(deltaMs, locale, style)` — style-only override without an options bag
+- `selectRelativeUnit(deltaMs)` — re-export of the auto-unit-selection helper
+
+## Usage: Basic Example
+
+```typescript
+import {
+    formatRelativeTimeStyled,
+    formatTimeAgo,
+    formatTimeIn,
+    selectRelativeUnit,
+} from "@suaveplan/i18n-formatter-relative-time/helpers";
+
+formatTimeAgo(3_600_000, "en-US"); // → "1 hour ago"
+formatTimeIn(60_000, "en-US");     // → "in 1 minute"
+formatRelativeTimeStyled(86_400_000, "en-US", "short"); // → "in 1 day"
+selectRelativeUnit(90_000);        // → { unit: "minutes", value: 2 }
+```
+
+## Usage: Advanced Example — Activity feed timestamps
+
+```typescript
+import { formatTimeAgo } from "@suaveplan/i18n-formatter-relative-time/helpers";
+
+function renderActivity(events, locale) {
+    return events.map((event) => ({
+        title: event.title,
+        when: formatTimeAgo(Date.now() - event.timestamp, locale, {
+            style: "short",
+        }),
+    }));
+}
+```
+
+## API Reference
+
+### `formatTimeAgo(ageMs, locale, options?)`
+
+Pre-bound shortcut for past-tense relative-time strings. Accepts an absolute (non-negative) age in milliseconds and renders it as "5 seconds ago", "1 hour ago", etc. Negates the input internally so callers never have to remember the past = negative convention of `Intl.RelativeTimeFormat`.
+
+### `formatTimeIn(intervalMs, locale, options?)`
+
+Pre-bound shortcut for future-tense relative-time strings. Accepts a non-negative interval in milliseconds and renders it as "in 5 seconds", "in 1 hour", etc.
+
+### `formatRelativeTimeStyled(deltaMs, locale, style)`
+
+Re-binds the style argument so the caller can skip the options bag for a one-shot style override. Accepts the original signed-delta convention (positive = future, negative = past).
+
+### `selectRelativeUnit(deltaMs)`
+
+Re-export of the formatter's auto-unit-selection helper. Returns `{ unit, value }` so callers can inspect the chosen unit without rendering through `Intl.RelativeTimeFormat`.
+
+## Implementation Notes
+
+`formatTimeAgo` uses `Math.abs(ageMs)` and negates the result before passing to `formatRelativeTime` so callers can pass either a positive duration or the natural `Date.now() - eventTime` form (which can be either sign depending on clock skew) without surprises. The same pattern in `formatTimeIn` ensures the future-tense helper always renders future-tense output even if the caller accidentally supplies a negative value.
+
+`formatRelativeTimeStyled` is intentionally kept as a separate function rather than a default-arg overload of `formatRelativeTime` because the latter would change the standalone helper's call signature, breaking the `formatBridge` design contract that the slim core wires up in Wave 6.