first commit

docs/localization/i18n/i18n-formatter-date/src/helpers/helpers.md

@@ -0,0 +1,91 @@
+# Date helpers — `formatTime`, `formatDateOnly`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`formatTime` and `formatDateOnly` pre-bind `formatDate` with the
+appropriate preset for time-only or date-only rendering. They exist
+because the most common UI patterns ("show just the time", "show just
+the date") shouldn't require the caller to remember the preset
+discriminant string.
+
+## Features
+
+- `formatTime(date, locale, long?)` — pre-binds `time-short` (`long === false`) or `time-long` (`long === true`)
+- `formatDateOnly(date, locale, long?)` — pre-binds `date-short` (`long === false`) or `date-long` (`long === true`)
+- Both default `long` to `false`
+- Both go through the cached `formatDate` path — every advantage of the per-(locale, options-hash) cache and OTel emission applies
+
+## Usage: Basic Example
+
+```ts
+import {
+    formatDateOnly,
+    formatTime,
+} from "@suaveplan/i18n-formatter-date";
+
+const now = new Date(2026, 0, 1, 14, 30, 45);
+
+formatTime(now, "en-GB"); // "14:30"
+formatTime(now, "en-GB", true); // "14:30:45"
+
+formatDateOnly(now, "en-GB"); // "01/01/2026"
+formatDateOnly(now, "en-GB", true); // "1 January 2026"
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    formatDateOnly,
+    formatTime,
+} from "@suaveplan/i18n-formatter-date";
+
+// Render a chat message timestamp — short form by default,
+// long form on hover/expand.
+function renderTimestamp(d: Date, locale: string, expanded: boolean) {
+    const date = formatDateOnly(d, locale, expanded);
+    const time = formatTime(d, locale, expanded);
+    return expanded ? `${date} at ${time}` : `${date} ${time}`;
+}
+
+renderTimestamp(new Date(2026, 5, 15, 9, 5), "en-GB", false);
+// "15/06/2026 09:05"
+
+renderTimestamp(new Date(2026, 5, 15, 9, 5, 30), "en-GB", true);
+// "15 June 2026 at 09:05:30"
+```
+
+## API Reference
+
+### `formatTime(date, locale, long?): string`
+
+Pre-binds `formatDate` with `preset: long ? "time-long" : "time-short"`.
+
+- `date` — a `Date` instance.
+- `locale` — BCP-47 locale tag.
+- `long` — when `true`, includes seconds.
+
+Throws every error class `formatDate` throws.
+
+### `formatDateOnly(date, locale, long?): string`
+
+Pre-binds `formatDate` with `preset: long ? "date-long" : "date-short"`.
+
+- `date` — a `Date` instance.
+- `locale` — BCP-47 locale tag.
+- `long` — when `true`, uses the long month name (e.g. "January"
+  instead of "01").
+
+Throws every error class `formatDate` throws.
+
+## Implementation Notes
+
+- Both helpers are one-line wrappers around `formatDate`. The
+  per-(locale, options-hash) cache shared with `formatDate` and
+  `formatDateRange` covers them automatically.
+- Default of `long = false` matches the monolith behaviour to
+  minimise behavioural drift during the modular split.