tera-system-ui 0.1.20 → 0.1.32

package/dist/paraglide/runtime.d.ts

@@ -1,52 +1,465 @@
 /**
- * Check if something is an available language tag.
+ * Sets the server side async local storage.
+ *
+ * The function is needed because the `runtime.js` file
+ * must define the `serverAsyncLocalStorage` variable to
+ * avoid a circular import between `runtime.js` and
+ * `server.js` files.
+ *
+ * @param {ParaglideAsyncLocalStorage | undefined} value
+ */
+export function overwriteServerAsyncLocalStorage(value: ParaglideAsyncLocalStorage | undefined): void;
+/**
+ * Check if something is an available locale.
+ *
+ * @example
+ *   if (isLocale(params.locale)) {
+ *     setLocale(params.locale);
+ *   } else {
+ *     setLocale('en');
+ *   }
+ *
+ * @param {any} locale
+ * @returns {locale is Locale}
+ */
+export function isLocale(locale: any): locale is Locale;
+/**
+ * Asserts that the input is a locale.
+ *
+ * @param {any} input - The input to check.
+ * @returns {Locale} The input if it is a locale.
+ * @throws {Error} If the input is not a locale.
+ */
+export function assertIsLocale(input: any): Locale;
+/**
+ * Extracts a cookie from the document.
+ *
+ * Will return undefined if the document is not available or if the cookie is not set.
+ * The `document` object is not available in server-side rendering, so this function should not be called in that context.
+ *
+ * @returns {string | undefined}
+ */
+export function extractLocaleFromCookie(): string | undefined;
+export function extractLocaleFromHeader(request: Request): Locale;
+export function extractLocaleFromNavigator(): Locale | undefined;
+/**
+ * Extracts the locale from a given URL using native URLPattern.
+ *
+ * @param {URL|string} url - The full URL from which to extract the locale.
+ * @returns {Locale|undefined} The extracted locale, or undefined if no locale is found.
+ */
+export function extractLocaleFromUrl(url: URL | string): Locale | undefined;
+/**
+ * Lower-level URL localization function, primarily used in server contexts.
+ *
+ * This function is designed for server-side usage where you need precise control
+ * over URL localization, such as in middleware or request handlers. It works with
+ * URL objects and always returns absolute URLs.
+ *
+ * For client-side UI components, use `localizeHref()` instead, which provides
+ * a more convenient API with relative paths and automatic locale detection.
+ *
+ * @example
+ * ```typescript
+ * // Server middleware example
+ * app.use((req, res, next) => {
+ *   const url = new URL(req.url, `${req.protocol}://${req.headers.host}`);
+ *   const localized = localizeUrl(url, { locale: "de" });
+ *
+ *   if (localized.href !== url.href) {
+ *     return res.redirect(localized.href);
+ *   }
+ *   next();
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using with URL patterns
+ * const url = new URL("https://example.com/about");
+ * localizeUrl(url, { locale: "de" });
+ * // => URL("https://example.com/de/about")
+ *
+ * // Using with domain-based localization
+ * const url = new URL("https://example.com/store");
+ * localizeUrl(url, { locale: "de" });
+ * // => URL("https://de.example.com/store")
+ * ```
+ *
+ * @param {string | URL} url - The URL to localize. If string, must be absolute.
+ * @param {Object} [options] - Options for localization
+ * @param {string} [options.locale] - Target locale. If not provided, uses getLocale()
+ * @returns {URL} The localized URL, always absolute
+ */
+export function localizeUrl(url: string | URL, options?: {
+    locale?: string | undefined;
+}): URL;
+/**
+ * Low-level URL de-localization function, primarily used in server contexts.
+ *
+ * This function is designed for server-side usage where you need precise control
+ * over URL de-localization, such as in middleware or request handlers. It works with
+ * URL objects and always returns absolute URLs.
+ *
+ * For client-side UI components, use `deLocalizeHref()` instead, which provides
+ * a more convenient API with relative paths.
+ *
+ * @example
+ * ```typescript
+ * // Server middleware example
+ * app.use((req, res, next) => {
+ *   const url = new URL(req.url, `${req.protocol}://${req.headers.host}`);
+ *   const baseUrl = deLocalizeUrl(url);
+ *
+ *   // Store the base URL for later use
+ *   req.baseUrl = baseUrl;
+ *   next();
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using with URL patterns
+ * const url = new URL("https://example.com/de/about");
+ * deLocalizeUrl(url); // => URL("https://example.com/about")
+ *
+ * // Using with domain-based localization
+ * const url = new URL("https://de.example.com/store");
+ * deLocalizeUrl(url); // => URL("https://example.com/store")
+ * ```
+ *
+ * @param {string | URL} url - The URL to de-localize. If string, must be absolute.
+ * @returns {URL} The de-localized URL, always absolute
+ */
+export function deLocalizeUrl(url: string | URL): URL;
+export function aggregateGroups(match: any): Record<string, string | null | undefined>;
+/**
+ * High-level URL localization function optimized for client-side UI usage.
+ *
+ * This is a convenience wrapper around `localizeUrl()` that provides features
+ * needed in UI:
+ *
+ * - Accepts relative paths (e.g., "/about")
+ * - Returns relative paths when possible
+ * - Automatically detects current locale if not specified
+ * - Handles string input/output instead of URL objects
+ *
+ * @example
+ * ```typescript
+ * // In a React/Vue/Svelte component
+ * const NavLink = ({ href }) => {
+ *   // Automatically uses current locale, keeps path relative
+ *   return <a href={localizeHref(href)}>...</a>;
+ * };
+ *
+ * // Examples:
+ * localizeHref("/about")
+ * // => "/de/about" (if current locale is "de")
+ * localizeHref("/store", { locale: "fr" })
+ * // => "/fr/store" (explicit locale)
+ *
+ * // Cross-origin links remain absolute
+ * localizeHref("https://other-site.com/about")
+ * // => "https://other-site.com/de/about"
+ * ```
+ *
+ * For server-side URL localization (e.g., in middleware), use `localizeUrl()`
+ * which provides more precise control over URL handling.
+ *
+ * @param {string} href - The href to localize (can be relative or absolute)
+ * @param {Object} [options] - Options for localization
+ * @param {string} [options.locale] - Target locale. If not provided, uses `getLocale()`
+ * @returns {string} The localized href, relative if input was relative
+ */
+export function localizeHref(href: string, options?: {
+    locale?: string | undefined;
+}): string;
+/**
+ * High-level URL de-localization function optimized for client-side UI usage.
+ *
+ * This is a convenience wrapper around `deLocalizeUrl()` that provides features
+ * needed in the UI:
+ *
+ * - Accepts relative paths (e.g., "/de/about")
+ * - Returns relative paths when possible
+ * - Handles string input/output instead of URL objects
+ *
+ * @example
+ * ```typescript
+ * // In a React/Vue/Svelte component
+ * const LocaleSwitcher = ({ href }) => {
+ *   // Remove locale prefix before switching
+ *   const baseHref = deLocalizeHref(href);
+ *   return locales.map(locale =>
+ *     <a href={localizeHref(baseHref, { locale })}>
+ *       Switch to {locale}
+ *     </a>
+ *   );
+ * };
+ *
+ * // Examples:
+ * deLocalizeHref("/de/about")  // => "/about"
+ * deLocalizeHref("/fr/store")  // => "/store"
+ *
+ * // Cross-origin links remain absolute
+ * deLocalizeHref("https://example.com/de/about")
+ * // => "https://example.com/about"
+ * ```
+ *
+ * For server-side URL de-localization (e.g., in middleware), use `deLocalizeUrl()`
+ * which provides more precise control over URL handling.
+ *
+ * @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;
+/**
+ * @param {string} safeModuleId
+ * @param {Locale} locale
+ */
+export function trackMessageCall(safeModuleId: string, locale: Locale): void;
+/**
+ * Generates a list of localized URLs for all provided URLs.
+ *
+ * This is useful for SSG (Static Site Generation) and sitemap generation.
+ * NextJS and other frameworks use this function for SSG.
  *
  * @example
- * 	if (isAvailableLanguageTag(params.locale)) {
- * 		setLanguageTag(params.locale)
- * 	} else {
- * 		setLanguageTag("en")
- * 	}
+ * ```typescript
+ * const urls = generateStaticLocalizedUrls([
+ *   "https://example.com/about",
+ *   "https://example.com/blog",
+ * ]);
+ * 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"
+ * ...
+ * ```
+ *
+ * @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
+ */
+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.
+ * @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} thing
- * @returns {thing is AvailableLanguageTag}
+ * @param {any} strategy The name of the custom strategy to define. Must follow the pattern `custom-<name>` where
+ * `<name>` contains only alphanumeric characters.
+ * @param {CustomServerStrategyHandler} handler The handler for the custom strategy, which should implement
+ * 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.
+ * @param {CustomClientStrategyHandler} handler The handler for the custom strategy, which should implement the
+ * methods `getLocale` and `setLocale`.
+ * @returns {void}
+ */
+export function defineCustomClientStrategy(strategy: any, handler: CustomClientStrategyHandler): void;
+/**
+ * The project's base locale.
+ *
+ * @example
+ *   if (locale === baseLocale) {
+ *     // do something
+ *   }
  */
-export function isAvailableLanguageTag(thing: any): thing is AvailableLanguageTag;
+export const baseLocale: "en";
 /**
- * The project's source language tag.
+ * The project's locales that have been specified in the settings.
  *
  * @example
- *   if (newlySelectedLanguageTag === sourceLanguageTag){
- *     // do nothing as the source language tag is the default language
- *     return
+ *   if (locales.includes(userSelectedLocale) === false) {
+ *     throw new Error('Locale is not available');
  *   }
  */
-export const sourceLanguageTag: "en";
+export const locales: readonly ["ar", "bg", "bn", "ca", "cs", "da", "de", "el", "en", "es", "fi", "fr", "he", "hi", "hu", "id", "it", "ja", "ko", "lt", "lv", "ms", "nl", "no", "pl", "pt", "ro", "ru", "sk", "sl", "sq", "sr", "sv", "sw", "ta", "te", "th", "tl", "tr", "uk", "vi", "zh-CN", "zh-TW"];
+/** @type {string} */
+export const cookieName: string;
+/** @type {number} */
+export const cookieMaxAge: number;
+/** @type {string} */
+export const cookieDomain: string;
+/** @type {string} */
+export const localStorageKey: string;
 /**
- * The project's available language tags.
+ * @type {Array<"cookie" | "baseLocale" | "globalVariable" | "url" | "preferredLanguage" | "localStorage" | `custom-${string}`>}
+ */
+export const strategy: Array<"cookie" | "baseLocale" | "globalVariable" | "url" | "preferredLanguage" | "localStorage" | `custom-${string}`>;
+/**
+ * The used URL patterns.
+ *
+ * @type {Array<{ pattern: string, localized: Array<[Locale, string]> }> }
+ */
+export const urlPatterns: Array<{
+    pattern: string;
+    localized: Array<[Locale, string]>;
+}>;
+/**
+ * @typedef {{
+ * 		getStore(): {
+ *   		locale?: Locale,
+ * 			origin?: string,
+ * 			messageCalls?: Set<string>
+ *   	} | undefined,
+ * 		run: (store: { locale?: Locale, origin?: string, messageCalls?: Set<string>},
+ *    cb: any) => any
+ * }} ParaglideAsyncLocalStorage
+ */
+/**
+ * Server side async local storage that is set by `serverMiddleware()`.
+ *
+ * The variable is used to retrieve the locale and origin in a server-side
+ * rendering context without effecting other requests.
+ *
+ * @type {ParaglideAsyncLocalStorage | undefined}
+ */
+export let serverAsyncLocalStorage: ParaglideAsyncLocalStorage | undefined;
+export const disableAsyncLocalStorage: false;
+export const experimentalMiddlewareLocaleSplitting: false;
+export const isServer: any;
+/**
+ * Get the current locale.
  *
  * @example
- *   if (availableLanguageTags.includes(userSelectedLanguageTag) === false){
- *     throw new Error("Language tag not available")
+ *   if (getLocale() === 'de') {
+ *     console.log('Germany 🇩🇪');
+ *   } else if (getLocale() === 'nl') {
+ *     console.log('Netherlands 🇳🇱');
  *   }
+ *
+ * @type {() => Locale}
  */
-export const availableLanguageTags: readonly ["ar", "bg", "bn", "ca", "cs", "da", "de", "el", "en", "es", "fi", "fr", "he", "hi", "hu", "id", "it", "ja", "ko", "lt", "lv", "ms", "nl", "no", "pl", "pt", "ro", "ru", "sk", "sl", "sq", "sr", "sv", "sw", "ta", "te", "th", "tl", "tr", "uk", "vi", "zh-CN", "zh-TW"];
+export let getLocale: () => Locale;
 /**
- * Get the current language tag.
+ * 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.
  *
  * @example
- *   if (languageTag() === "de"){
- *     console.log("Germany 🇩🇪")
- *   } else if (languageTag() === "nl"){
- *     console.log("Netherlands 🇳🇱")
+ *   overwriteGetLocale(() => {
+ *     // resolve the locale from a cookie. fallback to the base locale.
+ *     return Cookies.get('locale') ?? baseLocale
  *   }
  *
- * @type {() => AvailableLanguageTag}
+ * @type {(fn: () => Locale) => void}
+ */
+export const overwriteGetLocale: (fn: () => Locale) => void;
+/**
+ * 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.
+ *
+ * @example
+ *   setLocale('en');
+ *
+ * @example
+ *   setLocale('en', { reload: false });
+ *
+ * @type {(newLocale: Locale, options?: { reload?: boolean }) => void}
+ */
+export let setLocale: (newLocale: Locale, options?: {
+    reload?: boolean;
+}) => void;
+export function overwriteSetLocale(fn: (newLocale: Locale) => void): void;
+/**
+ * The origin of the current URL.
+ *
+ * Defaults to "http://y.com" in non-browser environments. If this
+ * behavior is not desired, the implementation can be overwritten
+ * by `overwriteGetUrlOrigin()`.
+ *
+ * @type {() => string}
+ */
+export let getUrlOrigin: () => string;
+/**
+ * Overwrite the getUrlOrigin function.
+ *
+ * Use this function in server environments to
+ * define how the URL origin is resolved.
+ *
+ * @type {(fn: () => string) => void}
+ */
+export let overwriteGetUrlOrigin: (fn: () => string) => void;
+/**
+ * Extracts a locale from a request.
+ *
+ * Use the function on the server to extract the locale
+ * from a request.
+ *
+ * The function goes through the strategies in the order
+ * they are defined. If a strategy returns an invalid locale,
+ * it will fall back to the next strategy.
+ *
+ * @example
+ *   const locale = extractLocaleFromRequest(request);
+ *
+ * @type {(request: Request) => Locale}
+ */
+export const extractLocaleFromRequest: (request: Request) => Locale;
+/**
+ * @typedef {"cookie" | "baseLocale" | "globalVariable" | "url" | "preferredLanguage" | "localStorage"} BuiltInStrategy
+ */
+/**
+ * @typedef {`custom_${string}`} CustomStrategy
+ */
+/**
+ * @typedef {BuiltInStrategy | CustomStrategy} Strategy
+ */
+/**
+ * @typedef {Array<Strategy>} Strategies
+ */
+/**
+ * @typedef {{ getLocale: (request?: Request) => string | undefined }} CustomServerStrategyHandler
+ */
+/**
+ * @typedef {{ getLocale: () => string | undefined, setLocale: (locale: string) => void }} CustomClientStrategyHandler
  */
-export let languageTag: () => AvailableLanguageTag;
-export function setLanguageTag(tag: AvailableLanguageTag | (() => AvailableLanguageTag)): void;
-export function onSetLanguageTag(fn: (languageTag: AvailableLanguageTag) => void): void;
+export const customServerStrategies: Map<any, any>;
+export const customClientStrategies: Map<any, any>;
+export type ParaglideAsyncLocalStorage = {
+    getStore(): {
+        locale?: Locale;
+        origin?: string;
+        messageCalls?: Set<string>;
+    } | undefined;
+    run: (store: {
+        locale?: Locale;
+        origin?: string;
+        messageCalls?: Set<string>;
+    }, cb: any) => any;
+};
+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;
+};
+export type CustomClientStrategyHandler = {
+    getLocale: () => string | undefined;
+    setLocale: (locale: string) => void;
+};
 /**
- * A language tag that is available in the project.
+ * A locale that is available in the project.
  */
-export type AvailableLanguageTag = (typeof availableLanguageTags)[number];
+export type Locale = (typeof locales)[number];