redweb 0.9.0 → 0.11.0

package/src/htmx/StaticSite.js

@@ -0,0 +1,182 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { decoratorDirectory } = require('./sourceRoot');
+const { getPageTemplateRoot, page, pageCache, pageHead, setPageStylesheetRoots } = require('./metadata');
+const { exportStatic } = require('./StaticExporter');
+
+function plainObject(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError(`${label} must be an object.`);
+    return value;
+}
+
+function files(value, label) {
+    if (value === undefined) return [];
+    const result = Array.isArray(value) ? value : [value];
+    if (!result.length || result.some(file => typeof file !== 'string' || !file)) {
+        throw new TypeError(`${label} must be a non-empty path or array of non-empty paths.`);
+    }
+    return result;
+}
+
+function siteOrigin(value) {
+    if (value === undefined) return undefined;
+    if (typeof value !== 'string' || !value) throw new TypeError('Site origin must be an absolute HTTP(S) origin.');
+    let parsed;
+    try { parsed = new URL(value); }
+    catch { throw new TypeError('Site origin must be an absolute HTTP(S) origin.'); }
+    if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password ||
+        parsed.pathname !== '/' || parsed.search || parsed.hash) {
+        throw new TypeError('Site origin must be an absolute HTTP(S) origin.');
+    }
+    return parsed.origin;
+}
+
+function resolveHead(origin, route, defaults, overrides) {
+    const head = { ...defaults, ...overrides };
+    if (origin && head.canonical === undefined) head.canonical = new URL(route, `${origin}/`).href;
+    if (origin && typeof head.image === 'string' && head.image.startsWith('/')) head.image = new URL(head.image, `${origin}/`).href;
+    return Object.keys(head).length ? head : undefined;
+}
+
+function publicFiles(publicDir) {
+    if (publicDir === undefined) return [];
+    const source = path.resolve(publicDir);
+    const files = [];
+    const visit = (directory, relative = '') => {
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+            const entryPath = path.join(directory, entry.name);
+            const entryRelative = path.join(relative, entry.name);
+            if (entry.isSymbolicLink()) throw new TypeError(`Site publicDir cannot contain links: ${entryPath}`);
+            if (entry.isDirectory()) {
+                visit(entryPath, entryRelative);
+                continue;
+            }
+            /* istanbul ignore else -- Windows cannot create a directory-contained special file for this guard. */
+            if (entry.isFile()) {
+                files.push({ source: entryPath, relative: entryRelative });
+                continue;
+            }
+            /* istanbul ignore next */
+            throw new TypeError(`Site publicDir can contain only files and directories: ${entryPath}`);
+        }
+    };
+    const details = fs.lstatSync(source);
+    if (details.isSymbolicLink() || !details.isDirectory()) throw new TypeError('Site publicDir must be a directory, not a link.');
+    visit(source);
+    return files;
+}
+
+function outputKey(file) {
+    return file.replaceAll('\\', '/').toLowerCase();
+}
+
+function rejectCollisions(files, occupied = []) {
+    const seen = new Set(occupied.map(outputKey));
+    for (const file of files) {
+        const key = outputKey(file);
+        if (seen.has(key)) throw new TypeError(`Site output paths collide: ${file}`);
+        seen.add(key);
+    }
+}
+
+function rejectOutputLinks(outDir) {
+    if (!fs.existsSync(outDir)) return;
+    const visit = directory => {
+        const details = fs.lstatSync(directory);
+        if (details.isSymbolicLink()) throw new TypeError(`Site outDir cannot contain links: ${directory}`);
+        if (!details.isDirectory()) return;
+        for (const name of fs.readdirSync(directory)) visit(path.join(directory, name));
+    };
+    visit(outDir);
+}
+
+function merge(directory, outDir) {
+    rejectOutputLinks(outDir);
+    for (const entry of publicFiles(directory)) {
+        const destination = path.join(outDir, entry.relative);
+        fs.mkdirSync(path.dirname(destination), { recursive: true });
+        fs.copyFileSync(entry.source, destination);
+    }
+}
+
+function defineSite(options = {}) {
+    const siteRoot = decoratorDirectory();
+    plainObject(options, 'Site options');
+    const allowed = new Set(['origin', 'css', 'head', 'cache', 'layout']);
+    const unknown = Object.keys(options).find(name => !allowed.has(name));
+    if (unknown) throw new TypeError(`Unknown site option: ${unknown}.`);
+    const origin = siteOrigin(options.origin);
+    const sharedCss = files(options.css, 'Site css');
+    const defaultHead = options.head === undefined ? {} : Object.freeze({ ...plainObject(options.head, 'Site head') });
+    const defaultCache = pageCache(options.cache, false);
+    const defaultLayout = options.layout;
+    if (defaultLayout !== undefined && typeof defaultLayout !== 'function') throw new TypeError('Site layout must be a function.');
+    pageHead(resolveHead(origin, '/', defaultHead));
+
+    const decorate = (route, pageOptions = {}) => {
+        plainObject(pageOptions, 'Site page options');
+        if (pageOptions.live !== undefined && pageOptions.live !== false) {
+            throw new TypeError('Site pages must use live: false.');
+        }
+        if (pageOptions.head !== undefined) plainObject(pageOptions.head, 'Page head');
+        const css = [...new Set([...sharedCss, ...files(pageOptions.css, 'Page css')])];
+        const decorator = page(route, {
+            ...pageOptions,
+            live: false,
+            ...(css.length && { css }),
+            head: resolveHead(origin, route, defaultHead, pageOptions.head),
+            cache: pageOptions.cache === undefined ? defaultCache : pageOptions.cache,
+            layout: pageOptions.layout === undefined ? defaultLayout : pageOptions.layout,
+        });
+        return PageClass => {
+            decorator(PageClass);
+            const pageRoot = getPageTemplateRoot(PageClass);
+            const shared = new Set(sharedCss);
+            setPageStylesheetRoots(PageClass, css.map(file => shared.has(file) ? siteRoot : pageRoot));
+            return PageClass;
+        };
+    };
+
+    const exportSite = async (pageOrPages, exportOptions = {}) => {
+        plainObject(exportOptions, 'Site export options');
+        const { publicDir, ...staticOptions } = exportOptions;
+        if (typeof staticOptions.outDir !== 'string' || !staticOptions.outDir) {
+            throw new TypeError('Site export requires a non-empty outDir.');
+        }
+        if (publicDir !== undefined && (typeof publicDir !== 'string' || !publicDir)) {
+            throw new TypeError('Site publicDir must be a non-empty path.');
+        }
+        const outDir = path.resolve(staticOptions.outDir);
+        const source = publicDir === undefined ? undefined : path.resolve(publicDir);
+        if (source && (source === outDir || outDir.startsWith(`${source}${path.sep}`))) {
+            throw new TypeError('Site outDir cannot be the publicDir or one of its descendants.');
+        }
+        const plannedPublic = publicFiles(publicDir);
+        rejectCollisions(plannedPublic.map(entry => entry.relative));
+        const staging = fs.mkdtempSync(path.join(os.tmpdir(), 'redweb-site-'));
+        try {
+            for (const entry of plannedPublic) {
+                const destination = path.join(staging, entry.relative);
+                fs.mkdirSync(path.dirname(destination), { recursive: true });
+                fs.copyFileSync(entry.source, destination);
+            }
+            const staged = await exportStatic(pageOrPages, { ...staticOptions, outDir: staging });
+            const generated = [...staged.pages, ...staged.assets].map(file => path.relative(staging, file));
+            rejectCollisions(plannedPublic.map(entry => entry.relative), generated);
+            merge(staging, outDir);
+            const destination = file => path.join(outDir, path.relative(staging, file));
+            const publicAssets = plannedPublic.map(entry => path.join(outDir, entry.relative));
+            return Object.freeze({
+                pages: Object.freeze(staged.pages.map(destination)),
+                assets: Object.freeze([...new Set([...staged.assets.map(destination), ...publicAssets])]),
+            });
+        } finally {
+            fs.rmSync(staging, { recursive: true, force: true });
+        }
+    };
+
+    return Object.freeze({ page: decorate, export: exportSite });
+}
+
+module.exports = { defineSite };

package/src/htmx/TemplateRenderer.js

@@ -0,0 +1,231 @@
+const { escapeHtml, isHtml, renderValue } = require('./Html');
+const {
+    RAW_TEXT,
+    closingTag,
+    isHtmlSpace,
+    isNonStartMarkup,
+    openingTag,
+    rawClosingTag,
+    tagEnd,
+} = require('./HtmlSyntax');
+
+const BINDING = /{{\s*([A-Za-z_$][\w$]*)\s*}}/g;
+const ATTRIBUTE_BINDING = /{{\s*[A-Za-z_$][\w$]*\s*}}/;
+const NAME = /^[A-Za-z_$][\w$]*$/;
+const DIRECTIVES = new Set(['data-rw-state', 'data-rw-html', 'rw-each']);
+const COMPONENT_DIRECTIVES = new Set(['data-rw-component', 'data-rw-state', 'rw-bind', 'rw-click', 'rw-submit']);
+
+function attributes(tag, nameEnd, tracked = DIRECTIVES) {
+    const found = new Map();
+    let position = nameEnd;
+    while (position < tag.length - 1) {
+        while (isHtmlSpace(tag[position])) position += 1;
+        if (tag[position] === '>' || (tag[position] === '/' && tag[position + 1] === '>')) break;
+        const start = position;
+        while (position < tag.length && !/[ \t\n\f\r=/>]/.test(tag[position])) position += 1;
+        if (start === position) throw new Error('Malformed HTML attribute.');
+        const name = tag.slice(start, position).toLowerCase();
+        while (isHtmlSpace(tag[position])) position += 1;
+        let value = null;
+        if (tag[position] === '=') {
+            position += 1;
+            while (isHtmlSpace(tag[position])) position += 1;
+            const quote = tag[position];
+            if (quote === '"' || quote === "'") {
+                const valueStart = ++position;
+                while (position < tag.length && tag[position] !== quote) position += 1;
+                value = tag.slice(valueStart, position++);
+            } else {
+                const valueStart = position;
+                while (position < tag.length && !/[ \t\n\f\r>]/.test(tag[position])) position += 1;
+                value = tag.slice(valueStart, position);
+            }
+        }
+        if (value && ATTRIBUTE_BINDING.test(value)) {
+            throw new TypeError('Template bindings are only allowed in element text.');
+        }
+        if (tracked.has(name)) {
+            if (found.has(name)) throw new Error(`Duplicate Live HTML directive "${name}".`);
+            found.set(name, value);
+        }
+    }
+    return found;
+}
+
+class TemplateRenderer {
+    constructor(source, page, collection, reactive) {
+        this.source = source;
+        this.page = page;
+        this.collection = collection;
+        this.reactive = reactive;
+        this.position = 0;
+        this.output = '';
+    }
+
+    render() {
+        while (this.position < this.source.length) {
+            if (this.source.startsWith('<!--', this.position)) this.comment();
+            else if (this.source[this.position] === '<') this.markup();
+            else this.text();
+        }
+        return this.output;
+    }
+
+    comment() {
+        const end = this.source.indexOf('-->', this.position + 4);
+        const next = end < 0 ? this.source.length : end + 3;
+        this.output += this.source.slice(this.position, next);
+        this.position = next;
+    }
+
+    markup() {
+        const parsed = this.startTag();
+        if (!parsed) {
+            const recognizedMarkup = isNonStartMarkup(this.source, this.position);
+            const recognizedStart = /[A-Za-z]/.test(this.source[this.position + 1]);
+            const beginsMarkup = recognizedMarkup || recognizedStart;
+            const end = beginsMarkup ? this.tagEnd(this.position + 1) : -1;
+            if (beginsMarkup && end < 0) {
+                this.output += this.source.slice(this.position);
+                this.position = this.source.length;
+                return;
+            }
+            const next = end < 0 ? this.position + 1 : end + 1;
+            this.output += this.source.slice(this.position, next);
+            this.position = next;
+            return;
+        }
+        this.position = parsed.end;
+        if (RAW_TEXT.has(parsed.name)) {
+            if ([...parsed.attributes.keys()].some(name => DIRECTIVES.has(name))) {
+                throw new Error('Live HTML directives are not allowed on raw-text elements.');
+            }
+            const close = parsed.name === 'plaintext' ? null : rawClosingTag(this.source, parsed.name, this.position);
+            const next = close ? close.end : this.source.length;
+            this.output += this.source.slice(parsed.start, next);
+            this.position = next;
+            return;
+        }
+        const each = parsed.attributes.get('rw-each');
+        const state = parsed.attributes.get('data-rw-state');
+        const hasEach = parsed.attributes.has('rw-each');
+        const hasState = parsed.attributes.has('data-rw-state');
+        const hasHtml = parsed.attributes.has('data-rw-html');
+        if (hasHtml && parsed.attributes.get('data-rw-html') !== null) {
+            throw new Error('data-rw-html must be a boolean attribute.');
+        }
+        if (hasHtml && !hasEach && !hasState) {
+            throw new Error('data-rw-html requires data-rw-state or rw-each.');
+        }
+        if (!hasEach && !hasState) {
+            this.output += parsed.source;
+            return;
+        }
+        if (hasEach && !NAME.test(each || '')) throw new Error('rw-each requires a valid state name.');
+        if (hasState && !NAME.test(state || '')) throw new Error('data-rw-state requires a valid state name.');
+        if (hasEach && hasState && each !== state) {
+            throw new Error(`Page collection "${each}" conflicts with state binding "${state}".`);
+        }
+        const name = each || state;
+        if (!(name in this.page)) throw new Error(hasEach ? `Unknown page collection "${name}".` : `Unknown page binding "${name}".`);
+        const closing = this.emptyClosing(parsed.name);
+        const value = hasEach ? this.collection(this.page, name, this.page[name]) : renderValue(this.page[name]);
+        const html = hasEach || isHtml(this.page[name]);
+        let opening = parsed.source;
+        if (!hasState) opening = opening.replace(/\/?>(?=$)/, ` data-rw-state="${name}"$&`);
+        if (html && !hasHtml) opening = opening.replace(/\/?>(?=$)/, ' data-rw-html$&');
+        this.output += opening + value + closing.source;
+        this.position = closing.end;
+    }
+
+    startTag() {
+        const start = this.position;
+        let position = start + 1;
+        if (!/[A-Za-z]/.test(this.source[position] || '')) return null;
+        while (/[A-Za-z0-9:_-]/.test(this.source[position] || '')) position += 1;
+        const name = this.source.slice(start + 1, position).toLowerCase();
+        const end = this.tagEnd(position);
+        if (end < 0) return null;
+        const source = this.source.slice(start, end + 1);
+        return { start, end: end + 1, name, source, attributes: attributes(source, position - start) };
+    }
+
+    tagEnd(position) {
+        return tagEnd(this.source, position);
+    }
+
+    emptyClosing(name) {
+        const contentStart = this.position;
+        while (this.position < this.source.length && isHtmlSpace(this.source[this.position])) this.position += 1;
+        const close = new RegExp(`^<\\/${name}[ \\t\\n\\f\\r]*>`, 'i').exec(this.source.slice(this.position));
+        if (!close) throw new Error(`Live HTML binding on <${name}> requires an empty container.`);
+        return {
+            source: this.source.slice(contentStart, this.position) + close[0],
+            end: this.position + close[0].length,
+        };
+    }
+
+    text() {
+        const end = this.source.indexOf('<', this.position);
+        const next = end < 0 ? this.source.length : end;
+        const text = this.source.slice(this.position, next).replace(BINDING, (_match, name) => {
+            if (!(name in this.page)) throw new Error(`Unknown page binding "${name}".`);
+            const value = this.page[name];
+            if (!this.reactive) return renderValue(value);
+            return `<span data-rw-state="${name}"${isHtml(value) ? ' data-rw-html' : ''}>${renderValue(value)}</span>`;
+        });
+        this.output += text;
+        this.position = next;
+    }
+}
+
+TemplateRenderer.closingTag = closingTag;
+TemplateRenderer.openingTag = openingTag;
+TemplateRenderer.component = (source, id) => {
+    let output = '';
+    let position = 0;
+    while (position < source.length) {
+        const start = source.indexOf('<', position);
+        if (start < 0) return output + source.slice(position);
+        output += source.slice(position, start);
+        if (source.startsWith('<!--', start)) {
+            const commentEnd = source.indexOf('-->', start + 4);
+            const next = commentEnd < 0 ? source.length : commentEnd + 3;
+            output += source.slice(start, next);
+            position = next;
+            continue;
+        }
+        if (isNonStartMarkup(source, start)) {
+            const end = tagEnd(source, start + 1);
+            if (end < 0) return output + source.slice(start);
+            output += source.slice(start, end + 1);
+            position = end + 1;
+            continue;
+        }
+        const opening = /^<([A-Za-z][\w:-]*)/.exec(source.slice(start));
+        if (!opening) {
+            output += '<';
+            position = start + 1;
+            continue;
+        }
+        const end = tagEnd(source, start + opening[0].length);
+        if (end < 0) return output + source.slice(start);
+        const tag = source.slice(start, end + 1);
+        const found = attributes(tag, opening[0].length, COMPONENT_DIRECTIVES);
+        const scoped = [...COMPONENT_DIRECTIVES].some(name => name !== 'data-rw-component' && found.has(name));
+        output += scoped && !found.has('data-rw-component')
+            ? tag.replace(/\/?>(?=$)/, ` data-rw-component="${escapeHtml(id)}"$&`)
+            : tag;
+        position = end + 1;
+        const name = opening[1].toLowerCase();
+        if (RAW_TEXT.has(name)) {
+            const close = name === 'plaintext' ? null : rawClosingTag(source, name, position);
+            const next = close ? close.end : source.length;
+            output += source.slice(position, next);
+            position = next;
+        }
+    }
+    return output;
+};
+
+module.exports = TemplateRenderer;

package/src/htmx/browserRuntime.js

@@ -0,0 +1,97 @@
+function browserRuntime(clientPath) {
+    return `import { RedwebClient } from ${JSON.stringify(clientPath)};
+
+const configNode = document.getElementById('__redweb_page');
+const config = JSON.parse(configNode.textContent);
+const client = new RedwebClient(config.socketPath + '?pageId=' + encodeURIComponent(config.pageId), {
+    baseUrl: window.location.href,
+    version: config.version,
+    reconnect: { enabled: true, maxAttempts: 8 },
+    maxQueueSize: 32
+});
+
+const emit = (type, detail) => document.dispatchEvent(new CustomEvent(type, { detail }));
+let stateTargets = new Map();
+const componentOf = node => node.closest('[data-rw-component]')?.getAttribute('data-rw-component') || null;
+const stateKey = (component, name) => (component || '') + '\\0' + name;
+const indexState = () => {
+    stateTargets = new Map();
+    document.querySelectorAll('[data-rw-state]').forEach(node => {
+        const name = node.getAttribute('data-rw-state');
+        const key = stateKey(componentOf(node), name);
+        const targets = stateTargets.get(key) || [];
+        targets.push(node);
+        stateTargets.set(key, targets);
+    });
+};
+const named = (attribute, name, component) => attribute === 'data-rw-state'
+    ? (stateTargets.get(stateKey(component, name)) || [])
+    : [...document.querySelectorAll('[' + attribute + ']')].filter(node =>
+        node.getAttribute(attribute) === name && componentOf(node) === component);
+indexState();
+
+client.on('redweb:state', message => {
+    const update = message.payload;
+    const component = update.component || null;
+    named('data-rw-state', update.name, component).forEach(node => {
+        if (update.html) {
+            node.innerHTML = update.value;
+            indexState();
+        }
+        else node.textContent = update.value;
+    });
+    named('rw-bind', update.name, component).forEach(node => {
+        if (node.type === 'checkbox') node.checked = update.value === true || update.value === 'true';
+        else if (node.value !== update.value) node.value = update.value;
+    });
+});
+
+const report = error => emit('redweb:error', error);
+const send = payload => {
+    try { client.send('redweb:html', payload); }
+    catch (error) { report(error); }
+};
+const formValues = form => {
+    const values = {};
+    for (const [name, value] of new FormData(form)) {
+        if (!(name in values)) values[name] = value;
+        else values[name] = Array.isArray(values[name]) ? [...values[name], value] : [values[name], value];
+    }
+    return values;
+};
+
+document.addEventListener('click', event => {
+    const target = event.target.closest('[rw-click]');
+    if (!target) return;
+    event.preventDefault();
+    client.request('redweb:html', {
+        kind: 'action', name: target.getAttribute('rw-click'), component: componentOf(target), args: []
+    }).catch(report);
+});
+
+document.addEventListener('submit', event => {
+    const form = event.target.closest('form[rw-submit]');
+    if (!form) return;
+    event.preventDefault();
+    client.request('redweb:html', {
+        kind: 'action', name: form.getAttribute('rw-submit'), component: componentOf(form), args: [formValues(form)]
+    }).then(() => form.reset()).catch(report);
+});
+
+document.addEventListener('input', event => {
+    const target = event.target.closest('[rw-bind]');
+    if (target) send({
+        kind: 'state',
+        name: target.getAttribute('rw-bind'),
+        component: componentOf(target),
+        value: target.type === 'checkbox' ? target.checked : target.value
+    });
+});
+
+client.onError(report);
+client.onStateChange(state => emit('redweb:connection', state));
+client.connect().catch(report);
+`;
+}
+
+module.exports = browserRuntime;

package/src/htmx/index.js

@@ -0,0 +1,10 @@
+const HtmlRenderer = require('./HtmlRenderer');
+const LiveHtmlServer = require('./LiveHtmlServer');
+const LivePage = require('./LivePage');
+const { attribute, codeBlock, each, html, safeUrl: url } = require('./Html');
+const { action, component, page, state, view } = require('./metadata');
+const { start } = require('./start');
+const { exportStatic } = require('./StaticExporter');
+const { defineSite } = require('./StaticSite');
+
+module.exports = { action, attribute, codeBlock, component, defineSite, each, exportStatic, html, HtmlRenderer, LiveHtmlServer, LivePage, page, start, state, url, view };