@rebasepro/cms-types 0.17.0-canary.0

package/dist/types/form_layout.d.ts

@@ -0,0 +1,126 @@
+import type { ColumnKey } from "../admin_collection.js";
+/**
+ * The number of columns the form grid is divided into. A field's
+ * {@link AdminPropertyOptions.span} is expressed against this.
+ *
+ * Fixed rather than configurable on purpose: the whole point of a span is that
+ * two fields written by two different people line up, and they only do that if
+ * everyone is counting against the same grid.
+ *
+ * @group Models
+ */
+export declare const FORM_GRID_COLUMNS = 4;
+/**
+ * How wide a field sits on the {@link FORM_GRID_COLUMNS}-column form grid.
+ *
+ * `4` is the full width of the main column. A field always takes at least a
+ * whole row on narrow layouts (the side panel, the split pane, mobile), where
+ * the grid collapses to one column and spans are ignored.
+ *
+ * @group Entity properties
+ */
+export type PropertySpan = 1 | 2 | 3 | 4;
+/**
+ * A titled group of fields in the main column of the form.
+ *
+ * @group Models
+ */
+export interface FormSection<M extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Stable identity for this section. Used as the React key and to remember
+     * the collapsed state across visits, so renaming `title` does not lose it.
+     */
+    key: string;
+    /**
+     * Shown above the group. A section with no title renders its fields with no
+     * heading and no rule — useful for the first group, which rarely needs one.
+     */
+    title?: string;
+    /**
+     * Property and additional-field keys in this section, in render order.
+     *
+     * Keys naming a property that does not exist, is hidden, or has been routed
+     * to {@link FormLayoutConfig.sidebar} are skipped. Any property *not* named
+     * by a section lands in the last section that has no explicit title, or in
+     * an untitled trailing group if there is none — a new column is never
+     * silently dropped from the form.
+     */
+    properties: ColumnKey<M>[];
+    /**
+     * Start collapsed. Defaults to `false`.
+     *
+     * Only meaningful when the section can be collapsed at all; a section with
+     * no `title` has nothing to click, so this is ignored there.
+     */
+    collapsed?: boolean;
+    /**
+     * Can the user collapse this section. Defaults to `true` for a titled
+     * section, `false` for an untitled one.
+     *
+     * A section holding a required field is still collapsible — but a
+     * validation error inside a collapsed section expands it, so an error can
+     * never hide.
+     */
+    collapsible?: boolean;
+    /**
+     * How this section arranges itself in the **read-only** view of a record.
+     * Defaults to `"grid"` — the same grid the form uses.
+     *
+     * `"summary"` stacks the fields as right-aligned label/value rows with the
+     * last one emphasised, which is what a run of related figures wants: a
+     * subtotal, a tax, a discount and a total are one calculation, and four
+     * equal cells on a four-column grid is the one arrangement that says they
+     * are unrelated. Opt in per section — nothing about a group of numbers tells
+     * us it adds up, so this is never derived.
+     *
+     * Read-only only, and named for it. The form goes on rendering the grid:
+     * a summary row is a reading arrangement, and shrinking a control to fit one
+     * would make the fields harder to edit to make them prettier to skim.
+     */
+    readVariant?: "grid" | "summary";
+}
+/**
+ * How the generated form is laid out.
+ *
+ * Everything here is optional, and the defaults are the point: with no config
+ * at all the layout is derived from the properties themselves —
+ *
+ * - the id and the `createdAt`/`updatedAt` timestamps go to the rail, read-only
+ * - short enums, booleans, dates and numbers take a narrow span
+ * - long text, markdown, arrays, maps and storage fields take the full width
+ * - everything else takes half
+ *
+ * so a collection that never mentions `form` still gets a two-column layout
+ * rather than one flat run of full-width fields. Use this block when the
+ * derived answer is wrong for your domain.
+ *
+ * @group Models
+ */
+export interface FormLayoutConfig<M extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Property keys shown in the metadata rail beside the main column instead
+     * of in it — status, ownership, publication dates, flags.
+     *
+     * The rail is narrow and does not use the grid, so `span` is ignored for
+     * these. On layouts too narrow for a rail (the side panel, the split pane,
+     * mobile) they render as an ordinary leading section, so nothing is lost.
+     *
+     * Set to `[]` to suppress the derived rail entirely and keep every field in
+     * the main column.
+     */
+    sidebar?: ColumnKey<M>[];
+    /**
+     * Groups for the main column. When omitted, every field lands in a single
+     * untitled group, which is the pre-existing behaviour.
+     */
+    sections?: FormSection<M>[];
+    /**
+     * Show the read-only record block (id, created, updated) at the foot of the
+     * rail. Defaults to `true` when a rail is shown.
+     *
+     * This is what replaces `hideIdFromForm` for most collections: the id stops
+     * being a field in the middle of the form and becomes a copyable line of
+     * metadata.
+     */
+    showRecordMeta?: boolean;
+}

package/dist/types/formex.d.ts

@@ -0,0 +1,40 @@
+import React, { FormEvent } from "react";
+export type FormexController<T = unknown> = {
+    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 = unknown> = {
+    values?: T;
+    submitCount?: number;
+    errors?: Record<string, string>;
+    touched?: Record<string, boolean>;
+};

package/dist/types/index.d.ts

@@ -0,0 +1,18 @@
+export * from "./breadcrumbs.js";
+export * from "./builders.js";
+export * from "./collection_views.js";
+export * from "./component_overrides.js";
+export * from "./entity_actions.js";
+export * from "./entity_link_builder.js";
+export * from "./entity_display.js";
+export * from "./entity_views.js";
+export * from "./export_import.js";
+export * from "./form_layout.js";
+export * from "./formex.js";
+export * from "./locales.js";
+export * from "./modify_collections.js";
+export * from "./plugins.js";
+export * from "./property_config.js";
+export * from "./slots.js";
+export * from "./translations.js";
+export * from "./user_management_delegate.js";

package/dist/types/locales.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @group Models
+ */
+export type Locale = "af" | "ar" | "arDZ" | "arMA" | "arSA" | "az" | "be" | "bg" | "bn" | "ca" | "cs" | "cy" | "da" | "de" | "el" | "enAU" | "enCA" | "enGB" | "enIN" | "enNZ" | "enUS" | "eo" | "es" | "et" | "eu" | "faIR" | "fi" | "fil" | "fr" | "frCA" | "frCH" | "gd" | "gl" | "gu" | "he" | "hi" | "hr" | "hu" | "hy" | "id" | "is" | "it" | "ja" | "ka" | "kk" | "kn" | "ko" | "lb" | "lt" | "lv" | "mk" | "ms" | "mt" | "nb" | "nl" | "nlBE" | "nn" | "pl" | "pt" | "ptBR" | "ro" | "ru" | "sk" | "sl" | "sr" | "srLatn" | "sv" | "ta" | "te" | "th" | "tr" | "ug" | "uk" | "uz" | "vi" | "zhCN" | "zhTW";

package/dist/types/modify_collections.d.ts

@@ -0,0 +1,5 @@
+import type { AdminCollection } from "@rebasepro/cms-types";
+export type ModifyCollectionProps = {
+    collection: AdminCollection;
+    parentPaths: string[];
+};

package/dist/types/plugins.d.ts

@@ -0,0 +1,277 @@
+import React, { PropsWithChildren } from "react";
+import type { EntityStatus } from "@rebasepro/types";
+import type { InferPropertyType, Property } from "@rebasepro/types";
+import type { FormContext } from "./entity_views.js";
+import type { RebaseContext } from "../rebase_context.js";
+import type { NavigationGroupMapping, AppView } from "../controllers/navigation.js";
+import type { User } from "@rebasepro/types";
+import type { SlotContribution } from "./slots.js";
+import type { AdminCollection } from "@rebasepro/cms-types";
+/**
+ * Props interface for custom field components.
+ *
+ * The `@rebasepro/cms` package re-exports a narrower version of this
+ * interface that adds `formex` and layout-specific fields. This base
+ * definition captures the core contract that every field renderer must
+ * satisfy, regardless of where it is rendered.
+ *
+ * @typeParam P - The property type this field is bound to
+ * @typeParam CustomProps - Extra props injected via the property's `customProps`
+ * @typeParam M - The entity model type
+ * @group Form custom fields
+ */
+export interface FieldProps<P extends Property = Property, CustomProps = unknown, M extends Record<string, unknown> = Record<string, unknown>> {
+    /** Key of the property (e.g. "user.name" for a nested path) */
+    propertyKey: string;
+    /** Current value of this field */
+    value: InferPropertyType<P> | null;
+    /** Set value of field directly */
+    setValue: (value: InferPropertyType<P> | null, shouldValidate?: boolean) => void;
+    /** Set value of a different field directly */
+    setFieldValue: (propertyKey: string, value: unknown, shouldValidate?: boolean) => void;
+    /** Is the form currently submitting */
+    isSubmitting?: boolean;
+    /** Should this field show the error indicator */
+    showError?: boolean;
+    /** Error message for this field, or undefined if valid */
+    error?: string;
+    /** Has this field been touched */
+    touched?: boolean;
+    /** Property related to this field */
+    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 */
+    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";
+    /** Callback when internal property state changes (e.g. panel expansion) */
+    onPropertyChange?: (property: Partial<Property>) => void;
+}
+/**
+ * Interface used to define plugins for Rebase.
+ * Plugins contribute UI via **slots**, wrap subtrees with **providers**,
+ * and inject behavioral logic via **hooks**.
+ * @group Core
+ */
+export interface RebasePlugin {
+    /**
+     * Unique key identifying this plugin.
+     */
+    key: string;
+    /**
+     * If true, no admin content is shown until this plugin finishes loading.
+     */
+    loading?: boolean;
+    /**
+     * UI slot contributions rendered at the matching extension points.
+     */
+    slots?: SlotContribution[];
+    /**
+     * HOC providers wrapping root or form content.
+     * Providers with `scope: "root"` wrap the entire admin below RebaseContext.
+     * Providers with `scope: "form"` wrap each entity form/edit view.
+     */
+    providers?: PluginProvider[];
+    /**
+     * Behavioral hooks (non-UI) — collection modification, search blocking,
+     * column reordering, navigation entries, etc.
+     */
+    hooks?: PluginHooks;
+    /**
+     * Field wrapping for custom field rendering (e.g. data enhancement).
+     */
+    fieldBuilder?: FieldBuilderConfig;
+    /**
+     * Views to be automatically added to the navigation.
+     */
+    views?: AppView[];
+    /**
+     * Optional lifecycle hooks. Called by the Rebase runtime
+     * at appropriate points in the app lifecycle.
+     */
+    lifecycle?: PluginLifecycle;
+}
+/**
+ * A HOC provider that wraps a subtree of the admin.
+ * @group Plugins
+ */
+export interface PluginProvider {
+    /**
+     * `"root"` — wraps the entire admin below RebaseContext.
+     * `"form"` — wraps each entity form / edit view.
+     */
+    scope: "root" | "form";
+    /**
+     * The provider component. Must accept `children`.
+     * Typed loosely because extra props are passed via the `props` field;
+     * strict signatures cause contravariance issues.
+     */
+    Component: React.ComponentType<PropsWithChildren<Record<string, unknown>>>;
+    /**
+     * Additional props passed to the Component.
+     */
+    props?: Record<string, unknown>;
+}
+/**
+ * Behavioral hooks that a plugin can provide.
+ * These are non-UI extension points for modifying admin behavior.
+ * @group Plugins
+ */
+export interface PluginHooks {
+    /**
+     * Modify a single collection before it is rendered (synchronous).
+     */
+    modifyCollection?: (collection: AdminCollection) => AdminCollection;
+    /**
+     * Async version of modifyCollection — supports fetching remote config.
+     * Runs during navigation resolution. If provided alongside `modifyCollection`,
+     * the sync version runs first, then the async version.
+     */
+    modifyCollectionAsync?: (collection: AdminCollection) => Promise<AdminCollection>;
+    /**
+     * Modify, add or remove collections.
+     */
+    injectCollections?: (collections: AdminCollection[]) => AdminCollection[];
+    /**
+     * Callback called when columns are reordered via drag and drop.
+     */
+    onColumnsReorder?: (props: {
+        fullPath: string;
+        parentCollectionSlugs: string[];
+        parentEntityIds: string[];
+        collection: AdminCollection;
+        newPropertiesOrder: string[];
+    }) => void;
+    /**
+     * Callback called when Kanban board columns are reordered.
+     */
+    onKanbanColumnsReorder?: (props: {
+        fullPath: string;
+        parentCollectionSlugs: string[];
+        parentEntityIds: string[];
+        collection: AdminCollection;
+        kanbanColumnProperty: string;
+        newColumnsOrder: string[];
+    }) => void;
+    /**
+     * Navigation entries contributed by this plugin.
+     */
+    navigationEntries?: NavigationGroupMapping[];
+    /**
+     * Callback when navigation entry order changes (e.g. drag-and-drop).
+     */
+    onNavigationEntriesUpdate?: (entries: NavigationGroupMapping[]) => void;
+    /**
+     * Allow reordering collections in the home page via drag and drop.
+     */
+    allowDragAndDrop?: boolean;
+}
+/**
+ * Lifecycle hooks for plugins. Called by the Rebase runtime
+ * at appropriate points in the app lifecycle.
+ * @group Plugins
+ */
+export interface PluginLifecycle {
+    /**
+     * Called once when the plugin is mounted in the Rebase tree.
+     * Can return a Promise for async initialization.
+     */
+    onMount?: (context: RebaseContext) => void | Promise<void>;
+    /**
+     * Called when the plugin is unmounted from the Rebase tree.
+     * Use this for cleanup (subscriptions, timers, etc.).
+     */
+    onUnmount?: () => void;
+    /**
+     * Called whenever the authentication state changes.
+     * Receives the new user (or null on sign-out).
+     */
+    onAuthStateChange?: (user: User | null) => void;
+    /**
+     * Called when a collection's visible entities change.
+     * Useful for analytics, caching, or cross-plugin coordination.
+     */
+    onCollectionChange?: (slug: string, entities: unknown[]) => void;
+}
+/**
+ * Configuration for wrapping form field components.
+ * @group Plugins
+ */
+export interface FieldBuilderConfig {
+    /**
+     * Returns a wrapped field component, or null to skip wrapping.
+     */
+    wrap: <T>(params: PluginFieldBuilderParams) => React.ComponentType<FieldProps<Property>> | null;
+    /**
+     * Optional guard — return false to skip wrapping for this field.
+     */
+    enabled?: (params: PluginFieldBuilderParams) => boolean;
+}
+/**
+ * Props passed to home page collection card action components.
+ * @group Models
+ */
+export interface PluginHomePageActionsProps<EP extends object = object, M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User, EC extends AdminCollection<M> = AdminCollection<M>> {
+    slug: string;
+    collection: EC;
+    context: RebaseContext<USER>;
+}
+/**
+ * Props passed to form action components in entity edit/form views.
+ * @group Models
+ */
+export interface PluginFormActionProps<USER extends User = User, EC extends AdminCollection = AdminCollection> {
+    entityId?: string | number;
+    path: string;
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
+    status: EntityStatus;
+    collection: EC;
+    disabled: boolean;
+    formContext?: FormContext;
+    context: RebaseContext<USER>;
+    openEntityMode?: "side_panel" | "full_screen" | "split" | "dialog";
+}
+/**
+ * Parameters passed to the field builder wrap function.
+ * @group Models
+ */
+export type PluginFieldBuilderParams<M extends Record<string, unknown> = Record<string, unknown>, EC extends AdminCollection<M> = AdminCollection<M>> = {
+    fieldConfigId: string;
+    propertyKey: string;
+    property: Property;
+    Field: React.ComponentType<FieldProps<Property, unknown, M>>;
+    plugin: RebasePlugin;
+    path?: string;
+    collection?: EC;
+};
+/**
+ * Generic props passed to plugin components that just need admin context.
+ * @group Models
+ */
+export interface PluginGenericProps<USER extends User = User> {
+    context: RebaseContext<USER>;
+}
+/**
+ * Props for additional card components in the home page.
+ * @group Models
+ */
+export interface PluginHomePageAdditionalCardsProps<USER extends User = User> {
+    group?: string;
+    context: RebaseContext<USER>;
+}

package/dist/types/property_config.d.ts

@@ -0,0 +1,74 @@
+import React from "react";
+import { ArrayProperty, MapProperty, StringProperty, NumberProperty, BooleanProperty, DateProperty, GeopointProperty, ReferenceProperty, RelationProperty, VectorProperty, BinaryProperty } from "@rebasepro/types";
+import { BaseProperty } from "@rebasepro/types";
+type AdminBasePropertyNoName = Omit<BaseProperty, "name">;
+export type ConfigProperty = (Omit<StringProperty, "name"> & {
+    name?: string;
+} & AdminBasePropertyNoName) | (Omit<NumberProperty, "name"> & {
+    name?: string;
+} & AdminBasePropertyNoName) | (Omit<BooleanProperty, "name"> & {
+    name?: string;
+} & AdminBasePropertyNoName) | (Omit<DateProperty, "name"> & {
+    name?: string;
+} & AdminBasePropertyNoName) | (Omit<GeopointProperty, "name"> & {
+    name?: string;
+} & AdminBasePropertyNoName) | (Omit<ReferenceProperty, "name"> & {
+    name?: string;
+} & AdminBasePropertyNoName) | (Omit<RelationProperty, "name"> & {
+    name?: string;
+} & AdminBasePropertyNoName) | (Omit<ArrayProperty, "name" | "of" | "oneOf"> & {
+    name?: string;
+    of?: ConfigProperty | ConfigProperty[];
+    oneOf?: {
+        properties: Record<string, ConfigProperty>;
+        typeField?: string;
+        valueField?: string;
+        propertiesOrder?: string[];
+    };
+} & AdminBasePropertyNoName) | (Omit<MapProperty, "name" | "properties"> & {
+    name?: string;
+    properties?: Record<string, ConfigProperty>;
+} & AdminBasePropertyNoName) | (Omit<VectorProperty, "name"> & {
+    name?: string;
+} & AdminBasePropertyNoName) | (Omit<BinaryProperty, "name"> & {
+    name?: string;
+} & AdminBasePropertyNoName);
+/**
+ * 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" | "multi_references" | "relation" | "switch" | "date_time" | "repeat" | "custom_array" | "block" | "vector_input" | "geopoint" | "binary";
+export {};