@rebasepro/cms 0.0.1-canary.4d4fb3e

package/src/types/components/EntityFormProps.tsx

@@ -0,0 +1,54 @@
+import { Entity, EntityStatus } from "@rebasepro/types";
+import { EntityCollection, EntityCustomViewParams } from "@rebasepro/types";
+import { FormContext } from "../fields";
+import { FormexController } from "./formex";
+import { EntityFormActionsProps } from "./EntityFormActionsProps";
+
+export type EntityFormProps<M extends Record<string, unknown>> = {
+    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>; // dirty cached entity in memory
+    onFormContextReady?: (formContext: FormContext<M>) => 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/src/types/components/PropertyPreviewProps.tsx

@@ -0,0 +1,59 @@
+import { InferPropertyType } from "@rebasepro/types";
+import { Property } from "@rebasepro/types";
+
+/**
+ * @group Preview components
+ */
+export type PreviewSize = "small" | "medium" | "large";
+
+/**
+ * @group Preview components
+ */
+export interface PropertyPreviewProps<P extends Property | Property, CustomProps = unknown> {
+    /**
+     * Name of the property
+     */
+    propertyKey?: string;
+
+    value: any;
+
+    /**
+     * 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/src/types/components/formex.tsx

@@ -0,0 +1,46 @@
+import React, { FormEvent } from "react";
+
+// this is duplicated from the formex package
+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/src/types/components/index.ts

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

package/src/types/fields.tsx

@@ -0,0 +1,299 @@
+import { InferPropertyType } from "@rebasepro/types";
+import { Entity } from "@rebasepro/types";
+import { FormexController } from "./components/formex";
+import { EntityCollection } from "@rebasepro/types";
+import { Property } from "@rebasepro/types";
+
+export type DefaultFieldConfig =
+    | "text_field"
+    | "multiline"
+    | "markdown"
+    | "url"
+    | "email"
+    | "switch"
+    | "select"
+    | "multi_select"
+    | "user_select"
+    | "number_input"
+    | "number_select"
+    | "multi_number_select"
+    | "file_upload"
+    | "multi_file_upload"
+    | "reference_as_string"
+    | "reference"
+    | "multi_references"
+    | "relation"
+    | "date_time"
+    | "group"
+    | "key_value"
+    | "repeat"
+    | "custom_array"
+    | "block";
+
+/**
+ * When building a custom field you need to create a React component that takes
+ * this interface as props.
+ *
+ * @group Form custom fields
+ */
+export interface FieldProps<
+    P extends Property | Property = Property,
+    CustomProps = any,
+    M extends Record<string, any> = any> {
+
+    /**
+     * Key of the property
+     * E.g. "user.name" for a property with path "user.name"
+     */
+    propertyKey: string;
+
+    /**
+     * Current value of this field, inferred from the property type P
+     */
+    value: any;
+
+    /**
+     * Set value of field directly
+     */
+    setValue: (value: any | null, shouldValidate?: boolean) => void;
+
+    /**
+     * Set value of a different field directly
+     * @param propertyKey
+     * @param value
+     * @param shouldValidate
+     */
+    setFieldValue: (propertyKey: string, value: unknown, shouldValidate?: boolean) => void;
+
+    /**
+     * Is the form currently submitting
+     */
+    isSubmitting?: boolean;
+
+    /**
+     * Should this field show the error indicator.
+     * Note that there might be an error (like an empty field that should be
+     * filled) but we don't want to show the error until the user has tried
+     * saving.
+     */
+    showError?: boolean;
+
+    /**
+     * Is there an error in this field. The error field has the same shape as
+     * the field, replacing values with a string containing the error.
+     * It takes the value `null` if there is no error
+     */
+    error?: string;
+
+    /**
+     * Has this field been touched
+     */
+    touched?: boolean;
+
+    /**
+     * Property related to this field, now strongly typed to P
+     */
+    property: P;
+
+    /**
+     * Should this field include a description
+     */
+    includeDescription?: boolean;
+
+    /**
+     * Flag to indicate that the underlying value has been updated in the
+     * driver
+     */
+    underlyingValueHasChanged?: boolean;
+
+    /**
+     * Is this field part of an array
+     */
+    partOfArray?: boolean;
+
+    /**
+     * Is this field part of a block
+     */
+    partOfBlock?: boolean;
+
+    /**
+     * Display the child properties directly, without being wrapped in an
+     * extendable panel. Note that this will also hide the title of this property.
+     */
+    minimalistView?: boolean;
+
+    /**
+     * Should this field autofocus on mount
+     */
+    autoFocus?: boolean;
+
+    /**
+     * Additional properties set by the developer
+     */
+    customProps: CustomProps
+
+    /**
+     * Additional values related to the state of the form or the entity
+     */
+    context: FormContext<M>;
+
+    /**
+     * Flag to indicate if this field should be disabled
+     */
+    disabled?: boolean;
+
+    /**
+     * Size of the field
+     */
+    size?: "small" | "medium" | "large";
+
+    /**
+     * Some properties might change internal state (like expanding a panel).
+     * This function should be called when the internal state changes.
+     * This is used to preserve state in array containers.
+     *
+     * @param property
+     */
+    onPropertyChange?: (property: Partial<Property>) => void;
+
+}
+
+/**
+ * Context passed to custom fields
+ * @group Form custom fields
+ */
+export interface FormContext<M extends Record<string, unknown> = Record<string, unknown>> {
+
+    /**
+     * Current values of the entity
+     */
+    values: M;
+
+    /**
+     * Update the value of a field
+     * @param key
+     * @param value
+     * @param shouldValidate
+     */
+    setFieldValue: (key: string, value: unknown, shouldValidate?: boolean) => void;
+
+    /**
+     * Save the entity.
+     */
+    save: (values: M) => void;
+
+    /**
+     * Collection of the entity being modified
+     */
+    collection?: EntityCollection<M>;
+
+    /**
+     * Entity id, it can be undefined if it's a new entity
+     */
+    entityId?: string | number;
+
+    /**
+     * Path this entity is located at
+     */
+    path?: string;
+
+    status: "new" | "existing" | "copy";
+
+    entity?: Entity<M>;
+
+    savingError?: Error;
+
+    openEntityMode: "side_panel" | "full_screen";
+
+    /**
+     * This is the underlying formex controller that powers the form.
+     * If you are in a red only mode, the formex controller is there, but you can't
+     * operate with it
+     */
+    formex: FormexController<M>;
+
+    disabled: boolean;
+}
+
+/**
+ * In case you need to render a field bound to a Property inside your
+ * custom field you can use {@link PropertyFieldBinding} with these props.
+ * @group Form custom fields
+ */
+export interface PropertyFieldBindingProps<M extends Record<string, unknown> = Record<string, unknown>> {
+
+    /**
+     * The key/path of the property, such as `age`. You can use nested and array
+     * indexed such as `address.street` or `people[3]`
+     */
+    propertyKey: string;
+
+    /**
+     * The CMS property you are binding this field to
+     */
+    property: Property;
+
+    /**
+     * The context where this field is being rendered. You get a context as a
+     * prop when creating a custom field.
+     */
+    context: FormContext<M>;
+
+    /**
+     * Should the description be included in this field
+     */
+    includeDescription?: boolean;
+
+    /**
+     * Has the value of this property been updated in the database while this
+     * field is being edited
+     */
+    underlyingValueHasChanged?: boolean;
+
+    /**
+     * Is this field part of an array
+     */
+    partOfArray?: boolean;
+
+    /**
+     * Is this field part of a block
+     */
+    partOfBlock?: boolean;
+
+    /**
+     * Display the child properties directly, without being wrapped in an
+     * extendable panel. Note that this will also hide the title of this property.
+     */
+    minimalistView?: boolean;
+
+    /**
+     * Should the field take focus when rendered. When opening the popup view
+     * in table mode, it makes sense to put the focus on the only field rendered.
+     */
+    autoFocus?: boolean;
+
+    /**
+     * Should this field be disabled
+     */
+    disabled?: boolean;
+
+    /**
+     * Index of the field in the array.
+     * Only used when the field is part of an array.
+     */
+    index?: number;
+
+    /**
+     * The size of the field
+     */
+    size?: "small" | "medium" | "large",
+
+    /**
+     * Some properties might change internal state (like expanding a panel).
+     * This function should be called when the internal state changes.
+     * This is used to preserve state in array containers.
+     *
+     * @param property
+     */
+    onPropertyChange?: (property: Partial<Property>) => void;
+}

package/src/types/index.ts

@@ -0,0 +1,4 @@
+export * from "./fields";
+export * from "./components";
+
+

package/src/util/entity_actions.ts

@@ -0,0 +1,28 @@
+import type { EntityAction } from "@rebasepro/types";
+
+const reservedKeys = ["edit", "copy", "delete"];
+
+export function mergeEntityActions(currentActions: EntityAction[], newActions: EntityAction[]): EntityAction[] {
+    // given the current actions, replace the ones with the same key
+    // and append the new ones
+    const updatedActions: EntityAction[] = [];
+    currentActions.forEach(action => {
+        const newAction = newActions.find(a => a.key === action.key);
+        if (newAction) {
+            const mergedAction = {
+                ...action,
+                ...newAction
+            }
+            updatedActions.push(mergedAction);
+        } else {
+            updatedActions.push(action);
+        }
+    });
+    newActions.forEach(action => {
+        if (!currentActions.find(a => a.key === action.key) && (!action.key || !reservedKeys.includes(action.key))) {
+            updatedActions.push(action);
+        }
+    });
+    return updatedActions;
+
+}

package/src/util/index.ts

@@ -0,0 +1,5 @@
+export * from "./entity_actions";
+export * from "./navigation_utils";
+export * from "./resolutions";
+export * from "./property_utils";
+export * from "./previews";