@easy-cms/core 0.26.0 → 0.27.0

package/dist/index.d.ts

@@ -1526,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 {
@@ -1537,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;
@@ -1562,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`. */
@@ -2069,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`). */
@@ -2084,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";
@@ -2121,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, 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 };
+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;
@@ -1994,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);
@@ -2114,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;
@@ -2751,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",
@@ -5001,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) {

package/package.json

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