asjs-express 1.2.0 → 1.4.0

package/lib/asjs.js

@@ -25,6 +25,192 @@ function normalizeNumberOption(value, fallback) {
   return Number.isFinite(normalized) && normalized >= 0 ? normalized : fallback;
 }
 
+function delay(duration) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, normalizeNumberOption(duration, 0));
+  });
+}
+
+function flattenClassNames(value) {
+  if (!value) {
+    return [];
+  }
+
+  if (Array.isArray(value)) {
+    return value.flatMap(flattenClassNames);
+  }
+
+  return String(value)
+    .split(/\s+/)
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function joinClassNames(...values) {
+  return [...new Set(values.flatMap(flattenClassNames))].join(' ');
+}
+
+function formatTimestamp(value = new Date(), options = {}) {
+  const settings = options && typeof options === 'object' ? options : {};
+  const locale = settings.locale || 'en-US';
+  const formatOptions = settings.formatOptions && typeof settings.formatOptions === 'object'
+    ? settings.formatOptions
+    : {
+      dateStyle: 'medium',
+      timeStyle: 'short'
+    };
+
+  return new Intl.DateTimeFormat(locale, formatOptions).format(value);
+}
+
+function normalizeFieldValue(value) {
+  return String(value || '').trim();
+}
+
+function normalizeFields(input = {}, fields = []) {
+  const source = input && typeof input === 'object' ? input : {};
+  const list = Array.isArray(fields)
+    ? fields
+    : Object.keys(fields && typeof fields === 'object' ? fields : {});
+
+  return list.reduce((result, fieldName) => {
+    result[fieldName] = normalizeFieldValue(source[fieldName]);
+    return result;
+  }, {});
+}
+
+function resolveValidationMessage(ruleValue, fallback) {
+  if (typeof ruleValue === 'string' && ruleValue) {
+    return ruleValue;
+  }
+
+  if (ruleValue && typeof ruleValue === 'object' && typeof ruleValue.message === 'string' && ruleValue.message) {
+    return ruleValue.message;
+  }
+
+  return fallback;
+}
+
+function validateFields(values = {}, schema = {}) {
+  const input = values && typeof values === 'object' ? values : {};
+  const rules = schema && typeof schema === 'object' ? schema : {};
+  const errors = {};
+
+  Object.entries(rules).forEach(([fieldName, fieldRules]) => {
+    const config = fieldRules && typeof fieldRules === 'object' ? fieldRules : {};
+    const label = config.label || fieldName;
+    const rawValue = Object.prototype.hasOwnProperty.call(input, fieldName) ? input[fieldName] : '';
+    const value = typeof rawValue === 'string' ? rawValue : normalizeFieldValue(rawValue);
+
+    if (config.required && !value) {
+      errors[fieldName] = resolveValidationMessage(config.required, `${label} is required.`);
+      return;
+    }
+
+    if (config.minLength) {
+      const minLength = normalizeNumberOption(
+        typeof config.minLength === 'object' ? config.minLength.value : config.minLength,
+        0
+      );
+
+      if (minLength > 0 && value.length < minLength) {
+        errors[fieldName] = resolveValidationMessage(
+          config.minLength,
+          `${label} must be at least ${minLength} characters.`
+        );
+        return;
+      }
+    }
+
+    if (config.pattern) {
+      const pattern = config.pattern instanceof RegExp
+        ? config.pattern
+        : (config.pattern && config.pattern.value instanceof RegExp ? config.pattern.value : null);
+
+      if (pattern && value && !pattern.test(value)) {
+        errors[fieldName] = resolveValidationMessage(config.pattern, `${label} format is invalid.`);
+        return;
+      }
+    }
+
+    if (typeof config.validate === 'function') {
+      const validationResult = config.validate(value, input);
+
+      if (typeof validationResult === 'string' && validationResult) {
+        errors[fieldName] = validationResult;
+      }
+    }
+  });
+
+  return errors;
+}
+
+function hasValidationErrors(errors) {
+  return Boolean(errors && typeof errors === 'object' && Object.keys(errors).length);
+}
+
+function renderInlineResponse(options = {}) {
+  const settings = options && typeof options === 'object' ? options : {};
+  const facts = Array.isArray(settings.facts) ? settings.facts : [];
+  const tone = settings.tone === 'error'
+    ? 'is-error'
+    : (settings.tone === 'neutral' ? 'is-neutral' : 'is-success');
+  const rootClassName = joinClassNames('asjs-inline-response', tone, settings.className);
+
+  return [
+    `<div class="${escapeHtml(rootClassName)}">`,
+    settings.title ? `  <strong>${escapeHtml(settings.title)}</strong>` : '',
+    `  <p>${escapeHtml(settings.message || 'The request was checked successfully.')}</p>`,
+    facts.length
+      ? '  <div class="inline-response-meta">' + facts.map((item) => (`<span><strong>${escapeHtml(item.label)}</strong>${escapeHtml(item.value)}</span>`)).join('') + '</div>'
+      : '',
+    '</div>'
+  ].join('');
+}
+
+function createPageModel(defaults = {}) {
+  const baseDefaults = defaults && typeof defaults === 'object' ? defaults : {};
+
+  return function buildPageModel(pageData = {}) {
+    const input = pageData && typeof pageData === 'object' ? pageData : {};
+
+    return {
+      ...baseDefaults,
+      ...input
+    };
+  };
+}
+
+function createPageRoute(pageHandlerFactory, viewName, options, pageFactory) {
+  const hasOptionsObject = options && typeof options === 'object' && !Array.isArray(options);
+  const settings = hasOptionsObject ? options : {};
+  const resolver = hasOptionsObject ? pageFactory : options;
+  const buildPage = typeof settings.buildPage === 'function'
+    ? settings.buildPage
+    : createPageModel(settings.pageDefaults || {});
+  const renderStateOptions = settings.renderState === false
+    ? false
+    : (settings.renderState && typeof settings.renderState === 'object' ? settings.renderState : null);
+
+  return pageHandlerFactory(viewName, async (req, res, next) => {
+    const renderState = renderStateOptions ? await createRenderState(req, renderStateOptions) : {};
+    const resolvedPageData = await Promise.resolve(
+      typeof resolver === 'function' ? resolver(req, res, next) : resolver
+    );
+
+    return buildPage({
+      ...renderState,
+      ...(resolvedPageData && typeof resolvedPageData === 'object' ? resolvedPageData : {})
+    }, {
+      next,
+      renderState,
+      req,
+      res,
+      viewName
+    });
+  });
+}
+
 function normalizeAssetMountPath(value) {
   const rawValue = value === undefined || value === null || value === ''
     ? '_asjs'
@@ -289,6 +475,42 @@ function normalizeSiteCtaOptions(value, fallback = null) {
   return defaults;
 }
 
+function normalizeLoadingBarOptions(value, fallback = { enabled: true, className: '' }) {
+  const base = fallback && typeof fallback === 'object'
+    ? {
+      enabled: fallback.enabled !== false,
+      className: typeof fallback.className === 'string' ? fallback.className : ''
+    }
+    : { enabled: true, className: '' };
+
+  if (value === undefined) {
+    return base;
+  }
+
+  if (typeof value === 'boolean') {
+    return {
+      ...base,
+      enabled: value
+    };
+  }
+
+  if (typeof value === 'string') {
+    return {
+      enabled: true,
+      className: value.trim()
+    };
+  }
+
+  if (value && typeof value === 'object') {
+    return {
+      enabled: value.enabled !== false,
+      className: typeof value.className === 'string' ? value.className.trim() : base.className
+    };
+  }
+
+  return base;
+}
+
 function resolveHeaderState(config, sourceLocals = {}, options = {}) {
   const locals = sourceLocals && typeof sourceLocals === 'object' ? sourceLocals : {};
   const input = options && typeof options === 'object' ? options : {};
@@ -571,6 +793,7 @@ function renderBodyAttrs(asjs, extraAttributes = {}) {
     'data-asjs-prefetch': asjs.prefetch ? 'true' : 'false',
     'data-asjs-prefetch-ttl': asjs.prefetchTtl,
     'data-asjs-loading-bar': asjs.loadingBar ? 'true' : 'false',
+    'data-asjs-loading-class': asjs.loadingBarClassName || undefined,
     'data-asjs-forms': asjs.forms && asjs.forms.enabled ? 'true' : 'false',
     'data-asjs-form-selector': asjs.forms ? asjs.forms.selector : undefined,
     'data-asjs-form-mode': asjs.forms ? asjs.forms.mode : undefined,
@@ -583,16 +806,29 @@ function renderBodyAttrs(asjs, extraAttributes = {}) {
 }
 
 function renderViewAttrs(asjs, extraAttributes = {}) {
+  const attributes = extraAttributes && typeof extraAttributes === 'object' ? { ...extraAttributes } : {};
+
   return serializeHtmlAttributes({
+    ...attributes,
+    class: joinClassNames('asjs-view', asjs.transition.className, attributes.class),
     'data-asjs-view': true,
     'data-asjs-transition': asjs.transition.enabled ? asjs.transition.name : 'none',
     'data-asjs-transition-duration': asjs.transition.duration,
-    ...extraAttributes
   });
 }
 
-function renderProgressMarkup() {
-  return '<div class="asjs-progress" data-asjs-progress aria-hidden="true"><span class="asjs-progress-bar"></span></div>';
+function renderProgressMarkup(asjs = {}, options = {}) {
+  const settings = options && typeof options === 'object' ? options : {};
+  const customClassName = joinClassNames(asjs.loadingBarClassName, settings.className);
+  const rootClassName = joinClassNames('asjs-progress', customClassName);
+  const barClassName = joinClassNames('asjs-progress-bar', settings.barClassName);
+
+  return `<div${serializeHtmlAttributes({
+    class: rootClassName,
+    'data-asjs-progress': true,
+    'data-asjs-progress-class': customClassName || undefined,
+    'aria-hidden': 'true'
+  })}><span${serializeHtmlAttributes({ class: barClassName })}></span></div>`;
 }
 
 function createAsjsViewModel(inputAsjs, config, overrides = {}) {
@@ -601,6 +837,18 @@ function createAsjsViewModel(inputAsjs, config, overrides = {}) {
   const transition = Object.prototype.hasOwnProperty.call(overrides, 'transition')
     ? normalizeTransitionOptions(overrides.transition, config.transitions)
     : normalizeTransitionOptions(current.transition, config.transitions);
+  const loadingBarState = normalizeLoadingBarOptions(
+    Object.prototype.hasOwnProperty.call(current, 'loadingBarClassName')
+      ? {
+        enabled: Object.prototype.hasOwnProperty.call(current, 'loadingBar') ? current.loadingBar : config.loadingBar,
+        className: current.loadingBarClassName
+      }
+      : current.loadingBar,
+    {
+      enabled: config.loadingBar,
+      className: config.loadingBarClassName
+    }
+  );
 
   const viewModel = {
     ...current,
@@ -612,9 +860,8 @@ function createAsjsViewModel(inputAsjs, config, overrides = {}) {
     prefetchTtl: Object.prototype.hasOwnProperty.call(current, 'prefetchTtl')
       ? normalizeNumberOption(current.prefetchTtl, config.prefetchTtl)
       : config.prefetchTtl,
-    loadingBar: Object.prototype.hasOwnProperty.call(current, 'loadingBar')
-      ? Boolean(current.loadingBar)
-      : config.loadingBar,
+    loadingBar: loadingBarState.enabled,
+    loadingBarClassName: loadingBarState.className,
     forms: Object.prototype.hasOwnProperty.call(current, 'forms')
       ? normalizeFormOptions(current.forms, config.forms)
       : normalizeFormOptions(undefined, config.forms),
@@ -629,7 +876,7 @@ function createAsjsViewModel(inputAsjs, config, overrides = {}) {
   viewModel.bodyAttrs = (extraAttributes) => renderBodyAttrs(viewModel, extraAttributes);
   viewModel.viewAttrs = (extraAttributes) => renderViewAttrs(viewModel, extraAttributes);
   viewModel.formAttrs = (options) => renderFormAttrs(viewModel, options);
-  viewModel.progressMarkup = () => renderProgressMarkup();
+  viewModel.progressMarkup = (options) => renderProgressMarkup(viewModel, options);
   viewModel.header = (options) => renderHeaderMarkup(resolveHeaderState(config, {}, options));
 
   return viewModel;
@@ -908,19 +1155,19 @@ function normalizeTransitionOptions(value, fallback = null) {
   if (value === undefined) {
     return fallback
       ? { ...fallback }
-      : { enabled: false, name: 'none', duration: 0 };
+      : { enabled: false, name: 'none', duration: 0, className: '' };
   }
 
   if (value === false || value === null || value === 'none') {
-    return { enabled: false, name: 'none', duration: 0 };
+    return { enabled: false, name: 'none', duration: 0, className: '' };
   }
 
   if (value === true) {
-    return { enabled: true, name: 'fade', duration: 260 };
+    return { enabled: true, name: 'fade', duration: 260, className: '' };
   }
 
   if (typeof value === 'string') {
-    return { enabled: true, name: value, duration: 260 };
+    return { enabled: true, name: value, duration: 260, className: '' };
   }
 
   if (typeof value === 'object') {
@@ -931,6 +1178,7 @@ function normalizeTransitionOptions(value, fallback = null) {
 
     return {
       enabled,
+      className: value.className ? String(value.className).trim() : '',
       name: enabled ? String(value.name || 'fade') : 'none',
       duration: enabled ? duration : 0
     };
@@ -938,7 +1186,7 @@ function normalizeTransitionOptions(value, fallback = null) {
 
   return fallback
     ? { ...fallback }
-    : { enabled: false, name: 'none', duration: 0 };
+    : { enabled: false, name: 'none', duration: 0, className: '' };
 }
 
 function resolveTemplatePath(name, currentFile, viewsDir, extension) {
@@ -1162,7 +1410,8 @@ function createAsjsConfig(options = {}) {
     transitions: normalizeTransitionOptions(options.transitions),
     prefetch: normalizeBooleanOption(options.prefetch, true),
     prefetchTtl: normalizeNumberOption(options.prefetchTtl, 30000),
-    loadingBar: normalizeBooleanOption(options.loadingBar, true),
+    loadingBar: normalizeLoadingBarOptions(options.loadingBar).enabled,
+    loadingBarClassName: normalizeLoadingBarOptions(options.loadingBar).className,
     forms: normalizeFormOptions(
       Object.prototype.hasOwnProperty.call(options, 'forms') ? options.forms : true
     ),
@@ -1612,6 +1861,30 @@ function buildPageLocals(req, config, pageData = {}) {
   };
 }
 
+async function createRenderState(req, options = {}) {
+  const settings = options && typeof options === 'object' ? options : {};
+  const startedAt = Date.now();
+
+  await delay(settings.delay);
+
+  const elapsed = Date.now() - startedAt;
+  const summary = Array.isArray(settings.summary)
+    ? settings.summary
+    : [
+      { label: 'Mode', value: settings.mode || 'res.render()' },
+      { label: 'Prepared by', value: settings.preparedBy || 'Async route callback' },
+      { label: 'Ready in', value: `${elapsed} ms` },
+      { label: 'Route', value: req.originalUrl || req.url }
+    ];
+
+  return {
+    renderLabel: settings.label || 'Server-prepared page model',
+    renderNarrative: settings.narrative || 'This page used an async ASJS callback so data work finished before res.render() produced the final HTML.',
+    renderSummary: summary,
+    renderTimestamp: formatTimestamp(new Date(), settings.timestamp || settings)
+  };
+}
+
 function setupAsjs(app, options = {}) {
   const config = createAsjsConfig(options);
 
@@ -1748,8 +2021,18 @@ function setupAsjs(app, options = {}) {
     app,
     config,
     clearCache,
+    createPageModel,
+    createPageRoute(viewName, routeOptions, pageFactory) {
+      return createPageRoute(page, viewName, routeOptions, pageFactory);
+    },
+    createRenderState,
     express,
+    formatTimestamp,
+    hasValidationErrors,
+    normalizeFields,
+    normalizeFieldValue,
     render,
+    renderInlineResponse,
     page,
     route: page,
     notFound,
@@ -1758,6 +2041,7 @@ function setupAsjs(app, options = {}) {
     packagePaths: config.packagePaths,
     extendLocals,
     defineComponents,
+    validateFields,
     addHook,
     use(plugin) {
       applyAsjsPlugin(plugin, api);
@@ -1792,13 +2076,22 @@ function setupAsjs(app, options = {}) {
 }
 
 module.exports = {
+  createPageModel,
+  createPageRoute,
   createAsjsConfig,
   createAsjsEngine,
+  createRenderState,
   escapeHtml,
+  formatTimestamp,
   getAsjsPackagePaths,
+  hasValidationErrors,
+  normalizeFields,
+  normalizeFieldValue,
   renderClientTags,
   renderDebugErrorPage,
   renderHeaderMarkup,
+  renderInlineResponse,
+  validateFields,
   validateComponentProps,
   setupAsjs
 };

package/lib/client/asjs-router.js

@@ -26,6 +26,26 @@
     return Number.isFinite(normalized) && normalized >= 0 ? normalized : fallback;
   }
 
+  function flattenClassNames(value) {
+    if (!value) {
+      return [];
+    }
+
+    if (Array.isArray(value)) {
+      return value.reduce((result, item) => result.concat(flattenClassNames(item)), []);
+    }
+
+    return String(value)
+      .split(/\s+/)
+      .map((item) => item.trim())
+      .filter(Boolean);
+  }
+
+  function joinClassNames() {
+    const values = Array.prototype.slice.call(arguments);
+    return Array.from(new Set(values.reduce((result, value) => result.concat(flattenClassNames(value)), []))).join(' ');
+  }
+
   function normalizePathname(value) {
     const normalized = String(value || '/').replace(/\/+$/, '');
     return normalized || '/';
@@ -258,6 +278,7 @@
       this.prefetchEnabled = parseBooleanAttribute(root && root.dataset.asjsPrefetch, this.defaultPrefetch);
       this.prefetchTtl = parseNumberAttribute(root && root.dataset.asjsPrefetchTtl, this.defaultPrefetchTtl);
       this.loadingBarEnabled = parseBooleanAttribute(root && root.dataset.asjsLoadingBar, this.defaultLoadingBar);
+      this.loadingBarClassName = (root && root.dataset.asjsLoadingClass) || '';
       this.formsEnabled = parseBooleanAttribute(root && root.dataset.asjsForms, this.defaultForms);
       this.formSelector = (root && root.dataset.asjsFormSelector) || this.defaultFormSelector;
       this.formMode = (root && root.dataset.asjsFormMode) || this.defaultFormMode;
@@ -265,17 +286,41 @@
       this.formResetOnSuccess = parseBooleanAttribute(root && root.dataset.asjsFormResetOnSuccess, this.defaultFormResetOnSuccess);
       this.formTarget = (root && root.dataset.asjsFormTarget) || this.defaultFormTarget;
       this.formSwap = (root && root.dataset.asjsFormSwap) || this.defaultFormSwap;
+      this.syncProgressRootClassName();
+    }
+
+    getProgressRootClassName() {
+      const progressClassName = this.progressRoot && this.progressRoot.dataset
+        ? this.progressRoot.dataset.asjsProgressClass || ''
+        : '';
+
+      return joinClassNames('asjs-progress', this.loadingBarClassName, progressClassName);
+    }
+
+    syncProgressRootClassName() {
+      if (!this.progressRoot) {
+        return;
+      }
+
+      const isActive = this.progressRoot.classList.contains('is-active');
+      this.progressRoot.className = this.getProgressRootClassName();
+
+      if (isActive) {
+        this.progressRoot.classList.add('is-active');
+      }
     }
 
     ensureProgressBar() {
       if (!this.progressRoot) {
         this.progressRoot = document.createElement('div');
-        this.progressRoot.className = 'asjs-progress';
+        this.progressRoot.className = this.getProgressRootClassName();
         this.progressRoot.dataset.asjsProgress = 'true';
         this.progressRoot.innerHTML = '<span class="asjs-progress-bar"></span>';
         document.body.prepend(this.progressRoot);
       }
 
+      this.syncProgressRootClassName();
+
       this.progressBar = this.progressRoot.querySelector('.asjs-progress-bar');
       return Boolean(this.progressRoot && this.progressBar);
     }

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "asjs-express",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Lightweight Express view engine with EJS-like templates, layouts, async page rendering, form enhancement, and a built-in client router.",
   "main": "index.js",
+  "bin": {
+    "asjs-express": "./bin/create-asjs-app.js",
+    "create-asjs-app": "./bin/create-asjs-app.js"
+  },
   "author": {
     "name": "Acarfx",
     "url": "https://acarfx.com"
@@ -21,28 +25,34 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "bin",
     "index.js",
     "lib",
-    "README.md"
+    "README.md",
+    "templates"
   ],
   "scripts": {
     "start": "node example-express/app.js",
     "demo": "node example-express/app.js",
     "dev": "node example-express/app.js",
     "example:express": "node example-express/app.js",
+    "example:minimal": "node example-minimal/app.js",
     "pack:check": "npm pack --dry-run"
   },
   "keywords": [
     "asjs",
     "component",
+    "cli",
     "ejs",
     "express",
     "express-view-engine",
     "forms",
     "layout",
     "prefetch",
+    "scaffold",
     "server-rendered",
     "ssr",
+    "starter-template",
     "template-engine",
     "view-engine",
     "spa-navigation"

package/templates/minimal/README.md.tpl

@@ -0,0 +1,12 @@
+# __APP_TITLE__
+
+This project was generated with `npx asjs-express`.
+
+## Run
+
+```bash
+npm install
+npm run dev
+```
+
+Open http://localhost:__PORT__

package/templates/minimal/app.js.tpl

@@ -0,0 +1,29 @@
+const express = require('express');
+const { setupAsjs } = require('asjs-express');
+
+const app = express();
+const port = process.env.PORT || __PORT__;
+
+const asjs = setupAsjs(app, {
+  rootDir: __dirname,
+  defaultLayout: 'layouts/main',
+  navItems: [
+    { href: '/', label: 'Home', activeMode: 'exact' }
+  ],
+  transitions: 'fade',
+  prefetch: true,
+  loadingBar: true
+});
+
+app.get('/', asjs.page('home', {
+  title: '__APP_TITLE__',
+  headline: '__APP_TITLE__ is ready.',
+  description: 'Header, router, loading bar, and SPA-ready page transitions are already connected.',
+  nextStep: 'Add a second route whenever you need it. ASJS will keep the same internal navigation flow.'
+}));
+
+app.use(asjs.errors());
+
+app.listen(port, () => {
+  console.log(`__APP_TITLE__ running at http://localhost:${port}`);
+});

package/templates/minimal/gitignore.tpl

@@ -0,0 +1,4 @@
+node_modules/
+.env
+.DS_Store
+npm-debug.log*

package/templates/minimal/package.json.tpl

@@ -0,0 +1,15 @@
+{
+  "name": "__PACKAGE_NAME__",
+  "version": "1.0.0",
+  "private": true,
+  "description": "ASJS minimal starter generated by npx asjs-express",
+  "main": "app.js",
+  "scripts": {
+    "dev": "node app.js",
+    "start": "node app.js"
+  },
+  "dependencies": {
+    "asjs-express": "^__ASJS_VERSION__",
+    "express": "__EXPRESS_VERSION__"
+  }
+}

package/templates/minimal/views/home.asjs.tpl

@@ -0,0 +1,5 @@
+<section style="max-width: 720px; margin: 40px auto; padding: 24px;">
+  <h1><%= headline %></h1>
+  <p><%= description %></p>
+  <p><%= nextStep %></p>
+</section>

package/templates/minimal/views/layouts/main.asjs.tpl

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title><%= title %></title>
+    <%- asjs.clientTags({ preload: true, theme: true }) %>
+  </head>
+  <body<%- asjs.bodyAttrs() %>>
+    <%- asjs.progressMarkup() %>
+    <%- asjs.header() %>
+    <main class="view-frame"<%- asjs.viewAttrs() %>>
+      <%- body %>
+    </main>
+  </body>
+</html>

package/templates/starter/README.md.tpl

@@ -0,0 +1,12 @@
+# __APP_TITLE__
+
+This project was generated with `npx asjs-express --template starter`.
+
+## Run
+
+```bash
+npm install
+npm run dev
+```
+
+Open http://localhost:__PORT__