xladmin 0.1.0 → 0.1.5

package/README.md

@@ -1,31 +1,38 @@
 # xladmin
 
-`xladmin` это React/MUI-библиотека для admin UI поверх backend-пакета `xladmin`.
+`xladmin` это React + MUI frontend-пакет для admin UI поверх backend-пакета `xladmin`.
 
 Важно:
 
 - имя пакета в npm: `xladmin`
-- импорты во frontend: `from 'xladmin'`
+- импорт во frontend: `from 'xladmin'`
+- исходники монорепы: [Artasov/xladmin](https://github.com/Artasov/xladmin)
 
 ## Что есть в библиотеке
 
-- `createXLAdminClient(...)` — сборка клиента из любого совместимого transport-объекта
-- `createAxiosXLAdminClient(...)` — готовый helper для `axios`
-- `createFetchXLAdminClient(...)` — готовый helper для `fetch`
-- `AdminShell` — общий layout админки
-- `AdminHome` — главная страница со списком моделей
-- `AdminModelPage` — список объектов модели
-- `AdminObjectPage` — детальная страница объекта
-- `defaultAdminTheme` — встроенная тема библиотеки
-
-Основные файлы:
-
-- `src/client.ts`
-- `src/components/AdminShell.tsx`
-- `src/components/AdminModelPage.tsx`
-- `src/components/AdminObjectPage.tsx`
-- `src/components/AdminFieldEditor.tsx`
-- `src/theme/defaultAdminTheme.ts`
+- transport-agnostic `XLAdminClient`
+- helpers для `axios` и `fetch`
+- `Shell`, `OverviewPage`, `ModelPage`, `ObjectPage`
+- `ModelsBlocks`, `FieldEditor`, `FormDialog`
+- встроенный RU / EN i18n
+- форматирование `date` и `datetime`
+- delete preview dialog перед single delete и bulk delete
+- встроенная MUI theme `defaultAdminTheme`
+
+Короткие имена считаются основными. Старые `Admin*` имена оставлены как alias для совместимости.
+
+## Основной API
+
+- `createXLAdminClient(...)`
+- `createAxiosXLAdminClient(...)`
+- `createFetchXLAdminClient(...)`
+- `Shell`
+- `OverviewPage`
+- `ModelPage`
+- `ObjectPage`
+- `ModelsBlocks`
+- `DeletePreviewDialog`
+- `defaultAdminTheme`
 
 ## Совместимость
 
@@ -36,7 +43,7 @@
 - `@mui/icons-material >=7,<8`
 - `@mui/x-date-pickers >=8,<9`
 - `dayjs >=1,<2`
-- `axios >=1,<2` — опционально, только если проект хочет использовать axios-helper
+- `axios >=1,<2` — опционально, только если проект использует axios-helper
 
 ## Как подключать
 
@@ -44,8 +51,8 @@
 
 Можно использовать:
 
-- `createAxiosXLAdminClient(api)` если у проекта уже есть `axios instance`
-- `createFetchXLAdminClient({...})` если проект работает через `fetch`
-- свой `XLAdminClient`, если проекту нужен полностью свой transport или особая логика
+- `createAxiosXLAdminClient(api)` — если проект уже живёт на `axios instance`
+- `createFetchXLAdminClient({...})` — если проект работает через `fetch`
+- свой `XLAdminClient` — если проекту нужен полностью свой transport
 
-Практическая инструкция вынесена в [docs/HOW_TO_USE.md](docs/HOW_TO_USE.md).
+Практическая интеграция вынесена в [docs/HOW_TO_USE.md](docs/HOW_TO_USE.md).

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AdminChoicesResponse, AdminDetailResponse, AdminListResponse, AdminModelMeta, AdminModelsResponse, AdminObjectActionResponse } from './types';
+import type { AdminChoicesResponse, AdminDeletePreviewResponse, AdminDetailResponse, AdminListResponse, AdminModelMeta, AdminModelsResponse, AdminObjectActionResponse } from './types';
 export type XLAdminClient = {
     getModels: () => Promise<AdminModelsResponse>;
     getModel: (slug: string) => Promise<AdminModelMeta>;
@@ -12,9 +12,11 @@ export type XLAdminClient = {
     createItem: (slug: string, payload: Record<string, unknown>) => Promise<AdminDetailResponse>;
     patchItem: (slug: string, id: string | number, payload: Record<string, unknown>) => Promise<AdminDetailResponse>;
     deleteItem: (slug: string, id: string | number) => Promise<void>;
+    getDeletePreview: (slug: string, id: string | number) => Promise<AdminDeletePreviewResponse>;
     bulkDelete: (slug: string, ids: Array<string | number>) => Promise<{
         deleted: number;
     }>;
+    getBulkDeletePreview: (slug: string, ids: Array<string | number>) => Promise<AdminDeletePreviewResponse>;
     runBulkAction: (slug: string, actionSlug: string, ids: Array<string | number>, payload?: Record<string, unknown>) => Promise<{
         processed: number;
     } & Record<string, unknown>>;

package/dist/components/DeletePreviewDialog.d.ts

@@ -0,0 +1,13 @@
+import type { AdminDeletePreviewResponse } from '../types';
+type DeletePreviewDialogProps = {
+    open: boolean;
+    title: string;
+    preview: AdminDeletePreviewResponse | null;
+    error: string | null;
+    isLoading: boolean;
+    isSubmitting: boolean;
+    onClose: () => void;
+    onConfirm: () => void;
+};
+export declare function DeletePreviewDialog({ open, title, preview, error, isLoading, isSubmitting, onClose, onConfirm, }: DeletePreviewDialogProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/FieldEditor.d.ts

@@ -0,0 +1,13 @@
+import type { XLAdminClient } from '../client';
+import type { AdminFieldMeta } from '../types';
+type AdminFieldEditorProps = {
+    field: AdminFieldMeta;
+    value: unknown;
+    onChange: (value: unknown) => void;
+    slug: string;
+    client: XLAdminClient;
+    readOnly?: boolean;
+};
+export type FieldEditorProps = AdminFieldEditorProps;
+export declare const FieldEditor: import("react").NamedExoticComponent<AdminFieldEditorProps>;
+export {};

package/dist/components/{AdminFormDialog.d.ts → FormDialog.d.ts}

@@ -12,5 +12,6 @@ type AdminFormDialogProps = {
     initialValues?: Record<string, unknown>;
     itemId?: string | number;
 };
-export declare function AdminFormDialog({ open, onClose, onSuccess, title, slug, mode, meta, client, initialValues, itemId, }: AdminFormDialogProps): import("react/jsx-runtime").JSX.Element;
+export type FormDialogProps = AdminFormDialogProps;
+export declare function FormDialog({ open, onClose, onSuccess, title, slug, mode, meta, client, initialValues, itemId, }: FormDialogProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/ModelPage.d.ts

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

package/dist/components/ModelsBlocks.d.ts

@@ -0,0 +1,10 @@
+import type { AdminModelMeta, AdminModelsBlockMeta } from '../types';
+type AdminModelsBlocksProps = {
+    basePath: string;
+    models: AdminModelMeta[];
+    blocks: AdminModelsBlockMeta[];
+    variant: 'sidebar' | 'dashboard';
+};
+export type ModelsBlocksProps = AdminModelsBlocksProps;
+export declare const ModelsBlocks: import("react").NamedExoticComponent<AdminModelsBlocksProps>;
+export {};

package/dist/components/NavLink.d.ts

@@ -0,0 +1,9 @@
+import type { CSSProperties, ReactNode } from 'react';
+type AdminNavLinkProps = {
+    href: string;
+    children: ReactNode;
+    style?: CSSProperties;
+};
+export type NavLinkProps = AdminNavLinkProps;
+export declare function NavLink({ href, children, style }: NavLinkProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/ObjectPage.d.ts

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

package/dist/components/OverviewPage.d.ts

@@ -0,0 +1,8 @@
+import type { XLAdminClient } from '../client';
+type AdminHomeProps = {
+    client: XLAdminClient;
+    basePath: string;
+};
+export type OverviewPageProps = AdminHomeProps;
+export declare function OverviewPage({ client, basePath }: OverviewPageProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Shell.d.ts

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

package/dist/components/layout/Main.d.ts

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react';
+type MainProps = {
+    children: ReactNode;
+};
+/**
+ * Правая часть админки.
+ *
+ * Здесь живёт только текущий контент маршрута без дополнительной логики переходов.
+ */
+export declare function Main({ children }: MainProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/layout/MainHeader.d.ts

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react';
+type MainHeaderProps = {
+    title: ReactNode;
+    subtitle?: ReactNode;
+    details?: ReactNode;
+    error?: string | null;
+};
+/**
+ * Основной заголовок правой панели админки.
+ *
+ * Это именованный компонент, чтобы в DevTools был виден не анонимный `Paper`,
+ * а понятный `MainHeader`.
+ */
+export declare function MainHeader({ title, subtitle, details, error }: MainHeaderProps): import("react/jsx-runtime").JSX.Element;
+type MainHeaderSkeletonProps = {
+    titleWidth?: number | string;
+    subtitleWidth?: number | string;
+};
+export declare function MainHeaderSkeleton({ titleWidth, subtitleWidth, }: MainHeaderSkeletonProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/layout/Sidebar.d.ts

@@ -0,0 +1,8 @@
+import type { AdminModelMeta, AdminModelsBlockMeta } from '../../types';
+type SidebarProps = {
+    models: AdminModelMeta[];
+    blocks: AdminModelsBlockMeta[];
+    basePath: string;
+};
+export declare const Sidebar: import("react").NamedExoticComponent<SidebarProps>;
+export {};

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

@@ -0,0 +1,15 @@
+import type { MouseEvent } from 'react';
+import type { AdminFieldMeta, AdminLocale } from '../../types';
+export type ListRowProps = {
+    row: Record<string, unknown>;
+    pkField: string;
+    listFields: string[];
+    basePath: string;
+    slug: string;
+    locale: AdminLocale;
+    fieldMap: Map<string, AdminFieldMeta>;
+    isSelected: boolean;
+    onToggleSelection: (rowId: string | number, checked: boolean) => void;
+    onOpenMenu: (event: MouseEvent<HTMLElement>, rowId: string | number) => void;
+};
+export declare const ListRow: import("react").NamedExoticComponent<ListRowProps>;

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

@@ -0,0 +1,8 @@
+type SearchFieldProps = {
+    value: string;
+    onCommit: (value: string) => void;
+    debounceMs: number;
+    placeholder?: string;
+};
+export declare const SearchField: import("react").NamedExoticComponent<SearchFieldProps>;
+export {};

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

@@ -0,0 +1,2 @@
+export declare function ModelPageSkeleton(): import("react/jsx-runtime").JSX.Element;
+export declare function ModelTableSkeleton(): import("react/jsx-runtime").JSX.Element;

package/dist/components/models-blocks/BlockTitle.d.ts

@@ -0,0 +1,7 @@
+import type { NormalizedBlock } from './types';
+type BlockTitleProps = {
+    block: NormalizedBlock;
+    compact?: boolean;
+};
+export declare function BlockTitle({ block, compact }: BlockTitleProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/models-blocks/DashboardModelsBlock.d.ts

@@ -0,0 +1,7 @@
+import type { NormalizedBlock } from './types';
+type DashboardModelsBlockProps = {
+    block: NormalizedBlock;
+    basePath: string;
+};
+export declare function DashboardModelsBlock({ block, basePath }: DashboardModelsBlockProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/models-blocks/SidebarModelsBlock.d.ts

@@ -0,0 +1,7 @@
+import type { NormalizedBlock } from './types';
+type SidebarModelsBlockProps = {
+    block: NormalizedBlock;
+    basePath: string;
+};
+export declare function SidebarModelsBlock({ block, basePath }: SidebarModelsBlockProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/models-blocks/surface.d.ts

@@ -0,0 +1,8 @@
+import type { NormalizedBlock } from './types';
+export declare function getBlockSurfaceSx(block: NormalizedBlock, variant: 'sidebar' | 'dashboard'): {
+    backgroundColor: string;
+    backgroundImage?: undefined;
+} | {
+    backgroundColor: string;
+    backgroundImage: string;
+};

package/dist/components/models-blocks/types.d.ts

@@ -0,0 +1,11 @@
+import type { AdminModelMeta } from '../../types';
+export type NormalizedBlock = {
+    slug: string;
+    title: string;
+    description?: string | null;
+    color?: string | null;
+    collapsible: boolean;
+    default_expanded: boolean;
+    models: AdminModelMeta[];
+    isAllModels?: boolean;
+};

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

@@ -0,0 +1,11 @@
+import type { XLAdminClient } from '../../client';
+import type { AdminFieldMeta } from '../../types';
+type ObjectFieldProps = {
+    field: AdminFieldMeta;
+    value: unknown;
+    slug: string;
+    client: XLAdminClient;
+    onFieldChange: (fieldName: string, nextValue: unknown) => void;
+};
+export declare const ObjectField: import("react").NamedExoticComponent<ObjectFieldProps>;
+export {};

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

@@ -0,0 +1 @@
+export declare function ObjectPageSkeleton(): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,7 @@
+import type { AdminFieldMeta } from '../../types';
+type ReadonlyObjectFieldProps = {
+    field: AdminFieldMeta;
+    value: string;
+};
+export declare const ReadonlyObjectField: import("react").NamedExoticComponent<ReadonlyObjectFieldProps>;
+export {};

package/dist/i18n.d.ts

@@ -0,0 +1,13 @@
+import { type ReactNode } from 'react';
+import type { AdminLocale } from './types';
+type AdminTranslationKey = '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' | 'create' | 'actions' | 'selected_count' | 'delete' | 'save' | 'saving' | 'deleting' | 'executing' | 'cancel' | 'objects_count' | 'yes' | 'no' | 'delete_object_title' | 'delete_bulk_title' | 'delete_preview_hint' | 'delete_preview_roots' | 'delete_preview_related' | 'delete_preview_total' | 'delete_preview_empty' | 'delete_preview_loading' | 'delete_preview_error' | 'delete_preview_no_selection' | 'staff_only';
+type AdminLocaleProviderProps = {
+    locale?: string | null;
+    children: ReactNode;
+};
+export declare function normalizeAdminLocale(locale?: string | null): AdminLocale;
+export declare function translateAdmin(locale: string | null | undefined, key: AdminTranslationKey, params?: Record<string, string | number>): string;
+export declare function AdminLocaleProvider({ locale, children }: AdminLocaleProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useAdminLocale(): AdminLocale;
+export declare function useAdminTranslation(): (key: AdminTranslationKey, params?: Record<string, string | number>) => string;
+export {};

package/dist/index.d.mts

@@ -1,9 +1,15 @@
 export { createAxiosXLAdminClient, createFetchXLAdminClient, createFetchXLAdminTransport, createXLAdminClient, type XLAdminAxiosLike, type XLAdminClient, type XLAdminFetchClientConfig, type XLAdminTransport, } from './client';
-export * from './components/AdminFormDialog';
-export * from './components/AdminHome';
-export * from './components/AdminModelPage';
-export * from './components/AdminObjectPage';
-export * from './components/AdminShell';
-export * from './components/AdminSidebar';
+export { FormDialog, type FormDialogProps } from './components/FormDialog';
+export { OverviewPage, type OverviewPageProps } from './components/OverviewPage';
+export { ModelPage, type ModelPageProps } from './components/ModelPage';
+export { ObjectPage, type ObjectPageProps } from './components/ObjectPage';
+export { Shell, type ShellProps } from './components/Shell';
+export { FieldEditor, type FieldEditorProps } from './components/FieldEditor';
+export { NavLink, type NavLinkProps } from './components/NavLink';
+export { ModelsBlocks, type ModelsBlocksProps } from './components/ModelsBlocks';
+export * from './components/DeletePreviewDialog';
+export { MainHeader, MainHeaderSkeleton } from './components/layout/MainHeader';
+export * from './components/layout/Sidebar';
 export * from './theme/defaultAdminTheme';
+export * from './i18n';
 export * from './types';

package/dist/index.d.ts

@@ -1,9 +1,15 @@
 export { createAxiosXLAdminClient, createFetchXLAdminClient, createFetchXLAdminTransport, createXLAdminClient, type XLAdminAxiosLike, type XLAdminClient, type XLAdminFetchClientConfig, type XLAdminTransport, } from './client';
-export * from './components/AdminFormDialog';
-export * from './components/AdminHome';
-export * from './components/AdminModelPage';
-export * from './components/AdminObjectPage';
-export * from './components/AdminShell';
-export * from './components/AdminSidebar';
+export { FormDialog, type FormDialogProps } from './components/FormDialog';
+export { OverviewPage, type OverviewPageProps } from './components/OverviewPage';
+export { ModelPage, type ModelPageProps } from './components/ModelPage';
+export { ObjectPage, type ObjectPageProps } from './components/ObjectPage';
+export { Shell, type ShellProps } from './components/Shell';
+export { FieldEditor, type FieldEditorProps } from './components/FieldEditor';
+export { NavLink, type NavLinkProps } from './components/NavLink';
+export { ModelsBlocks, type ModelsBlocksProps } from './components/ModelsBlocks';
+export * from './components/DeletePreviewDialog';
+export { MainHeader, MainHeaderSkeleton } from './components/layout/MainHeader';
+export * from './components/layout/Sidebar';
 export * from './theme/defaultAdminTheme';
+export * from './i18n';
 export * from './types';