@easy-cms/core 0.25.0 → 0.27.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;
@@ -533,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;
@@ -1082,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;
@@ -1104,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;
@@ -1220,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
@@ -1404,7 +1526,7 @@ interface GlobalConfig {
 }
 type AdminLocale = 'en' | 'th';
 /** Icons a collection or global can show in the admin menu ([Lucide](https://lucide.dev) names). */
-declare const ADMIN_ICONS: readonly ["file-text", "newspaper", "book-open", "notebook", "folder", "tag", "tags", "image", "images", "video", "music", "file", "users", "user", "building", "store", "shopping-bag", "shopping-cart", "package", "box", "calendar", "calendar-days", "map-pin", "globe", "house", "layout-grid", "layers", "star", "heart", "message-square", "mail", "phone", "briefcase", "graduation-cap", "utensils", "car", "settings", "sliders-horizontal", "palette", "megaphone", "bell", "link", "quote", "circle-help", "award", "ticket", "camera", "key"];
+declare const ADMIN_ICONS: readonly ["file-text", "newspaper", "book-open", "notebook", "folder", "tag", "tags", "image", "images", "video", "music", "file", "users", "user", "building", "store", "shopping-bag", "shopping-cart", "package", "box", "calendar", "calendar-days", "map-pin", "globe", "house", "layout-grid", "layers", "star", "heart", "message-square", "mail", "phone", "briefcase", "graduation-cap", "utensils", "car", "settings", "sliders-horizontal", "palette", "megaphone", "bell", "link", "quote", "circle-help", "award", "ticket", "camera", "key", "chart-column", "chart-line"];
 type AdminIcon = (typeof ADMIN_ICONS)[number];
 /** Your or your client's brand in the admin UI. */
 interface AdminBrand {
@@ -1415,6 +1537,34 @@ interface AdminBrand {
     /** Main color as `#rrggbb`; lighter and darker shades are derived from it. */
     readonly color?: string;
 }
+/** Who may see an admin page or dashboard widget. Default: every logged-in user. */
+type AdminViewAccess = (args: {
+    readonly user: AuthUser;
+}) => boolean | Promise<boolean>;
+/** A page of its own in the admin, e.g. a plugin's report, at `<admin>/p/<path>`. */
+interface AdminPage {
+    /** Its address under `<admin>/p/`: lowercase letters, digits and `-`, e.g. `forms-overview`. */
+    readonly path: string;
+    /** The page's body: a Web Component from an admin module. The admin draws the header. */
+    readonly component: AdminComponent;
+    /** Its title in the header and the menu. */
+    readonly label: Label;
+    /** Icon in the admin menu. Default `file-text`. */
+    readonly icon?: AdminIcon;
+    /** Listed under Content (default) or Settings in the menu, or not listed (`false`): reached by links. */
+    readonly group?: 'content' | 'settings' | false;
+    /** Who may open it. Pages a user may not open are left out of their admin. */
+    readonly access?: AdminViewAccess;
+}
+/** A panel on the admin's dashboard, after the built-in ones. */
+interface DashboardWidget {
+    /** A Web Component from an admin module. */
+    readonly component: AdminComponent;
+    /** Half the dashboard's width (default) or all of it. Full width on phones. */
+    readonly width?: 'half' | 'full';
+    /** Who sees it. */
+    readonly access?: AdminViewAccess;
+}
 interface AdminConfig {
     /** Where the admin UI is served. Default `/admin`. */
     readonly path?: string;
@@ -1440,6 +1590,10 @@ interface AdminConfig {
      * module file. Remote URLs are not allowed.
      */
     readonly modules?: readonly string[];
+    /** Pages of their own, e.g. from plugins, at `<admin>/p/<path>`. */
+    readonly pages?: readonly AdminPage[];
+    /** Panels on the dashboard, after the built-in ones. */
+    readonly dashboard?: readonly DashboardWidget[];
 }
 interface ImageSize {
     /** Key in `media.sizes`, e.g. `thumbnail`. */
@@ -1621,6 +1775,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.
@@ -1647,6 +1806,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
@@ -1720,58 +1880,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>;
@@ -1934,11 +2042,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;
@@ -1990,6 +2101,20 @@ interface AdminGlobal {
         update: boolean;
     };
 }
+/** A page of its own in the admin (`admin.pages`) that this user may open. */
+interface AdminPageRef {
+    path: string;
+    label: Label;
+    icon?: string;
+    /** Where it is listed in the menu; `false`: not listed. */
+    group: 'content' | 'settings' | false;
+    component: AdminComponentRef;
+}
+/** A dashboard panel (`admin.dashboard`) this user may see. */
+interface AdminWidgetRef {
+    component: AdminComponentRef;
+    width: 'half' | 'full';
+}
 interface AdminSchema {
     locale: AdminLocale;
     /** Admins can email users links to set their password (needs `email` and `serverURL`). */
@@ -2005,6 +2130,10 @@ interface AdminSchema {
     globals: AdminGlobal[];
     /** URLs under the API of the admin modules to load (`admin.modules`). */
     modules: string[];
+    /** Pages this user may open (`admin.pages`). */
+    pages: AdminPageRef[];
+    /** Dashboard panels this user may see (`admin.dashboard`). */
+    dashboard: AdminWidgetRef[];
 }
 
 declare const SESSION_COOKIE = "ecms-session";
@@ -2042,4 +2171,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, type DocumentOf, 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 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, 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 };
+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 AdminPage, type AdminPageRef, type AdminSchema, type AdminViewAccess, type AdminWidgetRef, 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 DashboardWidget, 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

@@ -1138,7 +1138,9 @@ var ADMIN_ICONS = [
   "award",
   "ticket",
   "camera",
-  "key"
+  "key",
+  "chart-column",
+  "chart-line"
 ];
 function definePlugin(plugin) {
   return plugin;
@@ -1669,6 +1671,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";
@@ -1874,6 +1996,7 @@ function validateConfig(config) {
     add("db", "is required", "pass a database adapter, e.g. db: sqlite({ url: 'file:./cms.db' })");
   }
   validateAdmin(config, add);
+  validateAdminViews(config, add);
   validateUpload(config, add);
   validateAuth(config, add);
   validateCors(config.cors, add);
@@ -1994,6 +2117,83 @@ function validateAdmin(config, add) {
     add("admin.brand.color", `must be a hex color like "#0f766e" (got ${JSON.stringify(color)})`);
   }
 }
+var PAGE_PATH = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+function validateAdminViews(config, add) {
+  const access = (value, path) => {
+    if (value !== void 0 && typeof value !== "function")
+      add(
+        `${path}.access`,
+        "must be a function",
+        'e.g. access: ({ user }) => user.role === "admin"'
+      );
+  };
+  const pages2 = config.admin?.pages;
+  if (pages2 !== void 0) {
+    if (!Array.isArray(pages2)) {
+      add(
+        "admin.pages",
+        "must be an array",
+        "e.g. pages: [{ path: 'stats', label: 'Stats', component: 'ecms-stats' }]"
+      );
+    } else {
+      const seen = /* @__PURE__ */ new Set();
+      pages2.forEach((page, i) => {
+        const path = `admin.pages[${i}]`;
+        if (typeof page !== "object" || page === null) {
+          add(path, "must be an object");
+          return;
+        }
+        const p = page;
+        if (typeof p.path !== "string" || !PAGE_PATH.test(p.path)) {
+          add(
+            `${path}.path`,
+            `must be lowercase letters, digits and "-" (got ${JSON.stringify(p.path)})`,
+            "e.g. path: 'forms-overview'"
+          );
+        } else if (seen.has(p.path)) {
+          add(`${path}.path`, `"${p.path}" is used by another page`);
+        } else {
+          seen.add(p.path);
+        }
+        validateComponent(p.component, `${path}.component`, add);
+        const label = p.label;
+        if (!(typeof label === "string" && label.trim() !== "") && !(typeof label === "object" && label !== null && !Array.isArray(label)))
+          add(
+            `${path}.label`,
+            "must be a string or { en, th }",
+            "e.g. label: { en: 'Stats', th: '\u0E2A\u0E16\u0E34\u0E15\u0E34' }"
+          );
+        validateIcon(p, path, add);
+        if (p.group !== void 0 && p.group !== "content" && p.group !== "settings" && p.group !== false)
+          add(`${path}.group`, 'must be "content", "settings" or false');
+        access(p.access, path);
+      });
+    }
+  }
+  const widgets2 = config.admin?.dashboard;
+  if (widgets2 !== void 0) {
+    if (!Array.isArray(widgets2)) {
+      add(
+        "admin.dashboard",
+        "must be an array",
+        "e.g. dashboard: [{ component: 'ecms-stats-widget' }]"
+      );
+    } else {
+      widgets2.forEach((widget, i) => {
+        const path = `admin.dashboard[${i}]`;
+        if (typeof widget !== "object" || widget === null) {
+          add(path, "must be an object");
+          return;
+        }
+        const w = widget;
+        validateComponent(w.component, `${path}.component`, add);
+        if (w.width !== void 0 && w.width !== "half" && w.width !== "full")
+          add(`${path}.width`, 'must be "half" or "full"');
+        access(w.access, path);
+      });
+    }
+  }
+}
 function validateIcon(container, path, add) {
   const icon = container.icon;
   if (icon === void 0 || ADMIN_ICONS.includes(icon)) return;
@@ -2326,9 +2526,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) {
@@ -2593,6 +2794,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) {
@@ -2601,7 +2811,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 = {
@@ -2619,7 +2831,9 @@ async function resolveConfig(input) {
       brand: config.admin?.brand ?? {},
       siteUrl: config.admin?.siteUrl ?? "",
       menu: config.admin?.menu ?? [],
-      modules: config.admin?.modules ?? []
+      modules: config.admin?.modules ?? [],
+      pages: config.admin?.pages ?? [],
+      dashboard: config.admin?.dashboard ?? []
     },
     upload: {
       dir: config.upload?.dir ?? "uploads",
@@ -2649,7 +2863,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;
@@ -4740,12 +4955,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":
@@ -4866,9 +5083,41 @@ async function adminSchema(cms, user, origin) {
     localization: localization ? { locales: [...localization.locales], defaultLocale: localization.defaultLocale } : null,
     collections: await Promise.all(collections.map((c) => collection(c, user, localized))),
     globals: await Promise.all(cms.config.globals.map((g) => global(g, user, localized))),
-    modules: adminModuleUrls(cms)
+    modules: adminModuleUrls(cms),
+    pages: await pages(cms, user),
+    dashboard: await widgets(cms, user)
   };
 }
+async function shown(access, user) {
+  if (!access) return true;
+  try {
+    return await access({ user }) === true;
+  } catch {
+    return false;
+  }
+}
+async function pages(cms, user) {
+  const out = [];
+  for (const page of cms.config.admin.pages) {
+    if (!await shown(page.access, user)) continue;
+    out.push({
+      path: page.path,
+      label: page.label,
+      ...page.icon ? { icon: page.icon } : {},
+      group: page.group ?? "content",
+      component: componentRef(page.component)
+    });
+  }
+  return out;
+}
+async function widgets(cms, user) {
+  const out = [];
+  for (const widget of cms.config.admin.dashboard) {
+    if (!await shown(widget.access, user)) continue;
+    out.push({ component: componentRef(widget.component), width: widget.width ?? "half" });
+  }
+  return out;
+}
 
 // src/rest/filter-options.ts
 function fieldAt(fields, path) {
@@ -5680,9 +5929,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":
@@ -5836,6 +6090,7 @@ export {
   EasyCMS,
   EasyCMSError,
   FIELD_TYPES,
+  FIELD_TYPE_BASES,
   ForbiddenError,
   INTERNAL_COLLECTIONS,
   MAX_DEPTH,
@@ -5862,6 +6117,7 @@ export {
   createRestHandler,
   createRootEndpointHandler,
   defineConfig,
+  defineFieldType,
   definePlugin,
   fillMissing,
   findConfigFile,

package/package.json

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