igniteui-webcomponents
Version:
Ignite UI for Web Components is a complete library of UI components, giving you the ability to build modern web applications using encapsulation and the concept of reusable components in a dependency-free approach.
86 lines (85 loc) • 4.18 kB
TypeScript
import { type IResourceChangeEventArgs } from 'igniteui-i18n-core';
import type { ReactiveController, ReactiveControllerHost } from 'lit';
import { type I18nResourceMapNames } from './utils.js';
/**
* Defines the structure for the host element that will use this controller.
* The host must be a Lit element (ReactiveControllerHost) and an HTMLElement.
*/
interface I18nControllerHost extends ReactiveControllerHost, HTMLElement {
resourceStrings?: unknown;
locale?: string;
}
type ResourceChangeCallback = (event: CustomEvent<IResourceChangeEventArgs>) => unknown;
/** Configuration object for the I18nController. */
type I18nControllerConfig<T extends object> = {
/** The full default English resource strings object for the component. Should always come from igniteui-i18n-core. */
defaultEN: T;
/** @deprecated since 7.2.0. Optional name if component uses mixed resource strings. To be removed with deprecated resources. */
resourceMapName?: I18nResourceMapNames;
/** An optional callback to execute when the global locale changes. */
onResourceChange?: ResourceChangeCallback;
};
/**
* Manages localization (i18n) for a Lit web component.
* It handles the current locale, component-specific resource overrides,
* and updates when the global localization state changes.
*/
declare class I18nController<T extends object> implements ReactiveController {
private readonly _host;
private readonly _defaultEN;
/** @deprecated since 7.2.0. Resource name to use when converting new to old and vice versa resource objects. */
private readonly _resourceMapName?;
private readonly _resourceChangeCallback?;
private _locale?;
/** Cache of default resource strings coming from i18n Manager. */
private _defaultResourceStrings;
/** Collection containing only custom resource strings provided. Allows for partial override of resource strings. */
private _customResourceStrings?;
/** Merged collection of custom resource strings and default resource strings. */
private _resourceStrings?;
/**
* Sets a custom locale that overrides the global one for this host component instance.
* Setting a new locale triggers an update of the resource strings.
*/
set locale(value: string | undefined);
/**
* Gets the resolved locale for the host component.
* This is the component's custom locale if set, otherwise it falls back to the
* global locale.
*/
get locale(): string;
/**
* Sets custom resource string for component with this controller.
* Gets the resolved resource string for component.
*/
set resourceStrings(value: T | undefined);
/** Get resolved resource strings for component */
get resourceStrings(): T;
constructor(host: I18nControllerHost, config: I18nControllerConfig<T>);
/** @internal */
hostConnected(): void;
/** @internal */
hostDisconnected(): void;
/** @internal */
handleEvent(event: CustomEvent<IResourceChangeEventArgs>): void;
/**
* Gets the current, locale-specific resource strings for the component.
* The logic maps component keys (from defaultEN) to core library keys
* and retrieves the localized string from the i18n manager.
*
* Result is truncated, containing only relevant locale strings.
*/
private _getDefaultResourceStrings;
private getMixedResourceStrings;
}
/** Returns the default date-time input format for a given locale */
export declare function getDefaultDateTimeFormat(locale: string): string;
/** Returns the date-time format string with the appropriate suffix if it's a predefined style */
export declare function getDateTimeFormat(format?: string, suffix?: 'Date' | 'Time'): string | undefined;
/**
* Formats a date for display using the specified format.
*/
export declare function formatDisplayDate(value: Date, locale: string, displayFormat?: string): string;
/** Factory function to create and attach the I18nController to a host. */
export declare function addI18nController<T extends object>(host: I18nControllerHost, config: I18nControllerConfig<T>): I18nController<T>;
export type { I18nController };