millas 0.2.12-beta-1 → 0.2.13-beta

package/src/admin/FormGenerator.js

@@ -0,0 +1,372 @@
+'use strict';
+
+const { widgetRegistry } = require('./WidgetRegistry');
+
+/**
+ * FormGenerator
+ *
+ * Derives a complete, validated form schema from:
+ *   1. Model field metadata (via Model.getFields())
+ *   2. AdminResource configuration (fields(), readonlyFields, fieldsets, widgets)
+ *   3. WidgetRegistry (type → widget mapping)
+ *
+ * The output is a FormSchema — a plain serialisable object that templates
+ * consume directly. No HTML is generated here.
+ *
+ * ── Usage ─────────────────────────────────────────────────────────────────────
+ *
+ *   // In Admin.js — replacing the existing _formFields() call
+ *   const schema = FormGenerator.fromResource(R, { record, isEdit });
+ *   res.render('pages/form.njk', { ...ctx, formFields: schema.fields });
+ *
+ * ── What FormGenerator adds over the current _formFields() ───────────────────
+ *
+ *   ✅  Widget type resolution via WidgetRegistry (customisable per field)
+ *   ✅  Per-resource widget overrides (static widgets = { body: { type:'richtext' } })
+ *   ✅  Validation rule derivation from field definitions
+ *   ✅  Step/min/max attributes derived from field definitions (e.g. decimal scale)
+ *   ✅  Coerce function available for each field (used by _sanitise)
+ *   ✅  FormValidator.validate() — validates a full data object before ORM write
+ *   ✅  Consistent field ordering: fieldsets respected, id always excluded
+ *
+ * ── FormSchema shape ──────────────────────────────────────────────────────────
+ *
+ *   {
+ *     fields: [
+ *       {
+ *         name:        string,
+ *         label:       string,
+ *         type:        string,      // widget type (text|number|select|checkbox|…)
+ *         ormType:     string,      // original ORM field type
+ *         required:    boolean,
+ *         nullable:    boolean,
+ *         readonly:    boolean,
+ *         hidden:      boolean,
+ *         tab:         string|null,
+ *         fieldset:    string|null,
+ *         span:        string|null, // 'full'|'third'|null
+ *         options:     array|null,  // for select/radio
+ *         placeholder: string|null,
+ *         help:        string|null,
+ *         min:         number|null,
+ *         max:         number|null,
+ *         step:        number|null,
+ *         prepopulate: string|null,
+ *         isReadonly:  boolean,
+ *         _isFieldset: boolean,     // sentinel: fieldset heading row
+ *       },
+ *       ...
+ *     ],
+ *     tabs:    string[],            // unique tab names in order
+ *     hasTab:  boolean,
+ *   }
+ */
+class FormGenerator {
+
+  /**
+   * Derive a FormSchema from an AdminResource class.
+   *
+   * @param {class}  Resource    — AdminResource subclass
+   * @param {object} [opts]
+   * @param {object} [opts.record={}]  — existing record data (for edit forms)
+   * @param {boolean}[opts.isEdit=false]
+   * @returns {FormSchema}
+   */
+  static fromResource(Resource, { record = {}, isEdit = false } = {}) {
+    const readonlySet  = new Set(Resource.readonlyFields || []);
+    const prepopFields = Resource.prepopulatedFields || {};
+    // Per-resource widget overrides: static widgets = { fieldName: { type: 'richtext' } }
+    const widgetOverrides = Resource.widgets || {};
+
+    // Get the merged model field map for widget/validation metadata
+    const modelFieldMap = Resource.model
+      ? (typeof Resource.model.getFields === 'function'
+          ? Resource.model.getFields()
+          : (Resource.model.fields || {}))
+      : {};
+
+    let currentTab     = null;
+    let currentFieldset = null;
+    const fields       = [];
+    const tabNames     = [];
+
+    for (const f of Resource.fields()) {
+
+      // ── Tab separator ─────────────────────────────────────────────────────
+      if (f._type === 'tab') {
+        currentTab      = f._label;
+        currentFieldset = null;
+        if (!tabNames.includes(currentTab)) tabNames.push(currentTab);
+        continue;
+      }
+
+      // ── Fieldset heading ──────────────────────────────────────────────────
+      if (f._type === 'fieldset') {
+        currentFieldset = f._label;
+        fields.push({ _isFieldset: true, label: f._label, tab: currentTab });
+        continue;
+      }
+
+      // ── Skip id and list-only fields from forms ───────────────────────────
+      if (f._type === 'id' || f._listOnly || f._hidden) continue;
+
+      const name    = f._name;
+
+      // ── FK / M2M fields — use AdminField metadata directly ───────────────
+      // AdminField.fromModelField() already resolved the correct widget type
+      // ('fk' or 'm2m') and the fkResource slug from the model's references.
+      // FormGenerator must respect that instead of re-deriving from ormType,
+      // because modelFieldMap uses the accessor name ('landlord') while the
+      // AdminField uses the column name ('landlord_id') — they can't be matched
+      // by name, and even if they could, ormType='integer' would give widget='number'.
+      if (f._type === 'fk') {
+        const isReadonly = readonlySet.has(name) || f._readonly || false;
+        fields.push({
+          name,
+          label:       f._label,
+          type:        'fk',
+          ormType:     'integer',
+          fkResource:  f._fkResource || null,
+          required:    !f._nullable,
+          nullable:    !!f._nullable,
+          readonly:    isReadonly,
+          isReadonly,
+          hidden:      false,
+          tab:         currentTab,
+          fieldset:    currentFieldset,
+          span:        f._span || null,
+          options:     null,
+          placeholder: f._placeholder || null,
+          help:        f._help        || null,
+          min:         null,
+          max:         null,
+          step:        null,
+          colors:      {},
+          isLink:      false,
+          prepopulate: null,
+          _coerce:     widgetRegistry.resolve('fk').coerce,
+          _validate:   widgetRegistry.resolve('fk').validate,
+        });
+        continue;
+      }
+
+      if (f._type === 'm2m') {
+        const isReadonly = readonlySet.has(name) || f._readonly || false;
+        fields.push({
+          name,
+          label:       f._label,
+          type:        'm2m',
+          ormType:     'm2m',
+          fkResource:  f._m2mResource || null,
+          required:    false,
+          nullable:    true,
+          readonly:    isReadonly,
+          isReadonly,
+          hidden:      false,
+          tab:         currentTab,
+          fieldset:    currentFieldset,
+          span:        'full',
+          options:     null,
+          placeholder: null,
+          help:        f._help || null,
+          min:         null,
+          max:         null,
+          step:        null,
+          colors:      {},
+          isLink:      false,
+          prepopulate: null,
+          _coerce:     widgetRegistry.resolve('m2m').coerce,
+          _validate:   widgetRegistry.resolve('m2m').validate,
+        });
+        continue;
+      }
+
+      // ── All other field types ─────────────────────────────────────────────
+      // AdminField carries its own _type (e.g. 'boolean', 'date', 'json',
+      // 'email', 'password', 'url', 'phone', 'color', 'richtext', 'select').
+      // For these, the AdminField._type IS the widget key — trust it directly
+      // rather than re-deriving from modelFieldMap which may not find the field
+      // (e.g. custom AdminField.boolean('active') with a name that doesn't
+      // match the model's field map exactly).
+      //
+      // AdminField types that need direct resolution (no ORM equivalent):
+      // Map AdminField._type → WidgetRegistry key.
+      // AdminField types that don't match ORM type names get aliased here.
+      // ── Type resolution ──────────────────────────────────────────────────────
+      // Two separate concerns:
+      //   ormType      → WidgetRegistry key (coerce/validate functions)
+      //   templateType → what field.type the template sees
+      //
+      // Admin-display types (color, richtext, phone, badge, image) have no ORM
+      // equivalent. They map to a string/text registry entry for coerce/validate
+      // but the template must receive the original AdminField type to render
+      // the correct widget (color picker, WYSIWYG, tel input, etc.).
+
+      // Maps AdminField._type → WidgetRegistry key
+      const REGISTRY_TYPE = {
+        boolean:  'boolean',
+        date:     'date',
+        datetime: 'timestamp',
+        timestamp:'timestamp',
+        json:     'json',
+        email:    'email',
+        url:      'url',
+        password: 'password',
+        phone:    'string',    // template renders <input type="tel">
+        color:    'string',    // template renders color picker
+        richtext: 'text',      // template renders WYSIWYG
+        badge:    'string',    // display-only, always readonly on forms
+        image:    'string',    // display-only URL, always readonly on forms
+        select:   'enum',
+        number:   'integer',
+        textarea: 'text',
+        uuid:     'uuid',
+      };
+
+      // These AdminField types must reach the template with their original type
+      // string intact — the template switches on it to render the right widget.
+      // 'boolean' is intentionally excluded — the template checks 'checkbox'
+      // (widget.type from WidgetRegistry), not 'boolean' (AdminField._type).
+      const PRESERVE_TYPE = new Set([
+        'color', 'richtext', 'phone', 'badge', 'image',
+        'date', 'datetime', 'email', 'url', 'password',
+        'json', 'number', 'textarea', 'select',
+      ]);
+
+      const ormType  = REGISTRY_TYPE[f._type] || modelFieldMap[name]?.type || 'string';
+      const fieldDef = modelFieldMap[name] || {};
+
+      // Resolve widget for coerce/validate — per-field override wins
+      const override = widgetOverrides[name];
+      const widget   = override
+        ? { ...widgetRegistry.resolve(ormType, fieldDef), ...override }
+        : widgetRegistry.resolve(ormType, fieldDef);
+
+      // badge and image have no meaningful form input — always readonly
+      const isBadgeOrImage = f._type === 'badge' || f._type === 'image';
+      const isReadonly = isBadgeOrImage || readonlySet.has(name) || f._readonly || false;
+
+      // Template sees the original AdminField type for display types,
+      // otherwise the widget type resolved from the registry.
+      const templateType = PRESERVE_TYPE.has(f._type) ? f._type : widget.type;
+
+      // Derive step from decimal scale (e.g. scale=2 → step=0.01)
+      let step = null;
+      if (ormType === 'decimal' || ormType === 'float') {
+        const scale = fieldDef.scale ?? 2;
+        step = parseFloat((Math.pow(10, -scale)).toFixed(scale));
+      } else if (ormType === 'integer' || ormType === 'bigInteger') {
+        step = 1;
+      }
+
+      // Options for select/enum
+      let options = f._options || null;
+      if (!options && ormType === 'enum' && fieldDef.enumValues) {
+        options = fieldDef.enumValues.map(v => ({ value: v, label: v }));
+      }
+
+      fields.push({
+        name,
+        label:       f._label,
+        type:        templateType,
+        ormType,
+
+        required:    !isBadgeOrImage && !f._nullable && !fieldDef.nullable,
+        nullable:    isBadgeOrImage  || !!(f._nullable || fieldDef.nullable),
+        readonly:    isReadonly,
+        isReadonly,
+        hidden:      false,
+
+        tab:         currentTab,
+        fieldset:    currentFieldset,
+        span:        f._span || null,
+
+        options,
+        placeholder: f._placeholder || null,
+        help:        f._help        || null,
+        min:         f._min         ?? null,
+        max:         f._max         ?? (ormType === 'string' ? (fieldDef.max || null) : null),
+        step,
+        colors:      f._colors      || {},
+        isLink:      f._isLink      || false,
+        prepopulate: prepopFields[name] || f._prepopulate || null,
+
+        _coerce:     widget.coerce  || null,
+        _validate:   widget.validate || null,
+      });
+    }
+
+    return {
+      fields,
+      tabs:   tabNames,
+      hasTab: tabNames.length > 0,
+    };
+  }
+
+  /**
+   * Validate a fully coerced data object against the resource's field rules.
+   *
+   * Called by AdminResource.create() and AdminResource.update() before
+   * the ORM write — after _sanitise() has already coerced the types.
+   *
+   * Returns null if all valid.
+   * Returns { fieldName: 'error message', … } if any field fails.
+   *
+   * @param {class}  Resource — AdminResource subclass
+   * @param {object} data     — coerced data object
+   * @param {object} [opts]
+   * @param {boolean}[opts.isNew=true]
+   * @returns {object|null}
+   */
+  static validate(Resource, data, { isNew = true } = {}) {
+    const modelFieldMap = Resource.model
+      ? (typeof Resource.model.getFields === 'function'
+          ? Resource.model.getFields()
+          : (Resource.model.fields || {}))
+      : {};
+
+    const widgetOverrides = Resource.widgets || {};
+    const errors = {};
+
+    for (const f of Resource.fields()) {
+      if (f._type === 'tab' || f._type === 'fieldset') continue;
+      if (f._type === 'id' || f._listOnly || f._hidden) continue;
+
+      const name     = f._name;
+      const ormType  = modelFieldMap[name]?.type || 'string';
+      const fieldDef = modelFieldMap[name] || {};
+      const override = widgetOverrides[name];
+      const widget   = override
+        ? { ...widgetRegistry.resolve(ormType, fieldDef), ...override }
+        : widgetRegistry.resolve(ormType, fieldDef);
+
+      const value = data[name];
+
+      // Skip password validation on edit if left blank (means "keep current")
+      if (ormType === 'password' && !isNew && (value === undefined || value === null || value === '')) {
+        continue;
+      }
+
+      if (typeof widget.validate === 'function') {
+        const err = widget.validate(value, { ...fieldDef, nullable: f._nullable || fieldDef.nullable });
+        if (err) errors[name] = err;
+      }
+    }
+
+    // Run custom validation hook on the resource if defined
+    // static validate(data, errors, isNew) — can add to errors or throw
+    if (typeof Resource.validate === 'function') {
+      try {
+        Resource.validate(data, errors, isNew);
+      } catch (err) {
+        // If validate() throws an HttpError with errors attached, use those
+        if (err.errors) Object.assign(errors, err.errors);
+        else errors._form = err.message;
+      }
+    }
+
+    return Object.keys(errors).length > 0 ? errors : null;
+  }
+}
+
+module.exports = { FormGenerator };

package/src/admin/HookRegistry.js

@@ -0,0 +1,256 @@
+'use strict';
+
+/**
+ * HookRegistry + HookPipeline
+ *
+ * The Millas admin hook system — inspired by Django's signals and WordPress hooks.
+ *
+ * ── Supported events ──────────────────────────────────────────────────────────
+ *
+ *   before_save    fired before create or update reaches the ORM
+ *                  ctx: { data, user, isNew, resource }
+ *                  return value replaces data → allows mutation
+ *
+ *   after_save     fired after a successful create or update
+ *                  ctx: { record, user, isNew, resource }
+ *
+ *   before_delete  fired before destroy() reaches the ORM
+ *                  ctx: { record, user, resource }
+ *                  throw to abort the delete
+ *
+ *   after_delete   fired after a successful delete
+ *                  ctx: { id, user, resource }
+ *
+ *   before_render  fired before a template is rendered
+ *                  ctx: { view, templateCtx, user, resource }
+ *                  return value replaces templateCtx → allows injection
+ *
+ *   after_render   fired after a response is sent (fire-and-forget)
+ *                  ctx: { view, user, resource, ms }
+ *
+ *   before_action  fired before a bulk action handler runs
+ *                  ctx: { ids, action, user, resource }
+ *
+ *   after_action   fired after a bulk action completes
+ *                  ctx: { ids, action, result, user, resource }
+ *
+ * ── Hook resolution order ────────────────────────────────────────────────────
+ *
+ *   1. Global hooks (registered via AdminHooks.on())  — run first
+ *   2. Resource-level hooks (static methods on AdminConfig subclass)
+ *      e.g.  static async before_save(data, ctx) { ... }
+ *
+ * ── Usage ─────────────────────────────────────────────────────────────────────
+ *
+ *   const { AdminHooks } = require('./HookRegistry');
+ *
+ *   // Global — runs for every resource
+ *   AdminHooks.on('after_save', async (ctx) => {
+ *     await Cache.invalidate(ctx.resource.slug);
+ *   });
+ *
+ *   // Global — abort a delete with a business rule
+ *   AdminHooks.on('before_delete', async (ctx) => {
+ *     if (ctx.record.status === 'published') {
+ *       throw new Error('Cannot delete a published record.');
+ *     }
+ *   });
+ *
+ *   // Per-resource — defined as static methods on AdminConfig subclass
+ *   class PostAdmin extends AdminConfig {
+ *     static async before_save(data, ctx) {
+ *       if (ctx.isNew) data.created_by = ctx.user?.id;
+ *       return data;   // MUST return data (possibly mutated)
+ *     }
+ *     static async after_save(record, ctx) {
+ *       if (ctx.isNew) await Mailer.send('welcome', record);
+ *     }
+ *     static async before_delete(record, ctx) {
+ *       if (record.is_protected) throw new Error('This record is protected.');
+ *     }
+ *   }
+ */
+
+const VALID_EVENTS = new Set([
+  'before_save',
+  'after_save',
+  'before_delete',
+  'after_delete',
+  'before_render',
+  'after_render',
+  'before_action',
+  'after_action',
+]);
+
+class HookRegistry {
+  constructor() {
+    /** @type {Map<string, Function[]>} */
+    this._hooks = new Map();
+    for (const event of VALID_EVENTS) {
+      this._hooks.set(event, []);
+    }
+  }
+
+  /**
+   * Register a global hook.
+   *
+   * @param {string}   event   — one of the VALID_EVENTS
+   * @param {Function} handler — async (ctx) => void | data
+   * @param {object}   [opts]
+   * @param {number}   [opts.priority=10] — lower runs first (like WordPress)
+   */
+  on(event, handler, { priority = 10 } = {}) {
+    if (!VALID_EVENTS.has(event)) {
+      throw new Error(
+        `[AdminHooks] Unknown event "${event}". ` +
+        `Valid events: ${[...VALID_EVENTS].join(', ')}`
+      );
+    }
+    if (typeof handler !== 'function') {
+      throw new Error(`[AdminHooks] Hook handler for "${event}" must be a function.`);
+    }
+
+    handler._priority = priority;
+    this._hooks.get(event).push(handler);
+    // Keep sorted by priority after each insertion
+    this._hooks.get(event).sort((a, b) => (a._priority || 10) - (b._priority || 10));
+    return this; // chainable
+  }
+
+  /**
+   * Remove a previously registered global hook.
+   * Pass the exact same function reference used in .on().
+   */
+  off(event, handler) {
+    if (!this._hooks.has(event)) return this;
+    const list = this._hooks.get(event).filter(h => h !== handler);
+    this._hooks.set(event, list);
+    return this;
+  }
+
+  /**
+   * Remove all global hooks for an event (or all events if none specified).
+   * Useful in tests to reset state between test cases.
+   */
+  clear(event = null) {
+    if (event) {
+      if (this._hooks.has(event)) this._hooks.set(event, []);
+    } else {
+      for (const e of VALID_EVENTS) this._hooks.set(e, []);
+    }
+    return this;
+  }
+
+  /**
+   * Return the list of global hooks for an event.
+   * @param {string} event
+   * @returns {Function[]}
+   */
+  getHandlers(event) {
+    return this._hooks.get(event) || [];
+  }
+}
+
+// ── HookPipeline ──────────────────────────────────────────────────────────────
+
+class HookPipeline {
+  /**
+   * Run the full hook pipeline for an event.
+   *
+   * Pipeline order:
+   *   1. Global hooks (from HookRegistry)
+   *   2. Resource-level static method on AdminConfig (if defined)
+   *
+   * For before_save:
+   *   - ctx.data is passed to each hook
+   *   - If a hook returns a non-undefined value, that becomes the new ctx.data
+   *   - Final ctx.data is what reaches the ORM
+   *
+   * For before_delete / before_render / before_action:
+   *   - Hooks may throw to abort the operation
+   *   - Return value is used if present (for before_render: replaces templateCtx)
+   *
+   * For after_* events:
+   *   - Fire-and-forget for after_render (errors are swallowed, never crash the request)
+   *   - Errors in other after_* hooks are logged but don't affect the response
+   *
+   * @param {string}   event    — hook event name
+   * @param {object}   ctx      — context passed to all handlers
+   * @param {class}    Resource — AdminConfig subclass (may have static hook methods)
+   * @param {HookRegistry} registry — the global hook registry
+   * @returns {Promise<object>} — possibly mutated ctx
+   */
+  static async run(event, ctx, Resource, registry) {
+    // ── 1. Global hooks ────────────────────────────────────────────────────
+    const globalHandlers = registry.getHandlers(event);
+
+    for (const handler of globalHandlers) {
+      try {
+        const result = await handler(ctx);
+        // For before_save: allow handler to return mutated data
+        if (result !== undefined && event === 'before_save') {
+          ctx.data = result;
+        }
+        // For before_render: allow handler to mutate templateCtx
+        if (result !== undefined && event === 'before_render') {
+          ctx.templateCtx = result;
+        }
+      } catch (err) {
+        if (event.startsWith('after_')) {
+          // after_* errors must never crash the response — log and continue
+          process.stderr.write(`[AdminHooks] Error in global "${event}" hook: ${err.message}\n`);
+        } else {
+          throw err; // before_* errors abort the operation
+        }
+      }
+    }
+
+    // ── 2. Resource-level hook method ──────────────────────────────────────
+    // e.g. static async before_save(data, ctx) on the AdminConfig subclass
+    if (Resource && typeof Resource[event] === 'function') {
+      try {
+        // Convention: first arg is the "primary subject", second is the full ctx
+        // before_save(data, ctx)         → returns mutated data
+        // after_save(record, ctx)        → no return needed
+        // before_delete(record, ctx)     → throw to abort
+        // after_delete(id, ctx)          → no return needed
+        // before_render(templateCtx,ctx) → returns mutated templateCtx
+        // before_action(ids, ctx)        → throw to abort
+        let primaryArg;
+        switch (event) {
+          case 'before_save':    primaryArg = ctx.data;        break;
+          case 'after_save':     primaryArg = ctx.record;      break;
+          case 'before_delete':  primaryArg = ctx.record;      break;
+          case 'after_delete':   primaryArg = ctx.id;          break;
+          case 'before_render':  primaryArg = ctx.templateCtx; break;
+          case 'after_render':   primaryArg = ctx.view;        break;
+          case 'before_action':  primaryArg = ctx.ids;         break;
+          case 'after_action':   primaryArg = ctx.ids;         break;
+          default:               primaryArg = ctx;
+        }
+
+        const result = await Resource[event](primaryArg, ctx);
+
+        if (result !== undefined && event === 'before_save') {
+          ctx.data = result;
+        }
+        if (result !== undefined && event === 'before_render') {
+          ctx.templateCtx = result;
+        }
+      } catch (err) {
+        if (event.startsWith('after_')) {
+          process.stderr.write(`[AdminHooks] Error in ${Resource.name}.${event}: ${err.message}\n`);
+        } else {
+          throw err;
+        }
+      }
+    }
+
+    return ctx;
+  }
+}
+
+// ── Singleton global registry ─────────────────────────────────────────────────
+const AdminHooks = new HookRegistry();
+
+module.exports = { HookRegistry, HookPipeline, AdminHooks, VALID_EVENTS };