feat: implement removedInV4 utility and update related code to handle deprecated options

Author: yaroslav8765

adminforth/auth.ts

@@ -4,7 +4,7 @@ import crypto from 'crypto';
 import AdminForth from './index.js';
 import { AdminUserAuthorizationResult, AdminUserAuthorizeFunction, AfterSessionCreatedFunction, HttpExtra, IAdminForthAuth, IAdminForthHttpResponse } from './types/Back.js';
 import { AdminUser } from './types/Common.js';
-import { listify } from './modules/utils.js';
+import { listify, removedInV4 } from './modules/utils.js';
 import { afLogger } from './modules/logger.js';
 import { Address4, Address6 } from 'ip-address';
 
@@ -130,6 +130,9 @@ class AdminForthAuth implements IAdminForthAuth {
   setCustomCookie({ response, payload }: {
     response: any, payload: { name: string, value: string, expirySeconds?: number, httpOnly: boolean, sessionBased?: boolean }
   }) {
+    if ('expiry' in payload) {
+      throw new Error(removedInV4('setCustomCookie payload "expiry"', 'expirySeconds'));
+    }
     const { name, value, httpOnly, expirySeconds = 24 * 60 * 60, sessionBased } = payload; // default 1 day
     const expiryMs = expirySeconds * 1000;
     const brandSlug = this.adminforth.config.customization.brandNameSlug;

adminforth/design/adoption.md

@@ -20,7 +20,6 @@ Which packages follow the [design concepts](./system-concepts.md): tokens instea
 | @adminforth/i18n | ✓ |
 | @adminforth/i18n-static | ✓ |
 | @adminforth/import-export | ✓ |
-| @adminforth/inline-create | |
 | @adminforth/json-form | |
 | @adminforth/list-in-place-edit | ✓ |
 | @adminforth/login-captcha | |
@@ -46,7 +45,7 @@ Which packages follow the [design concepts](./system-concepts.md): tokens instea
 
 ## Landing page previews
 
-The cards of the landing gallery (`documentation/src/pages/index.tsx`) show either a PNG screenshot (`original`) or a static HTML page of `documentation/static/landing-previews` (`preview: '<file>'`) drawn in the design system. A plugin moves to `preview` once it is adapted.
+The cards of the landing gallery (`documentation/src/pages/index.tsx`) show a static HTML page of `documentation/static/landing-previews` (`preview: '<file>'`) drawn in the design system.
 
 - Draw the screen of the plugin's core feature, not the whole page: keep one key element (an open menu, a form field, a dialog) and drop the columns, fields and buttons which don't explain the feature. A card is about 440px wide, so a screen with every column of the real page is unreadable.
 - Copy the closest page (a list, an edit form, a settings tab) and take the markup, texts, Lucide icons and tokens from the components of the plugin, the shared classes are in `previews.css`.
@@ -63,4 +62,4 @@ The cards of the landing gallery (`documentation/src/pages/index.tsx`) show eith
 
 - If simple - get of flowbite, prefer pure AFCL + Tailwind, move features we luck to AFCL
 - Existing icon fonts apart lucide - try to get rid of them if not complex
-- Core uses only Lucide icons and `flag-icons` flags (`afcl/CountryFlag.vue`). `vue-flowbite` and `vue-heroicons` stay in `spa/package.json` while plugins import them (flowbite: foreign-inline-list, inline-create, user-soft-delete, and dashboard only for `flowbite:chart-pie-solid`, the old default menu icon which stored dashboard configs may name; no plugin imports heroicons any more). After plugins rework it they should disappear.
+- Core uses only Lucide icons and `flag-icons` flags (`afcl/CountryFlag.vue`). `vue-flowbite` and `vue-heroicons` stay in `spa/package.json` while plugins import them (flowbite: foreign-inline-list, user-soft-delete, and dashboard only for `flowbite:chart-pie-solid`, the old default menu icon which stored dashboard configs may name; no plugin imports heroicons any more). After plugins rework it they should disappear.

adminforth/index.ts

@@ -4,7 +4,7 @@ import CodeInjector from './modules/codeInjector.js';
 import ExpressServer from './servers/express.js';
 import OpenApiRegistry from './servers/openapi.js';
 // import FastifyServer from './servers/fastify.js';
-import { ADMINFORTH_VERSION, listify, suggestIfTypo, RateLimiter, RAMLock, isProbablyUUIDColumn, convertPeriodToSeconds, hookResponseError, md5hash, applyRegexValidation, formatHugePluginError } from './modules/utils.js';
+import { ADMINFORTH_VERSION, listify, suggestIfTypo, RateLimiter, RAMLock, isProbablyUUIDColumn, convertPeriodToSeconds, hookResponseError, md5hash, applyRegexValidation, formatHugePluginError, removedInV4 } from './modules/utils.js';
 import { 
   type AdminForthConfig, 
   type IAdminForth, 
@@ -825,6 +825,9 @@ class AdminForth implements IAdminForth {
           `Note: Return { ok: false, error: null, redirectToRecordId } to stop creation and redirect to an existing record.`
         );
       }
+      if ('newRecordId' in resp) {
+        throw new Error(removedInV4(`Resource "${resource.resourceId}" hooks.create.beforeSave result "newRecordId"`, 'redirectToRecordId'));
+      }
       if (resp.ok === false && !resp.error) {
         const { error, redirectToRecordId } = resp;
         return {
@@ -886,6 +889,9 @@ class AdminForth implements IAdminForth {
   async updateResourceRecord(
     params: UpdateResourceRecordParams,
   ): Promise<UpdateResourceRecordResult> {
+    if ('record' in params) {
+      throw new Error(removedInV4('updateResourceRecord param "record"', 'updates'));
+    }
     const { resource, recordId, oldRecord, adminUser, extra, updates } = params;
     normalizeRecordValues(resource, updates);
     const err = this.validateRecordValues(resource, updates, 'edit');

adminforth/modules/configValidator.ts

@@ -18,7 +18,7 @@ import { compositePkValues, isCompositePrimaryKey } from './recordId.js';
 
 import fs from 'fs';
 import path from 'path';
-import { guessLabelFromName, md5hash, RateLimiter, suggestIfTypo, slugifyString } from './utils.js';
+import { guessLabelFromName, md5hash, RateLimiter, suggestIfTypo, slugifyString, removedInV4 } from './utils.js';
 import { 
   AdminForthSortDirections,
   type AdminForthComponentDeclarationFull,
@@ -179,6 +179,9 @@ export default class ConfigValidator implements IConfigValidator {
     customization.customPages.forEach((page) => {
       page.component = this.validateComponent(page.component, errors);
       const meta = page.component.meta || {};
+      if ('customLayout' in meta) {
+        errors.push(removedInV4(`Custom page "${page.path}" meta.customLayout`, `meta.sidebarAndHeader: 'none'`));
+      }
       if (meta.sidebarAndHeader === undefined) {
         meta.sidebarAndHeader = 'default';
       }
@@ -337,7 +340,9 @@ export default class ConfigValidator implements IConfigValidator {
     // an invalid showIn is reported with the other config errors, the column is normalized as if it had none
     // so the checks after this one do not crash on an undefined showIn before the errors are thrown
     const showInIsObject = column.showIn && !Array.isArray(column.showIn) && typeof column.showIn === 'object';
-    if (column.showIn && !showInIsObject) {
+    if (Array.isArray(column.showIn)) {
+      errors.push(removedInV4(`Resource "${resInput.resourceId || resInput.table}" column "${column.name}" showIn as an array`, 'an object, e.g. showIn: { list: true, edit: false }'));
+    } else if (column.showIn && !showInIsObject) {
       errors.push(`Resource "${resInput.resourceId || resInput.table}" column "${column.name}" showIn must be an object`);
     }
 
@@ -875,6 +880,9 @@ export default class ConfigValidator implements IConfigValidator {
         });
       }
 
+      if (resInput.options && 'bulkActions' in resInput.options) {
+        errors.push(removedInV4(`Resource "${res.resourceId}" options.bulkActions`, 'options.actions with bulkHandler'));
+      }
       const options: Partial<AdminForthResource['options']> = {...resInput.options, bulkActions: undefined, allowedActions: undefined};
 
       options.allowedActions = this.validateAndNormalizeAllowedActions(resInput, errors);
@@ -1158,6 +1166,9 @@ export default class ConfigValidator implements IConfigValidator {
     // AUTH checks
 
     if (newConfig.auth) {
+      if ('resourceId' in newConfig.auth) {
+        throw new Error(removedInV4('auth.resourceId', 'auth.usersResourceId'));
+      }
       if (!newConfig.auth.usersResourceId) {
         throw new Error('No config.auth.usersResourceId defined');
       }
@@ -1182,6 +1193,10 @@ export default class ConfigValidator implements IConfigValidator {
         }
       }
 
+      if ('rememberMeDays' in newConfig.auth) {
+        errors.push(removedInV4('auth.rememberMeDays', `auth.rememberMeDuration: "${newConfig.auth.rememberMeDays}d"`));
+      }
+
       if (newConfig.auth.rememberMeDuration !== undefined) {
         const duration = newConfig.auth.rememberMeDuration;
         if (typeof duration !== 'string') {

adminforth/modules/utils.ts

@@ -99,6 +99,13 @@ export function suggestIfTypo(names: string[], name: string): string {
 }
 
 
+/**
+ * Message for an option or param removed in AdminForth 4, names what to use instead
+ */
+export function removedInV4(what: string, replacement: string): string {
+  return `${what} is no longer supported in AdminForth 4+, use ${replacement} instead`;
+}
+
 export function md5hash(str:string) {
   return crypto.createHash('md5').update(str).digest('hex');
 }

documentation/src/pages/index.module.css

@@ -673,15 +673,11 @@
   flex-direction: column;
 }
 
-.gcard img,
+/* a drawn screen is a picture: no focus, clicks and scroll stay with the page */
 .gcard iframe {
   display: block;
   width: 100%;
   border-bottom: 1px solid var(--line);
-}
-
-/* a drawn screen is a picture: no focus, clicks and scroll stay with the page */
-.gcard iframe {
   aspect-ratio: 16 / 10;
   border-top: 0;
   border-right: 0;

documentation/src/pages/index.tsx

@@ -64,8 +64,8 @@ const FEATURED_ON = [
 
 type PluginItem = {name: string; slug: string; description: string; standard?: string};
 type PluginGroup = {title: string; items: PluginItem[]};
-// a card shows a screenshot (original) or a page of static/landing-previews drawn in the design system (preview)
-type GalleryItem = {title: string; link: string; description: string; original?: string; preview?: string};
+// a card shows a page of static/landing-previews drawn in the design system
+type GalleryItem = {title: string; link: string; description: string; preview: string};
 
 const images: GalleryItem[] = [
   {
@@ -159,12 +159,6 @@ const images: GalleryItem[] = [
     link: '/docs/tutorial/Plugins/list-in-place-edit/',
     description: 'Edit some oftenly used fields in list directly without opening edit page. Decide which fields to be editable in list view'
   },
-  {
-    original: require('@site/static/img/previews/inplace-create.png').default,
-    title: 'Inline create Plugin for quick create',
-    link: '/docs/tutorial/Plugins/inline-create/',
-    description: 'For tables with small fields number which should be created massively, use inline create plugin to create records directly in list view'
-  },
   {
     preview: 'import-export',
     title: 'Import/Export CSV Plugin',
@@ -264,7 +258,6 @@ const PLUGIN_GROUPS: PluginGroup[] = [
       {name: 'Markdown', slug: 'markdown', description: 'Author and preview Markdown, stored as Markdown'},
       {name: 'JSON form', slug: 'json-form', description: 'A real form for a JSON column, generated from your schema', standard: 'JSON Schema'},
       {name: 'Uploads', slug: 'upload', description: 'S3, S3-compatible or local storage under your own keys', standard: 'S3 API'},
-      {name: 'Inline create', slug: 'inline-create', description: 'Add a row without leaving the list'},
       {name: 'List in-place edit', slug: 'list-in-place-edit', description: 'Edit cells where you read them'},
       {name: 'Clone row', slug: 'clone-row', description: 'Duplicate a record into a prefilled form'},
       {name: 'Many-to-many', slug: 'many2many', description: 'Link tables managed as one ordinary field'},
@@ -544,16 +537,12 @@ function Gallery(): JSX.Element {
       <div className={styles.gallery}>
         {images.map((item, index) => (
           <div className={styles.gcard} key={`feature${index}`}>
-            {item.preview ? (
-              <iframe
-                src={withBaseUrl(`/landing-previews/${item.preview}.html`)}
-                title={item.title}
-                loading="lazy"
-                tabIndex={-1}
-              />
-            ) : (
-              <img src={item.original} alt={item.title} title={item.title} loading="lazy" />
-            )}
+            <iframe
+              src={withBaseUrl(`/landing-previews/${item.preview}.html`)}
+              title={item.title}
+              loading="lazy"
+              tabIndex={-1}
+            />
             <div className={styles.gcardBody}>
               <Heading as="h3" className={styles.gcardTitle}>{item.title}</Heading>
               <p>{item.description}</p>

live-demo/app/resources/users.ts

@@ -97,9 +97,9 @@ const usersResource: AdminForthResourceInput = {
     edit: {
       beforeSave: [
         blockDemoUsers,
-        async ({ record, adminUser, resource}: any) => {
-            if (record.password) {
-                record.password_hash = await AdminForth.Utils.generatePasswordHash(record.password);
+        async ({ updates }: any) => {
+            if (updates.password) {
+                updates.password_hash = await AdminForth.Utils.generatePasswordHash(updates.password);
             }
             return { ok: true }
         },