@bongo/bongo 0.0.0-stage → 0.1.0

package/bin.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+const { parseArgs } = require('node:util');
+
+let args = process.argv.slice(2);
+// A bare `--host` exposes the server on every interface, as sirv-cli's does.
+args = args.map((arg, i) => (arg === '--host' || arg === '-H') && !/^[^-]/.test(args[i + 1] || '') ? '--host=0.0.0.0' : arg);
+
+try {
+	var { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		allowNegative: true,
+		options: {
+			cwd: { type: 'string', short: 'C', default: '.' },
+			host: { type: 'string', short: 'H' },
+			port: { type: 'string', short: 'p' },
+			minify: { type: 'boolean', short: 'm', default: false },
+			debug: { type: 'boolean', short: 'd', default: false },
+			write: { type: 'boolean', short: 'w', default: false },
+			fresh: { type: 'boolean', short: 'f', default: false },
+			drafts: { type: 'boolean' },
+			version: { type: 'boolean', short: 'v' },
+			help: { type: 'boolean', short: 'h' },
+		},
+	});
+	var port = values.port === undefined ? undefined : Number(values.port);
+	if (port !== undefined && !(Number.isInteger(port) && port > 0 && port < 65536)) {
+		throw new Error(`Invalid --port "${values.port}"; use a port number`);
+	}
+} catch (err) {
+	console.error('ERROR', err.message);
+	process.exit(1);
+}
+
+if (values.version) {
+	const pkg = require('./package.json');
+	console.log(`${pkg.name}, v${pkg.version}`);
+	process.exit(0);
+}
+
+if (values.help) {
+	let output = '';
+	output += '\n  Usage';
+	output += '\n    bongo <command> [options]';
+	output += '\n';
+	output += '\n  Available Commands';
+	output += '\n    build    Build the source directory';
+	output += '\n    dev      Develop with a live-reload server';
+	output += '\n';
+	output += '\n  Options';
+	output += '\n    -C, --cwd        Directory to resolve from  (default .)';
+	output += '\n    -H, --host       Host to bind; bare flag exposes network  (default localhost)';
+	output += '\n    -p, --port       Port to bind  (default 3000)';
+	output += '\n    -m, --minify     Compress built assets  (default false)';
+	output += '\n    -d, --debug      Log each build stage and its time  (default false)';
+	output += '\n    -w, --write      Dev only: also write the output to public/  (default false)';
+	output += '\n    -f, --fresh      Render every page, not only what changed  (default false)';
+	output += '\n        --drafts     Build drafts; --no-drafts leaves them out  (default false; dev true)';
+	output += '\n    -v, --version    Displays current version';
+	output += '\n    -h, --help       Displays this message';
+	output += '\n';
+
+	process.stdout.write(output + '\n');
+	process.exit(0);
+}
+
+(async function () {
+	try {
+		let name = (positionals[0] || '').trim().toLowerCase();
+		if (!name) throw new Error('Missing <command> argument');
+
+		let command = require('.')[name];
+		if (!command) throw new Error(`Unknown "${name}" command`);
+
+		let { cwd, host, minify, debug, write, fresh, drafts } = values;
+		await command({ cwd, host, port, minify, debug, write, fresh, drafts });
+	} catch (err) {
+		console.error('ERROR', err.stack);
+		process.exit(1);
+	}
+})();

package/client.d.ts

@@ -0,0 +1,2 @@
+export type { ClientOptions, BongoEvent, BongoEventDetails } from './src/client/index';
+export { client, navigate, on, off } from './src/client/index';

package/client.js

@@ -0,0 +1 @@
+const e={fade:[`@keyframes bongo-fade-in{from{opacity:0}to{opacity:1}}`,`@keyframes bongo-fade-out{from{opacity:1}to{opacity:0}}`,`::view-transition-old(root){animation-name:bongo-fade-out;animation-duration:.18s}`,`::view-transition-new(root){animation-name:bongo-fade-in;animation-duration:.18s}`].join(``),slide:[`@keyframes bongo-slide-in{from{transform:translateX(16px);opacity:0}to{transform:none;opacity:1}}`,`@keyframes bongo-slide-out{from{transform:none;opacity:1}to{transform:translateX(-16px);opacity:0}}`,`::view-transition-old(root){animation-name:bongo-slide-out;animation-duration:.22s}`,`::view-transition-new(root){animation-name:bongo-slide-in;animation-duration:.22s}`].join(``)};function t(e){if(e===!0)return`fade`;if(e)return e}function n(t){let n=e[t];if(!n||document.querySelector(`style[data-bongo-preset="${t}"]`))return;let r=document.createElement(`style`);r.setAttribute(`data-bongo-preset`,t),r.textContent=n,document.head.appendChild(r)}const r=/* @__PURE__ */ new WeakMap;function i(e){return[...e.head.querySelectorAll(`link[rel~=stylesheet], style`)].filter(e=>!e.closest(`noscript`))}function a(e){let t=`href`in e?e.href:e.textContent;return JSON.stringify([e.localName,t,e.media,e.hasAttribute(`disabled`)])}function o(e,t){return e.hasAttribute(`disabled`)||`href`in e&&!e.getAttribute(`href`)?!1:!e.media||!t||t.matchMedia(e.media).matches}function s(e){for(let t of i(e))r.set(t,a(t))}function c(e,t,n){let s=e.defaultView,c=i(e).filter(e=>r.has(e)),l=/* @__PURE__ */ new Set,u=[],d=[],f=[],p=-1,m=0,h,g=()=>{for(let{el:e}of u){let t=e.sheet;t&&!t.disabled&&(t.disabled=!0,d.push(t))}},_=()=>{g(),m=s?.requestAnimationFrame(_)??0};for(let n of i(t)){let t=a(n),i=c.findIndex((e,n)=>n>p&&r.get(e)===t);if(i!==-1){l.add(h=c[i]),p=i;continue}let d=e.importNode(n,!0);u.push({el:d,id:t}),o(n,s)&&f.push(new Promise(e=>{d.addEventListener(`load`,()=>e(),{once:!0}),d.addEventListener(`error`,()=>e(),{once:!0})}).then(g)),h?h.after(d):c.length?c[0].before(d):e.head.append(d),h=d}return u.length&&_(),{ready:new Promise(e=>{if(!f.length||n.aborted)return e();let t=setTimeout(r,3e3);n.addEventListener(`abort`,r),Promise.all(f).then(r);function r(){clearTimeout(t),n.removeEventListener(`abort`,r),e()}}),commit(){s?.cancelAnimationFrame(m);for(let e of d)e.disabled=!1;for(let{el:e,id:t}of u)r.set(e,t);for(let e of c)l.has(e)||(r.delete(e),e.remove());u=[]},drop(){s?.cancelAnimationFrame(m);for(let{el:e}of u)e.remove();u=[]}}}function l(e,t,n){let r=new URL(n).origin,a=new Set(i(e).map(e=>`href`in e?e.href:``)),s=/* @__PURE__ */ new Set;for(let l of i(t))if(`href`in l&&o(l,e.defaultView)){try{var c=new URL(l.getAttribute(`href`)||``,n)}catch{continue}c.origin===r&&!a.has(c.href)&&s.add(c.href)}return[...s]}const u=/* @__PURE__ */ new Map;function d(e){if(e===!0)return`hover`;if(e)return e}function f(e){let t=u.get(e);if(t){if(Date.now()>t.expires)u.delete(e);else return t.html}}function p(e){if(!e||!e.href||e.hasAttribute(`prefetch:disable`)||e.hasAttribute(`transition:disable`))return!1;let t;try{t=new URL(e.href)}catch{return!1}return!(t.origin!==location.origin||t.href===location.href||f(t.href))}function m(e){if(f(e))return;let t=fetch(e,{headers:{Accept:`text/html`}}).then(e=>{if(!e.ok)throw Error(`prefetch: ${e.status}`);return e.text()}).catch(t=>{throw u.delete(e),t});u.set(e,{html:t,expires:Date.now()+3e4}),t.then(t=>{let n=new DOMParser().parseFromString(t,`text/html`);for(let t of l(document,n,e))fetch(t).then(e=>e.blob()).catch(()=>{})},()=>{})}function h(e){if(!e)return;if(document.addEventListener(`touchstart`,e=>{let t=e.target?.closest?.(`a`);p(t)&&m(t.href)},{capture:!0,passive:!0}),e===`tap`){document.addEventListener(`mousedown`,e=>{let t=e.target?.closest?.(`a`);p(t)&&m(t.href)},!0);return}let t=null;document.addEventListener(`mouseover`,e=>{let n=e.target?.closest?.(`a`);if(t&&t.anchor!==n&&(clearTimeout(t.timer),t=null),!p(n)||t?.anchor===n)return;let r=n;t={anchor:r,timer:setTimeout(()=>{m(r.href),t=null},80)}},!0),document.addEventListener(`mouseout`,e=>{if(!t)return;let n=e.relatedTarget?.closest?.(`a`);t.anchor!==n&&(clearTimeout(t.timer),t=null)},!0)}const g=/* @__PURE__ */ new Map,_=`bongo:live`;let v=!1;const y=/* @__PURE__ */ new Map;function b(e,t){let n=g.get(e);if(n)for(let r of n)try{r(t)}catch(t){console.error(`[bongo] handler for ${e} threw:`,t)}}function x(e,t){let n=g.get(e);return n||g.set(e,n=/* @__PURE__ */ new Set),n.add(t),()=>n.delete(t)}function S(e,t){g.get(e)?.delete(t)}function C(e){return v?v=!1:!(!e.canIntercept||e.hashChange||e.navigationType===`reload`||e.downloadRequest||new URL(e.destination.url).origin!==location.origin||e.sourceElement?.hasAttribute(`transition:disable`))}async function w(e,t){let n=f(e.href);if(n)try{return await n}catch{}let r=await fetch(e.href,{headers:{Accept:`text/html`},signal:t});if(!r.ok)throw Error(`Navigation fetch failed: ${r.status} ${r.statusText}`);return r.text()}function T(e){let t=/* @__PURE__ */ new Map;for(let n of e.querySelectorAll(`[transition\\:persist]`)){let e=n.getAttribute(`transition:persist`)||n.id;e&&t.set(e,n)}return t}function E(e,t){e.title=t.title;let n=T(e),r=e.activeElement,i=[];for(let[e,r]of T(t)){let t=n.get(e);t&&(i.push({el:t,top:t.scrollTop,left:t.scrollLeft}),r.replaceWith(t))}let a=e.getElementById(_);t.getElementById(_)?.remove(),e.body.replaceWith(t.body),a&&e.body.prepend(a);for(let{el:e,top:t,left:n}of i)e.scrollTop=t,e.scrollLeft=n;let o=e.defaultView;o&&r instanceof o.HTMLElement&&r!==e.activeElement&&i.some(({el:e})=>e.contains(r))&&r.focus({preventScroll:!0})}async function D(e,t){let n=e&&document.startViewTransition;if(!n)return t();let r=n.call(document,t);r.ready.catch(()=>{}),r.finished.catch(()=>{}),await r.updateCallbackDone,await r.finished}function O(e){y.set(e.href,{x:window.scrollX,y:window.scrollY})}function k(e,t){if(e.navigationType===`traverse`){let e=y.get(t.href);if(e){window.scrollTo(e.x,e.y);return}window.scrollTo(0,0)}else{if(t.hash){let e=decodeURIComponent(t.hash.slice(1)),n=e&&document.getElementById(e);if(n){n.scrollIntoView();return}}window.scrollTo(0,0)}}function A(){let e=document.getElementById(_);return e||!document.body?e??void 0:(e=document.createElement(`div`),e.id=_,e.setAttribute(`role`,`status`),e.setAttribute(`aria-live`,`polite`),e.style.cssText=`position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0,0,0,0);border:0`,document.body.prepend(e),e)}function j(e){v=e}function M(e={}){let r=globalThis.navigation;if(b(`bongo:ready`,{url:new URL(location.href)}),h(d(e.prefetch)),!r)return;s(document),`scrollRestoration`in history&&(history.scrollRestoration=`manual`);let i=t(e.transitions);i&&n(i),A(),document.addEventListener(`click`,e=>{let t=e.target?.closest?.(`a[transition\\:disable]`);j(!!t)},!0),r.addEventListener(`navigate`,e=>{if(!C(e))return;let t=new URL(location.href),n=new URL(e.destination.url);O(t),e.intercept({async handler(){let{signal:r}=e;try{b(`bongo:navigate`,{to:n,from:t});let a=await w(n,r);if(r.aborted)return;let o=new DOMParser().parseFromString(a,`text/html`);b(`bongo:replace`,{to:n,from:t,doc:o});let s=c(document,o,r);try{if(await s.ready,r.aborted)return;await D(!!i,()=>{r.aborted||(s.commit(),E(document,o),k(e,n),b(`bongo:replaced`,{to:n,from:t}))})}finally{s.drop()}if(r.aborted)return;let l=A();l&&(l.textContent=document.title),b(`bongo:navigated`,{to:n,from:t})}catch(e){if(r.aborted)return;throw b(`bongo:error`,{to:n,error:e instanceof Error?e:Error(String(e))}),e}}})})}async function N(e,t={}){let n=new URL(e,location.href),r=globalThis.navigation;if(r){let{committed:e,finished:i}=r.navigate(n.href,{history:t.replace?`replace`:`push`});e?.catch(()=>{});try{await i}catch(e){if(e instanceof DOMException&&e.name===`AbortError`)return;throw e}}else location[t.replace?`replace`:`assign`](n.href)}export{M as client,N as navigate,S as off,x as on};

package/index.d.ts

@@ -0,0 +1,305 @@
+import type { Args, Blocks } from 'tempura';
+
+type Promisable<T> = Promise<T> | T;
+
+export interface Argv {
+	cwd: string;
+	dev?: boolean;
+	minify?: boolean;
+	/** `bongo dev` only: also write the output to `public/`. @default false */
+	write?: boolean;
+	/** Render every page, and ignore what the last build kept. @default false */
+	fresh?: boolean;
+	/** Build each draft: a page with `draft: true`, or a `date` after the build starts, unless it has `draft: false`. @default false, and true for `bongo dev` */
+	drafts?: boolean;
+	// added via normalize
+	src?: string;
+	dest?: string;
+	assets?: string;
+	content?: string;
+	data?: string;
+	partials?: string;
+	layouts?: string;
+	debug?: boolean;
+	port?: number;
+	host?: string;
+}
+
+export type Loader = (
+	file: string,
+	content: Uint8Array | string,
+	utils: Loader.Utilities,
+) => Promisable<Loader.Result>;
+
+export namespace Loader {
+	type Metadata = Record<string, unknown>;
+
+	// Raw source map (v3). Loaders may also return the map as a JSON string —
+	// consumers (rolldown, lightningcss) accept either.
+	interface SourceMapObject {
+		version: number;
+		sources: (string | null)[];
+		mappings: string;
+		names?: string[];
+		file?: string;
+		sourceRoot?: string;
+		sourcesContent?: (string | null)[];
+	}
+
+	type SourceMap = string | SourceMapObject;
+
+	/** A heading of the HTML that a loader writes. Without `html`, bongo uses the escaped `text`. */
+	type Heading = Omit<Template.Heading, 'html'> & { html?: string };
+
+	interface Result {
+		filename: string;
+		content: Uint8Array | string;
+		metadata?: Loader.Metadata;
+		sourcemap?: Loader.SourceMap | null;
+		/** The headings of `content`, in document order. They become `$page.headings`. */
+		headings?: Loader.Heading[];
+	}
+
+	interface Utilities {
+		decode(input: Uint8Array): string;
+		render(partial: string, ...args: any[]): Promisable<string>;
+		frontmatter(content: string): {
+			offset: number;
+			value: Metadata;
+		};
+		/**
+		 * Parse element attributes as data; values are never evaluated.
+		 * @example utils.attrs('name="Luke" count=2 tags=[a, b] featured') //=> { name: 'Luke', count: 2, tags: ['a', 'b'], featured: true }
+		 */
+		attrs(input: string): Record<string, unknown>;
+	}
+}
+
+export type { Args, Blocks };
+
+export namespace Template {
+	// TODO: import from tempura
+	type Compiler<T extends Args = Args> = (data: T, blocks?: Blocks) => Promise<string> | string;
+	type Partials = Blocks;
+
+	interface Menu {
+		name: string;
+		href: string;
+	}
+
+	interface Site {
+		url: string;
+		lang: string;
+		title: string;
+		description?: string;
+		menu?: {
+			[name: string]: Menu;
+		};
+	}
+
+	/**
+	 * A heading of a page, as its loader reports it. `.html` and `.hbs` content has none.
+	 * @example { level: 2, id: 'install', text: 'Install bongo', html: 'Install <code>bongo</code>' }
+	 */
+	type Heading = {
+		level: number;
+		/** The anchor that the heading has in the page HTML. */
+		id: string;
+		/** Plain text, entities resolved. Escape it for HTML. */
+		text: string;
+		/** The inner HTML, such as inline code. */
+		html: string;
+	};
+
+	// TODO: lastmodified value
+	// TODO: file.abs path
+	// TODO: file.rel path
+	interface Page {
+		url: string;
+		path: string;
+		title: string;
+		summary: string;
+		section: string;
+		tags: string[];
+		headings: Heading[];
+		params: Params;
+		/** Whether the page is a draft: it has `draft: true`, or a `date` after the build started, unless it has `draft: false`. Only a build with drafts has one. */
+		draft: boolean;
+		content: string;
+		scripts: string;
+		styles: string;
+	}
+
+	type PageInfo = {
+		path: string;    // URL path (e.g. '/blog/post-1/')
+		url: string;     // absolute URL (e.g. 'https://example.com/blog/post-1/')
+		title: string;
+		summary: string;
+		section: string; // directory prefix (e.g. 'blog', '' for root)
+		tags: string[];  // parsed from frontmatter
+		headings: Heading[]; // from the page's loader; empty for .html and .hbs content
+		params: Params;  // full frontmatter
+		/** Whether the page is a draft: it has `draft: true`, or a `date` after the build started, unless it has `draft: false`. Only a build with drafts has one. */
+		draft: boolean;
+		/** The `<bongo:alternate>` elements of the page, as `{ type: href }`, such as `{ 'text/markdown': '/config.md' }`. Only output files and data modules see it, since a page's elements are found after its layouts render. */
+		alternates?: Record<string, string>;
+	};
+
+	type TagEntry = {
+		tag: string;
+		pages: PageInfo[];
+	};
+
+	/** `$assets` in layouts, partials, and `.hbs` content. */
+	type Assets = {
+		/**
+		 * Read a file of `assets/`; with an encoding, as text.
+		 * @example {{{ await $assets.load('img/logo.svg', 'utf8') }}}
+		 */
+		load(filename: string, encoding?: BufferEncoding): Promise<string | Buffer>;
+		/**
+		 * Draw a partial as an image, with the values of the current page, and return the URL path of the image.
+		 * The extension of `output` picks the format: `.svg` and `.png` work everywhere, `.jpg` and `.webp` need Bun.
+		 * Without `output`, the image is a PNG named from its partial and content. Needs `satori`, and `@resvg/resvg-js` for all but SVG.
+		 * @example {{#var card = await $assets.render('og/card', 'og/' + $utils.slug($page.title) + '.png')}}
+		 */
+		render(template: string, output?: string, options?: Render): Promise<string>;
+	};
+
+	type Render = {
+		/** @default 1200 */
+		width?: number;
+		/** @default 630 */
+		height?: number;
+		/** Values for the partial, as the attributes of `{{#partial}}` are. */
+		args?: Record<string, unknown>;
+	};
+
+	interface Params {
+		[name: string]: unknown;
+	}
+}
+
+interface Helpers {
+  [name: string]: Function | Promise<any> | Helpers;
+}
+
+export namespace Build {
+	/** A content file that a build writes: a page, or an output file such as `sitemap.xml.hbs`. */
+	type File = {
+		/** The URL path, like `/blog/post/` for a page or `/blog/index.xml` for an output file. */
+		path: string;
+		/** The frontmatter. */
+		params: Template.Params;
+	};
+
+	type Context = File & {
+		kind: 'page' | 'output';
+		/** Every output file of the build, sorted by path. */
+		outputs: File[];
+		/** The config, with its plugins merged. */
+		config: Required<Config>;
+	};
+
+	/**
+	 * Change a rendered page or output file before it is written. Pages arrive with their final asset URLs.
+	 * @example const year: Build.Transform = (text, ctx) => ctx.kind === 'page' ? text.replace('{year}', '2026') : text;
+	 */
+	type Transform = (text: string, ctx: Context) => Promisable<string>;
+
+	type Hooks = {
+		/** Plugins run first, in order, then the config's own; each gets the text the last one returned. */
+		transform?: Transform;
+	};
+
+	/**
+	 * What the default export of a data module, such as `content/search.json.ts`, receives when it is a function.
+	 * @example export default ({ $pages }: Build.Data) => $pages.map(page => ({ title: page.title, path: page.path }));
+	 */
+	type Data = {
+		$site: Template.Site;
+		$pages: Template.PageInfo[];
+		/** The pages in the module's own folder. */
+		$section: Template.PageInfo[];
+		$tags: Template.TagEntry[];
+		$data: Record<string, unknown>;
+		$utils: NonNullable<Config['$utils']>;
+	};
+}
+
+export namespace Images {
+	type Format = 'avif' | 'webp' | 'jpeg' | 'png';
+
+	type Options = {
+		/** Output widths in pixels. A source is never enlarged: wider ones become its own width. @default [640, 960, 1280, 1920, 2880] */
+		widths?: number[];
+		/** Output formats, best first; `original` is the format of each source. Content images use only the first; the last is the `<img>` fallback of `<bongo:image>`. `avif` needs an Apple Silicon M3+ Mac or Windows. @default ['webp', 'original'] */
+		formats?: (Format | 'original')[];
+		/** Encoder quality from 1 to 100, for all lossy formats or per format. PNG is always lossless. @default { avif: 50, webp: 80, jpeg: 80 } */
+		quality?: number | Partial<Record<Format, number>>;
+		/** The `sizes` of images that do not set one. A leading `auto` applies only to lazy images. @default 'auto, 100vw' */
+		sizes?: string;
+		/** Process `<img>` elements in content that have a relative `src`. @default true */
+		content?: boolean;
+		/** Delete cached images and renders that no build has used for this many days, checked at most once a day; `false` keeps them all. @default 30 */
+		prune?: number | false;
+	};
+}
+
+export interface Config {
+	$site: Template.Site;
+	// bongo provides these built-ins; a config may override or extend them
+	$utils?: Helpers & {
+		truncate?(text: string, length: number): string;
+		countwords?(text: string): number;
+		slug?(text: string): string;
+		excerpt?(html: string, length: number): string;
+		minutes?(text: string, wpm?: number): number;
+		json?(value: unknown): string;
+		url?: Helpers & {
+			abs?(to: string, fro?: string): string;
+			path?(to: string, fro?: string): string;
+			/**
+			 * The path of a page plus an extension, as `<bongo:alternate>` names its file.
+			 * @example $utils.url.ext('/config/', 'md') //=> '/config.md'
+			 */
+			ext?(path: string, ext: string): string;
+		};
+		date?: Helpers & {
+			format?(value: string|number|Date, options?: Intl.DateTimeFormatOptions): string;
+		};
+	};
+	$loaders?: {
+		[extension: string]: Loader;
+	};
+	$partials?: Template.Partials;
+	$build?: {
+		/**
+		 * The browsers to build for, as a browserslist query or a list of queries. It sets the CSS prefixes and the syntax that CSS and JavaScript are lowered to.
+		 * @default 'defaults'
+		 * @example $build: { target: ['chrome >= 120', 'safari >= 17', 'firefox >= 121'] }
+		 */
+		target?: string | string[];
+	};
+	$images?: Images.Options;
+	$hooks?: Build.Hooks;
+	plugins?: Partial<Config>[];
+}
+
+/**
+ * Run one build, as `bongo build` does. Resolves when the site is written.
+ * @example await build({ cwd: 'site', minify: true });
+ */
+export function build(argv: Argv): Promise<void>;
+
+/**
+ * Start the dev server, as `bongo dev` does. Resolves after the first build; the server keeps running.
+ * @example await dev({ cwd: 'site', port: 3000 });
+ */
+export function dev(argv: Argv): Promise<void>;
+
+/**
+ * Return the config as it is, typed as `Config`, for a JavaScript config file.
+ * @example export default define({ $site: { title: 'My Site', url: 'https://example.com/', lang: 'en' } });
+ */
+export function define(config: Config): Config;