@venizia/ardor-admin 0.4.8-1 → 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/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/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-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,13 +1,28 @@
 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;

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>;
@@ -46,8 +68,8 @@ export declare class DefaultAuthProvider<TResource extends string = string> exte
     private hookQueue;
     /** Where `login` posts: `paths.signIn`, else the IGNIS auth controller's route. */
     protected get signInPath(): string;
-    /** Where the admin goes once `login` resolves: `paths.afterLogin`, else `/`. */
-    protected get afterLoginPath(): string;
+    /** Where the admin goes once `login` resolves: `paths.afterLogin`, else `/`; `false` stays on the page. */
+    protected get afterLoginPath(): string | false;
     /** The route of the login page, which `checkAuth` and a `401` redirect to. */
     protected get loginPagePath(): string;
     /** The route a `403` redirects to; the application mounts it. */
@@ -149,18 +171,60 @@ 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. */
+    /**
+     * Runs when the session is gone, however it ended (sign-out, a `401`, a failed refresh, other
+     * code calling `cleanUp`): removes what the user stored under the store prefix of this
+     * application (`@app/store/`, or `@app/store/<id>/` with an application `id`) in `localStorage` and `sessionStorage`, so the next user does not see it.
+     * Override it to keep preferences, or put them under another prefix.
+     */
+    protected clearStoredData(): void;
+    /**
+     * Posts the sign-in body to `signInPath`, stores the session and resolves `{ ...response,
+     * redirectTo }`, where `redirectTo` is `afterLoginPath` (`false` when it is `false`). 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. They are read from browser storage, which the user can
+     * edit: use them to show or hide interface only, and let the backend check every permission.
+     */
     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

@@ -13,7 +13,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 var DefaultAuthProvider_1;
 import { getError, inject } from '@venizia/ignis-inversion';
 import { removeDoubleSlashes } from 'ra-core';
-import { BaseProvider, CoreBindings, RequestMethods, } from '@venizia/ardor-kernel';
+import { BaseProvider, BrowserStorage, CoreBindings, LocalStorageKeys, RequestMethods, StorageAreas, } from '@venizia/ardor-kernel';
 /** Why `onSessionCleared` was called. */
 export class SessionClearReasons {
     /** `logout` ran. */
@@ -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) {
@@ -63,7 +84,7 @@ let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider exte
     get signInPath() {
         return this.authProviderOptions.paths?.signIn ?? '/auth/sign-in';
     }
-    /** Where the admin goes once `login` resolves: `paths.afterLogin`, else `/`. */
+    /** Where the admin goes once `login` resolves: `paths.afterLogin`, else `/`; `false` stays on the page. */
     get afterLoginPath() {
         return this.authProviderOptions.paths?.afterLogin ?? '/';
     }
@@ -272,9 +293,17 @@ let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider exte
     }
     /** Announces or ends the session after the service saved or cleared it. */
     syncSession() {
-        return this.authService.getAuth()?.value
-            ? this.startStoredSession()
-            : this.endSession({ reason: this.clearing ?? SessionClearReasons.EXTERNAL });
+        if (this.authService.getAuth()?.value) {
+            return this.startStoredSession();
+        }
+        try {
+            this.clearStoredData();
+        }
+        catch (error) {
+            // An override that throws must not stop the session from ending.
+            this.logger.error('[clearStoredData] failed, the session ends anyway | error: %o', error);
+        }
+        return this.endSession({ reason: this.clearing ?? SessionClearReasons.EXTERNAL });
     }
     async clearSession(opts) {
         this.clearing = opts.reason;
@@ -294,8 +323,24 @@ let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider exte
         }
         return this.startSession({ token, user: this.authService.getUser() });
     }
+    /**
+     * Runs when the session is gone, however it ended (sign-out, a `401`, a failed refresh, other
+     * code calling `cleanUp`): removes what the user stored under the store prefix of this
+     * application (`@app/store/`, or `@app/store/<id>/` with an application `id`) in `localStorage` and `sessionStorage`, so the next user does not see it.
+     * Override it to keep preferences, or put them under another prefix.
+     */
+    clearStoredData() {
+        const prefix = this.authService.keys.storePrefix;
+        BrowserStorage.removeWhere({ storage: StorageAreas.LOCAL, prefix });
+        BrowserStorage.removeWhere({ storage: StorageAreas.SESSION, prefix });
+    }
     // --- 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` (`false` when it is `false`). 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,
@@ -311,14 +356,21 @@ let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider exte
         await this.startSession(stored?.value === session.token.value
             ? { token: stored, user: this.authService.getUser() }
             : { token: session.token, user: { userId: session.userId, username } });
+        const afterLogin = this.afterLoginPath;
         return {
             ...response,
-            redirectTo: removeDoubleSlashes(`/${this.afterLoginPath}`),
+            redirectTo: afterLogin === false ? false : removeDoubleSlashes(`/${afterLogin}`),
         };
     }
+    /** 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 +396,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 +418,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 +426,14 @@ 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. They are read from browser storage, which the user can
+     * edit: use them to show or hide interface only, and let the backend check every permission.
+     */
     getRoles(_params) {
         return Promise.resolve(this.authService.getRoles());
     }
@@ -378,6 +441,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();
@@ -387,6 +463,18 @@ let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider exte
         return isRefreshed;
     }
     value(container) {
+        // A subclass of DefaultAuthService with its own constructor must forward the application info to
+        // super(info): without it the service keeps the unscoped session, silently shared with every other
+        // application of the origin. Refuse that here, where the application info is at hand.
+        const id = container.get({
+            key: CoreBindings.APPLICATION_INFO,
+            isOptional: true,
+        })?.id;
+        if (id !== undefined && this.authService.keys.token !== LocalStorageKeys.scoped({ id }).token) {
+            throw getError({
+                message: `[DefaultAuthProvider] The auth service does not use the application id '${id}': a subclass of DefaultAuthService with its own constructor passes the application info to super(info)`,
+            });
+        }
         // A subclass with its own constructor rarely forwards the optional 4th argument to `super`.
         const permissionProvider = this.permissionProvider ??
             container.get({

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;

package/dist/providers/count-rest-data.js

@@ -1,6 +1,14 @@
 import { RequestMethods, RequestTypes } from '@venizia/ardor-kernel';
 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 class CountRestDataProvider extends DefaultRestDataProvider {
+    /**
+     * 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.
+     */
     requestList(opts) {
         const { resource, queryKey, filter } = opts;
         // The base class reads the rows and keeps the route's list extras as `meta.extra`.

package/dist/providers/i18n.d.ts

@@ -7,6 +7,26 @@ import { LocaleSources } from './i18n-sources.js';
 /**
  * The options hold data (`i18nSources`, `languages`); the hooks are `resolveInitialLocale` and
  * `composeMessages`, each taking one `opts` object.
+ *
+ * @example
+ * ```ts
+ * import { configuration, CoreBindings, englishMessages, provide, vietnameseMessages } from '@venizia/ardor';
+ *
+ * @configuration()
+ * export class I18nConfiguration {
+ *   @provide({ key: CoreBindings.I18N_PROVIDER_OPTIONS })
+ *   options() {
+ *     return {
+ *       languages: [{ locale: 'en', name: 'English' }, { locale: 'vi', name: 'Tieng Viet' }],
+ *       i18nSources: {
+ *         en: englishMessages,
+ *         // A loader runs the first time the locale is used, such as () => import('./vi').
+ *         vi: async () => vietnameseMessages,
+ *       },
+ *     };
+ *   }
+ * }
+ * ```
  */
 export declare class DefaultI18nProvider extends BaseProvider<I18nProvider> {
     protected i18nProviderOptions: II18nProviderOptions;
@@ -15,8 +35,8 @@ export declare class DefaultI18nProvider extends BaseProvider<I18nProvider> {
     constructor(i18nProviderOptions: II18nProviderOptions, features?: Array<TFeature>);
     /**
      * The locale the admin starts in: the browser's language when it is one of `locales`, else `en`.
-     * Read when the provider is built, not when the module is imported, and not at all outside a
-     * browser.
+     * Read when the provider is built, not when the module is imported. Without a `navigator` the
+     * language is `en-US`.
      */
     protected resolveInitialLocale(opts: {
         locales: Array<string>;

package/dist/providers/i18n.js

@@ -21,6 +21,26 @@ import { LazyLocales, LocaleSources } from './i18n-sources.js';
 /**
  * The options hold data (`i18nSources`, `languages`); the hooks are `resolveInitialLocale` and
  * `composeMessages`, each taking one `opts` object.
+ *
+ * @example
+ * ```ts
+ * import { configuration, CoreBindings, englishMessages, provide, vietnameseMessages } from '@venizia/ardor';
+ *
+ * @configuration()
+ * export class I18nConfiguration {
+ *   @provide({ key: CoreBindings.I18N_PROVIDER_OPTIONS })
+ *   options() {
+ *     return {
+ *       languages: [{ locale: 'en', name: 'English' }, { locale: 'vi', name: 'Tieng Viet' }],
+ *       i18nSources: {
+ *         en: englishMessages,
+ *         // A loader runs the first time the locale is used, such as () => import('./vi').
+ *         vi: async () => vietnameseMessages,
+ *       },
+ *     };
+ *   }
+ * }
+ * ```
  */
 let DefaultI18nProvider = DefaultI18nProvider_1 = class DefaultI18nProvider extends BaseProvider {
     constructor(i18nProviderOptions, features = []) {
@@ -34,8 +54,8 @@ let DefaultI18nProvider = DefaultI18nProvider_1 = class DefaultI18nProvider exte
     }
     /**
      * The locale the admin starts in: the browser's language when it is one of `locales`, else `en`.
-     * Read when the provider is built, not when the module is imported, and not at all outside a
-     * browser.
+     * Read when the provider is built, not when the module is imported. Without a `navigator` the
+     * language is `en-US`.
      */
     resolveInitialLocale(opts) {
         const browserLanguage = typeof navigator === 'undefined' ? undefined : navigator.language;

package/dist/providers/list-filter.d.ts

@@ -4,16 +4,20 @@ import { type ICustomParams } from '@venizia/ardor-kernel';
 /** The IGNIS filter a list request sends. Any other key of the list params is a filter key too. */
 export interface IListFilter {
     where: Record<string, unknown>;
+    /** Each entry is `'<field> <ASC|DESC>'`. */
     order?: Array<string>;
     limit?: number;
+    /** IGNIS's offset; `ListFilterBuilder.build` sets this one. */
     skip?: number;
-    offset?: number;
     include?: unknown;
     fields?: unknown;
+    /** Not part of the filter sent: `ListFilterBuilder.build` moves it into the query string. */
     params?: Record<string, unknown>;
+    /** Lifts `limit` and `skip`: the list is not paginated. */
     noLimit?: boolean;
     [key: string]: unknown;
 }
+/** Builds the filter, query and extras of a list request from react-admin's list params. */
 export declare class ListFilterBuilder {
     /** `filter.params` as the keys of the query string, as a copy. */
     static extractQueryParams(opts: {

package/dist/providers/list-filter.js

@@ -1,4 +1,5 @@
 import { ValueUtility } from '@venizia/ardor-kernel';
+/** Builds the filter, query and extras of a list request from react-admin's list params. */
 export class ListFilterBuilder {
     /** `filter.params` as the keys of the query string, as a copy. */
     static extractQueryParams(opts) {
@@ -36,7 +37,7 @@ export class ListFilterBuilder {
         }
         else {
             const { page = 1, perPage = 0 } = pagination ?? {};
-            // No `perPage` is no limit. `skip` is IGNIS's offset (`offset` is its alias): one is enough.
+            // No `perPage` is no limit. `skip` is IGNIS's offset.
             if (perPage > 0) {
                 filter['limit'] = perPage;
                 filter['skip'] = (Math.max(page, 1) - 1) * perPage;

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

@@ -1,14 +1,42 @@
 import { type Container } from '@venizia/ignis-inversion';
 import type { CreateParams, CreateResult, DeleteManyParams, DeleteManyResult, DeleteParams, DeleteResult, GetListParams, GetListResult, GetManyParams, GetManyReferenceParams, GetManyReferenceResult, GetManyResult, GetOneParams, GetOneResult, Identifier, QueryFunctionContext, RaRecord, UpdateManyParams, UpdateManyResult, UpdateParams, UpdateResult } from 'ra-core';
-import { BaseProvider, DefaultNetworkRequestService, type IApplicationInfo, type INetworkResponse, type ICustomParams, type IRestDataProviderOptions, type ISendParams, type ISendResponse, type TRequestType } from '@venizia/ardor-kernel';
+import { BaseProvider, type DefaultAuthService, DefaultNetworkRequestService, type IApplicationInfo, type INetworkResponse, type ICustomParams, type IRestDataProviderOptions, type ISendParams, type TRequestType } from '@venizia/ardor-kernel';
 import type { TExtraRequest } from '@venizia/ignis-kernel/repository';
 import type { IDataProvider, IRestRequestOptions } from '../common/index.js';
 import { type IListFilter } from './list-filter.js';
+/**
+ * The react-admin data provider over an IGNIS REST API. Each method takes one `opts` object
+ * (`{ resource, params }`) and resolves the result react-admin expects; it rejects with the error
+ * the network service throws (a non-2xx response, an empty base URL, an auth failure that cannot be
+ * recovered). A subclass overrides the protected hooks (`createNetworkService`, `buildListFilter`,
+ * `requestList`).
+ *
+ * @example
+ * ```ts
+ * import { type BaseArdorApplication, configuration, CoreBindings, DefaultRestDataProvider, inject, provide } from '@venizia/ardor';
+ *
+ * @configuration()
+ * export class DataConfiguration {
+ *   constructor(@inject({ key: CoreBindings.APPLICATION_INSTANCE }) private readonly application: BaseArdorApplication) {}
+ *
+ *   @provide({ key: CoreBindings.REST_DATA_PROVIDER_OPTIONS })
+ *   options() {
+ *     return { url: '/api', noAuthPaths: ['/auth/sign-in'] };
+ *   }
+ *
+ *   @provide({ key: CoreBindings.DEFAULT_REST_DATA_PROVIDER })
+ *   dataProvider() {
+ *     return this.application.instantiate(DefaultRestDataProvider).value(this.application);
+ *   }
+ * }
+ * ```
+ */
 export declare class DefaultRestDataProvider<TResource extends string = string> extends BaseProvider<IDataProvider<TResource>> {
     protected restDataProviderOptions: IRestDataProviderOptions;
     protected applicationInfo: IApplicationInfo;
     private cachedNetworkService?;
-    private authService?;
+    /** The auth service of the container, set when `value` builds the provider; pass it to the network service you return from `createNetworkService`. */
+    protected authService?: DefaultAuthService;
     constructor(restDataProviderOptions: IRestDataProviderOptions, applicationInfo: IApplicationInfo);
     /**
      * Builds the network service this provider sends through. Override it to return a subclass of
@@ -17,6 +45,7 @@ export declare class DefaultRestDataProvider<TResource extends string = string>
      */
     protected createNetworkService(): DefaultNetworkRequestService;
     protected get networkService(): DefaultNetworkRequestService;
+    /** The network service every request of this provider goes through; built on first use. */
     getNetworkService(): DefaultNetworkRequestService;
     /**
      * The ids a bulk write touched, read from the affected rows the server answers (not the ids asked
@@ -70,48 +99,81 @@ export declare class DefaultRestDataProvider<TResource extends string = string>
         filename?: string;
         contentDisposition?: string;
     }>;
+    /**
+     * `GET /{resource}` with the filter built from the list params in the query. Resolves the rows and
+     * `total` (the `Content-Range` total, else the page's row count), plus `meta.extra` when a route
+     * answered extras.
+     */
     getList<RecordType extends RaRecord = RaRecord>(opts: {
         resource: TResource;
         params: GetListParams & QueryFunctionContext & ICustomParams;
     }): Promise<GetListResult<RecordType>>;
+    /**
+     * `GET /{resource}/{id}`, with `params.meta.filter` as the query filter. Resolves `{ data }`.
+     */
     getOne<RecordType extends RaRecord = RaRecord>(opts: {
         resource: TResource;
         params: GetOneParams<RecordType> & QueryFunctionContext & ICustomParams;
     }): Promise<GetOneResult<RecordType>>;
+    /**
+     * `GET /{resource}` with the ids in `filter.where.id.inq`, merged into `params.meta.filter`.
+     * Resolves `{ data }`.
+     */
     getMany<RecordType extends RaRecord = RaRecord>(opts: {
         resource: TResource;
         params: GetManyParams<RecordType> & QueryFunctionContext & ICustomParams;
     }): Promise<GetManyResult<RecordType>>;
+    /**
+     * As `getList`, with `filter.where[target] = id`. Resolves the rows and `total`.
+     */
     getManyReference<RecordType extends RaRecord = RaRecord>(opts: {
         resource: TResource;
         params: GetManyReferenceParams & QueryFunctionContext & ICustomParams;
     }): Promise<GetManyReferenceResult<RecordType>>;
+    /** `PATCH /{resource}/{id}` with `params.data` as the body. Resolves `{ data }`. */
     update<RecordType extends RaRecord = RaRecord>(opts: {
         resource: TResource;
         params: UpdateParams;
     }): Promise<UpdateResult<RecordType>>;
+    /**
+     * `PATCH /{resource}` with `{ ...params.data, where: { id: { inq: ids } } }` as the body. Resolves
+     * `{ data }`, the ids of the rows the server answered (`undefined` when the answer is not a row
+     * array). Rejects when `ids` is empty or `params.data` has a `where` field, before any request.
+     */
     updateMany<RecordType extends RaRecord = RaRecord>(opts: {
         resource: TResource;
         params: UpdateManyParams;
     }): Promise<UpdateManyResult<RecordType>>;
+    /** `POST /{resource}` with `params.data` as the body. Resolves `{ data }`, the created record. */
     create<RecordType extends Omit<RaRecord, 'id'> = Omit<RaRecord, 'id'>, ResultRecordType extends RaRecord = RecordType & {
         id: Identifier;
     }>(opts: {
         resource: TResource;
         params: CreateParams;
     }): Promise<CreateResult<ResultRecordType>>;
+    /** `DELETE /{resource}/{id}`. Resolves `{ data }`, the record the server answered. */
     delete<RecordType extends RaRecord = RaRecord>(opts: {
         resource: TResource;
         params: DeleteParams<RecordType>;
     }): Promise<DeleteResult<RecordType>>;
+    /**
+     * `DELETE /{resource}` with `{ where: { id: { inq: ids } } }` as the body. Resolves `{ data }`, the
+     * ids of the rows the server answered (`undefined` when the answer is not a row array). Rejects
+     * when `ids` is empty, before any request.
+     */
     deleteMany<RecordType extends RaRecord = RaRecord>(opts: {
         resource: TResource;
         params: DeleteManyParams<RecordType>;
     }): Promise<DeleteManyResult<RecordType>>;
+    /**
+     * Sends `params.method` to `/{resource}` with the provider's headers and auth; `requestType`
+     * defaults to `RequestTypes.SEND`. Resolves the response read by that type. Rejects when
+     * `params.method` is missing, before any request.
+     */
     send<TResult = unknown>(opts: {
         resource: TResource;
         params: ISendParams;
-    }): Promise<ISendResponse<TResult>>;
+    }): Promise<INetworkResponse<TResult>>;
     /**
      * react-admin's data provider contract takes positional arguments, `(resource, params)`: the one
      * place this class does not take an `opts` object. Each method hands them to the `opts` method.

package/dist/providers/rest-data.js

@@ -14,6 +14,52 @@ var DefaultRestDataProvider_1;
 import { getError, inject } from '@venizia/ignis-inversion';
 import { BaseProvider, CoreBindings, DefaultNetworkRequestService, ValueUtility, NetworkHeaders, RequestCountData, RequestMethods, RequestTypes, } from '@venizia/ardor-kernel';
 import { ListFilterBuilder } from './list-filter.js';
+/**
+ * The path of one record: the id is a single path segment, whatever characters it holds. An empty
+ * id, `.` and `..` (dot segments even when written `%2E`) and a lone surrogate (which cannot be
+ * encoded) are refused, without naming the id.
+ */
+const recordPaths = (opts) => {
+    let segment = '';
+    try {
+        segment = encodeURIComponent(`${opts.id}`);
+        // eslint-disable-next-line venizia/no-silent-catch -- a lone surrogate cannot be encoded: the empty segment below refuses it
+    }
+    catch {
+        segment = '';
+    }
+    if (segment === '' || segment === '.' || segment === '..') {
+        throw getError({ message: '[recordPaths] The record id is not a valid path segment' });
+    }
+    return [opts.resource, segment];
+};
+/**
+ * The react-admin data provider over an IGNIS REST API. Each method takes one `opts` object
+ * (`{ resource, params }`) and resolves the result react-admin expects; it rejects with the error
+ * the network service throws (a non-2xx response, an empty base URL, an auth failure that cannot be
+ * recovered). A subclass overrides the protected hooks (`createNetworkService`, `buildListFilter`,
+ * `requestList`).
+ *
+ * @example
+ * ```ts
+ * import { type BaseArdorApplication, configuration, CoreBindings, DefaultRestDataProvider, inject, provide } from '@venizia/ardor';
+ *
+ * @configuration()
+ * export class DataConfiguration {
+ *   constructor(@inject({ key: CoreBindings.APPLICATION_INSTANCE }) private readonly application: BaseArdorApplication) {}
+ *
+ *   @provide({ key: CoreBindings.REST_DATA_PROVIDER_OPTIONS })
+ *   options() {
+ *     return { url: '/api', noAuthPaths: ['/auth/sign-in'] };
+ *   }
+ *
+ *   @provide({ key: CoreBindings.DEFAULT_REST_DATA_PROVIDER })
+ *   dataProvider() {
+ *     return this.application.instantiate(DefaultRestDataProvider).value(this.application);
+ *   }
+ * }
+ * ```
+ */
 let DefaultRestDataProvider = DefaultRestDataProvider_1 = class DefaultRestDataProvider extends BaseProvider {
     constructor(restDataProviderOptions, applicationInfo) {
         super({ scope: DefaultRestDataProvider_1.name });
@@ -40,6 +86,7 @@ let DefaultRestDataProvider = DefaultRestDataProvider_1 = class DefaultRestDataP
         this.cachedNetworkService ??= this.createNetworkService();
         return this.cachedNetworkService;
     }
+    /** The network service every request of this provider goes through; built on first use. */
     getNetworkService() {
         return this.networkService;
     }
@@ -112,6 +159,11 @@ let DefaultRestDataProvider = DefaultRestDataProvider_1 = class DefaultRestDataP
             return answered ? { ...rest, meta: { extra: answered } } : rest;
         });
     }
+    /**
+     * `GET /{resource}` with the filter built from the list params in the query. Resolves the rows and
+     * `total` (the `Content-Range` total, else the page's row count), plus `meta.extra` when a route
+     * answered extras.
+     */
     async getList(opts) {
         const { resource, params } = opts;
         const { filter, queryKey, extra } = this.buildListFilter({ params });
@@ -123,6 +175,9 @@ let DefaultRestDataProvider = DefaultRestDataProvider_1 = class DefaultRestDataP
             extra,
         });
     }
+    /**
+     * `GET /{resource}/{id}`, with `params.meta.filter` as the query filter. Resolves `{ data }`.
+     */
     async getOne(opts) {
         const { resource, params } = opts;
         const { params: filterParams, ...filter } = params?.meta?.filter ?? {};
@@ -131,10 +186,14 @@ let DefaultRestDataProvider = DefaultRestDataProvider_1 = class DefaultRestDataP
             resource,
             type: RequestTypes.GET_ONE,
             method: RequestMethods.GET,
-            paths: [resource, `${params.id}`],
+            paths: recordPaths({ resource, id: params.id }),
             query: { ...queryKey, filter },
         });
     }
+    /**
+     * `GET /{resource}` with the ids in `filter.where.id.inq`, merged into `params.meta.filter`.
+     * Resolves `{ data }`.
+     */
     async getMany(opts) {
         const { resource, params } = opts;
         const { params: filterParams, ...filter } = params?.meta?.filter ?? {};
@@ -154,6 +213,9 @@ let DefaultRestDataProvider = DefaultRestDataProvider_1 = class DefaultRestDataP
             },
         });
     }
+    /**
+     * As `getList`, with `filter.where[target] = id`. Resolves the rows and `total`.
+     */
     async getManyReference(opts) {
         const { resource, params } = opts;
         const { target, id, ...listParams } = params;
@@ -167,16 +229,22 @@ let DefaultRestDataProvider = DefaultRestDataProvider_1 = class DefaultRestDataP
             extra,
         });
     }
+    /** `PATCH /{resource}/{id}` with `params.data` as the body. Resolves `{ data }`. */
     async update(opts) {
         const { resource, params } = opts;
         return this.request({
             resource,
             type: RequestTypes.UPDATE,
             method: RequestMethods.PATCH,
-            paths: [resource, `${params.id}`],
+            paths: recordPaths({ resource, id: params.id }),
             body: params.data,
         });
     }
+    /**
+     * `PATCH /{resource}` with `{ ...params.data, where: { id: { inq: ids } } }` as the body. Resolves
+     * `{ data }`, the ids of the rows the server answered (`undefined` when the answer is not a row
+     * array). Rejects when `ids` is empty or `params.data` has a `where` field, before any request.
+     */
     async updateMany(opts) {
         const { resource, params } = opts;
         const { ids, data } = params;
@@ -199,6 +267,7 @@ let DefaultRestDataProvider = DefaultRestDataProvider_1 = class DefaultRestDataP
             return { data: this.toAffectedIds({ rows: result.data }) };
         });
     }
+    /** `POST /{resource}` with `params.data` as the body. Resolves `{ data }`, the created record. */
     async create(opts) {
         const { resource, params } = opts;
         return this.request({
@@ -208,15 +277,21 @@ let DefaultRestDataProvider = DefaultRestDataProvider_1 = class DefaultRestDataP
             body: params.data,
         });
     }
+    /** `DELETE /{resource}/{id}`. Resolves `{ data }`, the record the server answered. */
     async delete(opts) {
         const { resource, params } = opts;
         return this.request({
             resource,
             type: RequestTypes.DELETE,
             method: RequestMethods.DELETE,
-            paths: [resource, `${params.id}`],
+            paths: recordPaths({ resource, id: params.id }),
         });
     }
+    /**
+     * `DELETE /{resource}` with `{ where: { id: { inq: ids } } }` as the body. Resolves `{ data }`, the
+     * ids of the rows the server answered (`undefined` when the answer is not a row array). Rejects
+     * when `ids` is empty, before any request.
+     */
     async deleteMany(opts) {
         const { resource, params } = opts;
         const { ids } = params;
@@ -233,6 +308,11 @@ let DefaultRestDataProvider = DefaultRestDataProvider_1 = class DefaultRestDataP
             return { data: this.toAffectedIds({ rows: result.data }) };
         });
     }
+    /**
+     * Sends `params.method` to `/{resource}` with the provider's headers and auth; `requestType`
+     * defaults to `RequestTypes.SEND`. Resolves the response read by that type. Rejects when
+     * `params.method` is missing, before any request.
+     */
     async send(opts) {
         const { resource, params } = opts;
         if (!params?.method) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/ardor-admin",
-  "version": "0.4.8-1",
+  "version": "0.4.8-10",
   "description": "ARDOR react-admin adapter - the REST data provider, auth provider and i18n provider wired through IGNIS inversion, the ArdorApplication root component, the translate and notify hooks, and the English and Vietnamese message bundles.",
   "keywords": [
     "admin",
@@ -57,12 +57,11 @@
     "access": "public"
   },
   "scripts": {
-    "force-update": "sh ../../scripts/build/force-update.sh",
     "prepublishOnly": "make rebuild"
   },
   "dependencies": {
-    "@venizia/ardor-kernel": "0.4.8-1",
-    "@venizia/ardor-react": "0.4.8-1"
+    "@venizia/ardor-kernel": "0.4.8-10",
+    "@venizia/ardor-react": "0.4.8-10"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^21.0.4",
@@ -72,11 +71,11 @@
     "@testing-library/react": "^16.3.3",
     "@types/bun": "^1.4.3",
     "@types/react": "^19",
-    "@venizia/dev-configs": "^0.4.8-0",
-    "@venizia/ignis-filter": "^0.4.7-0",
-    "@venizia/ignis-helpers": "^0.4.8-0",
-    "@venizia/ignis-inversion": "^0.4.7-0",
-    "@venizia/ignis-kernel": "^0.4.8-0",
+    "@venizia/dev-configs": "^0.4.8-5",
+    "@venizia/ignis-filter": "^0.4.7-4",
+    "@venizia/ignis-helpers": "^0.4.8-8",
+    "@venizia/ignis-inversion": "^0.4.7-3",
+    "@venizia/ignis-kernel": "^0.4.8-9",
     "eslint": "^10.13.0",
     "oxlint": "1.89.0",
     "oxlint-tsgolint": "7.0.2004",
@@ -94,10 +93,10 @@
   "peerDependencies": {
     "@reduxjs/toolkit": ">=2.13.0",
     "@tanstack/react-query": ">=5.104.5",
-    "@venizia/ignis-filter": "^0.4.7-0",
-    "@venizia/ignis-helpers": "^0.4.8-0",
-    "@venizia/ignis-inversion": "^0.4.7-0",
-    "@venizia/ignis-kernel": "^0.4.8-0",
+    "@venizia/ignis-filter": "^0.4.7-4",
+    "@venizia/ignis-helpers": "^0.4.8-8",
+    "@venizia/ignis-inversion": "^0.4.7-3",
+    "@venizia/ignis-kernel": "^0.4.8-9",
     "ra-core": ">=5.15.5",
     "ra-i18n-polyglot": ">=5.15.5",
     "react": ">=19.3.1",
@@ -124,7 +123,7 @@
         "react-redux",
         "react-router-dom"
       ],
-      "limit": "10850 B"
+      "limit": "11200 B"
     }
   ],
   "engines": {