@nxgt/material 1.0.0

package/dist/lib/components/ui/upload/network-upload-field/network-upload-field.stories.d.ts

@@ -0,0 +1,31 @@
+import { StoryObj } from '@storybook/react';
+import { NetworkUploadField } from '../../..';
+declare const meta: {
+    title: string;
+    component: typeof NetworkUploadField;
+    parameters: {
+        layout: string;
+    };
+    tags: string[];
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+export declare const Default: Story;
+export declare const Multiple: Story;
+export declare const WithValidation: Story;
+export declare const AlwaysFails: Story;
+export declare const IndeterminateProgress: Story;
+export declare const WithRemovableFiles: Story;
+/**
+ * A value saved in an earlier session previews from its own URL — nothing to
+ * wire up, the extension is enough.
+ */
+export declare const SavedImage: Story;
+/**
+ * When the stored value is a storage key rather than a URL, `resolveUrl` is
+ * what turns it into something an `<img>` can load. Without it the row falls
+ * back to the file icon, because `avatars/…/x.png` in an `<img src>` would
+ * resolve against the current page.
+ */
+export declare const SavedKeyWithResolver: Story;
+export declare const Dark: Story;

package/dist/lib/components/ui/upload/network-upload-field/network-upload-field.utils.d.ts

@@ -0,0 +1,40 @@
+export type FileValidationError = 'accept' | 'max-size' | 'max-files';
+export type ValidateFileOptions = {
+    accept?: string;
+    maxSize?: number;
+    maxFiles?: number;
+    currentCount?: number;
+};
+export declare function matchesAccept(file: File, accept: string): boolean;
+export declare function validateFile(file: File, options: ValidateFileOptions): FileValidationError | null;
+export declare function formatFileSize(bytes: number): string;
+export declare function getValidationMessage(error: FileValidationError, options: ValidateFileOptions): string;
+export declare function createFileId(): string;
+export declare function filenameFromValue(value: string): string;
+export declare function getUploadErrorMessage(error: unknown): string;
+/**
+ * Whether a stored value looks like an image, judged by extension.
+ *
+ * A committed value is a bare string — a URL, a storage key or an id — so
+ * there is no `File` to read a MIME type from. The name is all there is, and
+ * `filenameFromValue` already strips a URL down to its last path segment, so a
+ * presigned URL with a long query string still ends in `.png`.
+ */
+export declare function isImageValue(value: string): boolean;
+/** Whether a value can go straight into an `<img src>` as it stands. */
+export declare function isDisplayableSrc(value: string): boolean;
+/**
+ * The `src` to preview a committed value with, or `undefined` for the file
+ * icon.
+ *
+ * Two kinds of value reach this. A URL is displayable as it stands. A storage
+ * key or an id is not — `avatars/<user>/<uuid>.png` in an `<img src>` resolves
+ * against the current page — so those need `resolveUrl` from the host, which
+ * is the only side that knows how to sign or address them.
+ *
+ * Either side may carry the extension: an id resolves to a URL that ends in
+ * `.png` while carrying nothing itself, and a key ends in `.png` while
+ * resolving to a signed URL whose path does too. Whichever one looks like an
+ * image is enough.
+ */
+export declare function resolvePreviewUrl(value: string, resolveUrl?: (value: string) => string | null | undefined): string | undefined;

package/dist/lib/components/ui/upload/network-upload-field/network-upload-field.utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/components/ui/upload/network-upload-field/network-upload-item.d.ts

@@ -0,0 +1,22 @@
+import { ComponentProps } from 'react';
+export type NetworkUploadItemStatus = 'uploading' | 'success' | 'error';
+export type NetworkUploadDisplayItem = {
+    id: string;
+    name: string;
+    size?: number;
+    status: NetworkUploadItemStatus;
+    progress?: number;
+    file?: File;
+    /** Thumbnail source for a committed value, when one could be worked out. */
+    previewUrl?: string;
+    errorMessage?: string;
+};
+export type NetworkUploadItemProps = ComponentProps<'div'> & {
+    item: NetworkUploadDisplayItem;
+    accept?: string;
+    disabled?: boolean;
+    onReplace: (item: NetworkUploadDisplayItem, file: File) => void;
+    onRetry: (item: NetworkUploadDisplayItem) => void;
+    onRemove: (item: NetworkUploadDisplayItem) => void;
+};
+export declare function NetworkUploadItem({ item, accept, disabled, onReplace, onRetry, onRemove, className, ...rest }: NetworkUploadItemProps): import("react").JSX.Element;

package/dist/lib/components/ui/upload/network-upload-field/use-file-drag-drop.d.ts

@@ -0,0 +1,14 @@
+import { DragEvent } from 'react';
+export type UseFileDragDropOptions = {
+    disabled?: boolean;
+    onDropFiles: (files: File[]) => void;
+};
+export declare function useFileDragDrop({ disabled, onDropFiles, }: UseFileDragDropOptions): {
+    isDragActive: boolean;
+    dragHandlers: {
+        onDragEnter: (event: DragEvent) => void;
+        onDragOver: (event: DragEvent) => void;
+        onDragLeave: (event: DragEvent) => void;
+        onDrop: (event: DragEvent) => void;
+    };
+};

package/dist/lib/components/ui/upload/network-upload-field/use-network-upload-field.d.ts

@@ -0,0 +1,19 @@
+import { NetworkUploadFieldProps } from './network-upload-field';
+import { NetworkUploadDisplayItem } from './network-upload-item';
+export declare function useNetworkUploadField(props: NetworkUploadFieldProps): {
+    displayItems: NetworkUploadDisplayItem[];
+    showEmptyZone: boolean;
+    atCapacity: boolean;
+    zoneDisabled: boolean;
+    isDragActive: boolean;
+    dragHandlers: {
+        onDragEnter: (event: import('react').DragEvent) => void;
+        onDragOver: (event: import('react').DragEvent) => void;
+        onDragLeave: (event: import('react').DragEvent) => void;
+        onDrop: (event: import('react').DragEvent) => void;
+    };
+    handleFilesSelected: (files: File[]) => void;
+    handleItemReplace: (item: NetworkUploadDisplayItem, file: File) => void;
+    handleItemRetry: (item: NetworkUploadDisplayItem) => void;
+    handleItemRemove: (item: NetworkUploadDisplayItem) => void;
+};

package/dist/lib/components/ui/upload/network-upload-field/use-upload-items.d.ts

@@ -0,0 +1,14 @@
+import { NetworkUploadFieldProps } from './network-upload-field';
+import { NetworkUploadDisplayItem } from './network-upload-item';
+export declare function useUploadItems(props: NetworkUploadFieldProps): {
+    localItems: import('./network-upload-field.slice').LocalFileItem[];
+    fileForValue: (value: string) => File | undefined;
+    addLocalItem: (file: File, options?: {
+        replacesValue?: string;
+        maxFiles?: number;
+        currentCount?: number;
+    }) => void;
+    handleItemReplace: (item: NetworkUploadDisplayItem, file: File) => void;
+    handleItemRetry: (item: NetworkUploadDisplayItem) => void;
+    handleItemRemove: (item: NetworkUploadDisplayItem) => void;
+};

package/dist/lib/components/ui/upload/s3-upload-field/index.d.ts

@@ -0,0 +1 @@
+export * from './s3-upload-field';

package/dist/lib/components/ui/upload/s3-upload-field/s3-upload-field.d.ts

@@ -0,0 +1,12 @@
+import { NetworkUploadFieldProps } from '../network-upload-field';
+type DistributiveOmit<T, K extends PropertyKey> = T extends any ? Omit<T, K> : never;
+export type PresignedUploadTarget = {
+    uploadUrl: string;
+    publicUrl: string;
+    headers?: Record<string, string>;
+};
+export type S3UploadFieldProps = DistributiveOmit<NetworkUploadFieldProps, 'onUpload'> & {
+    getPresignedUrl: (file: File) => Promise<PresignedUploadTarget>;
+};
+export declare function S3UploadField({ getPresignedUrl, ...props }: S3UploadFieldProps): import("react").JSX.Element;
+export {};

package/dist/lib/components/ui/upload/s3-upload-field/s3-upload-field.stories.d.ts

@@ -0,0 +1,15 @@
+import { StoryObj } from '@storybook/react';
+import { S3UploadField } from '../../..';
+declare const meta: {
+    title: string;
+    component: typeof S3UploadField;
+    parameters: {
+        layout: string;
+    };
+    tags: string[];
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+export declare const Default: Story;
+export declare const Multiple: Story;
+export declare const Dark: Story;

package/dist/lib/components/ui/upload/s3-upload-field/s3-upload-field.utils.d.ts

@@ -0,0 +1,5 @@
+export type PutFileWithProgressOptions = {
+    headers?: Record<string, string>;
+    onProgress?: (percent: number) => void;
+};
+export declare function putFileWithProgress(url: string, file: File, { headers, onProgress }?: PutFileWithProgressOptions): Promise<void>;

package/dist/lib/components/ui/upload-field.d.ts

@@ -0,0 +1,14 @@
+import { ReactNode } from 'react';
+import { InputProps } from './input';
+export type UploadFieldProps = {
+    label?: ReactNode;
+    helperText?: ReactNode;
+    error?: boolean;
+} & UploadInputProps;
+export declare function UploadField({ error, helperText, label, ...props }: UploadFieldProps): import("react").JSX.Element;
+type UploadInputProps = {
+    error?: boolean;
+    leading?: ReactNode;
+    trailing?: ReactNode;
+} & Omit<InputProps, 'type'>;
+export {};

package/dist/lib/components/ui/upload-field.stories.d.ts

@@ -0,0 +1,22 @@
+import { StoryObj } from '@storybook/react';
+import { UploadField } from '..';
+declare const meta: {
+    title: string;
+    component: typeof UploadField;
+    parameters: {
+        layout: string;
+    };
+    tags: string[];
+    argTypes: {
+        error: {
+            control: "boolean";
+        };
+        disabled: {
+            control: "boolean";
+        };
+    };
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+export declare const Default: Story;
+export declare const Dark: Story;

package/dist/lib/components/ui/url-field/index.d.ts

@@ -0,0 +1,3 @@
+export { isUrl, normalizeUrl } from './parse-url';
+export type { UrlFieldProps } from './url-field';
+export { UrlField } from './url-field';

package/dist/lib/components/ui/url-field/parse-url.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeUrl(raw: string): string | null;
+export declare function isUrl(raw: string): boolean;

package/dist/lib/components/ui/url-field/parse-url.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/components/ui/url-field/url-field.d.ts

@@ -0,0 +1,3 @@
+import { TextFieldProps } from '../text-field';
+export type UrlFieldProps = Omit<TextFieldProps, 'type' | 'leading' | 'trailing'>;
+export declare function UrlField({ value, defaultValue, onChange, onBlur, error, helperText, autoComplete, disabled, ...props }: UrlFieldProps): import("react").JSX.Element;

package/dist/lib/components/ui/url-field/url-field.stories.d.ts

@@ -0,0 +1,16 @@
+import { StoryObj } from '@storybook/react';
+import { UrlField } from '../..';
+declare const meta: {
+    title: string;
+    component: typeof UrlField;
+    parameters: {
+        layout: string;
+    };
+    tags: string[];
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+export declare const Default: Story;
+export declare const Valid: Story;
+export declare const ErrorState: Story;
+export declare const Dark: Story;

package/dist/lib/components/ui/video-player/index.d.ts

@@ -0,0 +1,2 @@
+/** @deprecated Use `StxPlayer` from `@nxgt/material` instead. */
+export { StxPlayer as VideoPlayer, type StxPlayerProps as VideoPlayerProps, type StxTrack as VideoPlayerTrack, } from '../stx-player';

package/dist/lib/dnd/index.d.ts

@@ -0,0 +1 @@
+export * from '../components/ui/dnd';

package/dist/lib/hooks/index.d.ts

@@ -0,0 +1,10 @@
+export * from './resolve-theme';
+export * from './use-allowed-transitions';
+export * from './use-is-client';
+export * from './use-localized-date';
+export * from './use-mobile';
+export * from './use-navigation';
+export * from './use-number-formatter';
+export * from './use-options';
+export * from './use-search-param';
+export * from './use-theme';

package/dist/lib/hooks/resolve-theme.d.ts

@@ -0,0 +1,7 @@
+export type ThemePreference = 'light' | 'dark' | 'system';
+export type ResolvedTheme = 'light' | 'dark';
+export declare function resolveTheme(stored: string | undefined | null, prefersDark: boolean): {
+    theme: ResolvedTheme;
+    preference: ThemePreference;
+};
+export declare function applyResolvedTheme(theme: ResolvedTheme): void;

package/dist/lib/hooks/resolve-theme.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/hooks/use-allowed-transitions.d.ts

@@ -0,0 +1,31 @@
+import { ResponsiveButtonProps } from '../components/ui/buttons/responsive-button';
+import { IconName } from '../components/ui/icon';
+import { TranslationContext } from '../i18n';
+/**
+ * Locale key type is generic here (`TLocaleKey`) rather than tied to this
+ * package's own `MaterialLocaleKey`: consuming apps call this hook with
+ * their own merged `LocaleKey` union (base `material.*` keys + their own),
+ * so the hook must not hardcode a specific app's i18n type.
+ */
+export type TranslationConfig<TLocaleKey extends string = string> = TLocaleKey | {
+    key: TLocaleKey;
+    context: TranslationContext;
+};
+export type ActionMetadata<TStatus extends string, TLocaleKey extends string = string> = {
+    targetStatus: TStatus;
+    icon: IconName;
+    color: ResponsiveButtonProps['color'];
+    label: TLocaleKey;
+    dialogTitle: TLocaleKey;
+    dialogMessage: TranslationConfig<TLocaleKey>;
+};
+export type ActionConfig<TStatus extends string, TLocaleKey extends string = string> = Omit<ActionMetadata<TStatus, TLocaleKey>, 'targetStatus'>;
+/**
+ * Computes the allowed transitions from the current status based on a transition map and UI configurations.
+ *
+ * @param currentStatus The current status of the entity.
+ * @param allowedTransitions Map of status to list of allowed target statuses.
+ * @param configs UI configurations (icons, colors, labels) for each target status.
+ * @returns An array of metadata for the allowed actions.
+ */
+export declare function useAllowedTransitions<TStatus extends string, TLocaleKey extends string = string>(currentStatus: TStatus, allowedTransitions: Record<TStatus, TStatus[]>, configs: Partial<Record<TStatus, ActionConfig<TStatus, TLocaleKey>>>): ActionMetadata<TStatus, TLocaleKey>[];

package/dist/lib/hooks/use-is-client.d.ts

@@ -0,0 +1,2 @@
+/** SSR-hydration guard: `true` only after the component has mounted on the client. */
+export declare function useIsClient(): boolean;

package/dist/lib/hooks/use-localized-date.d.ts

@@ -0,0 +1,21 @@
+import { Locale } from 'date-fns';
+/**
+ * useLocalizedDate - Date formatting bound to the current language.
+ *
+ * Resolves the date-fns locale from the mounted `I18nProvider` and pre-binds it,
+ * so callers do not have to thread a locale through every `DATE_UTILS.format`
+ * call. Falls back to `en`/`enUS` when no provider is mounted, which keeps the
+ * historical (English) output in apps that have not adopted i18n yet.
+ *
+ * @example
+ * ```tsx
+ * const { format } = useLocalizedDate();
+ * <span>{format(invoice.issuedAt)}</span>          // 'Oct 1, 2023' / '1 oct. 2023'
+ * <span>{format(invoice.issuedAt, 'PPPP')}</span>
+ * ```
+ */
+export declare function useLocalizedDate(): {
+    language: "fr" | "en";
+    locale: Locale;
+    format: (value?: string | null, formatStr?: string) => string;
+};

package/dist/lib/hooks/use-mobile.d.ts

@@ -0,0 +1 @@
+export declare function useIsMobile(): boolean;

package/dist/lib/hooks/use-navigation.d.ts

@@ -0,0 +1,6 @@
+import { NavigateOptions } from 'react-router';
+export declare function useNavigationHandler(to: string, options?: NavigateOptions): () => void;
+export declare function useNavigationHandlers(routes: {
+    to: string;
+    options?: NavigateOptions;
+}[]): (() => void)[];

package/dist/lib/hooks/use-number-formatter.d.ts

@@ -0,0 +1,12 @@
+/**
+ * useNumberFormatter - Number/currency formatting bound to the current
+ * language.
+ *
+ * Sources the language from the mounted `I18nProvider` (falling back to
+ * `formatNumber`'s own `'en-US'` default when no provider is mounted), so
+ * callers don't have to thread a locale through every call.
+ */
+export declare function useNumberFormatter(): {
+    formatCurrency: (value: number, options?: Omit<Intl.NumberFormatOptions, "language" | "style">) => string;
+    formatNumber: (value: number, options?: Omit<Intl.NumberFormatOptions, "language">) => string;
+};

package/dist/lib/hooks/use-options.d.ts

@@ -0,0 +1,29 @@
+export type UseOptionsConfig<T extends object> = {
+    filter?: (item: T) => boolean;
+    value: keyof T | ((item: T) => string);
+    label: keyof T | (keyof T)[] | ((item: T) => string);
+    expanded?: boolean;
+};
+export type InferOptions<T extends object, Expanded extends boolean = false> = Expanded extends true ? (T & {
+    value: string;
+    label: string;
+})[] : {
+    value: string;
+    label: string;
+}[];
+export declare function buildOptions<T extends object, Expanded extends boolean = false>(items: T[], { filter, value, label, expanded }: UseOptionsConfig<T>): InferOptions<T, Expanded>;
+export declare function useOptions<T extends object, Expanded extends boolean = false>(items: T[], config: UseOptionsConfig<T>): InferOptions<T, Expanded>;
+/**
+ * extractNode - Unwraps a GraphQL-edges shaped connection (`{ edges: { node
+ * }[] }`) into a plain array of nodes, for feeding into {@link useOptions} /
+ * {@link buildOptions} (which only operate over plain arrays).
+ */
+export declare function extractNode<T, E extends {
+    node: T;
+} = {
+    node: T;
+}, C extends {
+    edges: E[];
+} = {
+    edges: E[];
+}>(container?: C): T[];

package/dist/lib/hooks/use-search-param.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A hook to access and manipulate the URL search parameters.
+ *
+ * This hook wraps the `useSearchParams` hook from `react-router` to provide
+ * return the query parameter string or a typed object representation of the search parameters.
+ *
+ * @template T - The type of the search parameters object.
+ * @returns A tuple containing the search parameters as a typed object and a function to update them.
+ */
+export declare function useSearchParam(paramName: string): string | null;

package/dist/lib/hooks/use-theme.d.ts

@@ -0,0 +1,7 @@
+import { ThemePreference } from './resolve-theme';
+export declare function useTheme(): {
+    theme: import('./resolve-theme').ResolvedTheme;
+    preference: ThemePreference;
+    updateTheme: (next: ThemePreference) => void;
+};
+export type { ResolvedTheme, ThemePreference } from './resolve-theme';

package/dist/lib/i18n/consts.d.ts

@@ -0,0 +1,7 @@
+import { Language } from './types';
+/** `localStorage` key holding the user's selected language. */
+export declare const LANGUAGE_KEY = "language";
+/** Language used when nothing is stored, or the stored value is unsupported. */
+export declare const FALLBACK_LANGUAGE: Language;
+/** Languages the base bundle ships translations for. */
+export declare const SUPPORTED_LANGUAGES: Language[];

package/dist/lib/i18n/i18n-provider.d.ts

@@ -0,0 +1,61 @@
+import { ReactNode } from 'react';
+import { I18nContextValue, Language } from './types';
+export type I18nProviderProps = {
+    children: ReactNode;
+    /** Language used when nothing valid is stored. Defaults to `'en'`. */
+    defaultLanguage?: Language;
+    /** `localStorage` key holding the selected language. Defaults to `'language'`. */
+    storageKey?: string;
+    /** Languages the app accepts. Defaults to the base bundle's languages. */
+    supportedLanguages?: Language[];
+    /** Notified after a successful language change (analytics, server sync...). */
+    onLanguageChange?: (language: Language) => void;
+    /**
+     * Language resolved by the host before first render — e.g. from a
+     * request's `Accept-Language` header or a locale cookie during SSR. When
+     * provided and supported, this is used as-is for the initial render and
+     * `localStorage` is not read, so server and first client render always
+     * agree and no hydration guard is needed downstream.
+     */
+    initialLanguage?: Language;
+};
+/**
+ * I18nProvider - Shares the current language across the whole React tree.
+ *
+ * This is the piece that makes a language switch re-render every consumer:
+ * `language` lives in a single `useState` here rather than in a per-call-site
+ * `useState`/`useLocalStorage`, so no `window.location.reload()` is needed
+ * after `changeLanguage`.
+ *
+ * Only language state is shared — resource bundles stay static module imports
+ * inside each app, and are passed to `createTranslator` once.
+ *
+ * In a pure SPA (no `initialLanguage`), the initial language is read from
+ * `localStorage` lazily inside `useState`. In SSR, pass `initialLanguage`
+ * resolved by the host (e.g. from the request) so the server and first
+ * client render agree — `localStorage` is skipped entirely in that case.
+ *
+ * @example
+ * ```tsx
+ * <I18nProvider defaultLanguage="en">
+ *   <App />
+ * </I18nProvider>
+ * ```
+ */
+export declare function I18nProvider({ children, defaultLanguage, storageKey, supportedLanguages, onLanguageChange, initialLanguage, }: I18nProviderProps): import("react").JSX.Element;
+/**
+ * useI18nContext - Access the shared language state.
+ *
+ * Must be used within an {@link I18nProvider}.
+ *
+ * @throws Error if used outside of I18nProvider
+ */
+export declare function useI18nContext(): I18nContextValue;
+/**
+ * useOptionalI18nContext - Same as {@link useI18nContext}, but returns `null`
+ * instead of throwing when no provider is mounted.
+ *
+ * Components shipped by `@nxgt/material` use this so they keep rendering their
+ * built-in English defaults in apps that have not adopted `I18nProvider` yet.
+ */
+export declare function useOptionalI18nContext(): I18nContextValue | null;

package/dist/lib/i18n/i18n-provider.stories.d.ts

@@ -0,0 +1,29 @@
+import { StoryObj } from '@storybook/react';
+import { I18nProvider } from '.';
+declare const meta: {
+    title: string;
+    component: typeof I18nProvider;
+    parameters: {
+        layout: string;
+        docs: {
+            description: {
+                component: string;
+            };
+        };
+    };
+    tags: string[];
+    argTypes: {
+        defaultLanguage: {
+            control: "inline-radio";
+            options: string[];
+        };
+    };
+    args: {
+        children: null;
+        defaultLanguage: "en";
+        storageKey: string;
+    };
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+export declare const SharedLanguageState: Story;

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

@@ -0,0 +1,8 @@
+export * from './consts';
+export * from './i18n-provider';
+export * from './merge-resources';
+export * from './resources';
+export * from './translator';
+export * from './types';
+export * from './use-material-translation';
+export * from './use-typed-translation';

package/dist/lib/i18n/material-components.stories.d.ts

@@ -0,0 +1,30 @@
+import { StoryObj } from '@storybook/react';
+import { I18nProvider } from '.';
+declare const meta: {
+    title: string;
+    component: typeof I18nProvider;
+    parameters: {
+        layout: string;
+        docs: {
+            description: {
+                component: string;
+            };
+        };
+    };
+    tags: string[];
+    args: {
+        children: null;
+        defaultLanguage: "en";
+        storageKey: string;
+    };
+    argTypes: {
+        defaultLanguage: {
+            control: "inline-radio";
+            options: string[];
+        };
+    };
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+export declare const WithProvider: Story;
+export declare const WithoutProvider: Story;

package/dist/lib/i18n/merge-resources.d.ts

@@ -0,0 +1,40 @@
+/** A resource bundle: language code -> top-level namespaces. */
+export type ResourceBundle = Record<string, Record<string, unknown>>;
+/**
+ * Per-language intersection of a base bundle and an app bundle, so callers keep
+ * full key inference over the merged shape:
+ *
+ * ```ts
+ * const resources = mergeResources(materialResources, appResources);
+ * type LocaleKey = keyof FlatObject<typeof resources.en, string>;
+ * ```
+ */
+export type MergedResources<TBase extends ResourceBundle, TApp extends ResourceBundle> = {
+    [L in keyof TBase | keyof TApp]: (L extends keyof TBase ? TBase[L] : unknown) & (L extends keyof TApp ? TApp[L] : unknown);
+};
+/**
+ * Deep-merges the base bundle shipped by `@nxgt/material` with an app's own
+ * resources, per language.
+ *
+ * For each language present in either bundle, the two language objects are
+ * merged recursively (`lodash.merge`), so namespaces are combined at every
+ * depth: keys unique to either side are kept, and where both sides define the
+ * same leaf key the app's value wins.
+ *
+ * `@nxgt/material` ships everything under a single top-level namespace per
+ * language — **`material`** (`resources.en.material.table.*`,
+ * `resources.en.material['empty-state'].*`, ...). Apps can override individual
+ * strings within it (e.g. just `material.command.title`) without losing the
+ * rest of the namespace. In development, any leaf-level override is reported
+ * through `console.warn` so it stays visible rather than silent.
+ *
+ * @example
+ * ```ts
+ * import { mergeResources, resources as materialResources } from '@nxgt/material/i18n';
+ * import { resources as appResources } from './resources';
+ *
+ * export const resources = mergeResources(materialResources, appResources);
+ * export type LocaleKey = keyof FlatObject<typeof resources.en, string>;
+ * ```
+ */
+export declare function mergeResources<TBase extends ResourceBundle, TApp extends ResourceBundle>(base: TBase, app: TApp): MergedResources<TBase, TApp>;

package/dist/lib/i18n/merge-resources.test.d.ts

@@ -0,0 +1 @@
+export {};