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

asjs-express 1.1.1 → 1.2.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 (3) hide show

package/README.md CHANGED Viewed

@@ -97,6 +97,80 @@ 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.
+### 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)`.
@@ -537,6 +611,80 @@ 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.
+### 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

@@ -184,6 +184,196 @@ 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 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');
@@ -440,6 +630,7 @@ function createAsjsViewModel(inputAsjs, config, overrides = {}) {
   viewModel.viewAttrs = (extraAttributes) => renderViewAttrs(viewModel, extraAttributes);
   viewModel.formAttrs = (options) => renderFormAttrs(viewModel, options);
   viewModel.progressMarkup = () => renderProgressMarkup();
+  viewModel.header = (options) => renderHeaderMarkup(resolveHeaderState(config, {}, options));
   return viewModel;
 }
@@ -957,7 +1148,14 @@ 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(),
@@ -1378,9 +1576,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,
@@ -1574,6 +1798,7 @@ module.exports = {
   getAsjsPackagePaths,
   renderClientTags,
   renderDebugErrorPage,
+  renderHeaderMarkup,
   validateComponentProps,
   setupAsjs
 };

package/package.json CHANGED Viewed

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