@venizia/ardor-admin 0.4.8-0 → 0.4.8-10

package/README.md

@@ -4,7 +4,7 @@ The [react-admin](https://marmelab.com/react-admin/) adapter of
 [ARDOR](https://github.com/VENIZIA-AI/ardor): every place the framework touches `ra-core`.
 
 ```bash
-bun add @venizia/ardor-admin @venizia/ardor-kernel @venizia/ardor-react @venizia/ignis-inversion @venizia/ignis-filter @venizia/ignis-kernel @venizia/ignis-helpers reflect-metadata ra-core ra-i18n-polyglot
+bun add @venizia/ardor-admin @venizia/ardor-kernel @venizia/ardor-react @venizia/ignis-inversion @venizia/ignis-filter @venizia/ignis-kernel @venizia/ignis-helpers reflect-metadata ra-core ra-i18n-polyglot react react-dom react-redux react-router-dom @reduxjs/toolkit @tanstack/react-query
 ```
 
 Most applications install [`@venizia/ardor`](https://www.npmjs.com/package/@venizia/ardor) instead,
@@ -15,11 +15,15 @@ which re-exports this package.
 | Area | Exports |
 |---|---|
 | Data | `DefaultRestDataProvider`, `CountRestDataProvider` |
-| Auth | `DefaultAuthProvider` |
+| Auth | `DefaultAuthProvider`, `SessionClearReasons`, `IAuthRejection` |
 | i18n | `DefaultI18nProvider`, `englishMessages`, `vietnameseMessages` |
-| Component | `ArdorApplication` - the `CoreAdmin` root, wired from the container |
-| Hooks | `useTranslate`, `useNotifyError`, `useRefreshToken`, `useRequestHeaderLocale` |
-| Types | `IDataProvider`, `IAuthProvider`, `II18nProviderOptions`, `IApplication`, `TUseTranslateKeys` |
+| Component | `ArdorApplication` - the `CoreAdmin` root, wired from the container; `ApplicationProviders` |
+| Features | `Features`, `TFeature`, `useFeatures` |
+| Lists | `ListFilterBuilder` |
+| Hooks | `useTranslate`, `useUntypedTranslate`, `useNotifyError`, `useRefreshToken`, `useRequestHeaderLocale`, `useFeatures`, `useDocumentTitle`, `useHtmlLang` |
+| Types | `IDataProvider`, `IAuthProvider`, `II18nProviderOptions`, `IApplication`, `TUseTranslateKeys`, `TI18nSource` |
+
+Every export, with its signature, is in the [references](https://ardor.venizia.ai/references/).
 
 The data provider speaks the `@venizia/ignis-filter` vocabulary - react-admin pagination, sort and
 filter are mapped onto `{ where, order, limit, skip, fields, include }`.

package/dist/common/locales/en.d.ts

@@ -1,3 +1,4 @@
+/** The built-in English messages: react-admin's `ra` catalogue and ARDOR's own keys. */
 export declare const englishMessages: {
     ra: {
         action: {

package/dist/common/locales/en.js

@@ -1,3 +1,4 @@
+/** The built-in English messages: react-admin's `ra` catalogue and ARDOR's own keys. */
 export const englishMessages = {
     ra: {
         action: {

package/dist/common/locales/vi.d.ts

@@ -1,3 +1,4 @@
 import type { TranslationMessages } from 'ra-core';
+/** The built-in Vietnamese messages, the same shape as `englishMessages`. */
 export declare const vietnameseMessages: TranslationMessages;
 //# sourceMappingURL=vi.d.ts.map

package/dist/common/locales/vi.js

@@ -1,3 +1,4 @@
+/** The built-in Vietnamese messages, the same shape as `englishMessages`. */
 export const vietnameseMessages = {
     ra: {
         action: {

package/dist/common/merge.d.ts

@@ -0,0 +1,11 @@
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+/**
+ * A new object with the sources merged in order: a later source wins, plain objects merge
+ * recursively, anything else (an array, a string) replaces, and an `undefined` never overwrites. The
+ * sources are not changed. For JSON-like values only (message bundles): a `Date` becomes `{}`, an
+ * array is shared with its source by reference, and `__proto__` is dropped.
+ */
+export declare const deepMerge: (opts: {
+    sources: ReadonlyArray<object>;
+}) => Record<string, unknown>;
+//# sourceMappingURL=merge.d.ts.map

package/dist/common/merge.js

@@ -0,0 +1,25 @@
+export const isRecord = (value) => {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+/**
+ * A new object with the sources merged in order: a later source wins, plain objects merge
+ * recursively, anything else (an array, a string) replaces, and an `undefined` never overwrites. The
+ * sources are not changed. For JSON-like values only (message bundles): a `Date` becomes `{}`, an
+ * array is shared with its source by reference, and `__proto__` is dropped.
+ */
+export const deepMerge = (opts) => {
+    const merged = {};
+    for (const source of opts.sources) {
+        for (const [key, value] of Object.entries(source)) {
+            if (key === '__proto__' || value === undefined) {
+                continue;
+            }
+            const current = merged[key];
+            merged[key] = isRecord(value)
+                ? deepMerge({ sources: [isRecord(current) ? current : {}, value] })
+                : value;
+        }
+    }
+    return merged;
+};
+//# sourceMappingURL=merge.js.map

package/dist/common/types.d.ts

@@ -5,30 +5,46 @@ import type { TExtraRequest } from '@venizia/ignis-kernel/repository';
 import type { AuthProvider, CoreAdminProps, DataProvider, Locale, ResourceProps } from 'ra-core';
 import type { ReactNode } from 'react';
 import type { RouteProps } from 'react-router-dom';
-import type { DefaultNetworkRequestService, IDataSourceAuth, ISendParams, ISendResponse, RequestCountData, TConstValue, TRequestMethod, TRequestType } from '@venizia/ardor-kernel';
+import type { DefaultNetworkRequestService, IDataSourceAuth, INetworkResponse, ISendParams, RequestCountData, TConstValue, TRequestMethod, TRequestType } from '@venizia/ardor-kernel';
 import type { TFeature } from '../features/feature.js';
 /** What `DefaultRestDataProvider.request` sends: every react-admin method goes through it. */
 export interface IRestRequestOptions<TResource extends string = string> {
+    /** The first path segment, unless `paths` is set. */
     resource: TResource;
+    /** What the response is read as, and what the request is logged as. */
     type: TRequestType;
+    /** The HTTP method. */
     method: TRequestMethod;
-    /** Default `[resource]`. */
+    /**
+     * The path segments of the request.
+     * @default [resource]
+     */
     paths?: Array<string>;
+    /** The request body; encoded by `bodyType`. */
     body?: unknown;
     bodyType?: ISendParams['bodyType'];
+    /** The query string. */
     query?: Record<string, unknown>;
+    /** The list extras, sent in a header. */
     extra?: TExtraRequest;
     /** Win over the computed headers: a caller that names a header means it. */
     headers?: HeadersInit;
+    /**
+     * What the request asks the server to count.
+     * @default RequestCountData.DATA_ONLY
+     */
     requestCountData?: TConstValue<typeof RequestCountData>;
 }
 /** The nine data methods of react-admin, as ra-core declares them. */
 export type IReactAdminDataProvider<TResource extends string = string> = Pick<DataProvider<TResource>, 'getList' | 'getOne' | 'getMany' | 'getManyReference' | 'update' | 'updateMany' | 'create' | 'delete' | 'deleteMany'>;
+/** react-admin's data provider with a free-form `send` and access to the network service and its auth. */
 export interface IDataProvider<TResource extends string = string> extends IReactAdminDataProvider<TResource> {
+    /** A request outside react-admin's methods: the same headers and auth, the method and body of `params`. */
     send: <TResult = unknown>(opts: {
         resource: TResource;
         params: ISendParams;
-    }) => Promise<ISendResponse<TResult>>;
+    }) => Promise<INetworkResponse<TResult>>;
+    /** The network service every request goes through. */
     getNetworkService(): DefaultNetworkRequestService;
     /** Spread into an `HttpDataSource`: the repository then sends what this provider sends. */
     getDataSourceAuth(): IDataSourceAuth;
@@ -45,7 +61,12 @@ export interface IAuthRejection {
     logoutUser?: boolean;
     message?: string | false;
 }
+/** The auth provider of an ARDOR application: react-admin's methods, the user's roles and a token refresh. */
 export interface IAuthProvider extends IReactAdminAuthProvider {
+    /**
+     * The roles of the signed-in user, as the browser holds them: they only show or hide interface, and
+     * the backend must check every permission on every request.
+     */
     getRoles: (params?: unknown) => Promise<Set<string>>;
     /** `true` when the session was refreshed, `false` when there is no refresh to make. */
     refreshToken: () => Promise<boolean>;
@@ -56,19 +77,31 @@ export interface IAuthProvider extends IReactAdminAuthProvider {
  * is the messages). A loader that fails leaves that locale on the English messages.
  */
 export type TI18nSource = object | (() => Promise<object>);
+/** What `DefaultI18nProvider` is built from: the message sources and the languages on offer. */
 export interface II18nProviderOptions {
-    /** Messages by locale: the application's own over the features', English for a locale with no source or whose loader failed. */
+    /**
+     * Messages by locale: the application's own over the features', English for a locale with no source or whose loader failed.
+     * @default { en: englishMessages }
+     */
     i18nSources?: Record<string, TI18nSource>;
+    /**
+     * The locales the app offers.
+     * @default [{ locale: 'en', name: 'English' }]
+     */
     languages?: Array<Locale>;
 }
+/** The props of `ArdorApplication`: react-admin's `CoreAdmin` props except `children`, plus the ARDOR ones. */
 export interface IApplication extends Omit<CoreAdminProps, 'children'> {
+    /** The container the providers and the features are resolved from. */
     container: Container;
     /**
-     * The logger `useApplicationLogger()` returns. Absent, a console logger named after the application
+     * The logger `useApplicationLogger()` returns. Absent, a console logger named `ArdorApplication`
      * (IGNIS's, so a provider registered with `LoggerFactory.use` is the one behind it).
      */
     logger?: ILogger;
-    reduxStore: Store;
+    /** The store the Redux provider of the shell serves. Absent, the shell mounts no Redux provider. */
+    reduxStore?: Store;
+    /** Rendered as the `Suspense` fallback and while feature messages for the locale load. */
     suspense: ReactNode;
     /** The application's own resources; each feature's are mounted after them. */
     resources?: Array<ResourceProps>;

package/dist/components/application.d.ts

@@ -1,4 +1,12 @@
 import React from 'react';
 import type { IApplication } from '../common/types.js';
+/**
+ * The application shell. It resolves the data, auth and i18n providers from `container`, mounts the
+ * `resources` and `routes` of the application and of each feature inside react-admin, and wraps it
+ * all in `ApplicationContext.Provider` (`container`, `logger`), the Redux provider (only when
+ * `reduxStore` is passed) and `Suspense`. While a feature's lazy messages for the current locale
+ * load, it renders `suspense` instead of react-admin; a failed load is thrown from render. Remaining
+ * props go to react-admin's `CoreAdmin`.
+ */
 export declare const ArdorApplication: React.FC<IApplication>;
 //# sourceMappingURL=application.d.ts.map

package/dist/components/application.js

@@ -1,10 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React from 'react';
 import { LoggerFactory } from '@venizia/ignis-helpers/core';
+import { QueryClient } from '@tanstack/react-query';
 import { CoreAdmin, CustomRoutes, Resource } from 'ra-core';
 import { Provider as ReduxProvider } from 'react-redux';
 import { Route } from 'react-router-dom';
 import { Features } from '../features/feature.js';
+import { CoreBindings } from '@venizia/ardor-kernel';
 import { ApplicationContext } from '@venizia/ardor-react';
 import { ApplicationProviders } from './resolve.js';
 const Wrapper = ({ applicationName = 'ArdorApplication', container, reduxStore, suspense, logger, children, }) => {
@@ -12,7 +14,8 @@ const Wrapper = ({ applicationName = 'ArdorApplication', container, reduxStore,
     const applicationLogger = React.useMemo(() => {
         return logger ?? LoggerFactory.getLogger([applicationName]);
     }, [logger, applicationName]);
-    return (_jsx(ApplicationContext.Provider, { value: { container, logger: applicationLogger }, children: _jsx(ReduxProvider, { store: reduxStore, children: _jsx(React.Suspense, { fallback: suspense, children: children }) }) }));
+    const content = _jsx(React.Suspense, { fallback: suspense, children: children });
+    return (_jsx(ApplicationContext.Provider, { value: { container, logger: applicationLogger }, children: reduxStore ? _jsx(ReduxProvider, { store: reduxStore, children: content }) : content }));
 };
 /**
  * The i18n provider is built with the initial locale's eager messages only; when a feature loads
@@ -49,6 +52,14 @@ const useFeatureMessagesReady = (opts) => {
     }
     return state.isReady;
 };
+/**
+ * The application shell. It resolves the data, auth and i18n providers from `container`, mounts the
+ * `resources` and `routes` of the application and of each feature inside react-admin, and wraps it
+ * all in `ApplicationContext.Provider` (`container`, `logger`), the Redux provider (only when
+ * `reduxStore` is passed) and `Suspense`. While a feature's lazy messages for the current locale
+ * load, it renders `suspense` instead of react-admin; a failed load is thrown from render. Remaining
+ * props go to react-admin's `CoreAdmin`.
+ */
 export const ArdorApplication = (props) => {
     const { container, reduxStore, suspense, logger, resources, routes, features: selected, ...reactAdminProps } = props;
     // The list the shell passed, else every feature the application bound.
@@ -63,7 +74,31 @@ export const ArdorApplication = (props) => {
     const providers = React.useMemo(() => {
         return ApplicationProviders.resolve({ container });
     }, [container]);
-    const adminProps = { ...providers, ...reactAdminProps };
+    // The cache is owned here, so it can be emptied when the session ends by any route (a sign-out
+    // button empties it itself; a failed refresh, or code that calls `cleanUp`, does not).
+    const queryClient = React.useMemo(() => {
+        return reactAdminProps.queryClient ?? new QueryClient();
+    }, [reactAdminProps.queryClient]);
+    React.useEffect(() => {
+        const authService = container.get({
+            key: CoreBindings.DEFAULT_AUTH_SERVICE,
+            isOptional: true,
+        });
+        return authService?.subscribe({
+            listener: () => {
+                if (!authService.getAuth()?.value) {
+                    // After the redirect to the sign-in page, as react-admin's own sign-out does.
+                    setTimeout(() => {
+                        // Not when the next user signed in meanwhile.
+                        if (!authService.getAuth()?.value) {
+                            queryClient.clear();
+                        }
+                    }, 0);
+                }
+            },
+        });
+    }, [container, queryClient]);
+    const adminProps = { ...providers, ...reactAdminProps, queryClient };
     const isMessagesReady = useFeatureMessagesReady({
         features,
         i18nProvider: providers.i18nProvider,

package/dist/components/resolve.d.ts

@@ -1,17 +1,28 @@
 import type { Container } from '@venizia/ignis-inversion';
 import type { I18nProvider } from 'ra-core';
 import type { IAuthProvider, IDataProvider } from '../common/index.js';
+interface IResolvedProviders {
+    dataProvider: IDataProvider;
+    authProvider?: IAuthProvider;
+    i18nProvider: I18nProvider;
+}
+/** Resolves the providers `ArdorApplication` hands to react-admin. */
 export declare class ApplicationProviders {
     /**
      * What `ArdorApplication` resolves from the container when it mounts: the one place, so a test of
-     * the boot resolves exactly what the app does.
+     * the boot resolves exactly what the app does. With `isAuthRequired: true`, for an application that
+     * always binds a sign-in, `authProvider` is typed as present and an unbound one throws.
      */
     static resolve(opts: {
         container: Container;
-    }): {
-        dataProvider: IDataProvider;
-        authProvider?: IAuthProvider;
-        i18nProvider: I18nProvider;
+        isAuthRequired: true;
+    }): IResolvedProviders & {
+        authProvider: IAuthProvider;
     };
+    static resolve(opts: {
+        container: Container;
+        isAuthRequired?: boolean;
+    }): IResolvedProviders;
 }
+export {};
 //# sourceMappingURL=resolve.d.ts.map

package/dist/components/resolve.js

@@ -1,11 +1,8 @@
 import { CoreBindings } from '@venizia/ardor-kernel';
+/** Resolves the providers `ArdorApplication` hands to react-admin. */
 export class ApplicationProviders {
-    /**
-     * What `ArdorApplication` resolves from the container when it mounts: the one place, so a test of
-     * the boot resolves exactly what the app does.
-     */
     static resolve(opts) {
-        const { container } = opts;
+        const { container, isAuthRequired } = opts;
         const dataProvider = container.get({
             key: CoreBindings.DEFAULT_REST_DATA_PROVIDER,
         });
@@ -13,7 +10,7 @@ export class ApplicationProviders {
         // without an auth provider - every page is public.
         const authProvider = container.get({
             key: CoreBindings.DEFAULT_AUTH_PROVIDER,
-            isOptional: true,
+            isOptional: !isAuthRequired,
         });
         const i18nProvider = container.get({
             key: CoreBindings.DEFAULT_I18N_PROVIDER,

package/dist/features/feature.d.ts

@@ -15,6 +15,7 @@ export type TFeature<TExtension extends object = {}> = IFeatureBase & TExtension
     /** The application's own `i18nSources` override these. */
     messages?: TFeatureMessages;
 };
+/** Defines, reads, mounts and loads the messages of the features an application binds. */
 export declare class Features {
     /** Types a feature, keeping the shell's extension. */
     static define<TExtension extends object = {}>(feature: TFeature<TExtension>): TFeature<TExtension>;
@@ -28,7 +29,9 @@ export declare class Features {
      */
     static mount(opts: {
         features: Array<TFeature>;
+        /** @default [] */
         resources?: Array<ResourceProps>;
+        /** @default [] */
         routes?: Array<RouteProps>;
     }): {
         resources: Array<ResourceProps>;
@@ -46,6 +49,7 @@ export declare class Features {
     static loadMessages(opts: {
         features: Array<TFeature>;
         i18nProvider: I18nProvider;
+        /** The locale to load. @default i18nProvider.getLocale() */
         locale?: string;
     }): Promise<void>;
 }

package/dist/features/feature.js

@@ -2,6 +2,7 @@ import { getError } from '@venizia/ignis-inversion';
 import { CoreBindings } from '@venizia/ardor-kernel';
 import { LazyLocales } from '../providers/i18n-sources.js';
 import { FeatureMessages } from './messages.js';
+/** Defines, reads, mounts and loads the messages of the features an application binds. */
 export class Features {
     /** Types a feature, keeping the shell's extension. */
     static define(feature) {

package/dist/features/messages.js

@@ -1,6 +1,5 @@
 import { getError } from '@venizia/ignis-inversion';
-import isPlainObject from 'lodash/isPlainObject.js';
-import merge from 'lodash/merge.js';
+import { deepMerge, isRecord } from '../common/merge.js';
 /**
  * The features' messages for one locale, merged. Keys stay flat - no namespace is added - so a key
  * two features both define throws, naming both: a silent "later wins" is a wrong label nobody
@@ -74,11 +73,11 @@ export class FeatureMessages {
                 owners.set(key, feature);
             }
         }
-        return merge({}, ...bundles.map(({ bundle }) => bundle ?? {}));
+        return deepMerge({ sources: bundles.map(({ bundle }) => bundle ?? {}) });
     }
     static leafKeys(opts) {
         const { value, prefix } = opts;
-        if (!isPlainObject(value)) {
+        if (!isRecord(value)) {
             return prefix ? [prefix] : [];
         }
         return Object.entries(value).flatMap(([key, child]) => {

package/dist/hooks/use-document-title.d.ts

@@ -1,8 +1,13 @@
 type TDocumentTitleSegment = string | false | null | undefined;
+/** What `useDocumentTitle` writes into the tab title, and when. */
 export interface IUseDocumentTitleOptions {
+    /** The screen title, or a list of segments in order; `false`, `null`, `undefined` and empty segments are dropped. */
     title: TDocumentTitleSegment | Array<TDocumentTitleSegment>;
+    /** The last segment of the tab title. */
     appTitle: string;
+    /** Joins the segments. @default ' · ' */
     separator?: string;
+    /** When `false` the call writes no title. @default true */
     enabled?: boolean;
     /**
      * A base title for a layout. It shows only while no other call is mounted, so a screen's title

package/dist/hooks/use-features.js

@@ -1,8 +1,8 @@
-import { useInjectableContainer } from '@venizia/ardor-react';
+import { useApplicationContainer } from '@venizia/ardor-react';
 import { Features } from '../features/feature.js';
 /** The features the application mounts - for a menu, or a role editor listing their `permissions`. */
 export const useFeatures = () => {
-    const container = useInjectableContainer();
+    const container = useApplicationContainer();
     return Features.read({ container });
 };
 //# sourceMappingURL=use-features.js.map

package/dist/hooks/use-notify-error.d.ts

@@ -1,5 +1,9 @@
 import type { ApplicationError } from '@venizia/ignis-inversion';
 import type { NotificationOptions, NotificationType } from 'ra-core';
+/**
+ * Returns a stable function that shows an error notification for an `ApplicationError`: the message
+ * is its normalized `code`, with its normalized `args` as message arguments. `options` override both.
+ */
 export declare const useNotifyError: () => (error: ApplicationError, options?: NotificationOptions & {
     type?: NotificationType;
 }) => void;

package/dist/hooks/use-notify-error.js

@@ -1,5 +1,9 @@
 import React from 'react';
 import { useNotify } from 'ra-core';
+/**
+ * Returns a stable function that shows an error notification for an `ApplicationError`: the message
+ * is its normalized `code`, with its normalized `args` as message arguments. `options` override both.
+ */
 export const useNotifyError = () => {
     const notify = useNotify();
     return React.useCallback((error, options) => {

package/dist/hooks/use-refresh-token.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Returns a function that refreshes the session through the auth provider's `refreshToken` and, once
+ * that resolves, invalidates the cached permissions. It rejects when `refreshToken` rejects.
+ */
 export declare const useRefreshToken: () => TRefreshToken;
 /** `true` when the session was refreshed, `false` when there is no auth provider or no refresh to make. */
 type TRefreshToken = () => Promise<boolean>;

package/dist/hooks/use-refresh-token.js

@@ -3,6 +3,10 @@ import { useQueryClient } from '@tanstack/react-query';
 import { useAuthProvider } from 'ra-core';
 import { LoggerFactory } from '@venizia/ignis-helpers/core';
 const logger = LoggerFactory.getLogger(['useRefreshToken']);
+/**
+ * Returns a function that refreshes the session through the auth provider's `refreshToken` and, once
+ * that resolves, invalidates the cached permissions. It rejects when `refreshToken` rejects.
+ */
 export const useRefreshToken = () => {
     const authProvider = useAuthProvider();
     const queryClient = useQueryClient();

package/dist/hooks/use-request-header-locale.d.ts

@@ -1,6 +1,14 @@
+/** The header `useRequestHeaderLocale` sends the locale in. */
 export interface IUseRequestHeaderLocaleOptions {
-    /** The header the locale is sent in. Default `x-locale`. */
+    /**
+     * The header the locale is sent in.
+     * @default 'x-locale'
+     */
     key?: string;
 }
+/**
+ * Keeps the current react-admin locale in a header of the default REST data provider's network
+ * service, re-set on each locale change. `opts.key` defaults to `x-locale`; an empty key falls back to it.
+ */
 export declare const useRequestHeaderLocale: (opts?: IUseRequestHeaderLocaleOptions) => void;
 //# sourceMappingURL=use-request-header-locale.d.ts.map

package/dist/hooks/use-request-header-locale.js

@@ -2,6 +2,10 @@ import React from 'react';
 import { useLocaleState } from 'ra-core';
 import { CoreBindings, HeaderConstants } from '@venizia/ardor-kernel';
 import { useInjectable } from '@venizia/ardor-react';
+/**
+ * Keeps the current react-admin locale in a header of the default REST data provider's network
+ * service, re-set on each locale change. `opts.key` defaults to `x-locale`; an empty key falls back to it.
+ */
 export const useRequestHeaderLocale = (opts) => {
     const key = opts?.key?.length ? opts.key : HeaderConstants.X_LOCALE;
     const [locale] = useLocaleState();

package/dist/hooks/use-translate.d.ts

@@ -1,12 +1,31 @@
-import { type I18nProvider } from 'ra-core';
+import { type I18nProvider, type TranslateFunction } from 'ra-core';
 import type { TFullPaths } from '@venizia/ardor-kernel';
 import type { englishMessages } from '../common/locales/index.js';
+/**
+ * Augment this interface to add keys to `TUseTranslateKeys` (messages an app adds to the defaults):
+ *
+ * ```ts
+ * declare module '@venizia/ardor' {
+ *   interface IUseTranslateKeysOverrides {
+ *     'app.orders.title': unknown;
+ *   }
+ * }
+ * ```
+ */
 export interface IUseTranslateKeysOverrides {
 }
+/** Every dotted path to a message in the built-in English messages. */
 export type TUseTranslateKeysDefault = TFullPaths<typeof englishMessages>;
+/** The keys `useTranslate` accepts: the built-in message paths plus the keys added through `IUseTranslateKeysOverrides`. */
 export type TUseTranslateKeys = TUseTranslateKeysDefault | keyof IUseTranslateKeysOverrides;
 /** The options react-admin's `translate` takes (`smart_count`, `_` for a default text, ...). */
 export type TUseTranslateOptions = Parameters<I18nProvider['translate']>[1];
+/** `translate` with the key narrowed to `TUseTranslateKeys`. */
 export type TUseTranslateFn = (key: TUseTranslateKeys, options?: TUseTranslateOptions) => string;
+/** `translate` as react-admin types it, taking any string key. */
+export type TUseUntypedTranslateFn = TranslateFunction;
+/** For a key that exists only at run time (`errors.${code}`); a key written in code belongs to `useTranslate`. */
+export declare const useUntypedTranslate: () => TUseUntypedTranslateFn;
+/** The same function as `useUntypedTranslate`, with the key narrowed to `TUseTranslateKeys`. */
 export declare const useTranslate: () => TUseTranslateFn;
 //# sourceMappingURL=use-translate.d.ts.map

package/dist/hooks/use-translate.js

@@ -1,11 +1,6 @@
-import React from 'react';
-import { useI18nProvider } from 'ra-core';
-const identity = (key) => key;
-export const useTranslate = () => {
-    const i18nProvider = useI18nProvider();
-    const translate = React.useCallback((key, options) => {
-        return i18nProvider.translate(key, options);
-    }, [i18nProvider]);
-    return i18nProvider ? translate : identity;
-};
+import { useTranslate as useRaTranslate } from 'ra-core';
+/** For a key that exists only at run time (`errors.${code}`); a key written in code belongs to `useTranslate`. */
+export const useUntypedTranslate = useRaTranslate;
+/** The same function as `useUntypedTranslate`, with the key narrowed to `TUseTranslateKeys`. */
+export const useTranslate = useUntypedTranslate;
 //# sourceMappingURL=use-translate.js.map