@pine-ds/core 3.27.0 → 3.29.0

package/dist/types/i18n/i18n-format.d.ts

@@ -0,0 +1,38 @@
+export type I18nVars = Record<string, string | number>;
+export type PluralForms = Partial<Record<Intl.LDMLPluralRule, string>>;
+/**
+ * i18n formatting helpers for Pine components.
+ *
+ * Pine stays string-agnostic: user-facing text is supplied by the consumer as
+ * props (English-defaulted). These helpers only handle the two things a prop
+ * value can't express on its own — interpolating live component state into a
+ * translated template, and picking the right plural form. No stored strings, no
+ * locale registry; the locale is read from the DOM (`lang`), the web-standard
+ * signal a consumer already sets.
+ *
+ * Two limitations of DOM-`lang` locale resolution, both inherent to inferring
+ * locale from the DOM rather than being told it:
+ *
+ * 1. Not reactive. `resolveLocale` is read during render; Stencil has no
+ *    reactive dependency on a DOM attribute, so changing `lang` at runtime
+ *    (`document.documentElement.lang = 'pl'`) does NOT re-render mounted
+ *    components — the plural form stays stale until unrelated state forces a
+ *    render. Fine when locale changes via full-page navigation; a consumer that
+ *    switches locale client-side should pass the already-formatted/pluralized
+ *    string as the prop instead.
+ * 2. Does not cross shadow boundaries. `el.closest('[lang]')` stops at the host's
+ *    shadow root. A Pine component nested inside another custom element whose
+ *    `lang` sits on that outer host will not see it and falls back to
+ *    `document.documentElement.lang`. Set `lang` on (or above) the Pine element
+ *    in the same tree, or pass a pre-formatted string, when that matters.
+ */
+/** Replace `{token}` placeholders with `vars`; unknown tokens stay literal. */
+export declare function formatMessage(template: string, vars?: I18nVars): string;
+/** Nearest `[lang]` ancestor, then `<html lang>`, then `'en'`. */
+export declare function resolveLocale(el?: Element | null): string;
+/**
+ * Pick the CLDR plural form for `count` in the element's locale (via the
+ * platform `Intl.PluralRules`) and interpolate `{count}`. `forms` come from the
+ * caller — component props, English-defaulted — and fall back to `other`.
+ */
+export declare function pluralize(el: Element | null, count: number, forms: PluralForms, vars?: I18nVars): string;

package/dist/types/i18n/index.d.ts

@@ -0,0 +1,2 @@
+export { formatMessage, pluralize, resolveLocale } from './i18n-format';
+export type { I18nVars, PluralForms } from './i18n-format';