@tuwaio/docs-ui 0.5.3 → 0.5.5

package/dist/locale.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Locale primitives shared by the TUWA sites (docs hub, website, Quasar dashboard). Pure functions without React and
+ * without a `'use client'` directive, so server code (metadata, sitemaps) can call them too.
+ *
+ * Privacy: the locale is resolved from signals the browser already has (Local Storage, `navigator.languages`, the
+ * time zone). No GeoIP lookup, no cookie and no request is ever made.
+ */
+/** A locale of the TUWA sites. */
+type TuwaLocale = 'en' | 'uk' | 'zh-CN';
+/** Every supported locale, the default first. */
+declare const TUWA_LOCALES: readonly TuwaLocale[];
+/** The locale used on the server and when nothing else matches. */
+declare const DEFAULT_LOCALE: TuwaLocale;
+/**
+ * Local Storage key of the locale the visitor picked. Shared by every TUWA site, so a choice on one origin of the same
+ * site is kept; list it in `PreferenceExpiry` to forget it after 30 days (Cookie Policy).
+ */
+declare const LOCALE_STORAGE_KEY = "tuwa-locale";
+/**
+ * Maps a language tag or a stored value to a supported locale.
+ *
+ * @param tag - A BCP 47 tag (`uk-UA`, `zh-Hans`, `en-US`), a region alias (`ua`) or a stored value.
+ * @returns The matching {@link TuwaLocale}, or `null` when the tag names none.
+ */
+declare function normalizeLocale(tag: string | null | undefined): TuwaLocale | null;
+/**
+ * Browser signals read by {@link detectLocale}. Each is optional, so tests and server code can pass what they have.
+ */
+interface LocaleSignals {
+    /** The locale saved under {@link LOCALE_STORAGE_KEY}. */
+    stored?: string | null;
+    /** `navigator.languages`, or `[navigator.language]`. */
+    languages?: readonly string[];
+    /** IANA time zone, `Intl.DateTimeFormat().resolvedOptions().timeZone`. */
+    timeZone?: string;
+    /** Locale of the system, `Intl.DateTimeFormat().resolvedOptions().locale`. */
+    systemLocale?: string;
+    /** Offset of January 1 in minutes, `new Date(year, 0, 1).getTimezoneOffset()`. */
+    januaryOffset?: number;
+    /** Offset of July 1 in minutes, `new Date(year, 6, 1).getTimezoneOffset()`. */
+    julyOffset?: number;
+}
+/**
+ * Picks the locale from browser signals, in this order:
+ * 1. The locale the visitor picked (`stored`).
+ * 2. Ukrainian or Simplified Chinese in the browser languages, in the order the visitor ranked them.
+ * 3. A Ukrainian time zone, or a language or system locale with the region Ukraine (`ru-UA`, `en-UA`).
+ * 4. A mainland China time zone or system locale.
+ * 5. Russian with a masked time zone (UTC) and the Eastern European offsets (UTC+2 in winter, UTC+3 in summer).
+ * 6. English.
+ *
+ * @param signals - What the browser exposes.
+ * @returns The resolved {@link TuwaLocale}.
+ */
+declare function detectLocale(signals: LocaleSignals): TuwaLocale;
+/**
+ * Reads the browser signals and resolves the locale with {@link detectLocale}. Returns {@link DEFAULT_LOCALE} on the
+ * server. Never throws: blocked storage or a missing `Intl` only drop that signal.
+ *
+ * @param storageKey - Local Storage key of the picked locale (default: {@link LOCALE_STORAGE_KEY}).
+ * @returns The resolved {@link TuwaLocale}.
+ */
+declare function resolveClientLocale(storageKey?: string): TuwaLocale;
+/**
+ * Replaces `{name}` tokens of a template with values, as the labels of Nova UI Kit do. Unknown tokens stay.
+ *
+ * @param template - Text with `{name}` tokens.
+ * @param values - Values by token name.
+ * @returns The text with the values in place.
+ */
+declare function formatLabel(template: string, values: Record<string, string | number>): string;
+/**
+ * The language of the TUWA policies for a site locale: policies exist in English and Ukrainian only.
+ *
+ * @param locale - The site locale.
+ * @returns `uk` for Ukrainian, `en` otherwise.
+ */
+declare function policyLanguageOf(locale: TuwaLocale): 'en' | 'uk';
+
+export { DEFAULT_LOCALE, LOCALE_STORAGE_KEY, TUWA_LOCALES, detectLocale, formatLabel, normalizeLocale, policyLanguageOf, resolveClientLocale };
+export type { LocaleSignals, TuwaLocale };

package/dist/locale.js

@@ -0,0 +1,100 @@
+const TUWA_LOCALES = ["en", "uk", "zh-CN"];
+const DEFAULT_LOCALE = "en";
+const LOCALE_STORAGE_KEY = "tuwa-locale";
+const UKRAINE_TIMEZONES = /* @__PURE__ */ new Set([
+  "europe/kyiv",
+  "europe/kiev",
+  "europe/uzhgorod",
+  "europe/zaporozhye",
+  "europe/simferopol"
+]);
+const CHINA_TIMEZONES = /* @__PURE__ */ new Set([
+  "asia/shanghai",
+  "asia/chongqing",
+  "asia/harbin",
+  "asia/urumqi",
+  "asia/beijing",
+  "prc"
+]);
+const MASKED_TIMEZONES = /* @__PURE__ */ new Set(["", "utc", "gmt", "etc/utc", "etc/gmt"]);
+function hasUkraineRegion(tag) {
+  return /(?:^|[-_])ua(?:$|[-_])/.test(tag);
+}
+function isSimplifiedChinese(tag) {
+  if (tag === "zh" || tag === "zh-cn" || tag === "zh_cn" || tag.startsWith("zh-hans") || tag.startsWith("zh_hans")) {
+    return true;
+  }
+  return tag.startsWith("zh-") && !/hant|tw|hk|mo/.test(tag);
+}
+function normalizeLocale(tag) {
+  if (!tag) return null;
+  const lower = tag.trim().toLowerCase();
+  if (!lower) return null;
+  if (lower === "uk" || lower === "ua" || lower.startsWith("uk-") || lower.startsWith("uk_")) return "uk";
+  if (isSimplifiedChinese(lower)) return "zh-CN";
+  if (lower === "en" || lower.startsWith("en-") || lower.startsWith("en_")) return "en";
+  return null;
+}
+function detectLocale(signals) {
+  const stored = normalizeLocale(signals.stored);
+  if (stored) return stored;
+  const languages = (signals.languages ?? []).map((tag) => tag.trim().toLowerCase()).filter(Boolean);
+  for (const tag of languages) {
+    const locale = normalizeLocale(tag);
+    if (locale === "uk" || locale === "zh-CN") return locale;
+    if (locale === "en" && !hasUkraineRegion(tag)) break;
+  }
+  const timeZone = (signals.timeZone ?? "").trim().toLowerCase();
+  const systemLocale = (signals.systemLocale ?? "").trim().toLowerCase();
+  const explicitEnglish = languages.some((tag) => normalizeLocale(tag) === "en" && !hasUkraineRegion(tag));
+  if (UKRAINE_TIMEZONES.has(timeZone) || hasUkraineRegion(systemLocale) || languages.some(hasUkraineRegion)) {
+    return "uk";
+  }
+  if (CHINA_TIMEZONES.has(timeZone) || systemLocale && isSimplifiedChinese(systemLocale)) {
+    return "zh-CN";
+  }
+  if (!explicitEnglish && MASKED_TIMEZONES.has(timeZone) && languages.some((tag) => tag === "ru" || tag.startsWith("ru-")) && signals.januaryOffset === -120 && signals.julyOffset === -180) {
+    return "uk";
+  }
+  return DEFAULT_LOCALE;
+}
+function resolveClientLocale(storageKey = LOCALE_STORAGE_KEY) {
+  if (typeof window === "undefined") return DEFAULT_LOCALE;
+  const signals = {};
+  try {
+    signals.stored = window.localStorage.getItem(storageKey);
+  } catch {
+  }
+  try {
+    if (typeof navigator !== "undefined") {
+      signals.languages = navigator.languages?.length ? navigator.languages : [navigator.language];
+    }
+  } catch {
+  }
+  try {
+    const options = Intl.DateTimeFormat().resolvedOptions();
+    signals.timeZone = options.timeZone;
+    signals.systemLocale = options.locale;
+    const year = (/* @__PURE__ */ new Date()).getFullYear();
+    signals.januaryOffset = new Date(year, 0, 1).getTimezoneOffset();
+    signals.julyOffset = new Date(year, 6, 1).getTimezoneOffset();
+  } catch {
+  }
+  return detectLocale(signals);
+}
+function formatLabel(template, values) {
+  return template.replace(/\{(\w+)\}/g, (match, key) => key in values ? String(values[key]) : match);
+}
+function policyLanguageOf(locale) {
+  return locale === "uk" ? "uk" : "en";
+}
+export {
+  DEFAULT_LOCALE,
+  LOCALE_STORAGE_KEY,
+  TUWA_LOCALES,
+  detectLocale,
+  formatLabel,
+  normalizeLocale,
+  policyLanguageOf,
+  resolveClientLocale
+};

package/dist/policies.cjs

@@ -25,6 +25,7 @@ __export(policies_exports, {
   POLICY_SITE_URL: () => POLICY_SITE_URL,
   POLICY_SOURCE: () => POLICY_SOURCE,
   footerPolicies: () => footerPolicies,
+  formatPolicyDate: () => formatPolicyDate,
   getPolicyFileUrl: () => getPolicyFileUrl,
   getPolicyPageUrl: () => getPolicyPageUrl,
   loadPolicy: () => loadPolicy,
@@ -134,6 +135,41 @@ async function loadPolicy(slug, options = {}) {
     languages: languages.length > 0 ? languages : ["en"]
   };
 }
+const MONTH_MAP = {
+  january: 0,
+  february: 1,
+  march: 2,
+  april: 3,
+  may: 4,
+  june: 5,
+  july: 6,
+  august: 7,
+  september: 8,
+  october: 9,
+  november: 10,
+  december: 11
+};
+function formatPolicyDate(dateStr, locale) {
+  let parsed;
+  const match = dateStr.trim().match(/^([A-Za-z]+)\s+(\d{1,2}),?\s+(\d{4})/);
+  if (match) {
+    const monthIndex = MONTH_MAP[match[1].toLowerCase()];
+    if (monthIndex !== void 0) {
+      parsed = new Date(Date.UTC(Number(match[3]), monthIndex, Number(match[2])));
+    }
+  }
+  if (!parsed || Number.isNaN(parsed.getTime())) {
+    parsed = new Date(dateStr.includes("UTC") ? dateStr : `${dateStr} UTC`);
+  }
+  if (Number.isNaN(parsed.getTime())) return dateStr;
+  const bcp47 = locale === "uk" ? "uk-UA" : locale === "zh-CN" ? "zh-CN" : "en-US";
+  return parsed.toLocaleDateString(bcp47, {
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+    timeZone: "UTC"
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   POLICIES_INDEX_URL,
@@ -143,6 +179,7 @@ async function loadPolicy(slug, options = {}) {
   POLICY_SITE_URL,
   POLICY_SOURCE,
   footerPolicies,
+  formatPolicyDate,
   getPolicyFileUrl,
   getPolicyPageUrl,
   loadPolicy,

package/dist/policies.d.cts

@@ -124,6 +124,14 @@ declare function loadPolicy(slug: PolicySlug, options?: {
     revalidate?: number | false;
     language?: PolicyLanguage;
 }): Promise<PolicyContent>;
+/**
+ * Formats a policy date string (e.g. `'October 14, 2026'`) according to the active locale or policy language.
+ *
+ * @param dateStr - The date string from the policy document.
+ * @param locale - The target locale (`'uk'`, `'zh-CN'`, `'en'`, or BCP 47 tag).
+ * @returns The formatted date, or the original string if parsing fails.
+ */
+declare function formatPolicyDate(dateStr: string, locale?: string): string;
 
-export { POLICIES_INDEX_URL, POLICY_DOCUMENT_LABELS, POLICY_LANGUAGES, POLICY_LANGUAGE_NAMES, POLICY_SITE_URL, POLICY_SOURCE, footerPolicies, getPolicyFileUrl, getPolicyPageUrl, loadPolicy, policies, policyLanguageFrom, publishedPolicies };
+export { POLICIES_INDEX_URL, POLICY_DOCUMENT_LABELS, POLICY_LANGUAGES, POLICY_LANGUAGE_NAMES, POLICY_SITE_URL, POLICY_SOURCE, footerPolicies, formatPolicyDate, getPolicyFileUrl, getPolicyPageUrl, loadPolicy, policies, policyLanguageFrom, publishedPolicies };
 export type { Policy, PolicyContent, PolicyDocumentLabels, PolicyLanguage, PolicySection, PolicySlug };

package/dist/policies.d.ts

@@ -124,6 +124,14 @@ declare function loadPolicy(slug: PolicySlug, options?: {
     revalidate?: number | false;
     language?: PolicyLanguage;
 }): Promise<PolicyContent>;
+/**
+ * Formats a policy date string (e.g. `'October 14, 2026'`) according to the active locale or policy language.
+ *
+ * @param dateStr - The date string from the policy document.
+ * @param locale - The target locale (`'uk'`, `'zh-CN'`, `'en'`, or BCP 47 tag).
+ * @returns The formatted date, or the original string if parsing fails.
+ */
+declare function formatPolicyDate(dateStr: string, locale?: string): string;
 
-export { POLICIES_INDEX_URL, POLICY_DOCUMENT_LABELS, POLICY_LANGUAGES, POLICY_LANGUAGE_NAMES, POLICY_SITE_URL, POLICY_SOURCE, footerPolicies, getPolicyFileUrl, getPolicyPageUrl, loadPolicy, policies, policyLanguageFrom, publishedPolicies };
+export { POLICIES_INDEX_URL, POLICY_DOCUMENT_LABELS, POLICY_LANGUAGES, POLICY_LANGUAGE_NAMES, POLICY_SITE_URL, POLICY_SOURCE, footerPolicies, formatPolicyDate, getPolicyFileUrl, getPolicyPageUrl, loadPolicy, policies, policyLanguageFrom, publishedPolicies };
 export type { Policy, PolicyContent, PolicyDocumentLabels, PolicyLanguage, PolicySection, PolicySlug };

package/dist/policies.js

@@ -99,6 +99,41 @@ async function loadPolicy(slug, options = {}) {
     languages: languages.length > 0 ? languages : ["en"]
   };
 }
+const MONTH_MAP = {
+  january: 0,
+  february: 1,
+  march: 2,
+  april: 3,
+  may: 4,
+  june: 5,
+  july: 6,
+  august: 7,
+  september: 8,
+  october: 9,
+  november: 10,
+  december: 11
+};
+function formatPolicyDate(dateStr, locale) {
+  let parsed;
+  const match = dateStr.trim().match(/^([A-Za-z]+)\s+(\d{1,2}),?\s+(\d{4})/);
+  if (match) {
+    const monthIndex = MONTH_MAP[match[1].toLowerCase()];
+    if (monthIndex !== void 0) {
+      parsed = new Date(Date.UTC(Number(match[3]), monthIndex, Number(match[2])));
+    }
+  }
+  if (!parsed || Number.isNaN(parsed.getTime())) {
+    parsed = new Date(dateStr.includes("UTC") ? dateStr : `${dateStr} UTC`);
+  }
+  if (Number.isNaN(parsed.getTime())) return dateStr;
+  const bcp47 = locale === "uk" ? "uk-UA" : locale === "zh-CN" ? "zh-CN" : "en-US";
+  return parsed.toLocaleDateString(bcp47, {
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+    timeZone: "UTC"
+  });
+}
 export {
   POLICIES_INDEX_URL,
   POLICY_DOCUMENT_LABELS,
@@ -107,6 +142,7 @@ export {
   POLICY_SITE_URL,
   POLICY_SOURCE,
   footerPolicies,
+  formatPolicyDate,
   getPolicyFileUrl,
   getPolicyPageUrl,
   loadPolicy,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuwaio/docs-ui",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "private": false,
   "author": "Oleksandr Tkach",
   "license": "Apache-2.0",
@@ -23,6 +23,16 @@
       "import": "./dist/policies.js",
       "require": "./dist/policies.cjs"
     },
+    "./locale": {
+      "types": "./dist/locale.d.ts",
+      "import": "./dist/locale.js",
+      "require": "./dist/locale.cjs"
+    },
+    "./i18n": {
+      "types": "./dist/i18n.d.ts",
+      "import": "./dist/i18n.js",
+      "require": "./dist/i18n.cjs"
+    },
     "./dist/index.css": "./dist/index.css",
     "./dist/*": "./dist/*"
   },