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

package/README.md

@@ -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

@@ -9,26 +9,41 @@ import type { DefaultNetworkRequestService, IDataSourceAuth, ISendParams, ISendR
 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'>;
 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>>;
+    /** The network service every request goes through. */
     getNetworkService(): DefaultNetworkRequestService;
     /** Spread into an `HttpDataSource`: the repository then sends what this provider sends. */
     getDataSourceAuth(): IDataSourceAuth;
@@ -46,6 +61,7 @@ export interface IAuthRejection {
     message?: string | false;
 }
 export interface IAuthProvider extends IReactAdminAuthProvider {
+    /** The roles of the signed-in user. */
     getRoles: (params?: unknown) => Promise<Set<string>>;
     /** `true` when the session was refreshed, `false` when there is no refresh to make. */
     refreshToken: () => Promise<boolean>;
@@ -57,18 +73,29 @@ export interface IAuthProvider extends IReactAdminAuthProvider {
  */
 export type TI18nSource = object | (() => Promise<object>);
 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
      * (IGNIS's, so a provider registered with `LoggerFactory.use` is the one behind it).
      */
     logger?: ILogger;
+    /** The store the Redux provider of the shell serves. */
     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,11 @@
 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 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

@@ -49,6 +49,13 @@ 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 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.

package/dist/components/resolve.d.ts

@@ -1,6 +1,7 @@
 import type { Container } from '@venizia/ignis-inversion';
 import type { I18nProvider } from 'ra-core';
 import type { IAuthProvider, IDataProvider } from '../common/index.js';
+/** 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

package/dist/components/resolve.js

@@ -1,4 +1,5 @@
 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

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,12 @@
 type TDocumentTitleSegment = string | false | null | undefined;
 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,13 @@
 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

package/dist/providers/auth.d.ts

@@ -18,6 +18,7 @@ export declare class SessionClearReasons {
     /** `checkAuth` rejected: no token is stored, or the server answered with no data. */
     static readonly REJECTED = "rejected";
 }
+/** One of the `SessionClearReasons` values. */
 export type TSessionClearReason = TStringConstValue<typeof SessionClearReasons>;
 /**
  * The options hold data (`paths`); behaviour is in the protected hooks around `login` and the page
@@ -28,6 +29,27 @@ export type TSessionClearReason = TStringConstValue<typeof SessionClearReasons>;
  * hook that throws, or does not settle in `sessionHookTimeout`, is logged and does not stop the call
  * that fired it. A hook does not call this provider's methods: they wait behind it. Build one provider
  * per auth service: a second one listening to the same service calls every hook again.
+ *
+ * @example
+ * ```ts
+ * import { type BaseArdorApplication, configuration, CoreBindings, DefaultAuthProvider, inject, provide } from '@venizia/ardor';
+ *
+ * class AppAuthProvider extends DefaultAuthProvider {
+ *   protected override get afterLoginPath() {
+ *     return '/products';
+ *   }
+ * }
+ *
+ * @configuration()
+ * export class AuthConfiguration {
+ *   constructor(@inject({ key: CoreBindings.APPLICATION_INSTANCE }) private readonly application: BaseArdorApplication) {}
+ *
+ *   @provide({ key: CoreBindings.DEFAULT_AUTH_PROVIDER })
+ *   authProvider() {
+ *     return this.application.instantiate(AppAuthProvider).value(this.application);
+ *   }
+ * }
+ * ```
  */
 export declare class DefaultAuthProvider<TResource extends string = string> extends BaseProvider<IAuthProvider> {
     protected restDataProvider: IDataProvider<TResource>;
@@ -149,18 +171,50 @@ export declare class DefaultAuthProvider<TResource extends string = string> exte
     private clearSession;
     /** Announces the session in the store, when there is one. */
     private startStoredSession;
-    /** Typed `Promise<unknown>` so that a subclass override of `login` keeps compiling. */
+    /**
+     * Posts the sign-in body to `signInPath`, stores the session and resolves `{ ...response,
+     * redirectTo }`, where `redirectTo` is `afterLoginPath`. Rejects when the request fails, when the
+     * response carries no token or user id, or when `beforeSaveSession` throws; no session is stored
+     * then. Typed `Promise<unknown>` so that a subclass override of `login` keeps compiling.
+     */
     login(params: ILoginParams): Promise<unknown>;
+    /** Clears the session and resolves. */
     logout(_params?: unknown): Promise<void>;
+    /**
+     * Resolves when a token is stored and, if `paths.checkAuth` is set, the server answers with data.
+     * Otherwise it ends the session (reason `rejected`) and rejects with `unauthenticatedRejection`;
+     * it rejects with the request's error when the check request fails.
+     */
     checkAuth(_params?: unknown): Promise<void>;
+    /**
+     * Resolves for every error but 401 and 403. A 401 clears the session (unless
+     * `unauthenticatedRejection` says `logoutUser: false`) and rejects with that rejection; a 403
+     * rejects with `{ redirectTo: unauthorizedPagePath, logoutUser: false }`.
+     */
     checkError(error: unknown): Promise<void>;
+    /** Resolves the stored user; rejects when there is no `userId`. */
     getIdentity(_params?: unknown): Promise<any>;
+    /** Resolves with nothing; the roles come from `getRoles`. */
     getPermissions(_params?: unknown): Promise<void>;
+    /** Resolves the roles of the stored session. */
     getRoles(_params?: unknown): Promise<Set<string>>;
     /**
      * Refreshes the session through the network service's `refresh`, the one place a refresh is made:
      * `true` when it was refreshed, `false` when the service has no refresh to make. The `401`
      * recovery calls the same method, so one burst of 401s and this call share one refresh.
+     *
+     * @example
+     * ```tsx
+     * import { useRefreshToken } from '@venizia/ardor';
+     *
+     * // The data provider options name the refresh endpoint:
+     * // { url: '/api', authRecovery: { refreshTokenPath: '/auth/refresh-token' } }
+     * export const RefreshButton = () => {
+     *   const refreshToken = useRefreshToken();
+     *
+     *   return <button onClick={() => refreshToken()}>Refresh</button>;
+     * };
+     * ```
      */
     refreshToken(): Promise<boolean>;
     value(container: Container): IAuthProvider;

package/dist/providers/auth.js

@@ -42,6 +42,27 @@ const readStatus = (error) => {
  * hook that throws, or does not settle in `sessionHookTimeout`, is logged and does not stop the call
  * that fired it. A hook does not call this provider's methods: they wait behind it. Build one provider
  * per auth service: a second one listening to the same service calls every hook again.
+ *
+ * @example
+ * ```ts
+ * import { type BaseArdorApplication, configuration, CoreBindings, DefaultAuthProvider, inject, provide } from '@venizia/ardor';
+ *
+ * class AppAuthProvider extends DefaultAuthProvider {
+ *   protected override get afterLoginPath() {
+ *     return '/products';
+ *   }
+ * }
+ *
+ * @configuration()
+ * export class AuthConfiguration {
+ *   constructor(@inject({ key: CoreBindings.APPLICATION_INSTANCE }) private readonly application: BaseArdorApplication) {}
+ *
+ *   @provide({ key: CoreBindings.DEFAULT_AUTH_PROVIDER })
+ *   authProvider() {
+ *     return this.application.instantiate(AppAuthProvider).value(this.application);
+ *   }
+ * }
+ * ```
  */
 let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider extends BaseProvider {
     constructor(restDataProvider, authProviderOptions, authService, permissionProvider) {
@@ -295,7 +316,12 @@ let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider exte
         return this.startSession({ token, user: this.authService.getUser() });
     }
     // --- react-admin's auth provider -------------------------------------------------------------
-    /** Typed `Promise<unknown>` so that a subclass override of `login` keeps compiling. */
+    /**
+     * Posts the sign-in body to `signInPath`, stores the session and resolves `{ ...response,
+     * redirectTo }`, where `redirectTo` is `afterLoginPath`. Rejects when the request fails, when the
+     * response carries no token or user id, or when `beforeSaveSession` throws; no session is stored
+     * then. Typed `Promise<unknown>` so that a subclass override of `login` keeps compiling.
+     */
     async login(params) {
         const response = await this.restDataProvider.send({
             resource: this.signInPath,
@@ -316,9 +342,15 @@ let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider exte
             redirectTo: removeDoubleSlashes(`/${this.afterLoginPath}`),
         };
     }
+    /** Clears the session and resolves. */
     async logout(_params) {
         await this.clearSession({ reason: SessionClearReasons.LOGOUT });
     }
+    /**
+     * Resolves when a token is stored and, if `paths.checkAuth` is set, the server answers with data.
+     * Otherwise it ends the session (reason `rejected`) and rejects with `unauthenticatedRejection`;
+     * it rejects with the request's error when the check request fails.
+     */
     async checkAuth(_params) {
         const token = this.authService.getAuth();
         if (!token?.value) {
@@ -344,6 +376,11 @@ let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider exte
         await this.startStoredSession();
         return Promise.resolve();
     }
+    /**
+     * Resolves for every error but 401 and 403. A 401 clears the session (unless
+     * `unauthenticatedRejection` says `logoutUser: false`) and rejects with that rejection; a 403
+     * rejects with `{ redirectTo: unauthorizedPagePath, logoutUser: false }`.
+     */
     async checkError(error) {
         const status = readStatus(error);
         if (status === 401) {
@@ -361,6 +398,7 @@ let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider exte
         }
         return Promise.resolve();
     }
+    /** Resolves the stored user; rejects when there is no `userId`. */
     getIdentity(_params) {
         const user = this.authService.getUser();
         if (!user?.userId) {
@@ -368,9 +406,11 @@ let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider exte
         }
         return Promise.resolve(user);
     }
+    /** Resolves with nothing; the roles come from `getRoles`. */
     getPermissions(_params) {
         return Promise.resolve();
     }
+    /** Resolves the roles of the stored session. */
     getRoles(_params) {
         return Promise.resolve(this.authService.getRoles());
     }
@@ -378,6 +418,19 @@ let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider exte
      * Refreshes the session through the network service's `refresh`, the one place a refresh is made:
      * `true` when it was refreshed, `false` when the service has no refresh to make. The `401`
      * recovery calls the same method, so one burst of 401s and this call share one refresh.
+     *
+     * @example
+     * ```tsx
+     * import { useRefreshToken } from '@venizia/ardor';
+     *
+     * // The data provider options name the refresh endpoint:
+     * // { url: '/api', authRecovery: { refreshTokenPath: '/auth/refresh-token' } }
+     * export const RefreshButton = () => {
+     *   const refreshToken = useRefreshToken();
+     *
+     *   return <button onClick={() => refreshToken()}>Refresh</button>;
+     * };
+     * ```
      */
     async refreshToken() {
         const isRefreshed = await this.restDataProvider.getNetworkService().refresh();

package/dist/providers/count-rest-data.d.ts

@@ -3,7 +3,15 @@ import { type TRequestType } from '@venizia/ardor-kernel';
 import type { TExtraRequest } from '@venizia/ignis-kernel/repository';
 import type { IListFilter } from './list-filter.js';
 import { DefaultRestDataProvider } from './rest-data.js';
+/**
+ * A `DefaultRestDataProvider` whose list reads take their `total` from the count route
+ * (`GET /{resource}/count` with the same `where`) instead of the `Content-Range` header.
+ */
 export declare class CountRestDataProvider<TResource extends string = string> extends DefaultRestDataProvider<TResource> {
+    /**
+     * Sends the list GET and the count GET together; `total` is the count's `count`, or `0` when the
+     * count answers none. Rejects when either request rejects.
+     */
     protected requestList<RecordType extends RaRecord = RaRecord>(opts: {
         resource: TResource;
         type: TRequestType;