xladmin 0.1.8 → 0.2.7

package/README.md

@@ -1,64 +1,82 @@
-# xladmin
+<div align="center">
+  <a href="./README.md">
+    <img src="https://img.shields.io/badge/English-blue?style=for-the-badge" alt="English">
+  </a>
+  <a href="./docs/README.ru.md">
+    <img src="https://img.shields.io/badge/%D0%A0%D1%83%D1%81%D1%81%D0%BA%D0%B8%D0%B9-red?style=for-the-badge" alt="Russian">
+  </a>
+</div>
 
-`xladmin` это React + MUI frontend-пакет для admin UI поверх backend-пакета `xladmin`.
+# xladmin
 
-Важно:
+`xladmin` is the framework-agnostic React frontend for the `xladmin` backend.
 
-- имя пакета в npm: `xladmin`
-- импорт во frontend: `from 'xladmin'`
-- исходники монорепы: [Artasov/xladmin](https://github.com/Artasov/xladmin)
+## Install
 
-## Что есть в библиотеке
+```bash
+npm install xladmin
+```
 
-- transport-agnostic `XLAdminClient`
-- helpers для `axios` и `fetch`
-- `Shell`, `OverviewPage`, `ModelPage`, `ObjectPage`
-- `ModelsBlocks`, `FieldEditor`, `FormDialog`
-- встроенный RU / EN i18n
-- right sidebar list filters from backend `list_filters`
-- форматирование `date` и `datetime`
-- форматирование и редактирование `JSON` полей
-- ширины колонок списка через `FieldConfig.width_px`
-- image-preview через `FieldConfig.display_kind="image"`
-- обрезка длинных текстов в list-view
-- delete preview dialog перед single delete и bulk delete
-- сохранение раскрытости `ModelsBlocks` в `localStorage`
-- встроенная MUI theme `defaultAdminTheme`
+You also need one router adapter:
 
-Короткие имена считаются основными. Старые `Admin*` имена оставлены как alias для совместимости.
+- `xladmin-next`
+- `xladmin-react-router`
 
-## Основной API
+## What It Exports
 
-- `createXLAdminClient(...)`
-- `createAxiosXLAdminClient(...)`
-- `createFetchXLAdminClient(...)`
 - `Shell`
 - `OverviewPage`
 - `ModelPage`
 - `ObjectPage`
-- `ModelsBlocks`
-- `DeletePreviewDialog`
-- `defaultAdminTheme`
+- `FormDialog`
+- `FieldEditor`
+- `NavLink`
+- `createAxiosXLAdminClient(...)`
+- `createFetchXLAdminClient(...)`
+- `createBrowserXLAdminRouter(...)`
+- admin types, i18n helpers, and default theme
+
+## Minimal Example
+
+```tsx
+import {useEffect, useMemo, useState} from 'react';
+import {Shell, OverviewPage, createAxiosXLAdminClient, type AdminModelMeta, type AdminModelsBlockMeta} from 'xladmin';
+import axios from 'axios';
+
+const api = axios.create({baseURL: '/api/admin'});
+
+export function AdminApp() {
+  const client = useMemo(() => createAxiosXLAdminClient(api), []);
+  const [models, setModels] = useState<AdminModelMeta[]>([]);
+  const [blocks, setBlocks] = useState<AdminModelsBlockMeta[]>([]);
 
-## Совместимость
+  useEffect(() => {
+    client.getModels().then((response) => {
+      setModels(response.items);
+      setBlocks(response.blocks);
+    });
+  }, [client]);
 
-- `React >=19,<20`
-- `React DOM >=19,<20`
-- `Next >=15,<17`
-- `@mui/material >=7,<8`
-- `@mui/icons-material >=7,<8`
-- `@mui/x-date-pickers >=8,<9`
-- `dayjs >=1,<2`
-- `axios >=1,<2` — опционально, только если проект использует axios-helper
+  return (
+    <Shell client={client} models={models} blocks={blocks} basePath="/admin" locale="en">
+      <OverviewPage client={client} basePath="/admin" />
+    </Shell>
+  );
+}
+```
 
-## Как подключать
+For framework routing, use one of the adapter packages instead of the default browser router.
 
-Библиотека не требует именно `axios`.
+## Development
 
-Можно использовать:
+```bash
+npm test
+npm run check
+npm run build
+```
 
-- `createAxiosXLAdminClient(api)` — если проект уже живёт на `axios instance`
-- `createFetchXLAdminClient({...})` — если проект работает через `fetch`
-- свой `XLAdminClient` — если проекту нужен полностью свой transport
+## Docs
 
-Практическая интеграция вынесена в [docs/HOW_TO_USE.md](docs/HOW_TO_USE.md).
+- [Russian README](./docs/README.ru.md)
+- [Frontend workspace](../../README.md)
+- [Monorepo root](../../../README.md)

package/dist/cache.d.ts

@@ -0,0 +1,22 @@
+import type { XLAdminClient } from './client';
+import type { AdminDetailResponse, AdminListResponse } from './types';
+type ClientCacheBucket = {
+    detailResponseCache: Map<string, AdminDetailResponse>;
+    inFlightDetailRequests: Map<string, Promise<AdminDetailResponse>>;
+    listResponseCache: Map<string, AdminListResponse>;
+    inFlightListRequests: Map<string, Promise<AdminListResponse>>;
+    modelVersions: Map<string, number>;
+};
+export declare function buildDetailCacheKey(slug: string, id: string | number): string;
+export declare function buildListCacheKey(slug: string, params: {
+    q?: string;
+    sort?: string;
+    limit?: number;
+    offset?: number;
+} & Record<string, unknown>): string;
+export declare function getClientCacheBucket(client: XLAdminClient): ClientCacheBucket;
+export declare function getModelCacheVersion(client: XLAdminClient, slug: string): number;
+export declare function setCachedListResponse(client: XLAdminClient, key: string, response: AdminListResponse): void;
+export declare function setCachedDetailResponse(client: XLAdminClient, key: string, response: AdminDetailResponse): void;
+export declare function invalidateModelCache(client: XLAdminClient, slug: string): void;
+export {};

package/dist/client.d.ts

@@ -1,4 +1,7 @@
 import type { AdminChoicesResponse, AdminDeletePreviewResponse, AdminDetailResponse, AdminListResponse, AdminModelMeta, AdminModelsResponse, AdminObjectActionResponse } from './types';
+export type XLAdminRequestOptions = {
+    signal?: AbortSignal;
+};
 export type XLAdminClient = {
     getModels: () => Promise<AdminModelsResponse>;
     getModel: (slug: string) => Promise<AdminModelMeta>;
@@ -21,19 +24,19 @@ export type XLAdminClient = {
         processed: number;
     } & Record<string, unknown>>;
     runObjectAction: (slug: string, id: string | number, actionSlug: string, payload?: Record<string, unknown>) => Promise<AdminObjectActionResponse>;
-    getChoices: (slug: string, fieldName: string, q?: string, ids?: Array<string | number>) => Promise<AdminChoicesResponse>;
-    getFilterChoices: (slug: string, filterSlug: string, q?: string, ids?: Array<string | number>) => Promise<AdminChoicesResponse>;
+    getChoices: (slug: string, fieldName: string, q?: string, ids?: Array<string | number>, options?: XLAdminRequestOptions) => Promise<AdminChoicesResponse>;
+    getFilterChoices: (slug: string, filterSlug: string, q?: string, ids?: Array<string | number>, options?: XLAdminRequestOptions) => Promise<AdminChoicesResponse>;
 };
 type XLAdminTransportResponse<T> = T | {
     data: T;
 };
 export type XLAdminTransport = {
-    get: <T>(url: string, options?: {
+    get: <T>(url: string, options?: XLAdminRequestOptions & {
         params?: Record<string, unknown>;
     }) => Promise<XLAdminTransportResponse<T>>;
-    post: <T>(url: string, body?: Record<string, unknown>) => Promise<XLAdminTransportResponse<T>>;
-    patch: <T>(url: string, body: Record<string, unknown>) => Promise<XLAdminTransportResponse<T>>;
-    delete: (url: string) => Promise<unknown>;
+    post: <T>(url: string, body?: Record<string, unknown>, options?: XLAdminRequestOptions) => Promise<XLAdminTransportResponse<T>>;
+    patch: <T>(url: string, body: Record<string, unknown>, options?: XLAdminRequestOptions) => Promise<XLAdminTransportResponse<T>>;
+    delete: (url: string, options?: XLAdminRequestOptions) => Promise<unknown>;
 };
 export type XLAdminAxiosLike = XLAdminTransport;
 export type XLAdminFetchClientConfig = {

package/dist/components/ModelPage.d.ts

@@ -1,9 +1,11 @@
 import type { XLAdminClient } from '../client';
+import type { XLAdminRouter } from '../router';
 type AdminModelPageProps = {
     client: XLAdminClient;
     basePath: string;
     slug: string;
+    router?: XLAdminRouter;
 };
 export type ModelPageProps = AdminModelPageProps;
-export declare function ModelPage({ client, basePath, slug }: ModelPageProps): import("react/jsx-runtime").JSX.Element;
+export declare function ModelPage({ client, basePath, slug, router }: ModelPageProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/NavLink.d.ts

@@ -1,11 +1,13 @@
 import type { CSSProperties, ReactNode } from 'react';
+import type { XLAdminRouter } from '../router';
 type AdminNavLinkProps = {
     href: string;
     children: ReactNode;
     style?: CSSProperties;
     title?: string;
     onClick?: () => void;
+    router?: XLAdminRouter;
 };
 export type NavLinkProps = AdminNavLinkProps;
-export declare function NavLink({ href, children, style, title, onClick }: NavLinkProps): import("react/jsx-runtime").JSX.Element;
+export declare function NavLink({ href, children, style, title, onClick, router }: NavLinkProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/ObjectPage.d.ts

@@ -1,11 +1,13 @@
 import 'dayjs/locale/en.js';
 import 'dayjs/locale/ru.js';
 import type { XLAdminClient } from '../client';
+import type { XLAdminRouter } from '../router';
 type AdminObjectPageProps = {
     client: XLAdminClient;
     slug: string;
     id: string;
+    router?: XLAdminRouter;
 };
 export type ObjectPageProps = AdminObjectPageProps;
-export declare function ObjectPage({ client, slug, id }: ObjectPageProps): import("react/jsx-runtime").JSX.Element;
+export declare function ObjectPage({ client, slug, id, router }: ObjectPageProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/Shell.d.ts

@@ -1,6 +1,7 @@
 import type { ReactNode } from 'react';
 import { type Theme } from '@mui/material/styles';
 import type { XLAdminClient } from '../client';
+import type { XLAdminRouter } from '../router';
 import type { AdminModelMeta, AdminModelsBlockMeta } from '../types';
 type AdminShellProps = {
     client: XLAdminClient;
@@ -10,7 +11,8 @@ type AdminShellProps = {
     locale?: string | null;
     children: ReactNode;
     theme?: Theme;
+    router?: XLAdminRouter;
 };
 export type ShellProps = AdminShellProps;
-export declare function Shell({ client, models, blocks, basePath, locale, children, theme }: ShellProps): import("react/jsx-runtime").JSX.Element;
+export declare function Shell({ client, models, blocks, basePath, locale, children, theme, router }: ShellProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/model-page/useModelPageController.d.ts

@@ -0,0 +1,73 @@
+import type { XLAdminClient } from '../../client';
+import type { AdminTranslationKey } from '../../i18n';
+import type { XLAdminRouter } from '../../router';
+import type { AdminDeletePreviewResponse, AdminListResponse } from '../../types';
+type UseModelPageControllerOptions = {
+    client: XLAdminClient;
+    slug: string;
+    pathname: string;
+    locationSearch: string;
+    router: XLAdminRouter;
+    t: (key: AdminTranslationKey, params?: Record<string, string | number>) => string;
+};
+export declare function useModelPageController({ client, slug, pathname, locationSearch, router, t, }: UseModelPageControllerOptions): {
+    allVisibleSelected: boolean;
+    appliedFilters: Record<string, string>;
+    appliedQuery: string;
+    bulkActionMenuAnchor: HTMLElement | null;
+    bulkActions: import("../..").AdminBulkActionMeta[];
+    createOpen: boolean;
+    currentPage: number;
+    data: AdminListResponse | null;
+    deletePreview: AdminDeletePreviewResponse | null;
+    deletePreviewError: string | null;
+    deletePreviewOpen: boolean;
+    error: string | null;
+    fieldMap: Map<string, import("../..").AdminFieldMeta>;
+    filtersOpen: boolean;
+    handleConfirmDelete: () => Promise<void>;
+    handleFilterChange: (filterSlug: string, value: string) => void;
+    handleOpenRowMenu: (event: {
+        currentTarget: HTMLElement;
+    }, rowId: string | number) => void;
+    handlePageChange: (nextPage: number) => void;
+    handlePageInputCommit: () => void;
+    handleResetFilters: () => void;
+    handleRowDelete: (rowId: string | number) => Promise<void>;
+    handleRunNamedBulkAction: (actionSlug: string) => Promise<void>;
+    handleSearchCommit: (nextQuery: string) => void;
+    handleToggleAllVisible: (checked: boolean) => void;
+    handleToggleSelection: (rowId: string | number, checked: boolean) => void;
+    hasListFilters: boolean;
+    hasVisibleSelection: boolean;
+    isDeletePreviewLoading: boolean;
+    isDeleteSubmitting: boolean;
+    isLoading: boolean;
+    listFields: string[];
+    listFilters: import("../..").AdminListFilterMeta[];
+    meta: import("../..").AdminModelMeta | null;
+    pageInput: string;
+    pendingDeleteIds: (string | number)[];
+    pendingDeleteMode: "single" | "bulk";
+    refresh: () => Promise<void>;
+    rowActionMenuAnchor: HTMLElement | null;
+    rowActionMenuId: string | number | null;
+    rows: Record<string, unknown>[];
+    selectedIdSet: Set<string>;
+    selectedIds: (string | number)[];
+    setBulkActionMenuAnchor: import("react").Dispatch<import("react").SetStateAction<HTMLElement | null>>;
+    setCreateOpen: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setDeletePreview: import("react").Dispatch<import("react").SetStateAction<AdminDeletePreviewResponse | null>>;
+    setDeletePreviewError: import("react").Dispatch<import("react").SetStateAction<string | null>>;
+    setDeletePreviewOpen: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setFiltersOpen: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setPageInput: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setPendingDeleteIds: import("react").Dispatch<import("react").SetStateAction<(string | number)[]>>;
+    setRowActionMenuAnchor: import("react").Dispatch<import("react").SetStateAction<HTMLElement | null>>;
+    setRowActionMenuId: import("react").Dispatch<import("react").SetStateAction<string | number | null>>;
+    sortFields: string[];
+    toggleSort: (fieldName: string) => void;
+    total: number;
+    totalPages: number;
+};
+export {};

package/dist/components/object-page/useObjectPageController.d.ts

@@ -0,0 +1,46 @@
+import type { XLAdminClient } from '../../client';
+import type { AdminTranslationKey } from '../../i18n';
+import type { XLAdminRouter } from '../../router';
+import type { AdminDeletePreviewResponse, AdminDetailResponse } from '../../types';
+type UseObjectPageControllerOptions = {
+    client: XLAdminClient;
+    slug: string;
+    id: string;
+    listPath: string;
+    router: XLAdminRouter;
+    t: (key: AdminTranslationKey, params?: Record<string, string | number>) => string;
+};
+export declare function useObjectPageController({ client, slug, id, listPath, router, t, }: UseObjectPageControllerOptions): {
+    actionsAnchorEl: HTMLElement | null;
+    activeActionSlug: string | null;
+    data: AdminDetailResponse | null;
+    deleteConfirmOpen: boolean;
+    deletePreview: AdminDeletePreviewResponse | null;
+    deletePreviewError: string | null;
+    detailFields: string[];
+    editableFieldNames: Set<string>;
+    error: string | null;
+    fieldMap: Map<string, import("../..").AdminFieldMeta>;
+    handleDelete: () => Promise<void>;
+    handleFieldChange: (fieldName: string, nextValue: unknown) => void;
+    handleNavigateBack: () => void;
+    handleOpenDeletePreview: () => Promise<void>;
+    handleRunObjectAction: (actionSlug: string) => Promise<void>;
+    handleSave: () => Promise<void>;
+    initialValues: Record<string, unknown>;
+    isActionsMenuOpen: boolean;
+    isDeletePreviewLoading: boolean;
+    isDeleting: boolean;
+    isDirty: boolean;
+    isLoading: boolean;
+    isSaving: boolean;
+    meta: import("../..").AdminModelMeta | null;
+    objectActions: import("../..").AdminObjectActionMeta[];
+    objectTitle: string;
+    setActionsAnchorEl: import("react").Dispatch<import("react").SetStateAction<HTMLElement | null>>;
+    setDeleteConfirmOpen: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setDeletePreview: import("react").Dispatch<import("react").SetStateAction<AdminDeletePreviewResponse | null>>;
+    setDeletePreviewError: import("react").Dispatch<import("react").SetStateAction<string | null>>;
+    values: Record<string, unknown>;
+};
+export {};

package/dist/hooks/useRemoteChoices.d.ts

@@ -0,0 +1,15 @@
+type UseRemoteChoicesOptions<T> = {
+    enabled: boolean;
+    debounceMs?: number;
+    initialItems?: T[];
+    resetKey?: string;
+    queryKey: string;
+    load: (signal: AbortSignal) => Promise<T[]>;
+    merge?: (current: T[], next: T[]) => T[];
+};
+type UseRemoteChoicesResult<T> = {
+    items: T[];
+    isLoading: boolean;
+};
+export declare function useRemoteChoices<T>({ enabled, debounceMs, initialItems, resetKey, queryKey, load, merge, }: UseRemoteChoicesOptions<T>): UseRemoteChoicesResult<T>;
+export {};

package/dist/i18n.d.ts

@@ -1,6 +1,6 @@
 import { type ReactNode } from 'react';
 import type { AdminLocale } from './types';
-type AdminTranslationKey = 'admin_title' | 'loading' | 'overview' | 'overview_title' | 'overview_subtitle' | 'all_models' | 'all_models_description' | 'models_load_error' | 'model_load_error' | 'object_load_error' | 'object_save_error' | 'object_delete_error' | 'object_action_error' | 'search' | 'filters' | 'active_filters' | 'reset_filters' | 'create' | 'all' | 'actions' | 'selected_count' | 'delete' | 'save' | 'saving' | 'deleting' | 'executing' | 'cancel' | 'objects_count' | 'yes' | 'no' | 'delete_object_title' | 'delete_bulk_title' | 'delete_preview_hint' | 'delete_preview_blocked_hint' | 'delete_preview_roots' | 'delete_preview_delete' | 'delete_preview_protect' | 'delete_preview_set_null' | 'delete_preview_total' | 'delete_preview_empty' | 'delete_preview_loading' | 'delete_preview_error' | 'delete_preview_no_selection' | 'delete_effect_delete' | 'delete_effect_protect' | 'delete_effect_set_null' | 'invalid_json' | 'back' | 'menu' | 'show_details' | 'hide_details' | 'staff_only';
+export type AdminTranslationKey = 'admin_title' | 'loading' | 'overview' | 'overview_title' | 'overview_subtitle' | 'all_models' | 'all_models_description' | 'models_load_error' | 'model_load_error' | 'object_load_error' | 'object_save_error' | 'object_delete_error' | 'object_action_error' | 'search' | 'filters' | 'active_filters' | 'reset_filters' | 'create' | 'all' | 'actions' | 'selected_count' | 'delete' | 'save' | 'saving' | 'deleting' | 'executing' | 'cancel' | 'objects_count' | 'yes' | 'no' | 'delete_object_title' | 'delete_bulk_title' | 'delete_preview_hint' | 'delete_preview_blocked_hint' | 'delete_preview_roots' | 'delete_preview_delete' | 'delete_preview_protect' | 'delete_preview_set_null' | 'delete_preview_total' | 'delete_preview_empty' | 'delete_preview_loading' | 'delete_preview_error' | 'delete_preview_no_selection' | 'delete_effect_delete' | 'delete_effect_protect' | 'delete_effect_set_null' | 'invalid_json' | 'back' | 'menu' | 'show_details' | 'hide_details' | 'staff_only';
 type AdminLocaleProviderProps = {
     locale?: string | null;
     children: ReactNode;

package/dist/index.d.mts

@@ -1,4 +1,5 @@
-export { createAxiosXLAdminClient, createFetchXLAdminClient, createFetchXLAdminTransport, createXLAdminClient, type XLAdminAxiosLike, type XLAdminClient, type XLAdminFetchClientConfig, type XLAdminTransport, } from './client';
+export { createAxiosXLAdminClient, createFetchXLAdminClient, createFetchXLAdminTransport, createXLAdminClient, type XLAdminAxiosLike, type XLAdminClient, type XLAdminFetchClientConfig, type XLAdminRequestOptions, type XLAdminTransport, } from './client';
+export { XLAdminRouterProvider, buildUrlWithParams, createBrowserXLAdminRouter, handleNavLinkClick, type XLAdminAnchorProps, type XLAdminLocation, type XLAdminRouter, useXLAdminLocation, useXLAdminRouter, } from './router';
 export { FormDialog, type FormDialogProps } from './components/FormDialog';
 export { OverviewPage, type OverviewPageProps } from './components/OverviewPage';
 export { ModelPage, type ModelPageProps } from './components/ModelPage';

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { createAxiosXLAdminClient, createFetchXLAdminClient, createFetchXLAdminTransport, createXLAdminClient, type XLAdminAxiosLike, type XLAdminClient, type XLAdminFetchClientConfig, type XLAdminTransport, } from './client';
+export { createAxiosXLAdminClient, createFetchXLAdminClient, createFetchXLAdminTransport, createXLAdminClient, type XLAdminAxiosLike, type XLAdminClient, type XLAdminFetchClientConfig, type XLAdminRequestOptions, type XLAdminTransport, } from './client';
+export { XLAdminRouterProvider, buildUrlWithParams, createBrowserXLAdminRouter, handleNavLinkClick, type XLAdminAnchorProps, type XLAdminLocation, type XLAdminRouter, useXLAdminLocation, useXLAdminRouter, } from './router';
 export { FormDialog, type FormDialogProps } from './components/FormDialog';
 export { OverviewPage, type OverviewPageProps } from './components/OverviewPage';
 export { ModelPage, type ModelPageProps } from './components/ModelPage';