tera-system-ui 0.1.50 → 0.1.63

package/dist/paraglide/runtime.d.ts

@@ -59,6 +59,8 @@ export function extractLocaleFromUrl(url: URL | string): Locale | undefined;
  * For client-side UI components, use `localizeHref()` instead, which provides
  * a more convenient API with relative paths and automatic locale detection.
  *
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/i18n-routing
+ *
  * @example
  * ```typescript
  * // Server middleware example
@@ -104,6 +106,8 @@ export function localizeUrl(url: string | URL, options?: {
  * For client-side UI components, use `deLocalizeHref()` instead, which provides
  * a more convenient API with relative paths.
  *
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/i18n-routing
+ *
  * @example
  * ```typescript
  * // Server middleware example
@@ -133,6 +137,61 @@ export function localizeUrl(url: string | URL, options?: {
  */
 export function deLocalizeUrl(url: string | URL): URL;
 export function aggregateGroups(match: any): Record<string, string | null | undefined>;
+/**
+ * @typedef {object} ShouldRedirectServerInput
+ * @property {Request} request
+ * @property {string | URL} [url]
+ * @property {ReturnType<typeof assertIsLocale>} [locale]
+ *
+ * @typedef {object} ShouldRedirectClientInput
+ * @property {undefined} [request]
+ * @property {string | URL} [url]
+ * @property {ReturnType<typeof assertIsLocale>} [locale]
+ *
+ * @typedef {ShouldRedirectServerInput | ShouldRedirectClientInput} ShouldRedirectInput
+ *
+ * @typedef {object} ShouldRedirectResult
+ * @property {boolean} shouldRedirect - Indicates whether the consumer should perform a redirect.
+ * @property {ReturnType<typeof assertIsLocale>} locale - Locale resolved using the configured strategies.
+ * @property {URL | undefined} redirectUrl - Destination URL when a redirect is required.
+ */
+/**
+ * Determines whether a redirect is required to align the current URL with the active locale.
+ *
+ * This helper mirrors the logic that powers `paraglideMiddleware`, but works in both server
+ * and client environments. It evaluates the configured strategies in order, computes the
+ * canonical localized URL, and reports when the current URL does not match.
+ *
+ * When called in the browser without arguments, the current `window.location.href` is used.
+ *
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/i18n-routing#client-side-redirects
+ *
+ * @example
+ * // Client side usage (e.g. TanStack Router beforeLoad hook)
+ * async function beforeLoad({ location }) {
+ *   const decision = await shouldRedirect({ url: location.href });
+ *
+ *   if (decision.shouldRedirect) {
+ *     throw redirect({ to: decision.redirectUrl.href });
+ *   }
+ * }
+ *
+ * @example
+ * // Server side usage with a Request
+ * export async function handle(request) {
+ *   const decision = await shouldRedirect({ request });
+ *
+ *   if (decision.shouldRedirect) {
+ *     return Response.redirect(decision.redirectUrl, 307);
+ *   }
+ *
+ *   return render(request, decision.locale);
+ * }
+ *
+ * @param {ShouldRedirectInput} [input]
+ * @returns {Promise<ShouldRedirectResult>}
+ */
+export function shouldRedirect(input?: ShouldRedirectInput): Promise<ShouldRedirectResult>;
 /**
  * High-level URL localization function optimized for client-side UI usage.
  *
@@ -144,6 +203,8 @@ export function aggregateGroups(match: any): Record<string, string | null | unde
  * - Automatically detects current locale if not specified
  * - Handles string input/output instead of URL objects
  *
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/i18n-routing
+ *
  * @example
  * ```typescript
  * // In a React/Vue/Svelte component
@@ -184,6 +245,8 @@ export function localizeHref(href: string, options?: {
  * - Returns relative paths when possible
  * - Handles string input/output instead of URL objects
  *
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/i18n-routing
+ *
  * @example
  * ```typescript
  * // In a React/Vue/Svelte component
@@ -211,7 +274,6 @@ export function localizeHref(href: string, options?: {
  *
  * @param {string} href - The href to de-localize (can be relative or absolute)
  * @returns {string} The de-localized href, relative if input was relative
- * @see deLocalizeUrl - For low-level URL de-localization in server contexts
  */
 export function deLocalizeHref(href: string): string;
 /**
@@ -220,53 +282,76 @@ export function deLocalizeHref(href: string): string;
  */
 export function trackMessageCall(safeModuleId: string, locale: Locale): void;
 /**
- * Generates a list of localized URLs for all provided URLs.
+ * Generates localized URL variants for all provided URLs based on your configured locales and URL patterns.
  *
- * This is useful for SSG (Static Site Generation) and sitemap generation.
- * NextJS and other frameworks use this function for SSG.
+ * This function is essential for Static Site Generation (SSG) where you need to tell your framework
+ * which pages to pre-render at build time. It's also useful for generating sitemaps and
+ * `<link rel="alternate" hreflang>` tags for SEO.
+ *
+ * The function respects your `urlPatterns` configuration - if you have translated pathnames
+ * (e.g., `/about` → `/ueber-uns` for German), it will generate the correct localized paths.
+ *
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/static-site-generation
  *
  * @example
- * ```typescript
- * const urls = generateStaticLocalizedUrls([
- *   "https://example.com/about",
- *   "https://example.com/blog",
+ * // Basic usage - generate all locale variants for a list of paths
+ * const localizedUrls = generateStaticLocalizedUrls([
+ *   "/",
+ *   "/about",
+ *   "/blog/post-1",
  * ]);
- * urls[0].href // => "https://example.com/about"
- * urls[1].href // => "https://example.com/blog"
- * urls[2].href // => "https://example.com/de/about"
- * urls[3].href // => "https://example.com/de/blog"
- * ...
- * ```
+ * // Returns URL objects for each locale:
+ * // ["/en/", "/de/", "/en/about", "/de/about", "/en/blog/post-1", "/de/blog/post-1"]
+ *
+ * @example
+ * // Use with framework SSG APIs
+ * // SvelteKit
+ * export function entries() {
+ *   const paths = ["/", "/about", "/contact"];
+ *   return generateStaticLocalizedUrls(paths).map(url => ({
+ *     locale: extractLocaleFromUrl(url)
+ *   }));
+ * }
+ *
+ * @example
+ * // Sitemap generation
+ * const allPages = ["/", "/about", "/blog"];
+ * const sitemapUrls = generateStaticLocalizedUrls(allPages);
  *
- * @param {(string | URL)[]} urls - List of URLs to generate localized versions for. Can be absolute URLs or paths.
- * @returns {URL[]} List of localized URLs as URL objects
+ * @param {(string | URL)[]} urls - List of canonical URLs or paths to generate localized versions for.
+ *   Can be absolute URLs (`https://example.com/about`) or paths (`/about`).
+ *   Paths are resolved against `http://localhost` internally.
+ * @returns {URL[]} Array of URL objects representing all localized variants.
+ *   The order follows each input URL with all its locale variants before moving to the next URL.
  */
 export function generateStaticLocalizedUrls(urls: (string | URL)[]): URL[];
 /**
  * Checks if the given strategy is a custom strategy.
  *
  * @param {any} strategy The name of the custom strategy to validate.
- * Must be a string that starts with "custom-" followed by alphanumeric characters.
+ * Must be a string that starts with "custom-" followed by alphanumeric characters, hyphens, or underscores.
  * @returns {boolean} Returns true if it is a custom strategy, false otherwise.
  */
 export function isCustomStrategy(strategy: any): boolean;
 /**
  * Defines a custom strategy that is executed on the server.
  *
- * @param {any} strategy The name of the custom strategy to define. Must follow the pattern `custom-<name>` where
- * `<name>` contains only alphanumeric characters.
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/strategy#write-your-own-strategy
+ *
+ * @param {any} strategy The name of the custom strategy to define. Must follow the pattern custom-name with alphanumeric characters, hyphens, or underscores.
  * @param {CustomServerStrategyHandler} handler The handler for the custom strategy, which should implement
- * the method `getLocale`.
+ * the method getLocale.
  * @returns {void}
  */
 export function defineCustomServerStrategy(strategy: any, handler: CustomServerStrategyHandler): void;
 /**
  * Defines a custom strategy that is executed on the client.
  *
- * @param {any} strategy The name of the custom strategy to define. Must follow the pattern `custom-<name>` where
- * `<name>` contains only alphanumeric characters.
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/strategy#write-your-own-strategy
+ *
+ * @param {any} strategy The name of the custom strategy to define. Must follow the pattern custom-name with alphanumeric characters, hyphens, or underscores.
  * @param {CustomClientStrategyHandler} handler The handler for the custom strategy, which should implement the
- * methods `getLocale` and `setLocale`.
+ * methods getLocale and setLocale.
  * @returns {void}
  */
 export function defineCustomClientStrategy(strategy: any, handler: CustomClientStrategyHandler): void;
@@ -332,9 +417,17 @@ export let serverAsyncLocalStorage: ParaglideAsyncLocalStorage | undefined;
 export const disableAsyncLocalStorage: false;
 export const experimentalMiddlewareLocaleSplitting: false;
 export const isServer: any;
+/** @type {Locale | undefined} */
+export const experimentalStaticLocale: Locale | undefined;
 /**
  * Get the current locale.
  *
+ * The locale is resolved using your configured strategies (URL, cookie, localStorage, etc.)
+ * in the order they are defined. In SSR contexts, the locale is retrieved from AsyncLocalStorage
+ * which is set by the `paraglideMiddleware()`.
+ *
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/strategy - Configure locale detection strategies
+ *
  * @example
  *   if (getLocale() === 'de') {
  *     console.log('Germany 🇩🇪');
@@ -346,28 +439,36 @@ export const isServer: any;
  */
 export let getLocale: () => Locale;
 /**
- * Overwrite the \`getLocale()\` function.
+ * Overwrite the `getLocale()` function.
  *
- * Use this function to overwrite how the locale is resolved. For example,
- * you can resolve the locale from the browser's preferred language,
- * a cookie, env variable, or a user's preference.
+ * Use this function to overwrite how the locale is resolved. This is useful
+ * for custom locale resolution or advanced use cases like SSG with concurrent rendering.
+ *
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/strategy
  *
  * @example
  *   overwriteGetLocale(() => {
- *     // resolve the locale from a cookie. fallback to the base locale.
  *     return Cookies.get('locale') ?? baseLocale
- *   }
+ *   });
  *
  * @type {(fn: () => Locale) => void}
  */
 export const overwriteGetLocale: (fn: () => Locale) => void;
+/**
+ * @typedef {(newLocale: Locale, options?: { reload?: boolean }) => void | Promise<void>} SetLocaleFn
+ */
 /**
  * Set the locale.
  *
- * Set locale reloads the site by default on the client. Reloading
- * can be disabled by passing \`reload: false\` as an option. If
- * reloading is disabled, you need to ensure that the UI is updated
- * to reflect the new locale.
+ * Updates the locale using your configured strategies (cookie, localStorage, URL, etc.).
+ * By default, this reloads the page on the client to reflect the new locale. Reloading
+ * can be disabled by passing `reload: false` as an option, but you'll need to ensure
+ * the UI updates to reflect the new locale.
+ *
+ * If any custom strategy's `setLocale` function is async, then this function
+ * will become async as well.
+ *
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/strategy
  *
  * @example
  *   setLocale('en');
@@ -375,12 +476,10 @@ export const overwriteGetLocale: (fn: () => Locale) => void;
  * @example
  *   setLocale('en', { reload: false });
  *
- * @type {(newLocale: Locale, options?: { reload?: boolean }) => void}
+ * @type {SetLocaleFn}
  */
-export let setLocale: (newLocale: Locale, options?: {
-    reload?: boolean;
-}) => void;
-export function overwriteSetLocale(fn: (newLocale: Locale) => void): void;
+export let setLocale: SetLocaleFn;
+export function overwriteSetLocale(fn: SetLocaleFn): void;
 /**
  * The origin of the current URL.
  *
@@ -410,12 +509,45 @@ export let overwriteGetUrlOrigin: (fn: () => string) => void;
  * they are defined. If a strategy returns an invalid locale,
  * it will fall back to the next strategy.
  *
+ * Note: Custom server strategies are not supported in this synchronous version.
+ * Use `extractLocaleFromRequestAsync` if you need custom server strategies with async getLocale methods.
+ *
  * @example
  *   const locale = extractLocaleFromRequest(request);
  *
  * @type {(request: Request) => Locale}
  */
 export const extractLocaleFromRequest: (request: Request) => Locale;
+/**
+ * Asynchronously extracts a locale from a request.
+ *
+ * This function supports async custom server strategies, unlike the synchronous
+ * `extractLocaleFromRequest`. Use this function when you have custom server strategies
+ * that need to perform asynchronous operations (like database calls) in their getLocale method.
+ *
+ * The function first processes any custom server strategies asynchronously, then falls back
+ * to the synchronous `extractLocaleFromRequest` for all other strategies.
+ *
+ * @see {@link https://github.com/opral/inlang-paraglide-js/issues/527#issuecomment-2978151022}
+ *
+ * @example
+ *   // Basic usage
+ *   const locale = await extractLocaleFromRequestAsync(request);
+ *
+ * @example
+ *   // With custom async server strategy
+ *   defineCustomServerStrategy("custom-database", {
+ *     getLocale: async (request) => {
+ *       const userId = extractUserIdFromRequest(request);
+ *       return await getUserLocaleFromDatabase(userId);
+ *     }
+ *   });
+ *
+ *   const locale = await extractLocaleFromRequestAsync(request);
+ *
+ * @type {(request: Request) => Promise<Locale>}
+ */
+export const extractLocaleFromRequestAsync: (request: Request) => Promise<Locale>;
 /**
  * @typedef {"cookie" | "baseLocale" | "globalVariable" | "url" | "preferredLanguage" | "localStorage"} BuiltInStrategy
  */
@@ -429,13 +561,40 @@ export const extractLocaleFromRequest: (request: Request) => Locale;
  * @typedef {Array<Strategy>} Strategies
  */
 /**
- * @typedef {{ getLocale: (request?: Request) => string | undefined }} CustomServerStrategyHandler
+ * @typedef {{ getLocale: (request?: Request) => Promise<string | undefined> | (string | undefined) }} CustomServerStrategyHandler
  */
 /**
- * @typedef {{ getLocale: () => string | undefined, setLocale: (locale: string) => void }} CustomClientStrategyHandler
+ * @typedef {{ getLocale: () => Promise<string|undefined> | (string | undefined), setLocale: (locale: string) => Promise<void> | void }} CustomClientStrategyHandler
  */
-export const customServerStrategies: Map<any, any>;
-export const customClientStrategies: Map<any, any>;
+/** @type {Map<string, CustomServerStrategyHandler>} */
+export const customServerStrategies: Map<string, CustomServerStrategyHandler>;
+/** @type {Map<string, CustomClientStrategyHandler>} */
+export const customClientStrategies: Map<string, CustomClientStrategyHandler>;
+export type ShouldRedirectServerInput = {
+    request: Request;
+    url?: string | URL | undefined;
+    locale?: "id" | "no" | "ar" | "bg" | "bn" | "ca" | "cs" | "da" | "de" | "el" | "en" | "es" | "fi" | "fr" | "he" | "hi" | "hu" | "it" | "ja" | "ko" | "lt" | "lv" | "ms" | "nl" | "pl" | "pt" | "ro" | "ru" | "sk" | "sl" | "sq" | "sr" | "sv" | "sw" | "ta" | "te" | "th" | "tl" | "tr" | "uk" | "vi" | "zh-CN" | "zh-TW" | undefined;
+};
+export type ShouldRedirectClientInput = {
+    request?: undefined;
+    url?: string | URL | undefined;
+    locale?: "id" | "no" | "ar" | "bg" | "bn" | "ca" | "cs" | "da" | "de" | "el" | "en" | "es" | "fi" | "fr" | "he" | "hi" | "hu" | "it" | "ja" | "ko" | "lt" | "lv" | "ms" | "nl" | "pl" | "pt" | "ro" | "ru" | "sk" | "sl" | "sq" | "sr" | "sv" | "sw" | "ta" | "te" | "th" | "tl" | "tr" | "uk" | "vi" | "zh-CN" | "zh-TW" | undefined;
+};
+export type ShouldRedirectInput = ShouldRedirectServerInput | ShouldRedirectClientInput;
+export type ShouldRedirectResult = {
+    /**
+     * - Indicates whether the consumer should perform a redirect.
+     */
+    shouldRedirect: boolean;
+    /**
+     * - Locale resolved using the configured strategies.
+     */
+    locale: ReturnType<typeof assertIsLocale>;
+    /**
+     * - Destination URL when a redirect is required.
+     */
+    redirectUrl: URL | undefined;
+};
 export type ParaglideAsyncLocalStorage = {
     getStore(): {
         locale?: Locale;
@@ -448,18 +607,35 @@ export type ParaglideAsyncLocalStorage = {
         messageCalls?: Set<string>;
     }, cb: any) => any;
 };
+export type SetLocaleFn = (newLocale: Locale, options?: {
+    reload?: boolean;
+}) => void | Promise<void>;
 export type BuiltInStrategy = "cookie" | "baseLocale" | "globalVariable" | "url" | "preferredLanguage" | "localStorage";
 export type CustomStrategy = `custom_${string}`;
 export type Strategy = BuiltInStrategy | CustomStrategy;
 export type Strategies = Array<Strategy>;
 export type CustomServerStrategyHandler = {
-    getLocale: (request?: Request) => string | undefined;
+    getLocale: (request?: Request) => Promise<string | undefined> | (string | undefined);
 };
 export type CustomClientStrategyHandler = {
-    getLocale: () => string | undefined;
-    setLocale: (locale: string) => void;
+    getLocale: () => Promise<string | undefined> | (string | undefined);
+    setLocale: (locale: string) => Promise<void> | void;
 };
 /**
  * A locale that is available in the project.
  */
 export type Locale = (typeof locales)[number];
+/**
+ * A branded type representing a localized string.
+ *
+ * Message functions return this type instead of `string`, enabling TypeScript
+ * to distinguish translated strings from regular strings at compile time.
+ * This allows you to enforce that only properly localized content is used
+ * in your UI components.
+ *
+ * Since `LocalizedString` is a branded subtype of `string`, it remains fully
+ * backward compatible—you can pass it anywhere a `string` is expected.
+ */
+export type LocalizedString = string & {
+    readonly __brand: "LocalizedString";
+};