@rebasepro/types 0.0.1-canary.0

package/dist/controllers/dialogs_controller.d.ts

@@ -0,0 +1,36 @@
+import React from "react";
+/**
+ * Controller to open the side dialog
+ * @group Hooks and utilities
+ */
+export interface DialogsController {
+    /**
+     * Close the last dialog
+     */
+    close: () => void;
+    /**
+     * Open a dialog
+     * @param props
+     */
+    open: <T extends object = object>(props: DialogControllerEntryProps<T>) => {
+        closeDialog: () => void;
+    };
+}
+/**
+ * Props used to open a side dialog
+ * @group Hooks and utilities
+ */
+export interface DialogControllerEntryProps<T extends object = object> {
+    key: string;
+    /**
+     * The component type that will be rendered
+     */
+    Component: React.ComponentType<{
+        open: boolean;
+        closeDialog: () => void;
+    } & T>;
+    /**
+     * Props to pass to the dialog component
+     */
+    props?: T;
+}

package/dist/controllers/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./analytics_controller";
+export * from "./auth";
+export * from "./customization_controller";
+export * from "./datasource";
+export * from "./dialogs_controller";
+export * from "./local_config_persistence";
+export * from "./navigation";
+export * from "./side_dialogs_controller";
+export * from "./side_entity_controller";
+export * from "./snackbar";
+export * from "./storage";

package/dist/controllers/local_config_persistence.d.ts

@@ -0,0 +1,20 @@
+import { EntityCollection } from "../types";
+/**
+ * @group Models
+ */
+export type PartialEntityCollection<M extends Record<string, any> = any> = Partial<EntityCollection<M>>;
+/**
+ * This interface is in charge of defining the controller that persists
+ * modifications to a collection or collection, and retrieves them back from
+ * a data source, such as local storage or Firestore.
+ */
+export interface UserConfigurationPersistence {
+    onCollectionModified: <M extends Record<string, any> = any>(path: string, partialCollection: PartialEntityCollection<M>) => void;
+    getCollectionConfig: <M extends Record<string, any> = any>(path: string) => PartialEntityCollection<M>;
+    recentlyVisitedPaths: string[];
+    setRecentlyVisitedPaths: (paths: string[]) => void;
+    favouritePaths: string[];
+    setFavouritePaths: (paths: string[]) => void;
+    collapsedGroups: string[];
+    setCollapsedGroups: (paths: string[]) => void;
+}

package/dist/controllers/navigation.d.ts

@@ -0,0 +1,262 @@
+import React from "react";
+import { EntityCollection, EntityReference, RebasePlugin } from "../types";
+/**
+ * Controller that handles URL path building and resolution.
+ * @group Models
+ */
+export type CMSUrlController = {
+    /**
+     * Default path under the navigation routes of the CMS will be created.
+     * Defaults to '/'. You may want to change this `basepath` to 'admin' for example.
+     */
+    basePath: string;
+    /**
+     * Default path under the collection routes of the CMS will be created.
+     * It defaults to '/c'
+     */
+    baseCollectionPath: string;
+    /**
+     * Convert a URL path to a collection or entity path
+     * `/c/products` => `products`
+     * `/my_cms/c/products/B34SAP8Z` => `products/B34SAP8Z`
+     * `/my_cms/my_view` => `my_view`
+     * @param cmsPath
+     */
+    urlPathToDataPath: (cmsPath: string) => string;
+    /**
+     * Base url path for the home screen
+     */
+    homeUrl: string;
+    /**
+     * Check if a url path belongs to a collection
+     * @param path
+     */
+    isUrlCollectionPath: (urlPath: string) => boolean;
+    /**
+     * Build a URL collection path from a data path
+     * `products` => `/c/products`
+     * `products/B34SAP8Z` => `/c/products/B34SAP8Z`
+     * @param path
+     */
+    buildUrlCollectionPath: (path: string) => string;
+    /**
+     * Build a URL path for the CMS (e.g. for custom views)
+     * @param path
+     */
+    buildCMSUrlPath: (path: string) => string;
+    /**
+     * Turn a path with collection ids into a resolved path.
+     * The ids (typically used in urls) will be replaced with relative paths (typically used in database paths)
+     * @param path
+     */
+    resolveDatabasePathsFrom: (path: string) => string;
+    /**
+     * A function to navigate to a specified route or URL.
+     *
+     * @param {string} to - The target route or URL to navigate to.
+     * @param {NavigateOptions} [options] - Optional configuration settings for navigation, such as replace behavior or state data.
+     */
+    navigate: (to: string, options?: NavigateOptions) => void;
+};
+/**
+ * Controller that manages the state of the navigation menu,
+ * including resolved views and top-level grouping.
+ * @group Models
+ */
+export type NavigationStateController = {
+    /**
+     * Custom additional views created by the developer, added to the main
+     * navigation
+     */
+    views?: CMSView[];
+    /**
+     * Custom additional views created by the developer, added to the admin
+     * navigation
+     */
+    adminViews?: CMSView[];
+    /**
+     * Configuration for the views that should be displayed at the top
+     * level of the navigation (e.g. in the home page or the navigation
+     * drawer)
+     */
+    topLevelNavigation?: NavigationResult;
+    /**
+     * Is the navigation loading (the configuration persistence has not
+     * loaded yet, or a specified navigation builder has not completed)
+     */
+    loading: boolean;
+    /**
+     * Was there an error while loading the navigation data
+     */
+    navigationLoadingError?: unknown;
+    /**
+     * Call this method to recalculate the navigation
+     */
+    refreshNavigation: () => void;
+    /**
+     * Plugin system allowing to extend the CMS functionality.
+     */
+    plugins?: RebasePlugin<any, any, any>[];
+};
+/**
+ * Controller that provides access to the registered entity collections.
+ * @group Models
+ */
+export type CollectionRegistryController<EC extends EntityCollection = EntityCollection<any>> = {
+    /**
+     * List of the mapped collections in the CMS.
+     * Each entry relates to a collection in the root database.
+     * Each of the navigation entries in this field
+     * generates an entry in the main menu.
+     */
+    collections?: EntityCollection[];
+    /**
+     * Is the registry ready to be used
+     */
+    initialised: boolean;
+    /**
+     * Get the collection configuration for a given path.
+     * The collection is resolved from the given path or alias.
+     */
+    getCollection: (slugOrPath: string, includeUserOverride?: boolean) => EC | undefined;
+    /**
+     * Get the raw, un-normalized collection configuration.
+     * This bypasses the `CollectionRegistry` normalization (such as injecting `relation` instances).
+     * This is strictly for the Visual Editor to manipulate AST code without persisting runtime state.
+     */
+    getRawCollection: (slugOrPath: string) => EC | undefined;
+    /**
+     * Retrieve all the related parent references for a given path
+     * @param path
+     */
+    getParentReferencesFromPath: (path: string) => EntityReference[];
+    /**
+     * Retrieve all the related parent collection ids for a given path
+     * @param path
+     */
+    getParentCollectionIds: (path: string) => string[];
+    /**
+     * Resolve paths from a list of ids
+     * @param ids
+     */
+    convertIdsToPaths: (ids: string[]) => string[];
+};
+/**
+ * Legacy monolithic controller that includes the resolved navigation and utility methods and attributes.
+ * It is a combination of CMSUrlController, NavigationStateController, and CollectionRegistryController.
+ * @group Models
+ * @deprecated Use the specific controllers instead.
+ */
+export type NavigationController<EC extends EntityCollection = EntityCollection<any>> = CMSUrlController & NavigationStateController & CollectionRegistryController<EC>;
+export interface NavigateOptions {
+    replace?: boolean;
+    state?: unknown;
+    preventScrollReset?: boolean;
+    relative?: "route" | "path";
+    flushSync?: boolean;
+    viewTransition?: boolean;
+}
+export type NavigationBlocker = {
+    updateBlockListener: (path: string, block: boolean, basePath?: string) => () => void;
+    isBlocked: (path: string) => boolean;
+    proceed?: () => void;
+    reset?: () => void;
+};
+/**
+ * Custom additional views created by the developer, added to the main
+ * navigation.
+ * @group Models
+ */
+export interface CMSView {
+    /**
+     * CMS Path you can reach this view from.
+     */
+    slug: string;
+    /**
+     * Name of this view
+     */
+    name: string;
+    /**
+     * Optional description of this view. You can use Markdown
+     */
+    description?: string;
+    /**
+     * Icon key to use in this view.
+     * You can use any of the icons in the Material specs:
+     * https://fonts.google.com/icons
+     * e.g. 'account_tree' or 'person'
+     * Find all the icons in https://rebase.pro/docs/icons
+     */
+    icon?: string | React.ReactNode;
+    /**
+     * Should this view be hidden from the main navigation panel.
+     * It will still be accessible if you reach the specified path
+     */
+    hideFromNavigation?: boolean;
+    /**
+     * Component to be rendered. This can be any React component, and can use
+     * any of the provided hooks
+     */
+    view: React.ReactNode;
+    /**
+     * Optional field used to group top level navigation entries under a
+     * navigation view.
+     * This prop is ignored for admin views.
+     */
+    group?: string;
+    /**
+     * If true, a wildcard route (slug/*) is automatically registered
+     * alongside the base route, enabling nested navigation within this view.
+     */
+    nestedRoutes?: boolean;
+}
+/**
+ * A composable section that can be rendered on the home page.
+ * Use this to add custom content alongside the auto-generated
+ * navigation groups.
+ * @group Models
+ */
+export interface HomePageSection {
+    /**
+     * Unique key for this section.
+     */
+    key: string;
+    /**
+     * Title displayed as the section header.
+     */
+    title: string;
+    /**
+     * Arbitrary React content rendered inside the section.
+     */
+    children: React.ReactNode;
+}
+/**
+ * Used to group navigation entries in the main navigation.
+ */
+export interface NavigationGroupMapping {
+    /**
+     * Name of the group, used to display the group header in the UI
+     */
+    name: string;
+    /**
+     * List of collection ids or view paths that belong to this group.
+     */
+    entries: string[];
+}
+export interface NavigationEntry {
+    id: string;
+    url: string;
+    name: string;
+    slug: string;
+    type: "collection" | "view" | "admin";
+    collection?: EntityCollection;
+    view?: CMSView;
+    description?: string;
+    group: string;
+}
+export type NavigationResult = {
+    allowDragAndDrop: boolean;
+    navigationEntries: NavigationEntry[];
+    groups: string[];
+    onNavigationEntriesUpdate: (entries: NavigationGroupMapping[]) => void;
+};

package/dist/controllers/side_dialogs_controller.d.ts

@@ -0,0 +1,67 @@
+import React from "react";
+/**
+ * Controller to open the side dialog
+ * @group Hooks and utilities
+ */
+export interface SideDialogsController {
+    /**
+     * Close the last panel
+     */
+    close: () => void;
+    /**
+     * List of side panels currently open
+     */
+    sidePanels: SideDialogPanelProps[];
+    /**
+     * Override the current side panels
+     * @param panels
+     */
+    setSidePanels: (panels: SideDialogPanelProps[]) => void;
+    /**
+     * Open one or multiple side panels
+     * @param props
+     */
+    open: (panelProps: SideDialogPanelProps | SideDialogPanelProps[]) => void;
+    /**
+     * Replace the last open panel with the given one
+     * @param props
+     */
+    replace: (panelProps: SideDialogPanelProps | SideDialogPanelProps[]) => void;
+}
+/**
+ * Props used to open a side dialog
+ * @group Hooks and utilities
+ */
+export interface SideDialogPanelProps {
+    /**
+     * A key that identifies this panel
+     */
+    key: string;
+    /**
+     * The component type that will be rendered
+     */
+    component: React.ReactNode;
+    /**
+     * Optional width of the panel
+     */
+    width?: string;
+    /**
+     * When open, change the URL to this path.
+     * Note that if you want to restore state from a URL you need to add the
+     * logic yourself by listening to URL updates, and probably call `open`.
+     */
+    urlPath?: string;
+    /**
+     * If the navigation stack is empty (you landed in the `urlPath` url), what
+     * url path to change to when the panel gets closed.
+     */
+    parentUrlPath?: string;
+    /**
+     * Callback when the panel is closed
+     */
+    onClose?: () => void;
+    /**
+     * Use this prop to store additional data in the panel
+     */
+    additional?: unknown;
+}

package/dist/controllers/side_entity_controller.d.ts

@@ -0,0 +1,90 @@
+import { Entity, EntityCollection } from "../types";
+import { EntityFormProps } from "../components";
+/**
+ * Props used to open a side dialog
+ * @group Hooks and utilities
+ */
+export interface EntitySidePanelProps<M extends Record<string, any> = any> {
+    /**
+     * Absolute path of the entity
+     */
+    path: string;
+    /**
+     * ID of the entity, if not set, it means we are creating a new entity
+     */
+    entityId?: string | number;
+    /**
+     * Set this flag to true if you want to make a copy of an existing entity
+     */
+    copy?: boolean;
+    /**
+     * Open the entity with a selected sub-collection view. If the panel for this
+     * entity was already open, it is replaced.
+     */
+    selectedTab?: string;
+    /**
+     * Use this prop to override the width of the form view.
+     * e.g. "600px"
+     */
+    width?: number | string;
+    /**
+     * Collection representing the entities of this view.
+     * If you leave it blank it will be induced by your navigation
+     */
+    collection?: EntityCollection<M>;
+    /**
+     * Should update the URL when opening the dialog.
+     * Consider that if the collection that you provide is not defined in the base
+     * config of your `Rebase` component, you will not be able to recreate
+     * the state if copying the URL to a different window.
+     */
+    updateUrl?: boolean;
+    /**
+     * Callback when the entity is updated
+     * @param params
+     */
+    onUpdate?: (params: {
+        entity: Entity<any>;
+    }) => void;
+    /**
+     * Callback when the dialog is closed
+     */
+    onClose?: () => void;
+    /**
+     * Should this panel close when saving
+     */
+    closeOnSave?: boolean;
+    /**
+     * Override some form properties
+     */
+    formProps?: Partial<EntityFormProps<M>>;
+    /**
+     * Allow the user to open the entity fullscreen
+     */
+    allowFullScreen?: boolean;
+}
+/**
+ * Controller to open the side dialog displaying entity forms
+ * @group Hooks and utilities
+ */
+export interface SideEntityController {
+    /**
+     * Close the last panel
+     */
+    close: () => void;
+    /**
+     * Open a new entity sideDialog. By default, the collection and configuration
+     * of the view is fetched from the collections you have specified in the
+     * navigation.
+     * At least you need to pass the path of the entity you would like
+     * to edit. You can set an entityId if you would like to edit and existing one
+     * (or a new one with that id).
+     * @param props
+     */
+    open: <M extends Record<string, any> = any>(props: EntitySidePanelProps<M>) => void;
+    /**
+     * Replace the last open entity panel with the given one.
+     * @param props
+     */
+    replace: <M extends Record<string, any> = any>(props: EntitySidePanelProps<M>) => void;
+}

package/dist/controllers/snackbar.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Possible snackbar types
+ * @group Hooks and utilities
+ */
+export type SnackbarMessageType = "success" | "info" | "warning" | "error";
+/**
+ * Controller to display snackbars
+ * @group Hooks and utilities
+ */
+export interface SnackbarController {
+    /**
+     * Close the currently open snackbar
+     */
+    close: () => void;
+    /**
+     * Display a new snackbar. You need to specify the type and message.
+     * You can optionally specify a title
+     */
+    open: (props: {
+        type: SnackbarMessageType;
+        message: React.ReactNode;
+        autoHideDuration?: number;
+    }) => void;
+}

package/dist/controllers/storage.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @group Models
+ */
+export interface UploadFileProps {
+    file: File;
+    fileName?: string;
+    path?: string;
+    metadata?: Record<string, unknown>;
+    bucket?: string;
+}
+/**
+ * @group Models
+ */
+export interface UploadFileResult {
+    /**
+     * Storage path including the file name where the file was uploaded.
+     */
+    path: string;
+    /**
+     * Bucket where the file was uploaded
+     */
+    bucket: string;
+    /**
+     * Fully qualified storage URL for the uploaded file.
+     *
+     * For example: `gs://my-bucket/path/to/file.png`.
+     *
+     * This is optional for backwards compatibility.
+     */
+    storageUrl?: string;
+}
+/**
+ * @group Models
+ */
+export interface DownloadConfig {
+    /**
+     * Temporal url that can be used to download the file
+     */
+    url: string | null;
+    metadata?: DownloadMetadata;
+    fileNotFound?: boolean;
+}
+/**
+ * The full set of object metadata, including read-only properties.
+ * @public
+ */
+export declare interface DownloadMetadata {
+    /**
+     * The bucket this object is contained in.
+     */
+    bucket: string;
+    /**
+     * The full path of this object.
+     */
+    fullPath: string;
+    /**
+     * The short name of this object, which is the last component of the full path.
+     * For example, if path is 'full/path/image.png', name is 'image.png'.
+     */
+    name: string;
+    /**
+     * The size of this object, in bytes.
+     */
+    size: number;
+    /**
+     * Type of the uploaded file
+     * e.g. "image/jpeg"
+     */
+    contentType: string;
+    customMetadata: Record<string, unknown>;
+}
+/**
+ * @group Models
+ */
+export interface StorageSource {
+    /**
+     * Upload a file, specifying a name and a path
+     * @param file
+     * @param fileName
+     * @param path
+     * @param metadata
+     * @param bucket
+     */
+    uploadFile: ({ file, fileName, path, metadata, bucket }: UploadFileProps) => Promise<UploadFileResult>;
+    /**
+     * Convert a storage path or URL into a download configuration
+     * @param path
+     * @param bucket
+     */
+    getDownloadURL: (pathOrUrl: string, bucket?: string) => Promise<DownloadConfig>;
+    /**
+     * Get a file from a storage path.
+     * It returns null if the file does not exist.
+     * @param props
+     * @param bucket
+     */
+    getFile: (path: string, bucket?: string) => Promise<File | null>;
+    /**
+     * Delete a file.
+     * @param path
+     * @param bucket
+     */
+    deleteFile: (path: string, bucket?: string) => Promise<void>;
+    /**
+     * List the contents of a path.
+     * @param path
+     * @param options
+     */
+    list: (path: string, options?: {
+        bucket?: string;
+        maxResults?: number;
+        pageToken?: string;
+    }) => Promise<StorageListResult>;
+}
+/**
+ * Result returned by list().
+ * @public
+ */
+export declare interface StorageListResult {
+    /**
+     * References to prefixes (sub-folders). You can call list() on them to
+     * get its contents.
+     *
+     * Folders are implicit based on '/' in the object paths.
+     * For example, if a bucket has two objects '/a/b/1' and '/a/b/2', list('/a')
+     * will return '/a/b' as a prefix.
+     */
+    prefixes: StorageReference[];
+    /**
+     * Objects in this directory.
+     * You can call getMetadata() and getDownloadUrl() on them.
+     */
+    items: StorageReference[];
+    /**
+     * If set, there might be more results for this list. Use this token to resume the list.
+     */
+    nextPageToken?: string;
+}
+/**
+ * Represents a reference to a Google Cloud Storage object. Developers can
+ * upload, download, and delete objects, as well as get/set object metadata.
+ * @public
+ */
+export declare interface StorageReference {
+    /**
+     * Returns a gs:// URL for this object in the form
+     *   `gs://<bucket>/<path>/<to>/<object>`
+     * @returns The gs:// URL.
+     */
+    toString(): string;
+    /**
+     * A reference to the root of this object's bucket.
+     */
+    root: StorageReference;
+    /**
+     * The name of the bucket containing this reference's object.
+     */
+    bucket: string;
+    /**
+     * The full path of this object.
+     */
+    fullPath: string;
+    /**
+     * The short name of this object, which is the last component of the full path.
+     * For example, if path is 'full/path/image.png', name is 'image.png'.
+     */
+    name: string;
+    /**
+     * A reference pointing to the parent location of this reference, or null if
+     * this reference is the root.
+     */
+    parent: StorageReference | null;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./rebase_context";
+export * from "./types";
+export * from "./components";
+export * from "./controllers";
+export * from "./users";