@rebasepro/types 0.0.1-canary.eae7889 → 0.1.0

package/dist/types/slots.d.ts

@@ -100,7 +100,8 @@ export interface NavigationSlotProps {
 export interface CollectionToolbarProps {
     path: string;
     collection: EntityCollection;
-    parentCollectionIds: string[];
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
     tableController: EntityTableController;
     selectionController: SelectionController;
 }
@@ -111,7 +112,8 @@ export interface CollectionToolbarProps {
 export interface CollectionEmptyStateProps {
     path: string;
     collection: EntityCollection;
-    parentCollectionIds: string[];
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
     canCreate: boolean;
     onNewClick?: () => void;
 }
@@ -123,7 +125,8 @@ export interface CollectionHeaderActionProps {
     property: Property;
     propertyKey: string;
     path: string;
-    parentCollectionIds: string[];
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
     onHover: boolean;
     collection: EntityCollection;
     tableController: EntityTableController;
@@ -134,7 +137,8 @@ export interface CollectionHeaderActionProps {
  */
 export interface CollectionAddColumnProps {
     path: string;
-    parentCollectionIds: string[];
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
     collection: EntityCollection;
     tableController: EntityTableController;
 }
@@ -145,7 +149,8 @@ export interface CollectionAddColumnProps {
 export interface CollectionErrorProps {
     path: string;
     collection: EntityCollection;
-    parentCollectionIds?: string[];
+    parentCollectionSlugs?: string[];
+    parentEntityIds?: string[];
     error: Error;
 }
 /**
@@ -155,7 +160,8 @@ export interface CollectionErrorProps {
 export interface KanbanSetupProps {
     collection: EntityCollection;
     fullPath: string;
-    parentCollectionIds: string[];
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
 }
 /**
  * Props for the `kanban.add-column` slot.
@@ -164,7 +170,8 @@ export interface KanbanSetupProps {
 export interface KanbanAddColumnProps {
     collection: EntityCollection;
     fullPath: string;
-    parentCollectionIds: string[];
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
     columnProperty: string;
 }
 /**
@@ -177,7 +184,8 @@ export interface EntityRowActionsProps {
     entityId: string;
     path: string;
     collection: EntityCollection;
-    parentCollectionIds: string[];
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
     selectionController: SelectionController;
     context: RebaseContext;
 }
@@ -202,7 +210,8 @@ export interface EntityFieldSlotProps {
 export interface CollectionFilterPanelProps {
     path: string;
     collection: EntityCollection;
-    parentCollectionIds: string[];
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
     tableController: EntityTableController;
     context: RebaseContext;
 }
@@ -238,7 +247,8 @@ export interface ShellToolbarProps {
 export interface CollectionInsightsSlotProps {
     path: string;
     collection: EntityCollection;
-    parentCollectionIds: string[];
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
 }
 /**
  * Props for `home.card.insight` slot.

package/dist/types/translations.d.ts

@@ -51,6 +51,8 @@ export interface RebaseTranslations {
     all_entries_loaded: string;
     create_your_first_entry: string;
     no_results_filter_sort: string;
+    /** Shown when a text search yields no results. Supports `{{search}}` interpolation. */
+    no_results_search?: string;
     add: string;
     remove: string;
     copy_id: string;
@@ -461,6 +463,10 @@ export interface RebaseTranslations {
     reset_password_success?: string;
     reset_password_confirmation?: string;
     error_resetting_password?: string;
+    /** Permission-denied empty states */
+    no_permission_to_view_users?: string;
+    no_permission_to_view_roles?: string;
+    no_permission_description?: string;
     /** Editor table-bubble */
     add_row_before: string;
     add_row_after: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/types",
   "type": "module",
-  "version": "0.0.1-canary.eae7889",
+  "version": "0.1.0",
   "description": "Rebase type definitions — shared interfaces and controller types",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -39,9 +39,6 @@
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@jest/globals": "^29.7.0",
-    "@testing-library/react": "^16.3.0",
-    "@testing-library/user-event": "^14.6.1",
     "@types/jest": "^29.5.14",
     "@types/node": "^20.17.14",
     "@types/object-hash": "^3.0.6",
@@ -49,14 +46,9 @@
     "@types/react-dom": "^19.0.3",
     "@types/react-measure": "^2.0.12",
     "@vitejs/plugin-react": "^4.3.4",
-    "babel-plugin-react-compiler": "beta",
-    "cross-env": "^7.0.3",
     "eslint-plugin-react-compiler": "beta",
     "jest": "^29.7.0",
-    "npm-run-all": "^4.1.5",
     "ts-jest": "^29.3.1",
-    "ts-node": "^10.9.2",
-    "tsd": "^0.31.2",
     "typescript": "^5.8.3",
     "vite": "^5.4.17"
   },

package/src/controllers/auth.tsx

@@ -98,8 +98,11 @@ export type AuthController<USER extends User = User, ExtraData = unknown> = {
 export interface AuthControllerExtended<USER extends User = User, ExtraData = unknown> extends AuthController<USER, ExtraData> {
     /** Login with email and password */
     emailPasswordLogin?(email: string, password: string): Promise<void>;
-    /** Login with a Google ID token or trigger Google popup */
-    googleLogin?(idToken: string): Promise<void>;
+    /** Login with a Google token or authorization code */
+    googleLogin?: {
+        (token: string, tokenType?: "idToken" | "accessToken"): Promise<void>;
+        (payload: { code: string; redirectUri: string }): Promise<void>;
+    };
     /** Register a new user */
     register?(email: string, password: string, displayName?: string): Promise<void>;
     /** Skip login (for anonymous access if enabled) */

package/src/controllers/client.ts

@@ -130,4 +130,19 @@ export interface RebaseClient<DB = unknown> {
 
     /** Admin API for user and role management */
     admin?: AdminAPI;
+
+    /**
+     * The base HTTP URL of the backend server.
+     * Exposed by the SDK client (`@rebasepro/client`) and used to auto-derive
+     * the `ApiConfigProvider` URL.
+     */
+    baseUrl?: string;
+
+    /**
+     * WebSocket client for realtime subscriptions and admin capabilities.
+     * Exposed by the SDK client (`@rebasepro/client`). The shape is intentionally
+     * left as `unknown` in the base interface — callers should narrow via feature
+     * detection (e.g. `typeof ws.executeSql === "function"`).
+     */
+    ws?: unknown;
 }

package/src/controllers/collection_registry.ts

@@ -46,7 +46,8 @@ export type CollectionRegistryController<
      * Retrieve all the related parent collection ids for a given path
      * @param path
      */
-    getParentCollectionIds: (path: string) => string[];
+    getParentCollectionSlugs: (path: string) => string[];
+    getParentEntityIds: (path: string) => string[];
 
     /**
      * Resolve paths from a list of ids

package/src/controllers/data_driver.ts

@@ -179,7 +179,8 @@ export interface DataDriver {
         path: string,
         databaseId?: string,
         collection: EntityCollection,
-        parentCollectionIds?: string[]
+        parentCollectionSlugs?: string[];
+        parentEntityIds?: string[];
     }) => Promise<boolean>;
 
     /**
@@ -187,6 +188,15 @@ export interface DataDriver {
      */
     needsInitTextSearch?: boolean;
 
+    // ── REST fetch capabilities ─────────────────────────────────────────
+
+    /**
+     * Optional REST-optimised fetch service. When present, the REST API
+     * generator uses these methods instead of the generic `fetchEntity` /
+     * `fetchCollection` pipeline, enabling include-aware eager-loading.
+     */
+    restFetchService?: RestFetchService;
+
     // ── Admin capabilities ─────────────────────────────────────────────
     //
     // Admin operations are now modelled as capability-specific interfaces
@@ -205,3 +215,42 @@ export interface DataDriver {
     admin?: import("../types/backend").DatabaseAdmin;
 
 }
+
+/**
+ * REST-optimised fetch service exposed by drivers that support
+ * eager-loading of relations via `include`.
+ *
+ * The methods return flattened rows (`{ id, ...columns }`) rather
+ * than the `Entity<M>` wrapper used by the generic DataDriver API.
+ *
+ * @group DataDriver
+ */
+export interface RestFetchService {
+    /**
+     * Fetch a collection of flattened entities with optional relation includes.
+     */
+    fetchCollectionForRest(
+        collectionPath: string,
+        options?: {
+            filter?: FilterValues<string>;
+            orderBy?: string;
+            order?: "desc" | "asc";
+            limit?: number;
+            offset?: number;
+            startAfter?: Record<string, unknown>;
+            searchString?: string;
+            databaseId?: string;
+        },
+        include?: string[]
+    ): Promise<Record<string, unknown>[]>;
+
+    /**
+     * Fetch a single flattened entity with optional relation includes.
+     */
+    fetchEntityForRest(
+        collectionPath: string,
+        entityId: string | number,
+        include?: string[],
+        databaseId?: string
+    ): Promise<Record<string, unknown> | null>;
+}

package/src/controllers/navigation.ts

@@ -172,17 +172,18 @@ export interface AppView {
     hideFromNavigation?: boolean;
 
     /**
-     * Component to be rendered. This can be any React component, and can use
-     * any of the provided hooks
+     * Navigation group for this view.
+     * Views sharing the same group name will be visually grouped
+     * together in the drawer and home page. If not set, the view
+     * falls into the default "Views" group.
      */
-    view: React.ReactNode;
+    group?: string;
 
     /**
-     * Optional field used to group top level navigation entries under a
-     * navigation view.
-     * This prop is ignored for admin views.
+     * Component to be rendered. This can be any React component, and can use
+     * any of the provided hooks
      */
-    group?: string;
+    view: React.ReactNode;
 
     /**
      * If true, a wildcard route (slug/*) is automatically registered
@@ -227,6 +228,17 @@ export interface NavigationGroupMapping {
      * List of collection ids or view paths that belong to this group.
      */
     entries: string[];
+    /**
+     * Configure which groups start collapsed.
+     * Set to `true` to collapse in both drawer and home page,
+     * or use an object to control each independently.
+     *
+     * @defaultValue false (expanded)
+     */
+    collapsedByDefault?: boolean | {
+        drawer?: boolean;
+        home?: boolean;
+    };
 }
 
 export interface NavigationEntry {

package/src/controllers/registry.ts

@@ -3,7 +3,7 @@ import type { EntityCollection } from "../types/collections";
 import type { EntityCollectionsBuilder } from "../types/builders";
 import type { EntityCustomView } from "../types/entity_views";
 import type { EntityAction } from "../types/entity_actions";
-import type { AppView } from "./navigation";
+import type { AppView, NavigationGroupMapping } from "./navigation";
 
 /**
  * Options to enable the built-in collection editor.
@@ -28,6 +28,15 @@ export interface RebaseCMSConfig<EC extends EntityCollection = any> {
     entityActions?: EntityAction[];
     plugins?: any[];
 
+    /**
+     * Centralized configuration for how collections and views are grouped
+     * in the navigation sidebar and home page.
+     * Each mapping defines a named group and the collection/view slugs
+     * that belong to it. The array order determines group display order.
+     * Entry order within each group determines card order.
+     */
+    navigationGroupMappings?: NavigationGroupMapping[];
+
     /**
      * Enable the built-in visual collection/schema editor.
      * Pass `true` for zero-config, or an options object for fine-grained control.

package/src/controllers/side_entity_controller.tsx

@@ -73,6 +73,14 @@ export interface EntitySidePanelProps<M extends Record<string, unknown> = Record
      * Allow the user to open the entity fullscreen
      */
     allowFullScreen?: boolean;
+
+    /**
+     * Pre-populate the form with these values when creating a new entity.
+     * Only applied when `entityId` is not set (i.e. the form is in "new" mode).
+     * Useful for actions that fetch data from an external source (e.g. a URL)
+     * and want to pre-fill the document before the user saves.
+     */
+    defaultValues?: Partial<M>;
 }
 
 /**

package/src/rebase_context.tsx

@@ -3,6 +3,7 @@ import type { AuthController } from "./controllers/auth";
 import type { StorageSource } from "./controllers/storage";
 import type { UserConfigurationPersistence } from "./controllers/local_config_persistence";
 import type { DatabaseAdmin } from "./types/backend";
+import type { RebaseClient } from "./controllers/client";
 
 import type { RebaseData } from "./controllers/data";
 import type { User } from "./users";
@@ -16,6 +17,23 @@ import type { UserManagementDelegate } from "./types/user_management_delegate";
  */
 export type RebaseCallContext<USER extends User = User> = {
 
+    /**
+     * The Rebase client instance.
+     * Available in all entity callbacks (beforeSave, afterSave, afterRead,
+     * beforeDelete, afterDelete) and in CollectionActionsProps via context.
+     * Use it to call backend functions, access data, storage, etc.
+     *
+     * @example
+     * // In a beforeSave callback:
+     * const result = await context.client.functions.invoke('my-function', { ... });
+     *
+     * @example
+     * // In a CollectionAction component:
+     * const { client } = props.context;
+     * const result = await client.functions.invoke('extract-job', { url });
+     */
+    client: RebaseClient<any>;
+
     /**
      * Unified data access — `context.data.products.create(...)`.
      * Access any collection as a dynamic property.

package/src/types/backend_hooks.ts

@@ -0,0 +1,185 @@
+import type { AdminUser, AdminRole } from "../controllers/client";
+
+/**
+ * Context passed to every backend hook.
+ * Provides information about the request that triggered the hook.
+ * @group Backend Hooks
+ */
+export interface BackendHookContext {
+    /** The currently authenticated user making the request (if any) */
+    requestUser?: { userId: string; roles: string[] };
+    /** The HTTP method of the request */
+    method: "GET" | "POST" | "PUT" | "DELETE";
+}
+
+/**
+ * Hooks for intercepting Admin User data at the API boundary.
+ *
+ * These hooks run on the server after the database operation completes
+ * but before the response is sent to the client.
+ *
+ * @group Backend Hooks
+ */
+export interface UserHooks {
+    /**
+     * Transform a user record after it's read from the database,
+     * before it's returned to the client.
+     *
+     * Return the modified user, or `null` to filter it out entirely
+     * (the user won't appear in listings or individual fetches).
+     */
+    afterRead?(user: AdminUser, context: BackendHookContext): AdminUser | null | Promise<AdminUser | null>;
+
+    /**
+     * Transform user data before it's written to the database.
+     * Runs on POST (create) and PUT (update).
+     *
+     * Return the (possibly modified) data to proceed with the save.
+     * Throw an error to abort the operation.
+     */
+    beforeSave?(data: { email?: string; displayName?: string; roles?: string[] }, context: BackendHookContext): { email?: string; displayName?: string; roles?: string[] } | Promise<{ email?: string; displayName?: string; roles?: string[] }>;
+
+    /**
+     * Called after a user is successfully created or updated.
+     * Useful for side-effects like sending notifications.
+     */
+    afterSave?(user: AdminUser, context: BackendHookContext): void | Promise<void>;
+
+    /**
+     * Called before a user is deleted. Throw to prevent deletion.
+     */
+    beforeDelete?(userId: string, context: BackendHookContext): void | Promise<void>;
+
+    /**
+     * Called after a user is successfully deleted.
+     */
+    afterDelete?(userId: string, context: BackendHookContext): void | Promise<void>;
+}
+
+/**
+ * Hooks for intercepting Admin Role data at the API boundary.
+ * @group Backend Hooks
+ */
+export interface RoleHooks {
+    /**
+     * Transform a role record after it's read from the database,
+     * before it's returned to the client.
+     *
+     * Return the modified role, or `null` to filter it out entirely.
+     */
+    afterRead?(role: AdminRole, context: BackendHookContext): AdminRole | null | Promise<AdminRole | null>;
+}
+
+/**
+ * Hooks for intercepting collection entity data at the REST API boundary.
+ *
+ * These run **after** per-collection `EntityCallbacks` (which execute inside
+ * the DataDriver) and provide a single cross-cutting interception point for
+ * ALL collections flowing through the REST API.
+ *
+ * Every callback receives the collection `slug` so you can target specific
+ * collections or apply logic globally.
+ *
+ * @group Backend Hooks
+ */
+export interface DataHooks {
+    /**
+     * Transform an entity after it's read from the database,
+     * before it's returned to the client.
+     *
+     * Runs for both list (GET /:slug) and single (GET /:slug/:id) fetches.
+     * Return the modified entity, or `null` to filter it out.
+     *
+     * @param slug - The collection slug (e.g. "orders", "products")
+     * @param entity - The flattened entity object (id + values merged)
+     * @param context - Request context (authenticated user, HTTP method)
+     */
+    afterRead?(slug: string, entity: Record<string, unknown>, context: BackendHookContext): Record<string, unknown> | null | Promise<Record<string, unknown> | null>;
+
+    /**
+     * Transform entity values before they are written to the database.
+     * Runs on POST (create) and PUT (update).
+     *
+     * Return the (possibly modified) values. Throw to abort the save.
+     *
+     * @param slug - The collection slug
+     * @param values - The raw request body values
+     * @param entityId - The entity ID (only present on updates)
+     * @param context - Request context
+     */
+    beforeSave?(slug: string, values: Record<string, unknown>, entityId: string | undefined, context: BackendHookContext): Record<string, unknown> | Promise<Record<string, unknown>>;
+
+    /**
+     * Called after an entity is successfully saved (created or updated).
+     * Useful for side-effects like syncing to external systems.
+     *
+     * @param slug - The collection slug
+     * @param entity - The saved entity (flattened)
+     * @param context - Request context
+     */
+    afterSave?(slug: string, entity: Record<string, unknown>, context: BackendHookContext): void | Promise<void>;
+
+    /**
+     * Called before an entity is deleted. Throw to prevent deletion.
+     *
+     * @param slug - The collection slug
+     * @param entityId - The entity ID being deleted
+     * @param context - Request context
+     */
+    beforeDelete?(slug: string, entityId: string, context: BackendHookContext): void | Promise<void>;
+
+    /**
+     * Called after an entity is successfully deleted.
+     *
+     * @param slug - The collection slug
+     * @param entityId - The deleted entity ID
+     * @param context - Request context
+     */
+    afterDelete?(slug: string, entityId: string, context: BackendHookContext): void | Promise<void>;
+}
+
+/**
+ * Backend-level hooks for intercepting data at the API boundary.
+ *
+ * These hooks run server-side after database operations complete and before
+ * API responses are sent.
+ *
+ * - `users` / `roles` — intercept admin user and role management endpoints
+ * - `data` — intercept ALL collection entity data flowing through the REST API
+ *
+ * `data` hooks complement per-collection `EntityCallbacks`. Entity callbacks
+ * run inside the DataDriver (close to the DB); data hooks run at the HTTP
+ * boundary (close to the client). Use data hooks for cross-cutting concerns
+ * like audit logging, response enrichment, or field masking.
+ *
+ * @example
+ * ```typescript
+ * const hooks: BackendHooks = {
+ *     data: {
+ *         afterRead(slug, entity, ctx) {
+ *             // Mask PII for non-admin users across all collections
+ *             if (!ctx.requestUser?.roles.includes("admin") && entity.email) {
+ *                 return { ...entity, email: "***" };
+ *             }
+ *             return entity;
+ *         }
+ *     },
+ *     users: {
+ *         afterRead(user, ctx) {
+ *             if (user.email.endsWith("@system.internal")) return null;
+ *             return user;
+ *         }
+ *     }
+ * };
+ * ```
+ *
+ * @group Backend Hooks
+ */
+export interface BackendHooks {
+    /** Hooks for intercepting user management data */
+    users?: UserHooks;
+    /** Hooks for intercepting role management data */
+    roles?: RoleHooks;
+    /** Hooks for intercepting ALL collection entity data via the REST API */
+    data?: DataHooks;
+}

package/src/types/collections.ts

@@ -10,6 +10,7 @@ import type { RebaseContext } from "../rebase_context";
 import type { Relation } from "./relations";
 import type { EntityCustomView } from "./entity_views";
 import type { EntityAction } from "./entity_actions";
+import type { ComponentRef } from "./component_ref";
 
 /**
  * Base interface containing all driver-agnostic collection properties.
@@ -22,9 +23,8 @@ import type { EntityAction } from "./entity_actions";
 export interface BaseEntityCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> {
 
     /**
-     * You can set an alias that will be used internally instead of the `path`.
-     * The `alias` value will be used to determine the URL of the collection,
-     * while `path` will still be used in the driver.
+     * You can set an alias that will be used internally instead of the collection name.
+     * The `slug` value will be used to determine the URL of the collection.
      * Note that you can use this value in reference properties too.
      */
     slug: string;
@@ -100,6 +100,9 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
 
     /**
      * Navigation group for this collection.
+     * Collections sharing the same group name will be visually grouped
+     * together in the drawer and home page. If not set, the collection
+     * falls into the default "Views" group.
      */
     group?: string;
 
@@ -184,18 +187,18 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
     /**
      * Force a filter in this view. If applied, the rest of the filters will
      * be disabled. Filters applied with this prop cannot be changed.
-     * e.g. `forceFilter: { age: [">", 18] }`
-     * e.g. `forceFilter: { related_user: ["==", new EntityReference("sdc43dsw2", "users")] }`
+     * e.g. `fixedFilter: { age: [">", 18] }`
+     * e.g. `fixedFilter: { related_user: ["==", new EntityReference("sdc43dsw2", "users")] }`
      */
-    readonly forceFilter?: FilterValues<Extract<keyof M, string> | (string & {})>;
+    readonly fixedFilter?: FilterValues<Extract<keyof M, string> | (string & {})>;
 
     /**
      * Initial filters applied to the collection this collection is related to.
      * Defaults to none. Filters applied with this prop can be changed.
-     * e.g. `filter: { age: [">", 18] }`
-     * e.g. `filter: { related_user: ["==", new EntityReference("sdc43dsw2", "users")] }`
+     * e.g. `defaultFilter: { age: [">", 18] }`
+     * e.g. `defaultFilter: { related_user: ["==", new EntityReference("sdc43dsw2", "users")] }`
      */
-    readonly filter?: FilterValues<Extract<keyof M, string> | (string & {})>; // setting FilterValues<M> can break defining collections by code
+    readonly defaultFilter?: FilterValues<Extract<keyof M, string> | (string & {})>; // setting FilterValues<M> can break defining collections by code
 
     /**
      * Default sort applied to this collection.
@@ -352,7 +355,7 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
     /**
      * Builder for the collection actions rendered in the toolbar
      */
-    Actions?: React.ComponentType<any>[];
+    Actions?: ComponentRef<CollectionActionsProps>[];
 
 
 }
@@ -370,6 +373,7 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
  */
 export interface PostgresCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>
     extends BaseEntityCollection<M, USER> {
+    properties: Properties;
 
     /**
      * The driver for this collection. For Postgres collections this
@@ -417,7 +421,6 @@ export interface PostgresCollection<M extends Record<string, unknown> = Record<s
  */
 export interface FirebaseCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>
     extends BaseEntityCollection<M, USER> {
-
     /**
      * The driver for this collection. Must be set to `"firestore"`.
      */
@@ -554,7 +557,8 @@ export interface CollectionActionsProps<M extends Record<string, unknown> = Reco
     /**
      * Array of the parent path segments like `['users']`
      */
-    parentCollectionIds: string[];
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
 
     /**
      * The collection configuration
@@ -584,6 +588,22 @@ export interface CollectionActionsProps<M extends Record<string, unknown> = Reco
      */
     collectionEntitiesCount?: number;
 
+    /**
+     * Programmatically open the new-document form for this collection,
+     * optionally pre-populating it with initial field values.
+     * The form opens in the same mode configured for the collection
+     * (side panel, full screen, or split).
+     *
+     * This is the primary hook for workflows that need to create a document
+     * from external data — e.g. fetching content from a URL, importing from
+     * a third-party API, or duplicating from another system.
+     *
+     * @example
+     * // Inside a custom CollectionAction component:
+     * openNewDocument({ title: "Fetched title", body: "..." });
+     */
+    openNewDocument: (defaultValues?: Record<string, unknown>) => void;
+
 }
 
 /**