@rebasepro/types 0.0.1-canary.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Rebase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+<p align="center">
+    <img src="https://rebase.pro/img/dark_mode.webp" alt="Intro video" style="max-width: 100%;"/>
+</p>
+
+<p align="center">
+  <a href="https://rebase.pro">
+    <img src="https://rebase.pro/img/logo_small.png" width="240px" alt="Rebase logo" />
+  </a>
+</p>
+
+<h1 align="center">Rebase</h1>
+<h3 align="center">Awesome Firebase/MongoDB-based headless CMS</h3>
+<p align="center"><a href="https://demo.rebase.pro">Live demo</a></p>
+
+<br />
+
+
+[![NPM](https://img.shields.io/npm/v/rebase.svg)](https://www.npmjs.com/package/rebase) [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
+
+Designed by developers for developers, Rebase is a headless CMS and admin panel
+that seamlessly integrates with **Firebase and Firestore** by default, but is
+also
+compatible with any backend.
+
+Effortlessly generate **CRUD views** based on your configuration. Rebase is
+simple
+to set up for standard cases and easy to extend and customize for more specific
+needs.
+
+Built to produce collection and form views that naturally align with the
+collection/document model, Rebase covers a wide range of basic and advanced use
+cases. With extensibility in mind, it's easy to create your own views or modify
+existing ones.
+
+Rebase does **not impose any data structure** restrictions, ensuring a smooth,
+out-of-the-box experience for any project.
+
+### Core technologies
+
+Rebase is based on this great technologies:
+
+- Typescript
+- Tailwind CSS
+- Firebase SDK 10
+- React + React Router 6
+
+### Quickstart
+
+The easiest way to get going is to check our quickstart guide! You will just
+need to follow some quick steps:
+
+https://rebase.pro/docs
+
+### Demo
+
+Check the demo with all the core functionalities.
+
+https://demo.rebase.pro
+
+> You can modify the data, but it gets periodically restored.
+
+### Changelog
+
+https://rebase.pro/docs/changelog
+
+## Features
+
+Rebase has been meticulously crafted to make it incredibly easy for developers
+to build a CMS/admin tool while offering an excellent data editing experience
+and a user-friendly interface for marketers and content managers.
+
+### 🏓 Exceptional Spreadsheet View
+
+We've developed a highly efficient windowed **spreadsheet view** for
+collections, allowing inline editing for most common fields, as well as popup
+views for other cases and your custom field implementations.
+
+Featuring **real-time** support, Rebase is perfect for apps that require
+constant updates. It also supports **text search** (through an external provider
+like Algolia, if using Firestore), **filtering and sorting**, and **exporting**
+data.
+
+### ✨ Robust Forms
+
+![fields](https://rebase.pro/img/form_editing.webp)
+
+When editing an entity, Rebase offers a nested system of side dialogs for
+navigating through **subcollections** and accessing custom views (such as custom
+forms or blog previews). This functionality can also be accessed
+programmatically using the `useSideEntityController` hook.
+
+Rebase includes **over 20 built-in fields** with numerous customization and
+validation options. The components have been carefully designed for an
+outstanding user experience, including advanced features like **references** to
+other collections, **markdown**, and **array reordering**.
+
+For unsupported use cases, create your own **custom field** as a React
+component.
+
+Rebase also supports **conditional fields** in forms, allowing you to define
+rules for active fields based on your logic.
+
+### 👮 Authentication, Permissions, and Role System
+
+Define which navigation views users can see and the operations (create, edit,
+delete) they can perform based on your role system. You can even configure this
+on a per-entity or collection level.
+
+By default, Rebase supports all Firebase authorization mechanisms, but you can
+implement your own.
+
+### 🏹 Relational Support
+
+Define references to entities in other collections and benefit from the
+integrated reference fields and shortcuts.
+
+You can also define subcollections at the entity level for nesting data in a
+collection/document/collection model.
+
+### 🆒 Real-Time Data
+
+Every view in the CMS supports real-time data, making it suitable for displaying
+constantly updated information.
+
+Forms also support this feature, with any modified value in the database being
+updated in any open form view as long as it hasn't been touched by the user.
+This enables advanced cases where a Cloud Function is triggered after saving an
+entity, modifying some values, and requiring real-time updates.
+
+### 🗂️ File Storage
+
+Rebase supports uploading files to Firebase Storage out of the box and provides
+specific fields for handling single and multiple file uploads, as well as
+reordering.
+
+You can replace the Firebase Storage implementation with your own.
+
+## Included example
+
+You can access the code for the demo project under
+[`example`](https://github.com/Rebaseco/rebase/tree/master/example). It includes
+every feature provided by this CMS.
+
+Keep in mind you need to update the dependencies in that project if you want to
+use it as it is, without linking it to the library source code. More details in
+its README
+
+## Contact and support
+
+If you need general support, you can open a GitHub issue.
+
+Do you need consulting setting up your Firestore-based CMS in no time? We are
+happy to help!
+`hello@rebase.pro`
+
+## Development
+
+If you would like to make changes to the source, feel free to submit a PR!
+
+When developing, the core library can be found under `lib`.
+There is an example project in the folder `example`.
+
+In order to run the project, you need to create a file
+called `firebase_config.ts`
+in `example/src`.
+
+That file needs to export a valid Firebase config, that you can get
+from your Firebase console when creating a webapp for your project.
+
+Then simply run `yarn` and `yarn dev`
+
+## License
+
+MIT © [Rebase](https://github.com/Rebaseco)

package/dist/components/EntityFormActionsProps.d.ts

@@ -0,0 +1,17 @@
+import { Entity, EntityCollection, FormContext } from "../types";
+import { FormexController } from "./formex";
+export interface EntityFormActionsProps {
+    path: string;
+    collection: EntityCollection;
+    entity?: Entity;
+    layout: "bottom" | "side";
+    savingError?: Error;
+    formex: FormexController<any>;
+    disabled: boolean;
+    status: "new" | "existing" | "copy";
+    pluginActions: React.ReactNode[];
+    openEntityMode: "side_panel" | "full_screen";
+    showDefaultActions?: boolean;
+    navigateBack: () => void;
+    formContext: FormContext;
+}

package/dist/components/EntityFormProps.d.ts

@@ -0,0 +1,46 @@
+import { Entity, EntityCollection, EntityCustomViewParams, EntityStatus, FormContext } from "../types";
+import { FormexController } from "./formex";
+import { EntityFormActionsProps } from "./EntityFormActionsProps";
+export type EntityFormProps<M extends Record<string, any>> = {
+    path: string;
+    fullIdPath?: string;
+    collection: EntityCollection<M>;
+    entityId?: string | number;
+    entity?: Entity<M>;
+    databaseId?: string;
+    onIdChange?: (id: string | number) => void;
+    onValuesModified?: (modified: boolean, values: M) => void;
+    onSaved?: (params: OnUpdateParams) => void;
+    initialDirtyValues?: Partial<M>;
+    onFormContextReady?: (formContext: FormContext) => void;
+    forceActionsAtTheBottom?: boolean;
+    className?: string;
+    initialStatus: EntityStatus;
+    onStatusChange?: (status: EntityStatus) => void;
+    onEntityChange?: (entity: Entity<M>) => void;
+    formex?: FormexController<M>;
+    openEntityMode?: "side_panel" | "full_screen";
+    /**
+     * If true, the form will be disabled and no actions will be available
+     */
+    disabled?: boolean;
+    /**
+     * Include the copy and delete actions in the form
+     */
+    showDefaultActions?: boolean;
+    /**
+     * Display the entity path in the form
+     */
+    showEntityPath?: boolean;
+    EntityFormActionsComponent?: React.FC<EntityFormActionsProps>;
+    Builder?: React.ComponentType<EntityCustomViewParams<M>>;
+    children?: React.ReactNode;
+};
+export type OnUpdateParams = {
+    entity: Entity<any>;
+    status: EntityStatus;
+    path: string;
+    entityId?: string | number;
+    selectedTab?: string;
+    collection: EntityCollection<any>;
+};

package/dist/components/PropertyPreviewProps.d.ts

@@ -0,0 +1,50 @@
+import { InferPropertyType, Property } from "../types";
+/**
+ * @group Preview components
+ */
+export type PreviewSize = "small" | "medium" | "large";
+/**
+ * @group Preview components
+ */
+export interface PropertyPreviewProps<P extends Property, CustomProps = unknown> {
+    /**
+     * Name of the property
+     */
+    propertyKey?: string;
+    /**
+     * Current value of the property, inferred from the property schema P
+     */
+    value: InferPropertyType<P>;
+    /**
+     * Property this display is related to, now strongly typed to P
+     */
+    property: P;
+    /**
+     * Desired size of the preview, depending on the context.
+     */
+    size: PreviewSize;
+    /**
+     * Max height assigned to the preview, depending on the context.
+     * It may be undefined if unlimited.
+     */
+    height?: number;
+    /**
+     * Max height width to the preview, depending on the context.
+     * It may be undefined if unlimited.
+     */
+    width?: number;
+    /**
+     * Additional properties set by the developer
+     */
+    customProps?: CustomProps;
+    /**
+     * If the preview should be interactive or not.
+     * This applies only to videos.
+     */
+    interactive?: boolean;
+    /**
+     * If true, image previews will fill their container completely.
+     * Only applies to image type properties.
+     */
+    fill?: boolean;
+}

package/dist/components/formex.d.ts

@@ -0,0 +1,40 @@
+import React, { FormEvent } from "react";
+export type FormexController<T extends object> = {
+    values: T;
+    initialValues: T;
+    setValues: (values: T) => void;
+    setFieldValue: (key: string, value: unknown, shouldValidate?: boolean) => void;
+    touched: Record<string, boolean>;
+    setFieldTouched: (key: string, touched: boolean, shouldValidate?: boolean) => void;
+    setTouched: (touched: Record<string, boolean>) => void;
+    dirty: boolean;
+    setDirty: (dirty: boolean) => void;
+    setSubmitCount: (submitCount: number) => void;
+    errors: Record<string, string>;
+    setFieldError: (key: string, error?: string) => void;
+    handleChange: (event: React.SyntheticEvent) => void;
+    handleBlur: (event: React.FocusEvent) => void;
+    handleSubmit: (event?: FormEvent<HTMLFormElement>) => void;
+    validate: () => void;
+    resetForm: (props?: FormexResetProps<T>) => void;
+    submitCount: number;
+    isSubmitting: boolean;
+    setSubmitting: (isSubmitting: boolean) => void;
+    isValidating: boolean;
+    /**
+     * The version of the form. This is incremented every time the form is reset
+     * or the form is submitted.
+     */
+    version: number;
+    debugId?: string;
+    undo: () => void;
+    redo: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+};
+export type FormexResetProps<T extends object> = {
+    values?: T;
+    submitCount?: number;
+    errors?: Record<string, string>;
+    touched?: Record<string, boolean>;
+};

package/dist/components/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./PropertyPreviewProps";
+export * from "./EntityFormProps";
+export * from "./EntityFormActionsProps";

package/dist/controllers/analytics_controller.d.ts

@@ -0,0 +1,7 @@
+export type AnalyticsController = {
+    /**
+     * Callback used to get analytics events from the CMS
+     */
+    onAnalyticsEvent?: (event: CMSAnalyticsEvent, data?: object) => void;
+};
+export type CMSAnalyticsEvent = "entity_click" | "entity_click_from_reference" | "reference_selection_clear" | "reference_selection_toggle" | "reference_selected_single" | "reference_selection_new_entity" | "edit_entity_clicked" | "entity_edited" | "new_entity_click" | "new_entity_saved" | "copy_entity_click" | "entity_copied" | "single_delete_dialog_open" | "multiple_delete_dialog_open" | "single_entity_deleted" | "multiple_entities_deleted" | "drawer_navigate_to_home" | "drawer_navigate_to_collection" | "drawer_navigate_to_view" | "home_navigate_to_collection" | "home_favorite_navigate_to_collection" | "home_navigate_to_view" | "home_navigate_to_admin_view" | "home_favorite_navigate_to_view" | "home_move_card" | "home_move_group" | "home_drop_new_group" | "collection_inline_editing" | "view_mode_changed" | "kanban_card_moved" | "kanban_column_reorder" | "kanban_property_changed" | "kanban_new_entity_in_column" | "kanban_backfill_order" | "card_view_entity_click" | "unmapped_event";

package/dist/controllers/auth.d.ts

@@ -0,0 +1,73 @@
+import { DataSource } from "./datasource";
+import { StorageSource } from "./storage";
+import { Role, User } from "../users";
+/**
+ * Controller for retrieving the logged user or performing auth related operations.
+ * Note that if you are implementing your AuthController, you probably will want
+ * to do it as the result of a hook.
+ * @group Hooks and utilities
+ */
+export type AuthController<USER extends User = any, ExtraData = unknown> = {
+    /**
+     * The user currently logged in
+     * The values can be: the user object, null if they skipped login
+     */
+    user: USER | null;
+    /**
+     * Initial loading flag. It is used not to display the login screen
+     * when the app first loads, and it has not been checked whether the user
+     * is logged in or not.
+     */
+    initialLoading?: boolean;
+    /**
+     * Loading flag. It is used to display a loading screen when the user is
+     * logging in or out.
+     */
+    authLoading: boolean;
+    /**
+     * Sign out
+     */
+    signOut: () => Promise<void>;
+    /**
+     * Error initializing the authentication
+     */
+    authError?: unknown;
+    /**
+     * Error dispatched by the auth provider
+     */
+    authProviderError?: unknown;
+    /**
+     * You can use this method to retrieve the auth token for the current user.
+     */
+    getAuthToken: () => Promise<string>;
+    /**
+     * Has the user skipped the login process
+     */
+    loginSkipped: boolean;
+    extra: ExtraData;
+    setExtra: (extra: ExtraData) => void;
+    setUser?: (user: USER | null) => void;
+    setUserRoles?: (roles: Role[]) => void;
+};
+/**
+ * Implement this function to allow access to specific users.
+ * @group Hooks and utilities
+ */
+export type Authenticator<USER extends User = User> = (props: {
+    /**
+     * Logged-in user or null
+     */
+    user: USER | null;
+    /**
+     * AuthController
+     */
+    authController: AuthController<USER>;
+    /**
+     * Connector to your database, e.g. your Firestore database
+     */
+    dataSource: DataSource;
+    /**
+     * Used storage implementation
+     */
+    storageSource: StorageSource;
+}) => boolean | Promise<boolean>;

package/dist/controllers/customization_controller.d.ts

@@ -0,0 +1,50 @@
+import React from "react";
+import { EntityAction, EntityCustomView, EntityLinkBuilder, RebasePlugin, Locale, PropertyConfig } from "../types";
+export type CustomizationController = {
+    /**
+     * Builder for generating utility links for entities
+     */
+    entityLinkBuilder?: EntityLinkBuilder;
+    /**
+     * Use plugins to modify the behaviour of the CMS.
+     */
+    plugins?: RebasePlugin[];
+    /**
+     * 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;
+    /**
+     * 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>;
+    components?: {
+        /**
+         * Component to render when a reference is missing
+         */
+        missingReference?: React.ComponentType<{
+            path: string;
+        }>;
+    };
+};

package/dist/controllers/datasource.d.ts

@@ -0,0 +1,179 @@
+import { Entity, EntityCollection, EntityStatus, EntityValues, FilterValues, TableColumnInfo } from "../types";
+import { RebaseContext } from "../rebase_context";
+/**
+ * @group Datasource
+ */
+export interface FetchEntityProps<M extends Record<string, any> = any> {
+    path: string;
+    entityId: string | number;
+    databaseId?: string;
+    collection?: EntityCollection<M, any>;
+}
+/**
+ * @group Datasource
+ */
+export type ListenEntityProps<M extends Record<string, any> = any> = FetchEntityProps<M> & {
+    onUpdate: (entity: Entity<M> | null) => void;
+    onError?: (error: Error) => void;
+};
+/**
+ * @group Datasource
+ */
+export interface FetchCollectionProps<M extends Record<string, any> = any> {
+    path: string;
+    collection?: EntityCollection<M>;
+    filter?: FilterValues<Extract<keyof M, string>>;
+    limit?: number;
+    startAfter?: unknown;
+    orderBy?: string;
+    searchString?: string;
+    order?: "desc" | "asc";
+}
+/**
+ * @group Datasource
+ */
+export type ListenCollectionProps<M extends Record<string, any> = any> = FetchCollectionProps<M> & {
+    onUpdate: (entities: Entity<M>[]) => void;
+    onError?: (error: Error) => void;
+};
+/**
+ * @group Datasource
+ */
+export interface SaveEntityProps<M extends Record<string, any> = any> {
+    path: string;
+    values: Partial<EntityValues<M>>;
+    entityId?: string | number;
+    previousValues?: Partial<EntityValues<M>>;
+    collection?: EntityCollection<M>;
+    status: EntityStatus;
+}
+/**
+ * @group Datasource
+ */
+export interface DeleteEntityProps<M extends Record<string, any> = any> {
+    entity: Entity<M>;
+    collection?: EntityCollection<M>;
+}
+export type FilterCombinationValidProps = {
+    path: string;
+    databaseId?: string;
+    collection: EntityCollection<any>;
+    filterValues: FilterValues<any>;
+    sortBy?: [string, "asc" | "desc"];
+};
+/**
+ * Component in charge of communicating with the data source.
+ * @group Datasource
+ */
+export interface DataSource {
+    /**
+     * Key that identifies this data source
+     */
+    key?: string;
+    /**
+     * If the data source has been initialised
+     */
+    initialised?: boolean;
+    /**
+     * Fetch data from a collection
+     * @param props
+     * @return Promise of entities
+     * @see useCollectionFetch if you need this functionality implemented as a hook
+     */
+    fetchCollection<M extends Record<string, any> = any>(props: FetchCollectionProps<M>): Promise<Entity<M>[]>;
+    /**
+     * Listen to a collection in a given path. If you don't implement this method
+     * `fetchCollection` will be used instead, with no real time updates.
+     * @param props
+     * @return Function to cancel subscription
+     * @see useCollectionFetch if you need this functionality implemented as a hook
+     */
+    listenCollection?<M extends Record<string, any> = any>(props: ListenCollectionProps<M>): () => void;
+    /**
+     * Retrieve an entity given a path and a collection
+     * @param props
+     */
+    fetchEntity<M extends Record<string, any> = any>(props: FetchEntityProps<M>): Promise<Entity<M> | undefined>;
+    /**
+     * Get realtime updates on one entity.
+     * @param props
+     * @return Function to cancel subscription
+     */
+    listenEntity?<M extends Record<string, any> = any>(props: ListenEntityProps<M>): () => void;
+    /**
+     * Save entity to the specified path
+     * @param props
+     */
+    saveEntity<M extends Record<string, any> = any>(props: SaveEntityProps<M>): Promise<Entity<M>>;
+    /**
+     * Delete an entity
+     * @param props
+     * @return was the whole deletion flow successful
+     */
+    deleteEntity<M extends Record<string, any> = any>(props: DeleteEntityProps<M>): Promise<void>;
+    /**
+     * Check if the given property is unique in the given collection
+     * @param path Collection path
+     * @param name of the property
+     * @param value
+     * @param entityId
+     * @param collection
+     * @return `true` if there are no other fields besides the given entity
+     */
+    checkUniqueField(path: string, name: string, value: unknown, entityId?: string | number, collection?: EntityCollection): Promise<boolean>;
+    /**
+     * Count the number of entities in a collection
+     */
+    countEntities?<M extends Record<string, any> = any>(props: FetchCollectionProps<M>): Promise<number>;
+    /**
+     * Check if the given filter combination is valid
+     * @param props
+     */
+    isFilterCombinationValid?(props: Omit<FilterCombinationValidProps, "collection"> & {
+        databaseId?: string;
+    }): boolean;
+    /**
+     * Get the object to generate the current time in the datasource
+     */
+    currentTime?: () => unknown;
+    delegateToCMSModel?: (data: unknown) => unknown;
+    cmsToDelegateModel?: (data: unknown) => unknown;
+    initTextSearch?: (props: {
+        context: RebaseContext;
+        path: string;
+        databaseId?: string;
+        collection: EntityCollection;
+        parentCollectionIds?: string[];
+    }) => Promise<boolean>;
+    /**
+     * Execute raw SQL (if supported by the datasource)
+     */
+    executeSql?(sql: string, options?: {
+        database?: string;
+        role?: string;
+    }): Promise<Record<string, unknown>[]>;
+    /**
+     * Fetch the available databases (if supported by the datasource)
+     */
+    fetchAvailableDatabases?(): Promise<string[]>;
+    /**
+     * Fetch the available roles (if supported by the datasource)
+     */
+    fetchAvailableRoles?(): Promise<string[]>;
+    /**
+     * Fetch the current database name (if supported by the datasource)
+     */
+    fetchCurrentDatabase?(): Promise<string | undefined>;
+    /**
+     * Fetch database tables not yet mapped to a collection (if supported)
+     */
+    fetchUnmappedTables?(mappedPaths?: string[]): Promise<string[]>;
+    /**
+     * Fetch column metadata for a given table (if supported)
+     */
+    fetchTableColumns?(tableName: string): Promise<TableColumnInfo[]>;
+    /**
+     * Flag to indicate if the datasource delegate has requested the initialization of the text search index
+     */
+    needsInitTextSearch?: boolean;
+}