@rebasepro/admin 0.0.1-canary.09e5ec5

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" | "split";
+
+    /**
+     * 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";

package/src/util/navigation_utils.ts

@@ -0,0 +1,69 @@
+import type { EntityCollection, UrlController, SideEntityController } from "@rebasepro/types";
+
+// Canonical path utilities — single source of truth in @rebasepro/common
+export {
+    removeInitialAndTrailingSlashes,
+    removeInitialSlash,
+    removeTrailingSlash,
+    addInitialSlash,
+    getLastSegment,
+    resolveCollectionPathIds,
+    getCollectionBySlugWithin,
+    getCollectionPathsCombinations
+} from "@rebasepro/common";
+
+/**
+ * Navigate to an entity using either a side panel or full-screen mode.
+ * This is an admin-specific UI concern and lives here (not in common).
+ */
+export function navigateToEntity({
+    openEntityMode,
+    collection,
+    entityId,
+    copy,
+    path,
+    selectedTab,
+    sideEntityController,
+    onClose,
+    navigation
+}:
+
+    {
+        openEntityMode: "side_panel" | "full_screen" | "split";
+        collection?: EntityCollection;
+        entityId?: string | number;
+        selectedTab?: string;
+        copy?: boolean;
+        path: string;
+        sideEntityController: SideEntityController;
+        onClose?: () => void;
+        navigation: UrlController
+    }) {
+
+    if (openEntityMode === "side_panel") {
+
+        sideEntityController.open({
+            entityId,
+            path: path,
+            copy,
+            selectedTab,
+            collection,
+            updateUrl: true,
+            onClose
+        });
+
+    } else {
+        let to = navigation.buildUrlCollectionPath(entityId ? `${path ?? path}/${entityId}` : path ?? path);
+        if (entityId && selectedTab) {
+            to += `/${selectedTab}`;
+        }
+        if (!entityId) {
+            to += "#new";
+        }
+        if (copy) {
+            to += "#copy";
+        }
+        navigation.navigate(to);
+    }
+
+}

package/src/util/previews.ts

@@ -0,0 +1,50 @@
+import type { EntityCollection, Property, PropertyConfig } from "@rebasepro/types";
+import { AuthController } from "@rebasepro/types";
+import { isPropertyBuilder } from "@rebasepro/common";
+import { isReferenceProperty, isRelationProperty } from "./property_utils";
+
+export function getEntityPreviewKeys(
+    authController: AuthController,
+    targetCollection: EntityCollection<any>,
+    fields: Record<string, PropertyConfig>,
+    previewProperties?: string[],
+    limit = 3) {
+    const allProperties = Object.keys(targetCollection.properties);
+    let listProperties = previewProperties?.filter(p => allProperties.includes(p as string));
+    if (!listProperties && targetCollection.previewProperties) {
+        listProperties = targetCollection.previewProperties?.filter(p => allProperties.includes(p as string));
+    }
+    if (listProperties && listProperties.length > 0) {
+        return listProperties;
+    } else {
+        listProperties = allProperties;
+        return listProperties
+            .filter(key => {
+                const prop = targetCollection.properties[key];
+                const isIdProp = prop && typeof prop === "object" && "isId" in prop && Boolean((prop as unknown as { isId?: boolean }).isId);
+                return !isIdProp;
+            })
+            .filter(key => {
+                const property = targetCollection.properties[key];
+                return property && !isPropertyBuilder(property) && !isReferenceProperty(property) && !isRelationProperty(property);
+            }).slice(0, limit);
+    }
+}
+
+export function getEntityTitlePropertyKey<M extends Record<string, unknown>>(collection: EntityCollection<M>, propertyConfigs: Record<string, PropertyConfig>): string | undefined {
+    if (collection.titleProperty) {
+        return collection.titleProperty as string;
+    }
+    // find first text field property
+    for (const key in collection.properties) {
+        const property = collection.properties[key];
+        if (!isPropertyBuilder(property)) {
+            const prop = property as Property;
+            if (prop.type === "string" && !prop.multiline && !prop.markdown && !prop.storage && !prop.isId) {
+                return key;
+            }
+        }
+    }
+    return undefined;
+}
+

package/src/util/property_utils.tsx

@@ -0,0 +1,215 @@
+
+import type { Properties } from "@rebasepro/types";
+import type { EntityCollection, MapProperty, Property, PropertyConfig } from "@rebasepro/types";
+import React from "react";
+
+import { isPropertyBuilder } from "@rebasepro/common";
+import { iconSize } from "@rebasepro/ui";
+import type { IconSize } from "@rebasepro/ui";
+import { CircleIcon, FlagIcon, FunctionSquareIcon, GlobeIcon, TextIcon, Rows3Icon, LinkIcon, VoteIcon, MailIcon, HashIcon, RepeatIcon, CalendarIcon, AlignLeftIcon, UploadIcon } from "lucide-react";
+import type { LucideIcon } from "lucide-react";
+
+/**
+ * Resolve a size value (string token or number) to a numeric pixel value
+ * suitable for passing to Lucide icons.
+ */
+function resolveSize(size: IconSize | number): number {
+    if (typeof size === "number") return size;
+    return iconSize[size];
+}
+
+export function isReferenceProperty(property: Property) {
+
+    if (!property) return null;
+    if (property.type === "reference") {
+        return true;
+    }
+    if (property.type === "array") {
+        if (Array.isArray(property.of)) return false;
+        else return property.of?.type === "reference"
+    }
+    return false;
+}
+
+export function isRelationProperty(property: Property) {
+    if (!property) return null;
+    if (property.type === "relation") {
+        return true;
+    }
+    if (property.type === "array") {
+        if (Array.isArray(property.of)) return false;
+        else return property.of?.type === "relation"
+    }
+    return false;
+}
+
+export function getIconForWidget(widget: PropertyConfig | undefined,
+    size: IconSize | number) {
+    const Icon = widget?.Icon ?? CircleIcon;
+    const px = resolveSize(size);
+    return <Icon size={px}/>;
+}
+
+/**
+ * Returns a default Lucide icon component based on property type.
+ * This provides a sensible fallback when no PropertyConfig is available.
+ */
+function getDefaultIconForProperty(property: Property): LucideIcon {
+    switch (property.type) {
+        case "string": {
+            if (property.storage) return UploadIcon;
+            if (property.url) return GlobeIcon;
+            if (property.email) return MailIcon;
+            if (property.multiline || property.markdown) return AlignLeftIcon;
+            if (property.reference) return LinkIcon;
+            return TextIcon;
+        }
+        case "number":
+            return HashIcon;
+        case "boolean":
+            return FlagIcon;
+        case "date":
+            return CalendarIcon;
+        case "map":
+            return VoteIcon;
+        case "array": {
+            const of = property.of;
+            const oneOf = property.oneOf;
+            if (oneOf) return Rows3Icon;
+            if (of && !Array.isArray(of)) {
+                if (of.type === "reference") return LinkIcon;
+                if (of.type === "string" && of.storage) return UploadIcon;
+            }
+            return RepeatIcon;
+        }
+        case "reference":
+            return LinkIcon;
+        case "relation":
+            return LinkIcon;
+        default:
+            return CircleIcon;
+    }
+}
+
+export function getIconForProperty(
+    property: Property,
+    size: IconSize | number = "small",
+    fields: Record<string, PropertyConfig> = {}
+): React.ReactNode {
+    const px = resolveSize(size);
+
+    if (isPropertyBuilder(property)) {
+        return <FunctionSquareIcon size={px}/>;
+    }
+
+    // Try to look up a custom PropertyConfig icon first
+    const configId = property.propertyConfig || undefined;
+    const widget = configId ? fields[configId] : undefined;
+    if (widget?.Icon) {
+        return getIconForWidget(widget, size);
+    }
+
+    // Fall back to a type-based default icon
+    const Icon = getDefaultIconForProperty(property);
+    return <Icon size={px}/>;
+}
+
+/**
+ * Get a property in a property tree from a path like
+ * `address.street`
+ * @param properties
+ * @param path
+ */
+export function getPropertyInPath(properties: Properties, path: string): Property | undefined {
+    if (typeof properties === "object") {
+        if (path in properties) {
+            return (properties as Record<string, Property>)[path];
+        }
+        if (path.includes(".")) {
+            const pathSegments = path.split(".");
+            const childProperty = (properties as Record<string, Property>)[pathSegments[0]];
+            if (typeof childProperty === "object" && childProperty.type === "map" && childProperty.properties) {
+                return getPropertyInPath(childProperty.properties, pathSegments.slice(1).join("."))
+            }
+        }
+    }
+    return undefined;
+}
+
+export function getResolvedPropertyInPath(properties: Record<string, Property>, path: string): Property | undefined {
+    if (typeof properties === "object") {
+        if (path in properties) {
+            return properties[path];
+        }
+        if (path.includes(".")) {
+            const pathSegments = path.split(".");
+            const childProperty = properties[pathSegments[0]];
+            if (childProperty.type === "map" && childProperty.properties) {
+                return getResolvedPropertyInPath(childProperty.properties, pathSegments.slice(1).join("."))
+            }
+        }
+    }
+    return undefined;
+}
+
+// replace the dot notation with brackets
+// address.street => address[street]
+export function getBracketNotation(path: string): string {
+    return path.replace(/\.([^.]*)/g, "[$1]");
+}
+
+/**
+ * Get properties sorted by their order, but include ALL properties.
+ * Nested keys (like "data.mode") in propertiesOrder are ignored - they're for column ordering.
+ * @param properties
+ * @param propertiesOrder
+ */
+export function getPropertiesWithPropertiesOrder(properties: Properties, propertiesOrder?: string[]): Properties {
+    if (!propertiesOrder) return properties;
+
+    const propertyKeys = Object.keys(properties);
+
+    // Filter propertiesOrder to only include top-level keys (no dots) that exist
+    const validOrderKeys = (propertiesOrder as string[]).filter(
+        key => !key.includes(".") && properties[key]
+    );
+
+    const result: Properties = {};
+
+    // First add properties in the specified order
+    validOrderKeys.forEach(key => {
+        const property = properties[key];
+        if (typeof property === "object" && property.type === "map" && (property as MapProperty).properties) {
+            const mapProp = property as MapProperty;
+            result[key] = {
+                ...mapProp,
+                properties: getPropertiesWithPropertiesOrder(mapProp.properties!, mapProp.propertiesOrder ?? [])
+            } as Property;
+        } else if (property) {
+            result[key] = property;
+        }
+    });
+
+    // Then add any missing properties (so they don't disappear!)
+    propertyKeys.forEach(key => {
+        if (!result[key]) {
+            const property = properties[key];
+            if (typeof property === "object" && property.type === "map" && (property as MapProperty).properties) {
+                const mapProp = property as MapProperty;
+                result[key] = {
+                    ...mapProp,
+                    properties: getPropertiesWithPropertiesOrder(mapProp.properties!, mapProp.propertiesOrder ?? [])
+                } as Property;
+            } else if (property) {
+                result[key] = property;
+            }
+        }
+    });
+
+    return result;
+}
+
+export function getDefaultPropertiesOrder(collection: EntityCollection): string[] {
+    if (collection.propertiesOrder) return collection.propertiesOrder;
+    return [...Object.keys(collection.properties), ...(collection.additionalFields ?? []).map(field => field.key)];
+}