xladmin 0.9.0 → 0.10.0

package/README.md

@@ -11,6 +11,12 @@
 
 `xladmin` is the framework-agnostic React frontend for the `xladmin` backend.
 
+## Read-only models
+
+`AdminModelMeta.read_only` is a required boolean supplied by the backend. When true, model and object pages hide create, edit, delete and action controls; mutation handlers also reject submissions. List navigation, filters and selection for export remain available. `FormDialog` closes through its normal transition and disables pending submission when the model becomes read-only.
+
+`ModelPageToolbarContext.meta.read_only` exposes the same policy to extensions. The import/export extension hides import and blocks validation/commit for read-only models while retaining export. Update backend, frontend and the extension together: these controls require backend metadata support and do not replace server-side authorization or domain commands.
+
 ## Install
 
 ```bash
@@ -111,6 +117,16 @@ If your application already has the user or a custom logout flow, pass them expl
 
 Set `currentUser={null}` to hide the sidebar user panel.
 
+## Scoped navigation and client lifetime
+
+Every `AdminRouter` implements `resolveHref(href)`. The browser, Next.js and React Router adapters return the original URL. A host can override this method to preserve its workspace or tenant query parameter. `NavLink` uses the resolved URL both in the native anchor and in click navigation, so copying links and opening another tab retain the same context. Keep the resolver pure and idempotent; apply the same resolver in host `push`/`replace` wrappers for programmatic navigation. Custom router implementations must provide this method; tenant selection and authorization remain application concerns.
+
+When the authenticated user or workspace changes, create a new `AdminClient` and remount the workspace subtree with a different React key. Caches are isolated by client identity. The object controller ignores late reads and mutation completions after its scope is retired, including navigation after deletion. The host should also cancel its old transport and prevent new requests through retired clients. Cancelling a request does not roll back an operation already accepted by the server.
+
+## Item response contracts
+
+`getItem` returns `AdminDetailResponse` with `{meta, item}`. `createItem` and `patchItem` return `AdminItemResponse` with `{item}` only. Custom clients and transport mocks must use the same response shapes. After saving an object, retain its loaded metadata and replace its item with the server response; do not read mutation metadata that the HTTP API does not return.
+
 ## Development
 
 ```bash

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AdminChoicesResponse, AdminDeletePreviewResponse, AdminDetailResponse, AdminCurrentUser, AdminListResponse, AdminModelMeta, AdminModelsResponse, AdminObjectActionResponse } from './types';
+import type { AdminChoicesResponse, AdminDeletePreviewResponse, AdminDetailResponse, AdminItemResponse, AdminCurrentUser, AdminListResponse, AdminModelMeta, AdminModelsResponse, AdminObjectActionResponse } from './types';
 export type AdminRequestOptions = {
     signal?: AbortSignal;
 };
@@ -22,8 +22,8 @@ export type AdminClient = {
         sort?: string;
     } & Record<string, unknown>) => Promise<AdminListResponse>;
     getItem: (slug: string, id: string | number) => Promise<AdminDetailResponse>;
-    createItem: (slug: string, payload: Record<string, unknown>) => Promise<AdminDetailResponse>;
-    patchItem: (slug: string, id: string | number, payload: Record<string, unknown>) => Promise<AdminDetailResponse>;
+    createItem: (slug: string, payload: Record<string, unknown>) => Promise<AdminItemResponse>;
+    patchItem: (slug: string, id: string | number, payload: Record<string, unknown>) => Promise<AdminItemResponse>;
     deleteItem: (slug: string, id: string | number) => Promise<void>;
     getDeletePreview: (slug: string, id: string | number) => Promise<AdminDeletePreviewResponse>;
     bulkDelete: (slug: string, ids: Array<string | number>, options?: AdminSelectionOptions) => Promise<{

package/dist/components/ModelPage.d.ts

@@ -15,6 +15,7 @@ export type ModelPageToolbarContext = {
     meta: {
         slug: string;
         title: string;
+        read_only: boolean;
     };
     selectedIds: Array<string | number>;
     isAllMatchingSelected: boolean;

package/dist/components/form-dialog/useAdminFormSession.d.ts

@@ -0,0 +1,25 @@
+import type { AdminClient } from '../../client';
+import type { AdminEditableFieldMeta } from '../../types';
+type FormSessionOptions = {
+    client: AdminClient;
+    identity: string;
+    open: boolean;
+    fields: AdminEditableFieldMeta[];
+    initialValues?: Record<string, unknown>;
+    errorFallback: string;
+    onClose: () => void;
+};
+/** Owns one opening of a form, independently of metadata reference refreshes. */
+export declare function useAdminFormSession({ client, identity, open, fields, initialValues, errorFallback, onClose }: FormSessionOptions): {
+    values: Record<string, unknown>;
+    error: string | null;
+    isSubmitting: boolean;
+    editorVersion: number;
+    openPickerFieldName: string | null;
+    changeField: (name: string, value: unknown) => void;
+    requestPickerOpen: (name: string) => void;
+    requestPickerClose: (name: string) => void;
+    submit: (operation: (payload: Record<string, unknown>) => Promise<unknown>, onSuccess: () => void) => Promise<void>;
+    close: () => void;
+};
+export {};

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

@@ -1,7 +1,9 @@
 import type { ReactNode } from 'react';
 type ShellContextValue = {
-    isMobile: boolean;
-    openMobileSidebar: () => void;
+    hasSidebar: boolean;
+    sidebarId: string;
+    isSidebarOpen: boolean;
+    toggleSidebar: () => void;
     pendingPath: string | null;
     pendingView: 'overview' | 'model' | 'generic' | null;
     startPendingNavigation: (path: string, view?: 'overview' | 'model' | 'generic') => void;

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

@@ -9,6 +9,7 @@ export type ListRowProps = {
     locale: AdminLocale;
     fieldMap: Map<string, AdminFieldMeta>;
     isSelected: boolean;
+    canWrite: boolean;
     onToggleSelection: (rowId: string | number, checked: boolean) => void;
     onOpenMenu: (event: MouseEvent<HTMLElement>, rowId: string | number) => void;
 };

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

@@ -0,0 +1,10 @@
+import type { AdminClient } from '../../client';
+type AdminListRequestParams = {
+    limit?: number;
+    offset?: number;
+    q?: string;
+    sort?: string;
+    [key: string]: unknown;
+};
+export declare function requestListItems(client: AdminClient, slug: string, params: AdminListRequestParams, requestKey: string): Promise<import("../..").AdminListResponse>;
+export {};

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

@@ -11,6 +11,9 @@ type UseModelPageControllerOptions = {
     t: (key: AdminTranslationKey, params?: Record<string, string | number>) => string;
 };
 export declare function useModelPageController({ client, slug, pathname, locationSearch, router, t, }: UseModelPageControllerOptions): {
+    canWrite: boolean;
+    bulkActionFormOpen: boolean;
+    isBulkSubmitting: boolean;
     allVisibleSelected: boolean;
     appliedFilters: Record<string, string>;
     appliedQuery: string;

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

@@ -5,6 +5,7 @@ type ObjectFieldProps = {
     value: unknown;
     slug: string;
     client: AdminClient;
+    readOnly: boolean;
     onFieldChange: (fieldName: string, nextValue: unknown) => void;
 };
 export declare const ObjectField: import("react").NamedExoticComponent<ObjectFieldProps>;

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

@@ -0,0 +1,2 @@
+/** Refresh server-owned fields without discarding an unsaved card draft. */
+export declare function mergeObjectActionValues(values: Record<string, unknown>, baseline: Record<string, unknown>, item: Record<string, unknown>, editableNames: ReadonlySet<string>): Record<string, unknown>;

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

@@ -11,6 +11,7 @@ type UseObjectPageControllerOptions = {
     t: (key: AdminTranslationKey, params?: Record<string, string | number>) => string;
 };
 export declare function useObjectPageController({ client, slug, id, listPath, router, t, }: UseObjectPageControllerOptions): {
+    canWrite: boolean;
     actionsAnchorEl: HTMLElement | null;
     activeActionSlug: string | null;
     activeObjectAction: import("@xladmin-core/types").AdminObjectActionMeta | null;
@@ -23,6 +24,7 @@ export declare function useObjectPageController({ client, slug, id, listPath, ro
     error: string | null;
     fieldMap: Map<string, import("@xladmin-core/types").AdminFieldMeta>;
     handleDelete: () => Promise<void>;
+    handleCloseDeletePreview: () => void;
     handleFieldChange: (fieldName: string, nextValue: unknown) => void;
     handleNavigateBack: () => void;
     handleOpenDeletePreview: () => Promise<void>;
@@ -37,13 +39,12 @@ export declare function useObjectPageController({ client, slug, id, listPath, ro
     isDirty: boolean;
     isLoading: boolean;
     isSaving: boolean;
+    isMutating: boolean;
+    objectActionFormOpen: boolean;
     meta: import("@xladmin-core/types").AdminModelMeta | null;
     objectActions: import("@xladmin-core/types").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 {};