mechanica-shared 2.0.0-alpha.0 → 2.0.0-alpha.3

package/dist/block-format.js

@@ -0,0 +1,86 @@
+import { parse, stringify } from "yaml";
+//#region src/block-format.ts
+/**
+* Codec for the composed-block file format (`.mech/blocks/<id>.block.yml`) — a
+* single YAML document holding a {@link ComposedBlockDefinition}. Kept a
+* separate entry point (`mechanica-shared/block-format`), deliberately NOT
+* re-exported from the barrel: it pulls in the YAML parser, and the barrel is
+* imported by the client runtime, which never parses these files (only the dev
+* store, the plugin's collect step, and the CLI do). Mirrors the `page-format`
+* rule. See PLAN.md § 3.
+*/
+/** Thrown by {@link parseComposedBlock} with a human-readable reason. */
+var ComposedBlockParseError = class ComposedBlockParseError extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ComposedBlockParseError";
+		Object.setPrototypeOf(this, ComposedBlockParseError.prototype);
+	}
+};
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Validate the minimal shape of a content node (recurses into children). */
+function assertContentBlock(node, where) {
+	if (!isPlainObject(node)) throw new ComposedBlockParseError(`${where}: expected a mapping`);
+	if (typeof node.blockId !== "string" || node.blockId === "") throw new ComposedBlockParseError(`${where}: missing "blockId"`);
+	if (node.data !== void 0 && !isPlainObject(node.data)) throw new ComposedBlockParseError(`${where}: "data" must be a mapping`);
+	const children = node.children;
+	if (children === void 0) return;
+	if (Array.isArray(children)) children.forEach((child, i) => assertContentBlock(child, `${where} › child ${i}`));
+	else if (isPlainObject(children)) for (const [slot, list] of Object.entries(children)) {
+		if (!Array.isArray(list)) throw new ComposedBlockParseError(`${where}: slot "${slot}" must be a list`);
+		list.forEach((child, i) => assertContentBlock(child, `${where} › ${slot}[${i}]`));
+	}
+	else throw new ComposedBlockParseError(`${where}: "children" must be a list or a slot mapping`);
+}
+/**
+* Parse a `.block.yml` document into a {@link ComposedBlockDefinition}.
+*
+* @param fallbackId Used as the id when the document omits one — the store and
+*                   plugin pass the filename base, so a hand-authored file may
+*                   omit `id` and be identified by its filename.
+*/
+function parseComposedBlock(text, fallbackId) {
+	let doc;
+	try {
+		doc = parse(text);
+	} catch (error) {
+		throw new ComposedBlockParseError(`invalid YAML: ${error instanceof Error ? error.message : error}`);
+	}
+	if (doc == null) doc = {};
+	if (!isPlainObject(doc)) throw new ComposedBlockParseError("expected a top-level mapping");
+	const id = typeof doc.id === "string" && doc.id !== "" ? doc.id : fallbackId;
+	if (!id) throw new ComposedBlockParseError("missing \"id\"");
+	if (typeof doc.name !== "string" || doc.name === "") throw new ComposedBlockParseError("missing \"name\"");
+	const template = doc.template ?? [];
+	if (!Array.isArray(template)) throw new ComposedBlockParseError("\"template\" must be a list");
+	template.forEach((node, i) => assertContentBlock(node, `template[${i}]`));
+	if (doc.props !== void 0 && !isPlainObject(doc.props)) throw new ComposedBlockParseError("\"props\" must be a mapping");
+	if (doc.previewData !== void 0 && !isPlainObject(doc.previewData)) throw new ComposedBlockParseError("\"previewData\" must be a mapping");
+	const def = {
+		id,
+		name: doc.name,
+		template
+	};
+	if (typeof doc.icon === "string") def.icon = doc.icon;
+	if (typeof doc.category === "string") def.category = doc.category;
+	if (isPlainObject(doc.props)) def.props = doc.props;
+	if (isPlainObject(doc.previewData)) def.previewData = doc.previewData;
+	return def;
+}
+/** Serialize a {@link ComposedBlockDefinition} to a `.block.yml` document. */
+function serializeComposedBlock(def) {
+	const ordered = {
+		id: def.id,
+		name: def.name
+	};
+	if (def.icon) ordered.icon = def.icon;
+	if (def.category) ordered.category = def.category;
+	if (def.props && Object.keys(def.props).length) ordered.props = def.props;
+	if (def.previewData && Object.keys(def.previewData).length) ordered.previewData = def.previewData;
+	ordered.template = def.template ?? [];
+	return stringify(ordered, { lineWidth: 0 });
+}
+//#endregion
+export { ComposedBlockParseError, parseComposedBlock, serializeComposedBlock };