@rebasepro/cms-types 0.17.0-canary.0

package/src/types/entity_display.ts

@@ -0,0 +1,182 @@
+/**
+ * How a record shows up: its title, image, subtitle, status, date and tags.
+ *
+ * Every surface that draws a record draws some subset of these six roles. A list
+ * row is image + title + subtitle + status + date; a card is the same with the
+ * image on top; a board card drops the image; a reference picker is title +
+ * subtitle; a page heading is the title alone. The roles are stable — what fills
+ * them is not.
+ *
+ * Before this block, the roles were derived and only derived. `titleProperty`
+ * was the single exception, and it could only ever name a property of the
+ * collection: seven separate implementations read that key, disagreed about the
+ * fallback, and none of them could await. (It is gone now — `display.title`
+ * replaced it outright.) The other five roles could not be
+ * stated at all — the image was whichever storage property came first, the
+ * status whichever enum, the date whichever timestamp. Right often enough to
+ * feel automatic, and wrong with no way to say so.
+ *
+ * So: one mechanism, six roles, two forms each.
+ *
+ * ```ts
+ * admin: {
+ *     display: {
+ *         title: "name",                       // a property path
+ *         image: "photos.0",                   // a dotted path
+ *         subtitle: ({ entity }) =>            // computed
+ *             `${entity.values.city}, ${entity.values.country}`,
+ *         status: async ({ entity, context }) => {   // and may be async
+ *             const latest = await context.data.audits.get(`${entity.id}/latest`);
+ *             return latest?.state;
+ *         }
+ *     }
+ * }
+ * ```
+ *
+ * Anything left out is derived exactly as it is today, so an existing collection
+ * renders identically, and a collection that needs one role fixed states that
+ * one role.
+ */
+import type { Entity, User } from "@rebasepro/types";
+import type { RebaseContext } from "../rebase_context";
+
+/**
+ * What a resolver is handed.
+ *
+ * The whole {@link RebaseContext}, matching `AdditionalFieldDelegate.value` and
+ * `EntityAction.onClick` — so a resolver can reach `context.data` and
+ * `context.client` and read anything the panel can read, including a document in
+ * a subcollection that the entity itself never loads.
+ */
+export type EntityDisplayResolverParams<
+    M extends Record<string, unknown> = Record<string, unknown>,
+    USER extends User = User
+> = {
+    entity: Entity<M>;
+    context: RebaseContext<USER>;
+};
+
+/**
+ * Computes what fills one display role for one record.
+ *
+ * May be async. While a promise is in flight the surface shows the derived value
+ * and swaps the resolved one in when it lands — a title is never a spinner.
+ * Results are cached per record and per role, and concurrent calls for the same
+ * pair share one execution, so a list of fifty rows resolves each row once
+ * rather than once per render.
+ *
+ * Return `undefined` when this record has nothing for this role. Do not return a
+ * placeholder: the surface's own fallback is better informed than the resolver
+ * is about what belongs there instead — a heading wants the collection's
+ * singular name, a link wants the id.
+ *
+ * A resolver that throws is treated as `undefined` and logged once. A title that
+ * cannot be fetched must not take down the row that shows it.
+ */
+export type EntityDisplayResolver<
+    M extends Record<string, unknown> = Record<string, unknown>,
+    T = unknown,
+    USER extends User = User
+> = {
+    /**
+     * Declared as a *method* and then indexed back out, which is the only way to
+     * write a standalone function type whose parameters stay bivariant.
+     *
+     * Not a style choice. `AdminCollectionOptions<M>` has to remain assignable
+     * to `AdminCollectionOptions<Record<string, unknown>>` — every consumer that
+     * takes a collection it did not author depends on it, and losing it breaks
+     * `defineCollection`'s own overloads. A resolver takes `Entity<M>` in
+     * parameter position, so written as `(params) => …` it makes the entire
+     * admin block invariant in `M`, and a typed collection stops being usable as
+     * a collection. Method syntax is bivariant under `strictFunctionTypes`; the
+     * sibling callbacks (`EntityAction.onClick`, `AdditionalFieldDelegate.value`)
+     * are all written this way, and `packages/types/__tests__/bivariance` is the
+     * record of finding it out the hard way.
+     */
+    resolve(params: EntityDisplayResolverParams<M, USER>): T | undefined | Promise<T | undefined>;
+}["resolve"];
+
+/**
+ * Where one display role gets its value: a property path on this collection, or
+ * a resolver that computes it.
+ *
+ * The path arm is checked against `M` and read with `getValueInPath`, so
+ * `"profile.displayName"` is as valid as `"title"`. It also keeps the property's
+ * own rendering — an enum status stays a coloured chip, a date stays formatted,
+ * a storage path stays a thumbnail — which a resolver returning a bare string
+ * cannot. Prefer the path whenever the value is on the record.
+ *
+ * `Path` is a type parameter rather than `PropertyPath<M>` directly, so this
+ * module does not import from `admin_collection`, which imports it.
+ */
+export type EntityDisplaySource<
+    Path extends string,
+    M extends Record<string, unknown> = Record<string, unknown>,
+    T = unknown,
+    USER extends User = User
+> = Path | EntityDisplayResolver<M, T, USER>;
+
+/**
+ * The six roles, and what may fill each.
+ *
+ * The value types describe what the renderers accept, not what a resolver must
+ * produce exactly: a `date` resolver may return a `Date`, an ISO string or an
+ * epoch number, and `tags` takes a single string as shorthand for one tag. A
+ * property path is not constrained by them at all — the property's own type
+ * decides how it renders.
+ */
+export type EntityDisplay<
+    Path extends string = string,
+    M extends Record<string, unknown> = Record<string, unknown>,
+    USER extends User = User
+> = {
+    /**
+     * What the record is called: the heading, the breadcrumb, the row, and the
+     * label of every relation chip and reference that points at it.
+     */
+    title?: EntityDisplaySource<Path, M, string, USER>;
+
+    /**
+     * The line under the title — a short description, a location, a summary.
+     */
+    subtitle?: EntityDisplaySource<Path, M, string, USER>;
+
+    /**
+     * The record's picture. A storage path or a URL: the same two things a
+     * `storage` property holds, so a resolver may return either.
+     */
+    image?: EntityDisplaySource<Path, M, string, USER>;
+
+    /**
+     * The state chip — published, archived, paid. Rendered with the enum's own
+     * colour when it comes from an enum property.
+     */
+    status?: EntityDisplaySource<Path, M, string, USER>;
+
+    /**
+     * The timestamp a row is stamped with, usually when it last changed.
+     */
+    date?: EntityDisplaySource<Path, M, Date | string | number, USER>;
+
+    /**
+     * Free chips beside the status: labels, categories, topics. A single string
+     * is accepted as shorthand for one tag.
+     */
+    tags?: EntityDisplaySource<Path, M, string[] | string, USER>;
+};
+
+/**
+ * The roles as data, so every consumer iterates the same list instead of
+ * repeating it — the mistake that let `titleProperty` grow seven readers.
+ */
+export const ENTITY_DISPLAY_ROLES = [
+    "title",
+    "subtitle",
+    "image",
+    "status",
+    "date",
+    "tags"
+] as const;
+
+/** One of the six display roles. */
+export type EntityDisplayRole = typeof ENTITY_DISPLAY_ROLES[number];

package/src/types/entity_link_builder.ts

@@ -0,0 +1,8 @@
+import { Entity } from "@rebasepro/types";
+
+/**
+ * @group Models
+ */
+export type EntityLinkBuilder<M extends Record<string, unknown> = Record<string, unknown>> = ({ entity }: {
+    entity: Entity<M>
+}) => string;

package/src/types/entity_views.tsx

@@ -0,0 +1,135 @@
+import React from "react";
+import type { Entity, EntityValues } from "@rebasepro/types";
+
+import type { FormexController } from "./formex";
+import type { ComponentRef } from "@rebasepro/types";
+import type { AdminCollection } from "@rebasepro/cms-types";
+
+/**
+ * Context passed to custom fields and entity views.
+ * @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
+     */
+    setFieldValue: (key: string, value: unknown, shouldValidate?: boolean) => void;
+
+    /**
+     * Quietly persist the entity to the database without any UI feedback
+     * (no validation, no snackbar, no form reset).
+     * Use this for programmatic/background saves from custom views.
+     */
+    save: (values: M) => void;
+
+    /**
+     * Submit the form — validates, saves, resets the form, and shows
+     * a success snackbar. This is what the Save button calls.
+     * Use this from custom views when you want the full "user saved" experience.
+     */
+    submit: () => void;
+
+    /**
+     * Collection of the entity being modified
+     */
+    collection?: AdminCollection<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" | "dialog";
+
+    /**
+     * The underlying formex controller that powers the form.
+     */
+    formex: FormexController<M>;
+
+    disabled: boolean;
+
+    /**
+     * A save is in flight. Covers the autosave debounce too, which `formex`
+     * cannot report because it never goes through `handleSubmit`.
+     *
+     * The identity bar reads this to label its Save button, which is what
+     * replaced the unlabelled floating status circle in the form.
+     */
+    isSaving?: boolean;
+
+    /**
+     * Whether the form context is in read-only detail view mode.
+     * Custom entity views can use this to adjust their rendering.
+     */
+    readOnly?: boolean;
+}
+
+export type EntityCustomView<M extends Record<string, unknown> = Record<string, unknown>> = {
+    key: string;
+    name: string;
+    icon?: string | React.ReactNode;
+    tabComponent?: React.ReactNode;
+    includeActions?: boolean | "bottom";
+    Builder?: ComponentRef<EntityCustomViewParams<M>>;
+    /**
+     * Which side of the record's own tab this one sits on.
+     *
+     * `"end"` (the default) puts it after the record and before the
+     * subcollections, which is where an extra reading of a row belongs.
+     *
+     * `"start"` puts it *before* the record — the cover of an entity: a
+     * read-only summary an operator opens the row to see, with the form that
+     * edits it one tab to the right. Pair it with
+     * {@link AdminCollectionOptions.defaultSelectedView}, or the strip will open
+     * on a tab that is not the first one.
+     */
+    position?: "start" | "end";
+};
+
+/**
+ * Configuration to replace the default entity form with a custom component.
+ * The Builder receives the same props as entity view tabs (entity, formContext, etc.)
+ * and has full control over the UI.
+ *
+ * The form tab still appears in the tab bar but renders your Builder
+ * instead of the auto-generated field form.
+ *
+ * @group Models
+ */
+export type FormViewConfig<M extends Record<string, unknown> = Record<string, unknown>> = {
+    /**
+     * Custom component that replaces the default form.
+     */
+    Builder: ComponentRef<EntityCustomViewParams<M>>;
+    /**
+     * If true, the save/delete action bar is rendered alongside the custom view.
+     * Defaults to true.
+     */
+    includeActions?: boolean;
+};
+
+export interface EntityCustomViewParams<M extends Record<string, unknown> = Record<string, unknown>> {
+    collection: AdminCollection<M>;
+    entity?: Entity<M>;
+    modifiedValues?: EntityValues<M>;
+    formContext: FormContext<M>;
+    parentCollectionSlugs?: string[];
+    parentEntityIds?: string[];
+}

package/src/types/export_import.ts

@@ -0,0 +1,26 @@
+import type { Entity } from "@rebasepro/types";
+import type { User } from "@rebasepro/types";
+import type { RebaseContext } from "../rebase_context";
+
+/**
+ * You can use this configuration to add additional fields to the data
+ * exports
+ * @group Models
+ */
+export interface ExportConfig<USER extends User = User> {
+    additionalFields: ExportMappingFunction<USER>[];
+}
+
+/**
+ * @group Models
+ */
+export interface ExportMappingFunction<USER extends User = User> {
+    key: string;
+    builder: ({
+        entity,
+        context
+    }: {
+        entity: Entity,
+        context: RebaseContext<USER>
+    }) => Promise<string> | string;
+}

package/src/types/form_layout.ts

@@ -0,0 +1,137 @@
+import type { ColumnKey } from "../admin_collection";
+
+/**
+ * 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 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/src/types/formex.ts

@@ -0,0 +1,45 @@
+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/src/types/index.ts

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

package/src/types/locales.ts

@@ -0,0 +1,81 @@
+/**
+ * @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/src/types/modify_collections.tsx

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