@homepages/template-kit 0.0.1 → 0.1.0

package/dist/eslint/rules/no-hex.js

@@ -0,0 +1,111 @@
+//#region src/eslint/rules/no-hex.ts
+const COLOR_FN = /(?:oklch|oklab|rgba?|hsla?|color-mix)\s*\([^)]*\)/;
+const HEX = /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{4}|[0-9a-fA-F]{3})\b/g;
+const COLOR_UTILITY_PREFIXES = [
+	"bg",
+	"text",
+	"border",
+	"ring",
+	"outline",
+	"shadow",
+	"fill",
+	"stroke",
+	"decoration",
+	"divide",
+	"accent",
+	"caret",
+	"placeholder",
+	"from",
+	"via",
+	"to"
+];
+const COLOR_PROPERTY_NAMES = [
+	"color",
+	"background",
+	"background-color",
+	"border-color",
+	"outline-color",
+	"box-shadow",
+	"text-shadow",
+	"fill",
+	"stroke",
+	"caret-color",
+	"accent-color",
+	"text-decoration-color"
+];
+function colorBracketRanges(text) {
+	const ranges = [];
+	const re = /\[[^[\]]*\]/g;
+	let m;
+	while (m = re.exec(text)) {
+		const start = m.index;
+		const end = m.index + m[0].length;
+		const inner = m[0].slice(1, -1);
+		if (COLOR_PROPERTY_NAMES.some((prop) => inner.startsWith(`${prop}:`))) {
+			ranges.push([start, end]);
+			continue;
+		}
+		if (inner.startsWith("--") && inner.includes(":")) {
+			ranges.push([start, end]);
+			continue;
+		}
+		const before = text.slice(0, start).match(/\S+$/)?.[0] ?? "";
+		const lastColon = before.lastIndexOf(":");
+		const utility = lastColon === -1 ? before : before.slice(lastColon + 1);
+		if (COLOR_UTILITY_PREFIXES.some((prefix) => utility === prefix || utility.startsWith(`${prefix}-`))) ranges.push([start, end]);
+	}
+	return ranges;
+}
+function isWithinStyleAttribute(node) {
+	let cur = node;
+	while (cur) {
+		if (cur.type === "JSXAttribute" && cur.name?.type === "JSXIdentifier" && cur.name.name === "style") return true;
+		cur = cur.parent;
+	}
+	return false;
+}
+const noHex = {
+	meta: {
+		type: "problem",
+		docs: { description: "Ban hard-coded colour literals in section code" },
+		schema: [],
+		messages: { hardCodedColor: "`{{value}}` is a hard-coded colour — a section carries no palette of its own, or it breaks the first time another template reuses it. Fix: use a semantic token utility (e.g. `bg-surface-alt`, `text-ink`); if the value is genuinely brand decoration with no token, add it to the template's `theme.ts` palette and use the `--tr-color-<name>` utility it compiles to." }
+	},
+	create(context) {
+		function check(node, text) {
+			const fn = COLOR_FN.exec(text);
+			if (fn) {
+				context.report({
+					node,
+					messageId: "hardCodedColor",
+					data: { value: fn[0] }
+				});
+				return;
+			}
+			const hexMatches = [...text.matchAll(HEX)];
+			if (hexMatches.length === 0) return;
+			const inStyle = isWithinStyleAttribute(node);
+			const colorRanges = colorBracketRanges(text);
+			for (const hex of hexMatches) {
+				if (!colorRanges.some(([start, end]) => hex.index >= start && hex.index < end) && !inStyle) continue;
+				context.report({
+					node,
+					messageId: "hardCodedColor",
+					data: { value: hex[0] }
+				});
+				return;
+			}
+		}
+		return {
+			Literal(node) {
+				if (typeof node.value === "string") check(node, node.value);
+			},
+			TemplateElement(node) {
+				check(node, node.value.raw);
+			}
+		};
+	}
+};
+
+//#endregion
+export { noHex };

package/dist/eslint/rules/no-inline-style.js

@@ -0,0 +1,23 @@
+import { hasClientDirective } from "../is-client-file.js";
+
+//#region src/eslint/rules/no-inline-style.ts
+const noInlineStyle = {
+	meta: {
+		type: "problem",
+		docs: { description: "Ban the inline style prop in server-rendered section JSX" },
+		schema: [],
+		messages: { inlineStyle: "The inline `style=` prop is banned in server-rendered section JSX — it bypasses the cascade and Tailwind's responsive prefixes. Fix: use Tailwind utility classes; for a value that only exists at runtime, move the markup into a `\"use client\"` island, where `style` is allowed." }
+	},
+	create(context) {
+		if (hasClientDirective(context.sourceCode.getText())) return {};
+		return { JSXAttribute(node) {
+			if (node.name.type === "JSXIdentifier" && node.name.name === "style") context.report({
+				node,
+				messageId: "inlineStyle"
+			});
+		} };
+	}
+};
+
+//#endregion
+export { noInlineStyle };

package/dist/eslint/rules/no-nondeterminism.js

@@ -0,0 +1,44 @@
+import { hasClientDirective } from "../is-client-file.js";
+
+//#region src/eslint/rules/no-nondeterminism.ts
+const BANNED_MEMBERS = {
+	Date: /* @__PURE__ */ new Set(["now"]),
+	Math: /* @__PURE__ */ new Set(["random"]),
+	crypto: /* @__PURE__ */ new Set(["randomUUID", "getRandomValues"]),
+	performance: /* @__PURE__ */ new Set(["now"])
+};
+const noNondeterminism = {
+	meta: {
+		type: "problem",
+		docs: { description: "Ban clock and randomness reads in server-rendered section code" },
+		schema: [],
+		messages: { nondeterministic: "`{{what}}` is nondeterministic and is banned in server-rendered code — the publisher and the editor must render byte-identical HTML. Fix: compute this at fill time and pass it in as a slot value, or move the code into a `\"use client\"` island, where it runs in the browser." }
+	},
+	create(context) {
+		if (hasClientDirective(context.sourceCode.getText())) return {};
+		const sourceCode = context.sourceCode;
+		return {
+			MemberExpression(node) {
+				if (node.computed || node.object.type !== "Identifier" || node.property.type !== "Identifier") return;
+				if (!BANNED_MEMBERS[node.object.name]?.has(node.property.name)) return;
+				const ref = sourceCode.getScope(node).references.find((r) => r.identifier === node.object);
+				if (ref?.resolved && ref.resolved.defs.length > 0) return;
+				context.report({
+					node,
+					messageId: "nondeterministic",
+					data: { what: `${node.object.name}.${node.property.name}()` }
+				});
+			},
+			NewExpression(node) {
+				if (node.callee.type === "Identifier" && node.callee.name === "Date" && node.arguments.length === 0) context.report({
+					node,
+					messageId: "nondeterministic",
+					data: { what: "new Date()" }
+				});
+			}
+		};
+	}
+};
+
+//#endregion
+export { noNondeterminism };

package/dist/eslint/rules/no-raw-element.js

@@ -0,0 +1,32 @@
+//#region src/eslint/rules/no-raw-element.ts
+const FORBIDDEN = {
+	section: "<Section>",
+	img: "<Image>"
+};
+const noRawElement = {
+	meta: {
+		type: "problem",
+		docs: { description: "Ban raw <section> and <img> in section JSX" },
+		schema: [],
+		messages: { rawElement: "Raw `<{{tag}}>` is banned in section JSX — {{use}} carries the contract it skips. Fix: `import { {{name}} } from \"@homepages/template-kit\";` and use {{use}}." }
+	},
+	create(context) {
+		return { JSXOpeningElement(node) {
+			if (node.name.type !== "JSXIdentifier" || !node.name.name) return;
+			const use = FORBIDDEN[node.name.name];
+			if (!use) return;
+			context.report({
+				node,
+				messageId: "rawElement",
+				data: {
+					tag: node.name.name,
+					use,
+					name: use.slice(1, -1)
+				}
+			});
+		} };
+	}
+};
+
+//#endregion
+export { noRawElement };

package/dist/eslint/rules/props-from-schema.js

@@ -0,0 +1,32 @@
+//#region src/eslint/rules/props-from-schema.ts
+const propsFromSchema = {
+	meta: {
+		type: "problem",
+		docs: { description: "A Renderer must import its Props type from ./schema" },
+		schema: [],
+		messages: { handWritten: "`{{name}}` is a hand-written props type in a Renderer — it bypasses the schema→Props inference and will drift. Fix: add `export type Props = SectionProps<typeof schema>;` to schema.ts and `import type { Props } from \"./schema.js\";` here." }
+	},
+	create(context) {
+		return {
+			"ExportNamedDeclaration > TSTypeAliasDeclaration"(node) {
+				if (!node.id.name.endsWith("Props")) return;
+				context.report({
+					node,
+					messageId: "handWritten",
+					data: { name: node.id.name }
+				});
+			},
+			"ExportNamedDeclaration > TSInterfaceDeclaration"(node) {
+				if (!node.id.name.endsWith("Props")) return;
+				context.report({
+					node,
+					messageId: "handWritten",
+					data: { name: node.id.name }
+				});
+			}
+		};
+	}
+};
+
+//#endregion
+export { propsFromSchema };

package/dist/eslint/rules/serializable-island-props.js

@@ -0,0 +1,108 @@
+import { isClientFile, resolveImportedFile } from "../is-client-file.js";
+
+//#region src/eslint/rules/serializable-island-props.ts
+function inspect(node, path, out) {
+	switch (node.type) {
+		case "ArrowFunctionExpression":
+		case "FunctionExpression":
+			out.push({
+				node,
+				what: "a function",
+				path,
+				messageId: "notSerializableBadType"
+			});
+			return;
+		case "NewExpression":
+			if (node.callee?.type === "Identifier" && node.callee.name && node.callee.name !== "Object" && node.callee.name !== "Array") out.push({
+				node,
+				what: `a ${node.callee.name}`,
+				path,
+				messageId: "notSerializableClassInstance"
+			});
+			return;
+		case "ObjectExpression":
+			for (const prop of node.properties ?? []) {
+				if (prop.type !== "Property" || prop.computed) continue;
+				if (prop.kind !== "init") continue;
+				const key = prop.key.type === "Identifier" ? prop.key.name : prop.key.type === "Literal" ? String(prop.key.value) : null;
+				if (key === null) continue;
+				inspect(prop.value, `${path}.${key}`, out);
+			}
+			return;
+		case "ArrayExpression":
+			(node.elements ?? []).forEach((el, i) => {
+				if (el && el.type !== "SpreadElement") inspect(el, `${path}[${i}]`, out);
+			});
+			return;
+		case "Literal":
+			if (typeof node.bigint === "string") out.push({
+				node,
+				what: "a bigint",
+				path,
+				messageId: "notSerializableBadType"
+			});
+			return;
+		case "Identifier":
+			if (node.name === "NaN" || node.name === "Infinity") out.push({
+				node,
+				what: node.name,
+				path,
+				messageId: "notSerializableNanInfinity"
+			});
+			return;
+		default: return;
+	}
+}
+const serializableIslandProps = {
+	meta: {
+		type: "problem",
+		docs: { description: "Island props must be JSON-serializable" },
+		schema: [],
+		messages: {
+			notSerializableBadType: "{{path}} is {{what}} — island props must be JSON-serializable (string, number, boolean, null, plain object, array). Fix: pass data, not behavior — an island owns its own handlers.",
+			notSerializableClassInstance: "{{path}} is {{what}} — island props must be JSON-serializable (plain objects and arrays only). Fix: pass data, not behavior — a Date/Map/Set/RegExp crosses as its plain-JSON equivalent (e.g. an ISO string) that you reconstruct inside the island.",
+			notSerializableNanInfinity: "{{path}} is {{what}} — island props must be JSON-serializable, and JSON has no NaN or Infinity. Fix: pass a finite number, or encode the sentinel as a string prop the island parses."
+		}
+	},
+	create(context) {
+		const filename = context.filename;
+		const islandNames = /* @__PURE__ */ new Map();
+		function isIsland(name) {
+			return islandNames.get(name) ?? false;
+		}
+		return {
+			ImportDeclaration(node) {
+				const source = node.source.value;
+				if (typeof source !== "string") return;
+				const resolved = resolveImportedFile(source, filename);
+				if (resolved === null) return;
+				const island = isClientFile(resolved);
+				for (const spec of node.specifiers) islandNames.set(spec.local.name, island);
+			},
+			JSXOpeningElement(node) {
+				if (node.name.type !== "JSXIdentifier" || !node.name.name) return;
+				if (!isIsland(node.name.name)) return;
+				for (const attr of node.attributes) {
+					if (attr.type !== "JSXAttribute") continue;
+					const nameNode = attr.name;
+					if (nameNode.type !== "JSXIdentifier" || !nameNode.name) continue;
+					const value = attr.value;
+					if (!value || value.type !== "JSXExpressionContainer" || !value.expression) continue;
+					const bad = [];
+					inspect(value.expression, `props.${nameNode.name}`, bad);
+					for (const b of bad) context.report({
+						node: b.node,
+						messageId: b.messageId,
+						data: {
+							path: b.path,
+							what: b.what
+						}
+					});
+				}
+			}
+		};
+	}
+};
+
+//#endregion
+export { serializableIslandProps };

package/dist/eslint/rules/slot-marker-literal.js

@@ -0,0 +1,33 @@
+//#region src/eslint/rules/slot-marker-literal.ts
+const KEY_ATTRS = /* @__PURE__ */ new Set([
+	"data-slot-id",
+	"data-slot-group",
+	"slotId"
+]);
+const KEY_COMPONENTS = /* @__PURE__ */ new Set(["Slot", "SlotGroup"]);
+const slotMarkerLiteral = {
+	meta: {
+		type: "problem",
+		docs: { description: "Slot markers must carry a string-literal key" },
+		schema: [],
+		messages: { markerNotLiteral: "`{{attr}}` must be a string literal, not an expression — the slot-marker completeness check reads this key statically, and cannot resolve a computed one (the slot would silently lose editor selection). Fix: write the key inline, e.g. `{{attr}}=\"headline\"`." }
+	},
+	create(context) {
+		return { JSXAttribute(node) {
+			if (node.name.type !== "JSXIdentifier" || !node.name.name) return;
+			const attr = node.name.name;
+			const isKeyAttr = KEY_ATTRS.has(attr);
+			const isComponentId = attr === "id" && node.parent?.name?.type === "JSXIdentifier" && KEY_COMPONENTS.has(node.parent.name.name ?? "");
+			if (!isKeyAttr && !isComponentId) return;
+			if (node.value?.type === "Literal") return;
+			context.report({
+				node,
+				messageId: "markerNotLiteral",
+				data: { attr }
+			});
+		} };
+	}
+};
+
+//#endregion
+export { slotMarkerLiteral };

package/dist/eslint.d.ts

@@ -1,10 +1,6 @@
-import { Linter } from "eslint";
-//#region src/eslint.d.ts
-/**
- * The HomePages template-authoring ESLint preset.
- * Rules arrive with the surface they govern (schema, primitives, determinism bans).
- * Shipped now, empty, so a workspace's flat config can reference it from 0.0.x.
- */
+import { ESLint, Linter } from "eslint";
+//#region src/eslint/index.d.ts
+declare const plugin: ESLint.Plugin;
 declare const templateKitConfig: Linter.Config[];
 //#endregion
-export { templateKitConfig as default, templateKitConfig };
+export { templateKitConfig as default, templateKitConfig, plugin };

package/dist/eslint.js

@@ -1,13 +1,77 @@
-//#region src/eslint.ts
-/**
-* The HomePages template-authoring ESLint preset.
-* Rules arrive with the surface they govern (schema, primitives, determinism bans).
-* Shipped now, empty, so a workspace's flat config can reference it from 0.0.x.
-*/
-const templateKitConfig = [{
-	name: "@homepages/template-kit/base",
-	rules: {}
-}];
+import { imageBareNeedsReason } from "./eslint/rules/image-bare-needs-reason.js";
+import { noClientDirectiveInContract } from "./eslint/rules/no-client-directive-in-contract.js";
+import { noClientRuntimeInServer } from "./eslint/rules/no-client-runtime-in-server.js";
+import { noCssImportFromRenderPath } from "./eslint/rules/no-css-import-from-render-path.js";
+import { noHex } from "./eslint/rules/no-hex.js";
+import { noInlineStyle } from "./eslint/rules/no-inline-style.js";
+import { noNondeterminism } from "./eslint/rules/no-nondeterminism.js";
+import { noRawElement } from "./eslint/rules/no-raw-element.js";
+import { propsFromSchema } from "./eslint/rules/props-from-schema.js";
+import { serializableIslandProps } from "./eslint/rules/serializable-island-props.js";
+import { slotMarkerLiteral } from "./eslint/rules/slot-marker-literal.js";
+import tsParser from "@typescript-eslint/parser";
+
+//#region src/eslint/index.ts
+const rules = {
+	"no-client-directive-in-contract": noClientDirectiveInContract,
+	"no-nondeterminism": noNondeterminism,
+	"no-client-runtime-in-server": noClientRuntimeInServer,
+	"serializable-island-props": serializableIslandProps,
+	"props-from-schema": propsFromSchema,
+	"no-inline-style": noInlineStyle,
+	"no-raw-element": noRawElement,
+	"image-bare-needs-reason": imageBareNeedsReason,
+	"slot-marker-literal": slotMarkerLiteral,
+	"no-hex": noHex,
+	"no-css-import-from-render-path": noCssImportFromRenderPath
+};
+const plugin = {
+	meta: { name: "@homepages/template-kit" },
+	rules
+};
+const CONTRACT_FILES = [
+	"**/Renderer.tsx",
+	"**/schema.ts",
+	"**/fill-spec.ts",
+	"**/fixtures.ts"
+];
+const templateKitConfig = [
+	{
+		name: "template-kit/authoring",
+		files: ["**/*.ts", "**/*.tsx"],
+		ignores: ["**/*.config.{ts,mts,cts,tsx}"],
+		languageOptions: {
+			parser: tsParser,
+			ecmaVersion: "latest",
+			sourceType: "module",
+			parserOptions: { ecmaFeatures: { jsx: true } }
+		},
+		plugins: { "template-kit": plugin },
+		rules: {
+			"template-kit/no-nondeterminism": "error",
+			"template-kit/no-client-runtime-in-server": "error",
+			"template-kit/serializable-island-props": "error",
+			"template-kit/no-inline-style": "error",
+			"template-kit/no-raw-element": "error",
+			"template-kit/image-bare-needs-reason": "error",
+			"template-kit/slot-marker-literal": "error",
+			"template-kit/no-hex": "error",
+			"template-kit/no-css-import-from-render-path": "error"
+		}
+	},
+	{
+		name: "template-kit/contract-files",
+		files: CONTRACT_FILES,
+		plugins: { "template-kit": plugin },
+		rules: { "template-kit/no-client-directive-in-contract": "error" }
+	},
+	{
+		name: "template-kit/renderer",
+		files: ["**/Renderer.tsx"],
+		plugins: { "template-kit": plugin },
+		rules: { "template-kit/props-from-schema": "error" }
+	}
+];
 
 //#endregion
-export { templateKitConfig as default, templateKitConfig };
+export { templateKitConfig as default, templateKitConfig, plugin };

package/dist/fixtures/sample-property.d.ts

@@ -0,0 +1,67 @@
+import { ResponsiveImage } from "../contracts/image-descriptor.js";
+import { PropertyFacts } from "../schema/property-facts.js";
+//#region src/fixtures/sample-property.d.ts
+type PhotoFixture = {
+  id: string;
+  url: string;
+  alt: string;
+  tags: {
+    room?: string;
+    category?: string;
+  };
+};
+declare const allPhotos: PhotoFixture[];
+declare function mkResponsive(url: string, width: number, height: number): ResponsiveImage;
+type PoiFixture = {
+  id: string;
+  category: "restaurant" | "park" | "transit" | "shopping" | "coffee" | "fitness";
+  name: string;
+  distance: string;
+  lat: number;
+  lng: number;
+  url: string;
+};
+declare const samplePois: PoiFixture[];
+type ContactFixture = {
+  library_item_id: string;
+  category: "contact";
+  type: "agent";
+  position: number;
+  fields: {
+    display_name: string;
+    title: string;
+    bio: string;
+    headshot_url: string;
+    website_url: string;
+    email: string;
+    phone: string;
+    address: string;
+    socials: Array<{
+      platform: "instagram" | "linkedin" | "x" | "facebook";
+      url: string;
+    }>;
+  };
+};
+declare const sampleContacts: ContactFixture[];
+type AmenityItem = {
+  id: string;
+  label: string;
+  /** Catalog glyph key; narrowed by the consuming section (see amenities' safeIcon). */
+  icon: string;
+  description: string;
+  items: string[];
+};
+declare const sampleAmenities: AmenityItem[];
+declare const sampleProperty: PropertyFacts;
+declare const sampleHeroSlots: {
+  readonly headline: "A mansard victorian single-family home in the heart of Jamaica Plain";
+  readonly hero_image: {
+    readonly photo_id: string;
+    readonly url: string;
+    readonly alt: string;
+  };
+  readonly brand_logo: null;
+  readonly listing_status: "for_sale";
+};
+//#endregion
+export { AmenityItem, ContactFixture, PhotoFixture, PoiFixture, allPhotos, mkResponsive, sampleAmenities, sampleContacts, sampleHeroSlots, samplePois, sampleProperty };