@rebasepro/types 0.0.1-canary.0

package/src/types/property_config.tsx

@@ -0,0 +1,93 @@
+import React from "react";
+import { ArrayProperty, MapProperty, Property } from "./properties";
+
+import { BooleanProperty, DateProperty, GeopointProperty, NumberProperty, ReferenceProperty, RelationProperty, StringProperty } from "./properties";
+
+export type ConfigProperty =
+    | (Omit<StringProperty, "name"> & { name?: string })
+    | (Omit<NumberProperty, "name"> & { name?: string })
+    | (Omit<BooleanProperty, "name"> & { name?: string })
+    | (Omit<DateProperty, "name"> & { name?: string })
+    | (Omit<GeopointProperty, "name"> & { name?: string })
+    | (Omit<ReferenceProperty, "name"> & { name?: string })
+    | (Omit<RelationProperty, "name"> & { name?: string })
+    | (Omit<ArrayProperty, "name" | "of" | "oneOf"> & {
+        name?: string;
+        of?: ConfigProperty | ConfigProperty[];
+        oneOf?: { properties: Record<string, ConfigProperty>; typeField?: string; valueField?: string; propertiesOrder?: string[] }
+    })
+    | (Omit<MapProperty, "name" | "properties"> & {
+        name?: string;
+        properties?: Record<string, ConfigProperty>
+    });
+
+/**
+ * This is the configuration object for a property.
+ * These configs are generated by default for the properties defined in your
+ * collections' configuration, but you can define your own to be used.
+ */
+export type PropertyConfig = {
+
+    /**
+     * Key used to identify this property config.
+     */
+    key: PropertyConfigId | string;
+
+    /**
+     * Name of this field type.
+     * This is not the name of the property.
+     */
+    name: string;
+
+    /**
+     * Default config for the property.
+     * This property or builder will be used as the base values for the resulting property.
+     * You can also use a builder function to generate the base property.
+     */
+    property: ConfigProperty;
+
+    /**
+     * Optional icon to be used in the field selector.
+     * Use a 24x24 component, in order not to break the layout.
+     * Any Rebase icon can be used.
+     */
+    Icon?: React.ComponentType;
+
+    /**
+     * CSS color, used only in some plugins like the field selector.
+     * e.g. "#2d7ff9"
+     */
+    color?: string;
+
+    /**
+     * Description of this field type.
+     */
+    description?: string;
+
+}
+
+export type PropertyConfigId =
+    "text_field" |
+    "multiline" |
+    "markdown" |
+    "url" |
+    "email" |
+    "user_select" |
+    "select" |
+    "multi_select" |
+    "number_input" |
+    "number_select" |
+    "multi_number_select" |
+    "file_upload" |
+    "multi_file_upload" |
+    "group" |
+    "key_value" |
+    "reference" |
+    "reference_as_string" |
+    "multi_references" |
+    "relation" |
+    "switch" |
+    "date_time" |
+    "repeat" |
+    "custom_array" |
+    "block";

package/src/types/rebase.tsx

@@ -0,0 +1,211 @@
+import React from "react";
+import { EntityCollection, EntityCustomView } from "./collections";
+import { PropertyConfig } from "./property_config";
+import { Locale } from "./locales";
+import { EntityLinkBuilder } from "./entity_link_builder";
+import { RebasePlugin } from "./plugins";
+import { EntityAction } from "./entity_actions";
+import { User } from "../users";
+import {
+    AuthController, CMSAnalyticsEvent, CMSView, DataSource, StorageSource,
+    UserConfigurationPersistence, CollectionRegistryController, CMSUrlController, NavigationStateController
+} from "../controllers";
+import { RebaseContext } from "../rebase_context";
+import { UserManagementDelegate } from "./user_management_delegate";
+
+/**
+ * Controller to simulate different roles when dev mode is active.
+ * @group Models
+ */
+export interface EffectiveRoleController {
+    effectiveRole: string | null;
+    setEffectiveRole: (role: string | null) => void;
+}
+
+/**
+ * Use this callback to build entity collections dynamically.
+ * You can use the user to decide which collections to show.
+ * You can also use the data source to fetch additional data to build the
+ * collections.
+ * Note: you can use any type of synchronous or asynchronous code here,
+ * including fetching data from external sources, like using the Firestore
+ * APIs directly, or a REST API.
+ * @group Models
+ */
+export type EntityCollectionsBuilder<EC extends EntityCollection = EntityCollection> = (params: {
+    user: User | null,
+    authController: AuthController,
+    dataSource: DataSource
+}) => EC[] | Promise<EC[]>;
+
+/**
+ * Use this callback to build custom views dynamically.
+ * You can use the user to decide which views to show.
+ * You can also use the data source to fetch additional data to build the
+ * views. Note: you can use any type of synchronous or asynchronous code here,
+ * including fetching data from external sources, like using the Firestore
+ * APIs directly, or a REST API.
+ * @group Models
+ */
+export type CMSViewsBuilder = (params: {
+    user: User | null,
+    authController: AuthController,
+    dataSource: DataSource
+}) => CMSView[] | Promise<CMSView[]>;
+
+/**
+ * @group Models
+ */
+export type RebaseProps<USER extends User> = {
+
+    /**
+     * Use this function to return the components you want to render under
+     * Rebase
+     * @param props
+     */
+    children: (props: {
+        /**
+         * Context of the app
+         */
+        context: RebaseContext;
+        /**
+         * Is one of the main processes, auth and navigation resolving, currently
+         * loading. If you are building your custom implementation, you probably
+         * want to show a loading indicator if this flag is `true`
+         */
+        loading: boolean;
+    }) => React.ReactNode;
+
+    /**
+     * If you have a custom API key, you can use it here.
+     */
+    apiKey?: string;
+
+    /**
+     * Base URL for the backend API (e.g. "http://localhost:3001").
+     * When provided, this is available via `useApiConfig()` to any hook
+     * in the tree, reducing repetitive `apiUrl` threading.
+     */
+    apiUrl?: string;
+
+    /**
+     * Record of custom form fields to be used in the CMS.
+     * You can use the key to reference the custom field in
+     * the `propertyConfig` prop of a property in a collection.
+     */
+    propertyConfigs?: Record<string, PropertyConfig>;
+
+    /**
+     * This controller is in charge of resolving the collection and entity paths.
+     */
+    collectionRegistryController: CollectionRegistryController;
+
+    /**
+     * This controller is in charge of resolving the URL configurations map and building paths
+     */
+    cmsUrlController: CMSUrlController;
+
+    /**
+     * This controller is in charge of resolving the navigation views and state
+     */
+    navigationStateController: NavigationStateController;
+
+    /**
+     * List of additional custom views for entities.
+     * You can use the key to reference the custom view in
+     * the `entityViews` prop of a collection.
+     *
+     * You can also define an entity view from the UI.
+     */
+    entityViews?: EntityCustomView[];
+
+    /**
+     * List of actions that can be performed on entities.
+     * These actions are displayed in the entity view and in the collection view.
+     * You can later reuse these actions in the `entityActions` prop of a collection,
+     * by specifying the `key` of the action.
+     */
+    entityActions?: EntityAction[];
+
+    /**
+     * Format of the dates in the CMS.
+     * Defaults to 'MMMM dd, yyyy, HH:mm:ss'
+     */
+    dateTimeFormat?: string;
+
+    /**
+     * Locale of the CMS, currently only affecting dates
+     */
+    locale?: Locale;
+
+    /**
+     * Connector to your database
+     */
+    dataSource: DataSource;
+
+    /**
+     * Connector to your file upload/fetch implementation
+     */
+    storageSource: StorageSource;
+
+    /**
+     * Delegate for implementing your auth operations.
+     */
+    authController: AuthController<USER>;
+
+    /**
+     * Use this controller to access the configuration that is stored locally,
+     * and not defined in code
+     */
+    userConfigPersistence?: UserConfigurationPersistence;
+
+    /**
+     * Use plugins to modify the behaviour of the CMS.
+     * DEPRECATED: use the `plugins` prop in the `useBuildNavigationController` instead.
+     * This prop will work as a fallback for the `plugins` prop in the `useBuildNavigationController`.
+     * @deprecated
+     */
+    plugins?: RebasePlugin<any, any, any>[];
+
+    /**
+     * Callback used to get analytics events from the CMS
+     */
+    onAnalyticsEvent?: (event: CMSAnalyticsEvent, data?: object) => void;
+
+    /**
+     * Optional link builder you can add to generate a button in your entity forms.
+     * The function must return a URL that gets opened when the button is clicked
+     */
+    entityLinkBuilder?: EntityLinkBuilder;
+
+    /**
+     * You can use this props to provide your own user management implementation.
+     * Note that this will not affect the UI, but it will be used to show user information
+     * in various places of the CMS, for example, to show who created or modified an entity,
+     * or to assign ownership of an entity.
+     *
+     * You can also use this data to be retrieved in your custom properties,
+     * for example, to show a list of users in a dropdown.
+     *
+     * If you are using the Rebase user management plugin, this
+     * prop will be implemented automatically.
+     */
+    userManagement?: UserManagementDelegate;
+
+    components?: {
+
+        /**
+         * Component to render when a reference is missing
+         */
+        missingReference?: React.ComponentType<{
+            path: string,
+        }>;
+
+    };
+
+    /**
+     * Controller to simulate different roles when dev mode is active.
+     */
+    effectiveRoleController?: EffectiveRoleController;
+
+};

package/src/types/relations.ts

@@ -0,0 +1,351 @@
+import { EntityCollection } from "./collections";
+
+/**
+ * @group Models
+ */
+export type OnAction = "cascade" | "restrict" | "no action" | "set null" | "set default";
+
+/**
+ * Extended relation that combines base relation with Rebase UI config
+ * @group Models
+ */
+export interface Relation {
+    /**
+     * The application-level name for this relationship.
+     * If not provided, it will be inferred from the target collection path.
+     * @example "posts"
+     */
+    relationName?: string;
+
+    /**
+     * The final collection you want to retrieve records from.
+     */
+    target: () => EntityCollection;
+
+    /**
+     * The nature of the relationship, determining if one or many records are returned.
+     */
+    cardinality: "one" | "many";
+
+    /**
+     * Which side owns the persistence for this relationship.
+     * - "owning": The foreign key (for one-to-one/many-to-one) or the junction table (for many-to-many) is managed by this collection.
+     * - "inverse": The foreign key is on the target collection's table. This side of the relation is typically read-only.
+     * Defaults to "owning".
+     */
+    direction?: "owning" | "inverse";
+
+    /**
+     * The name of the inverse relation.
+     * This is only needed when the inverse relation is not the same as the relation name.
+     * For example, if the relation name is "posts", the inverse relation name might be "author".
+     */
+    inverseRelationName?: string
+
+    /**
+     * Column on THIS table that stores the foreign key to the target.
+     * Required when `direction` is "owning" and `cardinality` is "one".
+     * @example "author_id"
+     */
+    localKey?: string;
+
+    /**
+     * Column on the TARGET table that stores the foreign key to this entity.
+     * Required when `direction` is "inverse".
+     * @example "post_id"
+     */
+    foreignKeyOnTarget?: string;
+
+    /**
+     * Defines the junction table for a many-to-many relationship.
+     * Required when `cardinality` is "many" and `direction` is "owning".
+     *
+     * @example Simple many-to-many between Users and Roles:
+     * ```typescript
+     * // Users collection
+     * {
+     *   relations: [{
+     *     relationName: "roles",
+     *     target: () => rolesCollection,
+     *     cardinality: "many",
+     *     through: {
+     *       table: "user_roles",        // Junction table name
+     *       sourceColumn: "user_id",    // Column that references this collection's ID
+     *       targetColumn: "role_id"     // Column that references target collection's ID
+     *     }
+     *   }]
+     * }
+     *
+     * // This creates a junction table like:
+     * // CREATE TABLE user_roles (
+     * //   user_id INTEGER REFERENCES users(id),
+     * //   role_id INTEGER REFERENCES roles(id),
+     * //   PRIMARY KEY (user_id, role_id)
+     * // );
+     * ```
+     *
+     * @example Many-to-many with additional junction table data:
+     * ```typescript
+     * // Students and Courses with enrollment date
+     * {
+     *   relations: [{
+     *     relationName: "courses",
+     *     target: () => coursesCollection,
+     *     cardinality: "many",
+     *     through: {
+     *       table: "enrollments",
+     *       sourceColumn: "student_id",
+     *       targetColumn: "course_id"
+     *     }
+     *   }]
+     * }
+     *
+     * // Junction table can have additional columns:
+     * // CREATE TABLE enrollments (
+     * //   student_id INTEGER REFERENCES students(id),
+     * //   course_id INTEGER REFERENCES courses(id),
+     * //   enrolled_at TIMESTAMP DEFAULT NOW(),
+     * //   grade VARCHAR(2),
+     * //   PRIMARY KEY (student_id, course_id)
+     * // );
+     * ```
+     */
+    through?: {
+        table: string;
+        sourceColumn: string; // FK to "this" collection's PK
+        targetColumn: string; // FK to the target collection's PK
+    };
+
+    /**
+     * An explicit, ordered array of JOINs to perform to get from the source
+     * to the target. Used for multi-hop relations, composite keys, or when you need
+     * fine-grained control over the join logic.
+     *
+     * When `joinPath` is provided, it overrides all other relation configuration
+     * (localKey, foreignKeyOnTarget, through) and gives you complete control
+     * over how tables are joined together.
+     *
+     * @example Simple one-to-one join (equivalent to localKey):
+     * ```typescript
+     * // Posts -> Authors relationship
+     * {
+     *   relationName: "author",
+     *   target: () => authorsCollection,
+     *   cardinality: "one",
+     *   joinPath: [
+     *     {
+     *       table: "authors",
+     *       on: {
+     *         from: "author_id",  // Column on posts table
+     *         to: "id"           // Column on authors table
+     *       }
+     *     }
+     *   ]
+     * }
+     *
+     * // Generates: SELECT * FROM posts JOIN authors ON posts.author_id = authors.id
+     * ```
+     *
+     * @example Multi-hop relationship (3 tables):
+     * ```typescript
+     * // Users -> Permissions through Roles
+     * {
+     *   relationName: "permissions",
+     *   target: () => permissionsCollection,
+     *   cardinality: "many",
+     *   joinPath: [
+     *     {
+     *       table: "user_roles",
+     *       on: {
+     *         from: "id",        // users.id
+     *         to: "user_id"      // user_roles.user_id
+     *       }
+     *     },
+     *     {
+     *       table: "roles",
+     *       on: {
+     *         from: "role_id",   // user_roles.role_id
+     *         to: "id"          // roles.id
+     *       }
+     *     },
+     *     {
+     *       table: "role_permissions",
+     *       on: {
+     *         from: "id",        // roles.id
+     *         to: "role_id"      // role_permissions.role_id
+     *       }
+     *     },
+     *     {
+     *       table: "permissions",
+     *       on: {
+     *         from: "permission_id", // role_permissions.permission_id
+     *         to: "id"              // permissions.id
+     *       }
+     *     }
+     *   ]
+     * }
+     *
+     * // Generates:
+     * // SELECT * FROM users
+     * // JOIN user_roles ON users.id = user_roles.user_id
+     * // JOIN roles ON user_roles.role_id = roles.id
+     * // JOIN role_permissions ON roles.id = role_permissions.role_id
+     * // JOIN permissions ON role_permissions.permission_id = permissions.id
+     * ```
+     *
+     * @example Composite key relationship:
+     * ```typescript
+     * // Orders -> Customer by company_code + region
+     * {
+     *   relationName: "customer",
+     *   target: () => customersCollection,
+     *   cardinality: "one",
+     *   joinPath: [
+     *     {
+     *       table: "customers",
+     *       on: {
+     *         from: ["company_code", "region_id"], // Multiple columns from orders
+     *         to: ["code", "region_id"]            // Multiple columns on customers
+     *       }
+     *     }
+     *   ]
+     * }
+     *
+     * // Generates:
+     * // SELECT * FROM orders
+     * // JOIN customers ON orders.company_code = customers.code
+     * //               AND orders.region_id = customers.region_id
+     * ```
+     *
+     * @example Self-referencing with intermediate table:
+     * ```typescript
+     * // Users -> Friends (many-to-many self-reference)
+     * {
+     *   relationName: "friends",
+     *   target: () => usersCollection, // Same collection
+     *   cardinality: "many",
+     *   joinPath: [
+     *     {
+     *       table: "friendships",
+     *       on: {
+     *         from: "id",         // users.id
+     *         to: "user_id"       // friendships.user_id
+     *       }
+     *     },
+     *     {
+     *       table: "users",
+     *       on: {
+     *         from: "friend_id",  // friendships.friend_id
+     *         to: "id"           // users.id (target)
+     *       }
+     *     }
+     *   ]
+     * }
+     * ```
+     *
+     * @example Complex business logic join:
+     * ```typescript
+     * // Products -> Active Suppliers (only current, non-expired contracts)
+     * {
+     *   relationName: "activeSuppliers",
+     *   target: () => suppliersCollection,
+     *   cardinality: "many",
+     *   joinPath: [
+     *     {
+     *       table: "product_supplier_contracts",
+     *       on: {
+     *         from: "id",           // products.id
+     *         to: "product_id"      // contracts.product_id
+     *       }
+     *     },
+     *     {
+     *       table: "suppliers",
+     *       on: {
+     *         from: "supplier_id",  // contracts.supplier_id
+     *         to: "id"             // suppliers.id
+     *       }
+     *     }
+     *   ]
+     *   // Note: Additional WHERE conditions for active/non-expired
+     *   // would be handled in the query logic, not in joinPath
+     * }
+     * ```
+     */
+    joinPath?: JoinStep[];
+
+    /**
+     * Action to perform on update.
+     */
+    onUpdate?: OnAction;
+    /**
+     * Action to perform on delete.
+     */
+    onDelete?: OnAction;
+
+    overrides?: Partial<EntityCollection>;
+
+    validation?: {
+        required?: boolean;
+    }
+}
+
+/**
+ * Defines a single, explicit step in a multi-join path.
+ *
+ * Each step represents one JOIN operation in the sequence. The `from` columns
+ * refer to the previous table in the chain (or the source table for the first step),
+ * and the `to` columns refer to the current table being joined.
+ *
+ * @example Single column join:
+ * ```typescript
+ * {
+ *   table: "authors",
+ *   on: {
+ *     from: "author_id",  // Column from previous table (e.g., posts.author_id)
+ *     to: "id"           // Column from current table (authors.id)
+ *   }
+ * }
+ * ```
+ *
+ * @example Multi-column composite key join:
+ * ```typescript
+ * {
+ *   table: "order_items",
+ *   on: {
+ *     from: ["order_id", "store_id"],    // Multiple columns from previous table
+ *     to: ["order_id", "store_id"]       // Corresponding columns in current table
+ *   }
+ * }
+ * ```
+ */
+export interface JoinStep {
+    /**
+     * The database table name to join TO in this step.
+     * This is the table you're joining into, not the table you're joining from.
+     *
+     * @example "authors", "user_roles", "product_categories"
+     */
+    table: string;
+
+    /**
+     * The join condition for this step. Defines how the previous table
+     * connects to the current table.
+     *
+     * - `from`: Column name(s) on the PREVIOUS table in the join chain
+     * - `to`: Column name(s) on the CURRENT table (specified in `table`)
+     *
+     * For the first step, `from` refers to the source collection's table.
+     * For subsequent steps, `from` refers to the table from the previous step.
+     *
+     * Both `from` and `to` support:
+     * - Single column: `"user_id"`
+     * - Multiple columns: `["company_id", "region_id"]` for composite keys
+     *
+     * When using arrays, both `from` and `to` must have the same length,
+     * and columns are matched by position (index 0 with index 0, etc.).
+     */
+    on: {
+        from: string | string[];
+        to: string | string[];
+    };
+}