@i18n-micro/preact 1.2.16 → 2.0.0

package/dist/index.d.cts

@@ -1,15 +1,15 @@
 import { AnchorHTMLAttributes } from 'preact';
-import { Attributes } from 'preact';
 import { CleanTranslation } from '@i18n-micro/types';
 import { ComponentChildren } from 'preact';
+import { ComponentType } from 'preact';
 import { Context } from 'preact';
-import { default as default_2 } from 'react';
+import { createI18n } from '@i18n-micro/runtime';
+import { CSSProperties } from 'preact';
 import { defaultPlural } from '@i18n-micro/core';
 import { FormatService } from '@i18n-micro/core';
 import { Getter } from '@i18n-micro/types';
 import { HTMLAttributes } from 'preact';
-import { I18n } from '@i18n-micro/runtime';
-import { I18nOptions } from '@i18n-micro/runtime';
+import { I18nTRenderProps } from '@i18n-micro/core/render';
 import { interpolate } from '@i18n-micro/core';
 import { JSX } from 'preact';
 import { Locale } from '@i18n-micro/types';
@@ -17,21 +17,15 @@ import { LocaleCode } from '@i18n-micro/types';
 import { ModuleOptions } from '@i18n-micro/types';
 import { Params } from '@i18n-micro/types';
 import { PluralFunc } from '@i18n-micro/types';
+import { I18n as PreactI18n } from '@i18n-micro/runtime';
+import { I18nOptions as PreactI18nOptions } from '@i18n-micro/runtime';
 import { TranslationKey } from '@i18n-micro/types';
 import { Translations } from '@i18n-micro/types';
 import { VNode } from 'preact';
 
 export { CleanTranslation }
 
-/**
- * Создает адаптер для работы с History API (универсальный для Pure Preact)
- * Работает с любым роутером, который использует History API (wouter, preact-router, и т.д.)
- */
-export declare function createBrowserHistoryAdapter(locales: Locale[], defaultLocale: string): I18nRoutingStrategy;
-
-export declare function createI18n(options: PreactI18nOptions): PreactI18n;
-
-export declare const createPreactRouterAdapter: typeof createBrowserHistoryAdapter;
+export { createI18n }
 
 export { defaultPlural }
 
@@ -39,52 +33,75 @@ export { FormatService }
 
 export { Getter }
 
-export declare const I18nContext: Context<PreactI18n | null>;
+declare type HostAnchorAttrs<E extends EventTarget> = AnchorHTMLAttributes<E>;
+
+declare type HostAttrs<E extends EventTarget> = HTMLAttributes<E>;
+
+declare type HostComponent<P> = ComponentType<P>;
+
+declare type HostElement = VNode<any> | null;
+
+declare type HostNode = ComponentChildren;
+
+declare type HostStyle = CSSProperties;
+
+declare type HostTag = keyof JSX.IntrinsicElements;
 
-export declare const I18nDefaultLocaleContext: Context<string | null>;
+/** What a provider adds to its instance. It changes with its props, an adapter built in render on every render. */
+export declare interface I18nConfig {
+    locales: Locale[] | null;
+    defaultLocale: string | null;
+    router: I18nRoutingStrategy | null;
+    /** The `useI18n()` object of the current snapshot, shared by every consumer of this provider. */
+    api: {
+        snapshot: string;
+        value: UseI18nReturn;
+    } | null;
+    /** Translation methods by snapshot: they outlive the config, so `t` does not change with an adapter. */
+    methods: {
+        current: TranslationMethods | null;
+    };
+}
+
+export declare const I18nConfigContext: Context<I18nConfig | null>;
 
-export declare const I18nGroup: (props: I18nGroupProps) => VNode;
+/**
+ * The instance alone, stable while the app runs: `useT` and `<I18nT>` read only this, so a new
+ * adapter object does not render them.
+ */
+export declare const I18nContext: Context<PreactI18n | null>;
 
-export declare interface I18nGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+export declare const I18nGroup: (props: I18nGroupProps) => HostElement;
+
+export declare interface I18nGroupProps extends Omit<HostAttrs<HTMLDivElement>, 'children'> {
     prefix: string;
     groupClass?: string;
-    children?: (props: {
+    children?: HostNode | ((props: {
         prefix: string;
         t: (key: string, params?: Record<string, string | number | boolean>) => string;
-    }) => ComponentChildren;
+    }) => HostNode);
 }
 
-export declare const I18nLink: (props: I18nLinkProps) => VNode;
-
-export declare interface I18nLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
-    to: string | {
-        path?: string;
-    };
-    activeStyle?: Record<string, string | number>;
-    localeRoute?: (to: string | {
-        path?: string;
-    }, locale?: string) => string | {
-        path?: string;
-    };
-}
+export declare const I18nLink: (props: I18nLinkProps) => HostElement;
 
-export declare const I18nLocalesContext: Context<Locale[] | null>;
+export declare type I18nLinkProps = HostAnchorAttrs<HTMLAnchorElement> & {
+    to: RouteTarget;
+    activeStyle?: HostStyle;
+    localeRoute?: (to: RouteTarget, locale?: string) => RouteTarget;
+    children?: HostNode;
+};
 
-export declare function I18nProvider({ i18n, locales, defaultLocale, routingStrategy, children }: I18nProviderProps): VNode< Attributes & {
-    value: PreactI18n | null;
-    children?: ComponentChildren;
-}>;
+export declare function I18nProvider({ i18n, locales, defaultLocale, routingStrategy, children, ...options }: I18nProviderProps): HostElement;
 
-export declare interface I18nProviderProps {
-    i18n: PreactI18n;
+export declare interface I18nProviderProps extends Partial<PreactI18nOptions> {
+    /** An instance you created. Without it, the outer provider's; without that, one built from the options next to it: plain data, so a server component can pass them. */
+    i18n?: PreactI18n;
     locales?: Locale[];
     defaultLocale?: string;
     routingStrategy?: I18nRoutingStrategy;
-    children?: ComponentChildren;
+    children?: HostNode;
 }
 
-export declare const I18nRouterContext: Context<I18nRoutingStrategy | null>;
-
 /**
  * Routing strategy interface for i18n
  * Implement this interface to integrate with any router library
@@ -92,17 +109,17 @@ export declare const I18nRouterContext: Context<I18nRoutingStrategy | null>;
  */
 export declare interface I18nRoutingStrategy {
     /**
-     * Returns current path (without locale prefix if needed, or full path)
-     * Used for determining active classes in links
+     * Returns the current path with its query and hash, so a locale switch keeps them.
+     * Links compare it by page: query and hash do not count.
      */
     getCurrentPath: () => string;
     /**
      * Component to use for rendering links (e.g., RouterLink)
      */
-    linkComponent?: string | default_2.ComponentType<{
+    linkComponent?: string | HostComponent<{
         href: string;
-        children?: default_2.ReactNode;
-        style?: default_2.CSSProperties;
+        children?: HostNode;
+        style?: HostStyle;
         className?: string;
         [key: string]: unknown;
     }>;
@@ -121,11 +138,7 @@ export declare interface I18nRoutingStrategy {
     /**
      * Generate path for specific locale
      */
-    resolvePath?: (to: string | {
-        path?: string;
-    }, locale: string) => string | {
-        path?: string;
-    };
+    resolvePath?: (to: RouteTarget, locale: string) => RouteTarget;
     /**
      * (Optional) Get current route object for SEO/Meta tags
      */
@@ -135,50 +148,45 @@ export declare interface I18nRoutingStrategy {
     };
 }
 
-export declare const I18nSwitcher: (props: I18nSwitcherProps) => VNode;
+export declare const I18nSwitcher: (props: I18nSwitcherProps) => HostElement;
 
-export declare interface I18nSwitcherProps extends HTMLAttributes<HTMLDivElement> {
+export declare interface I18nSwitcherProps extends HostAttrs<HTMLDivElement> {
     locales?: Locale[];
     currentLocale?: string | (() => string);
     getLocaleName?: () => string | null;
     switchLocale?: (locale: string) => void;
-    localeRoute?: (to: string | {
-        path?: string;
-    }, locale?: string) => string | {
-        path?: string;
-    };
+    localeRoute?: (to: RouteTarget, locale?: string) => RouteTarget;
     customLabels?: Record<string, string>;
-    customWrapperStyle?: Record<string, string | number>;
-    customButtonStyle?: Record<string, string | number>;
-    customDropdownStyle?: Record<string, string | number>;
-    customItemStyle?: Record<string, string | number>;
-    customLinkStyle?: Record<string, string | number>;
-    customActiveLinkStyle?: Record<string, string | number>;
+    customWrapperStyle?: HostStyle;
+    customButtonStyle?: HostStyle;
+    customDropdownStyle?: HostStyle;
+    customItemStyle?: HostStyle;
+    customLinkStyle?: HostStyle;
+    customActiveLinkStyle?: HostStyle;
     /**
      * Inline style applied to the main switcher button when the current locale is
-     * marked as `disabled: true` in locale config.
+     * marked as `disabled: true` in the locale config.
      *
-     * Disabled locales are omitted from dropdown items.
+     * Disabled locales are omitted from the dropdown items, but still shown as the
+     * active button label.
      */
-    customDisabledLinkStyle?: Record<string, string | number>;
-    customIconStyle?: Record<string, string | number>;
+    customDisabledLinkStyle?: HostStyle;
+    customIconStyle?: HostStyle;
 }
 
-export declare const I18nT: (props: I18nTProps) => VNode | null;
-
-export declare interface I18nTProps extends Omit<HTMLAttributes<HTMLElement>, 'children'> {
-    keypath: TranslationKey;
-    params?: Record<string, string | number | boolean>;
-    tag?: keyof JSX.IntrinsicElements;
-    plural?: number | string;
-    defaultValue?: string;
-    html?: boolean;
-    hideIfEmpty?: boolean;
-    customPluralRule?: PluralFunc;
-    number?: number | string;
-    date?: Date | string | number;
-    relativeDate?: Date | string | number;
-    children?: never;
+export declare const I18nT: (props: I18nTProps) => HostElement;
+
+/** What fills a `{name}` placeholder: a node, or a function returning one (it may use hooks). */
+export declare type I18nTComponent = HostNode | (() => HostNode);
+
+export declare interface I18nTProps extends Omit<HostAttrs<HTMLElement>, 'children' | 'defaultValue'>, Omit<I18nTRenderProps, 'tag'> {
+    tag?: HostTag;
+    /** Elements for `{name}` placeholders. Beats a param of the same name. */
+    components?: Record<string, I18nTComponent>;
+    /** Replaces the text. As a function it gets the translation, like Vue's default slot. */
+    children?: HostNode | ((props: {
+        translation: string;
+    }) => HostNode);
 }
 
 export { interpolate }
@@ -193,18 +201,22 @@ export { Params }
 
 export { PluralFunc }
 
-/**
- * Preact-facing i18n instance. Same surface as `@i18n-micro/runtime`, kept as a
- * named subclass so `instanceof PreactI18n` and context typing stay stable.
- */
-export declare class PreactI18n extends I18n {
-}
+export { PreactI18n }
 
-export declare interface PreactI18nOptions extends I18nOptions {
-}
+export { PreactI18nOptions }
+
+/** Where a link or a switch goes. */
+export declare type RouteTarget = string | {
+    path?: string;
+};
 
 export { TranslationKey }
 
+declare type TranslationMethods = Pick<UseI18nReturn, 't' | 'ts' | 'tc' | 'tn' | 'td' | 'tdr' | 'has'> & Writers & {
+    i18n: PreactI18n;
+    snapshot: string;
+};
+
 export { Translations }
 
 export declare const useI18n: (options?: UseI18nOptions) => UseI18nReturn;
@@ -237,15 +249,9 @@ export declare interface UseI18nReturn {
     getLocales: () => Locale[];
     defaultLocale: () => string;
     getLocaleName: () => string | null;
-    switchLocale?: (locale: string) => void;
-    localeRoute?: (to: string | {
-        path?: string;
-    }, locale?: string) => string | {
-        path?: string;
-    };
-    localePath?: (to: string | {
-        path?: string;
-    }, locale?: string) => string;
+    switchLocale: (locale: string) => void;
+    localeRoute: (to: RouteTarget, locale?: string) => RouteTarget;
+    localePath: (to: RouteTarget, locale?: string) => string;
     addTranslations: (locale: string, translations: Translations, merge?: boolean) => void;
     addRouteTranslations: (locale: string, routeName: string, translations: Translations, merge?: boolean) => void;
     clearCache: () => void;
@@ -253,17 +259,20 @@ export declare interface UseI18nReturn {
 
 export declare const useI18nRouter: () => I18nRoutingStrategy | null;
 
+/**
+ * `setLocale` that loads first. A store write is synchronous for React, even inside
+ * `startTransition`, so a reader that suspends on a missing dictionary would show its fallback:
+ * this keeps the old UI until the messages are in. The last call wins; a failed `load` rejects
+ * and leaves the locale as it was.
+ */
+export declare function useLocaleSwitch(load: (locale: string) => unknown): [(locale: string) => Promise<void>, boolean];
+
+/**
+ * One translation as a value: the component renders only when this string changes, not on every
+ * locale or message write, nor when a provider gets a new adapter object.
+ */
+export declare function useT(key: TranslationKey, params?: Params, defaultValue?: string, routeName?: string): string;
+
+declare type Writers = Pick<UseI18nReturn, 'addTranslations' | 'addRouteTranslations' | 'clearCache'>;
+
 export { }
-
-// Type definitions for React package
-
-// Extend Window interface for SSR hydration state
-declare global {
-  interface Window {
-    __INITIAL_STATE__?: {
-      locale: string
-      route: string
-      // Add other SSR state fields as needed
-    }
-  }
-}