mechanica-shared 2.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 den59k
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,10 @@
+# mechanica-shared
+
+Internal support package for [mechanica](https://www.npmjs.com/package/mechanica) — DOM-free types, the field-type registry, schema/default helpers, the page-generation (SSG) core, and the `.page.md` page-format codec.
+
+You normally don't install this directly; it comes with `mechanica`. It is published separately so server-side renderers can consume it without the editor/runtime.
+
+Entry points:
+
+- `mechanica-shared` — types, field registry, schema helpers, `generatePage` and the `{{ }}` HTML templating engine. DOM-free by contract.
+- `mechanica-shared/page-format` — `parsePage` / `serializePage` for the `.page.md` on-disk format. A separate entry point on purpose: it pulls in a YAML parser that must never reach a client bundle.

package/dist/index.js

@@ -0,0 +1,476 @@
+import { registerAlias } from "compact-json-schema";
+//#region src/fields.ts
+/** The field types registered by default. */
+var builtinFields = [
+	{
+		name: "image",
+		schema: {
+			type: "object",
+			format: "image",
+			properties: {
+				src: "string",
+				previewSrc: "string?"
+			}
+		},
+		default: () => ({ src: "" })
+	},
+	{
+		name: "file",
+		schema: {
+			type: "object",
+			format: "file",
+			properties: { src: "string" }
+		},
+		default: () => ({ src: "" })
+	},
+	{
+		name: "text",
+		schema: {
+			type: "string",
+			format: "text"
+		}
+	},
+	{
+		name: "color",
+		schema: {
+			type: "string",
+			format: "color"
+		}
+	},
+	{
+		name: "smartLink",
+		schema: {
+			type: "object",
+			format: "smartLink",
+			properties: {
+				url: "string",
+				title: "string",
+				external: "boolean",
+				openNewTab: "boolean"
+			}
+		}
+	},
+	{
+		name: "multiselect",
+		schema: {
+			type: "array",
+			format: "multiselect",
+			items: "string"
+		}
+	},
+	{
+		name: "richText",
+		schema: {
+			type: "array",
+			format: "richText",
+			items: {
+				type: "object",
+				properties: {
+					text: "string",
+					type: "string?",
+					styles: "object?"
+				}
+			}
+		},
+		default: () => [{ text: "" }]
+	}
+];
+var fieldDefaults = /* @__PURE__ */ new Map();
+var registered = false;
+/**
+* Register field types as compact-json-schema aliases and record their default
+* values. Call once per runtime before unfolding any block/data schema.
+*
+* @param register Override the alias registrar (defaults to compact-json-schema's).
+* @param fields   Field set to register (defaults to {@link builtinFields}).
+*/
+function registerFieldSchemas(register = registerAlias, fields = builtinFields) {
+	for (const field of fields) {
+		register(field.name, field.schema);
+		if (field.default !== void 0) fieldDefaults.set(field.name, field.default);
+	}
+	registered = true;
+}
+/** Resolve the default value for a registered field format, or `undefined`. */
+function getFieldDefault(format) {
+	const value = fieldDefaults.get(format);
+	return typeof value === "function" ? value() : value;
+}
+/** Whether {@link registerFieldSchemas} has run in this runtime. */
+function areFieldSchemasRegistered() {
+	return registered;
+}
+//#endregion
+//#region src/schema.ts
+/**
+* Compute the default value for a (compact-unfolded) schema node, consulting the
+* field registry for format-specific defaults (e.g. `image`, `richText`).
+*/
+function getDefaultValue(schema) {
+	if (schema.default !== void 0) return schema.default;
+	if (schema.nullable) return null;
+	if (schema.format) {
+		const fieldDefault = getFieldDefault(schema.format);
+		if (fieldDefault !== void 0) return fieldDefault;
+	}
+	if (schema.type === "number" || schema.type === "integer") return 0;
+	if (schema.type === "object") {
+		if (!schema.properties) return {};
+		return Object.fromEntries(Object.entries(schema.properties).map(([key, value]) => {
+			if (!schema.required?.includes(key)) return [key, void 0];
+			return [key, getDefaultValue(value)];
+		}));
+	}
+	if (schema.type === "array") return [];
+	if (schema.type === "boolean") return false;
+	return "";
+}
+/**
+* Fill missing values in `state` with schema defaults, recursing into objects.
+* Returns `state` when present, otherwise a freshly generated default.
+*/
+function passDefaultValue(state, schema) {
+	if (!schema) return state;
+	if (schema.type === "object" && state) for (const key in schema.properties) {
+		if (!(key in state) && !schema.required?.includes(key)) continue;
+		state[key] = passDefaultValue(state[key], schema.properties[key]);
+	}
+	return state ?? getDefaultValue(schema);
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Deep-merge `patch` over `base`: plain objects merge, arrays and scalars replace. */
+function mergePreviewData(base, patch) {
+	const out = { ...base };
+	for (const [key, value] of Object.entries(patch)) {
+		const current = out[key];
+		out[key] = isPlainObject(current) && isPlainObject(value) ? mergePreviewData(current, value) : value;
+	}
+	return out;
+}
+/**
+* Resolve the data a block should render with outside a page: schema defaults,
+* overlaid with the block's authored `previewData`, overlaid with per-call
+* overrides (e.g. the `?data=` payload of the preview route).
+*
+* @param props Unfolded (JSON-schema shaped) props schema, as on `Block.props`.
+*/
+function buildPreviewData(props, previewData, overrides) {
+	const defaults = props ? getDefaultValue(props) : {};
+	return mergePreviewData(mergePreviewData(isPlainObject(defaults) ? defaults : {}, previewData ?? {}), overrides ?? {});
+}
+/** Depth-first walk over a content tree, including array and named-slot children. */
+function walkTree(blocks, callback) {
+	for (const block of blocks) {
+		callback(block);
+		if (!block.children) continue;
+		if (Array.isArray(block.children)) walkTree(block.children, callback);
+		else for (const list of Object.values(block.children)) walkTree(list, callback);
+	}
+}
+/** Walk a value alongside its schema, invoking `callback` for each described node. */
+function walkSchema(obj, schema, callback) {
+	if (schema.type === "object" && schema.properties && obj) for (const [key, childSchema] of Object.entries(schema.properties)) {
+		const isRequired = schema.required?.includes(key) ?? false;
+		callback(obj[key], childSchema, key, obj, isRequired);
+		const childType = childSchema.type;
+		if (childType === "array" || childType === "object") walkSchema(obj[key], childSchema, callback);
+	}
+	if (schema.type === "array" && schema.items && obj) for (const value of obj) {
+		callback(value, schema.items);
+		if (schema.items.type === "array" || schema.items.type === "object") walkSchema(value, schema.items, callback);
+	}
+}
+/** Resolve a dotted path within a data object (`'postMeta.date'`). */
+function getValueByPath(data, path) {
+	let value = data;
+	for (const key of path.split(".")) {
+		if (value == null) return value;
+		value = value[key];
+	}
+	return value;
+}
+//#endregion
+//#region src/generate-page.ts
+var HTML_ESCAPES = {
+	"&": "&",
+	"<": "&lt;",
+	">": "&gt;",
+	"\"": "&quot;"
+};
+/** Escape a templated value so it's safe in element text and attribute values. */
+function escapeHtml(value) {
+	return value.replace(/[&<>"]/g, (char) => HTML_ESCAPES[char]);
+}
+/**
+* Substitute `{{ a.b }}` placeholders in an HTML string with data values. Used to
+* template the `<head>` (title, meta, Open Graph, …) from `defineData` values and
+* the current page. Resolved values are HTML-escaped.
+*/
+function passDataToHTML(html, data) {
+	return html.replace(/\{\{(.+?)\}\}/g, (_match, expr) => escapeHtml(String(getValueByPath(data, expr.trim()) ?? "")));
+}
+/** Render a single page into the index template with serialized state. */
+async function generatePage(options) {
+	walkTree(options.state.content, (block) => {
+		const meta = options.blocksMap.get(block.blockId);
+		if (meta) passDefaultValue(block.data, meta.props);
+	});
+	const merged = {
+		...options.projectData,
+		...options.state.data
+	};
+	const data = Object.fromEntries(options.dataEntries.map((entry) => [entry.id, passDefaultValue(merged[entry.id] ?? {}, entry.props)]));
+	const state = {
+		content: options.state.content,
+		data,
+		baseUrl: options.baseUrl,
+		page: {
+			path: options.path,
+			...options.state.page
+		}
+	};
+	const result = await options.render(state, options.path ?? "");
+	const rendered = typeof result === "string" ? result : result.html;
+	const query = (typeof result === "string" ? void 0 : result.query) ?? {};
+	if (Object.keys(query).length) state.query = query;
+	let index = passDataToHTML(options.index, {
+		...data,
+		page: options.state.page
+	});
+	const appMatch = index.match(/(<div[^>]*\bid="app"[^>]*>)([\s\S]*?)<\/div>/);
+	if (!appMatch) throw new Error("index.html has no <div id=\"app\"> container — the rendered page has nowhere to go. Add <div id=\"app\"></div> to the template body.");
+	const start = appMatch.index + appMatch[1].length;
+	const end = appMatch.index + appMatch[0].length - 6;
+	index = index.slice(0, start) + rendered + index.slice(end);
+	const links = options.pageLinks?.(options.state.content) ?? [];
+	if (links.length) index = index.replace("</head>", `${links.join("\n")}\n</head>`);
+	if (options.assetsUrl) index = index.replace(/\/assets\//g, options.assetsUrl);
+	const stateScript = `<script>window.state=${serializeState(state)}<\/script>`;
+	return {
+		html: index.replace("</body>", `${stateScript}\n</body>`),
+		query
+	};
+}
+var UNSAFE_IN_SCRIPT = new RegExp(`[${[
+	60,
+	8232,
+	8233
+].map((c) => "\\u" + c.toString(16).padStart(4, "0")).join("")}]`, "g");
+/**
+* Serialize runtime state for embedding in an inline `<script>`. Plain JSON is
+* unsafe (a `<\/script>` in the data would close the tag early), so the few
+* dangerous characters are escaped to their `\uXXXX` form — valid JSON/JS that
+* `window.state` and the router's regex read back unchanged.
+*/
+function serializeState(state) {
+	return JSON.stringify(state).replace(UNSAFE_IN_SCRIPT, (ch) => "\\u" + ch.charCodeAt(0).toString(16).padStart(4, "0"));
+}
+/** Render every page of a project, yielding the html, path and resolved queries. */
+async function* generateProject(options) {
+	for (const page of options.pages) {
+		page.content = page.content ?? [];
+		if (options.onFile) collectFiles(page.content, options.blocksMap, options.onFile);
+		const { html, query } = await generatePage({
+			...options,
+			state: page,
+			path: page.path
+		});
+		yield {
+			html,
+			path: page.path,
+			query
+		};
+	}
+}
+/** Rewrite asset references (image/file/richText) through `onFile`. */
+function collectFiles(content, blocksMap, onFile) {
+	walkTree(content, (block) => {
+		const meta = blocksMap.get(block.blockId);
+		if (!meta) return;
+		walkSchema(block.data, meta.props, (value, schema) => {
+			if (!value) return;
+			if (schema.format === "image" || schema.format === "file") {
+				if (value.src) value.src = onFile(value.src);
+				if (value.previewSrc) value.previewSrc = onFile(value.previewSrc);
+			}
+			if (schema.format === "richText" && schema.type === "array") for (const row of value) {
+				if (row.image?.src) row.image.src = onFile(row.image.src);
+				if (row.image?.previewSrc) row.image.previewSrc = onFile(row.image.previewSrc);
+			}
+		});
+	});
+}
+//#endregion
+//#region src/validate-links.ts
+/** Normalize an internal URL for page-path comparison (drop query/hash/trailing slash). */
+function normalizeInternalUrl(url) {
+	const trimmed = url.split(/[?#]/)[0].replace(/\/+$/, "");
+	return trimmed === "" ? "/" : trimmed;
+}
+/**
+* Collect the internal link targets on a page: every `smartLink`-formatted
+* field whose URL is site-relative (starts with `/`) and not marked external.
+*/
+function collectInternalLinks(content, blocksMap) {
+	const found = [];
+	walkTree(content, (block) => {
+		const meta = blocksMap.get(block.blockId);
+		if (!meta) return;
+		walkSchema(block.data, meta.props, (value, schema) => {
+			if (schema?.format !== "smartLink" || value == null) return;
+			const url = typeof value === "string" ? value : value.url;
+			const external = typeof value === "object" && value.external === true;
+			if (typeof url === "string" && url.startsWith("/") && !external) found.push(url);
+		});
+	});
+	return found;
+}
+/**
+* Cross-check every page's internal `smartLink` targets against the set of
+* page paths that actually exist. Returns the dead links (empty = all good).
+* Meant for export/deploy time — a warning, not a hard failure, since a target
+* may be intentionally served by something else (redirects, external hosting).
+*/
+function validateLinks(pages, blocksMap) {
+	const known = new Set(pages.map((page) => normalizeInternalUrl(page.path)));
+	const issues = [];
+	for (const page of pages) for (const url of collectInternalLinks(page.content ?? [], blocksMap)) if (!known.has(normalizeInternalUrl(url))) issues.push({
+		page: page.path,
+		url
+	});
+	return issues;
+}
+//#endregion
+//#region src/migrate.ts
+/**
+* Upgrade placed blocks whose data was written with an older schema version.
+*
+* Each placed block records the schema version it was saved with (`v`, absent
+* = 1). When a block type declares a newer `version`, its `migrate` hook runs
+* with the stored data and the version it came from, then the block is
+* stamped with the current version. Runs on load (dev state, export) so pages
+* never render stale-shaped data; the upgrade persists with the next save.
+*
+* Returns whether anything changed.
+*/
+function migrateContent(content, blocksMap) {
+	let changed = false;
+	walkTree(content, (block) => {
+		const meta = blocksMap.get(block.blockId);
+		const version = meta?.version;
+		if (!version) return;
+		const from = block.v ?? 1;
+		if (from >= version) return;
+		if (meta.migrate) {
+			const result = meta.migrate(block.data ?? {}, from);
+			if (result) block.data = result;
+		}
+		block.v = version;
+		changed = true;
+	});
+	return changed;
+}
+/**
+* Block ids referenced by the content tree that the block registry doesn't
+* know (deleted or renamed block types). These render as nothing — callers
+* should surface them (export warning, editor badge).
+*/
+function findUnknownBlocks(content, blocksMap) {
+	const unknown = /* @__PURE__ */ new Set();
+	walkTree(content, (block) => {
+		if (!blocksMap.has(block.blockId)) unknown.add(block.blockId);
+	});
+	return [...unknown];
+}
+//#endregion
+//#region src/query-engine.ts
+/** Split a query key (`"<type>.<json-args>"`) into its type and parsed args. */
+function parseQueryKey(key) {
+	const dot = key.indexOf(".");
+	if (dot === -1) return {
+		type: key,
+		args: {}
+	};
+	const type = key.slice(0, dot);
+	const raw = key.slice(dot + 1);
+	try {
+		const parsed = JSON.parse(raw || "{}");
+		return {
+			type,
+			args: parsed && typeof parsed === "object" ? parsed : {}
+		};
+	} catch {
+		return {
+			type,
+			args: {}
+		};
+	}
+}
+/** Whether a key is a paginated `getPages` query (drives export page-splitting). */
+function isPaginatedQuery(key) {
+	const { type, args } = parseQueryKey(key);
+	return type === "getPages" && typeof args.pageSize === "number" && args.pageSize > 0;
+}
+/** Compare possibly-missing values: numbers numerically, everything else as strings. */
+function compareValues(a, b) {
+	if (a == null && b == null) return 0;
+	if (a == null) return 1;
+	if (b == null) return -1;
+	if (typeof a === "number" && typeof b === "number") return a - b;
+	return String(a).localeCompare(String(b));
+}
+/**
+* Resolve a `getPages` query: filter by folder, sort, and either cap (`limit`)
+* or paginate (`pageSize`). Internal ordering fields are stripped from results.
+*/
+function resolvePagesQuery(source, args, context = {}) {
+	let pages = source.listPages({ data: args.data });
+	if (args.folderName) {
+		const indexPath = "/" + args.folderName.replace(/^\/+|\/+$/g, "");
+		pages = pages.filter((page) => page.folderPath === args.folderName && page.path !== indexPath);
+	}
+	if (args.sort?.by) {
+		const { by, dir } = args.sort;
+		const sign = dir === "desc" ? -1 : 1;
+		pages = pages.map((page) => ({
+			page,
+			field: getValueByPath(page, by)
+		})).sort((a, b) => {
+			if (a.field == null || b.field == null) return compareValues(a.field, b.field);
+			return compareValues(a.field, b.field) * sign;
+		}).map((entry) => entry.page);
+	}
+	const items = pages.map(({ order, orderAfter, folderPath, ...rest }) => rest);
+	if (args.pageSize && args.pageSize > 0) {
+		const total = items.length;
+		const pageCount = Math.max(1, Math.ceil(total / args.pageSize));
+		const page = Math.min(Math.max(1, context.page ?? 1), pageCount);
+		return {
+			items: items.slice((page - 1) * args.pageSize, page * args.pageSize),
+			page,
+			pageCount,
+			pageSize: args.pageSize,
+			total
+		};
+	}
+	return typeof args.limit === "number" && args.limit >= 0 ? items.slice(0, args.limit) : items;
+}
+/**
+* Resolve any query key against a source. Unknown types resolve to `{}` (the
+* runtime containers keep their initial shape). `fetch` keys require the
+* source to provide `fetchJson`.
+*/
+async function resolveQueryKey(source, key, context = {}) {
+	const { type, args } = parseQueryKey(key);
+	if (type === "getPages") return resolvePagesQuery(source, args, context);
+	if (type === "fetch") {
+		if (!source.fetchJson) return {};
+		if (typeof args.url !== "string" || !args.url) return {};
+		return source.fetchJson(args);
+	}
+	return {};
+}
+//#endregion
+export { areFieldSchemasRegistered, buildPreviewData, builtinFields, collectInternalLinks, findUnknownBlocks, generatePage, generateProject, getDefaultValue, getFieldDefault, getValueByPath, isPaginatedQuery, mergePreviewData, migrateContent, normalizeInternalUrl, parseQueryKey, passDataToHTML, passDefaultValue, registerFieldSchemas, resolvePagesQuery, resolveQueryKey, serializeState, validateLinks, walkSchema, walkTree };