@momentumcms/core 0.0.1

package/src/lib/fields/field.types.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Field Types for Momentum CMS
+ * Defines all available field types and their configurations
+ */
+export interface BaseFieldOptions {
+    required?: boolean;
+    unique?: boolean;
+    defaultValue?: unknown;
+    label?: string;
+    description?: string;
+    admin?: FieldAdminConfig;
+    access?: FieldAccessConfig;
+    hooks?: FieldHooksConfig;
+    validate?: ValidateFunction;
+}
+export interface FieldAdminConfig {
+    position?: 'sidebar' | 'main';
+    width?: 'full' | 'half' | 'third';
+    condition?: (data: Record<string, unknown>) => boolean;
+    readOnly?: boolean;
+    hidden?: boolean;
+    placeholder?: string;
+    /** For blocks fields: editor rendering mode. 'visual' enables the WYSIWYG block editor. */
+    editor?: 'visual' | 'form';
+    /** Render this group field as a collapsible accordion section */
+    collapsible?: boolean;
+    /** Whether the collapsible section starts expanded (default: false) */
+    defaultOpen?: boolean;
+}
+export interface FieldAccessConfig {
+    create?: FieldAccessFunction;
+    read?: FieldAccessFunction;
+    update?: FieldAccessFunction;
+}
+export type FieldAccessFunction = (args: {
+    req: unknown;
+    data?: Record<string, unknown>;
+    doc?: Record<string, unknown>;
+}) => boolean | Promise<boolean>;
+export interface FieldHooksConfig {
+    beforeValidate?: FieldHookFunction[];
+    beforeChange?: FieldHookFunction[];
+    afterChange?: FieldHookFunction[];
+    afterRead?: FieldHookFunction[];
+}
+export type FieldHookFunction = (args: {
+    value: unknown;
+    data: Record<string, unknown>;
+    req: unknown;
+    operation: 'create' | 'update' | 'read';
+}) => unknown | Promise<unknown>;
+export type ValidateFunction = (value: unknown, args: {
+    data: Record<string, unknown>;
+    req: unknown;
+}) => string | true | Promise<string | true>;
+/** Display format configuration for number fields. Maps to Intl.NumberFormat options. */
+export interface NumberDisplayFormat {
+    /** Formatting style: 'currency' for prices, 'percent' for percentages, 'decimal' for plain numbers */
+    style?: 'decimal' | 'currency' | 'percent';
+    /** ISO 4217 currency code (e.g. 'USD', 'EUR'). Required when style is 'currency'. */
+    currency?: string;
+    /** BCP 47 locale tag (e.g. 'en-US'). Defaults to browser locale. */
+    locale?: string;
+    /** Minimum number of fraction digits to display */
+    minimumFractionDigits?: number;
+    /** Maximum number of fraction digits to display */
+    maximumFractionDigits?: number;
+}
+/** Preset date/time format styles, mapping to Intl.DateTimeFormat dateStyle/timeStyle */
+export type DateDisplayPreset = 'short' | 'medium' | 'long' | 'full';
+/** Display format configuration for date fields. Maps to Intl.DateTimeFormat options. */
+export interface DateDisplayFormat {
+    /** Preset format style (maps to Intl.DateTimeFormat dateStyle) */
+    preset?: DateDisplayPreset;
+    /** BCP 47 locale tag. Defaults to browser locale. */
+    locale?: string;
+    /** Whether to include time in the display. Defaults to false. */
+    includeTime?: boolean;
+    /** Time style when includeTime is true (maps to Intl.DateTimeFormat timeStyle) */
+    timePreset?: DateDisplayPreset;
+}
+export type FieldType = 'text' | 'textarea' | 'richText' | 'number' | 'date' | 'checkbox' | 'select' | 'radio' | 'email' | 'password' | 'upload' | 'relationship' | 'array' | 'group' | 'blocks' | 'json' | 'point' | 'slug' | 'tabs' | 'collapsible' | 'row';
+/** Layout field types that organize form fields visually but don't store data */
+export declare const LAYOUT_FIELD_TYPES: ReadonlySet<FieldType>;
+export interface BaseField {
+    name: string;
+    type: FieldType;
+    required?: boolean;
+    unique?: boolean;
+    defaultValue?: unknown;
+    label?: string;
+    description?: string;
+    admin?: FieldAdminConfig;
+    access?: FieldAccessConfig;
+    hooks?: FieldHooksConfig;
+    validate?: ValidateFunction;
+}
+export interface TextField extends BaseField {
+    type: 'text';
+    minLength?: number;
+    maxLength?: number;
+}
+export interface TextareaField extends BaseField {
+    type: 'textarea';
+    minLength?: number;
+    maxLength?: number;
+    rows?: number;
+}
+export interface RichTextField extends BaseField {
+    type: 'richText';
+}
+export interface NumberField extends BaseField {
+    type: 'number';
+    min?: number;
+    max?: number;
+    step?: number;
+    /** Display format for read-only views (e.g. currency, percent) */
+    displayFormat?: NumberDisplayFormat;
+}
+export interface DateField extends BaseField {
+    type: 'date';
+    /** Display format for read-only views (e.g. preset style, locale) */
+    displayFormat?: DateDisplayFormat;
+}
+export interface CheckboxField extends BaseField {
+    type: 'checkbox';
+}
+export interface SelectOption {
+    label: string;
+    value: string | number;
+}
+export interface SelectField extends BaseField {
+    type: 'select';
+    options: SelectOption[];
+    hasMany?: boolean;
+}
+export interface RadioField extends BaseField {
+    type: 'radio';
+    options: SelectOption[];
+}
+export interface EmailField extends BaseField {
+    type: 'email';
+}
+export interface PasswordField extends BaseField {
+    type: 'password';
+    minLength?: number;
+}
+export interface UploadField extends BaseField {
+    type: 'upload';
+    /** Collection slug where media documents are stored (default: 'media') */
+    relationTo: string;
+    /** Allowed MIME types (e.g., ['image/*', 'application/pdf']) */
+    mimeTypes?: string[];
+    /** Maximum file size in bytes */
+    maxSize?: number;
+    /** Allow multiple file uploads */
+    hasMany?: boolean;
+}
+/** Behavior when a referenced document is deleted. Maps to SQL FK constraint. */
+export type OnDeleteAction = 'set-null' | 'restrict' | 'cascade';
+/**
+ * Error thrown when a delete or update violates a foreign key constraint.
+ * Lives in core because it represents a domain-level referential integrity violation,
+ * not an HTTP concern. Mapped to HTTP 409 by server-core's handleError.
+ */
+export declare class ReferentialIntegrityError extends Error {
+    readonly constraint: string;
+    readonly table: string;
+    constructor(table: string, constraint: string);
+}
+export interface RelationshipField extends BaseField {
+    type: 'relationship';
+    /** Single target collection (lazy reference to avoid circular imports) */
+    collection: () => unknown;
+    /** Multiple target collections for polymorphic relationships */
+    relationTo?: Array<() => unknown>;
+    hasMany?: boolean;
+    /**
+     * Behavior when the referenced document is deleted.
+     * Maps to SQL FK constraint: 'set-null' → ON DELETE SET NULL, etc.
+     * Only applies to single-value relationships (not hasMany or polymorphic).
+     * @default 'set-null'
+     */
+    onDelete?: OnDeleteAction;
+    /** Filter which related documents can be selected */
+    filterOptions?: (args: {
+        data: Record<string, unknown>;
+    }) => Record<string, unknown>;
+}
+/** Value shape for polymorphic relationships (when relationTo is set) */
+export interface PolymorphicRelationshipValue {
+    relationTo: string;
+    value: string;
+}
+export interface ArrayField extends BaseField {
+    type: 'array';
+    fields: Field[];
+    minRows?: number;
+    maxRows?: number;
+    /** Name of the sub-field to use as summary label in read-only views. Falls back to first text sub-field. */
+    displayField?: string;
+}
+export interface GroupField extends BaseField {
+    type: 'group';
+    fields: Field[];
+}
+/** Editor configuration for a block type in the visual block editor */
+export interface BlockEditorConfig {
+    /** Custom Angular component for visual rendering in the editor */
+    component?: unknown;
+    /** Which fields should be inline-editable (defaults to auto-detect text/textarea/richText) */
+    inlineFields?: string[];
+}
+export interface BlockConfig {
+    slug: string;
+    fields: Field[];
+    labels?: {
+        singular?: string;
+        plural?: string;
+    };
+    /** Visual editor customization for this block type */
+    editor?: BlockEditorConfig;
+}
+export interface BlocksField extends BaseField {
+    type: 'blocks';
+    blocks: BlockConfig[];
+    minRows?: number;
+    maxRows?: number;
+}
+export interface JSONField extends BaseField {
+    type: 'json';
+}
+export interface PointField extends BaseField {
+    type: 'point';
+}
+export interface SlugField extends BaseField {
+    type: 'slug';
+    from: string;
+}
+/** Tab definition within a tabs layout field */
+export interface TabConfig {
+    label: string;
+    description?: string;
+    fields: Field[];
+}
+/** Tabs layout field - organizes fields into tabbed sections */
+export interface TabsField extends BaseField {
+    type: 'tabs';
+    tabs: TabConfig[];
+}
+/** Collapsible layout field - wraps fields in an expandable section */
+export interface CollapsibleField extends BaseField {
+    type: 'collapsible';
+    fields: Field[];
+    /** Whether the section starts expanded (default: false) */
+    defaultOpen?: boolean;
+}
+/** Row layout field - displays child fields in a horizontal row */
+export interface RowField extends BaseField {
+    type: 'row';
+    fields: Field[];
+}
+export type Field = TextField | TextareaField | RichTextField | NumberField | DateField | CheckboxField | SelectField | RadioField | EmailField | PasswordField | UploadField | RelationshipField | ArrayField | GroupField | BlocksField | JSONField | PointField | SlugField | TabsField | CollapsibleField | RowField;
+/** Check if a field type is a layout type (no data storage) */
+export declare function isLayoutField(field: Field): field is TabsField | CollapsibleField | RowField;
+/**
+ * Extracts all data fields from a field list, flattening through layout fields.
+ * Layout fields (tabs, collapsible, row) are containers that don't store data;
+ * their child data fields are stored at the same level as sibling fields.
+ */
+export declare function flattenDataFields(fields: Field[]): Field[];

package/src/lib/fields/humanize-field-name.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Convert a field name to a human-readable title.
+ *
+ * Supports camelCase, PascalCase, snake_case, kebab-case, and combinations.
+ *
+ * Examples:
+ *   firstName -> "First Name"
+ *   first_name -> "First Name"
+ *   SEOTitle -> "SEO Title"
+ *   createdAt -> "Created At"
+ */
+export declare function humanizeFieldName(name: string): string;

package/src/lib/fields/index.d.ts

@@ -0,0 +1,6 @@
+export * from './field.types';
+export { text, textarea, richText, number, date, checkbox, select, radio, email, password, upload, relationship, array, group, blocks, json, point, slug, tabs, collapsible, row, } from './field-builders';
+export type { TextFieldOptions, TextareaFieldOptions, RichTextFieldOptions, NumberFieldOptions, DateFieldOptions, CheckboxFieldOptions, SelectFieldOptions, RadioFieldOptions, EmailFieldOptions, PasswordFieldOptions, UploadFieldOptions, RelationshipFieldOptions, ArrayFieldOptions, GroupFieldOptions, BlocksFieldOptions, JSONFieldOptions, PointFieldOptions, SlugFieldOptions, TabsFieldOptions, CollapsibleFieldOptions, RowFieldOptions, } from './field-builders';
+export { validateFieldConstraints } from './field-validators';
+export type { FieldConstraintError } from './field-validators';
+export { humanizeFieldName } from './humanize-field-name';

package/src/lib/plugins.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Plugin System Type Definitions
+ *
+ * Canonical type definitions for the Momentum CMS plugin system.
+ * These live in @momentumcms/core to avoid circular dependencies.
+ * Runtime implementations (PluginRunner, etc.) live in @momentumcms/plugins/core.
+ */
+import type { CollectionConfig } from './collections';
+import type { MomentumConfig } from './config';
+/**
+ * Descriptor for Express middleware/routes that a plugin wants auto-mounted.
+ * Plugins register these during onInit via context.registerMiddleware().
+ * The framework mounts them automatically in momentumApiMiddleware().
+ */
+export interface PluginMiddlewareDescriptor {
+    /** Mount path relative to the API root (e.g. '/analytics/collect', '/') */
+    path: string;
+    /** Express Router or middleware function. Typed as unknown to avoid Express dependency in core. */
+    handler: unknown;
+    /** Where to mount relative to collection CRUD routes. @default 'before-api' */
+    position?: 'before-api' | 'after-api';
+}
+/**
+ * Descriptor for Angular DI providers that a plugin wants auto-registered during SSR.
+ * Plugins register these during onInit via context.registerProvider().
+ * The framework exposes them via getPluginProviders() for Angular SSR injection.
+ */
+export interface PluginProviderDescriptor {
+    /** Provider name (for debugging/logging) */
+    name: string;
+    /** The InjectionToken. Typed as unknown to avoid Angular dependency in core. */
+    token: unknown;
+    /** The value to provide */
+    value: unknown;
+}
+/**
+ * Descriptor for an admin UI route that a plugin wants to register.
+ * Plugins can declare these statically on the plugin object via `adminRoutes`,
+ * or register them during onInit via context.registerAdminRoute().
+ *
+ * The framework mounts them as lazy-loaded Angular routes inside the admin shell
+ * and renders corresponding sidebar navigation items.
+ *
+ * Mirrors Angular Route concepts (path, loadComponent, data) with
+ * additional Momentum sidebar metadata (label, icon, group).
+ */
+export interface PluginAdminRouteDescriptor {
+    /** Route path under admin (e.g., 'analytics') -- same as Angular Route.path */
+    path: string;
+    /** Lazy-loaded component -- same concept as Angular Route.loadComponent.
+     *  Typed as unknown to avoid Angular dependency in core. */
+    loadComponent: unknown;
+    /** Optional route data -- same concept as Angular Route.data */
+    data?: Record<string, unknown>;
+    /** Sidebar display label */
+    label: string;
+    /** Icon name from ng-icons (e.g., 'heroChartBarSquare') */
+    icon: string;
+    /** Sidebar section name. @default 'Plugins' */
+    group?: string;
+}
+/**
+ * Collection event types that plugins can listen to.
+ */
+export type CollectionEventType = 'beforeChange' | 'afterChange' | 'beforeDelete' | 'afterDelete' | 'beforeRead' | 'afterRead';
+/**
+ * A collection event emitted by the hook system.
+ */
+export interface CollectionEvent {
+    /** The collection slug */
+    collection: string;
+    /** The event type */
+    event: CollectionEventType;
+    /** The operation (create/update/delete/softDelete/restore) */
+    operation?: 'create' | 'update' | 'delete' | 'softDelete' | 'restore';
+    /** The document data (after operation) */
+    doc?: Record<string, unknown>;
+    /** The document data before the operation */
+    previousDoc?: Record<string, unknown>;
+    /** ISO timestamp of the event */
+    timestamp: string;
+}
+/** Logger interface for plugins (avoids importing @momentumcms/logger in core) */
+export interface PluginLogger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Context available to plugins during onInit.
+ * Collections are mutable -- plugins can inject hooks here.
+ */
+export interface PluginContext {
+    /** The full Momentum config */
+    config: MomentumConfig;
+    /** Mutable collections array -- plugins can add hooks */
+    collections: CollectionConfig[];
+    /** Logger scoped to the plugin name */
+    logger: PluginLogger;
+    /** Register Express middleware/routes to be auto-mounted by the framework */
+    registerMiddleware(descriptor: PluginMiddlewareDescriptor): void;
+    /** Register Angular providers for SSR (available to admin UI during server rendering) */
+    registerProvider(descriptor: PluginProviderDescriptor): void;
+}
+/**
+ * Extended context available during onReady.
+ * The API is fully initialized at this point.
+ */
+export interface PluginReadyContext extends PluginContext {
+    /** The initialized Momentum API singleton */
+    api: MomentumAPI;
+}
+/**
+ * Minimal MomentumAPI interface to avoid circular dependencies.
+ * The real MomentumAPI from server-core is structurally compatible.
+ * Plugins that need full typing can import from @momentumcms/server-core.
+ */
+export interface MomentumAPI {
+    /** Get operations for a specific collection */
+    collection(slug: string): unknown;
+    /** Get the current config */
+    getConfig(): MomentumConfig;
+}
+/**
+ * A Momentum CMS plugin.
+ *
+ * Plugins participate in the server lifecycle:
+ * - `onInit`: Before API initialization. Inject hooks into collections here.
+ * - `onReady`: After API + seeding. The API is ready for queries.
+ * - `onShutdown`: Graceful shutdown. Clean up resources.
+ *
+ * Plugins can declare admin routes statically via `adminRoutes`.
+ * These are read at config time by `momentumAdminRoutes(config)` to generate
+ * Angular routes without any manual wiring.
+ *
+ * @example
+ * ```typescript
+ * const myPlugin: MomentumPlugin = {
+ *   name: 'my-plugin',
+ *   adminRoutes: [{
+ *     path: 'my-page',
+ *     label: 'My Page',
+ *     icon: 'heroCog6Tooth',
+ *     loadComponent: () => import('./my-page').then(m => m.MyPage),
+ *   }],
+ *   async onInit({ collections, logger }) {
+ *     logger.info('Initializing...');
+ *   },
+ * };
+ * ```
+ */
+export interface MomentumPlugin {
+    /** Unique plugin name */
+    name: string;
+    /** Static collections declared by this plugin.
+     *  Read at config time by `momentumAdminRoutes(config)` to include
+     *  plugin collections in the admin UI route data.
+     *  Plugins should still push collections in `onInit` for server-side
+     *  schema generation and API registration. */
+    collections?: CollectionConfig[];
+    /** Static admin routes declared by this plugin.
+     *  Read at config time — no async needed. */
+    adminRoutes?: PluginAdminRouteDescriptor[];
+    /** Synchronously transform the merged collections at config time.
+     *  Called by `momentumAdminRoutes()` so the admin UI reflects plugin modifications
+     *  (e.g., injected fields). Also called during server-side `initializeMomentum()`.
+     *  Must be idempotent — may be called more than once. */
+    modifyCollections?(collections: CollectionConfig[]): void;
+    /** Called before API initialization. Inject hooks here. */
+    onInit?(context: PluginContext): void | Promise<void>;
+    /** Called after API + seeding complete. API is ready for queries. */
+    onReady?(context: PluginReadyContext): void | Promise<void>;
+    /** Called on graceful shutdown. Clean up resources. */
+    onShutdown?(context: PluginContext): void | Promise<void>;
+}

package/src/lib/seeding/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Seeding Module
+ *
+ * Declarative data seeding for Momentum CMS.
+ */
+export * from './seeding.types';
+export * from './seed-helpers';

package/src/lib/seeding/seed-helpers.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Seed Helpers
+ *
+ * Factory functions for creating typed seed entity definitions.
+ * Provides IntelliSense support for common entity types.
+ */
+import type { DefaultEntityHelpers } from './seeding.types';
+/**
+ * Creates the default entity helpers with full type safety.
+ * Used internally by the seeding system to provide the `helpers` parameter.
+ *
+ * @returns Default entity helpers object
+ *
+ * @example
+ * ```typescript
+ * const helpers = createSeedHelpers();
+ * const adminSeed = helpers.admin('first-admin', { name: 'Admin', email: 'admin@example.com' });
+ * const userSeed = helpers.user('regular-user', { name: 'John', email: 'john@example.com' });
+ * const postSeed = helpers.collection<PostDoc>('posts').create('welcome', { title: 'Hello' });
+ * ```
+ */
+export declare function createSeedHelpers(): DefaultEntityHelpers;