@webstir-io/webstir 0.1.1 → 0.1.2

package/assets/templates/full/src/frontend/app/scripts/features/document-navigation.ts

@@ -0,0 +1,344 @@
+export interface NavigationDomRuntime {
+    readonly dynamicAttr: string;
+    readonly dynamicValue: string;
+    withBasePath(value: string): string;
+    stripBasePath(value: string): string;
+}
+
+export type DocumentNavigationResponseResolution =
+    | { readonly kind: 'document' }
+    | { readonly kind: 'navigate'; readonly reason: 'http-status' | 'non-html' };
+
+export function resolveDocumentNavigationResponse(options: {
+    readonly ok: boolean;
+    readonly contentType: string | null;
+}): DocumentNavigationResponseResolution {
+    if (!options.ok) {
+        return { kind: 'navigate', reason: 'http-status' };
+    }
+
+    if (!isHtmlDocumentContentType(options.contentType)) {
+        return { kind: 'navigate', reason: 'non-html' };
+    }
+
+    return { kind: 'document' };
+}
+
+export async function syncHead(
+    doc: Document,
+    url: string,
+    runtime: NavigationDomRuntime
+): Promise<void> {
+    const head = document.head;
+    const newHead = doc.head;
+    if (!head || !newHead) {
+        return;
+    }
+
+    const preservedClientNav = head.querySelector('script[data-webstir="client-nav"]');
+    const preservedAppCss = Array.from(head.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"]'))
+        .find((link) => isAppStylesheetHref(link.getAttribute('href'), runtime.stripBasePath)) ?? null;
+
+    for (const element of Array.from(head.querySelectorAll(`script[${runtime.dynamicAttr}="${runtime.dynamicValue}"]`))) {
+        element.remove();
+    }
+
+    for (const script of Array.from(head.querySelectorAll('script[src]'))) {
+        const src = script.getAttribute('src') ?? '';
+        const normalizedSrc = runtime.stripBasePath(src);
+        if (script === preservedClientNav) {
+            continue;
+        }
+        if (normalizedSrc === '/hmr.js' || normalizedSrc === '/refresh.js') {
+            continue;
+        }
+        if (normalizedSrc.startsWith('/pages/')) {
+            script.remove();
+        }
+    }
+
+    const desiredStyles = new Map<string, string>();
+    for (const link of Array.from(newHead.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"]'))) {
+        const href = link.getAttribute('href');
+        if (!href) {
+            continue;
+        }
+        const resolved = resolveUrl(href, url, runtime);
+        if (!resolved) {
+            continue;
+        }
+        const key = runtime.stripBasePath(stripQueryAndHash(resolved));
+        const finalHref = key === '/app/app.css' && preservedAppCss
+            ? (preservedAppCss.getAttribute('href') ?? resolved)
+            : runtime.withBasePath(resolved);
+        desiredStyles.set(key, finalHref);
+    }
+
+    if (preservedAppCss) {
+        const appHref = preservedAppCss.getAttribute('href') ?? runtime.withBasePath('/app/app.css');
+        desiredStyles.set('/app/app.css', appHref);
+    }
+
+    const existingStyles = new Map<string, HTMLLinkElement>();
+    const staleStyles: HTMLLinkElement[] = [];
+    for (const link of Array.from(head.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"]'))) {
+        const key = normalizeStylesheetKey(link.getAttribute('href'), window.location.href, runtime);
+        if (!key) {
+            link.remove();
+            continue;
+        }
+        if (desiredStyles.has(key)) {
+            if (!existingStyles.has(key)) {
+                existingStyles.set(key, link);
+            }
+            continue;
+        }
+        staleStyles.push(link);
+    }
+
+    const pendingStyles: HTMLLinkElement[] = [];
+    for (const [key, href] of desiredStyles.entries()) {
+        if (existingStyles.has(key)) {
+            continue;
+        }
+        const next = document.createElement('link');
+        next.rel = 'stylesheet';
+        next.href = href;
+        head.appendChild(next);
+        existingStyles.set(key, next);
+        pendingStyles.push(next);
+    }
+
+    const stylesReady = pendingStyles.length > 0
+        ? waitForStylesheets(pendingStyles)
+        : Promise.resolve();
+    if (staleStyles.length > 0) {
+        void stylesReady.then(() => {
+            requestAnimationFrame(() => {
+                for (const link of staleStyles) {
+                    link.remove();
+                }
+            });
+        });
+    }
+
+    syncCriticalStyles(head, newHead);
+
+    for (const script of Array.from(newHead.querySelectorAll('script[src]'))) {
+        const src = script.getAttribute('src');
+        if (!src) {
+            continue;
+        }
+        if (src === '/clientNav.js' || src.endsWith('/clientNav.js')) {
+            continue;
+        }
+        if (src === '/hmr.js' || src === '/refresh.js') {
+            continue;
+        }
+
+        const resolved = resolveUrl(src, url, runtime);
+        if (!resolved) {
+            continue;
+        }
+
+        const next = document.createElement('script');
+        const type = script.getAttribute('type');
+        if (type) {
+            next.type = type;
+        }
+        next.src = resolved;
+        next.setAttribute(runtime.dynamicAttr, runtime.dynamicValue);
+        head.appendChild(next);
+    }
+
+    if (preservedClientNav && !head.contains(preservedClientNav)) {
+        head.appendChild(preservedClientNav);
+    }
+
+    await stylesReady;
+}
+
+export function executeScripts(container: Element | null, runtime: NavigationDomRuntime): void {
+    if (!container) {
+        return;
+    }
+
+    const scripts = Array.from(container.querySelectorAll('script'));
+    for (const script of scripts) {
+        const src = script.getAttribute('src');
+        const type = script.getAttribute('type');
+
+        const normalizedSrc = src ? runtime.stripBasePath(src) : '';
+        if (normalizedSrc && (normalizedSrc === '/clientNav.js' || normalizedSrc.endsWith('/clientNav.js'))) {
+            script.remove();
+            continue;
+        }
+        if (normalizedSrc === '/hmr.js' || normalizedSrc === '/refresh.js') {
+            script.remove();
+            continue;
+        }
+
+        const next = document.createElement('script');
+        if (type) {
+            next.type = type;
+        }
+
+        if (src) {
+            const resolved = resolveUrl(src, window.location.href, runtime);
+            if (resolved) {
+                next.src = resolved;
+            }
+        } else if (script.textContent) {
+            next.textContent = script.textContent;
+        }
+
+        script.replaceWith(next);
+    }
+}
+
+export function focusAutofocus(root: ParentNode): void {
+    const focusTarget = root.querySelector('[autofocus]');
+    if (focusTarget instanceof HTMLElement) {
+        focusTarget.focus();
+    }
+}
+
+export function cssEscape(value: string): string {
+    if (typeof CSS !== 'undefined' && typeof (CSS as { escape?: (input: string) => string }).escape === 'function') {
+        return (CSS as { escape: (input: string) => string }).escape(value);
+    }
+    return value.replace(/[\"\\\\]/g, '\\\\$&');
+}
+
+function resolveUrl(value: string, baseUrl: string, runtime: NavigationDomRuntime): string | null {
+    try {
+        const trimmed = String(value ?? '').trim();
+        const [path, suffix] = splitPathSuffix(trimmed);
+        if (path && !path.startsWith('/') && !path.startsWith('http:') && !path.startsWith('https:')) {
+            if (path === 'index.js' || path === 'index.css') {
+                const pageName = getPageNameFromUrl(baseUrl, runtime.stripBasePath);
+                return runtime.withBasePath(`/pages/${pageName}/${path}${suffix}`);
+            }
+        }
+
+        const resolved = new URL(value, baseUrl);
+        return runtime.withBasePath(resolved.pathname + resolved.search + resolved.hash);
+    } catch {
+        return null;
+    }
+}
+
+function normalizeStylesheetKey(href: string | null, baseUrl: string, runtime: NavigationDomRuntime): string | null {
+    const resolved = resolveUrl(href ?? '', baseUrl, runtime);
+    if (!resolved) {
+        return null;
+    }
+    return runtime.stripBasePath(stripQueryAndHash(resolved));
+}
+
+function stripQueryAndHash(value: string): string {
+    return value.split(/[?#]/)[0] ?? value;
+}
+
+function waitForStylesheets(links: HTMLLinkElement[], timeoutMs = 2000): Promise<void> {
+    if (links.length === 0) {
+        return Promise.resolve();
+    }
+
+    return new Promise((resolve) => {
+        let remaining = links.length;
+        let done = false;
+        const finish = () => {
+            if (done) {
+                return;
+            }
+            done = true;
+            resolve();
+        };
+
+        const timer = window.setTimeout(finish, timeoutMs);
+        const handle = () => {
+            if (done) {
+                return;
+            }
+            remaining -= 1;
+            if (remaining <= 0) {
+                window.clearTimeout(timer);
+                finish();
+            }
+        };
+
+        for (const link of links) {
+            if (link.sheet) {
+                handle();
+                continue;
+            }
+            link.addEventListener('load', handle, { once: true });
+            link.addEventListener('error', handle, { once: true });
+        }
+    });
+}
+
+function syncCriticalStyles(head: HTMLHeadElement, newHead: HTMLHeadElement): void {
+    for (const style of Array.from(head.querySelectorAll<HTMLStyleElement>('style[data-critical]'))) {
+        style.remove();
+    }
+
+    for (const style of Array.from(newHead.querySelectorAll<HTMLStyleElement>('style[data-critical]'))) {
+        const next = document.createElement('style');
+        for (const attribute of Array.from(style.attributes)) {
+            next.setAttribute(attribute.name, attribute.value);
+        }
+        if (style.textContent) {
+            next.textContent = style.textContent;
+        }
+        head.appendChild(next);
+    }
+}
+
+function splitPathSuffix(value: string): [string, string] {
+    const [path, suffix = ''] = value.split(/(?=[?#])/);
+    return [path ?? '', suffix ?? ''];
+}
+
+function isAppStylesheetHref(href: string | null, stripBasePath: (value: string) => string): boolean {
+    if (!href) {
+        return false;
+    }
+
+    try {
+        const normalized = stripBasePath(new URL(href, window.location.origin).pathname);
+        return normalized === '/app/app.css';
+    } catch {
+        const trimmed = href.trim();
+        if (!trimmed) {
+            return false;
+        }
+        const [path] = trimmed.split(/[?#]/);
+        return stripBasePath(path) === '/app/app.css';
+    }
+}
+
+function isHtmlDocumentContentType(value: string | null): boolean {
+    if (!value) {
+        return false;
+    }
+
+    const normalized = value.toLowerCase();
+    return normalized.includes('text/html') || normalized.includes('application/xhtml+xml');
+}
+
+function getPageNameFromUrl(url: string, stripBasePath: (value: string) => string): string {
+    try {
+        const pathname = stripBasePath(new URL(url, window.location.href).pathname);
+        const trimmed = pathname.replace(/^\/+|\/+$/g, '');
+        if (!trimmed) {
+            return 'home';
+        }
+
+        const firstSegment = trimmed.split('/')[0];
+        return firstSegment || 'home';
+    } catch {
+        return 'home';
+    }
+}

package/assets/templates/full/src/frontend/app/scripts/features/form-enhancement.ts

@@ -0,0 +1,275 @@
+export type FragmentUpdateMode = 'replace' | 'append' | 'prepend';
+
+export interface FragmentResponseMetadata {
+    readonly target: string;
+    readonly selector?: string;
+    readonly mode: FragmentUpdateMode;
+}
+
+export type FragmentResponseMetadataIssue = 'target' | 'selector' | 'mode';
+
+export type FragmentResponseMetadataResolution =
+    | { readonly kind: 'none' }
+    | { readonly kind: 'invalid'; readonly issues: readonly FragmentResponseMetadataIssue[] }
+    | { readonly kind: 'fragment'; readonly fragment: FragmentResponseMetadata };
+
+export interface FragmentRootCandidate {
+    readonly id?: string | null;
+    readonly fragmentTarget?: string | null;
+    readonly matchesSelector?: boolean;
+}
+
+export type FragmentInsertionBehavior =
+    | 'replace-target'
+    | 'replace-children'
+    | 'append-payload'
+    | 'append-matching-root-children'
+    | 'prepend-payload'
+    | 'prepend-matching-root-children';
+
+export interface EnhancedFormRequest {
+    readonly url: string;
+    readonly init: RequestInit;
+}
+
+export type EnhancedFormResponseResolution =
+    | { readonly kind: 'fragment'; readonly fragment: FragmentResponseMetadata }
+    | { readonly kind: 'document' }
+    | {
+        readonly kind: 'navigate';
+        readonly location: string;
+        readonly reason: 'redirect' | 'missing-target' | 'invalid-fragment' | 'non-html';
+    };
+
+const CLIENT_NAV_HEADER = 'X-Webstir-Client-Nav';
+const DEFAULT_FORM_ENCODING = 'application/x-www-form-urlencoded';
+
+export function normalizeFormMethod(value: string | null | undefined): string {
+    const normalized = String(value ?? 'GET').trim().toUpperCase();
+    return normalized || 'GET';
+}
+
+export function normalizeFormEnctype(value: string | null | undefined): string {
+    const normalized = String(value ?? DEFAULT_FORM_ENCODING).trim().toLowerCase();
+    return normalized || DEFAULT_FORM_ENCODING;
+}
+
+export function buildEnhancedFormRequest(options: {
+    readonly action: string;
+    readonly method: string;
+    readonly enctype?: string | null;
+    readonly formData: FormData;
+}): EnhancedFormRequest | null {
+    const method = normalizeFormMethod(options.method);
+    if (method !== 'POST') {
+        return null;
+    }
+
+    const enctype = normalizeFormEnctype(options.enctype);
+    const headers = new Headers({ [CLIENT_NAV_HEADER]: '1' });
+
+    if (enctype === DEFAULT_FORM_ENCODING) {
+        const body = toUrlEncodedBody(options.formData);
+        if (body === null) {
+            return null;
+        }
+        headers.set('content-type', DEFAULT_FORM_ENCODING);
+        return {
+            url: options.action,
+            init: {
+                method,
+                headers,
+                body
+            }
+        };
+    }
+
+    if (enctype === 'multipart/form-data') {
+        return {
+            url: options.action,
+            init: {
+                method,
+                headers,
+                body: options.formData
+            }
+        };
+    }
+
+    return null;
+}
+
+export function resolveFragmentResponseMetadata(headers: Headers): FragmentResponseMetadataResolution {
+    const rawTarget = headers.get('x-webstir-fragment-target');
+    const rawSelector = headers.get('x-webstir-fragment-selector');
+    const rawMode = headers.get('x-webstir-fragment-mode');
+
+    if (rawTarget === null && rawSelector === null && rawMode === null) {
+        return { kind: 'none' };
+    }
+
+    const issues: FragmentResponseMetadataIssue[] = [];
+    const target = rawTarget?.trim() ?? '';
+    if (!target) {
+        issues.push('target');
+    }
+
+    let selector: string | undefined;
+    if (rawSelector !== null) {
+        const normalizedSelector = rawSelector.trim();
+        if (!normalizedSelector) {
+            issues.push('selector');
+        } else {
+            selector = normalizedSelector;
+        }
+    }
+
+    let mode: FragmentUpdateMode = 'replace';
+    if (rawMode !== null) {
+        const normalizedMode = rawMode.trim().toLowerCase();
+        if (normalizedMode === 'replace' || normalizedMode === 'append' || normalizedMode === 'prepend') {
+            mode = normalizedMode;
+        } else {
+            issues.push('mode');
+        }
+    }
+
+    if (issues.length > 0) {
+        return {
+            kind: 'invalid',
+            issues
+        };
+    }
+
+    return {
+        kind: 'fragment',
+        fragment: {
+            target,
+            selector,
+            mode
+        }
+    };
+}
+
+export function readFragmentResponseMetadata(headers: Headers): FragmentResponseMetadata | null {
+    const resolution = resolveFragmentResponseMetadata(headers);
+    return resolution.kind === 'fragment' ? resolution.fragment : null;
+}
+
+export function resolveEnhancedFormResponse(options: {
+    readonly metadata: FragmentResponseMetadataResolution;
+    readonly hasFragmentTarget: boolean;
+    readonly contentType: string | null;
+    readonly redirected: boolean;
+    readonly responseUrl?: string | null;
+    readonly requestUrl: string;
+}): EnhancedFormResponseResolution {
+    if (options.metadata.kind === 'fragment') {
+        if (options.hasFragmentTarget) {
+            return {
+                kind: 'fragment',
+                fragment: options.metadata.fragment
+            };
+        }
+
+        if (isHtmlDocumentContentType(options.contentType)) {
+            return { kind: 'document' };
+        }
+
+        return {
+            kind: 'navigate',
+            location: options.responseUrl || options.requestUrl,
+            reason: 'missing-target'
+        };
+    }
+
+    if (options.metadata.kind === 'invalid') {
+        if (isHtmlDocumentContentType(options.contentType)) {
+            return { kind: 'document' };
+        }
+
+        return {
+            kind: 'navigate',
+            location: options.responseUrl || options.requestUrl,
+            reason: 'invalid-fragment'
+        };
+    }
+
+    if (isHtmlDocumentContentType(options.contentType)) {
+        return { kind: 'document' };
+    }
+
+    if (options.redirected && options.responseUrl) {
+        return {
+            kind: 'navigate',
+            location: options.responseUrl,
+            reason: 'redirect'
+        };
+    }
+
+    return {
+        kind: 'navigate',
+        location: options.responseUrl || options.requestUrl,
+        reason: 'non-html'
+    };
+}
+
+export function isHtmlDocumentContentType(value: string | null): boolean {
+    if (!value) {
+        return false;
+    }
+
+    const normalized = value.toLowerCase();
+    return normalized.includes('text/html') || normalized.includes('application/xhtml+xml');
+}
+
+export function shouldReplaceFragmentTarget(options: {
+    readonly mode: FragmentUpdateMode;
+    readonly target: string;
+    readonly roots: readonly FragmentRootCandidate[];
+}): boolean {
+    return resolveFragmentInsertionBehavior(options) === 'replace-target';
+}
+
+export function resolveFragmentInsertionBehavior(options: {
+    readonly mode: FragmentUpdateMode;
+    readonly target: string;
+    readonly roots: readonly FragmentRootCandidate[];
+    readonly hasMeaningfulSiblingContent?: boolean;
+}): FragmentInsertionBehavior {
+    const hasMatchingRoot = options.roots.length === 1
+        && options.hasMeaningfulSiblingContent !== true
+        && rootMatchesFragmentTarget(options.roots[0], options.target);
+
+    if (options.mode === 'replace') {
+        return hasMatchingRoot ? 'replace-target' : 'replace-children';
+    }
+
+    if (options.mode === 'append') {
+        return hasMatchingRoot ? 'append-matching-root-children' : 'append-payload';
+    }
+
+    return hasMatchingRoot ? 'prepend-matching-root-children' : 'prepend-payload';
+}
+
+function toUrlEncodedBody(formData: FormData): URLSearchParams | null {
+    const params = new URLSearchParams();
+    let hasBinaryValue = false;
+    formData.forEach((value, key) => {
+        if (typeof value !== 'string') {
+            hasBinaryValue = true;
+            return;
+        }
+        params.append(key, value);
+    });
+    return hasBinaryValue ? null : params;
+}
+
+function matchesFragmentTarget(value: string | null | undefined, target: string): boolean {
+    return typeof value === 'string' && value.trim() === target;
+}
+
+function rootMatchesFragmentTarget(root: FragmentRootCandidate, target: string): boolean {
+    return root.matchesSelector === true
+        || matchesFragmentTarget(root.id, target)
+        || matchesFragmentTarget(root.fragmentTarget, target);
+}

package/assets/templates/full/src/frontend/pages/home/index.css

@@ -6,6 +6,7 @@
     gap: 2rem;
     align-items: center;
     text-align: center;
+    padding: 4rem 1.5rem;
 }
 
 .hero h1 {
@@ -19,3 +20,10 @@
     margin: 0 auto;
     max-width: 42ch;
 }
+
+.eyebrow {
+    font-size: 0.875rem;
+    font-weight: 700;
+    letter-spacing: 0.16em;
+    text-transform: uppercase;
+}

package/assets/templates/full/src/frontend/pages/home/index.html

@@ -5,6 +5,11 @@
 </head>
 <body>
     <main>
-        Home
+        <section class="hero">
+            <p class="eyebrow">Webstir full demo</p>
+            <h1>Home</h1>
+            <p>Open the canonical progressive-enhancement route to compare full-page redirects with fragment updates driven by the same HTML form.</p>
+            <p><a href="/api/demo/progressive-enhancement">Open the form flow demo</a></p>
+        </section>
     </main>
 </body>

package/assets/templates/full/src/frontend/pages/home/tests/home.test.ts

@@ -14,8 +14,18 @@ test('home page has expected parts', () => {
   const html = readFileSync(htmlPath, 'utf8');
 
   assert.isTrue(html.includes('<title>Home</title>'), 'Missing <title>Home</title>');
-  assert.isTrue(html.includes('<link rel="stylesheet" href="index.css"'), 'Missing CSS link to index.css');
-  assert.isTrue(html.includes('<script type="module" src="index.js"'), 'Missing module script to index.js');
+  assert.isTrue(
+    html.includes('<link rel="stylesheet" href="index.css"') || html.includes('<link rel="stylesheet" href="/pages/home/index.css"'),
+    'Missing CSS link to index.css'
+  );
+  assert.isTrue(
+    html.includes('<script type="module" src="index.js"') || html.includes('<script type="module" src="/pages/home/index.js"'),
+    'Missing module script to index.js'
+  );
   assert.isTrue(html.includes('<main'), 'Missing <main> container');
   assert.isTrue(html.includes('Home'), 'Missing Home content');
+  assert.isTrue(
+    html.includes('href="/api/demo/progressive-enhancement"'),
+    'Missing link to the progressive enhancement demo route'
+  );
 });

package/assets/templates/spa/src/frontend/pages/home/tests/home.test.ts

@@ -14,8 +14,16 @@ test('home page has expected parts', () => {
   const html = readFileSync(htmlPath, 'utf8');
 
   assert.isTrue(html.includes('<title>Home</title>'), 'Missing <title>Home</title>');
-  assert.isTrue(html.includes('<link rel="stylesheet" href="index.css"'), 'Missing CSS link to index.css');
-  assert.isTrue(html.includes('<script type="module" src="index.js"'), 'Missing module script to index.js');
+  assert.isTrue(
+    html.includes('<link rel="stylesheet" href="index.css"') ||
+      html.includes('<link rel="stylesheet" href="/pages/home/index.css"'),
+    'Missing CSS link to index.css',
+  );
+  assert.isTrue(
+    html.includes('<script type="module" src="index.js"') ||
+      html.includes('<script type="module" src="/pages/home/index.js"'),
+    'Missing module script to index.js',
+  );
   assert.isTrue(html.includes('<main'), 'Missing <main> container');
   assert.isTrue(html.includes('Home'), 'Missing Home content');
 });