@contember/bindx-react 0.1.0

package/dist/dataview/useDataView.d.ts

@@ -0,0 +1,58 @@
+/**
+ * useDataView — low-level hook for building custom data views.
+ *
+ * Manages filtering, sorting, paging, and selection state, and loads data
+ * from the backend adapter. This is the hook API that DataGrid
+ * uses internally, exposed for building custom grid/list UIs.
+ */
+import type { FilterHandler, FilterArtifact, SelectionMeta, FieldError, SortingDirections, DataViewLayout, SelectionValues } from '@contember/bindx';
+import { type EntityListCoreItem } from '../hooks/useEntityListCore.js';
+import { type FilteringState, type SortingStateResult, type PagingStateResult, type SelectionStateResult } from './useDataViewState.js';
+import type { StateStorageOrName } from './stateStorage.js';
+export interface UseDataViewOptions {
+    /** Filter definitions: name → { handler, initialArtifact? } */
+    filters?: ReadonlyMap<string, {
+        handler: FilterHandler<FilterArtifact>;
+        initialArtifact?: FilterArtifact;
+    }>;
+    /** Fields that can be sorted */
+    sortableFields?: ReadonlySet<string>;
+    /** Initial sorting directions (supports multi-column) */
+    initialSorting?: SortingDirections;
+    /** Items per page. null = show all. Default: 50 */
+    itemsPerPage?: number | null;
+    /** Static filter (always applied) */
+    filter?: Record<string, unknown>;
+    /** Selection metadata for building the query */
+    selection: SelectionMeta;
+    /** Available layouts */
+    layouts?: readonly DataViewLayout[];
+    /** Initial selection (layout + visibility) */
+    initialSelection?: SelectionValues;
+    /** State storage for filter/sorting/selection state */
+    stateStorage?: StateStorageOrName;
+    /** State storage for current page (typically 'url') */
+    currentPageStateStorage?: StateStorageOrName;
+    /** State storage for page size preference (typically 'session' or 'local') */
+    pagingSettingsStorage?: StateStorageOrName;
+    /** Storage key prefix for isolation */
+    storageKey?: string;
+}
+export interface DataViewResult {
+    /** Current load status */
+    readonly status: 'loading' | 'error' | 'ready';
+    /** Error if status is 'error' */
+    readonly error?: FieldError;
+    /** Loaded items */
+    readonly items: readonly EntityListCoreItem[];
+    /** Filtering state and controls */
+    readonly filtering: FilteringState;
+    /** Sorting state and controls */
+    readonly sorting: SortingStateResult;
+    /** Paging state and controls */
+    readonly paging: PagingStateResult;
+    /** Selection state (visibility + layout) */
+    readonly selection: SelectionStateResult;
+}
+export declare function useDataView(entityType: string, options: UseDataViewOptions): DataViewResult;
+//# sourceMappingURL=useDataView.d.ts.map

package/dist/dataview/useDataView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDataView.d.ts","sourceRoot":"","sources":["../../src/dataview/useDataView.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EACX,aAAa,EACb,cAAc,EACd,aAAa,EACb,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,+BAA+B,CAAA;AAC1F,OAAO,EAKN,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAM3D,MAAM,WAAW,kBAAkB;IAClC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;QAAC,eAAe,CAAC,EAAE,cAAc,CAAA;KAAE,CAAC,CAAA;IAC3G,gCAAgC;IAChC,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACpC,yDAAyD;IACzD,cAAc,CAAC,EAAE,iBAAiB,CAAA;IAClC,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAChC,gDAAgD;IAChD,SAAS,EAAE,aAAa,CAAA;IACxB,wBAAwB;IACxB,OAAO,CAAC,EAAE,SAAS,cAAc,EAAE,CAAA;IACnC,8CAA8C;IAC9C,gBAAgB,CAAC,EAAE,eAAe,CAAA;IAClC,uDAAuD;IACvD,YAAY,CAAC,EAAE,kBAAkB,CAAA;IACjC,uDAAuD;IACvD,uBAAuB,CAAC,EAAE,kBAAkB,CAAA;IAC5C,8EAA8E;IAC9E,qBAAqB,CAAC,EAAE,kBAAkB,CAAA;IAC1C,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,cAAc;IAC9B,0BAA0B;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,CAAA;IAC9C,iCAAiC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAA;IAC3B,mBAAmB;IACnB,QAAQ,CAAC,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAC7C,mCAAmC;IACnC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;IAClC,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;IACpC,gCAAgC;IAChC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;IAClC,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,oBAAoB,CAAA;CACxC;AASD,wBAAgB,WAAW,CAC1B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,kBAAkB,GACzB,cAAc,CA8DhB"}

package/dist/dataview/useDataViewState.d.ts

@@ -0,0 +1,89 @@
+/**
+ * State management hooks for DataView filtering, sorting, paging, and selection.
+ *
+ * All hooks support optional state storage (URL, session, local, custom)
+ * for persisting state across navigations.
+ */
+import type { FilterHandler, FilterArtifact, SortingState, SortingDirections, SortingDirectionAction, PagingState, PagingInfo, OrderDirection, DataViewLayout, SelectionValues, SelectionState } from '@contember/bindx';
+import { type StateStorageOrName } from './stateStorage.js';
+export interface RegisteredFilter {
+    readonly name: string;
+    readonly handler: FilterHandler<FilterArtifact>;
+    artifact: FilterArtifact;
+}
+export interface FilteringState {
+    readonly filters: ReadonlyMap<string, RegisteredFilter>;
+    getArtifact(name: string): FilterArtifact | undefined;
+    setArtifact(name: string, artifact: FilterArtifact): void;
+    resetFilter(name: string): void;
+    resetAll(): void;
+    readonly hasActiveFilters: boolean;
+    readonly resolvedWhere: Record<string, unknown> | undefined;
+}
+export interface UseFilteringOptions {
+    filters: ReadonlyMap<string, {
+        handler: FilterHandler<FilterArtifact>;
+        initialArtifact?: FilterArtifact;
+    }>;
+    /** State storage backend. Default: 'null' (no persistence) */
+    stateStorage?: StateStorageOrName;
+    /** Storage key prefix */
+    storageKey?: string;
+}
+export declare function useFilteringState(options: UseFilteringOptions): FilteringState;
+export interface UseSortingOptions {
+    sortableFields: ReadonlySet<string>;
+    initialSorting?: SortingDirections;
+    stateStorage?: StateStorageOrName;
+    storageKey?: string;
+}
+export interface SortingStateResult {
+    readonly state: SortingState;
+    setOrderBy(field: string, action: SortingDirectionAction, append?: boolean): void;
+    clear(): void;
+    directionOf(field: string): OrderDirection | null;
+    readonly resolvedOrderBy: readonly Record<string, unknown>[] | undefined;
+}
+export declare function useSortingState(options: UseSortingOptions): SortingStateResult;
+export interface UsePagingOptions {
+    /** Initial items per page. null = show all. Default: 50 */
+    initialItemsPerPage?: number | null;
+    /** State storage for current page */
+    currentPageStateStorage?: StateStorageOrName;
+    /** State storage for page size preference */
+    pagingSettingsStorage?: StateStorageOrName;
+    /** Storage key prefix */
+    storageKey?: string;
+}
+export interface PagingStateResult {
+    readonly state: PagingState;
+    readonly info: PagingInfo;
+    readonly hasPrevious: boolean;
+    readonly hasNext: boolean;
+    goTo(page: number): void;
+    next(): void;
+    previous(): void;
+    first(): void;
+    last(): void;
+    setItemsPerPage(count: number | null): void;
+    setTotalCount(count: number): void;
+    refreshTotalCount(): void;
+    readonly queryLimit: number | undefined;
+    readonly queryOffset: number | undefined;
+}
+export declare function usePagingState(options?: UsePagingOptions): PagingStateResult;
+export interface UseSelectionOptions {
+    layouts?: readonly DataViewLayout[];
+    initialSelection?: SelectionValues;
+    stateStorage?: StateStorageOrName;
+    storageKey?: string;
+}
+export interface SelectionStateResult {
+    readonly state: SelectionState;
+    setLayout(layout: string | undefined): void;
+    setVisibility(name: string, visible: boolean | undefined): void;
+    isVisible(name: string, fallback?: boolean): boolean;
+    readonly currentLayout: string | undefined;
+}
+export declare function useSelectionState(options?: UseSelectionOptions): SelectionStateResult;
+//# sourceMappingURL=useDataViewState.d.ts.map

package/dist/dataview/useDataViewState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDataViewState.d.ts","sourceRoot":"","sources":["../../src/dataview/useDataViewState.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACX,aAAa,EACb,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,sBAAsB,EACtB,WAAW,EACX,UAAU,EACV,cAAc,EACd,cAAc,EACd,eAAe,EACf,cAAc,EACd,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAM3E,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,CAAA;IAC/C,QAAQ,EAAE,cAAc,CAAA;CACxB;AAED,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;IACvD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAA;IACrD,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAA;IACzD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,QAAQ,IAAI,IAAI,CAAA;IAChB,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAA;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;CAC3D;AAED,MAAM,WAAW,mBAAmB;IACnC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;QAAC,eAAe,CAAC,EAAE,cAAc,CAAA;KAAE,CAAC,CAAA;IAC1G,8DAA8D;IAC9D,YAAY,CAAC,EAAE,kBAAkB,CAAA;IACjC,yBAAyB;IACzB,UAAU,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,mBAAmB,GAAG,cAAc,CA8E9E;AAMD,MAAM,WAAW,iBAAiB;IACjC,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACnC,cAAc,CAAC,EAAE,iBAAiB,CAAA;IAClC,YAAY,CAAC,EAAE,kBAAkB,CAAA;IACjC,UAAU,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAA;IAC5B,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,sBAAsB,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;IACjF,KAAK,IAAI,IAAI,CAAA;IACb,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAAA;IACjD,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,SAAS,CAAA;CACxE;AAsBD,wBAAgB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,kBAAkB,CAkD9E;AAeD,MAAM,WAAW,gBAAgB;IAChC,2DAA2D;IAC3D,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACnC,qCAAqC;IACrC,uBAAuB,CAAC,EAAE,kBAAkB,CAAA;IAC5C,6CAA6C;IAC7C,qBAAqB,CAAC,EAAE,kBAAkB,CAAA;IAC1C,yBAAyB;IACzB,UAAU,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,IAAI,IAAI,IAAI,CAAA;IACZ,QAAQ,IAAI,IAAI,CAAA;IAChB,KAAK,IAAI,IAAI,CAAA;IACb,IAAI,IAAI,IAAI,CAAA;IACZ,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAC3C,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,iBAAiB,IAAI,IAAI,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC;AAED,wBAAgB,cAAc,CAAC,OAAO,GAAE,gBAAqB,GAAG,iBAAiB,CAoFhF;AAMD,MAAM,WAAW,mBAAmB;IACnC,OAAO,CAAC,EAAE,SAAS,cAAc,EAAE,CAAA;IACnC,gBAAgB,CAAC,EAAE,eAAe,CAAA;IAClC,YAAY,CAAC,EAAE,kBAAkB,CAAA;IACjC,UAAU,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;IAC9B,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAA;IAC3C,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,CAAA;IAC/D,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAAA;IACpD,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;CAC1C;AAID,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,mBAAwB,GAAG,oBAAoB,CA8BzF"}

package/dist/hooks/BackendAdapterContext.d.ts

@@ -0,0 +1,110 @@
+import { type ReactNode } from 'react';
+import type { BackendAdapter, MutationDataCollector, SchemaDefinition, UndoManagerConfig, UpdateMode } from '@contember/bindx';
+import { SnapshotStore } from '@contember/bindx';
+import { ActionDispatcher } from '@contember/bindx';
+import { BatchPersister } from '@contember/bindx';
+import { SchemaRegistry } from '@contember/bindx';
+import { UndoManager } from '@contember/bindx';
+import { QueryBatcher } from '../batching/QueryBatcher.js';
+/**
+ * Context value containing all bindx services
+ */
+export interface BindxContextValue {
+    /** Backend adapter for data fetching/persistence */
+    adapter: BackendAdapter;
+    /** Query batcher for combining multiple queries into single requests */
+    batcher: QueryBatcher;
+    /** Immutable snapshot store */
+    store: SnapshotStore;
+    /** Action dispatcher for mutations */
+    dispatcher: ActionDispatcher;
+    /** Batch persister for multi-entity persistence */
+    batchPersister: BatchPersister;
+    /** Schema registry for entity metadata */
+    schema: SchemaRegistry;
+    /** Undo manager (if enabled) */
+    undoManager: UndoManager | null;
+    /** Whether debug logging is enabled */
+    debug: boolean;
+}
+export declare const BindxContext: import("react").Context<BindxContextValue | null>;
+/**
+ * Props for BindxProvider
+ */
+export interface BindxProviderProps {
+    /** The backend adapter to use for data fetching/persistence */
+    adapter: BackendAdapter;
+    /** Optional custom snapshot store (useful for testing) */
+    store?: SnapshotStore;
+    /** Schema definition for entity metadata and mutation collection */
+    schema: SchemaDefinition<Record<string, object>>;
+    /** Optional custom mutation collector (overrides default behavior) */
+    mutationCollector?: MutationDataCollector;
+    /** Enable undo/redo functionality */
+    enableUndo?: boolean;
+    /** Configuration for undo manager */
+    undoConfig?: UndoManagerConfig;
+    /**
+     * Default update mode for persistence operations.
+     * - 'optimistic': Update UI immediately, revert on failure (default)
+     * - 'pessimistic': Wait for server confirmation before updating UI
+     */
+    defaultUpdateMode?: UpdateMode;
+    /** Enable debug logging (e.g., selection collection output) */
+    debug?: boolean;
+    children: ReactNode;
+}
+/**
+ * Provider component that supplies the bindx services
+ * to all child components using bindx hooks.
+ *
+ * @example
+ * ```tsx
+ * const adapter = new MockAdapter(initialData)
+ *
+ * function App() {
+ *   return (
+ *     <BindxProvider adapter={adapter} schema={testSchema}>
+ *       <ArticleEditor id="123" />
+ *     </BindxProvider>
+ *   )
+ * }
+ * ```
+ */
+export declare function BindxProvider({ adapter, store: customStore, schema: schemaDefinition, mutationCollector: customMutationCollector, enableUndo, undoConfig, defaultUpdateMode, debug, children, }: BindxProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the schema registry.
+ * Must be used within a BindxProvider or ContemberBindxProvider.
+ */
+export declare function useSchemaRegistry(): SchemaRegistry;
+/**
+ * Hook to access the backend adapter.
+ * Must be used within a BindxProvider.
+ */
+export declare function useBackendAdapter(): BackendAdapter;
+/**
+ * Hook to access the snapshot store.
+ * Must be used within a BindxProvider.
+ */
+export declare function useSnapshotStore(): SnapshotStore;
+/**
+ * Hook to access the action dispatcher.
+ * Must be used within a BindxProvider.
+ */
+export declare function useDispatcher(): ActionDispatcher;
+/**
+ * Hook to access the batch persister.
+ * Must be used within a BindxProvider.
+ */
+export declare function useBatchPersister(): BatchPersister;
+/**
+ * Hook to access all bindx services.
+ * Must be used within a BindxProvider.
+ */
+export declare function useBindxContext(): BindxContextValue;
+/**
+ * Hook to access the query batcher.
+ * Must be used within a BindxProvider.
+ */
+export declare function useQueryBatcher(): QueryBatcher;
+//# sourceMappingURL=BackendAdapterContext.d.ts.map

package/dist/hooks/BackendAdapterContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BackendAdapterContext.d.ts","sourceRoot":"","sources":["../../src/hooks/BackendAdapterContext.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAC1E,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC9H,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEjD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAE1D;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,oDAAoD;IACpD,OAAO,EAAE,cAAc,CAAA;IACvB,wEAAwE;IACxE,OAAO,EAAE,YAAY,CAAA;IACrB,+BAA+B;IAC/B,KAAK,EAAE,aAAa,CAAA;IACpB,sCAAsC;IACtC,UAAU,EAAE,gBAAgB,CAAA;IAC5B,mDAAmD;IACnD,cAAc,EAAE,cAAc,CAAA;IAC9B,0CAA0C;IAC1C,MAAM,EAAE,cAAc,CAAA;IACtB,gCAAgC;IAChC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAA;IAC/B,uCAAuC;IACvC,KAAK,EAAE,OAAO,CAAA;CACd;AAED,eAAO,MAAM,YAAY,mDAAgD,CAAA;AAEzE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,+DAA+D;IAC/D,OAAO,EAAE,cAAc,CAAA;IACvB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,oEAAoE;IACpE,MAAM,EAAE,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAChD,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,qBAAqB,CAAA;IACzC,qCAAqC;IACrC,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,qCAAqC;IACrC,UAAU,CAAC,EAAE,iBAAiB,CAAA;IAC9B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,UAAU,CAAA;IAC9B,+DAA+D;IAC/D,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,QAAQ,EAAE,SAAS,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,EAC7B,OAAO,EACP,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,gBAAgB,EACxB,iBAAiB,EAAE,uBAAuB,EAC1C,UAAkB,EAClB,UAAU,EACV,iBAAiB,EACjB,KAAa,EACb,QAAQ,GACR,EAAE,kBAAkB,2CAyCpB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAMlD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAMlD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAMhD;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,gBAAgB,CAMhD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAMlD;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,iBAAiB,CAMnD;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAM9C"}

package/dist/hooks/ContemberBindxProvider.d.ts

@@ -0,0 +1,67 @@
+import { type ReactNode } from 'react';
+import { GraphQlClient } from '@contember/graphql-client';
+import { type SchemaNames } from '@contember/client-content';
+import { SnapshotStore, UndoManager, type SchemaDefinition, type UndoManagerConfig, type UpdateMode } from '@contember/bindx';
+/**
+ * Converts SchemaNames (Contember format) to SchemaDefinition (bindx format)
+ * so that a SchemaRegistry can be created for standalone hooks.
+ */
+export declare function schemaNamesToDef(schemaNames: SchemaNames): SchemaDefinition<Record<string, object>>;
+/**
+ * Props for ContemberBindxProvider
+ */
+export interface ContemberBindxProviderProps {
+    /** Contember schema names for query building */
+    schema: SchemaNames;
+    /** Optional custom snapshot store (useful for testing) */
+    store?: SnapshotStore;
+    /** Children */
+    children: ReactNode;
+    client: GraphQlClient;
+    /** Enable undo/redo functionality. Pass true to auto-create an UndoManager, or pass an UndoManager instance. */
+    undoManager?: UndoManager | boolean;
+    /** Configuration for auto-created undo manager (only used when undoManager={true}) */
+    undoConfig?: UndoManagerConfig;
+    /**
+     * Default update mode for persistence operations.
+     * - 'optimistic': Update UI immediately, revert on failure (default)
+     * - 'pessimistic': Wait for server confirmation before updating UI
+     */
+    defaultUpdateMode?: UpdateMode;
+    /** Enable debug logging (e.g., selection collection output) */
+    debug?: boolean;
+}
+/**
+ * Provider component that combines Contember authentication with bindx data binding.
+ *
+ * @example
+ * ```tsx
+ * import { ContemberBindxProvider, useUndo } from '@contember/bindx-react'
+ * import { schema } from './generated/schema'
+ *
+ * function App() {
+ *   return (
+ *     <ContemberBindxProvider
+ *       client={graphQlClient}
+ *       schema={schema}
+ *       undoManager={true}
+ *     >
+ *       <ArticleEditor id="123" />
+ *     </ContemberBindxProvider>
+ *   )
+ * }
+ *
+ * // Access undo/redo in child components
+ * function UndoControls() {
+ *   const { canUndo, canRedo, undo, redo } = useUndo()
+ *   return (
+ *     <div>
+ *       <button onClick={undo} disabled={!canUndo}>Undo</button>
+ *       <button onClick={redo} disabled={!canRedo}>Redo</button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export declare const ContemberBindxProvider: import("react").NamedExoticComponent<ContemberBindxProviderProps>;
+//# sourceMappingURL=ContemberBindxProvider.d.ts.map

package/dist/hooks/ContemberBindxProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContemberBindxProvider.d.ts","sourceRoot":"","sources":["../../src/hooks/ContemberBindxProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AACzD,OAAO,EAAsC,KAAK,WAAW,EAAE,MAAM,2BAA2B,CAAA;AAChG,OAAO,EAAoB,aAAa,EAAuF,WAAW,EAAkB,KAAK,gBAAgB,EAAiB,KAAK,iBAAiB,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAInQ;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,WAAW,GAAG,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAwBnG;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC3C,gDAAgD;IAChD,MAAM,EAAE,WAAW,CAAA;IACnB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,eAAe;IACf,QAAQ,EAAE,SAAS,CAAA;IAEnB,MAAM,EAAE,aAAa,CAAA;IAErB,gHAAgH;IAChH,WAAW,CAAC,EAAE,WAAW,GAAG,OAAO,CAAA;IACnC,sFAAsF;IACtF,UAAU,CAAC,EAAE,iBAAiB,CAAA;IAC9B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,UAAU,CAAA;IAC9B,+DAA+D;IAC/D,KAAK,CAAC,EAAE,OAAO,CAAA;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,sBAAsB,mEA6DjC,CAAA"}

package/dist/hooks/createBindx.d.ts

@@ -0,0 +1,39 @@
+import { type ReactElement } from 'react';
+import { type SchemaDefinition, SchemaRegistry, type SelectionInput } from '@contember/bindx';
+import { type UseEntityOptions, type EntityAccessorResult } from './useEntityImpl.js';
+import { type UseEntityListOptions, type EntityListAccessorResult } from './useEntityListImpl.js';
+import type { ComponentBuilder, ComponentBuilderState, CreateComponentOptions } from '../jsx/componentBuilder.types.js';
+import { type EntityProps } from '../jsx/components/Entity.js';
+import { type EntityListProps } from '../jsx/components/EntityList.js';
+export { COMPONENT_MARKER, COMPONENT_SELECTIONS, type SelectionPropMeta } from '../jsx/componentBuilder.js';
+export type { EntityFields } from '@contember/bindx';
+export type { UseEntityOptions, EntityAccessorResult, LoadingEntityAccessor, ErrorEntityAccessor, NotFoundEntityAccessor, ReadyEntityAccessor } from './useEntityImpl.js';
+export type { UseEntityListOptions, EntityListAccessorResult, LoadingEntityListAccessor, ErrorEntityListAccessor, ReadyEntityListAccessor } from './useEntityListImpl.js';
+/**
+ * Creates type-safe bindx hooks and components for a specific schema.
+ *
+ * @example
+ * ```ts
+ * const schema = defineSchema<{
+ *   Article: Article
+ *   Author: Author
+ * }>({...})
+ *
+ * export const { useEntity, useEntityList, Entity, createComponent } = createBindx(schema)
+ * ```
+ */
+export declare function createBindx<TModels extends {
+    [K in keyof TModels]: object;
+}>(schemaDefinition: SchemaDefinition<TModels>): {
+    useEntity: <TEntityName extends keyof TModels & string, TResult extends object>(entityType: TEntityName, options: UseEntityOptions, definer: SelectionInput<TModels[TEntityName], TResult>) => EntityAccessorResult<TModels[TEntityName], TResult>;
+    useEntityList: <TEntityName extends keyof TModels & string, TResult extends object>(entityType: TEntityName, options: UseEntityListOptions, definer: SelectionInput<TModels[TEntityName], TResult>) => EntityListAccessorResult<TResult>;
+    Entity: <K extends keyof TModels & string>(props: EntityProps<TModels, K>) => ReactElement | null;
+    EntityList: <K extends keyof TModels & string>(props: EntityListProps<TModels, K>) => ReactElement | null;
+    createComponent: {
+        (): ComponentBuilder<TModels, ComponentBuilderState<TModels, {}, object, readonly string[]>>;
+        <TRoles extends readonly string[]>(options: CreateComponentOptions<TRoles>): ComponentBuilder<TModels, ComponentBuilderState<TModels, {}, object, TRoles>>;
+    };
+    schemaRegistry: SchemaRegistry<TModels>;
+    schema: SchemaRegistry<TModels>;
+};
+//# sourceMappingURL=createBindx.d.ts.map

package/dist/hooks/createBindx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createBindx.d.ts","sourceRoot":"","sources":["../../src/hooks/createBindx.tsx"],"names":[],"mappings":"AAAA,OAAc,EAAE,KAAK,YAAY,EAAE,MAAM,OAAO,CAAA;AAChD,OAAO,EACN,KAAK,gBAAgB,EACrB,cAAc,EACd,KAAK,cAAc,EAGnB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAiB,KAAK,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AACpG,OAAO,EAAqB,KAAK,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,wBAAwB,CAAA;AAQpH,OAAO,KAAK,EACX,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,MAAM,kCAAkC,CAAA;AACzC,OAAO,EAAU,KAAK,WAAW,EAAE,MAAM,6BAA6B,CAAA;AACtE,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,iCAAiC,CAAA;AAGlF,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,KAAK,iBAAiB,EAAE,MAAM,4BAA4B,CAAA;AAG3G,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACpD,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACzK,YAAY,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AAMzK;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,OAAO,SAAS;KAAG,CAAC,IAAI,MAAM,OAAO,GAAG,MAAM;CAAE,EAC3E,gBAAgB,EAAE,gBAAgB,CAAC,OAAO,CAAC;gBAqBxB,WAAW,SAAS,MAAM,OAAO,GAAG,MAAM,EAAE,OAAO,SAAS,MAAM,cACxE,WAAW,WACd,gBAAgB,WAChB,cAAc,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC,KACpD,oBAAoB,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;oBAiB/B,WAAW,SAAS,MAAM,OAAO,GAAG,MAAM,EAAE,OAAO,SAAS,MAAM,cAC5E,WAAW,WACd,oBAAoB,WACpB,cAAc,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC,KACpD,wBAAwB,CAAC,OAAO,CAAC;aAYf,CAAC,SAAS,MAAM,OAAO,GAAG,MAAM,SAAS,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,KAAG,YAAY,GAAG,IAAI;iBAIlF,CAAC,SAAS,MAAM,OAAO,GAAG,MAAM,SAAS,eAAe,CAAC,OAAO,EAAE,CAAC,CAAC,KAAG,YAAY,GAAG,IAAI;;YAQvF,gBAAgB,CAAC,OAAO,EAAE,qBAAqB,CAAC,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;SAC3F,MAAM,SAAS,SAAS,MAAM,EAAE,WAC/C,sBAAsB,CAAC,MAAM,CAAC,GAErC,gBAAgB,CAAC,OAAO,EAAE,qBAAqB,CAAC,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;;;;EAkBhF"}

package/dist/hooks/index.d.ts

@@ -0,0 +1,10 @@
+export { BindxProvider, useBackendAdapter, useSnapshotStore, useDispatcher, useBatchPersister, useBindxContext, useSchemaRegistry, type BindxProviderProps, type BindxContextValue, } from './BackendAdapterContext.js';
+export { usePersist, usePersistEntity, type PersistApi, type EntityPersistApi, type AnyRefWithMeta, } from './usePersist.js';
+export { useEntity, type UseEntityOptions, type LoadingEntityAccessor, type ErrorEntityAccessor, type NotFoundEntityAccessor, type ReadyEntityAccessor, type EntityAccessorResult, } from './useEntity.js';
+export { useEntityList, type UseEntityListOptions, type LoadingEntityListAccessor, type ErrorEntityListAccessor, type ReadyEntityListAccessor, type EntityListAccessorResult, } from './useEntityList.js';
+export { ContemberBindxProvider, schemaNamesToDef, } from './ContemberBindxProvider.js';
+export { useUndo, type UndoHookResult } from './useUndo.js';
+export { useOnEvent, useOnEntityEvent, useOnFieldEvent, useIntercept, useInterceptEntity, useInterceptField, } from './useBindxEvents.js';
+export { useEntityBeforePersist } from './useEntityBeforePersist.js';
+export { useEntityErrors, type EntityErrorsState, } from './useErrors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,GACtB,MAAM,4BAA4B,CAAA;AAEnC,OAAO,EACN,UAAU,EACV,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,cAAc,GACnB,MAAM,iBAAiB,CAAA;AAExB,OAAO,EACN,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GACzB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EACN,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,GAC7B,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EACN,sBAAsB,EACtB,gBAAgB,GAChB,MAAM,6BAA6B,CAAA;AAEpC,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAA;AAE3D,OAAO,EACN,UAAU,EACV,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,GACjB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAA;AAEpE,OAAO,EACN,eAAe,EACf,KAAK,iBAAiB,GACtB,MAAM,gBAAgB,CAAA"}

package/dist/hooks/useBindxEvents.d.ts

@@ -0,0 +1,83 @@
+import type { EventTypeMap, AfterEventTypes, BeforeEventTypes, EventListener, Interceptor } from '@contember/bindx';
+/**
+ * Subscribe to a global bindx event.
+ * Automatically handles subscription lifecycle and cleanup.
+ *
+ * @example
+ * ```tsx
+ * useOnEvent('field:changed', (event) => {
+ *   console.log('Any field changed:', event)
+ * })
+ * ```
+ */
+export declare function useOnEvent<T extends AfterEventTypes>(eventType: T, listener: EventListener<EventTypeMap[T]>): void;
+/**
+ * Subscribe to an entity-scoped bindx event.
+ * Automatically handles subscription lifecycle and cleanup.
+ *
+ * @example
+ * ```tsx
+ * useOnEntityEvent('entity:persisted', 'Article', articleId, (event) => {
+ *   toast.success('Article saved!')
+ * })
+ * ```
+ */
+export declare function useOnEntityEvent<T extends AfterEventTypes>(eventType: T, entityType: string, entityId: string, listener: EventListener<EventTypeMap[T]>): void;
+/**
+ * Subscribe to a field-scoped bindx event.
+ * Automatically handles subscription lifecycle and cleanup.
+ *
+ * @example
+ * ```tsx
+ * useOnFieldEvent('field:changed', 'Article', articleId, 'title', (event) => {
+ *   console.log('Title changed:', event.oldValue, '->', event.newValue)
+ * })
+ * ```
+ */
+export declare function useOnFieldEvent<T extends AfterEventTypes>(eventType: T, entityType: string, entityId: string, fieldName: string, listener: EventListener<EventTypeMap[T]>): void;
+/**
+ * Add a global interceptor for a before event.
+ * Automatically handles subscription lifecycle and cleanup.
+ *
+ * @example
+ * ```tsx
+ * useIntercept('field:changing', (event) => {
+ *   if (event.newValue === '') {
+ *     return { action: 'cancel' }
+ *   }
+ *   return { action: 'continue' }
+ * })
+ * ```
+ */
+export declare function useIntercept<T extends BeforeEventTypes>(eventType: T, interceptor: Interceptor<EventTypeMap[T]>): void;
+/**
+ * Add an entity-scoped interceptor.
+ * Automatically handles subscription lifecycle and cleanup.
+ *
+ * @example
+ * ```tsx
+ * useInterceptEntity('entity:persisting', 'Article', articleId, (event) => {
+ *   if (!isValid) {
+ *     return { action: 'cancel' }
+ *   }
+ *   return { action: 'continue' }
+ * })
+ * ```
+ */
+export declare function useInterceptEntity<T extends BeforeEventTypes>(eventType: T, entityType: string, entityId: string, interceptor: Interceptor<EventTypeMap[T]>): void;
+/**
+ * Add a field-scoped interceptor.
+ * Automatically handles subscription lifecycle and cleanup.
+ *
+ * @example
+ * ```tsx
+ * useInterceptField('field:changing', 'Article', articleId, 'title', (event) => {
+ *   if (event.newValue === '') {
+ *     return { action: 'cancel' }
+ *   }
+ *   return { action: 'continue' }
+ * })
+ * ```
+ */
+export declare function useInterceptField<T extends BeforeEventTypes>(eventType: T, entityType: string, entityId: string, fieldName: string, interceptor: Interceptor<EventTypeMap[T]>): void;
+//# sourceMappingURL=useBindxEvents.d.ts.map

package/dist/hooks/useBindxEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBindxEvents.d.ts","sourceRoot":"","sources":["../../src/hooks/useBindxEvents.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACX,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,MAAM,kBAAkB,CAAA;AAMzB;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,eAAe,EACnD,SAAS,EAAE,CAAC,EACZ,QAAQ,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GACtC,IAAI,CAgBN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,eAAe,EACzD,SAAS,EAAE,CAAC,EACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GACtC,IAAI,CAgBN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,eAAe,EACxD,SAAS,EAAE,CAAC,EACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GACtC,IAAI,CAgBN;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,gBAAgB,EACtD,SAAS,EAAE,CAAC,EACZ,WAAW,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GACvC,IAAI,CAgBN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,gBAAgB,EAC5D,SAAS,EAAE,CAAC,EACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GACvC,IAAI,CAgBN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,gBAAgB,EAC3D,SAAS,EAAE,CAAC,EACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GACvC,IAAI,CAgBN"}

package/dist/hooks/useEntity.d.ts

@@ -0,0 +1,123 @@
+import type { EntityDef, EntityUniqueWhere, SelectionInput, SelectionMeta, FieldError, SelectedEntityFields, CommonEntity, EntityForRoles, RoleNames } from '@contember/bindx';
+/**
+ * Options for useEntity hook
+ */
+export interface UseEntityOptions {
+    /** Unique field(s) to identify the entity (e.g., { id: '...' } or { slug: '...' }) */
+    by: EntityUniqueWhere;
+    /** If true, use cached data from store if available (default: false) */
+    cache?: boolean;
+    /**
+     * Pre-resolved selection metadata.
+     * When provided, definer (3rd argument) is not needed.
+     * Used internally by Entity component.
+     */
+    selection?: SelectionMeta;
+    /** Optional query key for cache invalidation */
+    queryKey?: string;
+}
+/**
+ * Loading state for entity accessor
+ */
+export interface LoadingEntityAccessor {
+    readonly status: 'loading';
+    readonly isLoading: true;
+    readonly isError: false;
+    readonly isNotFound: false;
+    readonly isPersisting: false;
+    readonly isDirty: false;
+    readonly id: string;
+    readonly fields: never;
+    readonly data: never;
+    persist(): Promise<void>;
+    reset(): void;
+}
+/**
+ * Error state for entity accessor
+ */
+export interface ErrorEntityAccessor {
+    readonly status: 'error';
+    readonly isLoading: false;
+    readonly isError: true;
+    readonly isNotFound: false;
+    readonly error: FieldError;
+    readonly isPersisting: false;
+    readonly isDirty: false;
+    readonly id: string;
+    readonly fields: never;
+    readonly data: never;
+    persist(): Promise<void>;
+    reset(): void;
+}
+/**
+ * Not found state for entity accessor
+ */
+export interface NotFoundEntityAccessor {
+    readonly status: 'not_found';
+    readonly isLoading: false;
+    readonly isError: false;
+    readonly isNotFound: true;
+    readonly isPersisting: false;
+    readonly isDirty: false;
+    readonly id: string;
+    readonly fields: never;
+    readonly data: never;
+    persist(): Promise<void>;
+    reset(): void;
+}
+/**
+ * Ready state base interface for entity accessor
+ */
+export interface ReadyEntityAccessorBase<TEntity extends object, TSelected extends object = TEntity> {
+    readonly status: 'ready';
+    readonly isLoading: false;
+    readonly isError: false;
+    readonly isNotFound: false;
+    readonly isPersisting: boolean;
+    readonly isDirty: boolean;
+    readonly id: string;
+    readonly fields: SelectedEntityFields<TEntity, TSelected>;
+    readonly data: TSelected;
+    persist(): Promise<void>;
+    reset(): void;
+}
+/**
+ * Ready state for entity accessor with direct field access via Proxy.
+ */
+export type ReadyEntityAccessor<TEntity extends object, TSelected extends object = TEntity> = ReadyEntityAccessorBase<TEntity, TSelected> & SelectedEntityFields<TEntity, TSelected>;
+/**
+ * Union of all entity accessor states
+ */
+export type EntityAccessorResult<TEntity extends object, TSelected extends object = TEntity> = LoadingEntityAccessor | ErrorEntityAccessor | NotFoundEntityAccessor | ReadyEntityAccessor<TEntity, TSelected>;
+/**
+ * Hook to fetch and manage a single entity with role-expanded type inference.
+ *
+ * @example
+ * ```tsx
+ * const article = useEntity(schema.Article, { by: { id }, roles: ['admin'] }, e => e.title().internalNotes())
+ * ```
+ */
+export declare function useEntity<TRoleMap extends Record<string, object>, TRoles extends RoleNames<TRoleMap>, TResult extends object>(entity: EntityDef<TRoleMap>, options: UseEntityOptions & {
+    roles: readonly TRoles[];
+}, definer: SelectionInput<EntityForRoles<TRoleMap, TRoles>, TResult>): EntityAccessorResult<EntityForRoles<TRoleMap, TRoles>, TResult>;
+/**
+ * Hook to fetch and manage a single entity with full type inference.
+ * Uses the common (narrowest) entity type when no roles are specified.
+ *
+ * @example
+ * ```tsx
+ * const article = useEntity(schema.Article, { by: { id } }, e => e.title().content())
+ * if (article.status !== 'ready') return <Loading />
+ * return <input value={article.title.value} onChange={...} />
+ * ```
+ */
+export declare function useEntity<TRoleMap extends Record<string, object>, TResult extends object>(entity: EntityDef<TRoleMap>, options: UseEntityOptions, definer: SelectionInput<CommonEntity<TRoleMap>, TResult>): EntityAccessorResult<CommonEntity<TRoleMap>, TResult>;
+/**
+ * Hook to fetch and manage a single entity with pre-resolved selection.
+ *
+ * Used internally by Entity component that collects selection from JSX.
+ */
+export declare function useEntity(entity: EntityDef, options: UseEntityOptions & {
+    selection: SelectionMeta;
+}): EntityAccessorResult<object, object>;
+//# sourceMappingURL=useEntity.d.ts.map

package/dist/hooks/useEntity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useEntity.d.ts","sourceRoot":"","sources":["../../src/hooks/useEntity.ts"],"names":[],"mappings":"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"}