@rebasepro/cms-types 0.17.0-canary.0

package/src/types/property_options.ts

@@ -0,0 +1,300 @@
+/**
+ * Per-property presentation options.
+ *
+ * These lived in `@rebasepro/types` next to the property types they belong to, which
+ * meant a BaaS install shipped `Field`, `Preview`, `columnWidth` and `hideFromCollection`
+ * in its type surface with nothing to render them. They are attached to the property
+ * types by `augment.ts` instead.
+ */
+import type { ComponentRef, FilterValues, WhereFilterOp } from "@rebasepro/types";
+import { ADMIN_PROPERTY_KEYS as CORE_ADMIN_PROPERTY_KEYS } from "@rebasepro/types";
+import type { PropertySpan } from "./form_layout";
+
+/**
+ * Interface including all common properties of an admin property.
+ * @group Entity properties
+ */
+export interface AdminPropertyOptions<CustomProps = unknown> {
+    columnWidth?: number;
+    hideFromCollection?: boolean;
+    readOnly?: boolean;
+    disabled?: boolean | PropertyDisabledConfig;
+
+    /**
+     * How many of the form grid's {@link FORM_GRID_COLUMNS} columns this field
+     * occupies. Omit to let the layout derive one from the property type.
+     *
+     * Spans snap to a shared grid, so two fields line up whatever order they
+     * are declared in.
+     */
+    span?: PropertySpan;
+    customProps?: CustomProps;
+    Field?: ComponentRef<any>;
+    Preview?: ComponentRef<any>;
+
+    /**
+     * Narrow the filter operators offered for this property in collection
+     * filter UIs (table header filters and the Filters dialog).
+     *
+     * The final offered set is the **intersection** of the engine's
+     * capabilities, the property-type defaults, and this list — you can only
+     * *restrict*, never enable an operator the underlying engine cannot run.
+     *
+     * Pass an empty array to disable filtering on this property entirely.
+     *
+     * @example
+     * // Email column: exact match, contains, and null check only
+     * admin: { filterOperators: ["==", "ilike", "is-null"] }
+     */
+    filterOperators?: readonly WhereFilterOp[];
+
+    /**
+     * Replace the filter field rendered for this property in collection
+     * filter UIs. The component receives `FilterFieldBindingProps`
+     * (property, resolved `operators`, `value`, `setValue`, …).
+     *
+     * Takes precedence over the collection-level
+     * `components["Collection.FilterField"]` override and the built-in
+     * per-type filter fields.
+     */
+    Filter?: ComponentRef<any>;
+}
+
+/**
+ * @group Entity properties
+ */
+export interface AdminStringOptions extends AdminPropertyOptions {
+    /**
+     * Is this string property long enough so it should be displayed in
+     * a multiple line field. Defaults to false. If set to true,
+     * the number of lines adapts to the content
+     */
+    multiline?: boolean;
+    /**
+     * Should this string property be displayed as a markdown field. If true,
+     * the field is rendered as a text editor that supports markdown highlight
+     * syntax. It also includes a preview of the result.
+     */
+    markdown?: boolean;
+    /**
+     * Should this string be rendered as a tag instead of just text.
+     */
+    previewAsTag?: boolean;
+    clearable?: boolean;
+    /**
+     * How to render a string that holds a URL: a link, or one of the supported
+     * media types for an inline preview.
+     *
+     * Only presentation. Whether the string *is* a URL is `url` on the property
+     * itself, which is what the OpenAPI contract is generated from.
+     */
+    urlPreview?: PreviewType;
+}
+
+/**
+ * How a number is written out for reading.
+ *
+ * A thin, explicit subset of `Intl.NumberFormatOptions`. Explicit is the whole
+ * point: nothing here is inferred. A collection that happens to carry a
+ * `currency` column alongside a `total` column has not told us that one formats
+ * the other — that is a relationship only the author knows, and guessing it
+ * would put a euro sign on the one number that was never money.
+ *
+ * Presentation only. It changes what {@link PropertyPreview} renders — the
+ * detail view, the table cell, a reference card — and never what the number
+ * input holds, because a formatted string is not a number you can type into.
+ */
+export interface NumberFormatOptions {
+    /** Defaults to `"decimal"`. `"currency"` requires {@link currency}. */
+    style?: "decimal" | "currency" | "percent";
+    /**
+     * ISO 4217 code — `"EUR"`, `"USD"`. Setting it implies `style: "currency"`,
+     * so the common case is one key.
+     */
+    currency?: string;
+    /**
+     * BCP 47 tag. Defaults to the panel's locale, which is what makes the same
+     * amount read `1,234.50` for one user and `1.234,50` for another.
+     */
+    locale?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    /** `"compact"` renders `12000` as `12K`. Useful in narrow table columns. */
+    notation?: "standard" | "compact";
+}
+
+/**
+ * @group Entity properties
+ */
+export interface AdminNumberOptions extends AdminPropertyOptions {
+    clearable?: boolean;
+    /**
+     * Write this number out as currency, a percentage, or with fixed decimals.
+     * Omit and the raw value renders, which stays the default: a number in the
+     * database is shown as the number in the database.
+     */
+    format?: NumberFormatOptions;
+}
+
+/**
+ * @group Entity properties
+ */
+export interface AdminVectorOptions extends AdminPropertyOptions {
+    clearable?: boolean;
+}
+
+/**
+ * @group Entity properties
+ */
+export interface AdminDateOptions extends AdminPropertyOptions {
+    /**
+     * Add an icon to clear the value and set it to `null`. Defaults to `false`
+     */
+    clearable?: boolean;
+}
+
+/**
+ * @group Entity properties
+ */
+export interface AdminReferenceOptions extends AdminPropertyOptions {
+    previewProperties?: string[];
+
+    /**
+     * Offer only entities that pass this filter in the selection dialog.
+     * e.g. `fixedFilter: { age: [">=", 18] }`
+     */
+    fixedFilter?: FilterValues<string>;
+
+    /** Show the referenced entity's id in previews. Defaults to `true`. */
+    includeId?: boolean;
+
+    /** Show a link that opens the referenced entity. Defaults to `true`. */
+    includeEntityLink?: boolean;
+}
+
+/**
+ * @group Entity properties
+ */
+export interface AdminRelationOptions extends AdminPropertyOptions {
+    previewProperties?: string[];
+
+    /**
+     * Which widget selects the related entity. Defaults to `select`.
+     */
+    widget?: "select" | "dialog";
+
+    /**
+     * Offer only entities that pass this filter in the selection widget.
+     * e.g. `fixedFilter: { age: [">=", 18] }`
+     */
+    fixedFilter?: FilterValues<string>;
+
+    /** Show the related entity's id in previews. Defaults to `true`. */
+    includeId?: boolean;
+
+    /** Show a link that opens the related entity. Defaults to `true`. */
+    includeEntityLink?: boolean;
+
+    /**
+     * Render a **many**-relation as a picker inside the entity form as well as
+     * the tab it already gets. Defaults to `false`.
+     *
+     * The entity view lists a many-relation's rows as a tab, which is the whole
+     * treatment: the child rows are a list, not a value the form holds. This
+     * flag exists for the project that wants the inline picker anyway — it is
+     * off by default because the two surfaces are redundant by construction.
+     *
+     * No effect on a to-one relation: a foreign key gets no tab, so its picker
+     * is always rendered.
+     */
+    renderInForm?: boolean;
+}
+
+/**
+ * @group Entity properties
+ */
+export interface AdminArrayOptions extends AdminPropertyOptions {
+    expanded?: boolean;
+    minimalistView?: boolean;
+
+    /**
+     * Can the elements in this array be reordered by dragging. Defaults to
+     * `true`. No effect when the property is disabled.
+     */
+    sortable?: boolean;
+
+    /**
+     * Can elements be added to this array. Defaults to `true`. No effect when
+     * the property is disabled.
+     */
+    canAddElements?: boolean;
+}
+
+/**
+ * @group Entity properties
+ */
+export interface AdminMapOptions extends AdminPropertyOptions {
+    expanded?: boolean;
+    minimalistView?: boolean;
+    spreadChildren?: boolean;
+
+    /**
+     * Which of the map's own properties are shown when it is rendered as a
+     * preview. Defaults to all of them, in `propertiesOrder`.
+     */
+    previewProperties?: string[];
+}
+
+/**
+ * @group Entity properties
+ */
+export interface PropertyDisabledConfig {
+    /**
+     * Enable this flag if you would like to clear the value of the field
+     * when the corresponding property gets disabled.
+     *
+     * This is useful for keeping data consistency when you have conditional
+     * properties.
+     */
+    clearOnDisabled?: boolean;
+
+    /**
+     * Explanation of why this property is disabled (e.g. a different field
+     * needs to be enabled)
+     */
+    disabledMessage?: string;
+
+    /**
+     * Set this flag to true if you want to hide this field when disabled
+     */
+    hidden?: boolean;
+}
+
+/**
+ * Used for previewing urls if the download file is known
+ * @group Entity properties
+ */
+export type PreviewType = "image" | "video" | "audio" | "file";
+
+/**
+ * Every key any property `admin` block accepts, across the base options and the
+ * per-type extensions.
+ */
+type AnyAdminPropertyOptionKey =
+    | keyof AdminPropertyOptions
+    | keyof AdminStringOptions
+    | keyof AdminNumberOptions
+    | keyof AdminVectorOptions
+    | keyof AdminDateOptions
+    | keyof AdminReferenceOptions
+    | keyof AdminRelationOptions
+    | keyof AdminArrayOptions
+    | keyof AdminMapOptions;
+
+/**
+ * Core's list, re-exported through the same `satisfies` agreement check that
+ * {@link ADMIN_COLLECTION_KEYS} gets: core owns the data because the boot-time
+ * collection validator in `@rebasepro/server` needs it and may not import this
+ * package, and this clause is what stops the data from drifting off the types.
+ */
+export const ADMIN_PROPERTY_KEYS = CORE_ADMIN_PROPERTY_KEYS satisfies readonly AnyAdminPropertyOptionKey[];

package/src/types/slots.tsx

@@ -0,0 +1,334 @@
+import React from "react";
+
+import type { CollectionActionsProps, EntityTableController, SelectionController } from "../collections";
+import type { Entity } from "@rebasepro/types";
+import type { PluginFormActionProps, PluginGenericProps, PluginHomePageActionsProps, PluginHomePageAdditionalCardsProps } from "./plugins";
+import type { Property } from "@rebasepro/types";
+import type { RebaseContext } from "../rebase_context";
+import type { AdminCollection } from "@rebasepro/cms-types";
+
+/**
+ * Registry mapping slot names to their component prop types.
+ * Each key represents a UI extension point in the admin.
+ * @group Plugins
+ */
+export interface SlotRegistry {
+    // ── Home page ─────────────────────────────────────────────────────
+    "home.actions": PluginGenericProps;
+    "home.cards": PluginHomePageAdditionalCardsProps;
+    "home.children.start": PluginGenericProps;
+    "home.children.end": PluginGenericProps;
+    /** Compact widget rendered inline in a home page collection card. */
+    "home.card.widget": HomeCardWidgetSlotProps;
+    "home.collection.actions": PluginHomePageActionsProps;
+
+    // ── Navigation / Drawer ───────────────────────────────────────────
+    /** Rendered below the logo in the sidebar drawer. */
+    "navigation.header": NavigationSlotProps;
+    /** Rendered above the collapse toggle at the bottom of the drawer. */
+    "navigation.footer": NavigationSlotProps;
+
+    // ── Collection view ───────────────────────────────────────────────
+    "collection.actions": CollectionActionsProps;
+    "collection.actions.start": CollectionActionsProps;
+    "collection.header.action": CollectionHeaderActionProps;
+    "collection.add-column": CollectionAddColumnProps;
+    "collection.error": CollectionErrorProps;
+    /** Extra widgets rendered inside the collection toolbar row. */
+    "collection.toolbar": CollectionToolbarProps;
+    /** Custom empty-state component when a collection has no data. */
+    "collection.empty-state": CollectionEmptyStateProps;
+    /** Widgets rendered above the collection table. */
+    "collection.widgets": CollectionWidgetsSlotProps;
+
+    // ── Entity / Form ─────────────────────────────────────────────────
+    "form.actions": PluginFormActionProps;
+    "form.actions.top": PluginFormActionProps;
+    /** Rendered before the form title / field list. */
+    "form.before": PluginFormActionProps;
+    /** Rendered after the form field list. */
+    "form.after": PluginFormActionProps;
+
+    // ── Entity row actions ────────────────────────────────────────────
+    /** Per-row actions in entity tables (e.g. bulk actions, row context menus). */
+    "entity.row.actions": EntityRowActionsProps;
+
+    // ── Entity field decoration ───────────────────────────────────────
+    /** Inject UI before an individual form field. */
+    "entity.field.before": EntityFieldSlotProps;
+    /** Inject UI after an individual form field. */
+    "entity.field.after": EntityFieldSlotProps;
+
+    // ── Collection filter panel ───────────────────────────────────────
+    /** Custom filter sidebar for a collection. */
+    "collection.filter-panel": CollectionFilterPanelProps;
+
+    // ── Dashboard ─────────────────────────────────────────────────────
+    /** Widget rendered on the dashboard / home page. */
+    "dashboard.widget": DashboardWidgetProps;
+
+    // ── Global ────────────────────────────────────────────────────────
+    /** Cross-collection search bar component. */
+    "global.search": GlobalSearchProps;
+    /** Top-level toolbar actions rendered in the shell toolbar area. */
+    "shell.toolbar": ShellToolbarProps;
+
+    // ── Kanban ────────────────────────────────────────────────────────
+    "kanban.setup": KanbanSetupProps;
+    "kanban.add-column": KanbanAddColumnProps;
+}
+
+/**
+ * Valid slot names for UI extension points.
+ * @group Plugins
+ */
+/**
+ * Slots this build declares but renders nowhere.
+ *
+ * Every name here appears in {@link SlotRegistry}, has a props interface, and
+ * is listed in the public slot reference alongside the ones that work — so a
+ * plugin author picks one off the table, registers a component, sees nothing,
+ * and has no way to tell whether the fault is theirs. Seven of twenty-nine were
+ * in that state.
+ *
+ * This is a statement of fact, not a wish list: `slot-render-sites.test.ts`
+ * derives the same set by scanning for render sites and fails when the two
+ * disagree. Implementing a slot therefore forces its removal from here, and
+ * declaring one without rendering it forces its addition — at which point
+ * `Rebase` warns anyone who registers for it, which is the whole point.
+ */
+export const UNRENDERED_SLOTS = [
+    "collection.filter-panel",
+    "dashboard.widget",
+    "entity.field.after",
+    "entity.field.before",
+    "entity.row.actions",
+    "global.search",
+    "shell.toolbar"
+] as const satisfies readonly (keyof SlotRegistry)[];
+
+export type SlotName = keyof SlotRegistry;
+
+/**
+ * A single UI component contribution to a named slot.
+ * @group Plugins
+ */
+export interface SlotContribution<K extends SlotName = SlotName> {
+    /**
+     * Which slot to contribute to.
+     */
+    slot: K;
+
+    /**
+     * The component to render in the slot.
+     * Typed loosely so mixed-slot arrays work.
+     * Type safety is provided at the `useSlot` call site.
+     */
+    Component: React.ComponentType<any>;
+
+    /**
+     * Additional props to merge into the slot props before rendering.
+     */
+    props?: Record<string, unknown>;
+
+    /**
+     * Ordering hint. Lower values render first. Defaults to 50.
+     */
+    order?: number;
+}
+
+// ── Prop interfaces for slots ─────────────────────────────────────────
+
+/**
+ * Props for `navigation.header` and `navigation.footer` slots.
+ * @group Plugins
+ */
+export interface NavigationSlotProps {
+    drawerOpen: boolean;
+    drawerHovered: boolean;
+    context: RebaseContext;
+}
+
+/**
+ * Props for the `collection.toolbar` slot.
+ * @group Plugins
+ */
+export interface CollectionToolbarProps {
+    path: string;
+    collection: AdminCollection;
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
+    tableController: EntityTableController;
+    selectionController: SelectionController;
+}
+
+/**
+ * Props for the `collection.empty-state` slot.
+ * @group Plugins
+ */
+export interface CollectionEmptyStateProps {
+    path: string;
+    collection: AdminCollection;
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
+    canCreate: boolean;
+    onNewClick?: () => void;
+}
+
+/**
+ * Props for the `collection.header.action` slot.
+ * @group Plugins
+ */
+export interface CollectionHeaderActionProps {
+    property: Property;
+    propertyKey: string;
+    path: string;
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
+    onHover: boolean;
+    collection: AdminCollection;
+    tableController: EntityTableController;
+}
+
+/**
+ * Props for the `collection.add-column` slot.
+ * @group Plugins
+ */
+export interface CollectionAddColumnProps {
+    path: string;
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
+    collection: AdminCollection;
+    tableController: EntityTableController;
+}
+
+/**
+ * Props for the `collection.error` slot.
+ * @group Plugins
+ */
+export interface CollectionErrorProps {
+    path: string;
+    collection: AdminCollection;
+    parentCollectionSlugs?: string[];
+    parentEntityIds?: string[];
+    error: Error;
+}
+
+/**
+ * Props for the `kanban.setup` slot.
+ * @group Plugins
+ */
+export interface KanbanSetupProps {
+    collection: AdminCollection;
+    fullPath: string;
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
+}
+
+/**
+ * Props for the `kanban.add-column` slot.
+ * @group Plugins
+ */
+export interface KanbanAddColumnProps {
+    collection: AdminCollection;
+    fullPath: string;
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
+    columnProperty: string;
+}
+
+// ── New slot prop interfaces ──────────────────────────────────────────
+
+/**
+ * Props for `entity.row.actions` slot.
+ * Rendered for each row in a entity collection table.
+ * @group Plugins
+ */
+export interface EntityRowActionsProps {
+    entity: Entity;
+    entityId: string;
+    path: string;
+    collection: AdminCollection;
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
+    selectionController: SelectionController;
+    context: RebaseContext;
+}
+
+/**
+ * Props for `entity.field.before` and `entity.field.after` slots.
+ * Rendered around individual form fields in the entity edit view.
+ * @group Plugins
+ */
+export interface EntityFieldSlotProps {
+    propertyKey: string;
+    property: Property;
+    path: string;
+    entityId?: string | number;
+    collection: AdminCollection;
+    context: RebaseContext;
+}
+
+/**
+ * Props for `collection.filter-panel` slot.
+ * Custom filter sidebar rendered alongside the collection table.
+ * @group Plugins
+ */
+export interface CollectionFilterPanelProps {
+    path: string;
+    collection: AdminCollection;
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
+    tableController: EntityTableController;
+    context: RebaseContext;
+}
+
+/**
+ * Props for `dashboard.widget` slot.
+ * Widgets rendered on the home / dashboard page.
+ * @group Plugins
+ */
+export interface DashboardWidgetProps {
+    context: RebaseContext;
+}
+
+/**
+ * Props for `global.search` slot.
+ * Cross-collection search bar rendered in the app shell.
+ * @group Plugins
+ */
+export interface GlobalSearchProps {
+    context: RebaseContext;
+}
+
+/**
+ * Props for `shell.toolbar` slot.
+ * Actions rendered in the top-level toolbar / app bar area.
+ * @group Plugins
+ */
+export interface ShellToolbarProps {
+    context: RebaseContext;
+}
+
+/**
+ * Props for `collection.widgets` slot.
+ * Widgets rendered above the collection table.
+ * @group Plugins
+ */
+export interface CollectionWidgetsSlotProps {
+    path: string;
+    collection: AdminCollection;
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
+}
+
+/**
+ * Props for `home.card.widget` slot.
+ * Compact widget rendered inline in a home page collection card.
+ * @group Plugins
+ */
+export interface HomeCardWidgetSlotProps {
+    slug: string;
+    collection: AdminCollection;
+    context: RebaseContext;
+}