npm - asjs-express - Versions diffs - 1.1.1 → 1.3.0 - Mend

asjs-express 1.1.1 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md +444 -0
package/lib/asjs.js +533 -15
package/lib/client/asjs-router.js +46 -1
package/package.json +2 -1

package/README.md CHANGED Viewed

@@ -75,6 +75,74 @@ app.get('/', asjs.page('home', { title: 'Hello ASJS' }))
 app.listen(3000)
 ```
+### Super simple one-page starter
+If you want the lowest-friction starting point, use a single-page structure like this:
+```text
+my-app/
+  app.js
+  views/
+    layouts/
+      main.asjs
+    home.asjs
+```
+```js
+const express = require('express')
+const { setupAsjs } = require('asjs-express')
+const app = express()
+const asjs = setupAsjs(app, {
+  rootDir: __dirname,
+  defaultLayout: 'layouts/main',
+  navItems: [
+    { href: '/', label: 'Home' }
+  ],
+  transitions: 'fade',
+  prefetch: true,
+  loadingBar: true
+})
+app.get('/', asjs.page('home', {
+  title: 'My first ASJS page',
+  headline: 'ASJS works with almost no setup.',
+  description: 'Header, router, loading bar, and SPA-ready page transitions are already connected.'
+}))
+app.use(asjs.errors())
+app.listen(3000)
+```
+```asjs
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8">
+    <title><%= title %></title>
+    <%- asjs.clientTags({ preload: true, theme: true }) %>
+  </head>
+  <body<%- asjs.bodyAttrs() %>>
+    <%- asjs.progressMarkup() %>
+    <%- asjs.header() %>
+    <main<%- asjs.viewAttrs() %>>
+      <%- body %>
+    </main>
+  </body>
+</html>
+```
+```asjs
+<section>
+  <h1><%= headline %></h1>
+  <p><%= description %></p>
+</section>
+```
+This is enough for a working ASJS page.
+The repository also ships the same idea as a real folder under `example-minimal/`.
+You can run it with `npm run example:minimal`.
 ### Layout usage
 ```asjs
@@ -97,6 +165,160 @@ app.listen(3000)
 `asjs.clientTags()` injects the built-in ASJS stylesheet and router script for you.
 `theme: true` optionally loads the packaged light, corporate WebAS theme.
+### Easiest Express SPA setup
+If you want the easiest integration, build it in 3 files: `app.js`, `views/layouts/main.asjs`, and one page such as `views/home.asjs`.
+```js
+const express = require('express')
+const { setupAsjs } = require('asjs-express')
+const app = express()
+const asjs = setupAsjs(app, {
+  rootDir: __dirname,
+  defaultLayout: 'layouts/main',
+  navItems: [
+    { href: '/', label: 'Home' },
+    { href: '/about', label: 'About' },
+    { href: '/contact', label: 'Contact' }
+  ],
+  transitions: 'fade',
+  prefetch: true,
+  loadingBar: true
+})
+const buildPage = asjs.createPageModel({
+  pageDescription: 'My first ASJS page',
+  renderSummary: []
+})
+app.get('/', asjs.createPageRoute('home', {
+  buildPage,
+  renderState: {
+    delay: 120,
+    label: 'Home page ready',
+    narrative: 'ASJS prepared this page model before the HTML response was sent.'
+  }
+}, () => ({
+  title: 'Home',
+  heroTitle: 'Hello ASJS',
+  heroText: 'This page is server-rendered and SPA navigation is already active.'
+})))
+app.listen(3000)
+```
+```asjs
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8">
+    <title><%= title %></title>
+    <%- asjs.clientTags({ preload: true, theme: true }) %>
+  </head>
+  <body<%- asjs.bodyAttrs() %>>
+    <%- asjs.progressMarkup() %>
+    <%- asjs.header() %>
+    <main<%- asjs.viewAttrs() %>>
+      <%- body %>
+    </main>
+  </body>
+</html>
+```
+Default SPA loading and page transition animations are already included.
+If you do not add a custom class, ASJS keeps the built-in loading bar and transition look.
+If you want to style on top of them later, pass a class name instead of replacing the system.
+```js
+const asjs = setupAsjs(app, {
+  rootDir: __dirname,
+  defaultLayout: 'layouts/main',
+  transitions: {
+    name: 'fade',
+    className: 'my-page-motion'
+  },
+  loadingBar: {
+    enabled: true,
+    className: 'my-loading-bar'
+  }
+})
+```
+### Built-in SPA header
+ASJS now ships with a built-in header helper for the default SPA flow.
+You do not have to define `brand`, `siteCta`, or `isActiveNavItem` just to make a working header. If you want a standard header, `navItems` is the only thing you will usually customize.
+```js
+const express = require('express')
+const { setupAsjs } = require('asjs-express')
+const app = express()
+const asjs = setupAsjs(app, {
+  rootDir: __dirname,
+  defaultLayout: 'layouts/main',
+  navItems: [
+    { href: '/', label: 'Home', activeMode: 'exact' },
+    { href: '/products', label: 'Products', activeMode: 'exact' },
+    { href: '/contact', label: 'Contact', activeMode: 'exact' }
+  ],
+  transitions: 'fade',
+  prefetch: true,
+  loadingBar: true
+})
+```
+```asjs
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8">
+    <title><%= title %></title>
+    <%- asjs.clientTags({ preload: true, theme: true }) %>
+  </head>
+  <body<%- asjs.bodyAttrs() %>>
+    <%- asjs.progressMarkup() %>
+    <%- asjs.header() %>
+    <main<%- asjs.viewAttrs() %>>
+      <%- body %>
+    </main>
+  </body>
+</html>
+```
+The built-in header is SPA-aware by default.
+It renders `data-asjs-link`, uses the current request path automatically, and applies active states internally.
+If you do not define a brand, ASJS generates a safe default brand object.
+If you do not define `siteCta`, the header still works and simply renders without the CTA button.
+If you want to customize them later, you can still pass them through `setupAsjs()`.
+```js
+const asjs = setupAsjs(app, {
+  rootDir: __dirname,
+  defaultLayout: 'layouts/main',
+  navItems: [
+    { href: '/', label: 'Overview' },
+    { href: '/contact', label: 'Contact' }
+  ],
+  brand: {
+    href: '/',
+    mark: 'WA',
+    name: 'WebAS',
+    tagline: 'Shared interface structure for Express projects'
+  },
+  siteCta: {
+    href: '/contact',
+    label: 'Start a project',
+    transition: 'slide'
+  }
+})
+```
+If you still prefer a custom partial, ASJS now also injects `brand`, `siteCta`, `currentPath`, and `isActiveNavItem` into the view locals automatically.
 ### Work before the page loads
 Yes. If you pass an async callback to `asjs.page()`, ASJS waits for that work to finish and only then calls `res.render(viewName, locals)`.
@@ -515,6 +737,74 @@ app.get('/', asjs.page('home', { title: 'Merhaba ASJS' }))
 app.listen(3000)
 ```
+### Aşırı basit tek sayfa başlangıcı
+En az sürtünmeli başlangıç için şu kadar basit bir yapı yeterlidir:
+```text
+my-app/
+  app.js
+  views/
+    layouts/
+      main.asjs
+    home.asjs
+```
+```js
+const express = require('express')
+const { setupAsjs } = require('asjs-express')
+const app = express()
+const asjs = setupAsjs(app, {
+  rootDir: __dirname,
+  defaultLayout: 'layouts/main',
+  navItems: [
+    { href: '/', label: 'Ana Sayfa' }
+  ],
+  transitions: 'fade',
+  prefetch: true,
+  loadingBar: true
+})
+app.get('/', asjs.page('home', {
+  title: 'İlk ASJS sayfam',
+  headline: 'ASJS neredeyse kurulum istemeden çalışır.',
+  description: 'Header, router, loading bar ve SPA hazır sayfa geçişleri zaten bağlı gelir.'
+}))
+app.use(asjs.errors())
+app.listen(3000)
+```
+```asjs
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8">
+    <title><%= title %></title>
+    <%- asjs.clientTags({ preload: true, theme: true }) %>
+  </head>
+  <body<%- asjs.bodyAttrs() %>>
+    <%- asjs.progressMarkup() %>
+    <%- asjs.header() %>
+    <main<%- asjs.viewAttrs() %>>
+      <%- body %>
+    </main>
+  </body>
+</html>
+```
+```asjs
+<section>
+  <h1><%= headline %></h1>
+  <p><%= description %></p>
+</section>
+```
+Bu kadarı çalışan bir ASJS sayfası için yeterlidir.
+Aynı mantığın gerçek klasör örneği repo içinde `example-minimal/` altında da var.
+Çalıştırmak için `npm run example:minimal` kullanabilirsin.
 ### Layout kullanımı
 ```asjs
@@ -537,6 +827,160 @@ app.listen(3000)
 `asjs.clientTags()` çağrısı dahili ASJS stil ve router etiketlerini otomatik üretir.
 `theme: true` ise açık renkli, kurumsal WebAS temasını yükler.
+### En kolay Express SPA kurulumu
+En kolay entegrasyon için 3 dosya yeterlidir: `app.js`, `views/layouts/main.asjs` ve örnek olarak `views/home.asjs`.
+```js
+const express = require('express')
+const { setupAsjs } = require('asjs-express')
+const app = express()
+const asjs = setupAsjs(app, {
+  rootDir: __dirname,
+  defaultLayout: 'layouts/main',
+  navItems: [
+    { href: '/', label: 'Ana Sayfa' },
+    { href: '/about', label: 'Hakkında' },
+    { href: '/contact', label: 'İletişim' }
+  ],
+  transitions: 'fade',
+  prefetch: true,
+  loadingBar: true
+})
+const buildPage = asjs.createPageModel({
+  pageDescription: 'İlk ASJS sayfam',
+  renderSummary: []
+})
+app.get('/', asjs.createPageRoute('home', {
+  buildPage,
+  renderState: {
+    delay: 120,
+    label: 'Ana sayfa hazır',
+    narrative: 'ASJS bu sayfa modelini HTML cevabı gitmeden önce hazırladı.'
+  }
+}, () => ({
+  title: 'Ana Sayfa',
+  heroTitle: 'Merhaba ASJS',
+  heroText: 'Bu sayfa server-rendered çalışır ve SPA gezinme hemen aktiftir.'
+})))
+app.listen(3000)
+```
+```asjs
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8">
+    <title><%= title %></title>
+    <%- asjs.clientTags({ preload: true, theme: true }) %>
+  </head>
+  <body<%- asjs.bodyAttrs() %>>
+    <%- asjs.progressMarkup() %>
+    <%- asjs.header() %>
+    <main<%- asjs.viewAttrs() %>>
+      <%- body %>
+    </main>
+  </body>
+</html>
+```
+Varsayılan SPA yükleme ve sayfa geçiş animasyonları zaten dahildir.
+Ek bir class vermezsen ASJS dahili loading bar ve transition görünümünü korur.
+Sonradan üstüne kendi stilini yazmak istersen sistemi komple değiştirmek yerine sadece class eklersin.
+```js
+const asjs = setupAsjs(app, {
+  rootDir: __dirname,
+  defaultLayout: 'layouts/main',
+  transitions: {
+    name: 'fade',
+    className: 'my-page-motion'
+  },
+  loadingBar: {
+    enabled: true,
+    className: 'my-loading-bar'
+  }
+})
+```
+### Dahili SPA header sistemi
+ASJS artık varsayılan SPA akışı için dahili bir header helper ile geliyor.
+Çalışan bir header kurmak için `brand`, `siteCta` veya `isActiveNavItem` tanımlamak zorunda değilsin. Standart bir header istiyorsan çoğu durumda sadece `navItems` alanını düzenlemen yeterlidir.
+```js
+const express = require('express')
+const { setupAsjs } = require('asjs-express')
+const app = express()
+const asjs = setupAsjs(app, {
+  rootDir: __dirname,
+  defaultLayout: 'layouts/main',
+  navItems: [
+    { href: '/', label: 'Ana Sayfa', activeMode: 'exact' },
+    { href: '/products', label: 'Ürünler', activeMode: 'exact' },
+    { href: '/contact', label: 'İletişim', activeMode: 'exact' }
+  ],
+  transitions: 'fade',
+  prefetch: true,
+  loadingBar: true
+})
+```
+```asjs
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8">
+    <title><%= title %></title>
+    <%- asjs.clientTags({ preload: true, theme: true }) %>
+  </head>
+  <body<%- asjs.bodyAttrs() %>>
+    <%- asjs.progressMarkup() %>
+    <%- asjs.header() %>
+    <main<%- asjs.viewAttrs() %>>
+      <%- body %>
+    </main>
+  </body>
+</html>
+```
+Bu dahili header varsayılan olarak SPA uyumludur.
+Linkleri `data-asjs-link` ile üretir, mevcut request path bilgisini kendi alır ve aktif link durumunu içeride hesaplar.
+`brand` tanımlamazsan ASJS güvenli bir varsayılan brand nesnesi üretir.
+`siteCta` tanımlamazsan header bozulmaz; sadece sağ taraftaki CTA düğmesi çizilmez.
+Daha sonra özelleştirmek istersen bunları yine `setupAsjs()` üzerinden verebilirsin.
+```js
+const asjs = setupAsjs(app, {
+  rootDir: __dirname,
+  defaultLayout: 'layouts/main',
+  navItems: [
+    { href: '/', label: 'Genel Bakış' },
+    { href: '/contact', label: 'İletişim' }
+  ],
+  brand: {
+    href: '/',
+    mark: 'WA',
+    name: 'WebAS',
+    tagline: 'Express projeleri için ortak arayüz yapısı'
+  },
+  siteCta: {
+    href: '/contact',
+    label: 'Proje başlat',
+    transition: 'slide'
+  }
+})
+```
+Kendi partial yapını yazmak istersen ASJS artık `brand`, `siteCta`, `currentPath` ve `isActiveNavItem` alanlarını da view locals içine otomatik koyar.
 ### Sayfa yüklenmeden önce işlem yapmak
 Evet, mümkün. `asjs.page()` içine async bir callback verirsen ASJS bu işlemin bitmesini bekler, ardından `res.render(viewName, locals)` çağrısını yapar.

package/lib/asjs.js CHANGED Viewed

@@ -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'
@@ -184,6 +370,232 @@ function renderClientTags(assets, options = {}) {
   return tags.join('\n');
 }
+function normalizePathname(value) {
+  const normalized = String(value || '/').replace(/\/+$/, '');
+  return normalized || '/';
+}
+function isActiveNavItem(currentPath, item = {}) {
+  const pathname = normalizePathname(currentPath);
+  const targetPath = normalizePathname(item.matchPath || item.href || '/');
+  const activeMode = String(item.activeMode || 'exact').toLowerCase();
+  if (activeMode === 'prefix') {
+    if (targetPath === '/') {
+      return pathname === '/';
+    }
+    return pathname === targetPath || pathname.startsWith(`${targetPath}/`);
+  }
+  return pathname === targetPath;
+}
+function normalizeNavItems(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value
+    .filter((item) => item && typeof item === 'object')
+    .map((item) => ({
+      ...item,
+      href: String(item.href || '/'),
+      label: item.label ? String(item.label) : String(item.href || '/'),
+      activeMode: String(item.activeMode || 'exact').toLowerCase()
+    }));
+}
+function normalizeBrandOptions(value, fallback = {}) {
+  const defaults = {
+    href: '/',
+    mark: 'AS',
+    name: fallback.name || 'ASJS',
+    tagline: fallback.tagline || 'Server-rendered interface shell for Express',
+    caption: fallback.caption || '',
+    transition: 'fade'
+  };
+  if (typeof value === 'string' && value) {
+    return {
+      ...defaults,
+      name: value
+    };
+  }
+  if (value && typeof value === 'object') {
+    return {
+      ...defaults,
+      ...value,
+      href: String(value.href || defaults.href),
+      mark: value.mark ? String(value.mark) : defaults.mark,
+      name: value.name ? String(value.name) : defaults.name,
+      tagline: value.tagline ? String(value.tagline) : defaults.tagline,
+      caption: value.caption ? String(value.caption) : defaults.caption,
+      transition: value.transition ? String(value.transition) : defaults.transition
+    };
+  }
+  return defaults;
+}
+function normalizeSiteCtaOptions(value, fallback = null) {
+  const defaults = fallback && typeof fallback === 'object'
+    ? {
+      href: String(fallback.href || '/'),
+      label: fallback.label ? String(fallback.label) : 'Get Started',
+      transition: fallback.transition ? String(fallback.transition) : 'fade'
+    }
+    : null;
+  if (value === undefined) {
+    return defaults;
+  }
+  if (value === false || value === null) {
+    return null;
+  }
+  if (typeof value === 'string' && value) {
+    return {
+      href: value,
+      label: defaults ? defaults.label : 'Get Started',
+      transition: defaults ? defaults.transition : 'fade'
+    };
+  }
+  if (value && typeof value === 'object') {
+    return {
+      href: String(value.href || (defaults ? defaults.href : '/')),
+      label: value.label ? String(value.label) : (defaults ? defaults.label : 'Get Started'),
+      transition: value.transition ? String(value.transition) : (defaults ? defaults.transition : 'fade')
+    };
+  }
+  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 : {};
+  const siteName = input.siteName || locals.siteName || config.locals.siteName || 'ASJS';
+  const navItems = normalizeNavItems(
+    Array.isArray(input.navItems)
+      ? input.navItems
+      : (Array.isArray(locals.navItems) ? locals.navItems : config.navItems)
+  );
+  const brand = normalizeBrandOptions(
+    Object.prototype.hasOwnProperty.call(input, 'brand')
+      ? input.brand
+      : (Object.prototype.hasOwnProperty.call(locals, 'brand') ? locals.brand : config.brand),
+    { name: siteName }
+  );
+  const siteCta = normalizeSiteCtaOptions(
+    Object.prototype.hasOwnProperty.call(input, 'siteCta')
+      ? input.siteCta
+      : (Object.prototype.hasOwnProperty.call(locals, 'siteCta') ? locals.siteCta : config.siteCta),
+    config.siteCta
+  );
+  return {
+    brand,
+    currentPath: input.currentPath || locals.currentPath || '/',
+    isActiveNavItem: typeof input.isActiveNavItem === 'function'
+      ? input.isActiveNavItem
+      : (typeof locals.isActiveNavItem === 'function' ? locals.isActiveNavItem : isActiveNavItem),
+    navItems,
+    note: input.note || locals.headerNote || '',
+    noteLabel: input.noteLabel || locals.headerNoteLabel || '',
+    siteCta,
+    siteName
+  };
+}
+function renderHeaderMarkup(options = {}) {
+  const brand = options.brand || normalizeBrandOptions();
+  const currentPath = options.currentPath || '/';
+  const resolveActive = typeof options.isActiveNavItem === 'function' ? options.isActiveNavItem : isActiveNavItem;
+  const navigation = normalizeNavItems(options.navItems);
+  const note = options.note ? String(options.note) : '';
+  const noteLabel = options.noteLabel ? String(options.noteLabel) : '';
+  const cta = normalizeSiteCtaOptions(options.siteCta);
+  return [
+    '<header class="example-header">',
+    note
+      ? `  <div class="header-note"><span class="example-pill">${escapeHtml(noteLabel || 'Site Header')}</span><p>${escapeHtml(note)}</p></div>`
+      : '',
+    '  <div class="header-main">',
+    `    <a${serializeHtmlAttributes({
+      class: 'brand-link',
+      href: brand.href || '/',
+      'data-asjs-link': true,
+      ...(brand.transition ? { 'data-asjs-transition': brand.transition } : {})
+    })}><span class="brand-mark">${escapeHtml(brand.mark || 'AS')}</span><span class="brand-copy"><strong>${escapeHtml(brand.name || options.siteName || 'ASJS')}</strong><span>${escapeHtml(brand.tagline || 'Server-rendered interface shell for Express')}</span>${brand.caption ? `<small>${escapeHtml(brand.caption)}</small>` : ''}</span></a>`,
+    navigation.length
+      ? `    <nav class="site-nav" aria-label="Primary navigation">${navigation.map((item) => {
+        const isActive = resolveActive(currentPath, item);
+        return `<a${serializeHtmlAttributes({
+          href: item.href,
+          class: `site-link${isActive ? ' is-active' : ''}`,
+          'data-asjs-link': true,
+          'data-asjs-active': item.activeMode || 'exact',
+          ...(item.matchPath ? { 'data-asjs-match-path': item.matchPath } : {}),
+          ...(item.transition ? { 'data-asjs-transition': item.transition } : {}),
+          ...(isActive ? { 'aria-current': 'page' } : {})
+        })}><span>${escapeHtml(item.label)}</span>${item.description ? `<small>${escapeHtml(item.description)}</small>` : ''}</a>`;
+      }).join('')}</nav>`
+      : '',
+    cta
+      ? `    <a${serializeHtmlAttributes({
+        class: 'button button-secondary header-cta',
+        href: cta.href,
+        'data-asjs-link': true,
+        ...(cta.transition ? { 'data-asjs-transition': cta.transition } : {})
+      })}>${escapeHtml(cta.label)}</a>`
+      : '',
+    '  </div>',
+    '</header>'
+  ].filter(Boolean).join('');
+}
 function normalizeFormMode(value, fallback = 'view') {
   const normalized = String(value || fallback || 'view').toLowerCase();
   return ['view', 'json'].includes(normalized) ? normalized : (fallback || 'view');
@@ -381,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,
@@ -393,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 = {}) {
@@ -411,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,
@@ -422,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),
@@ -439,7 +876,8 @@ 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;
 }
@@ -717,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') {
@@ -740,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
     };
@@ -747,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) {
@@ -957,14 +1396,22 @@ function createAsjsConfig(options = {}) {
     defaultLayout: options.defaultLayout || null,
     debug: Boolean(options.debug),
     cache: normalizeBooleanOption(options.cache, !options.debug),
-    navItems: Array.isArray(options.navItems) ? options.navItems : [],
+    navItems: normalizeNavItems(options.navItems),
+    brand: normalizeBrandOptions(
+      Object.prototype.hasOwnProperty.call(options, 'brand') ? options.brand : undefined,
+      { name: options.locals && options.locals.siteName ? options.locals.siteName : 'ASJS' }
+    ),
+    siteCta: normalizeSiteCtaOptions(
+      Object.prototype.hasOwnProperty.call(options, 'siteCta') ? options.siteCta : undefined
+    ),
     locals: options.locals && typeof options.locals === 'object' ? options.locals : {},
     components: normalizeComponentRegistry(options.components || {}, extension),
     templateCache: new Map(),
     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
     ),
@@ -1378,9 +1825,35 @@ function buildPageLocals(req, config, pageData = {}) {
   delete locals.transition;
   delete locals.asjs;
-  locals.navItems = Array.isArray(input.navItems) ? input.navItems : config.navItems;
+  const headerOverrides = {
+    currentPath: input.currentPath || req.path
+  };
+  if (Array.isArray(input.navItems)) {
+    headerOverrides.navItems = input.navItems;
+  }
+  if (Object.prototype.hasOwnProperty.call(input, 'brand')) {
+    headerOverrides.brand = input.brand;
+  }
+  if (Object.prototype.hasOwnProperty.call(input, 'siteCta')) {
+    headerOverrides.siteCta = input.siteCta;
+  }
+  if (typeof input.isActiveNavItem === 'function') {
+    headerOverrides.isActiveNavItem = input.isActiveNavItem;
+  }
+  const headerState = resolveHeaderState(config, locals, headerOverrides);
+  locals.brand = headerState.brand;
+  locals.isActiveNavItem = headerState.isActiveNavItem;
+  locals.navItems = headerState.navItems;
   locals.currentPath = input.currentPath || req.path;
   locals.asjs = createAsjsViewModel(pageAsjs, config, { transition });
+  locals.siteCta = headerState.siteCta;
+  locals.asjs.header = (options) => renderHeaderMarkup(resolveHeaderState(config, locals, options));
   return {
     locals,
@@ -1388,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);
@@ -1524,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,
@@ -1534,6 +2041,7 @@ function setupAsjs(app, options = {}) {
     packagePaths: config.packagePaths,
     extendLocals,
     defineComponents,
+    validateFields,
     addHook,
     use(plugin) {
       applyAsjsPlugin(plugin, api);
@@ -1568,12 +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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "asjs-express",
-  "version": "1.1.1",
+  "version": "1.3.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",
   "author": {
@@ -30,6 +30,7 @@
     "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": [