@easy-cms/core 0.24.0 → 0.26.0

package/dist/index.d.ts

@@ -254,6 +254,58 @@ declare function consoleEmail(options?: {
     })[];
 };
 
+interface ConfigIssue {
+    /** Where the problem is, e.g. `collections.posts.fields.slug.from`. */
+    readonly path: string;
+    readonly message: string;
+    /** How to fix it. */
+    readonly hint?: string;
+}
+declare class ConfigError extends Error {
+    readonly issues: readonly ConfigIssue[];
+    constructor(issues: readonly ConfigIssue[]);
+    static format(issues: readonly ConfigIssue[]): string;
+}
+/** Base class for errors that map to an HTTP status in the REST API. */
+declare class EasyCMSError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+interface FieldError {
+    /** Dotted path, e.g. `links.0.url`. */
+    readonly field: string;
+    readonly message: string;
+}
+declare class ValidationError extends EasyCMSError {
+    readonly errors: readonly FieldError[];
+    constructor(collection: string, errors: readonly FieldError[]);
+}
+declare class NotFoundError extends EasyCMSError {
+    constructor(collection: string, id: unknown);
+}
+/** A bad `where`, `sort` or unknown collection/global. */
+declare class QueryError extends EasyCMSError {
+    constructor(message: string);
+}
+/** The database schema does not match the config (pending or missing migrations). */
+declare class SchemaError extends EasyCMSError {
+    constructor(message: string);
+}
+/** Not logged in, or the session is invalid. */
+declare class UnauthorizedError extends EasyCMSError {
+    constructor(message?: string);
+}
+/** Logged in, but not allowed to do this. */
+declare class ForbiddenError extends EasyCMSError {
+    constructor(message?: string);
+}
+declare class TooManyRequestsError extends EasyCMSError {
+    constructor(message: string);
+}
+declare class PayloadTooLargeError extends EasyCMSError {
+    constructor(message: string);
+}
+
 /** What a preview token opens: one document of a collection, or one global. */
 type PreviewTarget = {
     readonly collection: string;
@@ -439,16 +491,41 @@ interface BuiltinApiKeysCollection {
 type ApiKeysOf<C extends Config> = C extends {
     readonly apiKeys: true;
 } ? BuiltinApiKeysCollection : never;
-/** Every collection of a config, including the built-in ones. */
-type AllCollections<C extends Config> = NonNullable<C['collections']>[number] | BuiltinUsersCollection | BuiltinMediaCollection | ApiKeysOf<C>;
+/** The `PluginTypes` of each plugin in the config (a union). */
+type PluginTypesOf<C extends Config> = C extends {
+    readonly plugins: readonly (infer P)[];
+} ? P extends TypedPlugin<infer T extends PluginTypes> ? T : never : never;
+/** Fields that plugins add to the collection (or global) `S`, as a union. */
+type AddedFields<T, S> = T extends {
+    readonly [K in 'fields' | 'globalFields']?: infer M;
+} ? M extends {
+    readonly [slug: string]: readonly Field[];
+} ? string extends keyof M ? never : S extends keyof M ? M[S][number] : never : never : never;
+type PluginFields<C extends Config, S, Key extends 'fields' | 'globalFields'> = AddedFields<PluginTypesOf<C> extends infer T ? T extends PluginTypes ? Pick<T, Key & keyof T> : never : never, S>;
+/** Collections that plugins add. */
+type PluginCollections<C extends Config> = PluginTypesOf<C> extends infer T ? T extends {
+    readonly collections: readonly (infer K extends CollectionConfig)[];
+} ? K : never : never;
+/** A collection or global with the fields plugins add to it. */
+type WithPluginFields<C extends Config, T extends {
+    readonly slug: string;
+    readonly fields: readonly Field[];
+}, Key extends 'fields' | 'globalFields'> = [PluginFields<C, T['slug'], Key>] extends [never] ? T : Omit<T, 'fields'> & {
+    readonly fields: readonly (T['fields'][number] | PluginFields<C, T['slug'], Key>)[];
+};
+/** Every collection of a config, including the built-in ones and those plugins add. */
+type AllCollections<C extends Config> = NonNullable<C['collections']>[number] | BuiltinUsersCollection | BuiltinMediaCollection | ApiKeysOf<C> | PluginCollections<C>;
 /** The built-in media collection; its documents are typed as `MediaDocument`. */
 interface BuiltinMediaCollection {
     readonly slug: 'media';
     readonly fields: readonly [];
 }
-type CollectionBySlug<C extends Config, S> = Extract<AllCollections<C>, {
+type CollectionBySlug<C extends Config, S> = WithPluginFields<C, Extract<AllCollections<C>, {
     readonly slug: S;
-}>;
+}>, 'fields'>;
+type GlobalBySlug<C extends Config, S> = WithPluginFields<C, Extract<NonNullable<C['globals']>[number], {
+    readonly slug: S;
+}>, 'globalFields'>;
 /** Relationships are ids at depth 0 and documents when populated. */
 type RelationValue<C extends Config, S> = [CollectionBySlug<C, S>] extends [never] ? ID | Record<string, unknown> : ID | CollectionDocument<C, S & string>;
 interface MediaSize {
@@ -508,7 +585,13 @@ type FieldValue<F extends Field, C extends Config = Config> = F extends {
 } ? FieldsValue<Sub, C> : F extends {
     readonly type: 'blocks';
     readonly blocks: infer B extends readonly Block[];
-} ? BlockValue<B[number], C>[] : never;
+} ? BlockValue<B[number], C>[] : CustomValue<F>;
+/** The value of a field of an added type (`CustomFieldTypes`). */
+type CustomValue<F> = F extends {
+    readonly type: infer T extends keyof CustomFieldTypes;
+} ? CustomFieldTypes[T] extends {
+    value: infer V;
+} ? V : unknown : never;
 /** One row of a `blocks` field: the block's fields plus `id` and `blockType` (distributes over kinds). */
 type BlockValue<B, C extends Config> = B extends {
     readonly slug: infer S;
@@ -544,7 +627,7 @@ type FieldsValue<Fs extends readonly Field[], C extends Config = Config> = Simpl
     -readonly [F in OptionalFields<Fs> as F['name']]?: FieldValue<F, C> | null;
 }>;
 type SystemFields<T extends {
-    readonly drafts?: boolean;
+    readonly drafts?: unknown;
 }> = {
     id: ID;
     createdAt: string;
@@ -554,8 +637,13 @@ type SystemFields<T extends {
 } ? {
     status: 'draft' | 'published';
 } : unknown);
-type InferCollection<T extends CollectionConfig, C extends Config = Config> = Simplify<SystemFields<T> & FieldsValue<T['fields'], C>>;
-type InferGlobal<T extends GlobalConfig, C extends Config = Config> = Simplify<
+/** What document types are inferred from: a collection's or global's fields and drafts. */
+type FieldsOwner = {
+    readonly fields: readonly Field[];
+    readonly drafts?: unknown;
+};
+type InferCollection<T extends FieldsOwner, C extends Config = Config> = Simplify<SystemFields<T> & FieldsValue<T['fields'], C>>;
+type InferGlobal<T extends FieldsOwner, C extends Config = Config> = Simplify<
 /** `null` until the global is saved for the first time. */
 {
     updatedAt: string | null;
@@ -564,14 +652,12 @@ type InferGlobal<T extends GlobalConfig, C extends Config = Config> = Simplify<
 } ? {
     status: 'draft' | 'published';
 } : unknown) & FieldsValue<T['fields'], C>>;
-type CollectionSlug<C extends Config> = NonNullable<C['collections']>[number]['slug'] | 'users' | 'media' | ApiKeysOf<C>['slug'];
+type CollectionSlug<C extends Config> = NonNullable<C['collections']>[number]['slug'] | 'users' | 'media' | ApiKeysOf<C>['slug'] | PluginCollections<C>['slug'];
 type GlobalSlug<C extends Config> = NonNullable<C['globals']>[number]['slug'];
 /** Document type of a collection, e.g. `CollectionDocument<typeof config, 'posts'>`. */
 type CollectionDocument<C extends Config, S extends CollectionSlug<C>> = S extends 'media' ? MediaDocument : InferCollection<CollectionBySlug<C, S>, C>;
 /** Data type of a global, e.g. `GlobalDocument<typeof config, 'site'>`. */
-type GlobalDocument<C extends Config, S extends GlobalSlug<C>> = InferGlobal<Extract<NonNullable<C['globals']>[number], {
-    readonly slug: S;
-}>, C>;
+type GlobalDocument<C extends Config, S extends GlobalSlug<C>> = InferGlobal<GlobalBySlug<C, S>, C>;
 type InputValue<F extends Field> = F extends {
     readonly type: 'relationship';
 } ? F extends {
@@ -630,11 +716,7 @@ type CreateInput<C extends Config, S extends CollectionSlug<C>> = Simplify<Field
 /** Data accepted by `update`: any subset of `CreateInput`. */
 type UpdateInput<C extends Config, S extends CollectionSlug<C>> = Partial<CreateInput<C, S>>;
 /** Data accepted by `updateGlobal`. */
-type GlobalInput<C extends Config, S extends GlobalSlug<C>> = Partial<Simplify<FieldsInput<Extract<NonNullable<C['globals']>[number], {
-    readonly slug: S;
-}>['fields']> & StatusInput<Extract<NonNullable<C['globals']>[number], {
-    readonly slug: S;
-}>>>>;
+type GlobalInput<C extends Config, S extends GlobalSlug<C>> = Partial<Simplify<FieldsInput<GlobalBySlug<C, S>['fields']> & StatusInput<GlobalBySlug<C, S>>>>;
 
 interface StoredFile {
     readonly body: Uint8Array;
@@ -690,6 +772,13 @@ type Create<C extends Config, S> = string extends CollectionSlug<C> ? Data$2 : C
 type Update<C extends Config, S> = string extends CollectionSlug<C> ? Data$2 : UpdateInput<C, S & CollectionSlug<C>>;
 type GDoc<C extends Config, S> = string extends GlobalSlug<C> ? Data$2 : GlobalDocument<C, S & GlobalSlug<C>>;
 type GInput<C extends Config, S> = string extends GlobalSlug<C> ? Data$2 : GlobalInput<C, S & GlobalSlug<C>>;
+/** A collection slug of the config `C` (any string when the config isn't a literal). */
+type SlugOf<C extends Config> = Slug<C>;
+/**
+ * A document of collection `S` as the Local API returns it, e.g. for helpers that take an
+ * `EasyCMS<C>`: inferred from a literal config, loose otherwise.
+ */
+type DocumentOf<C extends Config, S> = Doc<C, S>;
 interface AccessOptions {
     /**
      * The Local API trusts its caller and skips access rules by default.
@@ -1051,7 +1140,31 @@ interface FieldAdmin {
     readonly component?: AdminComponent;
     /** Shown below the field, e.g. a length meter or a preview. */
     readonly after?: readonly AdminComponent[];
+    /** Shows the value in the admin's lists (e.g. a color swatch). Default: the plain value. */
+    readonly cell?: AdminComponent;
 }
+/**
+ * Field types that packages add (`fieldTypes` in the config), for the types inferred from the
+ * config. A package declares its own by augmenting this interface:
+ *
+ * ```ts
+ * declare module '@easy-cms/core' {
+ *   interface CustomFieldTypes {
+ *     color: { value: string; options: { readonly presets?: readonly string[] } }
+ *   }
+ * }
+ * ```
+ */
+interface CustomFieldTypes {
+}
+/** A field of a type from `CustomFieldTypes`: the common options, plus the type's own. */
+type CustomField = {
+    [K in keyof CustomFieldTypes]: BaseField<K & string, CustomFieldTypes[K] extends {
+        value: infer V;
+    } ? V : unknown> & (CustomFieldTypes[K] extends {
+        options: infer O;
+    } ? O : unknown);
+}[keyof CustomFieldTypes];
 interface BaseField<TType extends string, TValue> {
     readonly type: TType;
     readonly name: string;
@@ -1073,6 +1186,8 @@ interface BaseField<TType extends string, TValue> {
     readonly position?: 'sidebar';
     /** Custom admin components for this field. */
     readonly admin?: FieldAdmin;
+    /** Set by Easy CMS on fields of an added type (`fieldTypes`): the type's name, e.g. `color`. */
+    readonly customType?: string;
 }
 interface TextField extends BaseField<'text', string> {
     readonly minLength?: number;
@@ -1189,10 +1304,48 @@ declare function mimeAllowedBy(mimeType: string, patterns: readonly string[]): b
 declare const hasRows: (field: Field) => field is ArrayField | BlocksField;
 /** The fields of one row of an `array` or `blocks` field (`undefined` for an unknown block). */
 declare function rowFields(field: ArrayField | BlocksField, row: unknown): readonly Field[] | undefined;
-type Field = TextField | TextareaField | NumberField | BooleanField | DateField | EmailField | JsonField | SelectField | SlugField | RichTextField | UploadField | RelationshipField | ArrayField | GroupField | BlocksField;
+type Field = CustomField | TextField | TextareaField | NumberField | BooleanField | DateField | EmailField | JsonField | SelectField | SlugField | RichTextField | UploadField | RelationshipField | ArrayField | GroupField | BlocksField;
 type FieldType = Field['type'];
 declare const FIELD_TYPES: readonly ["text", "textarea", "number", "boolean", "date", "email", "json", "select", "slug", "richText", "upload", "relationship", "array", "group", "blocks"];
 
+/** Built-in types a field type can be stored as. */
+declare const FIELD_TYPE_BASES: readonly ["text", "textarea", "email", "number", "boolean", "date", "json"];
+type FieldTypeBase = (typeof FIELD_TYPE_BASES)[number];
+/** What a field type's `validate` gets besides the value: the field, with its own options. */
+interface FieldTypeValidateContext extends FieldValidateContext {
+    readonly field: Readonly<Record<string, unknown>> & {
+        readonly name: string;
+    };
+}
+/**
+ * A field type a package adds, e.g. `color`: stored, queried and translated like its `base`
+ * type, with its own checks and admin components. List it in the config's `fieldTypes`.
+ */
+interface FieldTypeDefinition {
+    /** The `type` fields use, e.g. `color`. Lowercase; not one of the built-in types. */
+    readonly name: string;
+    /** How values are stored and queried: one of the built-in scalar types. */
+    readonly base: FieldTypeBase;
+    /** Checks a value (not empty ones; `required` covers those). Return `true` or a message. */
+    readonly validate?: (value: unknown, ctx: FieldTypeValidateContext) => true | string | Promise<true | string>;
+    /** Checks a field's own options when the config loads; return a message for a mistake. */
+    readonly checkOptions?: (field: Readonly<Record<string, unknown>>) => string | undefined;
+    readonly admin?: {
+        /** The input: a Web Component from `module`. */
+        readonly component?: string;
+        /** Shown in the admin's lists. */
+        readonly cell?: string;
+        /** The admin module (package export or file) that defines the components. */
+        readonly module?: string;
+        /** The field options its components get (as their `options`), e.g. `['presets']`. */
+        readonly props?: readonly string[];
+    };
+    /** The value's TypeScript type for `generate:types`. Default: the base type's. */
+    readonly typescript?: string;
+}
+/** Declares a field type; returns it unchanged. */
+declare function defineFieldType(definition: FieldTypeDefinition): FieldTypeDefinition;
+
 declare const WEBHOOK_EVENTS: readonly ["create", "update", "delete", "publish", "unpublish", "draft"];
 /**
  * `create`, `update`, `delete`: the stored document changed. `publish` / `unpublish`: its status
@@ -1519,6 +1672,38 @@ interface Endpoint {
 }
 /** Receives the config and returns a modified copy. Runs before validation. */
 type Plugin = (config: Config) => MaybePromise<Config>;
+/** Holds a plugin's `PluginTypes` at the type level only: nothing is stored at runtime. */
+declare const PLUGIN_TYPES: unique symbol;
+/**
+ * What a plugin adds, for the document types inferred from the config: fields on collections
+ * and globals (by slug), and whole collections. Field types are written like config fields,
+ * e.g. `{ fields: { posts: readonly [{ readonly name: 'meta'; readonly type: 'group'; … }] } }`.
+ */
+interface PluginTypes {
+    readonly fields?: {
+        readonly [collection: string]: readonly Field[];
+    };
+    readonly globalFields?: {
+        readonly [global: string]: readonly Field[];
+    };
+    readonly collections?: readonly CollectionConfig[];
+}
+/** A plugin that tells the type system what it adds (see `definePlugin`). */
+type TypedPlugin<T extends PluginTypes> = Plugin & {
+    readonly [PLUGIN_TYPES]?: T;
+};
+/**
+ * Returns the plugin unchanged, with what it adds as types, so `cms.find()` and
+ * `CollectionDocument` know the plugin's fields:
+ *
+ * ```ts
+ * export const colorPlugin = (options: { collections: readonly string[] }) =>
+ *   definePlugin<{ fields: { posts: readonly [{ readonly name: 'color'; readonly type: 'text' }] } }>(
+ *     (config) => ({ ...config, collections: … }),
+ *   )
+ * ```
+ */
+declare function definePlugin<const T extends PluginTypes = Record<never, never>>(plugin: Plugin): TypedPlugin<T>;
 interface Config {
     /** Signs sessions. At least 32 characters; read it from `process.env.EASY_CMS_SECRET`. */
     readonly secret: string;
@@ -1558,6 +1743,11 @@ interface Config {
     readonly endpoints?: readonly Endpoint[];
     /** Extra `easy-cms <name>` CLI commands, e.g. from plugins. */
     readonly commands?: readonly CliCommand[];
+    /**
+     * Field types from packages, e.g. `color` from `@easy-cms/fields`: fields then use
+     * `type: 'color'`. See `defineFieldType`.
+     */
+    readonly fieldTypes?: readonly FieldTypeDefinition[];
     /**
      * API keys for scripts and other apps (`Authorization: Bearer ecms_…`), managed in the admin
      * under Settings. A key acts as its owner, limited to the collections and operations it lists.
@@ -1584,6 +1774,7 @@ interface ResolvedConfig extends Omit<Config, 'cors' | 'localization' | 'routes'
     readonly globals: readonly GlobalConfig[];
     readonly endpoints: readonly Endpoint[];
     readonly commands: readonly CliCommand[];
+    readonly fieldTypes: readonly FieldTypeDefinition[];
 }
 /**
  * Declares the Easy CMS config. Returns it unchanged, keeping literal types
@@ -1657,58 +1848,6 @@ declare function copyDatabase(source: Database, target: Database, options?: {
     onTable?: (progress: CopyProgress) => void;
 }): Promise<CopyResult>;
 
-interface ConfigIssue {
-    /** Where the problem is, e.g. `collections.posts.fields.slug.from`. */
-    readonly path: string;
-    readonly message: string;
-    /** How to fix it. */
-    readonly hint?: string;
-}
-declare class ConfigError extends Error {
-    readonly issues: readonly ConfigIssue[];
-    constructor(issues: readonly ConfigIssue[]);
-    static format(issues: readonly ConfigIssue[]): string;
-}
-/** Base class for errors that map to an HTTP status in the REST API. */
-declare class EasyCMSError extends Error {
-    readonly status: number;
-    constructor(message: string, status: number);
-}
-interface FieldError {
-    /** Dotted path, e.g. `links.0.url`. */
-    readonly field: string;
-    readonly message: string;
-}
-declare class ValidationError extends EasyCMSError {
-    readonly errors: readonly FieldError[];
-    constructor(collection: string, errors: readonly FieldError[]);
-}
-declare class NotFoundError extends EasyCMSError {
-    constructor(collection: string, id: unknown);
-}
-/** A bad `where`, `sort` or unknown collection/global. */
-declare class QueryError extends EasyCMSError {
-    constructor(message: string);
-}
-/** The database schema does not match the config (pending or missing migrations). */
-declare class SchemaError extends EasyCMSError {
-    constructor(message: string);
-}
-/** Not logged in, or the session is invalid. */
-declare class UnauthorizedError extends EasyCMSError {
-    constructor(message?: string);
-}
-/** Logged in, but not allowed to do this. */
-declare class ForbiddenError extends EasyCMSError {
-    constructor(message?: string);
-}
-declare class TooManyRequestsError extends EasyCMSError {
-    constructor(message: string);
-}
-declare class PayloadTooLargeError extends EasyCMSError {
-    constructor(message: string);
-}
-
 type Localization = Required<LocalizationConfig>;
 
 type Data = Record<string, unknown>;
@@ -1871,11 +2010,14 @@ interface AdminField {
     localized?: boolean;
     /** Shown in the edit page's side panel. */
     position?: 'sidebar';
-    /** Components from admin modules: instead of the input, and below the field. */
+    /** Components from admin modules: instead of the input, below the field, and in lists. */
     admin?: {
         component?: AdminComponentRef;
         after?: AdminComponentRef[];
+        cell?: AdminComponentRef;
     };
+    /** A field of an added type (`fieldTypes`), e.g. `color`; `type` is the base it's stored as. */
+    customType?: string;
 }
 interface AdminCollection {
     slug: string;
@@ -1979,4 +2121,4 @@ declare const BUILTIN_COLLECTIONS: readonly ["users", "media"];
 /** Checks a config and returns every problem found. An empty array means it is valid. */
 declare function validateConfig(config: Config): ConfigIssue[];
 
-export { ADMIN_ICONS, API_KEYS, API_KEY_GLOBAL_OPERATIONS, API_KEY_OPERATIONS, type Access, type AccessArgs, type AccessOptions, type AdminBrand, type AdminCollection, type AdminComponent, type AdminComponentRef, type AdminConfig, type AdminField, type AdminGlobal, type AdminIcon, type AdminLocale, type AdminSchema, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ApiKeyContext, type ApiKeyGlobalOperation, type ApiKeyOperation, type ApiKeyPermissions, type ArrayField, Auth, type AuthConfig, type AuthUser, BUILTIN_COLLECTIONS, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type Block, type BlocksField, type BooleanField, type BuiltinApiKeysCollection, type BuiltinMediaCollection, type BuiltinUsersCollection, type BundleHints, CONFIG_FILE_NAMES, CSRF_COOKIE, CSRF_HEADER, type CliCommand, type CollectionAccess, type CollectionAdmin, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionListAdmin, type CollectionSlug, type Config, ConfigError, type ConfigIssue, type ContainerAdmin, type CopyProgress, type CopyResult, type CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_PASSWORD_EMAILS, DEFAULT_TOKEN_EXPIRATION, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DatabaseTransfer, type DateField, type DepthOptions, EXTENSIONS, EasyCMS, EasyCMSError, type EmailAdapter, type EmailField, type EmailMessage, type Endpoint, type EndpointRequest, FIELD_TYPES, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldType, type FieldValidate, type FieldValidateContext, type FieldValue, type FieldsInput, type FieldsValue, type FilterOptions, type FilterOptionsArgs, type FindArgs, type FindOptions, ForbiddenError, type GlobalAccess, type GlobalConfig, type GlobalDocument, type GlobalHooks, type GlobalInput, type GlobalSlug, type GroupField, type ID, INTERNAL_COLLECTIONS, type ImageSize, type InferCollection, type InferGlobal, type JsonField, type Label, type LivePreview, type LoadConfigOptions, type LocalStorageOptions, type LocalizationConfig, type Logger, type LoginArgs, MAX_DEPTH, MEDIA, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, type MediaSize, type MigrationInfo, NotFoundError, type NumberField, type Operation, type PaginatedDocs, type PasswordEmail, type PasswordEmailArgs, type PasswordEmailFn, type PasswordLinkOptions, PayloadTooLargeError, type Plugin, type PreviewTarget, type PreviewURL, QueryError, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoutesConfig, SESSION_COOKIE, type ScheduledJob, SchemaError, type SchemaMode, type SelectField, type SelectOption, type Session, type SlugField, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, UnauthorizedError, type UpdateInput, type UpdateOptions, type UploadConfig, type UploadField, ValidationError, type Version, type VersionSummary, type VersionsConfig, WEBHOOK_EVENTS, type WebhookConfig, type WebhookEvent, type WebhookPayload, type Where, type WhereOperators, anyone, applyDefaults, applyPlugins, configSignature, consoleEmail, consoleLogger, copyDatabase, createEasyCMS, createRestHandler, createRootEndpointHandler, defineConfig, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isHasMany, isLoggedIn, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, mimeAllowedBy, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword };
+export { ADMIN_ICONS, API_KEYS, API_KEY_GLOBAL_OPERATIONS, API_KEY_OPERATIONS, type Access, type AccessArgs, type AccessOptions, type AdminBrand, type AdminCollection, type AdminComponent, type AdminComponentRef, type AdminConfig, type AdminField, type AdminGlobal, type AdminIcon, type AdminLocale, type AdminSchema, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ApiKeyContext, type ApiKeyGlobalOperation, type ApiKeyOperation, type ApiKeyPermissions, type ArrayField, Auth, type AuthConfig, type AuthUser, BUILTIN_COLLECTIONS, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type Block, type BlocksField, type BooleanField, type BuiltinApiKeysCollection, type BuiltinMediaCollection, type BuiltinUsersCollection, type BundleHints, CONFIG_FILE_NAMES, CSRF_COOKIE, CSRF_HEADER, type CliCommand, type CollectionAccess, type CollectionAdmin, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionListAdmin, type CollectionSlug, type Config, ConfigError, type ConfigIssue, type ContainerAdmin, type CopyProgress, type CopyResult, type CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, type CustomField, type CustomFieldTypes, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_PASSWORD_EMAILS, DEFAULT_TOKEN_EXPIRATION, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DatabaseTransfer, type DateField, type DepthOptions, type DocumentOf, EXTENSIONS, EasyCMS, EasyCMSError, type EmailAdapter, type EmailField, type EmailMessage, type Endpoint, type EndpointRequest, FIELD_TYPES, FIELD_TYPE_BASES, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldType, type FieldTypeBase, type FieldTypeDefinition, type FieldTypeValidateContext, type FieldValidate, type FieldValidateContext, type FieldValue, type FieldsInput, type FieldsValue, type FilterOptions, type FilterOptionsArgs, type FindArgs, type FindOptions, ForbiddenError, type GlobalAccess, type GlobalConfig, type GlobalDocument, type GlobalHooks, type GlobalInput, type GlobalSlug, type GroupField, type ID, INTERNAL_COLLECTIONS, type ImageSize, type InferCollection, type InferGlobal, type JsonField, type Label, type LivePreview, type LoadConfigOptions, type LocalStorageOptions, type LocalizationConfig, type Logger, type LoginArgs, MAX_DEPTH, MEDIA, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, type MediaSize, type MigrationInfo, NotFoundError, type NumberField, type Operation, type PaginatedDocs, type PasswordEmail, type PasswordEmailArgs, type PasswordEmailFn, type PasswordLinkOptions, PayloadTooLargeError, type Plugin, type PluginTypes, type PreviewTarget, type PreviewURL, QueryError, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoutesConfig, SESSION_COOKIE, type ScheduledJob, SchemaError, type SchemaMode, type SelectField, type SelectOption, type Session, type SlugField, type SlugOf, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, type TypedPlugin, UnauthorizedError, type UpdateInput, type UpdateOptions, type UploadConfig, type UploadField, ValidationError, type Version, type VersionSummary, type VersionsConfig, WEBHOOK_EVENTS, type WebhookConfig, type WebhookEvent, type WebhookPayload, type Where, type WhereOperators, anyone, applyDefaults, applyPlugins, configSignature, consoleEmail, consoleLogger, copyDatabase, createEasyCMS, createRestHandler, createRootEndpointHandler, defineConfig, defineFieldType, definePlugin, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isHasMany, isLoggedIn, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, mimeAllowedBy, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword };

package/dist/index.js

@@ -1140,6 +1140,9 @@ var ADMIN_ICONS = [
   "camera",
   "key"
 ];
+function definePlugin(plugin) {
+  return plugin;
+}
 function defineConfig(config) {
   return config;
 }
@@ -1666,6 +1669,126 @@ var Mailer = class {
   }
 };
 
+// src/field-types.ts
+var FIELD_TYPE_BASES = [
+  "text",
+  "textarea",
+  "email",
+  "number",
+  "boolean",
+  "date",
+  "json"
+];
+function defineFieldType(definition) {
+  return definition;
+}
+var NAME = /^[a-z][a-zA-Z0-9]*$/;
+function fieldTypeModules(config) {
+  const list = config.fieldTypes;
+  if (!Array.isArray(list)) return [];
+  return list.map((t) => t?.admin?.module).filter((m) => typeof m === "string");
+}
+function applyFieldTypes(config) {
+  const issues = [];
+  const list = config.fieldTypes;
+  if (list === void 0) return { config, issues };
+  if (!Array.isArray(list)) {
+    issues.push({ path: "fieldTypes", message: "must be an array of field types" });
+    return { config, issues };
+  }
+  const types = /* @__PURE__ */ new Map();
+  for (const [i, type] of list.entries()) {
+    const path = `fieldTypes[${i}]`;
+    if (!type || typeof type.name !== "string" || !NAME.test(type.name)) {
+      issues.push({ path: `${path}.name`, message: 'must be a lowercase name like "color"' });
+    } else if (FIELD_TYPES.includes(type.name)) {
+      issues.push({ path: `${path}.name`, message: `"${type.name}" is a built-in field type` });
+    } else if (types.has(type.name)) {
+      issues.push({ path: `${path}.name`, message: `"${type.name}" is listed twice` });
+    } else if (!FIELD_TYPE_BASES.includes(type.base)) {
+      issues.push({
+        path: `${path}.base`,
+        message: `must be one of ${FIELD_TYPE_BASES.join(", ")}`
+      });
+    } else {
+      types.set(type.name, type);
+    }
+  }
+  if (types.size === 0) return { config, issues };
+  const component = (tag, field, props) => {
+    if (!tag) return void 0;
+    const options = Object.fromEntries(
+      (props ?? []).filter((key2) => field[key2] !== void 0).map((key2) => [key2, field[key2]])
+    );
+    return Object.keys(options).length ? { tag, props: options } : tag;
+  };
+  const convert = (fields, path) => fields.map((field, i) => {
+    const here = `${path}[${i}]`;
+    const own = field;
+    const type = types.get(own.type);
+    if (!type) {
+      if ((field.type === "group" || field.type === "array") && Array.isArray(field.fields))
+        return { ...field, fields: convert(field.fields, `${here}.fields`) };
+      if (field.type === "blocks" && Array.isArray(field.blocks))
+        return {
+          ...field,
+          blocks: field.blocks.map((block, b) => ({
+            ...block,
+            fields: convert(block.fields, `${here}.blocks[${b}].fields`)
+          }))
+        };
+      return field;
+    }
+    const problem = type.checkOptions?.(own);
+    if (problem) issues.push({ path: here, message: problem });
+    const ownValidate = own.validate;
+    const check = type.validate;
+    const admin = own.admin ?? {};
+    const input = admin.component ?? component(type.admin?.component, own, type.admin?.props);
+    const cell = admin.cell ?? component(type.admin?.cell, own, type.admin?.props);
+    return {
+      ...own,
+      type: type.base,
+      customType: type.name,
+      ...check || ownValidate ? {
+        validate: async (value, ctx) => {
+          const empty = value === null || value === void 0 || value === "";
+          if (check && !empty) {
+            const result = await check(value, { ...ctx, field: own });
+            if (result !== true) return result;
+          }
+          return ownValidate ? ownValidate(value, ctx) : true;
+        }
+      } : {},
+      ...input || cell ? {
+        admin: {
+          ...admin,
+          ...input ? { component: input } : {},
+          ...cell ? { cell } : {}
+        }
+      } : {}
+    };
+  });
+  return {
+    config: {
+      ...config,
+      ...config.collections ? {
+        collections: config.collections.map((c, i) => ({
+          ...c,
+          fields: convert(c.fields, `collections[${i}].fields`)
+        }))
+      } : {},
+      ...config.globals ? {
+        globals: config.globals.map((g, i) => ({
+          ...g,
+          fields: convert(g.fields, `globals[${i}].fields`)
+        }))
+      } : {}
+    },
+    issues
+  };
+}
+
 // src/load-config.ts
 import { existsSync } from "fs";
 import { resolve } from "path";
@@ -2323,9 +2446,10 @@ function validateField(field, path, siblings, collectionSlugs, add) {
     if (typeof admin !== "object" || admin === null) {
       add(`${path}.admin`, "must be an object", "e.g. admin: { component: 'ecms-color-picker' }");
     } else {
-      const { component, after } = admin;
+      const { component, after, cell } = admin;
       if (component !== void 0) validateComponent(component, `${path}.admin.component`, add);
       if (after !== void 0) validateComponents(after, `${path}.admin.after`, add);
+      if (cell !== void 0) validateComponent(cell, `${path}.admin.cell`, add);
     }
   }
   switch (field.type) {
@@ -2590,6 +2714,15 @@ async function applyPlugins(input) {
     if (typeof plugin !== "function") break;
     config = await plugin(config);
   }
+  const modules = fieldTypeModules(config);
+  if (modules.length > 0)
+    config = {
+      ...config,
+      admin: {
+        ...config.admin,
+        modules: [.../* @__PURE__ */ new Set([...config.admin?.modules ?? [], ...modules])]
+      }
+    };
   return config;
 }
 async function resolveConfig(input) {
@@ -2598,7 +2731,9 @@ async function resolveConfig(input) {
   if (typeof config === "object" && config !== null && Array.isArray(config.collections ?? [])) {
     config = withMedia(withUsers(config));
   }
-  const issues = validateConfig(config);
+  const applied = applyFieldTypes(config);
+  config = applied.config;
+  const issues = [...applied.issues, ...validateConfig(config)];
   if (issues.length > 0) throw new ConfigError(issues);
   const { plugins: _plugins, ...rest } = config;
   const result = {
@@ -2646,7 +2781,8 @@ async function resolveConfig(input) {
     ],
     globals: config.globals ?? [],
     endpoints: config.endpoints ?? [],
-    commands: config.commands ?? []
+    commands: config.commands ?? [],
+    fieldTypes: config.fieldTypes ?? []
   };
   resolved.add(result);
   return result;
@@ -4737,12 +4873,14 @@ async function serializeFields(fields, update, localized) {
     if (!await update.allows(field)) f.readOnly = true;
     if (field.localized && localized) f.localized = true;
     if (field.position === "sidebar") f.position = "sidebar";
-    if (field.admin?.component || field.admin?.after?.length) {
+    if (field.admin?.component || field.admin?.after?.length || field.admin?.cell) {
       f.admin = {
         ...field.admin.component ? { component: componentRef(field.admin.component) } : {},
-        ...field.admin.after?.length ? { after: field.admin.after.map(componentRef) } : {}
+        ...field.admin.after?.length ? { after: field.admin.after.map(componentRef) } : {},
+        ...field.admin.cell ? { cell: componentRef(field.admin.cell) } : {}
       };
     }
+    if (field.customType) f.customType = field.customType;
     switch (field.type) {
       case "text":
       case "textarea":
@@ -5677,9 +5815,14 @@ function names(config) {
   }
   const globals = /* @__PURE__ */ new Map();
   for (const g of config.globals) globals.set(g.slug, claim(pascal(g.slug), "Global"));
-  return { collections, globals };
+  const custom = new Map(
+    (config.fieldTypes ?? []).filter((t) => t.typescript).map((t) => [t.name, t.typescript])
+  );
+  return { collections, globals, custom };
 }
 function fieldType(field, n, indent) {
+  const custom = field.customType ? n.custom.get(field.customType) : void 0;
+  if (custom) return custom;
   switch (field.type) {
     case "text":
     case "textarea":
@@ -5833,6 +5976,7 @@ export {
   EasyCMS,
   EasyCMSError,
   FIELD_TYPES,
+  FIELD_TYPE_BASES,
   ForbiddenError,
   INTERNAL_COLLECTIONS,
   MAX_DEPTH,
@@ -5859,6 +6003,8 @@ export {
   createRestHandler,
   createRootEndpointHandler,
   defineConfig,
+  defineFieldType,
+  definePlugin,
   fillMissing,
   findConfigFile,
   generateSlugs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easy-cms/core",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Embedded, code-first headless CMS for Nuxt and Next.js",
   "license": "MIT",
   "type": "module",